Files
short-drama-agent-front/docs/audits/v8-10-frontend-integration-2026-11-18.md

127 lines
14 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# V8-10.2~V8-10.12 前端接入交接
## 范围与基线
- 前端根目录 `dev`,起点 `f6edc4eb708b0f69b078b6c74b5d1ca3d6eb8e30`,起始干净;只修改前端,没有创建 worktree。
- 后端契约基线 `fd0ab65c3c2d78032cdf8c243621df2941315e40`。收尾只读核对时为 `1f9ceace`,相对基线仅增加第三张图片执行审计等文档,没有修改本轮接口。后端另有并行质量审计文档未提交,本轮没有改动它们。
- 已核对用户指定四份公开 API、四份前端 Prompt,以及实际授权 Schema/Repository、图片 Provider/Storyboard/Video Router 和相应服务。
- 所有写入验收使用隔离 Mock。正式项目仅 GET;没有启动图片、文本、Vision、Repair、视频、Primary 或历史 unknown 重试。
- 开发验收时未提交、未推送;验收后用户已明确授权将本轮全部改动提交并推送到 `dev`。本次集中交付包含新增 9、修改 28、删除 0,共 37 个文件;保留正常提交钩子,最终提交号与远端同步状态以 Git 记录及交付回复为准。
## 已有能力与真实缺口
| 原有实现 | 本轮真实增量 |
| --- | --- |
| standing、additional、精确费用 Preview、撤销、图片费用审计 | bounded 创建、逐镜计划与次数、总次数、原预算、逐项接受 unknown、首帧主动选用 |
| Motion Plan 人工版本、保存、Workflow 起点校验、正式采用 | failed_candidate 根与 manual 子、null 原指针、原 Task/Workflow/公开回执、完整来源预检、精确起点计划指纹 |
| Provider 按需能力检查、实际生成 Preview | 容量 409 撤销旧成功状态、保留实际阻断和公开上限 |
| 原普通摄影草案、联合采用、视线与场景沿用、草案历史 | 已有失败图片下的 composition/cameraPosition 修订、完整差异/历史/相邻版本、采用后正式预览与质量刷新 |
| 机器审核与有效质量、候选管理、历史生成输入原件 | failed/stale 组合摘要、原图片费用按候选读取、来源变化后重新读取质量、候选与历史弹窗交接 |
| 时间语义、正式连续性问题与门禁 | sceneTransition 人工规划确认与真实视频末态分开展示 |
没有新增业务路由、第二套摄影编辑器、时间轴、费用或 Workflow 页面。继续保留 V8-9 的 additional、独立证据/复核、联合环境依据、原历史和来源保护。普通镜头目录无默认勾选,进入分镜页不弹生成配置。
## API 与交互
| 正式 API | 接入结果与边界 |
| --- | --- |
| GET /projects/:id/image-authorizations | 沿原投影读取 standing、additional/bounded、逐镜 usedRequests、inputFingerprint、原 unknown/预留及审计状态 |
| POST /projects/:id/image-authorizations | mode=bounded 严格发送正式 Schema:原 standing、接受的未知请求及 SHA、固定 OpenAI/型号、逐镜 source/plan/options/maxRequests、总次数、期限、两项风险确认、人及说明;不发送新预算 |
| POST /projects/:id/image-authorizations/preview | 用户主动逐镜免费编译,取得真实 Source/费用计划;不是图片生成、质量通过或费用核清 |
| POST /projects/:id/image-authorizations/:authorizationId/revoke | 继续原撤销,显示已用/剩余;撤销、过期、用尽不再允许领取,历史及旧预留不删 |
| POST /storyboard-shots/:id/keyframe | 单镜明确选择许可并再次核对精确预览;bounded 仍使用 additionalAuthorizationId。一次成功停止;同计划完整结果可只读查看 |
| GET /storyboard-shots/:id/keyframe-provider-capability、GET /image-providers/capabilities | 按需检查,409 清旧 capability 和实际生成预检。实际需要数量沿后端业务错误展示,Provider 上限来自公开能力;不丢必需参考或换模型 |
| GET /storyboard-shots/:id/video-prompt/preview、GET /video-prompt/executions/:taskId | 免费发现/只读核对原失败候选;原 SDK 未公开全文不伪造,展示公开 observations、steps、usage、Task/Workflow/质量 |
| GET /motion-plan/revisions、POST /revisions/preview、POST /revisions | failed_candidate 根与 manual 子保持区分,originalRevisionId=null 合法。先免费预检再明确保存;保存不启动起点模型或正式采用 |
| POST /revisions/:id/start-state-validation/start、PUT /revisions/:id/active | 起点前再次免费核对完整计划,发送 expectedPlanFingerprint;只有当前保存版本、主首帧和来源匹配的有效证据才可独立采用。复用旧 Workflow/SSE,不自动生成 Video Prompt/视频 |
| POST /projects/:id/storyboard-derived-reviews/confirm | 下游摄影沿原普通模式,仅 composition/cameraPosition;不发送 jointRevision 或 direction-only phase,其他正式字段原样保留。保存和正式采用独立 |
| GET keyframes、quality-review、validations、generation-input | 资产列表只来自真实 keyframes;未执行计划不变成候选。旧图可查看原输入、机器结论、当前有效质量;费用在原历史中按 project/Shot/candidateId 精确过滤授权账本 |
- bounded 只使用原预算,当前 blocker 必须逐项明确接受且 inputFingerprint 一致;新的未知请求或在途请求继续停止领取。
- 授权期限进入预览快照;页面停留期间到期也撤销旧成功预检,提交时再检查,不用旧许可继续生成。
- 任何能力 valid 仅说明对应输入。费用、规划、起点像素、图片质量、Primary 和正式采用独立。
- `basis=confirmed_plan` 且 `verifiedVideoEndState=false` 展示“人工规划衔接已确认,视频末态尚未验证”,使用中性状态;不推断前镜真实视频尾态。
- `SCENE_CONTINUITY_REVIEW_STALE` 清旧成功预览、保留输入、重新只读来源并等待人工确认;不自动重提。摄影/Motion 409 同样保留人工稿并刷新来源。
- 摄影采用后读取正式 D/VS、草案 Current/Stale、正式 Keyframe Preview 和免费费用计划,并强制刷新原图有效质量。原机器失败与旧图片不被删除或改写。
- 旧 `qualityDecision=failed`、当前 `effectiveQualityStatus=stale` 显示“历史审核未通过,当前来源已变化”。completed 不等于质量 passed,passed 不等于 Primary。
- 长原文、来源/计划/回执与历史使用已有公共折叠。沿用 NMessage、主题变量、就地 loading、固定底栏;候选管理完全关闭后再进入原图历史,避免双重焦点约束。
## 实际文件与职责
新增 9 个文件:
- `src/features/image-authorization/BoundedAuthorizationFields.vue`:原设置中的逐镜有限风险表单,复用原抽屉 footer。
- `src/features/storyboard/components/SceneTransitionEvidence.vue`:分镜与首帧共用的正式人工规划依据展示。
- `tests/features/image-authorization/bounded.test.ts`:范围/期限/次数/原预算/未知集合和显式登记。
- `tests/features/storyboard/failed-motion-candidate.test.ts`:原失败根、人工保存、精确起点及独立采用。
- `tests/features/storyboard/camera-candidate.test.ts`:已有图片的普通摄影保存/采用、质量刷新、409 保留。
- `tests/features/production/v8-10-contract.test.ts`:容量、连续性、failed/stale/Primary、旧图费用和范围隔离。
- `tests/browser/v8-10.html`、`tests/browser/v8-10.ts`:复用真实组件的 Chrome 隔离入口,fetch 全拦截,未知请求 403,绝无真实网络 fallback。
- 本交接文档。
修改 28 个文件:
- `src/features/image-authorization/{ImageAuthorizationSettings.vue,api.ts,model.ts,types.ts}`:登记模式、许可历史、原撤销、正式契约与实际准入。
- `src/features/production/api.ts`:免费正式预览支持已有项目 scope。
- `src/features/production/components/{KeyframeDialog.vue,ModelCapabilities.vue,KeyframePreviewChecks.vue}`:单镜主动选许可、能力阻断、正式规划说明。
- `src/features/production/components/{KeyframeCard.vue,KeyframeValidationHistory.vue,ShotProductionAssets.vue}`:有效质量、只读图片、按候选费用、来源更新与历史弹窗交接。
- `src/features/production/effective-keyframe-quality.ts`:机器历史与当前过期状态的组合摘要。
- `src/features/storyboard/components/{MotionRevisionEditor.vue,ShotDerivedReview.vue,ShotTools.vue}`:复用现有动作、摄影和详情交互。
- `src/features/storyboard/{generation-spec.types.ts,motion-api.ts,motion-revision.ts,motion.types.ts,useMotionRevision.ts}`:正式连续性/失败候选/精确起点计划契约与编排。
- `src/features/subject-images/generation-preview.ts`:旧费用准入清除、衔接冲突及授权到期保护,原 unknown guard 保留。
- `src/lib/{billing-errors.ts,user-facing-text.ts}`:bounded、来源/活动锁的中文反馈,原码保留。
- `tests/features/image-authorization/settings.test.ts`:原 standing 用例按语义标签定位,保留原幂等验证。
- `tests/features/production/quality.test.ts`:公开能力“默认推荐”文案断言。
- `tests/features/storyboard/motion-revision.test.ts`:起点启动正式精确计划指纹。
- `tests/features/subject-images/generation-preview.test.ts`:规划来源冲突与停留到期不收费回归。
- `docs/api-contract-sync.md`:本轮契约同步索引。
删除 0 文件;没有改依赖、锁文件或后端文件。
## 正式 API 只读观察
2026-11-18 本轮 GET 及 Chrome 时点,不是本轮生产或质量结论:
- V02 授权投影 `billingBlocked=true`,unknown 1 条。原 standing 已请求 5 次、剩余 495 次、余额 98,719,355 微美元;一个 additional 已撤销、已用 1、剩余 1;三个 bounded 各已用 1、剩余 0,全部不可再次使用。
- 3.1:originalRevisionId=null、activeRevisionId=null,包含一个 failed_candidate 根和一个 manual 子,均未正式采用;失败根有原 Task/Workflow/回执来源。
- 3.2:三张 completed 候选均非 Primary。最新机器 unknown/有效 blocked;第二张 unknown/unknown;第一张 failed/stale。第三张已由其它任务生成,不能继续写成“只有计划、尚未生成”。
- Chrome 旧图原请求详情:原预留 USD 1、公开用量价 USD 0.076537、实际账单未知;与旧机器失败、当前过期分别展示。
- 后端另一个任务持续更新正式质量审计。最后复验历史交接时服务短暂不可达,页面显示连接失败,不沿用旧成功数据;此前上述 GET/历史读取成功。没有为制造成功状态写入正式数据。
## 自动化与 Chrome 验收
2026-11-18 最终自动化检查:
- `node_modules/.bin/vitest run`:122 个文件、941 项全部通过,77.35 秒。首轮发现两项旧断言(下拉框位置、能力文案)并按真实语义修正;最终重新全量通过,不将首轮结果记为全绿。
- `node_modules/.bin/vue-tsc --noEmit`:通过。
- `node_modules/.bin/vite build`:通过,1.15 秒。
- 修改范围 Oxlint、Vue ESLint、Oxfmt 及 `git diff --check`:通过。
- 新增 28 项测试;覆盖 bounded 范围/预算/旧 unknown/期限/撤销/用尽、Motion 根/子/保存/精确起点/采用/并发、普通摄影兼容/409/完整字段/质量刷新、Provider 容量、规划非视频末态、候选质量/Primary、项目切换与旧图费用隔离、停留授权到期及来源冲突不重发。
测试过程未调用真实模型,未模拟路由一律拒绝。
Chrome 使用已有本地 Google Chrome 与 `localhost:4312`,原生 AX、截图、键鼠和 DevTools Responsive,未使用 Playwright。
- 桌面人工填写 bounded:选择原 standing/Shot,逐镜费用计划,次数 2/总 2、期限/人/理由、逐项 unknown 接受和浮动风险确认;登记前按钮禁用,登记后已用 0/剩余 2、无生图。
- 单镜不默认选许可;显式选择、重新 Preview 后主动模拟生成一次,已用 1/剩余 1,原 standing 预算同步扣减;随后只读查看同计划结果不增加模型请求。
- 撤销剩余许可后显示不可领取,原 unknown、预留及未知实际账单保留。
- failed 候选读取/载入/修改/免费预检/保存分开;创建 failed 根/manual 子,active 仍为空,Vision 0。切换 failed 根后不能直接起点审核或采用。
- Provider 容量阻断实际显示必需 17、上限 16;原成功输入不再展示,确认生成禁用;不删参考、不换模型。
- sceneTransition 仅显示人工规划已确认、视频末态未验证,未显示质量 Passed。
- 摄影构图在原模式保存、免费预览和明确采用,显示完整差异、当前及邻镜版本、摄影历史与原图片/质量;采用不自动生图。
- 390×844 核对首帧、摄影、Motion、bounded 长表单,正文可滚动,标题与底部关闭/提交保持可见,单列字段无横向溢出;恢复桌面响应式设置。
- 正式分镜页进入时没有生成弹窗和目录复选框;真实 3.2 三候选质量区别可见,旧图费用/来源历史可读。候选关闭后原图历史独立接管焦点。
截图(本地验收产物,不进入源码):
- `/Users/goujun/.codex/visualizations/2026/11/15/01a1df1f-2851-7ff2-b840-d1a0f3154f74/v8-10-motion-mobile.png`
- `/Users/goujun/.codex/visualizations/2026/11/15/01a1df1f-2851-7ff2-b840-d1a0f3154f74/v8-10-bounded-mobile.png`
- `/Users/goujun/.codex/visualizations/2026/11/15/01a1df1f-2851-7ff2-b840-d1a0f3154f74/v8-10-real-candidates.png`
## 未接入与验收边界
- 本轮要求的前端能力已接入;真实收费端到端生成、起点 Vision、正式摄影/Motion 采用、真实费用核清均按用户限制未执行。
- 原模型公开接口没有提供 SDK 原始全文时,仅展示正式公开的观察、用量及回执元数据,不补造原件。
- 容量 409 未提供结构化实际数量时保留后端含实际数量的业务原因;不根据前端关键词计算参考数量。
- 完整旧输入沿已有 generation-input 原件展示,缺少记录或 OpenAI 账本匹配不推断为零费用,也不重编译历史输入。