Merge branch 'develop' into refactor/voices-api

将 145 行的 voices.ts 拆分为目录化结构：
- types.ts: 类型定义（统一音色/预设音色/旧接口类型）
- voices.ts: 全部 7 个 API 函数（新统一音色 + 旧接口兼容）
- index.ts: 统一入口 re-export，保持 @/api/voices 路径向后兼容

主入口从 145 行减少到约 30 行，按职责清晰分层。

apps/web/src/api/tts.ts

@@ -0,0 +1,188 @@
+/**
+ * TTS 语音合成 API
+ * 对接后端 /api/v1/tts/* 端点
+ *
+ * 任务 3.14 新增
+ */
+import apiClient from "./client"
+
+/* ── 类型定义 ──────────────────────────────────── */
+
+/** TTS 元数据（合成时附带的扩展信息） */
+export interface TTSMetadata {
+  /** 语音时长（秒） */
+  duration?: number
+  /** 采样率（Hz） */
+  sample_rate?: number
+  /** 语言 */
+  language?: string
+  /** 其他扩展字段 */
+  [key: string]: unknown
+}
+
+/** TTS 合成请求参数 */
+export interface TTSSynthesizeRequest {
+  text: string
+  voice_id?: string
+  output_name?: string
+  language?: string
+  speed?: number
+  voice_model?: string
+  voice_clone_profile_id?: string
+  format?: string
+  metadata?: TTSMetadata
+}
+
+/** TTS 合成创建响应 */
+export interface TTSSynthesizeResponse {
+  job_id: string
+  status: string
+  message: string
+}
+
+/** TTS 任务详情 */
+export interface TTSJob {
+  id: string
+  user_id: string
+  project_id: string | null
+  text: string
+  voice_id: string | null
+  voice_model: string | null
+  voice_clone_profile_id: string | null
+  language: string
+  speed: number
+  output_name: string | null
+  output_audio_url: string | null
+  output_format: string
+  duration_seconds: number | null
+  file_size_bytes: number | null
+  sample_rate: number | null
+  status: string
+  error_message: string | null
+  retry_count: number
+  max_retries: number
+  metadata_: TTSMetadata | null
+  created_at: string
+  updated_at: string
+}
+
+/** TTS 任务状态（轻量轮询用） */
+export interface TTSJobStatus {
+  id: string
+  status: string
+  output_audio_url: string | null
+  error_message: string | null
+  duration_seconds: number | null
+  retry_count: number
+}
+
+/** TTS 任务列表响应 */
+export interface TTSJobListResponse {
+  items: TTSJob[]
+  total: number
+  skip: number
+  limit: number
+}
+
+/** TTS 任务列表查询参数 */
+export interface TTSJobListParams {
+  status?: string
+  skip?: number
+  limit?: number
+}
+
+/* ── API 函数 ──────────────────────────────────── */
+
+/** 创建 TTS 合成任务 */
+export const synthesizeSpeech = async (
+  data: TTSSynthesizeRequest,
+): Promise<TTSSynthesizeResponse> => {
+  const response = await apiClient.post<TTSSynthesizeResponse>("/tts/synthesize", data)
+  return response.data
+}
+
+/** 获取 TTS 任务详情 */
+export const getTTSJob = async (jobId: string): Promise<TTSJob> => {
+  const response = await apiClient.get<TTSJob>(`/tts/jobs/${jobId}`)
+  return response.data
+}
+
+/** 获取 TTS 任务状态（轻量轮询） */
+export const getTTSJobStatus = async (jobId: string): Promise<TTSJobStatus> => {
+  const response = await apiClient.get<TTSJobStatus>(`/tts/jobs/${jobId}/status`)
+  return response.data
+}
+
+/** 获取 TTS 任务列表 */
+export const getTTSJobs = async (params?: TTSJobListParams): Promise<TTSJobListResponse> => {
+  const searchParams = new URLSearchParams()
+  if (params?.status) searchParams.set("status", params.status)
+  if (params?.skip !== undefined) searchParams.set("skip", String(params.skip))
+  if (params?.limit !== undefined) searchParams.set("limit", String(params.limit))
+  const qs = searchParams.toString()
+  const response = await apiClient.get<TTSJobListResponse>(`/tts/jobs${qs ? `?${qs}` : ""}`)
+  return response.data
+}
+
+/** 存为素材请求参数 */
+export interface SaveTtsToLibraryRequest {
+  name?: string
+  tag_ids?: string[]
+}
+
+/** 将 TTS 合成结果保存到配音库 */
+export const saveTtsToLibrary = async (
+  jobId: string,
+  data?: SaveTtsToLibraryRequest,
+): Promise<void> => {
+  await apiClient.post(`/tts/jobs/${jobId}/save-to-library`, data ?? {})
+}
+
+/** 删除 TTS 任务 */
+export const deleteTTSJob = async (jobId: string): Promise<void> => {
+  await apiClient.delete(`/tts/jobs/${jobId}`)
+}
+
+/* ── 音色列表 ──────────────────────────────────── */
+
+/** TTS 音色 */
+export interface TTSVoice {
+  id: string
+  name: string
+  /** 音色分类标签：male/female/young/service/news/emotion */
+  category?: string
+  /** 语言 */
+  language?: string
+  /** 试听 URL */
+  preview_url?: string
+  /** 描述 */
+  description?: string
+}
+
+/** 获取 TTS 音色列表 */
+export const getTtsVoices = async (): Promise<TTSVoice[]> => {
+  const response = await apiClient.get<TTSVoice[]>("/tts/voices")
+  return response.data
+}
+
+/* ── TTS 试听 ──────────────────────────────────── */
+
+/** TTS 试听请求参数 */
+export interface TTSPreviewRequest {
+  text: string
+  voice_id: string
+  speed?: number
+  pitch?: number
+}
+
+/** TTS 试听响应 */
+export interface TTSPreviewResponse {
+  audio_url: string
+  duration?: number
+}
+
+/** TTS 试听 */
+export const previewTts = async (data: TTSPreviewRequest): Promise<TTSPreviewResponse> => {
+  const response = await apiClient.post<TTSPreviewResponse>("/tts/preview", data)
+  return response.data
+}

