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

| 文档类型 | 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 处理大文件时内存消耗大）