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

VoiceMaterialLibrary 页面拆分方案

一、现状摸底

文件： apps/web/src/pages/voice-materials/VoiceMaterialLibrary.tsx 总行数： 1966 行 CSS 文件： apps/web/src/pages/voice-materials/voice-materials.css (1262 行)

代码质量

指标	数量	评价
any 类型	0	✅ 优秀
@ts-ignore	0	✅ 优秀
eslint-disable	0	✅ 优秀
TODO/FIXME	0	✅ 干净

内联组件分布

组件	行数	职责
TagSelector	148行 (197-345)	标签选择器（输入+建议+选择）
MaterialForm	187行 (356-543)	上传/编辑表单（名称/描述/性别/标签/文件）
VoiceMaterialCard	220行 (543-763)	卡片视图 + 音频播放进度条
VoiceMaterialRow	153行 (763-916)	列表视图 + 音频播放进度条
VoiceMaterialLibrary（主组件）	1051行 (916-1966)	页面主逻辑 + 渲染

主组件内部结构（1051行）

• 状态 & hooks：约 230行
  • 数据查询：assets / libraries / tags / presetVoices
  • 视图状态：viewMode / searchText / filterGender / filterTagId
  • 播放状态：playingId / currentTime / audioRef / volume / pausedMaterial
  • 弹窗：uploadOpen / editingMaterial / ttsOpen
  • 批量：selectedIds / uploadProgress / batchCustomTag
  • TTS：ttsText / ttsVoiceId / ttsSpeed / ttsJobId / ttsStatus / ttsAudioUrl / ttsError
• 播放控制函数：约 100行（stopPlayback/startPlayback/handlePlay/handlePause/handleSeek/handleVolumeChange/toggleMute）
• 数据操作函数：约 60行（handleUpload/handleEdit/handleDelete）
• 筛选 & 统计：约 40行（filtered/tagCountMap）
• 批量操作：约 80行（handleToggleSelect/handleSelectAll/handleBatchDelete/handleBatchTag/handleBatchCustomTag）
• TTS 合成：约 70行（handleTtsSynthesize/handleTtsSave）
• 渲染 JSX：约 473行

二、拆分策略

跟 GeneratePage 同样的思路：按职责拆分，功能不变，纯结构优化。

拆分四阶段，每个阶段独立 PR，逐步降低主文件复杂度。

---

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

目标： 把纯数据定义和纯函数抽出去，主文件只留组件。

抽离内容

新文件	内容	行数估计
types.ts	VoiceGender / ViewMode / VoiceMaterial / VoiceAssetMetadata 等类型定义	~40行
constants.ts	MAX_CARD_TAGS / MAX_ROW_TAGS / TAG_VARIANTS / GENDER_OPTIONS	~25行
utils/format.ts	formatDuration / formatFileSize / formatDate / genderLabel / genderIcon / genderClass	~35行
utils/audio.ts	getAudioDuration（纯工具，跟组件无关）	~20行
utils/mappers.ts	mapAssetToMaterial / buildMetadata（数据映射）	~35行

预期效果

• 主文件减少约 155 行（1966 → ~1811）
• 工具函数可复用、可单测

---

Phase 2：抽离已有内联子组件

目标： 把 4 个已经定义好的内联组件拆成独立文件，主文件只保留 VoiceMaterialLibrary 主组件。

抽离内容

新文件	原位置	行数	备注
components/TagSelector.tsx	197-345行	~148行	标签选择器
components/MaterialForm.tsx	356-543行	~187行	上传/编辑表单
components/VoiceMaterialCard.tsx	543-763行	~220行	卡片视图，带播放控制
components/VoiceMaterialRow.tsx	763-916行	~153行	列表视图，带播放控制

播放状态共享方案

Card 和 Row 都有播放进度条（共 ~60行重复代码），但播放状态在主组件里。

方案： 播放状态提升到主组件，Card/Row 只接收 prop 并回调：

• isPlaying / currentTime / onPlay / onPause / onSeek
• 主组件统一管理 audioRef 和播放状态

这样 Card 和 Row 是纯展示组件，播放逻辑集中在主组件。

预期效果

• 主文件减少约 700 行（1811 → ~1111）
• 主组件专注页面逻辑，子组件专注展示

---

Phase 3：主组件拆分 — 业务逻辑抽 Hook

目标： 把主组件里的业务逻辑按领域拆成自定义 Hook，主组件只负责组装。

