# react_base_framework

**Repository Path**: hlw422/react_base_framework

## Basic Information

- **Project Name**: react_base_framework
- **Description**: 基于 React + .NET 的企业级后台管理系统框架，提供完整的用户认证、权限管理、多语言支持等功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-22
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# React Admin Framework

基于 React 的企业级后台管理系统框架，提供完整的用户认证、权限管理、多语言支持等功能。

**后端支持两种实现：**
- **.NET 版本** (`backend/`) - 使用 .NET 10 + Entity Framework Core
- **Node.js 版本** (`backend-nodejs/`) - 使用 Express + Prisma

## 功能特性

### 核心功能
- **用户认证** - JWT Token 认证，支持登录/注册
- **角色管理** - CRUD 操作，支持角色-菜单权限分配
- **用户管理** - CRUD 操作，支持用户-角色关联
- **菜单管理** - CRUD 操作，支持树形结构菜单
- **仪表盘** - 数据统计和可视化图表

### 技术特性
- **响应式布局** - 完美适配 PC 和移动端
- **多语言支持** - 中文 (zh-CN) / 英文 (en-US)
- **角色权限控制** - 基于角色的菜单权限，不同用户看到不同菜单
- **前端路由保护** - 无权限页面自动跳转
- **API 代理** - Vite 开发服务器代理后端 API

## 技术栈

### 前端
| 技术 | 版本 | 说明 |
|------|------|------|
| React | 18.3 | UI 框架 |
| TypeScript | 5.6 | 类型安全 |
| Vite | 5.4 | 构建工具 |
| Tailwind CSS | 3.4 | 原子化 CSS |
| shadcn/ui | - | 组件库 |
| Zustand | 5.0 | 状态管理 |
| React Router | 7.18 | 路由管理 |
| i18next | 26.3 | 国际化 |
| Axios | 1.18 | HTTP 客户端 |
| Recharts | 3.8 | 图表库 |

### 后端 (.NET 版本)
| 技术 | 版本 | 说明 |
|------|------|------|
| .NET | 10.0 | 运行时 |
| Entity Framework Core | 10.0 | ORM |
| PostgreSQL | 17.0 | 数据库 |
| JWT Bearer | 10.0 | 认证 |
| BCrypt.Net | 4.2 | 密码加密 |
| Swagger | 10.2 | API 文档 |

### 后端 (Node.js 版本)
| 技术 | 版本 | 说明 |
|------|------|------|
| Node.js | 20+ | 运行时 |
| Express | 5.1 | Web 框架 |
| Prisma | 6.10 | ORM |
| PostgreSQL | 17.0 | 数据库 |
| JWT | 9.0 | 认证 |
| bcryptjs | 3.0 | 密码加密 |

## 项目结构

