[M-AI-07-02] 注册 Quiz Generation Job Definition 与输入 Snapshot #321

New Issue

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

wangdl commented

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

类型 / 标签

backend / quiz / registry / snapshot

风险等级

P1 — Definition 错误会导致 Job 无法执行；Snapshot 泄露敏感信息为 P0

依赖

M-AI-07-01

目标

根据冻结契约注册 Quiz Generation Definition，并实现输入验证与 Snapshot Builder。

Definition

Job Type 建议 quiz_generation，最终以审计结果为准。至少冻结：jobType、queueName、priority、maxRetries、timeoutMs、inputSchemaVersion、outputSchemaVersion、promptKey、promptVersion、modelTier、inputSchema、outputSchema、executor、businessValidator、referenceValidator、projector。队列建议 ai-interactive（若为长耗时可 ai-background，需契约说明依据）。

Snapshot Builder

新增 QuizGenerationSnapshotBuilder。职责：校验当前用户、校验目标知识库/知识点/资料归属、加载必要学习内容、限制输入长度、规范化题目数量和类型、从 Definition 获取 Prompt 和模型策略、脱敏、计算 contentHash。

输入规则

至少验证：target 存在、用户有权限、questionCount 在允许范围、questionTypes 合法、difficulty 合法、sourceMaterials 非空、内容长度不超过限制、语言合法、submissionId 稳定。

Snapshot 稳定性

相同业务输入必须产生相同：规范化 Snapshot、contentHash、questionCount、questionTypes、difficulty。不得将当前毫秒时间或随机值加入 hash。

安全

禁止进入 Snapshot：JWT、Authorization、Cookie、API Key、DATABASE_URL、REDIS_URL、其他用户内容、未筛选的整库数据。

约束

不修改原 Controller / 不创建真实 Job / 不调用模型 / 不写 Quiz / 不新增 Migration

验收标准

Definition 注册成功
重复注册失败
权限校验正确（跨用户拒绝）
非法参数拒绝（questionCount/题型/难度）
Snapshot 最小且完整
contentHash 稳定
无敏感信息
单元测试通过

建议执行顺序

第 2 个执行

## 类型 / 标签 - backend / quiz / registry / snapshot ## 风险等级 P1 — Definition 错误会导致 Job 无法执行；Snapshot 泄露敏感信息为 P0 ## 依赖 - M-AI-07-01 ## 目标根据冻结契约注册 Quiz Generation Definition，并实现输入验证与 Snapshot Builder。 ## Definition Job Type 建议 `quiz_generation`，最终以审计结果为准。至少冻结：jobType、queueName、priority、maxRetries、timeoutMs、inputSchemaVersion、outputSchemaVersion、promptKey、promptVersion、modelTier、inputSchema、outputSchema、executor、businessValidator、referenceValidator、projector。队列建议 `ai-interactive`（若为长耗时可 `ai-background`，需契约说明依据）。 ## Snapshot Builder 新增 `QuizGenerationSnapshotBuilder`。职责：校验当前用户、校验目标知识库/知识点/资料归属、加载必要学习内容、限制输入长度、规范化题目数量和类型、从 Definition 获取 Prompt 和模型策略、脱敏、计算 contentHash。 ## 输入规则至少验证：target 存在、用户有权限、questionCount 在允许范围、questionTypes 合法、difficulty 合法、sourceMaterials 非空、内容长度不超过限制、语言合法、submissionId 稳定。 ## Snapshot 稳定性相同业务输入必须产生相同：规范化 Snapshot、contentHash、questionCount、questionTypes、difficulty。不得将当前毫秒时间或随机值加入 hash。 ## 安全禁止进入 Snapshot：JWT、Authorization、Cookie、API Key、DATABASE_URL、REDIS_URL、其他用户内容、未筛选的整库数据。 ## 约束不修改原 Controller / 不创建真实 Job / 不调用模型 / 不写 Quiz / 不新增 Migration ## 验收标准 - [ ] Definition 注册成功 - [ ] 重复注册失败 - [ ] 权限校验正确（跨用户拒绝） - [ ] 非法参数拒绝（questionCount/题型/难度） - [ ] Snapshot 最小且完整 - [ ] contentHash 稳定 - [ ] 无敏感信息 - [ ] 单元测试通过 ## 建议执行顺序第 2 个执行

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

wangdl commented

2026-06-22 20:34:57 +08:00

开发完成评论

完成内容

