搜索封禁管理员

1. 接口定位

• 接口名称: 搜索封禁管理员
• 所属域: admin/account
• 业务目标: 按管理员 userID、封禁原因或操作人分页检索当前封禁中的管理员列表，并补充管理员基础资料

2. 请求定义

• Method: POST
• Path: /adminx/account/block/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	是	object	分页参数

pagination 字段

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

字段约束

• pagination 不能为空。
• pageNumber 和 showNumber 都必须大于 0。

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
total	uint32	命中的封禁管理员总数
blockedAdmins	array<object>	当前页封禁管理员列表

blockedAdmins 元素字段

字段	类型	说明
userID	string	被封禁管理员 userID
account	string	管理员账号
nickname	string	管理员昵称
faceURL	string	管理员头像
level	int32	管理员等级
reason	string	封禁原因
operatorUserID	string	执行封禁的管理员 userID
createTime	int64	封禁时间，Unix 毫秒时间戳

5. 业务规则

• 仅管理员可以调用。
• 查询结果按 createTime 倒序返回。
• 当前 keyword 只匹配封禁记录中的 user_id、reason、operator_user_id，不会按 account 或 nickname 做搜索。
• 服务端会先分页查询 adminx_blocked_admin，再按当前页 userID 批量补充管理员基础资料。
• 若某条封禁记录对应的管理员资料已不存在，返回项仍会保留封禁信息，只是 account/nickname/faceURL/level 可能为空或零值。

6. 错误码与失败场景

错误码	场景	典型报错
1001	pagination 为空	pagination is empty
1001	分页参数非法	pagination invalid
-	封禁记录搜索失败	由数据库层返回原始错误
-	管理员资料批量查询失败	由数据库层返回原始错误

7. 示例

fetch 请求示例

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

请求示例（JSON）

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

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 1,
    "blockedAdmins": [
      {
        "userID": "1000000002",
        "account": "ops_admin",
        "nickname": "Ops Admin",
        "faceURL": "https://example.com/ops.png",
        "level": 80,
        "reason": "security review failed",
        "operatorUserID": "1000000001",
        "createTime": 1776139200000
      }
    ]
  }
}

失败响应示例

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "pagination is empty"
}

8. 时序流程

1. 中间件校验管理员 token。
2. 校验分页参数。
3. 按 keyword 在 adminx_blocked_admin 中分页搜索封禁记录。
4. 提取当前页 userID，批量查询管理员基础资料。
5. 组装 total + blockedAdmins 返回。

9. 变更记录

• 2026-04-15: 首版发布，新增 adminx 搜索封禁管理员接口文档。