# 顺丰物流管线 · 完整调试记录

## 背景
宝锐用顺丰月结发货，需通过丰桥 API 查询物流路由。

## 配置

```
partnerID: BRSWK5CQ08HV
secret: V7JDT0azGX93pnIXRyZe9zvlzY6fk1rC
月结卡号: 7561222900
注册手机: 18666926804
checkPhoneNo: 收件人手机后4位（非月结卡/注册号）
```

## 根因链条（2026-07-30 完整调试）

| # | 现象 | 测试 | 结论 |
|---|------|------|------|
| 1 | 661条"月结卡号不匹配" | 不带checkPhoneNo | checkPhoneNo是必传参数 |
| 2 | 6804"手机号校验失败" | 宝锐注册手机 | checkPhoneNo校验收件人号，非平台注册号 |
| 3 | 0727通过（1条） | 收件人后4位 | 必须用每笔订单的收件人手机号 |
| 4 | 批量10条仅1条通过 | 同phone4分组 | **SF API 批量查询只校验第一个单号** |
| 5 | 同一组9条全失败 | 同电话不同订单 | 即使phone4相同，SF对每个运单独立校验 |
| 6 | 289→363成功 | 改逐条查询 | 逐条查询解决批量限制 |
| 7 | 398仍失败 | 时序延迟 | SF需订单创建后数小时才有路由数据 |

## 最终方案

- **查询方式**：逐条（非批量），每条传 `checkPhoneNo=收件人后4位`
- **脚本**：
  - `~/.hermes/scripts/sf_delivery_watchdog.py` — 每日 cron
  - `脚本/sf_bulk_refresh.py` — 手动全量刷新
- **覆盖率**：66%（1349/2054 有路由），剩余 35 条缺收件人号/未发货

## 数据管道

```
MCP 销售订单 → shipment_pipeline.py → shipment_status.json
                 ↓
         sf_delivery_watchdog.py（逐条查SF路由）
                 ↓
         tcb deploy → CloudBase → 工作台订单管理页
```