# 5.4 权限管理（RBAC）

:::tip 概述
经典三级模型：用户-角色-菜单（权限节点）。角色携带数据范围档位，多角色用户取最宽松。接口级校验在 Authz 中间件（元数据驱动），按钮级在前端 v-permission。
:::

## 模型

```text
gin_user ──< gin_user_role >── gin_role ──< gin_role_menu >── gin_menu
                                  │
                                  └── data_scope  数据范围档位（1 全部 / 2 本部门及以下 / 3 本部门 / 4 仅本人）
```

菜单 `type` 区分页面菜单（0）与纯权限节点（1）；`permission` 列承载权限码（`sys:user:add` 形态）。

## 身份装配（LoadIdentity）

登录后经 IdentityLoader 装配（结果缓存 300 秒）：

| 输出 | 内容 |
|---|---|
| 角色编码集合 | 用于超管判定等 |
| 权限节点集合 | Authz 比对依据 |
| 数据范围 | 多角色取最宽松档位 |
| deptID | DataScope 行级过滤用 |

重新授权后权限缓存最长 300 秒生效，**重新登录立即生效**。

## 接口级校验（Authz 中间件）

```text
免登录 → 放行
元数据未命中 / Permission 为空 → 登录即可，放行
超管角色 → 直通
权限节点集合命中 → 放行
否则 → 403 信封 + 拒绝原因（不产生操作日志，metrics 归类 denied）
```

边界：Authz 只管**功能权限**（能不能访问这个接口）；**数据权限**（能看哪些行）在 repository 层 applyFilters 链实现，两者不混。

## 按钮级（前端 v-perm / v-perms）

```html
<el-button v-perm="['sys:user:add']">新增</el-button>
<el-button v-perms="['sys:user:update', 'sys:user:delete']">操作</el-button>
```

菜单接口下发的权限集合驱动指令显隐，超管通配码 `*:*:*` 直通。注意：前端隐藏只是体验，安全边界始终在后端 Authz。

## 超管语义

- 租户ID=0（平台级）：不过滤租户数据，Authz 直通
- 普通管理员：授权多少权限码就能调多少接口

## 权限配置操作

1. 菜单管理：为模块/按钮建节点，填 permission 码
2. 角色管理：勾选节点保存（写 gin_role_menu）
3. 用户管理：分配角色

三处权限码必须与 RouteSpec 声明逐字一致（见 [3.9 权限节点配置](/zh/guide/permission.html)）。

## 数据范围档位

| 档位 | 行级条件 |
|---|---|
| 1 全部 | 租户隔离之内不过滤 |
| 2 本部门及以下 | dept_id IN（自身部门 + 全部子孙） |
| 3 本部门 | dept_id = 自身部门 |
| 4 仅本人 | id = 自身用户 ID |

详见 [5.10 数据权限](/zh/core/data-scope.html)。

## 下一步

→ [5.5 跨域配置（CORS）](/zh/core/cors.html)