2026-05-20-23-28-51 项目库映射交互与导入提示优化

工程分析/实现方案-2026-05-20-23-28-51.md

@@ -0,0 +1,58 @@
+# 实现方案-2026-05-20-23-28-51
+
+## 实现方案文档路径
+
+`工程分析/实现方案-2026-05-20-23-28-51.md`
+
+## 修改目标
+
+- 修复位姿按钮首次点击导致中部可视化工具栏滚动上跳。
+- 统一项目库与逆向工作区竖向 Slice Navigator 滑块居中样式。
+- 将项目库 Overlay Label Map 摘要从映射视图右侧黑色面板改为导出按钮下方浅色信息格。
+- 调整逆向分割结果状态徽标与标题同行。
+- 导入已有 DICOM/STL 时增加覆盖确认。
+- DICOM 导入时生成并保存详细信息缓存，详情接口优先读取缓存。
+- 项目库逆向分割页导出按钮移到顶部操作区。
+
+## 涉及路径
+
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `WebSite/src/components/ProjectLibrary.tsx`
+- `WebSite/src/index.css`
+- `WebSite/server.ts`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+1. `VoxelizationMappingView` 新增 Overlay 统计回调和 `overlayPlacement='none'`，项目库使用外置浅色 Overlay 面板。
+2. 在项目库 mask 视图顶部操作区渲染“导出项目及结果”按钮和下拉菜单，删除下方旧导出入口。
+3. 调整竖向 range input CSS，使可点击层覆盖轨道但 thumb 视觉中心与轨道中心对齐。
+4. 为位姿微调按钮增加 `onMouseDown preventDefault`，并在位姿更新时保持工具栏滚动位置。
+5. 导入入口根据项目现有数据量弹出覆盖确认，再唤起文件选择。
+6. 后端 DICOM 导入后调用现有 DICOM 信息解析逻辑，将结果写入上传目录缓存文件；`/dicom-info` 优先读取缓存。
+
+## 执行步骤
+
+1. 写入本次需求、实现、测试方案。
+2. 定位映射视图、项目库 mask 页、位姿控件、CSS range 样式和导入接口。
+3. 修改前端组件结构与样式。
+4. 修改后端 DICOM 信息缓存逻辑。
+5. 执行 `npm run lint`、`npm run build`。
+6. 重启 `revoxelseg-dicom` tmux 服务并验证 `/api/health` 与首页。
+7. 追加经验记录，提交并推送 Gitea。
+
+## 兼容性与回滚方案
+
+- 若外置 Overlay 面板出现异常，可将项目库 `overlayPlacement` 改回 `side`。
+- DICOM 信息缓存失败时不阻断默认详情接口解析，可回退到实时解析。
+- 导入覆盖确认只在前端增加，后端接口仍保持原有覆盖写入能力。
+
+## 预计文件变更
+
+- 前端组件 2 个，样式 1 个，后端 1 个，工程分析文档 4 个。
+
+## 提交与部署策略
+
+- 只暂存本次相关文件，忽略历史删除和软著未跟踪文件。
+- commit message 包含 `2026-05-20-23-28-51` 与简要描述。
+- 推送 Gitea 后重启 4000 服务。

工程分析/测试方案-2026-05-20-23-28-51.md

