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