# AIclinicalresearch 系统当前状态与开发指南

> **文档版本：** v2.0  
> **创建日期：** 2025-11-28  
> **维护者：** 开发团队  
> **最后更新：** 2025-12-22  
> **重大进展：** 🏆 **DC Tool C Postgres-Only异步架构改造完成** - 性能提升99%，异步任务处理标准建立  
> **文档目的：** 快速了解系统当前状态，为新AI助手提供上下文

---

## 📋 快速导航

**🎯 如果您是新的AI助手**，请优先阅读：
1. **本文档**（5分钟） - 了解系统当前状态
2. [前后端模块化架构设计-V2.md](./前后端模块化架构设计-V2.md)（15分钟） - 了解技术架构
3. [[AI对接] 快速上下文.md](./%5BAI对接%5D%20快速上下文.md)（10分钟） - 快速上手指南

---

## 🎯 项目概述

### 项目名称
**壹证循科技 - AI临床研究平台**

### 核心定位
一个覆盖临床科研全生命周期、AI驱动的一站式智能科研平台

### 目标用户
- **主要用户**：临床医生、研究人员（三甲医院）
- **次要用户**：医院科研管理科室、信息中心
- **商业模式**：云端SaaS + 私有化部署 + 单机版

---

## 📊 业务模块概览（7大核心功能）

| 模块代号 | 模块名称 | 核心功能 | 商业价值 | 当前状态 | 优先级 |
|---------|---------|---------|---------|---------|--------|
| **AIA** | AI智能问答 | 10+专业智能体（选题评价、PICO梳理等） | ⭐⭐⭐⭐ | ✅ 已完成 | P1 |
| **PKB** | 个人知识库 | RAG问答、私人文献库 | ⭐⭐⭐ | ✅ 已完成 | P1 |
| **ASL** | AI智能文献 | 文献筛选、Meta分析、证据图谱 | ⭐⭐⭐⭐⭐ | 🚧 **正在开发** | **P0** |
| **DC** | 数据清洗整理 | ETL + 医学NER（百万行级数据） | ⭐⭐⭐⭐⭐ | ✅ **Tool B完成 + Tool C 99%（异步架构+性能优化-99%+多指标转换+7大功能）** | **P0** |
| **SSA** | 智能统计分析 | 队列/预测模型/RCT分析 | ⭐⭐⭐⭐⭐ | 📋 规划中 | P2 |
| **ST** | 统计分析工具 | 100+轻量化统计工具 | ⭐⭐⭐⭐ | 📋 规划中 | P2 |
| **RVW** | 稿件审查系统 | 方法学评估、审稿流程 | ⭐⭐⭐⭐ | 📋 规划中 | P3 |

---

## 🏗️ 技术架构（三层设计）

### 架构总览
```
┌─────────────────────────────────────────────────────────┐
│              业务模块层 (Product Layer)                    │
│  AIA | PKB | ASL | DC | SSA | ST | RVW                  │
│  ✅    ✅    🚧   🚧   📋   📋   📋                        │
└─────────────────────────────────────────────────────────┘
                      ↓ 依赖
┌─────────────────────────────────────────────────────────┐
│             通用能力层 (Capability Layer)                 │
│  后端：LLM网关 | 文档处理 | RAG引擎 | ETL引擎 | 医学NLP   │
│       ✅       ✅        ✅       🚧       📋            │
│  前端：Chat组件（Ant Design X）✅ 🎉 新增！             │
└─────────────────────────────────────────────────────────┘
                      ↓ 依赖
┌─────────────────────────────────────────────────────────┐
│              平台基础层 (Platform Layer)                  │
│  🏆 **Postgres-Only架构**（新）                          │
│  ├── 统一缓存：platform_schema.app_cache        ✅       │
│  ├── 统一队列：platform_schema.job (pg-boss)    ✅       │
│  ├── 任务管理：job.data 统一存储                ✅       │
│  └── 断点续传：CheckpointService 通用化         ✅       │
│                                                          │
│  存储 | 日志 | 缓存 | 任务 | 健康检查 | 监控 | 连接池     │
│  ✅    ✅    ✅    ✅    ✅        ✅    ✅                │
└─────────────────────────────────────────────────────────┘
```

