# react-admin-side

**Repository Path**: GyYuMine/react-admin-side

## Basic Information

- **Project Name**: react-admin-side
- **Description**: React 18
TypeScript 5.x类型安全
Ant Design 5.x 企业级 UI 组件库
Vite 5.x 下一代前端构建工具
SCSS CSS 预处理器
React Router DOM v6 路由管理
Zustand 轻量级状态管理
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-08
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# React + TypeScript + Ant Design 后台管理系统

一个使用最新技术栈构建的现代化后台管理系统，采用模块化架构设计，支持动态路由生成、组件自动导入、SVG图标管理等高级功能。

## 🚀 技术栈

- **React 19** - 最新版本
- **TypeScript 5.9** - 类型安全
- **Ant Design 6** - 企业级 UI 组件库
- **Vite 8** - 下一代前端构建工具
- **SCSS** - CSS 预处理器
- **React Router DOM v6** - 路由管理
- **Zustand 5** - 轻量级状态管理
- **SVG Icons** - 基于 vite-plugin-svg-icons 的图标方案

## ✨ 功能特性

### 核心功能
- ✅ 完整的登录认证系统（JWT Token）
- ✅ 路由守卫与权限控制
- ✅ 全局状态管理（Zustand + localStorage 持久化）
- ✅ 响应式布局设计
- ✅ 侧边栏折叠/展开
- ✅ 多级嵌套菜单支持（最高支持 5 级菜单）

### 高级特性
- 🎯 **模块化架构** - 支持按业务模块独立开发
- 🔄 **动态路由生成** - 基于环境变量按需加载模块路由
- 📦 **组件自动导入** - 无需手动 import，自动注册全局组件
- 🎨 **SVG 图标系统** - 支持图标缓存、按需加载
- 🔥 **热更新优化** - 组件变化自动更新类型声明
- ⚡ **懒加载** - 路由级代码分割，提升首屏性能

## 📦 快速开始

### 环境要求
- Node.js >= 18
- npm >= 9

### 安装依赖

```bash
npm install
```

### 启动开发服务器

#### 1. 启动完整应用（所有模块）
```bash
npm run dev
```

#### 2. 仅启动指定模块（开发优化）
```bash
# 仅启动 UserManage 模块
npm run dev:UserManage

# 仅启动 test 模块
npm run dev:test
```

访问 http://localhost:8080/

### 生产环境打包

```bash
# 打包所有模块
npm run build

# 仅打包 test 模块
npm run build:test
```

### 预览生产构建

```bash
npm run preview
```

### 代码检查

```bash
npm run lint
```

## 🔐 默认登录账号

- 用户名：`1111`
- 密码：任意（当前为演示模式，使用硬编码 token）

> ⚠️ 注意：当前版本为演示模式，实际项目需对接后端 API 实现真实认证

## 📁 项目结构

```
react-admin-side/
├── public/                    # 静态资源
│   └── favicon.svg
├── plugins/                   # Vite 插件
│   ├── auto-import.ts         # 组件自动导入配置
│   └── dynamic-route-generator.ts  # 动态路由生成插件
├── src/
│   ├── assets/                # 全局静态资源
│   │   ├── icons/             # 全局 SVG 图标
│   │   ├── images/            # 全局图片资源
│   │   └── fonts/             # 全局字体
│   ├── components/            # 全局通用组件
│   │   ├── MyIcon/            # SVG 图标组件
│   │   ├── MyCard/            # 卡片组件
│   │   └── auto-imports.d.ts  # 自动生成的类型声明
│   ├── module/                # 业务模块目录（核心特色）
│   │   ├── UserManage/        # 用户管理模块
│   │   │   ├── api/           # 模块 API
│   │   │   ├── assets/        # 模块专属资源
│   │   │   ├── router/        # 模块路由配置
│   │   │   └── views/         # 模块页面
│   │   └── test/              # 测试模块
│   ├── pages/                 # 全局页面
│   │   ├── LoginPage.tsx      # 登录页
│   │   ├── BasicLayout/       # 基础布局组件
│   │   ├── UserManagementPage.tsx
│   │   ├── SettingsPage.tsx
│   │   └── IconExamplePage.tsx
│   ├── router/                # 路由配置
│   │   ├── routes.tsx         # 全局路由定义
│   │   ├── AppRouter.tsx      # 路由入口组件
│   │   ├── ProtectedRoute.tsx # 路由守卫
│   │   └── moduleRoutes.tsx   # 动态生成的模块路由（自动生成）
│   ├── store/                 # 状态管理
│   │   └── authStore.ts       # 认证状态（Zustand）
│   ├── styles/                # 全局样式
│   │   ├── index.scss         # 样式入口
│   │   ├── variables.scss     # SCSS 变量
│   │   └── antd-overrides.scss
│   ├── typings/               # TypeScript 类型定义
│   │   ├── router.d.ts        # 路由类型
│   │   ├── auto-imports-antd.d.ts
│   │   └── auto-imports-react.d.ts
│   ├── App.tsx                # 应用根组件
│   └── main.tsx               # 应用入口
├── dist/                      # 构建输出目录
├── vite.config.ts             # Vite 配置
├── tsconfig.json              # TypeScript 配置
└── package.json
```

