feat: 系统日志定时清理任务(每日 03:00,硬删除超保留期日志)

- 新增 app/schedule/system_log_cleanup.js 定时任务:cron 从 config.systemLogCleanup.cron 读取(缺省回退 '0 0 3 * * *'),受 enable 开关与防重入保护

- 新增 app/service/systems/system_log.js:按 id 边界定位 + 分批硬删除超期日志,保留天数默认 60(normalizeRetainDays 校验非法值回退),批间随机休眠降低数据库压力

- config.default.js 新增 config.systemLogCleanup 配置块:enable、cron、retainDays 60、batchSize 2000、sleepMinMs/sleepMaxMs

- 新增 service 与 schedule 单测(39 个用例),覆盖边界定位、保留天数校验、配置开关与防重入等场景
This commit is contained in:
liufumingren 2026-09-08 17:00:05 +08:00
parent 68dbf65c77
commit 67a70d0394
5 changed files with 859 additions and 0 deletions

View File

@ -0,0 +1,88 @@
// app/schedule/system_log_cleanup.js
'use strict';
/** @type {number} 默认单批硬删除行数 */
const DEFAULT_BATCH_SIZE = 2000;
/** @type {number} 默认批间休眠最小毫秒数 */
const DEFAULT_SLEEP_MIN_MS = 100;
/** @type {number} 默认批间休眠最大毫秒数 */
const DEFAULT_SLEEP_MAX_MS = 500;
/**
* 系统日志超期清理定时任务。
*
* 默认每日凌晨 03:00:00(cron:秒 分 时 日 月 周)在单 worker 中执行一次,
* 硬删除 wms_system_log 超过保留天数(默认 60 天)的日志以释放磁盘空间,避开 08:00–23:00 业务高峰。
* cron 从 config.systemLogCleanup.cron 读取(config.default.js 提供默认值),
* 本地环境可在 config.local.js 覆盖为短间隔以便快速验证,不影响生产 03:00 触发时间。
* 保留天数由 service.systems.systemLog 读取 config.systemLogCleanup.retainDays(默认 60,非法值回退 60);
* 由 config.systemLogCleanup 控制:enable=false 时不注册本任务;
* 实际清理逻辑收敛在 service.systems.systemLog.cleanupExpiredSystemLogs。
*
* @param {Object} app Egg 应用实例。
* @return {Object} 定时任务定义(含 schedule 与 task)。
*/
module.exports = app => {
const cleanupConfig = (app.config && app.config.systemLogCleanup) || {};
// cron 从配置读取,缺省时回退为每日凌晨 03:00(cron 格式:秒 分 时 日 月 周)
const cleanupCron = typeof cleanupConfig.cron === 'string' && cleanupConfig.cron
? cleanupConfig.cron
: '0 0 3 * * *';
return {
schedule: {
cron: cleanupCron,
type: 'worker',
immediate: false,
disable: cleanupConfig.enable === false,
},
/**
* 执行系统日志超期清理。
*
* 采用单 worker 防重入:上一轮未结束时跳过本轮;
* 任务失败只记录错误日志,不向上抛出,避免导致 schedule 崩溃。
*
* @param {Object} ctx Egg 上下文。
* @return {Promise<void>} 无返回值。
*/
async task(ctx) {
const scheduleName = 'system_log_cleanup';
if (ctx.app._systemLogCleanupRunning) {
ctx.logger.info(`[${scheduleName}] 本轮任务跳过,上一轮尚未结束`);
return;
}
ctx.app._systemLogCleanupRunning = true;
const startedAt = Date.now();
try {
const config = ctx.app.config.systemLogCleanup || {};
// 保留天数(retainDays)由 service 读取 config.systemLogCleanup.retainDays 自行解析,此处不再透传
const options = {
batchSize: Number(config.batchSize) > 0
? Math.floor(Number(config.batchSize))
: DEFAULT_BATCH_SIZE,
sleepMinMs: Number(config.sleepMinMs) >= 0
? Math.floor(Number(config.sleepMinMs))
: DEFAULT_SLEEP_MIN_MS,
sleepMaxMs: Number(config.sleepMaxMs) >= 0
? Math.floor(Number(config.sleepMaxMs))
: DEFAULT_SLEEP_MAX_MS,
};
const summary = await ctx.service.systems.systemLog.cleanupExpiredSystemLogs(options);
ctx.logger.info(
`[${scheduleName}] 本轮完成 skipped=${summary.skipped} boundary_id=${summary.boundary_id}`
+ ` batches=${summary.batch_count} deleted=${summary.deleted_rows}`
+ ` duration=${Date.now() - startedAt}ms`
);
} catch (error) {
ctx.logger.error(`[${scheduleName}] 执行失败: ${error.message}`);
} finally {
ctx.app._systemLogCleanupRunning = false;
}
},
};
};

