559 lines
14 KiB
Markdown
559 lines
14 KiB
Markdown
# RBAC 路由权限集成说明
|
||
|
||
## 📋 概述
|
||
|
||
本文档说明如何将前端 Sidebar 菜单与后端 RBAC（基于角色的访问控制）路由权限系统集成。
|
||
|
||
前端通过调用后端的 `/rbac/user/routes` 接口获取当前用户有权限访问的路由列表，然后根据这些路由动态生成侧边栏菜单。
|
||
|
||
---
|
||
|
||
## 🔄 工作流程
|
||
|
||
```
|
||
1. 用户登录成功
|
||
↓
|
||
2. 前端存储 JWT token 和用户信息到 localStorage
|
||
↓
|
||
3. Layout 组件从 localStorage 读取 user_role 和 access_token
|
||
↓
|
||
4. 传递给 Sidebar 组件
|
||
↓
|
||
5. Sidebar 调用 getUserRoutesByRole(roleKey, jwt)
|
||
↓
|
||
6. 该函数调用后端接口 GET /rbac/user/routes
|
||
↓
|
||
7. 后端根据 JWT 中的用户信息查询该用户的路由权限
|
||
↓
|
||
8. 返回路由树结构（包含嵌套的 children）
|
||
↓
|
||
9. 前端将后端路由格式转换为 MenuItem 格式
|
||
↓
|
||
10. Sidebar 根据 MenuItem 数组渲染菜单
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 修改的文件
|
||
|
||
### 1. `app/api/auth/user-routes.ts`
|
||
|
||
#### 新增接口定义
|
||
|
||
```typescript
|
||
// 后端返回的路由数据接口
|
||
export interface BackendRouteInfo {
|
||
id: number;
|
||
route_path: string;
|
||
route_name: string;
|
||
component: string;
|
||
parent_id: number | null;
|
||
route_title: string;
|
||
icon: string | null;
|
||
sort_order: number;
|
||
is_hidden: boolean;
|
||
is_cache: boolean;
|
||
meta: string;
|
||
children?: BackendRouteInfo[];
|
||
}
|
||
|
||
// 后端API响应接口
|
||
export interface BackendRoutesResponse {
|
||
code: number;
|
||
msg: string;
|
||
data: {
|
||
user_id: number;
|
||
username: string;
|
||
routes: BackendRouteInfo[];
|
||
};
|
||
}
|
||
```
|
||
|
||
#### 修改 `getUserRoutesByRole` 函数
|
||
|
||
**之前**：通过多次 PostgREST 查询获取路由
|
||
```typescript
|
||
// 查询 roles 表 → role_route 表 → sys_routes 表
|
||
// 需要 3 次数据库查询
|
||
```
|
||
|
||
**现在**：调用后端统一接口
|
||
```typescript
|
||
export async function getUserRoutesByRole(roleKey: string, jwt?: string) {
|
||
// 调用后端统一接口
|
||
const response = await apiRequest<BackendRoutesResponse>({
|
||
method: 'GET',
|
||
url: '/rbac/user/routes',
|
||
headers: {
|
||
'Authorization': `Bearer ${jwt}`
|
||
}
|
||
});
|
||
|
||
// 转换后端路由格式为前端 MenuItem 格式
|
||
const menuItems = convertBackendRoutesToMenuItems(response.data.routes);
|
||
|
||
return { success: true, data: menuItems };
|
||
}
|
||
```
|
||
|
||
#### 新增转换函数
|
||
|
||
```typescript
|
||
/**
|
||
* 将后端路由格式转换为前端 MenuItem 格式
|
||
*/
|
||
function convertBackendRoutesToMenuItems(backendRoutes: BackendRouteInfo[]): MenuItem[] {
|
||
return backendRoutes
|
||
.filter(route => !route.is_hidden) // 过滤隐藏的路由
|
||
.map(route => {
|
||
const menuItem: MenuItem = {
|
||
id: route.route_name || `route-${route.id}`,
|
||
title: route.route_title,
|
||
path: route.route_path,
|
||
icon: convertIcon(route.icon),
|
||
order: route.sort_order,
|
||
hideBreadcrumb: route.is_hidden
|
||
};
|
||
|
||
// 递归处理子路由
|
||
if (route.children && route.children.length > 0) {
|
||
menuItem.children = convertBackendRoutesToMenuItems(route.children);
|
||
}
|
||
|
||
return menuItem;
|
||
})
|
||
.sort((a, b) => a.order - b.order);
|
||
}
|
||
```
|
||
|
||
#### 图标映射
|
||
|
||
Element UI 图标 → RemixIcon 映射：
|
||
|
||
```typescript
|
||
const ICON_MAPPING: Record<string, string> = {
|
||
'el-icon-s-home': 'ri-home-line',
|
||
'el-icon-house': 'ri-home-4-line',
|
||
'el-icon-document': 'ri-file-text-line',
|
||
'el-icon-edit': 'ri-edit-line',
|
||
'el-icon-connection': 'ri-links-line',
|
||
'el-icon-setting': 'ri-settings-4-line',
|
||
'el-icon-user': 'ri-user-line',
|
||
'el-icon-tickets': 'ri-ticket-line',
|
||
'el-icon-chat-dot-round': 'ri-chat-smile-2-line',
|
||
'el-icon-s-order': 'ri-list-check',
|
||
'el-icon-s-grid': 'ri-grid-line',
|
||
'el-icon-s-comment': 'ri-chat-1-line',
|
||
'el-icon-files': 'ri-file-copy-line',
|
||
'el-icon-folder': 'ri-folder-line',
|
||
'el-icon-upload': 'ri-upload-cloud-line',
|
||
'el-icon-download': 'ri-download-cloud-line',
|
||
'el-icon-search': 'ri-search-line',
|
||
};
|
||
```
|
||
|
||
#### 角色映射增强
|
||
|
||
```typescript
|
||
export function mapUserRoleToRoleKey(userRole: string): string {
|
||
const roleMapping: Record<string, string> = {
|
||
'common': 'common',
|
||
'admin': 'admin',
|
||
'deptLeader': 'deptLeader',
|
||
'groupLeader': 'groupLeader',
|
||
// 添加常见的后端角色映射
|
||
'super_admin': 'admin',
|
||
'system_admin': 'admin',
|
||
'user': 'common',
|
||
'developer': 'admin'
|
||
};
|
||
|
||
// 如果找不到映射，返回 userRole 本身
|
||
return roleMapping[userRole] || userRole || 'common';
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. `app/components/layout/Layout.tsx`
|
||
|
||
#### 新增从 localStorage 读取用户信息
|
||
|
||
```typescript
|
||
export function Layout({ children, userRole = 'developer' as UserRole, frontendJWT = '' }: LayoutProps) {
|
||
const [effectiveUserRole, setEffectiveUserRole] = useState<UserRole>(userRole);
|
||
const [effectiveFrontendJWT, setEffectiveFrontendJWT] = useState<string>(frontendJWT);
|
||
|
||
// 从 localStorage 读取用户信息和 JWT 作为备用方案
|
||
useEffect(() => {
|
||
if (typeof window === 'undefined') return;
|
||
|
||
try {
|
||
// 如果服务端没有传递 userRole，从 localStorage 读取
|
||
if (!userRole || userRole === '') {
|
||
const storedUserInfoStr = localStorage.getItem('user_info');
|
||
if (storedUserInfoStr) {
|
||
const storedUserInfo = JSON.parse(storedUserInfoStr);
|
||
const storedUserRole = storedUserInfo.user_role || 'common';
|
||
console.log('📖 [Layout] 从 localStorage 读取用户角色:', storedUserRole);
|
||
setEffectiveUserRole(storedUserRole as UserRole);
|
||
}
|
||
} else {
|
||
setEffectiveUserRole(userRole);
|
||
}
|
||
|
||
// 如果服务端没有传递 frontendJWT，从 localStorage 读取
|
||
if (!frontendJWT || frontendJWT === '') {
|
||
const storedToken = localStorage.getItem('access_token');
|
||
if (storedToken) {
|
||
console.log('📖 [Layout] 从 localStorage 读取 JWT token');
|
||
setEffectiveFrontendJWT(storedToken);
|
||
}
|
||
} else {
|
||
setEffectiveFrontendJWT(frontendJWT);
|
||
}
|
||
} catch (error) {
|
||
console.error('❌ [Layout] 读取 localStorage 失败:', error);
|
||
}
|
||
}, [userRole, frontendJWT]);
|
||
|
||
// 传递给 Sidebar
|
||
<Sidebar
|
||
collapsed={sidebarCollapsed}
|
||
onToggle={toggleSidebar}
|
||
userRole={effectiveUserRole}
|
||
selectedApp={selectedApp}
|
||
frontendJWT={effectiveFrontendJWT}
|
||
/>
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. `app/components/layout/Sidebar.tsx`
|
||
|
||
#### 修改路由获取逻辑
|
||
|
||
```typescript
|
||
// 获取用户路由权限
|
||
useEffect(() => {
|
||
const fetchUserRoutes = async () => {
|
||
setIsLoadingRoutes(true);
|
||
try {
|
||
// 优先使用传入的 frontendJWT，否则从 localStorage 读取
|
||
let jwt = frontendJWT;
|
||
|
||
if (!jwt && typeof window !== 'undefined') {
|
||
jwt = localStorage.getItem('access_token') || '';
|
||
console.log('📖 [Sidebar] 从 localStorage 读取 JWT');
|
||
}
|
||
|
||
if (!jwt) {
|
||
console.error('❌ [Sidebar] JWT token 未找到');
|
||
setMenuItems([]);
|
||
setIsLoadingRoutes(false);
|
||
return;
|
||
}
|
||
|
||
console.log('🔍 [Sidebar] 当前用户角色:', userRole);
|
||
const roleKey = mapUserRoleToRoleKey(userRole);
|
||
const result = await getUserRoutesByRole(roleKey, jwt);
|
||
|
||
if (result.success && result.data) {
|
||
setMenuItems(result.data);
|
||
console.log('✅ [Sidebar] 用户路由权限加载成功:', result.data);
|
||
} else {
|
||
console.error('❌ [Sidebar] 获取用户路由权限失败:', result.error);
|
||
|
||
// 如果需要重定向到首页
|
||
if (result.shouldRedirectToHome) {
|
||
console.log('🔄 [Sidebar] 重定向到首页');
|
||
navigate('/');
|
||
return;
|
||
}
|
||
|
||
// 其他错误情况，使用空数组
|
||
setMenuItems([]);
|
||
}
|
||
} catch (error) {
|
||
console.error('❌ [Sidebar] 获取用户路由权限时发生错误:', error);
|
||
navigate('/');
|
||
return;
|
||
} finally {
|
||
setIsLoadingRoutes(false);
|
||
}
|
||
};
|
||
|
||
fetchUserRoutes();
|
||
}, [userRole, frontendJWT, navigate]);
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 后端接口
|
||
|
||
### 请求
|
||
|
||
```http
|
||
GET /rbac/user/routes
|
||
Authorization: Bearer {JWT_TOKEN}
|
||
```
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "成功",
|
||
"data": {
|
||
"user_id": 5,
|
||
"username": "admin",
|
||
"routes": [
|
||
{
|
||
"id": 30,
|
||
"route_path": "/",
|
||
"route_name": "Index",
|
||
"component": "views/Index.vue",
|
||
"parent_id": null,
|
||
"route_title": "入口页",
|
||
"icon": "el-icon-s-home",
|
||
"sort_order": 0,
|
||
"is_hidden": false,
|
||
"is_cache": false,
|
||
"meta": "{\"requiresAuth\": true}"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"route_path": "/documents",
|
||
"route_name": "Documents",
|
||
"component": "views/documents/Index.vue",
|
||
"parent_id": null,
|
||
"route_title": "文档管理",
|
||
"icon": "el-icon-document",
|
||
"sort_order": 2,
|
||
"is_hidden": false,
|
||
"is_cache": true,
|
||
"meta": "{\"requiresAuth\": true}",
|
||
"children": [
|
||
{
|
||
"id": 32,
|
||
"route_path": "/documents/upload",
|
||
"route_name": "DocumentUpload",
|
||
"component": "views/documents/Upload.vue",
|
||
"parent_id": 2,
|
||
"route_title": "上传文档",
|
||
"icon": null,
|
||
"sort_order": 1,
|
||
"is_hidden": false,
|
||
"is_cache": false,
|
||
"meta": "{\"requiresAuth\": true}"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 测试步骤
|
||
|
||
### 1. 准备测试环境
|
||
|
||
确保后端接口 `/rbac/user/routes` 已经实现并正常运行。
|
||
|
||
### 2. 清除旧数据
|
||
|
||
在浏览器开发者工具控制台执行：
|
||
|
||
```javascript
|
||
localStorage.clear()
|
||
location.reload()
|
||
```
|
||
|
||
### 3. 登录测试
|
||
|
||
使用测试账号登录：
|
||
|
||
| 用户名 | 密码 | 角色 | 预期路由数 |
|
||
|--------|------|------|-----------|
|
||
| 000 | admin06111 | 超级管理员 | 29 |
|
||
| 001 | gdyc06111 | 普通用户 | 19 |
|
||
|
||
### 4. 观察控制台日志
|
||
|
||
登录成功后应该看到：
|
||
|
||
```
|
||
📖 [Layout] 从 localStorage 读取用户角色: admin
|
||
📖 [Layout] 从 localStorage 读取 JWT token
|
||
🔍 [Sidebar] 当前用户角色: admin
|
||
🔍 [User Routes] 获取用户路由，角色: admin
|
||
🔍 [User Routes] 后端返回: { code: 0, msg: "成功", data: {...} }
|
||
✅ [User Routes] 成功获取 29 个路由
|
||
📋 [User Routes] 菜单数据: [...]
|
||
✅ [Sidebar] 用户路由权限加载成功: [...]
|
||
```
|
||
|
||
### 5. 验证菜单显示
|
||
|
||
- ✅ 侧边栏显示正确的菜单项
|
||
- ✅ 菜单项按 `sort_order` 排序
|
||
- ✅ 有子菜单的项可以展开/折叠
|
||
- ✅ 图标正确显示（RemixIcon）
|
||
- ✅ `is_hidden: true` 的路由不显示在菜单中
|
||
|
||
### 6. 测试不同角色
|
||
|
||
切换不同角色的账号登录，验证：
|
||
|
||
- 不同角色看到的菜单项数量不同
|
||
- 权限较低的角色看不到高权限路由
|
||
|
||
---
|
||
|
||
## ❌ 常见问题
|
||
|
||
### Q1: 侧边栏显示空白或加载失败
|
||
|
||
**可能原因**：
|
||
1. JWT token 未正确传递
|
||
2. 后端接口返回格式不正确
|
||
3. 用户角色映射失败
|
||
|
||
**排查步骤**：
|
||
```javascript
|
||
// 检查 localStorage
|
||
console.log('Token:', localStorage.getItem('access_token'));
|
||
console.log('User Info:', localStorage.getItem('user_info'));
|
||
|
||
// 手动测试后端接口
|
||
const token = localStorage.getItem('access_token');
|
||
fetch('http://172.16.0.55:8073/rbac/user/routes', {
|
||
headers: { 'Authorization': `Bearer ${token}` }
|
||
}).then(r => r.json()).then(console.log);
|
||
```
|
||
|
||
---
|
||
|
||
### Q2: 菜单图标不显示
|
||
|
||
**可能原因**：
|
||
- Element UI 图标未映射到 RemixIcon
|
||
- 后端返回的 icon 字段为 null
|
||
|
||
**解决方案**：
|
||
在 `ICON_MAPPING` 中添加缺失的图标映射。
|
||
|
||
---
|
||
|
||
### Q3: 后端返回 401 错误
|
||
|
||
**可能原因**：
|
||
- JWT token 过期
|
||
- 后端认证中间件配置错误
|
||
- `/rbac/user/routes` 未添加到白名单
|
||
|
||
**解决方案**：
|
||
确保后端允许 `/rbac/user/routes` 接口使用 JWT 认证。
|
||
|
||
---
|
||
|
||
### Q4: 角色映射失败
|
||
|
||
**可能原因**：
|
||
- 后端返回的 `user_role` 字段值与前端映射不一致
|
||
|
||
**解决方案**：
|
||
在 `mapUserRoleToRoleKey` 中添加新的角色映射。
|
||
|
||
```typescript
|
||
export function mapUserRoleToRoleKey(userRole: string): string {
|
||
const roleMapping: Record<string, string> = {
|
||
// 添加新的角色映射
|
||
'new_role': 'admin',
|
||
};
|
||
|
||
return roleMapping[userRole] || userRole || 'common';
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 数据流图
|
||
|
||
```
|
||
┌─────────────┐
|
||
│ 用户登录 │
|
||
└──────┬──────┘
|
||
│
|
||
▼
|
||
┌─────────────────────┐
|
||
│ 存储到 localStorage │
|
||
│ - access_token │
|
||
│ - user_info │
|
||
└──────┬──────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────┐
|
||
│ Layout 组件加载 │
|
||
│ 读取 localStorage │
|
||
└──────┬──────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────┐
|
||
│ Sidebar 组件加载 │
|
||
│ 调用路由接口 │
|
||
└──────┬──────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────┐
|
||
│ GET /rbac/user/routes│
|
||
│ Authorization: Bearer│
|
||
└──────┬──────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────┐
|
||
│ 后端返回路由树 │
|
||
└──────┬──────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────┐
|
||
│ 转换为 MenuItem │
|
||
│ - route_path → path│
|
||
│ - route_title → title│
|
||
│ - icon 映射 │
|
||
│ - 递归处理 children│
|
||
└──────┬──────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────┐
|
||
│ 渲染侧边栏菜单 │
|
||
└─────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 总结
|
||
|
||
### 核心改动
|
||
|
||
1. **调用后端统一接口**：`GET /rbac/user/routes`
|
||
2. **数据格式转换**：后端格式 → MenuItem 格式
|
||
3. **图标映射**：Element UI → RemixIcon
|
||
4. **从 localStorage 读取认证信息**：作为服务端 session 的备用方案
|
||
|
||
### 优势
|
||
|
||
- ✅ 路由权限由后端统一管理
|
||
- ✅ 前端不需要查询多个表
|
||
- ✅ 支持动态菜单，后端修改后前端自动更新
|
||
- ✅ 更好的安全性和可维护性
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0
|
||
**最后更新**: 2025-11-17
|
||
**维护者**: DocReview 前端团队
|