视频¶
源码：
src/backend/db/models/video.py返回 总览 字段表格式：字段 | 中文名 | 类型 | 可空 | 作用
提示词组挂在 fabric_materials（产品面料）上；video_categories 为部分遗留树。
ER¶
erDiagram
fabric_materials ||--o{ video_prompt_groups : materials
fabric_materials ||--o{ video_scripts : optional
fabric_materials ||--o{ video_test_runs : optional
video_prompt_groups ||--o{ video_prompt_segments : segments
video_prompt_groups ||--o{ video_test_runs : used
video_scripts ||--o{ video_test_runs : script
video_test_runs ||--o{ video_dead_letters : dead
video_categories ||--o{ video_categories : parent
video_categories — 视频品类树（遗留）¶
parent_id 为空表示品类，非空表示下层（历史「材质」节点）。新链路提示词组已改挂 fabric_materials。
| 字段 | 中文名 | 类型 | 可空 | 作用 |
|---|---|---|---|---|
| id | 品类 ID | UUID | NO | 主键 |
| name | 名称 | String(100) | NO | 品类或下层节点展示名 |
| parent_id | 父节点 ID | UUID | YES | FK→video_categories.id CASCADE；空=品类，否则为下层 |
| sort_order | 排序权重 | SmallInteger | NO | 同级排序；默认 0 |
| created_at | 创建时间 | timestamptz | NO | 行创建时间 |
| updated_at | 更新时间 | timestamptz | NO | 行最后修改时间 |
video_prompt_groups — 提示词组¶
某材质下的一组提示词；同组 seg1/2/3 不混用。
约束：UniqueConstraint(video_type, material_id, group_name) → uq_video_prompt_group_material_name。
| 字段 | 中文名 | 类型 | 可空 | 作用 |
|---|---|---|---|---|
| id | 提示词组 ID | UUID | NO | 主键 |
| video_type | 视频类型 | String(20) | NO | grass / drama |
| material_id | 面料材质 ID | UUID | NO | FK→fabric_materials.id CASCADE；提示词组挂靠材质 |
| group_name | 组名 | String(100) | NO | 同材质、同视频类型下唯一；同组分段不混用 |
| is_active | 是否启用 | Boolean | NO | false 时不可被新试跑选用；默认 true |
| used_count | 使用次数 | Integer | NO | 被试跑选用的累计次数；默认 0 |
| created_at | 创建时间 | timestamptz | NO | 行创建时间 |
| updated_at | 更新时间 | timestamptz | NO | 行最后修改时间 |
video_prompt_segments — 分段提示词¶
提示词组内单段（seg1 / seg2 / seg3）。
约束：UniqueConstraint(group_id, segment) → uq_video_prompt_segment。
| 字段 | 中文名 | 类型 | 可空 | 作用 |
|---|---|---|---|---|
| id | 分段 ID | UUID | NO | 主键 |
| group_id | 提示词组 ID | UUID | NO | FK→video_prompt_groups.id CASCADE；所属组 |
| segment | 分段标识 | String(10) | NO | seg1 / seg2 / seg3；组内唯一 |
| frame_prompt | 首帧提示词 | Text | NO | 生成首帧图用的提示词；默认空串 |
| video_prompt | 视频提示词 | Text | NO | 生成视频段用的提示词；默认空串 |
| created_at | 创建时间 | timestamptz | NO | 行创建时间 |
| updated_at | 更新时间 | timestamptz | NO | 行最后修改时间 |
video_scripts — 共用剧本库¶
剧情（drama）共用剧本，可被多材质试跑复用。
部分唯一索引：uq_video_script_type_name_active on (video_type, name) WHERE deleted_at IS NULL。
| 字段 | 中文名 | 类型 | 可空 | 作用 |
|---|---|---|---|---|
| id | 剧本 ID | UUID | NO | 主键 |
| video_type | 视频类型 | String(20) | NO | 默认 drama；预留 grass |
| name | 剧本名称 | String(100) | NO | 展示名（如「校门口闺蜜」）；未软删时与 video_type 唯一 |
| material_id | 面料材质 ID | UUID | YES | FK→fabric_materials.id SET NULL；历史绑定字段，共用库后可空 |
| script_text | 剧本文本 | Text | NO | 原始剧本正文 |
| parsed_cache | 解析缓存 | JSONB | YES | 剧本结构化解析结果缓存 |
| sort_order | 排序权重 | SmallInteger | NO | 列表排序；默认 0 |
| status | 启用状态 | SmallInteger | NO | 1=启用 0=停用；默认 1 |
| deleted_at | 删除时间 | timestamptz | YES | 软删进回收站；非空表示已删除 |
| created_at | 创建时间 | timestamptz | NO | 行创建时间 |
| updated_at | 更新时间 | timestamptz | NO | 行最后修改时间 |
video_test_runs — 试跑 / 流水线¶
Admin 视频试跑与流水线进度记录；C 端用户字段预留。
| 字段 | 中文名 | 类型 | 可空 | 作用 |
|---|---|---|---|---|
| id | 试跑 ID | UUID | NO | 主键 |
| video_type | 视频类型 | String(20) | NO | grass / drama 等业务类型 |
| material_id | 面料材质 ID | UUID | YES | FK→fabric_materials.id SET NULL；试跑挂靠材质 |
| script_id | 剧本 ID | UUID | YES | FK→video_scripts.id SET NULL；剧情试跑选用剧本 |
| group_id | 提示词组 ID | UUID | YES | FK→video_prompt_groups.id SET NULL；选用的提示词组 |
| duration | 目标时长 | Integer | NO | 目标视频时长（秒）；默认 30；种草 I2V 透传；Metaso 限制 4–15 |
| resolution | I2V 分辨率 | String(20) | YES | 图生视频分辨率（如 768P/2K/720p）；空则 Activity 回落默认 |
| ratio | I2V 画幅比 | String(20) | YES | 图生视频画幅比（如 16:9/adaptive）；空则 Activity 回落默认 |
| status | 流水线状态 | String(32) | NO | 默认 pending；pending / generating_images / first_frames_ready / generating_videos / merging / done / failed（兼容旧 generating） |
| progress | 进度百分比 | SmallInteger | NO | 0–100 进度；默认 0 |
| upload_image_key | 上传图键 | String(500) | YES | 用户/运营上传参考图的 OSS object_key |
| segment_statuses | 分段状态 | JSONB | YES | 各分段当前状态列表 |
| material_statuses | 材质状态 | JSONB | YES | 多材质试跑时各材质进度/状态 |
| segment_labels | 分段标签 | JSONB | YES | 分段展示标签列表 |
| images | 生成图片 | JSONB | YES | 各段首帧/中间图结果元数据 |
| videos | 生成视频 | JSONB | YES | 各段视频结果元数据 |
| final_video_key | 成片键 | String(500) | YES | 合并后最终视频 OSS object_key |
| used_prompts | 所用提示词 | JSONB | YES | 旧版为 list[seg]；v2 为 dict{"format":"v2", characters, scenes, segments} |
| error_log | 错误日志 | Text | YES | 失败原因与诊断文本 |
| image_model_id | 生图模型 ID | UUID | YES | 无 FK；本次试跑选用的图像模型 |
| video_model_id | 视频模型 ID | UUID | YES | 无 FK；本次试跑选用的视频模型 |
| created_by | 创建人 ID | UUID | YES | 无 FK；启动试跑的 Admin/操作者标识 |
| operator_phone | 操作者手机号 | String(20) | YES | Admin 操作者手机号快照（审计/Temporal） |
| user_id | 用户 ID | UUID | YES | 无 FK；C 端用户预留；Admin 试跑可空 |
| phone | 用户手机号 | String(20) | YES | C 端用户手机号快照预留 |
| events | 事件日志 | JSONB | YES | 进度/重试事件；保留最近约 50 条，供轮询与审计 |
| created_at | 创建时间 | timestamptz | NO | 行创建时间 |
| updated_at | 更新时间 | timestamptz | NO | 行最后修改时间 |
video_dead_letters — 死信¶
上游重试耗尽后入库，供人工排查或重新入队。
| 字段 | 中文名 | 类型 | 可空 | 作用 |
|---|---|---|---|---|
| id | 死信 ID | UUID | NO | 主键 |
| run_id | 试跑 ID | UUID | NO | FK→video_test_runs.id CASCADE；有索引；归属试跑 |
| stage | 失败阶段 | String(64) | NO | 失败所处流水线阶段；默认 execute |
| payload | 载荷快照 | JSONB | YES | 失败时任务/消息载荷，便于重放 |
| error | 错误信息 | Text | NO | 失败原因文本 |
| retry_count | 重试次数 | Integer | NO | 入死信前已重试次数；默认 0 |
| status | 死信状态 | String(32) | NO | 默认 open；open / requeued / discarded |
| created_at | 创建时间 | timestamptz | NO | 行创建时间 |
| updated_at | 更新时间 | timestamptz | NO | 行最后修改时间 |