自动禁用未活跃用户（adminx）

1. 接口定位

• 接口名称: 自动禁用未活跃用户
• 所属域: admin/block
• 业务目标: 按固定规则自动筛选并禁用未活跃用户，减少手工运营成本

2. 请求定义

• Method: POST
• Path: /adminx/block/inactive/disable
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 非幂等；重复执行会跳过已禁用用户

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
reason	否	string	封禁原因；为空时使用默认自动禁用原因文本

请求示例（JSON）

{
  "reason": "auto disable inactive users"
}

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
scannedCount	uint32	本次扫描的用户数
candidateCount	uint32	命中未活跃规则的候选数
successCount	uint32	本次成功禁用用户数
failedCount	uint32	本次禁用失败用户数
successUserIDs	array<string>	本次成功禁用用户 ID 列表

5. 业务规则

• 固定规则：
  • 注册时间已超过 35 天（宽限阈值）；
  • 且最近 35 天 DAU 日桶未出现。
• 每次请求最多扫描 5000 名用户，并且最高只会生效 5000 条禁用。
• 禁用逻辑与现有封禁逻辑一致：
  • 写入封禁记录；
  • 调用 InvalidateToken 失效 openim-chat 登录态；
  • 调用 OpenIM force_logout 触发 openim-server 下线。
• 建议在业务低峰期执行，避免批量下线对在线体验造成冲击。

6. 错误码与失败场景

错误码	场景	典型报错
-	鉴权失败	由管理员鉴权链路返回
-	查询用户数据失败	由数据库层返回原始错误
-	DAU 查询失败	由 Redis 客户端返回原始错误
-	失效 token 或强制下线失败	由上游服务返回

7. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/block/inactive/disable", {
  method: "POST",
  headers: {
    operationID: "adminx-inactive-disable-001",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ reason: "auto disable inactive users" }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "scannedCount": 5000,
    "candidateCount": 913,
    "successCount": 913,
    "failedCount": 0,
    "successUserIDs": ["u10001", "u10002"]
  }
}

8. 时序流程

1. 中间件校验管理员 token。
2. 服务端扫描最多 5000 名用户。
3. 依据“注册满 35 天 + 近 35 天无 DAU”筛选候选。
4. 批量写入封禁记录。
5. 对成功禁用用户逐个调用 InvalidateToken。
6. 对成功禁用用户逐个调用 OpenIM force_logout。
7. 汇总统计并返回。

9. 变更记录

• 2026-08-14: 首版发布，新增 adminx 自动禁用未活跃用户接口。