567 lines
14 KiB
Markdown
567 lines
14 KiB
Markdown
# 前端开发快速开始指南
|
||
|
||
## 项目信息
|
||
|
||
- **技术栈**: React 18 + TypeScript + Vite + Ant Design 5 + React Router 7
|
||
- **项目路径**: `/Users/youziba/goalfyagent/goalfymax-admin-web`
|
||
- **状态管理**: Jotai
|
||
- **HTTP客户端**: Axios (自动处理 Token 认证和刷新)
|
||
|
||
---
|
||
|
||
## 快速创建新的配置管理页面
|
||
|
||
以创建"通用配置"管理页面为例，需要 5 个步骤：
|
||
|
||
### 步骤 1：创建类型定义文件
|
||
|
||
**文件**: `src/types/commonConfig.ts`
|
||
|
||
```typescript
|
||
export interface CommonConfig {
|
||
id: number;
|
||
config_key: string; // 配置键
|
||
config_value: string; // 配置值
|
||
description: string; // 描述
|
||
status: number; // 1=启用, 0=禁用
|
||
created_at: string;
|
||
updated_at: string;
|
||
}
|
||
|
||
export interface CommonConfigListRequest {
|
||
config_key?: string;
|
||
status?: number;
|
||
page?: number;
|
||
size?: number;
|
||
}
|
||
|
||
export interface CommonConfigListResponse {
|
||
data: CommonConfig[];
|
||
total: number;
|
||
page: number;
|
||
size: number;
|
||
}
|
||
|
||
export interface CommonConfigCreateRequest {
|
||
config_key: string;
|
||
config_value: string;
|
||
description?: string;
|
||
}
|
||
|
||
export interface CommonConfigUpdateRequest {
|
||
config_key: string;
|
||
config_value: string;
|
||
description?: string;
|
||
}
|
||
```
|
||
|
||
### 步骤 2：创建 API 服务文件
|
||
|
||
**文件**: `src/services/commonConfigApi.ts`
|
||
|
||
```typescript
|
||
import { apiClient } from './api';
|
||
import type {
|
||
CommonConfig,
|
||
CommonConfigListRequest,
|
||
CommonConfigListResponse,
|
||
CommonConfigCreateRequest,
|
||
CommonConfigUpdateRequest,
|
||
} from '../types/commonConfig';
|
||
|
||
export const getCommonConfigList = async (
|
||
params: CommonConfigListRequest
|
||
): Promise<CommonConfigListResponse> => {
|
||
const response = await apiClient.get('/admin/common-configs', { params });
|
||
return response.data;
|
||
};
|
||
|
||
export const getCommonConfigById = async (id: number): Promise<CommonConfig> => {
|
||
const response = await apiClient.get(`/admin/common-configs/${id}`);
|
||
return response.data;
|
||
};
|
||
|
||
export const createCommonConfig = async (
|
||
data: CommonConfigCreateRequest
|
||
): Promise<CommonConfig> => {
|
||
const response = await apiClient.post('/admin/common-configs', data);
|
||
return response.data;
|
||
};
|
||
|
||
export const updateCommonConfig = async (
|
||
id: number,
|
||
data: CommonConfigUpdateRequest
|
||
): Promise<CommonConfig> => {
|
||
const response = await apiClient.put(`/admin/common-configs/${id}`, data);
|
||
return response.data;
|
||
};
|
||
|
||
export const deleteCommonConfig = async (id: number): Promise<void> => {
|
||
await apiClient.delete(`/admin/common-configs/${id}`);
|
||
};
|
||
|
||
export const updateCommonConfigStatus = async (
|
||
id: number,
|
||
status: number
|
||
): Promise<void> => {
|
||
await apiClient.put(`/admin/common-configs/${id}/status`, { status });
|
||
};
|
||
```
|
||
|
||
### 步骤 3：创建页面组件
|
||
|
||
**文件**: `src/pages/CommonConfigs.tsx`
|
||
|
||
```typescript
|
||
import React, { useEffect, useState } from 'react';
|
||
import {
|
||
Table,
|
||
Button,
|
||
Modal,
|
||
Form,
|
||
Input,
|
||
Tag,
|
||
Space,
|
||
Popconfirm,
|
||
message,
|
||
Row,
|
||
Col,
|
||
Card,
|
||
} from 'antd';
|
||
import {
|
||
PlusOutlined,
|
||
EditOutlined,
|
||
DeleteOutlined,
|
||
CheckCircleOutlined,
|
||
StopOutlined,
|
||
} from '@ant-design/icons';
|
||
import type { CommonConfig } from '../types/commonConfig';
|
||
import {
|
||
getCommonConfigList,
|
||
createCommonConfig,
|
||
updateCommonConfig,
|
||
deleteCommonConfig,
|
||
updateCommonConfigStatus,
|
||
} from '../services/commonConfigApi';
|
||
|
||
export default function CommonConfigs() {
|
||
const [loading, setLoading] = useState(false);
|
||
const [list, setList] = useState<CommonConfig[]>([]);
|
||
const [total, setTotal] = useState(0);
|
||
const [page, setPage] = useState(1);
|
||
const [size, setSize] = useState(10);
|
||
const [editOpen, setEditOpen] = useState(false);
|
||
const [editing, setEditing] = useState<CommonConfig | null>(null);
|
||
const [createOpen, setCreateOpen] = useState(false);
|
||
const [form] = Form.useForm();
|
||
const [createForm] = Form.useForm();
|
||
|
||
// 获取列表
|
||
const fetchList = async () => {
|
||
setLoading(true);
|
||
try {
|
||
const res = await getCommonConfigList({ page, size });
|
||
setList(res?.data ?? []);
|
||
setTotal(res?.total ?? 0);
|
||
} catch (e) {
|
||
message.error('获取列表失败');
|
||
} finally {
|
||
setLoading(false);
|
||
}
|
||
};
|
||
|
||
useEffect(() => {
|
||
fetchList();
|
||
}, [page, size]);
|
||
|
||
const openEdit = (config: CommonConfig) => {
|
||
setEditing(config);
|
||
form.setFieldsValue({
|
||
config_key: config.config_key,
|
||
config_value: config.config_value,
|
||
description: config.description,
|
||
});
|
||
setEditOpen(true);
|
||
};
|
||
|
||
const submitEdit = async () => {
|
||
try {
|
||
const values = await form.validateFields();
|
||
if (!editing) return;
|
||
await updateCommonConfig(editing.id, values);
|
||
message.success('更新成功');
|
||
setEditOpen(false);
|
||
fetchList();
|
||
} catch (error) {
|
||
message.error('更新失败');
|
||
}
|
||
};
|
||
|
||
const openCreate = () => {
|
||
createForm.resetFields();
|
||
setCreateOpen(true);
|
||
};
|
||
|
||
const submitCreate = async () => {
|
||
try {
|
||
const values = await createForm.validateFields();
|
||
await createCommonConfig(values);
|
||
message.success('创建成功');
|
||
setCreateOpen(false);
|
||
fetchList();
|
||
} catch (error: any) {
|
||
message.error(error?.response?.data?.message || '创建失败');
|
||
}
|
||
};
|
||
|
||
const handleDelete = async (config: CommonConfig) => {
|
||
try {
|
||
await deleteCommonConfig(config.id);
|
||
message.success('删除成功');
|
||
fetchList();
|
||
} catch (error) {
|
||
message.error('删除失败');
|
||
}
|
||
};
|
||
|
||
const handleToggleStatus = async (config: CommonConfig) => {
|
||
try {
|
||
const newStatus = config.status === 1 ? 0 : 1;
|
||
await updateCommonConfigStatus(config.id, newStatus);
|
||
message.success(newStatus === 1 ? '已启用' : '已禁用');
|
||
fetchList();
|
||
} catch (error) {
|
||
message.error('状态更新失败');
|
||
}
|
||
};
|
||
|
||
const columns = [
|
||
{
|
||
title: '配置键',
|
||
dataIndex: 'config_key',
|
||
key: 'config_key',
|
||
},
|
||
{
|
||
title: '配置值',
|
||
dataIndex: 'config_value',
|
||
key: 'config_value',
|
||
},
|
||
{
|
||
title: '描述',
|
||
dataIndex: 'description',
|
||
key: 'description',
|
||
},
|
||
{
|
||
title: '状态',
|
||
dataIndex: 'status',
|
||
key: 'status',
|
||
render: (value: number) =>
|
||
value === 1 ? <Tag color="green">启用</Tag> : <Tag color="red">禁用</Tag>,
|
||
},
|
||
{
|
||
title: '操作',
|
||
key: 'action',
|
||
render: (_: any, config: CommonConfig) => (
|
||
<Space>
|
||
<Button type="link" icon={<EditOutlined />} onClick={() => openEdit(config)}>
|
||
编辑
|
||
</Button>
|
||
<Button
|
||
type="link"
|
||
icon={config.status === 1 ? <StopOutlined /> : <CheckCircleOutlined />}
|
||
onClick={() => handleToggleStatus(config)}
|
||
>
|
||
{config.status === 1 ? '禁用' : '启用'}
|
||
</Button>
|
||
<Popconfirm title="确定删除？" onConfirm={() => handleDelete(config)}>
|
||
<Button type="link" danger icon={<DeleteOutlined />}>
|
||
删除
|
||
</Button>
|
||
</Popconfirm>
|
||
</Space>
|
||
),
|
||
},
|
||
];
|
||
|
||
return (
|
||
<div>
|
||
<Row gutter={16} style={{ marginBottom: 16 }}>
|
||
<Col span={24}>
|
||
<Card>
|
||
<div style={{ marginBottom: 16 }}>
|
||
<Button type="primary" icon={<PlusOutlined />} onClick={openCreate}>
|
||
新建配置
|
||
</Button>
|
||
</div>
|
||
<Table
|
||
dataSource={list}
|
||
columns={columns}
|
||
rowKey="id"
|
||
loading={loading}
|
||
pagination={{
|
||
current: page,
|
||
pageSize: size,
|
||
total: total,
|
||
onChange: (p, s) => {
|
||
setPage(p);
|
||
setSize(s);
|
||
},
|
||
}}
|
||
/>
|
||
</Card>
|
||
</Col>
|
||
</Row>
|
||
|
||
{/* 编辑弹窗 */}
|
||
<Modal
|
||
title="编辑配置"
|
||
open={editOpen}
|
||
onOk={submitEdit}
|
||
onCancel={() => setEditOpen(false)}
|
||
>
|
||
<Form form={form} layout="vertical">
|
||
<Form.Item
|
||
name="config_key"
|
||
label="配置键"
|
||
rules={[{ required: true, message: '请输入配置键' }]}
|
||
>
|
||
<Input placeholder="请输入配置键" />
|
||
</Form.Item>
|
||
<Form.Item
|
||
name="config_value"
|
||
label="配置值"
|
||
rules={[{ required: true, message: '请输入配置值' }]}
|
||
>
|
||
<Input placeholder="请输入配置值" />
|
||
</Form.Item>
|
||
<Form.Item name="description" label="描述">
|
||
<Input.TextArea rows={3} />
|
||
</Form.Item>
|
||
</Form>
|
||
</Modal>
|
||
|
||
{/* 创建弹窗 */}
|
||
<Modal
|
||
title="新建配置"
|
||
open={createOpen}
|
||
onOk={submitCreate}
|
||
onCancel={() => setCreateOpen(false)}
|
||
>
|
||
<Form form={createForm} layout="vertical">
|
||
<Form.Item
|
||
name="config_key"
|
||
label="配置键"
|
||
rules={[{ required: true, message: '请输入配置键' }]}
|
||
>
|
||
<Input placeholder="请输入配置键（如：app_name）" />
|
||
</Form.Item>
|
||
<Form.Item
|
||
name="config_value"
|
||
label="配置值"
|
||
rules={[{ required: true, message: '请输入配置值' }]}
|
||
>
|
||
<Input placeholder="请输入配置值" />
|
||
</Form.Item>
|
||
<Form.Item name="description" label="描述">
|
||
<Input.TextArea rows={3} placeholder="请输入描述" />
|
||
</Form.Item>
|
||
</Form>
|
||
</Modal>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 步骤 4：在 App.tsx 中添加路由
|
||
|
||
在 `src/App.tsx` 中找到系统管理路由部分，添加：
|
||
|
||
```typescript
|
||
import CommonConfigs from './pages/CommonConfigs';
|
||
|
||
// 在 Routes 中的系统管理部分添加：
|
||
<Route path="/system/common-configs" element={<CommonConfigs />} />
|
||
```
|
||
|
||
### 步骤 5：在 Layout.tsx 中添加菜单项
|
||
|
||
在 `src/components/Layout.tsx` 中找到系统管理子菜单部分（`data-tabs="admin"`），添加：
|
||
|
||
```typescript
|
||
<button
|
||
className={activeSubTab === 'common-configs' ? 'active' : ''}
|
||
onClick={() => navigate('/system/common-configs')}
|
||
>
|
||
通用配置
|
||
</button>
|
||
```
|
||
|
||
---
|
||
|
||
## 核心文件速查表
|
||
|
||
| 功能 | 文件位置 | 说明 |
|
||
|------|---------|------|
|
||
| 全局路由 | `src/App.tsx` | 所有页面路由定义 |
|
||
| 菜单导航 | `src/components/Layout.tsx` | 菜单项和导航配置 |
|
||
| API 客户端 | `src/services/api.ts` | Axios 包装，自动处理 Token |
|
||
| 权限检查 | `src/hooks/usePagePermissions.ts` | 获取用户权限信息 |
|
||
| 认证管理 | `src/hooks/useAuth.ts` | SSO 认证相关逻辑 |
|
||
| 全局状态 | `src/atoms/auth.ts` | Jotai 状态原子定义 |
|
||
|
||
---
|
||
|
||
## 常用开发模式
|
||
|
||
### 1. 获取列表并分页
|
||
|
||
```typescript
|
||
const [list, setList] = useState<T[]>([]);
|
||
const [page, setPage] = useState(1);
|
||
const [size, setSize] = useState(10);
|
||
const [total, setTotal] = useState(0);
|
||
|
||
const fetchList = async () => {
|
||
const res = await getXxxList({ page, size });
|
||
setList(res?.data ?? []);
|
||
setTotal(res?.total ?? 0);
|
||
};
|
||
|
||
useEffect(() => {
|
||
fetchList();
|
||
}, [page, size]);
|
||
|
||
// 在 Table 中使用
|
||
<Table
|
||
dataSource={list}
|
||
pagination={{
|
||
current: page,
|
||
pageSize: size,
|
||
total: total,
|
||
onChange: (p, s) => {
|
||
setPage(p);
|
||
setSize(s);
|
||
},
|
||
}}
|
||
/>
|
||
```
|
||
|
||
### 2. 打开编辑弹窗并回显数据
|
||
|
||
```typescript
|
||
const [editOpen, setEditOpen] = useState(false);
|
||
const [editing, setEditing] = useState<T | null>(null);
|
||
const [form] = Form.useForm();
|
||
|
||
const openEdit = (record: T) => {
|
||
setEditing(record);
|
||
form.setFieldsValue({
|
||
field1: record.field1,
|
||
field2: record.field2,
|
||
});
|
||
setEditOpen(true);
|
||
};
|
||
|
||
const submitEdit = async () => {
|
||
const values = await form.validateFields();
|
||
await updateXxx(editing!.id, values);
|
||
message.success('更新成功');
|
||
setEditOpen(false);
|
||
fetchList();
|
||
};
|
||
```
|
||
|
||
### 3. 权限检查
|
||
|
||
```typescript
|
||
import { usePagePermissions } from '../hooks/usePagePermissions';
|
||
|
||
function MyComponent() {
|
||
const { getAccessiblePages } = usePagePermissions();
|
||
const accessiblePages = getAccessiblePages();
|
||
|
||
if (!accessiblePages.includes('/system')) {
|
||
return <div>无权访问</div>;
|
||
}
|
||
|
||
return <div>内容</div>;
|
||
}
|
||
```
|
||
|
||
### 4. 调用 API
|
||
|
||
```typescript
|
||
import { apiClient } from '../services/api';
|
||
|
||
// GET 请求
|
||
const data = await apiClient.get('/admin/xxx');
|
||
|
||
// POST 请求
|
||
const result = await apiClient.post('/admin/xxx', { key: 'value' });
|
||
|
||
// PUT 请求
|
||
const updated = await apiClient.put('/admin/xxx/123', { key: 'new-value' });
|
||
|
||
// DELETE 请求
|
||
await apiClient.delete('/admin/xxx/123');
|
||
```
|
||
|
||
---
|
||
|
||
## Ant Design 常用组件
|
||
|
||
| 组件 | 用途 | 导入 |
|
||
|------|------|------|
|
||
| `Button` | 按钮 | `from 'antd'` |
|
||
| `Table` | 数据表格 | `from 'antd'` |
|
||
| `Form` | 表单 | `from 'antd'` |
|
||
| `Input` | 文本输入 | `from 'antd'` |
|
||
| `InputNumber` | 数字输入 | `from 'antd'` |
|
||
| `Select` | 下拉选择 | `from 'antd'` |
|
||
| `Modal` | 弹窗对话框 | `from 'antd'` |
|
||
| `Message` | 消息提示 | `from 'antd'` |
|
||
| `Tag` | 标签 | `from 'antd'` |
|
||
| `Card` | 卡片容器 | `from 'antd'` |
|
||
| `Space` | 间距布局 | `from 'antd'` |
|
||
| `Popconfirm` | 确认弹窗 | `from 'antd'` |
|
||
|
||
---
|
||
|
||
## 开发工作流
|
||
|
||
1. **创建类型定义** → `src/types/xxx.ts`
|
||
2. **创建 API 服务** → `src/services/xxxApi.ts`
|
||
3. **创建页面组件** → `src/pages/Xxx.tsx`
|
||
4. **添加路由** → `src/App.tsx`
|
||
5. **添加菜单** → `src/components/Layout.tsx`
|
||
6. **测试** → `npm run dev`
|
||
|
||
---
|
||
|
||
## API 命名规范
|
||
|
||
- 列表: `GET /admin/xxx`
|
||
- 详情: `GET /admin/xxx/:id`
|
||
- 创建: `POST /admin/xxx`
|
||
- 更新: `PUT /admin/xxx/:id`
|
||
- 删除: `DELETE /admin/xxx/:id`
|
||
- 状态: `PUT /admin/xxx/:id/status`
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **Token 自动管理**: API 请求会自动附带 Token，401 错误会自动刷新 Token
|
||
2. **权限检查**: 菜单和路由需要通过 `usePagePermissions` 检查用户权限
|
||
3. **类型安全**: 始终使用 TypeScript 定义接口，避免使用 `any`
|
||
4. **表单验证**: 使用 `Form.useForm()` 和 `validateFields()` 进行表单验证
|
||
5. **消息提示**: 使用 `message.success()` / `message.error()` 等方法提示用户
|
||
6. **异步处理**: 使用 `async/await` 简化异步逻辑
|
||
|
||
---
|
||
|
||
## 参考文档
|
||
|
||
完整的开发指南请查看: `/Users/youziba/goalfyagent/goalfymax-admin-web/FRONTEND_GUIDE.md`
|
||
|