# 权限系统增强设计文档

**日期**: 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)