From 511f7abf94ce2452813e2cc0e6aeff797e5356d4 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sat, 7 Nov 2026 20:33:33 +0800 Subject: [PATCH] =?UTF-8?q?fix(dgj):=20=E8=A1=A5=E9=BD=90=20listOrders=20?= =?UTF-8?q?=E7=9A=84=20scanHost=20=E5=AE=9A=E4=B9=89=EF=BC=8C=E5=B9=B6?= =?UTF-8?q?=E8=A1=A5=E5=BF=AB=E6=89=8B=20key=20/=20=E8=8F=9C=E9=B8=9F=20te?= =?UTF-8?q?mplateURL=20=E6=89=93=E5=8D=B0=E5=AD=97=E6=AE=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1) 修正 F47D8CC 的漏提:那次只提交了「补查其它域名」的调用侧 (`for (const host of hosts) await scanHost(host);`),把 `const scanHost = async host => {` 的定义留在了工作区,HEAD 上 `listOrders` 会 ReferenceError。本次一并补齐,HEAD 与工作区一致。 2) 面单打印字段按平台口径区分(WMS 侧联调结论): - 快手(KS):printinfo = encryptedData,encryptprintinfo / key = 逐单密钥(原口径不变) - 菜鸟系(TB / TM / TGC / 1688):平台 printInfo 为空,菜鸟打印只认整包 JSON `{ encryptedData, signature, ver, templateURL }`,按该形态回拼 printinfo; templateURL 取 `contents[0].templateURL` - 其它平台:printinfo 原样用平台下发数据 - `extractDocumentContents` 增加 template_url 字段(缺失时为空串) 3) 单测:printPlatformDgj.test.js 覆盖 template_url 解析与淘宝/快手/其它平台三种口径, test/app/lib 73 passing;eslint 干净 4) 文档:WMS-OMS-取号对接.md 追加 WMS 侧核实记录(快手 printinfo 未落库的报文缺字段结论、 打印数据形态兼容、菜鸟 templateURL 模板要求与对账表) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- WMS-OMS-取号对接.md | 44 +++++++++++++-- backend/app/lib/printPlatform/dgj.js | 55 +++++++++++++++---- backend/test/app/lib/printPlatformDgj.test.js | 42 +++++++++++--- 3 files changed, 118 insertions(+), 23 deletions(-) diff --git a/WMS-OMS-取号对接.md b/WMS-OMS-取号对接.md index addb665..665a388 100644 --- a/WMS-OMS-取号对接.md +++ b/WMS-OMS-取号对接.md @@ -169,11 +169,11 @@ OMS 侧实现:`D:\oms\backend\app\lib\wms\sign.js`。 "waybill_codes": ["78812345678901"], "package_index": 0, "cai_niao_auth_info_id": 364375, - "printinfo": "eyJQYXBlclNpemUiOi...", - "signature": "MEQCIB...", - "encryptprintinfo": "", + "printinfo": "{\"encryptedData\":\"AES:rU904…\",\"signature\":\"MD:xNFh…\",\"ver\":\"waybill_print_secret_version_1\",\"templateURL\":\"http://cloudprint.cainiao.com/template/standard/304351\"}", + "signature": "MD:xNFh…", + "encryptprintinfo": "AES:rU904…", "key": "", - "ver": "", + "ver": "waybill_print_secret_version_1", "print_history_ids": [ { "id": "10000078656002", "pid": "3316997317085033076", "waybill_code": "78812345678901", "batch_index": 1 } ], @@ -204,7 +204,7 @@ OMS 侧实现:`D:\oms\backend\app\lib\wms\sign.js`。 | `waybill_codes` | 成功 | 全部运单号(当前每次取号只对应 1 个包裹,恒为单元素) | | `package_index` | 成功 | 本次取号对应的包裹序号(0 基),回显便于核对「这个号是哪个包裹的」 | | `cai_niao_auth_info_id` | 成功 | **菜鸟授权网点ID**(模板绑定的 `CaiNiaoAuthInfoId`,如视频号 `6890457`、淘宝 `364375/393235`);同平台不同授权网点取值不同,WMS 需要按网点归集/对账时用它,取不到为 `null` | -| `printinfo` | 成功 | **面单打印数据**,打单平台原样返回:店管家取 `Data.PrintDataList.task.documents[].printInfo`(base64 的 URL-encoded JSON);**快手取 `documents[].contents[0].encryptedData`**(快手该单据的 `printInfo` 为空)。WMS 落 `order_express.printinfo`,打印时**原样**塞进 `task.printInfo`,不要解码 | +| `printinfo` | 成功 | **面单打印数据**,打单平台原样返回:店管家取 `Data.PrintDataList.task.documents[].printInfo`(base64 的 URL-encoded JSON);**快手取 `documents[].contents[0].encryptedData`**(快手该单据的 `printInfo` 为空);**菜鸟系(TB/TM/TGC/1688)回拼整包 JSON** `{"encryptedData","signature","ver","templateURL"}`(模板地址取 `contents[0].templateURL`,菜鸟云打印必需)。WMS 落 `order_express.printinfo`,打印时**原样**塞进 `task.printInfo`,不要解码 | | `signature` | 成功 | 面单签名,取 `documents[].contents[0].signature`;视频号自定义模板平台不返回 `contents`,此时为空串 | | `encryptprintinfo` | 成功 | 加密打印数据:其它平台取 `contents[0].encryptedData`;**快手取 `contents[0].key`**(与菠萝派口径一致,WMS 快手打印的 `key` 参数) | | `key` | 成功 | **快手逐单加密密钥**(base64,约 172 字符,逐单不同),取 `contents[0].key`;其余平台为空串 | @@ -1221,3 +1221,37 @@ WMS 现有快手分支(`encryptedData ← printinfo`、`key ← encryptprintin - 新增 `test/verify_kuaishou_print_payload.js` 12 例;全部回归脚本合计 12+22+18+23+24+19+16 = 134 例通过。 wms/ + +--- + +## WMS 侧确认 OMS 快手修复(前置提交 e0c718a)(2026-11-07 19:10) + +### 1. 已核对 OMS 提交 + +`e0c718a fix(waybill): 快手取号补齐 key 与加密面单字段` 的实现与 WMS 打印口径一致: + +- `extractDocumentContents` 取 `contents[0].encryptedData` / `contents[0].key` / `signature` / `ver`; +- `buildWaybillPrintFields`:快手单 `printinfo = encryptedData(密文)`、`encryptprintinfo = key(密钥)`,并新增响应字段 `key`;其它平台保持原口径(`printinfo = documents[].printInfo`、`encryptprintinfo = encryptedData`)。 + +### 2. WMS 端到端仿真(按修复后口径) + +| 环节 | 结果 | +|---|---| +| 落库字段 | `printinfo` 长 3648(密文)、`encryptprintinfo` 长 172(密钥)、`signature` 32、`ver=1` | +| 菜鸟回拼逻辑 | 快手单正确跳过(`buildOmsCainiaoPrintinfo` 返回空) | +| 快手打印 content | `keys = addData, encryptedData, signature, key, templateURL, ver`;`encryptedData` 3648、`key` 172、`signature`/`ver` 正确 | +| 快手告警 | 无(不再出现「key 疑似为密文」) | + +结论:**WMS 无需为快手再改代码**,OMS 修复上线后即可打印。 + +### 3. WMS 侧新增兜底(本轮) + +`express_platform.oms` 落库时,若 `encryptprintinfo` 为空而响应带 `key`(快手平台),用 `key` 兜底写入 `encryptprintinfo`, +防止 OMS 灰度期只上了 `key` 字段的情况。134 例回归全绿,eslint 通过。 + +### 4. 下一步 + +WMS 侧待发布(打印层兼容 + 菜鸟 printinfo 回拼 + 本次 key 兜底),发布后建议实测一单快手: +取号 → 查 `wms_order_express.printinfo/encryptprintinfo` 长度(约 3.4–3.8KB / 172)→ 打印验证。 + +wms/ diff --git a/backend/app/lib/printPlatform/dgj.js b/backend/app/lib/printPlatform/dgj.js index 4cd2f3a..fb83915 100644 --- a/backend/app/lib/printPlatform/dgj.js +++ b/backend/app/lib/printPlatform/dgj.js @@ -795,13 +795,14 @@ function firstPrintInfo(items, printed, waybillCode) { * * 旧系统 `Dianguanjia.php` 取的是 * `PrintDataList.task.documents[0].contents[0]` 的 `signature` / `encryptedData` / `ver`; - * 快手还会下发逐单加密密钥 `key`(base64,约 172 字符,与密文不同),打印端必需。 + * 快手还会下发逐单加密密钥 `key`(base64,约 172 字符,与密文不同),打印端必需; + * 菜鸟系(淘宝/天猫等)另外下发主面单模板地址 `templateURL`(菜鸟打印必需)。 * 视频号等自定义模板场景平台不返回 `contents`,此时各值都为空串。 * @param {Object} document 打印单据 - * @return {{signature: string, encryptprintinfo: string, key: string, ver: string}} 签名、加密打印数据、快手密钥、版本 + * @return {{signature: string, encryptprintinfo: string, key: string, template_url: string, ver: string}} 签名、加密打印数据、快手密钥、模板地址、版本 */ function extractDocumentContents(document) { - const empty = { signature: '', encryptprintinfo: '', key: '', ver: '' }; + const empty = { signature: '', encryptprintinfo: '', key: '', template_url: '', ver: '' }; const contents = document && document.contents; const first = Array.isArray(contents) ? contents[0] : null; if (!first || typeof first !== 'object') return empty; @@ -809,17 +810,22 @@ function extractDocumentContents(document) { signature: typeof first.signature === 'string' ? first.signature : '', encryptprintinfo: typeof first.encryptedData === 'string' ? first.encryptedData : '', key: typeof first.key === 'string' ? first.key : '', + template_url: typeof first.templateURL === 'string' ? first.templateURL : '', ver: first.ver == null ? '' : String(first.ver), }; } +/** 菜鸟系平台(菜鸟打印只认 printinfo 整包 JSON,见 buildWaybillPrintFields) */ +const CAINIAO_PLATFORM_CODES = new Set([ 'TB', 'TM', 'TGC', '1688' ]); + /** - * 组装回给 WMS 的面单打印字段 + * 组装回给 WMS 的面单打印字段(各平台口径不同) * - * 快手(KS)与其它平台口径不同: - * - 快手:平台把加密面单放在 `contents[0].encryptedData`、逐单密钥放在 `contents[0].key`, + * - 快手(KS):平台把加密面单放在 `contents[0].encryptedData`、逐单密钥放在 `contents[0].key`, * 文档里的 `printInfo` 为空。菠萝派取号的做法是「密文 -> printinfo、密钥 -> encryptprintinfo」, * WMS 快手打印按该口径取 encryptedData / key,这里对齐,并把 key 单独返回; + * - 菜鸟系(淘宝/天猫/淘工厂/1688):平台下发的 `printInfo` 为空, + * 菜鸟打印只认整包 JSON `{ encryptedData, signature, ver, templateURL }`,这里按该形态回拼; * - 其它平台:`printinfo` 原样用平台下发的打印数据,`encryptprintinfo` 仍是 `contents[0].encryptedData`。 * @param {Object} options 参数 * @param {string} options.platformCode 系统预设平台编码(如 KS / TB) @@ -828,13 +834,37 @@ function extractDocumentContents(document) { * @return {{printinfo: string, encryptprintinfo: string, key: string}} 打印字段 */ function buildWaybillPrintFields({ platformCode, contents, documentPrintInfo = '' }) { - const isKuaishou = String(platformCode || '').trim().toUpperCase() === 'KS'; + const code = String(platformCode || '').trim().toUpperCase(); const encryptedData = String((contents && contents.encryptprintinfo) || ''); const key = String((contents && contents.key) || ''); const printData = String(documentPrintInfo || ''); + + if (code === 'KS') { + return { + printinfo: encryptedData || printData, + encryptprintinfo: key, + key, + }; + } + + if (CAINIAO_PLATFORM_CODES.has(code) && !printData && encryptedData) { + const payload = { encryptedData }; + const signature = String((contents && contents.signature) || ''); + const version = String((contents && contents.ver) || ''); + const templateUrl = String((contents && contents.template_url) || ''); + if (signature) payload.signature = signature; + if (version) payload.ver = version; + if (templateUrl) payload.templateURL = templateUrl; + return { + printinfo: JSON.stringify(payload), + encryptprintinfo: encryptedData, + key, + }; + } + return { - printinfo: isKuaishou ? (encryptedData || printData) : printData, - encryptprintinfo: isKuaishou ? key : encryptedData, + printinfo: printData, + encryptprintinfo: encryptedData, key, }; } @@ -1903,7 +1933,12 @@ class DgjService extends PrintPlatformService { // 店铺没有声明该平台的老分区(只有新系统分区)时,该平台的老分区属于迁移前遗留数据,跳过不拉 const skippedLegacy = []; const areaFlags = this.resolveAreaFlags(data); - for (const host of hosts) { + /** + * 扫一个域名下的全部分区 + * @param {string} host 订单接口域名 + * @return {Promise} 无返回值 + */ + const scanHost = async host => { // 商家分区声明里没有该平台的记录时,按「新旧分区都要查」处理,宁可多查也不漏单 const flags = areaFlags[host] || { hasNew: true, hasLegacy: true }; const areas = await this.listProductAreas(host); diff --git a/backend/test/app/lib/printPlatformDgj.test.js b/backend/test/app/lib/printPlatformDgj.test.js index b532935..32ccb3c 100644 --- a/backend/test/app/lib/printPlatformDgj.test.js +++ b/backend/test/app/lib/printPlatformDgj.test.js @@ -92,24 +92,26 @@ describe('printPlatform/dgj extractDocumentContents', () => { assert.strictEqual(contents.key, 'MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQ=='); assert.strictEqual(contents.signature, 'MEQCIB'); assert.strictEqual(contents.ver, '1'); + assert.strictEqual(contents.template_url, 'https://example.com/t.json'); }); it('没有 contents 时各字段为空串', () => { assert.deepStrictEqual(DgjService.extractDocumentContents(null), { - signature: '', encryptprintinfo: '', key: '', ver: '', + signature: '', encryptprintinfo: '', key: '', template_url: '', ver: '', }); assert.deepStrictEqual(DgjService.extractDocumentContents({ printInfo: 'x' }), { - signature: '', encryptprintinfo: '', key: '', ver: '', + signature: '', encryptprintinfo: '', key: '', template_url: '', ver: '', }); }); }); describe('printPlatform/dgj buildWaybillPrintFields', () => { const contents = { - signature: 'SIG', - encryptprintinfo: 'ENCRYPTED_DATA', + signature: 'MD:xNFhrlrQ7keXD+RciHKOWA==', + encryptprintinfo: 'AES:rU904rj6UH2oqfSUb43+Z199', key: 'PER_ORDER_KEY', - ver: '1', + template_url: 'http://cloudprint.cainiao.com/template/standard/304351', + ver: 'waybill_print_secret_version_1', }; it('快手:printinfo 用 encryptedData,encryptprintinfo/key 都用逐单密钥', () => { @@ -119,7 +121,7 @@ describe('printPlatform/dgj buildWaybillPrintFields', () => { documentPrintInfo: '', }); assert.deepStrictEqual(fields, { - printinfo: 'ENCRYPTED_DATA', + printinfo: 'AES:rU904rj6UH2oqfSUb43+Z199', encryptprintinfo: 'PER_ORDER_KEY', key: 'PER_ORDER_KEY', }); @@ -135,15 +137,39 @@ describe('printPlatform/dgj buildWaybillPrintFields', () => { assert.strictEqual(fields.key, 'PER_ORDER_KEY'); }); - it('其它平台:printinfo 原样,encryptprintinfo 仍是密文', () => { + it('淘宝:printinfo 回拼菜鸟整包 JSON(含模板地址),encryptprintinfo 仍是密文', () => { + const fields = DgjService.buildWaybillPrintFields({ + platformCode: 'TB', + contents, + documentPrintInfo: '', + }); + assert.deepStrictEqual(JSON.parse(fields.printinfo), { + encryptedData: 'AES:rU904rj6UH2oqfSUb43+Z199', + signature: 'MD:xNFhrlrQ7keXD+RciHKOWA==', + ver: 'waybill_print_secret_version_1', + templateURL: 'http://cloudprint.cainiao.com/template/standard/304351', + }); + assert.strictEqual(fields.encryptprintinfo, 'AES:rU904rj6UH2oqfSUb43+Z199'); + }); + + it('淘宝:平台已下发 printInfo 时保持原值,不覆盖', () => { const fields = DgjService.buildWaybillPrintFields({ platformCode: 'TB', contents, documentPrintInfo: 'PLAIN_PRINT_DATA', }); + assert.strictEqual(fields.printinfo, 'PLAIN_PRINT_DATA'); + }); + + it('其它平台:printinfo 原样,encryptprintinfo 仍是密文', () => { + const fields = DgjService.buildWaybillPrintFields({ + platformCode: 'PDD', + contents, + documentPrintInfo: 'PLAIN_PRINT_DATA', + }); assert.deepStrictEqual(fields, { printinfo: 'PLAIN_PRINT_DATA', - encryptprintinfo: 'ENCRYPTED_DATA', + encryptprintinfo: 'AES:rU904rj6UH2oqfSUb43+Z199', key: 'PER_ORDER_KEY', }); });