移动端通讯录（mobile.ContactsController）

移动端通讯录相关接口：按父级部门加载通讯录树、按关键字模糊搜索联系人/部门/二者合一、获取/添加/移除常用联系人。

范围说明：本控制器为移动端 cn.myapps.runtime.mobile.contacts.controller.ContactsController，基址 /runtime/app/contacts。另有同名页面级 REST 控制器 cn.myapps.runtime.contacts.controller.ContactsController（基址 /api/contacts），见 contacts.md，两者独立、不共用路由。

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

公共说明

• 鉴权（据源码）：基址 /runtime/app/contacts 不在 RestSecurityHandlerInterceptor 覆盖范围（拦截器仅覆盖 /api/runtime/** 与 /api/rest/bpm/**）。鉴权由 RuntimeMvcConfig 注册的全局过滤器 RuntimeSecurityFilter（URL 模式 /*）执行：过滤器解析 AuthTimeServiceManager.getWebUser(request)，取不到登录用户则返回 401（或 SSO 模式下重定向到 /signon）。除显式说明外，端点均需 accessToken，可通过 Cookie / 请求头 / query 参数任一方式传递。控制器内 getUserId() 通过 Security.getUserIdFromToken(request) 还原用户 id；当无登录态时返回 null，多数端点会在此时直接返回失败结果（addActionResult(false, null)）。
• 响应结构（据源码 mobile.common.controller.BaseController.addActionResult）：本控制器所有端点返回 Map<String, Object>，结构为：

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

• status：0 成功，1 失败；
• message：成功 ok，失败 error；
• data：业务数据；当业务返回 null 时 data 字段缺省；写入前由 ESAPI.encode(data) 做 XSS 编码。
• 与统一 Resource（errcode/errmsg/data/errors）约定不一致，本文档按源码如实记录。
• 参数读取：参数通过 BaseController.getParams()（基于 ParamsTable.convertHTTP(request)）统一从 query / form 读取，无 @RequestParam 注解；_pagelines 默认 Web.DEFAULT_LINES_PER_PAGE。
• 公开可见性过滤：getContactsTree（带 parentId 时）仅返回 status != 0 且 permissionType != "private" 的用户；getFavoriteContacts 仅返回 status == 1 且 permissionType == "public" 的用户。
• Tag：源码类级未声明 @Tag，本文件按模块归为「移动端通讯录」。

---

1. 获取通讯录（按父级部门加载树）

按 parentId 加载部门通讯录树：不传 parentId 时返回当前企业域根部门；传 parentId 时返回该部门下的子部门与公开用户集合（含常用联系人标记、用户头像 URI、所属部门名）。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method，支持 GET / POST 等所有方法）
• 请求路径：/tree.action（完整：{runtime-context}/runtime/app/contacts/tree.action）
• 鉴权：是（需 accessToken，据源码：RuntimeSecurityFilter 校验登录态；无登录态时 getUserId() 返回 null，控制器直接返回失败结果）
• Tag：移动端通讯录

请求参数

参数名	位置	类型	必填	说明
access_token	query	string	是	访问令牌（亦可经 Cookie / 请求头传递）
parentId	query	string	否	父级部门 id；不传时取当前企业域根部门

请求示例

GET /runtime/app/contacts/tree.action?parentId=__DEPTID__ HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map，固定字段见「公共说明 · 响应结构」。 data：Map，封装 { datas: List<Node>, count: int }；datas 元素为 Department（id/name/userCount，仅根节点带 userCount）或 User（id/name/mobile/mobile2/email/avatar/domain/dept/favoriteContact）。

{
  "status": 0,
  "message": "ok",
  "data": {
    "datas": [
      { "id": "__DEPTID__", "name": "研发部", "userCount": 12 },
      { "id": "__USERID__", "name": "张三", "mobile": "13800000000", "avatar": "/uploads/...", "domain": "默认企业域", "dept": "研发部", "favoriteContact": false }
    ],
    "count": 13
  }
}

---

2. 模糊搜索联系人

按联系人姓名 / 首字母 / 电话在当前企业域内模糊匹配用户（含常用联系人标记、用户头像 URI、默认部门名）。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/getContactsBySearch.action（完整：{runtime-context}/runtime/app/contacts/getContactsBySearch.action）
• 鉴权：是（需 accessToken；控制器内调用 getUser()，无登录态将抛错进入失败分支）
• Tag：移动端通讯录

请求参数

参数名	位置	类型	必填	说明
access_token	query	string	是	访问令牌
keyWord	query	string	否	关键字（联系人姓名 / 首字母 / 电话）

请求示例

GET /runtime/app/contacts/getContactsBySearch.action?keyWord=zhang HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map，固定字段见「公共说明 · 响应结构」。 data：List<User>，元素结构同 #1 的 User（无 userCount 字段）。

{
  "status": 0,
  "message": "ok",
  "data": [
    { "id": "__USERID__", "name": "张三", "mobile": "13800000000", "email": "zhangsan@example.com", "avatar": "/uploads/...", "domain": "默认企业域", "dept": "研发部", "favoriteContact": false }
  ]
}

---

3. 模糊搜索部门

按部门名称在当前企业域内模糊匹配有效（valid=1）部门。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/getDepartmentsBySearch.action（完整：{runtime-context}/runtime/app/contacts/getDepartmentsBySearch.action）
• 鉴权：是（需 accessToken；控制器内调用 getUser()）
• Tag：移动端通讯录

请求参数

参数名	位置	类型	必填	说明
access_token	query	string	是	访问令牌
keyWord	query	string	否	部门名称关键字

请求示例

GET /runtime/app/contacts/getDepartmentsBySearch.action?keyWord=研发 HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map，固定字段见「公共说明 · 响应结构」。 data：List<Department>，元素结构 { id, name }。

{
  "status": 0,
  "message": "ok",
  "data": [
    { "id": "__DEPTID__", "name": "研发部" }
  ]
}

---

4. 模糊搜索联系人和部门

同时按联系人关键字（姓名 / 首字母 / 电话，限制在当前用户范围内匹配）与部门名称关键字（限制在当前企业域范围内匹配）查询，合并为单一列表返回。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/getContactsAndDeptsBySearch.action（完整：{runtime-context}/runtime/app/contacts/getContactsAndDeptsBySearch.action）
• 鉴权：是（需 accessToken；控制器内调用 getUser()）
• Tag：移动端通讯录

请求参数

参数名	位置	类型	必填	说明
access_token	query	string	是	访问令牌
keyWord	query	string	否	关键字（同时用于联系人与部门匹配）

请求示例

GET /runtime/app/contacts/getContactsAndDeptsBySearch.action?keyWord=研发 HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：Map，固定字段见「公共说明 · 响应结构」。 data：List<Node>，元素为 User（同 #2）或 Department（同 #3）混排，联系人排在部门之前。

{
  "status": 0,
  "message": "ok",
  "data": [
    { "id": "__USERID__", "name": "张三", "mobile": "13800000000", "domain": "默认企业域", "dept": "研发部", "favoriteContact": false },
    { "id": "__DEPTID__", "name": "研发部" }
  ]
}

---

5. 获取常用联系人

读取当前用户的「常用联系人」清单（按 ; 分割用户 id），仅返回 status==1 且 permissionType=="public" 的有效用户，含常用联系人标记（恒为 true）、头像 URI、默认部门名。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/getFavoriteContacts.action（完整：{runtime-context}/runtime/app/contacts/getFavoriteContacts.action）
• 鉴权：是（需 accessToken；控制器内调用 getUser()）
• Tag：移动端通讯录

请求参数

参数名	位置	类型	必填	说明
access_token	query	string	是	访问令牌

请求示例

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

响应

结构：Map，固定字段见「公共说明 · 响应结构」。 data：Map，封装 { datas: List<User>, count: int }。

{
  "status": 0,
  "message": "ok",
  "data": {
    "datas": [
      { "id": "__USERID__", "name": "张三", "mobile": "13800000000", "domain": "默认企业域", "dept": "研发部", "favoriteContact": true }
    ],
    "count": 1
  }
}

---

6. 添加常用联系人

将指定联系人追加到当前用户的「常用联系人」清单（; 分隔）。若用户已有清单，原值后追加 ;userId。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/addFavoriteContact.action（完整：{runtime-context}/runtime/app/contacts/addFavoriteContact.action）
• 鉴权：是（需 accessToken；控制器内调用 getUser()）
• Tag：移动端通讯录

请求参数

参数名	位置	类型	必填	说明
access_token	query	string	是	访问令牌
userId	query	string	是	待加入的联系人主键

请求示例

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

响应

结构：Map，固定字段见「公共说明 · 响应结构」。 data：成功时缺省（业务数据为 null）。

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

---

7. 移除常用联系人

从当前用户的「常用联系人」清单中移除指定联系人（按字符串替换去除 userId 或 ;userId）。

• 接口类型：REST 资源
• 请求方式：@RequestMapping（未限定 method）
• 请求路径：/removeFavoriteContact.action（完整：{runtime-context}/runtime/app/contacts/removeFavoriteContact.action）
• 鉴权：是（需 accessToken；控制器内调用 getUser()）
• Tag：移动端通讯录

请求参数

参数名	位置	类型	必填	说明
access_token	query	string	是	访问令牌
userId	query	string	是	待移除的联系人主键

请求示例

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

响应

结构：Map，固定字段见「公共说明 · 响应结构」。 data：成功时缺省（业务数据为 null）。

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

---