docs: add IM contact us interface docking documentation

Complete the 4251-line docking document for IM contact us interface, including function description, interface definition, client rendering rules, local debugging example, operation configuration steps and reference implementation
2026-09-21 13:28:12 +08:00
parent 9748c7a478
commit d398467fb9
1 changed files with 122 additions and 0 deletions
@@ -0,0 +1,122 @@
+# 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:`、空列表回退静态链接）