AI 营销视频开发交付说明
交付基线：CR-20260823-001
产品 PRD / 前端契约：v3.0
Prompt：0.7-candidate，未接生产运行时
当前状态：Freddy 已认可当前交互方向并授权收口开发文档；真实浏览器全链路、模型、媒体、计费与 SLA 仍需独立验收
禁止事项：本文件不构成发布、合并、付费调用或生产切换授权
1. 开发阅读顺序
| 顺序 | 文档 | 开发用途 | 权威边界 |
|---|---|---|---|
| 1 | prd.md | 业务范围、对象、规则、权限、状态、异常、验收 | 产品业务事实唯一权威源 |
| 2 | frontend-contract.md | 页面、组件、交互、状态和响应式实现 | 只能细化 PRD，不能改变业务规则 |
| 3 | flows.md | 快速生成、分镜、画布、媒体、版本和回流流程 | 解释跨对象时序，不替代对象字段 |
| 4 | prompts/marketing-video-plan.prompt.md | AI 视频导演系统 Prompt 候选 | Candidate；不得直接接生产 |
| 5 | prompts/storyboard-template-modules.md | 六类业务模板 Prompt 模块 | Candidate；模板只定义职责，不写死时间轴 |
| 6 | prompts/marketing-video-plan.schema.json | DirectorPlanIR 输出校验 | 所有导演计划必须结构化校验 |
| 7 | prompts/marketing-video-plan.contract.json | Prompt 资产、版本和发布门禁 | 无真实回放前 active/runtime 为空 |
| 8 | prompts/golden-cases.json、behavior-evaluation.md | 静态回归和未来真实回放 | 当前不是模型质量报告 |
| 9 | prototype/ai-marketing-video/ | 本地交互参考 | 不代表真实接口或模型能力 |
PRD 已按四段拆分到 segments/，开发可分段阅读，最终冲突以完整 prd.md 为准。
2. 不得改变的产品常量
- 只有“快速生成”和“分镜创作”两套工作流；创作画布是分镜创作的可选视图，不是第三种模式。
- 快速生成保持当前交互：SKU、1–9 张商品图片、模板、视频模型与基础生成配置，AI 返回一份可编辑脚本，用户确认后才创建可能付费的执行任务。
- 分镜创作默认进入线性分镜；用户需要复杂分支时才切换创作画布。列表和画布读取同一工程、镜头、任务、结果和版本状态。
- 画布自由生图使用独立
ImageGenerationTask；不调用图片工坊，不继承 Listing 图片角色、套图 Visual Plan 或图片工坊复杂编辑。 - 统一元素库首期只在工作空间内共享；不建设个人库、公共市场或跨租户共享。
- 视频模型只生成无文字画面。旁白、字幕文本、打轴、SRT/VTT、字体和烧录由确定性媒体链处理。
- 系统可以定位问题并说明影响，但不得自动创建任何可能付费的图片、视频或 TTS 重试；执行动作由用户确认。
- 可发布质量、转化潜力预测和真实投放效果是三个独立域，不能互相冒充。
3. 一期系统边界
flowchart LR
UI["创建页 / 作品工作台"] --> FACT["商品事实与权利快照"]
UI --> DIR["AI 视频导演 Agent"]
FACT --> DIR
DIR --> IR["DirectorPlanIR"]
IR --> COMP["Prompt / 任务编译器"]
COMP --> VJOB["逐镜视频任务"]
COMP --> AJOB["TTS / 音频任务"]
COMP --> SJOB["字幕文本与确定性打轴"]
VJOB --> MEDIA["标准化 / 合并 / 字幕渲染"]
AJOB --> MEDIA
SJOB --> MEDIA
MEDIA --> QC["六层质量检查"]
QC --> VER["不可变 VideoVersion"]
VER --> PKG["DeliveryPackage"]一期不建设完整时间线编辑器、专业调色/音频工作站、自动投放、自动优化 Prompt、自动付费重试或跨工作空间素材市场。
4. 核心对象与唯一职责
| 对象 | 唯一职责 | 关键不可变边界 |
|---|---|---|
ProductBinding | 在租户、店铺、站点和变体范围内唯一绑定商品 | 不能只用 SKU 作为全局唯一键 |
ProductFactSnapshot | 冻结本次可使用的商品事实及来源 | 创建后不可原地改写；AI 推断不是商品事实 |
RightsSnapshot | 冻结素材、人物、音乐、字体、品牌和地域权利 | 过期或撤权只能标记失效并创建新快照 |
DirectorPlanIR | 脚本、旁白、字幕和逐镜语义的唯一源 | 视觉、TTS、字幕任务不得各自改写业务语义 |
VideoExecutionPlanSnapshot | 用户确认后冻结本次执行依据 | 脚本、镜头、模型、素材、配置或约束变化均新建快照 |
Shot | 稳定的镜头业务目的 | 一个镜头只有一个主要目的和主要动作 |
ShotAttempt | 某镜头的一次生成尝试 | v2/v3 追加，不覆盖旧结果 |
CreativeElement / ElementVersion | 工作空间内复用的人物、场景、道具、风格参考 | 商品主数据仍由 SKU/Product 域管理 |
ImageGenerationTask / ImageVersion | 画布自由生图任务和不可变图片结果 | 生成成功不等于自动采用 |
QualityRun / QualityIssue | 对指定版本执行可定位质量判断 | 硬失败不能被平均分掩盖 |
VideoVersion | 镜头、音频、字幕和合成清单的不可变版本 | 当前采用版只是指针，历史不可覆盖 |
ControlledVariant | 基准版上的单变量试验版本 | 一次只允许一个变量变化 |
DeliveryPackage | 一个视频版本对一个平台规格的交付清单 | 导出成功不等于已发布或真实投放 |
所有跨项目审计使用 project_id + change_id 联合标识，避免不同项目出现同号 CR 时碰撞。
5. 两套工作流的开发合同
5.1 快速生成
SKU 查询与历史去重
→ 上传 1–9 张商品图片
→ 选择模板、视频模型和基础配置
→ AI 导演生成一份 editable_script
→ 用户编辑并确认
→ 冻结执行快照
→ 后台逐镜生成、TTS、字幕、合并和质检
→ 创建视频版本与交付包用户确认脚本前禁止创建视频生成任务。快速生成界面不展示系统 Prompt、内部 Skill、供应商路由、seed、采样器或隐藏约束。
5.2 分镜创作
AI 导演生成动态 ShotPlan
→ 默认线性分镜逐镜编辑
→ 用户选择模型、首尾帧、旁白、字幕和 creative_prompt
→ 创建 ShotAttempt
→ 用户选择当前采用版本
→ 全部必需镜头可用后合并
→ 质检、版本与交付创作画布只改变视图和任务组织方式。creatorMode=storyboard 与 storyboardView=linear|canvas 必须分开持久化，切换不得清空结果。
6. Prompt 编译合同
编译顺序固定为：
商品事实与权利
→ 平台、品牌与合规规则
→ 模板 Prompt 模块
→ 用户一句需求 / 逐镜 creative_prompt
→ 模型能力适配
→ visual_execution_prompt / voiceover / subtitle jobs| 层 | 输入 | 输出 | 用户能否覆盖 |
|---|---|---|---|
| 商品事实层 | ProductFactSnapshot、来源、禁用主张 | 可使用事实和受保护约束 | 否 |
| 模板层 | TemplateVersion、PromptModuleVersion | 叙事职责、证明机制、风险红线 | 否 |
| 创意层 | 一句话需求、逐镜 creative_prompt | 场景、动作、景别、运镜、节奏 | 是 |
| 模型适配层 | CapabilityProfile、输出配置 | 供应商方言和参数 | 否 |
| 质量层 | 六层规则与 Golden Cases | 阻断、警告、人工复核项 | 否 |
visual_execution_prompt 只描述当前镜头的无文字画面；voiceover_script 是语义母稿；subtitle_cues 必须是旁白的连续原文片段。字幕变化只创建新字幕轨和合成版本，不触发视频模型。
7. 任务和状态机
7.1 项目状态
created → resolving_facts → needs_input | planning
planning → plan_ready → approved → generating
generating → quality_review | paused_budget | failed
quality_review → repair_required | ready_to_deliver
ready_to_deliver → delivered → closed7.2 执行任务状态
draft → awaiting_user_confirmation → queued → submitted
→ provider_processing → succeeded | failed | cancelled | unknownunknown 表示供应商回调和查询均无法确认，不能当作失败自动重提；必须保留幂等键、Provider Task ID 和最后一次查询证据。
7.3 前端必须覆盖的状态
Empty、Loading、Needs input、Awaiting confirmation、Queued、Processing、Partial success、Failed、Permission denied、Budget paused、Quality blocked、Ready、Superseded。
8. 命令与接口候选
具体外部 Provider 字段尚未核验，后端先实现内部命令合同，适配器不得把供应商字段透传到前端。
| 命令 | 主要输入 | 成功结果 | 幂等/权限要求 |
|---|---|---|---|
ResolveProduct | workspace、shop、site、SKU | ProductBinding + FactSnapshot 候选 | 店铺数据权限；查询不泄露跨店结果 |
GenerateDirectorPlan | 事实、素材、模板、输出配置 | Schema 合法的 DirectorPlanIR | 规划请求幂等；不创建付费任务 |
ConfirmExecutionPlan | 计划修订、模型、配置、确认人 | 冻结 ExecutionPlanSnapshot | 每次确认重新鉴权并校验费用边界 |
CreateShotAttempt | shot、执行快照、用户确认 | 异步任务 ID | user_confirmed_only；禁止自动重试 |
CreateImageTask | Prompt、引用、模型、参数 | ImageGenerationTask | 画布自由生图；不接图片工坊 |
SelectShotAttempt | shotAttemptId | 当前采用指针 | 不改旧 Attempt |
ComposeVideoVersion | 采用镜头、音轨、字幕轨 | VideoVersion | 输入清单哈希保证幂等 |
RunQualityCheck | videoVersionId、规则版本 | QualityRun | 机器复检可自动，付费生成不可自动 |
CreateDeliveryPackage | videoVersionId、平台规格 | DeliveryPackage | P0 全部通过；后端重新鉴权 |
9. 统一错误与恢复
| 错误码 | 含义 | 恢复动作 |
|---|---|---|
SKU_NOT_FOUND | 当前店铺无匹配商品 | 核对店铺或 SKU |
SKU_AMBIGUOUS | 当前范围存在多个候选 | 用户选择唯一商品 |
FACT_CONFLICT / FACTS_BLOCKED | 关键事实冲突或缺失 | 查看来源、补充或移除宣称 |
RIGHTS_BLOCKED | 素材权利不可用 | 替换素材或补授权 |
TEMPLATE_SCOPE_MISMATCH | 模板不适用当前品类/市场 | 换模板或调整目标 |
DURATION_INSUFFICIENT | 时长无法承载必要叙事 | 调整时长或模板 |
CAPABILITY_UNSUPPORTED | 所选模型缺少必要能力 | 选择已登记支持模型 |
TIMELINE_INVALID | 时间轴不连续或不守恒 | 重新生成导演计划，不创建任务 |
SUBTITLE_SOURCE_MISSING | 开启字幕但无旁白母稿 | 补旁白或关闭字幕 |
PROVIDER_TIMEOUT | 供应商任务超时 | 保留其他结果，由用户决定重试 |
BUDGET_PAUSED | 超出已确认费用边界 | 审批、降级或终止 |
QC_INCOMPLETE | 质量检查不完整 | 重跑非付费检查或人工复核 |
PERMISSION_DENIED | 无操作或数据权限 | 不发送命令，不泄露对象 |
页面只显示一个最高优先级阻断问题，其余问题进入可展开明细。
10. 六层质量与发布门禁
| 层 | 主要判断 | 发布门禁 |
|---|---|---|
| L1 商品事实与主体真实性 | 外形、结构、参数、功能与来源 | 事实冲突或主体严重漂移为 P0 |
| L2 权利、品牌与合规 | 素材、人物、音乐、字体、平台规则 | 无权、撤权、过期或合规 P0 阻断 |
| L3 脚本、Prompt 与创意 | Hook、卖点证据、叙事、CTA | 默认软门禁；触及事实/合规升级 |
| L4 视觉一致性与时序 | 商品、人物、物理、连续性 | 定位到镜头/时间段，由用户决定是否重做 |
| L5 字幕、音频与技术文件 | 文本同源、字形、时码、编码、规格 | 技术不可交付或字幕不一致为 P0 |
| L6 转化潜力预测 | 钩子、证据、CTA、平台适配 | 不是交付硬门禁，不得写入真实效果字段 |
结果枚举统一为 PASS | FAIL_BLOCKING | REVIEW_REQUIRED | NOT_EVALUATED | N_A。任何硬门禁失败都不能被平均分抵消。
11. 权限最小集
| 角色 | 能力 |
|---|---|
| 运营创作者 | 创建项目、编辑脚本/分镜、主动提交生成、选择版本、申请交付 |
| 业务审阅者 | 批注、驳回、确认软门禁处理、通过/撤回交付 |
| 品牌/合规 | 处理事实、权利、品牌与合规问题；P0 不可由普通用户豁免 |
| 预算负责人 | 只处理超预算确认，不代替创作或合规决策 |
| 投放运营 | 绑定外部创意与导入效果数据；不自动创建广告 |
| 系统管理员 | 维护模型、规则和 Prompt 资产；不能代替业务确认 |
| 只读观察者 | 查看授权项目，不可生成、修改或下载交付 |
前端禁用态不替代后端鉴权；每条命令都必须按工作空间、店铺和对象重新校验权限。
12. 开发阶段建议
| 阶段 | 范围 | 完成门禁 |
|---|---|---|
| D1 领域与状态骨架 | 对象、事件、权限、幂等、版本服务 | 状态回放和父子版本不可覆盖 |
| D2 AI 导演 Candidate | Prompt、Schema、模板模块、结构修复 | Golden Cases 结构 100%，仍不接真实视频模型 |
| D3 Provider 与媒体 POC | 模型能力注册、逐镜任务、TTS、字幕、合并 | 明确模型/参数/次数/费用授权后执行 |
| D4 产品联调 | 两套流程、列表/画布共享状态、失败恢复 | 快速/分镜全链、切换保留、权限与异常通过 |
| D5 质量与交付 | 六层检查、版本、交付包 | P0=0；不可发布版本无法生成交付包 |
| D6 受控投放回流 | 外部映射、可比性和数据导入 | 不自动发布；混杂因素不一致标记 not_comparable |
13. 尚未验证且不得写成生产能力
- 真实商品、素材、平台和投放 API 的字段、权限、错误码与回读。
- Seedance、MiniMax 或其他模型的首尾帧、声音、时长、分辨率、局部编辑和跨镜一致性。
- Prompt 0.7 的编译器、运行时消费者和真实模型回放。
- TTS、字幕确定性对齐、字体授权、媒体合并、并发、失败率和 SLA。
- 供应商单次费用、退款口径和预算暂停的生产实现。
- 可发布质量与真实转化之间的关系。
14. 开发交付完成定义
开发交付完成需要同时满足：PRD、前端契约、Prompt/Schema、流程图、代码和构建说明一致；所有 P0 验收通过；真实浏览器完整链路通过；Freddy 完成最终验收。即使项目交付完成，也只能表述“具备可交付视频生产能力”；真实转化效果仍须独立投放验证。