fix(pick): 领料跳过拦截单按打印状态区分,已打印拦截单照常领料并补写 claim_time(0.3.304)
- waveClaimScan:仅未打印(print_status != fin)的拦截订单跳过领料;已打印的拦截订单面单实物已流出,照常置为已领料并写 ORDER_WAVE_CLAIM 日志,响应新增 intercept_skipped_order_count / claimed_intercepted_order_count - waveClaimScan:already_claimed 幂等分支在波次 claim_time 为空时补写领料时间,修复 order.wave.confirmPrintUnclaimedWaveCount 长期把已领料波次计为「已打印未领料」 - getWaveClaimGateStats:已打印的拦截订单仍需领料登记,未领料时阻隔创建拣货任务 - 新增 script/backfill-wave-claim-status.cjs 存量订正脚本(默认 dry-run,自动定位待处理/配送/历史/委托外仓分表,幂等) - 同步 methods/system.json、methods/changes/system.json、AI_METHOD_ROUTING.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
parent
dc53058598
commit
5675e24225
File diff suppressed because one or more lines are too long
@ -835,7 +835,8 @@ class PickService extends MainService {
|
||||
}
|
||||
|
||||
// 领料前置校验:source=0 普通波次需整波领料,未领料阻隔创建拣货任务
|
||||
// (拦截订单未领料不阻隔拣货,拦截订单将在任务创建时被剔除)
|
||||
// (未打印的拦截订单未领料不阻隔拣货,拦截订单将在任务创建时被剔除;
|
||||
// 已打印的拦截订单面单实物已流出,仍需先领料登记)
|
||||
if (targetWaveSource === 0) {
|
||||
const claimGatePickMode = await this.getWavePickModeByWaveId(targetWaveId);
|
||||
let claimGateOrderModel = null;
|
||||
@ -1629,9 +1630,10 @@ class PickService extends MainService {
|
||||
* 统计口径:
|
||||
* - total_order_count:波次下全部订单数(含拦截订单);
|
||||
* - intercepted_order_count:拦截订单数(intercept_status != none);
|
||||
* - unclaimed_order_count:非拦截且需要领料的订单数,包括未领料
|
||||
* - unclaimed_order_count:需要领料的订单数,包括未领料
|
||||
* (claim_status != fin)与已领料但领料人非本人(claim_operator_id != 操作人)两种;
|
||||
* 拦截订单不阻隔拣货,不计入该数量。
|
||||
* 未打印的拦截订单不阻隔拣货,不计入该数量;已打印(print_status=fin)的拦截订单
|
||||
* 面单实物已流出,仍需领料登记,计入该数量。
|
||||
*
|
||||
* @param {Object} params 统计参数。
|
||||
* @param {Object} params.orderModel 订单分表模型。
|
||||
@ -1661,7 +1663,7 @@ class PickService extends MainService {
|
||||
warehouse_id: warehouseId,
|
||||
wave_id: waveId,
|
||||
},
|
||||
attributes: [ 'id', 'claim_status', 'intercept_status', 'claim_operator_id' ],
|
||||
attributes: [ 'id', 'claim_status', 'intercept_status', 'claim_operator_id', 'print_status' ],
|
||||
raw: true,
|
||||
});
|
||||
rows = Array.isArray(rows) ? rows : [];
|
||||
@ -1672,7 +1674,7 @@ class PickService extends MainService {
|
||||
warehouse_id: warehouseId,
|
||||
wave_no: waveNo,
|
||||
},
|
||||
attributes: [ 'id', 'claim_status', 'intercept_status', 'claim_operator_id' ],
|
||||
attributes: [ 'id', 'claim_status', 'intercept_status', 'claim_operator_id', 'print_status' ],
|
||||
raw: true,
|
||||
});
|
||||
rows = Array.isArray(fallbackRows) ? fallbackRows : [];
|
||||
@ -1685,10 +1687,16 @@ class PickService extends MainService {
|
||||
.filter(item => isInterceptedOrderStatus(item && item.intercept_status))
|
||||
.map(item => Number(item && item.id || 0))
|
||||
.filter(id => Number.isInteger(id) && id > 0));
|
||||
// 仅未打印的拦截订单免领料;已打印的拦截订单面单实物已流出,仍需领料登记
|
||||
const interceptClaimSkippedOrderIds = new Set(rows
|
||||
.filter(item => interceptedOrderIds.has(Number(item && item.id || 0))
|
||||
&& String(item && item.print_status || '').trim() !== 'fin')
|
||||
.map(item => Number(item && item.id || 0))
|
||||
.filter(id => Number.isInteger(id) && id > 0));
|
||||
const unclaimedOrderCount = rows
|
||||
.filter(item => {
|
||||
const orderIdItem = Number(item && item.id || 0);
|
||||
if (!orderIds.includes(orderIdItem) || interceptedOrderIds.has(orderIdItem)) {
|
||||
if (!orderIds.includes(orderIdItem) || interceptClaimSkippedOrderIds.has(orderIdItem)) {
|
||||
return false;
|
||||
}
|
||||
if (String(item && item.claim_status || '') !== 'fin') {
|
||||
@ -1706,6 +1714,75 @@ class PickService extends MainService {
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 递增「确认打印未领单波次」统计版本号(失败仅记录 warn,不影响主流程)。
|
||||
*
|
||||
* @param {number} warehouseId 仓库ID。
|
||||
* @return {Promise<void>} 无返回值。
|
||||
*/
|
||||
async bumpConfirmPrintUnclaimedWaveVersionSafe(warehouseId) {
|
||||
const { ctx } = this;
|
||||
try {
|
||||
const waveService = ctx.service
|
||||
&& ctx.service.systemMethods
|
||||
&& ctx.service.systemMethods.order
|
||||
&& ctx.service.systemMethods.order.wave;
|
||||
if (waveService && typeof waveService.bumpConfirmPrintUnclaimedWaveVersion === 'function') {
|
||||
await waveService.bumpConfirmPrintUnclaimedWaveVersion(warehouseId);
|
||||
}
|
||||
} catch (error) {
|
||||
ctx.logger.warn('[PickService.waveClaimScan] 统计版本号递增失败: %s',
|
||||
error && error.message ? error.message : error);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 补写波次领料时间。
|
||||
*
|
||||
* 场景:波次下订单已全部领料(claim_status=fin),但波次表 claim_time 为空
|
||||
* (历史领单发生在 claim_time 字段之前,或旧版拦截逻辑跳过领料导致整波未写领料时间)。
|
||||
* 此时 order.wave.confirmPrintUnclaimedWaveCount 以波次表 claim_time 判定未领单,
|
||||
* 会长期把该波次计为「已打印未领料」;而重复扫描领料只会返回 already_claimed,
|
||||
* 不会补记,故在幂等分支补写一次领料时间。
|
||||
*
|
||||
* @param {Object} params 参数。
|
||||
* @param {number} params.waveId 波次ID。
|
||||
* @param {number} params.warehouseId 仓库ID。
|
||||
* @param {string} params.operatorName 领料人。
|
||||
* @param {*} params.currentClaimTime 波次当前领料时间(非空则不补写)。
|
||||
* @return {Promise<boolean>} 是否补写成功。
|
||||
*/
|
||||
async backfillWaveClaimTime(params = {}) {
|
||||
const { ctx } = this;
|
||||
const waveId = Number(params.waveId || 0);
|
||||
const warehouseId = Number(params.warehouseId || 0);
|
||||
const operatorName = String(params.operatorName || '').trim() || 'system';
|
||||
if (!(waveId > 0) || !(warehouseId > 0) || params.currentClaimTime) {
|
||||
return false;
|
||||
}
|
||||
try {
|
||||
const updateResult = await ctx.model.WaveBatch.update(
|
||||
{
|
||||
claim_operator: operatorName,
|
||||
claim_time: new Date(),
|
||||
},
|
||||
{
|
||||
where: {
|
||||
wave_id: waveId,
|
||||
warehouse_id: warehouseId,
|
||||
claim_time: null,
|
||||
},
|
||||
}
|
||||
);
|
||||
const affectedRows = Number(Array.isArray(updateResult) ? updateResult[0] : updateResult) || 0;
|
||||
return affectedRows > 0;
|
||||
} catch (error) {
|
||||
ctx.logger.warn('[PickService.backfillWaveClaimTime] 波次领料时间补写失败: %s',
|
||||
error && error.message ? error.message : error);
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 扫描面单号领取整波(领料)。
|
||||
*
|
||||
@ -1718,9 +1795,12 @@ class PickService extends MainService {
|
||||
* 波次下存在未打印订单(print_status != fin,拦截订单除外)时禁止领料,
|
||||
* 返回 400 并提示「波次未打印,禁止领料」(失败 data 含 wave_id、wave_no、unprinted_order_count、
|
||||
* intercepted_order_count,拦截订单未打印不阻隔领料);
|
||||
* 拦截订单整体跳过领料:既不置为领料完成,其未打印状态也不阻隔整波领料。
|
||||
* 拦截订单跳过领料的口径按打印状态区分:未打印的拦截订单跳过领料(不置为 fin,其未打印状态也不阻隔整波领料);
|
||||
* 已打印(print_status=fin)的拦截订单面单实物已随波次流出并被领取,照常置为领料完成,不再受拦截影响。
|
||||
* 其余未知类型返回通用不支持提示。
|
||||
* 波次内订单已全部领单时返回 already_claimed 幂等结果并提示已领料。
|
||||
* 波次内订单已全部领单时返回 already_claimed 幂等结果并提示已领料;此时若波次表
|
||||
* claim_time 为空(历史领单/旧版拦截跳过导致),补写一次领料时间,避免
|
||||
* order.wave.confirmPrintUnclaimedWaveCount 长期把该波次计为「已打印未领料」。
|
||||
*
|
||||
* @param {Object} data 请求参数。
|
||||
* @param {string} data.waybill_no 面单号(运单号,wms_order_express.waybill_code)。
|
||||
@ -1800,7 +1880,7 @@ class PickService extends MainService {
|
||||
let waveRows = [];
|
||||
if (orderWaveId > 0) {
|
||||
waveRows = await ctx.model.query(
|
||||
`SELECT wave_id, wave_no, wave_type, source
|
||||
`SELECT wave_id, wave_no, wave_type, source, claim_time
|
||||
FROM wms_wave_batch
|
||||
WHERE warehouse_id = :warehouseId
|
||||
AND wave_id = :waveId
|
||||
@ -1815,7 +1895,7 @@ class PickService extends MainService {
|
||||
);
|
||||
} else {
|
||||
waveRows = await ctx.model.query(
|
||||
`SELECT wave_id, wave_no, wave_type, source
|
||||
`SELECT wave_id, wave_no, wave_type, source, claim_time
|
||||
FROM wms_wave_batch
|
||||
WHERE warehouse_id = :warehouseId
|
||||
AND wave_no = :waveNo
|
||||
@ -1838,6 +1918,7 @@ class PickService extends MainService {
|
||||
const targetWaveNo = String(waveRow.wave_no || '').trim();
|
||||
const targetWaveType = Number(waveRow.wave_type || 0);
|
||||
const targetWaveSource = Number(waveRow.source || 0);
|
||||
const targetWaveClaimTime = waveRow.claim_time || null;
|
||||
if (!(targetWaveId > 0) || !targetWaveNo) {
|
||||
return this.fail('目标波次信息不完整', {}, 400);
|
||||
}
|
||||
@ -1896,16 +1977,23 @@ class PickService extends MainService {
|
||||
}
|
||||
|
||||
const totalOrderCount = waveOrderIds.length;
|
||||
// 拦截订单整体跳过领料:不参与领取(保持未领料),其未打印/未领料状态也不阻隔领料与拣货
|
||||
// 拦截订单跳过领料的口径:仅「未打印」的拦截订单跳过(保持未领料),其未打印/未领料状态不阻隔领料与拣货;
|
||||
// 已打印(print_status=fin)的拦截订单面单实物已随波次流出并被领取,领料登记不再受拦截影响,
|
||||
// 否则会出现实物已领走但订单仍未领料(波次已确认打印后又收到拦截的场景)。
|
||||
const interceptedWaveOrderIds = new Set(waveOrders
|
||||
.filter(item => isInterceptedOrderStatus(item && item.intercept_status))
|
||||
.map(item => Number(item && item.id || 0))
|
||||
.filter(id => Number.isInteger(id) && id > 0));
|
||||
const interceptClaimSkippedOrderIds = new Set(waveOrders
|
||||
.filter(item => interceptedWaveOrderIds.has(Number(item && item.id || 0))
|
||||
&& String(item && item.print_status || '').trim() !== 'fin')
|
||||
.map(item => Number(item && item.id || 0))
|
||||
.filter(id => Number.isInteger(id) && id > 0));
|
||||
|
||||
const unclaimedOrderIds = [ ...new Set(waveOrders
|
||||
.filter(item => {
|
||||
const orderIdItem = Number(item && item.id || 0);
|
||||
if (interceptedWaveOrderIds.has(orderIdItem)) {
|
||||
if (interceptClaimSkippedOrderIds.has(orderIdItem)) {
|
||||
return false;
|
||||
}
|
||||
if (String(item && item.claim_status || '') !== 'fin') {
|
||||
@ -1920,7 +2008,7 @@ class PickService extends MainService {
|
||||
const ownClaimedOrderIds = [ ...new Set(waveOrders
|
||||
.filter(item => String(item && item.claim_status || '') === 'fin'
|
||||
&& Number(item && item.claim_operator_id || 0) === operatorId
|
||||
&& !interceptedWaveOrderIds.has(Number(item && item.id || 0)))
|
||||
&& !interceptClaimSkippedOrderIds.has(Number(item && item.id || 0)))
|
||||
.map(item => Number(item && item.id || 0))
|
||||
.filter(id => Number.isInteger(id) && id > 0)) ];
|
||||
|
||||
@ -1934,13 +2022,30 @@ class PickService extends MainService {
|
||||
waybill_no: waybillNo,
|
||||
total_order_count: totalOrderCount,
|
||||
intercepted_order_count: interceptedWaveOrderIds.size,
|
||||
intercept_skipped_order_count: interceptClaimSkippedOrderIds.size,
|
||||
};
|
||||
|
||||
if (unclaimedOrderIds.length === 0) {
|
||||
// 波次已领料(本人):若波次表缺少领料时间(历史领单或旧版拦截跳过导致),
|
||||
// 补写一次,避免 order.wave.confirmPrintUnclaimedWaveCount 长期把该波次计为未领料
|
||||
const backfilled = ownClaimedOrderIds.length > 0
|
||||
? await this.backfillWaveClaimTime({
|
||||
waveId: targetWaveId,
|
||||
warehouseId: normalizedWarehouseId,
|
||||
operatorName,
|
||||
currentClaimTime: targetWaveClaimTime,
|
||||
})
|
||||
: false;
|
||||
if (backfilled) {
|
||||
await this.bumpConfirmPrintUnclaimedWaveVersionSafe(normalizedWarehouseId);
|
||||
}
|
||||
|
||||
return this.success('ok', {
|
||||
data: {
|
||||
...baseResponse,
|
||||
claimed_order_count: ownClaimedOrderIds.length,
|
||||
claimed_intercepted_order_count: ownClaimedOrderIds
|
||||
.filter(orderId => interceptedWaveOrderIds.has(orderId)).length,
|
||||
status: 'already_claimed',
|
||||
tip: '该波次订单已领料(本人),无需重复领取',
|
||||
},
|
||||
@ -2036,23 +2141,14 @@ class PickService extends MainService {
|
||||
await transaction.commit();
|
||||
|
||||
// 驱动确认打印未领单波次统计长轮询:领单会减少未领单波次数量,递增版本号
|
||||
try {
|
||||
const waveService = ctx.service
|
||||
&& ctx.service.systemMethods
|
||||
&& ctx.service.systemMethods.order
|
||||
&& ctx.service.systemMethods.order.wave;
|
||||
if (waveService && typeof waveService.bumpConfirmPrintUnclaimedWaveVersion === 'function') {
|
||||
await waveService.bumpConfirmPrintUnclaimedWaveVersion(normalizedWarehouseId);
|
||||
}
|
||||
} catch (error) {
|
||||
ctx.logger.warn('[PickService.waveClaimScan] 统计版本号递增失败: %s',
|
||||
error && error.message ? error.message : error);
|
||||
}
|
||||
await this.bumpConfirmPrintUnclaimedWaveVersionSafe(normalizedWarehouseId);
|
||||
|
||||
return this.success('ok', {
|
||||
data: {
|
||||
...baseResponse,
|
||||
claimed_order_count: claimedOrderIds.length,
|
||||
claimed_intercepted_order_count: claimedOrderIds
|
||||
.filter(orderId => interceptedWaveOrderIds.has(orderId)).length,
|
||||
status: 'claimed',
|
||||
tip: `整波领单完成,本次领取 ${claimedOrderIds.length} 个订单`,
|
||||
},
|
||||
|
||||
@ -1,4 +1,24 @@
|
||||
[
|
||||
{
|
||||
"version": "0.3.304",
|
||||
"date": "2026-10-23",
|
||||
"type": "updated",
|
||||
"summary": "pick.waveClaimScan 领料跳过拦截单改为按打印状态区分:已打印(print_status=fin)的拦截订单面单实物已流出,不再受拦截影响、照常置为已领料;仅未打印的拦截订单跳过领料(0.3.303 → 0.3.304)",
|
||||
"methods": [
|
||||
"pick.waveClaimScan",
|
||||
"pick.query",
|
||||
"order.wave.confirmPrintUnclaimedWaveCount"
|
||||
],
|
||||
"notes": [
|
||||
"变更内容一(领料口径):waveClaimScan 计算待领料订单时,拦截订单由「整体跳过」改为「仅未打印(print_status != fin)的拦截订单跳过」;已打印(print_status=fin)的拦截订单纳入领料范围并写 ORDER_WAVE_CLAIM 日志,响应新增 intercept_skipped_order_count(因拦截且未打印跳过领料的订单数)与 claimed_intercepted_order_count(本次/本人已领的已打印拦截订单数);getWaveClaimGateStats(pick.query 领料门禁)同步按该口径统计,已打印的拦截订单未领料时阻隔建拣货任务。",
|
||||
"变更内容二(领料时间补写):waveClaimScan 命中 already_claimed 幂等分支时,若波次表 claim_time 为空则补写 claim_time + claim_operator 并递增统计版本号;旧逻辑下「整波订单均被拦截跳过」或历史领单发生在 claim_time 字段之前时,波次表永远没有领料时间,order.wave.confirmPrintUnclaimedWaveCount(以 wb.claim_time IS NULL 判定未领单)会长期显示该波次「已打印未领单」,且重复扫描领料只返回 already_claimed 无法自愈。",
|
||||
"背景:生产订单 1314391 所在波次已确认打印后被写入拦截,操作员扫描面单领料时该订单被拦截逻辑跳过、未置为已领料,但面单实物已打印并被领走;打印与领料之间不存在拦截出库流程,已打印订单不应再受拦截影响。同一波次在「确认打印未领单」统计中一直显示为 1,需重新扫描后自愈。",
|
||||
"代码依据:app/service/systemMethods/pick.js#waveClaimScan(新增 interceptClaimSkippedOrderIds,unclaimed/ownClaimed 与响应统计按新口径;already_claimed 分支调用 backfillWaveClaimTime 并复用 bumpConfirmPrintUnclaimedWaveVersionSafe)、#backfillWaveClaimTime、#bumpConfirmPrintUnclaimedWaveVersionSafe、#getWaveClaimGateStats(查询补 print_status,仅未打印拦截订单免领料);新增单测 test/app/service/systemMethods/pick.waveClaimScan.test.js(WC1~WC5,5 通过)。",
|
||||
"验证:npx egg-bin test test/app/service/systemMethods/pick.waveClaimScan.test.js 5 通过;ESLint 0 错误;pick.query.test.js / pick.createWavePickTask.test.js 的失败为改动前既有失败(stash 基线同样失败)。",
|
||||
"存量处理:受影响波次重新扫一次波次内已打印面单号即可自动补领料与 claim_time;若订单已迁出待处理订单表,需按仓库分表人工订正 claim_status/claim_time。",
|
||||
"文档变更范围:methods/system.json 的 pick.waveClaimScan(description、intercepted_order_count、新增 intercept_skipped_order_count / claimed_intercepted_order_count)、pick.query(description、400 错误说明)与 order.wave.confirmPrintUnclaimedWaveCount(description 补补写说明);根版本 0.3.303 → 0.3.304、updatedAt 2026-10-23;methods/changes/system.json 新增本条(插入数组首位)。"
|
||||
]
|
||||
},
|
||||
{
|
||||
"version": "2026.10.21-order-delivery-summary",
|
||||
"date": "2026-10-21",
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
{
|
||||
"module": "system",
|
||||
"description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内",
|
||||
"version": "0.3.303",
|
||||
"updatedAt": "2026-10-21",
|
||||
"version": "0.3.304",
|
||||
"updatedAt": "2026-10-23",
|
||||
"headers": [
|
||||
{
|
||||
"name": "platform",
|
||||
@ -21134,7 +21134,7 @@
|
||||
"list": [
|
||||
{
|
||||
"method": "pick.query",
|
||||
"description": "按 keyword(运单号或波次号)获取或创建当前用户的拣货任务:命中同用户活动任务返回 existing;无活动任务则创建并返回 created;若活动任务归属他人则返回冲突提示。新增领单前置校验:扫描命中的波次属于普通波次(wms_wave_batch.source=0)时,若波次内存在未领料订单(claim_status != fin,拦截订单除外)则返回 400 并携带 action=wave_claim 提示「订单未领料,请先领料后再拣货」(pick.waveClaimScan),中止拣货任务创建;拦截订单未领料不阻隔拣货,且创建任务计算拣货数量时剔除未领料订单(拦截订单也不入任务)。",
|
||||
"description": "按 keyword(运单号或波次号)获取或创建当前用户的拣货任务:命中同用户活动任务返回 existing;无活动任务则创建并返回 created;若活动任务归属他人则返回冲突提示。新增领单前置校验:扫描命中的波次属于普通波次(wms_wave_batch.source=0)时,若波次内存在未领料订单(claim_status != fin)则返回 400 并携带 action=wave_claim 提示「订单未领料,请先领料后再拣货」(pick.waveClaimScan),中止拣货任务创建;未打印的拦截订单未领料不阻隔拣货,已打印(print_status=fin)的拦截订单面单实物已流出、仍需先领料登记;创建任务计算拣货数量时剔除未领料订单(拦截订单也不入任务)。",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [
|
||||
@ -21177,7 +21177,7 @@
|
||||
"errors": [
|
||||
{
|
||||
"code": 400,
|
||||
"message": "参数错误或目标波次不满足建任务条件(如 keyword 为空、缺少仓库上下文、目标波次信息不完整、散单波次无可用订单);普通波次(source=0)存在非拦截未领料订单时中止建任务并提示「订单未领料,请先领料后再拣货」(失败 data 含 action=wave_claim、wave_id、wave_no、wave_type、wave_source、pick_mode、unclaimed_order_count、intercepted_order_count、total_order_count,拦截订单未领料不阻隔)。"
|
||||
"message": "参数错误或目标波次不满足建任务条件(如 keyword 为空、缺少仓库上下文、目标波次信息不完整、散单波次无可用订单);普通波次(source=0)存在需要领料但未领料的订单时中止建任务并提示「订单未领料,请先领料后再拣货」(失败 data 含 action=wave_claim、wave_id、wave_no、wave_type、wave_source、pick_mode、unclaimed_order_count、intercepted_order_count、total_order_count;未打印的拦截订单未领料不阻隔,已打印的拦截订单仍需先领料)。"
|
||||
},
|
||||
{
|
||||
"code": 401,
|
||||
@ -22030,7 +22030,7 @@
|
||||
},
|
||||
{
|
||||
"method": "pick.waveClaimScan",
|
||||
"description": "扫描面单号领取整波(领料)。按面单号(运单号)定位待处理订单表中的订单后反查订单所在波次,仅对普通波次(wms_wave_batch.source=0,含团购/散单)支持整波领料:命中后将该波次下全部未领单订单(拦截订单除外) claim_status 置为 fin(领料完成)并写入 ORDER_WAVE_CLAIM 订单操作日志,返回波次ID与波次编码;波次下存在未打印订单(print_status != fin,拦截订单除外)时返回 400「波次未打印,禁止领料」(data 含 wave_id、wave_no、unprinted_order_count、intercepted_order_count,拦截订单未打印不阻隔领料);拦截订单整体跳过领料(不置为 fin);策略抓取波次(source=1/2)无需领料,返回 400 并提示「该波次为抓取波次,无需领料」(失败 data 含 no_claim_needed=true、wave_id、wave_no);面单号查不到订单或订单不在待处理订单表返回 404 提示无记录;波次内订单已全部领料时返回 already_claimed 幂等结果并提示已领料。",
|
||||
"description": "扫描面单号领取整波(领料)。按面单号(运单号)定位待处理订单表中的订单后反查订单所在波次,仅对普通波次(wms_wave_batch.source=0,含团购/散单)支持整波领料:命中后将该波次下全部未领单订单(未打印的拦截订单除外)claim_status 置为 fin(领料完成)并写入 ORDER_WAVE_CLAIM 订单操作日志,返回波次ID与波次编码;波次下存在未打印订单(print_status != fin,拦截订单除外)时返回 400「波次未打印,禁止领料」(data 含 wave_id、wave_no、unprinted_order_count、intercepted_order_count,拦截订单未打印不阻隔领料);拦截订单跳过领料的口径按打印状态区分:未打印的拦截订单跳过领料(不置为 fin),已打印(print_status=fin)的拦截订单面单实物已随波次流出并被领取,不再受拦截影响、照常置为领料完成;策略抓取波次(source=1/2)无需领料,返回 400 并提示「该波次为抓取波次,无需领料」(失败 data 含 no_claim_needed=true、wave_id、wave_no);面单号查不到订单或订单不在待处理订单表返回 404 提示无记录;波次内订单已全部领料时返回 already_claimed 幂等结果并提示已领料,此时若波次表 claim_time 为空(历史领单/旧版拦截跳过导致)会补写一次领料时间,避免 order.wave.confirmPrintUnclaimedWaveCount 长期把该波次计为「已打印未领料」。",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"isNeedRight": false,
|
||||
@ -22104,7 +22104,13 @@
|
||||
"name": "intercepted_order_count",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "波次下拦截订单数(拦截订单跳过领料,其未打印/未领料状态不阻隔领料与拣货)"
|
||||
"description": "波次下拦截订单数(未打印的拦截订单跳过领料,其未打印/未领料状态不阻隔领料与拣货;已打印的拦截订单照常领料)"
|
||||
},
|
||||
{
|
||||
"name": "intercept_skipped_order_count",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "因处于拦截流程且未打印而跳过领料的订单数"
|
||||
},
|
||||
{
|
||||
"name": "claimed_order_count",
|
||||
@ -22112,6 +22118,12 @@
|
||||
"required": true,
|
||||
"description": "本次置为 fin 的订单数(已全部领料时返回 0)"
|
||||
},
|
||||
{
|
||||
"name": "claimed_intercepted_order_count",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "本次置为 fin 的已打印拦截订单数(已全部领料时返回本人已领的已打印拦截订单数)"
|
||||
},
|
||||
{
|
||||
"name": "status",
|
||||
"type": "string",
|
||||
@ -32711,7 +32723,7 @@
|
||||
},
|
||||
{
|
||||
"method": "order.wave.confirmPrintUnclaimedWaveCount",
|
||||
"description": "快速查询「已确认打印但未领单」的波次数量,使用当前登录操作者仓库上下文。口径(波次表驱动):未领单以 wms_wave_batch.claim_time IS NULL 为准(历史领单发生在波次表增加 claim_time 字段之前时,订单维度 claim_status 可能已是 fin 但波次表无记录,故不用订单 claim_status 判断),已确认打印以波次下存在 confirm_print_status='fin' 的非取消订单为准,仅统计 wave_status 0/1 的波次。支持长轮询(参考扫码登录):不传 last_count 立即返回当前值(status=current);传 last_count 且与当前值不同立即返回新值(status=changed);传 last_count 且与当前值相同则进入等待,每 1 秒检查统计版本号(确认打印/领单成功会递增版本号),最长等待 60 秒:期间变化立即返回新值(status=changed),超时未变化重查后返回当前值(status=timeout)。",
|
||||
"description": "快速查询「已确认打印但未领单」的波次数量,使用当前登录操作者仓库上下文。口径(波次表驱动):未领单以 wms_wave_batch.claim_time IS NULL 为准(历史领单发生在波次表增加 claim_time 字段之前时,订单维度 claim_status 可能已是 fin 但波次表无记录,故不用订单 claim_status 判断),已确认打印以波次下存在 confirm_print_status='fin' 的非取消订单为准,仅统计 wave_status 0/1 的波次;波次下订单均已领料但 claim_time 为空的(历史领单/旧版拦截跳过导致),重新扫描领料时 pick.waveClaimScan 会在 already_claimed 幂等分支补写 claim_time,从而不再被本统计计为未领单。支持长轮询(参考扫码登录):不传 last_count 立即返回当前值(status=current);传 last_count 且与当前值不同立即返回新值(status=changed);传 last_count 且与当前值相同则进入等待,每 1 秒检查统计版本号(确认打印/领单成功会递增版本号),最长等待 60 秒:期间变化立即返回新值(status=changed),超时未变化重查后返回当前值(status=timeout)。",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [
|
||||
|
||||
242
script/backfill-wave-claim-status.cjs
Normal file
242
script/backfill-wave-claim-status.cjs
Normal file
@ -0,0 +1,242 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* 回补「已打印但未领料」存量订单的领料登记(一次性数据订正脚本)。
|
||||
*
|
||||
* 背景:waveClaimScan 曾对拦截订单整体跳过领料,导致「波次已确认打印 → 之后写入拦截 →
|
||||
* 领单扫描」时该订单一直不置 claim_status=fin,但面单实物已打印并被领取。
|
||||
* 代码已修复(已打印的拦截订单照常领料),本脚本用于订正修复前已产生的存量数据。
|
||||
*
|
||||
* 订正内容(幂等):
|
||||
* 1. 订单 claim_status/claim_operator_id/claim_operator 回补为领料完成;
|
||||
* 2. 若波次表 claim_time 为空,回补 claim_time/claim_operator;
|
||||
* 3. 补一条 ORDER_WAVE_CLAIM 操作日志(message 标注「存量数据补记」)。
|
||||
*
|
||||
* 安全约束:
|
||||
* - 默认预览模式,只有显式 --apply 才写入;
|
||||
* - 仅处理 print_status='fin' 且未取消的订单,否则拒绝(--force 可强制);
|
||||
* - 已领料(claim_status='fin')直接跳过,可重复执行;
|
||||
* - 订单可能已迁移进配送表/历史表/委托外仓表,脚本会自动定位所在分表。
|
||||
*
|
||||
* 用法:
|
||||
* node script/backfill-wave-claim-status.cjs --warehouse-id=1000028 --order-id=1314391
|
||||
* node script/backfill-wave-claim-status.cjs --warehouse-id=1000028 --order-id=1314391 --apply
|
||||
*
|
||||
* 可选参数:
|
||||
* --operator-id=65 指定领料人工号(缺省取同波次已领料订单的领料人)
|
||||
* --operator-name=冯城礼 指定领料人姓名
|
||||
* --no-log 不写操作日志
|
||||
* --force 放宽 print_status 校验
|
||||
* --config=<path> 数据库配置(默认 script/db-query-prod-config.js)
|
||||
*/
|
||||
|
||||
const path = require('path');
|
||||
const { createRequire } = require('module');
|
||||
|
||||
const APPLY = process.argv.includes('--apply');
|
||||
const WITH_LOG = !process.argv.includes('--no-log');
|
||||
const FORCE = process.argv.includes('--force');
|
||||
|
||||
/**
|
||||
* 读取 --key=value 形式的命令行参数。
|
||||
* @param {string} key 参数名。
|
||||
* @param {*} [defaultValue] 缺省值。
|
||||
* @return {*} 参数值。
|
||||
*/
|
||||
function getArg(key, defaultValue) {
|
||||
const prefix = `--${key}=`;
|
||||
const hit = process.argv.find(arg => arg.startsWith(prefix));
|
||||
return hit ? hit.slice(prefix.length) : defaultValue;
|
||||
}
|
||||
|
||||
async function main() {
|
||||
const warehouseId = Number(getArg('warehouse-id', 0));
|
||||
const orderId = Number(getArg('order-id', 0));
|
||||
if (!Number.isInteger(warehouseId) || warehouseId <= 0) {
|
||||
throw new Error('缺少合法参数 --warehouse-id');
|
||||
}
|
||||
if (!Number.isInteger(orderId) || orderId <= 0) {
|
||||
throw new Error('缺少合法参数 --order-id');
|
||||
}
|
||||
|
||||
const projectRoot = path.resolve(__dirname, '..');
|
||||
const projectRequire = createRequire(path.join(projectRoot, 'package.json'));
|
||||
const mysql = projectRequire('mysql2/promise');
|
||||
|
||||
const configPath = path.resolve(__dirname, path.basename(getArg('config', 'db-query-prod-config.js')));
|
||||
const cfg = require(configPath);
|
||||
const client = cfg && cfg.mysql && cfg.mysql.clients && cfg.mysql.clients.wms;
|
||||
if (!client) {
|
||||
throw new Error(`未找到 mysql clients.wms 配置: ${configPath}`);
|
||||
}
|
||||
|
||||
const conn = await mysql.createConnection({
|
||||
host: client.host,
|
||||
port: Number(client.port),
|
||||
user: client.user,
|
||||
password: client.password,
|
||||
database: client.database,
|
||||
charset: client.charset || 'utf8mb4',
|
||||
});
|
||||
|
||||
const orderTableBase = `wms_order_delivery_${warehouseId}`;
|
||||
// 订单可能已迁移进配送表/历史表,按 待处理 → 配送 → 历史 → 委托外仓 顺序定位
|
||||
const orderTableCandidates = [
|
||||
orderTableBase,
|
||||
`${orderTableBase}_dispatch`,
|
||||
`${orderTableBase}_history`,
|
||||
`${orderTableBase}_outsourced`,
|
||||
];
|
||||
|
||||
try {
|
||||
let orderTable = null;
|
||||
let order = null;
|
||||
for (const table of orderTableCandidates) {
|
||||
try {
|
||||
const [ rows ] = await conn.query(
|
||||
`SELECT id, warehouse_id, wave_id, wave_no, claim_status, claim_operator_id, claim_operator,
|
||||
print_status, confirm_print_status, intercept_status, status
|
||||
FROM ${table}
|
||||
WHERE warehouse_id = ? AND id = ?`,
|
||||
[ warehouseId, orderId ]
|
||||
);
|
||||
if (rows.length > 0) {
|
||||
orderTable = table;
|
||||
order = rows[0];
|
||||
break;
|
||||
}
|
||||
} catch (error) {
|
||||
// 分表可能不存在,继续找下一张
|
||||
}
|
||||
}
|
||||
if (!order) {
|
||||
throw new Error(`订单不存在: ${orderTableCandidates.join(' / ')} id=${orderId}`);
|
||||
}
|
||||
|
||||
console.log('订单所在表:', orderTable);
|
||||
console.log('订单现状:', JSON.stringify(order));
|
||||
if (order.status === 'cancel') {
|
||||
throw new Error('订单已取消,不处理');
|
||||
}
|
||||
if (String(order.claim_status || '') === 'fin') {
|
||||
console.log('订单已是已领料(claim_status=fin),无需处理');
|
||||
return;
|
||||
}
|
||||
if (String(order.print_status || '') !== 'fin' && !FORCE) {
|
||||
throw new Error(`订单未打印(print_status=${order.print_status}),拒绝订正;如确认需要请加 --force`);
|
||||
}
|
||||
|
||||
const [ waveRows ] = await conn.query(
|
||||
`SELECT wave_id, wave_no, claim_operator, claim_time
|
||||
FROM wms_wave_batch
|
||||
WHERE warehouse_id = ? AND wave_id = ?`,
|
||||
[ warehouseId, Number(order.wave_id || 0) ]
|
||||
);
|
||||
const wave = waveRows[0] || null;
|
||||
if (!wave) {
|
||||
throw new Error(`波次不存在: warehouse_id=${warehouseId} wave_id=${order.wave_id}`);
|
||||
}
|
||||
console.log('波次现状:', JSON.stringify(wave));
|
||||
|
||||
let operatorId = Number(getArg('operator-id', 0)) || 0;
|
||||
let operatorName = String(getArg('operator-name', '') || '').trim();
|
||||
if (!operatorId || !operatorName) {
|
||||
const [ siblingRows ] = await conn.query(
|
||||
`SELECT claim_operator_id, claim_operator, COUNT(*) AS claimed_count
|
||||
FROM ${orderTable}
|
||||
WHERE warehouse_id = ? AND wave_id = ? AND claim_status = 'fin'
|
||||
AND claim_operator_id IS NOT NULL
|
||||
GROUP BY claim_operator_id, claim_operator
|
||||
ORDER BY claimed_count DESC
|
||||
LIMIT 1`,
|
||||
[ warehouseId, Number(wave.wave_id || 0) ]
|
||||
);
|
||||
const sibling = siblingRows[0] || null;
|
||||
if (sibling) {
|
||||
operatorId = operatorId || Number(sibling.claim_operator_id || 0);
|
||||
operatorName = operatorName || String(sibling.claim_operator || '').trim();
|
||||
}
|
||||
if (!operatorName) {
|
||||
operatorName = String(wave.claim_operator || '').trim();
|
||||
}
|
||||
}
|
||||
if (!operatorName) {
|
||||
throw new Error('无法确定领料人,请通过 --operator-name 指定');
|
||||
}
|
||||
console.log('将回补领料人:', JSON.stringify({ operator_id: operatorId || null, operator_name: operatorName }));
|
||||
|
||||
const [ beforeLogs ] = await conn.query(
|
||||
`SELECT id FROM wms_operation_log
|
||||
WHERE business_type = 'order' AND business_id = ? AND operation_code = 'ORDER_WAVE_CLAIM'
|
||||
LIMIT 1`,
|
||||
[ String(orderId) ]
|
||||
);
|
||||
const hasClaimLog = beforeLogs.length > 0;
|
||||
console.log('已有 ORDER_WAVE_CLAIM 日志:', hasClaimLog);
|
||||
|
||||
if (!APPLY) {
|
||||
console.log('');
|
||||
console.log('==== 预览(加 --apply 执行) ====');
|
||||
console.log(`UPDATE ${orderTable} SET claim_status='fin', claim_operator_id=${operatorId || 'NULL'}, claim_operator='${operatorName}' WHERE id=${orderId}`);
|
||||
if (!wave.claim_time) {
|
||||
console.log(`UPDATE wms_wave_batch SET claim_operator='${operatorName}', claim_time=NOW() WHERE wave_id=${wave.wave_id} AND claim_time IS NULL`);
|
||||
}
|
||||
if (WITH_LOG && !hasClaimLog) {
|
||||
console.log(`INSERT wms_operation_log (order ${orderId}, ORDER_WAVE_CLAIM, ${operatorName})`);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
await conn.beginTransaction();
|
||||
try {
|
||||
const [ updateResult ] = await conn.query(
|
||||
`UPDATE ${orderTable}
|
||||
SET claim_status = 'fin', claim_operator_id = ?, claim_operator = ?
|
||||
WHERE warehouse_id = ? AND id = ? AND claim_status <> 'fin'`,
|
||||
[ operatorId > 0 ? operatorId : null, operatorName, warehouseId, orderId ]
|
||||
);
|
||||
console.log('订单更新行数:', updateResult.affectedRows);
|
||||
|
||||
if (!wave.claim_time) {
|
||||
const [ waveUpdateResult ] = await conn.query(
|
||||
`UPDATE wms_wave_batch
|
||||
SET claim_operator = ?, claim_time = NOW()
|
||||
WHERE warehouse_id = ? AND wave_id = ? AND claim_time IS NULL`,
|
||||
[ operatorName, warehouseId, Number(wave.wave_id || 0) ]
|
||||
);
|
||||
console.log('波次领料时间补写行数:', waveUpdateResult.affectedRows);
|
||||
}
|
||||
|
||||
if (WITH_LOG && !hasClaimLog) {
|
||||
const [ logResult ] = await conn.query(
|
||||
`INSERT INTO wms_operation_log
|
||||
(business_type, business_id, operation_code, operator_id, operator_name,
|
||||
external_log_type, external_log_id, warehouse_id, before_changes, platform_code, message)
|
||||
VALUES ('order', ?, 'ORDER_WAVE_CLAIM', ?, ?, 'NONE', NULL, ?, NULL, 'SYSTEM', ?)`,
|
||||
[
|
||||
String(orderId),
|
||||
operatorId > 0 ? String(operatorId) : null,
|
||||
operatorName,
|
||||
warehouseId,
|
||||
`存量数据补记:整波领单完成(波次 ${wave.wave_no || order.wave_no})`,
|
||||
]
|
||||
);
|
||||
console.log('操作日志写入 id:', logResult.insertId);
|
||||
}
|
||||
|
||||
await conn.commit();
|
||||
console.log('');
|
||||
console.log('==== 已执行完成 ====');
|
||||
} catch (error) {
|
||||
await conn.rollback();
|
||||
throw error;
|
||||
}
|
||||
} finally {
|
||||
await conn.end();
|
||||
}
|
||||
}
|
||||
|
||||
main().catch(err => {
|
||||
console.error('领料存量回补失败:', err.message);
|
||||
process.exit(1);
|
||||
});
|
||||
Loading…
x
Reference in New Issue
Block a user