From 82879cdef5904b29d4381baa0a00d686d18f5aae Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sat, 7 Nov 2026 06:56:20 +0800 Subject: [PATCH] =?UTF-8?q?feat(waybill):=20getprintdata=20=E5=8F=AA?= =?UTF-8?q?=E5=9B=9E=20params=20=E4=B8=B2=EF=BC=8C=E5=B9=B6=E6=8C=89=20pri?= =?UTF-8?q?ntHistoryId=20=E9=80=90=E4=B8=AA=E9=99=90=E6=B5=81=E5=9B=9E?= =?UTF-8?q?=E6=BA=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 返回精简:每单只给定位字段 + params(contents[].params,形如 access_token=…&app_key=…&method=logistics.getShopKey&…&sign=…)与 template_url; 不再回整包 print_data / printer_config / document - 限流:平台该接口有限流,改为一次只带一个 printHistoryId,逐张串行并间隔 300ms; 单张失败不影响其它张,失败原因逐单返回 - params 为空时直接判失败(平台的打印数据里没有 params) 实测:{ printHistoryId: "10000078656212" } → params 为 access_token=uo7… &method=logistics.getShopKey&…&sign=8849…,template_url 为申通 76x130 模板。 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- WMS-OMS-取号对接.md | 22 +++-- backend/app/lib/waybillPrintData.js | 82 +++++++++++++------ backend/test/app/lib/waybillPrintData.test.js | 24 +++++- 3 files changed, 89 insertions(+), 39 deletions(-) diff --git a/WMS-OMS-取号对接.md b/WMS-OMS-取号对接.md index 9a70725..ad80271 100644 --- a/WMS-OMS-取号对接.md +++ b/WMS-OMS-取号对接.md @@ -386,18 +386,21 @@ WMS 真正要打印时,调 `deliveryorder.getprintdata` 换一份新的(OMS | 入参(推荐批量) | `{ "caiNiaoAuthInfoIds": [ 6838859 ], "waybillCodes": [ "770357408441408" ] }` | | 入参(可选直传) | `{ "printHistoryIds": [ "10000078656212", "…" ] }`(数组,命中即跳过按运单号查库) | | 出参 | `{ total, success, failed, expires_in, results: [ … ] }`,`expires_in` 固定 600 秒 | -| 单条结果 | `waybill_code, success, message, print_history_id, template_id, cai_niao_auth_info_id, dbname, print_data, printer_config, document` | +| 单条结果 | `waybill_code, success, message, print_history_id, template_id, cai_niao_auth_info_id, dbname, expires_in, params, template_url` | `caiNiaoAuthInfoId` 就是取号响应里的 `cai_niao_auth_info_id`(**每个店铺唯一**),WMS 落库时把它和运单号一起存下来即可; OMS 用它 + 运单号定位到那次取号的打印记录(`waybill_fetch_records`,已建 `principal_id + cai_niao_auth_info_id + waybill_code` 索引)。 -返回用法: +返回用法(**只需要 `params`**): -- `print_data`:平台原样返回的 params 字符串,直接交给打印服务 -- `printer_config` / `document`:拆好的结构。**同店铺多张面单共用一个 `printer_config`**, - 把各自的 `document`(含 `documentID` = 运单号、`contents[].params`)拼进同一个 `PrintDataList.task.documents` - 就是一次多张打印任务 —— 不要拿 A 单的 `document` 去打 B 单,`documentID`/params 是逐张面单的 -- 建议 WMS 按「店铺(caiNiaoAuthInfoId)分组、一批运单号一次调用」换 params,10 分钟内打完 +- `params`:打印端真正要的那串,平台原样返回的 + `access_token=uo7…&app_key=7152…&method=logistics.getShopKey¶m_json={}×tamp=2026-11-07 06:43:36&v=2&sign=9cb2…` + (取自 `documents[].contents[].params`,已从整包打印数据里提取好,**不需要 WMS 再解析**) +- `template_url`:该面单的模板地址(`contents[].templateURL`),打印 SDK 渲染时用;与 `params` 同源 +- `print_history_id` / `template_id` / `cai_niao_auth_info_id` / `dbname`:定位与对账用 +- ⚠️ **`params` 是逐张面单的**,不能拿 A 单的 `params` 去打 B 单(里面带着该面单的签名/时间戳) +- **限流**:平台该接口有限流,OMS 内部**一次只带一个 `printHistoryId`**、逐张串行并留 300ms 间隔; + WMS 侧也建议一张一张调(或小批),10 分钟内打完 **注意**:`printHistoryId` 由 OMS 保存,**不需要** WMS 再存一份(每张面单一条、重打/换号会新增,存两份必然不一致)。 单条失败原因:`未找到该运单号的取号记录(可能不是通过 OMS 取的号)` / @@ -409,8 +412,9 @@ OMS 用它 + 运单号定位到那次取号的打印记录(`waybill_fetch_reco > > 📌 **只传一个打印记录ID就够了**(实测):`{ "printHistoryId": "10000078656212" }` → > OMS 从自己库里取出该记录对应的**域名(`platform_host`)+ 分区(`dbname`)+ 打单账号**,直接回源 -> `PrintHistory/LoadPrintData` 拿新的 params,返回 `print_data`(实测 7888 字符)与拆好的 `document`。 -> 也就是说 WMS 不需要知道域名/分区,店铺标识与运单号也不是必填。 +> `PrintHistory/LoadPrintData` 拿新的 params,结果里的 `params` 就是那串 +> `access_token=…&app_key=…&method=logistics.getShopKey&…&sign=…`。 +> 也就是说 WMS 不需要知道域名/分区,店铺标识与运单号也不是必填;一次一张、串行调用即可。 ```sql -- 打印前换 params 时 OMS 内部按这条定位(同一个运单号多次取号取最新一条) diff --git a/backend/app/lib/waybillPrintData.js b/backend/app/lib/waybillPrintData.js index 3adfa7c..7f901ba 100644 --- a/backend/app/lib/waybillPrintData.js +++ b/backend/app/lib/waybillPrintData.js @@ -9,6 +9,18 @@ const PRINT_DATA_TTL_SECONDS = 600; /** 单次最多换取的运单号数量(一次打印任务的面单张数不会太多) */ const MAX_BATCH = 200; +/** 平台接口限流:同一个店铺两次请求之间至少间隔(毫秒),且一次只带一个 printHistoryId */ +const THROTTLE_MS = 300; + +/** + * 简单等待 + * @param {number} ms 毫秒 + * @return {Promise} 无返回值 + */ +function sleep(ms) { + return new Promise(resolve => setTimeout(resolve, ms)); +} + /** * 拆掉报文外层的 request / deliveryOrders 包装,取真正的入参对象 * @param {Object} data 原始报文 @@ -89,17 +101,23 @@ function pickPrintHistory(record, waybillCode, preferredIds = []) { * @return {{printer_config: Object|null, document: Object|null, documents: Array}} 解析结果 */ function parsePrintData(printData) { - const empty = { printer_config: null, document: null, documents: [] }; + const empty = { printer_config: null, document: null, documents: [], params: '', template_url: '' }; if (typeof printData !== 'string' || !printData.trim()) return empty; try { const outer = JSON.parse(printData); const inner = outer && outer.printDataJson ? JSON.parse(outer.printDataJson) : outer; const documents = inner && inner.PrintDataList && inner.PrintDataList.task && inner.PrintDataList.task.documents; const list = Array.isArray(documents) ? documents : []; + const document = list[0] || null; + const contents = document && Array.isArray(document.contents) ? document.contents : []; + // 打印端真正要的是 contents[].params(access_token=...&method=logistics.getShopKey&sign=...) + const first = contents.find(item => item && String(item.params || '').trim()) || contents[0] || {}; return { printer_config: (inner && inner.PrinterConfig) || null, - document: list[0] || null, + document, documents: list, + params: String(first.params || ''), + template_url: String(first.templateURL || ''), }; } catch { return empty; @@ -264,7 +282,10 @@ async function getPrintData(ctx, { principalId, warehouseId, data, requestId }) } /** - * 按「账号 + 域名 + 分区」分组拉取打印数据(同店铺一次请求取多张) + * 按「账号 + 域名 + 分区」分组拉取打印数据 + * + * 平台侧对这个接口有限流,**一次只带一个 printHistoryId**,逐个串行请求并在两次之间留间隔, + * 避免同店铺多张面单一起打过去被限流/超时。 * @param {Object} ctx egg context * @param {Object} params 参数 * @param {number} params.principalId 主体ID @@ -293,26 +314,34 @@ async function fetchGroup(ctx, { principalId, memo, group }) { traceId = ''; } - let list = []; - try { - list = await service.loadPrintData(host, { - traceId, - dbname, - printHistoryIds: items.map(item => item.history.id), - }); - } catch (err) { - ctx.logger.warn('[waybill.printdata] 换打印数据失败 host=%s dbname=%s:%s', host, dbname, err.message); - return fallback(`读取打印数据失败:${err.message}`); - } - - const byHistoryId = new Map(list.map(item => [ String(item.print_history_id), item ])); - return items.map(item => { - const row = byHistoryId.get(String(item.history.id)); + const results = []; + for (let index = 0; index < items.length; index += 1) { + const item = items[index]; + if (index > 0) await sleep(THROTTLE_MS); + let row = null; + try { + const list = await service.loadPrintData(host, { + traceId, + dbname, + printHistoryIds: [ item.history.id ], + }); + row = list[0] || null; + } catch (err) { + ctx.logger.warn('[waybill.printdata] 换打印数据失败 host=%s dbname=%s id=%s:%s', + host, dbname, item.history.id, err.message); + results.push({ waybill_code: item.waybillCode, success: false, message: `读取打印数据失败:${err.message}` }); + continue; + } if (!row) { - return { waybill_code: item.waybillCode, success: false, message: '平台未返回该运单号的打印数据' }; + results.push({ waybill_code: item.waybillCode, success: false, message: '平台未返回该运单号的打印数据' }); + continue; } const parsed = parsePrintData(row.print_data); - return { + if (!parsed.params) { + results.push({ waybill_code: item.waybillCode, success: false, message: '平台的打印数据里没有 params(access_token 串)' }); + continue; + } + results.push({ waybill_code: item.waybillCode, success: true, message: 'ok', @@ -321,13 +350,12 @@ async function fetchGroup(ctx, { principalId, memo, group }) { cai_niao_auth_info_id: item.record.cai_niao_auth_info_id == null ? null : Number(item.record.cai_niao_auth_info_id), dbname: item.record.dbname || '', expires_in: PRINT_DATA_TTL_SECONDS, - // 新的打印数据(平台原样返回的 params 字符串) - print_data: row.print_data, - // 拆好的结构:同店铺多张面单共用一个 printer_config,documents 拼起来即可 - printer_config: parsed.printer_config, - document: parsed.document, - }; - }); + // 打印端要的就是这串:access_token=...&app_key=...&method=logistics.getShopKey&...&sign=... + params: parsed.params, + template_url: parsed.template_url, + }); + } + return results; } module.exports = { diff --git a/backend/test/app/lib/waybillPrintData.test.js b/backend/test/app/lib/waybillPrintData.test.js index 08658e8..f218ddd 100644 --- a/backend/test/app/lib/waybillPrintData.test.js +++ b/backend/test/app/lib/waybillPrintData.test.js @@ -42,7 +42,7 @@ describe('waybillPrintData 打印数据换取', () => { assert.strictEqual(printData.pickPrintHistory({}, 'A'), null); }); - it('解析平台返回的 params:拿到打印机配置与面单 document', () => { + it('解析平台返回的 params:拿到打印机配置、面单 document 与 access_token 串', () => { const params = JSON.stringify({ id: null, sendContent: '[1];\n', @@ -50,14 +50,32 @@ describe('waybillPrintData 打印数据换取', () => { PrinterConfig: { cmd: 'setPrinterConfig', printer: { name: '默认打印机' } }, PrintDataList: { cmd: 'print', - task: { printer: '默认打印机', documents: [{ documentID: '770357408441408', contents: [{ templateURL: 'https://x/t.xml' }] }] }, + task: { + printer: '默认打印机', + documents: [{ + documentID: '770357408441408', + contents: [ + { templateURL: '', params: '' }, + { + templateURL: 'https://x/t.xml', + params: 'access_token=tok&app_key=715&method=logistics.getShopKey¶m_json={}×tamp=2026-11-07 06:43:36&v=2&sign=9cb2', + }, + ], + }], + }, }, }), }); const parsed = printData.parsePrintData(params); console.log('documentID:', parsed.document.documentID, '| printer:', parsed.printer_config.printer.name); + console.log('params:', parsed.params); assert.strictEqual(parsed.document.documentID, '770357408441408'); assert.strictEqual(parsed.printer_config.printer.name, '默认打印机'); - assert.deepStrictEqual(printData.parsePrintData('not-json'), { printer_config: null, document: null, documents: [] }); + // 跳过空的 contents,取真正带 params 的那条 + assert.ok(parsed.params.startsWith('access_token=tok&app_key=715')); + assert.strictEqual(parsed.template_url, 'https://x/t.xml'); + assert.deepStrictEqual(printData.parsePrintData('not-json'), { + printer_config: null, document: null, documents: [], params: '', template_url: '', + }); }); });