feat(returnUnpack): 拆包最大录制时长配置(默认5分钟),提交时截断结束时间

This commit is contained in:
liufumingren 2026-08-29 19:44:07 +08:00
parent 15e109f992
commit 54065d7ee1
5 changed files with 111 additions and 5 deletions

View File

@ -62,6 +62,7 @@ module.exports = app => {
default_location_id: null,
single_order_pack_max_minutes: 3,
group_order_pack_max_minutes: 40,
return_unpack_max_record_minutes: 5,
inventory_warning_rules: DEFAULT_INVENTORY_WARNING_RULES,
auto_outbound_rules: DEFAULT_AUTO_OUTBOUND_RULES,
cutoff_order_enabled: 1,
@ -267,6 +268,17 @@ module.exports = app => {
normalized.group_order_pack_max_minutes = groupOrderPackMaxMinutes;
}
const rawReturnUnpackMaxRecordMinutes = parsed.return_unpack_max_record_minutes;
if (rawReturnUnpackMaxRecordMinutes === undefined || rawReturnUnpackMaxRecordMinutes === null || rawReturnUnpackMaxRecordMinutes === '') {
normalized.return_unpack_max_record_minutes = DEFAULT_SUBJECT_CONFIG.return_unpack_max_record_minutes;
} else {
const returnUnpackMaxRecordMinutes = Number(rawReturnUnpackMaxRecordMinutes);
if (!Number.isInteger(returnUnpackMaxRecordMinutes) || returnUnpackMaxRecordMinutes <= 0) {
throw new Error('subject_config.return_unpack_max_record_minutes 必须是大于 0 的整数');
}
normalized.return_unpack_max_record_minutes = returnUnpackMaxRecordMinutes;
}
const rawExcludeRemarks = parsed.auto_allocate_express_exclude_remarks;
if (rawExcludeRemarks === undefined || rawExcludeRemarks === null || rawExcludeRemarks === '') {
normalized.auto_allocate_express_exclude_remarks = [];

View File

@ -509,7 +509,57 @@ class ReturnUnpackService extends Service {
}
/**
* 提交确认:未完成拆包单转 completed 终态,回写结束时间,
* 按仓库配置的拆包最大录制时长约束提交结束时间。
* 候选结束时间超过 开始时间+上限时长 时,截断为上限时间点。
* 开始时间缺失、配置非法或读取失败时不约束,原样返回。
*
* @param {Object} unpack 拆包单主表记录(需含 id / warehouse_id / start_time)。
* @param {Date} candidateEndTime 候选结束时间。
* @return {Promise<Date>} 约束后的结束时间。
*/
async _resolveSubmitEndTime(unpack, candidateEndTime) {
const { ctx } = this;
const candidate = candidateEndTime instanceof Date ? candidateEndTime : new Date(candidateEndTime);
if (!unpack || !Number.isFinite(candidate.getTime())) {
return candidateEndTime;
}
const startMs = new Date(unpack.start_time).getTime();
if (!Number.isFinite(startMs)) {
return candidateEndTime;
}
let limitMinutes = null;
try {
const warehouseId = Number(unpack.warehouse_id || 0);
const subjectConfig = await ctx.service.systems.deliveryOrder.getStoreSubjectConfig(warehouseId);
limitMinutes = Number(subjectConfig && subjectConfig.return_unpack_max_record_minutes);
} catch (error) {
ctx.logger.warn(`[returnUnpack.submit] 读取仓库拆包时长配置失败: ${error.message}`);
}
// 未配置有效时长时不约束结束时间
if (!Number.isInteger(limitMinutes) || limitMinutes <= 0) {
return candidateEndTime;
}
const maxEndMs = startMs + limitMinutes * 60 * 1000;
if (candidate.getTime() > maxEndMs) {
const cappedEndTime = new Date(maxEndMs);
ctx.logger.info(
`[returnUnpack.submit] 结束时间超过拆包录制上限,截断为上限时间 unpack_id=${unpack.id} ` +
`limitMinutes=${limitMinutes} candidate=${candidate.toISOString()} end=${cappedEndTime.toISOString()}`
);
return cappedEndTime;
}
return candidateEndTime;
}
/**
* 提交确认:未完成拆包单转 completed 终态,回写结束时间(超过仓库配置的
* 拆包最大录制时长时自动截断为开始时间+上限),
* 并同步更新退回查询记录 is_back=1(标记该运单号已退回)。
*
* @param {Object} params 提交参数。
@ -523,8 +573,9 @@ class ReturnUnpackService extends Service {
this._assertUnpacking(unpack);
const now = new Date();
const endTime = await this._resolveSubmitEndTime(unpack, now);
await ctx.model.ReturnUnpack.update(
{ status: 'completed', end_time: now },
{ status: 'completed', end_time: endTime },
{ where: { id: unpack.id } }
);

View File

@ -292,6 +292,15 @@ const WAREHOUSE_SETTING_FIELDS = Object.freeze([
description: '团购打包最大时长,单位:分钟,默认 40',
min: 1,
}),
Object.freeze({
key: 'return_unpack_max_record_minutes',
name: '拆包最大录制时长(分钟)',
type: 'integer',
default: 5,
required: false,
description: '拆包最大录制时长,单位:分钟,默认 5;超过上限时提交的结束时间自动截断为开始时间+上限',
min: 1,
}),
Object.freeze({
key: 'default_location_id',
name: '默认库位',

View File

@ -1,4 +1,25 @@
[
{
"version": "2026.08.29-return-unpack-max-record-minutes",
"date": "2026-08-29",
"type": "enhanced",
"summary": "仓库设置新增「拆包最大录制时长」配置 return_unpack_max_record_minutes(分钟,默认 5,min 1):returnUnpack.submit 提交确认时,结束时间超过 开始时间+配置上限 时自动截断为上限时间点",
"methods": [
"setting.warehouse.getSettings",
"setting.warehouse.getFieldMeta",
"setting.warehouse.saveSettings",
"returnUnpack.submit"
],
"notes": [
"app/service/systems/setting/warehouse.js WAREHOUSE_SETTING_FIELDS 新增 return_unpack_max_record_minutes(名称:拆包最大录制时长(分钟),type integer,非必填,默认 5,min 1,描述:超过上限时提交的结束时间自动截断为开始时间+上限),与 single_order_pack_max_minutes(默认 3)/ group_order_pack_max_minutes(默认 40)并列;getFieldMeta 自动返回该字段元信息",
"app/model/store.js DEFAULT_SUBJECT_CONFIG 增加 return_unpack_max_record_minutes: 5;normalizeSubjectConfig 非法值(非正整数)抛「subject_config.return_unpack_max_record_minutes 必须是大于 0 的整数」,空值回退默认 5",
"app/service/systems/return_unpack.js submit() 新增私有方法 _resolveSubmitEndTime:候选 end_time 超过 start_time + 配置上限分钟时截断为上限时间点并记录 info 日志;配置读取 ctx.service.systems.deliveryOrder.getStoreSubjectConfig,配置非法/读取失败/start_time 缺失时不约束;其余行为不变(completed 终态、回写 is_back=1、货主群通知等均不变)",
"methods/system.json:setting.warehouse.getSettings 响应与 setting.warehouse.saveSettings 入参新增 subject_config.return_unpack_max_record_minutes 字段文档;returnUnpack.submit description 与响应 record 补充「结束时间超过仓库配置的拆包最大录制时长上限时自动截断为开始时间+上限」语义;getFieldMeta 为通用字段元信息结构,无逐字段清单,无需改动",
"向后兼容:新增字段可选,不影响既有仓库设置读写;本次仅文档同步,业务代码由 wms-dev-agent 完成",
"methods/system.json 版本 0.3.45 -> 0.3.46(docMeta.version),updatedAt 保持 2026-08-29"
],
"module": "returnUnpack"
},
{
"version": "2026.08.27-order-allocateStorage-allow-storage-location",
"date": "2026-08-27",

View File

@ -1,7 +1,7 @@
{
"module": "system",
"description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内",
"version": "0.3.37",
"version": "0.3.46",
"updatedAt": "2026-08-27",
"headers": [
{
@ -13947,6 +13947,12 @@
"required": false,
"description": "团购打包最大时长,单位:分钟,默认 40"
},
{
"name": "subject_config.return_unpack_max_record_minutes",
"type": "number",
"required": false,
"description": "拆包最大录制时长,单位:分钟,默认 5,min 1;超过上限时拆包提交的结束时间自动截断为开始时间+上限"
},
{
"name": "subject_config.default_location_id",
"type": "number",
@ -14217,6 +14223,13 @@
"source": "body.subject_config",
"description": "团购打包最大时长,单位:分钟,默认 40,须为大于 0 的整数"
},
{
"name": "subject_config.return_unpack_max_record_minutes",
"type": "number",
"required": false,
"source": "body.subject_config",
"description": "拆包最大录制时长,单位:分钟,默认 5,min 1,须为大于 0 的整数(非法值报 400:subject_config.return_unpack_max_record_minutes 必须是大于 0 的整数);超过上限时拆包提交的结束时间自动截断为开始时间+上限"
},
{
"name": "subject_config.default_location_id",
"type": "number",
@ -37390,7 +37403,7 @@
},
{
"method": "returnUnpack.submit",
"description": "提交确认:未完成(unpacking)拆包单转 completed 终态并回写 end_time(拆包结束时间);同步按 warehouse_id+waybill_code 更新 wms_return_query_log.is_back=1(标记该运单号已退回,更新失败不阻断主流程)。提交后进入终态,不可再录/移除明细。仓库隔离校验(仅本仓库拆包单)。",
"description": "提交确认:未完成(unpacking)拆包单转 completed 终态并回写 end_time(拆包结束时间;结束时间超过仓库配置的拆包最大录制时长上限时,自动截断为 开始时间+上限——仓库配置项 subject_config.return_unpack_max_record_minutes,默认 5 分钟,配置缺失/非法或开始时间缺失时不约束);同步按 warehouse_id+waybill_code 更新 wms_return_query_log.is_back=1(标记该运单号已退回,更新失败不阻断主流程)。提交后进入终态,不可再录/移除明细。仓库隔离校验(仅本仓库拆包单)。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [],
@ -37408,7 +37421,7 @@
"name": "record",
"type": "object",
"required": true,
"description": "更新后的主表记录(含 status=completed、end_time 及格式化时间字段)"
"description": "更新后的主表记录(含 status=completed、end_time 及格式化时间字段;end_time 为按仓库拆包最大录制时长上限约束后的结束时间,超过上限时截断为 开始时间+上限)"
}
],
"errors": [