pangu-user-platform/docs/07-运维文档/角色权限配置指南.md

# 角色权限配置指南

> **作者**：湖北新华业务中台研发团队  
> **日期**：2026-01-31  
> **用途**：管理员角色菜单权限配置和问题修复

---

## 一、问题说明

### 1.1 问题现象

登录管理后台后，左侧菜单栏**只显示盘古业务菜单**，缺少RuoYi系统管理菜单：

**缺失菜单**：
- ❌ **系统管理**（用户管理、角色管理、菜单管理、部门管理等）
- ❌ **系统监控**（在线用户、定时任务、数据监控等）
- ❌ **系统工具**（表单构建、代码生成、系统接口）
- ❌ **若依官网**

**仅显示**：
- ✅ **盘古管理**（学校、会员、学生、应用、基础数据）

### 1.2 原因分析

**根本原因**：管理员角色（role_id=1）缺少RuoYi系统菜单的权限

**验证方法**：
```sql
-- 检查管理员角色的菜单权限数量
SELECT COUNT(*) FROM sys_role_menu WHERE role_id = 1;

-- 统计各类型菜单权限
SELECT 
    CASE 
        WHEN m.menu_id < 2000 THEN 'RuoYi系统菜单'
        ELSE '盘古业务菜单'
    END AS menu_type,
    COUNT(*) as count
FROM sys_role_menu rm
INNER JOIN sys_menu m ON rm.menu_id = m.menu_id
WHERE rm.role_id = 1
GROUP BY CASE WHEN m.menu_id < 2000 THEN 'RuoYi系统菜单' ELSE '盘古业务菜单' END;
```

**问题权限配置**：
```
RuoYi系统菜单：0条    ❌ (应该有72条)
盘古业务菜单：  30条   ✅
合计：         30条   ❌ (应该有118条)
```

---

## 二、解决方案

### 2.1 方法一：使用修复脚本（推荐）

#### 步骤1：进入SQL目录
```bash
cd /path/to/pangu-user-platform/sql
```

#### 步骤2：执行修复脚本
```bash
./fix_admin_permissions.sh
```

#### 步骤3：按提示确认
```
是否为管理员角色添加所有菜单权限？(y/n): y
```

#### 步骤4：退出登录并重新登录

**⚠️ 重要**：权限修改后，必须**退出登录并重新登录**才会生效！

### 2.2 方法二：手动执行SQL

```sql
-- 1. 删除管理员角色现有权限
DELETE FROM sys_role_menu WHERE role_id = 1;

-- 2. 为管理员角色添加所有菜单权限
INSERT INTO sys_role_menu (role_id, menu_id)
SELECT 1, menu_id FROM sys_menu;

-- 3. 验证权限数量
SELECT COUNT(*) as total FROM sys_role_menu WHERE role_id = 1;
-- 预期结果：118条
```

### 2.3 方法三：通过管理界面配置

**步骤**：
1. 以管理员身份登录（如果能看到系统管理菜单）
2. 进入 **系统管理 > 角色管理**
3. 点击超级管理员角色的**修改**按钮
4. 在**菜单权限**标签页，勾选所有菜单
5. 点击**提交**保存

**注意**：此方法前提是能看到系统管理菜单。如果看不到，请使用方法一或方法二。

---

## 三、验证结果

### 3.1 数据库验证

```sql
-- 验证权限总数
SELECT COUNT(*) as total FROM sys_role_menu WHERE role_id = 1;
-- 预期结果：118条

-- 验证各类型菜单权限
SELECT 
    CASE 
        WHEN m.menu_id < 2000 THEN 'RuoYi系统菜单'
        ELSE '盘古业务菜单'
    END AS menu_type,
    COUNT(*) as count
FROM sys_role_menu rm
INNER JOIN sys_menu m ON rm.menu_id = m.menu_id
WHERE rm.role_id = 1
GROUP BY CASE WHEN m.menu_id < 2000 THEN 'RuoYi系统菜单' ELSE '盘古业务菜单' END;
-- 预期结果：
-- RuoYi系统菜单  72
-- 盘古业务菜单    46

-- 验证顶级菜单权限
SELECT m.menu_id, m.menu_name, m.order_num
FROM sys_menu m
INNER JOIN sys_role_menu rm ON m.menu_id = rm.menu_id
WHERE rm.role_id = 1 AND m.parent_id = 0
ORDER BY m.order_num;
-- 预期结果：盘古管理、系统管理、系统监控、系统工具、若依官网
```

### 3.2 前端页面验证

