📝 docs(tasks): add test utils migration documentation

- create detailed migration plan for test utilities and integration tests
- outline steps for creating shared test-utils package
- document migration process for server API integration tests
- include directory structures, configuration examples and timeline estimates
- add risk assessment and验收标准 for the migration task

docs/tasks/test-utils-migration.md

@@ -0,0 +1,231 @@
+# 测试工具包迁移任务文档
+
+## 任务概述
+将 `web/tests/integration/server` 目录的API集成测试迁移到 `packages/server`，并通过创建共享测试工具包实现代码复用。
+
+## 目标
+- 创建共享测试工具包 `packages/test-utils`
+- 将服务器API集成测试迁移到 `packages/server/tests/integration/`
+- 保持现有测试功能完整性
+- 优化monorepo架构的测试组织
+
+## 阶段1：创建共享测试工具包
+
+### 1.1 创建 packages/test-utils 目录结构
+```
+packages/test-utils/
+├── package.json
+├── src/
+│   ├── index.ts
+│   ├── server/
+│   │   ├── integration-test-db.ts
+│   │   ├── integration-test-utils.ts
+│   │   ├── test-auth.ts
+│   │   └── test-db.ts
+│   └── client/
+│       ├── test-query.tsx
+│       ├── test-render.tsx
+│       └── test-router.tsx
+└── tsconfig.json
+```
+
+### 1.2 配置 package.json
+```json
+{
+  "name": "@d8d/test-utils",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@d8d/server": "workspace:*",
+    "@hono/node-server": "^1.13.0",
+    "@testing-library/react": "^14.1.2",
+    "@testing-library/jest-dom": "^6.1.4",
+    "@testing-library/user-event": "^14.5.1",
+    "@tanstack/react-query": "^5.8.4",
+    "react-router-dom": "^6.20.1",
+    "bcrypt": "^5.1.1",
+    "pg": "^8.11.3"
+  },
+  "devDependencies": {
+    "@types/bcrypt": "^5.0.2",
+    "@types/pg": "^8.10.9",
+    "typescript": "^5.3.3"
+  }
+}
+```
+
+### 1.3 迁移测试工具类
+从 `web/tests/utils/` 迁移以下文件：
+- `integration-test-db.ts` → `packages/test-utils/src/server/integration-test-db.ts`
+- `integration-test-utils.ts` → `packages/test-utils/src/server/integration-test-utils.ts`
+- `test-auth.ts` → `packages/test-utils/src/server/test-auth.ts`
+- `test-db.ts` → `packages/test-utils/src/server/test-db.ts`
+- `test-query.tsx` → `packages/test-utils/src/client/test-query.tsx`
+- `test-render.tsx` → `packages/test-utils/src/client/test-render.tsx`
+- `test-router.tsx` → `packages/test-utils/src/client/test-router.tsx`
+
+### 1.4 更新导入路径
+调整所有工具类中的导入语句，使用workspace引用：
+```typescript
+// 从
+import { IntegrationTestDatabase } from '../../utils/integration-test-db';
+// 改为
+import { IntegrationTestDatabase } from '@d8d/test-utils/server/integration-test-db';
+```
+
+## 阶段2：配置 packages/server 测试环境
+
+### 2.1 创建 packages/server/vitest.config.ts
+```typescript
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    setupFiles: ['./tests/setup.ts'],
+    globals: true,
+  },
+});
+```
+
+### 2.2 创建 packages/server/tests/setup.ts
+配置测试环境，包括数据库连接和全局设置。
+
+### 2.3 更新 packages/server/package.json
+添加测试脚本和依赖：
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "vitest run tests/integration/"
+  },
+  "devDependencies": {
+    "@d8d/test-utils": "workspace:*",
+    "vitest": "^1.2.2"
+  }
+}
+```
+
+## 阶段3：迁移集成测试文件
+
+### 3.1 创建目标目录结构
+```
+packages/server/tests/
+├── integration/
+│   ├── auth.integration.test.ts
+│   ├── backup.integration.test.ts
+│   ├── files/
+│   │   ├── files.integration.test.ts
+│   │   └── minio.integration.test.ts
+│   └── users.integration.test.ts
+└── setup.ts
+```
+
+### 3.2 迁移测试文件
+从 `web/tests/integration/server/` 迁移以下文件：
+- `auth.integration.test.ts`
+- `backup.integration.test.ts`
+- `files/files.integration.test.ts`
+- `files/minio.integration.test.ts`
+- `users.integration.test.ts`
+
+### 3.3 更新测试文件导入
+调整所有测试文件中的导入语句：
+```typescript
+// 从
+import { app } from '@d8d/server';
+import { IntegrationTestDatabase } from '../../../utils/integration-test-db';
+// 改为
+import { app } from '../../src/app';
+import { IntegrationTestDatabase } from '@d8d/test-utils/server/integration-test-db';
+```
+
+## 阶段4：更新根项目配置
+
+### 4.1 更新根 package.json
+添加workspace引用：
+```json
+{
+  "workspaces": [
+    "packages/*",
+    "packages/test-utils"
+  ]
+}
+```
+
+### 4.2 更新根 vitest.config.ts
+移除已迁移的服务器集成测试配置。
+
+### 4.3 更新 web/package.json
+移除不再需要的测试工具依赖，添加对 `@d8d/test-utils` 的引用。
+
+## 阶段5：验证和清理
+
+### 5.1 运行测试验证
+```bash
+# 在 packages/server 中运行集成测试
+cd packages/server && pnpm test:integration
+
+# 在 web 中运行所有测试
+cd web && pnpm test
+```
+
+### 5.2 清理原目录
+删除 `web/tests/integration/server/` 目录。
+
+### 5.3 更新 CI/CD 配置
+确保CI流程能够运行新的测试结构。
+
+## 风险与缓解措施
+
+### 风险1：数据库连接问题
+- **缓解**：在迁移前备份数据库配置，确保新的测试环境使用相同的连接参数
+
+### 风险2：导入路径错误
+- **缓解**：使用TypeScript编译器检查所有导入路径，确保无错误
+
+### 风险3：测试工具功能差异
+- **缓解**：在迁移后立即运行所有测试，验证功能完整性
+
+### 风险4：CI/CD流程中断
+- **缓解**：在迁移前测试CI流程，确保新的测试命令正常工作
+
+## 验收标准
+
+- [ ] 所有服务器集成测试在 `packages/server` 中正常运行
+- [ ] 所有web项目测试继续正常运行
+- [ ] 共享测试工具包被正确引用
+- [ ] CI/CD流程无错误
+- [ ] 无重复代码或工具类
+- [ ] 代码导入路径正确
+
+## 时间估算
+
+- 阶段1：2-3小时
+- 阶段2：1-2小时
+- 阶段3：2-3小时
+- 阶段4：1小时
+- 阶段5：1小时
+
+**总计：7-10小时**
+
+## 后续优化建议
+
+1. 考虑将单元测试也迁移到对应的包中
+2. 创建统一的测试运行脚本
+3. 添加测试覆盖率报告
+4. 优化测试数据管理
+
+---
+
+**任务创建者**: Winston 🏗️
+**创建时间**: 2025-10-23
+**状态**: 待执行