docs: 新增顺运宝接口契约;config.yaml 加入 gitignore

从 4 份 HAR 抓包和示例脚本还原 docs/admin/08-顺运宝接口.md。
全部结论标了出处,只有单一样本支撑的都标了 [待定]。

抓包验出三件和现有假设不符的事:

1. 登录响应的 JWT 从不参与请求,认证全靠 Cookie。示例脚本里
   self.token 只用于算缓存有效期,没进过任何请求头。Go 侧存 Cookie
   即可,token 都不用存。

2. _capture_refreshed_token 是死代码——它从响应头 X-Requested-With
   读刷新后的 JWT,而 4 份 HAR 共 18 个响应里带该头的是 0 个。
   会话就是 24 小时硬上限,没有滚动续期,不要移植这段逻辑。

3. 金额单位在同一个响应里不统一:amtOrder 在列表接口是分(61200
   对应 612.0),escrowAmount 却不是(505 对应 505.0)。不能假设
   "列表接口的金额都是分",逐字段确认。这条只有一个样本,已标 [待定]。

还推翻了「货运单规格能直接对上蝦皮商品規格ID」这个前提:顺运宝给的
productId 是 11 位商品ID,蝦皮規格ID 是 12 位。但 productSpec 的格式
与蝦皮报表完全一致,可直接复用 #38 的 ParseSpec,匹配走
"productId 定位商品 → 解析规格 → 在该商品的 SKU 里比对"。

admin/config.yaml 含明文密码且此前没有任何 gitignore 规则挡它,
一次目录级 git add 就会进历史。已加规则,并补 config.example.yaml
作为模板(不含真实凭据,进 git)。

已确认历史提交中从未出现过该凭据。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
chengma
2026-08-09 10:59:00 +08:00
co-authored by Claude Opus 5
parent 5fd71981e0
commit 512ccf34d6
4 changed files with 439 additions and 0 deletions
+2
View File
@@ -49,6 +49,7 @@
| 改页面、加表格列 | [05 界面规范](admin/05-ui-specification.md) | [02 架构](admin/02-architecture.md) §4 模板 |
| 加字段、改表、写 SQL | [03 数据模型](admin/03-data-model.md) | [02 架构](admin/02-architecture.md) §2 分层 |
| 改 Excel 导入 | [03 数据模型](admin/03-data-model.md) §3.3 | [00 术语表](admin/00-glossary.md) §3 upsert |
| 改顺运宝同步 | [08 顺运宝接口](admin/08-顺运宝接口.md) | [03 数据模型](admin/03-data-model.md) |
| 改给 Client 的接口 | [04 Client 接口实现](admin/04-client-api.md) | [Client 侧契约](client/04-admin-api-contract.md) |
| 和 Admin 联调、登记新设备 | [07 设备登记联调手册](admin/07-设备登记联调手册.md) | [Client 侧契约](client/04-admin-api-contract.md) §5 |
| 写测试 | [06 质量与安全](admin/06-quality-security.md) §2 | — |
@@ -88,6 +89,7 @@
| [05 界面规范](admin/05-ui-specification.md) | 三段式布局、五个页面、弹窗 |
| [06 质量、安全与测试](admin/06-quality-security.md) | 测试、Web 安全、发布门禁 |
| [07 设备登记联调手册](admin/07-设备登记联调手册.md) | **给 Client 开发者**:怎么让新设备登记成功 |
| [08 顺运宝接口](admin/08-顺运宝接口.md) | 从抓包还原的外部 ERP 契约:登录、会话、货运单列表与明细 |
## 文档标注说明