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
This commit is contained in:
liufumingren 2026-09-15 16:18:32 +08:00
parent 4f4128f337
commit a15c877f04
4 changed files with 274 additions and 153 deletions

View File

@ -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<Object>} options.successResults 同步成功结果列表。
* @param {Map<number, Object>} options.orderMap 订单 ID 到主表记录的映射。
* @param {Map<number, Array<Object>>} options.itemsByOrderId 订单 ID 到明细列表的映射。
* @return {Promise<void>} 无返回值,失败仅记录 warn 日志。
* @param {Object} orderModel 订单主模型。
* @param {number} orderId 订单 ID。
* @param {number} warehouseId 仓库 ID。
* @param {string} message 失败原因。
* @return {Promise<void>} 无返回值,写库失败仅记录 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<Object>} orderItems 订单明细记录。
* @param {Object} [context] 同步上下文(appKey 可选)。
* @param {Array<string>} [waybillCodes] 运单号列表。
* @param {Map<number, Object>} [appByStoreCache] 货主 → ApiApp 反查结果缓存(批内共享)。
* @return {Promise<Object>} 单订单同步结果(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<Object>} 单订单失败结果。
*/
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;

View File

@ -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&timestamp=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&timestamp=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&timestamp=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` 等)为追加式历史,保持原样,不回改。

View File

@ -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",

View File

@ -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 非空)"
]
},
{