# 图像注释保存与重现功能需求文档

## 文档信息

- **文档版本**: 1.0
- **创建日期**: 2025-12-16
- **最后更新**: 2025-12-16
- **相关实现文档**: [保存注释功能实现文档](../实现/保存注释功能实现文档.md)

---

## 1. 功能概述

### 1.1 功能简介

为医学影像工作站提供图像注释的持久化功能，允许用户在图像上添加各种测量和标注，并在后续打开同一图像时自动重现这些注释。

### 1.2 业务价值

- **提高工作效率**: 医生的测量和标注结果可以保存，避免重复操作
- **支持协作**: 多个医生可以查看和参考之前的注释
- **临床决策支持**: 历史测量数据为诊断提供参考依据
- **合规性**: 满足医疗影像归档和审计要求

### 1.3 适用场景

- 放射科医生进行影像测量和标注
- 多个医生协作诊断同一患者
- 复查患者历史影像
- 影像报告撰写和审核

---

## 2. 用户角色

| 角色 | 描述 | 主要需求 |
|------|------|----------|
| **放射科医生** | 进行影像诊断的主要用户 | 添加测量、标注，查看历史注释 |
| **技师** | 进行图像质量检查 | 添加质量标记，测量参数 |
| **科室主任** | 审核报告 | 查看和验证注释数据 |

---

## 3. 功能需求

### 3.1 注释创建

#### FR-01: 支持多种注释类型

**需求描述**: 系统应支持多种类型的图像注释工具

**注释类型**:
- ✅ **测量工具**
  - 长度测量（直线距离）
  - 角度测量
  - 面积测量
  - 圆形/椭圆测量
- ✅ **标注工具**
  - 文本标签（自由文本）
  - 预定义标记（L/R、时间戳等）
  - 箭头指示
- ✅ **专业测量工具**
  - 髋关节角度测量（HipNHAAngleMeasurementTool）
  - 其他临床专用测量工具

**优先级**: P0（核心功能）

#### FR-02: 实时注释反馈

**需求描述**: 用户创建注释时，应实时显示测量结果

**交互要求**:
- 绘制过程中实时显示测量值
- 完成后显示最终测量结果
- 测量值自动标注在注释旁边
- 支持测量单位显示（mm、度等）

**优先级**: P0

### 3.2 注释保存

#### FR-03: 自动保存机制

**需求描述**: 用户创建或修改注释后，系统应自动保存到后端

**功能要求**:
- ✅ 创建注释后立即触发保存
- ✅ 修改注释后延迟保存（防抖机制）
- ✅ 删除注释后同步删除
- ✅ 批量保存优化（避免频繁API调用）

**用户体验**:
- 保存过程不阻塞用户操作
- 显示保存状态指示（可选）
- 保存失败时提示用户

**优先级**: P0

#### FR-04: 离线支持（可选）

**需求描述**: 网络不可用时，注释应暂存本地，待网络恢复后同步

**功能要求**:
- 检测网络状态
- 本地缓存未保存的注释
- 网络恢复后自动同步
- 同步失败时提示用户

**优先级**: P2（增强功能）

### 3.3 注释加载与重现

#### FR-05: 自动加载注释

**需求描述**: 打开图像时，自动加载并显示该图像的所有注释

**功能要求**:
- ✅ 图像加载完成后立即获取注释数据
- ✅ 支持多个注释同时显示
- ✅ 注释位置和测量结果准确还原
- ✅ 注释样式和颜色保持一致

**性能要求**:
- 注释数量 < 50 时，加载时间 < 1秒
- 注释数量 > 50 时，分批加载或虚拟化渲染

**优先级**: P0

#### FR-06: 注释可见性控制

**需求描述**: 用户可以控制注释的显示和隐藏

**功能要求**:
- 全局显示/隐藏所有注释
- 按类型筛选显示（仅测量、仅标注等）
- 单个注释的显示/隐藏
- 注释列表管理界面

**优先级**: P1

### 3.4 注释管理

#### FR-07: 注释编辑

**需求描述**: 用户可以编辑已有的注释

**功能要求**:
- ✅ 选择注释进行编辑
- ✅ 拖拽调整注释位置和形状
- ✅ 修改文本内容
- ✅ 修改后自动保存

**优先级**: P0

#### FR-08: 注释删除

**需求描述**: 用户可以删除不需要的注释

**功能要求**:
- ✅ 单个注释删除
- ✅ 批量删除（可选）
- ✅ 删除确认提示（可配置）
- ✅ 删除后同步到后端

**优先级**: P0

#### FR-09: 注释导出（可选）

**需求描述**: 支持将注释数据导出为结构化格式

**功能要求**:
- 导出为JSON格式
- 导出为PDF报告（包含图像和注释）
- 导出为DICOM SR（结构化报告）

**优先级**: P3（未来增强）

---

## 4. 用户交互流程

### 4.1 创建和保存注释流程

