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 已正确注册该定时任务
This commit is contained in:
liufumingren 2026-09-15 18:19:57 +08:00
parent 4bf34410a3
commit 74e53d4d87
3 changed files with 1203 additions and 0 deletions

View File

@ -0,0 +1,384 @@
// app/schedule/archive_dispatch_orders_to_history.js
'use strict';
/**
* 配送表订单归档到历史表定时任务。
*
* 默认每日凌晨 06:00:00(cron:秒 分 时 日 月 周)在单 worker 中执行一次,
* 把 `wms_order_delivery_{仓库}_dispatch` 中创建时间距今超过 4 个月
* (或迁移进配送表时间距今超过 3 个月)的订单,连同商品明细一起归档到
* `_history` 分表,并同步更新订单索引表 `wms_order_id_location_{仓库}` 的位置指针。
*
* cron / 开关从 config.orderDeliveryArchive 读取(config.default.js 提供默认值),
* 本地环境可在 config.local.js 覆盖为短间隔以便快速验证,不影响生产 06:00 触发时间。
*
* 中断与重跑安全(本任务每日只跑一轮,必须具备"断了也能接着跑"的性质):
* 1. 单批一个事务:写入历史表 + 更新位置指针 + 删除源行 全部成功或全部回滚,
* 不会出现"历史表有数据但配送表没删"的中间态;
* 2. 已迁移的行在提交时即从配送表删除,重新执行时查询不会命中 → 天然幂等续跑;
* 3. 单批失败(死锁等重试耗尽)只跳过该批并推进游标,不中断整轮,未迁移的行留待下一轮;
* 4. 跨进程互斥用 Redis 锁(NX + TTL),进程被杀后锁到期自动释放,下一轮可继续;
* 5. 每批进度写入 Redis(progress key),日志与进度缓存均可观察"跑到哪、迁了多少"。
*/
/** 执行记录缓存 key(最近一次执行) */
const EXECUTION_LOG_CACHE_KEY = 'schedule:archive_dispatch_to_history:last_execution';
/** 执行记录缓存 TTL(秒) */
const EXECUTION_LOG_CACHE_TTL = 300;
/** 执行历史缓存 key(保留最近 N 次) */
const EXECUTION_LOG_HISTORY_CACHE_KEY = 'schedule:archive_dispatch_to_history:history';
/** 执行历史保留条数 */
const EXECUTION_LOG_HISTORY_MAX = 20;
/** 执行历史缓存 TTL(秒) */
const EXECUTION_LOG_HISTORY_TTL = 86400;
/** 跨进程互斥锁 key */
const LOCK_CACHE_KEY = 'schedule:archive_dispatch_to_history:lock';
/** 进度缓存 key(供人工观察断点位置) */
const PROGRESS_CACHE_KEY = 'schedule:archive_dispatch_to_history:progress';
/** 进度缓存 TTL(秒):保留 2 天,便于次日对比上一轮跑到哪里 */
const PROGRESS_CACHE_TTL = 2 * 24 * 60 * 60;
/** 默认 cron:每日凌晨 06:00 */
const DEFAULT_CRON = '0 0 6 * * *';
/** 默认互斥锁 TTL(秒),需覆盖单轮最长执行时间 */
const DEFAULT_LOCK_TTL_SECONDS = 30 * 60;
/**
* 获取 Redis cache 客户端。
*
* @param {Object} app Egg 应用实例。
* @return {Object|null} Redis 客户端或 null。
*/
function getCacheRedisClient(app) {
if (!app || !app.redis || typeof app.redis.get !== 'function') {
return null;
}
try {
return app.redis.get('cache') || null;
} catch (error) {
return null;
}
}
/**
* 获取互斥锁(SET NX EX)。
*
* @param {Object} ctx Egg 上下文。
* @param {number} ttlSeconds 锁 TTL(秒)。
* @return {Promise<boolean>} 是否获取成功;Redis 不可用时返回 true(退化为进程内防重入)。
*/
async function acquireLock(ctx, ttlSeconds) {
const redis = getCacheRedisClient(ctx.app);
if (!redis || typeof redis.set !== 'function') {
ctx.logger.warn('[archive-dispatch-to-history] Redis 不可用,跨进程互斥降级为进程内防重入');
return true;
}
try {
const result = await redis.set(LOCK_CACHE_KEY, String(process.pid || ''), 'EX', ttlSeconds, 'NX');
return result === 'OK';
} catch (error) {
ctx.logger.warn(`[archive-dispatch-to-history] 获取互斥锁失败(按未加锁继续): ${error.message}`);
return true;
}
}
/**
* 释放互斥锁。
*
* @param {Object} ctx Egg 上下文。
* @return {Promise<void>} 无返回值。
*/
async function releaseLock(ctx) {
const redis = getCacheRedisClient(ctx.app);
if (!redis || typeof redis.del !== 'function') {
return;
}
try {
await redis.del(LOCK_CACHE_KEY);
} catch (error) {
ctx.logger.warn(`[archive-dispatch-to-history] 释放互斥锁失败(等待 TTL 过期): ${error.message}`);
}
}
/**
* 写入进度缓存。
*
* @param {Object} ctx Egg 上下文。
* @param {Object} payload 进度内容。
* @return {Promise<void>} 无返回值。
*/
async function writeProgress(ctx, payload) {
try {
if (ctx.app && typeof ctx.app.setCacheAsync === 'function') {
await ctx.app.setCacheAsync(PROGRESS_CACHE_KEY, {
...payload,
updated_at: new Date().toISOString(),
}, PROGRESS_CACHE_TTL);
}
} catch (error) {
ctx.logger.warn(`[archive-dispatch-to-history] 写入进度缓存失败: ${error.message}`);
}
}
/**
* 读取上一轮进度缓存(用于识别"上一轮被中断")。
*
* @param {Object} ctx Egg 上下文。
* @return {Promise<Object|null>} 上一轮进度。
*/
async function readProgress(ctx) {
try {
if (ctx.app && typeof ctx.app.getCacheAsync === 'function') {
const cached = await ctx.app.getCacheAsync(PROGRESS_CACHE_KEY);
return cached && typeof cached === 'object' ? cached : null;
}
} catch (error) {
ctx.logger.warn(`[archive-dispatch-to-history] 读取进度缓存失败: ${error.message}`);
}
return null;
}
/**
* 将本次执行日志写入缓存。
*
* @param {Object} ctx Egg 上下文。
* @param {Object} logEntry 日志条目。
* @return {Promise<void>} 无返回值。
*/
async function writeExecutionLogToCache(ctx, logEntry) {
try {
if (ctx.app && typeof ctx.app.setCacheAsync === 'function') {
await ctx.app.setCacheAsync(EXECUTION_LOG_CACHE_KEY, logEntry, EXECUTION_LOG_CACHE_TTL);
}
} catch (error) {
ctx.logger.warn(`[archive-dispatch-to-history] 写入执行日志缓存失败: ${error.message}`);
}
}
/**
* 将本次执行日志追加到历史记录缓存(保留最近 N 次)。
*
* @param {Object} ctx Egg 上下文。
* @param {Object} logEntry 日志条目。
* @return {Promise<void>} 无返回值。
*/
async function appendExecutionHistory(ctx, logEntry) {
try {
if (typeof ctx.app.getCacheAsync !== 'function' || typeof ctx.app.setCacheAsync !== 'function') {
return;
}
const rawHistory = await ctx.app.getCacheAsync(EXECUTION_LOG_HISTORY_CACHE_KEY);
const history = Array.isArray(rawHistory) ? rawHistory : [];
history.unshift(logEntry);
await ctx.app.setCacheAsync(
EXECUTION_LOG_HISTORY_CACHE_KEY,
history.slice(0, EXECUTION_LOG_HISTORY_MAX),
EXECUTION_LOG_HISTORY_TTL
);
} catch (error) {
ctx.logger.warn(`[archive-dispatch-to-history] 写入执行历史缓存失败: ${error.message}`);
}
}
/**
* 提取错误详情,方便定位问题位置。
*
* @param {Error} error 错误对象。
* @return {Object} 错误详情。
*/
function extractErrorDetail(error) {
if (!error) return {};
const detail = {
name: error.name || '',
message: error.message || '',
code: error.code || '',
};
if (error.parent) {
detail.parent = {
name: error.parent.name || '',
message: error.parent.message || '',
code: error.parent.code || '',
sql: error.parent.sql || '',
};
}
if (error.stack) {
detail.stack_top = error.stack.split('\n').slice(0, 4).map(line => line.trim());
}
return detail;
}
/**
* 每日凌晨 06:00 归档配送表超期订单到历史表。
*
* @param {Object} app Egg 应用实例。
* @return {Object} 定时任务定义(含 schedule 与 task)。
*/
module.exports = app => {
const archiveConfig = (app.config && app.config.orderDeliveryArchive) || {};
const archiveCron = typeof archiveConfig.cron === 'string' && archiveConfig.cron
? archiveConfig.cron
: DEFAULT_CRON;
const lockTtlSeconds = Number(archiveConfig.lockTtlSeconds) > 0
? Number(archiveConfig.lockTtlSeconds)
: DEFAULT_LOCK_TTL_SECONDS;
return {
schedule: {
cron: archiveCron,
type: 'worker',
immediate: false,
disable: archiveConfig.enable === false,
},
/**
* 执行配送表订单归档。
*
* 任务失败只记录错误日志,不向上抛出,避免 schedule 崩溃;
* 未归档完成的订单保留在配送表,下一轮(或人工重跑)继续。
*
* @param {Object} ctx Egg 上下文。
* @return {Promise<void>} 无返回值。
*/
async task(ctx) {
const scheduleName = 'archive_dispatch_orders_to_history';
if (ctx.app._archiveDispatchOrdersToHistoryRunning) {
ctx.logger.info(`[${scheduleName}] 本轮任务跳过,上一轮尚未结束`);
return;
}
const previousProgress = await readProgress(ctx);
if (previousProgress && previousProgress.status === 'running') {
ctx.logger.warn(
`[${scheduleName}] 检测到上一轮未正常结束(status=running, started_at=${previousProgress.started_at || '-'}),本轮按断点续跑:已迁移订单已从配送表移除,不会重复处理`
);
}
const lockAcquired = await acquireLock(ctx, lockTtlSeconds);
if (!lockAcquired) {
ctx.logger.info(`[${scheduleName}] 未获取到互斥锁,判定其他进程正在执行,本轮跳过`);
return;
}
ctx.app._archiveDispatchOrdersToHistoryRunning = true;
const startedAt = Date.now();
const startedAtIso = new Date(startedAt).toISOString();
let status = 'success';
let errorMessage = '';
let errorDetail = null;
let result = null;
await writeProgress(ctx, {
status: 'running',
started_at: startedAtIso,
trigger: 'schedule',
pid: process.pid,
});
try {
result = await ctx.service.systems.orderDeliveryArchive.archiveDispatchOrdersToHistory({}, {
onBatch: async batch => {
await writeProgress(ctx, {
status: 'running',
started_at: startedAtIso,
trigger: 'schedule',
pid: process.pid,
warehouse_id: batch.warehouseId,
batch_index: batch.batchIndex,
last_id: batch.lastId,
total_selected: batch.summary.selectedCount,
total_archived: batch.summary.archivedCount,
total_items_archived: batch.summary.itemsArchivedCount,
failed_batches: batch.summary.failedBatches,
});
},
});
if (result.totalFailedBatches > 0) {
status = 'partial_failure';
errorMessage = `failedBatches=${result.totalFailedBatches}, failedRows=${result.totalFailedCount}`;
ctx.logger.warn(
`[${scheduleName}] 本轮存在 ${result.totalFailedBatches} 个失败批次(共 ${result.totalFailedCount} 条订单未迁移),已跳过并保留在配送表,下一轮继续`
);
}
if (result.backlogRemaining) {
status = status === 'success' ? 'partial_budget_exhausted' : status;
ctx.logger.warn(
`[${scheduleName}] 单轮时长上限用尽,仍有仓库未处理完(elapsedMs=${result.elapsedMs}),剩余订单将在下一轮继续归档`
);
}
ctx.logger.info(
`[${scheduleName}] 本轮完成 archived=${result.totalArchived} alreadyArchived=${result.totalAlreadyArchived} itemsArchived=${result.totalItemsArchived} selected=${result.totalSelected} failedBatches=${result.totalFailedBatches} elapsedMs=${result.elapsedMs}`
);
} catch (error) {
status = 'error';
errorMessage = error.message;
errorDetail = extractErrorDetail(error);
ctx.logger.error(`[${scheduleName}] 归档失败: ${error.message}`, errorDetail);
} finally {
ctx.app._archiveDispatchOrdersToHistoryRunning = false;
await releaseLock(ctx);
}
const logEntry = {
executed_at: new Date().toISOString(),
duration_ms: Date.now() - startedAt,
status,
error_message: errorMessage,
error_detail: errorDetail,
total_selected: result ? result.totalSelected : 0,
total_archived: result ? result.totalArchived : 0,
total_already_archived: result ? result.totalAlreadyArchived : 0,
total_items_archived: result ? result.totalItemsArchived : 0,
total_failed_batches: result ? result.totalFailedBatches : 0,
total_failed_count: result ? result.totalFailedCount : 0,
backlog_remaining: result ? Boolean(result.backlogRemaining) : false,
warehouse_ids: result ? result.warehouseIds : [],
warehouses: result
? result.results.map(item => ({
warehouse_id: item.warehouseId,
batches: item.batches,
archived: item.archivedCount,
items_archived: item.itemsArchivedCount,
failed_batches: item.failedBatches,
last_id: item.lastId,
stop_reason: item.stopReason,
}))
: [],
};
await writeExecutionLogToCache(ctx, logEntry);
await appendExecutionHistory(ctx, logEntry);
await writeProgress(ctx, {
status,
started_at: startedAtIso,
finished_at: new Date().toISOString(),
trigger: 'schedule',
pid: process.pid,
elapsed_ms: logEntry.duration_ms,
total_archived: logEntry.total_archived,
total_failed_batches: logEntry.total_failed_batches,
backlog_remaining: logEntry.backlog_remaining,
warehouses: logEntry.warehouses,
});
ctx.logger.info(
`[${scheduleName}] 执行日志已写入缓存 key=${EXECUTION_LOG_CACHE_KEY} history=${EXECUTION_LOG_HISTORY_CACHE_KEY} progress=${PROGRESS_CACHE_KEY}`
);
},
};
};

