diff --git a/docs/architecture/m-ai-07-gate-audit.md b/docs/architecture/m-ai-07-gate-audit.md index f171c15..b4095e7 100644 --- 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:` + 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 diff --git a/docs/architecture/m-ai-08-gate-audit.md b/docs/architecture/m-ai-08-gate-audit.md index e6abcac..6beddbc 100644 --- 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:` -- 定时：`learning-analysis:scheduled::::` - -### 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 +``` diff --git a/docs/architecture/m-ai-business-migration-closure.md b/docs/architecture/m-ai-business-migration-closure.md new file mode 100644 index 0000000..6e21c81 --- /dev/null +++ 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 流量清零 → 观察期 → 退役 +``` diff --git a/docs/architecture/m-ai-migration-inventory.md b/docs/architecture/m-ai-migration-inventory.md index 7676492..1fa1d47 100644 --- 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 状态 diff --git a/docs/operations/ai-unified-rollout-plan.md b/docs/operations/ai-unified-rollout-plan.md new file mode 100644 index 0000000..850b78c --- /dev/null +++ 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 分钟内升级