05-API接口契约

BasePath: /api 端口: 8080

全局约定

响应格式

{"code": 200, "message": "操作成功", "data": {}, "timestamp": 1700000000000}

错误码

范围	含义
200	成功
400xx	客户端参数错误
401xx	认证/授权错误
403xx	权限不足
404xx	资源不存在
500xx	服务端内部错误

鉴权

除 POST /api/usr/auth/login 外，所有接口必须在 HTTP 头携带：

Authorization: Bearer <JWT-access-token>

后端由 JwtAuthenticationFilter 校验签名 + 过期时间；缺失或失效返回 401xx。

分页参数

列表查询统一接收 query 参数：pageNum（1 起，默认 1）、pageSize（默认 20，上限 100）。 响应 data 字段结构：

{ "records": [], "total": 0, "pageNum": 1, "pageSize": 20 }

接口清单

（各模块接口段落见下方，由 downstream-gen 按 REQ 填入）

---

module_mod 模块管理

REQ-MOD-001 模块新增

• Method: POST
• Path: /api/mod/modules
• Auth: 必需
• Permission: 系统管理（仅超级管理员）
• 请求: CreateModuleDTO —— sDisplayType、sProcedureName、sModuleType、sManageDeptEn、bShowPermission、sModuleNameZh、iParentId?、iSortOrder?
• 响应: data = { "iIncrement": 123 }（新模块 id）

错误码

• 40001 — 必填字段缺失或类型错误（含字段定位）
• 40010 — sDisplayType 不在枚举范围
• 40020 — sProcedureName 已存在（唯一冲突）
• 40021 — iParentId 指定的父模块不存在或已软删除
• 40300 — 当前用户非超级管理员

REQ-MOD-002 模块修改

• Method: PUT
• Path: /api/mod/modules/{id}
• Auth: 必需
• Permission: 系统管理（仅超级管理员）
• 请求: path {id} = iIncrement；body UpdateModuleDTO 字段同新增（除 sProcedureName 之外可改，sProcedureName 不可修改）
• 响应: data = { "iIncrement": 123 }

错误码

• 40001 — 字段格式错误
• 40021 — iParentId 形成环或指向自身
• 40400 — 模块 id 不存在或已删除

REQ-MOD-003 模块删除

• Method: DELETE
• Path: /api/mod/modules/{id}
• Auth: 必需
• Permission: 系统管理（仅超级管理员）
• 请求: path {id} = iIncrement
• 响应: data = null（成功）

错误码

• 40400 — 模块不存在
• 40901 — 模块仍有未删除子节点
• 40902 — 模块被外部业务引用（菜单 / 权限 / 角色等）

REQ-MOD-004 模块查询

• Method: GET
• Path: /api/mod/modules
• Auth: 必需
• Permission: 所有登录用户
• 请求: query keyword?（对 sModuleNameZh 模糊匹配，空匹配全部）
• 响应: data = 模块树数组：[{ iIncrement, sModuleNameZh, sDisplayType, sManageDeptEn, iParentId, iSortOrder, children: [...] }]

错误码

• 40001 — keyword 长度超限

---

module_usr 用户管理

REQ-USR-001 用户新增

• Method: POST
• Path: /api/usr/users
• Auth: 必需
• Permission: 用户管理（仅超级管理员）
• 请求: CreateUserDTO —— sUserNo、sUserName、iStaffId?、sUserType、sLanguage、bCanModifyDocs?、permissionCategoryIds[]（权限组）；密码后端按规则生成默认 666666 哈希
• 响应: data = { "iIncrement": 456, "sUserNo": "..." }

错误码

• 40001 — 字段格式错误
• 40020 — sUserName 或 sUserNo 已存在
• 40022 — iStaffId 不存在
• 40023 — permissionCategoryIds 中含无效分类 id

REQ-USR-002 用户修改

• Method: PUT
• Path: /api/usr/users/{id}
• Auth: 必需
• Permission: 用户管理（仅超级管理员；密码不在此接口修改）
• 请求: path {id} = iIncrement；body UpdateUserDTO 字段同新增（不含密码）；permissionCategoryIds[] 重建权限组
• 响应: data = { "iIncrement": 456 }

错误码

• 40001 — 字段格式错误
• 40020 — 用户名 / 用户号唯一冲突
• 40400 — 用户 id 不存在

REQ-USR-003 用户查询

• Method: GET
• Path: /api/usr/users
• Auth: 必需
• Permission: 用户管理 / 本人查询
• 请求: query field（用户名 / 员工名 / 用户号 / 部门 / 用户类型 / 作废 / 登录日期 / 制单人）、match（包含 / 不包含 / 等于）、value?、pageNum?、pageSize?
• 响应: 分页对象，records[] 字段：iIncrement、sUserName、员工名、sUserNo、部门、sUserType、sLanguage、bDeleted、tLastLoginDate、sCreatedBy、tCreateDate（密码字段不返回）

错误码

• 40001 — field / match 取值非法
• 40002 — pageSize 超过 100

REQ-USR-004 用户登录

• Method: POST
• Path: /api/usr/auth/login
• Auth: 无（公开）
• Permission: —
• 请求: LoginDTO —— sUserName、password、version（标准版 / -）
• 响应: data = { "accessToken": "<jwt>", "refreshToken": "<jwt>", "expiresIn": 28800, "user": { "iIncrement", "sUserNo", "sUserName", "sUserType", "sLanguage" } }

错误码

• 40001 — 用户名 / 密码字段为空
• 40101 — 用户名或密码错误
• 40102 — 账号已禁用（bDeleted = 1）
• 42301 — 账号临时锁定（连续失败超过阈值），message 含剩余冷却秒数