# 顺丰物流轨迹数据管道

## 架构

```
MCP 销售订单 → 顺丰 EXP_RECE_SEARCH_ROUTES → 数据/shipment_status.json → 销售工作台 fetch()
```

## 管道脚本

`脚本/shipment_pipeline.py` — 位于 `/Users/liuxinyuan/Desktop/Hermes输出-工作类/`

用法：
```bash
python3 脚本/shipment_pipeline.py          # 从 MCP 输入文件拉取
python3 脚本/shipment_pipeline.py --mock   # 用 mock 数据测试
```

## 数据流

1. 从 MCP 拉取有物流单号的未完结销售订单（分页，每页50条）
2. 去重物流单号 + 提取手机号后4位
3. 批量调用顺丰 API（每10个一批，间隔0.5s，控制30qps内）
4. 解析轨迹，判断状态：delivered/delivering/in_transit/picked_up/no_data
   ⚠️ 签收判断不能用 `"签收" in remark`！顺丰用"派送至本人""派送成功"等。详见 `references/shipment-status-logic.md`
5. 合并订单字段 + 轨迹 → 写入 shipment_status.json

## JSON 输出格式

```json
{
  "updated_at": "2026-07-24 22:15:00",
  "total": 527,
  "orders": [{
    "orderId": "ZHBR260724027",
    "customer": "圣湘生物",
    "product": "2xFastAmpli Premix-UNG IV",
    "sku": "M2181-4-NA-095203",
    "batch": "20260417",
    "spec": "2×",
    "unit": "ml",
    "dept": "诊断原料大客户销售部",
    "createDate": "2026-07-24",
    "recipient": "蔡琦",
    "phone": "17610556866",
    "address": "湖南省长沙市...",
    "trackingNo": "SF5112860018518",
    "quantity": "30000",
    "unitPrice": "2.65486726",
    "taxTotal": "90000",
    "shipment": {
      "mailNo": "SF5112860018518",
      "status": "in_transit",
      "statusLabel": "运输中",
      "routes": [{"acceptTime":"...","acceptAddress":"珠海市","remark":"顺丰速运 已收取快件","opCode":"54"}],
      "routeCount": 4
    }
  }]
}
}
```

## 关键配置

- 顺丰生产 partnerID: BRSWK5CQ08HV
- 顺丰生产 secret: (见 references/sf-express-tracking-api.md)
- MCP 空间: `销售管理`，类型: `销售订单` (662612aea6bb7089fea044ef)
- 输出路径: `数据/shipment_status.json`

## 后续：设置 cron\n\n建议每天运行一次，刷新所有未签收订单的物流状态。配合工作台 `refreshData()` 即可实现到货弹窗。\n\n## H1/H2 数据分层归档\n\n详见 `baoyu-workbench-patterns/references/h1-h2-data-archiving.md`。\n\n- H1（≤6/30）：全部归档为 `h1_archive.json`（3KB汇总），季度末手动更新\n- H2 已签收>7天：自动归档至H1，从实时数据移除\n- H2 实时：保留在 `shipment_status.json`，cron每日刷新\n- 前端的全年统计：`shipment_status.json` 携带 `h1_summary` + `full_year_tax` 字段

## MCP 数据拉取（分页技巧）

MCP `search_by_mql` 每页限制 **50 条**。推荐使用 `LIMIT offset, count` 进行分页：

```sql
-- 第1页（offset 0）
SELECT ... FROM ... WHERE ... ORDER BY `创建时间` DESC LIMIT 50
-- 第2页（offset 50）
SELECT ... FROM ... WHERE ... ORDER BY `创建时间` DESC LIMIT 50, 50
-- 第3页（offset 100）
SELECT ... FROM ... WHERE ... ORDER BY `创建时间` DESC LIMIT 50, 100
```

**陷阱：`group_pagination_list` + `session_id` 方式不可靠**，测试中发现返回重复数据。

3067 条匹配记录 ≈ 62 页。手动逐页拉取耗时，全量数据建议使用 DeepSeek V4 Pro 并行拉取（模型协作规则：V4=数据处理）。

## 顺丰 Token 刷新

accessToken 有效期约 2 小时。管道脚本中每 30 批次刷新一次 token，避免长时间运行中断。