WMS_MAIN/docs/openapi-callback-events.md
liufumingren 89e4cd22c0 feat(waybill): 运单物流轨迹表与 waybill.getTrace 批量更新
- 新增 wms_order_express_trace(1 运单 : N 轨迹):express_id 关联主表,
  冗余 waybill_code / order_id,warehouse_id 隔离,raw_data 存原始报文;
  uk_express_op_scan(express_id, op_time, scan_type) 幂等;字符集与主表一致
- 新增出站回调 waybill.getTrace(注册到 callback_functions,管理端可勾选):
  入参与 waybill.getreceive 一致({ request: { waybill_codes: [...] } },单批 10 单,
  signMode=simple);响应 [{ waybillNo, trace: {...} }],兼容 trace 数组与 {code,data} 包装
- 新增 waybill.warehouse.updateTrace / updateTraceTaskProgress:
  复用导出任务的异步任务ID与进度模式(前缀 waybill_trace_),
  支持 waybillCodes 或与 waybill.warehouse.list 一致的 where 条件圈选(上限 5000);
  轨迹按 (express_id, op_time, scan_type) upsert,未匹配运单计入 not_found
- 文档:methods/system.json(0.3.325)、变更记录、设计文档 2.2.1/3.9、出站回调说明 3.7

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-11 19:53:29 +08:00

