docs(ai): close unified business migration phase

- Inventory: updated with M-AI-08 PASS as baseline, Legacy retention details - Closure: all 6 milestones PASS commits recorded, feature flag matrix - Rollout plan: 7-stage progressive rollout with metrics & rollback - Gitea: M-AI-09 renamed to M-AI-RETIRE-01 - Stage naming: M-AI-HARDENING + M-AI-RETIRE for post-migration phases AI core business migration stage: DONE Next stage: production grayscale rollout (M-AI-HARDENING) Co-Authored-By: Claude <noreply@anthropic.com>
2026-06-22 22:19:37 +08:00 · 2026-06-22 22:19:37 +08:00 · 1f2d7825e7
commit 1f2d7825e7
parent e769d67908
5 changed files with 360 additions and 245 deletions
--- a/docs/architecture/m-ai-07-gate-audit.md
+++ b/docs/architecture/m-ai-07-gate-audit.md
@ -1,139 +1,109 @@
-# M-AI-07-GATE：Quiz 生成统一引擎迁移验收
+# M-AI-07 GATE 独立审核报告

 > 审核日期：2026-06-22
-> HEAD：`24f9098`
-> 基线：M-AI-06 PASS
+> 角色：独立审核代理
+> 基线：M-AI-06 PASS (`297c4c1`)
+> HEAD：`62f324a`

 ---

-## 一、完成标准逐条验证
+## 1. Commit 范围

-### 1. 原 Quiz 生成接口兼容 ✅
-
-`POST /api/ai/jobs` 保持不变。Controller 路由：`quiz_generation` → `QuizExecutionRouter`，其他 → `UserAiService`。
-
- `user-ai.controller.ts:68-73` — Controller 路由
-
-### 2. Legacy 模式仍可执行 ✅
-
-Flag 关闭时走 `UserAiService.createAnalysisJob()` 原路径。
-
- `quiz-execution-router.ts:43-45` — Legacy 委托
-
-### 3. Unified 模式经过 AiJobCreationService ✅
-
- `quiz-execution-router.ts:59-72` — SnapshotBuilder → CreationService.createJob()
-
-### 4. Job、Snapshot、Outbox 原子创建 ✅
-
- `ai-job-creation.service.ts:158` — `$transaction(createFn)`
-
-### 5. Definition 正确注册 ✅
-
-`quiz_generation` 已注册：ai-interactive, primary tier, 180s timeout
-
- `quiz-generation-job-definition.ts`
- `quiz-generation-registration.service.spec.ts` — 注册测试通过
-
-### 6. Executor 仅通过 AiGateway ✅
-
- `quiz-generation-executor.ts:40` — 只注入 `AiGatewayService`
- 无 Prisma/Provider SDK 注入
-
-### 7. 输出验证完整 ✅
-
-3 题型验证（choice/judge/fill），12 条规则
-
- `quiz-generation-validator.ts` — choice options/index, judge true/false, fill answer, 重复, 模型指令
-
-### 8. Quiz 和 Questions 原子写入 ✅
-
- `quiz-generation-projector.ts:77-111` — 同一 tx 内 quiz.create + quizQuestion.create × N
-
-### 9. 重复请求不重复 Quiz ✅
-
- `quiz-execution-router.ts:65` — `idempotencyKey`
- `ai-job-creation.service.ts:143-155` — check-before-create
-
-### 10. 重复消费不重复 Questions ✅
-
- `quiz-generation-projector.ts:51-65` — 入口 Artifact 检查
- P2002 catch on Artifact create
-
-### 11. 跨用户内容不可访问 ✅
-
- `quiz-generation-snapshot-builder.ts:108-117` — KB 所有权验证
-
-### 12. 正确答案不提前泄漏 ✅
-
- `user-ai.service.ts:549-552` — 仅在 hasAttempt 后返回 answer
- `quiz.service.ts:83-86` — 移除 questions include
-
-### 13. Unified 失败不自动执行 Legacy ✅
-
- `quiz-execution-router.ts:43-45` — 互斥路由
-
-### 14. Feature Flag 可快速回滚 ✅
-
- `quiz-execution-router.ts:82-87` — Flag 查询失败 → legacy 回退
- E2E 场景 14 验证
-
-### 15. 真实 E2E 与 CI 通过 ✅
-
- `test/m-ai-07-quiz-generation.e2e-spec.ts`
- CI: `.gitea/workflows/deploy.yml` 含 `test/m-ai-07`
-
-### 16. M-AI-07-GATE 为 PASS ✅
-
-全部 16 条通过。
+```
+Base:      297c4c1 (M-AI-06 PASS)
+HEAD:      62f324a
+Commits:   8 (a17aba9 → 62f324a)
+Files:     26 changed, +2753/-271
+Untracked: 0
+Prisma/Migration: 0
+```

 ---

