# 多组织接入

一个 Screenshare 账号可以属于多个组织，并在不同组织中拥有不同角色。API 的授权上下文始终由**密钥绑定组织 + URL 中的组织 ID + 当前成员权限**共同决定。

## 显式绑定，禁止猜测

假设同一个账号是组织 A 的管理员、组织 B 的管理员、组织 C 的普通成员：

| 组织 | 可创建组织密钥 | 可用该密钥访问 |
| --- | --- | --- |
| A | 是 | A 的记录、邀请、工单和权益，仍受 scope 限制 |
| B | 是 | B 的相应能力 |
| C | 否 | 不可因同账号管理 A/B 而获取 C 的 API 权限 |

用 A 的密钥请求 `/v1/partners/B/invitations` 会返回 `403 PARTNER_SCOPE_MISMATCH`。即使创建者同时是 B 的管理员，也不会自动切换。

## 推荐配置模型

在你自己的后台建立“服务器 → 组织 ID → 密钥引用”映射。密钥引用指向环境变量或密钥存储，不直接放在用户可下载的配置中。

```json
{
  "servers": {
    "survival": {"partner_id":"ORGANIZATION_A_ID","key_env":"SCREENSHARE_KEY_A"},
    "minigames": {"partner_id":"ORGANIZATION_B_ID","key_env":"SCREENSHARE_KEY_B"}
  }
}
```

启动时对每份配置调用 `/v1/me`，严格比较返回的 `partner_id`。不要选择组织列表中的第一个组织，不要使用“最近使用的组织”，不要以组织名称代替 ID。

## 一次邀请的业务记录

在调用创建接口**之前**持久化：

| 字段 | 用途 |
| --- | --- |
| `local_request_id` | 你自己的业务主键 |
| `server_id` | 发起请求的服务器 |
| `partner_id` | 明确选定的组织 |
| `credential_reference` | 使用哪份密钥配置，不是完整密钥 |
| `idempotency_key` | 本次调用及所有恢复重试使用的编号 |
| `request_body` | 规范化后的 game 和 notes |
| `invitation_id` | API 成功返回后保存 |
| `ticket_id` | 玩家加入后返回的正式工单 ID |

普通插件玩家不能任意传入 `partner_id` 后就以你的管理员密钥创建邀请。先在你自己的应用中验证操作人的管理员权限，再从可信配置选择组织。

## Webhook 也要按组织分开

每个回调只绑定一个组织并拥有独立签名密钥。多组织应用可以共用接收服务，但建议使用不同路径，如 `/hooks/screenshare/org-a` 和 `/hooks/screenshare/org-b`，以便先按接收配置选择签名密钥。

先验证签名，再信任载荷的 `partner_id`，并核对它与当前回调配置相符。不要根据尚未验签的 `partner_id` 自动选择生产密钥或执行操作。

## 成员权限变化

创建者失去某个组织管理员身份时，该组织相关凭证立即失效，其他组织凭证不受此成员变更影响。接收方应将 `401` 或 `403` 标记为“需要管理员修复凭证”，停止自动重试授权失败，并暂停相应组织的自动任务。