2026-05-25-00-07-30 优化自动匹配对比视图与采样设置

工程分析/实现方案-2026-05-25-00-07-30.md

@@ -0,0 +1,64 @@
+# 实现方案-2026-05-25-00-07-30
+
+## 实现方案文档路径
+
+`工程分析/实现方案-2026-05-25-00-07-30.md`
+
+## 修改目标
+
+- 移除自动匹配页候选轨迹表格和低价值统计卡片。
+- 在“匹配结果”下方新增双栏 DICOM/STL 映射对比视图。
+- 同一个切片滑条同时控制两个视图。
+- 显示模式支持“所选骨骼区域”和“得分可视化”。
+- 骨骼区域默认空选。
+- 采样切片改为数量输入，按数量均匀筛选。
+- 调整默认权重：非骨区域惩罚 0.1、移动惩罚 0、缩放惩罚 0。
+- 为大 STL preview JSON 响应增加 gzip 发送，缓解 HTTP/2 大响应错误。
+
+## 涉及路径
+
+- `WebSite/src/components/AutoMatchWorkspace.tsx`
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `WebSite/server.ts`
+- `WebSite/src/types.ts`
+- `Docker部署/README.md`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+- 从 `ReverseWorkspace.tsx` 导出 `VoxelizationMappingView`，在自动匹配页复用。
+- 自动匹配页维护 `previewSlice` 和 `mappingMode` 状态，双视图传入同一个切片。
+- 为对比视图构造仅包含选中骨骼构件的 `moduleStyles`。
+- 采样切片数量通过 `buildUniformSampleSlices(total, count)` 生成 0-based 数组。
+- 自动匹配页不再显示候选轨迹表，保留关键位姿差值和操作按钮。
+- 后端新增 JSON gzip helper，`/models/:fileName/preview` 使用该 helper 返回大 preview。
+
+## 执行步骤
+
+1. 查看 `VoxelizationMappingView` 当前导出和 props。
+2. 修改自动匹配页面布局、状态和默认值。
+3. 修改采样切片生成逻辑与接口入参。
+4. 修改 STL preview 路由的大 JSON 发送方式。
+5. 执行 `npm run lint`、`npm run build`。
+6. 重启服务并验证健康检查与 preview 请求。
+7. 提交并推送 Gitea。
+
+## 兼容性与回滚方案
+
+- 自动匹配接口保留原 `sampleSlices` 字段，前端只是从数量生成。
+- 预览 gzip helper 只在客户端声明支持 gzip 时启用，不支持时仍走普通 JSON。
+- 若双视图性能不理想，可降低显示级别或只在有选中骨骼时加载。
+
+## 预计文件变更
+
+- 2 个前端组件。
+- 1 个后端服务文件。
+- 1 个类型文件。
+- 1 个 Docker 说明。
+- 工程分析三件套和经验记录。
+
+## 提交与部署策略
+
+- Commit message 使用 `2026-05-25-00-07-30 优化自动匹配对比视图与采样设置`。
+- 构建通过后重启 `tmux` 会话 `revoxelseg-dicom`。
+- 验证本机和公网入口。

工程分析/测试方案-2026-05-25-00-07-30.md

