212 lines
5.8 KiB
Markdown
212 lines
5.8 KiB
Markdown
# CONSENSUS - 完善 CRUD API 功能共识文档
|
|
|
|
## 明确的需求描述
|
|
|
|
### 核心目标
|
|
将现有基于内存假数据的 FastAPI 项目转换为基于 MySQL 数据库的完整 CRUD 系统，实现 Users 和 Products 的完整增删改查操作。
|
|
|
|
### 具体功能需求
|
|
|
|
#### Users API 完善
|
|
- **POST /api/v1/users/** - 创建新用户
|
|
- **PUT /api/v1/users/{id}** - 更新用户信息
|
|
- **DELETE /api/v1/users/{id}** - 删除用户
|
|
|
|
#### Products API 完善
|
|
- **POST /api/v1/products/** - 创建新产品
|
|
- **PUT /api/v1/products/{id}** - 更新产品信息
|
|
- **DELETE /api/v1/products/{id}** - 删除产品
|
|
|
|
#### 数据持久化
|
|
- 完全移除内存假数据 (`fake_users_db`, `fake_products_db`)
|
|
- 所有操作直接与 MySQL 数据库交互
|
|
- 使用 SQLAlchemy ORM 进行数据库操作
|
|
|
|
## 技术实现方案
|
|
|
|
### 已确认的技术决策
|
|
|
|
#### 1. 数据验证策略 ✅
|
|
- **Pydantic 层**: 数据类型和格式验证
|
|
- **服务层**: 业务规则验证（邮箱唯一性、产品名称等）
|
|
- **数据库层**: 约束验证（主键、外键、唯一索引）
|
|
|
|
#### 2. 错误处理方式 ✅
|
|
- 提供详细错误信息，便于调试
|
|
- 标准 HTTP 状态码
|
|
- 结构化错误响应
|
|
|
|
#### 3. 数据库会话管理 ✅
|
|
- 使用 FastAPI 依赖注入机制
|
|
- `get_db()` 依赖函数管理会话生命周期
|
|
- 自动会话关闭和异常处理
|
|
|
|
#### 4. API 响应格式 ✅
|
|
- 保持现有代码风格
|
|
- 直接返回 Pydantic 模型
|
|
- 无需额外响应包装
|
|
|
|
#### 5. 初始数据策略 ✅
|
|
- **不保留**假数据
|
|
- 移除所有内存数据初始化
|
|
- 从空数据库开始
|
|
|
|
## 技术约束
|
|
|
|
### 框架和库约束
|
|
- **FastAPI**: 保持现有路由结构 `/api/v1/`
|
|
- **SQLAlchemy**: 使用现有数据库模型
|
|
- **Pydantic**: 使用现有模式定义
|
|
- **MySQL**: 连接现有 `fast_demo` 数据库
|
|
|
|
### 代码规范约束
|
|
- 保持现有项目结构和命名约定
|
|
- 遵循现有代码风格和注释规范
|
|
- 保持现有错误处理模式
|
|
- 使用现有依赖包版本
|
|
|
|
### 架构约束
|
|
- 维持分层架构: API层 → 服务层 → 数据库层
|
|
- 保持应用工厂模式
|
|
- 使用现有配置管理系统
|
|
|
|
## 集成方案
|
|
|
|
### 数据库集成
|
|
- 利用现有 SQLAlchemy 配置
|
|
- 复用现有数据库连接池
|
|
- 使用现有模型定义 (`app/database/models.py`)
|
|
|
|
### API 集成
|
|
- 扩展现有路由文件
|
|
- 保持现有 API 版本控制
|
|
- 维持现有中间件配置
|
|
|
|
### 依赖注入集成
|
|
```python
|
|
# 复用现有数据库依赖
|
|
from app.database.connection import get_db
|
|
from sqlalchemy.orm import Session
|
|
|
|
@router.post("/users/", response_model=UserResponse, status_code=201)
|
|
async def create_user(user: UserCreate, db: Session = Depends(get_db)):
|
|
return user_service.create_user(db, user)
|
|
```
|
|
|
|
## 任务边界限制
|
|
|
|
### 包含范围 ✅
|
|
- Users 和 Products 完整 CRUD API
|
|
- 数据库持久化操作
|
|
- 基础数据验证和错误处理
|
|
- API 文档自动更新
|
|
- 基础功能测试
|
|
|
|
### 排除范围 ❌
|
|
- 用户认证和授权系统
|
|
- API 限流和缓存机制
|
|
- 分页、排序、过滤功能
|
|
- 文件上传处理
|
|
- 复杂业务逻辑验证
|
|
- 性能优化和索引调优
|
|
|
|
## 验收标准
|
|
|
|
### 功能验收标准
|
|
|
|
#### Users API 验收
|
|
- [ ] **POST /api/v1/users/**
|
|
- 成功创建返回 201 状态码
|
|
- 返回创建的用户信息
|
|
- 数据持久化到数据库
|
|
- 邮箱唯一性验证
|
|
- 用户名唯一性验证
|
|
|
|
- [ ] **PUT /api/v1/users/{id}**
|
|
- 成功更新返回 200 状态码
|
|
- 支持部分字段更新
|
|
- 数据持久化到数据库
|
|
- 用户不存在返回 404
|
|
|
|
- [ ] **DELETE /api/v1/users/{id}**
|
|
- 成功删除返回 204 状态码
|
|
- 数据从数据库中删除
|
|
- 用户不存在返回 404
|
|
|
|
#### Products API 验收
|
|
- [ ] **POST /api/v1/products/**
|
|
- 成功创建返回 201 状态码
|
|
- 返回创建的产品信息
|
|
- 数据持久化到数据库
|
|
- 价格和库存数据验证
|
|
|
|
- [ ] **PUT /api/v1/products/{id}**
|
|
- 成功更新返回 200 状态码
|
|
- 支持部分字段更新
|
|
- 数据持久化到数据库
|
|
- 产品不存在返回 404
|
|
|
|
- [ ] **DELETE /api/v1/products/{id}**
|
|
- 成功删除返回 204 状态码
|
|
- 数据从数据库中删除
|
|
- 产品不存在返回 404
|
|
|
|
### 数据验证验收
|
|
- [ ] 必填字段验证 (422 状态码)
|
|
- [ ] 数据类型验证 (422 状态码)
|
|
- [ ] 邮箱格式验证 (422 状态码)
|
|
- [ ] 唯一性约束验证 (409 状态码)
|
|
- [ ] 数值范围验证 (价格 > 0)
|
|
|
|
### 错误处理验收
|
|
- [ ] 资源不存在: 404 Not Found
|
|
- [ ] 数据验证失败: 422 Unprocessable Entity
|
|
- [ ] 唯一性冲突: 409 Conflict
|
|
- [ ] 数据库连接错误: 500 Internal Server Error
|
|
- [ ] 详细错误信息返回
|
|
|
|
### 技术质量验收
|
|
- [ ] 所有内存假数据已移除
|
|
- [ ] 数据库会话正确管理
|
|
- [ ] 无内存或连接泄漏
|
|
- [ ] 事务处理正确实现
|
|
- [ ] 代码符合现有规范
|
|
- [ ] API 文档自动生成正确
|
|
|
|
### 集成验收
|
|
- [ ] 现有 GET API 正常工作
|
|
- [ ] 应用启动无错误
|
|
- [ ] 数据库连接正常
|
|
- [ ] 与现有代码无冲突
|
|
- [ ] 环境配置兼容
|
|
|
|
## 确认的关键假设
|
|
|
|
1. **数据库状态**: MySQL 数据库 `fast_demo` 已存在且可连接
|
|
2. **表结构**: SQLAlchemy 模型与数据库表结构一致
|
|
3. **权限**: 数据库用户具有完整 CRUD 权限
|
|
4. **环境**: 开发环境配置正确且稳定
|
|
5. **依赖**: 所有必要的 Python 包已安装
|
|
|
|
## 风险评估
|
|
|
|
### 低风险 🟢
|
|
- API 端点实现 (基于现有模式)
|
|
- 数据库 CRUD 操作 (SQLAlchemy 标准操作)
|
|
- 基础数据验证 (Pydantic 支持)
|
|
|
|
### 中等风险 🟡
|
|
- 数据库事务管理 (需要正确的异常处理)
|
|
- 唯一性约束冲突处理 (需要适当的错误映射)
|
|
|
|
### 已缓解风险 ✅
|
|
- 数据库连接问题 (已验证连接正常)
|
|
- 模型定义不匹配 (已确认 SQLAlchemy 模型)
|
|
- 配置环境问题 (已确认多环境配置)
|
|
|
|
---
|
|
|
|
**共识确认**: ✅ 所有关键决策点已确认
|
|
**创建时间**: 2025-09-28
|
|
**最后更新**: 2025-09-28
|
|
**状态**: 已批准，准备进入架构阶段 |