View File

@ -0,0 +1,180 @@
// app/service/systems/system_log.js
'use strict';
const MainService = require('../main');
/** @type {string} 系统日志表名 */
const SYSTEM_LOG_TABLE = 'wms_system_log';
/** @type {number} 默认日志保留天数:删除创建时间早于该天数的日志 */
const DEFAULT_RETAIN_DAYS = 60;
/** @type {number} 默认单批硬删除行数 */
const DEFAULT_BATCH_SIZE = 2000;
/** @type {number} 默认批间休眠最小毫秒数 */
const DEFAULT_SLEEP_MIN_MS = 100;
/** @type {number} 默认批间休眠最大毫秒数 */
const DEFAULT_SLEEP_MAX_MS = 500;
/**
* 休眠指定毫秒数。
*
* @param {number} ms 休眠毫秒数。
* @return {Promise<void>} 无返回值。
*/
function sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
/**
* 将保留天数归一化为正整数。
*
* 仅接受正整数(含数字字符串),其余非法值(负数、0、小数、非数字)一律回退默认保留天数;
* 归一化后的值直接拼入 SQL 模板的 INTERVAL 表达式,保证无 SQL 注入风险。
*
* @param {*} value 待归一化的保留天数。
* @return {number} 归一化后的正整数保留天数。
*/
function normalizeRetainDays(value) {
const normalized = Number(value);
return Number.isInteger(normalized) && normalized > 0 ? normalized : DEFAULT_RETAIN_DAYS;
}
/**
* 系统日志清理服务。
*
* 背景:wms_system_log 单表无分表无分区,日志长期增长会占用大量磁盘空间。
* created_at 由应用写入 new Date(),与自增主键 id 严格单调递增,且 created_at 无索引,
* 因此按时间条件过滤会全表扫描,必须按 id 边界走主键索引删除;
* 同时必须使用原生 SQL 硬删除,禁止 SystemLog.destroy(全局 paranoid 软删除会增大行体积且语义不符)。
*/
class SystemLogService extends MainService {
/**
* 定位删除边界 id:创建时间早于保留天数截止时间的最大 id。
*
* 由于 created_at 与 id 严格单调递增,id 不大于该边界的行即全部过期行,
* 等价于按 created_at 时间边界删除且走主键索引;查不到时返回 null 表示无过期日志。
*
* @param {number} retainDays 日志保留天数(正整数;非法值回退默认 60)。
* @return {Promise<number|null>} 边界 id;无过期日志时返回 null。
*/
async findCleanupBoundaryId(retainDays) {
const { ctx } = this;
const safeRetainDays = normalizeRetainDays(retainDays);
const rows = await ctx.model.query(
`SELECT id FROM ${SYSTEM_LOG_TABLE}`
+ ` WHERE created_at < DATE_SUB(NOW(), INTERVAL ${safeRetainDays} DAY)`
+ ' ORDER BY id DESC LIMIT 1',
{ type: ctx.model.QueryTypes.SELECT }
);
const firstRow = Array.isArray(rows) ? rows[0] : null;
const boundaryId = firstRow ? Number(firstRow.id) : null;
return Number.isInteger(boundaryId) && boundaryId > 0 ? boundaryId : null;
}
/**
* 单批硬删除 id 不大于边界值的系统日志(每批最多 batchSize 行)。
*
* @param {number} boundaryId 删除边界 id(含边界行本身)。
* @param {number} batchSize 单批最大删除行数。
* @return {Promise<number>} 本批实际删除行数。
*/
async deleteSystemLogsBatch(boundaryId, batchSize) {
const { ctx } = this;
const safeBoundaryId = Number(boundaryId) > 0 ? Math.floor(Number(boundaryId)) : 0;
const safeBatchSize = Number(batchSize) > 0 ? Math.floor(Number(batchSize)) : DEFAULT_BATCH_SIZE;
if (safeBoundaryId <= 0) {
return 0;
}
// 不传 type:默认走 RAW 查询,mysql2 对 DELETE 返回 ResultSetHeader,
// 取 [result, data] 结构中第一项的 affectedRows 作为本批删除行数
const rawResult = await ctx.model.query(
`DELETE FROM ${SYSTEM_LOG_TABLE}`
+ ` WHERE id <= ${safeBoundaryId}`
+ ' ORDER BY id'
+ ` LIMIT ${safeBatchSize}`
);
const header = Array.isArray(rawResult) ? rawResult[0] : rawResult;
const affectedRows = Number(header && header.affectedRows);
return Number.isFinite(affectedRows) && affectedRows > 0 ? affectedRows : 0;
}
/**
* 清理超过保留天数的系统日志(定时任务入口)。
*
* 流程:先定位边界 id,再按 id 升序分批硬删除,循环到单批受影响行数为 0 为止,
* 批间随机休眠 100~500ms 降低数据库压力;不执行 OPTIMIZE TABLE,
* 由 InnoDB 自行复用已删除数据页,避免重建大表占满磁盘。
*
* @param {Object} [options={}] 清理参数。
* @param {number} [options.retainDays] 日志保留天数(正整数);缺省时读取
* config.systemLogCleanup.retainDays,仍非法或未配置时回退 60。
* @param {number} [options.batchSize=2000] 单批硬删除行数。
* @param {number} [options.sleepMinMs=100] 批间休眠最小毫秒数。
* @param {number} [options.sleepMaxMs=500] 批间休眠最大毫秒数。
* @return {Promise<Object>} 清理结果摘要。
*/
async cleanupExpiredSystemLogs(options = {}) {
const { ctx } = this;
const startedAt = Date.now();
const safeOptions = options && typeof options === 'object' ? options : {};
const cleanupConfig = (ctx.app.config && ctx.app.config.systemLogCleanup) || {};
const rawRetainDays = safeOptions.retainDays !== undefined && safeOptions.retainDays !== null
? safeOptions.retainDays
: cleanupConfig.retainDays;
const retainDays = normalizeRetainDays(rawRetainDays);
const batchSize = Number(safeOptions.batchSize) > 0
? Math.floor(Number(safeOptions.batchSize))
: DEFAULT_BATCH_SIZE;
const sleepMinMs = Number(safeOptions.sleepMinMs) >= 0
? Math.floor(Number(safeOptions.sleepMinMs))
: DEFAULT_SLEEP_MIN_MS;
let sleepMaxMs = Number(safeOptions.sleepMaxMs) >= 0
? Math.floor(Number(safeOptions.sleepMaxMs))
: DEFAULT_SLEEP_MAX_MS;
if (sleepMaxMs < sleepMinMs) {
sleepMaxMs = sleepMinMs;
}
const boundaryId = await this.findCleanupBoundaryId(retainDays);
if (boundaryId === null) {
ctx.logger.info(`[system-log-cleanup] 无超过 ${retainDays} 天的系统日志,跳过本次清理`);
return {
skipped: true,
boundary_id: null,
batch_count: 0,
deleted_rows: 0,
duration_ms: Date.now() - startedAt,
};
}
let batchCount = 0;
let totalDeleted = 0;
let affectedRows = 1;
while (affectedRows > 0) {
if (batchCount > 0) {
const sleepMs = Math.floor(sleepMinMs + Math.random() * (sleepMaxMs - sleepMinMs + 1));
await sleep(sleepMs);
}
affectedRows = await this.deleteSystemLogsBatch(boundaryId, batchSize);
if (affectedRows > 0) {
batchCount += 1;
totalDeleted += affectedRows;
}
}
return {
skipped: false,
boundary_id: boundaryId,
batch_count: batchCount,
deleted_rows: totalDeleted,
duration_ms: Date.now() - startedAt,
};
}
}
module.exports = SystemLogService;

