fix(dgj): 取号失败透出平台 ErrCode/ErrMsg,取号报文构造可对照

取号失败时用户只看到「店管家取号失败:平台返回取号失败」——平台把逐单错误放在
`Data.WaybillCode[n].ErrCode / ErrMsg`(实测 15002「非抖店订单,无法使用抖音电子面单
取号打印…」),我们只读了 `ErrorMsg` / `Message`,真实原因被吞掉。

- 新增 describeWaybillError:按 ErrMsg → ErrorMsg → Message → OrderInfo/Order 兜底,
  并附上 ErrCode;「未返回运单号」分支也带上平台原因
- 把 ExpressPrint 的 Orders[i] 报文构造抽成纯函数 buildExpressPrintOrder /
  buildExpressPrintOrders(expressPrint 内部改为调用),并挂到 DgjService 静态方法上:
  取号记录只有平台回显、没有请求体,出问题时要能把「我们实际发的报文」打出来对照
  (对比过成功/失败两单:结构完全一致,只有业务值不同)
- 单测:dgjWaybillError(4 例)+ dgjExpressPrintPayload(5 例:字段映射、明细口径、
  收件人、多包裹 Index、当前运单号)
- 文档补 §4.4.1:1688 分销单用抖音面单的前置条件(extField7 里要有 outPlatformOrderNo,
  明文渠道单没有就报 15002,只能在店管家侧重新授权/建线下单)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-08 19:05:30 +08:00
parent 8ae6733e97
commit e1f49451c0
4 changed files with 315 additions and 67 deletions

View File

