# 后端功能覆盖说明

核对日期：2026-09-10。后端：`qianlanse/short-drama-agent`，本地 `HEAD=f0321c2`。精简返回结构的适配详情见 [接口数据同步说明](api-contract-sync.md)。以 API 路由和实际 service／workflow 实现为依据，不只根据接口名称推断功能。本轮不修改后端。

## 页面与接口能力

所有路径以 `/api` 为前缀；`id`、`formId`、`shotId` 必须取正式数据库 ID。

| 能力 | 前端入口 | 对应后端 | 本轮结果 |
| --- | --- | --- | --- |
| 项目列表、创建与详情 | 我的剧本／剧本创作 | `/projects`、`/projects/:id` | 保留状态筛选、创建、正文、角色、世界观、审核与导出 |
| 剧本恢复 | 剧本创作操作面板 | `resume-generation`、`resume-rewrite` | 保留费用确认、项目互斥与最近可用 checkpoint |
| 拆解与恢复 | 拆解设置与恢复 | `breakdown-preview`、`breakdown/start`、`retry`、`resume-shots`、`resume-storyboard` | 保留正式剧集分组、模块选择、预览、失败恢复与 JSON 导出 |
| 运行诊断 | 创作／拆解的执行记录 → 查看完整运行诊断 | GET `metrics`、`timeline/grouped`、共享 `checkpoints` | 新增全量时间线、阶段分组、工作流与节点筛选、独立失败提示、JSON 导出 |
| 视觉风格 | 视觉风格 | GET／PUT／POST `visual-style` 及图片登记、启停、删除 | 保留锁定、分类提示词、硬约束、AI 生成与图片记录 |
| 项目资产库 | 资产库／视觉风格参考图选择器 | `/projects/:id/assets` 上传、列表、详情、编辑、删除 | 新增 JPEG／PNG／WebP 上传、名称与分类管理、筛选预览；被视觉风格引用时由后端阻止删除 |
| 稳定身份 | 主体身份 | `subjects/:id/identity`、单个／项目／角色文本生成 | 保留人工修改、锁定及批量文本生成 |
| 角色选角 | 主体身份角色模块 | `character-casting/readiness`、批量／单个 candidates、图片 `casting` | 保留候选、检查、确认母版并原子锁定 |
| 身份参考图 | 主体身份图库 | `identity/images`、图片 `anchor` | 保留完整预览、历史、辅助视角与母版切换；修正道具继承说明 |
| 正式形态提示词 | 形态卡片 → 提示词与生成；批量工具 | POST `subject-forms/:id/generation-prompt`、项目 `subject-forms/generation-prompts` | 新增单个生成／重生成、原始素材与正式文本对照、导出、批量补齐／覆盖及失败回执 |
| 形态图片 | 形态图片及图库 | 项目 `subject-forms`、形态 `images`、主图 PUT、项目 `subject-images/generate` | 增加本批数量上限；支持后端自动补正式 Prompt；人物／场景／道具已锁定母版继承；按需生成候选，历史母版信息不公开时不推断过期 |
| 导演设计与即时状态 | 分镜设计 | directions／visual-states 查询、项目 `generate` | 只保留正式项目批量、覆盖、校验修复次数和逐集回执；不暴露 `generate-test` |
| 参考图与规格 | 分镜参考图／生产单镜头 | `references`、`generation-spec`、`keyframe-spec`、`video-generation-spec` | 保留按需只读检查与缺失原因，查询不调用生成模型 |
| 视频提示词 | 分镜设计／镜头生产 | 单镜头 `video-prompt`、项目 `video-prompts/readiness` 与 `generate` | 保留单镜头／项目生成，重写需确认 |
| 镜头首帧 | 镜头生产 | 项目 `keyframes/readiness` 与 `generate`、单镜头 keyframe／keyframes、主图 PUT | 新增批量 `limit` 与成对尺寸；保留当前集／过期项／覆盖范围；显示因上限未执行数 |
| 视频任务与主视频 | 镜头生产 | 项目 videos readiness／generate-quality／status／retry-failed，逐镜 generate-quality／videos，单任务 status，主视频 PUT | 主入口改为严格质量候选：后台自动校验、有限修复，通过后晋升；保留状态刷新、播放和失败重试 |
| 高级串联生产 | 镜头生产批量面板底部（默认折叠） | POST `/projects/:id/production/start` | 新增预检、再次校验、费用确认、分阶段回执与诊断导出；明确不是全链自动制片 |

