2026-05-25-14-00-24 修正项目导出结构与新增批处理API

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

@@ -0,0 +1,62 @@
+# 实现方案-2026-05-25-14-00-24
+
+## 实现方案文档路径
+
+`工程分析/实现方案-2026-05-25-14-00-24.md`
+
+## 修改目标
+
+1. 将“导出项目及结果”从 tar.gz 改为 ZIP，消除 `PaxHeaders` 暴露问题。
+2. 统一 ZIP 内部结构：根目录直接包含 `manifest.json`、`pose/`、`segmentation/`、`segmentation-parts/`、`dicom/`、`stl/` 等目录。
+3. 分类分割导出时使用构件类别名生成 `.nii.gz` 文件名。
+4. 前端导出时显示顶部细进度条，并通过下载进度回调更新。
+5. 新增自动化 API，支持 DICOM/STL 上传、位姿参数、轴向自动拉伸、可选自动匹配、可选导出、可选记录项目库和锁定。
+
+## 涉及路径
+
+- `WebSite/server.ts`
+- `WebSite/src/lib/api.ts`
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `工程分析/需求分析-2026-05-25-14-00-24.md`
+- `工程分析/实现方案-2026-05-25-14-00-24.md`
+- `工程分析/测试方案-2026-05-25-14-00-24.md`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+- 使用项目现有 `adm-zip` 依赖生成 ZIP，而不是继续维护手写 tar.gz 的 PAX 扩展路径。
+- 在后端导出包中新增根级 `manifest.json`，记录项目、导出目标、格式、分割范围、分类导出模式、位姿等信息。
+- 后端分类导出命名为 `segmentation-parts/{类别名}.nii.gz`，若重名则自动追加序号。
+- 前端下载函数改为 `XMLHttpRequest`，支持 `onprogress` 并从 `Content-Disposition` 解析文件名。
+- `ReverseWorkspace` 增加 `exportProgress` 状态和顶部 fixed 细进度条；服务端生成阶段使用平滑进度，下载阶段使用真实进度。
+- 新增 `POST /api/reverse-pipeline`，接收 multipart 的 `dicomFiles`、`stlFiles`、可选 `metadata` JSON；复用现有资产解包、NIfTI 导出和自动匹配函数。
+
+## 执行步骤
+
+1. 调整服务端项目导出包创建逻辑，返回 ZIP buffer 并改为 `.zip` 下载。
+2. 更新导出包内部文件命名与 manifest 内容。
+3. 更新前端下载 API，加入进度回调。
+4. 在逆向工作区渲染导出进度条并接入进度回调。
+5. 增加批处理 API 的参数解析、项目创建、资产写入、位姿归一化、自动拉伸、自动匹配、导出、记录与锁定逻辑。
+6. 执行 TypeScript 构建和必要接口验证。
+7. 重新部署到 `tmux` 会话 `revoxelseg-dicom` 并验证本地与公网。
+8. 追加经验记录，提交并推送 Gitea。
+
+## 兼容性与回滚方案
+
+- 单文件 `export-nifti` 和 `dicom-archive` 接口保持原行为。
+- 若 ZIP 导出出现问题，可回滚 `createProjectExportBundle` 和 `/export-bundle` 响应相关修改。
+- 新增 API 为独立路径，不影响现有页面流程。
+
+## 预计文件变更
+
+- 后端：导出包结构、批处理 API、辅助函数。
+- 前端：下载 helper 和导出进度 UI。
+- 工程分析文档：三件套与经验记录。
+
+## 提交与部署策略
+
+- 修改完成后运行 `npm run build`。
+- 使用 `tmux` 会话 `revoxelseg-dicom` 重启 `npm run serve -- --host 0.0.0.0 --port 4000`。
+- 验证 `http://127.0.0.1:4000/api/health`、`http://127.0.0.1:4000/`、`https://revoxel.huijutec.cn/`。
+- commit message 包含 `2026-05-25-14-00-24` 和简要描述，并推送到 Gitea。

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

