组织成员管理

本文档说明如何管理组织内的成员关系，包括添加成员、移除成员、查看成员列表，以及为成员分配组织角色。

接口概览

方法	路径	说明
GET	/api/v1/organizations/:id/users	获取组织成员列表
POST	/api/v1/organizations/:id/users	添加组织成员
DELETE	/api/v1/organizations/:id/users/:userId	移除组织成员
GET	/api/v1/organizations/:id/users/:userId/roles	获取成员的组织角色
PUT	/api/v1/organizations/:id/users/:userId/roles	为成员分配组织角色

添加组织成员

将一个或多个用户添加为组织成员。支持批量操作。

请求

POST /api/v1/organizations/:id/users
Content-Type: application/json

路径参数

参数	类型	必填	说明
id	string	是	组织 ID

请求体

字段	类型	必填	说明
user_ids	string[]	是	用户 ID 数组

请求示例

{
  "user_ids": [
    "user_abc123def456ghi7",
    "user_def456ghi789jkl0",
    "user_ghi789jkl012mno3"
  ]
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": null
}

错误情况

错误码	说明
400	user_ids 为空或格式不正确
404	组织不存在，或某个用户 ID 不存在
409	用户已经是该组织的成员

说明

• 添加成员时仅建立成员关系，不会自动分配角色
• 新成员默认没有任何组织角色，需要通过角色分配接口单独设置
• 如果数组中部分用户已是成员，可能会返回冲突错误

移除组织成员

从组织中移除一个成员。移除后该用户在该组织中的所有角色分配也将被清除。

请求

DELETE /api/v1/organizations/:id/users/:userId

路径参数

参数	类型	必填	说明
id	string	是	组织 ID
userId	string	是	用户 ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": null
}

错误情况

错误码	说明
404	组织不存在，或用户不是该组织的成员

说明

• 移除成员会自动清除该成员在此组织中的所有角色分配（organization_user_roles 记录）
• 用户本身不会被删除，仅解除与该组织的关联
• 用户在其他组织中的成员身份和角色不受影响

获取组织成员列表

查询指定组织的所有成员，支持分页。

请求

GET /api/v1/organizations/:id/users?page=1&page_size=20

路径参数

参数	类型	必填	说明
id	string	是	组织 ID

查询参数

参数	类型	必填	说明
page	integer	否	页码，默认 1
page_size	integer	否	每页数量，默认 20

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "id": "user_abc123def456ghi7",
        "username": "zhangsan",
        "primary_email": "zhangsan@example.com",
        "name": "张三",
        "avatar": "https://cdn.example.com/avatars/zhangsan.png"
      },
      {
        "id": "user_def456ghi789jkl0",
        "username": "lisi",
        "primary_email": "lisi@example.com",
        "name": "李四",
        "avatar": null
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20
  }
}

获取成员的组织角色

查询某个成员在指定组织中拥有的所有角色。

请求

GET /api/v1/organizations/:id/users/:userId/roles

路径参数

参数	类型	必填	说明
id	string	是	组织 ID
userId	string	是	用户 ID

响应示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "role_abc123def456ghi7",
      "name": "admin",
      "description": "Organization administrator with full access",
      "created_at": "2026-01-01T00:00:00Z"
    },
    {
      "id": "role_def456ghi789jkl0",
      "name": "member",
      "description": "Regular member",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

说明

• 返回的角色是该用户在此特定组织中被分配的角色
• 同一用户在不同组织中的角色可能完全不同
• 如果用户尚未被分配任何角色，返回空数组

为成员分配组织角色

为指定成员在组织内分配角色。使用 PUT 语义，传入的角色列表将完全替换该成员当前在此组织中的所有角色。

请求

PUT /api/v1/organizations/:id/users/:userId/roles
Content-Type: application/json

路径参数

参数	类型	必填	说明
id	string	是	组织 ID
userId	string	是	用户 ID

请求体

字段	类型	必填	说明
role_ids	string[]	是	组织角色模板 ID 数组

请求示例

{
  "role_ids": [
    "role_abc123def456ghi7",
    "role_def456ghi789jkl0"
  ]
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": null
}

错误情况

错误码	说明
400	role_ids 格式不正确
404	组织不存在、用户不是该组织成员、或某个角色模板不存在

说明

• 使用 PUT 语义，传入的角色列表将完全替换成员在此组织中的原有角色
• 传入空数组 [] 将清除该成员在此组织中的所有角色
• role_ids 中的 ID 必须是已创建的组织角色模板 ID
• 用户必须先是组织成员才能分配角色

跨组织角色差异

Code Bird Cloud 的组织 RBAC 核心特性之一是支持同一用户在不同组织中拥有不同角色。以下场景说明了这一设计的实际应用：

场景：SaaS 顾问

张三是一位 IT 顾问，同时为两家客户公司提供服务：

张三的组织角色：
├── Company Alpha
│   ├── admin         (管理全部设置)
│   └── member        (日常操作)
│
└── Company Beta
    └── viewer        (仅查看报表)

操作步骤

# 1. 将张三添加到 Company Alpha
curl -X POST /api/v1/organizations/{alpha_id}/users \
  -d '{"user_ids": ["{zhangsan_id}"]}'

# 2. 在 Company Alpha 中分配 admin + member 角色
curl -X PUT /api/v1/organizations/{alpha_id}/users/{zhangsan_id}/roles \
  -d '{"role_ids": ["{admin_role_id}", "{member_role_id}"]}'

# 3. 将张三添加到 Company Beta
curl -X POST /api/v1/organizations/{beta_id}/users \
  -d '{"user_ids": ["{zhangsan_id}"]}'

# 4. 在 Company Beta 中分配 viewer 角色
curl -X PUT /api/v1/organizations/{beta_id}/users/{zhangsan_id}/roles \
  -d '{"role_ids": ["{viewer_role_id}"]}'

# 5. 查看张三所属的组织
curl -X GET /api/v1/users/{zhangsan_id}/organizations

# 6. 查看张三在 Company Alpha 中的角色
curl -X GET /api/v1/organizations/{alpha_id}/users/{zhangsan_id}/roles

# 7. 查看张三在 Company Beta 中的角色
curl -X GET /api/v1/organizations/{beta_id}/users/{zhangsan_id}/roles

这种设计使得在应用层可以根据用户当前所在组织的角色，精确控制其访问权限。