# 经验记录 本文件作为项目统一知识库。每次最终执行项目修改前必须阅读；每次执行完成后，如遇到关键问题或形成可复用经验，必须按以下四段式追加记录。 ## 2026-05-03-18-27-21 建立项目修改工作流 A. 具体问题 项目此前缺少统一的修改前分析、人工审核、测试确认、经验沉淀、Gitea 备份和重新部署流程，后续需求容易直接进入代码修改，导致风险不可追踪。 B. 产生问题原因 仓库中已有 README 和运行说明，但没有面向后续代码编纂工作的强制流程文件，也没有统一的 `工程分析/` 知识库目录。 C. 解决问题方案 新增仓库根目录 `AGENTS.md`，明确后续项目修改需求必须记录开始时间、生成需求分析、实现方案、测试方案，并在实现方案和测试方案通过用户二次审核后再修改业务代码。新增 `工程分析/工程整体分析.md`、本经验记录，以及本次需求、实现、测试方案文档。 D. 后续如何避免问题 后续每次项目修改开始时先阅读 `AGENTS.md`、`工程分析/工程整体分析.md` 和 `工程分析/经验记录.md`，严格使用同一开始时间戳创建三类分析文档，并在用户确认实现方案和测试方案后再执行代码改动。 ## 2026-05-03-22-02-15 调整硬边界与高斯平滑预览分界线 A. 具体问题 硬边界和高斯平滑预览图中的黄色分界线出现 Y 字形：一部分随头颈部形变变成斜线，另一部分仍横向延长，视觉上像多出一条不自然的横线。 B. 产生问题原因 旧逻辑先把黄色分界线画到原始 CT 预览图上，再把整张图传入 `preview_deform_2d` 做快速 2D 形变。硬边界和高斯平滑在分界附近存在不连续或快速变化的运动权重，导致同一条标注线被分裂成不同运动状态。 C. 解决问题方案 将硬边界和高斯平滑预览改为先对不含黄色线的 CT 图执行形变，再在形变结果上叠加单条黄色分界线。保留原始图的水平分界线，并尽量不改变软过渡原有视觉效果。 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` 下，避免污染仓库。 ## 2026-05-03-23-22-10 修复阅览切换和下载触发 A. 具体问题 DICOM 阅览切片滑杆和显示模式切换时，浏览器出现 `ERR_CONNECTION_RESET`；同时 ZIP 文件下载可能在其他 UI 操作期间再次触发，并出现 HTTP 文件加载安全提示。 B. 产生问题原因 阅览重建接口每次请求都重新读取整套 DICOM 体数据，切片滑杆快速拖动和显示模式切换会并发触发多个重建请求。前端 AbortController 只能取消浏览器等待，不能停止后端已经开始的 DICOM 读取，容易造成内存压力并导致后端被系统终止。ZIP 下载通过直接访问后端 `/api/file` URL 触发，且缺少已完成 ZIP job 的一次性下载保护。 C. 解决问题方案 后端为 DICOM 体数据增加基于目录签名的内存缓存，并限制缓存数量；阅览接口复用缓存体数据生成不同平面、切片和窗宽窗位的 PNG。前端为阅览切片请求增加防抖，减少滑杆拖动时的请求数量。ZIP 下载增加已下载 job id 记录，并优先使用 fetch blob 转本地 `blob:` URL 触发下载，失败时再回退到直接 URL。 D. 后续如何避免问题 涉及整套 DICOM 体数据读取的接口必须考虑缓存、并发和请求节流，不能把滑杆这类高频 UI 操作直接绑定到重型后端计算。自动下载类逻辑必须记录已处理 job，避免同一个完成状态在后续渲染或轮询中重复触发。