c88af39673
All checks were successful
Deploy API Server / build-and-deploy (push) Successful in 45s
- runtime-internal.service: resolveSnapshot 自动重建、persistResult 5种jobType持久化、validateOutput 校验、convertQuizCandidates/convertFlashcardCandidates 候选转换、notifyJobComplete 通知、JOB_CANCELLED处理、heartbeat 双阶段更新+取消检测 - user-ai.service: createAnalysisJob 11步流程、cancelJob、publishQuiz/publishFlashcard、getAnalysis/listAnalyses等 - user-ai.controller: 20+ 用户API端点 - 新增服务: SnapshotBuilderService、PriorityRulesService、SnapshotCleanupService、JobReaperService - 新增模块: admin-learning (CRUD管理) - Prisma schema: cancelRequestedAt/cancelledAt/sourceBlockIds 字段、expiresAt 索引 - 文档: ai-runtime-user-api.md、Issue 记录 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
44 lines
1.5 KiB
Markdown
44 lines
1.5 KiB
Markdown
# API-AI-R02: sourceDataVersion 增强
|
||
|
||
## 基本信息
|
||
|
||
| 字段 | 值 |
|
||
|------|-----|
|
||
| Issue ID | API-AI-R02 |
|
||
| 类型 | Non-blocking / 增强 |
|
||
| 仓库 | api-server |
|
||
| 关联 Issue | API-AI-021 (Snapshot 版本化与过期) |
|
||
| 发现日期 | 2026-06-17 |
|
||
| 优先级 | P2 |
|
||
|
||
## 问题描述
|
||
|
||
`LearningAnalysisSnapshot.sourceDataVersion` 字段当前写入固定值 `'1.0'`（`snapshot-builder.service.ts:122`），但缺乏自动递增/校验机制。
|
||
|
||
### 当前状态
|
||
|
||
- 字段已写入：`sourceDataVersion: SOURCE_DATA_VERSION`（常量 `'1.0'`）
|
||
- `resolveSnapshot` 已做版本匹配检查：`existing.sourceDataVersion === SOURCE_DATA_VERSION`
|
||
- 缺少：当聚合逻辑变更时自动检测并递增版本号的能力
|
||
|
||
### 期望增强
|
||
|
||
当以下任一变更发生时，`SOURCE_DATA_VERSION` 需要手动递增，但目前依赖开发者记忆：
|
||
|
||
1. `computeSignals` 信号计算公式变更
|
||
2. `getScoreWeights` 权重调整
|
||
3. `classifyMasteryLevel` 分类阈值变更
|
||
4. `BEHAVIOR_WINDOW_DAYS` / `SCORE_WINDOW_DAYS` 等窗口常量变更
|
||
5. 聚合查询字段增减
|
||
|
||
### 建议方案
|
||
|
||
- 方案 A：在 CI 中对信号计算相关文件做 hash，hash 变更时校验是否同步更新了 `SOURCE_DATA_VERSION`
|
||
- 方案 B：将 `SOURCE_DATA_VERSION` 改为从信号逻辑的语义版本自动推导
|
||
- 方案 C：在开发流程中增加 checklist，变更信号逻辑时必须更新版本号
|
||
|
||
## 相关文件
|
||
|
||
- `src/modules/ai-runtime/snapshot-builder.service.ts`
|
||
- `src/modules/ai-runtime/internal/runtime-internal.service.ts:resolveSnapshot()`
|