Austin
d398467fb9
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
123 lines
4.2 KiB
Markdown
123 lines
4.2 KiB
Markdown
# 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:`、空列表回退静态链接）
|