# H1/H2 数据分层归档架构

## 问题

4128条订单/8MB JSON 每次加载慢，MCP+顺丰全量拉取5-8分钟，H1历史数据（96%已稳定）无需重复查询。

## 方案

### 四文件结构

```
data/
├── h1_archive.json        3KB   H1汇总指标（月度金额/客户Top10/部门分布）
├── h2_live.json         300KB   H2实时订单明细（含顺丰轨迹）
├── orders_dashboard.json   1KB   看板用聚合指标（H1+H2合并）
└── shipment_status.json = h2_live + h1_summary + full_year_tax 字段
```

### 归档规则

| 条件 | 操作 |
|------|------|
| `createDate ≤ 2026-06-30` | H1全部归档至汇总 |
| H2 + `shipment.status = delivered` + 签收日期 > 7天前 | 归档至H1汇总，从实时移除 |
| H2 + 在途/未签收/签收≤7天 | 保留在 `shipment_status.json` |

### 归档脚本核心逻辑

```python
h1_archive = []   # 归入H1汇总
h2_live = []      # 保持实时

for o in orders:
    cd = o.get("createDate","")
    if cd <= "2026-06-30":
        h1_archive.append(o)  # H1全部归档
    elif o["shipment"]["status"] == "delivered":
        dd = routes[-1].get("acceptTime","")[:10]  # 签收日期
        if dd <= (datetime.now() - timedelta(days=7)).strftime("%Y-%m-%d"):
            h1_archive.append(o)  # 签收>7天归档
        else:
            h2_live.append(o)
    else:
        h2_live.append(o)
```

### h1_archive.json 生成（仅汇总指标，非明细）

```python
h1_archive.json = {
    "summary": {"total": 3785, "tax": 2154.6万, "status": {...}},
    "monthly": {"2026-01": {...}, ...},     # 按月聚合
    "top_customers": [{name, amount}×10],   # 客户Top10
    "departments": {dept: {amount, orders}} # 部门聚合
}
```

### 前端本年统计合并

```javascript
// shipment_status.json 携带 h1_summary + full_year_tax
if (orderState.analysisPeriod === 'year') {
    ps.total += data.h1Summary.total_orders || 0;
    ps.taxTotal = data.fullYearTax || 0;
}
```

## 收益

| 指标 | 归档前 | 归档后 |
|------|--------|--------|
| JSON大小 | 8MB | 2MB |
| 加载速度 | 1-2s | 瞬间 |
| 日刷新时间 | 5-8min | ~30s |
| H1查询 | 每次拉取 | 季度末手动一次 |
| 顺丰API调用 | 1233次 | ~300次 |

## 维护策略

- **H1汇总文件**：季度末手动更新一次（使用固化ERP导出数据校对）
- **H2实时文件**：cron每日自动拉取MCP+顺丰API
- **看板文件**：随H2刷新时一并生成
- **归档阈值**：每季度初手动调整 h1_key（如Q4时改为"2026-09-30"）