接入动作时间轴、密度审计、人工视线目标和后台首帧编辑;独立读取已保存提示词,并在首帧晋升前重新核对持久化质量状态。 统一 NMessage 结果反馈、局部 loading 和业务说明间距,保留真实长任务进度与部分失败语义。 验证:pnpm check(49 个文件、393 项测试)、pnpm build;当前环境无法完成 localhost 浏览器验收及真实后端联调。
92 lines
12 KiB
Markdown
92 lines
12 KiB
Markdown
# 接口数据同步说明
|
||
|
||
核对日期:2026-09-10。依据同级后端仓库 `short-drama-agent` 的 `HEAD=f0321c2`、`src/api/routes` 及实际资产 DTO/service 实现。本轮仅修改前端,沿用已完成页面和正式路由。
|
||
|
||
| 接口范围 | 精简后的公开数据 | 前端处理 |
|
||
| --- | --- | --- |
|
||
| 项目列表/详情 | 项目业务字段、characters、world、episodes;不含 reviews、tasks | 删除旧类型依赖;审核读取共享 checkpoint 的明确 reviewPassed,不伪造审核记录;生产预检从每条工作流最新 checkpoint 检查运行状态 |
|
||
| 视觉风格及参考图 | 风格保留可编辑 Prompt、hardConstraints 和 images;图片去除生成 Prompt | 保留编辑、锁定、图片登记和启停;移除图片内部提示词展示 |
|
||
| 主体身份查询/保存/生成 | id、subjectId、description、generationPrompt、isLocked、时间 | 图片继续通过独立 GET 查询,不从身份对象读取 images |
|
||
| 身份图片查询/生成/切母版 | 明确 isAnchor,不含 enabled、prompt、rawJson | 母版识别和切换结果校验统一使用 isAnchor;辅助视角仍不可设母版 |
|
||
| 角色选角确认 | identityId、subjectId、isLocked、anchor | 验证主体、身份、图片归属和母版标记,不再访问嵌套 identity |
|
||
| 形态图库/图片/主图 | identity.anchorImageId;图片仅含资产字段 | 正常预览、生成和切主图;移除依赖历史 rawJson 的身份过期推断及批量重生,保留下游 readiness 过期定位 |
|
||
| 形态正式 Prompt | 正式形态业务字段和时间,不含 subject、images 关联 | 单独声明回执类型;生成后重读图库,避免将单体回执当作图库记录 |
|
||
| 视频 Prompt | shotId、status、videoPrompt、negativePrompt、updatedAt | 两个页面均按 shotId 校验回执;保留正文展示与导出 |
|
||
| 首帧资产 | source、状态、图片、主图标记、模型与时间;无内部 Prompt/任务信息 | 保留候选和主图;source=provider_variant 的模型输入变体不可设业务主首帧 |
|
||
| 视频资产/单任务刷新 | 状态、地址、时长、isPrimary、模型和时间;无 rawJson/Provider Task/Prompt | 播放与状态使用公开字段;未知质量不显示通过或自动校验中 |
|
||
| 视频就绪/项目状态 | stale_prompt、provider_input_recovery;公开失败分类、retryable 和输入恢复状态 | 补齐类型和中文原因,显示不可普通重试提示;不解析内部失败快照 |
|
||
| 视频生成规格 | 业务 keyframe 和实际 providerInputKeyframe | 类型区分两种用途,规格面板展示实际输入 ID;尺寸允许后端 null |
|
||
| 失败视频重试 | totalFailed、retryable、skipped、retried、failed、failures | 显示可重试和跳过数,保留部分失败,不将 HTTP 成功当作全部重试成功 |
|
||
| 拆解、导演设计、即时状态、质量 POST、串联生产、诊断 | 已核对现有页面使用的正式路由与返回业务切片 | 保留原入口、参数、费用确认与失败处理;不增加测试/探针生成入口 |
|
||
|
||
视频校验的新增运动、空间交互、道具结构及连接检查回执也已同步;专项未执行不显示通过,完整证据随结果导出。视频校验费用提示按一次请求可能调用多个模型说明。
|
||
|
||
## 质量数据边界
|
||
|
||
公开视频 DTO 不再带质量候选类型、历史校验和修复次数。后端自动质量链仍负责通过后晋升,前端以刷新后的 `isPrimary` 为准。普通手动设主入口要求本会话对此资产收到 PASS;修复要求本会话收到 FAIL。回执按项目、镜头、资产隔离,切页仍可查看,刷新浏览器后不伪造历史。重新校验会清除旧通过资格;失败的修复请求保留其依据的失败校验。次数上限由后端检查,错误原样呈现,不自动重试。
|
||
|
||
项目详情不再提供内部任务列表。公开 checkpoint 只能证明已记录工作流的状态,不能证明所有外部生成任务均已停止;保留现有的资产状态检查和操作确认。
|
||
|
||
## 回归验证范围
|
||
|
||
测试使用不包含旧内部字段的公开 DTO,覆盖页面加载、身份保存/选角、图片主图、Prompt 正式 ID、质量会话隔离、输入变体禁用、失败重试和缺失历史不误报过期。全部 API 使用模拟响应,不触发真实模型。此次不以自动化 DOM 测试代替浏览器视觉验收或真实后端联调。
|
||
|
||
|
||
## 2026-09-14 增量同步
|
||
|
||
核对后端 dev `c2142681b16798ae5ff865a2eb648a9f45221af2` 的路由、Production Plan/Status/State、主体生图及视频输入编译实现。历史文档中的 `f0321c2` 已无法通过 GitHub compare 解析,本轮以当前源码为准。
|
||
|
||
- 接入制作执行计划和真实制作状态,删除“串联不会生成首帧”和必须先有全部主图的旧限制。
|
||
- 补齐首帧质量回执、视频阻塞/进行中、dispatchCompleted;Provider 启动参数保持空对象。
|
||
- 人工阻塞与请求错误分开,允许其余 ready 主体部分成功;提交前重新预检,项目归属/活动任务校验保留。
|
||
- 批量生图默认包含过期主图,但新候选不会自动替换已有主图,页面明确提醒确认主图。
|
||
- 指定模型最终输入支持只读检查授权素材与实际首帧,通用规格改为明确未指定模型的展示。授权资产绑定管理和实验探针不在本轮新增范围。
|
||
- 浅色主画布统一白色,输入框使用浅灰,Tab 导航、辅助区和图库使用统一主题变量,首屏 theme-color 与应用一致。深色视频播放背景保留。
|
||
|
||
验证使用模拟 API,不调用真实生成模型。浏览器无法访问当前本地预览地址,尚未完成浏览器截图验收或真实后端联调。
|
||
|
||
## 2026-09-21 项目资产接口
|
||
|
||
- `POST /projects/:projectId/assets` 使用 multipart 的 `file`、`name`、`category`,浏览器负责生成 boundary,前端不手工设置 `Content-Type`。
|
||
- GET/PUT/DELETE 项目资产接口全部使用正式项目 ID 与资产 ID;编辑只修改名称和分类,不替换物理文件。
|
||
- 素材公开字段包含 `publicUrl`、类型、MIME、扩展名、大小、分类、元数据和时间;页面只读取 `metadata.originalName` 作为辅助搜索,不依赖内部存储路径。
|
||
- 视觉风格新增参考图可发送 `projectAssetId`,后端从所属项目素材解析 `imageUrl`;外部 `imageUrl` 入口继续兼容。资产关联关系不在公开风格图 DTO 中推断。
|
||
- 删除仍由后端执行引用保护;前端不先删风格记录,也不将失败响应显示为已删除。
|
||
|
||
## 2026-09-22 增量同步
|
||
|
||
- 新增形态图和镜头首帧的 POST 预览接口;请求体默认 `{}`,只读取后端当前生成配置与参考图规划,不产生模型任务。
|
||
- 首帧预览按 `referencePlan.selected`/`omitted` 展示 Provider 上限后的真实输入;不再从通用 `keyframe-spec` 推断最终选图。
|
||
- 形态提示词、形态图片及主体身份文本批处理均可发送可选 `module`;省略时保持全项目行为。
|
||
- 场景/道具身份母版使用 `/projects/:projectId/subject-identities/anchors/generate`,请求包含 `module`、`limit`、`concurrency`;成功项已由后端设为 Anchor 并锁定,不再由前端逐项补 PUT。
|
||
|
||
|
||
## 2026-10-10 串联生产增量同步
|
||
|
||
核对后端本地与远端 `dev@8acc22db66605b2094098eb3f25b4d1de0ef4a69`。本轮调整已有生产流程:
|
||
|
||
- `POST /projects/:projectId/production/start` 新增 `videoLimit` 和 `videoGenerationOptions`。高级串联生产默认视频候选最多一镜,限制值必须为正整数;默认安全模式仍在视频提示词阶段停止。
|
||
- 项目 `creative-profile.videoOptions` 被复制到本轮启动快照。确认后重新读取配置,视频参数变化也会撤销旧预检与确认,避免启动未经确认的参数。计划接口仍仅解析图片参数及图片/视频供应方,视频参数和数量上限由启动接口实际消费,不将计划表中的全项目计数描述为本批上限。
|
||
- 补齐首帧就绪项 `primaryQualityStatus` 和视频就绪汇总 `failedKeyframeQuality`。缺省状态不推断通过;已有 `failed_keyframe_quality` 问题显示沿用后端真实原因。
|
||
- 新增首帧编辑、候选质量恢复和人工空间目标绑定属于独立操作入口,本轮未新增这些页面功能。已有通用 JSON 规格展示和导出保留后端新增数据,不人工编造空间目标。
|
||
|
||
验证:`pnpm check`(45 个测试文件、357 项测试)及 `pnpm build` 通过;本地 Chrome 的 `localhost:4312` 读取真实后端 `localhost:3412`,生产预检成功,视频候选上限可编辑,修改后旧预检失效且启动禁用。真实生产状态返回 passed/failed 主首帧质量标记;当前项目视频参数来自实际配置。未启动图片、视频或视觉校验模型任务。测试输出存在 localhost:3000 连接拒绝日志,但全部测试通过;不据此宣称付费生产端到端验证。
|
||
|
||
|
||
|
||
## 2026-10-12 工作区与长任务反馈同步
|
||
|
||
后端契约基线:`dev@45c8678971f71210764ef816c4a712b1b302f429`;前端起点:`dev@83482a70c50d85d6481f41e69f4b53dfaa3f986a`。以路由与实际服务返回为准。
|
||
|
||
- 分镜和生产工作区接入单镜头 `motion-plan/preview`;项目级 `storyboard/motion-plan-duration-audit` 按需读取,并按正式镜头 ID 定位。时间轴结构预警与动作密度预警独立计数;实时审计、历史生成预警和人工建议分别展示,缺失历史记录不推断通过。预警不阻断生产,不自动调整时长。
|
||
- 接入 `spatial-target-bindings` GET/PUT 和 `gaze-readability/preview`,人工编辑支持方向性注视/精确目标、画内外、景深、区域及唯一性。完整替换写入仅包含允许的业务字段,不提交后端 evidence;空列表撤销人工覆盖需确认。
|
||
- 首帧主图和历史候选增加 `edit/preview` 与 `edit` 入口。参数变化撤销预览和费用确认;提交前重新核对源图及主图状态。主图编辑自动校验并在通过后尝试晋升;历史候选仅生成下一代候选,不能显示质量通过。编辑的 202 句柄复用 `keyframe-quality` 持久化观察,完成回执与批量质量统计分开。
|
||
- 分镜工具通过 GET `video-prompt` 自动读取已保存正文,只有用户明确生成才 POST。首帧手动晋升前重新读取 `quality-review`,认可当前持久化 passed/manual_accepted,移除只认可本会话结果的过期限制。视频手动晋升仍保留已有独立守卫。
|
||
- 临时成功、失败、警告使用同一 NMessage;同一时间的重复查询错误去重。项目操作过程由按钮 loading、操作入口旋转图标、资产状态及真实后台阶段反馈,不再显示固定全局 loading 消息。后台终态只通知一次,旧完成记录不重放。
|
||
- 常驻彩色提示框改为紧凑业务状态与恢复入口;重复阶段成功说明移除。批量部分失败根据后端真实统计显示 warning,成功的只读刷新不再额外提示成功。
|
||
- 页面模块和提示说明沿用全局间距;新时间轴、目标表单与编辑面板在窄屏自动单列。历史错误、业务预警和操作错误分别保留正确的查看或恢复入口。
|
||
|
||
验证不启动真实生图、视频或视觉校验。当前浏览器无法访问本地 localhost 服务,浏览器视觉验收与真实后端联调仍待在可访问的开发环境完成。
|
||
|
||
本轮校验:`pnpm check`(49 个文件、393 项测试)、`pnpm build` 和差异检查通过。新增回归覆盖切镜迟到响应、历史审计缺失、编辑预览失效、主图身份变化及后台候选编辑句柄。测试输出仍有已有 localhost:3000 连接拒绝日志;不据此宣称真实后端或付费模型联调完成。
|