@w.ui/wui-react

🚀 Pro React Admin

Pro React Admin 是一款基于 React v19 的高性能、企业级中后台前端解决方案。深度整合 RBAC 动态权限、KeepAlive 缓存、多标签页与 AI 智能助手。提供开箱即用的国际化、暗黑模式、Mock 数据与 E2E 测试体系，助力开发者快速构建稳健、安全的 SaaS 平台与数据可视化系统。

🌐 在线预览

• 主应用 (Main App): https://wkylin.github.io/pro-react-admin/
• 组件文档 (Storybook): https://wkylin.github.io/pro-react-admin/storybook/
• 导航页 (Portal): https://wkylin.github.io/pro-react-admin/portal.html

🏆 项目亮点

• 🚀 极致性能体验：基于 React 19 构建，重构 KeepAlive 缓存机制（采用 CSS 显隐策略替代 DOM 移动，大幅减少重排），配合 useTransition 实现丝滑的 Tab 切换与交互响应。
• 🧩 丰富组件生态：沉淀 300+ 高质量业务组件，覆盖图表、地图、编辑器等场景。集成 Storybook 实现组件可视化开发与文档管理，显著提升复用效率。
• 🛡️ 企业级权限体系：完善的 RBAC 模型，支持路由、菜单、按钮级细粒度权限控制。内置路由自动过滤、useSafeNavigate 防越权跳转，保障系统安全。
• ⚡️ 前沿技术栈：采用 TypeScript v5 + Ant Design v6 + Vite v7/Webpack v5 双构建模式，紧跟社区最新标准，提供最佳开发体验。
• 🤖 AI 智能化集成：内置 ChatGPT 演示（支持 SSE 流式响应）、Markmap 思维导图生成、Mermaid 流程图渲染，探索 AI 在后台管理中的应用场景。
• 🧪 全链路质量保障：集成 Playwright E2E 自动化测试，配合 Mock Service Worker (MSW) 实现真实的网络模拟与多角色权限切换测试。
• 📱 极致移动端适配：精心打磨的响应式布局，从 PC 到手机端提供一致的流畅体验。

🔑 核心功能

• 🔐 动态权限引擎：登录后根据角色（Admin/Manager/Business/User）自动生成路由表，非权限路由自动拦截（403/404）。
• 📑 高性能多标签页：支持 ProTabs 多页签切换，状态持久化保持，支持右键菜单（关闭其他/关闭所有/刷新）。
• 📚 组件文档库：集成 Storybook，提供 300+ 组件的交互式文档与预览，支持 Props 动态调试与独立测试。
• 📡 健壮请求层：封装统一请求库，支持并发控制、自动重试、取消重复请求、全局错误处理与消息去重。
• 👤 登录/注册流程：完整的登录鉴权流程，支持一键测试账号切换，实时同步权限状态。
• 📊 数据可视化：集成 ECharts、D3.js、Recharts 等多种图表库，支持大数据量展示。
• 📝 富文本与文档：支持 Markdown 实时渲染与编辑、代码高亮、数学公式解析。
• 🎬 多媒体支持：内置音频/视频播放器，支持 Tab 切换自动暂停/恢复播放，优化资源占用。
• 🌍 主题与国际化：内置明亮/暗黑模式一键切换，支持多语言（i18n）动态切换。
• 🎭 Mock 数据模拟：基于 Faker.js 和 MSW 的纯前端 Mock 方案，脱离后端独立开发。

📦 技术栈

• ⚛️ Core: React v19 / TypeScript v5
• 🎨 UI: Ant Design v6
• 🛣️ Router: React Router v7
• ⚡ Build: Vite v7 / Webpack v5
• 🧪 Test: Playwright / Jest / Testing Library
• 🎭 Mock: Mock Server（Faker/MSW）
• 📏 Lint: ESLint / Prettier / Husky / Commitizen
• 🔍 Quality: Sentry / SonarQube / DeepScan
• 🐳 Deploy: Docker / Nginx / Github Actions

📁 目录结构

pro-react-admin/
├── src/
│   ├── actions/           # Redux/Action 相关
│   ├── assets/            # 静态资源
│   ├── components/        # 业务组件
│   ├── config/            # 配置文件
│   ├── hooks/             # 自定义 hooks
│   ├── i18n/              # 国际化
│   ├── mock/              # Mock 数据
│   ├── pages/             # 页面模块
│   ├── reducers/          # Redux Reducer
│   ├── routers/           # 路由配置
│   ├── service/           # 请求与服务
│   ├── store/             # 状态管理
│   ├── styles/            # 全局样式
│   ├── theme/             # 主题相关
│   ├── utils/             # 工具函数
│   ├── App.tsx            # 应用入口
│   └── index.tsx          # 渲染入口
├── public/                # 公共资源
├── tests/                 # 测试用例
├── docs/                  # 文档
├── scripts/               # 脚本
├── api/                   # Mock API 服务
├── ...

🚀 快速开始

git clone https://github.com/wkylin/pro-react-admin.git
cd pro-react-admin
npm install
npm run dev

更多用法详见 详细文档 与 用户角色权限说明。

📝 近期主要更新

