fix(print-data): 菜鸟系面单换打印参数空引用时回退按打印记录取

WMS「韵达」面单换打印数据时平台回「拉取打印参数失败:未将对象引用设置到对象的实例。」,
这是 ExpressPrint 复用路径上的平台内部空引用,多发生在菜鸟系面单(韵达/申通/中通…)。

- dgj.expressPrint:Orders[0] 补 CaiNiaoAuthInfoId(菜鸟面单按模板授权网点取打印数据,缺了平台会空引用)
- dgj.fetchPrintParams:支持传入 caiNiaoAuthInfoId 注入订单行;平台空引用时在错误里补一句排查提示
- waybillPrintData.fetchGroup:复用取号拉参数失败后回退
  POST /PrintHistory/LoadPrintData(按 printHistoryId 只读、不消耗面单),
  用 Data[].PrintDataJson 里的 contents[].params + templateURL 兜住,返回标 source=print_history;
  两条都失败才报错(带原原因)。成功路径仍优先 ExpressPrint(抖店签名要重新签发)
- 单测 waybillPrintDataFetch.test.js 4 例(成功不走回退 / 空引用回退 / 都失败 / PrintDataJson 解析)
- 文档补充双路径与踩坑记录

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-07 22:29:11 +08:00
parent 4501ca3922
commit 37de11c309
4 changed files with 174 additions and 5 deletions

View File