447 lines
27 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` 改为逐单「先回调、成功再扣减库存并置已同步」,失败置 `error` + 待处理异常)。
> 本文档描述 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`(含失败/跳过);改后 API 渠道**逐单在同步时**发送(同一个分发循环,成功 N 单 = N 次回调),且**回调成功才扣减库存并置 `sync_status='fin'`**;回调失败/异常、报文组装或 appKey 解析失败 → 该单同步失败(`sync_status='error'` + 待处理异常,不扣减库存,可重新派发),详见 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` | API 渠道订单同步时逐单发送(回调成功才扣减库存并置已同步) | `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)。
- `deliveryorder.confirm` 单订单发送 4 次尝试后仍失败 ⇒ 该订单同步判定失败:`sync_status='error'` + 待处理异常,**不扣减库存**、不置 `fin`,订单可重新派发。
### 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:API 渠道订单同步(出库)时逐单触发,对应奇门 `taobao.qimen.deliveryorder.confirm`
- 触发实现:`app/service/systems/order_async.js#finalizeLocalChannelOrdersInternal`(`syncApiOrders` 处理链,`createChannel=API`;触发条件已变:不再等本批出现同步成功订单,而是**逐单**在同一个分发循环内直接处理,`DISPATCH_BATCH_SIZE=20` 批内并行)→ `processApiOrderInternal`(① 组装报文,缺 ownerCode → 失败「发货单缺少奇门货主编码」→ ② 解析发送用 appKey → ③ `sendByAppKey` 发送 `deliveryorder.confirm`(最多 4 次尝试)→ ④ **回调成功才**调用 `processLocalChannelOrderInternal` 扣减库存并置 `sync_status='fin'`;任何失败统一走 `markApiSyncFailedInternal`:`sync_status='error'` + 待处理异常,不扣减、可重新派发)
- 发送途径:`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`(含失败/跳过) | API 渠道逐单在同步时发送(同一个 `finalizeLocalChannelOrdersInternal` 分发循环,`DISPATCH_BATCH_SIZE=20` 批内并行) |
| 回调次数 | 每批次 1 次 | 成功 N 单 = N 次回调(每单先回调、成功再扣减) |
| 报文内容 | 批次汇总 `{ orderIds, status, successCount, failedCount }` | 每单独立奇门同层级 `request` 报文(`buildQimenDeliveryOrderConfirmDataInternal` 组装) |
| 失败处理 | 不阻塞主流程 | 回调成功才扣减库存并置 `sync_status='fin'`;回调失败/异常/组装失败 → `sync_status='error'` + 待处理异常(`markPendingException`,写库失败仅记录 error 日志),**不扣减库存**,订单可重新派发(分发前过滤只跳过 `fin`) |
- 查询开销:复用原有主表+明细查询;运单号仍由 `buildOrderWaybillCodeMapInternal` 批量取(强制同仓校验,无 N+1,现在在 `finalizeLocalChannelOrdersInternal` 内、仅 API 渠道构建);appKey 反查按货主 `Map` 批内缓存(无 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)的订单按失败处理(置 `sync_status='error'` + 待处理异常、不扣减库存,可重新派发)
- **失败文案(2026-09-13)**:
- 回调失败:`OpenAPI 回调确认失败: {error}`,例如 `OpenAPI 回调确认失败: 回调返回非 2xx 状态码: 400`;订单结果新增返回字段 `callback_retry_count`(回调实际重试次数)
- 回调抛异常:`OpenAPI 回调确认异常: ...`
- 报文组装缺货主编码:`发货单缺少奇门货主编码`
- 缺 store_id:`发货单缺少货主 store_id,无法解析回传用 appKey`
- 无可用 ApiApp(无授权关系 / 无「启用且 callback_url 非空」配置):`货主未配置可用的 OpenAPI 回调(wms_api_app 启用且 callback_url 非空)`
- `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"
}
}
```
### 3.6 waybill.getreceive(查询型回调)
- label:运单揽收状态查询
- description:按运单号批量查询是否已揽收;与 3.1~3.5 的**推送型**事件不同,本事件**消费外部响应**并回写 `wms_order_express.is_galaxy_receive`
- 注册位置:`app/lib/callback_functions.js#CALLBACK_FUNCTIONS`(管理端应用可勾选承接该方法)
- 实现:`app/service/systems/waybill.js#queryReceiveStatus`(底层方法);业务入口 `waybill.warehouse.updateReceive`(异步任务模式,进度走 `waybill.warehouse.updateReceiveTaskProgress`)
- 运单号来源:显式 `waybillCodes`,或 `where`(与 `waybill.warehouse.list` 同一套筛选口径,不含分页/排序;匹配数上限 5000,超限要求缩小范围)
- 目标应用解析:未显式传 `appKey` 时,取该仓库 `callback_functions` 勾选了 `waybill.getreceive` 的首个应用(按 `id` 升序)
- 批量上限:单次回调**最多 10 个运单号**(外部接口上限),超出自动切批并逐批更新任务进度
- **签名口径(与 3.1~3.5 不同)**:`sign = MD5(appSecret + timestamp + bodyJson)`,即 `methods/warehouse_notify.json` 描述的仓库通知协议,而非 2.4 节的 `MD5(canonicalQuery + appSecret + MD5(body))`;实现为 `openapi/callback.js#signCallback({ signMode: 'simple' })`。query 仍携带 `method/v/timestamp/app_key/sign`
- 失败识别:HTTP 200 但响应体 `code` 非 `0/1/200`(如验签失败返回 `{"code":401,"msg":"签名验证失败"}`)时整批判失败,不写入揽收状态
- `request` 结构(经 `sendByAppKey` 统一包装,线路报文为 `{ request: {...} }`):
```json
{
"request": {
"waybill_codes": [ "YT1234567890" ]
}
}
```
- 外部**响应**:裸数组 `[{ "waybill_code": "YT1234567890", "is_galaxy_receive": 1 }]`;同时兼容 `{ "code": 200, "data": [...] }` 包装
- `is_galaxy_receive` 兼容取值:`1`/`0`、`'Y'`/`'N'`(大小写不敏感)、布尔值;非法取值计入 `failed`,不写库
- 回写口径:按 `waybill_code` + `warehouse_id` 更新 `wms_order_express.is_galaxy_receive`(`1→Y`、`0→N`),跨仓不串写
### 3.7 waybill.getTrace(查询型回调:物流轨迹)
- label:运单物流轨迹查询
- description:按运单号批量查询物流轨迹;消费外部响应并落库 `wms_order_express_trace`
- 注册位置:`app/lib/callback_functions.js#CALLBACK_FUNCTIONS`
- 实现:`app/service/systems/waybill.js#queryTraces` + `#saveTraces`;业务入口 `waybill.warehouse.updateTrace`(进度走 `waybill.warehouse.updateTraceTaskProgress`)
- 入参:与 `waybill.getreceive` 一致(`{ request: { waybill_codes: [...] } }`,单批最多 10 单);签名同样为 `MD5(appSecret + timestamp + bodyJson)`
- 响应:
```json
[{
"waybillNo": "770358128188071",
"trace": {
"opTime": "2026-11-10 06:15:53",
"outBizCode": "770358128188071_510180_1794262553000_210",
"memo": "【广州市】快件已发往 山东济南转运中心",
"opOrgCityName": "广州市",
"weight": 0,
"scanType": "发件"
}
}]
```
- 兼容:`trace` 可为数组(一个运单多条轨迹)、`traces` / `traceList` 数组、`{ code, data: [...] }` 包装
- 落库:`wms_order_express_trace`,唯一键 `(express_id, op_time, scan_type)` 幂等,命中时更新 `memo` / `op_org_city_name` / `weight` / `raw_data`
- 失败识别:与 3.6 相同(HTTP 200 但 `code` 非 `0/1/200` 整批判失败)
## 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`
- 查询型回调实现:`app/service/systems/waybill.js#queryReceiveStatus`(`waybill.getreceive`);同类的 `deliveryorder.getwaybill` / `deliveryorder.getprintdata` 分别见 `app/service/systems/express_platform.js`、`app/service/systems/order_print.js`
- 回调 method 注册表(管理端可勾选):`app/lib/callback_functions.js#CALLBACK_FUNCTIONS`
- 接口文档 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.4.0);变更记录写入 `methods/changes/openapi_callback.json`(首条 version `2026.09.12-openapi-callback-init`,type `added`;最新 version `2026.09.13-openapi-callback-confirm-before-deduct`,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` 等)为追加式历史,保持原样,不回改。