### 技术栈

**前端**：
- React 19 + TypeScript 5 + Vite 7
- **Ant Design 6.0** + **Ant Design X 2.1** ✨ 新增！
- TailwindCSS 3 + React Query v5 + React Router DOM v7
- 架构：frontend-v2（模块化，顶部导航）
- **通用能力层**：shared/components/Chat（基于 Ant Design X）✅

**后端**：
- Fastify v4 (Node.js 22)
- Prisma 6 (10个Schema隔离)
- LLM：DeepSeek-V3, Qwen-Max, GPT-5-Pro, Claude-4.5
- 架构：增量演进（legacy + common + modules）

**数据库**：
- PostgreSQL 15 （Docker: postgres:15-alpine）
- 10个Schema隔离（platform/aia/pkb/asl/dc/ssa/st/rvw/admin/common）

**云原生部署**：
- 阿里云 SAE (Serverless 应用引擎)
- RDS PostgreSQL 15 + OSS (对象存储) + Redis (可选，Dify需要)

---

## 🚀 当前开发状态（2025-12-10）

### ✅ 已完成模块

#### 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）
- ✅ 健康检查（Liveness + Readiness）
- ✅ 监控指标（数据库连接/内存/API）
- ✅ 数据库连接池（Serverless优化）

**测试覆盖：**
- ✅ 单元测试：8个全部通过
- ✅ 集成测试：2个全部通过
- ✅ 架构验证：Platform-Only 验证通过

**技术债务：**
- ⚠️ Phase 8 全面测试（断点续传压力测试、1000篇文献完整流程）
- ⚠️ Phase 9 SAE 部署验证

#### 2. AIA模块 - AI智能问答（已完成）
- ✅ 10个专业智能体
- ✅ 流式对话 + 非流式对话
- ✅ 知识库模式（RAG检索）
- ✅ 批处理模式
- **状态**：生产就绪

#### 3. PKB模块 - 个人知识库（已完成）
- ✅ 知识库CRUD
- ✅ 文档上传（PDF/Word/TXT/MD）
- ✅ RAG问答
- ✅ 批处理任务
- **状态**：生产就绪

### 🚧 正在开发模块

#### 4. ASL模块 - AI智能文献 🏆 **Postgres-Only 架构改造完成！**

**开发进度**：
- ✅ **标题摘要初筛MVP**：完整流程（设置→启动→审核→结果→导出）
- ✅ **全文复筛后端**：LLM服务、数据库、批处理、API
- ✅ **🏆 Postgres-Only 架构改造**：智能阈值、任务拆分、断点续传（Phase 6完成）
- 🚧 **全文复筛前端UI**：4个核心页面（待开发）

**核心功能**：
- 双模型并行筛选（DeepSeek-V3 + Qwen-Max）
- PICOS标准判断
- 12字段结构化提取（全文复筛）
- 医学逻辑验证 + 证据链验证
- Excel批量导出

**🚀 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 + Postgres-Only 架构改造完成！**

**开发进度**：
- ✅ **Tool B后端**：100%完成（1,658行代码）
  - 4个核心服务（HealthCheck、Template、DualModel、Conflict）
  - 1个控制器（6个API端点）
  - 路由集成（/api/v1/dc/tool-b）
  - Prisma Schema（4个表）
  - 100%云原生（复用平台能力）
  - ✅ **🏆 Postgres-Only 架构改造**：智能阈值、任务拆分、断点续传（Phase 7完成）
- ❌ **Tool B前端**：0%（有V4原型设计，未实现）

