组织核心概念

本文档详细说明 Code Bird Cloud 组织模块中的所有核心概念、数据模型及其关联关系。

概念总览

组织模块由以下六个核心实体组成：

OrganizationPermission ──┐
    (权限模板)             │
                          ├──> OrganizationRolePermission
                          │       (角色-权限关联)
OrganizationRole ─────────┘
    (角色模板)             │
                          ├──> OrganizationUserRole
                          │       (成员角色分配)
Organization ─────────────┤
    (组织)                 │
                          ├──> OrganizationUser
                          │       (成员关系)
User ─────────────────────┘
    (用户)

Organization（组织）

组织是最顶层的业务实体，代表一个公司、团队或工作空间。

数据模型

字段	类型	必填	说明
id	string(21)	是	nanoid 唯一标识
tenant_id	string(21)	是	所属租户，默认 `"default"`
name	string(128)	是	组织名称
description	string(256)	否	组织描述
metadata	JSON	是	自定义元数据，默认 `{}`
created_at	datetime	是	创建时间
updated_at	datetime	是	更新时间

关键特性

每个组织由 nanoid 唯一标识
metadata 字段为 JSON 类型，可存储任意业务扩展数据（如组织 Logo、联系方式、行业分类等）
组织的创建、更新、删除通过 Management API 完成
删除组织时，相关的成员关系和成员角色分配将被级联清除

元数据使用示例

json

{
  "logo": "https://cdn.example.com/org-logo.png",
  "industry": "technology",
  "contact_email": "admin@company.com",
  "max_members": 100
}

OrganizationRole（组织角色模板）

组织角色模板是在租户级别定义的角色，所有组织共享同一套角色定义。角色本身不属于某个特定组织，而是作为模板在任意组织中使用。

数据模型

字段	类型	必填	说明
id	string(21)	是	nanoid 唯一标识
tenant_id	string(21)	是	所属租户，默认 `"default"`
name	string(128)	是	角色名称
description	string(256)	否	角色描述
created_at	datetime	是	创建时间
updated_at	datetime	是	更新时间

设计理念

角色模板的"租户级共享"设计带来以下优势：

统一管理：只需在一个地方维护角色定义，避免在每个组织中重复创建
一致性保证：所有组织使用相同的角色语义，避免命名混乱
简化运维：新增组织时无需额外配置角色，直接使用已有模板

典型角色示例

角色名称	说明
admin	组织管理员，拥有组织内的全部权限
member	普通成员，拥有基本的读写权限
viewer	只读观察者，仅可查看数据
billing	财务角色，管理账单和订阅

OrganizationPermission（组织权限模板）

组织权限模板同样在租户级别定义，所有组织共享。权限代表一个具体的操作能力。

数据模型

字段	类型	必填	说明
id	string(21)	是	nanoid 唯一标识
tenant_id	string(21)	是	所属租户，默认 `"default"`
name	string(128)	是	权限名称
description	string(256)	否	权限描述
created_at	datetime	是	创建时间

注意：权限模板没有 updated_at 字段。权限一旦创建，名称和描述不可修改。如需变更，应删除后重新创建。

权限命名约定

建议使用 动作:资源 的格式命名权限，保持语义清晰：

权限名称	说明
read:members	查看组织成员
manage:members	管理组织成员（增删）
read:data	读取组织数据
write:data	写入组织数据
manage:settings	管理组织设置
manage:billing	管理账单

OrganizationRolePermission（角色-权限关联）

将权限模板分配给角色模板的关联实体。通过这个关联，定义每个角色拥有哪些权限。

数据模型

字段	类型	说明
tenant_id	string(21)	所属租户
organization_role_id	string(21)	角色模板 ID（联合主键）
organization_permission_id	string(21)	权限模板 ID（联合主键）

关联示例

角色: admin
├── read:members
├── manage:members
├── read:data
├── write:data
└── manage:settings

角色: member
├── read:members
├── read:data
└── write:data

角色: viewer
└── read:data

OrganizationUser（组织成员）

表示用户与组织之间的成员关系。一个用户可以同时是多个组织的成员。

数据模型

字段	类型	说明
tenant_id	string(21)	所属租户
organization_id	string(21)	组织 ID（联合主键）
user_id	string(21)	用户 ID（联合主键）
created_at	datetime	加入时间