@@ -0,0 +1,50 @@
+# 测试方案-2026-05-25-14-00-24
+
+## 测试方案文档路径
+
+`工程分析/测试方案-2026-05-25-14-00-24.md`
+
+## 静态检查
+
+- 检查 TypeScript 类型是否通过 Vite 构建。
+- 检查新增导出和 API 函数没有破坏现有 `ProjectExportTarget`、`ModelPoseValue`、`AutoMatchRequest` 使用。
+- 检查 ZIP 内路径不包含项目名根目录。
+
+## 构建检查
+
+- 在 `WebSite/` 执行：
+  - `npm run build`
+
+## 关键业务场景验证
+
+- 请求 `/api/projects/:projectId/export-bundle` 导出分割、位姿等内容，确认响应为 `.zip`。
+- 使用 `unzip -l` 查看 ZIP，确认存在 `manifest.json`、`segmentation/labels.json`，分类模式下存在 `segmentation-parts/{类别名}.nii.gz`。
+- 前端导出按钮点击后确认顶部进度条出现并完成后自动消失。
+- 新增 `/api/reverse-pipeline` 在默认不导出时返回 JSON；在指定导出内容时返回 ZIP。
+
+## 医学影像数据相关边界验证
+
+- 分割导出应继续使用当前 DICOM 体数据和当前位姿。
+- 可见类别导出时仅导出可见构件；所有类别导出时导出全部构件。
+- 分类导出的单构件 `.nii.gz` 文件命名可直接对应类别，类别映射 JSON 同包提供。
+
+## 部署验证
+
+- 重启 `tmux` 会话 `revoxelseg-dicom` 中的服务。
+- 验证：
+  - `http://127.0.0.1:4000/api/health`
+  - `http://127.0.0.1:4000/`
+  - `https://revoxel.huijutec.cn/`
+
+## Git/Gitea 备份验证
+
+- `git status --short` 确认本次改动范围。
+- commit message 包含 `2026-05-25-14-00-24`。
+- 推送至 Gitea 后确认 `origin/main` 更新。
+
+## 风险与回归关注点
+
+- ZIP 下载文件名需要兼容中文项目名。
+- 批处理 API 的临时项目目录需要在不入库时清理，避免磁盘堆积。
+- 自动匹配失败不能导致已上传临时文件残留或项目状态异常。
+- 导出进度条不能遮挡和阻塞其他功能。

工程分析/经验记录.md

@@ -1977,3 +1977,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 后续调整自动匹配参数上限时，要同时检查前端控件、API 类型、服务端归一化、默认值和运行耗时提示。对可能显著增加耗时的参数，只提高上限不改变默认值；若用户常用高上限，应补充进度、取消和超时保护。
+
+## 2026-05-25-14-00-24 项目导出包不应使用会暴露 PAX 头的 tar.gz
+
+A. 具体问题
+
+用户在 Windows 解压“导出项目及结果”压缩包时，只能看到 `entries`、`PaxHeaders` 和无扩展名编号文件，无法直接看到 JSON、分割类别映射和 `.nii.gz` 分割结果。同时分类分割导出的文件名带编号和 `-label` 后缀，不利于后续按类别处理。
+
+B. 产生问题原因
+
+旧导出包使用手写 tar.gz。tar 路径一旦包含中文项目名或较长路径，服务端会写入 PAX 扩展头；部分 Windows 解压工具会把 PAX 扩展头当成普通目录展示，并把真实文件显示成 `entries/000001` 之类的中转名。压缩包内部还额外套了项目名根目录，而下载文件名本身已经包含项目名。
+
+C. 解决问题方案
+
+将“项目及结果导出”改为 ZIP，包内不再套项目名根目录，固定输出 `manifest.json`、`pose/pose.json`、`segmentation/labels.json`、`segmentation/label.nii.gz` 或 `segmentation-parts/{类别名}.nii.gz`、`dicom/image.nii.gz`、`stl/{原文件名}`。前端下载改为 XHR blob 下载，接入顶部导出进度条。新增 `POST /api/reverse-pipeline`，支持上传 DICOM/STL、应用旋转/平移/缩放/镜像/轴向自动拉伸、可选自动匹配、可选导出、可选记录项目库和锁定。
+
+D. 后续如何避免问题
+
+面向 Windows 用户直接查看的复杂导出包优先使用 ZIP，不要用需要 PAX 扩展的 tar.gz；如果必须使用 tar.gz，必须避免非 ASCII 和长路径，或确认目标解压器正确隐藏 PAX。导出包内部结构应以机器可读和人工可读为准，分类分割文件名保持类别名，映射关系单独放入 `labels.json`。

