> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 会员计划

## 背景

Xpert 同时支持租户级和组织级的智能能力配置：

* 租户可以提供统一的大语言模型，作为整个平台的默认智能能力。
* 组织可以配置自己的大语言模型，用于满足本组织的模型、成本、合规或私有化需求。
* 用户在组织内使用智能助手、ClawXpert、工作空间助手或其它智能助理能力时，需要明确由哪一层会员计划控制额度、限流和用量统计。

如果只用“当前组织是否配置了大语言模型”来判断模型可用性，会产生几个产品问题：

* 组织配置了自己的模型但没有初始化组织会员计划时，用户可能因为作用域不匹配被拒绝。
* 组织移除租户计划后，希望进入组织自管模式，但模型列表和聊天仍可能按照租户回退逻辑工作。
* 用量统计可能落在错误作用域，导致“使用概览”和“使用情况和计费”无法解释。
* 产品上无法清晰表达“租户统一供给”和“组织自管智能能力成本”两种模式。

因此会员计划需要成为大语言模型可用性、限制和用量归属的统一决策中心。

## 产品目标

### 目标

* 明确租户会员计划与组织会员计划的边界。
* 让组织可以在“继承租户智能能力”和“组织自管智能能力”之间平滑切换。
* 当组织启用本地大语言模型时，系统自动补齐组织会员初始化，避免用户聊天被技术性错误阻断。
* 所有额度限制、速率限制、用量台账和使用概览都落到可解释的作用域。
* 支持无限量计划，用于组织自有模型或内部成本不需要按点数限制的场景。

### 非目标

* 不把租户计划与组织计划做叠加扣费。
* 不允许组织会员限制租户大语言模型，也不允许租户会员直接限制组织大语言模型。
* 不在用户聊天链路里创建复杂的计划选择交互。
* 不在这次设计里引入真实支付、订阅续费或发票能力。

## 核心概念

| 概念      | 说明                                                  |
| ------- | --------------------------------------------------- |
| 租户会员计划  | 租户作用域的计划，控制租户提供的大语言模型。                              |
| 组织会员计划  | 组织作用域的计划，控制当前组织自己的大语言模型。                            |
| 有效会员作用域 | 当前请求最终命中的会员作用域，决定可用模型、限制和记账位置。                      |
| 租户大语言模型 | `organizationId = null` 的模型，由租户提供。                  |
| 组织大语言模型 | `organizationId = 当前组织 ID` 的模型，由组织提供。               |
| 计费用户    | 实际被扣点或记录用量的用户。普通聊天是当前用户；使用数字专家时可按数字专家创建者解析。         |
| 无限量计划   | `includedPoints = null` 的计划，不限制总点数，但仍记录用量并执行显式速率限制。 |

## 产品模式

### 1. 租户统一供给模式

适用场景：

* 新租户初始化后希望快速让所有组织使用统一智能能力。
* 平台方统一配置模型供应商和大语言模型。
* 组织不需要自定义模型，也不独立承担智能能力成本。

产品行为：

* 租户管理员在租户作用域配置会员计划。
* 新用户默认获得租户作用域会员。
* 组织内没有启用中的组织会员计划时，组织用户回退使用租户会员。
* 用户只能看到租户作用域下已启用的大语言模型。
* 聊天、用量、台账都记录在租户会员上。

### 2. 组织自管模式

适用场景：

* 组织管理员配置了自己的模型供应商或大语言模型。
* 组织希望自己控制模型可用性、额度、速率限制和用量统计。
* 组织希望移除租户统一额度限制，改用自己的无限量或定额计划。

产品行为：

* 当前组织只要存在启用中的组织会员计划，就进入组织自管模式。
* 组织请求优先使用组织会员，不再回退租户会员。
* 用户只能看到当前组织作用域下已启用的大语言模型。
* 聊天、用量、台账都记录在组织会员上。
* 如果组织没有已启用的本地大语言模型，即使存在组织计划，也返回空模型列表，不回退租户模型。

### 3. 组织本地模型自动自愈模式

适用场景：

* 历史数据中组织已经配置了本地大语言模型，但没有初始化组织会员计划。
* 组织管理员在首次登录向导或设置页移除了租户会员计划，希望组织进入自管模式。
* 用户已经在组织里打开 ClawXpert 或智能助手并开始对话。

产品行为：