关键特性

一个用户可以加入多个组织
用户在不同组织中拥有独立的角色分配
添加成员时通过 user_ids 数组批量操作
移除成员时会自动清除该成员在对应组织中的所有角色分配

OrganizationUserRole（组织成员角色）

表示用户在某个特定组织内被分配的角色。这是组织级 RBAC 的核心关联实体。

数据模型

字段	类型	说明
tenant_id	string(21)	所属租户
organization_id	string(21)	组织 ID（联合主键）
user_id	string(21)	用户 ID（联合主键）
organization_role_id	string(21)	组织角色模板 ID（联合主键）

核心设计

三字段联合主键 (organization_id, user_id, organization_role_id) 确保：

同一用户在同一组织中可以拥有多个角色
同一用户在不同组织中可以拥有不同的角色组合
角色分配粒度精确到"某组织中的某用户"

场景示例

用户: 张三
├── 组织 A: [admin, member]     // 在组织 A 中是管理员兼成员
├── 组织 B: [viewer]            // 在组织 B 中仅为观察者
└── 组织 C: [member, billing]   // 在组织 C 中是成员兼财务

概念对比表

下表将 Code Bird Cloud 的组织概念与 Logto 进行对照：

Code Bird Cloud	Logto	说明
Organization	Organization	业务实体（公司/团队/工作空间）
OrganizationRole	Organization role	租户级共享的角色模板定义
OrganizationPermission	Organization permission	租户级共享的权限模板定义
OrganizationRolePermission	Role-permission mapping	角色模板与权限模板的关联
OrganizationUser	Organization member	用户-组织的成员关系
OrganizationUserRole	Member role assignment	特定组织内的成员角色分配

与 Logto 的主要差异

命名风格：Code Bird Cloud 使用更具描述性的命名（如 OrganizationUserRole vs Logto 的隐式关联）
多租户原生支持：所有实体都包含 tenant_id，原生支持多租户隔离
ID 方案：统一使用 nanoid（21 位字符），而 Logto 使用多种 ID 格式
元数据：Organization 提供 metadata JSON 字段用于业务扩展

数据流向图

                        租户级定义（共享）
                ┌─────────────────────────────┐
                │  OrganizationPermission     │
                │  (read:data, write:data...) │
                │              │               │
                │              v               │
                │  OrganizationRolePermission  │
                │              ^               │
                │              │               │
                │  OrganizationRole            │
                │  (admin, member, viewer)     │
                └─────────────┬───────────────┘
                              │
                    分配到组织内的用户
                              │
                ┌─────────────v───────────────┐
                │        组织级分配            │
                │                              │
                │  Organization                │
                │       │                      │
                │       v                      │
                │  OrganizationUser            │
                │       │                      │
                │       v                      │
                │  OrganizationUserRole        │
                │  (用户在此组织中的角色)       │
                └──────────────────────────────┘

这种分层设计确保了模板的复用性（一次定义，多处使用）和分配的灵活性（每个组织独立管理成员角色）。

组织核心概念 ​

概念总览 ​

Organization（组织） ​

数据模型 ​

关键特性 ​

元数据使用示例 ​

OrganizationRole（组织角色模板） ​

数据模型 ​

设计理念 ​

典型角色示例 ​

OrganizationPermission（组织权限模板） ​

数据模型 ​

权限命名约定 ​

OrganizationRolePermission（角色-权限关联） ​

数据模型 ​

关联示例 ​

OrganizationUser（组织成员） ​

数据模型 ​

关键特性 ​

OrganizationUserRole（组织成员角色） ​

数据模型 ​

核心设计 ​

场景示例 ​

概念对比表 ​

与 Logto 的主要差异 ​

数据流向图 ​

组织核心概念

概念总览

Organization（组织）

数据模型

关键特性

元数据使用示例

OrganizationRole（组织角色模板）

数据模型

设计理念

典型角色示例

OrganizationPermission（组织权限模板）

数据模型

权限命名约定

OrganizationRolePermission（角色-权限关联）

数据模型

关联示例

OrganizationUser（组织成员）

数据模型

关键特性

OrganizationUserRole（组织成员角色）

数据模型

核心设计

场景示例

概念对比表

与 Logto 的主要差异

数据流向图