WMS_MAIN/docs/openapi-callback-events.md
liufumingren d725e7e457 feat(openapi): 出站回调命名与报文改奇门同层级
- 回调 method 由 snake_case 事件名改为 模块.动作:entryorder.confirm / entryorder.match / deliveryorder.confirm / stockout.confirm / deliveryorder.cancel(原 order.cancel 与入站方法同名,改名避免 callback_url 误指向 /openapi 时被路由到取消单据接口)。

- 时间戳统一为秒级(String(Math.floor(Date.now()/1000))),与 /openapi 入站 ±600 秒时效校验及回调调试页一致。

- 报文体由 { event, data, metadata } 改为奇门同层级 { request: {...} }(移除 metadata,事件标识只靠 query 的 method);入库类回调与奇门侧共用同一份报文组装。

- deliveryorder.confirm 改为逐单发送(仅同步成功的订单);stockout.confirm 直接复用 buildStockoutConfirmDataInternal 结果。

- 修复 entryorder.match 死代码:绑定成功且本次新建绑定时回传,重复触发不重复通知,回传失败不影响绑定。

- 调试页 /docs/api/openapi/callback-test 按真实报文预填;新增出站回调文档页 /docs/api/openapi_callback 及入口链接。

- script/update-api-doc.cjs 支持 spec.newDoc 新建文档与 docMeta.description(附单测)。

- 文档:methods/openapi_callback.json、AI_METHOD_ROUTING.md 5.6 节、docs/openapi-callback-events.md、docs/api-doc-update-workflow.md 等。
2026-09-13 02:24:37 +08:00

20 KiB
Raw Blame History

OpenAPI 出站回调事件说明