@@ -0,0 +1,54 @@
+# 测试方案-2026-05-25-00-07-30
+
+## 测试方案文档路径
+
+`工程分析/测试方案-2026-05-25-00-07-30.md`
+
+## 静态检查
+
+- 执行 `cd WebSite && npm run lint`。
+- 确认 `VoxelizationMappingView` 导出后类型不破坏逆向工作区。
+
+## 构建检查
+
+- 执行 `cd WebSite && npm run build`。
+
+## 关键业务场景验证
+
+- 自动微调匹配页骨骼区域默认无选中。
+- 未选择骨骼区域时运行会提示选择。
+- 采样切片数量默认均匀生成，可调整数量。
+- “匹配结果”下方显示两个映射视图，滑条同时控制两个视图切片。
+- 两种显示模式可切换。
+- 候选评估、采样切片、骨骼构件、最佳模式卡片和候选表格不再显示。
+- 运行后右侧视图使用最佳位姿，左侧视图保留基准位姿。
+
+## HTTP/2 preview 验证
+
+- 请求 `/api/projects/:projectId/models/sternum.stl/preview?limit=800000`。
+- 确认本机返回 200。
+- 确认响应支持 gzip 压缩。
+
+## 医学影像数据相关边界验证
+
+- 不修改原始 DICOM/STL 文件。
+- 仅影响预览和自动匹配页，不影响导出分割逻辑。
+
+## 部署验证
+
+- 重启 `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 包含时间戳。
+- 推送到 Gitea `main`。
+
+## 风险与回归关注点
+
+- 双视图不应导致未选中构件参与显示。
+- gzip 发送 JSON 后浏览器仍应能正常 `fetch().json()`。
+- 大 STL preview 仍可能消耗内存，后续可进一步做二进制/流式格式。

工程分析/经验记录.md

@@ -1869,3 +1869,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 凡是页面允许用户配置的优化条件，都要确认该条件确实进入评分函数，而不是只进入展示层。医学切片编号在 UI 中使用 `1-N`，服务端计算用 `0-(N-1)`，转换必须集中在请求边界。自动优化结果如果没有改变位姿，应明确解释“当前就是本轮最高分”，避免用户误以为按钮或算法没执行。
+
+## 2026-05-25-00-07-30 自动匹配页应以映射对比为主，高精度预览要压缩传输
+
+A. 具体问题
+
+用户认为自动匹配页下方候选表格和若干统计卡片价值不大，希望直接看到逆向分割映射视图，并能用同一个切片进度条对比当前位姿和自动匹配结果。同时用户反馈公网请求 `sternum.stl/preview?limit=800000` 会报 `ERR_HTTP2_PROTOCOL_ERROR`。
+
+B. 产生问题原因
+
+自动匹配第一版偏调参和数值轨迹，缺少与逆向工作区一致的可视化闭环。高精度 STL preview 返回的是很大的 JSON，未压缩时在 HTTP/2 反向代理链路中更容易触发传输错误或代理缓冲限制。
+
+C. 解决问题方案
+
+自动匹配页移除候选轨迹表和低价值统计卡片，复用 `VoxelizationMappingView` 放置当前位姿/自动匹配结果两个对比画面，并新增共享横向切片条；视图只显示用户选中的骨骼构件，且骨骼区域默认空选。采样切片改为按数量均匀生成，默认 9 张。默认评分权重调整为非骨区域惩罚 `0.1`、移动惩罚 `0`、缩放惩罚 `0`。后端新增 JSON gzip 发送 helper，STL preview 大响应在浏览器支持 gzip 时压缩返回，缓解公网 HTTP/2 大响应失败。
+
+D. 后续如何避免问题
+
+自动优化类页面应优先提供可视化验证，而不是只展示候选表格。高精度 STL preview 继续使用 JSON 时，必须关注响应大小、压缩和代理限制；若后续仍遇到大模型传输问题，应考虑二进制 preview、分块流式加载或按切片局部计算，而不是继续扩大单次 JSON。

工程分析/需求分析-2026-05-25-00-07-30.md

@@ -0,0 +1,50 @@
+# 需求分析-2026-05-25-00-07-30
+
+## 开始时间
+
+2026-05-25-00-07-30
+
+## 原始需求摘要
+
+用户要求自动微调匹配工作区去掉下方候选表格和若干统计卡片，把逆向分割映射视图放到“匹配结果”正下方，提供两个视图进行对比，并通过同一个进度条调节切片；只显示选中的骨骼区域，并支持“所选骨骼区域”和“得分可视化”两种模式。骨骼区域默认不选，需要用户选择；采样切片改为可选择数量，默认均匀筛选；移动惩罚和缩放惩罚默认 0，非骨区域惩罚默认 0.1。另有 STL preview 请求 `/models/sternum.stl/preview?limit=800000` 报 `ERR_HTTP2_PROTOCOL_ERROR` 的问题需要修复。
+
+## 业务目标
+
+- 自动匹配页面更像实际配准工作台，而不是调参表格。
+- 支持运行前/运行后在同一切片位置直观看骨骼区域对比。
+- 采样切片按数量自动均匀选取，减少手动输入负担。
+- 自动匹配初始权重更宽松，避免默认惩罚过强导致难以移动。
+- 修复高精度 STL preview 大 JSON 在公网 HTTP/2 下传输失败的问题。
+
+## 输入与输出
+
+- 输入：项目 ID、当前位姿、选中骨骼 STL、采样切片数量、评分权重、切片预览位置、显示模式。
+- 输出：自动匹配最佳位姿、两个映射预览画布、同一切片控制、可写回项目的最佳位姿。
+
+## 影响范围
+
+- `WebSite/src/components/AutoMatchWorkspace.tsx`
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `WebSite/server.ts`
+- `WebSite/src/types.ts`
+- `Docker部署/README.md`
+- `工程分析/经验记录.md`
+
+## 关键约束
+
+- 自动匹配仍不能调整旋转。
+- 只显示用户选中的骨骼构件；默认不能预选。
+- UI 中切片编号使用 `1-N`，接口内部使用 `0-(N-1)`。
+- 高精度 STL preview 不能再因为响应过大导致公网请求失败。
+
+## 风险点
+
+- 复用逆向分割映射视图需要避免引入工作区保存/导出逻辑。
+- 双视图加载 DICOM 与 STL preview 可能增加网络请求，要限制只加载选中骨骼区域。
+- 对大 STL preview 做 gzip 传输要保留普通 JSON 响应兼容。
+
+## 默认假设
+
+- “两个对比视图”分别显示基准位姿和最佳位姿。
+- “得分可视化”第一版使用当前骨骼区域在 DICOM 骨窗下的命中/偏离叠加，而不是完整热力图算法。
+- 采样切片数量默认 9 张，可调到 1-96 张。