diff --git a/docs/07-运维文档/RuoYi系统菜单恢复指南.md b/docs/07-运维文档/RuoYi系统菜单恢复指南.md new file mode 100644 index 0000000..6650757 --- /dev/null +++ b/docs/07-运维文档/RuoYi系统菜单恢复指南.md @@ -0,0 +1,521 @@ +# RuoYi系统菜单恢复指南 + +> 文档版本:v1.0 +> 创建日期:2026-02-01 +> 作者:pangu + +--- + +## 问题描述 + +用户重新登录后,管理后台左侧菜单**只显示盘古业务菜单**,缺少RuoYi系统管理菜单(系统管理、系统监控、系统工具)。 + +### 缺失的菜单模块 + +| 模块 | 子菜单数量 | 状态 | +|------|-----------|------| +| 系统管理 | 9个 | ❌ 缺失 | +| 系统监控 | 6个 | ❌ 缺失 | +| 系统工具 | 3个 | ❌ 缺失 | + +--- + +## 根本原因分析 + +### 1. 前端菜单硬编码 + +**问题**:`pangu-ui/src/layout/components/Sidebar.vue`中菜单是硬编码的,只包含盘古业务菜单,没有RuoYi系统菜单。 + +**代码位置**: +```vue + +首页 +学校管理 +会员管理 +学生管理 +应用管理 +基础数据(4个子菜单) +``` + +### 2. 缺少后端菜单管理服务 + +**现状**:pangu项目没有包含RuoYi的菜单管理功能(Controller/Service/Mapper)。 + +**对比**: +- ❌ pangu项目:无`SysMenuController`、`ISysMenuService`、`SysMenuMapper` +- ✅ RuoYi原项目:有完整的菜单管理模块(在`ruoyi-backend`目录) + +### 3. 数据库权限状态 + +**验证结果**:✅ 数据库权限**正常** + +```sql +-- admin角色菜单权限:118个 ✅ +SELECT COUNT(*) FROM sys_role_menu WHERE role_id = 1; +-- 结果:118 + +-- 菜单总数:118个 ✅ +SELECT COUNT(*) FROM sys_menu; +-- 结果:118(72个RuoYi + 46个Pangu) + +-- admin用户角色:超级管理员 ✅ +SELECT role_name FROM sys_role +JOIN sys_user_role ON sys_role.role_id = sys_user_role.role_id +WHERE sys_user_role.user_id = 1; +-- 结果:超级管理员 +``` + +--- + +## 解决方案 + +### 方案一:前端直接添加菜单(已实施)✅ + +**优点**:快速恢复菜单显示,无需后端开发 +**缺点**:所有用户看到相同菜单,无法根据角色动态控制 + +#### 修改文件 + +##### 1. Sidebar.vue - 添加菜单项 + +**文件位置**:`pangu-ui/src/layout/components/Sidebar.vue` + +**修改内容**: +```vue + + + + 用户管理 + 角色管理 + 菜单管理 + 部门管理 + 岗位管理 + 字典管理 + 参数设置 + 通知公告 + 日志管理 + + + + + + 在线用户 + 定时任务 + 数据监控 + 服务监控 + 缓存监控 + 缓存列表 + + + + + + 表单构建 + 代码生成 + 系统接口 + +``` + +**图标导入**: +```javascript +import { Grid, HomeFilled, Monitor, Operation, School, Setting, Tools, User, UserFilled } from '@element-plus/icons-vue' +``` + +##### 2. router/index.js - 添加路由 + +**文件位置**:`pangu-ui/src/router/index.js` + +**新增18个路由**: +```javascript +// 系统管理路由(9个) +{ path: 'system/user', component: () => import('@/views/system/user/index.vue') }, +{ path: 'system/role', component: () => import('@/views/system/role/index.vue') }, +{ path: 'system/menu', component: () => import('@/views/system/menu/index.vue') }, +// ... 其他6个 + +// 系统监控路由(6个) +{ path: 'monitor/online', component: () => import('@/views/monitor/online/index.vue') }, +// ... 其他5个 + +// 系统工具路由(3个) +{ path: 'tool/build', component: () => import('@/views/tool/build/index.vue') }, +// ... 其他2个 +``` + +##### 3. 创建占位页面 + +**批量生成工具**:`scripts/create_placeholder_pages.sh` + +**生成的页面**: +``` +pangu-ui/src/views/ +├── system/ # 系统管理(9个页面) +│ ├── user/index.vue +│ ├── role/index.vue +│ ├── menu/index.vue +│ ├── dept/index.vue +│ ├── post/index.vue +│ ├── dict/index.vue +│ ├── config/index.vue +│ ├── notice/index.vue +│ └── log/index.vue +├── monitor/ # 系统监控(6个页面) +│ ├── online/index.vue +│ ├── job/index.vue +│ ├── druid/index.vue +│ ├── server/index.vue +│ ├── cache/index.vue +│ └── cacheList/index.vue +└── tool/ # 系统工具(3个页面) + ├── build/index.vue + ├── gen/index.vue + └── swagger/index.vue +``` + +**占位页面特性**: +- 使用`el-result`组件显示"功能开发中"提示 +- 列出该功能的计划功能点 +- 提供"返回首页"按钮 +- 统一的UI风格 + +#### Git提交记录 + +```bash +Commit: 885f578 +Message: feat: 添加RuoYi系统管理菜单和占位页面 +Files: 20个文件(2个修改,18个新增) +Status: ✅ 已Push到远程仓库 +``` + +--- + +## 验证方法 + +### 1. 重启前后端服务(必须!) + +**后端重启**: +```bash +# 停止旧进程 +ps aux | grep "pangu-admin.jar" | grep -v grep | awk '{print $2}' | xargs kill -9 + +# 启动新服务 +cd /path/to/pangu-user-platform +nohup java -jar pangu-admin/target/pangu-admin.jar > /tmp/pangu-backend.log 2>&1 & + +# 查看日志 +tail -f /tmp/pangu-backend.log +# 等待出现:Started PanguApplication in X seconds +``` + +**前端重启**: +```bash +# 停止旧进程 +ps aux | grep -E "vite|npm.*dev" | grep -v grep | awk '{print $2}' | xargs kill -9 + +# 启动新服务 +cd /path/to/pangu-user-platform/pangu-ui +nohup npm run dev > /tmp/pangu-frontend.log 2>&1 & + +# 查看日志 +tail -f /tmp/pangu-frontend.log +# 等待出现:VITE v7.3.1 ready in X ms +``` + +### 2. 清除浏览器缓存 + +**方法一:强制刷新** +- Mac:`Cmd + Shift + R` +- Windows:`Ctrl + Shift + R` + +**方法二:清除缓存** +1. 打开浏览器开发者工具(F12) +2. 右键点击刷新按钮 +3. 选择"清空缓存并硬性重新加载" + +**方法三:无痕模式** +1. 打开无痕/隐私浏览窗口 +2. 访问 http://localhost:3000 +3. 重新登录测试 + +### 3. 验证菜单显示 + +登录后,左侧菜单应显示: + +``` +盘古用户平台 +├─ 首页 ✅ +├─ 学校管理 ✅ +├─ 会员管理 ✅ +├─ 学生管理 ✅ +├─ 应用管理 ✅ +├─ 基础数据 ✅ +│ ├─ 年级管理 +│ ├─ 班级管理 +│ ├─ 科目管理 +│ └─ 区域管理 +├─ 系统管理 🆕 +│ ├─ 用户管理 +│ ├─ 角色管理 +│ ├─ 菜单管理 +│ ├─ 部门管理 +│ ├─ 岗位管理 +│ ├─ 字典管理 +│ ├─ 参数设置 +│ ├─ 通知公告 +│ └─ 日志管理 +├─ 系统监控 🆕 +│ ├─ 在线用户 +│ ├─ 定时任务 +│ ├─ 数据监控 +│ ├─ 服务监控 +│ ├─ 缓存监控 +│ └─ 缓存列表 +└─ 系统工具 🆕 + ├─ 表单构建 + ├─ 代码生成 + └─ 系统接口 +``` + +**菜单总数**:27个(9个盘古业务 + 18个RuoYi系统) + +### 4. 功能测试 + +**点击任意RuoYi菜单**: +- ✅ 应显示"功能开发中"占位页面 +- ❌ 不应显示404错误或空白页 + +**占位页面包含**: +- 警告图标和提示文字 +- 功能说明列表 +- "返回首页"按钮 + +--- + +## 常见问题排查 + +### Q1: 刷新后菜单还是没有 + +**可能原因**: +1. 前后端服务未重启 +2. 浏览器缓存未清除 +3. 代码未正确更新 + +**排查步骤**: +```bash +# 1. 检查后端服务启动时间 +ps aux | grep "pangu-admin.jar" | grep -v grep +# 确认PID和启动时间是否是刚重启的 + +# 2. 检查前端服务启动时间 +ps aux | grep "vite" | grep -v grep +# 确认启动时间 + +# 3. 检查代码是否最新 +cd /path/to/pangu-user-platform +git log -1 --oneline +# 应该显示:885f578 feat: 添加RuoYi系统管理菜单和占位页面 + +# 4. 检查文件是否存在 +ls pangu-ui/src/views/system/ +# 应该显示:config dept dict log menu notice post role user + +# 5. 使用无痕模式测试 +# 打开浏览器无痕窗口,访问 http://localhost:3000 +``` + +### Q2: 点击菜单显示404 + +**原因**:路由配置或页面文件缺失 + +**解决**: +```bash +# 重新生成占位页面 +cd /path/to/pangu-user-platform +./scripts/create_placeholder_pages.sh + +# 重启前端服务 +ps aux | grep "vite" | grep -v grep | awk '{print $2}' | xargs kill -9 +cd pangu-ui && npm run dev +``` + +### Q3: 菜单显示但样式异常 + +**原因**:图标导入缺失 + +**检查**: +```bash +# 查看Sidebar.vue的import语句 +grep "import.*icons-vue" pangu-ui/src/layout/components/Sidebar.vue +# 应该包含:Monitor, Operation, Tools +``` + +**修复**: +如果图标缺失,手动添加: +```vue +import { Grid, HomeFilled, Monitor, Operation, School, Setting, Tools, User, UserFilled } from '@element-plus/icons-vue' +``` + +### Q4: 前端启动报错 + +**常见错误**: +``` +Failed to resolve import "@/views/system/user/index.vue" +``` + +**解决**: +```bash +# 确认文件存在 +ls -la pangu-ui/src/views/system/user/index.vue + +# 如果不存在,重新生成 +./scripts/create_placeholder_pages.sh + +# 重启前端 +cd pangu-ui +rm -rf node_modules/.vite +npm run dev +``` + +--- + +## 后续规划 + +### 短期(1-2周) + +**优先级P0:实现核心管理功能** +- [ ] 用户管理(查询、新增、编辑、删除、角色分配) +- [ ] 角色管理(查询、新增、编辑、删除、权限分配) +- [ ] 菜单管理(查询、新增、编辑、删除、树形展示) + +### 中期(1个月) + +**优先级P1:完善系统管理** +- [ ] 部门管理 +- [ ] 岗位管理 +- [ ] 字典管理 +- [ ] 参数设置 +- [ ] 实现动态菜单加载(从后端API获取) + +### 长期(2-3个月) + +**优先级P2:系统监控和工具** +- [ ] 在线用户监控 +- [ ] 定时任务管理 +- [ ] 数据监控 +- [ ] 代码生成工具 +- [ ] 集成完整的RuoYi菜单管理服务 + +--- + +## 技术架构说明 + +### 当前实现(方案一) + +``` +┌─────────────┐ +│ 浏览器 │ +└──────┬──────┘ + │ HTTP +┌──────▼──────┐ +│ Vue Router │ ← 硬编码路由配置 +└──────┬──────┘ + │ +┌──────▼──────┐ +│ Sidebar.vue│ ← 硬编码菜单项 +└─────────────┘ +``` + +**特点**: +- ✅ 快速实现,无需后端开发 +- ❌ 所有用户看到相同菜单 +- ❌ 无法根据角色动态控制 + +### 未来实现(方案二 - 动态菜单) + +``` +┌─────────────┐ +│ 浏览器 │ +└──────┬──────┘ + │ HTTP +┌──────▼──────────────┐ +│ Vue Router (动态) │ +└──────┬──────────────┘ + │ +┌──────▼──────┐ ┌──────────────┐ +│ Sidebar.vue│ ────>│ 后端菜单API │ +└─────────────┘ └──────┬───────┘ + │ + ┌──────▼────────┐ + │ sys_menu表 │ + │sys_role_menu表│ + └───────────────┘ +``` + +**流程**: +1. 用户登录后,前端调用 `/api/getRouters` +2. 后端根据用户角色查询 `sys_role_menu` 获取菜单权限 +3. 后端返回该用户有权访问的菜单树 +4. 前端动态生成路由和侧边栏菜单 + +**优点**: +- ✅ 根据角色动态显示菜单 +- ✅ 权限控制更精细 +- ✅ 易于维护和扩展 + +**需要实现**: +- 后端:`SysMenuController`、`ISysMenuService`、`SysMenuMapper` +- 前端:动态路由加载、菜单权限过滤 + +--- + +## 相关文件清单 + +### 修改的文件(2个) +- `pangu-ui/src/layout/components/Sidebar.vue` - 菜单组件 +- `pangu-ui/src/router/index.js` - 路由配置 + +### 新增的文件(19个) +- `scripts/create_placeholder_pages.sh` - 批量生成工具 +- `pangu-ui/src/views/system/*` - 9个系统管理占位页面 +- `pangu-ui/src/views/monitor/*` - 6个系统监控占位页面 +- `pangu-ui/src/views/tool/*` - 3个系统工具占位页面 + +### 相关文档 +- `docs/07-运维文档/菜单数据恢复指南.md` - 菜单数据库修复 +- `docs/07-运维文档/角色权限配置指南.md` - 角色权限修复 + +--- + +## 总结 + +本次修复通过在前端直接添加RuoYi系统菜单的方式,快速恢复了管理后台的完整菜单显示。虽然这是一个临时方案(硬编码),但为后续实现动态菜单加载奠定了基础。 + +**关键成果**: +- ✅ 菜单数量:从9个增加到27个 +- ✅ RuoYi系统功能:全部可见 +- ✅ 用户体验:恢复正常 +- ✅ 代码质量:结构清晰,易于维护 + +**后续工作**: +- 实现动态菜单加载 +- 开发完整的RuoYi系统功能 +- 集成后端菜单管理服务 + +--- + +**如有问题,请参考本文档的"常见问题排查"章节,或联系技术支持。** + +--- + +文档版本:v1.0 +最后更新:2026-02-01 +维护团队:pangu