WMS_MAIN/app/service/systems/order_delivery_migration.js
liufumingren c5150bc35b feat: 配送表新增 dispath_time 迁移时间字段
- 新增迁移 20260907120000:为全部配送分表 wms_order_delivery_{wh}_dispatch 幂等新增 dispath_time(datetime, nullable),不触基表/当前分表/history/outsourced

- 配送表模型 schema dispatch 分支同步新增 dispath_time,drift 同步保持一致

- 订单迁移链路 buildDispatchRow 写入 dispath_time=new Date() 记录进入配送表时间
2026-09-07 16:43:35 +08:00

703 lines
24 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';
const MainService = require('../main');
const OUTBOUND_STATUS = 'fin';
const OUTBOUND_STATUS_TIMEOUT = 'timeout';
const OUTBOUND_STEP = 4;
const OUTBOUND_SYNC_STEPS = [ OUTBOUND_STEP, 9 ];
const DISPATCH_LANE = 'm4';
const MAX_BATCH_SIZE = 1000;
const CURRENT_TABLE_PATTERN = /^wms_order_delivery_(\d+)$/;
const RETRYABLE_DATABASE_ERROR_CODES = new Set([ 1205, 1213, 'ER_LOCK_WAIT_TIMEOUT', 'ER_LOCK_DEADLOCK' ]);
const DEFAULT_OUTBOUND_STATUSES = [ OUTBOUND_STATUS, 'padding' ];
/**
* 订单出库后迁移到配送表的同步服务。
*/
class OrderDeliveryMigrationService extends MainService {
/**
* 同步当前仓库分表中已出库订单到配送表。
*
* @param {Object} data 请求参数。
* @param {number|Array<number|string>} [data.warehouseId] 单个仓库ID或仓库ID列表。
* @param {Array<number|string>} [data.warehouseIds] 仓库ID列表。
* @return {Promise<Object>} 同步结果。
*/
async syncOutboundOrdersToDelivery(data = {}) {
return this.syncOutboundOrdersByStatus(data, {
outboundStatuses: DEFAULT_OUTBOUND_STATUSES,
persistTimeoutState: true,
});
}
/**
* 重试出库超时订单并继续迁移到配送表。
*
* @param {Object} data 请求参数。
* @param {number|Array<number|string>} [data.warehouseId] 单个仓库ID或仓库ID列表。
* @param {Array<number|string>} [data.warehouseIds] 仓库ID列表。
* @return {Promise<Object>} 同步结果。
*/
async retryTimeoutOutboundOrdersToDelivery(data = {}) {
return this.syncOutboundOrdersByStatus(data, {
outboundStatuses: [ OUTBOUND_STATUS_TIMEOUT ],
persistTimeoutState: false,
});
}
/**
* 按指定出库状态同步订单到配送表。
*
* @param {Object} data 请求参数。
* @param {number|Array<number|string>} [data.warehouseId] 单个仓库ID或仓库ID列表。
* @param {Array<number|string>} [data.warehouseIds] 仓库ID列表。
* @param {Object} [options] 迁移控制参数。
* @param {Array<string>} [options.outboundStatuses] 需要迁移的出库状态。
* @param {number} [options.queryTimeoutMs] 单条数据库查询的超时时间。
* @param {number} [options.executionTimeoutMs] 单仓库批次的执行超时时间。
* @param {boolean} [options.persistTimeoutState] 失败后是否将源订单标记为出库超时。
* @return {Promise<Object>} 同步结果。
*/
async syncOutboundOrdersByStatus(data = {}, options = {}) {
const requestData = this.isPlainObject(data) ? data : {};
const explicitWarehouseIds = this.normalizeWarehouseIds(requestData);
const warehouseIds = explicitWarehouseIds.length > 0
? explicitWarehouseIds
: await this.listCurrentWarehouseIds();
const results = [];
let remaining = MAX_BATCH_SIZE;
let totalSelected = 0;
let totalCreated = 0;
let totalSkipped = 0;
let totalTimeout = 0;
for (const warehouseId of warehouseIds) {
if (remaining <= 0) {
break;
}
const batchLimit = Math.min(remaining, MAX_BATCH_SIZE);
const batchResult = await this.syncOutboundOrdersForWarehouse(warehouseId, batchLimit, options);
results.push(batchResult);
totalSelected += batchResult.selectedCount;
totalCreated += batchResult.createdCount;
totalSkipped += batchResult.skippedCount;
totalTimeout += Number(batchResult.timeoutCount || 0);
remaining -= batchResult.selectedCount;
}
return {
warehouseIds,
batchSize: MAX_BATCH_SIZE,
outboundStatuses: this.normalizeOutboundStatuses(options.outboundStatuses),
totalSelected,
totalCreated,
totalSkipped,
totalTimeout,
results,
};
}
/**
* 规范化仓库ID列表。
*
* @param {Object} data 请求参数。
* @return {Array<number>} 仓库ID列表。
*/
normalizeWarehouseIds(data = {}) {
if (!this.isPlainObject(data)) {
return [];
}
const candidateValues = Array.isArray(data.warehouseIds)
? data.warehouseIds
: [ data.warehouseId ?? data.warehouse_id ].filter(value => value !== undefined && value !== null && value !== '');
return Array.from(new Set(candidateValues
.map(value => Number(value))
.filter(value => Number.isFinite(value) && value > 0)))
.sort((left, right) => left - right);
}
/**
* 获取当前库中存在的订单工作台仓库ID。
*
* @return {Promise<Array<number>>} 仓库ID列表。
*/
async listCurrentWarehouseIds() {
const factory = this.ctx.model && this.ctx.model.OrderDeliveryFactory;
if (!factory || typeof factory.listManagedTableNames !== 'function') {
return [];
}
const tableNames = await factory.listManagedTableNames();
return Array.from(new Set((Array.isArray(tableNames) ? tableNames : [])
.map(tableName => {
const matched = CURRENT_TABLE_PATTERN.exec(String(tableName || ''));
return matched ? Number(matched[1]) : null;
})
.filter(value => Number.isFinite(value) && value > 0)))
.sort((left, right) => left - right);
}
/**
* 规范化需要迁移的出库状态。
*
* @param {Array<string>|string} outboundStatuses 目标状态。
* @return {Array<string>} 规范化后的状态列表。
*/
normalizeOutboundStatuses(outboundStatuses = DEFAULT_OUTBOUND_STATUSES) {
const candidates = Array.isArray(outboundStatuses)
? outboundStatuses
: [ outboundStatuses ];
const normalizedStatuses = Array.from(new Set(candidates
.map(value => String(value || '').trim())
.filter(Boolean)));
return normalizedStatuses.length > 0 ? normalizedStatuses : DEFAULT_OUTBOUND_STATUSES;
}
/**
* 构造 Sequelize 查询参数。
*
* @param {Object|null} transaction 事务对象。
* @param {number} [queryTimeoutMs] 查询超时时间。
* @return {Object} Sequelize 查询参数。
*/
buildMigrationQueryOptions(transaction, queryTimeoutMs) {
const queryOptions = {};
if (transaction) {
queryOptions.transaction = transaction;
}
const normalizedTimeoutMs = Number(queryTimeoutMs);
if (Number.isFinite(normalizedTimeoutMs) && normalizedTimeoutMs > 0) {
queryOptions.timeout = normalizedTimeoutMs;
}
return queryOptions;
}
/**
* 识别可重试的出库迁移错误。
*
* @param {Error} error 运行时错误。
* @return {{ retryable: boolean, category: string, message: string }} 错误分类结果。
*/
getOutboundMigrationErrorInfo(error) {
const errorMessage = String(error && error.message || '');
const errorName = String(error && error.name || '');
const parentError = error && error.parent ? error.parent : null;
const errorCode = parentError && (parentError.code || parentError.errno)
? parentError.code || parentError.errno
: error && (error.code || error.errno);
const normalizedMessage = errorMessage.toLowerCase();
if (errorName === 'SequelizeTimeoutError' || errorName === 'TimeoutError' || errorCode === 'ETIMEDOUT') {
return {
retryable: true,
category: 'timeout',
message: errorMessage,
};
}
if (errorName === 'SequelizeDatabaseError') {
if (normalizedMessage.includes('lock wait timeout')) {
return {
retryable: true,
category: 'lock_wait_timeout',
message: errorMessage,
};
}
if (RETRYABLE_DATABASE_ERROR_CODES.has(errorCode) || normalizedMessage.includes('deadlock')) {
return {
retryable: true,
category: 'deadlock',
message: errorMessage,
};
}
}
return {
retryable: false,
category: 'other',
message: errorMessage,
};
}
/**
* 将指定仓库内的源订单标记为出库超时。
*
* @param {number} warehouseId 仓库ID。
* @param {Array<number>} orderIds 源订单ID列表。
* @param {number} [queryTimeoutMs] 更新语句超时时间。
* @return {Promise<number>} 受影响行数。
*/
async markOutboundOrdersTimeout(warehouseId, orderIds, queryTimeoutMs) {
const normalizedWarehouseId = Number(warehouseId);
const normalizedOrderIds = Array.from(new Set((Array.isArray(orderIds) ? orderIds : [])
.map(value => Number(value))
.filter(value => Number.isFinite(value) && value > 0)));
if (!Number.isFinite(normalizedWarehouseId) || normalizedWarehouseId <= 0) {
throw new Error('仓库ID不能为空');
}
if (normalizedOrderIds.length === 0) {
return 0;
}
const orderFactory = this.ctx.model && this.ctx.model.OrderDeliveryFactory;
if (!orderFactory || typeof orderFactory.getCurrentModel !== 'function') {
throw new Error('订单工厂未初始化');
}
const sourceOrderModel = await orderFactory.getCurrentModel(normalizedWarehouseId);
const { Op } = this.ctx.app.Sequelize;
const updateValues = {
outbound_status: OUTBOUND_STATUS_TIMEOUT,
updated_at: new Date(),
};
const updateResult = await sourceOrderModel.update(updateValues, {
where: {
warehouse_id: normalizedWarehouseId,
id: {
[Op.in]: normalizedOrderIds,
},
},
...this.buildMigrationQueryOptions(null, queryTimeoutMs),
});
return Array.isArray(updateResult) ? Number(updateResult[0] || 0) : Number(updateResult || 0);
}
/**
* 构造配送表去重键。
*
* @param {Object} row 订单行数据。
* @return {string} 去重键。
*/
buildDispatchKey(row) {
if (!this.isPlainObject(row)) {
return '';
}
const deliveryOrderCode = String(row.delivery_order_code || '').trim();
const storeId = String(row.store_id || '').trim();
const warehouseId = String(row.warehouse_id || '').trim();
if (!deliveryOrderCode || !storeId || !warehouseId) {
return '';
}
return `${deliveryOrderCode}::${storeId}::${warehouseId}`;
}
/**
* 构造配送表插入行。
*
* 写入配送表时追加 dispath_time(当前时间),用于记录订单迁移进配送表的时间;
* 仅配送表写入该字段,源表数据不受影响。
*
* @param {Object} row 当前订单工作台数据。
* @return {Object} 可写入配送表的数据。
*/
buildDispatchRow(row) {
const payload = { ...(row || {}) };
delete payload.dispatch_lane;
return {
...payload,
dispatch_lane: DISPATCH_LANE,
dispath_time: new Date(),
};
}
/**
* 构造商品明细迁移行。
*
* @param {Object} row 当前订单商品明细行。
* @param {number} targetOrderId 配送表订单ID。
* @return {Object} 可写入配送明细表的数据。
*/
buildDispatchItemRow(row, targetOrderId) {
return {
...(row || {}),
order_id: targetOrderId,
};
}
/**
* 获取订单与商品明细迁移所需的模型。
*
* @param {number} warehouseId 仓库ID。
* @return {Promise<Object>} 迁移模型集合。
*/
async getMigrationModels(warehouseId) {
const orderFactory = this.ctx.model && this.ctx.model.OrderDeliveryFactory;
const itemsFactory = this.ctx.model && this.ctx.model.OrderItemsFactory;
if (!orderFactory || typeof orderFactory.getCurrentModel !== 'function' || typeof orderFactory.getDispatchModel !== 'function') {
throw new Error('订单工厂未初始化');
}
if (!itemsFactory || typeof itemsFactory.getCurrentModel !== 'function' || typeof itemsFactory.getDispatchModel !== 'function') {
throw new Error('订单商品工厂未初始化');
}
return {
sourceOrderModel: await orderFactory.getCurrentModel(warehouseId),
targetOrderModel: await orderFactory.getDispatchModel(warehouseId),
sourceItemModel: await itemsFactory.getCurrentModel(warehouseId),
targetItemModel: await itemsFactory.getDispatchModel(warehouseId),
};
}
/**
* 将配送表订单行转换为订单ID映射。
*
* @param {Array<Object>} rows 配送表订单行。
* @return {Map<string, number>} 业务键到订单ID的映射。
*/
buildTargetOrderIdMap(rows) {
return new Map((Array.isArray(rows) ? rows : [])
.map(row => {
const key = this.buildDispatchKey(row);
const orderId = Number(row && row.id);
if (!key || !Number.isFinite(orderId) || orderId <= 0) {
return null;
}
return [ key, orderId ];
})
.filter(Boolean));
}
/**
* 同步指定仓库的已出库订单。
*
* @param {number|string} warehouseId 仓库ID。
* @param {number} [limit=1000] 单次处理数量上限。
* @param {Object} [options] 迁移控制参数。
* @param {Array<string>} [options.outboundStatuses] 需要迁移的出库状态。
* @param {number} [options.queryTimeoutMs] 单条数据库查询的超时时间。
* @param {number} [options.executionTimeoutMs] 单仓库批次的执行超时时间。
* @param {boolean} [options.persistTimeoutState] 失败后是否将源订单标记为出库超时。
* @return {Promise<Object>} 同步结果。
*/
async syncOutboundOrdersForWarehouse(warehouseId, limit = MAX_BATCH_SIZE, options = {}) {
const normalizedWarehouseId = Number(warehouseId);
if (!Number.isFinite(normalizedWarehouseId) || normalizedWarehouseId <= 0) {
throw new Error('仓库ID不能为空');
}
const batchLimit = Math.min(
Math.max(Number(limit) || MAX_BATCH_SIZE, 1),
MAX_BATCH_SIZE
);
const outboundStatuses = this.normalizeOutboundStatuses(options.outboundStatuses);
const queryTimeoutMs = Number(options.queryTimeoutMs);
const executionTimeoutMs = Number(options.executionTimeoutMs);
const persistTimeoutState = Boolean(options.persistTimeoutState);
const deadlineAt = Number.isFinite(executionTimeoutMs) && executionTimeoutMs > 0
? Date.now() + executionTimeoutMs
: 0;
// 序列表初始化可能执行 DDL(隐式提交),必须在事务外完成。
// 初始化失败直接终止迁移:位置指针与配送表写入必须在同一事务内原子完成,
// 没有序列表则无法保证索引一致,宁可迁移失败重试也不产生错位指针。
await this.ctx.model.OrderDeliveryFactory.ensureLocationSequenceTable(normalizedWarehouseId);
const transaction = await this.ctx.model.transaction();
const { Op } = this.ctx.app.Sequelize;
let sourceRows = [];
let selectedSourceOrderIds = [];
const assertMigrationDeadline = stage => {
if (deadlineAt > 0 && Date.now() > deadlineAt) {
const timeoutError = new Error(`仓库 ${normalizedWarehouseId} ${stage} 执行超时`);
timeoutError.code = 'OUTBOUND_MIGRATION_TIMEOUT';
throw timeoutError;
}
};
try {
assertMigrationDeadline('出库迁移');
const {
sourceOrderModel,
targetOrderModel,
sourceItemModel,
targetItemModel,
} = await this.getMigrationModels(normalizedWarehouseId);
assertMigrationDeadline('查询源订单');
sourceRows = await sourceOrderModel.findAll({
where: {
warehouse_id: normalizedWarehouseId,
outbound_status: {
[Op.in]: outboundStatuses,
},
step: {
[Op.in]: OUTBOUND_SYNC_STEPS,
},
},
order: [[ 'id', 'ASC' ]],
limit: batchLimit,
raw: true,
...this.buildMigrationQueryOptions(transaction, queryTimeoutMs),
});
selectedSourceOrderIds = Array.from(new Set((Array.isArray(sourceRows) ? sourceRows : [])
.map(row => Number(row && row.id))
.filter(value => Number.isFinite(value) && value > 0)));
if (!Array.isArray(sourceRows) || sourceRows.length === 0) {
await transaction.commit();
return {
warehouseId: normalizedWarehouseId,
selectedCount: 0,
createdCount: 0,
skippedCount: 0,
timeoutCount: 0,
};
}
const invalidSourceRows = sourceRows.filter(row => !this.buildDispatchKey(row));
if (invalidSourceRows.length > 0) {
const invalidRowIds = invalidSourceRows
.map(row => Number(row && row.id))
.filter(value => Number.isFinite(value) && value > 0);
throw new Error(`选中的源订单存在缺少 delivery_order_code/store_id/warehouse_id 的记录${invalidRowIds.length > 0 ? `: ${invalidRowIds.join(', ')}` : ''}`);
}
const validSourceRows = sourceRows;
const sourceOrderRowMap = new Map(validSourceRows
.map(row => [ Number(row.id), row ])
.filter(([ rowId, row ]) => Number.isFinite(rowId) && rowId > 0 && this.buildDispatchKey(row)));
let deliveryOrderCodes = Array.from(new Set(validSourceRows
.map(row => String(row.delivery_order_code || '').trim())
.filter(Boolean)));
const sourceOrderIds = Array.from(sourceOrderRowMap.keys());
const orderCodeMap = new Map(); // source order_id → renamed delivery_order_code
let existingRows = [];
if (deliveryOrderCodes.length > 0) {
assertMigrationDeadline('查询配送表订单');
existingRows = await targetOrderModel.findAll({
where: {
warehouse_id: normalizedWarehouseId,
delivery_order_code: {
[Op.in]: deliveryOrderCodes,
},
},
raw: true,
...this.buildMigrationQueryOptions(transaction, queryTimeoutMs),
});
}
const existingKeySet = new Set((Array.isArray(existingRows) ? existingRows : [])
.map(row => this.buildDispatchKey(row))
.filter(Boolean));
const rowsToCreate = [];
for (const row of validSourceRows) {
let tryCode = String(row.delivery_order_code || '').trim();
const storeId = String(row.store_id || '').trim();
const warehouseId = String(row.warehouse_id || '').trim();
const originalKey = `${tryCode}::${storeId}::${warehouseId}`;
let seq = 2;
while (existingKeySet.has(`${tryCode}::${storeId}::${warehouseId}`)) {
tryCode = `${String(row.delivery_order_code || '').trim()}-${seq}`;
seq++;
}
const newKey = `${tryCode}::${storeId}::${warehouseId}`;
if (newKey !== originalKey) {
this.ctx.logger.info(
`[sync-outbound-orders-to-delivery] delivery_order_code 冲突,重命名: ${originalKey} → ${newKey}`
);
orderCodeMap.set(Number(row.id), tryCode);
}
existingKeySet.add(newKey);
const modifiedRow = tryCode !== String(row.delivery_order_code || '').trim()
? { ...row, delivery_order_code: tryCode }
: row;
rowsToCreate.push(this.buildDispatchRow(modifiedRow));
}
for (const renamedCode of orderCodeMap.values()) {
deliveryOrderCodes.push(renamedCode);
}
deliveryOrderCodes = Array.from(new Set(deliveryOrderCodes.filter(Boolean)));
if (rowsToCreate.length > 0) {
assertMigrationDeadline('创建配送表订单');
await targetOrderModel.bulkCreate(rowsToCreate, {
...this.buildMigrationQueryOptions(transaction, queryTimeoutMs),
});
// 更新序列表位置指针:current → dispatch。与上方 bulkCreate 处于同一事务,
// 任一步失败整体回滚,保证配送表数据与位置索引原子一致(存量订单自动补录,
// 显式 id 大于序列表水位时 MySQL 会自动推进,后续发号不会与存量 id 冲突)。
const locationFactory = this.ctx.model && this.ctx.model.OrderDeliveryFactory;
if (!locationFactory || typeof locationFactory.updateOrderLocation !== 'function') {
throw new Error('订单工厂缺少 updateOrderLocation,无法同步序列表位置指针');
}
for (const row of rowsToCreate) {
await locationFactory.updateOrderLocation(
Number(row.id),
normalizedWarehouseId,
'dispatch',
transaction
);
}
}
assertMigrationDeadline('查询配送表订单');
const targetRows = deliveryOrderCodes.length > 0
? await targetOrderModel.findAll({
where: {
warehouse_id: normalizedWarehouseId,
delivery_order_code: {
[Op.in]: deliveryOrderCodes,
},
},
raw: true,
...this.buildMigrationQueryOptions(transaction, queryTimeoutMs),
})
: [];
const targetOrderIdMap = this.buildTargetOrderIdMap(targetRows);
if (sourceOrderIds.length > 0) {
assertMigrationDeadline('查询商品明细');
const sourceItems = await sourceItemModel.findAll({
where: {
order_id: {
[Op.in]: sourceOrderIds,
},
},
order: [[ 'id', 'ASC' ]],
raw: true,
...this.buildMigrationQueryOptions(transaction, queryTimeoutMs),
});
const validSourceItems = Array.isArray(sourceItems)
? sourceItems.filter(item => Number.isFinite(Number(item && item.id)))
: [];
const rowsToCreateItems = validSourceItems.map(item => {
const sourceOrder = sourceOrderRowMap.get(Number(item.order_id));
const renamedCode = orderCodeMap.get(Number(item.order_id));
const key = renamedCode
? `${renamedCode}::${String(sourceOrder.store_id || '').trim()}::${String(sourceOrder.warehouse_id || '').trim()}`
: this.buildDispatchKey(sourceOrder);
const targetOrderId = targetOrderIdMap.get(key);
if (!Number.isFinite(targetOrderId) || targetOrderId <= 0) {
throw new Error(`无法找到订单 ${item.order_id} 对应的配送表订单ID`);
}
return this.buildDispatchItemRow(item, targetOrderId);
});
if (rowsToCreateItems.length > 0) {
assertMigrationDeadline('创建商品明细');
await targetItemModel.bulkCreate(rowsToCreateItems, {
...this.buildMigrationQueryOptions(transaction, queryTimeoutMs),
});
}
assertMigrationDeadline('删除源商品明细');
await sourceItemModel.destroy({
where: {
id: {
[Op.in]: validSourceItems.map(item => Number(item.id)).filter(value => Number.isFinite(value) && value > 0),
},
},
...this.buildMigrationQueryOptions(transaction, queryTimeoutMs),
});
}
if (sourceOrderIds.length > 0) {
assertMigrationDeadline('删除源订单');
await sourceOrderModel.destroy({
where: {
id: {
[Op.in]: sourceOrderIds,
},
},
...this.buildMigrationQueryOptions(transaction, queryTimeoutMs),
});
}
await transaction.commit();
return {
warehouseId: normalizedWarehouseId,
selectedCount: sourceRows.length,
createdCount: rowsToCreate.length,
skippedCount: sourceRows.length - rowsToCreate.length,
timeoutCount: 0,
};
} catch (error) {
await transaction.rollback();
const migrationErrorInfo = this.getOutboundMigrationErrorInfo(error);
const shouldPersistTimeoutState = persistTimeoutState && migrationErrorInfo.retryable && selectedSourceOrderIds.length > 0;
if (shouldPersistTimeoutState) {
const timeoutCount = await this.markOutboundOrdersTimeout(
normalizedWarehouseId,
selectedSourceOrderIds,
queryTimeoutMs
);
return {
warehouseId: normalizedWarehouseId,
selectedCount: sourceRows.length,
createdCount: 0,
skippedCount: 0,
timeoutCount,
retryableFailure: true,
retryableFailureType: migrationErrorInfo.category,
retryableFailureMessage: migrationErrorInfo.message,
};
}
if (migrationErrorInfo.retryable) {
return {
warehouseId: normalizedWarehouseId,
selectedCount: sourceRows.length,
createdCount: 0,
skippedCount: 0,
timeoutCount: 0,
retryableFailure: true,
retryableFailureType: migrationErrorInfo.category,
retryableFailureMessage: migrationErrorInfo.message,
};
}
throw error;
}
}
}
module.exports = OrderDeliveryMigrationService;