# 模型文件存储与截图封面方案

2026-09-05。用户已确认，本方案已实施；验证结果见[截图封面实施报告](../model-cover-20260905/index.html)。以下保留方案与存储说明。

## 当前文件存储

GLB 经 `/api/tran/v1/content/projects/{id}/assets/upload` 上传到业务服务，完成格式和大小校验后，由业务服务提交至 `http://1.14.103.234:6180/fileapi/upload`。

文件按 `unreal-tran/model/年/月/日/随机ID.glb` 归档。当前 file_svc 部署配置根目录为 `/data/file_svc/files`，未登录远端核查实际磁盘目录。数据库保存 `fsvc://` 文件引用、大小、SHA-256、项目及版本关联；工程 JSON 保存节点、材质和动画。上传成功后删除本机临时文件。

应用内模型读取经过鉴权下载接口。远端 `/f/` 是静态读取地址；本次对两条测试资源的匿名 HEAD 均返回 200，不能将文件本体描述为完全私有。

## 建议的保存封面流程

1. 用户调整到希望保留的相机视角，点击“保存”。
2. 仅截取 3D 视口，沿用当前相机和模型姿态；临时隐藏选中框、变换控件和网格，截图后立即恢复，不截菜单和属性面板。
3. 同步复制已渲染画布，缩放并编码 JPEG，建议最长边 640 像素，避免黑图与过大图片。
4. 通过既有上传接口上传 IMAGE 资产，将上传票据、封面资产与工程放入同一保存队列，保存成功后更新 `coverUri`。
5. 列表通过受控图片下载解析为 Blob URL 展示，并在页面释放时回收；不把 `fsvc://` 直接当作图片地址，也不为读取缩略图逐条加载完整模型工程。

复用现有 `coverUri` 和 IMAGE 资产类型，无需新增表。固定封面资产编码用于当前版本替换，历史版本引用保留。

建议首次导入完成与手动保存时更新封面；每 30 秒的自动保存仅保存工程，避免持续生成图片。截图或上传失败时继续保存模型内容，保留旧封面并提示封面更新失败。

## 实施时需要补齐的接点

当前编辑器已有视口截图方法，但尚未连接保存流程。模型上传方法写死 MODEL_FILE，需要增加 IMAGE 分支；保存指纹需包含封面变化。列表当前直接使用 `img src=coverUri`，必须同步补图片资产读取映射及鉴权加载，才是完整功能。