[ { "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×tamp=&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 校验)" ] } ]