Core concepts

Outcome

你可以用一张关系图定位每个 Nexus 概念，并避免把身份、Access、Credential、Plan 和 Quota 混为同一件事。

Organization ── Member ── User                 Admin Plane
                         │
Workspace ── WorkspaceAccess ── User           Data Plane
    │              │
    │              ├── WorkspacePlan ── PlanStrategyBinding ── QuotaStrategy
    │              ├── QuotaPeriod ── QuotaReservation
    │              └── ApiKeyBinding ← Inference Key
    │
    └── ProviderConnection[] ← providerConnectionId in Gateway Base URL

Configuration boundary

Workspace

应用或环境的配置与隔离边界。ProviderConnection、WorkspacePlan、PlanStrategy、WorkspaceAccess、Quota 和 Usage 都属于一个 Workspace。

ProviderConnection

Workspace 内一条明确的上游能力连接，包含服务生成的不可变 UUID、上游 Base URL、Protocol Profile、状态和加密 Provider Secret。多条 Connection 表示多个可显式选择的目标，不代表自动选择。

Identity and access

Better Auth User

共享的身份记录。它可以通过 Organization Member 进入控制面，也可以通过 WorkspaceAccess 进入数据面；两种关系独立存在。

WorkspaceAccess

一个 User 在一个 Workspace 的数据面使用权，绑定当前 WorkspacePlan、Access 状态和有效期。它不是 API Key，也不是 Organization Membership。

ApiKeyBinding

把一把 Inference Key 的 Better Auth Key ID 指向 WorkspaceAccess。Gateway 的授权解析必须经过这条数据库关系。

Plans and quota

WorkspacePlan

Free、Pro 等稳定产品套餐。Access 绑定 Plan；Plan 通过带生效区间的 PlanStrategyBinding 启用类型化策略。

QuotaStrategy

MVP 唯一实现的 Plan Strategy，定义周期 Quota Units、整数 PPM 倍率、重置周期和最大输出上限。它不包含模型列表、Provider 成本或支付售价。

QuotaPeriod

某条 WorkspaceAccess 在一个时间区间内的额度快照。它保存 Granted、Reserved、Consumed 和创建时的策略快照。

QuotaReservation

请求进入 Provider 前原子创建的额度预留。它处理并发和 Streaming，并最终进入 SETTLED、RELEASED 或 EXPIRED。

Three invariants to remember

1. Inference Key 通过 ApiKeyBinding → WorkspaceAccess → Workspace 解析。
2. Gateway 用 (workspaceId, providerConnectionId) 读取连接，客户端不能指定上游 Host。
3. ApiKey.expiresAt、WorkspaceAccess.accessEndsAt 与 QuotaPeriod.periodEnd 是三个独立时间边界。

Next steps

• Glossary
• Credential model
• Workspace plans