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 补齐返回字段断言
This commit is contained in:
liufumingren 2026-09-13 15:30:55 +08:00
parent dfaaa7f060
commit da7df4139d
8 changed files with 287 additions and 20 deletions

View File

@ -92,6 +92,12 @@ module.exports = app => {
defaultValue: 'MANUAL',
comment: '创建来源渠道',
},
need_oms_waybill: {
type: TINYINT(4),
allowNull: false,
defaultValue: 0,
comment: '是否需要回OMS取号:0不需要 1需要(仅openapi创建来源使用,其他默认0)',
},
source_order_codes: {
type: TEXT,
allowNull: true,

View File

@ -47,7 +47,7 @@ module.exports = app => {
type: STRING(20),
allowNull: false,
defaultValue: 'pending',
comment: '状态:pending/processing/done/failed',
comment: '状态:pending/processing/done/failed/waiting_oms(waiting_oms=需要回 OMS 取号,等待外部接入,终态不重试)',
},
retry_count: {
type: INTEGER(3),

View File

@ -215,12 +215,28 @@ async function consumePendingRows(ctx) {
}
try {
await expressService.createWaybillCodePipeline(orders, {
const pipelineResult = await expressService.createWaybillCodePipeline(orders, {
awaitTasks: true,
warehouseId: group.warehouseId,
});
// 5) 判定结果:取到单号(status=1)的订单视为完成
// 需要回 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({
@ -240,13 +256,13 @@ async function consumePendingRows(ctx) {
}
}
const doneRows = group.rows.filter(row => doneKeySet.has(`${Number(row.order_id)}:${Number(row.business_key) || 1}`));
const restRows = group.rows.filter(row => !doneKeySet.has(`${Number(row.order_id)}:${Number(row.business_key) || 1}`));
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}`);
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);

View File

@ -66,7 +66,12 @@ class OpenapiDeliveryorderService extends MainService {
*/
async create(payload = {}) {
const { body = {} } = payload;
const { deliveryOrder, orderLines } = body;
const {
deliveryOrder,
orderLines,
need_oms_waybill: needOmsWaybillSnake,
needOmsWaybill,
} = body;
if (!deliveryOrder || !deliveryOrder.deliveryOrderCode) {
return this.fail('deliveryOrder 参数缺失或不完整');
@ -76,10 +81,13 @@ class OpenapiDeliveryorderService extends MainService {
}
try {
// need_oms_waybill 在请求根节点传入(不在 deliveryOrder 内),
// 兼容 snake_case / camelCase 两种写法,仅 openapi(API) 来源会落库生效。
const data = {
request: {
deliveryOrder,
orderLines,
need_oms_waybill: needOmsWaybillSnake ?? needOmsWaybill,
},
};

View File

@ -2518,7 +2518,7 @@ class ExpressService extends Service {
[Op.ne]: 'cancel',
},
},
attributes: [ 'id', 'sys_platform_code', 'logistics_code', 'sys_platform_name', 'logistics_name', 'store_id', 'pay_no', 'from_key', 'intercept_status', 'lock_status' ],
attributes: [ 'id', 'sys_platform_code', 'logistics_code', 'sys_platform_name', 'logistics_name', 'store_id', 'pay_no', 'from_key', 'intercept_status', 'lock_status', 'need_oms_waybill' ],
raw: true,
});
@ -2542,7 +2542,7 @@ class ExpressService extends Service {
[Op.ne]: 'cancel',
},
},
attributes: [ 'id', 'sys_platform_code', 'logistics_code', 'sys_platform_name', 'logistics_name', 'store_id', 'pay_no', 'from_key', 'intercept_status', 'lock_status' ],
attributes: [ 'id', 'sys_platform_code', 'logistics_code', 'sys_platform_name', 'logistics_name', 'store_id', 'pay_no', 'from_key', 'intercept_status', 'lock_status', 'need_oms_waybill' ],
raw: true,
});
}
@ -2578,22 +2578,41 @@ class ExpressService extends Service {
skippedLockedOrderIds,
});
}
// 需要回 OMS 取号的订单分流:不参与本地分配快递,等外部 OMS 取号能力接入后单独处理。
// need_oms_waybill 为订单级标记(仅 openapi 创建来源可能为 1),同一订单的所有 business_key 一并跳过。
const needOmsWaybillOrderIdSet = new Set(activeOrders
.filter(order => Number(order && order.need_oms_waybill) === 1)
.map(order => Number(order && order.id || 0))
.filter(orderId => Number.isInteger(orderId) && orderId > 0));
const skippedNeedOmsWaybillOrderIds = Array.from(needOmsWaybillOrderIdSet);
const allocatableOrders = activeOrders
.filter(order => !needOmsWaybillOrderIdSet.has(Number(order && order.id || 0)));
if (skippedNeedOmsWaybillOrderIds.length > 0) {
this.ctx.logger.info('[ExpressService.createWaybillCodePipeline] 跳过需要回 OMS 取号的订单', {
traceId,
warehouseId,
skippedNeedOmsWaybillOrderIds,
});
}
this.ctx.logger.info('[ExpressService.createWaybillCodePipeline] 订单筛选结果', {
traceId,
warehouseId,
inputOrderCount: orderList.length,
currentCount: (Array.isArray(currentOrders) ? currentOrders : []).length,
dispatchCount: dispatchOrders.length,
matchedOrderCount: activeOrders.length,
matchedOrderCount: allocatableOrders.length,
skippedInterceptedOrderIds,
skippedLockedOrderIds,
skippedNeedOmsWaybillOrderIds,
});
// 【step1.5】过滤已分配运单号(status=1)且传入 business_key=1 的订单,避免重复分配。
const orderExpressModel = this.ctx.model && this.ctx.model.OrderExpress;
let filteredOrdersArr = activeOrders;
if (orderExpressModel && activeOrders.length > 0) {
const orderIds = activeOrders.map(o => Number(o.id)).filter(id => id > 0);
let filteredOrdersArr = allocatableOrders;
if (orderExpressModel && allocatableOrders.length > 0) {
const orderIds = allocatableOrders.map(o => Number(o.id)).filter(id => id > 0);
const completedRows = await orderExpressModel.findAll({
where: {
order_id: { [Op.in]: orderIds },
@ -2608,8 +2627,8 @@ class ExpressService extends Service {
skipSet.add(`${Number(row.order_id)}:${Number(row.business_key)}`);
}
if (skipSet.size > 0) {
const beforeCount = activeOrders.length;
filteredOrdersArr = activeOrders.filter(order => {
const beforeCount = allocatableOrders.length;
filteredOrdersArr = allocatableOrders.filter(order => {
const matchedExpress = orderList.find(express => Number(order.id) === Number(express.order_id));
const businessKey = matchedExpress ? Number(matchedExpress.business_key) : 1;
if (businessKey === 1 && skipSet.has(`${Number(order.id)}:1`)) {
@ -2621,7 +2640,7 @@ class ExpressService extends Service {
this.ctx.logger.info('[ExpressService.createWaybillCodePipeline] 跳过已分配运单号(business_key=1)的订单', {
traceId,
skippedCount: beforeCount - filteredOrdersArr.length,
skippedOrderIds: activeOrders
skippedOrderIds: allocatableOrders
.filter(order => {
const matchedExpress = orderList.find(express => Number(order.id) === Number(express.order_id));
const businessKey = matchedExpress ? Number(matchedExpress.business_key) : 1;
@ -2634,11 +2653,20 @@ class ExpressService extends Service {
}
if (filteredOrdersArr.length === 0) {
this.ctx.logger.info('[ExpressService.createWaybillCodePipeline] 所有订单均已分配运单号,无需处理', { traceId });
const noAllocatableByNeedOms = allocatableOrders.length === 0 && skippedNeedOmsWaybillOrderIds.length > 0;
const emptyMessage = noAllocatableByNeedOms
? '订单需要回 OMS 取号,已跳过本地分配快递,等待外部 OMS 取号'
: '所有订单均已分配运单号,无需处理';
this.ctx.logger.info('[ExpressService.createWaybillCodePipeline] 无可处理订单', {
traceId,
needOmsWaybillOnly: noAllocatableByNeedOms,
skippedNeedOmsWaybillOrderIds,
});
return {
message: '所有订单均已分配运单号,无需处理',
message: emptyMessage,
skipped_intercepted_order_ids: skippedInterceptedOrderIds,
skipped_locked_order_ids: skippedLockedOrderIds,
skipped_need_oms_waybill_order_ids: skippedNeedOmsWaybillOrderIds,
};
}
@ -2745,6 +2773,7 @@ class ExpressService extends Service {
message: '分配快递任务已提交',
skipped_intercepted_order_ids: skippedInterceptedOrderIds,
skipped_locked_order_ids: skippedLockedOrderIds,
skipped_need_oms_waybill_order_ids: skippedNeedOmsWaybillOrderIds,
};
}
/**

View File

@ -0,0 +1,106 @@
'use strict';
/**
* 订单表增加 need_oms_waybill(是否需要回 OMS 取号)字段。
*
* 背景:openapi 创建的订单存在“回到上游 OMS 取运单号”的诉求,需要把该标记
* 落到订单表以便后续流程判断;非 openapi 创建来源一律默认 0。
*
* 取值约定:
* - 0 = 不需要回 OMS 取号(默认,非 openapi 来源);
* - 1 = 需要回 OMS 取号(仅 openapi 创建来源使用)。
*
* 覆盖范围:
* - 基表 wms_order_delivery;
* - 全部仓库分表 wms_order_delivery_{wh}(current)及
* _{wh}_history / _{wh}_dispatch / _{wh}_outsourced。
*
* 幂等:列已存在则跳过。分表模型由 app/model/order_delivery_factory.js
* 运行时 drift 同步兜底,本迁移提前补齐避免运行时 ALTER。
*/
const BASE_TABLE = 'wms_order_delivery';
const SHARD_PATTERN = /^wms_order_delivery_(\d+)(?:_(history|dispatch|outsourced))?$/;
const COLUMN_NAME = 'need_oms_waybill';
/**
* 列举库内全部订单分表。
* @param {import('sequelize').QueryInterface} queryInterface 查询接口。
* @return {Promise<string[]>} 分表名列表。
*/
async function listOrderShards(queryInterface) {
const [ rows ] = await queryInterface.sequelize.query(
'SELECT TABLE_NAME AS tableName FROM INFORMATION_SCHEMA.TABLES '
+ 'WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME LIKE \'wms_order_delivery\\_%\' '
+ 'ORDER BY TABLE_NAME'
);
return (rows || [])
.map(row => String(row.tableName || row.TABLE_NAME || ''))
.filter(name => SHARD_PATTERN.test(name));
}
/**
* 判断列是否已存在。
* @param {import('sequelize').QueryInterface} queryInterface 查询接口。
* @param {string} tableName 表名。
* @param {string} columnName 列名。
* @return {Promise<boolean>} 是否存在。
*/
async function columnExists(queryInterface, tableName, columnName) {
const described = await queryInterface.describeTable(tableName);
return Boolean(described && described[columnName]);
}
module.exports = {
/**
* 执行迁移:为基表与全部分表增加 need_oms_waybill 列。
* @param {import('sequelize').QueryInterface} queryInterface 查询接口。
* @param {import('sequelize')} Sequelize Sequelize 构造器。
* @return {Promise<void>} 无返回值。
*/
async up(queryInterface, Sequelize) {
const tables = [ BASE_TABLE, ...await listOrderShards(queryInterface) ];
const results = [];
for (const tableName of tables) {
if (await columnExists(queryInterface, tableName, COLUMN_NAME)) {
results.push({ tableName, action: 'skip', reason: 'exists' });
continue;
}
await queryInterface.addColumn(tableName, COLUMN_NAME, {
type: Sequelize.TINYINT(4),
allowNull: false,
defaultValue: 0,
comment: '是否需要回OMS取号:0不需要 1需要(仅openapi创建来源使用,其他默认0)',
});
results.push({ tableName, action: 'added' });
}
console.log('[20260912100000-add-need-oms-waybill-to-order-delivery] up results:', JSON.stringify(results));
},
/**
* 回滚迁移:移除基表与全部分表的 need_oms_waybill 列。
* @param {import('sequelize').QueryInterface} queryInterface 查询接口。
* @return {Promise<void>} 无返回值。
*/
async down(queryInterface) {
const tables = [ BASE_TABLE, ...await listOrderShards(queryInterface) ];
const results = [];
for (const tableName of tables) {
if (!await columnExists(queryInterface, tableName, COLUMN_NAME)) {
results.push({ tableName, action: 'skip', reason: 'missing' });
continue;
}
await queryInterface.removeColumn(tableName, COLUMN_NAME);
results.push({ tableName, action: 'removed' });
}
console.log('[20260912100000-add-need-oms-waybill-to-order-delivery] down results:', JSON.stringify(results));
},
};

View File

@ -361,4 +361,96 @@ describe('test/app/service/systems/delivery_order.asyncProcessOrderCreated.test.
'finishAutoGroupingIfNeeded:9001:2',
]);
});
it('should divert need_oms_waybill orders away from local auto waybill allocation', async () => {
const { service, calls, ctx } = createHarness();
const waitLogs = [];
service.buildAsyncProcessContext = async () => ({
orderId: 401,
warehouseId: 100000,
storeId: 200000,
order: {
id: 401,
store_id: 200000,
warehouse_id: 100000,
need_oms_waybill: 1,
},
orderItemRows: [],
});
service.getStoreWarehousePolicyConfig = async () => ({
auto_allocate_express: 1,
auto_allocate_storage: 0,
need_order_approval: 0,
});
service.enqueueAutoWaybillAllocation = async () => {
calls.sequence.push('allocateExpress');
};
service.runAutoGrouping = async () => {
calls.sequence.push('autoGrouping');
};
ctx.service.systemMethods.order.wave.submitWaveStrategyQuickScanForWarehouse = async () => null;
ctx.service.systems.operationLog = {
createOperationLogs: async payloads => {
waitLogs.push(...payloads);
},
};
await service.asyncProcessOrderCreated(401, {
warehouseId: 100000,
storeId: 200000,
}, 'API');
// 不进入本地取号队列
assert.equal(calls.sequence.includes('allocateExpress'), false);
assert.equal(waitLogs.length, 1);
assert.equal(waitLogs[0].businessType, 'order');
assert.equal(waitLogs[0].businessId, '401');
assert.equal(waitLogs[0].operationCode, 'ORDER_NEED_OMS_WAYBILL_WAIT');
assert.equal(waitLogs[0].operator.name, 'system');
assert.match(waitLogs[0].extras.message, /等待外部 OMS 取号/);
});
it('should keep local auto waybill allocation when need_oms_waybill is 0', async () => {
const { service, calls, ctx } = createHarness();
const waitLogs = [];
service.buildAsyncProcessContext = async () => ({
orderId: 402,
warehouseId: 100000,
storeId: 200000,
order: {
id: 402,
store_id: 200000,
warehouse_id: 100000,
need_oms_waybill: 0,
},
orderItemRows: [],
});
service.getStoreWarehousePolicyConfig = async () => ({
auto_allocate_express: 1,
auto_allocate_storage: 0,
need_order_approval: 0,
});
service.enqueueAutoWaybillAllocation = async () => {
calls.sequence.push('allocateExpress');
};
service.runAutoGrouping = async () => {
calls.sequence.push('autoGrouping');
};
ctx.service.systemMethods.order.wave.submitWaveStrategyQuickScanForWarehouse = async () => null;
ctx.service.systems.operationLog = {
createOperationLogs: async payloads => {
waitLogs.push(...payloads);
},
};
await service.asyncProcessOrderCreated(402, {
warehouseId: 100000,
storeId: 200000,
}, 'API');
assert.equal(calls.sequence.includes('allocateExpress'), true);
assert.equal(waitLogs.length, 0);
});
});

View File

@ -167,7 +167,12 @@ describe('test/app/service/systems/express.createWaybillCodePipeline.skipCancell
{ order_id: 2, business_key: 1 },
]);
assert.deepEqual(result, { message: '分配快递任务已提交' });
assert.deepEqual(result, {
message: '分配快递任务已提交',
skipped_intercepted_order_ids: [],
skipped_locked_order_ids: [],
skipped_need_oms_waybill_order_ids: [],
});
// current 表查询必须携带 status != 'cancel' 过滤
const currentQuery = calls.orderDeliveryFindAllQueries[0];
@ -211,7 +216,12 @@ describe('test/app/service/systems/express.createWaybillCodePipeline.skipCancell
{ order_id: 1, business_key: 1 },
]);
assert.deepEqual(result, { message: '所有订单均已分配运单号,无需处理' });
assert.deepEqual(result, {
message: '所有订单均已分配运单号,无需处理',
skipped_intercepted_order_ids: [],
skipped_locked_order_ids: [],
skipped_need_oms_waybill_order_ids: [],
});
assert.equal(calls.asyncTaskPayloads.length, 0);
});
});