# 3.8 权限节点配置

:::tip 概述
本项目权限校验的声明在接口 gmeta 标签，落地在菜单表的权限节点（menu.type=1）。新增模块后需要确保：权限码规范正确 → 节点存在 → 角色已勾选。超管（ROLE_SUPER_ADMIN）绕过全部校验。
:::

## 权限码规范

```text
sys:{模块小驼峰}:{动作}

动作与方法名一致：page / list / detail / add / update / delete / batchDelete
                / status / import / export / resetPwd / execute / pause / resume
                / savePermission / getPermission / cache / users / save …

特例：配置网站 sys:configWeb:data|save
      生成器   sys:generator:generator|batchGenerator
      上传     sys:upload:file|files
```

example 模块的权限码（gmeta 声明，摘自 api/v1/example.go）：

```go
permission:"sys:example:page"      // Page
permission:"sys:example:list"      // List
permission:"sys:example:detail"    // Detail
permission:"sys:example:add"       // Add
permission:"sys:example:update"    // Update
permission:"sys:example:status"    // Status
permission:"sys:example:delete"    // Delete
permission:"sys:example:batchDelete"  // BatchDelete
permission:"sys:example:import"    // Import
permission:"sys:example:export"    // Export
```

## 权限判定链路

```text
请求 → Bind 包装层 → consts.HasPerm(ctx, "sys:example:page")
  ├─ permission 标签为空        → 通过（仅登录即可）
  ├─ Roles 含 ROLE_SUPER_ADMIN  → 通过（超管全放行）
  ├─ Perms 精确匹配             → 通过
  └─ 否则                       → code=403 信封
```

Perms 来自身份缓存（`easygoadmin:user:identity:{uid}`，TTL 300s）：user → user_role → role_menu → menu 中 `type=1 且 status=0 且 hide=0` 的 permission 非空去重集合。

## 节点创建（两条途径）

### 途径一：代码生成器自动创建（推荐）

生成器 `createMenu` 副作用自动完成（幂等）：

```text
主菜单：parent_id = generator.parentMenuId（默认 189）
        path = /{domain}/{moduleCamel}，type=0，按 path 查重已存在则跳过
权限节点（type=1，挂主菜单下）：
        固定 7 个：page/list/detail/add/update/delete/batchDelete
        HasStatus 追加 :status；HasImport/HasExport 追加 :import/:export
```

### 途径二：菜单管理页面手工创建

「系统管理 → 菜单管理」新增：

| 字段 | 值（example 为例） |
|------|------------------|
| 上级菜单 | 选择模块主菜单 |
| 菜单类型 | 权限节点 |
| 权限标识 | sys:example:page |
| 名称 | 查询分页记录 |
| 状态 | 正常 |

## 角色勾选（生效前提）

节点创建后，**必须在「系统管理 → 角色管理 → 权限」为角色勾选**，保存走：

```text
POST /api/role/menu/save   （sys:role:savePermission）
  → 重写 role_menu 关联
  → 清理该角色全部用户的身份缓存（user:identity:{uid}）
```

超管不需要勾选（通配放行）；前端识别 getUser 返回的 `*:*:*` 通配权限放开全部按钮。

## 开发自检清单

+ [ ] gmeta `permission` 标签已按 `sys:{module小驼峰}:{action}` 声明
+ [ ] 权限节点已在菜单存在（生成器自动 / 手工创建）
+ [ ] 测试角色已勾选新节点并重新登录（或等 300s 缓存过期）
+ [ ] 前端按钮用权限指令控制（见 [9.7 权限控制](../frontend/permission)）
+ [ ] 免登录接口的 `public:"true"` 与 `middleware/public.go` 白名单一致