47 lines
1.9 KiB
Markdown
47 lines
1.9 KiB
Markdown
# 需求分析-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 模型”页签。
|