获取会话已读序号与最大序号

1. 接口定位

• 接口名称: 获取会话已读序号与最大序号
• 所属域: msg
• 业务目标: 批量查询会话级 hasReadSeq、maxSeq 与 maxSeqTime，用于未读统计与消息已读判定

2. 请求定义

• Method: POST
• Path: /msg/get_conversations_has_read_and_max_seq
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效令牌
• 幂等性: 幂等（只读操作）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	登录令牌

Body 参数

字段	必填	类型	说明
userID	是	string	查询目标用户 ID
conversationIDs	否	array	指定查询的会话 ID 列表
returnPinned	否	bool	是否返回置顶会话 ID 列表

字段约束

• userID 必填。
• 当 conversationIDs 为空时，服务端会自动查询该用户的全部会话。
• returnPinned 在协议层支持；当前服务端实现通常不返回置顶会话列表。

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	any	业务数据

data 字段结构

字段	类型	说明
seqs	object	key 为 conversationID，value 为序号信息
pinnedConversationIDs	array	置顶会话 ID 列表（协议字段，当前实现可能为空）

seqs value（Seqs）

字段	类型	说明
hasReadSeq	int64	已读到的会话序号
maxSeq	int64	会话当前最大序号
maxSeqTime	int64	会话最大序号对应时间（毫秒时间戳）

5. 业务规则

• 返回粒度是会话级，不是消息级。
• 单聊对端已读可按规则判定：消息 seq <= 对端 hasReadSeq 视为对端已读。
• maxSeq 优先取会话缓存中的最大序号；缺失时回落数据库结果。

6. 错误码与失败场景

错误码	场景	典型报错
1001	参数不合法（如缺少 userID）	ArgsError
1002	无权限访问	NoPermissionError
500	服务内部错误（缓存/存储异常）	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/msg/get_conversations_has_read_and_max_seq", {
  method: "POST",
  headers: {
    operationID: "8b63a91f-7c8f-4fbc-a4dd-7ca5a4e5f4c2",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userID: "u_1001",
    conversationIDs: ["si_u_1001_u_1002", "sg_group_001"],
    returnPinned: false,
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "userID": "u_1001",
  "conversationIDs": ["si_u_1001_u_1002", "sg_group_001"],
  "returnPinned": false
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "seqs": {
      "si_u_1001_u_1002": {
        "hasReadSeq": 1024,
        "maxSeq": 1030,
        "maxSeqTime": 1710000000000
      },
      "sg_group_001": {
        "hasReadSeq": 330,
        "maxSeq": 358,
        "maxSeqTime": 1710000005000
      }
    },
    "pinnedConversationIDs": []
  }
}

8. 时序流程

1. 解析请求并确定查询会话集合（优先 conversationIDs，否则取用户全部会话）。
2. 批量读取 hasReadSeq。
3. 批量读取 maxSeq/maxSeqTime，并按缓存优先策略覆盖 maxSeq。
4. 组装 seqs 映射并返回。

9. 变更记录

• 2026-07-06: 新增 get_conversations_has_read_and_max_seq 文档。