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

需求分析-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 模型”页签。