apps/web/src/api/tts/index.ts

@@ -1,31 +0,0 @@
-/**
- * TTS 语音合成 API — 目录化入口
- * 保持与原 tts.ts 相同导出，向后兼容
- */
-
-// 类型
-export type {
-  TTSMetadata,
-  TTSSynthesizeRequest,
-  TTSSynthesizeResponse,
-  TTSJob,
-  TTSJobStatus,
-  TTSJobListResponse,
-  TTSJobListParams,
-  SaveTtsToLibraryRequest,
-  TTSVoice,
-  TTSPreviewRequest,
-  TTSPreviewResponse,
-} from "./types"
-
-// API 函数
-export {
-  synthesizeSpeech,
-  getTTSJob,
-  getTTSJobStatus,
-  getTTSJobs,
-  saveTtsToLibrary,
-  deleteTTSJob,
-  getTtsVoices,
-  previewTts,
-} from "./jobs"

apps/web/src/api/tts/jobs.ts

@@ -1,72 +0,0 @@
-/**
- * TTS 语音合成 API 函数
- */
-import apiClient from "../client"
-import type {
-  TTSSynthesizeRequest,
-  TTSSynthesizeResponse,
-  TTSJob,
-  TTSJobStatus,
-  TTSJobListResponse,
-  TTSJobListParams,
-  SaveTtsToLibraryRequest,
-  TTSVoice,
-  TTSPreviewRequest,
-  TTSPreviewResponse,
-} from "./types"
-
-/** 创建 TTS 合成任务 */
-export const synthesizeSpeech = async (
-  data: TTSSynthesizeRequest,
-): Promise<TTSSynthesizeResponse> => {
-  const response = await apiClient.post<TTSSynthesizeResponse>("/tts/synthesize", data)
-  return response.data
-}
-
-/** 获取 TTS 任务详情 */
-export const getTTSJob = async (jobId: string): Promise<TTSJob> => {
-  const response = await apiClient.get<TTSJob>(`/tts/jobs/${jobId}`)
-  return response.data
-}
-
-/** 获取 TTS 任务状态（轻量轮询） */
-export const getTTSJobStatus = async (jobId: string): Promise<TTSJobStatus> => {
-  const response = await apiClient.get<TTSJobStatus>(`/tts/jobs/${jobId}/status`)
-  return response.data
-}
-
-/** 获取 TTS 任务列表 */
-export const getTTSJobs = async (params?: TTSJobListParams): Promise<TTSJobListResponse> => {
-  const searchParams = new URLSearchParams()
-  if (params?.status) searchParams.set("status", params.status)
-  if (params?.skip !== undefined) searchParams.set("skip", String(params.skip))
-  if (params?.limit !== undefined) searchParams.set("limit", String(params.limit))
-  const qs = searchParams.toString()
-  const response = await apiClient.get<TTSJobListResponse>(`/tts/jobs${qs ? `?${qs}` : ""}`)
-  return response.data
-}
-
-/** 将 TTS 合成结果保存到配音库 */
-export const saveTtsToLibrary = async (
-  jobId: string,
-  data?: SaveTtsToLibraryRequest,
-): Promise<void> => {
-  await apiClient.post(`/tts/jobs/${jobId}/save-to-library`, data ?? {})
-}
-
-/** 删除 TTS 任务 */
-export const deleteTTSJob = async (jobId: string): Promise<void> => {
-  await apiClient.delete(`/tts/jobs/${jobId}`)
-}
-
-/** 获取 TTS 音色列表 */
-export const getTtsVoices = async (): Promise<TTSVoice[]> => {
-  const response = await apiClient.get<TTSVoice[]>("/tts/voices")
-  return response.data
-}
-
-/** TTS 试听 */
-export const previewTts = async (data: TTSPreviewRequest): Promise<TTSPreviewResponse> => {
-  const response = await apiClient.post<TTSPreviewResponse>("/tts/preview", data)
-  return response.data
-}

