xiaoxia-saas/docs/voice-library-refactor-plan.md

VoiceLibrary 页面重构方案

现状分析

当前文件： apps/web/src/pages/voices/VoiceLibrary.tsx — 1783 行

代码质量：

• any: 0 处
• ts-ignore: 0 处
• eslint-disable: 0 处
• TODO: 1 处
• 整体质量良好，重构阻力小

目录结构（重构后）

apps/web/src/pages/voices/
├── VoiceLibrary.tsx        # 主组件（目标：~550 行，-69%）
├── types.ts                 # 类型定义
├── constants.ts             # 常量 + 配置
├── utils/
│   ├── format.ts          # 格式化工具函数
│   └── audio.ts           # 音频工具函数
├── components/
│   ├── VoiceCard.tsx       # 预设音色卡片
│   ├── CloneVoiceCard.tsx  # 克隆音色卡片
│   ├── CloneDetailModal.tsx # 克隆详情弹窗
│   ├── CloneCardSkeleton.tsx # 克隆卡片骨架屏
│   ├── UploadModal.tsx    # 上传音色弹窗
│   ├── TTSModal.tsx       # TTS合成弹窗
│   ├── VoiceFilterBar.tsx # 筛选栏（搜索/性别/语言）
│   └── VoiceTabBar.tsx     # Tab切换栏
└── hooks/
    ├── useVoices.ts        # 音色数据查询 + 筛选
    ├── useAudioPlayer.ts   # 音频播放控制
    ├── useVoiceUpload.ts  # 音色上传逻辑
    ├── useTTS.ts           # TTS合成逻辑
    └── useCloneVoice.ts    # 克隆音色操作

三阶段渐进式重构

Phase 1：抽离类型、常量、工具函数

目标： 主文件 1783 → ~1550 行（-13%）

抽出内容：

1. types.ts — 类型定义（~60行）

   • PresetVoiceDisplay / ClonedVoiceDisplay / VoiceCardProps / CloneVoiceCardProps
   • TabKey / Toast / VoiceUploadMetadata
   • 现有 mapPresetToDisplay / mapCloneToDisplay 数据映射函数

2. constants.ts — 常量配置（~40行）

   • CLONE_STATUS_CONFIG 克隆状态配置
   • GENDER_LABEL_MAP / LANGUAGE_LABEL_MAP 性别/语言标签映射
   • Tab 配置项

3. utils/format.ts — 格式化工具（~25行）

   • formatTime 时长格式化
   • formatFileSize 文件大小格式化
   • genderLabel / languageLabel / genderClass

4. utils/audio.ts — 音频工具（~15行）

   • getAudioDuration 获取音频文件时长

5. format.test.ts — 工具函数单测

   • 覆盖 formatTime / formatFileSize 等纯函数

Phase 1 交付：

• 新增文件：6 个（types.ts / constants.ts / utils/format.ts / utils/audio.ts / format.test.ts）
• 主文件减少：~230 行
• 纯机械抽离，无逻辑改动

---

Phase 2：抽离子组件

目标： 主文件 1550 → ~950 行（-39%）

抽出组件：

1. components/VoiceCard.tsx — 预设音色卡片（~120行）

   • 卡片渲染：头像、名称、性别标签、播放按钮、进度条、收藏
   • Props：voice / playingId / currentTime / onPlay / onPause / onSeek / onToggleStar

2. components/CloneVoiceCard.tsx — 克隆音色卡片（~160行）

   • 三种状态：processing / success / failed
   • 操作：播放、详情、删除、重试、使用
   • Props：voice / playingId / currentTime / onPlayPause / onShowDetail / onDelete / onRetry / onUse

3. components/CloneDetailModal.tsx — 克隆详情弹窗（~90行）

   • 展示克隆音色详细信息
   • 状态展示、音频播放、操作按钮

4. components/CloneCardSkeleton.tsx — 克隆卡片骨架屏（~20行）

   • 加载状态占位

5. components/UploadModal.tsx — 上传音色弹窗（~180行）

   • 文件选择、名称/性别/描述填写
   • 上传进度展示
   • Props：open / onClose / onUpload

6. components/TTSModal.tsx — TTS合成弹窗（~170行）

   • 文本输入、音色选择、语速调节
   • 合成状态轮询（idle/synthesizing/done/error）
   • 保存到素材库
   • Props：open / onClose / onSave

