feat(external-send): 发货回传改用本地快照拼报文,不再回读平台订单行

拉单时已把平台整行存进 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>
This commit is contained in:
liufumingren 2026-11-07 08:12:54 +08:00
parent 01ab1ccdab
commit bcca0075be
5 changed files with 381 additions and 13 deletions

View File

@ -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,
};

View File

@ -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 表单数据

View File

@ -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<Object|null>} 订单行
*/
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 配送表订单行

View File

@ -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);
});
});

View File

@ -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`,所有状态表 + 历史表同构):