From fa761659607c0d75aba69ffe4a78e86a9acad97e Mon Sep 17 00:00:00 2001 From: GJ Date: Wed, 14 Oct 2026 13:44:02 +0800 Subject: [PATCH] =?UTF-8?q?feat(short-drama-agent-front):=20=E6=8E=A5?= =?UTF-8?q?=E5=85=A5=E4=BA=BA=E5=B7=A5=E5=8A=A8=E4=BD=9C=E4=BF=AE=E8=AE=A2?= =?UTF-8?q?=E4=B8=8E=E8=A7=86=E9=A2=91=E7=89=88=E6=9C=AC=E6=9D=83=E9=99=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api-contract-sync.md | 13 + docs/backend-motion-contract-followup.md | 66 +++ src/components/ui/WorkspaceRefreshButton.vue | 27 + src/components/ui/WorkspaceSectionHeading.vue | 39 ++ src/components/ui/index.ts | 2 + src/features/production/ProductionPage.vue | 14 +- src/features/production/api.ts | 12 +- .../production/components/QualityDialog.vue | 77 ++- .../components/ShotProductionAssets.vue | 93 +++- .../production/components/VideoCard.vue | 39 +- .../components/VideoQualityDiagnostics.vue | 52 +- src/features/production/model.ts | 3 +- .../production/production-messages.ts | 3 + src/features/production/quality.ts | 24 + src/features/production/testing/fixtures.ts | 14 +- src/features/production/types.ts | 32 +- src/features/production/useQuality.ts | 34 +- src/features/production/video-permissions.ts | 18 + src/features/storyboard/StoryboardPage.vue | 12 +- .../storyboard/components/MotionPlanPanel.vue | 66 ++- .../components/MotionRevisionEditor.vue | 510 ++++++++++++++++++ .../storyboard/components/ShotDesign.vue | 19 +- .../storyboard/components/ShotTools.vue | 73 +-- .../components/SpatialBindingsPanel.vue | 24 +- src/features/storyboard/motion-api.ts | 78 ++- src/features/storyboard/motion-revision.ts | 148 +++++ src/features/storyboard/motion.types.ts | 6 + src/features/storyboard/useMotionRevision.ts | 352 ++++++++++++ .../workflows/WorkflowExecutionPanel.vue | 73 ++- src/features/workflows/execution.ts | 22 +- src/lib/http.ts | 14 +- src/styles/admin.css | 4 + .../features/production/public-assets.test.ts | 4 +- tests/features/production/quality.test.ts | 20 +- .../production/video-permissions.test.ts | 22 + .../production/video-quality-record.test.ts | 16 + .../storyboard/motion-revision.test.ts | 115 ++++ tests/lib/http.test.ts | 21 + 38 files changed, 2003 insertions(+), 158 deletions(-) create mode 100644 docs/backend-motion-contract-followup.md create mode 100644 src/components/ui/WorkspaceRefreshButton.vue create mode 100644 src/components/ui/WorkspaceSectionHeading.vue create mode 100644 src/features/production/video-permissions.ts create mode 100644 src/features/storyboard/components/MotionRevisionEditor.vue create mode 100644 src/features/storyboard/motion-revision.ts create mode 100644 src/features/storyboard/useMotionRevision.ts create mode 100644 tests/features/production/video-permissions.test.ts create mode 100644 tests/features/storyboard/motion-revision.test.ts diff --git a/docs/api-contract-sync.md b/docs/api-contract-sync.md index fbad3c9..3e1de90 100644 --- a/docs/api-contract-sync.md +++ b/docs/api-contract-sync.md @@ -89,3 +89,16 @@ 验证不启动真实生图、视频或视觉校验。当前浏览器无法访问本地 localhost 服务,浏览器视觉验收与真实后端联调仍待在可访问的开发环境完成。 本轮校验:`pnpm check`(49 个文件、393 项测试)、`pnpm build` 和差异检查通过。新增回归覆盖切镜迟到响应、历史审计缺失、编辑预览失效、主图身份变化及后台候选编辑句柄。测试输出仍有已有 localhost:3000 连接拒绝日志;不据此宣称真实后端或付费模型联调完成。 + + +## 2026-10-14 动作修订与候选权限同步 + +依据同级后端当前未提交 dev 的 `docs/api/public/motion-plan-revisions.md` 及正式路由、服务返回;不依赖旧建议文档推断契约。 + +- 视频 DTO 和质量链共用八个版本与权限字段。候选独立控制校验、修复与设主;过期终态优先于历史通过,两个空版本 ID 不自行判为过期。主视频优先显示 readiness 的具体原因。运行任务的过期计数与逐镜终态读取 metadata,完成后读取 result。 +- 分镜动作面板和生产动作弹窗共用完整修订编辑器。编辑、免费预检查、保存、确认模型费用、启动视觉任务、读取任务、激活均为独立步骤;阶段、整体约束、主体引用和收尾等字段完整传递。 +- 保存显式提交父版本(首次可为 null);校验提交当前主首帧 ID 和当前生效指针,使用服务端视觉模型,不传请求级模型选择参数;激活提交真实视觉任务 ID 和预期生效指针。 +- 激活资格要求任务完成、通过且未失效,并核对镜头、修订、内容指纹、主首帧 ID 与图片地址、生效指针。修改草稿、保存新修订、主首帧或生效指针变化后撤销旧资格和费用确认。刷新后可恢复同镜头持久化任务;关闭弹窗或切换标签不重复启动任务。 +- 激活后刷新版本、动作预览、视频资产、质量记录和项目 readiness,提示重新生成视频提示词,不自动发起生成。同步 409 保留顶层 code 与独立 details,撤销候选会话资格并刷新权限;后台 failed 任务独立展示 error 和 result.issues。 + +浏览器验收使用本地 Chrome 和 localhost。真实后端读取及免费预检查不调用模型;保存、收费视觉校验、激活、版本冲突、首帧换图和草稿修改的流程使用隔离模拟场景验证,不写入业务数据或触发真实付费任务。 diff --git a/docs/backend-motion-contract-followup.md b/docs/backend-motion-contract-followup.md new file mode 100644 index 0000000..65a1f0b --- /dev/null +++ b/docs/backend-motion-contract-followup.md @@ -0,0 +1,66 @@ +# 动作规划版本与视频质量接口补充建议归档 + +2026-10-14 更新:后三项已由后端实现。以下保留 2026-10-13 的建议清单;实际接口以同级后端的 `docs/api/public/motion-plan-revisions.md` 为准,前端已按实际契约接入。 + +前端需要识别视频候选所使用的动作版本、展示当前生效动作规划,并完成安全的人工修订流程。以下内容供后端实施与接口评审使用;标记为“建议新增”的路径和字段尚未开放,最终命名由后端确认。所有路径均以 `/api` 为前缀,成功响应沿用 `{ data: ... }`。 + +## 视频质量状态与候选版本字段 + +现有 `GET /storyboard-shots/:shotId/videos/quality-status`(含 `?detail=true`)没有读取持久化的 `qualityTerminalStatus=stale_motion_plan`。旧版本候选停止处理后,查询仍可能返回 `validating` 或 `repairing`。项目任务聚合结果已经提供 `staleMotionPlan` 和 `settled[shotId].status`,但不能替代逐候选状态。 + +建议在质量查询的每个 `chain` 项补充以下字段,并在视频列表、主视频和刷新接口使用的 `VideoAssetDto` 中提供同一份候选版本摘要,使普通候选也可判断是否过期。 + +| 建议字段 | 类型 | 用途 | +| --- | --- | --- | +| `motionPlanRevisionId` | `string \| null` | 此视频生成时绑定的动作修订 ID;历史 AI 快照为 `null` | +| `currentMotionPlanRevisionId` | `string \| null` | 此镜头当前生效的人工动作修订 ID | +| `motionPlanStale` | `boolean` | 后端根据绑定与当前版本判断,前端不解析内部快照 | +| `qualityTerminalStatus` | `string \| null` | 暴露已持久化的质量终态,至少支持 `stale_motion_plan`;其余终态以实际持久化能力为准 | +| `staleReason` | `string \| null` | 可直接展示的过期原因 | +| `canValidate`、`canRepair`、`canSetPrimary` | `boolean` | 后端依据版本、资产完成状态和质量证据计算的操作权限 | + +顶层 `status` 增加 `stale_motion_plan`;最新候选已终止时优先返回此状态,不继续显示校验或修复中。保留历史 `validationPassed` 和问题证据,同时明确历史通过不能证明版本仍有效。逐候选字段必须覆盖整条链,不能只判断最新视频或当前主视频。 + +版本字段与终态保持各自含义:即使后来切回同一版本,曾因过期而终止的任务也不能隐式恢复。历史视频的绑定版本与当前版本均为 `null` 时,保持既有兼容规则,不一律判为过期。不要新增 `ShotVideo.status` 的 Provider 状态值来代替质量终态,也不要公开完整 `rawJson`。 + +建议在现有 readiness 的镜头项增加 `primaryVideoStaleReasons: string[]`,为空数组表示没有原因。前端即可展示首帧、参考图、模型输入变体或动作版本变化的具体原因;当前仅有 `primaryVideoStale` 布尔值,只能展示概括说明。 + +## 人工动作规划的查询与修订接口 + +现有 `POST /storyboard-shots/:shotId/motion-plan/revisions/preview` 请求为 `{ motionPlan }`,时长从正式镜头读取。返回结构问题、时间轴与动作密度预警及内容指纹;`requiresStartStateValidation=true`、`canActivate=false`。结构合法不代表可直接激活。当前尚无公开的修订保存、历史查询与激活接口。 + +现有 `GET /storyboard-shots/:shotId/motion-plan/preview` 仍读取 `rawJson.motionPlan`。建议改为优先解析当前生效修订,沿用既有时间轴字段,同时增加 `source: 'ai_original' | 'manual'`、`activeRevisionId: string | null`、`motionPlanFingerprint: string | null`。仅在没有人工生效版本时读取历史 AI 快照;版本记录损坏或归属错误应明确报错,不静默回退。 + +| 建议新增接口 | 请求 | 返回核心字段 | +| --- | --- | --- | +| `GET /storyboard-shots/:shotId/motion-plan/revisions` | 无请求体 | `shotId`、`originalRevisionId`、`activeRevisionId`、`revisions`;未初始化的版本 ID 可为 `null` | +| `POST /storyboard-shots/:shotId/motion-plan/revisions` | `motionPlan`、`parentRevisionId`、`reason` | 新建修订;保存不激活,由服务端确定 `source=manual`、镜头时长和指纹 | +| `POST /storyboard-shots/:shotId/motion-plan/revisions/:revisionId/start-state-validation/start` | 目标主首帧 ID及预期生效版本 ID | `executionId`、`status`;复用持久化任务查询,明确此操作调用模型,供前端确认费用 | +| `PUT /storyboard-shots/:shotId/motion-plan/revisions/:revisionId/active` | `expectedRevisionId: string | null`、有效的起点校验任务 ID | `shotId`、`activeRevisionId`、`motionPlanFingerprint`、`changed`、`videoPromptStale` | + +修订记录建议包含 `revisionId`、`shotId`、`source`、`parentRevisionId`、`reason`、`motionPlan`、`durationSeconds`、`fingerprint`、`createdAt`、`isActive`。`motionPlan` 沿用 `MotionPlanOutputSchema` 的完整 `beats` 和 `globalMotionConstraints`,不另造简化编辑结构。 + +起点校验任务路径为建议方案,后端也可采用同等能力的现有任务接口。必须明确返回校验结论及其绑定的 `revisionId`、指纹、主首帧 ID,且激活前检查这些输入仍有效。预检查不调用模型;正式视觉校验的费用、模型参数和结果查询契约需要一并确认。现实性等其他激活门禁应由后端定义,不能由前端用预检查的 `valid` 推断。 + +保存、校验与激活均检查镜头和版本归属。激活在事务内执行版本并发检查,使旧视频提示词失效,并保留原始 AI 快照与所有历史候选。并发冲突建议返回 HTTP 409 及可识别错误码,附当前生效版本 ID,前端刷新后由用户重新确认。 + +## 手动设为主视频的版本检查 + +现有 `PUT /storyboard-shots/:shotId/videos/:videoId/primary` 经 `videoAssetService.setPrimary` 调用旧的 `shotVideoRepository.setPrimary`,尚未复用自动晋升的版本检查。仅禁用前端按钮不能防止页面打开后版本变化。 + +建议此接口在同一事务内重新读取镜头当前动作版本、候选绑定版本、持久化质量证据及终止事实,确认候选已完成、属于该镜头且允许晋升后再切换主视频。过期候选或已停止的质量候选必须拒绝;失败时不修改现有主视频。 + +请求可增加 `expectedMotionPlanRevisionId: string | null`,用于发现用户确认期间的版本变化;无论客户端是否提交,服务端都必须比较候选绑定版本和镜头当前版本。成功响应沿用视频 DTO,并包含上文的版本摘要。 + +建议错误返回 HTTP 409,提供可识别的 `code`(例如 `MOTION_PLAN_STALE`)、`message`、`shotId`、`videoId`、`motionPlanRevisionId`、`currentMotionPlanRevisionId`。错误包装沿用项目约定;前端据此撤销本次会话的通过资格、关闭切换确认并刷新资产。 + +## 联调验收 + +- 候选生成期间切换动作版本后,质量任务停止;任务汇总与逐候选状态一致,刷新页面后仍显示版本过期。 +- 同一镜头包含新旧版本候选时,各候选独立显示版本与操作权限,历史通过不会使旧候选可晋升。 +- 手动设主与动作版本切换并发时,旧候选不能替换当前主视频;拒绝请求不改变主视频。 +- 动作预览、提示词生成、视频生成和校验使用同一生效版本,原始 AI 规划始终可追溯。 +- 修订保存、起点校验与激活独立;结构合法但未经有效视觉校验的修订不能激活。 +- 无人工修订的历史镜头正常读取和生产;旧任务缺少 `staleMotionPlan` 时前端按零展示。 + +实现核对入口:后端 `video-quality-status.service.ts`、`video-quality-execution.service.ts`、`motion-plan-detail-preview.service.ts`、`motion-plan-revision-preview.service.ts`、`motion-plan-revision.repository.ts`、`video-asset.service.ts`、`shot-video.repository.ts` 和 `storyboard.routes.ts`、`video.routes.ts`。 diff --git a/src/components/ui/WorkspaceRefreshButton.vue b/src/components/ui/WorkspaceRefreshButton.vue new file mode 100644 index 0000000..c22646c --- /dev/null +++ b/src/components/ui/WorkspaceRefreshButton.vue @@ -0,0 +1,27 @@ + + + diff --git a/src/components/ui/WorkspaceSectionHeading.vue b/src/components/ui/WorkspaceSectionHeading.vue new file mode 100644 index 0000000..ce96497 --- /dev/null +++ b/src/components/ui/WorkspaceSectionHeading.vue @@ -0,0 +1,39 @@ + + + + + diff --git a/src/components/ui/index.ts b/src/components/ui/index.ts index ff71ff4..23b7ba1 100644 --- a/src/components/ui/index.ts +++ b/src/components/ui/index.ts @@ -9,3 +9,5 @@ export { default as AssetOpenLink } from './AssetOpenLink.vue' export { default as RevealImage } from './RevealImage.vue' export { default as DirectoryItem } from './DirectoryItem.vue' export { default as WorkspaceTools } from './WorkspaceTools.vue' +export { default as WorkspaceSectionHeading } from './WorkspaceSectionHeading.vue' +export { default as WorkspaceRefreshButton } from './WorkspaceRefreshButton.vue' diff --git a/src/features/production/ProductionPage.vue b/src/features/production/ProductionPage.vue index bb4f78b..39a5452 100644 --- a/src/features/production/ProductionPage.vue +++ b/src/features/production/ProductionPage.vue @@ -15,6 +15,7 @@ import { EmptyState, StatusBadge } from '../../components/ui' import BeatShotDirectory from '../storyboard/components/BeatShotDirectory.vue' import ConfirmAction from '../workflows/ConfirmAction.vue' import { productionStatusLabel } from './model' +import { videoInputStaleReason } from './production-messages' import { useProduction } from './useProduction' import ProductionReceipt from './components/ProductionReceipt.vue' import ShotProductionAssets from './components/ShotProductionAssets.vue' @@ -65,6 +66,8 @@ const { promptExecution, videoExecution } = useProduction() +/** 关闭动作弹窗或切换镜头时继续观察视觉任务,避免遗留未知活动锁。 */ +useWorkflowExecution(id, 'motion-plan-start-state-validation') /** 当前镜头资产组件引用,标题菜单仅操作此镜头的只读检查弹窗。 */ const shotAssetsRef = ref | null>(null) /** 标题状态只描述最近视频任务,不能表示质量通过或当前主视频仍可用。 */ @@ -387,7 +390,9 @@ const videoRules = { videoLimit: integerRule('本批镜头上限'), videoRepairA 当前有 {{ staleVideos }} - 个主视频已过期。它们使用的主首帧或主体参考图已经变化;非覆盖模式批量生成时会只重建这些过期主视频。 + 个主视频已过期。{{ + videoInputStaleReason + }};非覆盖模式批量生成会按最新输入重建过期主视频。 - 主视频已过期 {{ staleVideos }} · 会按当前主首帧与参考资产重新生成 + 主视频已过期 {{ staleVideos }} · + 会按当前主首帧、参考资产与动作规划重新生成

