检查用户建群权限

1. 接口定位

• 接口名称: 检查用户建群权限
• 所属域: admin/group
• 业务目标: 检查某个用户当前是否允许建群

2. 请求定义

• Method: POST
• Path: /adminx/group/create_permission/check
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 幂等（只读操作）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
userID	是	string	待检查用户 ID

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
allowed	bool	是否允许建群
mode	string	当前全局建群模式
inWhitelist	bool	是否命中白名单

5. 业务规则

• 当模式为 all 时，任何用户都返回 allowed=true。
• 当模式为 disabled 时，任何用户都返回 allowed=false。
• 当模式为 whitelist 时，仅命中白名单的用户返回 allowed=true 且 inWhitelist=true。
• 该接口不仅可用于后台人工检查，也被 chat 服务的 OpenIM 建群前 callback 链路复用。

6. 错误码与失败场景

错误码	场景	典型报错
1001	Header 缺少 operationID	header must have operationID
1001	建群模式配置非法	group create mode invalid
-	缺少管理员 token	由管理员鉴权链路返回
-	配置或白名单读取失败	由存储链路返回

7. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/group/create_permission/check", {
  method: "POST",
  headers: {
    operationID: "group-create-permission-check-001",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userID: "user_001",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "userID": "user_001"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "allowed": true,
    "mode": "whitelist",
    "inWhitelist": true
  }
}

8. 时序流程

1. 中间件校验管理员 token。
2. 读取当前建群模式。
3. 若模式为 whitelist，继续查询目标用户是否在白名单中。
4. 返回最终权限判断结果。

9. 变更记录

• 2026-04-06: 补全文档结构，修正真实服务前缀为 /adminx。