feat():learning后台管理前端页面初始化
This commit is contained in:
yuj
480
PROJECT_ARCHITECTURE.md
Normal file
480
PROJECT_ARCHITECTURE.md
Normal file
@@ -0,0 +1,480 @@
|
||||
# Goalfymax 管理后台项目架构概览
|
||||
|
||||
## 项目概述
|
||||
|
||||
这是一个基于 **React 18** + **Vite** + **Ant Design 5** + **React Router 7** 的现代管理后台应用。
|
||||
|
||||
- **技术栈**：React 18.3.1 + TypeScript + Vite 5.4.20 + Ant Design 5.27.4
|
||||
- **状态管理**：Jotai（原子状态管理）
|
||||
- **HTTP 客户端**：Axios 1.12.2
|
||||
- **日期处理**：Dayjs 1.11.18
|
||||
- **总文件数**：48 个 TypeScript/TSX 文件
|
||||
- **代码行数**：~7000+ 行代码
|
||||
|
||||
---
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
src/
|
||||
├── App.tsx # 主应用入口，定义静态路由
|
||||
├── main.tsx # Vite 应用入口点
|
||||
├── index.css # 全局样式
|
||||
├── App.css # 应用样式
|
||||
│
|
||||
├── atoms/ # 状态管理（Jotai 原子状态）
|
||||
│ └── auth.ts # 认证状态原子
|
||||
│
|
||||
├── components/ # 可复用 UI 组件
|
||||
│ ├── Layout.tsx # 主布局组件（侧边栏+主区域）
|
||||
│ ├── DynamicMenu.tsx # 动态菜单组件（权限感知）
|
||||
│ ├── DynamicMenu.css # 菜单样式
|
||||
│ ├── AuthGuard.tsx # 认证守卫组件
|
||||
│ ├── PermissionGuard.tsx # 权限守卫组件
|
||||
│ ├── PagePermissionGuard.tsx
|
||||
│ ├── QuotaCharts.tsx # 配额图表组件
|
||||
│ ├── QuotaRulesForm.tsx # 配额规则表单
|
||||
│ ├── QuotaRulesTable.tsx # 配额规则表格
|
||||
│ ├── QuotaHistoryTable.tsx # 配额历史表格
|
||||
│ ├── QuotaFilters.tsx # 配额过滤器
|
||||
│ ├── QuotaStats.tsx # 配额统计
|
||||
│ └── UserProjectQuotaPage.tsx
|
||||
│
|
||||
├── hooks/ # 自定义 React Hooks
|
||||
│ ├── useAuth.ts # 认证 Hook（登录、登出、Token 管理）
|
||||
│ ├── usePagePermissions.ts # 页面权限 Hook
|
||||
│ └── usePermissions.ts # 操作权限 Hook
|
||||
│
|
||||
├── pages/ # 页面组件
|
||||
│ ├── Dashboard.tsx # 仪表盘
|
||||
│ ├── Overview.tsx # 总览页
|
||||
│ ├── Operations.tsx # 运营页
|
||||
│ ├── Monitoring.tsx # 监控页
|
||||
│ ├── Finance.tsx # 财务页
|
||||
│ ├── SystemHealth.tsx # 系统健康
|
||||
│ ├── QuotaRules.tsx # 配额规则管理
|
||||
│ ├── UserProjectQuota.tsx # 用户项目配额管理
|
||||
│ ├── UserManagement.tsx # 系统用户管理
|
||||
│ ├── RoleManagement.tsx # 角色管理
|
||||
│ ├── GoalfyMaxUsers.tsx # GoalfyMax 用户管理
|
||||
│ ├── UserLevelConfigs.tsx # 用户等级配置管理
|
||||
│ ├── SystemConfigs.tsx # 系统配置管理
|
||||
│ ├── UserFeedback.tsx # 用户反馈管理
|
||||
│ ├── MessagePush.tsx # 消息推送管理
|
||||
│ ├── TokenHistory.tsx # Token 历史
|
||||
│ ├── TokenAnalytics.tsx # Token 分析
|
||||
│ ├── VendorModelPricing.tsx# 供应商模型价格管理
|
||||
│ └── ...
|
||||
│
|
||||
├── routes/ # 路由配置
|
||||
│ └── DynamicRoutes.tsx # 动态路由配置（基于权限的动态路由）
|
||||
│
|
||||
├── services/ # API 服务层
|
||||
│ ├── api.ts # 核心 API 客户端（ApiClient）+ API 服务导出
|
||||
│ ├── userLevelConfigApi.ts # 用户等级配置 API
|
||||
│ ├── systemConfigApi.ts # 系统配置 API
|
||||
│ ├── userApi.ts # 用户 API
|
||||
│ ├── roleApi.ts # 角色 API
|
||||
│ └── ...
|
||||
│
|
||||
├── types/ # TypeScript 类型定义
|
||||
│ ├── userLevelConfig.ts # 用户等级配置类型
|
||||
│ ├── systemConfig.ts # 系统配置类型
|
||||
│ ├── quota.ts # 配额类型
|
||||
│ ├── userProjectQuota.ts # 用户项目配额类型
|
||||
│ └── ...
|
||||
│
|
||||
├── utils/ # 工具函数
|
||||
│ └── storageMigration.ts # 存储迁移工具
|
||||
│
|
||||
└── assets/ # 静态资源
|
||||
└── react.svg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 核心架构设计
|
||||
|
||||
### 1. 路由设计
|
||||
|
||||
**双层路由系统**：
|
||||
|
||||
#### App.tsx 中的静态路由
|
||||
- 定义所有可用的路由路径
|
||||
- 组织模块化的路由结构（dashboard、operations、monitoring、system 等）
|
||||
|
||||
```typescript
|
||||
// 示例：系统管理路由
|
||||
<Route path="/system" element={<Navigate to="/system/quota-rules" replace />} />
|
||||
<Route path="/system/quota-rules" element={<QuotaRulesPage />} />
|
||||
<Route path="/system/user-management" element={<UserManagement />} />
|
||||
<Route path="/system/user-level-configs" element={<UserLevelConfigs />} />
|
||||
<Route path="/system/system-configs" element={<SystemConfigs />} />
|
||||
```
|
||||
|
||||
#### DynamicRoutes.tsx 中的权限感知路由
|
||||
- 根据用户权限动态显示/隐藏路由
|
||||
- 使用 `usePagePermissions()` hook 获取用户权限
|
||||
- 只挂载有权限访问的路由
|
||||
|
||||
### 2. 菜单系统
|
||||
|
||||
**DynamicMenu 组件**特点：
|
||||
- 权限感知的菜单项过滤
|
||||
- 支持一级和二级菜单
|
||||
- 自动同步当前路由位置
|
||||
- 详细的权限检查日志
|
||||
|
||||
核心逻辑：
|
||||
```typescript
|
||||
const filterAccessibleMenus = (items: MenuItem[]): MenuItem[] => {
|
||||
// 1. 仪表盘始终显示
|
||||
// 2. 父级菜单权限检查（如 /system、/operations）
|
||||
// 3. 单个菜单项权限检查
|
||||
// 4. 返回过滤后的菜单项
|
||||
}
|
||||
```
|
||||
|
||||
### 3. API 调用模式
|
||||
|
||||
**分层结构**：
|
||||
|
||||
```
|
||||
UI 组件
|
||||
↓
|
||||
Custom Hook (useXxx)
|
||||
↓
|
||||
API Service (xxxApi.ts)
|
||||
↓
|
||||
ApiClient (api.ts)
|
||||
↓
|
||||
Axios 实例 + 拦截器
|
||||
↓
|
||||
后端 API
|
||||
```
|
||||
|
||||
#### ApiClient 类特性
|
||||
- **自动 Token 管理**：请求自动附加 Authorization 头
|
||||
- **Token 刷新机制**：401 错误时自动刷新 token
|
||||
- **请求队列**：刷新 token 期间的请求入队等待
|
||||
- **错误处理**：统一处理认证失败和其他错误
|
||||
|
||||
#### API 服务示例
|
||||
|
||||
**系统配置 API**（systemConfigApi.ts）：
|
||||
```typescript
|
||||
export const getSystemConfigList = async (params) => {
|
||||
const response = await apiClient.get('/admin/system-configs', { params });
|
||||
return response; // 返回完整响应对象
|
||||
}
|
||||
|
||||
export const createSystemConfig = async (data) => {
|
||||
const response = await apiClient.post('/admin/system-configs', data);
|
||||
return response.data;
|
||||
}
|
||||
```
|
||||
|
||||
**用户等级配置 API**（userLevelConfigApi.ts）：
|
||||
```typescript
|
||||
export const getUserLevelConfigList = async (params) => {
|
||||
const response = await apiClient.get('/admin/user-level-configs', { params });
|
||||
return response.data;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关键文件详解
|
||||
|
||||
### 1. 用户等级配置（UserLevelConfigs）
|
||||
|
||||
**文件清单**：
|
||||
- `/src/pages/UserLevelConfigs.tsx` - 页面组件（292 行）
|
||||
- `/src/services/userLevelConfigApi.ts` - API 服务（60 行）
|
||||
- `/src/types/userLevelConfig.ts` - 类型定义（47 行）
|
||||
|
||||
**功能**：
|
||||
- 列表查询（分页）
|
||||
- 创建新等级配置
|
||||
- 编辑等级配置
|
||||
- 删除等级配置
|
||||
- 启用/禁用等级配置
|
||||
|
||||
**数据模型**：
|
||||
```typescript
|
||||
interface UserLevelConfig {
|
||||
id: number;
|
||||
level_name: string; // 等级名称
|
||||
level_code: string; // 等级代码
|
||||
project_limit: number; // 项目数限制
|
||||
description: string; // 描述
|
||||
sort_order: number; // 排序顺序
|
||||
status: number; // 1=启用, 0=禁用
|
||||
created_at: string;
|
||||
updated_at: string;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 系统配置（SystemConfigs）
|
||||
|
||||
**文件清单**：
|
||||
- `/src/pages/SystemConfigs.tsx` - 页面组件（284 行）
|
||||
- `/src/services/systemConfigApi.ts` - API 服务（66 行）
|
||||
- `/src/types/systemConfig.ts` - 类型定义（51 行）
|
||||
|
||||
**功能**：
|
||||
- 列表查询（分页）
|
||||
- 创建新系统配置
|
||||
- 编辑系统配置
|
||||
- 删除系统配置
|
||||
- 启用/禁用系统配置
|
||||
|
||||
**数据模型**：
|
||||
```typescript
|
||||
interface SystemConfig {
|
||||
id: number;
|
||||
key: string; // 唯一标识
|
||||
name: string; // 配置名称
|
||||
value: string; // 配置值
|
||||
type: string; // 配置类型（string, int, bool, json）
|
||||
desc: string; // 配置描述
|
||||
status: number; // 1=启用, 0=禁用
|
||||
createdAt: string;
|
||||
updatedAt: string;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Layout 组件（布局）
|
||||
|
||||
**结构**：
|
||||
```
|
||||
┌─────────────────────────────┐
|
||||
│ Header（顶部栏） │
|
||||
├─────────┬───────────────────┤
|
||||
│ │ │
|
||||
│ Sidebar │ Main Content │
|
||||
│(Menus) │ （页面内容） │
|
||||
│ │ │
|
||||
├─────────┼───────────────────┤
|
||||
│ Footer（页脚） │
|
||||
└─────────────────────────────┘
|
||||
```
|
||||
|
||||
**特性**：
|
||||
- 侧边栏可折叠/展开（按钮）
|
||||
- 动态菜单（DynamicMenu）
|
||||
- 子导航标签（针对多级菜单页面）
|
||||
- 用户认证状态显示 + 登出按钮
|
||||
|
||||
### 4. 认证流程（useAuth Hook）
|
||||
|
||||
**功能**：
|
||||
- SSO 单点登录
|
||||
- Token 管理（access_token + refresh_token）
|
||||
- 自动 Token 刷新
|
||||
- Token 过期检测和重新登录
|
||||
|
||||
---
|
||||
|
||||
## API 端点规范
|
||||
|
||||
### 用户等级配置
|
||||
```
|
||||
GET /admin/user-level-configs # 列表（分页）
|
||||
GET /admin/user-level-configs/all # 全部（不分页）
|
||||
GET /admin/user-level-configs/:id # 详情
|
||||
POST /admin/user-level-configs # 创建
|
||||
PUT /admin/user-level-configs/:id # 更新
|
||||
PUT /admin/user-level-configs/:id/status # 更新状态
|
||||
DELETE /admin/user-level-configs/:id # 删除
|
||||
```
|
||||
|
||||
### 系统配置
|
||||
```
|
||||
GET /admin/system-configs # 列表（分页）
|
||||
GET /admin/system-configs/all # 全部（不分页）
|
||||
GET /admin/system-configs/:id # 详情
|
||||
GET /admin/system-configs/key/:key # 按 Key 查询
|
||||
POST /admin/system-configs # 创建
|
||||
PUT /admin/system-configs/:id # 更新
|
||||
PUT /admin/system-configs/:id/status # 更新状态
|
||||
DELETE /admin/system-configs/:id # 删除
|
||||
```
|
||||
|
||||
### 其他 API
|
||||
```
|
||||
GET /admin/goalfymax-users # GoalfyMax 用户列表
|
||||
GET /admin/user-feedback # 用户反馈
|
||||
GET /admin/message-push/logs # 推送记录
|
||||
GET /admin/vendor-model-pricing # 供应商模型价格
|
||||
POST /admin/message-push/send # 发送消息
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 权限系统
|
||||
|
||||
### 权限检查层级
|
||||
|
||||
1. **页面级权限**（usePagePermissions）
|
||||
- 检查用户是否可以访问某个页面
|
||||
- 返回可访问的页面列表
|
||||
|
||||
2. **操作级权限**（usePermissions）
|
||||
- 检查用户是否可以执行某个操作
|
||||
- 如：创建、编辑、删除、启用/禁用
|
||||
|
||||
3. **菜单级权限**（DynamicMenu）
|
||||
- 根据页面权限动态显示/隐藏菜单项
|
||||
- 支持嵌套菜单的权限管理
|
||||
|
||||
### 权限存储
|
||||
- 通过 localStorage 缓存
|
||||
- 从后端 SSO API 获取用户权限信息
|
||||
- Jotai 原子状态管理
|
||||
|
||||
---
|
||||
|
||||
## 页面模块划分
|
||||
|
||||
### 系统管理（/system）
|
||||
- 配额/套餐规则
|
||||
- 用户项目配额
|
||||
- 系统用户管理
|
||||
- 角色管理
|
||||
- GoalfyMax 用户管理
|
||||
- **用户等级配置**
|
||||
- **系统配置**
|
||||
|
||||
### 运营（/operations）
|
||||
- 用户反馈管理
|
||||
- 消息推送管理
|
||||
- 供应商模型价格管理
|
||||
|
||||
### 监控（/monitoring）
|
||||
- Token 历史
|
||||
- Token 分析
|
||||
- 系统健康
|
||||
|
||||
### 财务（/finance）
|
||||
- 财务数据统计
|
||||
|
||||
---
|
||||
|
||||
## 通用 CRUD 页面模式
|
||||
|
||||
### UserLevelConfigs 和 SystemConfigs 采用的设计模式
|
||||
|
||||
**页面结构**：
|
||||
1. 数据列表（分页表格）
|
||||
2. 创建弹窗
|
||||
3. 编辑弹窗
|
||||
4. 操作列（编辑、启用/禁用、删除）
|
||||
|
||||
**状态管理**：
|
||||
```typescript
|
||||
const [list, setList] = useState<T[]>([]);
|
||||
const [total, setTotal] = useState(0);
|
||||
const [page, setPage] = useState(1);
|
||||
const [size, setSize] = useState(10);
|
||||
const [editing, setEditing] = useState<T | null>(null);
|
||||
const [editOpen, setEditOpen] = useState(false);
|
||||
const [createOpen, setCreateOpen] = useState(false);
|
||||
```
|
||||
|
||||
**操作流程**：
|
||||
1. **查询列表**：`fetchList()` → API → 更新 state
|
||||
2. **创建**：表单验证 → API → 刷新列表
|
||||
3. **编辑**：打开弹窗 → 表单填充 → 表单验证 → API → 刷新列表
|
||||
4. **删除**：确认弹窗 → API → 刷新列表
|
||||
5. **状态切换**：API → 刷新列表
|
||||
|
||||
---
|
||||
|
||||
## 代码架构建议
|
||||
|
||||
### 当前优点
|
||||
1. 清晰的分层结构（页面 → Hook → API → Client）
|
||||
2. 类型安全（完整的 TypeScript 类型定义）
|
||||
3. 权限管理系统
|
||||
4. 可复用的 CRUD 模式
|
||||
5. 自动 Token 刷新机制
|
||||
|
||||
### 需要关注的方面
|
||||
1. **页面文件大小**：UserLevelConfigs.tsx 和 SystemConfigs.tsx 都接近 300 行，可以考虑拆分
|
||||
2. **组件复用**：考虑提取通用的 CRUD 表格组件
|
||||
3. **错误处理**：某些 API 调用的错误处理需要完善
|
||||
4. **加载状态**：分页加载、动作加载等状态管理可以统一
|
||||
|
||||
---
|
||||
|
||||
## 开发指南
|
||||
|
||||
### 添加新的配置管理页面
|
||||
|
||||
**步骤**：
|
||||
|
||||
1. **创建类型定义** (`src/types/xxxConfig.ts`)
|
||||
```typescript
|
||||
export interface XxxConfig {
|
||||
id: number;
|
||||
name: string;
|
||||
value: string;
|
||||
status: number;
|
||||
created_at: string;
|
||||
updated_at: string;
|
||||
}
|
||||
|
||||
export interface XxxConfigListRequest {
|
||||
page?: number;
|
||||
size?: number;
|
||||
}
|
||||
|
||||
export interface XxxConfigListResponse {
|
||||
data: XxxConfig[];
|
||||
total: number;
|
||||
}
|
||||
```
|
||||
|
||||
2. **创建 API 服务** (`src/services/xxxConfigApi.ts`)
|
||||
```typescript
|
||||
export const getXxxConfigList = async (params) =>
|
||||
(await apiClient.get('/admin/xxx-configs', { params })).data;
|
||||
|
||||
export const createXxxConfig = async (data) =>
|
||||
(await apiClient.post('/admin/xxx-configs', data)).data;
|
||||
// ... 其他 CRUD 操作
|
||||
```
|
||||
|
||||
3. **创建页面组件** (`src/pages/XxxConfigs.tsx`)
|
||||
- 参考 UserLevelConfigs.tsx 或 SystemConfigs.tsx 的结构
|
||||
- 实现列表、创建、编辑、删除、状态切换
|
||||
|
||||
4. **添加路由** (`src/App.tsx`)
|
||||
```typescript
|
||||
<Route path="/system/xxx-configs" element={<XxxConfigs />} />
|
||||
```
|
||||
|
||||
5. **添加菜单项** (`src/components/DynamicMenu.tsx`)
|
||||
```typescript
|
||||
{
|
||||
key: 'system-xxx-configs',
|
||||
label: 'Xxx 配置',
|
||||
icon: <SettingOutlined />,
|
||||
path: '/xxx-configs',
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
这是一个**结构良好的 React 管理后台**，具有：
|
||||
- 权限驱动的动态菜单和路由
|
||||
- 清晰的分层 API 架构
|
||||
- 完整的 TypeScript 类型支持
|
||||
- 通用的 CRUD 页面模式
|
||||
- 自动化的 Token 管理
|
||||
|
||||
最近的开发方向是**添加系统配置管理功能**（SystemConfigs 和 UserLevelConfigs），这些都是遵循统一的模式和最佳实践。
|
||||
|
||||
Reference in New Issue
Block a user