feat(workbench): 大团购打包时长按工作台打包人数分摊

- 等待秒数公式改为「大团购打包系数 x 当前波次打包数 / 当前工作台打包人数」:_packOrder 倒计时字段 pack_wait_seconds 与 _queryOrder 闸门均按人数分摊

- 新增 _countCurrentPackMembers:统计 wms_workbench_member 当前成员数,查询失败/为 0 时按 1 兜底(人数为 0 时任务已被成员全登出流程自动结束,不会出现 0 人任务)

- 闸门拉取当前打包任务仅统计进行中任务(status<2,任务已结束则不计)

- 测试:workbench.bigGroupTimeGate.regression.test.js 新增人数分摊用例(打包 2 人 1x3/2=1.5 秒、闸门 3 人 10x3/3=10 秒未到拦截/超过放行),共 13 用例全绿;ESLint 0 错误;workbench.js 语法通过

- 文档:methods/system.json 升至 0.3.183(pack_wait_seconds 描述改为人数分摊口径、big_group_pack_coefficient 描述统一),changes 新增 2 条记录,已同步库表(import+export)
This commit is contained in:
liufumingren 2026-09-24 17:38:10 +08:00
parent c727cd1c5c
commit 3d2291907e
4 changed files with 139 additions and 18 deletions

View File

