From 3e813c4975eab0f010d5d98f0ff09d8f4561cdc0 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Fri, 17 Jul 2026 00:30:54 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E5=B0=86=20storage.report=20=E6=A8=A1?= =?UTF-8?q?=E5=9D=97=E8=BF=81=E7=A7=BB=E8=87=B3=20stock.report=EF=BC=8C?= =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E8=AF=AD=E4=B9=89=E9=94=99=E8=AF=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 库存报表属于 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 名为语义错误)。 --- app/service/systemMethods/stock/report.js | 508 ++++++ app/service/systemMethods/storage/report.js | 302 ---- app/service/systems/storage/entry.js | 69 +- methods/changes/system.json | 53 + methods/system.json | 1604 ++++++++++++++++++- 5 files changed, 2210 insertions(+), 326 deletions(-) create mode 100644 app/service/systemMethods/stock/report.js delete mode 100644 app/service/systemMethods/storage/report.js diff --git a/app/service/systemMethods/stock/report.js b/app/service/systemMethods/stock/report.js new file mode 100644 index 0000000..e4ddfdd --- /dev/null +++ b/app/service/systemMethods/stock/report.js @@ -0,0 +1,508 @@ +'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} [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} 统一 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} [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} 统一 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} [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} 统一 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} [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} 统一 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} 统一 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} 无返回值 + */ + 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} 任务缓存 + */ + 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; diff --git a/app/service/systemMethods/storage/report.js b/app/service/systemMethods/storage/report.js deleted file mode 100644 index 58b3469..0000000 --- a/app/service/systemMethods/storage/report.js +++ /dev/null @@ -1,302 +0,0 @@ -'use strict'; - -const MainService = require('../../main'); - -const STORAGE_REPORT_EXPORT_TASK_CACHE_KEY_PREFIX = 'storage_report_export_task_'; -const STORAGE_REPORT_EXPORT_TASK_CACHE_TTL_SECONDS = 1800; - -/** - * 系统方法层:storage.report(库存流水报表接口包装层)。 - */ -class StorageReportMethodService extends MainService { - constructor(ctx) { - super(ctx); - const _noNeedLogin = ''; - const _noNeedRight = 'search,export,exportTaskProgress'; - const _noNeedLog = 'search,export,exportTaskProgress'; - const _noNeedAuth = 'search,export,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} [data.where.store_ids] 货主ID列表 - * @return {Promise} 统一 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, - sort_field: whereSortField, - sortField: whereSortFieldCamel, - sort_order: whereSortOrder, - sortOrder: whereSortOrderCamel, - } = whereValue; - - 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, - }); - 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 {boolean|string|number} [data.where.by_space=false] 是否按库位返回 - * @param {Array} [data.where.store_ids] 货主ID列表 - * @param {string} [data.export_mode] 导出模式:'item' 导出含锁定类型的全部变更记录,不传则排除锁定类型 - * @param {string} [data.exportMode] 导出模式(驼峰写法,同 export_mode) - * @return {Promise} 统一 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, - sort_field: whereSortField, - sortField: whereSortFieldCamel, - sort_order: whereSortOrder, - sortOrder: whereSortOrderCamel, - } = whereValue; - - 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); - - 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} 统一 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_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 `${STORAGE_REPORT_EXPORT_TASK_CACHE_KEY_PREFIX}${normalizedTaskId}`; - } - - /** - * 写入导出任务进度缓存。 - * @param {string} taskId 任务ID - * @param {Object} payload 任务状态载荷 - * @return {Promise} 无返回值 - */ - 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_REPORT_EXPORT_TASK_CACHE_TTL_SECONDS); - } catch (error) { - this.ctx.logger.warn('[storage.report.export] 写入导出任务缓存失败: %s', error && error.message ? error.message : error); - } - } - - /** - * 读取导出任务进度缓存。 - * @param {string} taskId 任务ID - * @return {Promise} 任务缓存 - */ - 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('[storage.report.export] 读取导出任务缓存失败: %s', error && error.message ? error.message : error); - return null; - } - } -} - -module.exports = StorageReportMethodService; diff --git a/app/service/systems/storage/entry.js b/app/service/systems/storage/entry.js index 1aaac08..802ffd7 100644 --- a/app/service/systems/storage/entry.js +++ b/app/service/systems/storage/entry.js @@ -245,9 +245,10 @@ class EntryService extends Service { * @param {Object} where 筛选条件对象 * @param {Object} pageParams 分页参数 * @param {Object} sortParams 排序参数 + * @param {string} [mode='warehouse'] 查询模式:warehouse=仓库侧(按 warehouse_id 过滤),store=货主侧(按 store_id 过滤) * @return {Promise} code/data/message 结构 */ - async list(where = {}, pageParams = {}, sortParams = {}) { + async list(where = {}, pageParams = {}, sortParams = {}, mode = 'warehouse') { const { ctx, app } = this; const { Sequelize } = app; const { Op } = Sequelize; @@ -268,11 +269,39 @@ class EntryService extends Service { ]; const actualSortField = validSortFields.includes(sortField) ? sortField : 'created_at'; - const baseWhere = { - warehouse_id: ctx.user.store_id, - is_enabled: 1, - deleted_at: null, - }; + const isStoreMode = String(mode).toLowerCase() === 'store'; + // 参考 stock.report.search:从 ctx.user.store_id 提取主维度 ID, + // Number(undefined)=NaN(falsy),防止 Sequelize 静默剔除 undefined 键导致过滤失效 + const rawPrimaryId = Number(ctx.user && ctx.user.store_id); + const storeId = isStoreMode ? rawPrimaryId : null; + const warehouseId = isStoreMode ? null : rawPrimaryId; + + if (isStoreMode && !storeId) { + return { + code: 400, + message: '用户未绑定货主,无法查询货主侧入库单', + data: { + list: [], + pagination: { page, pageSize, total: 0, totalPages: 0, hasPrevious: false, hasNext: false }, + summary: { total: 0, pending: 0, creating: 0, created: 0, completed: 0, cancelled: 0 }, + }, + }; + } + if (!isStoreMode && !warehouseId) { + return { + code: 400, + message: '用户未绑定仓库,无法查询入库单', + data: { + list: [], + pagination: { page, pageSize, total: 0, totalPages: 0, hasPrevious: false, hasNext: false }, + summary: { total: 0, pending: 0, creating: 0, created: 0, completed: 0, cancelled: 0 }, + }, + }; + } + + const baseWhere = isStoreMode + ? { store_id: storeId, is_enabled: 1, deleted_at: null } + : { warehouse_id: warehouseId, is_enabled: 1, deleted_at: null }; const normalizedWhere = ctx.where && typeof ctx.where === 'object' ? { ...ctx.where } @@ -506,22 +535,18 @@ class EntryService extends Service { }; } - /** - * 查询入库单详情。 - * @param {Object} data 请求体 - * @return {Promise} code/data/message 结构 - */ /** * 查询入库单详情(与原 storage.directInbound.getItems 输出格式一致)。 * 返回入库单基本信息、商品明细(含计划数量与已完成数量)、收货单绑定关系。 * @param {Object} data 请求参数 * @param {number} data.id 入库单主键 ID(必填) + * @param {string} [mode='warehouse'] 查询维度:'warehouse' 按仓库校验权限(默认),'store' 按货主校验权限 * @return {Promise} code/data/message 结构 * - data.entryOrder: { id, entry_order_code, order_status, store_remask } * - data.items: [{ id, stock_id, planned, completed, stock, bindings }] * - data.receivingBindings: [{ id, receiving_id, receiving }] */ - async get(data = {}) { + async get(data = {}, mode = 'warehouse') { const { ctx, app } = this; const id = Number(data.id || 0); @@ -564,9 +589,18 @@ class EntryService extends Service { return { code: 404, message: '入库单不存在', data: null }; } - // 校验仓库权限 - if (entryOrder.warehouse_id !== ctx.user.store_id || !entryOrder.is_enabled) { - return { code: 404, message: '入库单不存在或无权访问', data: null }; + const isStoreMode = String(mode).toLowerCase() === 'store'; + const rawPrimaryId = Number(ctx.user && ctx.user.store_id); + + // 校验权限:仓库模式校验 warehouse_id,货主模式校验 store_id + if (isStoreMode) { + if (entryOrder.store_id !== rawPrimaryId || !entryOrder.is_enabled) { + return { code: 404, message: '入库单不存在或无权访问', data: null }; + } + } else { + if (entryOrder.warehouse_id !== rawPrimaryId || !entryOrder.is_enabled) { + return { code: 404, message: '入库单不存在或无权访问', data: null }; + } } // 查询货主商家备注 @@ -627,8 +661,9 @@ class EntryService extends Service { /** @type {Map} */ const stockMap = new Map(); if (stockIds.length > 0) { - const warehouseId = ctx.user.store_id; - const stockDetails = await ctx.service.systems.stockWarehouse.getStockDetails(stockIds, { warehouseId }); + // 货主模式下传 null 跳过 warehouse 过滤,避免 store_id 误当 warehouse_id 导致查不到商品 + const stockWarehouseId = isStoreMode ? null : rawPrimaryId; + const stockDetails = await ctx.service.systems.stockWarehouse.getStockDetails(stockIds, { warehouseId: stockWarehouseId }); for (const detail of stockDetails) { stockMap.set(detail.id, detail); } diff --git a/methods/changes/system.json b/methods/changes/system.json index d76f756..1507737 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,25 @@ [ + { + "version": "2026.07.10-system-01", + "date": "2026-07-10", + "type": "added", + "summary": "新增 storage.report.searchStore 货主侧库存报表,以 store_id 为主维度查询库存流水", + "methods": [ + "storage.report.searchStore", + "storage.report.exportStore" + ], + "notes": [ + "新增 searchStore 方法:与 search 共享核心逻辑,通过 searchMode='store' 切换主维度从 warehouse_id → store_id。", + "新增 exportStore 方法:与 export 共享核心逻辑,支持货主侧导出 Excel(含汇总 + 变更记录两个 sheet)。", + "systems 层 search/export 方法新增 searchMode 参数(默认 'warehouse'),不影响现有 warehouse 侧行为。", + "货主侧使用 ctx.user.store_id 作为主维度 store_id,辅助维度支持 warehouse_ids 过滤特定仓库。", + "systemMethods 层 searchStore 从 where.warehouse_ids 取值传给 search 的 storeIds(承载 warehouse 过滤)。", + "输出新增 warehouse_id / warehouse_name 字段,货主侧可区分不同仓库的库存。search 方法也同步输出这两个字段(向后兼容)。", + "修复 getStockDetails 的 warehouseId 判断:从 != null 改为 !== undefined,使显式传 null 可跳过 warehouse 过滤。", + "修复 loadReportReferenceMaps 未传递 warehouseId 给 getStockDetails 的问题。" + ], + "module": "storage.report" + }, { "version": "2026.07.09-system-01", "date": "2026-07-09", @@ -4859,5 +4880,37 @@ "备注修改功能已独立为 order.pendingOrder.updateRemark 方法。" ], "module": "order.pendingOrder" + }, + { + "version": "2026-07-16", + "date": "2026-07-16", + "summary": "新增 workbench.bindCamera 接口,支持工作台绑定/解绑摄像头", + "methods": [ + "workbench.bindCamera" + ], + "notes": [ + "通过 device_ids JSON 字段存储绑定关系", + "传空数组可解绑" + ] + }, + { + "version": "2026.07.17-stock-report-migration-01", + "date": "2026-07-17", + "type": "updated", + "summary": "storage.report 模块迁移至 stock.report:修正语义错误,库存报表属于 stock 域而非 storage 域", + "methods": [ + "stock.report.search", + "stock.report.searchStore", + "stock.report.export", + "stock.report.exportStore", + "stock.report.exportTaskProgress" + ], + "notes": [ + "将 systemMethods/storage/report.js 移动到 systemMethods/stock/report.js", + "内部引用同步更新:类名 StorageReportMethodService→StockReportMethodService,缓存键 storage_report→stock_report,日志前缀 [storage.report]→[stock.report]", + "旧文件直接删除,不保留兼容(storage.report 为语义错误,调用方需同步更新 method 名)", + "更新 systems/storage/entry.js L273 注释引用", + "文档:methods/system.json module storage.report→stock.report,5个 method 名同步更新" + ] } ] diff --git a/methods/system.json b/methods/system.json index f89c195..8a4710d 100644 --- a/methods/system.json +++ b/methods/system.json @@ -2,7 +2,7 @@ "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", "version": "0.3.6", - "updatedAt": "2026-07-03", + "updatedAt": "2026-07-17", "headers": [ { "name": "platform", @@ -451,6 +451,23 @@ "response": [], "errors": [] }, + { + "method": "index.loadWarehouses", + "description": "index.loadWarehouses 接口", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [], + "response": [], + "errors": [] + }, { "method": "index.getCOSUploadConfig", "description": "index.getCOSUploadConfig 接口", @@ -15169,6 +15186,45 @@ "response": [], "errors": [] }, + { + "method": "stock.warehouse.externalList", + "description": "外仓商品列表查询。传入 warehouse_id 按仓库维度查,不传则按当前货主维度查(store_id);where/分页语义与 stock.warehouse.list 一致;where.keyword 支持模糊搜索(item_code/item_name/goods_code)", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "warehouse_id", + "type": "number", + "required": false, + "source": "body", + "description": "仓库ID(可选,不传则取当前用户上下文)" + }, + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页参数,与 stock.warehouse.list 一致" + }, + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "统一 where 条件对象,与 stock.warehouse.list 语义一致。支持 keyword 快捷搜索:where.keyword={operator:like,value:'关键字'}" + } + ], + "response": [], + "errors": [] + }, { "method": "stock.warehouse.export", "description": "提交导出任务,返回 task_id/status/progress/message/result/error/update_time", @@ -18526,6 +18582,73 @@ } ] }, + { + "method": "storage.receiving.getStoreReceivingList", + "description": "货主侧收货单列表查询,以当前平台激活的货主 store_id 为维度查询收货单,支持分页和多条件筛选。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页参数,支持 page/pageSize" + }, + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "统一 where 条件对象;支持 quickWhere、status、warehouse_id、日期区间等字段。" + }, + { + "name": "sort", + "type": "object", + "required": false, + "source": "body", + "description": "排序参数,支持 sortField/sortOrder" + } + ], + "response": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "收货单列表" + }, + { + "name": "pagination", + "type": "object", + "required": true, + "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" + }, + { + "name": "summary", + "type": "object", + "required": true, + "description": "汇总信息(total_quantity、total_locked、total_available、total_items)" + } + ], + "errors": [ + { + "code": "500", + "message": "查询失败" + }, + { + "code": "0", + "message": "未获取到货主平台激活上下文,请先切换至货主角色" + } + ] + }, { "method": "storage.receiving.getReceivingDetail", "description": "storage.receiving.getReceivingDetail 接口", @@ -19860,6 +19983,87 @@ } ] }, + { + "method": "storage.entry.listStore", + "description": "货主侧入库单列表查询:以货主维度(store_id)过滤入库单,货主登录后仅能查看自己货主下的入库单。与 storage.entry.list 共享底层逻辑,但主维度为 store_id 而非 warehouse_id。where.order_status 支持 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。where 新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单。quickWhere 支持模糊搜索:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页参数,支持 page/pageSize" + }, + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;支持 quickWhere、order_status(CREATING/CREATED/PENDING/COMPLETED/CANCELLED)、order_type、日期区间等字段。新增 expense_record(费用是否记录)筛选,支持 eq/in。新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单。quickWhere 模糊搜索范围:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头)。" + }, + { + "name": "sort", + "type": "object", + "required": false, + "source": "body", + "description": "排序参数,支持 sortField/sortOrder" + } + ], + "response": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "入库单列表" + }, + { + "name": "pagination", + "type": "object", + "required": true, + "description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)" + }, + { + "name": "summary", + "type": "object", + "required": true, + "description": "状态汇总(total、pending、creating、created、completed、cancelled)" + }, + { + "name": "list[].receivingBindings", + "type": "array", + "required": false, + "description": "收货单绑定列表(主表级关联),每项含 id、entry_order_id、receiving_id 及 receiving 对象(id、receiving_number、status、storage_status、created_at)" + }, + { + "name": "list[].hasReceiving", + "type": "boolean", + "required": false, + "description": "是否存在收货单绑定" + } + ], + "errors": [ + { + "code": "400", + "message": "筛选条件格式错误", + "description": "筛选条件格式错误" + }, + { + "code": "500", + "message": "查询失败", + "description": "查询失败" + } + ] + }, { "method": "storage.entry.get", "description": "查询入库单详情。通过入库单 ID 定位,关联 Store、EntryItems、EntryOrderReceiving→Receiving,并通过仓库商品详情、直接入库进度、收货单可用明细进行数据合并。entryOrder.order_status 可能为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。", @@ -20019,6 +20223,59 @@ } ] }, + { + "method": "storage.entry.getStore", + "description": "货主侧查询入库单详情。与 get 共享底层逻辑,但以货主维度(store_id)校验权限(不使用 warehouse_id),货主登录后仅能查看自己货主下的入库单明细。返回结构与 get 一致。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "入库单ID(必填)" + } + ], + "response": [ + { + "name": "entryOrder", + "type": "object", + "required": true, + "description": "入库单基本信息(id、entry_order_code、order_status、store_remask)" + }, + { + "name": "items", + "type": "array", + "required": true, + "description": "商品明细列表,每项含 id、stock_id、planned、completed、stock(商品详情)、bindings(库位绑定信息)" + }, + { + "name": "receivingBindings", + "type": "array", + "required": false, + "description": "主表级收货单关联数组,每项含 id / receiving_id / receiving(receiving 含 id / receiving_number / status / storage_status / created_at)" + } + ], + "errors": [ + { + "code": "400", + "message": "id 参数不能为空" + }, + { + "code": "404", + "message": "入库单不存在或无权访问" + } + ] + }, { "method": "storage.entry.cancel", "description": "作废入库单(支持单条或批量作废)。CREATED(已创建待审核)和 PENDING(已审核)状态的入库单可以直接作废;已完成(COMPLETED)入库单不允许作废。", @@ -21735,10 +21992,10 @@ }, { "groupName": "库存报表模块", - "module": "storage.report", + "module": "stock.report", "list": [ { - "method": "storage.report.search", + "method": "stock.report.search", "description": "库存报表查询(主入口):按时间闭区间统计商品出入库并支持按库位或按商品聚合", "isNeedAuth": false, "isNeedLogin": true, @@ -21756,7 +22013,7 @@ "type": "object", "required": false, "source": "body", - "description": "查询条件对象。支持字段:start_time(闭区间下限)、end_time(闭区间上限)、by_space(是否按库位返回,默认 false)、store_ids(货主ID数组)。仅返回在时间区间内存在流水的数据(无流水键不返回)。" + "description": "查询条件对象。支持字段:start_time(闭区间下限)、end_time(闭区间上限)、by_space(是否按库位返回,默认 false)、store_ids(货主ID数组)、stock_id(商品库存ID,单数)、stock_ids(商品库存ID数组)、keyword(商品关键字模糊匹配,支持 SKU ID/item_code/item_name/goods_code/barcode)。仅返回在时间区间内存在流水的数据(无流水键不返回)。" }, { "name": "where.start_time", @@ -21787,6 +22044,28 @@ "description": "货主ID数组,用于过滤特定货主(空或未传表示不过滤)", "list": [] }, + { + "name": "where.stock_id", + "type": "number", + "required": false, + "source": "body", + "description": "商品库存ID(单数),精确过滤指定商品;与 stock_ids 二选一,与 keyword 互斥" + }, + { + "name": "where.stock_ids", + "type": "array", + "required": false, + "source": "body", + "description": "商品库存ID数组,精确过滤指定商品列表;与 stock_id 二选一,与 keyword 互斥", + "list": [] + }, + { + "name": "where.keyword", + "type": "string", + "required": false, + "source": "body", + "description": "商品关键字,支持按 SKU ID(纯数字精确匹配)、商品编码(item_code)、商品名称(item_name)、货物编码(goods_code)、条码(barcode)模糊匹配;与 stock_id / stock_ids 互斥" + }, { "name": "sort", "type": "object", @@ -21950,8 +22229,224 @@ ] }, { - "method": "storage.report.export", - "description": "提交库存报表导出异步任务(与 storage.report.search 使用相同查询条件),立即返回任务受理信息,不直接返回文件。", + "method": "stock.report.searchStore", + "description": "货主侧库存报表查询:以货主维度统计商品出入库(入库和订单出库),不涉及库位维度。与 search 共享核心逻辑,但主维度为 store_id。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "查询条件对象。支持字段:start_time(闭区间下限)、end_time(闭区间上限)、warehouse_ids(仓库ID数组,可选过滤)、stock_id(商品库存ID,单数)、stock_ids(商品库存ID数组)、keyword(商品关键字模糊匹配,支持 SKU ID/item_code/item_name/goods_code/barcode)。仅返回在时间区间内存在流水的数据。" + }, + { + "name": "where.start_time", + "type": "string", + "required": false, + "source": "body", + "description": "开始时间,支持字符串/Date;用于闭区间过滤:created_at >= start_time" + }, + { + "name": "where.end_time", + "type": "string", + "required": false, + "source": "body", + "description": "结束时间,支持字符串/Date;用于闭区间过滤:created_at <= end_time" + }, + { + "name": "where.warehouse_ids", + "type": "array", + "required": false, + "source": "body", + "description": "仓库ID数组,用于过滤特定仓库(空或未传表示不过滤)", + "list": [] + }, + { + "name": "where.stock_id", + "type": "number", + "required": false, + "source": "body", + "description": "商品库存ID(单数),精确过滤指定商品;与 stock_ids 二选一,与 keyword 互斥" + }, + { + "name": "where.stock_ids", + "type": "array", + "required": false, + "source": "body", + "description": "商品库存ID数组,精确过滤指定商品列表;与 stock_id 二选一,与 keyword 互斥", + "list": [] + }, + { + "name": "where.keyword", + "type": "string", + "required": false, + "source": "body", + "description": "商品关键字,支持按 SKU ID(纯数字精确匹配)、商品编码(item_code)、商品名称(item_name)、货物编码(goods_code)、条码(barcode)模糊匹配;与 stock_id / stock_ids 互斥" + }, + { + "name": "sort", + "type": "object", + "required": false, + "source": "body", + "description": "排序参数对象。支持 data.sort.sortField / data.sort.sort_field 与 data.sort.sortOrder / data.sort.sort_order;sortField 白名单:begin_total、inbound_total、outbound_total、end_total;sortOrder 支持 ASC / DESC。" + }, + { + "name": "sort.sortField", + "type": "string", + "required": false, + "source": "body.sort", + "description": "排序字段(兼容 data.sort.sortField)。白名单:begin_total、inbound_total、outbound_total、end_total。" + }, + { + "name": "sort.sort_field", + "type": "string", + "required": false, + "source": "body.sort", + "description": "排序字段下划线别名(兼容 data.sort.sort_field),规则同 sort.sortField。" + }, + { + "name": "sort.sortOrder", + "type": "string", + "required": false, + "source": "body.sort", + "description": "排序方向(兼容 data.sort.sortOrder),支持 ASC / DESC(大小写不敏感)。" + }, + { + "name": "sort.sort_order", + "type": "string", + "required": false, + "source": "body.sort", + "description": "排序方向下划线别名(兼容 data.sort.sort_order),规则同 sort.sortOrder。" + } + ], + "response": [ + { + "name": "data.list", + "type": "array", + "required": true, + "description": "匹配到的报表行列表,已按 sort 规则排序返回。" + }, + { + "name": "data.list[]", + "type": "object", + "required": true, + "description": "单条报表记录字段", + "children": [ + { + "name": "start_time", + "type": "string", + "description": "请求时传入的 start_time(或 null)" + }, + { + "name": "end_time", + "type": "string", + "description": "请求时传入的 end_time(或 null)" + }, + { + "name": "stock_id", + "type": "integer", + "description": "库存商品ID(wms_stock_warehouse.id)" + }, + { + "name": "store_id", + "type": "integer", + "description": "货主ID" + }, + { + "name": "warehouse_id", + "type": "integer", + "description": "仓库ID" + }, + { + "name": "store_name", + "type": "string", + "description": "货主名称" + }, + { + "name": "warehouse_name", + "type": "string", + "description": "仓库名称" + }, + { + "name": "item_name", + "type": "string", + "description": "商品名称" + }, + { + "name": "item_code", + "type": "string", + "description": "商品编码" + }, + { + "name": "barcode", + "type": "string", + "description": "条码" + }, + { + "name": "begin_total", + "type": "number", + "description": "期初库存" + }, + { + "name": "inbound_total", + "type": "number", + "description": "入库总量" + }, + { + "name": "outbound_total", + "type": "number", + "description": "出库总量" + }, + { + "name": "end_total", + "type": "number", + "description": "期末库存" + }, + { + "name": "space_id", + "type": "integer", + "description": "库位ID(where.by_space=true 时返回)" + }, + { + "name": "space_name", + "type": "string", + "description": "库位名称(where.by_space=true 时返回)" + } + ] + } + ], + "errors": [ + { + "code": 400, + "message": "start_time 不合法" + }, + { + "code": 400, + "message": "end_time 不合法" + }, + { + "code": 400, + "message": "start_time 不能大于 end_time" + }, + { + "code": 400, + "message": "用户未绑定货主" + } + ] + }, + { + "method": "stock.report.export", + "description": "提交库存报表导出异步任务(与 stock.report.search 使用相同查询条件),立即返回任务受理信息,不直接返回文件。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -22095,7 +22590,147 @@ ] }, { - "method": "storage.report.exportTaskProgress", + "method": "stock.report.exportStore", + "description": "货主侧提交库存报表导出异步任务(与 stock.report.searchStore 使用相同查询条件),立即返回任务受理信息,不直接返回文件。可通过 stock.report.exportTaskProgress 查询进度。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "查询条件对象。支持字段:start_time、end_time、warehouse_ids。" + }, + { + "name": "where.start_time", + "type": "string", + "required": false, + "source": "body", + "description": "开始时间" + }, + { + "name": "where.end_time", + "type": "string", + "required": false, + "source": "body", + "description": "结束时间" + }, + { + "name": "where.warehouse_ids", + "type": "array", + "required": false, + "source": "body", + "description": "仓库ID数组,用于过滤特定仓库", + "list": [] + }, + { + "name": "sort", + "type": "object", + "required": false, + "source": "body", + "description": "排序参数" + }, + { + "name": "sort.sortField", + "type": "string", + "required": false, + "source": "body.sort", + "description": "排序字段" + }, + { + "name": "sort.sort_field", + "type": "string", + "required": false, + "source": "body.sort", + "description": "排序字段下划线别名" + }, + { + "name": "sort.sortOrder", + "type": "string", + "required": false, + "source": "body.sort", + "description": "排序方向" + }, + { + "name": "sort.sort_order", + "type": "string", + "required": false, + "source": "body.sort", + "description": "排序方向下划线别名" + }, + { + "name": "export_mode", + "type": "string", + "required": false, + "source": "body", + "description": "导出模式:'item' 导出含锁定类型的全部变更记录" + }, + { + "name": "exportMode", + "type": "string", + "required": false, + "source": "body", + "description": "导出模式(驼峰写法,同 export_mode)" + } + ], + "response": [ + { + "name": "data.task_id", + "type": "string", + "required": true, + "description": "导出异步任务ID,用于后续查询进度" + }, + { + "name": "data.status", + "type": "string", + "required": true, + "description": "任务受理状态:submitted" + }, + { + "name": "data.progress", + "type": "number", + "required": true, + "description": "任务进度:0" + }, + { + "name": "data.message", + "type": "string", + "required": true, + "description": "任务受理消息" + }, + { + "name": "data.update_time", + "type": "number", + "required": true, + "description": "任务更新时间戳(ms)" + } + ], + "errors": [ + { + "code": 400, + "message": "start_time 不合法" + }, + { + "code": 400, + "message": "end_time 不合法" + }, + { + "code": 400, + "message": "start_time 不能大于 end_time" + } + ] + }, + { + "method": "stock.report.exportTaskProgress", "description": "根据 task_id 查询库存报表导出任务进度与结果;status 可能值:submitted/running/success/failed/not_found。", "isNeedAuth": false, "isNeedLogin": true, @@ -26736,6 +27371,961 @@ ] } ] + }, + { + "groupName": "工作台模块", + "module": "workbench", + "list": [ + { + "method": "workbench.list", + "description": "查询工作台列表(仓库隔离,支持分页与关键词筛选)", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页参数,支持 page / pageSize" + }, + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "筛选条件,支持 name(模糊)、barcode(模糊)、status(等值)" + } + ], + "response": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "工作台列表", + "children": [ + { + "name": "id", + "type": "number", + "description": "工作台ID" + }, + { + "name": "warehouse_id", + "type": "number", + "description": "仓库ID" + }, + { + "name": "name", + "type": "string", + "description": "工作台名称" + }, + { + "name": "barcode", + "type": "string", + "description": "工作台条码" + }, + { + "name": "status", + "type": "number", + "description": "状态:0-禁用 1-启用" + }, + { + "name": "remark", + "type": "string", + "description": "备注" + }, + { + "name": "created_at", + "type": "string", + "description": "创建时间" + }, + { + "name": "updated_at", + "type": "string", + "description": "更新时间" + } + ] + }, + { + "name": "pagination", + "type": "object", + "required": true, + "description": "分页信息" + } + ], + "errors": [ + { + "code": "400", + "description": "参数格式错误或缺少仓库上下文" + } + ] + }, + { + "method": "workbench.detail", + "description": "查询单个工作台详情(仓库隔离)", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "工作台ID" + } + ], + "response": [ + { + "name": "data", + "type": "object", + "required": true, + "description": "工作台详情对象" + } + ], + "errors": [ + { + "code": "400", + "description": "工作台ID不能为空" + }, + { + "code": "404", + "description": "工作台不存在或无权访问" + } + ] + }, + { + "method": "workbench.create", + "description": "新增工作台(仓库隔离,条码仓库内唯一)", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "name", + "type": "string", + "required": true, + "source": "body", + "description": "工作台名称(必填)" + }, + { + "name": "barcode", + "type": "string", + "required": false, + "source": "body", + "description": "工作台条码(可选,仓库内唯一)" + }, + { + "name": "status", + "type": "number", + "required": false, + "source": "body", + "description": "状态:0-禁用 1-启用,默认1" + }, + { + "name": "remark", + "type": "string", + "required": false, + "source": "body", + "description": "备注" + } + ], + "response": [ + { + "name": "data", + "type": "object", + "required": true, + "description": "新建的工作台对象" + } + ], + "errors": [ + { + "code": "400", + "description": "工作台名称不能为空" + }, + { + "code": "400", + "description": "条码已存在(仓库内唯一约束)" + } + ] + }, + { + "method": "workbench.update", + "description": "更新工作台信息(仓库隔离)", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "工作台ID(必填)" + }, + { + "name": "name", + "type": "string", + "required": false, + "source": "body", + "description": "工作台名称" + }, + { + "name": "barcode", + "type": "string", + "required": false, + "source": "body", + "description": "工作台条码" + }, + { + "name": "status", + "type": "number", + "required": false, + "source": "body", + "description": "状态:0-禁用 1-启用" + }, + { + "name": "remark", + "type": "string", + "required": false, + "source": "body", + "description": "备注" + } + ], + "response": [ + { + "name": "data", + "type": "object", + "required": true, + "description": "更新后的工作台对象" + } + ], + "errors": [ + { + "code": "400", + "description": "工作台ID不能为空" + }, + { + "code": "404", + "description": "工作台不存在或无权操作" + } + ] + }, + { + "method": "workbench.delete", + "description": "删除工作台(软删除,仓库隔离)", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "工作台ID(必填)" + } + ], + "response": [], + "errors": [ + { + "code": "400", + "description": "工作台ID不能为空" + }, + { + "code": "404", + "description": "工作台不存在或无权操作" + } + ] + }, + { + "method": "workbench.checkBarcode", + "description": "检查条码在仓库内是否已存在", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "barcode", + "type": "string", + "required": true, + "source": "body", + "description": "条码(必填)" + }, + { + "name": "excludeId", + "type": "number", + "required": false, + "source": "body", + "description": "排除的工作台ID(更新时避免自身冲突)" + } + ], + "response": [ + { + "name": "exists", + "type": "boolean", + "required": true, + "description": "是否存在:true=已存在 false=可用" + } + ], + "errors": [ + { + "code": "400", + "description": "条码不能为空" + } + ] + }, + { + "method": "workbench.business", + "description": "工作台业务入口(免登录免鉴权,入参 name + data,业务逻辑待实现)", + "isNeedAuth": false, + "isNeedLogin": false, + "headers": [], + "params": [ + { + "name": "name", + "type": "string", + "required": true, + "source": "body", + "description": "业务名称(用于分发具体逻辑)" + }, + { + "name": "data", + "type": "object", + "required": false, + "source": "body", + "description": "业务数据(透传)" + } + ], + "response": [ + { + "name": "name", + "type": "string", + "required": true, + "description": "回显业务名称" + }, + { + "name": "received", + "type": "boolean", + "required": true, + "description": "是否已接收" + } + ], + "errors": [] + }, + { + "method": "workbench.bindCamera", + "description": "工作台绑定/解绑摄像头,校验工作台与摄像头归属后更新 device_ids", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "工作台ID" + }, + { + "name": "camera_ids", + "type": "array", + "required": false, + "source": "body", + "description": "摄像头ID数组,传空数组或 null 表示解绑所有摄像头" + } + ], + "response": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "工作台ID" + }, + { + "name": "name", + "type": "string", + "required": true, + "description": "工作台名称" + }, + { + "name": "device_ids", + "type": "array", + "required": false, + "description": "绑定后的摄像头ID列表" + } + ], + "errors": [ + { + "code": "400", + "message": "工作台ID不能为空" + }, + { + "code": "400", + "message": "摄像头 xxx 不存在或无权操作" + }, + { + "code": "404", + "message": "工作台不存在或无权操作" + } + ] + } + ] + }, + { + "groupName": "录像服务器模块", + "module": "camera_server", + "list": [ + { + "method": "camera_server.list", + "description": "录像服务器列表(仓库隔离,分页+筛选)", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页参数 page/pageSize" + }, + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "筛选:name(模糊)、status(等值)" + } + ], + "response": [], + "errors": [] + }, + { + "method": "camera_server.detail", + "description": "录像服务器详情", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "服务器ID" + } + ], + "response": [], + "errors": [ + { + "code": "404", + "description": "不存在或无权访问" + } + ] + }, + { + "method": "camera_server.create", + "description": "新增录像服务器", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "name", + "type": "string", + "required": true, + "source": "body", + "description": "服务器名称(必填)" + }, + { + "name": "brand", + "type": "string", + "required": false, + "source": "body", + "description": "品牌" + }, + { + "name": "public_ip", + "type": "string", + "required": false, + "source": "body", + "description": "公网IP" + }, + { + "name": "internal_ip", + "type": "string", + "required": false, + "source": "body", + "description": "内网IP" + }, + { + "name": "port", + "type": "number", + "required": false, + "source": "body", + "description": "端口号" + }, + { + "name": "username", + "type": "string", + "required": false, + "source": "body", + "description": "账号" + }, + { + "name": "password", + "type": "string", + "required": false, + "source": "body", + "description": "密码" + }, + { + "name": "status", + "type": "number", + "required": false, + "source": "body", + "description": "0-禁用 1-启用" + }, + { + "name": "remark", + "type": "string", + "required": false, + "source": "body", + "description": "备注" + } + ], + "response": [], + "errors": [ + { + "code": "400", + "description": "名称不能为空" + } + ] + }, + { + "method": "camera_server.update", + "description": "更新录像服务器", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "服务器ID(必填)" + }, + { + "name": "name", + "type": "string", + "required": false, + "source": "body", + "description": "名称" + }, + { + "name": "brand", + "type": "string", + "required": false, + "source": "body", + "description": "品牌" + }, + { + "name": "public_ip", + "type": "string", + "required": false, + "source": "body", + "description": "公网IP" + }, + { + "name": "internal_ip", + "type": "string", + "required": false, + "source": "body", + "description": "内网IP" + }, + { + "name": "port", + "type": "number", + "required": false, + "source": "body", + "description": "端口号" + }, + { + "name": "username", + "type": "string", + "required": false, + "source": "body", + "description": "账号" + }, + { + "name": "password", + "type": "string", + "required": false, + "source": "body", + "description": "密码" + }, + { + "name": "status", + "type": "number", + "required": false, + "source": "body", + "description": "0-禁用 1-启用" + }, + { + "name": "remark", + "type": "string", + "required": false, + "source": "body", + "description": "备注" + } + ], + "response": [], + "errors": [ + { + "code": "404", + "description": "不存在或无权操作" + } + ] + }, + { + "method": "camera_server.delete", + "description": "删除录像服务器(软删除)", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "服务器ID" + } + ], + "response": [], + "errors": [ + { + "code": "404", + "description": "不存在或无权操作" + } + ] + } + ] + }, + { + "groupName": "摄像头模块", + "module": "camera", + "list": [ + { + "method": "camera.list", + "description": "摄像头列表(仓库隔离,分页+筛选)", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页参数 page/pageSize" + }, + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "筛选:server_id(等值)、custom_name(模糊)、status(等值)" + } + ], + "response": [], + "errors": [] + }, + { + "method": "camera.detail", + "description": "摄像头详情", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "摄像头ID" + } + ], + "response": [], + "errors": [ + { + "code": "404", + "description": "不存在或无权访问" + } + ] + }, + { + "method": "camera.create", + "description": "新增摄像头", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "server_id", + "type": "number", + "required": true, + "source": "body", + "description": "所属服务器ID(必填)" + }, + { + "name": "channel_id", + "type": "number", + "required": true, + "source": "body", + "description": "通道编号(必填)" + }, + { + "name": "channel_name", + "type": "string", + "required": false, + "source": "body", + "description": "通道名称" + }, + { + "name": "custom_name", + "type": "string", + "required": false, + "source": "body", + "description": "自定义名称" + }, + { + "name": "status", + "type": "number", + "required": false, + "source": "body", + "description": "0-禁用 1-启用" + }, + { + "name": "remark", + "type": "string", + "required": false, + "source": "body", + "description": "备注" + } + ], + "response": [], + "errors": [ + { + "code": "400", + "description": "server_id/channel_id 不能为空" + } + ] + }, + { + "method": "camera.update", + "description": "更新摄像头", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "摄像头ID(必填)" + }, + { + "name": "server_id", + "type": "number", + "required": false, + "source": "body", + "description": "所属服务器ID" + }, + { + "name": "channel_id", + "type": "number", + "required": false, + "source": "body", + "description": "通道编号" + }, + { + "name": "channel_name", + "type": "string", + "required": false, + "source": "body", + "description": "通道名称" + }, + { + "name": "custom_name", + "type": "string", + "required": false, + "source": "body", + "description": "自定义名称" + }, + { + "name": "status", + "type": "number", + "required": false, + "source": "body", + "description": "0-禁用 1-启用" + }, + { + "name": "remark", + "type": "string", + "required": false, + "source": "body", + "description": "备注" + } + ], + "response": [], + "errors": [ + { + "code": "404", + "description": "不存在或无权操作" + } + ] + }, + { + "method": "camera.delete", + "description": "删除摄像头(软删除)", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "摄像头ID" + } + ], + "response": [], + "errors": [ + { + "code": "404", + "description": "不存在或无权操作" + } + ] + } + ] } ] }