diff --git a/src/api/README.md b/src/api/README.md index b107536d912e90b83b79df4daefd5f4742fc2333..9d912059dec694db3e28a3d0e162936c8def9c8b 100644 --- a/src/api/README.md +++ b/src/api/README.md @@ -1,236 +1,138 @@ -# API 管理系统 -本项目采用模块化的 API 管理方式,将不同功能的 API 按模块划分,便于维护和扩展。 -## 📁 文件结构 +# 后台管理系统 - React 18 模板 + +这是一个基于 React 18、TypeScript、Ant Design 和 Redux Toolkit 构建的现代化后台管理系统模板。 + +## 技术栈 + +- **React 18** - 最新的 React 版本 +- **TypeScript** - 类型安全的 JavaScript +- **Ant Design 5** - 企业级 UI 组件库 +- **Redux Toolkit** - 现代化的 Redux 状态管理 +- **React Router 6** - 路由管理 +- **Vite** - 快速的构建工具 +- **Sass** - CSS 预处理器 +- **Axios** - HTTP 客户端 +- **i18next** - 国际化支持 + +## 功能特性 + +- 🎨 现代化的 UI 设计 +- 📱 响应式布局 +- 🔐 用户认证和授权 +- 🌐 国际化支持(中文/英文) +- 📊 数据可视化 +- 🔄 状态管理 +- 📝 表单验证 +- 🎯 TypeScript 支持 +- ⚡ 快速开发体验 + +## 项目结构 ``` -src/api/ -├── index.ts # API 统一入口 -├── request.ts # 请求配置和拦截器 -├── types.ts # TypeScript 类型定义 -├── auth.ts # 认证相关 API -├── users.ts # 用户管理 API -├── roles.ts # 角色管理 API -├── departments.ts # 部门管理 API -├── dashboard.ts # 仪表盘 API -├── example.ts # 使用示例 -└── README.md # 说明文档 +src/ +├── api/ # API 接口 +├── components/ # 公共组件 +├── pages/ # 页面组件 +├── router/ # 路由配置 +├── store/ # Redux 状态管理 +├── styles/ # 样式文件 +├── types/ # TypeScript 类型定义 +└── locales/ # 国际化文件 ``` -## 🚀 快速开始 +## 快速开始 -### 1. 导入 API +### 安装依赖 -```typescript -import { authApi, usersApi, rolesApi, departmentsApi, dashboardApi } from '@/api'; +```bash +npm install ``` -### 2. 使用示例 - -#### 用户登录 -```typescript -import { authApi } from '@/api'; - -const handleLogin = async () => { - try { - const result = await authApi.login({ - username: 'admin', - password: 'admin123' - }); - - // 保存 token - localStorage.setItem('token', result.token); - localStorage.setItem('userInfo', JSON.stringify(result.userInfo)); - - console.log('登录成功:', result); - } catch (error) { - console.error('登录失败:', error); - } -}; -``` +### 启动开发服务器 -#### 获取用户列表 -```typescript -import { usersApi } from '@/api'; - -const getUsers = async () => { - try { - const result = await usersApi.getUsers({ - page: 1, - pageSize: 10, - status: 'active' - }); - - console.log('用户列表:', result.list); - console.log('总数:', result.total); - } catch (error) { - console.error('获取用户列表失败:', error); - } -}; +```bash +npm run dev ``` -#### 创建用户 -```typescript -import { usersApi } from '@/api'; - -const createUser = async () => { - try { - const newUser = await usersApi.createUser({ - username: 'newuser', - password: 'password123', - email: 'newuser@example.com', - phone: '13800138002', - role: 'user', - status: 'active' - }); - - console.log('创建用户成功:', newUser); - } catch (error) { - console.error('创建用户失败:', error); - } -}; +### 构建生产版本 + +```bash +npm run build ``` -## 🔧 配置说明 +### 预览生产版本 -### 环境变量 +```bash +npm run preview +``` -在 `.env` 文件中配置 API 基础 URL: +### 类型检查 -```env -VITE_API_BASE_URL=http://localhost:3001/api +```bash +npm run type-check ``` -### 请求拦截器 - -- 自动添加 Authorization 头(从 localStorage 获取 token) -- 统一的错误处理 -- 401 状态码自动跳转登录页 - -### 响应拦截器 - -- 统一的响应格式处理 -- 自动显示错误消息 -- 业务错误处理 - -## 📝 API 模块说明 - -### authApi - 认证模块 -- `login(data)` - 用户登录 -- `getUserInfo()` - 获取用户信息 -- `logout()` - 用户登出 -- `refreshToken()` - 刷新 Token - -### usersApi - 用户管理模块 -- `getUsers(params)` - 获取用户列表 -- `getUser(id)` - 获取单个用户 -- `createUser(data)` - 创建用户 -- `updateUser(id, data)` - 更新用户 -- `deleteUser(id)` - 删除用户 -- `changePassword(id, newPassword)` - 修改密码 - -### rolesApi - 角色管理模块 -- `getRoles(params)` - 获取角色列表 -- `getRole(id)` - 获取单个角色 -- `createRole(data)` - 创建角色 -- `updateRole(id, data)` - 更新角色 -- `deleteRole(id)` - 删除角色 -- `getPermissions()` - 获取权限列表 - -### departmentsApi - 部门管理模块 -- `getDepartments(params)` - 获取部门列表 -- `getDepartmentTree()` - 获取部门树形结构 -- `getDepartment(id)` - 获取单个部门 -- `createDepartment(data)` - 创建部门 -- `updateDepartment(id, data)` - 更新部门 -- `deleteDepartment(id)` - 删除部门 -- `getDepartmentUsers(id)` - 获取部门用户列表 - -### dashboardApi - 仪表盘模块 -- `getOverview()` - 获取概览数据 -- `getUserGrowth(period)` - 获取用户增长趋势 -- `getUserDistribution()` - 获取用户分布数据 -- `getRecentActivities(limit)` - 获取最近活动 -- `getPerformance()` - 获取系统性能指标 -- `getPageViews(period)` - 获取页面访问统计 - -## 🔒 权限控制 - -所有需要认证的 API 都会自动添加 Authorization 头,格式为: +### 代码检查 -``` -Authorization: Bearer +```bash +npm run lint ``` -## 🛠️ 扩展指南 +### 环境变量 -### 添加新的 API 模块 +创建 `.env` 文件并配置以下变量: -1. 在 `src/api/` 目录下创建新的模块文件,如 `products.ts` -2. 在 `src/api/types.ts` 中添加相关类型定义 -3. 在 `src/api/index.ts` 中导出新模块 +```env +VITE_API_BASE_URL=http://localhost:3000/api +``` -```typescript -// src/api/products.ts -import { api } from './request'; -import { Product } from './types'; +## 主要页面 -export const productsApi = { - getProducts: () => api.get('/products'), - createProduct: (data: any) => api.post('/products', data), - // ... 其他方法 -}; +- **登录页面** - 用户认证 +- **仪表板** - 数据概览 +- **用户管理** - 用户 CRUD 操作 +- **角色管理** - 角色权限管理 +- **部门管理** - 组织架构管理 +- **系统设置** - 系统配置 -// src/api/index.ts -export * from './products'; -``` +## 开发指南 -### 自定义请求配置 +### 添加新页面 -```typescript -import { api } from '@/api'; +1. 在 `src/pages/` 目录下创建页面组件 +2. 在 `src/router/routes.ts` 中添加路由配置 +3. 在 `src/api/` 目录下添加相关 API 接口 -// 自定义请求配置 -const customRequest = api.get('/custom-endpoint', { - timeout: 5000, - headers: { - 'Custom-Header': 'value' - } -}); -``` +### 添加新组件 -## 📊 错误处理 +1. 在 `src/components/` 目录下创建组件 +2. 使用 TypeScript 定义组件 props 类型 +3. 添加必要的样式文件 -所有 API 调用都会自动处理以下错误: +### 状态管理 -- 网络错误 -- 401 未授权(自动跳转登录) -- 403 权限不足 -- 404 资源不存在 -- 500 服务器错误 -- 业务逻辑错误 +使用 Redux Toolkit 进行状态管理: -错误消息会自动通过 Ant Design 的 message 组件显示。 +1. 在 `src/store/slices/` 目录下创建 slice +2. 在 `src/store/index.ts` 中注册 slice +3. 在组件中使用 `useSelector` 和 `useDispatch` -## 🔄 状态管理集成 +## 代码规范 -可以与 Redux Toolkit 结合使用: +- 使用 TypeScript 进行类型检查 +- 遵循 ESLint 规则 +- 使用 Prettier 格式化代码 +- 组件使用函数式组件和 Hooks -```typescript -// store/slices/userSlice.ts -import { createAsyncThunk } from '@reduxjs/toolkit'; -import { usersApi } from '@/api'; +## 浏览器支持 -export const fetchUsers = createAsyncThunk( - 'users/fetchUsers', - async (params: any) => { - const response = await usersApi.getUsers(params); - return response; - } -); -``` +- Chrome >= 87 +- Firefox >= 78 +- Safari >= 14 +- Edge >= 88 -## 📚 更多示例 +## 许可证 -查看 `src/api/example.ts` 文件获取更多使用示例。 \ No newline at end of file +MIT License \ No newline at end of file