ystp/docs/frontend.md

前端工程设计（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 变量，方便后续主题化/暗色模式：

: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;
}