From 7f8cff808b7e9b7f9a323d2c248cefe0c1ebf5ba Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sat, 7 Nov 2026 06:26:46 +0800 Subject: [PATCH] =?UTF-8?q?feat(waybill):=20=E5=8F=96=E5=8F=B7=E6=97=B6?= =?UTF-8?q?=E8=A7=A3=E6=9E=90=E5=B9=B6=E7=95=99=E7=97=95=E6=89=93=E5=8D=B0?= =?UTF-8?q?=E8=AE=B0=E5=BD=95ID=EF=BC=88PrintHistoryIds=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 平台 ExpressPrint 响应里有 Data.PrintHistoryIds,元素 { Id, Pid, WaybillCode, WaybillCodeChild, BatchIndex },其中 Id 即 printHistoryId:重打/作废/查打印记录 (PrintHistory/LoadPrintData)都按它回捞。之前只用了 WaybillCode/printinfo, 这块被丢掉了。 - dgj.fetchWaybillNo 解析为 [{ id, pid, waybill_code, batch_index }] - waybillGet 写入 waybill_fetch_records.print_history_ids(JSON 数组,多包裹对齐) - 仅本地留痕,不改回 WMS 的响应契约 - 迁移 20261107030000 加列;单测覆盖真实响应样例与多包裹/缺失字段 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- backend/app/lib/printPlatform/dgj.js | 36 +++++++++++++++++++ backend/app/lib/waybillGet.js | 6 +++- backend/app/model/waybillFetchRecord.js | 4 +++ ...nt-history-ids-to-waybill-fetch-records.js | 23 ++++++++++++ backend/test/app/lib/printPlatformDgj.test.js | 32 +++++++++++++++++ 店管家取号-旧系统提取.md | 6 +++- 6 files changed, 105 insertions(+), 2 deletions(-) create mode 100644 backend/database/migrations/20261107030000-add-print-history-ids-to-waybill-fetch-records.js diff --git a/backend/app/lib/printPlatform/dgj.js b/backend/app/lib/printPlatform/dgj.js index 3892907..16c02be 100644 --- a/backend/app/lib/printPlatform/dgj.js +++ b/backend/app/lib/printPlatform/dgj.js @@ -534,6 +534,31 @@ function extractWaybillCodes(items) { return [ ...new Set(out) ]; } +/** + * 从 ExpressPrint 响应的 Data.PrintHistoryIds[] 里提取打印记录 + * + * 平台每打印一张面单就新增一条打印历史,`Id` 即打印记录ID(printHistoryId), + * 重打/作废/查打印记录(`PrintHistory/LoadPrintData`)都要用它。多包裹时数组长度 = 张数。 + * @param {Object} printed ExpressPrint 响应 + * @return {Array<{id: string, pid: string, waybill_code: string, batch_index: number|null}>} 打印记录 + */ +function extractPrintHistoryIds(printed) { + const list = printed && printed.Data && printed.Data.PrintHistoryIds; + const out = []; + for (const item of Array.isArray(list) ? list : []) { + if (!item || typeof item !== 'object') continue; + const id = String(item.Id == null ? '' : item.Id).trim(); + if (!id) continue; + out.push({ + id, + pid: String(item.Pid == null ? '' : item.Pid).trim(), + waybill_code: String(item.WaybillCode == null ? '' : item.WaybillCode).trim(), + batch_index: item.BatchIndex == null ? null : Number(item.BatchIndex), + }); + } + return out; +} + /** * 取平台返回的打印单据(`Data.PrintDataList.task.documents[]`) * @@ -2340,6 +2365,8 @@ class DgjService extends PrintPlatformService { return { waybill_code: waybillCodes[0], waybill_codes: waybillCodes, + // 打印记录ID(平台 PrintHistoryIds):重打/作废/查打印记录时平台按它回捞,仅本地留痕 + print_history_ids: extractPrintHistoryIds(printed), // 面单打印数据:原样透传(WMS 打印端直接塞进 task.printInfo) printinfo: firstPrintInfo(items, printed, waybillCodes[0]), signature: contents.signature, @@ -2852,6 +2879,15 @@ class DgjService extends PrintPlatformService { return isWaybillEnabled(); } + /** + * 从 ExpressPrint 响应里解析打印记录(`Data.PrintHistoryIds`) + * @param {Object} printed ExpressPrint 响应 + * @return {Array<{id: string, pid: string, waybill_code: string, batch_index: number|null}>} 打印记录 + */ + static extractPrintHistoryIds(printed) { + return extractPrintHistoryIds(printed); + } + /** * 构造店管家表单(PHP http_build_query 口径,嵌套用括号) * @param {Object} data 表单数据 diff --git a/backend/app/lib/waybillGet.js b/backend/app/lib/waybillGet.js index 21a3fa0..2a72ff1 100644 --- a/backend/app/lib/waybillGet.js +++ b/backend/app/lib/waybillGet.js @@ -418,6 +418,7 @@ async function loadAccountModel(ctx, memo, accountId, principalId) { * @param {string} [extra.raw] 平台原始返回 * @param {string} [extra.printinfo] 面单打印数据 * @param {string} [extra.signature] 面单签名 + * @param {Array} [extra.print_history_ids] 打印记录(平台 PrintHistoryIds:id/pid/waybill_code/batch_index) * @return {Promise} 无返回值 */ async function saveRecord(ctx, meta, result, extra = {}) { @@ -439,6 +440,7 @@ async function saveRecord(ctx, meta, result, extra = {}) { waybill_codes: result && result.waybill_codes ? JSON.stringify(result.waybill_codes) : '', printinfo: extra.printinfo || '', signature: extra.signature || '', + print_history_ids: Array.isArray(extra.print_history_ids) ? JSON.stringify(extra.print_history_ids) : '', raw_response: raw ? JSON.stringify(raw) : '', error_message: result && result.success ? '' : (result && result.message) || '', }); @@ -468,7 +470,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: '' }; + const detail = { raw: null, printinfo: '', signature: '', encryptprintinfo: '', 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; @@ -570,6 +572,8 @@ async function callPlatform(ctx, { principalId, warehouseId, code, expressCode, // 面单打印数据原样保留:既要透传给 WMS,也要落取号记录备查 detail.raw = fetched && fetched.raw ? fetched.raw : null; + // 打印记录ID(平台 PrintHistoryIds):仅本地留痕,不进 WMS 响应契约 + detail.print_history_ids = Array.isArray(fetched && fetched.print_history_ids) ? fetched.print_history_ids : []; detail.printinfo = String((fetched && fetched.printinfo) || ''); detail.signature = String((fetched && fetched.signature) || ''); detail.encryptprintinfo = String((fetched && fetched.encryptprintinfo) || ''); diff --git a/backend/app/model/waybillFetchRecord.js b/backend/app/model/waybillFetchRecord.js index 8cb062b..e85b404 100644 --- a/backend/app/model/waybillFetchRecord.js +++ b/backend/app/model/waybillFetchRecord.js @@ -28,6 +28,10 @@ module.exports = app => { waybill_codes: { type: TEXT, comment: '全部运单号(JSON 数组)' }, printinfo: { type: TEXT('medium'), comment: '面单打印数据(平台原样返回)' }, signature: { type: TEXT('medium'), comment: '面单签名(平台原样返回)' }, + print_history_ids: { + type: TEXT, + comment: '打印记录(平台 PrintHistoryIds,JSON 数组:id/pid/waybill_code/batch_index),重打/作废用', + }, raw_response: { type: TEXT('medium'), comment: '平台原始返回(JSON)' }, error_message: { type: TEXT, comment: '失败原因' }, created_at: { type: DATE, comment: '创建时间' }, diff --git a/backend/database/migrations/20261107030000-add-print-history-ids-to-waybill-fetch-records.js b/backend/database/migrations/20261107030000-add-print-history-ids-to-waybill-fetch-records.js new file mode 100644 index 0000000..45b7305 --- /dev/null +++ b/backend/database/migrations/20261107030000-add-print-history-ids-to-waybill-fetch-records.js @@ -0,0 +1,23 @@ +'use strict'; + +/** + * 取号记录增加「打印记录」(店管家 `PrintHistoryIds`)。 + * + * 平台每打印一张面单就新增一条打印历史,`Id` 即 printHistoryId:重打/作废/查打印记录 + * (`PrintHistory/LoadPrintData`)都按它回捞,因此取号成功时落库留痕。 + * 多包裹时存 JSON 数组,元素形如 `{ id, pid, waybill_code, batch_index }`。 + */ +module.exports = { + async up(queryInterface, Sequelize) { + await queryInterface.addColumn('waybill_fetch_records', 'print_history_ids', { + type: Sequelize.TEXT, + allowNull: true, + comment: '打印记录(平台 PrintHistoryIds,JSON 数组:id/pid/waybill_code/batch_index)', + after: 'signature', + }); + }, + + async down(queryInterface) { + await queryInterface.removeColumn('waybill_fetch_records', 'print_history_ids'); + }, +}; diff --git a/backend/test/app/lib/printPlatformDgj.test.js b/backend/test/app/lib/printPlatformDgj.test.js index 40c4101..7076997 100644 --- a/backend/test/app/lib/printPlatformDgj.test.js +++ b/backend/test/app/lib/printPlatformDgj.test.js @@ -43,3 +43,35 @@ describe('printPlatform/dgj isOrderFinished', () => { assert.strictEqual(DgjService.isOrderFinished(null), false); }); }); + +describe('printPlatform/dgj extractPrintHistoryIds', () => { + it('解析真实 ExpressPrint 响应的 PrintHistoryIds(打印记录ID)', () => { + const printed = { + Data: { + PrintHistoryIds: [ + { Id: 10000078656002, Pid: '3316997317085033076', WaybillCode: '9823617121121', WaybillCodeChild: null, BatchIndex: 1 }, + ], + WaybillCode: [{ WaybillCode: '9823617121121', WaybillCodeId: 10000298258339 }], + }, + }; + const list = DgjService.extractPrintHistoryIds(printed); + console.log('打印记录:', JSON.stringify(list)); + assert.deepStrictEqual(list, [ + { id: '10000078656002', pid: '3316997317085033076', waybill_code: '9823617121121', batch_index: 1 }, + ]); + }); + + it('多包裹按顺序返回,缺失数据不炸', () => { + const printed = { Data: { PrintHistoryIds: [{ Id: 1, Pid: 'a', WaybillCode: 'W1', BatchIndex: 1 }, { Id: 2, WaybillCode: 'W2' }, null, {}] } }; + const list = DgjService.extractPrintHistoryIds(printed); + assert.deepStrictEqual(list, [ + { id: '1', pid: 'a', waybill_code: 'W1', batch_index: 1 }, + { id: '2', pid: '', waybill_code: 'W2', batch_index: null }, + ]); + }); + + it('没有该字段时返回空数组', () => { + assert.deepStrictEqual(DgjService.extractPrintHistoryIds({ Data: {} }), []); + assert.deepStrictEqual(DgjService.extractPrintHistoryIds(null), []); + }); +}); diff --git a/店管家取号-旧系统提取.md b/店管家取号-旧系统提取.md index edb9875..33d5f45 100644 --- a/店管家取号-旧系统提取.md +++ b/店管家取号-旧系统提取.md @@ -264,6 +264,10 @@ WaybillCodeCreateDate='2026-11-04 08:20:37' 会拿回同一个 `WaybillCodeId` + 同一个号(我们的 08:20 / 08:39 两次就是这种情况,每次只新增一条打印历史 `PrintHistoryIds`), 换序号才会分配新号。 - `ExpressPrintTimes` 是打印次数,跟号码个数不是一回事(本单打印 4 次、只有 2 个号)。 +- 打印记录(`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。 - 因此 OMS「按 `LastWaybillCode` 复用」是错的判断;是否重复取号由 **OMS 幂等表(request_id)** 决定, 而**同一个包裹重复取号拿回同号**是平台行为,不是 bug。 @@ -410,7 +414,7 @@ $documentID = $PrintDataList["task"]["documents"][0]["documentID"]; // = 运单 | 动作 | 接口 | 说明 | |---|---|---| | 发货 | `POST /NewOrder/OnlineSendBatch` | 取号后通知平台发货;OMS 的发货由 WMS 回传 `deliveryorder.confirm` 处理,不在此调用 | -| 打印历史 | `POST /PrintHistory/LoadList` / `LoadPrintData` | 用于回捞运单号与打印数据;OMS 直接从 ExpressPrint 响应解析,暂不接入 | +| 打印历史 | `POST /PrintHistory/LoadList` / `LoadPrintData` | 用于回捞运单号与打印数据;OMS 直接从 ExpressPrint 响应解析,**打印记录ID(`Data.PrintHistoryIds[].Id`)已解析并落 `waybill_fetch_records.print_history_ids`**(重打/作废要用),列表接口暂不接入 | ---