7.6 KiB
WonderQ Admin UI Vue RuoYi 默认后台壳还原设计
1. 背景与目标
WonderQ-Admin-UI-Vue 当前使用自定义浅色侧栏和 88px 顶部区域。本次以仓库内 RuoYi-Vue3 的默认布局实现为唯一视觉与交互参考，将 WonderQ 管理端的后台壳完整还原为 RuoYi 默认后台结构，同时保留 WonderQ 已有业务页面、路由、权限和 API。
目标包括：
- 200px 深色侧栏、54px 折叠侧栏和递归权限菜单。
- 50px 顶部导航、汉堡按钮、面包屑和右侧工具栏。
- 34px TagsView 页签及关闭、刷新、右键菜单操作。
- 桌面端侧栏折叠、992px 移动端抽屉和遮罩交互。
- 用户下拉菜单、退出确认和布局设置入口。
- 右侧布局设置抽屉及 RuoYi 默认布局配置项。
2. 保留边界
以下能力保持现状，不因布局改造而改变：
auth.menus、权限码、动态路由注册和鉴权流程。src/api/下的请求路径、请求方法、Token 存储和响应类型。- 首页、玩法、管家、线索、媒体、运营工具和系统资源等业务页面。
- 业务页面对后端 API 的调用、字段转换、加载态、错误态和提交行为。
- WonderQ 现有品牌名称和中文菜单内容。
用户下拉只提供现有范围内可兑现的布局设置和退出登录，不新增没有路由与业务契约支撑的个人中心页面。
3. 布局结构
将 AdminLayout.vue 调整为职责清晰的 RuoYi 风格布局组合：
AdminLayout
├─ Sidebar
│ ├─ SidebarLogo
│ └─ SidebarMenu / SidebarItem
├─ MainContainer
│ ├─ Navbar
│ │ ├─ Hamburger
│ │ ├─ Breadcrumb
│ │ ├─ HeaderTools
│ │ └─ UserMenu
│ ├─ TagsView
│ └─ AppMain
│ └─ RouterView
└─ SettingsDrawer
建议的职责文件：
src/layouts/AdminLayout.vue：仅负责布局编排、响应式状态和 RouterView。src/components/layout/Sidebar.vue：侧栏容器、折叠状态和移动端抽屉。src/components/layout/SidebarItem.vue：递归目录与页面菜单项。src/components/layout/Navbar.vue：顶栏、汉堡按钮、面包屑、工具栏和用户菜单。src/components/layout/TagsView.vue：页签渲染、关闭和右键菜单。src/components/layout/SettingsDrawer.vue：布局设置表单和即时预览。src/stores/layout.ts：侧栏、设备类型和壳层状态。src/stores/tags.ts：访问页签、固定页签和页签操作。src/lib/layout-settings.ts：默认值、本地存储读写和设置归一化。
菜单继续消费现有 AdminMenu 类型。菜单图标优先使用 AdminMenu.icon，缺失时按路径或组件名提供 Element Plus 图标回退，不修改 Admin API 契约。
4. 状态与数据流
4.1 布局状态
layout store 管理：
sidebarOpened：桌面端侧栏是否展开。mobile：当前是否处于移动端断点。withoutAnimation：切换时是否关闭过渡。settingsDrawerOpen：布局设置抽屉是否打开。
断点沿用 RuoYi：视口小于 992px 时进入移动端。桌面端侧栏宽度为 200px，折叠后为 54px；移动端侧栏保持 200px，并通过平移和遮罩控制显示。
4.2 页签状态
tags store 管理：
- 固定的首页页签。
- 当前路由对应的访问页签。
- 页签的
path、fullPath、name、title和query。 - 当前页刷新、关闭当前、关闭其他、关闭左右侧和关闭全部。
路由变化后由布局层登记页签，重复访问同一路径只激活已有页签。刷新当前页使用现有的 routeViewKey 机制或等价的组件 key 更新，不改变 API 数据。
4.3 设置状态
使用独立的 wonderq-admin-layout-setting 本地存储键，避免与鉴权 Token 和其他项目配置耦合。设置项包括：
navType：左侧菜单、混合菜单、顶部菜单。sideTheme：深色或浅色侧栏。theme：主色。tagsView、tagsViewPersist、tagsIcon、tagsViewStyle。fixedHeader、sidebarLogo、dynamicTitle、footerVisible。
读取本地配置时通过归一化函数过滤未知值，缺失或非法配置回退到 RuoYi 默认值。设置即时生效，保存后可在刷新页面后恢复，重置操作清理布局配置和持久化页签。
5. 交互设计
5.1 侧栏与移动端
- 桌面端点击汉堡按钮在 200px 与 54px 之间切换。
- 折叠时显示图标，菜单项保留可访问名称和悬停提示。
- 目录菜单保持单目录展开，当前路由使用 RuoYi 风格激活背景和主色文字。
- 移动端打开侧栏时渲染半透明遮罩，点击遮罩关闭。
- 移动端导航到页面后自动关闭侧栏。
5.2 顶栏与用户菜单
- 顶栏固定高度 50px，左侧显示汉堡按钮和动态面包屑。
- 右侧提供全屏、明暗主题、布局设置等工具入口。
- 用户下拉显示当前用户名称，提供布局设置和退出登录。
- 退出沿用现有确认弹窗、
auth.logout()和登录页跳转。
5.3 TagsView
- 首页页签固定存在；其他页面首次访问时创建页签。
- 当前页签使用 RuoYi 主色激活样式。
- 页签支持关闭按钮、中键关闭和右键菜单。
- 右键菜单提供刷新当前、关闭当前、关闭其他、关闭左侧、关闭右侧和全部关闭。
- 关闭当前页后跳转到最近可用页签；关闭全部后回到首页。
- 页签内容超出容器时水平滚动，并自动定位当前页。
5.4 布局设置抽屉
- 从右侧打开，默认宽度 300px，与 RuoYi 设置抽屉保持一致。
- 提供导航模式、主题风格、主色和系统布局配置。
- 依赖 TagsView 的选项在 TagsView 关闭时禁用。
- 保存配置给出成功提示；重置配置清除本地设置并恢复默认布局。
6. 视觉基线
以 RuoYi-Vue3/src/assets/styles/variables.module.scss 和布局组件样式为准：
- 侧栏背景：
#304156。 - 侧栏悬停/激活背景：
#263445。 - 子菜单背景：
#1f2d3d。 - 菜单文字：
#bfcbd9。 - 激活文字与主色：
#409eff。 - 主内容背景：RuoYi 默认浅灰背景。
- 侧栏：200px / 54px。
- Navbar：50px。
- TagsView：34px。
- 页面表格、表单、弹窗优先使用 Element Plus 默认尺寸、边框和状态。
业务页面保留现有内容，仅统一页面壳的内容起始位置、固定 Header 下的滚动区域和移动端边距；不对业务字段或业务交互做无关重构。
7. 验证计划
自动验证：
Set-Location .\WonderQ-Admin-UI-Vue
yarn test
yarn build
浏览器验证：
- 1440px：检查深色侧栏、200px/54px 切换、50px 顶栏、34px 页签和页面滚动。
- 1024px：检查临界断点和侧栏收起行为。
- 390px：检查移动端抽屉、遮罩、自动关闭和业务页面横向溢出。
- 依次验证首页、玩法、管家、线索、媒体、工具和系统资源页面的导航与页签。
- 验证页签右键菜单、设置抽屉即时切换、用户下拉退出和全屏按钮。
- 检查控制台无新增错误，确认
/api/admin/...请求路径和业务响应结构未变化。
8. 风险与控制
- RuoYi 的顶部菜单、混合菜单会改变菜单展示位置，因此只在布局设置中改变壳层展示，不改变
auth.menus、权限码和路由路径。 - 移动端抽屉和固定 Header 可能影响原有业务页面高度，需在三种宽度下检查滚动容器和弹层层级。
- TagsView 关闭/刷新可能触发页面重新挂载，使用现有
routeViewKey并验证表单未提交状态的预期行为。 - 不修改后端、数据库、迁移、鉴权和 API 契约，不执行数据库迁移或重置。