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:
liufumingren 2026-10-23 22:35:08 +08:00
parent dc53058598
commit 5675e24225
5 changed files with 404 additions and 34 deletions

File diff suppressed because one or more lines are too long

View File

@ -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} 个订单`,
},

View File

@ -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",

View File

@ -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": [

View 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);
});