# 3.9 权限节点配置

:::tip 概述
接口侧的权限码在 RouteSpec 声明，但"谁能访问"由菜单-角色链路决定：菜单表登记权限节点，角色勾选授权，authz 中间件按元数据校验。本页说明新模块的权限接入步骤。
:::

## 权限判定链路

```text
RouteSpec.Permission（如 sys:example:page）
        │  Bind 注册时落路由元数据表
        ▼
authz 中间件：解析当前用户 → 查角色授权的权限集合 → 命中即放行
        │
        ▼
菜单表 gin_menu.permission 登记节点 → 角色管理勾选 → gin_role_menu 关联
```

注意：**RouteSpec 声明是校验依据，菜单登记是授权入口**——两处的权限码字符串必须一致。只配 RouteSpec 不配菜单，任何人都无法获得该接口权限；只配菜单不配 RouteSpec，接口实际处于"登录即可"状态。

## 菜单表关键字段

```text
gin_menu
├── name        菜单名称
├── parent_id   上级ID（目录/菜单树）
├── path        前端路由路径
├── component   前端组件路径（views 下的相对路径）
├── permission  权限节点（sys:example:page）
├── type        菜单类型：0-菜单 1-节点
├── target      打开方式：0-组件 1-内链 2-外链
├── status      状态：0-正常 1-停用
└── sort        排序
```

`type=1` 的"节点"类型专门承载纯权限点（不显示为菜单项），页面按钮级权限通常配成节点挂在页面菜单下。

## 新模块权限配置步骤

1. **目录**：菜单管理下为新模块建一个目录（或复用现有目录，生成器默认挂 `generator.parentMenuId` 指定的父级）
2. **菜单**：建页面菜单，`path` 与前端路由一致，`component` 指向 `ui/src/views` 下页面
3. **节点**：按 RouteSpec 中每个权限码建 `type=1` 节点，`permission` 逐字一致
4. **授权**：角色管理勾选新节点，保存（写入 gin_role_menu）
5. **验证**：用受限角色登录，页面可见、按钮按 `v-permission` 显隐、直连接口 403/放行符合预期

## 按钮级权限（前端）

前端用 `v-perm`（包含其一）/ `v-perms`（包含全部）指令按权限码控制按钮：

```html
<!-- ui/src/views/tool/example/index.vue 实际用法（注意：入参必须是数组） -->
<el-button type="primary" @click="handleAdd" v-perm="['sys:example:add']">添加案例演示</el-button>
<el-button type="danger" @click="handleDelete()" v-perm="['sys:example:batchDelete']">批量删除</el-button>
```

超管权限集合含通配码 `*:*:*`，指令判定直通。用户菜单接口（`/api/index/getMenus`）返回的菜单树已按角色过滤，节点权限码一并下发供前端比对。详见 [9.7 权限控制](/zh/frontend/permission.html)。

## 代码生成器代劳

生成器会按 RouteSpec 幂等创建菜单行（含页面菜单与权限节点），配置 `generator.parentMenuId` 指定挂载位置——手工开发时可以参照生成器的菜单行结构照抄。

## 常见问题

| 现象 | 原因 |
|---|---|
| 接口 403 | 角色未授权该权限码，或菜单 permission 与 RouteSpec 拼写不一致 |
| 接口通但页面按钮不显示 | 前端 v-perm 的码与菜单节点不一致 |
| 不配权限码接口却能访问 | RouteSpec.Permission 留空 = 登录即可，按需补声明 |

## 下一步

→ [3.10 前端联调指引](/zh/guide/frontend-integration.html)