- ✅ **Tool C（数据编辑器）**：**MVP + NA处理 + Pivot优化 + UX重大改进完成** ✅
  - ✅ Python微服务（~1800行）- Day 1 + NA处理优化 + 全量数据处理
  - ✅ Node.js后端（~3500行）- Day 2-3, Day 5-8增强 + 全量返回
  - ✅ 前端界面（~4000行）- Day 4-8, 筛选/行号/滚动条/全量加载
  - ✅ 通用 Chat 组件（~968行）- Day 5
  - ✅ 7个功能按钮（筛选、映射、分箱、条件、删NA、计算、Pivot）
  - ✅ NA处理优化（4个功能支持空值处理）
  - ✅ Pivot优化（保留未选列+原始列顺序）
  - ✅ 计算列方案B（安全列名映射，支持特殊字符 + 全角字符转换）
  - ✅ **UX重大改进**（Day 8）：
    - 列头筛选（Excel风格，Community版本，中文本地化）
    - 行号列（固定左侧，灰色背景）
    - 滚动条修复（修改MainLayout，整个页面无滚动条）
    - 全量数据（不再限制50行，筛选精确）
    - 删除预览提示条
  - **总计：~13068行** | **完成度：98%**

- ❌ **Tool A**：未开发
- ✅ **Portal**：已完成（Tool B + Tool C 入口）

**核心功能（Tool C，2025-12-10最新）**：
- 7个功能按钮：高级筛选、数值映射、生成分类变量、条件生成列、删除缺失值、计算列、Pivot转换
- NA处理支持：数值映射（保持/映射/删除）、分箱（保持/标记/分配）、条件（为空/不为空）
- Pivot优化：保留未选择的列、保持原始列顺序
- 计算列方案B：安全列名映射，支持中文括号等特殊字符 + 全角字符自动转换
- **UX重大改进**：
  - 列头筛选（Excel风格，Community版本，中文本地化，显示值计数）
  - 行号列（固定左侧，灰色背景，#列头）
  - 滚动条修复（修改MainLayout，整个页面无滚动条，只有表格内部滚动）
  - 全量数据（不再限制50行，筛选精确，所有操作全量返回）

**核心功能（Tool B）**：
- 双模型并发提取（DeepSeek-V3 + Qwen-Max）
- 自动冲突检测（字段级对比）
- Excel健康检查（空值率、Token估算、拦截策略）
- 预设模板系统（肺癌、糖尿病、高血压）

**🚀 Postgres-Only 架构亮点**：
- ✅ **智能双模式**：<50条直接处理，≥50条队列处理
- ✅ **任务拆分**：1000条 → 20个批次，每批50条
- ✅ **断点续传**：支持长时间提取任务，实例重启可恢复
- ✅ **Platform层统一**：与 ASL 共用 CheckpointService
- ✅ **零额外成本**：使用 pg-boss，无需 Redis

**技术实现**：
- `ExtractionController.ts`：智能阈值判断，推送批次任务
- `extractionWorker.ts`：批次处理，断点续传
- `CheckpointService`：操作 job.data，所有模块通用

**技术亮点**：
- ✅ Excel内存处理（零落盘，云原生）
- ✅ 双模型交叉验证（减少AI幻觉）
- ✅ 3层JSON解析（容错机制）
- ✅ 复用LLMFactory、storage、cache、jobQueue
- ✅ 预写Python函数架构（稳定、安全、高性能）
- ✅ 安全列名映射（支持特殊字符列名）

**待开发功能**：
- ⏳ 缺失值填补（均值/中位数/众数/固定值）
- ⏳ 多重插补（MICE）- 高优先级

**详细文档**：[DC模块当前状态](../03-业务模块/DC-数据清洗整理/00-模块当前状态与开发指南.md)

---

## 📁 项目结构概览

