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:
parent
82879cdef5
commit
82ebe7e022
@ -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/
|
||||
|
||||
@ -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,
|
||||
};
|
||||
|
||||
@ -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×tamp=…&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`,
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user