docs: 设计 RuoYi 管理端布局壳还原方案
This commit is contained in:
duanshuwen
@@ -0,0 +1,173 @@
|
||||
# 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 风格布局组合：
|
||||
|
||||
```text
|
||||
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. 验证计划
|
||||
|
||||
自动验证：
|
||||
|
||||
```powershell
|
||||
Set-Location .\WonderQ-Admin-UI-Vue
|
||||
yarn test
|
||||
yarn build
|
||||
```
|
||||
|
||||
浏览器验证：
|
||||
|
||||
1. 1440px：检查深色侧栏、200px/54px 切换、50px 顶栏、34px 页签和页面滚动。
|
||||
2. 1024px：检查临界断点和侧栏收起行为。
|
||||
3. 390px：检查移动端抽屉、遮罩、自动关闭和业务页面横向溢出。
|
||||
4. 依次验证首页、玩法、管家、线索、媒体、工具和系统资源页面的导航与页签。
|
||||
5. 验证页签右键菜单、设置抽屉即时切换、用户下拉退出和全屏按钮。
|
||||
6. 检查控制台无新增错误，确认 `/api/admin/...` 请求路径和业务响应结构未变化。
|
||||
|
||||
## 8. 风险与控制
|
||||
|
||||
- RuoYi 的顶部菜单、混合菜单会改变菜单展示位置，因此只在布局设置中改变壳层展示，不改变 `auth.menus`、权限码和路由路径。
|
||||
- 移动端抽屉和固定 Header 可能影响原有业务页面高度，需在三种宽度下检查滚动容器和弹层层级。
|
||||
- TagsView 关闭/刷新可能触发页面重新挂载，使用现有 `routeViewKey` 并验证表单未提交状态的预期行为。
|
||||
- 不修改后端、数据库、迁移、鉴权和 API 契约，不执行数据库迁移或重置。
|
||||
Reference in New Issue
Block a user