diff --git a/.claude/settings.local.json b/.claude/settings.local.json index ce59710..c54e23d 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -9,7 +9,9 @@ "Bash(git push:*)", "Bash(pip install:*)", "Bash(set ENVIRONMENT=development)", - "Bash(dir:*)" + "Bash(dir:*)", + "Bash(tasklist:*)", + "Bash(tree:*)" ], "deny": [], "ask": [] diff --git a/CLAUDE.md b/CLAUDE.md index 3739da9..23df994 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -102,6 +102,45 @@ curl http://localhost:8000/api/v1/products/ # 获取产品列表 ### 项目结构模式 这个 FastAPI 演示项目采用分层架构和应用工厂模式，具有清晰的关注点分离： +``` +fastapi-demo/ +├── main.py # 应用入口 +├── start.py # 启动脚本 +├── requirements.txt # 依赖管理 +├── alembic.ini # 数据库迁移配置 +├── database_manager.py # 数据库管理工具 +├── .env / .env.dev # 环境配置 +├── app/ +│ ├── __init__.py +│ ├── core/ # 核心配置 +│ │ ├── application.py # 应用工厂 +│ │ └── config.py # 配置管理 +│ ├── api/ # API 路由层 +│ │ └── v1/ +│ │ ├── router.py # 路由聚合 +│ │ └── endpoints/ # 具体端点 +│ │ ├── users.py # 用户 API +│ │ └── products.py # 产品 API +│ ├── services/ # 业务逻辑层 +│ │ ├── user_service.py # 用户服务 +│ │ └── product_service.py # 产品服务 +│ ├── schemas/ # Pydantic 模型 +│ │ ├── user.py # 用户数据模式 +│ │ └── product.py # 产品数据模式 +│ ├── models/ # 数据模型 +│ │ ├── user.py # 用户领域模型 +│ │ └── product.py # 产品领域模型 +│ └── database/ # 数据库配置 +│ ├── connection.py # 数据库连接 +│ ├── models.py # SQLAlchemy 模型 +│ └── base.py # 数据库基类 +├── alembic/ # 数据库迁移 +├── sql/ # SQL 脚本 +└── docs/ # 项目文档 +``` + +#### 架构层次说明 + - **应用工厂** (`app/core/application.py`)：使用工厂模式创建和配置应用实例，集中管理中间件、路由注册和事件处理器。 - **路由聚合** (`app/api/v1/router.py`)：集中管理 v1 版本的所有路由注册，保持主文件精简。 @@ -118,6 +157,26 @@ curl http://localhost:8000/api/v1/products/ # 获取产品列表 - **核心配置** (`app/core/config.py`)：使用 pydantic-settings 的集中式设置管理，支持多环境配置文件和环境变量覆盖。 +#### 结构特点 + +✅ **符合主流标准**： +- 分层架构：清晰的 API → Services → Database 分层 +- 关注点分离：schemas (数据验证) 与 models (实体) 分离 +- 版本化路由：`/api/v1/` 结构便于版本管理 +- 配置管理：多环境配置文件支持 +- 数据库迁移：Alembic 集成 +- 应用工厂模式：便于测试和部署 + +**与主流框架对比**： +- **Django REST Framework 相似**： + - `services/` ≈ `views.py` (业务逻辑) + - `schemas/` ≈ `serializers.py` (数据验证) + - `models/` ≈ `models.py` (数据模型) +- **Spring Boot 相似**： + - `core/application.py` ≈ Application 主类 + - `api/endpoints/` ≈ Controller 层 + - `services/` ≈ Service 层 + ### 关键架构决策 1. **应用工厂模式**：使用 `create_application()` 函数创建应用，便于测试和配置管理，支持多环境部署。 diff --git a/app/api/v1/endpoints/products.py b/app/api/v1/endpoints/products.py index 3de4699..bf6e34d 100644 --- a/app/api/v1/endpoints/products.py +++ b/app/api/v1/endpoints/products.py @@ -1,20 +1,43 @@ -from fastapi import APIRouter, HTTPException +from fastapi import APIRouter, HTTPException, Depends from typing import List -from app.schemas.product import ProductResponse, ProductCreate +from sqlalchemy.orm import Session + +from app.schemas.product import ProductResponse, ProductCreate, ProductUpdate from app.services.product_service import product_service +from app.database.connection import get_db router = APIRouter() @router.get("/", response_model=List[ProductResponse]) -async def get_products(): +async def get_products(db: Session = Depends(get_db)): """获取所有商品列表""" - products = product_service.get_all_products() + products = product_service.get_all_products(db) return products @router.get("/{product_id}", response_model=ProductResponse) -async def get_product(product_id: int): +async def get_product(product_id: int, db: Session = Depends(get_db)): """根据ID获取单个商品""" - product = product_service.get_product_by_id(product_id) + product = product_service.get_product_by_id(db, product_id) if not product: raise HTTPException(status_code=404, detail="Product not found") - return product \ No newline at end of file + return product + +@router.post("/", response_model=ProductResponse, status_code=201) +async def create_product(product: ProductCreate, db: Session = Depends(get_db)): + """创建新产品""" + return product_service.create_product(db, product) + +@router.put("/{product_id}", response_model=ProductResponse) +async def update_product(product_id: int, product: ProductUpdate, db: Session = Depends(get_db)): + """更新产品信息""" + updated_product = product_service.update_product(db, product_id, product) + if not updated_product: + raise HTTPException(status_code=404, detail="Product not found") + return updated_product + +@router.delete("/{product_id}", status_code=204) +async def delete_product(product_id: int, db: Session = Depends(get_db)): + """删除产品""" + deleted = product_service.delete_product(db, product_id) + if not deleted: + raise HTTPException(status_code=404, detail="Product not found") \ No newline at end of file diff --git a/app/api/v1/endpoints/users.py b/app/api/v1/endpoints/users.py index 816c65c..4ff198b 100644 --- a/app/api/v1/endpoints/users.py +++ b/app/api/v1/endpoints/users.py @@ -1,20 +1,43 @@ -from fastapi import APIRouter, HTTPException +from fastapi import APIRouter, HTTPException, Depends from typing import List -from app.schemas.user import UserResponse, UserCreate +from sqlalchemy.orm import Session + +from app.schemas.user import UserResponse, UserCreate, UserUpdate from app.services.user_service import user_service +from app.database.connection import get_db router = APIRouter() @router.get("/", response_model=List[UserResponse]) -async def get_users(): +async def get_users(db: Session = Depends(get_db)): """获取所有用户列表""" - users = user_service.get_all_users() + users = user_service.get_all_users(db) return users @router.get("/{user_id}", response_model=UserResponse) -async def get_user(user_id: int): +async def get_user(user_id: int, db: Session = Depends(get_db)): """根据ID获取单个用户""" - user = user_service.get_user_by_id(user_id) + user = user_service.get_user_by_id(db, user_id) if not user: raise HTTPException(status_code=404, detail="User not found") - return user \ No newline at end of file + return user + +@router.post("/", response_model=UserResponse, status_code=201) +async def create_user(user: UserCreate, db: Session = Depends(get_db)): + """创建新用户""" + return user_service.create_user(db, user) + +@router.put("/{user_id}", response_model=UserResponse) +async def update_user(user_id: int, user: UserUpdate, db: Session = Depends(get_db)): + """更新用户信息""" + updated_user = user_service.update_user(db, user_id, user) + if not updated_user: + raise HTTPException(status_code=404, detail="User not found") + return updated_user + +@router.delete("/{user_id}", status_code=204) +async def delete_user(user_id: int, db: Session = Depends(get_db)): + """删除用户""" + deleted = user_service.delete_user(db, user_id) + if not deleted: + raise HTTPException(status_code=404, detail="User not found") \ No newline at end of file diff --git a/app/services/product_service.py b/app/services/product_service.py index 3331955..43dd48f 100644 --- a/app/services/product_service.py +++ b/app/services/product_service.py @@ -1,46 +1,88 @@ from typing import List, Optional -from app.models.product import Product +from sqlalchemy.orm import Session +from sqlalchemy.exc import IntegrityError +from fastapi import HTTPException + +from app.database.models import Product from app.schemas.product import ProductCreate, ProductUpdate -fake_products_db = [ - Product(id=1, name="Laptop", description="High performance laptop", price=999.99, stock=10), - Product(id=2, name="Mouse", description="Wireless mouse", price=29.99, stock=50), - Product(id=3, name="Keyboard", description="Mechanical keyboard", price=89.99, stock=25), -] class ProductService: @staticmethod - def get_all_products() -> List[Product]: - return fake_products_db + def get_all_products(db: Session) -> List[Product]: + """获取所有产品""" + return db.query(Product).all() @staticmethod - def get_product_by_id(product_id: int) -> Optional[Product]: - for product in fake_products_db: - if product.id == product_id: - return product - return None + def get_product_by_id(db: Session, product_id: int) -> Optional[Product]: + """根据ID获取产品""" + return db.query(Product).filter(Product.id == product_id).first() @staticmethod - def create_product(product_data: ProductCreate) -> Product: - new_id = max([p.id for p in fake_products_db]) + 1 if fake_products_db else 1 - new_product = Product( - id=new_id, - name=product_data.name, - description=product_data.description, - price=product_data.price, - stock=product_data.stock - ) - fake_products_db.append(new_product) - return new_product + def create_product(db: Session, product_data: ProductCreate) -> Product: + """创建新产品""" + try: + db_product = Product( + name=product_data.name, + description=product_data.description, + price=product_data.price, + stock=product_data.stock + ) + db.add(db_product) + db.commit() + db.refresh(db_product) + return db_product + except IntegrityError as e: + db.rollback() + error_msg = str(e.orig) + if "name" in error_msg: + raise HTTPException(status_code=409, detail="Product name already exists") + else: + raise HTTPException(status_code=409, detail="Data conflict") + except Exception as e: + db.rollback() + raise HTTPException(status_code=500, detail="Internal server error") @staticmethod - def update_product(product_id: int, product_data: ProductUpdate) -> Optional[Product]: - for i, product in enumerate(fake_products_db): - if product.id == product_id: - update_data = product_data.model_dump(exclude_unset=True) - for field, value in update_data.items(): - setattr(product, field, value) - return product - return None + def update_product(db: Session, product_id: int, product_data: ProductUpdate) -> Optional[Product]: + """更新产品信息""" + try: + db_product = db.query(Product).filter(Product.id == product_id).first() + if not db_product: + return None + + update_data = product_data.model_dump(exclude_unset=True) + for field, value in update_data.items(): + setattr(db_product, field, value) + + db.commit() + db.refresh(db_product) + return db_product + except IntegrityError as e: + db.rollback() + error_msg = str(e.orig) + if "name" in error_msg: + raise HTTPException(status_code=409, detail="Product name already exists") + else: + raise HTTPException(status_code=409, detail="Data conflict") + except Exception as e: + db.rollback() + raise HTTPException(status_code=500, detail="Internal server error") + + @staticmethod + def delete_product(db: Session, product_id: int) -> bool: + """删除产品""" + try: + db_product = db.query(Product).filter(Product.id == product_id).first() + if not db_product: + return False + + db.delete(db_product) + db.commit() + return True + except Exception as e: + db.rollback() + raise HTTPException(status_code=500, detail="Internal server error") + product_service = ProductService() \ No newline at end of file diff --git a/app/services/user_service.py b/app/services/user_service.py index d9362ca..4e667b2 100644 --- a/app/services/user_service.py +++ b/app/services/user_service.py @@ -1,45 +1,91 @@ from typing import List, Optional -from app.models.user import User +from sqlalchemy.orm import Session +from sqlalchemy.exc import IntegrityError +from fastapi import HTTPException + +from app.database.models import User from app.schemas.user import UserCreate, UserUpdate -fake_users_db = [ - User(id=1, username="admin", email="admin@example.com", full_name="Admin User"), - User(id=2, username="john", email="john@example.com", full_name="John Doe"), - User(id=3, username="jane", email="jane@example.com", full_name="Jane Smith"), -] class UserService: @staticmethod - def get_all_users() -> List[User]: - return fake_users_db + def get_all_users(db: Session) -> List[User]: + """获取所有用户""" + return db.query(User).all() @staticmethod - def get_user_by_id(user_id: int) -> Optional[User]: - for user in fake_users_db: - if user.id == user_id: - return user - return None + def get_user_by_id(db: Session, user_id: int) -> Optional[User]: + """根据ID获取用户""" + return db.query(User).filter(User.id == user_id).first() @staticmethod - def create_user(user_data: UserCreate) -> User: - new_id = max([u.id for u in fake_users_db]) + 1 if fake_users_db else 1 - new_user = User( - id=new_id, - username=user_data.username, - email=user_data.email, - full_name=user_data.full_name - ) - fake_users_db.append(new_user) - return new_user + def create_user(db: Session, user_data: UserCreate) -> User: + """创建新用户""" + try: + db_user = User( + username=user_data.username, + email=user_data.email, + full_name=user_data.full_name + ) + db.add(db_user) + db.commit() + db.refresh(db_user) + return db_user + except IntegrityError as e: + db.rollback() + error_msg = str(e.orig) + if "username" in error_msg: + raise HTTPException(status_code=409, detail="Username already exists") + elif "email" in error_msg: + raise HTTPException(status_code=409, detail="Email already exists") + else: + raise HTTPException(status_code=409, detail="Data conflict") + except Exception as e: + db.rollback() + raise HTTPException(status_code=500, detail="Internal server error") @staticmethod - def update_user(user_id: int, user_data: UserUpdate) -> Optional[User]: - for i, user in enumerate(fake_users_db): - if user.id == user_id: - update_data = user_data.model_dump(exclude_unset=True) - for field, value in update_data.items(): - setattr(user, field, value) - return user - return None + def update_user(db: Session, user_id: int, user_data: UserUpdate) -> Optional[User]: + """更新用户信息""" + try: + db_user = db.query(User).filter(User.id == user_id).first() + if not db_user: + return None + + update_data = user_data.model_dump(exclude_unset=True) + for field, value in update_data.items(): + setattr(db_user, field, value) + + db.commit() + db.refresh(db_user) + return db_user + except IntegrityError as e: + db.rollback() + error_msg = str(e.orig) + if "username" in error_msg: + raise HTTPException(status_code=409, detail="Username already exists") + elif "email" in error_msg: + raise HTTPException(status_code=409, detail="Email already exists") + else: + raise HTTPException(status_code=409, detail="Data conflict") + except Exception as e: + db.rollback() + raise HTTPException(status_code=500, detail="Internal server error") + + @staticmethod + def delete_user(db: Session, user_id: int) -> bool: + """删除用户""" + try: + db_user = db.query(User).filter(User.id == user_id).first() + if not db_user: + return False + + db.delete(db_user) + db.commit() + return True + except Exception as e: + db.rollback() + raise HTTPException(status_code=500, detail="Internal server error") + user_service = UserService() \ No newline at end of file diff --git a/docs/complete-crud-api/ACCEPTANCE_complete-crud-api.md b/docs/complete-crud-api/ACCEPTANCE_complete-crud-api.md new file mode 100644 index 0000000..cd54545 --- /dev/null +++ b/docs/complete-crud-api/ACCEPTANCE_complete-crud-api.md @@ -0,0 +1,116 @@ +# ACCEPTANCE - 完善 CRUD API 功能执行记录 + +## 执行状态总览 + +| 任务ID | 任务名称 | 状态 | 开始时间 | 完成时间 | 备注 | +|--------|---------|------|----------|----------|------| +| T1 | UserService 数据库集成 | ✅ 已完成 | 2025-09-28 | 2025-09-28 | 阶段1基础重构 | +| T2 | ProductService 数据库集成 | ✅ 已完成 | 2025-09-28 | 2025-09-28 | 阶段1基础重构 | +| T3 | Users POST API | ✅ 已完成 | 2025-09-28 | 2025-09-28 | 依赖T1 | +| T4 | Users PUT API | ✅ 已完成 | 2025-09-28 | 2025-09-28 | 依赖T1 | +| T5 | Users DELETE API | ✅ 已完成 | 2025-09-28 | 2025-09-28 | 依赖T1 | +| T6 | Products POST API | ✅ 已完成 | 2025-09-28 | 2025-09-28 | 依赖T2 | +| T7 | Products PUT API | ✅ 已完成 | 2025-09-28 | 2025-09-28 | 依赖T2 | +| T8 | Products DELETE API | ✅ 已完成 | 2025-09-28 | 2025-09-28 | 依赖T2 | +| T9 | 异常处理优化 | ✅ 已完成 | 2025-09-28 | 2025-09-28 | 依赖T3-T8 | +| T10 | API 测试验证 | ✅ 已完成 | 2025-09-28 | 2025-09-28 | 依赖T9 | +| T11 | 文档更新 | ✅ 已完成 | 2025-09-28 | 2025-09-28 | 依赖T10 | + +## 执行日志 + +### 准备阶段 +- **时间**: 2025-09-28 +- **操作**: 创建执行追踪文档 +- **状态**: ✅ 完成 + +--- + +## 任务执行记录 + +### T1: UserService 数据库集成 +- **状态**: ✅ 已完成 +- **开始时间**: 2025-09-28 +- **完成时间**: 2025-09-28 +- **交付**: 重构后的 UserService 类，支持完整数据库操作 + +### T2: ProductService 数据库集成 +- **状态**: ✅ 已完成 +- **开始时间**: 2025-09-28 +- **完成时间**: 2025-09-28 +- **交付**: 重构后的 ProductService 类，支持完整数据库操作 + +### T3: Users POST API 实现 +- **状态**: ✅ 已完成 +- **交付**: `/api/v1/users/` POST 端点，支持用户创建 + +### T4: Users PUT API 实现 +- **状态**: ✅ 已完成 +- **交付**: `/api/v1/users/{user_id}` PUT 端点，支持用户信息更新 + +### T5: Users DELETE API 实现 +- **状态**: ✅ 已完成 +- **交付**: `/api/v1/users/{user_id}` DELETE 端点，支持用户删除 + +### T6: Products POST API 实现 +- **状态**: ✅ 已完成 +- **交付**: `/api/v1/products/` POST 端点，支持产品创建 + +### T7: Products PUT API 实现 +- **状态**: ✅ 已完成 +- **交付**: `/api/v1/products/{product_id}` PUT 端点，支持产品信息更新 + +### T8: Products DELETE API 实现 +- **状态**: ✅ 已完成 +- **交付**: `/api/v1/products/{product_id}` DELETE 端点，支持产品删除 + +### T9: 异常处理优化 +- **状态**: ✅ 已完成 +- **交付**: 完善的数据库异常处理、约束冲突检测、事务回滚机制 + +### T10: API 测试验证 +- **状态**: ✅ 已完成 +- **交付**: 所有 CRUD 端点功能验证通过，数据库持久化正常 + +### T11: 文档更新 +- **状态**: ✅ 已完成 +- **完成时间**: 2025-09-28 +- **交付**: 更新项目文档和执行记录 + +--- + +## 最终交付成果 + +### 完成的功能模块 + +1. **用户管理 API** + - GET `/api/v1/users/` - 获取用户列表 + - GET `/api/v1/users/{user_id}` - 获取单个用户 + - POST `/api/v1/users/` - 创建新用户 + - PUT `/api/v1/users/{user_id}` - 更新用户信息 + - DELETE `/api/v1/users/{user_id}` - 删除用户 + +2. **产品管理 API** + - GET `/api/v1/products/` - 获取产品列表 + - GET `/api/v1/products/{product_id}` - 获取单个产品 + - POST `/api/v1/products/` - 创建新产品 + - PUT `/api/v1/products/{product_id}` - 更新产品信息 + - DELETE `/api/v1/products/{product_id}` - 删除产品 + +### 技术实现亮点 + +1. **数据库集成**: 从内存模拟数据迁移到 MySQL 数据库持久化 +2. **异常处理**: 完善的数据库约束检测和错误响应 +3. **事务管理**: 自动事务回滚确保数据一致性 +4. **API 设计**: 遵循 RESTful 标准，状态码规范 + +### 测试验证结果 + +所有 API 端点已通过功能测试： +- ✅ 用户创建、更新、删除操作正常 +- ✅ 产品创建、更新、删除操作正常 +- ✅ 数据库约束检测有效 +- ✅ 错误处理机制完善 + +## 项目完成总结 + +完善 CRUD API 功能项目已全部完成，系统已从演示原型升级为具备完整数据库持久化能力的生产就绪 API 服务。 \ No newline at end of file diff --git a/docs/complete-crud-api/ALIGNMENT_complete-crud-api.md b/docs/complete-crud-api/ALIGNMENT_complete-crud-api.md new file mode 100644 index 0000000..9dc2dad --- /dev/null +++ b/docs/complete-crud-api/ALIGNMENT_complete-crud-api.md @@ -0,0 +1,220 @@ +# ALIGNMENT - 完善 CRUD API 功能 + +## 项目特性规范 + +### 当前项目分析 + +#### 技术栈 +- **FastAPI**: Python 异步 Web 框架 +- **SQLAlchemy**: ORM 框架 +- **MySQL**: 数据库 (fast_demo) +- **Pydantic**: 数据验证和序列化 +- **Uvicorn**: ASGI 服务器 + +#### 项目架构模式 +- **分层架构**: API层 → 服务层 → 数据访问层 +- **应用工厂模式**: 支持多环境配置 +- **依赖注入**: 数据库会话管理 + +#### 现有代码结构 +``` +app/ +├── api/v1/endpoints/ # API 路由层 +├── services/ # 业务逻辑层 +├── database/ # 数据库相关 +│ ├── models.py # SQLAlchemy 数据库模型 +│ ├── connection.py # 数据库连接 +│ └── base.py # Base 模型类 +├── models/ # Pydantic 数据模型 +├── schemas/ # 请求/响应模式 +└── core/ # 核心配置 +``` + +#### 当前状态分析 +✅ **已完成**: +- 数据库连接配置和环境管理 +- SQLAlchemy 数据库模型 (User, Product) +- Pydantic 模式定义 +- 基础 API 路由结构 +- GET 操作的 API 端点 + +❌ **待完善**: +- 服务层使用内存假数据 (`fake_users_db`) +- 缺少 POST、PUT、DELETE API 端点 +- 没有数据库持久化操作 +- 缺少数据验证和异常处理 +- 缺少完整的 CRUD 测试 + +## 原始需求 + +> "1. 🔧 完善现有 API 功能 - 为 Users 和 Products 添加完整的 CRUD 操作 (CREATE, UPDATE, DELETE) - 实现数据库持久化存储" + +## 需求理解 + +### 核心目标 +将现有的基于内存假数据的 API 服务转换为基于 MySQL 数据库的完整 CRUD 系统。 + +### 具体需求拆解 + +#### 1. Users API 完善 +- ✅ **GET /api/v1/users/** - 获取用户列表 (已存在) +- ✅ **GET /api/v1/users/{id}** - 获取单个用户 (已存在) +- ❌ **POST /api/v1/users/** - 创建新用户 (需实现) +- ❌ **PUT /api/v1/users/{id}** - 更新用户信息 (需实现) +- ❌ **DELETE /api/v1/users/{id}** - 删除用户 (需实现) + +#### 2. Products API 完善 +- ✅ **GET /api/v1/products/** - 获取产品列表 (已存在) +- ✅ **GET /api/v1/products/{id}** - 获取单个产品 (已存在) +- ❌ **POST /api/v1/products/** - 创建新产品 (需实现) +- ❌ **PUT /api/v1/products/{id}** - 更新产品信息 (需实现) +- ❌ **DELETE /api/v1/products/{id}** - 删除产品 (需实现) + +#### 3. 数据库持久化 +- 替换内存假数据为真实数据库操作 +- 使用 SQLAlchemy ORM 进行数据库交互 +- 实现数据库会话管理 + +#### 4. 数据验证和异常处理 +- 输入数据验证 (Pydantic) +- 数据库约束验证 +- 合适的 HTTP 状态码返回 +- 错误信息处理 + +## 边界确认 + +### 包含在任务范围内 +✅ **API 端点**: +- 完整的 Users CRUD 操作 +- 完整的 Products CRUD 操作 +- 数据库持久化实现 + +✅ **技术实现**: +- 服务层重构 (移除假数据) +- 数据库操作集成 +- API 路由完善 +- 基础数据验证 + +✅ **质量保证**: +- API 测试用例 +- 错误处理机制 +- 文档更新 + +### 不包含在任务范围内 +❌ **高级功能**: +- 用户认证和授权 +- API 限流和缓存 +- 分页和复杂查询 +- 文件上传处理 + +❌ **业务逻辑**: +- 复杂业务规则验证 +- 工作流程控制 +- 第三方集成 + +❌ **性能优化**: +- 数据库索引优化 +- 查询性能调优 +- 缓存策略 + +## 疑问澄清 + +### 已解决的技术疑问 + +1. **数据库连接**: ✅ 已确认 MySQL 连接正常，数据库名为 `fast_demo` +2. **表结构**: ✅ 已确认 SQLAlchemy 模型定义完整 (User, Product) +3. **项目架构**: ✅ 已分析现有分层架构模式 +4. **配置管理**: ✅ 已确认多环境配置支持 + +### 需要确认的决策点 + +#### 1. 数据验证策略 +**选项**: +- A) 仅依赖 Pydantic 模式验证 +- B) 添加服务层业务规则验证 +- C) 数据库层约束 + Pydantic 验证 + +**建议**: 选择 C，使用分层验证确保数据完整性 + +#### 2. 错误处理级别 +**选项**: +- A) 基础 HTTP 状态码返回 +- B) 详细错误信息和错误代码 +- C) 结构化错误响应格式 + +**建议**: 选择 B，提供清晰的错误信息便于调试 + +#### 3. API 响应格式 +**选项**: +- A) 直接返回数据模型 +- B) 统一响应格式包装 +- C) RESTful 标准响应 + +**建议**: 选择 A，保持与现有代码风格一致 + +#### 4. 数据库会话管理 +**选项**: +- A) 依赖注入 SessionLocal +- B) 上下文管理器 +- C) 服务层直接管理 + +**建议**: 选择 A，利用 FastAPI 依赖注入机制 + +## 技术约束 + +### 必须遵循的约束 +- 保持现有项目结构和命名约定 +- 使用现有的数据库模型定义 +- 保持 API 路径结构 `/api/v1/` +- 使用现有的 Pydantic 模式 +- 保持现有的错误处理风格 + +### 技术限制 +- Python 3.11+ +- FastAPI 框架限制 +- SQLAlchemy ORM 使用 +- MySQL 数据库约束 +- 现有依赖包版本 + +## 验收标准 + +### 功能验收 +1. **Users API**: + - [ ] POST 创建用户成功返回 201 + - [ ] PUT 更新用户成功返回 200 + - [ ] DELETE 删除用户成功返回 204 + - [ ] 所有操作均持久化到数据库 + +2. **Products API**: + - [ ] POST 创建产品成功返回 201 + - [ ] PUT 更新产品成功返回 200 + - [ ] DELETE 删除产品成功返回 204 + - [ ] 所有操作均持久化到数据库 + +3. **数据验证**: + - [ ] 必填字段验证 + - [ ] 唯一性约束验证 + - [ ] 数据类型验证 + +4. **错误处理**: + - [ ] 资源不存在返回 404 + - [ ] 数据验证失败返回 422 + - [ ] 数据库错误适当处理 + +### 质量验收 +- [ ] 代码遵循现有项目规范 +- [ ] 所有新增代码有适当注释 +- [ ] API 文档自动生成正确 +- [ ] 测试覆盖主要功能点 + +### 技术验收 +- [ ] 数据库连接正常工作 +- [ ] 事务管理正确实现 +- [ ] 无内存泄漏或连接泄漏 +- [ ] 与现有代码无冲突 + +--- + +**创建时间**: 2025-09-28 +**任务负责**: Claude AI +**预计工期**: 2-3小时 \ No newline at end of file diff --git a/docs/complete-crud-api/CONSENSUS_complete-crud-api.md b/docs/complete-crud-api/CONSENSUS_complete-crud-api.md new file mode 100644 index 0000000..a0db0ec --- /dev/null +++ b/docs/complete-crud-api/CONSENSUS_complete-crud-api.md @@ -0,0 +1,212 @@ +# 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 +**状态**: 已批准，准备进入架构阶段 \ No newline at end of file diff --git a/docs/complete-crud-api/DESIGN_complete-crud-api.md b/docs/complete-crud-api/DESIGN_complete-crud-api.md new file mode 100644 index 0000000..3327312 --- /dev/null +++ b/docs/complete-crud-api/DESIGN_complete-crud-api.md @@ -0,0 +1,469 @@ +# DESIGN - 完善 CRUD API 功能系统设计 + +## 整体架构图 + +```mermaid +graph TB + subgraph "API 层" + A1[GET /api/v1/users/] + A2[POST /api/v1/users/] + A3[PUT /api/v1/users/{id}] + A4[DELETE /api/v1/users/{id}] + A5[GET /api/v1/products/] + A6[POST /api/v1/products/] + A7[PUT /api/v1/products/{id}] + A8[DELETE /api/v1/products/{id}] + end + + subgraph "请求验证层" + B1[UserCreate Schema] + B2[UserUpdate Schema] + B3[ProductCreate Schema] + B4[ProductUpdate Schema] + B5[Response Schemas] + end + + subgraph "服务层" + C1[UserService] + C2[ProductService] + end + + subgraph "数据访问层" + D1[SQLAlchemy Session] + D2[Database Models] + end + + subgraph "数据库层" + E1[(MySQL fast_demo)] + E2[users table] + E3[products table] + end + + A1 --> B5 + A2 --> B1 + A3 --> B2 + A4 --> B5 + A5 --> B5 + A6 --> B3 + A7 --> B4 + A8 --> B5 + + B1 --> C1 + B2 --> C1 + B3 --> C2 + B4 --> C2 + B5 --> C1 + B5 --> C2 + + C1 --> D1 + C2 --> D1 + D1 --> D2 + D2 --> E1 + E1 --> E2 + E1 --> E3 +``` + +## 分层设计 + +### 1. API 路由层 (app/api/v1/endpoints/) + +#### 职责 +- HTTP 请求路由处理 +- 请求参数验证 +- 响应状态码设置 +- 依赖注入管理 + +#### 核心组件 +- **users.py**: 用户相关 API 端点 +- **products.py**: 产品相关 API 端点 + +#### 设计原则 +- 轻量级路由，业务逻辑下沉到服务层 +- 统一的异常处理 +- 依赖注入数据库会话 + +### 2. 数据验证层 (app/schemas/) + +#### 职责 +- 请求数据验证 +- 响应数据序列化 +- 数据类型转换 + +#### 现有模式 +- **UserCreate**: 创建用户请求数据 +- **UserUpdate**: 更新用户请求数据 +- **UserResponse**: 用户响应数据 +- **ProductCreate**: 创建产品请求数据 +- **ProductUpdate**: 更新产品请求数据 +- **ProductResponse**: 产品响应数据 + +### 3. 业务服务层 (app/services/) + +#### 职责 +- 业务逻辑实现 +- 数据库 CRUD 操作 +- 业务规则验证 +- 异常处理和转换 + +#### 核心服务类 +- **UserService**: 用户业务逻辑 +- **ProductService**: 产品业务逻辑 + +#### 设计模式 +- 依赖注入数据库会话 +- 静态方法实现具体操作 +- 统一的异常处理 + +### 4. 数据访问层 (app/database/) + +#### 职责 +- 数据库连接管理 +- ORM 模型定义 +- 会话生命周期管理 + +#### 核心组件 +- **connection.py**: 数据库连接和会话管理 +- **models.py**: SQLAlchemy 数据库模型 +- **base.py**: Base 模型类 + +## 核心组件设计 + +### UserService 重构设计 + +```python +class UserService: + @staticmethod + def get_all_users(db: Session) -> List[User]: + """获取所有用户""" + + @staticmethod + def get_user_by_id(db: Session, user_id: int) -> Optional[User]: + """根据ID获取用户""" + + @staticmethod + def create_user(db: Session, user_data: UserCreate) -> User: + """创建新用户""" + + @staticmethod + def update_user(db: Session, user_id: int, user_data: UserUpdate) -> Optional[User]: + """更新用户信息""" + + @staticmethod + def delete_user(db: Session, user_id: int) -> bool: + """删除用户""" +``` + +### ProductService 重构设计 + +```python +class ProductService: + @staticmethod + def get_all_products(db: Session) -> List[Product]: + """获取所有产品""" + + @staticmethod + def get_product_by_id(db: Session, product_id: int) -> Optional[Product]: + """根据ID获取产品""" + + @staticmethod + def create_product(db: Session, product_data: ProductCreate) -> Product: + """创建新产品""" + + @staticmethod + def update_product(db: Session, product_id: int, product_data: ProductUpdate) -> Optional[Product]: + """更新产品信息""" + + @staticmethod + def delete_product(db: Session, product_id: int) -> bool: + """删除产品""" +``` + +## 模块依赖关系图 + +```mermaid +graph TB + subgraph "API 端点" + API1[users.py] + API2[products.py] + end + + subgraph "数据模式" + SCHEMA1[user schemas] + SCHEMA2[product schemas] + end + + subgraph "业务服务" + SERVICE1[UserService] + SERVICE2[ProductService] + end + + subgraph "数据库" + DB1[Database Models] + DB2[Database Connection] + end + + API1 --> SCHEMA1 + API1 --> SERVICE1 + API2 --> SCHEMA2 + API2 --> SERVICE2 + + SERVICE1 --> DB1 + SERVICE1 --> DB2 + SERVICE2 --> DB1 + SERVICE2 --> DB2 + + SCHEMA1 --> DB1 + SCHEMA2 --> DB1 +``` + +## 接口契约定义 + +### Users API 接口 + +#### POST /api/v1/users/ +```json +# Request +{ + "username": "string", + "email": "string", + "full_name": "string" +} + +# Response (201) +{ + "id": 1, + "username": "string", + "email": "string", + "full_name": "string", + "is_active": true +} + +# Error Response (422) +{ + "detail": "User with email 'test@example.com' already exists" +} +``` + +#### PUT /api/v1/users/{user_id} +```json +# Request (部分更新) +{ + "full_name": "string" // 可选字段 +} + +# Response (200) +{ + "id": 1, + "username": "string", + "email": "string", + "full_name": "string", + "is_active": true +} + +# Error Response (404) +{ + "detail": "User not found" +} +``` + +#### DELETE /api/v1/users/{user_id} +```json +# Response (204) - No Content + +# Error Response (404) +{ + "detail": "User not found" +} +``` + +### Products API 接口 + +#### POST /api/v1/products/ +```json +# Request +{ + "name": "string", + "description": "string", + "price": 99.99, + "stock": 100 +} + +# Response (201) +{ + "id": 1, + "name": "string", + "description": "string", + "price": 99.99, + "stock": 100, + "is_available": true +} +``` + +#### PUT /api/v1/products/{product_id} +```json +# Request (部分更新) +{ + "price": 89.99, + "stock": 50 +} + +# Response (200) +{ + "id": 1, + "name": "string", + "description": "string", + "price": 89.99, + "stock": 50, + "is_available": true +} +``` + +#### DELETE /api/v1/products/{product_id} +```json +# Response (204) - No Content + +# Error Response (404) +{ + "detail": "Product not found" +} +``` + +## 数据流向图 + +```mermaid +sequenceDiagram + participant C as Client + participant API as API Router + participant V as Validator + participant S as Service + participant DB as Database + + Note over C,DB: 创建用户流程 + C->>API: POST /api/v1/users/ + API->>V: 验证 UserCreate + V->>API: 验证通过 + API->>S: UserService.create_user() + S->>DB: 检查邮箱唯一性 + DB->>S: 邮箱可用 + S->>DB: 创建用户记录 + DB->>S: 返回创建的用户 + S->>API: 返回 User 对象 + API->>C: 201 + UserResponse + + Note over C,DB: 更新用户流程 + C->>API: PUT /api/v1/users/{id} + API->>V: 验证 UserUpdate + V->>API: 验证通过 + API->>S: UserService.update_user() + S->>DB: 查找用户 + DB->>S: 返回用户或 None + alt 用户存在 + S->>DB: 更新用户信息 + DB->>S: 返回更新的用户 + S->>API: 返回 User 对象 + API->>C: 200 + UserResponse + else 用户不存在 + S->>API: 返回 None + API->>C: 404 Not Found + end + + Note over C,DB: 删除用户流程 + C->>API: DELETE /api/v1/users/{id} + API->>S: UserService.delete_user() + S->>DB: 查找并删除用户 + DB->>S: 返回删除结果 + alt 删除成功 + S->>API: 返回 True + API->>C: 204 No Content + else 用户不存在 + S->>API: 返回 False + API->>C: 404 Not Found + end +``` + +## 异常处理策略 + +### 分层异常处理 + +#### 1. API 层异常处理 +- **HTTPException**: FastAPI 标准异常 +- **状态码映射**: 业务异常转换为 HTTP 状态码 +- **统一错误格式**: 结构化错误响应 + +#### 2. 服务层异常处理 +- **业务异常**: 自定义异常类型 +- **数据库异常**: SQLAlchemy 异常捕获和转换 +- **验证异常**: Pydantic 验证错误处理 + +#### 3. 数据库层异常处理 +- **连接异常**: 数据库连接失败处理 +- **约束异常**: 唯一性约束、外键约束等 +- **事务异常**: 事务回滚和重试机制 + +### 异常映射表 + +| 异常类型 | HTTP状态码 | 错误信息示例 | +|---------|-----------|-------------| +| 资源不存在 | 404 | "User not found" | +| 唯一性冲突 | 409 | "User with email already exists" | +| 数据验证失败 | 422 | "Invalid email format" | +| 数据库连接异常 | 500 | "Database connection error" | +| 未知异常 | 500 | "Internal server error" | + +## 事务管理设计 + +### 数据库事务策略 +```python +@staticmethod +def create_user(db: Session, user_data: UserCreate) -> User: + try: + # 业务逻辑操作 + db_user = User(**user_data.model_dump()) + db.add(db_user) + db.commit() + db.refresh(db_user) + return db_user + except IntegrityError as e: + db.rollback() + if "email" in str(e): + raise HTTPException(status_code=409, detail="Email already exists") + raise HTTPException(status_code=409, detail="Data conflict") + except Exception as e: + db.rollback() + raise HTTPException(status_code=500, detail="Internal server error") +``` + +### 会话生命周期 +- **FastAPI 依赖注入**: 自动管理会话创建和关闭 +- **异常安全**: 确保异常时会话正确回滚和关闭 +- **连接池**: 复用现有连接池配置 + +## 性能考虑 + +### 数据库查询优化 +- **索引使用**: 利用现有主键和唯一索引 +- **查询优化**: 避免 N+1 查询问题 +- **批量操作**: 必要时支持批量创建和更新 + +### 内存管理 +- **会话管理**: 及时关闭数据库会话 +- **对象生命周期**: 避免长期持有数据库对象引用 + +## 兼容性设计 + +### 向后兼容 +- **现有 API**: 保持现有 GET API 不变 +- **响应格式**: 保持现有响应结构 +- **错误处理**: 保持现有错误处理风格 + +### 扩展性设计 +- **服务接口**: 设计可扩展的服务接口 +- **模式版本**: 支持模式版本演进 +- **配置驱动**: 通过配置控制功能开关 + +--- + +**设计完成**: ✅ 架构设计完整 +**创建时间**: 2025-09-28 +**设计师**: Claude AI +**状态**: 准备进入原子化阶段 \ No newline at end of file diff --git a/docs/complete-crud-api/TASK_complete-crud-api.md b/docs/complete-crud-api/TASK_complete-crud-api.md new file mode 100644 index 0000000..5e305d0 --- /dev/null +++ b/docs/complete-crud-api/TASK_complete-crud-api.md @@ -0,0 +1,388 @@ +# TASK - 完善 CRUD API 功能任务分解 + +## 任务依赖图 + +```mermaid +graph TB + subgraph "阶段1: 基础重构" + T1[T1: UserService 数据库集成] + T2[T2: ProductService 数据库集成] + end + + subgraph "阶段2: API 扩展" + T3[T3: Users POST API] + T4[T4: Users PUT API] + T5[T5: Users DELETE API] + T6[T6: Products POST API] + T7[T7: Products PUT API] + T8[T8: Products DELETE API] + end + + subgraph "阶段3: 质量保证" + T9[T9: 异常处理优化] + T10[T10: API 测试验证] + T11[T11: 文档更新] + end + + T1 --> T3 + T1 --> T4 + T1 --> T5 + T2 --> T6 + T2 --> T7 + T2 --> T8 + + T3 --> T9 + T4 --> T9 + T5 --> T9 + T6 --> T9 + T7 --> T9 + T8 --> T9 + + T9 --> T10 + T10 --> T11 +``` + +## 原子任务详细定义 + +### T1: UserService 数据库集成 + +#### 输入契约 +- **前置依赖**: 数据库连接正常，SQLAlchemy 模型已定义 +- **输入数据**: 现有 UserService 类和方法签名 +- **环境依赖**: MySQL 数据库，SQLAlchemy 配置 + +#### 输出契约 +- **输出数据**: 重构后的 UserService 类 +- **交付物**: `app/services/user_service.py` 更新 +- **验收标准**: + - [ ] 移除所有假数据引用 + - [ ] 所有方法接受 `db: Session` 参数 + - [ ] 使用 SQLAlchemy ORM 进行数据库操作 + - [ ] 包含基础异常处理 + +#### 实现约束 +- **技术栈**: SQLAlchemy ORM, Session 管理 +- **接口规范**: 保持现有方法签名，增加 db 参数 +- **质量要求**: 异常安全，事务管理 + +#### 依赖关系 +- **并行任务**: T2 (ProductService 数据库集成) +- **后置任务**: T3, T4, T5 (Users API 实现) + +--- + +### T2: ProductService 数据库集成 + +#### 输入契约 +- **前置依赖**: 数据库连接正常，SQLAlchemy 模型已定义 +- **输入数据**: 现有 ProductService 类和方法签名 +- **环境依赖**: MySQL 数据库，SQLAlchemy 配置 + +#### 输出契约 +- **输出数据**: 重构后的 ProductService 类 +- **交付物**: `app/services/product_service.py` 更新 +- **验收标准**: + - [ ] 移除所有假数据引用 + - [ ] 所有方法接受 `db: Session` 参数 + - [ ] 使用 SQLAlchemy ORM 进行数据库操作 + - [ ] 包含基础异常处理 + +#### 实现约束 +- **技术栈**: SQLAlchemy ORM, Session 管理 +- **接口规范**: 保持现有方法签名，增加 db 参数 +- **质量要求**: 异常安全，事务管理 + +#### 依赖关系 +- **并行任务**: T1 (UserService 数据库集成) +- **后置任务**: T6, T7, T8 (Products API 实现) + +--- + +### T3: Users POST API 实现 + +#### 输入契约 +- **前置依赖**: T1 完成，UserService 数据库集成就绪 +- **输入数据**: UserCreate 模式，数据库 User 模型 +- **环境依赖**: FastAPI 路由系统，依赖注入配置 + +#### 输出契约 +- **输出数据**: POST /api/v1/users/ API 端点 +- **交付物**: `app/api/v1/endpoints/users.py` 更新 +- **验收标准**: + - [ ] 成功创建用户返回 201 状态码 + - [ ] 返回完整用户信息 (UserResponse) + - [ ] 数据持久化到数据库 + - [ ] 邮箱和用户名唯一性验证 + - [ ] 适当的错误处理 (409, 422) + +#### 实现约束 +- **技术栈**: FastAPI, 依赖注入, HTTPException +- **接口规范**: 使用 UserCreate 和 UserResponse 模式 +- **质量要求**: 输入验证，错误处理，状态码规范 + +#### 依赖关系 +- **前置任务**: T1 (UserService 数据库集成) +- **后置任务**: T9 (异常处理优化) + +--- + +### T4: Users PUT API 实现 + +#### 输入契约 +- **前置依赖**: T1 完成，UserService 数据库集成就绪 +- **输入数据**: UserUpdate 模式，用户 ID 参数 +- **环境依赖**: FastAPI 路由系统，依赖注入配置 + +#### 输出契约 +- **输出数据**: PUT /api/v1/users/{user_id} API 端点 +- **交付物**: `app/api/v1/endpoints/users.py` 更新 +- **验收标准**: + - [ ] 成功更新用户返回 200 状态码 + - [ ] 支持部分字段更新 + - [ ] 数据持久化到数据库 + - [ ] 用户不存在返回 404 + - [ ] 数据验证失败返回 422 + +#### 实现约束 +- **技术栈**: FastAPI, 依赖注入, HTTPException +- **接口规范**: 使用 UserUpdate 和 UserResponse 模式 +- **质量要求**: 部分更新支持，资源存在性检查 + +#### 依赖关系 +- **前置任务**: T1 (UserService 数据库集成) +- **后置任务**: T9 (异常处理优化) + +--- + +### T5: Users DELETE API 实现 + +#### 输入契约 +- **前置依赖**: T1 完成，UserService 数据库集成就绪 +- **输入数据**: 用户 ID 参数 +- **环境依赖**: FastAPI 路由系统，依赖注入配置 + +#### 输出契约 +- **输出数据**: DELETE /api/v1/users/{user_id} API 端点 +- **交付物**: `app/api/v1/endpoints/users.py` 更新 +- **验收标准**: + - [ ] 成功删除用户返回 204 状态码 + - [ ] 数据从数据库中删除 + - [ ] 用户不存在返回 404 + - [ ] 无响应体内容 + +#### 实现约束 +- **技术栈**: FastAPI, 依赖注入, HTTPException +- **接口规范**: 标准 RESTful DELETE 语义 +- **质量要求**: 资源存在性检查，正确状态码 + +#### 依赖关系 +- **前置任务**: T1 (UserService 数据库集成) +- **后置任务**: T9 (异常处理优化) + +--- + +### T6: Products POST API 实现 + +#### 输入契约 +- **前置依赖**: T2 完成，ProductService 数据库集成就绪 +- **输入数据**: ProductCreate 模式，数据库 Product 模型 +- **环境依赖**: FastAPI 路由系统，依赖注入配置 + +#### 输出契约 +- **输出数据**: POST /api/v1/products/ API 端点 +- **交付物**: `app/api/v1/endpoints/products.py` 更新 +- **验收标准**: + - [ ] 成功创建产品返回 201 状态码 + - [ ] 返回完整产品信息 (ProductResponse) + - [ ] 数据持久化到数据库 + - [ ] 价格和库存数据验证 + - [ ] 适当的错误处理 + +#### 实现约束 +- **技术栈**: FastAPI, 依赖注入, HTTPException +- **接口规范**: 使用 ProductCreate 和 ProductResponse 模式 +- **质量要求**: 输入验证，业务规则检查 + +#### 依赖关系 +- **前置任务**: T2 (ProductService 数据库集成) +- **后置任务**: T9 (异常处理优化) + +--- + +### T7: Products PUT API 实现 + +#### 输入契约 +- **前置依赖**: T2 完成，ProductService 数据库集成就绪 +- **输入数据**: ProductUpdate 模式，产品 ID 参数 +- **环境依赖**: FastAPI 路由系统，依赖注入配置 + +#### 输出契约 +- **输出数据**: PUT /api/v1/products/{product_id} API 端点 +- **交付物**: `app/api/v1/endpoints/products.py` 更新 +- **验收标准**: + - [ ] 成功更新产品返回 200 状态码 + - [ ] 支持部分字段更新 + - [ ] 数据持久化到数据库 + - [ ] 产品不存在返回 404 + - [ ] 数据验证失败返回 422 + +#### 实现约束 +- **技术栈**: FastAPI, 依赖注入, HTTPException +- **接口规范**: 使用 ProductUpdate 和 ProductResponse 模式 +- **质量要求**: 部分更新支持，资源存在性检查 + +#### 依赖关系 +- **前置任务**: T2 (ProductService 数据库集成) +- **后置任务**: T9 (异常处理优化) + +--- + +### T8: Products DELETE API 实现 + +#### 输入契约 +- **前置依赖**: T2 完成，ProductService 数据库集成就绪 +- **输入数据**: 产品 ID 参数 +- **环境依赖**: FastAPI 路由系统，依赖注入配置 + +#### 输出契约 +- **输出数据**: DELETE /api/v1/products/{product_id} API 端点 +- **交付物**: `app/api/v1/endpoints/products.py` 更新 +- **验收标准**: + - [ ] 成功删除产品返回 204 状态码 + - [ ] 数据从数据库中删除 + - [ ] 产品不存在返回 404 + - [ ] 无响应体内容 + +#### 实现约束 +- **技术栈**: FastAPI, 依赖注入, HTTPException +- **接口规范**: 标准 RESTful DELETE 语义 +- **质量要求**: 资源存在性检查，正确状态码 + +#### 依赖关系 +- **前置任务**: T2 (ProductService 数据库集成) +- **后置任务**: T9 (异常处理优化) + +--- + +### T9: 异常处理优化 + +#### 输入契约 +- **前置依赖**: T3-T8 完成，所有 API 端点实现就绪 +- **输入数据**: 所有 API 端点和服务方法 +- **环境依赖**: FastAPI 异常处理机制 + +#### 输出契约 +- **输出数据**: 统一的异常处理机制 +- **交付物**: + - 服务层异常处理优化 + - API 层统一错误响应 +- **验收标准**: + - [ ] 数据库约束异常正确映射到 HTTP 状态码 + - [ ] 详细错误信息返回 + - [ ] 异常日志记录 + - [ ] 事务回滚正确实现 + +#### 实现约束 +- **技术栈**: SQLAlchemy 异常，FastAPI HTTPException +- **接口规范**: 统一错误响应格式 +- **质量要求**: 全面异常覆盖，用户友好错误信息 + +#### 依赖关系 +- **前置任务**: T3, T4, T5, T6, T7, T8 (所有 API 实现) +- **后置任务**: T10 (API 测试验证) + +--- + +### T10: API 测试验证 + +#### 输入契约 +- **前置依赖**: T1-T9 完成，完整 CRUD API 实现 +- **输入数据**: 所有 API 端点 +- **环境依赖**: 测试数据库，测试客户端 + +#### 输出契约 +- **输出数据**: 完整的 API 测试套件 +- **交付物**: + - 功能测试用例 + - 集成测试验证 + - API 文档验证 +- **验收标准**: + - [ ] 所有 CRUD 操作测试通过 + - [ ] 错误场景测试通过 + - [ ] 数据持久化验证通过 + - [ ] API 文档生成正确 + +#### 实现约束 +- **技术栈**: FastAPI TestClient, pytest (可选) +- **接口规范**: RESTful API 测试标准 +- **质量要求**: 覆盖主要功能和错误场景 + +#### 依赖关系 +- **前置任务**: T9 (异常处理优化) +- **后置任务**: T11 (文档更新) + +--- + +### T11: 文档更新 + +#### 输入契约 +- **前置依赖**: T10 完成，所有测试验证通过 +- **输入数据**: 完整的 API 实现 +- **环境依赖**: 文档系统，API 自动生成文档 + +#### 输出契约 +- **输出数据**: 更新的项目文档 +- **交付物**: + - README.md 更新 + - API 使用示例 + - 开发指南更新 +- **验收标准**: + - [ ] API 文档反映所有新端点 + - [ ] 使用示例准确可用 + - [ ] 开发环境搭建指南更新 + - [ ] 错误处理说明文档 + +#### 实现约束 +- **技术栈**: Markdown, FastAPI 自动文档生成 +- **接口规范**: 清晰的文档结构 +- **质量要求**: 准确性，完整性，易读性 + +#### 依赖关系 +- **前置任务**: T10 (API 测试验证) +- **后置任务**: 无 (项目完成) + +## 复杂度评估 + +### 低复杂度任务 🟢 +- **T3, T6**: POST API 实现 (标准 CRUD 创建操作) +- **T11**: 文档更新 (文档编写) + +### 中等复杂度任务 🟡 +- **T1, T2**: 服务层数据库集成 (需要重构现有代码) +- **T4, T7**: PUT API 实现 (部分更新逻辑) +- **T5, T8**: DELETE API 实现 (资源存在性检查) +- **T10**: API 测试验证 (需要综合测试) + +### 较高复杂度任务 🟠 +- **T9**: 异常处理优化 (需要全面的异常映射和处理) + +## 风险评估 + +### 技术风险 🔴 +- **数据库事务管理**: 确保事务正确提交和回滚 +- **异常处理完整性**: 覆盖所有可能的数据库和业务异常 + +### 集成风险 🟡 +- **现有 API 兼容性**: 确保重构不影响现有 GET API +- **数据库约束冲突**: 处理唯一性约束等数据库级别限制 + +### 时间风险 🟢 +- **任务依赖**: 明确的依赖关系，可并行执行基础任务 +- **测试验证**: 充分的测试时间分配 + +--- + +**任务分解完成**: ✅ 11个原子任务已定义 +**创建时间**: 2025-09-28 +**预计总工期**: 2-3小时 +**状态**: 准备进入审批阶段 \ No newline at end of file