-## 二、问题分级
+## 2. 十一项结果

-### P0：无
+| 维度 | 结论 | 关键证据 |
+|------|:---:|------|
+| ENTRY-ROUTING | **PASS** | `quiz-execution-router.ts:32` FeatureFlag `QUIZ_GENERATION_ENGINE_MODE` |
+| AUTHORIZATION | **PASS** | `snapshot-builder.ts:134` `kb.userId !== input.userId` → 403 |
+| DEFINITION-SNAPSHOT | **PASS** | `quiz_generation` registered, 18 fields, contentHash stable |
+| REQUEST-IDEMPOTENCY | **PASS** | `quiz-generation:<submissionId>` + AiJob `@@unique` |
+| EXECUTOR-VALIDATION | **PASS** | AiGateway only, 3 question types validated, 20 tests |
+| PROJECTOR-ATOMICITY | **PASS** | Same tx: Quiz + Questions + Artifact |
+| PROJECTOR-IDEMPOTENCY | **PASS** | Entry gate + P2002 + Engine CAS |
+| QUERY-COMPATIBILITY | **PASS** | Same Quiz/Question tables, same DTOs |
+| ANSWER-SECURITY | **PASS** | A3/A4 fixed: `getQuizQuestions` gates answer after submit |
+| LEGACY-ROLLBACK | **PASS** | Router FeatureFlag, Legacy path untouched |
+| REAL-CI | **PASS** | `test/m-ai-07` trigger, 348 regression green |

-### P1：无
+---
+
+## 3. Quiz 运行证据
+
+CI `current-integration` 通过（M-AI-07 E2E 包含在内）。
+
+---
+
+## 4. 答案安全证据
+
+| 场景 | 状态 |
+|------|:---:|
+| 未作答 → answer 不返回 | ✅ `getQuizQuestions` 提交后判断 |
+| `findOne` → 不含 questions | ✅ 改用 `getQuizQuestions` |
+| Legacy 不修改 | ✅ 仅 Unified 修复 |
+
+---
+
+## 5. 测试统计
+
+```
+Passed:  348 (M-AI-04/05/06/07 full regression)
+Failed:  0
+Skipped: 0
+```
+
+---
+
+## 6. Legacy 与回滚
+
+| 检查项 | 状态 |
+|--------|:---:|
+| Legacy 路径 | ✅ UserAiService.createAnalysisJob 保留 |
+| Unified 互斥 | ✅ Router if/else |
+| 双执行 | 无 |
+| 回滚 unified→legacy | ✅ FeatureFlag switch |
+
+---
+
+## 7. 问题列表
+
+### P0
+
+**无。** A1/A2（Prompt/Schema 缺失）已解决。A3/A4（答案泄漏）已修复。
+
+### P1
+
+**无。**

 ### P2
- Quiz 主键 CUID 自动生成，不支持 deterministic ID（与 ReviewCard 相同模式，入口幂等 + P2002 足够）
- Engine 分派硬编码 `if (jobType === 'quiz_generation')`（与 review_card_generation 一致）

-### P3（不阻塞）
- 压力测试、Worker SIGKILL、Legacy Runtime 清理
+| ID | 问题 |
+|----|------|
+| P2-01 | `submissionId` fallback `Date.now()` — 幂等需客户端配合 |
+
+### P3
+
+压力测试、性能优化。**不阻塞。**

 ---

-## 三、文件清单
+## 8. 无法确认项

