test(wave100): 40 unit tests for 3 application layer modules (milestone)

Milestone wave #100 — cleaning up zero-test application modules:
- generated_videos.py: 8 UseCases fully covered (25 tests)
  - ListGeneratedVideosUseCase: 4 tests
  - ListGeneratedVideosPaginatedUseCase: 7 tests (page clamp / page_size clamp / filters)
  - GetGeneratedVideoUseCase: 2 tests
  - ListGeneratedVideosByTaskUseCase: 3 tests
  - GetGeneratedVideoDownloadUrlUseCase: 2 tests
  - UpdateVideoReviewStatusUseCase: 7 tests (3 valid statuses + validation)
  - GetVideosByIdsUseCase: 2 tests
- assets.py: 6 tests (CreateAssetCommand + ListAssets + CreateAsset)
- asset_libraries.py: 5 tests (Command + List + Create)
Total: 40 tests across 3 modules

apps/api/app/services/plan_generator_service.py

@@ -206,4 +206,3 @@ class PlanGeneratorService:
         委托给 plan_generator_utils.distribute_assets 纯函数。
         """
         distribute_assets(clips, asset_ids, editing_mode)
-

apps/api/app/services/smart_asset_selector.py

@@ -21,14 +21,14 @@ from __future__ import annotations
 
 import logging
 
+from packages.domain.asset_scoring import MEDIUM_BUCKET_MAX as _MEDIUM_BUCKET_MAX
+from packages.domain.asset_scoring import MIN_QUALITY_SCORE as _MIN_QUALITY_SCORE
+from packages.domain.asset_scoring import OPTIMAL_DURATION_MAX as _OPTIMAL_DURATION_MAX
+from packages.domain.asset_scoring import OPTIMAL_DURATION_MIN as _OPTIMAL_DURATION_MIN
+from packages.domain.asset_scoring import SHORT_BUCKET_MAX as _SHORT_BUCKET_MAX
+from packages.domain.asset_scoring import TARGET_HEIGHT as _TARGET_HEIGHT
+from packages.domain.asset_scoring import TARGET_WIDTH as _TARGET_WIDTH
 from packages.domain.asset_scoring import (
-    MEDIUM_BUCKET_MAX as _MEDIUM_BUCKET_MAX,
-    MIN_QUALITY_SCORE as _MIN_QUALITY_SCORE,
-    OPTIMAL_DURATION_MAX as _OPTIMAL_DURATION_MAX,
-    OPTIMAL_DURATION_MIN as _OPTIMAL_DURATION_MIN,
-    SHORT_BUCKET_MAX as _SHORT_BUCKET_MAX,
-    TARGET_HEIGHT as _TARGET_HEIGHT,
-    TARGET_WIDTH as _TARGET_WIDTH,
     AssetScoreDetail,
     SmartSelectResult,
     diverse_selection,

apps/api/app/services/video_compose_service.py

@@ -29,33 +29,47 @@ from packages.adapters.sqlalchemy_impl.edit_plan_repository import (
 )
 from packages.domain.edit_plan import EditPlanStatus
 from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
-from packages.domain.video_filter_builder import (
-    DEFAULT_FPS,
-    DEFAULT_OUTPUT_HEIGHT,
-    DEFAULT_OUTPUT_WIDTH,
-    DEFAULT_TRANSITION_DURATION,
-    ClipFilterChain,
-    build_clip_filter,
-    build_concat_filter as _build_concat_filter_func,
-    build_filter_complex as _build_filter_complex,
-    build_xfade_filter as _build_xfade_filter_func,
-    chain_filters as _chain_filters_func,
-    has_audio as _has_audio_func,
-)
+from packages.domain.template_clip_config import TransitionEffect
 
 logger = logging.getLogger(__name__)
 
-# ── 常量（向后兼容别名） ──────────────────────────────────────────────────────
-# 实际定义已迁移至 packages/domain/video_filter_builder.py
+# ── 常量 ──────────────────────────────────────────────────────────────────────
 
+DEFAULT_OUTPUT_WIDTH = 1280
+DEFAULT_OUTPUT_HEIGHT = 720
+DEFAULT_FPS = 25
 DEFAULT_CODEC = "libx264"
 DEFAULT_CRF = 23
 DEFAULT_PRESET = "medium"
 
+# xfade 转场映射：TransitionEffect → FFmpeg xfade transition 名称
+_XFADE_TRANSITION_MAP: dict[str, str] = {
+    TransitionEffect.FADE: "fade",
+    TransitionEffect.SLIDE_LEFT: "slideleft",
+    TransitionEffect.SLIDE_RIGHT: "slideright",
+    TransitionEffect.DISSOLVE: "dissolve",
+    TransitionEffect.WIPE: "wipeleft",
+}
+
+# 转场默认时长（秒）
+DEFAULT_TRANSITION_DURATION = 0.5
+
 
 # ── 数据结构 ──────────────────────────────────────────────────────────────────
 
 
+@dataclass(frozen=True)
+class ClipFilterChain:
+    """单个片段的滤镜链描述。"""
+
+    clip_id: str
+    input_index: int
+    video_label: str
+    audio_label: str | None
+    filters: list[str]
+    duration: float
+
+
 @dataclass(frozen=True)
 class ComposeCommand:
     """完整的 FFmpeg 合成命令描述。"""
@@ -387,8 +401,62 @@ class VideoComposeService:
         output_height: int,
         fps: int,
     ) -> ClipFilterChain:
-        """向后兼容：委托给 video_filter_builder.build_clip_filter。"""
-        return build_clip_filter(clip, input_index, output_width, output_height, fps)
+        """为单个片段构建滤镜链。
+
+        滤镜顺序：
+        1. scale — 等比缩放到目标分辨率（保证覆盖）
+        2. crop — 居中裁剪到目标分辨率
+        3. fps — 统一输出帧率（concat 要求所有输入帧率一致）
+        4. setpts — 重置时间戳 + 偏移
+        5. trim — 视频时长裁剪
+        6. atrim — 音频时长裁剪（如有音频流）
+        """
+        duration = clip.duration if clip.duration > 0 else 5.0  # 默认 5 秒
+        start = clip.start_time
+
+        filters: list[str] = []
+
+        # 1. scale: 等比缩放（保持比例，不裁剪）
+        filters.append(f"scale={output_width}:{output_height}" f":force_original_aspect_ratio=decrease")
+
+        # 2. pad: 居中+留黑边到目标分辨率（保持原始比例，不裁剪内容）
+        filters.append(f"pad={output_width}:{output_height}:(ow-iw)/2:(oh-ih)/2:black")
+
+        # 3. format: 统一像素格式为 yuv420p（H.264 标准格式，concat 要求所有输入像素格式一致）
+        # 不同素材可能是 yuv420p / yuv422p / yuv444p / nv12 等，必须统一
+        filters.append("format=yuv420p")
+
+        # 4. fps: 统一帧率（concat 要求所有输入帧率一致）
+        # 放在 pad 之后、setpts 之前，确保分辨率和帧率都已统一
+        if fps and fps > 0:
+            filters.append(f"fps={fps}")
+
+        # 3. setpts: 重置时间戳
+        if start > 0:
+            filters.append(f"setpts=PTS-STARTPTS+{start}/TB")
+        else:
+            filters.append("setpts=PTS-STARTPTS")
+
+        # 4. trim: 视频时长
+        filters.append(f"trim=0:{duration}")
+        filters.append("setpts=PTS-STARTPTS")  # trim 后需要重置 PTS
+
+        video_label = f"v{input_index}"
+
+        # 5. 音频标签：仅当片段类型可能有音频时才设置
+        # title/subtitle 是纯文字/图片卡片，没有音频流
+        clip_type = clip.clip_type.lower() if clip.clip_type else ""
+        has_audio_stream = clip_type not in ("title", "subtitle")
+        audio_label = f"a{input_index}" if has_audio_stream else None
+
+        return ClipFilterChain(
+            clip_id=clip.id,
+            input_index=input_index,
+            video_label=video_label,
+            audio_label=audio_label,
+            filters=filters,
+            duration=duration,
+        )
 
     @staticmethod
     def _build_filter_complex(
@@ -398,30 +466,102 @@ class VideoComposeService:
         transition_duration: float,
         transitions: list[str],
     ) -> tuple[str, float]:
-        """向后兼容：委托给 video_filter_builder.build_filter_complex。"""
-        return _build_filter_complex(clip_chains, output_width, output_height, transition_duration, transitions)
+        """构建完整的 filter_complex 字符串。
+
+        策略：
+        - 单片段：直接输出
+        - 多片段 + 全 cut：使用 concat 滤镜（高效）
+        - 多片段 + 有转场：使用 xfade 滤镜链
+
+        返回 (filter_complex_string, estimated_total_duration)。
+        """
+        n = len(clip_chains)
+
+        if n == 0:
+            return "", 0.0
+
+        # ── 单片段 ─────────────────────────────────────────────────────
+        if n == 1:
+            chain = clip_chains[0]
+            filter_str = _chain_filters(chain.filters, chain.video_label)
+            # 音频
+            if chain.audio_label:
+                filter_str += f";[0:a]{chain.audio_label}"
+            total_duration = chain.duration
+            return filter_str, total_duration
+
+        # ── 检查是否有转场 ─────────────────────────────────────────────
+        has_transitions = any(t != TransitionEffect.CUT and t != "cut" for t in transitions)
+
+        if not has_transitions:
+            return _build_concat_filter(clip_chains)
+
+        # ── 有转场：使用 xfade ─────────────────────────────────────────
+        return _build_xfade_filter(
+            clip_chains=clip_chains,
+            transition_duration=transition_duration,
+            transitions=transitions,
+        )
 
     @staticmethod
     def _has_audio(clip_chains: list[ClipFilterChain]) -> bool:
-        """向后兼容：委托给 video_filter_builder.has_audio。"""
-        return _has_audio_func(clip_chains)
+        """是否有任何片段包含音频流。"""
+        return any(c.audio_label is not None for c in clip_chains)
 
 
-# ── 模块级辅助函数（向后兼容别名） ──────────────────────────────────────────
-# 实际实现已迁移至 packages/domain/video_filter_builder.py
-# 保留此处别名以兼容现有测试与调用方
+# ── 模块级辅助函数 ────────────────────────────────────────────────────────────
 
 
 def _chain_filters(filters: list[str], output_label: str) -> str:
-    """向后兼容：委托给 video_filter_builder.chain_filters。"""
-    return _chain_filters_func(filters, output_label)
+    """将滤镜列表串联为 FFmpeg 滤镜字符串。"""
+    filter_body = ",".join(filters)
+    return f"[0:v]{filter_body}[{output_label}]"
 
 
 def _build_concat_filter(
     clip_chains: list[ClipFilterChain],
 ) -> tuple[str, float]:
-    """向后兼容：委托给 video_filter_builder.build_concat_filter。"""
-    return _build_concat_filter_func(clip_chains)
+    """构建 concat 滤镜（无转场，高效拼接）。
+
+    格式：
+    [0:v]filters[v0]; [1:v]filters[v1]; ...
+    [v0][v1]...[vN]concat=n=N:v=1:a=0[outv]
+    """
+    n = len(clip_chains)
+    parts: list[str] = []
+    total_duration = 0.0
+
+    # 每个片段的滤镜链
+    for idx, chain in enumerate(clip_chains):
+        filter_body = ",".join(chain.filters)
+        parts.append(f"[{idx}:v]{filter_body}[{chain.video_label}]")
+        total_duration += chain.duration
+
+    # concat 滤镜
+    concat_inputs = "".join(f"[{c.video_label}]" for c in clip_chains)
+    concat_filter = f"{concat_inputs}concat=n={n}:v=1:a=0[outv]"
+    parts.append(concat_filter)
+
+    # 音频 concat（如果有）— 先统一音频格式再拼接，否则不同采样率/声道会导致concat失败
+    audio_parts: list[str] = []
+    for idx, chain in enumerate(clip_chains):
+        if chain.audio_label:
+            # aformat: 统一采样率48000Hz + 双声道stereo + fltp采样格式（AAC标准格式）
+            audio_filters = [
+                "aformat=sample_rates=48000:channel_layouts=stereo:sample_fmts=fltp",
+                f"atrim=0:{chain.duration}",
+                "asetpts=PTS-STARTPTS",
+            ]
+            audio_parts.append(f"[{idx}:a]{','.join(audio_filters)}[{chain.audio_label}]")
+
+    if audio_parts:
+        parts.extend(audio_parts)
+        audio_inputs = "".join(f"[{c.audio_label}]" for c in clip_chains if c.audio_label)
+        audio_count = sum(1 for c in clip_chains if c.audio_label)
+        if audio_count > 0:
+            parts.append(f"{audio_inputs}concat=n={audio_count}:v=0:a=1[outa]")
+
+    return ";".join(parts), total_duration
 
 
 def _build_xfade_filter(
@@ -429,5 +569,80 @@ def _build_xfade_filter(
     transition_duration: float,
     transitions: list[str],
 ) -> tuple[str, float]:
-    """向后兼容：委托给 video_filter_builder.build_xfade_filter。"""
-    return _build_xfade_filter_func(clip_chains, transition_duration, transitions)
+    """构建 xfade 转场滤镜链。
+
+    每两个相邻片段之间插入 xfade 转场。
+    offset = 前一个片段的累积时长 - 转场时长。
+
+    格式（2 片段）：
+    [0:v]filters[v0]; [1:v]filters[v1];
+    [v0][v1]xfade=transition=fade:duration=0.5:offset=4.5[outv]
+
+    格式（3+ 片段）：
+    [v0][v1]xfade=...[tmp1]; [tmp1][v2]xfade=...[outv]
+    """
+    n = len(clip_chains)
+    parts: list[str] = []
+    total_duration = 0.0
+
+    # 每个片段的滤镜链
+    for idx, chain in enumerate(clip_chains):
+        filter_body = ",".join(chain.filters)
+        parts.append(f"[{idx}:v]{filter_body}[{chain.video_label}]")
+        total_duration += chain.duration
+
+    # xfade 链
+    if n == 1:
+        # 单片段不需要 xfade
+        parts.append(f"[{clip_chains[0].video_label}]copy[outv]")
+        return ";".join(parts), total_duration
+
+    # 计算每个转场的 offset
+    cumulative = 0.0
+    prev_label = clip_chains[0].video_label
+
+    for i in range(1, n):
+        cumulative += clip_chains[i - 1].duration
+        offset = max(0.0, cumulative - transition_duration * i)
+
+        # 获取转场类型
+        transition = transitions[i] if i < len(transitions) else "cut"
+        xfade_transition = _XFADE_TRANSITION_MAP.get(transition, "fade")
+
+        if i == n - 1:
+            # 最后一个转场，输出到 [outv]
+            out_label = "outv"
+        else:
+            out_label = f"xf{i}"
+
+        parts.append(
+            f"[{prev_label}][{clip_chains[i].video_label}]"
+            f"xfade=transition={xfade_transition}"
+            f":duration={transition_duration}"
+            f":offset={offset:.3f}"
+            f"[{out_label}]"
+        )
+        prev_label = out_label
+
+    # 总时长需要减去转场重叠部分
+    total_duration -= transition_duration * (n - 1)
+
+    # 音频：先 aformat 归一化再 concat（不同采样率/声道/采样格式会导致concat失败）
+    audio_chains_with_label = [(c, c.audio_label) for c in clip_chains if c.audio_label]
+    if len(audio_chains_with_label) >= 2:
+        normalized_audio_labels: list[str] = []
+        for chain, _ in audio_chains_with_label:
+            norm_label = f"anorm_{chain.video_label}"
+            audio_filters = [
+                "aformat=sample_rates=48000:channel_layouts=stereo:sample_fmts=fltp",
+                f"atrim=0:{chain.duration}",
+                "asetpts=PTS-STARTPTS",
+            ]
+            parts.append(f"[{chain.audio_label}]{','.join(audio_filters)}[{norm_label}]")
+            normalized_audio_labels.append(norm_label)
+        audio_inputs = "".join(f"[{label}]" for label in normalized_audio_labels)
+        parts.append(f"{audio_inputs}concat=n={len(normalized_audio_labels)}:v=0:a=1[outa]")
+    elif len(audio_chains_with_label) == 1:
+        parts.append(f"[{audio_chains_with_label[0][0].audio_label}]acopy[outa]")
+
+    return ";".join(parts), max(0.0, total_duration)

apps/web/src/pages/editing-planner/components/pip-config/LayerConfig.tsx

@@ -2,7 +2,12 @@
  * 混剪单图层配置区
  */
 import React from "react"
-import type { PipLayer, PipAnimType, PipSlideDirection, PipGridPosition } from "@/pages/editing-planner/types"
+import type {
+  PipLayer,
+  PipAnimType,
+  PipSlideDirection,
+  PipGridPosition,
+} from "@/pages/editing-planner/types"
 import {
   GRID_POSITIONS,
   ANIM_OPTIONS,

apps/worker/worker_app/tasks/generation.py

@@ -20,19 +20,21 @@ import time
 from pathlib import Path
 from typing import Any
 
+from video_processing.ffmpeg_utils import probe_duration
 from worker_app.celery_app import celery_app
 from worker_app.db import SessionLocal
-
-from packages.domain.bgm_utils import merge_bgm_config
-from video_processing.ffmpeg_utils import probe_duration
+from worker_app.tasks.generation_plan_builder import VirtualClip as _VirtualClip
+from worker_app.tasks.generation_plan_builder import VirtualPlan as _VirtualPlan
+from worker_app.tasks.generation_plan_builder import apply_template_clip_effects as _apply_template_clip_effects
 from worker_app.tasks.generation_plan_builder import (
-    VirtualPlan as _VirtualPlan,
-    VirtualClip as _VirtualClip,
-    build_error_info as _build_error_info,
-    extract_intro_outro_from_clip_configs as _extract_intro_outro_from_clip_configs,
-    apply_template_clip_effects as _apply_template_clip_effects,
     build_clips_by_mode,
 )
+from worker_app.tasks.generation_plan_builder import build_error_info as _build_error_info
+from worker_app.tasks.generation_plan_builder import (
+    extract_intro_outro_from_clip_configs as _extract_intro_outro_from_clip_configs,
+)
+
+from packages.domain.bgm_utils import merge_bgm_config
 
 OUTPUT_WIDTH = 1280
 OUTPUT_HEIGHT = 720

apps/worker/worker_app/tasks/ingest.py

@@ -14,70 +14,18 @@ from packages.adapters.sqlalchemy_impl import (
     SQLAlchemyIngestJobRepository,
 )
 from packages.domain import Asset, AssetStatus, IngestJobStatus
+from packages.domain.media_validation import (
+    MIN_AUDIO_FILE_SIZE,
+    MIN_IMAGE_FILE_SIZE,
+    MIN_VIDEO_FILE_SIZE,
+    SUPPORTED_VIDEO_CODECS,
+    is_valid_media as _is_valid_media,
+    safe_parse_fps as _safe_parse_fps,
+)
 
 logger = get_task_logger(__name__)
 
 
-# 最小有效文件大小（字节）：小于此值的直接判为无效，避免文本/空文件伪装成媒体
-MIN_VIDEO_FILE_SIZE = 1024  # 1KB
-MIN_AUDIO_FILE_SIZE = 100  # 100B
-MIN_IMAGE_FILE_SIZE = 100  # 100B
-
-# 支持的视频编码格式（白名单，尽可能放宽）
-# 渲染引擎会在 concat 前统一转码为 h264，因此只要 ffprobe 能识别的视频编码都允许 ingested
-SUPPORTED_VIDEO_CODECS = {
-    "h264",
-    "avc1",
-    "avc",  # H.264 / AVC
-    "hevc",
-    "h265",
-    "hev1",
-    "hvc1",  # H.265 / HEVC
-    "vp9",
-    "vp09",  # VP9
-    "av1",
-    "av01",  # AV1
-    "vp8",
-    "vp08",  # VP8
-    "mpeg4",
-    "mp4v",  # MPEG-4
-    "mpeg2video",
-    "mpg2",  # MPEG-2
-    "wmv2",
-    "wmv1",
-    "vc1",  # WMV / VC-1
-    "flv1",
-    "flv",
-    "vp6f",  # Flash / FLV
-    "theora",
-    "ogg",  # Theora
-    "prores",
-    "prores_ks",
-    "apcn",
-    "apch",
-    "apco",
-    "apcs",
-    "ap4h",
-    "ap4x",  # Apple ProRes
-    "dnxhd",
-    "dnxhr",  # DNxHD / DNxHR
-}
-
-
-def _safe_parse_fps(fps_str: str) -> float:
-    """Safely parse fps from a fraction string like \"30/1\" or \"30000/1001\"."""
-    try:
-        if "/" in fps_str:
-            num, den = fps_str.split("/", 1)
-            den_val = float(den)
-            if den_val == 0:
-                return 0.0
-            return float(num) / den_val
-        return float(fps_str)
-    except (ValueError, ZeroDivisionError):
-        return 0.0
-
-
 def extract_media_metadata(file_url: str, media_type: str) -> tuple[dict, bool]:
     """
     提取媒体文件的元数据。
@@ -207,38 +155,6 @@ def extract_media_metadata(file_url: str, media_type: str) -> tuple[dict, bool]:
     return metadata, success
 
 
-def _is_valid_media(metadata: dict, media_type: str) -> bool:
-    """根据元数据判断文件是否为有效媒体文件。
-
-    Args:
-        metadata: extract_media_metadata 返回的元数据
-        media_type: 媒体类型
-
-    Returns:
-        True 表示文件有效
-    """
-    size = int(metadata.get("size_bytes", 0))
-
-    if media_type == "video":
-        duration = float(metadata.get("duration", 0))
-        if size < MIN_VIDEO_FILE_SIZE or duration <= 0:
-            return False
-        # 编码格式校验：只排除明确非视频的编码格式，只要 ffprobe 能识别的视频编码都允许
-        # 渲染引擎会在 concat 前统一转码为 h264 yuv420p，ingest 层不再做严格的编码拦截
-        codec = str(metadata.get("codec", "")).lower()
-        if codec and codec not in SUPPORTED_VIDEO_CODECS:
-            logger.info("检测到非白名单视频编码 %s，仍允许 ingested，渲染层会统一转码", codec)
-        return True
-    if media_type == "audio":
-        duration = float(metadata.get("duration", 0))
-        return size >= MIN_AUDIO_FILE_SIZE and duration > 0
-    if media_type == "image":
-        width = int(metadata.get("width", 0))
-        height = int(metadata.get("height", 0))
-        return size >= MIN_IMAGE_FILE_SIZE and width > 0 and height > 0
-    return False
-
-
 @celery_app.task(name="worker.ingest_asset")
 def ingest_asset(job_id: str) -> dict:
     """

packages/domain/media_validation.py

@@ -0,0 +1,110 @@
+"""媒体文件有效性校验与元数据解析工具。
+
+从 worker ingest 任务中抽取的纯逻辑模块，包含：
+- FPS 解析：从分数格式字符串（如 30000/1001）安全解析帧率
+- 媒体有效性校验：根据元数据判断视频/音频/图片文件是否有效
+- 常量定义：最小文件大小、支持的视频编码白名单
+"""
+
+from __future__ import annotations
+
+# 最小有效文件大小（字节）：小于此值的直接判为无效，避免文本/空文件伪装成媒体
+MIN_VIDEO_FILE_SIZE = 1024  # 1KB
+MIN_AUDIO_FILE_SIZE = 100  # 100B
+MIN_IMAGE_FILE_SIZE = 100  # 100B
+
+# 支持的视频编码格式（白名单，尽可能放宽）
+# 渲染引擎会在 concat 前统一转码为 h264，因此只要 ffprobe 能识别的视频编码都允许 ingested
+SUPPORTED_VIDEO_CODECS: frozenset[str] = frozenset(
+    {
+        "h264",
+        "avc1",
+        "avc",  # H.264 / AVC
+        "hevc",
+        "h265",
+        "hev1",
+        "hvc1",  # H.265 / HEVC
+        "vp9",
+        "vp09",  # VP9
+        "av1",
+        "av01",  # AV1
+        "vp8",
+        "vp08",  # VP8
+        "mpeg4",
+        "mp4v",  # MPEG-4
+        "mpeg2video",
+        "mpg2",  # MPEG-2
+        "wmv2",
+        "wmv1",
+        "vc1",  # WMV / VC-1
+        "flv1",
+        "flv",
+        "vp6f",  # Flash / FLV
+        "theora",
+        "ogg",  # Theora
+        "prores",
+        "prores_ks",
+        "apcn",
+        "apch",
+        "apco",
+        "apcs",
+        "ap4h",
+        "ap4x",  # Apple ProRes
+        "dnxhd",
+        "dnxhr",  # DNxHD / DNxHR
+    }
+)
+
+
+def safe_parse_fps(fps_str: str) -> float:
+    """Safely parse fps from a fraction string like "30/1" or "30000/1001".
+
+    Args:
+        fps_str: FPS 字符串，支持小数格式（"30.0"）或分数格式（"30000/1001"）
+
+    Returns:
+        解析得到的帧率浮点数；解析失败或分母为0时返回 0.0
+    """
+    try:
+        if "/" in fps_str:
+            num, den = fps_str.split("/", 1)
+            den_val = float(den)
+            if den_val == 0:
+                return 0.0
+            return float(num) / den_val
+        return float(fps_str)
+    except (ValueError, ZeroDivisionError):
+        return 0.0
+
+
+def is_valid_media(metadata: dict, media_type: str) -> bool:
+    """根据元数据判断文件是否为有效媒体文件。
+
+    Args:
+        metadata: 媒体元数据字典，可能包含 size_bytes / duration / codec / width / height 等
+        media_type: 媒体类型（video / audio / image）
+
+    Returns:
+        True 表示文件有效
+    """
+    size = int(metadata.get("size_bytes", 0))
+
+    if media_type == "video":
+        duration = float(metadata.get("duration", 0))
+        if size < MIN_VIDEO_FILE_SIZE or duration <= 0:
+            return False
+        # 编码格式校验：只排除明确非视频的编码格式，只要 ffprobe 能识别的视频编码都允许
+        # 渲染引擎会在 concat 前统一转码为 h264 yuv420p，ingest 层不再做严格的编码拦截
+        codec = str(metadata.get("codec", "")).lower()
+        if codec and codec not in SUPPORTED_VIDEO_CODECS:
+            # 非白名单编码仍允许通过，仅记录日志（调用方负责日志）
+            pass
+        return True
+    if media_type == "audio":
+        duration = float(metadata.get("duration", 0))
+        return size >= MIN_AUDIO_FILE_SIZE and duration > 0
+    if media_type == "image":
+        width = int(metadata.get("width", 0))
+        height = int(metadata.get("height", 0))
+        return size >= MIN_IMAGE_FILE_SIZE and width > 0 and height > 0
+    return False