apps/web/src/api/tts/types.ts

@@ -1,112 +0,0 @@
-/**
- * TTS 语音合成类型定义
- */
-
-/** TTS 元数据 */
-export interface TTSMetadata {
-  duration?: number
-  sample_rate?: number
-  language?: string
-  [key: string]: unknown
-}
-
-/** TTS 合成请求参数 */
-export interface TTSSynthesizeRequest {
-  text: string
-  voice_id?: string
-  output_name?: string
-  language?: string
-  speed?: number
-  voice_model?: string
-  voice_clone_profile_id?: string
-  format?: string
-  metadata?: TTSMetadata
-}
-
-/** TTS 合成创建响应 */
-export interface TTSSynthesizeResponse {
-  job_id: string
-  status: string
-  message: string
-}
-
-/** TTS 任务详情 */
-export interface TTSJob {
-  id: string
-  user_id: string
-  project_id: string | null
-  text: string
-  voice_id: string | null
-  voice_model: string | null
-  voice_clone_profile_id: string | null
-  language: string
-  speed: number
-  output_name: string | null
-  output_audio_url: string | null
-  output_format: string
-  duration_seconds: number | null
-  file_size_bytes: number | null
-  sample_rate: number | null
-  status: string
-  error_message: string | null
-  retry_count: number
-  max_retries: number
-  metadata_: TTSMetadata | null
-  created_at: string
-  updated_at: string
-}
-
-/** TTS 任务状态（轻量轮询用） */
-export interface TTSJobStatus {
-  id: string
-  status: string
-  output_audio_url: string | null
-  error_message: string | null
-  duration_seconds: number | null
-  retry_count: number
-}
-
-/** TTS 任务列表响应 */
-export interface TTSJobListResponse {
-  items: TTSJob[]
-  total: number
-  skip: number
-  limit: number
-}
-
-/** TTS 任务列表查询参数 */
-export interface TTSJobListParams {
-  status?: string
-  skip?: number
-  limit?: number
-}
-
-/** 存为素材请求参数 */
-export interface SaveTtsToLibraryRequest {
-  name?: string
-  tag_ids?: string[]
-}
-
-/** TTS 音色 */
-export interface TTSVoice {
-  id: string
-  name: string
-  category?: string
-  language?: string
-  preview_url?: string
-  description?: string
-}
-
-/** TTS 试听请求参数 */
-export interface TTSPreviewRequest {
-  text: string
-  voice_id: string
-  speed?: number
-  pitch?: number
-}
-
-/** TTS 试听响应 */
-export interface TTSPreviewResponse {
-  audio_url: string
-  duration?: number
-}

apps/web/src/api/voices/index.ts

