fastapi-demo/docs/frontend-ui/CONSENSUS_frontend-ui.md

# CONSENSUS - 前端 UI 项目共识文档

## 📋 需求描述

### 项目目标
在现有 FastAPI 项目根目录下创建一个独立的前端 UI 项目，为后端 API 提供简易的管理界面。

### 核心需求
1. **无认证管理界面**: 直接访问，无需登录注册
2. **用户管理功能**: 完整的用户 CRUD 操作界面
3. **产品管理功能**: 完整的产品 CRUD 操作界面
4. **现代化 UI**: 使用 Vue 3 + Element Plus 构建

## 🏗️ 技术实现方案

### 前端技术栈
- **框架**: Vue 3 (Composition API)
- **构建工具**: Vite
- **UI 组件库**: Element Plus
- **HTTP 客户端**: Axios
- **路由管理**: Vue Router 4
- **开发语言**: JavaScript (可后续升级 TypeScript)

### 后端集成
- **API 基础地址**: `http://localhost:8000/api/v1`
- **跨域配置**: 后端已启用 CORS，支持前端访问
- **数据格式**: JSON
- **错误处理**: 基于 HTTP 状态码

## 🏗️ 技术约束

### 环境要求
- Node.js >= 16.0.0
- npm 或 yarn 包管理器
- 现代浏览器支持 (Chrome/Firefox/Safari/Edge)

### 集成约束
- 前端开发服务器: `http://localhost:3000`
- 后端 API 服务器: `http://localhost:8000`
- 无需修改后端代码，纯前端项目

### 性能约束
- 首次加载时间 < 3秒
- 界面响应时间 < 500ms
- 支持现代浏览器，无需 IE 兼容

## 📐 任务边界

### 包含功能
✅ **项目初始化**
- Vue 3 + Vite 项目搭建
- Element Plus UI 框架集成
- 基础路由配置
- Axios HTTP 客户端配置

✅ **用户管理模块**
- 用户列表展示 (表格)
- 新增用户表单
- 编辑用户功能
- 删除用户功能
- 基础表单验证

✅ **产品管理模块**
- 产品列表展示 (表格)
- 新增产品表单
- 编辑产品功能
- 删除产品功能
- 基础表单验证

✅ **界面布局**
- 响应式侧边栏导航
- 顶部导航栏
- 内容主区域
- 基础页面样式

✅ **用户体验**
- 操作成功/失败提示
- 加载状态指示
- 表单验证提示
- 确认删除对话框

### 不包含功能
❌ 用户认证和权限管理
❌ 数据搜索和过滤
❌ 分页处理
❌ 批量操作
❌ 数据导出功能
❌ 实时数据更新
❌ 复杂数据可视化
❌ 移动端优化
❌ 国际化支持

## ✅ 验收标准

### 功能验收
1. **项目启动**: `npm run dev` 成功启动，访问 http://localhost:3000
2. **用户管理**: 能够查看、新增、编辑、删除用户
3. **产品管理**: 能够查看、新增、编辑、删除产品
4. **API 集成**: 所有操作能够正确调用后端 API
5. **错误处理**: 网络错误和业务错误有适当提示
6. **界面美观**: 使用 Element Plus 组件，界面整洁美观

### 技术验收
1. **代码规范**: 遵循 Vue 3 最佳实践
2. **组件化**: 合理的组件拆分和复用
3. **响应式**: 支持桌面端和平板端访问
4. **性能**: 页面加载和操作响应流畅
5. **兼容性**: 支持主流现代浏览器

### 质量验收
1. **代码质量**: 结构清晰，注释适当
2. **错误处理**: 完善的异常处理机制
3. **用户体验**: 操作流畅，反馈及时
4. **可维护性**: 代码模块化，易于扩展

## 📊 数据模型接口

### 用户 API
```typescript
// 用户数据结构
interface User {
  id: number
  username: string
  email: string
  full_name?: string
  is_active: boolean
}

// 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
```typescript
// 产品数据结构
interface Product {
  id: number
  name: string
  description?: string
  price: number
  stock: number
  is_available: boolean
}

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

## 🔧 开发约定

### 目录结构
```
frontend/
├── src/
│   ├── components/     # 通用组件
│   ├── views/         # 页面组件
│   ├── api/           # API 接口定义
│   ├── utils/         # 工具函数
│   ├── router/        # 路由配置
│   ├── styles/        # 全局样式
│   └── main.js        # 应用入口
├── public/            # 静态资源
├── package.json       # 项目配置
└── vite.config.js     # 构建配置
```

### 代码规范
- 使用 Vue 3 Composition API
- 组件名使用 PascalCase
- 文件名使用 kebab-case
- 接口调用统一使用 async/await
- 错误处理使用 try-catch

### 提交规范
- 功能开发完成后进行提交
- 提交信息使用中文，描述清晰
- 不提交 node_modules 和构建产物

## 🚀 项目交付物

1. **前端项目代码**: 完整的 Vue 3 项目
2. **开发文档**: README.md 包含启动和开发说明
3. **依赖配置**: package.json 包含所有必要依赖
4. **构建配置**: vite.config.js 开发和构建配置
5. **部署说明**: 简单的部署指导