wangdl/api-server
2
0
Fork 0
Code Issues 28 Pull Requests Actions Packages Projects Releases Wiki Activity

[M-AI-06-03] 注册 ReviewCard Generation Child Job Definition 与 Snapshot #314

New Issue
Closed
opened 2026-06-21 18:13:12 +08:00 by wangdl · 1 comment
wangdl commented 2026-06-21 18:13:12 +08:00
Owner
Copy Link

类型 / 标签

  • backend / review-card / registry / snapshot

风险等级

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

依赖

  • M-AI-06-01（契约）
  • M-AI-06-02（事务创建能力）

目标

注册 ReviewCard Generation Definition，并实现 Child Snapshot Builder。

Definition

建议值：jobType = review_card_generation、queueName = ai-background、triggerType = child_job、modelTier = cheap。最终以 01 契约为准。

至少冻结：priority、maxRetries、timeoutMs、inputSchemaVersion、outputSchemaVersion、promptKey、promptVersion、modelTier、inputSchema、outputSchema、executor、businessValidator、projector。

Snapshot Builder

新增 ReviewCardGenerationSnapshotBuilder。

输入来源应是已经验证并写入的 Feynman 输出，而不是再次读取未经验证的模型原始响应。

至少包含：userId、parentJobId、sourceResultId、knowledgeItemId、knowledgeBaseId、title、summary、strengths、weaknesses、cardCount、promptKey、promptVersion、modelTier、inputSchemaVersion、outputSchemaVersion。

稳定性

相同 Parent Job 必须生成相同：Snapshot 规范化内容、contentHash、cardCount、idempotencyKey。不得将随机值或当前毫秒时间加入 hash。

安全

禁止：Parent validatedOutput 全量无筛选复制、JWT、API Key、Provider Credential、内部错误、数据库连接信息、无关用户数据。

权限

Child Snapshot 必须继承并固定 userId、knowledgeItemId、knowledgeBaseId。不得在 Child Worker 中根据客户端输入重新决定所有权。

约束

  • 不修改 Prompt / 不调用模型 / 不写 ReviewCard
  • 不切换 Legacy Subscriber
  • 不创建真实 Child Job

验收标准

  • Definition 注册成功
  • 重复注册失败
  • Snapshot 最小且完整
  • contentHash 稳定
  • cardCount 符合旧规则
  • 无敏感字段
  • Parent/Child 关联完整
  • 单元测试通过

建议执行顺序

第 3 个执行（依赖 01 契约和 02 事务能力）

## 类型 / 标签 - backend / review-card / registry / snapshot ## 风险等级 P1 — Definition 错误会导致 Job 无法执行；Snapshot 泄露敏感信息为 P0 ## 依赖 - M-AI-06-01（契约） - M-AI-06-02（事务创建能力） ## 目标 注册 ReviewCard Generation Definition，并实现 Child Snapshot Builder。 ## Definition 建议值：jobType = review_card_generation、queueName = ai-background、triggerType = child_job、modelTier = cheap。最终以 01 契约为准。 至少冻结：priority、maxRetries、timeoutMs、inputSchemaVersion、outputSchemaVersion、promptKey、promptVersion、modelTier、inputSchema、outputSchema、executor、businessValidator、projector。 ## Snapshot Builder 新增 ReviewCardGenerationSnapshotBuilder。 输入来源应是已经验证并写入的 Feynman 输出，而不是再次读取未经验证的模型原始响应。 至少包含：userId、parentJobId、sourceResultId、knowledgeItemId、knowledgeBaseId、title、summary、strengths、weaknesses、cardCount、promptKey、promptVersion、modelTier、inputSchemaVersion、outputSchemaVersion。 ## 稳定性 相同 Parent Job 必须生成相同：Snapshot 规范化内容、contentHash、cardCount、idempotencyKey。不得将随机值或当前毫秒时间加入 hash。 ## 安全 禁止：Parent validatedOutput 全量无筛选复制、JWT、API Key、Provider Credential、内部错误、数据库连接信息、无关用户数据。 ## 权限 Child Snapshot 必须继承并固定 userId、knowledgeItemId、knowledgeBaseId。不得在 Child Worker 中根据客户端输入重新决定所有权。 ## 约束 - 不修改 Prompt / 不调用模型 / 不写 ReviewCard - 不切换 Legacy Subscriber - 不创建真实 Child Job ## 验收标准 - [ ] Definition 注册成功 - [ ] 重复注册失败 - [ ] Snapshot 最小且完整 - [ ] contentHash 稳定 - [ ] cardCount 符合旧规则 - [ ] 无敏感字段 - [ ] Parent/Child 关联完整 - [ ] 单元测试通过 ## 建议执行顺序 第 3 个执行（依赖 01 契约和 02 事务能力）
wangdl added this to the M-AI-06 Feynman ReviewCard 子 Job 与可靠生成 milestone 2026-06-21 18:13:12 +08:00
wangdl commented 2026-06-21 19:10:07 +08:00
Author
Owner
Copy Link

