feat(order.wave): 新增 order.wave.fetchableOrderCount 团购可抓取订单数统计接口

- 与 order.wave.groupOrderFetchList 同口径:同一候选条件(step in [1,2,3]、status!=cancel、
  outbound_status!=padding、intercept_status='none'、lock_status='none'、wave_id=0,叠加
  store_id/shop_name/stock_query 过滤)+ items_hash 粗分组 + 团购阈值过滤;
  仅取 id/items_hash/items/sys_logistics_code 四列做内存计数,不分页、不查订单明细
- 返回 data:group_count / order_count / same_order_quantity / raw_order_count /
  warehouse_id / distinguish_express;仓库上下文缺失返回 flag=failure/code=400
- 口径提示:order_count 为命中分组的订单数合计(与 groupOrderFetchList 的 pagination.total=分组数语义不同);
  include_sku 为 groupOrderFetchList 页内过滤参数,本方法不参与统计
- 权限与日志:已加入 wave.js systemInit 的 _noNeedRight / _noNeedLog / _noNeedAuth 名单
  (与 groupOrderFetchList 一致),仅需登录;不产生 wms_permission 记录,无需权限同步与迁移
- 文档:methods/system.json 新增 order.wave.fetchableOrderCount(根版本 0.3.194 -> 0.3.195、
  updatedAt 2026-09-28),methods/changes/system.json 新增变更记录;AI_METHOD_ROUTING.md 由脚本重新生成 service method 清单
