oms/backend/app/lib/waybillPrintData.js
liufumingren 498543b9d7 perf(external-send): 控制回传平台的请求量,避免被判刷单
全部回读订单行在批量场景会被平台当成高频访问,补齐三处节流:

- syncPending:同批相邻两单之间留 EXTERNAL_SEND_INTERVAL_MS(默认 300ms)
- resolveTraceId:按账号缓存,批量内只调一次 getUserInfo(原来每单一次)
- dgj.resolveTraceId():实例级缓存 5 分钟的 traceId,
  取号(fetchWaybillNo)与重打(waybillPrintData)改用它,批量取号不再逐单 getUserInfo

配合上一版的「快照拼报文」,发货每单只有 1 次 POST,不再回读订单行。

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-07 08:14:12 +08:00

459 lines
18 KiB
JavaScript
Raw 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;
try {
printed = await service.fetchPrintParams(host, {
traceId,
dbname,
templateId,
row,
expressCode: item.record.express_code || '',
});
} catch (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}` });
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,
// 供单测/脚本复用
unwrapBody,
toStringList,
parsePrintHistoryIds,
pickPrintHistory,
parsePrintData,
pickParamsTimestamp,
isParamsExpired,
pickLogicalOrderId,
};