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()`
|