Files

T

Austin d398467fb9 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

4.2 KiB

Raw Blame History

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

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

1. 功能说明

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

数据链路：

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

要点：

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

2. 接口定义

2.1 获取联系我们配置

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）：

{
  "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. 本地联调示例

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>"

实测返回：

{"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:、空列表回退静态链接）

4.2 KiB Raw Blame History Unescape Escape