feat(role): enhance role hierarchy with parent-child relationships and effective permissions

Author: zds-s

.gitattributes

@@ -1,4 +1,5 @@
 /.github export-ignore
 /.tmp export-ignore
 SECURITY.md export-ignore
-CONTRIBUTING.md export-ignore
+CONTRIBUTING.md export-ignore
+README*.md export-ignore

.gitignore

@@ -21,4 +21,7 @@ public
 !web/public
 *.lock
 storage/swagger/http.json
-storage/uploads
+storage/uploads
+.bmad-core
+.claude
+CLAUDE.md

ROLE_HIERARCHY_README.md

@@ -0,0 +1,225 @@
+# 角色层级与权限继承系统
+
+## 概述
+
+MineAdmin 已升级支持角色层级结构和权限继承，允许子角色自动继承父角色的所有权限。
+
+## 核心特性
+
+### 1. 角色层级结构
+- **单继承模式**：每个角色最多只能有一个父角色
+- **最大深度**：支持5级层级（0-4级）
+- **循环检测**：自动防止循环引用
+
+### 2. 权限继承机制
+- **累积继承**：子角色拥有自己的权限 + 所有祖先角色的权限
+- **向上查找**：从当前角色开始，依次向上检查祖先角色权限
+- **SuperAdmin特殊处理**：超级管理员角色自动拥有所有权限
+
+### 3. 多角色用户
+- **灵活组合**：用户可以拥有多个角色
+- **权限合并**：用户的最终权限 = 所有角色的有效权限合并
+
+## 数据库结构
+
+### 新增字段
+```sql
+ALTER TABLE role ADD COLUMN parent_id BIGINT NULL COMMENT '父角色ID';
+ALTER TABLE role ADD COLUMN level TINYINT DEFAULT 0 COMMENT '层级深度';
+```
+
+### 层级示例
+```
+SuperAdmin (level=0)
+└── DeptManager (level=1)
+    └── Employee (level=2)
+        └── Intern (level=3)
+```
+
+## API 使用示例
+
+### Role 模型新增方法
+
+```php
+use App\Model\Permission\Role;
+
+$role = Role::find(1);
+
+// 获取父角色
+$parent = $role->parent;
+
+// 获取子角色
+$children = $role->children;
+
+// 获取所有祖先角色
+$ancestors = $role->getAncestors();
+
+// 获取所有后代角色  
+$descendants = $role->getDescendants();
+
+// 获取有效权限（含继承）
+$permissions = $role->getEffectivePermissions();
+
+// 检查层级关系
+$isAncestor = $role->isAncestorOf($otherRole);
+$isDescendant = $role->isDescendantOf($otherRole);
+
+// 检查循环引用
+$wouldCycle = $role->wouldCreateCycle($potentialParent);
+```
+
+### User 模型权限检查
+
+```php
+use App\Model\Permission\User;
+
+$user = User::find(1);
+
+// 检查权限（含继承）
+$hasPermission = $user->hasPermission('user.manage');
+
+// 获取所有权限（含继承）
+$permissions = $user->getPermissions();
+```
+
+### RoleHierarchyService 服务
+
+```php
+use App\Service\Permission\RoleHierarchyService;
+
+$service = new RoleHierarchyService();
+
+// 设置父角色
+$service->setParent($childRole, $parentRole);
+
+// 移动角色
+$service->moveRole($role, $newParent);
+
+// 获取角色树
+$tree = $service->getRoleTree();
+
+// 获取角色路径
+$path = $service->getRolePath($role); // 输出: "SuperAdmin > DeptManager > Employee"
+
+// 重建层级结构
+$service->rebuildHierarchy();
+
+// 删除角色
+$service->deleteRoleWithChildren($role, $moveChildrenUp = true);
+
+// 获取可选父角色
+$availableParents = $service->getAvailableParents($role);
+```
+
+## 权限继承示例
+
+### 场景1：基本继承
+```
+SuperAdmin: [system.admin, user.manage, role.manage]
+├── DeptManager: [dept.manage] 
+    └── Employee: [profile.edit]
+```
+
+权限分布：
+- SuperAdmin: [system.admin, user.manage, role.manage]
+- DeptManager: [system.admin, user.manage, role.manage, dept.manage]
+- Employee: [system.admin, user.manage, role.manage, dept.manage, profile.edit]
+
+### 场景2：多角色用户
+```
+用户A拥有角色: [Employee, ProjectLead]
+最终权限 = Employee的有效权限 + ProjectLead的有效权限
+```
+
+## 最佳实践
+
+### 1. 角色设计
+- **按职能层级设计**：SuperAdmin → Manager → Employee → Intern
+- **避免过深层级**：建议不超过4级
+- **明确权限边界**：父角色权限应该包含子角色需要的基础权限
+
+### 2. 权限分配
+- **最小权限原则**：只给必要的权限
+- **继承优先**：优先通过继承获取权限，减少直接分配
+- **定期审查**：定期检查权限是否合理
+
+### 3. 性能优化
+- **缓存权限**：为频繁查询的用户缓存权限列表
+- **控制层级深度**：避免过深的递归查询
+- **索引优化**：为parent_id和level字段建立索引
+
+## 迁移指南
+
+### 1. 运行迁移
+```bash
+php bin/hyperf.php migrate
+```
+
+### 2. 设置现有角色层级
+```php
+// 设置现有角色的父级关系
+$superAdmin = Role::where('code', 'SuperAdmin')->first();
+$manager = Role::where('code', 'Manager')->first();
+$employee = Role::where('code', 'Employee')->first();
+
+$hierarchyService = new RoleHierarchyService();
+$hierarchyService->setParent($manager, $superAdmin);
+$hierarchyService->setParent($employee, $manager);
+```
+
+### 3. 验证权限继承
+```php
+// 测试权限继承是否正常工作
+$user = User::find(1);
+$hasPermission = $user->hasPermission('system.admin');
+```
+
+## 兼容性说明
+
+### 向后兼容
+- ✅ 现有的权限检查逻辑完全兼容
+- ✅ 现有的用户-角色关联不受影响
+- ✅ API接口保持不变
+
+### 新增功能
+- 🆕 角色层级管理
+- 🆕 权限继承机制
+- 🆕 循环引用检测
+- 🆕 层级路径显示
+
+## 故障排除
+
+### 常见问题
+
+1. **权限继承不生效**
+   - 检查角色的parent_id是否正确设置
+   - 检查level字段是否正确计算
+   - 使用`rebuildHierarchy()`重建层级结构
+
+2. **循环引用错误**
+   - 使用`wouldCreateCycle()`检查是否会产生循环
+   - 检查数据的完整性
+
+3. **性能问题**
+   - 为parent_id字段添加索引
+   - 启用权限缓存机制
+   - 控制角色层级深度
+
+### 调试工具
+
+```php
+// 打印角色层级树
+$tree = app(RoleHierarchyService::class)->getRoleTree();
+print_r($tree->toArray());
+
+// 检查用户的完整权限
+$user = User::find(1);
+$permissions = $user->getPermissions();
+foreach ($permissions as $permission) {
+    echo $permission->name . "\n";
+}
+```
+
+## 总结
+
+角色层级与权限继承系统为MineAdmin提供了更灵活和强大的权限管理能力，同时保持了向后兼容性。通过简单的单继承树形结构，实现了复杂权限场景的简洁管理。