risk-management-process/docs/前期讨论/001-后端API文档-用户管理相关.md

标题：风险防控管理系统_接口文档

版本：版本号:3.9.2
服务地址：http://localhost:8080
生成说明：基于 Swagger OpenAPI 3.1 自动提取（规范共 155 个接口路径，本文档仅整理以下 7 个目标接口）。该文档由后端团队提供，仅提供基础用户登录相关API。其他API尚待设计。

认证方式

• 方案 apikey：请求头 Authorization: Bearer <token>（scheme=Bearer）
  • 除「验证码」「用户登录」外，其它接口均需在请求头携带该令牌。

通用返回结构说明

本项目所有业务接口统一返回 AjaxResult（列表接口返回 TableDataInfo）。

注意：本 Swagger 规范中 AjaxResult 仅声明了 error/success/warn/empty 四个布尔字段， 未建模真实的 code / msg / data 字段。以下为运行时实际返回结构，编写调用代码请以实际返回为准。

AjaxResult（单对象 / 操作结果）：

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

TableDataInfo（分页列表）：

{
  "total": 0,
  "rows": [
    {}
  ],
  "code": 200,
  "msg": "查询成功"
}

• code：状态码（200 成功，其它为错误码）
• msg：提示信息
• data：业务数据对象（列表接口的 rows 为该对象数组）

接口总览

序号	接口	方法	路径	分组
1	用户列表	GET	/system/user/list	系统管理
2	部门树	GET	/system/user/deptTree	系统管理
3	用户信息-任意人员	GET	/system/user/{userId}	系统管理
4	用户信息-个人信息	GET	/system/user/profile	系统管理
5	修改密码	PUT	/system/user/profile/updatePwd	系统管理
6	验证码	GET	/captchaImage	公共
7	用户登陆	POST	/login	公共

1. 用户列表

• 路径：GET /system/user/list
• 分组（Tag）：sys-user-controller

请求参数

查询通过对象参数 user（类型 SysUser，必填：是）绑定，以下字段以同名 query 参数传入：

字段（参数名）	类型	必填	说明
createBy	string	否
createTime	string	否
updateBy	string	否
updateTime	string	否
remark	string	否
params	object	否
userId	integer(int64)	否
deptId	integer(int64)	否
userName	string	否
nickName	string	否
email	string	否
phonenumber	string	否
sex	string	否
avatar	string	否
password	string	否
status	string	否
delFlag	string	否
loginIp	string	否
loginDate	string	否
pwdUpdateDate	string	否
dept	SysDept	否
roles	array	否
roleIds	array	否
postIds	array	否
roleId	integer(int64)	否
admin	boolean	否

分页参数 pageNum、pageSize 由分页拦截器自动读取（不体现在方法签名中），示例：?pageNum=1&pageSize=10。

响应（HTTP 200）

响应结构（TableDataInfo）字段（按本规范建模）：

字段	类型	必填	说明
total	integer(int64)	否
rows	array	否
code	integer(int32)	否
msg	string	否

实际返回结构见上文「通用返回结构说明」（code/msg/data 等字段未在规范中建模）。

业务数据说明：rows 为 SysUser 对象数组，total 为总记录数。

---

2. 部门树

• 路径：GET /system/user/deptTree
• 分组（Tag）：sys-user-controller

请求参数

查询通过对象参数 dept（类型 SysDept，必填：是）绑定，以下字段以同名 query 参数传入：

字段（参数名）	类型	必填	说明
createBy	string	否
createTime	string	否
updateBy	string	否
updateTime	string	否
remark	string	否
params	object	否
deptId	integer(int64)	否
parentId	integer(int64)	否
ancestors	string	否
deptLevel	integer(int32)	否
deptName	string	否
orderNum	integer(int32)	否
leader	string	否
phone	string	否
email	string	否
deptType	string	否
status	string	否
delFlag	string	否
parentName	string	否
children	array	否

响应（HTTP 200）

响应结构（AjaxResult）字段（按本规范建模）：

字段	类型	必填	说明
error	boolean	否
success	boolean	否
warn	boolean	否
empty	boolean	否

实际返回结构见上文「通用返回结构说明」（code/msg/data 等字段未在规范中建模）。

---

3. 用户信息-任意人员

• 路径：GET /system/user/{userId}
• 分组（Tag）：sys-user-controller

请求参数

• userId（path，类型 integer(int64)，必填：是）：

响应（HTTP 200）

响应结构（AjaxResult）字段（按本规范建模）：

字段	类型	必填	说明
error	boolean	否
success	boolean	否
warn	boolean	否
empty	boolean	否

实际返回结构见上文「通用返回结构说明」（code/msg/data 等字段未在规范中建模）。

业务数据说明：data 返回指定 userId 对应用户的 SysUser 信息对象。

备注：路径变量在本文档中命名为 userId，即需求中的 {id}（按用户 ID 查询任意人员信息）。

---

4. 用户信息-个人信息

• 路径：GET /system/user/profile
• 分组（Tag）：sys-profile-controller

响应（HTTP 200）

响应结构（AjaxResult）字段（按本规范建模）：

字段	类型	必填	说明
error	boolean	否
success	boolean	否
warn	boolean	否
empty	boolean	否

实际返回结构见上文「通用返回结构说明」（code/msg/data 等字段未在规范中建模）。

业务数据说明：data 返回当前登录用户的 SysUser 信息对象。

---

5. 修改密码

• 路径：PUT /system/user/profile/updatePwd
• 分组（Tag）：sys-profile-controller

请求体（application/json）

字段	类型	必填	说明
oldPassword	string	是	原密码
newPassword	string	是	新密码

注：OpenAPI 中该请求体被建模为自由对象（Map<String,String>），上表为实际使用的字段。

响应（HTTP 200）

响应结构（AjaxResult）字段（按本规范建模）：

字段	类型	必填	说明
error	boolean	否
success	boolean	否
warn	boolean	否
empty	boolean	否

实际返回结构见上文「通用返回结构说明」（code/msg/data 等字段未在规范中建模）。

---

6. 验证码

• 路径：GET /captchaImage
• 分组（Tag）：captcha-controller

响应（HTTP 200）

响应结构（AjaxResult）字段（按本规范建模）：

字段	类型	必填	说明
error	boolean	否
success	boolean	否
warn	boolean	否
empty	boolean	否

实际返回结构见上文「通用返回结构说明」（code/msg/data 等字段未在规范中建模）。

业务数据说明：成功时 data 返回 {"uuid":"...","img":"data:image/png;base64,..."}，uuid 与 img 用于登录时校验验证码。

---

7. 用户登陆

• 路径：POST /login
• 分组（Tag）：sys-login-controller

请求体（application/json）

字段	类型	必填	说明
username	string	是	用户名
password	string	是	密码
code	string	是	验证码（由 /captchaImage 返回）
uuid	string	是	验证码唯一标识（由 /captchaImage 返回）

注：OpenAPI 中该请求体被建模为自由对象（Map<String,String>），上表为实际使用的字段。

响应（HTTP 200）

响应结构（AjaxResult）字段（按本规范建模）：

字段	类型	必填	说明
error	boolean	否
success	boolean	否
warn	boolean	否
empty	boolean	否

实际返回结构见上文「通用返回结构说明」（code/msg/data 等字段未在规范中建模）。

业务数据说明：登录成功时 data 返回 "token" 字符串，后续请求须在请求头 Authorization: Bearer <token> 中携带。

---