• ⚡ 性能优化：重构 KeepAlive 实现，支持 React 19 <Activity> (Offscreen) 原生冻结，降级模式采用 CSS 显隐替代 DOM 移动，大幅减少重排
• 🎨 体验优化：ProTabs 切换引入 useTransition，交互响应更流畅；global-loader 移除逻辑优化，消除首屏白屏与卡顿
• 🎬 媒体控制：音视频组件（MusicPlayer/Video）支持 Tab 切换自动暂停/恢复播放
• 🛠️ 开发体验：KeepAlive 支持 HMR 热更新，开发调试状态不丢失
• 🛡️ 权限体系：重构支持缓存、过期、强制刷新、单例获取，避免重复请求和竞态
• 🛣️ 路由过滤：路由与菜单权限自动过滤，首页对所有账号可见
• 🔒 安全跳转：useSafeNavigate/SafeLink 封装，防止越权跳转
• 📡 请求重构：支持并发/串行/重试/取消/全局错误处理
• 🔔 消息去重：全局消息去重，避免重复弹窗干扰
• 🎭 Mock 增强：多角色切换与权限同步
• 🧪 E2E 测试：Playwright 核心场景覆盖
• 📚 文档完善：文档与示例持续更新

🤝 贡献指南

欢迎 PR、Issue 与 Star！

• Fork 本仓库
• 新建分支：git checkout -b feature/xxx
• 提交更改：git commit -m 'feat: 新增 xxx 功能'
• 推送分支：git push origin feature/xxx
• 新建 Pull Request

📄 License

Apache-2.0 © wkylin

🌐 约定式提交

• 约定式提交
• 语义化版本 2.0.0

📄 架构

🛠️ 脚手架--白泽 baize

• 可以使用为此项目准备的脚手架开发--白泽 baize

     > npm install baize --location=global
     > baize
  

🔍 自动化持续代码审查工具

• DeepSource/
• DeepScan
• SonarQube

🐳 Mac 本地部署 SonarQube

• SonarQube for Mac
• Gitlab for Mac
• Gitlab CI/CD for Mac

🌏 Nginx 配置指南

• Mac Nginx

   brew install nginx
   brew reinstall nginx
  
   /usr/local/var/www
   /usr/local/etc/nginx/nginx.conf
   /usr/local/etc/nginx/servers/
  
   brew services list
   brew services start nginx
   brew services stop nginx
   brew services restart nginx
  

• Nginx.conf

  server {
   listen       8081;
   #server_name  localhost;
   server_name  www.pro.react.admin.com;
   # 静态资源
   location / {
       root   /usr/local/var/www/pro-react-admin;
       index  index.html index.htm;
       try_files  $uri $uri/ /index.html @rewrites;
       expires -1;
       add_header Cache-Control no-cache;
       # proxy_pass http://localhost:3000;
   }
   # API代理
   location /api/ {
       proxy_pass https://api.example.com/;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
       # 允许跨域配置
       add_header Access-Control-Allow-Origin $http_origin;
       add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE, OPTIONS';
       add_header Access-Control-Allow-Headers 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization';
       add_header Access-Control-Allow-Credentials 'true';
       if ($request_method = 'OPTIONS') {
           add_header Access-Control-Max-Age 86400;
           add_header Content-Length 0;
           add_header Content-Type text/plain;
           return 204;
       }
   }
   location @rewrites {
     rewrite ^(.+)$ /index.html break;
   }
   # 不缓存
   location ~ .*(htm|html|json)?$ {
     expires -1;
   }
   # 或者全部重定向
   # return 301 https://$server_name$request_uri;
  }
  
   # SwitchHosts!
   192.168.1.101 www.pro.react.admin.com
  
   # 第一个目录的配置
   # C:\nginx-1.27.5\html\var\www\html\
   # location /html/ {
   #     root   /var/www;
   #     index  index.html index.htm;
   # }
  
   # 第二个目录的配置
   # C:\nginx-1.27.5\html\var\www\static\
   # location /static/ {
   #    root   /var/www;
   #    index  index.html index.htm;
   #}
  
  

• Nginx for Windows

     1. start nginx
     2. nginx -s stop
     3. nginx -s quit
     4. nginx -s reload
     5. nginx -s reopen
  

🌳 Tree Node Cli

• npm install -g tree-node-cli
• Mac: tree -L 2 -I "node_modules" -r -F
• Win: treee -L 2 -I "node_modules" -r -F

📦 Webpack Analyse

• Webpack 官方分析工具

     npm run analyze:build
  

• 依赖分析

    1. npm run js-analyzer
    2. "standard": "standard src/\*_/_",
    3. "standard:fix": "standard --fix src/\*_/_",
    4. rm -rf package-lock.json
  

🚀 GitHub Proxy

• 首先确认自己 git 拉取代码的方式

    git remote -v
  

• 设置代理

    git config --global https.proxy 127.0.0.1:10808
    git config --global http.proxy 127.0.0.1:10808
    git config --global http.proxy 'socks5://127.0.0.1:10808'
    git config --global https.proxy 'socks5://127.0.0.1:10808'
  

• 查看代理是否成功

    git config --get --global http.proxy
  

• 查看 git 配置

    git config --global --list
  

• 取消代理

    git config --global --unset http.proxy
    git config --global --unset https.proxy
  

🤝 Show your support

If you like the project, give it a star ⭐️, it will be a great encouragement to me.

⭐️ Star History