全量获取用户已加入群 ID（带版本）

1. 接口定位

• 接口名称: 全量获取用户已加入群 ID（带版本）
• 所属域: group
• 业务目标: 获取指定用户的全量入群 groupID 集合，并返回版本与哈希比对结果，供客户端做全量同步

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
userID	是	string	目标用户 ID
idHash	否	string	客户端当前已入群 groupID 集合哈希，用于服务端快速判断是否一致

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
version	uint64	当前已入群集合版本号
versionID	string	版本记录 ID
equal	bool	服务端集合哈希是否与请求 idHash 一致
groupIDs	array[string]	全量已加入群 ID 列表；当 equal=true 时可能为空

5. 业务规则

• 调用方需满足“请求 userID 本人”或“应用管理员”之一。
• 服务端会计算已入群 groupID 集合哈希并与 idHash 对比。
• 当 idHash 命中（equal=true）时，服务端可不返回 groupIDs（节省带宽）。

6. 错误码与失败场景

错误码	场景	典型报错
1002	请求 userID 与 token 用户不一致且非管理员	NoPermissionError
500	服务内部错误	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/group/get_full_join_group_ids", {
  method: "POST",
  headers: {
    operationID: "e279eb74-6e0d-4dfd-bd53-72d982734a13",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userID: "u_1001",
    idHash: "9e6a83ce324d9a7c",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "userID": "u_1001",
  "idHash": "9e6a83ce324d9a7c"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "version": 57,
    "versionID": "66547f03f0d5ab0f51711888",
    "equal": false,
    "groupIDs": ["group_001", "group_002"]
  }
}

8. 时序流程

1. 校验调用权限（请求 userID 本人或管理员）。
2. 查询用户当前入群版本与全量 groupID 集合。
3. 计算并对比 idHash，回填 equal，必要时返回全量 groupIDs。

9. 变更记录

• 2026-06-20: 首版补充文档发布。