组织模板

组织模板是 Code Bird Cloud 多组织（B2B）场景下的核心概念，提供租户级别的角色和权限模板定义，这些模板在所有组织之间共享，确保组织级 RBAC 的一致性和可管理性。

概念说明

与系统角色的区别

维度	系统角色（Role）	组织角色模板（Organization Role）
作用范围	全局系统级	组织内部级
绑定对象	系统用户	组织成员
权限来源	资源作用域（Scope）	组织权限模板（Organization Permission）
适用场景	API 资源访问控制	组织内部角色划分

系统角色控制的是用户对全局 API 资源的访问权限，而组织角色模板控制的是用户在特定组织内的角色和权限。

模板共享机制

组织角色模板（全局定义）          组织 A          组织 B          组织 C
┌────────────────────┐
│ admin（管理员）      │ ───────> 张三=admin    王五=admin    赵七=admin
│ member（成员）       │ ───────> 李四=member   陈六=member   钱八=member
│ viewer（观察者）     │ ───────>              周九=viewer
└────────────────────┘

组织角色模板和权限模板在系统中全局定义一次，所有组织共享同一套模板。不同的是，每个组织可以独立地为其成员分配这些角色模板。

组织角色模板（Organization Role）

组织角色模板定义了组织内可使用的角色，是一组组织权限模板的集合。

管理 API

# 获取组织角色模板列表
GET /api/v1/organization-roles

# 创建组织角色模板
POST /api/v1/organization-roles
{
  "name": "admin",
  "description": "组织管理员，拥有组织内的完整管理权限"
}

# 获取组织角色模板详情
GET /api/v1/organization-roles/:id

# 更新组织角色模板
PATCH /api/v1/organization-roles/:id
{
  "description": "更新后的描述"
}

# 删除组织角色模板
DELETE /api/v1/organization-roles/:id

角色模板-权限模板绑定

为组织角色模板分配权限模板：

# 获取角色模板绑定的组织权限
GET /api/v1/organization-roles/:id/scopes

# 设置角色模板绑定的组织权限（完全替换）
PUT /api/v1/organization-roles/:id/scopes
{
  "scope_ids": ["scope_id_1", "scope_id_2", "scope_id_3"]
}

组织权限模板（Organization Permission）

组织权限模板定义了组织内可使用的具体权限项，与组织角色模板搭配使用。

管理 API

# 获取组织权限模板列表
GET /api/v1/organization-permissions

# 创建组织权限模板
POST /api/v1/organization-permissions
{
  "name": "manage:members",
  "description": "管理组织成员"
}

# 删除组织权限模板
DELETE /api/v1/organization-permissions/:id

权限模板命名规范

建议使用 动作:对象 格式命名组织权限模板：

示例	说明
manage:members	管理组织成员（邀请、移除、修改角色）
read:members	查看组织成员列表
manage:settings	管理组织设置
manage:projects	管理组织项目
read:projects	查看组织项目
manage:billing	管理组织账单

模板配置示例

典型的组织角色和权限配置

第一步：创建权限模板

// POST /api/v1/organization-permissions
[
  { "name": "manage:members", "description": "管理组织成员" },
  { "name": "read:members", "description": "查看组织成员" },
  { "name": "manage:settings", "description": "管理组织设置" },
  { "name": "manage:projects", "description": "管理组织项目" },
  { "name": "read:projects", "description": "查看组织项目" }
]

第二步：创建角色模板

// POST /api/v1/organization-roles
[
  { "name": "admin", "description": "组织管理员" },
  { "name": "member", "description": "组织成员" },
  { "name": "viewer", "description": "组织观察者" }
]

第三步：为角色模板绑定权限模板

管理员 (admin):
  - manage:members
  - read:members
  - manage:settings
  - manage:projects
  - read:projects

成员 (member):
  - read:members
  - manage:projects
  - read:projects

观察者 (viewer):
  - read:members
  - read:projects

// PUT /api/v1/organization-roles/{admin_id}/scopes
{
  "scope_ids": [
    "manage_members_scope_id",
    "read_members_scope_id",
    "manage_settings_scope_id",
    "manage_projects_scope_id",
    "read_projects_scope_id"
  ]
}

注意事项

1. 模板全局共享：组织角色模板和权限模板一经创建，所有组织均可使用，无需为每个组织单独配置
2. 删除影响范围：删除角色模板或权限模板会影响所有组织中使用该模板的成员角色分配
3. 模板更新实时生效：修改角色模板的权限绑定后，所有持有该角色的组织成员权限立即更新
4. 与系统角色独立：组织角色模板与系统角色是完全独立的两套体系，互不影响