# minimal-eagle-web

**Repository Path**: sunjones/minimal-eagle-web

## Basic Information

- **Project Name**: minimal-eagle-web
- **Description**: elagle-cloud 的web端
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-16
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ELEGANTEER WEB

基于 React + Vite + TypeScript 的现代化前端管理后台模板。

## 技术栈

- **构建工具**: Vite 8 + TypeScript 6
- **UI 框架**: React 19 + MUI 9 (Material UI)
- **路由**: React Router 7
- **状态管理**: Redux Toolkit (RTK Query)
- **表单**: React Hook Form + Zod
- **HTTP**: Axios
- **国际化**: i18next + react-i18next
- **动画**: Framer Motion
- **认证**: OAuth2 Authorization Code + PKCE

## 环境要求

- Node.js >= 20
- Yarn >= 4 (推荐) 或 npm

## 快速开始

### 1. 安装依赖

```bash
# 使用 Yarn (推荐)
yarn install

# 或使用 npm
npm install
```

### 2. 配置环境变量

复制 `.env` 文件并根据实际情况修改：

```bash
cp .env .env.local
```

默认环境变量：

```env
VITE_SERVER_URL=/api              # 后端 API 基础地址
VITE_OAUTH2_CLIENT_ID=eagleWeb    # OAuth2 客户端 ID
VITE_OAUTH2_SCOPE=openid profile phone email address  # OAuth2 授权范围
```

### 3. 启动开发服务器

```bash
# 使用 Yarn
yarn dev

# 或使用 npm
npm run dev
```

开发服务器默认运行在 http://localhost:8080

## 常用命令

```bash
# 开发
yarn dev              # 启动开发服务器 (端口 8080)
yarn build            # 构建生产环境 (先执行 tsc 类型检查，再 vite build)

# 代码质量
yarn lint             # ESLint 检查
yarn lint:fix         # ESLint 自动修复
yarn fm:check         # Prettier 格式检查
yarn fm:fix           # Prettier 格式化
yarn fix:all          # 同时执行 lint:fix 和 fm:fix
yarn tsc:watch        # TypeScript 实时类型检查

# 测试
yarn test             # 运行测试 (Vitest)
yarn test:run         # 运行测试一次
yarn test:coverage    # 生成测试覆盖率报告
yarn test:e2e         # 运行 Playwright E2E 测试
yarn test:e2e:local   # 使用 .env.e2e.local 运行本地 E2E 测试
yarn test:e2e:ui      # 以 UI 模式运行 Playwright E2E 测试
yarn test:e2e:headed  # 以有头浏览器运行 Playwright E2E 测试

# 清理与重装
yarn clean            # 删除 node_modules、dist 等
yarn re:dev           # 清理、重装依赖、启动开发
yarn re:build         # 清理、重装依赖、构建
```

## Playwright E2E 测试

项目已接入 Playwright，E2E 测试文件位于 `tests/e2e/`，配置文件为 `playwright.config.ts`。

首次运行前安装浏览器：

```bash
yarn playwright install chromium
```

认证后的业务用例需要先提供测试账号。Playwright 会自动读取 `.env.e2e.local`，通过 OAuth2 登录，并把登录态保存到 `tests/e2e/.auth/user.json`。

首次本地运行前创建环境变量文件：

```bash
cp .env.e2e.example .env.e2e.local
```

然后填写：

```dotenv
E2E_USERNAME=your_username
E2E_PASSWORD=your_password
```

运行所有 E2E 测试：

```bash
yarn test:e2e:local
```

调试测试：

```bash
# 打开 Playwright UI 模式
yarn test:e2e:ui

# 使用有头浏览器运行，便于观察页面行为
yarn test:e2e:headed
```

Playwright 会按配置自动启动 Vite 开发服务器，默认访问 `http://127.0.0.1:8080`。测试失败时会生成 `test-results/` 和 `playwright-report/`，这两个目录已加入 `.gitignore`。

当前 E2E 覆盖：

- 未登录认证页 smoke 测试
- 登录后 Dashboard、用户、角色、部门、字典、岗位、OAuth 客户端、日志和监控页面可达性
- 角色、部门、岗位、字典/字典项、OAuth 客户端、账号/用户的创建、查询、更新、状态切换和删除
- Dashboard、系统日志、在线用户、登录日志和 Actuator 监控接口读取

## 项目结构

```
src/
├── app.tsx           # 应用根组件，包含所有 Provider 嵌套
├── main.tsx          # 入口，配置 RouterProvider
├── global-config.ts  # 全局配置（OAuth2 客户端、服务端地址等）
├── routes/           # 路由配置
│   ├── sections/     # 路由定义（lazy load 页面）
│   ├── paths.ts      # 路径常量
│   └── hooks/        # 路由相关 hooks
├── auth/             # 认证系统
│   ├── context/oauth2/  # OAuth2 AuthProvider、PKCE、Token 管理
│   ├── guard/           # AuthGuard, GuestGuard, RoleBasedGuard
│   └── hooks/           # useAuthContext, useOAuth2
├── api/              # API 层
│   ├── axios.ts      # axios 实例（含 token 刷新拦截器）
│   ├── base-api.ts   # RTK Query baseApi
│   └── base-query.ts # axios 适配 RTK Query
├── store/            # Redux Store
│   └── slices/       # auth.slice 等
├── features/         # 功能模块（各管理页面的 api.ts、types.ts、页面组件）
├── layouts/          # 布局组件
│   ├── dashboard/    # Dashboard 布局（含侧边栏、导航）
│   ├── core/         # 布局基础组件
│   └── auth-split/   # 认证页面布局
├── theme/            # MUI 主题系统
├── components/       # 可复用组件
├── pages/            # 页面组件
├── locales/          # 国际化
└── lib/              # 工具函数
```

## 认证系统

本项目使用标准 OAuth2 Authorization Code + PKCE 流程：

1. 应用启动时通过 `/.well-known/oauth-authorization-server` 发现认证端点
2. 登录时跳转到发现的 `authorization_endpoint`，携带 PKCE code_challenge
3. 回调页面通过 `token_endpoint` 用 code 换 token
4. 用户信息通过 `/userinfo` 端点获取
5. Token 过期时通过 refresh_token 自动刷新，刷新失败则重新登录

### 认证守卫

- **AuthGuard**: 保护需要登录的路由
- **GuestGuard**: 仅限未登录用户访问（如登录页）
- **RoleBasedGuard**: 基于角色的访问控制

## 代理配置

开发服务器代理配置（`vite.config.ts`）：

- `/api/*` -> 转发到后端（去掉 `/api` 前缀）
- `/.well-known/*`, `/authorize`, `/oauth/*`, `/userinfo`, `/logout`, `/login`, `/connect/*` -> 直接转发到后端

## 注意事项

- 复制文件夹时请同时复制隐藏文件（如 `.env`），这些文件通常包含应用运行所需的关键环境变量
- 开发时如需跳过认证，可将 `src/global-config.ts` 中的 `auth.skip` 设为 `true`
- 推荐使用 yarn 作为包管理器

## 界面预览

### 用户管理页面

![用户管理页面](doc/启动登录后.png)

## 许可证

[MIT](LICENSE)