# 实现方案-2026-05-20-02-32-47

## 实现方案文档路径

`工程分析/实现方案-2026-05-20-02-32-47.md`

## 修改目标

将顶部“导出全部 NII.GZ”改为一次性下载 `.tar.gz` 导出包；分割影像导出时自动附带 label/category 映射 JSON，并支持“所有类别/可见类别”范围选择。

## 涉及路径

- `WebSite/server.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/需求分析-2026-05-20-02-32-47.md`
- `工程分析/实现方案-2026-05-20-02-32-47.md`
- `工程分析/测试方案-2026-05-20-02-32-47.md`
- `工程分析/经验记录.md`

## 技术路线

1. 后端扩展分割生成参数：
   - 增加 `SegmentationExportScope = all | visible`。
   - `createSegmentationData` 按 scope 决定是否跳过隐藏构件。
2. 后端新增类别映射 JSON：
   - 根据 `project.stlFiles` 和 `project.moduleStyles` 生成 label/name/fileName/color/opacity/visible。
   - scope 为 visible 时只包含可见构件。
3. 后端新增导出包接口：
   - `GET /api/projects/:projectId/export-bundle`
   - 参数：`targets=dicom,segmentation,pose`、`format=nii.gz`、`pose=...`、`segmentationScope=visible|all`
   - 使用现有 tar header 工具封装为 `.tar.gz`。
4. 前端 API：
   - 新增 `downloadProjectExportBundle`。
   - 保留单个分割 NII/NII.GZ 下载兼容。
5. 前端菜单：
   - “导出所选”改为下载单个压缩包。
   - 增加分割类别范围的 segmented control。
   - 仅选中分割影像时显示类别范围选项。

## 执行步骤

- 新增后端 tar entry 通用函数和 bundle 生成函数。
- 修改 NIfTI 分割生成函数支持 scope。
- 新增 label map JSON 生成逻辑。
- 调整前端 API 和导出菜单。
- 执行 `npm run lint`、`npm run build`。
- 用临时/正式服务验证 bundle 接口返回 `.tar.gz`，并检查包内文件名。
- 追加经验记录、commit、push、部署。

## 兼容性与回滚方案

- `/export-nifti` 与 `/export-mask` 保持可用。
- 单独分割导出默认沿用 visible scope。
- 若 bundle 导出异常，可回滚到多文件直链下载。

## 预计文件变更

- `server.ts`：新增 bundle、分割 scope、类别映射 JSON。
- `api.ts`：新增 bundle 下载 API。
- `ReverseWorkspace.tsx`：导出菜单增加 scope 选择并调用 bundle。
- 工程分析文档：新增本次文档，更新经验记录。

## 提交与部署策略

- Commit message：`2026-05-20-02-32-47 支持NII导出包与分割类别范围`
- 显式暂存本次相关文件，避免提交历史删除状态。
- 推送到 Gitea `origin/main`，并使用 `tmux` 会话 `revoxelseg-dicom` 重新部署。