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:
parent
c1d3e17188
commit
673bd0bef3
122
WMS-OMS-取号对接.md
122
WMS-OMS-取号对接.md
@ -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` 即可,
|
||||
无需新增数据库字段。当前不阻塞打印。
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user