From 3c31f30ee4952ef11f924048c680b85dc60c18a4 Mon Sep 17 00:00:00 2001
From: yuyx <237899745@qq.com>
Date: Sat, 13 Dec 2025 20:51:08 +0800
Subject: [PATCH] docs: admin UI refactor plan

---
 UI_REFACTOR_ADMIN.md | 430 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 430 insertions(+)
 create mode 100644 UI_REFACTOR_ADMIN.md

diff --git a/UI_REFACTOR_ADMIN.md b/UI_REFACTOR_ADMIN.md
new file mode 100644
index 0000000..bd4233d
--- /dev/null
+++ b/UI_REFACTOR_ADMIN.md
@@ -0,0 +1,430 @@
+# 后台管理 UI 重构方案（Vue3 + Vite，保持功能不变）
+
+> 目标：仅重构“后台管理界面”（优先 `/yuyx/admin`）的视觉与交互呈现，使其更现代、美观、易用、可维护；后端接口与业务流程保持不变。
+>
+> 实现方式：后台前端改为 **Vue3 单页应用**（Vite 构建产物部署到 `static/admin/`），所有接口继续使用现有 `/yuyx/api/...`，不改后端功能。
+
+---
+
+## 1. 项目概览（基于当前仓库代码）
+
+### 1.1 技术栈与形态
+
+- 后端：Python / Flask（`app.py`，不变）
+- 当前后台前端：Jinja2 模板 + 原生 HTML/CSS/JS（现状）
+- 目标后台前端：Vue3 + Vite（构建）+ Element Plus（组件库，默认方案）+ Vue Router + Axios（仅后台）
+- 静态资源：前端构建产物输出到 `static/admin/`（新增；运行时不依赖 CDN）
+
+### 1.2 后台入口与页面
+
+- 后台登录页：`GET /yuyx` → `templates/admin_login.html`（第一阶段可先不改，后续可再 Vue 化/美化）
+- 后台管理页：`GET /yuyx/admin` → Vue3 SPA（构建后由 Flask 返回 `static/admin/index.html`）
+- 回滚策略：保留旧版 `templates/admin.html`（计划改名为 `templates/admin_legacy.html` 备份，便于一键回滚）
+
+### 1.3 现状结论（为什么“臃肿”）
+
+- `templates/admin.html` 是一个超大单文件（包含大量内联 `<style>` + 大量内联 JS + 大量内联 `style="..."`），维护成本高、改动风险高。
+- “页面结构 / 样式 / 逻辑”混在一起，导致：
+  - 视觉风格不统一（按钮、卡片、表格、间距、字号混用）。
+  - 组件复用困难（很多 UI 是拷贝粘贴 + 内联样式）。
+  - 小改动容易引发回归（JS 依赖大量 DOM id/结构）。
+
+---
+
+## 2. 后台功能清单（用于“功能不变”验收）
+
+后台管理页 `templates/admin.html` 目前是一个“单页 + 多 Tab”结构，Tab 与能力如下：
+
+### 2.1 顶部统计卡片（页面顶部）
+
+- 展示：总用户数、已审核、待审核、总账号数、VIP 用户数
+- 数据来源：`GET /yuyx/api/stats`
+- 额外：显示管理员用户名（同接口返回 `admin_username` 时更新 UI）
+
+### 2.2 Tab：待审核（pending）
+
+1) 用户注册审核
+- 列表：ID、用户名、邮箱、注册时间、操作
+- 操作：通过、拒绝
+- 接口：
+  - `GET /yuyx/api/users/pending`
+  - `POST /yuyx/api/users/<user_id>/approve`
+  - `POST /yuyx/api/users/<user_id>/reject`
+
+2) 密码重置审核
+- 列表：申请ID、用户名、邮箱、申请时间、操作
+- 操作：批准、拒绝
+- 接口：
+  - `GET /yuyx/api/password_resets`
+  - `POST /yuyx/api/password_resets/<request_id>/approve`
+  - `POST /yuyx/api/password_resets/<request_id>/reject`
+
+### 2.3 Tab：所有用户（all）
+
+- 列表：ID、用户名（含邮箱/ VIP 标识/到期）、状态、注册/审核时间、操作
+- 操作：
+  - 待审核用户：通过 / 拒绝
+  - 删除用户
+  - VIP：开通（一周/一月/一年/永久）或移除
+  - 管理员直接重置用户密码（输入新密码）
+- 接口：
+  - `GET /yuyx/api/users`
+  - `POST /yuyx/api/users/<user_id>/approve`
+  - `POST /yuyx/api/users/<user_id>/reject`
+  - `DELETE /yuyx/api/users/<user_id>`
+  - `POST /yuyx/api/users/<user_id>/vip`（body: `{days}`）
+  - `DELETE /yuyx/api/users/<user_id>/vip`
+  - `POST /yuyx/api/users/<user_id>/reset_password`（body: `{new_password}`）
+
+### 2.4 Tab：反馈管理（feedbacks）
+
+- 筛选：状态（全部/待处理/已回复/已关闭）
+- 统计：总计、待处理、已回复、已关闭（并显示待处理徽章）
+- 列表字段：ID、用户、标题、描述、联系方式、状态、提交时间、回复、操作
+- 操作：回复（prompt）、关闭、删除
+- 接口：
+  - `GET /yuyx/api/feedbacks?status=...`
+  - `POST /yuyx/api/feedbacks/<feedback_id>/reply`（body: `{reply}`）
+  - `POST /yuyx/api/feedbacks/<feedback_id>/close`
+  - `DELETE /yuyx/api/feedbacks/<feedback_id>`
+
+### 2.5 Tab：统计（stats）
+
+1) 系统资源概览
+- CPU / 内存 / 磁盘 / 容器内存 / 运行时长
+- 接口：
+  - `GET /yuyx/api/server/info`
+  - `GET /yuyx/api/docker_stats`
+
+2) 实时任务监控（每 1 秒刷新）
+- 运行中数量、排队中数量、最大并发
+- 运行中/排队中任务列表（来源、用户、账号、浏览类型、详细状态、耗时等）
+- 接口：
+  - `GET /yuyx/api/task/running`
+
+3) 任务统计
+- 今日/累计：成功任务、失败任务、浏览内容、查看附件
+- 接口：
+  - `GET /yuyx/api/task/stats`
+
+### 2.6 Tab：任务日志（logs）
+
+- 筛选：日期、状态（成功/失败）、来源（手动/定时/即时/恢复）、用户、账号关键字
+- 列表字段：时间、来源、用户、账号、浏览类型、状态、内容/附件、用时、失败原因
+- 分页：limit/offset（每页 20）、首页/上一页/下一页/末页
+- 操作：清理旧日志（输入天数）
+- 接口：
+  - `GET /yuyx/api/task/logs?limit=&offset=&date=&status=&source=&user_id=&account=`
+  - `POST /yuyx/api/task/logs/clear`（body: `{days}`）
+
+### 2.7 Tab：公告管理（announcements）
+
+- 创建公告：标题、内容
+- 操作：发布并启用 / 保存但不启用 / 清空
+- 列表字段：ID、标题、状态、创建时间、操作
+- 操作：查看、启用、停用、删除
+- 接口：
+  - `GET /yuyx/api/announcements`
+  - `POST /yuyx/api/announcements`（body: `{title, content, is_active}`）
+  - `POST /yuyx/api/announcements/<id>/activate`
+  - `POST /yuyx/api/announcements/<id>/deactivate`
+  - `DELETE /yuyx/api/announcements/<id>`
+
+### 2.8 Tab：邮件配置（email）
+
+1) 全局开关与基础 URL
+- 启用邮件、故障转移、注册邮箱验证、任务完成通知、网站基础 URL
+- 接口：
+  - `GET /yuyx/api/email/settings`
+  - `POST /yuyx/api/email/settings`
+
+2) SMTP 配置
+- 列表：主/备用/禁用、名称、服务器、今日/限额、成功率、编辑
+- 弹窗：新增/编辑 SMTP（含密码显隐、测试连接、保存、设为主配置、删除）
+- 接口：
+  - `GET /yuyx/api/smtp/configs`
+  - `POST /yuyx/api/smtp/configs`
+  - `GET /yuyx/api/smtp/configs/<config_id>`
+  - `PUT /yuyx/api/smtp/configs/<config_id>`
+  - `DELETE /yuyx/api/smtp/configs/<config_id>`
+  - `POST /yuyx/api/smtp/configs/<config_id>/test`
+  - `POST /yuyx/api/smtp/configs/<config_id>/primary`
+
+3) 邮件统计 & 邮件日志
+- 统计：总发送、成功、失败、各类型
+- 日志：按类型/状态筛选、分页、清理
+- 接口：
+  - `GET /yuyx/api/email/stats`
+  - `GET /yuyx/api/email/logs?page=&page_size=&type=&status=`
+  - `POST /yuyx/api/email/logs/cleanup`（body: `{days}`）
+
+### 2.9 Tab：系统配置（system）
+
+1) 并发配置
+- 全局最大并发、单账号最大并发、截图最大并发
+- 接口：`POST /yuyx/api/system/config`
+
+2) 定时任务配置
+- 启用定时任务、执行时间、执行日期（周一~周日）、浏览类型、保存、立即执行
+- 接口：
+  - `GET /yuyx/api/system/config`
+  - `POST /yuyx/api/system/config`
+  - `POST /yuyx/api/schedule/execute`
+
+3) 代理设置
+- 启用代理、代理 API 地址、代理有效期、保存、测试代理
+- 接口：
+  - `GET /yuyx/api/proxy/config`
+  - `POST /yuyx/api/proxy/config`
+  - `POST /yuyx/api/proxy/test`
+
+4) 注册自动审核
+- 启用自动审核、每小时注册限制、注册赠送 VIP 天数
+- 接口：`POST /yuyx/api/system/config`
+
+### 2.10 Tab：设置（settings）
+
+- 修改管理员用户名（成功后提示重新登录并触发退出）
+- 修改管理员密码（成功后提示重新登录并触发退出）
+- 退出登录
+- 接口：
+  - `PUT /yuyx/api/admin/username`
+  - `PUT /yuyx/api/admin/password`
+  - `POST /yuyx/api/logout`
+
+---
+
+## 3. UI 重构目标与范围
+
+### 3.1 明确目标
+
+- 视觉：更现代、克制、统一（字体/字号/间距/颜色/阴影/圆角/表格/表单）
+- 交互：信息层级清晰、导航不拥挤、在桌面/手机都可用
+- 工程：可维护（减少内联样式、抽离 CSS/JS、结构更清晰）
+- 兼容：引入 Vue3 + Vite 构建（你已确认部署可拉依赖）；运行时仍是 Flask 提供静态文件，不需要 Node 常驻运行
+
+### 3.2 不做的事（避免范围失控）
+
+- 不改后端接口、不改数据库、不改业务流程
+- 不依赖运行时外网/CDN（所有前端依赖在构建期打包进静态文件）
+- 不额外新增“业务功能”（最多做纯 UI/UX 级别优化：排版、布局、可读性、响应式）
+
+---
+
+## 4. 推荐的界面改造方向（保持功能不变前提下）
+
+### 4.1 信息架构（解决“标签太多、拥挤”）
+
+建议把当前顶栏 Tabs 升级为“左侧导航 + 右侧内容”的后台经典布局：
+
+- 左侧：导航（待审核/用户/反馈/统计/日志/公告/邮件/系统/设置）
+- 右侧：内容区（每个导航项对应一个 Vue 页面/模块；不改变现有数据与按钮）
+- 顶部：保留 header（系统名 + 管理员用户名 + 退出）
+- 移动端：左侧导航折叠为抽屉（hamburger）
+
+这样可以显著减轻横向 Tabs 的拥挤感，同时保持“单页切换”的实现方式（Vue Router）。
+
+> 如果你希望“仍然保持 Tabs”也可以：我们会把 Tabs 做成可滚动 + 分组/二级菜单的样式；该点需要你确认（见第 8 节）。
+
+### 4.2 视觉体系（统一设计语言）
+
+在使用 Element Plus 的前提下，仍建议补一层轻量的 design tokens（CSS 变量），用于统一页面背景、间距、圆角、阴影与品牌色（Element Plus 负责组件能力，我们负责整体风格统一）：
+
+- 颜色：主色、成功/警告/危险、边框色、背景色、文本色
+- 间距：4/8/12/16/24/32
+- 圆角：8/12
+- 阴影：轻/中
+- 字体：系统字体栈（优先苹方/微软雅黑/Segoe UI）
+
+并把按钮、卡片、表格、表单、徽章、弹窗、通知统一到同一套组件外观。
+
+### 4.3 表格与表单体验
+
+- 表格：表头 sticky、行 hover、状态徽章统一、操作按钮收纳（避免一行按钮过多）
+- 表单：label 与 help text 统一样式；输入框 focus 样式；危险操作（删除/清理）更醒目
+
+### 4.4 反馈与通知
+
+现有通知是简单的 1 秒浮层提示。建议升级为更现代的 toast（可保留 1 秒自动消失，但样式更好、支持多行、更清晰的成功/失败状态）。
+
+---
+
+## 5. 技术实施方案（Vue3 + Vite 落地，保持功能不变）
+
+### 5.1 总体落地方案（你已确认采用“推荐方式”）
+
+- 新增后台前端工程：`admin-frontend/`（Vue3 + Vite）
+- 构建输出：`admin-frontend/dist/` → 复制/输出到 `static/admin/`
+- Flask 对接：`GET /yuyx/admin` 返回 `static/admin/index.html`
+- 路由策略：Vue Router 使用 **hash 模式**（避免后端再做 history fallback 配置）
+- 接口策略：所有请求继续调用现有 `/yuyx/api/...`（URL/method/body 完全不变）
+
+### 5.2 组件库选择（我来判断：默认 Element Plus）
+
+默认采用：
+
+- `element-plus` + `@element-plus/icons-vue`
+
+原因：
+
+- 后台大量场景是“表格/表单/弹窗/分页/通知”，Element Plus 开箱即用且样式现代
+- 可通过主题变量与少量 CSS 统一品牌风格，达到“更美观”目标
+- 能把大量 `alert/confirm/prompt` 升级为更现代的 Dialog/MessageBox（功能不变，体验更好）
+
+> 如果你明确不想引入组件库，我也能改为“纯自研 UI”，但开发周期会明显拉长。
+
+### 5.3 前端目录结构建议（便于可维护）
+
+建议结构（示意）：
+
+```
+admin-frontend/
+  package.json
+  vite.config.(ts|js)
+  src/
+    main.(ts|js)
+    App.vue
+    router/
+      index.(ts|js)
+    api/
+      client.(ts|js)          # axios 实例（baseURL=/yuyx/api）
+      users.(ts|js)
+      feedbacks.(ts|js)
+      announcements.(ts|js)
+      system.(ts|js)
+      email.(ts|js)
+      taskLogs.(ts|js)
+      stats.(ts|js)
+    layouts/
+      AdminLayout.vue         # Header + Sidebar + Content
+    pages/
+      Pending.vue
+      Users.vue
+      Feedbacks.vue
+      Stats.vue
+      Logs.vue
+      Announcements.vue
+      Email.vue
+      System.vue
+      Settings.vue
+    components/
+      ...                      # 可复用的表格/弹窗/筛选条等
+```
+
+### 5.4 与后端/静态资源的集成细节（避免踩坑）
+
+- Vite `base`：建议配置为 `/static/admin/`，确保打包后的资源路径正确
+- API：`axios.create({ baseURL: '/yuyx/api', withCredentials: true })`
+- 403/未登录体验：API 返回 403 时，前端可提示“需要管理员权限”，并跳转到 `/yuyx`（此行为是否接受见第 8 节问题）
+
+### 5.5 构建与部署（支持 Docker，多阶段构建，运行时无 Node）
+
+你已确认“部署时可以拉依赖”，因此可用以下思路：
+
+- 本地/服务器构建：
+  - `cd admin-frontend && npm ci && npm run build`
+  - 将 `admin-frontend/dist` 部署到后端容器的 `static/admin/`
+- Docker 推荐：多阶段构建
+  - Stage 1（Node）：安装依赖并 `npm run build`
+  - Stage 2（现有 Python/Playwright 镜像）：复制 `dist/` 到 `/app/static/admin/`
+
+> 这样最终运行容器里不需要 Node，仍是“Flask + 静态文件”的部署模式。
+
+### 5.6 分阶段交付（按功能模块逐步落地）
+
+阶段 1：工程搭建 + 新布局
+- 建好 Vue3 工程、Element Plus、路由与基础布局（Header/Sidebar）
+- 先把 9 个模块页面壳子跑通（不要求全部功能完成，但可导航切换）
+
+阶段 2：核心模块功能迁移（先保证可用）
+- 待审核 / 所有用户 / 系统配置 / 设置：完成列表+表单+操作全流程
+
+阶段 3：复杂模块迁移（数据量/交互多）
+- 统计（含 1 秒刷新）/ 任务日志（筛选分页）/ 邮件配置（SMTP 弹窗 + 日志分页）/ 公告 / 反馈
+
+阶段 4：统一细节 + 回归验收
+- 全量走一遍第 7 节验收清单
+- 补齐移动端适配与细节视觉统一
+- 保留旧版后台模板备份，便于回滚
+
+---
+
+## 6. 风险点与注意事项（提前说明）
+
+- Vue SPA 静态资源路径需要正确配置（Vite `base`）；否则会出现“页面白屏/资源 404”。
+- Vue Router 建议使用 hash 模式，避免出现刷新子路由 404 的历史路由问题。
+- 管理员鉴权依赖 session cookie；前端请求必须同源并携带 cookie（axios `withCredentials`）。
+- 统计页每 1 秒刷新一次接口（server/docker/task/running）；UI 改造不应额外增加请求频率。
+- 列表项里存在长文本（反馈描述/失败原因/邮件错误等），需要做更合理的折行/省略/查看方式，避免布局被撑爆。
+- `/yuyx/vip` 为历史废弃入口（旧模板缺失），已按确认删除该路由，避免误访问报错。
+
+---
+
+## 7. 验收清单（你确认后我按此对齐开发）
+
+建议你在重构完成后按以下清单点验收（确保“功能不变”）：
+
+- 登录/退出：
+  - `GET /yuyx` 登录成功跳转后台
+  - 退出后回到后台登录页
+- 顶部统计：
+  - 统计数字正常刷新，管理员用户名正常显示
+- 待审核：
+  - 注册审核列表加载/通过/拒绝正常
+  - 密码重置列表加载/批准/拒绝正常
+- 所有用户：
+  - 列表加载正常
+  - 删除用户、VIP 开通/移除、重置密码正常
+- 反馈管理：
+  - 状态筛选正常；徽章数字正确
+  - 回复/关闭/删除正常
+- 公告管理：
+  - 创建（启用/不启用）正常
+  - 启用/停用/删除/查看正常
+- 系统配置：
+  - 并发保存正常
+  - 定时任务保存与“立即执行”正常
+  - 代理保存与测试正常
+  - 自动审核保存正常
+- 统计：
+  - CPU/内存/磁盘/容器信息正常
+  - 运行中/排队中列表正常刷新
+  - 今日/累计统计正常显示
+- 任务日志：
+  - 筛选、分页、清理旧日志正常
+- 邮件配置：
+  - 全局开关/基础 URL 更新正常
+  - SMTP 新增/编辑/测试/设为主/删除正常
+  - 邮件统计/日志筛选/分页/清理正常
+- 设置：
+  - 修改用户名/密码后提示并强制重新登录
+
+---
+
+## 8. 需要你确认的问题（确认后再开始开发）
+
+已确认（来自你的回复）：
+
+- 范围：先改后台（`/yuyx/admin`），并同步美化后台登录页（`/yuyx`），仅 UI 不改登录逻辑
+- 技术：Vue3 + Vite 构建产物部署到 `static/admin/`；部署时允许拉依赖并构建
+- 布局：左侧导航 + 右侧内容（Admin Layout）
+- 风格：简洁克制（浅色背景 + 卡片 + 少量主色点缀）
+- 暗色模式：不需要
+- 适配：PC 优先；同时保证手机端不变形（必要时对表格做响应式处理/横向滚动）
+- 交互：允许把原生 `alert/confirm/prompt` 替换为 Element Plus 弹窗/对话框
+- 403 行为：保持现状（接口 403 时前端提示错误，不强制跳转登录页）
+- `/yuyx/vip`：为历史废弃入口，VIP 已整合在后台，已删除该路由
+
+仍需你确认（只剩 1 点，影响 Vite `base` 与反代配置）：
+
+1) 部署路径/前缀：
+- A. 你的站点是根路径部署（例如 `https://zsglpt.workyai.cn/` 直接访问就是本系统）
+- B. 你的站点是二级目录部署（例如 `https://example.com/zsglpt/`，需要告诉我前缀 `/zsglpt`）
+
+> 说明：域名本身没有影响，关键在“是否挂在二级目录”。若是根路径部署，我们默认使用 `/static/admin/` 与 `/yuyx/api/...` 即可。
+
+---
+
+## 9. 下一步
+
+你确认第 8 节后，我会按“分阶段交付”开始开发，并在每个阶段完成后给你可验收的版本点。