WMS_MAIN/docs/openapi-callback-events.md
liufumingren 2555f3bb4d fix(openapi): deliveryorder.confirm 回调 appKey 按货主合约反查
- 背景:order_storage_allocation 构造的 routeContext 不含 appKey,
  finalizeLocalChannelOrdersInternal 的 if(appKey) 门禁导致 API 同步链路的
  deliveryorder.confirm 从未真正发出;订单表 from_key 也兜不住
  (normalizeOrderFromKey 仅接受整数,字符串 app_key 被归一化为 null)
- order_async.js 新增 resolveOpenApiAppByStoreInternal:口径与入库单
  _sendOpenApiCallback 对齐(wms_store_warehouse auth_status=2 →
  wms_api_app is_enabled=1 且 callback_url 非空)
- notifyApiDeliveryOrderConfirmsInternal 逐单解析 appKey:context.appKey 非空优先
  (不触发反查),缺失时按 orderRow.store_id 反查并按货主缓存(同批次无 N+1);
  解析不到 appKey 的订单 warn 后跳过、不发请求
- 补充回调成功 info 日志(含 appKey)
- 文档:methods/openapi_callback.json 1.2.0 → 1.3.0、变更记录
  methods/changes/openapi_callback.json、docs/openapi-callback-events.md、
  AI_METHOD_ROUTING.md 同步
- test: order_async.openapi.callback.test.js 覆盖 context.appKey 为空时反查发送
2026-09-13 15:29:51 +08:00

386 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 请求体结构
```json
{
"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` 组装):
```json
{
"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` 组装):
```json
{
"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`;发送用 appKey 解析优先级:调用上下文 `context.appKey` 非空时优先(**不触发合约反查**),缺失时按订单货主(`store_id` + `warehouse_id`)合约反查 —— `wms_store_warehouse(auth_status=2)` → `wms_api_app(is_enabled=1 且 callback_url 非空)` 的 `self_app_key`(`resolveOpenApiAppByStoreInternal`,口径与入库单回调 `inbound_direct_log.js#_sendOpenApiCallback` 对齐);同一批次按货主 `Map` 缓存(N 个成功单 / M 个货主 → 2M 次查询,无 N+1)
- **逐单发送语义(2026-09-13 变化)**:
| 维度 | 改动前 | 改动后 |
|---|---|---|
| 通知对象 | 一次回调携带整批 `orderIds`(含失败/跳过) | 仅对 `syncResults` 中 `status==='success'` 的订单逐单发送 |
| 回调次数 | 每批次 1 次 | 成功 N 单 = N 次回调 |
| 报文内容 | 批次汇总 `{ orderIds, status, successCount, failedCount }` | 每单独立奇门同层级 `request` 报文(`buildQimenDeliveryOrderConfirmDataInternal` 组装) |
| 失败处理 | 不阻塞主流程 | 单订单组装/发送失败仅 warn,不影响其他订单与主流程 |
- 查询开销:复用原有主表+明细查询,新增 1 次运单号批量查询(`buildOrderWaybillCodeMapInternal`,强制同仓校验,无 N+1)
- **appKey 门禁修复(2026-09-13)**:此前 `order_storage_allocation.js` 构造的 `routeContext` 不含 `appKey`,而 `finalizeLocalChannelOrdersInternal` 内有 `if (appKey)` 门禁,导致 `syncOrderIds(API)` 链路的 `deliveryorder.confirm` **从未真正发出过请求**;订单 `wms_order_delivery.from_key` 也兜不住(`normalizeOrderFromKey` 只接受整数,字符串 app_key 被归一化为 null)。本次改为按货主合约反查 appKey 修复。解析不到 appKey(订单缺 `store_id` / 无授权关系 / 无「启用且 callback_url 非空」的 ApiApp)的订单 warn 后跳过、不发请求;同步失败的订单不发送
- `request` 结构(注册表 `request` 模板口径):
```json
{
"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` 模板口径):
```json
{
"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` 模板口径):
```json
{
"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` 等)为追加式历史,保持原样,不回改。