View File

@ -0,0 +1,795 @@
'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;

View File

@ -253,6 +253,30 @@ module.exports = appInfo => {
sleepMinMs: 100,
sleepMaxMs: 500,
};
// 配送表(dispatch) → 历史表(history) 归档定时任务配置
// 每日凌晨 06:00 把配送表超期订单(连同商品明细)迁入历史表,并更新订单索引表位置指针
config.orderDeliveryArchive = {
// 开关:false 时不注册本定时任务
enable: true,
// 触发 cron(秒 分 时 日 月 周):默认每日凌晨 06:00;本地环境可在 config.local.js 覆盖为短间隔
cron: '0 0 6 * * *',
// 归档门槛一:订单创建时间(create_at)距今超过该月数即归档(dispath_time 为 NULL 的存量单只靠此条)
archiveAfterMonths: 4,
// 归档门槛二:迁移进配送表时间(dispath_time)距今超过该月数即归档
dispatchStayMonths: 3,
// 单批条数(单批一个事务:写历史表 + 更新位置指针 + 删源行)
batchSize: 1000,
// 单仓库单轮最多批次数(异常情况下防死循环)
maxBatchesPerWarehouse: 200,
// 单轮总时长上限(毫秒):用尽后停止本轮,剩余订单下一轮继续(避免闯入业务高峰)
maxRunMs: 30 * 60 * 1000,
// 单批查询超时(毫秒)
queryTimeoutMs: 60 * 1000,
// 单批事务遇到死锁/锁等待的最大尝试次数
batchMaxAttempts: 3,
// 跨进程互斥锁 TTL(秒),需覆盖单轮最长执行时间;进程被杀后锁到期自动释放
lockTtlSeconds: 30 * 60,
};
// 打印自定义区模板出口域名
config.customAreaBaseUrl = 'https://api.ye4s.com';
// 仓库前端独立部署:证书部署目录。