签入版本

2026-10-25 17:24:27 +08:00
parent 48911cc08f
commit fdbeae092a
1010 changed files with 30682 additions and 95274 deletions
@@ -1,76 +1,72 @@
-# 3.8 权限节点配置
+# 3.9 权限节点配置

 :::tip 概述
-权限节点用于控制用户能访问哪些接口。通过菜单管理界面配置，格式为 `sys:{模块名}:{操作}`。
+接口侧的权限码在 RouteSpec 声明，但"谁能访问"由菜单-角色链路决定：菜单表登记权限节点，角色勾选授权，authz 中间件按元数据校验。本页说明新模块的权限接入步骤。
 :::

-## Example 模块权限码
-
-| 权限码 | 说明 | 对应接口 |
-|--------|------|----------|
-| `sys:example:page` | 案例演示分页列表 | `GET /api/example/page` |
-| `sys:example:add` | 添加案例演示 | `POST /api/example/add` |
-| `sys:example:update` | 修改案例演示 | `PUT /api/example/update` |
-| `sys:example:delete` | 删除案例演示 | `DELETE /api/example/delete/:id` |
-| `sys:example:import` | 导入案例演示 | `POST /api/example/import` |
-| `sys:example:export` | 导出案例演示 | `GET /api/example/export` |
-
-## 配置步骤
-
-### 1. 添加目录节点
-
-在系统菜单管理中添加一级目录：
-
-| 字段 | 值 |
-|------|-----|
-| 菜单名称 | 工具管理 |
-| 菜单类型 | 目录（type=0） |
-| 路由地址 | /tool |
-| 排序 | 60 |
-
-### 2. 添加菜单节点
-
-在目录下添加二级菜单：
-
-| 字段 | 值 |
-|------|-----|
-| 菜单名称 | 案例演示 |
-| 菜单类型 | 菜单（type=1） |
-| 路由地址 | /example |
-| 组件路径 | tool/example/index |
-| 权限标识 | sys:example:page |
-| 排序 | 1 |
-
-### 3. 添加按钮权限
-
-在菜单下添加三级按钮权限：
-
-| 字段 | 值 | 权限标识 |
-|------|-----|----------|
-| 添加案例演示 | type=2 | sys:example:add |
-| 修改案例演示 | type=2 | sys:example:update |
-| 删除案例演示 | type=2 | sys:example:delete |
-| 导入案例演示 | type=2 | sys:example:import |
-| 导出案例演示 | type=2 | sys:example:export |
-
-### 4. 分配角色权限
-
-在角色管理中，为角色勾选新增的权限节点。
-
-## 菜单类型说明
-
-| type | 说明 | 前端行为 |
-|------|------|----------|
-| 0 | 目录 | 渲染为侧边栏分组 |
-| 1 | 菜单 | 渲染为可点击的菜单项，对应一个页面 |
-| 2 | 按钮 | 不渲染，仅用于权限校验 |
-
-## 权限校验流程
+## 权限判定链路

 ```text
-1. 用户登录 → 获取用户角色
-2. 角色关联菜单 → 获取权限节点列表
-3. 请求接口 → AuthMiddleware 读取 #[Permission] 注解
-4. 检查权限码是否在用户权限列表中
-5. 超级管理员（uid=1）跳过校验，直接放行
-```
+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)