api-server/docs/architecture/m-ai-05-feynman-migration-contract.md

M-AI-05 Feynman 与复习产物迁移契约

审计日期：2026-06-21 审计人：开发执行代理（只读审计，未修改代码） 基线：M-AI-04 GATE CONDITIONAL PASS (a5ad0bc) 输出：本文档冻结 Feynman 迁移的全部契约

---

1. 当前时序图（Legacy 链路）

Client
  │
  │  POST /api/ai-analysis/feynman
  │  Body: { knowledgeItemTitle, knowledgeItemContent, userExplanation, sessionId?, answerId? }
  │  Auth: JWT Bearer
  ▼
AiAnalysisController.evaluateFeynman()          [ai-analysis.controller.ts:32]
  │  @AiAnalysisRateLimit()
  │  body 无 DTO class — 直接解构 @Body()
  │
  ▼
AiAnalysisService.evaluateFeynman()             [ai-analysis.service.ts:33]
  │
  ├─► AiAnalysisRepository.createJob()           [ai-analysis.repository.ts:17]
  │     INSERT INTO AiAnalysisJob (
  │       userId, jobType='feynman-evaluation',
  │       status='pending', lifecycleStatus='queued',
  │       queueName='ai-interactive', inputSchemaVersion='legacy-v1',
  │       attemptCount=0, queuedAt=now()
  │     )
  │     RETURNING job.id
  │
  ├─► QueueService.add('ai-analysis', {          [queue.service.ts:47]
  │     jobId, userId,
  │     type: 'feynman-evaluation',
  │     knowledgeItemTitle,
  │     knowledgeItemContent,
  │     userExplanation
  │   })
  │   → BullMQ Queue: 'ai-analysis'
  │   → taskLog INSERT (status='enqueued')
  │
  └─► return { jobId: job.id, status: 'queued' }

BullMQ 'ai-analysis' Queue
  │  concurrency: 1, lockDuration: 30000ms
  │  attempts: 3, backoff: exponential 1s
  │  timeoutMs: 180_000
  ▼
