refactor(waybill): 更正语义——这不是「重打」,只是给需要 params 的平台拉打印数据

- dgj.reprintPrintData → fetchPrintParams;expressPrint 选项 reprint → reuseWaybill
  (PrintMethod=Normal + IsIgnoreWaybillRepeat=true = 复用原运单号、只重新下发打印数据)
- 提示语与安全闸措辞改为「拉取打印参数 / 平台分配了面单」,不再叫重打
- 模板不返回 params 时明确提示:只有抖店面单需要 params,
  淘宝/拼多多/京东/视频号等直接用取号返回的 printinfo 打单
- 文档同步:LoadPrintData 只回放历史签名;拉 params 走「复用原号重新下发」;
  仅抖店需要 params;验收记录改为「拉取 params 未产生新面单(余额 5253→5253)」

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-07 07:52:23 +08:00
parent f7d070a2b4
commit d5b4298c86
4 changed files with 57 additions and 44 deletions

View File

@ -391,10 +391,15 @@ WMS 真正要打印时,调 `deliveryorder.getprintdata` 换一份新的(OMS
> ⚠️ **重要(实测 2026-11-07)**:店管家 `PrintHistory/LoadPrintData` **只回放那次打印时签发的 params,不会重签**
> (`params_timestamp` 恒等于该打印记录的 `CreateDate`;换 `FxPageType=1/2`、加 `IsRePrint`/`IsRefresh`
> 都返回同一个 `timestamp/sign`),所以那串 `access_token=…&sign=…` 10 分钟后必失效。
> ✅ 要新鲜签名只能让平台**重新打印**:`ExpressPrint` + `PrintMethod=Normal` + `IsIgnoreWaybillRepeat=true`
> —— 实测平台**复用订单已有运单号**(不消耗面单)并重签 params(返回的 `timestamp` = 当前时间)。
> OMS 的 `deliveryorder.getprintdata` 已按这条路径实现:回读平台订单行 → 原单号打印 → 返回新 `params`;
> 并带安全闸,万一平台返回了新运单号(说明已消耗面单)会直接判失败并告警,不会静默返回。
> ✅ 要新鲜签名只能让平台重新下发:`ExpressPrint` + `PrintMethod=Normal` + `IsIgnoreWaybillRepeat=true`
> —— 实测平台**复用订单已有运单号**(不分配新面单、余额 5253 → 5253 不变),只把打印数据(params)重新给一份。
> 注意这**不是「重打」**:真正的打印在打印端做,这里只是把打印数据重新取一次。
> OMS 的 `deliveryorder.getprintdata` 已按这条路径实现;并带安全闸,万一平台返回了新运单号(说明已分配面单)
> 会直接判失败并告警,不会静默返回。
>
> 📌 **只有需要 `params` 的平台/模板才用这个接口**:抖店(DYXD)面单打的是一串带签名的 `params`,
> 10 分钟过期;淘宝/拼多多/京东/视频号等平台取号返回的 `printinfo` 就是面单打印数据,直接用它打印即可。
> 若模板不返回 `params`,接口会返回失败并说明「只有抖店面单需要 params…」。
`caiNiaoAuthInfoId` 就是取号响应里的 `cai_niao_auth_info_id`(**每个店铺唯一**),WMS 落库时把它和运单号一起存下来即可;
OMS 用它 + 运单号定位到那次取号的打印记录(`waybill_fetch_records`,已建 `principal_id + cai_niao_auth_info_id + waybill_code` 索引)。
@ -410,16 +415,16 @@ OMS 用它 + 运单号定位到那次取号的打印记录(`waybill_fetch_reco
- **限流**:平台该接口有限流,OMS 内部**一次只带一个 `printHistoryId`**、逐张串行并留 300ms 间隔;
WMS 侧也建议一张一张调(或小批),10 分钟内打完
- **新鲜度**:`params_timestamp` 是平台签发时间,`params_expired` 由 OMS 按 10 分钟算出;
本接口走「原单号打印」重签,正常应当 `params_expired=false`。
若为 `true` 或 `success=false` 且 message 提到「重打返回了新运单号」,说明平台异常发了新号(已消耗面单),需人工核对
本接口走「复用原运单号、重新下发打印数据」,正常应当 `params_expired=false`。
若为 `true` 或 `success=false` 且 message 提到「平台返回了新运单号」,说明平台异常分配了新面单,需人工核对
**注意**:`printHistoryId` 由 OMS 保存,**不需要** WMS 再存一份(每张面单一条、重打/换号会新增,存两份必然不一致)。
**注意**:`printHistoryId` 由 OMS 保存,**不需要** WMS 再存一份(每张面单一条、换号/重打都会新增,存两份必然不一致)。
单条失败原因:`未找到该运单号的取号记录(可能不是通过 OMS 取的号)` /
`取号记录里没有该运单号的打印记录ID(PrintHistoryIds),无法换新的打印数据`。
> 📌 **取号响应也会返回 `print_history_ids` / `print_history_id`**(见 §4.2),WMS 可按需落库;
> 但打印前换 params 时**不要求** WMS 传它 —— 传「`caiNiaoAuthInfoIds` + `waybillCodes`」由 OMS 查库即可,
> 想省一次查库时再直传 `printHistoryIds`。两者以 OMS 库里的记录为准(重打会新增打印记录)。
> 想省一次查库时再直传 `printHistoryIds`。两者以 OMS 库里的记录为准(换号/重打都会新增打印记录)。
>
> 📌 **只传一个打印记录ID就够了**(实测):`{ "printHistoryId": "10000078656212" }` →
> OMS 从自己库里取出该记录对应的**域名(`platform_host`)+ 分区(`dbname`)+ 打单账号**,直接回源
@ -435,7 +440,7 @@ WHERE principal_id = ? AND status = 1 AND waybill_code = ?
ORDER BY id DESC LIMIT 1;
```
> ✅ **验收(2026-11-07 线上)**:重打未产生新面单,返回原运单号 + 新鲜 `params`,测试通过。
> ✅ **验收(2026-11-07 线上)**:拉取 params 未产生新面单(余额不变),返回原运单号 + 新鲜 `params`,测试通过。
> 误分配的 2 张面单已由业务侧回收。
---

View File

@ -2548,10 +2548,10 @@ class DgjService extends PrintPlatformService {
* @param {Object} [options.checkData] CheckTemplateAvaliable 返回的 Data(DateNow / DayPrintBatchNumber / Branches)
* @param {number} [options.packageCount] 包裹张数(默认 1):>1 时把同一订单行重复 N 份
* @param {string} [options.expressCode] 快递编码(仅用于回传 WaybillCodes 时补 ExpressCpCode)
* @param {boolean} [options.reprint] 是否「原单号打印」(复用平台已有运单号、不消耗面单;重打时用)
* @param {boolean} [options.reuseWaybill] 复用平台已有运单号、只拉取打印数据(不分配新面单);拉 params 时用
* @return {Promise<Object>} 平台响应(Data.WaybillCode[] 含运单号与打印数据)
*/
async expressPrint(host, { traceId, dbname, templateId, rows, checkData, packageCount = 1, expressCode = '', reprint = false }) {
async expressPrint(host, { traceId, dbname, templateId, rows, checkData, packageCount = 1, expressCode = '', reuseWaybill = false }) {
const data = checkData || {};
const repeat = Number.isFinite(Number(packageCount)) && Number(packageCount) > 1 ? Math.floor(Number(packageCount)) : 1;
const currentWaybillCode = (() => {
@ -2633,10 +2633,10 @@ class DgjService extends PrintPlatformService {
PackageCount: String(repeat),
PackageDesc: '',
GoodsDesc: '',
// 「原单号打印」(重打):PrintMethod=Normal + IsIgnoreWaybillRepeat=true 让平台复用已有运单号,
// 只重新签发打印数据(params 里的签名会刷新),不消耗新面单
PrintMethod: reprint ? 'Normal' : 'NewPrint',
IsIgnoreWaybillRepeat: reprint ? 'true' : 'false',
// 「复用已有运单号」拉取打印数据:PrintMethod=Normal + IsIgnoreWaybillRepeat=true,
// 平台不再分配新面单,只把打印数据(抖店是 params)重新下发
PrintMethod: reuseWaybill ? 'Normal' : 'NewPrint',
IsIgnoreWaybillRepeat: reuseWaybill ? 'true' : 'false',
PrinterName: '默认打印机',
IsPreview: 'false',
IsContinueForStock: 'false',
@ -2662,11 +2662,14 @@ class DgjService extends PrintPlatformService {
}
/**
* 「原单号打印」重签打印数据(复用已有运单号,**不消耗面单**)
* 拉取面单打印参数(抖店等需要 `params` 的平台;复用已有运单号,**不分配新面单**)
*
* `PrintHistory/LoadPrintData` 只回放历史签名(实测不会重签,10 分钟后必然过期),
* 要新的 `params`(`access_token=…&timestamp=…&sign=…`)只能让平台重新打印一次:
* `PrintMethod=Normal + IsIgnoreWaybillRepeat=true` → 平台复用该订单已有运单号,只重新签发打印数据。
* 背景:抖店面单打印走的是一串带签名的 `params`
* (`access_token=…&method=logistics.getShopKey&timestamp=…&sign=…`),**10 分钟过期**;
* 而 `PrintHistory/LoadPrintData` 只回放历史签名(实测不重签),拿不到新鲜串。
* 平台侧唯一能重新下发的入口是 `ExpressPrint`:
* `PrintMethod=Normal + IsIgnoreWaybillRepeat=true` → 复用订单已有运单号、只重新下发打印数据。
* 注意:这不是「重打」,只是把打印数据(params)重新取一次;真正的打印在打印端做。
* @param {string} host 平台域名
* @param {Object} options 参数
* @param {string} options.traceId 登录上下文 traceId
@ -2674,10 +2677,10 @@ class DgjService extends PrintPlatformService {
* @param {string} options.templateId 面单模板ID
* @param {Object} options.row 平台订单行(findPlatformOrderRow 的返回)
* @param {string} [options.expressCode] 快递编码
* @return {Promise<{waybill_codes: string[], documents: Array<{documentID: string, params: string, template_url: string}>, raw: Object}>} 重签结果
* @return {Promise<{waybill_codes: string[], documents: Array<{documentID: string, params: string, template_url: string}>, raw: Object}>} 打印数据
*/
async reprintPrintData(host, { traceId = '', dbname = '', templateId, row, expressCode = '' }) {
if (!row) throw new Error('原单号打印需要平台订单行');
async fetchPrintParams(host, { traceId = '', dbname = '', templateId, row, expressCode = '' }) {
if (!row) throw new Error('拉取打印参数需要平台订单行');
const printed = await this.expressPrint(host, {
traceId,
dbname,
@ -2685,14 +2688,14 @@ class DgjService extends PrintPlatformService {
rows: [ row ],
checkData: {},
expressCode,
reprint: true,
reuseWaybill: true,
});
const errorItem = (Array.isArray(printed && printed.Data && printed.Data.WaybillCode) ? printed.Data.WaybillCode : [])
.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 reason = errorItem.ErrMsg || errorItem.ErrorMsg || '平台返回失败';
throw buildPlatformError(`店管家拉取打印参数失败:${reason}`, { status: 200, json: printed, text: '' });
}
const documents = [];

View File

@ -138,7 +138,7 @@ function pickParamsTimestamp(params) {
* params 里的签名是否已过期(平台有效期 10 分钟)
*
* ⚠️ 店管家的 `PrintHistory/LoadPrintData` 只是**回放那次打印时的签名**,不会重新签发,
* 所以隔一段时间再取一定是过期的;要新签名只能重新走「原单号打印」。
* 所以隔一段时间再取一定是过期的;要新签名只能让平台重新下发(见 dgj.fetchPrintParams)。
* @param {string} timestamp 签名时间
* @param {number} [ttlSeconds] 有效期(秒)
* @return {boolean} 是否过期(时间解析失败按未过期处理,避免误判)
@ -319,11 +319,12 @@ function pickLogicalOrderId(deliveryOrderCode) {
}
/**
* 按「账号 + 域名 + 分区」分组换取打印数据
* 按「账号 + 域名 + 分区」分组拉取打印参数
*
* 用「原单号打印」重签:平台复用订单已有运单号(**不消耗面单**)并重新签发 params。
* `PrintHistory/LoadPrintData` 只是历史回放,不能用来换新签名。
* 平台侧有限流,逐张串行并在两次之间留间隔。
* 只对「打印需要 params 的平台」有意义(抖店:`params` 里是带签名的取号串,10 分钟过期);
* 其它平台(淘宝/拼多多/京东…)取号返回的 `printinfo` 就是面单打印数据,不需要 params。
* 拉取方式:复用订单已有运单号(`PrintMethod=Normal + IsIgnoreWaybillRepeat=true`),
* 平台只重新下发打印数据、不分配新面单。平台侧有限流,逐张串行并留间隔。
* @param {Object} ctx egg context
* @param {Object} params 参数
* @param {number} params.principalId 主体ID
@ -342,8 +343,8 @@ async function fetchGroup(ctx, { principalId, memo, group }) {
const entry = await loadAccount(ctx, memo, { accountId, principalId });
if (!entry) return fallback('打单账号不存在或不属于该主体');
const { service } = entry;
if (typeof service.reprintPrintData !== 'function' || typeof service.findPlatformOrderRow !== 'function') {
return fallback('当前打单平台不支持重新打印(原单号打印)');
if (typeof service.fetchPrintParams !== 'function' || typeof service.findPlatformOrderRow !== 'function') {
return fallback('当前打单平台不支持拉取打印参数');
}
let traceId = '';
@ -368,12 +369,12 @@ async function fetchGroup(ctx, { principalId, memo, group }) {
const logicalOrderId = pickLogicalOrderId(item.record.delivery_order_code);
if (!logicalOrderId) {
results.push({ ...base, success: false, message: '取号记录缺少店管家系统编号,无法重打' });
results.push({ ...base, success: false, message: '取号记录缺少店管家系统编号,无法拉取打印参数' });
continue;
}
const templateId = String(item.record.template_id || '').trim();
if (!templateId) {
results.push({ ...base, success: false, message: '取号记录缺少面单模板ID,无法重打' });
results.push({ ...base, success: false, message: '取号记录缺少面单模板ID,无法拉取打印参数' });
continue;
}
@ -391,7 +392,7 @@ async function fetchGroup(ctx, { principalId, memo, group }) {
let printed = null;
try {
printed = await service.reprintPrintData(host, {
printed = await service.fetchPrintParams(host, {
traceId,
dbname,
templateId,
@ -399,27 +400,31 @@ async function fetchGroup(ctx, { principalId, memo, group }) {
expressCode: item.record.express_code || '',
});
} catch (err) {
ctx.logger.warn('[waybill.printdata] 原单号打印失败 host=%s dbname=%s id=%s:%s',
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}` });
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(','));
ctx.logger.error('[waybill.printdata] 拉取参数时平台返回了新运单号,已分配面单!原号=%s 新号=%s', item.waybillCode, codes.join(','));
results.push({
...base,
success: false,
message: `重打返回了新运单号 ${codes.join(',')}(原号 ${item.waybillCode}),已消耗面单,请人工核对`,
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(access_token 串)' });
results.push({
...base,
success: false,
message: '该模板没有返回 params(只有抖店面单需要 params;其它平台请用取号返回的 printinfo 打单)',
});
continue;
}
const paramsTimestamp = pickParamsTimestamp(document.params);

View File

@ -276,11 +276,11 @@ WaybillCodeCreateDate='2026-11-04 08:20:37'
(`access_token=…&method=logistics.getShopKey&timestamp=…&sign=…`,`timestamp` = 该打印记录的 `CreateDate`)。
⚠️ 实测确认:`POST /PrintHistory/LoadPrintData` **只是回放那次打印的签名,不会重新签发**
(换 `FxPageType=1/2`、加 `IsRePrint` / `IsRefresh` 都返回同一个 `timestamp`/`sign`)。
✅ 要新签名只能让平台重新打印:`ExpressPrint` + `PrintMethod=Normal` + `IsIgnoreWaybillRepeat=true`
✅ 要新签名只能让平台重新下发(不是重打,只是拿一份新的打印数据):`ExpressPrint` + `PrintMethod=Normal` + `IsIgnoreWaybillRepeat=true`
→ 实测**复用订单已有运单号**(不消耗面单)、`params.timestamp` = 当前时间。
对照:`PrintMethod=NewPrint`(或 `IsIgnoreWaybillRepeat=false`)会分配新号并消耗面单,重打绝不能用。
对照:`PrintMethod=NewPrint`(或 `IsIgnoreWaybillRepeat=false`)会分配新号并消耗面单,拉取 params 绝不能用。
因此取号记录里同时落了 `dbname`、`platform_host`(实际命中的域名)与 `cai_niao_auth_info_id`(= 店铺唯一标识),
后续按「店铺标识 + 运单号」即可定位到该运单号对应的取号记录,再做原单号重打。
后续按「店铺标识 + 运单号」即可定位到该运单号对应的取号记录,再拉一份新的打印参数。
对外方法见 `deliveryorder.getprintdata`(`WMS-OMS-取号对接.md` §4.7.1)。
- **params 是逐张面单的**:`printDataJson.PrintDataList.task.documents[].documentID` = 运单号,
`contents[].params` 是该张面单的内容;同店铺可共用的只有 `PrinterConfig` 与 `templateURL`,