组织管理 API

组织管理接口提供完整的 B2B 多组织支持，包括组织的增删改查、成员管理、成员角色分配，以及组织角色模板和权限模板的管理。

所有接口均需要管理员令牌认证：Authorization: Bearer <admin_token>

概念说明

概念	说明
组织	一个逻辑上的租户或团队，用户可以同时属于多个组织
组织成员	加入组织的用户，每个成员可以在组织内被分配不同的角色
组织角色模板	租户级别的共享角色定义，可在所有组织中复用
组织权限模板	租户级别的共享权限定义，可分配给组织角色模板

组织管理

获取组织列表

`GET /api/v1/organizations`

分页获取组织列表。

查询参数：

参数	类型	必填	默认值	说明
`page`	integer	否	1	页码
`page_size`	integer	否	20	每页条数

请求示例：

bash

curl -X GET "https://your-domain/api/v1/organizations?page=1&page_size=10" \
  -H "Authorization: Bearer <admin_token>"

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "data": [
      {
        "id": "org_001",
        "name": "Acme Corporation",
        "description": "Enterprise customer organization",
        "metadata": {
          "industry": "technology",
          "plan": "enterprise"
        },
        "member_count": 25,
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
      },
      {
        "id": "org_002",
        "name": "Startup Inc",
        "description": "Startup team",
        "metadata": {},
        "member_count": 5,
        "created_at": "2025-03-10T00:00:00Z",
        "updated_at": "2025-03-10T00:00:00Z"
      }
    ],
    "total": 12,
    "page": 1,
    "page_size": 10
  }
}

创建组织

`POST /api/v1/organizations`

创建一个新组织。

请求体：

字段	类型	必填	说明
`name`	string	是	组织名称
`description`	string	否	组织描述
`metadata`	object	否	自定义元数据（JSON 对象）

请求示例：

bash

curl -X POST https://your-domain/api/v1/organizations \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "description": "Enterprise customer organization",
    "metadata": {
      "industry": "technology",
      "plan": "enterprise"
    }
  }'

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "org_003",
    "name": "Acme Corporation",
    "description": "Enterprise customer organization",
    "metadata": {
      "industry": "technology",
      "plan": "enterprise"
    },
    "member_count": 0,
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T08:00:00Z"
  }
}

获取组织详情

`GET /api/v1/organizations/:id`

根据组织 ID 获取组织详细信息。

路径参数：

参数	类型	说明
`id`	string	组织 ID

请求示例：

bash

curl -X GET https://your-domain/api/v1/organizations/org_003 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "org_003",
    "name": "Acme Corporation",
    "description": "Enterprise customer organization",
    "metadata": {
      "industry": "technology",
      "plan": "enterprise"
    },
    "member_count": 25,
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T08:00:00Z"
  }
}

更新组织

`PATCH /api/v1/organizations/:id`

更新组织信息。仅传入需要修改的字段。

路径参数：

参数	类型	说明
`id`	string	组织 ID

请求体：

字段	类型	必填	说明
`name`	string	否	组织名称
`description`	string	否	组织描述
`metadata`	object	否	自定义元数据（全量替换）

请求示例：

bash

curl -X PATCH https://your-domain/api/v1/organizations/org_003 \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "metadata": {
      "industry": "technology",
      "plan": "premium",
      "region": "asia-pacific"
    }
  }'

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "org_003",
    "name": "Acme Corp",
    "description": "Enterprise customer organization",
    "metadata": {
      "industry": "technology",
      "plan": "premium",
      "region": "asia-pacific"
    },
    "member_count": 25,
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T14:00:00Z"
  }
}

删除组织

`DELETE /api/v1/organizations/:id`

删除指定组织。删除后所有成员关系和角色分配将被同步清除。

路径参数：

参数	类型	说明
`id`	string	组织 ID

请求示例：

bash

curl -X DELETE https://your-domain/api/v1/organizations/org_003 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

json

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