@ -2912,6 +2912,9 @@ 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,
@ -2978,15 +2981,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 = '' }) {
async fetchPrintParams(host, { traceId = '', dbname = '', templateId, row, expressCode = '', caiNiaoAuthInfoId = null }) {
if (!row) throw new Error('拉取打印参数需要平台订单行');
const sendRow = caiNiaoAuthInfoId == null
? row
: { ...row, CaiNiaoAuthInfoId: row.CaiNiaoAuthInfoId == null ? caiNiaoAuthInfoId : row.CaiNiaoAuthInfoId };
const printed = await this.expressPrint(host, {
traceId,
dbname,
templateId,
rows: [ row ],
rows: [ sendRow ],
checkData: {},
expressCode,
reuseWaybill: true,
@ -2996,7 +3003,13 @@ class DgjService extends PrintPlatformService {
.find(item => item && (item.IsError === true || Number(item.IsError) === 1));
if (errorItem) {
const reason = errorItem.ErrMsg || errorItem.ErrorMsg || '平台返回失败';
throw buildPlatformError(`店管家拉取打印参数失败:${reason}`, { status: 200, json: printed, text: '' });
// 平台内部空引用(未将对象引用设置到对象的实例):多为面单模板/菜鸟授权网点与订单不匹配
const emptyRef = /未将对象引用/.test(String(reason));
throw buildPlatformError(
`店管家拉取打印参数失败:${reason}` +
(emptyRef ? '(平台内部空引用:常见于菜鸟系面单缺少授权网点或模板与订单不匹配)' : ''),
{ status: 200, json: printed, text: '' }
);
}
const documents = [];

View File

@ -392,6 +392,7 @@ async function fetchGroup(ctx, { principalId, memo, group }) {
}
let printed = null;
let expressError = null;
try {
printed = await service.fetchPrintParams(host, {
traceId,
@ -399,11 +400,44 @@ async function fetchGroup(ctx, { principalId, memo, group }) {
templateId,
row,
expressCode: item.record.express_code || '',
caiNiaoAuthInfoId: base.cai_niao_auth_info_id,
});
} catch (err) {
ctx.logger.warn('[waybill.printdata] 拉取打印参数失败 host=%s dbname=%s id=%s:%s',
expressError = err;
ctx.logger.warn('[waybill.printdata] 复用取号请求拉取打印参数失败 host=%s dbname=%s id=%s:%s',
host, dbname, logicalOrderId, err.message);
results.push({ ...base, success: false, message: `拉取打印参数失败:${err.message}` });
}
// 兜底:按打印记录(PrintHistory/LoadPrintData)重新取平台下发的打印数据
// 菜鸟系面单(韵达/申通/中通…)在「复用取号」路径上会抛空引用,这条只读路径能直接拿到 PrintDataJson
if (!printed && typeof service.loadPrintData === 'function' && item.history.id) {
try {
const loaded = await service.loadPrintData(host, { traceId, dbname, printHistoryIds: [ item.history.id ] });
const parsed = parsePrintData((loaded || [])[0] ? (loaded || [])[0].print_data : '');
if (parsed.params) {
const timestamp = pickParamsTimestamp(parsed.params);
results.push({
...base,
success: true,
message: 'ok(按打印记录取回)',
expires_in: PRINT_DATA_TTL_SECONDS,
params: parsed.params,
params_timestamp: timestamp,
params_expired: isParamsExpired(timestamp),
template_url: parsed.template_url || '',
source: 'print_history',
});
continue;
}
ctx.logger.warn('[waybill.printdata] 打印记录里没有 params host=%s dbname=%s id=%s', host, dbname, item.history.id);
} catch (err) {
ctx.logger.warn('[waybill.printdata] 按打印记录重取失败 host=%s dbname=%s id=%s:%s',
host, dbname, item.history.id, err.message);
}
}
if (!printed) {
const reason = expressError ? expressError.message : '平台未返回打印数据';
results.push({ ...base, success: false, message: `拉取打印参数失败:${reason}` });
continue;
}
@ -447,6 +481,7 @@ async function fetchGroup(ctx, { principalId, memo, group }) {
module.exports = {
getPrintData,
// 供单测/脚本复用
fetchGroup,
unwrapBody,
toStringList,
parsePrintHistoryIds,

View File

@ -0,0 +1,111 @@
'use strict';
const { assert } = require('egg-mock/bootstrap');
const { fetchGroup, parsePrintData } = require('../../../app/lib/waybillPrintData');
/** 静默 logger(lib 里只用来留痕,不影响返回) */
const silentCtx = { logger: { info() {}, warn() {}, error() {} } };
/**
* 造一个分组(一个运单号)
* @param {Object} [overrides] 覆盖取号记录字段
* @return {Object} fetchGroup 的 group 入参
*/
function buildGroup(overrides = {}) {
return {
accountId: 1,
host: 'fxdd.dgjapp.com',
dbname: 'dzh93a8yur84Y3Yln2ha9RbPovVMhBTc',
items: [{
waybillCode: '321450799451452',
history: { id: '21887928954' },
record: {
delivery_order_code: 'dgj-875172836006880609',
template_id: '12360764',
express_code: 'YUNDA',
cai_niao_auth_info_id: 6838859,
dbname: 'dzh93a8yur84Y3Yln2ha9RbPovVMhBTc',
...overrides,
},
}],
};
}
/**
* 菜鸟系面单的 PrintDataJson(平台原样)
* @return {string} JSON 字符串
*/
function buildPrintDataJson() {
return JSON.stringify({
printDataJson: JSON.stringify({
PrinterConfig: { printer: {} },
PrintDataList: {
task: {
documents: [{
documentID: 'doc-1',
contents: [{ params: 'access_token=tok&method=logistics.getShopKey&sign=abc&timestamp=2026-11-07 22:00:00', templateURL: 'https://tpl' }],
}],
},
},
}),
});
}
describe('app/lib/waybillPrintData 换取打印参数', () => {
it('复用取号拉参数成功时直接用平台返回的 params', async () => {
let loadCalled = false;
const service = {
findPlatformOrderRow: async () => ({ Id: 1, LogicOrderId: '875172836006880609', SubOrders: [] }),
fetchPrintParams: async () => ({ waybill_codes: [ '321450799451452' ], documents: [{ params: 'p1', template_url: 'u1' }] }),
loadPrintData: async () => {
loadCalled = true;
return [];
},
};
const memo = new Map([[ '7:1', { account: {}, service }]]);
const results = await fetchGroup(silentCtx, { principalId: 7, memo, group: buildGroup() });
assert.strictEqual(results.length, 1);
assert.strictEqual(results[0].success, true);
assert.strictEqual(results[0].params, 'p1');
assert.strictEqual(loadCalled, false, '成功路径不该多打一次平台接口');
});
it('平台空引用(未将对象引用设置到对象的实例)时回退按打印记录取回', async () => {
const service = {
findPlatformOrderRow: async () => ({ Id: 1, LogicOrderId: '875172836006880609', SubOrders: [] }),
fetchPrintParams: async () => {
throw new Error('店管家拉取打印参数失败:未将对象引用设置到对象的实例。');
},
loadPrintData: async () => ([{ print_history_id: '21887928954', print_data: buildPrintDataJson() }]),
};
const memo = new Map([[ '7:1', { account: {}, service }]]);
const results = await fetchGroup(silentCtx, { principalId: 7, memo, group: buildGroup() });
assert.strictEqual(results.length, 1);
assert.strictEqual(results[0].success, true);
assert.strictEqual(results[0].source, 'print_history');
assert.match(results[0].params, /access_token=tok/);
assert.strictEqual(results[0].template_url, 'https://tpl');
assert.strictEqual(results[0].template_id, '12360764');
assert.strictEqual(results[0].cai_niao_auth_info_id, 6838859);
});
it('两条路径都拿不到时返回原错误原因', async () => {
const service = {
findPlatformOrderRow: async () => ({ Id: 1, LogicOrderId: '875172836006880609', SubOrders: [] }),
fetchPrintParams: async () => {
throw new Error('店管家拉取打印参数失败:未将对象引用设置到对象的实例。');
},
loadPrintData: async () => ([{ print_history_id: '21887928954', print_data: '' }]),
};
const memo = new Map([[ '7:1', { account: {}, service }]]);
const results = await fetchGroup(silentCtx, { principalId: 7, memo, group: buildGroup() });
assert.strictEqual(results[0].success, false);
assert.match(results[0].message, /未将对象引用/);
});
it('parsePrintData 能从 PrintDataJson 里解出 params 与 templateURL', () => {
const parsed = parsePrintData(buildPrintDataJson());
assert.match(parsed.params, /access_token=tok/);
assert.strictEqual(parsed.template_url, 'https://tpl');
});
});

View File

@ -400,6 +400,16 @@ WaybillCodeCreateDate='2026-11-04 08:20:37'
因此取号记录里同时落了 `dbname`、`platform_host`(实际命中的域名)与 `cai_niao_auth_info_id`(= 店铺唯一标识),
后续按「店铺标识 + 运单号」即可定位到该运单号对应的取号记录,再拉一份新的打印参数。
对外方法见 `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` 重新签发。
- **params 是逐张面单的**:`printDataJson.PrintDataList.task.documents[].documentID` = 运单号,
`contents[].params` 是该张面单的内容;同店铺可共用的只有 `PrinterConfig` 与 `templateURL`,
**不能拿 A 单的 document 去打 B 单**(会把收件人/面单号搞错)。