### 🎯 模块化架构说明

项目采用**全局 + 模块**的混合架构：

- **全局部分** (`src/pages`, `src/components`)：所有模块共享的页面和组件
- **模块部分** (`src/module/`)：按业务划分的独立模块，每个模块包含自己的路由、页面、API、资源

#### 模块开发流程

1. 在 `src/module/` 下创建新模块目录
2. 模块标准结构：
   ```
   ModuleName/
   ├── api/          # 该模块的 API 请求
   ├── assets/       # 该模块专属图标、图片
   ├── router/
   │   └── routes.tsx  # 模块路由配置
   └── views/        # 模块页面组件
   ```
3. 在 `routes.tsx` 中配置路由，系统会自动加载

#### 模块启动优化

开发时可通过环境变量按需加载模块，提升开发速度：

```bash
# 仅加载 UserManage 模块
MODULE_NAME=UserManage npm run dev

# 或
npm run dev:UserManage
```

## 🗺️ 路由说明

### 路由配置结构

路由采用集中式配置管理，支持以下特性：
- 懒加载（`React.lazy`）
- 路由守卫（`protected: true`）
- 菜单自动生成（`menuItem` 配置）
- 多级嵌套（支持 5 级菜单）
- 隐藏路由（`hidden: true`）
- 重定向（`redirect`）

### 路由配置示例

```typescript
{
  path: "users",
  name: "用户管理",
  element: <UserManagementPage />,
  protected: true,        // 需要登录
  menuItem: {             // 菜单配置
    key: "users",
    icon: <UserOutlined />,
    label: "用户管理",
  },
}
```

### 核心路由

| 路径 | 说明 | 权限 |
|------|------|------|
| `/` | 重定向到登录页 | 公开 |
| `/login` | 登录页面 | 公开 |
| `/home` | 后台布局容器 | 需登录 |
| `/home/users` | 用户管理 | 需登录 |
| `/home/icon-example` | 图标示例 | 需登录 |
| `/home/settings/basic/profile/avatar/preview` | 五级菜单示例 | 需登录 |
| `/home/DashboardPage` | 模块路由示例 | 需登录 |
| `*` | 404 页面 | 公开 |

## 🎨 布局说明

### 经典三栏布局

```
┌─────────────────────────────────────────┐
│            Header（顶部导航栏）           │
│  [折叠按钮]              [用户信息 消息]  │
├──────────┬──────────────────────────────┤
│          │                              │
│  Sider   │         Content              │
│ (侧边栏)  │      （内容区域，可滚动）      │
│          │        <Outlet />            │
│  - Logo  │                              │
│  - 菜单  │                              │
│          │                              │
└──────────┴──────────────────────────────┘
```

### 布局特性

- **Header**：固定高度，包含折叠按钮、用户信息、消息通知、退出登录
- **Sider**：可折叠，深色主题，支持多级菜单，自动高亮当前路由
- **Content**：仅内容区域滚动，通过 `<Outlet />` 渲染子路由

### 菜单系统

- 自动从路由配置生成（基于 `menuItem` 字段）
- 支持递归多级嵌套
- 自动匹配当前路由高亮
- 点击菜单自动导航

## 🔧 核心插件说明

### 1. 动态路由生成插件 (dynamic-route-generator)

**功能**：根据环境变量 `MODULE_NAME` 动态生成模块路由文件

