From e01a7b52356f2add2527c9eb2fd070c8a3a5fa1f Mon Sep 17 00:00:00 2001 From: 237899745 <1730191420@qq.com> Date: Sun, 14 Dec 2025 18:24:34 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=A0=E9=99=A4=20UI=5FREFACTOR=5FFRONTEND.m?= =?UTF-8?q?d?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- UI_REFACTOR_FRONTEND.md | 302 ---------------------------------------- 1 file changed, 302 deletions(-) delete mode 100644 UI_REFACTOR_FRONTEND.md diff --git a/UI_REFACTOR_FRONTEND.md b/UI_REFACTOR_FRONTEND.md deleted file mode 100644 index 0e21ebe..0000000 --- a/UI_REFACTOR_FRONTEND.md +++ /dev/null @@ -1,302 +0,0 @@ -# 前台 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 事件） - -### 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 开始开发，并按阶段提交/推送（方便你随时回滚）。