fix(external-send): 发货回传改用 /NewOrder/OnlineSend 并按抓包补全报文

生产报错「店管家发货同步失败:请先勾选要发货的订单」= 平台没把提交的 Orders 当成有效选中项。

实测对比(2026-11-07):
- 空 Orders          → 「当前选中的订单都不是待发货状态,已取消发货」
- 我们的旧报文        → 「请先勾选要发货的订单」
- 抓包页面真实请求:`POST /NewOrder/OnlineSend`(不是 OnlineSendBatch),
  顶层带 TemplateId / ExpressCompanyId / ExcludeOrders / RequestBatchNumber,
  Orders[0] 带整行模型(ShopId、PlatformTypeName、UpFxUserId≠FxUserId、OrderTags、
  ShippingType 加密串、ExpressPrintTime、WaybillCodes、Items、OrderItemStrList 等)

改动:
- ONLINE_SEND_PATH 改为 /NewOrder/OnlineSend
- 新增 buildSendOrder:按抓包字段组装 Orders[i];再补 TemplateId/ExpressCompanyId 等顶层参数
- externalSendSync 把模板 ID / 快递公司ID / 快递编码传给 sendOrders
- 响应改为「整包 Success + Data.Orders[] 逐单结果」判定:
  逐单 IsSuccess=false 时,除「不是待发货状态/已发货/已取消/已关闭」(幂等)外都算失败

实测:新报文被平台接受(整包 Success=true, ErrorCode=200),
测试单返回逐单 ErrorMessage「订单不是待发货状态,请检查」(该单 08:06 已在平台手工发货),
按幂等口径视为已同步。

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-07 08:09:56 +08:00
parent c4943523b7
commit 01ab1ccdab
3 changed files with 187 additions and 85 deletions

View File

