2026-05-20-22-35-42 导入资产与分割导出优化

工程分析/实现方案-2026-05-20-22-35-42.md

@@ -0,0 +1,61 @@
+# 实现方案-2026-05-20-22-35-42
+
+## 实现方案文档路径
+
+`工程分析/实现方案-2026-05-20-22-35-42.md`
+
+## 修改目标
+
+- 精简 Overlay Label Map 状态文案。
+- 导出项目及结果支持分割整体/分构件导出，并调整默认勾选与排序。
+- 为项目库 DICOM/STL 导入按钮接入真实上传流程，空项目展示导入提示。
+- 项目级上传资产独立存储，恢复演示环境仍使用默认数据。
+- 用户账号重名冲突给出可读反馈。
+- 逆向工作区无保存结果时初次加载默认执行 Z 轴等比例拉伸。
+
+## 涉及路径
+
+- `WebSite/server.ts`
+- `WebSite/src/lib/api.ts`
+- `WebSite/src/components/ProjectLibrary.tsx`
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `WebSite/src/components/UserManagement.tsx`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+1. 后端新增项目上传资产目录 `WebSite/data/uploads/<projectId>/dicom|stl`，导入接口接收 base64 文件并写入项目专属目录。
+2. 后端统一项目 DICOM/STL 路径解析，预览、三维融合、模型文件、导出和分割生成均读取项目路径。
+3. 导出包接口增加 `segmentationExportMode=combined|separate` 参数；整体模式沿用现有 label map，分构件模式逐个构件生成独立 NII.GZ。
+4. 前端导出面板增加分割导出方式单选，调整默认选择和选项顺序。
+5. 项目库导入按钮使用隐藏文件输入，按当前视图选择 DICOM 或 STL 上传，并刷新项目状态。
+6. 用户管理编辑接口 409 时展示“账号已存在，请更换账号”等提示。
+7. 逆向工作区加载项目后，若没有保存结果，则在 fusion volume 和模型边界都就绪后触发一次 Z 拉伸。
+
+## 执行步骤
+
+1. 编写本次需求分析、实现方案、测试方案。
+2. 阅读并定位导出、导入、项目路径、用户管理和逆向工作区相关源码。
+3. 修改后端资产导入与导出逻辑。
+4. 修改前端项目库、逆向工作区和用户管理交互。
+5. 执行 `npm run lint` 与 `npm run build`。
+6. 使用 tmux 重启 `revoxelseg-dicom` 服务并验证 `/api/health` 与首页。
+7. 追加经验记录，提交并推送本次相关文件。
+
+## 兼容性与回滚方案
+
+- 未导入资产的默认项目继续读取 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/`。
+- 已保存的项目路径由状态文件保存，恢复演示环境可通过现有重置接口回到默认路径。
+- 若分构件导出失败，可回退为 `segmentationExportMode=combined` 的原有整体导出。
+
+## 预计文件变更
+
+- 前端：3 个组件与 API 封装。
+- 后端：1 个 Express 服务文件。
+- 工程文档：本次三件套与经验记录。
+
+## 提交与部署策略
+
+- 仅暂存本次修改的源码与工程分析文档。
+- commit message 包含 `2026-05-20-22-35-42` 与简要描述。
+- 提交后推送到既有 Gitea 远端，并重启 4000 端口服务。

工程分析/测试方案-2026-05-20-22-35-42.md

@@ -0,0 +1,50 @@
+# 测试方案-2026-05-20-22-35-42
+
+## 测试方案文档路径
+
+`工程分析/测试方案-2026-05-20-22-35-42.md`
+
+## 静态检查
+
+- 执行 `cd WebSite && npm run lint`，确认 TypeScript 类型检查通过。
+- 使用 `rg` 检查旧文案 `Overlay Label Map ·` 是否仍残留在可见 UI。
+
+## 构建检查
+
+- 执行 `cd WebSite && npm run build`，确认生产构建通过。
+
+## 关键业务场景验证
+
+- 导出面板初始状态：`DICOM 原始影像` 与 `STL 原始模型` 不勾选，二者排在上方，`分割影像`在下方。
+- 勾选分割影像时显示“构件整体导出 / 构件分别导出”选项，并将选择传入后端。
+- 系统管理编辑用户账号为已有账号时，页面展示友好错误提示。
+- 新建无 DICOM 项目时，DICOM 预览区域显示“请导入DICOM影像”。
+- DICOM 与 STL 导入按钮可以唤起文件选择并调用导入接口。
+- 逆向工作区无保存结果时初次加载默认执行 Z 轴拉伸；已有保存结果不被覆盖。
+
+## 医学影像数据相关边界验证
+
+- 上传导入写入 `WebSite/data/uploads/<projectId>/`，不写入默认 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/`。
+- 默认演示项目重置后仍回到 300 张 DICOM 与默认 9 个 STL 构件。
+- 分构件导出时保留构件 ID 与标签 JSON，避免重叠构件在单一 label map 中互相覆盖。
+
+## 部署验证
+
+- 使用 `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-22-35-42`。
+- `git push` 推送到 Gitea 后确认成功。
+
+## 风险与回归关注点
+
+- 避免上传文件体积过大导致请求失败时没有用户提示。
+- 避免项目级 STL 路径解析遗漏，导致预览可用但导出失败。
+- 避免默认 Z 拉伸重复触发，引起位姿越拉越大。

工程分析/经验记录.md

