# H1 订单存档管道：致命陷阱与正确方案

## 背景

H1（1-6月）订单数据不在 `shipment_status.json`（仅含近期 H2 订单）。需从 MCP 按月拉取 → 存档 → 合并到前端。

## ⚠️ 致命陷阱：用客户 owner 映射替代角色查询

**症状**：宋学伟 ERP 有 205 单/108.1 万，H1 存档仅 30 单。赵云浩等其他销售员也大量缺失。

**根因**：`pull_h1_archive.py` 初版用 `mcp_customers.json` 的 `owner` 字段做客户→销售员映射：

```python
# ❌ 致命错误
sales_map[customer_name] = customer_owner
order['creator'] = sales_map.get(order_customer)
```

MCP 客户的 `owner` ≠ 订单的「下单人」。客户 owner 离职后未更新 → 该客户所有订单都归到离职人员名下。

**修复**：必须逐订单调用 `get_workitem_brief` 获取「下单人」角色：

```python
# ✅ 正确
result = mcp("get_workitem_brief", {"project_key": PK, "work_item_id": wid})
role_members = result['work_item_attribute']['role_members']
for rm in role_members:
    if rm['name'] == '下单人':
        xdr = {'name_cn': rm['members'][0]['name'], 'email': rm['members'][0]['email']}
```

## 按月拉取架构

```
pull_h1_archive.py --m01~m06
  → h1_archive/m01_orders.json ~ m06_orders.json
  → h1_archive/h1_all.json (合并)
  → merge_workbench_data.py 注入到 shipments
  → workbench_data.json (H1 4063 + H2 186 = 4249 条)
```

每月约 800 个 work_item，去重后约 500-800 个唯一订单。首次拉取全部 6 个月约需 20 分钟（含 get_workitem_brief 查询）。后续增量极快（缓存命中）。

## 缓存策略

`order_role_cache.json` 按 orderId 索引下单人。首次慢（逐条查询），后续秒级。缓存与 H2 动态订单共用。

## MCP API 超时处理

MQL 分页查询偶发超时（30s）。需：
- 降低单次超时到 20s
- 加 2 次重试
- 限制最大页数（80 页/月 = 4000 items）

## ERP 对比验证

ERP 数据（`2026客户价格.xlsx`）中「销售员」字段是地面真相。H1 存档完成后应与 ERP 交叉验证：ERP 订单数 vs MCP 存档订单数，差异不应超过 10%。