python-test
/
fastapi-demo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
fastapi-demo/docs/frontend-ui/CONSENSUS_frontend-ui.md

5.1 KiB
Raw Permalink Blame History

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

// 用户数据结构
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

// 产品数据结构
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. 部署说明: 简单的部署指导