# API 参考：组织与共享

路由注册：`internal/router/router.go` 的 `RegisterOrganizationRoutes`。Handler：`internal/handler/organization.go`。

组织（Organization）以“空间（tenant）”为成员单位。组织组路由的 API key 策略为 `manage_spaces` 或 full-access；KB/Agent 分享管理仅 full-access key 可用。

## 组织管理（/api/v1/organizations）

### POST /api/v1/organizations

用途：创建组织。权限：Admin+。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 组织名称 |
| `description` | string | 否 | 描述 |
| `avatar` | string | 否 | 头像 URL |
| `searchable` | bool | 否 | 是否可被搜索发现 |
| `require_approval` | bool | 否 | 加入是否需审批 |
| `member_limit` | int | 否 | 成员空间数上限 |
| `invite_code_validity_days` | int | 否 | 邀请码有效期（天） |

响应：201 `{"success":true,"data":{OrganizationResponse}}`

```bash
curl -X POST $BASE/api/v1/organizations -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"name":"研发组织"}'
```

### GET /api/v1/organizations

用途：列出我所在的组织。权限：Viewer+。

响应：200 `{"success":true,"data":{"organizations":[...],"total":N,"resource_counts":{"knowledge_bases":{"by_organization":{}},"agents":{"by_organization":{}}}}}`

```bash
curl $BASE/api/v1/organizations -H "Authorization: Bearer $TOKEN"
```

### GET /api/v1/organizations/preview/:code

用途：按邀请码预览组织（不加入）。权限：Viewer+。路径参数：`code` 邀请码。

响应：200 `{"success":true,"data":{id,name,description,avatar,member_count,share_count,agent_share_count,is_already_member,require_approval,created_at}}`

```bash
curl $BASE/api/v1/organizations/preview/ABC123 -H "Authorization: Bearer $TOKEN"
```

### POST /api/v1/organizations/join

用途：凭邀请码加入组织。权限：Admin+。请求体：`{"invite_code":"..."}`（必填）。

响应：200 `{"success":true,"data":{OrganizationResponse}}`

```bash
curl -X POST $BASE/api/v1/organizations/join -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"invite_code":"ABC123"}'
```

### POST /api/v1/organizations/join-request

用途：提交加入申请（需审批的组织）。权限：Admin+。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `invite_code` | string | 是 | 邀请码 |
| `message` | string | 否 | 申请附言 |
| `role` | string | 否 | 期望角色 |

响应：200 `{"success":true,"data":{JoinRequest}}`

```bash
curl -X POST $BASE/api/v1/organizations/join-request -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"invite_code":"ABC123","message":"申请加入"}'
```

### GET /api/v1/organizations/search

用途：搜索可发现（searchable）的组织。权限：Viewer+。

| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `q` | string | 否 | 关键字 |
| `limit` | int | 否 | 默认 20，上限 100 |

响应：200 `{"success":true,"data":[SearchableOrganization],"total":N}`

```bash
curl "$BASE/api/v1/organizations/search?q=研发" -H "Authorization: Bearer $TOKEN"
```

### POST /api/v1/organizations/join-by-id

用途：按组织 ID 加入可发现组织（无需邀请码）。权限：Admin+。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `organization_id` | string | 是 | 目标组织 ID |
| `message` | string | 否 | 附言 |
| `role` | string | 否 | 期望角色 |

响应：200 `{"success":true,"data":{OrganizationResponse}}`

```bash
curl -X POST $BASE/api/v1/organizations/join-by-id -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"organization_id":"org-1"}'
```

### GET /api/v1/organizations/:id

用途：组织详情。权限：Viewer+。

响应：200 `{"success":true,"data":{OrganizationResponse}}`

```bash
curl $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN"
```

### PUT /api/v1/organizations/:id

用途：更新组织（服务层校验调用者空间为组织 owner）。权限：Admin+。请求体字段同创建（均可选）。

响应：200 `{"success":true,"data":{OrganizationResponse}}`

```bash
curl -X PUT $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"description":"更新描述"}'
```

### DELETE /api/v1/organizations/:id

用途：删除组织。权限：Admin+（服务层要求组织 owner）。

响应：200 `{"success":true,"message":"Organization deleted successfully"}`

```bash
curl -X DELETE $BASE/api/v1/organizations/org-1 -H "Authorization: Bearer $TOKEN"
```

### POST /api/v1/organizations/:id/leave

用途：本空间退出组织。权限：Admin+。无请求体。

响应：200 `{"success":true,"message":"Left organization successfully"}`

```bash
curl -X POST $BASE/api/v1/organizations/org-1/leave -H "Authorization: Bearer $TOKEN"
```

### POST /api/v1/organizations/:id/request-upgrade

用途：申请提升本空间在组织内的角色。权限：Admin+。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `requested_role` | string | 是 | 期望的组织角色（`viewer/editor/admin`） |
| `message` | string | 否 | 附言 |

响应：200 `{"success":true,"data":{JoinRequest}}`

