协议语义：ID、seq 与游标
结论
集成 Flare IM 时 必须区分 四类标识；混用会导致幂等失败、同步重复或游标回退。
| 字段 | 作用域 | 谁生成 | 用途 |
|---|---|---|---|
request_id | 单次 RPC / 发送请求 | 客户端 | 幂等重试、去重 |
message_id | 全局消息 | 服务端（或编排器） | 消息唯一性、撤回/引用 |
seq | 会话内 | 服务端单调递增 | 排序、增量同步、已读 |
cursor | 用户 × 会话（或设备） | 客户端上报、服务端合并 | 同步断点、多端漫游 |
seq（会话序列号）
- 每个
conversation_id维护max_seq，只增不减。 - 客户端拉历史：
syncMessages(conversation_id, last_seq, limit)，返回seq > last_seq的消息。 - 禁止 用 offset/limit 分页替代 seq（大群/大会话会漂移）。
// SDK
client.sync_messages("conv_1", last_seq, 200).await?;
client.conversation().await?.mark_read("conv_1", read_seq).await?;
cursor（同步游标）
- 表示「该用户在该会话已消费到的位置」，多端并发时服务端取 较大 seq 合并，避免误报回退。
- SDK 本地持久化 cursor；上报前应与本地
max(本地, 远端)对齐。
request_id 与幂等
- 同一会话重复发送应携带相同
request_id，编排器去重后返回同一message_id/seq。 - 网络超时重试 不要 换新
request_id（除非业务确认为新消息）。
message_id
- 跨会话唯一，用于引用、撤回、反应绑定。
- 与
seq无关：同一message_id在会话内对应唯一seq。
flare-proto 入口
| 包/服务 | 说明 |
|---|---|
flare_proto::message | 消息体、Elem、状态 |
flare_proto::conversation | 会话摘要、参与者 |
flare_proto::sync | 增量同步、会话补丁 |
服务端 gRPC 清单见 /docs/server/04-grpc-api。
检查清单
- [ ] 客户端同步 API 使用
last_seq，非 page offset - [ ] 上报已读使用
read_seq，且不大于服务端max_seq - [ ] 重试发送复用
request_id - [ ] 日志中分别打印四类 ID，便于排障