Refine seller store implementation

docs/v2.1/api.md

@@ -101,7 +101,14 @@
 
 `POST /api/assets/watermark/remove` 当前仍为短时同步操作，返回 `{ "updated_ids": [], "failed": [] }`。两接口均只保留原图和当前展示版本：重新加水印会在数据库提交后删除旧水印文件；前端展示、单张下载与导出均使用 `stored_url`。
 
-## 8. 导出与代理（Phase B / D）
+## 8. 商品轮播视频
+
+- `POST /api/products/{product_id}/video-jobs`：请求 `{ "asset_ids": ["uuid", "uuid"] }`，按传入顺序选择当前商品的 2–5 张已转存图片，立即返回 `{ "job_id": "uuid" }`。服务端只接受素材 ID，不接受任意图片 URL。
+- `GET /api/products/{product_id}/video-jobs`、`GET /api/video-jobs/{job_id}`：读取任务和成片状态；`POST /api/video-jobs/{job_id}/cancel` 会取消并立即清理任务记录，`POST /api/video-jobs/{job_id}/retry` 重试失败任务，`DELETE /api/video-jobs/{job_id}` 删除成片及记录，`GET /api/video-jobs/{job_id}/download` 下载 MP4。
+- Worker 使用 FFmpeg 合成无音轨轮播视频：AI 生成图在前端选择器中优先展示；支持 2–5 张，按 4.5 / 3.5 / 3.0 / 2.8 秒单图停留并使用 0.35 秒淡入淡出。默认输出为 `810×1080`、`30 fps`、`H.264`、`yuv420p`、最大 45 MB，结果存入 `products/{product_id}/videos/{job_id}/result.mp4`。
+- 需要系统安装 `ffmpeg` 与 `ffprobe`（Ubuntu：`apt install -y ffmpeg`）；路径和大小/超时限制可通过 `VIDEO_*` 环境变量覆盖。任务复用 `background_jobs`，无需新增视频业务表；进行中、失败和已完成成片可在刷新后继续查看，取消会立即移除任务及临时文件，不保留记录。
+
+## 9. 导出与代理（Phase B / D）
 
 | 接口 | 方法 | Req | Res |
 |---|---|---|---|
@@ -111,11 +118,15 @@
 
 图片资源上限：默认单张上传/远程下载 20 MB；一次导出最多 50 张，ZIP 内源图片总量与成品 ZIP 均最多 200 MB。超过限制返回 HTTP `413` 及可读错误提示；ZIP 超过 2 MB 自动写入临时磁盘，并以分块响应下载。
 
-## 9. 采集相关（Phase C 使用，均已实现）
+图片校验与元数据：图片上传、采集转存和 AI 生成图写入素材库时，服务端以实际字节识别 JPEG、PNG、WebP、GIF 或 BMP，不信任 URL 后缀和上传声明的 MIME。解码失败或不支持的格式返回/记录为失败；默认限制为 40,000,000 像素（`IMAGE_MAX_PIXELS`），并记录 `product_assets.width`、`height`。静态图片若带 EXIF 方向，会在落库前纠正并移除该方向标记；动画图不重编码，以避免丢帧。`POST /api/materials/bytes` 成功响应会额外返回 `width`、`height`，不合规图片返回 `422`。
+
+远程图片安全规则：`/api/proxy-image`、采集图转存、AI 参考图及远程导出统一只请求公网 `http(s)` 地址；`localhost`、回环、内网、链路本地、多播和其他保留 IP 会返回 `400`。重定向不会自动跟随：服务端最多跟随 3 跳，并在每一跳重新解析和校验目标地址。已转存的本项目 `/media/...` 素材直接读取本地磁盘，不经过 HTTP 回环请求。下载仍受 `IMAGE_DOWNLOAD_MAX_BYTES` 限制，连接/读写/总超时与重定向次数可通过 `IMAGE_DOWNLOAD_CONNECT_TIMEOUT`、`IMAGE_DOWNLOAD_READ_TIMEOUT`、`IMAGE_DOWNLOAD_TOTAL_TIMEOUT`、`IMAGE_DOWNLOAD_MAX_REDIRECTS` 配置；下载超时返回 `504`。
+
+## 10. 采集相关（Phase C 使用，均已实现）
 
 - `POST /api/materials`：插件上传采集结果；**响应含 `product_id`**（插件用于打开 `/trial/{id}`）。
 - `GET /api/collected?platform=&itemId=`：采集前查重。
 
-## 10. 冻结接口（不投入，保留代码）
+## 11. 冻结接口（不投入，保留代码）
 
 `/api/publish/*`、`/api/shops/*`、`/api/categories/*`——Ozon API 直传链路（D1）。