From 64a5849a3d1b597884d89b4c244f82dae9404350 Mon Sep 17 00:00:00 2001
From: "DESKTOP-L8OUL9F\\gfl0034" <1003614916@qq.com>
Date: Sun, 18 Oct 2026 20:26:18 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=85=AC=E5=BC=80=E8=A7=84=E8=8C=83?=
 =?UTF-8?q?=E8=A1=A5=E9=BD=90=E5=91=BD=E4=BB=A4=208=20=E7=9A=84=E5=B7=B2?=
 =?UTF-8?q?=E8=AF=BB=E8=AF=B7=E6=B1=82=E4=B8=8E=E6=88=90=E5=8A=9F=E5=93=8D?=
 =?UTF-8?q?=E5=BA=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

线上已接受 last_msg_id，文档命令表此前跳过第 8 行。

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 internal/transport/http/docs/openapi.yaml | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/internal/transport/http/docs/openapi.yaml b/internal/transport/http/docs/openapi.yaml
index 0ffab20..6820fb6 100644
--- a/internal/transport/http/docs/openapi.yaml
+++ b/internal/transport/http/docs/openapi.yaml
@@ -173,6 +173,7 @@ info:
     <tr><td>5</td><td>SEND_ACK</td><td>服务端 → 客户端</td><td>—</td><td>仅作 4 的应答</td></tr>
     <tr><td>6</td><td>MESSAGE</td><td>服务端 → 客户端</td><td>—</td><td>envelope，<code>data</code> 为消息 Item（<code>msg_id</code> / <code>content</code> / …）</td></tr>
     <tr><td>7</td><td>PUSH_ACK</td><td>客户端 → 服务端</td><td>空；<code>SequenceID</code>=推送帧的 SequenceID</td><td>无业务响应</td></tr>
+    <tr><td>8</td><td>READ</td><td>客户端 → 服务端</td><td><strong>不是 envelope</strong>：<code>conversation_id</code>，以及 <code>msg_id</code> 或 <code>last_msg_id</code>（任一大于 0；两者都大于 0 时用 <code>msg_id</code>）</td><td>同 8，envelope，<code>code</code> 为 <code>"0"</code>，<code>data</code>=<code>{"conversation_id","msg_id"}</code>。<code>data.msg_id</code> 是落库后的 <code>last_read_msg_id</code>（只增不减），并清该成员 Redis 未读</td></tr>
     <tr><td>9</td><td>RECALL</td><td>客户端 → 服务端</td><td><code>{"msg_id"}</code></td><td>同 9，envelope</td></tr>
     <tr><td>10</td><td>SYNC_INBOX</td><td>客户端 → 服务端</td><td><code>{"mailbox_seq","dialog_score","limit"}</code>，均可 0</td><td>同 10，<code>data.dialogs</code> / <code>mailbox</code> / 游标</td></tr>
     <tr><td>12</td><td>SYNC_MESSAGES</td><td>客户端 → 服务端</td><td><code>{"conversation_id","last_msg_id","limit"}</code></td><td>同 12，<code>data.items</code> / <code>has_more</code></td></tr>
@@ -3557,12 +3558,13 @@ components:
         Frame.Command：1 AUTH 2 HEARTBEAT 3 GENERATE_MSG_ID 4 SEND_MESSAGE 5 SEND_ACK
         6 MESSAGE 7 PUSH_ACK 8 READ 9 RECALL 10 SYNC_INBOX 11 SYNC_INBOX_FINISH
         12 SYNC_MESSAGES 13 SYNC_MESSAGES_FINISH 14 KICK 15 DELETE_MESSAGE。
-        命令 8 READ 请求体为 `{"conversation_id","msg_id"}`（无信封）。成功应答命令仍为 8，
-        Body 为 Envelope，`data` 为 `{"conversation_id","msg_id"}`，其中 `msg_id` 是
+        命令 8 READ 请求体不是 envelope：`conversation_id`，以及 `msg_id` 或 `last_msg_id`
+        （任一大于 0；两者都大于 0 时用 `msg_id`）。成功应答命令仍为 8，
+        Body 为 Envelope，`code` 为 `"0"`，`data` 为 `{"conversation_id","msg_id"}`，其中 `msg_id` 是
         `t_conversation_members.last_read_msg_id`（只增不减）。服务端清该用户 Redis
         `im:dialog:unreadcnt` 字段，并把会话从 `im:dialog:unread` 挪到 `im:dialog:read`。
         水位前进时通知该用户其他在线设备（命令 8，不系统推送、不写 mailbox）。
-        缺 `conversation_id` 或 `msg_id` 时 `code` 为 `40001`。
+        缺 `conversation_id`，或两个消息 id 都小于等于 0 时，`code` 为 `40001`。
     EnvelopeCode:
       type: string
       enum: ["0", "40001", "40002", "40003", "40004", "40005", "40101", "40102", "40103", "40301", "40302", "40303", "40401", "40402", "40901", "42901", "42902", "42903", "49901", "50001", "50002", "50003", "50301", "50401"]