docs(wms): 补菜鸟打印数据三段核查记录(printinfo 落库/形态兼容/templateURL)

记录 WMS 侧 2026-11-07 17:40 ~ 18:15 的三轮核查与修复:

1. OMS 淘宝(菜鸟)printinfo 落库不一致
   - 生产对照菠萝派菜鸟:signature / encryptprintinfo / ver 一致,仅 printinfo 为空
   - 影响:WMS 菜鸟主面单只从 printinfo 取,为空会退化为模板兜底,打印结果不一致
   - WMS 侧新增 buildOmsCainiaoPrintinfo 回拼;自测 18 例通过;需随 WMS 发布生效
2. 打印数据格式不对
   - printinfo 形态兼容(字符串/对象、encryptedData/encryptprintinfo 两种命名)
3. 菜鸟 templateURL 模板要求
   - 模板 ID 与接口配置逐一对账一致(申通 288948 / 韵达 288658 / 中通 300336 / 京东 776130)
   - printer_data_builder.js 模板地址改三级来源并告警兜底;回归 122 例通过
   - 建议(不阻塞)OMS 在 deliveryorder.getwaybill 补 template_url

顺手去掉文末多余的 wms/ 占位行。

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-07 18:18:14 +08:00
parent c1d3e17188
commit 673bd0bef3

View File

