签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,68 @@
+# 6.2 角色管理
+
+:::tip 概述
+角色模块（goframe_role，租户级表）承载 RBAC 分配与数据权限四档：MenuList 返回带勾选状态的全量菜单树，SavePermission 全量重写角色菜单并清理身份缓存，data_scope 经字典驱动展示。
+:::
+
+## 接口清单
+
+| 方法 | 路由 | 权限 | 说明 |
+|------|------|------|------|
+| GET | /api/role/page | sys:role:page | 分页（含 dataScope + dataScopeText） |
+| GET | /api/role/list | sys:role:list | 列表 |
+| GET | /api/role/detail/:id | sys:role:detail | 详情 |
+| POST | /api/role/add | sys:role:add | 新增（data_scope 缺省归一 1） |
+| PUT | /api/role/update | sys:role:update | 修改 |
+| DELETE | /api/role/delete/:id | sys:role:delete | 软删（存在用户引用则拒绝） |
+| DELETE | /api/role/batchDelete | sys:role:batchDelete | 批量删除 |
+| GET | /api/role/menu/list/:roleId | sys:role:getPermission | 查询角色菜单（带勾选状态） |
+| POST | /api/role/menu/save | sys:role:savePermission | 保存权限（全量重写） |
+
+## 权限勾选（MenuList / SavePermission）
+
+```text
+MenuList（GET /api/role/menu/list/:roleId）：
+  返回全量菜单树（type 0/1 均含，供勾选界面展示目录+菜单+按钮三层），
+  每节点带 Checked = role_menu 是否含该 id（checkedSet 预构建）
+
+SavePermission（POST /api/role/menu/save）——语义为"全量重写"：
+  1) 先 Delete 该角色全部 role_menu（软删）
+  2) 逐个 Insert req.MenuIds
+  3) clearRoleIdentityCache(roleId)
+     缓存清理链：按 roleId 查受影响 user_id 列表 → 逐个 Del
+     easygoadmin:user:identity:{uid}
+```
+
+## data_scope 数据范围链路
+
+```text
+roleToData：Add/Update 均带 data_scope，入参 ≤0 归一为 1（全部），
+            gvalid in:1,2,3,4 校验
+roleSpec.SerializeMaps = {"data_scope": "role_data_scope"}
+  → 列表行 dataScopeText 由字典填充
+AfterUpdate（roleClearCache）：数据范围变更后失效该角色全部用户身份缓存
+  → 下一次请求 LoadIdentity 重取 min(data_scope) 即生效
+```
+
+四档语义与安全边界见 [5.9 数据权限](../core/data-scope)。
+
+## 删除守卫
+
+存在用户引用则拒绝删除（1014/1011 语义）——先给用户换角色，再删空角色。
+
+## 已知偏差（如实记录）
+
+::: warning 唯一预检范围偏差
+role 的 spec 唯一预检当前声明为 `UniqueFields{Field:"code"}`（未带 Group），而索引 `uk_tenant_code` 是"租户内唯一"——预检范围偏宽：超管为不同租户创建相同角色编码时会被误报"已存在"（数据库层不会冲突）。
+
+修复方向：补 `Group:"tenant_id"`，使预检范围等于索引范围。
+:::
+
+## 排障
+
+| 症状 | 原因 |
+|------|------|
+| 保存权限后用户仍 403 | 身份缓存未清（SavePermission 应触发清理链）；DEL `easygoadmin:user:identity:{uid}` |
+| 改 data_scope 不生效 | 同上——AfterUpdate 应清该角色全部用户缓存 |
+| 删除角色报"存在关联" | 有用户挂该角色，先在用户管理换角色 |
+| 不同租户建同名角色编码被拒 | 上述已知偏差（预检缺 Group） |