组织成员管理

获取组织成员列表

`GET /api/v1/organizations/:id/users`

分页获取组织内的成员列表。

路径参数：

参数	类型	说明
`id`	string	组织 ID

查询参数：

参数	类型	必填	默认值	说明
`page`	integer	否	1	页码
`page_size`	integer	否	20	每页条数

请求示例：

bash

curl -X GET "https://your-domain/api/v1/organizations/org_003/users?page=1&page_size=10" \
  -H "Authorization: Bearer <admin_token>"

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "data": [
      {
        "id": "usr_abc123",
        "username": "john_doe",
        "name": "John Doe",
        "email": "john@example.com",
        "avatar": "https://example.com/avatar.png",
        "joined_at": "2025-02-01T00:00:00Z"
      },
      {
        "id": "usr_def456",
        "username": "jane_smith",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "avatar": null,
        "joined_at": "2025-03-15T00:00:00Z"
      }
    ],
    "total": 25,
    "page": 1,
    "page_size": 10
  }
}

添加组织成员

`POST /api/v1/organizations/:id/users`

批量将用户添加到组织中。

路径参数：

参数	类型	说明
`id`	string	组织 ID

请求体：

字段	类型	必填	说明
`user_ids`	string[]	是	要添加的用户 ID 数组

请求示例：

bash

curl -X POST https://your-domain/api/v1/organizations/org_003/users \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["usr_abc123", "usr_def456"]
  }'

成功响应：

json

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

错误响应（用户已是成员）：

json

{
  "code": 400,
  "message": "用户已经是该组织的成员",
  "result": ""
}

移除组织成员

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

从组织中移除指定成员。移除后该成员在组织内的角色分配将同步清除。

路径参数：

参数	类型	说明
`id`	string	组织 ID
`userId`	string	用户 ID

请求示例：

bash

curl -X DELETE https://your-domain/api/v1/organizations/org_003/users/usr_abc123 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

json

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

成员角色管理

获取成员的组织角色

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

获取指定成员在组织内被分配的所有角色。

路径参数：

参数	类型	说明
`id`	string	组织 ID
`userId`	string	用户 ID

请求示例：

bash

curl -X GET https://your-domain/api/v1/organizations/org_003/users/usr_abc123/roles \
  -H "Authorization: Bearer <admin_token>"

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "id": "org_role_001",
      "name": "org-admin",
      "description": "Organization administrator"
    },
    {
      "id": "org_role_002",
      "name": "org-member",
      "description": "Organization regular member"
    }
  ]
}

分配成员的组织角色

`PUT /api/v1/organizations/:id/users/:userId/roles`

为指定成员分配组织角色。此操作为全量替换，将覆盖该成员在组织内当前的所有角色分配。

路径参数：

参数	类型	说明
`id`	string	组织 ID
`userId`	string	用户 ID

请求体：

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

请求示例：

bash

curl -X PUT https://your-domain/api/v1/organizations/org_003/users/usr_abc123/roles \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_role_ids": ["org_role_001", "org_role_002"]
  }'

成功响应：

json

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

组织角色模板

组织角色模板是租户级别的共享角色定义，可在所有组织中复用。与系统级角色不同，组织角色模板专用于组织内部的权限管理。

获取角色模板列表

`GET /api/v1/organization-roles`

分页获取组织角色模板列表。

查询参数：

参数	类型	必填	默认值	说明
`page`	integer	否	1	页码
`page_size`	integer	否	20	每页条数

请求示例：

bash

curl -X GET "https://your-domain/api/v1/organization-roles?page=1&page_size=10" \
  -H "Authorization: Bearer <admin_token>"

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "data": [
      {
        "id": "org_role_001",
        "name": "org-admin",
        "description": "Organization administrator with full access",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
      },
      {
        "id": "org_role_002",
        "name": "org-member",
        "description": "Organization regular member",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
      }
    ],
    "total": 3,
    "page": 1,
    "page_size": 10
  }
}

