# Medical Data Marker

**Repository Path**: OceanEyeFF/medical_data_marker

## Basic Information

- **Project Name**: Medical Data Marker
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-27
- **Last Updated**: 2026-02-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 医疗数据标记工具 🏥

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Electron](https://img.shields.io/badge/Electron-39.2.4-blue.svg)](https://electronjs.org/)
[![React](https://img.shields.io/badge/React-18.2.0-blue.svg)](https://reactjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3.3-blue.svg)](https://www.typescriptlang.org/)

> 基于 **Electron + React + TypeScript + DICOM** 的专业医学影像病例级标注系统

## 📋 项目简介

医疗数据标记工具是一个专为医学影像设计的桌面应用程序，采用现代化技术栈开发，专注于**病例级**医学影像标注工作流。与传统的图像级标注不同，本系统以完整病例为基本单位，提供直观的用户界面和强大的DICOM文件处理能力。

### 🎯 核心特性

#### 🏥 病例级标注架构
- **病例组织**: 三级目录结构中，第三级文件夹代表一个完整病例
- **自然语言描述**: 征象、诊断等核心字段支持自然语言描述
- **高价值图像选择**: 从病例图像中选择具有诊断价值的图像
- **额外信息标签**: 灵活的标签系统补充病例信息

#### 📁 DICOM文件支持
- **多序列支持**: 自动识别和排序DICOM序列
- **元数据提取**: 提取完整的DICOM标签信息
- **图像位置计算**: 自动计算图像空间位置和方向
- **多格式兼容**: 支持常见医学影像格式

#### 💾 数据管理
- **分布式存储**: 每病例独立annotation.json文件
- **原子写入**: 确保数据完整性的原子操作
- **直接保存**: 简化工作流，直接覆盖保存
- **配置预设**: 支持不同医学类型的标注模板

#### 🔧 灵活扩展
- **JSON Schema扩展**: 通过JSON Schema动态扩展标注字段
- **配置预设系统**: 预置CT、MRI、X-Ray等医学类型模板
- **JSON编辑器**: 高级用户可编辑扩展字段
- **模块化设计**: 清晰的分层架构和模块边界

#### 🗑️ 病例删除功能 `NEW in v1.1.0`
- **安全删除**: 右键菜单触发，二次确认机制，系统目录保护
- **实时进度**: 三阶段进度条（扫描→删除→清理），实时速度和预计时间显示
- **智能终止**: 删除时自动终止DCM数据读取，避免资源浪费
- **错误处理**: 失败文件列表展示，进度回调失败警告

## 🏗️ 系统架构

### 整体架构

```
┌─────────────────────────────────────────────────────────┐
│                    用户界面层 (React)                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │ 病例浏览器  │  │ DICOM查看器 │  │ 标注表单   │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                 安全通信层 (Preload)                       │
│                contextBridge API                        │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                  Electron主进程                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │ 窗口管理    │  │ IPC通信     │  │ 文件系统    │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
│  ┌─────────────┐  ┌─────────────┐                       │
│  │ DICOM服务   │  │ 标注管理    │                       │
│  └─────────────┘  └─────────────┘                       │
└─────────────────────────────────────────────────────────┘
```

### 核心技术栈

| 类别 | 技术 | 版本 | 用途 |
|------|------|------|------|
| 桌面应用 | Electron | ^39.2.4 | 跨平台桌面应用框架 |
| 前端框架 | React | ^18.2.0 | UI渲染 |
| 语言 | TypeScript | ^5.3.3 | 类型安全 |
| 构建工具 | Vite | ^5.0.11 | 快速构建 |
| 样式 | TailwindCSS | ^3.4.1 | 原子化CSS |
| 状态管理 | Zustand | ^4.5.0 | 轻量状态管理 |
| 测试 | Vitest | ^1.1.3 | 单元测试 |
| DICOM | Cornerstone3D | ^4.12.6 | 医学影像处理 |
| DICOM解析 | dcmjs | ^0.45.0 | DICOM文件解析 |
| JSON编辑器 | @json-editor/json-editor | ^2.15.2 | 扩展字段编辑 |

## 🚀 快速开始

### 环境要求

- Node.js >= 18.0.0
- npm >= 9.0.0
- 操作系统: Windows 10+, macOS 10.15+, Ubuntu 20.04+

### 安装步骤

1. **克隆项目**
```bash
git clone https://github.com/your-org/medical-data-marker.git
cd medical-data-marker
```

2. **安装依赖**
```bash
npm install
```

3. **启动开发环境**
```bash
npm run dev
```

4. **构建生产版本**
```bash
npm run build
```

5. **打包应用**
```bash
npm run electron:build
```

### 可用脚本

```bash
# 开发模式 (热重载)
npm run dev

# 类型检查
npm run type-check

# 代码规范检查
npm run lint

# 运行测试
npm test
npm run test:ui  # 测试UI

# 构建
npm run build
npm run electron:build  # 打包Electron应用
```

## 📁 项目结构

```
medical_data_marker/
├── 📄 README.md                    # 项目说明文档
├── 📄 package.json                 # 项目配置和依赖
├── 📄 vite.config.ts              # Vite构建配置
├── 📄 vitest.config.ts            # 测试配置
│
├── 📁 src/                        # 源代码目录
│   ├── 📁 main/                   # [模块] Electron主进程
│   │   ├── 📄 index.ts           # 主进程入口
│   │   ├── 📁 ipc/               # IPC处理器
│   │   │   ├── 📄 index.ts       # IPC注册中心
│   │   │   ├── 📄 filesystemHandlers.ts
│   │   │   └── 📄 dicomHandlers.ts
│   │   └── 📁 services/          # 主进程服务
│   │       ├── 📄 dicomService.ts
│   │       └── 📄 fileSystemService.ts
│   │
│   ├── 📁 renderer/               # [模块] React渲染进程
│   │   ├── 📄 main.tsx           # React入口
│   │   ├── 📄 App.tsx            # 根组件
│   │   ├── 📁 components/        # UI组件
│   │   │   ├── 📄 MainLayout.tsx # 主布局
│   │   │   ├── 📄 CaseNavigator.tsx      # 病例导航器
│   │   │   ├── 📄 CaseAnnotationForm.tsx # 标注表单
│   │   │   ├── 📄 DicomViewer.tsx        # DICOM查看器
│   │   │   ├── 📄 ImageNavigator.tsx     # 图像导航器
│   │   │   └── 📄 JsonEditorWrapper.tsx  # JSON编辑器包装器
│   │   ├── 📁 stores/            # 状态管理
│   │   │   ├── 📄 appStore.ts    # 应用状态
│   │   │   ├── 📄 dicomStore.ts  # DICOM状态
│   │   │   └── 📄 caseStore.ts   # 病例状态
│   │   └── 📁 utils/             # 渲染进程工具
│   │
│   ├── 📁 preload/                # [模块] 预加载脚本
│   │   └── 📄 index.ts           # 安全通信桥
│   │
│   └── 📁 types/                  # [模块] 类型定义
│       ├── 📄 app.d.ts           # 应用类型
│       ├── 📄 electron.d.ts      # Electron类型
│       └── 📄 store.d.ts         # 状态类型
│
└── 📁 tests/                      # 测试目录
    └── 📁 unit/                   # 单元测试
```

## 💡 使用指南

### 病例级标注工作流

1. **选择病例目录**
   - 系统自动扫描第三级文件夹作为病例
   - 显示病例基本信息（名称、图像数量等）

2. **浏览病例图像**
   - 在DICOM查看器中浏览所有图像
   - 使用图像导航器快速切换

3. **填写标注信息**
   - **征象描述**: 自然语言描述影像征象
   - **诊断结论**: 自然语言描述诊断意见
   - **额外信息**: 添加标签补充病例信息
   - **高价值图像**: 选择具有诊断价值的图像

4. **保存标注**
   - 系统自动生成annotation.json文件
   - 保存到对应病例目录
   - 支持直接覆盖保存

### 数据结构

#### 病例标注结构

```typescript
interface PatientCaseAnnotation {
  id: string;                      // 病例ID (第三级文件夹名)
  path: string;                    // 病例相对路径
  findings: string;                // 征象描述 (自然语言)
  diagnosis: string;               // 诊断结论 (自然语言)
  extra_info: string[];            // 额外信息标签
  high_value_images: string[];     // 高价值图像列表
  content: Record<string, any>;    // JSON Schema扩展字段
  createdAt: Date;                 // 创建时间
  updatedAt: Date;                 // 更新时间
  annotatedBy: string;             // 标注者
}
```

#### 目录结构示例

```
root_directory/
├── CT/
│   └── 胸部CT/
│       ├── Patient_001/          # 病例1 (第三级文件夹)
│       │   ├── 1.dcm
│       │   ├── 2.dcm
│       │   ├── 3.dcm
│       │   └── annotation.json   # 病例标注文件
│       └── Patient_002/          # 病例2
│           ├── 1.dcm
│           ├── 2.dcm
│           └── annotation.json
└── MRI/
    └── 头部MRI/
        ├── Patient_003/
        │   ├── 1.dcm
        │   └── annotation.json
        └── Patient_004/
            ├── 1.dcm
            └── annotation.json
```

## 🧪 测试

### 测试覆盖

- ✅ 组件单元测试
- ✅ 状态管理测试
- ✅ IPC通信测试
- ✅ DICOM处理测试
- ✅ 病例工作流测试

### 运行测试

```bash
# 运行所有测试
npm test

# 运行测试UI
npm run test:ui

# 运行特定测试文件
npm test -- CaseAnnotationForm.test.tsx

# 生成覆盖率报告
npm test -- --coverage
```

## 🔌 IPC API

### 基础功能
- `ping(): Promise<string>` - 连接测试
- `getVersion(): Promise<string>` - 获取版本

### 病例操作
- `case:scan(rootPath)`: 扫描病例目录
- `case:getAnnotation(casePath)`: 获取病例标注
- `case:saveAnnotation(casePath, annotation)`: 保存病例标注

### 文件系统
- `filesystem:scanDirectory(rootPath)`: 扫描目录
- `filesystem:getDicomFiles(dirPath)`: 获取DICOM文件
- `filesystem:getCaseInfo(casePath)`: 获取病例信息 `NEW in v1.1.0`
- `filesystem:deleteDirectory(dirPath, onProgress)`: 删除目录 `NEW in v1.1.0`
- `filesystem:delete-progress`: 删除进度事件（IPC事件通道）`NEW in v1.1.0`

### DICOM处理
- `dicom:readDicomFile(filePath)`: 读取DICOM文件
- `dicom:sortDicomFiles(files)`: 排序DICOM文件
- `dicom:readAndSort(filePaths)`: 读取并排序

## 🔒 安全特性

- ✅ **进程隔离**: 主进程和渲染进程完全隔离
- ✅ **上下文隔离**: 启用contextIsolation
- ✅ **Node.js禁用**: 渲染进程禁用nodeIntegration
- ✅ **网络安全**: 启用webSecurity
- ✅ **IPC安全**: 统一的IPC错误处理
- ✅ **输入验证**: 所有用户输入验证

## 📊 开发进度

| 阶段 | 状态 | 进度 | 说明 |
|------|------|------|------|
| ✅ 阶段1: 基础架构 | 已完成 | 100% | 项目初始化、Electron配置、React集成 |
| ✅ 阶段2: 核心功能 | 已完成 | 100% | 文件系统、DICOM处理、窗口管理 |
| 🚧 阶段3: 标注功能 | 进行中 | 85% | 病例级标注、表单系统、数据管理 |
| ⏳ 阶段4: 高级功能 | 待开始 | 0% | 搜索过滤、导出导入、统计面板 |
| ⏳ 阶段5: 测试优化 | 待开始 | 0% | 性能优化、集成测试、文档完善 |

### 阶段3完成情况
- [x] 基础架构与JSON编辑器集成
- [x] 文本标注表单系统
- [x] 标注数据管理系统
- [x] 配置预设系统
- [x] 高级功能设计
- [x] 测试与优化计划
- [ ] 用户文档完善

## 🛠️ 开发指南

### 代码规范

- **TypeScript严格模式**: 启用所有严格检查
- **ESLint + Prettier**: 统一的代码风格
- **组件函数式编程**: 使用React Hooks
- **状态管理**: Zustand轻量状态管理
- **错误处理**: 统一的错误处理机制

### 提交规范

```bash
# 功能开发
git commit -m "feat: 添加病例搜索功能"

# 问题修复
git commit -m "fix: 修复DICOM文件读取错误"

# 文档更新
git commit -m "docs: 更新API文档"

# 测试添加
git commit -m "test: 添加病例表单单元测试"
```

## 📚 相关文档

- [架构设计文档](docs/Designs/SoftwareArchitectureDesign.md)
- [工程实施计划](docs/Designs/EngineeringImplementationPlan.md)
- [工作流设计](docs/Designs/WorkFlowDesign.md)
- [主进程模块文档](src/main/CLAUDE.md)
- [渲染进程模块文档](src/renderer/CLAUDE.md)
- [预加载模块文档](src/preload/CLAUDE.md)

## 🤝 贡献指南

我们欢迎所有形式的贡献！

### 贡献流程

1. **Fork** 项目
2. **创建特性分支** (`git checkout -b feature/AmazingFeature`)
3. **提交更改** (`git commit -m 'Add some AmazingFeature'`)
4. **推送分支** (`git push origin feature/AmazingFeature`)
5. **开启 Pull Request**

### 贡献类型

- 🐛 Bug修复
- ✨ 新功能开发
- 📚 文档完善
- 🎨 UI/UX改进
- 🧪 测试用例
- ⚡ 性能优化

## 📞 支持与反馈

- 📧 邮箱: dev@medical-marker.com
- 🐛 问题反馈: [GitHub Issues](https://github.com/your-org/medical-data-marker/issues)
- 💬 讨论: [GitHub Discussions](https://github.com/your-org/medical-data-marker/discussions)

## 📄 许可证

本项目采用 [MIT License](LICENSE) 开源协议。

## 🙏 致谢

感谢以下开源项目：

- [Electron](https://electronjs.org/) - 跨平台桌面应用框架
- [React](https://reactjs.org/) - 用户界面库
- [Cornerstone3D](https://www.cornerstonejs.org/) - 医学影像处理
- [dcmjs](https://github.com/dcmjs-org/dcmjs) - DICOM文件处理
- [Zustand](https://github.com/pmndrs/zustand) - 状态管理
- [TailwindCSS](https://tailwindcss.com/) - CSS框架

## 📈 路线图

### v1.1.0 (已发布 - 2025-12-19)
- [x] ✨ 病例文件夹删除功能（右键菜单、确认对话框、实时进度）
- [x] ⚡ 删除进度实时显示（速度、预计时间）
- [x] ⚡ 删除时终止DCM读取（避免资源浪费）
- [x] 🐛 静态代码问题修复（6项）
- [x] 🔒 安全性增强（系统目录保护、路径遍历防护）

### v1.2.0 (计划中)
- [ ] 病例搜索和过滤功能
- [ ] 批量操作支持
- [ ] 导出导入功能增强
- [ ] 统计面板
- [ ] 标注质量检查

### v2.0.0 (规划中)
- [ ] 云端同步
- [ ] 高级分析工具
- [ ] 机器学习集成

---

**开发团队**: 医疗数据标记工具开发团队
**联系方式**: dev@medical-marker.com
**最后更新**: 2025-12-19
**版本**: v1.1.0