[M-AI-07-01] 审计并冻结 Quiz 生成与题目产物迁移契约 #320

New Issue

wangdl · 2026-06-22T20:23:23+08:00

wangdl commented

2026-06-22 20:23:23 +08:00

类型 / 标签

audit / architecture / quiz / migration

风险等级

P0 — 契约错误将导致全量返工

依赖

M-AI-06 PASS

目标

完整审计当前 Quiz 生成链路、数据模型、Prompt、题型和客户端消费方式，冻结后续迁移契约。

必须审计

公开入口

确认所有真实 Quiz 生成入口：HTTP 路径、Controller、请求/响应 DTO、认证和权限、客户端调用方、是否存在不同入口（知识库/知识点/资料）、是否存在 Admin 内部入口。

当前执行链路

追踪 Controller → Quiz Service → Job/Queue → Worker → Quiz Workflow → AiGateway/Provider → Quiz Repository → Question Repository。所有结论附文件路径、类名、方法名、行号。

数据模型

逐字段审计：Quiz、QuizQuestion、QuizOption、QuizAttempt、QuizAnswer 及其他相关实体。确认主键、用户关联、知识库/知识点关联、题型、正确答案保存方式、选项保存方式、解析、难度、排序、状态、删除策略、唯一约束、索引。

当前题型

确认系统实际支持哪些题型（如 single_choice / multiple_choice / true_false / short_answer），不得自行增加新题型。

输入/输出分类

列出当前模型调用使用的字段，分类为：进入 Snapshot / 执行时查询 / 禁止进入 Snapshot。冻结模型实际输出 Schema。

查询与答案泄漏

确认哪个接口返回 Quiz/Question、未作答前是否隐藏正确答案、提交后如何返回解析、Admin 是否能查看答案、客户端依赖哪些字段。

幂等与副作用

确认是否已有 generationRequestId / submissionId / sessionId / sourceId / idempotencyKey。确认生成 Quiz 是否还会消耗会员额度、写 UsageLog、写学习记录、创建通知、更新知识点状态等。

输出

新增 docs/architecture/m-ai-07-quiz-generation-migration-contract.md，包含：当前时序图、目标时序图、数据关系图、Snapshot Schema、Output Schema、题型规则、副作用矩阵、Artifact 矩阵、幂等契约、权限模型、答案隐藏契约、Feature Flag、回滚流程、不确定项。

非目标

不修改代码 / 不修改 Prisma / 不创建 Migration / 不注册 Definition / 不切换流量

验收标准

所有 Quiz 生成入口确认（HTTP 路径 + Controller + DTO）
当前执行链路完整记录（文件路径+行号）
Quiz/Question/Option/Answer 数据模型字段级审计完成
真实题型清单冻结
输入字段分类完成
输出 Schema 冻结
答案隐藏机制确认
幂等策略冻结
副作用矩阵完成
契约文档写入 docs/architecture/

建议执行顺序

第 1 个执行

## 类型 / 标签 - audit / architecture / quiz / migration ## 风险等级 P0 — 契约错误将导致全量返工 ## 依赖 - M-AI-06 PASS ## 目标完整审计当前 Quiz 生成链路、数据模型、Prompt、题型和客户端消费方式，冻结后续迁移契约。 ## 必须审计 ### 公开入口确认所有真实 Quiz 生成入口：HTTP 路径、Controller、请求/响应 DTO、认证和权限、客户端调用方、是否存在不同入口（知识库/知识点/资料）、是否存在 Admin 内部入口。 ### 当前执行链路追踪 Controller → Quiz Service → Job/Queue → Worker → Quiz Workflow → AiGateway/Provider → Quiz Repository → Question Repository。所有结论附文件路径、类名、方法名、行号。 ### 数据模型逐字段审计：Quiz、QuizQuestion、QuizOption、QuizAttempt、QuizAnswer 及其他相关实体。确认主键、用户关联、知识库/知识点关联、题型、正确答案保存方式、选项保存方式、解析、难度、排序、状态、删除策略、唯一约束、索引。 ### 当前题型确认系统实际支持哪些题型（如 single_choice / multiple_choice / true_false / short_answer），不得自行增加新题型。 ### 输入/输出分类列出当前模型调用使用的字段，分类为：进入 Snapshot / 执行时查询 / 禁止进入 Snapshot。冻结模型实际输出 Schema。 ### 查询与答案泄漏确认哪个接口返回 Quiz/Question、未作答前是否隐藏正确答案、提交后如何返回解析、Admin 是否能查看答案、客户端依赖哪些字段。 ### 幂等与副作用确认是否已有 generationRequestId / submissionId / sessionId / sourceId / idempotencyKey。确认生成 Quiz 是否还会消耗会员额度、写 UsageLog、写学习记录、创建通知、更新知识点状态等。 ## 输出新增 `docs/architecture/m-ai-07-quiz-generation-migration-contract.md`，包含：当前时序图、目标时序图、数据关系图、Snapshot Schema、Output Schema、题型规则、副作用矩阵、Artifact 矩阵、幂等契约、权限模型、答案隐藏契约、Feature Flag、回滚流程、不确定项。 ## 非目标不修改代码 / 不修改 Prisma / 不创建 Migration / 不注册 Definition / 不切换流量 ## 验收标准 - [ ] 所有 Quiz 生成入口确认（HTTP 路径 + Controller + DTO） - [ ] 当前执行链路完整记录（文件路径+行号） - [ ] Quiz/Question/Option/Answer 数据模型字段级审计完成 - [ ] 真实题型清单冻结 - [ ] 输入字段分类完成 - [ ] 输出 Schema 冻结 - [ ] 答案隐藏机制确认 - [ ] 幂等策略冻结 - [ ] 副作用矩阵完成 - [ ] 契约文档写入 docs/architecture/ ## 建议执行顺序第 1 个执行

