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

3.4 KiB Raw Blame History Unescape Escape