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
+};