wangdl added this to the M-AI-07 Quiz 生成与题目产物统一引擎迁移 milestone 2026-06-22 20:23:23 +08:00

wangdl commented

2026-06-22 20:30:32 +08:00

开发完成评论

完成内容

审计 Quiz 生成双系统：确认存在 Procedural Quiz 和 AI Quiz Generation 两套系统，本批只迁移 AI Quiz
追踪完整 AI Quiz 执行链路：入口 POST /ai/jobs → UserAiService.createAnalysisJob() → aiRuntimeJob → Runtime 轮询 → POST /internal/runtime/jobs/:id/result → convertQuizCandidates() → Quiz + QuizQuestion
审计 5 个数据模型：Quiz (12 字段)、QuizQuestion (10 字段)、QuizAttempt (8 字段)、QuizAnswer (6 字段)、QuestionGenerationPlan (14 字段)
确认 3 种题型：choice（选择题）、fill（填空题）、judge（判断题）
发现 7 个架构异常：A1 无 Prompt 模板（阻塞）、A2 无 Output Schema（阻塞）、A3-A4 答案泄漏（P0）、A5 硬编码 deepseek-chat（P2）、A6 stem 去重（P2）、A7 两阶段发布（P2）
冻结完整契约：Snapshot Schema (16 字段)、Output Schema、幂等策略、副作用矩阵、Artifact 矩阵、权限模型、答案隐藏契约、Feature Flag、回滚流程
输出：docs/architecture/m-ai-07-quiz-generation-migration-contract.md (585 行)

修改文件

docs/architecture/m-ai-07-quiz-generation-migration-contract.md — 新增 (585 行)

代码证据

发现	证据
AI Quiz 入口	`user-ai.controller.ts:63` — `POST /ai/jobs` with `jobType: 'quiz_generation'`
入口 Service	`user-ai.service.ts:199` — `createAnalysisJob()` 13 步骤
Runtime 轮询	`runtime-internal.controller.ts:22` — `POST /internal/runtime/jobs/poll`
Quiz 持久化	`runtime-internal.service.ts:435` — `convertQuizCandidates()`
答案泄漏	`user-ai.service.ts:553` — `getQuizQuestions()` 包含 `answer` + `explanation`
答案泄漏	`quiz.service.ts:85` — `findOne()` include `questions` 含 `answer`
无 Prompt	`prompt-template.service.ts` — 注册表无 quiz prompt
硬编码模型	`user-ai.service.ts:294` — `modelName: 'deepseek-chat'`
题型	`quiz.service.ts:38` — `['choice', 'fill', 'judge']`
Quiz 模型	`schema.prisma:1833-1853`
QuizQuestion 模型	`schema.prisma:1855-1871`

架构异常清单

#	异常	严重程度	处理
A1	API 无 Quiz Prompt 模板	阻塞	M-AI-07-03 需新增（从 Runtime 获取或重新设计）
A2	API 无 Quiz Output Schema	阻塞	同上
A3	getQuizQuestions() 泄漏答案	P0	M-AI-07-06 修复
A4	findOne() include questions 泄漏答案	P0	M-AI-07-06 修复
A5	deepseek-chat 硬编码	P2	Unified 使用 Definition+ModelRouter
A6	题目去重依赖 stem 全局匹配	P2	Unified 使用确定性 ID
A7	Quiz 两阶段发布	P2	保留或简化