@@ -0,0 +1,54 @@
+# 测试方案-2026-05-20-23-28-51
+
+## 测试方案文档路径
+
+`工程分析/测试方案-2026-05-20-23-28-51.md`
+
+## 静态检查
+
+- 执行 `cd WebSite && npm run lint`，确保 TypeScript 类型检查通过。
+- 使用 `rg` 检查项目库是否仍残留不需要的黑色 side Overlay 面板调用。
+
+执行结果：`npm run lint` 已通过；项目库当前使用 `overlayPlacement="none"` 外置 Overlay 摘要。
+
+## 构建检查
+
+- 执行 `cd WebSite && npm run build`，确认生产构建通过。
+
+执行结果：`npm run build` 已通过；Vite 仅提示既有 chunk 体积超过 500 kB。
+
+## 关键业务场景验证
+
+- 逆向工作区位姿平移 Z 的 `-` 首次点击不再造成工具栏滚动条上跳。
+- 项目库和逆向工作区竖向 Slice Navigator 圆形滑块居中在轨道上。
+- 项目库逆向分割结果页顶部可点击“导出项目及结果”，菜单不被下方边界裁切。
+- 项目库 Overlay Label Map 显示在导出按钮下方，使用浅色信息格风格。
+- “逆向分割结果”标题与 `已保存` 状态同一行展示。
+- 项目已有 DICOM/STL 时点击导入会提示覆盖风险。
+
+## 医学影像数据相关边界验证
+
+- 导入 DICOM 后上传目录生成 DICOM 信息缓存。
+- `/api/projects/:projectId/dicom-info` 对上传项目优先返回缓存内容。
+- 覆盖导入仍只写入 `WebSite/data/uploads/<projectId>/...`，不影响 `Head_CT_DICOM/` 和 `Head_CT_ReConstruct/`。
+
+## 部署验证
+
+- 重启 tmux 会话 `revoxelseg-dicom`：
+  - `cd WebSite`
+  - `npm run serve -- --host 0.0.0.0 --port 4000`
+- 验证：
+  - `curl http://127.0.0.1:4000/api/health`
+  - `curl -I http://127.0.0.1:4000/`
+
+## Git/Gitea 备份验证
+
+- `git status --short` 确认暂存范围不包含无关历史删除或软著材料。
+- commit message 包含 `2026-05-20-23-28-51`。
+- `git push origin main` 成功。
+
+## 风险与回归关注点
+
+- Overlay 外置后仍要随切片、构件显示、颜色、透明度实时变化。
+- 位姿按钮防滚动跳动不能破坏长按连续微调。
+- DICOM 信息缓存不能在项目覆盖导入后返回旧内容。

工程分析/经验记录.md

@@ -1387,3 +1387,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 凡是新增医学影像或模型导入能力，都必须区分“默认演示资产”和“项目用户资产”。后端路径解析不能继续硬编码单一目录；导入后要清理前后端缓存并清空旧分割结果，避免新数据套用旧预览或旧位姿结果。
+
+## 2026-05-20-23-28-51 项目库结果操作要避免遮挡与误覆盖
+
+A. 具体问题
+
+用户指出位姿微调首次点击会带动可视化工具栏滚动条上跳，竖向 Slice Navigator 圆点没有稳定居中；项目库 Overlay Label Map 仍是黑色面板且位置不利于复核，“已保存”状态竖排；已有 DICOM/STL 再导入时缺少覆盖提醒，DICOM 详情也不应等点击后才解析。
+
+B. 产生问题原因
+
+位姿按钮在可滚动容器内按下时会触发浏览器默认焦点滚动，状态更新后滚动位置没有被恢复。项目库复用映射组件时仍使用组件内部深色 Overlay 摘要，导出入口放在下方导致菜单容易被页面边界裁切。DICOM 详情接口只做按需解析，导入流程没有缓存元数据，也没有在前端导入入口判断现有资产。
+
+C. 解决问题方案
+
+为位姿微调按钮增加 `preventDefault`，并在 `modelPose` 更新前后保持可视化工具栏 `scrollTop`。调整竖向 range input 的轨道和 thumb 偏移，使项目库与逆向工作区滑块居中。`VoxelizationMappingView` 增加 Overlay 统计回调和 `overlayPlacement="none"`，项目库外置浅色 Overlay 摘要；导出按钮移到顶部操作区，结果状态徽标增加不换行约束。项目导入前根据 DICOM/STL 现有数量弹覆盖确认；后端导入 DICOM 时生成 `.revoxelseg-dicom-info.json`，详情接口优先读取缓存。
+
+D. 后续如何避免问题
+
+可滚动面板内的长按按钮要优先处理焦点滚动和滚动位置恢复；医学视图内的统计面板若影响主画布或菜单可达性，应外置为复核信息块。任何覆盖式资产导入都要在前端显式确认，并在后端同步生成或清理与资产强绑定的缓存，防止新旧 DICOM/STL 信息串用。

