mini-starter/docs/prd/epic-004-api-actual-request-testing.md

API实际请求测试增强 - Brownfield Epic

Epic Goal

为现有API系统添加实际HTTP请求测试，验证系统在真实数据库环境下的行为，确保集成测试不仅使用mock数据，还能测试实际的数据流和业务逻辑。

Epic Description

现有系统上下文

• 当前相关功能：已有完整的API集成测试框架，但使用自定义测试工具而非官方hono/testing
• 技术栈：Node.js + TypeScript + Hono + TypeORM + PostgreSQL + Vitest
• 集成点：数据库连接、认证中间件、CRUD服务、API路由
• 现有测试：✅ 已迁移到hono/testing的testClient()，用户API实际请求测试已实现

增强详情

• 新增内容：迁移到hono/testing官方测试工具，创建实际HTTP请求测试套件，连接真实测试数据库进行端到端测试
• 集成方式：使用hono/testing的testClient()替代自定义实现，提供更好的类型安全和开发体验
• 当前进展：✅ 用户API实际请求测试已完全实现（13个测试用例）
• 成功标准：
  • ✅ 用户API核心端点都有实际请求测试
  • ✅ 测试覆盖CRUD操作的实际数据库交互
  • ✅ 测试通过率100%
  • ✅ 与现有mock测试并行运行

Stories

1. Story 004.001: 实际请求测试基础设施与用户API测试 ✅ 已完成

   • 配置测试数据库环境
   • 创建测试数据准备和清理工具
   • 实现测试专用的数据库连接
   • 迁移到hono/testing的testClient()
   • 实现用户CRUD操作的实际HTTP测试
   • 集成到CI/CD流水线

2. Story 004.002: 认证API实际请求测试 ✅ 已完成

   • 登录端点测试（正确凭据、错误凭据、禁用账户）
   • 令牌验证端点测试（有效、过期、无效令牌）
   • 权限检查端点测试（基于角色的访问控制）
   • 错误处理测试覆盖
   • 性能基准测试

3. Story 3: 扩展其他模块的实际请求测试

   • 为数据管理、配置管理等模块添加实际HTTP测试

兼容性要求

• [✅] 现有API保持不变
• [✅] 数据库schema变更向后兼容
• [✅] 现有测试继续正常工作（迁移到hono/testing后）
• [✅] 性能影响最小（测试专用数据库）
• [✅] 测试工具迁移保持功能对等（自定义ApiClient → hono/testing）

风险缓解

• 主要风险：测试数据库污染生产数据
• 缓解措施：使用独立的测试数据库，自动数据清理
• 次要风险：测试工具迁移导致现有测试中断
• 缓解措施：逐步迁移，保持新旧测试工具并行运行
• 回滚计划：删除测试数据库，恢复原有测试配置

完成定义

• [✅] Story 004.001完成且验收标准满足
• [✅] 用户API功能通过实际请求测试验证
• [✅] 集成点正常工作
• [✅] 文档适当更新（已完成）
• [✅] 现有功能无回归

验证检查清单

范围验证

• [✅] Epic进展良好，第一个故事超额完成
• [✅] 无需架构文档（使用现有模式）
• [✅] 增强遵循现有模式
• [✅] 集成复杂度可控

风险评估

• [✅] 对现有系统风险低
• [✅] 回滚计划可行
• [✅] 测试方法覆盖现有功能
• [✅] 团队具备集成点知识

完整性检查

• [✅] Epic目标清晰可实现
• [✅] 故事范围适当
• [✅] 成功标准可衡量
• [✅] 依赖项已识别