liufumingren 74b3f04b79 feat(storage): 新增按库位查询有量库存商品列表
- systems/storage/inventory.js 新增 getStorageListBySpaceId(spaceId):
  校验库位归属当前仓库(区分「库位不存在」与「库位属于其他仓库」),
  返回该库位 quantity>0 的库存并按 stock_id 汇总,
  商品信息复用 stock_warehouse 通用链路(getStockDetails)补全属性
- systemMethods/storage/inventory.js 开放 listBySpaceId,
  免权限/免鉴权/免日志名单同步补充
2026-09-13 15:31:05 +08:00

392 lines
15 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

'use strict';
const MainService = require('../../main');
const STORAGE_INVENTORY_EXPORT_TASK_CACHE_KEY_PREFIX = 'storage_inventory_export_task_';
const STORAGE_INVENTORY_EXPORT_TASK_CACHE_TTL_SECONDS = 1800;
/**
* 系统方法层:storage.inventory(库存操作接口包装层)。
* 职责:统一包装库存操作接口,调用底层 systems/storage/inventory service。
*/
class InventoryMethodService extends MainService {
constructor(ctx) {
super(ctx);
const _noNeedLogin = '';
const _noNeedRight = 'list,export,exportTaskProgress,listByStockId,listBySpaceId';
const _noNeedLog = 'list,export,exportTaskProgress,listByStockId,listBySpaceId';
const _noNeedAuth = 'list,quickPutaway,directPutaway,export,exportTaskProgress,listByStockId,listBySpaceId';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
/**
* 移库(库位转移):将单条库存从一个库位移动到另一个库位。
* @param {Object} data 请求体
* @param {number} data.storage_id 库存记录ID(必填)
* @param {number} data.target_space_id 目标库位ID(必填)
* @param {number} [data.quantity] 移库数量(可选,默认全部移动)
* @return {Promise<Object>} 统一 success 包装
*/
async transferLocation(data = {}) {
const { service } = this;
const result = await service.systems.storage.inventory.transferLocation(data);
return this.success('ok', result);
}
/**
* 按库位+商品维度移库:自动查找该库位下该商品的所有库存记录,合并移动到目标库位。
* @param {Object} data 请求体
* @param {number} data.space_id 原库位ID(必填)
* @param {number} data.stock_id 商品SKU ID(必填)
* @param {number} data.target_space_id 目标库位ID(必填)
* @param {number} data.quantity 移库数量(必填)
* @return {Promise<Object>} 统一 success 包装
*/
async transferByProduct(data = {}) {
const { service } = this;
const result = await service.systems.storage.inventory.transferByProduct(data);
return this.success('ok', result);
}
/**
* 提取 stock_query 虚拟筛选条件(与订单查询一致)。
* 将其从 where 中移除并返回清洗后的 where 与 stock_query 关键字。
* 兼容 value 为字符串或数组的场景(如 { operator: 'contains', value: ['A', 'B'] }),
* 数组按多关键字处理,由底层 service 取并集解析 stock_id。
* @param {Object} whereInput 原始 where 条件。
* @return {{ where: Object, stockQuery: string|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;
// value 为数组时逐项清洗为字符串数组(多关键字并集搜索)
if (Array.isArray(rawValue)) {
const stockQuery = rawValue
.map(item => String(item).trim())
.filter(Boolean);
return { where: normalizedWhere, stockQuery };
}
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' };value 支持数组(如 { operator: 'contains', value: ['111'] }),多关键字取并集匹配
* @param {Object} [data.pagination] 分页参数 { page, pageSize }
* @param {Object} [data.sort] 排序参数 { sortField, sortOrder }
* @param {boolean} [data.group_by_batch=false] 是否按批次查询
* @return {Promise<Object>} 统一 success 包装
*/
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, 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);
}
/**
* 按库位查询库存商品列表:传入 space_id,判断该库位是否为当前仓库的库位,
* 是则返回该库位下有量库存(quantity > 0)的商品列表(按 stock_id 汇总为一条)。
* 商品信息统一走 stock_warehouse 通用链路(getStockDetails),返回 stock_warehouse 通用属性。
* @param {Object} data 请求体
* @param {number} data.space_id 库位ID(必填)
* @return {Promise<Object>} 统一 success 包装
*/
async listBySpaceId(data = {}) {
const { service } = this;
const result = await service.systems.storage.inventory.getStorageListBySpaceId(data.space_id);
return this.success('ok', result);
}
/**
* 收货单快捷入库:将收货单的明细直接转为入库单,相同商品自动合并数量。
* 要求货主配置中允许收货单快捷入库,否则直接返回失败。
* @param {Object} data 请求体
* @param {number} data.receiving_id 收货单ID(必填)
* @return {Promise<Object>} 统一 success 包装,返回创建的入库单信息
*/
async quickPutaway(data = {}) {
const { service } = this;
const { receiving_id } = data;
const result = await service.systems.storage.inventory.quickPutaway({ receiving_id });
return this.success('ok', result);
}
/**
* 收货单直入库存(一步完成):直接写 wms_storage 库位库存并生成入库单。
* 入库单明细与收货明细一一对应,按收货明细的库位 space_id 入库。
* 要求货主配置中允许收货单直入库存,否则直接返回失败。
* @param {Object} data 请求体
* @param {number} data.receiving_id 收货单ID(必填)
* @return {Promise<Object>} 统一 success 包装,返回创建的入库单信息
*/
async directPutaway(data = {}) {
const { service } = this;
const { receiving_id } = data;
const result = await service.systems.storage.inventory.directPutaway({ receiving_id });
return this.success('ok', result);
}
/**
* 提交库存导出异步任务(入参与 list 一致,复用相同的 where/sort/group_by_batch 语义)。
*
* @param {Object} data 请求体
* @param {Object} [data.where] 查询条件(与 list 完全一致)
* @param {Object} [data.sort] 排序参数 { sortField, sortOrder }(与 list 完全一致)
* @param {boolean} [data.group_by_batch=false] 是否按批次导出,默认 false
* - false:按 stock_id + 库位聚合导出库存汇总
* - true:按 storage_id 逐条导出库存明细
* @return {Promise<Object>} 统一 success 包装,data 为导出任务信息
*/
async export(data = {}) {
const { service } = this;
const groupByBatch = data.group_by_batch === true || data.group_by_batch === 'true';
// 与 list 一致:prepareWhereContext 会设置 ctx.whereParsed,systems 层从中读取条件
this.prepareWhereContext(data);
const { sort = {} } = data;
const sortField = sort.sortField || sort.sort_field;
const sortOrder = sort.sortOrder || sort.sort_order;
const sortParams = {
...(sortField ? { sortField } : {}),
...(sortOrder ? { sortOrder } : {}),
};
const taskId = this.generateExportTaskId();
const taskPayload = {
task_id: taskId,
status: 'submitted',
progress: 0,
message: '导出任务已提交',
result: null,
error: '',
};
await this.setExportTaskProgress(taskId, taskPayload);
setImmediate(async () => {
try {
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: 'running',
progress: 10,
message: '导出任务执行中',
result: null,
error: '',
});
const result = await service.systems.storage.inventory.exportInventoryList(sortParams, groupByBatch);
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: 'success',
progress: 100,
message: '导出任务完成',
result,
error: '',
});
} catch (error) {
const errorMessage = error && error.message ? error.message : `${error}`;
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: 'failed',
progress: 100,
message: '导出任务失败',
result: null,
error: errorMessage,
});
}
});
return this.success('ok', {
...taskPayload,
update_time: Date.now(),
});
}
/**
* 查询库存导出任务进度。
* @param {Object} data 请求体
* @param {string} [data.task_id] 任务ID(下划线写法)
* @param {string} [data.taskId] 任务ID(驼峰写法)
* @return {Promise<Object>} 统一 success 包装
*/
async exportTaskProgress(data = {}) {
const taskId = this.normalizeExportTaskId(data);
if (!taskId) {
return this.success('ok', {
task_id: '',
status: 'not_found',
progress: 0,
message: '任务不存在',
result: null,
error: '',
download_url: '',
update_time: Date.now(),
});
}
const cachedTask = await this.getExportTaskProgress(taskId);
if (!cachedTask) {
return this.success('ok', {
task_id: taskId,
status: 'not_found',
progress: 0,
message: '任务不存在',
result: null,
error: '',
download_url: '',
update_time: Date.now(),
});
}
const safeResult = this.isPlainObject(cachedTask.result) ? cachedTask.result : {};
const downloadUrl = String(
safeResult.url
|| safeResult.cndUrl
|| safeResult.cosUrl
|| safeResult.fileKey
|| ''
);
return this.success('ok', {
task_id: taskId,
...cachedTask,
download_url: downloadUrl,
});
}
// ==================== 导出任务辅助方法 ====================
/**
* 生成库存导出任务ID。
* @return {string} 导出任务ID
*/
generateExportTaskId() {
const warehouseId = this.ctx?.user?.store_id || 'unknown';
const timestamp = Date.now();
const randomToken = Math.random().toString(36).slice(2, 10);
return `storage_inventory_export_${warehouseId}_${timestamp}_${randomToken}`;
}
/**
* 归一化导出任务ID。
* @param {Object} data 请求体
* @param {string} [data.task_id] 任务ID(下划线写法)
* @param {string} [data.taskId] 任务ID(驼峰写法)
* @return {string} 归一化后的任务ID
*/
normalizeExportTaskId(data = {}) {
const normalizedData = this.isPlainObject(data) ? data : {};
return String(normalizedData.task_id || normalizedData.taskId || '').trim();
}
/**
* 获取导出任务缓存键。
* @param {string} taskId 任务ID
* @return {string} 缓存键
*/
getExportTaskCacheKey(taskId = '') {
const normalizedTaskId = String(taskId || '').trim();
if (!normalizedTaskId) {
return '';
}
return `${STORAGE_INVENTORY_EXPORT_TASK_CACHE_KEY_PREFIX}${normalizedTaskId}`;
}
/**
* 写入导出任务进度缓存。
* @param {string} taskId 任务ID
* @param {Object} payload 任务状态载荷
* @return {Promise<void>} 无返回值
*/
async setExportTaskProgress(taskId = '', payload = {}) {
const cacheKey = this.getExportTaskCacheKey(taskId);
if (!cacheKey || typeof this.app.setCacheAsync !== 'function') {
return;
}
const safePayload = this.isPlainObject(payload) ? payload : {};
const progressPayload = {
task_id: String(taskId || '').trim(),
status: String(safePayload.status || 'submitted').trim() || 'submitted',
progress: Number.isFinite(Number(safePayload.progress)) ? Math.min(100, Math.max(0, Math.round(Number(safePayload.progress)))) : 0,
message: String(safePayload.message || ''),
result: safePayload.result ?? null,
error: String(safePayload.error || ''),
update_time: Date.now(),
};
try {
await this.app.setCacheAsync(cacheKey, progressPayload, STORAGE_INVENTORY_EXPORT_TASK_CACHE_TTL_SECONDS);
} catch (error) {
const errorMessage = error && error.message ? error.message : `${error}`;
this.ctx.logger.warn(`[storage.inventory.export] 写入导出任务缓存失败: ${errorMessage}`);
}
}
/**
* 读取导出任务进度缓存。
* @param {string} taskId 任务ID
* @return {Promise<Object|null>} 任务缓存
*/
async getExportTaskProgress(taskId = '') {
const cacheKey = this.getExportTaskCacheKey(taskId);
if (!cacheKey || typeof this.app.getCacheAsync !== 'function') {
return null;
}
try {
const cached = await this.app.getCacheAsync(cacheKey);
if (!this.isPlainObject(cached)) {
return null;
}
return cached;
} catch (error) {
const errorMessage = error && error.message ? error.message : `${error}`;
this.ctx.logger.warn(`[storage.inventory.export] 读取导出任务缓存失败: ${errorMessage}`);
return null;
}
}
}
module.exports = InventoryMethodService;