状态:2026-09-13 破坏性协议变更已落代码(报文体 { event, data, metadata } → { request };deliveryorder.confirm 改为逐单发送)。 本文档描述 WMS 主动向外部系统推送的 OpenAPI 出站回调(出站 HTTP 回调)协议。 与 methods/openapi.json 描述的入站 OpenAPI method(POST /openapi)方向相反;本文档不属于 methods/*.json 的 SSOT 范围。

1. 破坏性变更说明

1.1 2026-09-13:报文体改为奇门同层级 { request }

  • 报文体由 { event, data, metadata } 改为奇门同层级的 { request: {...} };发送端不再发送数据/元数据,event 仅出现在 query 的 method。
  • 5 个事件的 request 结构与奇门对应接口的 request 节点同层级(字段口径见第 3 节,与注册表 request 模板一致)。
  • deliveryorder.confirm 通知对象口径变化:改动前一次回调携带整批 orderIds(含失败/跳过);改后仅对 syncResults 中 status==='success' 的订单逐单发送(成功 N 单 = N 次回调),详见 3.3。
  • 旧报文结构({ event, data, metadata })已全部废弃:无新旧兼容、无双发,接收方必须同步改造。

1.2 2026-09-12:事件名改为 模块.动作(历史,仍有效)

  • 出站回调的 method(query 参数)原先使用 snake_case 事件名(如 stockout_completed),现统一改为 模块.动作(如 stockout.confirm),与奇门 method 去掉 taobao.qimen. 前缀后对齐。
  • 旧事件名已全部废弃:无新旧兼容、无双发。接收方必须同步改造;仅当接收方按 模块.动作 校验 method 时,新协议可正常通过(此前会报 400「参数缺失或错误: method(需为 模块.动作,如 index.ping)」)。
  • 回调事件 order.cancel 更名为 deliveryorder.cancel:与 /openapi 入站方法 order.cancel(取消单据接口,见 methods/openapi.json)同名,若接收方将 callback_url 误指向 WMS /openapi 会被路由到真正的取消单据接口;不做兼容、不双发,旧名 order.cancel(出站方向)已废弃。
旧(事件名,已废弃) 新(method) 触发场景 实现位置
entry_order_direct_inbound_completed entryorder.confirm 直入入库(API 来源)完成 app/service/systems/inbound_direct_log.js
entry_order_receiving_matched entryorder.match 入库单匹配收货单完成 app/service/systems/receiving_entry_match.js
order_completed deliveryorder.confirm 订单同步(出库)完成(逐单发送) app/service/systems/order_async.js
stockout_completed stockout.confirm 出库单确认完成 app/service/systems/order_async.js
order_cancelled deliveryorder.cancel 订单取消成功(旧 method 名 order.cancel 已废弃) app/service/openapiMethods/order.js

事件注册表:app/service/openapi/callbackRegistry.js#CALLBACK_EVENTS(5 条,每条含 name / label / description / request,request 为奇门同层级报文模板),回调调试页 GET /docs/api/openapi/callback-test(app/controller/openapiCallback.js)直接消费该注册表,并按注册表自动预填完整报文体 { request: {...} }(可编辑)。

2. 协议说明

2.1 出站请求与 query 参数

POST {callbackUrl}?method={模块.动作}&v=1.0&timestamp={timestamp}&app_key={selfAppKey}&sign={sign}

callbackUrl 来自 api_app 表(callback_url 字段,要求 is_enabled=1 且 callback_url 非空)。

query 参数 类型 必填 说明
method string 是 回调 method,模块.动作 格式(与奇门对应接口对应;报文体不再携带 event 字段);URL 中做 encodeURIComponent
v string 是 协议版本,固定 1.0
timestamp string 是 时间戳,秒级(10 位字符串),见第 4 节
app_key string 是 应用标识(api_app.self_app_key);URL 中做 encodeURIComponent
sign string 是 签名,算法见 2.4

2.2 请求头

Content-Type: application/json

2.3 请求体结构

{
  "request": { "…": "…" }
}
  • request 为奇门同层级业务报文,结构按事件不同,口径见第 3 节(与注册表 request 模板一致)。
  • event 不出现在报文体内,仅拼入 query 的 method。
  • 构造位置:app/service/openapi/callback.js#sendWithRetry(body = { request: request || {} });sendByAppKey 将 request 原样透传给 sendWithRetry。

2.4 签名算法

实现:app/lib/api_sign.js#signRequest(与 OpenAPI 入口验签算法一致)。

  1. canonicalQuery:query 中除 sign / signature(大小写不敏感)外、值非 undefined 的参数,按 key 字母序升序,拼为 key=value&key2=value2。值为原始字符串(不 URL 编码);对象值经 stableStringify。
  2. bodySign = md5(stableStringify(body));stableStringify 对对象键做字母序排序后 JSON 序列化;body 即完整报文 { request: {...} }。
  3. sign = md5(canonicalQuery + selfAppSecret + bodySign),小写十六进制。

注意:

  • 参与签名的是未 URL 编码的原值;实际 URL 中仅 method、app_key 做了 encodeURIComponent。
  • selfAppSecret 为 api_app.self_app_secret(signRequest 内部会 trim)。

canonicalQuery 示例(method=entryorder.confirm):

app_key=APP2024011514301234&method=entryorder.confirm&timestamp=1758047400&v=1.0

2.5 重试策略

实现:app/service/openapi/callback.js#sendWithRetry。

  • 最多重试 MAX_RETRY=3 次(即最多共 4 次尝试)。
  • 间隔:[2000, 5000, 15000] 毫秒(2s → 5s → 15s)。
  • 触发条件:非 2xx 响应或网络错误(异常 catch)。
  • 单次请求超时:30s(ctx.curl timeout: 30000)。
  • 每次尝试经 logCallback 记录日志:[OpenapiCallback] event=… appKey=… url=… retry=N success=… response=…(成功 info、中途失败 warn、最终失败 error)。

2.6 发送途径与配置解析

途径 配置解析 使用的事件
sendByAppKey 按 app_key 查 ApiApp(self_app_key=appKey, is_enabled=1),取 self_app_secret 与 callback_url deliveryorder.confirm、stockout.confirm、deliveryorder.cancel
sendWithRetry 直调 按 StoreWarehouse(store_id/warehouse_id, auth_status=2)→ ApiApp(contract_id=storeWarehouse.id, is_enabled=1, callback_url 非空)定位 entryorder.confirm、entryorder.match

调试/测试工具:

  • 调试页:GET /docs/api/openapi/callback-test(app/controller/openapiCallback.js,路由见 app/router.js),按注册表渲染事件下拉,选中事件后自动预填与真实回调一致的完整报文体 { request: {...} }(可编辑),前端算签名后 POST。
  • 模拟发送(入站):openapiMethods/callback.js#test(method=callback.test,body 为 { event, request },event 缺省 deliveryorder.confirm,按 app_key 走真实发送链路)。

3. 事件逐个说明

说明:以下触发实现中的行号为 2026-09-12 代码快照值,行号可能漂移;定位请以方法名 grep 为准。

3.1 entryorder.confirm

  • label:入库单确认完成(直入)
  • description:直入入库(API 来源)完成后回传,对应奇门 taobao.qimen.entryorder.confirm
  • 触发实现:app/service/systems/inbound_direct_log.js#qimenEntrySync 的 API 分支(source_type=API)→ _sendOpenApiCallback(event: 'entryorder.confirm');回传成功才执行本地回调,throwOnError=true
  • 发送途径:sendWithRetry 直调(见 2.6)
  • request 结构(注册表 request 模板口径;以 QM 分支为唯一基准,QM/API 共用 buildEntryOrderConfirmRequest 组装):
{
  "entryOrder": {
    "entryOrderCode": "RK20260912001",
    "ownerCode": "OWNER-001",
    "warehouseCode": "WH-100",
    "entryOrderId": 543,
    "entryOrderType": "SCRK",
    "outBizCode": "DIRECT_INBOUND_1726131400000",
    "confirmType": 0,
    "status": "FULFILLED",
    "freight": 0,
    "operateTime": "2026-09-12 10:30:00",
    "remark": "导入/PDA直接入库提交"
  },
  "orderLines": [
    {
      "orderLineNo": 1,
      "ownerCode": "OWNER-001",
      "itemCode": "SKU-1",
      "itemId": "1001",
      "inventoryType": "ZP",
      "planQty": 2,
      "actualQty": 2
    }
  ]
}
  • entryOrder 字段口径:outBizCode 缺省自动生成 DIRECT_INBOUND_时间戳;confirmType 0=最终确认 / 1=部分确认;status FULFILLED / PARTFULFILLED;freight 固定 0;operateTime 为 app.formatDate(new Date());remark 为业务备注。

3.2 entryorder.match

  • label:入库单匹配收货完成
  • description:入库单匹配收货单完成后回传(API 来源),对应奇门 taobao.qimen.entryorder.confirm
  • 触发实现:app/service/systems/receiving_entry_match.js#matchAfterEntryCompleted:匹配成功写入绑定关系且本次确实新建绑定(bindResult.created === true)时,调用 _sendCallback(entryOrder, matchedReceiving, 'auto_match');_sendCallback 按 source_type 分流(QM→奇门,API→OpenAPI → _sendOpenApiCallback,event: 'entryorder.match')。重复触发时绑定已存在(created === false),不会重复回传;回传失败仅记录 warn,不影响绑定与入库单状态更新。
  • 发送途径:sendWithRetry 直调(见 2.6)
  • matchType:仅保留在日志中(自动/手动匹配类型标识),不塞入回传报文
  • outBizCode / remark 口径:outBizCode 缺省自动生成 RECEIVING_MATCH_时间戳;remark 固定「匹配收货单{收货单号}自动回传」(如 匹配收货单RCV20260912001自动回传);confirmType 固定 0、status 固定 FULFILLED
  • request 结构(注册表 request 模板口径;QM/API 共用 buildEntryOrderConfirmRequest 组装):
{
  "entryOrder": {
    "entryOrderCode": "RK20260912002",
    "ownerCode": "OWNER-001",
    "warehouseCode": "WH-100",
    "entryOrderId": 543,
    "entryOrderType": "SCRK",
    "outBizCode": "RECEIVING_MATCH_1726131400000",
    "confirmType": 0,
    "status": "FULFILLED",
    "freight": 0,
    "operateTime": "2026-09-12 10:30:00",
    "remark": "匹配收货单RCV20260912001自动回传"
  },
  "orderLines": [
    {
      "orderLineNo": 1,
      "ownerCode": "OWNER-001",
      "itemCode": "SKU-1",
      "itemId": "1001",
      "inventoryType": "ZP",
      "planQty": 2,
      "actualQty": 2
    }
  ]
}

3.3 deliveryorder.confirm

  • label:订单发货完成
  • description:订单同步(出库)完成后触发,对应奇门 taobao.qimen.deliveryorder.confirm
  • 触发实现:app/service/systems/order_async.js#finalizeLocalChannelOrdersInternal(syncApiOrders 处理链,触发条件不变:createChannel=API 且 successCount>0)→ notifyApiDeliveryOrderConfirmsInternal(fire-and-forget,失败仅 warn)
  • 发送途径:sendByAppKey(按 app_key 解析)
  • 逐单发送语义(2026-09-13 变化):
维度 改动前 改动后
通知对象 一次回调携带整批 orderIds(含失败/跳过) 仅对 syncResults 中 status==='success' 的订单逐单发送
回调次数 每批次 1 次 成功 N 单 = N 次回调
报文内容 批次汇总 { orderIds, status, successCount, failedCount } 每单独立奇门同层级 request 报文(buildQimenDeliveryOrderConfirmDataInternal 组装)
失败处理 不阻塞主流程 单订单组装/发送失败仅 warn,不影响其他订单与主流程
  • 查询开销:复用原有主表+明细查询,新增 1 次运单号批量查询(buildOrderWaybillCodeMapInternal,强制同仓校验,无 N+1)
  • request 结构(注册表 request 模板口径):
{
  "deliveryOrder": {
    "totalOrderLines": 1,
    "deliveryOrderCode": "DO20260912001",
    "deliveryOrderId": 123,
    "warehouseCode": "WH-100",
    "orderType": "JYCK",
    "status": "DELIVERED",
    "outBizCode": "DO20260912001",
    "confirmType": 0,
    "orderConfirmTime": "2026-09-12 10:30:00",
    "operatorCode": "",
    "operatorName": "",
    "storageFee": "0",
    "operateTime": "2026-09-12 10:30:00"
  },
  "packages": {
    "package": [
      {
        "logisticsCode": "YTO",
        "logisticsName": "圆通速递",
        "expressCode": "YT1234567890",
        "packageCode": "DO20260912001",
        "invoiceNo": "INV20260912001",
        "items": [
          {
            "itemCode": "SKU-1",
            "itemId": 1001,
            "quantity": 2
          }
        ]
      }
    ]
  },
  "orderLines": [
    {
      "orderLineNo": "1",
      "orderSourceCode": "SO20260912001",
      "subSourceCode": "",
      "ownerCode": "OWNER-001",
      "itemCode": "SKU-1",
      "itemId": 1001,
      "itemName": "测试商品1",
      "extCode": "",
      "planQty": 2,
      "actualQty": 2,
      "retailPrice": 0,
      "actualPrice": 0,
      "discountAmount": "0",
      "inventoryType": "ZP",
      "snList": [],
      "qrCode": ""
    }
  ]
}

3.4 stockout.confirm

  • label:出库单确认完成
  • description:出库单确认回传(API 来源),对应奇门 taobao.qimen.stockout.confirm
  • 触发实现:app/service/systems/order_async.js#notifyStockoutExternalInternal 的 API 分支(source_type=API,event: 'stockout.confirm');request 即 buildStockoutConfirmDataInternal 的返回结构 { deliveryOrder, packages, orderLines }(不再有原先 data.stockoutOrderCode/status 薄包装,报文与奇门请求体同层级)
  • 发送途径:sendByAppKey(按 app_key 解析)
  • request 结构(注册表 request 模板口径):
{
  "deliveryOrder": {
    "totalOrderLines": 1,
    "deliveryOrderCode": "SO20260912001",
    "deliveryOrderId": 5001,
    "warehouseCode": "WH-100",
    "orderType": "PTCK",
    "status": "DELIVERED",
    "outBizCode": "SO20260912001",
    "confirmType": 0,
    "orderConfirmTime": "2026-09-12 10:30:00",
    "operatorCode": "",
    "operatorName": ""
  },
  "packages": {
    "package": [
      {
        "logisticsCode": "YTO",
        "logisticsName": "圆通速递",
        "expressCode": "YT1234567890",
        "packageCode": "SO20260912001",
        "items": [
          {
            "itemCode": "SKU-1",
            "itemId": 1001,
            "quantity": 2
          }
        ]
      }
    ]
  },
  "orderLines": [
    {
      "orderLineNo": "1",
      "ownerCode": "OWNER-001",
      "itemCode": "SKU-1",
      "itemId": 1001,
      "itemName": "测试商品1",
      "planQty": 2,
      "actualQty": 2,
      "inventoryType": "ZP"
    }
  ]
}

3.5 deliveryorder.cancel

  • label:订单已取消
  • description:订单取消成功后触发(出站事件名 deliveryorder.cancel)
  • 触发实现:app/service/openapiMethods/order.js#cancel 取消成功后 fire-and-forget(event: 'deliveryorder.cancel')
  • 改名原因:出站回调事件名与 /openapi 入站方法 order.cancel(取消单据接口,见 methods/openapi.json)同名,若接收方将 callback_url 误指向 WMS /openapi 会被路由到真正的取消单据接口;故改为 deliveryorder.cancel,不做兼容、不双发
  • 自定义约定(2026-09-13):无奇门对应接口,按 deliveryOrder 节点约定自定义;status 为自定义约定值 CANCELED(风格与奇门 deliveryOrder.status 家族枚举一致);orderType 为 body.orderType 大写归一化结果(String(body.orderType || 'JYCK').trim().toUpperCase())
  • 发送途径:sendByAppKey(按 app_key 解析)
  • request 结构(注册表 request 模板口径):
{
  "deliveryOrder": {
    "deliveryOrderCode": "TEST-ORDER-001",
    "orderType": "JYCK",
    "status": "CANCELED"
  }
}

4. timestamp 规范(2026-09-12 已统一为秒)

timestamp 已统一为**秒级(10 位字符串)**规范值:String(Math.floor(Date.now() / 1000))。

位置 取值 单位
出站发送 app/service/openapi/callback.js#sendWithRetry String(Math.floor(Date.now() / 1000)) 秒(10 位)
回调调试页 app/controller/openapiCallback.js(nowTimestamp) Math.floor(Date.now() / 1000) 秒(10 位)
  • 与 /openapi 入站入口 app/service/openapiEntry.js 的时间戳时效校验一致(秒级窗口,±600 秒),可作为规范值对外承诺。
  • 历史背景:此前发送端用 String(Date.now())(毫秒)与调试页(秒)口径不一致(methods/changes/openapi_callback.json 版本 2026.09.12-openapi-callback-init 的「已知问题」备注),已在本批次修复;接收方请按秒级(10 位)实现校验,勿再按毫秒。

5. 相关文件索引

  • 事件注册表:app/service/openapi/callbackRegistry.js
  • 发送与重试:app/service/openapi/callback.js
  • 签名算法:app/lib/api_sign.js
  • 调试页控制器:app/controller/openapiCallback.js(路由 app/router.js)
  • 入站方法路由文档:AI_METHOD_ROUTING.md 5.6 节
  • 触发实现:app/service/systems/inbound_direct_log.js、app/service/systems/receiving_entry_match.js、app/service/systems/order_async.js、app/service/openapiMethods/order.js
  • 接口文档 SSOT:methods/openapi_callback.json(5 个 method)
  • 变更记录:methods/changes/openapi_callback.json
  • 文档站页面:/docs/api/openapi_callback(OpenAPI 出站回调文档页)
  • 入口来源:/docs/api/openapi 页面头部的「→ 出站回调文档」链接

调试工具 GET /docs/api/openapi/callback-test 已在第 1 节与 2.6 节说明,此处不重复。

三份资料的定位与先后关系:

资料 定位
methods/openapi_callback.json 出站回调接口文档 SSOT(5 个 method 的 params / response / errors),文档站 /docs/api/openapi_callback 页面消费
app/service/openapi/callbackRegistry.js#CALLBACK_EVENTS 事件注册表(name / label / description / request,request 为奇门同层级报文模板),运行时数据源;回调调试页 /docs/api/openapi/callback-test 消费注册表并预填完整报文体 { request: {...} }
docs/openapi-callback-events.md(本文) 协议说明与背景(触发链路、签名算法、重试策略、时间戳规范),非 SSOT,仅作解释性补充

先后关系:事件或字段变化时,先改代码(callbackRegistry.js 注册表与发送实现)→ 再经 script/update-api-doc.cjs 更新接口文档 SSOT methods/openapi_callback.json 并追加 methods/changes/openapi_callback.json → 最后同步本文与文档站文案。调试页内容以注册表为准,文档站页面以 SSOT 为准。

6. 与 methods/*.json 的关系

  • 出站回调不写入 methods/openapi.json:该文件是入站 method 的 SSOT(POST /openapi),script/update-api-doc.cjs 的 spec 结构(modules→list→method→params/response/errors)不适合表达出站回调,写入会污染文档与文档 UI 语义。
  • 出站回调现已独立成接口文档 methods/openapi_callback.json(module=openapi_callback,5 个 method,当前版本 1.2.0);变更记录写入 methods/changes/openapi_callback.json(首条 version 2026.09.12-openapi-callback-init,type added;本次 version 2026.09.13-openapi-callback-request-protocol,type updated)。
  • 本次无入站接口契约变更:methods/openapi.json、methods/system.json、methods/qimen.json 均未改动。
  • methods/changes/*.json 中历史记录提及的旧事件名(stockout_completed、entry_order_direct_inbound_completed、entry_order_receiving_matched 等)为追加式历史,保持原样,不回改。