# 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目标清晰可实现
- [✅] 故事范围适当
- [✅] 成功标准可衡量
- [✅] 依赖项已识别