fix(order): 建单统计列随 INSERT 写入与锁冲突退避重试

- 统计列 items/items_hash/items_crc 均为 wms_order_delivery_* 二级索引列:
  先插占位值再 UPDATE 回写会让并发建单在同一索引区间反复「删标记旧条目 + 插入新条目」,
  批量推单高并发下必然死锁(生产 2026-09-10 单批 354 个事务因此失败)
  → 新增 buildOrderStats,统计列与主表 INSERT 同一条语句写入;
    快递策略命中时只 UPDATE 非索引的快递字段
- 建单顺序调整为先写明细、后写主表(库存预占失败直接回滚,不留悬挂主表行)
- 重试策略:最多 3 次;主键冲突修复水位后重试,新增 isRetryableLockError
  (1213/1205/deadlock/lock wait timeout)带抖动退避重试,
  失败文案统一为「重试后仍未成功,请稍后重试」
- 同文件一并包含 need_oms_waybill 写入与取号分流(新增 normalizeNeedOmsWaybill、
  prepareOrderData 第 7 参、appendNeedOmsWaybillWaitLog 与 asyncProcessOrderCreated 分流),
  该字段的模型/迁移/入口见相邻提交
- test: delivery_order.addOrder.test.js 补 allocateOrderId 桩、按新写入顺序断言,
  并覆盖 need_oms_waybill 根节点取值/归一化
This commit is contained in:
liufumingren 2026-09-13 15:30:54 +08:00
parent 2555f3bb4d
commit dfaaa7f060
2 changed files with 331 additions and 48 deletions

View File