新增 quiz_generation Job Definition: ai-interactive, primary tier, 180s timeout
新增 QuizGenerationSnapshotBuilder: KB 所有权验证, 参数规范化, 内容截断, 脱敏
新增 QuizGenerationRegistrationService: OnModuleInit 注册
更新 ai-job.module.ts 注册 2 个 Provider

修改文件

src/modules/ai-job/quiz-generation-job-definition.ts — 新增 (79 lines)
src/modules/ai-job/quiz-generation-snapshot-builder.ts — 新增 (244 lines)
src/modules/ai-job/quiz-generation-registration.service.ts — 新增 (32 lines)
src/modules/ai-job/quiz-generation-registration.service.spec.ts — 新增 (290 lines, 24 tests)
src/modules/ai-job/ai-job.module.ts — 修改 (+4 lines)

代码证据

quiz-generation-job-definition.ts:19 — jobType=quiz_generation
quiz-generation-job-definition.ts:33 — queue=ai-interactive
quiz-generation-job-definition.ts:54 — modelTier=primary
quiz-generation-snapshot-builder.ts:97-104 — 参数规范化在 DB 前 (fail-fast)
quiz-generation-snapshot-builder.ts:108-117 — KB 所有权验证
quiz-generation-snapshot-builder.ts:128-136 — content 截断到 2000 chars
quiz-generation-snapshot-builder.ts:155-158 — prompt/model 从 Definition 读取 (单一事实来源)

测试覆盖

测试	状态
Definition 注册成功	OK
重复注册拒绝	OK
字段格式验证 (6 fields)	OK
Snapshot 构建	OK
单一事实来源 (Definition values)	OK
默认值 (count=5, types=all, diff=medium)	OK
Content 截断	OK
KB 不存在	OK
KB 已删除	OK
跨用户拒绝	OK
非法 targetType	OK
非法 questionCount (0/51)	OK
非法 questionTypes	OK
非法 difficultyLevel	OK
空知识库	OK
敏感字段检查	OK
contentHash 稳定	OK
contentHash 不同输入	OK
contentHash 格式	OK

测试情况

24 passed (新增) + 506 passed (regression) = 0 failed

是否建议进入 Review

是 — 建议进入 M-AI-07-03 (Executor + Validator)

## 开发完成评论 ### 完成内容 - 新增 quiz_generation Job Definition: ai-interactive, primary tier, 180s timeout - 新增 QuizGenerationSnapshotBuilder: KB 所有权验证, 参数规范化, 内容截断, 脱敏 - 新增 QuizGenerationRegistrationService: OnModuleInit 注册 - 更新 ai-job.module.ts 注册 2 个 Provider ### 修改文件 - src/modules/ai-job/quiz-generation-job-definition.ts — 新增 (79 lines) - src/modules/ai-job/quiz-generation-snapshot-builder.ts — 新增 (244 lines) - src/modules/ai-job/quiz-generation-registration.service.ts — 新增 (32 lines) - src/modules/ai-job/quiz-generation-registration.service.spec.ts — 新增 (290 lines, 24 tests) - src/modules/ai-job/ai-job.module.ts — 修改 (+4 lines) ### 代码证据 - quiz-generation-job-definition.ts:19 — jobType=quiz_generation - quiz-generation-job-definition.ts:33 — queue=ai-interactive - quiz-generation-job-definition.ts:54 — modelTier=primary - quiz-generation-snapshot-builder.ts:97-104 — 参数规范化在 DB 前 (fail-fast) - quiz-generation-snapshot-builder.ts:108-117 — KB 所有权验证 - quiz-generation-snapshot-builder.ts:128-136 — content 截断到 2000 chars - quiz-generation-snapshot-builder.ts:155-158 — prompt/model 从 Definition 读取 (单一事实来源) ### 测试覆盖 | 测试 | 状态 | |------|------| | Definition 注册成功 | OK | | 重复注册拒绝 | OK | | 字段格式验证 (6 fields) | OK | | Snapshot 构建 | OK | | 单一事实来源 (Definition values) | OK | | 默认值 (count=5, types=all, diff=medium) | OK | | Content 截断 | OK | | KB 不存在 | OK | | KB 已删除 | OK | | 跨用户拒绝 | OK | | 非法 targetType | OK | | 非法 questionCount (0/51) | OK | | 非法 questionTypes | OK | | 非法 difficultyLevel | OK | | 空知识库 | OK | | 敏感字段检查 | OK | | contentHash 稳定 | OK | | contentHash 不同输入 | OK | | contentHash 格式 | OK | ### 测试情况 - 24 passed (新增) + 506 passed (regression) = 0 failed ### 是否建议进入 Review - 是 — 建议进入 M-AI-07-03 (Executor + Validator)

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#321