short-drama-agent-front/docs/backend-coverage.md

后端功能覆盖说明

核对日期：2026-09-10。后端：qianlanse/short-drama-agent，本地 HEAD=f0321c2。精简返回结构的适配详情见 接口数据同步说明。以 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 生成与图片记录
稳定身份	主体身份	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。质量接口的详细参数、默认一镜范围、费用确认、主图晋升、视频抽样与专项检查和会话回执限制见 前端简化与质量功能同步。首帧和视频均不虚构质量历史 GET；校验回执按项目、镜头和资产 ID 保存在当前会话。

高级串联生产边界

实际后端顺序：形态正式提示词 → 形态图片 → 视频提示词 → 视频任务提交。没有视觉风格、身份、导演设计、即时状态或首帧生成节点，也不会等待成片。

• 仅剧本 completed 可启动；先检查项目／工作流任务、形态活动图片、当前母版引用、镜头规格、主首帧有效性和活动视频。
• 为避免中途生成主图使既有首帧失效，前端要求先确认全部形态主图并补齐有效主首帧；因此该入口通常跳过形态生图，只串联仍缺少的文本与视频任务。
• 点击预检只有 GET；付费确认后再次 GET 校验。查询失败或条件变更不提交 POST。单次项目锁仅覆盖本浏览器，不能代替服务器事务和跨客户端互斥。
• 图片与视频模型由后端统一配置，前端不传请求级 Provider。旧串联路由仍解析默认字段，但实际执行节点已改用统一配置；不据此显示虚假模型选择。后端内部文字并发 3、图片与视频并发 2，不接受普通批量面板的覆盖、上限和尺寸配置。
• 图工作流 completed 仅说明经过 finalize，可能仍有错误；needsManualReview、stopReason 和所有 errors 原样显示。视频统计用“已提交”，不标“成片已完成”。
• 此工作流没有持久 checkpoint／恢复／取消接口。网络断开不能推断后端停止，禁止自动重发。已提交的长请求回执按原项目隔离；页面刷新后需从资产状态核对。

观测指标边界

后端 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。测试不触发真实模型或生产任务。
• 当前环境无法打开应用预览，未进行浏览器视觉验收；需在可访问的开发环境检查浅／暗主题和窄屏布局，并由用户明确批准后进行真实小批量模型联调。