feat(waybill): getprintdata 只回 params 串,并按 printHistoryId 逐个限流回源

- 返回精简:每单只给定位字段 + params(contents[].params,形如
  access_token=…&app_key=…&method=logistics.getShopKey&…&sign=…)与 template_url;
  不再回整包 print_data / printer_config / document
- 限流:平台该接口有限流,改为一次只带一个 printHistoryId,逐张串行并间隔 300ms;
  单张失败不影响其它张,失败原因逐单返回
- params 为空时直接判失败(平台的打印数据里没有 params)

实测:{ printHistoryId: "10000078656212" } → params 为 access_token=uo7…
&method=logistics.getShopKey&…&sign=8849…,template_url 为申通 76x130 模板。

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-07 06:56:20 +08:00
parent 07a27a5bbd
commit 82879cdef5
3 changed files with 89 additions and 39 deletions

View File

@ -386,18 +386,21 @@ WMS 真正要打印时,调 `deliveryorder.getprintdata` 换一份新的(OMS
| 入参(推荐批量) | `{ "caiNiaoAuthInfoIds": [ 6838859 ], "waybillCodes": [ "770357408441408" ] }` |
| 入参(可选直传) | `{ "printHistoryIds": [ "10000078656212", "…" ] }`(数组,命中即跳过按运单号查库) |
| 出参 | `{ total, success, failed, expires_in, results: [ … ] }`,`expires_in` 固定 600 秒 |
| 单条结果 | `waybill_code, success, message, print_history_id, template_id, cai_niao_auth_info_id, dbname, print_data, printer_config, document` |
| 单条结果 | `waybill_code, success, message, print_history_id, template_id, cai_niao_auth_info_id, dbname, expires_in, params, template_url` |
`caiNiaoAuthInfoId` 就是取号响应里的 `cai_niao_auth_info_id`(**每个店铺唯一**),WMS 落库时把它和运单号一起存下来即可;
OMS 用它 + 运单号定位到那次取号的打印记录(`waybill_fetch_records`,已建 `principal_id + cai_niao_auth_info_id + waybill_code` 索引)。
返回用法:
返回用法(**只需要 `params`**):
- `print_data`:平台原样返回的 params 字符串,直接交给打印服务
- `printer_config` / `document`:拆好的结构。**同店铺多张面单共用一个 `printer_config`**,
把各自的 `document`(含 `documentID` = 运单号、`contents[].params`)拼进同一个 `PrintDataList.task.documents`
就是一次多张打印任务 —— 不要拿 A 单的 `document` 去打 B 单,`documentID`/params 是逐张面单的
- 建议 WMS 按「店铺(caiNiaoAuthInfoId)分组、一批运单号一次调用」换 params,10 分钟内打完
- `params`:打印端真正要的那串,平台原样返回的
`access_token=uo7…&app_key=7152…&method=logistics.getShopKey&param_json={}&timestamp=2026-11-07 06:43:36&v=2&sign=9cb2…`
(取自 `documents[].contents[].params`,已从整包打印数据里提取好,**不需要 WMS 再解析**)
- `template_url`:该面单的模板地址(`contents[].templateURL`),打印 SDK 渲染时用;与 `params` 同源
- `print_history_id` / `template_id` / `cai_niao_auth_info_id` / `dbname`:定位与对账用
- ⚠️ **`params` 是逐张面单的**,不能拿 A 单的 `params` 去打 B 单(里面带着该面单的签名/时间戳)
- **限流**:平台该接口有限流,OMS 内部**一次只带一个 `printHistoryId`**、逐张串行并留 300ms 间隔;
WMS 侧也建议一张一张调(或小批),10 分钟内打完
**注意**:`printHistoryId` 由 OMS 保存,**不需要** WMS 再存一份(每张面单一条、重打/换号会新增,存两份必然不一致)。
单条失败原因:`未找到该运单号的取号记录(可能不是通过 OMS 取的号)` /
@ -409,8 +412,9 @@ OMS 用它 + 运单号定位到那次取号的打印记录(`waybill_fetch_reco
>
> 📌 **只传一个打印记录ID就够了**(实测):`{ "printHistoryId": "10000078656212" }` →
> OMS 从自己库里取出该记录对应的**域名(`platform_host`)+ 分区(`dbname`)+ 打单账号**,直接回源
> `PrintHistory/LoadPrintData` 拿新的 params,返回 `print_data`(实测 7888 字符)与拆好的 `document`。
> 也就是说 WMS 不需要知道域名/分区,店铺标识与运单号也不是必填。
> `PrintHistory/LoadPrintData` 拿新的 params,结果里的 `params` 就是那串
> `access_token=…&app_key=…&method=logistics.getShopKey&…&sign=…`。
> 也就是说 WMS 不需要知道域名/分区,店铺标识与运单号也不是必填;一次一张、串行调用即可。
```sql
-- 打印前换 params 时 OMS 内部按这条定位(同一个运单号多次取号取最新一条)

View File

@ -9,6 +9,18 @@ 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 原始报文
@ -89,17 +101,23 @@ function pickPrintHistory(record, waybillCode, preferredIds = []) {
* @return {{printer_config: Object|null, document: Object|null, documents: Array}} 解析结果
*/
function parsePrintData(printData) {
const empty = { printer_config: null, document: null, documents: [] };
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: list[0] || null,
document,
documents: list,
params: String(first.params || ''),
template_url: String(first.templateURL || ''),
};
} catch {
return empty;
@ -264,7 +282,10 @@ async function getPrintData(ctx, { principalId, warehouseId, data, requestId })
}
/**
* 按「账号 + 域名 + 分区」分组拉取打印数据(同店铺一次请求取多张)
* 按「账号 + 域名 + 分区」分组拉取打印数据
*
* 平台侧对这个接口有限流,**一次只带一个 printHistoryId**,逐个串行请求并在两次之间留间隔,
* 避免同店铺多张面单一起打过去被限流/超时。
* @param {Object} ctx egg context
* @param {Object} params 参数
* @param {number} params.principalId 主体ID
@ -293,26 +314,34 @@ async function fetchGroup(ctx, { principalId, memo, group }) {
traceId = '';
}
let list = [];
try {
list = await service.loadPrintData(host, {
traceId,
dbname,
printHistoryIds: items.map(item => item.history.id),
});
} catch (err) {
ctx.logger.warn('[waybill.printdata] 换打印数据失败 host=%s dbname=%s:%s', host, dbname, err.message);
return fallback(`读取打印数据失败:${err.message}`);
}
const byHistoryId = new Map(list.map(item => [ String(item.print_history_id), item ]));
return items.map(item => {
const row = byHistoryId.get(String(item.history.id));
const results = [];
for (let index = 0; index < items.length; index += 1) {
const item = items[index];
if (index > 0) await sleep(THROTTLE_MS);
let row = null;
try {
const list = await service.loadPrintData(host, {
traceId,
dbname,
printHistoryIds: [ item.history.id ],
});
row = list[0] || null;
} catch (err) {
ctx.logger.warn('[waybill.printdata] 换打印数据失败 host=%s dbname=%s id=%s:%s',
host, dbname, item.history.id, err.message);
results.push({ waybill_code: item.waybillCode, success: false, message: `读取打印数据失败:${err.message}` });
continue;
}
if (!row) {
return { waybill_code: item.waybillCode, success: false, message: '平台未返回该运单号的打印数据' };
results.push({ waybill_code: item.waybillCode, success: false, message: '平台未返回该运单号的打印数据' });
continue;
}
const parsed = parsePrintData(row.print_data);
return {
if (!parsed.params) {
results.push({ waybill_code: item.waybillCode, success: false, message: '平台的打印数据里没有 params(access_token 串)' });
continue;
}
results.push({
waybill_code: item.waybillCode,
success: true,
message: 'ok',
@ -321,13 +350,12 @@ async function fetchGroup(ctx, { principalId, memo, group }) {
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 || '',
expires_in: PRINT_DATA_TTL_SECONDS,
// 新的打印数据(平台原样返回的 params 字符串)
print_data: row.print_data,
// 拆好的结构:同店铺多张面单共用一个 printer_config,documents 拼起来即可
printer_config: parsed.printer_config,
document: parsed.document,
};
});
// 打印端要的就是这串:access_token=...&app_key=...&method=logistics.getShopKey&...&sign=...
params: parsed.params,
template_url: parsed.template_url,
});
}
return results;
}
module.exports = {

View File

@ -42,7 +42,7 @@ describe('waybillPrintData 打印数据换取', () => {
assert.strictEqual(printData.pickPrintHistory({}, 'A'), null);
});
it('解析平台返回的 params:拿到打印机配置与面单 document', () => {
it('解析平台返回的 params:拿到打印机配置、面单 document 与 access_token 串', () => {
const params = JSON.stringify({
id: null,
sendContent: '[1];\n',
@ -50,14 +50,32 @@ describe('waybillPrintData 打印数据换取', () => {
PrinterConfig: { cmd: 'setPrinterConfig', printer: { name: '默认打印机' } },
PrintDataList: {
cmd: 'print',
task: { printer: '默认打印机', documents: [{ documentID: '770357408441408', contents: [{ templateURL: 'https://x/t.xml' }] }] },
task: {
printer: '默认打印机',
documents: [{
documentID: '770357408441408',
contents: [
{ templateURL: '', params: '' },
{
templateURL: 'https://x/t.xml',
params: 'access_token=tok&app_key=715&method=logistics.getShopKey&param_json={}&timestamp=2026-11-07 06:43:36&v=2&sign=9cb2',
},
],
}],
},
},
}),
});
const parsed = printData.parsePrintData(params);
console.log('documentID:', parsed.document.documentID, '| printer:', parsed.printer_config.printer.name);
console.log('params:', parsed.params);
assert.strictEqual(parsed.document.documentID, '770357408441408');
assert.strictEqual(parsed.printer_config.printer.name, '默认打印机');
assert.deepStrictEqual(printData.parsePrintData('not-json'), { printer_config: null, document: null, documents: [] });
// 跳过空的 contents,取真正带 params 的那条
assert.ok(parsed.params.startsWith('access_token=tok&app_key=715'));
assert.strictEqual(parsed.template_url, 'https://x/t.xml');
assert.deepStrictEqual(printData.parsePrintData('not-json'), {
printer_config: null, document: null, documents: [], params: '', template_url: '',
});
});
});