From 1a8043bee238eacf89a06c99d4f26d5231e13b05 Mon Sep 17 00:00:00 2001 From: Austin Date: Tue, 29 Sep 2026 11:08:48 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20IM=20=E6=B6=88?= =?UTF-8?q?=E6=81=AF=E5=8E=86=E5=8F=B2=E5=88=86=E9=A1=B5=E7=9A=84=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=E7=BA=A6=E5=AE=9A=E5=92=8C=E5=90=91=E4=B8=8A=E7=BF=BB?= =?UTF-8?q?=E9=A1=B5=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补充向上翻页加载更早历史的参数约定，明确 REST 消息接口为空占位禁止使用，历史分页统一走 WebSocket 的 get data 接口，同步更新接口文档说明。 --- docs/IM-前后端对接文档.md | 4 +++- docs/对接文档最新/IM-前后端对接文档.md | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/IM-前后端对接文档.md b/docs/IM-前后端对接文档.md index cd933b4..f11fd04 100644 --- a/docs/IM-前后端对接文档.md +++ b/docs/IM-前后端对接文档.md @@ -236,6 +236,8 @@ WebSocket Upgrade 阶段由 `server/hdl_websock.go` 先调用 `checkAPIKey`。 {"sub":{"id":"sub-topic-1","topic":"grp...","get":{"what":"desc sub data del","data":{"since":125,"limit":50},"del":{"since":1,"limit":50}}}} ``` +**向上翻页（加载更早历史）最终参数约定（后端已确认，2026-09-29）**：复用同一 `get data`，最终参数为 `before`（排他上界，返回 `seq < before`），**没有 REST cursor 语义**。聊天页滚动到顶部时发 `data:{"before":<当前已加载最小 seq>,"limit":50}`（`since` 可省略，默认 0）。服务端返回该锚点之前**最接近 `before` 的 `limit` 条**，`{data}` 按 `seq` 从大到小下发（首条即锚点前最新一条）；收到 `ctrl 204 no content`（`params.what=="data"`）表示已到会话顶部。`data` 参数全集：`since`（含下界）、`before`（排他上界）、`limit`、`ranges`。P2P 与群聊（含热缓存 fallback）语义一致。REST `GET /v1/im/conversations/{topic}/messages` 当前为空占位（见 4.21.1），不得用于历史分页。 + 订阅成功后才允许 `{pub}`、`note read/recv` 等会话操作。断线恢复必须重新执行 `WebSocket Upgrade -> hi -> token login -> sub me -> 恢复 Topic`，同一连接内不得跳过 `hi` 或切换企业码。 ##### 0.5.1.1 WebSocket 心跳与在线状态 @@ -1425,7 +1427,7 @@ X-MeetingIM-APIKey: <预置的普通 API Key> | `POST /v1/im/conversations/p2p` | `{"peer_user_id":"usr..."}` | `{"topic":"p2p...","relationship":"friend","can_send":true}` | | `GET /v1/im/conversations/{topic}/settings` | Path topic | `{"pinned":false,"mute_notifications":false,"message_retention":"default","blocked":false,"remark":"","version":1,"permissions":{"can_update":true}}` | | `PATCH /v1/im/conversations/{topic}/settings` | `{"pinned":true,"mute_notifications":false,"version":1}` | `{"pinned":true,"mute_notifications":false,"message_retention":"default","blocked":false,"remark":"","version":2}` | -| `GET /v1/im/conversations/{topic}/messages` | Query `?since=12&limit=20` | `{"topic":"p2p...","items":[{"seq":13,"from":"usr...","ts":"2026-08-20T09:00:00Z","head":{"x-im-type":"text"},"content":{"text":"你好"}}],"next_cursor":""}` | +| `GET /v1/im/conversations/{topic}/messages` | **服务端当前为空占位**：GET 恒返回空列表，勿用 `?since=&limit=` 调它；历史消息（首屏与向上翻页）一律走 WS `get data` 的 `since`/`before`/`limit`（向上翻页见 0.5.1 约定） | `{"topic":"p2p...","items":[],"next_cursor":"","has_more":false}` | | `PUT /v1/im/topics/{topic}/draft` 待实现 | `{"content":"未发送草稿","version":1}` | `{"topic":"grp...","content":"未发送草稿","version":2,"updated_at":"2026-08-20T09:00:00Z"}` | | `POST /v1/im/topics/{topic}/messages/{seq}/recall` | 单条撤回；`topic` 可传 `p2p...` 或 `grp...`；Body `{}`，可选 `{"version":1,"reason":"mistake"}` | `{"topic":"grp...","seq":12,"status":"recalled","version":2,"updated_at":"2026-08-20T09:00:00Z"}` | | `POST /v1/im/topics/{topic}/messages/recall` | 多选批量撤回；`{"items":[{"seq":12,"version":1},{"seq":13}],"reason":"mistake"}`；`items` 1～50 条，`version` 可选 | `{"topic":"grp...","items":[{"topic":"grp...","seq":12,"status":"recalled","version":2,"updated_at":"2026-08-20T09:00:00Z"},{"seq":13,"status":"failed","http":409,"code":30006,"reason":"VERSION_CONFLICT","message":"message version conflict"}]}` | diff --git a/docs/对接文档最新/IM-前后端对接文档.md b/docs/对接文档最新/IM-前后端对接文档.md index 5b5137b..4321f23 100644 --- a/docs/对接文档最新/IM-前后端对接文档.md +++ b/docs/对接文档最新/IM-前后端对接文档.md @@ -210,6 +210,8 @@ WebSocket Upgrade 阶段由 `server/hdl_websock.go` 先调用 `checkAPIKey`。 {"sub":{"id":"sub-topic-1","topic":"grp...","get":{"what":"desc sub data del","data":{"since":125,"limit":50},"del":{"since":1,"limit":50}}}} ``` +**向上翻页（加载更早历史）最终参数约定（后端已确认，2026-09-29）**：复用同一 `get data`，最终参数为 `before`（排他上界，返回 `seq < before`），**没有 REST cursor 语义**。聊天页滚动到顶部时发 `data:{"before":<当前已加载最小 seq>,"limit":50}`（`since` 可省略，默认 0）。服务端返回该锚点之前**最接近 `before` 的 `limit` 条**，`{data}` 按 `seq` 从大到小下发（首条即锚点前最新一条）；收到 `ctrl 204 no content`（`params.what=="data"`）表示已到会话顶部。`data` 参数全集：`since`（含下界）、`before`（排他上界）、`limit`、`ranges`。P2P 与群聊（含热缓存 fallback）语义一致。REST `GET /v1/im/conversations/{topic}/messages` 当前为空占位（见 4.21.1），不得用于历史分页。 + 订阅成功后才允许 `{pub}`、`note read/recv` 等会话操作。断线恢复必须重新执行 `WebSocket Upgrade -> hi -> token login -> sub me -> 恢复 Topic`，同一连接内不得跳过 `hi` 或切换企业码。 #### 0.5.2 Long Polling 兼容流程：先取得的是 sid @@ -1389,7 +1391,7 @@ X-MeetingIM-APIKey: <预置的普通 API Key> | `POST /v1/im/conversations/p2p` | `{"peer_user_id":"usr..."}` | `{"topic":"p2p...","relationship":"friend","can_send":true}` | | `GET /v1/im/conversations/{topic}/settings` | Path topic | `{"pinned":false,"mute_notifications":false,"message_retention":"default","blocked":false,"remark":"","version":1,"permissions":{"can_update":true}}` | | `PATCH /v1/im/conversations/{topic}/settings` | `{"pinned":true,"mute_notifications":false,"version":1}` | `{"pinned":true,"mute_notifications":false,"message_retention":"default","blocked":false,"remark":"","version":2}` | -| `GET /v1/im/conversations/{topic}/messages` | Query `?since=12&limit=20` | `{"topic":"p2p...","items":[{"seq":13,"from":"usr...","ts":"2026-08-20T09:00:00Z","head":{"x-im-type":"text"},"content":{"text":"你好"}}],"next_cursor":""}` | +| `GET /v1/im/conversations/{topic}/messages` | **服务端当前为空占位**：GET 恒返回空列表，勿用 `?since=&limit=` 调它；历史消息（首屏与向上翻页）一律走 WS `get data` 的 `since`/`before`/`limit`（向上翻页见 0.5.1 约定） | `{"topic":"p2p...","items":[],"next_cursor":"","has_more":false}` | | `PUT /v1/im/topics/{topic}/draft` 待实现 | `{"content":"未发送草稿","version":1}` | `{"topic":"grp...","content":"未发送草稿","version":2,"updated_at":"2026-08-20T09:00:00Z"}` | | `POST /v1/im/topics/{topic}/messages/{seq}/recall` | 单条撤回；`topic` 可传 `p2p...` 或 `grp...`；Body `{}`，可选 `{"version":1,"reason":"mistake"}` | `{"topic":"grp...","seq":12,"status":"recalled","version":2,"updated_at":"2026-08-20T09:00:00Z"}` | | `POST /v1/im/topics/{topic}/messages/recall` | 多选批量撤回；`{"items":[{"seq":12,"version":1},{"seq":13}],"reason":"mistake"}`；`items` 1～50 条，`version` 可选 | `{"topic":"grp...","items":[{"topic":"grp...","seq":12,"status":"recalled","version":2,"updated_at":"2026-08-20T09:00:00Z"},{"seq":13,"status":"failed","http":409,"code":30006,"reason":"VERSION_CONFLICT","message":"message version conflict"}]}` |