合并主分支

解决简单冲突
2026-08-06 18:54:32 +08:00
parent fa02c366a9 281c84b7bf
commit 2b8ced9195
55 changed files with 11232 additions and 270 deletions
@@ -0,0 +1,188 @@
+# 音频生成 Composer 恢复共享分流方案
+
+日期：`2026-08-06`
+
+状态：`已实施`
+
+## 一、目标
+
+图片画布的音效与背景音乐恢复使用同一个音频 composer。`ImageCanvasGenerationComposerView.tsx` 内只保留一个 `ImageCanvasAudioGenerationComposerView`，并在组件内定义：
+
+```ts
+const isSoundEffect = dialog.mode === 'audio-sound-effect';
+```
+
+`isSoundEffect === true` 渲染现有 SFX 分支，`isSoundEffect === false` 渲染现有 BGM V1 分支。删除完整的独立 BGM composer 文件，但保留确有独立职责的 BGM 纯模型、助手 controller 和预设跑马灯组件。
+
+这次只调整前端视图组织方式，不改变任何生成契约、业务规则、请求时序、计费或持久化语义。
+
+## 二、范围与非目标
+
+### 2.1 必须保留的 BGM 能力
+
+- `gpt_description_prompt` 可见原文、Unicode `White_Space` canonicalization 和 200 字生成限制。
+- 30 个预设、字符计数、AI 补全、一键简化和单层交换式撤销。
+- AI 处理锁、同步正式提交锁、`generating` 锁和迟到响应隔离。
+- 稳定 dialog ID、账号 / 项目 scope 校验和按 dialog ID 写回。
+- 固定 `Suno`、当前动态泥点价格和隐藏 `make_instrumental` 的现状。
+
+### 2.2 必须保持不变的现有 SFX 能力
+
+- 固定 Vidu `audio1.0`，Prompt 同值映射到现有 `prompt + sound` 请求字段。
+- `2–10` 秒、步长 `1` 秒、默认 `5` 秒。
+- 当前 Prompt 规范化、全空白时回退“游戏音效”、1500 字限制、价格和失败态。
+- 现有提交 callback、生成占位和完成链路。
+- SFX 中不出现 Suno、BGM 预设、AI 补全、一键简化、BGM 字符计数或撤销。
+
+### 2.3 本次明确不做
+
+- 不实现 SFX V2 独有的一键优化、自动中译英、ElevenLabs、自动时长、30 秒、Loop 或 SFX 预设。
+- 不修改 BGM 或 SFX 需求原文。
+- 不修改 BFF、队列、`platform-audio`、External v1、OpenAPI、SpacetimeDB schema、计费或重试。
+- 不把 BGM Prompt controller 泛化为音频通用 controller。
+- 不新建配置驱动的 composer 框架、第二套音频组件或其它顺带重构。
+
+## 三、当前问题
+
+当前 `ImageCanvasGenerationComposerView.tsx` 分别渲染 SFX 内部组件和 `ImageCanvasBackgroundMusicGenerationComposerView.tsx`。这层完整视图拆分让同一个音频入口形成两套 composer 边界，而 SFX V2 需求已经表明预设、AI 写回、撤销和锁定等交互并非 BGM 永久独占，继续用“BGM 专属交互较多”作为完整组件分叉理由不再成立。
+
+同时，最近一次合并把共享架构中的 `isSoundEffect` 条件表达式带回了当前 SFX-only 组件，却没有带回变量定义，形成 `isSoundEffect is not defined`。该问题不是增加一个局部常量后就可以收口的长期架构问题；本次重构应恢复单一音频组件，使变量与它控制的两个分支重新处于同一组件边界。
+
+## 四、目标结构
+
+```text
+ImageCanvasEditorView
+└─ useImageCanvasGenerationSurface
+   └─ ImageCanvasGenerationComposerView
+      └─ ImageCanvasAudioGenerationComposerView
+         ├─ isSoundEffect === true  → 现有 SFX UI 与行为
+         └─ isSoundEffect === false → 现有 BGM V1 UI 与行为
+            └─ ImageCanvasBackgroundMusicPresetMarquee
+```
+
+继续保留的 BGM 专项模块：
+
+- `ImageCanvasBackgroundMusicPromptModel.ts`：canonicalization、计数、动作资格和 dialog 类型收窄。
+- `useImageCanvasBackgroundMusicPromptAssist.ts`：按 dialog ID 隔离的异步助手状态与提交锁。
+- `ImageCanvasBackgroundMusicPresetModel.ts`：30 个预设与追加规则。
+- `ImageCanvasBackgroundMusicPresetMarquee.tsx`：展开、滚动、hover、触摸和 reduced-motion。
+
+删除的完整视图模块：
+
+- `ImageCanvasBackgroundMusicGenerationComposerView.tsx`
+- `ImageCanvasBackgroundMusicGenerationComposerView.test.tsx`
+
+删除测试文件不等于删除覆盖；其中全部用例必须迁入总 composer 测试。
+
+## 五、实现边界
+
+### 5.1 单一渲染入口
+
+`ImageCanvasGenerationComposerView` 对 `audio-sound-effect` 与 `audio-background-music` 只保留一个渲染条件和一个 `ImageCanvasAudioGenerationComposerView` 调用。组件内部以 `isSoundEffect` 选择两棵现有表单子树，不为本次重构新造配置层。
+
+共享组件使用基于 dialog ID 与 mode 的稳定 `key`。连续切换 BGM dialog 时，预设展开、滚动、hover 和触摸状态不得继承；从 SFX 切到 BGM 时，音效时长菜单状态也不得泄漏。
+
+### 5.2 Hook 与类型安全
+
+- React Hook 不得放进 `isSoundEffect` 条件分支。`useState`、`useRef`、`useId` 和 `useImageCanvasFloatingOptionDismiss` 保持固定调用顺序。
+- `GenerateDialogState` 不是可判别联合。BGM 分支继续通过 `toBackgroundMusicGenerationDialog` 取得带稳定 ID 的 `BackgroundMusicGenerationDialogState`。
+- BGM 缺少稳定 ID 或 `backgroundMusicPromptAssist` 时失败关闭，不渲染不完整的 BGM 表单；SFX 不依赖这两个条件。
+
+### 5.3 两套状态写回不得合并
+
+- SFX 继续走现有 `setGenerateDialog` 路径，保持按 mode 更新、失败态复位和时长写回语义。
+- BGM 继续走 `updateCanvasGenerationDialogById(dialog.id, updater)`，不能降级成只比较 mode。助手响应、预设、撤销和提交锁仍按稳定 dialog ID 隔离。
+- `backgroundMusicPromptAssist` 可以继续由 surface 传给共享 composer，但只允许 BGM 分支读取或调用。
+
+### 5.4 锁定与提交资格不得串用
+
+|分支|锁定条件|生成资格|
+|---|---|---|
+|SFX|沿用现有 `dialog.status === 'generating'`|沿用现有 SFX 提交入口和默认 Prompt 规则|
+|BGM|AI processing、`submitting` 或 `generating` 任一成立|沿用 canonical Prompt 的有效字符与 `1–200` code point 规则|
+
+BGM 使用 `PlatformTextField + readOnly + aria-invalid`；SFX 继续使用 `AutoGrowTextArea + disabled`。本次不统一这两个输入控件，也不改错误、可访问名称或按钮文案。
+
+## 六、预计代码改动
+
+|文件|最小改动|
+|---|---|
+|`ImageCanvasGenerationComposerView.tsx`|恢复共享 `ImageCanvasAudioGenerationComposerView` 与 `isSoundEffect`；移入现有 BGM JSX、常量和依赖；删除独立 BGM import 与双渲染入口|
+|`ImageCanvasGenerationComposerView.test.tsx`|迁入独立 BGM composer 的全部测试，并增加双 mode 隔离与切换回归|
+|`ImageCanvasBackgroundMusicGenerationComposerView.tsx`|删除|
+|`ImageCanvasBackgroundMusicGenerationComposerView.test.tsx`|覆盖迁完后删除|
+|`useImageCanvasBackgroundMusicPromptAssist.ts`|只修正指向独立 composer 的历史注释；不改 controller 行为|
+
+以下生产文件预计不改：`useImageCanvasGenerationSurface.tsx` 的现有 props 接线、BGM Prompt / 预设模型、预设跑马灯、submission workflow、submission model、dialog model、`src/index.css` 的现有 BGM 样式，以及全部后端代码。
+
+如实施时发现必须超出该清单才能保持现有行为，应先停下并重新确认边界，不能借本次组件归并顺带重构。
+
+## 七、测试迁移与回归矩阵
+
+### 7.1 BGM 原覆盖完整迁移
+
+独立组件测试中的下列覆盖必须逐项迁入 `ImageCanvasGenerationComposerView.test.tsx`：
+
+- canonical preview 计数、超限展示和不改写输入框。
+- 0 / 1 / 2 个有效字符及 200 / 201 / 2000 / 2001 边界。
+- 补全、简化、撤销和预设按正确 dialog ID 路由。
+- `preparePreset` 拒绝时不写回，预设成功时沿用追加和清快照语义。
+- 助手错误与生成错误的展示顺序。
+- Suno、泥点价格、生成允许 / 拒绝。
+- `completing`、`simplifying`、`submitting`、`generating` 锁定。
+- 完整单层撤销按钮矩阵和现有可访问属性。
+
+### 7.2 mode 隔离与切换
+
+- SFX 渲染时不存在 BGM 控件，也不存在本次明确排除的 SFX V2 控件。
+- BGM 渲染时不存在 Vidu 和音效时长控件。
+- SFX 仍保持 `audio1.0`、2–10 秒、默认 5 秒、当前价格和既有提交参数。
+- BGM dialog A 展开预设后切到 dialog B，局部展开与滚动状态不继承。
+- SFX 与 BGM 相互切换时，菜单、锁和 Prompt 助手状态不跨 mode 泄漏。
+- 缺少稳定 ID 或 controller 的 BGM 失败关闭；同样条件不影响 SFX 正常渲染。
+
+### 7.3 最小验证命令
+
+```powershell
+npm run test -- src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasBackgroundMusicPromptModel.test.ts src/components/image-editor/ImageCanvasBackgroundMusicPresetModel.test.ts src/components/image-editor/ImageCanvasBackgroundMusicPresetMarquee.test.tsx src/components/image-editor/useImageCanvasBackgroundMusicPromptAssist.test.tsx
+npm run test -- src/components/image-editor/useImageCanvasGenerationSurface.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx
+npm run typecheck
+npm run check:encoding
+git diff --check
+```
+
+删除旧测试文件后，还要确认测试收集清单中不再引用它。若本次改动触发其它现有图片画布测试失败，只修复由共享 composer 归并直接造成的回归，不扩大到无关模块。
+
+## 八、实施顺序
+
+1. 在总 composer 内恢复共享音频组件、`isSoundEffect` 和单一音频渲染入口。
+2. 原样迁入 BGM 分支，保留按 ID 写回、锁定、错误顺序、Suno 与预设行为。
+3. 迁移独立 BGM 组件测试，并补齐 SFX/BGM 隔离与切换用例。
+4. 删除独立 BGM composer 及其测试文件，修正相关注释与文档引用。
+5. 运行定向测试、typecheck、编码检查和差异检查；实现完成后再把实际结果补入 T6 后续记录。
+
+## 九、完成定义
+
+- 两个音频 mode 均从同一个 `ImageCanvasAudioGenerationComposerView` 渲染，且组件内存在唯一的 `isSoundEffect` 分流。
+- 独立完整 BGM composer 文件和独立测试文件已删除，原测试覆盖无遗漏地迁入总 composer。
+- BGM V1 所有已交付能力与正式提交语义不变。
+- 现有 SFX UI、Prompt、Vidu、时长、价格、校验和提交链路无回归。
+- 没有实现任何 SFX V2 独有功能，没有修改需求原文或后端契约。
+- 规定的定向测试、typecheck、编码检查和 `git diff --check` 全部通过。
+
+## 十、实施结果
+
+2026-08-06 已按本文边界完成：
+
+- `ImageCanvasGenerationComposerView.tsx` 恢复唯一 `ImageCanvasAudioGenerationComposerView`，由组件内 `isSoundEffect` 分流；BGM 继续按稳定 dialog ID 写回，SFX 继续走原 `setGenerateDialog` 路径。
+- 删除 `ImageCanvasBackgroundMusicGenerationComposerView.tsx`，保留 BGM Prompt / 预设纯模型、助手 controller 和预设跑马灯。
+- 把独立组件全部用例迁入 `ImageCanvasGenerationComposerView.test.tsx` 后删除旧测试文件；总 composer 现有 50 项测试同时覆盖 BGM 完整动作矩阵和 SFX/BGM 控件、状态、dialog 切换隔离。
+- 只修正 `useImageCanvasBackgroundMusicPromptAssist.ts` 的组件归属注释；没有修改 controller、surface、submission workflow、样式、后端、契约或需求原文，也没有实现 SFX V2 独有功能。
+
+实际验证：
+
+- Prompt / 预设 / controller / 总 composer：`121/121`。
+- surface 与 submission workflow：`72/72`。
+- `npm run typecheck`、变更文件 ESLint、Prettier、`npm run check:encoding` 和 `git diff --check`：全部通过。
+
+2026-08-06 已执行共享 composer 归并后的浏览器视觉 smoke，未发现阻断性问题；本轮未创建真实音频生成任务或产生扣费。
@@ -4307,6 +4307,12 @@
 - 验证：自动测试使用真实公开 Host/Origin 执行 `initialize`；部署后再从公网域名完成带 Key 的 `initialize`、`tools/list`、`resources/list`、Skill resource 读取和至少一个只读业务 tool 调用。loopback 成功只能证明 MCP 实现和 Key 可用，不能替代公网 Host 验收。
 - 关联：`server-rs/crates/api-server/src/external_mcp.rs`、`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`。

