# 前端工程设计（Vue3）- ImageForge

目标：支撑“网站压缩 + 开发者 API 控制台 + 计费/发票 + 管理后台”的一个 Vue3 SPA（或同仓多入口）。

UI/UX 规格见 `docs/ui.md`。

---

## 1. 技术栈（确定）

- Vue 3 + TypeScript + Vite
- 路由：Vue Router
- 状态：Pinia
- 网络：Fetch 或 Axios（统一封装，支持幂等头、错误归一）
- 样式：Tailwind CSS（推荐）或 CSS Variables + 自研组件
- 工具：VueUse、Day.js（或 date-fns）、Zod（表单校验可选）

---

## 2. 路由与页面

### 2.1 公共
```
/            首页压缩
/pricing     套餐与 FAQ
/docs        开发者文档（引导）
/login
/register
/terms
/privacy
```

### 2.2 用户控制台（登录）
```
/dashboard
/dashboard/history
/dashboard/api-keys
/dashboard/billing
/dashboard/settings
```

### 2.3 管理后台（管理员）
```
/admin
/admin/users
/admin/tasks
/admin/billing
/admin/config
```

---

## 3. 前端项目结构（建议）

```
src/
  app/                 # 路由、布局、鉴权守卫
  pages/               # 页面（route components）
  components/          # 通用组件（UI、上传、表格等）
  features/
    compress/          # 压缩：上传、任务、下载
    billing/           # 套餐、订阅、发票、用量
    apiKeys/           # API Key 管理
    admin/             # 管理后台
  services/            # API 封装（http client + endpoints）
  stores/              # Pinia stores
  styles/              # 主题变量、tailwind 入口
  utils/               # 格式化、文件校验、错误处理
```

---

## 4. API 调用规范（前端约定）

### 4.1 Base URL
- 统一使用 `/api/v1`

### 4.2 幂等与重试
- 对 `POST /compress/*`、`POST /billing/checkout` 等请求默认注入 `Idempotency-Key`（UUID）。
- 网络重试仅限“明确幂等”的请求（否则会重复扣费/重复建任务）。

### 4.3 错误处理
将后端错误码映射为统一 UI 提示：
- `QUOTA_EXCEEDED`：引导升级/查看账单页
- `RATE_LIMITED`：展示倒计时（读取 `Retry-After`）
- `FILE_TOO_LARGE` / `TOO_MANY_PIXELS`：定位到具体文件并提示如何处理

---

## 5. 压缩流程（Web）

### 5.1 同步 vs 异步
- 小文件/少量：可直接调用 `POST /compress`，拿到 `download_url`。
- 批量/大文件：调用 `POST /compress/batch`，拿到 `task_id` 后：
  - 优先 WebSocket/SSE 订阅进度；
  - fallback：轮询 `GET /compress/tasks/{task_id}`。

### 5.2 上传前校验
前端必须做“用户体验级校验”（后端仍需二次校验）：
- 格式白名单（png/jpg/jpeg/webp/avif/gif/bmp/tiff/ico，GIF 仅静态）
- 文件大小与数量（按匿名/登录/套餐提示不同上限）
- 匿名试用：每日 10 次限制提示（达到后引导登录/升级）
- 可选：读取图片宽高（避免明显超限）

---

## 6. 计费与用量（前端展示）

对接 `docs/api.md` 的 Billing 模块：
- `/pricing` 页面：读取 `GET /billing/plans`
- 控制台概览：读取 `GET /billing/usage`、`GET /billing/subscription`
- 订阅升级：调用 `POST /billing/checkout` 获取 `checkout_url` 并跳转
- 支付方式/取消订阅：调用 `POST /billing/portal` 获取 portal 链接
- 发票列表：`GET /billing/invoices`

UI 必须展示：
- 当期已用/剩余、重置时间
- 当前订阅状态（active/past_due/canceled）

---

## 7. API Key 控制台（开发者体验）

页面提供三类信息：
1) Key 管理：创建/禁用/轮换（创建时只展示一次完整 Key）
2) 用量：本周期已用/剩余（与 Billing 用量一致）
3) 快速接入：curl 示例 + 常见错误码 + 幂等建议

---

## 8. 安全建议（前端侧）

- 若使用 Bearer Token：避免 localStorage（XSS 风险），优先 HttpOnly Cookie 会话（需要 CSRF 策略）。
- 上传与下载链接：明确到期时间与隐私说明（默认去 EXIF）。
- 管理后台路由加守卫：`role=admin` 才可进入。

---

## 9. 主题变量（CSS Variables）

首期可用 Tailwind 或自研组件，但建议保留一层 CSS 变量，方便后续主题化/暗色模式：

```css
:root {
  --bg: 248 250 252;
  --card: 255 255 255;
  --text: 15 23 42;
  --muted: 71 85 105;
  --border: 226 232 240;

  --brand: 99 102 241;
  --brand-strong: 79 70 229;

  --success: 34 197 94;
  --warning: 245 158 11;
  --danger: 239 68 68;
}
```