用户选择框（UserSelectboxController）

为前台「用户选择框」组件提供多种组织维度的用户/部门数据：按部门、按角色、按通讯录、按在线状态、按离职状态、模糊搜索，以及通讯录分组的增删改与成员维护。

• 接口类型：REST 资源（@Component + 类级 @RequestMapping(produces = APPLICATION_JSON_VALUE)，继承自 @RestController 的 AbstractRuntimeController，方法返回值由 Spring 以 JSON 序列化输出）
• 基址：${myapps.context-path.runtime:}/api/runtime
• Tag：用户选择框执行模块

公共说明

• 鉴权（据源码 RuntimeMvcConfig + RestSecurityHandlerInterceptor）：基址位于 /api/runtime/**，不在豁免名单（豁免名单仅覆盖 /api/runtime/login.*、/api/runtime/dingding/authlogin、/api/runtime/synchronization.*、/runtime/sync/.* 等，详见 login.md「公共说明 · 鉴权」）。拦截器对非 /rest/ 路径走 Security.getUserIdFromToken(request)，未取到再尝试 Security.getDebugUserIdFromToken(request)，两者皆无则拒绝访问。所有端点均需 accessToken（或 debugToken），可通过 Cookie / 请求头 / query 参数任一方式传递。
• 路径变量 {applicationId}：仅出现在 selectbox/department、selectbox/role 等以 /{applicationId}/... 开头的端点上，经 DES 加密（按当前执行用户密钥），服务端 DesUtil.decryptTextByUserId(applicationId, getUser().getId()) 解密。其余端点无此变量。
• 响应结构：多数端点返回统一 Resource（见 ../index.md「统一响应结构」）。下列端点返回类型非 Resource，由 Spring 直接序列化，无 errcode/errmsg 包装：
• PUT /updateOnlineUsers：返回 void（HTTP 200，无响应体）。
• DELETE /removeOnlineUser：返回 void（HTTP 200，无响应体）。
• GET /users/selectbox/dept-tree：返回 List<Node>（JSON 数组）。
• getDismissionUserList：源码在 catch 块仅打印堆栈后 return null，异常时控制器返回 Java null（HTTP 200，无响应体）；正常返回统一 Resource。
• 分页：本控制器所有分页端点的分页结构封装在 Resource.data 内，由 UserRunTimeService 返回的 Map<String, Object> 直接体现（字段名以服务端实现为准）。
• HTTP 状态码：所有端点类级标注 @ResponseStatus(HttpStatus.OK)，成功统一返回 200。

---

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

按部门 Id 分页获取该部门下的用户（以部门为树形结构组织）。

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

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件Id（DES 加密密文）
deptId	query	string	是	部门Id
pageSize	query	string	否	每页显示数据数（默认 10）
pageNum	query	string	否	当前页（默认 1）

请求示例

GET /api/runtime/__APPID__/users/selectbox/department?deptId=__DEPTID__&pageNum=1&pageSize=10 HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：统一 Resource。 data：Map<String, Object>，部门用户树（含分页信息），结构由 UserRunTimeService.getUserListAsDeptTree 决定。

{
  "errcode": 0,
  "errmsg": "ok",
  "data": { "...": "部门-用户树结构" },
  "errors": null
}

---

2. 获取以角色为树形结构的用户集合（分页）

按角色 Id 分页获取该角色下的用户（以角色为树形结构组织），可携带流程上下文用于流程节点身份过滤。

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

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	软件Id（DES 加密密文）
roleId	query	string	否	角色Id
pageSize	query	string	否	每页显示数据数（默认 10）
pageNum	query	string	否	当前页（默认 1）
flowId	query	string	否	流程Id（流程上下文过滤）
nodeId	query	string	否	流程节点Id（流程上下文过滤）
docId	query	string	否	文档Id（流程上下文过滤）
type	query	int	否	类型（流程上下文过滤）

请求示例

GET /api/runtime/__APPID__/users/selectbox/role?roleId=__ROLEID__&pageNum=1&pageSize=10 HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：统一 Resource。 data：Map<String, Object>，角色用户树（含分页信息）。

{ "errcode": 0, "errmsg": "ok", "data": { "...": "角色-用户树结构" }, "errors": null }

---

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

按通讯录分组获取用户树，支持按用户名过滤及邮件场景调用。

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

请求参数

参数名	位置	类型	必填	说明
contactsId	query	string	否	通讯录分组Id
userName	query	string	否	用户名称（模糊匹配）
pageNum	query	string	否	当前页（默认 1）
pageSize	query	string	否	每页显示数据数（默认 10）
isFromMail	query	boolean	否	是否邮件调用

请求示例

GET /api/runtime/users/selectbox/contacts?contactsId=__GROUPID__&pageNum=1&pageSize=10 HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：统一 Resource。 data：Map<String, Object>，通讯录用户树（含分页信息）。

{ "errcode": 0, "errmsg": "ok", "data": { "...": "通讯录-用户树结构" }, "errors": null }

---

4. 更新在线用户

将当前登录用户加入在线用户集合（心跳维持）。无响应体。

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

请求参数

无。

请求示例

PUT /api/runtime/updateOnlineUsers HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：非统一 Resource。控制器返回 void，HTTP 200，无响应体。

---

5. 移除在线用户

将当前登录用户从在线用户集合中移除（退出时调用）。无响应体。

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

请求参数

无。

请求示例

DELETE /api/runtime/removeOnlineUser HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：非统一 Resource。控制器返回 void，HTTP 200，无响应体。

---

6. 获取在线用户集合

分页获取当前在线用户集合（用于「在线用户」选择场景）。

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

请求参数

参数名	位置	类型	必填	说明
pageNum	query	string	否	当前页（默认 1）
pageSize	query	string	否	每页显示数据数（默认 10）

请求示例

GET /api/runtime/users/selectbox/onlines?pageNum=1&pageSize=10 HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：统一 Resource。 data：Map<String, Object>，在线用户集合（含分页信息）。

{ "errcode": 0, "errmsg": "ok", "data": { "...": "在线用户结构" }, "errors": null }

---

7. 获取离职用户集合

按企业域分页获取离职状态用户集合（用于排除/标记场景）。

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

请求参数

参数名	位置	类型	必填	说明
domainId	query	string	是	企业域Id
pageNum	query	int	是	当前页（源码 @RequestParam(required=true) int，无默认值）
pageSize	query	int	是	每页显示数据数（源码 @RequestParam(required=true) int，无默认值）

说明：源码 @ApiImplicitParams 标注了 defaultValue="1"/"50"，但方法签名是 @RequestParam(required = true) int pageNum/pageSize，Spring 解析为「必填且无默认」；缺参时返回 400。

请求示例

GET /api/runtime/users/selectbox/dimissions?domainId=__DOMAINID__&pageNum=1&pageSize=50 HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：统一 Resource（异常时控制器返回 Java null，HTTP 200 无响应体）。 data：List<UserNode>，每个元素 { "id": "...", "name": "..." }。

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [ { "id": "...", "name": "张三" } ],
  "errors": null
}

---

8. 模糊查询用户

按关键字（联系人姓名 / 首字母 / 电话）模糊查询用户。

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

请求参数

参数名	位置	类型	必填	说明
keyWord	query	string	否	关键字
pageNum	query	string	否	当前页（默认 1）
pageSize	query	string	否	每页显示数据数（默认 10）
isFromMail	query	boolean	否	是否邮件调用

请求示例

GET /api/runtime/users/selectbox/search?keyWord=zhang&pageNum=1&pageSize=10 HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：统一 Resource。 data：Map<String, Object>，命中用户集合（含分页信息）。

{ "errcode": 0, "errmsg": "ok", "data": { "...": "命中用户结构" }, "errors": null }

---

9. 获取部门树

按父级 Id 获取部门树（基于当前用户的企业域）。

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

请求参数

参数名	位置	类型	必填	说明
parentId	query	string	否	父级Id

请求示例

GET /api/runtime/users/selectbox/dept-tree?parentId=__PARENTID__ HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：非统一 Resource。控制器直接返回 List<Node>，由 Spring 序列化为 JSON 数组，无 errcode/errmsg 包装。

[
  { "id": "...", "name": "研发部", "parentId": "..." }
]

---

10. 获取通讯录分组

获取当前用户拥有的通讯录分组集合（分页结构由 DataPackage 封装）。

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

请求参数

无（分页参数由 ParamsTable 从 request 自动抽取）。

请求示例

GET /api/runtime/users/selectbox/contacts/group HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：统一 Resource。 data：DataPackage<UserGroupVO>，分页封装的通讯录分组集合。

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "datas": [ { "id": "...", "name": "常用联系人", "ownerId": "..." } ],
    "rowCount": 1,
    "pageNo": 1,
    "linesPerPage": 10
  },
  "errors": null
}

---

11. 新建通讯录分组

为当前用户新建一个通讯录分组；同名分组已存在时返回 errcode=4001。

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

请求参数

参数名	位置	类型	必填	说明
name	query	string	是	分组名称

请求示例

POST /api/runtime/users/contacts/groups?name=常用联系人 HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：统一 Resource。 data：UserGroupVO，新建的分组对象。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": { "id": "...", "name": "常用联系人", "ownerId": "...", "domainid": "..." },
  "errors": null
}

失败示例（同名已存在）：

{ "errcode": 4001, "errmsg": "该分组名称已存在", "data": null, "errors": null }

---

12. 保存通讯录分组

更新指定通讯录分组的名称；新名称与该用户其他分组重名时返回 errcode=4001。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/users/contacts/groups/{groupId}（完整：{runtime-context}/api/runtime/users/contacts/groups/{groupId}）
• 鉴权：是（需 accessToken，据源码）
• Tag：用户选择框执行模块

请求参数

参数名	位置	类型	必填	说明
groupId	path	string	是	分组Id
name	query	string	是	新的分组名称

请求示例

POST /api/runtime/users/contacts/groups/__GROUPID__?name=核心客户 HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：统一 Resource。 data：UserGroupVO，更新后的分组对象。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": { "id": "__GROUPID__", "name": "核心客户", "ownerId": "...", "domainid": "..." },
  "errors": null
}

失败示例（新名称与其他分组重名）：

{ "errcode": 4001, "errmsg": "该分组名称已存在", "data": null, "errors": null }

---

13. 删除通讯录分组

按分组 Id 删除通讯录分组。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/users/contacts/groups/{groupId}（完整：{runtime-context}/api/runtime/users/contacts/groups/{groupId}）
• 鉴权：是（需 accessToken，据源码）
• Tag：用户选择框执行模块

请求参数

参数名	位置	类型	必填	说明
groupId	path	string	是	分组Id

请求示例

DELETE /api/runtime/users/contacts/groups/__GROUPID__ HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：统一 Resource。 data：string，固定为 "删除成功"。

{ "errcode": 0, "errmsg": "ok", "data": "删除成功", "errors": null }

---

14. 添加用户至通讯录分组

将一组用户加入指定通讯录分组。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/users/contacts/groups/{groupId}/users（完整：{runtime-context}/api/runtime/users/contacts/groups/{groupId}/users）
• 鉴权：是（需 accessToken，据源码）
• Tag：用户选择框执行模块

请求参数

参数名	位置	类型	必填	说明
groupId	path	string	是	分组Id
userIds	body	string(JSON)	是	用户Id 的 JSON 数组字符串

请求体

["__USERID1__", "__USERID2__"]

请求示例

POST /api/runtime/users/contacts/groups/__GROUPID__/users HTTP/1.1
Content-Type: application/json
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

["__USERID1__", "__USERID2__"]

响应

结构：统一 Resource。 data：string，固定为 "添加成功"。

{ "errcode": 0, "errmsg": "ok", "data": "添加成功", "errors": null }

---

15. 移除通讯录分组用户

将一组用户从指定通讯录分组中移除。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/users/contacts/groups/{groupId}/users（完整：{runtime-context}/api/runtime/users/contacts/groups/{groupId}/users）
• 鉴权：是（需 accessToken，据源码）
• Tag：用户选择框执行模块

请求参数

参数名	位置	类型	必填	说明
groupId	path	string	是	分组Id
userIds	body	string(JSON)	是	用户Id 的 JSON 数组字符串

请求体

["__USERID1__", "__USERID2__"]

请求示例

DELETE /api/runtime/users/contacts/groups/__GROUPID__/users HTTP/1.1
Content-Type: application/json
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

["__USERID1__", "__USERID2__"]

响应

结构：统一 Resource。 data：string，固定为 "移除成功"。

{ "errcode": 0, "errmsg": "ok", "data": "移除成功", "errors": null }

---