packages/domain/plan_generator_utils.py

@@ -321,11 +321,7 @@ def create_clips_from_configs(
         clip_type = cfg.clip_type.value if hasattr(cfg.clip_type, "value") else cfg.clip_type
 
         # transition_effect 可能是枚举或字符串
-        transition = (
-            cfg.transition_effect.value
-            if hasattr(cfg.transition_effect, "value")
-            else cfg.transition_effect
-        )
+        transition = cfg.transition_effect.value if hasattr(cfg.transition_effect, "value") else cfg.transition_effect
 
         # 从 clip config 中解析 playback_speed（兼容 speed_ratio 字段名）
         clip_cfg = cfg.config or {}

packages/domain/video_filter_builder.py

@@ -1,375 +0,0 @@
-"""视频滤镜构建器 — FFmpeg filter_complex 纯逻辑层。
-
-从 video_compose_service.py 抽离的纯函数集合，专门负责 FFmpeg 滤镜链的构建，
-不依赖数据库、不做 IO，便于单元测试。
-
-主要职责：
-- 单片段滤镜链构建（scale / pad / format / fps / setpts / trim）
-- concat 滤镜构建（无转场高效拼接）
-- xfade 转场滤镜链构建（fade / slide / dissolve / wipe）
-- 完整 filter_complex 策略选择与组装
-- 音频流判断与音频滤镜归一化
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import TYPE_CHECKING
-
-from packages.domain.template_clip_config import TransitionEffect
-
-if TYPE_CHECKING:
-    from packages.domain.edit_plan_clip import EditPlanClip
-
-
-# ── 常量 ──────────────────────────────────────────────────────────────────────
-
-DEFAULT_OUTPUT_WIDTH = 1280
-DEFAULT_OUTPUT_HEIGHT = 720
-DEFAULT_FPS = 25
-
-# xfade 转场映射：TransitionEffect → FFmpeg xfade transition 名称
-XFADE_TRANSITION_MAP: dict[str, str] = {
-    TransitionEffect.FADE: "fade",
-    TransitionEffect.SLIDE_LEFT: "slideleft",
-    TransitionEffect.SLIDE_RIGHT: "slideright",
-    TransitionEffect.DISSOLVE: "dissolve",
-    TransitionEffect.WIPE: "wipeleft",
-}
-
-# 转场默认时长（秒）
-DEFAULT_TRANSITION_DURATION = 0.5
-
-# 默认片段时长（当 clip.duration <= 0 时使用）
-DEFAULT_CLIP_DURATION = 5.0
-
-
-# ── 数据结构 ──────────────────────────────────────────────────────────────────
-
-
-@dataclass(frozen=True)
-class ClipFilterChain:
-    """单个片段的滤镜链描述。"""
-
-    clip_id: str
-    input_index: int
-    video_label: str
-    audio_label: str | None
-    filters: list[str]
-    duration: float
-
-
-# ── 单片段滤镜链 ──────────────────────────────────────────────────────────────
-
-
-def build_clip_filter(
-    clip: "EditPlanClip",
-    input_index: int,
-    output_width: int,
-    output_height: int,
-    fps: int,
-) -> ClipFilterChain:
-    """为单个片段构建滤镜链。
-
-    滤镜顺序：
-    1. scale — 等比缩放到目标分辨率（保证覆盖，不裁剪内容）
-    2. pad — 居中+留黑边到目标分辨率（保持原始比例）
-    3. format — 统一像素格式为 yuv420p（concat 要求像素格式一致）
-    4. fps — 统一帧率（concat 要求所有输入帧率一致）
-    5. setpts — 重置时间戳 + 起始偏移
-    6. trim — 视频时长裁剪 + 重置 PTS
-
-    Args:
-        clip: 剪辑计划片段
-        input_index: 输入流索引（对应第几个 -i）
-        output_width: 输出宽度（像素）
-        output_height: 输出高度（像素）
-        fps: 输出帧率
-
-    Returns:
-        ClipFilterChain 描述对象
-    """
-    duration = clip.duration if clip.duration > 0 else DEFAULT_CLIP_DURATION
-    start = clip.start_time
-
-    filters: list[str] = []
-
-    # 1. scale: 等比缩放（保持比例，不裁剪）
-    filters.append(f"scale={output_width}:{output_height}" f":force_original_aspect_ratio=decrease")
-
-    # 2. pad: 居中+留黑边到目标分辨率
-    filters.append(f"pad={output_width}:{output_height}:(ow-iw)/2:(oh-ih)/2:black")
-
-    # 3. format: 统一像素格式为 yuv420p
-    filters.append("format=yuv420p")
-
-    # 4. fps: 统一帧率
-    if fps and fps > 0:
-        filters.append(f"fps={fps}")
-
-    # 5. setpts: 重置时间戳 + 偏移
-    if start > 0:
-        filters.append(f"setpts=PTS-STARTPTS+{start}/TB")
-    else:
-        filters.append("setpts=PTS-STARTPTS")
-
-    # 6. trim: 视频时长 + 重置 PTS
-    filters.append(f"trim=0:{duration}")
-    filters.append("setpts=PTS-STARTPTS")
-
-    video_label = f"v{input_index}"
-
-    # 音频标签：title/subtitle 是纯文字/图片卡片，没有音频流
-    clip_type = clip.clip_type.lower() if clip.clip_type else ""
-    has_audio_stream = clip_type not in ("title", "subtitle")
-    audio_label = f"a{input_index}" if has_audio_stream else None
-
-    return ClipFilterChain(
-        clip_id=clip.id,
-        input_index=input_index,
-        video_label=video_label,
-        audio_label=audio_label,
-        filters=filters,
-        duration=duration,
-    )
-
-
-# ── 滤镜串联工具 ──────────────────────────────────────────────────────────────
-
-
-def chain_filters(filters: list[str], output_label: str, input_label: str = "0:v") -> str:
-    """将滤镜列表串联为 FFmpeg 滤镜字符串。
-
-    Args:
-        filters: 滤镜表达式列表
-        output_label: 输出标签名（不含方括号）
-        input_label: 输入标签（默认 "0:v"）
-
-    Returns:
-        形如 "[0:v]scale=1280:720,fps=25[v0]" 的字符串
-    """
-    filter_body = ",".join(filters)
-    return f"[{input_label}]{filter_body}[{output_label}]"
-
-
-# ── 音频判断 ──────────────────────────────────────────────────────────────────
-
-
-def has_audio(clip_chains: list[ClipFilterChain]) -> bool:
-    """是否有任何片段包含音频流。"""
-    return any(c.audio_label is not None for c in clip_chains)
-
-
-# ── concat 滤镜 ──────────────────────────────────────────────────────────────
-
-
-def build_concat_filter(
-    clip_chains: list[ClipFilterChain],
-) -> tuple[str, float]:
-    """构建 concat 滤镜（无转场，高效拼接）。
-
-    视频：每个片段先应用各自滤镜链，再用 concat 滤镜拼接
-    音频：先 aformat 归一化（48000Hz/stereo/fltp）再 concat，
-         避免不同采样率/声道导致 concat 失败
-
-    Args:
-        clip_chains: 各片段的滤镜链描述
-
-    Returns:
-        (filter_complex_string, estimated_total_duration)
-    """
-    n = len(clip_chains)
-    if n == 0:
-        return "", 0.0
-
-    parts: list[str] = []
-    total_duration = 0.0
-
-    # 每个片段的视频滤镜链
-    for idx, chain in enumerate(clip_chains):
-        filter_body = ",".join(chain.filters)
-        parts.append(f"[{idx}:v]{filter_body}[{chain.video_label}]")
-        total_duration += chain.duration
-
-    # 视频 concat 滤镜
-    concat_inputs = "".join(f"[{c.video_label}]" for c in clip_chains)
-    parts.append(f"{concat_inputs}concat=n={n}:v=1:a=0[outv]")
-
-    # 音频：归一化 + concat
-    _append_audio_concat(parts, clip_chains)
-
-    return ";".join(parts), total_duration
-
-
-# ── xfade 转场滤镜 ────────────────────────────────────────────────────────────
-
-
-def build_xfade_filter(
-    clip_chains: list[ClipFilterChain],
-    transition_duration: float,
-    transitions: list[str],
-) -> tuple[str, float]:
-    """构建 xfade 转场滤镜链。
-
-    每两个相邻片段之间插入 xfade 转场。
-    offset = 前一个片段的累积时长 - 转场时长。
-
-    视频转场支持：fade / slideleft / slideright / dissolve / wipeleft
-
-    Args:
-        clip_chains: 各片段的滤镜链描述
-        transition_duration: 转场时长（秒）
-        transitions: 每个片段对应的转场效果列表（索引对应片段）
-
-    Returns:
-        (filter_complex_string, estimated_total_duration)
-    """
-    n = len(clip_chains)
-    if n == 0:
-        return "", 0.0
-
-    parts: list[str] = []
-    total_duration = 0.0
-
-    # 每个片段的视频滤镜链
-    for idx, chain in enumerate(clip_chains):
-        filter_body = ",".join(chain.filters)
-        parts.append(f"[{idx}:v]{filter_body}[{chain.video_label}]")
-        total_duration += chain.duration
-
-    # 单片段：直接 copy 输出（无音频，与原实现保持一致）
-    if n == 1:
-        parts.append(f"[{clip_chains[0].video_label}]copy[outv]")
-        return ";".join(parts), total_duration
-
-    # xfade 链式转场
-    cumulative = 0.0
-    prev_label = clip_chains[0].video_label
-
-    for i in range(1, n):
-        cumulative += clip_chains[i - 1].duration
-        offset = max(0.0, cumulative - transition_duration * i)
-
-        # 获取转场类型
-        transition = transitions[i] if i < len(transitions) else "cut"
-        xfade_transition = XFADE_TRANSITION_MAP.get(transition, "fade")
-
-        out_label = "outv" if i == n - 1 else f"xf{i}"
-
-        parts.append(
-            f"[{prev_label}][{clip_chains[i].video_label}]"
-            f"xfade=transition={xfade_transition}"
-            f":duration={transition_duration}"
-            f":offset={offset:.3f}"
-            f"[{out_label}]"
-        )
-        prev_label = out_label
-
-    # 总时长减去转场重叠部分
-    total_duration -= transition_duration * (n - 1)
-    total_duration = max(0.0, total_duration)
-
-    # 音频：xfade 路径下的音频处理
-    # 注意：使用 chain.audio_label 作为输入标签（与原实现保持一致）
-    audio_chains = [c for c in clip_chains if c.audio_label]
-    if len(audio_chains) >= 2:
-        normalized_labels: list[str] = []
-        for chain in audio_chains:
-            norm_label = f"anorm_{chain.video_label}"
-            audio_filters = [
-                "aformat=sample_rates=48000:channel_layouts=stereo:sample_fmts=fltp",
-                f"atrim=0:{chain.duration}",
-                "asetpts=PTS-STARTPTS",
-            ]
-            parts.append(f"[{chain.audio_label}]{','.join(audio_filters)}[{norm_label}]")
-            normalized_labels.append(norm_label)
-        audio_inputs = "".join(f"[{label}]" for label in normalized_labels)
-        parts.append(f"{audio_inputs}concat=n={len(normalized_labels)}:v=0:a=1[outa]")
-    elif len(audio_chains) == 1:
-        parts.append(f"[{audio_chains[0].audio_label}]acopy[outa]")
-
-    return ";".join(parts), total_duration
-
-
-# ── 完整 filter_complex 构建（策略选择） ────────────────────────────────────
-
-
-def build_filter_complex(
-    clip_chains: list[ClipFilterChain],
-    output_width: int,
-    output_height: int,
-    transition_duration: float,
-    transitions: list[str],
-) -> tuple[str, float]:
-    """构建完整的 filter_complex 字符串（策略自动选择）。
-
-    策略：
-    - 空列表：返回空字符串 + 0 时长
-    - 单片段：直接输出（scale+pad+fps+trim 单链）
-    - 多片段 + 全 cut：使用 concat 滤镜（高效）
-    - 多片段 + 有转场：使用 xfade 滤镜链
-
-    Args:
-        clip_chains: 各片段的滤镜链描述
-        output_width: 输出宽度（目前单片段策略不使用，保留参数一致性）
-        output_height: 输出高度（同上）
-        transition_duration: 转场时长（秒）
-        transitions: 每个片段对应的转场效果列表
-
-    Returns:
-        (filter_complex_string, estimated_total_duration)
-    """
-    n = len(clip_chains)
-
-    if n == 0:
-        return "", 0.0
-
-    # 单片段
-    if n == 1:
-        chain = clip_chains[0]
-        filter_str = chain_filters(chain.filters, chain.video_label)
-        # 音频直通
-        if chain.audio_label:
-            filter_str += f";[0:a]{chain.audio_label}"
-        total_duration = chain.duration
-        return filter_str, total_duration
-
-    # 检查是否有转场
-    has_transitions = any(t != TransitionEffect.CUT and t != "cut" for t in transitions)
-
-    if not has_transitions:
-        return build_concat_filter(clip_chains)
-
-    # 有转场：使用 xfade
-    return build_xfade_filter(
-        clip_chains=clip_chains,
-        transition_duration=transition_duration,
-        transitions=transitions,
-    )
-
-
-# ── 内部辅助：音频处理 ───────────────────────────────────────────────────────
-
-
-def _append_audio_concat(parts: list[str], clip_chains: list[ClipFilterChain]) -> None:
-    """追加音频归一化 + concat 滤镜链到 parts（concat 路径）。
-
-    与原实现保持一致：归一化输出标签复用 chain.audio_label，
-    concat 直接使用 audio_label 作为输入。
-    """
-    audio_chains = [c for c in clip_chains if c.audio_label]
-    if not audio_chains:
-        return
-
-    # 先 aformat 归一化，输出到 chain.audio_label
-    for chain in audio_chains:
-        audio_filters = [
-            "aformat=sample_rates=48000:channel_layouts=stereo:sample_fmts=fltp",
-            f"atrim=0:{chain.duration}",
-            "asetpts=PTS-STARTPTS",
-        ]
-        parts.append(f"[{chain.input_index}:a]{','.join(audio_filters)}[{chain.audio_label}]")
-
-    # concat 滤镜（使用 audio_label 作为输入）
-    audio_inputs = "".join(f"[{c.audio_label}]" for c in audio_chains)
-    parts.append(f"{audio_inputs}concat=n={len(audio_chains)}:v=0:a=1[outa]")

tests/unit/test_application_modules.py

@@ -0,0 +1,499 @@
+"""Application 层零测试模块合集 — 第100波里程碑。
+
+覆盖:
+- packages/application/generated_videos.py (8个UseCase)
+- packages/application/assets.py (ListAssets + CreateAsset)
+- packages/application/asset_libraries.py (ListLibraries + CreateLibrary)
+
+策略: Mock repository，测参数校验 + 委托行为
+"""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from packages.application.asset_libraries import (
+    CreateAssetLibraryCommand,
+    CreateAssetLibraryUseCase,
+    ListAssetLibrariesUseCase,
+)
+from packages.application.assets import (
+    CreateAssetCommand,
+    CreateAssetUseCase,
+    ListAssetsUseCase,
+)
+from packages.application.generated_videos import (
+    GetGeneratedVideoDownloadUrlUseCase,
+    GetGeneratedVideoUseCase,
+    GetVideosByIdsUseCase,
+    ListGeneratedVideosByTaskUseCase,
+    ListGeneratedVideosPaginatedUseCase,
+    ListGeneratedVideosUseCase,
+    UpdateVideoReviewStatusUseCase,
+)
+from packages.domain import AssetLibraryKind, AssetStatus, ClassificationStatus, GeneratedVideo
+
+# ── generated_videos.py ────────────────────────────────────────────────────────
+
+
+class TestListGeneratedVideosUseCase:
+    def test_success(self):
+        mock_repo = MagicMock()
+        mock_repo.list_by_project.return_value = [MagicMock(spec=GeneratedVideo)]
+        use_case = ListGeneratedVideosUseCase(mock_repo)
+
+        result = use_case.execute("proj1")
+
+        assert len(result) == 1
+        mock_repo.list_by_project.assert_called_once_with("proj1")
+
+    def test_strips_project_id(self):
+        mock_repo = MagicMock()
+        use_case = ListGeneratedVideosUseCase(mock_repo)
+
+        use_case.execute("  proj1  ")
+
+        mock_repo.list_by_project.assert_called_once_with("proj1")
+
+    def test_empty_project_id_raises(self):
+        mock_repo = MagicMock()
+        use_case = ListGeneratedVideosUseCase(mock_repo)
+
+        with pytest.raises(ValueError, match="project_id 不能为空"):
+            use_case.execute("")
+
+    def test_whitespace_project_id_raises(self):
+        mock_repo = MagicMock()
+        use_case = ListGeneratedVideosUseCase(mock_repo)
+
+        with pytest.raises(ValueError, match="project_id 不能为空"):
+            use_case.execute("  \t  ")
+
+
+class TestListGeneratedVideosPaginatedUseCase:
+    def test_default_params(self):
+        mock_repo = MagicMock()
+        mock_repo.list_paginated.return_value = ([], 0)
+        use_case = ListGeneratedVideosPaginatedUseCase(mock_repo)
+
+        result, total = use_case.execute()
+
+        assert total == 0
+        assert result == []
+        mock_repo.list_paginated.assert_called_once_with(
+            user_id=None,
+            project_id=None,
+            status=None,
+            review_status=None,
+            page=1,
+            page_size=20,
+        )
+
+    def test_page_below_1_clamps_to_1(self):
+        mock_repo = MagicMock()
+        mock_repo.list_paginated.return_value = ([], 0)
+        use_case = ListGeneratedVideosPaginatedUseCase(mock_repo)
+
+        use_case.execute(page=0)
+
+        mock_repo.list_paginated.assert_called_once()
+        call_kwargs = mock_repo.list_paginated.call_args.kwargs
+        assert call_kwargs["page"] == 1
+
+    def test_negative_page_clamps(self):
+        mock_repo = MagicMock()
+        mock_repo.list_paginated.return_value = ([], 0)
+        use_case = ListGeneratedVideosPaginatedUseCase(mock_repo)
+
+        use_case.execute(page=-5)
+
+        assert mock_repo.list_paginated.call_args.kwargs["page"] == 1
+
+    def test_page_size_zero_clamps(self):
+        mock_repo = MagicMock()
+        mock_repo.list_paginated.return_value = ([], 0)
+        use_case = ListGeneratedVideosPaginatedUseCase(mock_repo)
+
+        use_case.execute(page_size=0)
+
+        assert mock_repo.list_paginated.call_args.kwargs["page_size"] == 20
+
+    def test_page_size_over_100_clamps(self):
+        mock_repo = MagicMock()
+        mock_repo.list_paginated.return_value = ([], 0)
+        use_case = ListGeneratedVideosPaginatedUseCase(mock_repo)
+
+        use_case.execute(page_size=200)
+
+        assert mock_repo.list_paginated.call_args.kwargs["page_size"] == 20
+
+    def test_page_size_50_ok(self):
+        mock_repo = MagicMock()
+        mock_repo.list_paginated.return_value = ([], 0)
+        use_case = ListGeneratedVideosPaginatedUseCase(mock_repo)
+
+        use_case.execute(page_size=50)
+
+        assert mock_repo.list_paginated.call_args.kwargs["page_size"] == 50
+
+    def test_with_all_filters(self):
+        mock_repo = MagicMock()
+        mock_repo.list_paginated.return_value = ([], 0)
+        use_case = ListGeneratedVideosPaginatedUseCase(mock_repo)
+
+        use_case.execute(
+            user_id="u1",
+            project_id="p1",
+            status="completed",
+            review_status="approved",
+            page=2,
+            page_size=10,
+        )
+
+        mock_repo.list_paginated.assert_called_once_with(
+            user_id="u1",
+            project_id="p1",
+            status="completed",
+            review_status="approved",
+            page=2,
+            page_size=10,
+        )
+
+
+class TestGetGeneratedVideoUseCase:
+    def test_found(self):
+        mock_repo = MagicMock()
+        expected = MagicMock(spec=GeneratedVideo)
+        mock_repo.get.return_value = expected
+        use_case = GetGeneratedVideoUseCase(mock_repo)
+
+        result = use_case.execute("vid1")
+
+        assert result == expected
+        mock_repo.get.assert_called_once_with("vid1")
+
+    def test_not_found(self):
+        mock_repo = MagicMock()
+        mock_repo.get.return_value = None
+        use_case = GetGeneratedVideoUseCase(mock_repo)
+
+        result = use_case.execute("vid1")
+
+        assert result is None
+
+
+class TestListGeneratedVideosByTaskUseCase:
+    def test_success(self):
+        mock_repo = MagicMock()
+        mock_repo.list_by_generation_task.return_value = [MagicMock()]
+        use_case = ListGeneratedVideosByTaskUseCase(mock_repo)
+
+        result = use_case.execute("task1")
+
+        assert len(result) == 1
+        mock_repo.list_by_generation_task.assert_called_once_with("task1")
+
+    def test_strips_task_id(self):
+        mock_repo = MagicMock()
+        use_case = ListGeneratedVideosByTaskUseCase(mock_repo)
+
+        use_case.execute("  task1  ")
+
+        mock_repo.list_by_generation_task.assert_called_once_with("task1")
+
+    def test_empty_task_id_raises(self):
+        mock_repo = MagicMock()
+        use_case = ListGeneratedVideosByTaskUseCase(mock_repo)
+
+        with pytest.raises(ValueError, match="generation_task_id 不能为空"):
+            use_case.execute("")
+
+
+class TestGetGeneratedVideoDownloadUrlUseCase:
+    def test_found(self):
+        mock_repo = MagicMock()
+        mock_item = MagicMock()
+        mock_item.file_url = "https://cdn/v.mp4"
+        mock_repo.get.return_value = mock_item
+        use_case = GetGeneratedVideoDownloadUrlUseCase(mock_repo)
+
+        result = use_case.execute("vid1")
+
+        assert result == "https://cdn/v.mp4"
+
+    def test_not_found_returns_none(self):
+        mock_repo = MagicMock()
+        mock_repo.get.return_value = None
+        use_case = GetGeneratedVideoDownloadUrlUseCase(mock_repo)
+
+        result = use_case.execute("vid1")
+
+        assert result is None
+
+
+class TestUpdateVideoReviewStatusUseCase:
+    def test_pending_review(self):
+        mock_repo = MagicMock()
+        mock_repo.update_review_status.return_value = MagicMock()
+        use_case = UpdateVideoReviewStatusUseCase(mock_repo)
+
+        use_case.execute("vid1", "pending_review")
+
+        mock_repo.update_review_status.assert_called_once_with("vid1", "pending_review")
+
+    def test_approved(self):
+        mock_repo = MagicMock()
+        use_case = UpdateVideoReviewStatusUseCase(mock_repo)
+
+        use_case.execute("vid1", "approved")
+
+        mock_repo.update_review_status.assert_called_once_with("vid1", "approved")
+
+    def test_rejected(self):
+        mock_repo = MagicMock()
+        use_case = UpdateVideoReviewStatusUseCase(mock_repo)
+
+        use_case.execute("vid1", "rejected")
+
+        mock_repo.update_review_status.assert_called_once_with("vid1", "rejected")
+
+    def test_strips_video_id(self):
+        mock_repo = MagicMock()
+        use_case = UpdateVideoReviewStatusUseCase(mock_repo)
+
+        use_case.execute("  vid1  ", "approved")
+
+        mock_repo.update_review_status.assert_called_once_with("vid1", "approved")
+
+    def test_empty_video_id_raises(self):
+        mock_repo = MagicMock()
+        use_case = UpdateVideoReviewStatusUseCase(mock_repo)
+
+        with pytest.raises(ValueError, match="video_id 不能为空"):
+            use_case.execute("", "approved")
+
+    def test_invalid_status_raises(self):
+        mock_repo = MagicMock()
+        use_case = UpdateVideoReviewStatusUseCase(mock_repo)
+
+        with pytest.raises(ValueError, match="无效的 review_status"):
+            use_case.execute("vid1", "invalid_status")
+
+    def test_not_found_returns_none(self):
+        mock_repo = MagicMock()
+        mock_repo.update_review_status.return_value = None
+        use_case = UpdateVideoReviewStatusUseCase(mock_repo)
+
+        result = use_case.execute("vid1", "approved")
+
+        assert result is None
+
+
+class TestGetVideosByIdsUseCase:
+    def test_success(self):
+        mock_repo = MagicMock()
+        mock_repo.get_by_ids.return_value = [MagicMock(), MagicMock()]
+        use_case = GetVideosByIdsUseCase(mock_repo)
+
+        result = use_case.execute(["id1", "id2", "id3"])
+
+        assert len(result) == 2
+        mock_repo.get_by_ids.assert_called_once_with(["id1", "id2", "id3"])
+
+    def test_empty_list(self):
+        mock_repo = MagicMock()
+        mock_repo.get_by_ids.return_value = []
+        use_case = GetVideosByIdsUseCase(mock_repo)
+
+        result = use_case.execute([])
+
+        assert result == []
+        mock_repo.get_by_ids.assert_called_once_with([])
+
+
+# ── assets.py ──────────────────────────────────────────────────────────────────
+
+
+class TestCreateAssetCommand:
+    def test_minimal(self):
+        cmd = CreateAssetCommand(
+            project_id="p1",
+            library_id="l1",
+            name="test.mp4",
+            storage_key="k",
+            mime_type="video/mp4",
+        )
+        assert cmd.project_id == "p1"
+        assert cmd.library_id == "l1"
+        assert cmd.name == "test.mp4"
+        assert cmd.storage_key == "k"
+        assert cmd.mime_type == "video/mp4"
+        assert cmd.file_size == 0
+        assert cmd.status == AssetStatus.UPLOADING
+        assert cmd.classification_status == ClassificationStatus.PENDING
+
+    def test_full(self):
+        cmd = CreateAssetCommand(
+            project_id="p1",
+            library_id="l1",
+            name="test.mp4",
+            storage_key="k",
+            mime_type="video/mp4",
+            metadata={"k": "v"},
+            file_size=1024,
+            duration=10.0,
+            width=1920,
+            height=1080,
+            fps=30.0,
+            codec="h264",
+            status=AssetStatus.READY,
+            quality_score=0.9,
+            uploaded_by_user_id="u1",
+        )
+        assert cmd.file_size == 1024
+        assert cmd.duration == 10.0
+        assert cmd.status == AssetStatus.READY
+        assert cmd.quality_score == 0.9
+
+
+class TestListAssetsUseCase:
+    def test_success(self):
+        mock_repo = MagicMock()
+        mock_repo.find_by_library.return_value = []
+        use_case = ListAssetsUseCase(mock_repo)
+
+        result = use_case.execute("lib1")
+
+        assert result == []
+        mock_repo.find_by_library.assert_called_once_with("lib1")
+
+    def test_strips_library_id(self):
+        mock_repo = MagicMock()
+        use_case = ListAssetsUseCase(mock_repo)
+
+        use_case.execute("  lib1  ")
+
+        mock_repo.find_by_library.assert_called_once_with("lib1")
+
+    def test_empty_library_id_raises(self):
+        mock_repo = MagicMock()
+        use_case = ListAssetsUseCase(mock_repo)
+
+        with pytest.raises(ValueError, match="library_id 不能为空"):
+            use_case.execute("")
+
+
+class TestCreateAssetUseCase:
+    def test_creates_asset_via_repo(self):
+        mock_repo = MagicMock()
+        mock_repo.create.return_value = MagicMock()
+        use_case = CreateAssetUseCase(mock_repo)
+
+        cmd = CreateAssetCommand(
+            project_id="p1",
+            library_id="l1",
+            name="test.mp4",
+            storage_key="videos/t.mp4",
+            mime_type="video/mp4",
+            file_size=1024,
+        )
+        result = use_case.execute(cmd)
+
+        assert result is not None
+        mock_repo.create.assert_called_once()
+        created_asset = mock_repo.create.call_args[0][0]
+        assert created_asset.project_id == "p1"
+        assert created_asset.name == "test.mp4"
+        assert created_asset.file_size == 1024
+        assert created_asset.status == AssetStatus.UPLOADING
+
+    def test_asset_create_validation_propagates(self):
+        mock_repo = MagicMock()
+        use_case = CreateAssetUseCase(mock_repo)
+
+        cmd = CreateAssetCommand(
+            project_id="p1",
+            library_id="l1",
+            name="",
+            storage_key="k",
+            mime_type="video/mp4",
+        )
+
+        with pytest.raises(ValueError, match="素材名称不能为空"):
+            use_case.execute(cmd)
+
+
+# ── asset_libraries.py ────────────────────────────────────────────────────────
+
+
+class TestCreateAssetLibraryCommand:
+    def test_creation(self):
+        cmd = CreateAssetLibraryCommand(
+            project_id="p1",
+            name="我的库",
+            kind=AssetLibraryKind.VIDEO,
+        )
+        assert cmd.project_id == "p1"
+        assert cmd.name == "我的库"
+        assert cmd.kind == AssetLibraryKind.VIDEO
+
+
+class TestListAssetLibrariesUseCase:
+    def test_success(self):
+        mock_repo = MagicMock()
+        mock_repo.find_by_project.return_value = []
+        use_case = ListAssetLibrariesUseCase(mock_repo)
+
+        result = use_case.execute("p1")
+
+        assert result == []
+        mock_repo.find_by_project.assert_called_once_with("p1")
+
+    def test_strips_project_id(self):
+        mock_repo = MagicMock()
+        use_case = ListAssetLibrariesUseCase(mock_repo)
+
+        use_case.execute("  p1  ")
+
+        mock_repo.find_by_project.assert_called_once_with("p1")
+
+    def test_empty_project_id_raises(self):
+        mock_repo = MagicMock()
+        use_case = ListAssetLibrariesUseCase(mock_repo)
+
+        with pytest.raises(ValueError, match="project_id 不能为空"):
+            use_case.execute("")
+
+
+class TestCreateAssetLibraryUseCase:
+    def test_creates_library_via_repo(self):
+        mock_repo = MagicMock()
+        mock_repo.create.return_value = MagicMock()
+        use_case = CreateAssetLibraryUseCase(mock_repo)
+
+        cmd = CreateAssetLibraryCommand(
+            project_id="p1",
+            name="视频库",
+            kind=AssetLibraryKind.VIDEO,
+        )
+        result = use_case.execute(cmd)
+
+        assert result is not None
+        mock_repo.create.assert_called_once()
+        created = mock_repo.create.call_args[0][0]
+        assert created.project_id == "p1"
+        assert created.name == "视频库"
+        assert created.kind == AssetLibraryKind.VIDEO
+
+    def test_validation_propagates(self):
+        mock_repo = MagicMock()
+        use_case = CreateAssetLibraryUseCase(mock_repo)
+
+        cmd = CreateAssetLibraryCommand(
+            project_id="p1",
+            name="",
+            kind=AssetLibraryKind.VIDEO,
+        )
+
+        with pytest.raises(ValueError, match="素材库名称不能为空"):
+            use_case.execute(cmd)

tests/unit/test_asset_scoring.py

@@ -19,19 +19,19 @@ from typing import Optional
 import pytest
 
 from packages.domain.asset_scoring import (
-    AssetScoreDetail,
     MEDIUM_BUCKET_MAX,
     MIN_QUALITY_SCORE,
     OPTIMAL_DURATION_MAX,
     OPTIMAL_DURATION_MIN,
     SHORT_BUCKET_MAX,
-    SmartSelectResult,
     TARGET_HEIGHT,
     TARGET_WIDTH,
     WEIGHT_BITRATE,
     WEIGHT_DURATION,
     WEIGHT_QUALITY,
     WEIGHT_RESOLUTION,
+    AssetScoreDetail,
+    SmartSelectResult,
     _bucket_by_duration,
     calculate_total_score,
     diverse_selection,

tests/unit/test_domain_entities.py

@@ -0,0 +1,488 @@
+"""Domain entities 单元测试。"""
+
+from datetime import datetime, timezone
+
+import pytest
+
+from packages.domain.classification import (
+    AssetLibraryKind,
+    ClassificationStatus,
+    IngestJobStatus,
+)
+from packages.domain.entities import (
+    Asset,
+    AssetLibrary,
+    AssetStatus,
+    IngestJob,
+    Project,
+    User,
+)
+
+
+class TestProjectCreate:
+    def test_create_success(self):
+        project = Project.create(owner_user_id="user1", name="我的项目")
+        assert project.id is not None
+        assert len(project.id) == 32
+        assert project.owner_user_id == "user1"
+        assert project.name == "我的项目"
+        assert project.description == ""
+        assert project.shared_users == []
+        assert isinstance(project.created_at, datetime)
+
+    def test_create_with_description(self):
+        project = Project.create("u1", "Test Project", "A test description")
+        assert project.description == "A test description"
+
+    def test_create_strips_name(self):
+        project = Project.create("u1", "  带空格的项目  ")
+        assert project.name == "带空格的项目"
+
+    def test_create_strips_description(self):
+        project = Project.create("u1", "P1", "  desc  ")
+        assert project.description == "desc"
+
+    def test_create_empty_name(self):
+        with pytest.raises(ValueError, match="项目名称不能为空"):
+            Project.create("u1", "")
+
+    def test_create_whitespace_name(self):
+        with pytest.raises(ValueError, match="项目名称不能为空"):
+            Project.create("u1", "   \t  ")
+
+    def test_create_unique_ids(self):
+        p1 = Project.create("u1", "P1")
+        p2 = Project.create("u1", "P2")
+        assert p1.id != p2.id
+
+
+class TestProjectAccess:
+    def test_is_owner_true(self):
+        project = Project.create("owner1", "P1")
+        assert project.is_owner("owner1") is True
+
+    def test_is_owner_false(self):
+        project = Project.create("owner1", "P1")
+        assert project.is_owner("other") is False
+
+    def test_is_shared_with_true(self):
+        project = Project.create("owner1", "P1")
+        project.shared_users = ["user_a", "user_b"]
+        assert project.is_shared_with("user_a") is True
+        assert project.is_shared_with("user_b") is True
+
+    def test_is_shared_with_false(self):
+        project = Project.create("owner1", "P1")
+        project.shared_users = ["user_a"]
+        assert project.is_shared_with("user_c") is False
+
+    def test_can_access_owner(self):
+        project = Project.create("owner1", "P1")
+        assert project.can_access("owner1") is True
+
+    def test_can_access_shared_user(self):
+        project = Project.create("owner1", "P1")
+        project.shared_users = ["shared_user"]
+        assert project.can_access("shared_user") is True
+
+    def test_cannot_access_other(self):
+        project = Project.create("owner1", "P1")
+        assert project.can_access("stranger") is False
+
+    def test_empty_shared_users(self):
+        project = Project.create("owner1", "P1")
+        assert project.shared_users == []
+        assert project.is_shared_with("anyone") is False
+
+
+class TestAssetLibraryCreate:
+    def test_create_video_library(self):
+        lib = AssetLibrary.create("proj1", "视频素材库", AssetLibraryKind.VIDEO)
+        assert lib.id is not None
+        assert len(lib.id) == 32
+        assert lib.project_id == "proj1"
+        assert lib.name == "视频素材库"
+        assert lib.kind == AssetLibraryKind.VIDEO
+        assert lib.asset_count == 0
+        assert lib.total_size == 0
+
+    def test_create_voice_library(self):
+        lib = AssetLibrary.create("proj1", "音乐库", AssetLibraryKind.VOICE)
+        assert lib.kind == AssetLibraryKind.VOICE
+
+    def test_create_image_library(self):
+        lib = AssetLibrary.create("proj1", "图片库", AssetLibraryKind.IMAGE)
+        assert lib.kind == AssetLibraryKind.IMAGE
+
+    def test_create_strips_name(self):
+        lib = AssetLibrary.create("p1", "  我的库  ", AssetLibraryKind.VIDEO)
+        assert lib.name == "我的库"
+
+    def test_create_empty_name(self):
+        with pytest.raises(ValueError, match="素材库名称不能为空"):
+            AssetLibrary.create("p1", "", AssetLibraryKind.VIDEO)
+
+    def test_create_whitespace_name(self):
+        with pytest.raises(ValueError, match="素材库名称不能为空"):
+            AssetLibrary.create("p1", "  \t  ", AssetLibraryKind.VIDEO)
+
+
+class TestAssetStatusEnum:
+    def test_basic_values(self):
+        assert AssetStatus.UPLOADING.value == "uploading"
+        assert AssetStatus.READY.value == "ready"
+        assert AssetStatus.PROCESSING.value == "processing"
+        assert AssetStatus.ERROR.value == "error"
+        assert AssetStatus.DELETED.value == "deleted"
+
+    def test_missing_uploaded_maps_to_ready(self):
+        assert AssetStatus("uploaded") == AssetStatus.READY
+
+    def test_missing_success_maps_to_ready(self):
+        assert AssetStatus("success") == AssetStatus.READY
+
+    def test_missing_ok_maps_to_ready(self):
+        assert AssetStatus("ok") == AssetStatus.READY
+
+    def test_missing_done_maps_to_ready(self):
+        assert AssetStatus("done") == AssetStatus.READY
+
+    def test_missing_complete_maps_to_ready(self):
+        assert AssetStatus("complete") == AssetStatus.READY
+
+    def test_missing_upload_maps_to_uploading(self):
+        assert AssetStatus("upload") == AssetStatus.UPLOADING
+
+    def test_missing_uploading_start_maps_to_uploading(self):
+        assert AssetStatus("uploading_start") == AssetStatus.UPLOADING
+
+    def test_missing_upload_start_maps_to_uploading(self):
+        assert AssetStatus("upload_start") == AssetStatus.UPLOADING
+
+    def test_missing_failed_maps_to_error(self):
+        assert AssetStatus("failed") == AssetStatus.ERROR
+
+    def test_missing_fail_maps_to_error(self):
+        assert AssetStatus("fail") == AssetStatus.ERROR
+
+    def test_missing_err_maps_to_error(self):
+        assert AssetStatus("err") == AssetStatus.ERROR
+
+    def test_missing_process_maps_to_processing(self):
+        assert AssetStatus("process") == AssetStatus.PROCESSING
+
+    def test_missing_running_maps_to_processing(self):
+        assert AssetStatus("running") == AssetStatus.PROCESSING
+
+    def test_missing_run_maps_to_processing(self):
+        assert AssetStatus("run") == AssetStatus.PROCESSING
+
+    def test_missing_unknown_value_falls_back_to_ready(self):
+        assert AssetStatus("completely_unknown_status") == AssetStatus.READY
+
+    def test_missing_empty_string_falls_back_to_ready(self):
+        assert AssetStatus("") == AssetStatus.READY
+
+    def test_missing_case_insensitive(self):
+        assert AssetStatus("UPLOADED") == AssetStatus.READY
+        assert AssetStatus("Success") == AssetStatus.READY
+        assert AssetStatus("FAILED") == AssetStatus.ERROR
+
+    def test_missing_with_whitespace(self):
+        assert AssetStatus("  uploaded  ") == AssetStatus.READY
+        assert AssetStatus("\tfailed\n") == AssetStatus.ERROR
+
+    def test_missing_non_string_value(self):
+        assert AssetStatus(None) == AssetStatus.READY
+        assert AssetStatus(123) == AssetStatus.READY
+
+    def test_known_values_still_work(self):
+        assert AssetStatus("uploading") == AssetStatus.UPLOADING
+        assert AssetStatus("ready") == AssetStatus.READY
+        assert AssetStatus("processing") == AssetStatus.PROCESSING
+        assert AssetStatus("error") == AssetStatus.ERROR
+        assert AssetStatus("deleted") == AssetStatus.DELETED
+
+
+class TestAssetCreate:
+    def test_create_minimal(self):
+        asset = Asset.create(
+            project_id="proj1",
+            library_id="lib1",
+            name="test.mp4",
+            storage_key="videos/test.mp4",
+            mime_type="video/mp4",
+        )
+        assert asset.id is not None
+        assert len(asset.id) == 32
+        assert asset.project_id == "proj1"
+        assert asset.library_id == "lib1"
+        assert asset.name == "test.mp4"
+        assert asset.storage_key == "videos/test.mp4"
+        assert asset.mime_type == "video/mp4"
+        assert asset.file_size == 0
+        assert asset.thumbnail_url is None
+        assert asset.duration is None
+        assert asset.width is None
+        assert asset.height is None
+        assert asset.status == AssetStatus.UPLOADING
+        assert asset.classification_status == ClassificationStatus.PENDING
+        assert asset.quality_score is None
+        assert asset.tag_ids == []
+        assert isinstance(asset.created_at, datetime)
+        assert isinstance(asset.updated_at, datetime)
+
+    def test_create_with_all_fields(self):
+        asset = Asset.create(
+            project_id="proj1",
+            library_id="lib1",
+            name="movie.mp4",
+            storage_key="v/m.mp4",
+            mime_type="video/mp4",
+            metadata={"key": "val"},
+            file_size=1024000,
+            thumbnail_url="http://cdn/thumb.jpg",
+            duration=120.5,
+            width=1920,
+            height=1080,
+            fps=30.0,
+            codec="h264",
+            status=AssetStatus.READY,
+            classification_status=ClassificationStatus.COMPLETED,
+            quality_score=0.85,
+            uploaded_by_user_id="user1",
+            file_hash="abc123",
+        )
+        assert asset.file_size == 1024000
+        assert asset.thumbnail_url == "http://cdn/thumb.jpg"
+        assert asset.duration == 120.5
+        assert asset.width == 1920
+        assert asset.height == 1080
+        assert asset.fps == 30.0
+        assert asset.codec == "h264"
+        assert asset.status == AssetStatus.READY
+        assert asset.classification_status == ClassificationStatus.COMPLETED
+        assert asset.quality_score == 0.85
+        assert asset.uploaded_by_user_id == "user1"
+        assert asset.file_hash == "abc123"
+        assert asset.metadata == {"key": "val"}
+
+    def test_create_strips_name(self):
+        asset = Asset.create("p1", "l1", "  test.mp4  ", "k", "video/mp4")
+        assert asset.name == "test.mp4"
+
+    def test_create_strips_storage_key(self):
+        asset = Asset.create("p1", "l1", "n", "  key.mp4  ", "video/mp4")
+        assert asset.storage_key == "key.mp4"
+
+    def test_create_strips_mime_type(self):
+        asset = Asset.create("p1", "l1", "n", "k", "  video/mp4  ")
+        assert asset.mime_type == "video/mp4"
+
+    def test_create_empty_name(self):
+        with pytest.raises(ValueError, match="素材名称不能为空"):
+            Asset.create("p1", "l1", "", "k", "video/mp4")
+
+    def test_create_empty_storage_key(self):
+        with pytest.raises(ValueError, match="storage_key 不能为空"):
+            Asset.create("p1", "l1", "n", "", "video/mp4")
+
+    def test_create_empty_mime_type(self):
+        with pytest.raises(ValueError, match="mime_type 不能为空"):
+            Asset.create("p1", "l1", "n", "k", "")
+
+    def test_create_whitespace_storage_key(self):
+        with pytest.raises(ValueError, match="storage_key 不能为空"):
+            Asset.create("p1", "l1", "n", "  \t  ", "video/mp4")
+
+    def test_create_none_metadata_defaults_to_empty_dict(self):
+        asset = Asset.create("p1", "l1", "n", "k", "video/mp4", metadata=None)
+        assert asset.metadata == {}
+
+    def test_create_unique_ids(self):
+        a1 = Asset.create("p1", "l1", "n1", "k1", "video/mp4")
+        a2 = Asset.create("p1", "l1", "n2", "k2", "video/mp4")
+        assert a1.id != a2.id
+
+
+class TestAssetFileType:
+    def test_video_mime(self):
+        asset = Asset.create("p1", "l1", "n", "k", "video/mp4")
+        assert asset.file_type == "video"
+
+    def test_audio_mime(self):
+        asset = Asset.create("p1", "l1", "n", "k", "audio/mpeg")
+        assert asset.file_type == "audio"
+
+    def test_image_mime(self):
+        asset = Asset.create("p1", "l1", "n", "k", "image/jpeg")
+        assert asset.file_type == "image"
+
+    def test_simple_mime_no_slash(self):
+        asset = Asset.create("p1", "l1", "n", "k", "application")
+        assert asset.file_type == "application"
+
+
+class TestAssetTags:
+    def test_add_tag(self):
+        asset = Asset.create("p1", "l1", "n", "k", "video/mp4")
+        asset.add_tag("tag1")
+        assert "tag1" in asset.tag_ids
+        assert len(asset.tag_ids) == 1
+
+    def test_add_tag_strips(self):
+        asset = Asset.create("p1", "l1", "n", "k", "video/mp4")
+        asset.add_tag("  tag_trim  ")
+        assert "tag_trim" in asset.tag_ids
+
+    def test_add_tag_duplicate_prevented(self):
+        asset = Asset.create("p1", "l1", "n", "k", "video/mp4")
+        asset.add_tag("tag1")
+        asset.add_tag("tag1")
+        assert asset.tag_ids.count("tag1") == 1
+        assert len(asset.tag_ids) == 1
+
+    def test_add_tag_empty(self):
+        asset = Asset.create("p1", "l1", "n", "k", "video/mp4")
+        with pytest.raises(ValueError, match="标签 ID 不能为空"):
+            asset.add_tag("")
+
+    def test_add_tag_whitespace(self):
+        asset = Asset.create("p1", "l1", "n", "k", "video/mp4")
+        with pytest.raises(ValueError, match="标签 ID 不能为空"):
+            asset.add_tag("   \t  ")
+
+    def test_add_multiple_tags(self):
+        asset = Asset.create("p1", "l1", "n", "k", "video/mp4")
+        asset.add_tag("t1")
+        asset.add_tag("t2")
+        asset.add_tag("t3")
+        assert asset.tag_ids == ["t1", "t2", "t3"]
+
+    def test_remove_tag(self):
+        asset = Asset.create("p1", "l1", "n", "k", "video/mp4")
+        asset.add_tag("t1")
+        asset.add_tag("t2")
+        asset.remove_tag("t1")
+        assert asset.tag_ids == ["t2"]
+
+    def test_remove_nonexistent_tag_idempotent(self):
+        asset = Asset.create("p1", "l1", "n", "k", "video/mp4")
+        asset.add_tag("t1")
+        # 删除不存在的标签不报错
+        asset.remove_tag("nonexistent")
+        assert asset.tag_ids == ["t1"]
+
+    def test_remove_tag_strips(self):
+        asset = Asset.create("p1", "l1", "n", "k", "video/mp4")
+        asset.add_tag("t1")
+        asset.remove_tag("  t1  ")
+        assert asset.tag_ids == []
+
+    def test_add_tag_updates_updated_at(self):
+        asset = Asset.create("p1", "l1", "n", "k", "video/mp4")
+        old_time = asset.updated_at
+        asset.add_tag("t1")
+        assert asset.updated_at >= old_time
+
+    def test_remove_tag_updates_updated_at(self):
+        asset = Asset.create("p1", "l1", "n", "k", "video/mp4")
+        asset.add_tag("t1")
+        old_time = asset.updated_at
+        asset.remove_tag("t1")
+        assert asset.updated_at >= old_time
+
+
+class TestIngestJobCreate:
+    def test_create_success(self):
+        job = IngestJob.create(
+            project_id="proj1",
+            library_id="lib1",
+            storage_key="videos/test.mp4",
+        )
+        assert job.id is not None
+        assert len(job.id) == 32
+        assert job.project_id == "proj1"
+        assert job.library_id == "lib1"
+        assert job.storage_key == "videos/test.mp4"
+        assert job.status == IngestJobStatus.PENDING
+        assert job.error_message == ""
+        assert job.result_asset_id == ""
+        assert job.file_hash == ""
+
+    def test_create_with_hash(self):
+        job = IngestJob.create("p1", "l1", "k", file_hash="abcdef123456")
+        assert job.file_hash == "abcdef123456"
+
+    def test_create_strips_project_id(self):
+        job = IngestJob.create("  p1  ", "l1", "k")
+        assert job.project_id == "p1"
+
+    def test_create_strips_library_id(self):
+        job = IngestJob.create("p1", "  l1  ", "k")
+        assert job.library_id == "l1"
+
+    def test_create_strips_storage_key(self):
+        job = IngestJob.create("p1", "l1", "  k  ")
+        assert job.storage_key == "k"
+
+    def test_create_strips_file_hash(self):
+        job = IngestJob.create("p1", "l1", "k", file_hash="  hash  ")
+        assert job.file_hash == "hash"
+
+    def test_create_empty_project_id(self):
+        with pytest.raises(ValueError, match="project_id 不能为空"):
+            IngestJob.create("", "l1", "k")
+
+    def test_create_empty_library_id(self):
+        with pytest.raises(ValueError, match="library_id 不能为空"):
+            IngestJob.create("p1", "", "k")
+
+    def test_create_empty_storage_key(self):
+        with pytest.raises(ValueError, match="storage_key 不能为空"):
+            IngestJob.create("p1", "l1", "")
+
+    def test_create_whitespace_project_id(self):
+        with pytest.raises(ValueError, match="project_id 不能为空"):
+            IngestJob.create("  \t  ", "l1", "k")
+
+    def test_create_unique_ids(self):
+        j1 = IngestJob.create("p1", "l1", "k1")
+        j2 = IngestJob.create("p1", "l1", "k2")
+        assert j1.id != j2.id
+
+
+class TestUserDataclass:
+    def test_default_values(self):
+        user = User(id="u1", email="test@example.com", display_name="Test User")
+        assert user.id == "u1"
+        assert user.email == "test@example.com"
+        assert user.display_name == "Test User"
+        assert user.username == ""
+        assert user.password_hash == ""
+        assert user.email_verified is False
+        assert user.subscription_plan == "free"
+        assert user.subscription_status == "active"
+        assert user.max_projects == 3
+        assert user.max_storage_gb == 10
+        assert user.used_storage_gb == 0.0
+        assert user.is_admin is False
+        assert user.wechat_openid is None
+        assert user.phone is None
+        assert user.phone_verified is False
+        assert isinstance(user.created_at, datetime)
+
+    def test_admin_user(self):
+        user = User(id="admin", email="admin@test.com", display_name="Admin", is_admin=True)
+        assert user.is_admin is True
+
+    def test_pro_subscription(self):
+        user = User(
+            id="u1",
+            email="u@t.com",
+            display_name="U",
+            subscription_plan="pro",
+            max_storage_gb=100,
+        )
+        assert user.subscription_plan == "pro"
+        assert user.max_storage_gb == 100

tests/unit/test_domain_small_modules.py

@@ -0,0 +1,391 @@
+"""Domain 小模块合集单元测试。
+
+覆盖零测试的小 domain 模块：
+- EditingMode 枚举
+- Template / TemplateSegment
+- TemplateClipConfig + ClipType + TransitionEffect
+- EditTemplateVersion
+- VoiceLibraryItem
+- TitleLibraryItem
+- Recipe / RecipeItem
+"""
+
+from datetime import datetime, timezone
+
+import pytest
+
+from packages.domain.editing_mode import EditingMode
+from packages.domain.recipe import RecipeItem
+from packages.domain.template import TemplateSegment
+from packages.domain.template_clip_config import (
+    ClipType,
+    TemplateClipConfig,
+    TransitionEffect,
+)
+from packages.domain.template_version import EditTemplateVersion
+from packages.domain.title_library import TitleLibraryItem
+from packages.domain.voice_library import VoiceLibraryItem
+
+
+class TestEditingMode:
+    def test_all_modes_exist(self):
+        assert EditingMode.ONE_TAKE.value == "one_take"
+        assert EditingMode.PIP.value == "pip"
+        assert EditingMode.VOICE_OVER.value == "voice_over"
+        assert EditingMode.VOICE_PIP.value == "voice_pip"
+
+    def test_from_string(self):
+        assert EditingMode("one_take") == EditingMode.ONE_TAKE
+        assert EditingMode("voice_over") == EditingMode.VOICE_OVER
+
+    def test_invalid_mode_raises(self):
+        with pytest.raises(ValueError):
+            EditingMode("invalid_mode")
+
+    def test_is_str_enum(self):
+        # StrEnum 的值是字符串，可以直接比较
+        assert EditingMode.ONE_TAKE == "one_take"
+
+
+class TestTemplateSegment:
+    def test_create_minimal(self):
+        seg = TemplateSegment(
+            id="seg1",
+            template_id="tpl1",
+            segment_order=1,
+            duration_min=5.0,
+            duration_max=10.0,
+        )
+        assert seg.id == "seg1"
+        assert seg.template_id == "tpl1"
+        assert seg.segment_order == 1
+        assert seg.duration_min == 5.0
+        assert seg.duration_max == 10.0
+        assert seg.material_type is None
+        assert isinstance(seg.created_at, datetime)
+
+    def test_create_with_material_type(self):
+        seg = TemplateSegment(
+            id="seg2",
+            template_id="tpl1",
+            segment_order=2,
+            duration_min=3.0,
+            duration_max=8.0,
+            material_type="人物",
+        )
+        assert seg.material_type == "人物"
+
+
+class TestClipType:
+    def test_basic_types_exist(self):
+        assert hasattr(ClipType, "MAIN")
+        assert hasattr(ClipType, "INTRO")
+        assert hasattr(ClipType, "OUTRO")
+        assert hasattr(ClipType, "TRANSITION")
+
+    def test_values_are_strings(self):
+        for ct in ClipType:
+            assert isinstance(ct.value, str)
+
+
+class TestTransitionEffect:
+    def test_effects_exist(self):
+        assert TransitionEffect.CUT.value == "cut"
+        assert TransitionEffect.FADE.value == "fade"
+        assert TransitionEffect.DISSOLVE.value == "dissolve"
+        # 至少有 5 种以上转场效果
+        assert len(list(TransitionEffect)) >= 5
+
+
+class TestTemplateClipConfig:
+    def test_create_minimal(self):
+        config = TemplateClipConfig.create(
+            template_id="tpl1",
+            clip_type=ClipType.MAIN,
+            order=1,
+            min_duration=3.0,
+            max_duration=8.0,
+        )
+        assert config.id is not None
+        assert config.template_id == "tpl1"
+        assert config.clip_type == ClipType.MAIN
+        assert config.order == 1
+        assert config.min_duration == 3.0
+        assert config.max_duration == 8.0
+
+    def test_create_with_string_type(self):
+        config = TemplateClipConfig.create(
+            template_id="tpl1",
+            clip_type="intro",
+            order=0,
+            min_duration=2.0,
+            max_duration=5.0,
+        )
+        assert config.clip_type == ClipType.INTRO
+
+    def test_has_duration_range_true(self):
+        config = TemplateClipConfig.create(
+            template_id="t1",
+            clip_type=ClipType.MAIN,
+            order=1,
+            min_duration=3.0,
+            max_duration=8.0,
+        )
+        assert config.has_duration_range is True
+
+    def test_has_duration_range_false_when_both_zero(self):
+        config = TemplateClipConfig.create(
+            template_id="t1",
+            clip_type=ClipType.MAIN,
+            order=1,
+        )
+        assert config.has_duration_range is False
+
+    def test_default_duration_midpoint(self):
+        config = TemplateClipConfig.create(
+            template_id="t1",
+            clip_type=ClipType.MAIN,
+            order=1,
+            min_duration=4.0,
+            max_duration=6.0,
+        )
+        assert config.default_duration == pytest.approx(5.0)
+
+    def test_default_duration_when_only_max(self):
+        config = TemplateClipConfig.create(
+            template_id="t1",
+            clip_type=ClipType.MAIN,
+            order=1,
+            max_duration=5.0,
+        )
+        assert config.default_duration == 5.0
+
+    def test_create_negative_min_duration_raises(self):
+        with pytest.raises(ValueError, match="min_duration"):
+            TemplateClipConfig.create(
+                template_id="t1",
+                clip_type=ClipType.MAIN,
+                order=1,
+                min_duration=-1.0,
+            )
+
+    def test_create_min_greater_than_max_raises(self):
+        with pytest.raises(ValueError, match="min_duration.*max_duration"):
+            TemplateClipConfig.create(
+                template_id="t1",
+                clip_type=ClipType.MAIN,
+                order=1,
+                min_duration=10.0,
+                max_duration=5.0,
+            )
+
+    def test_create_empty_template_id_raises(self):
+        with pytest.raises(ValueError, match="template_id"):
+            TemplateClipConfig.create(
+                template_id="",
+                clip_type=ClipType.MAIN,
+                order=1,
+            )
+
+    def test_default_transition_is_cut(self):
+        config = TemplateClipConfig.create(
+            template_id="t1",
+            clip_type=ClipType.MAIN,
+            order=1,
+        )
+        assert config.transition_effect == TransitionEffect.CUT
+
+    def test_custom_transition_effect(self):
+        config = TemplateClipConfig.create(
+            template_id="t1",
+            clip_type=ClipType.MAIN,
+            order=1,
+            transition_effect="fade",
+        )
+        assert config.transition_effect == TransitionEffect.FADE
+
+
+class TestEditTemplateVersion:
+    def test_create_minimal(self):
+        version = EditTemplateVersion.create(
+            template_id="tpl1",
+            version=1,
+        )
+        assert version.id is not None
+        assert len(version.id) == 32
+        assert version.template_id == "tpl1"
+        assert version.version == 1
+        assert version.config == {}
+        assert version.clip_configs == []
+        assert version.published_by == ""
+        assert version.change_note == ""
+        assert version.name == ""
+        assert version.editing_mode == "one_take"
+        assert isinstance(version.created_at, datetime)
+
+    def test_create_with_config_and_clip_configs(self):
+        version = EditTemplateVersion.create(
+            template_id="tpl1",
+            version=2,
+            config={"layout": "one_take"},
+            clip_configs=[{"clip_id": "c1", "type": "main"}],
+            published_by="user1",
+            change_note="添加了片头效果",
+        )
+        assert version.config == {"layout": "one_take"}
+        assert len(version.clip_configs) == 1
+        assert version.published_by == "user1"
+        assert version.change_note == "添加了片头效果"
+
+    def test_create_with_name_and_mode(self):
+        version = EditTemplateVersion.create(
+            template_id="t1",
+            version=1,
+            name="v1.0 正式版",
+            editing_mode="voice_over",
+        )
+        assert version.name == "v1.0 正式版"
+        assert version.editing_mode == "voice_over"
+
+    def test_create_unique_ids(self):
+        v1 = EditTemplateVersion.create("t1", 1)
+        v2 = EditTemplateVersion.create("t1", 2)
+        assert v1.id != v2.id
+
+    def test_none_config_defaults_to_empty_dict(self):
+        version = EditTemplateVersion.create("t1", 1, config=None)
+        assert version.config == {}
+
+    def test_none_clip_configs_defaults_to_empty_list(self):
+        version = EditTemplateVersion.create("t1", 1, clip_configs=None)
+        assert version.clip_configs == []
+
+
+class TestVoiceLibraryItem:
+    def test_create_minimal(self):
+        item = VoiceLibraryItem(
+            id="v1",
+            user_id="u1",
+            name="我的配音",
+        )
+        assert item.id == "v1"
+        assert item.user_id == "u1"
+        assert item.name == "我的配音"
+        assert item.text == ""
+        assert item.voice_provider == ""
+        assert item.duration == 0
+        assert item.status == "completed"
+        assert item.tags == []
+        assert item.project_id is None
+        assert isinstance(item.created_at, datetime)
+
+    def test_create_with_all_fields(self):
+        item = VoiceLibraryItem(
+            id="v2",
+            user_id="u1",
+            name="产品介绍",
+            text="欢迎来到我们的产品",
+            voice_provider="cosyvoice",
+            voice_id="voice_001",
+            voice_name="温柔女声",
+            audio_url="https://cdn/v2.mp3",
+            duration=30.5,
+            file_size=102400,
+            status="processing",
+            project_id="proj1",
+            tags=["产品", "介绍"],
+        )
+        assert item.text == "欢迎来到我们的产品"
+        assert item.voice_provider == "cosyvoice"
+        assert item.voice_id == "voice_001"
+        assert item.audio_url == "https://cdn/v2.mp3"
+        assert item.duration == 30.5
+        assert item.file_size == 102400
+        assert item.status == "processing"
+        assert item.project_id == "proj1"
+        assert item.tags == ["产品", "介绍"]
+
+
+class TestTitleLibraryItem:
+    def test_create_minimal(self):
+        item = TitleLibraryItem(
+            id="t1",
+            user_id="u1",
+            name="爆款标题1",
+            text="这是一个爆款标题",
+        )
+        assert item.id == "t1"
+        assert item.user_id == "u1"
+        assert item.name == "爆款标题1"
+        assert item.text == "这是一个爆款标题"
+        assert item.category == "default"
+        assert item.description == ""
+        assert item.tags == []
+        assert item.usage_count == 0
+        assert item.is_active is True
+
+    def test_create_with_category(self):
+        item = TitleLibraryItem(
+            id="t2",
+            user_id="u1",
+            name="美食标题",
+            text="太好吃了！",
+            category="美食",
+        )
+        assert item.category == "美食"
+
+    def test_inactive_item(self):
+        item = TitleLibraryItem(
+            id="t3",
+            user_id="u1",
+            name="旧标题",
+            text="旧文案",
+            is_active=False,
+        )
+        assert item.is_active is False
+
+    def test_usage_count_increment(self):
+        item = TitleLibraryItem(
+            id="t4",
+            user_id="u1",
+            name="T",
+            text="T",
+        )
+        item.usage_count += 1
+        assert item.usage_count == 1
+
+
+class TestRecipeItem:
+    def test_create_minimal(self):
+        item = RecipeItem(
+            id="ri1",
+            recipe_id="r1",
+            item_type="asset",
+            item_id="asset_001",
+        )
+        assert item.id == "ri1"
+        assert item.recipe_id == "r1"
+        assert item.item_type == "asset"
+        assert item.item_id == "asset_001"
+        assert item.position == 0
+        assert item.metadata_ == {}
+
+    def test_create_with_position_and_metadata(self):
+        item = RecipeItem(
+            id="ri2",
+            recipe_id="r1",
+            item_type="title",
+            item_id="title_001",
+            position=2,
+            metadata_={"style": "bold"},
+        )
+        assert item.position == 2
+        assert item.metadata_ == {"style": "bold"}
+
+    def test_item_types_variety(self):
+        asset_item = RecipeItem(id="a", recipe_id="r", item_type="asset", item_id="i1")
+        title_item = RecipeItem(id="t", recipe_id="r", item_type="title", item_id="i2")
+        voice_item = RecipeItem(id="v", recipe_id="r", item_type="voice", item_id="i3")
+        assert asset_item.item_type == "asset"
+        assert title_item.item_type == "title"
+        assert voice_item.item_type == "voice"

tests/unit/test_generation_plan_builder.py

@@ -15,7 +15,6 @@ from typing import Any
 from unittest.mock import patch
 
 import pytest
-
 from worker_app.tasks.generation_plan_builder import (
     VirtualClip,
     VirtualPlan,

tests/unit/test_job_domain.py

@@ -1,4 +1,6 @@
-"""Job 领域层单元测试 - job.py"""
+"""Job 领域模型单元测试。"""
+
+from datetime import datetime, timezone
 
 import pytest
 
@@ -10,45 +12,45 @@ from packages.domain.job import (
 )
 
 
-class TestJobType:
-    """JobType 枚举测试"""
+class TestJobTypeEnum:
+    def test_all_types_exist(self):
+        assert JobType.VIDEO_COMPOSE.value == "video_compose"
+        assert JobType.RENDER_EDIT_PLAN.value == "render_edit_plan"
+        assert JobType.ASSET_INGEST.value == "asset_ingest"
+        assert JobType.CLASSIFICATION.value == "classification"
+        assert JobType.VOICE_EXTRACTION.value == "voice_extraction"
+        assert JobType.GENERATION.value == "generation"
 
-    def test_all_types_have_values(self):
-        """所有枚举成员都有字符串值"""
-        for jt in JobType:
-            assert isinstance(jt.value, str)
-            assert jt.value
+    def test_from_string(self):
+        assert JobType("video_compose") == JobType.VIDEO_COMPOSE
+        assert JobType("generation") == JobType.GENERATION
 
-    def test_str_enum_behavior(self):
-        """是 str 枚举"""
-        assert JobType.VIDEO_COMPOSE == "video_compose"
-        assert isinstance(JobType.VIDEO_COMPOSE, str)
-
-    def test_known_types_exist(self):
-        """核心任务类型都存在"""
-        assert JobType.VIDEO_COMPOSE
-        assert JobType.RENDER_EDIT_PLAN
-        assert JobType.ASSET_INGEST
-        assert JobType.CLASSIFICATION
-        assert JobType.GENERATION
+    def test_invalid_type_raises(self):
+        with pytest.raises(ValueError):
+            JobType("invalid_type")
 
 
-class TestJobStatus:
-    """JobStatus 枚举测试"""
+class TestJobStatusEnum:
+    def test_all_statuses_exist(self):
+        assert JobStatus.PENDING.value == "pending"
+        assert JobStatus.RUNNING.value == "running"
+        assert JobStatus.SUCCESS.value == "success"
+        assert JobStatus.FAILED.value == "failed"
+        assert JobStatus.CANCELLED.value == "cancelled"
 
-    def test_all_statuses_have_values(self):
-        for js in JobStatus:
-            assert isinstance(js.value, str)
-            assert js.value
+    def test_from_string(self):
+        assert JobStatus("pending") == JobStatus.PENDING
+        assert JobStatus("success") == JobStatus.SUCCESS
 
-    def test_str_enum_behavior(self):
-        assert JobStatus.PENDING == "pending"
-        assert isinstance(JobStatus.PENDING, str)
 
-    def test_terminal_statuses(self):
-        """终态集合包含成功/失败/取消"""
+class TestTerminalStatuses:
+    def test_success_is_terminal(self):
         assert JobStatus.SUCCESS in TERMINAL_STATUSES
+
+    def test_failed_is_terminal(self):
         assert JobStatus.FAILED in TERMINAL_STATUSES
+
+    def test_cancelled_is_terminal(self):
         assert JobStatus.CANCELLED in TERMINAL_STATUSES
 
     def test_pending_not_terminal(self):
@@ -59,372 +61,376 @@ class TestJobStatus:
 
 
 class TestJobCreate:
-    """Job.create 工厂方法测试"""
-
-    def test_create_basic(self):
-        """基本创建"""
-        job = Job.create(
-            project_id="proj-1",
-            job_type=JobType.VIDEO_COMPOSE,
-        )
-        assert job.id
-        assert len(job.id) == 32  # uuid4 hex
-        assert job.project_id == "proj-1"
+    def test_create_minimal(self):
+        job = Job.create(project_id="proj1", job_type=JobType.VIDEO_COMPOSE)
+        assert job.id is not None
+        assert len(job.id) == 32
+        assert job.project_id == "proj1"
         assert job.job_type == JobType.VIDEO_COMPOSE
         assert job.status == JobStatus.PENDING
         assert job.progress == 0.0
+        assert job.current_stage == ""
         assert job.payload == {}
         assert job.result == {}
+        assert job.error_message == ""
         assert job.retry_count == 0
         assert job.max_retries == 3
-        assert job.created_at
-        assert job.updated_at
+        assert job.celery_task_id == ""
+        assert job.source_id == ""
+        assert job.created_by_user_id == ""
+        assert job.started_at is None
+        assert job.completed_at is None
+        assert isinstance(job.created_at, datetime)
+        assert isinstance(job.updated_at, datetime)
 
-    def test_create_with_string_job_type(self):
-        """用字符串创建任务类型"""
-        job = Job.create(
-            project_id="proj-1",
-            job_type="video_compose",
-        )
+    def test_create_with_enum_type(self):
+        job = Job.create("p1", JobType.GENERATION)
+        assert job.job_type == JobType.GENERATION
+
+    def test_create_with_string_type(self):
+        job = Job.create("p1", "video_compose")
         assert job.job_type == JobType.VIDEO_COMPOSE
 
-    def test_create_invalid_string_job_type_raises(self):
-        """无效的任务类型字符串抛 ValueError"""
-        with pytest.raises(ValueError, match="不支持的任务类型"):
-            Job.create(project_id="proj-1", job_type="invalid_type")
-
-    def test_create_empty_project_id_raises(self):
-        """空 project_id 抛 ValueError"""
-        with pytest.raises(ValueError, match="project_id 不能为空"):
-            Job.create(project_id="   ", job_type=JobType.VIDEO_COMPOSE)
-
     def test_create_with_payload(self):
-        """带 payload 创建"""
-        payload = {"video_id": "v1", "quality": "1080p"}
-        job = Job.create(
-            project_id="proj-1",
-            job_type=JobType.VIDEO_COMPOSE,
-            payload=payload,
-        )
+        payload = {"edit_plan_id": "plan123", "resolution": "1080p"}
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, payload=payload)
         assert job.payload == payload
 
-    def test_create_with_source_id(self):
-        """带 source_id 创建"""
-        job = Job.create(
-            project_id="proj-1",
-            job_type=JobType.VIDEO_COMPOSE,
-            source_id="plan-123",
-        )
-        assert job.source_id == "plan-123"
-
-    def test_create_with_created_by(self):
-        """带创建人"""
-        job = Job.create(
-            project_id="proj-1",
-            job_type=JobType.VIDEO_COMPOSE,
-            created_by_user_id="user-1",
-        )
-        assert job.created_by_user_id == "user-1"
-
-    def test_create_with_custom_max_retries(self):
-        """自定义最大重试次数"""
-        job = Job.create(
-            project_id="proj-1",
-            job_type=JobType.VIDEO_COMPOSE,
-            max_retries=5,
-        )
-        assert job.max_retries == 5
-
-    def test_create_project_id_stripped(self):
-        """project_id 会被 strip"""
-        job = Job.create(
-            project_id="  proj-1  ",
-            job_type=JobType.VIDEO_COMPOSE,
-        )
-        assert job.project_id == "proj-1"
-
-    def test_create_source_id_stripped(self):
-        job = Job.create(
-            project_id="proj-1",
-            job_type=JobType.VIDEO_COMPOSE,
-            source_id="  src-1  ",
-        )
-        assert job.source_id == "src-1"
-
-    def test_create_created_by_stripped(self):
-        job = Job.create(
-            project_id="proj-1",
-            job_type=JobType.VIDEO_COMPOSE,
-            created_by_user_id="  user-1  ",
-        )
-        assert job.created_by_user_id == "user-1"
-
-    def test_create_none_payload_defaults_to_empty_dict(self):
-        """payload=None 时默认为空 dict"""
-        job = Job.create(
-            project_id="proj-1",
-            job_type=JobType.VIDEO_COMPOSE,
-            payload=None,
-        )
+    def test_create_with_none_payload(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, payload=None)
         assert job.payload == {}
 
+    def test_create_with_source_id(self):
+        job = Job.create("p1", JobType.GENERATION, source_id="gen123")
+        assert job.source_id == "gen123"
 
-class TestJobIsTerminal:
-    """is_terminal 属性测试"""
+    def test_create_with_user_id(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, created_by_user_id="user1")
+        assert job.created_by_user_id == "user1"
 
+    def test_create_with_custom_max_retries(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, max_retries=5)
+        assert job.max_retries == 5
+
+    def test_create_strips_project_id(self):
+        job = Job.create("  proj1  ", JobType.VIDEO_COMPOSE)
+        assert job.project_id == "proj1"
+
+    def test_create_strips_source_id(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, source_id="  src1  ")
+        assert job.source_id == "src1"
+
+    def test_create_strips_user_id(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, created_by_user_id="  u1  ")
+        assert job.created_by_user_id == "u1"
+
+    def test_create_empty_project_id(self):
+        with pytest.raises(ValueError, match="project_id 不能为空"):
+            Job.create("", JobType.VIDEO_COMPOSE)
+
+    def test_create_whitespace_project_id(self):
+        with pytest.raises(ValueError, match="project_id 不能为空"):
+            Job.create("  \t  ", JobType.VIDEO_COMPOSE)
+
+    def test_create_invalid_job_type_string(self):
+        with pytest.raises(ValueError, match="不支持的任务类型"):
+            Job.create("p1", "invalid_type")
+
+    def test_create_unique_ids(self):
+        j1 = Job.create("p1", JobType.VIDEO_COMPOSE)
+        j2 = Job.create("p1", JobType.VIDEO_COMPOSE)
+        assert j1.id != j2.id
+
+
+class TestIsTerminal:
     def test_pending_not_terminal(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         assert job.is_terminal is False
 
     def test_running_not_terminal(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.transition_to(JobStatus.RUNNING)
         assert job.is_terminal is False
 
     def test_success_is_terminal(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.transition_to(JobStatus.RUNNING)
         job.transition_to(JobStatus.SUCCESS)
         assert job.is_terminal is True
 
     def test_failed_is_terminal(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.transition_to(JobStatus.RUNNING)
         job.transition_to(JobStatus.FAILED)
         assert job.is_terminal is True
 
     def test_cancelled_is_terminal(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.transition_to(JobStatus.CANCELLED)
         assert job.is_terminal is True
 
 
-class TestJobTransitions:
-    """状态转换测试"""
+class TestIsRetryable:
+    def test_pending_not_retryable(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        assert job.is_retryable is False
 
+    def test_running_not_retryable(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.transition_to(JobStatus.RUNNING)
+        assert job.is_retryable is False
+
+    def test_success_not_retryable(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.mark_running()
+        job.mark_success()
+        assert job.is_retryable is False
+
+    def test_failed_within_limit_is_retryable(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, max_retries=3)
+        job.mark_running()
+        job.mark_failed("error")
+        assert job.is_retryable is True
+
+    def test_failed_at_limit_not_retryable(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, max_retries=3)
+        job.mark_running()
+        job.mark_failed("error")
+        job.retry_count = 3  # 已达到上限
+        assert job.is_retryable is False
+
+    def test_failed_over_limit_not_retryable(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, max_retries=3)
+        job.retry_count = 5
+        job.status = JobStatus.FAILED
+        assert job.is_retryable is False
+
+    def test_zero_max_retries_not_retryable(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, max_retries=0)
+        job.status = JobStatus.FAILED
+        assert job.is_retryable is False
+
+
+class TestTransitionTo:
     def test_pending_to_running(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.transition_to(JobStatus.RUNNING)
         assert job.status == JobStatus.RUNNING
         assert job.started_at is not None
 
     def test_pending_to_success(self):
-        """pending 可以直接到 success（快速成功）"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.transition_to(JobStatus.SUCCESS)
         assert job.status == JobStatus.SUCCESS
         assert job.completed_at is not None
 
     def test_pending_to_cancelled(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.transition_to(JobStatus.CANCELLED)
         assert job.status == JobStatus.CANCELLED
 
-    def test_running_to_success(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        job.transition_to(JobStatus.RUNNING)
-        job.transition_to(JobStatus.SUCCESS)
-        assert job.status == JobStatus.SUCCESS
-        assert job.completed_at is not None
-
-    def test_running_to_failed(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        job.transition_to(JobStatus.RUNNING)
-        job.transition_to(JobStatus.FAILED)
-        assert job.status == JobStatus.FAILED
-        assert job.completed_at is not None
-
-    def test_running_to_cancelled(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        job.transition_to(JobStatus.RUNNING)
-        job.transition_to(JobStatus.CANCELLED)
-        assert job.status == JobStatus.CANCELLED
-
-    def test_failed_to_pending_retry(self):
-        """失败后可以回到 pending（重试）"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        job.transition_to(JobStatus.RUNNING)
-        job.transition_to(JobStatus.FAILED)
-        job.transition_to(JobStatus.PENDING)
-        assert job.status == JobStatus.PENDING
-
-    def test_invalid_transition_raises(self):
-        """非法状态转换抛 ValueError"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        # pending 不能直接到 failed
+    def test_pending_to_failed_invalid(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         with pytest.raises(ValueError, match="非法状态转换"):
             job.transition_to(JobStatus.FAILED)
 
-    def test_success_to_pending_raises(self):
-        """成功后不能回到 pending"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+    def test_running_to_success(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.transition_to(JobStatus.RUNNING)
+        job.transition_to(JobStatus.SUCCESS)
+        assert job.status == JobStatus.SUCCESS
+
+    def test_running_to_failed(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.transition_to(JobStatus.RUNNING)
+        job.transition_to(JobStatus.FAILED)
+        assert job.status == JobStatus.FAILED
+
+    def test_running_to_cancelled(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.transition_to(JobStatus.RUNNING)
+        job.transition_to(JobStatus.CANCELLED)
+        assert job.status == JobStatus.CANCELLED
+
+    def test_running_to_pending_invalid(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.transition_to(JobStatus.RUNNING)
+        with pytest.raises(ValueError, match="非法状态转换"):
+            job.transition_to(JobStatus.PENDING)
+
+    def test_failed_to_pending(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.transition_to(JobStatus.RUNNING)
+        job.transition_to(JobStatus.FAILED)
+        # 注意：_VALID_TRANSITIONS 中 FAILED → PENDING 是允许的
+        job.transition_to(JobStatus.PENDING)
+        assert job.status == JobStatus.PENDING
+
+    def test_success_to_anything_invalid(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.transition_to(JobStatus.RUNNING)
         job.transition_to(JobStatus.SUCCESS)
         with pytest.raises(ValueError):
-            job.transition_to(JobStatus.PENDING)
+            job.transition_to(JobStatus.FAILED)
+        with pytest.raises(ValueError):
+            job.transition_to(JobStatus.RUNNING)
 
     def test_transition_with_string_status(self):
-        """用字符串做状态转换"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.transition_to("running")
         assert job.status == JobStatus.RUNNING
 
-    def test_transition_invalid_string_raises(self):
-        """无效状态字符串抛 ValueError"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+    def test_transition_with_invalid_string(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         with pytest.raises(ValueError, match="无效状态"):
             job.transition_to("invalid_status")
 
     def test_transition_updates_updated_at(self):
-        """状态转换更新 updated_at"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        old_updated = job.updated_at
-        import time
-
-        time.sleep(0.001)
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        old_time = job.updated_at
         job.transition_to(JobStatus.RUNNING)
-        assert job.updated_at >= old_updated
+        assert job.updated_at >= old_time
 
     def test_started_at_only_set_once(self):
-        """started_at 只在第一次 RUNNING 时设置"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.transition_to(JobStatus.RUNNING)
-        first_started = job.started_at
-        job.transition_to(JobStatus.SUCCESS)
-        # 回到 pending 再 running（模拟重试场景，但started_at是None时才设置）
-        # 注意：正常重试是通过 prepare_retry 重置的
-        assert first_started is not None
+        first_start = job.started_at
+        # 再次 RUNNING 不合法，但我们测试 started_at 在多次 running→success→retry→running 时的行为
+        # 先失败重试
+        job.transition_to(JobStatus.FAILED)
+        job.transition_to(JobStatus.PENDING)
+        job.started_at = None  # 模拟 prepare_retry 的重置
+        job.transition_to(JobStatus.RUNNING)
+        assert job.started_at is not None
+        assert job.started_at != first_start
 
 
-class TestJobMarkMethods:
-    """便捷标记方法测试"""
-
-    def test_mark_running(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        job.mark_running("合成中")
-        assert job.status == JobStatus.RUNNING
-        assert job.current_stage == "合成中"
-
-    def test_mark_running_no_stage(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+class TestMarkRunning:
+    def test_mark_running_basic(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.mark_running()
         assert job.status == JobStatus.RUNNING
-        assert job.current_stage == ""
+        assert job.started_at is not None
 
-    def test_mark_success(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        job.mark_running()
-        job.mark_success({"output_url": "http://..."})
-        assert job.status == JobStatus.SUCCESS
-        assert job.progress == 100.0
-        assert job.current_stage == "完成"
-        assert job.result == {"output_url": "http://..."}
+    def test_mark_running_with_stage(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.mark_running(stage="下载素材")
+        assert job.status == JobStatus.RUNNING
+        assert job.current_stage == "下载素材"
 
-    def test_mark_success_no_result(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+    def test_mark_running_empty_stage_unchanged(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.current_stage = "已有阶段"
+        job.mark_running()  # 不传 stage
+        assert job.current_stage == "已有阶段"
+
+
+class TestMarkSuccess:
+    def test_mark_success_basic(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.mark_running()
         job.mark_success()
         assert job.status == JobStatus.SUCCESS
-        assert job.result == {}
+        assert job.progress == 100.0
+        assert job.current_stage == "完成"
+        assert job.completed_at is not None
 
-    def test_mark_failed(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+    def test_mark_success_with_result(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.mark_running()
+        result = {"video_url": "https://...", "duration": 30}
+        job.mark_success(result=result)
+        assert job.result == result
+
+    def test_mark_success_without_result(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.mark_running()
+        original_result = job.result.copy()
+        job.mark_success()
+        assert job.result == original_result  # 不变
+
+
+class TestMarkFailed:
+    def test_mark_failed_basic(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.mark_running()
         job.mark_failed("网络超时")
         assert job.status == JobStatus.FAILED
         assert job.error_message == "网络超时"
         assert job.current_stage == "失败"
+        assert job.completed_at is not None
 
-    def test_mark_cancelled(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+    def test_mark_failed_empty_message(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.mark_running()
+        job.mark_failed("")
+        assert job.error_message == ""
+
+
+class TestMarkCancelled:
+    def test_mark_cancelled_from_pending(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.mark_cancelled()
         assert job.status == JobStatus.CANCELLED
         assert job.current_stage == "已取消"
 
+    def test_mark_cancelled_from_running(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.mark_running()
+        job.mark_cancelled()
+        assert job.status == JobStatus.CANCELLED
 
-class TestJobProgress:
-    """进度更新测试"""
 
-    def test_update_progress(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        job.update_progress(50.0, "渲染中")
+class TestUpdateProgress:
+    def test_update_progress_valid(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.update_progress(50.0)
         assert job.progress == 50.0
-        assert job.current_stage == "渲染中"
 
     def test_update_progress_zero(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.update_progress(0.0)
         assert job.progress == 0.0
 
-    def test_update_progress_100(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+    def test_update_progress_hundred(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         job.update_progress(100.0)
         assert job.progress == 100.0
 
-    def test_update_progress_negative_raises(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+    def test_update_progress_negative(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         with pytest.raises(ValueError, match="进度必须在 0~100 之间"):
             job.update_progress(-1.0)
 
-    def test_update_progress_over_100_raises(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
+    def test_update_progress_over_100(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
         with pytest.raises(ValueError, match="进度必须在 0~100 之间"):
             job.update_progress(101.0)
 
-    def test_update_progress_without_stage(self):
-        """不传 stage 时不修改 current_stage"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        job.current_stage = "初始阶段"
-        job.update_progress(30.0)
+    def test_update_progress_with_stage(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.update_progress(30.0, stage="渲染中")
         assert job.progress == 30.0
-        assert job.current_stage == "初始阶段"
+        assert job.current_stage == "渲染中"
 
-    def test_update_progress_updates_updated_at(self):
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        old_updated = job.updated_at
-        import time
-
-        time.sleep(0.001)
+    def test_update_progress_without_stage_unchanged(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.current_stage = "原阶段"
         job.update_progress(50.0)
-        assert job.updated_at >= old_updated
+        assert job.current_stage == "原阶段"
+
+    def test_update_progress_updates_timestamp(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        old_time = job.updated_at
+        job.update_progress(25.0)
+        assert job.updated_at >= old_time
 
 
-class TestJobRetry:
-    """重试逻辑测试"""
-
-    def test_is_retryable_failed_within_limit(self):
-        """失败且未超过重试上限时可重试"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE, max_retries=3)
-        job.mark_running()
-        job.mark_failed("错误")
-        assert job.is_retryable is True
-
-    def test_is_retryable_failed_at_limit(self):
-        """达到重试上限时不可重试"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE, max_retries=1)
-        job.mark_running()
-        job.mark_failed("错误")
-        job.retry_count = 1
-        assert job.is_retryable is False
-
-    def test_is_retryable_pending_false(self):
-        """pending 状态不可重试"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        assert job.is_retryable is False
-
-    def test_is_retryable_success_false(self):
-        """成功状态不可重试"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        job.mark_running()
-        job.mark_success()
-        assert job.is_retryable is False
-
-    def test_prepare_retry(self):
-        """准备重试"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE, max_retries=3)
+class TestPrepareRetry:
+    def test_prepare_retry_success(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, max_retries=3)
         job.mark_running()
         job.mark_failed("网络错误")
-        job.celery_task_id = "task-123"
 
         job.prepare_retry()
 
@@ -437,38 +443,41 @@ class TestJobRetry:
         assert job.completed_at is None
         assert job.celery_task_id == ""
 
-    def test_prepare_retry_not_retryable_raises(self):
-        """不可重试时抛 ValueError"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE, max_retries=0)
+    def test_prepare_retry_increments_count(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, max_retries=5)
         job.mark_running()
-        job.mark_failed("错误")
-        with pytest.raises(ValueError, match="任务不可重试"):
-            job.prepare_retry()
+        job.mark_failed("err")
 
-    def test_prepare_retry_increments_correctly(self):
-        """多次重试计数正确"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE, max_retries=3)
-        job.mark_running()
-        job.mark_failed("错误1")
         job.prepare_retry()
         assert job.retry_count == 1
 
+        # 再次失败重试
         job.mark_running()
-        job.mark_failed("错误2")
+        job.mark_failed("err2")
         job.prepare_retry()
         assert job.retry_count == 2
 
+    def test_prepare_retry_not_retryable_raises(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, max_retries=0)
+        job.mark_running()
+        job.mark_failed("err")
+        with pytest.raises(ValueError, match="任务不可重试"):
+            job.prepare_retry()
 
-class TestJobToDict:
-    """to_dict 序列化测试"""
+    def test_prepare_retry_wrong_status_raises(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        with pytest.raises(ValueError, match="任务不可重试"):
+            job.prepare_retry()
 
-    def test_to_dict_contains_all_fields(self):
+
+class TestToDict:
+    def test_to_dict_structure(self):
         job = Job.create(
-            project_id="p1",
-            job_type=JobType.VIDEO_COMPOSE,
-            payload={"key": "value"},
-            source_id="src-1",
-            created_by_user_id="user-1",
+            "p1",
+            JobType.VIDEO_COMPOSE,
+            payload={"key": "val"},
+            source_id="src1",
+            created_by_user_id="u1",
         )
         d = job.to_dict()
         assert d["id"] == job.id
@@ -476,33 +485,39 @@ class TestJobToDict:
         assert d["job_type"] == "video_compose"
         assert d["status"] == "pending"
         assert d["progress"] == 0.0
-        assert d["payload"] == {"key": "value"}
-        assert d["source_id"] == "src-1"
-        assert d["created_by_user_id"] == "user-1"
+        assert d["current_stage"] == ""
+        assert d["payload"] == {"key": "val"}
+        assert d["result"] == {}
+        assert d["error_message"] == ""
+        assert d["retry_count"] == 0
+        assert d["max_retries"] == 3
+        assert d["celery_task_id"] == ""
+        assert d["source_id"] == "src1"
+        assert d["created_by_user_id"] == "u1"
         assert d["is_retryable"] is False
-
-    def test_to_dict_datetime_fields_are_strings(self):
-        """时间字段序列化为 ISO 字符串"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        d = job.to_dict()
-        assert isinstance(d["created_at"], str)
-        assert isinstance(d["updated_at"], str)
-
-    def test_to_dict_none_datetime_fields(self):
-        """未设置的时间字段为 None"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        d = job.to_dict()
         assert d["started_at"] is None
         assert d["completed_at"] is None
+        assert d["created_at"] is not None
+        assert d["updated_at"] is not None
 
     def test_to_dict_after_success(self):
-        """成功后 to_dict 状态正确"""
-        job = Job.create(project_id="p1", job_type=JobType.VIDEO_COMPOSE)
-        job.mark_running()
-        job.mark_success({"url": "http://..."})
+        job = Job.create("p1", JobType.VIDEO_COMPOSE)
+        job.mark_running("渲染")
+        job.mark_success({"url": "https://..."})
         d = job.to_dict()
         assert d["status"] == "success"
         assert d["progress"] == 100.0
-        assert d["result"] == {"url": "http://..."}
+        assert d["is_retryable"] is False
         assert d["started_at"] is not None
         assert d["completed_at"] is not None
+        assert isinstance(d["started_at"], str)
+        assert isinstance(d["completed_at"], str)
+
+    def test_to_dict_after_failed(self):
+        job = Job.create("p1", JobType.VIDEO_COMPOSE, max_retries=3)
+        job.mark_running()
+        job.mark_failed("timeout")
+        d = job.to_dict()
+        assert d["status"] == "failed"
+        assert d["error_message"] == "timeout"
+        assert d["is_retryable"] is True

tests/unit/test_media_validation.py

@@ -0,0 +1,299 @@
+"""media_validation 领域模块单元测试。"""
+
+import pytest
+
+from packages.domain.media_validation import (
+    MIN_AUDIO_FILE_SIZE,
+    MIN_IMAGE_FILE_SIZE,
+    MIN_VIDEO_FILE_SIZE,
+    SUPPORTED_VIDEO_CODECS,
+    is_valid_media,
+    safe_parse_fps,
+)
+
+
+class TestSafeParseFpsBasic:
+    def test_integer_fps(self):
+        assert safe_parse_fps("30") == 30.0
+
+    def test_decimal_fps(self):
+        assert safe_parse_fps("29.97") == pytest.approx(29.97)
+
+    def test_fraction_simple(self):
+        assert safe_parse_fps("30/1") == 30.0
+
+    def test_fraction_ntsc(self):
+        assert safe_parse_fps("30000/1001") == pytest.approx(29.97002997)
+
+    def test_fraction_pal(self):
+        assert safe_parse_fps("25/1") == 25.0
+
+    def test_fraction_24fps_cine(self):
+        assert safe_parse_fps("24000/1001") == pytest.approx(23.976023976)
+
+    def test_zero_fps(self):
+        assert safe_parse_fps("0") == 0.0
+
+    def test_zero_fraction(self):
+        assert safe_parse_fps("0/1") == 0.0
+
+
+class TestSafeParseFpsEdgeCases:
+    def test_zero_denominator(self):
+        assert safe_parse_fps("30/0") == 0.0
+
+    def test_empty_string(self):
+        assert safe_parse_fps("") == 0.0
+
+    def test_garbage_string(self):
+        assert safe_parse_fps("not_a_number") == 0.0
+
+    def test_multiple_slashes(self):
+        # split("/", 1) 只切第一个，后面的作为 den 的一部分会解析失败
+        assert safe_parse_fps("30/1/2") == 0.0
+
+    def test_negative_fps(self):
+        assert safe_parse_fps("-30") == -30.0
+
+    def test_negative_fraction(self):
+        assert safe_parse_fps("-30/1") == -30.0
+
+    def test_very_high_fps(self):
+        assert safe_parse_fps("240/1") == 240.0
+
+    def test_fraction_float_num(self):
+        assert safe_parse_fps("29.97/1") == pytest.approx(29.97)
+
+    def test_fraction_float_den(self):
+        assert safe_parse_fps("30/1.001") == pytest.approx(29.97002997)
+
+    def test_whitespace_in_string(self):
+        # float(" 30 ") 能解析，所以应该返回 30.0
+        assert safe_parse_fps(" 30 ") == 30.0
+
+
+class TestMinFileSizeConstants:
+    def test_min_video_size_is_1kb(self):
+        assert MIN_VIDEO_FILE_SIZE == 1024
+
+    def test_min_audio_size(self):
+        assert MIN_AUDIO_FILE_SIZE == 100
+
+    def test_min_image_size(self):
+        assert MIN_IMAGE_FILE_SIZE == 100
+
+
+class TestSupportedVideoCodecs:
+    def test_h264_family_present(self):
+        assert "h264" in SUPPORTED_VIDEO_CODECS
+        assert "avc1" in SUPPORTED_VIDEO_CODECS
+        assert "avc" in SUPPORTED_VIDEO_CODECS
+
+    def test_h265_family_present(self):
+        assert "hevc" in SUPPORTED_VIDEO_CODECS
+        assert "h265" in SUPPORTED_VIDEO_CODECS
+        assert "hev1" in SUPPORTED_VIDEO_CODECS
+        assert "hvc1" in SUPPORTED_VIDEO_CODECS
+
+    def test_vp9_av1_present(self):
+        assert "vp9" in SUPPORTED_VIDEO_CODECS
+        assert "vp09" in SUPPORTED_VIDEO_CODECS
+        assert "av1" in SUPPORTED_VIDEO_CODECS
+        assert "av01" in SUPPORTED_VIDEO_CODECS
+
+    def test_vp8_present(self):
+        assert "vp8" in SUPPORTED_VIDEO_CODECS
+        assert "vp08" in SUPPORTED_VIDEO_CODECS
+
+    def test_mpeg_family_present(self):
+        assert "mpeg4" in SUPPORTED_VIDEO_CODECS
+        assert "mp4v" in SUPPORTED_VIDEO_CODECS
+        assert "mpeg2video" in SUPPORTED_VIDEO_CODECS
+
+    def test_prores_family_present(self):
+        assert "prores" in SUPPORTED_VIDEO_CODECS
+        assert "apcn" in SUPPORTED_VIDEO_CODECS
+        assert "apch" in SUPPORTED_VIDEO_CODECS
+
+    def test_unknown_codec_not_present(self):
+        assert "unknown_codec_xyz" not in SUPPORTED_VIDEO_CODECS
+
+    def test_codecs_count_reasonable(self):
+        # 白名单应该有足够多的编码格式
+        assert len(SUPPORTED_VIDEO_CODECS) >= 30
+
+
+class TestIsValidMediaVideo:
+    def test_valid_video(self):
+        metadata = {"size_bytes": 5000, "duration": 10.0, "codec": "h264"}
+        assert is_valid_media(metadata, "video") is True
+
+    def test_video_too_small(self):
+        metadata = {"size_bytes": 500, "duration": 10.0, "codec": "h264"}
+        assert is_valid_media(metadata, "video") is False
+
+    def test_video_exact_min_size(self):
+        metadata = {"size_bytes": 1024, "duration": 10.0, "codec": "h264"}
+        assert is_valid_media(metadata, "video") is True
+
+    def test_video_zero_duration(self):
+        metadata = {"size_bytes": 5000, "duration": 0, "codec": "h264"}
+        assert is_valid_media(metadata, "video") is False
+
+    def test_video_negative_duration(self):
+        metadata = {"size_bytes": 5000, "duration": -1.0, "codec": "h264"}
+        assert is_valid_media(metadata, "video") is False
+
+    def test_video_missing_size_default_zero(self):
+        metadata = {"duration": 10.0, "codec": "h264"}
+        assert is_valid_media(metadata, "video") is False
+
+    def test_video_missing_duration_default_zero(self):
+        metadata = {"size_bytes": 5000, "codec": "h264"}
+        assert is_valid_media(metadata, "video") is False
+
+    def test_video_unknown_codec_still_valid(self):
+        # 非白名单编码仍允许通过（渲染层统一转码）
+        metadata = {"size_bytes": 5000, "duration": 10.0, "codec": "some_unknown_codec"}
+        assert is_valid_media(metadata, "video") is True
+
+    def test_video_missing_codec_still_valid(self):
+        metadata = {"size_bytes": 5000, "duration": 10.0}
+        assert is_valid_media(metadata, "video") is True
+
+    def test_video_codec_case_insensitive(self):
+        metadata = {"size_bytes": 5000, "duration": 10.0, "codec": "H264"}
+        assert is_valid_media(metadata, "video") is True
+
+    def test_video_empty_codec(self):
+        metadata = {"size_bytes": 5000, "duration": 10.0, "codec": ""}
+        assert is_valid_media(metadata, "video") is True
+
+    def test_video_hevc_codec(self):
+        metadata = {"size_bytes": 5000, "duration": 10.0, "codec": "hevc"}
+        assert is_valid_media(metadata, "video") is True
+
+    def test_video_vp9_codec(self):
+        metadata = {"size_bytes": 5000, "duration": 10.0, "codec": "vp9"}
+        assert is_valid_media(metadata, "video") is True
+
+    def test_video_av1_codec(self):
+        metadata = {"size_bytes": 5000, "duration": 10.0, "codec": "av1"}
+        assert is_valid_media(metadata, "video") is True
+
+    def test_video_prores_codec(self):
+        metadata = {"size_bytes": 5000, "duration": 10.0, "codec": "prores"}
+        assert is_valid_media(metadata, "video") is True
+
+    def test_video_empty_metadata(self):
+        assert is_valid_media({}, "video") is False
+
+
+class TestIsValidMediaAudio:
+    def test_valid_audio(self):
+        metadata = {"size_bytes": 5000, "duration": 30.0}
+        assert is_valid_media(metadata, "audio") is True
+
+    def test_audio_too_small(self):
+        metadata = {"size_bytes": 50, "duration": 30.0}
+        assert is_valid_media(metadata, "audio") is False
+
+    def test_audio_exact_min_size(self):
+        metadata = {"size_bytes": 100, "duration": 10.0}
+        assert is_valid_media(metadata, "audio") is True
+
+    def test_audio_zero_duration(self):
+        metadata = {"size_bytes": 5000, "duration": 0}
+        assert is_valid_media(metadata, "audio") is False
+
+    def test_audio_negative_duration(self):
+        metadata = {"size_bytes": 5000, "duration": -1.0}
+        assert is_valid_media(metadata, "audio") is False
+
+    def test_audio_missing_size(self):
+        metadata = {"duration": 10.0}
+        assert is_valid_media(metadata, "audio") is False
+
+    def test_audio_missing_duration(self):
+        metadata = {"size_bytes": 5000}
+        assert is_valid_media(metadata, "audio") is False
+
+    def test_audio_with_codec_info(self):
+        metadata = {"size_bytes": 5000, "duration": 30.0, "codec": "aac"}
+        assert is_valid_media(metadata, "audio") is True
+
+    def test_audio_empty_metadata(self):
+        assert is_valid_media({}, "audio") is False
+
+
+class TestIsValidMediaImage:
+    def test_valid_image(self):
+        metadata = {"size_bytes": 5000, "width": 1920, "height": 1080}
+        assert is_valid_media(metadata, "image") is True
+
+    def test_image_too_small(self):
+        metadata = {"size_bytes": 50, "width": 1920, "height": 1080}
+        assert is_valid_media(metadata, "image") is False
+
+    def test_image_exact_min_size(self):
+        metadata = {"size_bytes": 100, "width": 100, "height": 100}
+        assert is_valid_media(metadata, "image") is True
+
+    def test_image_zero_width(self):
+        metadata = {"size_bytes": 5000, "width": 0, "height": 1080}
+        assert is_valid_media(metadata, "image") is False
+
+    def test_image_zero_height(self):
+        metadata = {"size_bytes": 5000, "width": 1920, "height": 0}
+        assert is_valid_media(metadata, "image") is False
+
+    def test_image_negative_dimensions(self):
+        metadata = {"size_bytes": 5000, "width": -1, "height": 1080}
+        assert is_valid_media(metadata, "image") is False
+
+    def test_image_missing_width(self):
+        metadata = {"size_bytes": 5000, "height": 1080}
+        assert is_valid_media(metadata, "image") is False
+
+    def test_image_missing_height(self):
+        metadata = {"size_bytes": 5000, "width": 1920}
+        assert is_valid_media(metadata, "image") is False
+
+    def test_image_missing_size(self):
+        metadata = {"width": 1920, "height": 1080}
+        assert is_valid_media(metadata, "image") is False
+
+    def test_image_small_but_valid(self):
+        metadata = {"size_bytes": 100, "width": 1, "height": 1}
+        assert is_valid_media(metadata, "image") is True
+
+    def test_image_empty_metadata(self):
+        assert is_valid_media({}, "image") is False
+
+
+class TestIsValidMediaUnknownType:
+    def test_unknown_type_returns_false(self):
+        metadata = {"size_bytes": 5000, "duration": 10.0}
+        assert is_valid_media(metadata, "unknown") is False
+
+    def test_empty_type_returns_false(self):
+        metadata = {"size_bytes": 5000, "duration": 10.0}
+        assert is_valid_media(metadata, "") is False
+
+    def test_text_type_returns_false(self):
+        metadata = {"size_bytes": 5000}
+        assert is_valid_media(metadata, "text") is False
+
+
+class TestIsValidMediaSizeTypes:
+    def test_size_as_string(self):
+        # int("5000") 能解析
+        metadata = {"size_bytes": "5000", "duration": 10.0, "codec": "h264"}
+        assert is_valid_media(metadata, "video") is True
+
+    def test_size_as_none(self):
+        # int(None) 会 TypeError，但 metadata.get 返回 0 默认值
+        metadata = {"size_bytes": None, "duration": 10.0, "codec": "h264"}
+        # int(None) 会抛 TypeError
+        with pytest.raises(TypeError):
+            is_valid_media(metadata, "video")

tests/unit/test_plan_generator_utils.py

@@ -17,7 +17,6 @@ from packages.domain.plan_generator_utils import (
 )
 from packages.domain.template_clip_config import ClipType, TemplateClipConfig
 
-
 # ── 辅助函数 ──────────────────────────────────────────────────────────
 
 
@@ -184,11 +183,7 @@ class TestDistributeVoicePip:
 
     def test_three_assets_full_distribution(self):
         """3个素材：background + corner_voice + b_roll 各一个."""
-        clips = (
-            _make_clips(1, "background")
-            + _make_clips(1, "corner_voice")
-            + _make_clips(1, "b_roll")
-        )
+        clips = _make_clips(1, "background") + _make_clips(1, "corner_voice") + _make_clips(1, "b_roll")
         distribute_assets(clips, ["a1", "a2", "a3"], EditingMode.VOICE_PIP.value)
         bgs = [c for c in clips if c.clip_type == "background"]
         voices = [c for c in clips if c.clip_type == "corner_voice"]
@@ -199,11 +194,7 @@ class TestDistributeVoicePip:
 
     def test_single_asset_only_background(self):
         """1个素材：只分配给 background."""
-        clips = (
-            _make_clips(1, "background")
-            + _make_clips(1, "corner_voice")
-            + _make_clips(2, "b_roll")
-        )
+        clips = _make_clips(1, "background") + _make_clips(1, "corner_voice") + _make_clips(2, "b_roll")
         distribute_assets(clips, ["a1"], EditingMode.VOICE_PIP.value)
         assert clips[0].asset_id == "a1"
         assert clips[1].asset_id == ""
@@ -212,11 +203,7 @@ class TestDistributeVoicePip:
 
     def test_two_assets_bg_and_voice(self):
         """2个素材：background + corner_voice."""
-        clips = (
-            _make_clips(1, "background")
-            + _make_clips(1, "corner_voice")
-            + _make_clips(2, "b_roll")
-        )
+        clips = _make_clips(1, "background") + _make_clips(1, "corner_voice") + _make_clips(2, "b_roll")
         distribute_assets(clips, ["a1", "a2"], EditingMode.VOICE_PIP.value)
         bgs = [c for c in clips if c.clip_type == "background"]
         voices = [c for c in clips if c.clip_type == "corner_voice"]
@@ -227,11 +214,7 @@ class TestDistributeVoicePip:
 
     def test_many_broll_clips(self):
         """多个 b_roll clip：按顺序分配剩余素材."""
-        clips = (
-            _make_clips(1, "background")
-            + _make_clips(1, "corner_voice")
-            + _make_clips(5, "b_roll")
-        )
+        clips = _make_clips(1, "background") + _make_clips(1, "corner_voice") + _make_clips(5, "b_roll")
         distribute_assets(
             clips,
             ["a1", "a2", "a3", "a4", "a5"],
@@ -337,11 +320,7 @@ class TestMapClipTypesForMode:
 
     def test_non_main_clips_unchanged(self):
         """非 MAIN 类型 clip 不受影响."""
-        clips = (
-            _make_clips(1, "intro")
-            + _make_clips(3)  # main
-            + _make_clips(1, "outro")
-        )
+        clips = _make_clips(1, "intro") + _make_clips(3) + _make_clips(1, "outro")  # main
         map_clip_types_for_mode(clips, EditingMode.PIP.value)
         assert clips[0].clip_type == "intro"
         assert clips[1].clip_type == "main"  # 第1个 main

tests/unit/test_preset_bgm.py

@@ -0,0 +1,201 @@
+"""Preset BGM 预设背景音乐单元测试。"""
+
+import pytest
+
+from packages.domain.preset_bgm import (
+    BGM_STYLES,
+    PRESET_BGM_LIBRARY,
+    PresetBGM,
+    get_preset_bgm,
+    list_preset_bgm_by_style,
+    search_preset_bgm,
+)
+
+
+class TestPresetBGMDataclass:
+    def test_creation_required_fields(self):
+        bgm = PresetBGM(id="test_001", name="Test BGM", style="upbeat", duration=120.0)
+        assert bgm.id == "test_001"
+        assert bgm.name == "Test BGM"
+        assert bgm.style == "upbeat"
+        assert bgm.duration == 120.0
+        assert bgm.artist == ""
+        assert bgm.description == ""
+        assert bgm.tags == []
+        assert bgm.audio_url == ""
+
+    def test_creation_all_fields(self):
+        bgm = PresetBGM(
+            id="test_002",
+            name="Full BGM",
+            style="relax",
+            duration=180.5,
+            artist="Artist Name",
+            description="A test description",
+            tags=["tag1", "tag2"],
+            audio_url="https://cdn/test.mp3",
+        )
+        assert bgm.artist == "Artist Name"
+        assert bgm.description == "A test description"
+        assert bgm.tags == ["tag1", "tag2"]
+        assert bgm.audio_url == "https://cdn/test.mp3"
+
+    def test_frozen_immutable(self):
+        bgm = PresetBGM(id="t1", name="T", style="upbeat", duration=60.0)
+        with pytest.raises(Exception):  # FrozenInstanceError
+            bgm.name = "new name"
+
+    def test_equality(self):
+        bgm1 = PresetBGM(id="same", name="N", style="upbeat", duration=60.0)
+        bgm2 = PresetBGM(id="same", name="N", style="upbeat", duration=60.0)
+        assert bgm1 == bgm2
+
+    def test_inequality(self):
+        bgm1 = PresetBGM(id="a", name="A", style="upbeat", duration=60.0)
+        bgm2 = PresetBGM(id="b", name="B", style="upbeat", duration=60.0)
+        assert bgm1 != bgm2
+
+    def test_frozen_with_list_field_not_hashable(self):
+        # 包含 list 字段的 frozen dataclass 仍然不可哈希（list 不可哈希）
+        bgm = PresetBGM(id="h1", name="H", style="upbeat", duration=60.0, tags=["a"])
+        with pytest.raises(TypeError, match="unhashable"):
+            hash(bgm)
+
+
+class TestPresetBGMLibrary:
+    def test_library_not_empty(self):
+        assert len(PRESET_BGM_LIBRARY) > 0
+
+    def test_library_has_entries(self):
+        assert len(PRESET_BGM_LIBRARY) >= 10
+
+    def test_all_have_unique_ids(self):
+        ids = [bgm.id for bgm in PRESET_BGM_LIBRARY]
+        assert len(ids) == len(set(ids))
+
+    def test_all_have_valid_styles(self):
+        for bgm in PRESET_BGM_LIBRARY:
+            assert bgm.style in BGM_STYLES
+
+    def test_all_have_positive_duration(self):
+        for bgm in PRESET_BGM_LIBRARY:
+            assert bgm.duration > 0
+
+    def test_all_have_non_empty_name(self):
+        for bgm in PRESET_BGM_LIBRARY:
+            assert bgm.name.strip() != ""
+
+
+class TestBGMStyles:
+    def test_styles_dict_keys(self):
+        assert "upbeat" in BGM_STYLES
+        assert "relax" in BGM_STYLES
+        assert "tech" in BGM_STYLES
+        assert "commerce" in BGM_STYLES
+        assert "emotional" in BGM_STYLES
+        assert "cinematic" in BGM_STYLES
+
+    def test_styles_have_chinese_names(self):
+        for key, value in BGM_STYLES.items():
+            assert isinstance(value, str)
+            assert len(value) > 0
+
+
+class TestGetPresetBGM:
+    def test_get_existing(self):
+        bgm = get_preset_bgm("bgm_upbeat_001")
+        assert bgm is not None
+        assert bgm.id == "bgm_upbeat_001"
+        assert bgm.name == "阳光清晨"
+        assert bgm.style == "upbeat"
+
+    def test_get_nonexistent(self):
+        assert get_preset_bgm("nonexistent_id") is None
+
+    def test_get_empty_string(self):
+        assert get_preset_bgm("") is None
+
+    def test_get_returns_same_object(self):
+        bgm1 = get_preset_bgm("bgm_relax_001")
+        bgm2 = get_preset_bgm("bgm_relax_001")
+        assert bgm1 is bgm2  # 同一实例（引用同一列表中的对象）
+
+
+class TestListPresetBGMByStyle:
+    def test_list_upbeat(self):
+        results = list_preset_bgm_by_style("upbeat")
+        assert len(results) >= 3
+        for bgm in results:
+            assert bgm.style == "upbeat"
+
+    def test_list_relax(self):
+        results = list_preset_bgm_by_style("relax")
+        assert len(results) >= 3
+        for bgm in results:
+            assert bgm.style == "relax"
+
+    def test_list_tech(self):
+        results = list_preset_bgm_by_style("tech")
+        assert len(results) >= 2
+        for bgm in results:
+            assert bgm.style == "tech"
+
+    def test_list_commerce(self):
+        results = list_preset_bgm_by_style("commerce")
+        assert len(results) >= 2
+        for bgm in results:
+            assert bgm.style == "commerce"
+
+    def test_list_empty_style(self):
+        results = list_preset_bgm_by_style("nonexistent_style")
+        assert results == []
+
+    def test_list_preserves_order(self):
+        results = list_preset_bgm_by_style("upbeat")
+        ids = [b.id for b in results]
+        # 应该按照在列表中的出现顺序排列
+        assert ids == sorted(ids, key=lambda x: PRESET_BGM_LIBRARY.index(get_preset_bgm(x)))
+
+
+class TestSearchPresetBGM:
+    def test_search_by_name(self):
+        results = search_preset_bgm("阳光")
+        assert len(results) >= 1
+        assert any("阳光" in b.name for b in results)
+
+    def test_search_by_description(self):
+        results = search_preset_bgm("钢琴")
+        assert len(results) >= 1
+        # 钢琴出现在名称或描述或标签中
+        found = False
+        for b in results:
+            if "钢琴" in b.description or "钢琴" in b.name or "钢琴" in b.tags:
+                found = True
+                break
+        assert found
+
+    def test_search_by_tag(self):
+        results = search_preset_bgm("科技")
+        assert len(results) >= 1
+        found_tech = any(b.style == "tech" for b in results)
+        assert found_tech
+
+    def test_search_case_insensitive(self):
+        results1 = search_preset_bgm("Tech")
+        results2 = search_preset_bgm("tech")
+        assert len(results1) == len(results2)
+
+    def test_search_no_match(self):
+        results = search_preset_bgm("zzzzzzzzzzz_nonexistent_keyword")
+        assert results == []
+
+    def test_search_empty_keyword(self):
+        # 空字符串应该匹配所有（因为空字符串 in 任何字符串都是 True）
+        results = search_preset_bgm("")
+        assert len(results) == len(PRESET_BGM_LIBRARY)
+
+    def test_search_no_duplicates(self):
+        # 确保同一个 BGM 不会出现多次
+        results = search_preset_bgm("电子")
+        ids = [b.id for b in results]
+        assert len(ids) == len(set(ids))

tests/unit/test_quota_domain.py

@@ -1,13 +1,11 @@
-"""Quota 领域层单元测试 - quota.py"""
-
-import math
+"""Quota 配额系统单元测试。"""
 
 import pytest
 
 from packages.domain.quota import (
     QUOTA_TIERS,
-    QuotaChecker,
     QuotaCheckResult,
+    QuotaChecker,
     QuotaDimension,
     QuotaRegistry,
     QuotaTier,
@@ -19,103 +17,114 @@ from packages.domain.quota import (
 
 
 class TestQuotaDimension:
-    """QuotaDimension 枚举测试"""
+    def test_core_dimensions_exist(self):
+        assert QuotaDimension.STORAGE_GB.value == "storage_gb"
+        assert QuotaDimension.VIDEOS_PER_MONTH.value == "videos_per_month"
+        assert QuotaDimension.MAX_CONCURRENT.value == "max_concurrent"
+        assert QuotaDimension.MAX_TEMPLATES.value == "max_templates"
+        assert QuotaDimension.MAX_TITLES.value == "max_titles"
+        assert QuotaDimension.MAX_VOICEOVERS.value == "max_voiceovers"
+        assert QuotaDimension.AI_VOICE_ENABLED.value == "ai_voice_enabled"
 
-    def test_all_dimensions_have_values(self):
-        """所有枚举成员都有字符串值"""
+    def test_extended_dimensions_exist(self):
+        assert QuotaDimension.AI_VOICE_CREDITS.value == "ai_voice_credits"
+        assert QuotaDimension.BATCH_EXPORT_ENABLED.value == "batch_export_enabled"
+        assert QuotaDimension.MULTI_PLATFORM_ENABLED.value == "multi_platform_enabled"
+        assert QuotaDimension.DEDUP_REPORT_ENABLED.value == "dedup_report_enabled"
+
+    def test_all_dimensions_are_strings(self):
         for dim in QuotaDimension:
             assert isinstance(dim.value, str)
-            assert dim.value
-
-    def test_dimension_count(self):
-        """配额维度数量 >= 内置维度"""
-        # 至少有 storage_gb, videos_per_month, max_concurrent, max_templates 等
-        assert len(QuotaDimension) >= 7
-
-    def test_str_enum_behavior(self):
-        """是 str 枚举，可直接当字符串用"""
-        assert QuotaDimension.STORAGE_GB == "storage_gb"
-        assert isinstance(QuotaDimension.STORAGE_GB, str)
 
 
 class TestQuotaTier:
-    """QuotaTier 测试"""
-
     def test_get_limit_defined(self):
-        """已定义的维度返回正确值"""
-        tier = QuotaTier(name="test", limits={"storage": 10, "videos": 5})
-        assert tier.get_limit("storage") == 10
+        tier = QuotaTier(name="test", limits={"storage_gb": 10, "videos": 5})
+        assert tier.get_limit("storage_gb") == 10
         assert tier.get_limit("videos") == 5
 
     def test_get_limit_undefined_returns_zero(self):
-        """未定义的维度返回 0"""
-        tier = QuotaTier(name="test", limits={"storage": 10})
-        assert tier.get_limit("unknown") == 0
+        tier = QuotaTier(name="test", limits={"storage_gb": 10})
+        assert tier.get_limit("unknown_dim") == 0
 
-    def test_is_unlimited_true(self):
-        """不限量判断 - inf"""
+    def test_is_unlimited_false_for_finite(self):
+        tier = QuotaTier(name="test", limits={"storage_gb": 10})
+        assert tier.is_unlimited("storage_gb") is False
+
+    def test_is_unlimited_true_for_inf(self):
         tier = QuotaTier(name="test", limits={"templates": float("inf")})
         assert tier.is_unlimited("templates") is True
 
-    def test_is_unlimited_false(self):
-        """限量判断"""
-        tier = QuotaTier(name="test", limits={"storage": 10})
-        assert tier.is_unlimited("storage") is False
-
-    def test_is_unlimited_undefined_returns_true(self):
-        """未定义的维度默认 inf，is_unlimited 返回 True"""
+    def test_is_unlimited_undefined(self):
         tier = QuotaTier(name="test", limits={})
-        # get_limit 用 dict.get 默认 0，但 is_unlimited 用 dict.get 默认 inf
+        # 未定义的维度，limits.get 返回默认 inf，所以 is_unlimited 返回 True
         assert tier.is_unlimited("unknown") is True
 
+    def test_empty_limits(self):
+        tier = QuotaTier(name="empty")
+        assert tier.limits == {}
+        assert tier.name == "empty"
+
 
 class TestQuotaTiers:
-    """内置套餐配额测试"""
-
     def test_three_tiers_exist(self):
-        """三个套餐等级都存在"""
         assert "free" in QUOTA_TIERS
         assert "basic" in QUOTA_TIERS
         assert "premium" in QUOTA_TIERS
 
-    def test_free_tier_storage(self):
-        """free 套餐 2GB 存储"""
-        assert QUOTA_TIERS["free"].get_limit(QuotaDimension.STORAGE_GB) == 2
+    def test_free_tier_limits(self):
+        free = QUOTA_TIERS["free"]
+        assert free.get_limit("storage_gb") == 2
+        assert free.get_limit("videos_per_month") == 5
+        assert free.get_limit("max_concurrent") == 3
+        assert free.get_limit("max_templates") == 3
+        assert free.get_limit("max_titles") == 50
+        assert free.get_limit("max_voiceovers") == 10
+        assert free.get_limit("ai_voice_enabled") == 0
 
-    def test_basic_tier_storage(self):
-        """basic 套餐 20GB 存储"""
-        assert QUOTA_TIERS["basic"].get_limit(QuotaDimension.STORAGE_GB) == 20
+    def test_basic_tier_limits(self):
+        basic = QUOTA_TIERS["basic"]
+        assert basic.get_limit("storage_gb") == 20
+        assert basic.get_limit("videos_per_month") == 30
+        assert basic.get_limit("max_concurrent") == 10
+        assert basic.get_limit("max_templates") == 15
+        assert basic.get_limit("max_titles") == 500
+        assert basic.get_limit("max_voiceovers") == 100
+        assert basic.get_limit("ai_voice_enabled") == 1
+        assert basic.get_limit("ai_voice_credits") == 100
+        assert basic.get_limit("batch_export_enabled") == 1
 
-    def test_premium_tier_storage(self):
-        """premium 套餐 100GB 存储"""
-        assert QUOTA_TIERS["premium"].get_limit(QuotaDimension.STORAGE_GB) == 100
+    def test_premium_tier_limits(self):
+        premium = QUOTA_TIERS["premium"]
+        assert premium.get_limit("storage_gb") == 100
+        assert premium.get_limit("videos_per_month") == 100
+        assert premium.get_limit("max_concurrent") == 20
+        assert premium.is_unlimited("max_templates") is True
+        assert premium.get_limit("ai_voice_enabled") == 1
+        assert premium.get_limit("ai_voice_credits") == 500
+        assert premium.get_limit("batch_export_enabled") == 1
+        assert premium.get_limit("multi_platform_enabled") == 1
+        assert premium.get_limit("dedup_report_enabled") == 1
 
-    def test_free_no_ai_voice(self):
-        """free 套餐没有 AI 配音"""
-        assert QUOTA_TIERS["free"].get_limit(QuotaDimension.AI_VOICE_ENABLED) == 0
-
-    def test_basic_has_ai_voice(self):
-        """basic 套餐有 AI 配音"""
-        assert QUOTA_TIERS["basic"].get_limit(QuotaDimension.AI_VOICE_ENABLED) == 1
-
-    def test_premium_templates_unlimited(self):
-        """premium 套餐模板不限量"""
-        assert QUOTA_TIERS["premium"].is_unlimited(QuotaDimension.MAX_TEMPLATES) is True
-
-    def test_free_videos_per_month(self):
-        """free 每月 5 个视频"""
-        assert QUOTA_TIERS["free"].get_limit(QuotaDimension.VIDEOS_PER_MONTH) == 5
-
-    def test_premium_multi_platform_enabled(self):
-        """premium 支持多平台发布"""
-        assert QUOTA_TIERS["premium"].get_limit(QuotaDimension.MULTI_PLATFORM_ENABLED) == 1
+    def test_tier_increase_monotonic(self):
+        free = QUOTA_TIERS["free"]
+        basic = QUOTA_TIERS["basic"]
+        premium = QUOTA_TIERS["premium"]
+        # 高级套餐应该 >= 低级套餐的所有限制
+        for dim in [
+            "storage_gb",
+            "videos_per_month",
+            "max_concurrent",
+            "max_titles",
+            "max_voiceovers",
+            "ai_voice_credits",
+        ]:
+            assert basic.get_limit(dim) >= free.get_limit(dim)
+            assert premium.get_limit(dim) >= basic.get_limit(dim)
 
 
 class TestQuotaWarningLevel:
-    """告警级别常量测试"""
-
-    def test_level_values(self):
-        """四个告警级别都有定义"""
+    def test_levels_exist(self):
         assert QuotaWarningLevel.NORMAL == "normal"
         assert QuotaWarningLevel.WARNING == "warning"
         assert QuotaWarningLevel.CRITICAL == "critical"
@@ -123,302 +132,231 @@ class TestQuotaWarningLevel:
 
 
 class TestQuotaCheckResult:
-    """QuotaCheckResult 测试"""
-
     def test_usage_percent_normal(self):
-        """正常使用百分比计算"""
         result = QuotaCheckResult(
             allowed=True,
-            dimension="storage",
+            dimension="storage_gb",
             limit=100,
-            used=30,
-            remaining=70,
-            warning_level=QuotaWarningLevel.NORMAL,
+            used=50,
+            remaining=50,
+            warning_level="normal",
         )
-        assert result.usage_percent == 30.0
+        assert result.usage_percent == 50.0
 
-    def test_usage_percent_capped_at_100(self):
-        """超过 100% 时截断为 100%"""
+    def test_usage_percent_exceeded(self):
         result = QuotaCheckResult(
-            allowed=False,
-            dimension="storage",
-            limit=100,
-            used=150,
-            remaining=0,
-            warning_level=QuotaWarningLevel.EXCEEDED,
+            allowed=False, dimension="d", limit=100, used=150, remaining=0, warning_level="exceeded"
         )
-        assert result.usage_percent == 100.0
+        assert result.usage_percent == 100.0  # min(100, 150%)
+
+    def test_usage_percent_zero_used(self):
+        result = QuotaCheckResult(allowed=True, dimension="d", limit=100, used=0, remaining=100, warning_level="normal")
+        assert result.usage_percent == 0.0
 
     def test_usage_percent_zero_limit_with_usage(self):
-        """limit=0 但有使用量，返回 100%"""
-        result = QuotaCheckResult(
-            allowed=False,
-            dimension="storage",
-            limit=0,
-            used=5,
-            remaining=0,
-            warning_level=QuotaWarningLevel.EXCEEDED,
-        )
+        result = QuotaCheckResult(allowed=False, dimension="d", limit=0, used=10, remaining=0, warning_level="exceeded")
         assert result.usage_percent == 100.0
 
     def test_usage_percent_zero_limit_no_usage(self):
-        """limit=0 且无使用量，返回 0%"""
-        result = QuotaCheckResult(
-            allowed=True,
-            dimension="storage",
-            limit=0,
-            used=0,
-            remaining=0,
-            warning_level=QuotaWarningLevel.NORMAL,
-        )
+        result = QuotaCheckResult(allowed=True, dimension="d", limit=0, used=0, remaining=0, warning_level="normal")
         assert result.usage_percent == 0.0
 
     def test_usage_percent_unlimited(self):
-        """不限量时使用百分比为 0"""
         result = QuotaCheckResult(
             allowed=True,
-            dimension="templates",
+            dimension="d",
             limit=float("inf"),
-            used=50,
+            used=1000,
             remaining=float("inf"),
-            warning_level=QuotaWarningLevel.NORMAL,
+            warning_level="normal",
         )
         assert result.usage_percent == 0.0
 
 
 class TestQuotaRegistry:
-    """QuotaRegistry 测试"""
-
     def test_initial_dimensions(self):
-        """初始化时内置维度已注册"""
-        registry = QuotaRegistry()
-        dims = registry.list_dimensions()
-        assert QuotaDimension.STORAGE_GB in dims
-        assert QuotaDimension.VIDEOS_PER_MONTH in dims
+        reg = QuotaRegistry()
+        dims = reg.list_dimensions()
+        assert "storage_gb" in dims
+        assert "videos_per_month" in dims
+        assert len(dims) == len(QuotaDimension)
 
-    def test_initial_tiers(self):
-        """初始化时三个套餐已注册"""
-        registry = QuotaRegistry()
-        tiers = registry.list_tiers()
+    def test_list_tiers(self):
+        reg = QuotaRegistry()
+        tiers = reg.list_tiers()
         assert "free" in tiers
         assert "basic" in tiers
         assert "premium" in tiers
-
-    def test_register_new_dimension(self):
-        """注册新的配额维度"""
-        registry = QuotaRegistry()
-        registry.register_dimension("custom_dim", "自定义维度")
-        dims = registry.list_dimensions()
-        assert "custom_dim" in dims
-        assert dims["custom_dim"] == "自定义维度"
-
-    def test_register_dimension_idempotent(self):
-        """重复注册是幂等的"""
-        registry = QuotaRegistry()
-        registry.register_dimension("custom", "描述1")
-        registry.register_dimension("custom", "描述2")
-        # 保留第一次注册的描述
-        assert registry.list_dimensions()["custom"] == "描述1"
-
-    def test_register_with_default_limits(self):
-        """注册时指定各套餐的默认限制"""
-        registry = QuotaRegistry()
-        registry.register_dimension(
-            "custom",
-            "自定义",
-            default_limits={"free": 1, "basic": 10, "premium": 100},
-        )
-        assert registry.get_limit("free", "custom") == 1
-        assert registry.get_limit("basic", "custom") == 10
-        assert registry.get_limit("premium", "custom") == 100
-
-    def test_register_without_default_limits_defaults_to_zero(self):
-        """不指定默认限制时各套餐该维度为 0"""
-        registry = QuotaRegistry()
-        registry.register_dimension("custom_no_limit", "自定义")
-        assert registry.get_limit("free", "custom_no_limit") == 0
-        assert registry.get_limit("basic", "custom_no_limit") == 0
-
-    def test_register_default_limits_ignores_unknown_plan(self):
-        """默认限制中未知的套餐名被忽略"""
-        registry = QuotaRegistry()
-        registry.register_dimension(
-            "custom",
-            "自定义",
-            default_limits={"nonexistent": 999},
-        )
-        # 不报错，但也不会创建新套餐
-        assert registry.get_tier("nonexistent") is None
+        assert len(tiers) == 3
 
     def test_get_tier_existing(self):
-        """获取存在的套餐"""
-        registry = QuotaRegistry()
-        tier = registry.get_tier("free")
+        reg = QuotaRegistry()
+        tier = reg.get_tier("free")
         assert tier is not None
         assert tier.name == "free"
 
-    def test_get_tier_nonexistent(self):
-        """获取不存在的套餐返回 None"""
-        registry = QuotaRegistry()
-        assert registry.get_tier("enterprise") is None
+    def test_get_tier_unknown(self):
+        reg = QuotaRegistry()
+        assert reg.get_tier("unknown_plan") is None
 
-    def test_get_limit_existing(self):
-        """获取存在的套餐和维度的限制"""
-        registry = QuotaRegistry()
-        assert registry.get_limit("free", QuotaDimension.STORAGE_GB) == 2
+    def test_get_limit_known(self):
+        reg = QuotaRegistry()
+        assert reg.get_limit("free", "storage_gb") == 2
+        assert reg.get_limit("premium", "storage_gb") == 100
 
-    def test_get_limit_nonexistent_plan(self):
-        """不存在的套餐返回 0"""
-        registry = QuotaRegistry()
-        assert registry.get_limit("unknown", QuotaDimension.STORAGE_GB) == 0
+    def test_get_limit_unknown_plan(self):
+        reg = QuotaRegistry()
+        assert reg.get_limit("unknown", "storage_gb") == 0
 
-    def test_list_dimensions_returns_copy(self):
-        """list_dimensions 返回副本，修改不影响内部"""
-        registry = QuotaRegistry()
-        dims = registry.list_dimensions()
-        dims["fake"] = "fake"
-        assert "fake" not in registry.list_dimensions()
+    def test_register_new_dimension(self):
+        reg = QuotaRegistry()
+        reg.register_dimension("new_feature", "新功能", default_limits={"free": 0, "basic": 1, "premium": 5})
+        dims = reg.list_dimensions()
+        assert "new_feature" in dims
+        assert dims["new_feature"] == "新功能"
+        assert reg.get_limit("free", "new_feature") == 0
+        assert reg.get_limit("basic", "new_feature") == 1
+        assert reg.get_limit("premium", "new_feature") == 5
 
-    def test_list_tiers_returns_all_three(self):
-        """列出所有套餐"""
-        registry = QuotaRegistry()
-        tiers = registry.list_tiers()
-        assert len(tiers) == 3
-        assert set(tiers) == {"free", "basic", "premium"}
+    def test_register_dimension_idempotent(self):
+        reg = QuotaRegistry()
+        reg.register_dimension("storage_gb", "should not change", default_limits={"free": 999})
+        # 已经存在的不覆盖
+        assert reg.get_limit("free", "storage_gb") == 2
+
+    def test_register_without_defaults(self):
+        reg = QuotaRegistry()
+        reg.register_dimension("new_dim", "描述")
+        assert reg.get_limit("free", "new_dim") == 0
+        assert reg.get_limit("basic", "new_dim") == 0
+        assert reg.get_limit("premium", "new_dim") == 0
+
+    def test_register_partial_limits(self):
+        reg = QuotaRegistry()
+        reg.register_dimension("partial", "partial", default_limits={"premium": 42})
+        assert reg.get_limit("free", "partial") == 0  # 未设置的保持 0
+        assert reg.get_limit("premium", "partial") == 42
 
 
 class TestQuotaChecker:
-    """QuotaChecker 测试"""
-
-    def test_check_under_limit_allowed(self):
-        """使用量低于限制，允许"""
+    def test_check_within_limit(self):
         checker = QuotaChecker()
-        result = checker.check("free", QuotaDimension.STORAGE_GB, 1.0)
+        result = checker.check("free", "storage_gb", 1)
         assert result.allowed is True
-        assert result.remaining == 1.0
-        assert result.warning_level == QuotaWarningLevel.NORMAL
+        assert result.limit == 2
+        assert result.used == 1
+        assert result.remaining == 1
+        assert result.dimension == "storage_gb"
 
-    def test_check_at_limit_not_allowed(self):
-        """使用量等于限制，不允许（used < limit 判定）"""
+    def test_check_exceeded(self):
         checker = QuotaChecker()
-        result = checker.check("free", QuotaDimension.STORAGE_GB, 2.0)
+        result = checker.check("free", "storage_gb", 3)
         assert result.allowed is False
         assert result.remaining == 0
-        assert result.warning_level == QuotaWarningLevel.EXCEEDED
+        assert result.warning_level == "exceeded"
 
-    def test_check_over_limit(self):
-        """使用量超过限制"""
+    def test_check_exact_limit_not_allowed(self):
+        # used < limit 才 allowed，等于不算
         checker = QuotaChecker()
-        result = checker.check("free", QuotaDimension.STORAGE_GB, 3.0)
+        result = checker.check("free", "storage_gb", 2)
         assert result.allowed is False
         assert result.remaining == 0
-        assert result.warning_level == QuotaWarningLevel.EXCEEDED
 
-    def test_check_warning_level_80_percent(self):
-        """80% 触发 WARNING"""
+    def test_check_unlimited(self):
         checker = QuotaChecker()
-        # 100GB 的 80% = 80GB
-        result = checker.check("premium", QuotaDimension.STORAGE_GB, 80.0)
-        assert result.warning_level == QuotaWarningLevel.WARNING
+        result = checker.check("premium", "max_templates", 999999)
+        assert result.allowed is True
+        assert result.remaining == float("inf")
+        assert result.warning_level == "normal"
 
-    def test_check_warning_level_95_percent(self):
-        """95% 触发 CRITICAL"""
+    def test_check_warning_level_normal(self):
         checker = QuotaChecker()
-        result = checker.check("premium", QuotaDimension.STORAGE_GB, 95.0)
-        assert result.warning_level == QuotaWarningLevel.CRITICAL
+        result = checker.check("free", "storage_gb", 1)  # 50%
+        assert result.warning_level == "normal"
+
+    def test_check_warning_level_warning(self):
+        checker = QuotaChecker()
+        # 80% <= used < 95%
+        result = checker.check("free", "max_templates", 2.5)  # 2.5/3 = 83%
+        assert result.warning_level == "warning"
+
+    def test_check_warning_level_critical(self):
+        checker = QuotaChecker()
+        # 95% <= used < 100%
+        result = checker.check("free", "max_templates", 2.9)  # 2.9/3 = 97%
+        assert result.warning_level == "critical"
 
     def test_check_warning_level_exceeded(self):
-        """100% 及以上触发 EXCEEDED"""
         checker = QuotaChecker()
-        result = checker.check("premium", QuotaDimension.STORAGE_GB, 100.0)
-        assert result.warning_level == QuotaWarningLevel.EXCEEDED
-
-    def test_check_unlimited_always_allowed(self):
-        """不限量的维度始终允许"""
-        checker = QuotaChecker()
-        result = checker.check("premium", QuotaDimension.MAX_TEMPLATES, 9999)
-        assert result.allowed is True
-        assert math.isinf(result.remaining)
-        assert result.warning_level == QuotaWarningLevel.NORMAL
-
-    def test_check_unknown_plan_zero_limit(self):
-        """未知套餐限制为 0，used=0 时不允许（0 < 0 为 False）"""
-        checker = QuotaChecker()
-        result = checker.check("unknown", QuotaDimension.STORAGE_GB, 0)
-        assert result.limit == 0
-        assert result.allowed is False
+        result = checker.check("free", "storage_gb", 5)  # 250%
+        assert result.warning_level == "exceeded"
 
     def test_check_multiple(self):
-        """批量检查多个维度"""
         checker = QuotaChecker()
         results = checker.check_multiple(
             "free",
-            {
-                QuotaDimension.STORAGE_GB: 1.0,
-                QuotaDimension.VIDEOS_PER_MONTH: 3,
-            },
+            {"storage_gb": 1, "max_templates": 2, "max_titles": 10},
         )
-        assert len(results) == 2
+        assert len(results) == 3
+        assert results[0].dimension == "storage_gb"
+        assert results[1].dimension == "max_templates"
+        assert results[2].dimension == "max_titles"
         assert all(r.allowed for r in results)
-        dims = {r.dimension for r in results}
-        assert QuotaDimension.STORAGE_GB in dims
-        assert QuotaDimension.VIDEOS_PER_MONTH in dims
 
-    def test_check_with_custom_registry(self):
-        """使用自定义注册表"""
-        registry = QuotaRegistry()
-        registry.register_dimension("custom", "自定义", default_limits={"free": 5})
-        checker = QuotaChecker(registry)
-        result = checker.check("free", "custom", 3)
-        assert result.allowed is True
-        assert result.limit == 5
+    def test_check_zero_limit(self):
+        checker = QuotaChecker()
+        result = checker.check("free", "ai_voice_enabled", 0)
+        # limit=0, used=0: used < limit 为 False → allowed=False
+        assert result.allowed is False
+        assert result.remaining == 0
+        assert result.warning_level == "normal"
 
-    def test_compute_warning_level_zero_limit_no_usage(self):
-        """limit=0, used=0 → NORMAL"""
-        level = QuotaChecker._compute_warning_level(0, 0)
-        assert level == QuotaWarningLevel.NORMAL
+    def test_compute_warning_level_normal(self):
+        assert QuotaChecker._compute_warning_level(50, 100) == "normal"
+        assert QuotaChecker._compute_warning_level(79, 100) == "normal"
+
+    def test_compute_warning_level_warning_boundary(self):
+        assert QuotaChecker._compute_warning_level(80, 100) == "warning"
+        assert QuotaChecker._compute_warning_level(94, 100) == "warning"
+
+    def test_compute_warning_level_critical_boundary(self):
+        assert QuotaChecker._compute_warning_level(95, 100) == "critical"
+        assert QuotaChecker._compute_warning_level(99, 100) == "critical"
+
+    def test_compute_warning_level_exceeded(self):
+        assert QuotaChecker._compute_warning_level(100, 100) == "exceeded"
+        assert QuotaChecker._compute_warning_level(150, 100) == "exceeded"
+
+    def test_compute_warning_level_unlimited(self):
+        assert QuotaChecker._compute_warning_level(9999, float("inf")) == "normal"
 
     def test_compute_warning_level_zero_limit_with_usage(self):
-        """limit=0, used>0 → EXCEEDED"""
-        level = QuotaChecker._compute_warning_level(1, 0)
-        assert level == QuotaWarningLevel.EXCEEDED
+        assert QuotaChecker._compute_warning_level(1, 0) == "exceeded"
+
+    def test_compute_warning_level_zero_limit_no_usage(self):
+        assert QuotaChecker._compute_warning_level(0, 0) == "normal"
 
     def test_compute_warning_level_negative_limit(self):
-        """limit<0 视同 0 处理"""
-        level = QuotaChecker._compute_warning_level(1, -1)
-        assert level == QuotaWarningLevel.EXCEEDED
+        # limit <= 0 且 used=0 → NORMAL
+        assert QuotaChecker._compute_warning_level(0, -1) == "normal"
 
 
 class TestGetWarningLevel:
-    """get_warning_level 便捷函数测试"""
-
-    def test_normal(self):
-        assert get_warning_level(50, 100) == QuotaWarningLevel.NORMAL
-
-    def test_warning(self):
-        assert get_warning_level(85, 100) == QuotaWarningLevel.WARNING
-
-    def test_critical(self):
-        assert get_warning_level(97, 100) == QuotaWarningLevel.CRITICAL
-
-    def test_exceeded(self):
-        assert get_warning_level(100, 100) == QuotaWarningLevel.EXCEEDED
-
-    def test_unlimited(self):
-        assert get_warning_level(9999, float("inf")) == QuotaWarningLevel.NORMAL
+    def test_convenience_function(self):
+        assert get_warning_level(50, 100) == "normal"
+        assert get_warning_level(99, 100) == "critical"
+        assert get_warning_level(100, 100) == "exceeded"
+        assert get_warning_level(0, 0) == "normal"
+        assert get_warning_level(1, 0) == "exceeded"
 
 
 class TestGlobalSingletons:
-    """全局单例测试"""
-
     def test_quota_registry_is_instance(self):
         assert isinstance(quota_registry, QuotaRegistry)
 
     def test_quota_checker_is_instance(self):
         assert isinstance(quota_checker, QuotaChecker)
 
-    def test_global_checker_uses_global_registry(self):
-        """全局 checker 使用全局 registry"""
-        # 验证能正常工作
-        result = quota_checker.check("free", QuotaDimension.STORAGE_GB, 1.0)
+    def test_global_checker_works(self):
+        result = quota_checker.check("free", "storage_gb", 1)
         assert result.allowed is True

tests/unit/test_video_filter_builder.py

@@ -1,855 +0,0 @@
-"""video_filter_builder 单元测试 — FFmpeg 滤镜构建纯逻辑层。
-
-覆盖：
-- ClipFilterChain 数据类
-- 常量与映射表
-- build_clip_filter：单片段滤镜链
-- chain_filters：滤镜串联工具
-- has_audio：音频流判断
-- build_concat_filter：concat 滤镜
-- build_xfade_filter：xfade 转场滤镜
-- build_filter_complex：策略选择（空/单片段/concat/xfade）
-"""
-
-from __future__ import annotations
-
-import unittest
-
-from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
-from packages.domain.template_clip_config import TransitionEffect
-from packages.domain.video_filter_builder import (
-    DEFAULT_CLIP_DURATION,
-    DEFAULT_FPS,
-    DEFAULT_OUTPUT_HEIGHT,
-    DEFAULT_OUTPUT_WIDTH,
-    DEFAULT_TRANSITION_DURATION,
-    ClipFilterChain,
-    XFADE_TRANSITION_MAP,
-    build_clip_filter,
-    build_concat_filter,
-    build_filter_complex,
-    build_xfade_filter,
-    chain_filters,
-    has_audio,
-)
-
-# ── 辅助：构造 EditPlanClip ──────────────────────────────────────────────────
-
-
-def _make_clip(
-    clip_id: str = "clip-1",
-    duration: float = 5.0,
-    start_time: float = 0.0,
-    clip_type: str = "video",
-    asset_id: str | None = "asset-1",
-) -> EditPlanClip:
-    """构造一个测试用 EditPlanClip。"""
-    return EditPlanClip(
-        id=clip_id,
-        plan_id="plan-1",
-        asset_id=asset_id,
-        clip_type=clip_type,
-        duration=duration,
-        start_time=start_time,
-        order=0,
-        status=EditPlanClipStatus.READY,
-    )
-
-
-# ── ClipFilterChain 数据类测试 ──────────────────────────────────────────────
-
-
-class TestClipFilterChain(unittest.TestCase):
-    """ClipFilterChain 数据类测试。"""
-
-    def test_immutable(self):
-        """ClipFilterChain 是 frozen dataclass，不可修改。"""
-        chain = ClipFilterChain(
-            clip_id="c1",
-            input_index=0,
-            video_label="v0",
-            audio_label="a0",
-            filters=["scale=1280:720"],
-            duration=5.0,
-        )
-        with self.assertRaises(Exception):
-            chain.duration = 10.0  # type: ignore[misc]
-
-    def test_fields(self):
-        """所有字段正确存储。"""
-        chain = ClipFilterChain(
-            clip_id="c1",
-            input_index=2,
-            video_label="v2",
-            audio_label=None,
-            filters=["fps=25", "trim=0:3"],
-            duration=3.0,
-        )
-        self.assertEqual(chain.clip_id, "c1")
-        self.assertEqual(chain.input_index, 2)
-        self.assertEqual(chain.video_label, "v2")
-        self.assertIsNone(chain.audio_label)
-        self.assertEqual(chain.filters, ["fps=25", "trim=0:3"])
-        self.assertEqual(chain.duration, 3.0)
-
-
-# ── 常量测试 ────────────────────────────────────────────────────────────────
-
-
-class TestConstants(unittest.TestCase):
-    """常量与映射表测试。"""
-
-    def test_default_output_size(self):
-        """默认输出分辨率 1280x720。"""
-        self.assertEqual(DEFAULT_OUTPUT_WIDTH, 1280)
-        self.assertEqual(DEFAULT_OUTPUT_HEIGHT, 720)
-
-    def test_default_fps(self):
-        """默认帧率 25。"""
-        self.assertEqual(DEFAULT_FPS, 25)
-
-    def test_default_transition_duration(self):
-        """默认转场时长 0.5 秒。"""
-        self.assertEqual(DEFAULT_TRANSITION_DURATION, 0.5)
-
-    def test_default_clip_duration(self):
-        """默认片段时长 5 秒。"""
-        self.assertEqual(DEFAULT_CLIP_DURATION, 5.0)
-
-    def test_xfade_transition_map_keys(self):
-        """xfade 映射包含所有转场类型。"""
-        self.assertIn(TransitionEffect.FADE, XFADE_TRANSITION_MAP)
-        self.assertIn(TransitionEffect.SLIDE_LEFT, XFADE_TRANSITION_MAP)
-        self.assertIn(TransitionEffect.SLIDE_RIGHT, XFADE_TRANSITION_MAP)
-        self.assertIn(TransitionEffect.DISSOLVE, XFADE_TRANSITION_MAP)
-        self.assertIn(TransitionEffect.WIPE, XFADE_TRANSITION_MAP)
-
-    def test_xfade_transition_map_values(self):
-        """xfade 映射值为 FFmpeg 合法 transition 名称。"""
-        self.assertEqual(XFADE_TRANSITION_MAP[TransitionEffect.FADE], "fade")
-        self.assertEqual(XFADE_TRANSITION_MAP[TransitionEffect.SLIDE_LEFT], "slideleft")
-        self.assertEqual(XFADE_TRANSITION_MAP[TransitionEffect.SLIDE_RIGHT], "slideright")
-        self.assertEqual(XFADE_TRANSITION_MAP[TransitionEffect.DISSOLVE], "dissolve")
-        self.assertEqual(XFADE_TRANSITION_MAP[TransitionEffect.WIPE], "wipeleft")
-
-
-# ── chain_filters 测试 ──────────────────────────────────────────────────────
-
-
-class TestChainFilters(unittest.TestCase):
-    """chain_filters 滤镜串联工具测试。"""
-
-    def test_single_filter(self):
-        """单个滤镜。"""
-        result = chain_filters(["scale=1280:720"], "v0")
-        self.assertEqual(result, "[0:v]scale=1280:720[v0]")
-
-    def test_multiple_filters(self):
-        """多个滤镜用逗号串联。"""
-        result = chain_filters(["scale=1280:720", "fps=25", "trim=0:5"], "v1")
-        self.assertEqual(result, "[0:v]scale=1280:720,fps=25,trim=0:5[v1]")
-
-    def test_empty_filters(self):
-        """空滤镜列表。"""
-        result = chain_filters([], "v0")
-        self.assertEqual(result, "[0:v][v0]")
-
-    def test_custom_input_label(self):
-        """自定义输入标签。"""
-        result = chain_filters(["fps=30"], "out", input_label="v0")
-        self.assertEqual(result, "[v0]fps=30[out]")
-
-
-# ── has_audio 测试 ──────────────────────────────────────────────────────────
-
-
-class TestHasAudio(unittest.TestCase):
-    """has_audio 音频流判断测试。"""
-
-    def test_all_have_audio(self):
-        """所有片段都有音频。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", "a0", [], 5.0),
-            ClipFilterChain("c2", 1, "v1", "a1", [], 3.0),
-        ]
-        self.assertTrue(has_audio(chains))
-
-    def test_some_have_audio(self):
-        """部分片段有音频。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", "a0", [], 5.0),
-            ClipFilterChain("c2", 1, "v1", None, [], 3.0),
-        ]
-        self.assertTrue(has_audio(chains))
-
-    def test_none_have_audio(self):
-        """没有片段有音频。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, [], 5.0),
-            ClipFilterChain("c2", 1, "v1", None, [], 3.0),
-        ]
-        self.assertFalse(has_audio(chains))
-
-    def test_empty_list(self):
-        """空列表返回 False。"""
-        self.assertFalse(has_audio([]))
-
-
-# ── build_clip_filter 测试 ──────────────────────────────────────────────────
-
-
-class TestBuildClipFilter(unittest.TestCase):
-    """build_clip_filter 单片段滤镜链测试。"""
-
-    def test_basic_video_clip(self):
-        """普通视频片段生成完整滤镜链。"""
-        clip = _make_clip(duration=5.0, clip_type="video")
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-
-        self.assertEqual(chain.clip_id, "clip-1")
-        self.assertEqual(chain.input_index, 0)
-        self.assertEqual(chain.video_label, "v0")
-        self.assertEqual(chain.audio_label, "a0")
-        self.assertEqual(chain.duration, 5.0)
-        # 应有 7 个滤镜：scale, pad, format, fps, setpts, trim, setpts
-        self.assertEqual(len(chain.filters), 7)
-
-    def test_filter_order(self):
-        """滤镜顺序：scale → pad → format → fps → setpts → trim → setpts。"""
-        clip = _make_clip(duration=3.0, clip_type="video")
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-
-        self.assertTrue(chain.filters[0].startswith("scale="))
-        self.assertTrue(chain.filters[1].startswith("pad="))
-        self.assertEqual(chain.filters[2], "format=yuv420p")
-        self.assertTrue(chain.filters[3].startswith("fps="))
-        self.assertTrue(chain.filters[4].startswith("setpts="))
-        self.assertTrue(chain.filters[5].startswith("trim="))
-        self.assertEqual(chain.filters[6], "setpts=PTS-STARTPTS")
-
-    def test_scale_force_original_aspect_ratio(self):
-        """scale 使用 decrease 保持比例。"""
-        clip = _make_clip(duration=5.0)
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertIn("force_original_aspect_ratio=decrease", chain.filters[0])
-
-    def test_pad_centered_black(self):
-        """pad 居中 + 黑边。"""
-        clip = _make_clip(duration=5.0)
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertIn("(ow-iw)/2:(oh-ih)/2:black", chain.filters[1])
-
-    def test_format_yuv420p(self):
-        """像素格式统一为 yuv420p。"""
-        clip = _make_clip(duration=5.0)
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertEqual(chain.filters[2], "format=yuv420p")
-
-    def test_custom_resolution(self):
-        """自定义输出分辨率。"""
-        clip = _make_clip(duration=5.0)
-        chain = build_clip_filter(clip, 0, 1920, 1080, 30)
-        self.assertIn("scale=1920:1080", chain.filters[0])
-        self.assertIn("pad=1920:1080", chain.filters[1])
-        self.assertEqual(chain.filters[3], "fps=30")
-
-    def test_zero_duration_uses_default(self):
-        """duration <= 0 时使用默认时长。"""
-        clip = _make_clip(duration=0.0)
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertEqual(chain.duration, DEFAULT_CLIP_DURATION)
-        self.assertIn(f"trim=0:{DEFAULT_CLIP_DURATION}", chain.filters[5])
-
-    def test_negative_duration_uses_default(self):
-        """负时长也使用默认时长。"""
-        clip = _make_clip(duration=-1.0)
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertEqual(chain.duration, DEFAULT_CLIP_DURATION)
-
-    def test_start_time_offset(self):
-        """start_time > 0 时 setpts 带偏移。"""
-        clip = _make_clip(duration=3.0, start_time=2.0)
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertIn("PTS-STARTPTS+2.0/TB", chain.filters[4])
-
-    def test_zero_start_time_no_offset(self):
-        """start_time = 0 时 setpts 不带偏移。"""
-        clip = _make_clip(duration=3.0, start_time=0.0)
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertEqual(chain.filters[4], "setpts=PTS-STARTPTS")
-
-    def test_title_clip_no_audio(self):
-        """title 类型片段没有音频。"""
-        clip = _make_clip(clip_type="title")
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertIsNone(chain.audio_label)
-
-    def test_subtitle_clip_no_audio(self):
-        """subtitle 类型片段没有音频。"""
-        clip = _make_clip(clip_type="subtitle")
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertIsNone(chain.audio_label)
-
-    def test_video_clip_has_audio(self):
-        """video 类型片段有音频。"""
-        clip = _make_clip(clip_type="video")
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertEqual(chain.audio_label, "a0")
-
-    def test_image_clip_has_audio(self):
-        """image 类型片段有音频标签（可能有BGM）。"""
-        clip = _make_clip(clip_type="image")
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertIsNotNone(chain.audio_label)
-
-    def test_clip_type_case_insensitive(self):
-        """clip_type 大小写不敏感。"""
-        clip = _make_clip(clip_type="TITLE")
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertIsNone(chain.audio_label)
-
-    def test_empty_clip_type_has_audio(self):
-        """空 clip_type 默认有音频。"""
-        clip = _make_clip(clip_type="")
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertIsNotNone(chain.audio_label)
-
-    def test_input_index_reflected_in_labels(self):
-        """input_index 反映在 video_label 和 audio_label 中。"""
-        clip = _make_clip()
-        chain = build_clip_filter(clip, 3, 1280, 720, 25)
-        self.assertEqual(chain.video_label, "v3")
-        self.assertEqual(chain.audio_label, "a3")
-
-    def test_zero_fps_skipped(self):
-        """fps = 0 时跳过 fps 滤镜。"""
-        clip = _make_clip(duration=5.0)
-        chain = build_clip_filter(clip, 0, 1280, 720, 0)
-        # 少了 fps 滤镜：scale, pad, format, setpts, trim, setpts = 6个
-        self.assertEqual(len(chain.filters), 6)
-        self.assertFalse(any(f.startswith("fps=") for f in chain.filters))
-
-    def test_negative_fps_skipped(self):
-        """fps < 0 时也跳过 fps 滤镜。"""
-        clip = _make_clip(duration=5.0)
-        chain = build_clip_filter(clip, 0, 1280, 720, -1)
-        self.assertEqual(len(chain.filters), 6)
-
-    def test_trim_uses_duration(self):
-        """trim 时长等于 clip.duration。"""
-        clip = _make_clip(duration=7.5)
-        chain = build_clip_filter(clip, 0, 1280, 720, 25)
-        self.assertIn("trim=0:7.5", chain.filters[5])
-
-
-# ── build_concat_filter 测试 ────────────────────────────────────────────────
-
-
-class TestBuildConcatFilter(unittest.TestCase):
-    """build_concat_filter 拼接滤镜测试。"""
-
-    def test_empty_clips(self):
-        """空列表返回空字符串和 0 时长。"""
-        filter_str, duration = build_concat_filter([])
-        self.assertEqual(filter_str, "")
-        self.assertEqual(duration, 0.0)
-
-    def test_single_clip_no_audio(self):
-        """单片段无音频：视频滤镜 + concat(n=1)。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, ["scale=1280:720"], 5.0),
-        ]
-        filter_str, duration = build_concat_filter(chains)
-
-        self.assertIn("[0:v]scale=1280:720[v0]", filter_str)
-        self.assertIn("[v0]concat=n=1:v=1:a=0[outv]", filter_str)
-        self.assertEqual(duration, 5.0)
-        # 没有音频相关
-        self.assertNotIn("[outa]", filter_str)
-
-    def test_single_clip_with_audio(self):
-        """单片段有音频：视频 + 音频归一化 + concat。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", "a0", ["scale=1280:720"], 5.0),
-        ]
-        filter_str, duration = build_concat_filter(chains)
-
-        self.assertIn("[0:v]scale=1280:720[v0]", filter_str)
-        self.assertIn("[v0]concat=n=1:v=1:a=0[outv]", filter_str)
-        # 音频归一化
-        self.assertIn("[0:a]aformat=sample_rates=48000", filter_str)
-        self.assertIn("stereo:sample_fmts=fltp", filter_str)
-        self.assertIn("atrim=0:5.0", filter_str)
-        self.assertIn("[a0]", filter_str)
-        # 音频 concat（n=1）
-        self.assertIn("[a0]concat=n=1:v=0:a=1[outa]", filter_str)
-        self.assertEqual(duration, 5.0)
-
-    def test_two_clips_no_audio(self):
-        """两片段无音频：两个视频滤镜 + concat(n=2)。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, ["fps=25"], 5.0),
-            ClipFilterChain("c2", 1, "v1", None, ["fps=25"], 3.0),
-        ]
-        filter_str, duration = build_concat_filter(chains)
-
-        self.assertIn("[0:v]fps=25[v0]", filter_str)
-        self.assertIn("[1:v]fps=25[v1]", filter_str)
-        self.assertIn("[v0][v1]concat=n=2:v=1:a=0[outv]", filter_str)
-        self.assertEqual(duration, 8.0)
-
-    def test_two_clips_with_audio(self):
-        """两片段都有音频：视频 concat + 音频归一化 + 音频 concat。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", "a0", ["fps=25"], 5.0),
-            ClipFilterChain("c2", 1, "v1", "a1", ["fps=25"], 3.0),
-        ]
-        filter_str, duration = build_concat_filter(chains)
-
-        # 视频
-        self.assertIn("[v0][v1]concat=n=2:v=1:a=0[outv]", filter_str)
-        # 音频归一化
-        self.assertIn(
-            "[0:a]aformat=sample_rates=48000:channel_layouts=stereo:sample_fmts=fltp,atrim=0:5.0,asetpts=PTS-STARTPTS[a0]",
-            filter_str,
-        )
-        self.assertIn(
-            "[1:a]aformat=sample_rates=48000:channel_layouts=stereo:sample_fmts=fltp,atrim=0:3.0,asetpts=PTS-STARTPTS[a1]",
-            filter_str,
-        )
-        # 音频 concat
-        self.assertIn("[a0][a1]concat=n=2:v=0:a=1[outa]", filter_str)
-        self.assertEqual(duration, 8.0)
-
-    def test_mixed_audio_some_none(self):
-        """部分有音频部分没有：只有有音频的片段参与音频 concat。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", "a0", ["fps=25"], 5.0),
-            ClipFilterChain("c2", 1, "v1", None, ["fps=25"], 3.0),
-            ClipFilterChain("c3", 2, "v2", "a2", ["fps=25"], 4.0),
-        ]
-        filter_str, duration = build_concat_filter(chains)
-
-        # 视频 concat 有 3 个输入
-        self.assertIn("[v0][v1][v2]concat=n=3:v=1:a=0[outv]", filter_str)
-        # 音频 concat 只有 2 个输入
-        self.assertIn("[a0][a2]concat=n=2:v=0:a=1[outa]", filter_str)
-        # 片段 1 没有音频归一化
-        self.assertNotIn("[1:a]", filter_str)
-        self.assertEqual(duration, 12.0)
-
-    def test_three_clips_total_duration(self):
-        """三片段总时长为各片段之和。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, [], 2.0),
-            ClipFilterChain("c2", 1, "v1", None, [], 3.0),
-            ClipFilterChain("c3", 2, "v2", None, [], 4.0),
-        ]
-        _, duration = build_concat_filter(chains)
-        self.assertEqual(duration, 9.0)
-
-    def test_audio_format_normalization(self):
-        """音频归一化包含 aformat/atrim/asetpts。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", "a0", [], 5.0),
-        ]
-        filter_str, _ = build_concat_filter(chains)
-
-        self.assertIn("aformat=sample_rates=48000", filter_str)
-        self.assertIn("channel_layouts=stereo", filter_str)
-        self.assertIn("sample_fmts=fltp", filter_str)
-        self.assertIn("atrim=0:5.0", filter_str)
-        self.assertIn("asetpts=PTS-STARTPTS", filter_str)
-
-    def test_filter_parts_separated_by_semicolon(self):
-        """各滤镜部分用分号分隔。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", "a0", ["fps=25"], 5.0),
-            ClipFilterChain("c2", 1, "v1", "a1", ["fps=25"], 3.0),
-        ]
-        filter_str, _ = build_concat_filter(chains)
-        parts = filter_str.split(";")
-        # 2 视频 + 2 音频归一化 + 1 视频 concat + 1 音频 concat = 6
-        self.assertEqual(len(parts), 6)
-
-
-# ── build_xfade_filter 测试 ─────────────────────────────────────────────────
-
-
-class TestBuildXfadeFilter(unittest.TestCase):
-    """build_xfade_filter 转场滤镜测试。"""
-
-    def test_empty_clips(self):
-        """空列表返回空字符串和 0 时长。"""
-        filter_str, duration = build_xfade_filter([], 0.5, [])
-        self.assertEqual(filter_str, "")
-        self.assertEqual(duration, 0.0)
-
-    def test_single_clip_no_audio(self):
-        """单片段无音频：视频滤镜 + copy。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, ["scale=1280:720"], 5.0),
-        ]
-        filter_str, duration = build_xfade_filter(chains, 0.5, ["fade"])
-
-        self.assertIn("[0:v]scale=1280:720[v0]", filter_str)
-        self.assertIn("[v0]copy[outv]", filter_str)
-        self.assertEqual(duration, 5.0)
-        # 单片段 xfade 没有音频输出
-        self.assertNotIn("[outa]", filter_str)
-
-    def test_single_clip_with_audio(self):
-        """单片段有音频：xfade 路径下单片段不输出音频（与原实现一致）。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", "a0", ["scale=1280:720"], 5.0),
-        ]
-        filter_str, _ = build_xfade_filter(chains, 0.5, ["fade"])
-        # 单片段 xfade 没有音频输出
-        self.assertNotIn("[outa]", filter_str)
-        self.assertNotIn("acopy", filter_str)
-
-    def test_two_clips_fade_transition(self):
-        """两片段 fade 转场：xfade 滤镜结构正确。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, ["fps=25"], 5.0),
-            ClipFilterChain("c2", 1, "v1", None, ["fps=25"], 3.0),
-        ]
-        filter_str, duration = build_xfade_filter(chains, 0.5, ["cut", "fade"])
-
-        # 两个视频滤镜链
-        self.assertIn("[0:v]fps=25[v0]", filter_str)
-        self.assertIn("[1:v]fps=25[v1]", filter_str)
-        # xfade 转场
-        self.assertIn("xfade=transition=fade", filter_str)
-        self.assertIn(":duration=0.5", filter_str)
-        self.assertIn("[outv]", filter_str)
-        # 总时长 = 5 + 3 - 0.5 = 7.5
-        self.assertAlmostEqual(duration, 7.5)
-
-    def test_two_clips_offset_calculation(self):
-        """转场 offset = 第一个片段时长 - 转场时长。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, [], 5.0),
-            ClipFilterChain("c2", 1, "v1", None, [], 3.0),
-        ]
-        filter_str, _ = build_xfade_filter(chains, 0.5, ["cut", "fade"])
-
-        # offset = 5.0 - 0.5 * 1 = 4.5
-        self.assertIn(":offset=4.500", filter_str)
-
-    def test_three_clips_chain(self):
-        """三片段链式转场：两个 xfade，中间用 xf1 标签。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, [], 4.0),
-            ClipFilterChain("c2", 1, "v1", None, [], 3.0),
-            ClipFilterChain("c3", 2, "v2", None, [], 5.0),
-        ]
-        filter_str, duration = build_xfade_filter(chains, 0.5, ["cut", "fade", "dissolve"])
-
-        # 第一个转场输出到 xf1
-        self.assertIn("[xf1]", filter_str)
-        # 第二个转场输出到 outv
-        self.assertIn("[xf1][v2]xfade=transition=dissolve", filter_str)
-        self.assertIn("[outv]", filter_str)
-        # 总时长 = 4 + 3 + 5 - 0.5 * 2 = 11.0
-        self.assertAlmostEqual(duration, 11.0)
-
-    def test_three_clips_offsets(self):
-        """三片段两个转场的 offset 计算正确。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, [], 4.0),
-            ClipFilterChain("c2", 1, "v1", None, [], 3.0),
-            ClipFilterChain("c3", 2, "v2", None, [], 5.0),
-        ]
-        filter_str, _ = build_xfade_filter(chains, 0.5, ["cut", "fade", "slideleft"])
-
-        # 第一个 offset = 4.0 - 0.5*1 = 3.5
-        # 第二个 offset = (4.0+3.0) - 0.5*2 = 7.0 - 1.0 = 6.0
-        self.assertIn(":offset=3.500", filter_str)
-        self.assertIn(":offset=6.000", filter_str)
-
-    def test_all_transition_types(self):
-        """所有转场类型都能正确映射。"""
-        transitions = [
-            (TransitionEffect.FADE, "fade"),
-            (TransitionEffect.SLIDE_LEFT, "slideleft"),
-            (TransitionEffect.SLIDE_RIGHT, "slideright"),
-            (TransitionEffect.DISSOLVE, "dissolve"),
-            (TransitionEffect.WIPE, "wipeleft"),
-        ]
-        for effect, expected_name in transitions:
-            chains = [
-                ClipFilterChain("c1", 0, "v0", None, [], 3.0),
-                ClipFilterChain("c2", 1, "v1", None, [], 2.0),
-            ]
-            filter_str, _ = build_xfade_filter(chains, 0.5, ["cut", effect])
-            self.assertIn(
-                f"xfade=transition={expected_name}",
-                filter_str,
-                f"Transition {effect} should map to {expected_name}",
-            )
-
-    def test_unknown_transition_defaults_to_fade(self):
-        """未知转场类型默认使用 fade。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, [], 3.0),
-            ClipFilterChain("c2", 1, "v1", None, [], 2.0),
-        ]
-        filter_str, _ = build_xfade_filter(chains, 0.5, ["cut", "nonexistent"])
-        self.assertIn("xfade=transition=fade", filter_str)
-
-    def test_cut_still_uses_fade(self):
-        """cut 类型在 xfade 路径下也映射为 fade（因为走了 xfade 分支）。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, [], 3.0),
-            ClipFilterChain("c2", 1, "v1", None, [], 2.0),
-        ]
-        # 只要有一个非 cut 就走 xfade，cut 的那个也用 fade 作为默认
-        filter_str, _ = build_xfade_filter(chains, 0.5, ["fade", "cut"])
-        # 第二个转场是 cut，默认用 fade
-        self.assertIn("xfade=transition=fade", filter_str)
-
-    def test_transitions_shorter_than_clips(self):
-        """transitions 列表比 clip 短时，超出部分默认 cut→fade。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, [], 2.0),
-            ClipFilterChain("c2", 1, "v1", None, [], 2.0),
-            ClipFilterChain("c3", 2, "v2", None, [], 2.0),
-        ]
-        # 只给 1 个 transition（索引0），索引1和2会越界
-        filter_str, _ = build_xfade_filter(chains, 0.5, ["fade"])
-        # 应该有两个 xfade，都用 fade（第二个是默认值）
-        self.assertEqual(filter_str.count("xfade=transition=fade"), 2)
-
-    def test_zero_transition_duration(self):
-        """转场时长为 0 时不减时长。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, [], 5.0),
-            ClipFilterChain("c2", 1, "v1", None, [], 3.0),
-        ]
-        _, duration = build_xfade_filter(chains, 0.0, ["cut", "fade"])
-        self.assertAlmostEqual(duration, 8.0)
-
-    def test_total_duration_not_negative(self):
-        """总时长不会为负数。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, [], 0.1),
-            ClipFilterChain("c2", 1, "v1", None, [], 0.1),
-        ]
-        _, duration = build_xfade_filter(chains, 10.0, ["cut", "fade"])
-        self.assertGreaterEqual(duration, 0.0)
-
-    def test_two_clips_with_audio_normalize_and_concat(self):
-        """两片段都有音频：归一化 + concat。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", "a0", [], 5.0),
-            ClipFilterChain("c2", 1, "v1", "a1", [], 3.0),
-        ]
-        filter_str, _ = build_xfade_filter(chains, 0.5, ["cut", "fade"])
-
-        # 音频归一化（注意：xfade 路径用 audio_label 作为输入，与原实现一致）
-        self.assertIn(
-            "[a0]aformat=sample_rates=48000:channel_layouts=stereo:sample_fmts=fltp,atrim=0:5.0,asetpts=PTS-STARTPTS[anorm_v0]",
-            filter_str,
-        )
-        self.assertIn(
-            "[a1]aformat=sample_rates=48000:channel_layouts=stereo:sample_fmts=fltp,atrim=0:3.0,asetpts=PTS-STARTPTS[anorm_v1]",
-            filter_str,
-        )
-        # 音频 concat
-        self.assertIn("[anorm_v0][anorm_v1]concat=n=2:v=0:a=1[outa]", filter_str)
-
-    def test_single_audio_in_xfade_acopy(self):
-        """xfade 路径下只有一个音频片段时直接 acopy。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", "a0", [], 5.0),
-            ClipFilterChain("c2", 1, "v1", None, [], 3.0),
-        ]
-        filter_str, _ = build_xfade_filter(chains, 0.5, ["cut", "fade"])
-
-        self.assertIn("[a0]acopy[outa]", filter_str)
-        # 没有音频归一化
-        self.assertNotIn("aformat", filter_str)
-        self.assertNotIn("concat=n=", filter_str)
-
-    def test_no_audio_in_xfade(self):
-        """xfade 路径下都没有音频时没有 outa。"""
-        chains = [
-            ClipFilterChain("c1", 0, "v0", None, [], 5.0),
-            ClipFilterChain("c2", 1, "v1", None, [], 3.0),
-        ]
-        filter_str, _ = build_xfade_filter(chains, 0.5, ["cut", "fade"])
-        self.assertNotIn("[outa]", filter_str)
-        self.assertNotIn("acopy", filter_str)
-
-
-# ── build_filter_complex 测试 ───────────────────────────────────────────────
-
-
-class TestBuildFilterComplex(unittest.TestCase):
-    """build_filter_complex 策略选择测试。"""
-
-    def _chain(self, idx: int, has_audio: bool = True) -> ClipFilterChain:
-        return ClipFilterChain(
-            clip_id=f"c{idx}",
-            input_index=idx,
-            video_label=f"v{idx}",
-            audio_label=f"a{idx}" if has_audio else None,
-            filters=["fps=25"],
-            duration=3.0,
-        )
-
-    def test_empty_clips(self):
-        """空列表返回空字符串和 0 时长。"""
-        filter_str, duration = build_filter_complex([], 1280, 720, 0.5, [])
-        self.assertEqual(filter_str, "")
-        self.assertEqual(duration, 0.0)
-
-    def test_single_clip_direct_output(self):
-        """单片段：直接输出单链滤镜。"""
-        chains = [self._chain(0)]
-        filter_str, duration = build_filter_complex(chains, 1280, 720, 0.5, [])
-
-        self.assertIn("[0:v]fps=25[v0]", filter_str)
-        self.assertNotIn("concat", filter_str)
-        self.assertNotIn("xfade", filter_str)
-        self.assertEqual(duration, 3.0)
-
-    def test_single_clip_audio_passthrough(self):
-        """单片段有音频：音频直通标签。"""
-        chains = [self._chain(0, has_audio=True)]
-        filter_str, _ = build_filter_complex(chains, 1280, 720, 0.5, [])
-        # 单片段音频：[0:a]a0（直通标签）
-        self.assertIn("[0:a]a0", filter_str)
-
-    def test_single_clip_no_audio(self):
-        """单片段无音频：没有音频部分。"""
-        chains = [self._chain(0, has_audio=False)]
-        filter_str, _ = build_filter_complex(chains, 1280, 720, 0.5, [])
-        self.assertNotIn("[0:a]", filter_str)
-        self.assertNotIn("[outa]", filter_str)
-
-    def test_multiple_all_cut_uses_concat(self):
-        """多片段 + 全 cut：使用 concat 滤镜。"""
-        chains = [self._chain(0), self._chain(1), self._chain(2)]
-        transitions = [TransitionEffect.CUT, TransitionEffect.CUT, TransitionEffect.CUT]
-        filter_str, duration = build_filter_complex(chains, 1280, 720, 0.5, transitions)
-
-        self.assertIn("concat=n=3:v=1:a=0[outv]", filter_str)
-        self.assertNotIn("xfade", filter_str)
-        self.assertEqual(duration, 9.0)
-
-    def test_multiple_one_transition_uses_xfade(self):
-        """多片段 + 有一个非 cut 转场：使用 xfade。"""
-        chains = [self._chain(0), self._chain(1)]
-        transitions = [TransitionEffect.CUT, TransitionEffect.FADE]
-        filter_str, duration = build_filter_complex(chains, 1280, 720, 0.5, transitions)
-
-        self.assertIn("xfade=transition=fade", filter_str)
-        self.assertNotIn("concat=n=2:v=1:a=0", filter_str)
-        self.assertAlmostEqual(duration, 5.5)  # 3 + 3 - 0.5
-
-    def test_string_cut_value(self):
-        """字符串 'cut' 也被识别为无转场。"""
-        chains = [self._chain(0), self._chain(1)]
-        transitions = ["cut", "cut"]
-        filter_str, _ = build_filter_complex(chains, 1280, 720, 0.5, transitions)
-        self.assertIn("concat=n=2:v=1:a=0[outv]", filter_str)
-        self.assertNotIn("xfade", filter_str)
-
-    def test_mixed_cut_and_transition(self):
-        """混合 cut 和转场：走 xfade 路径。"""
-        chains = [self._chain(0), self._chain(1), self._chain(2)]
-        transitions = ["cut", TransitionEffect.FADE, "cut"]
-        filter_str, _ = build_filter_complex(chains, 1280, 720, 0.5, transitions)
-        self.assertIn("xfade", filter_str)
-
-    def test_all_dissolve_transition(self):
-        """全部 dissolve 转场。"""
-        chains = [self._chain(0), self._chain(1)]
-        transitions = [TransitionEffect.CUT, TransitionEffect.DISSOLVE]
-        filter_str, _ = build_filter_complex(chains, 1280, 720, 0.5, transitions)
-        self.assertIn("xfade=transition=dissolve", filter_str)
-
-
-# ── 集成测试：build_clip_filter + build_filter_complex 端到端 ────────────────
-
-
-class TestEndToEndFilterBuilding(unittest.TestCase):
-    """端到端集成测试：从 EditPlanClip 到完整 filter_complex。"""
-
-    def test_two_video_clips_concat(self):
-        """两个视频片段走 concat 路径的完整流程。"""
-        clip1 = _make_clip("c1", duration=5.0, clip_type="video")
-        clip2 = _make_clip("c2", duration=3.0, clip_type="video")
-
-        chain1 = build_clip_filter(clip1, 0, 1280, 720, 25)
-        chain2 = build_clip_filter(clip2, 1, 1280, 720, 25)
-
-        filter_str, duration = build_filter_complex(
-            [chain1, chain2],
-            1280,
-            720,
-            0.5,
-            [TransitionEffect.CUT, TransitionEffect.CUT],
-        )
-
-        # 有两个视频滤镜链
-        self.assertIn("[0:v]", filter_str)
-        self.assertIn("[1:v]", filter_str)
-        # concat 输出
-        self.assertIn("[outv]", filter_str)
-        self.assertIn("[outa]", filter_str)
-        # 总时长
-        self.assertAlmostEqual(duration, 8.0)
-        # 结构：2视频 + 2音频 + 1视频concat + 1音频concat = 6 段
-        self.assertEqual(len(filter_str.split(";")), 6)
-
-    def test_two_clips_with_xfade(self):
-        """两个片段走 xfade 转场的完整流程。"""
-        clip1 = _make_clip("c1", duration=5.0, clip_type="video")
-        clip2 = _make_clip("c2", duration=4.0, clip_type="video")
-
-        chain1 = build_clip_filter(clip1, 0, 1920, 1080, 30)
-        chain2 = build_clip_filter(clip2, 1, 1920, 1080, 30)
-
-        filter_str, duration = build_filter_complex(
-            [chain1, chain2],
-            1920,
-            1080,
-            0.5,
-            [TransitionEffect.CUT, TransitionEffect.FADE],
-        )
-
-        self.assertIn("xfade=transition=fade:duration=0.5", filter_str)
-        self.assertIn("[outv]", filter_str)
-        # 总时长减去转场
-        self.assertAlmostEqual(duration, 8.5)  # 5 + 4 - 0.5
-
-    def test_title_plus_video(self):
-        """title 片段（无音频）+ video 片段（有音频）。"""
-        clip1 = _make_clip("c1", duration=2.0, clip_type="title")
-        clip2 = _make_clip("c2", duration=5.0, clip_type="video")
-
-        chain1 = build_clip_filter(clip1, 0, 1280, 720, 25)
-        chain2 = build_clip_filter(clip2, 1, 1280, 720, 25)
-
-        # title 无音频，video 有音频
-        self.assertIsNone(chain1.audio_label)
-        self.assertIsNotNone(chain2.audio_label)
-
-        # concat 路径
-        filter_str, _ = build_filter_complex(
-            [chain1, chain2],
-            1280,
-            720,
-            0.5,
-            [TransitionEffect.CUT, TransitionEffect.CUT],
-        )
-        # 音频 concat 只有 1 个输入（片段2）
-        self.assertIn("[a1]concat=n=1:v=0:a=1[outa]", filter_str)
-        self.assertNotIn("[a0]", filter_str)
-
-
-if __name__ == "__main__":
-    unittest.main()