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 事件）
• 主题：暗色模式（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 开始开发，并按阶段提交/推送（方便你随时回滚）。