# 测试工具包迁移与架构优化 - Brownfield Epic

## Epic Goal
将现有测试工具和集成测试从web项目迁移到独立的共享测试工具包，优化monorepo架构的测试组织，提高代码复用性和维护性。

## Epic Description

### 现有系统上下文
- **当前状态**：测试工具和集成测试分散在web项目中，存在代码重复和维护困难
- **技术栈**：Node.js + TypeScript + Hono + PostgreSQL + Vitest + React
- **集成点**：数据库测试工具、认证测试工具、API测试客户端、React测试工具
- **现有测试**：✅ 服务器集成测试、前端组件测试、API测试

### 迁移详情
- **目标架构**：创建独立的 `@d8d/test-utils` 包，统一管理所有测试工具
- **迁移范围**：
  - 服务器集成测试工具（数据库、认证、API客户端）
  - 前端测试工具（React组件、路由、状态管理）
  - 集成测试文件从web迁移到packages/server
- **架构优化**：
  - 清晰的包边界和依赖关系
  - 统一的测试工具接口
  - 更好的代码复用和类型安全

## Stories

1. **Story 005.001**: 创建共享测试工具包基础设施
   - 创建 `packages/test-utils` 目录结构
   - 配置package.json和TypeScript配置
   - 建立基础导出接口
   - 配置workspace依赖

2. **Story 005.002**: 迁移服务器端测试工具
   - 迁移数据库测试工具（integration-test-db.ts, test-db.ts）
   - 迁移认证测试工具（test-auth.ts）
   - 迁移集成测试工具（integration-test-utils.ts）
   - 更新所有导入路径

3. **Story 005.003**: 迁移客户端测试工具
   - 迁移React查询测试工具（test-query.tsx）
   - 迁移React渲染测试工具（test-render.tsx）
   - 迁移路由测试工具（test-router.tsx）
   - 更新前端测试导入

4. **Story 005.004**: 配置packages/server测试环境
   - 创建vitest配置
   - 设置测试环境setup
   - 更新package.json测试脚本
   - 验证测试环境

5. **Story 005.005**: 迁移服务器集成测试
   - 创建目标目录结构
   - 迁移认证集成测试
   - 迁移备份集成测试
   - 迁移文件管理集成测试
   - 迁移用户管理集成测试
   - 更新所有测试导入

6. **Story 005.006**: 更新根项目配置
   - 更新workspace配置
   - 调整根vitest配置
   - 更新web项目依赖
   - 验证CI/CD流程

7. **Story 005.007**: 验证和清理
   - 运行所有迁移后的测试
   - 清理原web项目中的测试文件
   - 更新文档和README
   - 性能基准测试

## 兼容性要求

- [ ] 现有测试功能保持不变
- [ ] 测试执行结果一致
- [ ] 开发体验无退化
- [ ] CI/CD流程继续正常工作
- [ ] 类型安全得到保持

## 风险缓解

- **主要风险**：导入路径错误导致测试失败
- **缓解措施**：使用TypeScript严格检查，逐步迁移验证
- **次要风险**：工具包接口不兼容
- **缓解措施**：保持向后兼容的接口设计
- **回滚计划**：恢复原测试文件，移除测试工具包

## 完成定义

- [ ] 所有测试工具成功迁移到共享包
- [ ] 服务器集成测试在packages/server中正常运行
- [ ] 前端测试继续正常工作
- [ ] 无重复代码或工具类
- [ ] 导入路径全部正确
- [ ] CI/CD流程无错误

## 验证检查清单

### 范围验证
- [ ] Epic目标清晰可实现
- [ ] 故事范围适当
- [ ] 迁移计划完整
- [ ] 集成复杂度可控

### 风险评估
- [ ] 对现有系统风险可控
- [ ] 回滚计划可行
- [ ] 测试覆盖现有功能
- [ ] 团队具备迁移知识

### 完整性检查
- [ ] Epic目标清晰可实现
- [ ] 故事范围适当
- [ ] 成功标准可衡量
- [ ] 依赖项已识别

## 时间估算

- Story 005.001: 2-3小时
- Story 005.002: 2-3小时
- Story 005.003: 1-2小时
- Story 005.004: 1-2小时
- Story 005.005: 3-4小时
- Story 005.006: 1-2小时
- Story 005.007: 1-2小时

**总计：11-18小时**

## 后续优化建议

1. 考虑将单元测试也迁移到对应的包中
2. 创建统一的测试运行脚本
3. 添加测试覆盖率报告
4. 优化测试数据管理
5. 建立测试工具包版本管理