159 lines
4.3 KiB
Markdown
159 lines
4.3 KiB
Markdown
# 前端工程设计（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;
|
||
}
|
||
```
|