Files

HaHafeng 19f9c5ea93 docs(deployment): Fix 8 critical deployment issues and enhance documentation

Summary of fixes:
- Fix service discovery address (change .sae domain to internal IP)
- Unify timezone configuration (Asia/Shanghai for all services)
- Enhance ECS security group configuration (Redis/Weaviate port binding)
- Add image pull strategy best practices
- Add Python service memory management guidelines
- Update Dify API Key deployment strategy (avoid deadlock)
- Add SSH tunnel for RDS database access
- Add NAT gateway cost optimization explanation

Modified files (7 docs):
- 00-部署架构总览.md (enhanced with 7 sections)
- 03-Dify-ECS部署完全指南.md (security hardening)
- 04-Python微服务-SAE容器部署指南.md (timezone + service discovery)
- 05-Node.js后端-SAE容器部署指南.md (timezone configuration)
- PostgreSQL部署策略-摸底报告.md (timezone best practice)
- 07-关键配置补充说明.md (3 new sections)
- 08-部署检查清单.md (service address fix)

New files:
- 文档修正报告-20251214.md (comprehensive fix report)
- Review documents from technical team

Impact:
- Fixed 3 P0/P1 critical issues (100% connection failure risk)
- Fixed 3 P2 important issues (stability and maintainability)
- Added 2 P3 best practices (developer convenience)

Status: All deployment documents reviewed and corrected, ready for production deployment

2025-12-14 13:25:28 +08:00

23 KiB

Raw Blame History

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

文档版本： v1.8
创建日期： 2025-11-28
维护者： 开发团队
最后更新： 2025-12-13
重大进展： 🏆 Postgres-Only 架构改造完成（Phase 1-7） - Platform层统一任务管理、智能双模式处理、断点续传机制
文档目的： 快速了解系统当前状态，为新AI助手提供上下文

📋 快速导航

🎯 如果您是新的AI助手，请优先阅读：

本文档（5分钟） - 了解系统当前状态
前后端模块化架构设计-V2.md（15分钟） - 了解技术架构
[AI对接] 快速上下文.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 98%（7个功能+NA处理+Pivot优化+UX重大改进）	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模块当前状态

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模块当前状态

📁 项目结构概览

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秒）
数据库连接池：防止连接数耗尽
详细规范：云原生开发规范 ⭐ 必读

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周）

ASL全文复筛前端（Day 6-8）
- 4个核心页面：设置、进度、工作台、结果
- PDF上传和预览功能
- 双模型判断对比UI
- 实时进度监控
DC工具B完成（Day 4-7）
- ExtractionService实现
- 批量提取API
- 前端集成和测试

中期（1-2月）

DC模块完整实现（工具A、工具C、Portal）
ASL模块优化（Prompt优化、并发处理）
LLM网关统一抽取

长期（3月+）

SSA模块（智能统计分析）
ST模块（统计分析工具）
RVW模块（稿件审查系统）

📚 重要文档索引

🎯 必读文档（新AI助手）

⭐⭐⭐ 本文档 - 系统当前状态
⭐⭐⭐ 前后端模块化架构设计-V2.md - 架构总纲
⭐⭐⭐ 云原生开发规范.md - 开发规范（必读）
⭐⭐ 01-系统架构分层设计.md - 三层架构详解
⭐⭐ 09-总体需求文档(PRD).md - 产品需求

🚀 当前开发相关

🏗️ 架构设计

🔧 开发环境

环境要求

Node.js: v22.18.0+
PostgreSQL: 15+（当前使用15.14）
npm: 10+

快速启动

后端：

cd backend
npm install
npx prisma generate
npm run dev  # http://localhost:3001

前端：

cd frontend-v2
npm install
npm run dev  # http://localhost:3000

环境变量配置

参考：环境配置指南

⚠️ 重要注意事项

对新AI助手

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

常见陷阱

❌ 不要在业务模块中自己实现存储：使用 import { storage } from '@/common/storage'
❌ 不要硬编码配置：使用环境变量
❌ 不要依赖本地文件系统：使用OSS或内存处理
❌ 不要创建新的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`	智能拆分批次	✅ 所有模块

智能双模式处理

const QUEUE_THRESHOLD = 50;

if (items.length >= 50) {
  // 队列模式：可靠性优先
  - 任务拆分（50条/批）
  - 断点续传（每10条保存）
  - 自动重试（3次）
  - 支持24小时长任务
} else {
  // 直接模式：性能优先
  - 快速响应（<1分钟）
  - 无队列延迟
  - 适合小任务
}

技术亮点

Platform-Only 模式（首创）
- 利用 pg-boss 的 job.data 字段统一管理
- 业务表保持简洁，只存储业务信息
- CheckpointService 真正做到平台级通用
智能阈值判断
- 根据数据量自动选择处理模式
- 性能与可靠性的完美平衡
- 用户体验优化
零额外成本
- 不引入 Redis（年省￥8400）
- 使用已有 Postgres 实现缓存和队列
- 适合小团队快速迭代
企业级可靠性
- 断点续传：任务中断后可恢复
- 自动重试：失败任务重试3次
- 并发处理：支持多实例并行
- 长任务支持：可运行24小时

适用模块

✅ ASL 筛选服务（已改造）
✅ DC 提取服务（已改造）
📋 SSA 统计分析（未来）
📋 RVW 文献综述（未来）

详细文档

Postgres-Only 改造实施计划
[Postgres-Only 全能架构解决方案](../07-运维文档/08-Postgres-Only 全能架构解决方案.md)
工作总结（2025-12-13）

🌟 技术亮点

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

📞 联系方式

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

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

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

23 KiB Raw Blame History Unescape Escape