## 新增质量检查与修复

已接入：首帧 `validate`、`repair`，项目 `keyframes/generate-quality`，视频 `validate`／`repair`，以及单镜头和项目级 `videos/generate-quality`。严格视频候选由后端 Poller 自动执行 Validator，失败时按上限创建 Repair Candidate，只有 PASS 才晋升 Primary；公开视频列表不再提供质量标记；前端只有在本会话收到 PASS 校验回执后才显示候选的手动设主入口。生成请求不再传固定 Provider。质量接口的详细参数、默认一镜范围、费用确认、主图晋升、视频抽样与专项检查和会话回执限制见 [前端简化与质量功能同步](frontend-simplification.md)。首帧和视频均不虚构质量历史 GET；校验回执按项目、镜头和资产 ID 保存在当前会话。

## 高级串联生产边界

实际后端顺序：形态正式提示词 → 形态图片 → 首帧质量生成／校验／有限修复 → 视频提示词 → 视频任务提交。视觉风格、身份母版、导演设计和即时状态需提前准备。

- 通过 GET `/projects/:id/production/plan` 展示可执行、跳过、前置完成后可执行和人工阻塞数量，并保留逐项后端原因。缺少可自动生成的主图或首帧不再被前端直接拦截。
- GET `/projects/:id/production/status` 展示真实资产有效数量与完成状态。计划是当前快照，前置阶段执行后后端还会重新检查。
- 剧本未完成、活动任务、资产归属或列表不一致、没有可执行工作时不提交。人工阻塞独立提示，允许其余 ready 形态部分成功；不能保证后续阶段继续。
- 点击检查只有 GET；费用确认后再次读取计划与状态，条件变化时不提交 POST。POST body 为 `{}`，图片／视频模型与并发读取后端配置，不消费普通批量面板参数。
- `dispatchCompleted` 表示同步分发结束；`completed` 由后端核对所有有效主体主图、首帧、主视频后给出。回执展示首帧 passed／repairFailed／failed／blocked 及视频 inProgress／blocked，不把提交成功显示为制作完成。
- 批量主体生图会处理缺失及过期主图，已有过期主图仍须用户确认新候选为主图。前端不读取 rawJson 猜测时效。
- 单次项目锁仅覆盖本浏览器；长请求不自动重发，回执按原项目隔离。刷新后通过只读制作状态重新核对。

## 视频实际输入

生成规格弹窗提供 GET `/storyboard-shots/:id/provider-input-spec?provider=...`，显式填写目标模型，查看实际首帧、变体原因和授权素材。查询失败保留后端错误；切换镜头或模型清除旧结果。通用生成规格不宣称是指定模型最终输入。本轮未增加授权资产绑定管理或探针生成入口。

## 观测指标边界

后端 metrics 将 checkpoint 数当 completedNodeCount，并给非空记录返回 successRate 100；并非模型任务成功率。前端只展示保存记录数、累计节点耗时、最近 checkpoint 重试数；累计耗时不等于墙钟耗时。明确的失败取 checkpoint 中的执行字段，其他记录仅标“记录已保存”。原始统计保留在导出 JSON 中。

时间线分组是节点阶段，不是独立 executionId。未识别的节点被后端归为“其它”；前端用共享 checkpoint 的 workflowName 进一步筛选。两个观测接口独立报错，关闭弹窗不继续发起 API 查询，旧项目迟到响应不会覆盖新项目。

## 过期首帧与素材定位

- 生产页将结构化 `stale_keyframe.missingSubjects` 映射到当前镜头 `/references` 返回的正式 `subjectFormId`，点击可定位图库中实际使用的形态；不按主体名称猜默认形态。缺少关联时退回主体引用检索并明确提示待核对。
- 图库始终读取 keyframes 与 videos 的 readiness，显示下游过期镜头数量；选择来源镜头后才查询其参考图，避免遍历全部镜头的 N+1 请求。只允许定位当前项目列表中的镜头。
- 图库深链接支持 `sourceShotId`、`subjectFormId` 和 `subjectRef`；精确形态优先，切换定位清除旧筛选，丢失的形态不自动回退其他形态。返回生产页携带 `episodeNo` 与正式 `shotId`。
- 形态图库不再有历史母版引用，已移除前端推导的“身份主图过期”筛选和批量重生入口。“下游首帧过期”仍读取后端 readiness；核对素材无误后可重建首帧；定位、刷新、筛选不触发生成或切换主资产。
- 本次后端基线已修复视频 readiness／compiler 缺少当前身份母版参数引起的过期误报。前端保留异常时的两种检查结果对照和“状态待核对”提示，不绕过后端阻塞或自动重复生图。

