# 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 契约，不执行数据库迁移或重置。