AiAnalysisWorker.process()                       [ai-analysis.worker.ts:32]
  │
  ├─► repository.updateJobStatus(jobId, 'processing')   [line 48]
  │     status='processing', lifecycleStatus='running', startedAt=now()
  │
  ├─► [type === 'feynman-evaluation']
  │   FeynmanEvaluationWorkflow.execute()         [feynman-evaluation.workflow.ts:17]
  │   │
  │   │  构建 userMessage：
  │   │    【知识点标题】+ title
  │   │    【知识点原文】+ content
  │   │    【用户的费曼解释】+ userExplanation
  │   │    请评估以上费曼解释的质量，严格按照 JSON Schema 输出。
  │   │
  │   ├─► AiGatewayService.generate()             [ai-gateway.service.ts:40]
  │   │   │  feature: 'feynman-evaluation'
  │   │   │  tier: 'primary'
  │   │   │  promptKey: 'feynman-evaluation', version: '1.0.0'
  │   │   │  outputSchema: FeynmanEvaluationResultSchema
  │   │   │
  │   │   ├─► ModelRouter.resolve('primary')
  │   │   │   → preferred: deepseek, fallback: deepseek
  │   │   │   → model: deepseek-v4-pro, maxRetries: 3
  │   │   │
  │   │   ├─► PromptTemplateService.get('feynman-evaluation')
  │   │   │   → systemPrompt: FEYNMAN_EVALUATION_SYSTEM_PROMPT
  │   │   │   → schema description appended
  │   │   │
  │   │   ├─► Provider.generate()
  │   │   │   → HTTP POST to DeepSeek API
  │   │   │
  │   │   ├─► parseJson(rawText, FeynmanEvaluationResultSchema)
  │   │   │   → JSON Repair (可配置)
  │   │   │   → Zod validation
  │   │   │
  │   │   └─► usageLog.log() — cost/usage tracking
  │   │
  │   └─► return response.parsed as FeynmanEvaluationResult
  │
  ├─► repository.createResult(userId, jobId, result)     [line 67]
  │     INSERT INTO AiAnalysisResult (
  │       userId, jobId,
  │       summary=result.summary,
  │       masteryScore=result.score,
  │       strengths=result.strengths (JSON),
  │       weaknesses=result.weaknesses (JSON),
  │       suggestions=result.focusItems ?? result.suggestions (JSON),
  │       nextActions=result.reviewSuggestion ?? result.recommendations (JSON),
  │       rawResult=result (JSON)
  │     )
  │
  ├─► repository.updateJobStatus(jobId, 'completed')     [line 68]
  │     status='completed', lifecycleStatus='succeeded', finishedAt=now()
  │
  ├─► eventBus.publish(AIAnalysisCompleted)              [line 72]
  │   │  eventType: 'ai.analysis.completed'
  │   │  payload: { userId, jobId, sessionId, answerId, type, score, analysis, timestamp }
  │   │
  │   └─► [ASYNC SUBSCRIBER]
  │       ReviewCardSubscriber.handleAIAnalysisCompleted()  [review-card.subscriber.ts:12]
  │       │
  │       │  构造 title = summary.slice(0,80)
  │       │  构造 content = "摘要：...\n\n掌握点：...\n\n薄弱点：..."
  │       │  cardCount = min(3, max(1, weaknesses.length))
  │       │
  │       └─► ReviewService.generateCards()                 [review.service.ts:68]
  │           │
  │           └─► ReviewCardGenerationWorkflow.execute()    [review-card-generation.workflow.ts]
  │               │  ★ 二次 AI 调用 — feature: 'review-card-generation'
  │               │  ★ tier: 'cheap' (deepseek-v4-flash)
  │               │  outputSchema: ReviewCardGenerationSchema
  │               │
  │               └─► ReviewRepository.insertCard()  (× cardCount)
  │                     INSERT INTO ReviewCard (
  │                       userId, frontText, backText, difficulty, status='active',
  │                       intervalDays=1, easeFactor=2.5, repetitionCount=0,
  │                       lapseCount=0, scheduleState='new', nextReviewAt=now()
  │                     )
  │
  └─► FocusItemsService.create()                          [line 88]
      │  ★ for each weakness string in result.weaknesses
      │
      └─► FocusItemsRepository.create()             [focus-items.repository.ts:23]
            INSERT INTO FocusItem (
              userId, title=weaknessString,
              reason='', suggestion='', priority='normal',
              status='open', source='ai-analysis',
              knowledgeBaseId=result.knowledgeBaseId || 'unknown'
            )
            ★ result.knowledgeBaseId 在 Feynman Schema 中不存在 → 永远为 'unknown'

---

2. 目标时序图（Unified 链路）

Client
  │
  │  POST /api/ai-analysis/feynman  (不变)
  │  Body: 不变
  │  Auth: JWT Bearer (不变)
  ▼
AiAnalysisController.evaluateFeynman()          [不变]
  │
  ▼
FeynmanExecutionRouter                         [新增]
  │
  ├─► FEYNMAN_ENGINE_MODE=legacy → 原 AiAnalysisService (不变)
  │
  └─► FEYNMAN_ENGINE_MODE=unified
      │
      ├─► 原有请求校验（权限、必填字段）
      ├─► 确定 submissionId → 构造 idempotencyKey = feynman:<submissionId>
      ├─► FeynmanSnapshotBuilder.build()
      │     → 加载知识点、用户解释、参考材料
      │     → 脱敏
      │     → 计算 contentHash
      │
      └─► AiJobCreationService.create({
            userId, jobType='feynman_evaluation',
            triggerType='user_api',
            targetType='knowledge_item', targetId=knowledgeItemId,
            idempotencyKey
          })
          │
          │  ★ 同一 Prisma Transaction:
          │    1. AiJob (lifecycleStatus='queued')
          │    2. AiJobSnapshot (snapshotContent, contentHash)
          │    3. OutboxEvent (eventType='ai.job.enqueue', payload={jobId})
          │
          └─► return { jobId, status: 'queued', engineMode: 'unified' }

Outbox Dispatcher
  │
  ▼
