pro/im_server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 添加单聊已读/已收回执协议约定文档

Browse Source
This commit is contained in:
Austin
2026-09-29 09:53:24 +08:00
parent 1ff0894205
commit 2f8ded104d
2 changed files with 16 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/IM-前后端对接文档.md
+8
View File
@@ -398,6 +398,14 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
`kp/kpa/kpv` 只表示输入态、录音态、视频输入态等短暂 UI 状态，不能作为长连接心跳。长连接保活必须依赖 0.5.1.1 中的 WebSocket Ping/Pong。
**单聊已读/已收回执协议约定（服务端已验证，2026-09-29）：**
1. **在线下行形态**：`info.topic` 为话题名（如 `p2p...`），`info.from` 为报读者，`info.what` 为 `recv`/`read`，`info.seq` 为水位。服务端跳过上报会话自身，推送给对端及本人其他在线设备（多 Pod 部署经 Kafka 同步，各 Pod 均会下发）。
2. **离线补发形态**：接收方离线时收到 `{"info":{"topic":"me","src":"p2p...","from":"usr...","what":"recv","seq":12}}`，即 `topic` 固定为 `me`、`src` 才是话题名。客户端必须同时兼容上述两种形态。
3. **序号单调递增**：服务端丢弃 `seq` 不大于当前水位的回执（`read`、`recv` 各自独立判断），`read` 回执会同步抬升 `recv`，恒有 `read ≥ recv`。客户端渲染一律取服务端最大游标，禁止用本地计数覆盖服务端值。
4. **断线重连恢复**：`sub`/`get desc` 响应的 `desc` 中包含 `seq`、`read`、`recv`、`clear` 四个游标；`get {"what":"sub"}` 也返回各成员的 `read/recv`。重连后以这些游标恢复本地状态，不要依赖进程内存。
5. **换设备登录**：回执水位按「用户 × 话题」在服务端持久化，与设备无关；新设备订阅后 `desc` 同时返回自己与对端的最新 `read/recv`，可完整恢复对方"已读/已收"状态。发送者自身的 `read/recv` 由服务端自动推进到其最新发出的 `seq`。
##### 0.5.4.5 Topic 资料、个人群设置和标签
| 场景 | 客户端发送 | 服务端返回/下行示例 |
docs/对接文档最新/IM-前后端对接文档.md
+8
View File
@@ -357,6 +357,14 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
| 删除单条/多条消息 | `{"del":{"id":"del-1","topic":"grp...","what":"msg","delseq":[{"low":12,"hi":13}],"hard":false}}` | `{"ctrl":{"id":"del-1","code":200,"text":"ok","params":{"del":3}}}`；其他端可能收到 `{"pres":{"topic":"grp...","what":"del","seq":3}}` |
| 清空当前用户视图 | `{"del":{"id":"del-all-1","topic":"p2p...","what":"msg","delseq":[{"low":1,"hi":126}],"hard":false}}` | `{"ctrl":{"id":"del-all-1","code":200,"text":"ok","params":{"del":4}}}` |
**单聊已读/已收回执协议约定（服务端已验证，2026-09-29）：**
1. **在线下行形态**：`info.topic` 为话题名（如 `p2p...`），`info.from` 为报读者，`info.what` 为 `recv`/`read`，`info.seq` 为水位。服务端跳过上报会话自身，推送给对端及本人其他在线设备（多 Pod 部署经 Kafka 同步，各 Pod 均会下发）。
2. **离线补发形态**：接收方离线时收到 `{"info":{"topic":"me","src":"p2p...","from":"usr...","what":"recv","seq":12}}`，即 `topic` 固定为 `me`、`src` 才是话题名。客户端必须同时兼容上述两种形态。
3. **序号单调递增**：服务端丢弃 `seq` 不大于当前水位的回执（`read`、`recv` 各自独立判断），`read` 回执会同步抬升 `recv`，恒有 `read ≥ recv`。客户端渲染一律取服务端最大游标，禁止用本地计数覆盖服务端值。
4. **断线重连恢复**：`sub`/`get desc` 响应的 `desc` 中包含 `seq`、`read`、`recv`、`clear` 四个游标；`get {"what":"sub"}` 也返回各成员的 `read/recv`。重连后以这些游标恢复本地状态，不要依赖进程内存。
5. **换设备登录**：回执水位按「用户 × 话题」在服务端持久化，与设备无关；新设备订阅后 `desc` 同时返回自己与对端的最新 `read/recv`，可完整恢复对方"已读/已收"状态。发送者自身的 `read/recv` 由服务端自动推进到其最新发出的 `seq`。
##### 0.5.4.5 Topic 资料、个人群设置和标签
| 场景 | 客户端发送 | 服务端返回/下行示例 |