创建角色模板

`POST /api/v1/organization-roles`

创建一个新的组织角色模板。

请求体：

字段	类型	必填	说明
`name`	string	是	角色名称，需唯一
`description`	string	否	角色描述

请求示例：

bash

curl -X POST https://your-domain/api/v1/organization-roles \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "org-viewer",
    "description": "Organization read-only viewer"
  }'

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "org_role_003",
    "name": "org-viewer",
    "description": "Organization read-only viewer",
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T08:00:00Z"
  }
}

获取角色模板详情

`GET /api/v1/organization-roles/:id`

根据 ID 获取组织角色模板详情。

路径参数：

参数	类型	说明
`id`	string	组织角色模板 ID

请求示例：

bash

curl -X GET https://your-domain/api/v1/organization-roles/org_role_003 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "org_role_003",
    "name": "org-viewer",
    "description": "Organization read-only viewer",
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T08:00:00Z"
  }
}

更新角色模板

`PATCH /api/v1/organization-roles/:id`

更新组织角色模板信息。仅传入需要修改的字段。

路径参数：

参数	类型	说明
`id`	string	组织角色模板 ID

请求体：

字段	类型	必填	说明
`name`	string	否	角色名称
`description`	string	否	角色描述

请求示例：

bash

curl -X PATCH https://your-domain/api/v1/organization-roles/org_role_003 \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Organization read-only viewer (no write access)"
  }'

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "org_role_003",
    "name": "org-viewer",
    "description": "Organization read-only viewer (no write access)",
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T14:00:00Z"
  }
}

删除角色模板

`DELETE /api/v1/organization-roles/:id`

删除指定的组织角色模板。删除后所有组织中使用该角色的成员分配将被同步清除。

路径参数：

参数	类型	说明
`id`	string	组织角色模板 ID

请求示例：

bash

curl -X DELETE https://your-domain/api/v1/organization-roles/org_role_003 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

json

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

获取角色模板绑定的组织权限

`GET /api/v1/organization-roles/:id/scopes`

获取指定角色模板关联的所有权限模板。

路径参数：

参数	类型	说明
`id`	string	组织角色模板 ID

请求示例：

bash

curl -X GET https://your-domain/api/v1/organization-roles/org_role_001/scopes \
  -H "Authorization: Bearer <admin_token>"

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "id": "org_perm_001",
      "name": "org:manage:members",
      "description": "Manage organization members"
    },
    {
      "id": "org_perm_002",
      "name": "org:manage:settings",
      "description": "Manage organization settings"
    },
    {
      "id": "org_perm_003",
      "name": "org:read:data",
      "description": "Read organization data"
    }
  ]
}

分配角色模板的组织权限

`PUT /api/v1/organization-roles/:id/scopes`

为指定角色模板分配权限。此操作为全量替换，将覆盖角色模板当前的所有权限分配。

路径参数：

参数	类型	说明
`id`	string	组织角色模板 ID

请求体：

字段	类型	必填	说明
`scope_ids`	string[]	是	组织权限模板 ID 数组

请求示例：

bash

curl -X PUT https://your-domain/api/v1/organization-roles/org_role_001/scopes \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_ids": ["org_perm_001", "org_perm_002", "org_perm_003"]
  }'

成功响应：

json

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

组织权限模板

组织权限模板是租户级别的共享权限定义，可分配给组织角色模板以构建灵活的组织内权限体系。

获取权限模板列表

`GET /api/v1/organization-permissions`

分页获取组织权限模板列表。

查询参数：

参数	类型	必填	默认值	说明
`page`	integer	否	1	页码
`page_size`	integer	否	20	每页条数

请求示例：

bash