BullMQ Queue: 'ai-interactive'
  │  payload: { jobId }  ← 极简
  ▼
AiJobExecutionEngine
  │
  ├─► lockJob (CAS: queued → running)
  ├─► load Definition (feynman_evaluation)
  ├─► load Snapshot
  │
  ├─► FeynmanExecutor.execute(snapshot, signal)
  │   │
  │   ├─► 从 Snapshot + Definition 构造消息
  │   ├─► AiGatewayService.generate()
  │   │     feature, promptKey, promptVersion, modelTier → 全部来自 Definition
  │   │
  │   └─► return rawOutput
  │
  ├─► BusinessValidator.validate(rawOutput)
  │   ★ JSON Repair → Schema Validate → Business Rules
  │
  ├─► ReferenceValidator.validate(validatedOutput, snapshot)
  │
  └─► FeynmanProjector.project(tx, { job, snapshot, validatedOutput })
      │
      │  ★ 同一 Prisma Transaction:
      │    1. AiAnalysisResult (upsert by deterministic ID)
      │    2. FocusItem (按契约创建，不超过 N 个)
      │    3. ReviewCard (按契约创建，不二次调用 AI)
      │    4. AiJobArtifact (×3: analysis_result, focus_item, review_card)
      │    5. validatedOutput + outputHash
      │    6. Job → succeeded + finishedAt
      │
      └─► 任何步骤失败 → 全部回滚

---

3. Snapshot Schema（冻结）

3.1 进入 Snapshot 的字段

字段	来源	说明
userId	JWT sub	评估者标识
knowledgeItemId	请求体 / 路由参数	知识点 ID
knowledgeItemTitle	请求体 knowledgeItemTitle	知识点标题
knowledgeItemContent	请求体 knowledgeItemContent	知识点原文
userExplanation	请求体 userExplanation	用户费曼解释
referenceMaterials	从 DB 加载	关联参考材料摘要（非全文）
knowledgeBaseId	从 knowledgeItem 推导	知识库归属
submissionId	请求体或生成	稳定业务标识（幂等）
promptKey	Definition	feynman-evaluation
promptVersion	Definition	1.0.0
modelTier	Definition	primary
inputSchemaVersion	Definition	1.0.0
outputSchemaVersion	Definition	1.0.0
createdAt	创建时间（归一化）	ISO 8601，截断到秒

3.2 执行时查询的字段

字段	说明
系统 Prompt 全文	从 PromptTemplateService 实时获取
模型凭据	从 CredentialService 实时解密
Provider 配置	从 ModelRouter 实时解析

3.3 禁止进入 Snapshot 的字段

字段	原因
JWT / Authorization Header	敏感凭据
Cookie	敏感凭据
明文模型 API Key	敏感凭据
DATABASE_URL	基础设施密钥
REDIS_URL	基础设施密钥
完整用户画像	不必要
整个知识库序列化	不必要，应只取必要字段
每次生成时间戳	破坏 contentHash 稳定性

3.4 contentHash 规范化规则

相同业务输入 → 相同 contentHash。规范化：

1. 字段按字母序排序
2. null 与缺省字段等价（不写入 null 字段）
3. 时间字段归一化（截断到秒）
4. 字符串首尾去空白（trim）
5. 数组按业务 key 排序（如有），否则按原始顺序
6. JSON 使用紧凑格式（无美化空格）

---

4. Output Schema（冻结）

4.1 当前 Feynman 输出 Schema

源文件：src/modules/ai/prompts/schemas/feynman-evaluation.schema.ts:3-14

FeynmanEvaluationResultSchema = z.object({
  score:              z.number().int().min(0).max(100),
  clarityLevel:       z.enum(['crystal_clear','clear','mostly_clear','confusing','very_confusing']),
  summary:            z.string().min(1).max(2000),
  strengths:          z.array(z.string().max(500)).max(10).default([]),
  weaknesses:         z.array(z.string().max(500)).max(10).default([]),
  blindSpots:         z.array(z.string().max(500)).max(10).default([]),
  suggestions:        z.array(z.string().max(500)).max(10).default([]),
  isBeginnerFriendly: z.boolean(),
  analogyQuality:     z.enum(['excellent','good','acceptable','poor','none']).optional(),
  jargonUsage:        z.enum(['none','minimal','moderate','heavy']),
})