@ -782,7 +782,7 @@ class WorkbenchService extends Service {
* 打包人:上报了 users(business 旧链路)以上报为准,未上报(token+key 新链路)自动回填工作台绑定成员。
* 波次范围(wave_scope):优先取上报值(0-4 整数),非法/缺省时兜底取订单行 wave_scope,
* 服务端复查落库,防止前端失真;写入 wms_pack_task.wave_scope。
* 响应附大团购倒计时字段:wave_scope=1 时下发 pack_wait_seconds(当前波次打包数 × 大团购打包系数,秒)
* 响应附大团购倒计时字段:wave_scope=1 时下发 pack_wait_seconds(大团购打包系数 × 当前波次打包数 ÷ 当前工作台打包人数,秒)
* 与 pack_start_time(开始打包时间,毫秒时间戳)供前端倒计时;其他波次两字段均为 0。
* @param {Object} params - { delivery_order_code, wave_no, wave_scope, warehouse_id, workbench_id, status, pack_time, waybill_code, users }
* @param {string} [params.waybill_code] 扫描打包的运单号(可选,用于运单维度记录流水)
@ -1269,13 +1269,16 @@ class WorkbenchService extends Service {
};
// 大团购波次(wave_scope=1)下发倒计时字段供前端展示:
// pack_wait_seconds = 当前波次打包数 × 大团购打包系数(秒),pack_start_time = 开始打包时间(毫秒时间戳);
// 其他波次一律下发 0(不参与倒计时)。
// pack_wait_seconds = 大团购打包系数 × 当前波次打包数 ÷ 当前工作台打包人数(秒),
// pack_start_time = 开始打包时间(毫秒时间戳);其他波次一律下发 0(不参与倒计时)。
// 打包人数取该工作台当前打包成员数;人数为 0 时任务已被成员全部登出流程自动结束,
// 不会出现 0 人任务,仍按 1 兜底防除零。
let packWaitSeconds = 0;
let packStartTime = 0;
if (normalizedWaveScope === 1) {
const coefficient = await this._getBigGroupPackCoefficient(warehouseId);
packWaitSeconds = packQuantity * coefficient;
const packMemberCount = Array.isArray(users) && users.length > 0 ? users.length : 1;
packWaitSeconds = packQuantity * coefficient / packMemberCount;
packStartTime = packTimeMs;
}
result.pack_wait_seconds = packWaitSeconds;
@ -2066,6 +2069,28 @@ class WorkbenchService extends Service {
return items;
}
/**
* 统计当前工作台打包成员人数(wms_workbench_member 未软删除记录)。
* 查询失败或结果为 0 时按 1 兜底:成员全部登出时未结束任务已被自动结束,
* 正常流程不会出现 0 人任务,兜底仅防除零。
* @param {number} workbenchId 工作台ID
* @return {Promise<number>} 打包成员人数(至少 1)
*/
async _countCurrentPackMembers(workbenchId) {
const { ctx } = this;
try {
const count = await ctx.model.WorkbenchMember.count({
where: { workbench_id: workbenchId },
});
if (Number.isInteger(count) && count > 0) {
return count;
}
} catch (countErr) {
ctx.logger.warn('[Workbench._countCurrentPackMembers] 统计打包成员失败: %s', countErr.message);
}
return 1;
}
/**
* 读取仓库「大团购打包系数」配置(wms_store.subject_config.big_group_pack_coefficient)。
* 走 deliveryOrder.getStoreSubjectConfig 公共读取链路(带缓存);配置读取失败
@ -2100,7 +2125,7 @@ class WorkbenchService extends Service {
* order 对象始终包含 picker_id / picker_name:通过 wave_id 关联拣货任务取拣货人,
* 散单无波次或未分配拣货人时为 null / 空串。
* 大团购打包时长闸门:当前工作台存在进行中的大团购打包任务时,判断是否已到
* 「当前波次打包数 × 大团购打包系数」秒:未到时仅允许查询本波次订单,
* 「大团购打包系数 × 当前波次打包数 ÷ 当前工作台打包人数」秒:未到时仅允许查询本波次订单,
* 其他波次订单返回「打包时长不足」错误;已到时不受限制。
* 查询成功时生成一次性打包上下文 key(20 分钟有效)写入 Redis,
* 响应附 key 供 workbench.packOrder 消费,打包参数由后端维护防篡改。
@ -2224,8 +2249,9 @@ class WorkbenchService extends Service {
// 步骤3.5:大团购打包时长闸门。
// 打包任务已落库 wave_scope,直接按 wave_scope=1 快捷判定当前工作台是否有
// 进行中的大团购任务需要限制下一个任务的开始时间:
// - 未到「当前波次打包数 × 大团购打包系数」秒时:仅允许查询本波次订单,其他波次订单返回「打包时长不足」错误;
// 进行中的大团购任务(status<2,任务已结束则不计)需要限制下一个任务的开始时间:
// - 未到「大团购打包系数 × 当前波次打包数 ÷ 当前工作台打包人数」秒时:
// 仅允许查询本波次订单,其他波次订单返回「打包时长不足」错误;
// - 已到时:不受限制,正常下发。
if (validQueryWorkbenchId) {
let packTimeGateNotReached = false;
@ -2252,7 +2278,8 @@ class WorkbenchService extends Service {
const currentPackQuantity = Number(currentPackTask.pack_quantity) > 0
? Number(currentPackTask.pack_quantity)
: 1;
const requiredSeconds = currentPackQuantity * coefficient;
const packMemberCount = await this._countCurrentPackMembers(validQueryWorkbenchId);
const requiredSeconds = currentPackQuantity * coefficient / packMemberCount;
const elapsedSeconds = Math.floor((Date.now() - startMs) / 1000);
if (elapsedSeconds < requiredSeconds) {
packTimeGateNotReached = true;

View File

@ -1,4 +1,30 @@
[
{
"version": "2026.09.24-big-group-pack-coefficient-desc",
"date": "2026-09-24",
"type": "updated",
"summary": "大团购打包系数字段描述统一:subject_config.big_group_pack_coefficient 描述更新为「大团购波次(wave_scope=1)打包中,扫描其他波次订单至少需等待「当前波次打包数 × 系数」秒,单位:秒/单,默认 3,必须大于 0」",
"methods": [
"setting.warehouse.getSettings"
],
"notes": [
"字段元信息 app/service/systems/setting/warehouse.js(WAREHOUSE_SETTING_FIELDS)中 big_group_pack_coefficient 的 description 已与该口径一致,无代码变更"
]
},
{
"version": "2026.09.24-workbench-big-group-pack-member-divide",
"date": "2026-09-24",
"type": "updated",
"summary": "大团购打包时长按人数分摊:workbench.packOrder 倒计时字段 pack_wait_seconds 与 workbench.queryOrder 闸门等待秒数改为「大团购打包系数 × 当前波次打包数 ÷ 当前工作台打包人数」;拉取当前打包任务时仅统计进行中任务(status<2,任务已结束则不计);人数为 0 时任务已被成员全部登出流程自动结束,不会出现,仍按 1 兜底防除零",
"methods": [
"workbench.packOrder",
"workbench.queryOrder"
],
"notes": [
"代码位置:app/service/systems/workbench.js(_packOrder 倒计时按 users 成员数分摊、_queryOrder 闸门按 _countCurrentPackMembers 统计 wms_workbench_member 人数分摊)",
"回归测试:test/app/service/systems/workbench.bigGroupTimeGate.regression.test.js 新增人数分摊用例(打包 2 人 1×3/2=1.5 秒、闸门 3 人 10×3/3=10 秒),共 13 用例全绿"
]
},
{
"version": "2026.09.24-setting-big-group-pack-coefficient",
"date": "2026-09-24",

View File

@ -1,7 +1,7 @@
{
"module": "system",
"description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内",
"version": "0.3.181",
"version": "0.3.183",
"updatedAt": "2026-09-24",
"headers": [
{
@ -15131,7 +15131,7 @@
"name": "subject_config.big_group_pack_coefficient",
"type": "number",
"required": false,
"description": "大团购打包系数(数字,默认 3,单位秒/单,必须大于 0;workbench.packOrder 大团购波次倒计时等待秒数 = 当前波次打包数 × 该系数)"
"description": "大团购波次(wave_scope=1)打包中,扫描其他波次订单至少需等待「当前波次打包数 × 系数」秒,单位:秒/单,默认 3,必须大于 0"
},
{
"name": "subject_config.return_unpack_max_record_minutes",
@ -35401,7 +35401,7 @@
},
{
"method": "workbench.packOrder",
"description": "工作台打包上报(免登录、免权限、免鉴权,以工作台 token 鉴权):推荐只传 token + key,订单相关信息(订单号/波次号/运单号)由后端从缓存拉取(前端先经 workbench.queryOrder 扫码拿到 key,20 分钟有效,防篡改);不传 key 时旧参数模式(delivery_order_code 等直传)过渡兼容,后续版本将移除;仓库与工作台均由服务端从 token 解析注入(禁止前端传值);跨仓库/跨工作台消费他人 key 返回 403、key 缺失或过期返回 400(请重新扫码)。打包流程:按发货单号定位订单(current→dispatch 分表),同一工作台存在上一个未结束任务时先关闭(同步回写旧订单打包状态并补确认打印状态,并将工作台绑定摄像头 OSD 复位为「无任务」,新任务 OSD 在其后串行下发避免被复位覆盖),散单去重(传运单号按 order_id+waybill_code、未传按 order_id)、团购按 wave_no 去重后创建打包任务(wms_pack_task,status 归一化为 1=打包中,散单传运单号时 waybill_code 写入流水),写入打包人员(wms_pack_task_packer,自动取该工作台绑定成员 wms_workbench_member)与 operator_text、下发 OSD 到工作台绑定摄像头(散单优先展示打包运单号、团购显示波次号+订单总量,并写 Redis osd_{workbenchId} 缓存)、写操作日志;打包状态变更后主动失效对应工作台 token 缓存,保证 getWorkbenchInfo 尽快返回最新打包信息;团购单(isSandan=0)响应附 batch 波次信息(波次订单数为 current+dispatch 分表实时统计);拦截流程中的订单不允许打包(散单直接拒绝、团购波次静默跳过并视为完成);保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200;打包任务落库 wave_scope(波次范围:0=未分配 1=大团购 2=散单 3=小团购 4=单品单件,服务端复查:上报值非法/缺省时兜底订单行值);大团购波次(wave_scope=1)响应附倒计时字段 pack_wait_seconds(当前波次打包数 × 仓库配置大团购打包系数,单位秒)与 pack_start_time(开始打包时间,毫秒时间戳)供前端倒计时,其他波次两字段均为 0",
"description": "工作台打包上报(免登录、免权限、免鉴权,以工作台 token 鉴权):推荐只传 token + key,订单相关信息(订单号/波次号/运单号)由后端从缓存拉取(前端先经 workbench.queryOrder 扫码拿到 key,20 分钟有效,防篡改);不传 key 时旧参数模式(delivery_order_code 等直传)过渡兼容,后续版本将移除;仓库与工作台均由服务端从 token 解析注入(禁止前端传值);跨仓库/跨工作台消费他人 key 返回 403、key 缺失或过期返回 400(请重新扫码)。打包流程:按发货单号定位订单(current→dispatch 分表),同一工作台存在上一个未结束任务时先关闭(同步回写旧订单打包状态并补确认打印状态,并将工作台绑定摄像头 OSD 复位为「无任务」,新任务 OSD 在其后串行下发避免被复位覆盖),散单去重(传运单号按 order_id+waybill_code、未传按 order_id)、团购按 wave_no 去重后创建打包任务(wms_pack_task,status 归一化为 1=打包中,散单传运单号时 waybill_code 写入流水),写入打包人员(wms_pack_task_packer,自动取该工作台绑定成员 wms_workbench_member)与 operator_text、下发 OSD 到工作台绑定摄像头(散单优先展示打包运单号、团购显示波次号+订单总量,并写 Redis osd_{workbenchId} 缓存)、写操作日志;打包状态变更后主动失效对应工作台 token 缓存,保证 getWorkbenchInfo 尽快返回最新打包信息;团购单(isSandan=0)响应附 batch 波次信息(波次订单数为 current+dispatch 分表实时统计);拦截流程中的订单不允许打包(散单直接拒绝、团购波次静默跳过并视为完成);保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200;打包任务落库 wave_scope(波次范围:0=未分配 1=大团购 2=散单 3=小团购 4=单品单件,服务端复查:上报值非法/缺省时兜底订单行值);大团购波次(wave_scope=1)响应附倒计时字段 pack_wait_seconds(大团购打包系数 × 当前波次打包数 ÷ 当前工作台打包人数,单位秒;人数为 0 时任务已被成员全部登出流程自动结束,不会出现,仍按 1 兜底防除零)与 pack_start_time(开始打包时间,毫秒时间戳)供前端倒计时,其他波次两字段均为 0",
"isNeedAuth": false,
"isNeedLogin": false,
"isNeedRight": false,
@ -35469,7 +35469,7 @@
"name": "pack_wait_seconds",
"type": "number",
"required": true,
"description": "大团购倒计时等待秒数(当前波次打包数 × 仓库配置大团购打包系数 big_group_pack_coefficient;仅 wave_scope=1 返回实际值,其他波次为 0)"
"description": "大团购倒计时等待秒数(大团购打包系数 big_group_pack_coefficient × 当前波次打包数 ÷ 当前工作台打包人数;仅 wave_scope=1 返回实际值,其他波次为 0)"
},
{
"name": "pack_start_time",
@ -35727,7 +35727,7 @@
},
{
"method": "workbench.queryOrder",
"description": "工作台条码查询订单(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值,防止跨仓库查单),入参条码(运单号);条码→运单记录(wms_order_express,按 waybill_code+warehouse_id+status=1 精确匹配)→ 序列表定位优先、未命中按 current→dispatch 回退遍历订单分表 → 组装查询结果(barcode/waybill_code/isSandan/store_remark/express/order/items/source_table);散单(isSandan=1)order 附拦截/打包 0/1 标志 intercept_flag/pack_flag(拦截标志:拦截状态空值归一化为 none,非 none 记 1;打包标志:按运单维度判定,该运单号已有打包流水 wms_pack_task.waybill_code 命中或历史订单级流水 waybill_code 为空兜底时为 1,否则 0,主单号/子单号互不影响);团购(isSandan=0,波次类型 wave_type=1)附 batch 波次信息(wave_id/wave_no/wave_type/total_orders,total_orders 为 current+dispatch 分表实时统计并带 15s 短缓存兜底);items 逐项合并 stock 详情(sku_property/stock_unit/barcodes/image_url/packing_requirements/need_recheck(是否需要复核:Y=需要 N=不需要(免验)));store_remark 来自合约表 store_warehouse.store_remask;只读查询,不涉及缓存失效;保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200;查询成功时生成打包上下文 key(wpck 前缀 + 随机段,Redis 缓存 workbench:packctx:{key},TTL 20 分钟,内容含订单号/波次号/运单号/归属仓库与工作台,后端维护防篡改)并在响应返回 key,供 workbench.packOrder 凭 key 打包;order 附 wave_scope(波次范围:0=未分配波次 1=大团购 2=散单 3=小团购 4=单品单件);大团购打包时长闸门:当前工作台存在进行中的 wave_scope=1 打包任务时,未到「当前波次打包数 × 仓库配置大团购打包系数」秒仅允许查询本波次订单,其他波次订单返回错误「打包时长不足」,已到时不受限制",
"description": "工作台条码查询订单(免登录、免权限、免鉴权,以工作台 token 鉴权):仓库与工作台均由服务端从 token 解析注入(body 传入 warehouse_id/workbench_id 一律忽略,禁止前端传值,防止跨仓库查单),入参条码(运单号);条码→运单记录(wms_order_express,按 waybill_code+warehouse_id+status=1 精确匹配)→ 序列表定位优先、未命中按 current→dispatch 回退遍历订单分表 → 组装查询结果(barcode/waybill_code/isSandan/store_remark/express/order/items/source_table);散单(isSandan=1)order 附拦截/打包 0/1 标志 intercept_flag/pack_flag(拦截标志:拦截状态空值归一化为 none,非 none 记 1;打包标志:按运单维度判定,该运单号已有打包流水 wms_pack_task.waybill_code 命中或历史订单级流水 waybill_code 为空兜底时为 1,否则 0,主单号/子单号互不影响);团购(isSandan=0,波次类型 wave_type=1)附 batch 波次信息(wave_id/wave_no/wave_type/total_orders,total_orders 为 current+dispatch 分表实时统计并带 15s 短缓存兜底);items 逐项合并 stock 详情(sku_property/stock_unit/barcodes/image_url/packing_requirements/need_recheck(是否需要复核:Y=需要 N=不需要(免验)));store_remark 来自合约表 store_warehouse.store_remask;只读查询,不涉及缓存失效;保留系统日志(systemInit 未声明免日志);成功返回 flag=success、code=200;查询成功时生成打包上下文 key(wpck 前缀 + 随机段,Redis 缓存 workbench:packctx:{key},TTL 20 分钟,内容含订单号/波次号/运单号/归属仓库与工作台,后端维护防篡改)并在响应返回 key,供 workbench.packOrder 凭 key 打包;order 附 wave_scope(波次范围:0=未分配波次 1=大团购 2=散单 3=小团购 4=单品单件);大团购打包时长闸门:拉取当前工作台进行中的 wave_scope=1 打包任务(status<2,任务已结束则不计)并判断是否已到「大团购打包系数 × 当前波次打包数 ÷ 当前工作台打包人数」秒:未到时仅允许查询本波次订单,其他波次订单返回错误「打包时长不足」,已到时不受限制",
"isNeedAuth": false,
"isNeedLogin": false,
"isNeedRight": false,

View File

@ -167,6 +167,12 @@ function createQueryOrderHarness(options = {}) {
return options.currentTask;
},
},
WorkbenchMember: {
async count() {
// 当前工作台打包成员人数(默认 1,可配置)
return options.memberCount === undefined ? 1 : options.memberCount;
},
},
},
};
@ -263,7 +269,13 @@ function createPackOrderHarness(options = {}) {
},
WorkbenchMember: {
async findAll() {
return [];
// 当前工作台绑定成员(默认 1 人,可配置)
const memberCount = options.memberCount === undefined ? 1 : options.memberCount;
return Array.from({ length: memberCount }, (_, index) => ({
id: index + 1,
user_id: 100000 + index,
user_name: `成员${index + 1}`,
}));
},
},
PackTask: {
@ -275,7 +287,13 @@ function createPackOrderHarness(options = {}) {
},
async create(data) {
created.push({ ...data });
return { id: 777, ...data };
return {
id: 777,
...data,
async update() {
// mock:更新任务无操作
},
};
},
async destroy() {
return 0;
@ -285,6 +303,10 @@ function createPackOrderHarness(options = {}) {
async destroy() {
return 0;
},
async bulkCreate() {
// mock:写入打包人无操作
return [];
},
},
},
};
@ -317,17 +339,25 @@ describe('workbench 大团购打包系数回归(wave_scope 落库 / 倒计时
});
describe('2. packOrder 信息写入 wms_pack_task(wave_scope 落库)与倒计时字段下发', () => {
it('wave_scope=1:PackTask.create 落库 wave_scope=1,并下发 pack_wait_seconds=打包数×系数 与 pack_start_time>0', async () => {
it('wave_scope=1:PackTask.create 落库 wave_scope=1,并下发 pack_wait_seconds=打包数×系数÷人数 与 pack_start_time>0', async () => {
const harness = createPackOrderHarness({ orderWaveScope: 1, waveScopeParam: 1 });
const result = await harness.service._packOrder(harness.packParams);
assert.strictEqual(harness.created.length, 1, '应创建一条打包任务');
assert.strictEqual(harness.created[0].wave_scope, 1, 'wave_scope=1 应写入打包任务');
// 散单打包数=1,系数=3 → 等待秒数=3
// 散单打包数=1,系数=3,成员默认 1 人 → 等待秒数=1×3/1=3
assert.strictEqual(result.pack_wait_seconds, 3);
assert.ok(result.pack_start_time > 0, 'wave_scope=1 时应下发开始打包时间');
});
it('wave_scope=1 且工作台 2 人打包:等待秒数按人数分摊(1×3/2=1.5)', async () => {
const harness = createPackOrderHarness({ orderWaveScope: 1, waveScopeParam: 1, memberCount: 2 });
const result = await harness.service._packOrder(harness.packParams);
assert.strictEqual(result.pack_wait_seconds, 1.5);
assert.ok(result.pack_start_time > 0);
});
it('未上报 wave_scope:兜底订单行 wave_scope=1 落库,并下发倒计时字段', async () => {
const harness = createPackOrderHarness({ orderWaveScope: 1 });
const result = await harness.service._packOrder(harness.packParams);
@ -361,7 +391,7 @@ describe('workbench 大团购打包系数回归(wave_scope 落库 / 倒计时
},
});
// 需要 10×3=30 秒,仅过去 5 秒 → 未到时 → 不同波次拦截
// 需要 10×3/1=30 秒,仅过去 5 秒 → 未到时 → 不同波次拦截
await assert.rejects(
() => harness.service._queryOrder(harness.queryParams),
error => error && error.message === '打包时长不足'
@ -404,6 +434,44 @@ describe('workbench 大团购打包系数回归(wave_scope 落库 / 倒计时
assert.strictEqual(result.order.wave_id, TEST_WAVE_ID);
});
it('工作台 3 人打包时等待秒数按人数分摊(10×3/3=10 秒):未到 10 秒拦截,超过 10 秒放行', async () => {
const notReached = createQueryOrderHarness({
memberCount: 3,
orderRow: { wave_scope: 1, wave_id: TEST_WAVE_ID },
currentTask: {
id: 1,
wave_scope: 1,
wave_id: TEST_OTHER_WAVE_ID,
pack_quantity: 10,
start_time: new Date(Date.now() - 5 * 1000),
create_time: new Date(Date.now() - 5 * 1000),
},
});
// 需要 10×3/3=10 秒,仅过去 5 秒 → 未到时 → 拦截
await assert.rejects(
() => notReached.service._queryOrder(notReached.queryParams),
error => error && error.message === '打包时长不足'
);
const reached = createQueryOrderHarness({
memberCount: 3,
orderRow: { wave_scope: 1, wave_id: TEST_WAVE_ID },
currentTask: {
id: 1,
wave_scope: 1,
wave_id: TEST_OTHER_WAVE_ID,
pack_quantity: 10,
start_time: new Date(Date.now() - 12 * 1000),
create_time: new Date(Date.now() - 12 * 1000),
},
});
// 需要 10 秒,已过 12 秒 → 已到时 → 放行
const result = await reached.service._queryOrder(reached.queryParams);
assert.strictEqual(result.order.wave_id, TEST_WAVE_ID);
});
it('当前任务 wave_scope≠1(散单任务)→ 不限制(其他不限制)', async () => {
const harness = createQueryOrderHarness({
orderRow: { wave_scope: 1, wave_id: TEST_WAVE_ID },