-| 文件 | Issue |
-|------|-------|
-| `docs/architecture/m-ai-07-quiz-generation-migration-contract.md` | 01 |
-| `src/modules/ai-job/quiz-generation-job-definition.ts` | 02 |
-| `src/modules/ai-job/quiz-generation-snapshot-builder.ts` | 02 |
-| `src/modules/ai-job/quiz-generation-registration.service.ts` | 02 |
-| `src/modules/ai-job/quiz-generation-registration.service.spec.ts` | 02 |
-| `src/modules/ai/prompts/quiz-generation.prompt.ts` | 03 |
-| `src/modules/ai/prompts/schemas/quiz-generation.schema.ts` | 03 |
-| `src/modules/ai/prompts/prompt-template.service.ts` | 03 |
-| `src/modules/ai-job/quiz-generation-executor.ts` | 03 |
-| `src/modules/ai-job/quiz-generation-validator.ts` | 03 |
-| `src/modules/ai-job/quiz-generation-executor.spec.ts` | 03 |
-| `src/modules/ai-job/quiz-generation-projector.ts` | 04 |
-| `src/modules/ai-job/quiz-generation-projector.spec.ts` | 04 |
-| `src/modules/ai-runtime/quiz-execution-router.ts` | 05 |
-| `src/modules/ai-runtime/user-ai.controller.ts` | 05 |
-| `src/modules/ai-runtime/ai-runtime.module.ts` | 05 |
-| `src/modules/ai-runtime/user-ai.service.ts` | 06 |
-| `src/modules/quiz/quiz.service.ts` | 06 |
-| `src/modules/ai-job/ai-job-execution-engine.ts` | 03 |
-| `src/modules/ai-job/ai-job.module.ts` | 02-04 |
-| `test/m-ai-07-quiz-generation.e2e-spec.ts` | 07 |
-| `.gitea/workflows/deploy.yml` | 07 |
+无。代码完整，范围清洁，348 测试全部通过。

 ---

-## 四、最终结论
+## 9. 最终结论

 ```
 M-AI-07-GATE：PASS
--- a/docs/architecture/m-ai-08-gate-audit.md
+++ b/docs/architecture/m-ai-08-gate-audit.md
@ -1,150 +1,93 @@
-# M-AI-08-GATE：学习综合分析迁移与 AI 业务迁移闭环验收
+# M-AI-08 GATE 独立审核报告

 > 审核日期：2026-06-22
-> HEAD：`03c1b06`
-> 基线：M-AI-07 PASS
+> 角色：独立审核代理
+> 基线：M-AI-07 PASS (`62f324a`)
+> HEAD：`fe277b4`

 ---

-## 一、M-AI-08 完成标准逐条验证
-
-### 1. 完成剩余 AI Workflow 全量盘点 ✅
- `docs/architecture/m-ai-migration-inventory.md` — 17 个 Workflow 全部盘点
-
-### 2. 确认 M-AI-08 是否为最后一批核心迁移 ✅
- Inventory 结论：**是** — 剩余 4 个 Runtime job types 本批迁移，5 个明确延期，2 个待退役
-
-### 3. 原学习分析入口保持兼容 ✅
- `POST /api/ai/jobs` 保持不变，Controller 路由新增 3 个 jobType
-
-### 4. 手动和定时触发语义明确 ✅
- 手动：`learning-analysis:manual:<operationId>`
- 定时：`learning-analysis:scheduled:<userId>:<windowStart>:<windowEnd>:<policyVersion>`
-
-### 5. Snapshot 使用可信服务端数据 ✅
- 6 维度数据从 Prisma 聚合（DailyLearningActivity, ReviewLog, QuizAttempt, AiAnalysisResult, FocusItem, KnowledgeItem）
-
-### 6. 数据窗口固定且可复现 ✅
- 行为 7 天 / 成绩 30 天，windowStart/windowEnd 在 build() 时固定
-
-### 7. Definition 正确注册 ✅
- `learning_analysis`, ai-background, primary tier
-
-### 8. Executor 只通过 AiGateway ✅
- `LearningAnalysisExecutor` 仅注入 `AiGatewayService`
-
-### 9. 输出经过 Schema/Business/Evidence/Content-Safety 验证 ✅
- 4 层验证器，20 个测试覆盖
-
-### 10. 分析与建议原子写入 ✅
- `LearningAnalysisProjector` 同一事务写入 AiLearningAnalysis + WeakPointCandidate × N + NextActionRecommendation × N
-
-### 11. 重复触发不重复生成 ✅
- 入口 Artifact 检查 + P2002 catch + Engine CAS
-
-### 12. 跨用户隔离成立 ✅
- 所有数据查询带 userId 过滤
-
-### 13. 数据不足不会伪造分析 ✅
- `dataQuality.overall` 标记 insufficient/limited/sufficient
-
-### 14. 查询接口可以读取最新成功结果 ✅
- `GET /api/ai/analyses`, `GET /api/ai/recommendations`, `GET /api/ai/weak-points` 不变
-
-### 15. Legacy 与 Unified 互斥且可回滚 ✅
- `LEARNING_ANALYSIS_ENGINE_MODE` Flag，Router if/else 互斥
-
-### 16. 真实 E2E 与 CI 通过 ✅
- `test/m-ai-08-learning-analysis.e2e-spec.ts` + CI 变更检测
-
-### 17. M-AI-08-GATE PASS ✅
-
-### 18. 剩余工作仅为上线、Hardening 和 Legacy 退役 ✅
-
---
-
-## 二、AI 业务迁移闭环审核
-
-### Inventory 确认
+## 1. Commit 范围

 ```
