fix(waybill): 实测 LoadPrintData 只回放历史签名,返回 params_timestamp/params_expired

核实结论(2026-11-07,真实账号只读探测):
- Data[0].PrintDataJson、PrintHistoryData.PrintDataJson、PrinterJsonData 里的 params 完全一致,
  timestamp 都等于该打印记录的 CreateDate(实测 05:52:50 / 06:43:36)
- 换 FxPageType=1/2、加 IsRePrint / IsRefresh 都返回同一个 timestamp/sign → 接口不会重签
- 所以「打印前换新 params」不成立;只有取号那一刻返回的 params 是新鲜的,10 分钟后必过期

- getprintdata 结果新增 params_timestamp / params_expired,message 里点明是历史签名与后续做法
- 文档更正:LoadPrintData 是回放、不是重签;重打需走 ExpressPrint「原单号打印」重签(待接入)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-07 07:31:55 +08:00
parent 82879cdef5
commit 82ebe7e022
3 changed files with 91 additions and 7 deletions

View File

@ -386,7 +386,15 @@ 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, expires_in, params, template_url` |
| 单条结果 | `waybill_code, success, message, print_history_id, template_id, cai_niao_auth_info_id, dbname, expires_in, params, params_timestamp, params_expired, template_url` |
> ⚠️ **重要(实测 2026-11-07)**:店管家 `PrintHistory/LoadPrintData` **只回放那次打印时签发的 params,不会重签**。
> 返回里的 `params_timestamp` 等于该打印记录的 `CreateDate`;换 `FxPageType=1/2`、加 `IsRePrint`/`IsRefresh`
> 都返回同一个 `timestamp/sign`。所以隔超过 10 分钟再取,`params_expired` 一定为 `true`,
> 那串 `access_token=…&sign=…` 发给打印网关会被判过期。
> 结论:**「打印前调本接口换新 params」不成立**,只能保证「取号后 10 分钟内打印」。
> 超过 10 分钟的重打需要平台重新签发(走 `ExpressPrint` 的「原单号打印」模式,复用已有运单号、不消耗面单),
> 该路径待确认后接入;当前本接口会把 `params_expired` 如实返回,请按它决定是否走重打。
`caiNiaoAuthInfoId` 就是取号响应里的 `cai_niao_auth_info_id`(**每个店铺唯一**),WMS 落库时把它和运单号一起存下来即可;
OMS 用它 + 运单号定位到那次取号的打印记录(`waybill_fetch_records`,已建 `principal_id + cai_niao_auth_info_id + waybill_code` 索引)。
@ -401,6 +409,8 @@ OMS 用它 + 运单号定位到那次取号的打印记录(`waybill_fetch_reco
- ⚠️ **`params` 是逐张面单的**,不能拿 A 单的 `params` 去打 B 单(里面带着该面单的签名/时间戳)
- **限流**:平台该接口有限流,OMS 内部**一次只带一个 `printHistoryId`**、逐张串行并留 300ms 间隔;
WMS 侧也建议一张一张调(或小批),10 分钟内打完
- **新鲜度**:`params_timestamp` 是平台签发时间,`params_expired` 由 OMS 按 10 分钟算出;
取号后 10 分钟内换到的 `params` 可直接打印,超过就一定是历史签名(见上方 ⚠️)
**注意**:`printHistoryId` 由 OMS 保存,**不需要** WMS 再存一份(每张面单一条、重打/换号会新增,存两份必然不一致)。
单条失败原因:`未找到该运单号的取号记录(可能不是通过 OMS 取的号)` /
@ -951,4 +961,43 @@ OMS(API) 渠道订单同步时报「发货单缺少奇门货主编码」:
本地 `wms_api_app`(id=48 测试接口)的 `qimen_customer_id` / `qimen_warehouse_code` 为空。
若后续需要回传 `ownerCode`,建议由 OMS 侧在 `warehouse_apis` 提供货主编码并同步到 `api_app.qimen_customer_id`。
wms/
wms/
---
## WMS 侧落库 print_history_id / cai_niao_auth_info_id 并按店铺换抖音 params(2026-11-07 07:05)
### 1. 需求(WMS 侧确认)
1. `wms_order_express` 增加 `print_history_id`、`cai_niao_auth_info_id` 两个字段;
2. 回 OMS 取号(`deliveryorder.getwaybill`)成功时落这两个字段;
3. 拉取抖音打印数据时按 `cai_niao_auth_info_id` 做店铺分组,每组任取一个 `print_history_id`
回 OMS 换一次 `params`,该店铺下所有运单共用。
### 2. WMS 已完成
| 项 | 说明 |
|---|---|
| 迁移 | `D:\wms\database\migrations\20261107110000-add-oms-print-fields-to-order-express.js`(`print_history_id varchar(64)`、`cai_niao_auth_info_id bigint unsigned`,均允许空) |
| 模型 | `app/model/order_express.js` 同步两个字段 |
| 取号落库 | `app/service/systems/express_platform.js#oms`:`print_history_id` 兼容 `print_history_id` / `print_history_ids[0].id`;`cai_niao_auth_info_id` 仅在 > 0 时写入;二者缺省时不覆盖已有值 |
| 打印换取 | `app/service/systems/order_print.js` 新增 `resolveOmsDouyinPrintParamsMap`:按 `cai_niao_auth_info_id` 归集,每个店铺只调一次 `deliveryorder.getprintdata`(请求体 `{ printHistoryIds: [printHistoryId] }`),结果按店铺缓存 300 秒(params 有效期 600 秒) |
| 兜底 | 无 `cai_niao_auth_info_id`/`print_history_id`、或 OMS 换取失败时,回退原有菠萝派 `logistics.getShopKey` 临时 key 逻辑 |
| appKey 解析 | 优先订单 `from_key`,缺失时按「货主+仓库」反查 `api_app`(与取号链路一致) |
| 取号报文缓存 | 新增 `oms:waybill:request:latest` / `oms:waybill:response:latest` / `oms:waybill:response:<request_id>`(TTL 24h,超 256KB 按字段脱敏,保留字段名与结构) |
| 验证 | `test/verify_oms_douyin_print_params.js`(23 例)、`test/verify_oms_waybill_payload_cache.js`(24 例)、`test/verify_oms_waybill_platform_code.js`(19 例)全部通过 |
### 3. 与文档 §4.7.1 的偏差(请 OMS 侧确认)
文档 §4.7.1 明确「`params` 是逐张面单的,不能拿 A 单的 `params` 去打 B 单」。
WMS 按本次需求实现为**按店铺分组、组内共用一份 `params`**(每组只用其中一个 `print_history_id` 换取)。
- 如果平台侧确实要求逐单换取,WMS 只需把 `resolveOmsDouyinPrintParamsMap` 的归集键
由 `cai_niao_auth_info_id` 改为 `print_history_id`(改动点集中在一个方法内)。
- 请 OMS 侧确认:同店铺不同运单的 `params` 是否可以共用。
### 4. 待执行(需确认)
生产 `wms_order_express` 当前约 79.5 万行 / ibd 14.6GB,生产 MySQL 5.7.44
(`ADD COLUMN` 需重建表,`/www` 剩余 24GB)。开发库已执行并通过校验,生产尚未执行。
wms/

