feat():learning后台管理前端页面初始化
This commit is contained in:
yuj
566
QUICK_START.md
Normal file
566
QUICK_START.md
Normal file
@@ -0,0 +1,566 @@
|
||||
# 前端开发快速开始指南
|
||||
|
||||
## 项目信息
|
||||
|
||||
- **技术栈**: 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`
|
||||
|
||||
Reference in New Issue
Block a user