WMS_MAIN/app/schedule/consume_waybill_allocate_queue.js
liufumingren da7df4139d feat(order): 新增 need_oms_waybill 回 OMS 取号标记与本地取号分流
- 模型/迁移:wms_order_delivery 新增 need_oms_waybill TINYINT(4) NOT NULL DEFAULT 0,
  迁移覆盖基表与全部分表(含 _history/_dispatch/_outsourced),幂等且 down 可回滚
- 写入链路:openapi 请求根节点 need_oms_waybill(兼容 camelCase needOmsWaybill)→
  openapiMethods/deliveryorder.js 透传;delivery_order.js 仅 API 来源可能为 1,
  QM/MANUAL/STOCKOUT 一律强制 0(见相邻提交)
- 取号分流:need_oms_waybill=1 的订单不参与本地自动分配快递
  1. asyncProcessOrderCreated 不入本地取号队列,写 ORDER_NEED_OMS_WAYBILL_WAIT 操作日志
  2. express.createWaybillCodePipeline 按订单级标记过滤(同订单全部 business_key 一并跳过),
     返回值新增 skipped_need_oms_waybill_order_ids
  3. schedule/consume_waybill_allocate_queue 将对应队列行置终态 waiting_oms
     (不再走 pending 重试 → failed)
- waybill_allocate_queue.status 注释补充 waiting_oms 语义(STRING(20),无需迁移)
- test: delivery_order.asyncProcessOrderCreated.test.js 新增分流/保持本地取号用例,
  express.createWaybillCodePipeline.skipCancelled.test.js 补齐返回字段断言
2026-09-13 15:30:55 +08:00

272 lines
9.4 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

