📝 docs(architecture): update documentation for file management feature

- add MinIO to technology stack documentation
- document file management data model and schema changes
- update component architecture with file management service
- add API documentation for file upload endpoints
- update source tree structure with new file management modules

docs/architecture.md

@@ -91,6 +91,7 @@
 | Testing Library | 13.x | React组件测试 | 提供组件级测试能力 | 与React项目集成 |
 | hono/testing | 内置 | API端点测试 | 验证API功能和集成 | Hono官方测试工具，更好的类型安全 |
 | node-cron | latest | 定时任务调度 | Node.js定时任务调度库 | 集成到应用启动流程 |
+| MinIO | latest | 对象存储服务 | 提供可扩展的文件存储解决方案，替代传统文件系统存储 | 通过MinIO客户端SDK集成 |
 
 ## 数据模型和Schema变更
 
@@ -105,14 +106,26 @@
   - `roles`: Role[] - 用户角色多对多关系
 - **关系**: 与Role实体建立正确的多对多关系映射
 
-**优化重点**: 保持现有数据模型不变，仅优化查询性能和验证逻辑
+**文件管理模型**:
+- **现状**: 新增完整的文件管理系统，支持MinIO对象存储
+- **关键属性**:
+  - `id`: number - 主键标识符
+  - `name`: string - 文件名
+  - `path`: string - MinIO存储路径
+  - `size`: number - 文件大小（字节）
+  - `type`: string - 文件类型
+  - `uploadUserId`: number - 上传用户ID
+  - `uploadTime`: Date - 上传时间
+- **关系**: 与User实体建立多对一关系映射
+
+**优化重点**: 保持现有数据模型不变，新增文件管理功能，优化查询性能和验证逻辑
 
 ### Schema集成策略
-- **数据库变更要求**: 无新表创建，仅优化现有表结构
-- **新表**: 无
+- **数据库变更要求**: 新增文件管理表，优化现有表结构
+- **新表**: file表（文件管理）
 - **修改的表**: 无结构性变更
-- **新索引**: 考虑为常用查询字段添加索引
-- **迁移策略**: 无破坏性变更，使用TypeORM迁移工具
+- **新索引**: 为文件查询字段添加索引（name, uploadUserId, uploadTime）
+- **迁移策略**: 使用TypeORM迁移工具，确保数据完整性
 
 ### 向后兼容性
 - 保持所有现有API端点不变
@@ -128,6 +141,11 @@
 - **现状**: 已实现完整功能，支持关联查询和复杂操作
 - **优化重点**: 增强错误处理、添加测试覆盖、优化性能
 
+**文件管理服务**:
+- **责任**: 提供MinIO对象存储集成，支持文件上传、下载、删除等操作
+- **现状**: 已实现完整功能，支持分段上传、预签名URL生成
+- **优化重点**: 增强大文件处理能力，优化上传性能
+
 **API文档组件**:
 - **责任**: 自动生成和维护OpenAPI文档
 - **现状**: 通过@hono/zod-openapi集成，提供Swagger UI
@@ -142,11 +160,16 @@ graph TD
     C --> E[Zod验证]
     B --> F[OpenAPI文档生成]
     F --> G[Swagger UI]
+    B --> H[文件管理服务]
+    H --> I[MinIO对象存储]
+    H --> J[文件实体管理]
 
     style A fill:#e1f5fe
     style B fill:#f3e5f5
     style C fill:#fff3e0
     style D fill:#e8f5e8
