AIclinicalresearch/backend/src/tests/README.md

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. ✅ 数据库迁移已完成

   # 确认app_cache表和新字段已创建
   psql -U postgres -d ai_clinical -c "\dt platform_schema.app_cache"
   

2. ✅ pg-boss依赖已安装

   npm list pg-boss
   

3. ✅ 环境变量已配置

   • DATABASE_URL 指向正确的数据库

---

📝 测试执行

1️⃣ 测试 PostgresCacheAdapter（缓存）

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（任务队列）

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（断点续传）

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️⃣ 测试任务拆分工具（纯逻辑，无数据库）

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

原因： 数据库迁移未执行

解决：

cd AIclinicalresearch/backend
npx ts-node prisma/manual-migrations/run-migration.ts

---

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

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

解决：

npm install pg-boss@9.0.3 --save

---

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

原因： Prisma Client 未重新生成

解决：

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，如果外键约束严格，需要：

-- 临时禁用外键约束
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