```mermaid
sequenceDiagram
    participant 用户
    participant 工作站UI
    participant 后端API
    participant 数据库

    用户->>工作站UI: 1. 选择注释工具
    工作站UI->>工作站UI: 2. 激活工具
    用户->>工作站UI: 3. 在图像上绘制注释
    工作站UI->>工作站UI: 4. 实时显示测量结果
    用户->>工作站UI: 5. 完成绘制
    工作站UI->>后端API: 6. 自动保存注释数据
    后端API->>数据库: 7. 存储注释
    数据库-->>后端API: 8. 保存成功
    后端API-->>工作站UI: 9. 返回确认
    工作站UI-->>用户: 10. 显示保存状态（可选）
```

### 4.2 打开图像并重现注释流程

```mermaid
sequenceDiagram
    participant 用户
    participant 工作站UI
    participant 后端API
    participant 数据库

    用户->>工作站UI: 1. 打开图像
    工作站UI->>工作站UI: 2. 加载图像
    工作站UI->>后端API: 3. 请求注释数据
    后端API->>数据库: 4. 查询注释
    数据库-->>后端API: 5. 返回注释数据
    后端API-->>工作站UI: 6. 返回JSON数据
    工作站UI->>工作站UI: 7. 解析并重现注释
    工作站UI-->>用户: 8. 显示图像和注释
```

---

## 5. 数据要求

### 5.1 注释数据结构

每个注释应包含以下信息：

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| **id** | String | ✅ | 注释唯一标识符 |
| **toolName** | String | ✅ | 工具类型（LengthTool、AngleTool等） |
| **sopInstanceUid** | String | ✅ | 关联的图像标识 |
| **handles** | Object | ✅ | 几何数据（坐标点、文本框位置等） |
| **metadata** | Object | ✅ | 元数据（视图平面、参考帧等） |
| **cachedStats** | Object | ❌ | 测量结果（长度、角度、面积等） |
| **label** | String | ❌ | 显示标签 |
| **createdAt** | DateTime | ✅ | 创建时间 |
| **updatedAt** | DateTime | ✅ | 更新时间 |
| **userId** | String | ❌ | 创建用户 |

### 5.2 数据存储格式

- **格式**: JSON
- **编码**: UTF-8
- **大小限制**: 单个注释 < 100KB，单张图像所有注释 < 5MB

---

## 6. 性能要求

### 6.1 响应时间

| 操作 | 目标时间 | 最大时间 |
|------|----------|----------|
| 创建注释并保存 | < 500ms | < 1s |
| 加载注释（< 50个） | < 500ms | < 1s |
| 加载注释（> 50个） | < 2s | < 5s |
| 编辑注释 | 即时 | < 100ms |
| 删除注释 | < 300ms | < 1s |

### 6.2 并发支持

- 支持多用户同时查看同一图像
- 检测并发编辑冲突
- 提供冲突解决机制（后保存覆盖/提示用户选择）

---

## 7. 非功能性需求

### 7.1 可用性

- **易用性**: 注释操作应直观，无需培训即可使用
- **一致性**: 注释交互与其他图像操作保持一致
- **反馈**: 所有操作应有明确的视觉反馈

### 7.2 可靠性

- **数据完整性**: 确保注释数据不丢失
- **容错性**: 网络错误时自动重试（最多3次）
- **数据验证**: 保存前验证数据完整性和有效性

### 7.3 兼容性

- **浏览器**: Chrome 90+, Edge 90+, Firefox 88+
- **设备**: 桌面端优先，支持触摸屏操作
- **DICOM标准**: 兼容DICOM Structured Report（未来）

### 7.4 安全性

- **访问控制**: 仅授权用户可查看和编辑注释
- **数据加密**: 传输过程使用HTTPS加密
- **审计日志**: 记录注释的创建、修改、删除操作（可选）

---

## 8. 用例场景

### 8.1 用例1: 肺部结节测量

**场景**: 放射科医生在胸部CT图像上测量肺部结节大小

**前置条件**:
- 用户已登录系统
- 已打开患者的胸部CT图像

**操作步骤**:
1. 医生选择"长度测量"工具
2. 在结节上绘制测量线，获得直径12.5mm
3. 选择"文本标注"工具，添加备注"疑似恶性结节"
4. 系统自动保存测量和标注
5. 医生关闭图像，继续诊断其他患者
6. 第二天复查时，打开同一图像，自动显示昨天的测量和标注

**预期结果**:
- ✅ 测量值准确显示为12.5mm
- ✅ 文本标注正确显示
- ✅ 注释位置与原始位置一致

### 8.2 用例2: 髋关节角度评估

**场景**: 骨科医生测量髋关节角度以评估发育异常

**前置条件**:
- 用户已登录系统
- 已打开患者的髋关节X光图像

**操作步骤**:
1. 医生选择"髋关节角度测量"工具（HipNHAAngleMeasurementTool）
2. 按照工具要求标记关键解剖点
3. 工具自动计算并显示角度值：135°
4. 医生添加文本标注："角度正常范围"
5. 系统自动保存测量结果
6. 打印报告时，测量数据自动包含在报告中

**预期结果**:
- ✅ 角度值自动计算准确
- ✅ 关键点位置准确保存
- ✅ 可在报告中引用测量数据

