DoTouchAI/docs/requirements/usage-quota-requirements-v0.1.md

用量提醒与限制（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 就绪后自动启用）