# Kylin RBAC

Kylin 基于 Role-Permission 的权限管理包，Fork 自 spatie/laravel-permission，符合等保 2.0 (GB/T 22239) 要求。

## 功能特性

- **角色管理**：创建、编辑、删除角色，支持角色继承
- **权限管理**：细粒度权限定义与分配，支持权限分组
- **用户-角色关联**：多对多关系（morphToMany），一个用户可拥有多个角色
- **角色-权限关联**：多对多关系，一个角色可拥有多个权限
- **Gate / Policy 集成**：`RbacServiceProvider::registerRbacGates()` 自动注册所有权限
- **BasePolicy / CrudPolicy**：业务 Policy 继承 `CrudPolicy` 即可拥有标准 CRUD 权限
- **缓存优化**：权限检查结果自动缓存（`cache.enabled`、`cache.ttl`）
- **预置角色**：超级管理员、管理员、编辑、查看者
- **审计日志**：`HasRoles` trait 自动记录权限变更审计日志
- **权限变更通知**：`PermissionChangeNotifier` 敏感角色/权限变更自动通知
- **权限定期审查**：`PermissionReviewCommand` 命令审查冗余/异常权限
- **最小权限原则**：`least_privilege` 配置 + `BasePolicy::isSuperAdmin()`

## 安装

```bash
composer require kylin/rbac
```

## 初始化

```bash
php artisan kylin:rbac-install
```

此命令将：
1. 运行数据库迁移
2. 创建预置角色（超级管理员、管理员、编辑、查看者）

## 使用示例

### 分配角色

```php
$user->assignRole('超级管理员');
```

### 检查权限

```php
// Blade 模板
@can('edit articles')
    <a href="#">编辑文章</a>
@endcan

// 代码中
$user->can('edit articles');
$user->hasRole('管理员');
```

### Facade

```php
use Kylin\Rbac\Facades\KylinRbac;

// 创建角色
KylinRbac::createRole('运营', '运营人员', 'web', '负责日常运营');
KylinRbac::createPermission('article.publish', '发布文章', 'article');

// 同步角色权限
$role = Role::findByName('运营');
KylinRbac::syncRolePermissions($role, ['article.publish', 'article.edit']);

// 获取角色权限（带缓存）
$permissions = KylinRbac::getRolePermissions('运营');
```

### 中间件

```php
Route::middleware('kylin.role:管理员')->group(function () {
    // 仅管理员可访问
});

Route::middleware('kylin.permission:edit articles')->group(function () {
    // 需要 edit articles 权限
});
```

### Policy 继承

```php
use Kylin\Rbac\Policies\CrudPolicy;

class ArticlePolicy extends CrudPolicy
{
    protected string $resource = 'article';
    // 自动实现 viewAny/view/create/update/delete/restore/forceDelete
}
```

### 权限变更通知（自动触发）

`assignRole/removeRole/givePermissionTo/revokePermissionTo` 会自动触发 `PermissionChangeNotifier`：

- 敏感角色变更（super_admin/admin/auditor）→ 通知所有管理员
- 敏感权限变更（admin.access/user.delete/rbac.manage 等）→ 通知所有管理员
- 通知渠道：系统日志 + 数据库通知（如已集成 `kylin/notification`）

### 权限定期审查命令

```bash
# 审查权限分配
php artisan kylin:permission-review

# 自动修复异常权限
php artisan kylin:permission-review --auto-fix

# JSON 格式输出
php artisan kylin:permission-review --json

# 通知管理员
php artisan kylin:permission-review --notify
```

审查项：
- 冗余权限（无角色关联的权限）
- 闲置角色（无用户关联的角色）
- 权限过度分配（非管理员拥有管理权限）
- 不活跃用户权限（90 天未登录用户仍拥有角色）

**建议配置 cron 每月执行**：
```bash
0 0 1 * * php artisan kylin:permission-review --auto-fix --notify
```

## 审计事件

| 事件 | 说明 | 法律依据 |
|------|------|------|
| `role_created` | 角色创建 | 等保 2.0 8.1.4.5 |
| `permission_created` | 权限创建 | 等保 2.0 8.1.4.5 |
| `role_permissions_synced` | 角色权限同步 | 等保 2.0 8.1.4.5 |
| `role_assign` | 角色分配（`HasRoles` trait） | 等保 2.0 8.1.4.6 |
| `role_remove` | 角色移除（`HasRoles` trait） | 等保 2.0 8.1.4.6 |
| `permission_grant` | 权限授予（`HasRoles` trait） | 等保 2.0 8.1.4.6 |
| `permission_revoke` | 权限撤销（`HasRoles` trait） | 等保 2.0 8.1.4.6 |

## 合规要点

| 合规项 | 实现方式 | 法律依据 |
|------|------|------|
| 最小权限原则 | `least_privilege` 配置 + `BasePolicy` | 等保 2.0 8.1.4.1 |
| 基于角色的访问控制 | RBAC 模型 + Gate/Policy | 等保 2.0 8.1.4.3 |
| 权限变更审计 | `HasRoles` trait 自动审计 | 等保 2.0 8.1.4.6 |
| 权限变更通知 | `PermissionChangeNotifier` | 等保 2.0 8.1.4.1 |
| 权限定期审查 | `PermissionReviewCommand` | 等保 2.0 8.1.4.1 |
| 数据加密传输 | 商用密码保护 | 《密码法》第二十七条 |
| 个人信息保护 | 权限数据不对外公开 | 《个人信息保护法》第六条 |

## 数据库表

| 表名 | 说明 |
|------|------|
| `kylin_roles` | 角色表 |
| `kylin_permissions` | 权限表 |
| `kylin_role_has_permissions` | 角色-权限关联表 |
| `kylin_model_has_roles` | 模型-角色关联表（多态） |
| `kylin_model_has_permissions` | 模型-权限关联表（多态） |

## 法律合规

详见 [LEGAL.md](./LEGAL.md)，涵盖：
- 等保 2.0 (GB/T 22239-2019)
- 《中华人民共和国网络安全法》(2017.6.1)
- 《中华人民共和国个人信息保护法》(2021.11.1)
- 《中华人民共和国数据安全法》(2021.9.1)
- 《中华人民共和国密码法》(2020.1.1)
- NIST RBAC 标准 (ANSI/INCITS 359-2004)

## 依赖

- PHP ^8.5
- Laravel ^13.0
- kylin/core
- 建议：kylin/audit-log（审计日志）、kylin/notification（权限变更通知）

## 许可证

私有软件，未经授权禁止使用。
