feat(wave): item_detail_machine 改 TEXT 并新增波次自动终结

- wms_wave_batch.item_detail_machine VARCHAR(1024) -> TEXT, 兼容多商品长结构标识
- 新增 wave_batch_closure 服务: 扫描活动波次(0/1)中订单已全部离开待处理表的波次并收敛 wave_status=5
- 新增 sync_finished_wave_batch 定时任务与执行日志缓存
This commit is contained in:
liufumingren 2026-08-21 02:20:17 +08:00
parent 60b4babb34
commit 90d5701a53
4 changed files with 415 additions and 4 deletions

View File

@ -2,7 +2,7 @@
'use strict';
module.exports = app => {
const { BIGINT, INTEGER, STRING, DATE, TINYINT, BOOLEAN } = app.Sequelize;
const { BIGINT, INTEGER, STRING, TEXT, DATE, TINYINT, BOOLEAN } = app.Sequelize;
const WaveBatch = app.model.define('wms_wave_batch', {
wave_id: {
@ -115,9 +115,9 @@ module.exports = app => {
comment: '更新时间',
},
item_detail_machine: {
type: STRING(1024),
type: TEXT,
allowNull: true,
comment: '抓取结构token:v1|item_part_type|item_part|distinguish_express|logistics_name|item_snapshot_key',
comment: '抓取结构token:v1|item_part_type|item_part|distinguish_express|logistics_name|item_snapshot_key(TEXT 以容纳多商品订单的长结构标识)',
},
item_part_type: {
type: STRING(32),
@ -143,7 +143,7 @@ module.exports = app => {
item_snapshot_key: {
type: STRING(1024),
allowNull: true,
comment: '结构快照键(与 item_detail_machine 一致,1024 长度以容纳多商品订单的快照)',
comment: '结构快照键(多商品订单的快照键,最长 1024)',
},
}, {
tableName: 'wms_wave_batch',

View File

@ -0,0 +1,118 @@
// app/schedule/sync_finished_wave_batch.js
'use strict';
const EXECUTION_LOG_CACHE_KEY = 'schedule:sync_finished_wave_batch:last_execution';
const EXECUTION_LOG_CACHE_TTL = 300; // 5 分钟
const EXECUTION_LOG_HISTORY_CACHE_KEY = 'schedule:sync_finished_wave_batch:history';
const EXECUTION_LOG_HISTORY_MAX = 20; // 保留最近 20 次执行记录
const EXECUTION_LOG_HISTORY_TTL = 86400; // 1 天
/**
* 将本次执行日志写入缓存。
*
* @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 (err) {
ctx.logger.warn(`[sync-finished-wave-batch] 写入执行日志缓存失败: ${err.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 (err) {
ctx.logger.warn(`[sync-finished-wave-batch] 写入执行历史缓存失败: ${err.message}`);
}
}
/**
* 每 1 分钟在单 worker 中执行一次波次自动终结。
*
* 将"订单已全部离开待处理表"的活动波次(wave_status IN (0,1))收敛为
* wave_status=5(复核完成),修复遗留 0 单波次在 batchList 中展示的问题。
*/
module.exports = {
schedule: {
interval: '1m',
type: 'worker',
immediate: false,
disable: false,
},
/**
* 执行波次自动终结任务。
*
* @param {Object} ctx Egg 上下文。
* @return {Promise<void>} 无返回值。
*/
async task(ctx) {
if (ctx.app._syncFinishedWaveBatchRunning) {
return;
}
ctx.app._syncFinishedWaveBatchRunning = true;
const startedAt = Date.now();
let status = 'success';
let errorMessage = '';
let result = null;
try {
result = await ctx.service.systems.waveBatchClosure.closeFinishedWaves();
if (result && result.closed_count > 0) {
ctx.logger.info(
`[sync-finished-wave-batch] 自动终结 ${result.closed_count} 个波次: ${JSON.stringify(result.closed_waves)}`
);
}
} catch (error) {
status = 'error';
errorMessage = error.message;
ctx.logger.error(`[sync-finished-wave-batch] 执行失败: ${error.message}`);
} finally {
ctx.app._syncFinishedWaveBatchRunning = false;
}
const logEntry = {
executed_at: new Date().toISOString(),
duration_ms: Date.now() - startedAt,
status,
error_message: errorMessage,
candidate_count: result ? result.candidate_count : 0,
closed_count: result ? result.closed_count : 0,
warehouse_ids: result ? result.warehouse_ids : [],
closed_waves: result ? result.closed_waves : [],
};
await writeExecutionLogToCache(ctx, logEntry);
await appendExecutionHistory(ctx, logEntry);
ctx.logger.info(
`[sync-finished-wave-batch] 本轮完成 closed=${result ? result.closed_count : 0} candidate=${result ? result.candidate_count : 0} warehouses=${result ? result.warehouse_ids.length : 0}`
);
},
};

View File

@ -0,0 +1,173 @@
// app/service/systems/wave_batch_closure.js
'use strict';
const MainService = require('../main');
// 活动中的波次状态(batchList 可见口径)
const ACTIVE_WAVE_STATUSES = [ 0, 1 ];
// 终结态:复核完成(与 recheckOrder 复核完成路径一致,使波次从 batchList 中自然消失)
const CLOSED_WAVE_STATUS = 5;
// 创建不足该分钟数的波次不参与自动终结,避免与创建事务并发误判
const WAVE_MIN_AGE_MINUTES = 5;
// 单次 SQL IN 列表的波次数量上限
const WAVE_ID_BATCH_SIZE = 500;
/**
* 波次批次自动终结服务。
*
* 背景:波次内订单全部离开待处理表后(发货迁移配送表、库内拦截确认、取消等),
* 若相关路径未回写 wms_wave_batch,波次会停留在 wave_status IN (0,1),
* 导致 order.wave.batchList 展示 0 单波次。
*
* 本服务按仓库扫描活动波次,对"待处理表中已无任何订单"的波次,
* 将 wave_status 收敛为 5(复核完成),使其从批次列表中消失。
*/
class WaveBatchClosureService extends MainService {
/**
* 扫描并关闭"订单已全部离表"的活动波次。
*
* @param {Object} [options={}] 执行选项。
* @param {boolean} [options.dryRun=false] 仅盘点不更新(用于验证命中范围)。
* @return {Promise<Object>} 执行结果汇总。
*/
async closeFinishedWaves(options = {}) {
const { ctx } = this;
const startedAt = Date.now();
const dryRun = Boolean(options && options.dryRun);
const candidateRows = await ctx.model.query(
`SELECT wave_id, wave_no, warehouse_id, wave_status, total_orders
FROM wms_wave_batch
WHERE wave_status IN (:waveStatuses)
AND total_orders > 0
AND create_time < (NOW() - INTERVAL ${WAVE_MIN_AGE_MINUTES} MINUTE)`,
{
replacements: { waveStatuses: ACTIVE_WAVE_STATUSES },
type: ctx.model.QueryTypes.SELECT,
}
);
// 按仓库分组,过滤非法数据
const warehouseWaveMap = new Map();
for (const row of (Array.isArray(candidateRows) ? candidateRows : [])) {
const warehouseId = Number(row && row.warehouse_id || 0);
const waveId = Number(row && row.wave_id || 0);
if (!Number.isInteger(warehouseId) || warehouseId <= 0
|| !Number.isInteger(waveId) || waveId <= 0) {
continue;
}
if (!warehouseWaveMap.has(warehouseId)) {
warehouseWaveMap.set(warehouseId, []);
}
warehouseWaveMap.get(warehouseId).push({
waveId,
waveNo: String(row && row.wave_no || '').trim(),
warehouseId,
});
}
const warehouseIds = Array.from(warehouseWaveMap.keys());
const closedWaves = [];
for (const warehouseId of warehouseIds) {
const waves = warehouseWaveMap.get(warehouseId);
let currentTableName = '';
try {
const factory = ctx.model && ctx.model.OrderDeliveryFactory;
if (!factory || typeof factory.generateTableName !== 'function') {
throw new Error('订单工厂不可用');
}
currentTableName = factory.generateTableName(warehouseId, 'current');
} catch (error) {
ctx.logger.warn(`[wave-batch-closure] 生成仓库 ${warehouseId} 订单表名失败,跳过: ${error.message}`);
continue;
}
// 分批查询待处理表中仍存在订单的波次
const existingWaveIds = new Set();
let warehouseQueryFailed = false;
for (let offset = 0; offset < waves.length; offset += WAVE_ID_BATCH_SIZE) {
const batchWaves = waves.slice(offset, offset + WAVE_ID_BATCH_SIZE);
const batchWaveIds = batchWaves.map(item => item.waveId);
try {
const existingRows = await ctx.model.query(
`SELECT DISTINCT wave_id
FROM ${currentTableName}
WHERE wave_id IN (:waveIds)`,
{
replacements: { waveIds: batchWaveIds },
type: ctx.model.QueryTypes.SELECT,
}
);
for (const row of (Array.isArray(existingRows) ? existingRows : [])) {
const waveId = Number(row && row.wave_id || 0);
if (Number.isInteger(waveId) && waveId > 0) {
existingWaveIds.add(waveId);
}
}
} catch (error) {
warehouseQueryFailed = true;
ctx.logger.warn(`[wave-batch-closure] 查询仓库 ${warehouseId} 待处理表失败,跳过该仓库: ${error.message}`);
break;
}
}
if (warehouseQueryFailed) {
continue;
}
const finishedWaves = waves.filter(item => !existingWaveIds.has(item.waveId));
if (finishedWaves.length > 0) {
closedWaves.push(...finishedWaves);
}
}
const closedWaveIds = closedWaves.map(item => item.waveId);
const candidateCount = Array.from(warehouseWaveMap.values()).reduce((sum, waves) => sum + waves.length, 0);
if (!dryRun && closedWaveIds.length > 0) {
for (let offset = 0; offset < closedWaveIds.length; offset += WAVE_ID_BATCH_SIZE) {
const batchWaveIds = closedWaveIds.slice(offset, offset + WAVE_ID_BATCH_SIZE);
await ctx.model.query(
`UPDATE wms_wave_batch
SET wave_status = :closedStatus,
processed_orders = total_orders,
check_time = NOW(),
update_time = NOW()
WHERE wave_id IN (:waveIds)
AND wave_status IN (:waveStatuses)
AND total_orders > 0`,
{
replacements: {
closedStatus: CLOSED_WAVE_STATUS,
waveIds: batchWaveIds,
waveStatuses: ACTIVE_WAVE_STATUSES,
},
type: ctx.model.QueryTypes.UPDATE,
}
);
}
}
const result = {
dryRun,
candidate_count: candidateCount,
closed_count: closedWaves.length,
warehouse_ids: warehouseIds,
closed_waves: closedWaves,
duration_ms: Date.now() - startedAt,
};
if (closedWaves.length > 0) {
ctx.logger.info(
`[wave-batch-closure] 波次终结结果 dryRun=${dryRun} closed=${closedWaves.length}/${candidateCount} waves=${closedWaveIds.join(',')}`
);
}
return result;
}
}
module.exports = WaveBatchClosureService;

View File

@ -0,0 +1,120 @@
'use strict';
/**
* 将 wms_wave_batch.item_detail_machine 列从 VARCHAR(1024) 改为 TEXT。
*
* 背景:
* buildMachineStructureToken 生成的结构标识为
* `v1|item_part_type|item_part|distinguish_express|logistics_name|item_snapshot_key`,
* 其中 item_part 与 item_snapshot_key 均经 encodeURIComponent 编码,
* 多商品订单下编码后的长度可能远超 1024,抓取分组 INSERT 时报
* "Data too long for column 'item_detail_machine' at row 1"。
*
* 变更:
* 1. wms_wave_batch.item_detail_machine: VARCHAR(1024) → TEXT
* 2. 索引 idx_wave_item_machine_prefix 维持前缀索引
* (item_detail_machine(191)),TEXT 列前缀索引仍合法;
* 若存量环境存在全列索引则先删除。
* 3. 模型定义同步改为 TEXT(app/model/wave_batch.js)。
*/
const TABLE_NAME = 'wms_wave_batch';
const COLUMN_NAME = 'item_detail_machine';
const INDEX_NAME = 'idx_wave_item_machine_prefix';
async function hasColumn(queryInterface, tableName, columnName) {
const [ columns ] = await queryInterface.sequelize.query(
`
SELECT COLUMN_NAME
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = :tableName
AND COLUMN_NAME = :columnName
`,
{ replacements: { tableName, columnName } }
);
return (Array.isArray(columns) ? columns : []).length > 0;
}
async function listColumnIndexes(queryInterface, tableName, columnName) {
const [ rows ] = await queryInterface.sequelize.query(
`
SELECT DISTINCT INDEX_NAME, SUB_PART
FROM INFORMATION_SCHEMA.STATISTICS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = :tableName
AND COLUMN_NAME = :columnName
`,
{ replacements: { tableName, columnName } }
);
return Array.isArray(rows) ? rows : [];
}
module.exports = {
up: async queryInterface => {
if (!(await hasColumn(queryInterface, TABLE_NAME, COLUMN_NAME))) {
console.log(`[migrate] ${TABLE_NAME}.${COLUMN_NAME} 列不存在,跳过`);
return;
}
// ── 1. 全列索引对 TEXT 无效(无前缀),先删除存量全列索引 ──
const existingIndexes = await listColumnIndexes(queryInterface, TABLE_NAME, COLUMN_NAME);
for (const idx of existingIndexes) {
const indexName = String(idx.INDEX_NAME || '').trim();
const subPart = idx.SUB_PART === null || idx.SUB_PART === undefined
? null
: Number(idx.SUB_PART);
if (!indexName || subPart) {
continue;
}
try {
await queryInterface.removeIndex(TABLE_NAME, indexName);
console.log(`[migrate] 已移除全列索引 ${indexName}(TEXT 列要求前缀索引)`);
} catch (e) {
const msg = String(e && e.message || '');
if (!msg.includes('check that it exists') && !msg.includes('exist')) {
console.warn(`[migrate] 移除全列索引 ${indexName} 时出现非预期错误: ${msg}`);
}
}
}
// ── 2. 修改列类型为 TEXT ──
await queryInterface.sequelize.query(
`ALTER TABLE \`${TABLE_NAME}\` MODIFY \`${COLUMN_NAME}\` TEXT NULL COMMENT '抓取结构token:v1|item_part_type|item_part|distinguish_express|logistics_name|item_snapshot_key'`
);
console.log(`[migrate] ${TABLE_NAME}.${COLUMN_NAME} VARCHAR(1024) → TEXT`);
// ── 3. 确保前缀索引存在 ──
const remainingIndexes = await listColumnIndexes(queryInterface, TABLE_NAME, COLUMN_NAME);
if (remainingIndexes.length === 0) {
try {
await queryInterface.sequelize.query(
`ALTER TABLE \`${TABLE_NAME}\` ADD INDEX \`${INDEX_NAME}\` (\`${COLUMN_NAME}\`(191))`
);
console.log(`[migrate] 已创建前缀索引 ${INDEX_NAME}(${COLUMN_NAME}(191))`);
} catch (e) {
const msg = String(e && e.message || '');
if (!msg.includes('Duplicate')) {
throw e;
}
console.log(`[migrate] 前缀索引 ${INDEX_NAME} 已存在,跳过`);
}
}
},
down: async queryInterface => {
if (!(await hasColumn(queryInterface, TABLE_NAME, COLUMN_NAME))) {
console.log(`[migrate:down] ${TABLE_NAME}.${COLUMN_NAME} 列不存在,跳过`);
return;
}
// 注意:若已有数据超过 1024 字符,回滚会失败,需先人工截断数据
await queryInterface.sequelize.query(
`ALTER TABLE \`${TABLE_NAME}\` MODIFY \`${COLUMN_NAME}\` VARCHAR(1024) NULL COMMENT '抓取结构token:v1|item_part_type|item_part|distinguish_express|logistics_name|item_snapshot_key'`
);
console.log(`[migrate:down] ${TABLE_NAME}.${COLUMN_NAME} TEXT → VARCHAR(1024)`);
},
};