From aacf9c8539cd58a55ec96eaa49fc3d912799d3a9 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sat, 22 Aug 2026 01:57:27 +0800 Subject: [PATCH] =?UTF-8?q?feat(storage):=20=E6=96=B0=E5=A2=9E=E6=8C=89?= =?UTF-8?q?=E5=95=86=E5=93=81=E6=9F=A5=E6=9C=89=E9=87=8F=E5=BA=93=E5=AD=98?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=E4=B8=8E=E5=BA=93=E5=AD=98=E5=88=97=E8=A1=A8?= =?UTF-8?q?=E9=9B=B6=E9=87=8F=E8=BF=87=E6=BB=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - listByStockId:传入 stock_id 返回 quantity>1 的库存,支持 group_by_space 双模式(逐条明细/按库位汇总) - 修复 store_stock 关联未按仓库收敛导致同 id 库存行重复返回,统一改用 buildStoreStockInclude - list/export 基础条件增加 quantity>0,过滤总数量为0的商品或明细行 - list 支持 where.stock_query 虚拟筛选(商品编码/名称/货物编码/条码/SKU ID 模糊匹配) - 重构 getInventoryList 明细分支:提取 _loadInventoryWarningRanges/_formatBatchStorageRows 复用 - 同步 methods/system.json 与 methods/changes/system.json 文档及变更记录 --- .../systemMethods/storage/inventory.js | 55 ++- app/service/systems/storage/inventory.js | 379 +++++++++++++++--- methods/changes/system.json | 77 ++++ methods/system.json | 71 +++- 4 files changed, 517 insertions(+), 65 deletions(-) diff --git a/app/service/systemMethods/storage/inventory.js b/app/service/systemMethods/storage/inventory.js index c4d3253..34857fe 100644 --- a/app/service/systemMethods/storage/inventory.js +++ b/app/service/systemMethods/storage/inventory.js @@ -13,9 +13,9 @@ class InventoryMethodService extends MainService { constructor(ctx) { super(ctx); const _noNeedLogin = ''; - const _noNeedRight = 'list,export,exportTaskProgress'; - const _noNeedLog = 'list,export,exportTaskProgress'; - const _noNeedAuth = 'list,quickPutaway,export,exportTaskProgress'; + const _noNeedRight = 'list,export,exportTaskProgress,listByStockId'; + const _noNeedLog = 'list,export,exportTaskProgress,listByStockId'; + const _noNeedAuth = 'list,quickPutaway,export,exportTaskProgress,listByStockId'; this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth); } @@ -48,10 +48,39 @@ class InventoryMethodService extends MainService { return this.success('ok', result); } + /** + * 提取 stock_query 虚拟筛选条件(与订单查询一致)。 + * 将其从 where 中移除并返回清洗后的 where 与 stock_query 关键字。 + * @param {Object} whereInput 原始 where 条件。 + * @return {{ where: Object, stockQuery: string }} 清洗后的 where 与 stock_query 值。 + */ + extractStockQueryVirtualFilter(whereInput = {}) { + const normalizedWhere = this.isPlainObject(whereInput) + ? { ...whereInput } + : {}; + const stockQueryCondition = normalizedWhere.stock_query; + + delete normalizedWhere.stock_query; + + if (!stockQueryCondition) { + return { where: normalizedWhere, stockQuery: '' }; + } + + const rawValue = this.isPlainObject(stockQueryCondition) + && Object.prototype.hasOwnProperty.call(stockQueryCondition, 'value') + ? stockQueryCondition.value + : stockQueryCondition; + + const stockQuery = typeof rawValue === 'string' ? rawValue.trim() : ''; + + return { where: normalizedWhere, stockQuery }; + } + /** * 库存列表查询(查 wms_storage),支持 where 条件、分页、排序、批次分组。 * @param {Object} data 请求体 * @param {Object} [data.where] 查询条件 + * @param {Object} [data.where.stock_query] 虚拟筛选字段:按商品编码(item_code)/名称(item_name)/货物编码(goods_code)/条码(barcode)/SKU ID 模糊匹配,如 { operator: 'like', value: '111' } * @param {Object} [data.pagination] 分页参数 { page, pageSize } * @param {Object} [data.sort] 排序参数 { sortField, sortOrder } * @param {boolean} [data.group_by_batch=false] 是否按批次查询 @@ -60,8 +89,26 @@ class InventoryMethodService extends MainService { async list(data = {}) { const { service } = this; const { pagination, sort, group_by_batch } = data; + const { where: cleanedWhere, stockQuery } = this.extractStockQueryVirtualFilter(data.where); + data.where = cleanedWhere; this.prepareWhereContext(data); - const result = await service.systems.storage.inventory.getInventoryList(pagination, sort, group_by_batch); + const result = await service.systems.storage.inventory.getInventoryList(pagination, sort, group_by_batch, stockQuery); + return this.success('ok', result); + } + + /** + * 按商品查询库存明细:传入 stock_id,返回该商品在当前仓库下所有数量大于 1 的 storage 行。 + * 支持两种模式:group_by_space=false 不汇总(逐条明细,含效期/预警字段,默认); + * group_by_space=true 按库位汇总数量(不含批次/效期/预警字段)。 + * @param {Object} data 请求体 + * @param {number} data.stock_id 商品SKU ID(必填) + * @param {boolean} [data.group_by_space=false] 是否按库位汇总 + * @return {Promise} 统一 success 包装 + */ + async listByStockId(data = {}) { + const { service } = this; + const groupBySpace = data.group_by_space === true || data.group_by_space === 'true'; + const result = await service.systems.storage.inventory.getStorageListByStockId(data.stock_id, groupBySpace); return this.success('ok', result); } diff --git a/app/service/systems/storage/inventory.js b/app/service/systems/storage/inventory.js index 7ee56a8..6fded1d 100644 --- a/app/service/systems/storage/inventory.js +++ b/app/service/systems/storage/inventory.js @@ -1152,6 +1152,64 @@ class InventoryService extends Service { } } + /** + * 根据商品快捷搜索关键字解析匹配的 stock_id 列表(仓库维度)。 + * 支持按商品编码(item_code)、商品名称(item_name)、货物编码(goods_code)、 + * 条码(barcode)、SKU ID(纯数字时精确匹配)模糊匹配。 + * + * @param {string} keyword 搜索关键字 + * @param {number} warehouseId 仓库ID + * @return {Promise} 匹配的 stock_id 列表 + */ + async resolveStockQueryToStockIds(keyword = '', warehouseId) { + const { ctx, app } = this; + const normalizedKeyword = String(keyword || '').trim(); + if (!normalizedKeyword || !warehouseId) { + return []; + } + + const likePattern = `%${normalizedKeyword}%`; + const exactStockId = /^\d+$/.test(normalizedKeyword) ? Number(normalizedKeyword) : null; + const extraIdCondition = exactStockId !== null ? 'OR sw.id = :exactStockId' : ''; + + const stockRows = await ctx.model.query(` + SELECT DISTINCT sw.id AS stock_id + FROM wms_stock_warehouse sw + WHERE sw.warehouse_id = :warehouseId + AND ( + sw.item_code LIKE :keyword + OR sw.item_name LIKE :keyword + OR sw.goods_code LIKE :keyword + ${extraIdCondition} + ) + `, { + replacements: { warehouseId, keyword: likePattern, exactStockId }, + type: app.Sequelize.QueryTypes.SELECT, + }); + + const barcodeRows = await ctx.model.query(` + SELECT DISTINCT sb.stock_id + FROM wms_stock_barcodes sb + INNER JOIN wms_stock_warehouse sw ON sw.id = sb.stock_id AND sw.warehouse_id = :warehouseId + WHERE sb.barcode LIKE :keyword + `, { + replacements: { warehouseId, keyword: likePattern }, + type: app.Sequelize.QueryTypes.SELECT, + }); + + const stockIdSet = new Set(); + for (const row of stockRows) { + const sid = Number(row.stock_id); + if (sid > 0) stockIdSet.add(sid); + } + for (const row of barcodeRows) { + const sid = Number(row.stock_id); + if (sid > 0) stockIdSet.add(sid); + } + + return [ ...stockIdSet ]; + } + /** * 查询库存列表。 * @@ -1165,9 +1223,10 @@ class InventoryService extends Service { * @param {string} [sortParams.sortField='created_at'] 排序字段(明细模式支持 wms_storage 真实列;汇总模式仅支持 quantity/locked_quantity/available_quantity/batch_count/first_inbound_time/last_inbound_time/production_date/expiry_date,其余回退 last_inbound_time) * @param {string} [sortParams.sortOrder='DESC'] 排序方向 * @param {boolean} [groupByBatch=false] 是否按批次明细返回 + * @param {string} [stockQuery=''] 商品快捷搜索关键字(来自 where.stock_query,按商品编码/名称/货物编码/条码/SKU ID 模糊匹配,解析为 stock_id 过滤) * @return {Promise<{list: Object[], pagination: {page: number, pageSize: number, total: number, totalPages: number}}>} 库存列表结果 */ - async getInventoryList(pageParams = {}, sortParams = {}, groupByBatch = false) { + async getInventoryList(pageParams = {}, sortParams = {}, groupByBatch = false, stockQuery = '') { const { ctx, app } = this; const { Op, fn, col, literal } = app.Sequelize; const nowMs = Date.now(); @@ -1188,6 +1247,8 @@ class InventoryService extends Service { { warehouse_id: warehouseId }, { is_enabled: 1 }, { delete_at: null }, + // 仅返回有量库存:明细模式过滤 quantity=0 的行,汇总模式过滤总量为 0 的商品 + { quantity: { [Op.gt]: 0 } }, ], }; @@ -1197,26 +1258,31 @@ class InventoryService extends Service { baseWhere[Op.and].push(...parsed.dynamicConditions); } + // stock_query 快捷搜索:按商品编码/名称/货物编码/条码/SKU ID 解析为 stock_id IN 条件 + const normalizedKeyword = String(stockQuery || '').trim(); + if (normalizedKeyword) { + const stockIds = await this.resolveStockQueryToStockIds(normalizedKeyword, warehouseId); + if (stockIds.length > 0) { + baseWhere[Op.and].push({ stock_id: { [Op.in]: stockIds } }); + } else { + // stock_query 无匹配结果,直接返回空列表 + return { + list: [], + pagination: { + page, + pageSize, + total: 0, + totalPages: 0, + }, + }; + } + } + const offset = (page - 1) * pageSize; const limit = pageSize; if (groupByBatch) { - let inventoryWarningRanges = []; - try { - const store = await ctx.model.Store.findByPk(warehouseId, { - attributes: [ 'id', 'subject_config' ], - }); - const normalizedSubjectConfig = ctx.model.Store.normalizeSubjectConfig( - store ? store.subject_config : null - ); - inventoryWarningRanges = buildInventoryWarningRanges( - normalizedSubjectConfig && Array.isArray(normalizedSubjectConfig.inventory_warning_rules) - ? normalizedSubjectConfig.inventory_warning_rules - : [] - ); - } catch (error) { - ctx.logger.warn(`[getInventoryList] 库存预警规则读取失败: ${error.message}`); - } + const inventoryWarningRanges = await this._loadInventoryWarningRanges(warehouseId, 'getInventoryList'); // 按批次明细:逐条返回 const { count: total, rows } = await ctx.model.Storage.findAndCountAll({ @@ -1239,12 +1305,11 @@ class InventoryService extends Service { 'remaining_threshold_days', ], include: [ - { - model: ctx.model.StoreWarehouse, - as: 'store_stock', - attributes: [ 'store_id', 'store_remask' ], + ctx.model.StoreWarehouse.buildStoreStockInclude({ + warehouseId, required: false, - }, + attributes: [ 'store_id', 'store_remask' ], + }), ], required: false, }, @@ -1257,34 +1322,7 @@ class InventoryService extends Service { ], }); - const list = rows.map(item => { - const row = item.get({ plain: true }); - const shelfLifeWarningState = getShelfLifeWarningState(row.stock || {}, row.expiry_date, nowMs); - const inventoryWarningPayload = getInventoryWarningPayload( - shelfLifeWarningState.remainingDays, - inventoryWarningRanges - ); - if (row.stock) { - row.stock.is_batch_mgmt_enabled = toBooleanFlag(row.stock.is_batch_mgmt); - row.stock.store_name = row.stock.store_stock?.store_remask || null; - delete row.stock.store_stock; - delete row.stock.is_batch_mgmt; - } - // 货主名称提升到根层级,便于前端直接使用 - row.store_name = row.stock?.store_name || null; - row.created_at = row.created_at ? app.formatDate(row.created_at) : ''; - row.updated_at = row.updated_at ? app.formatDate(row.updated_at) : ''; - row.inbound_time = row.inbound_time ? app.formatDate(row.inbound_time) : ''; - row.production_date = row.production_date ? app.formatDate(row.production_date) : ''; - row.expiry_date = row.expiry_date ? app.formatDate(row.expiry_date) : ''; - row.is_shelf_life_warning_triggered = shelfLifeWarningState.isTriggered; - row.expiry_remaining_days = inventoryWarningPayload.expiry_remaining_days; - row.inventory_warning_level = inventoryWarningPayload.inventory_warning_level; - row.inventory_warning_color = inventoryWarningPayload.inventory_warning_color; - row.inventory_warning_range = inventoryWarningPayload.inventory_warning_range; - row.inventory_warning_tip_text = inventoryWarningPayload.inventory_warning_tip_text; - return row; - }); + const list = this._formatBatchStorageRows(rows, inventoryWarningRanges, nowMs); await enrichInventoryStockAttachments(ctx, list); @@ -1342,12 +1380,11 @@ class InventoryService extends Service { 'remaining_threshold_days', ], include: [ - { - model: ctx.model.StoreWarehouse, - as: 'store_stock', - attributes: [ 'store_id', 'store_remask' ], + ctx.model.StoreWarehouse.buildStoreStockInclude({ + warehouseId, required: false, - }, + attributes: [ 'store_id', 'store_remask' ], + }), ], required: false, }, @@ -1386,6 +1423,236 @@ class InventoryService extends Service { }, }; } + + /** + * 按商品查询库存明细:返回指定 stock_id 下所有数量大于 1 的 storage 行。 + * 支持两种模式: + * - group_by_space=false(默认,不汇总):逐条返回明细,结构与 storage.inventory.list + * 明细模式一致(含批次/效期/库存预警字段); + * - group_by_space=true(按库位汇总):先筛 quantity > 1 的明细行,再按 space_id + * 汇总数量(quantity/locked_quantity/available_quantity),返回行含库位/商品信息, + * 不包含批次与效期/预警字段。 + * + * @param {number} stockId 商品SKU ID(wms_stock_warehouse.id,必填) + * @param {boolean} [groupBySpace=false] 是否按库位汇总 + * @return {Promise} code/message/data 结构,data 中为 { list: [...] } + */ + async getStorageListByStockId(stockId, groupBySpace = false) { + const { ctx, app } = this; + const { Op } = app.Sequelize; + + // ────────── 1. 参数校验 ────────── + const normalizedStockId = Number(stockId); + if (!Number.isInteger(normalizedStockId) || normalizedStockId <= 0) { + return { code: 400, message: 'stock_id 必填且必须为正整数', data: null }; + } + + const warehouseId = ctx.user && ctx.user.store_id; + if (!warehouseId) { + return { code: 400, message: '无法获取当前仓库信息', data: null }; + } + + // ────────── 2. 先筛 quantity > 1 的库存明细(两种模式共用同一查询) ────────── + const nowMs = Date.now(); + const inventoryWarningRanges = await this._loadInventoryWarningRanges(warehouseId, 'getStorageListByStockId'); + + const rows = await ctx.model.Storage.findAll({ + where: { + warehouse_id: warehouseId, + stock_id: normalizedStockId, + quantity: { [Op.gt]: 1 }, + is_enabled: 1, + delete_at: null, + }, + order: [[ 'id', 'DESC' ]], + include: [ + { + model: ctx.model.StockWarehouse, + as: 'stock', + attributes: [ + 'id', + 'item_code', + 'item_name', + 'sku_property', + 'stock_unit', + 'is_batch_mgmt', + 'is_shelf_life_mgmt', + 'remaining_threshold_days', + ], + include: [ + ctx.model.StoreWarehouse.buildStoreStockInclude({ + warehouseId, + required: false, + attributes: [ 'store_id', 'store_remask' ], + }), + ], + required: false, + }, + { + model: ctx.model.LocationSpace, + as: 'space', + attributes: [ 'id', 'space_code', 'custom_name' ], + required: false, + }, + ], + }); + + // ────────── 3. 按模式格式化返回 ────────── + if (groupBySpace) { + // 按库位汇总:汇总数量,不返回批次/效期/预警字段 + const list = this._aggregateStorageRowsBySpace(rows); + await enrichInventoryStockAttachments(ctx, list); + return { code: 200, message: 'ok', data: { list } }; + } + + // 不汇总:逐条明细(含效期/库存预警字段) + const list = this._formatBatchStorageRows(rows, inventoryWarningRanges, nowMs); + await enrichInventoryStockAttachments(ctx, list); + + return { + code: 200, + message: 'ok', + data: { list }, + }; + } + + /** + * 将库存明细行按库位(space_id)汇总:汇总 quantity/locked_quantity/available_quantity, + * 统计批次数并取最早/最晚入库时间。汇总行不含批次与效期字段,保留商品/库位关联信息。 + * + * @param {Array} rows Sequelize 实例数组(或 plain 对象数组) + * @return {Array} 按库位汇总后的数组 + */ + _aggregateStorageRowsBySpace(rows = []) { + const { app } = this; + const groupedMap = new Map(); + + for (const item of rows) { + const row = item && typeof item.get === 'function' ? item.get({ plain: true }) : item; + const spaceId = Number(row.space_id || 0); + const quantity = Number(row.quantity || 0); + const lockedQuantity = Number(row.locked_quantity || 0); + const availableQuantity = Number(row.available_quantity || 0); + const inboundTimeMs = row.inbound_time ? new Date(row.inbound_time).getTime() : null; + + const existing = groupedMap.get(spaceId); + if (!existing) { + groupedMap.set(spaceId, { + warehouse_id: row.warehouse_id, + store_id: row.store_id, + space_id: spaceId, + stock_id: row.stock_id, + quantity, + locked_quantity: lockedQuantity, + available_quantity: availableQuantity, + batch_count: 1, + first_inbound_time: inboundTimeMs, + last_inbound_time: inboundTimeMs, + stock: row.stock || null, + space: row.space || null, + }); + continue; + } + + existing.quantity += quantity; + existing.locked_quantity += lockedQuantity; + existing.available_quantity += availableQuantity; + existing.batch_count += 1; + if (inboundTimeMs !== null && (existing.first_inbound_time === null || inboundTimeMs < existing.first_inbound_time)) { + existing.first_inbound_time = inboundTimeMs; + } + if (inboundTimeMs !== null && (existing.last_inbound_time === null || inboundTimeMs > existing.last_inbound_time)) { + existing.last_inbound_time = inboundTimeMs; + } + } + + return [ ...groupedMap.values() ].map(row => { + const formatted = { ...row }; + if (formatted.stock) { + formatted.stock = { + ...formatted.stock, + is_batch_mgmt_enabled: toBooleanFlag(formatted.stock.is_batch_mgmt), + store_name: formatted.stock.store_stock?.store_remask || null, + }; + delete formatted.stock.store_stock; + delete formatted.stock.is_batch_mgmt; + } + // 货主名称提升到根层级,便于前端直接使用 + formatted.store_name = formatted.stock?.store_name || null; + formatted.first_inbound_time = formatted.first_inbound_time ? app.formatDate(formatted.first_inbound_time) : ''; + formatted.last_inbound_time = formatted.last_inbound_time ? app.formatDate(formatted.last_inbound_time) : ''; + return formatted; + }); + } + + /** + * 读取当前仓库货主配置中的库存预警规则,并转换为按到期天数递增的区间配置。 + * + * @param {number} warehouseId 仓库ID(货主ID) + * @param {string} logTag 日志标记 + * @return {Promise>} 库存预警规则区间列表 + */ + async _loadInventoryWarningRanges(warehouseId, logTag = 'storage.inventory') { + const { ctx } = this; + try { + const store = await ctx.model.Store.findByPk(warehouseId, { + attributes: [ 'id', 'subject_config' ], + }); + const normalizedSubjectConfig = ctx.model.Store.normalizeSubjectConfig( + store ? store.subject_config : null + ); + return buildInventoryWarningRanges( + normalizedSubjectConfig && Array.isArray(normalizedSubjectConfig.inventory_warning_rules) + ? normalizedSubjectConfig.inventory_warning_rules + : [] + ); + } catch (error) { + ctx.logger.warn(`[${logTag}] 库存预警规则读取失败: ${error.message}`); + return []; + } + } + + /** + * 将库存批次明细查询结果整理为接口返回格式: + * 货主名称提升、批次管理标记布尔化、日期格式化、效期与库存预警字段填充。 + * + * @param {Array} rows Sequelize 实例数组(或 plain 对象数组) + * @param {Array} inventoryWarningRanges 库存预警规则区间 + * @param {number} nowMs 当前时间戳 + * @return {Array} 格式化后的明细数组 + */ + _formatBatchStorageRows(rows = [], inventoryWarningRanges = [], nowMs = Date.now()) { + const { app } = this; + return rows.map(item => { + const row = item && typeof item.get === 'function' ? item.get({ plain: true }) : item; + const shelfLifeWarningState = getShelfLifeWarningState(row.stock || {}, row.expiry_date, nowMs); + const inventoryWarningPayload = getInventoryWarningPayload( + shelfLifeWarningState.remainingDays, + inventoryWarningRanges + ); + if (row.stock) { + row.stock.is_batch_mgmt_enabled = toBooleanFlag(row.stock.is_batch_mgmt); + row.stock.store_name = row.stock.store_stock?.store_remask || null; + delete row.stock.store_stock; + delete row.stock.is_batch_mgmt; + } + // 货主名称提升到根层级,便于前端直接使用 + row.store_name = row.stock?.store_name || null; + row.created_at = row.created_at ? app.formatDate(row.created_at) : ''; + row.updated_at = row.updated_at ? app.formatDate(row.updated_at) : ''; + row.inbound_time = row.inbound_time ? app.formatDate(row.inbound_time) : ''; + row.production_date = row.production_date ? app.formatDate(row.production_date) : ''; + row.expiry_date = row.expiry_date ? app.formatDate(row.expiry_date) : ''; + row.is_shelf_life_warning_triggered = shelfLifeWarningState.isTriggered; + row.expiry_remaining_days = inventoryWarningPayload.expiry_remaining_days; + row.inventory_warning_level = inventoryWarningPayload.inventory_warning_level; + row.inventory_warning_color = inventoryWarningPayload.inventory_warning_color; + row.inventory_warning_range = inventoryWarningPayload.inventory_warning_range; + row.inventory_warning_tip_text = inventoryWarningPayload.inventory_warning_tip_text; + return row; + }); + } + /** * 收货单快捷入库:判断货主配置是否允许收货单快捷入库,不允许直接返回失败; * 允许的话使用收货单的明细创建入库单,相同 stock_id 的合并为一条,汇集总数。 @@ -1707,6 +1974,8 @@ class InventoryService extends Service { { warehouse_id: warehouseId }, { is_enabled: 1 }, { delete_at: null }, + // 仅导出有量库存:明细模式过滤 quantity=0 的行,汇总模式过滤总量为 0 的商品 + { quantity: { [Op.gt]: 0 } }, ], }; diff --git a/methods/changes/system.json b/methods/changes/system.json index c70c931..c646a1c 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,66 @@ [ + { + "version": "2026.08.22-storage.inventory.list-filter-zero-quantity", + "date": "2026-08-22", + "type": "enhanced", + "summary": "storage.inventory.list 过滤总数量为 0 的商品或明细行:基础查询条件增加 quantity > 0,明细模式(group_by_batch=true)不再返回 quantity=0 的明细行,合并模式(group_by_batch=false)不再返回总数量为 0 的商品。storage.inventory.export 同步保持一致。", + "methods": [ + "storage.inventory.list", + "storage.inventory.export" + ], + "notes": [ + "app/service/systems/storage/inventory.js:getInventoryList 与 exportInventoryList 的 baseWhere 均增加 { quantity: { [Op.gt]: 0 } },动态 where/stock_query 条件不受影响", + "明细模式:quantity=0 的 storage 行直接过滤;合并模式:某商品所有明细行均无正数量时分组自然消失,总量为 0 的商品不返回", + "storage.inventory.export 入参与 list 语义保持一致(导出同样过滤零量行/零量商品)" + ], + "module": "storage.inventory" + }, + { + "version": "2026.08.22-storage.inventory.listByStockId-group-by-space", + "date": "2026-08-22", + "type": "enhanced", + "summary": "storage.inventory.listByStockId 新增 group_by_space 双模式:false(默认,不汇总)逐条返回 quantity > 1 明细行(含批次/效期/预警字段,行为不变);true(按库位汇总)先筛 quantity > 1 明细行,再按 space_id 汇总 quantity/locked_quantity/available_quantity,返回库位级汇总行(含 batch_count、first/last_inbound_time、stock/space/store_name),不含批次与效期/预警字段。", + "methods": [ + "storage.inventory.listByStockId" + ], + "notes": [ + "app/service/systems/storage/inventory.js:getStorageListByStockId(stockId, groupBySpace=false) 两种模式共用同一查询(先筛 quantity > 1 明细行),group_by_space=true 时用新增 _aggregateStorageRowsBySpace 按 space_id 在内存汇总(求和、批次数、最早/最晚入库时间),并保留商品/库位关联与条码图片附属信息", + "app/service/systemMethods/storage/inventory.js:listByStockId 透传 group_by_space(支持 true/'true' 布尔/字符串)", + "汇总口径:先筛 quantity > 1 的明细行再按库位求和;汇总行不返回批次与效期/库存预警字段" + ], + "module": "storage.inventory" + }, + { + "version": "2026.08.22-storage.inventory.store-stock-join-dedup", + "date": "2026-08-22", + "type": "fixed", + "summary": "修复库存接口按 stock_id 查询返回重复 storage 行(同 id 多条)的问题:store_stock 关联(belongsTo StoreWarehouse,按 store_id 关联)未按仓库收敛,货主在多仓库存在签约行时 JOIN 多行匹配导致同一库存行重复且 store_name 不一致。改为统一使用 StoreWarehouse.buildStoreStockInclude(按 warehouse_id + warehouse_use_status=1 收敛,命中唯一签约行)。", + "methods": [ + "storage.inventory.listByStockId", + "storage.inventory.list" + ], + "notes": [ + "app/service/systems/storage/inventory.js:getStorageListByStockId、getInventoryList(明细模式与合并模式)三处 store_stock 嵌套 include 均改为 buildStoreStockInclude({ warehouseId, required: false, attributes: ['store_id','store_remask'] })", + "wms_store_warehouse 存在 (store_id, warehouse_id) 唯一索引,按仓库收敛后每商品至多命中一行签约关系,不再产生重复明细;合并模式下 SUM(quantity) 也不会因 JOIN 多行而翻倍", + "同时修正 storage.inventory.list 同源隐患(明细模式重复行、合并模式数量翻倍),返回结构不变" + ], + "module": "storage.inventory" + }, + { + "version": "2026.08.22-storage.inventory.listByStockId", + "date": "2026-08-22", + "type": "added", + "summary": "新增 storage.inventory.listByStockId 接口:传入 stock_id,返回该商品在当前仓库下所有 quantity > 1 的 wms_storage 明细行(按 id 倒序),返回结构与 storage.inventory.list 明细模式一致(含 stock 条码/图片、space 库位、货主名称及效期/库存预警字段)。", + "methods": [ + "storage.inventory.listByStockId" + ], + "notes": [ + "app/service/systemMethods/storage/inventory.js 新增 listByStockId 包装方法,并加入 _noNeedRight/_noNeedLog/_noNeedAuth 豁免列表(与 list 一致)", + "app/service/systems/storage/inventory.js 新增 getStorageListByStockId:校验 stock_id 正整数与当前仓库上下文,where 条件 warehouse_id+stock_id+quantity>1+is_enabled=1+delete_at=null,include stock/space 与明细模式一致", + "重构 getInventoryList 明细分支:提取 _loadInventoryWarningRanges 与 _formatBatchStorageRows 复用,现有 storage.inventory.list 行为不变" + ], + "module": "storage.inventory" + }, { "version": "2026.08.21-returnUnpack.create-orderItems", "date": "2026-08-21", @@ -6639,5 +6701,20 @@ "仅文档变更,无业务代码修改" ], "module": "storeWarehouse" + }, + { + "version": "2026.08.21-storage.inventory.list-stock-query", + "date": "2026-08-21", + "type": "updated", + "summary": "storage.inventory.list 新增 where.stock_query 虚拟筛选:按商品编码/名称/货物编码/条码/SKU ID 模糊匹配库存列表", + "methods": [ + "storage.inventory.list" + ], + "notes": [ + "与订单查询一致的 stock_query 虚拟筛选字段,如 where.stock_query = { operator: 'like', value: '111' }。", + "解析链路:stock_query → wms_stock_warehouse(item_code/item_name/goods_code/纯数字精确 id)+ wms_stock_barcodes(barcode)→ stock_id 集合 → wms_storage.stock_id IN 过滤;无匹配时返回空列表。", + "代码变更:systemMethods/storage/inventory.js#list 新增 extractStockQueryVirtualFilter(从 where 提取并移除 stock_query);systems/storage/inventory.js#getInventoryList 新增 stockQuery 参数与 resolveStockQueryToStockIds;methods/system.json 同步 where 参数文档(export 注明暂不支持 stock_query)。" + ], + "module": "storage" } ] diff --git a/methods/system.json b/methods/system.json index e22ef73..0be23eb 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.32", - "updatedAt": "2026-08-19", + "version": "0.3.35", + "updatedAt": "2026-08-22", "headers": [ { "name": "platform", @@ -23633,7 +23633,7 @@ }, { "method": "storage.inventory.list", - "description": "库存列表查询(查 wms_storage),支持 where 条件、分页、排序、批次分组。默认按库位+商品合并数量(合并模式),group_by_batch=true 时返回每条库存明细(明细模式)", + "description": "库存列表查询(查 wms_storage),支持 where 条件、分页、排序、批次分组。默认按库位+商品合并数量(合并模式),group_by_batch=true 时返回每条库存明细(明细模式)。仅返回有量库存:明细模式过滤 quantity=0 的行,合并模式过滤总数量为 0 的商品。", "name": "库存列表", "isNeedAuth": false, "isNeedLogin": true, @@ -23644,7 +23644,7 @@ "type": "object", "required": false, "source": "body", - "description": "统一 where 条件对象,可用字段:stock_id(商品ID)、space_id(库位ID)、store_id(货主ID)、inventory_type(ZP/CC/JS/XS/ZT/DJ/FP)、batch_no(批次号)、inbound_order_no(入库单号)、available_quantity(可用数量,支持 gt/lt)、inbound_time(入库时间,支持 between)、created_at(创建时间,支持 between)" + "description": "统一 where 条件对象,可用字段:stock_id(商品ID)、space_id(库位ID)、store_id(货主ID)、inventory_type(ZP/CC/JS/XS/ZT/DJ/FP)、batch_no(批次号)、inbound_order_no(入库单号)、available_quantity(可用数量,支持 gt/lt)、inbound_time(入库时间,支持 between)、created_at(创建时间,支持 between)、stock_query(虚拟筛选字段:按商品编码/名称/货物编码/条码/SKU ID 模糊匹配,如 { operator: 'like', value: '111' })" }, { "name": "pagination", @@ -23754,7 +23754,7 @@ }, { "method": "storage.inventory.export", - "description": "提交库存导出异步任务。支持两种导出模式(exportMode):stock_location(默认,按 stock_id + 库位聚合导出库存汇总,含库位编码/名称、商品信息、总库存/锁定/可用、批次数、最近入库时间等)、storage(按 storage_id 逐条导出库存明细,含库位编码/名称、商品信息、批次号、库存类型、数量、生产日期、过期日期、入库单号等)。立即返回任务受理信息(task_id/status/progress),不直接返回文件。通过 storage.inventory.exportTaskProgress 查询进度并获取下载地址。", + "description": "提交库存导出异步任务。支持两种导出模式(exportMode):stock_location(默认,按 stock_id + 库位聚合导出库存汇总,含库位编码/名称、商品信息、总库存/锁定/可用、批次数、最近入库时间等)、storage(按 storage_id 逐条导出库存明细,含库位编码/名称、商品信息、批次号、库存类型、数量、生产日期、过期日期、入库单号等)。立即返回任务受理信息(task_id/status/progress),不直接返回文件。通过 storage.inventory.exportTaskProgress 查询进度并获取下载地址。仅导出有量库存(与 storage.inventory.list 一致):明细模式过滤 quantity=0 的行,合并模式过滤总数量为 0 的商品。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -23771,7 +23771,7 @@ "type": "object", "required": false, "source": "body", - "description": "统一 where 条件对象,与 storage.inventory.list 的 where 语义完全一致。支持字段:stock_id(商品ID)、space_id(库位ID)、store_id(货主ID)、inventory_type(ZP/CC/JS/XS/ZT/DJ/FP)、batch_no(批次号)、inbound_order_no(入库单号)、available_quantity(可用数量,支持 gt/lt)、inbound_time(入库时间,支持 between)、created_at(创建时间,支持 between)" + "description": "统一 where 条件对象,与 storage.inventory.list 的 where 语义完全一致(暂不支持 stock_query 虚拟筛选)。支持字段:stock_id(商品ID)、space_id(库位ID)、store_id(货主ID)、inventory_type(ZP/CC/JS/XS/ZT/DJ/FP)、batch_no(批次号)、inbound_order_no(入库单号)、available_quantity(可用数量,支持 gt/lt)、inbound_time(入库时间,支持 between)、created_at(创建时间,支持 between)" }, { "name": "sort", @@ -24164,6 +24164,65 @@ "message": "分页参数不合法" } ] + }, + { + "method": "storage.inventory.listByStockId", + "name": "按商品查询有量库存明细", + "description": "按商品查询库存明细:传入 stock_id,返回该商品在当前仓库下所有数量大于 1(quantity > 1)的 wms_storage 明细行。支持两种模式:group_by_space=false(默认,不汇总)逐条返回明细,结构与 storage.inventory.list 明细模式(group_by_batch=true)一致,含批次字段(batch_no/inventory_type/quantity/locked_quantity/available_quantity/production_date/expiry_date/inbound_time/inbound_order_no/receiving_id/entry_order_id/supplier_id/supplier_batch_no 等)、stock(商品信息,含 barcodes/images 附属信息)、space(库位信息)、store_name(货主名称,来源于当前仓库签约表 store_remask)以及效期/库存预警字段;group_by_space=true(按库位汇总)先筛 quantity > 1 的明细行,再按 space_id 汇总 quantity/locked_quantity/available_quantity,返回行含库位/商品信息与 batch_count、first_inbound_time、last_inbound_time,不含批次与效期/预警字段。仓库上下文来自当前登录用户(ctx.user.store_id)。", + "isNeedAuth": false, + "isNeedLogin": true, + "isNeedRight": false, + "headers": [], + "params": [ + { + "name": "stock_id", + "type": "number", + "required": true, + "source": "body", + "description": "商品SKU ID(wms_stock_warehouse.id,必填)" + }, + { + "name": "group_by_space", + "type": "boolean", + "required": false, + "source": "body", + "description": "是否按库位汇总,默认 false。false=不汇总(逐条明细);true=按库位汇总(先筛 quantity > 1 明细行,再按 space_id 求和)" + } + ], + "response": [ + { + "name": "code", + "type": "number", + "required": true, + "description": "状态码,200=成功" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "结果说明" + }, + { + "name": "data.list", + "type": "array", + "required": true, + "description": "库存数组(quantity > 1,按 id 倒序)。group_by_space=false 时为明细行,每项字段:id、warehouse_id、store_id、space_id、stock_id、batch_no、inventory_type、quantity、locked_quantity、available_quantity、production_date、expiry_date、inbound_time、inbound_order_no、receiving_id、entry_order_id、supplier_id、supplier_batch_no、is_enabled、created_at、updated_at、delete_at;stock 对象(id/item_code/item_name/sku_property/stock_unit/is_shelf_life_mgmt/remaining_threshold_days/is_batch_mgmt_enabled/store_name/barcodes/images);space 对象(id/space_code/custom_name);顶层 store_name(货主名称);is_shelf_life_warning_triggered(效期预警是否触发);expiry_remaining_days/inventory_warning_level/inventory_warning_color/inventory_warning_range/inventory_warning_tip_text(库存预警字段,无预警时为 null)。group_by_space=true 时为按库位汇总行,每项字段:warehouse_id、store_id、space_id、stock_id、quantity/locked_quantity/available_quantity(汇总值)、batch_count(批次数)、first_inbound_time(最早入库时间)、last_inbound_time(最晚入库时间)、stock 对象、space 对象、顶层 store_name;不含批次与效期/预警字段" + } + ], + "errors": [ + { + "code": 400, + "message": "stock_id 必填且必须为正整数" + }, + { + "code": 400, + "message": "无法获取当前仓库信息" + }, + { + "code": 500, + "message": "系统异常" + } + ] } ] },