View File

@ -236,6 +236,19 @@ module.exports = appInfo => {
// 单轮批处理大小(按 id 升序分批)
batchSize: 50,
};
// 系统日志超期清理定时任务配置(每日凌晨 03:00 执行,硬删除 wms_system_log 超期数据释放磁盘空间)
config.systemLogCleanup = {
enable: true,
// 触发 cron(秒 分 时 日 月 周):默认每日凌晨 03:00;本地环境可在 config.local.js 覆盖为短间隔
cron: '0 0 3 * * *',
// 日志保留天数:删除 created_at 早于该天数的日志(默认 60 天,仅接受正整数,非法值回退 60)
retainDays: 60,
// 单批硬删除行数(按 id 升序分批,走主键索引)
batchSize: 2000,
// 批间休眠毫秒数下限/上限:在区间内随机取值,降低数据库瞬时压力
sleepMinMs: 100,
sleepMaxMs: 500,
};
// 打印自定义区模板出口域名
config.customAreaBaseUrl = 'https://api.ye4s.com';

View File

@ -0,0 +1,195 @@
'use strict';
const assert = require('node:assert/strict');
const fs = require('node:fs');
const path = require('node:path');
const scheduleFactory = require('../../../app/schedule/system_log_cleanup');
/**
* 创建定时任务测试上下文(纯 mock,不连接任何数据库)。
*
* @param {Object} [options={}] 测试配置。
* @param {Object} [options.config] app.config(默认 { systemLogCleanup: {} })。
* @param {boolean} [options.running] 初始防重入标记。
* @param {boolean} [options.serviceThrows] 清理服务是否抛错。
* @return {Object} { app, ctx, logs, getCleanupCallCount, getCleanupCallArgs }
*/
function createScheduleCtx(options = {}) {
const config = options.config !== undefined ? options.config : { systemLogCleanup: {} };
const logs = { info: [], warn: [], error: [] };
let cleanupCallCount = 0;
let cleanupCallArgs = null;
const app = {
_systemLogCleanupRunning: Boolean(options.running),
config,
};
const ctx = {
app,
logger: {
info(message) { logs.info.push(message); },
warn(message) { logs.warn.push(message); },
error(message) { logs.error.push(message); },
},
service: {
systems: {
systemLog: {
async cleanupExpiredSystemLogs(args) {
cleanupCallCount += 1;
cleanupCallArgs = args;
if (options.serviceThrows) {
throw new Error('模拟清理失败');
}
return {
skipped: false,
boundary_id: 100,
batch_count: 2,
deleted_rows: 4000,
duration_ms: 1,
};
},
},
},
},
};
return {
app,
ctx,
logs,
getCleanupCallCount() { return cleanupCallCount; },
getCleanupCallArgs() { return cleanupCallArgs; },
};
}
describe('test/app/schedule/system_log_cleanup.test.js', () => {
describe('任务注册', () => {
it('每日凌晨 03:00 单 worker 执行,默认启用', () => {
const schedule = scheduleFactory({ config: { systemLogCleanup: {} } });
assert.equal(schedule.schedule.cron, '0 0 3 * * *');
assert.equal(schedule.schedule.type, 'worker');
assert.equal(schedule.schedule.immediate, false);
assert.equal(schedule.schedule.disable, false);
});
it('config.systemLogCleanup.enable=false 时任务禁用', () => {
const schedule = scheduleFactory({ config: { systemLogCleanup: { enable: false } } });
assert.equal(schedule.schedule.disable, true);
});
it('配置整体缺失时默认启用', () => {
const schedule = scheduleFactory({ config: {} });
assert.equal(schedule.schedule.disable, false);
});
it('cron 从 config.systemLogCleanup.cron 读取,缺失或非法时回退每日 03:00', () => {
const custom = scheduleFactory({ config: { systemLogCleanup: { cron: '0 */10 * * * *' } } });
assert.equal(custom.schedule.cron, '0 */10 * * * *');
const fallback = scheduleFactory({ config: { systemLogCleanup: { cron: 0 } } });
assert.equal(fallback.schedule.cron, '0 0 3 * * *');
});
});
describe('task 执行', () => {
it('正常执行:仅透传 batchSize/sleepMinMs/sleepMaxMs(不再解析 retainDays)、完成日志输出、finally 释放防重入标记', async () => {
const harness = createScheduleCtx({
config: {
systemLogCleanup: {
retainDays: 90,
batchSize: 500,
sleepMinMs: 10,
sleepMaxMs: 20,
},
},
});
const schedule = scheduleFactory({ config: harness.app.config });
await schedule.task(harness.ctx);
assert.equal(harness.getCleanupCallCount(), 1);
assert.deepEqual(harness.getCleanupCallArgs(), {
batchSize: 500,
sleepMinMs: 10,
sleepMaxMs: 20,
});
assert.equal(harness.app._systemLogCleanupRunning, false, '任务结束后应释放防重入标记');
assert.equal(harness.logs.info.some(message => message.includes('本轮完成')), true);
});
it('防重入:上一轮未结束时跳过本轮且不调用服务', async () => {
const harness = createScheduleCtx({ running: true });
const schedule = scheduleFactory({ config: harness.app.config });
await schedule.task(harness.ctx);
assert.equal(harness.getCleanupCallCount(), 0);
assert.equal(harness.app._systemLogCleanupRunning, true, '跳过时不应改动防重入标记');
assert.equal(harness.logs.info.some(message => message.includes('跳过')), true);
});
it('服务异常时仅记录错误日志、不向上抛出、finally 复位', async () => {
const harness = createScheduleCtx({ serviceThrows: true });
const schedule = scheduleFactory({ config: harness.app.config });
await assert.doesNotReject(() => schedule.task(harness.ctx));
assert.equal(harness.getCleanupCallCount(), 1);
assert.equal(harness.app._systemLogCleanupRunning, false);
assert.equal(harness.logs.error.length, 1);
assert.match(harness.logs.error[0], /执行失败/);
});
it('配置非法时回退默认值:batchSize=2000、sleepMinMs=100、sleepMaxMs=500', async () => {
const harness = createScheduleCtx({
config: {
systemLogCleanup: {
batchSize: -1,
sleepMinMs: -5,
sleepMaxMs: -5,
},
},
});
const schedule = scheduleFactory({ config: harness.app.config });
await schedule.task(harness.ctx);
assert.deepEqual(harness.getCleanupCallArgs(), {
batchSize: 2000,
sleepMinMs: 100,
sleepMaxMs: 500,
});
});
it('配置整体缺失时任务按默认参数执行', async () => {
const harness = createScheduleCtx({ config: {} });
const schedule = scheduleFactory({ config: harness.app.config });
await schedule.task(harness.ctx);
assert.equal(harness.getCleanupCallCount(), 1);
assert.deepEqual(harness.getCleanupCallArgs(), {
batchSize: 2000,
sleepMinMs: 100,
sleepMaxMs: 500,
});
});
});
describe('配置文件静态回归(定时恢复每日 03:00 扫描、保留 60 天)', () => {
const DEFAULT_CONFIG_PATH = path.join(__dirname, '../../../config/config.default.js');
const LOCAL_CONFIG_PATH = path.join(__dirname, '../../../config/config.local.js');
it('config.default.js 提供 systemLogCleanup 默认 cron 03:00 与 retainDays 60', () => {
const source = fs.readFileSync(DEFAULT_CONFIG_PATH, 'utf8');
assert.match(source, /cron: '0 0 3 \* \* \*'/);
assert.match(source, /retainDays: 60/);
});
it('config.local.js 不得再覆盖 systemLogCleanup(每分钟 cron 覆盖已移除)', () => {
const source = fs.readFileSync(LOCAL_CONFIG_PATH, 'utf8');
assert.doesNotMatch(source, /systemLogCleanup/);
});
});
});

