380 lines
20 KiB
JavaScript
380 lines
20 KiB
JavaScript
'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: '状态说明/异常原因' },
|
||
},
|
||
};
|