View File

@ -124,6 +124,31 @@ function parsePrintData(printData) {
}
}
/**
* 从 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` 只是**回放那次打印时的签名**,不会重新签发,
* 所以隔一段时间再取一定是过期的;要新签名只能重新走「原单号打印」。
* @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
@ -341,10 +366,12 @@ async function fetchGroup(ctx, { principalId, memo, group }) {
results.push({ waybill_code: item.waybillCode, success: false, message: '平台的打印数据里没有 params(access_token 串)' });
continue;
}
const paramsTimestamp = pickParamsTimestamp(parsed.params);
const expired = isParamsExpired(paramsTimestamp);
results.push({
waybill_code: item.waybillCode,
success: true,
message: 'ok',
message: expired ? `平台返回的是打印记录里的原签名(${paramsTimestamp}),已超过 10 分钟有效期;要新签名需走「原单号打印」` : 'ok',
print_history_id: row.print_history_id,
template_id: row.template_id,
cai_niao_auth_info_id: item.record.cai_niao_auth_info_id == null ? null : Number(item.record.cai_niao_auth_info_id),
@ -352,6 +379,9 @@ async function fetchGroup(ctx, { principalId, memo, group }) {
expires_in: PRINT_DATA_TTL_SECONDS,
// 打印端要的就是这串:access_token=...&app_key=...&method=logistics.getShopKey&...&sign=...
params: parsed.params,
// 签名时间与是否过期:LoadPrintData 只回放历史签名,不会重签
params_timestamp: paramsTimestamp,
params_expired: expired,
template_url: parsed.template_url,
});
}
@ -366,4 +396,6 @@ module.exports = {
parsePrintHistoryIds,
pickPrintHistory,
parsePrintData,
pickParamsTimestamp,
isParamsExpired,
};

View File

@ -272,11 +272,14 @@ WaybillCodeCreateDate='2026-11-04 08:20:37'
- **printHistoryId 不在「面单数据」里**(实测:`PrintDataJson.id = null`、`printDataJson.printHistoryIds = null`,
`WaybillCode[]` 里也没有该字段),只在响应顶层:取号是 `Data.PrintHistoryIds[].Id`,
回捞打印数据是 `Data[].ID`(实测 `10000078656212`,number)。要拿它只能从这两个顶层字段取。
- **打印数据(params)只有 10 分钟有效期**:取号返回的 `printinfo` 不能长期保存着用,WMS 真正打印前必须重新拉一次
`POST /PrintHistory/LoadPrintData?token=&dbname=<取号命中的分区>`,表单 `printHistoryIds[]=<Id>&IsCustomerOrder=false&FxPageType=1`;
响应 `Data[0].PrintDataJson` 就是新的 params(实测 7888 字符,`id/sendContent/printDataJson`)。
- **打印数据(params)只有 10 分钟有效期**:`contents[].params` 是平台在**打印那一刻**签发的
(`access_token=…&method=logistics.getShopKey&timestamp=…&sign=…`,`timestamp` = 该打印记录的 `CreateDate`)。
⚠️ 实测确认:`POST /PrintHistory/LoadPrintData` **只是回放那次打印的签名,不会重新签发**
(换 `FxPageType=1/2`、加 `IsRePrint` / `IsRefresh` 都返回同一个 `timestamp`/`sign`),
所以隔一段时间再取一定是过期的 —— 要新签名只能重新走「原单号打印」(`ExpressPrint` 复用已有运单号,不消耗面单),
这条待与平台侧确认后接入(见 `WMS-OMS-取号对接.md` §4.7.1 的说明)。
因此取号记录里同时落了 `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`,