From 56d2cadd819b52e266a21fde8899770b0f1bb4a1 Mon Sep 17 00:00:00 2001 From: yuyx <237899745@qq.com> Date: Sat, 13 Dec 2025 22:26:28 +0800 Subject: [PATCH] docs: frontend UI refactor plan --- UI_REFACTOR_FRONTEND.md | 312 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 312 insertions(+) create mode 100644 UI_REFACTOR_FRONTEND.md diff --git a/UI_REFACTOR_FRONTEND.md b/UI_REFACTOR_FRONTEND.md new file mode 100644 index 0000000..5ab9a6c --- /dev/null +++ b/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/`、`GET /api/verify-bind-email/` → 验证成功/失败页（`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/` + - 更新备注：`PUT /api/accounts//remark` + - 启动：`POST /api/accounts//start` + - 停止：`POST /api/accounts//stop` + - 删除：`DELETE /api/accounts/` + - 触发截图：`POST /api/accounts//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/` +- 创建/编辑： + - `POST /api/schedules` + - `PUT /api/schedules/` + - 字段（以现有为准）：任务名、执行时间、执行星期、浏览类型、参与账号、随机延迟、完成后截图等 +- 启用/停用： + - `POST /api/schedules//toggle` +- 立即执行： + - `POST /api/schedules//run` +- 执行日志： + - `GET /api/schedules//logs?limit=...` + - `DELETE /api/schedules//logs` + +### 2.5 模块：截图管理（screenshots） + +能力： +- 列表： + - `GET /api/screenshots` +- 删除单张： + - `DELETE /api/screenshots/` +- 清空： + - `POST /api/screenshots/clear` +- 查看/下载： + - 图片资源来源：`/截图/...` 或 `/static/...`（以现有实现为准；重构后保持链接可用） + +### 2.6 全局：公告弹窗（announcements） + +- 获取当前启用公告： + - `GET /api/announcements/active` +- 关闭/永久关闭（dismiss）： + - `POST /api/announcements//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/` +- 解绑邮箱： + - `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/`、`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 开始开发，并按阶段提交/推送（方便你随时回滚）。