```
react_base/
├── backend/                          # .NET 后端项目
│   └── ReactBase.Api/
│       ├── Controllers/              # API 控制器
│       │   ├── AuthController.cs     # 认证接口
│       │   ├── UsersController.cs    # 用户管理
│       │   ├── RolesController.cs    # 角色管理
│       │   ├── MenusController.cs    # 菜单管理
│       │   └── DashboardController.cs # 仪表盘
│       ├── DTOs/                     # 数据传输对象
│       ├── Data/                     # 数据库上下文
│       ├── Migrations/               # 数据库迁移
│       ├── Models/                   # 数据模型
│       ├── Services/                 # 业务服务层
│       └── Program.cs                # 启动配置
│
├── backend-nodejs/                   # Node.js 后端项目
│   ├── src/
│   │   ├── routes/                   # API 路由
│   │   │   ├── auth.routes.ts        # 认证接口
│   │   │   ├── user.routes.ts        # 用户管理
│   │   │   ├── role.routes.ts        # 角色管理
│   │   │   ├── menu.routes.ts        # 菜单管理
│   │   │   └── dashboard.routes.ts   # 仪表盘
│   │   ├── middleware/               # 中间件
│   │   ├── utils/                    # 工具函数
│   │   ├── seed.ts                   # 种子数据
│   │   └── index.ts                  # 入口文件
│   ├── prisma/
│   │   └── schema.prisma             # 数据库模型
│   ├── package.json
│   └── tsconfig.json
│
├── src/                              # 前端项目
│   ├── components/                   # 公共组件
│   │   ├── layout/                   # 布局组件
│   │   │   ├── AppLayout.tsx         # 主布局
│   │   │   ├── AppSidebar.tsx        # 桌面端侧边栏
│   │   │   ├── AppHeader.tsx         # 顶部导航
│   │   │   └── MobileNav.tsx         # 移动端导航
│   │   └── ui/                       # shadcn/ui 组件
│   │
│   ├── pages/                        # 页面组件
│   │   ├── Login.tsx                 # 登录页
│   │   ├── Register.tsx              # 注册页
│   │   ├── Dashboard.tsx             # 仪表盘
│   │   ├── user/                     # 用户管理
│   │   ├── role/                     # 角色管理
│   │   └── menu/                     # 菜单管理
│   │
│   ├── services/                     # API 服务层
│   │   ├── http.ts                   # Axios 封装
│   │   ├── authService.ts            # 认证服务
│   │   ├── userService.ts            # 用户服务
│   │   ├── roleService.ts            # 角色服务
│   │   ├── menuService.ts            # 菜单服务
│   │   └── dashboardService.ts       # 仪表盘服务
│   │
│   ├── stores/                       # 状态管理
│   │   ├── authStore.ts              # 认证状态
│   │   ├── appStore.ts               # 应用状态
│   │   └── userStore.ts              # 用户状态
│   │
│   ├── router/                       # 路由配置
│   │   ├── index.tsx                 # 路由定义
│   │   ├── ProtectedRoute.tsx        # 认证保护
│   │   └── MenuProtectedRoute.tsx    # 菜单权限保护
│   │
│   ├── i18n/                         # 国际化
│   │   └── locales/
│   │       ├── zh-CN.ts              # 中文
│   │       └── en-US.ts              # 英文
│   │
│   ├── types/                        # TypeScript 类型
│   └── utils/                        # 工具函数
│
├── public/                           # 静态资源
├── index.html                        # 入口 HTML
├── package.json                      # 前端依赖
├── vite.config.ts                    # Vite 配置
├── tailwind.config.js                # Tailwind 配置
└── tsconfig.json                     # TypeScript 配置
```

## 快速开始

### 环境要求

- **Node.js** >= 18.0
- **PostgreSQL** >= 17.0
- **.NET SDK** >= 10.0（仅 .NET 版本）

### 1. 克隆项目

```bash
git clone <repository-url>
cd react_base
```

### 2. 启动后端

#### 方式一：Node.js 版本（推荐）

```bash
# 进入 Node.js 后端目录
cd backend-nodejs

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库连接

# 初始化数据库
npm run db:push
npm run db:seed

# 启动后端服务（默认端口 5010）
npm run dev
```

#### 方式二：.NET 版本

```bash
# 进入 .NET 后端目录
cd backend/ReactBase.Api

# 还原依赖
dotnet restore

# 启动后端服务（默认端口 5010）
dotnet run
```

启动后访问 http://localhost:5010/swagger 查看 API 文档。

### 3. 启动前端

```bash
# 回到项目根目录
cd ..

# 安装依赖
npm install

# 启动开发服务器（端口 5566）
npm run dev
```

访问 http://localhost:5566 访问应用。

### 4. 默认账户

| 用户名 | 密码 | 角色 | 权限 |
|--------|------|------|------|
| admin | admin123 | Admin | 所有菜单 |
| (注册) | - | User | 仅仪表盘 |

## API 接口

### 认证接口
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/auth/login` | 用户登录 |
| POST | `/api/auth/register` | 用户注册 |

### 用户管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/users` | 获取用户列表 |
| GET | `/api/users/{id}` | 获取用户详情 |
| POST | `/api/users` | 创建用户 |
| PUT | `/api/users/{id}` | 更新用户 |
| DELETE | `/api/users/{id}` | 删除用户 |

### 角色管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/roles` | 获取角色列表 |
| GET | `/api/roles/{id}` | 获取角色详情 |
| POST | `/api/roles` | 创建角色 |
| PUT | `/api/roles/{id}` | 更新角色 |
| DELETE | `/api/roles/{id}` | 删除角色 |