'use strict';
/**
* 定时消费订单创建时入队的自动分配快递队列(wms_waybill_allocate_queue)。
*
* 背景:订单创建后的异步流程逐单直接取号,大批量订单创建时 N 条并发取号事务
* 与结算事务产生 wms_store_warehouse / wms_order_express 的 AB-BA 死锁。
* 本任务按仓库+货主串行消费,保证同一签约关系下同一时刻只有一个取号事务在跑。
*
* 截单语义:订单创建时已判定(截单/未审核不入队),已入队的正常消费,消费侧不再校验截单。
* 间隔 15 秒、type: worker(仅一个 worker 执行),带重入保护。
*/
const MAX_CONSUME_ROWS_PER_WINDOW = 200;
const MAX_RETRY_COUNT = 3;
const RETRY_BASE_DELAY_MS = 60 * 1000;
const PROCESSING_STALE_MS = 10 * 60 * 1000;
const MAX_ERROR_MESSAGE_LENGTH = 500;
module.exports = {
schedule: {
interval: '15s',
type: 'worker',
immediate: false,
disable: false,
},
async task(ctx) {
// 防止重入
if (ctx.app._consumeWaybillAllocateQueueRunning) return;
ctx.app._consumeWaybillAllocateQueueRunning = true;
try {
await consumePendingRows(ctx);
} catch (err) {
ctx.logger.error(`[consume-waybill-allocate-queue] 消费异常: ${err.message}`, { stack: err.stack });
} finally {
ctx.app._consumeWaybillAllocateQueueRunning = false;
}
},
};
/**
* 批量更新队列行状态。
* @param {Object} ctx Egg 上下文。
* @param {Array<Object>} rows 队列行(含 id)。
* @param {string} status 目标状态。
* @param {string|null} errorMessage 失败原因。
* @return {Promise<void>} 无返回值。
*/
async function updateQueueRowsStatus(ctx, rows, status, errorMessage) {
const queueModel = ctx.model && ctx.model.WaybillAllocateQueue;
if (!queueModel || !Array.isArray(rows) || rows.length === 0) {
return;
}
const { Op } = ctx.app.Sequelize;
const ids = rows.map(row => Number(row.id)).filter(id => Number.isInteger(id) && id > 0);
if (ids.length === 0) {
return;
}
await queueModel.update({
status,
error_message: errorMessage ? String(errorMessage).slice(0, MAX_ERROR_MESSAGE_LENGTH) : null,
updated_at: new Date(),
}, {
where: {
id: {
[Op.in]: ids,
},
},
});
}
/**
* 组消费失败或未完成时:重试次数+1,未超限退回 pending(带退避),超限转 failed。
* @param {Object} ctx Egg 上下文。
* @param {Array<Object>} rows 队列行。
* @param {string} errorMessage 失败原因。
* @param {boolean} failImmediately 是否立即判失败(如 warehouse_id 缺失,重试无意义)。
* @return {Promise<void>} 无返回值。
*/
async function markGroupRetryOrFailed(ctx, rows, errorMessage, failImmediately) {
const queueModel = ctx.model && ctx.model.WaybillAllocateQueue;
if (!queueModel || !Array.isArray(rows) || rows.length === 0) {
return;
}
const normalizedErrorMessage = String(errorMessage || '运单分配失败');
for (const row of rows) {
const rowId = Number(row.id);
if (!Number.isInteger(rowId) || rowId <= 0) {
continue;
}
const retryCount = Number(row.retry_count) || 0;
if (failImmediately || retryCount + 1 >= MAX_RETRY_COUNT) {
await queueModel.update({
status: 'failed',
retry_count: retryCount + 1,
error_message: normalizedErrorMessage.slice(0, MAX_ERROR_MESSAGE_LENGTH),
updated_at: new Date(),
}, {
where: { id: rowId },
});
} else {
const delay = (retryCount + 1) * RETRY_BASE_DELAY_MS;
await queueModel.update({
status: 'pending',
retry_count: retryCount + 1,
next_retry_at: new Date(Date.now() + delay),
error_message: null,
updated_at: new Date(),
}, {
where: { id: rowId },
});
}
}
}
/**
* 拉取并消费待分配队列。
* @param {Object} ctx Egg 上下文。
* @return {Promise<void>} 无返回值。
*/
async function consumePendingRows(ctx) {
const queueModel = ctx.model && ctx.model.WaybillAllocateQueue;
const expressService = ctx.service && ctx.service.systems && ctx.service.systems.express;
if (!queueModel || typeof queueModel.findAll !== 'function'
|| !expressService || typeof expressService.createWaybillCodePipeline !== 'function') {
return;
}
const { Op } = ctx.app.Sequelize;
// 1) 兜底恢复:上次运行中断遗留的 processing 行退回 pending
await queueModel.update({
status: 'pending',
updated_at: new Date(),
}, {
where: {
status: 'processing',
updated_at: {
[Op.lt]: new Date(Date.now() - PROCESSING_STALE_MS),
},
},
});
// 2) 拉取待消费行
const now = new Date();
const pendingRows = await queueModel.findAll({
where: {
status: 'pending',
[Op.or]: [
{ next_retry_at: null },
{ next_retry_at: { [Op.lte]: now } },
],
},
order: [[ 'id', 'ASC' ]],
limit: MAX_CONSUME_ROWS_PER_WINDOW,
raw: true,
});
if (!Array.isArray(pendingRows) || pendingRows.length === 0) {
return;
}
// 3) 标记消费中(单 worker + 重入保护下仅作状态记录)
const pendingIds = pendingRows.map(row => Number(row.id)).filter(id => Number.isInteger(id) && id > 0);
if (pendingIds.length > 0) {
await queueModel.update({
status: 'processing',
updated_at: new Date(),
}, {
where: {
id: {
[Op.in]: pendingIds,
},
},
});
}
// 4) 按 warehouse_id + store_id 分组,逐组串行消费
const groupMap = new Map();
for (const row of pendingRows) {
const warehouseId = Number(row.warehouse_id) || 0;
const storeId = Number(row.store_id) || 0;
const groupKey = `${warehouseId}:${storeId}`;
if (!groupMap.has(groupKey)) {
groupMap.set(groupKey, {
warehouseId,
storeId,
rows: [],
});
}
groupMap.get(groupKey).rows.push(row);
}
const orderExpressModel = ctx.model && ctx.model.OrderExpress;
for (const group of groupMap.values()) {
const orders = group.rows
.map(row => {
const orderId = Number(row.order_id);
const businessKey = Number(row.business_key) || 1;
return { order_id: orderId, business_key: businessKey };
})
.filter(order => Number.isInteger(order.order_id) && order.order_id > 0);
if (group.warehouseId <= 0 || orders.length === 0) {
await markGroupRetryOrFailed(ctx, group.rows, '队列数据缺少有效 warehouse_id/order_id', true);
continue;
}
try {
const pipelineResult = await expressService.createWaybillCodePipeline(orders, {
awaitTasks: true,
warehouseId: group.warehouseId,
});
// 需要回 OMS 取号的订单已由流水线分流:对应队列行置等待终态,不参与本地重试,
// 等外部 OMS 取号能力开发完成后再统一处理。
const needOmsWaybillOrderIdSet = new Set(
(pipelineResult && Array.isArray(pipelineResult.skipped_need_oms_waybill_order_ids)
? pipelineResult.skipped_need_oms_waybill_order_ids
: [])
.map(orderId => Number(orderId))
.filter(orderId => Number.isInteger(orderId) && orderId > 0)
);
const waitingRows = group.rows.filter(row => needOmsWaybillOrderIdSet.has(Number(row.order_id)));
const allocatableRows = group.rows.filter(row => !needOmsWaybillOrderIdSet.has(Number(row.order_id)));
if (waitingRows.length > 0) {
await updateQueueRowsStatus(ctx, waitingRows, 'waiting_oms', '等待外部OMS取号');
ctx.logger.info(`[consume-waybill-allocate-queue] 组内订单需要回 OMS 取号,已置等待态 warehouse_id=${group.warehouseId} store_id=${group.storeId} waiting=${waitingRows.length}`);
}
// 5) 判定结果:取到单号(status=1)的订单视为完成(仅统计参与本地取号的队列行)
const doneKeySet = new Set();
if (orderExpressModel && typeof orderExpressModel.findAll === 'function') {
const doneRows = await orderExpressModel.findAll({
where: {
warehouse_id: group.warehouseId,
[Op.or]: orders.map(order => ({
order_id: order.order_id,
business_key: order.business_key,
})),
status: 1,
},
attributes: [ 'order_id', 'business_key' ],
raw: true,
});
for (const doneRow of Array.isArray(doneRows) ? doneRows : []) {
doneKeySet.add(`${Number(doneRow.order_id)}:${Number(doneRow.business_key)}`);
}
}
const doneRows = allocatableRows.filter(row => doneKeySet.has(`${Number(row.order_id)}:${Number(row.business_key) || 1}`));
const restRows = allocatableRows.filter(row => !doneKeySet.has(`${Number(row.order_id)}:${Number(row.business_key) || 1}`));
await updateQueueRowsStatus(ctx, doneRows, 'done', null);
await markGroupRetryOrFailed(ctx, restRows, '运单分配未完成', false);
ctx.logger.info(`[consume-waybill-allocate-queue] 组消费完成 warehouse_id=${group.warehouseId} store_id=${group.storeId} total=${group.rows.length} done=${doneRows.length} rest=${restRows.length} waiting_oms=${waitingRows.length}`);
} catch (error) {
ctx.logger.error(`[consume-waybill-allocate-queue] 组消费失败 warehouse_id=${group.warehouseId} store_id=${group.storeId}: ${error.message}`);
await markGroupRetryOrFailed(ctx, group.rows, error && error.message ? error.message : String(error), false);
}
}
}