diff --git a/app/lib/lock_guard.js b/app/lib/lock_guard.js new file mode 100644 index 0000000..d1ef960 --- /dev/null +++ b/app/lib/lock_guard.js @@ -0,0 +1,29 @@ +'use strict'; + +/** + * 订单锁定状态共享定义。 + * + * wms_order_delivery.lock_status 枚举(order_delivery.js / order_delivery_factory.js)实际取值为: + * none / warehouse / store。 + * + * 业务约定:锁定状态只要不是 'none'(即被仓库或货主锁定的订单),一律视为"已锁定", + * 禁止继续执行仓储作业(分配储位/分配快递/抓取波次/自动加团等), + * 已锁定订单一律跳过。 + */ +const LOCK_STATUS_NONE = 'none'; + +/** + * 判断订单锁定状态是否属于"已锁定"。 + * 空值/NULL 归一化为 none 处理;除此之外任何非 none 状态(含 warehouse/store)均视为已锁定。 + * @param {*} status 锁定状态值。 + * @return {boolean} 是否已锁定。 + */ +function isLockedOrderStatus(status) { + const normalizedStatus = String(status || '').trim() || LOCK_STATUS_NONE; + return normalizedStatus !== LOCK_STATUS_NONE; +} + +module.exports = { + LOCK_STATUS_NONE, + isLockedOrderStatus, +}; diff --git a/app/service/systemMethods/order/base.js b/app/service/systemMethods/order/base.js index 8353f85..64dbe36 100644 --- a/app/service/systemMethods/order/base.js +++ b/app/service/systemMethods/order/base.js @@ -3,6 +3,7 @@ const MainService = require('../../main'); const { parseWhereConditions } = require('../../../lib/query_condition_parser'); const { isInterceptedOrderStatus } = require('../../../lib/intercept_guard'); +const { isLockedOrderStatus } = require('../../../lib/lock_guard'); const DEFAULT_PAGE_SIZE = 20; const MAX_PAGE_SIZE = 500; @@ -208,6 +209,16 @@ class OrderBaseService extends MainService { return isInterceptedOrderStatus(status); } + /** + * 判断订单锁定状态是否属于"已锁定"(lock_status != none)。 + * + * @param {*} status 锁定状态值。 + * @return {boolean} 是否已锁定。 + */ + isLockedOrderStatus(status = '') { + return isLockedOrderStatus(status); + } + /** * 断言订单未进入拦截流程,否则抛出阻断异常。 * @@ -567,6 +578,17 @@ class OrderBaseService extends MainService { return Number.isNaN(numericVersion) ? strategyVersion : numericVersion; } + /** + * 规范化订单锁定状态展示值。 + * none 返回 N,其余状态(warehouse/store 等)一律返回 Y。 + * @param {*} lockStatus 锁定状态值。 + * @return {string} Y 或 N。 + */ + normalizeLockStatusFlag(lockStatus) { + const normalizedStatus = String(lockStatus || '').trim() || 'none'; + return normalizedStatus === 'none' ? 'N' : 'Y'; + } + /** * 规范订单列表单行输出,保证重量类型直接返回中文。 * @param {Object} order 订单列表行数据。 @@ -585,6 +607,7 @@ class OrderBaseService extends MainService { wave_strategy_version: this.normalizeWaveStrategyVersion(order.wave_strategy_version), wave_scan_result: this.normalizeWaveScanResult(order.wave_scan_result), create_channel: this.formatCreateChannelLabel(order.create_channel), + lock_status: this.normalizeLockStatusFlag(order.lock_status), }; } diff --git a/app/service/systemMethods/order/wave.js b/app/service/systemMethods/order/wave.js index 0f2e84b..cb21d9c 100644 --- a/app/service/systemMethods/order/wave.js +++ b/app/service/systemMethods/order/wave.js @@ -6800,7 +6800,7 @@ class WaveService extends OrderBaseService { try { const orderRows = await orderModel.findAll({ - attributes: [ 'id', 'wave_id', 'wave_no', 'step', 'status', 'outbound_status', 'items_hash', 'items', 'logistics_name', 'intercept_status' ], + attributes: [ 'id', 'wave_id', 'wave_no', 'step', 'status', 'outbound_status', 'items_hash', 'items', 'logistics_name', 'intercept_status', 'lock_status' ], where: { id: { [Op.in]: normalizedIds }, }, @@ -6824,6 +6824,11 @@ class WaveService extends OrderBaseService { .map(row => Number(row && row.id || 0)) .filter(id => Number.isInteger(id) && id > 0)) ] .sort((a, b) => a - b); + const excludedLockedOrderIds = [ ...new Set(normalizedOrderRows + .filter(row => this.isLockedOrderStatus(row && row.lock_status)) + .map(row => Number(row && row.id || 0)) + .filter(id => Number.isInteger(id) && id > 0)) ] + .sort((a, b) => a - b); const fetchableRows = normalizedOrderRows.filter(row => { const orderId = Number(row && row.id || 0); @@ -6842,6 +6847,11 @@ class WaveService extends OrderBaseService { return false; } + // 已锁定的订单不允许抓取波次 + if (this.isLockedOrderStatus(row && row.lock_status)) { + return false; + } + return true; }); @@ -6862,6 +6872,7 @@ class WaveService extends OrderBaseService { fetched_order_count: 0, excluded_existing_wave_order_ids: excludedExistingWaveOrderIds, excluded_intercepted_order_ids: excludedInterceptedOrderIds, + excluded_locked_order_ids: excludedLockedOrderIds, skipped_order_ids: skippedOrderIds, not_found_order_ids: notFoundOrderIds, }); @@ -6976,6 +6987,7 @@ class WaveService extends OrderBaseService { fetched_order_count: grabbedOrderIds.length, excluded_existing_wave_order_ids: excludedExistingWaveOrderIds, excluded_intercepted_order_ids: excludedInterceptedOrderIds, + excluded_locked_order_ids: excludedLockedOrderIds, skipped_order_ids: skippedOrderIds, not_found_order_ids: notFoundOrderIds, }); @@ -8804,7 +8816,7 @@ class WaveService extends OrderBaseService { try { orderRows = await orderModel.findAll({ - attributes: [ 'id', 'business_key', 'intercept_status' ], + attributes: [ 'id', 'business_key', 'intercept_status', 'lock_status' ], where: baseOrderWhere, raw: true, }); @@ -8820,7 +8832,7 @@ class WaveService extends OrderBaseService { warehouseId, }); orderRows = await orderModel.findAll({ - attributes: [ 'id', 'intercept_status' ], + attributes: [ 'id', 'intercept_status', 'lock_status' ], where: baseOrderWhere, raw: true, }); @@ -8850,10 +8862,27 @@ class WaveService extends OrderBaseService { }); } + const skippedLockedOrderIds = [ ...new Set((Array.isArray(orderRows) ? orderRows : []) + .filter(row => this.isLockedOrderStatus(row && row.lock_status)) + .map(row => Number(row && row.id || 0)) + .filter(orderId => Number.isInteger(orderId) && orderId > 0)) ] + .sort((a, b) => a - b); + const skippedLockedOrderIdSet = new Set(skippedLockedOrderIds); + if (skippedLockedOrderIds.length > 0) { + this.ctx.logger.info('[wave.batchAllocateExpress] 跳过锁定订单', { + traceId, + taskId: normalizedTaskId, + warehouseId, + skippedLockedOrderIds, + }); + } + const normalizedOrders = (Array.isArray(orderRows) ? orderRows : []) .map(row => { const orderId = Number(row && row.id || 0); - if (!Number.isInteger(orderId) || orderId <= 0 || skippedInterceptedOrderIdSet.has(orderId)) { + if (!Number.isInteger(orderId) || orderId <= 0 + || skippedInterceptedOrderIdSet.has(orderId) + || skippedLockedOrderIdSet.has(orderId)) { return null; } @@ -8872,6 +8901,7 @@ class WaveService extends OrderBaseService { warehouseId, waveIds, skippedInterceptedOrderIds, + skippedLockedOrderIds, }); const durationMs = Date.now() - startTime; await this.setBatchAllocateExpressTaskProgress(normalizedTaskId, 'success', { @@ -8882,6 +8912,7 @@ class WaveService extends OrderBaseService { success_order_count: 0, failed_order_count: 0, skipped_intercepted_order_ids: skippedInterceptedOrderIds, + skipped_locked_order_ids: skippedLockedOrderIds, progress_percent: 100, end_time: Date.now(), duration_ms: durationMs, @@ -8889,9 +8920,10 @@ class WaveService extends OrderBaseService { wave_ids: waveIds, allocated_order_count: 0, skipped_intercepted_order_ids: skippedInterceptedOrderIds, + skipped_locked_order_ids: skippedLockedOrderIds, duration_ms: durationMs, - message: skippedInterceptedOrderIds.length > 0 - ? `拦截订单已跳过,未找到可分配快递号的订单(跳过 ${skippedInterceptedOrderIds.length} 单)` + message: skippedInterceptedOrderIds.length > 0 || skippedLockedOrderIds.length > 0 + ? `拦截/锁定订单已跳过,未找到可分配快递号的订单(拦截 ${skippedInterceptedOrderIds.length} 单,锁定 ${skippedLockedOrderIds.length} 单)` : '未找到可分配快递号的订单', }, trace_id: traceId, @@ -8935,6 +8967,7 @@ class WaveService extends OrderBaseService { success_order_count: normalizedOrders.length, failed_order_count: 0, skipped_intercepted_order_ids: skippedInterceptedOrderIds, + skipped_locked_order_ids: skippedLockedOrderIds, progress_percent: 100, end_time: Date.now(), duration_ms: durationMs, @@ -8942,6 +8975,7 @@ class WaveService extends OrderBaseService { wave_ids: waveIds, allocated_order_count: normalizedOrders.length, skipped_intercepted_order_ids: skippedInterceptedOrderIds, + skipped_locked_order_ids: skippedLockedOrderIds, duration_ms: durationMs, message: String(pipelineResult && pipelineResult.message || '分配快递任务已提交').trim(), }, @@ -9054,7 +9088,7 @@ class WaveService extends OrderBaseService { try { const orderModel = await this.getOrderModel('pendingOrder', warehouseId); const orderRows = await orderModel.findAll({ - attributes: [ 'id' ], + attributes: [ 'id', 'lock_status' ], where: { warehouse_id: warehouseId, wave_id: { @@ -9067,9 +9101,14 @@ class WaveService extends OrderBaseService { raw: true, }); + const skippedLockedOrderIdSet = new Set((Array.isArray(orderRows) ? orderRows : []) + .filter(row => this.isLockedOrderStatus(row && row.lock_status)) + .map(row => Number(row && row.id || 0)) + .filter(orderId => Number.isInteger(orderId) && orderId > 0)); const normalizedOrders = [ ...new Set((Array.isArray(orderRows) ? orderRows : []) .map(row => Number(row && row.id || 0)) .filter(orderId => Number.isInteger(orderId) && orderId > 0)) ] + .filter(orderId => !skippedLockedOrderIdSet.has(orderId)) .map(orderId => ({ order_id: orderId, business_id: BATCH_ALLOCATE_STORAGE_FORCE_BUSINESS_ID, diff --git a/app/service/systems/delivery_order.js b/app/service/systems/delivery_order.js index b4b87fe..eef7854 100644 --- a/app/service/systems/delivery_order.js +++ b/app/service/systems/delivery_order.js @@ -1,6 +1,7 @@ 'use strict'; const Service = require('egg').Service; const { normalizeWarehouseShardId } = require('../../lib/warehouse_shard_guard'); +const { isLockedOrderStatus } = require('../../lib/lock_guard'); const DELIVERY_ORDER_STEP = Object.freeze({ PENDING_REVIEW: 0, @@ -2001,7 +2002,7 @@ class DeliveryOrderService extends Service { id: orderId, warehouse_id: warehouseId, }, - attributes: [ 'id', 'wave_id', 'step', 'status', 'outbound_status' ], + attributes: [ 'id', 'wave_id', 'step', 'status', 'outbound_status', 'lock_status' ], transaction, lock: transaction.LOCK.UPDATE, }); @@ -2010,6 +2011,12 @@ class DeliveryOrderService extends Service { return false; } + // 已锁定的订单不允许自动加团 + if (isLockedOrderStatus(orderRow.lock_status)) { + await transaction.commit(); + return false; + } + const currentWaveId = Number(orderRow.wave_id || 0); if (currentWaveId === normalizedWaveId) { await transaction.commit(); @@ -2057,6 +2064,7 @@ class DeliveryOrderService extends Service { id: orderId, warehouse_id: warehouseId, wave_id: 0, + lock_status: 'none', }, transaction, }); @@ -2139,6 +2147,7 @@ class DeliveryOrderService extends Service { step: { [ctx.app.Sequelize.Op.in]: [ 1, 2, 3 ] }, status: { [ctx.app.Sequelize.Op.ne]: 'cancel' }, outbound_status: { [ctx.app.Sequelize.Op.ne]: 'padding' }, + lock_status: 'none', sys_logistics_code: structure.logisticsName, }; where[structure.itemPartType] = structure.itemPart; @@ -2392,6 +2401,16 @@ class DeliveryOrderService extends Service { return; } + // 已锁定的订单不自动分配快递、储位,不自动加团 + if (isLockedOrderStatus(context.order && context.order.lock_status)) { + this.ctx.logger.info('[DeliveryOrderService.asyncProcessOrderCreated] 订单已锁定,跳过自动分配快递/储位/自动加团', { + warehouseId: context.warehouseId, + orderId: context.orderId, + lockStatus: context.order.lock_status, + }); + return; + } + const policyConfig = await this.getStoreWarehousePolicyConfig(context.storeId, context.warehouseId); // 截单时间兜底:货主-仓库级未启用时,fallback 到仓库级配置 diff --git a/app/service/systems/express.js b/app/service/systems/express.js index 2db92ef..fb97ab2 100644 --- a/app/service/systems/express.js +++ b/app/service/systems/express.js @@ -3,6 +3,7 @@ const { Service } = require('egg'); const { isInterceptedOrderStatus } = require('../../lib/intercept_guard'); +const { isLockedOrderStatus } = require('../../lib/lock_guard'); const DEFAULT_CACHE_TTL_SECONDS = 600; const DEFAULT_EXPRESS_PRODUCT_TYPE_CACHE_TTL_SECONDS = 60 * 60; @@ -2516,7 +2517,7 @@ class ExpressService extends Service { [Op.ne]: 'cancel', }, }, - attributes: [ 'id', 'sys_platform_code', 'logistics_code', 'sys_platform_name', 'logistics_name', 'store_id', 'pay_no', 'from_key', 'intercept_status' ], + attributes: [ 'id', 'sys_platform_code', 'logistics_code', 'sys_platform_name', 'logistics_name', 'store_id', 'pay_no', 'from_key', 'intercept_status', 'lock_status' ], raw: true, }); @@ -2540,7 +2541,7 @@ class ExpressService extends Service { [Op.ne]: 'cancel', }, }, - attributes: [ 'id', 'sys_platform_code', 'logistics_code', 'sys_platform_name', 'logistics_name', 'store_id', 'pay_no', 'from_key', 'intercept_status' ], + attributes: [ 'id', 'sys_platform_code', 'logistics_code', 'sys_platform_name', 'logistics_name', 'store_id', 'pay_no', 'from_key', 'intercept_status', 'lock_status' ], raw: true, }); } @@ -2561,21 +2562,37 @@ class ExpressService extends Service { skippedInterceptedOrderIds, }); } + + // 锁定订单跳过(除 none 外一律视为已锁定,锁定期间不允许分配快递) + const lockedOrderIdSet = new Set(orders_arr + .filter(order => isLockedOrderStatus(order && order.lock_status)) + .map(order => Number(order && order.id || 0)) + .filter(orderId => Number.isInteger(orderId) && orderId > 0)); + const skippedLockedOrderIds = Array.from(lockedOrderIdSet); + const activeOrders = orders_arr.filter(order => !lockedOrderIdSet.has(Number(order && order.id || 0))); + if (skippedLockedOrderIds.length > 0) { + this.ctx.logger.info('[ExpressService.createWaybillCodePipeline] 跳过锁定订单', { + traceId, + warehouseId, + skippedLockedOrderIds, + }); + } this.ctx.logger.info('[ExpressService.createWaybillCodePipeline] 订单筛选结果', { traceId, warehouseId, inputOrderCount: orderList.length, currentCount: (Array.isArray(currentOrders) ? currentOrders : []).length, dispatchCount: dispatchOrders.length, - matchedOrderCount: orders_arr.length, + matchedOrderCount: activeOrders.length, skippedInterceptedOrderIds, + skippedLockedOrderIds, }); // 【step1.5】过滤已分配运单号(status=1)且传入 business_key=1 的订单,避免重复分配。 const orderExpressModel = this.ctx.model && this.ctx.model.OrderExpress; - let filteredOrdersArr = orders_arr; - if (orderExpressModel && orders_arr.length > 0) { - const orderIds = orders_arr.map(o => Number(o.id)).filter(id => id > 0); + let filteredOrdersArr = activeOrders; + if (orderExpressModel && activeOrders.length > 0) { + const orderIds = activeOrders.map(o => Number(o.id)).filter(id => id > 0); const completedRows = await orderExpressModel.findAll({ where: { order_id: { [Op.in]: orderIds }, @@ -2590,8 +2607,8 @@ class ExpressService extends Service { skipSet.add(`${Number(row.order_id)}:${Number(row.business_key)}`); } if (skipSet.size > 0) { - const beforeCount = orders_arr.length; - filteredOrdersArr = orders_arr.filter(order => { + const beforeCount = activeOrders.length; + filteredOrdersArr = activeOrders.filter(order => { const matchedExpress = orderList.find(express => Number(order.id) === Number(express.order_id)); const businessKey = matchedExpress ? Number(matchedExpress.business_key) : 1; if (businessKey === 1 && skipSet.has(`${Number(order.id)}:1`)) { @@ -2603,7 +2620,7 @@ class ExpressService extends Service { this.ctx.logger.info('[ExpressService.createWaybillCodePipeline] 跳过已分配运单号(business_key=1)的订单', { traceId, skippedCount: beforeCount - filteredOrdersArr.length, - skippedOrderIds: orders_arr + skippedOrderIds: activeOrders .filter(order => { const matchedExpress = orderList.find(express => Number(order.id) === Number(express.order_id)); const businessKey = matchedExpress ? Number(matchedExpress.business_key) : 1; @@ -2620,6 +2637,7 @@ class ExpressService extends Service { return { message: '所有订单均已分配运单号,无需处理', skipped_intercepted_order_ids: skippedInterceptedOrderIds, + skipped_locked_order_ids: skippedLockedOrderIds, }; } @@ -2725,6 +2743,7 @@ class ExpressService extends Service { return { message: '分配快递任务已提交', skipped_intercepted_order_ids: skippedInterceptedOrderIds, + skipped_locked_order_ids: skippedLockedOrderIds, }; } /** diff --git a/app/service/systems/order_storage_allocation.js b/app/service/systems/order_storage_allocation.js index e3b921c..7d3473f 100644 --- a/app/service/systems/order_storage_allocation.js +++ b/app/service/systems/order_storage_allocation.js @@ -3,6 +3,7 @@ const MainService = require('../main'); const { isInterceptedOrderStatus } = require('../../lib/intercept_guard'); +const { isLockedOrderStatus } = require('../../lib/lock_guard'); const STORAGE_STATUS_FIN = 'fin'; const STORAGE_STATUS_ERROR = 'error'; @@ -645,6 +646,21 @@ class OrderStorageAllocationService extends MainService { continue; } + if (isLockedOrderStatus(orderRow && orderRow.lock_status)) { + skippedOrders.push({ + order_id: orderId, + status: 'skipped', + lock_status: orderRow.lock_status, + skipped_reason: 'locked', + }); + writeAllocationTextLog('[OrderStorageAllocationService.allocatePicking] 过滤订单结果', { + orderId, + lockStatus: orderRow.lock_status, + skippedReason: 'locked', + }); + continue; + } + if (String(orderRow.storage_status || 'none') === STORAGE_STATUS_FIN) { skippedOrders.push({ order_id: orderId, diff --git a/methods/changes/system.json b/methods/changes/system.json index f04174e..cb9ea6e 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,62 @@ [ + { + "version": "2026.08.18-order-lock-status-guard-and-list-yn", + "date": "2026-08-18", + "type": "enhanced", + "summary": "新增锁定订单作业门禁与订单列表 lock_status 转 Y/N:lock_status 非 none(枚举 warehouse/store)的订单在分配储位、分配快递、抓取波次、自动加团等流程中被直接跳过,跳过明细通过 skipped_locked_order_ids / excluded_locked_order_ids / skipped_orders 等字段返回;订单列表 lock_status 统一输出 Y/N(none→N,其余→Y)。", + "methods": [ + "order.pendingOrder.list", + "order.pendingOrder.allocateExpressCode", + "order.pendingOrder.allocateStorage", + "order.wave.singleFetchByIds", + "order.wave.waveStrategyFallbackOrderList", + "order.wave.batchAllocateExpress", + "order.wave.batchAllocateExpressTaskProgress", + "order.wave.batchAllocateStorage", + "order.wave.batchAllocateStorageTaskProgress" + ], + "notes": [ + "新增 app/lib/lock_guard.js isLockedOrderStatus:lock_status 非 'none' 即视为已锁定(枚举 none/warehouse/store)", + "app/service/systems/order_storage_allocation.js allocatePicking:过滤循环新增锁定订单跳过,skipped 记录含 lock_status 与 skipped_reason='locked';order.storageAllocation.allocateStorage / order.pendingOrder.allocateStorage / order.wave.batchAllocateStorage 共用该底层入口", + "app/service/systems/express.js createWaybillCodePipeline:查询新增 lock_status 字段,锁定订单与拦截订单同样剔除,返回结果新增 skipped_locked_order_ids", + "app/service/systemMethods/order/wave.js runBatchAllocateExpressTask:查询新增 lock_status,任务进度与 result 新增 skipped_locked_order_ids;singleFetchByIds 查询属性新增 lock_status 并过滤锁定订单,响应新增 excluded_locked_order_ids(两个返回分支均返回);waveStrategyFallbackOrderList 查询追加 lock_status/intercept_status 非 none 条件,列表行新增 excluded_reason(locked/intercepted/printed/no_match)", + "app/service/systems/delivery_order.js asyncProcessOrderCreated:订单已锁定时跳过自动分配快递/储位/自动加团三步;appendOrderToWave 增加锁定校验且更新波次时 where 追加 lock_status='none';countCandidateGroupOrders 过滤 lock_status='none'(内部流程,无公开接口)", + "app/service/systemMethods/order/base.js 新增 normalizeLockStatusFlag:none(含空值)返回 'N',其余值一律返回 'Y';normalizeOrderListItem 统一覆盖 lock_status 输出为 Y/N,影响 order.pendingOrder.list、order.wave.waveStrategyFallbackOrderList 及经 listByModule 的各类工作台订单列表", + "同步更新 methods/system.json 中上述 method 的 description 与 response 字段" + ], + "module": "order" + }, + { + "version": "2026.08.18-storage.entry.addItem-non-binding", + "date": "2026-08-18", + "type": "fixed", + "summary": "库存导入(storage.entry.addItem 导入/PDA 入库)不再强制绑定收货单:原 PENDING 状态下未绑定收货单拒绝上架、每项缺少 receiving_detail_id 拒绝,导致移除绑定收货单后仍限制必须传入收货单 ID。现 PENDING 状态允许不绑定收货单直接导入(非绑定模式,数量受计划数量限制),传 receiving_detail_id 时仍走绑定模式(预占收货明细)", + "methods": [ + "storage.entry.addItem" + ], + "notes": [ + "app/service/systems/inbound_direct_log.js addItem:删除 PENDING 状态下 hasReceivingBindings 与 receiving_detail_id 的强制校验,绑定模式 space_id/可用数量校验仍由 _addSingleItem 统一处理;CREATED 已绑定收货单需先审核的限制保留", + "PENDING 非绑定模式导入数量仍受计划数量限制(isManualImport 仅 CREATED 且非绑定可超计划),防止超计划入库", + "同步更新 methods/system.json 中 storage.entry.addItem 的 description、receiving_detail_id 参数说明与错误码列表(移除两条 PENDING 绑定错误码)" + ], + "module": "storage.entry" + }, + { + "version": "2026.08.18-recheckOrder.scanOrder.singleIntercept", + "date": "2026-08-18", + "type": "fixed", + "summary": "修复 order.recheckOrder.scanOrder 散单模式拦截订单识别:原逻辑对波次内所有订单执行复核校验,只要波次内存在一单已进入拦截流程(requested/requesting/intercepting/intercepted_in_transit/intercepted_at_warehouse,历史值 intercepted 兼容),整个散单扫描视图即报错「订单已被拦截,无法提交复核」,导致波次内其他正常订单也无法复核。现拦截订单保留在 list 中按单提示(intercept_status),不再阻断整个扫描视图加载,且不计入复核/打印统计", + "methods": [ + "order.recheckOrder.scanOrder", + "order.recheckOrder.scanTask" + ], + "notes": [ + "buildSingleWaveScanView:用 isInterceptedOrderStatus 分离拦截订单,仅非拦截订单参与 assertOrderCanRecheck 校验与 reviewed/unreviewed/printed/unprinted 统计,拦截订单保留在 list 中按单提示", + "车号/任务模式(cart/task)合并多个波次后,reviewed_count/unreviewed_count 仅统计非拦截订单,total_orders 仍为订单总数", + "同步更新 methods/system.json 中 scanOrder 散单订单项 intercept_status 字段说明" + ], + "module": "order" + }, { "version": "2026.08.17-inbox-group-reset", "date": "2026-08-17", @@ -6226,5 +6284,24 @@ "退回查询 _resolveReturnOrderInfo 优先主表快照,空时实时兜底(交易单号→原运单/原订单,店铺→store_remask)" ], "module": "returnUnpack" + }, + { + "version": "2026.08.18-storeWarehouse-sign-confirmSign-doc", + "date": "2026-08-18", + "type": "added", + "summary": "补齐 storeWarehouse 签约接口文档(纯文档补全,无业务代码变更):新增 storeWarehouse.store.confirmSign(货主侧确认签约)、storeWarehouse.warehouse.sign(仓库侧发起签约)、storeWarehouse.warehouse.confirmSign(仓库侧确认签约)三个方法的入参/出参/错误码说明。", + "methods": [ + "storeWarehouse.store.confirmSign", + "storeWarehouse.warehouse.sign", + "storeWarehouse.warehouse.confirmSign" + ], + "notes": [ + "storeWarehouse.store.confirmSign:当前主体作为对方主体确认待签约申请,auth_status 由 1(申请中)变更为 2(已通过);入参 id(兼容 contract_id);400=id 缺失或签约状态非待签约、403=当前主体不在签约关系中或发起方自确认、404=签约关系不存在;响应 data.mode=confirm 与 data.contract 精简对象(id/store_id/warehouse_id/counterparty_name/remask/use_status/auth_status/auth_status_label/auth_end/print_quantity/has_qimen_config)", + "storeWarehouse.warehouse.sign:仓库侧发起签约,当前仓库在 store_id 方、对方在 warehouse_id 方,支持签约外部合作仓库;入参 counterparty_id(兼容 warehouse_id / store_id),当前主体自动识别;响应 data.mode=initiate/already_exists/already_confirmed 与 data.contract;400=对方主体缺失/日期非法,404=签约对象不存在", + "storeWarehouse.warehouse.confirmSign:仓库侧确认签约,校验逻辑与货主侧确认一致(400/403/404 同 storeWarehouse.store.confirmSign)", + "代码对齐:app/service/systemMethods/storeWarehouse/store.js#confirmSign、app/service/systemMethods/storeWarehouse/warehouse.js#sign/#confirmSign 均已注册(_noNeedAuth 含三个方法,isNeedAuth=false、isNeedLogin=true);实现位于 app/service/systems/store_warehouse.js#sign/#confirmSign;权限表 method id 397「签约确定」", + "仅文档变更,无业务代码修改" + ], + "module": "storeWarehouse" } ] diff --git a/methods/system.json b/methods/system.json index 20fd2f4..0c531be 100644 --- a/methods/system.json +++ b/methods/system.json @@ -2960,7 +2960,7 @@ "name": "list", "type": "array", "required": true, - "description": "订单列表(raw 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段。" + "description": "订单列表(raw 行数据,字段字典见 docs/order-workbench-list-api.md 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段。lock_status 字段统一输出为 Y/N:none(含空值)→ 'N',其余值(如 warehouse/store)→ 'Y'。" }, { "name": "pagination", @@ -3280,7 +3280,7 @@ }, { "method": "order.pendingOrder.allocateExpressCode", - "description": "批量分配待处理订单的首单快递号(异步接口)。调用后立即返回 task_id,后台异步执行运单创建;可通过 order.pendingOrder.allocateExpressCodeTaskProgress 查询进度。拆单场景请使用 order.pendingOrder.allocateSubOrderNumber。", + "description": "批量分配待处理订单的首单快递号(异步接口)。调用后立即返回 task_id,后台异步执行运单创建;可通过 order.pendingOrder.allocateExpressCodeTaskProgress 查询进度。拆单场景请使用 order.pendingOrder.allocateSubOrderNumber。已锁定订单(lock_status 非 none)与拦截订单同样在流水线中被跳过、不参与分配,任务结果(allocateExpressCodeTaskProgress)中包含 skipped_locked_order_ids 等跳过明细。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -3339,7 +3339,7 @@ }, { "method": "order.pendingOrder.allocateStorage", - "description": "按订单批量分配储位(迁移自 order.storageAllocation.allocateStorage)。这是一个异步提交接口:调用后接口立即返回受理信息(包含 request_id),后端异步执行实际的储位分配与锁定操作;仓库上下文由当前登录用户提供(ctx.user.store_id)。接口不会在同步响应中返回分配明细(如 requested_order_ids、allocated_order_ids 等),客户端可通过请求 ID 或事件/查询链路获取最终结果。", + "description": "按订单批量分配储位(迁移自 order.storageAllocation.allocateStorage)。这是一个异步提交接口:调用后接口立即返回受理信息(包含 request_id),后端异步执行实际的储位分配与锁定操作;仓库上下文由当前登录用户提供(ctx.user.store_id)。接口不会在同步响应中返回分配明细(如 requested_order_ids、allocated_order_ids 等),客户端可通过请求 ID 或事件/查询链路获取最终结果。已锁定订单(lock_status 非 none)会在分配流水线中被跳过(底层分配结果 skipped_orders 中记录 skipped_reason='locked')。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -5568,7 +5568,7 @@ { "name": "intercept_status", "type": "string", - "description": "[散单有波次] 拦截状态(requested / intercepted_at_warehouse / 空字符串)" + "description": "[散单有波次] 拦截状态(requested / requesting / intercepting / intercepted_in_transit / intercepted_at_warehouse / 历史值 intercepted / 空字符串)。已拦截订单保留在 list 中按单提示,不阻断整个扫描视图,且不计入 reviewed_count / unreviewed_count / printed_count / unprinted_count 统计" }, { "name": "stock", @@ -8304,7 +8304,7 @@ }, { "method": "order.wave.singleFetchByIds", - "description": "按订单 ID 列表抓取到一个散单波次。仅处理当前仓库的待处理订单(step in [1,2,3]),排除已在波次中的订单(wave_id>0),不区分快递;成功抓取后批量写入订单操作日志;当无可抓取订单时返回 wave_id=0。", + "description": "按订单 ID 列表抓取到一个散单波次。仅处理当前仓库的待处理订单(step in [1,2,3]),排除已在波次中的订单(wave_id>0),不区分快递;成功抓取后批量写入订单操作日志;当无可抓取订单时返回 wave_id=0。已锁定订单(lock_status 非 none)不允许抓取波次,返回 excluded_locked_order_ids。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -8361,6 +8361,12 @@ "required": false, "description": "原始入参中已在其它波次中的订单 ID(被排除,不会被抓取)" }, + { + "name": "excluded_locked_order_ids", + "type": "array", + "required": false, + "description": "因已锁定(lock_status 非 none)被排除、不会被抓取波次的订单 ID 列表(成功与无可抓取订单两个返回分支均返回)" + }, { "name": "skipped_order_ids", "type": "array", @@ -8377,17 +8383,17 @@ "errors": [ { "code": "400", - "description": "未识别到当前仓库上下文或 ids 参数不能为空或格式错误;当入参包含非法字段或别名冲突时也会返回 400" + "message": "未识别到当前仓库上下文或 ids 参数不能为空或格式错误;当入参包含非法字段或别名冲突时也会返回 400" }, { "code": "500", - "description": "抓取失败或内部错误" + "message": "抓取失败或内部错误" } ] }, { "method": "order.wave.waveStrategyFallbackOrderList", - "description": "基于波次策略的回退候选订单列表。该接口内置固定筛选条件:step != 0、wave_id = 0、wave_scan_result = 2。用于展示策略未命中但需回退处理的订单候选。", + "description": "基于波次策略的回退候选订单列表。该接口内置固定筛选条件:step != 0、wave_id = 0,且满足以下任一条件:wave_scan_result = 2(未匹配任何波次策略)、print_status = 'fin'(已完全打印)、lock_status != 'none'(订单已锁定)、intercept_status != 'none'(订单已拦截)。用于展示策略未命中或需回退处理的订单候选。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -8419,7 +8425,7 @@ "name": "list", "type": "array", "required": true, - "description": "回退候选订单简要列表。数组内对象字段说明见 children。", + "description": "回退候选订单简要列表。数组内对象字段说明见 children;每行含 excluded_reason 标记:locked=订单已锁定(lock_status 非 none)、intercepted=订单已拦截、printed=已完全打印、no_match=未匹配任何波次策略。", "children": [ { "name": "id", @@ -8480,6 +8486,11 @@ "name": "item_snapshot", "type": "string", "description": "商品快照,格式示例:苹果*2|香蕉*3" + }, + { + "name": "excluded_reason", + "type": "string", + "description": "订单进入回退列表的原因枚举:locked(已锁定,lock_status 非 none)/ intercepted(已拦截)/ printed(已完全打印)/ no_match(未匹配任何波次策略)" } ] }, @@ -9189,7 +9200,7 @@ }, { "method": "order.wave.batchAllocateExpress", - "description": "提交批次分配快递号任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理订单并提交到快递号分配流水线。", + "description": "提交批次分配快递号任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理订单并提交到快递号分配流水线。已锁定订单(lock_status 非 none)与拦截订单在任务中被跳过、不参与分配,跳过明细见任务进度(batchAllocateExpressTaskProgress)的 skipped_locked_order_ids。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -9251,21 +9262,21 @@ "errors": [ { "code": "400", - "description": "未识别到当前仓库上下文" + "message": "未识别到当前仓库上下文" }, { "code": "400", - "description": "wave_ids 参数不能为空或格式错误" + "message": "wave_ids 参数不能为空或格式错误" }, { "code": "500", - "description": "任务提交失败或内部错误" + "message": "任务提交失败或内部错误" } ] }, { "method": "order.wave.batchAllocateExpressTaskProgress", - "description": "查询批次分配快递号任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。", + "description": "查询批次分配快递号任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。已锁定订单(lock_status 非 none)被跳过,任务进度与 result 中包含 skipped_locked_order_ids(因已锁定被跳过的订单 ID)。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -9334,6 +9345,12 @@ "required": false, "description": "提交分配失败的订单数量" }, + { + "name": "skipped_locked_order_ids", + "type": "array", + "required": false, + "description": "因已锁定(lock_status 非 none)被跳过、未参与快递号分配的订单 ID 列表(任务进度与 result 中均返回)" + }, { "name": "progress_percent", "type": "number", @@ -9362,11 +9379,11 @@ "errors": [ { "code": "400", - "description": "task_id 参数不能为空" + "message": "task_id 参数不能为空" }, { "code": "500", - "description": "查询失败或内部错误" + "message": "查询失败或内部错误" } ] }, @@ -9555,7 +9572,7 @@ }, { "method": "order.wave.batchAllocateStorage", - "description": "提交批次分配储位任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理订单并提交到储位分配流水线。", + "description": "提交批次分配储位任务。该接口为异步任务提交接口,立即返回 task_id,后端异步按当前仓库 + wave_ids 拉取待处理订单并提交到储位分配流水线。已锁定订单(lock_status 非 none)在任务中被直接跳过、不参与储位分配。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -9617,21 +9634,21 @@ "errors": [ { "code": "400", - "description": "未识别到当前仓库上下文" + "message": "未识别到当前仓库上下文" }, { "code": "400", - "description": "wave_ids 参数不能为空或格式错误" + "message": "wave_ids 参数不能为空或格式错误" }, { "code": "500", - "description": "任务提交失败或内部错误" + "message": "任务提交失败或内部错误" } ] }, { "method": "order.wave.batchAllocateStorageTaskProgress", - "description": "查询批次分配储位任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。", + "description": "查询批次分配储位任务进度:按 task_id 查询任务状态与统计信息;兼容 taskId 参数名。已锁定订单(lock_status 非 none)被直接跳过,不计入 total_order_count 等统计。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -9728,11 +9745,11 @@ "errors": [ { "code": "400", - "description": "task_id 参数不能为空" + "message": "task_id 参数不能为空" }, { "code": "500", - "description": "查询失败或内部错误" + "message": "查询失败或内部错误" } ] }, @@ -21501,7 +21518,7 @@ }, { "method": "storage.entry.addItem", - "description": "按商品增量添加导入/PDA 入库记录(支持单条和批量)。单条模式传 stock_id/quantity/inbound_type/remark,批量模式传 items 数组。批量模式所有商品共享同一个入库单状态校验,任一商品校验失败整批拒绝。若某商品累计入库量超过计划数量则拒绝(PENDING 非绑定模式)。PENDING 状态需传 receiving_detail_id 绑定收货明细;CREATED 人工导入允许超过计划数量;传入 receiving_detail_id 时 quantity 可选(自动计算可用数量),space_id 必填。", + "description": "按商品增量添加导入/PDA 入库记录(支持单条和批量)。单条模式传 stock_id/quantity/inbound_type/remark,批量模式传 items 数组。批量模式所有商品共享同一个入库单状态校验,任一商品校验失败整批拒绝。若某商品累计入库量超过计划数量则拒绝(PENDING 非绑定模式)。PENDING 状态可传 receiving_detail_id 绑定收货明细(不传则走非绑定模式,数量受计划数量限制),不再强制绑定收货单、不再强制传收货单 ID;CREATED 人工导入允许超过计划数量;传入 receiving_detail_id 时 quantity 可选(自动计算可用数量),space_id 必填。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -21560,7 +21577,7 @@ "type": "number", "required": false, "source": "body", - "description": "收货单明细ID(PDA 上架绑定模式),传入后触发收货明细预占绑定,quantity 自动计算" + "description": "收货单明细ID(PDA 上架绑定模式),传入后触发收货明细预占绑定,quantity 自动计算;不传则按非绑定模式直接导入,不要求绑定收货单" }, { "name": "allocated_quantity", @@ -21674,14 +21691,6 @@ "code": 400, "message": "入库单已绑定收货单且状态为 CREATED,请先审核后再进行上架操作" }, - { - "code": 400, - "message": "入库单未绑定收货单,无法上架(PENDING)" - }, - { - "code": 400, - "message": "随机入库需要选定收货单明细提交,缺少 receiving_detail_id(PENDING)" - }, { "code": 400, "message": "绑定收货明细时必须指定 space_id" @@ -25720,6 +25729,131 @@ } ], "errors": [] + }, + { + "method": "storeWarehouse.store.confirmSign", + "description": "确认签约:当前主体作为对方主体确认待签约的申请,签约状态从 1(申请中)变为 2(已通过);发起方不能确认自己的申请", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "签约关系ID,兼容 contract_id" + } + ], + "response": [ + { + "name": "data.mode", + "type": "string", + "required": true, + "description": "确认模式标识,固定为 confirm" + }, + { + "name": "data.contract", + "type": "object", + "required": true, + "description": "签约关系精简对象" + }, + { + "name": "data.contract.id", + "type": "number", + "required": true, + "description": "签约关系主键 ID" + }, + { + "name": "data.contract.store_id", + "type": "number", + "required": true, + "description": "货主方主体 ID" + }, + { + "name": "data.contract.warehouse_id", + "type": "number", + "required": true, + "description": "仓库方主体 ID" + }, + { + "name": "data.contract.counterparty_name", + "type": "string", + "required": true, + "description": "对方主体名称" + }, + { + "name": "data.contract.remask", + "type": "string", + "required": true, + "description": "当前主体视角的签约备注名" + }, + { + "name": "data.contract.use_status", + "type": "number", + "required": true, + "description": "当前主体启用状态:0=禁用 1=启用" + }, + { + "name": "data.contract.auth_status", + "type": "number", + "required": true, + "description": "签约状态:1=申请中 2=已通过 3=已拒绝 4=已解除 5=已过期" + }, + { + "name": "data.contract.auth_status_label", + "type": "string", + "required": true, + "description": "签约状态中文标签" + }, + { + "name": "data.contract.auth_end", + "type": "string|null", + "required": true, + "description": "授权结束时间" + }, + { + "name": "data.contract.print_quantity", + "type": "number", + "required": true, + "description": "面单余额数量" + }, + { + "name": "data.contract.has_qimen_config", + "type": "boolean", + "required": true, + "description": "是否已配置奇门" + } + ], + "errors": [ + { + "code": 400, + "message": "id 参数不能为空" + }, + { + "code": 400, + "message": "当前签约状态不允许确认,仅待签约状态可确认" + }, + { + "code": 403, + "message": "当前主体不在此签约关系中" + }, + { + "code": 403, + "message": "发起方不能确认自己的签约申请" + }, + { + "code": 404, + "message": "签约关系不存在" + } + ] } ] }, @@ -25912,6 +26046,134 @@ "message": "获取签约列表失败" } ] + }, + { + "method": "storeWarehouse.warehouse.sign", + "description": "仓库侧发起签约(当前仓库在 store_id 方,对方在 warehouse_id 方,支持签约外部合作仓库)", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "counterparty_id", + "type": "number", + "required": true, + "source": "body", + "description": "对方主体 ID(兼容 warehouse_id / store_id),当前主体自动识别" + } + ], + "response": [ + { + "name": "data.mode", + "type": "string", + "required": true, + "description": "签约结果模式:initiate=新建或更新签约申请,already_exists=已存在待确认的签约关系,already_confirmed=已签约" + }, + { + "name": "data.contract", + "type": "object", + "required": true, + "description": "签约关系精简对象(data.mode 非空时返回)" + }, + { + "name": "data.action", + "type": "string", + "required": false, + "description": "initiate 模式下的操作类型:create=新建签约申请,update=更新已有申请" + } + ], + "errors": [ + { + "code": 400, + "message": "counterparty_id / 对方主体ID 参数不能为空" + }, + { + "code": 400, + "message": "counterparty_id / 对方主体ID 参数不合法" + }, + { + "code": 400, + "message": "auth_start 参数不合法" + }, + { + "code": 400, + "message": "auth_end 参数不合法" + }, + { + "code": 400, + "message": "auth_end 不能早于 auth_start" + }, + { + "code": 404, + "message": "签约对象不存在" + } + ] + }, + { + "method": "storeWarehouse.warehouse.confirmSign", + "description": "仓库侧确认签约:作为对方主体确认待签约申请,签约状态从 1(申请中)变为 2(已通过);发起方不能确认自己的申请", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "签约关系ID,兼容 contract_id" + } + ], + "response": [ + { + "name": "data.mode", + "type": "string", + "required": true, + "description": "确认模式标识,固定为 confirm" + }, + { + "name": "data.contract", + "type": "object", + "required": true, + "description": "签约关系精简对象,字段同 storeWarehouse.store.confirmSign 的 data.contract" + } + ], + "errors": [ + { + "code": 400, + "message": "id 参数不能为空" + }, + { + "code": 400, + "message": "当前签约状态不允许确认,仅待签约状态可确认" + }, + { + "code": 403, + "message": "当前主体不在此签约关系中" + }, + { + "code": 403, + "message": "发起方不能确认自己的签约申请" + }, + { + "code": 404, + "message": "签约关系不存在" + } + ] } ] }, diff --git a/script/update-api-doc.cjs b/script/update-api-doc.cjs index 288cc9a..8efdc35 100644 --- a/script/update-api-doc.cjs +++ b/script/update-api-doc.cjs @@ -312,7 +312,8 @@ function applyDocUpdate(doc, groupSpec, methods, docMeta) { function appendChange(changes, change) { const exists = changes.some(item => item && item.version === change.version); assert(!exists, `Duplicate change version detected: ${change.version}`); - changes.push(cloneJson(change)); + // 变更记录保持“新记录在数组开头”的顺序(与 methods/changes/*.json 现有约定一致) + changes.unshift(cloneJson(change)); } function main() { @@ -384,4 +385,4 @@ module.exports = { applyDocUpdate, parseArgs, validateSpec, -}; \ No newline at end of file +};