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:
parent
4f4128f337
commit
a15c877f04
@ -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;
|
||||
|
||||
@ -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` 等)为追加式历史,保持原样,不回改。
|
||||
|
||||
@ -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",
|
||||
|
||||
@ -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 非空)"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user