```
AIclinicalresearch/
├── frontend-v2/              # 🌐 前端（React 19 + TS）
│   └── src/
│       ├── framework/        # 框架层（布局、路由、权限）
│       ├── modules/          # 业务模块
│       │   ├── asl/          # ✅ AI智能文献
│       │   ├── aia/          # ✅ AI智能问答
│       │   ├── pkb/          # ✅ 个人知识库
│       │   ├── dc/           # ✅ 数据清洗（Tool C 完成）
│       │   └── ...
│       └── shared/           # 共享组件和工具
│           └── components/   # ✨ 通用能力层
│               └── Chat/     # ✅ Chat 通用组件（Ant Design X）
│
├── backend/                  # ⚙️ 后端（Fastify + Prisma）
│   └── src/
│       ├── common/           # ⭐ 平台基础设施（云原生）
│       │   ├── storage/      # 存储抽象层
│       │   ├── logging/      # 日志系统
│       │   ├── cache/        # 缓存服务
│       │   ├── jobs/         # 异步任务
│       │   └── ...
│       ├── legacy/           # 🔸 现有业务代码（稳定）
│       └── modules/          # 🌟 新架构模块
│           ├── asl/          # ✅ AI智能文献
│           └── dc/           # 🚧 数据清洗（开发中）
│
├── docs/                     # 📚 文档体系
│   ├── 00-系统总体设计/      # 架构设计
│   ├── 01-平台基础层/        # 平台能力
│   ├── 02-通用能力层/        # LLM、RAG等
│   ├── 03-业务模块/          # 各模块文档
│   ├── 04-开发规范/          # 云原生规范等
│   └── 08-项目管理/          # 计划和进度
│
└── prisma/
    └── schema.prisma         # 10个Schema定义
```

---

## 🎯 核心设计原则

### 1. 云原生架构 ☁️
- **无状态应用**：不依赖本地文件系统
- **存储抽象层**：适配器模式，零代码环境切换
- **异步任务**：避免Serverless超时（30秒）
- **数据库连接池**：防止连接数耗尽
- **详细规范**：[云原生开发规范](../04-开发规范/08-云原生开发规范.md) ⭐ **必读**

### 2. 模块化与独立部署 🔧
- **前后端分离**：每个模块前后端完全独立
- **Schema隔离**：数据库层面模块隔离（10个Schema）
- **路由独立**：每个模块有独立的API路由前缀
- **支持独立销售**：任何模块都可独立打包

### 3. 商业模式灵活性 💰
- **4种部署形态**：云端SaaS、私有化部署、单机版、混合部署
- **多版本支持**：专业版/高级版/旗舰版（Feature Flag控制）
- **AI成本可控**：动态切换LLM模型
- **模块化售卖**：任何模块都可独立销售

### 4. 渐进式演进 📈
- **新旧并存**：Frontend-v2（新）+ Frontend（旧保留）
- **增量改造**：Legacy模块保持稳定，新模块标准化
- **Just-in-time**：聚焦当前，架构预留，避免过度设计

---

## 📅 开发时间线

| 时间 | 阶段 | 主要成果 |
|------|------|---------|
| **2025-11-12** | Week 1 | ✅ 数据库Schema隔离（10个Schema） |
| **2025-11-13~14** | Week 2 | ✅ 前端模块化架构 + 后端分层 |
| **2025-11-17** | Week 2+ | ✅ 平台基础设施（8个核心模块） |
| **2025-11-18~21** | Week 3~4 | ✅ ASL标题摘要初筛MVP |
| **2025-11-22~23** | ASL Day 2-5 | ✅ ASL全文复筛后端完成 |
| **2025-11-26~27** | DC Day 2-3 | ✅ DC工具B健康检查+模板管理 |
| **2025-11-28** | 当前 | 🚧 ASL全文复筛前端 + DC工具B开发 |

---

## 🎯 下一步计划

### 短期（1-2周）
1. **ASL全文复筛前端**（Day 6-8）
   - 4个核心页面：设置、进度、工作台、结果
   - PDF上传和预览功能
   - 双模型判断对比UI
   - 实时进度监控

2. **DC工具B完成**（Day 4-7）
   - ExtractionService实现
   - 批量提取API
   - 前端集成和测试

### 中期（1-2月）
3. DC模块完整实现（工具A、工具C、Portal）
4. ASL模块优化（Prompt优化、并发处理）
5. LLM网关统一抽取

### 长期（3月+）
6. SSA模块（智能统计分析）
7. ST模块（统计分析工具）
8. RVW模块（稿件审查系统）

---

## 📚 重要文档索引

### 🎯 必读文档（新AI助手）
1. ⭐⭐⭐ **本文档** - 系统当前状态
2. ⭐⭐⭐ [前后端模块化架构设计-V2.md](./前后端模块化架构设计-V2.md) - 架构总纲
3. ⭐⭐⭐ [云原生开发规范.md](../04-开发规范/08-云原生开发规范.md) - 开发规范（必读）
4. ⭐⭐ [01-系统架构分层设计.md](./01-系统架构分层设计.md) - 三层架构详解
5. ⭐⭐ [09-总体需求文档(PRD).md](./09-总体需求文档\(PRD\).md) - 产品需求

