WMS_MAIN/methods/changes/openapi_callback.json
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

81 lines
8.4 KiB
JSON
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.

[
{
"version": "2026.09.13-openapi-callback-deliveryorder-confirm-appkey-resolve",
"date": "2026-09-13",
"type": "updated",
"summary": "同步 deliveryorder.confirm 触发条件(appKey 解析规则):发送用 appKey 由仅依赖调用上下文 context.appKey 改为「context.appKey 非空优先,缺失时按订单货主(store_id + warehouse_id)合约反查 wms_store_warehouse(auth_status=2) → wms_api_app(is_enabled=1 且 callback_url 非空) 的 self_app_key,同批次按货主缓存无 N+1」;解析不到 appKey 的订单 warn 后跳过、不发送。修复此前 routeContext 不含 appKey 导致该回调从未真正发出的问题。文档版本 1.2.0 → 1.3.0。",
"methods": [
"deliveryorder.confirm"
],
"notes": [
"背景:order_storage_allocation.js 构造的 routeContext 不含 appKey,finalizeLocalChannelOrdersInternal 内 if(appKey) 门禁使 syncOrderIds(API) 链路的 deliveryorder.confirm 从未真正发出请求;订单 wms_order_delivery.from_key 兜不住(normalizeOrderFromKey 仅接受整数,字符串 app_key 被归一化为 null)",
"实现:order_async.js 新增 resolveOpenApiAppByStoreInternal(口径与 inbound_direct_log.js#_sendOpenApiCallback 对齐);notifyApiDeliveryOrderConfirmsInternal 逐单解析 appKey:context.appKey 优先(不触发反查)→ 按 orderRow.store_id 合约反查 → 逐货主 Map 缓存(N 成功单 / M 货主 → 2M 次查询);解析不到 appKey(订单缺 store_id / 无授权关系 / 无可用 ApiApp 配置)warn 后跳过该订单",
"同步 docs/openapi-callback-events.md 3.3 与 AI_METHOD_ROUTING.md 5.6"
]
},
{
"version": "2026.09.13-openapi-callback-request-protocol",
"date": "2026-09-13",
"type": "updated",
"summary": "破坏性协议变更:OpenAPI 出站回调报文体由 { event, data, metadata } 改为奇门同层级的 { request: {...} },发送端不再发送数据/元数据;event 仅保留在 query 的 method;5 个事件的 request 结构按 callbackRegistry.js 的 request 模板重写;deliveryorder.confirm 由一次批量汇总通知改为逐单发送(仅对 status='success' 的订单,成功 N 单 = N 次回调);deliveryorder.cancel 按 deliveryOrder 节点约定自定义(status 固定 CANCELED,无奇门对应接口);回调调试页预填完整报文体 { request }。文档版本 1.1.0 → 1.2.0。",
"methods": [
"entryorder.confirm",
"entryorder.match",
"deliveryorder.confirm",
"stockout.confirm",
"deliveryorder.cancel"
],
"notes": [
"破坏性协议变更:body 不再有 event/data/metadata,发送端统一发送 { request: request || {} }(app/service/openapi/callback.js#sendWithRetry / sendByAppKey);event 仅用于 query 的 method",
"5 个事件 request 结构:entryorder.confirm { entryOrder, orderLines }(inbound_direct_log.js#buildEntryOrderConfirmRequest,QM/API 共用);entryorder.match { entryOrder, orderLines }(receiving_entry_match.js#buildEntryOrderConfirmRequest,QM/API 共用,outBizCode 前缀 RECEIVING_MATCH_、remark=匹配收货单{收货单号}自动回传);deliveryorder.confirm { deliveryOrder, packages{package[]}, orderLines }(order_async.js#buildQimenDeliveryOrderConfirmDataInternal);stockout.confirm { deliveryOrder, packages{package[]}, orderLines }(order_async.js#buildStockoutConfirmDataInternal,删除原先 data.stockoutOrderCode/status 薄包装);deliveryorder.cancel { deliveryOrder: { deliveryOrderCode, orderType, status:'CANCELED' } }(openapiMethods/order.js#cancel,无奇门对应接口)",
"deliveryorder.confirm 逐单语义:改动前一次回调携带整批 orderIds(含失败/跳过);改后仅对 syncResults 中 status==='success' 的订单逐单发送(成功 N 单 = N 次回调),fire-and-forget、失败仅 warn;复用原有主表+明细查询并新增 1 次运单号批量查询,无 N+1",
"事件注册表 callbackRegistry.js 由 { name, label, description, sampleData, metadata } 改为 { name, label, description, request };回调调试页 GET /docs/api/openapi/callback-test 预填完整报文体 { request: {...} }(此前预填三层 { event, data, metadata })",
"同步 docs/openapi-callback-events.md 与 AI_METHOD_ROUTING.md 5.6 节"
]
},
{
"version": "2026.09.12-openapi-callback-protocol-align",
"date": "2026-09-12",
"type": "updated",
"module": "callback",
"summary": "methods/openapi_callback.json 同步 2026-09-12 出站回调代码改动:回调方法 order.cancel 更名为 deliveryorder.cancel(与 /openapi 入站方法 order.cancel 区分,不做兼容、不双发);5 个事件的 timestamp 统一为秒级(10 位)规范值(原「毫秒/秒不一致待统一」已知问题已修复);补齐 metadata 字段说明;entryorder.match 由「已实现待接入」改为已接入(matchAfterEntryCompleted 绑定成功且本次新建绑定时回传,matchType 固定 auto_match);调试页按真实 { event, data, metadata } 三层预填。",
"methods": [
"entryorder.confirm",
"entryorder.match",
"deliveryorder.confirm",
"stockout.confirm",
"deliveryorder.cancel"
],
"notes": [
"order.cancel 为出站回调旧方法名,本次删除(不做兼容、不双发);入站方法 order.cancel 仍属于 methods/openapi.json,不受影响",
"timestamp 统一:app/service/openapi/callback.js#sendWithRetry 改为 String(Math.floor(Date.now()/1000)),与 /openapi 入站 ±600 秒时效校验及回调调试页一致",
"entryorder.match 接入点:app/service/systems/receiving_entry_match.js#matchAfterEntryCompleted 绑定成功且 bindResult.created===true 时调用 _sendCallback(...,'auto_match');重复触发不重复回传,回传失败仅 warn 不影响绑定",
"metadata:entryorder.confirm {source:'inbound_direct_log',entryOrderId};entryorder.match {source:'receiving_entry_match',entryOrderId,receivingId};deliveryorder.confirm {warehouseId,createChannel:'API',syncTarget};stockout.confirm {warehouseId,storeId,sourceType:'API'};deliveryorder.cancel 真实调用点未传(报文内 {})",
"回调调试页 GET /docs/api/openapi/callback-test 按注册表自动预填真实三层报文体 { event, data, metadata }(此前把 sampleData 直接当整个 body)",
"同步 docs/openapi-callback-events.md 与 AI_METHOD_ROUTING.md 5.6 节;新建 docs/api-doc-update-workflow.md",
"文档版本 1.0.0 → 1.1.0"
]
},
{
"version": "2026.09.12-openapi-callback-init",
"date": "2026-09-12",
"type": "added",
"module": "callback",
"summary": "新增 methods/openapi_callback.json:OpenAPI 出站回调(WMS → 外部)接口文档,登记 5 个出站回调事件 entryorder.confirm / entryorder.match / deliveryorder.confirm / stockout.confirm / order.cancel(event 与 query method 同值);协议口径与 docs/openapi-callback-events.md 及 app/service/openapi/callbackRegistry.js#CALLBACK_EVENTS 一致;入站接口仍以 methods/openapi.json 为准。",
"methods": [
"entryorder.confirm",
"entryorder.match",
"deliveryorder.confirm",
"stockout.confirm",
"order.cancel"
],
"notes": [
"触发实现与发送途径:entryorder.confirm(inbound_direct_log.js#qimenEntrySync API 分支,sendWithRetry 直调,throwOnError=true);entryorder.match(receiving_entry_match.js#_sendCallback API 分支,sendWithRetry 直调,当前无调用方);deliveryorder.confirm(order_async.js#finalizeLocalChannelOrdersInternal,sendByAppKey);stockout.confirm(order_async.js#notifyStockoutExternalInternal API 分支,sendByAppKey);order.cancel(openapiMethods/order.js#cancel,sendByAppKey)",
"协议:POST {ApiApp.callback_url}?method=&v=1.0&timestamp=&app_key=&sign=;body 统一 { event, data, metadata };sign = md5(canonicalQuery + selfAppSecret + md5(stableStringify(body)));非 2xx/网络错误重试至多 3 次(间隔 2s→5s→15s,单次超时 30s)",
"已知问题如实记录:timestamp 口径不一致(sendWithRetry 毫秒 vs 调试页秒),统一前不作为规范值;entryorder.match 触发函数 _sendCallback 无调用方(已实现待接入)",
"本文件为出站方向文档(版本 0.0.0 -> 1.0.0),不修改 methods/openapi.json(入站)",
"写入通过 script/update-api-doc.cjs(先 --dry-run 校验)"
]
}
]