2026-05-21-00-43-44 修复ZIP STL导入反馈

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

@@ -0,0 +1,46 @@
+# 需求分析-2026-05-21-00-43-44
+
+## 开始时间
+
+2026-05-21-00-43-44
+
+## 原始需求摘要
+
+1. 用户上传 `3279-STL.zip` 后项目库没有明显反应。
+2. 浏览器控制台显示 `/api/projects/:projectId/import-assets` 返回 `422 Unprocessable Entity`。
+3. 用户已将 `3279-STL.zip` 放在当前项目目录，需要定位压缩包导入失败原因并修复。
+
+## 业务目标
+
+- 让包含多个 STL 的 ZIP 压缩包可以稳定导入项目库 3D 模型。
+- 导入失败时前端必须给出显眼、可读的错误反馈，而不是让用户感觉“没有反应”。
+- 后端返回具体错误原因，便于定位压缩包、模型文件或服务器处理问题。
+
+## 输入与输出
+
+- 输入：项目根目录中的 `3279-STL.zip`，项目库 3D 模型导入动作。
+- 输出：成功导入 ZIP 内 STL 模型并更新项目 `modelCount/stlFiles`，或在失败时展示明确原因。
+
+## 影响范围
+
+- `WebSite/server.ts`：ZIP 解压、文件名处理、STL 筛选、错误信息。
+- `WebSite/src/components/ProjectLibrary.tsx`：导入错误提示可见性、导入进度失败状态。
+- `WebSite/src/lib/api.ts`：错误消息解析。
+- `工程分析/经验记录.md`：记录本次压缩包导入经验。
+
+## 关键约束
+
+- 不把 `3279-STL.zip` 或解压后的大模型资产纳入 Git 提交。
+- 继续保证导入只写入项目级上传目录，不影响默认演示数据。
+- 不回退到浏览器 base64 导入。
+
+## 风险点
+
+- ZIP 内 STL 总体积较大，服务端一次性解压到内存可能产生压力。
+- ZIP 文件名或条目可能存在编码、路径、目录层级差异。
+- 导入成功后项目库预览如果一次性加载过多大 STL，也可能造成浏览器压力，需要至少保证导入链路稳定。
+
+## 默认假设
+
+- 当前 422 由后端解压或写入阶段抛错造成，而不是项目不存在。
+- 用户截图中的 ZIP 内条目均为 `.stl`，导入目标处于“3D 模型”页签。