REVOXELSEG_DICOM/工程分析/实现方案-2026-05-21-00-43-44.md

实现方案-2026-05-21-00-43-44

实现方案文档路径

工程分析/实现方案-2026-05-21-00-43-44.md

修改目标

• 复现 3279-STL.zip 导入时的 422 错误，获取具体失败原因。
• 修复 ZIP 内 STL 解压/筛选/写入逻辑，使该压缩包可导入。
• 优化导入失败 UI，将错误状态和原因显示在顶部导入进度区域。
• 补充测试记录和经验记录。

涉及路径

• WebSite/server.ts
• WebSite/src/components/ProjectLibrary.tsx
• 工程分析/经验记录.md

技术路线

1. 使用 curl -F files=@3279-STL.zip 对现有接口复现错误，查看响应体。
2. 检查 AdmZip 解包结果、ZIP 条目大小和写入逻辑。
3. 如果问题来自大 ZIP 一次性 entry.getData() 导致内存或写入失败，则改为按条目流式/逐条写入目标目录，减少内存峰值。
4. 如果问题来自文件名扩展名、编码或路径处理，则修正筛选和安全文件名逻辑。
5. 前端导入状态增加 failed phase，错误时保留进度卡并展示错误文案。

执行步骤

1. 创建本次工程分析文档。
2. 本地复现 422，记录响应。
3. 修改后端 ZIP 导入逻辑和前端错误反馈。
4. 执行 npm run lint、npm run build。
5. 用 3279-STL.zip 对临时项目实际导入验证。
6. 追加经验记录，提交推送 Gitea，重新部署。

兼容性与回滚方案

• 若 AdmZip 对该 ZIP 仍不稳定，可增加系统 unzip fallback 或改用更适合流式解压的库。
• 前端错误卡只影响导入反馈，不影响其他页面。
• 导入失败时不更新项目状态，避免半成品资产进入项目库。

预计文件变更

• 后端 1 个、前端组件 1 个、工程分析文档 4 个。

提交与部署策略

• 不提交 3279-STL.zip 和解压资产。
• commit message 包含 2026-05-21-00-43-44 与“修复 ZIP STL 导入失败”。
• 部署后验证 /api/health、首页以及 ZIP 导入结果。