# Phase 1-5 测试指南

## 📋 测试概览

本目录包含 4 个独立的测试脚本，用于验证 Postgres-Only 架构的核心组件：

| 测试脚本 | 测试内容 | 预计耗时 |
|---------|---------|----------|
| `test-postgres-cache.ts` | PostgresCacheAdapter（缓存读写、过期、批量操作） | ~30秒 |
| `test-pgboss-queue.ts` | PgBossQueue（任务入队、处理、重试） | ~20秒 |
| `test-checkpoint.ts` | CheckpointService（断点保存、恢复、中断续传） | ~15秒 |
| `test-task-split.ts` | 任务拆分工具（splitIntoChunks、recommendChunkSize） | <1秒 |

---

## 🚀 快速开始

### 前置条件

1. ✅ **数据库迁移已完成**
   ```bash
   # 确认app_cache表和新字段已创建
   psql -U postgres -d ai_clinical -c "\dt platform_schema.app_cache"
   ```

2. ✅ **pg-boss依赖已安装**
   ```bash
   npm list pg-boss
   ```

3. ✅ **环境变量已配置**
   - `DATABASE_URL` 指向正确的数据库

---

## 📝 测试执行

### 1️⃣ 测试 PostgresCacheAdapter（缓存）

```bash
cd AIclinicalresearch/backend
npx ts-node src/tests/test-postgres-cache.ts
```

**测试内容：**
- ✅ 基本读写（set/get）
- ✅ 过期机制（2秒TTL验证）
- ✅ 批量操作（mset/mget）
- ✅ 删除操作（delete）
- ✅ has() 方法
- ✅ 过期数据自动清理（懒删除）

**预期输出：**
```
🚀 开始测试 PostgresCacheAdapter...

📝 测试 1: 基本读写
   ✅ 写入并读取: { name: 'Alice', age: 25 }

⏰ 测试 2: 过期机制
   写入缓存，2秒后过期...
   ✅ 3秒后读取: null

📦 测试 3: 批量操作
   ✅ 批量写入并读取: [{ id: 1 }, { id: 2 }, { id: 3 }]

🗑️ 测试 4: 删除操作
   ✅ 删除后读取: null

🔍 测试 5: has() 方法
   ✅ 存在的key: true
   ✅ 不存在的key: false

🧹 测试 6: 过期缓存自动删除
   ✅ 过期数据已自动删除: 是

🎉 所有测试通过！
```

---

### 2️⃣ 测试 PgBossQueue（任务队列）

```bash
npx ts-node src/tests/test-pgboss-queue.ts
```

**测试内容：**
- ✅ 连接初始化（pg-boss.start()）
- ✅ 推送任务（push）
- ✅ 处理任务（process）
- ✅ 批量任务处理（3个并发）
- ✅ 任务失败重试（模拟失败+重试）

**预期输出：**
```
🚀 开始测试 PgBossQueue...

📝 测试 1: 连接初始化
   ✅ PgBoss连接成功

📝 测试 2: 推送任务
   ✅ 任务已推送，ID: abc-123-def

📝 测试 3: 处理任务
   📥 收到任务: abc-123-def
   📦 任务数据: { message: 'Hello PgBoss', timestamp: 1234567890 }
   ✅ 任务处理完成
   ✅ 任务处理验证通过

📝 测试 4: 批量任务处理
   ✅ 已推送 3 个批量任务
   📥 处理批次 1
   📥 处理批次 2
   📥 处理批次 3
   ✅ 已处理 3/3 个批量任务

📝 测试 5: 任务失败重试
   📥 第 1 次尝试
   ❌ 模拟失败，将重试...
   📥 第 2 次尝试
   ✅ 第2次成功
   ✅ 重试机制验证通过

🎉 所有测试通过！
```

**⚠️ 注意事项：**
- pg-boss 会在 `platform_schema` 下自动创建 `job` 和 `version` 表
- 测试会等待任务异步处理，总耗时约 20 秒
- 如果测试超时，检查数据库连接和 pg-boss 日志

---

### 3️⃣ 测试 CheckpointService（断点续传）

```bash
npx ts-node src/tests/test-checkpoint.ts
```

**测试内容：**
- ✅ 保存断点（saveCheckpoint）
- ✅ 加载断点（loadCheckpoint）
- ✅ 模拟中断恢复（SAE实例重启场景）
- ✅ 更新任务进度（processedBatches/currentIndex）
- ✅ 清除断点（clearCheckpoint）
- ✅ 完整流程模拟（10批次）

**预期输出：**
```
🚀 开始测试 CheckpointService...

📝 准备测试数据...
   ✅ 创建测试任务 ID: task-123-abc

📝 测试 1: 保存断点
   ✅ 断点已保存

📝 测试 2: 加载断点
   ✅ 断点数据: {
     "currentBatchIndex": 3,
     "currentIndex": 350,
     "processedBatches": 3
   }
   ✅ 断点加载验证通过

📝 测试 3: 模拟中断恢复
   场景：任务在第5批次突然中断...
   ⏸️ 保存中断点...
   🔄 模拟恢复...
   ✅ 恢复到批次 5，索引 550
   ✅ 已处理 5 批次

📝 测试 4: 更新任务进度
   ✅ 任务进度: {
     processedBatches: 5,
     currentBatchIndex: 5,
     currentIndex: 550,
     progress: '550/1000'
   }

📝 测试 5: 清除断点
   ✅ 清除后的断点: null
   ✅ 断点清除验证通过

📝 测试 6: 完整流程模拟（10批次）
   📦 处理批次 1/10 (0-100)
   📦 处理批次 2/10 (100-200)
   ...
   📦 处理批次 10/10 (900-1000)
   ✅ 最终进度: {
     processedBatches: 10,
     totalBatches: 10,
     processedItems: 1000,
     totalItems: 1000
   }

🎉 所有测试通过！
```

