# react19-admin

**Repository Path**: copperpeas/react19-admin

## Basic Information

- **Project Name**: react19-admin
- **Description**: React 19 + React Router 7+ Vite 6 + Redux Toolkit + Ant Design 6 + TypeScript
- **Primary Language**: TypeScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-13
- **Last Updated**: 2026-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# React19Admin

基于 React 19 + TypeScript 的后台管理系统脚手架，已包含登录、路由鉴权、固定式后台布局和总览工作台，可继续扩展订单、客户、分析等业务模块。

## 技术栈

| 技术 | 版本 | 用途 |
| --- | --- | --- |
| React | 19 | 页面组件和交互逻辑 |
| TypeScript | 7 | 类型安全和工程约束 |
| Vite | 7 | 开发服务器和生产构建 |
| Redux Toolkit | 2 | 全局状态管理 |
| React Redux | 9 | Redux 与 React 组件连接 |
| React Router DOM | 7 | 路由配置、嵌套路由和鉴权跳转 |
| Ant Design | 6 | 表单、布局、菜单、表格、进度等后台组件 |
| Lucide React | 0.468 | 界面图标 |
| ECharts | 6 | 数据可视化和业务图表绘制 |
| echarts-for-react | 3 | ECharts React 组件封装 |
| Axios | 1 | HTTP 请求封装和接口调用 |
| CSS | 原生 CSS | 主题、布局、响应式和细节样式 |

项目不使用 Tailwind CSS 或 shadcn/ui，样式集中维护在 `src/styles.css` 和 `src/alignment.css`。

## 当前功能

### 登录和鉴权

- 登录邮箱和密码表单校验
- 模拟后台登录接口返回用户对象和 token
- 用户信息存储在 Redux `auth` slice
- 未登录访问后台路由自动跳转到 `/login`
- `/login` 是公开白名单路由
- 已登录访问 `/login` 自动跳转到 `/admin/overview`
- 退出登录清除用户信息和 token

模拟登录返回的数据结构：

```ts
{
  token: string
  name: string
  email: string
  avatar: string
  role: string
}
```

### 后台布局

- 左侧菜单固定在视口左侧
- 右侧顶部 Header 固定
- 只有右侧内容区出现滚动条
- 菜单基于路由状态高亮
- 顶部用户名称、头像和角色从 Redux store 读取
- Header 高度通过 `--admin-header-height` 统一控制

### 页面和路由

| 路径 | 页面 |
| --- | --- |
| `/login` | 登录页 |
| `/admin/overview` | 总览工作台 |
| `/admin/orders` | 订单管理模块页 |
| `/admin/customers` | 客户中心模块页 |
| `/admin/analytics` | 数据分析模块页 |
| `/admin/settings` | 系统设置模块页 |

总览页包含经营统计卡片、ECharts 营收趋势图、目标进度和最近订单。其他模块已完成路由接入，页面内容可继续替换为实际业务功能。

## 项目结构

```text
.
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
└── src/
    ├── App.tsx                 # RouterProvider 入口
    ├── main.tsx                # React、Redux、Ant Design 初始化
    ├── router.tsx              # 路由、白名单和鉴权守卫
    ├── store/
    │   ├── index.ts            # Redux store 入口和类型导出
    │   └── authSlice.ts        # 登录用户和 token 状态模块
    ├── api/
    │   ├── index.ts             # API 统一导出
    │   ├── http.ts              # Axios 实例、拦截器和通用请求方法
    │   └── auth.ts              # 登录、当前用户和退出接口
    ├── vite-env.d.ts           # Vite 类型声明
    ├── layouts/
    │   └── AdminLayout.tsx     # 固定式后台布局和左侧菜单
    ├── pages/
    │   ├── LoginPage.tsx       # 登录页和模拟登录
    │   ├── OverviewPage.tsx    # 总览工作台
    │   └── ModulePage.tsx      # 通用业务模块页
    ├── components/             # 自定义开发组件（可复用 UI，不耦合业务接口）
    │   └── demo.StatCard.tsx   # 示例组件（demo 模板，可替换为真实组件）
    ├── services/               # 复杂页面的业务服务（编排 api、数据加工，不含全局状态）
    │   └── demo.orderService.ts # 示例服务（demo 模板，可替换为真实业务服务）
    ├── i18n/                   # 国际化（见「国际化」章节）
    ├── utils/                  # 工具与全局通信
    │   └── eventBus.ts         # 基于 mitt 的 EventBus 单例、事件类型表与初始化
    ├── styles.css              # 全局主题和页面样式
    └── alignment.css           # 输入框和布局覆盖样式
```

## 安装和运行

环境要求：Node.js 20.19+ 或 22.12+（Vite 7 已不再支持 Node 18）。

环境变量统一放在根目录 `env/`：

```text
env/
├── .env.dev    # 本地开发
├── .env.test   # 测试环境
└── .env.pro    # 生产环境
```

```bash
npm install
npm run dev
```

默认开发命令使用 `env/.env.dev`。其他环境命令：

```bash
npm run dev:test    # 使用 env/.env.test 启动开发服务
npm run build:test  # 使用 env/.env.test 构建
npm run build       # 使用 env/.env.pro 构建生产版本
```

访问：`http://localhost:5173`

登录时使用任意有效邮箱和非空密码即可进入后台。

## 开发环境 API 代理

开发环境请求统一使用 `/api` 前缀，例如：

```ts
http.get('/orders')
```

Vite 会根据当前 mode 从 `env/` 加载对应文件，并将 `/api/*` 请求代理到 `VITE_API_PROXY_TARGET`：

```env
VITE_API_BASE_URL=/api
VITE_API_PROXY_TARGET=http://localhost:8080
```

代理配置位于 `vite.config.ts` 的 `server.proxy`。修改 `env/.env.*` 后需要重启开发服务器。

## 国际化（i18n）

项目使用 `i18next` + `react-i18next` 提供多语言支持，语言包位于 `src/i18n/locales/`：

- `zh.ts`：简体中文（默认）
- `en.ts`：English

入口在 `src/i18n/index.ts`，通过 `i18next-browser-languagedetector` 按 `localStorage`（键名 `nebula-lang`）持久化语言选择，并同步切换 Ant Design 的 `ConfigProvider` locale。

在组件中使用：

```tsx
import { useTranslation } from 'react-i18next'

const { t } = useTranslation()
return <span>{t('menu.overview')}</span>
```

顶栏的 `LanguageSwitcher` 组件可在运行时切换语言。新增语言时，在 `locales/` 下增加对应语言包，并在 `src/i18n/index.ts` 的 `SUPPORTED_LANGUAGES` 与 `resources` 中登记即可。

## 类型检查和构建

执行 TypeScript 类型检查：

```bash
npx tsc --noEmit
```

构建生产版本：

```bash
npm run build
```

预览生产构建：

```bash
npm run preview
```

## 开发约定

- 新增页面优先使用 `.tsx`，状态和工具模块使用 `.ts`
- 新增后台模块时，在 `src/router.tsx` 注册路由
- 页面公共壳层和菜单逻辑放在 `AdminLayout.tsx`
- 业务状态统一通过 Redux Toolkit slice 管理
- 真实登录接口接入时，用接口返回的用户对象替换 `LoginPage.tsx` 中的 `mockLogin`
- 接口请求统一放在 `src/api`，通过 `VITE_API_BASE_URL` 配置后端地址
- 新增菜单项时，同时配置菜单项和对应路由