搜索建群白名单

1. 接口定位

• 接口名称: 搜索建群白名单
• 所属域: admin/group
• 业务目标: 按关键字分页搜索建群白名单记录

2. 请求定义

• Method: POST
• Path: /adminx/group/create_permission/search
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 幂等（只读操作）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	管理员 token

Body 参数

字段	必填	类型	说明
keyword	否	string	支持匹配 user_id / reason / operator_user_id
pagination	是	RequestPagination	分页参数

RequestPagination 字段如下：

字段	必填	类型	说明
pageNumber	是	int32	页码，从 1 开始
showNumber	是	int32	每页条数

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
total	uint32	命中总数
users	array<GroupCreatePermissionInfo>	当前页记录列表

GroupCreatePermissionInfo 字段结构与 查询指定用户白名单状态 一致。

5. 业务规则

• 关键字搜索直接委托数据库侧处理。
• 返回记录会补齐用户公开资料。
• total 表示全部命中数量，users 仅表示当前页数据。

6. 错误码与失败场景

错误码	场景	典型报错
1001	Header 缺少 operationID	header must have operationID
-	缺少管理员 token	由管理员鉴权链路返回
-	搜索白名单失败	由存储链路返回
-	用户资料查询失败	由用户资料查询链路返回

7. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/group/create_permission/search", {
  method: "POST",
  headers: {
    operationID: "group-create-permission-search-001",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    keyword: "admin",
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "keyword": "admin",
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 1,
    "users": [
      {
        "userID": "user_001",
        "reason": "运营活动白名单",
        "opUserID": "admin_001",
        "createTime": 1775404800000,
        "user": {
          "userID": "user_001",
          "nickname": "Tom"
        }
      }
    ]
  }
}

8. 时序流程

1. 中间件校验管理员 token。
2. 按关键字和分页参数搜索建群白名单。
3. 批量补齐当前页用户公开资料。
4. 返回总数与当前页记录。

9. 变更记录

• 2026-04-06: 补全文档结构，修正真实服务前缀为 /adminx。