# Story 005.003: 迁移工具类单元测试

## Status
Ready for Review

## Story
**As a** 开发人员，
**I want** 将工具类单元测试从 web/tests 迁移到 packages/server/tests 目录，
**so that** packages/server 成为一个真正独立的、可测试的库包，工具类测试与源代码在同一包内管理

## Acceptance Criteria
1. 迁移 backup 工具测试
2. 迁移 restore 工具测试
3. 验证迁移后测试正常运行

## Tasks / Subtasks
- [x] 创建 packages/server/tests/unit/utils 目录结构 (AC: 1,2)
  - [x] 创建目录 packages/server/tests/unit/utils/
- [x] 迁移 backup 工具测试 (AC: 1)
  - [x] 复制 web/tests/unit/server/utils/backup.test.ts 内容
  - [x] 更新导入路径为 @/utils/backup
  - [x] 验证测试通过
- [x] 迁移 restore 工具测试 (AC: 2)
  - [x] 复制 web/tests/unit/server/utils/restore.test.ts 内容
  - [x] 更新导入路径为 @/utils/restore
  - [x] 验证测试通过
- [x] 验证迁移后测试正常运行 (AC: 5)
  - [x] 运行所有工具类测试
  - [x] 检查测试覆盖率
  - [x] 确保没有测试失败

## Dev Notes

### 技术栈信息 [Source: architecture/tech-stack.md]
- **测试框架**: Vitest 3.2.4
- **运行时**: Node.js 20.18.3
- **模块系统**: ES 模块
- **数据库**: PostgreSQL 17 + TypeORM

### 项目结构信息 [Source: architecture/source-tree.md]
- **工具类位置**: packages/server/src/utils/
  - backup.ts - 数据库备份工具
  - restore.ts - 数据库恢复工具
  - jwt.util.ts - JWT 工具
  - logger.ts - 日志工具
  - errorHandler.ts - 错误处理工具
- **测试目录结构**: packages/server/tests/
  - unit/ - 单元测试
  - integration/ - 集成测试
  - utils/ - 测试工具
- **测试文件命名**: [module].test.ts

### 测试策略信息 [Source: architecture/testing-strategy.md]
- **单元测试位置**: tests/unit/**/*.test.{ts,js}
- **覆盖率目标**: ≥ 80%
- **测试标准**: 使用 Vitest 框架，遵循 Arrange-Act-Assert 模式
- **测试命名**: 使用「应该...」格式描述测试行为

### 工具类功能分析
- **backup.ts**: 数据库备份工具，包含单例模式、定时备份、文件清理等功能
- **restore.ts**: 数据库恢复工具，包含备份文件查找、恢复操作等功能
- **注意**: 当前 web/tests 中只有 backup 和 restore 工具类的单元测试，其他工具类暂时没有专门的单元测试文件

### 迁移注意事项
- 保持测试功能对等，迁移前后测试覆盖相同功能
- 更新导入路径为 @d8d/server 包内路径
- 确保 mock 和依赖注入正确配置
- 验证测试在 packages/server 环境中正常运行

### Testing
- **测试文件位置**: packages/server/tests/unit/utils/
- **测试框架**: Vitest
- **测试模式**: 单元测试，完全 mock 外部依赖
- **覆盖率要求**: 工具类测试覆盖率 ≥ 80%
- **测试标准**:
  - 使用 vi.mock() 进行依赖 mock
  - 遵循 Arrange-Act-Assert 模式
  - 包含边界条件和错误场景测试
  - 测试文件命名: [tool-name].test.ts

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-11-09 | 1.1 | 简化范围，只迁移现有测试文件 | Bob (Scrum Master) |
| 2025-11-09 | 1.0 | 初始故事创建 | Bob (Scrum Master) |

## Dev Agent Record

### Agent Model Used
- Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)

### Debug Log References
- 创建了 packages/server/tests/unit/utils/ 目录结构
- 迁移 backup 工具测试：12个测试全部通过
- 迁移 restore 工具测试：12个测试全部通过
- 验证所有工具类测试正常运行：24个测试全部通过

### Completion Notes List
1. ✅ 成功创建 packages/server/tests/unit/utils 目录结构
2. ✅ 成功迁移 backup 工具测试，更新导入路径为 @/utils/backup
3. ✅ 成功迁移 restore 工具测试，更新导入路径为 @/utils/restore
4. ✅ 验证迁移后测试正常运行，所有24个测试通过
5. ✅ 测试覆盖率保持稳定，工具类测试功能完整

### File List
- **新增文件**: packages/server/tests/unit/utils/backup.test.ts
- **新增文件**: packages/server/tests/unit/utils/restore.test.ts
- **修改文件**: 无（仅新增迁移后的测试文件）
- **删除文件**: 无（保留原始测试文件在 web/tests 中）

## QA Results