feat: 接入渲染灰度观测指标到compose_video和stream_copy

- compose_video 入口接入 render_task_metrics 上下文自动记录：引擎选择、任务耗时、成功/失败、错误类型、活跃任务数 - unified_render_service 接入 stream_copy 埋点三种状态：hit（命中直通）/ miss（条件不满足跳过）/ fallback（失败回退） miss 原因归一化为8类：编码/分辨率/帧率/字幕/像素格式/裁剪/多片段/其他
feat: 新增渲染引擎灰度观测指标模块
2026-07-13 14:39:15 +08:00 · 2026-07-13 14:37:19 +08:00
70 changed files with 1988 additions and 178 deletions
@@ -3,7 +3,6 @@
 # ==================== 应用配置 ====================
 APP_NAME=小虾 SaaS
 APP_BASE_URL=http://localhost:3000
-APP_ENV=development

 # ==================== 数据库配置 ====================
 DATABASE_URL=postgresql://xiaoxia_user:your_password@localhost:5432/xiaoxia_saas
@@ -36,8 +35,7 @@ ENVIRONMENT=development
 DEBUG=true

 # ==================== CORS 配置 ====================
-# 逗号分隔的域名列表（Settings 读取 CORS_ORIGINS_RAW）
-CORS_ORIGINS_RAW=http://localhost:3000,http://localhost:5173
+CORS_ORIGINS=["http://localhost:3000","http://localhost:5173"]

 # ==================== 阿里云 OSS 配置 ====================
 OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
@@ -51,7 +49,6 @@ OSS_BUCKET_NAME=xiaoxia-autocut
 #       cosyvoice-v3-plus (高质量，系统音色少)
 #       cosyvoice-v3.5-flash / cosyvoice-v3.5-plus (仅支持克隆/设计音色，无系统音色)
 # 音色: v3系列系统音色带 _v3 后缀，如 longxiaochun_v3, longxiaoxia_v3, longanyang (无后缀)
-# 注意：COSYVOICE_* 变量由 packages/shared/config.py 的 SharedSettings 读取
 COSYVOICE_API_KEY=your-cosyvoice-api-key
 COSYVOICE_BASE_URL=https://dashscope.aliyuncs.com/api/v1
 COSYVOICE_MODEL=cosyvoice-v3-flash
@@ -0,0 +1 @@
+"""API application package."""
@@ -0,0 +1 @@
+"""API package."""
@@ -1,48 +0,0 @@
-"""路由层共享辅助函数 — 消除跨文件重复定义。"""
-
-from typing import Any
-
-from fastapi import HTTPException, status
-
-from packages.application import GetProjectUseCase
-from packages.ports.user_repository import UserRepository
-
-
-def check_project_access(project_id: str, user_id: str, project_repository) -> None:
-    """检查用户是否有项目访问权限。
-
-    合并自 asset_libraries.py / edit_plans.py 的同名函数。
-    - 空 project_id 直接放行（兼容 edit_plans 中 project_id 可选的场景）
-    - 错误信息使用中文，与项目其他路由保持一致
-    """
-    if not project_id or not project_id.strip():
-        return
-    project = project_repository.find_by_id(project_id)
-    if project is None:
-        raise HTTPException(status_code=404, detail="项目不存在")
-    if not project.can_access(user_id):
-        raise HTTPException(status_code=403, detail="无权访问该项目")
-
-
-def get_user_plan(user_id: str, user_repository: UserRepository) -> str:
-    """获取用户的订阅计划名称。"""
-    user = user_repository.find_by_id(user_id)
-    if user is None:
-        return "free"
-    return getattr(user, "subscription_plan", "free") or "free"
-
-
-def require_project_and_library(
-    project_id: str,
-    library_id: str,
-    project_repository: Any,
-    asset_library_repository: Any,
-) -> None:
-    """Verify project and asset library exist."""
-    project = GetProjectUseCase(project_repository).execute(project_id)
-    if project is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
-
-    libraries = asset_library_repository.find_by_project(project_id)
-    if not any(item.id == library_id for item in libraries):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Asset library not found")
@@ -22,11 +22,18 @@ from packages.application import (
 )
 from packages.domain import AssetLibrary, AssetLibraryKind

-from ._helpers import check_project_access
-
 router = APIRouter()


+def _check_project_access(project_id: str, user_id: str, project_repository) -> None:
+    """检查用户是否有项目访问权限"""
+    project = project_repository.find_by_id(project_id)
+    if project is None:
+        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
+    if not project.can_access(user_id):
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied to project")
+
+
 def _to_asset_library_response(item) -> AssetLibraryResponse:
    return AssetLibraryResponse(
        id=item.id,
@@ -161,7 +168,7 @@ def delete_asset_library(
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="素材库不存在")

    # 权限校验：检查用户是否有项目访问权限
-    check_project_access(library.project_id, authenticated_user.user.id, project_repository)
+    _check_project_access(library.project_id, authenticated_user.user.id, project_repository)

    # 删除库内所有素材（无 FK 级联，需手动清理）
    assets_in_library = asset_repository.find_by_library(library_id)
@@ -27,8 +27,6 @@ from packages.application import (
 )
 from packages.domain import AssetStatus, ClassificationStatus

-from app.api.routes._helpers import check_project_access
-
 logger = logging.getLogger(__name__)

 router = APIRouter()
@@ -74,6 +72,14 @@ def _to_asset_response(item, storage_service=None) -> AssetResponse:
    )


+def _check_project_access(project_id: str, user_id: str, project_repository) -> None:
+    """检查用户是否有项目访问权限"""
+    project = project_repository.find_by_id(project_id)
+    if project is None:
+        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
+    if not project.can_access(user_id):
+        raise HTTPException(status_code=403, detail="Access denied to project")
+

