# 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 导航
- 颜色对比：状态色满足可读性
- 大文件/批量：明确“后台处理中，可关闭页面稍后回来”
- 移动端：首页只保留必要参数，高级参数折叠