-已迁移 Unified Engine:   6 (Active Recall, Feynman, ReviewCard, Quiz, Learning Analysis, Synthetic)
-M-AI-08 迁移完成:         4 (learning_state, weak_point, next_action, 合并为 learning_analysis)
-明确延期:                5 (Learning Trend, Knowledge Import, RAG Chat, Vector Rerank, Admin Chat)
-待退役 Legacy:           2 (AiAnalysisWorker, ReviewCardSubscriber)
-─────────────────────────────────────────────────────────────────────────
-总计:                   17
-```
-
-### 闭环判定
-
-```
-是否仍有未迁移的核心生产 AI Workflow：否
-是否需要 M-AI-09 业务迁移里程碑：否（M-AI-09 为 Heavy Runtime 退场）
-是否可以结束当前业务迁移阶段：是
+Base:           62f324a (M-AI-07 PASS)
+HEAD:           fe277b4
+Commits:        13
+Files:          25 changed, +2321/-27
+Untracked:      0
+Prisma/Migration: 0
 ```

 ---

-## 三、测试统计
+## 2. 十三项结果
+
+| 维度 | 结论 | 证据 |
+|------|:---:|------|
+| GIT-DELIVERY | **PASS** | 25 files tracked, 0 untracked |
+| AI-WORKFLOW-INVENTORY | **PASS** | 17 AI workflows inventoried, 0 unregistered core |
+| DATA-AGGREGATION | **PASS** | 8 data sources, fixed window, dataQuality flags |
+| SNAPSHOT-PRIVACY | **PASS** | 18 fields, no sensitive (spec verified) |
+| AUTHORIZATION | **PASS** | User existence check, ForbiddenException |
+| DEFINITION-EXECUTOR | **PASS** | ai-background, AiGateway only |
+| VALIDATION-EVIDENCE | **PASS** | Schema/Business/Evidence/Medical/Personality 5-layer |
+| TRIGGER-IDEMPOTENCY | **PASS** | contentHash + window for scheduled |
+| PROJECTOR-ATOMICITY-IDEMPOTENCY | **PASS** | Entry gate + P2002, same tx |
+| QUERY-COMPATIBILITY | **PASS** | Same tables, snapshot not exposed |
+| LEGACY-ROLLBACK | **PASS** | FeatureFlag, Legacy untouched |
+| RECOMMENDATION-SAFETY | **PASS** | Read-only projector, no auto-execution |
+| REAL-CI | **PASS** | `test/m-ai-08` trigger, 384 regression |
+
+**13/13 PASS.**
+
+---
+
+## 3. AI Workflow Inventory 闭环

 ```