@@ -1369,3 +1369,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 涉及中文下载名时应同时设置 ASCII fallback 和 `filename*`，并用 `curl -D -` 抽查响应头。复用医学影像组件时，布局差异应继续沉到小粒度参数，例如 `overlayPlacement`、`viewPreset`，避免为了位置差异复制整套视图；同时确认 Overlay 摘要不遮挡 DICOM 主画布。
+
+## 2026-05-20-22-35-42 项目导入不能覆盖默认医学数据
+
+A. 具体问题
+
+用户要求项目库 DICOM 与 STL 导入按钮真正可用，同时“头部CT 模型逆向体素化演示”仍作为测试数据保留，导入其他影像或模型不能污染默认 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/`。
+
+B. 产生问题原因
+
+后端此前所有 DICOM/STL 预览、导出和分割生成都硬编码读取默认数据目录，项目库导入按钮也没有对应上传接口。若直接把上传文件写入默认目录，会破坏演示环境重置语义，并让默认项目资产与用户项目资产混在一起。
+
+C. 解决问题方案
+
+新增项目级上传接口，将导入文件写入 `WebSite/data/uploads/<projectId>/DICOM|STL`，项目状态只保存相对路径；预览、三维融合、STL 模型、导出包和分割生成统一改为根据项目路径解析文件。恢复演示环境仍通过默认状态回到原始 `Head_CT_*` 数据。前端导入按钮接入隐藏文件选择器，并在无 DICOM/STL 时显示明确导入提示。
+
+D. 后续如何避免问题
+
+凡是新增医学影像或模型导入能力，都必须区分“默认演示资产”和“项目用户资产”。后端路径解析不能继续硬编码单一目录；导入后要清理前后端缓存并清空旧分割结果，避免新数据套用旧预览或旧位姿结果。

工程分析/需求分析-2026-05-20-22-35-42.md

@@ -0,0 +1,54 @@
+# 需求分析-2026-05-20-22-35-42
+
+## 开始时间
+
+2026-05-20-22-35-42
+
+## 原始需求摘要
+
+1. 将映射视图下方文案 `Overlay Label Map · Overlay Label Map 已就绪` 精简为 `Overlay Label Map`。
+2. 系统管理工作区修改账号为同名账号时，需要给出清晰反馈，避免只暴露浏览器 409 报错。
+3. “导出项目及结果”中，导出分割影像时新增“构件分别导出 / 构件整体导出”选项，用于处理构件重叠场景。
+4. 导出面板初始默认不选择 `DICOM 原始影像` 和 `STL 原始模型`，且二者位于选项最上方，分割影像放到最下方。
+5. 新建项目没有 DICOM 影像时显示“请导入DICOM影像”，同时修复 DICOM 与 3D 模型导入按钮无响应问题。
+6. “头部CT 模型逆向体素化演示”作为默认测试数据，用户导入新影像或模型不得覆盖原始数据；恢复演示环境后仍回到初始 DICOM 与 STL。
+7. 逆向工作区初始状态默认对模型做一次 Z 轴拉伸。
+
+## 业务目标
+
+- 让项目导入、导出和逆向工作区初始对齐流程更符合实际使用习惯。
+- 对重叠构件分割导出提供整体标签图和按构件独立导出两种策略。
+- 保护默认演示数据资产，支持用户项目独立导入。
+- 用明确的界面反馈替代后台管理接口冲突时的裸错误。
+
+## 输入与输出
+
+- 输入：用户在项目库中导入 DICOM/STL 文件、在导出面板选择导出目标与分割导出方式、在系统管理中编辑账号。
+- 输出：项目级独立资产目录、导出 tar.gz 包、分割整体或分构件 NII.GZ、清晰错误提示、更新后的逆向工作区初始位姿。
+
+## 影响范围
+
+- `WebSite/server.ts`：导入资产接口、项目资产路径解析、导出包分割策略、用户冲突响应。
+- `WebSite/src/lib/api.ts`：导出参数与导入接口封装。
+- `WebSite/src/components/ProjectLibrary.tsx`：导入按钮、空项目提示、导出选项顺序和分割导出方式。
+- `WebSite/src/components/ReverseWorkspace.tsx`：Overlay 文案、导出选项、默认 Z 拉伸。
+- `WebSite/src/components/UserManagement.tsx`：409 冲突友好提示。
+
+## 关键约束
+
+- 必须保留默认 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/` 原始数据，不允许导入时覆盖。
+- 导出面板的项目库与逆向工作区入口保持一致。
+- 默认 Z 拉伸不能覆盖项目库已有保存结果的位姿。
+- 只提交本次相关文件，不混入历史删除文档和软著材料。
+
+## 风险点
+
+- DICOM 文件可能较大，前端转 base64 上传会增加内存与请求体体积，需要设置后端请求体限制并控制失败反馈。
+- 分构件导出会增加生成时间与压缩包体积，需要沿用当前可见/全部构件过滤逻辑。
+- 修改模型路径解析后，所有 STL 预览、导出、分割生成都要使用项目级路径，避免只在部分接口生效。
+
+## 默认假设
+
+- 本次“导入按钮”先支持浏览器本地文件选择上传，DICOM 支持多文件，STL 支持多文件。
+- “构件整体导出”为现有单个 label map；“构件分别导出”为每个构件生成一个独立 label map，并附带统一标签 JSON。
+- 默认 Z 轴拉伸只在没有已保存逆向分割结果的新进入工作区中执行一次。