docs(M-AI-08-01): AI workflow inventory + learning analysis migration contract
Inventory: 17 AI workflows cataloged. 6 migrated, 4 in M-AI-08 scope, 5 deferred, 2 legacy pending retirement. Confirmed M-AI-08 as final core business migration milestone. Contract: 4 Runtime job types (learning_state/weak_point/next_action/ flashcard) to be merged into unified learning_analysis Job. Data source matrix, snapshot schema, evidence schema, topology frozen. Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
wangdl
parent
ec2379eaf3
commit
5628e6db90
@ -0,0 +1,462 @@
|
|||||||
|
# M-AI-08 学习综合分析迁移契约
|
||||||
|
|
||||||
|
> 审计日期：2026-06-22
|
||||||
|
> 契约状态：冻结（待 M-AI-08-01 验收）
|
||||||
|
> 对应里程碑：M-AI-08 学习综合分析、学习建议与 AI 迁移闭环
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
1. [当前链路审计](#1-当前链路审计)
|
||||||
|
2. [目标链路](#2-目标链路)
|
||||||
|
3. [数据源矩阵](#3-数据源矩阵)
|
||||||
|
4. [聚合窗口](#4-聚合窗口)
|
||||||
|
5. [Snapshot Schema](#5-snapshot-schema)
|
||||||
|
6. [Output Schema](#6-output-schema)
|
||||||
|
7. [Evidence Schema](#7-evidence-schema)
|
||||||
|
8. [触发模型](#8-触发模型)
|
||||||
|
9. [幂等契约](#9-幂等契约)
|
||||||
|
10. [Artifact 矩阵](#10-artifact-矩阵)
|
||||||
|
11. [权限与隐私](#11-权限与隐私)
|
||||||
|
12. [Feature Flag](#12-feature-flag)
|
||||||
|
13. [回滚流程](#13-回滚流程)
|
||||||
|
14. [架构异常与不确定项](#14-架构异常与不确定项)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 当前链路审计
|
||||||
|
|
||||||
|
### 1.1 四种 Runtime 作业类型
|
||||||
|
|
||||||
|
| Job Type | 产出实体 | promptVersion | outputSchemaVersion | 现状 |
|
||||||
|
|----------|---------|---------------|---------------------|------|
|
||||||
|
| `learning_state_analysis` | AiLearningAnalysis | learning_state_v1 | analysis_output_v1 | Runtime 轮询 |
|
||||||
|
| `weak_point_analysis` | WeakPointCandidate | weak_point_v1 | weak_point_output_v1 | Runtime 轮询 |
|
||||||
|
| `next_action_planning` | NextActionRecommendation | next_action_v1 | next_action_output_v1 | Runtime 轮询 |
|
||||||
|
| `flashcard_generation` | Flashcard | flashcard_gen_v1 | flashcard_output_v1 | Runtime 轮询 |
|
||||||
|
|
||||||
|
### 1.2 当前时序（Runtime 轮询路径）
|
||||||
|
|
||||||
|
```text
|
||||||
|
POST /api/ai/jobs { jobType: "learning_state_analysis", targetType, targetId }
|
||||||
|
→ UserAiService.createAnalysisJob()
|
||||||
|
`src/modules/ai-runtime/user-ai.service.ts:199`
|
||||||
|
├─ settings 检查 (:201-206)
|
||||||
|
├─ jobType 验证 (:210-214)
|
||||||
|
├─ 幂等检查 (:225-233)
|
||||||
|
├─ 配额+预算 (:252-267)
|
||||||
|
├─ SnapshotBuilderService.buildSnapshot() (:270)
|
||||||
|
│ `src/modules/ai-runtime/snapshot-builder.service.ts:75`
|
||||||
|
│ ├─ fetchBehaviorData() — DailyLearningActivity, LearningSession
|
||||||
|
│ ├─ aggregateProgress() — MaterialReadingProgress
|
||||||
|
│ ├─ aggregateContent() — KnowledgeItem（可选）
|
||||||
|
│ ├─ calculateScores() — Quiz/Review/ActiveRecall/Feynman metrics
|
||||||
|
│ ├─ computeSignals() — engagement/consistency/streaks/patterns
|
||||||
|
│ └─ buildDeviceContext() — 平台/时区/设备
|
||||||
|
├─ PriorityRulesService.computeJobPriority() (:279)
|
||||||
|
└─ aiRuntimeJob.create (:282-299)
|
||||||
|
|
||||||
|
外部 Runtime 轮询
|
||||||
|
→ POST /internal/runtime/jobs/poll → pollJobs() (:22)
|
||||||
|
→ POST /internal/runtime/jobs/:id/lock → lockJob() (:85)
|
||||||
|
→ GET /internal/runtime/jobs/:id/snapshot → getSnapshot() (:153)
|
||||||
|
→ Runtime 执行 AI 调用（prompt/schema 外部管理）
|
||||||
|
→ POST /internal/runtime/jobs/:id/result → submitResult() (:220)
|
||||||
|
└─ persistResult() (:286)
|
||||||
|
├─ learning_state_analysis → AiLearningAnalysis.create (:295-311)
|
||||||
|
├─ weak_point_analysis → WeakPointCandidate.create (:313-337)
|
||||||
|
└─ next_action_planning → NextActionRecommendation.create (:339-365)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.3 数据模型
|
||||||
|
|
||||||
|
**AiLearningAnalysis** (`schema.prisma:2173-2194`):
|
||||||
|
```text
|
||||||
|
id, userId, jobId, snapshotId, targetType, targetId,
|
||||||
|
learningState, summary, riskLevel, confidence, evidence (Json),
|
||||||
|
nextActionIds (Json), promptVersion, schemaVersion
|
||||||
|
```
|
||||||
|
|
||||||
|
**WeakPointCandidate** (`schema.prisma:2198-2216`):
|
||||||
|
```text
|
||||||
|
id, userId, jobId, snapshotId, targetType, targetId,
|
||||||
|
knowledgePointId, title, reason, confidence, evidence (Json),
|
||||||
|
status (active/resolved)
|
||||||
|
```
|
||||||
|
|
||||||
|
**NextActionRecommendation** (`schema.prisma:2220-2239`):
|
||||||
|
```text
|
||||||
|
id, userId, jobId, snapshotId, actionType, targetType, targetId,
|
||||||
|
title, reason, priority, estimatedMinutes, deviceSuitability,
|
||||||
|
status (active/resolved)
|
||||||
|
```
|
||||||
|
|
||||||
|
**LearningAnalysisSnapshot** (`schema.prisma:2058-2083`):
|
||||||
|
```text
|
||||||
|
id, userId, scopeType, scopeId, snapshotVersion, sourceDataVersion,
|
||||||
|
privacyScope, userProfile, aiSettings, deviceContext,
|
||||||
|
learningBehaviorSummary, materialProgressSummary, contentStructureSummary,
|
||||||
|
behaviorSignals, scoreSignals, constraints, allowedModelFields
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.4 拓扑（冻结）
|
||||||
|
|
||||||
|
审计确认：`learning_state_analysis`、`weak_point_analysis`、`next_action_planning` 三者**各自独立调用模型**，由外部 Runtime 分别执行。
|
||||||
|
|
||||||
|
**M-AI-08 迁移决策**：将三者合并为一个 `learning_analysis` Job，一次模型调用同时产出综合分析 + 薄弱点 + 建议。
|
||||||
|
|
||||||
|
```text
|
||||||
|
单一 learning_analysis Job
|
||||||
|
→ 一次 AiGateway 调用
|
||||||
|
→ LearningAnalysisProjector
|
||||||
|
→ AiLearningAnalysis（综合分析）
|
||||||
|
→ WeakPointCandidate × N（薄弱点）
|
||||||
|
→ NextActionRecommendation × N（建议）
|
||||||
|
→ AiJobArtifact × N
|
||||||
|
```
|
||||||
|
|
||||||
|
`flashcard_generation` 保持独立（不属于"学习分析"范畴）。
|
||||||
|
|
||||||
|
### 1.5 数据来源分类
|
||||||
|
|
||||||
|
| 数据 | 来源 | 可信度 | Snapshot 处理 |
|
||||||
|
|------|------|:---:|------|
|
||||||
|
| userId | JWT | 可信 | 直接包含 |
|
||||||
|
| learningGoal | UserLearningProfile | 可信 | 直接包含 |
|
||||||
|
| dailyAvailableMinutes | UserLearningProfile | 可信 | 聚合 |
|
||||||
|
| qualityPreference | UserAiSettings | 可信 | 直接包含 |
|
||||||
|
| 学习时长 | DailyLearningActivity | 可信 | **仅聚合后进入** |
|
||||||
|
| 活跃天数 | DailyLearningActivity | 可信 | 聚合指标 |
|
||||||
|
| 复习完成率 | ReviewCard + ReviewLog | 可信 | 聚合指标 |
|
||||||
|
| Quiz 正确率 | QuizAttempt | 可信 | 聚合指标 |
|
||||||
|
| Active Recall 表现 | AiAnalysisResult | 可信 | 聚合指标 |
|
||||||
|
| Feynman 弱点 | FocusItem + AiAnalysisResult | 可信 | 聚合指标 |
|
||||||
|
| 知识点进度 | KnowledgeItem + MaterialReadingProgress | 可信 | 列表（限量+截断） |
|
||||||
|
| 设备/时区 | DeviceContext（服务端推断） | 可信 | 直接包含 |
|
||||||
|
| 学习时长（客户端声明） | — | **不可信** | **禁止进入** |
|
||||||
|
| 掌握度（客户端声明） | — | **不可信** | **禁止进入** |
|
||||||
|
| JWT / API Key | Request Header | — | **禁止进入** |
|
||||||
|
| 完整对话历史 | — | — | **禁止进入** |
|
||||||
|
|
||||||
|
### 1.6 副作用矩阵
|
||||||
|
|
||||||
|
| 副作用 | 当前 | Unified |
|
||||||
|
|--------|------|---------|
|
||||||
|
| 配额消耗 | quota.incrementJobCount | 保持 |
|
||||||
|
| UsageLog | Runtime 记录 | Engine 记录 |
|
||||||
|
| 更新用户画像 | 否 | 否 |
|
||||||
|
| 更新知识点掌握度 | 否 | 否 |
|
||||||
|
| 创建通知 | 否 | 否 |
|
||||||
|
| 自动生成复习卡 | 否 | 否 |
|
||||||
|
| 自动执行建议 | 否 | 否（禁止） |
|
||||||
|
| Snapshot 创建 | SnapshotBuilderService | SnapshotBuilder（复用） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 目标链路
|
||||||
|
|
||||||
|
```text
|
||||||
|
手动/定时触发
|
||||||
|
→ LearningAnalysisExecutionRouter
|
||||||
|
├─ [legacy] → UserAiService.createAnalysisJob()
|
||||||
|
└─ [unified] →
|
||||||
|
LearningAnalysisSnapshotBuilder.build()
|
||||||
|
→ AiJobCreationService.createJob()
|
||||||
|
→ Job + Snapshot + Outbox
|
||||||
|
→ BullMQ (ai-background)
|
||||||
|
→ Worker → AiJobExecutionEngine
|
||||||
|
EXECUTE: LearningAnalysisExecutor (AiGateway)
|
||||||
|
VALIDATE: SchemaValidator + EvidenceValidator + BusinessValidator
|
||||||
|
PROJECT: LearningAnalysisProjector
|
||||||
|
→ AiLearningAnalysis + WeakPointCandidate × N
|
||||||
|
+ NextActionRecommendation × N + Artifact
|
||||||
|
→ markSucceeded
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 数据源矩阵
|
||||||
|
|
||||||
|
| 数据源 | Prisma 模型 | Snapshot 包含方式 |
|
||||||
|
|--------|-----------|-----------------|
|
||||||
|
| 用户学习目标 | UserLearningProfile | 直接字段 |
|
||||||
|
| AI 设置 | UserAiSettings | 直接字段 |
|
||||||
|
| 每日学习活动 | DailyLearningActivity | 聚合（totalDuration/activeDays/sessionCount） |
|
||||||
|
| 学习会话 | LearningSession | 聚合（avgSessionDuration/completionRate） |
|
||||||
|
| 阅读进度 | MaterialReadingProgress | 列表（限量 50，仅标题+进度） |
|
||||||
|
| 知识项 | KnowledgeItem | 列表（限量 200，仅标题+摘要） |
|
||||||
|
| 复习记录 | ReviewCard + ReviewLog | 聚合（dueCount/completedCount/accuracy/overdue） |
|
||||||
|
| Quiz 结果 | QuizAttempt + QuizAnswer | 聚合（accuracy/byType/byKnowledgeItem） |
|
||||||
|
| Active Recall | AiAnalysisResult | 聚合（count/avgScore/weaknesses） |
|
||||||
|
| Feynman 评估 | AiAnalysisResult + FocusItem | 聚合（count/weaknesses/focusItems） |
|
||||||
|
| 设备上下文 | 服务端推断 | 直接字段（platform/timezone） |
|
||||||
|
| 连续学习 | StreakRecord | 聚合指标 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 聚合窗口
|
||||||
|
|
||||||
|
| 参数 | 默认值 | 说明 |
|
||||||
|
|------|--------|------|
|
||||||
|
| windowStart | 请求时确定 | Snapshot 固定，不漂移 |
|
||||||
|
| windowEnd | 请求时确定 | 与 windowStart 配对 |
|
||||||
|
| timezone | 服务端推断 | 用户设备时区 |
|
||||||
|
| sourceCutoffAt | 请求时 | 数据截止时间 |
|
||||||
|
| aggregationVersion | 语义版本 | 算法版本，变化时重新分析 |
|
||||||
|
| 行为窗口 | 7 天 | 学习行为数据 |
|
||||||
|
| 成绩窗口 | 30 天 | Quiz/复习/Active Recall 成绩 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Snapshot Schema
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface LearningAnalysisSnapshot {
|
||||||
|
schemaVersion: string; // "learning-analysis-v1"
|
||||||
|
snapshot: {
|
||||||
|
userId: string;
|
||||||
|
triggerType: 'manual' | 'scheduled';
|
||||||
|
operationId: string;
|
||||||
|
windowStart: string; // ISO8601
|
||||||
|
windowEnd: string;
|
||||||
|
timezone: string; // IANA
|
||||||
|
aggregationVersion: string;
|
||||||
|
sourceCutoffAt: string;
|
||||||
|
|
||||||
|
learningGoal?: string;
|
||||||
|
qualityPreference?: string;
|
||||||
|
dailyAvailableMinutes?: number;
|
||||||
|
|
||||||
|
studyMetrics: {
|
||||||
|
totalStudyDuration: number;
|
||||||
|
activeDays: number;
|
||||||
|
sessionCount: number;
|
||||||
|
averageSessionDuration: number;
|
||||||
|
completionRate: number;
|
||||||
|
};
|
||||||
|
|
||||||
|
reviewMetrics: {
|
||||||
|
reviewDueCount: number;
|
||||||
|
reviewCompletedCount: number;
|
||||||
|
reviewAccuracy: number;
|
||||||
|
overdueCount: number;
|
||||||
|
retentionTrend: number; // -1 to 1
|
||||||
|
};
|
||||||
|
|
||||||
|
quizMetrics: {
|
||||||
|
quizCount: number;
|
||||||
|
attemptCount: number;
|
||||||
|
accuracy: number;
|
||||||
|
accuracyByQuestionType: Record<string, number>;
|
||||||
|
};
|
||||||
|
|
||||||
|
activeRecallMetrics: {
|
||||||
|
count: number;
|
||||||
|
avgScore: number;
|
||||||
|
weaknessCount: number;
|
||||||
|
};
|
||||||
|
|
||||||
|
feynmanMetrics: {
|
||||||
|
count: number;
|
||||||
|
weaknessCount: number;
|
||||||
|
focusItemCount: number;
|
||||||
|
};
|
||||||
|
|
||||||
|
knowledgeProgress: {
|
||||||
|
totalItems: number;
|
||||||
|
completedItems: number;
|
||||||
|
inProgressItems: number;
|
||||||
|
weakItems: Array<{ id: string; title: string }>;
|
||||||
|
};
|
||||||
|
|
||||||
|
dataQuality: {
|
||||||
|
availableSources: string[];
|
||||||
|
missingSources: string[];
|
||||||
|
sampleSize: number;
|
||||||
|
coverageStart?: string;
|
||||||
|
coverageEnd?: string;
|
||||||
|
insufficientDataReasons: string[];
|
||||||
|
};
|
||||||
|
|
||||||
|
promptKey: string;
|
||||||
|
promptVersion: string;
|
||||||
|
modelTier: string;
|
||||||
|
inputSchemaVersion: string;
|
||||||
|
outputSchemaVersion: string;
|
||||||
|
createdAt: string;
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Output Schema
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface LearningAnalysisOutput {
|
||||||
|
summary: string;
|
||||||
|
strengths: Array<{
|
||||||
|
title: string;
|
||||||
|
description: string;
|
||||||
|
evidenceRefs: EvidenceRef[];
|
||||||
|
}>;
|
||||||
|
weaknesses: Array<{
|
||||||
|
title: string;
|
||||||
|
description: string;
|
||||||
|
knowledgePointId?: string;
|
||||||
|
evidenceRefs: EvidenceRef[];
|
||||||
|
}>;
|
||||||
|
trends: Array<{
|
||||||
|
metricKey: string;
|
||||||
|
direction: 'improving' | 'declining' | 'stable';
|
||||||
|
description: string;
|
||||||
|
evidenceRefs: EvidenceRef[];
|
||||||
|
}>;
|
||||||
|
risks: Array<{
|
||||||
|
title: string;
|
||||||
|
severity: 'low' | 'medium' | 'high';
|
||||||
|
description: string;
|
||||||
|
evidenceRefs: EvidenceRef[];
|
||||||
|
}>;
|
||||||
|
recommendations: Array<{
|
||||||
|
actionType: string;
|
||||||
|
title: string;
|
||||||
|
reason: string;
|
||||||
|
priority: number;
|
||||||
|
estimatedMinutes?: number;
|
||||||
|
targetType?: string;
|
||||||
|
targetId?: string;
|
||||||
|
evidenceRefs: EvidenceRef[];
|
||||||
|
}>;
|
||||||
|
confidence: number; // 0.0-1.0
|
||||||
|
dataQuality: {
|
||||||
|
overall: 'sufficient' | 'limited' | 'insufficient';
|
||||||
|
};
|
||||||
|
insufficientData: boolean;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Evidence Schema
|
||||||
|
|
||||||
|
每个结论必须附带 evidenceRefs：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface EvidenceRef {
|
||||||
|
sourceType: 'study_metric' | 'review_metric' | 'quiz_metric'
|
||||||
|
| 'active_recall' | 'feynman' | 'knowledge_progress';
|
||||||
|
metricKey: string; // e.g. "reviewAccuracy", "quizAccuracy"
|
||||||
|
entityId?: string; // knowledgeItemId / quizId / analysisResultId
|
||||||
|
windowStart: string;
|
||||||
|
windowEnd: string;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 触发模型
|
||||||
|
|
||||||
|
| 触发类型 | 幂等键 | 说明 |
|
||||||
|
|---------|--------|------|
|
||||||
|
| manual | `learning-analysis:manual:<operationId>` | 用户手动触发，同一操作重试相同 Job |
|
||||||
|
| scheduled | `learning-analysis:scheduled:<userId>:<windowStart>:<windowEnd>:<policyVersion>` | 定时触发，同一窗口唯一 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 幂等契约
|
||||||
|
|
||||||
|
### 请求级
|
||||||
|
- 同一 operationId → 同一 Job
|
||||||
|
- 同一 scheduled window → 同一 Job
|
||||||
|
- 禁止 Date.now()/random 回退
|
||||||
|
|
||||||
|
### 投影级
|
||||||
|
- analysisId = deterministic(jobId)
|
||||||
|
- recommendationId = deterministic(jobId + ordinal)
|
||||||
|
- 入口 Artifact 检查 + P2002 catch
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Artifact 矩阵
|
||||||
|
|
||||||
|
| 实体 | artifactType | artifactId |
|
||||||
|
|------|-------------|-----------|
|
||||||
|
| AiLearningAnalysis | `learning_analysis` | analysis.id |
|
||||||
|
| WeakPointCandidate | `weak_point` | candidate.id |
|
||||||
|
| NextActionRecommendation | `recommendation` | recommendation.id |
|
||||||
|
| Flashcard (单独) | `flashcard` | flashcard.id |
|
||||||
|
|
||||||
|
注：M-AI-02 已冻结 `learning_analysis`、`recommendation` 等 artifactType。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. 权限与隐私
|
||||||
|
|
||||||
|
- 所有数据必须属于同一 userId
|
||||||
|
- 禁止其他用户数据进入 Snapshot
|
||||||
|
- 禁止跨用户 evidenceRefs
|
||||||
|
- 公开错误不泄漏 Snapshot/validatedOutput
|
||||||
|
- Admin 可查看所有（现有权限制）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. Feature Flag
|
||||||
|
|
||||||
|
```text
|
||||||
|
Flag Name: LEARNING_ANALYSIS_ENGINE_MODE
|
||||||
|
Values: legacy | unified
|
||||||
|
Default: legacy
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 13. 回滚流程
|
||||||
|
|
||||||
|
```text
|
||||||
|
unified → legacy:
|
||||||
|
1. 修改 Flag → legacy
|
||||||
|
2. 新触发走 Legacy Runtime 轮询
|
||||||
|
3. 已创建 Unified Job 继续完成
|
||||||
|
4. 已生成分析保留
|
||||||
|
5. 无需数据库回滚
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 14. 架构异常与不确定项
|
||||||
|
|
||||||
|
### 阻塞项
|
||||||
|
|
||||||
|
| # | 异常 | 说明 | 处理 |
|
||||||
|
|---|------|------|------|
|
||||||
|
| A1 | 无 learning_state/weak_point/next_action Prompt 模板 | 当前由 Runtime 管理 | M-AI-08-03 需新增内联 Prompt |
|
||||||
|
| A2 | 无对应 Output Schema | 同上 | M-AI-08-03 需新增 Zod Schema |
|
||||||
|
| A3 | flashcard_generation prompt/schema 缺失 | 同 Quiz 模式 | 延期或并入 M-AI-08 |
|
||||||
|
|
||||||
|
### 不确定项
|
||||||
|
|
||||||
|
| 项 | 问题 | 建议 |
|
||||||
|
|----|------|------|
|
||||||
|
| 三个 Job Type 合并策略 | 当前三者独立，合并为一个 learning_analysis 需验证业务合理性 | M-AI-08-01 中确认后冻结 |
|
||||||
|
| flashcard_generation 归属 | 语义上更接近 Quiz 生成而非学习分析 | 建议纳入 M-AI-08 作为独立 Definition |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 附录：关键文件索引
|
||||||
|
|
||||||
|
| 用途 | 路径 | 关键行号 |
|
||||||
|
|------|------|---------|
|
||||||
|
| 分析入口 | `src/modules/ai-runtime/user-ai.service.ts` | `:199` createAnalysisJob, `:11-17` JOB_TYPE_CONFIG |
|
||||||
|
| Runtime 持久化 | `src/modules/ai-runtime/internal/runtime-internal.service.ts` | `:286` persistResult, `:295-365` 四种类型分支 |
|
||||||
|
| Snapshot 构建 | `src/modules/ai-runtime/snapshot-builder.service.ts` | `:75` buildSnapshot, `:259` aggregateBehavior |
|
||||||
|
| Priority 规则 | `src/modules/ai-runtime/priority-rules.service.ts` | `:45` computePriorityRules |
|
||||||
|
| AiLearningAnalysis | `prisma/schema.prisma` | `:2173-2194` |
|
||||||
|
| WeakPointCandidate | `prisma/schema.prisma` | `:2198-2216` |
|
||||||
|
| NextActionRecommendation | `prisma/schema.prisma` | `:2220-2239` |
|
||||||
|
| LearningAnalysisSnapshot | `prisma/schema.prisma` | `:2058-2083` |
|
||||||
|
| UserLearningProfile | `prisma/schema.prisma` | `:1912-1932` |
|
||||||
|
| UserAiSettings | `prisma/schema.prisma` | `:1936-1953` |
|
||||||
|
| 学习趋势 Workflow | `src/modules/ai/workflows/learning-trend.workflow.ts` | `:30` execute |
|
||||||
|
| 学习趋势 Prompt | `src/modules/ai/prompts/learning-trend.prompt.ts` | `:1` system prompt |
|
||||||
109
docs/architecture/m-ai-migration-inventory.md
Normal file
109
docs/architecture/m-ai-migration-inventory.md
Normal file
@ -0,0 +1,109 @@
|
|||||||
|
# M-AI 迁移盘点：AI Workflow 全量清单
|
||||||
|
|
||||||
|
> 审计日期：2026-06-22
|
||||||
|
> 基线：M-AI-07 PASS（commit `ec2379e`）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 一、全量 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 退场 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 三、闭环判定
|
||||||
|
|
||||||
|
### 核心生产 AI Workflow 状态
|
||||||
|
|
||||||
|
```text
|
||||||
|
已迁移到 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 退役 |
|
||||||
Loading…
x
Reference in New Issue
Block a user