## 不添加无效或重复入口

| 后端路由／能力 | 处理方式与理由 |
| --- | --- |
| `episode-groups` | 正式 `breakdown-preview` 已包含分组与任务，不重复增加一个分组页 |
| `checkpoints/latest`、`state`、`breakdown/latest` | 页面已按 workflowName 从共享 checkpoint 取状态及最近可用快照；保留现有 API 方法，避免重复查询 |
| `timeline` | 新诊断从 `timeline/grouped` 展平并按 index 排序，保持同一份数据 |
| 图片／首帧／视频的 GET primary | 从后端完整列表的 primary 标志选取，无需再次发相同内容请求 |
| POST `/projects/:id/resume` | 实际只返回恢复信息，并不启动恢复工作流；不显示虚假的“继续执行”按钮 |
| `projects/stream-test`、`breakdown/start-test`、Storyboard `generate-test` | 测试或试运行路由，不暴露生产入口；分镜只使用正式项目级 `generate` |
| 手工保存形态 generationPrompt、取消运行任务、删除项目、合并最终视频 | 后端没有对应正式路由，本轮不虚构按钮、成功提示或客户端模拟实现 |

## 回归验证

- 自动测试全部模拟 API，覆盖正式 ID／参数、提示词与图片职责分离、批量部分失败、数量和尺寸校验、候选不覆盖、未完成剧本禁用、费用确认、预检后条件变化、项目切换与旧响应隔离。
- 已通过 lint、格式、TypeScript、Vitest（含质量链路及菜单／折叠交互回归）和生产构建；定位回归见 `src/features/subject-images/asset-impact.test.ts`。测试不触发真实模型或生产任务。
- 当前环境无法打开应用预览，未进行浏览器视觉验收；需在可访问的开发环境检查浅／暗主题和窄屏布局，并由用户明确批准后进行真实小批量模型联调。

## 2026-09-21 项目资产与形态参考同步

核对后端 dev `d9ca93ef54a4c5fbe3917c504531a45f31cb9966`。新增独立项目资产库页面，接入图片上传、列表筛选、详情预览、名称／分类编辑和删除；上传使用 multipart，前端与后端同时限制 JPEG、PNG、WebP 及单张 20MB。视觉风格页可按需读取资产库并以正式 `projectAssetId` 登记参考图，仍保留外部 URL 兼容入口。后端负责校验资产归属、图片类型和删除引用保护。

启用的视觉风格参考图会由后端编译为形态生图的分类参考职责，身份母版继续承担主体一致性。前端不拼接 Provider Prompt，也不把资产库图片自动设为形态主图；已有形态图不会因资产或风格参考变化被客户端静默替换。

## 2026-09-22 生图预览与主体模块批处理

核对后端 dev `9d927cd3e9d7e01415ad953bf3a0957bc3825050`，补齐以下正式能力：

- 形态生图弹窗接入 POST `/subject-forms/:subjectFormId/images/preview`，展示后端实际 Provider、模型、参考图顺序、生成配置与最终 Prompt；预览不创建生图任务。
- 首帧弹窗接入 POST `/storyboard-shots/:shotId/keyframe/preview`，展示视觉风格、身份母版和形态主图经过去重与 Provider 上限规划后的实际选中／省略结果。
- 形态提示词与形态图片批处理支持 `module=character|scene|prop`，前端提供统一批处理范围选择，不再只能执行全项目全部类型。
- 身份文本批处理支持模块筛选；场景／道具新增稳定母版小批量入口，成功后由后端原子设为 Anchor 并锁定 Identity，前端保留部分失败回执。
- 全局 GET `/assets` 已由现有资产库页面使用，无需新增重复页面。

预览结果只用于提交前核对，不作为持久化任务或质量通过证明；真正生成仍需费用确认，并以刷新后的正式资产记录为准。