@ -1049,3 +1049,125 @@ WMS 侧排查「回调到底有没有到、报了什么」只能翻服务器日
**日志表大的话要选低峰执行**(重建期间该表不可写);
2. 只保留 10 天意味着**历史日志会被物理删除**,需要留存的话先备份/导出;
3. 任务失败不会重试,失败原因写在 `logs/oms/oms-error.log` 的 `[log-retention]` 前缀里。
---
## WMS 侧核实并修复「OMS 淘宝(菜鸟)printinfo 落库不一致」(2026-11-07 17:40)
### 1. 核实结论(生产数据)
对照 OMS 返回的淘宝单(`delivery_order_code=dgj-10000283327758`,`waybill_code=773450695620554`)与菠萝派菜鸟取号的落库形态:
| 字段 | 菠萝派菜鸟(抽样 id=1773910) | OMS 淘宝(id=1769366) | 结论 |
|---|---|---|---|
| `printinfo` | 2312 字节 JSON:`{"encryptedData":"AES:…","signature":"MD:…","templateURL":"…","ver":"waybill_print_secret_version_1"}` | 空串(落库 NULL) | ❌ 不一致 |
| `signature` | `MD:` 前缀 / 27 字符 | `MD:` 前缀 / 27 字符 | ✅ |
| `encryptprintinfo` | `AES:` 前缀 / ≈2.1KB | `AES:` 前缀 / 2268 | ✅ |
| `ver` | `waybill_print_secret_version_1` | 同 | ✅ |
| `platform_code` | `CAINIAO` | `CAINIAO`(TB → print_platform_id=2) | ✅ |
统计(`create_at >= 2026-11-01`):`CAINIAO` 共 21,784 单,`printinfo` 为空的仅 1 条,即上述 OMS 淘宝单。
### 2. 影响
WMS 菜鸟打印主面单**只从 `printinfo` 取**(`resolveCainiaoMainContentFromPrintinfo`),支持
`{ encryptedData, signature, ver, templateURL }` 这形态;`encryptprintinfo/signature/ver` 在菜鸟打印分支里**不被读取**
(只有拼多多、快手、抖音分支读)。`printinfo` 为空时会退化为 `_dataFrom='template'` 的模板兜底,
打印结果与正常菜鸟单不一致。
### 3. 修复(已改代码,待发布)
`app/service/systems/express_platform.js#oms` 落库时新增 `buildOmsCainiaoPrintinfo`:
- 触发条件:归一后平台码为 `CAINIAO`(或归一失败遗留的 `TB`)、`printinfo` 为空、`encryptprintinfo` 非空;
- 输出:`{"encryptedData":"<encryptprintinfo 原样>","signature":"<signature 原样>","ver":"<ver 原样>"}`,
`AES:` / `MD:` 前缀原样保留、不解码,与菠萝派菜鸟 `printinfo` 同构;
- `templateURL` 仍由打印链路 `enrichCainiaoOrderExpressRows` 按接口配置补 `cainiao_template_url`;
- 抖音 / 拼多多分支不动(它们直接读 `encryptprintinfo`)。
验证:`test/verify_oms_cainiao_printinfo.js` 18 例通过,其中包含「回拼后的 printinfo 直接被菜鸟打印组装消费
(主面单带 encryptedData/signature/ver,不再走模板兜底)」的端到端断言。
### 4. 待办
- 本次修复需随 WMS 发布上线才生效;生产当前 `express_platform.js` 为 2026-11-07 06:17 版本,不含该修复。
- 存量那 1 条(`wms_order_express.id=1769366`)`printinfo` 仍为空,按确认暂不做数据订正。
wms/
---
## WMS 侧定位「打印数据格式不对」并加 printinfo 形态兼容(2026-11-07 18:10)
### 1. 现象与根因
生产 `wms_order_express.id=1769366`(运单 `773450695620554`)的 `printinfo` 被填成了**裸密文** `AES:rU904…`(2268 字符),
而不是菜鸟要求的整包 JSON。菜鸟主面单解析逻辑 `resolveCainiaoMainContentFromPrintinfo` 需要 JSON,
裸密文解析失败 → `hasPrintinfoMainContent=false` → 退化成 `buildCainiaoFallbackMainData`(`_dataFrom='template'`),
所以打印出来的主面单是模板占位(`waybillCode: ""`、`recipient` 全空),与接口返回的现象完全一致。
用生产真实行离线复现:
| printinfo 形态 | 主面单 keys | 说明 |
|---|---|---|
| `AES:rU904…`(当前库值) | `templateURL, data`(`_dataFrom=template`) | 旧行为,模板兜底 |
| `{"encryptedData":"AES:…","signature":"MD:…","ver":"…"}` | `encryptedData, signature, ver` | 正确形态 |
### 2. 修复(两层)
1. **落库层**(`express_platform.js#buildOmsCainiaoPrintinfo`,上一轮已加):OMS 淘宝单自动回拼整包 JSON。
2. **打印层**(本轮新增,`printer_data_builder.js`):菜鸟分支在 `printinfo` 缺失或非 JSON 时,
用 `encryptprintinfo` + `signature` + `ver` 回拼加密面单 content,不再直接退化成模板;
真正缺密文时才回退模板并给出「菜鸟 printinfo 为空且缺少 encryptprintinfo,已回退模板骨架」告警。
同时 `resolveCainiaoMainContentFromPrintinfo` 增加 `warnOnFailure` 开关,避免有兜底时误报「已回退模板骨架」。
### 3. 影响面
- 存量那条 `printinfo=裸密文` 的单**无需改数据**,上线后即可正常打印;
- 明文 `data` 形态(`_dataFrom=printinfo`)、抖音/拼多多/快手分支均不受影响(已用矩阵用例覆盖)。
### 4. 验证
`test/verify_cainiao_print_payload.js`:17 例(空 printinfo、裸密文、整包 JSON、双缺失回退、明文 data 不回归、非菜鸟平台)。
全部回归脚本合计 17+18+23+24+19+16 = 117 例通过,eslint 通过。
wms/
---
## WMS 侧处理「菜鸟 templateURL 模板要求」(2026-11-07 18:15)
### 1. 现状核实(生产数据)
菜鸟加密面单的主 content 需要 `templateURL` 才能渲染,现有链路已经保证:
- `enrichCainiaoOrderExpressRows` 按快递编码匹配 `wms_express_interface.template_url` → 写运行时字段 `cainiao_template_url`;
- 打印组装时 `applyCainiaoExpressFieldMapping` 用该值覆盖 `contents[0].templateURL`(示例响应里的
`https://cloudprint.cainiao.com/template/standard/288948/112` 就来自这里)。
模板 ID 对账(`wms_express_interface` 配置 vs 菠萝派菜鸟 `printinfo` 内嵌):
| 快递 | 接口配置 | printinfo 内嵌 | 模板 ID |
|---|---|---|---|
| 申通 | `…/template/standard/288948/112` | `http://cloudprint.cainiao.com/template/standard/288948` | 288948 ✅ |
| 韵达 | `…/288658/79` | `…/288658` | 288658 ✅ |
| 中通 | `…/300336/97` | `…/300336` | 300336 ✅ |
| 京东 | `…/776130/7` | `…/776130` | 776130 ✅ |
结论:模板 ID 完全一致,差异只有 `http/https` 与是否带版本段(`/112`),菜鸟云打印按同一模板 ID 渲染,**无需改配置或数据**。
### 2. 本轮新增兜底(`printer_data_builder.js`)
主 content 的模板地址改为三级来源,避免 content 被整体替换(加密面单/模板兜底)后丢模板地址:
1. `cainiao_template_url`(接口配置,最高优先,保持原行为);
2. 未配置时 → 模板样例里的 `contents[0].templateURL`;
3. 两者都没有 → 保留加密字段并告警「菜鸟主面单缺少 templateURL(接口未配置 template_url 且模板样例为空)」。
验证:`test/verify_cainiao_print_payload.js` 扩到 22 例(含模板三级来源),全部回归脚本 22+18+23+24+19+16 = 122 例通过。
### 3. 可选增强(需 OMS 配合)
若要严格保证「模板与密文同源」,建议 OMS 在 `deliveryorder.getwaybill` 响应里补一个 `template_url`
(`deliveryorder.getprintdata` 已返回同名字段),WMS 回拼 printinfo 时写进 `templateURL` 即可,
无需新增数据库字段。当前不阻塞打印。