* 系统发现组织作用域下存在已启用的本地大语言模型，且组织没有会员计划时，会执行一次幂等初始化。
* 初始化会创建组织默认无限量计划，并给当前组织所有活跃成员分配会员。
* 初始化完成后，只返回组织大语言模型。
* 后续聊天、限制和台账都落在组织作用域。

## 作用域决策规则

### 组织请求

组织作用域下的请求按以下顺序解析有效会员：

1. 查找当前组织作用域的启用中会员。
2. 如果存在，使用组织会员。
3. 如果当前组织存在启用中的会员计划，但当前用户没有会员，则拒绝使用，不回退租户。
4. 如果当前组织没有启用中的会员计划，查找租户作用域会员。
5. 如果存在租户会员，使用租户会员。
6. 如果两者都不存在，不返回可用模型，也不能聊天。

### 租户请求

租户作用域请求只查找租户会员：

1. 查找租户作用域的启用中会员。
2. 如果存在，使用租户会员。
3. 如果不存在，不返回可用模型，也不能聊天。

### 大语言模型作用域校验

有效会员作用域必须与大语言模型作用域一致：

| 请求作用域 | 有效会员 | 大语言模型   | 结果        |
| ----- | ---- | ------- | --------- |
| 租户    | 租户   | 租户大语言模型 | 允许        |
| 租户    | 租户   | 组织大语言模型 | 拒绝        |
| 组织    | 租户回退 | 租户大语言模型 | 允许        |
| 组织    | 租户回退 | 组织大语言模型 | 触发组织自愈或拒绝 |
| 组织    | 组织   | 组织大语言模型 | 允许        |
| 组织    | 组织   | 租户大语言模型 | 拒绝        |

这个规则保证了“谁提供模型，谁的会员计划管模型和用量”。

## 计划初始化设计

### 默认组织计划

组织自愈或手动初始化时创建的默认计划：

```ts theme={null}
{
  code: 'default-unlimited',
  name: 'Default Unlimited',
  includedPoints: null,
  tokensPerPoint: 1000,
  isDefault: true,
  status: 'active'
}
```

产品含义：

* 默认进入无限量模式，避免组织自有模型被总点数意外拦截。
* `tokensPerPoint` 仍保留，用于用量台账、报表和未来成本换算。
* 组织管理员可以后续把无限量改成固定点数计划。

### 初始化策略

初始化必须幂等：

* 已有启用中的默认计划：直接使用。
* 有启用中的计划但没有默认计划：将第一个启用中的计划设为默认。
* 只有已归档的 `default-unlimited`：重新激活并设为默认。
* 没有可用计划：创建新的 `default-unlimited`。
* 给当前组织所有活跃 `UserOrganization` 成员创建启用中的 `UserMembership`。
* 已有启用中会员的成员不覆盖。
* 无限量分配台账的 `pointsDelta = 0`。

### 手动初始化与修复

组织会员页面提供两个产品动作：

* **初始化组织会员**：组织没有计划时执行初始化。
* **修复成员分配**：组织已有计划，但成员分配不完整时补齐。

这两个动作都调用同一个幂等初始化能力。

## 用量与限制

### 点数限制

普通计划：

* `includedPoints` 是当前周期总点数额度。
* 使用模型时按令牌数和倍率换算点数。
* 剩余点数小于等于 0 时拒绝继续使用。

无限量计划：

* `includedPoints = null`。
* 不执行总点数上限检查。
* 仍然计算本次使用点数。
* 仍然写用量台账。
* 仍然执行显式 `rateLimits`。

### 速率限制

速率限制与无限量计划独立：

* 无限量只代表不限制总点数。
* 如果计划配置了按小时、天、周、周期等维度的速率限制，仍然生效。
* 这允许组织使用无限量计划的同时，对单模型或高成本模型设置节流规则。

### 台账归属

台账必须写入有效会员作用域：

* 租户大语言模型用量写入租户会员台账。
* 组织大语言模型用量写入同组织会员台账。
* 作用域不匹配时不写台账，直接拒绝。

用户在“使用概览”和“使用情况和计费”中看到的是当前有效会员对应的用量。

## 页面与用户体验

### 设置入口

`/settings/membership` 是双作用域页面：

* 租户作用域下展示租户会员计划。
* 组织作用域下展示组织会员计划。
* 访问权限使用 `MEMBERSHIP_EDIT`。
* 组织本地管理员拥有该权限即可进入组织会员页面。

