NestBase

Appearance

权限管理系统 (RBAC) 使用手册 ​

本手册将指导您如何使用 NestBase 的权限管理系统，包括用户管理、角色管理、菜单分配与按钮权限控制。

1. 概念说明 ​

本系统采用标准的 RBAC (Role-Based Access Control) 模型，并结合菜单分离设计：

  • 用户 (User): 系统的登录账号。一个用户可以拥有多个角色。
  • 角色 (Role): 权限的集合载体（如：管理员、编辑、访客）。
  • 菜单 (Menu): 左侧导航栏的页面结构。可以控制角色是否可见某些菜单。
  • 权限 (Permission): 具体的操作许可，分为三类：
    • MENU: 页面访问权限（通常与菜单可见性强关联）。
    • BUTTON: 页面内的按钮操作权限（如：新增、删除）。
    • API: 后端接口调用权限。

2. 操作流程 ​

通常的配置流程如下：

  1. 创建菜单: 定义系统有哪些页面。
  2. 定义权限: 为该页面下的功能（按钮/API）定义具体的权限点。
  3. 创建角色: 建立职能角色（如“财务”、“运营”）。
  4. 授权:
    • 分配菜单: 决定该角色能看到哪些导航菜单。
    • 分配权限: 决定该角色能进行哪些具体操作。
  5. 分配角色: 将角色赋予具体的用户。

3. 功能指南 ​

3.1 菜单管理 ​

路径：/manage/menu

  1. 新建菜单:
    • 菜单名称: 显示在侧边栏的标题。
    • 路由名称 (RouteName): 必须唯一，对应前端路由定义（如 user_manage）。
    • 路径 (Path): 浏览器访问路径（如 /manage/user）。
    • 组件 (Component): 前端组件路径（如 layout.base 或 view.manage_user）。
  2. 隐藏/显示: 可设置菜单是否在侧边栏显示（如详情页通常隐藏但路由存在）。

3.2 权限管理 ​

路径：/manage/role (通常在角色授权弹窗中操作，或通过 API 预置)

系统支持细粒度权限控制。示例：

权限名称权限编码 (Code)类型说明
用户管理页user:viewMENU是否能进入页面
新增用户user:createBUTTON是否显示“新增”按钮
删除用户user:deleteBUTTON是否显示“删除”按钮

提示: 按钮权限 (BUTTON) 必须关联一个父级菜单 (MenuId)，以便在授权界面按菜单分组展示。

3.3 角色管理与授权 ​

路径：/manage/role

  1. 新建角色: 设置角色名称和编码（如 admin, editor）。
  2. 菜单授权 (分配可见性):
    • 点击角色的 "菜单权限" 按钮（如有）。
    • 勾选该角色可见的菜单树。
    • 效果: 用户登录后，左侧菜单栏仅显示被勾选的项。
  3. 功能授权 (分配操作权):
    • 点击角色的 "操作权限" 按钮。
    • 勾选具体的权限点（如 新增用户、导出报表）。
    • 效果: 前端根据权限显示/隐藏按钮，后端拦截无权请求。

3.4 用户管理 ​

路径：/manage/user

  1. 新建用户: 创建账号。
  2. 分配角色:
    • 编辑用户，在 "角色" 选项中勾选一个或多个角色。
    • 用户权限 = 所有拥有角色的权限之和（并集）。

4. 前端按钮权限使用 ​

在前端开发中，若需根据权限控制按钮显示，请使用 v-permission 指令或 hasPermission 函数。

方式 A: 指令 (推荐) ​

vue
<!-- 仅拥有 'user:create' 权限的用户可见 -->
<NButton v-permission="'user:create'">新增用户</NButton>

<!-- 拥有 'user:edit' 或 'user:delete' 任一权限可见 -->
<div v-permission="['user:edit', 'user:delete']">
  操作区域
</div>

方式 B: 函数调用 ​

typescript
import { useAuthStore } from '@/store/modules/auth';

const authStore = useAuthStore();

if (authStore.hasPermission('content:article:import')) {
  // 执行逻辑
}

5. 常见问题 ​

Q: 为什么我有菜单权限，但进页面提示 403？ A: 请检查是否缺少对应的路由守卫验证权限（如 MENU 类型的权限点）。或者后端接口是否被 @RequirePermissions 拦截。

Q: 新增了权限，为什么不生效？ A: 权限变更通常需要用户重新登录或刷新页面（重新拉取权限配置）才能生效。

Q: 超级管理员需要配置权限吗？ A: 系统内置的 SUPER_ADMIN (admin) 通常拥有所有权限（跳过权限检查），具体取决于后端配置。但在界面展示上，建议仍为其分配完整菜单以保证导航显示正常。