@ -270,9 +270,129 @@ function buildSendOrder(row, index, expressCode = '') {
return [ ...new Set(out) ].slice(0, 3);
}
/**
* 当前运单号(平台订单行上已取的号):新单号打印时带给平台,平台据此分配下一个号
* @param {Object} row 平台订单行
* @return {string} 运单号,无则空串
*/
function deriveCurrentWaybillCode(row) {
const data = row || {};
const list = Array.isArray(data.WaybillCodes) ? data.WaybillCodes.filter(item => item && item.WaybillCode) : [];
return String(data.LastWaybillCode || (list[list.length - 1] || {}).WaybillCode || '').trim();
}
/**
* 构造取号(`ExpressPrint`)的 `Orders[i]` 报文
*
* 单独抽出来是为了能把「我们实际发给平台的订单报文」打出来做对照(取号失败排查时,
* `waybill_fetch_records.raw_response` 只有平台回显,没有请求体)。
* @param {Object} row 平台订单行(findPlatformOrderRow 的返回 / 拉单落库的 external_data)
* @param {Object} options 参数
* @param {string} options.templateId 面单模板ID
* @param {string} [options.expressCode] 快递编码
* @param {number} [options.index] 报文序号(0 基)
* @param {string} [options.currentWaybillCode] 当前运单号,缺省按订单行推导
* @return {Object} Orders[i] 报文
*/
function buildExpressPrintOrder(row, { templateId, expressCode = '', index = 0, currentWaybillCode } = {}) {
const waybillCode = currentWaybillCode === undefined ? deriveCurrentWaybillCode(row) : currentWaybillCode;
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,
SkuCode: sub.SkuCode,
ProductCode: sub.ProductCode,
});
orderItems.push(sub.OrderItemId);
}
return {
WaybillCodeId: '',
Index: index + 1,
Id: row.Id,
IdStr: row.Id,
PlatformOrderId: row.LogicOrderId,
LogicOrderId: row.LogicOrderId,
PathFlowCode: row.PathFlowCode,
CustomerOrderId: row.PlatformOrderId,
ShopId: row.ShopId,
// 与平台前端一致:PrintInfo 传 `[1];\n`(第 1 份)
PrintInfo: '[1];\n',
OrderItems: orderItems,
Items: items,
OrderItemStrList: orderItems,
// 新单号打印:把当前号(含 Pid/WaybillCodeId)带给平台,平台据此分配下一个号
WaybillCode: waybillCode,
WaybillCodes: buildWaybillCodesBlock(row, templateId, expressCode),
NewSellerRemark: '',
PrintRemark: '',
NewPrintRemark: '',
SellerRemark: row.SellerRemark,
BuyerRemark: row.BuyerRemark,
FxUserId: row.FxUserId,
IsSelectAllNotPrintedItem: '1',
SendType: '0',
DataFlag: row.IsCold,
Receiver: {
toFullName: row.ToName,
toMobile: row.ToPhone,
toArea: row.ToFullAddress,
toProvince: row.ToProvince,
toCity: row.ToCity,
toCounty: row.ToCounty,
toMaskAddress: `${row.ToTown || ''}${row.ToAddress || ''}`,
},
Sender: { CompanyName: '' },
Buyer: { BuyerWangWang: row.ToName },
};
}
/**
* 构造取号报文的 `Orders` 数组(多包裹时同一订单行重复 N 份)
* @param {Array<Object>} rows 平台订单行
* @param {Object} options 参数
* @param {string} options.templateId 面单模板ID
* @param {string} [options.expressCode] 快递编码
* @param {number} [options.repeat] 复制份数(包裹张数,默认 1)
* @return {Array<Object>} Orders 数组
*/
function buildExpressPrintOrders(rows, { templateId, expressCode = '', repeat = 1 } = {}) {
const count = Number.isFinite(Number(repeat)) && Number(repeat) > 1 ? Math.floor(Number(repeat)) : 1;
const sourceRows = [];
for (let i = 0; i < count; i += 1) sourceRows.push(...(rows || []));
const first = (rows || [])[0] || {};
const currentWaybillCode = deriveCurrentWaybillCode(first);
return sourceRows.map((row, index) => buildExpressPrintOrder(row, {
templateId, expressCode, index, currentWaybillCode,
}));
}
/**
* 取号失败的可读原因
*
* 平台的逐单错误放在 `ErrMsg` / `ErrCode`(实测 `15002`「非抖店订单,无法使用抖音电子面单
* 取号打印,请用抖店平台订单号重新创建线下单再重试」),早先只读 `ErrorMsg` / `Message`,
* 结果用户只看到「平台返回取号失败」,真实原因查不到。
* @param {Object} item 平台返回的逐单结果(Data.WaybillCode[n])
* @return {string} 可读原因,含 ErrCode
*/
function describeWaybillError(item) {
const data = item || {};
const orderInfo = data.OrderInfo || {};
const order = orderInfo.Order || {};
const message = data.ErrorMsg || data.ErrMsg || data.Message
|| orderInfo.ErrorMsg || orderInfo.ErrMsg
|| order.ErrorMsg || order.ErrMsg || '';
const code = data.ErrCode || data.ErrorCode || orderInfo.ErrCode || order.ErrCode || '';
if (!message) return code ? `平台返回取号失败(ErrCode=${code})` : '平台返回取号失败';
return code ? `${message}(ErrCode=${code})` : message;
}
/** 订单列表单页条数(平台允许 500) */
const ORDER_PAGE_SIZE = 500;
/** 订单查询的最大翻页数,防御平台分页异常 */
const ORDER_MAX_PAGES = 200;
@ -2811,13 +2931,16 @@ class DgjService extends PrintPlatformService {
const errorItem = items.find(item => item && (item.IsError === true || Number(item.IsError) === 1));
if (errorItem) {
const reason = errorItem.ErrorMsg || errorItem.Message || (errorItem.OrderInfo && errorItem.OrderInfo.ErrorMsg) || '平台返回取号失败';
throw buildPlatformError(`店管家取号失败:${reason}`, { status: 200, json: printed, text: '' });
throw buildPlatformError(`店管家取号失败:${describeWaybillError(errorItem)}`, { status: 200, json: printed, text: '' });
}
const waybillCodes = extractWaybillCodes(items);
if (!waybillCodes.length) {
throw buildPlatformError('店管家未返回运单号:请检查模板与订单状态,或查看原始响应', { status: 200, json: printed, text: '' });
const firstMessage = items.map(item => describeWaybillError(item)).find(text => text && text !== '平台返回取号失败');
throw buildPlatformError(
`店管家未返回运单号${firstMessage ? `:${firstMessage}` : ':请检查模板与订单状态,或查看原始响应'}`,
{ status: 200, json: printed, text: '' }
);
}
const document = firstPrintDocument(printed, waybillCodes[0]);
@ -3039,11 +3162,6 @@ class DgjService extends PrintPlatformService {
async expressPrint(host, { traceId, dbname, templateId, rows, checkData, packageCount = 1, expressCode = '', reuseWaybill = false }) {
const data = checkData || {};
const repeat = Number.isFinite(Number(packageCount)) && Number(packageCount) > 1 ? Math.floor(Number(packageCount)) : 1;
const currentWaybillCode = (() => {
const row = (rows || [])[0] || {};
const list = Array.isArray(row.WaybillCodes) ? row.WaybillCodes.filter(item => item && item.WaybillCode) : [];
return String(row.LastWaybillCode || (list[list.length - 1] || {}).WaybillCode || '').trim();
})();
const branches = Array.isArray(data.Branches) ? data.Branches.map(branch => {
const copy = { ...branch };
for (const key of Object.keys(copy)) {
@ -3055,63 +3173,7 @@ class DgjService extends PrintPlatformService {
}) : '';
// 多包裹:同一订单行重复 N 份,Index 依次 1..N(平台按包裹各分配一个运单号)
const sourceRows = [];
for (let i = 0; i < repeat; i += 1) sourceRows.push(...(rows || []));
const orders = sourceRows.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,
SkuCode: sub.SkuCode,
ProductCode: sub.ProductCode,
});
orderItems.push(sub.OrderItemId);
}
return {
WaybillCodeId: '',
Index: index + 1,
Id: row.Id,
IdStr: row.Id,
PlatformOrderId: row.LogicOrderId,
LogicOrderId: row.LogicOrderId,
PathFlowCode: row.PathFlowCode,
CustomerOrderId: row.PlatformOrderId,
ShopId: row.ShopId,
// 与平台前端一致:PrintInfo 传 `[1];\n`(第 1 份)
PrintInfo: '[1];\n',
OrderItems: orderItems,
Items: items,
OrderItemStrList: orderItems,
// 新单号打印:把当前号(含 Pid/WaybillCodeId)带给平台,平台据此分配下一个号
WaybillCode: currentWaybillCode,
WaybillCodes: buildWaybillCodesBlock(row, templateId, expressCode),
NewSellerRemark: '',
PrintRemark: '',
NewPrintRemark: '',
SellerRemark: row.SellerRemark,
BuyerRemark: row.BuyerRemark,
FxUserId: row.FxUserId,
IsSelectAllNotPrintedItem: '1',
SendType: '0',
DataFlag: row.IsCold,
Receiver: {
toFullName: row.ToName,
toMobile: row.ToPhone,
toArea: row.ToFullAddress,
toProvince: row.ToProvince,
toCity: row.ToCity,
toCounty: row.ToCounty,
toMaskAddress: `${row.ToTown || ''}${row.ToAddress || ''}`,
},
Sender: { CompanyName: '' },
Buyer: { BuyerWangWang: row.ToName },
};
});
const orders = buildExpressPrintOrders(rows, { templateId, expressCode, repeat });
const form = buildPhpForm({
TemplateId: String(templateId),
@ -3580,6 +3642,35 @@ class DgjService extends PrintPlatformService {
static buildForm(data) {
return buildPhpForm(data);
}
/**
* 取号失败原因解析(逐单结果 → 可读文案)
* @param {Object} item 平台返回的逐单结果
* @return {string} 可读原因
*/
static describeWaybillError(item) {
return describeWaybillError(item);
}
/**
* 打印「我们实际发给平台的取号订单报文」(排错用:取号记录里只有平台回显)
* @param {Object} row 平台订单行
* @param {Object} options 参数(templateId / expressCode / index / currentWaybillCode)
* @return {Object} Orders[i] 报文
*/
static buildExpressPrintOrder(row, options) {
return buildExpressPrintOrder(row, options);
}
/**
* 构造取号报文的 Orders 数组(多包裹时同一订单行重复 N 份)
* @param {Array<Object>} rows 平台订单行
* @param {Object} options 参数(templateId / expressCode / repeat)
* @return {Array<Object>} Orders 数组
*/
static buildExpressPrintOrders(rows, options) {
return buildExpressPrintOrders(rows, options);
}
}
module.exports = DgjService;

View File

@ -0,0 +1,89 @@
'use strict';
const { assert } = require('egg-mock/bootstrap');
const DgjService = require('../../../app/lib/printPlatform/dgj');
/**
* 取号请求报文(`ExpressPrint` 的 `Orders[i]`)构造。
*
* 抽成纯函数是为了排错时能把「实际发给平台的报文」打出来 —— `waybill_fetch_records`
* 只存平台回显,没有请求体。这里锁住字段映射,避免以后调字段时又说不清「差异在哪」。
*/
describe('dgj.buildExpressPrintOrder 取号请求报文', () => {
const row = {
Id: '10000289308857',
LogicOrderId: '10000289308857',
PlatformOrderId: '3316563626158027487',
PathFlowCode: '10000001412039',
ShopId: 7398588,
FxUserId: 1227061,
IsCold: 0,
ToName: '张*',
ToPhone: '157****6483-2116',
ToProvince: '河南省',
ToCity: '漯河市',
ToCounty: '舞阳县',
ToTown: '舞泉镇',
ToAddress: '北京路哆哆潮品服装店',
ToFullAddress: '河南省漯河市舞阳县舞泉镇 北京路哆哆潮品服装店',
SubOrders: [
{ OrderItemId: '10000314681299', OrderItemCode: '10000314681299', SkuCode: '006-1', ProductCode: '10000053027651' },
],
};
it('订单级字段按平台前端口径映射', () => {
const order = DgjService.buildExpressPrintOrder(row, { templateId: '12360764', expressCode: 'YUNDA' });
assert.strictEqual(order.Index, 1);
assert.strictEqual(order.Id, '10000289308857');
// 平台单号(抖店单号)放 CustomerOrderId,店管家系统编号放 LogicOrderId/PlatformOrderId
assert.strictEqual(order.CustomerOrderId, '3316563626158027487');
assert.strictEqual(order.LogicOrderId, '10000289308857');
assert.strictEqual(order.PlatformOrderId, '10000289308857');
assert.strictEqual(order.ShopId, 7398588);
assert.strictEqual(order.FxUserId, 1227061);
assert.strictEqual(order.PrintInfo, '[1];\n');
assert.strictEqual(order.IsSelectAllNotPrintedItem, '1');
});
it('明细按 SubOrders 逐条下发,OrderItems 与 Items 同源', () => {
const order = DgjService.buildExpressPrintOrder(row, { templateId: '12360764' });
assert.deepStrictEqual(order.OrderItems, [ '10000314681299' ]);
assert.deepStrictEqual(order.OrderItemStrList, [ '10000314681299' ]);
assert.deepStrictEqual(order.Items, [{
OrderItemId: '10000314681299',
OrderItemCode: '10000314681299',
Quantity: '1',
ShortTitle: undefined,
SkuCode: '006-1',
ProductCode: '10000053027651',
}]);
});
it('收件人按平台字段映射,脱敏值原样透传', () => {
const order = DgjService.buildExpressPrintOrder(row, { templateId: '12360764' });
assert.deepStrictEqual(order.Receiver, {
toFullName: '张*',
toMobile: '157****6483-2116',
toArea: '河南省漯河市舞阳县舞泉镇 北京路哆哆潮品服装店',
toProvince: '河南省',
toCity: '漯河市',
toCounty: '舞阳县',
toMaskAddress: '舞泉镇北京路哆哆潮品服装店',
});
});
it('多包裹时同一订单行重复下发,Index 递增', () => {
const orders = DgjService.buildExpressPrintOrders([ row ], { templateId: '12360764', repeat: 2 });
assert.strictEqual(orders.length, 2);
assert.deepStrictEqual(orders.map(item => item.Index), [ 1, 2 ]);
assert.deepStrictEqual(orders.map(item => item.LogicOrderId), [ '10000289308857', '10000289308857' ]);
});
it('平台已有运单号时作为当前号下发(新单号打印据此换号)', () => {
const order = DgjService.buildExpressPrintOrder(
{ ...row, LastWaybillCode: '435434980095250', WaybillCodes: [{ WaybillCode: '435434980095251' }] },
{ templateId: '12360764' }
);
assert.strictEqual(order.WaybillCode, '435434980095250');
});
});

View File

@ -0,0 +1,43 @@
'use strict';
const { assert } = require('egg-mock/bootstrap');
const DgjService = require('../../../app/lib/printPlatform/dgj');
/**
* 取号失败的逐单错误解析。
*
* 实测(生产 18:49):1688 抖音分销单用抖音模板取号,平台返回
* `{"IsError":true,"ErrCode":"15002","ErrMsg":"非抖店订单,无法使用抖音电子面单取号打印…"}`,
* 旧代码只读 `ErrorMsg` / `Message`,用户侧只看到「平台返回取号失败」,查不到真实原因。
*/
describe('dgj.describeWaybillError 取号失败原因', () => {
it('优先取 ErrMsg 并带上 ErrCode(真实响应结构)', () => {
const message = DgjService.describeWaybillError({
IsError: true,
ErrCode: '15002',
ErrMsg: '非抖店订单,无法使用抖音电子面单取号打印,请用抖店平台订单号重新创建线下单再重试。',
});
assert.strictEqual(
message,
'非抖店订单,无法使用抖音电子面单取号打印,请用抖店平台订单号重新创建线下单再重试。(ErrCode=15002)'
);
});
it('兼容 ErrorMsg / Message 等历史字段', () => {
assert.strictEqual(DgjService.describeWaybillError({ ErrorMsg: '模板未配置' }), '模板未配置');
assert.strictEqual(DgjService.describeWaybillError({ Message: '余额不足' }), '余额不足');
assert.strictEqual(
DgjService.describeWaybillError({ ErrMsg: '地址超区', ErrorMsg: '' }),
'地址超区'
);
});
it('只有 ErrCode 没有文案时也把它透出来', () => {
assert.strictEqual(DgjService.describeWaybillError({ ErrCode: '15002' }), '平台返回取号失败(ErrCode=15002)');
});
it('什么都没有时回落到默认文案', () => {
assert.strictEqual(DgjService.describeWaybillError({}), '平台返回取号失败');
assert.strictEqual(DgjService.describeWaybillError(null), '平台返回取号失败');
});
});

View File

@ -632,8 +632,33 @@ WaybillCodeCreateDate='2026-11-04 08:20:37'
}
```
### 4.5 取号响应
### 4.4.1 1688 分销单用抖音面单的前置条件(`ErrCode=15002`)
1688 分销单换算成抖音小店(DYXD)后,平台侧还要求**订单在店管家带抖店原单信息**,
否则 `ExpressPrint` 直接失败(实测 2026-11-08,订单 `dgj-10000289308857`):
```
"ErrCode":"15002",
"ErrMsg":"非抖店订单,无法使用抖音电子面单取号打印,请用抖店平台订单号重新创建线下单再重试。"
```
判据在订单报文的 `Order.ExtraJson`(店管家订单行 `ExtField7`)里:
| 场景 | `ExtraJson.extField7` | 取号结果 |
|---|---|---|
| 下游渠道 `OutChannel=douyin`(API 授权过) | `{"outPlatformOrderNo":"6931267452381592757","outPlatformCode":"douyin","outPlatformAppkey":"…","outShopId":"152278571","encryptReceiver…":…}` | 成功(生产 DYXD 成功 60+ 单,全部带 `outPlatformOrderNo`) |
| 下游渠道 `OutChannel=douyin_plaintext`(明文渠道) | `""`(空串,没有抖店原单号/加密收件人) | 失败 `15002` |
即:**同一店铺、同一模板**下,差别只在这个字段(`RequestBatchNumber`、`AuthUrl`、`FxPathUserNodes`
在成功与失败响应里都一样,可以排除)。这类单只能在店管家侧解决:
重新授权「抖音分销」(`https://auth.dgjapp.com/auth/douyinfx`)后同步该单,
或按平台提示用抖店平台订单号在店管家建线下单再取号 —— OMS 侧重试即可。
取号失败原因的透出:平台的逐单错误在 `Data.WaybillCode[n].ErrCode / ErrMsg`,
`DgjService.describeWaybillError` 会拼成「ErrMsg(ErrCode=…)」写进 `waybill_fetch_records.error_message`,
不再只剩一句「平台返回取号失败」。
### 4.5 取号响应
旧系统只用到的两个字段:
```php