388 lines
11 KiB
Markdown
388 lines
11 KiB
Markdown
# 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小时
|
||
**状态**: 准备进入审批阶段 |