From 2d1b9e98fad8a2dee1d976e421e8343a3645cc23 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Thu, 13 Aug 2026 21:40:57 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=E8=BF=90=E5=8D=95?= =?UTF-8?q?=E9=80=80=E5=9B=9E=E7=99=BB=E8=AE=B0=E6=A8=A1=E5=9D=97=EF=BC=88?= =?UTF-8?q?returnWaybill=EF=BC=89=E5=B9=B6=E5=90=8C=E6=AD=A5=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 复用 wms_return_query_log 表,提供货主+运单号退回登记增删查改(create/update/list/detail/delete) - create 幂等(同仓库+货主+运单号返回已有);货主合约校验;update 冲突 409 - 权限固定 ID 551-555 + 角色授权迁移 - 同步 methods/system.json 退回拆包/运单退回登记模块与 changes 变更记录 --- app/service/systemMethods/returnWaybill.js | 132 ++ app/service/systems/return_waybill.js | 371 +++++ ...60000-create-return-waybill-permissions.js | 104 ++ methods/changes/system.json | 141 ++ methods/system.json | 1368 +++++++++++++++-- 5 files changed, 2024 insertions(+), 92 deletions(-) create mode 100644 app/service/systemMethods/returnWaybill.js create mode 100644 app/service/systems/return_waybill.js create mode 100644 database/migrations/20260813160000-create-return-waybill-permissions.js diff --git a/app/service/systemMethods/returnWaybill.js b/app/service/systemMethods/returnWaybill.js new file mode 100644 index 0000000..74ec66a --- /dev/null +++ b/app/service/systemMethods/returnWaybill.js @@ -0,0 +1,132 @@ +'use strict'; + +const MainService = require('../main'); + +/** + * 系统方法层:returnWaybill(运单退回登记模块接口包装层)。 + * 主要职责:统一包装系统方法接口,处理权限、where 解析等公共逻辑, + * 将具体业务逻辑下沉到 systems.return_waybill 中。 + */ +class ReturnWaybillMethodService extends MainService { + constructor(ctx) { + super(ctx); + // 免登录方法列表:空(全部需要登录) + const _noNeedLogin = ''; + // 免权限方法列表:detail 复用列表权限(仅登录 + 仓库隔离校验),其余走 API 权限校验 + const _noNeedRight = 'detail'; + // 免日志方法列表:空(全部记录日志) + const _noNeedLog = ''; + // 免鉴权(仓库有效期检查)方法列表:空(全部检查有效期) + const _noNeedAuth = ''; + this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth); + } + + /** + * 统一调用运单退回登记业务服务,并捕获业务错误码。 + * + * @param {Function} fn 业务调用函数。 + * @param {string} fallbackMessage 兜底错误文案。 + * @return {Promise} 统一 success/fail 包装。 + */ + async _call(fn, fallbackMessage) { + try { + const result = await fn(); + return this.success('ok', result); + } catch (error) { + const code = Number(error && error.code); + if (Number.isInteger(code) && code >= 400 && code < 600) { + return this.fail(error.message || fallbackMessage, {}, code); + } + this.ctx.logger.error(`[returnWaybill] ${fallbackMessage}: ${error && error.message ? error.message : error}`); + return this.fail('服务器内部错误', {}, 500); + } + } + + /** + * 运单退回登记(增)。 + * + * @param {Object} data 请求体。 + * @param {string} data.waybill_code 运单号。 + * @param {number} data.store_id 货主ID。 + * @param {string} [data.remark] 备注。 + * @return {Promise} 统一 success 包装。 + */ + async create(data = {}) { + const { waybill_code, store_id, remark } = data; + return this._call( + () => this.service.systems.returnWaybill.create({ waybill_code, store_id, remark }), + '登记失败' + ); + } + + /** + * 修改登记(改)。 + * + * @param {Object} data 请求体。 + * @param {number} data.id 登记记录ID。 + * @param {string} [data.waybill_code] 运单号。 + * @param {number} [data.store_id] 货主ID。 + * @param {string} [data.remark] 备注。 + * @return {Promise} 统一 success 包装。 + */ + async update(data = {}) { + const { id, waybill_code, store_id, remark } = data; + return this._call( + () => this.service.systems.returnWaybill.update({ id, waybill_code, store_id, remark }), + '修改登记失败' + ); + } + + /** + * 分页查询登记列表(查,仓库隔离自动注入)。 + * + * @param {Object} data 请求体。 + * @param {Object} [data.pagination] 分页参数。 + * @param {Object} [data.where] 筛选条件。 + * @param {Object} [data.sort] 排序参数。 + * @return {Promise} 统一 success 包装。 + */ + async list(data = {}) { + const { service } = this; + const { pagination, sort } = data; + const { where } = this.prepareWhereContext(data, {}); + + // 仓库隔离:由服务端从当前上下文自动注入,禁止前端传入 + const warehouseId = Number(this.ctx.user && this.ctx.user.store_id || 0); + const enforcedWhere = { ...where }; + if (warehouseId > 0) { + enforcedWhere.warehouse_id = { operator: 'eq', value: warehouseId }; + } + + return this._call( + () => service.systems.returnWaybill.list(enforcedWhere, pagination, sort), + '查询列表失败' + ); + } + + /** + * 查询单条登记详情(查)。 + * + * @param {Object} data 请求体。 + * @param {number} data.id 登记记录ID。 + * @return {Promise} 统一 success 包装。 + */ + async detail(data = {}) { + const { id } = data; + return this._call(() => this.service.systems.returnWaybill.detail(Number(id)), '查询详情失败'); + } + + /** + * 删除单条登记(删)。 + * + * @param {Object} data 请求体。 + * @param {number} data.id 登记记录ID。 + * @return {Promise} 统一 success 包装。 + */ + async delete(data = {}) { + const { id } = data; + return this._call(() => this.service.systems.returnWaybill.delete(Number(id)), '删除失败'); + } +} + +module.exports = ReturnWaybillMethodService; diff --git a/app/service/systems/return_waybill.js b/app/service/systems/return_waybill.js new file mode 100644 index 0000000..fafd8c4 --- /dev/null +++ b/app/service/systems/return_waybill.js @@ -0,0 +1,371 @@ +'use strict'; + +const Service = require('egg').Service; + +/** + * 运单退回登记模块业务逻辑层。 + * 复用 wms_return_query_log 表,提供「货主 + 运单号」退回登记的增删查改。 + * 所有数据库交互集中在此层,供 systemMethods/returnWaybill.js 调用。 + */ +class ReturnWaybillService extends Service { + /** + * 创建带业务错误码的异常对象。 + * + * @param {string} message 错误信息。 + * @param {number} [code=400] 业务错误码。 + * @return {Error} 包含 code 的异常对象。 + */ + createBusinessError(message, code = 400) { + const error = new Error(`${message}`); + error.code = code; + return error; + } + + /** + * 运单退回登记(增)。入参:运单号 + 货主ID。 + * 同 warehouse_id + store_id + waybill_code 已存在时返回已有记录(幂等)。 + * + * @param {Object} params 登记参数。 + * @param {string} params.waybill_code 运单号(必填)。 + * @param {number} params.store_id 货主ID(必填)。 + * @param {string} [params.remark] 备注。 + * @return {Promise} { record, duplicated }。 + */ + async create({ waybill_code, store_id, remark }) { + const { ctx } = this; + + const waybillCode = String(waybill_code || '').trim(); + if (!waybillCode) { + throw this.createBusinessError('waybill_code 不能为空', 400); + } + + const storeId = Number(store_id || 0); + if (!Number.isFinite(storeId) || storeId <= 0) { + throw this.createBusinessError('store_id 必填且必须为正整数', 400); + } + + const warehouseId = Number(ctx.user && ctx.user.store_id || 0); + if (!Number.isFinite(warehouseId) || warehouseId <= 0) { + throw this.createBusinessError('缺少仓库上下文', 400); + } + + // 货主合约校验:wms_store_warehouse 存在 store_id + warehouse_id 合约 + await this._assertStoreContract(storeId, warehouseId); + + // 幂等:同仓库+货主+运单号已存在 → 返回已有记录 + const existing = await ctx.model.ReturnQueryLog.findOne({ + where: { + warehouse_id: warehouseId, + store_id: storeId, + waybill_code: waybillCode, + }, + order: [[ 'id', 'ASC' ]], + raw: true, + }); + if (existing) { + return { record: this._formatRow(existing), duplicated: true }; + } + + const created = await ctx.model.ReturnQueryLog.create({ + warehouse_id: warehouseId, + store_id: storeId, + waybill_code: waybillCode, + remark: remark ? String(remark).slice(0, 500) : null, + is_notified: 0, + is_back: 0, + }); + + const createdRow = created && typeof created.toJSON === 'function' ? created.toJSON() : created; + return { record: this._formatRow(createdRow), duplicated: false }; + } + + /** + * 修改登记(改)。入参:id + 可改运单号/货主ID/备注。 + * + * @param {Object} params 修改参数。 + * @param {number} params.id 登记记录ID(必填)。 + * @param {string} [params.waybill_code] 运单号。 + * @param {number} [params.store_id] 货主ID。 + * @param {string} [params.remark] 备注。 + * @return {Promise} { record }。 + */ + async update({ id, waybill_code, store_id, remark }) { + const { ctx } = this; + const { Op } = ctx.app.Sequelize; + + const record = await this._findByIdChecked(id); + + const updateFields = {}; + const nextWaybillCode = waybill_code !== undefined && waybill_code !== null + ? String(waybill_code).trim() + : record.waybill_code; + if (!nextWaybillCode) { + throw this.createBusinessError('waybill_code 不能为空', 400); + } + + const nextStoreId = store_id !== undefined && store_id !== null + ? Number(store_id) + : Number(record.store_id); + if (!Number.isFinite(nextStoreId) || nextStoreId <= 0) { + throw this.createBusinessError('store_id 必填且必须为正整数', 400); + } + + if (waybill_code !== undefined && waybill_code !== null) { + updateFields.waybill_code = nextWaybillCode; + } + if (store_id !== undefined && store_id !== null && Number(store_id) !== Number(record.store_id)) { + // 货主变更时校验新货主合约 + await this._assertStoreContract(nextStoreId, record.warehouse_id); + updateFields.store_id = nextStoreId; + } + if (remark !== undefined && remark !== null) { + updateFields.remark = String(remark).slice(0, 500); + } + + // 冲突防护:改后与另一条同仓库+货主+运单号冲突则拒绝 + const changed = Object.keys(updateFields).length > 0; + if (changed) { + const conflict = await ctx.model.ReturnQueryLog.findOne({ + where: { + warehouse_id: record.warehouse_id, + store_id: nextStoreId, + waybill_code: nextWaybillCode, + id: { [Op.ne]: record.id }, + }, + attributes: [ 'id' ], + raw: true, + }); + if (conflict) { + throw this.createBusinessError('已存在相同货主 + 运单号的登记记录', 409); + } + + await ctx.model.ReturnQueryLog.update(updateFields, { + where: { id: record.id }, + }); + } + + const updated = await ctx.model.ReturnQueryLog.findOne({ + where: { id: record.id }, + raw: true, + }); + + return { record: this._formatRow(updated) }; + } + + /** + * 分页查询登记列表(仓库隔离由方法层注入 warehouse_id)。 + * + * @param {Object} where 标准化 where 条件对象。 + * @param {Object} [pagination] 分页参数。 + * @param {Object} [sort] 排序参数。 + * @return {Promise} { list, pagination }。 + */ + async list(where = {}, pagination = {}, sort = {}) { + const { ctx, app } = this; + const { Op } = app.Sequelize; + + const page = Math.max(1, parseInt(pagination.page) || 1); + const pageSize = Math.min(500, Math.max(1, parseInt(pagination.pageSize) || 20)); + + const queryWhere = this._buildListWhere(where, Op); + const order = this._buildListOrder(sort); + + const { count, rows } = await ctx.model.ReturnQueryLog.findAndCountAll({ + where: queryWhere, + order, + offset: (page - 1) * pageSize, + limit: pageSize, + raw: true, + }); + + return { + list: rows.map(row => this._formatRow(row)), + pagination: { + page, + pageSize, + total: count, + totalPages: Math.ceil(count / pageSize), + hasPrevious: page > 1, + hasNext: page * pageSize < count, + }, + }; + } + + /** + * 查询单条登记详情。 + * + * @param {number} id 登记记录ID。 + * @return {Promise} { record }。 + */ + async detail(id) { + const record = await this._findByIdChecked(id); + return { record: this._formatRow(record) }; + } + + /** + * 删除单条登记(物理删除)。 + * + * @param {number} id 登记记录ID。 + * @return {Promise} 删除结果,含被删除记录 id。 + */ + async delete(id) { + const { ctx } = this; + const record = await this._findByIdChecked(id); + await ctx.model.ReturnQueryLog.destroy({ where: { id: record.id } }); + return { id: record.id }; + } + + // =========================== + // 辅助方法 + // =========================== + + /** + * 按主键查询登记记录,并校验仓库隔离。 + * + * @param {number} id 登记记录ID。 + * @return {Promise} 登记记录原始数据。 + */ + async _findByIdChecked(id) { + const { ctx } = this; + const normalizedId = Number(id || 0); + if (!Number.isFinite(normalizedId) || normalizedId <= 0) { + throw this.createBusinessError('id 必填且必须为正整数', 400); + } + + const record = await ctx.model.ReturnQueryLog.findOne({ + where: { id: normalizedId }, + raw: true, + }); + if (!record) { + throw this.createBusinessError('登记记录不存在', 404); + } + + const warehouseId = Number(ctx.user && ctx.user.store_id || 0); + if (warehouseId > 0 && Number(record.warehouse_id) !== warehouseId) { + throw this.createBusinessError('无权访问该登记记录', 403); + } + + return record; + } + + /** + * 货主合约校验:wms_store_warehouse 必须存在 store_id + warehouse_id 合约。 + * + * @param {number} storeId 货主ID。 + * @param {number} warehouseId 仓库ID。 + * @return {Promise} 校验失败抛业务异常。 + */ + async _assertStoreContract(storeId, warehouseId) { + const { ctx } = this; + const contract = await ctx.model.StoreWarehouse.findOne({ + where: { store_id: storeId, warehouse_id: warehouseId }, + attributes: [ 'id' ], + raw: true, + }); + if (!contract) { + throw this.createBusinessError('货主在当前仓库无合约关系,无法登记', 400); + } + } + + /** + * 格式化登记记录(时间字段本地化)。 + * + * @param {Object} row 登记记录原始数据。 + * @return {Object} 格式化后的记录。 + */ + _formatRow(row) { + const { app } = this; + const record = { ...row }; + record.created_at = record.created_at ? app.formatDate(record.created_at) : null; + record.updated_at = record.updated_at ? app.formatDate(record.updated_at) : null; + return record; + } + + /** + * 根据标准化 where 条件构建 Sequelize 查询条件。 + * + * @param {Object} where 标准化 where 条件对象。 + * @param {Object} Op Sequelize Op 对象。 + * @return {Object} Sequelize where 条件。 + */ + _buildListWhere(where = {}, Op) { + const queryWhere = {}; + + const fields = [ + 'warehouse_id', 'store_id', 'waybill_code', + 'is_notified', 'is_back', 'created_at', 'updated_at', + ]; + + for (const field of fields) { + if (where[field] !== undefined && where[field] !== null) { + queryWhere[field] = this._resolveConditionValue(where[field], Op); + } + } + + return queryWhere; + } + + /** + * 解析标准化条件值为 Sequelize 可用的条件对象。 + * + * @param {*} condition 标准化条件(可能是 {operator, value} 或直接值)。 + * @param {Object} Op Sequelize Op 对象。 + * @return {*} Sequelize 条件。 + */ + _resolveConditionValue(condition, Op) { + if (condition && typeof condition === 'object' && !Array.isArray(condition)) { + const operator = condition.operator; + const value = condition.value; + + if (!operator) { + return value; + } + + switch (operator) { + case 'eq': + return value; + case 'ne': + return { [Op.ne]: value }; + case 'in': + return { [Op.in]: Array.isArray(value) ? value : [ value ] }; + case 'notin': + return { [Op.notIn]: Array.isArray(value) ? value : [ value ] }; + case 'like': + return { [Op.like]: `%${value}%` }; + case 'gt': + return { [Op.gt]: value }; + case 'gte': + return { [Op.gte]: value }; + case 'lt': + return { [Op.lt]: value }; + case 'lte': + return { [Op.lte]: value }; + case 'between': + return { [Op.between]: Array.isArray(value) ? value : [ value ] }; + default: + return value; + } + } + + return condition; + } + + /** + * 根据 sort 参数构建 Sequelize 排序数组。 + * + * @param {Object} sort 排序参数。 + * @return {Array>} Sequelize order 数组。 + */ + _buildListOrder(sort = {}) { + const sortField = sort.sortField || sort.sort_field || 'created_at'; + const sortOrderRaw = (sort.sortOrder || sort.sort_order || 'desc').toLowerCase(); + const sortOrder = sortOrderRaw === 'asc' ? 'ASC' : 'DESC'; + + const allowedSortFields = new Set([ 'id', 'created_at', 'updated_at', 'waybill_code' ]); + const safeSortField = allowedSortFields.has(sortField) ? sortField : 'created_at'; + + return [[ safeSortField, sortOrder ]]; + } +} + +module.exports = ReturnWaybillService; diff --git a/database/migrations/20260813160000-create-return-waybill-permissions.js b/database/migrations/20260813160000-create-return-waybill-permissions.js new file mode 100644 index 0000000..8710091 --- /dev/null +++ b/database/migrations/20260813160000-create-return-waybill-permissions.js @@ -0,0 +1,104 @@ +'use strict'; + +/** + * 运单退回登记模块权限记录 + 角色授权迁移。 + * + * 权限明细(固定 ID 551-555,550 预留): + * 551 — returnWaybill.create API:运单退回登记 + * 552 — returnWaybill.update API:运单退回登记修改 + * 553 — returnWaybill.list API:运单退回登记列表 + * 554 — returnWaybill.detail API:运单退回登记详情 + * 555 — returnWaybill.delete API:运单退回登记删除 + * + * 角色授权(系统预设角色,不含通配符角色): + * 作业类(551-552)→ 仓库组-员工(27) → 仓库组-主管(26)(仓库员工及以上) + * 查询/删除类(553-555)→ 客服组-员工(30) → 客服组-主管(28)(客服员工及以上) + * 经理(8)/仓库管理员(2)/超级管理员(7) 已持有 * 通配符,自动拥有所有权限,无需处理 + * + * 幂等:INSERT IGNORE 创建权限记录;角色权限数组追加后去重排序,已存在跳过。 + */ + +const TABLE = 'wms_permission'; +const ROLE_TABLE = 'wms_role'; +const COLUMNS = 'id, path, component, name, redirect, meta_title, meta_icon, hidden, always_show, parent_id, type, sort, status, created_at, update_at'; + +/** 权限ID → 授权角色ID列表(不含通配符角色) */ +const PERMISSION_ROLES = { + 551: [ 27, 26 ], + 552: [ 27, 26 ], + 553: [ 30, 28 ], + 554: [ 30, 28 ], + 555: [ 30, 28 ], +}; + +module.exports = { + // eslint-disable-next-line no-unused-vars + async up(queryInterface, Sequelize) { + // ── 1. 创建 API 权限记录(固定 ID)── + const apis = [ + [ 551, 'returnWaybill.create', 'API:运单退回登记' ], + [ 552, 'returnWaybill.update', 'API:运单退回登记修改' ], + [ 553, 'returnWaybill.list', 'API:运单退回登记列表' ], + [ 554, 'returnWaybill.detail', 'API:运单退回登记详情' ], + [ 555, 'returnWaybill.delete', 'API:运单退回登记删除' ], + ]; + + for (const [ id, path, metaTitle ] of apis) { + await queryInterface.sequelize.query( + `INSERT IGNORE INTO \`${TABLE}\` (${COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NOW(), NOW())`, + { replacements: [ id, path, null, path, null, metaTitle, null, 0, 0, null, 'api', 0, 1 ] } + ); + } + + // ── 2. 角色授权注入 ── + for (const permId of Object.keys(PERMISSION_ROLES).map(Number)) { + for (const roleId of PERMISSION_ROLES[permId]) { + const rows = await queryInterface.sequelize.query( + `SELECT id, permissions FROM \`${ROLE_TABLE}\` WHERE id = ?`, + { replacements: [ roleId ], type: queryInterface.sequelize.QueryTypes.SELECT } + ); + const record = Array.isArray(rows) ? rows[0] : null; + if (!record) { + continue; + } + + // 通配符角色跳过 + if (record.permissions === '*') { + continue; + } + + let perms; + try { + perms = JSON.parse(record.permissions || '[]'); + } catch (err) { + continue; + } + if (!Array.isArray(perms)) { + continue; + } + + if (perms.includes(permId)) { + continue; + } + + perms.push(permId); + perms.sort((a, b) => a - b); + + await queryInterface.sequelize.query( + `UPDATE \`${ROLE_TABLE}\` SET permissions = ? WHERE id = ?`, + { replacements: [ JSON.stringify(perms), roleId ] } + ); + } + } + }, + + // eslint-disable-next-line no-unused-vars + async down(queryInterface, Sequelize) { + const ids = [ 551, 552, 553, 554, 555 ]; + const placeholders = ids.map(() => '?').join(', '); + await queryInterface.sequelize.query( + `DELETE FROM \`${TABLE}\` WHERE id IN (${placeholders})`, + { replacements: ids } + ); + }, +}; diff --git a/methods/changes/system.json b/methods/changes/system.json index 239f8da..9ef0b36 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,21 @@ [ + { + "version": "2026.08.13-stockQueryWhere", + "date": "2026-08-13", + "type": "added", + "summary": "storage.receiving.getReceivingList / getStoreReceivingList 新增 stock_query_where 参数:按商品条码/商品编码/商品ID 搜索,经收货明细关联过滤收货单列表(仓库侧与货主侧同步支持)", + "methods": [ + "storage.receiving.getReceivingList", + "storage.receiving.getStoreReceivingList" + ], + "notes": [ + "新增 stock_query_where 入参(string|string[], optional, body,前端通常传数组),搜索范围:wms_stock_barcodes.barcode + wms_stock_warehouse.item_code + wms_stock_warehouse.id(纯数字时精确匹配)", + "解析链路:stock_query_where → wms_stock_warehouse.id 集合 → wms_receiving_detail.system_product_id IN 集合 → receiving_id 列表", + "与 filterDepleted、entry_order_id 可组合使用(多组过滤取交集,仓库侧),无匹配结果时返回空列表", + "代码变更:systems/storage/receiving.js 新增 _resolveStockQueryReceivingIds 并对两个列表方法注入过滤;systemMethods/storage/receiving.js 两个列表方法均透传 stock_query_where;methods/system.json 两个接口均新增参数文档" + ], + "module": "storage" + }, { "version": "2026.08.12-confirmIntercept-doc", "date": "2026-08-12", @@ -5775,5 +5792,129 @@ "代码变更:app/model/return_received.js、app/service/systems/return_received.js、app/service/systemMethods/returnReceived.js、database/migrations/20260812160000-create-wms-return-received.js、20260813100000-create-return-received-permissions.js" ], "module": "returnReceived" + }, + { + "version": "2026.08.13-shops-GetAuthorizeSessionKey-doc-sync", + "date": "2026-08-13", + "type": "updated", + "summary": "同步 shops.GetAuthorizeSessionKey 文档:实现已切换为调用授权服务 saveShop 换取授权会话,旧的 PDD/CAINIAO 预占码方案已下线。", + "methods": [ + "shops.GetAuthorizeSessionKey" + ], + "notes": [ + "实现:按店铺 platform_code 取 wms_print_platform.get_auth_platform_name 作为 platName,POST 授权服务 saveShop,携带 RedirectCodeUrl/shopName;京东平台附 VenderID,视频号平台改传 appId/toUserName 且不带 RedirectCodeUrl", + "成功后更新店铺 access_token=sessionKey、status=1,返回 data.message='获取授权成功';上游 code≠0 或未返回 sessionKey 时抛 500", + "文档更新:移除旧 data.session_key/authorize_url/state 返回结构与 501 未实现错误,补充 appId/toUserName 入参及 shop_id/callbackurl/platform_code 校验错误码", + "仅文档同步,不修改业务代码" + ], + "module": "shops" + }, + { + "version": "2026.08.13-interceptScan-non-intercept-guard", + "date": "2026-08-13", + "type": "updated", + "summary": "order.recheckOrder.interceptScan 增加非拦截订单前置校验:运单不存在或未发起系统拦截时直接拒绝并提示「非拦截订单」,移除原先自动创建运单补充记录的逻辑。", + "methods": [ + "order.recheckOrder.interceptScan" + ], + "notes": [ + "校验规则:运单记录不存在即拒绝;运单 is_intercept≠'Y' 时回查关联订单,intercept_status 不在 requested/intercepting 也拒绝,提示「非拦截订单」", + "校验通过后原逻辑不变:标记 is_back='Y'/is_intercept='Y'、处理未完结售后工单、订单级更新 intercepted_at_warehouse 并释放储位分配与订单锁", + "移除运单不存在时自动创建补充记录的分支(未发起拦截的运单不再被静默置为拦截)", + "同步更新 JSDoc 与 methods/system.json 文档,错误码新增 400 非拦截订单" + ], + "module": "order.recheckOrder" + }, + { + "version": "2026.08.13-returnUnpack", + "date": "2026-08-13", + "type": "added", + "summary": "新增退回拆包模块(returnUnpack):开拆包单、录明细、更新明细、移除明细、取消、提交确认、分页列表、明细列表、详情、删除十个接口。开单反查原运单判定原单退回并回填货主,未命中原单时按 warehouse_id+waybill_code 从退回查询记录反查货主;拆包单号 RP+YYYYMMDD+6位序号;状态机 unpacking/completed/cancelled;明细识别状态 none_recognized/partial_recognized/all_recognized;全接口仓库隔离(服务端注入 warehouse_id)。配套权限 540-549(作业类→仓库员工及以上,查询/删除类→客服员工及以上,detail 免权限复用列表权限)", + "methods": [ + "returnUnpack.create", + "returnUnpack.addDetail", + "returnUnpack.updateDetail", + "returnUnpack.removeDetail", + "returnUnpack.cancel", + "returnUnpack.submit", + "returnUnpack.list", + "returnUnpack.detailList", + "returnUnpack.detail", + "returnUnpack.delete" + ], + "notes": [ + "新增表 wms_return_unpack(主表)/ wms_return_unpack_detail(明细)/ wms_return_unpack_video(视频,paranoid 软删)/ wms_return_query_log(退回查询记录)", + "returnUnpack.create:waybill_code 必填;反查 wms_order_express.waybill_code 命中则回填 order_express_id/order_id/store_id 并返回原订单详情(复用 afterSale._resolveOrderDetail);未命中再从 wms_return_query_log 按 warehouse_id+waybill_code 反查货主(限最近 3 个月内登记);返回 id/record/is_original_return/store_remark/order", + "returnUnpack.addDetail:主单非终态校验;stock_id 有值 → 查 wms_stock_warehouse 校验货主归属(不一致 403)+ 回填 is_recognized=1 与快照;主表 store_id 为空时以首个识别商品回填货主;写明细后重算 total_items/total_quantity/detail_status", + "returnUnpack.updateDetail:白名单仅 quantity/remark;仅 quantity 变更时重算主表汇总", + "returnUnpack.removeDetail:明细表 paranoid:false 硬删除 + 重算主表汇总", + "returnUnpack.cancel:仅 unpacking 状态;事务内硬删主表+明细,软删视频", + "returnUnpack.submit:仅 unpacking;status=completed + 回写 end_time,并同步更新 wms_return_query_log.is_back=1(失败不阻断主流程)", + "returnUnpack.list:主表分页,仓库隔离服务端注入 warehouse_id;where 支持 unpack_no/waybill_code 模糊、unpack_date/start_time/end_time 范围、status/detail_status/unpacker_id/return_received_id/store_id/order_express_id/order_id 等值", + "returnUnpack.detailList:明细分页 + stockWarehouse 关联(命中时);where 支持 unpack_id/stock_id/barcode/is_recognized/product_status", + "returnUnpack.detail:主表 + details(stockWarehouse) + videos(camera) + returnReceived;原单退回时返回 related.order;免权限仅登录 + 仓库隔离", + "returnUnpack.delete:后台删除不限状态;事务物理删主表+明细,软删视频", + "仓库隔离:全部接口禁止前端传入 warehouse_id,由服务端注入 ctx.user.store_id;拆包单号规则 RP+YYYYMMDD+6位序号(仓库维度序号)", + "权限:540 returnUnpack.create、541 addDetail、542 updateDetail、543 removeDetail、544 cancel、545 submit(仓库员工及以上);546 list、547 detailList、548 detail、549 delete(客服员工及以上);detail 免权限(复用列表权限)", + "代码变更:app/model/return_unpack.js、return_unpack_detail.js、return_unpack_video.js、return_query_log.js;app/service/systems/return_unpack.js;app/service/systemMethods/returnUnpack.js;database/migrations/20260813120000-20260813120300 建表、20260813130000 权限" + ], + "module": "returnUnpack" + }, + { + "version": "2026.08.13-returnReceived.createResponse", + "date": "2026-08-13", + "type": "updated", + "summary": "returnReceived.create 出参结构调整:由平铺返回登记字段改为包装结构 { record, is_original_return, store_remark, duplicated },record 含登记记录完整字段与派生字段 is_original_return/store_remark,与代码实现(app/service/systems/return_received.js)及设计文档对齐", + "methods": [ + "returnReceived.create" + ], + "notes": [ + "原出参平铺 id/waybill_code/scan_date/scanner_id/scanner_name/order_express_id/order_id/store_id/remark/is_original_return/store_remark/duplicated,现改为四个顶层字段:record(object,必填)、is_original_return(boolean,必填)、store_remark(string,必填)、duplicated(boolean,必填)", + "record 内字段:id、waybill_code、scan_date、scanner_id、scanner_name、order_express_id、order_id、store_id、remark、created_at、updated_at(时间为格式化字符串)+ 派生字段 is_original_return、store_remark", + "顶层 is_original_return / store_remark / duplicated 为 record 之外独立返回字段,与 record 内同名字段取值一致", + "仅文档变更,代码实现已对齐(create 返回 { record, is_original_return, store_remark, duplicated },30日幂等命中与新建分支结构一致)" + ], + "module": "returnReceived" + }, + { + "version": "2026.08.13-returnWaybill", + "date": "2026-08-13", + "type": "added", + "summary": "新增运单退回登记模块(returnWaybill):复用 wms_return_query_log 表实现「货主 + 运单号」退回关系的增删查改五个接口(create/update/list/detail/delete)。create 校验货主合约并幂等返回已有记录;update 支持改运单号/货主/备注,改后冲突 409 拒绝;list 分页筛选(运单号模糊/货主/是否已通知/是否退回/登记时间范围);detail 免权限仅登录+仓库隔离;delete 物理删除。全接口仓库隔离(warehouse_id 服务端注入)。配套权限 551-555(作业类 create/update→仓库员工及以上,查询/删除类 list/detail/delete→客服员工及以上,detail 免权限复用列表权限)", + "methods": [ + "returnWaybill.create", + "returnWaybill.update", + "returnWaybill.list", + "returnWaybill.detail", + "returnWaybill.delete" + ], + "notes": [ + "复用表 wms_return_query_log(20260813120300 迁移已落地):warehouse_id/store_id/waybill_code/remark/is_notified/is_back/created_at/updated_at;登记接口不维护 is_notified/is_back(由定时任务与拆包联动维护)", + "returnWaybill.create:waybill_code/store_id 必填;货主合约校验(wms_store_warehouse 存在 store_id+warehouse_id,无合约 400 拒绝);同仓库+货主+运单号已存在时幂等返回已有记录 duplicated=true;写入 is_notified=0/is_back=0", + "returnWaybill.update:id 必填;仓库隔离校验;waybill_code/store_id/remark 可选更新;store_id 变更时校验新货主合约;改后与另一条同仓库+货主+运单号冲突则 409 拒绝", + "returnWaybill.list:pagination(pageSize 上限 500 默认 20)+ where(waybill_code 模糊、store_id、is_notified、is_back、created_at 起止)+ sort(id/created_at/updated_at/waybill_code,默认 created_at desc)", + "returnWaybill.detail:免权限(复用列表权限),仅登录 + 仓库隔离校验", + "returnWaybill.delete:物理删除(表 paranoid:false),返回被删除记录 id", + "仓库隔离:所有接口 warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入", + "权限:551 create、552 update(仓库员工及以上);553 list、554 detail、555 delete(客服员工及以上);detail 免权限复用 list 权限", + "代码变更:app/service/systems/return_waybill.js、app/service/systemMethods/returnWaybill.js、database/migrations/20260813160000-create-return-waybill-permissions.js" + ], + "module": "returnWaybill" + }, + { + "version": "2026.08.13-returnUnpack.detailAuth", + "date": "2026-08-13", + "type": "updated", + "summary": "returnUnpack.detail 鉴权配置变更:不再免权限(原 _noNeedRight='detail'),改为走 API 权限校验(固定权限 ID 548,客服员工及以上),与 app/service/systemMethods/returnUnpack.js 实现对齐。", + "methods": [ + "returnUnpack.detail" + ], + "notes": [ + "isNeedAuth:false → true;description 同步说明「需 548 权限(客服员工及以上)」", + "代码对齐:returnUnpack.js _noNeedRight 改为空字符串,detail 与其他接口一致走 API 权限校验", + "权限 548 为客服员工及以上(与原「查询类→客服员工及以上」设计一致)", + "仅文档同步,其余接口与模块不动" + ], + "module": "returnUnpack" } ] diff --git a/methods/system.json b/methods/system.json index 55b7389..36faa19 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,7 +1,7 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.22", + "version": "0.3.27", "updatedAt": "2026-08-13", "headers": [ { @@ -5990,7 +5990,7 @@ }, { "method": "order.recheckOrder.interceptScan", - "description": "拦截扫描:通过运单号查找运单记录,标记退回与拦截(is_back='Y', is_intercept='Y')。运单记录不存在时自动创建补充。处理关联的未完结售后工单(写入「库内拦截成功」步骤并置为 completed)。同步更新订单拦截状态为 intercepted_at_warehouse 并释放储位分配与订单锁(与 confirmIntercept 一致,订单级拦截覆盖所有面单含子面单)。工单处理失败不阻断主流程。", + "description": "拦截扫描:通过运单号查找运单记录。非拦截订单会被拒绝并提示「非拦截订单」:运单记录不存在,或运单 is_intercept≠'Y' 且关联订单 intercept_status 不在 requested/intercepting。校验通过后标记退回与拦截(is_back='Y', is_intercept='Y'),处理关联的未完结售后工单(写入「库内拦截成功」步骤并置为 completed)。若运单关联到订单,则将订单拦截状态更新为 intercepted_at_warehouse(step=4、outbound_status=fin)并释放储位分配与订单锁(仅订单级状态更新,不标记订单下其他面单)。工单处理失败不阻断主流程。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -6046,6 +6046,10 @@ { "code": 400, "message": "运单号不能为空" + }, + { + "code": 400, + "message": "非拦截订单" } ] }, @@ -19494,7 +19498,7 @@ "list": [ { "method": "storage.receiving.getReceivingList", - "description": "查询收货单列表,支持分页和多条件筛选。支持 filterDepleted 参数过滤掉无可再用量的收货单(所有明细已被其他入库单 committed 绑定占满)。支持 entry_order_id 参数按入库单商品交集过滤。", + "description": "查询收货单列表,支持分页和多条件筛选。支持 filterDepleted 参数过滤掉无可再用量的收货单(所有明细已被其他入库单 committed 绑定占满)。支持 entry_order_id 参数按入库单商品交集过滤。支持 stock_query_where 参数按商品条码/编码/ID 过滤。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -19533,6 +19537,13 @@ "required": false, "source": "body", "description": "按入库单商品交集过滤。传入入库单 ID 后,只返回至少有一条收货明细的 system_product_id 在入库单明细中存在的收货单。与 filterDepleted 可组合使用。不传则不过滤。" + }, + { + "name": "stock_query_where", + "type": "string|string[]", + "required": false, + "source": "body", + "description": "按商品维度过滤。传入字符串或字符串数组后搜索商品条码(wms_stock_barcodes.barcode)、商品编码(wms_stock_warehouse.item_code)与商品ID(wms_stock_warehouse.id,纯数字时精确匹配),再经 wms_receiving_detail.system_product_id 关联,返回明细中含匹配商品的收货单;多个关键字取并集。与 filterDepleted、entry_order_id 可组合使用(组合时取交集)。不传则不过滤。" } ], "response": [ @@ -19596,6 +19607,13 @@ "required": false, "source": "body", "description": "排序参数,支持 sortField/sortOrder" + }, + { + "name": "stock_query_where", + "type": "string|string[]", + "required": false, + "source": "body", + "description": "按商品维度过滤。传入字符串或字符串数组后搜索商品条码(wms_stock_barcodes.barcode)、商品编码(wms_stock_warehouse.item_code)与商品ID(wms_stock_warehouse.id,纯数字时精确匹配),再经 wms_receiving_detail.system_product_id 关联,返回明细中含匹配商品的收货单;多个关键字取并集。不传则不过滤。" } ], "response": [ @@ -27627,7 +27645,7 @@ }, { "method": "shops.GetAuthorizeSessionKey", - "description": "按店铺所属平台生成授权会话。入参兼容 id/shop_id/shopId 与 callbackurl/callback_url,callbackurl 必填。对已实现的平台(PDD/CAINIAO)返回 session_key/authorize_url/state,其他平台返回 501 未实现。", + "description": "按店铺所属平台向授权服务换取授权会话(saveShop)。入参兼容 id/shop_id/shopId 与 callbackurl/callback_url,callbackurl 必填;视频号平台还需 appId 与 toUserName(此时不带 RedirectCodeUrl),京东平台附带 VenderID。成功后更新店铺 access_token 与 status=1,返回 data.message='获取授权成功'。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ @@ -27651,7 +27669,21 @@ "type": "string", "required": true, "source": "body", - "description": "回调地址,兼容 callback_url" + "description": "授权回调地址,兼容 callback_url,最长 500 字符" + }, + { + "name": "appId", + "type": "string", + "required": false, + "source": "body", + "description": "视频号平台必填:授权服务应用 ID" + }, + { + "name": "toUserName", + "type": "string", + "required": false, + "source": "body", + "description": "视频号平台必填:授权服务用户名" } ], "response": [ @@ -27674,47 +27706,29 @@ "description": "提示信息" }, { - "name": "data.shop_id", - "type": "number", - "required": true, - "description": "店铺 ID" - }, - { - "name": "data.platform_code", + "name": "data.message", "type": "string", "required": true, - "description": "平台编码(大写)" - }, - { - "name": "data.callbackurl", - "type": "string", - "required": true, - "description": "回调地址" - }, - { - "name": "data.session_key", - "type": "string", - "required": true, - "description": "授权预占码(session)" - }, - { - "name": "data.authorize_url", - "type": "string", - "required": true, - "description": "平台授权跳转地址(含 state)" - }, - { - "name": "data.state", - "type": "string", - "required": true, - "description": "内部 state 值(platform + '_' + authRandomCode),用于回调解析" + "description": "成功时固定返回「获取授权成功」" } ], "errors": [ + { + "code": 400, + "message": "shop_id 不能为空" + }, + { + "code": 400, + "message": "shop_id 参数不合法" + }, { "code": 400, "message": "callbackurl 不能为空" }, + { + "code": 400, + "message": "callbackurl 长度不能超过 500" + }, { "code": 400, "message": "未识别到当前仓库" @@ -27725,15 +27739,23 @@ }, { "code": 400, - "message": "平台授权基础地址未配置" + "message": "platform_code 不能为空" }, { - "code": 501, - "message": "平台 %s 暂未实现授权会话换取能力" + "code": 400, + "message": "platform_code 未匹配到打印平台编码" + }, + { + "code": 400, + "message": "视频号授权需要提供 appId 和 toUserName" }, { "code": 500, - "message": "生成唯一授权码失败,请稍后重试" + "message": "获取授权失败,未返回 sessionKey" + }, + { + "code": 500, + "message": "获取授权失败:接口请求异常(上游返回非 0 时携带上游 msg)" } ] } @@ -34769,58 +34791,10 @@ ], "response": [ { - "name": "id", - "type": "integer", + "name": "record", + "type": "object", "required": true, - "description": "登记记录主键ID" - }, - { - "name": "waybill_code", - "type": "string", - "required": true, - "description": "退回收件运单号" - }, - { - "name": "scan_date", - "type": "string", - "required": true, - "description": "扫描收到日期" - }, - { - "name": "scanner_id", - "type": "integer", - "required": true, - "description": "扫描人员工号ID" - }, - { - "name": "scanner_name", - "type": "string", - "required": true, - "description": "扫描人员工号名称" - }, - { - "name": "order_express_id", - "type": "integer", - "required": false, - "description": "原运单ID(原单退回时回填,否则为 null)" - }, - { - "name": "order_id", - "type": "integer", - "required": false, - "description": "原订单ID(原单退回时回填,否则为 null)" - }, - { - "name": "store_id", - "type": "integer", - "required": false, - "description": "货主ID(原单退回时回填,否则为 null)" - }, - { - "name": "remark", - "type": "string", - "required": false, - "description": "备注" + "description": "登记记录包装对象,含登记记录完整字段(id、waybill_code、scan_date、scanner_id、scanner_name、order_express_id、order_id、store_id、remark、created_at、updated_at 等,时间字段为格式化字符串)及派生字段 is_original_return、store_remark" }, { "name": "is_original_return", @@ -35050,6 +35024,1216 @@ ] } ] + }, + { + "groupName": "退回拆包模块", + "module": "returnUnpack", + "list": [ + { + "method": "returnUnpack.create", + "description": "开拆包单(明细不在此提交,由 returnUnpack.addDetail 逐件录入)。用 waybill_code 反查 wms_order_express 判定是否原单退回,命中则回填 order_express_id/order_id/store_id 并返回原订单详情;未命中原单时按 warehouse_id+waybill_code 从 wms_return_query_log 反查货主(限最近 3 个月内登记)。拆包单号规则 RP+YYYYMMDD+6位序号。仓库隔离:warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "waybill_code", + "type": "string", + "required": true, + "source": "body", + "description": "拆包的运单号(退回包裹运单号,必填,用于反查原单/货主信息)" + }, + { + "name": "camera_ids", + "type": "array", + "required": false, + "source": "body", + "description": "摄像头ID列表,如 [1,2,3],关联 wms_camera.id(非正整数会被过滤)" + }, + { + "name": "return_received_id", + "type": "integer", + "required": false, + "source": "body", + "description": "关联退回收到单ID(wms_return_received.id),非必填,允许独立拆包" + }, + { + "name": "remark", + "type": "string", + "required": false, + "source": "body", + "description": "备注(最长 500 字符,超出截断)" + } + ], + "response": [ + { + "name": "id", + "type": "integer", + "required": true, + "description": "拆包单主键ID(后续明细收录的依据,传给 returnUnpack.addDetail)" + }, + { + "name": "record", + "type": "object", + "required": true, + "description": "拆包单主表记录(含 unpack_no、waybill_code、unpack_date、start_time、unpacker_id/unpacker_name、status、detail_status、camera_ids 数组、回填的 order_express_id/order_id/store_id 及 is_original_return 派生字段)" + }, + { + "name": "is_original_return", + "type": "boolean", + "required": true, + "description": "是否原单退回(反查 wms_order_express.waybill_code 命中为 true)" + }, + { + "name": "store_remark", + "type": "string", + "required": true, + "description": "货主的合约货主备注名称(wms_store_warehouse.store_remask),未命中时为空字符串" + }, + { + "name": "order", + "type": "object", + "required": false, + "description": "原订单详情(含 items 明细,仅原单退回时返回,非原单为 null)" + } + ], + "errors": [ + { + "code": "400", + "message": "waybill_code 不能为空" + }, + { + "code": "400", + "message": "缺少仓库上下文" + }, + { + "code": "400", + "message": "缺少拆包人员工号上下文" + }, + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该接口" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "returnUnpack.addDetail", + "description": "录明细:以拆包单ID为依据录入一条明细。主单非终态(unpacking)校验;stock_id 有值时校验货主归属并回填识别快照(is_recognized=1 + item_code/item_name/spec/product_snapshot),为空即无关联货物(is_recognized=0);主表 store_id 为空时以首个识别商品回填主表货主。写明细后重算主表 total_items/total_quantity/detail_status。仓库隔离校验(仅本仓库拆包单)。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "id", + "type": "integer", + "required": true, + "source": "body", + "description": "拆包单ID(returnUnpack.create 返回的依据)" + }, + { + "name": "stock_id", + "type": "integer", + "required": false, + "source": "body", + "description": "系统商品ID(wms_stock_warehouse.id),为空即无关联货物" + }, + { + "name": "quantity", + "type": "integer", + "required": false, + "source": "body", + "description": "数量,默认 1(小于 1 按 1 处理)" + }, + { + "name": "product_status", + "type": "string", + "required": false, + "source": "body", + "description": "产品状态:normal 正常(默认)/ damaged 破损" + }, + { + "name": "remark", + "type": "string", + "required": false, + "source": "body", + "description": "备注(最长 500 字符,超出截断)" + } + ], + "response": [ + { + "name": "detail_id", + "type": "integer", + "required": true, + "description": "新增明细ID(供 returnUnpack.updateDetail / returnUnpack.removeDetail 使用)" + }, + { + "name": "detail", + "type": "object", + "required": true, + "description": "新增的明细行(含 is_recognized/item_code/item_name/spec/product_snapshot 等识别结果快照)" + }, + { + "name": "total_items", + "type": "integer", + "required": true, + "description": "主表最新物品种类数(明细行数)" + }, + { + "name": "total_quantity", + "type": "integer", + "required": true, + "description": "主表最新物品总数量(明细数量合计)" + }, + { + "name": "detail_status", + "type": "string", + "required": true, + "description": "主表最新明细识别状态:none_recognized 全未识别 / partial_recognized 部分识别 / all_recognized 全部识别" + } + ], + "errors": [ + { + "code": "400", + "message": "id 必填且必须为正整数" + }, + { + "code": "400", + "message": "拆包单已提交或已取消,不可操作" + }, + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "该商品不属于当前货主,无法录入" + }, + { + "code": "403", + "message": "无权访问该拆包单" + }, + { + "code": "403", + "message": "无权访问该接口" + }, + { + "code": "404", + "message": "拆包单不存在" + }, + { + "code": "404", + "message": "系统商品不存在" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "returnUnpack.updateDetail", + "description": "更新明细:仅允许更新 quantity/remark(更新范围白名单,暂限这两个字段)。校验拆包单存在且非终态(unpacking)、明细属于该拆包单;仅 quantity 变更时重算主表 total_quantity(total_items/detail_status 不变)。仓库隔离校验(仅本仓库拆包单)。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "id", + "type": "integer", + "required": true, + "source": "body", + "description": "拆包单ID" + }, + { + "name": "detail_id", + "type": "integer", + "required": true, + "source": "body", + "description": "明细ID(returnUnpack.addDetail 返回)" + }, + { + "name": "quantity", + "type": "integer", + "required": false, + "source": "body", + "description": "数量(小于 1 按 1 处理,变更时才触发主表重算)" + }, + { + "name": "remark", + "type": "string", + "required": false, + "source": "body", + "description": "备注(最长 500 字符,超出截断)" + } + ], + "response": [ + { + "name": "detail", + "type": "object", + "required": true, + "description": "更新后的明细行" + }, + { + "name": "total_items", + "type": "integer", + "required": true, + "description": "主表最新物品种类数" + }, + { + "name": "total_quantity", + "type": "integer", + "required": true, + "description": "主表最新物品总数量(quantity 变更时重算)" + }, + { + "name": "detail_status", + "type": "string", + "required": true, + "description": "主表最新明细识别状态:none_recognized/partial_recognized/all_recognized" + } + ], + "errors": [ + { + "code": "400", + "message": "id 必填且必须为正整数" + }, + { + "code": "400", + "message": "detail_id 必填且必须为正整数" + }, + { + "code": "400", + "message": "拆包单已提交或已取消,不可操作" + }, + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该拆包单" + }, + { + "code": "403", + "message": "无权访问该接口" + }, + { + "code": "404", + "message": "拆包单不存在" + }, + { + "code": "404", + "message": "明细不存在或不属于该拆包单" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "returnUnpack.removeDetail", + "description": "移除明细:删除拆包单下的一条明细(明细表 paranoid:false,硬删除/物理删除),并重算主表 total_items/total_quantity/detail_status。校验拆包单存在且非终态(unpacking)、明细属于该拆包单。仓库隔离校验(仅本仓库拆包单)。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "id", + "type": "integer", + "required": true, + "source": "body", + "description": "拆包单ID" + }, + { + "name": "detail_id", + "type": "integer", + "required": true, + "source": "body", + "description": "明细ID(returnUnpack.addDetail 返回)" + } + ], + "response": [ + { + "name": "removed_detail_id", + "type": "integer", + "required": true, + "description": "被移除明细ID" + }, + { + "name": "total_items", + "type": "integer", + "required": true, + "description": "主表最新物品种类数" + }, + { + "name": "total_quantity", + "type": "integer", + "required": true, + "description": "主表最新物品总数量" + }, + { + "name": "detail_status", + "type": "string", + "required": true, + "description": "主表最新明细识别状态:none_recognized/partial_recognized/all_recognized" + } + ], + "errors": [ + { + "code": "400", + "message": "id 必填且必须为正整数" + }, + { + "code": "400", + "message": "detail_id 必填且必须为正整数" + }, + { + "code": "400", + "message": "拆包单已提交或已取消,不可操作" + }, + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该拆包单" + }, + { + "code": "403", + "message": "无权访问该接口" + }, + { + "code": "404", + "message": "拆包单不存在" + }, + { + "code": "404", + "message": "明细不存在或不属于该拆包单" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "returnUnpack.cancel", + "description": "取消拆包单:仅在未完成(unpacking)状态可取消,事务内硬删除主表 + 该单所有明细,并同步软删视频副表记录。与 returnUnpack.delete 区别:cancel 仅供未完成状态作业取消;delete 为后台管理删除,不限制状态。仓库隔离校验(仅本仓库拆包单)。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "id", + "type": "integer", + "required": true, + "source": "body", + "description": "拆包单ID" + } + ], + "response": [ + { + "name": "id", + "type": "integer", + "required": true, + "description": "被取消拆包单ID" + } + ], + "errors": [ + { + "code": "400", + "message": "id 必填且必须为正整数" + }, + { + "code": "400", + "message": "拆包单已提交或已取消,不可操作" + }, + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该拆包单" + }, + { + "code": "403", + "message": "无权访问该接口" + }, + { + "code": "404", + "message": "拆包单不存在" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "returnUnpack.submit", + "description": "提交确认:未完成(unpacking)拆包单转 completed 终态并回写 end_time(拆包结束时间);同步按 warehouse_id+waybill_code 更新 wms_return_query_log.is_back=1(标记该运单号已退回,更新失败不阻断主流程)。提交后进入终态,不可再录/移除明细。仓库隔离校验(仅本仓库拆包单)。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "id", + "type": "integer", + "required": true, + "source": "body", + "description": "拆包单ID" + } + ], + "response": [ + { + "name": "record", + "type": "object", + "required": true, + "description": "更新后的主表记录(含 status=completed、end_time 及格式化时间字段)" + } + ], + "errors": [ + { + "code": "400", + "message": "id 必填且必须为正整数" + }, + { + "code": "400", + "message": "拆包单已提交或已取消,不可操作" + }, + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该拆包单" + }, + { + "code": "403", + "message": "无权访问该接口" + }, + { + "code": "404", + "message": "拆包单不存在" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "returnUnpack.list", + "description": "拆包单分页列表(主表)。仓库隔离:warehouse_id 由服务端自动注入 ctx.user.store_id,禁止前端传入。支持拆包单号/运单号模糊、日期/时间范围、状态、拆包人员、退回收到单、货主、原运单/原订单等筛选。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页 { page: 1, pageSize: 20 }(pageSize 上限 500,默认 20)" + }, + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "筛选条件对象,所有字段均可选" + }, + { + "name": "where.unpack_no", + "type": "string", + "required": false, + "source": "body.where", + "description": "拆包单号(模糊搜索,传 {operator:'like',value} 或直接值)" + }, + { + "name": "where.waybill_code", + "type": "string", + "required": false, + "source": "body.where", + "description": "运单号(模糊搜索,传 {operator:'like',value} 或直接值)" + }, + { + "name": "where.unpack_date", + "type": "object", + "required": false, + "source": "body.where", + "description": "拆包日期范围 { operator:'between'|'gte'|'lte'|'gt'|'lt', value:[start,end] 或单值 }" + }, + { + "name": "where.start_time", + "type": "object", + "required": false, + "source": "body.where", + "description": "拆包开始时间范围 { operator:'between'|'gte'|'lte'|'gt'|'lt', value:[start,end] 或单值 }" + }, + { + "name": "where.end_time", + "type": "object", + "required": false, + "source": "body.where", + "description": "拆包结束时间范围 { operator:'between'|'gte'|'lte'|'gt'|'lt', value:[start,end] 或单值 }" + }, + { + "name": "where.status", + "type": "string", + "required": false, + "source": "body.where", + "description": "拆包状态(等值):unpacking 拆包中 / completed 完成 / cancelled 作废" + }, + { + "name": "where.detail_status", + "type": "string", + "required": false, + "source": "body.where", + "description": "明细识别状态(等值):none_recognized / partial_recognized / all_recognized" + }, + { + "name": "where.unpacker_id", + "type": "number", + "required": false, + "source": "body.where", + "description": "拆包人员工号ID(等值)" + }, + { + "name": "where.return_received_id", + "type": "number", + "required": false, + "source": "body.where", + "description": "关联退回收到单ID(等值)" + }, + { + "name": "where.store_id", + "type": "number", + "required": false, + "source": "body.where", + "description": "货主ID(等值)" + }, + { + "name": "where.order_express_id", + "type": "number", + "required": false, + "source": "body.where", + "description": "原运单ID(等值)" + }, + { + "name": "where.order_id", + "type": "number", + "required": false, + "source": "body.where", + "description": "原订单ID(等值)" + }, + { + "name": "sort", + "type": "object", + "required": false, + "source": "body", + "description": "排序 { sortField: 'id'|'created_at'|'updated_at'|'unpack_date'|'start_time'|'end_time'|'unpack_no'|'waybill_code', sortOrder: 'asc'|'desc' },默认 created_at desc" + } + ], + "response": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "拆包单列表,每条含主表字段 + is_original_return 派生字段 + 格式化时间字段 + camera_ids 数组" + }, + { + "name": "pagination", + "type": "object", + "required": true, + "description": "分页信息 { page, pageSize, total, totalPages, hasPrevious, hasNext }" + } + ], + "errors": [ + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该接口" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "returnUnpack.detailList", + "description": "拆包明细分页列表,命中识别商品时含 stockWarehouse 关联。仓库隔离:warehouse_id 由服务端自动注入 ctx.user.store_id,禁止前端传入。支持按拆包单ID、系统商品、条码、识别标记、产品状态筛选。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页 { page: 1, pageSize: 20 }(pageSize 上限 500,默认 20)" + }, + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "筛选条件对象,所有字段均可选" + }, + { + "name": "where.unpack_id", + "type": "number", + "required": false, + "source": "body.where", + "description": "拆包单ID(等值)" + }, + { + "name": "where.stock_id", + "type": "number", + "required": false, + "source": "body.where", + "description": "系统商品ID(wms_stock_warehouse.id,等值)" + }, + { + "name": "where.barcode", + "type": "string", + "required": false, + "source": "body.where", + "description": "扫描条码(模糊搜索,传 {operator:'like',value} 或直接值)" + }, + { + "name": "where.is_recognized", + "type": "number", + "required": false, + "source": "body.where", + "description": "是否识别(等值):1 识别到系统商品 / 0 非识别物品" + }, + { + "name": "where.product_status", + "type": "string", + "required": false, + "source": "body.where", + "description": "产品状态(等值):normal 正常 / damaged 破损" + }, + { + "name": "sort", + "type": "object", + "required": false, + "source": "body", + "description": "排序 { sortField: 'id'|'created_at'|'updated_at'|'quantity', sortOrder: 'asc'|'desc' },默认 created_at desc" + } + ], + "response": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "明细行列表(含 is_recognized/item_code/item_name/spec/product_snapshot,识别命中时含 stockWarehouse 关联)" + }, + { + "name": "pagination", + "type": "object", + "required": true, + "description": "分页信息 { page, pageSize, total, totalPages, hasPrevious, hasNext }" + } + ], + "errors": [ + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该接口" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "returnUnpack.detail", + "description": "拆包单详情:主表 + 明细(含 stockWarehouse 关联,命中时)+ 视频副表(含 camera 关联,命中时)+ 退回收到单(命中时);原单退回时(order_id 有值)返回 related.order 原订单详情。需 548 权限(客服员工及以上),仓库隔离校验(仅本仓库拆包单)。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "id", + "type": "integer", + "required": true, + "source": "body", + "description": "拆包单ID" + } + ], + "response": [ + { + "name": "record", + "type": "object", + "required": true, + "description": "主表完整记录(含 details 明细、videos 视频、returnReceived 退回收到单关联与格式化时间字段)" + }, + { + "name": "related", + "type": "object", + "required": true, + "description": "关联信息对象" + }, + { + "name": "related.order", + "type": "object", + "required": false, + "description": "原订单详情(含 items 明细,仅原单退回时返回,非原单为 null)" + } + ], + "errors": [ + { + "code": "400", + "message": "id 必填且必须为正整数" + }, + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该拆包单" + }, + { + "code": "404", + "message": "拆包单不存在" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "returnUnpack.delete", + "description": "删除拆包单(后台管理,不限制状态):事务内物理删除主表 + 所有明细,并同步软删视频副表记录。作业层未完成状态取消请走 returnUnpack.cancel。仓库隔离校验(仅本仓库拆包单)。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "id", + "type": "integer", + "required": true, + "source": "body", + "description": "拆包单ID" + } + ], + "response": [ + { + "name": "id", + "type": "integer", + "required": true, + "description": "被删除拆包单ID" + } + ], + "errors": [ + { + "code": "400", + "message": "id 必填且必须为正整数" + }, + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该拆包单" + }, + { + "code": "403", + "message": "无权访问该接口" + }, + { + "code": "404", + "message": "拆包单不存在" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + } + ] + }, + { + "groupName": "运单退回登记模块", + "module": "returnWaybill", + "list": [ + { + "method": "returnWaybill.create", + "description": "运单退回登记(增):录入「货主 + 运单号」退回关系。waybill_code/store_id 必填;校验 wms_store_warehouse 存在 store_id + warehouse_id 货主合约,无合约拒绝写入;同仓库+货主+运单号已存在时幂等返回已有记录(duplicated=true,不重复插入)。写入 is_notified=0/is_back=0(由定时任务与拆包联动维护,登记接口不维护)。仓库隔离:warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "waybill_code", + "type": "string", + "required": true, + "source": "body", + "description": "运单号(登记入参,必填,trim 后不能为空)" + }, + { + "name": "store_id", + "type": "integer", + "required": true, + "source": "body", + "description": "货主ID(必填,正整数,需存在 wms_store_warehouse 中 store_id + warehouse_id 合约记录)" + }, + { + "name": "remark", + "type": "string", + "required": false, + "source": "body", + "description": "备注(可选,最长 500 字符,超出截断)" + } + ], + "response": [ + { + "name": "record", + "type": "object", + "required": true, + "description": "登记记录包装对象,含登记记录完整字段(id、warehouse_id、store_id、waybill_code、remark、is_notified、is_back、created_at、updated_at,时间字段为格式化字符串)" + }, + { + "name": "duplicated", + "type": "boolean", + "required": true, + "description": "是否命中已有记录:同仓库+货主+运单号已存在时为 true(返回已有记录,不重复插入),否则 false" + } + ], + "errors": [ + { + "code": "400", + "message": "waybill_code 不能为空" + }, + { + "code": "400", + "message": "store_id 必填且必须为正整数" + }, + { + "code": "400", + "message": "缺少仓库上下文" + }, + { + "code": "400", + "message": "货主在当前仓库无合约关系,无法登记" + }, + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该接口" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "returnWaybill.update", + "description": "修改登记(改):id 必填,可改 waybill_code/store_id/remark。校验记录存在且属于当前仓库;store_id 变更时重新校验新货主合约(wms_store_warehouse 存在 store_id + warehouse_id);改后与另一条同仓库+货主+运单号冲突则 409 拒绝(防重复登记)。仓库隔离校验(仅本仓库记录)。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "id", + "type": "integer", + "required": true, + "source": "body", + "description": "登记记录主键ID(必填,正整数)" + }, + { + "name": "waybill_code", + "type": "string", + "required": false, + "source": "body", + "description": "运单号(可选,改运单号,trim 后不能为空字符串)" + }, + { + "name": "store_id", + "type": "integer", + "required": false, + "source": "body", + "description": "货主ID(可选,改货主ID;变更时校验新货主在当前仓库的合约)" + }, + { + "name": "remark", + "type": "string", + "required": false, + "source": "body", + "description": "备注(可选,最长 500 字符,超出截断)" + } + ], + "response": [ + { + "name": "record", + "type": "object", + "required": true, + "description": "更新后的登记记录完整信息(含格式化时间字段)" + } + ], + "errors": [ + { + "code": "400", + "message": "id 必填且必须为正整数" + }, + { + "code": "400", + "message": "waybill_code 不能为空" + }, + { + "code": "400", + "message": "store_id 必填且必须为正整数" + }, + { + "code": "400", + "message": "货主在当前仓库无合约关系,无法登记" + }, + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该登记记录" + }, + { + "code": "403", + "message": "无权访问该接口" + }, + { + "code": "404", + "message": "登记记录不存在" + }, + { + "code": "409", + "message": "已存在相同货主 + 运单号的登记记录" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "returnWaybill.list", + "description": "运单退回登记分页列表。仓库隔离:warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入。支持按运单号模糊、货主、是否已通知、是否退回、登记时间范围筛选。is_notified/is_back 由定时任务与拆包联动维护,登记接口不维护。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "pagination", + "type": "object", + "required": false, + "source": "body", + "description": "分页 { page: 1, pageSize: 20 }(pageSize 上限 500,默认 20)" + }, + { + "name": "where", + "type": "object", + "required": false, + "source": "body", + "description": "筛选条件对象,所有字段均可选" + }, + { + "name": "where.waybill_code", + "type": "string", + "required": false, + "source": "body.where", + "description": "运单号(模糊搜索,传 {operator:'like',value} 或直接值)" + }, + { + "name": "where.store_id", + "type": "number", + "required": false, + "source": "body.where", + "description": "货主ID(等值)" + }, + { + "name": "where.is_notified", + "type": "number", + "required": false, + "source": "body.where", + "description": "是否已通知(等值):1 已通知 / 0 未通知(由定时任务维护,登记接口不写入)" + }, + { + "name": "where.is_back", + "type": "number", + "required": false, + "source": "body.where", + "description": "是否退回(等值):1 已退回 / 0 未退回(由拆包单提交联动维护,登记接口不写入)" + }, + { + "name": "where.created_at", + "type": "object", + "required": false, + "source": "body.where", + "description": "登记日期范围 { operator:'between'|'gte'|'lte'|'gt'|'lt', value:[start,end] 或单值 }" + }, + { + "name": "sort", + "type": "object", + "required": false, + "source": "body", + "description": "排序 { sortField: 'id'|'created_at'|'updated_at'|'waybill_code', sortOrder: 'asc'|'desc' },默认 created_at desc" + } + ], + "response": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "运单退回登记列表,每条含登记字段(id、warehouse_id、store_id、waybill_code、remark、is_notified、is_back)及格式化时间字段" + }, + { + "name": "pagination", + "type": "object", + "required": true, + "description": "分页信息 { page, pageSize, total, totalPages, hasPrevious, hasNext }" + } + ], + "errors": [ + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该接口" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "returnWaybill.detail", + "description": "运单退回登记详情。免权限(复用列表权限),仅需登录 + 仓库隔离校验(仅本仓库记录)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "id", + "type": "integer", + "required": true, + "source": "body", + "description": "登记记录主键ID(必填,正整数)" + } + ], + "response": [ + { + "name": "record", + "type": "object", + "required": true, + "description": "登记记录完整信息(id、warehouse_id、store_id、waybill_code、remark、is_notified、is_back 及格式化时间字段)" + } + ], + "errors": [ + { + "code": "400", + "message": "id 必填且必须为正整数" + }, + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该登记记录" + }, + { + "code": "404", + "message": "登记记录不存在" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + }, + { + "method": "returnWaybill.delete", + "description": "删除运单退回登记(物理删除,表 paranoid:false)。仓库隔离校验(仅本仓库记录)。", + "isNeedAuth": true, + "isNeedLogin": true, + "headers": [], + "params": [ + { + "name": "id", + "type": "integer", + "required": true, + "source": "body", + "description": "登记记录主键ID(必填,正整数)" + } + ], + "response": [ + { + "name": "id", + "type": "integer", + "required": true, + "description": "被删除登记记录ID" + } + ], + "errors": [ + { + "code": "400", + "message": "id 必填且必须为正整数" + }, + { + "code": "401", + "message": "未提供有效的认证令牌" + }, + { + "code": "403", + "message": "无权访问该登记记录" + }, + { + "code": "403", + "message": "无权访问该接口" + }, + { + "code": "404", + "message": "登记记录不存在" + }, + { + "code": "500", + "message": "服务器内部错误" + } + ] + } + ] } ] }