测试情况

已运行命令：

npx jest --testPathPatterns="quiz|ai-runtime|user-ai"

结果：13 suites, 291 passed, 0 failed

是否建议进入 Review

是 — 契约已冻结。需注意 A1/A2 阻塞项：M-AI-07-02/03 执行前需先解决 Prompt/Schema 来源问题

## 开发完成评论 ### 完成内容 - **审计 Quiz 生成双系统**：确认存在 Procedural Quiz 和 AI Quiz Generation 两套系统，本批只迁移 AI Quiz - **追踪完整 AI Quiz 执行链路**：入口 `POST /ai/jobs` → `UserAiService.createAnalysisJob()` → `aiRuntimeJob` → Runtime 轮询 → `POST /internal/runtime/jobs/:id/result` → `convertQuizCandidates()` → Quiz + QuizQuestion - **审计 5 个数据模型**：Quiz (12 字段)、QuizQuestion (10 字段)、QuizAttempt (8 字段)、QuizAnswer (6 字段)、QuestionGenerationPlan (14 字段) - **确认 3 种题型**：choice（选择题）、fill（填空题）、judge（判断题） - **发现 7 个架构异常**：A1 无 Prompt 模板（阻塞）、A2 无 Output Schema（阻塞）、A3-A4 答案泄漏（P0）、A5 硬编码 deepseek-chat（P2）、A6 stem 去重（P2）、A7 两阶段发布（P2） - **冻结完整契约**：Snapshot Schema (16 字段)、Output Schema、幂等策略、副作用矩阵、Artifact 矩阵、权限模型、答案隐藏契约、Feature Flag、回滚流程 - **输出**：`docs/architecture/m-ai-07-quiz-generation-migration-contract.md` (585 行) ### 修改文件 - `docs/architecture/m-ai-07-quiz-generation-migration-contract.md` — **新增** (585 行) ### 代码证据 | 发现 | 证据 | |------|------| | AI Quiz 入口 | `user-ai.controller.ts:63` — `POST /ai/jobs` with `jobType: 'quiz_generation'` | | 入口 Service | `user-ai.service.ts:199` — `createAnalysisJob()` 13 步骤 | | Runtime 轮询 | `runtime-internal.controller.ts:22` — `POST /internal/runtime/jobs/poll` | | Quiz 持久化 | `runtime-internal.service.ts:435` — `convertQuizCandidates()` | | 答案泄漏 | `user-ai.service.ts:553` — `getQuizQuestions()` 包含 `answer` + `explanation` | | 答案泄漏 | `quiz.service.ts:85` — `findOne()` include `questions` 含 `answer` | | 无 Prompt | `prompt-template.service.ts` — 注册表无 quiz prompt | | 硬编码模型 | `user-ai.service.ts:294` — `modelName: 'deepseek-chat'` | | 题型 | `quiz.service.ts:38` — `['choice', 'fill', 'judge']` | | Quiz 模型 | `schema.prisma:1833-1853` | | QuizQuestion 模型 | `schema.prisma:1855-1871` | ### 架构异常清单 | # | 异常 | 严重程度 | 处理 | |---|------|---------|------| | A1 | API 无 Quiz Prompt 模板 | 阻塞 | M-AI-07-03 需新增（从 Runtime 获取或重新设计） | | A2 | API 无 Quiz Output Schema | 阻塞 | 同上 | | A3 | getQuizQuestions() 泄漏答案 | P0 | M-AI-07-06 修复 | | A4 | findOne() include questions 泄漏答案 | P0 | M-AI-07-06 修复 | | A5 | deepseek-chat 硬编码 | P2 | Unified 使用 Definition+ModelRouter | | A6 | 题目去重依赖 stem 全局匹配 | P2 | Unified 使用确定性 ID | | A7 | Quiz 两阶段发布 | P2 | 保留或简化 | ### 测试情况 - 已运行命令： ``` npx jest --testPathPatterns="quiz|ai-runtime|user-ai" ``` - 结果：13 suites, 291 passed, 0 failed ### 是否建议进入 Review - **是** — 契约已冻结。需注意 A1/A2 阻塞项：M-AI-07-02/03 执行前需先解决 Prompt/Schema 来源问题

wangdl closed this issue

2026-06-22 21:23:04 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#320