feat: 配音列表 API 增强 — 预置音色 + 克隆音色统一接口

- 新增预置音色配置（8 个 CosyVoice 真实音色）
- 增强 GET /api/v1/voices 接口，支持 type 查询参数（preset/clone/all）
- 新增 GET /api/v1/voices/presets 端点
- 统一响应格式，包含 preset_count 和 clone_count
- 保留原有 CRUD 端点向后兼容
- 添加 18 个预置音色单元测试（全部通过）

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

apps/api/app/api/routes/voices.py

@@ -1,11 +1,20 @@
-"""Voice library CRUD routes."""
+"""Voice library CRUD routes — Phase 3 增强版.
+
+支持预置音色和克隆音色的统一列表。
+"""
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import Literal, Optional
 
 from app.auth import AuthenticatedUser, get_current_user
 from app.dependencies import get_db_session, get_user_repository
+from app.schemas.voice import (
+    PresetVoiceItemResponse,
+    PresetVoiceListResponse,
+    UnifiedVoiceItemResponse,
+    UnifiedVoiceListResponse,
+)
 from app.schemas.voice_library import (
     CreateVoiceLibraryRequest,
     ListVoiceLibraryResponse,
@@ -26,6 +35,7 @@ from packages.application.voice_library.use_cases import (
     QuotaExceededError,
     UpdateVoiceLibraryUseCase,
 )
+from packages.domain.preset_voices import PRESET_VOICES
 from packages.ports.user_repository import UserRepository
 
 router = APIRouter()
@@ -55,6 +65,45 @@ def _to_response(item) -> VoiceLibraryItemResponse:
     )
 
 
+def _to_unified_response(item) -> UnifiedVoiceItemResponse:
+    """将数据库音色转换为统一响应格式。"""
+    return UnifiedVoiceItemResponse(
+        id=item.id,
+        type="clone",
+        name=item.name,
+        description=item.text,
+        gender="unknown",
+        language="zh-CN",
+        voice_id=item.voice_id,
+        voice_provider=item.voice_provider or "cosyvoice",
+        audio_url=item.audio_url,
+        duration=item.duration,
+        file_size=item.file_size,
+        status=item.status,
+        tags=item.tags,
+        user_id=item.user_id,
+        project_id=item.project_id,
+        created_at=item.created_at,
+        updated_at=item.updated_at,
+    )
+
+
+def _preset_to_unified_response(preset) -> UnifiedVoiceItemResponse:
+    """将预置音色转换为统一响应格式。"""
+    return UnifiedVoiceItemResponse(
+        id=preset.voice_id,
+        type="preset",
+        name=preset.name,
+        description=preset.description,
+        gender=preset.gender,
+        language=preset.language,
+        voice_id=preset.voice_id,
+        voice_provider="cosyvoice",
+        preview_url=preset.preview_url,
+        tags=preset.tags or [],
+    )
+
+
 def _get_user_plan(user_id: str, user_repository: UserRepository) -> str:
     user = user_repository.find_by_id(user_id)
     if user is None:
@@ -62,14 +111,121 @@ def _get_user_plan(user_id: str, user_repository: UserRepository) -> str:
     return getattr(user, "subscription_plan", "free") or "free"
 
 