### 菜单管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/menus` | 获取所有菜单 |
| GET | `/api/menus/tree` | 获取菜单树 |
| GET | `/api/menus/user` | 获取当前用户菜单 |
| POST | `/api/menus` | 创建菜单 |
| PUT | `/api/menus/{id}` | 更新菜单 |
| DELETE | `/api/menus/{id}` | 删除菜单 |

### 仪表盘
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/dashboard/stats` | 获取统计数据 |

## 开发命令

### 前端命令
```bash
npm run dev      # 启动开发服务器
npm run build    # 构建生产版本
npm run preview  # 预览生产构建
npm run lint     # 代码检查
```

### Node.js 后端命令
```bash
cd backend-nodejs
npm run dev          # 启动开发服务器
npm run build        # 编译 TypeScript
npm start            # 启动生产服务器
npm run db:generate  # 生成 Prisma Client
npm run db:push      # 推送数据库结构
npm run db:seed      # 填充种子数据
npm run db:reset     # 重置数据库
```

### .NET 后端命令
```bash
cd backend/ReactBase.Api
dotnet run                           # 启动服务
dotnet build                         # 编译项目
dotnet ef migrations add <Migration> # 添加迁移
dotnet ef database update            # 更新数据库
```

## 配置说明

### 前端配置 (vite.config.ts)

```typescript
server: {
  port: 5566,           // 开发服务器端口
  proxy: {
    '/api': {
      target: 'http://localhost:5010',  // 后端地址
      changeOrigin: true,
    }
  }
}
```

### 后端配置 (appsettings.json)

```json
{
  "Jwt": {
    "Key": "YourSecretKey",
    "ExpiryInMinutes": 60
  },
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=reactbase.db"
  }
}
```

## 权限系统

### 角色权限流程

1. 用户登录获取 Token 和菜单列表
2. 侧边栏根据菜单列表动态渲染
3. 路由访问时验证菜单权限
4. 无权限自动跳转到仪表盘

### 菜单数据结构

```typescript
interface MenuItem {
  id: number
  name: string
  icon?: string        // lucide-react 图标名称
  path?: string        // 路由路径
  parentId?: number    // 父级菜单 ID
  sortOrder: number
  isActive: boolean
  children?: MenuItem[]
}
```

### 图标映射

支持的图标名称（基于 lucide-react）：

- `LayoutDashboard` - 仪表盘
- `Users` - 用户管理
- `Shield` - 角色管理
- `Menu` - 菜单管理
- `Settings` - 设置
- `Home` - 首页
- `FileText` - 文档
- `BarChart3` - 图表
- `Bell` - 通知

## 多语言

### 添加新语言

1. 创建语言文件 `src/i18n/locales/<lang>.ts`
2. 在 `src/i18n/index.ts` 中注册

### 添加翻译

```typescript
// src/i18n/locales/zh-CN.ts
const zhCN = {
  menuNames: {
    dashboard: "仪表盘",
    usermanagement: "用户管理",
    // ...
  }
}
```

## 部署

### 前端部署

```bash
npm run build
# 将 dist/ 目录部署到 Web 服务器
```

### Node.js 后端部署

```bash
cd backend-nodejs
npm run build
# 将 dist/ 目录和 package.json 部署到服务器
# 在服务器上运行 npm install --production
# 启动: node dist/index.js
```

或使用 Docker：
```bash
cd backend-nodejs
docker build -t react-base-api-nodejs .
docker run -d -p 5010:5010 react-base-api-nodejs
```

### .NET 后端部署

```bash
cd backend/ReactBase.Api
dotnet publish -c Release
# 将发布目录部署到服务器
```

## 常见问题

### 1. 后端启动失败

确保已安装 .NET 10 SDK：
```bash
dotnet --version
```

### 2. 数据库不存在

首次启动会自动创建 SQLite 数据库和种子数据。

### 3. 登录失败

检查后端是否启动，默认地址：http://localhost:5010

### 4. API 代理不生效

确保前端 Vite 开发服务器正在运行，代理配置在 vite.config.ts 中。

## License

MIT