- 测试:test/app/service/systemMethods/order/wave.fetchableOrderCount.test.js(8 用例);
  该路径命中仓库 .gitignore 的 test/* 规则,按既有约定未纳入版本管理
This commit is contained in:
liufumingren 2026-09-28 01:32:03 +08:00
parent 1fbc24c904
commit f8081b876f
4 changed files with 332 additions and 73 deletions

File diff suppressed because one or more lines are too long

View File

@ -134,9 +134,9 @@ class WaveService extends OrderBaseService {
constructor(ctx) {
super(ctx);
const _noNeedLogin = '';
const _noNeedRight = 'wavePickTaskCancelSelf,groupOrderFetchList,singleOrderFetchList,waveStrategyList,waveStrategyFallbackOrderList,waveStrategyFetchPda,waveStrategyFetchAdmin,groupFetch,singleFetch,fetch,fetchTaskProgress,batchList,wavePickTaskList,batchCancel,batchCancelTaskProgress,batchRemoveExceptionOrders,batchRemoveExceptionOrdersTaskProgress,batchAllocateExpress,batchAllocateExpressTaskProgress,batchAllocateStorage,batchAllocateStorageTaskProgress,batchAutoGrouping,batchFinishAutoGrouping,batchRemoveOrders,singleFetchByIds,waveStrategyQuickScan,waveStrategyQuickScanTaskProgress,confirmPrintUnclaimedWaveCount';
const _noNeedLog = 'groupOrderFetchList,singleOrderFetchList,waveStrategyList,waveStrategyFallbackOrderList,waveStrategyFetchAdmin,groupFetch,singleFetch,fetch,fetchTaskProgress,batchList,wavePickTaskList,batchCancel,batchCancelTaskProgress,batchRemoveExceptionOrders,batchRemoveExceptionOrdersTaskProgress,batchAllocateExpress,batchAllocateExpressTaskProgress,batchAllocateStorage,batchAllocateStorageTaskProgress,batchAutoGrouping,batchFinishAutoGrouping,batchRemoveOrders,singleFetchByIds,waveStrategyQuickScan,waveStrategyQuickScanTaskProgress,confirmPrintScan,confirmPrintUnclaimedWaveCount';
const _noNeedAuth = 'groupOrderFetchList,singleOrderFetchList,waveStrategyList,waveStrategyFallbackOrderList,waveStrategyFetchPda,waveStrategyFetchAdmin,groupFetch,singleFetch,fetch,fetchTaskProgress,batchList,wavePickTaskList,batchCancel,batchCancelTaskProgress,batchRemoveExceptionOrders,batchRemoveExceptionOrdersTaskProgress,batchAllocateExpress,batchAllocateExpressTaskProgress,batchAllocateStorage,batchAllocateStorageTaskProgress,batchAutoGrouping,batchFinishAutoGrouping,batchRemoveOrders,singleFetchByIds,waveStrategyQuickScan,waveStrategyQuickScanTaskProgress,confirmPrintUnclaimedWaveCount';
const _noNeedRight = 'wavePickTaskCancelSelf,groupOrderFetchList,singleOrderFetchList,fetchableOrderCount,waveStrategyList,waveStrategyFallbackOrderList,waveStrategyFetchPda,waveStrategyFetchAdmin,groupFetch,singleFetch,fetch,fetchTaskProgress,batchList,wavePickTaskList,batchCancel,batchCancelTaskProgress,batchRemoveExceptionOrders,batchRemoveExceptionOrdersTaskProgress,batchAllocateExpress,batchAllocateExpressTaskProgress,batchAllocateStorage,batchAllocateStorageTaskProgress,batchAutoGrouping,batchFinishAutoGrouping,batchRemoveOrders,singleFetchByIds,waveStrategyQuickScan,waveStrategyQuickScanTaskProgress,confirmPrintUnclaimedWaveCount';
const _noNeedLog = 'groupOrderFetchList,singleOrderFetchList,fetchableOrderCount,waveStrategyList,waveStrategyFallbackOrderList,waveStrategyFetchAdmin,groupFetch,singleFetch,fetch,fetchTaskProgress,batchList,wavePickTaskList,batchCancel,batchCancelTaskProgress,batchRemoveExceptionOrders,batchRemoveExceptionOrdersTaskProgress,batchAllocateExpress,batchAllocateExpressTaskProgress,batchAllocateStorage,batchAllocateStorageTaskProgress,batchAutoGrouping,batchFinishAutoGrouping,batchRemoveOrders,singleFetchByIds,waveStrategyQuickScan,waveStrategyQuickScanTaskProgress,confirmPrintScan,confirmPrintUnclaimedWaveCount';
const _noNeedAuth = 'groupOrderFetchList,singleOrderFetchList,fetchableOrderCount,waveStrategyList,waveStrategyFallbackOrderList,waveStrategyFetchPda,waveStrategyFetchAdmin,groupFetch,singleFetch,fetch,fetchTaskProgress,batchList,wavePickTaskList,batchCancel,batchCancelTaskProgress,batchRemoveExceptionOrders,batchRemoveExceptionOrdersTaskProgress,batchAllocateExpress,batchAllocateExpressTaskProgress,batchAllocateStorage,batchAllocateStorageTaskProgress,batchAutoGrouping,batchFinishAutoGrouping,batchRemoveOrders,singleFetchByIds,waveStrategyQuickScan,waveStrategyQuickScanTaskProgress,confirmPrintUnclaimedWaveCount';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
@ -3379,6 +3379,141 @@ class WaveService extends OrderBaseService {
});
}
/**
* 团购可抓取订单数统计。
*
* 口径与 groupOrderFetchList 完全一致(同一候选 where、同一 items_hash 粗分组、
* 同一团购阈值 same_order_quantity 过滤),但**不分页、不查订单明细**,
* 仅返回达到团购阈值分组的数量与组内订单数合计,供前端展示「可抓取订单数」等轻量统计。
*
* 差异说明:groupOrderFetchList 的 pagination.total 是**分组数**(每组订单数在 group_count 内),
* 本方法 order_count 是**订单数合计**,两者口径不同;include_sku 为页内过滤,本方法不参与统计。
*
* @param {Object} [data={}] 请求参数。
* @param {boolean} [data.distinguish_express=false] 是否区分快递(影响分组粒度)。
* @param {number|string} [data.store_id] 货主ID(作为筛选条件)。
* @param {number|string} [data.same_order_quantity] 最小同组订单数量阈值(>=);未传时取仓库配置 min_group_order_fetch_quantity(默认 13)。
* @param {string} [data.shop_name] 店铺名称(模糊匹配)。
* @param {string} [data.stock_query] 商品模糊筛选(stock_warehouse / stock_barcodes → order_items)。
* @return {Promise<Object>} 统一返回结构,data 含 group_count / order_count / same_order_quantity / raw_order_count / warehouse_id / distinguish_express。
*/
async fetchableOrderCount(data = {}) {
const t0 = Date.now();
const requestData = this.isPlainObject(data) ? data : {};
const warehouseId = Number(this.getWarehouseId() || 0);
if (!Number.isInteger(warehouseId) || warehouseId <= 0) {
return this.fail('未识别到当前仓库上下文', {}, 400);
}
const model = await this.getOrderModel('pendingOrder', warehouseId);
const t1 = Date.now();
const distinguishExpress = this.normalizeBoolean(requestData.distinguish_express, false);
const storeId = this.normalizePositiveInteger(requestData.store_id, 'store_id', 0);
const sameOrderQuantityInput = requestData.same_order_quantity;
const hasSameOrderQuantityInput = !(sameOrderQuantityInput === undefined || sameOrderQuantityInput === null || sameOrderQuantityInput === '');
const explicitSameOrderQuantity = hasSameOrderQuantityInput
? this.normalizePositiveInteger(sameOrderQuantityInput, 'same_order_quantity', 0)
: 0;
const minGroupOrderFetchQuantity = await this.getMinGroupOrderFetchQuantity(warehouseId);
const sameOrderQuantity = explicitSameOrderQuantity > 0
? explicitSameOrderQuantity
: minGroupOrderFetchQuantity;
const shopName = this.normalizeShopName(requestData.shop_name);
const stockQuery = String(requestData.stock_query || '').trim();
const where = {
step: { [Op.in]: [ 1, 2, 3 ] },
status: { [Op.ne]: 'cancel' },
outbound_status: { [Op.ne]: 'padding' },
intercept_status: 'none',
lock_status: 'none',
wave_id: 0,
};
if (storeId > 0) {
where.store_id = storeId;
}
if (shopName) {
where.shop_nick = { [Op.like]: `%${shopName}%` };
}
if (stockQuery) {
const stockOrderIds = await this.findOrderIdsByStockQuery(stockQuery, 'order', warehouseId);
if (stockOrderIds.length <= 0) {
return this.success('ok', {
group_count: 0,
order_count: 0,
same_order_quantity: sameOrderQuantity,
raw_order_count: 0,
warehouse_id: warehouseId,
distinguish_express: distinguishExpress,
});
}
where.id = { [Op.in]: stockOrderIds };
}
// 仅取分组基准字段,不取明细(与 groupOrderFetchList Phase 1 同表同 where)
const rawOrders = await model.findAll({
where,
attributes: [ 'id', 'items_hash', 'items', 'sys_logistics_code' ],
raw: true,
});
const t2 = Date.now();
// 纯内存粗分组:items_hash(缺省回落 items)相同即为同组,distinguish_express 时再叠加快递编码
const coarseGroupSizeMap = new Map();
for (const order of rawOrders) {
const coarseKey = this.buildCoarseGroupKey(order, distinguishExpress);
if (!coarseKey) {
continue;
}
coarseGroupSizeMap.set(coarseKey, Number(coarseGroupSizeMap.get(coarseKey) || 0) + 1);
}
// 团购阈值过滤:仅统计同组订单数 >= sameOrderQuantity 的分组
let groupCount = 0;
let orderCount = 0;
for (const groupSize of coarseGroupSizeMap.values()) {
if (groupSize < sameOrderQuantity) {
continue;
}
groupCount += 1;
orderCount += groupSize;
}
const t3 = Date.now();
this.ctx.logger.info('[wave.fetchableOrderCount] 链路耗时', {
warehouseId,
params: { distinguishExpress, storeId, sameOrderQuantity, shopName: shopName || null, stockQuery: stockQuery || null },
counts: {
rawOrders: rawOrders.length,
coarseGroups: coarseGroupSizeMap.size,
fetchableGroups: groupCount,
fetchableOrders: orderCount,
},
timing_ms: {
getModel: t1 - t0,
queryOrders: t2 - t1,
counting: t3 - t2,
total: t3 - t0,
},
});
return this.success('ok', {
group_count: groupCount,
order_count: orderCount,
same_order_quantity: sameOrderQuantity,
raw_order_count: rawOrders.length,
warehouse_id: warehouseId,
distinguish_express: distinguishExpress,
});
}
/**
* 查询当前仓库波次策略列表。
*

View File

@ -1,4 +1,22 @@
[
{
"version": "2026.09.28-order-wave-fetchable-order-count",
"date": "2026-09-28",
"type": "added",
"summary": "新增 order.wave.fetchableOrderCount:统计当前仓库团购可抓取订单数(与 order.wave.groupOrderFetchList 同口径:同一候选条件 + items_hash 粗分组 + 团购阈值过滤),但不分页、不查订单明细,仅返回命中分组数与组内订单数合计。",
"methods": [
"order.wave.fetchableOrderCount"
],
"notes": [
"代码依据:app/service/systemMethods/order/wave.js 新增 async fetchableOrderCount(data)。候选 where 与 groupOrderFetchList 完全一致(step in [1,2,3]、status != cancel、outbound_status != padding、intercept_status='none'、lock_status='none'、wave_id=0,叠加 store_id / shop_name / stock_query 过滤);分组键复用 buildCoarseGroupKey(items_hash 缺省回落 items,distinguish_express=true 时再叠加 sys_logistics_code);阈值同源 getMinGroupOrderFetchQuantity(仓库配置,默认 13);仅取 id/items_hash/items/sys_logistics_code 四列,纯内存计数,不查订单明细。",
"口径差异(重要):groupOrderFetchList 的 pagination.total 是分组数(每组订单数在 item.group_count 内),本方法 order_count 是命中分组的订单数合计、group_count 是命中分组数;include_sku 为 groupOrderFetchList 的页内过滤参数,本方法不参与统计,因此带 include_sku 时两者不保证一致。",
"权限与日志:方法已加入 wave.js systemInit 的 _noNeedRight / _noNeedLog / _noNeedAuth 名单(与 groupOrderFetchList 一致),仅需登录;isNeedAuth=false,不产生 wms_permission 权限记录,无需执行 permission:sync:system-api,也不需要新增迁移。",
"返回结构:成功返回 flag=success/code=1,data 含 group_count / order_count / same_order_quantity / raw_order_count / warehouse_id / distinguish_express;仓库上下文缺失时返回 flag=failure/code=400「未识别到当前仓库上下文」。",
"测试:test/app/service/systemMethods/order/wave.fetchableOrderCount.test.js(8 用例:阈值命中统计、阈值变化、区分快递粒度、store_id+shop_name 进入候选 where、stock_query 空命中短路、仓库上下文缺失 400、默认阈值回落、与 groupOrderFetchList 命中分组订单数合计一致性)。",
"文档变更范围:methods/system.json 在 module=order.wave(订单波次模块)分组 list 末尾新增 1 条 method;根版本 0.3.194 → 0.3.195、updatedAt 2026-09-27 → 2026-09-28;methods/changes/system.json 新增本条(插入数组首位);其余 method 未改动。",
"维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta);本次按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库,后续由维护者决定是否同步入库。"
]
},
{
"version": "2026.09.27-weigh-pack-message-simplify",
"date": "2026-09-27",

View File

@ -1,8 +1,8 @@
{
"module": "system",
"description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内",
"version": "0.3.194",
"updatedAt": "2026-09-27",
"version": "0.3.195",
"updatedAt": "2026-09-28",
"headers": [
{
"name": "platform",
@ -11672,6 +11672,109 @@
"message": "内部错误"
}
]
},
{
"method": "order.wave.fetchableOrderCount",
"description": "统计当前仓库团购可抓取订单数。口径与 order.wave.groupOrderFetchList 完全一致(同一候选条件 + items_hash 粗分组 + 团购阈值过滤),但不分页、不查订单明细,仅返回达到团购阈值分组的数量与组内订单数合计。注意与 groupOrderFetchList 的口径差异:其 pagination.total 是分组数,本方法 order_count 是命中分组的订单数合计。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "distinguish_express",
"type": "boolean",
"required": false,
"source": "body",
"description": "是否区分快递(影响分组粒度):开启后按「结构(items_hash) + 快递编码」分组,关闭(默认)仅按结构分组。"
},
{
"name": "store_id",
"type": "number",
"required": false,
"source": "body",
"description": "货主ID(仅作为筛选条件,需为非负整数)。"
},
{
"name": "same_order_quantity",
"type": "number",
"required": false,
"source": "body",
"description": "最小同组订单数量阈值(>=)。显式传入有效非负整数且大于 0 时按传入值使用;未传入或为 0 时使用仓库配置 min_group_order_fetch_quantity(默认 13)。"
},
{
"name": "shop_name",
"type": "string",
"required": false,
"source": "body",
"description": "店铺名称(shop_nick 模糊匹配)。"
},
{
"name": "stock_query",
"type": "string",
"required": false,
"source": "body",
"description": "商品模糊筛选:经 stock_warehouse / stock_barcodes → order_items 限定候选订单范围;未匹配到任何商品时直接返回 group_count=0 / order_count=0。"
}
],
"response": [
{
"name": "group_count",
"type": "number",
"required": true,
"description": "达到团购阈值的分组数(同组订单数 >= same_order_quantity)。"
},
{
"name": "order_count",
"type": "number",
"required": true,
"description": "可抓取订单数合计(命中分组内订单数之和;不含未达阈值分组的订单,也不含 items_hash/items 均为空无法分组的订单)。"
},
{
"name": "same_order_quantity",
"type": "number",
"required": true,
"description": "本次统计实际使用的团购阈值(入参值或仓库配置值)。"
},
{
"name": "raw_order_count",
"type": "number",
"required": true,
"description": "参与分组统计的候选订单总数(过滤团购阈值之前,便于核对口径)。"
},
{
"name": "warehouse_id",
"type": "number",
"required": true,
"description": "当前仓库ID(取自登录上下文 ctx.user.store_id)。"
},
{
"name": "distinguish_express",
"type": "boolean",
"required": true,
"description": "是否区分快递(回显本次分组粒度)。"
}
],
"errors": [
{
"code": "400",
"message": "未识别到当前仓库上下文"
},
{
"code": "400",
"message": "参数格式错误(如 store_id / same_order_quantity 非非负整数)"
},
{
"code": "500",
"message": "查询失败"
}
]
}
]
},