fastapi-demo/frontend/README.md

# FastAPI Demo - 前端管理界面

基于 Vue 3 + Element Plus 构建的简易管理后台，为 FastAPI Demo 项目提供用户友好的管理界面。

## 🚀 快速开始

### 环境要求

- Node.js >= 16.0.0
- npm 或 yarn
- 后端 FastAPI 服务运行在 `http://localhost:8000`

### 安装依赖

```bash
# 进入前端目录
cd frontend

# 安装依赖
npm install
```

### 开发环境启动

```bash
# 启动开发服务器
npm run dev

# 访问地址：http://localhost:3000
```

### 构建生产版本

```bash
# 构建生产版本
npm run build

# 预览构建结果
npm run preview
```

## 📋 功能特性

### 核心功能
- 🏠 **仪表板**: 系统概览和快速导航
- 👥 **用户管理**: 完整的用户 CRUD 操作
- 📦 **产品管理**: 完整的产品 CRUD 操作
- 🔗 **API 集成**: 与 FastAPI 后端无缝对接

### 技术特性
- ✨ **现代化界面**: Element Plus 组件库
- 📱 **响应式设计**: 支持桌面端和平板端
- 🛡️ **表单验证**: 完善的输入验证机制
- 💬 **用户反馈**: 统一的成功/错误消息提示
- 🔄 **错误处理**: 网络异常和业务错误处理

## 🏗️ 项目结构

```
frontend/
├── public/                    # 静态资源
├── src/
│   ├── api/                   # API 接口定义
│   │   ├── user.js           # 用户相关API
│   │   └── product.js        # 产品相关API
│   ├── components/           # 组件库
│   │   ├── AppHeader.vue     # 头部组件
│   │   ├── AppSidebar.vue    # 侧边栏组件
│   │   ├── DataTable.vue     # 通用数据表格
│   │   ├── FormDialog.vue    # 通用表单对话框
│   │   ├── UserForm.vue      # 用户表单
│   │   └── ProductForm.vue   # 产品表单
│   ├── layouts/              # 布局组件
│   │   └── AppLayout.vue     # 主布局
│   ├── views/                # 页面组件
│   │   ├── Dashboard.vue     # 仪表板
│   │   ├── UserManagement.vue    # 用户管理
│   │   └── ProductManagement.vue # 产品管理
│   ├── router/               # 路由配置
│   │   └── index.js          # 路由定义
│   ├── utils/                # 工具函数
│   │   └── request.js        # Axios 配置
│   ├── App.vue               # 根组件
│   └── main.js               # 应用入口
├── index.html                # HTML 模板
├── package.json              # 项目配置
├── vite.config.js            # 构建配置
└── README.md                 # 项目说明
```

## 🔌 API 接口

### 用户管理 API
- `GET /api/v1/users/` - 获取用户列表
- `GET /api/v1/users/{id}` - 获取单个用户
- `POST /api/v1/users/` - 创建用户
- `PUT /api/v1/users/{id}` - 更新用户
- `DELETE /api/v1/users/{id}` - 删除用户

### 产品管理 API
- `GET /api/v1/products/` - 获取产品列表
- `GET /api/v1/products/{id}` - 获取单个产品
- `POST /api/v1/products/` - 创建产品
- `PUT /api/v1/products/{id}` - 更新产品
- `DELETE /api/v1/products/{id}` - 删除产品

## 🛠️ 技术栈

### 核心框架
- **Vue 3**: 渐进式 JavaScript 框架
- **Vite**: 快速构建工具
- **Vue Router 4**: 官方路由管理器

### UI 组件库
- **Element Plus**: 基于 Vue 3 的组件库
- **Element Plus Icons**: 图标库

### HTTP 客户端
- **Axios**: Promise based HTTP 客户端

### 开发工具
- **Vite**: 开发服务器和构建工具
- **ES6+**: 现代 JavaScript 语法

## ⚙️ 配置说明

### Vite 配置 (`vite.config.js`)
```javascript
export default {
  server: {
    port: 3000,                    // 开发服务器端口
    proxy: {
      '/api': {
        target: 'http://localhost:8000',  // 后端 API 地址
        changeOrigin: true
      }
    }
  }
}
```

### API 配置 (`src/utils/request.js`)
- 基础 URL: `/api`
- 请求超时: 10 秒
- 自动错误处理和消息提示

## 🎯 使用指南

### 启动项目
1. 确保后端 FastAPI 服务已启动 (`http://localhost:8000`)
2. 安装前端依赖: `npm install`
3. 启动开发服务器: `npm run dev`
4. 浏览器访问: `http://localhost:3000`

### 功能操作
1. **仪表板**: 查看系统概览，快速导航到管理页面
2. **用户管理**:
   - 查看用户列表
   - 点击"新增用户"创建用户
   - 点击"编辑"修改用户信息
   - 点击"删除"删除用户（需确认）
3. **产品管理**:
   - 查看产品列表
   - 点击"新增产品"创建产品
   - 点击"编辑"修改产品信息
   - 点击"删除"删除产品（需确认）

### 表单验证
- **用户表单**:
  - 用户名: 必填，3-20 个字符
  - 邮箱: 必填，邮箱格式验证
  - 全名: 可选
- **产品表单**:
  - 产品名称: 必填，2-50 个字符
  - 价格: 必填，数字类型，≥0
  - 库存: 必填，整数类型，≥0
  - 描述: 可选

## 🚨 注意事项

1. **后端依赖**: 前端需要后端 FastAPI 服务正常运行
2. **CORS 配置**: 后端已配置 CORS，允许前端跨域访问
3. **数据持久化**: 数据通过后端 API 存储到 MySQL 数据库
4. **无认证系统**: 当前版本无需登录，直接访问管理功能
5. **错误处理**: 网络错误和服务器错误会自动显示错误消息

## 🔧 开发说明

### 添加新页面
1. 在 `src/views/` 创建新的 Vue 组件
2. 在 `src/router/index.js` 添加路由配置
3. 在 `src/components/AppSidebar.vue` 添加导航菜单项

### 添加新 API
1. 在 `src/api/` 创建对应的 API 服务文件
2. 使用 `src/utils/request.js` 的 axios 实例
3. 遵循 RESTful API 设计规范

### 组件复用
- `DataTable`: 通用数据表格组件
- `FormDialog`: 通用表单对话框组件
- 新增表单可参考 `UserForm.vue` 和 `ProductForm.vue`

## 📈 性能优化

- ✅ 路由懒加载
- ✅ 组件按需引入
- ✅ 代码分割
- ✅ 生产环境优化

## 🐛 常见问题

**Q: 页面显示"网络连接异常"**
A: 请确认后端 FastAPI 服务是否正常运行在 `http://localhost:8000`

**Q: 新增/编辑操作失败**
A: 检查表单输入是否符合验证规则，查看浏览器控制台错误信息

**Q: 页面样式异常**
A: 确认 Element Plus 样式文件是否正确加载

## 📞 技术支持

如有问题，请查看：
1. 浏览器开发者工具控制台错误信息
2. 后端 FastAPI 服务日志
3. 网络请求响应状态

---

**开发团队**: FastAPI Demo Project
**创建时间**: 2025-09-28
**技术栈**: Vue 3 + Element Plus + Vite