+    style H fill:#fff0f5
+    style I fill:#f0fff0
 ```
 
 ## API设计和集成
@@ -163,6 +186,12 @@ graph TD
 - **用途**: 获取用户分页列表
 - **集成**: 使用通用CRUD服务，支持搜索和过滤
 
+**文件管理端点**:
+- **方法**: POST
+- **端点**: `/api/v1/files/upload-policy`
+- **用途**: 生成文件上传策略和预签名URL
+- **集成**: 使用MinIO服务，支持分段上传和大文件处理
+
 **请求示例**:
 ```json
 {
@@ -221,6 +250,8 @@ d8d-starter/
 d8d-starter/
 ├── src/
 │   ├── client/           # 现有结构保持不变
+│   │   └── utils/
+│   │       └── minio.ts                # 新增：MinIO前端上传工具
 │   ├── server/
 │   │   ├── api/
 │   │   │   ├── users/
@@ -228,12 +259,27 @@ d8d-starter/
 │   │   │   │   ├── [id]/
 │   │   │   │   ├── get.ts
 │   │   │   │   └── index.ts
+│   │   │   ├── files/                  # 新增：文件管理API
+│   │   │   │   ├── upload-policy/
+│   │   │   │   │   └── post.ts         # 文件上传策略生成
+│   │   │   │   ├── multipart-policy/
+│   │   │   │   │   └── post.ts         # 分段上传策略生成
+│   │   │   │   ├── multipart-complete/
+│   │   │   │   │   └── post.ts         # 分段上传完成
+│   │   │   │   ├── [id]/
+│   │   │   │   │   ├── download.ts     # 文件下载
+│   │   │   │   │   └── get-url.ts      # 获取文件URL
 │   │   ├── modules/
 │   │   │   ├── users/
 │   │   │   │   ├── __tests__/          # 新增：服务测试
 │   │   │   │   ├── user.entity.ts
 │   │   │   │   ├── user.service.ts
 │   │   │   │   └── role.entity.ts
+│   │   │   ├── files/                  # 新增：文件管理模块
+│   │   │   │   ├── file.entity.ts      # 文件实体
+│   │   │   │   ├── file.service.ts     # 文件服务
+│   │   │   │   ├── minio.service.ts    # MinIO服务
+│   │   │   │   └── file.schema.ts      # 文件Schema定义
 │   │   └── utils/
 │   │       ├── __tests__/              # 新增：工具测试
 │   │       ├── generic-crud.service.ts

docs/architecture/api-design-integration.md

@@ -40,3 +40,44 @@
   }
 }
 ```
+
+**文件管理端点**:
+- **方法**: POST
+- **端点**: `/api/v1/files/upload-policy`
+- **用途**: 生成文件上传策略和预签名URL
+- **集成**: 使用MinIO服务，支持分段上传和大文件处理
+
+**请求示例**:
+```json
+{
+  "name": "example.pdf",
+  "type": "application/pdf",
+  "size": 1048576,
+  "description": "示例文件"
+}
+```
+
+**响应示例**:
+```json
+{
+  "file": {
+    "id": 123,
+    "name": "example.pdf",
+    "path": "user-1/uuid-example.pdf",
+    "size": 1048576,
+    "type": "application/pdf",
+    "uploadUserId": 1,
+    "uploadTime": "2025-09-19T10:30:00.000Z"
+  },
+  "uploadPolicy": {
+    "x-amz-algorithm": "AWS4-HMAC-SHA256",
+    "x-amz-credential": "minioadmin/20250919/us-east-1/s3/aws4_request",
+    "x-amz-date": "20250919T103000Z",
+    "policy": "base64-encoded-policy",
+    "x-amz-signature": "signature",
+    "host": "https://minio.example.com",
+    "key": "user-1/uuid-example.pdf",
+    "bucket": "d8dai"
+  }
+}
+```

docs/architecture/component-architecture.md

@@ -11,6 +11,11 @@
 - **现状**: 通过@hono/zod-openapi集成，提供Swagger UI
 - **优化重点**: 完善文档示例、确保文档与代码同步
 
+**文件管理服务**:
+- **责任**: 提供MinIO对象存储集成，支持文件上传、下载、删除等操作
+- **现状**: 已实现完整功能，支持分段上传、预签名URL生成
+- **优化重点**: 增强大文件处理能力，优化上传性能
+
 ## 组件交互
 ```mermaid
 graph TD
@@ -20,9 +25,14 @@ graph TD
     C --> E[Zod验证]
     B --> F[OpenAPI文档生成]
     F --> G[Swagger UI]
+    B --> H[文件管理服务]
+    H --> I[MinIO对象存储]
+    H --> J[文件实体管理]
 
     style A fill:#e1f5fe
     style B fill:#f3e5f5
     style C fill:#fff3e0
     style D fill:#e8f5e8
