193 lines
5.1 KiB
Markdown
193 lines
5.1 KiB
Markdown
# 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. **部署说明**: 简单的部署指导 |