feat(storage): 新增按商品查有量库存接口与库存列表零量过滤

- 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 文档及变更记录
This commit is contained in:
liufumingren 2026-08-22 01:57:27 +08:00
parent 84929b6904
commit aacf9c8539
4 changed files with 517 additions and 65 deletions

View File

@ -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<Object>} 统一 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);
}

View File

@ -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<number[]>} 匹配的 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<Object>} 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<Object>} rows Sequelize 实例数组(或 plain 对象数组)
* @return {Array<Object>} 按库位汇总后的数组
*/
_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<Array<Object>>} 库存预警规则区间列表
*/
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<Object>} rows Sequelize 实例数组(或 plain 对象数组)
* @param {Array<Object>} inventoryWarningRanges 库存预警规则区间
* @param {number} nowMs 当前时间戳
* @return {Array<Object>} 格式化后的明细数组
*/
_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 } },
],
};

View File

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

View File

@ -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": "系统异常"
}
]
}
]
},