refactor(TtsPanel): TTS配音面板目录化拆分（332→173行, -48%） #1193

Merged

auto-approve-bot merged 25 commits from refactor/tts-panel-split into develop 2026-07-30 12:06:17 +08:00

Conversation 5 Commits 25 Files Changed 9

+347 -18

xiaoxia commented 2026-07-30 09:15:41 +08:00

Owner

Copy Link

Copy Source

变更内容

TTS配音面板组件目录化拆分，降低单文件复杂度：

新增文件

• TtsPanel/index.tsx - 主组件（173行，组合层）
• TtsPanel/constants.ts - 常量（音色分类、配音模式选项）
• TtsPanel/hooks/useTtsPanel.ts - 核心逻辑Hook（音色加载、试听播放、所有配置操作）
• TtsPanel/components/VoiceSelector.tsx - 音色选择器组件
• TtsPanel/components/TtsSlider.tsx - 通用滑块组件

删除文件

• TtsPanel.tsx - 旧单文件（332行，已目录化替代）

变更说明

• 主组件从 332行 → 173行，减少48%
• 保持原有功能和props接口完全不变
• 导入路径保持向后兼容
• Hook层封装了API调用和试听播放逻辑

## 变更内容 TTS配音面板组件目录化拆分，降低单文件复杂度： ### 新增文件 - `TtsPanel/index.tsx` - 主组件（173行，组合层） - `TtsPanel/constants.ts` - 常量（音色分类、配音模式选项） - `TtsPanel/hooks/useTtsPanel.ts` - 核心逻辑Hook（音色加载、试听播放、所有配置操作） - `TtsPanel/components/VoiceSelector.tsx` - 音色选择器组件 - `TtsPanel/components/TtsSlider.tsx` - 通用滑块组件 ### 删除文件 - `TtsPanel.tsx` - 旧单文件（332行，已目录化替代） ### 变更说明 - 主组件从 332行 → 173行，减少48% - 保持原有功能和props接口完全不变 - 导入路径保持向后兼容 - Hook层封装了API调用和试听播放逻辑

xiaoxia added 6 commits 2026-07-30 09:15:41 +08:00

refactor(TtsPanel): 提取常量 3466537bfd

refactor(TtsPanel): 提取核心逻辑Hook 3630907ea4

refactor(TtsPanel): 提取音色选择器组件 194eab7296

refactor(TtsPanel): 提取通用滑块组件 1bcda88635

refactor(TtsPanel): 目录化主组件 5ce1a00e26

refactor(TtsPanel): 删除旧单文件（已目录化） e33cecb33c

xiaoxia added 1 commit 2026-07-30 09:22:39 +08:00

fix: correct types import path 8493d536ca

xiaoxia added 1 commit 2026-07-30 09:22:41 +08:00

fix: correct types import path 6381c21b56

xiaoxia added 1 commit 2026-07-30 09:24:50 +08:00

test: add smoke test 4bd939972e

xiaoxia added 1 commit 2026-07-30 09:24:51 +08:00

test: add smoke test 7c4f133d3f

xiaoxia added 1 commit 2026-07-30 09:24:52 +08:00

test: add smoke test 86eb51b41d

xiaoxia added 1 commit 2026-07-30 09:24:54 +08:00

test: add smoke test 3c681f8eff

xiaoxia added 1 commit 2026-07-30 09:49:59 +08:00

fix: add mounted ref guard for async preview operation 9952cf8061

xiaoxia added 1 commit 2026-07-30 10:03:36 +08:00

fix: correct types import path (missing ../ level) c11c05ec4d

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

fix: add mountedRef guards for async state updates + move play success msg to .then() 7e50baed40

xiaoxia added 1 commit 2026-07-30 10:20:58 +08:00

fix: prettier formatting 48baed8231

xiaoxia added 1 commit 2026-07-30 10:20:59 +08:00

fix: prettier formatting d1fc4194d8

xiaoxia added 1 commit 2026-07-30 10:21:00 +08:00

fix: prettier formatting 4806c0a1eb

xiaoxia added 1 commit 2026-07-30 10:21:01 +08:00

fix: prettier formatting 223599914c

xiaoxia added 1 commit 2026-07-30 10:35:49 +08:00

fix: Prettier格式化 aae2c8d319

xiaoxia added 1 commit 2026-07-30 10:47:40 +08:00

fix: useEffect中mountedRef位置修正(open判断后再设为true) cf5253d105

