批量封禁用户（adminx）

1. 接口定位

• 接口名称: 批量封禁用户（支持部分成功）
• 所属域: admin/block
• 业务目标: 批量把指定用户加入封禁列表，并在单次请求内返回每个 userID 的处理结果

2. 请求定义

• Method: POST
• Path: /adminx/block/add/batch
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 非幂等；对已封禁用户会返回该条失败，但不影响其它条目

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
userIDs	是	array<string>	待封禁用户 ID 列表
reason	否	string	封禁原因

字段约束

• userIDs 不能为空。
• reason 会在服务端做首尾空白裁剪后写入封禁记录。
• 同一请求内重复 userID 不会中断整个请求，会按条目标记失败。

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
total	uint32	输入条目总数
successCount	uint32	成功条目数
failedCount	uint32	失败条目数
successUserIDs	array<string>	成功封禁的用户 ID 列表
results	array<object>	每条输入的处理结果

results 子字段：

字段	类型	说明
userID	string	本条对应的用户 ID
success	bool	是否成功
reasonCode	string	失败原因码；成功时为空
reason	string	失败说明；成功时为空

5. 业务规则

• 仅管理员可以调用。
• 单条失败不影响其它条目，接口支持部分成功。
• 对已在封禁列表中的用户，本条返回失败：
  • reasonCode = ALREADY_BLOCKED
  • reason = user already blocked
• 对空 userID，本条返回失败：
  • reasonCode = INVALID_USER_ID
  • reason = userID is empty
• 对同请求内重复 userID，重复条目返回失败：
  • reasonCode = DUPLICATE_USER_ID
  • reason = duplicate userID in request
• 成功条目会写入：
  • userID
  • reason
  • operatorUserID
  • createTime
• 对成功封禁的 userID，API 层会调用 OpenIM force_logout，触发目标用户在 openim-server 连接层下线。
• 对成功封禁的 userID，API 层会调用 InvalidateToken 清理 openim-chat 登录 token，使既有登录态立即失效。
• openim-chat 本身不维护长连接，下线动作由 OpenIM 连接层（openim-server）执行。

6. 错误码与失败场景

错误码	场景	典型报错
1001	userIDs 为空	userIDs is empty
-	鉴权失败	由管理员鉴权链路返回
-	查询或写入数据库失败	由数据库层返回原始错误

说明：

• 当请求本身合法时，即使存在部分条目失败，接口仍返回 errCode = 0，并通过 data.results 给出逐条结果。

7. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/block/add/batch", {
  method: "POST",
  headers: {
    operationID: "adminx-batch-block-001",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userIDs: ["user_001", "", "user_002", "user_001", "user_003"],
    reason: "risk control",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "userIDs": ["user_001", "", "user_002", "user_001", "user_003"],
  "reason": "risk control"
}

部分成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 5,
    "successCount": 2,
    "failedCount": 3,
    "successUserIDs": ["user_002", "user_003"],
    "results": [
      {
        "userID": "",
        "success": false,
        "reasonCode": "INVALID_USER_ID",
        "reason": "userID is empty"
      },
      {
        "userID": "user_001",
        "success": false,
        "reasonCode": "DUPLICATE_USER_ID",
        "reason": "duplicate userID in request"
      },
      {
        "userID": "user_001",
        "success": false,
        "reasonCode": "ALREADY_BLOCKED",
        "reason": "user already blocked"
      },
      {
        "userID": "user_002",
        "success": true,
        "reasonCode": "",
        "reason": ""
      },
      {
        "userID": "user_003",
        "success": true,
        "reasonCode": "",
        "reason": ""
      }
    ]
  }
}

8. 时序流程

1. 中间件校验管理员 token。
2. RPC 层逐条校验输入，先记录空值和请求内重复项失败结果。
3. 对剩余候选用户批量查询封禁状态。
4. 过滤已封禁用户并写入逐条失败结果。
5. 对可封禁用户批量落库。
6. 对成功封禁用户逐个调用 InvalidateToken 使 openim-chat 登录态失效。
7. 对成功封禁用户逐个调用 OpenIM force_logout 触发下线。
8. 汇总成功/失败统计并返回统一成功响应。

9. 变更记录

• 2026-06-21: 首版发布，新增 adminx 批量封禁接口文档，支持部分成功语义。
• 2026-07-04: 更新文档，补充批量封禁成功后会触发 OpenIM 强制下线，并明确 openim-chat 与 openim-server 的职责边界。