React App

基于 React 19 + Ant Design 6 的企业级后台管理系统。

技术栈

类别	技术
框架	React 19 + TypeScript 6
构建	Vite 8
UI	Ant Design 6
状态管理	Zustand 5 + TanStack React Query 5
路由	React Router 7
HTTP	Axios
测试	Vitest + React Testing Library + Playwright
代码规范	Oxlint + Prettier
Git 钩子	husky + lint-staged
Docker	多阶段构建 + docker-compose
类型生成	swagger.json → TypeScript

页面功能

页面	功能
登录 / 注册	账号密码登录、新用户注册、账号注销
仪表盘	系统概览（占位）
用户管理	用户 CRUD、角色分配、密码重置、权限控制
角色管理	角色 CRUD、权限分配、权限列表查看
菜单管理	菜单树 CRUD、排序
个人中心	个人资料查看

快速开始

环境要求

• Node.js >= 22
• npm >= 10

安装

git clone "https://github.com/Gin4ever688/ReactApp"
cd ReactApp
npm install

开发

npm run dev

启动后访问 http://localhost:3000。需确保后端 API 在 http://localhost:8000 运行。

构建

npm run build

构建产物输出到 dist/。

脚本说明

命令	说明
npm run dev	启动开发服务器（热更新）
npm run build	TypeScript 类型检查 + 生产构建
npm run lint	运行 oxlint 代码检查
npm run preview	本地预览构建产物
npm test	启动单元测试（监听模式）
npm run test:run	跑一次单元测试（CI 用）
npm run test:e2e	运行 Playwright E2E 测试
npm run generate:types	从 swagger.json 重新生成 TypeScript 类型

项目结构

src/
  api/              API 接口层 (axios + 类型定义)
    generated.ts    从 swagger.json 自动生成的类型
    types.ts        通用类型 + 生成类型的 re-export
    request.ts      axios 实例 + HTTP 拦截器
  components/       公共组件
    ErrorBoundary.tsx  错误边界
  layouts/          布局组件
  pages/            页面
    system/          系统管理模块
  stores/           Zustand 状态管理
  utils/            工具函数
    permission.ts    权限校验
  __tests__/        单元测试
  test/             测试配置
e2e/                E2E 测试 (Playwright)
scripts/
  generate-types.js  swagger → TypeScript 生成脚本

类型生成

本项目的 TypeScript 类型由后端 swagger.json 自动生成，保证前后端类型一致。

# 1. 把后端最新的 swagger.json 放到项目根目录
# 2. 运行
npm run generate:types

生成的文件在 src/api/generated.ts。部分后端未在 swagger 中定义的字段（如 SystemRole.permissions）在 types.ts 中手动扩展。

Docker 部署

方式一：docker-compose（推荐）

docker compose up -d --build

访问 http://localhost:81。

方式二：手动构建

docker build -t react-app .
docker run -d -p 81:80 --name react-app react-app

详细说明见 DOCKER.md。

测试

单元测试

npm run test:run

覆盖工具函数（permission.ts）和公共组件（ErrorBoundary）。

E2E 测试

npx playwright install chromium
npm run test:e2e

需先启动开发服务器 + 后端。

代码规范

• Prettier：保存时自动格式化代码
• Oxlint：提交前自动检查代码规范
• husky + lint-staged：git commit 时自动对暂存文件执行格式化 + 检查

---

MIT