Implement compression quota refunds and admin manual subscription
This commit is contained in:
158
docs/frontend.md
Normal file
158
docs/frontend.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# 前端工程设计（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;
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user