工程分析/需求分析-2026-05-20-23-28-51.md

@@ -0,0 +1,53 @@
+# 需求分析-2026-05-20-23-28-51
+
+## 开始时间
+
+2026-05-20-23-28-51
+
+## 原始需求摘要
+
+1. 修复逆向工作区点击模型位姿平移 Z 的 `-` 时，可视化工具栏滚动条首次上跳的问题。
+2. 项目库与逆向工作区中的竖向切片滑块圆点需要居中在滑条中。
+3. 项目库 Overlay Label Map 放到“导出项目及结果”下方，颜色改为与项目库浅色信息格统一，不再使用黑色面板。
+4. 项目库“逆向分割结果”右侧 `已保存` 不应竖排，需与标题同行展示。
+5. 项目已有 DICOM 影像或 3D 模型时再次导入，需要提示新数据会覆盖原数据。
+6. 项目库 DICOM 详细信息在传入 DICOM 时提前解析，减少后续点击详情时的解析等待。
+7. 项目库逆向分割页的“导出项目及结果”移到顶部操作区，与导入入口同级，避免下方菜单被页面边界裁切。
+
+## 业务目标
+
+- 让位姿微调、切片导航和导出菜单的交互更加稳定。
+- 将项目库逆向分割结果页从“深色工作区组件”调整为“浅色项目库复核信息区”。
+- 在导入覆盖原有医学影像/模型前给出明确确认，降低误操作风险。
+- 上传 DICOM 时预解析元数据，提升后续查看 DICOM 详细信息的响应速度。
+
+## 输入与输出
+
+- 输入：用户点击位姿平移按钮、拖动竖向切片滑条、打开项目库逆向分割结果、重新导入 DICOM/STL、查看 DICOM 信息。
+- 输出：稳定的工具栏滚动位置、居中的竖向滑块、浅色 Overlay 摘要、顶部导出菜单、覆盖确认提示、预缓存 DICOM 信息。
+
+## 影响范围
+
+- `WebSite/src/components/ReverseWorkspace.tsx`：位姿按钮滚动稳定、映射视图 Overlay 输出和滑条样式入口。
+- `WebSite/src/components/ProjectLibrary.tsx`：项目库逆向分割布局、顶部导出、覆盖导入确认、浅色 Overlay 面板。
+- `WebSite/src/index.css`：竖向 range input 样式。
+- `WebSite/server.ts`：DICOM 导入时生成信息缓存，DICOM 信息接口优先使用缓存。
+
+## 关键约束
+
+- 项目库复核页与逆向工作区仍复用同一映射组件，避免维护两套核心渲染逻辑。
+- 覆盖导入只覆盖项目级上传资产，不覆盖默认演示数据目录。
+- 位姿按钮防跳动不能影响连续按住调参能力。
+- Overlay 摘要移动到项目库外部后，逆向工作区仍保留底部 Overlay 摘要。
+
+## 风险点
+
+- 将 Overlay 摘要外置后需要把统计数据从映射组件传回项目库，避免重复计算或丢失实时联动。
+- 竖向 range input 在不同浏览器下样式差异较大，需要保持 WebKit 与 Firefox 都可用。
+- DICOM 信息缓存必须在导入后与项目路径一致，避免旧数据详情串到新项目。
+
+## 默认假设
+
+- “已保存”指项目库逆向分割结果标题右侧状态徽标。
+- “设置在条中间”指竖向切片导航的圆形滑块需要与轨道中心线对齐。
+- DICOM 信息缓存优先服务项目级上传数据；默认演示数据仍可按需解析。