开发完成评论

完成内容

  • 新增 review-card-generation-job-definition.ts：冻结 Child Job Definition

    • jobType: 'review_card_generation'
    • queueName: 'ai-background'（不阻塞用户请求）
    • modelTier: 'cheap'（与旧 ReviewCardGenerationWorkflow 一致）
    • promptKey: 'review-card-generation', promptVersion: '1.0.0'
    • timeoutMs: 120_000, maxRetries: 3, cancellable: true
    • projectorKey: 'review_card_generation_projector'

  • 新增 review-card-generation-snapshot-builder.ts：Child Snapshot Builder

    • 接收已验证的 Feynman 输出（非模型原始响应）
    • 确定性 cardCount：Math.min(3, Math.max(1, weaknesses.length || 1))
    • title 截断 80 字符，summary 拼接与 Legacy 一致
    • prompt/model 值全部从 Definition 读取（单一事实来源）
    • computeHash() 使用稳定序列化（字段按字母序排序），SHA256 前 16 字符
    • 禁止字段：JWT/API Key/Credential/PII
    • 无数据库依赖（所有数据由调用方传入）

  • 新增 review-card-generation-registration.service.ts：OnModuleInit 注册服务

    • 容忍 API+Worker 双进程重复注册

  • 修改 ai-job.module.ts：注册 2 个新 Provider

修改文件

  • src/modules/ai-job/review-card-generation-job-definition.ts — 新增（65 行）
  • src/modules/ai-job/review-card-generation-snapshot-builder.ts — 新增（189 行）
  • src/modules/ai-job/review-card-generation-registration.service.ts — 新增（42 行）
  • src/modules/ai-job/review-card-generation-registration.service.spec.ts — 新增（261 行，32 个测试）
  • src/modules/ai-job/ai-job.module.ts — 修改（+4 行：2 个 import + 2 个 provider）

代码证据

  • review-card-generation-snapshot-builder.ts:116-117 — cardCount 规则：Math.min(3, Math.max(1, count))（契约 §1.4）
  • review-card-generation-snapshot-builder.ts:122-123 — summary 拼接格式与 Legacy review-card.subscriber.ts:36-37 一致
  • review-card-generation-snapshot-builder.ts:104-108 — prompt/model 值全部来自 this.registry.get('review_card_generation')，零硬编码
  • review-card-generation-snapshot-builder.ts:138-142 — computeHash 使用 Object.keys().sort() 稳定序列化
  • review-card-generation-snapshot-builder.ts:133 — createdAt 归一化到秒 .replace(/\.\d{3}Z$/, 'Z')，保证稳定 hash
  • review-card-generation-job-definition.ts:48 — queueName: 'ai-background'
  • review-card-generation-job-definition.ts:65 — modelTier: 'cheap'
  • review-card-generation-job-definition.ts:66 — modelName: 'deepseek-chat'（cheap tier 默认模型）

测试情况

  • 已运行命令： 
    npx jest --testPathPatterns="review-card-generation"
npx jest --testPathPatterns="ai-job|ai-analysis.*spec|outbox"
  • 结果：
    • 新增：32 passed（17 注册验证 + 15 Snapshot Builder）
    • 回归：20 suites, 418 passed, 0 failed
    • 回归含：AiJobCreationService (19), ActiveRecallRegistration (17), FeynmanRegistration (17), Engine tests, Outbox tests

Snapshot Builder 测试覆盖

