zsglpt/UI_REFACTOR_FRONTEND.md

# 前台 UI 重构方案（Vue3 + Vite + Element Plus，保持功能不变）

> 目标：重构“用户前台界面”（优先 `/app`，可选包含 `/login`、`/register`、`/reset_password` 等页面）的视觉与交互，使其更现代、美观、易用、可维护；**后端接口与业务流程保持不变**。
>
> 实现方式：前台前端改为 **Vue3 单页应用**（Vite 构建产物部署到 `static/app/`），所有接口继续使用现有 `/api/...`，不改后端功能。

---

## 1. 项目概览（基于当前仓库代码）

### 1.1 技术栈与形态

- 后端：Python / Flask（`app.py`，不变）
- 当前前台前端：
  - `templates/index.html`：一个超大单文件（内联 CSS + 内联 JS + 大量 DOM 操作），覆盖“账号/定时/截图/反馈/设置/VIP/公告/Socket 实时更新”
  - 登录/注册/重置等：`templates/login.html`、`templates/register.html`、`templates/reset_password.html` 等（同样以内联样式与原生 JS 为主）
- 目标前台前端：Vue3 + Vite +（推荐）Element Plus + Vue Router + Axios + socket.io-client
- 静态资源：前端构建产物输出到 `static/app/`（新增；运行时不依赖 CDN）

### 1.2 页面入口与路由

- 用户登录页：
  - `GET /login` → `templates/login.html`
- 用户注册页：
  - `GET /register` → `templates/register.html`
- 用户主应用页（前台核心）：
  - `GET /app` → `templates/index.html`
- 其他辅助页：
  - `GET /reset_password` → `templates/reset_password.html`
  - `GET /api/verify-email/<token>`、`GET /api/verify-bind-email/<token>` → 验证成功/失败页（`templates/verify_success.html`、`templates/verify_failed.html`）

### 1.3 重构落地与回滚策略（推荐）

- 新增前台前端工程：`app-frontend/`
- 构建输出：`app-frontend/` → `static/app/`（带 `.vite/manifest.json`）
- Flask 对接：各前台页面读取 manifest 并渲染“挂载模板”（例如 `templates/app.html` / `templates/login.html` 等改为挂载 SPA）
- 回滚：保留旧版模板（例如 `templates/index_legacy.html` 等），当 manifest 缺失/异常时自动回退旧版

> 推荐的上线策略：开发阶段先提供“v2 预览入口”（不影响线上功能），最终验收通过后再把原路由切到新版（详见第 8 节问题）。

---

## 2. 前台功能清单（用于“功能不变”验收）

> 下面按 `templates/index.html` 的现有能力梳理，重构后需要逐项对齐。

### 2.1 顶部 Header（全局）

- 显示：站点名称、当前用户名、VIP/普通用户徽章、VIP 到期提醒
- 操作：
  - 打开“反馈”弹窗
  - 打开“设置/个人设置”弹窗（改密、邮箱绑定与通知开关）
  - 退出登录
- 接口：
  - `POST /api/logout`
  - `GET /api/user/vip`

### 2.2 侧栏导航（全局）

当前 3 个主模块：
- 账号管理
- 定时任务
- 截图管理

移动端目前通过 CSS 将侧栏改为底部导航样式（需保持“不变形、可用”）。

### 2.3 模块：账号管理（accounts）

能力（保持逻辑不变）：
- 顶部统计卡片：
  - 今日完成、今日失败、正在运行、浏览内容、查看附件、账号数量/上限
  - 数据来源：`GET /api/run_stats`、`GET /api/accounts`、`GET /api/user/vip`
- 账号列表（卡片网格）：
  - 展示账号信息、备注、状态、进度条、耗时/进度、按钮操作等
  - 实时更新来源：Socket 事件 `accounts_list`、`account_update`、`task_progress`、`log`
- 单账号操作：
  - 新增账号：`POST /api/accounts`
  - 编辑账号（含密码更新、remember 等）：`PUT /api/accounts/<id>`
  - 更新备注：`PUT /api/accounts/<id>/remark`
  - 启动：`POST /api/accounts/<id>/start`
  - 停止：`POST /api/accounts/<id>/stop`
  - 删除：`DELETE /api/accounts/<id>`
  - 触发截图：`POST /api/accounts/<id>/screenshot`
- 批量操作：
  - 批量启动：`POST /api/accounts/batch/start`
  - 批量停止：`POST /api/accounts/batch/stop`
  - 清空账号：`POST /api/accounts/clear`
  - 批量参数：浏览类型（应读/注册前未读）、截图开关、选中账号集合
- VIP 限制/提示：
  - 普通用户账号数量上限、批量能力/定时能力等（以现有逻辑为准）

