# 看板数据一致性级联故障（2026-08-07 实战）

## 概述

一次数据更新操作触发三重级联 bug，导致看板显示 `2517.6万` 而非正确的 `2633.3万`。
根源：kpi_dashboard、kpi_progress、three_year_monthly 三文件缺乏原子性更新机制。

---

## Bug #1: mcp_kpi_pipeline.py `total_h2_actual` 只取单月

**文件**：`数据/mcp_kpi_pipeline.py` 第 115 行

```python
# ❌ 只取当前月份 month_idx，丢失已完成的月份
kpi['total_h2_actual'] = round(sum(p['h2_actual_months'][month_idx] for p in kpi['people']), 2)

# ✅ 用每个 person 的 h2_actual（已累计所有月份）
kpi['total_h2_actual'] = round(sum(p.get('h2_actual', 0) for p in kpi['people']), 2)
```

**表现**：运行 8 月数据后，`total_h2_actual` = 115.7万（仅 8 月），而非 469.3万（7+8月）。
**影响**：kpi_dashboard → merge → workbench_data → 看板累计达成显示错误。

---

## Bug #2: cb_sync_data.sh 未同步 kpi_dashboard.json

**文件**：`~/.hermes/scripts/cb_sync_data.sh`

```bash
# ❌ 只同步 kpi_progress，不同步 kpi_dashboard
for f in "kpi_progress.json" ...

# ✅ 加入 kpi_dashboard.json
for f in "kpi_dashboard.json" "kpi_progress.json" ...
```

**影响**：修复本地 `kpi_dashboard.json` 后部署 `workbench_data.json`（正确），但前端从 `ENDPOINTS` 加载独立 JSON 文件仍读旧值。

---

## Bug #3: 前端 H2 图表月份错位

**文件**：`工具/index.html` `getKPI()` 第 997 行

```javascript
// ❌ 把当前月（8月=115.7万）放在 H2 第一格（7月位置）
h2Actuals: [current, 0, 0, 0, 0, 0]

// ✅ 从 threeYearMonthly 按月份取值
var tym = d.threeYearMonthly || {};
var t2026 = tym['2026'] || {};
var h2Actuals = [
  t2026['7'] || 0,   // 7月
  t2026['8'] || current,  // 8月
  t2026['9'] || 0,   // 9月
  t2026['10'] || 0,  // 10月
  t2026['11'] || 0,  // 11月
  t2026['12'] || 0   // 12月
];
```

---

## Bug #4: 前端累计达成缺少历史 H2 月份

**文件**：`工具/index.html` `renderDashboard()` 第 1152 行

```javascript
// ❌ H1 + 当月 = 2164.0 + 115.7 = 2279.7万（缺7月）
var fullYearTax = filteredYtd + (prog.total || 0);

// ✅ 无筛选时直接用 kpiDashboard 权威累计值
var fullYearTax = filteredYtd + (prog.total || 0);
if (!filteredSalesSet) fullYearTax = dash.total_h1_h2 || fullYearTax;
```

---

## 数据源权威链

```
ERP上传 → threeYearMonthly.json (各月固定, 权威)
         → kpi_progress.json (当月, 动态)
         → kpi_dashboard.json (聚合: H1 + all H2 months from threeYearMonthly)
            → merge → workbench_data.json (嵌入)
            → 前端 ENDPOINTS 单独加载 kpi_dashboard.json + kpi_progress.json
```

## 修复后正确值

| 字段 | 修复前 | 修复后 |
|------|--------|--------|
| kpi_dashboard.total_h2_actual | 352.6万 | 469.3万 |
| kpi_dashboard.total_h1_h2 | 2516.7万 | 2633.3万 |
| 前端 H2 图表 7 月 | 115.7万（错） | 353.6万 ✅ |
| 前端 H2 图表 8 月 | 0 | 115.7万 ✅ |
| 前端累计达成 | 2517.6万 | 2633.3万 ✅ |