WMS_MAIN/methods/changes/openapi_callback.json
liufumingren a15c877f04 fix(order): API 渠道订单同步改为先回传确认、成功后再扣减库存
- 删除 notifyApiDeliveryOrderConfirmsInternal(原「同步完成后 fire-and-forget
  逐单回调、失败仅 warn」),新增 processApiOrderInternal 在同一个分发循环内逐单
  处理:组装 deliveryorder.confirm 报文 → 解析发送用 appKey → sendByAppKey
  (最多 4 次尝试)→ 回调成功才扣减库存并置 sync_status='fin'
- 新增 markApiSyncFailedInternal:回调失败/异常、报文组装配不上货主编码、
  解析不到 appKey 等一律置 sync_status='error' + 待处理异常,不扣减库存、不置
  fin,订单可重新派发(分发前过滤仅跳过 fin)
- 解析不到 appKey 的订单不再静默跳过,改为按失败处理
- 同步 docs/openapi-callback-events.md、methods/openapi_callback.json 与
  methods/changes/openapi_callback.json
2026-09-15 16:18:32 +08:00

98 lines
11 KiB
JSON
Raw Permalink 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-confirm-before-deduct",
"date": "2026-09-13",
"type": "updated",
"summary": "deliveryorder.confirm 同步顺序与奇门渠道对齐:删除 notifyApiDeliveryOrderConfirmsInternal(原「同步完成后 fire-and-forget 逐单回调,失败仅 warn」),新增 processApiOrderInternal 逐单「先回调、成功再扣减库存并置 sync_status='fin'」,失败统一 markApiSyncFailedInternal 回写 sync_status='error' + 待处理异常、不扣减库存、可重新派发;解析不到 appKey 的订单不再静默跳过,改为按失败处理。文档版本 1.3.0 → 1.4.0。",
"methods": [
"deliveryorder.confirm"
],
"notes": [
"代码(app/service/systems/order_async.js,API 渠道):删除 notifyApiDeliveryOrderConfirmsInternal;新增 processApiOrderInternal(逐单):① buildQimenDeliveryOrderConfirmDataInternal 组装报文(缺 ownerCode → 失败)→ ② 解析发送用 appKey(context.appKey 优先,缺失时按 store_id + warehouse_id 合约反查 wms_store_warehouse(auth_status=2) → wms_api_app(is_enabled=1 且 callback_url 非空) 的 self_app_key,同批次按货主 Map 缓存)→ ③ sendByAppKey 发送 deliveryorder.confirm(最多 4 次尝试)→ ④ 回调成功才调用 processLocalChannelOrderInternal 扣减库存并置 sync_status='fin'",
"新增 markApiSyncFailedInternal:失败统一回写 sync_status='error' + markPendingException(写库失败仅记录 error 日志),不扣减库存、不置 fin,订单可重新派发(分发前过滤只跳过 fin)",
"失败文案:回调失败「OpenAPI 回调确认失败: {error}」(如「OpenAPI 回调确认失败: 回调返回非 2xx 状态码: 400」,附 callback_retry_count)/ 回调抛异常「OpenAPI 回调确认异常: ...」/ 报文组装缺货主编码「发货单缺少奇门货主编码」/ 缺 store_id「发货单缺少货主 store_id,无法解析回传用 appKey」/ 无可用 ApiApp「货主未配置可用的 OpenAPI 回调(wms_api_app 启用且 callback_url 非空)」",
"未变:appKey 解析优先级与反查口径;报文复用 buildQimenDeliveryOrderConfirmDataInternal;运单号仍由 buildOrderWaybillCodeMapInternal 批量取(现在在 finalizeLocalChannelOrdersInternal 内、仅 API 渠道构建);仍逐单发送(成功 N 单 = N 次回调),但现在每单是「先回调、成功再扣减」而不是「先扣减、后异步回调」",
"触发条件表述变更:不再是「本批存在同步成功订单后才发」,而是逐单在同步时发送(同一个 finalizeLocalChannelOrdersInternal 分发循环里,DISPATCH_BATCH_SIZE=20 批内并行)",
"同步 docs/openapi-callback-events.md(状态/§1.1/§1.2 事件表/§3.3/§2.5/§6)与 AI_METHOD_ROUTING.md 5.6;本次仅同步文档,未修改任何业务代码;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)"
]
},
{
"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 校验)"
]
}
]