素材入库（footage-ingest）
1. 入库五件事（缺一不算入库完成）
| 项 | 口径 | 落库字段 |
|---|
| 内容指纹 | 文件 sha256（整文件，不是抽帧哈希） | asset.sha256 |
| 规格 | ffprobe：时长/画幅/帧率/音轨/声道/码率 | asset.durationSeconds 等 |
| 授权与用途 | rights.status + rights.declaredUsage[] | 见下方授权口径 |
| 代理文件 | H.264 720p 或 1080p 低码率代理 + 缩略图 | asset.proxyPath |
| 索引条目 | 标签/实体/可用性/复用建议 | media_index_entry |
2. 幂等规则
- 同一 sha256 再次上传 → 命中既有资产，不新建记录；只允许补空字段（title/tags/授权缺失项）。
- 同名不同内容 → 视为新资产，文件名加序号（禁止覆盖同名文件）。
- 中断可续：入库各步之间以
footage. 事件留痕，重跑从最后成功的步骤继续。
3. 授权与用途口径（G-ED2 前置）
| 状态 | 允许动作 |
|---|
cleared + 用途含 timeline-source | 可剪进成片、可导出封面 |
cleared + 仅 cover/thumbnail | 只能做封面/缩略图，不得进时间线 |
cleared + 仅 reference-only | 只能作为风格/构图参考，不得出现在成片画面 |
pending / restricted / unknown | 只入库登记，不得进片；缺字段按违规处理（fail-closed） |
授权口径引用素材提供方的事实声明，素材馆员不得自行认定版权归属。
4. 代理与缩略图参数（默认值，可覆盖）
代理： ffmpeg -i <src> -vf scale=-2:720 -c:v libx264 -preset veryfast -crf 24 \
-c:a aac -ar 48000 -ac 2 -movflags +faststart <proxy.mp4>
缩略图： 1s 处单帧（不足 1s 取首帧）→ scale=640:-2 → <thumb.jpg>
- 代理只用于预览与快速粗剪；最终合成使用原件（避免二次压缩）。
- 转码失败必须显式报错（缺 ffmpeg / 源文件不可读 / 磁盘不足），不得产生 0 字节假产物。
5. 自检清单
6. 失败模式
| 症状 | 首查 | 处置 |
|---|
| 同一素材出现两条记录 | sha256 计算方式不一致（整文件 vs 分段） | 统一整文件 sha256；按内容去重后合并标签 |
| 代理能播但合成报错 | 代理被误当源文件 | 合成阶段强制使用 asset.localPath 原件路径 |
| 素材进片后被判违规 | 授权用途未登记 | 回退该片，补登记授权后重新出时间轴（保留旧版本） |
| 抽帧图全黑 | 源为 HDR/色彩空间异常 | 转码时加 -vf zscale=t=linear:npl=100,tonemap=hable,zscale=p=bt709 兜底并记录 |