docs: frontend UI refactor plan

UI_REFACTOR_FRONTEND.md

@@ -0,0 +1,312 @@
+# 前台 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 事件）
+- 主题：暗色模式（Element Plus 暗色变量 + 自定义 design tokens），支持“跟随系统/手动切换/记忆”
+
+### 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（先做“v2 预览入口”，不影响原 `/app`、`/login` 等）
+- 页面壳子可切换：账号/定时/截图；并提供登录/注册/重置/验证页的新版壳子
+
+阶段 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）暗色模式：B（需要）
+- 7）部署方式：与后台一致（构建产物提交到仓库，运行时不依赖 Node）
+
+## 9. 仍需你确认的小问题（避免返工）
+
+1) **新版上线切换策略**（推荐 A，更稳）：
+- A. 先加“v2 预览入口”（例如 `/app/v2`、`/login/v2`…），原路由保持旧版；最终验收后再切换原路由到新版
+- B. 开发过程中直接替换原路由（出现问题用 git 回滚）
+
+2) **暗色模式默认行为**：
+- A. 默认跟随系统（`prefers-color-scheme`），并提供手动切换（记忆）
+- B. 默认浅色，并提供手动切换（记忆）
+
+3) **暗色模式开关放哪**（二选一即可）：
+- A. 放在 Header 右侧（全局随时可切）
+- B. 放在“设置”里（不占 Header 空间）
+
+4) **VIP 升级弹窗的联系信息**：
+- A. 保持现状（只提示“通过反馈联系管理员”）
+- B. 你提供一个固定联系方式（例如微信/QQ/群号），我放到弹窗里
+
+> 你回复第 9 节的选项后，我就从阶段 1 开始开发，并按阶段提交/推送（方便你随时回滚）。