2026-05-03-22-36-18 增加DICOM阅览和单项下载

2026-05-03 22:46:46 +08:00
parent 525c2c1dda
commit bff7eead08
6 changed files with 509 additions and 6 deletions
--- a/工程分析/实现方案-2026-05-03-22-36-18.md
+++ b/工程分析/实现方案-2026-05-03-22-36-18.md
@@ -0,0 +1,78 @@
+# 实现方案
+
+开始时间：2026-05-03-22-36-18
+
+## 本次方案路径
+
+`工程分析/实现方案-2026-05-03-22-36-18.md`
+
+## 实现目标
+
+完成下载文案、四状态单项 DICOM 下载、影像库阅览入口和冠状/矢状 DICOM 显示模式切换。
+
+## 涉及文件
+
+- `WebSite/src/App.tsx`
+- `web_backend.py`
+- `工程分析/经验记录.md`
+
+## 执行步骤
+
+1. 前端文案调整：
+   - 将左侧工作站区域的“下载四状态ZIP”改为“下载结果”。
+   - 将影像库卡片中的“调阅”改为“变换”。
+2. 四状态单项下载：
+   - 在四状态结果卡片中，为原始序列、硬边界、高斯平滑、软过渡重建标题旁增加下载图标按钮。
+   - 点击按钮调用已有 `handlePackageDownload(t.key)`，复用后端现有 `prepare_deformation_zip(job_id, target)`。
+   - 按钮在形变任务未完成、对应状态 ZIP 正在打包时禁用，并显示简短状态。
+3. 后端新增影像库重建阅览接口：
+   - 新增 `/api/library/reformat-preview`，参数包含 `id`、`plane`、`index`、`window`。
+   - `plane` 支持 `coronal`、`sagittal`。
+   - `window` 支持 `default`、`bone`、`soft_tissue`、`brain`、`lung` 等固定窗宽窗位模式。
+   - 读取影像库 DICOM 序列为体数据，根据平面切片后用窗宽窗位转 PNG，缓存到 `web_library/_preview_cache/<item_id>/reformat/`。
+4. 前端新增影像库阅览弹层：
+   - 增加 `libraryViewerItem`、`viewerPlane`、`viewerWindow`、`viewerSliceIndex`、`viewerPreview` 等状态。
+   - 新增“阅览”按钮，打开弹层。
+   - 弹层提供冠状位/矢状位分段按钮、显示模式选择、切片滑杆、当前切片计数和预览图。
+   - 按切片、平面、显示模式请求 `/api/library/reformat-preview`。
+5. 保持现有“信息”“删除”“变换”行为不变，避免影响数据选择和工作站流程。
+6. 执行测试方案。
+7. 将关键问题和解决方案追加到 `工程分析/经验记录.md`。
+8. 提交并推送 Gitea，commit 信息使用 `2026-05-03-22-36-18 增加DICOM阅览和单项下载`。
+9. 重新部署到 `http://192.168.3.11:3005/`。
+
+## 预期实现细节
+
+- 单项下载 target 使用现有键：
+  - `original`
+  - `hard_boundary`
+  - `gaussian_smooth`
+  - `soft_transition`
+- 阅览接口返回：
+  - `imageUrl`
+  - `index`
+  - `count`
+  - `plane`
+  - `window`
+  - `patientId`
+- 窗宽窗位建议：
+  - default：沿用现有 `ct_window` 默认范围。
+  - bone：骨窗。
+  - soft_tissue：软组织窗。
+  - brain：脑窗。
+  - lung：肺窗。
+
+## 回滚思路
+
+如阅览接口或 UI 不符合预期，可回滚 `web_backend.py` 的新接口和 `WebSite/src/App.tsx` 中的阅览弹层及按钮；四状态单项下载和文案调整可单独保留或回退。
+
+## 风险控制
+
+- 不引入新的前端依赖。
+- 不修改真实 DICOM 形变与输出目录结构。
+- 后端预览只输出 PNG，不暴露额外 DICOM 文件写操作。
+- 缓存文件写入现有 `_preview_cache` 下，删除影像库条目时继续随缓存目录清理。
+
+## 人工审核状态
+
+待用户二次人工审核确认。未经确认不得修改业务代码。
--- a/工程分析/测试方案-2026-05-03-22-36-18.md
+++ b/工程分析/测试方案-2026-05-03-22-36-18.md
@@ -0,0 +1,87 @@
+# 测试方案
+
+开始时间：2026-05-03-22-36-18
+
+## 本次方案路径
+
+`工程分析/测试方案-2026-05-03-22-36-18.md`
+
+## 测试范围
+
+- 前端文案是否正确调整。
+- 四状态输出区每个状态是否都有独立下载按钮。
+- 单状态 DICOM ZIP 下载是否能触发、轮询并下载。
+- 数据影像库“变换”“阅览”“信息”“删除”按钮是否正常布局和工作。
+- 阅览弹层是否能显示冠状位、矢状位。
+- 阅览弹层是否能切换 DICOM/CT 显示模式和切片。
+- 前端类型检查、构建和 Python 语法检查是否通过。
+- 重新部署后目标地址是否可访问。
+
+## 测试命令
+
+Python 语法检查：
+
+```bash
+python -m py_compile web_backend.py head_extension_app.py
+```
+
+前端类型检查：
+
+```bash
+cd WebSite
+npm run lint
+```
+
+前端构建：
+
+```bash
+cd WebSite
+npm run build
+```
+
+后端阅览接口验证：
+
+```bash
+curl -s 'http://127.0.0.1:8787/api/library/reformat-preview?id=<影像库ID>&plane=coronal&index=0&window=bone'
+```
+
+```bash
+curl -s 'http://127.0.0.1:8787/api/library/reformat-preview?id=<影像库ID>&plane=sagittal&index=0&window=soft_tissue'
+```
+
+部署验证：
+
+```bash
+curl -I --max-time 5 http://192.168.3.11:3005/
+```
+
+## 手工验证点
+
+- 左侧按钮显示“下载结果”。
+- 四状态卡片中原始序列、硬边界、高斯平滑、软过渡重建旁边均有下载按钮。
+- 点击单状态下载按钮后，能下载对应 DICOM 序列 ZIP。
+- 数据影像库卡片中“调阅”改为“变换”。
+- 点击“变换”仍能进入影像变换工作站并选择该数据。
+- 点击“阅览”打开弹层，能查看冠状位和矢状位。
+- 切换显示模式后图像灰度/对比度发生变化。
+- 调节切片滑杆后图像更新。
+
+## 验收标准
+
+- 所有用户提出的文字和功能入口均出现。
+- 单状态 DICOM ZIP 下载可用。
+- 阅览弹层可用，冠状位/矢状位和显示模式切换可用。
+- `python -m py_compile web_backend.py head_extension_app.py` 通过。
+- `npm run lint` 通过。
+- `npm run build` 通过。
+- Gitea commit 和 push 完成。
+- 项目重新部署后 `http://192.168.3.11:3005/` 返回 `200 OK`。
+
+## 无法测试或残余风险
+
+- 若没有真实业务 DICOM 数据，使用仓库样例或当前影像库数据验证；不同扫描协议下的窗宽窗位显示效果可能需用户进一步微调。
+- 冠状/矢状重建为轻量预览，不替代专业 DICOM 阅片器的诊断级 MPR 功能。
+
+## 人工审核状态
+
+待用户二次人工审核确认。未经确认不得修改业务代码。
--- a/工程分析/经验记录.md
+++ b/工程分析/经验记录.md
@@ -37,3 +37,21 @@ C. 解决问题方案
 D. 后续如何避免问题

 预览标注层、参考线、箭头等非 CT 内容应优先在形变结果上单独叠加，不要和医学影像像素一起参与形变采样。若必须参与形变，应先确认该标注能承受硬边界或快速变化权重造成的撕裂效果。
