feat(order): 锁定订单作业门禁与订单列表 lock_status 转 Y/N

- lock_guard: 新增 isLockedOrderStatus,lock_status 非 none 一律视为已锁定
- 储位分配(allocatePicking)跳过锁定订单,skipped_reason=locked
- 快递分配(createWaybillCodePipeline、wave.batchAllocateExpress)跳过锁定订单并返回 skipped_locked_order_ids
- 抓取波次 singleFetchByIds 排除锁定订单并返回 excluded_locked_order_ids
- 自动加团(delivery_order)锁定订单跳过自动分配快递/储位/自动加团
- 订单列表 normalizeOrderListItem 统一 lock_status 输出 Y/N(none→N,其余→Y)
- 同步 methods/system.json、methods/changes/system.json 文档
This commit is contained in:
liufumingren 2026-08-18 16:25:12 +08:00
parent 591a69d35e
commit 3817948b35
9 changed files with 537 additions and 52 deletions

29
app/lib/lock_guard.js Normal file
View File

@ -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,
};

View File

@ -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),
};
}

View File

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

View File

@ -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 到仓库级配置

View File

@ -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,
};
}
/**

View File

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

View File

@ -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"
}
]

View File

@ -2960,7 +2960,7 @@
"name": "list",
"type": "array",
"required": true,
"description": "订单列表(raw 行数据,字段字典见 <window>docs/order-workbench-list-api.md</window> 中的“订单列表 raw 字段字典”章节),本次新增 store_remark(货主备注)字段。"
"description": "订单列表(raw 行数据,字段字典见 <window>docs/order-workbench-list-api.md</window> 中的“订单列表 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": "签约关系不存在"
}
]
}
]
},

View File

@ -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,
};
};