amlhc/.planning/phases/11-predictv3/11-01-SUMMARY.md

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, decisions, metrics

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	decisions	metrics
11-predictv3	01	backend	predictv3 backtest metrics ndcg mrr	PRED-02 PRED-05	NDCG@5 计算方法 MRR 计算方法 命中分布计算方法 扩展的回测返回结构	_runBacktestV3 返回值 前端回测结果展示	added patterns TDD-style validation edge case handling	created modified application/admin/model/History.php	使用 50 期作为最小数据量阈值 hit_distribution 使用 rank_N 键名格式便于前端解析 空预测或无效数据返回默认值而非抛出异常	duration tasks_completed files_modified completed_at ~5min 3 1 2026-05-01T07:15:00Z

Phase 11 - Plan 01: 回测指标扩展 Summary

One-liner

扩展 _runBacktestV3 方法，新增 NDCG@5、MRR、命中率分布等排名质量评估指标，提升算法评估能力。

Changes Made

Task 1: 实现 NDCG@5 计算方法

新增 _calculateNDCG 方法：

• 实现归一化折损累积增益计算
• 公式：DCG = Σ(1/log2(rank+1))，IDCG = Σ(1/log2(i+1))
• 添加空预测保护和数据完整性检查
• 返回 0-1 范围标准化值

Task 2: 实现 MRR 和命中分布计算方法

新增 _calculateMRR 方法：

• 实现平均倒数排名计算
• 公式：MRR = Σ(1/rank_i) / N
• 添加空预测保护

新增 _calculateHitDistribution 方法：

• 统计各排名位置(1-5)的命中次数
• 返回格式：{rank_1: n, rank_2: n, ..., rank_5: n}
• 用于前端柱状图可视化

Task 3: 扩展 _runBacktestV3 返回结果

修改返回结构，新增字段：

• ndcg_5: NDCG@5 值
• mrr: 平均倒数排名
• hit_distribution: 各排名命中分布
• precision_5: Top-5 精确率
• data_warning: 数据量不足警告
• data_sufficient: 数据量是否充足标志

添加数据量检查：不足 50 期时返回默认值和警告提示。

Files Modified

File	Changes
application/admin/model/History.php	+134 行（3个新方法 + 返回结构扩展）

Acceptance Criteria Verification

Criteria	Status
_calculateNDCG 方法存在	PASSED
_calculateMRR 方法存在	PASSED
_calculateHitDistribution 方法存在	PASSED
所有方法包含空预测保护	PASSED
所有方法包含函数级注释	PASSED
hit_distribution 结构为 rank_N 格式	PASSED
_runBacktestV3 返回结构包含新字段	PASSED
数据量检查（50期阈值）	PASSED

Deviations from Plan

None - plan executed exactly as written.

Known Stubs

None.

Threat Flags

None.

Self-Check

• 所有新增方法已实现
• 所有验收标准已通过
• 提交已完成 (483a616)
• 代码包含函数级注释