+
+## 2026-05-03-22-36-18 增加 DICOM 阅览和单项下载
+
+A. 具体问题
+
+四状态结果区只有总 ZIP 下载入口，用户无法直接下载单个状态的 DICOM 序列；影像库卡片只能进入变换工作站或查看信息，缺少冠状位、矢状位阅览能力和 CT 显示模式切换。
+
+B. 产生问题原因
+
+后端已经具备单状态 DICOM ZIP 打包能力，但前端未暴露单状态按钮。影像库已有轴位缩略图接口，但该接口只读取单张 DICOM，未提供基于整套 DICOM 体数据的冠状/矢状重建预览。
+
+C. 解决问题方案
+
+前端在四状态卡片标题旁增加单状态下载按钮，复用现有 ZIP job 轮询和下载逻辑。后端新增影像库冠状/矢状重建预览接口，并按平面、切片和窗宽窗位缓存 PNG。前端新增影像库阅览弹层，支持冠状位、矢状位、切片滑杆和显示模式切换。
+
+D. 后续如何避免问题
+
+已有后端能力应先通过前端入口复用，不重复实现打包逻辑。DICOM 阅览类预览需要使用缓存，避免每次切换切片或窗宽窗位都重复生成相同图像；新增缓存应继续放在现有 `_preview_cache` 下，避免污染仓库。
--- a/工程分析/需求分析-2026-05-03-22-36-18.md
+++ b/工程分析/需求分析-2026-05-03-22-36-18.md
@@ -0,0 +1,55 @@
+# 需求分析
+
+开始时间：2026-05-03-22-36-18
+
+## 原始需求
+
+用户提出三项修改：
+
+1. 左侧“下载四状态ZIP”描述变为“下载结果”。
+2. “四状态 DICOM 输出结果”中，原始序列、硬边界、高斯平滑、软过渡重建旁边都增加下载按钮，可以下载对应的 DICOM 文件。
+3. 在“数据影像库”中，“调阅”描述变为“变换”；右侧增加“阅览”按钮，可以看 CT 冠状位、矢状位，同时可以调节 DCM 影像显示模式。
+
+## 目标
+
+- 调整已有按钮文案，使下载入口和变换入口更符合用户表达。
+- 在四状态结果区为每个状态提供独立 DICOM 下载入口。
+- 在影像库卡片中新增阅览入口，打开 DICOM 阅览弹层。
+- 阅览弹层支持冠状位、矢状位切换，并支持常见 DICOM/CT 显示窗宽窗位模式切换。
+
+## 影响范围
+
+- `WebSite/src/App.tsx`
+  - 修改按钮文字。
+  - 增加四状态单项下载按钮。
+  - 增加影像库阅览弹层状态、UI 和请求逻辑。
+- `web_backend.py`
+  - 复用或扩展现有 DICOM 读取、窗宽窗位、预览缓存能力。
+  - 增加影像库冠状位/矢状位阅览预览接口。
+- `工程分析/经验记录.md`
+  - 完成后追加关键问题和解决方案。
+
+## 当前定位
+
+- 四状态单状态 ZIP 下载能力后端已存在：`prepare_deformation_zip(job_id, target)` 支持 `original`、`hard_boundary`、`gaussian_smooth`、`soft_transition`。
+- 前端现有 `handlePackageDownload(target)` 已支持传入 target，并会轮询 ZIP job 完成后下载文件；当前仅全量 DICOM ZIP 按钮显式暴露。
+- 影像库目前只有轴位切片缩略预览接口 `/api/library/preview`，使用单张 DICOM 像素生成 PNG。
+- 影像库信息弹层已存在，可在其旁边新增独立阅览弹层，不必复用信息弹层。
+
+## 约束
+
+- 修改业务代码前必须先等待用户确认实现方案和测试方案。
+- 不改变 DICOM 形变算法。
+- 单状态下载应下载对应状态完整 DICOM 序列的 ZIP，而不是仅下载截图。
+- 阅览功能应尽量轻量，不引入大型医学影像前端库。
+
+## 风险点
+
+- 冠状位/矢状位预览需要读取整套 DICOM 体数据，可能比单张轴位预览更耗时；需要做缓存。
+- DICOM 切片排序、窗宽窗位和方向显示若处理粗糙，可能导致阅览体验不稳定。
+- 四状态卡片空间有限，新增下载按钮需要避免文字拥挤或遮挡。
+- 单状态 ZIP job 与全量 ZIP job 共用 `zipJobs` 状态，需避免 target key 冲突。
+
+## 待确认事项
+
+建议实现为：四状态卡片标题旁增加图标下载按钮；影像库卡片按钮区从“调阅/信息/删除”调整为“变换/阅览/信息/删除”，阅览弹层支持冠状位、矢状位，以及默认/骨窗/软组织/脑窗/肺窗等显示模式。待用户确认后执行。