张翔
539 lines
16 KiB
Markdown
539 lines
16 KiB
Markdown
# 权限系统增强设计文档
|
||
|
||
**日期**: 2026-04-08
|
||
**作者**: 张翔
|
||
**版本**: 1.0
|
||
**状态**: 待审查
|
||
|
||
## 1. 概述
|
||
|
||
### 1.1 背景
|
||
|
||
当前系统已完成基础的路由权限控制，但存在以下优化空间：
|
||
|
||
1. **菜单硬编码** - 菜单在前端硬编码，无法根据用户角色动态显示
|
||
2. **权限数据分散** - 角色和权限信息存储在 localStorage，缺乏统一管理
|
||
3. **缺少按钮级权限控制** - 无法控制按钮级别的权限
|
||
4. **缺少 API 权限检查** - 前端调用 API 前未检查权限，可能发送无效请求
|
||
|
||
### 1.2 目标
|
||
|
||
实现完整的权限系统增强，包括：
|
||
|
||
1. **动态菜单渲染** - 从后端获取菜单数据，根据用户权限动态渲染
|
||
2. **权限缓存优化** - 使用 Pinia 统一管理权限数据，localStorage 持久化
|
||
3. **权限指令** - 提供 `v-permission` 指令实现按钮级权限控制
|
||
4. **API 权限检查** - 前端调用 API 前检查权限，减少无效请求
|
||
|
||
### 1.3 范围
|
||
|
||
**包含：**
|
||
- Permission Store (Pinia)
|
||
- v-permission 指令
|
||
- 动态菜单渲染
|
||
- API 权限检查工具
|
||
- 相关单元测试
|
||
|
||
**不包含：**
|
||
- 后端权限系统修改（仅需新增 API）
|
||
- 数据库权限表结构调整
|
||
- 其他业务功能开发
|
||
|
||
## 2. 架构设计
|
||
|
||
### 2.1 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 前端应用 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ 路由守卫 │ │ 权限指令 │ │ 动态菜单 │ │
|
||
│ │ (已完成) │ │ v-permission │ │ 渲染 │ │
|
||
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
|
||
│ │ │ │ │
|
||
│ └──────────────────┼──────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────▼────────┐ │
|
||
│ │ Permission │ │
|
||
│ │ Store (Pinia) │ │
|
||
│ └────────┬────────┘ │
|
||
│ │ │
|
||
│ ┌────────▼────────┐ │
|
||
│ │ localStorage │ │
|
||
│ │ (持久化) │ │
|
||
│ └─────────────────┘ │
|
||
│ │
|
||
└───────────────────────────┬─────────────────────────────────┘
|
||
│
|
||
HTTP API │
|
||
│
|
||
┌───────────────────────────▼─────────────────────────────────┐
|
||
│ 后端服务 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ /auth/login │ │ /menus/user │ │ /permissions │ │
|
||
│ │ (已存在) │ │ (新增) │ │ (已存在) │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ RBAC 权限系统 (角色-权限-菜单) │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 数据流
|
||
|
||
```
|
||
登录成功
|
||
↓
|
||
解析 JWT token 获取角色
|
||
↓
|
||
调用 fetchUserMenus() 获取菜单和权限
|
||
↓
|
||
存入 Store + localStorage
|
||
↓
|
||
页面刷新时从 localStorage 恢复
|
||
```
|
||
|
||
## 3. 详细设计
|
||
|
||
### 3.1 Permission Store
|
||
|
||
**文件位置**: `src/stores/permission.ts`
|
||
|
||
**状态定义**:
|
||
|
||
```typescript
|
||
interface PermissionState {
|
||
roles: string[] // 用户角色
|
||
permissions: string[] // 用户权限码
|
||
menus: MenuItem[] // 用户菜单
|
||
loaded: boolean // 是否已加载
|
||
}
|
||
|
||
interface MenuItem {
|
||
id: number
|
||
name: string
|
||
path: string
|
||
icon?: string
|
||
parentId?: number
|
||
sort: number
|
||
children?: MenuItem[]
|
||
}
|
||
```
|
||
|
||
**核心 Actions**:
|
||
|
||
```typescript
|
||
// 初始化权限数据（从 localStorage 恢复）
|
||
initFromStorage(): void
|
||
|
||
// 登录后设置权限数据
|
||
setPermissionData(data: {
|
||
roles: string[]
|
||
permissions: string[]
|
||
menus: MenuItem[]
|
||
}): void
|
||
|
||
// 从后端刷新权限数据
|
||
async fetchUserMenus(): Promise<void>
|
||
|
||
// 清除权限数据（退出登录）
|
||
clearPermissionData(): void
|
||
|
||
// 权限检查方法
|
||
hasRole(role: string | string[]): boolean
|
||
hasPermission(permission: string | string[]): boolean
|
||
```
|
||
|
||
**持久化策略**:
|
||
|
||
- 登录时：将角色、权限、菜单数据存入 localStorage
|
||
- 页面刷新：Pinia 从 localStorage 恢复数据，立即渲染菜单
|
||
- 权限变更：提供刷新机制，同步更新 localStorage 和 Pinia
|
||
- 退出登录：清除所有数据
|
||
|
||
### 3.2 v-permission 指令
|
||
|
||
**文件位置**: `src/directives/permission.ts`
|
||
|
||
**用法**:
|
||
|
||
```vue
|
||
<!-- 角色检查 -->
|
||
<button v-permission:role="'admin'">管理员按钮</button>
|
||
|
||
<!-- 权限码检查 -->
|
||
<button v-permission:permission="'user:delete'">删除用户</button>
|
||
|
||
<!-- 支持数组（满足任一条件） -->
|
||
<button v-permission:role="['admin', 'manager']">导出数据</button>
|
||
<button v-permission:permission="['user:create', 'user:update']">编辑用户</button>
|
||
|
||
<!-- 简写形式（默认权限检查） -->
|
||
<button v-permission="'user:delete'">删除</button>
|
||
```
|
||
|
||
**实现逻辑**:
|
||
|
||
```typescript
|
||
export const permissionDirective = {
|
||
mounted(el: HTMLElement, binding: DirectiveBinding) {
|
||
const permissionStore = usePermissionStore()
|
||
|
||
const { arg, value } = binding
|
||
const checkType = arg || 'permission' // 默认权限检查
|
||
|
||
let hasAccess = false
|
||
|
||
if (checkType === 'role') {
|
||
hasAccess = permissionStore.hasRole(value)
|
||
} else if (checkType === 'permission') {
|
||
hasAccess = permissionStore.hasPermission(value)
|
||
}
|
||
|
||
if (!hasAccess) {
|
||
el.style.display = 'none'
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**注册方式**:
|
||
|
||
```typescript
|
||
// src/main.ts
|
||
import { permissionDirective } from '@/directives/permission'
|
||
|
||
app.directive('permission', permissionDirective)
|
||
```
|
||
|
||
### 3.3 动态菜单渲染
|
||
|
||
**后端 API**:
|
||
|
||
```
|
||
GET /api/menus/user
|
||
|
||
请求头：
|
||
Authorization: Bearer <token>
|
||
|
||
响应：
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"menus": [
|
||
{
|
||
"id": 1,
|
||
"name": "仪表盘",
|
||
"path": "/dashboard",
|
||
"icon": "Odometer",
|
||
"parentId": null,
|
||
"sort": 1
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "系统管理",
|
||
"path": "/system",
|
||
"icon": "Setting",
|
||
"parentId": null,
|
||
"sort": 2,
|
||
"children": [
|
||
{
|
||
"id": 3,
|
||
"name": "用户管理",
|
||
"path": "/users",
|
||
"icon": null,
|
||
"parentId": 2,
|
||
"sort": 1
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"permissions": [
|
||
"user:read",
|
||
"user:create",
|
||
"user:update",
|
||
"user:delete"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**前端组件**:
|
||
|
||
```vue
|
||
<!-- src/layouts/DefaultLayout.vue -->
|
||
<template>
|
||
<el-menu
|
||
:default-active="activeMenu"
|
||
class="menu"
|
||
:collapse="collapsed"
|
||
router
|
||
>
|
||
<menu-item
|
||
v-for="menu in menuTree"
|
||
:key="menu.id"
|
||
:menu="menu"
|
||
/>
|
||
</el-menu>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { computed } from 'vue'
|
||
import { usePermissionStore } from '@/stores/permission'
|
||
import MenuItem from '@/components/MenuItem.vue'
|
||
|
||
const permissionStore = usePermissionStore()
|
||
const menuTree = computed(() => permissionStore.menus)
|
||
</script>
|
||
```
|
||
|
||
**递归菜单组件**:
|
||
|
||
```vue
|
||
<!-- src/components/MenuItem.vue -->
|
||
<template>
|
||
<!-- 有子菜单 -->
|
||
<el-sub-menu
|
||
v-if="menu.children && menu.children.length > 0"
|
||
:index="String(menu.id)"
|
||
>
|
||
<template #title>
|
||
<el-icon v-if="menu.icon">
|
||
<component :is="menu.icon" />
|
||
</el-icon>
|
||
<span>{{ menu.name }}</span>
|
||
</template>
|
||
<menu-item
|
||
v-for="child in menu.children"
|
||
:key="child.id"
|
||
:menu="child"
|
||
/>
|
||
</el-sub-menu>
|
||
|
||
<!-- 无子菜单 -->
|
||
<el-menu-item
|
||
v-else
|
||
:index="menu.path"
|
||
>
|
||
<el-icon v-if="menu.icon">
|
||
<component :is="menu.icon" />
|
||
</el-icon>
|
||
<span>{{ menu.name }}</span>
|
||
</el-menu-item>
|
||
</template>
|
||
```
|
||
|
||
### 3.4 API 权限检查
|
||
|
||
**文件位置**: `src/utils/permission-check.ts`
|
||
|
||
**权限映射配置**:
|
||
|
||
```typescript
|
||
const apiPermissionMap: Record<string, { permission: string; method: string }> = {
|
||
'/api/users:GET': { permission: 'user:read', method: 'GET' },
|
||
'/api/users:POST': { permission: 'user:create', method: 'POST' },
|
||
'/api/users/*:PUT': { permission: 'user:update', method: 'PUT' },
|
||
'/api/users/*:DELETE': { permission: 'user:delete', method: 'DELETE' },
|
||
'/api/roles:GET': { permission: 'role:read', method: 'GET' },
|
||
// ... 更多映射
|
||
}
|
||
```
|
||
|
||
**检查函数**:
|
||
|
||
```typescript
|
||
export function canAccessApi(path: string, method: string): boolean {
|
||
const permissionStore = usePermissionStore()
|
||
|
||
const required = findRequiredPermission(path, method, apiPermissionMap)
|
||
|
||
if (!required) {
|
||
return true // 未定义权限要求的 API 默认允许
|
||
}
|
||
|
||
return permissionStore.hasPermission(required.permission)
|
||
}
|
||
```
|
||
|
||
**集成到请求拦截器**:
|
||
|
||
```typescript
|
||
// src/utils/request.ts
|
||
import { canAccessApi } from './permission-check'
|
||
|
||
request.interceptors.request.use(
|
||
(config) => {
|
||
// 权限检查
|
||
const path = config.url || ''
|
||
const method = config.method?.toUpperCase() || 'GET'
|
||
|
||
if (!canAccessApi(path, method)) {
|
||
return Promise.reject(new Error('无权限访问此 API'))
|
||
}
|
||
|
||
// 原有的 token 和签名逻辑
|
||
// ...
|
||
|
||
return config
|
||
}
|
||
)
|
||
```
|
||
|
||
## 4. 测试策略
|
||
|
||
### 4.1 测试覆盖范围
|
||
|
||
1. **Permission Store 单元测试**
|
||
- 测试权限数据的存储和恢复
|
||
- 测试 hasRole 和 hasPermission 方法
|
||
- 测试 localStorage 持久化
|
||
- 测试数据清除功能
|
||
|
||
2. **v-permission 指令测试**
|
||
- 测试角色检查功能
|
||
- 测试权限码检查功能
|
||
- 测试数组参数处理
|
||
- 测试元素隐藏/显示逻辑
|
||
|
||
3. **动态菜单测试**
|
||
- 测试菜单数据获取
|
||
- 测试菜单树渲染
|
||
- 测试菜单缓存机制
|
||
- 测试菜单权限过滤
|
||
|
||
4. **API 权限检查测试**
|
||
- 测试权限映射匹配
|
||
- 测试通配符匹配
|
||
- 测试请求拦截逻辑
|
||
|
||
### 4.2 测试文件结构
|
||
|
||
```
|
||
src/
|
||
├── stores/
|
||
│ └── __tests__/
|
||
│ └── permission.test.ts
|
||
├── directives/
|
||
│ └── __tests__/
|
||
│ └── permission.test.ts
|
||
├── components/
|
||
│ └── __tests__/
|
||
│ └── MenuItem.test.ts
|
||
└── utils/
|
||
└── __tests__/
|
||
└── permission-check.test.ts
|
||
```
|
||
|
||
## 5. 实施计划
|
||
|
||
### 5.1 实施顺序
|
||
|
||
**第 1 步：Permission Store（1-2 小时）**
|
||
- 创建 `src/stores/permission.ts`
|
||
- 实现 localStorage 持久化
|
||
- 编写单元测试
|
||
- 集成到登录流程
|
||
|
||
**第 2 步：v-permission 指令（1-2 小时）**
|
||
- 创建 `src/directives/permission.ts`
|
||
- 注册全局指令
|
||
- 编写单元测试
|
||
- 在现有页面应用示例
|
||
|
||
**第 3 步：后端 API 开发（2-3 小时）**
|
||
- 新增 `GET /api/menus/user` 接口
|
||
- 根据用户角色返回菜单树
|
||
- 返回用户权限列表
|
||
- 编写后端测试
|
||
|
||
**第 4 步：动态菜单渲染（2-3 小时）**
|
||
- 创建 `src/components/MenuItem.vue`
|
||
- 修改 `DefaultLayout.vue`
|
||
- 集成 Permission Store
|
||
- 编写组件测试
|
||
|
||
**第 5 步：API 权限检查（1-2 小时）**
|
||
- 创建 `src/utils/permission-check.ts`
|
||
- 集成到请求拦截器
|
||
- 编写单元测试
|
||
- 优化性能
|
||
|
||
### 5.2 后端 API 需求
|
||
|
||
**接口**: `GET /api/menus/user`
|
||
|
||
**功能**: 获取当前登录用户可访问的菜单和权限
|
||
|
||
**业务逻辑**:
|
||
1. 从 token 获取用户 ID
|
||
2. 查询用户角色
|
||
3. 根据角色查询菜单和权限
|
||
4. 构建菜单树结构
|
||
5. 返回菜单和权限列表
|
||
|
||
**预估时间**: 7-12 小时
|
||
|
||
## 6. 风险和约束
|
||
|
||
### 6.1 技术风险
|
||
|
||
1. **后端 API 开发时间** - 需要后端配合开发新 API
|
||
2. **菜单数据迁移** - 需要将硬编码菜单迁移到数据库
|
||
3. **权限数据同步** - 前后端权限数据需要保持一致
|
||
|
||
### 6.2 约束条件
|
||
|
||
1. **向后兼容** - 需要兼容现有的路由守卫逻辑
|
||
2. **性能要求** - 菜单加载不能影响页面首屏渲染速度
|
||
3. **测试覆盖** - 所有新增代码需要单元测试覆盖
|
||
|
||
## 7. 验收标准
|
||
|
||
### 7.1 功能验收
|
||
|
||
- [ ] Permission Store 正确管理权限数据
|
||
- [ ] v-permission 指令正确控制按钮显示
|
||
- [ ] 动态菜单根据用户权限正确渲染
|
||
- [ ] API 权限检查正确拦截无权限请求
|
||
|
||
### 7.2 质量验收
|
||
|
||
- [ ] 所有单元测试通过
|
||
- [ ] 代码覆盖率 ≥ 80%
|
||
- [ ] TypeScript 类型检查通过
|
||
- [ ] ESLint 检查通过
|
||
|
||
### 7.3 性能验收
|
||
|
||
- [ ] 菜单加载时间 < 500ms
|
||
- [ ] localStorage 读写不影响页面性能
|
||
- [ ] 权限检查不影响 API 请求速度
|
||
|
||
## 8. 后续优化
|
||
|
||
### 8.1 短期优化
|
||
|
||
1. **权限缓存过期** - 添加权限数据过期机制
|
||
2. **权限变更通知** - 实现权限变更后的实时通知
|
||
3. **权限日志** - 记录权限检查日志，便于调试
|
||
|
||
### 8.2 长期优化
|
||
|
||
1. **权限可视化配置** - 提供权限配置界面
|
||
2. **权限审计** - 记录用户权限变更历史
|
||
3. **权限模板** - 提供常用权限模板，简化配置
|
||
|
||
## 9. 参考资料
|
||
|
||
- [Vue 3 官方文档](https://vuejs.org/)
|
||
- [Pinia 官方文档](https://pinia.vuejs.org/)
|
||
- [Element Plus 文档](https://element-plus.org/)
|
||
- [RBAC 权限模型](https://en.wikipedia.org/wiki/Role-based_access_control)
|