From 807d8891d56cd08590bc4d3070e515eb517b4cbf Mon Sep 17 00:00:00 2001
From: duanshuwen <duanshuwen@gogpay.cn>
Date: Wed, 26 Aug 2026 20:09:08 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=BE=E8=AE=A1=20RuoYi=20=E7=AE=A1?=
 =?UTF-8?q?=E7=90=86=E7=AB=AF=E5=B8=83=E5=B1=80=E5=A3=B3=E8=BF=98=E5=8E=9F?=
 =?UTF-8?q?=E6=96=B9=E6=A1=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...6-08-26-ruoyi-admin-shell-visual-design.md | 173 ++++++++++++++++++
 1 file changed, 173 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-26-ruoyi-admin-shell-visual-design.md

diff --git a/docs/superpowers/specs/2026-08-26-ruoyi-admin-shell-visual-design.md b/docs/superpowers/specs/2026-08-26-ruoyi-admin-shell-visual-design.md
new file mode 100644
index 0000000..d7602a1
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-26-ruoyi-admin-shell-visual-design.md
@@ -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 契约，不执行数据库迁移或重置。