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

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