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

docs(platform): Add database documentation system and restructure deployment docs

Browse Source 
Completed:
- Add 6 core database documents (docs/01-平台基础层/07-数据库/)
  Architecture overview, migration history, environment comparison,
  tech debt tracking, seed data management, PostgreSQL extensions
- Restructure deployment docs: archive 20 legacy files to _archive-2025/
- Create unified daily operations manual (01-日常更新操作手册.md)
- Add pending deployment change tracker (03-待部署变更清单.md)
- Update database development standard to v3.0 (three iron rules)
- Fix Prisma schema type drift: align @db.* annotations with actual DB
  IIT: UUID/Timestamptz(6), SSA: Timestamp(6)/VarChar(20/50/100)
- Add migration: 20260227_align_schema_with_db_types (idempotent ALTER)
- Add Cursor Rule for auto-reminding deployment change documentation
- Update system status guide v6.4 with deployment and DB doc references
- Add architecture consultation docs (Prisma guide, SAE deployment guide)

Technical details:
- Manual migration due to shadow DB limitation (TD-001 in tech debt)
- Deployment docs reduced from 20+ scattered files to 3 core documents
- Cursor Rule triggers on schema.prisma, package.json, Dockerfile changes

Made-with: Cursor
This commit is contained in:
HaHafeng
2026-02-27 14:35:25 +08:00
parent 9b8490b4d0
commit 6124c7abc6
48 changed files with 3009 additions and 582 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,10 +1,11 @@
# AIclinicalresearch 系统当前状态与开发指南
> **文档版本：** v6.3
> **文档版本：** v6.4
> **创建日期：** 2025-11-28
> **维护者：** 开发团队
> **最后更新：** 2026-02-26
> **最后更新：** 2026-02-27
> **🎉 重大里程碑：**
> - **🆕 2026-02-27：数据库文档体系 + 部署文档体系 + Prisma Schema 对齐完成！** 6 篇数据库核心文档 + 部署文档归档整理 + 统一操作手册 + 数据库开发规范 v3.0 + Cursor Rule 自动提醒 + Schema 类型漂移修正
> - **🆕 2026-02-26：ASL 工具 4 SR 图表生成器 + 工具 5 Meta 分析引擎开发完成！** PRISMA 流程图（中英切换）+ 基线特征表 + Meta 分析（HR/二分类/连续型）+ 森林图/漏斗图 + R Docker meta 包 + E2E 36/36 通过
> - **🆕 2026-02-26：CRA Agent V3.0 P0+P1 全部完成！** 自驱动质控流水线 + ChatOrchestrator + LLM Function Calling + E2E 54/54 通过
> - **2026-02-24：ASL 工具 3 V2.0 架构升级至散装派发 + Aggregator！** 9 条研发红线 + 散装派发与轮询收口任务模式指南 v1.1 沉淀
@@ -30,12 +31,14 @@
> - **2026-01-24：Protocol Agent 框架完成！** 可复用Agent框架+5阶段对话流程
> - **2026-01-22：OSS 存储集成完成！** 阿里云 OSS 正式接入平台基础层
>
> **🆕 最新进展（ASL 工具 4+5 开发完成 2026-02-26）：**
> - ✅ **🎉🆕 ASL 工具 4 SR 图表生成器完成** — PRISMA 2020 流程图（中英切换）+ 基线特征表 + 双通道数据源（项目流水线/Excel）+ SVG/PNG 导出
> - ✅ **🎉🆕 ASL 工具 5 Meta 分析引擎完成** — HR/二分类/连续型 3 种数据类型 + 随机/固定效应模型 + 森林图/漏斗图 + R Docker meta 包 + E2E 36/36 通过
> - ✅ **🆕 R Docker 镜像更新** — 新增 meta 包，工具总数从 12 增至 13（ST_META_ANALYSIS）
> - ✅ **🎉 ASL 工具 3 M1+M2 开发完成** — 散装派发+Aggregator + MinerU VLM + XML Prompt + HITL 审核抽屉 + Excel 导出
> - ✅ **🎉 SSA Phase I-IV 全部开发完成** — Session 黑板 + 意图路由器 + 对话层 LLM + 方法咨询 + QPER 集成，E2E 107/107
> **🆕 最新进展（数据库文档体系 + 部署文档整理 2026-02-27）：**
> - ✅ **🆕 数据库文档体系建立** — 6 篇核心文档（架构总览/迁移历史/环境对照/技术债务/种子数据/PG扩展），位于 `docs/01-平台基础层/07-数据库/`
> - ✅ **🆕 Prisma Schema 类型漂移修正** — IIT/SSA 模型 @db.* 注解对齐 + 手动迁移 + Tech Debt 注释
> - ✅ **🆕 部署文档体系整理** — 归档 2025 旧文档 + 统一操作手册 + 待部署变更清单 + README 重写
> - ✅ **🆕 数据库开发规范 v3.0** — 三条铁律 + 变更记录规则 + Shadow DB 降级方案 + 事故案例
> - ✅ **🆕 Cursor Rule 自动提醒** — 修改 Schema/依赖时自动提醒更新待部署变更清单
> - ✅ **🎉 ASL 工具 4 SR 图表生成器完成** — PRISMA 2020 流程图（中英切换）+ 基线特征表 + 双通道数据源 + SVG/PNG 导出
> - ✅ **🎉 ASL 工具 5 Meta 分析引擎完成** — HR/二分类/连续型 3 种数据类型 + 森林图/漏斗图 + R Docker meta 包 + E2E 36/36
> - ✅ **🎉 CRA Agent V3.0 P0+P1 完成** — ChatOrchestrator + LLM Function Calling + 4 工具 + E2E 54/54
>
> **部署状态：** ✅ 生产环境运行中 | 公网地址：http://8.140.53.236/
@@ -155,14 +158,11 @@
- ✅ Node.js后端（v1.3）- 内网：172.17.173.73:3001
- ✅ 前端Nginx（v1.0）- 内网：172.17.173.72:80
- ✅ CLB负载均衡 - 公网：http://8.140.53.236/
- RDS PostgreSQL 15（生产环境运行中）
- RDS PostgreSQL 15（生产环境运行中，14个Schema）
- OSS对象存储（✅ 2026-01-22 已集成，4个Bucket）
- ACR容器镜像仓库（已推送3个镜像）
- 阿里云 ACR (容器镜像服务) ✅ 已推送3个镜像（Frontend、Backend、Python）
- 阿里云 RDS (PostgreSQL 15) ✅ 已迁移数据
- RDS PostgreSQL 15 + OSS (对象存储) + NAT网关
- ACR (容器镜像服务 - 个人版免费)
- **部署状态**：🚀 **进行中**（PostgreSQL✅、Python微服务✅、前端镜像✅、Node.js后端⏳）
- ACR容器镜像仓库（已推送 4 个镜像：Frontend、Backend、Python、R Statistics）
- **部署状态**：✅ **生产环境运行中**
- **部署文档**：`docs/05-部署文档/`（操作手册 + 待部署变更清单 + 归档）
---
@@ -1109,9 +1109,9 @@ docs/03-业务模块/Redcap/ # REDCap文档体系（新增）
---
## 🚀 阿里云生产环境部署状态（2025-12-24）
## 🚀 阿里云生产环境部署状态（2026-02-27 更新）
### ✅ 已完成部署
### ✅ 已完成部署（全部运行中）
#### 1. 基础设施层
- ✅ **VPC网络**：`vpc-2ze055cptkew9c38w4r06`（172.17.0.0/16）
@@ -1119,6 +1119,7 @@ docs/03-业务模块/Redcap/ # REDCap文档体系（新增）
- ✅ **安全组**：`sg-2zedk6fi8sgmmcwdu7tu`
- ✅ **交换机**：2个（可用区F + 可用区A）
- ✅ **SAE命名空间**：`cn-beijing:test-airesearch`
- ✅ **CLB负载均衡** — 公网：http://8.140.53.236/
#### 2. 数据存储层
- ✅ **RDS PostgreSQL 15**
@@ -1126,117 +1127,46 @@ docs/03-业务模块/Redcap/ # REDCap文档体系（新增）
- 规格: 2核4GB
- 内网地址: `pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432`
- 数据库: `ai_clinical_research`
- **数据迁移**: ✅ 完成（90MB SQL文件，约12秒导入）
- **Schema验证**: ✅ 11个Schema全部迁移成功
- **数据验证**: ✅ 用户3条、项目2条、文献1204条
- **部署时间**: 2025-12-24
- **Schema**: 14 个隔离 Schema（platform/aia/pkb/asl/dc/iit/ssa/ssa_schema/st/rvw/admin/common/capability/ekb）
- **扩展**: pgvector 0.8.1 + pg_bigm 1.2
- **Prisma 迁移**: 15 个已应用（含 2026-02-27 类型对齐迁移）
- ✅ **OSS对象存储**
- Bucket: `ai-clinical-research`
- 存储类型: 标准存储（同城冗余）
- 4 个 Bucket（生产/开发 × 数据/静态）
- 内网域名: `ai-clinical-research.oss-cn-beijing-internal.aliyuncs.com`
- RAM用户: `oss-bucket-put-object@1991407246109125.onaliyun.com`
- AccessKey: 已配置（不公开）
#### 3. 容器镜像服务（ACR）
- ✅ **命名空间**: `ai-clinical`
- ✅ **Registry**: `crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com`
- ✅ **已推送镜像**:
- **前端Nginx**: `ai-clinical_frontend-nginx:v1.0`（约50MB）
- 构建时间: 2025-12-24
- 基础镜像: `nginx:alpine`
- 功能: React SPA + Nginx反向代理 + 动态环境变量
- 配置文件: `frontend-v2/Dockerfile`, `nginx.conf`, `.dockerignore`
- **Python微服务**: `python-extraction:v1.0`（1.12GB）
- 构建时间: 2025-12-24
- 基础镜像: `python:3-slim`
- 功能: PDF提取（PyMuPDF）+ 数据清洗（pandas/numpy/polars）
- 特性: 移除Nougat（减小1.5GB）、使用阿里云Debian源
- 配置文件: `extraction_service/Dockerfile`, `requirements-prod.txt`, `.dockerignore`
- **Node.js后端**: `backend-service:v1.0`（838MB，压缩后~186MB）✨ 新增！
- 构建时间: 2025-12-24（约5分钟）
- 基础镜像: `node:alpine`
- 构建策略: 改进版方案B（本地编译+Docker打包）
- 技术突破: 修复200+TypeScript错误、手动补全30+Prisma关系字段
- 架构特性: Postgres-Only（pg-boss队列+PostgreSQL缓存）
- 配置文件: `backend/Dockerfile`, `backend/.dockerignore`, `backend/prisma/schema.prisma`
- ✅ **已推送镜像**: 4 个
- **前端Nginx**: `ai-clinical_frontend-nginx`
- **Node.js后端**: `backend-service`
- **Python微服务**: `python-extraction`
- **R 统计引擎**: `r-statistics-service`（含 meta 包）
### 🚧 进行中
#### 4. SAE 应用（全部运行中）
- ✅ **Python微服务** — 内网：`172.17.173.66:8000`（1核2GB）
- ✅ **Node.js后端** — 内网：`172.17.173.73:3001`（2核4GB）
- ✅ **前端Nginx** — 内网：`172.17.173.72:80`（1核2GB）
- ✅ **R 统计引擎** — 通过后端调用
#### 4. SAE应用部署
- ✅ **Python微服务**: 已成功部署到SAE轻量版
- 应用名称: `python-extraction-test`
- 规格: 1核2GB
- 内网地址: `http://172.17.173.66:8000`
- 状态: 运行中 ✅
### 📊 部署文档体系（2026-02-27 重构）
- ⏳ **Node.js后端**: 镜像已推送，待部署到SAE
- 目标规格: 1核2GB（测试环境）
- 端口: 8000
- 健康检查: `/api/health`
- ⏳ **Node.js后端**: Docker镜像待构建
- 目标规格: 2核4GB
- 端口: 3001
- 依赖: RDS PostgreSQL
- ⏳ **前端Nginx**: 镜像已推送，待部署到SAE
- 目标规格: 1核2GB
- 端口: 80
- 需配置: 后端API内网地址
**核心文档**（位于 `docs/05-部署文档/`）：
- ⭐ [00-阿里云SAE最新真实状态记录.md](../05-部署文档/00-阿里云SAE最新真实状态记录.md) — 生产环境实时状态
- ⭐ [01-日常更新操作手册.md](../05-部署文档/01-日常更新操作手册.md) — 构建/推送/部署 SOP
- ⭐ [03-待部署变更清单.md](../05-部署文档/03-待部署变更清单.md) — 待部署变更追踪
### 📋 待完成
**历史文档**：已归档至 `docs/05-部署文档/_archive-2025首次部署/`
- [ ] Python微服务部署到SAE
- [ ] Node.js后端Docker镜像构建
- [ ] Node.js后端部署到SAE
- [ ] 前端Nginx部署到SAE
- [ ] 配置服务间内网通信
- [ ] 全链路验证测试
- [ ] Dify AI服务部署（可选）
### 📚 数据库文档体系（2026-02-27 新建）
### 📊 部署文档
**部署进度总览**：
- [00-部署进度总览.md](../05-部署文档/00-部署进度总览.md) - 🎯 **一站式部署状态查看**
**操作手册**：
- [07-前端Nginx-SAE部署操作手册.md](../05-部署文档/07-前端Nginx-SAE部署操作手册.md)
- [08-PostgreSQL数据库部署操作手册.md](../05-部署文档/08-PostgreSQL数据库部署操作手册.md)
- Python微服务SAE部署操作手册（待创建）
**技术指南**：
- [01-快速部署SOP-零基础版.md](../05-部署文档/01-快速部署SOP-零基础版.md) - 完整部署流程
- [04-Python微服务-SAE容器部署指南.md](../05-部署文档/04-Python微服务-SAE容器部署指南.md)
- [06-前端Nginx-SAE容器部署指南.md](../05-部署文档/06-前端Nginx-SAE容器部署指南.md)
### 🎯 部署关键成就
1. **PostgreSQL数据迁移** ✅
- 采用`pg_dump`全量导出/导入方案
- 11个Schema完整迁移
- 数据一致性验证通过
- 安全加固（外网访问已关闭）
2. **前端Nginx镜像优化** ✅
- 解决Docker Hub网络问题（使用通用标签）
- 修复30个TypeScript编译错误
- 多阶段构建优化
- 健康检查通过
3. **Python微服务镜像优化** ✅
- 移除Nougat OCR（减小1.5GB）
- 使用阿里云Debian镜像源（解决apt-get网络问题）
- 保留数据清洗功能（pandas/numpy/polars）
- 运行时依赖优化（libgl1、libglib2.0）
4. **镜像配置文件Git管理** ✅
- Dockerfile: ✅ 已提交Git（构建蓝图）
- .dockerignore: ✅ 已提交Git（优化构建）
- 依赖文件: ✅ 已提交Git（可复现）
- 敏感信息: ❌ 禁止提交（.env等）
**核心文档**（位于 `docs/01-平台基础层/07-数据库/`）：
- [00-数据库架构总览.md](../01-平台基础层/07-数据库/00-数据库架构总览.md) — 14 个 Schema、表结构、扩展
- [01-Prisma迁移历史与变更日志.md](../01-平台基础层/07-数据库/01-Prisma迁移历史与变更日志.md) — 15 个迁移记录
- [02-环境状态对照表.md](../01-平台基础层/07-数据库/02-环境状态对照表.md) — 本地 vs 测试 RDS
- [03-技术债务追踪.md](../01-平台基础层/07-数据库/03-技术债务追踪.md) — 6 项技术债务
- [04-种子数据管理.md](../01-平台基础层/07-数据库/04-种子数据管理.md) — Prompt/SSA/Agent 种子数据
- [05-PostgreSQL扩展与特性.md](../01-平台基础层/07-数据库/05-PostgreSQL扩展与特性.md) — pgvector/pg_bigm/pg-boss
### 💰 当前运行成本估算
@@ -1247,10 +1177,10 @@ docs/03-业务模块/Redcap/ # REDCap文档体系（新增）
| NAT网关 | 小型 | ¥60 | ✅ 运行中 |
| EIP流量 | 5Mbps | ¥40 | ✅ 运行中 |
| ACR镜像仓库 | 个人版 | ¥0（免费） | ✅ 运行中 |
| SAE - Python | 1核2GB×1 | ¥60 | ⏳ 待部署 |
| SAE - Node.js | 2核4GB×1 | ¥120 | ⏳ 待部署 |
| SAE - Frontend | 1核2GB×1 | ¥60 | ⏳ 待部署 |
| **总计** | - | **¥602/月** | 部署中 |
| SAE - Python | 1核2GB×1 | ¥60 | ✅ 运行中 |
| SAE - Node.js | 2核4GB×1 | ¥120 | ✅ 运行中 |
| SAE - Frontend | 1核2GB×1 | ¥60 | ✅ 运行中 |
| **总计** | - | **¥602/月** | ✅ 全部运行中 |
---
@@ -1296,9 +1226,11 @@ AIclinicalresearch/
├── docs/ # 📚 文档体系
│ ├── 00-系统总体设计/ # 架构设计
│ ├── 01-平台基础层/ # 平台能力
│ │ └── 07-数据库/ # 🆕 数据库文档（6篇核心文档）
│ ├── 02-通用能力层/ # LLM、RAG等
│ ├── 03-业务模块/ # 各模块文档
│ ├── 04-开发规范/ # 云原生规范等
│ ├── 04-开发规范/ # 云原生规范 + 数据库规范 v3.0
│ ├── 05-部署文档/ # 🆕 部署操作手册 + 变更清单
│ └── 08-项目管理/ # 计划和进度
│
└── prisma/
@@ -1358,6 +1290,8 @@ AIclinicalresearch/
| **2026-01-21** | **🎉 Dify替换完成** | ✅ PKB 成功替换 Dify，完全使用自研 pgvector RAG 引擎 |
| **2026-01-22** | **🆕 OSS存储集成** | ✅ 阿里云OSS接入，PKB文档存储云端化，建立存储开发规范 |
| **2026-02-22** | **SSA Phase I-IV 完成** 🎉 | ✅ Session黑板+意图路由+对话LLM+方法咨询+QPER集成，E2E 107/107 |
| **2026-02-26** | **ASL 工具 4+5 完成** 🎉 | ✅ SR图表生成器+Meta分析引擎+R Docker meta包+E2E 36/36 |
| **2026-02-27** | **DB文档+部署体系** 📚 | ✅ 6篇数据库文档+部署归档+统一操作手册+开发规范v3.0+Schema对齐 |
| **当前** | **PKB模块生产可用** | ✅ 核心功能全部实现（95%），自研RAG+OSS存储上线 |
| **2026-01-07 晚** | **RVW模块开发完成** 🎉 | ✅ Phase 1-3完成（后端迁移+数据库扩展+前端重构） |
@@ -1445,11 +1379,18 @@ AIclinicalresearch/
- [DC模块README](../03-业务模块/DC-数据清洗整理/README.md)
- [DC Day3完成总结](../03-业务模块/DC-数据清洗整理/06-开发记录/Day3完成总结.md)
### 🚀 部署文档（新增）
- ⭐ [00-部署进度总览.md](../05-部署文档/00-部署进度总览.md) - **一站式部署状态查看**
- [01-快速部署SOP-零基础版.md](../05-部署文档/01-快速部署SOP-零基础版.md) - 完整部署流程
- [07-前端Nginx-SAE部署操作手册.md](../05-部署文档/07-前端Nginx-SAE部署操作手册.md)
- [08-PostgreSQL数据库部署操作手册.md](../05-部署文档/08-PostgreSQL数据库部署操作手册.md)
### 🚀 部署文档
- ⭐ [00-阿里云SAE最新真实状态记录.md](../05-部署文档/00-阿里云SAE最新真实状态记录.md) - 生产环境实时状态
- ⭐ [01-日常更新操作手册.md](../05-部署文档/01-日常更新操作手册.md) - 构建/推送/部署 SOP
- ⭐ [03-待部署变更清单.md](../05-部署文档/03-待部署变更清单.md) - 待部署变更追踪
### 🗄️ 数据库文档（2026-02-27 新建）
- ⭐ [00-数据库架构总览.md](../01-平台基础层/07-数据库/00-数据库架构总览.md) - 14 个 Schema + 表结构
- [01-Prisma迁移历史与变更日志.md](../01-平台基础层/07-数据库/01-Prisma迁移历史与变更日志.md) - 迁移记录
- [02-环境状态对照表.md](../01-平台基础层/07-数据库/02-环境状态对照表.md) - 本地 vs RDS
- [03-技术债务追踪.md](../01-平台基础层/07-数据库/03-技术债务追踪.md) - 技术债务清单
- [04-种子数据管理.md](../01-平台基础层/07-数据库/04-种子数据管理.md) - 种子数据维护
- [05-PostgreSQL扩展与特性.md](../01-平台基础层/07-数据库/05-PostgreSQL扩展与特性.md) - pgvector/pg_bigm/pg-boss
### 🏗️ 架构设计
- [平台基础设施规划](../09-架构实施/04-平台基础设施规划.md)
@@ -1542,11 +1483,11 @@ npm run dev # http://localhost:3000
- 📋 **未开始**：ST
### 部署完成度
- ✅ **基础设施**：VPC（100%）、NAT网关（100%）、安全组（100%）
- ✅ **数据存储**：RDS PostgreSQL（100%）、OSS（100%）
- ✅ **容器镜像**：前端Nginx（100%）、Python微服务（100%）、Node.js后端（100%）✨ 新增！
- ✅ **SAE应用**：Python微服务（100%，已运行）、Node.js后端（镜像已推送，待部署）、前端Nginx（待部署）
- 📋 **验证测试**：全链路测试（待进行）
- ✅ **基础设施**：VPC（100%）、NAT网关（100%）、安全组（100%）、CLB（100%）
- ✅ **数据存储**：RDS PostgreSQL（100%，14 Schema）、OSS（100%，4 Bucket）
- ✅ **容器镜像**：前端Nginx + Node.js后端 + Python微服务 + R统计引擎（全部 100%）
- ✅ **SAE应用**：全部 4 个服务运行中（Python + Node.js + Frontend + R）
- ✅ **数据库文档**：6 篇核心文档 + 开发规范 v3.0 + 待部署变更清单
### 测试覆盖率
- **平台基础层**：100%（8/8模块全部通过）
@@ -1688,9 +1629,9 @@ if (items.length >= 50) {
---
**文档版本**：v6.3
**最后更新**：2026-02-26
**本次更新**：ASL 工具 4 SR 图表生成器 + 工具 5 Meta 分析引擎开发完成（PRISMA 中英切换 + Meta 分析 HR/二分类/连续型 + R Docker meta 包 + E2E 36/36）
**文档版本**：v6.4
**最后更新**：2026-02-27
**本次更新**：数据库文档体系建立（6 篇核心文档）+ 部署文档整理归档 + Prisma Schema 类型漂移修正 + 数据库开发规范 v3.0 + Cursor Rule 自动提醒 + 部署状态更新为全部运行中
---