fix(print-data): 换打印参数前必须做模板校验,补上 RequestBatchNumber 批次号

WMS「韵达」面单换打印数据时平台抛空引用(未将对象引用设置到对象的实例)。实测对照
(同一账号、同一 fxdd 域名、真实面单)定位到根因:RequestBatchNumber 由
DateNow + DayPrintBatchNumber 拼成,取号流程会先调 CheckTemplateAvaliable 拿这两个值,
而换打印参数时传的是 checkData: {},批次号退化成 1/1/,平台解析时抛空引用
(偶尔表现成「成功」但 documents 为空、WaybillCode 为 null)。

- dgj.fetchPrintParams:先 checkTemplateAvailable 再把 check.Data 作为 checkData 提交;
  平台「成功」但没有任何 params 时按失败抛出,交给上层回退
- 去掉上一版尝试的 Orders[0][CaiNiaoAuthInfoId] 注入(实测加不加结果一样,不是根因)
- 保留 LoadPrintData 兜底(PrintHistory/LoadPrintData,按 printHistoryId 只读、不消耗面单):
  订单已离开待发货、或平台仍未返回打印数据时用它拿到当时打印的 params(可能过期,标 params_expired)
- 单测 dgjFetchPrintParams.test.js 3 例(必须带批次号 / 空数据按失败 / 带平台原因)
- 文档更正:不是域名或菜鸟授权网点问题,是批次号,并附实测对照表

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-07 22:35:37 +08:00
parent 37de11c309
commit 956793ba66
4 changed files with 102 additions and 27 deletions

View File