@ -45,9 +45,9 @@ const TEMPLATE_AVAILABLE_PATH = '/TemplateSet/CheckTemplateAvaliable';
const EXPRESS_PRINT_PATH = '/NewOrder/ExpressPrint';
/**
* 通知平台发货接口:把 OMS 的发货结果同步回店管家(**不消耗面单**)。
* 通知平台发货接口(`POST /NewOrder/OnlineSend`,**不消耗面单**)。
*/
const ONLINE_SEND_PATH = '/NewOrder/OnlineSendBatch';
const ONLINE_SEND_PATH = '/NewOrder/OnlineSend';
/**
* 按打印记录重新拉取面单打印数据(**只读,不消耗面单**)。
@ -81,6 +81,109 @@ function buildPlatformError(message, res) {
return error;
}
/**
* 提取发货回传的逐单失败(平台是「整包 Success + Data.Orders[] 逐单结果」)
* @param {Object} json 平台响应
* @return {Array<{logicOrderId: string, message: string}>} 逐单失败
*/
function extractSendOrderFailures(json) {
const list = json && json.Data && Array.isArray(json.Data.Orders) ? json.Data.Orders : [];
const out = [];
for (const item of list) {
if (!item || typeof item !== 'object') continue;
if (item.IsSuccess === true || Number(item.IsSuccess) === 1) continue;
out.push({
logicOrderId: String(item.LogicOrderId || item.OrderCode || ''),
message: String(item.ErrorMessage || item.ErrorMsg || '平台未返回原因'),
});
}
return out;
}
/**
* 组装发货回传的单条订单报文(对齐平台「待打订单 → 发货」实际请求,2026-11-07 抓包)
* @param {Object} row 平台订单行(findPlatformOrderRow 的返回)
* @param {number} index 序号(0 基)
* @param {string} [expressCode] 快递编码兜底
* @return {Object} Orders[i]
*/
function buildSendOrder(row, index, expressCode = '') {
const subOrders = Array.isArray(row.SubOrders) ? row.SubOrders : [];
const waybills = Array.isArray(row.WaybillCodes) ? row.WaybillCodes : [];
const firstWaybill = waybills.find(code => code && code.WaybillCode) || {};
const items = subOrders.map(sub => ({
OrderItemId: sub.OrderItemId,
OrderItemCode: sub.OrderItemCode,
Quantity: '1',
SkuCode: sub.SkuCode,
ProductCode: sub.ProductID,
OrderItemIdStr: String(sub.OrderItemId == null ? '' : sub.OrderItemId),
}));
const orderItems = subOrders.map(sub => sub.OrderItemId);
return {
Id: row.Id,
Index: index + 1,
LogicOrderId: row.LogicOrderId,
PlatformOrderId: row.LogicOrderId,
PathFlowCode: row.PathFlowCode,
CustomerOrderId: row.PlatformOrderId,
ExpressPrintTime: row.ExpressPrintTime || '',
ShopId: row.ShopId,
ShopName: row.ShopName || '',
PlatformTypeName: row.PlatformTypeName || '',
PlatformType: row.PlatformType,
PlatformStatus: 'waitsellersend',
RefunStatus: '',
FxUserId: row.FxUserId,
BuyerRemark: row.BuyerRemark || '',
SellerRemark: row.SellerRemark || '',
NewSellerRemark: '',
NewPrintRemark: '',
// 分销场景 UpFxUserId(上游厂家)≠ FxUserId,直接透传平台值,别用 FxUserId 顶替
UpFxUserId: row.UpFxUserId,
IsPddCrossBorderOrder: row.IsPddCrossBorderOrder === true,
IsPddCourierDoorToDoorCollect: row.IsPddCourierDoorToDoorCollect === true,
ReceiverIsChange: row.ReceiverIsChange === true,
DataFlag: row.DataFlag,
PrintState: row.PrintState,
IsOfflineOrder: row.IsOfflineOrder === true,
OrderTags: Array.isArray(row.OrderTags) ? row.OrderTags : [],
PayTime: row.PayTime || '',
MergeredType: row.MergeredType == null ? 0 : row.MergeredType,
// 平台页面会把订单行里这个加密串原样带回,缺了可能被判报文不合法
ShippingType: row.ShippingType || '',
LogisticStatus: row.LogisticStatus == null ? 0 : row.LogisticStatus,
ExtField1: row.ExtField1 || '',
ExtField2: row.ExtField2 || '',
SellerRemarkFlagTag: row.SellerRemarkFlagTag || '',
IsSelectAllNotPrintedItem: 1,
WaybillCode: row.LastWaybillCode || firstWaybill.WaybillCode || '',
ExpressCompanyCode: firstWaybill.ExpressCpCode || expressCode || '',
weight: 0,
WaybillCodeUniqueKey: firstWaybill.UniqueKey || '',
SubOrders: subOrders,
WaybillCodes: waybills,
Items: items,
OrderItems: orderItems,
OrderItemStrList: orderItems,
Receiver: {
ToProvince: row.ToProvince,
ToCity: row.ToCity,
ToCounty: row.ToCounty,
ToMaskAddress: `${row.ToTown || ''}${row.ToAddress || ''}`,
ToName: row.ToName,
ToMobile: row.ToPhone,
ToAddress: row.ToFullAddress,
toFullName: row.ToName,
toArea: row.ToFullAddress,
},
Sender: { SenderCompany: '', CompanyName: '' },
ReceiverIsEmpty: 0,
PrintInfo: '',
NoPrintFlag: 'false',
};
}
/**
* 收集发货回传响应里的逐单错误(各平台结构不统一,这里按常见字段兜底)
* @param {Object} json 平台响应
@ -2783,7 +2886,7 @@ class DgjService extends PrintPlatformService {
}
/**
* 通知平台发货(旧系统 `Dianguanjia.php#OnlineSendBatch` 同口径)
* 通知平台发货(对齐平台「待打订单 → 发货」的 `POST /NewOrder/OnlineSend`,2026-11-07 抓包)
*
* WMS 回传 `deliveryorder.confirm`、OMS 流转到「配送」后,需要把发货结果同步回店管家,
* 平台才会把订单状态推进为「已发货」。走**订单域名**(`fxali` / `fxdd` / `fxpdd` / `fxjd`)。
@ -2791,77 +2894,32 @@ class DgjService extends PrintPlatformService {
* @param {Object} options 参数
* @param {string} options.traceId 登录上下文 traceId
* @param {string} options.dbname 分区库名
* @param {Array} options.rows 平台订单行(含 SubOrders / LastWaybillCode / WaybillCodes)
* @param {Array} options.rows 平台订单行(含 SubOrders / LastWaybillCode / WaybillCodes / ShippingType)
* @param {string} [options.templateId] 面单模板ID(平台页面会带上,缺了会被判「请先勾选要发货的订单」)
* @param {string|number} [options.expressCompanyId] 快递公司ID(同模板记录)
* @param {string} [options.expressCode] 快递编码兜底
* @return {Promise<Object>} 平台响应
*/
async sendOrders(host, { traceId, dbname, rows }) {
const orders = (rows || []).map((row, index) => {
const items = [];
const orderItems = [];
for (const sub of Array.isArray(row.SubOrders) ? row.SubOrders : []) {
items.push({
OrderItemId: sub.OrderItemId,
OrderItemCode: sub.OrderItemCode,
Quantity: '1',
ShortTitle: sub.ShortTitle,
});
orderItems.push(sub.OrderItemId);
}
const firstWaybill = (Array.isArray(row.WaybillCodes) ? row.WaybillCodes : []).find(code => code && code.WaybillCode) || {};
return {
Id: row.Id,
Index: index + 1,
WaybillCodeId: '',
LogicOrderId: row.LogicOrderId,
OrderCode: row.OrderCode,
PlatformOrderId: row.LogicOrderId,
PathFlowCode: row.PathFlowCode,
CustomerOrderId: row.PlatformOrderId,
PlatformType: row.PlatformType,
PlatformStatus: 'waitsellersend',
RefunStatus: '',
FxUserId: row.FxUserId,
BuyerRemark: row.BuyerRemark,
SellerRemark: row.SellerRemark,
UpFxUserId: row.FxUserId,
IsPddCrossBorderOrder: row.IsPddCrossBorderOrder === true,
IsPddCourierDoorToDoorCollect: row.IsPddCourierDoorToDoorCollect === true,
ReceiverIsChange: row.ReceiverIsChange === true,
PrintState: row.PrintState,
SubOrders: row.SubOrders,
IsOfflineOrder: row.IsOfflineOrder === true,
PublishTime: row.PublishTime,
IsSelectAllNotPrintedItem: 1,
WaybillCode: row.LastWaybillCode || firstWaybill.WaybillCode || '',
ExpressCompanyCode: firstWaybill.ExpressCpCode || '',
weight: 0,
WaybillCodeUniqueKey: firstWaybill.UniqueKey || '',
OrderItems: orderItems,
NoPrintFlag: 'false',
Items: items,
SendType: '0',
DataFlag: row.DataFlag,
Receiver: {
toFullName: row.ToName,
toMobile: row.ToPhone,
toArea: row.ToFullAddress,
toProvince: row.ToProvince,
toCity: row.ToCity,
toCounty: row.ToCounty,
toMaskAddress: row.ToAddress,
},
Sender: { CompanyName: '' },
Buyer: { BuyerWangWang: '' },
};
});
async sendOrders(host, { traceId, dbname, rows, templateId = '', expressCompanyId = '', expressCode = '' }) {
const orders = (rows || []).map((row, index) => buildSendOrder(row, index, expressCode));
const now = new Date();
const pad = value => String(value).padStart(2, '0');
const batchNo = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}${pad(now.getHours())}${pad(now.getMinutes())}` +
String(Date.now()).slice(-9) + Math.floor(Math.random() * 100000);
// 顶层参数按平台「待打订单 → 发货」实际请求对齐(2026-11-07 抓包):
// 少了 TemplateId / ExpressCompanyId 时平台会回「请先勾选要发货的订单」
const form = buildPhpForm({
Orders: orders,
IsCustomerOrder: 'false',
FxPageType: '2',
TemplateId: String(templateId || (rows && rows[0] && rows[0].LastExpressPrintTemplateId) || ''),
ExpressCompanyId: String(expressCompanyId || ''),
ExcludeOrders: { productItemCount: 0, productCount: 0 },
NoLogisticsInfoModel: '',
IsSendPreCheck: 'true',
IsContinueForStock: 'false',
NoLogisticsInfoModel: '',
RequestBatchNumber: `1/1/${batchNo}`,
IsCustomerOrder: 'false',
FxPageType: '2',
});
const res = await this.postPlatformForm(host, ONLINE_SEND_PATH, form, traceId, dbname);
@ -2892,6 +2950,22 @@ class DgjService extends PrintPlatformService {
res
);
}
// 平台是「整包 Success + 逐单结果」:逐单失败要单独判,否则会把没发成功的单标成已同步。
// 例外:单子已经是已发货状态(平台早于我们手工/别处发货)视为幂等成功。
const failed = extractSendOrderFailures(res.json);
const realFailures = failed.filter(item => !/不是待发货状态|已发货|已取消|已关闭/.test(item.message));
if (realFailures.length) {
throw buildPlatformError(
`店管家发货同步失败:${realFailures.map(item => `${item.logicOrderId}: ${item.message}`).join(';')}`,
res
);
}
if (failed.length && this.logger && typeof this.logger.info === 'function') {
for (const item of failed) {
this.logger.info('[dgj.sendOrders] 平台侧该单无需再发货:%s %s', item.logicOrderId, item.message);
}
}
return res.json;
}

View File

@ -116,7 +116,7 @@ class ExternalSendSyncService extends Service {
return { ok: true, skipped: true, message: '非外部打单订单,无需同步' };
}
const { service, platformType, dbname, platformCode } = target;
const { service, platformType, dbname, platformCode, template } = target;
const host = service.constructor.resolveOrderHost(platformType);
const row = await service.findPlatformOrderRow(host, {
traceId: await this.resolveTraceId(service),
@ -133,6 +133,9 @@ class ExternalSendSyncService extends Service {
traceId: await this.resolveTraceId(service),
dbname,
rows: [ row ],
templateId: template ? template.template_id : '',
expressCompanyId: template ? template.express_company_id : '',
expressCode: template ? template.express_company_code : '',
});
await order.update({
@ -163,6 +166,9 @@ class ExternalSendSyncService extends Service {
traceId: await this.resolveTraceId(target.service),
dbname: target.dbname,
rows: [ row ],
templateId: target.template ? target.template.template_id : '',
expressCompanyId: target.template ? target.template.express_company_id : '',
expressCode: target.template ? target.template.express_company_code : '',
});
await order.update({
external_send_status: SEND_STATUS.SYNCED,
@ -227,7 +233,7 @@ class ExternalSendSyncService extends Service {
const resolvePlatformType = service.constructor && service.constructor.resolvePlatformType;
const template = await ctx.model.ExternalPrintExpressInterface.findOne({
where: { principal_id: order.principal_id, account_id: account.id, platform_code: platformCode, status: 1 },
attributes: [ 'id', 'platform_type', 'dbname' ],
attributes: [ 'id', 'platform_type', 'dbname', 'template_id', 'express_company_id', 'express_company_code' ],
order: [[ 'id', 'ASC' ]],
});
// PlatformType(决定回传发货用哪个域名)优先按「订单原始平台」:1688 分销单在 OMS 里被换算成
@ -242,7 +248,7 @@ class ExternalSendSyncService extends Service {
platformType = template ? template.platform_type : (typeof resolvePlatformType === 'function' ? resolvePlatformType(platformCode) : '');
}
if (!platformType) return null;
return { service, account, platformType, dbname: template ? template.dbname : '', platformCode };
return { service, account, platformType, dbname: template ? template.dbname : '', platformCode, template };
}
/**

View File

@ -35,32 +35,54 @@ OMS 实现:`resolveOrderHost(platformType)`(`dgj.js` 顶部 `ORDER_HOSTS`,
---
## 2.1 发货接口:`POST /NewOrder/OnlineSendBatch`(同步发货)
## 2.1 发货接口:`POST /NewOrder/OnlineSend`(同步发货)
OMS 的订单被 WMS 回传 `deliveryorder.confirm` 流转到「配送」后,需要把发货结果**同步回店管家**,平台才会把订单状态推进为「已发货」。
接口与取号同域(走订单域名,见上表),**不消耗面单**。
请求(旧系统 `Dianguanjia.php#OnlineSendBatch` 同口径,`buildPhpForm` 展开):
⚠️ **2026-11-07 抓包更正**:真实接口是 `/NewOrder/OnlineSend`(不是 `OnlineSendBatch`),
且平台页面把**整行订单模型**都带上,顶层还必须带 `TemplateId` / `ExpressCompanyId`;
只发 `Orders`(旧实现)平台会回「**请先勾选要发货的订单**」。
实测请求(浏览器「待打订单 → 发货」):
```
Orders[0][Id] / [Index] / [LogicOrderId] / [OrderCode] / [PlatformOrderId] / [PathFlowCode]
Orders[0][CustomerOrderId](= 平台单号)/ [PlatformType] / [PlatformStatus]=waitsellersend
Orders[0][WaybillCode](= LastWaybillCode)/ [ExpressCompanyCode](= WaybillCodes[0].ExpressCpCode)
Orders[0][WaybillCodeUniqueKey](= WaybillCodes[0].UniqueKey)
Orders[0][SubOrders] / [Items][n][OrderItemId/OrderItemCode/Quantity] / [OrderItems][n]
Orders[0][Receiver][toFullName/toMobile/toArea/toProvince/toCity/toCounty/toMaskAddress]
Orders[0][Sender][CompanyName] / [Buyer][BuyerWangWang]
IsCustomerOrder=false FxPageType=2 IsSendPreCheck=true IsContinueForStock=false NoLogisticsInfoModel=
TemplateId=10824270 ExpressCompanyId=8
ExcludeOrders[productItemCount]=1 ExcludeOrders[productCount]=1
NoLogisticsInfoModel= IsSendPreCheck=true IsContinueForStock=false
RequestBatchNumber=1/1/20261107080668392473417 IsCustomerOrder=false FxPageType=2
Orders[0][Id] / [Index] / [LogicOrderId] / [PlatformOrderId](= 系统编号)/ [PathFlowCode]
Orders[0][CustomerOrderId](= 平台单号)/ [PlatformType]=Alibaba / [PlatformTypeName]=1688
Orders[0][ShopId] / [ShopName] / [PlatformStatus]=waitsellersend / [RefunStatus]=
Orders[0][FxUserId] / [UpFxUserId](分销场景 ≠ FxUserId,必须透传平台值)
Orders[0][ExpressPrintTime] / [PayTime] / [MergeredType] / [LogisticStatus] / [DataFlag] / [PrintState]
Orders[0][ShippingType](平台给的加密串,原样带回)/ [ExtField1] / [ExtField2] / [SellerRemarkFlagTag]
Orders[0][OrderTags][n][...](分销渠道等标签,整块透传)
Orders[0][WaybillCode] / [ExpressCompanyCode] / [WaybillCodeUniqueKey] / [weight]=0
Orders[0][WaybillCodes][0][...](含 WaybillCodeId / Pid / ExpressCpCode / IsSended)
Orders[0][SubOrders][0][...](整块透传)
Orders[0][Items][n][OrderItemId/OrderItemCode/Quantity/SkuCode/ProductCode/OrderItemIdStr]
Orders[0][OrderItems][] / [OrderItemStrList][]
Orders[0][Receiver][ToProvince/ToCity/ToCounty/ToMaskAddress/ToName/ToMobile/ToAddress/toFullName/toArea]
Orders[0][Sender][SenderCompany/CompanyName] / [ReceiverIsEmpty]=0 / [PrintInfo]= / [NoPrintFlag]=false
```
响应是「整包 `Success` + `Data.Orders[]` 逐单结果」,必须看逐单 `IsSuccess`:
```json
{"Success":true,"ErrorCode":"200","Data":{"Orders":[{"LogicOrderId":10000280844952,"IsSuccess":false,
"ErrorMessage":"订单不是待发货状态,请检查"}]}}
```
OMS 口径:逐单 `IsSuccess=false` 时,除「不是待发货状态 / 已发货 / 已取消 / 已关闭」(幂等,视为已同步)外都算失败。
OMS 实现:
| 位置 | 作用 |
|---|---|
| `dgj.sendOrders(host, { traceId, dbname, rows })` | 组装并提交上面这份表单;`Success!==true` 抛「店管家发货同步失败:…」 || `service/externalSendSync.js` | 配送后同步的状态机(待同步 → 已同步 / 待重试 → 3 次转异常) |
| `schedule/externalSendSyncWorker.js` | 每 2 分钟扫描「待同步 / 待重试」的配送单并发货同步 |
| `POST /api/external-send/retry` | 人工批量重试(重置次数后立刻同步一批) |
| `GET /api/external-send/counts` | 待同步 / 待重试 / 异常 / 已同步数量 |
| `dgj.sendOrders(host, { traceId, dbname, rows, templateId, expressCompanyId, expressCode })` | 按上面口径组装并提交;整包或逐单失败抛「店管家发货同步失败:…」 |
| `service/externalSendSync.js` | 配送后同步的状态机(待同步 → 已同步 / 待重试 → 3 次转异常),把模板/快递公司ID 一起传下去 |
状态字段(配送表 `order_status_delivery`,所有状态表 + 历史表同构):
@ -430,7 +452,7 @@ $documentID = $PrintDataList["task"]["documents"][0]["documentID"]; // = 运单
| 动作 | 接口 | 说明 |
|---|---|---|
| 发货 | `POST /NewOrder/OnlineSendBatch` | 取号后通知平台发货;OMS 的发货由 WMS 回传 `deliveryorder.confirm` 处理,不在此调用 |
| 发货 | `POST /NewOrder/OnlineSend` | 取号后通知平台发货;OMS 的发货由 WMS 回传 `deliveryorder.confirm` 处理,不在此调用 |
| 打印历史 | `POST /PrintHistory/LoadList` / `LoadPrintData` | 用于回捞运单号与打印数据;OMS 直接从 ExpressPrint 响应解析,**打印记录ID(`Data.PrintHistoryIds[].Id`)已解析并落 `waybill_fetch_records.print_history_ids`**(重打/作废要用),列表接口暂不接入 |
---