封禁管理员

1. 接口定位

• 接口名称: 封禁管理员
• 所属域: admin/account
• 业务目标: 将指定管理员加入封禁列表，阻止其继续登录 adminx 管理后台

2. 请求定义

• Method: POST
• Path: /adminx/account/block
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 非幂等；同一管理员重复封禁会直接失败

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
userID	是	string	被封禁管理员 userID
reason	否	string	封禁原因，允许为空

字段约束

• userID 不能为空。
• reason 会在入库前做首尾空白裁剪。

4. 响应结构

通用响应包裹

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

data 字段

• 本接口成功时返回空对象（无业务字段）。

5. 业务规则

• 仅超级管理员可调用。
• 超级管理员不能封禁自己。
• 不能封禁另一个超级管理员。
• 目标管理员必须已存在于管理员表。
• 封禁状态以 adminx_blocked_admin 集合中的记录是否存在为准。
• 封禁成功后会写入以下字段：
  • userID
  • reason
  • operatorUserID: 当前操作管理员 userID
  • createTime: 当前服务端时间
• 封禁成功后会尝试让目标管理员当前 token 失效，避免继续使用既有会话。

6. 错误码与失败场景

错误码	场景	典型报错
1001	userID 为空	userID is empty
1002	非超级管理员调用	only super admin can block admin
1002	超级管理员封禁自己	super admin cannot block self
1002	目标管理员是超级管理员	cannot block super admin
1004	目标管理员不存在	target admin not found
1003	目标管理员已被封禁	admin already blocked
-	查询或写入数据库失败	由数据库层返回原始错误

7. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/account/block", {
  method: "POST",
  headers: {
    operationID: "adminx-block-admin-001",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userID: "1000000002",
    reason: "security review failed",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "userID": "1000000002",
  "reason": "security review failed"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

失败响应示例

{
  "errCode": 1002,
  "errMsg": "NoPermissionError",
  "errDlt": "cannot block super admin"
}

8. 时序流程

1. 中间件校验管理员 token。
2. 从上下文中读取当前操作管理员 userID。
3. 校验当前操作人是否为超级管理员。
4. 校验目标管理员是否存在、是否已被封禁、是否命中自封禁或超级管理员保护规则。
5. 写入封禁记录。
6. 尝试让目标管理员当前 token 失效。
7. 返回统一成功响应。

9. 变更记录

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