---
phase: 11-predictv3
reviewed: 2026-05-01T12:30:00Z
depth: standard
files_reviewed: 3
files_reviewed_list:
  - application/admin/model/History.php
  - application/admin/controller/History.php
  - public/assets/js/backend/history.js
findings:
  critical: 0
  warning: 0
  info: 3
  total: 3
status: clean
---

# Phase 11: Code Review Report

**Reviewed:** 2026-05-01T12:30:00Z
**Depth:** standard
**Files Reviewed:** 3
**Status:** clean

## Summary

审查了 phase 11-predictv3 的三个核心文件：后端 Model、Controller 和前端 JS。代码整体质量优秀，包含完善的边界情况处理、详细的公式注释、安全的输入验证和前后端数据结构一致性。

主要新增功能实现正确：
- 回测指标扩展（NDCG@5、MRR、命中分布）公式正确，边界保护完善
- 置信度计算三维加权公式（0.4 + 0.3 + 0.3）实现正确
- 权重网格搜索优化包含超时保护，避免长时间阻塞
- 二阶马尔可夫转移概率实现正确，包含观察次数阈值判断
- 前端正确解析后端返回的置信度、NDCG、MRR 和命中分布数据

所有关键除零点都有保护，空数组检查完善，输入参数范围验证到位。

## Critical Issues

无严重问题发现。

## Warnings

无警告级别问题发现。

## Info

### IN-01: 参数越界时静默使用默认值

**File:** `application/admin/controller/History.php:515-523`
**Issue:** `optimizeWeights` 方法中 `backtest` 和 `timeout` 参数越界时使用默认值而非报错，用户可能不知道参数被调整。虽然设计意图是提供容错性，但缺少明确反馈。
**Fix:** 建议在响应中添加参数调整提示，或改用 `$this->error()` 明确告知用户参数无效：
```php
if ($backtestCount < 10 || $backtestCount > 100) {
    $this->error('回测期数范围必须在 10-100 之间');
}
```

### IN-02: 变量初始化位置不一致

**File:** `application/admin/model/History.php:3791-3806`
**Issue:** `$ndcg5`、`$mrr`、`$hitDistribution` 变量在条件分支内定义，虽然逻辑正确（数据不足时返回零值），但两个分支结构不同可能导致代码维护时遗漏。
**Fix:** 建议在函数开头统一初始化默认值，使代码结构更清晰：
```php
$ndcg5 = 0;
$mrr = 0;
$hitDistribution = ['rank_1' => 0, 'rank_2' => 0, 'rank_3' => 0, 'rank_4' => 0, 'rank_5' => 0];
$dataWarning = null;

if ($testCount >= $minDataThreshold) {
    $ndcg5 = $this->_calculateNDCG($details, 5);
    // ...
}
```

### IN-03: precision_5 指标含义需补充注释

**File:** `application/admin/model/History.php:3808`
**Issue:** `precision_5` 计算公式 `$hits / ($testCount * 5) * 100` 缺少公式说明注释，含义不够直观（应为 Top5 推荐的精确率，即命中次数占总推荐数的比例）。
**Fix:** 添加注释说明指标含义：
```php
// Precision@5 = 命中次数 / (测试次数 × 推荐数量5) × 100
// 表示 Top5 推荐的整体精确率，范围 0-20%（因为单次最多命中1个）
$precision5 = $testCount > 0 ? round($hits / ($testCount * 5) * 100, 2) : 0;
```

## Verified Quality Points

以下边界保护和公式实现经审查确认正确：

1. **除零保护完善**：
   - `_calculateNDCG` 第3875行检查 `$idcg > 0`
   - `_calculateMRR` 第3910行检查 `count($reciprocalRanks) > 0`
   - `_getHistoricalHitRateByRank` 第4072行检查 `$totalTests > 0`
   - `_getScoreDistributionConfidence` 第4094行检查 `$topScore == $bottomScore`
   - `_getScoreConcentration` 第4126行检查 `$topScore == $avgScore`
   - `_calcStdDev` 第1997行检查 `count($data) < 2`
   - `_adjustWeightsDynamic` 第3015行检查 `$total > 0`

2. **空数组检查**：
   - `_calculateConfidence` 第3998行检查 `empty($predictions)`
   - `_getScoreDistributionConfidence` 第4089行检查 `empty($predictions)`
   - `_getScoreConcentration` 第4116行检查 `empty($predictions)`
   - `_calcOmitScoreEmpirical` 第3055行检查 `empty($omitHistory)`
   - `_calculateNDCG` 第3844行检查 `empty($backtestDetails)`
   - `_calculateMRR` 第3893行检查 `empty($backtestDetails)`
   - `_calculateHitDistribution` 第3930行检查 `empty($backtestDetails)`

3. **公式正确性**：
   - NDCG@5 使用标准 DCG/IDCG 公式（第3858行）
   - MRR 使用标准倒数排名均值公式（第3904行）
   - 置信度三维加权公式 `0.4 * rank_hit_rate + 0.3 * score_distribution + 0.3 * score_concentration` 正确（第4018行）
   - 权重网格搜索综合评分公式 `hit_rate * 0.6 + ndcg * 100 * 0.4` 正确（第4249行）

4. **前后端数据一致性**：
   - 前端正确将 NDCG/MRR（0-1范围）乘以100显示为百分比（第1779、1782行）
   - 前端正确解析 `hit_distribution` 使用 `rank_1` 到 `rank_5` 键名（第1792-1816行）
   - 前端正确查找 `confidence.confidence_scores` 中的特定号码置信度（第1946-1953行）

---

_Reviewed: 2026-05-01T12:30:00Z_
_Reviewer: Claude (gsd-code-reviewer)_
_Depth: standard_