# 实现方案-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 导入结果。