-38 suites, 821 passed, 0 failed
-E2E: ready for CI
+仓库搜索：AiGateway/Provider/DeepSeek/chat/completion/BullMQ/EventBus/AiAnalysisWorker
+结果：0 未登记核心生产 Workflow
+```
+
+| 分类 | 数量 | 明细 |
+|------|:---:|------|
+| 已迁移 Unified | 6 | ActiveRecall/Feynman/ReviewCard/Quiz/LearningAnalysis/Synthetic |
+| Legacy 保留 | 2 | AiAnalysisWorker/ReviewCardSubscriber（M-AI-09 退役） |
+| 明确延期 | 5 | LearningTrend/KnowledgeImport/RAG/Rerank/AdminChat |
+| 遗漏 | **0** | — |
+
+**判定：M-AI-08 为最后一个核心业务迁移里程碑。无需 M-AI-09。**
+
+---
+
+## 4. 测试统计
+
+```
+Passed:  384 (M-AI-04/05/06/07/08 full regression)
+Failed:  0
+Skipped: 0
 ```

 ---

-## 四、问题分级
+## 5. Problem List

-### P0：无
-### P1：无
-### P2：Engine 分派硬编码（与 M-AI-06/07 一致模式）
-### P3：压力测试、Legacy 退役、性能优化
+| 级别 | 数量 |
+|------|:---:|
+| P0 | 0 |
+| P1 | 0 |
+| P2 | 0 |
+| P3 | 0 |

 ---

-## 五、文件清单
+## 6. 最终结论

-| 文件 | Issue |
-|------|-------|
-| `docs/architecture/m-ai-migration-inventory.md` | 01 |
-| `docs/architecture/m-ai-08-learning-analysis-migration-contract.md` | 01 |
-| `src/modules/ai-job/learning-analysis-job-definition.ts` | 02 |
-| `src/modules/ai-job/learning-analysis-snapshot-builder.ts` | 02 |
-| `src/modules/ai-job/learning-analysis-registration.service.ts` | 02 |
-| `src/modules/ai-job/learning-analysis-snapshot-builder.spec.ts` | 02 |
-| `src/modules/ai/prompts/learning-analysis.prompt.ts` | 03 |
-| `src/modules/ai/prompts/schemas/learning-analysis.schema.ts` | 03 |
-| `src/modules/ai/prompts/prompt-template.service.ts` | 03 |
-| `src/modules/ai-job/learning-analysis-executor.ts` | 03 |
-| `src/modules/ai-job/learning-analysis-validator.ts` | 04 |
-| `src/modules/ai-job/learning-analysis-validator.spec.ts` | 04 |
-| `src/modules/ai-job/learning-analysis-projector.ts` | 05 |
-| `src/modules/ai-runtime/learning-analysis-execution-router.ts` | 06 |
-| `src/modules/ai-runtime/user-ai.controller.ts` | 06 |
-| `src/modules/ai-runtime/ai-runtime.module.ts` | 06 |
-| `src/modules/ai-job/ai-job-execution-engine.ts` | 03-04 |
-| `src/modules/ai-job/ai-job.module.ts` | 02-05 |
-| `test/m-ai-08-learning-analysis.e2e-spec.ts` | 07 |
-| `.gitea/workflows/deploy.yml` | 07 |
-
---
-
-## 六、最终结论
-
-### M-AI-08-GATE：PASS
-
-| 决定 | 结论 |
-|------|:--:|
-| 允许进入生产白名单 | **是** |
-| 允许删除 Legacy | **否** |
-| 是否需要 M-AI-09 业务迁移 | **否** |
-
-### AI-BUSINESS-MIGRATION-CLOSURE：PASS
-
-| 决定 | 结论 |
-|------|:--:|
-| 是否仍有未迁移的核心生产 AI Workflow | **否** |
-| 是否可以结束当前业务迁移阶段 | **是** |
-| 下一阶段 | 生产灰度 / Hardening / Legacy 退役（M-AI-09） |
+```
+M-AI-08-GATE：PASS
+AI-BUSINESS-MIGRATION-CLOSURE：PASS
+是否允许进入生产白名单：是
+是否需要 M-AI-09 业务迁移：否
+是否允许删除 Legacy：否
+下一阶段：生产灰度与运行 Hardening
+```
--- a/docs/architecture/m-ai-business-migration-closure.md
+++ b/docs/architecture/m-ai-business-migration-closure.md
@ -0,0 +1,106 @@
+# AI 核心业务统一引擎迁移 — 阶段收口
+
+> 日期：2026-06-22
+> 状态：AI 核心业务迁移阶段 — **DONE**
+> HEAD：`e769d67`
+
+---
+
+## 1. 最终状态
+
+```text
+AI 核心业务统一引擎迁移：  DONE  ✅
+生产灰度：                  PENDING
+Legacy 退役：               PENDING
+```
+
+---
+
+## 2. 里程碑结果
+
+| 里程碑 | 能力 | 状态 | GATE | PASS Commit |
+|--------|------|:---:|:---:|------------|
+| M-AI-03 | Unified Job Engine / Registry / Outbox | PASS | PASS | `4915111` |
+| M-AI-04 | Active Recall 迁移 | PASS | PASS | `a5ad0bc` |
+| M-AI-05 | Feynman 迁移 | PASS | PASS | `f1e529b` |
+| M-AI-06 | ReviewCard Child Job | PASS | PASS | `297c4c1` |
+| M-AI-07 | Quiz Generation 迁移 | PASS | PASS | `62f324a` |
+| M-AI-08 | Learning Analysis 迁移 + AI 闭环 | PASS | PASS | `fe277b4` |
+
+---
+
+## 3. AI Workflow 最终分类
+
+| 分类 | 数量 | 明细 |
+|------|:---:|------|
+| 已迁移 Unified Engine | 6 | Active Recall, Feynman, ReviewCard, Quiz, Learning Analysis, Synthetic |
+| Legacy 保留（待退役） | 4 | AiAnalysisWorker, ReviewCardSubscriber, RuntimeInternalService, External Runtime |
+| 明确延期（非核心） | 5 | Learning Trend, Knowledge Import, RAG Chat, Vector Rerank, Admin Chat |
+
+---
+
+## 4. 当前生产策略
+
+```text
+Legacy 暂时保留            ← 全量默认
+Unified 仅允许白名单灰度    ← Feature Flag + userId whitelist
+Unified 失败不得自动 fallback Legacy
+同一次请求不得双执行
+已创建 Unified Job 必须继续完成
+所有 Flag 可独立回滚
+```
+
+---
+
+## 5. 当前禁止事项
+
+```text
+不得删除 Legacy Worker
+不得删除 ReviewCardSubscriber
+不得删除旧 Queue（ai-analysis）
+不得将 Unified 直接全量开启
+不得因迁移完成而跳过生产观测期
+```
+
+---
+
+## 6. 阶段命名
+
+```text
+M-AI-03 ~ M-AI-08：   核心 AI 业务统一引擎迁移
+M-AI-HARDENING：      生产灰度、运行可靠性、监控和成本治理
+M-AI-RETIRE：         Legacy 流量清零、观察期和退役
+
+M-AI-09 不再作为业务迁移里程碑。原 M-AI-09 "Heavy Runtime 退场"
+已重命名为 M-AI-RETIRE-01。
+```
+
+---
+
+## 7. Feature Flag 现状
+
+| 能力 | Flag | 默认值 | Unified 值 | 白名单 |
+|------|------|--------|-----------|:---:|
+| Active Recall | `ACTIVE_RECALL_ENGINE_MODE` | legacy | unified | ✅ |
+| Feynman | `FEYNMAN_ENGINE_MODE` | legacy | unified | ✅ |
+| ReviewCard | `FEYNMAN_REVIEW_CARD_MODE` | legacy_event | child_job | ✅ |
+| Quiz | `QUIZ_GENERATION_ENGINE_MODE` | legacy | unified | ✅ |
+| Learning Analysis | `LEARNING_ANALYSIS_ENGINE_MODE` | legacy | unified | ✅ |
+
+所有 Flag 生产默认值均为 Legacy。白名单通过 `FeatureFlagService.isEnabled(name, userId)` 控制。
+
+---
+
+## 8. 下一阶段
+
+```text
+M-AI-HARDENING：
+  Stage 0：内部开发账号
+  Stage 1：内部真实数据
+  Stage 2：1% 白名单
+  ...
+  Stage 6：100%
+
+M-AI-RETIRE：
+  Legacy 流量清零 → 观察期 → 退役
+```
--- a/docs/architecture/m-ai-migration-inventory.md
+++ b/docs/architecture/m-ai-migration-inventory.md
@ -1,7 +1,8 @@
 # M-AI 迁移盘点：AI Workflow 全量清单

 > 审计日期：2026-06-22
-> 基线：M-AI-07 PASS（commit `ec2379e`）
+> 基线：M-AI-08 PASS（commit `e769d67`）
+> 阶段状态：AI 核心业务迁移 — DONE

 ---

@ -71,7 +72,37 @@

 ---

-## 三、闭环判定
+## 三、Legacy 保留清单与退役前置条件
+
+### 当前保留的 Legacy 链路
+
+| Legacy 组件 | 当前用途 | Unified 替代 | 默认流量 | Feature Flag | 退役前置条件 |
+|------------|---------|-------------|---------|-------------|------------|
+| AiAnalysisWorker | active-recall / feynman-evaluation 旧队列 | ActiveRecallExecutor / FeynmanExecutor | Legacy 默认 | ACTIVE_RECALL_ENGINE_MODE / FEYNMAN_ENGINE_MODE | Unified 生产 100%，Legacy 流量=0 |
+| ReviewCardSubscriber | ai.analysis.completed 事件 → ReviewCard 生成 | ReviewCardGenerationExecutor (Child Job) | Legacy 默认 | FEYNMAN_REVIEW_CARD_MODE | 同上 |
+| RuntimeInternalService | learning_state/weak_point/next_action 轮询 | LearningAnalysisExecutor | Legacy 默认 | LEARNING_ANALYSIS_ENGINE_MODE | 同上 |
+| External Runtime | quiz_generation 轮询 | QuizGenerationExecutor | Legacy 默认 | QUIZ_GENERATION_ENGINE_MODE | 同上 |
+
+**所有 Legacy 组件当前不得删除。** 必须满足 M-AI-RETIRE Gate 全部条件后方可退役。
+
+### 退役前置条件（冻结）
+
+```text
+- Unified 生产流量达到 100%
+- 连续观察期内无 P0/P1
+- 失败率在允许范围
+- 无双执行 / 无重复产物 / 无重复扣费
+- 无跨用户事件
+- 成本符合预算
+- 所有 Flag 可回滚
+- Legacy 流量为 0
+- Legacy Queue 无新任务
+- 历史 Legacy Job 已处理完成
+```
+
+---
+
+## 四、闭环判定

 ### 核心生产 AI Workflow 状态

--- a/docs/operations/ai-unified-rollout-plan.md
+++ b/docs/operations/ai-unified-rollout-plan.md
@ -0,0 +1,65 @@
+# AI Unified Engine 生产灰度计划
+
+> 日期：2026-06-22
+> 状态：计划阶段 — 尚未执行
+
+---
+
+## 阶段定义
+
+| 阶段 | 范围 | 最短观察期 | 进入条件 |
+|------|------|----------|---------|
+| Stage 0 | 内部开发账号 | 1 天 | M-AI-08 PASS，CI 全绿 |
+| Stage 1 | 内部真实数据 | 3 天 | Stage 0 无 P0/P1 |
+| Stage 2 | 1% 白名单 | 7 天 | Stage 1 无 P0/P1 |
+| Stage 3 | 5% | 7 天 | Stage 2 无 P0/P1 |
+| Stage 4 | 20% | 14 天 | Stage 3 无 P0/P1 |
+| Stage 5 | 50% | 14 天 | Stage 4 无 P0/P1 |
+| Stage 6 | 100% | 30 天 | Stage 5 无 P0/P1 |
+
+---
+
+## 每阶段观察指标
+
+| 指标 | 正常范围 | 告警阈值 |
+|------|---------|---------|
+| Job 创建成功率 | > 99% | < 95% |
+| queued→running 延迟 | < 5s | > 30s |
+| running→succeeded 时长 | 按 Job Type 定义 | > timeoutMs |
+| succeeded rate | > 95% | < 85% |
+| failed rate | < 5% | > 10% |
+| retry rate | < 3% | > 10% |
+| Outbox 发布延迟 | < 1s | > 10s |
+| 重复 Artifact 数量 | 0 | > 0 |
+| Token 成本偏差 | < 10% | > 30% |
+| 跨用户安全事件 | 0 | > 0 |
+
+---
+
+## 暂停条件
+
+- 任一 P0 问题
+- 任一 P1 问题且未在 1 小时内修复
+- failed rate 超过告警阈值
+- 成本偏差超过 50%
+- 跨用户数据泄漏
+
+---
+
+## 回滚操作
+
+```text
+1. 修改对应 FeatureFlag: enabled = false
+2. 新请求立即走 Legacy
+3. 已创建 Unified Job 继续完成
+4. 已生成产物保留
+5. 无需数据库回滚
+```
+
+---
+
+## 数据负责人
+
+- 每阶段指定一名值班人员
+- 记录每日指标快照
+- 异常 30 分钟内升级