+## 异步任务接受后的刷新回调不能统一套用 dialog 所有权（2026-08-05）
+
+- 现象：正式生成任务已被后端接受，用户随后删除 dialog 或切换项目，任务仍继续并可能扣费，但钱包和任务列表没有刷新；反向问题是账号切换时若 project ID 暂时相同，旧任务可能刷新新账号的任务列表。
+- 原因：把 dialog / canvas 的完整 UI 所有权同时用于账号级钱包和账号内项目级任务列表，或者任务列表只比较 project ID，没有校验账号。
+- 处理：按副作用分层校验。钱包只比较账号；任务列表比较账号加项目；dialog、canvas、asset 和 layer 写回继续比较账号、项目、scope version 与原 dialog。正式请求已接受后，删除 UI 状态不等于取消后端任务。
+- 验证：分别覆盖删除 dialog、同账号切项目、账号 A 切到账号 B 且 project ID 保持相同，以及原账号原项目原 dialog 仍有效的正常回写。
 ## GUI owner 锁不能替代逐 boot 的事件接收端登记（2026-08-05）

 - 现象：GUI 首次启动后 manifest 事件转发正常，但 Runner 被替换为新 boot 后只剩 owner 锁和 endpoint 可用，后台更新不再到达 GUI；或者 attach 响应只确认 owner，客户端却误记当前 boot 已完整登记，后续 ensure 不再重试。
