组织 API

组织是 Forgexa 多租户架构的顶层实体。一个组织包含工作空间，管理成员，强制预算，定义共享配置（集成、工作流模板、运行时）。

层级：组织 → 工作空间 → 项目 → 需求 → 执行

创建组织

任何认证用户可以创建组织并成为其 Owner。

POST /api/v1/organizations
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Acme Corp",
  "description": "产品工程部门"
}

响应 201 Created

{
  "id": "uuid",
  "name": "Acme Corp",
  "org_key": "acme-corp",
  "slug": "acme-corp",
  "owner_id": "uuid",
  "description": "产品工程部门",
  "member_count": 1,
  "workspace_count": 0,
  "created_at": "2026-05-16T00:00:00Z"
}

列出组织

返回当前用户所属的所有组织。

GET /api/v1/organizations
Authorization: Bearer <token>

获取组织详情

需要 member 及以上角色。

GET /api/v1/organizations/{org_id}
Authorization: Bearer <token>

更新组织

需要 admin 及以上角色。

PUT /api/v1/organizations/{org_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Acme Corp Engineering",
  "budget_monthly_limit_usd": 2000,
  "budget_alert_threshold": 0.85
}

可更新字段

字段	类型	说明
name	string	组织显示名称
description	string	简要描述
logo_url	string	Logo 图片 URL
registration_mode	string	open 或 invite-only（默认 invite-only）
max_workspaces	int	最大工作空间数（null = 无限制）
max_members	int	最大成员数（null = 无限制）
budget_monthly_limit_usd	float	月度预算上限（null = 无限制）
budget_alert_threshold	float	使用量超过此比例时告警（默认 0.80）

删除组织

需要 owner 角色。级联删除组织内所有工作空间、项目和数据。

DELETE /api/v1/organizations/{org_id}
Authorization: Bearer <token>

WARNING

删除组织将永久移除其所有工作空间、项目、需求、执行及相关数据。此操作不可撤销。

成员管理

查看我的角色

GET /api/v1/organizations/{org_id}/my-role
Authorization: Bearer <token>

列出成员

GET /api/v1/organizations/{org_id}/members
Authorization: Bearer <token>

添加成员

需要 admin 角色。通过邮箱或用户 ID 添加。

POST /api/v1/organizations/{org_id}/members
Content-Type: application/json

{
  "email": "bob@acme.com",
  "role": "member"
}

更新成员角色

PUT /api/v1/organizations/{org_id}/members/{member_user_id}
Content-Type: application/json

{
  "role": "admin"
}

移除成员

DELETE /api/v1/organizations/{org_id}/members/{member_user_id}

转移所有权

仅当前 Owner 可以将所有权转移给现有成员。

POST /api/v1/organizations/{org_id}/transfer-ownership
Content-Type: application/json

{
  "new_owner_id": "uuid"
}

工作流模板

获取模板

GET /api/v1/organizations/{org_id}/workflow-template

设置模板

需要 admin 角色。

PUT /api/v1/organizations/{org_id}/workflow-template
Content-Type: application/json

{
  "template": "# WORKFLOW.md\norchestration:\n  mode: polling\n..."
}

预算

查询预算

GET /api/v1/organizations/{org_id}/budget

设置预算

PUT /api/v1/organizations/{org_id}/budget
Content-Type: application/json

{
  "monthly_limit_usd": 5000,
  "alert_threshold": 0.80
}

审计日志

查询日志

GET /api/v1/organizations/{org_id}/audit-logs?page=1&page_size=20&action=member.added

支持过滤参数：action、actor_id、start_date、end_date、page、page_size。