# react-pc-template

**Repository Path**: mj-project/react-pc-template

## Basic Information

- **Project Name**: react-pc-template
- **Description**: PC端后台管理项目模板 - React18版
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 7
- **Forks**: 4
- **Created**: 2024-11-07
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: TypeScript, React, Ant-Design, zustand, admin

## README

# React PC Template 后台管理模板

一个基于 `Vite + React + TypeScript + Ant Design` 的 PC 端后台管理模板，已经内置登录页、布局框架、动态菜单、路由守卫、主题切换、权限控制、Mock 数据、图表首页、系统管理和表格示例，适合直接作为中后台项目的起点。

## 项目概览

- 构建工具：`Vite 5`
- 核心框架：`React 18`
- 语言：`TypeScript`
- UI 组件库：`Ant Design 5`
- 状态管理：`Zustand`
- 请求工具：`Axios`
- 样式方案：`SCSS`
- 图表：`@ant-design/charts`
- 本地假数据：`vite-plugin-mock-dev-server + mockjs`

## 当前已包含的能力

- 登录页与登录态校验
- 后台布局框架
- 左侧菜单与顶部导航
- 动态路由与路由守卫
- 前端静态路由 / 后端动态路由切换
- 主题切换
- 多页签、页面缓存和页面刷新
- 布局偏好、主题色、紧凑模式和色弱模式
- 通知中心、个人中心和轻量中英文切换
- 首页图表看板示例，并支持看板显示与顺序配置
- 基础表格、表单表格、用户管理表格示例
- 系统用户、角色、菜单、登录日志和操作日志示例
- 按角色和权限码控制路由、菜单与按钮
- Token 过期自动刷新、操作日志和前端异常上报
- 403 / 404 异常页
- SVG 图标自动注册
- Vitest 单元测试、React Testing Library 组件测试、Playwright 端到端测试和 GitHub Actions CI

## 运行截图

![登录页面](src/assets/doc/login_page.png)

![Home页面](src/assets/doc/home_page.png)

![表格页面1](src/assets/doc/table_page1.png)

![表格页面2](src/assets/doc/table_page2.png)

## 快速开始

### 1. 安装依赖

推荐使用 `pnpm`，因为仓库里已经包含 `pnpm-lock.yaml`。

```bash
pnpm install
```

如果本机没有全局 `pnpm`，也可以这样执行：

```bash
npx pnpm install
```

### 2. 启动开发环境

```bash
pnpm dev
```

默认会启动在 `http://localhost:3000`。

### 3. 构建生产包

```bash
pnpm build
```

### 4. 本地预览构建结果

```bash
pnpm preview
```

### 5. 代码检查

```bash
pnpm lint
```

### 6. 自动化测试

```bash
pnpm test
pnpm test:e2e
```

## 默认登录信息

开发环境默认启用了本地 Mock，可以直接使用下面的账号登录：

- 用户名：`admin`
- 密码：`123456`

普通用户账号可用于验证权限受限场景：

- 用户名：`user`
- 密码：`123456`

对应的登录模拟接口在 [mock/login.mock.ts](mock/login.mock.ts)。

## 环境变量说明

开发环境配置在 [.env.development](.env.development)，生产环境配置在 [.env.production](.env.production)。

当前主要用到这些变量：

- `VITE_BASE_API`：接口基础地址
- `VITE_MOCK`：是否启用本地 Mock
- `VITE_USE_FRONT_ROUTE`：是否使用前端静态路由

## 路由机制

这个项目同时支持两套路由来源：

### 1. 前端静态路由

当 `VITE_USE_FRONT_ROUTE = true` 时，菜单和页面来自 [src/router/frontEnd.ts](src/router/frontEnd.ts)。

### 2. 后端动态路由

当 `VITE_USE_FRONT_ROUTE = false` 时，项目会调用 [src/api/route.ts](src/api/route.ts) 获取路由数据，再交给 [src/router/index.tsx](src/router/index.tsx) 动态生成页面。

路由守卫逻辑在 [src/router/authRoutes.tsx](src/router/authRoutes.tsx)。

## Mock 与接口说明

Mock 文件位于 [mock](mock) 目录，当前主要包含：

- 登录接口
- Token 刷新接口
- 后端路由接口
- 用户列表和用户角色接口
- 用户信息接口
- 系统用户、角色、菜单接口
- 登录日志、操作日志和前端异常日志接口