+    style H fill:#fff0f5
+    style I fill:#f0fff0
 ```

docs/architecture/data-model-schema-changes.md

@@ -11,14 +11,26 @@
   - `roles`: Role[] - 用户角色多对多关系
 - **关系**: 与Role实体建立正确的多对多关系映射
 
-**优化重点**: 保持现有数据模型不变，仅优化查询性能和验证逻辑
+**文件管理模型**:
+- **现状**: 新增完整的文件管理系统，支持MinIO对象存储
+- **关键属性**:
+  - `id`: number - 主键标识符
+  - `name`: string - 文件名
+  - `path`: string - MinIO存储路径
+  - `size`: number - 文件大小（字节）
+  - `type`: string - 文件类型
+  - `uploadUserId`: number - 上传用户ID
+  - `uploadTime`: Date - 上传时间
+- **关系**: 与User实体建立多对一关系映射
+
+**优化重点**: 保持现有数据模型不变，新增文件管理功能，优化查询性能和验证逻辑
 
 ## Schema集成策略
-- **数据库变更要求**: 无新表创建，仅优化现有表结构
-- **新表**: 无
+- **数据库变更要求**: 新增文件管理表，优化现有表结构
+- **新表**: file表（文件管理）
 - **修改的表**: 无结构性变更
-- **新索引**: 考虑为常用查询字段添加索引
-- **迁移策略**: 无破坏性变更，使用TypeORM迁移工具
+- **新索引**: 为文件查询字段添加索引（name, uploadUserId, uploadTime）
+- **迁移策略**: 使用TypeORM迁移工具，确保数据完整性
 
 ## 向后兼容性
 - 保持所有现有API端点不变

docs/architecture/source-tree.md

@@ -27,6 +27,8 @@ d8d-starter/
 d8d-starter/
 ├── src/
 │   ├── client/           # 现有结构保持不变
+│   │   └── utils/
+│   │       └── minio.ts                # 新增：MinIO前端上传工具
 │   ├── server/
 │   │   ├── api/
 │   │   │   ├── users/
@@ -34,12 +36,27 @@ d8d-starter/
 │   │   │   │   ├── [id]/
 │   │   │   │   ├── get.ts
 │   │   │   │   └── index.ts
+│   │   │   ├── files/                  # 新增：文件管理API
+│   │   │   │   ├── upload-policy/
+│   │   │   │   │   └── post.ts         # 文件上传策略生成
+│   │   │   │   ├── multipart-policy/
+│   │   │   │   │   └── post.ts         # 分段上传策略生成
+│   │   │   │   ├── multipart-complete/
+│   │   │   │   │   └── post.ts         # 分段上传完成
+│   │   │   │   ├── [id]/
+│   │   │   │   │   ├── download.ts     # 文件下载
+│   │   │   │   │   └── get-url.ts      # 获取文件URL
 │   │   ├── modules/
 │   │   │   ├── users/
 │   │   │   │   ├── __tests__/          # 新增：服务测试
 │   │   │   │   ├── user.entity.ts
 │   │   │   │   ├── user.service.ts
 │   │   │   │   └── role.entity.ts
+│   │   │   ├── files/                  # 新增：文件管理模块
+│   │   │   │   ├── file.entity.ts      # 文件实体
+│   │   │   │   ├── file.service.ts     # 文件服务
+│   │   │   │   ├── minio.service.ts    # MinIO服务
+│   │   │   │   └── file.schema.ts      # 文件Schema定义
 │   │   └── utils/
 │   │       ├── __tests__/              # 新增：工具测试
 │   │       ├── generic-crud.service.ts

docs/architecture/tech-stack.md

@@ -20,3 +20,4 @@
 | Testing Library | 13.x | React组件测试 | 提供组件级测试能力 | 与React项目集成 |
 | hono/testing | 内置 | API端点测试 | 验证API功能和集成 | Hono官方测试工具，更好的类型安全 |
 | node-cron | latest | 定时任务调度 | Node.js定时任务调度库 | 集成到应用启动流程 |
+| MinIO | latest | 对象存储服务 | 提供可扩展的文件存储解决方案，替代传统文件系统存储 | 通过MinIO客户端SDK集成 |