Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
HaHafeng
2025-12-13 16:10:04 +08:00
parent a3586cdf30
commit fa72beea6c
135 changed files with 17508 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

194
docs/00-系统总体设计/00-系统当前状态与开发指南.md
View File

@@ -1,10 +1,10 @@
# AIclinicalresearch 系统当前状态与开发指南
> **文档版本：** v1.7
> **文档版本：** v1.8
> **创建日期：** 2025-11-28
> **维护者：** 开发团队
> **最后更新：** 2025-12-10
> **重大进展：** ✨ DC模块Tool C功能按钮Phase 1-2完成 + NA处理优化 + Pivot列顺序优化 + UX重大改进（筛选/行号/滚动条/全量数据）
> **最后更新：** 2025-12-13
> **重大进展：** 🏆 **Postgres-Only 架构改造完成（Phase 1-7）** - Platform层统一任务管理、智能双模式处理、断点续传机制
> **文档目的：** 快速了解系统当前状态，为新AI助手提供上下文
---
@@ -66,7 +66,13 @@
↓ 依赖
┌─────────────────────────────────────────────────────────┐
│ 平台基础层 (Platform Layer) │
│ 存储 | 日志 | 缓存 | 任务 | 健康检查 | 监控 | 数据库连接池 │
│ 🏆 **Postgres-Only架构**（新） │
│ ├── 统一缓存：platform_schema.app_cache ✅ │
│ ├── 统一队列：platform_schema.job (pg-boss) ✅ │
│ ├── 任务管理：job.data 统一存储 ✅ │
│ └── 断点续传：CheckpointService 通用化 ✅ │
│ │
│ 存储 | 日志 | 缓存 | 任务 | 健康检查 | 监控 | 连接池 │
│ ✅ ✅ ✅ ✅ ✅ ✅ ✅ │
└─────────────────────────────────────────────────────────┘
```
@@ -100,15 +106,30 @@
### ✅ 已完成模块
#### 1. 平台基础层（2025-11-17完成）
#### 1. 平台基础层 🏆 **Postgres-Only 架构完成！**（2025-12-13）
**核心架构：Platform-Only 模式**
- ✅ **统一缓存**：`PostgresCacheAdapter` → `platform_schema.app_cache`
- ✅ **统一队列**：`PgBossQueue` → `platform_schema.job` (pg-boss)
- ✅ **任务管理**：所有任务信息存储在 `job.data` (JSONB)
- ✅ **断点续传**：`CheckpointService` 通用化（操作 job.data）
- ✅ **智能阈值**：小任务直接处理，大任务队列处理（THRESHOLD=50）
**原有能力：**
- ✅ 存储服务（LocalAdapter ↔ OSSAdapter）
- ✅ 日志系统（Winston + 结构化JSON）
- ✅ 缓存服务（Memory ↔ Redis）
- ✅ 异步任务（MemoryQueue ↔ DatabaseQueue）
- ✅ 健康检查（Liveness + Readiness）
- ✅ 监控指标（数据库连接/内存/API）
- ✅ 数据库连接池（Serverless优化）
- ✅ **100%测试通过**
**测试覆盖：**
- ✅ 单元测试：8个全部通过
- ✅ 集成测试：2个全部通过
- ✅ 架构验证：Platform-Only 验证通过
**技术债务：**
- ⚠️ Phase 8 全面测试（断点续传压力测试、1000篇文献完整流程）
- ⚠️ Phase 9 SAE 部署验证
#### 2. AIA模块 - AI智能问答（已完成）
- ✅ 10个专业智能体
@@ -126,11 +147,13 @@
### 🚧 正在开发模块
#### 4. ASL模块 - AI智能文献（正在开发）
#### 4. ASL模块 - AI智能文献 🏆 **Postgres-Only 架构改造完成！**
**开发进度**：
- ✅ **标题摘要初筛MVP**：完整流程（设置→启动→审核→结果→导出）
- ✅ **全文复筛后端**：LLM服务、数据库、批处理、API（Day 2-5完成）
- 🚧 **全文复筛前端UI**：4个核心页面（Day 6-8，预计2.5天）
- ✅ **全文复筛后端**：LLM服务、数据库、批处理、API
- ✅ **🏆 Postgres-Only 架构改造**：智能阈值、任务拆分、断点续传（Phase 6完成）
- 🚧 **全文复筛前端UI**：4个核心页面（待开发）
**核心功能**：
- 双模型并行筛选（DeepSeek-V3 + Qwen-Max）
@@ -139,15 +162,22 @@
- 医学逻辑验证 + 证据链验证
- Excel批量导出
**技术亮点**：
- Nougat优先 + PyMuPDF降级（PDF提取）
- 3层JSON解析（容错机制）
- 冲突检测与人工复核
- 云原生存储（零文件落盘）
**🚀 Postgres-Only 架构亮点**：
- ✅ **智能双模式**：<50篇直接处理，≥50篇队列处理
- ✅ **任务拆分**：1000篇 → 20个批次，每批50篇
- ✅ **断点续传**：支持2-24小时长任务，实例重启可恢复
- ✅ **Platform层统一**：任务管理信息存储在 `job.data`，不在业务表中
- ✅ **零额外成本**：使用 pg-boss，无需 Redis
- ✅ **高可靠性**：自动重试3次，6小时过期保护
**技术实现**：
- `screeningService.ts`：智能阈值判断，推送批次任务
- `screeningWorker.ts`：批次处理，断点续传
- `CheckpointService`：操作 job.data，所有模块通用
**详细文档**：[ASL模块当前状态](../03-业务模块/ASL-AI智能文献/00-模块当前状态与开发指南.md)
#### 5. DC模块 - 数据清洗整理 ✅ **Tool C MVP + NA处理 + Pivot优化完成！**
#### 5. DC模块 - 数据清洗整理 🏆 **Tool C MVP + Postgres-Only 架构改造完成！**
**开发进度**：
- ✅ **Tool B后端**：100%完成（1,658行代码）
@@ -156,6 +186,7 @@
- 路由集成（/api/v1/dc/tool-b）
- Prisma Schema（4个表）
- 100%云原生（复用平台能力）
- ✅ **🏆 Postgres-Only 架构改造**：智能阈值、任务拆分、断点续传（Phase 7完成）
- ❌ **Tool B前端**：0%（有V4原型设计，未实现）
- ✅ **Tool C（数据编辑器）**：**MVP + NA处理 + Pivot优化 + UX重大改进完成** ✅
@@ -195,6 +226,18 @@
- Excel健康检查（空值率、Token估算、拦截策略）
- 预设模板系统（肺癌、糖尿病、高血压）
**🚀 Postgres-Only 架构亮点**：
- ✅ **智能双模式**：<50条直接处理，≥50条队列处理
- ✅ **任务拆分**：1000条 → 20个批次，每批50条
- ✅ **断点续传**：支持长时间提取任务，实例重启可恢复
- ✅ **Platform层统一**：与 ASL 共用 CheckpointService
- ✅ **零额外成本**：使用 pg-boss，无需 Redis
**技术实现**：
- `ExtractionController.ts`：智能阈值判断，推送批次任务
- `extractionWorker.ts`：批次处理，断点续传
- `CheckpointService`：操作 job.data，所有模块通用
**技术亮点**：
- ✅ Excel内存处理（零落盘，云原生）
- ✅ 双模型交叉验证（减少AI幻觉）
@@ -413,14 +456,113 @@ npm run dev # http://localhost:3000
---
## 🏆 Postgres-Only 架构（2025-12-13 重大创新）
### 核心理念
**Platform-Only 模式**：所有平台级功能（缓存、队列、任务管理）统一在 Platform 层实现，业务层只关注业务逻辑。
### 架构演进
```
改造前：
业务层 (分散)
├── ASL: 任务管理字段 (6个)
└── DC: 任务管理字段 (6个)
❌ 代码重复
❌ 维护困难
改造后（Platform-Only）：
平台层 (统一)
├── platform_schema.job.data (pg-boss)
│ └── 所有任务管理信息
└── CheckpointService (通用)
└── 操作 job.data，所有模块复用
业务层 (简洁)
├── ASL: 只存储业务信息
└── DC: 只存储业务信息
✅ 无重复
✅ 易维护
✅ 符合3层架构
```
### 核心组件
| 组件 | 位置 | 功能 | 通用性 |
|------|------|------|--------|
| **PostgresCacheAdapter** | `common/cache/` | Postgres 缓存 | ✅ 所有模块 |
| **PgBossQueue** | `common/jobs/` | pg-boss 队列封装 | ✅ 所有模块 |
| **CheckpointService** | `common/jobs/` | 操作 job.data | ✅ 所有模块 |
| **任务拆分工具** | `common/jobs/utils.ts` | 智能拆分批次 | ✅ 所有模块 |
### 智能双模式处理
```typescript
const QUEUE_THRESHOLD = 50;
if (items.length >= 50) {
// 队列模式：可靠性优先
- 任务拆分（50条/批）
- 断点续传（每10条保存）
- 自动重试（3次）
- 支持24小时长任务
} else {
// 直接模式：性能优先
- 快速响应（<1分钟）
- 无队列延迟
- 适合小任务
}
```
### 技术亮点
1. **Platform-Only 模式**（首创）
- 利用 pg-boss 的 `job.data` 字段统一管理
- 业务表保持简洁，只存储业务信息
- CheckpointService 真正做到平台级通用
2. **智能阈值判断**
- 根据数据量自动选择处理模式
- 性能与可靠性的完美平衡
- 用户体验优化
3. **零额外成本**
- 不引入 Redis（年省￥8400）
- 使用已有 Postgres 实现缓存和队列
- 适合小团队快速迭代
4. **企业级可靠性**
- 断点续传：任务中断后可恢复
- 自动重试：失败任务重试3次
- 并发处理：支持多实例并行
- 长任务支持：可运行24小时
### 适用模块
- ✅ ASL 筛选服务（已改造）
- ✅ DC 提取服务（已改造）
- 📋 SSA 统计分析（未来）
- 📋 RVW 文献综述（未来）
### 详细文档
- [Postgres-Only 改造实施计划](../07-运维文档/09-Postgres-Only改造实施计划(完整版).md)
- [Postgres-Only 全能架构解决方案](../07-运维文档/08-Postgres-Only 全能架构解决方案.md)
- [工作总结（2025-12-13）](../08-项目管理/03-每周计划/2025-12-13-Postgres-Only架构改造完成.md)
---
## 🌟 技术亮点
1. ✅ **适配器模式**：存储/缓存/日志支持本地↔云端零代码切换
2. ✅ **10个Schema一次性完成**：架构一次到位
3. ✅ **Prisma自动路由**：Schema迁移后，代码无需修改
4. ✅ **4个LLM集成**：DeepSeek、Qwen、GPT、Claude
5. ✅ **增量演进**：新旧并存，降低风险
6. ✅ **云原生就绪**：为SAE部署做好准备
1. ✅ **Platform-Only 架构**：统一任务管理，零代码重复 🏆 **新！**
2. ✅ **智能双模式处理**：小任务快速响应，大任务可靠执行 🏆 **新！**
3. ✅ **适配器模式**：存储/缓存/日志支持本地↔云端零代码切换
4. ✅ **10个Schema一次性完成**：架构一次到位
5. ✅ **Prisma自动路由**：Schema迁移后，代码无需修改
6. ✅ **4个LLM集成**：DeepSeek、Qwen、GPT、Claude
7. ✅ **增量演进**：新旧并存，降低风险
8. ✅ **云原生就绪**：为SAE部署做好准备
---
@@ -432,9 +574,9 @@ npm run dev # http://localhost:3000
---
**文档版本**：v1.7
**最后更新**：2025-12-10
**下次更新**：Tool C缺失值填补功能完成 或 MICE多重插补完成
**文档版本**：v1.8
**最后更新**：2025-12-13
**下次更新**：Phase 8 全面测试完成 或 Phase 9 SAE 部署完成
---