# 管理台

## 模块定位

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

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

## 页面结构

| 页面 | 主要用途 |
| --- | --- |
| 用户 Key | 管理用户、访问策略、路由、额度和并发，查看用户汇总与账目 |
| 请求明细 | 分页查看请求结果、上游、Token、性能和成本，执行组合筛选 |
| 价格配置 | 维护模型基础价格、长上下文价格和 Fast 倍率 |

页面顶部统一提供实时/测试模式切换和 CPA 管理密钥输入。

## 用户 Key 页面

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

Key 列表展示：

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

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

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

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

## 请求明细页面

请求明细默认每页显示 100 条，页码、上一页、下一页、选择列和刷新操作位于同一顶部工具区。

当前筛选项包括：

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

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

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

## 价格配置页面

价格页面采用左侧模型列表、右侧编辑区：

- 新增或选择一个精确模型名称；
- 设置输入、缓存读取、缓存写入和输出的基础价格；
- 可选启用长上下文价格；
- 设置长上下文输入门槛及“大于/大于等于”比较方式；
- 可选启用 Fast 价格并设置倍率；
- 保存或删除模型价格。

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

## 实时模式

实时模式连接当前 CLIProxyAPI 实例：

- 需要输入 CPA Management Key；
- 所有读取来自真实管理接口；
- 创建、编辑、归档、重置和价格保存会修改真实数据；
- 请求明细和汇总反映真实请求事实。

管理台资源本身可以被 CPA 加载，但敏感管理接口仍由 CLIProxyAPI 的管理认证保护。

## 测试模式

测试模式用于管理员熟悉页面和验证交互，与真实数据完全隔离：

- 不需要管理密钥；
- 不访问任何真实 cpa-ext 管理接口；
- 使用浏览器本地的模拟 Key、上游、请求、价格和账目；
- 创建、编辑、归档、重置和删除只修改本地模拟状态；
- 提供放大的请求记录量，便于测试分页、筛选和表格布局；
- 可以一键恢复初始测试数据。

测试数据保存在浏览器本地存储中，当前选择的实时/测试模式保存在当前会话。切换模式不会把测试数据导入真实数据库，也不会用真实数据覆盖测试样例。

## 管理接口

管理接口统一挂载在：

```text
/v0/management/plugins/cpa-ext
```

| 路径 | 方法 | 用途 |
| --- | --- | --- |
| `/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 | 查询、保存和删除模型价格 |

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

```text
/v0/resource/plugins/cpa-ext/ui
```

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

## 界面与数据原则

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

## 模块边界

本模块负责：

- 提供统一管理页面；
- 调用并呈现 cpa-ext Management API；
- 管理实时和测试数据模式；
- 提供紧凑、可筛选、可分页的操作界面。

本模块不负责：

- 绕过 CLIProxyAPI 管理认证；
- 在浏览器中直接执行业务扣费或访问控制；
- 保存真实业务数据；
- 提供普通用户自助页面；
- 提供登录、角色和多管理员权限体系。