oms/WMS-OMS-取号对接.md
liufumingren b7010921c9 feat(export): 订单导出区分范围与内容,并带出序列号数量/列表
- 导出范围:支持 ids(导出选中,最多 500 条)或按筛选条件全部
- 导出内容:export_mode=order(默认,一行一个订单,不含明细)/ item(一行一个商品明细,订单字段重复)
- 订单导出新增「序列号数量」「序列号列表」列;含明细时按行号取该行 SN(行号为空按商品编码兜底)
- 前端导出按钮:订单类型弹窗选择「导出选中 / 按条件全部」与「订单行 / 含明细」,其余类型行为不变
- 导出任务页隐藏 ids 这类由页面自动携带的筛选字段(filters[].hidden)
- 补充 exportDefs 订单导出单测(两种模式、选中、权限、参数顺序)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-14 00:48:56 +08:00

80 KiB
Raw Permalink Blame History

OMS ↔ WMS 取号联调说明(现状 / 契约 / 待办)

文档用途:作为 OMS 侧与 WMS 侧 agent 对接取号链路的沟通基线。 核对时间:2026-11-04,OMS 仓库 D:\oms(后端 Egg.js + Sequelize + MySQL,前端 Vue3),WMS 仓库 D:\wms(Egg.js)。 文中数据快照来自本地开发库,生产以实际查询为准(文末附核对 SQL)。

规则说明:每轮工作内容以/oms或wms开头oms或wms/结尾,完成当前内容后汇报写入文档结尾,以记录或保持沟通

/oms

1. 结论速览(TL;DR)

能力 OMS 侧 WMS 侧 说明
订单推送 deliveryorder.create + need_oms_waybill ✅ 已完成 ✅ 已识别 OMS 按平台配置自动下发,WMS 已能把这类订单分流到 waiting_oms
取号入站方法 deliveryorder.getwaybill ✅ 已完成 ❌ 未接通 OMS 可批量回取号并逐单返回结果
打印前换新 params deliveryorder.getprintdata ✅ 已完成 ❌ 未接通 平台打印数据只有 10 分钟有效期,打印前按「店铺标识 + 运单号」换新的(只读,不消耗面单)
WMS 侧「oms 取号平台」实现 — ❌ 缺失 express_platform.js 只有 polyapi / cainiao / pdd
WMS 侧消费 waiting_oms — ❌ 缺失 目前 waiting_oms 是终态,不会被再次处理
店管家(dgj)真实取号调用 ✅ 已实现(默认开启) — dgj.fetchWaybillNo() 已按旧系统流程实现,平台无运单号时会真实取号(消耗面单);可用 DGJ_WAYBILL_ENABLE=0 临时关闭

当前为真实校验模式:deliveryorder.getwaybill 会真实回读订单(单号/主体/仓库/状态/平台/店铺/打单账号/平台配置/编码绑定), 按「账号 + 平台 + 编码」定位快递接口;取不到接口时直接返回绑定入口与操作步骤(详见 §4.6)。 店管家真实取号已按旧系统流程实现(见 店管家取号-旧系统提取.md):回读平台订单行 → 已发货拦截 → 模板校验 → ExpressPrint 取号并返回面单打印数据。每次调用都会真实向平台取号(不判断平台已有运单号), 是否算重复调用只由幂等表按 request_id 决定;需要只读联调时设 DGJ_WAYBILL_ENABLE=0 关闭。 当前风险:平台配置 external_print_platforms.fetch_waybill_no 对 dgj 已置为 1,所以新推送的外部打单订单会带 need_oms_waybill=1。但 WMS 端还没人调用 OMS 取号、OMS 端 dgj 取号也没实现,这些订单推送后会在 WMS 停在 waiting_oms 且拿不到运单号。


2. 链路总览

         ① 推送(已有)
OMS ─────────────────────────────► WMS   POST {warehouse_apis.base_url}
    deliveryorder.create                 ?method=deliveryorder.create&app_key=...&timestamp=...&sign=...
    根节点 need_oms_waybill=0|1

         ② 回取号(本次要打通,WMS 发起)
WMS ─────────────────────────────► OMS   POST {api_app.callback_url} → OMS /openapi
    deliveryorder.getwaybill             ?method=deliveryorder.getwaybill&app_key=...&timestamp=...&sign=...&request_id=...
    body: { orders: [{ deliveryOrderCode, expressCode }] }

         ③ 发货确认(已有)
WMS ─────────────────────────────► OMS   deliveryorder.confirm
  • ②③ 都由 WMS 主动调 OMS 的同一个入口 /openapi,用同一套 app_key/app_secret 与签名算法。
  • OMS 侧按 app_key 定位「主体 + 仓库」(warehouse_apis),因此 WMS 用哪个 app_key 调,就只会操作该主体该仓库的单据。

3. 鉴权与签名(两侧完全一致,务必对齐)

3.1 请求形态

POST {OMS_BASE}/openapi?method=deliveryorder.getwaybill&v=1.0&timestamp=1750000000&app_key=xxx&sign=abc&request_id=uuid
Content-Type: application/json

{ "orders": [ { "deliveryOrderCode": "XK202611040001", "expressCode": "ZTO" } ] }
  • 系统参数一律走 query,业务参数走 JSON body。
  • timestamp 为 秒级 时间戳,OMS 校验窗口 ±600 秒(毫秒时间戳会自动换算)。
  • 未传 request_id 就不启用幂等(不建议)。

3.2 签名算法

bodySign       = md5( stableStringify(body) )                    # 小写 hex
canonicalQuery = query 的 key 升序拼接 "k=v&k2=v2",忽略 sign/signature 与 undefined 值
sign           = md5( canonicalQuery + app_secret + bodySign )    # 小写 hex

stableStringify:对象 key 递归升序;数组保序;undefined 视为空串。

WMS 侧已有实现可直接复用:D:\wms\app\lib\api_sign.js(signRequest)、app/service/openapi/callback.js#signCallback。 OMS 侧实现:D:\oms\backend\app\lib\wms\sign.js。

⚠️ body 参与签名的是解析后的对象,不是原始 JSON 字符串;两边都必须用稳定序列化,否则 query 顺序/空格差异会导致验签失败。

3.3 app_key 两侧对应关系

方向 调用方取什么 被调方校验什么
OMS → WMS OMS warehouse_apis.app_key / app_secret WMS api_app.self_app_key / self_app_secret
WMS → OMS WMS api_app.self_app_key / self_app_secret + api_app.callback_url OMS warehouse_apis.app_key / app_secret(且 status=1)

