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

实现方案-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。