ai/docs/work-sync/SPLUS_GENERATION_PLAN_IMPLEMENTATION_REPORT_V1.md

S+ 不可变 Generation Plan 实施报告 V1

状态：工程已完成，真实付费小样待验收
日期：2026-07-15
适用引擎：splus_v1

1. 目标

每个可生成镜头在关键帧之前冻结唯一执行计划。关键帧、参考资产、角色元素、音色、视频请求、质量门、重试、回退和成本审计共同读取该计划，禁止执行阶段静默换模型或重算资产。

2. 不可变规则

• 计划使用规范化内容的 SHA-256 作为 plan_hash。
• 相同输入复用同一修订；输入变化创建下一修订。
• 历史修订只读，不执行 update。
• StoryboardShot.active_generation_plan_id 只指向当前活动修订。
• ShotImage、VideoClip、RenderTask 保存 generation_plan_id，形成结果与成本追踪链。
• S+ 正式执行必须存在状态为 frozen 的活动计划；旧项目继续走 legacy_v1，不强制回填。

3. 冻结内容

单个计划固定保存：

• Provider、模型、接口、能力版本、路由理由和回退链。
• 推荐分辨率、实际生成分辨率、画幅、时长、原生声音、多镜头和4K候选状态。
• 角色/场景/道具参考资产及 Provider 请求装配快照。
• 角色元素与逐说话人音色计划。
• 关键帧模型、尺寸、质量与参考图上限。
• 视频请求、Prompt、质检阈值、重试上限和成本/价格快照。

4. 共同读取链路

镜头分析与路由
-> freeze generation_plan
-> 关键帧读取资产与关键帧参数
-> 视频队列读取 Provider、参数、声音与分辨率
-> VideoClip/RenderTask 绑定 plan_id
-> QC 读取计划阈值
-> 重试读取计划上限与回退链
-> TTS/后期读取逐角色音色
-> ProviderLog 通过 RenderTask 进入成本审计

正常请求不能覆盖冻结 Provider；系统定向修复只能使用计划内已批准的回退链。关键帧缓存也必须与活动计划 ID 一致，避免旧图被新修订误用。

5. 数据与接口

数据库迁移：20260715223000_shot_generation_plan_v1。

新增接口：

• GET /episodes/:episodeId/live-action/generation-plans
• POST /episodes/:episodeId/live-action/shots/:shotId/generation-plan/freeze

镜头、视频片段和任务安全响应均返回对应计划 ID，便于前端和后台展示真实执行来源。

6. 验证

• Prisma Client 生成、schema 校验和迁移部署通过。
• Backend、User App、Admin、Workers 生产构建通过。
• Generation Plan 与 AI Router 定向测试 9/9 通过。
• 全量后端测试 299 条中 265 通过、34 失败；失败属于既有旧测试桩和历史断言漂移，本阶段新增测试全部通过。
• 未触发真实付费生成。

7. 下一步

1. 活动计划、历史修订与字段级差异查看已完成。
2. 版本化模型能力、参数 Schema 和价格注册表已完成并绑定 Generation Plan。
3. 下一步把 Kling 元素创建/验证结果纳入供应商绑定，并在计划冻结前硬校验。
4. 用一个全新 S+ 项目做单镜头真实验收，核对计划快照、请求日志、QC 与成本是否完全一致。