@anycms/rbac

基于角色的访问控制（RBAC）前端包，提供权限判断、角色管理、权限管理的完整解决方案。

安装

pnpm add @anycms/rbac

模块结构

@anycms/rbac              # 主入口（类型、工具函数、Guard、Context）
@anycms/rbac/types        # 类型定义
@anycms/rbac/constants    # 内置角色常量
@anycms/rbac/utils        # 权限/角色判断纯函数
@anycms/rbac/context      # RbacProvider / useRbac
@anycms/rbac/guard        # PermissionGuard / usePermissionCheck
@anycms/rbac/api          # 权限、角色、角色-权限关联 API
@anycms/rbac/admin        # 管理后台适配器 + Hooks
@anycms/rbac/admin/hooks  # useRoles / usePermissions

使用方式

1. 提供 RbacContext

在应用顶层（或 AuthProvider 内部）嵌套 RbacProvider：

import { RbacProvider } from "@anycms/rbac/context";

function App({ children }) {
  const user = useCurrentUser(); // 从你的认证系统获取

  return (
    <RbacProvider permissions={user?.permissions ?? []} roles={user?.roles ?? []}>
      {children}
    </RbacProvider>
  );
}

2. 权限守卫组件

import { PermissionGuard } from "@anycms/rbac/guard";

// 单个权限
<PermissionGuard permission="agent:create">
  <Button>创建 Agent</Button>
</PermissionGuard>

// 多个权限（任意一个满足）
<PermissionGuard permission={["agent:read", "agent:write"]}>
  <Button>操作</Button>
</PermissionGuard>

// 多个权限（全部满足）
<PermissionGuard permission={["agent:read", "agent:write"]} requireAll>
  <Button>完整操作</Button>
</PermissionGuard>

// 角色判断
<PermissionGuard role="admin">
  <Button>管理后台</Button>
</PermissionGuard>

// 自定义 fallback
<PermissionGuard permission="system:write" fallback={<span>无权限</span>}>
  <Button>系统设置</Button>
</PermissionGuard>

3. 编程式权限检查

import { usePermissionCheck } from "@anycms/rbac/guard";

function Toolbar() {
  const { can, canAny, canAll, is, isAny, permissions, roles } = usePermissionCheck();

  return (
    <div>
      {can("agent:create") && <Button>创建</Button>}
      {is("admin") && <Button>管理</Button>}
      {canAny(["agent:read", "agent:write"]) && <Button>操作</Button>}
    </div>
  );
}

4. 纯工具函数

无需 React Context，直接传入权限/角色数组：

import { hasPermission, hasRole, hasAnyPermission, hasAllPermissions, canAccessAdmin } from "@anycms/rbac/utils";

const userPermissions = ["agent:create", "agent:read"];
const userRoles = ["user"];

hasPermission(userPermissions, "agent:create"); // true
hasRole(userRoles, "admin");                     // false
hasAnyPermission(userPermissions, ["agent:delete", "agent:read"]); // true
hasAllPermissions(userPermissions, ["agent:create", "agent:read"]); // true
canAccessAdmin(userRoles, userPermissions);      // false

5. API 调用

import { listPermissions, createPermission } from "@anycms/rbac/api/permissions";
import { listRoles, assignRole, getUserRoles } from "@anycms/rbac/api/roles";
import { grantPermission, revokePermission } from "@anycms/rbac/api/role-permissions";

// 列出权限
const res = await listPermissions({ page: 1, page_size: 20 });

// 分配角色
await assignRole({ user_id: "u1", role: "content_editor" });

// 为角色授予权限
await grantPermission({ role: "editor", permission_id: "p1" });

6. 管理后台 Hooks

import { useRoles, usePermissions } from "@anycms/rbac/admin/hooks";

function RolesPage() {
  const { roles, loading, createRole, updateRole, deleteRole } = useRoles();
  // ...
}

function PermissionsPage() {
  const { permissions, categories, loading, createPermission, deletePermission } = usePermissions();
  // ...
}

类型

// 核心类型
type UserRole = string;
type Permission = string;

// 内置角色
const BUILTIN_ROLES: { USER: 'user'; ADMIN: 'admin'; OPERATOR: 'operator' };

// API 类型（from @anycms/rbac/api）
interface Permission { id: string; code: string; name: string; category: string; ... }
interface Role { id: string; name: string; description: string; is_system: boolean; ... }
interface RoleAssignment { user_id: string; role: string; scope: "global" | "client"; ... }

依赖

仅依赖 react，无其他外部依赖。可独立发布使用。