@router.get("", response_model=ListAssetsResponse)
 def list_assets(
@@ -130,7 +136,7 @@ def list_assets(
            library = asset_library_repository.get(library_id)
            if library is None:
                raise HTTPException(status_code=404, detail=f"AssetLibrary {library_id} not found")
-            check_project_access(library.project_id, user_id, project_repository)
+            _check_project_access(library.project_id, user_id, project_repository)
            if ft:
                items = asset_repository.find_by_library_and_file_type(library_id, ft, skip=skip, limit=limit)
                total = asset_repository.count_by_project(library.project_id) if not kind else len(items)
@@ -146,7 +152,7 @@ def list_assets(

        # 模式2：指定 project_id
        if project_id:
-            check_project_access(project_id, user_id, project_repository)
+            _check_project_access(project_id, user_id, project_repository)
            if ft:
                # 无直接方法，加载后按 file_type 过滤（仍比全量加载好）
                all_items = asset_repository.find_by_project(project_id)
@@ -204,13 +210,13 @@ def list_assets(
        library = asset_library_repository.get(library_id)
        if library is None:
            raise HTTPException(status_code=404, detail=f"AssetLibrary {library_id} not found")
-        check_project_access(library.project_id, user_id, project_repository)
+        _check_project_access(library.project_id, user_id, project_repository)
        if kind:
            all_items = asset_repository.find_by_library_and_file_type(library_id, kind_to_file_type[kind])
        else:
            all_items = asset_repository.find_by_library(library_id)
    elif project_id:
-        check_project_access(project_id, user_id, project_repository)
+        _check_project_access(project_id, user_id, project_repository)
        all_items = asset_repository.find_by_project(project_id)
    else:
        try:
@@ -256,7 +262,7 @@ def update_asset_review_status(
    item = asset_repository.get(asset_id)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
-    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    _check_project_access(item.project_id, authenticated_user.user.id, project_repository)
    _apply_asset_review_status(item, request.review_status)
    updated = asset_repository.update(item)
    return _to_asset_response(updated)
@@ -280,7 +286,7 @@ def batch_delete_assets(
            failed_ids.append(asset_id)
            continue
        try:
-            check_project_access(item.project_id, user_id, project_repository)
+            _check_project_access(item.project_id, user_id, project_repository)
            deleted_ids.append(asset_id)
        except HTTPException:
            failed_ids.append(asset_id)
@@ -301,7 +307,7 @@ def get_asset(
    item = asset_repository.find_by_id(asset_id)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
-    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    _check_project_access(item.project_id, authenticated_user.user.id, project_repository)
    return _to_asset_response(item)


@@ -316,7 +322,7 @@ def update_asset(
    item = asset_repository.find_by_id(asset_id)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
-    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    _check_project_access(item.project_id, authenticated_user.user.id, project_repository)

    # 合并可修改字段
    if request.name is not None:
@@ -340,7 +346,7 @@ def delete_asset(
    item = asset_repository.find_by_id(asset_id)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
-    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    _check_project_access(item.project_id, authenticated_user.user.id, project_repository)
    asset_repository.delete(asset_id)


@@ -357,7 +363,7 @@ def tag_asset(
    item = asset_repository.find_by_id(asset_id)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
-    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    _check_project_access(item.project_id, authenticated_user.user.id, project_repository)
    for tag_id in request.tag_ids:
        tag = tag_repository.get(tag_id)
        if tag is None:
@@ -381,7 +387,7 @@ def untag_asset(
    item = asset_repository.find_by_id(asset_id)
    if item is None:
        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
-    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    _check_project_access(item.project_id, authenticated_user.user.id, project_repository)
    item.remove_tag(tag_id)
    asset_repository.update(item)

@@ -206,7 +206,7 @@ async def verify_email_post(
    return _verify_email_token(request.token, user_repository)


-@router.post("/forgot-password", response_model=MessageResponse, status_code=status.HTTP_202_ACCEPTED)
+@router.post("/password/forgot", response_model=MessageResponse, status_code=status.HTTP_202_ACCEPTED)
 async def forgot_password(
    request: PasswordResetRequestModel,
    user_repository: UserRepository = Depends(get_user_repository),
@@ -223,7 +223,7 @@ async def forgot_password(
    return MessageResponse(message="如果账户存在，密码重置邮件已发送")


-@router.post("/reset-password", response_model=MessageResponse)
+@router.post("/password/reset", response_model=MessageResponse)
 async def reset_password(
    request: ResetPasswordModel,
    user_repository: UserRepository = Depends(get_user_repository),
@@ -243,6 +243,7 @@ async def logout(
    current_user: AuthenticatedUser = Depends(get_current_user),
 ):
    """登出 - 将当前 token 加入黑名单"""
+    from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer

    if credentials:
        try:
@@ -14,6 +14,7 @@ from typing import Any
 from uuid import uuid4

 from app.auth import AuthenticatedUser, get_current_user
+from app.config import get_settings
 from app.core.celery_app import celery_app
 from app.core.storage import OSSStorageService, get_storage_service
 from app.dependencies import (
@@ -34,8 +35,6 @@ from fastapi.params import File

 from packages.application import GetProjectUseCase, SubmitIngestJobCommand, SubmitIngestJobUseCase

-from app.api.routes._helpers import require_project_and_library
-
 router = APIRouter()
 logger = logging.getLogger(__name__)

@@ -114,6 +113,22 @@ def _atomic_check_and_record(upload_id: str, chunk_index: int) -> bool:
            fcntl.flock(f.fileno(), fcntl.LOCK_UN)


+def _require_project_and_library(
+    project_id: str,
+    library_id: str,
+    project_repository: Any,
+    asset_library_repository: Any,
+) -> None:
+    """Verify project and asset library exist"""
+    project = GetProjectUseCase(project_repository).execute(project_id)
+    if project is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+
+    libraries = asset_library_repository.find_by_project(project_id)
+    if not any(item.id == library_id for item in libraries):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Asset library not found")
+
+
 def _load_upload_meta(upload_id: str) -> dict[str, Any]:
    """Load upload metadata"""
    meta_path = _get_upload_meta_path(upload_id)
@@ -191,6 +206,7 @@ async def init_chunked_upload(
    asset_library_repository: Any = Depends(get_asset_library_repository),
 ) -> ChunkedUploadInitResponse:
    """Initialize chunked upload"""
+    settings = get_settings()

    # Validate file size
    if request.file_size > MAX_FILE_SIZE:
@@ -205,7 +221,7 @@ async def init_chunked_upload(
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")

    # Verify asset library
-    require_project_and_library(
+    _require_project_and_library(
        request.project_id,
        request.library_id,
        project_repository,
@@ -32,6 +32,12 @@ from fastapi import APIRouter, Depends, HTTPException, Query, status
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session

+from packages.adapters.sqlalchemy_impl.asset_library_repository import (
+    SQLAlchemyAssetLibraryRepository,
+)
+from packages.adapters.sqlalchemy_impl.asset_repository import (
+    SQLAlchemyAssetRepository,
+)
 from packages.adapters.sqlalchemy_impl.generation_task_repository import (
    SQLAlchemyGenerationTaskRepository,
 )
@@ -45,8 +51,6 @@ from packages.application.generation_tasks import (
    CreateGenerationTaskCommand,
    CreateGenerationTaskUseCase,
 )
-
-from ._helpers import check_project_access
 from packages.domain.config_schemas import normalize_plan_config
 from packages.domain.edit_plan import EditPlan, EditPlanStatus

@@ -243,6 +247,17 @@ class GenerateFromTemplateResponse(BaseModel):
 # ── Helpers ───────────────────────────────────────────────────────────────────


+def _check_project_access(project_id: str, user_id: str, project_repository: Any) -> None:
+    """校验用户对项目的访问权限（参照 assets.py 的 can_access 模式）"""
+    if not project_id or not project_id.strip():
+        return
+    project = project_repository.find_by_id(project_id)
+    if project is None:
+        raise HTTPException(status_code=404, detail="项目不存在")
+    if not project.can_access(user_id):
+        raise HTTPException(status_code=403, detail="无权访问该项目")
+
+
 def _to_response(p: EditPlan) -> EditPlanResponse:
    return EditPlanResponse(
        id=p.id,
@@ -296,7 +311,7 @@ def list_plans(

    # 项目鉴权：如果指定了 project_id，校验用户是否有权访问
    if project_id:
-        check_project_access(project_id, current_user.user.id, project_repository)
+        _check_project_access(project_id, current_user.user.id, project_repository)

    skip = (page - 1) * page_size
    plans = svc.list_plans(
@@ -338,7 +353,7 @@ def get_plan(
        )
    # 项目鉴权
    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
+        _check_project_access(plan.project_id, current_user.user.id, project_repository)
    return _to_response(plan)


@@ -354,7 +369,7 @@ def create_plan(
    project_id = (body.project_id or "").strip()
    # 项目鉴权
    if project_id:
-        check_project_access(project_id, current_user.user.id, project_repository)
+        _check_project_access(project_id, current_user.user.id, project_repository)
    svc = EditPlanService(db)
    # 标准化 config，填充 cover/title/subtitle/bgm 默认值
    normalized_config = normalize_plan_config(body.config)
@@ -396,7 +411,7 @@ def update_plan(
    if existing is None:
        raise HTTPException(status_code=404, detail=f"剪辑计划不存在: {plan_id}")
    if existing.project_id:
-        check_project_access(existing.project_id, current_user.user.id, project_repository)
+        _check_project_access(existing.project_id, current_user.user.id, project_repository)

    # 基础字段更新
    try:
@@ -450,7 +465,7 @@ def delete_plan(
    # 项目鉴权
    existing = svc.get_plan(plan_id)
    if existing and existing.project_id:
-        check_project_access(existing.project_id, current_user.user.id, project_repository)
+        _check_project_access(existing.project_id, current_user.user.id, project_repository)
    deleted = svc.delete_plan(plan_id)
    if not deleted:
        raise HTTPException(
@@ -492,7 +507,7 @@ def generate_plan(
    if plan_check is None:
        raise HTTPException(status_code=404, detail=f"剪辑计划不存在: {plan_id}")
    if plan_check.project_id:
-        check_project_access(plan_check.project_id, current_user.user.id, project_repository)
+        _check_project_access(plan_check.project_id, current_user.user.id, project_repository)

    # ── 自动兜底 1: draft → editing ──────────────────────────────────────
    if plan_check.status == EditPlanStatus.DRAFT:
@@ -695,7 +710,7 @@ def generate_plan(
    except HTTPException:
        # 已处理的 HTTP 异常直接透传
        raise
-    except Exception:
+    except Exception as exc:
        logger.exception("触发剪辑计划生成失败: plan_id=%s", plan_id)
        # 尝试将计划标记为失败（RENDERING → FAILED 是合法的状态流转）
        try:
@@ -734,7 +749,7 @@ def get_generation_status(
    plan = gen_status["plan"]
    # 项目鉴权
    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
+        _check_project_access(plan.project_id, current_user.user.id, project_repository)
    clips = gen_status["clips"]

    clip_items = [
@@ -776,7 +791,7 @@ def list_plan_generations(
    # 验证计划存在 + 项目鉴权
    plan = svc.get_plan_or_raise(plan_id)
    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
+        _check_project_access(plan.project_id, current_user.user.id, project_repository)

    gen_task_repo = SQLAlchemyGenerationTaskRepository(db)
    tasks = gen_task_repo.list_by_source_edit_plan(plan_id)
@@ -845,7 +860,7 @@ def ai_recommend_clips(

    # 项目鉴权
    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
+        _check_project_access(plan.project_id, current_user.user.id, project_repository)

    # 验证状态：只允许 draft 或 editing
    plan_status = plan.status.value if hasattr(plan.status, "value") else plan.status
@@ -894,7 +909,7 @@ def ai_recommend_clips(
            config=normalized_config,
            total_duration=result["total_duration"],
        )
-    except Exception:
+    except Exception as exc:
        logger.exception("AI 推荐写入失败，plan_id=%s 数据可能不一致", plan_id)
        # 尝试回滚未提交的变更
        try:
@@ -975,7 +990,7 @@ def generate_cover(

    # 项目鉴权
    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
+        _check_project_access(plan.project_id, current_user.user.id, project_repository)

    # 调用 AI 封面生成服务
    from apps.worker.worker_app.tasks.ai_tasks import run_generate_cover
@@ -1095,7 +1110,7 @@ def get_plan_timeline(
    plan = svc.get_plan_or_raise(plan_id)
    # 项目鉴权
    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
+        _check_project_access(plan.project_id, current_user.user.id, project_repository)

    clips = svc.list_clips(plan_id=plan_id, skip=0, limit=200)
    # 按 order 排序
@@ -1156,7 +1171,7 @@ def generate_from_template(

    # 项目鉴权
    if body.project_id:
-        check_project_access(body.project_id, current_user.user.id, project_repository)
+        _check_project_access(body.project_id, current_user.user.id, project_repository)

    template_svc = EditTemplateService(db)

@@ -32,8 +32,6 @@ from app.schemas.generation_task import (
 )
 from fastapi import APIRouter, Depends, HTTPException

-from app.api.routes._helpers import check_project_access
-
 from packages.application import (
    CreateGenerationTaskCommand,
    CreateGenerationTaskUseCase,
@@ -45,6 +43,15 @@ logger = logging.getLogger(__name__)

 router = APIRouter()

+def _check_project_access(project_id: str, user_id: str, project_repository) -> None:
+    """检查用户是否有项目访问权限"""
+    project = project_repository.find_by_id(project_id)
+    if project is None:
+        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
+    if not project.can_access(user_id):
+        raise HTTPException(status_code=403, detail="Access denied to project")
+
+
 def _to_generation_task_response(task) -> GenerationTaskResponse:
    return GenerationTaskResponse(
        id=task.id,
@@ -332,7 +339,7 @@ def get_generation_task(
    if task is None:
        raise HTTPException(status_code=404, detail=f"GenerationTask {task_id} not found")
    if task.project_id:
-        check_project_access(task.project_id, authenticated_user.user.id, project_repository)
+        _check_project_access(task.project_id, authenticated_user.user.id, project_repository)
    return _to_generation_task_response(task)


@@ -349,7 +356,7 @@ def list_generation_results(
    if task is None:
        raise HTTPException(status_code=404, detail=f"GenerationTask {task_id} not found")
    if task.project_id:
-        check_project_access(task.project_id, authenticated_user.user.id, project_repository)
+        _check_project_access(task.project_id, authenticated_user.user.id, project_repository)
    use_case = ListGeneratedVideosByTaskUseCase(generated_video_repository)
    items = use_case.execute(task_id)
    responses = []
@@ -20,7 +20,7 @@ from typing import Any

 from app.auth import AuthenticatedUser, get_current_user
 from app.core.celery_app import celery_app
-from app.dependencies import get_job_repository, get_project_repository
+from app.dependencies import get_db_session, get_job_repository, get_project_repository
 from app.schemas.job import (
    CompleteJobRequest,
    CreateJobRequest,
@@ -51,8 +51,6 @@ from packages.application.jobs import (
 )
 from packages.domain.job import JobType

-from app.api.routes._helpers import check_project_access
-
 logger = logging.getLogger(__name__)

 router = APIRouter()
@@ -68,6 +66,15 @@ _JOB_TYPE_TO_CELERY_TASK: dict[str, str] = {
 }


+def _check_project_access(project_id: str, user_id: str, project_repository) -> None:
+    """检查用户是否有项目访问权限。"""
+    project = project_repository.find_by_id(project_id)
+    if project is None:
+        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
+    if not project.can_access(user_id):
+        raise HTTPException(status_code=403, detail="Access denied to project")
+
+
 # ── 创建任务 ──────────────────────────────────────────────────────────────────


@@ -82,7 +89,7 @@ def create_job(

    创建后任务处于 pending 状态，需要调用 /submit 提交执行。
    """
-    check_project_access(request.project_id, authenticated_user.user.id, project_repository)
+    _check_project_access(request.project_id, authenticated_user.user.id, project_repository)

    # 校验 job_type
    try:
@@ -175,7 +182,7 @@ def list_project_jobs(
    offset: int = Query(default=0, ge=0),
 ) -> ListJobsResponse:
    """获取项目下的任务列表。"""
-    check_project_access(project_id, authenticated_user.user.id, project_repository)
+    _check_project_access(project_id, authenticated_user.user.id, project_repository)

    use_case = ListJobsUseCase(job_repo)
    jobs = use_case.execute(
@@ -197,7 +204,7 @@ def get_job_statistics(
    project_repository: Any = Depends(get_project_repository),
 ) -> JobStatisticsResponse:
    """获取项目任务统计摘要。"""
-    check_project_access(project_id, authenticated_user.user.id, project_repository)
+    _check_project_access(project_id, authenticated_user.user.id, project_repository)

    use_case = GetJobStatisticsUseCase(job_repo)
    stats = use_case.execute(project_id)
@@ -33,8 +33,6 @@ from packages.application.recipe.use_cases import (
 )
 from packages.ports.user_repository import UserRepository

-from app.api.routes._helpers import get_user_plan
-
 router = APIRouter()


@@ -42,6 +40,13 @@ def _get_recipe_repository(session: Session = Depends(get_db_session)) -> SQLAlc
    return SQLAlchemyRecipeRepository(session)


+def _get_user_plan(user_id: str, user_repository: UserRepository) -> str:
+    user = user_repository.find_by_id(user_id)
+    if user is None:
+        return "free"
+    return getattr(user, "subscription_plan", "free") or "free"
+
+
 def _item_to_response(item) -> RecipeItemResponse:
    return RecipeItemResponse(
        id=item.id,
@@ -189,7 +194,7 @@ def use_recipe(
    user_repository: UserRepository = Depends(get_user_repository),
 ) -> UseRecipeResponse:
    user_id = authenticated_user.user.id
-    plan_name = get_user_plan(user_id, user_repository)
+    plan_name = _get_user_plan(user_id, user_repository)
    use_case = UseRecipeUseCase(recipe_repository)
    try:
        result = use_case.execute(recipe_id, user_id, user_plan=plan_name)
@@ -232,7 +232,7 @@ async def payment_callback(

        # 创建账单记录
        record_id = uuid.uuid4().hex
-        repo.create(
+        record = repo.create(
            {
                "id": record_id,
                "user_id": user_id,
@@ -28,8 +28,6 @@ from packages.application.title_library.use_cases import (
 )
 from packages.ports.user_repository import UserRepository

-from app.api.routes._helpers import get_user_plan
-
 router = APIRouter()


@@ -53,6 +51,13 @@ def _to_response(item) -> TitleLibraryItemResponse:
    )


+def _get_user_plan(user_id: str, user_repository: UserRepository) -> str:
+    user = user_repository.find_by_id(user_id)
+    if user is None:
+        return "free"
+    return getattr(user, "subscription_plan", "free") or "free"
+
+
@router.get("", response_model=ListTitleLibraryResponse)
 def list_titles(
    category: Optional[str] = Query(None),
@@ -93,7 +98,7 @@ def create_title(
    user_repository: UserRepository = Depends(get_user_repository),
 ) -> TitleLibraryItemResponse:
    user_id = authenticated_user.user.id
-    plan_name = get_user_plan(user_id, user_repository)
+    plan_name = _get_user_plan(user_id, user_repository)
    command = CreateTitleLibraryCommand(
        user_id=user_id,
        name=request.name,
@@ -1,5 +1,5 @@
 import logging
-from typing import Any
+from typing import Annotated, Any
 from uuid import uuid4

 from app.auth import AuthenticatedUser, get_current_user
@@ -17,13 +17,12 @@ from app.schemas.upload import (
    DirectUploadCompleteResponse,
    DirectUploadPrepareRequest,
    DirectUploadPrepareResponse,
+    UploadAssetRequest,
    UploadAssetResponse,
 )
 from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile, status

-from packages.application import SubmitIngestJobCommand, SubmitIngestJobUseCase
-
-from app.api.routes._helpers import require_project_and_library
+from packages.application import GetProjectUseCase, SubmitIngestJobCommand, SubmitIngestJobUseCase

 logger = logging.getLogger(__name__)

@@ -81,6 +80,21 @@ def _validate_mime_type(content_type: str | None) -> str:
    return base_type


+def _require_project_and_library(
+    project_id: str,
+    library_id: str,
+    project_repository: Any,
+    asset_library_repository: Any,
+) -> None:
+    project = GetProjectUseCase(project_repository).execute(project_id)
+    if project is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+
+    libraries = asset_library_repository.find_by_project(project_id)
+    if not any(item.id == library_id for item in libraries):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Asset library not found")
+
+
 def _submit_ingest_job(
    project_id: str,
    library_id: str,
@@ -121,7 +135,7 @@ async def prepare_direct_upload(
    # P2-5: 服务端验证 MIME 类型
    validated_content_type = _validate_mime_type(request.content_type)

-    require_project_and_library(
+    _require_project_and_library(
        request.project_id,
        request.library_id,
        project_repository,
@@ -169,7 +183,7 @@ async def complete_direct_upload(
    storage_service: OSSStorageService = Depends(get_storage_service),
 ) -> DirectUploadCompleteResponse:
    """确认浏览器直传完成并创建导入任务。"""
-    require_project_and_library(
+    _require_project_and_library(
        request.project_id,
        request.library_id,
        project_repository,
@@ -238,7 +252,7 @@ async def upload_asset(
    storage_service: OSSStorageService = Depends(get_storage_service),
 ) -> UploadAssetResponse:
    """上传素材文件并触发导入流水线。"""
-    require_project_and_library(project_id, library_id, project_repository, asset_library_repository)
+    _require_project_and_library(project_id, library_id, project_repository, asset_library_repository)

    # ── 素材去重检测：上传前检查同素材库 + 同 file_hash ──
    if file_hash:
@@ -28,6 +28,7 @@ from packages.application.voice_clone.use_cases import (
    VoiceCloneNotRetryableError,
 )
 from packages.application.voice_clone.workflow import (
+    VoiceCloneWorkflowError,
    VoiceCloneWorkflowService,
 )

@@ -39,8 +39,6 @@ from packages.application.voice_library.use_cases import (
 from packages.domain.preset_voices import PRESET_VOICES
 from packages.ports.user_repository import UserRepository

-from app.api.routes._helpers import get_user_plan
-
 router = APIRouter()


@@ -127,6 +125,13 @@ def _preset_to_unified_response(preset) -> UnifiedVoiceItemResponse:
    )


+def _get_user_plan(user_id: str, user_repository: UserRepository) -> str:
+    user = user_repository.find_by_id(user_id)
+    if user is None:
+        return "free"
+    return getattr(user, "subscription_plan", "free") or "free"
+
+
 # ==================== 统一配音列表（预置 + 克隆）====================


@@ -266,7 +271,7 @@ def create_voice(
    sign_url=Depends(get_audio_url_signer),
 ) -> VoiceLibraryItemResponse:
    user_id = authenticated_user.user.id
-    plan_name = get_user_plan(user_id, user_repository)
+    plan_name = _get_user_plan(user_id, user_repository)
    command = CreateVoiceLibraryCommand(
        user_id=user_id,
        name=request.name,
@@ -25,7 +25,7 @@ class Settings(BaseSettings):
    DATABASE_POOL_SIZE: int = 20
    DATABASE_MAX_OVERFLOW: int = 10  # 调整为合理值：pool_size(20) + max_overflow(10) = 最大30连接
    DATABASE_POOL_TIMEOUT: int = 30
-    DATABASE_POOL_RECYCLE: int = 3600
+    DATABASE_POOL_RECYLE: int = 3600
    USE_IN_MEMORY_DB: bool = False
    AUTO_CREATE_SCHEMA: bool = False

@@ -41,11 +41,6 @@ class Settings(BaseSettings):
    # 密钥轮换天数（到达此天数后建议更换密钥）
    SECRET_ROTATION_DAYS: int = 90

-    # JWT 算法与过期时间（与 .env.example 对齐）
-    JWT_ALGORITHM: str = "HS256"
-    JWT_ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
-    JWT_REFRESH_TOKEN_EXPIRE_DAYS: int = 30
-
    @field_validator("JWT_SECRET_KEY", mode="before")
    @classmethod
    def validate_jwt_secret_key(cls, v):
@@ -0,0 +1 @@
+"""Core configuration package."""
@@ -50,8 +50,20 @@ from packages.adapters.sqlalchemy_impl.voice_clone_profile_repository import (
 from packages.adapters.sqlalchemy_impl.voice_library_repository import (
    SQLAlchemyVoiceLibraryRepository,
 )
+from packages.ports.asset_library_repository import AssetLibraryRepository
+from packages.ports.asset_repository import AssetRepository
+from packages.ports.classification_job_repository import ClassificationJobRepository
+from packages.ports.duplication_repository import DuplicationRecordRepository
+from packages.ports.generated_video_repository import GeneratedVideoRepository
+from packages.ports.generation_task_repository import GenerationTaskRepository
+from packages.ports.ingest_job_repository import IngestJobRepository
+from packages.ports.job_repository import JobRepository
+from packages.ports.project_repository import ProjectRepository
 from packages.ports.tag_repository import TagRepository
+from packages.ports.title_library_repository import TitleLibraryRepository
 from packages.ports.user_repository import UserRepository
+from packages.ports.voice_clone_profile_repository import VoiceCloneProfileRepository
+from packages.ports.voice_library_repository import VoiceLibraryRepository

 _engine, _SessionLocal = build_session_factory(settings.DATABASE_URL)

@@ -10,7 +10,7 @@ from __future__ import annotations
 from app.auth import AuthenticatedUser
 from app.auth import get_current_user as get_authenticated_user
 from app.dependencies import get_user_repository
-from fastapi import Depends, HTTPException
+from fastapi import Depends
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer

 from packages.domain.entities import User
@@ -6,7 +6,7 @@ import logging
 import time
 from typing import Callable

-from fastapi import Request
+from fastapi import Request, Response
 from starlette.middleware.base import BaseHTTPMiddleware

 logger = logging.getLogger(__name__)
@@ -2,7 +2,7 @@

 from __future__ import annotations

-from typing import Optional
+from typing import List, Optional

 from pydantic import BaseModel, Field

@@ -24,7 +24,7 @@ from packages.adapters.sqlalchemy_impl import (
 )
 from packages.domain.asset import AssetType
 from packages.domain.classification import AssetClassification
-from packages.domain.edit_plan_clip import EditPlanClip
+from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus

 logger = logging.getLogger(__name__)

@@ -18,6 +18,7 @@ from packages.adapters.sqlalchemy_impl import (
 )
 from packages.domain.edit_plan import EditPlan, EditPlanStatus
 from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
+from packages.domain.generation_task import GenerationTaskStatus

 logger = logging.getLogger(__name__)

@@ -13,6 +13,7 @@ from __future__ import annotations
 import logging
 from typing import Any

+from sqlalchemy.orm import Session

 from packages.application.jobs import (
    CancelJobUseCase,
@@ -13,7 +13,7 @@
 from __future__ import annotations

 import logging
-from typing import Any, List
+from typing import Any, List, Optional

 from sqlalchemy.orm import Session

@@ -16,6 +16,7 @@ FFmpeg 视频合成编排服务：
 from __future__ import annotations

 import logging
+import shutil
 from dataclasses import dataclass, field
 from typing import Any

@@ -27,7 +28,7 @@ from packages.adapters.sqlalchemy_impl.edit_plan_clip_repository import (
 from packages.adapters.sqlalchemy_impl.edit_plan_repository import (
    SQLAlchemyEditPlanRepository,
 )
-from packages.domain.edit_plan import EditPlanStatus
+from packages.domain.edit_plan import EditPlan, EditPlanStatus
 from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
 from packages.domain.template_clip_config import TransitionEffect

@@ -0,0 +1,42 @@
+/**
+ * 仪表盘 API
+ * Phase 1 新增：用户仪表盘概览
+ */
+import apiClient from "./client";
+
+/** 仪表盘概览数据 */
+export interface DashboardOverview {
+  /** 素材总数 */
+  total_assets: number;
+  /** 已用存储（字节） */
+  used_storage_bytes: number;
+  /** 总标题数 */
+  total_titles: number;
+  /** 总配音数 */
+  total_voices: number;
+  /** 生成任务总数 */
+  total_tasks: number;
+  /** 成品总数 */
+  total_products: number;
+  /** 最近生成任务 */
+  recent_tasks: Array<{
+    id: string;
+    task_type: string;
+    status: string;
+    progress: number;
+    user_message: string;
+    created_at: string;
+  }>;
+  /** 订阅信息 */
+  subscription: {
+    plan: "free" | "pro" | "enterprise";
+    status: "active" | "inactive" | "expired";
+    expires_at?: string;
+  };
+}
+
+/** 获取仪表盘概览数据 */
+export const getDashboardOverview = async (): Promise<DashboardOverview> => {
+  const response = await apiClient.get("/dashboard/overview");
+  return response.data;
+};
@@ -0,0 +1,365 @@
+/* V21 业务组件统一样式 */
+
+/* ==================== 按钮 ==================== */
+.xx-primary-btn {
+  background: var(--gradient-primary) !important;
+  color: var(--text-inverse) !important;
+  border: none !important;
+  border-radius: var(--radius-md) !important;
+  padding: 10px 20px !important;
+  font-weight: var(--font-weight-bold) !important;
+  box-shadow: var(--shadow-primary) !important;
+  transition: var(--transition-all) !important;
+  cursor: pointer;
+  height: auto !important;
+}
+
+.xx-primary-btn:hover {
+  box-shadow: var(--shadow-hover) !important;
+  transform: translateY(-1px);
+}
+
+.xx-ghost-btn {
+  background: transparent !important;
+  color: var(--primary-color) !important;
+  border: 2px solid var(--primary-color) !important;
+  border-radius: var(--radius-md) !important;
+  padding: var(--space-sm) 18px !important;
+  font-weight: var(--font-weight-bold) !important;
+  transition: var(--transition-all) !important;
+  cursor: pointer;
+  height: auto !important;
+}
+
+.xx-ghost-btn:hover {
+  background: var(--primary-soft) !important;
+}
+
+/* ==================== 卡片 ==================== */
+.xx-card {
+  background: var(--bg-elevated);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-xl);
+  box-shadow: var(--shadow-card);
+  padding: var(--space-lg);
+  margin-bottom: 20px;
+  transition: all var(--transition-slow);
+}
+
+.xx-card:hover {
+  box-shadow: var(--shadow-md);
+  transform: translateY(-2px);
+}
+
+/* ==================== 页面结构 ==================== */
+.xx-page {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: var(--space-lg);
+}
+
+.xx-page-head {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  gap: 18px;
+  margin-bottom: 28px;
+}
+
+.xx-page-head h2 {
+  font-size: 26px;
+  font-weight: var(--font-weight-extrabold);
+  color: var(--text-primary);
+  margin: 0 0 var(--space-sm);
+}
+
+.xx-page-head p {
+  font-size: var(--font-size-base);
+  color: var(--text-secondary);
+  margin: 0;
+}
+
+/* ==================== 表格样式 ==================== */
+.xx-table-card {
+  background: var(--bg-elevated);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-xl);
+  box-shadow: var(--shadow-card);
+  padding: 20px;
+  overflow: hidden;
+}
+
+/* 表格包装器 */
+.xx-table-wrapper {
+  border-radius: var(--radius-lg);
+  overflow: hidden;
+}
+
+/* ==================== 标签/Tag ==================== */
+.xx-tag {
+  padding: var(--space-xs) 12px;
+  border-radius: var(--radius-xs);
+  font-size: 13px;
+  font-weight: var(--font-weight-medium);
+}
+
+.xx-tag-indigo {
+  background: var(--primary-soft);
+  color: var(--primary-color);
+  border: 1px solid var(--color-primary-200);
+}
+
+.xx-tag-success {
+  background: var(--success-soft);
+  color: var(--color-secondary-500);
+  border: 1px solid var(--success-border);
+}
+
+.xx-tag-warning {
+  background: var(--warning-soft);
+  color: var(--accent-dark);
+  border: 1px solid var(--color-accent-200);
+}
+
+.xx-tag-error {
+  background: var(--error-soft);
+  color: var(--error-color);
+  border: 1px solid var(--error-border);
+}
+
+/* ==================== 搜索栏 ==================== */
+.xx-search-bar {
+  margin-bottom: 20px;
+}
+
+.xx-search-input {
+  width: 100%;
+  padding: 12px 18px;
+  border: 2px solid var(--border-color);
+  border-radius: var(--radius-md);
+  font-size: var(--font-size-base);
+  background: var(--bg-primary);
+  transition: var(--transition-all);
+  outline: none;
+}
+
+.xx-search-input:focus {
+  border-color: var(--primary-color);
+  box-shadow: 0 0 0 4px
+    color-mix(in srgb, var(--primary-color) 10%, transparent);
+}
+
+/* ==================== Modal ==================== */
+.xx-modal .ant-modal-content {
+  border-radius: var(--radius-xl);
+  padding: var(--space-lg);
+}
+
+.xx-modal .ant-modal-header {
+  border-radius: var(--radius-xl) var(--radius-xl) 0 0;
+  padding: 20px var(--space-lg);
+  border-bottom: 1px solid var(--border-color);
+}
+
+.xx-modal .ant-modal-title {
+  font-size: var(--font-size-lg);
+  font-weight: var(--font-weight-bold);
+  color: var(--text-primary);
+}
+
+.xx-modal .ant-modal-footer {
+  border-top: 1px solid var(--border-color);
+  padding: var(--space-md) var(--space-lg);
+}
+
+/* ==================== 空状态 ==================== */
+.xx-empty-state {
+  text-align: center;
+  padding: var(--space-3xl) var(--space-lg);
+  color: var(--text-secondary);
+}
+
+.xx-empty-state-icon {
+  font-size: 48px;
+  margin-bottom: var(--space-md);
+}
+
+/* ==================== 网格布局 ==================== */
+.xx-grid-2 {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 20px;
+}
+
+.xx-grid-3 {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 20px;
+}
+
+.xx-grid-4 {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 20px;
+}
+
+@media (max-width: 768px) {
+  .xx-grid-2,
+  .xx-grid-3,
+  .xx-grid-4 {
+    grid-template-columns: 1fr;
+  }
+}
+
+/* ==================== 配额展示 ==================== */
+.xx-quota-item {
+  padding: 20px;
+  background: var(--bg-primary);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-lg);
+  transition: var(--transition-all);
+}
+
+.xx-quota-item:hover {
+  border-color: var(--primary-color);
+  box-shadow: 0 8px 24px
+    color-mix(in srgb, var(--primary-color) 10%, transparent);
+}
+
+/* ==================== 进度条 ==================== */
+.xx-progress {
+  margin-top: 12px;
+}
+
+/* ==================== Ant Design 覆盖样式 ==================== */
+/* Table overrides */
+.ant-table-wrapper .ant-table-thead > tr > th {
+  background: var(--bg-secondary) !important;
+  font-weight: var(--font-weight-bold) !important;
+  color: var(--text-primary) !important;
+  border-bottom: 2px solid var(--border-color) !important;
+  padding: 14px var(--space-md) !important;
+}
+
+.ant-table-wrapper .ant-table-tbody > tr > td {
+  padding: 14px var(--space-md) !important;
+  border-bottom: 1px solid var(--color-gray-100) !important;
+}
+
+.ant-table-wrapper .ant-table-tbody > tr:hover > td {
+  background: var(--color-gray-50) !important;
+}
+
+/* Card overrides */
+.ant-card {
+  border-radius: var(--radius-xl) !important;
+  border: 1px solid var(--border-color) !important;
+}
+
+.ant-card-head {
+  border-bottom: 1px solid var(--border-color) !important;
+  min-height: 52px !important;
+  padding: 0 var(--space-lg) !important;
+}
+
+.ant-card-head-title {
+  font-weight: var(--font-weight-bold) !important;
+  font-size: var(--font-size-md) !important;
+  color: var(--text-primary) !important;
+}
+
+.ant-card-body {
+  padding: 20px var(--space-lg) !important;
+}
+
+/* Modal overrides */
+.ant-modal-content {
+  border-radius: var(--radius-xl) !important;
+  overflow: hidden;
+}
+
+.ant-modal-header {
+  padding: 20px var(--space-lg) !important;
+  background: var(--bg-primary) !important;
+}
+
+.ant-modal-title {
+  font-weight: var(--font-weight-bold) !important;
+  font-size: var(--font-size-lg) !important;
+  color: var(--text-primary) !important;
+}
+
+.ant-modal-body {
+  padding: var(--space-lg) !important;
+}
+
+.ant-modal-footer {
+  padding: var(--space-md) var(--space-lg) !important;
+}
+
+/* Button overrides */
+.ant-btn-primary {
+  background: var(--gradient-primary) !important;
+  border: none !important;
+  border-radius: var(--radius-md) !important;
+  box-shadow: var(--shadow-primary) !important;
+  height: auto !important;
+  padding: 10px 20px !important;
+  font-weight: var(--font-weight-bold) !important;
+}
+
+.ant-btn-primary:hover {
+  background: var(--gradient-primary) !important;
+  box-shadow: var(--shadow-hover) !important;
+  transform: translateY(-1px);
+}
+
+/* Tag overrides */
+.ant-tag {
+  border-radius: var(--radius-xs) !important;
+  padding: var(--space-xs) 12px !important;
+  font-weight: var(--font-weight-medium) !important;
+}
+
+/* Select overrides */
+.ant-select-selector {
+  border-radius: var(--radius-md) !important;
+  border-color: var(--border-color) !important;
+}
+
+.ant-select:not(.ant-select-disabled):hover .ant-select-selector {
+  border-color: var(--primary-color) !important;
+}
+
+.ant-select-focused .ant-select-selector {
+  border-color: var(--primary-color) !important;
+  box-shadow: 0 0 0 3px
+    color-mix(in srgb, var(--primary-color) 10%, transparent) !important;
+}
+
+/* Input overrides */
+.ant-input {
+  border-radius: var(--radius-md) !important;
+  border-color: var(--border-color) !important;
+  padding: 10px 14px !important;
+}
+
+.ant-input:hover {
+  border-color: var(--primary-color) !important;
+}
+
+.ant-input:focus {
+  border-color: var(--primary-color) !important;
+  box-shadow: 0 0 0 3px
+    color-mix(in srgb, var(--primary-color) 10%, transparent) !important;
+}
+
+/* Progress overrides */
+.ant-progress-inner {
+  background: var(--color-gray-100) !important;
+  border-radius: var(--radius-xs) !important;
+}
+
+.ant-progress-bg {
+  border-radius: var(--radius-xs) !important;
+}
@@ -0,0 +1,290 @@
+/**
+ * CloneVoiceModal — 音色克隆弹窗
+ *
+ * 三步骤状态：input → uploading → success
+ * 支持上传音频文件或直接录制（mock，无真实录音）
+ *
+ * V21 Design System — 零 antd 直接导入
+ */
+import React, { useState, useCallback, useRef } from "react";
+import { Modal, Button } from "@/components/ui";
+import { createVoiceClone, toVoiceClone } from "@/api/voiceClone";
+import type { VoiceClone } from "@/api/voiceClone";
+import { uploadAsset } from "@/api/assets";
+import "./clone-voice-modal.css";
+
+/* ── 类型定义 ───────────────────────────────────────────── */
+
+type ModalStep = "input" | "uploading" | "success";
+
+export interface CloneVoiceModalProps {
+  /** 弹窗是否可见 */
+  open: boolean;
+  /** 关闭弹窗回调 */
+  onClose: () => void;
+  /** 克隆成功回调（返回新创建的音色） */
+  onSuccess?: (voice: VoiceClone) => void;
+}
+
+/* ── 默认音色名称计数器 ─────────────────────────────────── */
+
+let cloneCounter = 1;
+
+const getNextDefaultName = (): string => {
+  const name = `我的声音 ${cloneCounter}`;
+  cloneCounter += 1;
+  return name;
+};
+
+/* ── 组件 ───────────────────────────────────────────────── */
+
+const CloneVoiceModal: React.FC<CloneVoiceModalProps> = ({
+  open,
+  onClose,
+  onSuccess,
+}) => {
+  const [step, setStep] = useState<ModalStep>("input");
+  const [voiceName, setVoiceName] = useState("");
+  const [isRecording, setIsRecording] = useState(false);
+  const [selectedFile, setSelectedFile] = useState<File | null>(null);
+  const [dragActive, setDragActive] = useState(false);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  /** 重置弹窗状态 */
+  const resetState = useCallback(() => {
+    setStep("input");
+    setVoiceName("");
+    setSelectedFile(null);
+    setIsRecording(false);
+    setDragActive(false);
+  }, []);
+
+  /** 关闭弹窗 */
+  const handleClose = useCallback(() => {
+    resetState();
+    onClose();
+  }, [resetState, onClose]);
+
+  /** 上传区域点击 */
+  const handleUploadClick = () => {
+    fileInputRef.current?.click();
+  };
+
+  /** 文件选择 */
+  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (file) {
+      setSelectedFile(file);
+      // 清除之前的录制状态
+      setIsRecording(false);
+    }
+    // 清空 input 以允许重复选择同一文件
+    e.target.value = "";
+  };
+
+  /** 拖拽事件 */
+  const handleDrag = (e: React.DragEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    if (e.type === "dragenter" || e.type === "dragover") {
+      setDragActive(true);
+    } else if (e.type === "dragleave") {
+      setDragActive(false);
+    }
+  };
+
+  const handleDrop = (e: React.DragEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setDragActive(false);
+    const file = e.dataTransfer.files?.[0];
+    if (file) {
+      const ext = file.name.split(".").pop()?.toLowerCase();
+      if (ext === "mp3" || ext === "wav") {
+        setSelectedFile(file);
+        setIsRecording(false);
+      }
+    }
+  };
+
+  /** 录制按钮（mock） */
+  const handleRecord = () => {
+    setIsRecording((prev) => !prev);
+    if (!isRecording) {
+      // 开始录制 — 清除已选文件
+      setSelectedFile(null);
+    }
+  };
+
+  /** 开始克隆 */
+  const handleStartClone = async () => {
+    const name = voiceName.trim() || getNextDefaultName();
+    setStep("uploading");
+
+    try {
+      // 先上传音频文件获取真实 URL
+      let audioUrl: string;
+      if (selectedFile) {
+        const formData = new FormData();
+        formData.append("file", selectedFile);
+        formData.append("kind", "voice");
+        const uploadResult = await uploadAsset(formData);
+        audioUrl = uploadResult.url;
+      } else {
+        // 录制功能暂未实现，提示用户上传
+        setStep("input");
+        return;
+      }
+
+      // 提交克隆请求
+      const result = await createVoiceClone({
+        name,
+        audio_url: audioUrl,
+      });
+
+      setStep("success");
+
+      // 2秒后自动关闭
+      setTimeout(() => {
+        onSuccess?.(toVoiceClone(result));
+        handleClose();
+      }, 2000);
+    } catch {
+      setStep("input");
+    }
+  };
+
+  /** 弹窗打开时初始化默认名称 */
+  const handleAfterOpenChange = (visible: boolean) => {
+    if (visible) {
+      setVoiceName(getNextDefaultName());
+    }
+  };
+
+  const canStart = selectedFile || isRecording;
+
+  return (
+    <Modal
+      open={open}
+      onCancel={handleClose}
+      title="🎤 克隆新音色"
+      width={520}
+      footer={null}
+      destroyOnClose
+      afterOpenChange={handleAfterOpenChange}
+    >
+      {/* ── 输入步骤 ──────────────────────────────────── */}
+      {step === "input" && (
+        <div className="cvm-body">
+          {/* 音色名称 */}
+          <div className="cvm-field">
+            <label className="cvm-label">音色名称</label>
+            <input
+              type="text"
+              className="cvm-input"
+              value={voiceName}
+              onChange={(e) => setVoiceName(e.target.value)}
+              placeholder="输入音色名称"
+            />
+          </div>
+
+          {/* 上传区域 */}
+          <div className="cvm-field">
+            <label className="cvm-label">上传音频</label>
+            <div
+              className={`cvm-upload-zone${dragActive ? " cvm-upload-zone--active" : ""}`}
+              onClick={handleUploadClick}
+              onDragEnter={handleDrag}
+              onDragOver={handleDrag}
+              onDragLeave={handleDrag}
+              onDrop={handleDrop}
+            >
+              <div className="cvm-upload-icon">🎵</div>
+              <p className="cvm-upload-title">
+                {selectedFile ? selectedFile.name : "拖拽音频文件到此处"}
+              </p>
+              <p className="cvm-upload-hint">支持 MP3、WAV 格式</p>
+              <input
+                ref={fileInputRef}
+                type="file"
+                accept=".mp3,.wav,audio/mpeg,audio/wav"
+                style={{ display: "none" }}
+                onChange={handleFileChange}
+              />
+            </div>
+          </div>
+
+          {/* 或分隔 */}
+          <div className="cvm-divider">
+            <div className="cvm-divider-line" />
+            <span className="cvm-divider-text">或</span>
+            <div className="cvm-divider-line" />
+          </div>
+
+          {/* 录制区域 */}
+          <div className="cvm-field">
+            <label className="cvm-label">直接录制</label>
+            <div className="cvm-record-area">
+              <p className="cvm-record-hint">
+                {isRecording
+                  ? "录制中…再次点击停止"
+                  : "点击按钮开始录制你的声音"}
+              </p>
+              <button
+                type="button"
+                className={`cvm-record-btn${isRecording ? " cvm-record-btn--recording" : ""}`}
+                onClick={handleRecord}
+              >
+                🎙️
+              </button>
+            </div>
+          </div>
+
+          {/* 提示 */}
+          <div className="cvm-tip">
+            <span className="cvm-tip-icon">💡</span>
+            <span>
+              建议上传10秒~3分钟的清晰语音，环境安静、语速均匀效果最佳
+            </span>
+          </div>
+
+          {/* 底部按钮 */}
+          <div className="cvm-footer">
+            <Button buttonType="ghost" onClick={handleClose}>
+              取消
+            </Button>
+            <Button
+              buttonType="primary"
+              disabled={!canStart}
+              onClick={handleStartClone}
+            >
+              🎤 开始克隆
+            </Button>
+          </div>
+        </div>
+      )}
+
+      {/* ── 上传中步骤 ────────────────────────────────── */}
+      {step === "uploading" && (
+        <div className="cvm-uploading">
+          <div className="cvm-uploading-spinner" />
+          <p className="cvm-uploading-text">正在克隆你的音色…</p>
+          <p className="cvm-uploading-sub">AI 正在分析你的声音特征，请稍候</p>
+        </div>
+      )}
+
+      {/* ── 成功步骤 ──────────────────────────────────── */}
+      {step === "success" && (
+        <div className="cvm-success">
+          <div className="cvm-success-icon">✅</div>
+          <h3 className="cvm-success-title">克隆已提交</h3>
+          <p className="cvm-success-desc">
+            音色正在生成中，完成后将出现在列表中
+          </p>
+        </div>
+      )}
+    </Modal>
+  );
+};
+
+export default CloneVoiceModal;
@@ -0,0 +1,325 @@
+/**
+ * CloneVoiceModal — V21 Design System
+ *
+ * 音色克隆弹窗样式
+ * 三步骤状态：input → uploading → success
+ */
+
+/* ── 弹窗内容区 ─────────────────────────────────────────── */
+
+.cvm-body {
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+}
+
+/* ── 表单区 ─────────────────────────────────────────────── */
+
+.cvm-field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.cvm-label {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--text-secondary, #475467);
+}
+
+.cvm-input {
+  width: 100%;
+  padding: 10px 14px;
+  border: 1px solid var(--line, #e4e7ec);
+  border-radius: var(--radius-sm);
+  background: var(--bg-surface, #fff);
+  color: var(--text-primary, #101828);
+  font-size: 14px;
+  line-height: 1.5;
+  transition:
+    border-color 0.2s,
+    box-shadow 0.2s;
+  outline: none;
+}
+
+.cvm-input:focus {
+  border-color: var(--primary, #6366f1);
+  box-shadow: 0 0 0 3px
+    color-mix(in srgb, var(--primary-color) 12%, transparent);
+}
+
+.cvm-input::placeholder {
+  color: var(--muted, #98a2b3);
+}
+
+/* ── 上传区域 ───────────────────────────────────────────── */
+
+.cvm-upload-zone {
+  border: 2px dashed var(--line, #e4e7ec);
+  border-radius: var(--radius-md);
+  padding: 28px 20px;
+  text-align: center;
+  background: var(--bg-subtle, #f8fafc);
+  cursor: pointer;
+  transition:
+    border-color 0.2s,
+    background 0.2s;
+}
+
+.cvm-upload-zone:hover {
+  border-color: var(--primary, #6366f1);
+  background: color-mix(in srgb, var(--primary-color) 4%, transparent);
+}
+
+.cvm-upload-zone.cvm-upload-zone--active {
+  border-color: var(--primary, #6366f1);
+  background: color-mix(in srgb, var(--primary-color) 6%, transparent);
+}
+
+.cvm-upload-icon {
+  font-size: 36px;
+  margin-bottom: 8px;
+  line-height: 1;
+}
+
+.cvm-upload-title {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary, #101828);
+  margin: 0 0 4px;
+}
+
+.cvm-upload-hint {
+  font-size: 13px;
+  color: var(--muted, #98a2b3);
+  margin: 0;
+}
+
+/* ── 或分隔线 ───────────────────────────────────────────── */
+
+.cvm-divider {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  margin: 4px 0;
+}
+
+.cvm-divider-line {
+  flex: 1;
+  height: 1px;
+  background: var(--line, #e4e7ec);
+}
+
+.cvm-divider-text {
+  font-size: 13px;
+  color: var(--muted, #98a2b3);
+  flex-shrink: 0;
+}
+
+/* ── 录制区域 ───────────────────────────────────────────── */
+
+.cvm-record-area {
+  border: 1px solid var(--line, #e4e7ec);
+  border-radius: var(--radius-md);
+  padding: 24px;
+  text-align: center;
+}
+
+.cvm-record-hint {
+  font-size: 13px;
+  color: var(--muted, #98a2b3);
+  margin: 0 0 14px;
+}
+
+.cvm-record-btn {
+  width: 80px;
+  height: 80px;
+  border-radius: 50%;
+  border: none;
+  cursor: pointer;
+  font-size: 32px;
+  line-height: 1;
+  padding: 0;
+  background: linear-gradient(
+    135deg,
+    var(--error-color, #ef4444),
+    var(--error-dark, #dc2626)
+  );
+  color: var(--text-inverse);
+  box-shadow: 0 4px 14px
+    color-mix(in srgb, var(--error-color, #ef4444) 35%, transparent);
+  transition:
+    transform 0.15s,
+    box-shadow 0.15s;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.cvm-record-btn:hover {
+  transform: scale(1.06);
+  box-shadow: 0 6px 20px
+    color-mix(in srgb, var(--error-color, #ef4444) 45%, transparent);
+}
+
+.cvm-record-btn:active {
+  transform: scale(0.96);
+}
+
+.cvm-record-btn--recording {
+  animation: cvm-pulse 1.2s ease-in-out infinite;
+}
+
+@keyframes cvm-pulse {
+  0%,
+  100% {
+    box-shadow: 0 4px 14px
+      color-mix(in srgb, var(--error-color, #ef4444) 35%, transparent);
+  }
+  50% {
+    box-shadow: 0 4px 28px
+      color-mix(in srgb, var(--error-color, #ef4444) 60%, transparent);
+  }
+}
+
+/* ── 提示条 ─────────────────────────────────────────────── */
+
+.cvm-tip {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  padding: 12px 16px;
+  background: var(--warning-soft, #fef3c7);
+  border-radius: var(--radius-sm);
+  font-size: 13px;
+  color: var(--warning-color, #92400e);
+  line-height: 1.5;
+}
+
+.cvm-tip-icon {
+  flex-shrink: 0;
+  font-size: 14px;
+  line-height: 1.5;
+}
+
+/* ── 底部按钮 ───────────────────────────────────────────── */
+
+.cvm-footer {
+  display: flex;
+  gap: 12px;
+  margin-top: 4px;
+}
+
+.cvm-footer .xx-btn {
+  flex: 1;
+}
+
+/* ── 上传中状态 ─────────────────────────────────────────── */
+
+.cvm-uploading {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 48px 20px;
+  gap: 16px;
+}
+
+.cvm-uploading-spinner {
+  width: 48px;
+  height: 48px;
+  border: 3px solid var(--line, #e4e7ec);
+  border-top-color: var(--primary, #6366f1);
+  border-radius: 50%;
+  animation: cvm-spin 0.8s linear infinite;
+}
+
+@keyframes cvm-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.cvm-uploading-text {
+  font-size: 15px;
+  font-weight: 500;
+  color: var(--text-primary, #101828);
+  margin: 0;
+}
+
+.cvm-uploading-sub {
+  font-size: 13px;
+  color: var(--muted, #98a2b3);
+  margin: 0;
+}
+
+/* ── 成功状态 ───────────────────────────────────────────── */
+
+.cvm-success {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 48px 20px;
+  gap: 12px;
+}
+
+.cvm-success-icon {
+  font-size: 56px;
+  line-height: 1;
+}
+
+.cvm-success-title {
+  font-size: 18px;
+  font-weight: 700;
+  color: var(--text-primary, #101828);
+  margin: 0;
+}
+
+.cvm-success-desc {
+  font-size: 14px;
+  color: var(--muted, #98a2b3);
+  margin: 0;
+}
+
+/* ── 响应式 ─────────────────────────────────────────────── */
+
+@media (max-width: 768px) {
+  .cvm-overlay {
+    padding: var(--space-md);
+  }
+
+  .cvm-modal {
+    width: 100%;
+    max-width: 100%;
+    padding: var(--space-lg);
+  }
+}
+
+@media (max-width: 576px) {
+  .cvm-upload-zone {
+    padding: 20px 14px;
+  }
+
+  .cvm-record-btn {
+    width: 64px;
+    height: 64px;
+    font-size: 26px;
+  }
+
+  .cvm-footer {
+    flex-direction: column;
+  }
+}
+
+@media (max-width: 480px) {
+  .cvm-record-btn {
+    width: 60px;
+    height: 60px;
+  }
+
+  .cvm-tip {
+    font-size: 12px;
+    padding: var(--space-sm);
+  }
+}
@@ -532,23 +532,3 @@
    padding: 8px 16px !important;
  }
 }
-
-
-/* ── xx-card antd 子元素覆盖样式（从 Admin.css 迁移） ── */
-/* AdminComingSoon 等页面使用 <Card className="xx-card"> 时需要 */
-/* .xx-card 基础样式和 :hover 已在 global.css 中定义（V21 设计系统） */
-
-.xx-card .ant-card-head {
-  border-bottom: 1px solid var(--border-color);
-  padding: 20px 24px;
-}
-
-.xx-card .ant-card-head-title {
-  font-weight: 800;
-  font-size: 17px;
-  color: var(--text-primary);
-}
-
-.xx-card .ant-card-body {
-  padding: 24px;
-}
@@ -0,0 +1,211 @@
+/**
+ * 统一导航配置
+ * Header 和 Sidebar 共用此数据源
+ */
+import React from "react";
+import {
+  DashboardOutlined,
+  VideoCameraOutlined,
+  FileOutlined,
+  AudioOutlined,
+  FileTextOutlined,
+  TrophyOutlined,
+  AppstoreOutlined,
+  HistoryOutlined,
+  ControlOutlined,
+  CrownOutlined,
+  ScanOutlined,
+  EditOutlined,
+  FolderOutlined,
+} from "@ant-design/icons";
+
+/** 导航项定义 */
+export interface NavItem {
+  key: string;
+  label: string;
+  path: string;
+  icon: React.ReactNode;
+}
+
+/** 导航分组定义 */
+export interface NavGroup {
+  title: string;
+  items: NavItem[];
+}
+
+/**
+ * 扁平导航列表（Header 使用）
+ */
+export const NAV_ITEMS: NavItem[] = [
+  {
+    key: "dashboard",
+    label: "概览",
+    path: "/app/dashboard",
+    icon: <DashboardOutlined />,
+  },
+  {
+    key: "assets",
+    label: "素材库",
+    path: "/app/assets",
+    icon: <FileOutlined />,
+  },
+  {
+    key: "titles",
+    label: "标题库",
+    path: "/app/titles",
+    icon: <FileTextOutlined />,
+  },
+  {
+    key: "voices",
+    label: "配音库",
+    path: "/app/voices",
+    icon: <AudioOutlined />,
+  },
+  {
+    key: "voice-clone",
+    label: "我的音色",
+    path: "/app/voice-clone",
+    icon: <AudioOutlined />,
+  },
+  {
+    key: "voice-materials",
+    label: "配音素材库",
+    path: "/app/voice-materials",
+    icon: <AudioOutlined />,
+  },
+  {
+    key: "templates",
+    label: "模板库",
+    path: "/app/templates",
+    icon: <AppstoreOutlined />,
+  },
+  {
+    key: "editing-planner",
+    label: "剪辑编辑器",
+    path: "/app/editing-planner",
+    icon: <EditOutlined />,
+  },
+  {
+    key: "my-templates",
+    label: "我的模板",
+    path: "/app/my-templates",
+    icon: <FolderOutlined />,
+  },
+  {
+    key: "generate",
+    label: "一键生成",
+    path: "/app/generate",
+    icon: <VideoCameraOutlined />,
+  },
+  {
+    key: "history",
+    label: "任务历史",
+    path: "/app/history",
+    icon: <HistoryOutlined />,
+  },
+  {
+    key: "products",
+    label: "成品库",
+    path: "/app/products",
+    icon: <TrophyOutlined />,
+  },
+  {
+    key: "duplication",
+    label: "查重",
+    path: "/app/duplication",
+    icon: <ScanOutlined />,
+  },
+];
+
+/**
+ * 分组导航列表（Sidebar 使用）
+ */
+export const NAV_GROUPS: NavGroup[] = [
+  {
+    title: "创作工具",
+    items: [
+      {
+        key: "dashboard",
+        label: "首页",
+        path: "/app/dashboard",
+        icon: <DashboardOutlined />,
+      },
+      {
+        key: "generate",
+        label: "一键生成",
+        path: "/app/generate",
+        icon: <VideoCameraOutlined />,
+      },
+    ],
+  },
+  {
+    title: "资源管理",
+    items: [
+      {
+        key: "assets",
+        label: "素材库",
+        path: "/app/assets",
+        icon: <FileOutlined />,
+      },
+      {
+        key: "voices",
+        label: "配音库",
+        path: "/app/voices",
+        icon: <AudioOutlined />,
+      },
+      {
+        key: "voice-clone",
+        label: "我的音色",
+        path: "/app/voice-clone",
+        icon: <AudioOutlined />,
+      },
+      {
+        key: "voice-materials",
+        label: "配音素材库",
+        path: "/app/voice-materials",
+        icon: <AudioOutlined />,
+      },
+      {
+        key: "titles",
+        label: "标题库",
+        path: "/app/titles",
+        icon: <FileTextOutlined />,
+      },
+      {
+        key: "products",
+        label: "成片库",
+        path: "/app/products",
+        icon: <TrophyOutlined />,
+      },
+      {
+        key: "templates",
+        label: "模板库",
+        path: "/app/templates",
+        icon: <AppstoreOutlined />,
+      },
+    ],
+  },
+  {
+    title: "系统",
+    items: [
+      {
+        key: "history",
+        label: "任务历史",
+        path: "/app/history",
+        icon: <HistoryOutlined />,
+      },
+      {
+        key: "admin",
+        label: "控制台",
+        path: "/app/admin",
+        icon: <ControlOutlined />,
+      },
+      {
+        key: "subscription",
+        label: "订阅管理",
+        path: "/app/subscription",
+        icon: <CrownOutlined />,
+      },
+    ],
+  },
+];
@@ -153,7 +153,7 @@ const Accounts: React.FC = () => {
    },
  });

-  /** 绑定 mutation */
+  /** 绑定 mutation（mock） */
  const bindMutation = useMutation({
    mutationFn: bindAccount,
    onSuccess: () => {
@@ -165,7 +165,7 @@ const Accounts: React.FC = () => {
    },
  });

-  /** 绑定新账号 */
+  /** 绑定新账号（mock：直接创建） */
  const handleBind = (platformId: PlatformId) => {
    const platform = PLATFORMS.find((p) => p.id === platformId);
    if (!platform) return;
@@ -75,6 +75,35 @@
  margin: 0;
 }

+/* V21 卡片 */
+.xx-card {
+  background: rgba(255, 255, 255, 0.94);
+  border: 1px solid rgba(226, 232, 240, 0.95);
+  border-radius: var(--radius-lg);
+  box-shadow: 0 10px 30px rgba(15, 23, 42, 0.06);
+  padding: 24px;
+  transition: all 0.3s;
+}
+
+.xx-card:hover {
+  box-shadow: 0 16px 40px rgba(15, 23, 42, 0.08);
+}
+
+.xx-card .ant-card-head {
+  border-bottom: 1px solid rgba(226, 232, 240, 0.8);
+  padding: 20px 24px;
+}
+
+.xx-card .ant-card-head-title {
+  font-weight: 800;
+  font-size: 17px;
+  color: var(--slate, #0f172a);
+}
+
+.xx-card .ant-card-body {
+  padding: 24px;
+}
+
 /* 统计卡片网格 - 4列 */
 .xx-grid-4 {
  display: grid;
@@ -273,6 +302,17 @@
  box-shadow: 0 0 0 3px rgba(79, 70, 229, 0.1) !important;
 }

+/* V21 Select */
+.xx-select {
+  border-radius: var(--radius-md) !important;
+}
+
+.xx-select:hover,
+.xx-select:focus {
+  border-color: var(--indigo, #4f46e5) !important;
+  box-shadow: 0 0 0 3px rgba(79, 70, 229, 0.1) !important;
+}
+
 /* V21 Tag */
 .xx-tag {
  border-radius: var(--radius-xs) !important;
@@ -29,7 +29,6 @@ interface KpiItem {
  accent: string;
 }

-// TODO: kpiData 当前使用硬编码 mock 数据，待后端提供 Dashboard 统计 API 后替换
 const kpiData: KpiItem[] = [
  {
    key: "projects",
@@ -82,7 +81,6 @@ interface QuickEntry {
  path: string;
 }

-// TODO: quickEntries 描述中含硬编码计数（如 486个素材），待后端 API 后动态化
 const quickEntries: QuickEntry[] = [
  {
    id: "titles",
@@ -137,7 +135,6 @@ const statusLabel: Record<TaskStatus, string> = {
  failed: "失败",
 };

-// TODO: recentTasks 当前使用硬编码 mock 数据，待后端提供最近任务 API 后替换
 const recentTasks: RecentTask[] = [
  {
    id: "t-1",
@@ -612,6 +612,54 @@
  flex: 1;
 }

+/* ============================================================
+   按钮（匹配原型 .btn .ghost / .btn .primary）
+   ============================================================ */
+.xx-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  height: 42px;
+  padding: 0 20px;
+  border-radius: var(--radius-sm);
+  font-size: 14px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.15s ease;
+  border: none;
+  outline: none;
+  white-space: nowrap;
+}
+
+.xx-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.xx-btn-primary {
+  background: var(--gradient-primary);
+  color: var(--text-inverse);
+  box-shadow: 0 14px 26px rgba(79, 70, 229, 0.22);
+}
+
+.xx-btn-primary:hover:not(:disabled) {
+  transform: translateY(-2px);
+  box-shadow: 0 18px 34px rgba(79, 70, 229, 0.28);
+}
+
+.xx-btn-ghost {
+  background: var(--bg-primary);
+  border: 1px solid var(--border-color);
+  color: var(--text-secondary);
+}
+
+.xx-btn-ghost:hover:not(:disabled) {
+  border-color: var(--info-border);
+  color: var(--primary-dark);
+  background: var(--primary-soft);
+}
+
 /* ============================================================
   右侧预览区 generate-preview
   ============================================================ */
@@ -55,9 +55,13 @@ interface TitleData {
 /* ============================================================
 * Mock 数据
 * ============================================================ */
-// TODO: 分类数据当前为前端硬编码 mock，待后端提供标题分类 API 后替换
 const MOCK_CATEGORIES: CategoryItem[] = [
-  { id: "cat-all", name: "全部标题", count: 0 },
+  { id: "cat-all", name: "全部标题", count: 15 },
+  { id: "cat-1", name: "美食探店", count: 4 },
+  { id: "cat-2", name: "科技数码", count: 3 },
+  { id: "cat-3", name: "生活日常", count: 4 },
+  { id: "cat-4", name: "美妆穿搭", count: 2 },
+  { id: "cat-5", name: "教育学习", count: 2 },
 ];

 /** 后端 TitleItem → 前端 TitleData 映射 */
@@ -18,7 +18,7 @@ import {
  CloseCircleOutlined,
 } from "@ant-design/icons";
 import PageHead from "@/components/layout/PageHead";
-import CloneModal from "@/components/voice/CloneModal";
+import CloneVoiceModal from "@/components/modals/CloneVoiceModal";
 import {
  getVoiceClones,
  deleteVoiceClone,
@@ -356,7 +356,7 @@ const VoiceClone: React.FC = () => {
      )}

      {/* 克隆音色弹窗 */}
-      <CloneModal
+      <CloneVoiceModal
        open={cloneModalOpen}
        onClose={() => setCloneModalOpen(false)}
        onSuccess={() => {
@@ -170,6 +170,13 @@ export const router = createBrowserRouter([
            Component: m.default,
          })),
      },
+      {
+        path: "my-voices",
+        lazy: () =>
+          import("@/pages/my-voices/MyVoices").then((m) => ({
+            Component: m.default,
+          })),
+      },
      {
        path: "accounts",
        lazy: () =>
@@ -0,0 +1,214 @@
+"""渲染引擎灰度观测指标。
+
+提供 Prometheus 指标埋点，用于灰度发布期间观测新旧引擎的：
+  - 任务成功率
+  - 耗时分布
+  - 错误类型分布
+  - stream_copy 命中率
+
+使用方式（任务入口）：
+    with render_task_metrics(engine="unified", task_type="compose_video"):
+        # 执行渲染任务
+        result = do_render()
+
+stream_copy 埋点：
+    record_stream_copy(result="hit", reason="成功")
+    record_stream_copy(result="miss", reason="编码不匹配")
+    record_stream_copy(result="fallback", reason="失败回退")
+
+Worker 进程启动时需调用 start_metrics_server(port) 暴露 /metrics 端点。
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from contextlib import contextmanager
+from typing import Iterator, Optional
+
+from prometheus_client import REGISTRY, Counter, Gauge, Histogram, start_http_server
+
+logger = logging.getLogger(__name__)
+
+
+# ── 指标定义 ──────────────────────────────────────────────────────────────────
+
+# 渲染任务总数（按引擎、任务类型、状态区分）
+RENDER_TASK_TOTAL = Counter(
+    "render_task_total",
+    "Total number of render tasks",
+    ["engine", "task_type", "status"],
+    registry=REGISTRY,
+)
+
+# 渲染任务耗时直方图（按引擎、任务类型区分）
+# buckets 覆盖从秒级到小时级，适配短视频到长视频的渲染场景
+RENDER_TASK_DURATION_SECONDS = Histogram(
+    "render_task_duration_seconds",
+    "Render task duration in seconds",
+    ["engine", "task_type"],
+    buckets=(1, 5, 10, 30, 60, 120, 300, 600, 900, 1800, 3600, 7200),
+    registry=REGISTRY,
+)
+
+# 渲染错误统计（按引擎、任务类型、错误类型区分）
+RENDER_ERROR_TOTAL = Counter(
+    "render_error_total",
+    "Total number of render errors",
+    ["engine", "task_type", "error_type"],
+    registry=REGISTRY,
+)
+
+# stream_copy 命中统计（仅新引擎有意义）
+RENDER_STREAM_COPY_TOTAL = Counter(
+    "render_stream_copy_total",
+    "Total number of stream copy attempts and results",
+    ["result", "reason"],
+    registry=REGISTRY,
+)
+
+# 当前正在执行的渲染任务数
+RENDER_ACTIVE_TASKS = Gauge(
+    "render_active_tasks",
+    "Number of render tasks currently in progress",
+    ["engine", "task_type"],
+    registry=REGISTRY,
+)
+
+
+# ── Metrics Server ───────────────────────────────────────────────────────────
+
+_metrics_server_started = False
+_metrics_server_lock = threading.Lock()
+
+
+def start_metrics_server(port: int = 9101) -> None:
+    """启动 Prometheus metrics HTTP 服务器。
+
+    在 worker 进程启动时调用一次即可，多进程环境下每个 worker 进程
+    会启动自己的 metrics server（需配置不同端口或使用进程号偏移）。
+
+    Args:
+        port: metrics 服务端口，默认 9101
+    """
+    global _metrics_server_started
+
+    with _metrics_server_lock:
+        if _metrics_server_started:
+            return
+
+        try:
+            start_http_server(port)
+            _metrics_server_started = True
+            logger.info("Render metrics server started on port %d", port)
+        except OSError as e:
+            # 端口已占用可能是多 worker 进程场景，记录警告不阻断
+            logger.warning("Failed to start metrics server on port %d: %s", port, e)
+
+
+# ── 任务级埋点 ───────────────────────────────────────────────────────────────
+
+@contextmanager
+def render_task_metrics(engine: str, task_type: str) -> Iterator[None]:
+    """渲染任务指标上下文管理器。
+
+    自动记录：任务开始（活跃数+1）、任务结束（耗时 + 状态 + 活跃数-1）。
+
+    Args:
+        engine: 渲染引擎类型，"legacy" 或 "unified"
+        task_type: 任务类型，"compose_video" / "edit_plan" / "generate_video"
+
+    Usage:
+        with render_task_metrics(engine="unified", task_type="compose_video"):
+            result = do_render()
+            # 正常退出 = success
+            # 抛异常 = failure（会记录 error_type）
+    """
+    RENDER_ACTIVE_TASKS.labels(engine=engine, task_type=task_type).inc()
+    start_time = time.perf_counter()
+    status = "success"
+
+    try:
+        yield
+    except Exception as e:
+        status = "failure"
+        error_type = _classify_error(e)
+        RENDER_ERROR_TOTAL.labels(
+            engine=engine,
+            task_type=task_type,
+            error_type=error_type,
+        ).inc()
+        raise
+    finally:
+        duration = time.perf_counter() - start_time
+        RENDER_TASK_TOTAL.labels(
+            engine=engine,
+            task_type=task_type,
+            status=status,
+        ).inc()
+        RENDER_TASK_DURATION_SECONDS.labels(
+            engine=engine,
+            task_type=task_type,
+        ).observe(duration)
+        RENDER_ACTIVE_TASKS.labels(engine=engine, task_type=task_type).dec()
+
+
+def record_stream_copy(result: str, reason: str) -> None:
+    """记录 stream_copy 命中/跳过/回退情况。
+
+    Args:
+        result: "hit"（命中直通） / "miss"（条件不满足跳过） / "fallback"（失败回退）
+        reason: 具体原因，如"编码不匹配"、"分辨率不同"、"成功"、"ffmpeg失败"等
+    """
+    RENDER_STREAM_COPY_TOTAL.labels(result=result, reason=reason).inc()
+
+
+# ── 辅助函数 ─────────────────────────────────────────────────────────────────
+
+def _classify_error(exc: BaseException) -> str:
+    """将异常分类为标准错误类型。
+
+    用于 error_type 标签，控制指标基数不要爆炸。
+    """
+    import subprocess
+
+    if isinstance(exc, subprocess.TimeoutExpired):
+        return "timeout"
+    if isinstance(exc, subprocess.CalledProcessError):
+        return "ffmpeg_error"
+    if isinstance(exc, ValueError):
+        return "validation"
+    if isinstance(exc, (OSError, IOError)):
+        return "io_error"
+
+    exc_name = type(exc).__name__
+    # 常见的 OSS / 网络相关异常
+    if "oss" in exc_name.lower() or "storage" in exc_name.lower():
+        return "oss_error"
+    if "timeout" in exc_name.lower():
+        return "timeout"
+
+    return "unknown"
+
+
+def classify_stream_copy_miss_reason(reason: str) -> str:
+    """将 stream_copy 未命中原因归一化为标准分类。
+
+    控制 reason 标签基数，避免爆炸。
+    """
+    if "编码" in reason or "codec" in reason.lower():
+        return "编码不匹配"
+    if "分辨率" in reason or "width" in reason.lower() or "height" in reason.lower():
+        return "分辨率不匹配"
+    if "帧率" in reason or "fps" in reason.lower():
+        return "帧率不匹配"
+    if "字幕" in reason or "ass" in reason.lower():
+        return "有字幕叠加"
+    if "像素格式" in reason or "pix_fmt" in reason.lower():
+        return "像素格式不匹配"
+    if "trim" in reason or "时长" in reason:
+        return "裁剪不支持"
+    if "多clip" in reason or "多片段" in reason or "转场" in reason:
+        return "多片段不支持"
+    return "其他"
@@ -728,6 +728,10 @@ class UnifiedRenderService:
                self.plan.id,
                reason,
            )
+            # 灰度观测：stream_copy 未命中
+            from video_processing.render_metrics import classify_stream_copy_miss_reason, record_stream_copy
+            miss_reason = classify_stream_copy_miss_reason(reason)
+            record_stream_copy("miss", miss_reason)
            return False

        # 构建 copy 命令
@@ -784,9 +788,15 @@ class UnifiedRenderService:
                    self.plan.id,
                    output_path.stat().st_size,
                )
+                # 灰度观测：stream_copy 命中成功
+                from video_processing.render_metrics import record_stream_copy
+                record_stream_copy("hit", "成功")
                return True
            else:
                logger.warning("[unified-render] stream_copy 输出为空: plan_id=%s", self.plan.id)
+                # 灰度观测：stream_copy 失败回退（输出为空）
+                from video_processing.render_metrics import record_stream_copy
+                record_stream_copy("fallback", "输出为空")
                return False
        except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
            logger.warning(
@@ -794,6 +804,9 @@ class UnifiedRenderService:
                self.plan.id,
                str(e)[:200],
            )
+            # 灰度观测：stream_copy 失败回退（ffmpeg错误）
+            from video_processing.render_metrics import record_stream_copy
+            record_stream_copy("fallback", "ffmpeg失败")
            # 清理可能的损坏输出文件
            if output_path.exists():
                try:
@@ -63,15 +63,30 @@ def compose_video(self, job_id: str, **kwargs):
        # 判断使用哪个渲染引擎
        # 优先级：Redis Feature Flag（白名单 > 百分比） > 环境变量默认
        from video_processing.render_engine_resolver import get_render_engine_resolver
+        from video_processing.render_metrics import render_task_metrics

        resolver = get_render_engine_resolver()
        user_id = job.created_by_user_id or None
        engine = resolver.get_engine(user_id=user_id)
+        # 灰度期间打印详细 flag 配置，便于排查
+        config = resolver.get_config_snapshot()
+        logger.info(
+            "compose_video 引擎选择: job_id=%s engine=%s user_id=%s enabled=%s percentage=%s whitelist=%d default=%s",
+            job_id,
+            engine,
+            user_id,
+            config.get("enabled"),
+            config.get("percentage"),
+            len(config.get("whitelist", [])),
+            config.get("default_engine"),
+        )

-        if engine == "unified":
-            return _compose_with_unified_engine(self, job_service, job, plan_id, db)
-        else:
-            return _compose_with_legacy_engine(self, job_service, job, plan_id, db)
+        # 灰度观测指标埋点
+        with render_task_metrics(engine=engine, task_type="compose_video"):
+            if engine == "unified":
+                return _compose_with_unified_engine(self, job_service, job, plan_id, db)
+            else:
+                return _compose_with_legacy_engine(self, job_service, job, plan_id, db)

    except self.retry_exc as exc:
        logger.warning("视频合成重试中: job_id=%s, exc=%s", job_id, exc)
@@ -0,0 +1 @@
+"""Packages root."""
@@ -0,0 +1 @@
+"""Adapters package for external implementations."""
@@ -1,6 +1,6 @@
 from datetime import datetime, timezone

-from sqlalchemy import JSON, Boolean, Column, DateTime, Float, Integer, String, Text, UniqueConstraint
+from sqlalchemy import JSON, Boolean, Column, DateTime, Float, Integer, String, Text, UniqueConstraint, create_engine
 from sqlalchemy.orm import declarative_base

 Base = declarative_base()
@@ -27,6 +27,7 @@ from .generated_videos import (
 from .generation_tasks import (
    CreateGenerationTaskCommand,
    CreateGenerationTaskUseCase,
+    GetGenerationTaskUseCase,
 )
 from .ingest_jobs import SubmitIngestJobCommand, SubmitIngestJobUseCase
 from .jobs import (
@@ -12,9 +12,10 @@ JWT 处理器委托层
    payload = jwt_handler.verify_access_token(token)
 """

+from datetime import datetime, timedelta
 from typing import Any, Dict, Optional

-from packages.application.auth.jwt_service import JWTConfig, JWTService
+from packages.application.auth.jwt_service import JWTConfig, JWTService, TokenType


 class JWTHandler:
@@ -208,10 +208,10 @@ def _get_jwt_service():
        kw = dict(secret_key=settings.JWT_SECRET_KEY)
        if hasattr(settings, "JWT_ALGORITHM"):
            kw["algorithm"] = settings.JWT_ALGORITHM
-        if hasattr(settings, "JWT_ACCESS_TOKEN_EXPIRE_MINUTES"):
-            kw["access_token_expire_minutes"] = settings.JWT_ACCESS_TOKEN_EXPIRE_MINUTES
-        if hasattr(settings, "JWT_REFRESH_TOKEN_EXPIRE_DAYS"):
-            kw["refresh_token_expire_days"] = settings.JWT_REFRESH_TOKEN_EXPIRE_DAYS
+        if hasattr(settings, "ACCESS_TOKEN_EXPIRE_MINUTES"):
+            kw["access_token_expire_minutes"] = settings.ACCESS_TOKEN_EXPIRE_MINUTES
+        if hasattr(settings, "REFRESH_TOKEN_EXPIRE_DAYS"):
+            kw["refresh_token_expire_days"] = settings.REFRESH_TOKEN_EXPIRE_DAYS
        _jwt_service_instance = JWTService(JWTConfig(**kw))
    return _jwt_service_instance

@@ -293,7 +293,7 @@ class LogoutUseCase:
        try:
            if request.logout_all_devices:
                # 删除所有设备的 session
-                self.session_store.delete_all_user_sessions(request.user_id)
+                count = self.session_store.delete_all_user_sessions(request.user_id)
                return True, None
            else:
                # 删除当前 session
@@ -85,6 +85,8 @@ class PasswordHasher:
            True 如果需要重新哈希
        """
        try:
+            hashed_bytes = hashed_password.encode("utf-8")
+            current_rounds = bcrypt.getsalt(hashed_bytes)

            # 提取当前的 cost factor
            # bcrypt hash 格式: $2b$rounds$salt+hash
@@ -3,7 +3,7 @@
 """

 import secrets
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from typing import Optional
 from uuid import uuid4

@@ -3,7 +3,7 @@
 """

 from math import ceil
-from typing import Generic, List, TypeVar
+from typing import Generic, List, Optional, TypeVar

 from pydantic import BaseModel, Field

@@ -7,7 +7,9 @@ from __future__ import annotations

 import logging
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from typing import Any
+from uuid import uuid4

 from packages.domain.job import Job, JobStatus, JobType
 from packages.ports.job_repository import JobRepository
@@ -9,6 +9,7 @@ from typing import List, Optional
 from packages.adapters.sqlalchemy_impl.recipe_repository import SQLAlchemyRecipeRepository
 from packages.application.recipe.commands import (
    CreateRecipeCommand,
+    RecipeItemCommand,
    UpdateRecipeCommand,
 )
 from packages.domain.recipe import Recipe, RecipeItem
@@ -0,0 +1 @@
+"""TTS Job application layer."""
@@ -148,6 +148,7 @@ class TTSStreamingService:

        # 并发合成所有分段，按顺序流式推送
        queue: asyncio.Queue[tuple[int, Optional[bytes], Optional[str]]] = asyncio.Queue()
+        completed_count = 0

        async def _synthesize_one(idx: int, seg_text: str) -> None:
            """合成单个分段并放入队列。"""
@@ -24,7 +24,7 @@ from packages.application.cosyvoice_service import (
    CosyVoiceError,
    CosyVoiceService,
 )
-from packages.application.tts_job.audio_merger import AudioMerger
+from packages.application.tts_job.audio_merger import AudioMergeError, AudioMerger
 from packages.application.tts_job.text_splitter import split_text
 from packages.domain.tts_job import TTSJob, TTSJobStatus
 from packages.ports.tts_job_repository import TTSJobRepository
@@ -2,6 +2,7 @@

 from __future__ import annotations

+import uuid
 from typing import List, Optional

 from packages.domain.voice_clone_profile import VoiceCloneProfile
@@ -10,7 +10,7 @@
 from __future__ import annotations

 import logging
-from typing import Optional
+from typing import Any, Optional

 from packages.application.cosyvoice_service import (
    CosyVoiceAuthError,
@@ -21,8 +21,9 @@ from packages.application.voice_clone.use_cases import (
    CreateVoiceCloneUseCase,
    RetryVoiceCloneUseCase,
    VoiceCloneNotFoundError,
+    VoiceCloneNotRetryableError,
 )
-from packages.domain.voice_clone_profile import VoiceCloneProfile
+from packages.domain.voice_clone_profile import VoiceCloneProfile, VoiceCloneStatus
 from packages.ports.voice_clone_profile_repository import VoiceCloneProfileRepository

 logger = logging.getLogger(__name__)
@@ -13,6 +13,7 @@ else:
        pass


+from typing import Any
 from uuid import uuid4


@@ -10,7 +10,7 @@ from __future__ import annotations

 import copy
 from enum import Enum
-from typing import Optional
+from typing import List, Optional

 from pydantic import BaseModel, Field

@@ -24,7 +24,7 @@ from __future__ import annotations

 import logging
 from dataclasses import dataclass, field
-from typing import Dict, Optional
+from typing import Any, Dict, Optional, Set

 logger = logging.getLogger(__name__)

@@ -14,7 +14,7 @@ from __future__ import annotations
 import logging
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional, Set

 logger = logging.getLogger(__name__)

@@ -2,7 +2,7 @@

 from abc import ABC, abstractmethod

-from packages.domain import AssetLibrary
+from packages.domain import AssetLibrary, AssetLibraryKind


 class AssetLibraryRepository(ABC):
@@ -247,4 +247,3 @@ def main() -> int:

 if __name__ == "__main__":
    sys.exit(main())
-
@@ -0,0 +1,195 @@
+"""渲染引擎灰度观测指标单元测试。"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+
+import pytest
+from prometheus_client import REGISTRY, CollectorRegistry, Counter, Gauge, Histogram
+
+
+@pytest.fixture(autouse=True)
+def _isolate_registry(monkeypatch):
+    """每个测试使用独立的 CollectorRegistry，避免互相影响。"""
+    from video_processing import render_metrics
+
+    test_registry = CollectorRegistry()
+
+    # 用测试 registry 重新创建所有指标
+    task_total = Counter(
+        "render_task_total",
+        "Total number of render tasks",
+        ["engine", "task_type", "status"],
+        registry=test_registry,
+    )
+    task_duration = Histogram(
+        "render_task_duration_seconds",
+        "Render task duration in seconds",
+        ["engine", "task_type"],
+        buckets=(1, 5, 10, 30, 60, 120, 300, 600, 900, 1800, 3600, 7200),
+        registry=test_registry,
+    )
+    error_total = Counter(
+        "render_error_total",
+        "Total number of render errors",
+        ["engine", "task_type", "error_type"],
+        registry=test_registry,
+    )
+    stream_copy_total = Counter(
+        "render_stream_copy_total",
+        "Total number of stream copy attempts and results",
+        ["result", "reason"],
+        registry=test_registry,
+    )
+    active_tasks = Gauge(
+        "render_active_tasks",
+        "Number of render tasks currently in progress",
+        ["engine", "task_type"],
+        registry=test_registry,
+    )
+
+    # 替换模块中的指标对象
+    monkeypatch.setattr(render_metrics, "RENDER_TASK_TOTAL", task_total)
+    monkeypatch.setattr(render_metrics, "RENDER_TASK_DURATION_SECONDS", task_duration)
+    monkeypatch.setattr(render_metrics, "RENDER_ERROR_TOTAL", error_total)
+    monkeypatch.setattr(render_metrics, "RENDER_STREAM_COPY_TOTAL", stream_copy_total)
+    monkeypatch.setattr(render_metrics, "RENDER_ACTIVE_TASKS", active_tasks)
+
+    yield test_registry
+
+
+def _counter_value(counter: Counter, **labels) -> float:
+    """获取 Counter 指定标签的当前值。"""
+    return counter.labels(**labels)._value.get()
+
+
+def _gauge_value(gauge: Gauge, **labels) -> float:
+    """获取 Gauge 指定标签的当前值。"""
+    return gauge.labels(**labels)._value.get()
+
+
+def _histogram_sum(histogram: Histogram, **labels) -> float:
+    """获取 Histogram 指定标签的观测总和。"""
+    return histogram.labels(**labels)._sum.get()
+
+
+def test_render_task_metrics_success():
+    """成功任务应记录 success 状态 + 耗时 + 活跃数正确增减。"""
+    from video_processing.render_metrics import (
+        RENDER_ACTIVE_TASKS,
+        RENDER_TASK_DURATION_SECONDS,
+        RENDER_TASK_TOTAL,
+        render_task_metrics,
+    )
+
+    assert _counter_value(RENDER_TASK_TOTAL, engine="unified", task_type="compose_video", status="success") == 0
+    assert _gauge_value(RENDER_ACTIVE_TASKS, engine="unified", task_type="compose_video") == 0
+
+    with render_task_metrics(engine="unified", task_type="compose_video"):
+        assert _gauge_value(RENDER_ACTIVE_TASKS, engine="unified", task_type="compose_video") == 1
+        time.sleep(0.01)
+
+    assert _gauge_value(RENDER_ACTIVE_TASKS, engine="unified", task_type="compose_video") == 0
+    assert _counter_value(RENDER_TASK_TOTAL, engine="unified", task_type="compose_video", status="success") == 1
+    assert _counter_value(RENDER_TASK_TOTAL, engine="unified", task_type="compose_video", status="failure") == 0
+    assert _histogram_sum(RENDER_TASK_DURATION_SECONDS, engine="unified", task_type="compose_video") > 0
+
+
+def test_render_task_metrics_failure():
+    """失败任务应记录 failure 状态 + 对应错误类型。"""
+    from video_processing.render_metrics import (
+        RENDER_ERROR_TOTAL,
+        RENDER_TASK_TOTAL,
+        render_task_metrics,
+    )
+
+    with pytest.raises(ValueError, match="test error"):
+        with render_task_metrics(engine="legacy", task_type="edit_plan"):
+            raise ValueError("test error")
+
+    assert _counter_value(RENDER_TASK_TOTAL, engine="legacy", task_type="edit_plan", status="failure") == 1
+    assert _counter_value(RENDER_TASK_TOTAL, engine="legacy", task_type="edit_plan", status="success") == 0
+    assert _counter_value(RENDER_ERROR_TOTAL, engine="legacy", task_type="edit_plan", error_type="validation") == 1
+
+
+def test_render_task_metrics_ffmpeg_error():
+    """FFmpeg 执行失败应分类为 ffmpeg_error。"""
+    from video_processing.render_metrics import RENDER_ERROR_TOTAL, render_task_metrics
+
+    with pytest.raises(subprocess.CalledProcessError):
+        with render_task_metrics(engine="unified", task_type="generate_video"):
+            raise subprocess.CalledProcessError(returncode=1, cmd=["ffmpeg"])
+
+    assert _counter_value(RENDER_ERROR_TOTAL, engine="unified", task_type="generate_video", error_type="ffmpeg_error") == 1
+
+
+def test_render_task_metrics_timeout():
+    """超时异常应分类为 timeout。"""
+    from video_processing.render_metrics import RENDER_ERROR_TOTAL, render_task_metrics
+
+    with pytest.raises(subprocess.TimeoutExpired):
+        with render_task_metrics(engine="unified", task_type="compose_video"):
+            raise subprocess.TimeoutExpired(cmd=["ffmpeg"], timeout=10)
+
+    assert _counter_value(RENDER_ERROR_TOTAL, engine="unified", task_type="compose_video", error_type="timeout") == 1
+
+
+def test_render_task_metrics_active_tasks_decrement_on_error():
+    """任务异常退出时，活跃任务数也应正确递减。"""
+    from video_processing.render_metrics import RENDER_ACTIVE_TASKS, render_task_metrics
+
+    assert _gauge_value(RENDER_ACTIVE_TASKS, engine="legacy", task_type="compose_video") == 0
+
+    with pytest.raises(RuntimeError):
+        with render_task_metrics(engine="legacy", task_type="compose_video"):
+            raise RuntimeError("boom")
+
+    assert _gauge_value(RENDER_ACTIVE_TASKS, engine="legacy", task_type="compose_video") == 0
+
+
+def test_record_stream_copy():
+    """stream_copy 命中/跳过/回退应分别计数。"""
+    from video_processing.render_metrics import RENDER_STREAM_COPY_TOTAL, record_stream_copy
+
+    assert _counter_value(RENDER_STREAM_COPY_TOTAL, result="hit", reason="成功") == 0
+    assert _counter_value(RENDER_STREAM_COPY_TOTAL, result="miss", reason="编码不匹配") == 0
+
+    record_stream_copy("hit", "成功")
+    record_stream_copy("hit", "成功")
+    record_stream_copy("miss", "编码不匹配")
+    record_stream_copy("fallback", "ffmpeg失败")
+
+    assert _counter_value(RENDER_STREAM_COPY_TOTAL, result="hit", reason="成功") == 2
+    assert _counter_value(RENDER_STREAM_COPY_TOTAL, result="miss", reason="编码不匹配") == 1
+    assert _counter_value(RENDER_STREAM_COPY_TOTAL, result="fallback", reason="ffmpeg失败") == 1
+
+
+def test_classify_error_unknown():
+    """未知异常应分类为 unknown。"""
+    from video_processing.render_metrics import _classify_error
+
+    assert _classify_error(RuntimeError("something")) == "unknown"
+
+
+def test_classify_error_io():
+    """IO 异常应分类为 io_error。"""
+    from video_processing.render_metrics import _classify_error
+
+    assert _classify_error(OSError("disk full")) == "io_error"
+
+
+def test_engine_and_task_type_labels():
+    """不同 engine 和 task_type 应独立计数。"""
+    from video_processing.render_metrics import RENDER_TASK_TOTAL, render_task_metrics
+
+    with render_task_metrics(engine="unified", task_type="compose_video"):
+        pass
+    with render_task_metrics(engine="legacy", task_type="compose_video"):
+        pass
+    with render_task_metrics(engine="unified", task_type="edit_plan"):
+        pass
+
+    assert _counter_value(RENDER_TASK_TOTAL, engine="unified", task_type="compose_video", status="success") == 1
+    assert _counter_value(RENDER_TASK_TOTAL, engine="legacy", task_type="compose_video", status="success") == 1
+    assert _counter_value(RENDER_TASK_TOTAL, engine="unified", task_type="edit_plan", status="success") == 1
				`@@ -0,0 +1 @@`
				`"""Adapters package for external implementations."""`