ObjectQL Documentation
++ Visit /docs to view the documentation +
+
+
+ {uploading &&
+ );
+};
+```
+
+---
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| `FILE_TOO_LARGE` | File exceeds `max_size` limit |
+| `FILE_TOO_SMALL` | File is smaller than `min_size` |
+| `FILE_TYPE_NOT_ALLOWED` | File extension not in `accept` list |
+| `IMAGE_DIMENSIONS_INVALID` | Image dimensions don't meet requirements |
+| `UPLOAD_FAILED` | General upload failure |
+| `STORAGE_QUOTA_EXCEEDED` | Storage quota exceeded |
+| `FILE_NOT_FOUND` | Requested file doesn't exist |
+| `FILE_ACCESS_DENIED` | User doesn't have permission to access file |
+
+---
+
+## TypeScript Definitions
+
+```typescript
+/**
+ * Attachment field data structure
+ */
+export interface AttachmentData {
+ id?: string;
+ name: string;
+ url: string;
+ size: number;
+ type: string;
+ original_name?: string;
+ uploaded_at?: string;
+ uploaded_by?: string;
+}
+
+/**
+ * Image-specific attachment data
+ */
+export interface ImageAttachmentData extends AttachmentData {
+ width?: number;
+ height?: number;
+ thumbnail_url?: string;
+ variants?: {
+ small?: string;
+ medium?: string;
+ large?: string;
+ };
+}
+
+/**
+ * Upload response
+ */
+export interface UploadResponse {
+ data: AttachmentData;
+}
+
+/**
+ * Batch upload response
+ */
+export interface BatchUploadResponse {
+ data: AttachmentData[];
+}
+```
+
+---
+
+## Server Implementation
+
+### Setting up File Storage
+
+ObjectQL provides a flexible file storage abstraction that supports multiple backends.
+
+#### Using Local File Storage
+
+```typescript
+import { createNodeHandler, LocalFileStorage } from '@objectql/server';
+import { ObjectQL } from '@objectql/core';
+import * as http from 'http';
+
+const app = new ObjectQL({ /* ... */ });
+
+// Configure local file storage
+const fileStorage = new LocalFileStorage({
+ baseDir: './uploads', // or process.env.OBJECTQL_UPLOAD_DIR
+ baseUrl: 'http://localhost:3000/api/files' // or process.env.OBJECTQL_BASE_URL
+});
+
+// Create HTTP handler with file storage
+const handler = createNodeHandler(app, { fileStorage });
+
+const server = http.createServer(handler);
+server.listen(3000);
+```
+
+#### Using Memory Storage (For Testing)
+
+```typescript
+import { MemoryFileStorage } from '@objectql/server';
+
+const fileStorage = new MemoryFileStorage({
+ baseUrl: 'http://localhost:3000/api/files'
+});
+
+const handler = createNodeHandler(app, { fileStorage });
+```
+
+#### Custom Storage Implementation
+
+You can implement custom storage backends by implementing the `IFileStorage` interface:
+
+```typescript
+import { IFileStorage, AttachmentData, FileStorageOptions } from '@objectql/server';
+
+class S3FileStorage implements IFileStorage {
+ async save(
+ file: Buffer,
+ filename: string,
+ mimeType: string,
+ options?: FileStorageOptions
+ ): PromiseUploading...
} + {error &&{error}
} +Loading...
;
+ if (error) return Error: {error.message}
;
+
+ return (
+ -
+ {users.map(user => (
+
- + {user.name} - {user.email} + + ))} +
Loading form...
;
+ if (error) return Error: {error.message}
;
+ if (!schema) return null;
+
+ return (
+
+ );
+}
+```
+
+---
+
+## Vue.js Example
+
+### Composable for Data Fetching
+
+```typescript
+import { ref, watchEffect } from 'vue';
+import { DataApiClient } from '@objectql/sdk';
+
+const dataClient = new DataApiClient({
+ baseUrl: import.meta.env.VITE_API_URL || 'http://localhost:3000'
+});
+
+export function useObjectDataLoading...
; + if (error) returnError: {error.message}
; + + return ( +-
+ {data.userList.map(user => (
+
- {user.name} + ))} +
+ setFile(e.target.files?.[0] || null)}
+ />
+
+
+ );
+}
+```
+
+## 测试
+
+### 运行单元测试
+
+```bash
+cd packages/runtime/server
+pnpm test
+```
+
+测试覆盖：
+- ✅ 文件存储（保存、获取、删除）
+- ✅ 文件验证（大小、类型）
+- ✅ 多部分表单解析
+- ✅ 集成测试示例
+
+### 集成测试示例
+
+```bash
+pnpm test file-upload-integration.example.ts
+```
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `OBJECTQL_UPLOAD_DIR` | 文件存储目录 | `./uploads` |
+| `OBJECTQL_BASE_URL` | 文件访问基础 URL | `http://localhost:3000/api/files` |
+
+## 扩展性
+
+### 自定义存储后端
+
+```typescript
+import { IFileStorage } from '@objectql/server';
+
+class CustomStorage implements IFileStorage {
+ async save(file: Buffer, filename: string, mimeType: string) {
+ // 实现自定义存储逻辑（如上传到 S3/OSS）
+ // ...
+ return attachmentData;
+ }
+
+ async get(fileId: string): Promise
+
+
+ {files.length > 0 && (
+
+ );
+};
+```
+
+## 验证规则
+
+多选字段的验证规则：
+
+- `max_size`: 限制**每个文件**的最大大小
+- `min_size`: 限制**每个文件**的最小大小
+- `accept`: 限制允许的文件类型（对所有文件生效）
+- 数组长度：通过应用层逻辑控制（ObjectQL 默认不限制）
+
+## 总结
+
+ObjectQL 的附件字段**完全支持多选功能**：
+
+✅ **字段定义简单** - 只需设置 `multiple: true`
+✅ **两种上传方式** - 批量上传 API 或并行单文件上传
+✅ **数据格式统一** - 单选为对象，多选为数组
+✅ **灵活的更新操作** - 支持替换、追加、删除
+✅ **完整的查询支持** - 可以查询、过滤包含附件的记录
+
+**相关文档：**
+- [附件 API 完整文档](../api/attachments.md)
+- [附件关联指南](./attachment-association-guide-cn.md)
+- [文件上传示例](./file-upload-example.md)
diff --git a/apps/site/content/docs/examples/s3-integration-guide-cn.mdx b/apps/site/content/docs/examples/s3-integration-guide-cn.mdx
new file mode 100644
index 00000000..9b89db55
--- /dev/null
+++ b/apps/site/content/docs/examples/s3-integration-guide-cn.mdx
@@ -0,0 +1,611 @@
+---
+title: 如何使用 AWS S3 存储附件
+---
+
+# 如何使用 AWS S3 存储附件
+
+本指南详细说明如何将 ObjectQL 文件附件存储到 AWS S3，包括完整的实现代码和最佳实践。
+
+## 目录
+
+1. [为什么选择 S3](#为什么选择-s3)
+2. [架构设计](#架构设计)
+3. [实现方案](#实现方案)
+4. [配置说明](#配置说明)
+5. [使用示例](#使用示例)
+6. [高级功能](#高级功能)
+7. [最佳实践](#最佳实践)
+
+---
+
+## 为什么选择 S3
+
+使用 AWS S3 存储文件附件有以下优势：
+
+✅ **可扩展性** - 无限存储容量，无需管理磁盘空间
+✅ **高可用性** - 99.99% 可用性 SLA，自动多区域备份
+✅ **高性能** - 与 CloudFront CDN 集成，全球加速访问
+✅ **成本优化** - 按需付费，支持生命周期管理和存储分层
+✅ **安全性** - 支持加密、访问控制、签名 URL 等安全特性
+✅ **易于维护** - 无需管理服务器，AWS 负责基础设施
+
+---
+
+## 架构设计
+
+### 存储接口抽象
+
+ObjectQL 通过 `IFileStorage` 接口实现存储抽象：
+
+```typescript
+interface IFileStorage {
+ save(file: Buffer, filename: string, mimeType: string, options?: FileStorageOptions): Promise
+
+ )}
+
+
+
+ {error && 已选择 {files.length} 个文件：
+-
+ {files.map((file, index) => (
+
- + {file.name} ({(file.size / 1024).toFixed(2)} KB) + + ))} +
{error}
} +