From bcca0075bed9f191a8b1f92c137eb8c6e2db1289 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sat, 7 Nov 2026 08:12:54 +0800 Subject: [PATCH] =?UTF-8?q?feat(external-send):=20=E5=8F=91=E8=B4=A7?= =?UTF-8?q?=E5=9B=9E=E4=BC=A0=E6=94=B9=E7=94=A8=E6=9C=AC=E5=9C=B0=E5=BF=AB?= =?UTF-8?q?=E7=85=A7=E6=8B=BC=E6=8A=A5=E6=96=87=EF=BC=8C=E4=B8=8D=E5=86=8D?= =?UTF-8?q?=E5=9B=9E=E8=AF=BB=E5=B9=B3=E5=8F=B0=E8=AE=A2=E5=8D=95=E8=A1=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 拉单时已把平台整行存进 orders.external_data(实测 113 字段,含 PathFlowCode / ShippingType / OrderTags / SubOrders[].OrderItemId 这些状态表没有的内部字段), 发货报文其实就是这一行,所以没必要再回读平台。 - 新增 lib/dgjSendRow.js#buildSendRow:快照(静态内部字段) + 状态表(收件人/平台单号/运单号,可能晚于快照更新) + 最近一次成功取号记录(WaybillCodeId / Pid / ExpressCpCode / CreateDate) 拼成订单行;PrintState/ExpressPrintTime 用取号记录覆盖(快照里恒为 0/空) - externalSendSync.resolveSendRow:快照可用就不访问平台;缺快照(历史单)才回读兜底 - dgj 暴露 buildSendOrder 静态方法,供脚本/单测复用同一口径 实测(本地真实单 dgj-10000279877231):拼出的 Orders[0] 覆盖抓包全部 47 个关键字段 (163 个顶层键),面单块含 WaybillCodeId=10000298258339、Pid=ced304e7c1ffd618_0_1。 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- backend/app/lib/dgjSendRow.js | 173 ++++++++++++++++++++++++ backend/app/lib/printPlatform/dgj.js | 11 ++ backend/app/service/externalSendSync.js | 72 ++++++++-- backend/test/app/lib/dgjSendRow.test.js | 135 ++++++++++++++++++ 店管家取号-旧系统提取.md | 3 +- 5 files changed, 381 insertions(+), 13 deletions(-) create mode 100644 backend/app/lib/dgjSendRow.js create mode 100644 backend/test/app/lib/dgjSendRow.test.js diff --git a/backend/app/lib/dgjSendRow.js b/backend/app/lib/dgjSendRow.js new file mode 100644 index 0000000..df25775 --- /dev/null +++ b/backend/app/lib/dgjSendRow.js @@ -0,0 +1,173 @@ +'use strict'; + +/** + * 用本地快照组装店管家「发货回传」需要的订单行 + * + * 背景:`POST /NewOrder/OnlineSend` 的 `Orders[i]` 基本就是平台订单行本身。 + * 拉单时我们已把平台整行存进老表 `orders.external_data`(实测 113 个字段,含 + * `PathFlowCode` / `ShippingType` / `OrderTags` / `SubOrders[].OrderItemId` 等内部字段), + * 因此发货时不必再回读平台,只需把「快照 + 状态表(最新业务字段)+ 取号记录(最新面单信息)」拼起来。 + * + * 时效性处理: + * - 快照里的 `PrintState` / `ExpressPrintTime` / `WaybillCodes` 是拉单那一刻的, + * 取号之后才有正确值 → 用取号记录(`waybill_fetch_records`)覆盖; + * - 收件人、平台单号等以状态表为准(快照可能早于改地址/改备注)。 + */ + +/** + * 安全解析 JSON(快照/原始响应可能是字符串) + * @param {*} value 原始值 + * @return {Object|null} 解析结果 + */ +function parseJson(value) { + if (!value) return null; + if (typeof value === 'object') return value; + try { + return JSON.parse(String(value)); + } catch { + return null; + } +} + +/** + * 从取号记录的平台原始返回里取面单信息(WaybillCode[] 第一张) + * @param {string|Object} rawResponse 取号记录的 raw_response + * @return {Object|null} 平台面单对象 + */ +function pickWaybillFromFetchRecord(rawResponse) { + const json = parseJson(rawResponse); + const list = json && json.Data && Array.isArray(json.Data.WaybillCode) ? json.Data.WaybillCode : []; + return list.find(item => item && item.WaybillCode) || null; +} + +/** + * 把平台面单对象转成订单行里的 `WaybillCodes[]` 元素 + * @param {Object} waybill 平台面单对象(ExpressPrint 返回) + * @param {Object} params 补充参数 + * @param {string} [params.templateId] 面单模板ID + * @param {string} [params.expressCode] 快递编码 + * @param {string} [params.expressName] 快递名称 + * @param {Array} [params.subOrders] 平台子单(生成面单-商品关联) + * @return {Object|null} WaybillCodes 元素 + */ +function toWaybillEntry(waybill, { templateId = '', expressCode = '', expressName = '', subOrders = [] } = {}) { + if (!waybill || !waybill.WaybillCode) return null; + const cpCode = waybill.RealCpCode || waybill.CpCode || expressCode || ''; + const orderId = String(waybill.WaybillCode); + const masterIdBase = `${waybill.OrderId || ''}_${orderId}_EI`; + return { + TemplateId: templateId || null, + ExpressCpCode: cpCode, + ExpressName: expressName || cpCode, + WaybillCode: orderId, + ChildWaybillCode: null, + ChildWaybillCodes: null, + CompanyCode: cpCode, + WaybillCodeId: waybill.WaybillCodeId || null, + CreateDate: waybill.WaybillCodeCreateDate || '', + IsSended: false, + IsPreviewed: null, + TotalWeight: 0, + SendType: 0, + Status: 1, + UniqueKey: waybill.WaybillUniqueKey || null, + Pid: waybill.WaybillCodePid || null, + LogisticType: null, + WaybillCodeOrderProducts: (subOrders || []).map(sub => ({ + Id: null, + MasterId: `${masterIdBase}_${sub.OrderItemId || ''}`, + OrderItemId: sub.OrderItemId, + OrderItemIdStr: String(sub.OrderItemId == null ? '' : sub.OrderItemId), + Quantity: 1, + OrderItemCode: sub.OrderItemCode, + SendType: null, + ParentUniqueKey: null, + WaybillCodeId: waybill.WaybillCodeId || null, + StockCode: null, + })), + IsManual: false, + }; +} + +/** + * 组装发货回传用的订单行(本地快照优先,不访问平台) + * @param {Object} params 参数 + * @param {Object} params.order 配送状态行(含 parent_order_no / 收件人 / extend_props / express_codes) + * @param {Object} [params.snapshot] 拉单快照(orders.external_data) + * @param {Object} [params.fetchRecord] 最近一次成功取号记录(waybill_fetch_records) + * @param {Object} [params.template] 快递接口记录(template_id / express_company_code / express_company_name) + * @return {Object|null} 订单行;快照缺失且状态表信息不足以拼装时返回 null(调用方回退到回读平台) + */ +function buildSendRow({ order, snapshot, fetchRecord, template }) { + const snap = snapshot && typeof snapshot === 'object' ? snapshot : null; + if (!snap) return null; + + const extendProps = order && typeof order.extend_props === 'object' && order.extend_props ? order.extend_props : {}; + const logicalOrderId = String((order && (order.parent_order_no || order.order_no)) || snap.LogicOrderId || '').trim(); + if (!logicalOrderId) return null; + + const templateId = String((template && template.template_id) || ''); + const expressCode = String((template && template.express_company_code) || '').trim(); + const expressName = String((template && template.express_company_name) || '').trim(); + const subOrders = Array.isArray(snap.SubOrders) ? snap.SubOrders : []; + + // 面单信息:取号记录最新;没有取号记录时退回快照里的(可能为空) + const waybill = pickWaybillFromFetchRecord(fetchRecord && fetchRecord.raw_response); + const waybillEntry = toWaybillEntry(waybill, { templateId, expressCode, expressName, subOrders }); + let waybillCodes = Array.isArray(snap.WaybillCodes) ? snap.WaybillCodes.filter(item => item && item.WaybillCode) : []; + if (waybillEntry) waybillCodes = [ waybillEntry ]; + + const statusCodes = String((order && order.express_codes) || '').trim(); + const statusList = (() => { + if (!statusCodes) return []; + const parsed = parseJson(statusCodes); + if (Array.isArray(parsed)) return parsed.map(String); + return statusCodes.split(',').map(item => item.trim()).filter(Boolean); + })(); + const waybillCode = String((waybillEntry && waybillEntry.WaybillCode) || statusList[0] || order && order.express_code || '').trim(); + if (!waybillCode) return null; + + const pick = (stateValue, snapKey) => { + const value = stateValue == null ? '' : String(stateValue).trim(); + return value || (snap[snapKey] == null ? '' : String(snap[snapKey])); + }; + + return { + ...snap, + Id: snap.Id || logicalOrderId, + LogicOrderId: logicalOrderId, + PlatformOrderId: logicalOrderId, + CustomerOrderId: pick(extendProps.platform_order_no || (order && order.oaid_order_source_code), 'PlatformOrderId'), + PathFlowCode: snap.PathFlowCode || '', + ShopId: snap.ShopId, + ShopName: snap.ShopName || extendProps.platform_shop_name || '', + PlatformType: snap.PlatformType || '', + PlatformTypeName: snap.PlatformTypeName || '', + FxUserId: snap.FxUserId, + UpFxUserId: snap.UpFxUserId, + OrderTags: Array.isArray(snap.OrderTags) ? snap.OrderTags : [], + SubOrders: subOrders, + WaybillCodes: waybillCodes, + LastWaybillCode: waybillCode, + // 取号/打印之后才有:快照里恒为 0 / 空 + PrintState: 1, + ExpressPrintTime: (fetchRecord && fetchRecord.created_at) || snap.ExpressPrintTime || '', + // 收件人以状态表为准(快照可能早于改地址) + ToName: pick(order && order.receiver, 'ToName'), + ToPhone: pick(order && (order.mobile || order.tel), 'ToPhone'), + ToProvince: pick(order && order.province, 'ToProvince'), + ToCity: pick(order && order.city, 'ToCity'), + ToCounty: pick(order && order.area, 'ToCounty'), + ToTown: pick(order && order.town, 'ToTown'), + ToAddress: pick(order && order.detail_address, 'ToAddress'), + ToFullAddress: pick(order && order.address, 'ToFullAddress'), + }; +} + +module.exports = { + buildSendRow, + // 供单测复用 + parseJson, + pickWaybillFromFetchRecord, + toWaybillEntry, +}; diff --git a/backend/app/lib/printPlatform/dgj.js b/backend/app/lib/printPlatform/dgj.js index a2de00d..5fae0f2 100644 --- a/backend/app/lib/printPlatform/dgj.js +++ b/backend/app/lib/printPlatform/dgj.js @@ -3117,6 +3117,17 @@ class DgjService extends PrintPlatformService { return extractPrintHistoryIds(printed); } + /** + * 组装发货回传单体报文(`Orders[i]`),供脚本/单测复用同一口径 + * @param {Object} row 订单行(平台行或本地快照拼装结果) + * @param {number} index 序号(0 基) + * @param {string} [expressCode] 快递编码兜底 + * @return {Object} Orders[i] + */ + static buildSendOrder(row, index, expressCode = '') { + return buildSendOrder(row, index, expressCode); + } + /** * 构造店管家表单(PHP http_build_query 口径,嵌套用括号) * @param {Object} data 表单数据 diff --git a/backend/app/service/externalSendSync.js b/backend/app/service/externalSendSync.js index 73734a5..012c923 100644 --- a/backend/app/service/externalSendSync.js +++ b/backend/app/service/externalSendSync.js @@ -1,6 +1,7 @@ 'use strict'; const Service = require('egg').Service; +const { buildSendRow } = require('../lib/dgjSendRow'); /** 外部发货同步状态 */ const SEND_STATUS = { @@ -118,13 +119,7 @@ class ExternalSendSyncService extends Service { const { service, platformType, dbname, platformCode, template } = target; const host = service.constructor.resolveOrderHost(platformType); - const row = await service.findPlatformOrderRow(host, { - traceId: await this.resolveTraceId(service), - dbname, - logicalOrderId: String(order.parent_order_no || order.order_no || ''), - platformOrderId: String((order.extend_props && order.extend_props.platform_order_no) || order.oaid_order_source_code || ''), - placeOrderTime: order.place_order_time || order.pay_time || order.created_at, - }); + const row = await this.resolveSendRow(order, { service, host, dbname, platformCode, template }); if (!row) { throw new Error(`外部打单平台未找到该订单(平台 ${platformCode},系统编号 ${order.parent_order_no || order.order_no})`); } @@ -154,12 +149,12 @@ class ExternalSendSyncService extends Service { if (target) { await target.service.loginByPassword(); const host = target.service.constructor.resolveOrderHost(target.platformType); - const row = await target.service.findPlatformOrderRow(host, { - traceId: await this.resolveTraceId(target.service), + const row = await this.resolveSendRow(order, { + service: target.service, + host, dbname: target.dbname, - logicalOrderId: String(order.parent_order_no || order.order_no || ''), - platformOrderId: String((order.extend_props && order.extend_props.platform_order_no) || order.oaid_order_source_code || ''), - placeOrderTime: order.place_order_time || order.pay_time || order.created_at, + platformCode: target.platformCode, + template: target.template, }); if (!row) throw new Error('外部打单平台未找到该订单'); await target.service.sendOrders(host, { @@ -187,6 +182,59 @@ class ExternalSendSyncService extends Service { } } + /** + * 组装发货回传用的订单行:优先用本地快照(不访问平台),快照缺失才回读平台 + * @param {Object} order 配送状态行 + * @param {Object} ctxInfo 上下文 + * @param {Object} ctxInfo.service 打单平台服务 + * @param {string} ctxInfo.host 订单域名 + * @param {string} ctxInfo.dbname 分区库名 + * @param {Object} [ctxInfo.template] 快递接口记录 + * @return {Promise} 订单行 + */ + async resolveSendRow(order, { service, host, dbname, template }) { + const { ctx } = this; + const logicalOrderId = String(order.parent_order_no || order.order_no || ''); + + // 1) 拉单快照:老表 orders.external_data(平台整行,含 PathFlowCode / ShippingType / SubOrders) + let snapshot = null; + try { + const legacy = await ctx.model.Order.findOne({ + where: { principal_id: order.principal_id, order_no: order.order_no }, + attributes: [ 'id', 'external_data' ], + }); + snapshot = legacy && legacy.external_data ? legacy.external_data : null; + } catch { + snapshot = null; + } + + // 2) 最近一次成功取号记录:拿最新面单信息(WaybillCodeId / Pid / 快递编码) + let fetchRecord = null; + if (order.express_code) { + fetchRecord = await ctx.model.WaybillFetchRecord.findOne({ + where: { + principal_id: order.principal_id, + delivery_order_code: { [ ctx.app.Sequelize.Op.like ]: `${order.order_no}%` }, + status: 1, + }, + order: [[ 'id', 'DESC' ]], + }); + } + + const localRow = buildSendRow({ order, snapshot, fetchRecord, template }); + if (localRow) return localRow; + + // 3) 没有快照(历史单/非平台单):退回回读平台订单行 + ctx.logger.info('[external-send] %s 没有本地快照,回读平台订单行', order.order_no); + return await service.findPlatformOrderRow(host, { + traceId: await this.resolveTraceId(service), + dbname, + logicalOrderId, + platformOrderId: String((order.extend_props && order.extend_props.platform_order_no) || order.oaid_order_source_code || ''), + placeOrderTime: order.place_order_time || order.pay_time || order.created_at, + }); + } + /** * 记录一次失败:累加次数,达到上限转「异常」 * @param {Object} order 配送表订单行 diff --git a/backend/test/app/lib/dgjSendRow.test.js b/backend/test/app/lib/dgjSendRow.test.js new file mode 100644 index 0000000..8fc8fa1 --- /dev/null +++ b/backend/test/app/lib/dgjSendRow.test.js @@ -0,0 +1,135 @@ +'use strict'; + +const { assert } = require('egg-mock/bootstrap'); +const { buildSendRow, pickWaybillFromFetchRecord, toWaybillEntry } = require('../../../app/lib/dgjSendRow'); + +/** + * 最小可用的拉单快照(字段名与店管家订单行一致) + * @param {Object} overrides 覆盖字段 + * @return {Object} 快照 + */ +function buildSnapshot(overrides = {}) { + return { + Id: '10000279877231', + LogicOrderId: '10000279877231', + PlatformOrderId: '5127000000000000001', + PathFlowCode: '10000001527089', + ShippingType: 'ENCRYPTED_BLOB', + ShopId: 9560713, + ShopName: '13668975305(意洁)', + PlatformType: 'Taobao', + PlatformTypeName: '淘宝', + FxUserId: 1227061, + UpFxUserId: 953516, + OrderTags: [{ Tag: 'OutChannel', TagValue: 'douyin' }], + MergeredType: 0, + ExtField1: '', + ExtField2: '', + SellerRemarkFlagTag: '', + ReceiverIsChange: false, + IsPddCrossBorderOrder: false, + IsPddCourierDoorToDoorCollect: false, + IsOfflineOrder: false, + DataFlag: 1, + PayTime: '2026-11-06 19:16:01', + PrintState: 0, + WaybillCodes: [], + SubOrders: [{ OrderItemId: 10000305495583, OrderItemCode: '10000305495583', ProductID: 881526926136, SkuCode: '007' }], + ToName: '吴*', + ToPhone: '1**********', + ToProvince: '湖北省', + ToCity: '黄冈市', + ToCounty: '武穴市', + ToTown: '武穴街道', + ToAddress: '武穴街道********', + ToFullAddress: '湖北省黄冈市武穴市武穴街道********', + ...overrides, + }; +} + +/** 取号记录(raw_response 是 ExpressPrint 响应) */ +function buildFetchRecord() { + return { + express_code: 'STO', + waybill_code: '770357410089880', + created_at: new Date('2026-11-07T07:39:45Z'), + raw_response: JSON.stringify({ + Success: true, + Data: { + WaybillCode: [{ + WaybillCode: '770357410089880', + WaybillCodeId: 10000304201567, + WaybillCodePid: '8c51d72ab1f_2_1', + CpCode: 'STO', + RealCpCode: 'STO', + WaybillCodeCreateDate: '2026-11-07 07:39:45', + OrderId: '10000279877231', + }], + }, + }), + }; +} + +const template = { template_id: '10776786', express_company_code: 'STO', express_company_name: '申通' }; + +describe('lib/dgjSendRow 本地快照拼发货报文', () => { + it('从快照 + 取号记录拼出订单行(不回读平台)', () => { + const order = { + order_no: 'dgj-10000279877231', + parent_order_no: '10000279877231', + oaid_order_source_code: '5127000000000000001', + express_code: 'STO', + express_codes: JSON.stringify([ '770357410089880' ]), + receiver: '吴*', + mobile: '1**********', + province: '湖北省', + city: '黄冈市', + area: '武穴市', + town: '武穴街道', + detail_address: '武穴街道********', + address: '湖北省黄冈市武穴市武穴街道********', + extend_props: { platform_order_no: '5127000000000000001' }, + }; + const row = buildSendRow({ order, snapshot: buildSnapshot(), fetchRecord: buildFetchRecord(), template }); + console.log('拼装结果:', row.LogicOrderId, row.WaybillCode || row.LastWaybillCode, '| PrintState:', row.PrintState, + '| 面单:', row.WaybillCodes[0].WaybillCodeId, row.WaybillCodes[0].Pid); + assert.strictEqual(row.PathFlowCode, '10000001527089'); + assert.strictEqual(row.ShippingType, 'ENCRYPTED_BLOB'); + assert.strictEqual(row.LastWaybillCode, '770357410089880'); + assert.strictEqual(row.PrintState, 1, '取号后应按已打印处理'); + assert.strictEqual(row.UpFxUserId, 953516); + assert.strictEqual(row.WaybillCodes[0].WaybillCodeId, 10000304201567); + assert.strictEqual(row.WaybillCodes[0].Pid, '8c51d72ab1f_2_1'); + assert.strictEqual(row.WaybillCodes[0].ExpressCpCode, 'STO'); + }); + + it('收件人以状态表为准(快照可能早于改地址)', () => { + const order = { + order_no: 'dgj-1', parent_order_no: '1', express_codes: JSON.stringify([ 'W1' ]), + receiver: '新收件人', mobile: '13900000000', province: '广东省', city: '广州市', area: '白云区', + town: '钟落潭镇', detail_address: '新地址', address: '广东省广州市白云区新地址', + extend_props: {}, + }; + const row = buildSendRow({ order, snapshot: buildSnapshot(), fetchRecord: buildFetchRecord(), template }); + assert.strictEqual(row.ToName, '新收件人'); + assert.strictEqual(row.ToAddress, '新地址'); + }); + + it('没有快照 / 没有运单号时返回 null(上层回退回读平台)', () => { + assert.strictEqual(buildSendRow({ order: { order_no: 'dgj-1', parent_order_no: '1' }, snapshot: null }), null); + const noWaybill = buildSendRow({ + order: { order_no: 'dgj-1', parent_order_no: '1', extend_props: {} }, + snapshot: buildSnapshot(), + fetchRecord: null, + }); + assert.strictEqual(noWaybill, null); + }); + + it('面单信息解析:优先 RealCpCode,缺字段不炸', () => { + const waybill = pickWaybillFromFetchRecord(buildFetchRecord().raw_response); + const entry = toWaybillEntry(waybill, { templateId: '10776786', expressCode: 'STO', subOrders: [{ OrderItemId: 1, OrderItemCode: 'A' }] }); + assert.strictEqual(entry.ExpressCpCode, 'STO'); + assert.strictEqual(entry.WaybillCodeOrderProducts[0].OrderItemId, 1); + assert.strictEqual(pickWaybillFromFetchRecord('not-json'), null); + }); +}); diff --git a/店管家取号-旧系统提取.md b/店管家取号-旧系统提取.md index b332b73..0a05a7f 100644 --- a/店管家取号-旧系统提取.md +++ b/店管家取号-旧系统提取.md @@ -81,8 +81,9 @@ OMS 实现: | 位置 | 作用 | |---|---| +| `lib/dgjSendRow.js#buildSendRow` | **用本地快照拼订单行**(不访问平台):快照 `orders.external_data`(`PathFlowCode`/`ShippingType`/`OrderTags`/`SubOrders`)+ 状态表(收件人/平台单号/运单号)+ 最近一次成功取号记录(`WaybillCodeId`/`Pid`/`ExpressCpCode`) | | `dgj.sendOrders(host, { traceId, dbname, rows, templateId, expressCompanyId, expressCode })` | 按上面口径组装并提交;整包或逐单失败抛「店管家发货同步失败:…」 | -| `service/externalSendSync.js` | 配送后同步的状态机(待同步 → 已同步 / 待重试 → 3 次转异常),把模板/快递公司ID 一起传下去 | +| `service/externalSendSync.js` | 配送后同步的状态机(待同步 → 已同步 / 待重试 → 3 次转异常);快照缺失时才回读平台订单行兜底 | 状态字段(配送表 `order_status_delivery`,所有状态表 + 历史表同构):