feat(pick): 整波领料 waveClaimScan 与拣货领料前置校验

- 新增 pick.waveClaimScan: 扫面单号定位订单并反查波次, 仅普通波次(source=0)支持整波领料
- 新增 getWavePickModeByWaveId 关联拣货模式查询
- query 命中大团购/非抓取散单波次时校验领料状态, 未领料提示先整波领单
- 波次存在未打印订单时禁止领料, 领料写入 ORDER_WAVE_CLAIM 操作日志
This commit is contained in:
liufumingren 2026-08-21 02:20:02 +08:00
parent ace0e456a7
commit d4dc25c8e7
2 changed files with 350 additions and 2 deletions

View File

@ -76,6 +76,7 @@ module.exports = {
ORDER_WAVE_GRAB: '抓取波次',
ORDER_WAVE_AUTO_GROUP: '自动加团',
ORDER_WAVE_STRATEGY_FETCH: '策略抓取波次',
ORDER_WAVE_CLAIM: '领取波次',
ORDER_PICK_COMPLETE: '拣货完成',
ORDER_RECHECK: '订单复核',
ORDER_RECHECK_BATCH: '批量复核',

View File

@ -1,5 +1,6 @@
'use strict';
const { Op } = require('sequelize');
const MainService = require('../main');
const { isInterceptedOrderStatus } = require('../../lib/intercept_guard');
@ -12,9 +13,9 @@ class PickService extends MainService {
constructor(ctx) {
super(ctx);
const _noNeedLogin = '';
const _noNeedRight = 'query,wavePickComplete,wavePickTaskDetail,wavePickTaskCurrent,wavePickTaskSubmit,wavePickTaskComplete';
const _noNeedRight = 'query,wavePickComplete,wavePickTaskDetail,wavePickTaskCurrent,wavePickTaskSubmit,wavePickTaskComplete,waveClaimScan';
const _noNeedLog = 'query';
const _noNeedAuth = 'query,wavePickComplete,wavePickTaskDetail,wavePickTaskCurrent,wavePickTaskSubmit,wavePickTaskComplete';
const _noNeedAuth = 'query,wavePickComplete,wavePickTaskDetail,wavePickTaskCurrent,wavePickTaskSubmit,wavePickTaskComplete,waveClaimScan';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
@ -1488,6 +1489,352 @@ class PickService extends MainService {
}
}
/**
* 查询波次关联的拣货模式。
*
* 优先按拣货任务主表(wms_wave_pick_task.wave_id)直接关联查询,
* 未命中时回退到任务与波次关联表(wms_wave_pick_task_wave)查询。
*
* @param {number|string} waveId 波次ID。
* @return {Promise<number>} 拣货模式:1-团购小波次 2-散单单品单件 3-先拣后分 4-边拣边分 5-团购大波次(0 表示无关联拣货任务)。
*/
async getWavePickModeByWaveId(waveId) {
const { ctx } = this;
const normalizedWaveId = Number(waveId || 0);
if (!Number.isInteger(normalizedWaveId) || normalizedWaveId <= 0) {
return 0;
}
const directRows = await ctx.model.query(
`SELECT pick_mode
FROM wms_wave_pick_task
WHERE wave_id = :waveId
ORDER BY id DESC
LIMIT 1`,
{
replacements: { waveId: normalizedWaveId },
type: ctx.model.QueryTypes.SELECT,
}
);
const directRow = Array.isArray(directRows) && directRows.length > 0 ? directRows[0] : null;
if (directRow) {
return Number(directRow.pick_mode || 0);
}
const linkRows = await ctx.model.query(
`SELECT t.pick_mode
FROM wms_wave_pick_task_wave tw
INNER JOIN wms_wave_pick_task t ON t.id = tw.task_id
WHERE tw.wave_id = :waveId
ORDER BY t.id DESC
LIMIT 1`,
{
replacements: { waveId: normalizedWaveId },
type: ctx.model.QueryTypes.SELECT,
}
);
const linkRow = Array.isArray(linkRows) && linkRows.length > 0 ? linkRows[0] : null;
return linkRow ? Number(linkRow.pick_mode || 0) : 0;
}
/**
* 扫描面单号领取整波(领料)。
*
* 按面单号(运单号,wms_order_express.waybill_code)定位待处理订单表中的订单后反查订单所在波次,
* 仅对普通波次(wms_wave_batch.source=0,含团购/散单)支持整波领料:
* 命中后将该波次下全部未领单订单 claim_status 置为 fin(领单完成),
* 并写入 ORDER_WAVE_CLAIM 订单操作日志,返回波次ID(wave_id)与波次编码(wave_no);
* 策略抓取波次(source=1/2)无需领料,返回 400 并提示「该波次为抓取波次,无需领料」
* (失败 data 含 no_claim_needed=true、wave_id、wave_no);
* 波次下存在未打印订单(print_status != fin)时禁止领料,
* 返回 400 并提示「波次未打印,禁止领料」(失败 data 含 wave_id、wave_no、unprinted_order_count);
* 其余未知类型返回通用不支持提示。
* 波次内订单已全部领单时返回 already_claimed 幂等结果并提示已领料。
*
* @param {Object} data 请求参数。
* @param {string} data.waybill_no 面单号(运单号,wms_order_express.waybill_code)。
* @return {Promise<Object>} 统一 success/fail 包装结果。
*/
async waveClaimScan(data = {}) {
const { ctx } = this;
const requestData = this.isPlainObject(data) ? data : {};
const waybillNo = String(requestData.waybill_no || requestData.waybillNo || '').trim();
if (!waybillNo) {
return this.fail('waybill_no 必填(面单号/运单号)', {}, 400);
}
// --- 仓库上下文与操作人 ---
const userWarehouseId = ctx && ctx.user ? ctx.user.store_id : undefined;
const stateWarehouseId = ctx && ctx.state && ctx.state.user ? ctx.state.user.store_id : undefined;
const normalizedWarehouseId = Number(userWarehouseId || stateWarehouseId || 0);
if (!Number.isFinite(normalizedWarehouseId) || normalizedWarehouseId <= 0) {
return this.fail('缺少当前用户仓库上下文 store_id', {}, 400);
}
const stateUser = this.isPlainObject(ctx && ctx.state && ctx.state.user) ? ctx.state.user : null;
const ctxUser = this.isPlainObject(ctx && ctx.user) ? ctx.user : null;
const operatorSource = stateUser || ctxUser || {};
const rawOperatorId = operatorSource.employees_id ?? operatorSource.operator_id ?? operatorSource.id;
const operatorId = Number(rawOperatorId || 0);
const operatorName = String(
operatorSource.operator_name
|| operatorSource.employees_name
|| operatorSource.name
|| ''
).trim() || 'system';
if (!Number.isInteger(operatorId) || operatorId <= 0) {
return this.fail('未获取到操作人上下文', {}, 401);
}
// --- 1. 面单号定位订单 ---
const orderExpress = await ctx.model.OrderExpress.findOne({
where: {
warehouse_id: normalizedWarehouseId,
waybill_code: waybillNo,
},
attributes: [ 'order_id' ],
raw: true,
});
const matchedOrderId = Number(orderExpress && orderExpress.order_id || 0);
if (!(matchedOrderId > 0)) {
return this.fail('未查询到该面单号对应的订单,无记录', {}, 404);
}
// --- 2. 待处理订单表定位订单 ---
let orderModel = null;
try {
orderModel = await this.getOrderModelByWarehouse(normalizedWarehouseId);
} catch (error) {
return this.fail(error && error.message ? error.message : '订单模型不可用', {}, 500);
}
const order = await orderModel.findOne({
where: {
id: matchedOrderId,
warehouse_id: normalizedWarehouseId,
},
attributes: [ 'id', 'wave_id', 'wave_no' ],
raw: true,
});
if (!order) {
return this.fail('订单不在待处理订单表,无记录', {}, 404);
}
// --- 3. 订单定位波次 ---
const orderWaveId = Number(order.wave_id || 0);
const orderWaveNo = String(order.wave_no || '').trim();
if (!(orderWaveId > 0 || orderWaveNo)) {
return this.fail('运单对应订单未分配波次', {}, 400);
}
let waveRows = [];
if (orderWaveId > 0) {
waveRows = await ctx.model.query(
`SELECT wave_id, wave_no, wave_type, source
FROM wms_wave_batch
WHERE warehouse_id = :warehouseId
AND wave_id = :waveId
LIMIT 1`,
{
replacements: {
warehouseId: normalizedWarehouseId,
waveId: orderWaveId,
},
type: ctx.model.QueryTypes.SELECT,
}
);
} else {
waveRows = await ctx.model.query(
`SELECT wave_id, wave_no, wave_type, source
FROM wms_wave_batch
WHERE warehouse_id = :warehouseId
AND wave_no = :waveNo
LIMIT 1`,
{
replacements: {
warehouseId: normalizedWarehouseId,
waveNo: orderWaveNo,
},
type: ctx.model.QueryTypes.SELECT,
}
);
}
const waveRow = Array.isArray(waveRows) && waveRows.length > 0 ? waveRows[0] : null;
if (!waveRow) {
return this.fail('运单对应波次不存在或不属于当前仓库', {}, 404);
}
const targetWaveId = Number(waveRow.wave_id || 0);
const targetWaveNo = String(waveRow.wave_no || '').trim();
const targetWaveType = Number(waveRow.wave_type || 0);
const targetWaveSource = Number(waveRow.source || 0);
if (!(targetWaveId > 0) || !targetWaveNo) {
return this.fail('目标波次信息不完整', {}, 400);
}
// --- 4. 波次关联拣货模式与领料资格判定(仅普通波次 source=0 支持整波领料)---
const pickMode = await this.getWavePickModeByWaveId(targetWaveId);
const isFetchedWave = targetWaveSource === 1 || targetWaveSource === 2;
if (isFetchedWave) {
return this.fail('该波次为抓取波次,无需领料', {
no_claim_needed: true,
wave_id: targetWaveId,
wave_no: targetWaveNo,
wave_type: targetWaveType,
wave_source: targetWaveSource,
pick_mode: pickMode,
matched_order_id: matchedOrderId,
waybill_no: waybillNo,
}, 400);
}
if (targetWaveSource !== 0) {
return this.fail('当前波次类型不支持整波领单', {
wave_id: targetWaveId,
wave_no: targetWaveNo,
wave_type: targetWaveType,
wave_source: targetWaveSource,
}, 400);
}
// --- 5. 查询波次下全部订单 ---
const waveOrderRows = await orderModel.findAll({
where: {
warehouse_id: normalizedWarehouseId,
wave_id: targetWaveId,
},
attributes: [ 'id', 'claim_status', 'print_status' ],
raw: true,
});
let waveOrders = Array.isArray(waveOrderRows) ? waveOrderRows : [];
if (waveOrders.length === 0) {
const fallbackRows = await orderModel.findAll({
where: {
warehouse_id: normalizedWarehouseId,
wave_no: targetWaveNo,
},
attributes: [ 'id', 'claim_status', 'print_status' ],
raw: true,
});
waveOrders = Array.isArray(fallbackRows) ? fallbackRows : [];
}
const waveOrderIds = [ ...new Set(waveOrders
.map(item => Number(item && item.id || 0))
.filter(id => Number.isInteger(id) && id > 0)) ];
if (waveOrderIds.length === 0) {
return this.fail('波次下无可用订单', {}, 400);
}
const totalOrderCount = waveOrderIds.length;
const unclaimedOrderIds = [ ...new Set(waveOrders
.filter(item => String(item && item.claim_status || '') !== 'fin')
.map(item => Number(item && item.id || 0))
.filter(id => Number.isInteger(id) && id > 0)) ];
const baseResponse = {
wave_id: targetWaveId,
wave_no: targetWaveNo,
wave_type: targetWaveType,
wave_source: targetWaveSource,
pick_mode: pickMode,
matched_order_id: matchedOrderId,
waybill_no: waybillNo,
total_order_count: totalOrderCount,
};
if (unclaimedOrderIds.length === 0) {
return this.success('ok', {
data: {
...baseResponse,
claimed_order_count: 0,
status: 'already_claimed',
tip: '该波次已领料,无需重复领取',
},
code: 200,
});
}
// 波次打印校验:存在未打印订单(print_status != fin)时禁止整波领料
const unprintedOrderIds = [ ...new Set(waveOrders
.filter(item => String(item && item.print_status || '') !== 'fin')
.map(item => Number(item && item.id || 0))
.filter(id => Number.isInteger(id) && id > 0)) ];
if (unprintedOrderIds.length > 0) {
return this.fail('波次未打印,禁止领料', {
...baseResponse,
unprinted_order_count: unprintedOrderIds.length,
}, 400);
}
// --- 6. 事务更新领单状态并写订单日志 ---
const operationLogService = ctx.service
&& ctx.service.systems
&& ctx.service.systems.operationLog;
const transaction = await ctx.model.transaction();
try {
await orderModel.update(
{ claim_status: 'fin' },
{
where: {
id: { [Op.in]: unclaimedOrderIds },
warehouse_id: normalizedWarehouseId,
claim_status: { [Op.ne]: 'fin' },
},
transaction,
}
);
const claimedRows = await orderModel.findAll({
where: {
id: { [Op.in]: unclaimedOrderIds },
warehouse_id: normalizedWarehouseId,
claim_status: 'fin',
},
attributes: [ 'id' ],
raw: true,
transaction,
});
const claimedOrderIds = [ ...new Set((Array.isArray(claimedRows) ? claimedRows : [])
.map(item => Number(item && item.id || 0))
.filter(id => Number.isInteger(id) && id > 0)) ];
if (claimedOrderIds.length > 0
&& operationLogService
&& typeof operationLogService.createOperationLogs === 'function') {
await operationLogService.createOperationLogs(claimedOrderIds.map(orderId => ({
businessType: 'order',
businessId: `${orderId}`,
operationCode: 'ORDER_WAVE_CLAIM',
operator: {
id: operatorId ? String(operatorId) : null,
name: operatorName || 'system',
},
operationAction: 'UPDATE',
extras: {
message: `整波领单完成(波次 ${targetWaveNo})`,
warehouseId: normalizedWarehouseId,
externalLogType: 'API',
},
})), { transaction });
}
await transaction.commit();
return this.success('ok', {
data: {
...baseResponse,
claimed_order_count: claimedOrderIds.length,
status: 'claimed',
tip: `整波领单完成,本次领取 ${claimedOrderIds.length} 个订单`,
},
code: 200,
});
} catch (error) {
await transaction.rollback();
ctx.logger.error('[PickService.waveClaimScan] 整波领单失败: %s', error && error.message ? error.message : error);
return this.fail('领单失败', {}, 500);
}
}
}
module.exports = PickService;