- 主视频已过期:当前主首帧或主体参考图与生成该视频时不一致。旧视频仍保留,但需要重新生成后才能作为当前有效成片。 + 主视频已过期:{{ + videoItem.primaryVideoStaleReasons?.join(';') || videoInputStaleReason + }}。旧视频仍保留,但需要重新生成后才能作为当前有效成片。 request(`/storyboard-shot-videos/${encodeURIComponent(videoId)}/status`, { signal }), - setPrimaryVideo: (shotId: string, videoId: string) => + /** + * 按候选后端权限切换主视频,并携带已读取的生效版本作并发检查。 + * @param shotId 镜头 ID + * @param videoId 候选 ID + * @param expectedMotionPlanRevisionId 已查询的当前动作版本 + * @returns 后端确认后的主视频 + */ + setPrimaryVideo: (shotId: string, videoId: string, expectedMotionPlanRevisionId?: string | null) => request(`${shotPath(shotId)}/videos/${encodeURIComponent(videoId)}/primary`, { - method: 'PUT' + method: 'PUT', + body: expectedMotionPlanRevisionId === undefined ? {} : { expectedMotionPlanRevisionId } }) } diff --git a/src/features/production/components/QualityDialog.vue b/src/features/production/components/QualityDialog.vue index a1a7d77..ebbe4c8 100644 --- a/src/features/production/components/QualityDialog.vue +++ b/src/features/production/components/QualityDialog.vue @@ -1,4 +1,5 @@ @@ -75,10 +76,24 @@ const canSelect = computed(

{{ item.isPrimary ? '主视频' : '候选视频' }} - 需更新 + 需更新 {{ item.durationSeconds || durationSeconds || '—' }}s
+

{{ item.staleReason }}

+

+ 生成动作版本 {{ item.motionPlanRevisionId ?? 'AI 原始' }} · 当前 + {{ item.currentMotionPlanRevisionId ?? 'AI 原始' }} +

{{ previousValidation ? '此前画面检查通过' : '此前画面检查未通过' }}

@@ -87,9 +102,23 @@ const canSelect = computed( {{ item.provider }} · {{ item.model }} · {{ formatDate(item.createdAt) }}

- + 质量检查 + 创建修复候选 查看质量记录 设为主视频 diff --git a/src/features/production/components/VideoQualityDiagnostics.vue b/src/features/production/components/VideoQualityDiagnostics.vue index e56c90b..446488f 100644 --- a/src/features/production/components/VideoQualityDiagnostics.vue +++ b/src/features/production/components/VideoQualityDiagnostics.vue @@ -7,6 +7,7 @@ import { useQuery } from '../../../composables/useQuery' import { formatDate } from '../../../lib/format' import { videoDiagnosticsApi } from '../diagnostics-api' import { videoQualityStatusLabel } from '../model' +import { videoInputStaleReason } from '../production-messages' import type { VideoQualityRollbackTarget } from '../diagnostics.types' /** 视频诊断绑定正式镜头与用户选中的视频,随弹窗挂载直接读取。 */ @@ -15,8 +16,10 @@ const props = defineProps<{ shotId: string /** 用户选中的视频 ID。 */ videoId: string - /** 当前视频是否因首帧或参考图变化而需要更新。 */ + /** 当前视频是否因首帧、参考图或动作规划版本等输入变化而需要更新。 */ stale: boolean + /** 当前资产公开的过期原因,普通候选也可能不在自动链中。 */ + staleReason?: string | null }>() /** 查询目标包含镜头和视频,切换目标后取消旧请求。 */ const key = computed(() => (props.shotId && props.videoId ? JSON.stringify([props.shotId, props.videoId]) : '')) @@ -37,6 +40,15 @@ const query = useQuery(key, async (value, signal) => { const detail = computed(() => query.data.value?.detail) /** 当前视频的独立记录,不能使用其它候选或流程整体结果兜底。 */ const currentRecord = computed(() => detail.value?.chain.find(item => item.videoId === props.videoId)) +/** 当前候选的终态优先于保留的历史通过证据。 */ +const currentStale = computed( + () => + props.stale || + !!currentRecord.value?.motionPlanStale || + currentRecord.value?.qualityTerminalStatus === 'stale_motion_plan' +) +/** 仅展示当前候选的具体原因,不能套用最新候选的原因。 */ +const reason = computed(() => currentRecord.value?.staleReason || props.staleReason || videoInputStaleReason) /** 当前视频优先展示,其它候选明确标识为相关记录。 */ const orderedChain = computed(() => { const chain = detail.value?.chain ?? [] @@ -69,8 +81,8 @@ function rollbackLabel(target: VideoQualityRollbackTarget) {