### 2.4 模块：定时任务（schedule）

能力：
- 列表与详情：
  - `GET /api/schedules`
  - `GET /api/schedules/<id>`
- 创建/编辑：
  - `POST /api/schedules`
  - `PUT /api/schedules/<id>`
  - 字段（以现有为准）：任务名、执行时间、执行星期、浏览类型、参与账号、随机延迟、完成后截图等
- 启用/停用：
  - `POST /api/schedules/<id>/toggle`
- 立即执行：
  - `POST /api/schedules/<id>/run`
- 执行日志：
  - `GET /api/schedules/<id>/logs?limit=...`
  - `DELETE /api/schedules/<id>/logs`

### 2.5 模块：截图管理（screenshots）

能力：
- 列表：
  - `GET /api/screenshots`
- 删除单张：
  - `DELETE /api/screenshots/<filename>`
- 清空：
  - `POST /api/screenshots/clear`
- 查看/下载：
  - 图片资源来源：`/截图/...` 或 `/static/...`（以现有实现为准；重构后保持链接可用）

### 2.6 全局：公告弹窗（announcements）

- 获取当前启用公告：
  - `GET /api/announcements/active`
- 关闭/永久关闭（dismiss）：
  - `POST /api/announcements/<id>/dismiss`

### 2.7 全局：反馈（feedback）

- 提交反馈：
  - `POST /api/feedback`
- 查看我的反馈：
  - `GET /api/feedback`

### 2.8 全局：个人设置（settings）

- 修改密码：
  - `POST /api/user/password`
- 邮箱绑定状态：
  - `GET /api/user/email`
- 绑定邮箱（需要邮件验证）：
  - `POST /api/user/bind-email`
  - `GET /api/verify-bind-email/<token>`
- 解绑邮箱：
  - `POST /api/user/unbind-email`
- 任务完成邮件通知开关：
  - `GET /api/user/email-notify`
  - `POST /api/user/email-notify`

### 2.9 登录/注册/找回密码（如纳入本次重构范围）

- 登录：
  - `POST /api/login`
  - 验证码：`POST /api/generate_captcha`
- 注册：
  - `POST /api/register`
  - 邮箱验证：`GET /api/verify-email/<token>`、`POST /api/resend-verify-email`、`GET /api/email/verify-status`
- 忘记密码 / 重置：
  - `POST /api/forgot-password`
  - `POST /api/reset-password-confirm`
  - 另有“需管理员审核的重置申请”：`POST /api/reset_password_request`（保持现有入口与提示）

---

## 3. 为什么要重构（现状问题）

- `templates/index.html` 体量大、CSS/JS/DOM 耦合严重，维护成本高、改动风险高。
- 功能多但缺乏模块边界（账号/定时/截图/反馈/设置都混在一起），难以复用和做一致性升级。
- 交互与状态管理依赖大量 `document.getElementById(...)` + 手工拼字符串渲染，后续迭代容易引入回归。

---

## 4. 推荐技术方案（Vue3 落地，保持功能不变）

### 4.1 前端技术选型（推荐）

- Vue3 + Vite
- UI 组件库（推荐）：Element Plus（与后台保持一致，减少重复造轮子）
- 路由：Vue Router（建议 hash 模式，避免刷新 404）
- 请求：Axios（统一错误处理；不改变接口）
- 状态：Pinia（推荐，用于账号/定时/截图/用户信息等全局状态）
- 实时：socket.io-client（对齐现有 Socket 事件）

### 4.2 构建与部署方式（与后台一致）

- 新工程：`app-frontend/`
- Vite build 输出到：`static/app/`（`manifest: true`）
- Flask `/app`：
  - 读取 `static/app/.vite/manifest.json`
  - 把入口 js/css 注入 `templates/app.html`
  - 读取失败则回退 `templates/index_legacy.html`

> 这样运行容器不需要 Node；构建产物提交到仓库（与你后台当前策略一致）。

### 4.3 信息架构与布局建议（不改变功能）

- 桌面端：保留“Header + 左侧导航 + 右侧内容”的经典布局
- 移动端：导航折叠为抽屉或底部 Tab（两者择一，见第 8 节问题）
- 账号页：卡片网格保留，但组件化（AccountCard、BatchToolbar、StatsCards）
- 定时页：卡片列表 + 表单弹窗（或抽屉）
- 截图页：瀑布流/网格 + 预览弹窗

---

## 5. 代码结构建议（便于维护）

建议结构（示例）：

