2026-05-24-17-29-17 增加构件加载进度并修正滚轮事件

工程分析/实现方案-2026-05-24-17-29-17.md

@@ -0,0 +1,53 @@
+# 实现方案-2026-05-24-17-29-17
+
+## 实现方案文档路径
+
+`工程分析/实现方案-2026-05-24-17-29-17.md`
+
+## 修改目标
+
+- 为逆向分割映射视图增加可见 STL 构件加载进度条。
+- 修正 DICOM/映射画布滚轮缩放和触摸操作中的 passive event listener 警告。
+- 同步 Docker 部署说明与本次交互修正。
+
+## 涉及路径
+
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `WebSite/src/components/ProjectLibrary.tsx`
+- `Docker部署/README.md`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+- 在逆向分割映射视图中新增 overlay 加载状态，记录 `loading/loaded/total/phase`。
+- 可见构件列表变化时清空旧预览并按构件逐个更新加载进度；加载完成后再绘制最新 overlay。
+- 将需要阻止页面滚动的 `wheel` 缩放改为原生 `addEventListener('wheel', ..., { passive: false })`，避免 React 合成事件被浏览器按 passive 处理时产生告警。
+- 移除按钮触摸开始阶段不必要的 `event.preventDefault()`，用 `touch-action` 类维持操作稳定性。
+
+## 执行步骤
+
+1. 定位 `preventDefault` 和 `onWheel/onTouchStart` 使用点。
+2. 为项目库 DICOM 画布和逆向映射画布改造 wheel 事件监听。
+3. 为逆向映射视图增加加载进度状态和 UI。
+4. 更新 Docker 部署说明。
+5. 执行类型检查、构建、部署和访问验证。
+6. 提交并推送到 Gitea。
+
+## 兼容性与回滚方案
+
+- 新增进度条只依赖现有 STL preview API，不改变接口契约。
+- 如 wheel 原生监听出现兼容问题，可回退到 React `onWheel` 但必须移除 `preventDefault` 或继续保持非被动监听。
+- 回滚时可撤销本次 commit，重新构建并部署上一版本。
+
+## 预计文件变更
+
+- 2 个前端组件文件。
+- 1 个 Docker 部署说明文件。
+- 3 个工程分析当次文档。
+- 1 个经验记录追加。
+
+## 提交与部署策略
+
+- Commit message 使用 `2026-05-24-17-29-17 增加构件加载进度并修正滚轮事件`。
+- 构建通过后重启 `tmux` 会话 `revoxelseg-dicom`，使用生产模式启动服务。
+- 验证本机和公网入口可访问。

工程分析/测试方案-2026-05-24-17-29-17.md

@@ -0,0 +1,46 @@
+# 测试方案-2026-05-24-17-29-17
+
+## 测试方案文档路径
+
+`工程分析/测试方案-2026-05-24-17-29-17.md`
+
+## 静态检查
+
+- 执行 `cd WebSite && npm run lint`，确认 TypeScript 类型检查通过。
+- 搜索 `preventDefault` 相关调用，确认需要阻止页面滚动的场景使用非被动原生 wheel 监听，不再在 passive-prone touch/wheel 合成事件中调用。
+
+## 构建检查
+
+- 执行 `cd WebSite && npm run build`。
+- 确认 Vite 生产构建成功，前端 bundle 可生成。
+
+## 关键业务场景验证
+
+- 逆向工作区切换构件层级可见性时，映射视图区出现加载进度条，完成后显示当前可见构件 overlay。
+- 项目库 DICOM 影像保留滚轮缩放、拖拽移动、左转、右转和位置重置能力。
+- 逆向分割映射视图保留滚轮缩放、拖拽移动和位置重置能力。
+
+## 医学影像数据相关边界验证
+
+- 构件隐藏到 0 个可见项时不显示加载进度，并提示当前没有可见 STL 构件。
+- 大 STL 构件加载过程中不能用旧预览覆盖新可见状态。
+- 本次不改动 DICOM/STL 原始数据和 NIfTI 导出算法，仅验证显示反馈不影响已有流程。
+
+## 部署验证
+
+- 重启 `tmux` 会话 `revoxelseg-dicom`。
+- 验证 `http://127.0.0.1:4000/api/health`。
+- 验证 `http://127.0.0.1:4000/`。
+- 验证 `https://revoxel.huijutec.cn/api/health` 与 `https://revoxel.huijutec.cn/`。
+
+## Git/Gitea 备份验证
+
+- 仅暂存本次相关前端、Docker 文档和工程分析文件。
+- 提交 message 包含 `2026-05-24-17-29-17`。
+- 推送到 Gitea `main` 后检查本地分支与远端同步。
+
+## 风险与回归关注点
+
+- 浏览器控制台仍可能有第三方库内部 passive 事件提示，需要通过源码搜索和实际交互继续定位。
+- 加载进度 UI 不能遮挡核心 DICOM 区域或造成布局跳动。
+- 原生 wheel 监听要在组件卸载时清理，防止重复绑定。

工程分析/经验记录.md

