# IM「联系我们」移动端接口对接文档

> 版本：v1.0
> 日期：2026-09-21
> 状态：**已实现**，可按本文直接联调
> 适用端：iOS / Android / Web（im_webapp）

## 1. 功能说明

移动端「设置 / 关于 / 支持」页面的**联系我们**入口，展示管理员配置的客服邮箱。

数据链路：

```text
管理后台「系统管理 → 字典管理 → 联系我们」
  → IM 管理端数据库（字典类型 im_contact_us，条目即 label/value）
  → im-server 缓存（内存 TTL 1 分钟兜底 + 管理端变更事件主动失效）
  → 移动端 GET /v1/im/contact-us
```

要点：

- 条目内容由运营在管理后台维护，客户端不需要硬编码任何联系方式。
- 管理后台修改后**近实时生效**（事件失效，秒级）；事件通道不可用时最长 1 分钟内收敛（缓存 TTL 兜底）。
- 条目数量不固定，客户端必须按列表渲染，不能假设只有一个条目。
- 接口返回为空列表时，客户端应**隐藏联系我们入口**，不要渲染空区块。

## 2. 接口定义

### 2.1 获取联系我们配置

```text
GET {api_path}v1/im/contact-us
```

**请求头**（公共约定同《IM-前后端对接文档.md》§0.2）：

| Header | 必填 | 说明 |
| --- | --- | --- |
| `X-MeetingIM-APIKey` | 是 | 应用级接入标识 |
| `X-IM-Schema` | 是 | 固定 `1` |
| `X-Request-ID` | 是 | 请求追踪 ID |
| `Authorization` | 是 | `Bearer <token>`，登录态必填 |

**请求参数**：无

**成功响应**（HTTP 200）：

```json
{
  "code": 0,
  "data": {
    "items": [
      { "label": "客服邮箱", "value": "support@example.com" }
    ]
  },
  "request_id": "req-contactus-2",
  "server_time": "2026-09-21T04:58:19.521Z"
}
```

`data` 字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `items` | `array` | 联系方式条目列表，按管理后台配置的排序返回；可能为空数组 `[]` |
| `items[].label` | `string` | 条目名称，如「客服邮箱」，客户端原样展示 |
| `items[].value` | `string` | 条目值，邮箱地址 |

**失败响应**：

| HTTP | code | reason | 场景 |
| --- | --- | --- | --- |
| 403 | 30003 | `API_KEY_REQUIRED` | API Key 缺失或无效 |
| 401 | 30043 | `AUTH_REQUIRED` | 未登录 / token 过期，引导重新登录 |
| 405 | 30002 | `METHOD_NOT_ALLOWED` | 非 GET 请求 |
| 500 | 90000 | `INTERNAL_ERROR` | 服务端内部错误，可重试 |

## 3. 客户端渲染规则

按条目值的形态渲染（客户端本地判断，与服务端无关）：

| value 形态 | 判断 | 交互 |
| --- | --- | --- |
| 邮箱 | 包含 `@` 且形如 `x@y.z` | `mailto:{value}`，图标用 `email` |
| 其他 | 不满足邮箱格式 | 纯文本展示，不可点击 |

补充约定：

- 每个条目的展示文案使用 `label`，不要自行翻译或改写。
- 接口失败（网络/500）时静默降级：若客户端保留了旧版本静态联系方式可继续展示，否则隐藏入口，不弹 toast。
- 不需要本地缓存该接口结果；进入页面时请求即可，服务端已有缓存兜底。

## 4. 本地联调示例

```bash
curl -s "http://{host}/{api_path}v1/im/contact-us" \
  -H "X-MeetingIM-APIKey: <api_key>" \
  -H "X-IM-Schema: 1" \
  -H "X-Request-ID: req-contactus-2" \
  -H "Authorization: Bearer <token>"
```

实测返回：

```json
{"code":0,"data":{"items":[{"label":"客服邮箱","value":"support@example.com"}]},"request_id":"req-contactus-2","server_time":"2026-09-21T04:58:19.521Z"}
```

## 5. 配置维护（运营侧）

- 入口：管理后台「系统管理 → 字典管理」→ 字典类型 `联系我们`（type=`im_contact_us`）。
- 新增/修改/删除条目即配置生效，`状态=停用` 的条目不会返回。
- 测试环境初始化 SQL：`im_manager/docs/im/IM-联系我们字典配置.sql`（im_manager 仓库）。
- 首次部署后如接口返回空列表，先确认管理后台该字典类型下存在 `状态=启用` 的条目。

## 6. 参考实现

Web 端（im_webapp）已完成对接，可直接参考：

- API 封装：`src/lib/im-api.js` 中 `getContactUs()`
- 页面渲染：`src/views/acc-support-view.jsx`（邮箱 `mailto:`、空列表回退静态链接）