```bash
curl -X POST $BASE/api/v1/organizations/org-1/request-upgrade -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"requested_role":"editor"}'
```

### POST /api/v1/organizations/:id/invite-code

用途：生成组织邀请码。权限：Admin+（服务层要求组织 admin）。无请求体。

响应：200 `{"success":true,"data":{"invite_code":"..."}}`

```bash
curl -X POST $BASE/api/v1/organizations/org-1/invite-code -H "Authorization: Bearer $TOKEN"
```

### GET /api/v1/organizations/:id/search-tenants

用途：搜索可邀请的空间（返回按空间分组的候选）。权限：Admin+。

| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `q` | string | 是 | 空间名关键字 |
| `limit` | int | 否 | 默认 10，上限 50 |

响应：200 `{"success":true,"data":[{"tenant_id","tenant_name"}]}`

```bash
curl "$BASE/api/v1/organizations/org-1/search-tenants?q=demo" -H "Authorization: Bearer $TOKEN"
```

### GET /api/v1/organizations/:id/search-users

用途：已废弃别名，行为同 `search-tenants`（返回空间分组结果）。权限：Admin+。参数同上。

```bash
curl "$BASE/api/v1/organizations/org-1/search-users?q=demo" -H "Authorization: Bearer $TOKEN"
```

### POST /api/v1/organizations/:id/invite

用途：直接邀请空间加入组织。权限：Admin+。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `tenant_id` | uint64 | 二选一 | 目标空间 ID（推荐） |
| `user_id` | string | 二选一 | 兼容路径：用户 ID（解析为其空间） |
| `representative_user_id` | string | 否 | 该空间的代表用户 |
| `role` | string | 是 | 组织内角色 |

响应：200 `{"success":true,"message":"Member added successfully"}`

```bash
curl -X POST $BASE/api/v1/organizations/org-1/invite -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"tenant_id":2,"role":"viewer"}'
```

### GET /api/v1/organizations/:id/members

用途：组织成员（空间）列表。权限：Viewer+。

响应：200 `{"success":true,"data":{"members":[{id,user_id,representative_user_id,role,tenant_id,tenant_name,username,email,avatar,joined_at}],"total":N}}`

```bash
curl $BASE/api/v1/organizations/org-1/members -H "Authorization: Bearer $TOKEN"
```

### PUT /api/v1/organizations/:id/members/:tenant_id

用途：修改成员空间的组织角色。权限：Admin+。路径参数 `tenant_id` 为成员空间 ID。请求体：`{"role":"editor"}`（必填，`viewer/editor/admin`）。

响应：200 `{"success":true,"message":"Member role updated successfully"}`

```bash
curl -X PUT $BASE/api/v1/organizations/org-1/members/2 -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"role":"editor"}'
```

### DELETE /api/v1/organizations/:id/members/:tenant_id

用途：移除成员空间（含自移除）。权限：Admin+。

响应：200 `{"success":true,"message":"Member removed successfully"}`

```bash
curl -X DELETE $BASE/api/v1/organizations/org-1/members/2 -H "Authorization: Bearer $TOKEN"
```

### GET /api/v1/organizations/:id/join-requests

用途：加入申请队列。权限：Admin+。

响应：200 `{"success":true,"data":{"requests":[{id,user_id,username,email,message,request_type,prev_role,requested_role,status,created_at,reviewed_at}],"total":N}}`

```bash
curl $BASE/api/v1/organizations/org-1/join-requests -H "Authorization: Bearer $TOKEN"
```

### PUT /api/v1/organizations/:id/join-requests/:request_id/review

用途：审批加入/升级申请。权限：Admin+。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `approved` | bool | 是 | 通过/拒绝 |
| `message` | string | 否 | 审批意见 |
| `role` | string | 否 | 通过时授予的角色 |

响应：200 `{"success":true,"message":"Review completed"}`

```bash
curl -X PUT $BASE/api/v1/organizations/org-1/join-requests/req-1/review \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"approved":true}'
```

### GET /api/v1/organizations/:id/shares

用途：查看共享到该组织的 KB 列表。权限：Viewer+。

响应：200 `{"success":true,"data":{"shares":[KnowledgeBaseShareResponse],"total":N}}`

```bash
curl $BASE/api/v1/organizations/org-1/shares -H "Authorization: Bearer $TOKEN"
```

### GET /api/v1/organizations/:id/agent-shares

用途：查看共享到该组织的 Agent 列表。权限：Viewer+。

响应：200 `{"success":true,"data":{"shares":[AgentShareResponse],"total":N}}`

```bash
curl $BASE/api/v1/organizations/org-1/agent-shares -H "Authorization: Bearer $TOKEN"
```

### GET /api/v1/organizations/:id/shared-knowledge-bases

用途：组织空间视图：组织内全部共享 KB（含我自己的）。权限：Viewer+。

响应：200 `{"success":true,"data":[...含 is_mine、source_from_agent 标记...],"total":N}`

```bash
curl $BASE/api/v1/organizations/org-1/shared-knowledge-bases -H "Authorization: Bearer $TOKEN"
```

