# **总体技术设计文档：医疗科研智能数据清洗平台**

| 文档类型 | System Architecture Document (SAD) |
| :---- | :---- |
| **对应 PRD** | **PRD\_总体\_医疗科研智能数据清洗平台.md** |
| **版本** | **V1.0** |
| **状态** | Final Draft |
| **核心目标** | 确立平台的统一技术标准，梳理通用模块与专用模块的技术边界，指导多团队并行开发。 |

## **1\. 总体系统架构图 (System Architecture)**

平台采用 **“微服务化单体 (Modular Monolith)”** 或 **“BFF \+ Worker”** 架构。前端统一入口，后端按功能拆分服务或模块。

graph TD  
    subgraph Client\_Layer \[前端交互层 (Browser)\]  
        Portal\[工作台 (Portal)\]  
        ToolA\_UI\[工具A: 超级合并器\]  
        ToolB\_UI\[工具B: 结构化机器人\]  
        ToolC\_UI\[工具C: 科研编辑器\]  
    end

    subgraph Gateway\_Layer \[网关与聚合层\]  
        Nginx\[Nginx / Load Balancer\]  
        BFF\[Node.js BFF (Fastify)\]  
    end

    subgraph Service\_Layer \[业务服务层\]  
        Auth\[认证服务\]  
        Asset\[资产管理服务\]  
          
        subgraph Workers \[异步计算集群\]  
            WorkerA\[合并引擎 (Stream)\]  
            WorkerB\[AI 引擎 (LangChain)\]  
        end  
    end

    subgraph Storage\_Layer \[存储层\]  
        PG\[(PostgreSQL \- 业务数据)\]  
        Redis\[(Redis \- 队列/缓存)\]  
        MinIO\[(MinIO/S3 \- 文件存储)\]  
    end

    Client\_Layer \--\> Nginx \--\> BFF  
    BFF \--\> Auth  
    BFF \--\> Asset  
    BFF \--任务分发--\> Redis  
    Redis \--消费--\> WorkerA & WorkerB  
    ToolC\_UI \--Local First--\> IndexedDB\[(Browser DB)\]  
    ToolC\_UI \--快照同步--\> BFF

## **2\. 通用技术基座 (The Common Foundation)**

这部分技术栈贯穿所有模块，是团队必须统一遵循的标准。

### **2.1 前端通用栈 (Frontend Core)**

| 组件 | 选型 | 说明 |
| :---- | :---- | :---- |
| **框架** | **React 19** | 利用最新的 Hooks 和并发特性。 |
| **构建工具** | **Vite 5.x** | 极速构建，支持 HMR。 |
| **语言** | **TypeScript 5.x** | 强制强类型，前后端共享类型定义 (shared-types)。 |
| **样式库** | **Tailwind CSS** | 统一 UI 风格，快速开发。 |
| **图标库** | **Lucide React** | 风格统一的轻量级 SVG 图标。 |
| **路由** | **React Router v6** | 管理 Portal 与各个 Tool 之间的路由嵌套。 |
| **数据请求** | **SWR** 或 **TanStack Query** | 处理 API 请求、缓存、以及任务状态的**轮询 (Polling)**。 |

### **2.2 后端通用栈 (Backend Core)**

| 组件 | 选型 | 说明 |
| :---- | :---- | :---- |
| **运行时** | **Node.js 22 (LTS)** | 保持最新 LTS 版本。 |
| **Web 框架** | **Fastify 5.x** | 高性能，低开销，Schema 校验友好。 |
| **ORM** | **Prisma 6** | 类型安全的数据库操作，支持 Schema Migration。 |
| **参数校验** | **Zod** | 运行时 Schema 校验，可生成 TypeScript 类型。 |
| **日志** | **Winston / Pino** | 结构化 JSON 日志。 |

### **2.3 基础设施栈 (Infrastructure)**

| 组件 | 选型 | 说明 |
| :---- | :---- | :---- |
| **数据库** | **PostgreSQL 15** | 存储用户、任务、资产元数据、结构化结果 (JSONB)。 |
| **缓存/队列** | **Redis 7** | 这里的 Redis 既做缓存，也是 **BullMQ** 的后端。 |
| **文件存储** | **MinIO / AWS S3** | 存储用户上传的 Excel、PDF 以及生成的中间文件。 |

