diff --git a/WMS-OMS-取号对接.md b/WMS-OMS-取号对接.md index 1a89792..addb665 100644 --- a/WMS-OMS-取号对接.md +++ b/WMS-OMS-取号对接.md @@ -171,6 +171,9 @@ OMS 侧实现:`D:\oms\backend\app\lib\wms\sign.js`。 "cai_niao_auth_info_id": 364375, "printinfo": "eyJQYXBlclNpemUiOi...", "signature": "MEQCIB...", + "encryptprintinfo": "", + "key": "", + "ver": "", "print_history_ids": [ { "id": "10000078656002", "pid": "3316997317085033076", "waybill_code": "78812345678901", "batch_index": 1 } ], @@ -201,15 +204,16 @@ 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)。WMS 落 `order_express.printinfo`,打印时**原样**塞进 `task.printInfo`,不要解码 | +| `printinfo` | 成功 | **面单打印数据**,打单平台原样返回:店管家取 `Data.PrintDataList.task.documents[].printInfo`(base64 的 URL-encoded JSON);**快手取 `documents[].contents[0].encryptedData`**(快手该单据的 `printInfo` 为空)。WMS 落 `order_express.printinfo`,打印时**原样**塞进 `task.printInfo`,不要解码 | | `signature` | 成功 | 面单签名,取 `documents[].contents[0].signature`;视频号自定义模板平台不返回 `contents`,此时为空串 | -| `encryptprintinfo` | 成功 | 加密打印数据,取 `contents[0].encryptedData`(需要加密打印的平台才有值,店管家当前为空串) | +| `encryptprintinfo` | 成功 | 加密打印数据:其它平台取 `contents[0].encryptedData`;**快手取 `contents[0].key`**(与菠萝派口径一致,WMS 快手打印的 `key` 参数) | +| `key` | 成功 | **快手逐单加密密钥**(base64,约 172 字符,逐单不同),取 `contents[0].key`;其余平台为空串 | | `ver` | 成功 | 打印数据版本,取 `contents[0].ver`(无则为空串) | | `print_history_ids` | 成功 | **打印记录ID**(店管家 `Data.PrintHistoryIds[]`):`[{ id, pid, waybill_code, batch_index }]`,每张面单一条,WMS 自行落库。`id` 即 printHistoryId,`WaybillCode` 与 `waybill_codes` 一一对应;平台**不会**把它放进面单数据(`printinfo` 里对应字段恒为 `null`) | | `print_history_id` | 成功 | 第一张面单的打印记录ID(`print_history_ids[0].id` 的便捷值,多包裹时以数组为准) | > **取号结果不回写 OMS 订单表**(现阶段取号与订单表不做关联),运单号与打印数据只在响应里返回,由 WMS 自行落单。 -> **WMS 仍需落自己的 `order_express`**(`waybill_code` + `printinfo` + `signature` + `encryptprintinfo` + `ver` + `cai_niao_auth_info_id` + `print_history_ids`)**/ 队列状态**,不要依赖 OMS 的库。 +> **WMS 仍需落自己的 `order_express`**(`waybill_code` + `printinfo` + `signature` + `encryptprintinfo` + `ver` + `cai_niao_auth_info_id` + `print_history_ids`,快手另有 `key`)**/ 队列状态**,不要依赖 OMS 的库。 > 每次取号的平台原始返回都会写进 OMS 的 `waybill_fetch_records`(见 §4.7),出问题可直接查表对账,不必再让 WMS 重放报文。 > > **同一包裹重复取号会拿到新号**:店管家「新单号打印」口径是每次分配一个新号(`WaybillCodePid` 第二段自增), @@ -1171,3 +1175,49 @@ wms/ 若要严格保证「模板与密文同源」,建议 OMS 在 `deliveryorder.getwaybill` 响应里补一个 `template_url` (`deliveryorder.getprintdata` 已返回同名字段),WMS 回拼 printinfo 时写进 `templateURL` 即可, 无需新增数据库字段。当前不阻塞打印。 + +--- + +## WMS 侧核实快手(KS)printinfo 未落库 —— 结论:报文缺字段(2026-11-07 18:45) + +### 1. 字段对照(生产实测 + 本次 OMS 报文) + +| 字段 | 菠萝派快手单(正常,id=1775133 等) | OMS 快手单(本批 `dgj-10000280095565` / `319414677101981`) | 说明 | +|---|---|---|---| +| `printinfo` | 3456–3776 字符(大写 hex 密文) | **空串** | OMS 未返回 | +| `encryptprintinfo` | **172 字符**(base64,逐单密钥) | **3648 字符(hex 密文)** | 语义相反:OMS 把密文放进了「密钥」字段 | +| `key` | 无独立列,取 `encryptprintinfo` | **缺失** | 快手打印必需 | +| `signature` | 32 字符 hex | 32 字符 hex | ✅ | +| `ver` | `1` | `1` | ✅ | + +生产正常快手单的 `encryptprintinfo` 逐单不同(逐单密钥,非店铺固定),无法从配置或其他字段推导。 + +### 2. 快手打印契约 + +`printer_data_builder` 快手分支需要四个字段: +`encryptedData ← printinfo`、`key ← encryptprintinfo`、`signature`、`ver`(模板 content keys:`addData, encryptedData, signature, key, templateURL, ver`)。 + +因此 OMS 快手单现状是 **`encryptedData` 缺失 + `key` 被密文占位**,即使把 `encryptprintinfo` 灌进 `printinfo` 也无法打印(缺真正的 key)。 + +### 3. 需要 OMS 侧补齐(阻塞项)—— ✅ 已补齐(2026-11-07) + +快手单请在取号响应中返回: + +- `printinfo`:快手 `encryptedData`(hex 密文,约 3.4–3.8KB)—— 已改:快手单取 `contents[0].encryptedData`(`printInfo` 为空时回退平台原值) +- `key`:快手加密密钥(base64,172 字符,**逐单生成**)——对应店管家 `contents[0].key` —— 已新增响应字段 `key` +- `signature`、`ver`:现有已正确,无需改动 + +同时把 `encryptprintinfo` 在快手口径下改为 `contents[0].key`(与菠萝派一致:密文进 `printinfo`、密钥进 `encryptprintinfo`), +WMS 现有快手分支(`encryptedData ← printinfo`、`key ← encryptprintinfo`)无需改代码即可打印; +新增的 `key` 字段供 WMS 后续直接落 `order_express` 使用。 + +其余平台不受影响:拼多多、抖音直接读 `encryptprintinfo`;菜鸟用 `printinfo` 整包 JSON(WMS 已按 `encryptprintinfo+signature+ver` 回拼)。 + +### 4. WMS 侧本轮改动 + +- 快手分支新增 key 合理性校验:`key` 长度 > 512 或与密文相同 → 告警 + 「快手模板字段 key 疑似为密文而非密钥(上游未返回 key),打印可能失败」,避免静默打出错误面单; +- 既有告警保留(encryptedData / signature / key 缺失映射源)。 +- 新增 `test/verify_kuaishou_print_payload.js` 12 例;全部回归脚本合计 12+22+18+23+24+19+16 = 134 例通过。 + +wms/ diff --git a/backend/app/lib/printPlatform/dgj.js b/backend/app/lib/printPlatform/dgj.js index 076433d..2913b6d 100644 --- a/backend/app/lib/printPlatform/dgj.js +++ b/backend/app/lib/printPlatform/dgj.js @@ -795,22 +795,50 @@ function firstPrintInfo(items, printed, waybillCode) { * * 旧系统 `Dianguanjia.php` 取的是 * `PrintDataList.task.documents[0].contents[0]` 的 `signature` / `encryptedData` / `ver`; - * 视频号等自定义模板场景平台不返回 `contents`,此时三个值都为空串。 + * 快手还会下发逐单加密密钥 `key`(base64,约 172 字符,与密文不同),打印端必需。 + * 视频号等自定义模板场景平台不返回 `contents`,此时各值都为空串。 * @param {Object} document 打印单据 - * @return {{signature: string, encryptprintinfo: string, ver: string}} 签名、加密打印数据、版本 + * @return {{signature: string, encryptprintinfo: string, key: string, ver: string}} 签名、加密打印数据、快手密钥、版本 */ function extractDocumentContents(document) { - const empty = { signature: '', encryptprintinfo: '', ver: '' }; + const empty = { signature: '', encryptprintinfo: '', key: '', ver: '' }; const contents = document && document.contents; const first = Array.isArray(contents) ? contents[0] : null; if (!first || typeof first !== 'object') return empty; return { signature: typeof first.signature === 'string' ? first.signature : '', encryptprintinfo: typeof first.encryptedData === 'string' ? first.encryptedData : '', + key: typeof first.key === 'string' ? first.key : '', ver: first.ver == null ? '' : String(first.ver), }; } +/** + * 组装回给 WMS 的面单打印字段 + * + * 快手(KS)与其它平台口径不同: + * - 快手:平台把加密面单放在 `contents[0].encryptedData`、逐单密钥放在 `contents[0].key`, + * 文档里的 `printInfo` 为空。菠萝派取号的做法是「密文 -> printinfo、密钥 -> encryptprintinfo」, + * WMS 快手打印按该口径取 encryptedData / key,这里对齐,并把 key 单独返回; + * - 其它平台:`printinfo` 原样用平台下发的打印数据,`encryptprintinfo` 仍是 `contents[0].encryptedData`。 + * @param {Object} options 参数 + * @param {string} options.platformCode 系统预设平台编码(如 KS / TB) + * @param {Object} options.contents extractDocumentContents 的结果 + * @param {string} [options.documentPrintInfo] 平台下发的打印数据(documents[].printInfo) + * @return {{printinfo: string, encryptprintinfo: string, key: string}} 打印字段 + */ +function buildWaybillPrintFields({ platformCode, contents, documentPrintInfo = '' }) { + const isKuaishou = String(platformCode || '').trim().toUpperCase() === 'KS'; + const encryptedData = String((contents && contents.encryptprintinfo) || ''); + const key = String((contents && contents.key) || ''); + const printData = String(documentPrintInfo || ''); + return { + printinfo: isKuaishou ? (encryptedData || printData) : printData, + encryptprintinfo: isKuaishou ? key : encryptedData, + key, + }; +} + /** * 构造 `Orders[0][WaybillCodes][]`(平台「新单号打印」请求里带的当前号清单) * @@ -2463,7 +2491,7 @@ class DgjService extends PrintPlatformService { * @param {Object} options.template 已绑定的快递接口记录(template_id / platform_type / dbname / raw) * @param {number} [options.packageIndex] 包裹序号(0 基):>0 目前不支持,会直接报错(见下) * @param {number} [options.packageCount] 包裹张数(默认 1):>1 时同一次请求取多张面单 - * @return {Promise<{waybill_code: string, waybill_codes: string[], printinfo: string, signature: string, previous_code: string, raw: Object}>} 取号结果 + * @return {Promise<{waybill_code: string, waybill_codes: string[], printinfo: string, signature: string, encryptprintinfo: string, key: string, ver: string, previous_code: string, raw: Object}>} 取号结果 */ async fetchWaybillNo(order, options = {}) { if (!this.token || !this.cookie) throw new Error('店管家账号未登录:缺少 token 或 cookie,请先登录'); @@ -2573,6 +2601,14 @@ class DgjService extends PrintPlatformService { const document = firstPrintDocument(printed, waybillCodes[0]); const contents = extractDocumentContents(document); + // 模板上落的是 OMS 预设编码,优先用它判断平台;缺失时再按打单平台原始类型/调用方编码换算 + const platformCode = String((template && template.platform_code) || '').trim().toUpperCase() + || resolveOrderPlatform((template && template.platform_type) || options.platformCode).code; + const printFields = buildWaybillPrintFields({ + platformCode, + contents, + documentPrintInfo: firstPrintInfo(items, printed, waybillCodes[0]), + }); return { waybill_code: waybillCodes[0], waybill_codes: waybillCodes, @@ -2583,9 +2619,11 @@ class DgjService extends PrintPlatformService { // 实际命中的订单域名:重取打印数据要发到同一个域名 host, // 面单打印数据:原样透传(WMS 打印端直接塞进 task.printInfo) - printinfo: firstPrintInfo(items, printed, waybillCodes[0]), + printinfo: printFields.printinfo, signature: contents.signature, - encryptprintinfo: contents.encryptprintinfo, + encryptprintinfo: printFields.encryptprintinfo, + // 快手逐单加密密钥(base64,约 172 字符),其余平台为空串 + key: printFields.key, ver: contents.ver, // 取号前后对比用的旧号码(不参与判断,只用于提示「平台仍返回原运单号」) previous_code: previousCode, @@ -3250,6 +3288,27 @@ class DgjService extends PrintPlatformService { return extractPrintHistoryIds(printed); } + /** + * 从打印单据里取 signature / encryptedData / key / ver(供脚本/单测复用同一口径) + * @param {Object} document 打印单据(`documents[]` 中的一项) + * @return {{signature: string, encryptprintinfo: string, key: string, ver: string}} 打印附加信息 + */ + static extractDocumentContents(document) { + return extractDocumentContents(document); + } + + /** + * 组装回给 WMS 的面单打印字段(快手口径与其它平台不同) + * @param {Object} options 参数 + * @param {string} options.platformCode 系统预设平台编码(如 KS / TB) + * @param {Object} options.contents extractDocumentContents 的结果 + * @param {string} [options.documentPrintInfo] 平台下发的打印数据 + * @return {{printinfo: string, encryptprintinfo: string, key: string}} 打印字段 + */ + static buildWaybillPrintFields(options) { + return buildWaybillPrintFields(options); + } + /** * 组装发货回传单体报文(`Orders[i]`),供脚本/单测复用同一口径 * @param {Object} row 订单行(平台行或本地快照拼装结果) diff --git a/backend/app/lib/waybillGet.js b/backend/app/lib/waybillGet.js index cf38594..ce0103b 100644 --- a/backend/app/lib/waybillGet.js +++ b/backend/app/lib/waybillGet.js @@ -481,7 +481,7 @@ async function processItem(ctx, { principalId, warehouseId, item, memo, requestI // 留痕上下文:处理过程中逐步补齐(平台编码 / 打单账号 / 模板) const meta = { principalId, warehouseId, requestId, code, expressCode, platformCode: '', accountId: null, templateId: null }; - const detail = { raw: null, printinfo: '', signature: '', encryptprintinfo: '', ver: '', print_history_ids: [] }; + const detail = { raw: null, printinfo: '', signature: '', encryptprintinfo: '', key: '', ver: '', print_history_ids: [] }; const result = await callPlatform(ctx, { principalId, warehouseId, code, expressCode, item, memo, meta, detail }); await saveRecord(ctx, meta, result, detail); return result; @@ -593,6 +593,7 @@ async function callPlatform(ctx, { principalId, warehouseId, code, expressCode, detail.printinfo = String((fetched && fetched.printinfo) || ''); detail.signature = String((fetched && fetched.signature) || ''); detail.encryptprintinfo = String((fetched && fetched.encryptprintinfo) || ''); + detail.key = String((fetched && fetched.key) || ''); detail.ver = String((fetched && fetched.ver) || ''); // 取号结果只回给调用方(WMS 自行落单),不写回 OMS 订单表: @@ -607,6 +608,7 @@ async function callPlatform(ctx, { principalId, warehouseId, code, expressCode, platformCode, waybillCode: waybill.waybill_code, printinfoLength: detail.printinfo.length, + keyLength: detail.key.length, }); return { delivery_order_code: code, @@ -632,6 +634,8 @@ async function callPlatform(ctx, { principalId, warehouseId, code, expressCode, : ''), // 需要加密打印的平台(如菜鸟系)才有值,店管家视频号自定义模板一般为空 encryptprintinfo: detail.encryptprintinfo, + // 快手逐单加密密钥(base64,约 172 字符):WMS 快手打印模板的 key 参数,其余平台为空串 + key: detail.key, ver: detail.ver, }; } catch (err) { diff --git a/backend/scripts/dgj-waybill-probe.js b/backend/scripts/dgj-waybill-probe.js index 473059c..9a5e75b 100644 --- a/backend/scripts/dgj-waybill-probe.js +++ b/backend/scripts/dgj-waybill-probe.js @@ -207,6 +207,8 @@ function readArg(name) { printinfo_len: (result.printinfo || '').length, printinfo_head: (result.printinfo || '').slice(0, 120), signature: result.signature ? '已返回' : '无', + encryptprintinfo_len: (result.encryptprintinfo || '').length, + key_len: (result.key || '').length, raw: file, }); if (result.previous_code && result.previous_code === result.waybill_code) { diff --git a/backend/test/app/lib/printPlatformDgj.test.js b/backend/test/app/lib/printPlatformDgj.test.js index 7076997..b532935 100644 --- a/backend/test/app/lib/printPlatformDgj.test.js +++ b/backend/test/app/lib/printPlatformDgj.test.js @@ -75,3 +75,76 @@ describe('printPlatform/dgj extractPrintHistoryIds', () => { assert.deepStrictEqual(DgjService.extractPrintHistoryIds(null), []); }); }); + +describe('printPlatform/dgj extractDocumentContents', () => { + it('快手单据要取出逐单密钥 key 与密文 encryptedData', () => { + const document = { + contents: [{ + encryptedData: 'A1B2C3D4'.repeat(400), + key: 'MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQ==', + signature: 'MEQCIB', + ver: '1', + templateURL: 'https://example.com/t.json', + }], + }; + const contents = DgjService.extractDocumentContents(document); + assert.strictEqual(contents.encryptprintinfo, 'A1B2C3D4'.repeat(400)); + assert.strictEqual(contents.key, 'MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQ=='); + assert.strictEqual(contents.signature, 'MEQCIB'); + assert.strictEqual(contents.ver, '1'); + }); + + it('没有 contents 时各字段为空串', () => { + assert.deepStrictEqual(DgjService.extractDocumentContents(null), { + signature: '', encryptprintinfo: '', key: '', ver: '', + }); + assert.deepStrictEqual(DgjService.extractDocumentContents({ printInfo: 'x' }), { + signature: '', encryptprintinfo: '', key: '', ver: '', + }); + }); +}); + +describe('printPlatform/dgj buildWaybillPrintFields', () => { + const contents = { + signature: 'SIG', + encryptprintinfo: 'ENCRYPTED_DATA', + key: 'PER_ORDER_KEY', + ver: '1', + }; + + it('快手:printinfo 用 encryptedData,encryptprintinfo/key 都用逐单密钥', () => { + const fields = DgjService.buildWaybillPrintFields({ + platformCode: 'KS', + contents, + documentPrintInfo: '', + }); + assert.deepStrictEqual(fields, { + printinfo: 'ENCRYPTED_DATA', + encryptprintinfo: 'PER_ORDER_KEY', + key: 'PER_ORDER_KEY', + }); + }); + + it('快手:没有 encryptedData 时回退平台下发的 printInfo', () => { + const fields = DgjService.buildWaybillPrintFields({ + platformCode: 'KS', + contents: { ...contents, encryptprintinfo: '' }, + documentPrintInfo: 'PLAIN_PRINT_DATA', + }); + assert.strictEqual(fields.printinfo, 'PLAIN_PRINT_DATA'); + assert.strictEqual(fields.key, 'PER_ORDER_KEY'); + }); + + it('其它平台:printinfo 原样,encryptprintinfo 仍是密文', () => { + const fields = DgjService.buildWaybillPrintFields({ + platformCode: 'TB', + contents, + documentPrintInfo: 'PLAIN_PRINT_DATA', + }); + assert.deepStrictEqual(fields, { + printinfo: 'PLAIN_PRINT_DATA', + encryptprintinfo: 'ENCRYPTED_DATA', + key: 'PER_ORDER_KEY', + }); + }); +});