AIclinicalresearch/docs/03-业务模块/DC-数据清洗整理/02-技术设计/总体技术设计文档：医疗科研智能数据清洗平台.md

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

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