通讯录（ContactsController）

通讯录相关接口：分页/全量获取当前企业域用户、按部门组装通讯录树、按软件+角色组装通讯录树、按关键字模糊/首字母查询联系人、按部门加载子树、收藏/取消收藏/查询收藏/判断收藏、获取头像、按角色或部门统计人数、自由流程回退取历史处理人。

范围说明：本控制器为页面级 @Controller（cn.myapps.runtime.contacts.controller.ContactsController），基址 /api/contacts。另有同名移动端控制器 cn.myapps.runtime.mobile.contacts.controller.ContactsController（基址 /runtime/app/contacts，返回 {status, message, data} JSON），见 mobile-contacts.md。

• 接口类型：REST 资源（@Controller 继承 BaseController，方法返回 Map<String, Object>，由 Spring Jackson 序列化为 JSON 对象；响应非统一 Resource，统一封装为 { "status": 1/0, "message": "ok"/"error", "data": <数据> }，详见「公共说明 · 响应结构」）
• 基址：${myapps.context-path.runtime:}/api/contacts
• Tag：通讯录

公共说明

• 鉴权（据源码）：基址 /api/contacts 不在 RestSecurityHandlerInterceptor 覆盖范围（拦截器仅覆盖 /api/runtime/** 与 /api/rest/bpm/**）。鉴权由 RuntimeMvcConfig 注册的全局过滤器 RuntimeSecurityFilter（URL 模式 /*）执行：过滤器解析 AuthTimeServiceManager.getWebUser(request)，取不到登录用户则返回 401（或 SSO 模式下重定向到 /signon）。所有端点均需 accessToken，可通过 Cookie / 请求头 / query 参数任一方式传递。控制器内 getUser() 通过 AuthTimeServiceManager.getWebUser(request) 还原 WebUser；当无登录态时 fallback 到内置「测试用户」（id=1234-5678-90，仅用于异常容错，生产调用应保证登录态）。
• 响应结构（据源码 BaseController.addActionResult）：本控制器所有端点返回 Map<String, Object>，结构为：

  {
    "status": 1,
    "message": "ok",
    "data": <数据>
  }
  

• status：1 成功，0 失败；
• message：成功 ok，失败 error；
• data：业务数据；当业务返回 null 时 data 字段缺省。
• 与统一 Resource（errcode/errmsg/data/errors）约定不一致，本文档按源码如实记录。
• 参数读取：参数通过 BaseController.getParams()（基于 ParamsTable.convertHTTP(request)）统一从 query / form 读取，无 @RequestParam 注解；_pagelines 默认 Web.DEFAULT_LINES_PER_PAGE。
• 公开可见性过滤：getContacts / getContactsBySearch / getFavoriteContacts 仅返回 status==1 且 permissionType=="public" 的用户；手机号/邮箱按 isTelephonePublic / isTelephonePublic2 / isEmailPublic 控制可见性。

---

1. 获取全部用户（分页）

按当前用户的企业域分页查询用户列表，封装为 UserNode 集合返回。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method，支持 GET / POST 等所有方法）
• 请求路径：/contacts/getAllUser.action 或 /getAllUser.action（完整：{runtime-context}/api/contacts/contacts/getAllUser.action 或 {runtime-context}/api/contacts/getAllUser.action）
• 鉴权：是（需 accessToken，据源码：RuntimeSecurityFilter 校验登录态）
• Tag：通讯录

请求参数

参数名	位置	类型	必填	说明
pageNo	query	int	否	页码，默认 1

请求示例

GET /api/contacts/getAllUser.action?pageNo=1 HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map，固定字段如下（详见「公共说明 · 响应结构」）。 data：Map，封装 { datas: List<UserNode>, linesPerPage, pageCount, pageNo, rowCount }。

{
  "status": 1,
  "message": "ok",
  "data": {
    "datas": [{ "id": "__USERID__", "name": "张三", "mobile": "13800000000", "dept": "研发部" }],
    "linesPerPage": 10,
    "pageCount": 1,
    "pageNo": 1,
    "rowCount": 1
  }
}

---

2. 获取通讯录（按部门组装树）

按当前企业域全部部门（按层级倒序）+ 全部公开用户组装通讯录树（每个部门挂载其默认部门等于该部门的公开用户）。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/contacts/getContacts.action（完整：{runtime-context}/api/contacts/contacts/getContacts.action）
• 鉴权：是（需 accessToken，据源码）
• Tag：通讯录

请求参数

无。

请求示例

GET /api/contacts/contacts/getContacts.action HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map（详见「公共说明 · 响应结构」）。 data：List<DepartmentNode>，每个 DepartmentNode 挂载 children: List<UserNode>。

{
  "status": 1,
  "message": "ok",
  "data": [
    {
      "id": "__DEPTID__",
      "name": "研发部",
      "children": [{ "id": "__USERID__", "name": "张三", "mobile": "13800000000", "dept": "研发部" }]
    }
  ]
}

---

3. 获取「软件-角色」通讯录树

按 applictaionId / roleId（均非必填）分三段返回： - 两者皆空：返回当前企业域下全部已激活软件（ApplicationNode）； - 仅 applictaionId：返回该软件下全部有效角色（RoleNode）； - 含 roleId：返回该角色下的公开/有效用户（UserNode）。

字段名源码为 applictaionId（拼写与常见 applicationId 不同），按源码记录。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/contacts/getApplicationAndRoleContactsTree.action 或 /getApplicationAndRoleContactsTree.action（完整：{runtime-context}/api/contacts/contacts/getApplicationAndRoleContactsTree.action 或 {runtime-context}/api/contacts/getApplicationAndRoleContactsTree.action）
• 鉴权：是（需 accessToken，据源码）
• Tag：通讯录

请求参数

参数名	位置	类型	必填	说明
applictaionId	query	string	否	软件 id（源码字段名拼写）
roleId	query	string	否	角色 id

请求示例

GET /api/contacts/contacts/getApplicationAndRoleContactsTree.action?applictaionId=__APPID__&roleId=__ROLEID__ HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map（详见「公共说明 · 响应结构」）。 data：List<Node>，元素类型由参数组合决定（ApplicationNode / RoleNode / UserNode）。

{
  "status": 1,
  "message": "ok",
  "data": [{ "id": "__USERID__", "name": "张三", "mobile": "13800000000", "dept": "研发部" }]
}

---

4. 按关键字模糊查询联系人

按 keyWord 在当前企业域模糊匹配用户，返回公开且有效的用户集合。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/contacts/getContactsBySearch.action（完整：{runtime-context}/api/contacts/contacts/getContactsBySearch.action）
• 鉴权：是（需 accessToken，据源码）
• Tag：通讯录

请求参数

参数名	位置	类型	必填	说明
keyWord	query	string	否	关键字（姓名/电话/邮箱等模糊匹配）

请求示例

GET /api/contacts/contacts/getContactsBySearch.action?keyWord=张 HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map（详见「公共说明 · 响应结构」）。 data：List<UserNode>，命中的公开用户集合。

{
  "status": 1,
  "message": "ok",
  "data": [{ "id": "__USERID__", "name": "张三", "dept": "研发部" }]
}

---

5. 按首字母查询联系人

按 keyWord（首字母）在当前企业域匹配用户，返回匹配用户集合（不区分公开/私有）。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/contacts/getContactsByFirstLetter.action（完整：{runtime-context}/api/contacts/contacts/getContactsByFirstLetter.action）
• 鉴权：是（需 accessToken，据源码）
• Tag：通讯录

请求参数

参数名	位置	类型	必填	说明
keyWord	query	string	否	首字母关键字

请求示例

GET /api/contacts/contacts/getContactsByFirstLetter.action?keyWord=Z HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map（详见「公共说明 · 响应结构」）。 data：List<UserNode>。

{
  "status": 1,
  "message": "ok",
  "data": [{ "id": "__USERID__", "name": "张三", "dept": "研发部" }]
}

---

6. 获取通讯录树（按部门逐级展开）

按 parentId 逐级加载部门树： - 不传 parentId：返回当前企业域根部门； - 传 parentId：返回该部门下的子部门 + 该部门下的公开用户（私有用户与停用用户过滤）。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/contacts/getContactsTree.action 或 /getContactsTree.action（完整：{runtime-context}/api/contacts/contacts/getContactsTree.action 或 {runtime-context}/api/contacts/getContactsTree.action）
• 鉴权：是（需 accessToken，据源码）
• Tag：通讯录

请求参数

参数名	位置	类型	必填	说明
parentId	query	string	否	父部门 id；为空时取企业域根部门

请求示例

GET /api/contacts/contacts/getContactsTree.action?parentId=__DEPTID__ HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map（详见「公共说明 · 响应结构」）。 data：List<Node>，元素为 DepartmentNode 或 UserNode。

{
  "status": 1,
  "message": "ok",
  "data": [
    { "id": "__DEPTID_CHILD__", "name": "前端组" },
    { "id": "__USERID__", "name": "张三", "mobile": "13800000000", "dept": "研发部" }
  ]
}

---

7. 添加常用联系人

将 userId 追加到当前登录用户的 favoriteContacts（以 ; 分隔），更新入库。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/contacts/addFavoriteContact.action（完整：{runtime-context}/api/contacts/contacts/addFavoriteContact.action）
• 鉴权：是（需 accessToken，据源码）
• Tag：通讯录

请求参数

参数名	位置	类型	必填	说明
userId	query	string	否	待收藏用户 id（源码无必填校验）

请求示例

GET /api/contacts/contacts/addFavoriteContact.action?userId=__USERID__ HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map（详见「公共说明 · 响应结构」）。 data：成功时缺省（无 data 字段）。

{ "status": 1, "message": "ok" }

---

8. 移除常用联系人

从当前登录用户的 favoriteContacts 中移除 userId（按 ; 分隔重组），更新入库。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/contacts/removeFavoriteContact.action（完整：{runtime-context}/api/contacts/contacts/removeFavoriteContact.action）
• 鉴权：是（需 accessToken，据源码）
• Tag：通讯录

请求参数

参数名	位置	类型	必填	说明
userId	query	string	否	待取消收藏的用户 id

请求示例

GET /api/contacts/contacts/removeFavoriteContact.action?userId=__USERID__ HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map（详见「公共说明 · 响应结构」）。 data：成功时缺省。

{ "status": 1, "message": "ok" }

---

9. 获取常用联系人列表

解析当前登录用户 favoriteContacts 字段，按用户 id 集合批量加载，过滤出公开且有效的用户。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/contacts/getFavoriteContacts.action 或 /getFavoriteContacts.action（完整：{runtime-context}/api/contacts/contacts/getFavoriteContacts.action 或 {runtime-context}/api/contacts/getFavoriteContacts.action）
• 鉴权：是（需 accessToken，据源码）
• Tag：通讯录

请求参数

无。

请求示例

GET /api/contacts/contacts/getFavoriteContacts.action HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map（详见「公共说明 · 响应结构」）。 data：List<UserNode>，常用联系人集合（无收藏时为空数组）。

{
  "status": 1,
  "message": "ok",
  "data": [{ "id": "__USERID__", "name": "张三", "dept": "研发部" }]
}

---

10. 判断是否为常用联系人

判断 userId 是否已存在于当前登录用户的 favoriteContacts 中。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/contacts/isFavoriteContact.action（完整：{runtime-context}/api/contacts/contacts/isFavoriteContact.action）
• 鉴权：是（需 accessToken，据源码）
• Tag：通讯录

请求参数

参数名	位置	类型	必填	说明
userId	query	string	否	待判断用户 id

请求示例

GET /api/contacts/contacts/isFavoriteContact.action?userId=__USERID__ HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map（详见「公共说明 · 响应结构」）。 data：boolean，已收藏为 true，未收藏为 false。

{ "status": 1, "message": "ok", "data": true }

---

11. 获取用户头像

按 id 加载用户，返回头像 URI（无头像时返回空字符串）。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/contacts/getAvatar.action（完整：{runtime-context}/api/contacts/contacts/getAvatar.action）
• 鉴权：是（需 accessToken，据源码）
• Tag：通讯录

请求参数

参数名	位置	类型	必填	说明
id	query	string	否	用户 id

请求示例

GET /api/contacts/contacts/getAvatar.action?id=__USERID__ HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map（详见「公共说明 · 响应结构」）。 data：string，头像 URI；用户不存在时返回 status=0、无 data。

{ "status": 1, "message": "ok", "data": "/resource/avatar/__USERID__.png" }

失败示例：

{ "status": 0, "message": "error" }

---

12. 获取角色或部门下人数

按 type 与 id 统计角色或部门下的用户数。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/contacts/getRoleOrDeptUserCounts.action（完整：{runtime-context}/api/contacts/contacts/getRoleOrDeptUserCounts.action）
• 鉴权：是（需 accessToken，据源码）
• Tag：通讯录

请求参数

参数名	位置	类型	必填	说明
type	query	int	否	数据类型：Node.TYPE_DEPT（部门）/ Node.TYPE_ROLE（角色）；为 null 时默认按部门统计
id	query	string	否	部门 id 或角色 id

请求示例

GET /api/contacts/contacts/getRoleOrDeptUserCounts.action?type=2&id=__ROLEID__ HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map（详见「公共说明 · 响应结构」）。 data：int，用户数量。

{ "status": 1, "message": "ok", "data": 25 }

---

13. 自由流程回退获取历史处理人

按 stateId（文档 id）查询流程历史处理人，去除当前用户自身并去重，封装为 UserNode 集合返回（用于自由流程回退节点选择审批人）。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/getHisActors4FreeFlow.action（完整：{runtime-context}/api/contacts/getHisActors4FreeFlow.action）
• 鉴权：是（需 accessToken，据源码）
• Tag：通讯录

请求参数

参数名	位置	类型	必填	说明
stateId	query	string	否	流程文档 id（实际作为 FlowHistoryService.getFlowHistorysByDocId 入参）
applicationId	query	string	否	软件 id（DES 加密密文，服务端 DesUtil.decryptTextByUserId 解密）

请求示例

GET /api/contacts/getHisActors4FreeFlow.action?stateId=__STATEID__&applicationId=__ENC_APPID__ HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map（详见「公共说明 · 响应结构」）。 data：List<UserNode>，历史处理人集合（不包含当前用户）；异常时 data 为 ""（空字符串）。

{
  "status": 1,
  "message": "ok",
  "data": [{ "id": "__USERID__", "name": "李四", "dept": "研发部" }]
}

---