Implement compression quota refunds and admin manual subscription

docs/ui.md

@@ -0,0 +1,134 @@
+# UI/UX 设计文档 - ImageForge
+
+目标：做一个接近商用的体验（简单、可信、可解释），同时覆盖“网站压缩 + 开发者 API + 计费”三条主线。
+
+---
+
+## 1. 设计原则
+
+1) **一眼可用**：首页即工具，不把用户“逼进登录”才能体验。  
+2) **结果可信**：清晰展示“压缩前后对比、节省多少、是否去除元数据、链接多久过期”。  
+3) **开发者友好**：API Key、用量、示例代码和错误处理在控制台里一站式找到。  
+4) **商用闭环**：升级/取消/发票/支付状态明确，避免“扣费但不知道扣了什么”。  
+
+---
+
+## 2. 信息架构（站点地图）
+
+### 2.1 公共区域（无需登录）
+- `/` 首页（压缩工具）
+- `/pricing` 价格页（套餐对比、FAQ）
+- `/docs` 开发者文档入口（API 概览、SDK、示例）
+- `/login` `/register`
+- `/terms` `/privacy`
+
+### 2.2 用户控制台（需要登录）
+- `/dashboard` 概览（当期用量、套餐、最近任务）
+- `/dashboard/history` 历史任务
+- `/dashboard/api-keys` API Key 管理 + 用量头说明
+- `/dashboard/billing` 订阅与发票
+- `/dashboard/settings` 账号设置（密码、删除账号等）
+
+### 2.3 管理后台（管理员）
+- `/admin` 概览（QPS、错误率、队列长度、订阅状态分布）
+- `/admin/users` 用户管理（冻结、限流覆盖、赠送额度）
+- `/admin/tasks` 任务管理（取消/重试、失败原因）
+- `/admin/billing` 订阅/发票/支付事件（Webhook）排查
+- `/admin/config` 全局配置（开关、限流、文件限制、保留期默认）
+
+---
+
+## 3. 关键页面规格（线框级）
+
+### 3.1 首页（压缩工具）
+核心组件：
+- 顶栏：Logo + `/pricing` `/docs` + 登录/注册（登录后显示头像菜单）
+- 上传区：拖拽 + 点击选择 + 限制提示（格式/大小/数量）
+- 参数区：压缩率、尺寸限制、元数据开关（输出格式保持原图）
+- 结果区：文件列表（缩略图、大小、节省%、状态、下载/重试）
+- 汇总区：总节省、下载 ZIP、清空
+- 信任区：隐私说明（默认去 EXIF）、保留期说明、状态页/联系入口
+
+交互要点：
+- 上传后立即生成本地缩略图与原始大小；压缩进度逐文件显示。
+- 默认提示“匿名试用：每日 10 次”，登录后提示“升级解锁更大额度/保留期”。
+
+### 3.2 价格页（Pricing）
+结构建议：
+- Hero：一句话价值 + CTA（开始压缩 / 查看 API）
+- 套餐卡片：Free / Pro / Business（三列）
+- 对比表：文件大小/批量上限/保留期/Webhook/团队
+- FAQ：计量单位、超额策略、退款、隐私与保留
+
+### 3.3 控制台概览（Dashboard）
+上半区（KPI 卡片）：
+- 当期已用/剩余（进度条）
+- 节省流量累计（本周期/总计）
+- API 调用数（本周期）
+- 当前套餐与到期时间
+
+下半区：
+- 最近任务列表（状态、文件数、节省、操作）
+- 升级提示（当剩余额度 < 20%）
+
+### 3.4 API Key 管理
+列表字段：
+- 名称、前缀、权限、限流、最后使用时间/IP、状态（启用/禁用）
+
+创建/轮换：
+- 创建时弹窗展示一次完整 Key（支持“一键复制”）
+- 轮换说明：首期默认“立即轮换”（生成新 Key 并立即禁用旧 Key），避免双 Key 过渡带来的复杂度
+
+开发者引导：
+- 显示 curl 示例（调用 `POST /compress/direct`）
+- 显示常见错误码（`QUOTA_EXCEEDED`、`RATE_LIMITED`）与重试策略（Idempotency-Key）
+
+### 3.5 订阅与发票（Billing）
+模块：
+- 当前订阅：套餐、周期、状态（active/past_due）、升级/取消按钮
+- 发票列表：编号、金额、状态、周期、下载/跳转支付（provider）
+- 支付方式入口：跳转客户 Portal（如 Stripe portal）
+
+### 3.6 历史任务（History）
+筛选：
+- 时间范围、状态、来源（web/api）、格式、压缩模式
+
+列表：
+- 任务创建时间、文件数、节省、到期时间、下载 ZIP、删除（隐私）
+
+---
+
+## 4. 视觉与组件规范（建议）
+
+### 4.1 设计风格
+- 清爽、留白、强调数据对比（节省% 是视觉重点）
+- 状态色：成功/警告/失败明确
+
+### 4.2 主题变量（示例）
+沿用 `docs/frontend.md` 的 CSS 变量，并补充：
+- `--info`、`--border`、`--bg`、`--text` 等
+- 暗色模式（V1+）
+
+### 4.3 组件清单（公共）
+- `AppLayout` / `AuthLayout` / `AdminLayout`
+- `DropZone`、`FileCard`、`OptionsPanel`
+- `UsageMeter`、`PlanCard`、`InvoiceTable`
+- `Toast`、`Modal`、`Skeleton`、`EmptyState`
+
+---
+
+## 5. 关键文案（必须在 UI 中出现）
+
+- 元数据：默认提示“默认会移除 EXIF 等元数据（定位/设备信息）”
+- 保留期：下载链接到期时间（例如“24 小时后自动删除”）
+- 计量：说明“成功压缩 1 个文件计 1 次”
+- 错误：配额不足/限流时给出“如何解决”（登录/升级/稍后重试）
+
+---
+
+## 6. 可访问性与体验细节
+
+- 键盘可达：上传区、弹窗、按钮可 Tab 导航
+- 颜色对比：状态色满足可读性
+- 大文件/批量：明确“后台处理中，可关闭页面稍后回来”
+- 移动端：首页只保留必要参数，高级参数折叠