View File

@ -0,0 +1,383 @@
'use strict';
const assert = require('node:assert/strict');
const fs = require('node:fs');
const path = require('node:path');
const SystemLogService = require('../../../../app/service/systems/system_log');
const SERVICE_SOURCE_PATH = path.join(__dirname, '../../../../app/service/systems/system_log.js');
/**
* 创建系统日志清理服务的测试上下文(纯 mock,不连接任何数据库)。
*
* @param {Function} [queryHandler] 自定义 query 处理器,接收 (sql, options, callIndex)。
* @return {Object} { service, ctx, captures }
*/
function createHarness(queryHandler) {
const captures = { queries: [] };
const ctx = {
app: { config: {} },
service: {},
model: {
QueryTypes: { SELECT: 'SELECT' },
async query(sql, queryOptions) {
captures.queries.push({ sql, options: queryOptions });
if (typeof queryHandler === 'function') {
return await queryHandler(sql, queryOptions, captures.queries.length);
}
return [];
},
},
logger: {
debug() {},
info() {},
warn() {},
error() {},
},
};
const service = new SystemLogService(ctx);
return { service, ctx, captures };
}
/**
* 按 SQL 类型返回预设结果:SELECT 返回边界行,DELETE 依次返回各批 affectedRows。
*
* @param {Array<Object>} selectRows SELECT 结果行。
* @param {Array<number>} deleteAffectedRows DELETE 各批 affectedRows 序列。
* @return {Function} query 处理器。
*/
function sequenceQueryHandler(selectRows, deleteAffectedRows) {
const pending = deleteAffectedRows.slice();
return sql => {
if (/^SELECT/.test(sql)) {
return selectRows;
}
return [{ affectedRows: pending.shift() }, undefined ];
};
}
/**
* 临时替换 global.setTimeout:捕获休眠时长并立即回调,避免测试真实等待。
*
* @param {Function} handler 执行体,接收捕获到的休眠时长数组。
* @return {Promise<Object>} { result, sleepDelays }
*/
async function runWithStubbedTimers(handler) {
const realSetTimeout = global.setTimeout;
const sleepDelays = [];
global.setTimeout = (callback, delay) => {
if (typeof delay === 'number') {
sleepDelays.push(delay);
}
return realSetTimeout(callback, 0);
};
try {
const result = await handler(sleepDelays);
return { result, sleepDelays };
} finally {
global.setTimeout = realSetTimeout;
}
}
describe('test/app/service/systems/system_log.test.js', () => {
describe('normalizeRetainDays 保留天数归一化(经 findCleanupBoundaryId 的 SQL 断言)', () => {
it('正整数保留原值:30 生成 INTERVAL 30 DAY', async () => {
const { service, captures } = createHarness(() => []);
await service.findCleanupBoundaryId(30);
assert.match(captures.queries[0].sql, /INTERVAL 30 DAY/);
});
it('数字字符串归一化为整数:\'45\' 生成 INTERVAL 45 DAY', async () => {
const { service, captures } = createHarness(() => []);
await service.findCleanupBoundaryId('45');
assert.match(captures.queries[0].sql, /INTERVAL 45 DAY/);
});
it('负数回退默认 60:-10 生成 INTERVAL 60 DAY', async () => {
const { service, captures } = createHarness(() => []);
await service.findCleanupBoundaryId(-10);
assert.match(captures.queries[0].sql, /INTERVAL 60 DAY/);
});
it('0 回退默认 60:生成 INTERVAL 60 DAY', async () => {
const { service, captures } = createHarness(() => []);
await service.findCleanupBoundaryId(0);
assert.match(captures.queries[0].sql, /INTERVAL 60 DAY/);
});
it('小数回退默认 60:30.5 生成 INTERVAL 60 DAY', async () => {
const { service, captures } = createHarness(() => []);
await service.findCleanupBoundaryId(30.5);
assert.match(captures.queries[0].sql, /INTERVAL 60 DAY/);
});
it('非数字回退默认 60:\'abc\' 生成 INTERVAL 60 DAY', async () => {
const { service, captures } = createHarness(() => []);
await service.findCleanupBoundaryId('abc');
assert.match(captures.queries[0].sql, /INTERVAL 60 DAY/);
});
it('null/undefined 回退默认 60', async () => {
const { service: service1, captures: captures1 } = createHarness(() => []);
await service1.findCleanupBoundaryId(null);
assert.match(captures1.queries[0].sql, /INTERVAL 60 DAY/);
const { service: service2, captures: captures2 } = createHarness(() => []);
await service2.findCleanupBoundaryId(undefined);
assert.match(captures2.queries[0].sql, /INTERVAL 60 DAY/);
});
});
describe('findCleanupBoundaryId 边界定位', () => {
it('返回超期行的最大 id 且 SQL 按 id 倒序取 1 行(默认 60 天)', async () => {
const { service, captures } = createHarness(() => [{ id: '987654' }]);
const boundaryId = await service.findCleanupBoundaryId(60);
assert.equal(boundaryId, 987654);
assert.equal(captures.queries.length, 1);
assert.match(captures.queries[0].sql, /SELECT id FROM wms_system_log/);
assert.match(captures.queries[0].sql, /WHERE created_at < DATE_SUB\(NOW\(\), INTERVAL 60 DAY\)/);
assert.match(captures.queries[0].sql, /ORDER BY id DESC LIMIT 1$/);
assert.equal(captures.queries[0].options.type, 'SELECT');
});
it('空表(查询返回 [])时返回 null', async () => {
const { service } = createHarness(() => []);
const boundaryId = await service.findCleanupBoundaryId(60);
assert.equal(boundaryId, null);
});
it('查询返回非数组(null)时返回 null', async () => {
const { service } = createHarness(() => null);
const boundaryId = await service.findCleanupBoundaryId(60);
assert.equal(boundaryId, null);
});
it('返回行缺少 id 字段时返回 null', async () => {
const { service } = createHarness(() => [{ created_at: '2026-01-01' }]);
const boundaryId = await service.findCleanupBoundaryId(60);
assert.equal(boundaryId, null);
});
});
describe('deleteSystemLogsBatch 分批硬删除', () => {
it('RAW DELETE 取 [ResultSetHeader, metadata] 第一项的 affectedRows', async () => {
const { service, captures } = createHarness(() => [{ affectedRows: 2000 }, undefined ]);
const affectedRows = await service.deleteSystemLogsBatch(42, 2000);
assert.equal(affectedRows, 2000);
const call = captures.queries[0];
assert.match(call.sql, /^DELETE FROM wms_system_log WHERE id <= 42 ORDER BY id LIMIT 2000$/);
assert.equal(call.options, undefined, '硬删除应走 RAW 查询,不传 type');
});
it('数组第二项也有 affectedRows 时仍取第一项', async () => {
const { service } = createHarness(() => [{ affectedRows: 7 }, { affectedRows: 999 }]);
const affectedRows = await service.deleteSystemLogsBatch(10, 2000);
assert.equal(affectedRows, 7);
});
it('非数组单对象返回时取 header.affectedRows', async () => {
const { service } = createHarness(() => ({ affectedRows: 5 }));
const affectedRows = await service.deleteSystemLogsBatch(10, 2000);
assert.equal(affectedRows, 5);
});
it('affectedRows 为 0 或非法时返回 0', async () => {
const harness1 = createHarness(() => [{ affectedRows: 0 }, undefined ]);
assert.equal(await harness1.service.deleteSystemLogsBatch(10, 2000), 0);
const harness2 = createHarness(() => [{}, undefined ]);
assert.equal(await harness2.service.deleteSystemLogsBatch(10, 2000), 0);
});
it('boundaryId 无效时不执行任何 SQL', async () => {
const { service, captures } = createHarness(() => {
throw new Error('不应被调用');
});
assert.equal(await service.deleteSystemLogsBatch(0, 2000), 0);
assert.equal(await service.deleteSystemLogsBatch(-1, 2000), 0);
assert.equal(captures.queries.length, 0);
});
});
describe('cleanupExpiredSystemLogs 清理主流程', () => {
it('查不到边界时 skipped 且不执行任何删除', async () => {
const { service, captures } = createHarness(() => []);
const summary = await service.cleanupExpiredSystemLogs();
assert.equal(summary.skipped, true);
assert.equal(summary.boundary_id, null);
assert.equal(summary.batch_count, 0);
assert.equal(summary.deleted_rows, 0);
const deleteQueries = captures.queries.filter(query => /^DELETE/.test(query.sql));
assert.equal(deleteQueries.length, 0);
});
it('分批循环删除到 affectedRows=0 为止,批数与总删除行数统计正确', async () => {
const { service, captures } = createHarness(
sequenceQueryHandler([{ id: 5000 }], [ 2000, 2000, 1000, 0 ])
);
const { result: summary, sleepDelays } = await runWithStubbedTimers(
() => service.cleanupExpiredSystemLogs()
);
assert.equal(summary.skipped, false);
assert.equal(summary.boundary_id, 5000);
assert.equal(summary.batch_count, 3);
assert.equal(summary.deleted_rows, 5000);
const deleteQueries = captures.queries.filter(query => /^DELETE/.test(query.sql));
// 3 个有效批次 + 1 个终止探测批(affectedRows=0)共 4 次 DELETE
assert.equal(deleteQueries.length, 4);
for (const query of deleteQueries) {
assert.match(query.sql, /WHERE id <= 5000/);
assert.match(query.sql, /LIMIT 2000$/);
}
// 批间休眠存在:第 2 批起每批前休眠一次(共 3 次),且默认区间 100~500ms
assert.equal(sleepDelays.length, 3);
for (const delay of sleepDelays) {
assert.ok(delay >= 100 && delay <= 500, `休眠时长 ${delay} 应在 100~500ms 区间内`);
}
});
it('边界行本身应被删除:DELETE 使用 <= 语义', async () => {
const { service, captures } = createHarness(
sequenceQueryHandler([{ id: 42 }], [ 1, 0 ])
);
const summary = await service.cleanupExpiredSystemLogs({ sleepMinMs: 0, sleepMaxMs: 0 });
assert.equal(summary.boundary_id, 42);
assert.equal(summary.deleted_rows, 1);
const deleteQuery = captures.queries.find(query => /^DELETE/.test(query.sql));
assert.match(deleteQuery.sql, /WHERE id <= 42/);
});
it('边界存在但首批 affectedRows=0 时统计为 0 批 0 行', async () => {
const { service } = createHarness(sequenceQueryHandler([{ id: 99 }], [ 0 ]));
const summary = await service.cleanupExpiredSystemLogs();
assert.equal(summary.skipped, false);
assert.equal(summary.boundary_id, 99);
assert.equal(summary.batch_count, 0);
assert.equal(summary.deleted_rows, 0);
});
it('参数非法时回退默认值:retainDays=-1 → INTERVAL 60 DAY、batchSize=-5 → LIMIT 2000', async () => {
const { service, captures } = createHarness(
sequenceQueryHandler([{ id: 9 }], [ 1, 0 ])
);
await service.cleanupExpiredSystemLogs({
retainDays: -1,
batchSize: -5,
sleepMinMs: 0,
sleepMaxMs: 0,
});
const selectQuery = captures.queries.find(query => /^SELECT/.test(query.sql));
const deleteQuery = captures.queries.find(query => /^DELETE/.test(query.sql));
assert.match(selectQuery.sql, /INTERVAL 60 DAY/);
assert.match(deleteQuery.sql, /LIMIT 2000$/);
});
it('解析优先级:options.retainDays 优先于 config.systemLogCleanup.retainDays', async () => {
const { service, ctx, captures } = createHarness(
sequenceQueryHandler([{ id: 9 }], [ 1, 0 ])
);
ctx.app.config = { systemLogCleanup: { retainDays: 90 } };
await service.cleanupExpiredSystemLogs({
retainDays: 30,
sleepMinMs: 0,
sleepMaxMs: 0,
});
const selectQuery = captures.queries.find(query => /^SELECT/.test(query.sql));
assert.match(selectQuery.sql, /INTERVAL 30 DAY/);
});
it('解析优先级:未传 options.retainDays 时读取 config.systemLogCleanup.retainDays', async () => {
const { service, ctx, captures } = createHarness(
sequenceQueryHandler([{ id: 9 }], [ 1, 0 ])
);
ctx.app.config = { systemLogCleanup: { retainDays: 90 } };
await service.cleanupExpiredSystemLogs({ sleepMinMs: 0, sleepMaxMs: 0 });
const selectQuery = captures.queries.find(query => /^SELECT/.test(query.sql));
assert.match(selectQuery.sql, /INTERVAL 90 DAY/);
});
it('解析优先级:options 与 config 均未提供保留天数时回退默认 60', async () => {
const { service, captures } = createHarness(
sequenceQueryHandler([{ id: 9 }], [ 1, 0 ])
);
await service.cleanupExpiredSystemLogs({ sleepMinMs: 0, sleepMaxMs: 0 });
const selectQuery = captures.queries.find(query => /^SELECT/.test(query.sql));
assert.match(selectQuery.sql, /INTERVAL 60 DAY/);
});
it('解析优先级:options.retainDays 非法时回退默认 60(不读取 config 值)', async () => {
const { service, ctx, captures } = createHarness(
sequenceQueryHandler([{ id: 9 }], [ 1, 0 ])
);
ctx.app.config = { systemLogCleanup: { retainDays: 90 } };
await service.cleanupExpiredSystemLogs({
retainDays: 0,
sleepMinMs: 0,
sleepMaxMs: 0,
});
const selectQuery = captures.queries.find(query => /^SELECT/.test(query.sql));
assert.match(selectQuery.sql, /INTERVAL 60 DAY/);
});
it('旧参数名 retentionDays 不再生效:回退默认 60', async () => {
const { service, captures } = createHarness(
sequenceQueryHandler([{ id: 9 }], [ 1, 0 ])
);
await service.cleanupExpiredSystemLogs({
retentionDays: 30,
sleepMinMs: 0,
sleepMaxMs: 0,
});
const selectQuery = captures.queries.find(query => /^SELECT/.test(query.sql));
assert.match(selectQuery.sql, /INTERVAL 60 DAY/);
});
it('sleepMaxMs < sleepMinMs 时钳制为 sleepMinMs', async () => {
const { service } = createHarness(sequenceQueryHandler([{ id: 9 }], [ 1, 0 ]));
const { sleepDelays } = await runWithStubbedTimers(
() => service.cleanupExpiredSystemLogs({ sleepMinMs: 150, sleepMaxMs: 50 })
);
assert.equal(sleepDelays.length, 1);
assert.equal(sleepDelays[0], 150);
});
});
describe('硬删除语义(静态检查)', () => {
it('必须走 ctx.model.query 原生 DELETE,禁止 SystemLog.destroy 软删除', () => {
const source = fs.readFileSync(SERVICE_SOURCE_PATH, 'utf8');
assert.match(source, /DELETE FROM \$\{SYSTEM_LOG_TABLE\}/);
assert.doesNotMatch(source, /\.destroy\s*\(/);
});
});
});