# 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. 共同读取链路

```text
镜头分析与路由
-> 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 与成本是否完全一致。