管理员身份判定迁移说明

本文档用于说明 Code Bird Cloud 当前生效的管理员身份判定规则，并指导现有工程师从旧的“按角色名判断组织管理员”方式迁移到新的字段模式。

如果你正在维护第三方应用接入、组织成员管理、组织级鉴权或后台组织管理功能，请以本文档为准。

结论

当前系统中有两类管理员身份，它们的判定方式不同：

• 平台或租户后台超级管理员：继续按 is_super 或 is_super_admin 判定
• 组织管理员：统一按组织成员关系上的 is_admin 判定

以下旧方式已经废弃，不应继续作为组织管理员的判断依据：

• 根据组织角色名称是否为 admin 判断
• 根据 organization_roles 中是否包含 admin 判断
• 根据“角色描述是组织管理员”判断

一句话总结：

角色名 admin 现在只表示一个组织角色模板名称，不再等价于“组织管理员”。

为什么要迁移

旧文档中的组织模型把“组织管理员”当作一个角色模板，例如 admin。这种方式有两个问题：

1. 角色名称只能表达“某个角色模板”，不能稳定表达“该成员是否受到管理员保护规则约束”
2. 第三方应用和后台功能现在都需要区分“普通角色管理”和“组织管理员保护”，继续用角色名会导致语义混乱

本次变更后，组织管理员已经升级为组织成员关系上的独立标记，对应后端模型字段：

• organization_users.is_admin

在接口层面，组织成员相关响应会返回：

• is_admin

这才是当前唯一可靠的组织管理员判断方式。

当前生效的判定规则

场景	当前正确的判断方式	说明
平台后台超级管理员	is_super / is_super_admin	适用于平台管理后台、租户后台、签名密钥等平台级管理能力
组织管理员	is_admin	适用于组织成员管理、M2M 组织成员接口、组织管理员保护规则
组织级 OIDC 登录中的当前组织管理员	organization_is_admin	适用于 Authorization Code Flow 登录后的 ID Token、Access Token、/oidc/userinfo
组织角色权限	scope	适用于鉴权，不应再依赖角色名本身

旧方式与新方式对比

旧方式：按角色名判断组织管理员

历史文档中存在类似表述：

• 用户拥有 admin 角色，视为组织管理员
• 第三方应用读取 organization_roles 后，自行约定 admin 拥有全部权限

这种方式现在仅能说明“该用户或应用被分配了一个名字叫 admin 的角色模板”，不能说明：

• 该成员是否为组织管理员
• 该成员是否不能被第三方应用移除
• 该成员是否受“至少保留一名管理员”规则保护

新方式：按 is_admin 判断组织管理员

现在组织管理员是成员关系上的独立状态。

只要响应中的 is_admin = true，就表示该成员是组织管理员，应当适用管理员保护规则。

示例：

{
  "id": "user_001",
  "username": "zhangsan",
  "phone": "13800000000",
  "roles": [
    { "id": "role_001", "name": "admin" }
  ],
  "is_admin": true
}

上面的示例里：

• roles[].name = "admin" 只是角色模板名称
• is_admin = true 才表示该成员是真正的组织管理员

第三方应用与 M2M 集成的最新规则

对于第三方应用接入和 M2M 组织成员管理，请遵循以下规则：

1. 判断某个成员是不是组织管理员，只看 is_admin
2. 判断某个请求能不能管理组织成员，只看 token 中的 scope
3. 不再根据 organization_roles 中是否出现 admin 来决定组织管理员身份

对于第三方应用接入和 OIDC 用户登录，请遵循以下规则：

1. 判断“当前登录用户在当前组织下是不是组织管理员”，只看 organization_is_admin
2. organization_roles 只表示角色模板名称，不再代表组织管理员身份
3. is_super / is_super_admin 仍然只表示平台或租户后台超级管理员，不表示组织管理员

需要特别注意

M2M token 中的组织角色，例如：

{
  "organization_roles": ["admin"],
  "scope": ["all"]
}

只能说明：

• 该应用在当前组织下拿到了名为 admin 的组织角色
• 该角色最终解析出了 all 这个可用 scope

不能说明：

• 目标成员是不是组织管理员
• 第三方应用能不能维护组织管理员

组织管理员是否可移除、是否可取消、是否受保护，只由成员的 is_admin 决定。

迁移建议

1. 替换所有按角色名判断组织管理员的逻辑

请在代码中搜索以下模式并替换：

• role.name === 'admin'
• organization_roles.includes('admin')
• organization_roles.includes(orgId + ':admin')
• 任何“角色描述为组织管理员”之类的前端或后端判断

迁移目标：

• 组织管理员身份判断统一改为读取 is_admin

2. 保留平台超级管理员的旧判断方式

平台后台和租户后台的超级管理员逻辑没有变化，仍然使用：

• is_super
• is_super_admin

不要把这组字段和组织管理员的 is_admin 混用。

3. 鉴权逻辑改为基于 scope

如果你的代码以前是这样做的：

• 看到角色名是 admin 就认为可以管理组织成员

现在应改为：

• 根据 token 的 scope 判定是否允许调用管理接口

对于本次 M2M 组织成员管理接口，当前放行条件是：

• manage:organizations
• 或 all

4. 检查历史组织数据

本次变更没有对历史组织执行管理员初始化迁移。

这意味着历史组织可能存在以下情况：

• 成员拥有 admin 角色
• 但成员关系上的 is_admin 仍然是 false

这种情况下，系统不会自动把该成员视为新的组织管理员。需要由后台管理员在组织管理页面手动设置组织管理员。

你应该如何理解现有文档

下列文档中，涉及“通过角色名 admin 判断组织管理员”的表述，应视为历史兼容说明或角色模板示例，不再作为最新规则：

• 组织级 RBAC
• 组织核心概念
• 组织级登录

当前涉及组织成员管理和第三方应用接入时，请优先参考：

• M2M 组织成员管理接入指南
• M2M 组织成员管理配置指南
• M2M 组织成员管理 API 参考

迁移检查清单

在完成迁移前，请确认以下事项：

• 平台后台权限判断仍使用 is_super 或 is_super_admin
• 组织管理员身份判断已经全部切换到 is_admin
• 不再把角色名 admin 当成组织管理员身份标志
• 不再把 organization_roles 当成组织管理员身份来源
• 组织成员管理鉴权改为基于 scope
• 历史组织如需管理员保护规则，已由后台手动设置至少一名组织管理员

推荐实施顺序

1. 先替换代码中的组织管理员判断逻辑
2. 再联调组织成员查询接口，确认能正确读取 is_admin
3. 再验证移除成员、管理员保护、M2M 鉴权等行为
4. 最后下线或删除旧的“按角色名判断组织管理员”逻辑

常见误区

误区 1：角色名是 admin，就一定是组织管理员

不是。

admin 现在只是组织角色模板名称，真正的组织管理员要看 is_admin。

误区 2：M2M token 里有 organization_roles: ["admin"]，就说明可以维护组织管理员

不是。

这只能说明该应用拿到了某个角色，不代表它可以设置、取消或移除组织管理员。

误区 3：平台超级管理员和组织管理员是同一套字段

不是。

• 平台超级管理员：is_super / is_super_admin
• 组织管理员：is_admin

相关代码模型

如需查看当前代码实现，可参考：

• backend/src/application/dto/admin.go
• backend/src/domain/models/organization.go