'use strict'; /** * Swagger 契约(数据结构)定义。 * 在 Controller 注释中通过 `@Request` / `@Response` 引用这里的 key。 * * 插件约定(egg-swagger-doc): * 1. 每个字段必须声明 type,可选值:string / number / boolean / integer / array / file * 2. type 非上述基础类型时,会被解析为契约引用 `$ref: #/definitions/{type}` * 3. type 为 array 时必须声明 itemType,itemType 可为基础类型或其他契约名 * 4. 字段加 required: true 表示必填 */ /** 通用响应:data 为任意业务数据 */ const baseResponse = { code: { type: 'integer', description: '业务状态码,0 成功,非 0 失败' }, message: { type: 'string', description: '提示信息' }, data: { type: 'string', description: '业务数据(JSON)' }, }; /** * 分页数据结构契约 * @param {String} itemContract 列表项契约名,如 userItem * @param {String} listDesc 列表描述 * @return {Object} 分页契约 */ const buildPage = (itemContract, listDesc) => ({ page: { type: 'integer', description: '当前页码' }, pageSize: { type: 'integer', description: '每页条数' }, total: { type: 'integer', description: '总条数' }, list: { type: 'array', itemType: itemContract, description: listDesc }, }); /** * 列表响应契约(data 引用对应的分页契约) * @param {String} pageContract 分页契约名,如 userPage * @return {Object} 列表响应契约 */ const buildListResponse = pageContract => ({ code: { type: 'integer', description: '业务状态码,0 成功' }, message: { type: 'string', description: '提示信息' }, data: { type: pageContract, description: '分页数据:page / pageSize / total / list' }, }); module.exports = { baseResponse, // ---------- 登录鉴权 ---------- loginRequest: { account: { type: 'string', required: true, description: '登录账号或邮箱' }, password: { type: 'string', required: true, description: '登录密码(明文,HTTPS 传输)' }, }, sendEmailCodeRequest: { email: { type: 'string', required: true, description: '接收验证码的邮箱,需未在系统中注册' }, }, registerRequest: { username: { type: 'string', required: true, description: '登录账号,全局唯一' }, password: { type: 'string', required: true, description: '登录密码(明文,不少于 6 位),服务端生成盐并加盐哈希存储' }, email: { type: 'string', required: true, description: '邮箱,全局唯一,需通过邮箱验证码认证' }, code: { type: 'string', required: true, description: '邮箱收到的 6 位验证码,10 分钟内有效' }, nickname: { type: 'string', description: '昵称,不传则默认与账号相同' }, phone: { type: 'string', description: '手机号' }, }, loginData: { token: { type: 'string', description: 'JWT 令牌,载荷仅含 user_id' }, user_id: { type: 'integer', description: '用户ID' }, expires_in: { type: 'integer', description: '有效秒数,如 7200' }, }, loginResponse: { code: { type: 'integer', description: '业务状态码,0 成功' }, message: { type: 'string', description: '提示信息' }, data: { type: 'loginData', description: '登录结果' }, }, // ---------- 用户 users ---------- userItem: { id: { type: 'integer', description: '主键' }, username: { type: 'string', description: '登录账号' }, nickname: { type: 'string', description: '昵称' }, avatar: { type: 'string', description: '头像' }, email: { type: 'string', description: '邮箱' }, phone: { type: 'string', description: '手机号' }, status: { type: 'integer', description: '状态:1启用 0禁用' }, last_login_at: { type: 'string', description: '最后登录时间' }, created_at: { type: 'string', description: '创建时间' }, updated_at: { type: 'string', description: '更新时间' }, }, userPage: buildPage('userItem', '用户列表'), userListResponse: buildListResponse('userPage'), createUserRequest: { username: { type: 'string', required: true, description: '登录账号,唯一' }, password: { type: 'string', required: true, description: '登录密码(明文传入,服务端生成盐并加盐哈希存储)' }, nickname: { type: 'string', description: '昵称' }, avatar: { type: 'string', description: '头像URL' }, email: { type: 'string', description: '邮箱' }, phone: { type: 'string', description: '手机号' }, status: { type: 'integer', description: '状态:1启用 0禁用,默认1' }, }, updateUserRequest: { nickname: { type: 'string', description: '昵称' }, avatar: { type: 'string', description: '头像URL' }, email: { type: 'string', description: '邮箱' }, phone: { type: 'string', description: '手机号' }, status: { type: 'integer', description: '状态:1启用 0禁用' }, }, resetPasswordRequest: { password: { type: 'string', required: true, description: '新密码(明文),服务端重新生成盐值并加盐哈希' }, }, // ---------- 主体 principals ---------- principalItem: { id: { type: 'integer', description: '主键' }, code: { type: 'string', description: '主体编码,唯一' }, name: { type: 'string', description: '主体名称' }, type: { type: 'integer', description: '主体类型:1自营 2加盟 3外部' }, contact_name: { type: 'string', description: '联系人' }, contact_phone: { type: 'string', description: '联系电话' }, status: { type: 'integer', description: '状态:1启用 0禁用' }, remark: { type: 'string', description: '备注' }, created_at: { type: 'string', description: '创建时间' }, updated_at: { type: 'string', description: '更新时间' }, }, principalPage: buildPage('principalItem', '主体列表'), principalListResponse: buildListResponse('principalPage'), createPrincipalRequest: { code: { type: 'string', required: true, description: '主体编码,唯一' }, name: { type: 'string', required: true, description: '主体名称' }, type: { type: 'integer', description: '主体类型:1自营 2加盟 3外部,默认1' }, contact_name: { type: 'string', description: '联系人' }, contact_phone: { type: 'string', description: '联系电话' }, status: { type: 'integer', description: '状态:1启用 0禁用,默认1' }, remark: { type: 'string', description: '备注' }, }, updatePrincipalRequest: { name: { type: 'string', description: '主体名称' }, type: { type: 'integer', description: '主体类型:1自营 2加盟 3外部' }, contact_name: { type: 'string', description: '联系人' }, contact_phone: { type: 'string', description: '联系电话' }, status: { type: 'integer', description: '状态:1启用 0禁用' }, remark: { type: 'string', description: '备注' }, }, // ---------- 主体用户关联 principal_users ---------- principalUserItem: { id: { type: 'integer', description: '主键' }, principal_id: { type: 'integer', description: '主体ID' }, user_id: { type: 'integer', description: '用户ID' }, role: { type: 'string', description: '该主体下的角色标识' }, is_default: { type: 'integer', description: '是否默认主体:1是 0否' }, status: { type: 'integer', description: '状态:1启用 0禁用' }, created_at: { type: 'string', description: '创建时间' }, updated_at: { type: 'string', description: '更新时间' }, }, principalUserPage: buildPage('principalUserItem', '关联记录列表'), principalUserListResponse: buildListResponse('principalUserPage'), bindPrincipalUserRequest: { principal_id: { type: 'integer', required: true, description: '主体ID' }, user_id: { type: 'integer', required: true, description: '用户ID' }, role: { type: 'string', description: '角色标识,如 admin' }, is_default: { type: 'integer', description: '是否默认主体:1是 0否,默认0' }, status: { type: 'integer', description: '状态:1启用 0禁用,默认1' }, }, // ---------- 商品 products ---------- productItem: { id: { type: 'integer', description: '主键' }, principal_id: { type: 'integer', description: '所属主体ID' }, code: { type: 'string', description: '商品编码' }, name: { type: 'string', description: '商品名称' }, type: { type: 'integer', description: '商品类型' }, category: { type: 'string', description: '分类' }, spec: { type: 'string', description: '规格' }, unit: { type: 'string', description: '单位' }, price: { type: 'number', description: '销售价' }, cost_price: { type: 'number', description: '成本价' }, image: { type: 'string', description: '图片URL' }, status: { type: 'integer', description: '状态:1上架 0下架' }, remark: { type: 'string', description: '备注' }, created_at: { type: 'string', description: '创建时间' }, updated_at: { type: 'string', description: '更新时间' }, }, productPage: buildPage('productItem', '商品列表'), productListResponse: buildListResponse('productPage'), createProductRequest: { principal_id: { type: 'integer', required: true, description: '所属主体ID' }, code: { type: 'string', required: true, description: '商品编码,主体内唯一' }, name: { type: 'string', required: true, description: '商品名称' }, type: { type: 'integer', description: '商品类型,默认1' }, category: { type: 'string', description: '分类' }, spec: { type: 'string', description: '规格' }, unit: { type: 'string', description: '单位' }, price: { type: 'number', required: true, description: '销售价' }, cost_price: { type: 'number', description: '成本价' }, image: { type: 'string', description: '图片URL' }, status: { type: 'integer', description: '状态:1上架 0下架,默认1' }, remark: { type: 'string', description: '备注' }, }, updateProductRequest: { principal_id: { type: 'integer', description: '所属主体ID' }, code: { type: 'string', description: '商品编码' }, name: { type: 'string', description: '商品名称' }, type: { type: 'integer', description: '商品类型' }, category: { type: 'string', description: '分类' }, spec: { type: 'string', description: '规格' }, unit: { type: 'string', description: '单位' }, price: { type: 'number', description: '销售价' }, cost_price: { type: 'number', description: '成本价' }, image: { type: 'string', description: '图片URL' }, status: { type: 'integer', description: '状态:1上架 0下架' }, remark: { type: 'string', description: '备注' }, }, // ---------- 组合商品 combo_products ---------- comboProductItem: { id: { type: 'integer', description: '主键' }, principal_id: { type: 'integer', description: '所属主体ID' }, code: { type: 'string', description: '组合商品编码' }, name: { type: 'string', description: '组合商品名称' }, price: { type: 'number', description: '组合售价' }, items: { type: 'string', description: '组合明细 JSON:[{ product_id: 1, quantity: 2 }]' }, status: { type: 'integer', description: '状态:1上架 0下架' }, remark: { type: 'string', description: '备注' }, created_at: { type: 'string', description: '创建时间' }, updated_at: { type: 'string', description: '更新时间' }, }, comboProductPage: buildPage('comboProductItem', '组合商品列表'), comboProductListResponse: buildListResponse('comboProductPage'), createComboProductRequest: { principal_id: { type: 'integer', required: true, description: '所属主体ID' }, code: { type: 'string', required: true, description: '组合商品编码,主体内唯一' }, name: { type: 'string', required: true, description: '组合商品名称' }, price: { type: 'number', required: true, description: '组合售价' }, items: { type: 'string', description: '组合明细 JSON 数组:[{ product_id: 1, quantity: 2 }]' }, status: { type: 'integer', description: '状态:1上架 0下架,默认1' }, remark: { type: 'string', description: '备注' }, }, updateComboProductRequest: { principal_id: { type: 'integer', description: '所属主体ID' }, code: { type: 'string', description: '组合商品编码' }, name: { type: 'string', description: '组合商品名称' }, price: { type: 'number', description: '组合售价' }, items: { type: 'string', description: '组合明细 JSON 数组' }, status: { type: 'integer', description: '状态:1上架 0下架' }, remark: { type: 'string', description: '备注' }, }, // ---------- 菜单 menus ---------- menuItem: { id: { type: 'integer', description: '主键' }, parent_id: { type: 'integer', description: '父菜单ID,0 为根节点' }, name: { type: 'string', description: '菜单名称' }, type: { type: 'integer', description: '类型:1目录 2菜单 3按钮' }, path: { type: 'string', description: '前端路由/地址' }, icon: { type: 'string', description: '图标' }, permission: { type: 'string', description: '权限标识,如 order:create' }, sort: { type: 'integer', description: '排序,值越大越靠前' }, status: { type: 'integer', description: '状态:1启用 0禁用' }, created_at: { type: 'string', description: '创建时间' }, updated_at: { type: 'string', description: '更新时间' }, }, menuPage: buildPage('menuItem', '菜单列表'), menuListResponse: buildListResponse('menuPage'), createMenuRequest: { parent_id: { type: 'integer', description: '父菜单ID,默认0(根节点)' }, name: { type: 'string', required: true, description: '菜单名称' }, type: { type: 'integer', description: '类型:1目录 2菜单 3按钮,默认2' }, path: { type: 'string', description: '前端路由/地址' }, icon: { type: 'string', description: '图标' }, permission: { type: 'string', description: '权限标识,如 order:create' }, sort: { type: 'integer', description: '排序,默认0' }, status: { type: 'integer', description: '状态:1启用 0禁用,默认1' }, }, updateMenuRequest: { parent_id: { type: 'integer', description: '父菜单ID' }, name: { type: 'string', description: '菜单名称' }, type: { type: 'integer', description: '类型:1目录 2菜单 3按钮' }, path: { type: 'string', description: '前端路由/地址' }, icon: { type: 'string', description: '图标' }, permission: { type: 'string', description: '权限标识' }, sort: { type: 'integer', description: '排序' }, status: { type: 'integer', description: '状态:1启用 0禁用' }, }, // ---------- 主体外部接口 principal_external_apis ---------- externalApiItem: { id: { type: 'integer', description: '主键' }, principal_id: { type: 'integer', description: '所属主体ID' }, code: { type: 'string', description: '外部系统标识,如 wms / erp' }, name: { type: 'string', description: '接口名称' }, base_url: { type: 'string', description: '接口基础地址' }, app_key: { type: 'string', description: '应用Key' }, app_secret: { type: 'string', description: '应用密钥(建议加密存储)' }, extra: { type: 'string', description: '扩展配置 JSON' }, status: { type: 'integer', description: '状态:1启用 0禁用' }, created_at: { type: 'string', description: '创建时间' }, updated_at: { type: 'string', description: '更新时间' }, }, externalApiPage: buildPage('externalApiItem', '接口配置列表'), externalApiListResponse: buildListResponse('externalApiPage'), createExternalApiRequest: { principal_id: { type: 'integer', required: true, description: '所属主体ID' }, code: { type: 'string', required: true, description: '外部系统标识,如 wms;主体内唯一' }, name: { type: 'string', required: true, description: '接口名称' }, base_url: { type: 'string', description: '接口基础地址' }, app_key: { type: 'string', description: '应用Key' }, app_secret: { type: 'string', description: '应用密钥' }, extra: { type: 'string', description: '扩展配置 JSON' }, status: { type: 'integer', description: '状态:1启用 0禁用,默认1' }, }, updateExternalApiRequest: { principal_id: { type: 'integer', description: '所属主体ID' }, code: { type: 'string', description: '外部系统标识' }, name: { type: 'string', description: '接口名称' }, base_url: { type: 'string', description: '接口基础地址' }, app_key: { type: 'string', description: '应用Key' }, app_secret: { type: 'string', description: '应用密钥' }, extra: { type: 'string', description: '扩展配置 JSON' }, status: { type: 'integer', description: '状态:1启用 0禁用' }, }, // ---------- 订单 orders ---------- orderItem: { id: { type: 'integer', description: '主键' }, order_no: { type: 'string', description: '业务订单号,唯一' }, principal_id: { type: 'integer', description: '所属主体ID' }, order_type: { type: 'integer', description: '订单类型' }, status: { type: 'integer', description: '主状态:1待处理 2处理中 3已完成 4已取消' }, wms_status: { type: 'string', description: '外部WMS状态,如 CREATED/PICKING/SHIPPED' }, wms_order_no: { type: 'string', description: '外部WMS单号' }, wms_synced_at: { type: 'string', description: '最近一次WMS同步时间' }, submit_status: { type: 'integer', description: '上交状态:0未上交 1上交中 2已上交 3上交失败' }, submit_order_no: { type: 'string', description: '上交后返回的单号' }, submit_at: { type: 'string', description: '上交时间' }, submit_msg: { type: 'string', description: '上交结果/失败原因' }, total_amount: { type: 'number', description: '订单金额' }, pay_amount: { type: 'number', description: '实付金额' }, receiver: { type: 'string', description: '收货人信息 JSON:{ name, phone, address }' }, remark: { type: 'string', description: '备注' }, created_at: { type: 'string', description: '创建时间' }, updated_at: { type: 'string', description: '更新时间' }, }, orderPage: buildPage('orderItem', '订单列表'), orderListResponse: buildListResponse('orderPage'), createOrderRequest: { order_no: { type: 'string', required: true, description: '业务订单号,唯一' }, principal_id: { type: 'integer', required: true, description: '所属主体ID' }, order_type: { type: 'integer', description: '订单类型,默认1' }, status: { type: 'integer', description: '主状态,默认1(待处理)' }, wms_status: { type: 'string', description: '外部WMS状态' }, wms_order_no: { type: 'string', description: '外部WMS单号' }, total_amount: { type: 'number', description: '订单金额' }, pay_amount: { type: 'number', description: '实付金额' }, receiver: { type: 'string', description: '收货人信息 JSON:{ name, phone, address }' }, remark: { type: 'string', description: '备注' }, }, updateOrderRequest: { order_no: { type: 'string', description: '业务订单号' }, order_type: { type: 'integer', description: '订单类型' }, status: { type: 'integer', description: '主状态:1待处理 2处理中 3已完成 4已取消' }, total_amount: { type: 'number', description: '订单金额' }, pay_amount: { type: 'number', description: '实付金额' }, receiver: { type: 'string', description: '收货人信息 JSON' }, remark: { type: 'string', description: '备注' }, }, /** 订单状态流转:主状态 + 上交(上报)状态 */ updateOrderStatusRequest: { status: { type: 'integer', description: '主状态:1待处理 2处理中 3已完成 4已取消' }, submit_status: { type: 'integer', description: '上交状态:0未上交 1上交中 2已上交 3上交失败' }, submit_order_no: { type: 'string', description: '上交后返回的单号' }, submit_msg: { type: 'string', description: '上交结果/失败原因' }, }, /** 外部 WMS 状态回写 */ wmsStatusRequest: { wms_status: { type: 'string', required: true, description: '外部WMS状态,如 CREATED/PICKING/SHIPPED' }, wms_order_no: { type: 'string', description: '外部WMS单号' }, status: { type: 'integer', description: '同时更新主状态(可选)' }, message: { type: 'string', description: '状态说明/异常原因' }, }, };