oms/backend/app/lib/waybillPrintData.js
liufumingren 956793ba66 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>
2026-11-07 22:35:37 +08:00

493 lines
20 KiB
JavaScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

'use strict';
/**
* 打印数据(params)有效期:店管家面团单打印数据只有 10 分钟有效,
* 这里按保守口径回给调用方,便于 WMS 判断是否需要重新拉取。
*/
const PRINT_DATA_TTL_SECONDS = 600;
/** 单次最多换取的运单号数量(一次打印任务的面单张数不会太多) */
const MAX_BATCH = 200;
/** 平台接口限流:同一个店铺两次请求之间至少间隔(毫秒),且一次只带一个 printHistoryId */
const THROTTLE_MS = 300;
/**
* 简单等待
* @param {number} ms 毫秒
* @return {Promise<void>} 无返回值
*/
function sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
/**
* 拆掉报文外层的 request / deliveryOrders 包装,取真正的入参对象
* @param {Object} data 原始报文
* @return {Object} 入参对象
*/
function unwrapBody(data) {
if (!data || typeof data !== 'object') return {};
if (data.request && typeof data.request === 'object' && !Array.isArray(data.request)) return data.request;
return data;
}
/**
* 归一化成非空字符串数组(兼容单值、逗号分隔、数组)
* @param {*} value 原始值
* @return {string[]} 去重后的字符串数组
*/
function toStringList(value) {
const raw = Array.isArray(value) ? value : [ value ];
const out = [];
for (const item of raw) {
if (item == null) continue;
for (const part of String(item).split(',')) {
const text = part.trim();
if (text) out.push(text);
}
}
return [ ...new Set(out) ];
}
/**
* 解析取号记录里的打印记录(`print_history_ids` 存的是 JSON 字符串)
* @param {string|Array} value 打印记录
* @return {Array<Object>} 打印记录数组
*/
function parsePrintHistoryIds(value) {
if (Array.isArray(value)) return value;
if (typeof value !== 'string' || !value.trim()) return [];
try {
const parsed = JSON.parse(value);
return Array.isArray(parsed) ? parsed : [];
} catch {
return [];
}
}
/**
* 从一条取号记录里挑出与运单号对应的打印记录
*
* 一个取号请求可能取到多张面单(多包裹),`print_history_ids` 与 `waybill_codes` 按顺序对应;
* 优先按 `waybill_code` 精确匹配,匹配不到时(历史数据缺该字段)退回按位取。
* @param {Object} record 取号记录(Sequelize 实例或 plain object)
* @param {string} waybillCode 运单号
* @param {string[]} [preferredIds] 调用方直传的打印记录ID(命中则优先用)
* @return {Object|null} 打印记录 { id, pid, waybill_code, batch_index }
*/
function pickPrintHistory(record, waybillCode, preferredIds = []) {
const list = parsePrintHistoryIds(record && record.print_history_ids);
if (!list.length) return null;
if (preferredIds.length) {
const hit = list.find(item => item && preferredIds.includes(String(item.id)));
if (hit) return hit;
}
const matched = list.find(item => item && String(item.waybill_code || '') === waybillCode);
if (matched) return matched;
const codes = parsePrintHistoryIds(record && record.waybill_codes);
const index = codes.findIndex(code => String(code) === waybillCode);
return index >= 0 ? list[index] || null : null;
}
/**
* 解析平台返回的打印数据(params),取出打印机配置与面单 document
*
* `Data[].PrintDataJson` 是字符串,里面还有一层 `printDataJson`,形如
* `{ PrinterConfig, PrintDataList: { task: { documents: [ { documentID, contents } ] } } }`。
* 同店铺的 PrinterConfig / templateURL 相同,多张面单只需把各自 documents 拼成一个 task。
* @param {string} printData 平台返回的 PrintDataJson
* @return {{printer_config: Object|null, document: Object|null, documents: Array}} 解析结果
*/
function parsePrintData(printData) {
const empty = { printer_config: null, document: null, documents: [], params: '', template_url: '' };
if (typeof printData !== 'string' || !printData.trim()) return empty;
try {
const outer = JSON.parse(printData);
const inner = outer && outer.printDataJson ? JSON.parse(outer.printDataJson) : outer;
const documents = inner && inner.PrintDataList && inner.PrintDataList.task && inner.PrintDataList.task.documents;
const list = Array.isArray(documents) ? documents : [];
const document = list[0] || null;
const contents = document && Array.isArray(document.contents) ? document.contents : [];
// 打印端真正要的是 contents[].params(access_token=...&method=logistics.getShopKey&sign=...)
const first = contents.find(item => item && String(item.params || '').trim()) || contents[0] || {};
return {
printer_config: (inner && inner.PrinterConfig) || null,
document,
documents: list,
params: String(first.params || ''),
template_url: String(first.templateURL || ''),
};
} catch {
return empty;
}
}
/**
* 从 params 串里取平台签名时间(`timestamp=YYYY-MM-DD HH:mm:ss`)
* @param {string} params 平台返回的 params
* @return {string} 时间字符串,取不到为空串
*/
function pickParamsTimestamp(params) {
const matched = /[?&]timestamp=([^&]+)/.exec(String(params || ''));
return matched ? decodeURIComponent(matched[1]).trim() : '';
}
/**
* params 里的签名是否已过期(平台有效期 10 分钟)
*
* ⚠️ 店管家的 `PrintHistory/LoadPrintData` 只是**回放那次打印时的签名**,不会重新签发,
* 所以隔一段时间再取一定是过期的;要新签名只能让平台重新下发(见 dgj.fetchPrintParams)。
* @param {string} timestamp 签名时间
* @param {number} [ttlSeconds] 有效期(秒)
* @return {boolean} 是否过期(时间解析失败按未过期处理,避免误判)
*/
function isParamsExpired(timestamp, ttlSeconds = PRINT_DATA_TTL_SECONDS) {
const time = Date.parse(String(timestamp || '').replace(' ', 'T'));
if (Number.isNaN(time)) return false;
return Date.now() - time > ttlSeconds * 1000;
}
/**
* 取(并缓存)打单账号的完整实例:一次批量请求通常只涉及 1~2 个账号
* @param {Object} ctx egg context
* @param {Map} memo 批内缓存
* @param {Object} params 参数
* @param {number} params.accountId 打单账号ID
* @param {number} params.principalId 主体ID
* @return {Promise<Object|null>} { account, service }
*/
async function loadAccount(ctx, memo, { accountId, principalId }) {
const key = `${principalId}:${accountId}`;
if (memo.has(key)) return memo.get(key);
const account = await ctx.model.ExternalPrintAccount.findByPk(accountId, {
include: [{ model: ctx.model.ExternalPrintPlatform, as: 'platform' }],
});
if (!account || !account.platform || (account.principal_id && Number(account.principal_id) !== Number(principalId))) {
memo.set(key, null);
return null;
}
const service = ctx.service.externalPrintOrder.createPlatformService(account);
const entry = { account, service };
memo.set(key, entry);
return entry;
}
/**
* 按运单号(或打印记录ID)重新拉取面单打印数据
*
* 背景:取号返回的打印数据只有 10 分钟有效期,WMS 真正打印前必须换新的。
* 定位口径:WMS 传「店铺标识(CaiNiaoAuthInfoId)+ 运单号」,OMS 查取号记录得到该运单号的
* 打印记录ID,再回平台 `PrintHistory/LoadPrintData` 换新的 params。
* 也支持直传 `printHistoryIds`(命中即跳过按运单号的匹配)。
* @param {Object} ctx egg context
* @param {Object} params 参数
* @param {number} params.principalId 主体ID(来自 app_key)
* @param {number} [params.warehouseId] 仓库ID(来自 app_key,仅用于日志)
* @param {Object} params.data 报文
* @param {string} [params.requestId] 调用方 request_id(日志用)
* @return {Promise<Object>} { ok, message, data }
*/
async function getPrintData(ctx, { principalId, warehouseId, data, requestId }) {
const Op = ctx.app.Sequelize.Op;
const body = unwrapBody(data);
ctx.logger.info('[waybill.printdata] 换取打印数据 principal=%s warehouse=%s requestId=%s', principalId, warehouseId || '-', requestId || '-');
const waybillCodes = toStringList(
body.waybillCodes || body.waybillCode || body.mailNos || body.mailNo || body.expressCodes
);
const historyIds = toStringList(body.printHistoryIds || body.printHistoryId);
const shopIds = toStringList(body.caiNiaoAuthInfoIds || body.caiNiaoAuthInfoId || body.authInfoIds)
.map(value => Number(value))
.filter(value => Number.isFinite(value) && value > 0);
if (!waybillCodes.length && !historyIds.length) {
return { ok: false, message: '缺少运单号(waybillCodes)或打印记录ID(printHistoryIds)' };
}
if (waybillCodes.length > MAX_BATCH) {
return { ok: false, message: `单次最多换取 ${MAX_BATCH} 个运单号的打印数据` };
}
// 定位取号记录:运单号走索引;直传打印记录ID时按 JSON 里的 id 匹配(避免全表扫描)
const where = { principal_id: principalId, status: 1 };
if (shopIds.length) where.cai_niao_auth_info_id = { [Op.in]: shopIds };
const conditions = [];
if (waybillCodes.length) conditions.push({ waybill_code: { [Op.in]: waybillCodes } });
if (historyIds.length) {
conditions.push({
[Op.or]: historyIds.map(id => ({ print_history_ids: { [Op.like]: `%"id":"${id}"%` } })),
});
}
where[Op.or] = conditions;
const records = await ctx.model.WaybillFetchRecord.findAll({
where,
order: [[ 'id', 'DESC' ]],
});
// 运单号 → 取号记录(同号可能被多次取号,取最新一条)
const byWaybill = new Map();
for (const record of records) {
const code = String(record.waybill_code || '');
if (!code || byWaybill.has(code)) continue;
if (shopIds.length && !shopIds.includes(Number(record.cai_niao_auth_info_id))) continue;
byWaybill.set(code, record);
}
const results = [];
const memo = new Map();
const groups = new Map(); // `${accountId}|${host}|${dbname}` → { accountId, host, dbname, items: [] }
for (const code of waybillCodes) {
const record = byWaybill.get(code);
if (!record) {
results.push({ waybill_code: code, success: false, message: '未找到该运单号的取号记录(可能不是通过 OMS 取的号)' });
continue;
}
const history = pickPrintHistory(record, code, historyIds);
if (!history) {
results.push({
waybill_code: code,
success: false,
message: '取号记录里没有该运单号的打印记录ID(PrintHistoryIds),无法换新的打印数据',
});
continue;
}
const key = `${record.account_id}|${record.platform_host || ''}|${record.dbname || ''}`;
if (!groups.has(key)) {
groups.set(key, {
accountId: Number(record.account_id),
host: String(record.platform_host || ''),
dbname: String(record.dbname || ''),
items: [],
});
}
groups.get(key).items.push({ waybillCode: code, record, history });
}
// 直传 printHistoryIds 但没有对应运单号的情况:按记录里的运单号补齐
if (historyIds.length) {
for (const record of records) {
const list = parsePrintHistoryIds(record.print_history_ids)
.filter(item => item && historyIds.includes(String(item.id)));
for (const history of list) {
const code = String(history.waybill_code || record.waybill_code || '');
if (!code || results.some(row => row.waybill_code === code)) continue;
if (waybillCodes.length && !waybillCodes.includes(code)) continue;
const key = `${record.account_id}|${record.platform_host || ''}|${record.dbname || ''}`;
if (!groups.has(key)) {
groups.set(key, {
accountId: Number(record.account_id),
host: String(record.platform_host || ''),
dbname: String(record.dbname || ''),
items: [],
});
}
groups.get(key).items.push({ waybillCode: code, record, history });
}
}
}
for (const group of groups.values()) {
const found = await fetchGroup(ctx, { principalId, memo, group });
results.push(...found);
}
const success = results.filter(row => row.success).length;
return {
ok: true,
message: 'ok',
data: {
total: results.length,
success,
failed: results.length - success,
// params 只有 10 分钟有效期,调用方需要在这个时间内打印
expires_in: PRINT_DATA_TTL_SECONDS,
results,
},
};
}
/**
* 从发货单号里取店管家系统编号(`dgj-10000280844952_2` → `10000280844952`)
* @param {string} deliveryOrderCode 发货单号
* @return {string} 系统编号
*/
function pickLogicalOrderId(deliveryOrderCode) {
return String(deliveryOrderCode || '')
.trim()
.replace(/^[^-]+-/, '')
.replace(/_\d+$/, '');
}
/**
* 按「账号 + 域名 + 分区」分组拉取打印参数
*
* 只对「打印需要 params 的平台」有意义(抖店:`params` 里是带签名的取号串,10 分钟过期);
* 其它平台(淘宝/拼多多/京东…)取号返回的 `printinfo` 就是面单打印数据,不需要 params。
* 拉取方式:复用订单已有运单号(`PrintMethod=Normal + IsIgnoreWaybillRepeat=true`),
* 平台只重新下发打印数据、不分配新面单。平台侧有限流,逐张串行并留间隔。
* @param {Object} ctx egg context
* @param {Object} params 参数
* @param {number} params.principalId 主体ID
* @param {Map} params.memo 批内账号缓存
* @param {Object} params.group 分组 { accountId, host, dbname, items }
* @return {Promise<Array<Object>>} 逐运单号结果
*/
async function fetchGroup(ctx, { principalId, memo, group }) {
const { accountId, host, dbname, items } = group;
const fallback = message => items.map(item => ({
waybill_code: item.waybillCode,
success: false,
message,
}));
const entry = await loadAccount(ctx, memo, { accountId, principalId });
if (!entry) return fallback('打单账号不存在或不属于该主体');
const { service } = entry;
if (typeof service.fetchPrintParams !== 'function' || typeof service.findPlatformOrderRow !== 'function') {
return fallback('当前打单平台不支持拉取打印参数');
}
let traceId = '';
try {
traceId = typeof service.resolveTraceId === 'function'
? await service.resolveTraceId()
: ((await service.getUserInfo()).data || {}).TraceId || '';
} catch {
traceId = '';
}
const results = [];
for (let index = 0; index < items.length; index += 1) {
const item = items[index];
if (index > 0) await sleep(THROTTLE_MS);
const base = {
waybill_code: item.waybillCode,
print_history_id: item.history.id,
template_id: item.record.template_id || '',
cai_niao_auth_info_id: item.record.cai_niao_auth_info_id == null ? null : Number(item.record.cai_niao_auth_info_id),
dbname: item.record.dbname || '',
};
const logicalOrderId = pickLogicalOrderId(item.record.delivery_order_code);
if (!logicalOrderId) {
results.push({ ...base, success: false, message: '取号记录缺少店管家系统编号,无法拉取打印参数' });
continue;
}
const templateId = String(item.record.template_id || '').trim();
if (!templateId) {
results.push({ ...base, success: false, message: '取号记录缺少面单模板ID,无法拉取打印参数' });
continue;
}
let row = null;
try {
row = await service.findPlatformOrderRow(host, { traceId, dbname, logicalOrderId });
} catch (err) {
results.push({ ...base, success: false, message: `回读平台订单失败:${err.message}` });
continue;
}
if (!row) {
results.push({ ...base, success: false, message: `店管家未找到订单:系统编号 ${logicalOrderId}` });
continue;
}
let printed = null;
let expressError = null;
try {
printed = await service.fetchPrintParams(host, {
traceId,
dbname,
templateId,
row,
expressCode: item.record.express_code || '',
});
} catch (err) {
expressError = err;
ctx.logger.warn('[waybill.printdata] 复用取号请求拉取打印参数失败 host=%s dbname=%s id=%s:%s',
host, dbname, logicalOrderId, 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;
}
// 安全闸:复用原号的调用不该换号;换号说明平台分配了新面单(已消耗),必须暴露出来
const codes = Array.isArray(printed.waybill_codes) ? printed.waybill_codes.map(String) : [];
if (codes.length && !codes.includes(String(item.waybillCode))) {
ctx.logger.error('[waybill.printdata] 拉取参数时平台返回了新运单号,已分配面单!原号=%s 新号=%s', item.waybillCode, codes.join(','));
results.push({
...base,
success: false,
message: `平台返回了新运单号 ${codes.join(',')}(原号 ${item.waybillCode}),已分配面单,请人工核对`,
});
continue;
}
const document = (printed.documents || []).find(doc => doc && String(doc.params || '').trim()) || (printed.documents || [])[0];
if (!document || !document.params) {
results.push({
...base,
success: false,
message: '该模板没有返回 params(只有抖店面单需要 params;其它平台请用取号返回的 printinfo 打单)',
});
continue;
}
const paramsTimestamp = pickParamsTimestamp(document.params);
results.push({
...base,
success: true,
message: 'ok',
expires_in: PRINT_DATA_TTL_SECONDS,
// 打印端要的就是这串:access_token=...&app_key=...&method=logistics.getShopKey&...&sign=...
params: document.params,
params_timestamp: paramsTimestamp,
params_expired: isParamsExpired(paramsTimestamp),
template_url: document.template_url || '',
});
}
return results;
}
module.exports = {
getPrintData,
// 供单测/脚本复用
fetchGroup,
unwrapBody,
toStringList,
parsePrintHistoryIds,
pickPrintHistory,
parsePrintData,
pickParamsTimestamp,
isParamsExpired,
pickLogicalOrderId,
};