WMS_MAIN/app/service/systems/wave_batch_closure.js
liufumingren df641257cc fix(wave): 波次闭环判空二次确认,避免瞬时空表误终结波次
- wave_batch_closure.js 新增判空二次确认:同一波次需连续两轮(间隔不小于
  confirmMinIntervalMs,默认 30s)都被判定为空才允许终结,确认状态写 Redis
  (TTL 1h);状态缓存不可用或读取异常时本轮不终结任何波次(宁可漏关、不可误关)
- 规避批量解波/订单迁移进行中造成的瞬时空表误判(2026-09-12 生产事故)
- closed_count 改为 UPDATE 实际影响行数,新增 empty_count / confirmed_count /
  pending_confirm_count 等统计与日志(波次列表超长截断)
- sync_finished_wave_batch.js 调度日志同步输出 empty_count / pending_confirm_count
- systemMethods/order/wave.js 解波 UPDATE 增加 wave_status < 3 守卫,避免覆盖
  自动终结(5)及已进入拣货及后续环节的波次状态
2026-09-15 16:18:58 +08:00

361 lines
14 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.

// 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;
// 判空二次确认:同一波次需连续两轮(间隔不小于该毫秒数)都判定为空,才允许终结。
// 用于规避"批量解波/订单迁移进行中"造成的瞬时空表误判(2026-09-12 生产事故)。
const EMPTY_CONFIRM_MIN_INTERVAL_MS = 30 * 1000;
// 判空二次确认状态缓存键(记录上一轮判空结果与首次判定时间)
const EMPTY_CONFIRM_CACHE_KEY = 'schedule:sync_finished_wave_batch:empty_confirm';
// 判空二次确认状态缓存 TTL(秒)
const EMPTY_CONFIRM_CACHE_TTL_SECONDS = 3600;
// 判空二次确认状态最多保留的波次数量(防御性上限)
const EMPTY_CONFIRM_MAX_WAVE_COUNT = 10000;
// 日志中最多打印的波次数量(避免日志爆量)
const LOG_WAVE_ID_LIMIT = 200;
/**
* 提取 UPDATE 语句实际影响行数。
*
* @param {*} updateResult Sequelize query 返回值(UPDATE 通常为 [undefined, metadata])。
* @return {number} 影响行数,无法识别时返回 0。
*/
function extractAffectedRows(updateResult) {
const metadata = Array.isArray(updateResult) ? updateResult[1] : updateResult;
const rawCount = metadata
&& (metadata.affectedRows !== undefined
? metadata.affectedRows
: metadata.affectedCount !== undefined
? metadata.affectedCount
: metadata.rowCount);
const count = Number(rawCount);
return Number.isFinite(count) && count > 0 ? count : 0;
}
/**
* 格式化波次ID列表用于日志输出(超长时截断)。
*
* @param {Array<number>} waveIds 波次ID列表。
* @return {string} 日志用字符串。
*/
function formatWaveIdListForLog(waveIds) {
const list = Array.isArray(waveIds) ? waveIds : [];
if (list.length <= LOG_WAVE_ID_LIMIT) {
return list.join(',');
}
return `${list.slice(0, LOG_WAVE_ID_LIMIT).join(',')},...(共${list.length}个)`;
}
/**
* 波次批次自动终结服务。
*
* 背景:波次内订单全部离开待处理表后(发货迁移配送表、库内拦截确认、取消等),
* 若相关路径未回写 wms_wave_batch,波次会停留在 wave_status IN (0,1),
* 导致 order.wave.batchList 展示 0 单波次。
*
* 本服务按仓库扫描活动波次,对"待处理表中已无任何订单"的波次,
* 将 wave_status 收敛为 5(复核完成),使其从批次列表中消失。
*/
class WaveBatchClosureService extends MainService {
/**
* 扫描并关闭"订单已全部离表"的活动波次。
*
* 判空需通过"二次确认":同一波次连续两轮(间隔不小于 confirmMinIntervalMs)
* 都被判定为空才允许终结。这样即使某一瞬间待处理表查不到该波次订单
* (批量解波、出库迁移、外部 DDL 等并发场景),也不会被误判为 0 单波次。
*
* @param {Object} [options={}] 执行选项。
* @param {boolean} [options.dryRun=false] 仅盘点不更新(用于验证命中范围)。
* @param {number} [options.confirmMinIntervalMs] 判空二次确认最小间隔(毫秒),传 0 表示跳过确认、首轮即终结。
* @return {Promise<Object>} 执行结果汇总。
*/
async closeFinishedWaves(options = {}) {
const { ctx } = this;
const startedAt = Date.now();
const normalizedOptions = this.isPlainObject(options) ? options : {};
const dryRun = Boolean(normalizedOptions.dryRun);
const confirmMinIntervalMs = this.normalizeConfirmIntervalMs(normalizedOptions.confirmMinIntervalMs);
const confirmEnabled = !dryRun && confirmMinIntervalMs > 0;
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 emptyWaves = [];
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) {
emptyWaves.push(...finishedWaves);
}
}
const candidateCount = Array.from(warehouseWaveMap.values()).reduce((sum, waves) => sum + waves.length, 0);
// 二次确认:只有"上一轮也判空"且距首次判空已满 confirmMinIntervalMs 的波次才允许终结
const now = Date.now();
const previousState = confirmEnabled ? await this.readEmptyConfirmState() : null;
const previousWaveIds = Array.isArray(previousState && previousState.waveIds)
? previousState.waveIds
: [];
const previousWaveIdSet = new Set(previousWaveIds);
const previousRoundAt = Number(previousState && previousState.roundAt || 0);
const previousStateUsable = Number.isFinite(previousRoundAt)
&& previousRoundAt > 0
&& (now - previousRoundAt) >= confirmMinIntervalMs;
const confirmedWaves = [];
const pendingConfirmWaves = [];
for (const item of emptyWaves) {
if (!confirmEnabled || (previousStateUsable && previousWaveIdSet.has(item.waveId))) {
confirmedWaves.push(item);
} else {
pendingConfirmWaves.push(item);
}
}
if (confirmEnabled) {
// 状态仍在确认窗口内时保留首次判定时间,避免调度频率高于确认间隔时永远无法确认
const nextRoundAt = previousRoundAt > 0 && !previousStateUsable ? previousRoundAt : now;
await this.writeEmptyConfirmState({
roundAt: nextRoundAt,
waveIds: emptyWaves.map(item => item.waveId),
});
}
const confirmedWaveIds = confirmedWaves.map(item => item.waveId);
let closedRowCount = 0;
if (!dryRun && confirmedWaveIds.length > 0) {
for (let offset = 0; offset < confirmedWaveIds.length; offset += WAVE_ID_BATCH_SIZE) {
const batchWaveIds = confirmedWaveIds.slice(offset, offset + WAVE_ID_BATCH_SIZE);
const updateResult = 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,
}
);
closedRowCount += extractAffectedRows(updateResult);
}
}
const result = {
dryRun,
confirm_min_interval_ms: confirmMinIntervalMs,
candidate_count: candidateCount,
empty_count: emptyWaves.length,
confirmed_count: confirmedWaves.length,
closed_count: dryRun ? 0 : closedRowCount,
pending_confirm_count: pendingConfirmWaves.length,
pending_confirm_wave_ids: pendingConfirmWaves.map(item => item.waveId),
empty_wave_ids: emptyWaves.map(item => item.waveId),
warehouse_ids: warehouseIds,
closed_waves: confirmedWaves,
duration_ms: Date.now() - startedAt,
};
if (confirmedWaves.length > 0 || pendingConfirmWaves.length > 0) {
const pendingSuffix = pendingConfirmWaves.length > 0
? ` pendingWaves=${formatWaveIdListForLog(result.pending_confirm_wave_ids)}`
: '';
const confirmedSuffix = confirmedWaveIds.length > 0
? ` waves=${formatWaveIdListForLog(confirmedWaveIds)}`
: '';
ctx.logger.info(
`[wave-batch-closure] 波次终结结果 dryRun=${dryRun} candidate=${candidateCount}`
+ ` confirmed=${confirmedWaves.length} closedRows=${result.closed_count}`
+ ` pendingConfirm=${pendingConfirmWaves.length}${pendingSuffix}${confirmedSuffix}`
);
}
return result;
}
/**
* 归一化判空二次确认最小间隔。
*
* @param {*} rawValue 原始入参。
* @return {number} 毫秒数;未传/非法/负数时回落默认值,0 表示跳过确认。
*/
normalizeConfirmIntervalMs(rawValue) {
if (rawValue === undefined || rawValue === null || rawValue === '') {
return EMPTY_CONFIRM_MIN_INTERVAL_MS;
}
const numberValue = Number(rawValue);
if (!Number.isFinite(numberValue) || numberValue < 0) {
return EMPTY_CONFIRM_MIN_INTERVAL_MS;
}
return Math.floor(numberValue);
}
/**
* 读取上一轮判空二次确认状态。
*
* 缓存不可用或读取异常时返回 null,调用方据此跳过本轮终结(宁可漏关,不可误关)。
*
* @return {Promise<{ roundAt: number, waveIds: Array<number> }|null>} 上一轮状态。
*/
async readEmptyConfirmState() {
const { ctx } = this;
const app = ctx && ctx.app;
if (!app || typeof app.getCacheAsync !== 'function') {
ctx.logger.warn('[wave-batch-closure] 判空二次确认状态缓存不可用,本轮不终结任何波次');
return null;
}
try {
const cached = await app.getCacheAsync(EMPTY_CONFIRM_CACHE_KEY);
if (cached === undefined || cached === null) {
return null;
}
const state = typeof cached === 'string' ? JSON.parse(cached) : cached;
if (!state || typeof state !== 'object') {
return null;
}
return {
roundAt: Number(state.roundAt || 0),
waveIds: Array.isArray(state.waveIds)
? state.waveIds.map(waveId => Number(waveId)).filter(waveId => Number.isInteger(waveId) && waveId > 0)
: [],
};
} catch (error) {
ctx.logger.warn(`[wave-batch-closure] 读取判空二次确认状态失败,本轮不终结任何波次: ${error.message}`);
return null;
}
}
/**
* 写入本轮判空二次确认状态(供下一轮确认)。
*
* @param {{ roundAt: number, waveIds: Array<number> }} state 状态。
* @return {Promise<void>} 无返回值。
*/
async writeEmptyConfirmState(state) {
const { ctx } = this;
const app = ctx && ctx.app;
if (!app || typeof app.setCacheAsync !== 'function') {
return;
}
try {
const waveIds = Array.isArray(state && state.waveIds)
? state.waveIds.slice(0, EMPTY_CONFIRM_MAX_WAVE_COUNT)
: [];
await app.setCacheAsync(
EMPTY_CONFIRM_CACHE_KEY,
{
roundAt: Number(state && state.roundAt || Date.now()),
waveIds,
},
EMPTY_CONFIRM_CACHE_TTL_SECONDS
);
} catch (error) {
ctx.logger.warn(`[wave-batch-closure] 写入判空二次确认状态失败: ${error.message}`);
}
}
}
module.exports = WaveBatchClosureService;