动态路由与权限管理指南

详细说明如何在应用中实现权限守卫及权限高阶组件的使用。

本模板内置了完整的 RBAC 权限管理系统，支持菜单权限和按钮权限控制。

[!TIP] 在线演示 (Demo)：您可以访问权限插件测试页实时体验权限管理和路由权限校验的实际效果。

� 核心功能

如果您的项目中需要使用授权菜单和按钮级权限，必须在项目入口文件（如 main.ts 或 index.tsx）中初始化插件库的 API 配置。

初始化 API

在挂载应用之前，调用 initApi 来配置基础路径及未授权时的重定向逻辑。

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { initApi } from "@pt/react-common/api";
import App from "@/App";
import { getLoginUrl } from "@/config";
import router from "@/router";

import "@/styles/globals.css";
import "@/styles/index.css";

// 🔐 初始化核心 API 配置
initApi({
  baseURL: import.meta.env.VITE_API_URL, // 环境变量中的接口地址
  onUnauthorized: () => {
    // 处理 401 情况：自动跳转到登录页
    router.navigate(getLoginUrl(false));
  },
});

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

🔐 权限系统规范

1. 权限码命名规范

系统中所有的按钮和资源权限均采用 模块:资源:操作 的三段式命名法，确保全局唯一且可读。

system:role:list：查看角色列表页面
system:role:create：新增角色按钮
system:role:delete：删除角色按钮
agent:create:view：创建智能体页面
knowledge:base:edit：编辑知识库资源

2. 菜单配置参数 (Meta)

在项目配套的 运营管理中心 中配置菜单时，可以通过 自定义配置 设置项控制前端展示逻辑。常用的 meta 参数如下：

参数	类型	说明
`meta.title`	`string`	菜单标题：展示在侧边栏的名称
`meta.icon`	`string`	菜单图标：Lucide 图标名称 (如 `users`, `settings`)
`meta.hidden`	`boolean`	是否隐藏：设为 `true` 则不在侧边栏显示但可通过路由访问
`meta.isLink`	`string`	外链地址：配置后点击菜单会跳转到指定 URL
`meta.isOpenInNewTab`	`boolean`	外链打开方式：是否在新窗口打开外链
`meta.isFull`	`boolean`	全屏显示：是否隐藏侧边栏和顶栏（纯净模式）
`meta.isAffix`	`boolean`	是否固定在多标签页（暂不支持）
`meta.isKeepAlive`	`boolean`	是否开启页面缓存（暂不支持）

🛠️ 前端使用方式

1. 使用 AuthGuard 组件 (推荐)

最直观的权限控制方式。

import { AuthGuard } from "@pt/react-common/components";

function MyPage() {
  return (
    <div>
      {/* 🟢 只有具备权限时才渲染 */}
      <AuthGuard permission="system:role:create">
        <button>新增角色</button>
      </AuthGuard>

      {/* 🔴 无权限时显示回退内容 */}
      <AuthGuard
        permission="admin"
        fallback={<div className="text-gray-400">您暂无权限进行此操作</div>}
      >
        <button>系统设置</button>
      </AuthGuard>
    </div>
  );
}

2. 使用 useAuth Hook (逻辑控制)

适用于需要手动判断权限或遍历渲染菜单的场景。

import { useAuth } from "@/providers/AuthProvider";

function SideBar() {
  const { hasPermission, showMenuList } = useAuth();

  return (
    <nav>
      {/* 按钮权限逻辑判断 */}
      {hasPermission("system:role:create") && <QuickAction />}

      {/* 菜单动态渲染 */}
      <ul>
        {showMenuList.map((menu) => (
          <li key={menu.id}>{menu.meta?.title}</li>
        ))}
      </ul>
    </nav>
  );
}

3. 高阶组件 withAuth

用于对整个页面组件进行快速鉴权。

import { withAuth } from "@pt/react-common/components";

const AdminPage = () => <div>秘密控制台</div>;

export default withAuth(AdminPage, {
  permission: "system:admin:view",
  fallback: <ForbiddenPage />,
});

📦 属性说明 (AuthGuard Props)

属性	类型	默认值	说明
`permission`	`string \| string[]`	-	权限标识，数组形式代表需同时满足
`fallback`	`ReactNode`	`null`	权限不足时的占位内容
`children`	`ReactNode`	-	鉴权通过后的子元素

动态路由与权限管理指南

On this page