### 8.3 用例3: 多医生协作诊断

**场景**: 主治医生的初步诊断需要科室主任审核

**前置条件**:
- 主治医生已完成初步诊断并添加注释
- 科室主任有权限查看该患者图像

**操作步骤**:
1. 主治医生完成测量和标注，保存后离开
2. 科室主任打开同一图像
3. 系统自动加载主治医生的所有注释
4. 主任查看测量值和标注
5. 主任添加新的注释表示审核意见
6. 两组注释同时保存在系统中

**预期结果**:
- ✅ 主治医生的注释完整显示
- ✅ 主任的新注释也被保存
- ✅ 可区分不同医生的注释（通过用户ID）

---

## 9. 验收标准

### 9.1 功能验收

- [ ] **FR-01**: 所有列出的注释类型均可正常使用
- [ ] **FR-02**: 测量工具实时显示测量值，单位正确
- [ ] **FR-03**: 创建/编辑注释后自动保存，保存成功率 > 99%
- [ ] **FR-05**: 打开图像后3秒内加载并显示所有注释
- [ ] **FR-07**: 注释可正常编辑，修改后准确保存
- [ ] **FR-08**: 注释可正常删除，删除后不再显示

### 9.2 性能验收

- [ ] 保存注释响应时间 < 1秒（90%的情况）
- [ ] 加载50个注释的时间 < 1秒
- [ ] 加载200个注释的时间 < 5秒
- [ ] 编辑注释无明显延迟（< 100ms）

### 9.3 兼容性验收

- [ ] Chrome浏览器测试通过
- [ ] Edge浏览器测试通过
- [ ] Firefox浏览器测试通过
- [ ] 支持4K分辨率显示

### 9.4 稳定性验收

- [ ] 网络断开后，注释数据不丢失（本地缓存）
- [ ] 网络恢复后，自动同步成功
- [ ] API错误时，有友好的错误提示
- [ ] 长时间使用无内存泄漏

---

## 10. 边界条件和约束

### 10.1 数据量限制

| 限制项 | 值 | 说明 |
|--------|-----|------|
| 单张图像最大注释数 | 500 | 超过后性能可能下降 |
| 单个注释最大大小 | 100KB | JSON序列化后 |
| 单张图像注释总大小 | 5MB | 超过后需优化 |
| 文本标注最大字符数 | 1000 | 防止滥用 |

### 10.2 异常情况处理

| 异常情况 | 处理策略 |
|----------|----------|
| **网络断开** | 本地缓存，网络恢复后重试 |
| **API超时** | 重试3次，失败后提示用户 |
| **数据格式错误** | 记录错误日志，跳过该注释，继续加载其他 |
| **并发编辑冲突** | 后保存覆盖（默认），或提示用户选择 |
| **存储空间不足** | 提示用户删除旧注释 |

### 10.3 权限控制

- 创建注释：需要图像查看权限
- 编辑注释：需要编辑权限（可配置为仅创建者可编辑）
- 删除注释：需要删除权限（可配置为仅创建者可删除）
- 查看注释：所有有图像查看权限的用户

---

## 11. 未来扩展

### 11.1 规划中的功能（P2-P3）

1. **注释模板**: 预定义常用测量组合
2. **智能测量**: AI辅助自动识别和测量
3. **DICOM SR支持**: 导出为DICOM结构化报告
4. **注释历史版本**: 查看和恢复历史版本
5. **注释协作**: 多用户实时协作标注
6. **注释统计**: 生成测量数据的统计报告
7. **语音标注**: 语音输入文本标注

### 11.2 技术优化方向

1. **性能优化**: 虚拟化渲染大量注释
2. **离线功能**: 完整的离线支持和冲突解决
3. **移动端适配**: 支持平板和手机操作
4. **3D注释**: 支持3D影像（CT/MRI）的体积注释

---

## 12. 参考资料

- [保存注释功能实现文档](../实现/保存注释功能实现文档.md) - 技术实现细节
- [Cornerstone Tools文档](https://www.cornerstonejs.org/) - 图像工具库
- DICOM PS3.11 - Media Storage and File Format for Media Interchange
- DICOM PS3.16 - Content Mapping Resource

---

## 附录

### A. 术语表

| 术语 | 英文 | 说明 |
|------|------|------|
| **注释** | Annotation | 在图像上添加的测量、标记或文本 |
| **测量工具** | Measurement Tool | 用于测量长度、角度、面积等的工具 |
| **标注** | Label/Mark | 文本或图形标记 |
| **重现** | Restore/Render | 从存储的数据恢复显示注释 |
| **序列化** | Serialization | 将注释对象转换为JSON格式 |
| **反序列化** | Deserialization | 从JSON格式恢复注释对象 |
| **SOP Instance UID** | SOP Instance UID | DICOM图像唯一标识符 |

### B. 变更历史

| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|----------|
| 1.0 | 2025-12-16 | Development Team | 初始版本，基于实现文档提炼 |

---

**文档状态**: ✅ 已完成  
**审核状态**: ⏳ 待审核  
**批准状态**: ⏳ 待批准