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