用户选择框（UserSelectboxController）

提供 KMS 知识管理模块「用户选择框域」的能力：以通讯录树形结构返回用户集合、按部门Id分页查询用户、按关键字搜索用户、按父部门Id获取部门树。主要用于前端表单中选择用户/部门的弹出框场景。所有端点均返回 JSON 资源。

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

公共说明

• 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*）。本控制器路径 /api/kms/users/selectbox/** 不在 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。本控制器均使用 getUser().getDomainid() 限定企业域范围。无 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。
• @RequestParam 默认必填：未标 required=false 且无 defaultValue 的 query 参数按 Spring 约定为必填。
• 路径变量：departmentId 为 KMS 内部主键（明文 id）。

---

1. 获取以通讯录为树形结构的用户集合

返回当前用户所在企业域下、以通讯录为树形结构组织的用户集合。固定取前 10 条（服务端调用固定 firstResult=1、maxResults=10）。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（不限定方法，GET/POST 均可；下文示例按 GET）
• 请求路径：/contacts（完整：{kms-context}/api/kms/users/selectbox/contacts）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms用户选择框模块

请求参数

无。

请求示例

GET /api/kms/users/selectbox/contacts?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：Map<String, Object>，通讯录树形结构（由 userService.getUserListAsContactsTree(domainid, 1, 10) 返回）。

---

2. 获取部门下的用户集合

按部门Id分页查询当前企业域下指定部门的用户列表。

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

请求参数

参数名	位置	类型	必填	说明
departmentId	path	string	是	部门Id
linesPerPage	query	int	是	每页条数（基本类型，建议显式传入）
pageNo	query	int	是	页码（基本类型，建议显式传入）

请求示例

GET /api/kms/users/selectbox/departments/__DEPARTMENTID__?pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：Map<String, Object>，含分页用户列表与分页信息（由 userService.queryUsersByDeptId(...) 返回）。

---

3. 根据关键字搜索用户

按关键字（名称/账号模糊匹配）分页搜索当前企业域下的用户。

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

请求参数

参数名	位置	类型	必填	说明
keyword	query	string	是	搜索关键字（名称或账号）
linesPerPage	query	int	是	每页条数
pageNo	query	int	是	页码

请求示例

GET /api/kms/users/selectbox/search?keyword=张&pageNo=1&linesPerPage=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：Map<String, Object>，含分页用户列表与分页信息（由 userService.queryUsersBySearch(...) 返回）。

---

4. 获取以部门为树形结构的用户集合

按父部门Id获取部门树（用于通讯录/部门选择框的层级展示）。parentDeptId 不传时表示从根节点取。

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

请求参数

参数名	位置	类型	必填	说明
parentDeptId	query	string	否	父部门Id（源码标注 required=false；不传时由服务端取根部门）

请求示例

GET /api/kms/users/selectbox/departments?parentDeptId=__DEPARTMENTID__&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：List<Node>，部门树节点列表（由 userService.getDeptTreeByParentId(...) 返回）。

---