dros/docs/需求/图像注释保存与重现功能需求.md

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

文档信息

• 文档版本: 1.0
• 创建日期: 2025-12-16
• 最后更新: 2025-12-16
• 相关实现文档: 保存注释功能实现文档

---

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 创建和保存注释流程

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 打开图像并重现注释流程

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. 参考资料

• 保存注释功能实现文档 - 技术实现细节
• Cornerstone Tools文档 - 图像工具库
• 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	初始版本，基于实现文档提炼

---

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