统一请求封装在 [src/utils/request.ts](src/utils/request.ts)，已经处理了：

- 请求基础地址
- Token 自动携带
- Token 过期自动刷新
- 未登录强制退出
- 常见请求错误提示
- 操作日志和接口异常上报

## 目录结构

```text
react-pc-template
├─ mock                 # 本地 Mock 接口
├─ docs                 # 开发指南、发布清单和项目分析文档
├─ e2e                  # Playwright 端到端测试
├─ public               # 静态资源
├─ src
│  ├─ api               # 接口调用封装
│  ├─ assets            # 图片、图标、说明截图
│  ├─ components        # 通用组件
│  ├─ layout            # 后台整体布局
│  ├─ router            # 路由配置与守卫
│  ├─ store             # Zustand 状态
│  ├─ styles            # 全局样式与主题
│  ├─ types             # 类型声明
│  ├─ utils             # 工具函数与请求封装
│  └─ views             # 页面视图
├─ .env.development     # 开发环境变量
├─ .env.production      # 生产环境变量
├─ vite.config.ts       # Vite 配置
└─ package.json         # 脚本与依赖
```

## 关键文件说明

- [src/main.tsx](src/main.tsx)：应用入口
- [src/App.tsx](src/App.tsx)：全局主题、语言、路由挂载
- [src/layout/layout.tsx](src/layout/layout.tsx)：后台主布局
- [src/store/route.ts](src/store/route.ts)：菜单与路由数据来源切换
- [src/store/experience.ts](src/store/experience.ts)：多页签、布局偏好、通知和首页看板配置
- [src/utils/permission.ts](src/utils/permission.ts)：角色与权限码判断
- [src/utils/observability.ts](src/utils/observability.ts)：操作日志、页面访问和前端异常上报
- [src/views/Login/index.tsx](src/views/Login/index.tsx)：登录页
- [src/views/Home/index.tsx](src/views/Home/index.tsx)：首页看板
- [src/views/Tables/UserTable.tsx](src/views/Tables/UserTable.tsx)：表格综合示例
- [src/views/System](src/views/System)：系统管理示例页

## 常见开发入口

### 新增页面

1. 在 `src/views` 下新增页面文件
2. 如果走前端静态路由，在 `src/router/frontEnd.ts` 里补菜单和路由项
3. 如果走后端动态路由，保证后端或 Mock 返回的 `element` 能匹配到页面路径
4. 如果需要菜单缓存、固定标签或权限控制，同步配置 `meta.keepAlive`、`meta.affix`、`meta.permission` 或 `meta.roles`

### 新增接口

1. 在 `src/api` 下新增接口函数
2. 统一复用 `src/utils/request.ts`
3. 开发阶段如果需要假数据，在 `mock` 目录补对应 Mock

### 新增权限按钮

1. 优先使用 [src/components/PermissionButton](src/components/PermissionButton)
2. 权限码建议使用 `模块:资源:动作` 格式，例如 `system:user:create`
3. 路由访问权限写在路由 `meta.permission` 或 `meta.roles` 中

### 新增全局状态

1. 在 `src/store` 下新增 store
2. 页面或组件按需订阅，避免不必要的整仓订阅

## 当前已知情况

- 项目使用 `HashRouter`
- `vite.config.ts` 中默认开启了 Mock 插件
- 生产构建时会移除 `console.log`、`console.warn`、`console.info`
- 构建产物会按依赖包拆分到 `assets/js`
- 默认开发端口是 `3000`
- CI 会依次执行 `pnpm lint`、`pnpm test`、`pnpm test:e2e` 和 `pnpm build`
- 仓库当前更适合使用 `pnpm`，不要额外提交 `package-lock.json`

## 后续扩展建议

- 接入真实登录与刷新 Token 逻辑
- 将示例表格替换成真实业务页
- 按业务模块继续拆分 `views` 与 `api`
- 将通知中心、操作日志和前端异常日志接入真实后端

## 更新记录

- 2024-11-21：对表格相关组件做进一步优化以及功能扩充，新增用户管理页面
- 2024-11-15：添加了按钮颜色扩充组件、表格组件、条件搜索表单组件、弹窗表单组件
- 2026-04-23：补充项目现状说明、目录结构、运行方式、路由机制、Mock 说明与开发指引
- 2026-04-30：同步多页签、页面缓存、系统管理、权限控制、日志上报、自动化测试和 CI 现状