# IM WebSocket 前后端接口文档

> 本文档根据 `/Users/superysh/im/prototype` 下的产品原型图整理，用于移动端/前端与 Tinode 后端对接。协议风格遵循 Tinode `docs/API.md`：默认全部业务通信通过 WebSocket JSON 文本帧完成；大文件仍沿用 Tinode 现有 HTTP 上传/下载端点，上传完成后通过 WebSocket 发送附件引用。

## 目录

1. [适用范围](#适用范围)
2. [协议总则](#协议总则)
3. [公共数据约定](#公共数据约定)
4. [连接与认证](#连接与认证)
5. [消息与会话](#消息与会话)
6. [好友与通讯录](#好友与通讯录)
7. [群聊与群管理](#群聊与群管理)
8. [文件、收藏与聊天记录](#文件收藏与聊天记录)
9. [语音、视频与通话](#语音视频与通话)
10. [话题功能](#话题功能)
11. [系统消息、举报与安全提示](#系统消息举报与安全提示)
12. [个人中心与设置](#个人中心与设置)
13. [错误码与状态码](#错误码与状态码)

## 适用范围

### 原型覆盖页面

原型图覆盖以下业务域：

| 业务域 | 页面示例 |
|---|---|
| 登录注册 | 登录、注册、忘记密码、验证码、实名认证、身份验证、独立密码 |
| 消息 | 消息列表、私聊、群聊、文件助手、系统消息、长按菜单、多选、转发、撤回、删除 |
| 联系人 | 朋友、新朋友、添加好友、好友主页、备注、拉黑、黑名单、删除好友 |
| 群聊 | 创建群聊、加入群聊、群二维码、群资料、群公告、群文件、群管理员、禁言、群主转让、进群验证 |
| 文件与收藏 | 文件发送、下载、打开、群文件、我的收藏、收藏分享 |
| 通话 | 语音通话、视频通话、等待接听、通话中、关闭摄像头/麦克风/扬声器、悬浮状态 |
| 话题 | 话题列表、发布话题、话题详情、话题人数、话题类型、积分不足 |
| 设置 | 个人信息、个性签名、隐私设置、青少年模式、版本更新、清空缓存、意见反馈 |
| 安全 | 反诈弹窗、用户协议、推送权限、相机/麦克风权限、安全提醒、举报 |

### 与 Tinode 原生能力的关系

| 能力 | 接入方式 |
|---|---|
| 登录、注册、Token、验证码 | 使用 `{hi}`、`{acc}`、`{login}`，必要时接入 `code`/`rest` auth |
| 私聊、群聊、频道 | 使用 `{sub}`、`{leave}`、`{pub}`、`{get}`、`{set}`、`{del}` |
| 消息回执、输入中、语音录制中 | 使用 `{note}`，服务端转发为 `{info}` |
| 用户资料、群资料、备注、置顶、免打扰 | 使用 `public`、`private`、`aux` |
| 文件、图片、语音、视频 | 大文件先上传 `/v0/file/u/`，再通过 `{pub}` 发送 Drafty 附件 |
| 群权限、管理员、禁言、踢人 | 使用 Tinode ACL 与 `{set sub}`、`{del what="sub"}`，业务状态写入 `aux` |
| 收藏、话题、签到、青少年模式、反诈提示 | 使用本产品扩展命名空间 `x-im-*` |

## 协议总则

### WebSocket 端点

客户端统一连接：

```text
ws://{host}/v0/channels?apikey={api_key}
wss://{host}/v0/channels?apikey={api_key}
```

每个 WebSocket 文本帧只发送一个 JSON 消息。二进制帧不用于业务数据。

### 首包与登录顺序

客户端连接成功后必须先发送 `{hi}`，再发送 `{login}` 或 `{acc}`。登录后建议立即订阅 `me` 和 `fnd`：

```json
{"hi":{"id":"100","ver":"0.25","ua":"IM/1.0 (iOS)","platf":"ios","lang":"zh-CN","tenant":"acme"}}
```

```json
{"login":{"id":"101","scheme":"basic","secret":"MTg4MjY4Mjc3NTQ6MTIzNDU2"}}
```

```json
{"sub":{"id":"102","topic":"me","get":{"what":"desc sub tags cred"}}}
```

```json
{"sub":{"id":"103","topic":"fnd"}}
```

### 消息类型

客户端到服务端：

| 包 | 用途 |
|---|---|
| `{hi}` | 握手、声明企业码、客户端版本和设备信息 |
| `{acc}` | 注册、修改认证参数、提交验证码 |
| `{login}` | 登录、Token 登录、重置密码流程 |
| `{sub}` | 订阅/进入会话、创建群、创建私聊、拉取初始数据 |
| `{leave}` | 离开会话或退订会话 |
| `{pub}` | 发送持久化消息 |
| `{get}` | 查询资料、订阅、消息历史、删除记录、辅助数据 |
| `{set}` | 更新资料、备注、权限、群设置、辅助数据 |
| `{del}` | 删除消息、订阅、topic、凭证 |
| `{note}` | 发送临时通知，如已读、已收、输入中、通话信令 |

服务端到客户端：

| 包 | 用途 |
|---|---|
| `{ctrl}` | 请求结果，应答成功或失败 |
| `{data}` | 持久化消息投递 |
| `{meta}` | 资料、订阅、标签、凭证、删除记录、辅助数据返回 |
| `{pres}` | 在线、离线、权限、资料更新、消息到达等通知 |
| `{info}` | 由 `{note}` 转发而来的临时通知 |

### 请求 ID 规范

客户端必须为需要应答的请求设置 `id`。建议格式：

```text
{module}-{timestamp_ms}-{seq}
```

示例：

```json
{"get":{"id":"msg-1722400000000-1","topic":"grpAbC123","what":"data","data":{"limit":20}}}
```

### 扩展命名空间

Tinode 原生字段保持不变。本产品扩展字段统一使用 `x-im-*`：

| 位置 | 示例 | 说明 |
|---|---|---|
| `head.x-im-type` | `"text"`、`"card"`、`"topic-share"` | 消息业务类型 |
| `head.x-im-client-mid` | `"local-uuid"` | 客户端本地消息 ID，用于发送中/失败重试 |
| `head.x-im-anti-fraud` | `true` | 需要客户端展示反诈提醒 |
| `content.x-im-*` | `{...}` | 消息内容里的业务负载 |
| `public.x-im-*` | `{...}` | 对所有可见的业务资料 |
| `private.x-im-*` | `{...}` | 仅当前用户可见的配置 |
| `aux.x-im-*` | `{...}` | 群/频道管理员可写、成员可读的配置 |

第一阶段服务端已启用轻量校验：

| 字段 | 规则 |
|---|---|
| `head.x-im-type` | 必须是文档附录里的已知消息类型 |
| `private.x-im-applyText` | 字符串，最长 256 个字符 |
| `private.x-im-applyStatus`、`private.x-im-joinStatus` | 枚举：`pending`、`accepted`、`rejected`、`expired` |
| `private.x-im-joinApplyText` | 字符串，最长 256 个字符 |
| `private.x-im-blocked`、`private.x-im-muted`、`private.x-im-pinned` | 布尔值 |
| `aux.x-im-group.joinApproval`、`onlyAdminInvite`、`allowMemberFileUpload`、`muteAll` | 布尔值 |
| `aux.x-im-group.mutedUsers` | Tinode 用户 ID 数组 |
| `aux.x-im-group.announcement.text` | 字符串，最长 2000 个字符 |

## 公共数据约定

### 时间与 ID

| 字段 | 说明 |
|---|---|
| `ts`、`created`、`updated` | RFC3339 UTC 字符串，如 `"2026-07-31T08:00:00.000Z"` |
| `user` | Tinode 用户 ID，如 `usrAbCdEf123` |
| `topic` | Tinode topic，如 `usrAbCdEf123`、`grpAbCdEf123`、`chnAbCdEf123` |
| `seq` | topic 内递增消息序号 |
| `clear` | 删除事务序号 |

### 用户公开资料 `public`

用户资料页面、好友主页、群成员头像昵称均使用用户 `public`。

```json
{
  "fn": "张三",
  "photo": {
    "ref": "/v0/file/s/avatar.jpg",
    "type": "image/jpeg"
  },
  "note": "成人最懂什么都没留下",
  "x-im-gender": "female",
  "x-im-birthday": "2008-02-07",
  "x-im-area": "广东省广州市",
  "x-im-id-no": "84444646554"
}
```

### 用户私有资料 `private`

仅当前用户可见。

```json
{
  "comment": "好友备注",
  "tpins": ["usrPeer001", "grpTeam001"],
  "x-im-settings": {
    "teenMode": false,
    "independentPassword": true,
    "allowSearchByPhone": true,
    "allowSearchByQr": true,
    "allowSearchByGroup": true,
    "pushEnabled": true
  }
}
```

### 群公开资料 `public`

群资料、群二维码、群设置页读取群 topic 的 `public`。

```json
{
  "fn": "新人交流群",
  "photo": {
    "ref": "/v0/file/s/group-avatar.jpg",
    "type": "image/jpeg"
  },
  "note": "群主很懒，还没有群简介",
  "x-im-ownerName": "王子民",
  "x-im-qrcode": "im://group/grpAbCdEf123"
}
```

### 群业务配置 `aux`

群设置、群公告、群文件权限、进群验证、禁言列表使用 `aux`。

```json
{
  "x-im-group": {
    "joinApproval": true,
    "onlyAdminInvite": false,
    "onlyAdminEditInfo": true,
    "allowMemberFileUpload": true,
    "muteAll": false,
    "mutedUsers": ["usrMuted001"],
    "announcement": {
      "text": "为帮助新用户熟悉群规则，请勿发布违规内容。",
      "updatedBy": "usrOwner001",
      "updatedAt": "2026-07-31T08:00:00.000Z"
    }
  }
}
```

### 当前用户对会话的私有设置 `desc.private`

聊天设置页里的备注、免打扰、置顶、拉黑、本地草稿等使用当前用户对 topic 的 `private`。

```json
{
  "comment": "王子民",
  "arch": false,
  "x-im-muted": false,
  "x-im-pinned": true,
  "x-im-blocked": false,
  "x-im-draft": "稍后回复"
}
```

## 连接与认证

### 登录

原型页面：登录页面、注册页面。

客户端先发送 `{hi}`，再使用手机号/用户名 + 密码登录。`secret` 为 `base64(username + ":" + password)`。

```json
{"login":{"id":"login-1","scheme":"basic","secret":"MTg4MjY4Mjc3NTQ6MTIzNDU2"}}
```

成功响应：

```json
{
  "ctrl": {
    "id": "login-1",
    "code": 200,
    "text": "ok",
    "params": {
      "user": "usrUser001",
      "token": "token-string",
      "expires": "2026-08-30T08:00:00.000Z"
    },
    "ts": "2026-07-31T08:00:00.000Z"
  }
}
```

### Token 自动登录

```json
{"login":{"id":"login-token-1","scheme":"token","secret":"token-string"}}
```

### 注册

```json
{
  "acc": {
    "id": "acc-1",
    "user": "new",
    "scheme": "basic",
    "secret": "MTg4MjY4Mjc3NTQ6MTIzNDU2",
    "login": true,
    "tags": ["tel:+8618826827754", "basic:18826827754"],
    "cred": [
      {"meth": "tel", "val": "+8618826827754", "resp": "123456"}
    ],
    "desc": {
      "defacs": {"auth": "JRWS", "anon": "N"},
      "public": {
        "fn": "用户1882",
        "x-im-area": "广东省广州市"
      },
      "private": {
        "x-im-settings": {
          "pushEnabled": true,
          "teenMode": false
        }
      }
    }
  }
}
```

### 忘记密码

发送重置请求：

```json
{"login":{"id":"reset-1","scheme":"reset","secret":"YmFzaWM6dGVsOis4NjE4ODI2ODI3NzU0"}}
```

使用收到的临时 token 修改密码：

```json
{
  "acc": {
    "id": "reset-2",
    "token": "restricted-reset-token",
    "scheme": "basic",
    "secret": "OjEyMzQ1Njc4"
  }
}
```

### 实名认证

实名认证是业务扩展，建议写入用户 `private.x-im-realname`，服务端审核通过后可由 root 写入 `trusted.verified=true`。

```json
{
  "set": {
    "id": "realname-1",
    "topic": "me",
    "desc": {
      "private": {
        "x-im-realname": {
          "name": "张三",
          "idCard": "440100199001011234",
          "status": "pending"
        }
      }
    }
  }
}
```

服务端返回：

```json
{"ctrl":{"id":"realname-1","topic":"me","code":200,"text":"ok","ts":"2026-07-31T08:00:00.000Z"}}
```

## 消息与会话

### 获取消息列表

原型页面：消息、文件助手、系统消息、聊天会话列表。

订阅 `me` 后获取当前用户订阅的所有会话：

```json
{"get":{"id":"contacts-1","topic":"me","what":"sub","sub":{"limit":50}}}
```

响应：

```json
{
  "meta": {
    "id": "contacts-1",
    "topic": "me",
    "sub": [
      {
        "topic": "usrPeer001",
        "updated": "2026-07-31T08:00:00.000Z",
        "touched": "2026-07-31T08:10:00.000Z",
        "seq": 18,
        "read": 15,
        "recv": 18,
        "online": true,
        "public": {"fn": "王子民", "photo": {"ref": "/v0/file/s/a.jpg"}},
        "private": {"comment": "王子民", "x-im-muted": false, "x-im-pinned": true}
      }
    ]
  }
}
```

### 进入私聊

私聊 topic 使用对方用户 ID。首次 `{sub}` 会创建 P2P topic。

```json
{
  "sub": {
    "id": "p2p-sub-1",
    "topic": "usrPeer001",
    "get": {
      "what": "desc sub data",
      "data": {"limit": 20}
    }
  }
}
```

### 进入群聊

```json
{
  "sub": {
    "id": "grp-sub-1",
    "topic": "grpTeam001",
    "get": {
      "what": "desc sub data aux",
      "data": {"limit": 20}
    }
  }
}
```

### 发送文本消息

Tinode 推荐使用 Drafty。发送 Drafty 时必须设置 `head.mime="text/x-drafty"`。

```json
{
  "pub": {
    "id": "pub-text-1",
    "topic": "usrPeer001",
    "head": {
      "mime": "text/x-drafty",
      "x-im-type": "text",
      "x-im-client-mid": "local-001"
    },
    "content": {
      "txt": "你好，我是王理娟，很高兴认识你，你怎么称呼"
    }
  }
}
```

接收方收到：

```json
{
  "data": {
    "topic": "usrPeer001",
    "from": "usrUser001",
    "seq": 19,
    "ts": "2026-07-31T08:10:00.000Z",
    "head": {
      "mime": "text/x-drafty",
      "x-im-type": "text",
      "x-im-client-mid": "local-001"
    },
    "content": {
      "txt": "你好，我是王理娟，很高兴认识你，你怎么称呼"
    }
  }
}
```

### 已收、已读、未读数

原型页面：个人对话已读状态、消息未读红点。

```json
{"note":{"topic":"usrPeer001","what":"recv","seq":19,"unread":3}}
```

```json
{"note":{"topic":"usrPeer001","what":"read","seq":19,"unread":0}}
```

对端收到：

```json
{"info":{"topic":"usrPeer001","from":"usrPeer002","what":"read","seq":19}}
```

### 输入中与录音中

```json
{"note":{"topic":"usrPeer001","what":"kp"}}
```

```json
{"note":{"topic":"usrPeer001","what":"kpa"}}
```

```json
{"note":{"topic":"usrPeer001","what":"kpv"}}
```

### @ 提醒

原型页面：`@人员-选择提醒人`、`@人员—选择提醒人-多选`。

```json
{
  "pub": {
    "id": "pub-mention-1",
    "topic": "grpTeam001",
    "head": {
      "mime": "text/x-drafty",
      "mentions": ["usrA001", "usrB001"],
      "x-im-type": "text"
    },
    "content": {
      "txt": "@万先生 @钱哥你们看一下",
      "fmt": [
        {"at": 0, "len": 4, "key": 0},
        {"at": 5, "len": 3, "key": 1}
      ],
      "ent": [
        {"tp": "MN", "data": {"val": "usrA001"}},
        {"tp": "MN", "data": {"val": "usrB001"}}
      ]
    }
  }
}
```

### 回复、引用、编辑

长按菜单中的引用、回复、编辑沿用 Tinode `head.reply`、`head.replace`。

```json
{
  "pub": {
    "id": "pub-reply-1",
    "topic": "grpTeam001",
    "head": {
      "mime": "text/x-drafty",
      "reply": "grpTeam001:19",
      "x-im-type": "text"
    },
    "content": {"txt": "我同意这个方案"}
  }
}
```

编辑消息：

```json
{
  "pub": {
    "id": "pub-edit-1",
    "topic": "grpTeam001",
    "head": {
      "mime": "text/x-drafty",
      "replace": ":19",
      "x-im-type": "text"
    },
    "content": {"txt": "修改后的消息内容"}
  }
}
```

### 撤回与删除

单聊/群聊撤回使用硬删除，前提是用户有 `D` 权限或符合后端业务规则。

```json
{
  "del": {
    "id": "del-msg-1",
    "topic": "grpTeam001",
    "what": "msg",
    "hard": true,
    "delseq": [{"low": 19}]
  }
}
```

仅自己删除：

```json
{
  "del": {
    "id": "del-msg-self-1",
    "topic": "grpTeam001",
    "what": "msg",
    "hard": false,
    "delseq": [{"low": 19}]
  }
}
```

### 转发

逐条转发：

```json
{
  "pub": {
    "id": "forward-1",
    "topic": "usrPeer002",
    "head": {
      "mime": "text/x-drafty",
      "forwarded": "grpTeam001:19",
      "x-im-type": "text"
    },
    "content": {"txt": "被转发的内容"}
  }
}
```

合并转发：

```json
{
  "pub": {
    "id": "forward-merge-1",
    "topic": "usrPeer002",
    "head": {
      "mime": "application/json",
      "x-im-type": "forward-bundle"
    },
    "content": {
      "title": "群聊的聊天记录",
      "items": [
        {"topic": "grpTeam001", "seq": 19, "from": "usrA001", "text": "第一条"},
        {"topic": "grpTeam001", "seq": 20, "from": "usrB001", "text": "第二条"}
      ]
    }
  }
}
```

## 好友与通讯录

### 查找用户

原型页面：添加好友、输入精准用户 ID。

使用 `fnd` topic 查询标签。手机号、用户名、用户 ID 由后端查询重写或精确匹配。

```json
{
  "set": {
    "id": "find-1",
    "topic": "fnd",
    "desc": {
      "public": "18826827754"
    }
  }
}
```

```json
{"get":{"id":"find-2","topic":"fnd","what":"sub","sub":{"limit":20}}}
```

### 添加好友申请

P2P 建立关系使用 `{sub topic=userId}`。申请备注放入 `set.desc.private.x-im-applyText`，审批状态放入 `private.x-im-applyStatus`。服务端会校验状态枚举，真实可聊权限仍以 Tinode ACL 为准。

```json
{
  "sub": {
    "id": "friend-apply-1",
    "topic": "usrPeer001",
    "set": {
      "desc": {
        "private": {
          "x-im-applyText": "我是王子民",
          "x-im-applyStatus": "pending"
        }
      }
    },
    "get": {"what": "desc"}
  }
}
```

对方在线时会收到 `me` topic 的 `pres what="acs"`；客户端可据此刷新新朋友列表。

### 新朋友列表

客户端从 `me` 的订阅列表中过滤待处理 P2P 权限：

```json
{"get":{"id":"new-friends-1","topic":"me","what":"sub","sub":{"limit":100}}}
```

列表状态建议：

| 条件 | 含义 |
|---|---|
| `private.x-im-applyStatus="pending"` | 申请待处理 |
| `private.x-im-applyStatus="accepted"` | 申请已同意 |
| `private.x-im-applyStatus="rejected"` | 申请已拒绝 |
| 对方订阅变更产生 `pres what="acs"` | 我收到的新申请 |

### 同意好友

```json
{
  "set": {
    "id": "friend-approve-1",
    "topic": "usrPeer001",
    "sub": {
      "user": "usrPeer001",
      "mode": "JRWPA"
    }
  }
}
```

同意后建议双方把各自订阅 `private.x-im-applyStatus` 更新为 `accepted`；拒绝时更新为 `rejected`。非法状态会返回 `400 malformed`。

### 设置备注

```json
{
  "set": {
    "id": "remark-1",
    "topic": "usrPeer001",
    "desc": {
      "private": {
        "comment": "王子民",
        "x-im-remarkUpdatedAt": "2026-07-31T08:00:00.000Z"
      }
    }
  }
}
```

### 拉黑与取消拉黑

客户端私有状态用于 UI 展示，服务端应同时调整 P2P ACL，阻止对方继续发起会话。

```json
{
  "set": {
    "id": "block-1",
    "topic": "usrPeer001",
    "desc": {
      "private": {
        "x-im-blocked": true
      }
    },
    "sub": {
      "user": "usrPeer001",
      "mode": "JRPA"
    }
  }
}
```

取消拉黑：

```json
{
  "set": {
    "id": "unblock-1",
    "topic": "usrPeer001",
    "desc": {
      "private": {
        "x-im-blocked": false
      }
    },
    "sub": {
      "user": "usrPeer001",
      "mode": "JRWPA"
    }
  }
}
```

### 删除好友

```json
{
  "leave": {
    "id": "friend-delete-1",
    "topic": "usrPeer001",
    "unsub": true
  }
}
```

## 群聊与群管理

### 创建群聊

原型页面：创建群聊。

```json
{
  "sub": {
    "id": "group-create-1",
    "topic": "new",
    "set": {
      "desc": {
        "defacs": {"auth": "JRWP", "anon": "N"},
        "public": {
          "fn": "新人交流群",
          "note": "群主很懒，还没有群简介"
        },
        "private": {}
      },
      "aux": {
        "x-im-group": {
          "joinApproval": false,
          "onlyAdminInvite": false,
          "allowMemberFileUpload": true,
          "muteAll": false,
          "mutedUsers": []
        }
      }
    },
    "get": {"what": "desc sub aux"}
  }
}
```

成功响应的 `ctrl.topic` 为新群 ID：

说明：创建群时传入的 `set.aux.x-im-group` 会写入 `topics.aux`，后续可通过 `{get what="aux"}` 或 `{sub get.what="desc sub aux"}` 读取。

```json
{"ctrl":{"id":"group-create-1","topic":"grpNew001","code":200,"text":"ok","ts":"2026-07-31T08:00:00.000Z"}}
```

### 邀请成员入群

原型页面：邀请进群申请、开启群验证拉人状态。

无需审批时直接共享订阅：

如果 `aux.x-im-group.onlyAdminInvite=true`，服务端只允许群管理员或群主执行邀请。

```json
{
  "set": {
    "id": "group-invite-1",
    "topic": "grpNew001",
    "sub": {
      "user": "usrInvitee001",
      "mode": "JRWP"
    }
  }
}
```

需要审批时，申请人发送 `{sub}`，请求 `JRWPS`，申请备注写入自己的订阅 `private.x-im-joinApplyText`。若群 `aux.x-im-group.joinApproval=true` 且默认 `defacs.auth` 不包含 `J`，服务端会保存一条 `want=JRWPS/given=N` 的待审批订阅并返回 `200 ok`，但不会把申请人 attach 到群。

```json
{
  "sub": {
    "id": "group-join-apply-1",
    "topic": "grpNew001",
    "set": {
      "sub": {"mode": "JRWPS"},
      "desc": {
        "private": {
          "x-im-joinApplyText": "申请加入群聊",
          "x-im-joinStatus": "pending"
        }
      }
    }
  }
}
```

管理员获取待审批列表：

```json
{"get":{"id":"group-apply-list-1","topic":"grpNew001","what":"sub","sub":{"limit":100}}}
```

返回中待审批用户表现为 `acs.want` 包含 `J`、`acs.given="N"`、`private.x-im-joinStatus="pending"`：

```json
{
  "meta": {
    "id": "group-apply-list-1",
    "topic": "grpNew001",
    "sub": [
      {
        "user": "usrInvitee001",
        "acs": {"want": "JRWPS", "given": "N", "mode": "N"},
        "private": {
          "x-im-joinApplyText": "申请加入群聊",
          "x-im-joinStatus": "pending"
        }
      }
    ]
  }
}
```

管理员审批通过：

```json
{
  "set": {
    "id": "group-approve-1",
    "topic": "grpNew001",
    "sub": {
      "user": "usrInvitee001",
      "mode": "JRWP"
    }
  }
}
```

服务端会把申请人的 `private.x-im-joinStatus` 自动更新为 `accepted`。如果拒绝，管理员设置 `mode="N"`，服务端会把状态更新为 `rejected`：

```json
{
  "set": {
    "id": "group-reject-1",
    "topic": "grpNew001",
    "sub": {
      "user": "usrInvitee001",
      "mode": "N"
    }
  }
}
```

如需在群内留痕，管理员可额外发布审批结果消息：

```json
{
  "pub": {
    "id": "group-join-decision-1",
    "topic": "grpNew001",
    "head": {
      "mime": "application/json",
      "x-im-type": "group-join-approve"
    },
    "content": {
      "applicant": "usrInvitee001",
      "status": "accepted",
      "reviewedAt": "2026-07-31T08:00:00.000Z"
    }
  }
}
```

### 群资料与群公告

更新群名称、头像、简介：

```json
{
  "set": {
    "id": "group-profile-1",
    "topic": "grpNew001",
    "desc": {
      "public": {
        "fn": "新人交流群",
        "photo": {"ref": "/v0/file/s/group-avatar.jpg", "type": "image/jpeg"},
        "note": "欢迎交流，禁止广告。"
      }
    }
  }
}
```

更新群公告：

```json
{
  "set": {
    "id": "group-ann-1",
    "topic": "grpNew001",
    "aux": {
      "x-im-group": {
        "announcement": {
          "text": "为帮助新用户熟悉群规则，请勿发布违规内容。",
          "updatedBy": "usrOwner001",
          "updatedAt": "2026-07-31T08:00:00.000Z"
        }
      }
    }
  }
}
```

公告也可以发送一条系统样式消息，方便聊天页展示：

```json
{
  "pub": {
    "id": "group-ann-msg-1",
    "topic": "grpNew001",
    "head": {
      "mime": "application/json",
      "x-im-type": "group-announcement"
    },
    "content": {
      "text": "为帮助新用户熟悉群规则，请勿发布违规内容。"
    }
  }
}
```

### 设置管理员

原型页面：设置群管理员、添加管理员、删除管理员。

当前后端 `{set.sub.mode}` 使用绝对权限字符串，不支持 `+A`、`-A` 这类增量写法。前端需要按目标最终权限发送完整 mode；用户有效权限为 `want & given`，因此授予管理员时通常需要管理员设置目标用户的 `given`，目标用户再通过自己的 `{set.sub}` 提升 `want`。

授予管理员权限：

```json
{
  "set": {
    "id": "admin-add-1",
    "topic": "grpNew001",
    "sub": {
      "user": "usrAdmin001",
      "mode": "JRWPASD"
    }
  }
}
```

移除管理员权限：

```json
{
  "set": {
    "id": "admin-del-1",
    "topic": "grpNew001",
    "sub": {
      "user": "usrAdmin001",
      "mode": "JRWPS"
    }
  }
}
```

### 群禁言

禁言单个成员建议同时更新 ACL 与 `aux.x-im-group.mutedUsers`。第一阶段服务端会在发送消息时检查 `mutedUsers`，普通成员在列表中会被拒绝；管理员和群主不受该业务禁言影响。

```json
{
  "set": {
    "id": "mute-user-1",
    "topic": "grpNew001",
    "sub": {
      "user": "usrMuted001",
      "mode": "JRP"
    },
    "aux": {
      "x-im-group": {
        "mutedUsers": ["usrMuted001"]
      }
    }
  }
}
```

解除禁言：

```json
{
  "set": {
    "id": "unmute-user-1",
    "topic": "grpNew001",
    "sub": {
      "user": "usrMuted001",
      "mode": "JRWP"
    },
    "aux": {
      "x-im-group": {
        "mutedUsers": []
      }
    }
  }
}
```

全员禁言：

第一阶段服务端会拒绝普通成员发送消息，管理员和群主仍可发送。

```json
{
  "set": {
    "id": "mute-all-1",
    "topic": "grpNew001",
    "aux": {
      "x-im-group": {
        "muteAll": true
      }
    }
  }
}
```

### 群文件上传权限

当 `aux.x-im-group.allowMemberFileUpload=false` 时，服务端会拒绝普通成员发送 `x-im-type` 为 `image`、`audio`、`video`、`file` 的消息，或带 `extra.attachments` 的消息。管理员和群主不受限制。

```json
{
  "set": {
    "id": "group-file-policy-1",
    "topic": "grpNew001",
    "aux": {
      "x-im-group": {
        "allowMemberFileUpload": false
      }
    }
  }
}
```

### 群主转让

原型页面：选择新群主、选择新群主提示。

第一步，当前群主发起转让，把新群主的 `given` 权限设置为包含 `O` 的完整权限：

```json
{
  "set": {
    "id": "owner-transfer-1",
    "topic": "grpNew001",
    "sub": {
      "user": "usrNewOwner001",
      "mode": "JRWPASDO"
    }
  }
}
```

第二步，新群主接受转让，把自己的 `want` 权限设置为包含 `O` 的完整权限：

```json
{
  "set": {
    "id": "owner-accept-1",
    "topic": "grpNew001",
    "sub": {
      "mode": "JRWPASDO"
    }
  }
}
```

后端必须保证同一 topic 只有一个 `O` 权限用户。当前 Tinode 实际行为是：新群主接受后，服务端自动移除旧群主的 `O`，并向双方推送 `pres what="acs"`。

### 踢出群成员

```json
{
  "del": {
    "id": "kick-1",
    "topic": "grpNew001",
    "what": "sub",
    "user": "usrTarget001",
    "hard": false
  }
}
```

### 退出群聊

```json
{
  "leave": {
    "id": "leave-group-1",
    "topic": "grpNew001",
    "unsub": true
  }
}
```

## 文件、收藏与聊天记录

### 上传并发送图片

原型页面：单张图片状态、图片和语音发送中。

1. 客户端通过 `/v0/file/u/` 上传图片，获得 `ctrl.params.url`。
2. 通过 WebSocket `{pub}` 发送 Drafty 图片消息。

```json
{
  "pub": {
    "id": "pub-img-1",
    "topic": "usrPeer001",
    "head": {
      "mime": "text/x-drafty",
      "attachments": ["/v0/file/s/img001.jpg"],
      "x-im-type": "image",
      "x-im-client-mid": "local-img-1"
    },
    "content": {
      "txt": " ",
      "fmt": [{"at": -1, "len": 1, "key": 0}],
      "ent": [
        {
          "tp": "IM",
          "data": {
            "mime": "image/jpeg",
            "ref": "/v0/file/s/img001.jpg",
            "width": 1080,
            "height": 1920,
            "size": 245760
          }
        }
      ]
    }
  },
  "extra": {
    "attachments": ["/v0/file/s/img001.jpg"]
  }
}
```

### 发送普通文件

原型页面：文件发送状态、文件下载、文件打开。

```json
{
  "pub": {
    "id": "pub-file-1",
    "topic": "usrPeer001",
    "head": {
      "mime": "text/x-drafty",
      "attachments": ["/v0/file/s/doc001.pdf"],
      "x-im-type": "file"
    },
    "content": {
      "txt": "365天天高清晰记忆曲线复习_pdf",
      "fmt": [{"at": -1, "len": 0, "key": 0}],
      "ent": [
        {
          "tp": "EX",
          "data": {
            "mime": "application/pdf",
            "ref": "/v0/file/s/doc001.pdf",
            "name": "365天天高清晰记忆曲线复习_pdf",
            "size": 115000
          }
        }
      ]
    }
  },
  "extra": {
    "attachments": ["/v0/file/s/doc001.pdf"]
  }
}
```

### 发送语音消息

```json
{
  "pub": {
    "id": "pub-audio-1",
    "topic": "usrPeer001",
    "head": {
      "mime": "text/x-drafty",
      "attachments": ["/v0/file/s/audio001.m4a"],
      "x-im-type": "audio"
    },
    "content": {
      "txt": " ",
      "fmt": [{"at": -1, "len": 1, "key": 0}],
      "ent": [
        {
          "tp": "AU",
          "data": {
            "mime": "audio/mp4",
            "ref": "/v0/file/s/audio001.m4a",
            "duration": 6000,
            "name": "voice.m4a",
            "size": 48000
          }
        }
      ]
    }
  },
  "extra": {
    "attachments": ["/v0/file/s/audio001.m4a"]
  }
}
```

### 群文件列表

群文件是群消息附件的业务视图。二期 MySQL 后端已建立 `im_message_index`，带 `x-im-filter` 或 `x-im-search` 的 `{get data}` 会优先走索引查询；其它未实现索引的数据库后端仍回退到一阶段内存过滤。

扩展查询：

```json
{
  "get": {
    "id": "group-files-1",
    "topic": "grpNew001",
    "what": "data",
    "data": {
      "limit": 50
    },
    "x-im-filter": {
      "types": ["file"],
      "keyword": "复习"
    }
  }
}
```

### 收藏消息

原型页面：我的收藏、收藏文本、收藏文件、收藏语音、收藏链接。

建议收藏使用 `slf` topic 存储，`head.x-im-type="favorite"`，原始消息定位放在内容里。

```json
{
  "pub": {
    "id": "fav-1",
    "topic": "slf",
    "head": {
      "mime": "application/json",
      "x-im-type": "favorite"
    },
    "content": {
      "sourceTopic": "grpNew001",
      "sourceSeq": 19,
      "kind": "file",
      "title": "365天天高清晰记忆曲线复习_pdf",
      "summary": "PDF 115KB",
      "collectedAt": "2026-07-31T08:00:00.000Z"
    }
  }
}
```

获取收藏：

```json
{
  "sub": {
    "id": "fav-list-1",
    "topic": "slf",
    "get": {
      "what": "data",
      "data": {"limit": 50}
    }
  }
}
```

### 查找聊天记录

原型页面：查看聊天记录-全部、图片、视频、文件、链接、搜索关键词。

Tinode 原生 `{get what="data"}` 支持按 `seq` 分页，不直接支持关键词搜索。关键词、类型搜索需要后端扩展索引。
二期以后 MySQL 后端会优先查询 `im_message_index`；当前 schema `119` 对 `search_text` 增加 `FULLTEXT` 索引，同时保留 `LIKE` fallback，避免中文短词或未命中全文分词时漏查。

```json
{
  "get": {
    "id": "search-msg-1",
    "topic": "usrPeer001",
    "what": "data",
    "data": {"limit": 50},
    "x-im-search": {
      "keyword": "装修",
      "types": ["text", "image", "file", "link"],
      "before": 0
    }
  }
}
```

## 语音、视频与通话

### 发起语音通话

原型页面：语音通话-对方待接受状态、双方语音沟通中。

Tinode 原生通话流程为：先用 `{pub}` 发送 `head.webrtc="started"` 的通话邀请并持久化一条通话消息；后续信令用 `{note what="call"}`。本产品在通话消息内容与 `note.payload` 中约定 `callId`、`callType`。

后端校验规则：显式发送 `head.x-im-type="call"` 且 `head.webrtc="started"` 的产品通话邀请，`content.callId` 必填，否则返回 `400 malformed`。`ringing`、`accept`、`hang-up` 控制事件的 `payload.callId` 必填；`offer`、`answer`、`ice-candidate` 仍按 Tinode 原生 WebRTC 信令透传，避免破坏 SDP/ICE 结构。

```json
{
  "pub": {
    "id": "call-audio-1",
    "topic": "usrPeer001",
    "head": {
      "mime": "application/json",
      "webrtc": "started",
      "x-im-type": "call"
    },
    "content": {
      "callId": "call-001",
      "callType": "audio",
      "audio": true,
      "video": false
    }
  }
}
```

### 发起视频通话

```json
{
  "pub": {
    "id": "call-video-1",
    "topic": "usrPeer001",
    "head": {
      "mime": "application/json",
      "webrtc": "started",
      "x-im-type": "call"
    },
    "content": {
      "callId": "call-002",
      "callType": "video",
      "audio": true,
      "video": true,
      "cameraOn": true
    }
  }
}
```

### 接受、拒绝、挂断

接受：

```json
{
  "note": {
    "topic": "usrPeer001",
    "what": "call",
    "event": "accept",
    "seq": 102,
    "payload": {
      "callId": "call-002"
    }
  }
}
```

拒绝或挂断使用 Tinode 原生 `hang-up` 事件；通话尚未接通时服务端会把最终消息标记为 declined/missed。

```json
{
  "note": {
    "topic": "usrPeer001",
    "what": "call",
    "event": "hang-up",
    "seq": 102,
    "payload": {
      "callId": "call-002",
      "reason": "user_declined"
    }
  }
}
```

挂断：

```json
{
  "note": {
    "topic": "usrPeer001",
    "what": "call",
    "event": "hang-up",
    "seq": 102,
    "payload": {
      "callId": "call-002",
      "duration": 65000
    }
  }
}
```

### 通话状态消息

通话结束后发送一条持久消息用于聊天记录展示。

```json
{
  "pub": {
    "id": "call-record-1",
    "topic": "usrPeer001",
    "head": {
      "mime": "application/json",
      "webrtc": "finished",
      "webrtc-duration": 65000,
      "x-im-type": "call"
    },
    "content": {
      "callId": "call-002",
      "callType": "video",
      "status": "finished",
      "duration": 65000
    }
  }
}
```

### SDP 与 ICE 信令

通话被接受后，WebRTC 元数据使用 Tinode 原生 `offer`、`answer`、`ice-candidate` 事件转发。麦克风、扬声器、摄像头开关属于本地 UI 状态；如后续需要跨端同步，应在 `server/calls.go` 明确扩展事件白名单。

```json
{
  "note": {
    "topic": "usrPeer001",
    "what": "call",
    "event": "ice-candidate",
    "seq": 102,
    "payload": {
      "callId": "call-002",
      "candidate": "candidate:..."
    }
  }
}
```

## 话题功能

话题不是 Tinode 原生 topic 的“群聊 topic”，而是产品信息流/活动报名类业务。建议实现为频道 `chn`，每个话题详情页对应一个频道 topic；话题列表由 `fnd` 搜索或专用系统频道承载。

### 发布话题

原型页面：发布话题、话题类型选择、话题人数、积分不足。

二期 MySQL 后端已接入话题发布积分扣减：创建 `nch` 频道时，如果 `public.x-im-topic.pointsCost` 大于 `0`，服务端会在同一事务中创建话题、创建作者订阅并扣减 `im_user_points.balance`。余额不足返回 `422 policy violation`，话题不会创建；普通群聊 `{sub topic="new"}` 不受该规则影响。

```json
{
  "sub": {
    "id": "topic-create-1",
    "topic": "nch",
    "set": {
      "desc": {
        "defacs": {"auth": "R", "anon": "N"},
        "public": {
          "fn": "国防办举行高质量完成十四五规划系列主题新闻发布会",
          "photo": {"ref": "/v0/file/s/topic-cover.jpg", "type": "image/jpeg"},
          "note": "话题摘要内容",
          "x-im-topic": {
            "type": "news",
            "labels": ["美食", "天气"],
            "durationHours": 3,
            "participantLimit": 20,
            "pointsCost": 234,
            "joinEnabled": true
          }
        }
      },
      "tags": ["topic", "topic:news", "美食", "天气"],
      "aux": {
        "x-im-topic": {
          "participants": [],
          "status": "open"
        }
      }
    },
    "get": {"what": "desc aux"}
  }
}
```

### 获取话题列表

```json
{
  "set": {
    "id": "topic-search-1",
    "topic": "fnd",
    "desc": {
      "public": "topic news"
    }
  }
}
```

```json
{"get":{"id":"topic-search-2","topic":"fnd","what":"sub","sub":{"limit":20}}}
```

### 推荐话题列表

推荐排序仍复用 Tinode `fnd` topic，通过 `{get what="sub"}` 附带 `x-im-recommend` 传入推荐条件。MySQL 后端当前按关键词、话题类型、标签与订阅数做轻量排序；频道型话题会按 Tinode 规范以 `chnXXX` 返回。

```json
{
  "get": {
    "id": "topic-recommend-1",
    "topic": "fnd",
    "what": "sub",
    "sub": {"limit": 20},
    "x-im-recommend": {
      "keyword": "发布会",
      "types": ["news"],
      "labels": ["美食"],
      "limit": 10
    }
  }
}
```

响应示例：

```json
{
  "meta": {
    "id": "topic-recommend-1",
    "topic": "fnd",
    "sub": [
      {
        "topic": "chnTopic001",
        "public": {
          "fn": "本周美食发布会",
          "x-im-topic": {
            "type": "news",
            "labels": ["美食", "活动"]
          }
        },
        "private": ["topic", "topic:news", "美食"],
        "subcnt": 128
      }
    ]
  }
}
```

### 参与话题

话题详情页点击“参与话题”时订阅频道。

```json
{
  "sub": {
    "id": "topic-join-1",
    "topic": "chnTopic001",
    "set": {
      "sub": {"mode": "R"}
    },
    "get": {"what": "desc data aux"}
  }
}
```

若要发送评论，需要后端根据业务授予 `W` 权限。

### 转发帖子

```json
{
  "pub": {
    "id": "topic-forward-1",
    "topic": "usrPeer001",
    "head": {
      "mime": "application/json",
      "x-im-type": "topic-share"
    },
    "content": {
      "topic": "chnTopic001",
      "title": "国防办举行高质量完成十四五规划系列主题新闻发布会",
      "cover": "/v0/file/s/topic-cover.jpg",
      "summary": "话题摘要内容"
    }
  }
}
```

## 系统消息、举报与安全提示

### 系统消息

系统消息建议使用 `sys` topic 或专用系统账号向用户 P2P 发送。客户端消息列表可将系统账号展示为“系统消息”。

```json
{
  "data": {
    "topic": "usrSystem001",
    "from": "usrSystem001",
    "seq": 1,
    "head": {
      "mime": "application/json",
      "x-im-type": "system-notice"
    },
    "content": {
      "title": "平台整治净化治理公告",
      "summary": "国防办举行高质量完成十四五规划系列...",
      "url": "/notice/20260731"
    },
    "ts": "2026-07-31T08:00:00.000Z"
  }
}
```

### 举报

原型页面：举报、举报原因列表。

普通用户可向 `sys` 发布举报内容。

```json
{
  "pub": {
    "id": "report-1",
    "topic": "sys",
    "head": {
      "mime": "application/json",
      "x-im-type": "report"
    },
    "content": {
      "targetType": "message",
      "targetUser": "usrBad001",
      "targetTopic": "grpNew001",
      "targetSeq": 19,
      "reason": "发布违法违规内容",
      "description": "群成员发布诈骗信息",
      "evidence": ["/v0/file/s/evidence001.jpg"]
    }
  },
  "extra": {
    "attachments": ["/v0/file/s/evidence001.jpg"]
  }
}
```

### 反诈与安全提醒

反诈弹窗可由服务端在消息 `head` 上标记，前端收到后根据策略展示一次或二次确认。当前后端已实现轻量规则 MVP：疑似转账、验证码、外链、违禁词等命中后不阻断消息，只追加风险和审核标记，便于前端提示与后台后续处理。

```json
{
  "data": {
    "topic": "usrPeer001",
    "from": "usrPeer001",
    "seq": 20,
    "head": {
      "mime": "text/x-drafty",
      "x-im-type": "text",
      "x-im-anti-fraud": true,
      "x-im-risk-level": "high",
      "x-im-moderation": {
        "status": "flagged",
        "reasons": ["payment-scam", "credential-risk", "external-link"],
        "reviewedAt": "2026-07-31T08:00:00.000Z"
      }
    },
    "content": {"txt": "请点击链接完成转账"},
    "ts": "2026-07-31T08:00:00.000Z"
  }
}
```

客户端确认提醒后可发送临时回执：

```json
{
  "note": {
    "topic": "usrPeer001",
    "what": "data",
    "payload": {
      "x-im-event": "anti-fraud-confirmed",
      "seq": 20
    }
  }
}
```

## 个人中心与设置

### 获取个人资料

```json
{"get":{"id":"profile-1","topic":"me","what":"desc tags cred"}}
```

### 修改昵称、头像、生日、地区、个性签名

```json
{
  "set": {
    "id": "profile-update-1",
    "topic": "me",
    "desc": {
      "public": {
        "fn": "林南",
        "photo": {"ref": "/v0/file/s/avatar.jpg", "type": "image/jpeg"},
        "note": "成人最懂什么都没留下",
        "x-im-gender": "female",
        "x-im-birthday": "2008-02-07",
        "x-im-area": "广东省广州市"
      }
    }
  },
  "extra": {
    "attachments": ["/v0/file/s/avatar.jpg"]
  }
}
```

### 置顶、免打扰、清空聊天记录

置顶写入 `me.private.tpins` 或当前 topic `private.x-im-pinned`。

```json
{
  "set": {
    "id": "pin-1",
    "topic": "usrPeer001",
    "desc": {
      "private": {
        "x-im-pinned": true
      }
    }
  }
}
```

免打扰：

```json
{
  "set": {
    "id": "mute-topic-1",
    "topic": "usrPeer001",
    "desc": {
      "private": {
        "x-im-muted": true
      }
    }
  }
}
```

清空聊天记录：

```json
{
  "del": {
    "id": "clear-local-1",
    "topic": "usrPeer001",
    "what": "msg",
    "hard": false,
    "delseq": [{"low": 1, "hi": 2147483647}]
  }
}
```

### 隐私设置

原型页面：隐私设置-添加我的方式选项。

```json
{
  "set": {
    "id": "privacy-1",
    "topic": "me",
    "desc": {
      "private": {
        "x-im-settings": {
          "allowSearchByCard": true,
          "allowSearchByQr": true,
          "allowSearchByGroup": true,
          "allowSearchByPhone": false,
          "joinGroupNeedsApproval": true
        }
      }
    }
  }
}
```

### 青少年模式

```json
{
  "set": {
    "id": "teen-1",
    "topic": "me",
    "desc": {
      "private": {
        "x-im-settings": {
          "teenMode": true,
          "teenModeEnabledAt": "2026-07-31T08:00:00.000Z"
        }
      }
    }
  }
}
```

### 签到任务

签到属于业务扩展，使用 `slf` topic 记录用户行为，同时后端更新积分系统。

二期 MySQL 后端已接入 `head.x-im-type="checkin"` 的 `{pub}` 处理：同一用户、同一自然日、同一 `event_type` 只记录一次，首次签到成功后固定增加 `5` 积分并保存一条 `slf` 消息；重复签到返回 `304 no action`，不重复加分，也不保存重复消息。前后端通信仍保持 WebSocket `{pub}` 形态。

```json
{
  "pub": {
    "id": "checkin-1",
    "topic": "slf",
    "head": {
      "mime": "application/json",
      "x-im-type": "checkin"
    },
    "content": {
      "date": "2026-07-31",
      "points": 5
    }
  }
}
```

重复签到响应示例：

```json
{
  "ctrl": {
    "id": "checkin-1",
    "topic": "slf",
    "code": 304,
    "text": "no action",
    "params": {
      "x-im-checkin": {
        "already": true,
        "date": "2026-07-31",
        "points": 5,
        "balance": 35
      }
    }
  }
}
```

### 意见反馈

```json
{
  "pub": {
    "id": "feedback-1",
    "topic": "sys",
    "head": {
      "mime": "application/json",
      "x-im-type": "feedback"
    },
    "content": {
      "type": "功能建议",
      "text": "希望优化消息搜索",
      "images": ["/v0/file/s/feedback001.jpg"]
    }
  },
  "extra": {
    "attachments": ["/v0/file/s/feedback001.jpg"]
  }
}
```

## 错误码与状态码

Tinode `{ctrl.code}` 遵循 HTTP 状态码模型。

| code | 含义 | 前端处理 |
|---|---|---|
| `200` | 成功 | 更新本地状态 |
| `201` | 已创建 | 使用返回的 `topic` 或 `params` |
| `300` | 需要额外验证 | 展示验证码/身份验证页面 |
| `400` | 请求格式错误 | 检查 JSON 和字段 |
| `401` | 未登录或 Token 失效 | 重新登录 |
| `403` | 无权限 | 展示“无权限”或禁言/拉黑提示 |
| `404` | 资源不存在 | 提示用户不存在、群不存在 |
| `409` | 状态冲突 | 已申请、已加入、重复操作 |
| `413` | 消息或文件过大 | 提示压缩或重新选择 |
| `423` | Topic 锁定/处理中 | 稍后重试 |
| `500` | 服务端错误 | 展示通用错误并上报 |
| `503` | 队列满或服务不可用 | 自动重试或稍后重试 |

### 业务状态枚举

| 字段 | 值 | 含义 |
|---|---|---|
| `x-im-type` | `text` | 文本 |
| `x-im-type` | `image` | 图片 |
| `x-im-type` | `audio` | 语音 |
| `x-im-type` | `video` | 视频 |
| `x-im-type` | `file` | 文件 |
| `x-im-type` | `card` | 名片 |
| `x-im-type` | `favorite` | 收藏 |
| `x-im-type` | `forward-bundle` | 合并转发 |
| `x-im-type` | `group-join-apply` | 加群申请 |
| `x-im-type` | `group-join-approve` | 加群审批通过 |
| `x-im-type` | `group-join-reject` | 加群审批拒绝 |
| `x-im-type` | `group-announcement` | 群公告 |
| `x-im-type` | `call` | 通话记录 |
| `x-im-type` | `topic-share` | 话题分享 |
| `x-im-type` | `system-notice` | 系统通知 |
| `x-im-type` | `report` | 举报 |
| `x-im-type` | `feedback` | 意见反馈 |
| `x-im-type` | `checkin` | 签到 |

### 前端发送状态建议

| UI 状态 | 判定方式 |
|---|---|
| 发送中 | 本地消息已入队，尚未收到 `{ctrl}` 或 `{data}` echo |
| 发送成功 | 收到同 `id` 的 `{ctrl.code=200}` 或同 `x-im-client-mid` 的 `{data}` |
| 发送失败 | 收到 `{ctrl.code>=400}` 或超时 |
| 已送达 | 收到对端 `{info.what="recv"}` |
| 已读 | 收到对端 `{info.what="read"}` |
| 已撤回 | 收到 `{pres.what="del"}` 或 `{meta.del}` 包含对应 `seq` |

## 后端实现提示

1. 原生 Tinode 已支持的字段优先复用：`public`、`private`、`aux`、`head.mentions`、`head.reply`、`head.replace`、`head.forwarded`、`extra.attachments`。
2. 业务扩展统一从 `x-im-*` 读取和写入，避免污染 Tinode 原生字段。
3. 需要服务端索引的功能包括：聊天记录关键词搜索、按附件类型搜索、收藏分类、话题列表、积分扣减、反诈风险标记。
4. 所有 WebSocket 消息必须是严格 JSON，示例中的字段名和字符串在真实请求中都需要双引号。
5. 文件上传仍使用 Tinode 大文件接口；上传后的文件引用必须写入 `extra.attachments`，否则服务端 GC 可能清理未引用文件。
6. Phase 3 当前为后端内置 MVP：反诈和内容审核只做规则标记，推荐只做 MySQL 轻量排序，复杂模型、人工审核工作台、异步搜索服务仍可后续独立演进。