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。