2026-05-21-00-05-04 导入进度与压缩包支持

工程分析/需求分析-2026-05-21-00-05-04.md

@@ -0,0 +1,50 @@
+# 需求分析-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`。