HaHafeng
d4d33528c7
Summary: - Implement DC module Portal page with 3 tool cards - Create ToolCard component with decorative background and hover animations - Implement TaskList component with table layout and progress bars - Implement AssetLibrary component with tab switching and file cards - Complete database verification (4 tables confirmed) - Complete backend API verification (6 endpoints ready) - Optimize UI to match prototype design (V2.html) Frontend Components (~715 lines): - components/ToolCard.tsx - Tool cards with animations - components/TaskList.tsx - Recent tasks table view - components/AssetLibrary.tsx - Data asset library with tabs - hooks/useRecentTasks.ts - Task state management - hooks/useAssets.ts - Asset state management - pages/Portal.tsx - Main portal page - types/portal.ts - TypeScript type definitions Backend Verification: - Backend API: 1495 lines code verified - Database: dc_schema with 4 tables verified - API endpoints: 6 endpoints tested (templates API works) Documentation: - Database verification report - Backend API test report - Phase 1 completion summary - UI optimization report - Development task checklist - Development plan for Tool B Status: Phase 1 completed (100%), ready for browser testing Next: Phase 2 - Tool B Step 1 and 2 development
152 lines
7.1 KiB
Markdown
152 lines
7.1 KiB
Markdown
# **总体技术设计文档：医疗科研智能数据清洗平台**
|
||
|
||
| 文档类型 | 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 处理大文件时内存消耗大）。 |