2026-05-20-02-32-47 支持NII导出包与分割类别范围

工程分析/经验记录.md

@@ -1099,3 +1099,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 凡是三维视图中的方向、法向、切面或平移提示，都应从 Three.js 真实对象矩阵或统一坐标变换链路推导，不能手写静态示意。若该提示会随拖拽视角变化，还必须包含场景根节点和相机投影。
+
+## 2026-05-20-02-32-47 分割影像与类别元数据必须同包同源
+
+A. 具体问题
+
+用户要求“导出全部 NII.GZ”改成压缩包形式，同时分割影像必须附带不同类别 ID 与名称的对应 JSON，并且分割范围可选所有类别或可见类别。如果 NIfTI 和 JSON 分开下载，或二者使用不同筛选条件，后续在 ITK-SNAP 查看时容易无法追溯标签语义。
+
+B. 产生问题原因
+
+旧前端对多个导出目标采用连续触发多个直链下载，缺少一个原子化导出包；旧分割生成逻辑默认跳过隐藏构件，也没有把实际参与导出的 label/partId/name/fileName/color 等元数据写入侧车文件。
+
+C. 解决问题方案
+
+新增 `/api/projects/:projectId/export-bundle`，将 DICOM NIfTI、分割 NIfTI、位姿 JSON 和分割 labels JSON 放入同一个 `.tar.gz`。分割生成函数和 labels JSON 生成函数共用 `segmentationScope=visible|all`，确保可见/全量筛选逻辑一致；labels JSON 中记录 label、partId、name、categoryName、className、fileName、color、opacity、visible 和 activePose。
+
+D. 后续如何避免问题
+
+任何分割影像导出都应同时考虑语义侧车文件，并保证侧车元数据与实际 mask 标签来自同一批样式和筛选条件。多文件导出优先做成一个后端归档包，避免浏览器多下载顺序、丢文件或元数据错配。