# 需求分析-2026-05-21-00-05-04

## 开始时间

2026-05-21-00-05-04

## 原始需求摘要

1. 项目库导入 DICOM 影像、3D 模型时增加进度条。
2. 导入时允许选择 ZIP 或其他常见压缩格式，方便传输批量 DICOM/STL。
3. 导入 3D 模型时出现 Chrome `Render process gone / Out of Memory`，需要定位原因并修复。

## 业务目标

- 让大体量医学影像和 STL 构件导入过程有明确进度反馈。
- 支持用户用压缩包一次性传输多文件，减少文件选择和网络传输压力。
- 避免前端在大文件导入时因 base64 转换和 JSON 请求造成浏览器内存崩溃。

## 输入与输出

- 输入：DICOM 文件、STL 文件、ZIP/TAR/TAR.GZ/TGZ/GZ 等压缩文件。
- 输出：项目级 DICOM/STL 上传目录中的解包文件、更新后的项目状态、导入进度条、导入成功/失败反馈。

## 影响范围

- `WebSite/src/components/ProjectLibrary.tsx`：导入入口、进度条、文件选择 accept、导入状态。
- `WebSite/src/lib/api.ts`：新增带上传进度的 multipart 导入 API。
- `WebSite/server.ts`：新增 multipart 文件接收、压缩包展开、导入文件筛选与项目状态更新。
- `WebSite/package.json`、`WebSite/package-lock.json`：新增 multipart/zip 解析依赖。
- `工程分析/经验记录.md`：记录本次导入链路经验。

## 关键约束

- 上传资产仍必须写入 `WebSite/data/uploads/<projectId>/DICOM|STL`，不能覆盖默认 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/`。
- 大文件导入不能再在浏览器中整包 base64 化。
- 压缩包解压必须防止路径穿越，不能写出目标目录。
- 导入后需要清理项目预览缓存，避免继续使用旧 DICOM/STL。

## 风险点

- ZIP 内可能包含多层目录、中文文件名、无扩展 DICOM 文件或无关文件，需要筛选可导入文件。
- TAR.GZ 解包需要处理普通文件、目录和路径安全。
- 上传进度只能覆盖网络上传阶段，服务端解压/解析阶段需要用“处理中”状态承接。
- 大 STL 导入后如果立即按实体精度加载过多预览，仍可能造成前端渲染压力。

## 默认假设

- “其他常见压缩格式”优先支持 `.zip`、`.tar`、`.tar.gz`、`.tgz`，并支持单文件 `.gz`。
- DICOM 导入接受 `.dcm`、`.dicom`，同时保留压缩包中无扩展 DICOM 的识别尝试空间。
- 3D 模型导入当前仍以 STL 为主，压缩包中只提取 `.stl`。