全量获取群成员用户 ID（带版本）

1. 接口定位

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

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

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

4. 响应结构

通用响应包裹

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

data 字段结构

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

5. 业务规则

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

6. 错误码与失败场景

错误码	场景	典型报错
1002	非群成员且非管理员	NoPermissionError
500	服务内部错误	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/group/get_full_group_member_user_ids", {
  method: "POST",
  headers: {
    operationID: "b8f5b8de-9326-4d0a-b221-7a6a6f4db1d3",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    groupID: "group_001",
    idHash: "e6f8e13f3f5f7d10",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "groupID": "group_001",
  "idHash": "e6f8e13f3f5f7d10"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "version": 128,
    "versionID": "66547a10f0d5ab0f51711234",
    "equal": false,
    "userIDs": ["u_1001", "u_1002", "u_admin"]
  }
}

8. 时序流程

1. 读取群成员 userID 列表并校验调用者权限（管理员或群成员）。
2. 查询群成员版本信息并计算服务端 idHash。
3. 与请求 idHash 比对，回填 equal，必要时返回全量 userIDs。

9. 变更记录

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