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
67 changed files with 1385 additions and 724 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,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 />,
+      },
+    ],
+  },
+];
@@ -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;
@@ -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
   ============================================================ */
@@ -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:
@@ -17,7 +17,6 @@ class WorkerSettings(BaseSettings):
    database_pool_recycle: int = 3600
    environment: str = "development"
    auto_create_schema: bool = False
-    redis_url: str = "redis://redis:6379/0"

    # 渲染引擎选择：legacy=旧VideoComposeService，unified=新UnifiedRenderService
    render_engine: str = "legacy"
@@ -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())
-
@@ -1,256 +0,0 @@
-#!/bin/sh
-# ============================================================
-# Production 部署脚本 - Registry 拉取方式
-# ============================================================
-# 原始位置：原内嵌在 .gitea/workflows/ci-cd.yml 的 deploy-production Job 中
-# 以 base64 编码存储在 DEPLOY_B64 变量中，通过 SSH 管道传送到服务器执行
-#
-# 功能：
-#   1. 登录 Gitea Registry
-#   2. Pull api / worker / web 三个镜像
-#   3. 备份旧前端静态资源（兼容 CDN 缓存，防止 404）
-#   4. 检查基础设施容器（PostgreSQL / Redis）
-#   5. 执行数据库 Migration
-#   6. 停止并重新启动三个业务容器
-#   7. 健康检查等待就绪
-#   8. 清理旧镜像
-#
-# 依赖的环境变量（由 CI 通过 SSH 传入）：
-#   IMAGE_TAG       - 镜像版本标签（如 v0.1.127，对应 git tag）
-#   REGISTRY_TOKEN  - Gitea Registry 访问令牌
-# ============================================================
-
-set -eu
-
-IMAGE_TAG="${IMAGE_TAG:-}"
-REGISTRY="${REGISTRY:-git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas}"
-REGISTRY_USER="${REGISTRY_USER:-xiaoxia}"
-REGISTRY_TOKEN="${REGISTRY_TOKEN:-}"
-
-ENV_FILE="${ENV_FILE:-/var/lib/xiaoxia-saas-production/.env}"
-GENERATED_DIR="${GENERATED_DIR:-/var/lib/xiaoxia-saas-production/generated}"
-LEGACY_ASSETS_DIR="${LEGACY_ASSETS_DIR:-/var/lib/xiaoxia-saas-production/legacy-assets}"
-
-if [ -z "$IMAGE_TAG" ]; then
-  echo "ERROR: IMAGE_TAG is required"
-  exit 1
-fi
-
-test -f "$ENV_FILE"
-mkdir -p "$GENERATED_DIR"
-mkdir -p "$LEGACY_ASSETS_DIR"
-
-# ---- 登录 Registry ----
-if [ -n "$REGISTRY_TOKEN" ]; then
-  echo "Logging in to registry: $REGISTRY"
-  REGISTRY_HOST=$(echo "$REGISTRY" | cut -d/ -f1)
-  printf %s "$REGISTRY_TOKEN" | docker login "$REGISTRY_HOST" -u "$REGISTRY_USER" --password-stdin 2>/dev/null || {
-    echo "WARN: docker login failed, will try to pull anyway"
-  }
-fi
-
-# ---- Pull 三个镜像 ----
-REGISTRY_API="${REGISTRY}/xiaoxia-saas-api:${IMAGE_TAG}"
-REGISTRY_WORKER="${REGISTRY}/xiaoxia-saas-worker:${IMAGE_TAG}"
-REGISTRY_WEB="${REGISTRY}/xiaoxia-saas-web:${IMAGE_TAG}"
-
-LOCAL_API="xiaoxia-saas-api:${IMAGE_TAG}"
-LOCAL_WORKER="xiaoxia-saas-worker:${IMAGE_TAG}"
-LOCAL_WEB="xiaoxia-saas-web:${IMAGE_TAG}"
-
-echo "Pulling API image..."
-docker pull "$REGISTRY_API"
-echo "Pulling Worker image..."
-docker pull "$REGISTRY_WORKER"
-echo "Pulling Web image..."
-docker pull "$REGISTRY_WEB"
-
-# ---- Re-tag 成本地镜像名 ----
-docker tag "$REGISTRY_API" "$LOCAL_API"
-docker tag "$REGISTRY_WORKER" "$LOCAL_WORKER"
-docker tag "$REGISTRY_WEB" "$LOCAL_WEB"
-echo "All images pulled and tagged."
-
-# ---- 备份旧前端 assets（生产环境访问量大，防止 CDN 缓存命中 404） ----
-echo "Backing up legacy assets from current web container..."
-if docker inspect xiaoxia-web-production >/dev/null 2>&1; then
-  _tmpdir="/tmp/legacy-assets-$$"
-  rm -rf "$_tmpdir"
-  mkdir -p "$_tmpdir"
-  docker cp xiaoxia-web-production:/usr/share/nginx/html/assets/. "$_tmpdir/" 2>/dev/null || true
-  # 复制到 LEGACY_ASSETS_DIR（下一次部署时作为 fallback 挂载）
-  if [ -d "$_tmpdir" ] && [ "$(ls -A "$_tmpdir" 2>/dev/null)" ]; then
-    cp -an "$_tmpdir"/. "$LEGACY_ASSETS_DIR"/ 2>/dev/null || true
-    echo "Legacy assets backed up: $(ls "$_tmpdir" | wc -l) files"
-  fi
-  rm -rf "$_tmpdir"
-else
-  echo "No existing web container, skipping legacy assets backup"
-fi
-
-# 清理超过 7 天的旧 assets 文件
-if [ -d "$LEGACY_ASSETS_DIR" ]; then
-  find "$LEGACY_ASSETS_DIR" -type f -mtime +7 -delete 2>/dev/null || true
-  echo "Legacy assets cleanup done (retain 7 days)"
-fi
-
-# ---- 检查基础设施容器状态 ----
-echo "Checking infrastructure containers..."
-for c in xiaoxia-postgres-production xiaoxia-redis-production; do
-  if ! docker inspect "$c" >/dev/null 2>&1; then
-    echo "ERROR: Required container not found: $c"
-    exit 1
-  fi
-  state=$(docker inspect -f '{{.State.Status}}' "$c")
-  if [ "$state" != "running" ]; then
-    echo "ERROR: Container not running: $c ($state)"
-    exit 1
-  fi
-done
-
-# ---- 创建生产网络 ----
-docker network create xiaoxia-net-production 2>/dev/null || true
-
-# ---- 执行数据库 Migration ----
-echo "Running database migrations..."
-docker run --rm \
-  --env-file "$ENV_FILE" \
-  --network xiaoxia-net-production \
-  -e APP_ENV=production \
-  "$LOCAL_API" sh -c "cd /app && alembic upgrade head"
-echo "Migrations completed."
-
-# ---- 停止旧容器 ----
-echo "Stopping old containers..."
-docker rm -f xiaoxia-api-production 2>/dev/null || true
-docker rm -f xiaoxia-worker-production 2>/dev/null || true
-docker rm -f xiaoxia-web-production 2>/dev/null || true
-
-# ---- 启动参数（日志配置统一） ----
-LOG_OPTS="--log-driver json-file --log-opt max-size=50m --log-opt max-file=3"
-
-# ---- 启动 API 容器 ----
-echo "Starting API container..."
-docker run -d \
-  --name xiaoxia-api-production \
-  --env-file "$ENV_FILE" \
-  --network xiaoxia-net-production \
-  -p 127.0.0.1:8001:8000 \
-  -e APP_ENV=production \
-  -e APP_VERSION="$IMAGE_TAG" \
-  -e GENERATED_FILES_DIR=/app/generated \
-  -e GENERATED_FILES_URL_PREFIX=/generated-files \
-  -e PUBLIC_API_BASE_URL=https://api.xiaoxiajianji.com \
-  -v "$GENERATED_DIR:/app/generated" \
-  --restart unless-stopped \
-  --cpus 2 \
-  --memory 2g \
-  --health-cmd "python3 -c \"import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=5)\"" \
-  --health-interval 30s \
-  --health-timeout 10s \
-  --health-retries 3 \
-  --health-start-period 40s \
-  $LOG_OPTS \
-  "$LOCAL_API"
-
-# ---- 启动 Worker 容器 ----
-echo "Starting Worker container..."
-docker run -d \
-  --name xiaoxia-worker-production \
-  --env-file "$ENV_FILE" \
-  --network xiaoxia-net-production \
-  -e APP_ENV=production \
-  -e APP_VERSION="$IMAGE_TAG" \
-  -e WORKER_CONCURRENCY=1 \
-  -e WORKER_MAX_TASKS_PER_CHILD=100 \
-  -e GENERATED_FILES_DIR=/app/generated \
-  -e GENERATED_FILES_URL_PREFIX=/generated-files \
-  -e PUBLIC_API_BASE_URL=https://api.xiaoxiajianji.com \
-  -v "$GENERATED_DIR:/app/generated" \
-  --restart unless-stopped \
-  --cpus 2 \
-  --memory 2g \
-  --health-cmd "sh -c \"grep -q celery /proc/1/cmdline || exit 1\"" \
-  --health-interval 30s \
-  --health-timeout 10s \
-  --health-retries 3 \
-  --health-start-period 30s \
-  $LOG_OPTS \
-  "$LOCAL_WORKER"
-
-# ---- 启动 Web 容器 ----
-# Legacy assets 挂载到 /usr/share/nginx/html/assets-legacy/assets/
-# nginx 配置中 assets location 有 fallback 规则
-LEGACY_VOLUME=""
-if [ -d "$LEGACY_ASSETS_DIR" ] && [ "$(ls -A "$LEGACY_ASSETS_DIR" 2>/dev/null)" ]; then
-  LEGACY_VOLUME="-v ${LEGACY_ASSETS_DIR}:/usr/share/nginx/html/assets-legacy/assets:ro"
-  echo "Web container: legacy assets mounted (fallback)"
-else
-  echo "Web container: no legacy assets to mount"
-fi
-
-echo "Starting Web container..."
-docker run -d \
-  --name xiaoxia-web-production \
-  --network xiaoxia-net-production \
-  -p 127.0.0.1:3002:80 \
-  --restart unless-stopped \
-  --cpus 0.5 \
-  --memory 512m \
-  $LEGACY_VOLUME \
-  --health-cmd "wget --spider -q http://127.0.0.1:80" \
-  --health-interval 30s \
-  --health-timeout 5s \
-  --health-retries 3 \
-  $LOG_OPTS \
-  "$LOCAL_WEB"
-
-# ---- 等待 API 就绪 ----
-echo "Waiting for API to become healthy..."
-i=0
-while [ "$i" -lt 40 ]; do
-  if curl -sf --max-time 5 http://127.0.0.1:8001/health >/dev/null 2>&1; then
-    echo "API is healthy!"
-    break
-  fi
-  i=$((i + 1))
-  echo "  Waiting... ($i/40)"
-  sleep 3
-done
-
-if [ "$i" -ge 40 ]; then
-  echo "ERROR: API did not become healthy within 120s"
-  docker logs --tail 50 xiaoxia-api-production
-  exit 1
-fi
-
-# ---- 等待 Web 就绪 ----
-echo "Waiting for Web to become healthy..."
-i=0
-while [ "$i" -lt 15 ]; do
-  if curl -sf --max-time 5 http://127.0.0.1:3002/ >/dev/null 2>&1; then
-    echo "Web is healthy!"
-    break
-  fi
-  i=$((i + 1))
-  echo "  Waiting... ($i/15)"
-  sleep 2
-done
-
-if [ "$i" -ge 15 ]; then
-  echo "ERROR: Web did not become healthy within 30s"
-  docker logs --tail 30 xiaoxia-web-production
-  exit 1
-fi
-
-# ---- 清理旧镜像 ----
-echo "Cleaning up old images..."
-docker image prune -af --filter "until=168h" 2>/dev/null || true
-docker builder prune -af --filter "until=168h" 2>/dev/null || true
-
-echo ""
-echo "=== Production deployment complete ==="
-echo "API:      http://127.0.0.1:8001"
-echo "Web:      http://127.0.0.1:3002"
-echo "Version:  $IMAGE_TAG"
-docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep production
@@ -1,219 +0,0 @@
-#!/bin/sh
-# ============================================================
-# Staging 部署脚本 - Registry 拉取方式（替代 Watchtower）
-# ============================================================
-# 说明：原 Staging 使用 Watchtower 轮询 :staging 标签自动更新
-# 本脚本替代 Watchtower，由 CI 主动触发部署，优势：
-#   - 部署时机精确可控，无需固定 sleep 等待
-#   - 部署完成立即健康检查，失败可快速回滚
-#   - 部署日志完整记录在 CI 中
-#
-# 功能：
-#   1. 登录 Gitea Registry
-#   2. Pull api / worker / web 三个镜像（用 commit SHA 作为 tag）
-#   3. 执行数据库 Migration
-#   4. 停止并重新启动三个业务容器
-#   5. 健康检查等待就绪
-#
-# 依赖的环境变量（由 CI 通过 SSH 传入）：
-#   IMAGE_TAG       - 镜像标签（一般为 commit SHA）
-#   REGISTRY_TOKEN  - Gitea Registry 访问令牌
-# ============================================================
-
-set -eu
-
-IMAGE_TAG="${IMAGE_TAG:-}"
-REGISTRY="${REGISTRY:-git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas}"
-REGISTRY_USER="${REGISTRY_USER:-xiaoxia}"
-REGISTRY_TOKEN="${REGISTRY_TOKEN:-}"
-
-ENV_FILE="${ENV_FILE:-/var/lib/xiaoxia-saas-staging/.env}"
-GENERATED_DIR="${GENERATED_DIR:-/var/lib/xiaoxia-saas-staging/generated}"
-
-if [ -z "$IMAGE_TAG" ]; then
-  echo "ERROR: IMAGE_TAG is required"
-  exit 1
-fi
-
-test -f "$ENV_FILE"
-mkdir -p "$GENERATED_DIR"
-
-# ---- 登录 Registry ----
-if [ -n "$REGISTRY_TOKEN" ]; then
-  echo "Logging in to registry: $REGISTRY"
-  REGISTRY_HOST=$(echo "$REGISTRY" | cut -d/ -f1)
-  printf %s "$REGISTRY_TOKEN" | docker login "$REGISTRY_HOST" -u "$REGISTRY_USER" --password-stdin 2>/dev/null || {
-    echo "WARN: docker login failed, will try to pull anyway"
-  }
-fi
-
-# ---- Pull 三个镜像 ----
-REGISTRY_API="${REGISTRY}/xiaoxia-saas-api:${IMAGE_TAG}"
-REGISTRY_WORKER="${REGISTRY}/xiaoxia-saas-worker:${IMAGE_TAG}"
-REGISTRY_WEB="${REGISTRY}/xiaoxia-saas-web:${IMAGE_TAG}"
-
-LOCAL_API="xiaoxia-saas-api:staging-${IMAGE_TAG}"
-LOCAL_WORKER="xiaoxia-saas-worker:staging-${IMAGE_TAG}"
-LOCAL_WEB="xiaoxia-saas-web:staging-${IMAGE_TAG}"
-
-echo "Pulling API image..."
-docker pull "$REGISTRY_API"
-echo "Pulling Worker image..."
-docker pull "$REGISTRY_WORKER"
-echo "Pulling Web image..."
-docker pull "$REGISTRY_WEB"
-
-# ---- Re-tag 成本地镜像名 ----
-docker tag "$REGISTRY_API" "$LOCAL_API"
-docker tag "$REGISTRY_WORKER" "$LOCAL_WORKER"
-docker tag "$REGISTRY_WEB" "$LOCAL_WEB"
-echo "All images pulled and tagged."
-
-# ---- 检查基础设施容器 ----
-echo "Checking infrastructure containers..."
-for c in xiaoxia-postgres-staging xiaoxia-redis-staging; do
-  if ! docker inspect "$c" >/dev/null 2>&1; then
-    echo "ERROR: Required container not found: $c"
-    exit 1
-  fi
-  state=$(docker inspect -f '{{.State.Status}}' "$c")
-  if [ "$state" != "running" ]; then
-    echo "ERROR: Container not running: $c ($state)"
-    exit 1
-  fi
-done
-
-# ---- 创建 Staging 网络 ----
-docker network create xiaoxia-net-staging 2>/dev/null || true
-
-# ---- 执行数据库 Migration ----
-echo "Running database migrations..."
-docker run --rm \
-  --env-file "$ENV_FILE" \
-  --network xiaoxia-net-staging \
-  -e APP_ENV=staging \
-  "$LOCAL_API" sh -c "cd /app && alembic upgrade head"
-echo "Migrations completed."
-
-# ---- 停止旧容器 ----
-echo "Stopping old containers..."
-docker rm -f xiaoxia-api-staging 2>/dev/null || true
-docker rm -f xiaoxia-worker-staging 2>/dev/null || true
-docker rm -f xiaoxia-web-staging 2>/dev/null || true
-
-# ---- 启动参数（日志配置统一） ----
-LOG_OPTS="--log-driver json-file --log-opt max-size=50m --log-opt max-file=3"
-
-# ---- 启动 API 容器 ----
-echo "Starting API container..."
-docker run -d \
-  --name xiaoxia-api-staging \
-  --env-file "$ENV_FILE" \
-  --network xiaoxia-net-staging \
-  -p 127.0.0.1:8000:8000 \
-  -e APP_ENV=staging \
-  -e APP_VERSION="$IMAGE_TAG" \
-  -e GENERATED_FILES_DIR=/app/generated \
-  -e GENERATED_FILES_URL_PREFIX=/generated-files \
-  -e PUBLIC_API_BASE_URL=https://staging-api.xiaoxiajianji.com \
-  -v "$GENERATED_DIR:/app/generated" \
-  --restart unless-stopped \
-  --cpus 1 \
-  --memory 1g \
-  --health-cmd "python3 -c \"import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=5)\"" \
-  --health-interval 30s \
-  --health-timeout 10s \
-  --health-retries 3 \
-  --health-start-period 30s \
-  $LOG_OPTS \
-  "$LOCAL_API"
-
-# ---- 启动 Worker 容器 ----
-echo "Starting Worker container..."
-docker run -d \
-  --name xiaoxia-worker-staging \
-  --env-file "$ENV_FILE" \
-  --network xiaoxia-net-staging \
-  -e APP_ENV=staging \
-  -e APP_VERSION="$IMAGE_TAG" \
-  -e WORKER_CONCURRENCY=1 \
-  -e WORKER_MAX_TASKS_PER_CHILD=100 \
-  -e GENERATED_FILES_DIR=/app/generated \
-  -e GENERATED_FILES_URL_PREFIX=/generated-files \
-  -e PUBLIC_API_BASE_URL=https://staging-api.xiaoxiajianji.com \
-  -v "$GENERATED_DIR:/app/generated" \
-  --restart unless-stopped \
-  --cpus 1 \
-  --memory 1g \
-  --health-cmd "sh -c \"grep -q celery /proc/1/cmdline || exit 1\"" \
-  --health-interval 30s \
-  --health-timeout 10s \
-  --health-retries 3 \
-  --health-start-period 30s \
-  $LOG_OPTS \
-  "$LOCAL_WORKER"
-
-# ---- 启动 Web 容器 ----
-echo "Starting Web container..."
-docker run -d \
-  --name xiaoxia-web-staging \
-  --network xiaoxia-net-staging \
-  -p 127.0.0.1:3001:80 \
-  --restart unless-stopped \
-  --cpus 0.5 \
-  --memory 256m \
-  --health-cmd "wget --spider -q http://127.0.0.1:80" \
-  --health-interval 30s \
-  --health-timeout 5s \
-  --health-retries 3 \
-  $LOG_OPTS \
-  "$LOCAL_WEB"
-
-# ---- 等待 API 就绪 ----
-echo "Waiting for API to become healthy..."
-i=0
-while [ "$i" -lt 30 ]; do
-  if curl -sf --max-time 5 http://127.0.0.1:8000/health >/dev/null 2>&1; then
-    echo "API is healthy!"
-    break
-  fi
-  i=$((i + 1))
-  echo "  Waiting... ($i/30)"
-  sleep 2
-done
-
-if [ "$i" -ge 30 ]; then
-  echo "ERROR: API did not become healthy within 60s"
-  docker logs --tail 50 xiaoxia-api-staging
-  exit 1
-fi
-
-# ---- 等待 Web 就绪 ----
-echo "Waiting for Web to become healthy..."
-i=0
-while [ "$i" -lt 15 ]; do
-  if curl -sf --max-time 5 http://127.0.0.1:3001/ >/dev/null 2>&1; then
-    echo "Web is healthy!"
-    break
-  fi
-  i=$((i + 1))
-  echo "  Waiting... ($i/15)"
-  sleep 2
-done
-
-if [ "$i" -ge 15 ]; then
-  echo "ERROR: Web did not become healthy within 30s"
-  docker logs --tail 30 xiaoxia-web-staging
-  exit 1
-fi
-
-# ---- 清理旧镜像 ----
-echo "Cleaning up old images..."
-docker image prune -af --filter "until=72h" 2>/dev/null || true
-
-echo ""
-echo "=== Staging deployment complete ==="
-echo "API:      http://127.0.0.1:8000"
-echo "Web:      http://127.0.0.1:3001"
-echo "Version:  $IMAGE_TAG"
-docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" | grep staging
@@ -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."""`