# react-dome

**Repository Path**: mssng/dome

## Basic Information

- **Project Name**: react-dome
- **Description**: QiFeng DDD Frontend 是 QiFeng DDD 后端服务 的官方配套前端应用，基于 React 18 和 Ant Design 5 构建的企业级权限管理系统前端实现。项目完整实现了 RBAC 权限模型的前端交互，支持动态数据级权限控制和多租户隔离。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-10-31
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QiFeng DDD Frontend - 企业级权限管理系统前端

<div align="center">

**React + Ant Design · 动态权限控制 · 完美对接 QiFeng DDD 后端**

[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![React](https://img.shields.io/badge/React-18.3.1-blue.svg)](https://reactjs.org/)
[![Ant Design](https://img.shields.io/badge/Ant%20Design-5.25.4-1890ff.svg)](https://ant.design/)
[![Node](https://img.shields.io/badge/Node-16+-green.svg)](https://nodejs.org/)

[⚡ 快速开始](#-快速开始) • [🔥 核心特性](#-核心特性) • [📖 API文档](#-api-集成)

</div>

---

## 💡 项目简介

QiFeng DDD Frontend 是 **QiFeng DDD 后端服务** 的官方配套前端应用，基于 **React 18** 和 **Ant Design 5** 构建的企业级权限管理系统前端实现。项目完整实现了 RBAC 权限模型的前端交互，支持动态数据级权限控制和多租户隔离。

**核心价值**：
- 🎨 **现代化 UI**：基于 Ant Design 5 的专业后台管理界面
- 🔐 **三层权限防护**：URL级 + 组件级 + 按钮级权限控制
- ⚡ **高性能体验**：路由懒加载、组件按需引入、请求缓存
- 🎯 **配置化权限**：通过 SpEL 表达式实现细粒度控制，无需修改代码
- 🏢 **多租户支持**：自动处理租户上下文，支持 SaaS 模式
- 📱 **响应式设计**：适配桌面端和移动端设备

---

## ⚡ 快速开始

### 前置要求

在开始之前，请确保已安装以下环境：

- **Node.js 16+**：JavaScript 运行时
- **npm 或 yarn**：包管理器
- **QiFeng DDD 后端服务**：需要先启动后端服务（见下方说明）

### 第一步：启动后端服务

本项目需要配合 **QiFeng DDD 后端服务** 使用，请先确保后端服务已启动：

```bash
# 克隆后端项目
git clone https://gitee.com/mssng/ddd.git
cd ddd

# 方式一：Docker Compose 启动（推荐）
docker-compose up -d

# 方式二：本地启动
mvn spring-boot:run -pl qiufeng-ddd-trigger
```

**后端服务地址**：http://localhost:8091  
**API 文档**：http://localhost:8091/doc.html  
**默认账号**：`master` / `Qq123456`

### 第二步：启动前端项目

```bash
# 克隆前端项目
git clone https://gitee.com/mssng/dome.git
cd dome

# 安装依赖
npm install
# 或使用 yarn
yarn install

# 启动开发服务器
npm start
# 或使用 yarn
yarn start
```

访问 http://localhost:3000

默认账号：`master` / `Qq123456`

### 生产环境部署

```bash
# 构建生产版本
npm run build

# 将 build 目录部署到 Nginx 或其他静态服务器
```

**Nginx 配置示例**：
```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # 代理 API 请求到后端
    location /api/ {
        proxy_pass http://localhost:8091;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

---

## 🔥 核心特性

### 1️⃣ 完整的 RBAC 权限模型

- 👥 **用户管理**：用户的增删改查、状态控制、密码重置
- 🎭 **角色管理**：角色的增删改查、权限分配、数据范围设置
- 🔑 **权限管理**：菜单权限、按钮权限、API 接口权限的细粒度控制
- 📋 **菜单管理**：树形菜单结构、路由配置、图标管理

### 2️⃣ 三层权限防护

| 层级 | 实现方式 | 说明 |
|------|---------|------|
| URL级 | RequireAuth 组件 | 路由级别的认证保护 |
| 组件级 | Permission 组件 | 条件渲染受保护的UI元素 |
| 按钮级 | hasPermission 工具函数 | 细粒度的按钮级别权限控制 |

**使用示例**：
```jsx
// URL级保护
<Route path="/user-list" element={
    <RequireAuth><UserList/></RequireAuth>
} />

// 组件级保护
<Permission permission="user:create" userPermissions={permissions}>
    <Button>创建用户</Button>
</Permission>

// 按钮级保护
{hasPermission('user:delete', permissions) && (
    <Button danger>删除</Button>
)}
```

### 3️⃣ 动态数据级权限

通过后端 SpEL 表达式引擎实现的数据级权限控制：

```javascript
// 前端只需传递权限标识，规则由后端动态执行
@PreAuthorize("hasPermission('order:view')")
```

配置示例（在后端数据库）：
```sql
INSERT INTO permission_rule
VALUES (10, '#order.userId == #currentUserId', 'DATA_SCOPE');
```

### 4️⃣ 高性能优化

- 🚀 **路由懒加载**：按需加载页面组件，减少首屏加载时间
- 📦 **组件按需引入**：Ant Design 组件按需加载，减小打包体积
- 💾 **请求缓存**：常用数据缓存，减少重复请求
- ⚡ **Token 自动刷新**：无感知的 Token 续期机制

### 5️⃣ 在线用户管理

- 👥 实时查看在线用户列表
- 🚫 强制用户下线功能
- 🔒 Token 黑名单机制
- 📊 用户会话监控

### 6️⃣ 登录日志审计

- 📝 完整记录登录/登出行为
- 🌍 IP 地理位置解析
- 🔍 登录失败追踪
- 📈 统计分析功能

### 7️⃣ 多租户数据隔离

- 🏢 **自动隔离**：框架层自动处理租户上下文
- 🔑 **JWT 携带**：Token 中包含租户ID
- 🛡️ **数据安全**：避免跨租户数据泄露
- ⚡ **零侵入**：业务代码无需关心租户逻辑

---

## 📸 演示页面

### 1. 登录页面

![登录页面](public/img/0.png)

### 2. 仪表盘

![仪表盘](public/img/1.png)

### 3. 用户管理

![用户管理](public/img/3.png)

### 4. 角色管理

![角色管理](public/img/4.png)

### 5. 权限管理

![权限管理](public/img/6.png)

### 6. 菜单管理

![菜单管理](public/img/5.png)

### 7. 公司管理

![公司管理](public/img/2.png)


### 8. 个人中心

![个人中心](public/img/9.png)

### 8. 用户登录日志

![用户登录日志](public/img/8.png)

---

## 🏗️ 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| React | 18.3.1 | 前端框架 |
| Ant Design | 5.25.4 | UI 组件库 |
| React Router DOM | 7.6.2 | 路由管理 |
| Axios | 1.9.0 | HTTP 请求 |
| Crypto-JS | 4.2.0 | 加密工具 |
| React App Rewired | 2.2.1 | 自定义配置 |
| Sass | 1.89.1 | CSS 预处理器 |

---

## 📂 项目结构

```
src/
├── api/                      # API 接口层
│   ├── auth.js              # 认证相关接口
│   ├── user.js              # 用户管理接口
│   ├── role.js              # 角色管理接口
│   ├── permission.js        # 权限管理接口
│   ├── permissionRule.js    # 权限规则接口
│   ├── menu.js              # 菜单管理接口
│   ├── company.js           # 公司/租户管理接口
│   ├── dept.js              # 部门管理接口
│   └── loginLog.js          # 登录日志接口
├── components/               # 通用组件
│   └── auth/
│       └── Permission.js    # 权限控制组件
├── hooks/                    # 自定义 Hooks
│   ├── usePermissions.js    # 权限相关 Hooks
│   └── index.js             # 统一导出
├── router/                   # 路由配置
│   └── IndexRouter.js       # 路由定义
├── utils/                    # 工具类
│   ├── request.js           # HTTP 请求封装
│   ├── auth.js              # 认证工具函数
│   ├── permission.js        # 权限检查工具
│   ├── encryption.js        # 加密工具
│   └── ownership.js         # 所有权检查工具
├── views/                    # 页面组件
│   ├── login/               # 登录模块
│   │   ├── Login.js         # 登录页面
│   │   └── ForgotPassword.js # 忘记密码
│   ├── home/                # 首页模块
│   │   ├── Dashboard.js     # 仪表盘
│   │   ├── Home.js          # 主页布局
│   │   ├── TopHeader.js     # 顶部导航
│   │   ├── SideMenu.js      # 侧边菜单
│   │   ├── Profile.js       # 个人中心
│   │   ├── Settings.js      # 个人设置
│   │   └── Notice.js        # 消息通知
│   └── base/                # 基础管理模块
│       ├── UserList.js      # 用户列表
│       ├── User.js          # 用户详情
│       ├── RoleList.js      # 角色列表
│       ├── PermissionList.js # 权限列表
│       ├── MenuList.js      # 菜单列表
│       ├── CompanyList.js   # 公司列表
│       ├── DeptList.js      # 部门列表
│       ├── LoginLogList.js  # 登录日志
│       └── OnlineList.js    # 在线用户
└── styles/                   # 样式文件
    └── layout.css           # 布局样式
```

---

## 📖 API 集成

本项目与 **QiFeng DDD 后端服务** 完美对接，所有 API 接口已封装完成。

### 认证接口

```javascript
import { login, getCurrentUser, logout } from '@/api/auth';

// 用户登录
const handleLogin = async (values) => {
    const data = await login({
        username: values.username,
        password: values.password
    });
    localStorage.setItem('accessToken', data.accessToken);
};

// 获取当前用户信息
const userInfo = await getCurrentUser();

// 退出登录
await logout();
```

### 用户管理

```javascript
import { getUserList, createUser, updateUser, deleteUser } from '@/api/user';

// 获取用户列表（分页）
const users = await getUserList({
    pageNum: 1,
    pageSize: 10,
    username: 'admin'
});

// 创建用户
await createUser({
    userName: 'testuser',
    nickName: '测试用户',
    phone: '13800138000',
    email: 'test@example.com',
    status: 1
});

// 更新用户
await updateUser({ userId, ...userData });

// 删除用户
await deleteUser(userId);
```

### 角色管理

```javascript
import { getAllRoles, assignRoleToUser, getUserRoles } from '@/api/role';

// 获取所有角色
const roles = await getAllRoles();

// 为用户分配角色
await assignRoleToUser(userId, roleId);

// 获取用户角色
const userRoles = await getUserRoles(userId);
```

### 权限管理

```javascript
import { getAllPermissions } from '@/api/permission';

// 获取所有权限
const permissions = await getAllPermissions();

// 为角色分配权限
await assignPermissionToRole(roleId, permissionId);
```

### 菜单管理

```javascript
import { getMenuList } from '@/api/menu';

// 获取菜单列表（树形结构）
const menus = await getMenuList();
```

更多 API 使用示例请参考：[API_USAGE.md](API_USAGE.md)

---

## 🎯 适用场景

- ✅ **企业内部系统**：权限管理系统、OA 系统、ERP 系统
- ✅ **SaaS 平台**：多租户业务系统、云平台管理后台
- ✅ **学习实践**：DDD 架构学习、React 最佳实践、权限系统设计
- ✅ **面试项目**：展示全栈开发能力、系统设计能力

---

## 🌟 支持项目

如果这个项目对你有帮助，欢迎：

- ⭐ Star 项目
- 🍴 Fork 二次开发
- 🐛 提交 Issue
- 🔧 提交 PR

---

## 📄 开源协议

[MIT License](LICENSE)

---

## 🔗 相关链接

- **后端项目**：[QiFeng DDD Backend](https://gitee.com/mssng/ddd)
- **后端 API 文档**：http://localhost:8091/doc.html
- **React 官方文档**：https://reactjs.org/
- **Ant Design 官方文档**：https://ant.design/

---

<div align="center">

**Made with ❤️ by houhuai**

[↑ 返回顶部](#qifeng-ddd-frontend---企业级权限管理系统前端)

</div>