**工作原理**：
1. 扫描 `src/module/` 目录下所有模块
2. 根据 `MODULE_NAME` 环境变量过滤模块
3. 自动生成 `src/router/moduleRoutes.tsx`
4. 监听文件变化，自动重新生成（带防抖）

**使用场景**：
- 开发时按需加载模块，提升构建速度
- 生产环境按模块打包，减小体积

### 2. 组件自动导入插件 (auto-import)

**功能**：自动扫描 `src/components/` 目录，全局注册组件

**工作原理**：
1. 扫描 `components/` 下所有文件夹
2. 查找 `index.tsx` 或同名 `.tsx` 文件
3. 自动生成类型声明文件 `auto-imports.d.ts`
4. 监听文件变化，热更新类型声明

**使用方式**：
```tsx
// 无需 import，直接使用
<MyCard title="标题">内容</MyCard>
<MyIcon name="check" size={24} />
```

### 3. Ant Design & React 自动导入

通过 `unplugin-auto-import` 实现：
- React Hooks 自动导入（`useState`, `useEffect` 等）
- React Router Hooks 自动导入（`useNavigate`, `useLocation` 等）
- Ant Design 组件自动导入（`Button`, `Modal` 等）
- Zustand Store 自动导入（`useAuthStore`）

## 💡 开发指南

### 添加新页面（全局）

1. 在 `src/pages/` 创建页面组件
2. 在 `src/router/routes.tsx` 中添加路由配置
3. 配置 `menuItem` 即可自动显示在菜单中

### 创建新业务模块

1. 在 `src/module/` 下创建模块目录：
```bash
mkdir -p src/module/ModuleName/{api,assets/icons,router,views}
```

2. 创建路由配置文件 `src/module/ModuleName/router/routes.tsx`：
```typescript
import React from "react"
import type { RouteConfig } from "@/typings/router"
import { EyeOutlined } from "@ant-design/icons"

export const routes: RouteConfig[] = [
  {
    path: "/MyPage",
    name: "我的页面",
    element: React.createElement(React.lazy(() => import("../views/MyPage"))),
    menuItem: {
      key: "MyPage",
      icon: <EyeOutlined />,
      label: "我的页面",
    },
  },
]
```

3. 创建页面组件 `src/module/ModuleName/views/MyPage.tsx`

4. 启动模块：
```bash
npm run dev:ModuleName
```

### 添加全局组件

1. 在 `src/components/` 下创建组件目录：
```
MyComponent/
├── index.tsx      # 组件实现
└── index.scss     # 组件样式（可选）
```

2. 组件会自动注册，无需手动 import

3. 在任意页面使用：
```tsx
<MyComponent prop1="value1" />
```

### 添加 SVG 图标

1. 将 SVG 文件放入 `src/assets/icons/`（全局）或 `src/module/ModuleName/assets/icons/`（模块专属）

2. 使用 `MyIcon` 组件：
```tsx
<MyIcon name="my-icon" size={24} color="red" />
```

> 注意：`name` 为文件名（不含 `.svg`），路径分隔符会自动转换为 `-`

## 🛠️ 开发建议

### 文件命名规范
- 组件文件：PascalCase（如 `LoginPage.tsx`）
- 样式文件：与组件同名（如 `LoginPage.scss`）
- 工具文件：camelCase（如 `authStore.ts`）
- 模块目录：PascalCase（如 `UserManage`）

### 目录组织原则
- **按功能模块组织**：全局页面、模块页面分离
- **组件与样式同目录**：TSX 和 SCSS 放在同一目录
- **模块独立性**：每个模块包含完整的路由、页面、API、资源

### 代码风格
- 使用 TypeScript 严格模式
- 遵循 React Hooks 最佳实践
- 使用 ESLint 统一代码格式
- 组件使用函数式组件 + TypeScript 类型定义

### 性能优化
- 路由级懒加载（`React.lazy`）
- 按需加载模块（`MODULE_NAME` 环境变量）
- SVG 图标缓存（`vite-plugin-svg-icons`）
- 构建产物按类型分类输出（JS/CSS/Images/Fonts）

## 📝 License

MIT

## 👨‍💻 作者

- **GyYu** - tj_ygy@163.com

## 📅 创建日期

2026-04-03