- 导出范围:支持 ids(导出选中,最多 500 条)或按筛选条件全部 - 导出内容:export_mode=order(默认,一行一个订单,不含明细)/ item(一行一个商品明细,订单字段重复) - 订单导出新增「序列号数量」「序列号列表」列;含明细时按行号取该行 SN(行号为空按商品编码兜底) - 前端导出按钮:订单类型弹窗选择「导出选中 / 按条件全部」与「订单行 / 含明细」,其余类型行为不变 - 导出任务页隐藏 ids 这类由页面自动携带的筛选字段(filters[].hidden) - 补充 exportDefs 订单导出单测(两种模式、选中、权限、参数顺序) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
80 KiB
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=...×tamp=...&sign=...
根节点 need_oms_waybill=0|1
② 回取号(本次要打通,WMS 发起)
WMS ─────────────────────────────► OMS POST {api_app.callback_url} → OMS /openapi
deliveryorder.getwaybill ?method=deliveryorder.getwaybill&app_key=...×tamp=...&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×tamp=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 记录同时承担两个方向,只需保证:
- WMS
api_app的self_app_key / self_app_secret= OMS 某条warehouse_apis的app_key / app_secret; - WMS
api_app.callback_url指向 OMS 的/openapi(例:https://api.example.com/openapi,不要带 query); - 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 的逐单校验顺序(任一不通过即返回该单失败,不影响其它单):
- 报文单号 / 快递编码齐全;
- 按
deliveryOrderCode回读订单(order_index.order_no,回退老发货单order_deliveries.delivery_order_code),并按app_key校验主体与仓库; - 订单状态:
canceled/void/history/delivery直接失败(不读也不写订单上的运单号); - 订单来源平台
source_platform_code; - 店铺 →
shops.type=2→external_print_account_id(打单账号); - 打单账号 + 平台配置(
fetch_waybill_no); - 按「账号 + 平台 + WMS 传入编码」定位快递接口 → 找不到时返回带入口与步骤的提示;
- 调用平台取号(当前店管家未实现 → 返回「店管家取号接口尚未接入」)。
取不到快递接口时,返回一句话的简短提示(平台/快递优先带中文名,查不到名称时只显示编码),真实示例:
平台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¶m_json={}×tamp=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取号'),之后就没人处理。
建议改成:
- 组内先按
warehouse_id + store_id分组(已有); - 把
waitingRows对应的order_id → delivery_order_code查出来(order_delivery.delivery_order_code),按 ≤100/批 切分(OMS 硬上限); - 调 OMS(走
dispatchWaybillAsyncPlatform('oms', ...)或直接调sendByAppKey); - 结果落地:
- 成功 →
order_express写入(见 6.1),队列行置done; - 失败:
- 不可重试类(取消/作废/归档/未绑定编码/仓库不符/单据不存在)→ 置
failed,把message写进队列行,便于运营看见; - 可重试类(网络/OMS 5xx/
平台未返回运单号)→ 按现有markGroupRetryOrFailed的重试策略处理;
- 不可重试类(取消/作废/归档/未绑定编码/仓库不符/单据不存在)→ 置
- 成功 →
- 重试必须复用同一
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 侧待办(我方)
- 店管家真实取号:已按旧系统
Dianguanjia.php提取并实现(见店管家取号-旧系统提取.md)。 默认开启真实取号(会消耗面单,DGJ_WAYBILL_ENABLE=0可关闭);首次使用前建议按该文档 §7 核对响应字段。 - 打印数据回传:已实现——逐单结果回传
printinfo / signature,并落waybill_fetch_records(见 §4.7)。 - 多包裹 / 拆单取号(已跑通):店管家用
PrintMethod=NewPrint+IsIgnoreWaybillRepeat=false分配新号, 每次调用 pid 第二段自增(63274907ebce8f6b_1_1→_2_1→_3_1),实测连续 3 次均拿到不同运单号。 WMS 按包裹各调一次即可;多一次调用 = 多一张面单,重试必须复用request_id。 详见店管家取号-旧系统提取.md§4.2.4。 - 平台字典维护:
external_print_platforms.fetch_waybill_no由迁移维护(当前dgj = 1)。如需前端可配,另开需求。 - 生产 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. 联调步骤(建议顺序)
- 连通性: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 } - 准备绑定:OMS 侧给至少 1 个淘宝模板绑定编码(例如
ZTO);确认该订单来源平台是TB。 - 推送一单:挑 1 张待审核的外部打单订单 → 审核 → 待推送 → 手动推送;到 WMS 查
order_delivery.need_oms_waybill应为1,队列行应为waiting_oms。 - 单笔取号:WMS 直接调
deliveryorder.getwaybill(单条),报文:
当前预期:{ "orders": [ { "deliveryOrderCode": "<OMS 订单号>", "expressCode": "ZTO" } ] }flag=success,逐单返回真实校验结果。以订单dgj-10000266092590(平台SPH)+ 编码STO为例,会返回 「平台SPH(视频号)快递STO(申通快递)在账号15197817068下未绑定到快递接口,…」, 按提示绑定后重试即可。 - 验证响应:成功时响应里返回
waybill_code / waybill_codes;OMS 订单表不会写入运单号(现阶段不关联)。 - 验证幂等:同一
request_id重复调用,第二次应回放同样报文(日志有「幂等重放」)。 - 失败分支:传一个不存在的编码 → 应返回「…下未绑定到快递接口…」;对已取消订单调用 → 应返回「订单已取消,取号失败」。
- 批量:一次 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 点)
expressCode口径:WMS 传订单上的logistics_code(如ZTO/STO),与wms_express_interface.sys_express_code同源。请确认它与external_print_express_interfaces.custom_code是同一套编码;若不是,请告知 WMS 应改传哪个字段。request_id通道:WMS 放在body.request.request_id。请确认 OMS 取值链确实覆盖该位置(4.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)
- OMS
dgj.fetchWaybillNo()未实现前,deliveryorder.getWaybill只能返回「接口错误/平台异常」这类可重试失败,WMS 队列会重试 3 次后置failed。 - 建议联调期先把
external_print_platforms.fetch_waybill_no临时置0,避免新单持续进入waiting_oms。 - 联调第一步仍建议先跑
index.ping验证签名与api_app ↔ warehouse_apis凭据对应关系。 - 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 取号同口径)
- appKey 按
from_key回原通道:context.appKey→orderRow.from_key→ 按货主反查api_app。 与express_platform.oms取号完全一致的解析优先级,「从哪里回哪里去」。 - 不再要求奇门货主编码:OMS
deliveryorder.confirm不校验ownerCode(OMS 侧warehouseApiFields.js注释亦确认「OMS 接收回传不看 ownerCode」), 组装失败判定改为只看requestData.request是否存在。 - 奇门(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 侧确认)
wms_order_express增加print_history_id、cai_niao_auth_info_id两个字段;- 回 OMS 取号(
deliveryorder.getwaybill)成功时落这两个字段; - 拉取抖音打印数据时按
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. 上线注意
- 迁移
20261107080000会改主键((id)→(id, created_at))并重建表分区, 日志表大的话要选低峰执行(重建期间该表不可写); - 只保留 10 天意味着历史日志会被物理删除,需要留存的话先备份/导出;
- 任务失败不会重试,失败原因写在
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. 修复(两层)
- 落库层(
express_platform.js#buildOmsCainiaoPrintinfo,上一轮已加):OMS 淘宝单自动回拼整包 JSON。 - 打印层(本轮新增,
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 被整体替换(加密面单/模板兜底)后丢模板地址:
cainiao_template_url(接口配置,最高优先,保持原行为);- 未配置时 → 模板样例里的
contents[0].templateURL; - 两者都没有 → 保留加密字段并告警「菜鸟主面单缺少 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—— 已新增响应字段keysignature、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.js12 例;全部回归脚本合计 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)」按钮,点击展开该行的序列号列表(含运单号 / 回传时间)。