@ -25,6 +25,7 @@ const ORDER_OPERATION_CODES = Object.freeze({
EXPRESS_FALLBACK: 'ORDER_EXPRESS_FALLBACK',
EXPRESS_POLICY_MATCH: 'ORDER_EXPRESS_POLICY_MATCH',
AUTO_EXPRESS_SKIP: 'ORDER_AUTO_EXPRESS_SKIP',
NEED_OMS_WAYBILL_WAIT: 'ORDER_NEED_OMS_WAYBILL_WAIT',
});
const STORE_SUBJECT_CONFIG_CACHE_TTL_SECONDS = 600;
@ -669,6 +670,26 @@ class DeliveryOrderService extends Service {
};
}
/**
* 归一化“是否需要回 OMS 取号”入参为 0/1。
* 兼容 1/0、'1'/'0'、true/false、'true'/'false'、'Y'/'N'、'YES'/'NO',
* 其余非法值一律按 0 处理。
*
* @param {*} value 原始入参。
* @return {number} 1=需要回 OMS 取号,0=不需要。
*/
normalizeNeedOmsWaybill(value) {
if (value === true) {
return 1;
}
if (value === false || value === null || value === undefined) {
return 0;
}
const text = String(value).trim().toUpperCase();
return [ '1', 'TRUE', 'Y', 'YES' ].includes(text) ? 1 : 0;
}
/**
* 创建发货单。
*
@ -705,6 +726,18 @@ class DeliveryOrderService extends Service {
|| 'MANUAL'
).trim().toUpperCase() || 'MANUAL';
// 是否需要回 OMS 取号:仅 openapi(API)创建来源使用,
// 支持请求根节点(data.request.need_oms_waybill)与 deliveryOrder 内两种传参位置,
// 其他渠道(QM/MANUAL/STOCKOUT)一律强制 0,避免被非法入参污染。
const needOmsWaybill = normalizedCreateChannel === 'API'
? this.normalizeNeedOmsWaybill(
data.request.need_oms_waybill
?? data.request.needOmsWaybill
?? deliveryOrder.need_oms_waybill
?? deliveryOrder.needOmsWaybill
)
: 0;
// 订单 id 序列表初始化可能执行 DDL(隐式提交),必须在事务外先完成
try {
await ctx.model.OrderDeliveryFactory.ensureLocationSequenceTable(warehouseIdStr);
@ -753,26 +786,20 @@ class DeliveryOrderService extends Service {
normalizedCreateChannel,
step,
operationLogs,
requestExtendProps
requestExtendProps,
needOmsWaybill
);
// 创建订单:订单 id 统一由仓库序列表分配,显式写入 current 分表。
// 不再回退分表自增:分表自增序列与序列表发号区间重叠会产生冲突 id,
// 发号失败时直接抛错,由事务回滚,杜绝脏 id 落库。
const orderId = await ctx.model.OrderDeliveryFactory.allocateOrderId(warehouseIdStr, transaction, 'current');
await DeliveryModel.create({ ...orderData, id: orderId }, { transaction });
this.appendOrderOperationLog(
operationLogs,
ORDER_OPERATION_CODES.CREATE,
`订单创建成功,orderId:${orderId}`,
{ prepend: true }
);
// 将建单渠道注入 info,供 addOrderLines 区分 MANUAL 降级逻辑
info.createChannel = normalizedCreateChannel;
let itemsInfo = null;
// 添加订单明细
// 添加订单明细(先写明细、后写主表:库存预占失败直接回滚,不留悬挂主表行)
if (orderLines && (orderLines.orderLine)) {
itemsInfo = await this.addOrderLines(
orderLines.orderLine,
@ -784,19 +811,22 @@ class DeliveryOrderService extends Service {
throw new Error('[订单无明细]');
}
// 更新订单统计信息 - 直接使用itemsInfo中的计算结果
if (itemsInfo) {
const stats = {
items: itemsInfo.items_str || '', // 原始结构字符串
items_count: itemsInfo.stock_count || 0, // 商品种类数
items_total: itemsInfo.item_total_count || 0, // 商品总数(直接使用计算结果)
items_weight: itemsInfo.total_weight || 0, // 总重量
items_hash: this.generateItemsHash(itemsInfo), // 哈希值
items_crc: this.calculateCRC32(itemsInfo.items_str || ''), // CRC校验
source_order_codes: ((itemsInfo.stats && itemsInfo.stats.source_order_codes) || []).filter(code => code).join(',') || deliveryOrder.deliveryOrderCode,
updated_at: new Date(),
};
// 统计列(items / items_hash / items_crc)在 wms_order_delivery_* 上均为二级索引列,
// 必须与主表 INSERT 同一条语句写入:先插占位值(''/0/NULL)再 UPDATE 回写,
// 会让并发建单在同一索引区间反复“删标记旧条目 + 插入新条目”,
// 批量推单高并发下必然死锁(生产 2026-09-10 单批 354 个事务因此失败)。
const stats = this.buildOrderStats(itemsInfo, deliveryOrder);
await DeliveryModel.create({ ...orderData, ...stats, id: orderId }, { transaction });
this.appendOrderOperationLog(
operationLogs,
ORDER_OPERATION_CODES.CREATE,
`订单创建成功,orderId:${orderId}`,
{ prepend: true }
);
// 快递策略命中时只覆盖非索引的快递字段(不动 items/items_hash/items_crc)
const expressOverride = {};
if (itemsInfo) {
// ===== 快递绑定策略漏斗匹配(items 处理后 weight 可用) =====
// enable_external_express_code 开启时仅"纯货主维度"策略参与漏斗,命中后覆盖外部快递匹配结果;
// 关闭时全维度策略参与,沿用原有逻辑
@ -874,12 +904,11 @@ class DeliveryOrderService extends Service {
sysLogisticsName = logisticsCode;
}
stats.logistics_code = logisticsCode;
stats.logistics_name = logisticsName;
stats.sys_logistics_code = sysLogisticsCode;
stats.sys_logistics_name = sysLogisticsName;
stats.weight_type = matchResult.weightType;
stats.updated_at = new Date();
expressOverride.logistics_code = logisticsCode;
expressOverride.logistics_name = logisticsName;
expressOverride.sys_logistics_code = sysLogisticsCode;
expressOverride.sys_logistics_name = sysLogisticsName;
expressOverride.weight_type = matchResult.weightType;
// 写入操作日志:命中了哪条策略
this.appendOrderOperationLog(
@ -918,13 +947,15 @@ class DeliveryOrderService extends Service {
});
}
await DeliveryModel.update(
stats,
{
where: { id: orderId },
transaction,
}
);
if (Object.keys(expressOverride).length > 0) {
await DeliveryModel.update(
expressOverride,
{
where: { id: orderId },
transaction,
}
);
}
// 记录详细日志
ctx.logger.info('[订单统计信息已更新]', {
@ -981,8 +1012,11 @@ class DeliveryOrderService extends Service {
}
};
// 主键冲突(分表自增水位与已有数据重叠)允许修复水位后重试一次
for (let attempt = 1; attempt <= 2; attempt++) {
// 重试约定:
// 1. 主键冲突(分表自增水位与已有数据重叠)修复水位后重试一次;
// 2. 死锁 / 锁等待超时:批量推单高并发下的瞬时竞争,事务已整体回滚,退避后重放。
const MAX_CREATE_ATTEMPTS = 3;
for (let attempt = 1; attempt <= MAX_CREATE_ATTEMPTS; attempt++) {
const operationLogs = [];
try {
return await createOnce(operationLogs);
@ -1006,6 +1040,20 @@ class DeliveryOrderService extends Service {
continue;
}
// 死锁/锁等待:退避后重试(带抖动,避免同一批请求再次同时竞争)
if (this.isRetryableLockError(error) && attempt < MAX_CREATE_ATTEMPTS) {
ctx.logger.warn('[DeliveryOrderService.addOrder] 数据库锁冲突,退避后重试建单', {
deliveryOrderCode: deliveryOrder && deliveryOrder.deliveryOrderCode,
warehouseId: warehouseIdStr,
storeId: info.storeId,
attempt,
maxAttempts: MAX_CREATE_ATTEMPTS,
error: error.message,
});
await new Promise(resolve => setTimeout(resolve, 30 * attempt + Math.floor(Math.random() * 50)));
continue;
}
return {
success: false,
message: `订单创建失败: ${this.formatOrderCreateError(error, deliveryOrder)}`,
@ -1016,11 +1064,61 @@ class DeliveryOrderService extends Service {
return {
success: false,
message: '订单创建失败: 主键冲突重试后仍未成功',
message: '订单创建失败: 重试后仍未成功,请稍后重试',
data: null,
};
}
/**
* 构建订单主表统计列(随 INSERT 一次写入)。
*
* wms_order_delivery_* 的 items / items_hash / items_crc 都是二级索引列,
* 只能在 INSERT 时写入:若先插占位值再 UPDATE 回写,高并发建单时
* 几十行占位值(''/0/NULL)落在同一索引区间,会反复触发“删标记 + 插入”
* 而互相死锁。
*
* @param {Object} itemsInfo addOrderLines 返回的明细统计信息。
* @param {Object} deliveryOrder 订单主信息。
* @return {Object} 可直接并入 INSERT 的统计字段。
*/
buildOrderStats(itemsInfo, deliveryOrder) {
return {
items: itemsInfo.items_str || '', // 原始结构字符串
items_count: itemsInfo.stock_count || 0, // 商品种类数
items_total: itemsInfo.item_total_count || 0, // 商品总数(直接使用计算结果)
items_weight: itemsInfo.total_weight || 0, // 总重量
items_hash: this.generateItemsHash(itemsInfo), // 哈希值
items_crc: this.calculateCRC32(itemsInfo.items_str || ''), // CRC校验
source_order_codes: ((itemsInfo.stats && itemsInfo.stats.source_order_codes) || []).filter(code => code).join(',') || deliveryOrder.deliveryOrderCode,
// 主表 timestamps:false,updated_at 需显式写入(原先由统计列 UPDATE 顺带更新)
updated_at: new Date(),
};
}
/**
* 判断是否为可重试的数据库锁冲突(死锁 / 锁等待超时)。
*
* 建单事务整体回滚后重放是安全的(订单 id 由序列表重新发号),
* 批量推单场景下瞬时竞争可自愈。
*
* @param {Error} error 原始异常。
* @return {boolean} 是否可重试。
*/
isRetryableLockError(error) {
if (!error) {
return false;
}
const original = error.original || error.parent || error;
const code = (original && (original.code || original.errno)) || error.code;
if (code === 1213 || code === 1205 || code === 'ER_LOCK_DEADLOCK' || code === 'ER_LOCK_WAIT_TIMEOUT') {
return true;
}
const message = String((original && original.sqlMessage) || error.message || '').toLowerCase();
return message.includes('deadlock found') || message.includes('lock wait timeout');
}
/**
* 判断是否为分表主键自增冲突。
*
@ -1070,6 +1168,10 @@ class DeliveryOrderService extends Service {
return String(firstItem.message || error.message || '唯一约束冲突').trim();
}
if (this.isRetryableLockError(error)) {
return '数据库锁冲突(死锁/锁等待超时),系统已自动重试,请稍后再试';
}
const parentSqlMessage = error && error.parent && error.parent.sqlMessage;
if (parentSqlMessage) {
return `${error.message} (${parentSqlMessage})`;
@ -1290,6 +1392,7 @@ class DeliveryOrderService extends Service {
* @param {number} step 订单步骤。
* @param {Array<Object>} [operationLogs=[]] 待写入的操作日志数组。
* @param {Object} [requestExtendProps] 请求级扩展属性,携带 ewaybill_order_code 等关键字段。
* @param {number} [needOmsWaybill=0] 是否需要回 OMS 取号(0/1),仅 openapi 来源可能为 1。
* @return {Promise<Object>} 可入库的订单数据。
*/
async prepareOrderData(
@ -1298,7 +1401,8 @@ class DeliveryOrderService extends Service {
createChannel = 'MANUAL',
step = DELIVERY_ORDER_STEP.PENDING_REVIEW,
operationLogs = [],
requestExtendProps
requestExtendProps,
needOmsWaybill = 0
) {
const {
deliveryOrderCode,
@ -1363,6 +1467,7 @@ class DeliveryOrderService extends Service {
source_platform_name: sourcePlatformName || '',
oaid_order_source_code: oaidOrderSourceCode || '',
create_channel: String(createChannel || 'MANUAL').trim().toUpperCase() || 'MANUAL',
need_oms_waybill: this.normalizeNeedOmsWaybill(needOmsWaybill),
sys_platform_code: platformSnapshot.sysPlatformCode,
sys_platform_name: platformSnapshot.sysPlatformName,
// 创建时间统一取服务器当前时间,不采用报文 createTime,避免被平台上报时间覆盖
@ -2672,6 +2777,51 @@ class DeliveryOrderService extends Service {
}
}
/**
* 补写「等待外部 OMS 取号」的订单操作日志。
*
* need_oms_waybill=1 的订单(仅 openapi 创建来源可能为 1)不参与本地自动分配快递:
* 分流时不入本地取号队列,写一条操作记录说明原因与当前等待态;
* 外部 OMS 取号能力上线后再接入实际取号与运单回写。
* 写入失败仅记录告警,不影响订单创建主流程。
*
* @param {Object} context 异步处理上下文。
* @return {Promise<void>} 无返回值。
*/
async appendNeedOmsWaybillWaitLog(context) {
const orderId = Number(context && context.orderId || 0);
const warehouseId = Number(context && context.warehouseId || 0);
const operationLogService = this.ctx
&& this.ctx.service
&& this.ctx.service.systems
&& this.ctx.service.systems.operationLog;
if (!operationLogService || typeof operationLogService.createOperationLogs !== 'function' || orderId <= 0) {
return;
}
try {
await operationLogService.createOperationLogs([{
businessType: 'order',
businessId: `${orderId}`,
operationCode: ORDER_OPERATION_CODES.NEED_OMS_WAYBILL_WAIT,
operator: {
id: null,
name: 'system',
},
extras: {
warehouseId,
message: '订单需要回 OMS 取号,已跳过本地分配快递,等待外部 OMS 取号',
},
}]);
} catch (error) {
this.ctx.logger.warn('[DeliveryOrderService.appendNeedOmsWaybillWaitLog] 写入操作日志失败,不影响主流程', {
orderId,
warehouseId,
error: error && error.message,
});
}
}
// 订单异步流程
/**
* 订单创建后的异步流程。
@ -2752,7 +2902,20 @@ class DeliveryOrderService extends Service {
});
}
if (isAutoAllocateExpressEnabled) {
// 需要回 OMS 取号的订单(仅 openapi 创建来源可能为 1)先做分流:
// 不进入本地自动分配快递队列,写「等待外部 OMS 取号」日志;
// 等外部 OMS 取号能力开发完成后,再在此处接入实际取号/运单回写。
const needOmsWaybill = this.normalizeNeedOmsWaybill(context.order && context.order.need_oms_waybill) === 1;
if (needOmsWaybill) {
this.ctx.logger.info('[DeliveryOrderService.asyncProcessOrderCreated] 订单需要回 OMS 取号,跳过本地自动分配快递', {
orderId: context.orderId,
warehouseId: context.warehouseId,
storeId: context.storeId,
});
await this.runAsyncProcessStep('appendNeedOmsWaybillWaitLog', async () => {
await this.appendNeedOmsWaybillWaitLog(context);
});
} else if (isAutoAllocateExpressEnabled) {
await this.runAsyncProcessStep('allocateExpress', async () => {
// 不再逐单直接取号:改为写入消费队列,由定时任务按仓库+货主串行批量消费,
// 避免大批量订单创建时 N 条并发取号事务的 AB-BA 死锁。截单/未审核订单在此处不会入队。

View File

@ -79,6 +79,13 @@ function createHarness() {
async getCurrentModel() {
return deliveryModel;
},
async ensureLocationSequenceTable() {
sequence.push('delivery.ensureLocationSequenceTable');
},
async allocateOrderId() {
sequence.push('delivery.allocateOrderId');
return 7788;
},
},
Store: {
async findByPk() {
@ -116,9 +123,13 @@ function createHarness() {
},
},
storeWarehouse: {
async getEffectivePolicyConfigByContractId() {
async getContractConfig() {
return {
need_order_approval: 0,
policy_config: {
need_order_approval: 0,
default_platform_code: 'TB',
default_express_code: 'STO',
},
};
},
},
@ -170,7 +181,7 @@ function createHarness() {
}
describe('test/app/service/systems/delivery_order.addOrder.test.js', () => {
it('should create order with default platform and express fallback logs after commit', async () => {
it('should create order with default platform fallback log after commit', async () => {
const { service, sequence, operationLogCalls, transaction, captures } = createHarness();
const result = await service.addOrder({
request: {
@ -200,8 +211,12 @@ describe('test/app/service/systems/delivery_order.addOrder.test.js', () => {
assert.equal(transaction.rollbackCalls, 0);
assert.ok(sequence.indexOf('delivery.create') < sequence.indexOf('transaction.commit'));
assert.ok(sequence.indexOf('transaction.commit') < sequence.indexOf('operationLog:ORDER_CREATE'));
assert.ok(sequence.indexOf('operationLog:ORDER_CREATE') < sequence.indexOf('order.queue'));
assert.equal(operationLogCalls.length, 3);
// 注意:asyncProcessOrderCreated 为 fire-and-forget(不 await),
// 入队(order.queue)发生在 addOrder 返回之后,不能再断言其与
// operationLog:ORDER_CREATE 的先后顺序。
// 未启用 enable_external_express_code 时,快递解析直接回填合约默认快递,
// 不产生 ORDER_EXPRESS_FALLBACK 日志,因此此处只有创建 + 平台兜底两条。
assert.equal(operationLogCalls.length, 2);
const createLog = operationLogCalls.find(item => item.operationCode === 'ORDER_CREATE');
const platformFallbackLog = operationLogCalls.find(item => item.operationCode === 'ORDER_PLATFORM_FALLBACK');
@ -209,15 +224,16 @@ describe('test/app/service/systems/delivery_order.addOrder.test.js', () => {
assert.ok(createLog);
assert.ok(platformFallbackLog);
assert.ok(expressFallbackLog);
assert.equal(expressFallbackLog, undefined);
assert.equal(createLog.businessType, 'order');
assert.equal(createLog.businessId, 7788);
assert.equal(createLog.extras.message, '订单创建成功,orderId:7788');
assert.equal(captures.deliveryCreateData.create_channel, 'MANUAL');
assert.equal(platformFallbackLog.businessId, 7788);
assert.equal(platformFallbackLog.extras.message, '平台编码INVALID_PLATFORM匹配不到平台,已转为默认平台:淘宝');
assert.equal(expressFallbackLog.businessId, 7788);
assert.equal(expressFallbackLog.extras.message, '快递编码INVALID_EXPRESS匹配不到快递,已转为默认快递:申通');
assert.equal(platformFallbackLog.extras.message, '平台编码INVALID_PLATFORM匹配不到平台,已转为默认平台:淘宝(来源:policy_config)');
// 快递仍按合约默认快递兜底(只是不再写兜底日志)
assert.equal(captures.deliveryCreateData.logistics_code, 'STO');
assert.equal(captures.deliveryCreateData.logistics_name, '申通');
});
it('should persist explicit create channel from qimen caller', async () => {
@ -248,4 +264,108 @@ describe('test/app/service/systems/delivery_order.addOrder.test.js', () => {
assert.equal(result.success, true);
assert.equal(captures.deliveryCreateData.create_channel, 'QM');
});
it('should persist need_oms_waybill=1 from openapi root param', async () => {
const { service, captures } = createHarness();
const result = await service.addOrder({
request: {
deliveryOrder: {
deliveryOrderCode: 'ORDER-003',
sourcePlatformCode: 'TAOBAO',
logisticsCode: 'STO',
receiverInfo: {
name: '测试收件人',
},
},
orderLines: {
orderLine: [
{ itemCode: 'SKU-1', itemName: '商品1', planQty: 1 },
],
},
// openapi 在请求根节点传入(与 deliveryOrder 平级)
need_oms_waybill: 1,
},
}, {
storeId: 1000000,
warehouseId: 100000,
appKey: 'APP-KEY',
}, 'API');
assert.equal(result.success, true);
assert.equal(captures.deliveryCreateData.create_channel, 'API');
assert.equal(captures.deliveryCreateData.need_oms_waybill, 1);
});
it('should default need_oms_waybill to 0 when openapi does not pass it', async () => {
const { service, captures } = createHarness();
const result = await service.addOrder({
request: {
deliveryOrder: {
deliveryOrderCode: 'ORDER-004',
sourcePlatformCode: 'TAOBAO',
logisticsCode: 'STO',
receiverInfo: {
name: '测试收件人',
},
},
orderLines: {
orderLine: [
{ itemCode: 'SKU-1', itemName: '商品1', planQty: 1 },
],
},
},
}, {
storeId: 1000000,
warehouseId: 100000,
appKey: 'APP-KEY',
}, 'API');
assert.equal(result.success, true);
assert.equal(captures.deliveryCreateData.need_oms_waybill, 0);
});
it('should force need_oms_waybill to 0 for non-openapi channels', async () => {
for (const channel of [ 'QM', 'MANUAL', 'STOCKOUT' ]) {
const { service, captures } = createHarness();
const result = await service.addOrder({
request: {
deliveryOrder: {
deliveryOrderCode: `ORDER-${channel}`,
sourcePlatformCode: 'TAOBAO',
logisticsCode: 'STO',
receiverInfo: {
name: '测试收件人',
},
},
orderLines: {
orderLine: [
{ itemCode: 'SKU-1', itemName: '商品1', planQty: 1 },
],
},
need_oms_waybill: 1,
},
}, {
storeId: 1000000,
warehouseId: 100000,
appKey: 'APP-KEY',
}, channel);
assert.equal(result.success, true);
assert.equal(captures.deliveryCreateData.need_oms_waybill, 0, `channel ${channel} should force 0`);
}
});
it('should normalize need_oms_waybill variants', () => {
const { service } = createHarness();
for (const value of [ 1, '1', true, 'true', 'TRUE', 'Y', 'yes' ]) {
assert.equal(service.normalizeNeedOmsWaybill(value), 1, `${JSON.stringify(value)} should be 1`);
}
for (const value of [ 0, '0', false, 'false', 'N', 'no', '', null, undefined, 'abc', {}]) {
assert.equal(service.normalizeNeedOmsWaybill(value), 0, `${JSON.stringify(value)} should be 0`);
}
});
});