## **3\. 模块专用技术栈 (Module-Specific Stack)**

针对不同场景的特殊需求，各工具引入了特定的技术组件。

### **3.1 工具 A：超级合并器 (IO 密集型)**

*核心挑战：大文件流式处理、日期解析、哈希匹配。*

| 领域 | 专用组件 | 选型理由 |
| :---- | :---- | :---- |
| **后端 (Excel)** | **ExcelJS** | 相比 SheetJS，它对 **Stream (流)** 的支持更好，能处理超过内存限制的大文件。 |
| **后端 (Date)** | **Day.js \+ CustomParseFormat** | 解决 Excel 杂乱的日期格式 (44927, 2023/1/1)，轻量且强大。 |
| **异步队列** | **BullMQ** | 处理耗时合并任务，支持进度汇报。 |
| **前端组件** | **Ant Design Steps / Upload** | 快速实现向导式 UI。 |

### **3.2 工具 B：病历结构化机器人 (API/计算密集型)**

*核心挑战：LLM 编排、双模型并发、文本比对。*

| 领域 | 专用组件 | 选型理由 |
| :---- | :---- | :---- |
| **后端 (AI)** | **LangChain.js** | 统一 DeepSeek 和 Qwen 的调用接口，管理 Prompt Template。 |
| **后端 (Diff)** | **diff-match-patch** (Google) | 计算两个模型输出的文本差异，或者原文的高亮位置。 |
| **后端 (比对)** | **Lodash / Dice Coefficient** | 用于 JSON 对象的深层比对和字符串相似度计算。 |
| **前端 (Grid)** | **TanStack Table** (Headless) | 因为需要高度定制“冲突单元格”的 UI (左右并排按钮)，Headless 库比 AntD Table 更灵活。 |

### **3.3 工具 C：科研数据编辑器 (交互密集型)**

*核心挑战：前端高性能渲染、本地计算、撤销重做。*

| 领域 | 专用组件 | 选型理由 |
| :---- | :---- | :---- |
| **前端 (Grid)** | **AG Grid Community** | **核心组件**。唯一能免费支持虚拟滚动、列拖拽、Excel 级交互的库。 |
| **前端 (Storage)** | **Dexie.js (IndexedDB)** | **Local-First 架构核心**。在浏览器端存储 5-10 万行数据，避免频繁网络请求。 |
| **前端 (State)** | **Zustand \+ Immer** | 利用 Immer 的 Patches 功能实现 **Undo/Redo (撤销重做)** 栈。 |
| **前端 (Calc)** | **Math.js** | 解决 JS 浮点数精度问题，解析用户输入的医学公式 (ln, pow)。 |
| **前端 (Chart)** | **Ant Design Charts (G2)** | 在智能侧边栏中绘制直方图和频次图。 |

## **4\. 数据交互标准 (Data Standards)**

为了打通 A \-\> B \-\> C 的流转，必须定义统一的数据交换格式。

### **4.1 内部流转格式**

* **文件物理格式：** 统一使用 **CSV (UTF-8 with BOM)** 或 **JSON Lines (.jsonl)**。  
  * *理由：* Stream 处理最快，且不依赖 Excel 复杂的 XML 结构。  
* **日期标准：** 所有工具产出的日期，必须归一化为 YYYY-MM-DD 字符串。  
* **空值标准：** 统一为 null (JSON) 或 "" (CSV)，严禁使用 "NA", "-"。

### **4.2 API 响应结构 (Standard Response)**

interface ApiResponse\<T\> {  
  code: number;      // 0: 成功, \>0: 错误码  
  data: T;           // 业务数据  
  message?: string;  // 错误提示  
  meta?: {           // 分页或元数据  
    total?: number;  
    traceId: string;  
  }  
}

## **5\. 开发环境与部署 (DevOps)**

* **包管理：** **pnpm** (推荐，节省磁盘空间，安装快)。  
* **Monorepo (可选)：** 建议使用 Turborepo 或 Nx 管理 frontend, backend-api, worker-merger, worker-ai 等包，共享类型定义。  
* **容器化：**  
  * **API Service:** 无状态，可水平扩展。  
  * **Worker Service:** 单独部署，根据 CPU/内存负载进行扩容（特别是 Worker A 处理大文件时内存消耗大）。