feat(pack): 打包任务最大时长约束与自动结束

- 仓库设置新增 single_order_pack_max_minutes(默认3)/group_order_pack_max_minutes(默认40) 配置
- 新增每小时定时任务扫描未结束打包任务,超时自动结束(end=start+上限)
- 结束时间统一截断为开始时间+上限时长(finishPack/新任务顶替/setEndTime 接口)
This commit is contained in:
liufumingren 2026-08-15 23:12:51 +08:00
parent f127853592
commit e5196dc1ea
9 changed files with 374 additions and 7 deletions

View File

@ -59,6 +59,8 @@ module.exports = app => {
receiver_address: '',
group_wave_prefix: 'B',
delete_order_wave_prefix: 'A',
single_order_pack_max_minutes: 3,
group_order_pack_max_minutes: 40,
inventory_warning_rules: DEFAULT_INVENTORY_WARNING_RULES,
auto_outbound_rules: DEFAULT_AUTO_OUTBOUND_RULES,
cutoff_order_enabled: 1,
@ -242,6 +244,28 @@ module.exports = app => {
normalized.min_group_order_fetch_quantity = minGroupOrderFetchQuantity;
}
const rawSingleOrderPackMaxMinutes = parsed.single_order_pack_max_minutes;
if (rawSingleOrderPackMaxMinutes === undefined || rawSingleOrderPackMaxMinutes === null || rawSingleOrderPackMaxMinutes === '') {
normalized.single_order_pack_max_minutes = DEFAULT_SUBJECT_CONFIG.single_order_pack_max_minutes;
} else {
const singleOrderPackMaxMinutes = Number(rawSingleOrderPackMaxMinutes);
if (!Number.isInteger(singleOrderPackMaxMinutes) || singleOrderPackMaxMinutes <= 0) {
throw new Error('subject_config.single_order_pack_max_minutes 必须是大于 0 的整数');
}
normalized.single_order_pack_max_minutes = singleOrderPackMaxMinutes;
}
const rawGroupOrderPackMaxMinutes = parsed.group_order_pack_max_minutes;
if (rawGroupOrderPackMaxMinutes === undefined || rawGroupOrderPackMaxMinutes === null || rawGroupOrderPackMaxMinutes === '') {
normalized.group_order_pack_max_minutes = DEFAULT_SUBJECT_CONFIG.group_order_pack_max_minutes;
} else {
const groupOrderPackMaxMinutes = Number(rawGroupOrderPackMaxMinutes);
if (!Number.isInteger(groupOrderPackMaxMinutes) || groupOrderPackMaxMinutes <= 0) {
throw new Error('subject_config.group_order_pack_max_minutes 必须是大于 0 的整数');
}
normalized.group_order_pack_max_minutes = groupOrderPackMaxMinutes;
}
const rawExcludeRemarks = parsed.auto_allocate_express_exclude_remarks;
if (rawExcludeRemarks === undefined || rawExcludeRemarks === null || rawExcludeRemarks === '') {
normalized.auto_allocate_express_exclude_remarks = [];

View File

@ -0,0 +1,48 @@
'use strict';
/**
* 打包任务自动结束定时任务。
* 每小时在单 worker 中扫描一次 wms_pack_task 表:
* - 扫描所有未结束的任务(status < 2),区分散单(pack_mode=1)/ 团购(pack_mode=2);
* - 按仓库拉取 subject_config 中配置的打包最大时长
* (散单 single_order_pack_max_minutes / 团购 group_order_pack_max_minutes,单位分钟);
* - 当 当前时间 - 开始时间 > 配置时长 时自动结束,
* 将 end_time 置为 开始时间 + 上限时长,状态置为已完成(2)。
*/
module.exports = {
schedule: {
interval: '1h',
type: 'worker',
immediate: false,
disable: false,
},
/**
* 执行打包任务自动结束任务。
*
* @param {Object} ctx Egg 上下文。
* @return {Promise<void>} 无返回值。
*/
async task(ctx) {
if (ctx.app._autoFinishPackTaskRunning) {
return;
}
ctx.app._autoFinishPackTaskRunning = true;
try {
const result = await ctx.service.systems.packTaskAutoFinish.executeAutoFinishPackTasks();
ctx.logger.info(
'[auto-finish-pack-task] 本轮扫描 %d 条未结束打包任务(涉及 %d 个仓库),自动结束 %d 条',
result && result.total_scanned || 0,
result && result.warehouse_count || 0,
result && result.auto_finished || 0
);
} catch (error) {
ctx.logger.error(`[auto-finish-pack-task] 打包任务自动结束执行失败: ${error.message}`);
} finally {
ctx.app._autoFinishPackTaskRunning = false;
}
},
};

View File

@ -62,6 +62,7 @@ class OrderPackingMethodService extends MainService {
* 设置打包任务结束时间(仓库侧 system method 包装层)。
* 若任务状态不是已完成,则同步更新状态为已完成。
* 前端默认值逻辑:已有结束时间→当前时间;无结束时间→开始时间+5分钟。
* 结束时间超过仓库配置的打包最大时长上限时,自动截断为上限时间。
*
* @param {Object} data 请求体
* @param {number} data.id 打包任务ID

View File

@ -510,6 +510,8 @@ class OrderPackingService extends Service {
* 设置打包任务结束时间。
* 按 id + warehouse_id 查找任务,更新结束时间。
* 若任务状态不是已完成(2),则同时将状态更新为已完成。
* 结束时间超过仓库配置的打包最大时长上限时,自动截断为 开始时间+上限时长
* (散单 single_order_pack_max_minutes / 团购 group_order_pack_max_minutes,单位分钟)。
*
* @param {Object} options 操作参数
* @param {number} options.id 打包任务ID
@ -547,7 +549,13 @@ class OrderPackingService extends Service {
return { code: 400, message: '结束时间不能早于开始时间', data: null };
}
const updates = { end_time: newEndTime };
// 结束时间超过仓库配置的打包最大时长上限时,截断为 开始时间+上限时长
const workbenchService = ctx.service.systems && ctx.service.systems.workbench;
const finalEndTime = workbenchService && typeof workbenchService.resolvePackTaskEndTime === 'function'
? await workbenchService.resolvePackTaskEndTime(record, newEndTime)
: newEndTime;
const updates = { end_time: finalEndTime };
// 若任务状态不是已完成(2),同步更新为已完成
if (record.status !== 2) {

View File

@ -0,0 +1,120 @@
'use strict';
const MainService = require('../main');
const { Op } = require('sequelize');
const PACK_MODE_GROUP = 2;
const PACK_TASK_FINISHED_STATUS = 2;
const MINUTE_MS = 60 * 1000;
/**
* 打包任务自动结束服务。
* 扫描 wms_pack_task 未结束任务,按仓库配置的打包最大时长
* (散单 single_order_pack_max_minutes / 团购 group_order_pack_max_minutes,单位分钟)
* 判断是否超时,超时则将结束时间置为开始时间 + 上限时长并标记已完成。
*/
class PackTaskAutoFinishService extends MainService {
/**
* 执行打包任务自动结束扫描。
*
* @return {Promise<Object>} 处理统计 { total_scanned, warehouse_count, auto_finished }。
*/
async executeAutoFinishPackTasks() {
const { ctx, app } = this;
const { PackTask } = app.model || {};
if (!PackTask || typeof PackTask.findAll !== 'function') {
return { total_scanned: 0, warehouse_count: 0, auto_finished: 0 };
}
const nowMs = Date.now();
// 1. 扫描所有未结束的打包任务(status < 2,即待处理/打包中),且已有开始时间
const tasks = await PackTask.findAll({
where: {
status: { [Op.lt]: PACK_TASK_FINISHED_STATUS },
start_time: { [Op.ne]: null },
},
attributes: [ 'id', 'warehouse_id', 'pack_mode', 'start_time' ],
});
if (tasks.length === 0) {
return { total_scanned: 0, warehouse_count: 0, auto_finished: 0 };
}
// 2. 按仓库去重后拉取各仓库配置(缓存优先,模型规范化会补齐默认值)
const warehouseIds = [ ...new Set(
tasks
.map(task => Number(task.warehouse_id || 0))
.filter(warehouseId => Number.isInteger(warehouseId) && warehouseId > 0)
) ];
const configMap = new Map();
for (const warehouseId of warehouseIds) {
try {
const subjectConfig = await ctx.service.systems.deliveryOrder.getStoreSubjectConfig(warehouseId);
configMap.set(warehouseId, subjectConfig && typeof subjectConfig === 'object' ? subjectConfig : {});
} catch (error) {
ctx.logger.warn('[packTaskAutoFinish] 读取仓库 %d 配置失败: %s', warehouseId, error.message);
configMap.set(warehouseId, {});
}
}
// 3. 逐条判断超时并自动结束
let autoFinished = 0;
for (const task of tasks) {
const warehouseId = Number(task.warehouse_id || 0);
const config = configMap.get(warehouseId) || {};
const isGroup = Number(task.pack_mode) === PACK_MODE_GROUP;
const limitMinutes = Number(
isGroup ? config.group_order_pack_max_minutes : config.single_order_pack_max_minutes
);
// 未配置有效时长(或非法值)的仓库跳过,不做自动结束
if (!Number.isInteger(limitMinutes) || limitMinutes <= 0) {
continue;
}
const startMs = new Date(task.start_time).getTime();
if (!Number.isFinite(startMs)) {
continue;
}
const limitMs = limitMinutes * MINUTE_MS;
// 仅当 当前时间 - 开始时间 > 上限时长 时自动结束
if (nowMs - startMs <= limitMs) {
continue;
}
// 结束时间 = 开始时间 + 上限时长
const endTime = new Date(startMs + limitMs);
await task.update({
end_time: endTime,
status: PACK_TASK_FINISHED_STATUS,
});
autoFinished += 1;
ctx.logger.info(
'[packTaskAutoFinish] 自动结束超时打包任务 taskId=%d warehouseId=%d packMode=%s limitMinutes=%d start=%s end=%s',
task.id,
warehouseId,
isGroup ? 'group' : 'single',
limitMinutes,
new Date(startMs).toISOString(),
endTime.toISOString()
);
}
return {
total_scanned: tasks.length,
warehouse_count: warehouseIds.length,
auto_finished: autoFinished,
};
}
}
module.exports = PackTaskAutoFinishService;

View File

@ -294,6 +294,24 @@ const WAREHOUSE_SETTING_FIELDS = Object.freeze([
stockout: Object.freeze({ _default: 24, return_issue: 48, shortage: 48 }),
}),
}),
Object.freeze({
key: 'single_order_pack_max_minutes',
name: '散单打包最大时长(分钟)',
type: 'integer',
default: 3,
required: false,
description: '散单打包最大时长,单位:分钟,默认 3',
min: 1,
}),
Object.freeze({
key: 'group_order_pack_max_minutes',
name: '团购打包最大时长(分钟)',
type: 'integer',
default: 40,
required: false,
description: '团购打包最大时长,单位:分钟,默认 40',
min: 1,
}),
Object.freeze({
key: INTERNAL_WAVE_STRATEGY_VERSION_KEY,
name: '仓库波次策略版本号',

View File

@ -521,7 +521,8 @@ class WorkbenchService extends Service {
},
});
if (previousTask) {
await previousTask.update({ end_time: new Date(packTimeMs), status: 2 });
const previousEndTime = await this.resolvePackTaskEndTime(previousTask, new Date(packTimeMs));
await previousTask.update({ end_time: previousEndTime, status: 2 });
ctx.logger.info('[Workbench._packOrder] 关闭上一个未结束任务 taskId=%d orderId=%d workbenchId=%d',
previousTask.id, previousTask.order_id, validWorkbenchId);
}
@ -736,6 +737,63 @@ class WorkbenchService extends Service {
return result;
}
/**
* 按仓库配置的打包最大时长约束任务结束时间。
* 候选结束时间超过 开始时间+上限时长 时,截断为上限时间点。
* 未配置有效时长或开始时间非法时不做约束,原样返回。
*
* @param {Object} packTask 打包任务实例(需含 warehouse_id / pack_mode / start_time)
* @param {Date|string} endTime 候选结束时间
* @return {Promise<Date>} 约束后的结束时间
*/
async resolvePackTaskEndTime(packTask, endTime) {
const { ctx } = this;
const candidate = endTime instanceof Date ? endTime : new Date(endTime);
if (!packTask || !Number.isFinite(candidate.getTime())) {
return endTime;
}
const startMs = new Date(packTask.start_time).getTime();
if (!Number.isFinite(startMs)) {
return endTime;
}
const isGroup = Number(packTask.pack_mode) === 2;
let limitMinutes = null;
try {
const warehouseId = Number(packTask.warehouse_id || 0);
const subjectConfig = await ctx.service.systems.deliveryOrder.getStoreSubjectConfig(warehouseId);
const rawMinutes = isGroup
? subjectConfig.group_order_pack_max_minutes
: subjectConfig.single_order_pack_max_minutes;
limitMinutes = Number(rawMinutes);
} catch (error) {
ctx.logger.warn('[Workbench.resolvePackTaskEndTime] 读取仓库配置失败: %s', error.message);
}
// 未配置有效时长时不约束结束时间
if (!Number.isInteger(limitMinutes) || limitMinutes <= 0) {
return endTime;
}
const maxEndMs = startMs + limitMinutes * 60 * 1000;
if (candidate.getTime() > maxEndMs) {
const cappedEndTime = new Date(maxEndMs);
ctx.logger.info(
'[Workbench.resolvePackTaskEndTime] 结束时间超过打包上限,截断为上限时间 taskId=%d packMode=%s limitMinutes=%d end=%s',
packTask.id,
isGroup ? 'group' : 'single',
limitMinutes,
cappedEndTime.toISOString()
);
return cappedEndTime;
}
return endTime;
}
/**
* 工作台打包完成:传入工作台ID,查找最后一个未结束的打包任务并结束
* @param {Object} params - { workbench_id, warehouse_id }
@ -773,7 +831,8 @@ class WorkbenchService extends Service {
}
const now = new Date();
await lastTask.update({ end_time: now, status: 2 });
const endTime = await this.resolvePackTaskEndTime(lastTask, now);
await lastTask.update({ end_time: endTime, status: 2 });
ctx.logger.info('[Workbench._finishPack] 工作台 %d 结束打包任务 taskId=%d orderId=%d',
validWorkbenchId, lastTask.id, lastTask.order_id);
@ -783,7 +842,7 @@ class WorkbenchService extends Service {
finished: true,
task_id: lastTask.id,
order_id: lastTask.order_id,
end_time: now,
end_time: endTime,
};
}

View File

@ -1,4 +1,67 @@
[
{
"version": "2026.08.15-packing-setEndTime-cap",
"date": "2026-08-15",
"type": "enhanced",
"summary": "order.packing.setEndTime 增加结束时间上限约束:传入结束时间超过仓库配置的打包最大时长上限(散单 single_order_pack_max_minutes / 团购 group_order_pack_max_minutes)时,自动截断为 开始时间+上限时长 后落库",
"methods": [
"order.packing.setEndTime"
],
"notes": [
"app/service/systems/order_packing.js setEndTime:结束时间不能早于开始时间校验之后,复用 workbench.resolvePackTaskEndTime 做上限截断(按 pack_mode 区分散单/团购配置,未配置有效时长时不约束)",
"截断使用最终值落库与响应(end_time/status 同步返回截断后的时间)",
"与 workbench.finishPack / packOrder 关闭旧任务 / 定时任务自动结束 的 end_time 上限语义对齐",
"同步更新 methods/system.json 中 order.packing.setEndTime 的 description、end_time 参数与响应说明"
],
"module": "order.packing"
},
{
"version": "2026.08.15-pack-task-end-time-cap",
"date": "2026-08-15",
"type": "enhanced",
"summary": "打包任务结束时间增加上限约束:工作台结束任务时(finishPack 手动结束、packOrder 关闭上一个未结束任务),若结束时间超过仓库配置的打包最大时长上限(散单 single_order_pack_max_minutes / 团购 group_order_pack_max_minutes),自动截断为 开始时间+上限时长",
"methods": [],
"notes": [
"app/service/systems/workbench.js 新增 resolvePackTaskEndTime:按 warehouse_id+pack_mode 读取配置上限分钟,候选结束时间超过 开始时间+上限 时返回上限时间点,未配置有效时长或 start_time 非法时不约束",
"_packOrder 步骤4 关闭上一个未结束任务、_finishPack 手动结束 两处结束路径统一接入约束,_finishPack 响应 end_time 同步返回约束后的时间",
"与定时任务 auto_finish_pack_task 语义一致:end_time 最多为 开始时间+上限时长,自动结束与手动结束行为对齐",
"创建任务时即完成(packStatus>=2)的场景 end_time=start_time,不超上限,无需处理"
],
"module": "setting.warehouse"
},
{
"version": "2026.08.15-pack-task-auto-finish",
"date": "2026-08-15",
"type": "added",
"summary": "新增打包任务自动结束定时任务(每小时一次):扫描 wms_pack_task 未结束任务,按仓库配置 single_order_pack_max_minutes(散单,默认 3 分钟)/ group_order_pack_max_minutes(团购,默认 40 分钟)判断超时,当前时间-开始时间超过上限时将 end_time 置为开始时间+上限时长并标记已完成",
"methods": [],
"notes": [
"新增 app/schedule/auto_finish_pack_task.js:interval 1h、type worker、非 immediate,单 worker 防重入(ctx.app._autoFinishPackTaskRunning)",
"新增 app/service/systems/pack_task_auto_finish.js:扫描 status < 2 且 start_time 非空的任务,按 warehouse_id 去重后经 deliveryOrder.getStoreSubjectConfig(缓存优先)拉取配置,pack_mode=2 按团购时长、其余按散单时长",
"超时判定:当前时间 - 开始时间 > 配置分钟数;结束时间 = 开始时间 + 上限时长(而非当前时间),status 置为 2",
"未配置有效时长(缺失或非正整数)的仓库跳过,不做自动结束;任务 start_time 非法时跳过",
"配置字段与仓库设置联动:single_order_pack_max_minutes / group_order_pack_max_minutes 已在 WAREHOUSE_SETTING_FIELDS 与 Store.normalizeSubjectConfig 中注册,默认值 3 / 40 分钟"
],
"module": "setting.warehouse"
},
{
"version": "2026.08.15-warehouse-pack-max-minutes",
"date": "2026-08-15",
"type": "added",
"summary": "仓库设置 setting.warehouse 新增打包最大时长配置:single_order_pack_max_minutes 散单打包最大时长(分钟,默认 3)、group_order_pack_max_minutes 团购打包最大时长(分钟,默认 40)",
"methods": [
"setting.warehouse.getSettings",
"setting.warehouse.getFieldMeta",
"setting.warehouse.saveSettings"
],
"notes": [
"在 WAREHOUSE_SETTING_FIELDS 中新增 single_order_pack_max_minutes(integer,非必填,默认 3,min 1)与 group_order_pack_max_minutes(integer,非必填,默认 40,min 1)",
"wms_store.subject_config 默认值同步补齐(app/model/store.js DEFAULT_SUBJECT_CONFIG),normalizeSubjectConfig 增加大于 0 的整数校验,空值回退默认",
"methods/system.json 中 getSettings 响应与 saveSettings 入参补充对应字段文档",
"向后兼容:新增字段为可选,不影响既有仓库设置读写"
],
"module": "setting.warehouse"
},
{
"version": "2026.08.15-recheckOrder.scanOrder.groupInterceptSeq",
"date": "2026-08-15",

View File

@ -6918,7 +6918,7 @@
},
{
"method": "order.packing.setEndTime",
"description": "设置打包任务结束时间。若任务状态不是已完成(2),则同步更新状态为已完成。前端默认值:若任务已有结束时间则默认为当前时间,否则默认为开始时间+5分钟。",
"description": "设置打包任务结束时间。若任务状态不是已完成(2),则同步更新状态为已完成。前端默认值:若任务已有结束时间则默认为当前时间,否则默认为开始时间+5分钟。结束时间超过仓库配置的打包最大时长上限时自动截断为 开始时间+上限时长(散单 single_order_pack_max_minutes 默认 3 分钟 / 团购 group_order_pack_max_minutes 默认 40 分钟)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -6940,7 +6940,7 @@
"name": "end_time",
"type": "string",
"required": true,
"description": "结束时间(ISO 8601 格式,如 2026-07-27T11:00:00.000Z)。前端默认值:若任务已有结束时间→当前时间;无结束时间→开始时间+5分钟"
"description": "结束时间(ISO 8601 格式,如 2026-07-27T11:00:00.000Z)。前端默认值:若任务已有结束时间→当前时间;无结束时间→开始时间+5分钟。若超过仓库配置的打包最大时长上限(开始时间+配置分钟数),将自动截断为上限时间"
}
],
"response": [
@ -6954,7 +6954,7 @@
"name": "end_time",
"type": "string",
"required": true,
"description": "更新后的结束时间"
"description": "更新后的结束时间(已按仓库配置上限截断,最多为开始时间+配置分钟数)"
},
{
"name": "status",
@ -13783,6 +13783,18 @@
"type": "string",
"required": false,
"description": "仓库收货地址(退货/退件收件地址),一行文本,默认空字符串"
},
{
"name": "subject_config.single_order_pack_max_minutes",
"type": "number",
"required": false,
"description": "散单打包最大时长,单位:分钟,默认 3"
},
{
"name": "subject_config.group_order_pack_max_minutes",
"type": "number",
"required": false,
"description": "团购打包最大时长,单位:分钟,默认 40"
}
],
"errors": [
@ -14033,6 +14045,20 @@
"required": false,
"source": "body.subject_config",
"description": "仓库收货地址(退货/退件收件地址),一行文本,默认空字符串,最大长度 500"
},
{
"name": "subject_config.single_order_pack_max_minutes",
"type": "number",
"required": false,
"source": "body.subject_config",
"description": "散单打包最大时长,单位:分钟,默认 3,须为大于 0 的整数"
},
{
"name": "subject_config.group_order_pack_max_minutes",
"type": "number",
"required": false,
"source": "body.subject_config",
"description": "团购打包最大时长,单位:分钟,默认 40,须为大于 0 的整数"
}
],
"response": [