52 lines
2.0 KiB
Markdown
52 lines
2.0 KiB
Markdown
# 实现方案-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 导入结果。
|