api-server/docs/architecture/m-ai-migration-inventory.md

M-AI 迁移盘点：AI Workflow 全量清单

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

---

一、全量 AI Workflow 清单

#	Workflow	公开入口	模型调用方	当前执行方式	已迁移	里程碑	后续处理
1	Active Recall 分析	POST /ai-analysis / POST /active-recalls/:id/submit	ActiveRecallExecutor / AiAnalysisWorker	Unified Engine + 旧 Worker 双路径	✅	M-AI-04	旧 Worker 待退役
2	Feynman 评估	POST /ai-analysis/feynman	FeynmanExecutor / AiAnalysisWorker	Unified Engine + 旧 Worker 双路径	✅	M-AI-05	旧 Worker 待退役
3	ReviewCard 生成	POST /ai/analysis/feynman（子Job）	ReviewCardGenerationExecutor / ReviewCardGenerationWorkflow	Unified Child Job + Legacy EventBus 双路径	✅	M-AI-06	旧 Subscriber 待退役
4	Quiz 生成	POST /api/ai/jobs（jobType=quiz_generation）	QuizGenerationExecutor / 外部 Runtime	Unified Engine + 旧 Runtime 轮询双路径	✅	M-AI-07	旧 Runtime 待退役
5	学习状态分析	POST /api/ai/jobs（jobType=learning_state_analysis）	外部 Runtime	旧 Runtime 轮询 → aiRuntimeJob 表	❌	M-AI-08	本批迁移
6	薄弱点分析	POST /api/ai/jobs（jobType=weak_point_analysis）	外部 Runtime	旧 Runtime 轮询 → aiRuntimeJob 表	❌	M-AI-08	本批迁移
7	下一步行动规划	POST /api/ai/jobs（jobType=next_action_planning）	外部 Runtime	旧 Runtime 轮询 → aiRuntimeJob 表	❌	M-AI-08	本批迁移
8	闪卡生成	POST /api/ai/jobs（jobType=flashcard_generation）	外部 Runtime	旧 Runtime 轮询 → Flashcard	❌	M-AI-08	本批迁移
9	学习趋势分析	GET /api/activity/trend	LearningTrendWorkflow → AiGateway	Legacy Workflow 直接调用 AiGateway	❌	延期	非核心首版功能
10	知识导入	POST /api/knowledge-bases/:kbId/items/import	KnowledgeImportWorkflow → AiGateway	Legacy Workflow 直接调用 AiGateway	❌	延期	非核心首版功能
11	RAG 聊天	WebSocket / POST /api/rag-chat	RagChatService → AiGateway	独立服务，不在 Job Engine 中	❌	延期	独立系统，非 Job 模型
12	向量 Rerank	内部（RAG 管道）	VectorService → AiGateway	独立服务调用	❌	延期	独立系统，非 Job 模型
13	Admin Hermes Chat	Admin 内部	AdminAiChatService → 直接 HTTP	绕过 AiGateway（直接 fetch）	❌	延期	Admin 工具，非生产用户路径
14	Synthetic Job	测试	SyntheticResultProjector → Engine	Unified Engine（NODE_ENV=test）	✅	M-AI-03	测试工具
15	Legacy AiAnalysisWorker	BullMQ ai-analysis 队列	ActiveRecallAnalysisWorkflow / FeynmanEvaluationWorkflow → AiGateway	旧 Worker（双路径中的 Legacy 分支）	⚠️	M-AI-04/05	保留至 Legacy 退役
16	ReviewCardSubscriber	EventBus ai.analysis.completed	ReviewCardGenerationWorkflow → AiGateway	EventBus 订阅（Legacy 分支）	⚠️	M-AI-06	保留至 Legacy 退役

---

二、分类汇总

已迁移（6）

#	Workflow	Milestone
1	Active Recall	M-AI-04
2	Feynman	M-AI-05
3	ReviewCard	M-AI-06
4	Quiz	M-AI-07
14	Synthetic	M-AI-03
*	(Engine 基础设施)	M-AI-03

M-AI-08 范围（4）

#	Workflow	当前模型	当前数据表	优先级
5	learning_state_analysis	外部 Runtime	AiLearningAnalysis	高
6	weak_point_analysis	外部 Runtime	WeakPointCandidate	高
7	next_action_planning	外部 Runtime	NextActionRecommendation	高
8	flashcard_generation	外部 Runtime	Flashcard	中

这四个作业类型均通过外部 Runtime 轮询机制执行，使用 AiRuntimeJob 表而非统一 AiJob 表。需要内联 Prompt/Schema 并通过 AiGateway 调用。

明确延期（5）

#	Workflow	原因
9	学习趋势	短期可视化，非核心分析
10	知识导入	独立功能链
11	RAG 聊天	独立系统，非 Job 模型
12	向量 Rerank	独立管道
13	Admin Chat	Admin 工具

待退役（2）

#	Workflow	何时退役
15	Legacy AiAnalysisWorker	M-AI-09 Heavy Runtime 退场
16	ReviewCardSubscriber (Legacy)	M-AI-09 Heavy Runtime 退场

---

三、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 全部条件后方可退役。

退役前置条件（冻结）

- Unified 生产流量达到 100%
- 连续观察期内无 P0/P1
- 失败率在允许范围
- 无双执行 / 无重复产物 / 无重复扣费
- 无跨用户事件
- 成本符合预算
- 所有 Flag 可回滚
- Legacy 流量为 0
- Legacy Queue 无新任务
- 历史 Legacy Job 已处理完成

---

四、闭环判定

核心生产 AI Workflow 状态

已迁移到 Unified Engine：  6 个
M-AI-08 范围内（本批）：    4 个
明确延期（非阻塞）：        5 个
待退役（Legacy 双路径）：   2 个
─────────────────────────────────
总计：                     17 个

判定

M-AI-08 是否为最后一个核心业务迁移里程碑：是

理由：
- M-AI-08 覆盖剩余 4 个核心生产 AI Workflow（均通过 Runtime 轮询）
- 延期的 5 个为非核心/独立系统，不阻塞业务迁移主线
- Legacy 双路径（Active Recall/Feynman）在 Engine 层面已完成迁移，
  仅待 M-AI-09 退役旧 Worker

---

四、未登记模型调用检查

检查项	状态	证据
是否存在未登记的生产模型调用	否	全部 17 个 Workflow 已盘点
是否存在 Controller 直连 Provider	否	所有调用通过 AiGateway 或外部 Runtime
是否存在 Service 绕过 AiGateway	仅 Admin Chat	Admin 工具，非生产用户路径
是否存在生产 Worker 绕过统一 Job	Runtime 4 个	本批 M-AI-08 迁移
是否存在无主人的 Legacy AI Queue	ai-analysis	仍有双路径，M-AI-09 退役