### 页面信息架构

页面顶部显示当前作用域状态：

| 信息      | 租户作用域  | 组织作用域      |
| ------- | ------ | ---------- |
| 当前作用域   | 显示租户会员 | 显示组织会员     |
| 启用计划    | 显示     | 显示         |
| 默认计划    | 显示     | 显示         |
| 活跃成员    | 不显示    | 显示         |
| 已分配成员   | 不显示    | 显示         |
| 本地大语言模型 | 不显示    | 显示         |
| 初始化按钮   | 不显示    | 未初始化时显示    |
| 修复按钮    | 不显示    | 成员分配不完整时显示 |

### 空状态

组织作用域下没有计划时：

* 如果组织没有本地大语言模型，可以提示“当前组织仍继承租户智能能力；如需组织自管，请初始化组织会员计划并配置组织大语言模型”。
* 如果组织已经有本地大语言模型，显示初始化按钮，并说明初始化会创建默认无限量计划和成员会员。

### 计划编辑

计划目录和编辑器继续支持：

* 创建计划。
* 编辑计划。
* 设置默认计划。
* 归档计划。
* 配置 `includedPoints`。
* 开启无限量，即保存 `includedPoints = null`。
* 配置 `tokensPerPoint`、模型倍率和速率限制。

## 用户旅程

### 新租户快速启用

1. 租户管理员配置租户大语言模型。
2. 租户管理员配置租户默认会员计划。
3. 新用户被分配租户会员。
4. 用户进入任意组织，如果该组织没有组织计划，则使用租户模型。
5. 用量统计进入租户会员。

### 组织切换为自管

1. 组织管理员进入组织作用域。
2. 配置组织自己的大语言模型。
3. 进入“设置 / 会员”。
4. 点击“初始化组织会员”。
5. 系统创建默认无限量计划，并给活跃成员分配会员。
6. 组织用户只看到组织大语言模型。
7. 用量统计进入组织会员。

### 旧数据自愈

1. 组织已有已启用的本地大语言模型，但没有组织计划。
2. 用户打开 ClawXpert 或请求模型列表。
3. 系统检测到本地大语言模型，并执行幂等初始化。
4. 模型列表返回组织模型。
5. 用户聊天成功，台账写入组织会员。

### 新成员加入已自管组织

1. 新用户加入组织。
2. 用户初始化任务执行。
3. 如果组织已有启用中的会员计划，则给该用户补启用中的会员。
4. 如果组织没有启用中的计划，不做会员初始化。

## 权限设计

| 动作         | 权限                |
| ---------- | ----------------- |
| 查看会员页面     | `MEMBERSHIP_EDIT` |
| 初始化组织会员    | `MEMBERSHIP_EDIT` |
| 修复成员分配     | `MEMBERSHIP_EDIT` |
| 创建、编辑、归档计划 | `MEMBERSHIP_EDIT` |
| 给用户手动分配计划  | `MEMBERSHIP_EDIT` |
| 查看自己的使用概览  | 当前登录用户            |

租户管理员通常在租户作用域管理租户计划。

组织本地管理员在组织作用域管理组织计划。

## 边界与异常

### 组织有计划但没有本地大语言模型

返回空模型列表，不回退租户。

产品含义：组织已经选择自管模式，但还没有配置可用模型，需要管理员补模型。

### 组织有本地大语言模型但没有计划

触发初始化自愈。

产品含义：系统把“组织已经配置本地模型”视为组织自管意图，自动补齐默认会员。

### 用户没有分配

如果组织已有启用中的计划，但用户没有启用中的会员，则拒绝使用并提示需要会员。

管理员可通过“修复成员分配”或用户管理页分配计划。

### 租户会员与组织会员同时存在

组织作用域请求永远优先组织会员。

只有当前组织没有启用中的组织计划时，租户会员才允许用户使用租户大语言模型。

### 删除或归档计划

归档默认计划后，组织可能进入需要修复状态。

管理员需要设置新的启用中默认计划，或执行修复。

## 后续演进

* 支持组织管理员选择初始化时使用固定额度计划还是无限量计划。
* 支持从租户计划批量克隆为组织计划。
* 支持更明确的会员健康检查，例如缺计划、缺默认计划、缺成员分配、无本地模型。
* 支持按供应商/模型展示成本估算，而不仅是点数。
* 支持计划生命周期与真实订阅支付系统对接。