测试 状态
有效快照构建（全部字段验证） ✅
prompt/model 值来自 Definition（单一事实来源） ✅
cardCount=1（无 weaknesses） ✅
cardCount=1（undefined weaknesses） ✅
cardCount=1（1 个 weakness） ✅
cardCount=2（2 个 weaknesses） ✅
cardCount capped at 3（5 个 weaknesses） ✅
title 截断 80 字符 ✅
title fallback "AI 分析结果" ✅
不含敏感字段（JWT/API Key/Credential 等） ✅
不含 Parent Job 全量实体 ✅
createdAt 归一化到秒 ✅
contentHash 稳定（相同输入→相同hash） ✅
contentHash 不同（不同输入→不同hash） ✅
contentHash 长度 16，hex 格式 ✅
contentHash 无随机性（10 次相同输入→相同hash） ✅

未完成 / 风险

  • 无风险。本批仅注册 Definition 和 Snapshot Builder，不调用模型、不写数据库、不切换 EventBus
  • Executor（M-AI-06-04）和 Projector（M-AI-06-05）尚未实现，当前 Definition 的 executor/businessValidator/projector 字段仅声明式冻结，执行时由 Engine 通过 projectorKey 匹配
  • Snapshot Builder 无 Prisma 依赖——调用方（FeynmanProjector in M-AI-06-06）负责在事务外构建 snapshot

是否建议进入 Review

  • 是 — 建议进入 M-AI-06-04（实现 ReviewCard Generation Executor 与输出验证）