curl -X GET "https://your-domain/api/v1/organization-permissions?page=1&page_size=20" \
  -H "Authorization: Bearer <admin_token>"

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "data": [
      {
        "id": "org_perm_001",
        "name": "org:manage:members",
        "description": "Manage organization members",
        "created_at": "2025-01-01T00:00:00Z"
      },
      {
        "id": "org_perm_002",
        "name": "org:manage:settings",
        "description": "Manage organization settings",
        "created_at": "2025-01-01T00:00:00Z"
      },
      {
        "id": "org_perm_003",
        "name": "org:read:data",
        "description": "Read organization data",
        "created_at": "2025-01-01T00:00:00Z"
      }
    ],
    "total": 3,
    "page": 1,
    "page_size": 20
  }
}

创建权限模板

`POST /api/v1/organization-permissions`

创建一个新的组织权限模板。

请求体：

字段	类型	必填	说明
`name`	string	是	权限名称（建议使用 `resource:action` 格式），需唯一
`description`	string	否	权限描述

请求示例：

bash

curl -X POST https://your-domain/api/v1/organization-permissions \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "org:manage:billing",
    "description": "Manage organization billing and invoices"
  }'

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "org_perm_004",
    "name": "org:manage:billing",
    "description": "Manage organization billing and invoices",
    "created_at": "2025-06-15T08:00:00Z"
  }
}

删除权限模板

`DELETE /api/v1/organization-permissions/:id`

删除指定的组织权限模板。删除后所有引用该权限的角色模板将自动取消关联。

路径参数：

参数	类型	说明
`id`	string	组织权限模板 ID

请求示例：

bash

curl -X DELETE https://your-domain/api/v1/organization-permissions/org_perm_004 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

json

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

组织管理 API ​

概念说明 ​

组织管理 ​

获取组织列表 ​

GET /api/v1/organizations ​

创建组织 ​

POST /api/v1/organizations ​

获取组织详情 ​

GET /api/v1/organizations/:id ​

更新组织 ​

PATCH /api/v1/organizations/:id ​

删除组织 ​

DELETE /api/v1/organizations/:id ​

组织成员管理 ​

获取组织成员列表 ​

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 ​

组织角色模板 ​

获取角色模板列表 ​

GET /api/v1/organization-roles ​

创建角色模板 ​

POST /api/v1/organization-roles ​

获取角色模板详情 ​

GET /api/v1/organization-roles/:id ​

更新角色模板 ​

PATCH /api/v1/organization-roles/:id ​

删除角色模板 ​

DELETE /api/v1/organization-roles/:id ​

获取角色模板绑定的组织权限 ​

GET /api/v1/organization-roles/:id/scopes ​

分配角色模板的组织权限 ​

PUT /api/v1/organization-roles/:id/scopes ​

组织权限模板 ​

获取权限模板列表 ​

GET /api/v1/organization-permissions ​

创建权限模板 ​

POST /api/v1/organization-permissions ​

删除权限模板 ​

DELETE /api/v1/organization-permissions/:id ​

组织管理 API

概念说明

组织管理

获取组织列表

`GET /api/v1/organizations`

创建组织

`POST /api/v1/organizations`

获取组织详情

`GET /api/v1/organizations/:id`

更新组织

`PATCH /api/v1/organizations/:id`

删除组织

`DELETE /api/v1/organizations/:id`

组织成员管理

获取组织成员列表

`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`

组织角色模板

获取角色模板列表

`GET /api/v1/organization-roles`

创建角色模板

`POST /api/v1/organization-roles`

获取角色模板详情

`GET /api/v1/organization-roles/:id`

更新角色模板

`PATCH /api/v1/organization-roles/:id`

删除角色模板

`DELETE /api/v1/organization-roles/:id`

获取角色模板绑定的组织权限

`GET /api/v1/organization-roles/:id/scopes`

分配角色模板的组织权限

`PUT /api/v1/organization-roles/:id/scopes`

组织权限模板

获取权限模板列表

`GET /api/v1/organization-permissions`

创建权限模板

`POST /api/v1/organization-permissions`

删除权限模板

`DELETE /api/v1/organization-permissions/:id`