liufumingren 3e813c4975 fix: 将 storage.report 模块迁移至 stock.report,修正语义错误
库存报表属于 stock(商品库存)域而非 storage(库位存储)域。

变更:
- systemMethods/storage/report.js → systemMethods/stock/report.js
- 类名 StorageReportMethodService → StockReportMethodService
- 缓存键 storage_report_export_ → stock_report_export_
- 日志前缀 [storage.report] → [stock.report]
- methods/system.json: module + 5 method 名同步更新
- methods/changes/system.json: 追加迁移记录
- systems/storage/entry.js: 注释引用修正

旧文件直接删除,不保留兼容(旧 method 名为语义错误)。
2026-07-17 00:30:54 +08:00

509 lines
17 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 STOCK_REPORT_EXPORT_TASK_CACHE_KEY_PREFIX = 'stock_report_export_task_';
const STOCK_REPORT_EXPORT_TASK_CACHE_TTL_SECONDS = 1800;
/**
* 系统方法层:stock.report(库存流水报表接口包装层)。
*/
class StockReportMethodService extends MainService {
constructor(ctx) {
super(ctx);
const _noNeedLogin = '';
const _noNeedRight = 'search,searchStore,export,exportStore,exportTaskProgress';
const _noNeedLog = 'search,searchStore,export,exportStore,exportTaskProgress';
const _noNeedAuth = 'search,searchStore,export,exportStore,exportTaskProgress';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
/**
* 查询库存流水统计报表。
* @param {Object} data 请求体
* @param {Object} [data.where] 查询条件
* @param {Object} [data.sort] 排序参数
* @param {string} [data.sort.sortField] 排序字段(兼容:sort_field)
* @param {string} [data.sort.sortOrder] 排序顺序(兼容:sort_order)
* @param {string|Date} [data.where.start_time] 开始时间
* @param {string|Date} [data.where.end_time] 结束时间
* @param {boolean|string|number} [data.where.by_space=false] 是否按库位返回
* @param {Array<number|string>} [data.where.store_ids] 货主ID列表
* @param {number|number[]} [data.where.stock_id] 商品库存ID(单数)
* @param {number[]} [data.where.stock_ids] 商品库存ID列表(复数)
* @param {string} [data.where.keyword] 商品关键字(按 item_code/item_name/goods_code/barcode 模糊匹配)
* @return {Promise<Object>} 统一 success 包装
*/
async search(data = {}) {
const { service } = this;
const { whereValue = {} } = this.prepareWhereContext(data);
const {
start_time: startTime,
end_time: endTime,
by_space: bySpace,
store_ids: storeIds,
stock_id: stockIdRaw,
stock_ids: stockIdsRaw,
keyword,
sort_field: whereSortField,
sortField: whereSortFieldCamel,
sort_order: whereSortOrder,
sortOrder: whereSortOrderCamel,
} = whereValue;
// 兼容 stock_id(单数)和 stock_ids(数组)
const stockIds = stockIdsRaw !== undefined
? stockIdsRaw
: (stockIdRaw !== undefined ? [ stockIdRaw ] : null);
const { sort = {} } = data;
const {
sort_field: sortFieldSnake,
sortField: sortFieldCamel,
sort_order: sortOrderSnake,
sortOrder: sortOrderCamel,
} = sort || {};
const result = await service.systems.storage.report.search(startTime, endTime, bySpace, storeIds, {
sortField: sortFieldCamel || sortFieldSnake || whereSortFieldCamel || whereSortField,
sortOrder: sortOrderCamel || sortOrderSnake || whereSortOrderCamel || whereSortOrder,
}, 'warehouse', stockIds, keyword);
return this.success('ok', result);
}
/**
* 货主侧库存流水统计报表。
* 以货主维度查询库存流水,只关注商品入库和订单出库,不涉及库位维度。
* @param {Object} data 请求体
* @param {Object} [data.where] 查询条件
* @param {Object} [data.sort] 排序参数
* @param {string} [data.sort.sortField] 排序字段(兼容:sort_field)
* @param {string} [data.sort.sortOrder] 排序顺序(兼容:sort_order)
* @param {string|Date} [data.where.start_time] 开始时间
* @param {string|Date} [data.where.end_time] 结束时间
* @param {Array<number|string>} [data.where.warehouse_ids] 仓库ID列表(可选过滤)
* @param {number|number[]} [data.where.stock_id] 商品库存ID(单数)
* @param {number[]} [data.where.stock_ids] 商品库存ID列表(复数)
* @param {string} [data.where.keyword] 商品关键字(按 item_code/item_name/goods_code/barcode 模糊匹配)
* @return {Promise<Object>} 统一 success 包装
*/
async searchStore(data = {}) {
const { service } = this;
const { whereValue = {} } = this.prepareWhereContext(data);
const {
start_time: startTime,
end_time: endTime,
warehouse_ids: warehouseIdsRaw,
warehouse_id: warehouseIdRaw,
stock_id: stockIdRaw,
stock_ids: stockIdsRaw,
keyword,
sort_field: whereSortField,
sortField: whereSortFieldCamel,
sort_order: whereSortOrder,
sortOrder: whereSortOrderCamel,
} = whereValue;
// 兼容 warehouse_id(单数)和 warehouse_ids(数组)
const warehouseIds = warehouseIdsRaw !== undefined
? warehouseIdsRaw
: (warehouseIdRaw !== undefined ? [ warehouseIdRaw ] : undefined);
// 兼容 stock_id(单数)和 stock_ids(数组)
const stockIds = stockIdsRaw !== undefined
? stockIdsRaw
: (stockIdRaw !== undefined ? [ stockIdRaw ] : null);
const { sort = {} } = data;
const {
sort_field: sortFieldSnake,
sortField: sortFieldCamel,
sort_order: sortOrderSnake,
sortOrder: sortOrderCamel,
} = sort || {};
// 货主侧不涉及库位维度(by_space 固定为 false)
const result = await service.systems.storage.report.search(
startTime,
endTime,
false,
warehouseIds, // store 模式下 storeIds 参数实际承载 warehouse_id 过滤
{
sortField: sortFieldCamel || sortFieldSnake || whereSortFieldCamel || whereSortField,
sortOrder: sortOrderCamel || sortOrderSnake || whereSortOrderCamel || whereSortOrder,
},
'store',
stockIds,
keyword
);
return this.success('ok', result);
}
/**
* 货主侧提交库存报表导出任务。
* 与 export 逻辑一致但使用货主维度,只关注商品入库和订单出库,不涉及库位维度。
* 异步执行,立即返回任务ID。
* @param {Object} data 请求体
* @param {Object} [data.where] 查询条件
* @param {Object} [data.sort] 排序参数
* @param {string} [data.sort.sortField] 排序字段(兼容:sort_field)
* @param {string} [data.sort.sortOrder] 排序顺序(兼容:sort_order)
* @param {string|Date} [data.where.start_time] 开始时间
* @param {string|Date} [data.where.end_time] 结束时间
* @param {Array<number|string>} [data.where.warehouse_ids] 仓库ID列表
* @param {number|number[]} [data.where.stock_id] 商品库存ID(单数)
* @param {number[]} [data.where.stock_ids] 商品库存ID列表(复数)
* @param {string} [data.where.keyword] 商品关键字(模糊匹配)
* @param {string} [data.export_mode] 导出模式:'item' 导出含锁定类型的全部变更记录
* @param {string} [data.exportMode] 导出模式(驼峰写法,同 export_mode)
* @return {Promise<Object>} 统一 success 包装(返回任务ID)
*/
async exportStore(data = {}) {
const { service } = this;
const { whereValue = {} } = this.prepareWhereContext(data);
const {
start_time: startTime,
end_time: endTime,
warehouse_ids: warehouseIdsRaw,
warehouse_id: warehouseIdRaw,
stock_id: stockIdRaw,
stock_ids: stockIdsRaw,
keyword,
sort_field: whereSortField,
sortField: whereSortFieldCamel,
sort_order: whereSortOrder,
sortOrder: whereSortOrderCamel,
} = whereValue;
// 兼容 warehouse_id(单数)和 warehouse_ids(数组)
const warehouseIds = warehouseIdsRaw !== undefined
? warehouseIdsRaw
: (warehouseIdRaw !== undefined ? [ warehouseIdRaw ] : undefined);
// 兼容 stock_id(单数)和 stock_ids(数组)
const stockIds = stockIdsRaw !== undefined
? stockIdsRaw
: (stockIdRaw !== undefined ? [ stockIdRaw ] : null);
const { sort = {} } = data;
const {
sort_field: sortFieldSnake,
sortField: sortFieldCamel,
sort_order: sortOrderSnake,
sortOrder: sortOrderCamel,
} = sort || {};
const exportMode = String(data.export_mode || data.exportMode || '').trim();
const taskId = this.generateExportTaskId();
const taskPayload = {
task_id: taskId,
status: 'submitted',
progress: 0,
message: '导出任务已提交',
result: null,
error: '',
};
await this.setExportTaskProgress(taskId, taskPayload);
const sortOption = {
sortField: sortFieldCamel || sortFieldSnake || whereSortFieldCamel || whereSortField,
sortOrder: sortOrderCamel || sortOrderSnake || whereSortOrderCamel || whereSortOrder,
};
setImmediate(async () => {
try {
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: 'running',
progress: 10,
message: '导出任务执行中',
result: null,
error: '',
});
const result = await service.systems.storage.report.export(
startTime, endTime, false, warehouseIds,
sortOption, exportMode, 'store', stockIds, keyword
);
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 {Object} [data.where] 查询条件
* @param {Object} [data.sort] 排序参数
* @param {string} [data.sort.sortField] 排序字段(兼容:sort_field)
* @param {string} [data.sort.sortOrder] 排序顺序(兼容:sort_order)
* @param {string|Date} [data.where.start_time] 开始时间
* @param {string|Date} [data.where.end_time] 结束时间
* @param {boolean|string|number} [data.where.by_space=false] 是否按库位返回
* @param {Array<number|string>} [data.where.store_ids] 货主ID列表
* @param {number|number[]} [data.where.stock_id] 商品库存ID(单数)
* @param {number[]} [data.where.stock_ids] 商品库存ID列表(复数)
* @param {string} [data.where.keyword] 商品关键字(模糊匹配)
* @param {string} [data.export_mode] 导出模式:'item' 导出含锁定类型的全部变更记录,不传则排除锁定类型
* @param {string} [data.exportMode] 导出模式(驼峰写法,同 export_mode)
* @return {Promise<Object>} 统一 success 包装(返回任务ID)
*/
async export(data = {}) {
const { service } = this;
const { whereValue = {} } = this.prepareWhereContext(data);
const {
start_time: startTime,
end_time: endTime,
by_space: bySpace,
store_ids: storeIds,
stock_id: stockIdRaw,
stock_ids: stockIdsRaw,
keyword,
sort_field: whereSortField,
sortField: whereSortFieldCamel,
sort_order: whereSortOrder,
sortOrder: whereSortOrderCamel,
} = whereValue;
// 兼容 stock_id(单数)和 stock_ids(数组)
const stockIds = stockIdsRaw !== undefined
? stockIdsRaw
: (stockIdRaw !== undefined ? [ stockIdRaw ] : null);
const { sort = {} } = data;
const {
sort_field: sortFieldSnake,
sortField: sortFieldCamel,
sort_order: sortOrderSnake,
sortOrder: sortOrderCamel,
} = sort || {};
const exportMode = String(data.export_mode || data.exportMode || '').trim();
const taskId = this.generateExportTaskId();
const taskPayload = {
task_id: taskId,
status: 'submitted',
progress: 0,
message: '导出任务已提交',
result: null,
error: '',
};
await this.setExportTaskProgress(taskId, taskPayload);
const sortOption = {
sortField: sortFieldCamel || sortFieldSnake || whereSortFieldCamel || whereSortField,
sortOrder: sortOrderCamel || sortOrderSnake || whereSortOrderCamel || whereSortOrder,
};
setImmediate(async () => {
try {
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: 'running',
progress: 10,
message: '导出任务执行中',
result: null,
error: '',
});
const result = await service.systems.storage.report.export(startTime, endTime, bySpace, storeIds, sortOption, exportMode, 'warehouse', stockIds, keyword);
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 `stock_report_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 `${STOCK_REPORT_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, STOCK_REPORT_EXPORT_TASK_CACHE_TTL_SECONDS);
} catch (error) {
this.ctx.logger.warn('[stock.report.export] 写入导出任务缓存失败: %s', error && error.message ? error.message : error);
}
}
/**
* 读取导出任务进度缓存。
* @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) {
this.ctx.logger.warn('[stock.report.export] 读取导出任务缓存失败: %s', error && error.message ? error.message : error);
return null;
}
}
}
module.exports = StockReportMethodService;