**⚠️ 注意事项：**
- 测试会创建临时的 `AslScreeningProject` 和 `AslScreeningTask`
- 测试结束后会自动清理测试数据
- 如果测试失败，手动清理：`DELETE FROM asl_schema.screening_tasks WHERE project_id = 'test-...'`

---

### 4️⃣ 测试任务拆分工具（纯逻辑，无数据库）

```bash
npx ts-node src/tests/test-task-split.ts
```

**测试内容：**
- ✅ 基本拆分（100条数据，每批10条）
- ✅ 不整除拆分（105条数据，最后一批5条）
- ✅ 大数据拆分（1000条数据验证完整性）
- ✅ 推荐批次大小（recommendChunkSize）
- ✅ 边界情况（空数组、小数组、批次大小为1）
- ✅ 实际场景模拟（1000篇文献筛选）

**预期输出：**
```
🚀 开始测试任务拆分工具...

📝 测试 1: 基本拆分
   总数据: 100 条
   每批次: 10 条
   拆分结果: 10 批次
   ✅ 基本拆分通过

📝 测试 2: 不整除拆分
   总数据: 105 条
   每批次: 10 条
   拆分结果: 11 批次
   最后1批: 5 条
   ✅ 不整除拆分通过

📝 测试 3: 大数据拆分（1000条）
   ✅ 大数据拆分通过

📝 测试 4: 推荐批次大小
   文献筛选-100篇:
      推荐批次: 50 条/批
      总批次数: 2 批
   文献筛选-1000篇:
      推荐批次: 50 条/批
      总批次数: 20 批
   ...

📝 测试 5: 边界情况
   空数组拆分: ✅
   小数组拆分: ✅
   批次大小为1: ✅
   ✅ 边界情况通过

📝 测试 6: 实际应用场景模拟
   场景：1000篇文献筛选
   总文献: 1000 篇
   推荐批次: 50 篇/批
   总批次数: 20 批
   预计总时间: 140.0 分钟 (假设每批7分钟)
   ✅ 实际场景模拟通过

🎉 所有测试通过！
```

---

## 🔍 故障排查

### 问题 1：`relation "platform_schema.app_cache" does not exist`

**原因：** 数据库迁移未执行

**解决：**
```bash
cd AIclinicalresearch/backend
npx ts-node prisma/manual-migrations/run-migration.ts
```

---

### 问题 2：`Module '"pg-boss"' has no default export`

**原因：** pg-boss 未安装或版本不兼容

**解决：**
```bash
npm install pg-boss@9.0.3 --save
```

---

### 问题 3：`Property 'appCache' does not exist on type 'PrismaClient'`

**原因：** Prisma Client 未重新生成

**解决：**
```bash
npx prisma generate
```

---

### 问题 4：测试卡住不动（PgBossQueue测试）

**原因：** pg-boss 连接失败或任务处理超时

**排查：**
1. 检查数据库连接：`psql -U postgres -d ai_clinical`
2. 检查 pg-boss 表：`\dt platform_schema.job`
3. 查看 pg-boss 日志：检查终端输出

---

### 问题 5：`AslScreeningProject` 创建失败

**原因：** 外键约束（userId 不存在）

**解决：** 测试脚本会使用假的 UUID，如果外键约束严格，需要：
```sql
-- 临时禁用外键约束
SET session_replication_role = 'replica';

-- 运行测试...

-- 恢复外键约束
SET session_replication_role = 'origin';
```

---

## 📊 测试结果总结

### ✅ 全部通过

如果所有 4 个测试脚本都输出 `🎉 所有测试通过！`，说明：

1. ✅ **PostgresCacheAdapter** 可以正常缓存数据
2. ✅ **PgBossQueue** 可以正常处理任务
3. ✅ **CheckpointService** 可以正常保存/恢复断点
4. ✅ **任务拆分工具** 逻辑正确

**下一步：** 可以开始 **Phase 6**（改造 ASL 筛选服务）

---

### ❌ 部分失败

如果某个测试失败，**不要继续 Phase 6**，先排查错误：

1. 查看错误堆栈
2. 参考上面的"故障排查"部分
3. 如有疑问，查看测试脚本源码（都有详细注释）

---

## 📚 扩展阅读

- **pg-boss 文档**: https://github.com/timgit/pg-boss/blob/master/docs/readme.md
- **Prisma 客户端**: https://www.prisma.io/docs/concepts/components/prisma-client
- **Postgres JSONB**: https://www.postgresql.org/docs/current/datatype-json.html

---

## 🎯 测试覆盖率

| 模块 | 测试覆盖 | 状态 |
|------|---------|------|
| PostgresCacheAdapter | 100% (6/6 方法) | ✅ |
| PgBossQueue | 80% (5/6 方法，未测试 failJob) | ✅ |
| CheckpointService | 100% (3/3 方法) | ✅ |
| TaskSplit Utils | 100% (2/2 函数) | ✅ |

**总体覆盖率：95%** 🎉

---

**更新日期：** 2025-12-13  
**版本：** V1.0  
**作者：** AI Clinical Research Team