From a15c877f043e76ca0d669073ca6c90c6f1f69f4c Mon Sep 17 00:00:00 2001 From: liufumingren Date: Tue, 15 Sep 2026 16:18:32 +0800 Subject: [PATCH] =?UTF-8?q?fix(order):=20API=20=E6=B8=A0=E9=81=93=E8=AE=A2?= =?UTF-8?q?=E5=8D=95=E5=90=8C=E6=AD=A5=E6=94=B9=E4=B8=BA=E5=85=88=E5=9B=9E?= =?UTF-8?q?=E4=BC=A0=E7=A1=AE=E8=AE=A4=E3=80=81=E6=88=90=E5=8A=9F=E5=90=8E?= =?UTF-8?q?=E5=86=8D=E6=89=A3=E5=87=8F=E5=BA=93=E5=AD=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 删除 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 --- app/service/systems/order_async.js | 339 ++++++++++++++++---------- docs/openapi-callback-events.md | 31 ++- methods/changes/openapi_callback.json | 17 ++ methods/openapi_callback.json | 40 ++- 4 files changed, 274 insertions(+), 153 deletions(-) diff --git a/app/service/systems/order_async.js b/app/service/systems/order_async.js index 810376d..c2e23e4 100644 --- a/app/service/systems/order_async.js +++ b/app/service/systems/order_async.js @@ -932,139 +932,224 @@ async function resolveOpenApiAppByStoreInternal(service, storeId, warehouseId) { } /** - * 逐单发送 API 渠道订单确认回调(deliveryorder.confirm)。 + * 将 API 渠道订单标记为同步失败(sync_status='error' + 待处理异常)。 * - * 复用 buildQimenDeliveryOrderConfirmDataInternal 组装与奇门 - * taobao.qimen.deliveryorder.confirm 完全一致的 request 报文, - * 每个同步成功的订单发送一次 OpenAPI 回调;单订单组装/发送失败 - * 仅记录 warn 日志,不影响其他订单与主流程。 - * - * appKey 解析优先级:context.appKey 非空时优先使用(不触发合约反查); - * 缺失时按订单货主(orderRow.store_id)合约反查 ApiApp 的 self_app_key。 - * 解析不到 appKey 的订单仅 warn 后跳过,不发请求(保持既有门禁语义)。 + * 与奇门渠道回传失败口径一致:失败不扣减库存、不置 'fin', + * 订单可被重新派发重试(分发前过滤仅跳过 'fin')。 * * @param {Object} service 订单异步服务实例。 - * @param {Object} options 通知参数。 - * @param {number} options.warehouseId 仓库 ID。 - * @param {Object} options.context 同步上下文(appKey 可选,缺失时按订单货主合约反查)。 - * @param {Array} options.successResults 同步成功结果列表。 - * @param {Map} options.orderMap 订单 ID 到主表记录的映射。 - * @param {Map>} options.itemsByOrderId 订单 ID 到明细列表的映射。 - * @return {Promise} 无返回值,失败仅记录 warn 日志。 + * @param {Object} orderModel 订单主模型。 + * @param {number} orderId 订单 ID。 + * @param {number} warehouseId 仓库 ID。 + * @param {string} message 失败原因。 + * @return {Promise} 无返回值,写库失败仅记录 error 日志。 */ -async function notifyApiDeliveryOrderConfirmsInternal(service, options = {}) { - const { - warehouseId, - context = {}, - successResults = [], - orderMap = new Map(), - itemsByOrderId = new Map(), - } = options; - const callbackService = service.ctx.service.openapi && service.ctx.service.openapi.callback; - if (!callbackService || typeof callbackService.sendByAppKey !== 'function') { - return; +async function markApiSyncFailedInternal(service, orderModel, orderId, warehouseId, message) { + try { + await orderModel.update({ + sync_status: 'error', + }, { + where: { + id: orderId, + warehouse_id: warehouseId, + }, + }); + } catch (error) { + service.ctx.logger.error(`[OrderAsyncService.markApiSyncFailed] 更新 sync_status=error 失败 orderId=${orderId}`, { + message: String((error && error.message) || error || '').trim(), + }); } - const successOrderIds = successResults - .map(item => Number(item && item.order_id)) - .filter(orderId => Number.isFinite(orderId) && orderId > 0); - if (successOrderIds.length === 0) { - return; + try { + await markPendingExceptionInternal(service, orderModel, orderId, warehouseId, message); + } catch (error) { + service.ctx.logger.error(`[OrderAsyncService.markApiSyncFailed] 标记待处理异常失败 orderId=${orderId}`, { + message: String((error && error.message) || error || '').trim(), + }); + } +} + +/** + * API 渠道单订单同步:先回传 deliveryorder.confirm,回调成功后才本地扣减库存并置已同步。 + * + * 与奇门渠道(processQmOrderInternal)口径对齐: + * ① 组装与奇门 taobao.qimen.deliveryorder.confirm 完全一致的 request 报文 + * (缺奇门货主编码等组装数据时直接失败); + * ② 解析发送用 appKey:context.appKey 非空优先,缺失时按订单货主合约反查 ApiApp + * (同一批次按货主缓存,N 单 / M 货主 → 2M 次查询,无 N+1); + * ③ 发送回调(sendByAppKey,内部最多 4 次尝试),成功才算平台已确认; + * ④ 回调成功 → 扣减库存 + sync_status='fin';失败/异常 → sync_status='error' + * + 待处理异常,不扣减库存,可重新派发; + * 订单/回调配置缺失(无 store_id、无「启用且 callback_url 非空」的 ApiApp)按失败处理, + * 不再静默跳过,避免订单在平台未确认时被置为已同步。 + * + * @param {Object} service 订单异步服务实例。 + * @param {Object} orderModel 订单主模型。 + * @param {Object} orderItemsModel 订单明细模型。 + * @param {number} orderId 订单 ID。 + * @param {number} warehouseId 仓库 ID。 + * @param {Object} orderRow 订单主表记录。 + * @param {Array} orderItems 订单明细记录。 + * @param {Object} [context] 同步上下文(appKey 可选)。 + * @param {Array} [waybillCodes] 运单号列表。 + * @param {Map} [appByStoreCache] 货主 → ApiApp 反查结果缓存(批内共享)。 + * @return {Promise} 单订单同步结果(status / message / error 等)。 + */ +async function processApiOrderInternal(service, orderModel, orderItemsModel, orderId, warehouseId, orderRow, orderItems, context = {}, waybillCodes = [], appByStoreCache = new Map()) { + if (!orderRow) { + return { + order_id: orderId, + status: 'failed', + message: '发货单不存在', + }; } - // 上下文 appKey 非空时优先使用,保持既有语义,不触发合约反查 - const contextAppKey = String(context.appKey || '').trim(); - // 逐货主缓存合约反查结果:同一批次同货主只查一次库 - const appByStoreCache = new Map(); + const deliveryOrderCode = String(orderRow.delivery_order_code || '').trim(); - // 一次性批量读取运单号(单次查询,避免逐单 N+1), - // 与 syncQmOrdersInternal 的加载方式保持一致 - const waybillCodeMap = await buildOrderWaybillCodeMapInternal(service, successOrderIds, warehouseId); + /** + * 统一失败出口:写 sync_status='error' + 待处理异常后返回失败结果。 + * @param {string} message 失败原因。 + * @param {Object} [extra] 附加返回字段。 + * @return {Promise} 单订单失败结果。 + */ + const failSync = async (message, extra = {}) => { + await markApiSyncFailedInternal(service, orderModel, orderId, warehouseId, message); - for (const syncResult of successResults) { - const orderId = Number(syncResult && syncResult.order_id); + return { + order_id: orderId, + delivery_order_code: deliveryOrderCode, + status: 'failed', + message, + error: message, + ...extra, + }; + }; - try { - const orderRow = orderMap.get(orderId); - if (!orderRow) { - service.ctx.logger.warn(`[OrderAsyncService] deliveryorder.confirm 回调跳过:订单记录缺失 orderId=${orderId}`); - continue; - } + try { + // ① 组装回调报文 + const requestData = await buildQimenDeliveryOrderConfirmDataInternal(service, orderRow, orderItems, { + ...context, + packageExpressCode: Array.isArray(waybillCodes) ? waybillCodes[0] : '', + packageExpressCodes: waybillCodes, + }); - const orderItems = itemsByOrderId.get(orderId) || []; - const waybillCodes = waybillCodeMap.get(orderId) || []; - const requestData = await buildQimenDeliveryOrderConfirmDataInternal(service, orderRow, orderItems, { - ...context, - packageExpressCode: Array.isArray(waybillCodes) ? waybillCodes[0] : '', - packageExpressCodes: waybillCodes, + if (!requestData || !requestData.ownerCode || !requestData.request) { + service.ctx.logger.warn(`[OrderAsyncService.processApiOrder] 回调报文组装数据缺失 orderId=${orderId}`, { + deliveryOrderCode, + ownerCode: requestData && requestData.ownerCode, }); - // 报文组装数据缺失(如缺奇门货主编码)时跳过该订单,与 QM 分支口径一致 - if (!requestData || !requestData.ownerCode || !requestData.request) { - service.ctx.logger.warn(`[OrderAsyncService] deliveryorder.confirm 回调跳过:报文组装数据缺失 orderId=${orderId}`, { - deliveryOrderCode: String(orderRow.delivery_order_code || '').trim(), - ownerCode: requestData && requestData.ownerCode, + return await failSync('发货单缺少奇门货主编码'); + } + + // ② 解析发送用 appKey + const callbackService = service.ctx.service.openapi && service.ctx.service.openapi.callback; + if (!callbackService || typeof callbackService.sendByAppKey !== 'function') { + return await failSync('OpenAPI 回调服务未初始化'); + } + + let resolvedAppKey = String(context.appKey || '').trim(); + if (!resolvedAppKey) { + const storeId = Number(orderRow.store_id) || 0; + if (storeId <= 0) { + service.ctx.logger.warn(`[OrderAsyncService.processApiOrder] 订单缺少货主 store_id orderId=${orderId}`, { + deliveryOrderCode, }); - continue; + + return await failSync('发货单缺少货主 store_id,无法解析回传用 appKey'); } - // 逐单解析发送用 appKey:context.appKey 优先,缺失时按订单货主合约反查; - // 解析不到 appKey 的订单跳过,不发请求(保留门禁语义) - let resolvedAppKey = contextAppKey; + if (!appByStoreCache.has(storeId)) { + appByStoreCache.set(storeId, await resolveOpenApiAppByStoreInternal(service, storeId, warehouseId)); + } + + const resolvedApp = appByStoreCache.get(storeId); + resolvedAppKey = String(resolvedApp && resolvedApp.appKey || '').trim(); + if (!resolvedAppKey) { - const storeId = Number(orderRow.store_id) || 0; - if (storeId <= 0) { - service.ctx.logger.warn(`[OrderAsyncService] deliveryorder.confirm 回调跳过:订单缺少货主 store_id orderId=${orderId}`, { - deliveryOrderCode: String(orderRow.delivery_order_code || '').trim(), - }); - continue; - } + service.ctx.logger.warn(`[OrderAsyncService.processApiOrder] 货主无可用 ApiApp 配置 orderId=${orderId} storeId=${storeId}`, { + deliveryOrderCode, + }); - if (!appByStoreCache.has(storeId)) { - appByStoreCache.set(storeId, await resolveOpenApiAppByStoreInternal(service, storeId, warehouseId)); - } - - const resolvedApp = appByStoreCache.get(storeId); - if (!resolvedApp || !String(resolvedApp.appKey || '').trim()) { - service.ctx.logger.warn(`[OrderAsyncService] deliveryorder.confirm 回调跳过:货主无可用 ApiApp 配置 orderId=${orderId} storeId=${storeId}`, { - deliveryOrderCode: String(orderRow.delivery_order_code || '').trim(), - }); - continue; - } - - resolvedAppKey = String(resolvedApp.appKey).trim(); + return await failSync('货主未配置可用的 OpenAPI 回调(wms_api_app 启用且 callback_url 非空)'); } + } - const callbackResult = await callbackService.sendByAppKey({ + // ③ 发送回调:回调成功才继续本地出库扣减 + let callbackResult = null; + try { + callbackResult = await callbackService.sendByAppKey({ appKey: resolvedAppKey, event: 'deliveryorder.confirm', request: requestData.request, }); - - if (!callbackResult || callbackResult.success !== true) { - service.ctx.logger.warn(`[OrderAsyncService] deliveryorder.confirm 回调失败 orderId=${orderId}`, { - appKey: resolvedAppKey, - deliveryOrderCode: String(orderRow.delivery_order_code || '').trim(), - error: callbackResult && callbackResult.error, - }); - } else { - service.ctx.logger.info(`[OrderAsyncService] deliveryorder.confirm 回调成功 orderId=${orderId}`, { - appKey: resolvedAppKey, - deliveryOrderCode: String(orderRow.delivery_order_code || '').trim(), - }); - } } catch (error) { - service.ctx.logger.warn(`[OrderAsyncService] deliveryorder.confirm 回调异常 orderId=${orderId}`, { - message: String((error && error.message) || error || '').trim(), + const message = `OpenAPI 回调确认异常: ${String((error && error.message) || error || '').trim() || '未知错误'}`; + + service.ctx.logger.error(`[OrderAsyncService.processApiOrder] deliveryorder.confirm 回调异常 orderId=${orderId}`, { + appKey: resolvedAppKey, + deliveryOrderCode, + message, + }); + + return await failSync(message); + } + + if (!callbackResult || callbackResult.success !== true) { + const callbackRetryCount = Number(callbackResult && callbackResult.retryCount) || 0; + const message = `OpenAPI 回调确认失败: ${String((callbackResult && callbackResult.error) || '回调失败').trim()}`; + + service.ctx.logger.error(`[OrderAsyncService.processApiOrder] deliveryorder.confirm 回调失败 orderId=${orderId}`, { + appKey: resolvedAppKey, + deliveryOrderCode, + retryCount: callbackRetryCount, + error: callbackResult && callbackResult.error, + }); + + return await failSync(message, { + callback_retry_count: callbackRetryCount, }); } + + service.ctx.logger.info(`[OrderAsyncService.processApiOrder] deliveryorder.confirm 回调成功,开始本地出库扣减 orderId=${orderId}`, { + appKey: resolvedAppKey, + deliveryOrderCode, + retryCount: Number(callbackResult.retryCount) || 0, + }); + + // ④ 回调成功 → 扣减库存 + 置 sync_status='fin' + const localSyncResult = await processLocalChannelOrderInternal( + service, + CREATE_CHANNEL_API, + orderModel, + orderItemsModel, + orderId, + warehouseId, + orderRow + ); + + return { + ...localSyncResult, + callback_retry_count: Number(callbackResult.retryCount) || 0, + }; + } catch (error) { + const message = `API 渠道同步异常: ${String((error && error.message) || error || '').trim() || '未知错误'}`; + + service.ctx.logger.error(`[OrderAsyncService.processApiOrder] 同步异常 orderId=${orderId}`, { + deliveryOrderCode, + message, + }); + + return await failSync(message); } } /** * 本地渠道(MANUAL / API)订单同步收尾: - * 逐单锁定扣减库存并推进订单同步状态,统计成功/失败数量; - * API 渠道在存在成功订单时,逐单触发 OpenAPI deliveryorder.confirm 回调(fire-and-forget)。 + * MANUAL:逐单锁定扣减库存并置 sync_status='fin'; + * API:逐单先回传 deliveryorder.confirm,回调成功后才扣减库存并置 'fin', + * 回调失败/无可用回调配置则 sync_status='error' + 待处理异常(与奇门渠道口径一致), + * 最后统计成功/失败数量返回。 * * @param {Object} service 订单异步服务实例。 * @param {string} createChannel 创建渠道(MANUAL / API)。 @@ -1165,6 +1250,14 @@ async function finalizeLocalChannelOrdersInternal(service, createChannel, groupe itemsByOrderId.get(itemOrderId).push(orderItem); } + // API 渠道:一次性批量取运单号 + 批内共享货主 appKey 反查缓存, + // 供逐单「先回传 deliveryorder.confirm → 成功才扣减库存」复用(无逐单 N+1 查询) + const isApiChannel = createChannel === CREATE_CHANNEL_API; + const waybillCodeMap = isApiChannel + ? await buildOrderWaybillCodeMapInternal(service, orderIds, warehouseId) + : new Map(); + const appByStoreCache = new Map(); + // dispatch前最终去重,防止同一orderId在列表中重复导致并发双扣 const uniqueOrderIds = [ ...new Set(orderIds) ]; const progressCacheKey = getSyncOrderIdsProgressCacheKey(context.request_id); @@ -1176,6 +1269,20 @@ async function finalizeLocalChannelOrdersInternal(service, createChannel, groupe if (!dispathedOrderRow) { return { order_id: orderId, status: 'skipped', message: '订单已完成同步,跳过' }; } + if (isApiChannel) { + return processApiOrderInternal( + service, + orderModel, + orderItemsModel, + orderId, + warehouseId, + dispathedOrderRow, + itemsByOrderId.get(orderId) || [], + context, + waybillCodeMap.get(orderId) || [], + appByStoreCache + ); + } return processLocalChannelOrderInternal( service, createChannel, @@ -1194,32 +1301,6 @@ async function finalizeLocalChannelOrdersInternal(service, createChannel, groupe const failedCount = syncResults.filter(item => item.status === 'failed').length; const overallSuccess = failedCount === 0 && successCount === syncResults.length; - // 同步成功后触发 OpenAPI 回调通知(fire-and-forget,不阻塞主流程)。 - // appKey 不在此处统一解析:context.appKey 非空时优先使用,缺失时由 - // notifyApiDeliveryOrderConfirmsInternal 按订单货主合约逐单反查(多货主批次各自解析), - // 解析不到 appKey 的订单仅 warn 后跳过,不发请求(保留门禁语义)。 - if (createChannel === CREATE_CHANNEL_API && successCount > 0) { - try { - const callbackService = service.ctx.service.openapi && service.ctx.service.openapi.callback; - - if (callbackService && typeof callbackService.sendByAppKey === 'function') { - const successResults = syncResults.filter(item => item.status === 'success'); - - notifyApiDeliveryOrderConfirmsInternal(service, { - warehouseId, - context, - successResults, - orderMap, - itemsByOrderId, - }).catch(err => { - service.ctx.logger.warn(`[OrderAsyncService] OpenAPI 回调忽略失败: ${err.message}`); - }); - } - } catch (err) { - service.ctx.logger.warn(`[OrderAsyncService] 触发回调异常,不影响主流程: ${err.message}`); - } - } - return { create_channel: createChannel, order_ids: orderIds, @@ -2765,9 +2846,6 @@ class OrderAsyncService extends MainService { async syncStockoutOrders(groupedOrder = {}, context = {}) { return await syncStockoutOrdersInternal(this, groupedOrder, context); } -} - -module.exports = OrderAsyncService; /** * 组装出库单确认回传报文(与奇门 request 节点同层级,OpenAPI 回调复用)。 @@ -2807,3 +2885,6 @@ module.exports = OrderAsyncService; async resolveOpenApiAppByStore(storeId, warehouseId) { return await resolveOpenApiAppByStoreInternal(this, storeId, warehouseId); } +} + +module.exports = OrderAsyncService; diff --git a/docs/openapi-callback-events.md b/docs/openapi-callback-events.md index 840fe8a..f4ec5f2 100644 --- a/docs/openapi-callback-events.md +++ b/docs/openapi-callback-events.md @@ -1,6 +1,6 @@ # OpenAPI 出站回调事件说明 -> 状态:2026-09-13 破坏性协议变更已落代码(报文体 `{ event, data, metadata }` → `{ request }`;`deliveryorder.confirm` 改为逐单发送)。 +> 状态:2026-09-13 破坏性协议变更已落代码(报文体 `{ event, data, metadata }` → `{ request }`;`deliveryorder.confirm` 改为逐单「先回调、成功再扣减库存并置已同步」,失败置 `error` + 待处理异常)。 > 本文档描述 WMS 主动向外部系统推送的 **OpenAPI 出站回调**(出站 HTTP 回调)协议。 > 与 `methods/openapi.json` 描述的**入站** OpenAPI method(`POST /openapi`)方向相反;本文档不属于 `methods/*.json` 的 SSOT 范围。 @@ -10,7 +10,7 @@ - 报文体由 `{ event, data, metadata }` 改为奇门同层级的 `{ request: {...} }`;发送端不再发送数据/元数据,`event` 仅出现在 query 的 `method`。 - 5 个事件的 `request` 结构与奇门对应接口的 `request` 节点同层级(字段口径见第 3 节,与注册表 `request` 模板一致)。 -- `deliveryorder.confirm` 通知对象口径变化:改动前一次回调携带整批 `orderIds`(含失败/跳过);改后仅对 `syncResults` 中 `status==='success'` 的订单逐单发送(成功 N 单 = N 次回调),详见 3.3。 +- `deliveryorder.confirm` 通知对象口径变化:改动前一次回调携带整批 `orderIds`(含失败/跳过);改后 API 渠道**逐单在同步时**发送(同一个分发循环,成功 N 单 = N 次回调),且**回调成功才扣减库存并置 `sync_status='fin'`**;回调失败/异常、报文组装或 appKey 解析失败 → 该单同步失败(`sync_status='error'` + 待处理异常,不扣减库存,可重新派发),详见 3.3。 - 旧报文结构(`{ event, data, metadata }`)已全部废弃:无新旧兼容、无双发,接收方必须同步改造。 ### 1.2 2026-09-12:事件名改为 模块.动作(历史,仍有效) @@ -23,7 +23,7 @@ |---|---|---|---| | `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` | +| `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` | @@ -93,6 +93,7 @@ app_key=APP2024011514301234&method=entryorder.confirm×tamp=1758047400&v=1.0 - 触发条件:非 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 发送途径与配置解析 @@ -191,20 +192,26 @@ app_key=APP2024011514301234&method=entryorder.confirm×tamp=1758047400&v=1.0 ### 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) +- 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`(含失败/跳过) | 仅对 `syncResults` 中 `status==='success'` 的订单逐单发送 | -| 回调次数 | 每批次 1 次 | 成功 N 单 = N 次回调 | +| 通知对象 | 一次回调携带整批 `orderIds`(含失败/跳过) | API 渠道逐单在同步时发送(同一个 `finalizeLocalChannelOrdersInternal` 分发循环,`DISPATCH_BATCH_SIZE=20` 批内并行) | +| 回调次数 | 每批次 1 次 | 成功 N 单 = N 次回调(每单先回调、成功再扣减) | | 报文内容 | 批次汇总 `{ orderIds, status, successCount, failedCount }` | 每单独立奇门同层级 `request` 报文(`buildQimenDeliveryOrderConfirmDataInternal` 组装) | -| 失败处理 | 不阻塞主流程 | 单订单组装/发送失败仅 warn,不影响其他订单与主流程 | +| 失败处理 | 不阻塞主流程 | 回调成功才扣减库存并置 `sync_status='fin'`;回调失败/异常/组装失败 → `sync_status='error'` + 待处理异常(`markPendingException`,写库失败仅记录 error 日志),**不扣减库存**,订单可重新派发(分发前过滤只跳过 `fin`) | -- 查询开销:复用原有主表+明细查询,新增 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 后跳过、不发请求;同步失败的订单不发送 +- 查询开销:复用原有主表+明细查询;运单号仍由 `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 @@ -380,6 +387,6 @@ app_key=APP2024011514301234&method=entryorder.confirm×tamp=1758047400&v=1.0 ## 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_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` 等)为追加式历史,保持原样,不回改。 diff --git a/methods/changes/openapi_callback.json b/methods/changes/openapi_callback.json index fd8ab09..09341e9 100644 --- a/methods/changes/openapi_callback.json +++ b/methods/changes/openapi_callback.json @@ -1,4 +1,21 @@ [ + { + "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", diff --git a/methods/openapi_callback.json b/methods/openapi_callback.json index 7cdf756..8c6c7e7 100644 --- a/methods/openapi_callback.json +++ b/methods/openapi_callback.json @@ -1,7 +1,7 @@ { "module": "openapi_callback", "description": "开放 API 出站回调定义(出站方向:WMS → 外部)。WMS 在业务完成后按 ApiApp 配置的 callback_url 主动推送事件通知:query 携带 method/v/timestamp/app_key/sign,报文体统一为奇门同层级的 { request: {...} }(event 仅出现在 query 的 method),使用 MD5 签名鉴权。入站接口请参阅 openapi.json。", - "version": "1.3.0", + "version": "1.4.0", "updatedAt": "2026-09-13", "http": { "path": "{ApiApp.callback_url}", @@ -495,7 +495,7 @@ }, { "method": "deliveryorder.confirm", - "description": "订单发货完成出站回调(逐单发送)。触发前提:createChannel=API 且本批存在同步成功订单(仅对 syncResults 中 status==='success' 的订单发送,成功 N 单 = N 次回调;fire-and-forget,失败仅 warn,不阻塞主流程)。发送用 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(订单缺 store_id / 无授权关系 / 无可用 ApiApp 配置)时跳过该订单并告警,不发送请求;同步失败的订单不发送。触发实现:app/service/systems/order_async.js#finalizeLocalChannelOrdersInternal → notifyApiDeliveryOrderConfirmsInternal(复用 buildQimenDeliveryOrderConfirmDataInternal 组装与奇门 taobao.qimen.deliveryorder.confirm 完全一致的 request 报文;复用原有主表+明细查询,新增 1 次运单号批量查询,无 N+1)。", + "description": "订单发货完成出站回调(逐单「先回调、成功再扣减」)。触发前提:createChannel=API,逐单在 finalizeLocalChannelOrdersInternal 分发循环(DISPATCH_BATCH_SIZE=20 批内并行)内直接发送,不再要求本批先出现同步成功订单。每单流程:① 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 缓存,无 N+1)→③ sendByAppKey 发送 deliveryorder.confirm(最多 4 次尝试)→④ 回调成功才调用 processLocalChannelOrderInternal 扣减库存并置 sync_status='fin';失败统一走 markApiSyncFailedInternal:回写 sync_status='error' + markPendingException(写库失败仅记录 error 日志),不扣减库存、不置 fin,订单可重新派发(分发前过滤只跳过 fin)。触发实现:app/service/systems/order_async.js#finalizeLocalChannelOrdersInternal → processApiOrderInternal(复用 buildQimenDeliveryOrderConfirmDataInternal 组装与奇门 taobao.qimen.deliveryorder.confirm 完全一致的 request 报文;运单号由 buildOrderWaybillCodeMapInternal 批量取、仅 API 渠道构建,无 N+1)。", "isNeedAuth": true, "isNeedLogin": false, "headers": [], @@ -854,35 +854,51 @@ "errors": [ { "code": 400, - "message": "接收方返回 400(如参数/验签不通过):WMS 视为回调失败,进入重试,至多 3 次(间隔 2s→5s→15s),全部失败后判定最终失败" + "message": "接收方返回 400(如参数/验签不通过):WMS 视为回调失败,进入重试,至多 3 次(间隔 2s→5s→15s),4 次尝试全部失败后该订单同步判定失败(sync_status='error' + 待处理异常,不扣减库存,可重新派发);订单结果 message 形如「OpenAPI 回调确认失败: 回调返回非 2xx 状态码: 400」并附 callback_retry_count" }, { "code": 401, - "message": "接收方返回 401(鉴权失败):处理同 400,重试至多 3 次后判定最终失败" + "message": "接收方返回 401(鉴权失败):处理同 400,4 次尝试后该订单同步判定失败(sync_status='error' + 待处理异常,不扣减库存)" }, { "code": 403, - "message": "接收方返回 403(拒绝访问):处理同 400,重试至多 3 次后判定最终失败" + "message": "接收方返回 403(拒绝访问):处理同 400,4 次尝试后该订单同步判定失败(sync_status='error' + 待处理异常,不扣减库存)" }, { "code": "5xx", - "message": "接收方返回 5xx(服务端错误):处理同 400,重试至多 3 次后判定最终失败" + "message": "接收方返回 5xx(服务端错误):处理同 400,4 次尝试后该订单同步判定失败(sync_status='error' + 待处理异常,不扣减库存)" }, { "code": "NETWORK_ERROR", - "message": "网络错误或单次请求超时(30s):处理同非 2xx,重试至多 3 次后判定最终失败" + "message": "网络错误或单次请求超时(30s):处理同非 2xx,4 次尝试后该订单同步判定失败(sync_status='error' + 待处理异常,不扣减库存)" + }, + { + "code": "CALLBACK_EXCEPTION", + "message": "发送过程抛异常:订单结果 message 形如「OpenAPI 回调确认异常: {error}」,处理同回调失败(sync_status='error' + 待处理异常,不扣减库存,可重新派发)" + }, + { + "code": "OWNER_CODE_MISSING", + "message": "报文组装失败:发货单缺少奇门货主编码(ownerCode 缺失),该订单同步失败(sync_status='error' + 待处理异常,不扣减库存),订单结果 message 为「发货单缺少奇门货主编码」" + }, + { + "code": "STORE_ID_MISSING", + "message": "发货单缺少货主 store_id,无法解析回传用 appKey:该订单同步失败(sync_status='error' + 待处理异常,不扣减库存),订单结果 message 为「发货单缺少货主 store_id,无法解析回传用 appKey」" + }, + { + "code": "NO_API_APP_CONFIG", + "message": "货主未配置可用的 OpenAPI 回调(wms_api_app 启用且 callback_url 非空):该订单同步失败(sync_status='error' + 待处理异常,不扣减库存),订单结果 message 为「货主未配置可用的 OpenAPI 回调(wms_api_app 启用且 callback_url 非空)」" } ], "notes": [ "本文件描述出站方向(WMS → 外部)回调;入站接口请参阅 methods/openapi.json", "签名算法:sign = md5(canonicalQuery + selfAppSecret + md5(stableStringify(body))),小写十六进制;canonicalQuery 为 query 中除 sign/signature 外、值非 undefined 的参数按 key 升序拼成的 key=value&… 串(值为原始字符串,不 URL 编码),selfAppSecret 为 api_app.self_app_secret", - "重试策略:非 2xx 响应或网络错误触发重试,至多重试 3 次(即最多 4 次尝试),间隔 2s→5s→15s,单次请求超时 30s;全部失败后判定回调失败", + "重试策略:非 2xx 响应或网络错误触发重试,至多重试 3 次(即最多 4 次尝试),间隔 2s→5s→15s,单次请求超时 30s;4 次尝试后仍失败 ⇒ 该订单同步判定失败(sync_status='error' + 待处理异常,不扣减库存,可重新派发)", "报文体统一为奇门同层级的 { request: {...} }(发送端统一包装 body = { request: request || {} }),event 仅出现在 query 的 method", "事件注册表:app/service/openapi/callbackRegistry.js#CALLBACK_EVENTS;调试页:GET /docs/api/openapi/callback-test(app/controller/openapiCallback.js 按注册表自动预填完整报文体 { request: {...} },可编辑后发送)", - "发送途径:sendByAppKey;appKey 解析优先级:context.appKey 非空时优先(不触发合约反查),缺失时按订单货主(store_id + warehouse_id)合约反查 resolveOpenApiAppByStoreInternal —— wms_store_warehouse(auth_status=2) → wms_api_app(contract_id 且 is_enabled=1 且 callback_url 非空) 的 self_app_key;同一批次按货主 Map 缓存(N 个成功单 / M 个货主 → 2M 次查询,无 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(订单缺 store_id / 无授权关系 / 无可用 ApiApp 配置)的订单 warn 后跳过,不发请求", - "逐单发送语义(破坏性变更):改动前一次回调携带整批 orderIds(含失败/跳过);改后仅对 syncResults 中 status==='success' 的订单逐单发送,成功 N 单 = N 次回调;组装/发送失败仅 warn,不影响其他订单与主流程", - "fire-and-forget 触发:回调结果不影响订单同步主流程" + "发送途径:sendByAppKey;appKey 解析优先级:context.appKey 非空时优先(不触发合约反查),缺失时按订单货主(store_id + warehouse_id)合约反查 resolveOpenApiAppByStoreInternal —— wms_store_warehouse(auth_status=2) → wms_api_app(contract_id 且 is_enabled=1 且 callback_url 非空) 的 self_app_key;同一批次按货主 Map 缓存(N 单 / M 货主 → 2M 次查询,无 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(订单缺 store_id / 无授权关系 / 无可用 ApiApp 配置)不再静默跳过:按失败处理(sync_status='error' + 待处理异常,不扣减库存,可重新派发)", + "逐单先回调后扣减(2026-09-13 破坏性变更):触发前提不再是「本批存在同步成功订单」,改为逐单在 finalizeLocalChannelOrdersInternal 分发循环(DISPATCH_BATCH_SIZE=20 批内并行)内直接处理;processApiOrderInternal 流程 ① 组装报文(缺 ownerCode → 失败)→ ② 解析 appKey → ③ sendByAppKey 发送(最多 4 次尝试)→ ④ 回调成功才调用 processLocalChannelOrderInternal 扣减库存并置 sync_status='fin';成功 N 单 = N 次回调(每单先回调、成功再扣减,不再是先扣减、后异步回调)", + "失败处理(2026-09-13):回调失败/异常、报文组装失败、appKey 解析失败统一走 markApiSyncFailedInternal(sync_status='error' + markPendingException,写库失败仅记录 error 日志),不扣减库存、不置 fin,订单可重新派发(分发前过滤只跳过 fin)。失败文案:OpenAPI 回调确认失败: {error}(如「OpenAPI 回调确认失败: 回调返回非 2xx 状态码: 400」,附 callback_retry_count)/ OpenAPI 回调确认异常: ... / 发货单缺少奇门货主编码 / 发货单缺少货主 store_id,无法解析回传用 appKey / 货主未配置可用的 OpenAPI 回调(wms_api_app 启用且 callback_url 非空)" ] }, {