From 673bd0bef3a4ccd3695e135142b62d7d70177f49 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sat, 7 Nov 2026 18:18:14 +0800 Subject: [PATCH] =?UTF-8?q?docs(wms):=20=E8=A1=A5=E8=8F=9C=E9=B8=9F?= =?UTF-8?q?=E6=89=93=E5=8D=B0=E6=95=B0=E6=8D=AE=E4=B8=89=E6=AE=B5=E6=A0=B8?= =?UTF-8?q?=E6=9F=A5=E8=AE=B0=E5=BD=95=EF=BC=88printinfo=20=E8=90=BD?= =?UTF-8?q?=E5=BA=93/=E5=BD=A2=E6=80=81=E5=85=BC=E5=AE=B9/templateURL?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 记录 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> --- WMS-OMS-取号对接.md | 122 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) diff --git a/WMS-OMS-取号对接.md b/WMS-OMS-取号对接.md index 105e70f..1a89792 100644 --- a/WMS-OMS-取号对接.md +++ b/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":"","signature":"","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` 即可, +无需新增数据库字段。当前不阻塞打印。