用户（UserController）

提供 KMS 知识管理模块「用户域」的能力：获取当前登录用户（并初始化个人网盘）、按用户Id查询用户、为用户批量设置角色、按部门Id与名称分页查询用户。所有端点均返回 JSON 资源。

• 接口类型：REST 资源（@RestController，方法级 produces = MediaType.APPLICATION_JSON_VALUE；类级 @RequestMapping 仅声明前缀，未带 produces）
• 基址：${myapps.context-path.kms:}/api/kms（类级 @RequestMapping 仅声明单一前缀，无 /kms 备用前缀）
• Tag：kms用户模块

公共说明

• 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*）。本控制器路径 /api/kms/users/** 不在 KmsSecurityFilter.isExcludeURI 的豁免名单内（豁免仅覆盖 /login.*、/admin、/domain.*、/tray/service、/authtime、service/OfficeServer、.*outsideshare/.*/preview、静态资源后缀、actuator/health 等）。过滤器调用 Security.getUserIdFromToken(request)，取不到用户则返回 HTTP 401。因此所有端点均需 accessToken，可通过以下任一方式传递（据 Security.getUserIdFromToken）：query 参数 accessToken、query 参数 access_token（移动端）、请求头 accessToken、Cookie accessToken、请求头 Authorization: Bearer <token>。完整鉴权机制见 index.md「鉴权说明」。
• 执行用户：控制器内 getUser()（继承自 AbstractBaseController）调用 Security.getUserIdFromToken(request) 还原当前用户 id，再经 Feign（UserAPI.getUserById）装载 KmsUser。无 userCode 参数。
• 响应结构：统一 Resource（见 ../index.md「统一响应结构」），字段为 errcode/errmsg/data/errors。KMS 的 Resource 为 AbstractBaseController 内部类，其构造器对 data 执行 ESAPI.encode(data) 做 XSS 编码，故 data 中的 HTML 特殊字符会被转义。
• HTTP 状态码与错误码（据源码 AbstractBaseController 全局异常处理）：成功默认 HTTP 200；InvalidRequestException → HTTP 400 / errcode=400；UnauthorizedException → HTTP 403 / errcode=403；ForbiddenException → HTTP 403 / errcode=403；ResourceNotFoundException → HTTP 404 / errcode=404；其他 Exception → HTTP 500 / errcode=500。
• error(Exception) 重载的行为差异（据源码，需注意）：本控制器在参数校验失败时调用的是 error(new InvalidRequestException("<消息>"))。由于 AbstractBaseController 同时存在 error(int, String, List) 与 error(Exception) 两个重载，Java 方法解析会匹配 error(Exception)，从而**返回固定 errcode=500、errmsg="error"（字面字符串，非传入的消息）**，且 HTTP 状态由方法级 @ResponseStatus(HttpStatus.OK) 决定仍为 200。下方各端点的「失败示例」据此如实记录。
• @RequestParam 默认必填：未标 required=false 且无 defaultValue 的 query 参数按 Spring 约定为必填。
• 路径变量：id 为用户Id（KMS 内部主键，明文 id）。

---

1. 获取当前登录用户

返回当前登录的 KmsUser 对象。会先以当前用户Id查找其个人网盘，若不存在则自动创建一个个人网盘。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/users/myprofile（完整：{kms-context}/api/kms/users/myprofile）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms用户模块

请求参数

无。

请求示例

GET /api/kms/users/myprofile?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：KmsUser 对象，含 id、name、loginid、domainid、domainName、defaultDepartment 等字段。

据源码：方法在 getUser() 返回 null 的分支里调用 error(new RuntimeException("您还没有登陆系统，请重新登陆"))。受前述重载规则影响，此时实际返回 Resource(500, "error", null, null)（HTTP 200）；但实际上 getUser() 在用户为空时会先抛 UnauthorizedException（HTTP 403），故该分支通常不可达。

---

2. 根据用户ID获取用户信息

按用户Id查询用户对象。id 为空时返回错误。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/users/{id}（完整：{kms-context}/api/kms/users/{id}）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms用户模块

请求参数

参数名	位置	类型	必填	说明
id	path	string	是	用户Id

请求示例

GET /api/kms/users/__USERID__?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：KmsUser 对象。

失败示例（id 为空，据源码 error(Exception) 重载）：

{ "errcode": 500, "errmsg": "error", "data": null, "errors": null }

---

3. 为用户设置角色

为一批用户批量设置角色。deptIds 由服务端以当前用户默认部门填充（请求体无需传 deptIds）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/users/userroleset（完整：{kms-context}/api/kms/users/userroleset）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms用户模块

请求参数

参数名	位置	类型	必填	说明
body	body	object	是	JSON 对象，含 roleIds、userIds 两个字段，见下方请求体

请求体

{
  "roleIds": ["__ROLEID1__", "__ROLEID2__"],
  "userIds": ["__USERID1__", "__USERID2__"]
}

请求示例

POST /api/kms/users/userroleset?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "roleIds": ["__ROLEID1__"], "userIds": ["__USERID1__"] }

响应

结构：统一 Resource。 data：boolean，固定为 true（角色设置由 userService.setRoles(userIds, roleIds, deptIds) 完成，过程中抛出的异常由全局处理器映射）。

---

4. 根据部门ID或名称查询用户

按部门Id、名称/账号关键字、角色Id分页查询当前企业域下的用户。departmentId 允许为空串（按全部用户处理）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/users（完整：{kms-context}/api/kms/users）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms用户模块

请求参数

参数名	位置	类型	必填	说明
departmentId	query	string	是	部门Id（源码形参未标 required=false，但注释「可以为空」；调用方可传空串）
nameOrAccount	query	string	是	名称或账号关键字
roleId	query	string	否	角色Id（required=false）
linesPerPage	query	string	是	每页条数（字符串型数字）
pageNo	query	string	是	页码（字符串型数字）

请求示例

GET /api/kms/users?departmentId=__DEPTID__&nameOrAccount=张&roleId=__ROLEID__&pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<KmsUser>，用户分页数据。

失败示例（linesPerPage 与 pageNo 均为空，据源码 error(Exception) 重载）：

{ "errcode": 500, "errmsg": "error", "data": null, "errors": null }

据源码：仅当 linesPerPage 与 pageNo 同时为空时才进入错误分支；任一非空都会继续走 Integer.parseInt(...)，若传入非数字字符串会抛 NumberFormatException，由全局 @ExceptionHandler(Exception.class) 映射为 HTTP 500 / errcode=500 / errmsg="error"。

---