## 开发完成评论 ### 完成内容 - **新增 `review-card-generation-job-definition.ts`**：冻结 Child Job Definition - `jobType: 'review_card_generation'` - `queueName: 'ai-background'`（不阻塞用户请求） - `modelTier: 'cheap'`（与旧 ReviewCardGenerationWorkflow 一致） - `promptKey: 'review-card-generation'`, `promptVersion: '1.0.0'` - `timeoutMs: 120_000`, `maxRetries: 3`, `cancellable: true` - `projectorKey: 'review_card_generation_projector'` - **新增 `review-card-generation-snapshot-builder.ts`**：Child Snapshot Builder - 接收已验证的 Feynman 输出（非模型原始响应） - 确定性 cardCount：`Math.min(3, Math.max(1, weaknesses.length || 1))` - title 截断 80 字符，summary 拼接与 Legacy 一致 - prompt/model 值全部从 Definition 读取（单一事实来源） - `computeHash()` 使用稳定序列化（字段按字母序排序），SHA256 前 16 字符 - 禁止字段：JWT/API Key/Credential/PII - 无数据库依赖（所有数据由调用方传入） - **新增 `review-card-generation-registration.service.ts`**：OnModuleInit 注册服务 - 容忍 API+Worker 双进程重复注册 - **修改 `ai-job.module.ts`**：注册 2 个新 Provider ### 修改文件 - `src/modules/ai-job/review-card-generation-job-definition.ts` — **新增**（65 行） - `src/modules/ai-job/review-card-generation-snapshot-builder.ts` — **新增**（189 行） - `src/modules/ai-job/review-card-generation-registration.service.ts` — **新增**（42 行） - `src/modules/ai-job/review-card-generation-registration.service.spec.ts` — **新增**（261 行，32 个测试） - `src/modules/ai-job/ai-job.module.ts` — **修改**（+4 行：2 个 import + 2 个 provider） ### 代码证据 - `review-card-generation-snapshot-builder.ts:116-117` — cardCount 规则：`Math.min(3, Math.max(1, count))`（契约 §1.4） - `review-card-generation-snapshot-builder.ts:122-123` — summary 拼接格式与 Legacy `review-card.subscriber.ts:36-37` 一致 - `review-card-generation-snapshot-builder.ts:104-108` — prompt/model 值全部来自 `this.registry.get('review_card_generation')`，零硬编码 - `review-card-generation-snapshot-builder.ts:138-142` — computeHash 使用 `Object.keys().sort()` 稳定序列化 - `review-card-generation-snapshot-builder.ts:133` — createdAt 归一化到秒 `.replace(/\.\d{3}Z$/, 'Z')`，保证稳定 hash - `review-card-generation-job-definition.ts:48` — `queueName: 'ai-background'` - `review-card-generation-job-definition.ts:65` — `modelTier: 'cheap'` - `review-card-generation-job-definition.ts:66` — `modelName: 'deepseek-chat'`（cheap tier 默认模型） ### 测试情况 - 已运行命令： ``` npx jest --testPathPatterns="review-card-generation" npx jest --testPathPatterns="ai-job|ai-analysis.*spec|outbox" ``` - 结果： - 新增：32 passed（17 注册验证 + 15 Snapshot Builder） - 回归：20 suites, 418 passed, 0 failed - 回归含：AiJobCreationService (19), ActiveRecallRegistration (17), FeynmanRegistration (17), Engine tests, Outbox tests ### Snapshot Builder 测试覆盖 | 测试 | 状态 | |------|------| | 有效快照构建（全部字段验证） | ✅ | | prompt/model 值来自 Definition（单一事实来源） | ✅ | | cardCount=1（无 weaknesses） | ✅ | | cardCount=1（undefined weaknesses） | ✅ | | cardCount=1（1 个 weakness） | ✅ | | cardCount=2（2 个 weaknesses） | ✅ | | cardCount capped at 3（5 个 weaknesses） | ✅ | | title 截断 80 字符 | ✅ | | title fallback "AI 分析结果" | ✅ | | 不含敏感字段（JWT/API Key/Credential 等） | ✅ | | 不含 Parent Job 全量实体 | ✅ | | createdAt 归一化到秒 | ✅ | | contentHash 稳定（相同输入→相同hash） | ✅ | | contentHash 不同（不同输入→不同hash） | ✅ | | contentHash 长度 16，hex 格式 | ✅ | | contentHash 无随机性（10 次相同输入→相同hash） | ✅ | ### 未完成 / 风险 - **无风险**。本批仅注册 Definition 和 Snapshot Builder，不调用模型、不写数据库、不切换 EventBus - Executor（M-AI-06-04）和 Projector（M-AI-06-05）尚未实现，当前 Definition 的 executor/businessValidator/projector 字段仅声明式冻结，执行时由 Engine 通过 projectorKey 匹配 - Snapshot Builder 无 Prisma 依赖——调用方（FeynmanProjector in M-AI-06-06）负责在事务外构建 snapshot ### 是否建议进入 Review - **是** — 建议进入 M-AI-06-04（实现 ReviewCard Generation Executor 与输出验证）
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
adr
Area: adr
architecture
Area: architecture
area:activity
活动/统计
area:admin
管理后台
area:admin-api
area:ai
AI/RAG
area:ai-runtime
AI Runtime / AI 分析体系相关
area:analytics
area:api
API 接口
area:auth
认证与授权
area:cos
对象存储
area:database
数据库/Migration
area:import
文件导入/解析
area:knowledge
知识库/知识点
area:learning-info
area:learning-session
area:quiz
测验/自测
area:reading-event
area:reading-progress
area:review
复习系统
area:security
安全相关
audit
Area: audit
audit:api-admin-info
audit:api-info
audit:planned
已完成宏观规划，尚未代码审查
audit:reviewed
backend
Area: backend
billing
Area: billing
blocked-by:api-info-aggregation
blocked-by:api-info-core
blocked-by:api-info-ops
blocked-by:api-info-schema
blocked-by:processor
blocked-by:schema
compatibility
Area: compatibility
gate
Area: gate
infrastructure
Area: infrastructure
priority:p0
最高优先级，阻塞发布
priority:p1
高优先级，里程碑必需
priority:p2
中优先级，后续版本
prisma
Area: prisma
release
Area: release
repo:api
API 仓库 Issue
status:blocked
被阻塞
status:done
已完成
status:partial
status:todo
type:aggregation
type:bug
缺陷修复
type:design
设计
type:docs
文档
type:feature
新功能
type:migration
type:refactor
重构
type:test
work:admin-api
work:aggregation
work:api
work:artifact
题目/卡片产物
work:audit
work:circuit-breaker
熔断
work:contract
work:design
架构/协议设计工作
work:docs
work:export
work:extend-existing
work:internal-api
Runtime 内部接口
work:job
Job 调度相关
work:new-module
work:new-table
work:ops
work:query
work:quota
额度/限流
work:schema
Prisma Schema 设计
work:security
work:service
Service 层实现
work:snapshot
Snapshot 构建
work:test
No Label
Milestone
No items
No Milestone M-AI-06 Feynman ReviewCard 子 Job 与可靠生成
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#314
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?