搜索封禁用户

1. 接口定位

• 接口名称: 搜索封禁用户
• 所属域: admin/block
• 业务目标: 按用户 ID、封禁原因或操作人分页检索封禁列表，并补充用户完整资料

2. 请求定义

• Method: POST
• Path: /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

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
total	uint32	命中的封禁用户总数
users	array<object>	当前页封禁用户列表

users 元素字段

字段	类型	说明
userID	string	被封禁用户 ID
account	string	用户账号
phoneNumber	string	手机号
areaCode	string	区号
email	string	邮箱
nickname	string	昵称
faceURL	string	头像
gender	int32	性别
reason	string	封禁原因
opUserID	string	操作人用户 ID
createTime	int64	创建时间，Unix 毫秒时间戳

5. 业务规则

• 仅管理员可以调用。
• 数据库先返回封禁记录，再由 chat 服务按 userID 批量补充完整用户资料。
• 如果某条封禁记录对应的用户资料已不存在，返回项里仍会保留封禁信息，只是账号、手机号、邮箱等补充字段可能为空。

6. 错误码与失败场景

错误码	场景	典型报错
1001	pagination 为空	pagination is empty
1001	pageNumber < 1	pageNumber is invalid
1001	showNumber < 1	showNumber is invalid
-	数据库搜索失败	由数据库层返回原始错误
-	用户完整资料查询失败	由 chat 服务链路返回

7. 示例

fetch 请求示例

fetch("http://localhost:10009/block/search", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440503",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    keyword: "spam",
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

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

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 1,
    "users": [
      {
        "userID": "1000001234",
        "account": "alice",
        "phoneNumber": "13800138000",
        "areaCode": "+86",
        "email": "alice@example.com",
        "nickname": "Alice",
        "faceURL": "https://example.com/avatar.png",
        "gender": 2,
        "reason": "spam account",
        "opUserID": "admin_001",
        "createTime": 1767225600000
      }
    ]
  }
}

失败响应示例

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

8. 时序流程

1. 中间件校验管理员 token。
2. 校验分页参数。
3. 按 keyword 在封禁表中分页搜索封禁记录。
4. 提取用户 ID，调用 chat 服务批量获取用户完整资料。
5. 组装 total + users 返回。

9. 变更记录

• 2026-03-31: 首版发布，基于封禁用户分页检索和用户资料补充逻辑补全文档。