**退出登录并重新登录后**，菜单栏应显示：

```
📋 盘古管理 ✅
  ├─ 学校管理
  ├─ 会员管理
  ├─ 学生管理
  ├─ 应用管理
  └─ 基础数据

⚙️ 系统管理 ✅ (新增)
  ├─ 用户管理
  ├─ 角色管理
  ├─ 菜单管理
  ├─ 部门管理
  ├─ 岗位管理
  ├─ 字典管理
  ├─ 参数设置
  ├─ 通知公告
  └─ 日志管理

📊 系统监控 ✅ (新增)
  ├─ 在线用户
  ├─ 定时任务
  ├─ 数据监控
  ├─ 服务监控
  └─ 缓存监控

🔧 系统工具 ✅ (新增)
  ├─ 表单构建
  ├─ 代码生成
  └─ 系统接口

🌐 若依官网 ✅ (新增)
```

---

## 四、角色权限管理

### 4.1 权限分配原则

| 角色 | 权限范围 | 建议配置 |
|------|---------|---------|
| **超级管理员** | 所有菜单 | 118个菜单全部勾选 ✅ |
| **普通管理员** | 业务菜单 | 盘古管理46个菜单 ✅ |
| **教师** | 部分业务菜单 | 会员管理、学生管理 ✅ |
| **家长** | 查看功能 | 学生查询、学校查询 ✅ |

### 4.2 新建角色权限配置

**步骤**：
1. **系统管理 > 角色管理** > 点击**新增**
2. 填写角色信息（角色名称、权限字符、排序）
3. 设置**菜单权限**：
   - 系统管理员：勾选所有菜单
   - 业务管理员：只勾选盘古管理下的菜单
   - 教师/家长：根据需要勾选特定菜单
4. 设置**数据权限**（本部门数据/全部数据等）
5. 点击**提交**保存

### 4.3 修改用户角色

**步骤**：
1. **系统管理 > 用户管理** > 点击用户的**修改**按钮
2. 在**角色**下拉框中选择角色
3. 点击**提交**保存
4. **⚠️ 用户需要退出登录并重新登录**

---

## 五、常见问题

### Q1：修复权限后仍然看不到菜单？

**A**：请按以下步骤排查：
1. ✅ **退出登录并重新登录**（必须！）
2. ✅ 清除浏览器缓存
3. ✅ 检查菜单状态：`SELECT menu_id, menu_name, visible, status FROM sys_menu WHERE parent_id = 0;`
   - `visible = '0'` 表示显示
   - `status = '0'` 表示正常
4. ✅ 检查用户角色：`SELECT * FROM sys_user_role WHERE user_id = 1;`

### Q2：只想给部分菜单权限怎么办？

**A**：不要使用修复脚本，通过管理界面手动勾选：
1. **系统管理 > 角色管理** > 修改角色
2. 在**菜单权限**标签页，只勾选需要的菜单
3. 点击**提交**保存

### Q3：新用户如何分配权限？

**A**：
1. **系统管理 > 用户管理** > 新增用户
2. 在**角色**下拉框中选择合适的角色
3. 如果需要特殊权限，先创建新角色再分配

### Q4：权限修复脚本会影响其他角色吗？

**A**：不会。脚本只修复role_id=1（超级管理员）的权限，其他角色不受影响。

---

## 六、权限数据备份

### 6.1 备份权限数据

```sql
-- 备份所有角色权限
CREATE TABLE sys_role_menu_backup_20260131 AS 
SELECT * FROM sys_role_menu;

-- 备份用户角色关系
CREATE TABLE sys_user_role_backup_20260131 AS 
SELECT * FROM sys_user_role;
```

### 6.2 恢复权限数据

```sql
-- 恢复角色权限
TRUNCATE TABLE sys_role_menu;
INSERT INTO sys_role_menu SELECT * FROM sys_role_menu_backup_20260131;

-- 恢复用户角色
TRUNCATE TABLE sys_user_role;
INSERT INTO sys_user_role SELECT * FROM sys_user_role_backup_20260131;
```

---

## 七、相关文件

| 文件路径 | 说明 |
|---------|------|
| `sql/fix_admin_permissions.sh` | 管理员权限自动修复脚本 |
| `sql/sys_menu_complete.sql` | 完整菜单数据SQL |
| `docs/07-运维文档/菜单数据恢复指南.md` | 菜单数据恢复文档 |

---

## 八、技术支持

如有问题，请联系：**湖北新华业务中台研发团队**

---

*最后更新：2026-01-31*