@ -2912,9 +2912,6 @@ class DgjService extends PrintPlatformService {
SellerRemark: row.SellerRemark,
BuyerRemark: row.BuyerRemark,
FxUserId: row.FxUserId,
// 菜鸟系面单(韵达/申通/中通…):平台按模板的授权网点取打印数据,
// 报文里缺这个字段时平台会抛空引用(「未将对象引用设置到对象的实例」)
CaiNiaoAuthInfoId: row.CaiNiaoAuthInfoId == null ? '' : row.CaiNiaoAuthInfoId,
IsSelectAllNotPrintedItem: '1',
SendType: '0',
DataFlag: row.IsCold,
@ -2981,20 +2978,19 @@ class DgjService extends PrintPlatformService {
* @param {string} options.templateId 面单模板ID
* @param {Object} options.row 平台订单行(findPlatformOrderRow 的返回)
* @param {string} [options.expressCode] 快递编码
* @param {string|number} [options.caiNiaoAuthInfoId] 菜鸟授权网点ID(模板绑定;菜鸟系面单打印必须带上,缺了平台会报「未将对象引用设置到对象的实例」)
* @return {Promise<{waybill_codes: string[], documents: Array<{documentID: string, params: string, template_url: string}>, raw: Object}>} 打印数据
*/
async fetchPrintParams(host, { traceId = '', dbname = '', templateId, row, expressCode = '', caiNiaoAuthInfoId = null }) {
async fetchPrintParams(host, { traceId = '', dbname = '', templateId, row, expressCode = '' }) {
if (!row) throw new Error('拉取打印参数需要平台订单行');
const sendRow = caiNiaoAuthInfoId == null
? row
: { ...row, CaiNiaoAuthInfoId: row.CaiNiaoAuthInfoId == null ? caiNiaoAuthInfoId : row.CaiNiaoAuthInfoId };
// 必须带模板校验的返回一起提交:`RequestBatchNumber` 由 `DateNow + DayPrintBatchNumber` 拼成,
// 缺了就变成 `1/1/`,平台侧会抛空引用(「未将对象引用设置到对象的实例」)或回空打印数据(2026-11-07 实测)
const check = await this.checkTemplateAvailable(host, { traceId, dbname, templateId, rows: [ row ] });
const printed = await this.expressPrint(host, {
traceId,
dbname,
templateId,
rows: [ sendRow ],
checkData: {},
rows: [ row ],
checkData: check && check.Data,
expressCode,
reuseWaybill: true,
});
@ -3003,13 +2999,7 @@ class DgjService extends PrintPlatformService {
.find(item => item && (item.IsError === true || Number(item.IsError) === 1));
if (errorItem) {
const reason = errorItem.ErrMsg || errorItem.ErrorMsg || '平台返回失败';
// 平台内部空引用(未将对象引用设置到对象的实例):多为面单模板/菜鸟授权网点与订单不匹配
const emptyRef = /未将对象引用/.test(String(reason));
throw buildPlatformError(
`店管家拉取打印参数失败:${reason}` +
(emptyRef ? '(平台内部空引用:常见于菜鸟系面单缺少授权网点或模板与订单不匹配)' : ''),
{ status: 200, json: printed, text: '' }
);
throw buildPlatformError(`店管家拉取打印参数失败:${reason}`, { status: 200, json: printed, text: '' });
}
const documents = [];
@ -3024,6 +3014,11 @@ class DgjService extends PrintPlatformService {
template_url: String(content.templateURL || ''),
});
}
// 平台「成功」但没给打印数据(模板批次号不匹配/面单状态异常时会这样)也按失败处理,
// 让上层回退到按打印记录取
if (!documents.some(doc => doc.params)) {
throw buildPlatformError('店管家没有返回打印数据(params 为空)', { status: 200, json: printed, text: '' });
}
return {
waybill_codes: extractWaybillCodes(printed.Data && printed.Data.WaybillCode),

View File

@ -400,7 +400,6 @@ async function fetchGroup(ctx, { principalId, memo, group }) {
templateId,
row,
expressCode: item.record.express_code || '',
caiNiaoAuthInfoId: base.cai_niao_auth_info_id,
});
} catch (err) {
expressError = err;

View File

@ -0,0 +1,67 @@
'use strict';
const { assert } = require('egg-mock/bootstrap');
const DgjService = require('../../../app/lib/printPlatform/dgj');
/**
* 造一个只调本模块自身方法的服务实例(不打网络)
* @return {Object} dgj 服务实例
*/
function buildService() {
return new DgjService({ platform: { code: 'dgj', name: '店管家' } });
}
const ROW = { Id: 1, LogicOrderId: '875172836006880609', SubOrders: [], WaybillCodes: [{ WaybillCode: '321450799451452' }] };
describe('dgj.fetchPrintParams 拉取打印参数', () => {
it('提交时必须带上模板校验的批次号(否则 RequestBatchNumber 只剩 1/1/,平台空引用)', async () => {
const service = buildService();
let captured = null;
service.checkTemplateAvailable = async () => ({ Success: true, Data: { DateNow: '20261107223459', DayPrintBatchNumber: '0001' } });
service.expressPrint = async (host, options) => {
captured = options;
return {
Success: true,
Data: {
WaybillCode: [{ WaybillCode: '321450799451452', IsError: false }],
PrintDataList: { task: { documents: [{ documentID: '321450799451452', contents: [{ params: 'access_token=t', templateURL: 'u' }] }] } },
},
};
};
const out = await service.fetchPrintParams('fxdd.dgjapp.com', {
traceId: 'tr', dbname: '', templateId: '12360764', row: ROW, expressCode: 'YUNDA',
});
assert.strictEqual(captured.reuseWaybill, true, '换打印参数不能分配新面单');
assert.deepStrictEqual(captured.checkData, { DateNow: '20261107223459', DayPrintBatchNumber: '0001' });
assert.strictEqual(out.documents[0].params, 'access_token=t');
assert.deepStrictEqual(out.waybill_codes, [ '321450799451452' ]);
});
it('平台「成功」但没给打印数据时按失败抛出(交给上层回退)', async () => {
const service = buildService();
service.checkTemplateAvailable = async () => ({ Success: true, Data: { DateNow: '1', DayPrintBatchNumber: '2' } });
service.expressPrint = async () => ({
Success: true,
Data: { WaybillCode: [{ WaybillCode: null }], PrintDataList: { task: { documents: [] } } },
});
await assert.rejects(
() => service.fetchPrintParams('fxdd.dgjapp.com', { templateId: '1', row: ROW }),
/没有返回打印数据/
);
});
it('平台逐单报错时带上平台原因', async () => {
const service = buildService();
service.checkTemplateAvailable = async () => ({ Success: true, Data: {} });
service.expressPrint = async () => ({
Success: true,
Data: { WaybillCode: [{ WaybillCode: '1', IsError: true, ErrMsg: '未将对象引用设置到对象的实例。' }] },
});
await assert.rejects(
() => service.fetchPrintParams('fxdd.dgjapp.com', { templateId: '1', row: ROW }),
/店管家拉取打印参数失败:未将对象引用设置到对象的实例。/
);
});
});

View File

@ -401,15 +401,29 @@ WaybillCodeCreateDate='2026-11-04 08:20:37'
后续按「店铺标识 + 运单号」即可定位到该运单号对应的取号记录,再拉一份新的打印参数。
对外方法见 `deliveryorder.getprintdata`(`WMS-OMS-取号对接.md` §4.7.1)。
- **`deliveryorder.getprintdata` 的双路径(2026-11-07 线上故障)**:WMS「韵达」面单
(`template_id=12360764`、`CaiNiaoAuthInfoId=6838859`)换打印数据时,平台回
`拉取打印参数失败:未将对象引用设置到对象的实例。`——`ExpressPrint` 复用路径上的**平台内部空引用**,
多发生在菜鸟系面单(韵达/申通/中通…)模板与授权网点对不上时。现在:
1. 复用取号路径的报文补上 `Orders[0][CaiNiaoAuthInfoId]`(取自模板/取号记录),先按原逻辑拉;
2. 仍然失败就**回退 `POST /PrintHistory/LoadPrintData`**(按 `printHistoryId`,只读、不消耗面单),
解析 `Data[].PrintDataJson` 拿 `contents[].params` + `templateURL`,返回里标 `source: print_history`;
3. 两条都拿不到才报错(带原错误原因)。
注意回退拿到的 `params` 是**当时打印的签名**(可能已过 10 分钟),所以成功路径仍优先用 `ExpressPrint` 重新签发。
- **`deliveryorder.getprintdata` 的空引用(2026-11-07 线上故障,已修)**:WMS「韵达」面单
(`template_id=12360764`、`CaiNiaoAuthInfoId=6838859`、`dbname=dzh93a8…`)换打印数据时平台回
`拉取打印参数失败:未将对象引用设置到对象的实例。`
实测对照(同一账号、同一 `fxdd` 域名、真实面单):
| 报文 | 平台结果 |
|---|---|
| `ExpressPrint` 复用 + `checkData={}`(旧实现) | 空引用;偶尔「成功」但 `documents` 为空、`WaybillCode` 为 null |
| `ExpressPrint` 复用 + `checkTemplateAvailable` 的 `Data`(`DateNow`/`DayPrintBatchNumber`) | **成功**,返回新鲜 `params`(`timestamp` = 当前时间)与 `templateURL` |
根因:`RequestBatchNumber` 由 `DateNow + DayPrintBatchNumber` 拼成,取号流程(`fetchWaybillNo`)
会先调 `CheckTemplateAvaliable` 拿这两个值,而换打印参数时传了 `checkData: {}`,
`RequestBatchNumber` 退化成 `1/1/`,平台解析批次号时抛空引用。
结论:**不是域名/分区问题**(fxdd + 该 dbname 在补齐批次号后正常),也不是菜鸟授权网点字段问题
(`Orders[0][CaiNiaoAuthInfoId]` 加不加结果一样)。现在 `fetchPrintParams` 固定先做模板校验再提交。
兜底(`waybillPrintData.fetchGroup`):平台没给 `documents`/`params`、或复用路径仍失败时,
回退 `POST /PrintHistory/LoadPrintData`(按 `printHistoryId`,只读、不消耗面单),
用 `Data[].PrintDataJson` 解出 `contents[].params` + `templateURL`,返回标 `source: print_history`。
这条路径在订单已离开「待发货」(`ErpState=sended`)时仍可用,但拿到的是**当时打印的签名**(可能已过期),
所以成功路径始终优先 `ExpressPrint` 重新签发。
- **params 是逐张面单的**:`printDataJson.PrintDataList.task.documents[].documentID` = 运单号,
`contents[].params` 是该张面单的内容;同店铺可共用的只有 `PrinterConfig` 与 `templateURL`,
**不能拿 A 单的 document 去打 B 单**(会把收件人/面单号搞错)。