oms/backend/app/contract/index.js

380 lines
20 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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