# 需求分析-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` 时保留项目记录。