H0-06 补齐 iOS 核心流程 DTO（import / source / learning-session） #51

New Issue

wangdl · 2026-05-24T21:49:32+08:00

wangdl commented

2026-05-24 21:49:32 +08:00

目标

为 import、source、learning-session 三个核心 Controller 补齐 DTO 定义，消除 @Body() any 的安全隐患。

背景说明

当前以下 Controller 使用 @Body() any 接收请求体，缺少类型校验和 Swagger 文档：

document-import.controller
knowledge-source.controller
learning-session.controller

这导致 iOS 端无法确认请求格式，也无法通过 Swagger 自测，是 iOS 对接的关键阻断点。

模块职责

请设计和补齐以下 DTO：

DocumentImport 相关 DTO（创建导入任务、查询状态等）
KnowledgeSource 相关 DTO（创建 Source、版本管理等）
LearningSession 相关 DTO（创建会话、提交 ActiveRecall 等）
每个 DTO 配套 ValidationPipe 校验规则
每个 DTO 配套 Swagger 注解（ApiProperty）

禁止事项

禁止保留 @Body() any
不要照搬现有数据对象的所有字段——只暴露 API 层需要的字段

## 目标为 import、source、learning-session 三个核心 Controller 补齐 DTO 定义，消除 @Body() any 的安全隐患。 ## 背景说明当前以下 Controller 使用 @Body() any 接收请求体，缺少类型校验和 Swagger 文档： - document-import.controller - knowledge-source.controller - learning-session.controller 这导致 iOS 端无法确认请求格式，也无法通过 Swagger 自测，是 iOS 对接的关键阻断点。 ## 模块职责请设计和补齐以下 DTO： 1. DocumentImport 相关 DTO（创建导入任务、查询状态等） 2. KnowledgeSource 相关 DTO（创建 Source、版本管理等） 3. LearningSession 相关 DTO（创建会话、提交 ActiveRecall 等） 4. 每个 DTO 配套 ValidationPipe 校验规则 5. 每个 DTO 配套 Swagger 注解（ApiProperty） ## 禁止事项 - 禁止保留 @Body() any - 不要照搬现有数据对象的所有字段——只暴露 API 层需要的字段

wangdl added this to the H0：iOS 对接阻断修复（P0） milestone 2026-05-24 21:49:32 +08:00

wangdl commented

2026-05-24 22:22:44 +08:00

✅ H0-06 修复完成

问题

iOS 核心流程的三个 Controller（document-import、knowledge-source、learning-session）使用 @Body() body: any，无类型校验。iOS 客户端可能发送错误字段但拿到 201，直到 AI 异步处理阶段才失败。

修改

文件	变更
`src/modules/document-import/dto/create-import.dto.ts`	新建 — CreateImportDto: userId?, knowledgeBaseId?, fileName? (@MaxLength 500), sourceType?, rawText?
`src/modules/knowledge-source/dto/add-source.dto.ts`	新建 — AddSourceDto: fileId?, type? (@IsIn file/link/manual/paste), title?, originalFilename?, mimeType?, sizeBytes?, originalObjectKey?
`src/modules/learning-session/dto/start-session.dto.ts`	新建 — StartSessionDto: knowledgeItemId?, knowledgeBaseId?, mode? (@IsIn active_recall/feynman/review/reading)
`src/modules/document-import/document-import.controller.ts`	`@Body() body: any` → `@Body() dto: CreateImportDto`
`src/modules/knowledge-source/knowledge-source.controller.ts`	`@Body() dto: any` → `@Body() dto: AddSourceDto`
`src/modules/learning-session/learning-session.controller.ts`	`@Body() body: any` → `@Body() dto: StartSessionDto`
`test/mocks/ioredis.mock.ts`	添加 `eval()` mock 方法以支持 Redis lock/unlock 流程
`test/h0.e2e-spec.ts`	新增 H0-06 相关 4 个测试用例

DTO 校验规则

DTO	校验
CreateImportDto	全部可选，fileName 最长 500 字符
AddSourceDto	全部可选，type 枚举校验（file/link/manual/paste），title/filename 最长 500 字符，sizeBytes 数字校验
StartSessionDto	全部可选，mode 枚举校验（active_recall/feynman/review/reading）

测试

npx jest --config ./test/jest-e2e.json --testPathPatterns="h0" --forceExit  # 22/22
npx jest --config ./test/jest-e2e.json --testPathPatterns="m0" --forceExit  # 25/25, no regression

## ✅ H0-06 修复完成 ### 问题 iOS 核心流程的三个 Controller（document-import、knowledge-source、learning-session）使用 `@Body() body: any`，无类型校验。iOS 客户端可能发送错误字段但拿到 201，直到 AI 异步处理阶段才失败。 ### 修改 | 文件 | 变更 | |------|------| | `src/modules/document-import/dto/create-import.dto.ts` | **新建** — CreateImportDto: userId?, knowledgeBaseId?, fileName? (@MaxLength 500), sourceType?, rawText? | | `src/modules/knowledge-source/dto/add-source.dto.ts` | **新建** — AddSourceDto: fileId?, type? (@IsIn file/link/manual/paste), title?, originalFilename?, mimeType?, sizeBytes?, originalObjectKey? | | `src/modules/learning-session/dto/start-session.dto.ts` | **新建** — StartSessionDto: knowledgeItemId?, knowledgeBaseId?, mode? (@IsIn active_recall/feynman/review/reading) | | `src/modules/document-import/document-import.controller.ts` | `@Body() body: any` → `@Body() dto: CreateImportDto` | | `src/modules/knowledge-source/knowledge-source.controller.ts` | `@Body() dto: any` → `@Body() dto: AddSourceDto` | | `src/modules/learning-session/learning-session.controller.ts` | `@Body() body: any` → `@Body() dto: StartSessionDto` | | `test/mocks/ioredis.mock.ts` | 添加 `eval()` mock 方法以支持 Redis lock/unlock 流程 | | `test/h0.e2e-spec.ts` | 新增 H0-06 相关 4 个测试用例 | ### DTO 校验规则 | DTO | 校验 | |-----|------| | CreateImportDto | 全部可选，fileName 最长 500 字符 | | AddSourceDto | 全部可选，type 枚举校验（file/link/manual/paste），title/filename 最长 500 字符，sizeBytes 数字校验 | | StartSessionDto | 全部可选，mode 枚举校验（active_recall/feynman/review/reading） | ### 测试 ```bash npx jest --config ./test/jest-e2e.json --testPathPatterns="h0" --forceExit # 22/22 npx jest --config ./test/jest-e2e.json --testPathPatterns="m0" --forceExit # 25/25, no regression ```

wangdl referenced this issue

2026-05-24 22:27:35 +08:00

H0-07 修复后跑核心 CAPI E2E + 输出 iOS 对接文档 #52

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

H0-07 修复后跑核心 CAPI E2E + 输出 iOS 对接文档 #52

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

H0-12 Quiz 模型与API #57

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

H0-11 RAG Chat 回复接入真实检索管道 #56

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

H0-07 修复后跑核心 CAPI E2E + 输出 iOS 对接文档 #52

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