Job
一个视频任务。前端维护多个 jobs[]，当前激活的是 activeJobId。URL 查询参数会持久化多个 job。
Job {
id, document_id, source_kind, workflow_mode, storage_prefix,
url, status, progress, message,
video_url, source_audio_url, duration, width, height,
frames: KeyFrame[],
transcript: TranscriptSegment[],
audio_script: AudioScript,
storyboard_images?: StoryboardImage[],
product_refs?: ProductRefStateItem[]
}
Document / DB
文档是业务归类顶层，不等于物理文件。当前一条 TK 链接或一次上传视频默认生成一个 document；不同来源或模式通过 source_kind 和 workflow_mode 区分。数据库只保存元数据、状态和文件索引，不保存视频/图片二进制。
documents {
id, title, source_kind, workflow_mode,
source_url, primary_job_id, status,
storage_prefix, metadata_json,
created_at, updated_at
}
jobs {
id, document_id, source_kind, workflow_mode,
source_url, status, progress,
storage_path, state_path,
frame_count, video_count
}
media_assets {
id, document_id, job_id,
kind: video | audio | image,
role: source_video | keyframe | product_ref | subject_asset | first_frame | last_frame | generated_video,
path, url, frame_index, metadata_json
}
KeyFrame
关键帧是整个产品的核心单位。index 是稳定 ID，手动加帧后不连续，不能用数组下标代替。
KeyFrame {
index, timestamp, url,
description,
transparent_human_score,
cleaned_url, cleaned_applied,
quality_report,
scene_assets: SceneAsset[],
elements: KeyElement[],
storyboard: StoryboardScene,
generated_images: GeneratedImage[]
}
TransparentHumanFrameScore
透明骨架人主题的抽帧验收结果。只有 target=transparent_human 时会在抽帧阶段写入；普通抽帧目标不要求该字段。
TransparentHumanFrameScore {
transparent_body_score: 0-25,
skeleton_visible_score: 0-25,
human_prominence_score: 0-15,
clarity_score: 0-15,
commercial_style_score: 0-10,
product_usefulness_score: 0-10,
total_score,
qualified,
reject_reason
}
KeyElement
从关键帧识别结果里确认出来的主体候选。当前素材准备流程只保留一个统一主体；多张关键帧通过 source_frame_indices 作为该主体的参考帧。
KeyElement {
id,
name_zh, name_en, position,
source: auto | manual | region,
region,
cutouts: string[],
cutout_id,
subject_kind: object | living,
subject_assets: SubjectAsset[]
}
AudioScript
第一步音频解析的结构化产物。pipeline_transcribe 提取 audio.wav 后先保存原始转写、中文翻译、讲话人画像、口播节奏和背景音乐/环境声/音效分析。rewritten_text、voice_url 等字段仍保留给后续新配音阶段，当前第一步不默认写入。
AudioScript {
status: idle | rewriting | completed | failed,
source_text,
source_zh,
rewritten_text,
speaker_profile,
rhythm_profile,
background_audio_profile,
product_brief,
rewrite_model,
voice_provider: azure_openai,
voice_model,
voice_id,
voice_url,
error
}
SceneAsset / SubjectAsset
画面工作台素材准备阶段生成的组图资产。实际图片保存在 jobs/<jobId>/assets，可作为 asset 类型复制到分镜槽位。
SceneAsset {
id, label, url,
width, height, quality, size,
scene_mode: remove_subject | similar | style,
scene_style,
quality_report
}
SubjectAsset {
id, view, label, url,
background: white | black,
width, height, size,
source_frame_indices[]
}
ProductLibraryItem
内置 SKG 白底图库条目。实际图片保存在 api/product_library/skg-products/images，被选中时会复制到 jobs/<jobId>/assets，再以普通 ImageRef(kind="asset") 进入产品参考组。
ProductLibraryItem {
id, handle, title, product_type,
image_index, filename, url,
width, height,
white_score,
source_path,
tags[]
}
ImageRef.asset_meta
产品图上传或从产品图库复制到 job 时，后端会把原图转为统一 AI 工作副本，避免超高清原图拖慢识别、生图和生视频链路。黑底/白底不强行改色；只有透明底会铺白。前端用该字段展示工作图尺寸、自动转换动作和分辨率风险。
asset_meta {
standard: "AI工作副本：最长边≤1600px，建议长边≥900px，短边≥600px，JPEG q92",
original_width, original_height,
width, height,
original_bytes, work_bytes,
max_side, min_long_side, min_short_side, quality,
actions[],
warnings[],
normalized
}
ProductViewAnalysisItem
产品素材池识别结果。它不判断不同产品身份，只服务同一款挂脖肩颈按摩仪的生视频选图和方向约束；左/右按佩戴者身体左右，不按图片左右。前端会把上传图、识别标注、AI 补图、备注和删除结果写入 Job.product_refs，后端保存到 state.json，避免刷新、热更新或服务重启后丢失产品素材池。
ProductViewAnalysisItem {
index,
view: front | left_45 | right_45 | side_thickness | inner_contacts | back_bottom,
background,
use_tags[],
orientation: {
product_left, product_right,
top, bottom,
inner_side, outer_side,
opening_direction
},
landmarks[],
note,
risk,
confidence
}
ProductRefStateItem {
id,
ref: ImageRef,
view,
background,
useTags[],
orientation,
landmarks[],
note,
risk,
source: upload | ai,
assetMeta,
confidence
}
ProductFusionShot
产品融合镜头组的单行数据。每个关键帧最多 6 行，用户选择一个内置角色后只微调场景/产品使用/享受描述和秒数；四张桌面 SKG 产品角度图会在顶部显式展示为真实产品真源，所选角色 7 张参考图作为人物身份参考，生成时作为 Seedance 参考图提交。
ProductFusionShot {
id,
first_image,
last_image,
product_images[4],
action_text,
duration,
image_model: gpt-image-2,
video_model: seedance,
// legacy: product_image, person_image, product_region, scene_image, guide_image
}
StoryboardScene
分镜编排结果，不是复刻说明。当前主流程里 first_image/last_image 只接受生成后的 asset 首尾帧；旧 keyframe 首尾帧引用会被前端忽略。subject_images 保存相似主体白底视图，product_images 保存该行挑选的产品参考。
StoryboardScene {
duration,
visual_mode: person_only | person_product | product_only | environment,
needs_product,
needs_subject,
first_frame_plan,
last_frame_plan,
product_placement,
first_image,
last_image,
product_images[],
subject_images[],
subject_image,
scene_image,
product_image,
action_image,
subject,
product,
scene,
action
}