From d5b4298c86c400fe31b999f98fbdd64e236dfc0e Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sat, 7 Nov 2026 07:52:23 +0800 Subject: [PATCH] =?UTF-8?q?refactor(waybill):=20=E6=9B=B4=E6=AD=A3?= =?UTF-8?q?=E8=AF=AD=E4=B9=89=E2=80=94=E2=80=94=E8=BF=99=E4=B8=8D=E6=98=AF?= =?UTF-8?q?=E3=80=8C=E9=87=8D=E6=89=93=E3=80=8D=EF=BC=8C=E5=8F=AA=E6=98=AF?= =?UTF-8?q?=E7=BB=99=E9=9C=80=E8=A6=81=20params=20=E7=9A=84=E5=B9=B3?= =?UTF-8?q?=E5=8F=B0=E6=8B=89=E6=89=93=E5=8D=B0=E6=95=B0=E6=8D=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - dgj.reprintPrintData → fetchPrintParams;expressPrint 选项 reprint → reuseWaybill (PrintMethod=Normal + IsIgnoreWaybillRepeat=true = 复用原运单号、只重新下发打印数据) - 提示语与安全闸措辞改为「拉取打印参数 / 平台分配了面单」,不再叫重打 - 模板不返回 params 时明确提示:只有抖店面单需要 params, 淘宝/拼多多/京东/视频号等直接用取号返回的 printinfo 打单 - 文档同步:LoadPrintData 只回放历史签名;拉 params 走「复用原号重新下发」; 仅抖店需要 params;验收记录改为「拉取 params 未产生新面单(余额 5253→5253)」 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- WMS-OMS-取号对接.md | 23 ++++++++++------- backend/app/lib/printPlatform/dgj.js | 35 ++++++++++++++------------ backend/app/lib/waybillPrintData.js | 37 ++++++++++++++++------------ 店管家取号-旧系统提取.md | 6 ++--- 4 files changed, 57 insertions(+), 44 deletions(-) diff --git a/WMS-OMS-取号对接.md b/WMS-OMS-取号对接.md index a818abf..785f9d0 100644 --- a/WMS-OMS-取号对接.md +++ b/WMS-OMS-取号对接.md @@ -391,10 +391,15 @@ WMS 真正要打印时,调 `deliveryorder.getprintdata` 换一份新的(OMS > ⚠️ **重要(实测 2026-11-07)**:店管家 `PrintHistory/LoadPrintData` **只回放那次打印时签发的 params,不会重签** > (`params_timestamp` 恒等于该打印记录的 `CreateDate`;换 `FxPageType=1/2`、加 `IsRePrint`/`IsRefresh` > 都返回同一个 `timestamp/sign`),所以那串 `access_token=…&sign=…` 10 分钟后必失效。 -> ✅ 要新鲜签名只能让平台**重新打印**:`ExpressPrint` + `PrintMethod=Normal` + `IsIgnoreWaybillRepeat=true` -> —— 实测平台**复用订单已有运单号**(不消耗面单)并重签 params(返回的 `timestamp` = 当前时间)。 -> OMS 的 `deliveryorder.getprintdata` 已按这条路径实现:回读平台订单行 → 原单号打印 → 返回新 `params`; -> 并带安全闸,万一平台返回了新运单号(说明已消耗面单)会直接判失败并告警,不会静默返回。 +> ✅ 要新鲜签名只能让平台重新下发:`ExpressPrint` + `PrintMethod=Normal` + `IsIgnoreWaybillRepeat=true` +> —— 实测平台**复用订单已有运单号**(不分配新面单、余额 5253 → 5253 不变),只把打印数据(params)重新给一份。 +> 注意这**不是「重打」**:真正的打印在打印端做,这里只是把打印数据重新取一次。 +> OMS 的 `deliveryorder.getprintdata` 已按这条路径实现;并带安全闸,万一平台返回了新运单号(说明已分配面单) +> 会直接判失败并告警,不会静默返回。 +> +> 📌 **只有需要 `params` 的平台/模板才用这个接口**:抖店(DYXD)面单打的是一串带签名的 `params`, +> 10 分钟过期;淘宝/拼多多/京东/视频号等平台取号返回的 `printinfo` 就是面单打印数据,直接用它打印即可。 +> 若模板不返回 `params`,接口会返回失败并说明「只有抖店面单需要 params…」。 `caiNiaoAuthInfoId` 就是取号响应里的 `cai_niao_auth_info_id`(**每个店铺唯一**),WMS 落库时把它和运单号一起存下来即可; OMS 用它 + 运单号定位到那次取号的打印记录(`waybill_fetch_records`,已建 `principal_id + cai_niao_auth_info_id + waybill_code` 索引)。 @@ -410,16 +415,16 @@ OMS 用它 + 运单号定位到那次取号的打印记录(`waybill_fetch_reco - **限流**:平台该接口有限流,OMS 内部**一次只带一个 `printHistoryId`**、逐张串行并留 300ms 间隔; WMS 侧也建议一张一张调(或小批),10 分钟内打完 - **新鲜度**:`params_timestamp` 是平台签发时间,`params_expired` 由 OMS 按 10 分钟算出; - 本接口走「原单号打印」重签,正常应当 `params_expired=false`。 - 若为 `true` 或 `success=false` 且 message 提到「重打返回了新运单号」,说明平台异常发了新号(已消耗面单),需人工核对 + 本接口走「复用原运单号、重新下发打印数据」,正常应当 `params_expired=false`。 + 若为 `true` 或 `success=false` 且 message 提到「平台返回了新运单号」,说明平台异常分配了新面单,需人工核对 -**注意**:`printHistoryId` 由 OMS 保存,**不需要** WMS 再存一份(每张面单一条、重打/换号会新增,存两份必然不一致)。 +**注意**:`printHistoryId` 由 OMS 保存,**不需要** WMS 再存一份(每张面单一条、换号/重打都会新增,存两份必然不一致)。 单条失败原因:`未找到该运单号的取号记录(可能不是通过 OMS 取的号)` / `取号记录里没有该运单号的打印记录ID(PrintHistoryIds),无法换新的打印数据`。 > 📌 **取号响应也会返回 `print_history_ids` / `print_history_id`**(见 §4.2),WMS 可按需落库; > 但打印前换 params 时**不要求** WMS 传它 —— 传「`caiNiaoAuthInfoIds` + `waybillCodes`」由 OMS 查库即可, -> 想省一次查库时再直传 `printHistoryIds`。两者以 OMS 库里的记录为准(重打会新增打印记录)。 +> 想省一次查库时再直传 `printHistoryIds`。两者以 OMS 库里的记录为准(换号/重打都会新增打印记录)。 > > 📌 **只传一个打印记录ID就够了**(实测):`{ "printHistoryId": "10000078656212" }` → > OMS 从自己库里取出该记录对应的**域名(`platform_host`)+ 分区(`dbname`)+ 打单账号**,直接回源 @@ -435,7 +440,7 @@ WHERE principal_id = ? AND status = 1 AND waybill_code = ? ORDER BY id DESC LIMIT 1; ``` -> ✅ **验收(2026-11-07 线上)**:重打未产生新面单,返回原运单号 + 新鲜 `params`,测试通过。 +> ✅ **验收(2026-11-07 线上)**:拉取 params 未产生新面单(余额不变),返回原运单号 + 新鲜 `params`,测试通过。 > 误分配的 2 张面单已由业务侧回收。 --- diff --git a/backend/app/lib/printPlatform/dgj.js b/backend/app/lib/printPlatform/dgj.js index a68dd3e..4dc9dd1 100644 --- a/backend/app/lib/printPlatform/dgj.js +++ b/backend/app/lib/printPlatform/dgj.js @@ -2548,10 +2548,10 @@ class DgjService extends PrintPlatformService { * @param {Object} [options.checkData] CheckTemplateAvaliable 返回的 Data(DateNow / DayPrintBatchNumber / Branches) * @param {number} [options.packageCount] 包裹张数(默认 1):>1 时把同一订单行重复 N 份 * @param {string} [options.expressCode] 快递编码(仅用于回传 WaybillCodes 时补 ExpressCpCode) - * @param {boolean} [options.reprint] 是否「原单号打印」(复用平台已有运单号、不消耗面单;重打时用) + * @param {boolean} [options.reuseWaybill] 复用平台已有运单号、只拉取打印数据(不分配新面单);拉 params 时用 * @return {Promise} 平台响应(Data.WaybillCode[] 含运单号与打印数据) */ - async expressPrint(host, { traceId, dbname, templateId, rows, checkData, packageCount = 1, expressCode = '', reprint = false }) { + async expressPrint(host, { traceId, dbname, templateId, rows, checkData, packageCount = 1, expressCode = '', reuseWaybill = false }) { const data = checkData || {}; const repeat = Number.isFinite(Number(packageCount)) && Number(packageCount) > 1 ? Math.floor(Number(packageCount)) : 1; const currentWaybillCode = (() => { @@ -2633,10 +2633,10 @@ class DgjService extends PrintPlatformService { PackageCount: String(repeat), PackageDesc: '', GoodsDesc: '', - // 「原单号打印」(重打):PrintMethod=Normal + IsIgnoreWaybillRepeat=true 让平台复用已有运单号, - // 只重新签发打印数据(params 里的签名会刷新),不消耗新面单 - PrintMethod: reprint ? 'Normal' : 'NewPrint', - IsIgnoreWaybillRepeat: reprint ? 'true' : 'false', + // 「复用已有运单号」拉取打印数据:PrintMethod=Normal + IsIgnoreWaybillRepeat=true, + // 平台不再分配新面单,只把打印数据(抖店是 params)重新下发 + PrintMethod: reuseWaybill ? 'Normal' : 'NewPrint', + IsIgnoreWaybillRepeat: reuseWaybill ? 'true' : 'false', PrinterName: '默认打印机', IsPreview: 'false', IsContinueForStock: 'false', @@ -2662,11 +2662,14 @@ class DgjService extends PrintPlatformService { } /** - * 「原单号打印」重签打印数据(复用已有运单号,**不消耗面单**) + * 拉取面单打印参数(抖店等需要 `params` 的平台;复用已有运单号,**不分配新面单**) * - * `PrintHistory/LoadPrintData` 只回放历史签名(实测不会重签,10 分钟后必然过期), - * 要新的 `params`(`access_token=…×tamp=…&sign=…`)只能让平台重新打印一次: - * `PrintMethod=Normal + IsIgnoreWaybillRepeat=true` → 平台复用该订单已有运单号,只重新签发打印数据。 + * 背景:抖店面单打印走的是一串带签名的 `params` + * (`access_token=…&method=logistics.getShopKey×tamp=…&sign=…`),**10 分钟过期**; + * 而 `PrintHistory/LoadPrintData` 只回放历史签名(实测不重签),拿不到新鲜串。 + * 平台侧唯一能重新下发的入口是 `ExpressPrint`: + * `PrintMethod=Normal + IsIgnoreWaybillRepeat=true` → 复用订单已有运单号、只重新下发打印数据。 + * 注意:这不是「重打」,只是把打印数据(params)重新取一次;真正的打印在打印端做。 * @param {string} host 平台域名 * @param {Object} options 参数 * @param {string} options.traceId 登录上下文 traceId @@ -2674,10 +2677,10 @@ class DgjService extends PrintPlatformService { * @param {string} options.templateId 面单模板ID * @param {Object} options.row 平台订单行(findPlatformOrderRow 的返回) * @param {string} [options.expressCode] 快递编码 - * @return {Promise<{waybill_codes: string[], documents: Array<{documentID: string, params: string, template_url: string}>, raw: Object}>} 重签结果 + * @return {Promise<{waybill_codes: string[], documents: Array<{documentID: string, params: string, template_url: string}>, raw: Object}>} 打印数据 */ - async reprintPrintData(host, { traceId = '', dbname = '', templateId, row, expressCode = '' }) { - if (!row) throw new Error('原单号打印需要平台订单行'); + async fetchPrintParams(host, { traceId = '', dbname = '', templateId, row, expressCode = '' }) { + if (!row) throw new Error('拉取打印参数需要平台订单行'); const printed = await this.expressPrint(host, { traceId, dbname, @@ -2685,14 +2688,14 @@ class DgjService extends PrintPlatformService { rows: [ row ], checkData: {}, expressCode, - reprint: true, + reuseWaybill: true, }); const errorItem = (Array.isArray(printed && printed.Data && printed.Data.WaybillCode) ? printed.Data.WaybillCode : []) .find(item => item && (item.IsError === true || Number(item.IsError) === 1)); if (errorItem) { - const reason = errorItem.ErrMsg || errorItem.ErrorMsg || '平台返回重打失败'; - throw buildPlatformError(`店管家原单号打印失败:${reason}`, { status: 200, json: printed, text: '' }); + const reason = errorItem.ErrMsg || errorItem.ErrorMsg || '平台返回失败'; + throw buildPlatformError(`店管家拉取打印参数失败:${reason}`, { status: 200, json: printed, text: '' }); } const documents = []; diff --git a/backend/app/lib/waybillPrintData.js b/backend/app/lib/waybillPrintData.js index 5514283..1559371 100644 --- a/backend/app/lib/waybillPrintData.js +++ b/backend/app/lib/waybillPrintData.js @@ -138,7 +138,7 @@ function pickParamsTimestamp(params) { * params 里的签名是否已过期(平台有效期 10 分钟) * * ⚠️ 店管家的 `PrintHistory/LoadPrintData` 只是**回放那次打印时的签名**,不会重新签发, - * 所以隔一段时间再取一定是过期的;要新签名只能重新走「原单号打印」。 + * 所以隔一段时间再取一定是过期的;要新签名只能让平台重新下发(见 dgj.fetchPrintParams)。 * @param {string} timestamp 签名时间 * @param {number} [ttlSeconds] 有效期(秒) * @return {boolean} 是否过期(时间解析失败按未过期处理,避免误判) @@ -319,11 +319,12 @@ function pickLogicalOrderId(deliveryOrderCode) { } /** - * 按「账号 + 域名 + 分区」分组换取打印数据 + * 按「账号 + 域名 + 分区」分组拉取打印参数 * - * 用「原单号打印」重签:平台复用订单已有运单号(**不消耗面单**)并重新签发 params。 - * `PrintHistory/LoadPrintData` 只是历史回放,不能用来换新签名。 - * 平台侧有限流,逐张串行并在两次之间留间隔。 + * 只对「打印需要 params 的平台」有意义(抖店:`params` 里是带签名的取号串,10 分钟过期); + * 其它平台(淘宝/拼多多/京东…)取号返回的 `printinfo` 就是面单打印数据,不需要 params。 + * 拉取方式:复用订单已有运单号(`PrintMethod=Normal + IsIgnoreWaybillRepeat=true`), + * 平台只重新下发打印数据、不分配新面单。平台侧有限流,逐张串行并留间隔。 * @param {Object} ctx egg context * @param {Object} params 参数 * @param {number} params.principalId 主体ID @@ -342,8 +343,8 @@ async function fetchGroup(ctx, { principalId, memo, group }) { const entry = await loadAccount(ctx, memo, { accountId, principalId }); if (!entry) return fallback('打单账号不存在或不属于该主体'); const { service } = entry; - if (typeof service.reprintPrintData !== 'function' || typeof service.findPlatformOrderRow !== 'function') { - return fallback('当前打单平台不支持重新打印(原单号打印)'); + if (typeof service.fetchPrintParams !== 'function' || typeof service.findPlatformOrderRow !== 'function') { + return fallback('当前打单平台不支持拉取打印参数'); } let traceId = ''; @@ -368,12 +369,12 @@ async function fetchGroup(ctx, { principalId, memo, group }) { const logicalOrderId = pickLogicalOrderId(item.record.delivery_order_code); if (!logicalOrderId) { - results.push({ ...base, success: false, message: '取号记录缺少店管家系统编号,无法重打' }); + results.push({ ...base, success: false, message: '取号记录缺少店管家系统编号,无法拉取打印参数' }); continue; } const templateId = String(item.record.template_id || '').trim(); if (!templateId) { - results.push({ ...base, success: false, message: '取号记录缺少面单模板ID,无法重打' }); + results.push({ ...base, success: false, message: '取号记录缺少面单模板ID,无法拉取打印参数' }); continue; } @@ -391,7 +392,7 @@ async function fetchGroup(ctx, { principalId, memo, group }) { let printed = null; try { - printed = await service.reprintPrintData(host, { + printed = await service.fetchPrintParams(host, { traceId, dbname, templateId, @@ -399,27 +400,31 @@ async function fetchGroup(ctx, { principalId, memo, group }) { expressCode: item.record.express_code || '', }); } catch (err) { - ctx.logger.warn('[waybill.printdata] 原单号打印失败 host=%s dbname=%s id=%s:%s', + ctx.logger.warn('[waybill.printdata] 拉取打印参数失败 host=%s dbname=%s id=%s:%s', host, dbname, logicalOrderId, err.message); - results.push({ ...base, success: false, message: `重新打印失败:${err.message}` }); + results.push({ ...base, success: false, message: `拉取打印参数失败:${err.message}` }); continue; } - // 安全闸:原单号打印不该换号;换号说明平台发了新面单(已消耗),必须暴露出来 + // 安全闸:复用原号的调用不该换号;换号说明平台分配了新面单(已消耗),必须暴露出来 const codes = Array.isArray(printed.waybill_codes) ? printed.waybill_codes.map(String) : []; if (codes.length && !codes.includes(String(item.waybillCode))) { - ctx.logger.error('[waybill.printdata] 重打返回了新运单号,已消耗面单!原号=%s 新号=%s', item.waybillCode, codes.join(',')); + ctx.logger.error('[waybill.printdata] 拉取参数时平台返回了新运单号,已分配面单!原号=%s 新号=%s', item.waybillCode, codes.join(',')); results.push({ ...base, success: false, - message: `重打返回了新运单号 ${codes.join(',')}(原号 ${item.waybillCode}),已消耗面单,请人工核对`, + message: `平台返回了新运单号 ${codes.join(',')}(原号 ${item.waybillCode}),已分配面单,请人工核对`, }); continue; } const document = (printed.documents || []).find(doc => doc && String(doc.params || '').trim()) || (printed.documents || [])[0]; if (!document || !document.params) { - results.push({ ...base, success: false, message: '平台重打后没有返回 params(access_token 串)' }); + results.push({ + ...base, + success: false, + message: '该模板没有返回 params(只有抖店面单需要 params;其它平台请用取号返回的 printinfo 打单)', + }); continue; } const paramsTimestamp = pickParamsTimestamp(document.params); diff --git a/店管家取号-旧系统提取.md b/店管家取号-旧系统提取.md index 7915301..9dd8490 100644 --- a/店管家取号-旧系统提取.md +++ b/店管家取号-旧系统提取.md @@ -276,11 +276,11 @@ WaybillCodeCreateDate='2026-11-04 08:20:37' (`access_token=…&method=logistics.getShopKey×tamp=…&sign=…`,`timestamp` = 该打印记录的 `CreateDate`)。 ⚠️ 实测确认:`POST /PrintHistory/LoadPrintData` **只是回放那次打印的签名,不会重新签发** (换 `FxPageType=1/2`、加 `IsRePrint` / `IsRefresh` 都返回同一个 `timestamp`/`sign`)。 - ✅ 要新签名只能让平台重新打印:`ExpressPrint` + `PrintMethod=Normal` + `IsIgnoreWaybillRepeat=true` + ✅ 要新签名只能让平台重新下发(不是重打,只是拿一份新的打印数据):`ExpressPrint` + `PrintMethod=Normal` + `IsIgnoreWaybillRepeat=true` → 实测**复用订单已有运单号**(不消耗面单)、`params.timestamp` = 当前时间。 - 对照:`PrintMethod=NewPrint`(或 `IsIgnoreWaybillRepeat=false`)会分配新号并消耗面单,重打绝不能用。 + 对照:`PrintMethod=NewPrint`(或 `IsIgnoreWaybillRepeat=false`)会分配新号并消耗面单,拉取 params 绝不能用。 因此取号记录里同时落了 `dbname`、`platform_host`(实际命中的域名)与 `cai_niao_auth_info_id`(= 店铺唯一标识), - 后续按「店铺标识 + 运单号」即可定位到该运单号对应的取号记录,再做原单号重打。 + 后续按「店铺标识 + 运单号」即可定位到该运单号对应的取号记录,再拉一份新的打印参数。 对外方法见 `deliveryorder.getprintdata`(`WMS-OMS-取号对接.md` §4.7.1)。 - **params 是逐张面单的**:`printDataJson.PrintDataList.task.documents[].documentID` = 运单号, `contents[].params` 是该张面单的内容;同店铺可共用的只有 `PrinterConfig` 与 `templateURL`,