- `app-frontend/src/layouts/AppLayout.vue`
- `app-frontend/src/router/index.js`
- `app-frontend/src/pages/AccountsPage.vue`
- `app-frontend/src/pages/SchedulesPage.vue`
- `app-frontend/src/pages/ScreenshotsPage.vue`
- `app-frontend/src/components/account/AccountCard.vue`
- `app-frontend/src/components/account/BatchToolbar.vue`
- `app-frontend/src/components/common/ConfirmDanger.vue`
- `app-frontend/src/api/*.js`（按资源拆分：accounts/schedules/screenshots/user/feedback/announcements）
- `app-frontend/src/stores/*`（Pinia：accountsStore、userStore、schedulesStore、screenshotsStore）
- `app-frontend/src/composables/useSocket.js`（统一管理连接、事件订阅、断线重连）

---

## 6. 分阶段交付（建议）

> 你之前希望“每个阶段提交到 git 方便回滚”，前台我也按同样方式推进。

阶段 1：工程搭建 + 新布局（可访问可导航）
- 新建 `app-frontend/`，跑通 Vue3 + 路由 + 基础布局（Header/Sidebar/Drawer）
- Flask 接入 manifest（按你的选择：开发完成后直接替换原路由；开发过程中可先保留旧版模板不切换）
- 页面壳子可切换：账号/定时/截图；并提供登录/注册/重置/验证页的新版壳子

阶段 2：认证相关页面全量迁移（确保可登录可注册可找回）
- `/login`：含验证码、忘记密码、重发验证邮件等（接口不变）
- `/register`：含邮箱验证流程（接口不变）
- `/reset_password`：重置密码确认页（接口不变）
- 验证成功/失败页：视觉统一（不改跳转逻辑）

阶段 3：账号管理全量迁移（含实时更新）
- 账号 CRUD、启动/停止、截图、批量操作、账号上限与 VIP 文案
- Socket 实时事件（accounts_list/account_update/task_progress/log）迁移
- 顶部统计（run_stats）与公告弹窗迁移

阶段 4：定时任务 + 截图管理迁移
- 定时任务 CRUD、启停、立即执行、日志查看/清空
- 截图列表、预览、删除、清空

阶段 5：反馈 + 设置 + 统一细节 + 回归验收（最终切换）
- 反馈提交/我的反馈
- 设置：改密、邮箱绑定、通知开关
- 移动端适配、统一视觉细节、性能（按需加载等）
- 按第 7 节验收清单全量回归
- 验收通过后：将原 `/app`、`/login`、`/register` 等路由切到新版；旧版保留为回滚入口

---

## 7. 验收清单（重构后你可按此点验）

- 登录/退出不变：登录进入 `/app`，退出回到登录页
- 账号管理：
  - 列表加载/新增/编辑/备注/删除正常
  - 启动/停止/截图正常
  - 批量启动/停止、全部启动/停止、清空账号正常
  - 进度与状态实时更新正常（Socket）
- 定时任务：
  - 新建/编辑/删除/启停/立即执行正常
  - 执行日志查看/清空正常
- 截图：
  - 列表/预览/下载/删除/清空正常
- 公告：
  - 有启用公告时弹出；关闭/永久关闭行为不变
- 反馈：
  - 提交成功；我的反馈列表可查看状态与管理员回复
- 设置：
  - 修改密码成功后提示清晰
  - 邮箱绑定/解绑/通知开关可用
- 移动端：
  - 三个主页面不变形、关键按钮可点、表单可完整操作

---

## 8. 已确认的决策（来自你的回复）

- 1）重构范围：C（全部前台页面都重构：`/app` + `/login` + `/register` + `/reset_password` + 验证成功/失败页等）
- 2）组件库：A（Element Plus）
- 3）移动端导航：A（抽屉菜单）
- 4）视觉风格：A（与后台一致：克制、浅色、卡片化）
- 5）VIP 展示：A（保留升级 VIP 弹窗与入口，仍走反馈/联系管理员）
- 6）暗色模式：不开发（按你最新回复）
- 7）部署方式：与后台一致（构建产物提交到仓库，运行时不依赖 Node）

## 9. 仍需你确认的小问题（避免返工）

1) **新版上线切换策略**（推荐 A，更稳）：
- A. 先加“v2 预览入口”（例如 `/app/v2`、`/login/v2`…），原路由保持旧版；最终验收后再切换原路由到新版
- B. 开发过程中直接替换原路由（出现问题用 git 回滚）
 
2) **VIP 升级弹窗的联系信息**：
- A. 保持现状（只提示“通过反馈联系管理员”）
- B. 你提供一个固定联系方式（例如微信/QQ/群号），我放到弹窗里

> 你已回复：上线切换策略选 B；VIP 联系信息选 A。接下来我按阶段 1 开始开发，并按阶段提交/推送（方便你随时回滚）。