# 实现方案-2026-05-21-00-05-04

## 实现方案文档路径

`工程分析/实现方案-2026-05-21-00-05-04.md`

## 修改目标

- 项目库导入 DICOM/STL 时显示上传进度、文件数量和体积。
- 将项目资产导入从 base64 JSON 改为 multipart 表单上传，降低浏览器内存占用。
- 后端接收普通文件和压缩包，并在服务端展开 ZIP/TAR/TAR.GZ/TGZ/GZ。
- 导入完成后继续刷新项目状态、清理缓存、保留覆盖确认逻辑。
- 对 3D 模型导入崩溃原因给出技术修复：避免 `Promise.all(fileToBase64)` 和巨型 JSON body。

## 涉及路径

- `WebSite/src/lib/api.ts`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/server.ts`
- `WebSite/package.json`
- `WebSite/package-lock.json`
- `工程分析/经验记录.md`

## 技术路线

1. 引入 `multer` 接收 multipart 文件，使用内存上传缓冲后统一写入项目资产目录。
2. 引入 `adm-zip` 解压 ZIP；TAR/TAR.GZ/TGZ 使用 Node `zlib` 与简单 tar header 解析；单文件 GZ 解压为原文件。
3. 后端新增导入文件展开函数，统一过滤 DICOM/STL 目标扩展名，并防止路径穿越。
4. 前端新增 `uploadProjectAssets`，使用 `XMLHttpRequest.upload.onprogress` 返回上传百分比。
5. 项目库增加导入进度状态和紧凑进度条，上传完成后显示服务器解析/解压阶段。
6. 文件选择器 accept 增加 `.zip,.tar,.tar.gz,.tgz,.gz`。

## 执行步骤

1. 写入需求、实现、测试方案。
2. 安装 multipart 和 zip 解析依赖。
3. 修改后端导入接口，兼容新的 multipart 上传。
4. 修改前端 API 封装和项目库导入 UI。
5. 执行 `npm run lint`、`npm run build`。
6. 验证健康检查、首页响应和示例项目状态。
7. 追加经验记录，提交推送 Gitea，重新部署服务。

## 兼容性与回滚方案

- 若 multipart 上传出现问题，可临时保留 JSON body 解析分支作为兼容回退。
- 若压缩包解析失败，应返回明确错误，不写入半成品项目状态。
- 如新增依赖不可用，可回退为仅支持普通文件和 TAR.GZ，ZIP 支持后续补齐。

## 预计文件变更

- 前端 API 1 个、项目库组件 1 个、后端服务 1 个、依赖清单 2 个、工程分析文档 4 个。

## 提交与部署策略

- 只暂存本次相关代码和工程分析文档。
- commit message 包含 `2026-05-21-00-05-04` 与“导入进度与压缩包支持”。
- 重新构建并使用 `tmux` 会话 `revoxelseg-dicom` 运行 4000 服务。