WMS_MAIN/app/service/systems/order_delivery_archive.js
liufumingren 74e53d4d87 feat(order): 新增配送表超期订单归档到历史表定时任务
- 新增 systems/orderDeliveryArchive(app/service/systems/order_delivery_archive.js):
  把 wms_order_delivery_{仓库}_dispatch 中 dispath_time 距今超过 3 个月、或 create_at
  距今超过 4 个月的订单(不限状态)归档到 _history 分表;dispath_time 为 NULL 的存量
  订单不特殊处理,SQL 三值逻辑下自动由 create_at 条件兜底
- 单批默认 1000 条、一个事务内完成:写历史表(剔除历史表不存在的
  dispatch_lane/dispath_time、写 archive_time=归档时刻、id 原样复制)→ 同步复制
  wms_order_items_*_dispatch 商品明细(补 archive_time)→ 更新订单索引表
  wms_order_id_location_* 的 location 为 history → 删除源行(先子表后主表),任一步
  失败整体回滚,不产生「历史表有数据但配送表没删」的中间态
- 可续跑 / 防中断:批量提交且提交即删除源行,重跑天然幂等;实际条件列
  (create_at/dispath_time)无索引,故按主键 id 游标取候选、禁用 OFFSET;单批遇
  死锁/锁等待重试 3 次后跳过该批并推进游标(上报 failedBatches/failedCount),
  不中断整轮;单轮时长预算 maxRunMs 用尽即停止本轮,剩余订单下一轮继续
- 历史表已存在同 id 记录(历史残留/人工补数)时不重复写入但仍清理源行,保证重复
  执行结果一致
- 新增 app/schedule/archive_dispatch_orders_to_history.js:默认每日 06:00 单 worker
  执行(cron 可配),Redis SET NX EX 跨进程互斥(进程被杀靠 TTL 释放)+ 批级进度
  缓存 + 执行日志缓存,上一轮 status=running 时按断点续跑
- 新增 config.orderDeliveryArchive 配置:开关/cron/归档门槛月数/单批条数/单仓批次
  上限/单轮时长预算/查询超时/重试次数/锁 TTL
- 本地开发库实测 44 项断言全部通过:字段保真(订单与明细逐列一致、archive_time
  正确、无 dispatch_lane/dispath_time、id 原样复制)、索引表位置更新、源行删除、
  幂等复跑、注入失败整批回滚、单批失败后继续、限额用尽后重跑续传、预算用尽停止、
  无同 id 双写与孤立明细残留;Egg 已正确注册该定时任务
2026-09-15 18:19:57 +08:00

