# 用量提醒与限制（Quota）需求规格 v1.0（定稿）

> 日期：2026-08-08 ｜ 状态：已确认 ✅
> 确认项：三维度 ✓ ｜ 429 quota_exceeded ✓ ｜ 新用户默认不限 ✓ ｜ 站内+邮件预留 ✓
> 范围：用户控制台 + 平台管理后台 + 后端网关

---

## 1. 目标
1. **成本保护**：防止单个账号/Key 用量失控（恶意或误配置）导致平台亏损
2. **用户透明**：用量进度可视化 + 提前预警，避免请求突然失败
3. **平台可控**：默认限额 + 全局视图 + 超限事件审计

## 2. 作用域（两层限额，同时生效）
| 层级 | 对象 | 说明 |
|---|---|---|
| 账号级 | User | 该用户全部 Key 的合计用量 |
| Key 级 | ApiKey | 单个 Key 的用量 |

> 生效逻辑：请求同时满足**账号级**与**Key 级**限额才放行；任一超限即拒绝。

## 3. 计量维度与窗口（三个维度独立，任一达限即触发）
| 维度 | 单位 | 每日窗口 | 总量窗口 |
|---|---|---|---|
| 请求次数 | req | 每日请求数上限 | 生命周期累计请求数 |
| Token 量 | tokens | 每日 prompt+completion 合计 | 累计合计 |
| 费用 | USD cents | 每日按售价累计 | 累计 |

> 每日窗口按自然日（UTC）滚动；总量窗口不清零。

## 4. 提醒与限制行为
| 级别 | 触发 | 行为 |
|---|---|---|
| **预警（软）** | 任一维度达阈值（默认 80%，可配 50/80/90%） | ① 控制台用量进度条变黄 + 顶部横幅提醒 ② 邮件提醒（预留 SMTP，每日最多 1 封） |
| **硬限** | 任一维度达 100% | 网关拒绝请求，返回 `429 quota_exceeded`（OpenAI 兼容错误格式），控制台进度条变红 |

## 5. 数据模型
```
ApiKey 新增：
  daily_req_limit Int?      daily_token_limit BigInt?
  daily_cost_cents_limit Int?
  total_req_limit Int?      total_token_limit BigInt?
  total_cost_cents_limit Int?
  alert_pct Int @default(80)
User 新增：同上字段（账号级；未设则用平台默认）

新表 QuotaEvent：id, userId, apiKeyId?, dimension(req/token/cost),
  windowType(daily/total), threshold, current, action(alert/block), createdAt
```

## 6. 统计与执行
- **统计来源**：现有 UsageRecord（按 userId/apiKeyId 按日聚合 + 累计求和）——无需新计数器
- **执行点**：网关 `/v1/chat/completions` 鉴权后、计费前 `checkQuota()`；流式请求在预扣前检查
- **高频优化**：当日计数用 Redis 缓存（key: quota:d:{date}:{apiKeyId}），定期/落库

## 7. 接口设计
| 方法 | 路径 | 说明 |
|---|---|---|
| PUT | /v1/keys/:id/limits | 用户设置自己 Key 的限额 |
| PUT | /v1/account/limits | 用户设置账号级限额 |
| GET | /v1/usage/quota | 当前用量 vs 限额（进度条数据源） |
| GET | /v1/admin/quotas | 全局限额视图（用户/Key/配置/状态） |
| PUT | /v1/admin/quotas/defaults | 平台默认限额 |
| PUT | /v1/admin/users/:id/limits | 管理员覆盖用户限额 |
| GET | /v1/admin/quota-events | 预警/超限事件列表 |

## 8. 界面设计
### 用户控制台
- **总览页**：账号级用量进度条（3 维度 × 每日/总量，超 80% 黄 / 100% 红）
- **API Keys 页**：每 Key 行内限额配置（编辑弹窗）+ 当日进度条 + 超限状态徽章
- **顶部横幅**：达预警/硬限时提示
### 平台管理后台
- **限额管理 tab**：全局列表（搜索/筛选超限用户）、默认限额设置、单用户覆盖、QuotaEvent 审计
- **用户详情**：限额配置 + 实时用量

## 9. 平台默认限额（已确认：**默认不限**）
- 新用户不设默认限额（不强制），由用户自行设置
- 管理员可对**具体用户/Key** 设置限额（覆盖）
- 建议后续提供"推荐限额"引导（非强制）

## 10. 已确认决策
1. ✅ 三个维度（请求/token/费用）都要，独立配置、任一达限即触发
2. ✅ 超限响应：HTTP 429 + OpenAI 兼容错误 `{error:{code:'quota_exceeded'}}`
3. ✅ 新用户默认不限；管理员可对具体账号/Key 设置
4. ✅ 提醒：控制台横幅 + 进度条变色 + 邮件预留（SMTP 就绪后自动启用）