feat(inventory): 新增库存异步导出功能

- systemMethods 层:export 提交异步任务 + exportTaskProgress 查询进度
- systems 层:exportInventoryList 导出实现(支持按 stock_id 聚合/按 storage_id 明细)
- 导出任务通过 Redis 缓存管理进度状态(TTL 30min)
This commit is contained in:
liufumingren 2026-08-01 03:45:16 +08:00
parent bd6013d7b8
commit 315e366c4c
2 changed files with 515 additions and 3 deletions

View File

@ -2,6 +2,9 @@
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。
@ -10,9 +13,9 @@ class InventoryMethodService extends MainService {
constructor(ctx) {
super(ctx);
const _noNeedLogin = '';
const _noNeedRight = 'list';
const _noNeedLog = 'list';
const _noNeedAuth = 'list,quickPutaway';
const _noNeedRight = 'list,export,exportTaskProgress';
const _noNeedLog = 'list,export,exportTaskProgress';
const _noNeedAuth = 'list,quickPutaway,export,exportTaskProgress';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
@ -75,6 +78,228 @@ class InventoryMethodService extends MainService {
const result = await service.systems.storage.inventory.quickPutaway({ 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;

View File

@ -1686,6 +1686,293 @@ class InventoryService extends Service {
}
}
/**
* 导出库存列表(异步任务内部调用,生成 Excel 并上传)。
*
* where 条件通过 ctx.whereParsed 读取(与 getInventoryList 完全一致),
* 调用方需先执行 prepareWhereContext 设置 ctx.whereParsed。
*
* 支持两种导出模式:
* - stock_location:按 stock_id + space_id(库位)聚合,汇总数量
* - storage:按 storage_id 逐条导出明细
*
* @param {Object} sortParams 排序参数 { sortField, sortOrder }
* @param {boolean} groupByBatch 是否按批次导出(false=聚合,true=逐条明细)
* @return {Promise<Object>} 导出上传结果(含 url/fileKey 等)
*/
async exportInventoryList(sortParams = {}, groupByBatch = false) {
const { ctx, app } = this;
const { Op, fn, col, literal } = app.Sequelize;
const warehouseId = ctx.user.store_id;
const { sortField = 'id', sortOrder = 'DESC' } = sortParams;
const pageSize = 500;
let page = 1;
let hasNext = true;
const rows = [];
// 构建基础 where 条件(与 getInventoryList 完全一致)
const baseWhere = {
[Op.and]: [
{ warehouse_id: warehouseId },
{ is_enabled: 1 },
{ delete_at: null },
],
};
// 动态 where 条件(与 getInventoryList 一致:从 ctx.whereParsed 读取)
const parsed = ctx.whereParsed;
if (parsed && parsed.dynamicConditions && parsed.dynamicConditions.length > 0) {
baseWhere[Op.and].push(...parsed.dynamicConditions);
}
if (groupByBatch) {
// ────── group_by_batch=true:按 storage_id 逐条导出明细 ──────
while (hasNext) {
const { rows: pageRows } = await ctx.model.Storage.findAndCountAll({
where: baseWhere,
attributes: [
'id', 'stock_id', 'space_id', 'batch_no', 'inventory_type',
'quantity', 'locked_quantity', 'available_quantity',
'production_date', 'expiry_date', 'inbound_time', 'inbound_order_no',
'supplier_batch_no', 'store_id', 'warehouse_id',
'created_at', 'updated_at',
],
order: [[ sortField, sortOrder ]],
offset: (page - 1) * pageSize,
limit: pageSize,
include: [
{
model: ctx.model.StockWarehouse,
as: 'stock',
attributes: [ 'id', 'item_code', 'item_name', 'sku_property', 'stock_unit' ],
required: false,
},
{
model: ctx.model.LocationSpace,
as: 'space',
attributes: [ 'id', 'space_code', 'custom_name' ],
required: false,
},
],
raw: true,
nest: true,
});
if (pageRows.length === 0) {
hasNext = false;
break;
}
// 收集 store_id 批量查询货主名称
const storeIds = [ ...new Set(pageRows.map(r => Number(r.store_id)).filter(Boolean)) ];
const storeMap = new Map();
if (storeIds.length > 0) {
try {
const storeRows = await ctx.model.StoreWarehouse.findAll({
attributes: [ 'store_id', 'store_remask' ],
where: { store_id: { [Op.in]: storeIds }, warehouse_id: warehouseId },
raw: true,
});
for (const sr of storeRows) {
storeMap.set(Number(sr.store_id), sr.store_remask || '');
}
} catch (_e) { /* ignore */ }
}
for (const row of pageRows) {
rows.push({
storage_id: row.id,
stock_id: row.stock_id,
item_code: row.stock?.item_code || '',
item_name: row.stock?.item_name || '',
sku_property: row.stock?.sku_property || '',
stock_unit: row.stock?.stock_unit || '',
store_name: storeMap.get(Number(row.store_id)) || '',
space_code: row.space?.space_code || '',
space_name: row.space?.custom_name || '',
batch_no: row.batch_no || '',
inventory_type: row.inventory_type || '',
quantity: row.quantity,
locked_quantity: row.locked_quantity,
available_quantity: row.available_quantity,
production_date: row.production_date ? app.formatDate(row.production_date) : '',
expiry_date: row.expiry_date ? app.formatDate(row.expiry_date) : '',
inbound_time: row.inbound_time ? app.formatDate(row.inbound_time) : '',
inbound_order_no: row.inbound_order_no || '',
supplier_batch_no: row.supplier_batch_no || '',
created_at: row.created_at ? app.formatDate(row.created_at) : '',
updated_at: row.updated_at ? app.formatDate(row.updated_at) : '',
});
}
hasNext = pageRows.length >= pageSize;
page += 1;
}
} else {
// ────── group_by_batch=false(默认):按 stock_id + space_id 聚合 ──────
const groupFields = [ 'stock_id', 'space_id' ];
while (hasNext) {
const pageRows = await ctx.model.Storage.findAll({
where: baseWhere,
attributes: [
'stock_id',
'space_id',
[ fn('MIN', col('wms_storage.store_id')), 'store_id' ],
[ fn('SUM', col('wms_storage.quantity')), 'quantity' ],
[ fn('SUM', col('wms_storage.locked_quantity')), 'locked_quantity' ],
[ fn('SUM', col('wms_storage.available_quantity')), 'available_quantity' ],
[ fn('COUNT', col('wms_storage.id')), 'batch_count' ],
[ fn('MAX', col('wms_storage.inbound_time')), 'last_inbound_time' ],
[ fn('MIN', col('wms_storage.created_at')), 'first_created_at' ],
[ fn('MAX', col('wms_storage.updated_at')), 'last_updated_at' ],
],
group: groupFields,
order: [[ literal('last_inbound_time'), sortOrder ]],
offset: (page - 1) * pageSize,
limit: pageSize,
include: [
{
model: ctx.model.StockWarehouse,
as: 'stock',
attributes: [ 'id', 'item_code', 'item_name', 'sku_property', 'stock_unit' ],
required: false,
},
{
model: ctx.model.LocationSpace,
as: 'space',
attributes: [ 'id', 'space_code', 'custom_name' ],
required: false,
},
],
raw: true,
nest: true,
});
if (pageRows.length === 0) {
hasNext = false;
break;
}
// 收集 store_id 批量查询货主名称
const storeIds = [ ...new Set(pageRows.map(r => Number(r.store_id)).filter(Boolean)) ];
const storeMap = new Map();
if (storeIds.length > 0) {
try {
const storeRows = await ctx.model.StoreWarehouse.findAll({
attributes: [ 'store_id', 'store_remask' ],
where: { store_id: { [Op.in]: storeIds }, warehouse_id: warehouseId },
raw: true,
});
for (const sr of storeRows) {
storeMap.set(Number(sr.store_id), sr.store_remask || '');
}
} catch (_e) { /* ignore */ }
}
for (const row of pageRows) {
rows.push({
stock_id: row.stock_id,
space_id: row.space_id,
item_code: row.stock?.item_code || '',
item_name: row.stock?.item_name || '',
sku_property: row.stock?.sku_property || '',
stock_unit: row.stock?.stock_unit || '',
store_name: storeMap.get(Number(row.store_id)) || '',
space_code: row.space?.space_code || '',
space_name: row.space?.custom_name || '',
quantity: row.quantity,
locked_quantity: row.locked_quantity,
available_quantity: row.available_quantity,
batch_count: row.batch_count,
last_inbound_time: row.last_inbound_time ? app.formatDate(row.last_inbound_time) : '',
created_at: row.first_created_at ? app.formatDate(row.first_created_at) : '',
updated_at: row.last_updated_at ? app.formatDate(row.last_updated_at) : '',
});
}
hasNext = pageRows.length >= pageSize;
page += 1;
}
}
// ── 批量填充商品条码和图片(复用 loadStockAttachments 缓存查询)──
if (rows.length > 0) {
const stockIds = [ ...new Set(
rows.map(r => Number(r.stock_id || 0)).filter(Boolean)
) ];
const { barcodesByStockId, imagesByStockId } = await loadStockAttachments(ctx, stockIds);
for (const row of rows) {
const sid = Number(row.stock_id || 0);
row.barcodes = sid ? (barcodesByStockId.get(sid) || []).join(', ') : '';
row.image_url = sid ? ((imagesByStockId.get(sid) || [])[0] || '') : '';
}
}
// 生成 Excel
const now = new Date();
const dateToken = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}${String(now.getHours()).padStart(2, '0')}${String(now.getMinutes()).padStart(2, '0')}${String(now.getSeconds()).padStart(2, '0')}${String(now.getMilliseconds()).padStart(3, '0')}`;
const modeLabel = groupByBatch ? '库存明细' : '库存汇总';
const sheetName = groupByBatch ? '库存明细' : '库存汇总(按商品+库位)';
const columns = groupByBatch
? [
{ header: '库存记录ID', key: 'storage_id' },
{ header: '商品编码', key: 'item_code' },
{ header: '商品名称', key: 'item_name' },
{ header: '规格', key: 'sku_property' },
{ header: '库存单位', key: 'stock_unit' },
{ header: '货主', key: 'store_name' },
{ header: '库位编码', key: 'space_code' },
{ header: '库位名称', key: 'space_name' },
{ header: '条码', key: 'barcodes' },
{ header: '图片', key: 'image_url' },
{ header: '批次号', key: 'batch_no' },
{ header: '库存类型', key: 'inventory_type' },
{ header: '数量', key: 'quantity' },
{ header: '锁定数量', key: 'locked_quantity' },
{ header: '可用数量', key: 'available_quantity' },
{ header: '生产日期', key: 'production_date' },
{ header: '过期日期', key: 'expiry_date' },
{ header: '入库时间', key: 'inbound_time' },
{ header: '入库单号', key: 'inbound_order_no' },
{ header: '供应商批次号', key: 'supplier_batch_no' },
{ header: '创建时间', key: 'created_at' },
{ header: '更新时间', key: 'updated_at' },
]
: [
{ header: '商品编码', key: 'item_code' },
{ header: '商品名称', key: 'item_name' },
{ header: '规格', key: 'sku_property' },
{ header: '库存单位', key: 'stock_unit' },
{ header: '货主', key: 'store_name' },
{ header: '条码', key: 'barcodes' },
{ header: '图片', key: 'image_url' },
{ header: '库位编码', key: 'space_code' },
{ header: '库位名称', key: 'space_name' },
{ header: '总库存', key: 'quantity' },
{ header: '锁定库存', key: 'locked_quantity' },
{ header: '可用库存', key: 'available_quantity' },
{ header: '批次数', key: 'batch_count' },
{ header: '最近入库时间', key: 'last_inbound_time' },
{ header: '创建时间', key: 'created_at' },
{ header: '更新时间', key: 'updated_at' },
];
return await ctx.service.systems.excel.generateAndUpload({
filename: `${modeLabel}导出_${dateToken}.xlsx`,
dir: `exports/storage/inventory/${warehouseId}`,
category: 'document',
sheets: [{
name: sheetName,
columns,
rows,
}],
});
}
/**
* 生成入库单号。
* 格式:SCRK + 年月日 + 4位流水号