yunzer_go/权限管理模块使用说明.md

# 权限管理模块使用说明

## 📋 功能概述

权限管理模块实现了基于角色的访问控制（RBAC），允许管理员为不同角色分配菜单和API访问权限。

## 🗄️ 数据库结构

### 1. 角色菜单关联表 `yz_role_menus`
```sql
CREATE TABLE yz_role_menus (
  id INT AUTO_INCREMENT PRIMARY KEY,
  role_id INT NOT NULL,           -- 角色ID
  menu_id INT NOT NULL,           -- 菜单ID（包括页面菜单和API接口）
  create_time DATETIME,
  create_by VARCHAR(50),
  UNIQUE KEY uk_role_menu (role_id, menu_id)
);
```

### 2. 菜单类型说明
- `menu_type = 1`: 页面菜单（显示在导航栏）
- `menu_type = 2`: API接口（用于权限控制）

## 🎯 核心功能

### 1. 权限分配
- 为角色分配菜单访问权限
- 为角色分配API访问权限
- 支持树形结构的权限选择
- 支持批量分配和取消

### 2. 权限验证
- 用户登录后自动加载权限
- 菜单根据权限动态显示
- API访问根据权限自动拦截

### 3. 权限查询
- 查询角色的所有权限
- 查询用户的所有权限
- 检查用户是否拥有特定权限

## 📡 API接口

### 1. 获取所有菜单权限列表
```
GET /api/permissions/menus
```
**响应示例：**
```json
{
  "success": true,
  "data": [
    {
      "menu_id": 1,
      "menu_name": "系统管理",
      "path": "/system",
      "menu_type": 1,
      "permission": null,
      "parent_id": 0
    }
  ]
}
```

### 2. 获取角色权限
```
GET /api/permissions/role/:roleId
```
**响应示例：**
```json
{
  "success": true,
  "data": {
    "role_id": 1,
    "role_name": "系统管理员",
    "menu_ids": [1, 2, 3, 4, 5],
    "permissions": ["user:list", "user:add", "file:upload"]
  }
}
```

### 3. 分配角色权限
```
POST /api/permissions/role/:roleId
Content-Type: application/json

{
  "menu_ids": [1, 2, 3, 4, 5]
}
```

### 4. 获取当前用户权限
```
GET /api/permissions/user
```

### 5. 获取用户菜单树
```
GET /api/permissions/user/menus
```

### 6. 检查权限
```
GET /api/permissions/check?permission=user:list
```

## 🎨 前端使用

### 页面访问
```
系统管理 -> 权限管理
```

### 权限分配流程
1. 在左侧选择要配置的角色
2. 在右侧权限树中勾选该角色应该拥有的菜单和API权限
3. 点击"保存权限设置"按钮
4. 系统会自动保存并刷新权限

### 权限树操作
- **全部展开**: 展开所有节点
- **全部折叠**: 折叠所有节点
- **全选**: 选中所有权限
- **取消全选**: 取消所有权限选择
- **搜索**: 支持按菜单名称、路径、权限标识搜索

### 权限类型标识
- 🔹 **页面**：蓝色标签，表示页面菜单
- 🟢 **API**：绿色标签，表示API接口
- ℹ️ **权限标识**：灰色标签，显示具体的权限代码

## 🔒 权限验证中间件（可选）

已创建权限验证中间件 `server/middleware/permission.go`，但默认未启用。

### 启用方法
在 `server/routers/router.go` 中添加：
```go
// 在JWT中间件之后添加权限验证中间件
beego.InsertFilter("/api/*", beego.BeforeExec, middleware.PermissionMiddleware())
```

### 注意事项
- 权限中间件会根据路径和方法自动匹配权限标识
- 如果用户没有对应权限，会返回 403 错误
- 公开接口（如登录、注册）会自动跳过权限验证

## 📊 权限标识规范

### 命名规范
格式：`模块:操作`

### 示例
- `user:list` - 查看用户列表
- `user:add` - 添加用户
- `user:edit` - 编辑用户
- `user:delete` - 删除用户
- `file:upload` - 上传文件
- `file:download` - 下载文件
- `role:create` - 创建角色
- `menu:update` - 更新菜单

## 🎯 使用场景

### 1. 为新角色分配权限
```
场景：公司新增了"财务专员"角色，需要分配相关权限
步骤：
1. 在角色管理中创建"财务专员"角色
2. 在权限管理中选择"财务专员"
3. 勾选需要的权限（如：文件管理、知识库查看）
4. 保存权限设置
```

### 2. 调整现有角色权限
```
场景：需要限制"普通用户"的某些功能
步骤：
1. 在权限管理中选择"普通用户"角色
2. 取消不需要的权限（如：用户管理、系统设置）
3. 保存权限设置
```

### 3. 权限审计
```
场景：查看某个角色有哪些权限
步骤：
1. 在权限管理中选择目标角色
2. 查看已勾选的权限项
3. 所有勾选项即为该角色拥有的权限
```

## 🔧 技术实现

### 后端
- **模型层**: `server/models/permission.go`
  - 角色权限关联
  - 权限查询和验证
  - 菜单树构建
  
- **控制器层**: `server/controllers/permission.go`
  - 权限分配接口
  - 权限查询接口
  
- **中间件层**: `server/middleware/permission.go`
  - API权限验证
  - 路径-权限映射

### 前端
- **API层**: `pc/src/api/permission.js`
  - 权限相关接口封装
  
- **页面层**: `pc/src/views/system/permissions/index.vue`
  - 角色列表展示
  - 权限树展示和操作
  - 权限保存

## 📝 注意事项

1. **权限继承**：子菜单会继承父菜单的权限，建议同时勾选父子节点
2. **API权限**：分配页面权限时，也要分配对应的API权限
3. **系统管理员**：role_id=1 的系统管理员已默认分配所有权限
4. **权限缓存**：修改权限后，用户需要重新登录才能生效（可以实现实时刷新）
5. **权限粒度**：当前实现到API级别，可以根据需要扩展到字段级别

## 🚀 后续优化建议

1. **权限缓存**: 使用Redis缓存用户权限，提高查询效率
2. **实时刷新**: WebSocket推送权限变更，无需重新登录
3. **权限日志**: 记录权限变更历史，便于审计
4. **数据权限**: 扩展到数据行级权限控制
5. **权限模板**: 预定义常用权限组合，快速分配

## ❓ 常见问题

### Q1: 修改权限后不生效？
A: 用户需要重新登录，因为权限信息存储在JWT中。可以实现权限实时刷新机制。

### Q2: 如何给新用户分配权限？
A: 在用户管理中为用户分配角色，然后在权限管理中为该角色分配权限。

### Q3: 权限标识是什么？
A: 权限标识是API接口的唯一识别码，格式为"模块:操作"，用于权限验证。

### Q4: 为什么看不到某些菜单？
A: 检查该角色是否被分配了对应的菜单权限，同时确保菜单状态为启用。

### Q5: API接口返回403错误？
A: 用户没有访问该接口的权限，需要在权限管理中为用户角色分配对应的API权限。

## 📞 技术支持

如有问题，请联系系统管理员或技术支持团队。