@@ -4327,3 +4333,10 @@
 - 原因：客户端虽在重试中复用 `x-request-id`，队列入口却用随机 job id 生成 dedupe key；前端允许无限追加，api-server 和 provider 用 `.take(...)` 静默截断；`generationInputs.references` 被当成可信持久 provenance。
 - 处理：主站生成 POST 禁止自动重试，把显式复用的稳定 request id 接到队列唯一键并校验 replay payload；所有边界显式拒绝超限，前端还要预留主图槽位、统计在途上传，并在上传完成前拒绝模型切换、画布选图、提交生成、关联源图删除 / 剪切 / 素材删除和面板切换 / 关闭；reservation 必须绑定原面板上下文，批量部分失败时不能丢弃已经持久化的成功项。入队、完美像素及直接创建资源 / 素材时删除客户端 references，执行时按真实参考源和 owner 资源记录重建权威引用。历史任务比较必须兼容仅差已删除 references 的旧 payload，不能只保留旧 hash 却让 payload 比较误报冲突。
 - 验证：覆盖同键同 payload / 不同 payload、普通图片第 6 张、带主图的 GPT-image-2 第 5 张额外引用、provider 6 / 15 张边界、伪造引用删除和 owned 资源 / 素材重建。
+
+## 共享音频 Composer 架构冲突不能按单行选边（2026-08-06）
+
+- 现象：master 的音频 composer 同时承载 SFX 与 BGM，并在组件内定义 `isSoundEffect`；功能分支把 BGM 拆成独立组件后，原组件变成 SFX-only。合并时只把 master 的条件占位表达式带回 SFX-only 组件，没有带回变量定义，最终在测试渲染阶段报 `isSoundEffect is not defined`。
+- 原因：冲突两侧代表不同组件架构，逐行保留看似有用的 JSX 会把一个架构中的局部条件拼进另一个架构。import 排序、格式检查和只覆盖单一 mode 的测试都不能证明这种组合成立。
+- 处理：先确定权威组件边界，再按完整调用链解决冲突。图片画布音频入口当前决策是恢复一个共享 `ImageCanvasAudioGenerationComposerView`，由组件内 `isSoundEffect` 分流；BGM/SFX 的 validator、写回、锁和提交契约仍分别保持。不要只补一个常量后继续维持已经废弃的双 composer 边界。
+- 验证：同时渲染 `audio-sound-effect` 与 `audio-background-music`，覆盖两个 mode 的正向控件和互斥负向断言、dialog / mode 切换、BGM 稳定 ID 与 controller 缺失的失败关闭，并运行 `ImageCanvasGenerationComposerView.test.tsx` 与 typecheck。