# 实现方案

开始时间：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 下载失败后无法下载。

## 人工审核状态

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