796 lines
30 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');
/** 单批处理条数(与 current → dispatch 迁移保持一致,单批一个事务) */
const MAX_BATCH_SIZE = 1000;
/** 归档门槛:订单创建时间(create_at)距今超过该月数即归档 */
const DEFAULT_ARCHIVE_AFTER_MONTHS = 4;
/** 归档门槛:订单迁移进配送表(dispath_time)距今超过该月数即归档 */
const DEFAULT_DISPATCH_STAY_MONTHS = 3;
/** 单仓库单轮最多处理的批次数(异常情况下防止死循环) */
const DEFAULT_MAX_BATCHES_PER_WAREHOUSE = 200;
/** 单轮总时长上限(毫秒):超过后停止本轮,剩余订单下一轮继续 */
const DEFAULT_MAX_RUN_MS = 30 * 60 * 1000;
/** 单批查询超时(毫秒) */
const DEFAULT_QUERY_TIMEOUT_MS = 60 * 1000;
/** 单批事务遇到死锁/锁等待时的最大尝试次数 */
const DEFAULT_BATCH_MAX_ATTEMPTS = 3;
/** 重试基础退避毫秒数(按尝试次数线性放大) */
const BATCH_RETRY_BASE_DELAY_MS = 50;
/** 历史表位置标识(写入订单索引表 wms_order_id_location_{仓库}.location) */
const HISTORY_LOCATION = 'history';
/** 配送域分表名匹配(仅 _dispatch 参与归档) */
const DISPATCH_TABLE_PATTERN = /^wms_order_delivery_(\d+)_dispatch$/;
/** 可重试的数据库锁错误码 */
const RETRYABLE_DATABASE_ERROR_CODES = new Set([ 1205, 1213, 'ER_LOCK_WAIT_TIMEOUT', 'ER_LOCK_DEADLOCK' ]);
/**
* 按自然月回退时间(与 MySQL DATE_SUB(NOW(), INTERVAL n MONTH) 语义一致:
* 目标月份天数不足时取该月最后一天,如 3/31 回退 1 个月 → 2/28)。
*
* @param {Date} baseDate 基准时间。
* @param {number} months 回退月数(正整数)。
* @return {Date} 回退后的时间。
*/
function subtractMonths(baseDate, months) {
const base = baseDate instanceof Date ? baseDate : new Date(baseDate);
const normalizedMonths = Math.max(0, Math.floor(Number(months) || 0));
if (normalizedMonths === 0) {
return new Date(base.getTime());
}
const day = base.getDate();
const target = new Date(base.getTime());
// 先落到 1 号再回退月份,避免 9/30 回退 1 个月时被 JS 进位成 10/30
target.setDate(1);
target.setMonth(target.getMonth() - normalizedMonths);
const daysInTargetMonth = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();
target.setDate(Math.min(day, daysInTargetMonth));
return target;
}
/**
* 规范化正整数配置项。
*
* @param {*} value 原始值。
* @param {number} fallback 回退值。
* @return {number} 规范化结果。
*/
function normalizePositiveNumber(value, fallback) {
const parsed = Number(value);
return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
}
/**
* 配送表订单归档到历史表的同步服务。
*
* 归档链路(单批一个事务,全部成功或全部回滚):
* 1. 从 `wms_order_delivery_{仓库}_dispatch` 按主键游标取候选订单
* (create_at 距今 > 4 个月,或 dispath_time 距今 > 3 个月);
* 2. 复制订单行到 `_history`(剔除历史表不存在的 dispatch_lane / dispath_time,
* 写入 archive_time = 当前时刻),id 原样复制(多表共用 id 契约);
* 3. 同步复制商品明细 `wms_order_items_{仓库}_dispatch` → `_history`;
* 4. 更新订单索引表 `wms_order_id_location_{仓库}` 的 location 为 history;
* 5. 硬删除 dispatch 源行(先子表后主表)。
*
* 幂等与可续跑:每批提交后源行已消失,重跑查询不会命中;若历史表已存在同 id
* 记录(上一轮中断或人工补数的残留),则跳过写入但仍清理源行,保证重复执行安全。
*/
class OrderDeliveryArchiveService extends MainService {
/**
* 读取归档任务默认参数(config.orderDeliveryArchive 优先)。
*
* @return {Object} 归档参数。
*/
getArchiveDefaults() {
const config = (this.app && this.app.config && this.app.config.orderDeliveryArchive) || {};
return {
archiveAfterMonths: normalizePositiveNumber(config.archiveAfterMonths, DEFAULT_ARCHIVE_AFTER_MONTHS),
dispatchStayMonths: normalizePositiveNumber(config.dispatchStayMonths, DEFAULT_DISPATCH_STAY_MONTHS),
batchSize: Math.min(
normalizePositiveNumber(config.batchSize, MAX_BATCH_SIZE),
MAX_BATCH_SIZE
),
maxBatchesPerWarehouse: normalizePositiveNumber(
config.maxBatchesPerWarehouse,
DEFAULT_MAX_BATCHES_PER_WAREHOUSE
),
maxRunMs: normalizePositiveNumber(config.maxRunMs, DEFAULT_MAX_RUN_MS),
queryTimeoutMs: normalizePositiveNumber(config.queryTimeoutMs, DEFAULT_QUERY_TIMEOUT_MS),
batchMaxAttempts: normalizePositiveNumber(config.batchMaxAttempts, DEFAULT_BATCH_MAX_ATTEMPTS),
};
}
/**
* 合并调用方参数与默认参数。
*
* @param {Object} options 调用方参数。
* @return {Object} 合并后的参数。
*/
buildArchiveOptions(options = {}) {
const defaults = this.getArchiveDefaults();
const source = this.isPlainObject(options) ? options : {};
return {
archiveAfterMonths: normalizePositiveNumber(source.archiveAfterMonths, defaults.archiveAfterMonths),
dispatchStayMonths: normalizePositiveNumber(source.dispatchStayMonths, defaults.dispatchStayMonths),
batchSize: Math.min(normalizePositiveNumber(source.batchSize, defaults.batchSize), MAX_BATCH_SIZE),
maxBatchesPerWarehouse: normalizePositiveNumber(source.maxBatchesPerWarehouse, defaults.maxBatchesPerWarehouse),
maxRunMs: normalizePositiveNumber(source.maxRunMs, defaults.maxRunMs),
queryTimeoutMs: normalizePositiveNumber(source.queryTimeoutMs, defaults.queryTimeoutMs),
batchMaxAttempts: normalizePositiveNumber(source.batchMaxAttempts, defaults.batchMaxAttempts),
};
}
/**
* 构造归档时间门槛。
*
* 使用应用进程时钟(而非数据库 NOW()):dispath_time / create_at 均由应用以
* `new Date()` 写入,两者同源比较可避免数据库时区与服务时区不一致带来的偏差。
*
* @param {Date} [now] 基准时间,默认当前时间。
* @param {Object} options 归档参数。
* @return {{ now: Date, createThreshold: Date, dispatchThreshold: Date }} 门槛集合。
*/
buildArchiveThresholds(now = new Date(), options = {}) {
const resolved = this.buildArchiveOptions(options);
const baseTime = now instanceof Date ? now : new Date();
return {
now: baseTime,
createThreshold: subtractMonths(baseTime, resolved.archiveAfterMonths),
dispatchThreshold: subtractMonths(baseTime, resolved.dispatchStayMonths),
};
}
/**
* 规范化仓库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 listDispatchWarehouseIds() {
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 = DISPATCH_TABLE_PATTERN.exec(String(tableName || ''));
return matched ? Number(matched[1]) : null;
})
.filter(value => Number.isFinite(value) && value > 0)))
.sort((left, right) => left - right);
}
/**
* 获取归档所需的模型集合。
*
* @param {number} warehouseId 仓库ID。
* @return {Promise<Object>} 模型集合。
*/
async getArchiveModels(warehouseId) {
const orderFactory = this.ctx.model && this.ctx.model.OrderDeliveryFactory;
const itemsFactory = this.ctx.model && this.ctx.model.OrderItemsFactory;
if (!orderFactory
|| typeof orderFactory.getDispatchModel !== 'function'
|| typeof orderFactory.getHistoryModel !== 'function') {
throw new Error('订单工厂未初始化,无法获取配送表/历史表模型');
}
if (!itemsFactory
|| typeof itemsFactory.getDispatchModel !== 'function'
|| typeof itemsFactory.getHistoryModel !== 'function') {
throw new Error('订单商品工厂未初始化,无法获取配送表/历史表模型');
}
return {
dispatchOrderModel: await orderFactory.getDispatchModel(warehouseId),
historyOrderModel: await orderFactory.getHistoryModel(warehouseId),
dispatchItemModel: await itemsFactory.getDispatchModel(warehouseId),
historyItemModel: await itemsFactory.getHistoryModel(warehouseId),
};
}
/**
* 构造候选订单查询条件。
*
* 仅取 _dispatch 分表内满足下列任一条件的订单:
* - 创建时间距今超过 archiveAfterMonths(默认 4 个月);
* - 迁移进配送表时间(dispath_time)距今超过 dispatchStayMonths(默认 3 个月)。
*
* 注意:dispath_time 为 NULL 的存量订单由上述 OR 的另一分支(create_at)兜底,
* 无需显式 IS NULL 判断 —— SQL 三值逻辑下 `dispath_time < ?` 对 NULL 结果为
* UNKNOWN,天然不会命中。
*
* 游标条件用主键 id(条件列 create_at / dispath_time 均无索引),
* 避免生产大表上的全表扫描 + filesort。
*
* @param {number} warehouseId 仓库ID。
* @param {number} lastId 上一批处理到的最大 id(0 表示从头开始)。
* @param {Object} thresholds 归档时间门槛。
* @return {Object} Sequelize where 条件。
*/
buildCandidateWhere(warehouseId, lastId, thresholds) {
const { Op } = this.ctx.app.Sequelize;
const normalizedLastId = Number(lastId);
return {
warehouse_id: warehouseId,
id: Number.isFinite(normalizedLastId) && normalizedLastId > 0
? { [Op.gt]: normalizedLastId }
: { [Op.gt]: 0 },
[Op.or]: [
{ dispath_time: { [Op.lt]: thresholds.dispatchThreshold } },
{ create_at: { [Op.lt]: thresholds.createThreshold } },
],
};
}
/**
* 构造 Sequelize 查询参数(事务 + 超时)。
*
* @param {Object|null} transaction 事务对象。
* @param {number} [queryTimeoutMs] 查询超时时间。
* @return {Object} Sequelize 查询参数。
*/
buildQueryOptions(transaction, queryTimeoutMs) {
const queryOptions = {};
if (transaction) {
queryOptions.transaction = transaction;
}
const normalizedTimeoutMs = Number(queryTimeoutMs);
if (Number.isFinite(normalizedTimeoutMs) && normalizedTimeoutMs > 0) {
queryOptions.timeout = normalizedTimeoutMs;
}
return queryOptions;
}
/**
* 构造写入历史表的订单行。
*
* 历史表比配送表少两列,必须剔除,否则 Sequelize 属性映射会静默丢弃/报错:
* - dispatch_lane:配送域车道,仅 dispatch 分表存在;
* - dispath_time:迁移进配送表的时间,仅 dispatch 分表存在
* (迁出/迁入时刻统一由 archive_time 表达)。
*
* @param {Object} row 配送表订单行。
* @param {Date} archiveTime 归档时间。
* @return {Object} 可写入历史表的订单行。
*/
buildHistoryOrderRow(row, archiveTime) {
const payload = { ...(row || {}) };
delete payload.dispatch_lane;
delete payload.dispath_time;
payload.archive_time = archiveTime;
return payload;
}
/**
* 构造写入历史表的商品明细行。
*
* 商品配送表与历史表列完全一致(历史表仅多 archive_time),无需剔除字段。
*
* @param {Object} row 配送表商品明细行。
* @param {Date} archiveTime 归档时间。
* @return {Object} 可写入历史表的商品明细行。
*/
buildHistoryItemRow(row, archiveTime) {
return {
...(row || {}),
archive_time: archiveTime,
};
}
/**
* 识别可重试的数据库锁错误。
*
* @param {Error} error 运行时错误。
* @return {{ retryable: boolean, category: string, message: string }} 分类结果。
*/
getArchiveErrorInfo(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 {Object} transaction 事务对象。
* @return {Promise<void>} 无返回值。
*/
async rollbackQuietly(transaction) {
if (!transaction || typeof transaction.rollback !== 'function') {
return;
}
try {
await transaction.rollback();
} catch (error) {
this.ctx.logger.warn(`[archive-dispatch-to-history] 事务回滚失败: ${error.message}`);
}
}
/**
* 单批归档:查询候选 → 写历史表 → 更新位置指针 → 删除源行,全部在一个事务内完成。
*
* @param {number|string} warehouseId 仓库ID。
* @param {Object} [params] 单批参数。
* @param {number} [params.lastId] 上一批处理到的最大 id。
* @param {number} [params.batchSize] 单批条数。
* @param {Object} [params.thresholds] 归档时间门槛。
* @param {Object} [options] 归档参数。
* @return {Promise<Object>} 单批结果。
*/
async archiveDispatchBatch(warehouseId, params = {}, options = {}) {
const resolved = this.buildArchiveOptions(options);
const normalizedWarehouseId = Number(warehouseId);
if (!Number.isFinite(normalizedWarehouseId) || normalizedWarehouseId <= 0) {
throw new Error('仓库ID不能为空');
}
const batchSize = Math.min(normalizePositiveNumber(params.batchSize, resolved.batchSize), MAX_BATCH_SIZE);
const lastId = Number(params.lastId) > 0 ? Number(params.lastId) : 0;
const thresholds = params.thresholds || this.buildArchiveThresholds(new Date(), resolved);
const archiveTime = new Date();
const { Op } = this.ctx.app.Sequelize;
// 序列表初始化可能执行 DDL(隐式提交),必须在事务外完成:
// 位置指针与历史表写入必须同事务原子完成,无索引表宁可整批失败重试。
await this.ctx.model.OrderDeliveryFactory.ensureLocationSequenceTable(normalizedWarehouseId);
const transaction = await this.ctx.model.transaction();
try {
const models = await this.getArchiveModels(normalizedWarehouseId);
// 加行锁读取候选:归档会删除源行,锁住候选可避免与并发修改(如拦截确认)
// 交错导致"归档了旧值、删掉了新值"。
const candidateRows = await models.dispatchOrderModel.findAll({
where: this.buildCandidateWhere(normalizedWarehouseId, lastId, thresholds),
order: [[ 'id', 'ASC' ]],
limit: batchSize,
raw: true,
lock: transaction.LOCK.UPDATE,
...this.buildQueryOptions(transaction, resolved.queryTimeoutMs),
});
const rows = Array.isArray(candidateRows) ? candidateRows : [];
const orderIds = Array.from(new Set(rows
.map(row => Number(row && row.id))
.filter(value => Number.isFinite(value) && value > 0)));
if (orderIds.length === 0) {
await transaction.commit();
return {
warehouseId: normalizedWarehouseId,
lastId,
maxCandidateId: lastId,
selectedCount: 0,
archivedCount: 0,
alreadyArchivedCount: 0,
itemsSelectedCount: 0,
itemsArchivedCount: 0,
hasMore: false,
};
}
const maxCandidateId = Math.max(...orderIds);
// 幂等保护:历史表已存在同 id 记录(上一轮中断残留 / 人工补数)时不再重复写入,
// 但仍清理源行,保证本任务重复执行或跨轮次执行结果一致。
const existingHistoryRows = await models.historyOrderModel.findAll({
where: { id: { [Op.in]: orderIds } },
attributes: [ 'id' ],
raw: true,
...this.buildQueryOptions(transaction, resolved.queryTimeoutMs),
});
const existingHistoryIdSet = new Set((Array.isArray(existingHistoryRows) ? existingHistoryRows : [])
.map(row => Number(row && row.id)));
const rowsToArchive = rows.filter(row => !existingHistoryIdSet.has(Number(row.id)));
// 商品明细:按 order_id 一并搬迁(子表同步迁入)
const dispatchItems = await models.dispatchItemModel.findAll({
where: { order_id: { [Op.in]: orderIds } },
order: [[ 'id', 'ASC' ]],
raw: true,
...this.buildQueryOptions(transaction, resolved.queryTimeoutMs),
});
const itemRows = Array.isArray(dispatchItems) ? dispatchItems : [];
const itemIds = Array.from(new Set(itemRows
.map(row => Number(row && row.id))
.filter(value => Number.isFinite(value) && value > 0)));
let itemsToArchive = itemRows;
if (itemIds.length > 0) {
const existingHistoryItems = await models.historyItemModel.findAll({
where: { id: { [Op.in]: itemIds } },
attributes: [ 'id' ],
raw: true,
...this.buildQueryOptions(transaction, resolved.queryTimeoutMs),
});
const existingItemIdSet = new Set((Array.isArray(existingHistoryItems) ? existingHistoryItems : [])
.map(row => Number(row && row.id)));
itemsToArchive = itemRows.filter(row => !existingItemIdSet.has(Number(row.id)));
}
if (rowsToArchive.length > 0) {
await models.historyOrderModel.bulkCreate(
rowsToArchive.map(row => this.buildHistoryOrderRow(row, archiveTime)),
this.buildQueryOptions(transaction, resolved.queryTimeoutMs)
);
}
if (itemsToArchive.length > 0) {
await models.historyItemModel.bulkCreate(
itemsToArchive.map(row => this.buildHistoryItemRow(row, archiveTime)),
this.buildQueryOptions(transaction, resolved.queryTimeoutMs)
);
}
// 订单索引表位置指针 dispatch → history,与历史表写入同事务,
// 保证「订单去向」与数据所在表位原子一致。
const locationFactory = this.ctx.model && this.ctx.model.OrderDeliveryFactory;
if (!locationFactory || typeof locationFactory.updateOrderLocation !== 'function') {
throw new Error('订单工厂缺少 updateOrderLocation,无法同步订单索引表位置');
}
for (const orderId of orderIds) {
await locationFactory.updateOrderLocation(orderId, normalizedWarehouseId, HISTORY_LOCATION, transaction);
}
// 删除源行:先子表后主表
if (itemIds.length > 0) {
await models.dispatchItemModel.destroy({
where: { id: { [Op.in]: itemIds } },
...this.buildQueryOptions(transaction, resolved.queryTimeoutMs),
});
}
await models.dispatchOrderModel.destroy({
where: { id: { [Op.in]: orderIds } },
...this.buildQueryOptions(transaction, resolved.queryTimeoutMs),
});
await transaction.commit();
return {
warehouseId: normalizedWarehouseId,
lastId: maxCandidateId,
maxCandidateId,
selectedCount: orderIds.length,
archivedCount: rowsToArchive.length,
alreadyArchivedCount: orderIds.length - rowsToArchive.length,
itemsSelectedCount: itemIds.length,
itemsArchivedCount: itemsToArchive.length,
hasMore: rows.length >= batchSize,
};
} catch (error) {
await this.rollbackQuietly(transaction);
throw error;
}
}
/**
* 归档指定仓库的配送表订单(按主键游标循环分批,直到无候选或达到限额)。
*
* @param {number|string} warehouseId 仓库ID。
* @param {Object} [options] 归档参数。
* @param {Function} [options.onBatch] 单批完成回调(用于上报进度)。
* @param {Function} [options.shouldStop] 外部中断判断回调。
* @return {Promise<Object>} 仓库归档汇总。
*/
async archiveDispatchOrdersForWarehouse(warehouseId, options = {}) {
const resolved = this.buildArchiveOptions(options);
const normalizedWarehouseId = Number(warehouseId);
if (!Number.isFinite(normalizedWarehouseId) || normalizedWarehouseId <= 0) {
throw new Error('仓库ID不能为空');
}
const thresholds = options.thresholds || this.buildArchiveThresholds(new Date(), resolved);
const deadlineAt = options.deadlineAt > 0 ? Number(options.deadlineAt) : 0;
const onBatch = typeof options.onBatch === 'function' ? options.onBatch : null;
const shouldStop = typeof options.shouldStop === 'function' ? options.shouldStop : null;
const summary = {
warehouseId: normalizedWarehouseId,
batches: 0,
selectedCount: 0,
archivedCount: 0,
alreadyArchivedCount: 0,
itemsArchivedCount: 0,
failedBatches: 0,
failedCount: 0,
lastId: Number(options.lastId) > 0 ? Number(options.lastId) : 0,
stopReason: '',
};
for (let batchIndex = 0; batchIndex < resolved.maxBatchesPerWarehouse; batchIndex++) {
if (shouldStop && shouldStop()) {
summary.stopReason = 'external_stop';
break;
}
if (deadlineAt > 0 && Date.now() >= deadlineAt) {
summary.stopReason = 'run_budget_exhausted';
break;
}
let batchResult = null;
let lastError = null;
for (let attempt = 1; attempt <= resolved.batchMaxAttempts; attempt++) {
try {
batchResult = await this.archiveDispatchBatch(normalizedWarehouseId, {
lastId: summary.lastId,
batchSize: resolved.batchSize,
thresholds,
}, resolved);
break;
} catch (error) {
lastError = error;
const errorInfo = this.getArchiveErrorInfo(error);
if (!errorInfo.retryable || attempt >= resolved.batchMaxAttempts) {
break;
}
this.ctx.logger.warn(
`[archive-dispatch-to-history] 仓库 ${normalizedWarehouseId} 第 ${batchIndex + 1} 批遇到 ${errorInfo.category},`
+ `重试 ${attempt}/${resolved.batchMaxAttempts}: ${errorInfo.message}`
);
await new Promise(resolve => setTimeout(resolve, BATCH_RETRY_BASE_DELAY_MS * attempt));
}
}
if (!batchResult) {
// 单批彻底失败:记录后越过该批(游标推进到候选范围内已知的最大 id),
// 避免整轮卡死在同一批;未迁移的行保留在配送表,下一轮继续尝试。
summary.failedBatches += 1;
summary.stopReason = 'batch_failure';
this.ctx.logger.error(
`[archive-dispatch-to-history] 仓库 ${normalizedWarehouseId} 第 ${batchIndex + 1} 批归档失败,已跳过该批: `
+ `${lastError ? lastError.message : 'unknown error'}`
);
const skippedLastId = await this.resolveFailureCursor(normalizedWarehouseId, summary.lastId, thresholds, resolved);
summary.failedCount += skippedLastId.failedCount;
summary.lastId = skippedLastId.lastId;
if (!skippedLastId.advanced) {
break;
}
continue;
}
summary.batches += 1;
summary.selectedCount += batchResult.selectedCount;
summary.archivedCount += batchResult.archivedCount;
summary.alreadyArchivedCount += batchResult.alreadyArchivedCount;
summary.itemsArchivedCount += batchResult.itemsArchivedCount;
summary.lastId = batchResult.lastId;
if (onBatch) {
await onBatch({ ...batchResult, batchIndex: batchIndex + 1, summary: { ...summary } });
}
// 未取满一批(hasMore=false)说明候选已清空;取满但下一轮可能仍有候选,继续循环
if (batchResult.selectedCount === 0 || !batchResult.hasMore) {
summary.stopReason = 'no_more_candidates';
break;
}
}
if (!summary.stopReason) {
summary.stopReason = 'max_batches_reached';
}
return summary;
}
/**
* 单批失败后推进游标:取该批候选范围内的最大 id,返回下一次查询起点。
*
* @param {number} warehouseId 仓库ID。
* @param {number} lastId 当前游标。
* @param {Object} thresholds 归档时间门槛。
* @param {Object} options 归档参数。
* @return {Promise<{ lastId: number, failedCount: number, advanced: boolean }>} 游标结果。
*/
async resolveFailureCursor(warehouseId, lastId, thresholds, options) {
try {
const models = await this.getArchiveModels(warehouseId);
const rows = await models.dispatchOrderModel.findAll({
where: this.buildCandidateWhere(warehouseId, lastId, thresholds),
attributes: [ 'id' ],
order: [[ 'id', 'ASC' ]],
limit: options.batchSize,
raw: true,
...this.buildQueryOptions(null, options.queryTimeoutMs),
});
const idList = (Array.isArray(rows) ? rows : [])
.map(row => Number(row && row.id))
.filter(value => Number.isFinite(value) && value > 0);
if (idList.length === 0) {
return { lastId, failedCount: 0, advanced: false };
}
return {
lastId: Math.max(...idList),
failedCount: idList.length,
advanced: true,
};
} catch (error) {
this.ctx.logger.error(`[archive-dispatch-to-history] 推进失败游标时查询失败: ${error.message}`);
return { lastId, failedCount: 0, advanced: false };
}
}
/**
* 归档全部(或指定)仓库的配送表订单。
*
* 每批一个事务、失败仅推进游标不中断整体,因此任务中断后重新执行即可续跑:
* 已迁移的行已从配送表删除,不会重复处理。
*
* @param {Object} [data] 请求参数。
* @param {number|Array<number|string>} [data.warehouseId] 单个仓库ID或仓库ID列表。
* @param {Array<number|string>} [data.warehouseIds] 仓库ID列表。
* @param {Object} [options] 归档参数(可覆盖 config.orderDeliveryArchive)。
* @param {Function} [options.onBatch] 单批完成回调。
* @param {Function} [options.onWarehouseDone] 单仓库完成回调。
* @return {Promise<Object>} 归档汇总结果。
*/
async archiveDispatchOrdersToHistory(data = {}, options = {}) {
const resolved = this.buildArchiveOptions(options);
const requestData = this.isPlainObject(data) ? data : {};
const explicitWarehouseIds = this.normalizeWarehouseIds(requestData);
const warehouseIds = explicitWarehouseIds.length > 0
? explicitWarehouseIds
: await this.listDispatchWarehouseIds();
const startedAt = Date.now();
const deadlineAt = startedAt + resolved.maxRunMs;
const thresholds = this.buildArchiveThresholds(new Date(startedAt), resolved);
const results = [];
let totalSelected = 0;
let totalArchived = 0;
let totalAlreadyArchived = 0;
let totalItemsArchived = 0;
let totalFailedBatches = 0;
let totalFailedCount = 0;
for (const warehouseId of warehouseIds) {
if (Date.now() >= deadlineAt) {
results.push({
warehouseId,
batches: 0,
selectedCount: 0,
archivedCount: 0,
alreadyArchivedCount: 0,
itemsArchivedCount: 0,
failedBatches: 0,
failedCount: 0,
lastId: 0,
stopReason: 'run_budget_exhausted',
});
continue;
}
const warehouseResult = await this.archiveDispatchOrdersForWarehouse(warehouseId, {
...resolved,
thresholds,
deadlineAt,
onBatch: options.onBatch,
shouldStop: options.shouldStop,
});
results.push(warehouseResult);
totalSelected += warehouseResult.selectedCount;
totalArchived += warehouseResult.archivedCount;
totalAlreadyArchived += warehouseResult.alreadyArchivedCount;
totalItemsArchived += warehouseResult.itemsArchivedCount;
totalFailedBatches += warehouseResult.failedBatches;
totalFailedCount += warehouseResult.failedCount;
if (typeof options.onWarehouseDone === 'function') {
await options.onWarehouseDone(warehouseResult);
}
}
const backlogRemaining = results.some(result => result.stopReason === 'run_budget_exhausted');
return {
warehouseIds,
batchSize: resolved.batchSize,
archiveAfterMonths: resolved.archiveAfterMonths,
dispatchStayMonths: resolved.dispatchStayMonths,
thresholds: {
createThreshold: thresholds.createThreshold.toISOString(),
dispatchThreshold: thresholds.dispatchThreshold.toISOString(),
},
elapsedMs: Date.now() - startedAt,
totalSelected,
totalArchived,
totalAlreadyArchived,
totalItemsArchived,
totalFailedBatches,
totalFailedCount,
backlogRemaining,
results,
};
}
}
module.exports = OrderDeliveryArchiveService;