From ccd007005ace488f3acf8ccde0aa03686e59379e Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sat, 7 Nov 2026 06:47:32 +0800 Subject: [PATCH] =?UTF-8?q?feat(waybill):=20=E5=8F=96=E5=8F=B7=E5=93=8D?= =?UTF-8?q?=E5=BA=94=E5=9B=9E=E4=BC=A0=20print=5Fhistory=5Fids=EF=BC=8C?= =?UTF-8?q?=E7=94=B1=20WMS=20=E8=87=AA=E8=A1=8C=E8=90=BD=E5=BA=93?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit deliveryorder.getwaybill 的逐单结果新增: - print_history_ids: [{ id, pid, waybill_code, batch_index }](每张面单一条,与 waybill_codes 对应) - print_history_id: 第一张的 id(便捷值) 平台不会把 printHistoryId 放进面单数据(printinfo 里对应字段恒为 null), 只能从 Data.PrintHistoryIds[] 取,所以直接在响应里给到 WMS,便于其对账/查重。 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- WMS-OMS-取号对接.md | 14 ++++++++++++-- backend/app/lib/waybillGet.js | 5 +++++ 店管家取号-旧系统提取.md | 3 ++- 3 files changed, 19 insertions(+), 3 deletions(-) diff --git a/WMS-OMS-取号对接.md b/WMS-OMS-取号对接.md index ce051f8..ec88d2d 100644 --- a/WMS-OMS-取号对接.md +++ b/WMS-OMS-取号对接.md @@ -170,7 +170,11 @@ OMS 侧实现:`D:\oms\backend\app\lib\wms\sign.js`。 "package_index": 0, "cai_niao_auth_info_id": 364375, "printinfo": "eyJQYXBlclNpemUiOi...", - "signature": "MEQCIB..." + "signature": "MEQCIB...", + "print_history_ids": [ + { "id": "10000078656002", "pid": "3316997317085033076", "waybill_code": "78812345678901", "batch_index": 1 } + ], + "print_history_id": "10000078656002" }, { "delivery_order_code": "XK202611040002", @@ -201,9 +205,11 @@ OMS 侧实现:`D:\oms\backend\app\lib\wms\sign.js`。 | `signature` | 成功 | 面单签名,取 `documents[].contents[0].signature`;视频号自定义模板平台不返回 `contents`,此时为空串 | | `encryptprintinfo` | 成功 | 加密打印数据,取 `contents[0].encryptedData`(需要加密打印的平台才有值,店管家当前为空串) | | `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`)**/ 队列状态**,不要依赖 OMS 的库。 +> **WMS 仍需落自己的 `order_express`**(`waybill_code` + `printinfo` + `signature` + `encryptprintinfo` + `ver` + `cai_niao_auth_info_id` + `print_history_ids`)**/ 队列状态**,不要依赖 OMS 的库。 > 每次取号的平台原始返回都会写进 OMS 的 `waybill_fetch_records`(见 §4.7),出问题可直接查表对账,不必再让 WMS 重放报文。 > > **同一包裹重复取号会拿到新号**:店管家「新单号打印」口径是每次分配一个新号(`WaybillCodePid` 第二段自增), @@ -396,6 +402,10 @@ OMS 用它 + 运单号定位到那次取号的打印记录(`waybill_fetch_reco 单条失败原因:`未找到该运单号的取号记录(可能不是通过 OMS 取的号)` / `取号记录里没有该运单号的打印记录ID(PrintHistoryIds),无法换新的打印数据`。 +> 📌 **取号响应也会返回 `print_history_ids` / `print_history_id`**(见 §4.2),WMS 可按需落库; +> 但打印前换 params 时**不要求** WMS 传它 —— 传「`caiNiaoAuthInfoIds` + `waybillCodes`」由 OMS 查库即可, +> 想省一次查库时再直传 `printHistoryIds`。两者以 OMS 库里的记录为准(重打会新增打印记录)。 + ```sql -- 打印前换 params 时 OMS 内部按这条定位(同一个运单号多次取号取最新一条) SELECT id, delivery_order_code, print_history_ids, cai_niao_auth_info_id, dbname, platform_host diff --git a/backend/app/lib/waybillGet.js b/backend/app/lib/waybillGet.js index 5d9d0bd..58a2c20 100644 --- a/backend/app/lib/waybillGet.js +++ b/backend/app/lib/waybillGet.js @@ -619,6 +619,11 @@ async function callPlatform(ctx, { principalId, warehouseId, code, expressCode, // 面单打印数据:平台原样返回,WMS 落 order_express 后打印时直接使用 printinfo: detail.printinfo, signature: detail.signature, + // 打印记录ID(平台 PrintHistoryIds):WMS 自行落库;重取打印数据时可直接用 printHistoryIds 直传 + print_history_ids: Array.isArray(detail.print_history_ids) ? detail.print_history_ids : [], + print_history_id: (Array.isArray(detail.print_history_ids) && detail.print_history_ids[0] + ? String(detail.print_history_ids[0].id || '') + : ''), // 需要加密打印的平台(如菜鸟系)才有值,店管家视频号自定义模板一般为空 encryptprintinfo: detail.encryptprintinfo, ver: detail.ver, diff --git a/店管家取号-旧系统提取.md b/店管家取号-旧系统提取.md index 740d283..8305774 100644 --- a/店管家取号-旧系统提取.md +++ b/店管家取号-旧系统提取.md @@ -267,7 +267,8 @@ WaybillCodeCreateDate='2026-11-04 08:20:37' - 打印记录(`Data.PrintHistoryIds`):元素 `{ Id, Pid, WaybillCode, WaybillCodeChild, BatchIndex }`, **`Id` 即 printHistoryId**,每打一张新增一条;`Pid` 与 `WaybillCode[].WaybillCodePid`、`WaybillCodeId` 是不同概念,别混。 OMS 把解析结果(`id/pid/waybill_code/batch_index` 数组)落到 `waybill_fetch_records.print_history_ids`, - 供后续重打/作废(`PrintHistory/LoadPrintData` 按它回捞)使用,暂不回传 WMS。 + 并在取号响应里回传 `print_history_ids` / `print_history_id`(WMS 自行落库), + 后续重打/作废(`PrintHistory/LoadPrintData` 按它回捞)以 OMS 库里的记录为准。 - **printHistoryId 不在「面单数据」里**(实测:`PrintDataJson.id = null`、`printDataJson.printHistoryIds = null`, `WaybillCode[]` 里也没有该字段),只在响应顶层:取号是 `Data.PrintHistoryIds[].Id`, 回捞打印数据是 `Data[].ID`(实测 `10000078656212`,number)。要拿它只能从这两个顶层字段取。