# react-admin-template

**Repository Path**: mic-HAO/react-admin-template

## Basic Information

- **Project Name**: react-admin-template
- **Description**: 基于 React 19 + TypeScript + Ant Design 6 + Vite 8 的企业级后台管理系统模板。内置完整的权限管理、Mock 数据、路由守卫等能力，开箱即用。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-04-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# React Admin Template

[English](./README.en.md) | 中文

基于 React 19 + TypeScript + Ant Design 6 + Vite 8 的企业级后台管理系统模板。内置完整的权限管理、Mock 数据、路由守卫等能力，开箱即用。

## 技术栈

| 类别 | 技术 | 版本 |
| --- | --- | --- |
| 框架 | React | 19 |
| 语言 | TypeScript | 6 |
| 构建工具 | Vite | 8 |
| UI 组件库 | Ant Design | 6 |
| 路由 | React Router | 7 |
| 状态管理 | Zustand | 5 |
| HTTP 请求 | Axios | 1.x |
| 图表 | @ant-design/charts | 2.x |
| Mock | MSW (Mock Service Worker) | 2.x |
| 代码规范 | ESLint + Prettier + Husky + lint-staged + commitlint | - |

## 功能特性

- **用户认证** - 登录 / 登出 / Token 管理 / 自动刷新用户信息
- **权限控制** - 基于权限字符串的路由守卫 + 按钮级权限组件 (`PermissionGuard`、`AuthButton`)
- **布局系统** - 可折叠侧边栏 + 顶部导航栏 + 面包屑 + 用户下拉菜单
- **数据面板** - Dashboard 统计卡片 + 图表面板（访问趋势、分类销售）
- **用户管理** - 完整 CRUD（列表搜索、分页、新增、编辑、删除）
- **异常页面** - 403 / 404 页面
- **Mock 数据** - MSW 拦截，开发环境自动启用，生产环境自动关闭
- **Axios 封装** - 统一请求/响应拦截、Token 注入、401 自动跳转
- **代码规范** - ESLint + Prettier + Husky pre-commit + commitlint 提交校验
- **路由懒加载** - 基于 `React.lazy` + `Suspense` 的按需加载

## 项目结构

```
src/
├── api/                    # API 请求模块
│   ├── index.ts            #   Axios 实例 & 拦截器
│   ├── auth.ts             #   认证相关接口
│   ├── dashboard.ts        #   Dashboard 接口
│   └── user.ts             #   用户管理接口
├── assets/styles/          # 全局样式
├── components/             # 通用组件
│   ├── AuthButton/         #   权限按钮
│   ├── PageContainer/      #   页面容器
│   ├── PermissionGuard/    #   权限守卫
│   └── SearchForm/         #   搜索表单
├── config/                 # 应用配置
├── hooks/                  # 自定义 Hooks
│   ├── usePagination.ts    #   分页逻辑
│   └── usePermission.ts    #   权限判断
├── layouts/                # 布局组件
│   ├── BasicLayout/        #   后台主布局（侧边栏 + 顶栏 + 内容区）
│   ├── BlankLayout/        #   空白布局（登录页等）
│   └── components/         #   布局子组件（Header / Sidebar / Breadcrumb / UserDropdown）
├── mocks/                  # MSW Mock 数据
│   ├── browser.ts          #   Worker 初始化
│   ├── data/               #   Mock 数据源
│   └── handlers/           #   请求处理器（auth / dashboard / user）
├── pages/                  # 页面
│   ├── dashboard/          #   仪表盘
│   ├── exception/          #   403 / 404
│   ├── login/              #   登录页
│   └── user/list/          #   用户管理
├── router/                 # 路由
│   ├── index.tsx           #   路由实例
│   ├── routes.tsx          #   路由表
│   ├── AuthRoute.tsx       #   认证路由守卫
│   └── lazyLoad.tsx        #   懒加载工具
├── stores/                 # Zustand 状态管理
│   ├── useAuthStore.ts     #   认证状态
│   └── useAppStore.ts      #   应用状态（侧边栏折叠等）
├── types/                  # TypeScript 类型定义
├── utils/                  # 工具函数
│   ├── auth.ts             #   Token 操作
│   └── storage.ts          #   LocalStorage 封装
├── App.tsx                 # 应用根组件
└── main.tsx                # 入口文件
```

## 快速开始

### 环境要求

- Node.js >= 18
- pnpm / npm / yarn

### 安装依赖

```bash
npm install
```

### 启动开发服务器

```bash
npm run dev
```

默认访问 http://localhost:3000，Mock 数据自动启用。

### Mock 账号

| 用户名 | 密码 |
| --- | --- |
| admin | admin123 |

### 生产构建

```bash
npm run build
```

构建产物输出到 `dist/` 目录。

### 预览构建产物

```bash
npm run preview
```

## 可用脚本

| 命令 | 说明 |
| --- | --- |
| `npm run dev` | 启动开发服务器 |
| `npm run build` | TypeScript 编译 + 生产构建 |
| `npm run preview` | 预览构建产物 |
| `npm run lint` | ESLint 检查 |
| `npm run lint:fix` | ESLint 自动修复 |
| `npm run format` | Prettier 格式化 |

## 环境变量

| 变量 | 说明 | 开发默认值 | 生产默认值 |
| --- | --- | --- | --- |
| `VITE_APP_TITLE` | 应用标题 | React Admin Template | React Admin Template |
| `VITE_API_BASE_URL` | API 基础路径 | /api | /api |
| `VITE_ENABLE_MOCK` | 是否启用 Mock | true | false |

## API 代理

开发环境下，`/api` 前缀的请求会被代理到 `http://localhost:8080`，可在 `vite.config.ts` 中修改：

```ts
proxy: {
  '/api': {
    target: 'http://localhost:8080',
    changeOrigin: true,
  },
},
```

## Git 规范

项目集成了 Husky + lint-staged + commitlint：

- **pre-commit** - 自动对暂存文件执行 ESLint 修复和 Prettier 格式化
- **commit-msg** - 校验提交信息是否符合 [Conventional Commits](https://www.conventionalcommits.org/) 规范

提交示例：

```bash
git commit -m "feat: add user management page"
git commit -m "fix: resolve login redirect issue"
```

## License

MIT