feat: 预览生成 API 传入 voice_library_id（配音素材 ID） #1314

Merged

auto-approve-bot merged 7 commits from feat/voice-library-id-in-preview into develop 2026-08-09 12:31:00 +08:00

Conversation 5 Commits 7 Files Changed 3

+8

xiaoxia commented 2026-08-09 12:08:44 +08:00

Owner

Copy Link

Copy Source

变更说明

调用 POST /api/v1/generation/preview 时，将用户在配音页面选择的音频素材 ID 传入 voice_library_id 字段。

后端已在 PR #1313 中支持该字段（CreatePreviewGenerationTaskRequest.voice_library_id），本次补齐前端对接。

修改文件

1. apps/web/src/api/generation/types.ts

   • CreatePreviewRequest 新增可选字段 voice_library_id?: string

2. apps/web/src/pages/generate/hooks/useStep4Preview.ts

   • UseStep4PreviewProps 新增 voiceLibraryId?: string 入参
   • createPreview 调用时传入 voice_library_id

3. apps/web/src/pages/generate/GeneratePage.tsx

   • 将 previewVoiceIds[0]（用户选择的配音素材 ID）作为 voiceLibraryId 传给 useStep4Preview

数据流

Step5VoiceSelect → selectedVoice（素材ID）
  → GeneratePage → previewVoiceIds[0]
    → useStep4Preview → voiceLibraryId
      → createPreview → voice_library_id
        → 后端渲染时使用该素材的音频

## 变更说明 调用 `POST /api/v1/generation/preview` 时，将用户在配音页面选择的音频素材 ID 传入 `voice_library_id` 字段。 后端已在 PR #1313 中支持该字段（`CreatePreviewGenerationTaskRequest.voice_library_id`），本次补齐前端对接。 ## 修改文件 1. **`apps/web/src/api/generation/types.ts`** - `CreatePreviewRequest` 新增可选字段 `voice_library_id?: string` 2. **`apps/web/src/pages/generate/hooks/useStep4Preview.ts`** - `UseStep4PreviewProps` 新增 `voiceLibraryId?: string` 入参 - `createPreview` 调用时传入 `voice_library_id` 3. **`apps/web/src/pages/generate/GeneratePage.tsx`** - 将 `previewVoiceIds[0]`（用户选择的配音素材 ID）作为 `voiceLibraryId` 传给 `useStep4Preview` ## 数据流 ``` Step5VoiceSelect → selectedVoice（素材ID） → GeneratePage → previewVoiceIds[0] → useStep4Preview → voiceLibraryId → createPreview → voice_library_id → 后端渲染时使用该素材的音频 ```

xiaoxia added 3 commits 2026-08-09 12:08:44 +08:00

feat: 添加 voice_library_id 到 CreatePreviewRequest 4f9a873513

feat: useStep4Preview 传递 voice_library_id 到预览 API a2d72d8da4

feat: 将用户选择的配音素材 ID 传入预览 API 的 voice_library_id 0bd910c9b3

gitea-actions bot commented 2026-08-09 12:10:10 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

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

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

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

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

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

xiaoxia added 1 commit 2026-08-09 12:13:06 +08:00

fix: 添加 voiceLibraryId 到 useCallback 依赖数组 fd3eb76024

xiaoxia added 1 commit 2026-08-09 12:16:57 +08:00

fix: types.ts Prettier 格式修复（末尾单换行） b1eebf7dd9

auto-approve-bot approved these changes 2026-08-09 12:19:19 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-08-09 12:19:19 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

xiaoxia added 1 commit 2026-08-09 12:26:04 +08:00

fix: voiceLibraryId 改用 selectedVoice，不与 previewVoiceIds 混用 335502b673

xiaoxia added 1 commit 2026-08-09 12:26:31 +08:00

fix: 确保 GeneratePage.tsx 末尾有换行符 3ebfb724b2

auto-approve-bot commented 2026-08-09 12:28:23 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

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

📊 审查概览

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

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

无

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

1. [apps/web/src/pages/generate/hooks/useStep4Preview.ts: 338] 空值处理逻辑一致性

   • 具体内容：代码中对 voice_ids 使用了显式的长度检查 voiceIds && voiceIds.length > 0，而对新增的 voice_library_id 使用了隐式真值检查 voiceLibraryId || undefined。虽然功能上在大多数情况下等效（都能过滤空字符串），但为了代码风格统一，建议显式处理空字符串，例如：voice_library_id: voiceLibraryId || undefined 改为 voice_library_id: voiceLibraryId ? voiceLibraryId : undefined，或者保持现状但确认 ID 不会是数值字符串 "0"（因为 || 会将 "0" 判定为 false）。

2. [apps/web/src/pages/generate/GeneratePage.tsx: 109] 业务逻辑互斥性确认

   • 具体内容：在调用 useStep4Preview 时同时传递了 voiceIds 和 voiceLibraryId。请确认业务逻辑上这两个参数是否互斥（即用户要么选择系统配音 voiceIds，要么选择素材库配音 voiceLibraryId）。如果两者同时存在，需确认后端 API 的优先级处理逻辑，避免产生不可预期的混合结果。

✅ 良好实践

• 类型定义（types.ts）更新及时，且包含了清晰的 JSDoc 注释，有助于维护。
• 在 GeneratePage 和 useStep4Preview 中均正确处理了可选参数的传递，保持了数据流的完整性。
• 依赖数组中正确添加了新的依赖项 voiceLibraryId，符合 React Hooks 规则。

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-08-09 04:28:23 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：否 - 阻塞级问题数量：0 个 ### 📊 审查概览 - 整体评价：通过 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 无 ### 💡 改进建议（不阻塞合并） 1. **[apps/web/src/pages/generate/hooks/useStep4Preview.ts: 338] 空值处理逻辑一致性** - 具体内容：代码中对 `voice_ids` 使用了显式的长度检查 `voiceIds && voiceIds.length > 0`，而对新增的 `voice_library_id` 使用了隐式真值检查 `voiceLibraryId || undefined`。虽然功能上在大多数情况下等效（都能过滤空字符串），但为了代码风格统一，建议显式处理空字符串，例如：`voice_library_id: voiceLibraryId || undefined` 改为 `voice_library_id: voiceLibraryId ? voiceLibraryId : undefined`，或者保持现状但确认 ID 不会是数值字符串 "0"（因为 `||` 会将 "0" 判定为 false）。 2. **[apps/web/src/pages/generate/GeneratePage.tsx: 109] 业务逻辑互斥性确认** - 具体内容：在调用 `useStep4Preview` 时同时传递了 `voiceIds` 和 `voiceLibraryId`。请确认业务逻辑上这两个参数是否互斥（即用户要么选择系统配音 `voiceIds`，要么选择素材库配音 `voiceLibraryId`）。如果两者同时存在，需确认后端 API 的优先级处理逻辑，避免产生不可预期的混合结果。 ### ✅ 良好实践 - 类型定义（`types.ts`）更新及时，且包含了清晰的 JSDoc 注释，有助于维护。 - 在 `GeneratePage` 和 `useStep4Preview` 中均正确处理了可选参数的传递，保持了数据流的完整性。 - 依赖数组中正确添加了新的依赖项 `voiceLibraryId`，符合 React Hooks 规则。 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-09 04:28:23 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

auto-approve-bot merged commit d9c5281f46 into develop 2026-08-09 12:31:00 +08:00

auto-approve-bot deleted branch feat/voice-library-id-in-preview 2026-08-09 12:31:00 +08:00

gitea-actions bot commented 2026-08-09 12:32:05 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

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

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

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