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

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

@@ -0,0 +1,51 @@
+# 实现方案-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 导入结果。