# 管理台

## 模块定位

管理台是 billing 各业务模块的统一操作和查看入口。它不单独保存业务事实，而是通过 CLIProxyAPI 受保护的 Management API 读取或修改 SQLite 中的真实配置与记录。

当前管理台采用单页、紧凑布局，直接作为插件资源嵌入，不依赖 CDN、外部前端框架或独立构建服务。

## 页面结构

| 页面 | 主要用途 |
| --- | --- |
| 用户 Key | 管理用户、访问策略、路由、额度和并发，查看用户汇总与账目 |
| 请求明细 | 分页查看请求结果、上游、Token、性能和成本，执行组合筛选 |
| 价格配置 | 维护本地价格，并搜索、导入和确认更新 models.dev 参考价格 |

页面顶部保留 CPA 管理密钥输入。留空时页面进入匿名只读模式；输入有效密钥后进入管理模式。

## 用户 Key 页面

页面顶部展示今日请求、今日 Token、今日成本、各用户今日用量以及近 7 日 Token 趋势。

Key 列表展示：

- 用户名称和脱敏 Key；
- 启用、禁用或归档状态；
- 当前余额和额度；
- 活跃并发与并发上限；
- 自动或严格上游路由；
- 允许的模型规则。

管理员可以创建 Key，并通过侧边抽屉完成以下操作。列表默认不显示已归档项：

- 修改名称和状态；
- 选择自动路由或指定上游账号；
- 允许全部模型或填写逗号分隔的模型规则；
- 设置额度、并发上限、重置周期和下一次重置时间；
- 立即重置额度；
- 查看最近计费账目；
- 永久归档 Key；
- 查看该用户累计、今日和最近请求。

业务规则和拒绝条件分别由“用户与访问管理”“额度与计费”模块执行，管理台只负责提交和呈现。

## 请求明细页面

请求明细默认每页显示 100 条，页码、上一页、下一页、查询过滤、列和刷新操作位于同一顶部工具区。查询过滤默认折叠，按需展开。

当前筛选项包括：

- 开始和结束时间；
- 用户；
- 模型；
- 成功、失败、拒绝或取消；
- 实际上游；
- Responses、Compact 或 Chat 端点；
- 完整 Request ID。

筛选和分页由服务端执行。应用新筛选会返回第一页；刷新保持当前页和筛选条件。只有页面可见、位于请求明细且处于第一页时才每三秒自动刷新，避免用户查看历史页时列表自行跳动。

“列”用于控制明细表可见字段，不改变服务端保存的数据。

## 价格配置页面

价格页面采用左侧模型列表、右侧编辑区。未选择模型时右侧留空，点击左侧任意模型项后加载价格详情：

- 新增或选择一个精确模型名称；
- 设置输入、缓存读取、缓存写入和输出的基础价格；
- 可选启用长上下文价格；
- 设置长上下文输入门槛及“大于/大于等于”比较方式；
- 可选启用 Fast 价格并设置倍率；
- 保存或删除模型价格。
- 手动更新 models.dev 供应商价格目录；
- 按模型或供应商搜索参考价格，并导入到当前本地模型；
- 查看价格是手动配置还是关联到具体 models.dev 供应商与模型；
- 目录价格变化时先查看输入/输出差异，再确认是否更新本地价格。

价格单位统一显示为 `$ / 1M Token`。保存前由管理接口完成严格字段校验，页面不会自行推断缺失价格。

点击普通“保存价格”始终把该模型切换为手动配置。目录更新或下载失败不会改变本地价格，也不会影响用户请求。

## 匿名只读模式

直接打开资源 URL 且不填写管理密钥时，页面读取当前 CLIProxyAPI 实例的真实数据：

- 可以查看汇总、请求明细和已配置价格；完整用户 Key 管理表不展示；
- 可以执行分页、筛选、刷新和选择显示列；
- Key 只由服务端返回 `00******0000` 形式的脱敏值，不能复制完整 Key；
- 历史 Usage 中可能存在的旧 `api_key` 值在匿名响应中统一清空；
- 创建、管理、保存、删除、归档、重置、目录更新和参考价导入入口不显示。

匿名读取使用单独的 GET-only 插件资源，不复用受保护的完整 Key 接口，也不提供任何修改方法。

## 管理模式

输入有效 CPA Management Key 后，页面切换到受保护的 Management API：

- 读取完整管理数据，脱敏 Key 可以点击复制完整值；
- 显示创建、管理、归档、额度重置、价格保存和目录更新等操作；
- 所有修改仍由 CLIProxyAPI 管理认证和 billing 服务端规则校验；
- 密钥无效时回退匿名只读数据，不额外显示状态标签。

## 管理接口

管理接口统一挂载在：

```text
/v0/management/plugins/billing
```

| 路径 | 方法 | 用途 |
| --- | --- | --- |
| `/keys` | GET、POST、PATCH、DELETE | 查询、创建、更新和归档 Key |
| `/key-stats` | GET | 查询单个 Key 的统计和最近请求 |
| `/upstreams` | GET | 同步并查询 CPA 上游账号 |
| `/model-suggestions` | GET | 查询已知模型名称建议 |
| `/billing-reset` | POST | 立即重置指定 Key 的额度 |
| `/billing-ledger` | GET | 查询指定 Key 的计费账目 |
| `/usage` | GET | 查询分页请求明细 |
| `/usage-summary` | GET | 查询今日、用户和每日汇总 |
| `/prices` | GET、PUT、DELETE | 查询、保存和删除模型价格 |
| `/prices/import` | POST | 将指定 models.dev 参考价格导入本地模型 |
| `/price-catalog` | GET | 查看目录状态并搜索供应商级参考价格 |
| `/price-catalog/refresh` | POST | 下载新目录并返回已关联价格差异，不修改本地价格 |
| `/price-catalog/apply` | POST | 按目录 revision 确认应用选中的价格变化 |

管理台 HTML 由以下插件资源提供：

```text
/v0/resource/plugins/billing/ui
```

匿名只读 JSON 复用同一个 GET-only 页面资源，页面通过 `view` 查询参数选择数据：

```text
/v0/resource/plugins/billing/ui?view=keys
```

管理接口返回结构化 JSON 和明确的 HTTP 状态码；未知路径返回 `not_found`，数据库不可用、请求字段错误等情况返回对应错误码和消息。

## 界面与数据原则

- 管理台不直接操作 SQLite，只调用公开管理接口。
- 统计卡片和图表使用服务端汇总，不从当前明细页推算。
- 业务校验由服务端完成，前端校验只用于尽早提示。
- 完整 Key 仅由受管理认证保护的 Key 接口返回；匿名接口只返回服务端生成的脱敏值。
- 上游 Token、Cookie 和原始凭证不进入管理台。
- 界面保持单个嵌入资源，避免运行时依赖外部 CDN。
- 窄屏下表单和工具栏自动重排，明细表保留横向滚动能力。

## 模块边界

本模块负责：

- 提供统一管理页面；
- 调用并呈现 billing Management API；
- 提供匿名只读和密钥管理两种访问状态；
- 提供紧凑、可筛选、可分页的操作界面。

本模块不负责：

- 允许匿名调用任何修改接口；
- 在浏览器中直接执行业务扣费或访问控制；
- 保存真实业务数据；
- 提供普通用户自助修改能力；
- 提供登录、角色和多管理员权限体系。