7. components/VoiceFilterBar.tsx — 筛选栏（~80行）

   • 搜索框、性别筛选、语言筛选
   • Props：searchText / filterGender / filterLang / onChange handlers

Phase 2 交付：

• 新增组件：7 个
• 主文件减少：~600 行
• 纯UI抽离，业务逻辑保留在主组件

---

Phase 3：抽离业务逻辑 Hook

目标： 主文件 950 → ~550 行（-42%）

抽出 Hook：

1. hooks/useVoices.ts — 音色数据 Hook（~200行）

   • 三个 useQuery：presetVoices / cloneVoices / materialVoices / unifiedStats
   • 筛选逻辑：searchText / filterGender / filterLang → filteredPreset / filteredClone
   • 统计数据：presetCount / cloneCount / materialCount
   • 收藏切换 handleToggleStar
   • 返回：data / loading / filtered / counts / handlers

2. hooks/useAudioPlayer.ts — 音频播放控制 Hook（~120行）

   • playingId / currentTime / intervalRef 状态
   • handlePlay / handlePause / handleSeek
   • 自动停止（切换新音频时停止旧的）
   • 组件卸载清理
   • 注意：与 VoiceMaterialLibrary 的 useAudioPlayer 类似但有差异（一个操作DOM音频，一个操作audio元素），评估是否复用还是独立

3. hooks/useVoiceUpload.ts — 音色上传 Hook（~120行）

   • uploadFile / uploadName / uploadGender / uploadDesc / uploadProgress 状态
   • uploadMutation（上传文件 + 创建音色）
   • buildVoiceMetadata 元数据构建
   • getAudioDuration 时长获取
   • 成功后刷新列表 + toast 关闭弹窗

4. hooks/useTTS.ts — TTS合成 Hook（~110行）

   • ttsOpen / ttsText / ttsVoiceId / ttsSpeed 弹窗状态
   • ttsJobId / ttsStatus / ttsAudioUrl / ttsError 合成状态
   • handleTtsSynthesize 发起合成 + 轮询
   • handleTtsSave 保存到素材库
   • handleTtsClose 清理状态

5. hooks/useCloneVoice.ts — 克隆音色操作 Hook（~80行）

   • deleteMutation / retryMutation
   • handleCloneDelete / handleCloneRetry
   • detailVoice 详情状态
   • 操作后刷新列表

Phase 3 交付：

• 新增 Hook：5 个
• 主文件减少：~400 行
• 主文件只剩：Tab切换逻辑 + JSX 组装 + 顶层状态编排

---

最终效果汇总

阶段	主文件行数	减少行数	减少比例	新增文件
初始	1783	—	—	—
Phase 1	~1550	-233	-13.1%	5
Phase 2	~950	-600	-38.7%	7
Phase 3	~550	-400	-42.1%	5
总计	~550	-1233	-69.2%	17

与 GeneratePage / VoiceMaterialLibrary 的异同

相同点：

• 三阶段渐进式重构（类型常量 → 组件 → Hook）
• 每阶段独立PR，独立验证
• 每阶段加 smoke test 保证 vitest related 模式可用
• 代码质量基线高（0 any / 0 ts-ignore）

不同点：

• VoiceLibrary 有两个数据源（预设音色 + 克隆音色），还有TTS和上传功能
• 音频播放逻辑与 VoiceMaterialLibrary 类似但操作的音频类型不同
• 有 CloneModal 是外部组件（已在 @/components/voice/CloneModal），不需要重写
• 骨架屏组件比较简单

风险与注意事项

1. vitest related 模式：每阶段新增文件需建立测试覆盖，避免 "No test files found"
2. Preview Deploy：环境问题导致失败，不影响代码质量
3. 音频播放逻辑：VoiceLibrary 和 VoiceMaterialLibrary 的播放控制类似但是两套独立实现，后续可考虑抽象为共享 Hook
4. 克隆状态：CLONE_STATUS_CONFIG 是核心常量，抽离时注意类型完整
5. 上传逻辑：uploadMutation 内部逻辑较复杂（上传文件 + 获取时长 + 创建音色），抽 Hook 时保持逻辑不变