MG-04-010 媒体上传接口

2026-10-15 用户确认：网关作为视频/图片物理媒体资源第一源头；测试素材支持图片、视频、音频上传和预览，长期保留、重复选用。产品项目、销售与用户权限领域不因此搬入网关。

持久化与访问

文件存入当前配置的 TOS primary-results 桶的 media-uploads/<kind>/<operation-id>/<sha256>。只有内容检查、PUT 和 HEAD 校验全部通过，才在 PostgreSQL media_uploads 登记。登记不可修改；不设置到期时间、不接入临时素材清理，不提供删除接口。任务提交沿用 material.Prepare，在 temporary-materials 桶创建请求自己的副本；任务失败清理不会删除原始上传。

同一次上传沿用 UUID；相同 UUID、类型与文件 SHA256 返回原登记，不创建第二条记录；不同文件返回 409。TOS I/O 不进入数据库事务；TOS 已写而 DB 写失败时，同 UUID 可以重试，未新增自动孤儿对象删除策略。记录只存 bucket/object key 与校验元数据，浏览器只收到不透明引用和同源预览地址。长期记录存在时 migration 32 不允许 destructive down；应用回滚保留 schema 与对象。

管理接口

以下接口统一处于 /admin/v1 管理员会话/管理员服务 Key 边界；平台服务 Key 无权访问管理素材库。浏览器使用 /backend 同源 facade，写请求必须携带已有 CSRF token 和 local-client header。

上传响应：id、kind、filename、content_type、byte_size、sha256、duration_ms、width、height、created_at、reference（upload-ref:media_<32位UUID>）、preview_url。单文件沿用现有参考素材大小上限：图片 12 MiB、视频 48 MiB、音频 16 MiB。实际流类型与时长用本地 ffprobe 验证；SVG/HTML 不接受。选择数量、合计数量、参考视频总时长等仍按当前规格及现有 material 域校验。

测试页面

预设、最大参数、自定义参数保持现有能力约束。预设使用源码内的第一方合成素材，选择素材/最大参数预设时先完成 TOS 登记，再把内部引用填入参数；稳定 UUID + SHA256 防止重复登记，不依赖外部演示域名。视频每段 3 秒，三段合计 9 秒；音频各 3 秒；所有预设字节不可变，替换素材必须新建版本。每种素材支持上传、同源预览、从素材库选用和导入 HTTPS。预设链接可以手动导入预览；点击提交时尚未导入的链接先转 TOS，再冻结原测试 operation 和参数。移除素材仅取消本次选用。首/尾帧也使用同一选择组件。

图片用 img，视频用 video controls，音频用 audio controls；均读取鉴权同源 TOS 内容。长效对象引用由现有 SourceResolver.Uploads 解析，在提交时复制为任务素材。客户端不持有 TOS 凭据，不持久化签名 URL。

上游结果链路核对

现有 internal/video/result.Processor 把每个成功 Provider 输出交给 assets.Transfer 后才完成成功 Attempt；internal/image/result.Service 经 Stage/PublishAttempt（或历史 Transfer）发布持久对象。两者的输出内容均通过自身内容接口交付。MG-MEDIA-01 保留这些成熟转存与恢复实现，不新增只返回 Provider 临时 URL 的路径，也不启用尚未验收的图片生成或音频生成入口。测试上传/播放音频属于媒体素材支持。