# **壹证循科技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) 的方式重组后端逻辑，实现数�?00%本地化�?
## **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 独立业务模块 (产品�?**

这些是可插拔的“积木”，对应你们�?大功能，每个都应设计�?*独立的服�?*�?
1. **智能统计 (SSA) 服务** (可包含统计工具ST)  
2. **AI问答 (AIA) 服务**  
3. **AI文献 (ASL) 服务**  
4. **知识�?(PKB) 服务**  
5. **数据清洗 (DC) 服务** (详见�?�?

## **5\. 推荐技术栈 (技术异�?**

我们允许“用最合适的工具做最合适的事”�?
| 领域 | 推荐技�?| 理由 |  
| 前端 (UI) | React �?Vue | 1\. 现代SPA框架�?2\. �?00%复用于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，天�?*多线程并�?*，内存效率极高�? 
     * 在服务器的大内存中（�?4GB+），Polars能以**数秒或数十秒**的速度，在内存中完�?00万行数据的多表JOIN、GROUP BY等操作，速度是Pandas�?0-100倍�? 
  3. **NER (LLM API)**�? 
     * FastAPI 服务**并行调用** AI大模型网关（�?.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)**�? 
     * **严禁**�?00万行数据一次性读入内存（会导致用户电脑崩溃）�? 
     * 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�? 
* **架构融合**：此方案**就是**白皮书�?.4 场景四：医生单机版】的具体实现�?
## **7\. 关键路径：多部署模式实现**

同一套代码库，如何支持所有商业场景？

### **7.1 场景一：云端SaaS�?(标准微服�?**

* **架构**：所有服务（UAM, SSA, ASL...）和数据库都在云端，通过K8s管理�? 
* **客户�?*：用户通过浏览器访问�?
### **7.2 场景二：医院本地化部�?(私有�?**

* **架构**：将数据敏感的服务（�?SSA服务、DC服务）及其数据库打包为Docker容器�? 
* **部署**：使用K8s或更轻量的K3s，在医院内网服务器上“一键部署”�? 
* **数据**：数�?00%留在医院内网�?
### **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. **稳定性的“崩溃”问�?*�?2位系统有4GB内存上限，APP最多用2-3GB。您�?*R语言统计分析**�?*数据清洗**都是内存消耗大户，处理真实数据�?*不是变卡，而是会直接崩溃闪退**，导致用户数据丢失�? 
2. **安全性的“漏洞”问�?*：微软已放弃Win 7。现代Electron, Node.js, Python, R生态已**全部停止支持32位和Win 7**。强行兼容意味着您必须使�?年前、充满已知安全漏洞的“古董”技术栈来处理敏感医疗数据，这是不可接受的�?
## **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项目，按照�?.4】中的路径进行“重组”（采用6.2节的“单机版”架构）�?
### **9.3 阶段三：全面微服�?(18个月+)**

* **目标**：支持灵活的业务组合和团队扩张�? 
* **架构**：随着业务发展，将 ASL, PKB 等其他成熟模块也逐步拆分为独立的微服务，实现最终的“乐高积木式”的灵活架构�?
## **10\. 结论**

本架构方案的核心是\*\*“演进”\*\*。它在初期（阶段一）通过“模块化单体”保证了初创公司的迭代速度，同时通过“代�?数据隔离”和“全面Docker化”的纪律，为未来（阶段二、三）向复杂微服务和多部署形态的平滑过渡打下了坚实的地基，避免了未来推倒重来的灾难性成本