@@ -0,0 +1,26 @@
+/**
+ * 配音相关 API — 目录化入口
+ * 保持与原 voices.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type {
+  UnifiedVoiceItem,
+  UnifiedVoiceListResponse,
+  PresetVoiceItem,
+  PresetVoiceListResponse,
+  UnifiedVoiceListParams,
+  VoiceItem,
+  CreateVoiceRequest,
+} from "./types"
+
+// API 函数
+export {
+  fetchVoices,
+  fetchPresetVoices,
+  getVoices,
+  createVoice,
+  updateVoice,
+  deleteVoice,
+  generateAIVoice,
+} from "./voices"

apps/web/src/api/voices/types.ts

@@ -0,0 +1,81 @@
+/**
+ * 配音相关类型定义
+ */
+
+/** 统一音色条目（preset + clone 混合） */
+export interface UnifiedVoiceItem {
+  id: string
+  type: "preset" | "clone"
+  name: string
+  description: string
+  gender: string
+  language: string
+  voice_id: string
+  voice_provider: string
+  audio_url: string | null
+  preview_url: string | null
+  duration: number | null
+  file_size: number | null
+  status: string
+  tags: string[]
+  user_id: string | null
+  project_id: string | null
+  voice_clone_profile_id: string | null
+  created_at: string | null
+  updated_at: string | null
+}
+
+/** 统一音色列表响应 */
+export interface UnifiedVoiceListResponse {
+  items: UnifiedVoiceItem[]
+  total: number
+  preset_count: number
+  clone_count: number
+}
+
+/** 预设音色条目 */
+export interface PresetVoiceItem {
+  voice_id: string
+  name: string
+  description: string
+  gender: string
+  language: string
+  preview_url: string | null
+  tags: string[]
+}
+
+/** 预设音色列表响应 */
+export interface PresetVoiceListResponse {
+  items: PresetVoiceItem[]
+  total: number
+}
+
+/** 统一列表查询参数 */
+export interface UnifiedVoiceListParams {
+  type?: "preset" | "clone"
+  status?: string
+  skip?: number
+  limit?: number
+}
+
+/** 配音条目（旧） */
+export interface VoiceItem {
+  id: string
+  name: string
+  text: string
+  voice_type?: string
+  duration_seconds?: number
+  storage_key?: string
+  audio_url?: string
+  status?: string
+  is_favorite?: boolean
+  created_at?: string
+  updated_at?: string
+}
+
+/** 创建配音请求（旧） */
+export interface CreateVoiceRequest {
+  name: string
+  text: string
+  voice_type?: string
+}

apps/web/src/api/voices/voices.ts

@@ -1,68 +1,15 @@
 /**
- * 配音相关 API
- * Phase 1 新增：全局配音库
- *
+ * 配音相关 API 函数
  * 任务 3.11：新增统一音色 API（对接后端 3.04），保留旧接口向后兼容
  */
-import apiClient from "./client"
-
-/* ── 统一音色 API（后端 3.04） ─────────────────────────── */
-
-/** 统一音色条目（preset + clone 混合） */
-export interface UnifiedVoiceItem {
-  id: string
-  type: "preset" | "clone"
-  name: string
-  description: string
-  gender: string
-  language: string
-  voice_id: string
-  voice_provider: string
-  audio_url: string | null
-  preview_url: string | null
-  duration: number | null
-  file_size: number | null
-  status: string
-  tags: string[]
-  user_id: string | null
-  project_id: string | null
-  voice_clone_profile_id: string | null
-  created_at: string | null
-  updated_at: string | null
-}
-
-/** 统一音色列表响应 */
-export interface UnifiedVoiceListResponse {
-  items: UnifiedVoiceItem[]
-  total: number
-  preset_count: number
-  clone_count: number
-}
-
-/** 预设音色条目 */
-export interface PresetVoiceItem {
-  voice_id: string
-  name: string
-  description: string
-  gender: string
-  language: string
-  preview_url: string | null
-  tags: string[]
-}
-
-/** 预设音色列表响应 */
-export interface PresetVoiceListResponse {
-  items: PresetVoiceItem[]
-  total: number
-}
-
-/** 统一列表查询参数 */
-export interface UnifiedVoiceListParams {
-  type?: "preset" | "clone"
-  status?: string
-  skip?: number
-  limit?: number
-}
+import apiClient from "../client"
+import type {
+  CreateVoiceRequest,
+  PresetVoiceListResponse,
+  UnifiedVoiceListParams,
+  UnifiedVoiceListResponse,
+  VoiceItem,
+} from "./types"
 
 /** 获取统一音色列表（推荐） */
 export const fetchVoices = async (
@@ -86,28 +33,6 @@ export const fetchPresetVoices = async (): Promise<PresetVoiceListResponse> => {
 
 /* ── 向后兼容（旧接口） ────────────────────────────────── */
 
-/** 配音条目（旧） */
-export interface VoiceItem {
-  id: string
-  name: string
-  text: string
-  voice_type?: string
-  duration_seconds?: number
-  storage_key?: string
-  audio_url?: string
-  status?: string
-  is_favorite?: boolean
-  created_at?: string
-  updated_at?: string
-}
-
-/** 创建配音请求（旧） */
-export interface CreateVoiceRequest {
-  name: string
-  text: string
-  voice_type?: string
-}
-
 /** 获取当前用户的所有配音（旧 → /voices/legacy） */
 export const getVoices = async (): Promise<VoiceItem[]> => {
   const response = await apiClient.get("/voices/legacy")