@@ -1729,3 +1729,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 凡是导出“当前可见”这类 UI 状态，不能只依赖历史保存结果；后端应以项目当前状态为准，前端最好显式携带本次导出的关键状态，防止异步保存延迟。二维 overlay 如果用于判断实体形状，必须确认 STL 预览不是抽样缺面；对超过预览上限的大模型，应按可见构件高精度加载或在界面提示。细血管、胆管等管状结构应解释为“天然多小截面/窄带”，不要把所有结构都承诺成单一大实体块。
+
+## 2026-05-24-17-29-17 构件层级切换要有加载反馈并避免 passive 事件告警
+
+A. 具体问题
+
+用户反馈调整逆向工作区“构件层级”时可能出现暂时不显示或看起来像 bug，同时浏览器控制台反复打印 `Unable to preventDefault inside passive event listener invocation`。
+
+B. 产生问题原因
+
+逆向分割映射视图为了修正抽样缺面，已经改成按当前可见构件高精度加载 STL preview。构件眼睛切换后，新 preview 在网络和前端缓存返回前，旧 overlay 被清空或尚未绘制，界面没有明确进度反馈。另一个问题是项目库 DICOM 画布和逆向映射画布仍使用 React `onWheel` 调用 `preventDefault`，部分浏览器会把 wheel/touch 合成事件按 passive 处理；按钮 `onTouchStart` 中的 `preventDefault` 也会增加同类告警风险。
+
+C. 解决问题方案
+
+为逆向分割映射视图新增 `overlayLoadState`，在可见 STL 构件列表变化时清空旧 preview、显示 `loaded/total` 进度条，并在每个构件 preview 成功或失败后更新进度，全部完成后再绘制最新 overlay。项目库 DICOM 画布和逆向映射画布改为原生 `addEventListener('wheel', ..., { passive: false })`，保留滚轮缩放和阻止页面滚动能力。长按步进按钮改用 pointer 事件和 `touch-none`，移除 touch 合成事件里的 `preventDefault`。
+
+D. 后续如何避免问题
+
+后续只要某个 UI 操作会触发异步加载大 STL、DICOM 或导出预计算，都应提供明确加载状态、进度和空状态，避免用户把正常等待理解为显示故障。需要阻止滚轮默认滚动时，应使用原生非被动 wheel 监听并在卸载时清理；触摸按钮优先使用 pointer 事件和 `touch-action` 控制，不要在 passive-prone 的 touch 合成事件中调用 `preventDefault`。

工程分析/需求分析-2026-05-24-17-29-17.md

@@ -0,0 +1,44 @@
+# 需求分析-2026-05-24-17-29-17
+
+## 开始时间
+
+2026-05-24-17-29-17
+
+## 原始需求摘要
+
+用户反馈在逆向工作区调整“构件层级”时，可能出现构件显示异常或暂时不显示；如果处于加载中，应在界面显示加载进度条。同时浏览器控制台反复输出 `Unable to preventDefault inside passive event listener invocation`，需要排查并修正相关事件监听。
+
+## 业务目标
+
+- 提升构件层级可见性切换后的反馈，避免高精度 STL 预览加载期间被误判为显示故障。
+- 修正滚轮或触摸事件中被动监听器内调用 `preventDefault` 的浏览器警告。
+- 保持现有逆向分割映射视图、项目库 DICOM 操作和部署方式兼容。
+
+## 输入与输出
+
+- 输入：用户在构件层级中切换眼睛、透明度或可见构件后触发高精度模型预览重新加载；用户在 DICOM/映射画布上滚轮缩放或拖动。
+- 输出：加载可见 STL 构件时显示进度条与数量；加载完成后恢复正常 overlay；控制台不再因被动事件监听器反复打印 `preventDefault` 警告。
+
+## 影响范围
+
+- `WebSite/src/components/ReverseWorkspace.tsx`：逆向分割映射视图、构件预览加载流程、滚轮缩放事件。
+- `WebSite/src/components/ProjectLibrary.tsx`：项目库 DICOM 画布滚轮缩放与触摸重复按钮事件。
+- `Docker部署/README.md`：同步记录本次前端交互与部署包能力变化。
+- `工程分析/经验记录.md`：沉淀本次事件监听和加载反馈经验。
+
+## 关键约束
+
+- 必须继续按当前 `tmux` 会话 `revoxelseg-dicom` 和 `npm run serve -- --host 0.0.0.0 --port 4000` 方式部署验证。
+- 不改变 STL 到 Label Map 的体素化算法语义，仅改善加载反馈与事件监听方式。
+- 不能提交运行态数据、导出包、医学原始数据或无关文件。
+
+## 风险点
+
+- 高精度可见构件加载可能较快或较慢，进度状态要处理竞态，避免旧加载结果覆盖新可见状态。
+- 去除或迁移 `preventDefault` 时不能破坏滚轮缩放、拖拽平移、长按步进等既有交互。
+- 进度条必须只在加载中展示，避免常驻遮挡医学影像区域。
+
+## 待确认问题或默认假设
+
+- 默认假设用户所说的“加载”主要指逆向分割映射视图为当前可见构件重新拉取 STL preview 的阶段。
+- 默认假设控制台警告来自 React `onWheel` 或触摸事件中的 `preventDefault`，优先改为原生非被动 wheel 监听和移除不必要的 touch `preventDefault`。