-@router.get("", response_model=ListVoiceLibraryResponse)
-def list_voices(
+# ==================== 统一配音列表（预置 + 克隆）====================
+
+
+@router.get("", response_model=UnifiedVoiceListResponse)
+def list_voices_unified(
+    type: Optional[Literal["preset", "clone"]] = Query(
+        None,
+        description="音色类型过滤：preset=仅预置，clone=仅克隆，不传=全部",
+    ),
+    status_filter: Optional[str] = Query(None, alias="status"),
+    skip: int = Query(0, ge=0),
+    limit: int = Query(50, ge=1, le=200),
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    voice_repository: SQLAlchemyVoiceLibraryRepository = Depends(_get_voice_repository),
+) -> UnifiedVoiceListResponse:
+    """获取配音列表（预置音色 + 用户克隆音色）。
+
+    - 不传 type：返回预置音色 + 用户克隆音色，预置音色在前
+    - type=preset：仅返回预置音色
+    - type=clone：仅返回用户克隆音色
+    """
+    user_id = authenticated_user.user.id
+    items: list[UnifiedVoiceItemResponse] = []
+    preset_count = 0
+    clone_count = 0
+
+    # 获取预置音色
+    if type is None or type == "preset":
+        preset_items = [_preset_to_unified_response(p) for p in PRESET_VOICES]
+        preset_count = len(preset_items)
+        if type == "preset":
+            # 仅预置：应用分页
+            items = preset_items[skip : skip + limit]
+        else:
+            items.extend(preset_items)
+
+    # 获取克隆音色
+    if type is None or type == "clone":
+        use_case = ListVoiceLibraryUseCase(voice_repository)
+        clone_items_raw = use_case.execute(user_id, status=status_filter, skip=0, limit=1000)
+        clone_items = [_to_unified_response(i) for i in clone_items_raw]
+        clone_count = len(clone_items)
+        if type == "clone":
+            # 仅克隆：应用分页
+            items = clone_items[skip : skip + limit]
+        else:
+            items.extend(clone_items)
+
+    # 全量模式：应用分页
+    if type is None:
+        total = preset_count + clone_count
+        items = items[skip : skip + limit]
+    elif type == "preset":
+        total = preset_count
+    else:
+        total = clone_repository_count(voice_repository, user_id, status_filter)
+
+    return UnifiedVoiceListResponse(
+        items=items,
+        total=total,
+        preset_count=preset_count if type != "clone" else 0,
+        clone_count=clone_count if type != "preset" else 0,
+    )
+
+
+def clone_repository_count(
+    voice_repository: SQLAlchemyVoiceLibraryRepository,
+    user_id: str,
+    status_filter: Optional[str],
+) -> int:
+    """获取克隆音色数量。"""
+    if status_filter:
+        return voice_repository.count_by_user(user_id, status=status_filter)
+    return voice_repository.count_by_user(user_id)
+
+
+# ==================== 预置音色专用端点 ====================
+
+
+@router.get("/presets", response_model=PresetVoiceListResponse)
+def list_preset_voices() -> PresetVoiceListResponse:
+    """获取预置音色列表。
+
+    不需要认证，返回所有系统预置的 CosyVoice 音色。
+    """
+    items = [
+        PresetVoiceItemResponse(
+            voice_id=p.voice_id,
+            name=p.name,
+            description=p.description,
+            gender=p.gender,
+            language=p.language,
+            preview_url=p.preview_url,
+            tags=p.tags or [],
+        )
+        for p in PRESET_VOICES
+    ]
+    return PresetVoiceListResponse(items=items, total=len(items))
+
+
+# ==================== 原有 CRUD 端点（保持向后兼容）====================
+
+
+@router.get("/legacy", response_model=ListVoiceLibraryResponse)
+def list_voices_legacy(
     status_filter: Optional[str] = Query(None, alias="status"),
     skip: int = Query(0, ge=0),
     limit: int = Query(50, ge=1, le=200),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     voice_repository: SQLAlchemyVoiceLibraryRepository = Depends(_get_voice_repository),
 ) -> ListVoiceLibraryResponse:
+    """原有配音列表接口（仅返回用户克隆音色）。
+
+    保留用于向后兼容，新客户端请使用 GET /api/v1/voices。
+    """
     user_id = authenticated_user.user.id
     use_case = ListVoiceLibraryUseCase(voice_repository)
     items = use_case.execute(user_id, status=status_filter, skip=skip, limit=limit)

apps/api/app/schemas/voice.py

@@ -0,0 +1,127 @@
+"""统一配音响应 Schema — Phase 3 CosyVoice 集成.
+
+支持预置音色和克隆音色的统一响应格式。
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class UnifiedVoiceItemResponse(BaseModel):
+    """统一配音项响应。
+
+    同时支持预置音色（type=preset）和克隆音色（type=clone）。
+    """
+
+    id: str
+    """音色 ID（预置音色为 voice_id，克隆音色为数据库 ID）"""
+
+    type: Literal["preset", "clone"]
+    """音色类型：preset=预置音色，clone=用户克隆音色"""
+
+    name: str
+    """音色展示名称"""
+
+    description: str = ""
+    """音色描述"""
+
+    gender: str = "unknown"
+    """性别：male/female/unknown"""
+
+    language: str = "zh-CN"
+    """语言代码"""
+
+    voice_id: str = ""
+    """CosyVoice 模型音色名"""
+
+    voice_provider: str = "cosyvoice"
+    """语音服务商"""
+
+    audio_url: str = ""
+    """音频 URL（克隆音色为上传的音频，预置音色为空）"""
+
+    preview_url: str = ""
+    """预览音频 URL（预置音色可能有）"""
+
+    duration: float = 0
+    """音频时长（秒）"""
+
+    file_size: int = 0
+    """文件大小（字节）"""
+
+    status: str = "completed"
+    """状态"""
+
+    tags: List[str] = Field(default_factory=list)
+    """标签列表"""
+
+    # 克隆音色特有字段
+    user_id: Optional[str] = None
+    """所属用户 ID（仅克隆音色）"""
+
+    project_id: Optional[str] = None
+    """所属项目 ID（仅克隆音色）"""
+
+    voice_clone_profile_id: Optional[str] = None
+    """关联的音色克隆档案 ID（仅克隆音色）"""
+
+    created_at: Optional[datetime] = None
+    """创建时间（仅克隆音色）"""
+
+    updated_at: Optional[datetime] = None
+    """更新时间（仅克隆音色）"""
+
+
+class UnifiedVoiceListResponse(BaseModel):
+    """统一配音列表响应。"""
+
+    items: list[UnifiedVoiceItemResponse]
+    """音色列表（预置音色在前）"""
+
+    total: int = 0
+    """总数"""
+
+    preset_count: int = 0
+    """预置音色数量"""
+
+    clone_count: int = 0
+    """克隆音色数量"""
+
+
+class PresetVoiceItemResponse(BaseModel):
+    """预置音色项响应。"""
+
+    voice_id: str
+    """CosyVoice 模型音色名"""
+
+    name: str
+    """中文展示名"""
+
+    description: str
+    """音色描述"""
+
+    gender: str
+    """性别"""
+
+    language: str = "zh-CN"
+    """语言代码"""
+
+    preview_url: str = ""
+    """预览音频 URL"""
+
+    tags: List[str] = Field(default_factory=list)
+    """标签列表"""
+
+
+class PresetVoiceListResponse(BaseModel):
+    """预置音色列表响应。"""
+
+    items: list[PresetVoiceItemResponse]
+    """预置音色列表"""
+
+    total: int = 0
+    """总数"""