4.2 已确认被业务消费的字段

字段	消费位置	用途
score	ai-analysis.repository.ts:61	→ masteryScore
summary	ai-analysis.repository.ts:60	→ summary；同时被 ReviewCardSubscriber 用于卡片标题
strengths	ai-analysis.repository.ts:62	→ strengths (JSON)；被 ReviewCardSubscriber 拼入卡片内容
weaknesses	ai-analysis.worker.ts:85-96	每个字符串创建一个 FocusItem (title=w)；被 ReviewCardSubscriber 拼入卡片内容
suggestions	ai-analysis.repository.ts:64	→ suggestions (JSON)，路径为 result.focusItems ?? result.suggestions
blindSpots	—	Schema 中有，但未在业务代码中找到消费位置
clarityLevel	—	Schema 中有，但未在业务代码中找到消费位置
isBeginnerFriendly	—	Schema 中有，但未在业务代码中找到消费位置
analogyQuality	—	Schema 中有，但未在业务代码中找到消费位置
jargonUsage	—	Schema 中有，但未在业务代码中找到消费位置

4.3 验证规则

Schema 验证（Zod 层）

• score：0-100 整数，越界拒绝
• clarityLevel：必须在枚举值内
• summary：1-2000 字符，空字符串拒绝
• strengths/weaknesses/blindSpots/suggestions：每项 ≤500 字符，数组 ≤10 项
• isBeginnerFriendly：必须是 boolean
• jargonUsage：必须在枚举值内

Business Validator（新增）