xiaoxia added 1 commit 2026-07-30 11:27:03 +08:00

fix: tooltip formatter空值检查(v!=null) a29a4c3f0a

xiaoxia added 1 commit 2026-07-30 11:27:03 +08:00

fix: useEffect用局部active变量替代mountedRef防竞态 c08d4bda9b

xiaoxia added 1 commit 2026-07-30 11:55:20 +08:00

fix: 移除重复的TtsPanelProps导出（与interface声明冲突） a317eb9ad3

xiaoxia added 1 commit 2026-07-30 11:55:21 +08:00

fix: 修复mountedRef重置+组件卸载音频资源清理（AI Review阻塞问题） c2384132b2

auto-approve-bot commented 2026-07-30 11:59:44 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

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

📊 审查概览

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

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

无

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

1. [apps/web/src/pages/editing-planner/components/TtsPanel/components/TtsSlider.tsx:38] 列表渲染 Key 建议

   • 具体内容：在渲染 marks 时使用了索引 i 作为 key。虽然当前 marks 是静态常量，但在 React 列表渲染中，最佳实践是使用数据本身作为 key（如果唯一），以避免因数组顺序变化导致的潜在渲染问题。建议修改为 key={m}。

2. [apps/web/src/test/pages/editing-planner/components/TtsPanel] 测试覆盖率不足

   • 具体内容：当前新增的测试文件（如 useTtsPanel.test.ts 等）仅为 Smoke test（冒烟测试），仅验证模块能否加载，未覆盖核心逻辑（如 handlePreview 音频播放、handleTextChange 截断逻辑等）。建议补充单元测试以保障重构后的逻辑稳定性。

✅ 良好实践

1. 资源清理：useTtsPanel hook 中正确使用了 audioRef 和 mountedRef 来处理组件卸载时的音频停止和异步状态竞态问题，有效避免了内存泄漏和 setState on unmounted error。
2. 防御性编程：VoiceSelector 组件中在处理 voice 可能不存在的情况时，使用了可选链和逻辑与（voice && ...），保证了在数据未加载完成时的 UI 稳定性。
3. 类型安全：全面使用了 TypeScript 接口定义 Props 和返回值，类型定义清晰。

---

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

### 【阻塞级判定】 - 是否存在阻塞级问题：否 - 阻塞级问题数量：0 个 ### 📊 审查概览 - 整体评价：通过 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 无 ### 💡 改进建议（不阻塞合并） 1. **[apps/web/src/pages/editing-planner/components/TtsPanel/components/TtsSlider.tsx:38] 列表渲染 Key 建议** - 具体内容：在渲染 `marks` 时使用了索引 `i` 作为 key。虽然当前 `marks` 是静态常量，但在 React 列表渲染中，最佳实践是使用数据本身作为 key（如果唯一），以避免因数组顺序变化导致的潜在渲染问题。建议修改为 `key={m}`。 2. **[apps/web/src/test/pages/editing-planner/components/TtsPanel] 测试覆盖率不足** - 具体内容：当前新增的测试文件（如 `useTtsPanel.test.ts` 等）仅为 Smoke test（冒烟测试），仅验证模块能否加载，未覆盖核心逻辑（如 `handlePreview` 音频播放、`handleTextChange` 截断逻辑等）。建议补充单元测试以保障重构后的逻辑稳定性。 ### ✅ 良好实践 1. **资源清理**：`useTtsPanel` hook 中正确使用了 `audioRef` 和 `mountedRef` 来处理组件卸载时的音频停止和异步状态竞态问题，有效避免了内存泄漏和 setState on unmounted error。 2. **防御性编程**：`VoiceSelector` 组件中在处理 `voice` 可能不存在的情况时，使用了可选链和逻辑与（`voice && ...`），保证了在数据未加载完成时的 UI 稳定性。 3. **类型安全**：全面使用了 TypeScript 接口定义 Props 和返回值，类型定义清晰。 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-07-30 03:59:43 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

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

Copy Link

Copy Source

🚀 预览环境已部署

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

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

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

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

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

auto-approve-bot approved these changes 2026-07-30 12:05:45 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-07-30 12:05:45 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot merged commit cfe97ea059 into develop 2026-07-30 12:06:17 +08:00

auto-approve-bot deleted branch refactor/tts-panel-split 2026-07-30 12:06:17 +08:00

gitea-actions bot commented 2026-07-30 12:06:37 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

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

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

🗑️ **预览环境已清理** PR #1193 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 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#1193