diff --git a/WMS-OMS-取号对接.md b/WMS-OMS-取号对接.md index ad80271..8c67fae 100644 --- a/WMS-OMS-取号对接.md +++ b/WMS-OMS-取号对接.md @@ -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/ \ No newline at end of file +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:`(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/ diff --git a/backend/app/lib/waybillPrintData.js b/backend/app/lib/waybillPrintData.js index 7f901ba..d06699d 100644 --- a/backend/app/lib/waybillPrintData.js +++ b/backend/app/lib/waybillPrintData.js @@ -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, }; diff --git a/店管家取号-旧系统提取.md b/店管家取号-旧系统提取.md index 8305774..273f5f0 100644 --- a/店管家取号-旧系统提取.md +++ b/店管家取号-旧系统提取.md @@ -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[]=&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`,