docs: complete documentation system (250+ files)
- System architecture and design documentation - Business module docs (ASL/AIA/PKB/RVW/DC/SSA/ST) - ASL module complete design (quality assurance, tech selection) - Platform layer and common capabilities docs - Development standards and API specifications - Deployment and operations guides - Project management and milestone tracking - Architecture implementation reports - Documentation templates and guides
This commit is contained in:
234
docs/00-项目概述/壹证循科技AI科研产品 - 技术架构白皮书.md
Normal file
234
docs/00-项目概述/壹证循科技AI科研产品 - 技术架构白皮书.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# **壹证循科技AI科研产品 \- 技术架构白皮书**
|
||||
|
||||
## **1\. 执行摘要 (Executive Summary)**
|
||||
|
||||
本文档为“壹证循科技”AI科研产品套件提供了一个统一的技术架构方案。
|
||||
|
||||
**核心战略**：采用\*\*“演进式架构”**。以**“模块化单体”**（Modular Monolith）启动，快速迭代；并为未来向**“微服务”\*\*（Microservices）架构的平滑过渡做好充分准备。
|
||||
|
||||
**核心原则**：
|
||||
|
||||
1. **平台与产品分离**：严格划分“底层通用模块”（如用户中心）和“上层业务模块”（如统计分析）。
|
||||
2. **一个架构，多种部署**：设计一套灵活的架构，通过“容器化”和“逻辑重组”，同时支持**①云端SaaS**、**②医院私有化部署**、**③混合部署**和**④医生个人单机版**。
|
||||
3. **技术异构（Polyglot）**：采用“用最合适的工具做最合适的事”的原则，允许Node.js、R、Python、Java等技术栈在微服务架构中共存。
|
||||
|
||||
**技术路径**：
|
||||
|
||||
* **云端/私有化**：采用 Docker(容器) \+ Kubernetes(编排) \+ API网关 的标准微服务部署方案。
|
||||
* **单机版**：采用 **Electron** 框架，**100%复用前端UI代码**，并通过 Node.js主进程 \+ 本地子进程(R/Python) 的方式重组后端逻辑，实现数据100%本地化。
|
||||
|
||||
## **2\. 业务需求与架构挑战**
|
||||
|
||||
### **2.1 产品功能矩阵 (7大模块)**
|
||||
|
||||
1. **智能统计分析 (SSA)**
|
||||
2. **统计分析工具 (ST)**
|
||||
3. **AI智能回答 (AIA)**
|
||||
4. **AI智能文献 (ASL)**
|
||||
5. **个人知识库 (PKB)**
|
||||
6. **数据清洗整理 (DC)**
|
||||
7. **个人中心 (UAM)**
|
||||
|
||||
### **2.2 复杂的商业与部署挑战**
|
||||
|
||||
1. **多版本 (SaaS)**：云端版分为专业版、高级版、旗舰版。
|
||||
2. **模块化售卖**：任何模块（如AI智能文献）都可能独立售卖。
|
||||
3. **私有化部署**：医院要求将数据敏感模块（如SSA、DC）部署在内网服务器。
|
||||
4. **混合部署**：医院本地使用SSA，同时又调用云端的ASL。
|
||||
5. **单机版部署**：医生需要在个人电脑(Windows/Mac)上离线运行SSA、DC、ASL等模块，确保数据（文献、病例）不出本地。
|
||||
|
||||
## **3\. 核心架构：API网关 \+ 微服务**
|
||||
|
||||
为满足以上所有需求，我们推荐一个解耦的、面向服务的架构。
|
||||
|
||||
* **客户端 (Clients)**：包括Web浏览器、PC单机版(Electron)、移动端。
|
||||
* **API网关 (API Gateway)**：所有流量的统一入口。负责：
|
||||
* **认证**：校验用户Token。
|
||||
* **路由**：将请求转发给正确的后端微服务（如 /api/stats \-\> SSA服务）。
|
||||
* **聚合**：(未来)合并多个服务的数据。
|
||||
* **后端服务 (Services)**：真正执行业务逻辑的单元。
|
||||
|
||||
## **4\. 服务模块划分 (平台 vs 产品)**
|
||||
|
||||
这是架构解耦的第一步。
|
||||
|
||||
### **4.1 底层通用模块 (平台层)**
|
||||
|
||||
这些是所有产品共用的“地基”，必须稳固、统一。
|
||||
|
||||
1. **用户与权限中心 (UAM)**
|
||||
* **功能**：管理用户、角色、租户（医院）、权限。
|
||||
* **价值**：实现SaaS多版本（专业版/高级版）的功能开关(Feature Flag)控制。
|
||||
2. **AI大模型网关 (LLM Gateway)**
|
||||
* **功能**：统一管理所有对大模型的调用（DeepSeek, Claude等）。
|
||||
* **价值**：根据SaaS版本、成本考量动态切换模型。是AI功能的核心中枢。
|
||||
3. **账户/个人中心**：管理用户配置、订单、帮助文档。
|
||||
4. **通知服务**：邮件、站内信。
|
||||
|
||||
### **4.2 独立业务模块 (产品层)**
|
||||
|
||||
这些是可插拔的“积木”，对应你们的7大功能，每个都应设计为**独立的服务**。
|
||||
|
||||
1. **智能统计 (SSA) 服务** (可包含统计工具ST)
|
||||
2. **AI问答 (AIA) 服务**
|
||||
3. **AI文献 (ASL) 服务**
|
||||
4. **知识库 (PKB) 服务**
|
||||
5. **数据清洗 (DC) 服务** (详见第6节)
|
||||
|
||||
## **5\. 推荐技术栈 (技术异构)**
|
||||
|
||||
我们允许“用最合适的工具做最合适的事”。
|
||||
|
||||
| 领域 | 推荐技术 | 理由 |
|
||||
| 前端 (UI) | React 或 Vue | 1\. 现代SPA框架。 2\. 可100%复用于Web版和Electron单机版。 |
|
||||
| API网关 & 粘合层 | Node.js | 1\. 高并发I/O性能。 2\. 作为“总指挥”粘合R/Python非常成熟。 3\. Electron单机版后端复用。 |
|
||||
| 统计分析 (SSA) | R 语言 | 统计分析的王者。通过 Plumber 包暴露为API，或通过子进程调用。 |
|
||||
| AI/数据清洗 (DC) | Python | 强大的Pandas、Scikit-learn、NLP生态。通过 FastAPI 暴露API，或通过子进程调用。 |
|
||||
| 数据库 | PostgreSQL \+ Vector DB | PostgreSQL处理结构化数据；向量数据库支持知识库(PKB)的RAG。 |
|
||||
| 部署方案 | Docker \+ Kubernetes | 现代云原生的唯一标准，实现弹性和多环境部署。 |
|
||||
| 单机版方案 | Electron | 唯一能原生支持Node.js后端、复用Web前端UI的跨平台方案。 |
|
||||
|
||||
## **6\. 模块深度解析：(DC) 数据清洗整理服务**
|
||||
|
||||
“数据清洗整理 (DC)” 模块是连接原始数据与有效分析的桥梁，技术挑战分为两部分：
|
||||
|
||||
1. **海量表格ETL**：处理百万行、多表格的结构化数据，执行高效的连接(Join)、重组(Pivot)和排序。
|
||||
2. **非结构化文本NER**：从病理、出入院小结等大段文本中，提取结构化字段（如TNM分期、肿瘤大小）。
|
||||
|
||||
针对不同的部署场景，我们采用两种实现方案：
|
||||
|
||||
### **6.1 方案一：服务器最优版 (Cloud-Optimal)**
|
||||
|
||||
此方案用于**云端SaaS版**和**私有化部署**，目标是追求极致的**效率、准确率和质量**（假设数据已脱敏）。
|
||||
|
||||
* **技术栈**：Python (FastAPI) \+ Polars \+ LLM API (Claude/GPT) \+ PostgreSQL
|
||||
* **工作流**：
|
||||
1. **API接收**：FastAPI (Python) 服务接收用户上传的多个Excel文件。
|
||||
2. **ETL (Polars)**：
|
||||
* **放弃Pandas**，采用Polars库。Polars基于Rust，天生**多线程并行**，内存效率极高。
|
||||
* 在服务器的大内存中（如64GB+），Polars能以**数秒或数十秒**的速度，在内存中完成200万行数据的多表JOIN、GROUP BY等操作，速度是Pandas的10-100倍。
|
||||
3. **NER (LLM API)**：
|
||||
* FastAPI 服务**并行调用** AI大模型网关（见4.1节）。
|
||||
* 使用 **Claude 3** 或 **GPT-4o** 等SOTA模型，配合JSON Mode，从病理报告中提取结构化信息。
|
||||
* **优势**：准确率极高，能理解复杂上下文，无需训练模型。
|
||||
4. **交付**：清洗完成的Polars DataFrame被存入PostgreSQL结果表，前端可在线浏览或导出。
|
||||
* **架构融合**：此 FastAPI \+ Polars 服务，**就是**白皮书架构中的“数据清洗 (DC) 微服务”，由“Node.js API网关”负责调用。
|
||||
|
||||
### **6.2 方案二：单机版 (Desktop-Offline)**
|
||||
|
||||
此方案用于**医生个人电脑**，目标是**100%数据隐私**和**离线可用性**，是对性能和准确率的**必要妥协**。
|
||||
|
||||
* **技术栈**：Electron (Node.js) \+ Python (Pandas) \+ SQLite \+ spaCy (本地NLP)
|
||||
* **工作流**：
|
||||
1. **总指挥 (Node.js)**：Electron的主进程作为总指挥，调度Python子进程。
|
||||
2. **ETL (SQLite)**：
|
||||
* **严禁**将200万行数据一次性读入内存（会导致用户电脑崩溃）。
|
||||
* Python脚本被调用，使用Pandas的chunksize参数，**分块**读取Excel，**逐行**写入一个本地**SQLite**数据库文件 (.db)。
|
||||
* **关键**：利用 **SQLite 数据库引擎**（而不是Pandas内存）来执行所有繁重的JOIN和GROUP BY。这是在低内存电脑上处理大数据的唯一稳定方案。
|
||||
3. **NER (本地 spaCy)**：
|
||||
* **严禁**将原始病例（PHI）发送到任何云端API（重大违规）。
|
||||
* Python脚本被调用，加载 **spaCy** 等**100%本地运行**的NLP模型，在用户电脑上提取实体。
|
||||
* **劣势**：spaCy准确率有限，无法处理复杂语义，效果远不如LLM。
|
||||
4. **交付**：所有结果被写回本地 SQLite 数据库。Electron前端通过分页从SQLite中读取数据展示，或导出为Excel。
|
||||
* **架构融合**：此方案**就是**白皮书【7.4 场景四：医生单机版】的具体实现。
|
||||
|
||||
## **7\. 关键路径：多部署模式实现**
|
||||
|
||||
同一套代码库，如何支持所有商业场景？
|
||||
|
||||
### **7.1 场景一：云端SaaS版 (标准微服务)**
|
||||
|
||||
* **架构**：所有服务（UAM, SSA, ASL...）和数据库都在云端，通过K8s管理。
|
||||
* **客户端**：用户通过浏览器访问。
|
||||
|
||||
### **7.2 场景二：医院本地化部署 (私有化)**
|
||||
|
||||
* **架构**：将数据敏感的服务（如 SSA服务、DC服务）及其数据库打包为Docker容器。
|
||||
* **部署**：使用K8s或更轻量的K3s，在医院内网服务器上“一键部署”。
|
||||
* **数据**：数据100%留在医院内网。
|
||||
|
||||
### **7.3 场景三：混合部署**
|
||||
|
||||
* **架构**：在场景二的基础上，前端应用被智能配置。
|
||||
* **流程**：
|
||||
* 用户访问 .../stats \-\> 前端调用**医院内网API** (http://192.168.x.x/api/stats)。
|
||||
* 用户访问 .../literature \-\> 前端调用**云端公网API** (https://api.yizhengxun.com/api/lit)。
|
||||
|
||||
### **7.4 场景四：医生单机版 (Electron)**
|
||||
|
||||
这是技术上最关键的“过渡”，它不是“打包”，而是\*\*“架构重组”\*\*。
|
||||
|
||||
云端版架构:
|
||||
\[浏览器UI\] \<-- (HTTP网络) \--\> \[云端Node.js API\] \<-- (HTTP) \--\> \[云端R/Python服务\]
|
||||
单机版架构:
|
||||
\[Electron UI (复用)\] \<-- (IPC本机通信) \--\> \[Electron主进程 (Node.js复用)\] \<-- (Child Process本机调用) \--\> \[本地R/Python脚本\]
|
||||
**实现路径：**
|
||||
|
||||
1. **新建Electron项目**。
|
||||
2. **移植前端 (UI复用)**：将云端版的React/Vue**编译后的静态文件** (dist目录) 完整复制到Electron中。
|
||||
3. **重组后端 (逻辑复用)**：
|
||||
* 云端版的 **Node.js API逻辑**，被移植到 **Electron的主进程(main.js)** 中。
|
||||
* 云端版的 **R 和 Python 脚本**，被作为**本地文件**打包进安装包。
|
||||
* main.js (Node.js) 通过 child\_process.spawn（子进程）来**本地调用**这些R/Python脚本。（具体实现见第6.2节）
|
||||
4. **数据交换**：Node.js、R、Python之间通过 stdin/stdout 和 **JSON** 字符串进行数据交换。
|
||||
5. **本地AI功能 (ASL模块)**：
|
||||
* Node.js (fs模块) 读取本地文献夹中的PDF。
|
||||
* Node.js (用 pdf-parse) 在**本地**提取摘要文本。
|
||||
* Node.js (用 axios) **只将“摘要文本”发送给云端LLM API** (如DeepSeek) 进行分析。（注意：这与DC模块的原始病例处理不同）。
|
||||
* **文献原文件 (.pdf) 100% 不离开用户电脑**。
|
||||
6. **本地存储**：使用 **SQLite**（通过 npm install sqlite3）在本地存储文献的元数据、分析结果等。
|
||||
|
||||
## **8\. 工程化与兼容性 (必读)**
|
||||
|
||||
### **8.1 单机版的“全家桶”挑战**
|
||||
|
||||
单机版的工程挑战不是开发，而是**打包**。
|
||||
|
||||
* 您的 .exe (Windows) 和 .dmg (Mac) 安装包必须是一个“全家桶”。
|
||||
* 您需要使用 electron-builder 等工具，将以下所有内容捆绑进一个安装包：
|
||||
1. 您的Electron应用 (Node.js \+ 前端UI)。
|
||||
2. 一个**嵌入式的 Python 运行时**及所有依赖 (pandas, spaCy等)。
|
||||
3. 一个**嵌入式的 R 运行时**及所有依赖 (jsonlite等)。
|
||||
* 这会使安装包体积变大（如500MB+），这对于专业软件是完全可以接受的。
|
||||
|
||||
### **8.2 必须放弃：Win 7 与 32位系统**
|
||||
|
||||
**这是一个商业和安全决策，不是技术选项。**
|
||||
|
||||
**必须声明：** 您的单机版最低系统要求是 **Windows 10 (64位)**。
|
||||
|
||||
**理由：**
|
||||
|
||||
1. **稳定性的“崩溃”问题**：32位系统有4GB内存上限，APP最多用2-3GB。您的**R语言统计分析**和**数据清洗**都是内存消耗大户，处理真实数据时**不是变卡，而是会直接崩溃闪退**，导致用户数据丢失。
|
||||
2. **安全性的“漏洞”问题**：微软已放弃Win 7。现代Electron, Node.js, Python, R生态已**全部停止支持32位和Win 7**。强行兼容意味着您必须使用5年前、充满已知安全漏洞的“古董”技术栈来处理敏感医疗数据，这是不可接受的。
|
||||
|
||||
## **9\. 分阶段实施路线图 (Roadmap)**
|
||||
|
||||
作为初创公司，我们必须务实。
|
||||
|
||||
### **9.1 阶段一：云端MVP (0-6个月) \- “模块化单体”**
|
||||
|
||||
* **目标**：快速上线云端SaaS版，验证市场。
|
||||
* **架构**：一个代码仓库 (Monorepo)，一个主后端服务（如Node.js）。
|
||||
* **关键纪律 (打地基)**：
|
||||
1. **代码隔离**：在代码目录上，严格按“平台模块”和“业务模块”划分。
|
||||
2. **数据隔离**：在同一个PostgreSQL数据库中，**严格使用不同的Schema** (如 uam\_schema, stats\_schema) 来隔离数据。这是未来拆分微服务的生命线。
|
||||
3. **全员Docker**：从第一天起，所有开发、测试、生产环境都必须基于 Docker 和 docker-compose。
|
||||
|
||||
### **9.2 阶段二：首次部署 (6-18个月) \- “首次拆分”**
|
||||
|
||||
* **触发点**：迎来第一个“私有化部署”客户，或“单机版”需求。
|
||||
* **架构**：
|
||||
1. **引入K8s**：在云端正式启用Kubernetes进行服务编排。
|
||||
2. **引入API网关**：在K8s集群前部署Nginx或Kong。
|
||||
3. **执行首次拆分**：将 SSA 和 DC 模块（连同它们的 stats\_schema）从主应用中**物理拆分**出来，打包成第一个独立的微服务（采用6.1节的“最优版”架构）。
|
||||
4. **开发单机版**：启动第一个Electron项目，按照【7.4】中的路径进行“重组”（采用6.2节的“单机版”架构）。
|
||||
|
||||
### **9.3 阶段三：全面微服务 (18个月+)**
|
||||
|
||||
* **目标**：支持灵活的业务组合和团队扩张。
|
||||
* **架构**：随着业务发展，将 ASL, PKB 等其他成熟模块也逐步拆分为独立的微服务，实现最终的“乐高积木式”的灵活架构。
|
||||
|
||||
## **10\. 结论**
|
||||
|
||||
本架构方案的核心是\*\*“演进”\*\*。它在初期（阶段一）通过“模块化单体”保证了初创公司的迭代速度，同时通过“代码/数据隔离”和“全面Docker化”的纪律，为未来（阶段二、三）向复杂微服务和多部署形态的平滑过渡打下了坚实的地基，避免了未来推倒重来的灾难性成本。
|
||||
Reference in New Issue
Block a user