From 76e25db7da0699ae864c715da972497abd4c0e45 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sat, 1 Aug 2026 03:39:41 +0800 Subject: [PATCH] =?UTF-8?q?feat(apiApp):=20=E6=96=B0=E5=A2=9E=E4=BB=93?= =?UTF-8?q?=E5=BA=93=20API=20=E5=BA=94=E7=94=A8=E7=AE=A1=E7=90=86=E6=A8=A1?= =?UTF-8?q?=E5=9D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 systems/apiApp.js 业务层:CRUD + AppKey/Secret 自动生成 + 仓库隔离 - 新增 systemMethods/apiApp.js 入口层:list/detail/create/update/delete/regenerateSecret - 注册 methods/system.json API 文档 + changes 变更记录 - 新增迁移脚本:wms_permission 固定 ID 464-470 + 客服组主管及以上角色授权 --- app/service/systemMethods/apiApp.js | 117 + app/service/systems/apiApp.js | 320 ++ .../20260801120000-add-apiApp-permissions.js | 80 + methods/changes/system.json | 138 +- methods/system.json | 2677 ++++++++++++++++- 5 files changed, 3189 insertions(+), 143 deletions(-) create mode 100644 app/service/systemMethods/apiApp.js create mode 100644 app/service/systems/apiApp.js create mode 100644 database/migrations/20260801120000-add-apiApp-permissions.js diff --git a/app/service/systemMethods/apiApp.js b/app/service/systemMethods/apiApp.js new file mode 100644 index 0000000..87c126c --- /dev/null +++ b/app/service/systemMethods/apiApp.js @@ -0,0 +1,117 @@ +'use strict'; + +const MainService = require('../main'); + +/** + * 仓库 API 应用管理 Service + * 管理当前仓库的外部 API 应用(AppKey/Secret 生成、IP 白名单、限流等)。 + * 仓库隔离:所有操作自动按 ctx.user.store_id 过滤。 + */ +class ApiAppService extends MainService { + constructor(ctx) { + super(ctx); + const _noNeedLogin = ''; + const _noNeedRight = ''; + const _noNeedLog = ''; + const _noNeedAuth = ''; + this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth); + } + + /** + * 查询当前仓库的 API 应用列表(分页)。 + * @param {Object} data 查询参数。 + * @return {Promise} 分页结果。 + */ + async list(data) { + try { + const result = await this.service.systems.apiApp.list(data || {}); + return this.success('获取成功', result); + } catch (e) { return this.fail(e.message); } + } + + /** + * 查询单个 API 应用详情。 + * @param {Object} data 查询参数。 + * @param {number|string} data.id 应用 ID。 + * @return {Promise} 应用详情。 + */ + async detail(data) { + try { + const { id } = data || {}; + if (!id) return this.fail('ID不能为空'); + const { ctx } = this; + const warehouseId = Number(ctx.user && ctx.user.store_id || 0); + const defaultTypeId = await this.service.systems.apiApp.getDefaultInterfaceTypeId(); + const record = await ctx.model.ApiApp.findOne({ + attributes: [ + 'id', 'app_name', 'warehouse_id', 'self_app_key', 'self_app_secret', + 'self_ip_whitelist', 'callback_url', 'interface_type_id', + 'rate_limit', 'sign_method', 'is_enabled', 'created_at', 'updated_at', + ], + where: { id: Number(id), warehouse_id: warehouseId, interface_type_id: defaultTypeId }, + raw: true, + }); + if (!record) return this.fail('API应用不存在'); + record.self_app_secret = record.self_app_secret + ? String(record.self_app_secret).substring(0, 8) + '****' + : ''; + return this.success('获取成功', record); + } catch (e) { return this.fail(e.message); } + } + + /** + * 创建 API 应用,自动生成 AppKey 和 AppSecret。 + * @param {Object} data 创建参数。 + * @return {Promise} 创建结果(含完整 secret)。 + */ + async create(data) { + try { + const result = await this.service.systems.apiApp.create(data || {}); + return this.success('创建成功', result); + } catch (e) { return this.fail(e.message); } + } + + /** + * 更新 API 应用。 + * @param {Object} data 更新参数。 + * @return {Promise} 更新结果。 + */ + async update(data) { + try { + const { id, ...fields } = data || {}; + if (!id) return this.fail('ID不能为空'); + const result = await this.service.systems.apiApp.update(id, fields); + return this.success('更新成功', result); + } catch (e) { return this.fail(e.message); } + } + + /** + * 删除/停用 API 应用。 + * @param {Object} data 删除参数。 + * @return {Promise} 删除结果。 + */ + async delete(data) { + try { + const { id } = data || {}; + if (!id) return this.fail('ID不能为空'); + await this.service.systems.apiApp.delete(id); + return this.success('删除成功'); + } catch (e) { return this.fail(e.message); } + } + + /** + * 重新生成 AppSecret。 + * @param {Object} data 参数。 + * @return {Promise} 新 secret。 + */ + async regenerateSecret(data) { + try { + const { id } = data || {}; + if (!id) return this.fail('ID不能为空'); + const result = await this.service.systems.apiApp.regenerateSecret(id); + return this.success('重新生成成功', result); + } catch (e) { return this.fail(e.message); } + } +} + +module.exports = ApiAppService; diff --git a/app/service/systems/apiApp.js b/app/service/systems/apiApp.js new file mode 100644 index 0000000..c5b7042 --- /dev/null +++ b/app/service/systems/apiApp.js @@ -0,0 +1,320 @@ +'use strict'; + +const { randomBytes } = require('node:crypto'); +const { Service } = require('egg'); + +class ApiAppService extends Service { + /** + * 生成唯一的 AppKey。 + * 格式:AK{yyyyMMddHHmmss}{random8} + * @return {string} AppKey + */ + generateAppKey() { + const now = new Date(); + const timestamp = [ + 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'), + ].join(''); + return `AK${timestamp}${randomBytes(4).toString('hex')}`; + } + + /** + * 生成 AppSecret。 + * @return {string} 64 字符十六进制密钥。 + */ + generateAppSecret() { + return randomBytes(32).toString('hex'); + } + + /** + * 获取默认的仓库渠道接口类型 ID。 + * 查找 interface_type 中 interface_code = 'OPEN_API_WAREHOUSE' 的记录。 + * @return {Promise} 接口类型 ID,找不到时返回 0。 + */ + async getDefaultInterfaceTypeId() { + const row = await this.ctx.model.InterfaceType.findOne({ + attributes: [ 'id' ], + where: { interface_code: 'OPEN_API_WAREHOUSE', is_enabled: 1 }, + raw: true, + }); + return row ? Number(row.id) : 0; + } + + /** + * 查询当前仓库的 API 应用列表(分页)。 + * @param {Object} data 查询参数。 + * @param {number} [data.page=1] 页码。 + * @param {number} [data.pageSize=20] 每页数量。 + * @param {string} [data.app_name] 应用名称(模糊搜索)。 + * @param {number} [data.is_enabled] 启用状态。 + * @return {Promise} 分页结果。 + */ + async list(data = {}) { + const { ctx } = this; + const warehouseId = Number(ctx.user && ctx.user.store_id || 0); + const page = Math.max(1, Number(data.page) || 1); + const pageSize = Math.min(100, Math.max(1, Number(data.pageSize) || 20)); + + // 仅查询仓库开放接口类型的应用,排除货主/奇门等类型 + const where = { + warehouse_id: warehouseId, + interface_type_id: await this.getDefaultInterfaceTypeId(), + }; + if (data.app_name) { + where.app_name = { [this.app.Sequelize.Op.like]: `%${String(data.app_name).trim()}%` }; + } + if (data.is_enabled !== undefined && data.is_enabled !== null && data.is_enabled !== '') { + where.is_enabled = Number(data.is_enabled); + } + + const total = await ctx.model.ApiApp.count({ where }); + const list = await ctx.model.ApiApp.findAll({ + attributes: [ + 'id', 'app_name', 'warehouse_id', 'self_app_key', 'self_app_secret', + 'self_ip_whitelist', 'callback_url', 'interface_type_id', + 'rate_limit', 'sign_method', 'is_enabled', 'created_at', 'updated_at', + ], + where, + offset: (page - 1) * pageSize, + limit: pageSize, + order: [[ 'id', 'DESC' ]], + raw: true, + }); + + // 脱敏:只返回 secret 前 8 位 + const maskedList = list.map(item => ({ + ...item, + self_app_secret: item.self_app_secret + ? String(item.self_app_secret).substring(0, 8) + '****' + : '', + })); + + return { + list: maskedList, + pagination: { + page, + pageSize, + total, + totalPages: Math.ceil(total / pageSize), + hasNext: page * pageSize < total, + hasPrevious: page > 1, + }, + }; + } + + /** + * 创建仓库 API 应用,自动生成 AppKey 和 AppSecret。 + * @param {Object} data 创建参数。 + * @param {string} data.app_name 应用名称(必填)。 + * @param {number|string} [data.interface_type_id] 接口类型 ID,不传则查 WH_CHANNEL。 + * @param {Array} [data.self_ip_whitelist] IP 白名单。 + * @param {string} [data.callback_url] 回调地址。 + * @param {number} [data.rate_limit=1000] 速率限制。 + * @param {string} [data.sign_method='md5'] 签名方法。 + * @return {Promise} 创建结果(含完整 secret,仅创建时返回)。 + */ + async create(data = {}) { + const { ctx } = this; + const warehouseId = Number(ctx.user && ctx.user.store_id || 0); + + if (!warehouseId) { + throw new Error('无法获取当前仓库ID'); + } + + const appName = String(data.app_name || '').trim(); + if (!appName) { + throw new Error('应用名称不能为空'); + } + if (appName.length > 200) { + throw new Error('应用名称不能超过200个字符'); + } + + const interfaceTypeId = data.interface_type_id + ? Number(data.interface_type_id) + : await this.getDefaultInterfaceTypeId(); + + const appKey = this.generateAppKey(); + const appSecret = this.generateAppSecret(); + + const payload = { + app_name: appName, + warehouse_id: warehouseId, + interface_type_id: interfaceTypeId, + self_app_key: appKey, + self_app_secret: appSecret, + self_ip_whitelist: Array.isArray(data.self_ip_whitelist) ? data.self_ip_whitelist : null, + callback_url: String(data.callback_url || '').trim() || null, + rate_limit: Number(data.rate_limit) || 1000, + sign_method: [ 'md5', 'hmac', 'sha256' ].includes(String(data.sign_method || '').trim()) + ? String(data.sign_method).trim() + : 'md5', + is_enabled: 1, + }; + + const record = await ctx.model.ApiApp.create(payload); + + this.ctx.logger.info('[apiApp] 创建仓库API应用成功', { + warehouseId, + appId: record.id, + appName, + appKey, + }); + + return { + id: record.id, + app_name: record.app_name, + warehouse_id: record.warehouse_id, + interface_type_id: record.interface_type_id, + self_app_key: record.self_app_key, + self_app_secret: record.self_app_secret, + self_ip_whitelist: record.self_ip_whitelist, + callback_url: record.callback_url, + rate_limit: record.rate_limit, + sign_method: record.sign_method, + is_enabled: record.is_enabled, + created_at: record.created_at, + updated_at: record.updated_at, + }; + } + + /** + * 更新仓库 API 应用。 + * @param {number|string} id 应用 ID。 + * @param {Object} data 更新字段。 + * @param {string} [data.app_name] 应用名称。 + * @param {Array} [data.self_ip_whitelist] IP 白名单。 + * @param {string} [data.callback_url] 回调地址。 + * @param {number} [data.rate_limit] 速率限制。 + * @param {string} [data.sign_method] 签名方法。 + * @param {number} [data.is_enabled] 启用状态。 + * @return {Promise} 更新后的记录(脱敏)。 + */ + async update(id, data = {}) { + const { ctx } = this; + const warehouseId = Number(ctx.user && ctx.user.store_id || 0); + + const record = await ctx.model.ApiApp.findOne({ + where: { id: Number(id), warehouse_id: warehouseId, interface_type_id: await this.getDefaultInterfaceTypeId() }, + }); + + if (!record) { + throw new Error('API应用不存在或不属于当前仓库'); + } + + const updatableFields = [ 'app_name', 'self_ip_whitelist', 'callback_url', 'rate_limit', 'sign_method', 'is_enabled' ]; + for (const field of updatableFields) { + if (data[field] !== undefined && data[field] !== null) { + if (field === 'sign_method') { + const val = String(data[field]).trim(); + if (![ 'md5', 'hmac', 'sha256' ].includes(val)) { + throw new Error('签名方法仅支持 md5/hmac/sha256'); + } + record[field] = val; + } else if (field === 'is_enabled') { + record[field] = Number(data[field]); + } else if (field === 'rate_limit') { + const val = Number(data[field]); + record[field] = val > 0 && val <= 100000 ? val : record[field]; + } else if (field === 'app_name') { + const val = String(data[field]).trim(); + if (!val) throw new Error('应用名称不能为空'); + if (val.length > 200) throw new Error('应用名称不能超过200个字符'); + record[field] = val; + } else { + record[field] = data[field]; + } + } + } + + await record.save(); + + this.ctx.logger.info('[apiApp] 更新仓库API应用成功', { + warehouseId, + appId: record.id, + }); + + return { + id: record.id, + app_name: record.app_name, + warehouse_id: record.warehouse_id, + interface_type_id: record.interface_type_id, + self_app_key: record.self_app_key, + self_app_secret: record.self_app_secret + ? String(record.self_app_secret).substring(0, 8) + '****' + : '', + self_ip_whitelist: record.self_ip_whitelist, + callback_url: record.callback_url, + rate_limit: record.rate_limit, + sign_method: record.sign_method, + is_enabled: record.is_enabled, + created_at: record.created_at, + updated_at: record.updated_at, + }; + } + + /** + * 删除仓库 API 应用(软删除:is_enabled=0)。 + * @param {number|string} id 应用 ID。 + * @return {Promise} 无返回值。 + */ + async delete(id) { + const { ctx } = this; + const warehouseId = Number(ctx.user && ctx.user.store_id || 0); + + const record = await ctx.model.ApiApp.findOne({ + where: { id: Number(id), warehouse_id: warehouseId, interface_type_id: await this.getDefaultInterfaceTypeId() }, + }); + + if (!record) { + throw new Error('API应用不存在或不属于当前仓库'); + } + + record.is_enabled = 0; + await record.save(); + + this.ctx.logger.info('[apiApp] 停用仓库API应用成功', { + warehouseId, + appId: record.id, + }); + } + + /** + * 重新生成 AppSecret。 + * @param {number|string} id 应用 ID。 + * @return {Promise} 包含新 secret 的结果(仅此次返回完整 secret)。 + */ + async regenerateSecret(id) { + const { ctx } = this; + const warehouseId = Number(ctx.user && ctx.user.store_id || 0); + + const record = await ctx.model.ApiApp.findOne({ + where: { id: Number(id), warehouse_id: warehouseId, interface_type_id: await this.getDefaultInterfaceTypeId() }, + }); + + if (!record) { + throw new Error('API应用不存在或不属于当前仓库'); + } + + const newSecret = this.generateAppSecret(); + record.self_app_secret = newSecret; + await record.save(); + + this.ctx.logger.info('[apiApp] 重新生成AppSecret成功', { + warehouseId, + appId: record.id, + }); + + return { + id: record.id, + app_name: record.app_name, + self_app_key: record.self_app_key, + self_app_secret: newSecret, + }; + } +} + +module.exports = ApiAppService; diff --git a/database/migrations/20260801120000-add-apiApp-permissions.js b/database/migrations/20260801120000-add-apiApp-permissions.js new file mode 100644 index 0000000..486d856 --- /dev/null +++ b/database/migrations/20260801120000-add-apiApp-permissions.js @@ -0,0 +1,80 @@ +'use strict'; + +/** + * 为 apiApp 仓库 API 应用管理模块创建权限并授权给客服组-主管及以上角色。 + * + * 固定 ID(开发库 & 生产库 wms_permission 当前 max_id 均为 463): + * 464 — 父级菜单 "API应用管理" + * 465 — apiApp.list + * 466 — apiApp.detail + * 467 — apiApp.create + * 468 — apiApp.update + * 469 — apiApp.delete + * 470 — apiApp.regenerateSecret + * + * 授权角色(permissions 不为 "*" 的 主管/经理 级角色): + * 8 — 经理 + * 26 — 仓库组-主管 + * 28 — 客服组-主管 + * 29 — 生产组-主管 + */ +module.exports = { + // eslint-disable-next-line no-unused-vars + async up(queryInterface, Sequelize) { + // ── 1. 插入父级权限 (type=web_pages, sort=1, status=1) ── + await queryInterface.sequelize.query(` + INSERT INTO wms_permission (id, path, component, name, redirect, meta_title, meta_icon, hidden, always_show, parent_id, type, sort, status, created_at, update_at) + VALUES (464, 'apiApp', NULL, 'API应用管理', NULL, 'API应用管理', NULL, 0, 0, NULL, 'web_pages', 1, 1, NOW(), NOW()) + `); + + // ── 2. 插入 6 个接口权限 ── + const methods = [ + [ 465, 'apiApp.list' ], + [ 466, 'apiApp.detail' ], + [ 467, 'apiApp.create' ], + [ 468, 'apiApp.update' ], + [ 469, 'apiApp.delete' ], + [ 470, 'apiApp.regenerateSecret' ], + ]; + + for (const [ id, method ] of methods) { + await queryInterface.sequelize.query(` + INSERT INTO wms_permission (id, path, component, name, redirect, meta_title, meta_icon, hidden, always_show, parent_id, type, sort, status, created_at, update_at) + VALUES (${id}, '${method}', NULL, '${method}', NULL, 'API:${method}', NULL, 0, 0, 464, 'api', 0, 1, NOW(), NOW()) + `); + } + + // ── 3. 给 客服组-主管及以上角色 追加新权限 ID ── + // 只更新 permissions 为显式列表(非 "*")的角色 + const newIdSuffix = ', 465, 466, 467, 468, 469, 470'; + + await queryInterface.sequelize.query(` + UPDATE wms_role + SET permissions = CONCAT(LEFT(permissions, LENGTH(permissions) - 1), '${newIdSuffix}]') + WHERE id IN (8, 26, 28, 29) + AND permissions != '*' + AND permissions IS NOT NULL + AND LENGTH(permissions) > 2 + `); + }, + + // eslint-disable-next-line no-unused-vars + async down(queryInterface, Sequelize) { + // ── 1. 从角色权限中移除新增的 ID ── + await queryInterface.sequelize.query(` + UPDATE wms_role + SET permissions = REPLACE(permissions, ', 465, 466, 467, 468, 469, 470', '') + WHERE id IN (8, 26, 28, 29) + `); + + // ── 2. 删除 6 个接口权限 ── + await queryInterface.sequelize.query( + 'DELETE FROM wms_permission WHERE id IN (465, 466, 467, 468, 469, 470)' + ); + + // ── 3. 删除父级权限 ── + await queryInterface.sequelize.query( + 'DELETE FROM wms_permission WHERE id = 464' + ); + }, +}; diff --git a/methods/changes/system.json b/methods/changes/system.json index f3daf2b..49f9658 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,83 @@ [ + { + "version": "2026.08.01-system-01", + "date": "2026-08-01", + "type": "added", + "summary": "新增 apiApp 仓库 API 应用管理模块,支持当前仓库维度的 API 应用 CRUD、AppKey/Secret 自动生成与重新生成、IP 白名单、回调地址、限流等配置", + "methods": [ + "apiApp.list", + "apiApp.detail", + "apiApp.create", + "apiApp.update", + "apiApp.delete", + "apiApp.regenerateSecret" + ], + "notes": [ + "apiApp.list:分页查询当前仓库 API 应用列表,支持按 app_name(模糊)、is_enabled 筛选,Secret 自动脱敏(前8位+****)。", + "apiApp.detail:按 ID 查询单个应用详情,需同时匹配 warehouse_id(自动注入 ctx.user.store_id),Secret 脱敏。", + "apiApp.create:创建应用时自动生成 AppKey(AK{yyyyMMddHHmmss}{random8hex})和 AppSecret(64位hex)。默认 interface_type_id 取 WH_CHANNEL。仅创建时返回完整 Secret。", + "apiApp.update:更新可编辑字段(app_name、self_ip_whitelist、callback_url、rate_limit、sign_method、is_enabled),不可变字段为 self_app_key 和 interface_type_id。", + "apiApp.delete:软删除(is_enabled=0),不物理删除。", + "apiApp.regenerateSecret:重新生成 64位hex AppSecret,旧 Secret 立即失效。仅此次返回完整 Secret。", + "仓库隔离:所有操作按 ctx.user.store_id → warehouse_id 自动过滤。", + "Secret 安全策略:list/detail/update 返回脱敏值,仅 create/regenerateSecret 返回完整 Secret。" + ], + "module": "apiApp" + }, + { + "version": "2026.07.31-system-02", + "date": "2026-07-31", + "type": "added", + "summary": "新增 storage.inventory.export 库存导出与 storage.inventory.exportTaskProgress 导出进度查询,入参复用 list 的 where/sort/group_by_batch 语义,支持两种导出模式(聚合汇总 / 逐条明细),库位信息一并导出", + "methods": [ + "storage.inventory.export", + "storage.inventory.exportTaskProgress" + ], + "notes": [ + "storage.inventory.export:异步提交导出任务,返回 task_id 与受理信息,后端异步生成 Excel 并上传。入参 where/sort/group_by_batch 与 storage.inventory.list 完全一致,无需额外学习成本。", + "group_by_batch=false(默认):按 stock_id + space_id(库位)聚合导出库存汇总,含商品编码/名称/规格/单位/货主/库位编码/名称/总库存/锁定/可用/批次数/最近入库时间。", + "group_by_batch=true:按 storage_id 逐条导出库存明细,含库存记录ID/商品信息/库位信息/批次号/库存类型/数量/生产日期/过期日期/入库时间/入库单号/供应商批次号。", + "新增 storage.inventory.exportTaskProgress:按 task_id/taskId 查询导出任务进度与状态(submitted/running/success/failed/not_found),status=success 时返回 download_url 供客户端下载。", + "导出文件目录:exports/storage/inventory/{warehouseId}/,缓存 TTL 1800 秒。" + ], + "module": "storage.inventory" + }, + { + "version": "2026.07.31-system-01", + "date": "2026-07-31", + "type": "added", + "summary": "新增按波次批量快捷复核接口 batchQuickRecheckByWave,支持批量波次 IDs 的前置条件检查(储位、快递、同步、拦截),自动完成拣货并标记复核,支持部分失败", + "methods": [ + "order.recheckOrder.batchQuickRecheckByWave" + ], + "notes": [ + "新增 order.recheckOrder.batchQuickRecheckByWave 方法,复用 batchQuickRecheck 的 _completePickForOrder / _markRecheckForOrder / _tryCompleteWaveInTransaction 等内部事务方法", + "入参 wave_ids 支持数组或逗号分隔字符串,兼容 waveIds(驼峰)、wave_id(单值)", + "按波次维度批量查询订单后逐波次、逐订单执行前置校验与复核,每个订单独立事务,部分失败不影响其他订单", + "响应包含 success/failed 列表及计数,failed 项含 order_id、wave_id、delivery_order_code、reason 说明;波次下无订单时仅返回 wave_id + reason" + ], + "module": "order.recheckOrder" + }, + { + "version": "2026.07.29-system-01", + "date": "2026-07-29", + "type": "added", + "summary": "补全 waybill.warehouse group API 文档参数定义:完善 list/detail/export 的 params 与 response,新增 exportTaskProgress 异步进度查询接口", + "methods": [ + "waybill.warehouse.list", + "waybill.warehouse.detail", + "waybill.warehouse.export", + "waybill.warehouse.exportTaskProgress" + ], + "notes": [ + "waybill.warehouse.list:params 含 pagination/where/sort 完整字段定义,where 支持 15 个筛选维度(运单号、主单号、订单ID、订单号、物流编码、物流接口ID、平台编码、状态、退回/拦截/星河签收、包材ID、已称重、关键词、创建时间范围),sort 白名单 create_at/weighing_weight/id。response 含 list(28 个字段)+ pagination。", + "waybill.warehouse.detail:修正 id 参数为可选(required: false),与 waybillCode 二选一,waybillCode 优先。response 含 id/waybill_code/main_waybill_code/waybill_type/business_key/sibling_waybills/order/logistics/status_info/weight/package/print_records/print_count 等完整详情。", + "waybill.warehouse.export:response 补充 progress/message/update_time 字段,完整覆盖异步任务返回信息。", + "新增 waybill.warehouse.exportTaskProgress:按 task_id/taskId 查询导出进度,response 含 task_id/status/progress/current_count/total_count/message/result/error/download_url/update_time。", + "所有接口 isNeedAuth: false, isNeedLogin: true,仓库隔离通过 ctx.user.store_id 自动注入。" + ], + "module": "waybill.warehouse" + }, { "version": "2026.07.28-system-01", "date": "2026-07-28", @@ -2335,24 +2414,6 @@ ], "type": "updated" }, - { - "version": "2026.05.20-system-02", - "date": "2026-05-20", - "summary": "新增打印失败自动补偿能力:定时扫描并触发 print.retryFailed 批量补打", - "methods": [ - "print.retryFailed" - ], - "notes": [ - "新增定时任务:app/schedule/print_retry_compensation.js,按仓库分组调用 print.retryFailed 进行批量补打。", - "配置项位置:config/config.default.js 的 printRetryCompensation,包含:enable(boolean, 默认 false)、intervalMs(毫秒,默认 60000)、batchSize(批量大小,默认 50)、force(boolean,默认 false)、maxRetryCount(number,默认 5)。", - "行为摘要:任务按 printRetryCompensation.intervalMs 频率查询 send_status=send_failed 或 print_status IN (print_failed, timeout),且 next_retry_at <= now 且 retry_count < maxRetryCount 的记录,按仓库分组并调用 print.retryFailed({ print_ids, warehouse_id, force }) 进行补打。", - "兼容性:print.retryFailed 支持显式传入 warehouse_id(调度任务会传入),当未提供时回退到 ctx.user.store_id;若两者均无则接口返回 400。", - "注意:当前实现中传入的 force 参数不会放宽对状态的判定(代码注释说明为“最小实现”),如需放宽需修改 print.getRetryEligibility 的逻辑。", - "回滚说明:1) 将 printRetryCompensation.enable 设为 false 并重启服务以停止新任务;2) 从部署包中移除或注释 app/schedule/print_retry_compensation.js 并重启服务;3) 如需从 methods/changes/system.json 中移除此变更,请通过生成对应 spec(change.version 设置为本条版本并 type='removed')并运行 npm run doc:api:update -- --spec= 来更新变更记录;4) 若调度已触发的补打需中止,请在调度或队列系统中停止对应任务或通过运维回退正在执行的补打逻辑。" - ], - "module": "print", - "type": "added" - }, { "version": "2026.05.20-system-01", "date": "2026-05-20", @@ -5017,5 +5078,46 @@ "仓库侧导出自动限定 warehouse_id=ctx.user.store_id,货主侧需传 store_id", "导出 Excel 列:序号/创建时间/流水类型/仓库ID/货主ID/商品ID/变动数量/变更前库存/变更后库存/变更前锁定/变更后锁定/批次号/单据类型/单据号/收货单ID/入库单ID/发货单ID/操作人/备注" ] + }, + { + "version": "2026.07.29-system-01", + "date": "2026-07-29", + "type": "added", + "summary": "新增 waybill.warehouse 运单模块(仓库侧):list(列表)、detail(详情)、export(导出)3 个接口,支持运单号独立查询与管理", + "methods": [ + "waybill.warehouse.list", + "waybill.warehouse.detail", + "waybill.warehouse.export" + ], + "notes": [ + "新增 waybill.warehouse.list:仓库侧运单列表查询,支持分页与多条件筛选(运单号/主单号/订单ID/订单号/物流公司/物流接口/平台/状态/退回/拦截/星河签收/包材/称重/关键词/时间范围),默认按 create_at desc 排序。", + "新增 waybill.warehouse.detail:仓库侧运单详情查询,含关联订单信息、兄弟运单(sibling_waybills)、物流信息、状态信息、称重信息、打包信息(打包状态/打包人/打包时间)、打印记录列表。", + "新增 waybill.warehouse.export:仓库侧运单导出,复用 list 筛选逻辑,异步任务模式,支持自定义导出字段。", + "仓库隔离策略:所有接口自动注入 warehouse_id = ctx.user.store_id(全系统统一约定),不可由前端入参覆盖。", + "快照字段方案:wms_order_express 表新增 delivery_order_code、store_id_snapshot、store_name_snapshot、warehouse_name_snapshot 四个快照列,列表查询无需 JOIN 订单表或货主表,仅单表查询 + SELF JOIN(主单号)。", + "主单号/子单号规则:同一 order_id 下 business_key=1 为主单号,business_key>1 为子单号,沿用系统已有约定。", + "命名空间规划:waybill.warehouse.* 本期实现(仓库侧),后续预留 waybill.store.*(货主侧)。", + "本模块一期仅提供只读查询,不涉及运单创建/修改/删除,不修改任何现有接口。" + ], + "module": "waybill.warehouse" + }, + { + "version": "2026.07.30-system-01", + "date": "2026-07-30", + "type": "changed", + "summary": "更新 waybill.warehouse group API 文档:list 新增 waybillType/storeId 筛选、移除 pack_status 响应字段;detail 精简 package 对象;export 响应改为纯异步任务模式(仅含 task_id/status/progress/message/update_time)", + "methods": [ + "waybill.warehouse.list", + "waybill.warehouse.detail", + "waybill.warehouse.export", + "waybill.warehouse.exportTaskProgress" + ], + "notes": [ + "waybill.warehouse.list:新增 where.waybillType 筛选(\"main\"/\"1\"=主单号,\"child\"/\"2\"=子单号),新增 where.storeId 货主ID等值筛选。where.orderNo 标注暂不可用(待快照字段就绪)。response 移除 pack_status 字段(两表无关联,不再返回),list 字段数从 28 减至 27。", + "waybill.warehouse.detail:package 对象移除 pack_status/pack_quantity/pack_at/packer_name 四个字段,仅保留 package_material_id 和 package_material_name。description 同步去掉\"打包状态\"相关描述。", + "waybill.warehouse.export:响应简化为纯异步任务模式,data 仅含 task_id/status/progress/message/update_time,不含 total_count/current_count/result/error/download_url 等执行期字段(这些信息由 exportTaskProgress 接口返回)。export 的 where 参数同步新增 waybillType 和 storeId。", + "waybill.warehouse.exportTaskProgress:无变更,保持不变。" + ], + "module": "waybill.warehouse" } ] diff --git a/methods/system.json b/methods/system.json index 731ccea..08870ca 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.7", - "updatedAt": "2026-07-27", + "version": "0.3.9", + "updatedAt": "2026-07-30", "headers": [ { "name": "platform", @@ -6354,6 +6354,100 @@ } ] }, + { + "method": "order.recheckOrder.batchQuickRecheckByWave", + "description": "按波次批量快捷复核:传入波次 IDs 列表,对每个波次下所有有效订单执行前置检查(已分配储位、已分配快递、已同步且未被拦截),必要时自动完成拣货(含库存锁定校验与扣减、库存流水写入、拣货任务状态同步)后标记复核(含复核任务记录、任务复核状态更新、车任务解绑、操作日志)。每个订单在独立事务中执行,支持部分失败,不满足条件的订单跳过并返回原因。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "wave_ids", + "type": "array|string", + "required": true, + "source": "body|query", + "description": "波次 ID 列表,支持数组或以逗号分隔的字符串。兼容 waveIds(驼峰)、wave_id(单值)" + } + ], + "response": [ + { + "name": "success", + "type": "array", + "required": true, + "description": "复核成功的订单列表", + "children": [ + { + "name": "order_id", + "type": "number", + "description": "订单ID" + }, + { + "name": "wave_id", + "type": "number", + "description": "所属波次ID" + }, + { + "name": "delivery_order_code", + "type": "string", + "description": "发货单号" + } + ] + }, + { + "name": "failed", + "type": "array", + "required": true, + "description": "复核失败的订单列表", + "children": [ + { + "name": "order_id", + "type": "number", + "description": "订单ID(波次无订单时为 null)" + }, + { + "name": "wave_id", + "type": "number", + "description": "所属波次ID" + }, + { + "name": "delivery_order_code", + "type": "string", + "description": "发货单号(波次无订单时为 null)" + }, + { + "name": "reason", + "type": "string", + "description": "失败原因(未分配储位 / 没有分配快递 / 没有同步 / 已拦截 / 波次下无订单 / 复核失败: xxx)" + } + ] + }, + { + "name": "success_count", + "type": "number", + "required": true, + "description": "成功数量" + }, + { + "name": "failed_count", + "type": "number", + "required": true, + "description": "失败数量" + } + ], + "errors": [ + { + "code": 400, + "message": "波次ID列表不能为空" + } + ] + }, { "method": "order.recheckOrder.queryRecheckOrderSingleList", "description": "散单模式复核列表查询,按订单维度返回待复核订单(排除 pick_status='none' 和 recheck_status='fin'),支持分页与关键词/波次号/复核状态筛选。与 recheckOrderList 不同:本方法仅处理散单模式,不包含团购分支。", @@ -6425,8 +6519,18 @@ "required": false, "description": "分页参数 { page, pageSize },默认 page=1, pageSize=20", "children": [ - { "name": "page", "type": "number", "required": false, "description": "页码" }, - { "name": "pageSize", "type": "number", "required": false, "description": "每页条数" } + { + "name": "page", + "type": "number", + "required": false, + "description": "页码" + }, + { + "name": "pageSize", + "type": "number", + "required": false, + "description": "每页条数" + } ] }, { @@ -6435,8 +6539,18 @@ "required": false, "description": "排序参数 { sortField, sortOrder }", "children": [ - { "name": "sortField", "type": "string", "required": false, "description": "排序字段,支持:id、order_id、workbench_id、wave_id、pack_quantity、pack_mode、status、start_time、end_time、create_time、update_time" }, - { "name": "sortOrder", "type": "string", "required": false, "description": "排序方向:ASC / DESC,默认 DESC" } + { + "name": "sortField", + "type": "string", + "required": false, + "description": "排序字段,支持:id、order_id、workbench_id、wave_id、pack_quantity、pack_mode、status、start_time、end_time、create_time、update_time" + }, + { + "name": "sortOrder", + "type": "string", + "required": false, + "description": "排序方向:ASC / DESC,默认 DESC" + } ] }, { @@ -6445,17 +6559,72 @@ "required": false, "description": "筛选条件", "children": [ - { "name": "status", "type": "number", "required": false, "description": "任务状态:0=待处理 1=打包中 2=已完成 3=异常" }, - { "name": "pack_mode", "type": "number", "required": false, "description": "打包模式:1=散单 2=团购" }, - { "name": "waybill_code", "type": "string", "required": false, "description": "运单号(模糊匹配)" }, - { "name": "wave_no", "type": "string", "required": false, "description": "波次号(模糊匹配)" }, - { "name": "order_id", "type": "number", "required": false, "description": "订单ID(精确匹配)" }, - { "name": "workbench_id", "type": "number", "required": false, "description": "工作台ID(精确匹配)" }, - { "name": "quickWhere", "type": "string", "required": false, "description": "快捷搜索:波次号模糊匹配 + 运单号通过 express→order→wave 链路解析" }, - { "name": "start_time_start", "type": "string", "required": false, "description": "开始打包时间范围起始(ISO 8601)" }, - { "name": "start_time_end", "type": "string", "required": false, "description": "开始打包时间范围结束(ISO 8601)" }, - { "name": "has_video", "type": "number", "required": false, "description": "是否包含录像:1=有录像 2=无录像" }, - { "name": "video_enable", "type": "number", "required": false, "description": "录像是否可用:1=可用(存在 video_url 非空且 status!=failed 的记录) 2=不可用" } + { + "name": "status", + "type": "number", + "required": false, + "description": "任务状态:0=待处理 1=打包中 2=已完成 3=异常" + }, + { + "name": "pack_mode", + "type": "number", + "required": false, + "description": "打包模式:1=散单 2=团购" + }, + { + "name": "waybill_code", + "type": "string", + "required": false, + "description": "运单号(模糊匹配)" + }, + { + "name": "wave_no", + "type": "string", + "required": false, + "description": "波次号(模糊匹配)" + }, + { + "name": "order_id", + "type": "number", + "required": false, + "description": "订单ID(精确匹配)" + }, + { + "name": "workbench_id", + "type": "number", + "required": false, + "description": "工作台ID(精确匹配)" + }, + { + "name": "quickWhere", + "type": "string", + "required": false, + "description": "快捷搜索:波次号模糊匹配 + 运单号通过 express→order→wave 链路解析" + }, + { + "name": "start_time_start", + "type": "string", + "required": false, + "description": "开始打包时间范围起始(ISO 8601)" + }, + { + "name": "start_time_end", + "type": "string", + "required": false, + "description": "开始打包时间范围结束(ISO 8601)" + }, + { + "name": "has_video", + "type": "number", + "required": false, + "description": "是否包含录像:1=有录像 2=无录像" + }, + { + "name": "video_enable", + "type": "number", + "required": false, + "description": "录像是否可用:1=可用(存在 video_url 非空且 status!=failed 的记录) 2=不可用" + } ] } ], @@ -11835,6 +12004,159 @@ "description": "查询失败" } ] + }, + { + "method": "order.print.getPrintDataByWaybillCodes", + "description": "按运单号数组拉取平台打印中间态数据,与 getOrderPrintData 返回结构一致。支持子单号(business_key>1):主面单与现有逻辑一致,子面单使用主订单数据构建打印数据并在自定义区追加「子单号【{business_key}】-{主单号}」行。仓库ID统一从当前上下文获取。自动过滤快递未完全分配的订单(post_status !== 'fin'),返回 waveGroups(波次 -> 平台 -> 订单)结构。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "waybill_codes", + "type": "array", + "required": true, + "source": "body", + "description": "运单号数组(字符串数组,内部自动去重与归一化,必须为非空数组)" + } + ], + "response": [ + { + "name": "summary", + "type": "object", + "required": true, + "description": "汇总信息", + "children": [ + { + "name": "total_waves", + "type": "number", + "required": true, + "description": "通过过滤的波次总数" + }, + { + "name": "total_orders", + "type": "number", + "required": true, + "description": "所有平台下打印条目总数(每个运单一条)" + }, + { + "name": "total_platforms", + "type": "number", + "required": true, + "description": "所有波次内平台分组总数(累加)" + } + ] + }, + { + "name": "wave_ids", + "type": "array", + "required": true, + "description": "通过过滤的波次ID数组" + }, + { + "name": "waveGroups", + "type": "array", + "required": true, + "description": "波次分组(波次 -> 平台 -> 订单),结构与 getOrderPrintData 一致", + "children": [ + { + "name": "wave_id", + "type": "number", + "required": true, + "description": "波次ID" + }, + { + "name": "wave_no", + "type": "string", + "required": true, + "description": "波次号" + }, + { + "name": "order_count", + "type": "number", + "required": true, + "description": "该波次下打印条目数" + }, + { + "name": "platforms", + "type": "array", + "required": true, + "description": "平台分组列表", + "children": [ + { + "name": "platform", + "type": "string", + "required": true, + "description": "平台编码" + }, + { + "name": "platform_name", + "type": "string", + "required": true, + "description": "平台名称" + }, + { + "name": "order_count", + "type": "number", + "required": true, + "description": "该平台下打印条目数" + }, + { + "name": "order_ids", + "type": "array", + "required": true, + "description": "订单ID数组(去重)" + }, + { + "name": "orders", + "type": "array", + "required": true, + "description": "打印数据文档数组(print_data)" + } + ] + } + ] + }, + { + "name": "ext", + "type": "object", + "required": true, + "description": "扩展信息", + "children": [ + { + "name": "missing_waybill_codes", + "type": "array", + "required": true, + "description": "未匹配到的运单号" + }, + { + "name": "filtered_waybill_codes", + "type": "array", + "required": true, + "description": "被过滤掉的运单号及其原因,每项含 waybill_code、reason" + } + ] + } + ], + "errors": [ + { + "code": "400", + "message": "waybill_codes 必填,且必须为非空数组", + "description": "waybill_codes 必填,且必须为非空数组" + }, + { + "code": "500", + "message": "查询失败", + "description": "查询失败" + } + ] } ] }, @@ -12687,114 +13009,6 @@ } ] }, - { - "method": "print.retryFailed", - "description": "失败项补打:重试指定打印记录的发送。被定时任务 print-retry-compensation 调用以批量触发失败项补打。", - "isNeedAuth": false, - "isNeedLogin": true, - "headers": [ - { - "name": "Authorization", - "type": "string", - "required": true, - "description": "Bearer token" - } - ], - "params": [ - { - "name": "print_ids", - "type": "array", - "required": true, - "source": "body", - "description": "要补打的打印记录 ID 数组", - "children": [ - { - "name": "id", - "type": "number", - "description": "打印记录 ID" - } - ] - }, - { - "name": "force", - "type": "boolean", - "required": false, - "source": "body", - "description": "是否强制补打(当前实现仍不放宽状态判定)" - }, - { - "name": "warehouse_id", - "type": "number", - "required": false, - "source": "body", - "description": "显式指定仓库 ID(调度任务推荐提供),若缺失将使用当前用户的 store_id" - } - ], - "response": [ - { - "name": "flag", - "type": "string", - "required": true, - "description": "调用标识,成功为 success" - }, - { - "name": "code", - "type": "number", - "required": true, - "description": "业务状态码,成功通常为 200" - }, - { - "name": "message", - "type": "string", - "required": true, - "description": "返回信息" - }, - { - "name": "success_count", - "type": "number", - "required": false, - "description": "成功补打数量" - }, - { - "name": "failed_count", - "type": "number", - "required": false, - "description": "补打失败数量" - }, - { - "name": "skipped_count", - "type": "number", - "required": false, - "description": "被跳过的记录数量" - }, - { - "name": "retried", - "type": "array", - "required": false, - "description": "补打尝试结果数组" - }, - { - "name": "skipped", - "type": "array", - "required": false, - "description": "跳过项明细" - } - ], - "errors": [ - { - "code": 400, - "message": "warehouse_id 参数缺失,且当前上下文无可用仓库信息" - }, - { - "code": 400, - "message": "print_ids 参数不能为空数组或不合法" - }, - { - "code": 500, - "message": "内部错误" - } - ] - }, { "method": "print.notifyLock", "description": "仅执行订单锁定流程,不发送打印任务;记录打印任务日志并写入订单操作日志。兼容别名:print.notify_lock(等价转调)。", @@ -12920,6 +13134,90 @@ "params": [], "response": [], "errors": [] + }, + { + "method": "print.markWavePrintStatus", + "description": "标记/取消标记整个波次订单的打印状态。仓库隔离:从登录上下文获取仓库ID。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "wave_id", + "type": "number", + "required": true, + "source": "body", + "description": "波次ID(必填,正整数)" + }, + { + "name": "status", + "type": "string", + "required": false, + "source": "body", + "description": "目标状态:printed=标记已打印,unprinted=取消已打印标记。默认 printed。" + } + ], + "response": [ + { + "name": "wave_id", + "type": "number", + "description": "波次ID" + }, + { + "name": "status", + "type": "string", + "description": "目标状态" + }, + { + "name": "print_status", + "type": "string", + "description": "订单表 print_status 字段值(fin / none)" + }, + { + "name": "total_orders", + "type": "number", + "description": "波次下总订单数" + }, + { + "name": "affected_orders", + "type": "number", + "description": "实际更新的订单数" + }, + { + "name": "order_ids", + "type": "array", + "description": "波次下所有订单ID" + } + ], + "errors": [ + { + "code": 400, + "message": "wave_id 参数必填,且必须为正整数" + }, + { + "code": 400, + "message": "status 参数不合法,仅支持 printed / unprinted" + }, + { + "code": 400, + "message": "无法获取当前仓库ID,请确认已登录" + }, + { + "code": 404, + "message": "波次在当前仓库下没有可操作的订单" + }, + { + "code": 500, + "message": "内部错误(OrderDeliveryFactory/OrderDeliveryModel 不可用或更新失败)" + } + ] } ] }, @@ -21955,6 +22253,155 @@ } } }, + { + "method": "storage.inventory.export", + "description": "提交库存导出异步任务。支持两种导出模式(exportMode):stock_location(默认,按 stock_id + 库位聚合导出库存汇总,含库位编码/名称、商品信息、总库存/锁定/可用、批次数、最近入库时间等)、storage(按 storage_id 逐条导出库存明细,含库位编码/名称、商品信息、批次号、库存类型、数量、生产日期、过期日期、入库单号等)。立即返回任务受理信息(task_id/status/progress),不直接返回文件。通过 storage.inventory.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": "统一 where 条件对象,与 storage.inventory.list 的 where 语义完全一致。支持字段:stock_id(商品ID)、space_id(库位ID)、store_id(货主ID)、inventory_type(ZP/CC/JS/XS/ZT/DJ/FP)、batch_no(批次号)、inbound_order_no(入库单号)、available_quantity(可用数量,支持 gt/lt)、inbound_time(入库时间,支持 between)、created_at(创建时间,支持 between)" + }, + { + "name": "sort", + "type": "object", + "required": false, + "source": "body", + "description": "排序参数,与 storage.inventory.list 的 sort 语义完全一致。sortField 支持:id/stock_id/space_id/created_at/updated_at/inbound_time/quantity,sortOrder 支持 ASC/DESC。默认 id DESC" + }, + { + "name": "group_by_batch", + "type": "boolean", + "required": false, + "source": "body", + "description": "是否按批次导出,默认 false。与 storage.inventory.list 的 group_by_batch 语义一致。false=合并模式(按 stock_id+库位聚合导出库存汇总,含总库存/锁定/可用/批次数/最近入库时间),true=明细模式(按 storage_id 逐条导出库存明细,含批次号/库存类型/生产日期/过期日期/入库单号等)" + } + ], + "response": [ + { + "name": "task_id", + "type": "string", + "description": "导出任务ID,用于后续查询进度" + }, + { + "name": "status", + "type": "string", + "description": "任务状态:submitted" + }, + { + "name": "progress", + "type": "number", + "description": "进度:0" + }, + { + "name": "message", + "type": "string", + "description": "受理消息" + }, + { + "name": "update_time", + "type": "number", + "description": "更新时间戳" + } + ], + "errors": [ + { + "code": 400, + "message": "where 条件格式不正确" + }, + { + "code": 500, + "message": "导出任务提交失败" + } + ] + }, + { + "method": "storage.inventory.exportTaskProgress", + "description": "按 task_id 查询库存导出任务进度,未找到时 status=not_found。任务完成(status=success)时返回 download_url 供客户端下载导出文件。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "task_id / taskId", + "type": "string", + "required": true, + "source": "body|query", + "description": "任务ID,兼容 taskId 驼峰写法" + } + ], + "response": [ + { + "name": "task_id", + "type": "string", + "description": "任务ID" + }, + { + "name": "status", + "type": "string", + "description": "任务状态:submitted/running/success/failed/not_found" + }, + { + "name": "progress", + "type": "number", + "description": "进度百分比(0-100)" + }, + { + "name": "message", + "type": "string", + "description": "额外提示信息" + }, + { + "name": "result", + "type": "object", + "description": "任务成功时返回的结果对象(含 fileKey/url 等)" + }, + { + "name": "error", + "type": "string", + "description": "失败时的错误信息" + }, + { + "name": "download_url", + "type": "string", + "description": "任务完成后可直接下载的文件地址" + }, + { + "name": "update_time", + "type": "number", + "description": "最近一次状态更新时间戳" + } + ], + "errors": [ + { + "code": 400, + "message": "task_id 参数不能为空" + }, + { + "code": 500, + "message": "查询失败或内部错误" + } + ] + }, { "method": "storage.expiry.list", "description": "库存有效期列表查询(效期预警),按 wms_storage 查询并计算剩余天数与过期状态,支持 where 条件与分页。注意:无需传 warehouse_id/store_id,服务端会从当前登录用户取仓库上下文。", @@ -28968,6 +29415,20 @@ "source": "body", "description": "0-禁用 1-启用" }, + { + "name": "username", + "type": "string", + "required": false, + "source": "body", + "description": "摄像头登录用户名" + }, + { + "name": "password", + "type": "string", + "required": false, + "source": "body", + "description": "摄像头登录密码" + }, { "name": "remark", "type": "string", @@ -29040,6 +29501,20 @@ "source": "body", "description": "0-禁用 1-启用" }, + { + "name": "username", + "type": "string", + "required": false, + "source": "body", + "description": "摄像头登录用户名" + }, + { + "name": "password", + "type": "string", + "required": false, + "source": "body", + "description": "摄像头登录密码" + }, { "name": "remark", "type": "string", @@ -29056,6 +29531,65 @@ } ] }, + { + "method": "camera.setOsd", + "description": "设置摄像头 OSD 文字叠加", + "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": "text", + "type": "string", + "required": true, + "source": "body", + "description": "OSD 叠加文字(必填)" + }, + { + "name": "x", + "type": "number", + "required": false, + "source": "body", + "description": "X 坐标(-1 到 1,默认 -0.9)" + }, + { + "name": "y", + "type": "number", + "required": false, + "source": "body", + "description": "Y 坐标(-1 到 1,默认 0.8)" + } + ], + "response": [], + "errors": [ + { + "code": "400", + "description": "摄像头ID/OSD文字不能为空" + }, + { + "code": "404", + "description": "摄像头不存在或无权操作" + }, + { + "code": "500", + "description": "打印服务调用失败" + } + ] + }, { "method": "camera.delete", "description": "删除摄像头(软删除)", @@ -29413,6 +29947,1899 @@ "errors": [] } ] + }, + { + "groupName": "运单模块(仓库侧)", + "module": "waybill.warehouse", + "list": [ + { + "method": "waybill.warehouse.list", + "description": "运单列表-仓库侧:分页查询运单号列表,支持多条件筛选。仓库隔离(自动注入 warehouse_id = ctx.user.store_id),所有查询仅返回当前仓库数据。通过快照字段(delivery_order_code、store_id_snapshot、store_name_snapshot、warehouse_name_snapshot)避免 JOIN 订单表和货主表,列表核心查询为 wms_order_express 单表 + SELF JOIN(主单号)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token,从中解析 warehouseId(仓库上下文,ctx.user.store_id)" + } + ], + "params": [ + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页参数。默认 page=1, pageSize=20" + }, + { + "name": "pagination.page", + "type": "number", + "required": false, + "source": "body.pagination", + "description": "页码,默认 1" + }, + { + "name": "pagination.pageSize", + "type": "number", + "required": false, + "source": "body.pagination", + "description": "每页条数,默认 20" + }, + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "筛选条件对象,所有字段均为可选" + }, + { + "name": "where.waybillCode", + "type": "string", + "required": false, + "source": "body.where", + "description": "运单号(模糊搜索)" + }, + { + "name": "where.mainWaybillCode", + "type": "string", + "required": false, + "source": "body.where", + "description": "主单号(精确匹配)。先通过主单号定位 order_id,再返回该订单下所有运单(主+子)。与 waybillCode 互斥,同时传入时 mainWaybillCode 优先" + }, + { + "name": "where.orderId", + "type": "number", + "required": false, + "source": "body.where", + "description": "订单ID(等值匹配)" + }, + { + "name": "where.orderNo", + "type": "string", + "required": false, + "source": "body.where", + "description": "订单号(模糊搜索,暂不可用,待快照字段就绪)" + }, + { + "name": "where.waybillType", + "type": "string", + "required": false, + "source": "body.where", + "description": "运单类型:\"main\"/\"1\"=主单号(business_key=1),\"child\"/\"2\"=子单号(business_key>1)" + }, + { + "name": "where.storeId", + "type": "number", + "required": false, + "source": "body.where", + "description": "货主ID(等值匹配)" + }, + { + "name": "where.logisticsCode", + "type": "string", + "required": false, + "source": "body.where", + "description": "物流公司编码(等值匹配),如 SF/YT/STO/ZTO 等" + }, + { + "name": "where.logisticsInterfaceId", + "type": "number", + "required": false, + "source": "body.where", + "description": "物流接口ID(等值匹配),对应 wms_order_express.logistics_interface_id" + }, + { + "name": "where.platformCode", + "type": "string", + "required": false, + "source": "body.where", + "description": "平台编码(等值匹配),如 PDD/DY/KS/JD/CAINIAO/SPH/XHS" + }, + { + "name": "where.status", + "type": "number", + "required": false, + "source": "body.where", + "description": "运单状态:0=未分配,1=已分配" + }, + { + "name": "where.isBack", + "type": "string", + "required": false, + "source": "body.where", + "description": "是否退回:Y/N" + }, + { + "name": "where.isIntercept", + "type": "string", + "required": false, + "source": "body.where", + "description": "是否拦截:Y/N" + }, + { + "name": "where.isGalaxyReceive", + "type": "string", + "required": false, + "source": "body.where", + "description": "是否星河签收:Y/N" + }, + { + "name": "where.packageMaterialId", + "type": "number", + "required": false, + "source": "body.where", + "description": "包材ID(等值匹配)" + }, + { + "name": "where.hasWeighingWeight", + "type": "boolean", + "required": false, + "source": "body.where", + "description": "是否已称重:true=weighing_weight>0,false=weighing_weight=0" + }, + { + "name": "where.keyword", + "type": "string", + "required": false, + "source": "body.where", + "description": "关键词搜索:同时匹配运单号(waybill_code)、主单号、订单号" + }, + { + "name": "where.createdAtStart", + "type": "string", + "required": false, + "source": "body.where", + "description": "创建时间起始,格式 YYYY-MM-DD" + }, + { + "name": "where.createdAtEnd", + "type": "string", + "required": false, + "source": "body.where", + "description": "创建时间截止,格式 YYYY-MM-DD" + }, + { + "name": "sort", + "type": "object", + "required": false, + "source": "body", + "description": "排序参数。默认 create_at desc" + }, + { + "name": "sort.field", + "type": "string", + "required": false, + "source": "body.sort", + "description": "排序字段,白名单:create_at / weighing_weight / id" + }, + { + "name": "sort.order", + "type": "string", + "required": false, + "source": "body.sort", + "description": "排序方向:asc / desc,默认 desc" + } + ], + "response": [ + { + "name": "code", + "type": "number", + "required": true, + "description": "业务状态码,200 表示成功" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "业务提示信息" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "成功时返回的运单列表数据", + "children": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "运单列表数组", + "children": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "运单记录ID(wms_order_express.id)" + }, + { + "name": "waybill_code", + "type": "string", + "required": true, + "description": "运单号" + }, + { + "name": "main_waybill_code", + "type": "string", + "required": true, + "description": "主单号。business_key=1 时等于 waybill_code 本身;business_key>1 时通过 SELF JOIN 查找同 order_id 下 business_key=1 的运单号" + }, + { + "name": "waybill_type", + "type": "string", + "required": true, + "description": "运单类型:business_key=1→'主单号',business_key>1→'子单号'" + }, + { + "name": "order_id", + "type": "number", + "required": true, + "description": "订单ID" + }, + { + "name": "order_no", + "type": "string", + "required": true, + "description": "订单号(来自 delivery_order_code 快照列)" + }, + { + "name": "warehouse_id", + "type": "number", + "required": true, + "description": "仓库ID" + }, + { + "name": "warehouse_name", + "type": "string", + "required": true, + "description": "仓库名称(来自 warehouse_name_snapshot 快照列)" + }, + { + "name": "store_id", + "type": "number", + "required": true, + "description": "货主ID(来自 store_id_snapshot 快照列)" + }, + { + "name": "store_name", + "type": "string", + "required": true, + "description": "货主名称(来自 store_name_snapshot 快照列)" + }, + { + "name": "business_key", + "type": "number", + "required": true, + "description": "拆单序号:1=主单号,>1=子单号" + }, + { + "name": "status", + "type": "number", + "required": true, + "description": "运单状态:0=未分配,1=已分配" + }, + { + "name": "status_text", + "type": "string", + "required": true, + "description": "状态文本:'未分配'/'已分配'" + }, + { + "name": "logistics_interface_id", + "type": "number", + "required": false, + "description": "物流接口ID" + }, + { + "name": "logistics_code", + "type": "string", + "required": false, + "description": "物流公司编码" + }, + { + "name": "logistics_name", + "type": "string", + "required": false, + "description": "物流公司名称" + }, + { + "name": "logistics_interface_name", + "type": "string", + "required": false, + "description": "物流接口名称" + }, + { + "name": "platform_code", + "type": "string", + "required": false, + "description": "平台编码" + }, + { + "name": "platform_name", + "type": "string", + "required": false, + "description": "平台名称(前端映射)" + }, + { + "name": "is_back", + "type": "string", + "required": false, + "description": "是否退回:Y/N" + }, + { + "name": "is_intercept", + "type": "string", + "required": false, + "description": "是否拦截:Y/N" + }, + { + "name": "is_galaxy_receive", + "type": "string", + "required": false, + "description": "是否星河签收:Y/N" + }, + { + "name": "weighing_weight", + "type": "number", + "required": false, + "description": "称重重量(单位:g)" + }, + { + "name": "weighing_weight_display", + "type": "string", + "required": false, + "description": "称重重量可读展示(如 '1.25 kg')" + }, + { + "name": "package_material_id", + "type": "number", + "required": false, + "description": "包材ID" + }, + { + "name": "package_material_name", + "type": "string", + "required": false, + "description": "包材名称(来自 package_material_name_snapshot 快照列)" + }, + { + "name": "print_count", + "type": "number", + "required": false, + "description": "打印次数(COUNT express_print_record)" + }, + { + "name": "last_print_at", + "type": "string", + "required": false, + "description": "最近打印时间" + }, + { + "name": "create_at", + "type": "string", + "required": true, + "description": "运单创建时间" + } + ] + }, + { + "name": "pagination", + "type": "object", + "required": true, + "description": "分页信息", + "children": [ + { + "name": "page", + "type": "number", + "required": true, + "description": "当前页码" + }, + { + "name": "pageSize", + "type": "number", + "required": true, + "description": "每页条数" + }, + { + "name": "total", + "type": "number", + "required": true, + "description": "总记录数" + }, + { + "name": "totalPages", + "type": "number", + "required": true, + "description": "总页数" + } + ] + } + ] + } + ], + "errors": [ + { + "code": "401", + "message": "未登录,请先登录" + }, + { + "code": "405", + "message": "参数校验失败:{具体原因}" + }, + { + "code": "500", + "message": "服务器内部错误:运单列表查询失败" + } + ] + }, + { + "method": "waybill.warehouse.detail", + "description": "运单详情-仓库侧:查看单个运单的完整信息,包含关联订单、打印记录、称重信息。仓库隔离校验。支持按运单记录ID(id)或运单号(waybillCode)查询,waybillCode 优先。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token,从中解析 warehouseId(仓库上下文,ctx.user.store_id)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": false, + "source": "body", + "description": "运单记录ID(wms_order_express.id)。与 waybillCode 二选一,waybillCode 优先" + }, + { + "name": "waybillCode", + "type": "string", + "required": false, + "source": "body", + "description": "运单号。与 id 二选一,waybillCode 优先。需配合仓库隔离校验" + } + ], + "response": [ + { + "name": "code", + "type": "number", + "required": true, + "description": "业务状态码,200 表示成功" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "业务提示信息" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "成功时返回的运单详情数据", + "children": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "运单记录ID" + }, + { + "name": "waybill_code", + "type": "string", + "required": true, + "description": "运单号" + }, + { + "name": "main_waybill_code", + "type": "string", + "required": true, + "description": "主单号" + }, + { + "name": "waybill_type", + "type": "string", + "required": true, + "description": "运单类型:'主单号'/'子单号'" + }, + { + "name": "business_key", + "type": "number", + "required": true, + "description": "拆单序号" + }, + { + "name": "sibling_waybills", + "type": "array", + "required": false, + "description": "同订单下所有运单(兄弟运单),含 waybill_code、business_key、waybill_type", + "children": [ + { + "name": "waybill_code", + "type": "string", + "required": true, + "description": "运单号" + }, + { + "name": "business_key", + "type": "number", + "required": true, + "description": "拆单序号" + }, + { + "name": "waybill_type", + "type": "string", + "required": true, + "description": "运单类型" + } + ] + }, + { + "name": "order", + "type": "object", + "required": true, + "description": "关联订单信息(通过 OrderDeliveryFactory 多表遍历查找)", + "children": [ + { + "name": "order_id", + "type": "number", + "required": true, + "description": "订单ID" + }, + { + "name": "order_no", + "type": "string", + "required": true, + "description": "订单号" + }, + { + "name": "warehouse_id", + "type": "number", + "required": true, + "description": "仓库ID" + }, + { + "name": "warehouse_name", + "type": "string", + "required": true, + "description": "仓库名称(快照)" + }, + { + "name": "store_id", + "type": "number", + "required": true, + "description": "货主ID(快照)" + }, + { + "name": "store_name", + "type": "string", + "required": true, + "description": "货主名称(快照)" + }, + { + "name": "wave_id", + "type": "number", + "required": false, + "description": "波次ID" + }, + { + "name": "wave_no", + "type": "string", + "required": false, + "description": "波次号" + }, + { + "name": "order_type", + "type": "string", + "required": false, + "description": "订单类型:delivery/entry 等" + } + ] + }, + { + "name": "logistics", + "type": "object", + "required": true, + "description": "物流信息", + "children": [ + { + "name": "logistics_code", + "type": "string", + "required": false, + "description": "物流公司编码" + }, + { + "name": "logistics_name", + "type": "string", + "required": false, + "description": "物流公司名称" + }, + { + "name": "logistics_interface_id", + "type": "number", + "required": false, + "description": "物流接口ID" + }, + { + "name": "logistics_interface_name", + "type": "string", + "required": false, + "description": "物流接口名称" + }, + { + "name": "platform_code", + "type": "string", + "required": false, + "description": "平台编码" + } + ] + }, + { + "name": "status_info", + "type": "object", + "required": true, + "description": "运单状态信息", + "children": [ + { + "name": "status", + "type": "number", + "required": true, + "description": "运单状态:0=未分配,1=已分配" + }, + { + "name": "status_text", + "type": "string", + "required": true, + "description": "状态文本" + }, + { + "name": "is_back", + "type": "string", + "required": false, + "description": "是否退回" + }, + { + "name": "is_intercept", + "type": "string", + "required": false, + "description": "是否拦截" + }, + { + "name": "is_galaxy_receive", + "type": "string", + "required": false, + "description": "是否星河签收" + } + ] + }, + { + "name": "weight", + "type": "object", + "required": false, + "description": "称重信息", + "children": [ + { + "name": "weighing_weight", + "type": "number", + "required": false, + "description": "称重重量(g)" + }, + { + "name": "weighing_weight_display", + "type": "string", + "required": false, + "description": "称重重量可读展示" + } + ] + }, + { + "name": "package", + "type": "object", + "required": false, + "description": "包材信息", + "children": [ + { + "name": "package_material_id", + "type": "number", + "required": false, + "description": "包材ID" + }, + { + "name": "package_material_name", + "type": "string", + "required": false, + "description": "包材名称(快照)" + } + ] + }, + { + "name": "print_records", + "type": "array", + "required": false, + "description": "打印记录列表(LEFT JOIN express_print_record ON express_no = waybill_code)", + "children": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "打印记录ID" + }, + { + "name": "printer_name", + "type": "string", + "required": false, + "description": "打印机名称" + }, + { + "name": "template_id", + "type": "number", + "required": false, + "description": "打印模板ID" + }, + { + "name": "template_name", + "type": "string", + "required": false, + "description": "打印模板名称" + }, + { + "name": "platform", + "type": "string", + "required": false, + "description": "平台" + }, + { + "name": "printed_at", + "type": "string", + "required": false, + "description": "打印时间" + } + ] + }, + { + "name": "print_count", + "type": "number", + "required": false, + "description": "打印次数" + }, + { + "name": "printinfo", + "type": "string", + "required": false, + "description": "打印信息(TEXT 字段)" + }, + { + "name": "ver", + "type": "string", + "required": false, + "description": "打印版本号" + }, + { + "name": "retry_count", + "type": "number", + "required": false, + "description": "重试次数" + }, + { + "name": "create_at", + "type": "string", + "required": true, + "description": "运单创建时间" + }, + { + "name": "delete_at", + "type": "string", + "required": false, + "description": "删除时间(软删除),null 表示未删除" + } + ] + } + ], + "errors": [ + { + "code": "401", + "message": "未登录,请先登录" + }, + { + "code": "404", + "message": "运单不存在" + }, + { + "code": "405", + "message": "参数校验失败:请提供运单ID或运单号" + }, + { + "code": "405", + "message": "无权访问该运单(仓库隔离校验不通过)" + }, + { + "code": "500", + "message": "服务器内部错误:运单详情查询失败" + } + ] + }, + { + "method": "waybill.warehouse.export", + "description": "运单导出-仓库侧:按筛选条件导出运单列表为 Excel 文件。复用 waybill.warehouse.list 的筛选逻辑,去掉分页,全量导出。导出为异步任务模式,立即返回任务受理信息,通过 exportTaskProgress 查询进度。仓库隔离(自动注入 warehouse_id)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token,从中解析 warehouseId(仓库上下文,ctx.user.store_id)" + } + ], + "params": [ + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "筛选条件对象,同 waybill.warehouse.list 的 where 参数" + }, + { + "name": "where.waybillCode", + "type": "string", + "required": false, + "source": "body.where", + "description": "运单号(模糊搜索)" + }, + { + "name": "where.mainWaybillCode", + "type": "string", + "required": false, + "source": "body.where", + "description": "主单号(精确匹配)" + }, + { + "name": "where.orderId", + "type": "number", + "required": false, + "source": "body.where", + "description": "订单ID(等值匹配)" + }, + { + "name": "where.orderNo", + "type": "string", + "required": false, + "source": "body.where", + "description": "订单号(模糊搜索,暂不可用,待快照字段就绪)" + }, + { + "name": "where.waybillType", + "type": "string", + "required": false, + "source": "body.where", + "description": "运单类型:\"main\"/\"1\"=主单号,\"child\"/\"2\"=子单号" + }, + { + "name": "where.storeId", + "type": "number", + "required": false, + "source": "body.where", + "description": "货主ID(等值匹配)" + }, + { + "name": "where.logisticsCode", + "type": "string", + "required": false, + "source": "body.where", + "description": "物流公司编码(等值匹配)" + }, + { + "name": "where.logisticsInterfaceId", + "type": "number", + "required": false, + "source": "body.where", + "description": "物流接口ID(等值匹配)" + }, + { + "name": "where.platformCode", + "type": "string", + "required": false, + "source": "body.where", + "description": "平台编码(等值匹配)" + }, + { + "name": "where.status", + "type": "number", + "required": false, + "source": "body.where", + "description": "运单状态:0=未分配,1=已分配" + }, + { + "name": "where.isBack", + "type": "string", + "required": false, + "source": "body.where", + "description": "是否退回:Y/N" + }, + { + "name": "where.isIntercept", + "type": "string", + "required": false, + "source": "body.where", + "description": "是否拦截:Y/N" + }, + { + "name": "where.isGalaxyReceive", + "type": "string", + "required": false, + "source": "body.where", + "description": "是否星河签收:Y/N" + }, + { + "name": "where.packageMaterialId", + "type": "number", + "required": false, + "source": "body.where", + "description": "包材ID(等值匹配)" + }, + { + "name": "where.hasWeighingWeight", + "type": "boolean", + "required": false, + "source": "body.where", + "description": "是否已称重" + }, + { + "name": "where.keyword", + "type": "string", + "required": false, + "source": "body.where", + "description": "关键词搜索" + }, + { + "name": "where.createdAtStart", + "type": "string", + "required": false, + "source": "body.where", + "description": "创建时间起始,格式 YYYY-MM-DD" + }, + { + "name": "where.createdAtEnd", + "type": "string", + "required": false, + "source": "body.where", + "description": "创建时间截止,格式 YYYY-MM-DD" + }, + { + "name": "sort", + "type": "object", + "required": false, + "source": "body", + "description": "排序参数,同 waybill.warehouse.list" + }, + { + "name": "sort.field", + "type": "string", + "required": false, + "source": "body.sort", + "description": "排序字段:create_at / weighing_weight / id" + }, + { + "name": "sort.order", + "type": "string", + "required": false, + "source": "body.sort", + "description": "排序方向:asc / desc" + }, + { + "name": "exportFields", + "type": "array", + "required": false, + "source": "body", + "description": "需要导出的字段列表,不传则导出全部字段。可选字段:waybill_code, main_waybill_code, waybill_type, order_no, warehouse_name, store_name, business_key, status_text, logistics_code, logistics_name, logistics_interface_name, platform_code, weighing_weight, package_material_name, print_count, last_print_at, create_at" + } + ], + "response": [ + { + "name": "code", + "type": "number", + "required": true, + "description": "业务状态码,200 表示任务已受理" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "业务提示信息" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "成功时返回的导出任务受理信息(异步任务模式,不含导出数据)", + "children": [ + { + "name": "task_id", + "type": "string", + "required": true, + "description": "异步导出任务ID,前缀 waybill_export_,用于后续通过 exportTaskProgress 查询进度和获取下载链接" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "任务状态:submitted(已提交)/ running(执行中)/ success(成功)/ failed(失败)" + }, + { + "name": "progress", + "type": "number", + "required": false, + "description": "任务进度百分比(0-100)" + }, + { + "name": "message", + "type": "string", + "required": false, + "description": "任务状态说明" + }, + { + "name": "update_time", + "type": "string", + "required": false, + "description": "任务最近更新时间(ISO 8601)" + } + ] + } + ], + "errors": [ + { + "code": "401", + "message": "未登录,请先登录" + }, + { + "code": "405", + "message": "参数校验失败:{具体原因}" + }, + { + "code": "500", + "message": "服务器内部错误:运单导出任务创建失败" + } + ] + }, + { + "method": "waybill.warehouse.exportTaskProgress", + "description": "运单导出进度查询-仓库侧:按 task_id 或 taskId 查询异步导出任务的执行进度。任务进度通过 Redis 缓存存储,任务 ID 前缀 waybill_export_。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token,从中解析 warehouseId(仓库上下文,ctx.user.store_id)" + } + ], + "params": [ + { + "name": "task_id", + "type": "string", + "required": false, + "source": "body", + "description": "异步导出任务ID(前缀 waybill_export_)。与 taskId 二选一,taskId 优先" + }, + { + "name": "taskId", + "type": "string", + "required": false, + "source": "body", + "description": "异步导出任务ID(别名,优先使用)。至少传入 taskId 或 task_id 之一" + } + ], + "response": [ + { + "name": "code", + "type": "number", + "required": true, + "description": "业务状态码,200 表示成功" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "业务提示信息" + }, + { + "name": "data", + "type": "object", + "required": true, + "description": "成功时返回的导出任务进度信息", + "children": [ + { + "name": "task_id", + "type": "string", + "required": true, + "description": "任务ID" + }, + { + "name": "status", + "type": "string", + "required": true, + "description": "任务状态:submitted(已提交)/ running(执行中)/ success(成功)/ failed(失败)" + }, + { + "name": "progress", + "type": "number", + "required": false, + "description": "任务进度百分比(0-100)" + }, + { + "name": "current_count", + "type": "number", + "required": false, + "description": "当前已处理的运单记录数" + }, + { + "name": "total_count", + "type": "number", + "required": false, + "description": "需要导出的总运单记录数" + }, + { + "name": "message", + "type": "string", + "required": false, + "description": "任务状态说明或错误信息" + }, + { + "name": "result", + "type": "object", + "required": false, + "description": "任务执行结果(status=success 时返回)", + "children": [ + { + "name": "total_exported", + "type": "number", + "required": false, + "description": "实际导出的记录数" + }, + { + "name": "file_size", + "type": "number", + "required": false, + "description": "导出文件大小(字节)" + } + ] + }, + { + "name": "error", + "type": "string", + "required": false, + "description": "错误信息(status=failed 时返回)" + }, + { + "name": "download_url", + "type": "string", + "required": false, + "description": "导出文件下载地址(COS 临时签名 URL,status=success 时返回)" + }, + { + "name": "update_time", + "type": "string", + "required": false, + "description": "任务最近更新时间(ISO 8601)" + } + ] + } + ], + "errors": [ + { + "code": "401", + "message": "未登录,请先登录" + }, + { + "code": "404", + "message": "任务不存在或已过期" + }, + { + "code": "405", + "message": "参数校验失败:请提供 taskId 或 task_id" + }, + { + "code": "500", + "message": "服务器内部错误:导出进度查询失败" + } + ] + } + ] + }, + { + "groupName": "API应用管理模块", + "module": "apiApp", + "list": [ + { + "method": "apiApp.list", + "description": "查询当前仓库的 API 应用列表(分页),返回脱敏后的 AppSecret", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "page", + "type": "number", + "required": false, + "source": "body", + "description": "页码,默认 1" + }, + { + "name": "pageSize", + "type": "number", + "required": false, + "source": "body", + "description": "每页数量,默认 20,最大 100" + }, + { + "name": "app_name", + "type": "string", + "required": false, + "source": "body", + "description": "应用名称(模糊搜索)" + }, + { + "name": "is_enabled", + "type": "number", + "required": false, + "source": "body", + "description": "启用状态:1-启用,0-停用" + } + ], + "response": { + "type": "object", + "properties": [ + { + "name": "list", + "type": "array", + "description": "应用列表", + "children": [ + { + "name": "id", + "type": "number", + "description": "应用 ID" + }, + { + "name": "app_name", + "type": "string", + "description": "应用名称" + }, + { + "name": "warehouse_id", + "type": "number", + "description": "仓库 ID" + }, + { + "name": "interface_type_id", + "type": "number", + "description": "接口类型 ID" + }, + { + "name": "self_app_key", + "type": "string", + "description": "自身 AppKey(对外提供)" + }, + { + "name": "self_app_secret", + "type": "string", + "description": "自身 AppSecret(脱敏,仅显示前8位+****)" + }, + { + "name": "self_ip_whitelist", + "type": "array", + "description": "IP 白名单", + "children": [ + { + "name": "ip", + "type": "string", + "description": "IP 地址或 CIDR" + } + ] + }, + { + "name": "callback_url", + "type": "string", + "description": "回调通知 URL" + }, + { + "name": "rate_limit", + "type": "number", + "description": "速率限制(次/秒)" + }, + { + "name": "sign_method", + "type": "string", + "description": "签名方法:md5/hmac/sha256" + }, + { + "name": "is_enabled", + "type": "number", + "description": "启用状态:1-启用,0-停用" + }, + { + "name": "created_at", + "type": "string", + "description": "创建时间" + }, + { + "name": "updated_at", + "type": "string", + "description": "更新时间" + } + ] + }, + { + "name": "pagination", + "type": "object", + "description": "分页信息", + "children": [ + { + "name": "page", + "type": "number", + "description": "当前页" + }, + { + "name": "pageSize", + "type": "number", + "description": "每页数量" + }, + { + "name": "total", + "type": "number", + "description": "总记录数" + }, + { + "name": "totalPages", + "type": "number", + "description": "总页数" + }, + { + "name": "hasNext", + "type": "boolean", + "description": "是否有下一页" + }, + { + "name": "hasPrevious", + "type": "boolean", + "description": "是否有上一页" + } + ] + } + ] + }, + "errors": [ + { + "code": "401", + "message": "未登录,请先登录" + }, + { + "code": "500", + "message": "服务器内部错误:查询 API 应用列表失败" + } + ] + }, + { + "method": "apiApp.detail", + "description": "查询单个 API 应用详情", + "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": { + "type": "object", + "properties": [ + { + "name": "id", + "type": "number", + "description": "应用 ID" + }, + { + "name": "app_name", + "type": "string", + "description": "应用名称" + }, + { + "name": "warehouse_id", + "type": "number", + "description": "仓库 ID" + }, + { + "name": "interface_type_id", + "type": "number", + "description": "接口类型 ID" + }, + { + "name": "self_app_key", + "type": "string", + "description": "自身 AppKey" + }, + { + "name": "self_app_secret", + "type": "string", + "description": "自身 AppSecret(脱敏)" + }, + { + "name": "self_ip_whitelist", + "type": "array", + "description": "IP 白名单" + }, + { + "name": "callback_url", + "type": "string", + "description": "回调通知 URL" + }, + { + "name": "rate_limit", + "type": "number", + "description": "速率限制" + }, + { + "name": "sign_method", + "type": "string", + "description": "签名方法" + }, + { + "name": "is_enabled", + "type": "number", + "description": "启用状态" + }, + { + "name": "created_at", + "type": "string", + "description": "创建时间" + }, + { + "name": "updated_at", + "type": "string", + "description": "更新时间" + } + ] + }, + "errors": [ + { + "code": "400", + "message": "ID不能为空" + }, + { + "code": "401", + "message": "未登录,请先登录" + }, + { + "code": "404", + "message": "API应用不存在" + }, + { + "code": "500", + "message": "服务器内部错误:查询 API 应用详情失败" + } + ] + }, + { + "method": "apiApp.create", + "description": "创建 API 应用,自动生成 AppKey(AK{时间戳}{随机8位hex})和 AppSecret(64位hex)。仅创建时返回完整 Secret", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "app_name", + "type": "string", + "required": true, + "source": "body", + "description": "应用名称,最大 200 字符" + }, + { + "name": "interface_type_id", + "type": "number", + "required": false, + "source": "body", + "description": "接口类型 ID,不传则默认取 WH_CHANNEL 类型" + }, + { + "name": "self_ip_whitelist", + "type": "array", + "required": false, + "source": "body", + "description": "IP 白名单,如 [\"192.168.1.1\", \"10.0.0.0/24\"]", + "children": [ + { + "name": "ip", + "type": "string", + "description": "IP 地址或 CIDR" + } + ] + }, + { + "name": "callback_url", + "type": "string", + "required": false, + "source": "body", + "description": "API 回调通知 URL" + }, + { + "name": "rate_limit", + "type": "number", + "required": false, + "source": "body", + "description": "速率限制(次/秒),默认 1000,范围 1-100000" + }, + { + "name": "sign_method", + "type": "string", + "required": false, + "source": "body", + "description": "签名方法:md5/hmac/sha256,默认 md5" + } + ], + "response": { + "type": "object", + "properties": [ + { + "name": "id", + "type": "number", + "description": "应用 ID" + }, + { + "name": "app_name", + "type": "string", + "description": "应用名称" + }, + { + "name": "self_app_key", + "type": "string", + "description": "自动生成的 AppKey" + }, + { + "name": "self_app_secret", + "type": "string", + "description": "自动生成的 AppSecret(仅创建和重新生成时返回完整值,请妥善保存)" + }, + { + "name": "warehouse_id", + "type": "number", + "description": "所属仓库 ID" + }, + { + "name": "interface_type_id", + "type": "number", + "description": "接口类型 ID" + }, + { + "name": "rate_limit", + "type": "number", + "description": "速率限制" + }, + { + "name": "sign_method", + "type": "string", + "description": "签名方法" + }, + { + "name": "is_enabled", + "type": "number", + "description": "启用状态,创建后默认 1" + }, + { + "name": "created_at", + "type": "string", + "description": "创建时间" + } + ] + }, + "errors": [ + { + "code": "400", + "message": "应用名称不能为空" + }, + { + "code": "400", + "message": "应用名称不能超过200个字符" + }, + { + "code": "401", + "message": "未登录,请先登录" + }, + { + "code": "403", + "message": "无法获取当前仓库ID" + }, + { + "code": "500", + "message": "服务器内部错误:创建 API 应用失败" + } + ] + }, + { + "method": "apiApp.update", + "description": "更新 API 应用(名称、白名单、回调地址、限流、签名方法、启用状态),不可变字段:app_key、interface_type_id", + "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": "app_name", + "type": "string", + "required": false, + "source": "body", + "description": "应用名称,最大 200 字符" + }, + { + "name": "self_ip_whitelist", + "type": "array", + "required": false, + "source": "body", + "description": "IP 白名单" + }, + { + "name": "callback_url", + "type": "string", + "required": false, + "source": "body", + "description": "回调通知 URL" + }, + { + "name": "rate_limit", + "type": "number", + "required": false, + "source": "body", + "description": "速率限制,范围 1-100000" + }, + { + "name": "sign_method", + "type": "string", + "required": false, + "source": "body", + "description": "签名方法:md5/hmac/sha256" + }, + { + "name": "is_enabled", + "type": "number", + "required": false, + "source": "body", + "description": "启用状态:1-启用,0-停用" + } + ], + "response": { + "type": "object", + "properties": [ + { + "name": "id", + "type": "number", + "description": "应用 ID" + }, + { + "name": "app_name", + "type": "string", + "description": "应用名称" + }, + { + "name": "self_app_key", + "type": "string", + "description": "AppKey(不可变)" + }, + { + "name": "self_app_secret", + "type": "string", + "description": "AppSecret(脱敏)" + }, + { + "name": "is_enabled", + "type": "number", + "description": "启用状态" + }, + { + "name": "updated_at", + "type": "string", + "description": "更新时间" + } + ] + }, + "errors": [ + { + "code": "400", + "message": "ID不能为空" + }, + { + "code": "400", + "message": "应用名称不能为空/不能超过200个字符" + }, + { + "code": "400", + "message": "签名方法仅支持 md5/hmac/sha256" + }, + { + "code": "401", + "message": "未登录,请先登录" + }, + { + "code": "404", + "message": "API应用不存在或不属于当前仓库" + }, + { + "code": "500", + "message": "服务器内部错误:更新 API 应用失败" + } + ] + }, + { + "method": "apiApp.delete", + "description": "停用 API 应用(软删除,设置 is_enabled=0,不物理删除数据)", + "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": { + "type": "object", + "properties": [] + }, + "errors": [ + { + "code": "400", + "message": "ID不能为空" + }, + { + "code": "401", + "message": "未登录,请先登录" + }, + { + "code": "404", + "message": "API应用不存在或不属于当前仓库" + }, + { + "code": "500", + "message": "服务器内部错误:停用 API 应用失败" + } + ] + }, + { + "method": "apiApp.regenerateSecret", + "description": "重新生成 AppSecret,旧 Secret 立即失效。仅此次返回完整 Secret,请妥善保存", + "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": { + "type": "object", + "properties": [ + { + "name": "id", + "type": "number", + "description": "应用 ID" + }, + { + "name": "app_name", + "type": "string", + "description": "应用名称" + }, + { + "name": "self_app_key", + "type": "string", + "description": "AppKey(不变)" + }, + { + "name": "self_app_secret", + "type": "string", + "description": "新生成的 AppSecret,64位十六进制(仅此次返回完整值,请妥善保存)" + } + ] + }, + "errors": [ + { + "code": "400", + "message": "ID不能为空" + }, + { + "code": "401", + "message": "未登录,请先登录" + }, + { + "code": "404", + "message": "API应用不存在或不属于当前仓库" + }, + { + "code": "500", + "message": "服务器内部错误:重新生成 AppSecret 失败" + } + ] + } + ] } ] }