fix(#1195): 克隆音色增加试听播放功能，预留后端试听接口对接位 #1203

Merged

auto-approve-bot merged 9 commits from fix/clone-voice-playback into develop 2026-07-30 16:11:12 +08:00

Conversation 5 Commits 9 Files Changed 5

+233 -2

xiaoxia commented 2026-07-30 14:05:37 +08:00

Owner

Copy Link

Copy Source

问题

克隆音色不能播放，用户无法试听克隆效果

修改内容

1. CloneVoiceSection.tsx: 每个克隆音色行增加试听播放按钮（播放/暂停切换）
2. useStep5Voice.tsx: 增加克隆音色试听播放逻辑（独立audioRef管理，播放状态与预设音色独立）
3. Step5VoiceSelect.tsx: 传递播放状态和方法给CloneVoiceSection
4. generate.css: 新增克隆音色播放按钮样式

待后端对齐

• 克隆音色试听接口：目前使用 sample_url 字段播放
• 后端专用试听接口就绪后，替换 handlePlayCloneSample 中的音频源获取逻辑即可
• 预计接口：GET /voice-clones/{id}/preview 或 POST /voice-clones/{id}/preview

影响范围

• 智能剪辑第5步配音选择 → 克隆我的声音区域
• 仅前端改动，不影响后端

## 问题 克隆音色不能播放，用户无法试听克隆效果 ## 修改内容 1. **CloneVoiceSection.tsx**: 每个克隆音色行增加试听播放按钮（播放/暂停切换） 2. **useStep5Voice.tsx**: 增加克隆音色试听播放逻辑（独立audioRef管理，播放状态与预设音色独立） 3. **Step5VoiceSelect.tsx**: 传递播放状态和方法给CloneVoiceSection 4. **generate.css**: 新增克隆音色播放按钮样式 ## 待后端对齐 - 克隆音色试听接口：目前使用 `sample_url` 字段播放 - 后端专用试听接口就绪后，替换 `handlePlayCloneSample` 中的音频源获取逻辑即可 - 预计接口：`GET /voice-clones/{id}/preview` 或 `POST /voice-clones/{id}/preview` ## 影响范围 - 智能剪辑第5步配音选择 → 克隆我的声音区域 - 仅前端改动，不影响后端

xiaoxia added 4 commits 2026-07-30 14:05:37 +08:00

fix(#1195): CloneVoiceSection增加试听播放按钮，支持克隆音色试听 09f214d941

fix(#1195): useStep5Voice增加克隆音色试听播放逻辑，预留后端接口位置 950dced40b

fix(#1195): Step5VoiceSelect传递播放状态和方法给CloneVoiceSection c434fc2641

fix(#1195): 增加克隆音色试听播放按钮样式 3e3ebf71ce

gitea-actions bot commented 2026-07-30 14:07:15 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1203
预览链接	https://pr-1203.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1203 | | 预览链接 | [https://pr-1203.preview.xiaoxiajianji.com](https://pr-1203.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

xiaoxia added 1 commit 2026-07-30 14:30:26 +08:00

fix(#1195): 克隆音色播放失败状态修复 + 音频切换竞态防护 + 卸载清理 a19be2e304

xiaoxia added 1 commit 2026-07-30 15:34:54 +08:00

fix(#1195): 音频播放竞态修复 - 回调中校验当前活跃音频实例 71ca97f03a

xiaoxia added 1 commit 2026-07-30 15:41:42 +08:00

fix(#1195): Prettier格式对齐 + 音频实例竞态校验 + 卸载清理 db213d1c35

xiaoxia added 1 commit 2026-07-30 15:41:55 +08:00

fix(#1195): Prettier格式对齐 c206ca04d6

xiaoxia added 1 commit 2026-07-30 16:04:42 +08:00

test(#1195): 添加useStep5Voice smoke test，确保vitest related能关联 599f52403c

auto-approve-bot approved these changes 2026-07-30 16:06:26 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-07-30 16:06:26 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot commented 2026-07-30 16:06:58 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

• 是否存在阻塞级问题：否
• 阻塞级问题数量：0 个

📊 审查概览

• 整体评价：有建议
• 建议级问题数量：2 个

🔴 阻塞级问题（必须修复）

无

💡 改进建议（不阻塞合并）

1. [apps/web/src/pages/generate/hooks/useStep5Voice.tsx: 156] 播放失败时的状态重置

   • 具体内容：在 audio.play().catch(...) 错误处理逻辑中，仅清理了 cloneAudioRef.current，但未重置 playingCloneVoice 状态。
   • 后果：如果用户从声音A切换到声音B，而声音B加载/播放失败，UI状态仍会停留在“正在播放声音B”或“正在播放声音A”（取决于具体时序），导致播放按钮状态与实际不符，用户需再次点击才能修正状态。
   • 修改建议：在 catch 块中添加 setPlayingCloneVoice(null)，确保播放失败时 UI 状态同步重置。

2. [apps/web/src/pages/generate/components/voice/CloneVoiceSection.tsx: 29] Props 命名规范

   • 具体内容：接口 CloneVoiceSectionProps 中的 onPlaySample 回调参数命名为 voiceId，但实际传入的类型是 VoiceClone 对象。
   • 后果：命名具有误导性，voiceId 通常暗示为字符串 ID，而此处为对象，容易引起后续开发者的误解。
   • 修改建议：将参数名修改为 voice 或 voiceClone，使其与类型保持一致。

✅ 良好实践

1. 竞态条件处理：在 useStep5Voice.tsx 中，通过 cloneMountedRef 和 cloneAudioRef.current === audio 的双重校验，有效避免了组件卸载后的状态更新及快速切换音频时的竞态问题，逻辑严谨。
2. 资源清理：useEffect 中正确处理了音频资源的销毁和事件监听器的解绑，防止了内存泄漏。
3. 烟雾测试：新增的测试文件 useStep5Voice.test.tsx 覆盖了 Hook 的基本渲染和导出检查，保证了重构后的代码可被正确导入和调用。

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-07-30 08:06:58 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：否 - 阻塞级问题数量：0 个 ### 📊 审查概览 - 整体评价：有建议 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 无 ### 💡 改进建议（不阻塞合并） 1. **[apps/web/src/pages/generate/hooks/useStep5Voice.tsx: 156] 播放失败时的状态重置** - 具体内容：在 `audio.play().catch(...)` 错误处理逻辑中，仅清理了 `cloneAudioRef.current`，但未重置 `playingCloneVoice` 状态。 - 后果：如果用户从声音A切换到声音B，而声音B加载/播放失败，UI状态仍会停留在“正在播放声音B”或“正在播放声音A”（取决于具体时序），导致播放按钮状态与实际不符，用户需再次点击才能修正状态。 - 修改建议：在 catch 块中添加 `setPlayingCloneVoice(null)`，确保播放失败时 UI 状态同步重置。 2. **[apps/web/src/pages/generate/components/voice/CloneVoiceSection.tsx: 29] Props 命名规范** - 具体内容：接口 `CloneVoiceSectionProps` 中的 `onPlaySample` 回调参数命名为 `voiceId`，但实际传入的类型是 `VoiceClone` 对象。 - 后果：命名具有误导性，`voiceId` 通常暗示为字符串 ID，而此处为对象，容易引起后续开发者的误解。 - 修改建议：将参数名修改为 `voice` 或 `voiceClone`，使其与类型保持一致。 ### ✅ 良好实践 1. **竞态条件处理**：在 `useStep5Voice.tsx` 中，通过 `cloneMountedRef` 和 `cloneAudioRef.current === audio` 的双重校验，有效避免了组件卸载后的状态更新及快速切换音频时的竞态问题，逻辑严谨。 2. **资源清理**：`useEffect` 中正确处理了音频资源的销毁和事件监听器的解绑，防止了内存泄漏。 3. **烟雾测试**：新增的测试文件 `useStep5Voice.test.tsx` 覆盖了 Hook 的基本渲染和导出检查，保证了重构后的代码可被正确导入和调用。 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-07-30 08:06:58 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

auto-approve-bot merged commit e6effdb6f2 into develop 2026-07-30 16:11:12 +08:00

auto-approve-bot deleted branch fix/clone-voice-playback 2026-07-30 16:11:12 +08:00

gitea-actions bot commented 2026-07-30 16:12:04 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1203 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1203 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

auto-approve-bot

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1203