抽离 Hooks

Hook 文件	职责	管理的状态
hooks/useVoiceMaterials.ts	素材列表查询 + 筛选 + 增删改	assets / searchText / filterGender / filterTagId / uploadMutation / editMutation / deleteMutation
hooks/useAudioPlayer.ts	音频播放控制	playingId / currentTime / volume / audioRef / pausedMaterial
hooks/useBatchOperations.ts	批量操作	selectedIds / handleToggleSelect / handleSelectAll / handleBatchDelete / handleBatchTag
hooks/useTtsSynthesize.ts	TTS 合成逻辑	ttsText / ttsVoiceId / ttsSpeed / ttsJobId / ttsStatus / ttsAudioUrl / ttsError

预期效果

• 主组件减少约 500 行（1111 → ~611）
• 每个 Hook 职责单一，可独立测试
• 主组件变成"组装器"，可读性大幅提升

---

Phase 4：UI 组件细化 — 工具栏 & 弹窗拆分

目标： 把主组件里的大块 JSX 拆成独立 UI 组件。

抽离 UI 组件

组件文件	内容	行数估计
components/LibraryToolbar.tsx	顶部工具栏：搜索框 + 性别筛选 + 视图切换 + 结果计数	~60行
components/TagFilterBar.tsx	标签筛选药丸条（全部 + 各标签计数）	~45行
components/BatchActionBar.tsx	批量操作栏：全选 + 计数 + 批量打标签 + 批量删除	~70行
components/UploadModal.tsx	上传弹窗（包裹 MaterialForm）	~30行
components/EditModal.tsx	编辑弹窗（包裹 MaterialForm）	~30行
components/TtsSynthesizeModal.tsx	AI 配音合成弹窗：文本输入 + 音色选择 + 语速 + 合成结果预览 + 保存	~150行
components/EmptyState.tsx	空状态展示	~20行
components/VoiceMaterialGrid.tsx	卡片视图网格容器	~25行
components/VoiceMaterialList.tsx	列表视图表格容器	~25行

预期效果

• 主组件 JSX 部分减少约 400 行（611 → ~211）
• 每个 UI 组件职责清晰，方便后续迭代

---

三、拆分后文件结构

apps/web/src/pages/voice-materials/
├── VoiceMaterialLibrary.tsx      # 主组件（~211行，组装器）
├── voice-materials.css           # 样式（保持不变，后续再拆）
├── types.ts                      # 类型定义
├── constants.ts                  # 常量
├── utils/
│   ├── format.ts                 # 格式化工具
│   ├── audio.ts                  # 音频工具
│   └── mappers.ts                # 数据映射
├── hooks/
│   ├── useVoiceMaterials.ts      # 素材数据 + 筛选 + 增删改
│   ├── useAudioPlayer.ts         # 音频播放控制
│   ├── useBatchOperations.ts     # 批量操作
│   └── useTtsSynthesize.ts       # TTS合成
└── components/
    ├── TagSelector.tsx           # 标签选择器
    ├── MaterialForm.tsx          # 上传/编辑表单
    ├── VoiceMaterialCard.tsx     # 卡片视图
    ├── VoiceMaterialRow.tsx      # 列表视图
    ├── VoiceMaterialGrid.tsx     # 卡片网格容器
    ├── VoiceMaterialList.tsx     # 列表容器
    ├── LibraryToolbar.tsx        # 顶部工具栏
    ├── TagFilterBar.tsx          # 标签筛选条
    ├── BatchActionBar.tsx        # 批量操作栏
    ├── UploadModal.tsx           # 上传弹窗
    ├── EditModal.tsx             # 编辑弹窗
    ├── TtsSynthesizeModal.tsx    # TTS合成弹窗
    └── EmptyState.tsx            # 空状态

拆分前后对比

指标	拆分前	拆分后	变化
主文件行数	1966	~211	-89%
文件数量	2	22	+20
最大文件	1966行	~220行	-89%
可测试性	低	高	每个Hook/组件可单测

四、实施顺序 & 风险

1. Phase 1：最低风险，纯抽离，零逻辑变化
2. Phase 2：低风险，组件本来就是独立定义的，只是挪位置
3. Phase 3：中风险，Hook 拆分需要仔细梳理状态依赖
4. Phase 4：低风险，JSX 拆分，纯结构调整

每个 Phase 完成后提 PR，CI 全绿再合，跟 GeneratePage 同样节奏。