3.8 权限节点配置

概述

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

权限码规范

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）：

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

权限判定链路

请求 → 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 副作用自动完成（幂等）：

主菜单：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
名称	查询分页记录
状态	正常

角色勾选（生效前提）

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

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

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

开发自检清单

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