From 2f8ded104d61c2df3e496bbbc77fb8f607fcf8f7 Mon Sep 17 00:00:00 2001 From: Austin Date: Tue, 29 Sep 2026 09:53:24 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=8D=95=E8=81=8A?= =?UTF-8?q?=E5=B7=B2=E8=AF=BB/=E5=B7=B2=E6=94=B6=E5=9B=9E=E6=89=A7?= =?UTF-8?q?=E5=8D=8F=E8=AE=AE=E7=BA=A6=E5=AE=9A=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/IM-前后端对接文档.md | 8 ++++++++ docs/对接文档最新/IM-前后端对接文档.md | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/docs/IM-前后端对接文档.md b/docs/IM-前后端对接文档.md index 2c2e724..449c766 100644 --- a/docs/IM-前后端对接文档.md +++ b/docs/IM-前后端对接文档.md @@ -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 资料、个人群设置和标签 | 场景 | 客户端发送 | 服务端返回/下行示例 | diff --git a/docs/对接文档最新/IM-前后端对接文档.md b/docs/对接文档最新/IM-前后端对接文档.md index 27b2b26..2d339c7 100644 --- a/docs/对接文档最新/IM-前后端对接文档.md +++ b/docs/对接文档最新/IM-前后端对接文档.md @@ -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 资料、个人群设置和标签 | 场景 | 客户端发送 | 服务端返回/下行示例 |