Head_CT_Morph/工程分析/实现方案-2026-05-03-23-22-10.md

实现方案

开始时间：2026-05-03-23-22-10

本次方案路径

工程分析/实现方案-2026-05-03-23-22-10.md

实现目标

修复 DICOM 阅览切片/显示模式切换导致后端连接重置的问题，并降低 ZIP 下载误触发和 HTTP 文件加载警告。

涉及文件

• web_backend.py
• WebSite/src/App.tsx
• 工程分析/经验记录.md

执行步骤

1. 后端增加 DICOM 体数据缓存：
   • 增加 DICOM_VOLUME_CACHE 和锁。
   • 基于 DICOM 目录路径、文件数量、最新修改时间生成签名。
   • /api/library/reformat-preview 复用缓存体数据，避免每次切片/窗位变化都重新读取完整 DICOM。
   • 控制缓存规模，避免多个大体数据长期驻留。
2. 后端下载容错：
   • send_file 捕获 BrokenPipeError、ConnectionResetError、ConnectionAbortedError，避免客户端中断下载时污染日志或影响服务。
3. 前端 DICOM 阅览请求防抖：
   • 增加 debouncedViewerSliceIndex。
   • 切片滑杆变化后延迟短时间再请求后端，减少快速拖动时的请求数量。
   • 显示模式或平面切换仍可即时重置到中间切片，但实际请求走防抖后的切片索引。
4. 前端 ZIP 下载防重复：
   • 增加已下载 ZIP job id 记录，确保同一个 ZIP job 自动下载只触发一次。
5. 前端 ZIP 下载方式调整：
   • 对后端文件路径优先使用 fetch 获取 blob，再使用本地 blob: URL 触发下载。
   • 如 blob 下载失败，回退到原有 /api/file URL 方式，并提示用户。
6. 执行测试方案。
7. 更新 工程分析/经验记录.md。
8. 提交并推送 Gitea，commit 信息使用 2026-05-03-23-22-10 修复阅览切换和下载触发。
9. 重新部署到 http://192.168.3.11:3005/。

回滚思路

若缓存或 blob 下载出现问题，可回滚本次 web_backend.py 和 WebSite/src/App.tsx 修改，恢复直接读取体数据和直接 URL 下载方式。

风险控制

• 体数据缓存只影响阅览预览接口，不影响真实形变输出。
• 缓存使用目录签名，影像库数据变化后会重新读取。
• 删除影像库时同步清除 DICOM 文件缓存和体数据缓存。
• 前端保留下载回退路径，避免 blob 下载失败后无法下载。

人工审核状态

用户已明确本次不需要人工二次确认，直接执行。