fastapi-demo/docs/complete-crud-api/TASK_complete-crud-api.md

TASK - 完善 CRUD API 功能任务分解

任务依赖图

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小时 状态: 准备进入审批阶段