### GET /api/v1/organizations/:id/shared-agents

用途：组织空间视图：组织内全部共享 Agent。权限：Viewer+。

响应：200 `{"success":true,"data":[SharedAgentInfo],"total":N}`

```bash
curl $BASE/api/v1/organizations/org-1/shared-agents -H "Authorization: Bearer $TOKEN"
```

## KB 分享（/api/v1/knowledge-bases/:id/shares）

API key：仅 full-access。Handler: `internal/handler/organization.go`

### POST /api/v1/knowledge-bases/:id/shares

用途：把 KB 分享到组织。权限：KB 创建者 OR Admin+。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `organization_id` | string | 是 | 目标组织 |
| `permission` | string | 是 | 共享权限（组织角色语义，如 `viewer/editor`） |

响应：201 `{"success":true,"data":{KBShare}}`

```bash
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/shares -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"organization_id":"org-1","permission":"viewer"}'
```

### GET /api/v1/knowledge-bases/:id/shares

用途：查看该 KB 的分享列表。权限：Viewer+。

响应：200 `{"success":true,"data":{"shares":[KnowledgeBaseShareResponse],"total":N}}`

```bash
curl $BASE/api/v1/knowledge-bases/kb-1/shares -H "Authorization: Bearer $TOKEN"
```

### PUT /api/v1/knowledge-bases/:id/shares/:share_id

用途：修改分享权限。权限：KB 创建者 OR Admin+。请求体：`{"permission":"editor"}`（必填）。

响应：200 `{"success":true,"message":"Share permission updated successfully"}`

```bash
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/shares/s-1 -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"permission":"editor"}'
```

### DELETE /api/v1/knowledge-bases/:id/shares/:share_id

用途：取消分享。权限：KB 创建者 OR Admin+。

响应：200 `{"success":true,"message":"Share removed successfully"}`

```bash
curl -X DELETE $BASE/api/v1/knowledge-bases/kb-1/shares/s-1 -H "Authorization: Bearer $TOKEN"
```

## Agent 分享（/api/v1/agents/:id/shares）

API key：仅 full-access。Handler: `internal/handler/organization.go`

### POST /api/v1/agents/:id/shares

用途：把 Agent 分享到组织。权限：Agent 创建者 OR Admin+。请求体同 KB 分享（`organization_id` + `permission`，必填）。

响应：201 `{"success":true,"data":{AgentShare}}`

```bash
curl -X POST $BASE/api/v1/agents/agent-1/shares -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"organization_id":"org-1","permission":"viewer"}'
```

### GET /api/v1/agents/:id/shares

用途：查看该 Agent 的分享列表。权限：Agent 创建者 OR Admin+。

响应：200 `{"success":true,"data":{"shares":[AgentShareResponse],"total":N}}`

```bash
curl $BASE/api/v1/agents/agent-1/shares -H "Authorization: Bearer $TOKEN"
```

### DELETE /api/v1/agents/:id/shares/:share_id

用途：取消 Agent 分享。权限：Agent 创建者 OR Admin+。

响应：200 `{"success":true,"message":"Share removed successfully"}`

```bash
curl -X DELETE $BASE/api/v1/agents/agent-1/shares/s-1 -H "Authorization: Bearer $TOKEN"
```

## 共享资源聚合视图

### GET /api/v1/shared-knowledge-bases

用途：列出通过组织共享给我的 KB（去除属主侧向量库元数据）。权限：Viewer+；API key 需 `manage_spaces` 或 full-access。

响应：200 `{"success":true,"data":[...],"total":N}`

```bash
curl $BASE/api/v1/shared-knowledge-bases -H "Authorization: Bearer $TOKEN"
```

### GET /api/v1/shared-agents

用途：列出通过组织共享给我的 Agent。权限：Viewer+；API key 同上。

响应：200 `{"success":true,"data":[SharedAgentInfo],"total":N}`。`SharedAgentInfo` 含 `source_tenant_id`（来源空间）、`org_name`、`shared_by_username`、`permission`，以及 `web_search_ready`——只返回「来源空间的联网搜索是否可用」这一个布尔位，不下发来源空间的 provider 配置（会泄露配置），也不拿接收方空间的 provider ID 去比对（会误报不可用）。

使用共享 Agent 调用其它接口时，若同名 Agent 被多个空间共享，可带 `agent_source_tenant_id` 指明来源空间；该值会与共享关系逐一校验，非法或无权限时直接报错，不会静默回退到别的来源。

```bash
curl $BASE/api/v1/shared-agents -H "Authorization: Bearer $TOKEN"
```

### POST /api/v1/shared-agents/disabled

用途：设置“本空间禁用某共享 Agent”（影响整个空间的会话下拉）。权限：Admin+；API key 同上。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `agent_id` | string | 是（`binding:"required"`） | 共享 Agent ID |
| `disabled` | bool | 否 | 是否禁用（默认 false） |

响应：200 `{"success":true}`

```bash
curl -X POST $BASE/api/v1/shared-agents/disabled -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"agent_id":"agent-1","disabled":true}'
```