From 5675e2422559dc0b3ab4923078c789c15c6bfbd4 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Fri, 23 Oct 2026 22:35:08 +0800 Subject: [PATCH] =?UTF-8?q?fix(pick):=20=E9=A2=86=E6=96=99=E8=B7=B3?= =?UTF-8?q?=E8=BF=87=E6=8B=A6=E6=88=AA=E5=8D=95=E6=8C=89=E6=89=93=E5=8D=B0?= =?UTF-8?q?=E7=8A=B6=E6=80=81=E5=8C=BA=E5=88=86=EF=BC=8C=E5=B7=B2=E6=89=93?= =?UTF-8?q?=E5=8D=B0=E6=8B=A6=E6=88=AA=E5=8D=95=E7=85=A7=E5=B8=B8=E9=A2=86?= =?UTF-8?q?=E6=96=99=E5=B9=B6=E8=A1=A5=E5=86=99=20claim=5Ftime=EF=BC=880.3?= =?UTF-8?q?.304=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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> --- AI_METHOD_ROUTING.md | 4 +- app/service/systemMethods/pick.js | 146 +++++++++++++--- methods/changes/system.json | 20 +++ methods/system.json | 26 ++- script/backfill-wave-claim-status.cjs | 242 ++++++++++++++++++++++++++ 5 files changed, 404 insertions(+), 34 deletions(-) create mode 100644 script/backfill-wave-claim-status.cjs diff --git a/AI_METHOD_ROUTING.md b/AI_METHOD_ROUTING.md index ef8ba37..43fac5d 100644 --- a/AI_METHOD_ROUTING.md +++ b/AI_METHOD_ROUTING.md @@ -476,8 +476,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - buildBatchAllocateExpressTraceId, buildOrderOperationLogRows, batchCreateOrderOperationLogs, buildMachineStructureToken, parseMachineStructureToken, getOrderItemPart, getDefaultWaveQuantity, getMinGroupOrderFetchQuantity, getGroupWavePrefix, getSingleFetchByIdsWavePrefix, getWarehouseSubjectConfig, getWarehouseSubjectConfigValue, normalizeFetchStructureRequests, generateWaveId, getCurrentDatePart, getNextWaveNoSequence, buildWaveNo, getWaveCreator, extractInsertId, extractLastInsertId, isDuplicateEntryError, resolveWaveScopeByWaveMeta, createWaveBatchReady, buildFetchWhere, fetchSingleStructure, normalizeBoolean, normalizePositiveInteger, normalizeRequiredPositiveInteger, normalizeIdsInput, normalizePagination, normalizeWaveStatusList, normalizeBatchListStorageAssignmentStatusFilter, normalizeBatchListExpressAssignmentStatusFilter, normalizeBatchListPrintAssignmentStatusFilter, normalizeBatchListConfirmPrintAssignmentStatusFilter, normalizeBatchListClaimAssignmentStatusFilter, normalizeBatchListReviewAssignmentStatusFilter, normalizeBatchListSyncAssignmentStatusFilter, getBatchListAssignmentFilterSchema, normalizeBatchListAssignmentStatusFilterByType, normalizeBatchListAssignmentStatusFilter, getModelTableSqlName, buildBatchListStorageAssignmentFilterClause, buildBatchListExpressAssignmentFilterClause, buildBatchListPrintAssignmentFilterClause, buildBatchListConfirmPrintAssignmentFilterClause, buildBatchListClaimAssignmentFilterClause, buildBatchListReviewAssignmentFilterClause, buildBatchListSyncAssignmentFilterClause, buildBatchListAssignmentStatusFilterClauseByType, buildBatchListAssignmentStatusFilterClause, isEmptyBatchListWhereValue, resolveBatchListFieldCondition, buildBatchListFieldConditionSql, normalizeBatchListDistinguishExpressValue, normalizeBatchListStoreIdCondition, buildBatchListWhereClause, normalizeWavePickTaskListPagination, normalizeWavePickTaskListRequest, buildWavePickTaskListWhereClause, resolveAssignmentStatus, normalizeSkuText, normalizeShopName, parseItemSnapshot, normalizeOrderItemRow, mergeOrderItemDetails, buildItemSummary, buildOrderItemSnapshot, buildItemSnapshotKey, orderMatchesIncludeSku, buildCoarseGroupKey, buildStatusSummary, buildGroupKey, groupOrderFetchList, singleOrderFetchList, fetchableOrderCount, waveStrategyList, getWaveStrategyNextFetchOrderCountMap, getWaveStrategyDebugFetchOrderListMap, previewWaveStrategyNextFetchOrderCount, getWaveStrategyMatchedOrderCountFilteredMap, getWaveStrategyMatchedOrderCountTotal, waveStrategyCreate, waveStrategyUpdate, bumpWaveStrategyVersionAndInvalidateCache, getWaveStrategyModel, normalizeWaveStrategyId, normalizeWaveStrategyUpsertPayload, normalizeWaveStrategyWavePrefix, resolveWaveStrategyFetchWavePrefix, patchWaveStrategyIntegerField, validateWaveStrategyAllowedOwners, validateWaveStrategyAllowedExpresses, getWaveStrategyAvailableOwnerSet, getWaveStrategyAvailableExpressSet, applyWaveStrategyMaxSameStructureConstraint, normalizeWaveStrategyFallbackOrderListWhere, resolveWaveStrategyFallbackTrackingNo, resolveWaveStrategyFallbackStoreName, resolveWaveStrategyFallbackSysLogisticsName, buildWaveStrategyFallbackOrderListItem, waveStrategyFallbackOrderList, resolveWaveBatchOwnerStoreNameMap, batchList, getConfirmPrintUnclaimedVersionKey, bumpConfirmPrintUnclaimedWaveVersion, getConfirmPrintUnclaimedWaveVersion, queryConfirmPrintUnclaimedWaveCount, confirmPrintScan, confirmPrintUnclaimedWaveCount, wavePickTaskList, batchCancel, batchCancelTaskProgress, batchAllocateExpress, batchAllocateExpressTaskProgress, batchAllocateStorage, batchAllocateStorageTaskProgress, submitWaveStrategyQuickScanForWarehouse, waveStrategyQuickScan, waveStrategyQuickScanTaskProgress, buildWaveStrategyQuickScanOrderWhere, getWaveStrategyQuickScanStrategyRows, getWaveStrategyQuickScanMatchModel, syncWaveStrategyQuickScanMatchedStrategies, cleanupWaveStrategyQuickScanMatchedStrategies, cleanupWaveStrategyQuickScanMatchedStrategiesByOrderIds, enqueueWaveStrategyQuickScanPostOrderChange, executeWaveStrategyQuickScan, runWaveStrategyQuickScanTask, batchUpdateWaveStrategyQuickScanOrders, generateWaveStrategyQuickScanTaskId, normalizeWaveStrategyQuickScanTaskId, getWaveStrategyQuickScanTaskCacheKey, setWaveStrategyQuickScanTaskProgress, getWaveStrategyQuickScanTaskProgress, getWaveStrategyQuickScanWarehouseLockCacheKey, setWaveStrategyQuickScanWarehouseLock, getWaveStrategyQuickScanWarehouseLock, clearWaveStrategyQuickScanWarehouseLock, normalizeWaveStrategyQuickScanVersion, normalizeWaveStrategyQuickScanList, normalizeWaveStrategyQuickScanNumberOrNull, normalizeWaveStrategyQuickScanBoolean, normalizeWaveStrategyQuickScanStringList, getWaveStrategyQuickScanStructureKey, getWaveStrategyQuickScanExpressKey, filterCandidateOrdersByRequireSameExpress, isWaveStrategyQuickScanOrderMatched, getWaveStrategyQuickScanMatchedStrategyIds, isWaveStrategyQuickScanOrderMatchedSingleStrategy, isWaveStrategyQuickScanValueInRange, resolveGroupCandidateOrderIdsForSingleFetch, singleFetchByIds, batchRemoveOrders, resortWaveIndex, batchRemoveExceptionOrders, batchRemoveExceptionOrdersTaskProgress, generateBatchCancelTaskId, normalizeBatchCancelTaskId, generateBatchRemoveExceptionOrdersTaskId, normalizeBatchRemoveExceptionOrdersTaskId, normalizeBatchRemoveExceptionOrdersWaveIds, getBatchRemoveExceptionOrdersTaskCacheKey, setBatchRemoveExceptionOrdersTaskProgress, getBatchRemoveExceptionOrdersTaskProgress, isExceptionRemovableOrder, runBatchRemoveExceptionOrdersTask, normalizeBatchCancelWaveIds, getBatchCancelTaskCacheKey, setBatchCancelTaskProgress, getBatchCancelTaskProgress, runBatchCancelTask, generateBatchAllocateExpressTaskId, normalizeBatchAllocateExpressTaskId, normalizeBatchAllocateExpressWaveIds, getBatchAllocateExpressTaskCacheKey, setBatchAllocateExpressTaskProgress, getBatchAllocateExpressTaskProgress, generateBatchAllocateStorageTaskId, normalizeBatchAllocateStorageTaskId, normalizeBatchAllocateStorageWaveIds, normalizeBatchAllocateStorageTaskCount, buildBatchAllocateStorageRunningProgressPayload, normalizeBatchAllocateStorageOrderIds, getBatchAllocateStorageTaskCacheKey, getBatchAllocateStorageWarehouseLockKey, tryAcquireBatchAllocateStorageWarehouseLock, releaseBatchAllocateStorageWarehouseLock, setBatchAllocateStorageTaskProgress, getBatchAllocateStorageTaskProgress, isMissingBusinessKeyColumnError, runBatchAllocateExpressTask, runBatchAllocateStorageTask, batchAutoGrouping, batchFinishAutoGrouping, generateFetchTaskId, normalizeFetchTaskId, getFetchTaskCacheKey, setFetchTaskProgress, getFetchTaskProgress, fetchTaskProgress, runFetchTask, submitFetchTask, groupFetch, singleFetch, resolveWaveStrategyFetchPickMode, buildWaveStrategyFetchBoxAssignments, prepareWaveStrategyFetchPlan, ensureNoActiveWavePickTaskForOperator, normalizeWaveStrategyFetchCreatedBefore, buildWaveStrategyFetchTodayStart, getWaveStrategyFetchCandidateOrders, groupWaveStrategyFetchCandidateOrdersByStructure, buildWaveStrategyFetchOrderSkuMap, selectWaveStrategyFetchOrdersBySkuLimit, createWaveBatchByOrderIdsInTransaction, mergeWaveStrategyFirstPoolSameStructureOrders, autoPopulateWaveStrategyFetchSelections, executeWaveStrategyDirectFetch, createWavePickTaskFromPlan, buildTaskCreatePayload, buildTaskWaveRows, buildTaskOrderRows, buildTaskSkuRows, buildTaskBoxRows, bindPickCartForTask, initTaskCheckpointAndLogs, ensurePickCartAvailable, generateWavePickTaskNo, createWavePickTaskWithRetry, isTaskNoDuplicateError, bulkInsertRows, parseWaveStrategyExistingTaskInfo, waveStrategyFetchPda, cancelWavePickTasksInternal, wavePickTaskCancel, wavePickTaskCancelSelf, waveStrategyFetchAdmin, deleteOrderWaveIndexByOrderIds, deleteOrderWaveIndexByWaveIds, rebuildOrderWaveIndex, replaceOrderWaveIndexByWaveIds, fetch - app/service/systemMethods/outbound.js (1) - autoOutbound -- app/service/systemMethods/pick.js (14) - - normalizeBoolean, getOrderModelByWarehouse, generatePickTaskNo, createWavePickTask, resolveLocationSortedOrderIds, query, wavePickTaskDetail, wavePickTaskCurrent, wavePickTaskSubmit, wavePickComplete, wavePickTaskComplete, getWavePickModeByWaveId, getWaveClaimGateStats, waveClaimScan +- app/service/systemMethods/pick.js (16) + - normalizeBoolean, getOrderModelByWarehouse, generatePickTaskNo, createWavePickTask, resolveLocationSortedOrderIds, query, wavePickTaskDetail, wavePickTaskCurrent, wavePickTaskSubmit, wavePickComplete, wavePickTaskComplete, getWavePickModeByWaveId, getWaveClaimGateStats, bumpConfirmPrintUnclaimedWaveVersionSafe, backfillWaveClaimTime, waveClaimScan - app/service/systemMethods/pickCart.js (9) - scan, bindTaskCart, create, update, delete, batchDelete, detail, list, codeDuplicateCheck - app/service/systemMethods/print.js (57) diff --git a/app/service/systemMethods/pick.js b/app/service/systemMethods/pick.js index eab0590..d4f3e10 100644 --- a/app/service/systemMethods/pick.js +++ b/app/service/systemMethods/pick.js @@ -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} 无返回值。 + */ + 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} 是否补写成功。 + */ + 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} 个订单`, }, diff --git a/methods/changes/system.json b/methods/changes/system.json index 742f211..3504227 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -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", diff --git a/methods/system.json b/methods/system.json index 059f6bd..0f25709 100644 --- a/methods/system.json +++ b/methods/system.json @@ -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": [ diff --git a/script/backfill-wave-claim-status.cjs b/script/backfill-wave-claim-status.cjs new file mode 100644 index 0000000..bc295fd --- /dev/null +++ b/script/backfill-wave-claim-status.cjs @@ -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= 数据库配置(默认 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); +});