结论:同一条 api_app 记录同时承担两个方向,只需保证:

  1. WMS api_app 的 self_app_key / self_app_secret = OMS 某条 warehouse_apis 的 app_key / app_secret;
  2. WMS api_app.callback_url 指向 OMS 的 /openapi(例:https://api.example.com/openapi,不要带 query);
  3. OMS 该条 warehouse_apis.status = 1,principal_id / warehouse_id 指向要操作的仓库。

OMS 的仓库接口配置入口:前端「仓库 → 接口配置」(frontend/src/views/ExternalApi/Index.vue,表 warehouse_apis)。

3.4 响应结构(奇门风格)

// 成功
{ "flag": "success", "code": 1, "message": "ok", "data": { }, "timestamp": 1750000000 }
// 失败
{ "flag": "failure", "code": 400, "message": "参数缺失或错误: sign", "data": null, "timestamp": 1750000000 }
HTTP / code 场景
200 / 1 业务处理成功(批量逐单失败也返回 200/1,逐单结果在 data.results)
400 参数缺失、时间戳过期、签名错误、request_id 报文不一致
401 app_key 不存在/被禁用/未配置密钥
409 同一 request_id 正在处理中(调用方稍后重试)
500 服务端异常

4. 接口契约:deliveryorder.getwaybill

4.1 请求

支持以下任一种写法(会兼容 {request:{...}} / {data:{...}} 包装):

// 推荐
{ "orders": [ { "deliveryOrderCode": "XK202611040001", "expressCode": "ZTO" } ] }
// 也支持
{ "deliveryOrders": { "deliveryOrder": [ ] } }
{ "list": [ ] }
{ "request": { "orders": [ ] } }

字段:

字段 必填 说明
deliveryOrderCode ✅ OMS 订单号(= 当初 deliveryorder.create 里的 deliveryOrderCode)。也兼容 outBizCode / orderCode,以及放在 deliveryOrder 对象内
expressCode ✅ 本次要取的快递编码。也兼容 express_code / logisticsCode / logistics_code / express.code
packageIndex ❌ 包裹/子单序号(0 基),仅用于日志留痕。也兼容 package_index / packageNo / package_no / waybillIndex,以及 WMS 原生的 businessKey / business_key(1 基,自动转 0 基)。每次取号都会分配一个新号(店管家「新单号打印」口径),所以 WMS 按包裹各调一次即可,序号不需要下发给平台

约束:

  • 单次最多 100 单,超限整批失败:单次最多取号 100 单。
  • 快递编码只以报文为准,OMS 不读取订单上已设置的 logistics_code。
  • OMS 内部并发 4 逐单调用平台,返回结果顺序与请求一致。
  • 每单都会真实向打单平台取号,不判断平台订单上是否已有运单号(店管家 LastWaybillCode 只用于事后对比是否换号)。 也就是说:重复调用与否只由幂等表(request_id)决定——清掉幂等记录或换 request_id 就会再取一次新号,并消耗一张面单。

4.2 响应

{
  "flag": "success",
  "code": 1,
  "message": "ok",
  "data": {
    "total": 2,
    "success": 1,
    "failed": 1,
    "results": [
      {
        "delivery_order_code": "XK202611040001",
        "success": true,
        "message": "ok",
        "waybill_source": "express_print",
        "express_code": "ZTO",
        "platform_code": "TB",
        "waybill_code": "78812345678901",
        "waybill_codes": ["78812345678901"],
        "package_index": 0,
        "cai_niao_auth_info_id": 364375,
        "printinfo": "{\"encryptedData\":\"AES:rU904…\",\"signature\":\"MD:xNFh…\",\"ver\":\"waybill_print_secret_version_1\",\"templateURL\":\"http://cloudprint.cainiao.com/template/standard/304351\"}",
        "signature": "MD:xNFh…",
        "encryptprintinfo": "AES:rU904…",
        "key": "",
        "ver": "waybill_print_secret_version_1",
        "print_history_ids": [
          { "id": "10000078656002", "pid": "3316997317085033076", "waybill_code": "78812345678901", "batch_index": 1 }
        ],
        "print_history_id": "10000078656002"
      },
      {
        "delivery_order_code": "XK202611040002",
        "success": false,
        "message": "平台TB(淘宝)快递YTO(圆通速递)在账号15197817068下未绑定到快递接口,请到 OMS 店铺管理→外部打单平台→快递接口 查看绑定对应的快递接口"
      }
    ]
  },
  "timestamp": 1750000000
}

逐单结果字段:

字段 出现条件 说明
delivery_order_code 始终 回显单号(取不到单号时为空串)
success 始终 是否取号成功
message 始终 ok 或失败原因(见 4.4);若平台返回的号码与订单行上原有的 LastWaybillCode 相同,会提示「本次调用平台取号,但平台仍返回原运单号 X」
waybill_source 成功 现阶段固定为 express_print(本次向打单平台取号,不再复用平台已有运单号)
express_code 成功 回显本次快递编码
platform_code 成功 订单来源平台(OMS 预设编码,如 TB/PDD/DYXD)
waybill_code 成功 主运单号
waybill_codes 成功 全部运单号(当前每次取号只对应 1 个包裹,恒为单元素)
package_index 成功 本次取号对应的包裹序号(0 基),回显便于核对「这个号是哪个包裹的」
cai_niao_auth_info_id 成功 菜鸟授权网点ID(模板绑定的 CaiNiaoAuthInfoId,如视频号 6890457、淘宝 364375/393235);同平台不同授权网点取值不同,WMS 需要按网点归集/对账时用它,取不到为 null
printinfo 成功 面单打印数据,打单平台原样返回:店管家取 Data.PrintDataList.task.documents[].printInfo(base64 的 URL-encoded JSON);快手取 documents[].contents[0].encryptedData(快手该单据的 printInfo 为空);菜鸟系(TB/TM/TGC/1688)回拼整包 JSON {"encryptedData","signature","ver","templateURL"}(模板地址取 contents[0].templateURL,菜鸟云打印必需)。WMS 落 order_express.printinfo,打印时原样塞进 task.printInfo,不要解码
signature 成功 面单签名,取 documents[].contents[0].signature;视频号自定义模板平台不返回 contents,此时为空串
encryptprintinfo 成功 加密打印数据:其它平台取 contents[0].encryptedData;快手取 contents[0].key(与菠萝派口径一致,WMS 快手打印的 key 参数)
key 成功 快手逐单加密密钥(base64,约 172 字符,逐单不同),取 contents[0].key;其余平台为空串
ver 成功 打印数据版本,取 contents[0].ver(无则为空串)
print_history_ids 成功 打印记录ID(店管家 Data.PrintHistoryIds[]):[{ id, pid, waybill_code, batch_index }],每张面单一条,WMS 自行落库。id 即 printHistoryId,WaybillCode 与 waybill_codes 一一对应;平台不会把它放进面单数据(printinfo 里对应字段恒为 null)
print_history_id 成功 第一张面单的打印记录ID(print_history_ids[0].id 的便捷值,多包裹时以数组为准)

取号结果不回写 OMS 订单表(现阶段取号与订单表不做关联),运单号与打印数据只在响应里返回,由 WMS 自行落单。 WMS 仍需落自己的 order_express(waybill_code + printinfo + signature + encryptprintinfo + ver + cai_niao_auth_info_id + print_history_ids,快手另有 key)/ 队列状态,不要依赖 OMS 的库。 每次取号的平台原始返回都会写进 OMS 的 waybill_fetch_records(见 §4.7),出问题可直接查表对账,不必再让 WMS 重放报文。

同一包裹重复取号会拿到新号:店管家「新单号打印」口径是每次分配一个新号(WaybillCodePid 第二段自增), 所以重试必须复用同一个 request_id,否则会多耗一张面单。包裹序号由 OMS 从 deliveryOrderCode 尾部 _N 推导 或由报文 packageIndex / businessKey 指定,仅用于留痕。

4.3 幂等(请求级去重,只回放成功结果)

request_id 来源优先级:query.request_id → query.requestId → Header X-Request-Id → body.request_id → body.requestId → body.request.request_id(最长 100 字符)。

唯一键:(app_key, method, request_id)。

场景 OMS 行为
首次请求 正常处理;成功则保存完整响应
已完成且成功 + 相同报文 直接回放当时的完整响应(含逐单结果),不再调平台
已完成但失败 / 批量中任一单失败 不保存、释放该 request_id;下次同 request_id 会重新执行
相同 request_id + 报文不同 400:request_id 已被使用且报文不一致,请更换 request_id 后重试
相同 request_id + 仍在处理 409:相同 request_id 的请求正在处理中,请稍后重试
处理中超过 30 分钟(进程异常退出) 允许接管重跑
记录保留 7 天(每日 02:00 清理,OPENAPI_IDEMPOTENCY_KEEP_DAYS 可调)

语义要点:请求幂等 ≠ 取号幂等

  • 请求幂等(本表):只保证「同一批成功的结果不重复执行」;失败结果允许用同一 request_id 重试,不会被锁死。
  • 取号不与订单表关联:不读也不写订单上的 express_code,重复调用会再次向平台取号(需重测时无需清理订单数据)。
  • 因此 WMS 可以放心用稳定的 request_id 做自动重试:先成功的单不会重复取号,之前失败的单会被重新处理。
  • 重测取号时要清这张表(成功结果会回放):DELETE FROM openapi_request_idempotency WHERE method='deliveryorder.getwaybill',或换个 request_id。订单表已不参与幂等,无需清理 express_code。
  • 清表后就会真正向平台再取一次号(会消耗面单);取号记录表 waybill_fetch_records 里能看到每次的 waybill_source=express_print 与平台返回。
  • ⚠️ 反过来要注意:批量里只要有一单失败,整批的 request_id 就不会被锁。用同一 request_id 重试会整批重跑,已成功的单会再取一次号(多消耗面单)。生产上建议按「单」或小批提交,减少重复取号。

4.4 逐单失败原因全表(OMS 侧)

message 触发条件 WMS 建议处理
缺少发货单号(deliveryOrderCode / outBizCode) 报文没有单号 修报文,不重试
缺少快递编码(expressCode) 报文没有编码 修报文,不重试
未找到发货单:{code} OMS 查不到该单(或不属于该主体) 不重试,人工核查
单据 {code} 不属于当前 app_key 对应的仓库 仓库不匹配 不重试,检查 app_key
订单已取消,取号失败 订单状态 canceled 不重试,队列置失败
订单已作废,取号失败 void 不重试
订单已归档,取号失败 history 不重试
订单已配送,取号失败 订单状态已是 delivery 不重试
订单已完成,取号失败 老模型 status=4 不重试
订单缺少来源平台,无法匹配快递接口 订单没有 source_platform_code 不重试
订单未关联店铺,无法确定打单账号 订单无 shop_id 不重试
订单未关联外部打单账号,无法取号:… 店铺不是 type=2(外部打单商家)或无 external_print_account_id 检查店铺类型/账号同步
外部打单账号或平台配置不存在:… 账号/平台被删或跨主体 检查账号与平台配置
平台X(中文名)快递Y(中文名)在账号Z下未绑定到快递接口… 该账号该平台该编码没有唯一绑定模板(含重复绑定) 不重试;按提示到 OMS 店铺管理→外部打单平台→快递接口 绑定
快递编码X不存在(…均无此编码)… 系统快递公司字典与自定义快递编码字典都没有该编码 不重试;到 OMS 系统管理→自定义快递编码 新增后再试
快递编码X已停用… 编码在字典里但 status=0 到 OMS 系统管理→自定义快递编码 启用后再试
打单平台「X」未开启回平台取号:… 平台 fetch_waybill_no != 1 先改平台配置
店管家真实取号已关闭(DGJ_WAYBILL_ENABLE=0):… 显式关闭了真实取号,且平台侧还没有运单号 去掉该环境变量后重试
店管家未找到订单:系统编号 X(域名 Y) 订单不在该平台的订单域名/分区,或系统编号不对 检查平台域名(视频号/淘宝走 fxali、抖店 fxdd)、分区 dbname
店管家面单余额不足,请充值后再取号 模板余额 < 本次张数 充值后重试
订单在店管家已发货或已终结(ErpState=sended,平台运单号 X…),取号失败:请作废或取消该单 平台侧已发货/已终结(常见于平台先发货、OMS 后审核) 不重试;OMS 作废/取消该单,WMS 同步取消

取号失败提示都带操作指引,示例(真实返回):

平台SPH(视频号)快递STO(申通快递)在账号15197817068下未绑定到快递接口,请到 OMS 店铺管理→外部打单平台→快递接口 查看绑定对应的快递接口
请在 OMS「外部打单平台 → 快递接口」中为该模板绑定编码 STO,同一账号同平台下一个编码只能绑定一个模板

提示的三种形态:①该平台没有模板 → 提示先去「从平台同步数据」;②有同快递公司的模板但未绑定 → 直接点名模板;③模板快递公司不匹配 → 列出该平台现有模板及其快递公司编码,提示改用正确编码。 | 平台未返回运单号 | 平台调用成功但没解析到单号 | 可重试(谨慎) | | 接口错误: ... / 平台异常 | 平台接口异常 | 可有限重试 |

注意:不复用任何已有运单号。 既不读 OMS 订单上的 express_code,也不判断店管家订单行上的 LastWaybillCode; 每次请求都真实调用平台取号(消耗面单),去重只靠幂等表的 request_id。

4.5 快递接口定位规则(OMS 内部,用于理解失败原因)

订单.source_platform_code  ──┐
订单.shop_id → shops(type=2) ─┼─► external_print_accounts(打单账号)
                             │        └─► external_print_platforms(平台配置 fetch_waybill_no)
WMS 传入的 expressCode ───────┴─► external_print_express_interfaces
                                     where account_id + platform_code + custom_code + status=1
                                     (必须唯一命中,重复绑定视为未命中)
  • 不按店铺区分:店管家里的「店铺」是商家,同一账号下的快递接口共用。
  • 同一账号 + 同一平台下,一个快递编码只能绑定一个模板;不同平台可以重复(互不影响)。
  • 平台字典 external_print_platforms.fetch_waybill_no 目前由迁移/开发者维护,前端只读。

4.6 校验顺序与「取不到接口」的提示(真实模式)

getwaybill 的逐单校验顺序(任一不通过即返回该单失败,不影响其它单):

  1. 报文单号 / 快递编码齐全;
  2. 按 deliveryOrderCode 回读订单(order_index.order_no,回退老发货单 order_deliveries.delivery_order_code),并按 app_key 校验主体与仓库;
  3. 订单状态:canceled / void / history / delivery 直接失败(不读也不写订单上的运单号);
  4. 订单来源平台 source_platform_code;
  5. 店铺 → shops.type=2 → external_print_account_id(打单账号);
  6. 打单账号 + 平台配置(fetch_waybill_no);
  7. 按「账号 + 平台 + WMS 传入编码」定位快递接口 → 找不到时返回带入口与步骤的提示;
  8. 调用平台取号(当前店管家未实现 → 返回「店管家取号接口尚未接入」)。

取不到快递接口时,返回一句话的简短提示(平台/快递优先带中文名,查不到名称时只显示编码),真实示例:

平台SPH(视频号)快递STO(申通快递)在账号15197817068下未绑定到快递接口,请到 OMS 店铺管理→外部打单平台→快递接口 查看绑定对应的快递接口

附加说明只在必要时出现(很短的括号补充):

场景 返回
快递编码在系统 + 自定义字典里都不存在 快递编码XYZ999不存在(系统快递编码与自定义快递编码均无此编码),请到 OMS 系统管理→自定义快递编码 新增后再重试
快递编码已停用 快递编码XYZ999已停用,请到 OMS 系统管理→自定义快递编码 启用后再重试
该平台没有任何模板 主提示 + (该平台暂无面单模板,请先点「从平台同步数据」)
该平台没有该快递公司的模板 主提示 + (该平台暂无对应快递公司的模板,请先点「从平台同步数据」)
同一编码被多个模板绑定 整句换成「…下绑定了 N 个快递接口,请到 OMS 店铺管理→外部打单平台→快递接口 只保留一个后重试」

判定顺序:先按「账号 + 平台 + 编码」找绑定,命中就直接取号;找不到才校验编码是否存在(避免历史绑定了字典外编码的单据无法取号)。

已实测(本地真实 HTTP + 真实签名,订单 dgj-10000266092590 / 平台 SPH): 编码 STO → 未绑定提示;编码 XYZ999 → 「编码不存在」;停用编码 → 「已停用」。 这些失败结果都不占用 request_id,WMS 可直接重试。

4.7 取号记录(waybill_fetch_records)——平台返回全部留存

取号不只是拿单号:店管家 ExpressPrint 会同时返回面单打印数据(PrintInfo)与签名,WMS 打印时必须用它们。 因此 OMS 会把每次取号的平台原始返回整条落库,不写订单表,只做留痕。

写入时机:逐单处理中一旦定位到打单账号(即真正接触平台)就写一条,成功 / 失败都写。

字段 说明
principal_id / warehouse_id 来自 app_key 的主体与仓库
request_id 调用方 request_id,同一次批量取号共用,便于按批串起来
delivery_order_code OMS 发货单号
express_code / platform_code 本次快递编码 / 订单来源平台
account_id / template_id 打单账号 / 面单模板
status 1 成功、0 失败
waybill_source 现阶段固定 express_print(每次请求都真实向平台取号)
waybill_code / waybill_codes 主运单号 / 全部运单号(JSON 数组)
printinfo / signature 面单打印数据与签名(平台原样,透传给 WMS 的同一份)
raw_response 平台原始返回 JSON(含 Data.WaybillCode[]、失败时的 Message/ErrorCode)
error_message 失败原因(与响应里的 message 一致)

排查用的常用 SQL:

-- 某单最近 5 次取号(每次的号码与平台原始返回)
SELECT id, created_at, status, waybill_source, waybill_code, error_message
FROM waybill_fetch_records WHERE delivery_order_code = 'dgj-10000267890142_1'
ORDER BY id DESC LIMIT 5;

-- 看某次真取号的面单打印数据(WMS 该怎么落库、打印时该传什么)
SELECT waybill_code, length(printinfo) AS printinfo_len, signature, raw_response
FROM waybill_fetch_records WHERE delivery_order_code = 'dgj-10000267890142_1' AND status = 1
ORDER BY id DESC LIMIT 1;

-- 按批排查(与 openapi_request_idempotency 的 request_id 对齐)
SELECT * FROM waybill_fetch_records WHERE request_id = 'oms-getwaybill-xxx' ORDER BY id;

WMS 侧对应落库字段建议:order_express.waybill_code ← waybill_code,order_express.printinfo ← printinfo, order_express.signature ← signature,status=1;打印时把 printinfo 原样交给打印服务即可,不要自己拼格式。

⚠️ printinfo 是整张面单的打印数据(单张常见几十到几百 KB),批量取号时响应会明显变大: 建议一次批量不超过 20 单,或让 WMS 逐单/小批取号,避免响应体过大拖慢回调。

4.7.1 ⚠️ printinfo 只有 10 分钟有效期 → 打印前必须换新的

店管家面团单打印数据(params)有效期只有 10 分钟,取号时拿到的 printinfo 不能存着以后慢慢用。 WMS 真正要打印时,调 deliveryorder.getprintdata 换一份新的(OMS 内部走 PrintHistory/LoadPrintData,只读、不消耗面单)。

项 说明
方法 deliveryorder.getprintdata
入参(最简) { "printHistoryId": "10000078656212" } —— 只给一个打印记录ID即可,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, params_timestamp, params_expired, template_url

⚠️ 重要(实测 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 —— 实测平台复用订单已有运单号(不分配新面单、余额 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 索引)。

返回用法(只需要 params):

  • 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 分钟内打完
  • 新鲜度:params_timestamp 是平台签发时间,params_expired 由 OMS 按 10 分钟算出; 本接口走「复用原运单号、重新下发打印数据」,正常应当 params_expired=false。 若为 true 或 success=false 且 message 提到「平台返回了新运单号」,说明平台异常分配了新面单,需人工核对

注意:printHistoryId 由 OMS 保存,不需要 WMS 再存一份(每张面单一条、换号/重打都会新增,存两份必然不一致)。 单条失败原因:未找到该运单号的取号记录(可能不是通过 OMS 取的号) / 取号记录里没有该运单号的打印记录ID(PrintHistoryIds),无法换新的打印数据。

📌 取号响应也会返回 print_history_ids / print_history_id(见 §4.2),WMS 可按需落库; 但打印前换 params 时不要求 WMS 传它 —— 传「caiNiaoAuthInfoIds + waybillCodes」由 OMS 查库即可, 想省一次查库时再直传 printHistoryIds。两者以 OMS 库里的记录为准(换号/重打都会新增打印记录)。

📌 只传一个打印记录ID就够了(实测):{ "printHistoryId": "10000078656212" } → OMS 从自己库里取出该记录对应的域名(platform_host)+ 分区(dbname)+ 打单账号,直接回源 PrintHistory/LoadPrintData 拿新的 params,结果里的 params 就是那串 access_token=…&app_key=…&method=logistics.getShopKey&…&sign=…。 也就是说 WMS 不需要知道域名/分区,店铺标识与运单号也不是必填;一次一张、串行调用即可。

-- 打印前换 params 时 OMS 内部按这条定位(同一个运单号多次取号取最新一条)
SELECT id, delivery_order_code, print_history_ids, cai_niao_auth_info_id, dbname, platform_host
FROM waybill_fetch_records
WHERE principal_id = ? AND status = 1 AND waybill_code = ?
ORDER BY id DESC LIMIT 1;

✅ 验收(2026-11-07 线上):拉取 params 未产生新面单(余额不变),返回原运单号 + 新鲜 params,测试通过。 误分配的 2 张面单已由业务侧回收。


5. 推送侧:need_oms_waybill

5.1 OMS 下发的值

  • 报文位置:deliveryorder.create 的请求根节点,与 deliveryOrder、orderLines 同级:
{ "deliveryOrder": { }, "orderLines": { "orderLine": [] }, "need_oms_waybill": 1 }
  • 取值规则(推送时实时判定,并回写单据):
    • 订单店铺 type = 2(外部打单平台商家)且该账号所属平台 fetch_waybill_no = 1 → 1
    • 其他(手工单、平台店铺、数据库模式店铺)→ 0
  • 平台配置改动不需要重新建单,下一次推送即生效(读缓存,TTL 300 秒;绑定/账号变更会主动失效)。

5.2 WMS 现有行为

  • need_oms_waybill=1 的订单在取号流水线里被跳过本地分配,waybill_allocate_queue 行被置为 waiting_oms(终态,message='等待外部OMS取号')。
  • 相关代码:D:\wms\app\service\systems\express.js(skipped_need_oms_waybill_order_ids)、D:\wms\app\schedule\consume_waybill_allocate_queue.js(约 225~238 行)。

6. WMS 侧改造清单(给 WMS agent)

6.1 新增 oms 取号平台实现

文件:D:\wms\app\service\systems\express_platform.js

  • 分发规则:express.js#dispatchWaybillAsyncPlatform(platformCode, bizcontent) 直接调用 this.service.systems.expressPlatform[request_platform_code](bizcontent);方法不存在会抛 xxx接口未实现。
  • 因此新增方法名必须叫 oms,与 wms_print_platform.request_platform_code = 'oms' 一致。
  • 返回值约定:成功返回 { flag: 'success' }(或 undefined);失败返回 { flag: 'failure', message } 或直接 throw。
  • oms 不要加入 shouldDispatchWaybillAsyncPerOrder() 的逐单列表(保持整批调用,减少 HTTP 次数)。

参考骨架(伪代码,字段名以 WMS 现有 bizcontent.orders 为准):

async oms(bizcontent = {}) {
  const orders = Array.isArray(bizcontent.orders) ? bizcontent.orders : [];
  if (!orders.length) return { flag: 'success' };

  // 1) 组报文:deliveryOrderCode 取 OMS 单号,expressCode 取 WMS 自己的快递编码
  const payload = {
    orders: orders.map(o => ({
      deliveryOrderCode: o.order_info.delivery_order_code || o.delivery_order_code,
      expressCode: o.logistics_code || o.express_code,
    })),
  };

  // 2) 调用 OMS:appKey 取当前打印平台绑定的 api_app.self_app_key
  //    callback_url 必须是 OMS /openapi(sendByAppKey 内部会包成 { request: payload })
  const appKey = /* api_app.self_app_key */ '';
  const result = await this.service.openapi.callback.sendByAppKey({
    appKey,
    event: 'deliveryorder.getwaybill',
    request: payload,
  });
  if (!result.success) throw new Error(result.error || 'OMS 取号调用失败');

  // 3) 解析逐单结果
  const body = result.response || {};
  const results = (body.data && body.data.results) || [];
  const failed = results.filter(r => !r.success);
  const success = results.filter(r => r.success);

  // 4) 回写成功运单号(复用现成方法)
  const successUpdates = success.map(r => {
    const ctxOrder = orders.find(o => (o.order_info.delivery_order_code || o.delivery_order_code) === r.delivery_order_code);
    return {
      warehouse_id: Number(bizcontent.warehouse_id || 0),
      order_id: Number(ctxOrder.order_id),
      business_key: Number(ctxOrder.business_key) || 1,
      waybill_code: r.waybill_code,
      orderExpressValues: {
        waybill_code: r.waybill_code,
        logistics_code: r.express_code,
        platform_code: r.platform_code,
        create_at: new Date(),
        delivery_order_code: r.delivery_order_code,
        status: 1,
        retry_count: 0,
      },
      orderDeliveryValues: { post_status: 'fin', order_flag: '' },
    };
  });
  await this.persistWaybillSuccessUpdates(successUpdates, orders);

  // 5) 失败处理:按 message 区分「不可重试」与「可重试」
  if (failed.length) {
    throw new Error(failed.map(f => `${f.delivery_order_code}: ${f.message}`).join('; '));
  }
  return { flag: 'success' };
}

persistWaybillSuccessUpdates(successUpdates, orders) 的必需字段:warehouse_id / order_id / business_key、orderExpressValues(至少 waybill_code、status:1)。 参考已有实现:express_platform.js 的 KS / DY / pdd 分支。

6.2 平台配置

  • wms_print_platform:把对应打印平台的 request_platform_code 设为 oms(该字段决定分发到哪个方法)。
  • 该平台关联的 api_app(self_app_key / self_app_secret / callback_url)必须是 OMS 侧 warehouse_apis 的同一套凭据,callback_url = OMS /openapi。
  • 如果 WMS 回调调试页要展示该方法,可同步补 methods/openapi_callback.json / callbackRegistry.js(仅文档用,非必需)。

6.3 消费 waiting_oms

文件:D:\wms\app\schedule\consume_waybill_allocate_queue.js

现状:waitingRows 直接 updateQueueRowsStatus(..., 'waiting_oms', '等待外部OMS取号'),之后就没人处理。

建议改成:

  1. 组内先按 warehouse_id + store_id 分组(已有);
  2. 把 waitingRows 对应的 order_id → delivery_order_code 查出来(order_delivery.delivery_order_code),按 ≤100/批 切分(OMS 硬上限);
  3. 调 OMS(走 dispatchWaybillAsyncPlatform('oms', ...) 或直接调 sendByAppKey);
  4. 结果落地:
    • 成功 → order_express 写入(见 6.1),队列行置 done;
    • 失败:
      • 不可重试类(取消/作废/归档/未绑定编码/仓库不符/单据不存在)→ 置 failed,把 message 写进队列行,便于运营看见;
      • 可重试类(网络/OMS 5xx/平台未返回运单号)→ 按现有 markGroupRetryOrFailed 的重试策略处理;
  5. 重试必须复用同一 request_id(建议 request_id = oms-getwaybill-${queueBatchId},或用队列行 id 拼接的稳定值),否则 OMS 会重新走平台取号(可能重复下单/浪费面单)。

关键取舍:waiting_oms 不应是终态。要么消费后改为 done/failed,要么保持可重试状态——不能让订单静默停在这里。

6.4 可观测性

  • 建议每批记录:appKey / 批大小 / success / failed / 耗时 / 首个失败原因;
  • 失败信息写 waybill_allocate_queue.message 与订单操作日志(operationLog,operationCode: 'WAYBILL')。

7. OMS 侧待办(我方)

  1. 店管家真实取号:已按旧系统 Dianguanjia.php 提取并实现(见 店管家取号-旧系统提取.md)。 默认开启真实取号(会消耗面单,DGJ_WAYBILL_ENABLE=0 可关闭);首次使用前建议按该文档 §7 核对响应字段。
  2. 打印数据回传:已实现——逐单结果回传 printinfo / signature,并落 waybill_fetch_records(见 §4.7)。
  3. 多包裹 / 拆单取号(已跑通):店管家用 PrintMethod=NewPrint + IsIgnoreWaybillRepeat=false 分配新号, 每次调用 pid 第二段自增(63274907ebce8f6b_1_1 → _2_1 → _3_1),实测连续 3 次均拿到不同运单号。 WMS 按包裹各调一次即可;多一次调用 = 多一张面单,重试必须复用 request_id。 详见 店管家取号-旧系统提取.md §4.2.4。
  4. 平台字典维护:external_print_platforms.fetch_waybill_no 由迁移维护(当前 dgj = 1)。如需前端可配,另开需求。
  5. 生产 app_key/callback_url:需要与 WMS 对齐生产环境的 warehouse_apis 与 api_app 记录。

8. 当前数据现状(本地开发库,2026-11-04)

对象 现状
仓库 4 个(WH2609111438491570 科创仓 等,均启用)
warehouse_apis 1 条:主体 5 / 仓库 1(科创仓)/ type=qimen / base_url=http://127.0.0.1:6060/openapi / app_key 前缀 WMSD08… / app_secret 已配置(64) / 启用
外部打单平台 1 条:dgj(店管家,dgjapp.com),fetch_waybill_no = 1,启用
外部打单账号 1 条(id=1,主体 5,已登录)
type=2 店铺 5 个(均挂账号 1)
快递接口模板 29 条全部有效;仅 2 条绑定了快递编码;覆盖平台 TB 10 / XHS 5 / DYXD 4 / JD 3 / PDD 3 / KS 2 / SPH 2
自定义快递编码 0 条
订单量 待审核 22 / 委外中 5 / 配送 3;老发货单 5
幂等表 已建(openapi_request_idempotency)
取号记录表 已建(waybill_fetch_records,存平台原始返回 + printinfo / signature)

结论:29 个模板里只有 2 个绑了编码,所以除这 2 个编码外,其余取号都会返回「…下未绑定到快递接口…」。联调前先在 OMS「外部打单平台 → 快递接口」把要测的编码(如 TB + ZTO)绑定好。

8.1 WMS 实测记录(2026-11-04 06:13~06:18)

WMS 已成功调通 OMS deliveryorder.getwaybill,共 6 次请求(1 次真实执行 + 5 次幂等回放,request_id 相同):

{"request":{"orders":[{"deliveryOrderCode":"dgj-10000266092590","expressCode":"STO"}],
            "request_id":"oms-getwaybill-db385b87054379228b1d9c52fc1d7c6a"}}
检查项 结果
app_key / 签名 / 时间戳 ✅ 通过,HTTP 200 flag=success
报文结构 ✅ request.orders[].deliveryOrderCode / expressCode 均被正确解析并回显
幂等 ✅ 首笔 46ms,后续 2~12ms 回放;响应 timestamp 恒等于首笔
订单 ✅ dgj-10000266092590(订单 id 271,状态 outsourcing,need_oms_waybill=1)
来源平台 SPH(视频号),店铺 18「东莞业思勤贸易」→ 打单账号 1(店管家)
编码绑定 ❌ SPH 平台没有任何编码绑定(已绑定仅 TB + POSTB、TB + ZTKY)

真实路径验证结果:

STO  → 平台SPH(视频号)快递STO(申通快递)在账号15197817068下未绑定到快递接口,请到 OMS 店铺管理→外部打单平台→快递接口 查看绑定对应的快递接口…
ZTKY → 平台SPH(视频号)快递ZTKY在账号15197817068下未绑定到快递接口,…(已绑定的 TB 编码同样匹配不到 SPH,平台筛选生效)

视频号现有模板:17 / 12411097 / 【视频号】韵达一联3 / YUNDA、29 / 10824270 / 【视频号】申通一联1 / STO。 绑定 SPH + STO 即可进入取号流程(随后会停在 dgj 取号未实现)。

生产核对 SQL(只读):

-- 平台开关
SELECT id, code, name, fetch_waybill_no, status FROM external_print_platforms;
-- 打单账号与店铺
SELECT id, principal_id, platform_id, account, login_status FROM external_print_accounts;
SELECT id, code, name, type, external_print_account_id FROM shops WHERE type = 2;
-- 绑定情况(bound 为已绑定编码的模板数)
SELECT platform_code, COUNT(*) total, SUM(custom_code IS NOT NULL AND custom_code <> '') bound
FROM external_print_express_interfaces WHERE status = 1 GROUP BY platform_code;
-- 接口配置(务必与 WMS api_app 的 self_app_key/self_app_secret 一致)
SELECT id, principal_id, warehouse_id, name, base_url, app_key, CHAR_LENGTH(app_secret) secret_len, status
FROM warehouse_apis;

9. 联调步骤(建议顺序)

  1. 连通性:WMS 用 sendByAppKey({ appKey, event: 'index.ping', request: {} }) 调 OMS,确认返回 flag=success(先验证签名/时间戳/app_key)。返回体可用于确认凭据与仓库的对应关系:
    { "flag": "success", "code": 1, "message": "ok",
      "data": { "pong": true, "method": "index.ping", "app_key": "WMSD08…",
                "warehouse": { "id": 1, "code": "WH2609111438491570", "name": "科创仓" },
                "principal_id": 5, "api_version": "1.0", "echo": {}, "server_time": 1750000000 },
      "timestamp": 1750000000 }
    
  2. 准备绑定:OMS 侧给至少 1 个淘宝模板绑定编码(例如 ZTO);确认该订单来源平台是 TB。
  3. 推送一单:挑 1 张待审核的外部打单订单 → 审核 → 待推送 → 手动推送;到 WMS 查 order_delivery.need_oms_waybill 应为 1,队列行应为 waiting_oms。
  4. 单笔取号:WMS 直接调 deliveryorder.getwaybill(单条),报文:
    { "orders": [ { "deliveryOrderCode": "<OMS 订单号>", "expressCode": "ZTO" } ] }
    
    当前预期:flag=success,逐单返回真实校验结果。以订单 dgj-10000266092590(平台 SPH)+ 编码 STO 为例,会返回 「平台SPH(视频号)快递STO(申通快递)在账号15197817068下未绑定到快递接口,…」, 按提示绑定后重试即可。
  5. 验证响应:成功时响应里返回 waybill_code / waybill_codes;OMS 订单表不会写入运单号(现阶段不关联)。
  6. 验证幂等:同一 request_id 重复调用,第二次应回放同样报文(日志有「幂等重放」)。
  7. 失败分支:传一个不存在的编码 → 应返回「…下未绑定到快递接口…」;对已取消订单调用 → 应返回「订单已取消,取号失败」。
  8. 批量:一次 20 单(混合成功/失败),确认 WMS 能分别落到 done / failed。

10. 附录:手工构造签名(联调/自测用)

// node sign.js  →  打印可直接用于 curl 的完整 URL
const crypto = require('crypto');

const stable = v => {
  if (v === undefined) return '';
  if (v === null || typeof v !== 'object') return JSON.stringify(v);
  if (Array.isArray(v)) return `[${v.map(stable).join(',')}]`;
  return `{${Object.keys(v).sort().map(k => `${JSON.stringify(k)}:${stable(v[k])}`).join(',')}}`;
};

const base = 'https://api.example.com/openapi';
const secret = '<warehouse_apis.app_secret>';
const query = {
  method: 'deliveryorder.getwaybill',
  v: '1.0',
  timestamp: String(Math.floor(Date.now() / 1000)),
  app_key: '<warehouse_apis.app_key>',
  request_id: 'test-' + Date.now(),          // 可选:带上就启用幂等
};
const body = { orders: [{ deliveryOrderCode: 'XK202611040001', expressCode: 'ZTO' }] };

const canonical = Object.keys(query).sort().map(k => `${k}=${query[k]}`).join('&');
const bodySign = crypto.createHash('md5').update(stable(body), 'utf8').digest('hex');
const sign = crypto.createHash('md5').update(canonical + secret + bodySign, 'utf8').digest('hex');

console.log(`${base}?${canonical}&sign=${sign}`);
console.log(JSON.stringify(body));
curl -X POST '<上面打印的 URL>' -H 'Content-Type: application/json' -d '<上面打印的 JSON>'

值里含特殊字符(空格、&、中文)时,URL 上要 encodeURIComponent,且签名用的 query 值必须与 URL 上实际传的值一致。


11. 风险与注意事项

风险 说明 建议
取号未实现就开着开关 dgj fetch_waybill_no=1 会让订单进 waiting_oms,长期无运单号 要么先补 dgj 取号,要么临时把开关改回 0(改完 5 分钟内生效,或清缓存)
平台侧重复取号 WMS 重试换了 request_id,OMS 会再次调平台并消耗面单 重试务必复用 request_id;OMS 现在每次都会真实取号(不再复用平台已有运单号),所以幂等表是唯一的去重手段
批大小 OMS 单次上限 100 WMS 侧按 100 切分,注意超时(OMS 内部并发 4)
绑定缺失 只有唯一命中才取号,重复绑定视为未命中 运营侧保持「一账号一平台一编码一模板」
配置缓存 平台配置/绑定缓存 TTL 300s 改完配置要立刻生效时清 Redis:oms:cache:external-print-account:*、oms:cache:express-template:*
幂等表增长 保留 7 天 已由每日定时任务清理

12. 文件索引

OMS(D:\oms)

文件 作用
backend/app/controller/openapi.js /openapi 入口:参数校验、app_key→主体+仓库、验签、幂等回放、分发
backend/app/lib/openapiMethods.js 方法注册表:index.ping / entryorder.confirm / entryorder.match / deliveryorder.confirm / deliveryorder.getwaybill / stockout.confirm / order.cancel
backend/app/lib/waybillGet.js deliveryorder.getwaybill 实现(解析、状态校验、模板定位、逐单结果、透传 printinfo/signature、写取号记录;不写订单表)
backend/app/lib/openapiIdempotency.js 请求级幂等(begin/finish/回放/409/报文摘要)
backend/app/lib/wms/sign.js 签名算法(stableStringify / qimenSign)
backend/app/lib/apiResponse.js 响应封装 {flag, code, message, data, timestamp}
backend/app/lib/wms/qimenClient.js OMS→WMS 推送(deliveryorder.create,根节点 need_oms_waybill)
backend/app/service/orderWms.js 订单推送主流程;resolveNeedOmsWaybill 实时判定开关
backend/app/service/externalPrintOrder.js 店管家拉单入库(建单时写 need_oms_waybill 快照)
backend/app/service/externalPrintExpressInterface.js 快递接口同步/列表/绑定/resolveByCode
backend/app/lib/printPlatform/dgj.js 店管家实现(模板同步、明细、fetchWaybillNo 取号 + 打印数据解析)
backend/app/lib/printPlatform/base.js 平台基类(needFetchWaybillNo、cookie/token 保存回调)
backend/app/service/cache.js 店铺/打单账号/编码绑定缓存(oms:cache:*)
backend/database/migrations/20261104000000-*.js external_print_express_interfaces 表
backend/database/migrations/20261104010000-*.js custom_express_codes 表
backend/database/migrations/20261104020000-*.js openapi_request_idempotency 表
backend/database/migrations/20261104040000-*.js waybill_fetch_records 表(取号平台原始返回留痕)
backend/app/model/waybillFetchRecord.js 取号记录模型(printinfo / signature / print_history_ids / cai_niao_auth_info_id / dbname / platform_host / raw_response)
backend/app/lib/waybillPrintData.js deliveryorder.getprintdata 实现(按运单号+店铺标识定位打印记录 → PrintHistory/LoadPrintData 换新 params)

WMS(D:\wms)

文件 作用
app/service/systems/express.js 取号流水线;dispatchWaybillAsyncPlatform 按 request_platform_code 分发;skipped_need_oms_waybill_order_ids 分流
app/service/systems/express_platform.js 平台实现:polyapi / cainiao / pdd(需新增 oms);persistWaybillSuccessUpdates、cleanupFailedWaybillOrders
app/schedule/consume_waybill_allocate_queue.js 队列消费;waiting_oms 目前置终态(需改为调用 OMS)
app/model/waybill_allocate_queue.js 队列状态定义(pending/processing/done/failed/waiting_oms)
app/model/order_delivery.js 订单:delivery_order_code、logistics_code、need_oms_waybill
app/model/order_express.js 运单:waybill_code / status / printinfo / signature
app/service/openapi/callback.js sendByAppKey({appKey,event,request}):查 api_app 取 callback_url 与密钥,签名+重试(2s/5s/15s)
app/model/api_app.js self_app_key / self_app_secret / callback_url
app/lib/api_sign.js 与 OMS 一致的签名实现

oms/

/wms

WMS 侧实施汇报(2026-11-04)

已完成

1. 新增 express_platform.oms(app/service/systems/express_platform.js)

  • 方法名 oms,与 6.1 约定一致;不进入 shouldDispatchWaybillAsyncPerOrder() 逐单列表,保持整批调用。
  • 入参兼容 orders[].order_delivery 结构,内部归一化为 { order_id, business_key, delivery_order_code, express_code, store_id, warehouse_id }。
  • 按 100 单/批自动切分(OMS 硬上限),批间顺序处理。
  • request_id 由「仓库 + 货主 + 订单集合」推导为 oms-getwaybill-<md5>(46 字符),重试复用同一值,命中 OMS 幂等回放。
  • request_id 走 body.request.request_id(文档 4.3 的 body 兜底通道),因此没有改动 callback.js 的签名逻辑 —— body 已参与 bodySign,无需新增 query 参数。
  • appKey 解析:store_id + warehouse_id → store_warehouse(auth_status=2) → api_app(is_enabled=1 且 callback_url 非空),复用 orderAsync.resolveOpenApiAppByStore;解析不到直接失败且标记不可重试。
  • 成功项复用现有 persistWaybillSuccessUpdates(含结算扣减、WAYBILL 操作日志、auto_sync_back)。
  • 取号前先补 order_express 占位行(status=0,ignoreDuplicates):这类订单被本地流水线整体跳过、不建占位行,不补会导致取号后 update 命中 0 行而丢运单号。

2. waiting_oms 不再是终态(app/schedule/consume_waybill_allocate_queue.js)

  • 流水线返回 skipped_need_oms_waybill_order_ids 后,同一轮转调 dispatchWaybillAsyncPlatform('oms', ...)。
  • 结果落地:成功 → done;不可重试 → failed(原因写 error_message);可重试 → 退回 pending(沿用 3 次上限、60s×n 退避)。
  • 部分成功时不依赖 OMS 返回条数,统一按 order_express.status=1 的实际落库结果判定 done / 未完成。
  • 新增兜底:waiting_oms 超过 10 分钟未更新自动退回 pending,避免进程中断后订单静默停住。

3. 失败可重试性(对齐 4.4)

  • 不可重试:订单已取消/作废/归档、未找到发货单、仓库不符、未关联店铺/外部打单账号、未绑定到快递接口、平台未开启取号、缺少单号或快递编码。
  • 可重试:平台未返回运单号、接口错误、OMS 409/5xx、网络错误、返回条数不一致。

需要 OMS 侧确认(3 点)

  1. expressCode 口径:WMS 传订单上的 logistics_code(如 ZTO/STO),与 wms_express_interface.sys_express_code 同源。请确认它与 external_print_express_interfaces.custom_code 是同一套编码;若不是,请告知 WMS 应改传哪个字段。
  2. request_id 通道:WMS 放在 body.request.request_id。请确认 OMS 取值链确实覆盖该位置(4.3 有列出),否则幂等不生效、重试会重复打平台。
  3. data.results 顺序:WMS 按请求顺序逐单匹配(不按 delivery_order_code 反查,因为取号失败时该字段可能为空串)。请确认「失败项也保持顺序」。

与原文档 6.2 的差异:不需要平台配置

WMS 在 createWaybillCodePipeline 分流 need_oms_waybill 之后才调 OMS,而流水线在进入平台分组前就会对这类订单 early return。 因此 wms_print_platform.request_platform_code 不需要设为 oms;只有走流水线内部平台分发的场景才需要。 仍必须保证:api_app.callback_url 指向 OMS /openapi,self_app_key / self_app_secret 与 OMS warehouse_apis 对齐。

测试

文件 用例
test/app/service/systems/express_platform.oms.test.js 7 例:报文结构、request_id 稳定性、100 单切分、不可重试失败、可重试判定、409、缺 api_app
test/app/schedule/consume_waybill_allocate_queue.oms.test.js 5 例:成功置 done、不可重试置 failed、可重试退回 pending、部分成功、平台方法缺失

12 例全部通过,eslint 通过。

联调前置(WMS 侧 blocker)

  1. OMS dgj.fetchWaybillNo() 未实现前,deliveryorder.getWaybill 只能返回「接口错误/平台异常」这类可重试失败,WMS 队列会重试 3 次后置 failed。
  2. 建议联调期先把 external_print_platforms.fetch_waybill_no 临时置 0,避免新单持续进入 waiting_oms。
  3. 联调第一步仍建议先跑 index.ping 验证签名与 api_app ↔ warehouse_apis 凭据对应关系。
  4. WMS 侧 express_platform.oms 未补 methods/openapi_callback.json(仅回调调试页展示用),如需可视化再补。

wms/

/wms

WMS 侧对齐新版文档(2026-11-04 08:40)

已按更新后的文档(已取号复用 规则删除、printinfo/signature 透传、批大小建议)调整实现:

1. 落面单打印数据(4.2 / 4.7)

取号成功时除 waybill_code 外,同时落库:

order_express.printinfo  ← row.printinfo   // 字段类型 LONGTEXT,单张几十~几百 KB 无压力
order_express.signature  ← row.signature   // TEXT

打印时原样下发,不自行拼格式。

2. 批大小 100 → 20

OMS_WAYBILL_MAX_BATCH_SIZE = 20,与文档 4.7「建议一次批量不超过 20 单」一致。

3. request_id 改为包裹标识摘要

摘要输入改为 warehouse_id(16进制)_order_id(16进制)_business_key 的排序拼接,再取 md5:

object_id  = 186a0_394c77c9_1
request_id = oms-getwaybill-f3ea07d27abbbb8262592ed9606130e7

同一订单的主单/子单因此得到不同 request_id。

4. 子单号分配接入 OMS

既然「不再复用任何已有运单号、每次真实取号、不回写订单表」,同一 OMS 单的不同包裹可以各自取到独立面单。 allocateSubOrderNumber 已接上 OMS:流水线返回的 skipped_need_oms_waybill_order_ids 会带各自 business_key 转调 oms, buildSubOrderDetails 回查后能反映真实结果,不再固定返回「未找到分配的运单记录」。

5. 失败关键词按 4.4 新版重写

不可重试:订单已配送/已完成/已取消/已作废/已归档、未绑定到快递接口、快递编码不存在/已停用、 未开启回平台取号、真实取号已关闭、未找到订单、面单余额不足、已发货或已终结、未关联店铺/外部打单账号等。

可重试:平台未返回运单号、接口错误、店管家取号接口尚未接入、OMS 409/5xx、网络错误。

6. 关于「批量中任一单失败不锁 request_id」的风险说明

WMS 侧不会整批重取:成功的订单行会置 done 并已落库,只有失败行退回 pending。 下一轮组批时批次里只剩失败单 → request_id 随之变化 → OMS 只会对失败单重新取号。 因此 20 单/批不会因单笔失败而重复消耗 20 张面单。

7. 一个需要留意的副作用

request_id 构造方式变更后,之前用旧格式(md5(warehouse|store|order集合))写进 openapi_request_idempotency 的记录不再命中,同一批重试会新建记录并真实取号(消耗面单)。 本地已存在的 id=50 记录(订单 961312713)属于旧格式,重测时请先按文档 4.3 清理该表。

wms/

/wms

WMS 侧跟进子单号契约(2026-11-04 09:10)

按文档 4.1/4.2 新增的 packageIndex 契约调整:

1. 请求显式传包裹序号

orders: batch.map(item => ({
  deliveryOrderCode: item.delivery_order_code,
  expressCode: item.express_code,
  packageIndex: Math.max((Number(item.business_key) || 1) - 1, 0),   // business_key 1 基 → 0 基
}))

不传时 OMS 按 deliveryOrderCode 尾部 _N 推导;WMS 的 OMS 单号都是 _1 结尾(驳回复推后缀,非包裹号), 导致主单与子单都推导成 0 号包裹 —— 这正是之前「子单拿到主单运单号」的原因。现在显式传入即可区分。

2. 落库补齐新字段

order_express.printinfo        ← row.printinfo          // base64 URL-encoded JSON,原样存储不解码
order_express.signature        ← row.signature
order_express.encryptprintinfo ← row.encryptprintinfo
order_express.ver              ← row.ver
order_express.platform_code    ← 订单 sys_platform_code(回退 row.platform_code)

platform_code 必须落来源平台(如 SPH),不能落 oms:打印时用它在 wms_print_platform 匹配模板,而该表只有 DY/CAINIAO/PDD/JD/DW/KS/SPH/XHS/QT。

3. 回显校验

响应里 package_index 与请求的 packageIndex 不一致时判该单失败(可重试),避免把运单号落到错误的包裹行。

4. 已知现象说明

文档 4.2 提到「同一包裹重复取号会拿到同一个号」(店管家按 <LogicOrderId>_<包裹序号> 分配), WMS 侧不做特殊处理,按成功落库;message 里的提示会原样进 aggregatedResults。

wms/

/wms

WMS 侧修正 API 渠道出库单回传取号(2026-11-04 11:20)

问题

OMS(API) 渠道订单同步时报「发货单缺少奇门货主编码」:

  • processApiOrderInternal 组装 deliveryorder.confirm 报文后,要求 requestData.ownerCode 非空;
  • ownerCode 只能来自请求上下文 customerId、订单明细 owner_code 或奇门合同;
  • OMS 推送的 orderLines 不带 ownerCode,明细 owner_code 为空 → 直接判失败,订单 sync_status='error'。

修正(与回 OMS 取号同口径)

  1. appKey 按 from_key 回原通道:context.appKey → orderRow.from_key → 按货主反查 api_app。 与 express_platform.oms 取号完全一致的解析优先级,「从哪里回哪里去」。
  2. 不再要求奇门货主编码:OMS deliveryorder.confirm 不校验 ownerCode (OMS 侧 warehouseApiFields.js 注释亦确认「OMS 接收回传不看 ownerCode」), 组装失败判定改为只看 requestData.request 是否存在。
  3. 奇门(QM)渠道逻辑不变,仍要求 ownerCode。

验证

test/app/service/systems/order_async.api-confirm.test.js:

  • 明细无 owner_code 时仍能发起 deliveryorder.confirm,appKey 取自 from_key;
  • from_key 缺失时回退按 store_warehouse → api_app 反查。

2 例通过,eslint 通过。

待确认

本地 wms_api_app(id=48 测试接口)的 qimen_customer_id / qimen_warehouse_code 为空。 若后续需要回传 ownerCode,建议由 OMS 侧在 warehouse_apis 提供货主编码并同步到 api_app.qimen_customer_id。

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)。开发库已执行并通过校验,生产尚未执行。

回调解可查 + 日志按天分区只留 10 天(2026-11-07)

1. 背景

callback_logs(外部系统 → OMS POST /openapi)一直在写,但没有查询入口, WMS 侧排查「回调到底有没有到、报了什么」只能翻服务器日志。 同时 callback_logs / api_outbound_logs / request_logs 只增不减, DELETE 只标记删除、ibd 不还盘,硬盘只会涨。

2. 本次改动

项 说明
查询接口 GET /api/callback-logs(callbackLog.js):按主体隔离,支持 warehouse_id / warehouse_api_id / method / app_key / is_success / ip / keyword(匹配 message、error)/ start_time / end_time + page/pageSize
前端 「外部接口 → 回调日志」tab(Index.vue),可在列表里直接看请求/返回报文、HTTP 状态、业务码、耗时
分区迁移 20261107080000-partition-log-tables-by-day.js:三张日志表主键改为 (id, created_at),按 TO_DAYS(created_at) 做天分区
保留任务 logRetention.js + purgeApiLogs.js,每天 03:30 跑:补未来分区 → DROP PARTITION 删过期分区
旧任务 clear_request_logs 已 disable,避免两条清理逻辑抢同一张表

3. 分区口径

  • 分区名 pYYYYMMDD 表示「< 次日 0 点」,即 p20261107 装的是 11-07 当天的数据;
  • p_old 装保留期之前的历史数据,首次运行会直接 DROP(老分区表初始化时用它兜住存量);
  • pmax 是 MAXVALUE 兜底分区,每天用 REORGANIZE PARTITION pmax 拆出新的日分区;
  • 保留期默认 10 天(今天 + 前 9 天),可用环境变量 LOG_RETENTION_DAYS 调整; 迁移与服务读同一个变量,改的时候两边一致(服务侧每次运行都读最新值,无需改迁移)。

4. 为什么用 DROP PARTITION

DROP PARTITION 是元数据操作 + 直接删 ibd 段,毫秒级完成并立刻还盘; DELETE FROM ... WHERE created_at < ? 在大表上既慢又要等 purge 线程才还盘, OPTIMIZE TABLE 还会重建整表(锁表 + 双倍空间)。 因此只要表是分区的就走 DROP PARTITION,只有出现「表被还原成非分区」的情况才退化为分批 DELETE + OPTIMIZE 兜底。

5. 上线注意

  1. 迁移 20261107080000 会改主键((id) → (id, created_at))并重建表分区, 日志表大的话要选低峰执行(重建期间该表不可写);
  2. 只保留 10 天意味着历史日志会被物理删除,需要留存的话先备份/导出;
  3. 任务失败不会重试,失败原因写在 logs/oms/oms-error.log 的 [log-retention] 前缀里。

WMS 侧核实并修复「OMS 淘宝(菜鸟)printinfo 落库不一致」(2026-11-07 17:40)

1. 核实结论(生产数据)

对照 OMS 返回的淘宝单(delivery_order_code=dgj-10000283327758,waybill_code=773450695620554)与菠萝派菜鸟取号的落库形态:

字段 菠萝派菜鸟(抽样 id=1773910) OMS 淘宝(id=1769366) 结论
printinfo 2312 字节 JSON:{"encryptedData":"AES:…","signature":"MD:…","templateURL":"…","ver":"waybill_print_secret_version_1"} 空串(落库 NULL) ❌ 不一致
signature MD: 前缀 / 27 字符 MD: 前缀 / 27 字符 ✅
encryptprintinfo AES: 前缀 / ≈2.1KB AES: 前缀 / 2268 ✅
ver waybill_print_secret_version_1 同 ✅
platform_code CAINIAO CAINIAO(TB → print_platform_id=2) ✅

统计(create_at >= 2026-11-01):CAINIAO 共 21,784 单,printinfo 为空的仅 1 条,即上述 OMS 淘宝单。

2. 影响

WMS 菜鸟打印主面单只从 printinfo 取(resolveCainiaoMainContentFromPrintinfo),支持 { encryptedData, signature, ver, templateURL } 这形态;encryptprintinfo/signature/ver 在菜鸟打印分支里不被读取 (只有拼多多、快手、抖音分支读)。printinfo 为空时会退化为 _dataFrom='template' 的模板兜底, 打印结果与正常菜鸟单不一致。

3. 修复(已改代码,待发布)

app/service/systems/express_platform.js#oms 落库时新增 buildOmsCainiaoPrintinfo:

  • 触发条件:归一后平台码为 CAINIAO(或归一失败遗留的 TB)、printinfo 为空、encryptprintinfo 非空;
  • 输出:{"encryptedData":"<encryptprintinfo 原样>","signature":"<signature 原样>","ver":"<ver 原样>"}, AES: / MD: 前缀原样保留、不解码,与菠萝派菜鸟 printinfo 同构;
  • templateURL 仍由打印链路 enrichCainiaoOrderExpressRows 按接口配置补 cainiao_template_url;
  • 抖音 / 拼多多分支不动(它们直接读 encryptprintinfo)。

验证:test/verify_oms_cainiao_printinfo.js 18 例通过,其中包含「回拼后的 printinfo 直接被菜鸟打印组装消费 (主面单带 encryptedData/signature/ver,不再走模板兜底)」的端到端断言。

4. 待办

  • 本次修复需随 WMS 发布上线才生效;生产当前 express_platform.js 为 2026-11-07 06:17 版本,不含该修复。
  • 存量那 1 条(wms_order_express.id=1769366)printinfo 仍为空,按确认暂不做数据订正。

wms/


WMS 侧定位「打印数据格式不对」并加 printinfo 形态兼容(2026-11-07 18:10)

1. 现象与根因

生产 wms_order_express.id=1769366(运单 773450695620554)的 printinfo 被填成了裸密文 AES:rU904…(2268 字符), 而不是菜鸟要求的整包 JSON。菜鸟主面单解析逻辑 resolveCainiaoMainContentFromPrintinfo 需要 JSON, 裸密文解析失败 → hasPrintinfoMainContent=false → 退化成 buildCainiaoFallbackMainData(_dataFrom='template'), 所以打印出来的主面单是模板占位(waybillCode: ""、recipient 全空),与接口返回的现象完全一致。

用生产真实行离线复现:

printinfo 形态 主面单 keys 说明
AES:rU904…(当前库值) templateURL, data(_dataFrom=template) 旧行为,模板兜底
{"encryptedData":"AES:…","signature":"MD:…","ver":"…"} encryptedData, signature, ver 正确形态

2. 修复(两层)

  1. 落库层(express_platform.js#buildOmsCainiaoPrintinfo,上一轮已加):OMS 淘宝单自动回拼整包 JSON。
  2. 打印层(本轮新增,printer_data_builder.js):菜鸟分支在 printinfo 缺失或非 JSON 时, 用 encryptprintinfo + signature + ver 回拼加密面单 content,不再直接退化成模板; 真正缺密文时才回退模板并给出「菜鸟 printinfo 为空且缺少 encryptprintinfo,已回退模板骨架」告警。 同时 resolveCainiaoMainContentFromPrintinfo 增加 warnOnFailure 开关,避免有兜底时误报「已回退模板骨架」。

3. 影响面

  • 存量那条 printinfo=裸密文 的单无需改数据,上线后即可正常打印;
  • 明文 data 形态(_dataFrom=printinfo)、抖音/拼多多/快手分支均不受影响(已用矩阵用例覆盖)。

4. 验证

test/verify_cainiao_print_payload.js:17 例(空 printinfo、裸密文、整包 JSON、双缺失回退、明文 data 不回归、非菜鸟平台)。 全部回归脚本合计 17+18+23+24+19+16 = 117 例通过,eslint 通过。

wms/


WMS 侧处理「菜鸟 templateURL 模板要求」(2026-11-07 18:15)

1. 现状核实(生产数据)

菜鸟加密面单的主 content 需要 templateURL 才能渲染,现有链路已经保证:

  • enrichCainiaoOrderExpressRows 按快递编码匹配 wms_express_interface.template_url → 写运行时字段 cainiao_template_url;
  • 打印组装时 applyCainiaoExpressFieldMapping 用该值覆盖 contents[0].templateURL(示例响应里的 https://cloudprint.cainiao.com/template/standard/288948/112 就来自这里)。

模板 ID 对账(wms_express_interface 配置 vs 菠萝派菜鸟 printinfo 内嵌):

快递 接口配置 printinfo 内嵌 模板 ID
申通 …/template/standard/288948/112 http://cloudprint.cainiao.com/template/standard/288948 288948 ✅
韵达 …/288658/79 …/288658 288658 ✅
中通 …/300336/97 …/300336 300336 ✅
京东 …/776130/7 …/776130 776130 ✅

结论:模板 ID 完全一致,差异只有 http/https 与是否带版本段(/112),菜鸟云打印按同一模板 ID 渲染,无需改配置或数据。

2. 本轮新增兜底(printer_data_builder.js)

主 content 的模板地址改为三级来源,避免 content 被整体替换(加密面单/模板兜底)后丢模板地址:

  1. cainiao_template_url(接口配置,最高优先,保持原行为);
  2. 未配置时 → 模板样例里的 contents[0].templateURL;
  3. 两者都没有 → 保留加密字段并告警「菜鸟主面单缺少 templateURL(接口未配置 template_url 且模板样例为空)」。

验证:test/verify_cainiao_print_payload.js 扩到 22 例(含模板三级来源),全部回归脚本 22+18+23+24+19+16 = 122 例通过。

3. 可选增强(需 OMS 配合)

若要严格保证「模板与密文同源」,建议 OMS 在 deliveryorder.getwaybill 响应里补一个 template_url (deliveryorder.getprintdata 已返回同名字段),WMS 回拼 printinfo 时写进 templateURL 即可, 无需新增数据库字段。当前不阻塞打印。


WMS 侧核实快手(KS)printinfo 未落库 —— 结论:报文缺字段(2026-11-07 18:45)

1. 字段对照(生产实测 + 本次 OMS 报文)

字段 菠萝派快手单(正常,id=1775133 等) OMS 快手单(本批 dgj-10000280095565 / 319414677101981) 说明
printinfo 3456–3776 字符(大写 hex 密文) 空串 OMS 未返回
encryptprintinfo 172 字符(base64,逐单密钥) 3648 字符(hex 密文) 语义相反:OMS 把密文放进了「密钥」字段
key 无独立列,取 encryptprintinfo 缺失 快手打印必需
signature 32 字符 hex 32 字符 hex ✅
ver 1 1 ✅

生产正常快手单的 encryptprintinfo 逐单不同(逐单密钥,非店铺固定),无法从配置或其他字段推导。

2. 快手打印契约

printer_data_builder 快手分支需要四个字段: encryptedData ← printinfo、key ← encryptprintinfo、signature、ver(模板 content keys:addData, encryptedData, signature, key, templateURL, ver)。

因此 OMS 快手单现状是 encryptedData 缺失 + key 被密文占位,即使把 encryptprintinfo 灌进 printinfo 也无法打印(缺真正的 key)。

3. 需要 OMS 侧补齐(阻塞项)—— ✅ 已补齐(2026-11-07)

快手单请在取号响应中返回:

  • printinfo:快手 encryptedData(hex 密文,约 3.4–3.8KB)—— 已改:快手单取 contents[0].encryptedData(printInfo 为空时回退平台原值)
  • key:快手加密密钥(base64,172 字符,逐单生成)——对应店管家 contents[0].key —— 已新增响应字段 key
  • signature、ver:现有已正确,无需改动

同时把 encryptprintinfo 在快手口径下改为 contents[0].key(与菠萝派一致:密文进 printinfo、密钥进 encryptprintinfo), WMS 现有快手分支(encryptedData ← printinfo、key ← encryptprintinfo)无需改代码即可打印; 新增的 key 字段供 WMS 后续直接落 order_express 使用。

其余平台不受影响:拼多多、抖音直接读 encryptprintinfo;菜鸟用 printinfo 整包 JSON(WMS 已按 encryptprintinfo+signature+ver 回拼)。

4. WMS 侧本轮改动

  • 快手分支新增 key 合理性校验:key 长度 > 512 或与密文相同 → 告警 「快手模板字段 key 疑似为密文而非密钥(上游未返回 key),打印可能失败」,避免静默打出错误面单;
  • 既有告警保留(encryptedData / signature / key 缺失映射源)。
  • 新增 test/verify_kuaishou_print_payload.js 12 例;全部回归脚本合计 12+22+18+23+24+19+16 = 134 例通过。

wms/


WMS 侧确认 OMS 快手修复(前置提交 e0c718a)(2026-11-07 19:10)

1. 已核对 OMS 提交

e0c718a fix(waybill): 快手取号补齐 key 与加密面单字段 的实现与 WMS 打印口径一致:

  • extractDocumentContents 取 contents[0].encryptedData / contents[0].key / signature / ver;
  • buildWaybillPrintFields:快手单 printinfo = encryptedData(密文)、encryptprintinfo = key(密钥),并新增响应字段 key;其它平台保持原口径(printinfo = documents[].printInfo、encryptprintinfo = encryptedData)。

2. WMS 端到端仿真(按修复后口径)

环节 结果
落库字段 printinfo 长 3648(密文)、encryptprintinfo 长 172(密钥)、signature 32、ver=1
菜鸟回拼逻辑 快手单正确跳过(buildOmsCainiaoPrintinfo 返回空)
快手打印 content keys = addData, encryptedData, signature, key, templateURL, ver;encryptedData 3648、key 172、signature/ver 正确
快手告警 无(不再出现「key 疑似为密文」)

结论:WMS 无需为快手再改代码,OMS 修复上线后即可打印。

3. WMS 侧新增兜底(本轮)

express_platform.oms 落库时,若 encryptprintinfo 为空而响应带 key(快手平台),用 key 兜底写入 encryptprintinfo, 防止 OMS 灰度期只上了 key 字段的情况。134 例回归全绿,eslint 通过。

4. 下一步

WMS 侧待发布(打印层兼容 + 菜鸟 printinfo 回拼 + 本次 key 兜底),发布后建议实测一单快手: 取号 → 查 wms_order_express.printinfo/encryptprintinfo 长度(约 3.4–3.8KB / 172)→ 打印验证。

wms/


OMS 侧:发货确认回传序列号(SN)留存与反查(2026-11-13)

WMS 回传 deliveryorder.confirm 时,明细行可能带上序列号列表:

{
  "request": {
    "deliveryOrder": { "deliveryOrderCode": "FH_123", "status": "DELIVERED" },
    "packages": { "package": [ { "expressCode": "YT123", "packageCode": "PK-1", "items": [ { "itemCode": "SKU-A", "snList": [ "SN3" ] } ] } ] },
    "orderLines": [ { "orderLineNo": "1", "itemCode": "SKU-A", "snList": [ "SN1", "SN2" ] } ]
  }
}

OMS 侧处理:

项 说明
落库表 order_sn_codes(一行一个 SN;order_id = order_index.id,订单在状态表间流转时 ID 不变,故转表不搬 SN)
解析字段 行级 orderLines[].snList / snCodes / snCode(兼容逗号分隔、[{ snCode }] 对象数组),包裹级 packages.package[].items[].snList
附加字段 行号 / 商品编码 / 商品ID / 商品名称 / 包裹号 / 运单号 / 仓库ID(来自 app_key)
幂等 同一订单重复回传同一 SN 不新增(先按订单查已存在 SN,唯一键 uk_osc_order_sn 兜底)
实现 backend/app/lib/orderSnCodes.js(extractSnEntries / saveOrderSnCodes),由 orderCallback.confirmDelivery 调用;老表发货单(order_deliveries)不回写

订单查询按 SN 反查(支持多个,逗号 / 换行分隔,最多 200 个,精确匹配):

GET /api/order-status/list?status=delivery&sn_codes=SN1,SN2
  • 后端先按 (principal_id, sn_code) 从 order_sn_codes 取命中的订单ID,再回状态表过滤;
  • 订单导出的筛选条件同样支持「序列号」(sn_codes);
  • 订单导出支持两个维度(提交参数):
    • 范围:ids(导出选中,订单ID 逗号分隔,最多 500 个)/ 不传(按筛选条件全部);
    • 内容:export_mode=order(默认,一行一个订单,不含明细)/ export_mode=item(一行一个商品明细,订单字段重复填充);
    • 两种内容都带「序列号数量」「序列号列表」列:订单行取该订单全部回传 SN,含明细取该行 SN(按行号匹配,行号为空的回传记录按商品编码兜底);
  • 订单详情(GET /api/order-status/:id)返回 order.sn_codes;页面详情抽屉在「商品明细」每行提供「SN码(N)」按钮,点击展开该行的序列号列表(含运单号 / 回传时间)。