05-API接口契约

BasePath: /api 端口: 8080（见 docs/07 § 二，可在 application.yml 覆盖）

全局约定

响应格式

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

错误码

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

鉴权

除登录接口外，所有接口均需在请求头携带 Authorization: Bearer <access_token>。Token 由 REQ-USR-004 登录接口签发，有效期 24 小时。

分页参数

列表查询接口统一使用以下分页入参：pageNum（页码，从 1 起）、pageSize（每页条数，默认 20，最大 100）。响应体 data 字段格式：{ list: [], total: N, pageNum: N, pageSize: N }。

接口清单

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

---

module_usr 用户管理

REQ-USR-004 用户登录

• Method: POST
• Path: /api/auth/login
• Auth: 无（公开接口）
• Permission: —
• 请求: { "username": "string", "password": "string", "brandNo": "string" } — 用户名、密码（明文，HTTPS 传输）、公司编号（对应 brand.sNo）
• 响应: { "accessToken": "string", "refreshToken": "string", "expiresIn": 86400, "userInfo": { "userId": "string", "username": "string", "userType": "string", "language": "string" } }

错误码

• 40100 — 用户名或密码错误（不区分哪个错，防信息泄露）
• 40101 — 账号已被禁用
• 40102 — 账号已被锁定，请 N 分钟后重试
• 40400 — 公司编号不存在

---

REQ-USR-001 增加用户

• Method: POST
• Path: /api/usr/users
• Auth: Bearer Token
• Permission: usr:create
• 请求: { "userCode": "string", "username": "string", "userType": "普通用户|超级管理员", "language": "中文|英文|繁体", "canEditDoc": false, "employeeId": "string|null", "permGroupIds": ["string"] } — 初始密码由后端自动设为系统默认值（666666 哈希）
• 响应: { "userId": "string", "userCode": "string", "username": "string" }

错误码

• 40001 — 参数校验失败（缺必填 / 格式错）
• 40300 — 权限不足
• 40901 — 用户名已存在
• 40902 — 用户号已存在

---

REQ-USR-003 查询用户

• Method: GET
• Path: /api/usr/users
• Auth: Bearer Token
• Permission: usr:query
• 请求: Query 参数：queryField=username|staffName|userCode|department|userType|disabled|lastLoginDate|creator（默认 username）、matchType=contains|notContains|equals（默认 contains）、queryValue=string、page=int（默认 1）、pageSize=int（默认 20，最大 100）
• 响应: { list: [{ "sId", "sUsername", "sUserCode", "sUserType", "sLanguage", "bIsDisabled", "tLastLoginDate", "sCreatorUsername", "tCreateDate", "sStaffName", "sDepartment" }], total, page, pageSize } — sPasswordHash / iLoginFailCount / tLockUntil 不返回

错误码

• 40001 — 参数校验失败
• 40300 — 权限不足

---

REQ-USR-002 修改用户

• Method: PUT
• Path: /api/usr/users/{userId}
• Auth: Bearer Token
• Permission: usr:edit
• 请求: Path 参数 userId（usr_user.sId）；Body：{ "userType": "普通用户|超级管理员", "language": "中文|英文|繁体", "canEditDoc": false, "isDisabled": false, "employeeId": "string|null", "permGroupIds": ["string"] } — 用户名不可修改；密码由单独接口重置
• 响应: { "userId": "string", "username": "string", "updatedAt": "datetime" }

错误码

• 40001 — 参数校验失败
• 40300 — 权限不足
• 40301 — 禁止修改自己的管理员角色
• 40400 — 用户不存在