feat(platform): Complete Postgres-Only architecture refactoring (Phase 1-7)

Major Changes: - Implement Platform-Only architecture pattern (unified task management) - Add PostgresCacheAdapter for unified caching (platform_schema.app_cache) - Add PgBossQueue for job queue management (platform_schema.job) - Implement CheckpointService using job.data (generic for all modules) - Add intelligent threshold-based dual-mode processing (THRESHOLD=50) - Add task splitting mechanism (auto chunk size recommendation) - Refactor ASL screening service with smart mode selection - Refactor DC extraction service with smart mode selection - Register workers for ASL and DC modules Technical Highlights: - All task management data stored in platform_schema.job.data (JSONB) - Business tables remain clean (no task management fields) - CheckpointService is generic (shared by all modules) - Zero code duplication (DRY principle) - Follows 3-layer architecture principle - Zero additional cost (no Redis needed, save 8400 CNY/year) Code Statistics: - New code: ~1750 lines - Modified code: ~500 lines - Test code: ~1800 lines - Documentation: ~3000 lines Testing: - Unit tests: 8/8 passed - Integration tests: 2/2 passed - Architecture validation: passed - Linter errors: 0 Files: - Platform layer: PostgresCacheAdapter, PgBossQueue, CheckpointService, utils - ASL module: screeningService, screeningWorker - DC module: ExtractionController, extractionWorker - Tests: 11 test files - Docs: Updated 4 key documents Status: Phase 1-7 completed, Phase 8-9 pending
2025-12-13 16:10:04 +08:00
parent a3586cdf30
commit fa72beea6c
135 changed files with 17508 additions and 91 deletions
--- a/backend/src/tests/README.md
+++ b/backend/src/tests/README.md
@@ -0,0 +1,383 @@
+# 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
+