工程分析/需求分析-2026-05-25-14-00-24.md

@@ -0,0 +1,54 @@
+# 需求分析-2026-05-25-14-00-24
+
+## 开始时间
+
+2026-05-25-14-00-24
+
+## 原始需求摘要
+
+用户反馈“导出项目及结果”的压缩包内容异常，只能看到 `entries`、`PaxHeaders` 和无扩展名编号文件，缺少可直接识别的 JSON、分割类别映射和 `.nii.gz` 分割结果。用户希望压缩包内不再套项目名目录，内容格式统一；分类导出的 `.nii.gz` 直接使用类别名作为文件名。同时，点击导出后需要在页面最上方显示不影响其他操作的导出进度条。最后需要提供一个可调用 API：给定 DICOM 和 STL，能够指定 X/Y/Z 轴拉伸、旋转、平移、缩放、镜像、是否自动配准、导出内容、是否记录项目库、是否上锁。
+
+## 业务目标
+
+- 让项目导出包在 Windows 常见解压工具中可直接识别文件结构，不出现 PAX 头目录。
+- 让导出包内的分割结果、类别映射、位姿和模型文件按稳定目录命名，便于后续处理脚本读取。
+- 让用户点击导出后能获得明确进度反馈，同时不阻塞逆向工作区其他功能。
+- 为外部系统或脚本提供一条“上传 DICOM/STL -> 应用位姿/自动配准 -> 可选记录/锁定 -> 可选导出”的自动化接口。
+
+## 输入与输出
+
+- 输入：
+  - 当前项目库中的 DICOM、STL、构件可见性、构件 ID、位姿和导出选项。
+  - 批处理 API 的 multipart 文件或 JSON 资产、位姿参数、自动匹配参数、导出目标、项目记录与锁定开关。
+- 输出：
+  - ZIP 格式项目导出包。
+  - 顶部导出进度条。
+  - 新增批处理 API 的 JSON 响应或 ZIP 下载响应。
+
+## 影响范围
+
+- `WebSite/server.ts`：项目导出包生成、批处理 API、导出响应类型与文件名。
+- `WebSite/src/lib/api.ts`：项目导出包下载进度回调。
+- `WebSite/src/components/ReverseWorkspace.tsx`：顶部导出进度条和导出调用。
+- `工程分析/经验记录.md`：完成后追加本次经验。
+
+## 关键约束
+
+- 继续保持单独 DICOM 原始影像下载接口兼容，不主动改动其 tar.gz 行为。
+- 项目导出包内不再以项目名作为根目录，因为下载文件名已经包含项目标识。
+- 分类分割导出时，`.nii.gz` 文件名优先使用构件类别名。
+- API 默认不导出任何内容，避免未明确指定时产生大文件下载。
+- 当前系统的位姿模型为统一缩放；X/Y/Z 轴拉伸沿用现有工作区语义，即选择轴向后计算统一缩放以适配 DICOM 尺寸，而不是引入三轴非等比例缩放字段。
+
+## 风险点
+
+- ZIP 替代 tar.gz 会改变导出包扩展名和 MIME 类型，需要前端下载逻辑正确读取服务端文件名。
+- 导出进度条如果只依赖响应下载进度，在服务端生成阶段可能没有真实百分比，需要结合平滑进度和下载事件。
+- 批处理 API 上传文件可能较大，需要复用现有导入解包逻辑并在临时项目不入库时清理文件。
+- 自动配准可能因未指定骨骼构件或 DICOM/STL 不完整而失败，应返回可读错误。
+
+## 默认假设
+
+- 用户当前要修复的是“导出项目及结果”按钮生成的压缩包，不包括“下载原始 DICOM 归档”。
+- 外部调用 API 可接受 multipart/form-data，并可通过 `metadata` JSON 字段传入复杂参数。
+- 当 `recordProject=false` 且 `lock=true` 时，锁定没有项目库持久对象可附着，因此仅在 `recordProject=true` 或 `lock=true` 时保留项目记录。