• score 在 0-100 范围内
• summary 非空且非纯空格
• strengths 和 weaknesses 不能同时为空
• 禁止空对象 {} 冒充成功
• 禁止异常大文本（单项 > 500 字符）
• 禁止模型指令或代码块进入结构化字段
• 禁止 JSON 中包含 ````json` 等 markdown 包装

Reference Validator（新增）

• 当前 Feynman 输出不包含引用字段 → 无需实现 Reference Validator
• 如果后续 Schema 增加了 sourceReferences，则必须验证

---

5. 副作用矩阵（冻结）

副作用	创建条件	数量	唯一性	失败策略	当前实现位置
AiAnalysisResult	每次 Feynman 评估	1	jobId 唯一（1:1）	抛错 → Worker catch → mark failed	ai-analysis.worker.ts:67
FocusItem	result.weaknesses.length > 0	每个 weakness 字符串 1 个（最多 10）	无去重 — 每次创建新的	单个失败被 catch 吞掉	ai-analysis.worker.ts:88
ReviewCard	EventBus 触发 + strengths/weaknesses 非空	min(3, max(1, weaknesses.length)) 张	无去重 — 每次创建新的	整个 subscriber catch 吞掉	review-card.subscriber.ts:39
UsageLog	Provider 每次调用	1（加 retry）	—	AiGateway 内部处理	ai-gateway.service.ts
ReviewLog	用户提交复习	1 per submission	—	不在 Feynman 链路内	review.service.ts:57
学习统计	间接（通过 FocusItem/ReviewCard）	不确定	—	不在 Feynman 链路内	—
通知	无	0	—	—	—
EventBus	每次 AI 分析完成	1 个 ai.analysis.completed 事件	—	catch 吞掉	ai-analysis.worker.ts:72

关键发现

1. FocusItem 的 knowledgeBaseId 永远为 'unknown'：result.knowledgeBaseId 不在 Feynman Schema 中，而 worker 代码 ai-analysis.worker.ts:89 使用 result.knowledgeBaseId || 'unknown'，因此该字段始终为 'unknown'。
2. FocusItem 无 reason/suggestion/priority：Worker 只传 title=weaknessString，其余字段为默认值（reason=''、suggestion=''、priority='normal'）。
3. ReviewCard 创建通过二次 AI 调用：不是从 Feynman 结果直接映射，而是调用独立的 review-card-generation workflow（tier: 'cheap'）。
4. 无事务保证：result、FocusItem、ReviewCard 分别在独立操作中写入，无原子性。

---

6. Artifact 矩阵（冻结）

Artifact Type	对应实体	创建时机	数量	ID 格式
AiAnalysisResult	AiAnalysisResult (analysis_result)	Projector — Result 写入后	1	ar_<jobId前24字符>
FocusItem	FocusItem (focus_item)	Projector — 每个 FocusItem 创建后	0-N	数据库自增 cuid
ReviewCard	ReviewCard (review_card)	Projector — ReviewCard 创建后	0-1	数据库自增 cuid

注：旧链路不创建 Artifact。这是 Unified 链路的产物。

---

7. 幂等契约（冻结）

7.1 幂等键

格式：feynman:<submissionId>

其中 submissionId 由业务方传入或由以下字段组合派生：

• userId
• knowledgeItemId
• userExplanation 的前 N 个字符（hash）

建议优先使用客户端传入的稳定标识（如 sessionId、answerId 组合）。

7.2 幂等语义

场景	预期行为
相同 submissionId 重复请求	返回同一个 Job（不创建新 Job/Snapshot/Outbox）
用户重新提交新解释	新 submissionId → 新 Job（不覆盖旧 Job）
相同 Job 重复消费（Worker crash 重试）	Projector 幂等 — 结果不重复
并发提交相同 submissionId	DB 唯一约束保证只有一个成功

7.3 禁止作为幂等键

• 时间戳（每次不同）
• 随机值（每次不同）
• JWT（过期后变化）
• 用户解释全文（Hash 可以，全文不行 — 太大）

---

8. 状态映射（冻结）

8.1 Legacy 状态

旧链路使用的状态字符串（来源于 ai-analysis.repository.ts:10-15）：

status (旧)	lifecycleStatus (新 Shadow Write)	说明
pending	queued	已入队，等待 Worker 拾取
processing	running	Worker 正在处理
completed	succeeded	成功完成
failed	failed	失败（含 errorMessage）

8.2 Unified 状态

lifecycleStatus	旧 status (兼容)	说明
queued	pending	Outbox 已创建，等待 Dispatcher
running	processing	Engine 已拾取并开始执行
succeeded	completed	Projector 成功
failed	failed	Executor/Validator/Projector 失败
cancelled	failed	Admin/用户取消了 Job

8.3 公开状态查询

旧接口 GET /api/ai-analysis/:id/status 返回 status 字段。Unified Job 必须映射后返回，不得直接返回 lifecycleStatus。

---

9. Job Type 映射（冻结）

位置	当前值	新 Registry Key	兼容方式
AiAnalysisService.evaluateFeynman() (ai-analysis.service.ts:40)	'feynman-evaluation'	'feynman_evaluation'	新 Definition 使用 feynman_evaluation；数据库历史记录保留 feynman-evaluation；查询时两者都匹配
AiAnalysisWorker.process() (ai-analysis.worker.ts:51)	'feynman-evaluation'	—	Legacy 分支不变
AiJob 表 jobType 列	'feynman-evaluation'	'feynman_evaluation'	历史数据不修改；Unified 新 Job 使用新值

决定：Registry Key 使用 feynman_evaluation（下划线），与 active_recall 风格一致。不修改数据库历史记录。

---

10. Feature Flag（冻结）

10.1 机制

建议新增环境变量：

FEYNMAN_ENGINE_MODE=legacy   # 默认值
FEYNMAN_ENGINE_MODE=unified  # 切换后走新引擎

或复用 FeatureFlagService（如项目已有）。

10.2 行为契约

配置	行为
legacy（默认）	所有请求走原 AiAnalysisService → ai-analysis 队列
unified	所有请求走 FeynmanExecutionRouter → AiJobCreationService
白名单模式	支持特定 userId 走 Unified，其余走 Legacy

10.3 约束

• 同一请求只能执行一个引擎（禁止双跑）
• Unified 失败不得自动调用 Legacy
• 可随时从 unified 切回 legacy
• 已创建的 Unified Job 继续完成，不重新送入旧链路
• 切回 Legacy 不需要数据库回滚

---

11. FocusItem 创建契约（冻结）

11.1 当前行为（Legacy）

源：ai-analysis.worker.ts:85-96

• 触发条件：result.weaknesses.length > 0
• 每个 weakness 创建 1 个 FocusItem，字段值：
  • title = weakness 字符串（如 "缺少生活化类比"）
  • reason = ''（空）
  • suggestion = ''（空）
  • priority = 'normal'（默认）
  • status = 'open'
  • source = 'ai-analysis'
  • knowledgeBaseId = 'unknown'（永远）
• 无去重：每次 AI 分析都创建新的 FocusItem
• 无上限：理论上最多 10 个（Schema 限制 weaknesses.max(10)）
• 失败策略：单个 FocusItem 创建失败被 catch 吞掉，不影响其他

11.2 Unified 行为（目标）

• 触发条件：同 Legacy（result.weaknesses.length > 0）
• 数量：每个 weakness 字符串 1 个，最多 10 个
• 字段映射：
  • title = weakness 字符串
  • reason = ''（Feynman Schema 无结构化 weakness，保持 Legacy 兼容）
  • suggestion = ''（同上）
  • priority = 'normal'
  • status = 'open'
  • source = 'ai-analysis'
  • knowledgeBaseId = 从 Snapshot 读取真实值（修复 Legacy bug）
  • knowledgeItemId = 从 Snapshot 读取（新增，Legacy 未设置）
• 幂等：相同 userId + title + source 不重复创建（使用 findFirst + create 或 upsert）
• 原子性：Projector 事务内完成
• 不重新设计：不改为结构化 weakness、不增加 reason/suggestion 推导逻辑

---

12. ReviewCard 创建契约（冻结）

12.1 当前行为（Legacy）

源：review-card.subscriber.ts:12-51 → review.service.ts:68-98

• 触发条件：EventBus 收到 ai.analysis.completed 事件 + strengths 或 weaknesses 非空
• 二次 AI 调用：ReviewCardGenerationWorkflow.execute() — 独立 Provider 调用（tier: 'cheap'）
• 数量：min(3, max(1, weaknesses.length)) 张
• 内容来源：
  • frontText / backText：AI 生成的卡片内容
  • difficulty：AI 判断（schema 默认 'normal'）
• 无去重：每次事件都生成新卡片
• 失败策略：整个 subscriber 方法 catch 吞掉，不影响主链路
• SM-2 参数：intervalDays=1, easeFactor=2.5, repetitionCount=0, lapseCount=0, scheduleState='new', nextReviewAt=now()
• 不关联 Job：ReviewCard 表无 jobId 字段

12.2 Unified 行为（目标）

方案选择：保持 Legacy 兼容 — 在同一 Projector 事务内基于 EventBus 逻辑创建 ReviewCard。

由于 Feynman Schema 没有 reviewSuggestion 结构化字段（ActiveRecall 有），无法像 Active Recall Projector 那样直接从输出创建 ReviewCard。需要二次 AI 调用。

但二次 AI 调用不能放在 Projector 事务内（事务内不应有外部 HTTP 调用）。

两种实现方案：

方案 A（保守）：Projector 只创建 Result + FocusItem + Artifact。ReviewCard 仍通过 EventBus 异步生成。

• 优点：事务简单，不引入新的复杂度
• 缺点：ReviewCard 生成仍非原子

方案 B（推荐）：在 Executor 阶段并行调用 Feynman 评估 + ReviewCard 生成，两者的结果一起传入 Projector。

• 优点：Projector 事务内原子写入全部产物
• 缺点：Executor 复杂度增加

本契约冻结：方案 A。理由：

1. Feynman Schema 无结构化 ReviewCard 字段，方案 B 需要改 Prompt/Schema — 这是"重新设计复习算法"的范畴（非目标）
2. 将 ReviewCard 生成改为子 Job 是 Gitea 原始里程碑的内容，但本批明确非目标
3. 保持与 Legacy 行为最大兼容

Unified 链路下 ReviewCard 仍通过 EventBus 异步生成，但 EventBus 发布从 AiAnalysisWorker 移至 Projector 完成后。

如果发现 EventBus 丢失导致 ReviewCard 不生成，那是 M-AI-06 的可靠性改进范畴。

12.3 字段映射

ReviewCard 字段	值	来源
frontText	AI 生成	ReviewCardGenerationWorkflow
backText	AI 生成	ReviewCardGenerationWorkflow
difficulty	AI 生成或 'normal'	ReviewCardGenerationWorkflow
status	'active'	硬编码
intervalDays	1	SM-2 初始值
easeFactor	2.5	SM-2 默认
repetitionCount	0	SM-2 初始值
lapseCount	0	SM-2 初始值
scheduleState	'new'	新卡片
nextReviewAt	now()	立即可复习
knowledgeItemId	null	Legacy 未设置，Unified 可补充

---

13. Projector 原子性契约（冻结）

13.1 事务边界

同一 $transaction 内：

1. AiAnalysisResult    — upsert (deterministic ID)
2. FocusItem           — findFirst + create (per weakness) 或 skipDuplicates
3. AiJobArtifact       — create (×2: analysis_result, focus_item)
   ★ ReviewCard 不在事务内（方案 A）
4. Job.validatedOutput — update
5. Job.outputHash      — update
6. Job.lifecycleStatus — update → 'succeeded'
7. Job.finishedAt      — update

13.2 失败回滚

失败步骤	预期结果
Result upsert 失败	事务回滚 — 无任何产物
FocusItem 创建失败	事务回滚 — Result 不保留
Artifact 创建失败	事务回滚 — Result + FocusItem 不保留
Job update 失败	事务回滚 — 全部业务产物不保留
重复执行 Projector	入口幂等检查 — 已有 Artifact → 直接返回已有引用
ReviewCard 生成失败	不影响主链路（异步 EventBus）

---

14. 入口兼容契约（冻结）

14.1 请求

POST /api/ai-analysis/feynman
Content-Type: application/json
Authorization: Bearer <JWT>

Body (不变):
{
  "knowledgeItemTitle": "string",    // 必填
  "knowledgeItemContent": "string",  // 必填
  "userExplanation": "string",       // 必填
  "sessionId?": "string",            // 可选
  "answerId?": "string"              // 可选
}

14.2 响应

Legacy 模式（不变）：

{
  "jobId": "cuid...",
  "status": "queued"
}

Unified 模式（兼容扩展）：

{
  "jobId": "cuid...",
  "status": "queued",
  "engineMode": "unified",       // 新增可选字段
  "lifecycleStatus": "queued"    // 新增可选字段
}

14.3 状态码

场景	HTTP 状态	响应
正常提交	201	{ jobId, status }
参数缺失	400	{ message, error }
未认证	401	{ message, error }
重复提交	200	返回已有 Job 信息
Unified 创建失败	500	{ message, errorCode } — 不自动 fallback Legacy

---

15. 回滚流程（冻结）

unified → legacy 切换步骤：

1. 修改 FEYNMAN_ENGINE_MODE=legacy（或 Feature Flag 切回）
2. 重启 API Process（或热加载 Feature Flag）
3. 验证：
   a. 新请求走 Legacy（检查日志）
   b. 已创建的 Unified Job 继续完成（Worker 日志不中断）
   c. 同一 submission 不重新进入 Legacy
   d. 客户端查询旧/新 Job 均正常
4. 不需要：
   a. 数据库回滚
   b. 删除 Unified 产物
   c. 清理 Outbox 事件
   d. 重启 Worker

---

16. 不确定项

编号	不确定项	影响	建议
U-1	submissionId 来源 — 客户端是否传入？是否用 sessionId + answerId 组合？	幂等键设计	优先使用 sessionId + answerId（如都存在）；否则服务端生成 cuid 作为 submissionId
U-2	knowledgeItemId 来源 — 请求体当前不包含此字段，需要从 knowledgeItemTitle + knowledgeItemContent 匹配？还是客户端传入？	Snapshot 完整性	需要客户端新增 knowledgeItemId 字段，或在服务端通过标题+内容匹配
U-3	blindSpots 字段当前未被消费 — 是否需要保留？	Schema 冻结	保留（不删除已有 Schema 字段），但不为其创建 FocusItem
U-4	Feature Flag 机制 — 项目是否已有 FeatureFlagService？还是使用环境变量？	入口路由实现	检查 M0-03 是否已实现；优先复用已有机制
U-5	Legacy Feynman 的 BullMQ Job 重试次数是 3 — Unified 是否保持一致？	Job 可靠性	在 Definition 中设置 attempts: 3
U-6	ReviewCard 生成的 tier: 'cheap' 在 Unified 链路的 EventBus 中是否保持一致？	成本	保持 tier: 'cheap'
U-7	FocusItem 的 knowledgeBaseId 修复（从 'unknown' 改为真实值）是否会影响现有业务查询？	数据兼容	影响极小（当前值始终为 'unknown'）；Fix 后 UI 可按 knowledgeBaseId 筛选

---

17. 附录：相关文件索引

文件路径	关键类/函数	行号
src/modules/ai-analysis/ai-analysis.controller.ts	AiAnalysisController.evaluateFeynman()	29-43
src/modules/ai-analysis/ai-analysis.service.ts	AiAnalysisService.evaluateFeynman()	33-52
src/modules/ai-analysis/ai-analysis.repository.ts	AiAnalysisRepository.createJob()	17-33
src/modules/ai-analysis/ai-analysis.repository.ts	AiAnalysisRepository.updateJobStatus()	35-46
src/modules/ai-analysis/ai-analysis.repository.ts	AiAnalysisRepository.createResult()	55-69
src/modules/ai-analysis/ai-analysis.repository.ts	STATUS_TO_LIFECYCLE 映射表	10-15
src/workers/ai-analysis.worker.ts	AiAnalysisWorker.process()	32-105
src/workers/ai-analysis.worker.ts	FocusItem 创建循环	85-96
src/workers/ai-analysis.worker.ts	AIAnalysisCompleted 事件发布	72-81
src/modules/ai/workflows/feynman-evaluation.workflow.ts	FeynmanEvaluationWorkflow.execute()	17-44
src/modules/ai/prompts/feynman-evaluation.prompt.ts	FEYNMAN_EVALUATION_SYSTEM_PROMPT	1-31
src/modules/ai/prompts/schemas/feynman-evaluation.schema.ts	FeynmanEvaluationResultSchema	3-14
src/modules/ai/prompts/prompt-template.service.ts	Feynman prompt 注册	33-38
src/modules/ai/gateway/ai-gateway.service.ts	AiGatewayService.generate()	40-110
src/modules/ai/model-router.ts	ModelRouter.resolve()	70+
src/modules/review/review-card.subscriber.ts	ReviewCardSubscriber.handleAIAnalysisCompleted()	12-51
src/modules/review/review.service.ts	ReviewService.generateCards()	68-98
src/modules/review/review.repository.ts	ReviewRepository.insertCard()	24-39
src/modules/focus-items/focus-items.service.ts	FocusItemsService.create()	12
src/modules/focus-items/focus-items.repository.ts	FocusItemsRepository.create()	23-47
src/modules/ai-job/active-recall-projector.ts	ActiveRecallProjector.project() (参考)	37-202
src/modules/ai-job/ai-job-creation.service.ts	AiJobCreationService.create() (参考)	50+
src/infrastructure/queue/queue.service.ts	QueueService.add()	47+
src/infrastructure/queue/queue.constants.ts	QUEUE_AI_ANALYSIS = 'ai-analysis'	1
src/infrastructure/queue/queue-definitions.ts	Queue 配置	97+
prisma/schema.prisma	AiJob (AiAnalysisJob)	568-639
prisma/schema.prisma	AiAnalysisResult	679-701
prisma/schema.prisma	FocusItem	703-729
prisma/schema.prisma	ReviewCard	731-757
prisma/schema.prisma	AiJobArtifact	663-677