### 🚀 当前开发相关
- [ASL模块当前状态](../03-业务模块/ASL-AI智能文献/00-模块当前状态与开发指南.md)
- [DC模块README](../03-业务模块/DC-数据清洗整理/README.md)
- [DC Day3完成总结](../03-业务模块/DC-数据清洗整理/06-开发记录/Day3完成总结.md)

### 🏗️ 架构设计
- [平台基础设施规划](../09-架构实施/04-平台基础设施规划.md)
- [云原生部署架构指南](../09-架构实施/03-云原生部署架构指南.md)
- [数据库设计规范](../04-开发规范/01-数据库设计规范.md)

---

## 🔧 开发环境

### 环境要求
```
Node.js: v22.18.0+
PostgreSQL: 15+（当前使用15.14）
npm: 10+
```

### 快速启动

**后端**：
```bash
cd backend
npm install
npx prisma generate
npm run dev  # http://localhost:3001
```

**前端**：
```bash
cd frontend-v2
npm install
npm run dev  # http://localhost:3000
```

### 环境变量配置
参考：[环境配置指南](../07-运维文档/01-环境配置指南.md)

---

## ⚠️ 重要注意事项

### 对新AI助手
1. ✅ **优先阅读云原生开发规范**：所有代码必须遵守
2. ✅ **使用平台基础设施**：不要重复实现存储、日志、缓存等
3. ✅ **遵循Schema隔离**：每个模块的表必须在对应的Schema中
4. ✅ **查看最新开发记录**：了解当前开发状态和已知问题

### 常见陷阱
1. ❌ **不要在业务模块中自己实现存储**：使用 `import { storage } from '@/common/storage'`
2. ❌ **不要硬编码配置**：使用环境变量
3. ❌ **不要依赖本地文件系统**：使用OSS或内存处理
4. ❌ **不要创建新的Prisma实例**：使用全局 `prisma` 实例

---

## 📊 项目统计

### 代码量
- **前端**：约 15,000 行（TypeScript + TSX）
- **后端**：约 20,000 行（TypeScript）
- **文档**：约 50,000 行（Markdown）
- **总计**：约 85,000 行

### 模块完成度
- ✅ **已完成**：AIA（100%）、PKB（100%）、平台基础层（100%）
- 🚧 **开发中**：ASL（80%）、DC（Tool C 98%，Tool B后端100%，Tool B前端0%）
- 📋 **未开始**：SSA、ST、RVW

### 测试覆盖率
- **平台基础层**：100%（8/8模块全部通过）
- **AIA模块**：手动测试通过
- **PKB模块**：手动测试通过
- **ASL模块**：部分自动化测试（31个REST Client测试用例）
- **DC模块**：开发中

---

## 🏆 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. ✅ **Platform-Only 架构**：统一任务管理，零代码重复 🏆 **新！**
2. ✅ **智能双模式处理**：小任务快速响应，大任务可靠执行 🏆 **新！**
3. ✅ **适配器模式**：存储/缓存/日志支持本地↔云端零代码切换
4. ✅ **10个Schema一次性完成**：架构一次到位
5. ✅ **Prisma自动路由**：Schema迁移后，代码无需修改
6. ✅ **4个LLM集成**：DeepSeek、Qwen、GPT、Claude
7. ✅ **增量演进**：新旧并存，降低风险
8. ✅ **云原生就绪**：为SAE部署做好准备

---

## 📞 联系方式

- **项目负责人**：技术架构师
- **文档维护**：开发团队
- **问题反馈**：GitHub Issues

---

**文档版本**：v1.8  
**最后更新**：2025-12-13  
**下次更新**：Phase 8 全面测试完成 或 Phase 9 SAE 部署完成

---

**🎉 祝新的AI助手工作顺利！所有信息已梳理完毕，可以无缝衔接！**