refactor(backend): 智能剪辑后端公共逻辑抽取+解耦 (#1884 )

Co-authored-by: xiaoxia <dev@xiaoxiajianji.com> Co-committed-by: xiaoxia <dev@xiaoxiajianji.com>
refactor(web): 智能剪辑 & AI数字人前端代码审查与重构 (#1883 )
2026-09-14 03:15:00 +08:00 · 2026-09-14 02:44:41 +08:00 · 2026-09-14 02:15:43 +08:00 · 2026-09-14 01:50:15 +08:00 · 2026-09-14 01:29:57 +08:00 · 2026-09-14 00:07:35 +08:00
21 changed files with 1310 additions and 1782 deletions
@@ -58,27 +58,10 @@ def _variant_value(values: list[str], index: int, fallback: str = "") -> str:


 def _query_voice_durations(db: Session, voice_ids: list[str]) -> list[float]:
-    """批量查询配音素材时长（秒），#1749 配音时长分配用。
+    """[已下沉] 路由层兼容别名 → app.services.generation_common.query_voice_durations。"""
+    from app.services.generation_common import query_voice_durations

-    逐项 try/float 硬化：MagicMock/异常/缺失 → 0.0（无配音不分配，不阻断）。
-    """
-    ids = [v for v in dict.fromkeys(voice_ids or []) if v]
-    if not ids:
-        return []
-    try:
-        from packages.adapters.sqlalchemy_impl.models import AssetModel
-
-        rows = db.query(AssetModel.id, AssetModel.duration).filter(AssetModel.id.in_(ids)).all()
-        dur_map: dict[str, float] = {}
-        for row in rows:
-            try:
-                dur_map[row[0]] = float(row[1] or 0.0)
-            except (TypeError, ValueError):
-                dur_map[row[0]] = 0.0
-        return [dur_map.get(v, 0.0) for v in ids]
-    except Exception:
-        logger.warning("[生成任务] 配音时长查询失败（按无配音处理，不阻断）", exc_info=True)
-        return [0.0 for _ in ids]
+    return query_voice_durations(db, voice_ids)


 def _to_generation_task_response(task) -> GenerationTaskResponse:
@@ -184,61 +167,10 @@ def _writeback_edit_plan_config(
    title_config: dict | None,
    db: Session,
 ) -> None:
-    """任务入队成功后，回写 EditPlan.config：generation_task_id + title_config。
+    """[已下沉] 路由层兼容别名 → app.services.generation_common.writeback_edit_plan_config。"""
+    from app.services.generation_common import writeback_edit_plan_config

-    用 merge 方式更新，不整体覆盖 config，避免丢失其他字段。
-    失败只记日志，不影响任务创建。
-    """
-    if not plan_id:
-        return
-    try:
-        from packages.adapters.sqlalchemy_impl.models import EditPlanModel
-
-        plan_model = db.query(EditPlanModel).filter(EditPlanModel.id == plan_id).first()
-        if plan_model is None:
-            logger.warning("[生成任务] 回写plan.config失败: plan不存在 plan_id=%s", plan_id)
-            return
-
-        current_config = plan_model.config if isinstance(plan_model.config, dict) else {}
-        merged = dict(current_config)
-        merged["generation_task_id"] = task_id
-
-        # 检查标题是否发生变化，如果变化则清除 cover 字段强制重新生成封面
-        if title_config:
-            old_title_config = merged.get("title_config", {}) or {}
-            old_title_text = (old_title_config.get("text") or "").strip()
-            new_title_text = (title_config.get("text") or "").strip()
-            if old_title_text != new_title_text:
-                # 标题变化，清除旧封面
-                if "cover" in merged:
-                    del merged["cover"]
-                    logger.info(
-                        "[生成任务] 标题变化，清除旧封面: plan_id=%s old_title=%s new_title=%s",
-                        plan_id,
-                        old_title_text,
-                        new_title_text,
-                    )
-            merged["title_config"] = title_config
-
-        plan_model.config = merged
-        db.commit()
-        logger.info(
-            "[生成任务] 回写plan.config成功: plan_id=%s task_id=%s keys=%s",
-            plan_id,
-            task_id,
-            list(merged.keys()),
-        )
-    except Exception as e:
-        logger.warning(
-            "[生成任务] 回写plan.config异常（不影响任务创建）: plan_id=%s error=%s",
-            plan_id,
-            e,
-            exc_info=True,
-        )
-        try:
-            db.rollback()
-        except Exception:
-            pass
+    return writeback_edit_plan_config(plan_id, task_id, title_config, db)


 def _resolve_project_and_library(
@@ -489,25 +421,14 @@ def create_generation_task(
        # 各变体配音时长（查询硬化：异常 → 0.0 不阻断）
        voice_durations = _query_voice_durations(db, variant_voices)

-        # 解析批量源 plan：优先前端传入；否则按 template_id + user 查最新（与单任务兜底同源）
-        batch_source_plan_id = request.source_edit_plan_id
-        if not batch_source_plan_id and request.template_id:
-            try:
-                from packages.adapters.sqlalchemy_impl.models import EditPlanModel
+        # 解析批量源 plan：优先前端传入；否则按 template_id + user 查最新（公共函数）
+        from app.services.generation_common import resolve_latest_plan_by_template

-                _latest = (
-                    db.query(EditPlanModel)
-                    .filter(
-                        EditPlanModel.template_id == request.template_id,
-                        EditPlanModel.created_by_user_id == user_id,
-                    )
-                    .order_by(EditPlanModel.created_at.desc())
-                    .first()
-                )
-                if _latest:
-                    batch_source_plan_id = _latest.id
-            except Exception:
-                logger.warning("[生成任务] 批量源 plan 解析失败", exc_info=True)
+        batch_source_plan_id = (
+            request.source_edit_plan_id
+            or resolve_latest_plan_by_template(db, template_id=request.template_id, user_id=user_id)
+            or ""
+        )

        if not batch_source_plan_id and not request.variant_plan_ids:
            # 无任何可用源 plan：批量变体无从选片，明确报错，严禁静默共用/同源
@@ -552,7 +473,12 @@ def create_generation_task(
                ) from clone_err
            variant_plan_ids.append(_plan0.id)

-            # 变体 1..N-1 独立选片
+            # #1855 P0：批次区间避让表，从变体0实际clips构建初始值（公共函数）
+            from app.services.generation_common import collect_plan_segments as _collect_segments
+
+            _batch_segments = _collect_segments(_plan0.id, _plan_svc._clip_repo)
+
+            # 变体 1..N-1 独立选片（传入累积batch_segments做素材区间避让）
            for task_index in range(1, count):
                variant = None
                last_err: Exception | None = None
@@ -564,6 +490,7 @@ def create_generation_task(
                            created_by_user_id=user_id,
                            name_suffix=f"批量{task_index + 1}",
                            voice_duration=voice_durations[task_index] if task_index < len(voice_durations) else 0.0,
+                            batch_segments=_batch_segments,
                        )
                        break
                    except ValueError as ve:
@@ -595,7 +522,16 @@ def create_generation_task(
                    ) from last_err
                variant_plan_ids.append(variant.id)

-        # ③ 配音时长分配（回传 plan / clone 变体0 均需幂等分配；reselect 已在选片时分配）
+                # #1855 P0：把新变体的clips区间追加到batch_segments，供下一变体避让
+                try:
+                    _new_segs = _collect_segments(variant.id, _plan_svc._clip_repo)
+                    for _aid, _ivs in _new_segs.items():
+                        _batch_segments.setdefault(_aid, []).extend(_ivs)
+                except Exception:
+                    logger.exception("[生成任务] 变体%d 区间收集失败（不阻断）", task_index)
+
+        # ③ 配音时长分配（回传 plan / clone 变体0 均需幂等分配；reselect 已在选片时分配，
+        #    #1855：apply_voice_duration_to_plan 已内置幂等判断，重复调用安全）
        for _vi, _pid in enumerate(variant_plan_ids):
            _vd = voice_durations[_vi] if _vi < len(voice_durations) else 0.0
            if _vd > 0:
@@ -616,24 +552,13 @@ def create_generation_task(
            )
            _single_vd: list[float] = _query_voice_durations(db, _voices)
            _single_dur = _single_vd[0] if _single_vd else 0.0
-            _single_plan = request.source_edit_plan_id
-            if not _single_plan and request.template_id:
-                try:
-                    from packages.adapters.sqlalchemy_impl.models import EditPlanModel
+            from app.services.generation_common import resolve_latest_plan_by_template

-                    _latest = (
-                        db.query(EditPlanModel)
-                        .filter(
-                            EditPlanModel.template_id == request.template_id,
-                            EditPlanModel.created_by_user_id == user_id,
-                        )
-                        .order_by(EditPlanModel.created_at.desc())
-                        .first()
-                    )
-                    if _latest:
-                        _single_plan = _latest.id
-                except Exception:
-                    logger.warning("[生成任务] 单任务源 plan 解析失败", exc_info=True)
+            _single_plan = (
+                request.source_edit_plan_id
+                or resolve_latest_plan_by_template(db, template_id=request.template_id, user_id=user_id)
+                or ""
+            )
            if _single_dur > 0 and _single_plan:
                from app.services.edit_plan_service import EditPlanService

@@ -90,25 +90,12 @@ def create_variant_plans(
    except VariantVoiceError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc

-    # 解析源 plan：显式传入优先；否则按 template_id + user 查最新
+    # 解析源 plan：显式传入优先；否则按 template_id + user 查最新（公共函数）
+    from app.services.generation_common import resolve_latest_plan_by_template
+
    source_plan_id = request.source_edit_plan_id.strip()
    if not source_plan_id and request.template_id.strip():
-        try:
-            from packages.adapters.sqlalchemy_impl.models import EditPlanModel
-
-            _latest = (
-                db.query(EditPlanModel)
-                .filter(
-                    EditPlanModel.template_id == request.template_id.strip(),
-                    EditPlanModel.created_by_user_id == user_id,
-                )
-                .order_by(EditPlanModel.created_at.desc())
-                .first()
-            )
-            if _latest:
-                source_plan_id = _latest.id
-        except Exception:
-            logger.exception("[variant-plans] 源 plan 解析失败")
+        source_plan_id = resolve_latest_plan_by_template(db, template_id=request.template_id, user_id=user_id) or ""

    if not source_plan_id:
        raise HTTPException(
@@ -473,6 +473,7 @@ class EditPlanService:
        name_suffix: str = "变体",
        voice_duration: float = 0.0,
        rng=None,
+        batch_segments: dict[str, list[tuple[float, float]]] | None = None,
    ) -> EditPlan:
        """为批量变体生成独立 plan：完整重跑单视频选片流程（#1743）。

@@ -489,6 +490,8 @@ class EditPlanService:
            created_by_user_id: 新 plan 归属用户。
            name_suffix: plan 名后缀。
            rng: 可选随机数（测试注入种子）。
+            batch_segments: 可选，外部传入的批次内已使用素材区间（前序变体避让用）。
+                传入时作为初始避让对象；未传则保持原逻辑从源 plan clips 自建（向后兼容）。

        Raises:
            ValueError: 源 plan 不存在/无片段、素材池为空或时长全未知。
@@ -537,16 +540,26 @@ class EditPlanService:
            voice = float(voice_duration or 0.0)
        except (TypeError, ValueError):
            voice = 0.0
+        rhythm_template_for_reselect = None
+        if source.config:
+            rhythm_template_for_reselect = source.config.get("rhythm_template")
+
        if voice > 0 and source_clips_data:
            from packages.domain.voice_duration_planner import plan_clip_durations

            _effects: list[str | None] = [c.get("transition_effect") for c in source_clips_data]
            _tdurs: list[float] = [float(c.get("transition_duration") or 0.0) for c in source_clips_data]
+            # #1855 P0：先占位durations为空dict，真正查durations在后面pool_ids确定后执行；
+            # plan_clip_durations 的 asset_durations 参数在该函数中仅作最大段长钳制，
+            # 这里先不依赖它（durations 还没查），传 None 让planner用默认策略；
+            # 真正的asset_durations会在后面 clips_data 生成时传入 reselect_clips_for_variant
            target_durations = plan_clip_durations(
                len(source_clips_data),
                voice,
                transition_effects=_effects,
                transition_durations=_tdurs,
+                rhythm_template=rhythm_template_for_reselect,
+                asset_durations=None,
            )
            if target_durations:
                for _c, _d in zip(source_clips_data, target_durations, strict=False):
@@ -582,12 +595,18 @@ class EditPlanService:
            created_by_user_id=created_by_user_id or (source.created_by_user_id or ""),
        )

-        # 批次内区间：以源 plan（变体 0）片段为初始避让对象
-        batch_segments: dict[str, list[tuple[float, float]]] = {}
-        for c in clips:
-            if c.asset_id and float(c.duration or 0) > 0:
-                st = float(c.start_time or 0.0)
-                batch_segments.setdefault(c.asset_id, []).append((st, st + float(c.duration)))
+        # 批次内区间：外部传入时使用外部传入（含前序变体已用区间）；
+        # 否则保持原逻辑从源 plan clips 自建（向后兼容）
+        if batch_segments is not None:
+            batch_segments_resolved: dict[str, list[tuple[float, float]]] = {
+                k: list(v) for k, v in batch_segments.items()
+            }
+        else:
+            batch_segments_resolved = {}
+            for c in clips:
+                if c.asset_id and float(c.duration or 0) > 0:
+                    st = float(c.start_time or 0.0)
+                    batch_segments_resolved.setdefault(c.asset_id, []).append((st, st + float(c.duration)))

        clips_data = reselect_clips_for_variant(
            source_clips_data,
@@ -595,7 +614,7 @@ class EditPlanService:
            asset_durations=durations,
            asset_scene_points=scene_points,
            historical_used_segments=historical,
-            batch_segments=batch_segments,
+            batch_segments=batch_segments_resolved,
            target_durations=target_durations,
            rng=rng,
        )
@@ -767,6 +786,17 @@ class EditPlanService:
        if plan is None:
            return None

+        # #1855 P0：幂等判断——如果已成功分配过且当前 total_duration 已接近 voice_duration，直接返回
+        try:
+            existing_mark = None
+            if plan.config:
+                existing_mark = plan.config.get("voice_duration_applied")
+            cur_total = float(plan.total_duration or 0.0)
+            if existing_mark is not None and abs(existing_mark - voice) < 1e-6 and abs(cur_total - voice) < 0.5:
+                return plan
+        except Exception:
+            pass
+
        clips: List[EditPlanClip] = []
        skip, page = 0, 500
        while True:
@@ -838,6 +868,10 @@ class EditPlanService:
        )
        try:
            plan.total_duration = net
+            # #1855 P0：写入幂等标记，避免二次调用时只重分配 duration 不重算 start_time
+            new_cfg = dict(plan.config or {})
+            new_cfg["voice_duration_applied"] = voice
+            plan.config = new_cfg
            db = self._clip_repo.session
            db.commit()
        except Exception:
@@ -878,6 +912,69 @@ class EditPlanService:
        rng = rng or _random.Random()
        plan_ids: list[str] = []

+        # #1855 P0：先确定片段数 clip_count（用于节奏模板生成长度匹配）
+        from packages.domain.bgm_pool import allocate_bgm_pool_for_variants
+        from packages.domain.variant_plan_selector import (
+            generate_pixel_perturbation,
+            generate_visual_perturbation,
+        )
+        from packages.domain.voice_duration_planner import RHYTHM_TEMPLATES, adapt_template_length
+
+        clip_count = 0
+        # 从源 plan 获取片段数（分页读，避免关系加载问题）
+        _sclips: list = []
+        _sk, _pg = 0, 500
+        while True:
+            _b = self._clip_repo.list_by_plan(source_plan_id, skip=_sk, limit=_pg)
+            if not _b:
+                break
+            _sclips.extend(_b)
+            if len(_b) < _pg:
+                break
+            _sk += _pg
+        clip_count = len(_sclips)
+
+        # 预先生成所有 N 个变体的节奏模板/BGM/扰动参数（时机提前到选片前写入config）
+        rhythm_templates_for_variants: list = []
+        for _idx in range(count):
+            if clip_count > 0:
+                variant_seed = rng.randint(0, 999999)
+                _tpl = adapt_template_length(RHYTHM_TEMPLATES[variant_seed % len(RHYTHM_TEMPLATES)], clip_count)
+                rhythm_templates_for_variants.append(_tpl)
+            else:
+                rhythm_templates_for_variants.append(None)
+
+        source_bgm_config: dict = {}
+        source_plan = self.get_plan(source_plan_id)
+        if source_plan and source_plan.config:
+            source_bgm_config = source_plan.config.get("bgm", {}) or {}
+        variant_seeds_for_bgm = [rng.randint(0, 999999) for _ in range(count)]
+        bgm_pool_assignments = allocate_bgm_pool_for_variants(source_bgm_config, variant_seeds_for_bgm)
+
+        def _build_variant_config_update(idx: int) -> dict:
+            """构建单个变体的 config 更新（节奏模板/BGM/视觉/像素扰动）。"""
+            upd: dict = {}
+            try:
+                perturbation = generate_visual_perturbation(rng)
+                if idx == 0:
+                    perturbation["hflip"] = False
+                upd["visual_perturbation"] = perturbation
+            except Exception:
+                logger.exception("变体 %d 视觉扰动生成失败（不阻断）", idx)
+            try:
+                pixel_pert = generate_pixel_perturbation(rng)
+                upd["pixel_perturbation"] = pixel_pert
+            except Exception:
+                logger.exception("变体 %d 像素扰动生成失败（不阻断）", idx)
+            rt = rhythm_templates_for_variants[idx] if idx < len(rhythm_templates_for_variants) else None
+            if rt is not None:
+                upd["rhythm_template"] = rt
+            if idx < len(bgm_pool_assignments):
+                existing_bgm = dict((source_plan.config or {}).get("bgm", {}) or {})
+                existing_bgm.update(bgm_pool_assignments[idx])
+                upd["bgm"] = existing_bgm
+            return upd
+
        # 变体 0：clone（片段结构同源 plan，起点重算），不污染源 plan
        plan0 = self.clone_plan_for_variant(
            source_plan_id,
@@ -890,6 +987,15 @@ class EditPlanService:
                v0_voice = float(voice_durations[0] or 0.0)
            except (TypeError, ValueError):
                v0_voice = 0.0
+
+        # #1855 P0：在配音分配前先写入变体0的节奏模板/扰动/BGM，确保 apply_voice_duration_to_plan 能读到 rhythm_template
+        try:
+            _cfg0 = _build_variant_config_update(0)
+            if _cfg0:
+                self.update_plan_config(plan0.id, _cfg0)
+        except Exception:
+            logger.exception("变体0 配置写入失败（不阻断）: plan=%s", plan0.id)
+
        if v0_voice > 0:
            try:
                self.apply_voice_duration_to_plan(plan0.id, v0_voice)
@@ -897,7 +1003,12 @@ class EditPlanService:
                logger.exception("变体0 配音分配失败（不阻断）: plan=%s", plan0.id)
        plan_ids.append(plan0.id)

-        # 变体 1..N-1：独立选片
+        # #1855 P0：批次内素材区间避让表——从变体0实际落库的clips构建初始值（公共函数）
+        from app.services.generation_common import collect_plan_segments as _collect_plan_segments
+
+        batch_segments_acc: dict[str, list[tuple[float, float]]] = _collect_plan_segments(plan0.id, self._clip_repo)
+
+        # 变体 1..N-1：独立选片（传入累积的 batch_segments 做区间避让）
        for i in range(1, count):
            voice = 0.0
            if voice_durations and i < len(voice_durations):
@@ -905,6 +1016,14 @@ class EditPlanService:
                    voice = float(voice_durations[i] or 0.0)
                except (TypeError, ValueError):
                    voice = 0.0
+
+            # #1855 P0：在reselect前先为"变体i"准备配置更新——但reselect内部复制的是source.config，
+            # 所以每个变体独立的节奏模板需要在reselect后单独写入config；
+            # 但 plan_clip_durations 用的是 source.config.rhythm_template（即源plan的节奏模板），
+            # 为了让每个变体在选片阶段就使用自己的节奏模板分配段长，这里采用：
+            #   - reselect 仍使用源 plan 的 rhythm_template（保持片段骨架一致）
+            #   - 选片完成后立即写入该变体自己的 rhythm_template/扰动/BGM 到config，
+            #     后续不再二次 apply_voice_duration_to_plan（由幂等标记跳过）
            variant = self.reselect_plan_for_variant(
                source_plan_id,
                candidate_asset_ids,
@@ -912,73 +1031,26 @@ class EditPlanService:
                name_suffix=f"变体{i + 1}",
                voice_duration=voice,
                rng=rng,
+                batch_segments=batch_segments_acc,
            )
+
+            # 选片完成后写入该变体的独立配置（节奏模板/扰动/BGM）
+            try:
+                _cfgi = _build_variant_config_update(i)
+                if _cfgi:
+                    self.update_plan_config(variant.id, _cfgi)
+            except Exception:
+                logger.exception("变体 %d 配置写入失败（不阻断）: plan=%s", i, variant.id)
+
            plan_ids.append(variant.id)

-        # #1764：为每个变体生成独立节奏模板（让批量视频片段时长分布不同）
-        from packages.domain.voice_duration_planner import RHYTHM_TEMPLATES, adapt_template_length
-
-        clip_count = 0
-        if voice_durations and len(voice_durations) > 0:
-            # 从源 plan 获取片段数
-            source_plan = self.get_plan(source_plan_id)
-            if source_plan and hasattr(source_plan, "clips"):
-                clip_count = len(list(source_plan.clips)) if source_plan.clips else 0
-
-        rhythm_templates_for_variants = []
-        if clip_count > 0:
-            for idx in range(len(plan_ids)):
-                # 每个变体用不同的 seed 选择节奏模板
-                variant_seed = rng.randint(0, 999999)
-                template = adapt_template_length(RHYTHM_TEMPLATES[variant_seed % len(RHYTHM_TEMPLATES)], clip_count)
-                rhythm_templates_for_variants.append(template)
-                logger.info("变体 %d 节奏模板: plan=%s template=%s", idx, plan_ids[idx], template)
-
-        # #1767：BGM 池差异化分配（让批量变体使用不同 BGM / 段落 / 音量）
-        from packages.domain.bgm_pool import allocate_bgm_pool_for_variants
-
-        source_bgm_config = {}
-        source_plan = self.get_plan(source_plan_id)
-        if source_plan and source_plan.config:
-            source_bgm_config = source_plan.config.get("bgm", {}) or {}
-
-        variant_seeds_for_bgm = [rng.randint(0, 999999) for _ in plan_ids]
-        bgm_pool_assignments = allocate_bgm_pool_for_variants(source_bgm_config, variant_seeds_for_bgm)
-
-        # 为每个变体生成独立视觉扰动参数（让批量视频画面本身更不同）
-        from packages.domain.variant_plan_selector import generate_visual_perturbation
-
-        for idx, pid in enumerate(plan_ids):
+            # #1855 P0：把当前新变体的 clips 区间追加到 batch_segments，供下一变体避让
            try:
-                perturbation = generate_visual_perturbation(rng)
-                # 变体 0 不做 hflip（保持预览 plan 原始画面方向）
-                if idx == 0:
-                    perturbation["hflip"] = False
-                config_update = {"visual_perturbation": perturbation}
-                # #1764：写入节奏模板
-                if idx < len(rhythm_templates_for_variants):
-                    config_update["rhythm_template"] = rhythm_templates_for_variants[idx]
-                # #1765：写入像素级扰动滤镜
-                from packages.domain.variant_plan_selector import generate_pixel_perturbation
-
-                pixel_pert = generate_pixel_perturbation(rng)
-                config_update["pixel_perturbation"] = pixel_pert
-                # #1767：写入 BGM 池分配（覆盖 bgm 配置中的 preset_id / audio_offset / volume_adjust_db）
-                if idx < len(bgm_pool_assignments):
-                    existing_bgm = dict((source_plan.config or {}).get("bgm", {}) or {})
-                    existing_bgm.update(bgm_pool_assignments[idx])
-                    config_update["bgm"] = existing_bgm
-                self.update_plan_config(pid, config_update)
-                logger.info(
-                    "变体 %d 视觉扰动+像素扰动+BGM池: plan=%s vis=%s pix=%s bgm=%s",
-                    idx,
-                    pid,
-                    perturbation,
-                    pixel_pert,
-                    bgm_pool_assignments[idx] if idx < len(bgm_pool_assignments) else None,
-                )
+                _new_segs = _collect_plan_segments(variant.id, self._clip_repo)
+                for _aid, _ivs in _new_segs.items():
+                    batch_segments_acc.setdefault(_aid, []).extend(_ivs)
            except Exception:
-                logger.exception("变体 %d 视觉扰动生成失败（不阻断）: plan=%s", idx, pid)
+                logger.exception("变体 %d 区间收集失败（不阻断）: plan=%s", i, variant.id)

        # 标记所有变体 plan 的 clips 为 ready（已分配素材+起点，语义上就是 ready）
        for pid in plan_ids:
@@ -0,0 +1,175 @@
+"""智能剪辑公共服务辅助函数（从 route 层下沉）。
+
+集中管理：
+- query_voice_durations：批量查询配音素材时长
+- writeback_edit_plan_config：任务入队后回写 EditPlan.config
+- collect_plan_segments：分页读取 plan clips 构建素材区间表（变体避让用）
+- resolve_latest_plan_by_template：按 template_id + user_id 查最新 EditPlan
+
+设计原则：
+- 无副作用的纯查询 / 幂等写回；失败一律不阻断主流程（记日志 + 返回安全默认值）
+- 不依赖 FastAPI / HTTPException，便于 service 层和 worker 复用
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from sqlalchemy.orm import Session
+
+logger = logging.getLogger(__name__)
+
+
+def query_voice_durations(db: Session, voice_ids: list[str]) -> list[float]:
+    """批量查询配音素材时长（秒），#1749 配音时长分配用。
+
+    逐项 try/float 硬化：MagicMock/异常/缺失 → 0.0（无配音不分配，不阻断）。
+
+    #1855 P0修复：不再对 voice_ids 去重，保持与调用方传入顺序/长度一致，
+    允许同配音id多次出现时返回相同时长（支持"同配音N变体"的时长对齐）。
+    """
+    raw_ids = list(voice_ids or [])
+    if not raw_ids:
+        return []
+    unique_ids: list[str] = []
+    _seen: set[str] = set()
+    for v in raw_ids:
+        if v and v not in _seen:
+            _seen.add(v)
+            unique_ids.append(v)
+    if not unique_ids:
+        return [0.0 for _ in raw_ids]
+    try:
+        from packages.adapters.sqlalchemy_impl.models import AssetModel
+
+        rows = db.query(AssetModel.id, AssetModel.duration).filter(AssetModel.id.in_(unique_ids)).all()
+        dur_map: dict[str, float] = {}
+        for row in rows:
+            try:
+                dur_map[row[0]] = float(row[1] or 0.0)
+            except (TypeError, ValueError):
+                dur_map[row[0]] = 0.0
+        return [dur_map.get(v, 0.0) if v else 0.0 for v in raw_ids]
+    except Exception:
+        logger.warning("[generation_common] 配音时长查询失败（按无配音处理，不阻断）", exc_info=True)
+        return [0.0 for _ in raw_ids]
+
+
+def writeback_edit_plan_config(
+    plan_id: str,
+    task_id: str,
+    title_config: dict | None,
+    db: Session,
+) -> None:
+    """任务入队成功后，回写 EditPlan.config：generation_task_id + title_config。
+
+    用 merge 方式更新，不整体覆盖 config，避免丢失其他字段。
+    失败只记日志，不影响任务创建。
+    """
+    if not plan_id:
+        return
+    try:
+        from packages.adapters.sqlalchemy_impl.models import EditPlanModel
+
+        plan_model = db.query(EditPlanModel).filter(EditPlanModel.id == plan_id).first()
+        if plan_model is None:
+            logger.warning("[generation_common] 回写plan.config失败: plan不存在 plan_id=%s", plan_id)
+            return
+
+        current_config = plan_model.config if isinstance(plan_model.config, dict) else {}
+        merged = dict(current_config)
+        merged["generation_task_id"] = task_id
+
+        if title_config:
+            old_title_config = merged.get("title_config", {}) or {}
+            old_title_text = (old_title_config.get("text") or "").strip()
+            new_title_text = (title_config.get("text") or "").strip()
+            if old_title_text != new_title_text:
+                if "cover" in merged:
+                    del merged["cover"]
+                    logger.info(
+                        "[generation_common] 标题变化，清除旧封面: plan_id=%s old_title=%s new_title=%s",
+                        plan_id,
+                        old_title_text,
+                        new_title_text,
+                    )
+            merged["title_config"] = title_config
+
+        plan_model.config = merged
+        db.commit()
+        logger.info(
+            "[generation_common] 回写plan.config成功: plan_id=%s task_id=%s keys=%s",
+            plan_id,
+            task_id,
+            list(merged.keys()),
+        )
+    except Exception as e:
+        logger.warning(
+            "[generation_common] 回写plan.config异常（不影响任务创建）: plan_id=%s error=%s",
+            plan_id,
+            e,
+            exc_info=True,
+        )
+        try:
+            db.rollback()
+        except Exception:
+            pass
+
+
+def collect_plan_segments(
+    plan_id: str,
+    clip_repo: Any,
+    *,
+    page_size: int = 500,
+) -> dict[str, list[tuple[float, float]]]:
+    """分页读取 plan 所有 clips，构建 {asset_id: [(start, end), ...]} 素材区间表。
+
+    用于 #1855 P0 批次内素材区间避让（变体间素材片段重叠控制）。
+    """
+    segs: dict[str, list[tuple[float, float]]] = {}
+    sk, pg = 0, page_size
+    while True:
+        batch = clip_repo.list_by_plan(plan_id, skip=sk, limit=pg)
+        if not batch:
+            break
+        for c in batch:
+            if c.asset_id and float(c.duration or 0) > 0:
+                st = float(c.start_time or 0.0)
+                segs.setdefault(c.asset_id, []).append((st, st + float(c.duration)))
+        if len(batch) < pg:
+            break
+        sk += pg
+    return segs
+
+
+def resolve_latest_plan_by_template(
+    db: Session,
+    *,
+    template_id: str,
+    user_id: str,
+) -> Optional[str]:
+    """按 template_id + user_id 查找最新的 EditPlan.id（模板兜底用）。找不到返回 None。"""
+    if not (template_id or "").strip():
+        return None
+    try:
+        from packages.adapters.sqlalchemy_impl.models import EditPlanModel
+
+        latest = (
+            db.query(EditPlanModel)
+            .filter(
+                EditPlanModel.template_id == template_id.strip(),
+                EditPlanModel.created_by_user_id == user_id,
+            )
+            .order_by(EditPlanModel.created_at.desc())
+            .first()
+        )
+        return latest.id if latest else None
+    except Exception:
+        logger.warning(
+            "[generation_common] 按template查找最新plan失败: template=%s user=%s",
+            template_id,
+            user_id,
+            exc_info=True,
+        )
+        return None
@@ -26,6 +26,10 @@ export interface BatchVariantPlansRequest {
  count: number
  /** 源剪辑计划 ID：优先取预览/草稿关联的 plan；不传由后端按 template_id+user 兜底最新 plan */
  source_edit_plan_id?: string
+  /** 统一配音 ID（共用配音模式）；独立配音模式不传，改传 voice_library_ids */
+  voice_library_id?: string
+  /** 独立配音 ID 列表（长度=count，按变体序号一一对应）；共用配音模式不传 */
+  voice_library_ids?: string[]
 }

 /** 单个变体的计划片段 */
@@ -36,6 +40,8 @@ export interface VariantPlan {
  plan_id: string
  /** 该变体的真实片段（顺序/素材/起点与正式成片一致） */
  clips: EditPlanClip[]
+  /** 该变体实际配音时长（秒），用于前端预览按配音时长对齐音画；后端暂未返回时缺省 */
+  voice_duration?: number
 }

 /** 批量变体计划响应 */
@@ -227,11 +227,6 @@ const AiAvatarPage: React.FC = () => {
      setLipsyncStatus("generating")
      setLipsyncErrorMessage("")

-      console.log("[对口型] 开始生成:", {
-        videoId: video.id,
-        mode: isPreSynth ? "pre-synth" : "tts-direct",
-        textLen: state.scriptText.length,
-      })
      const asset = await getAssetById(video.id)
      const videoUrl = asset?.file_url
      if (!videoUrl) {
@@ -262,9 +257,7 @@ const AiAvatarPage: React.FC = () => {
          emotion: normalizeEmotion(state.emotion),
        }
      }
-      console.log("[对口型] createLipsyncJob 请求:", payload)
      const job = await createLipsyncJob(payload)
-      console.log("[对口型] createLipsyncJob 响应:", { id: job.id, status: job.status })
      state.setLipsyncJob(job)

      // 如果是预合成模式，后端会同步把状态置为 submitted（甚至可能已返回 running），
@@ -274,11 +267,6 @@ const AiAvatarPage: React.FC = () => {
        try {
          const updated = await getLipsyncJob(job.id)
          state.setLipsyncJob(updated)
-          console.log("[对口型] 轮询状态:", {
-            id: updated.id,
-            status: updated.status,
-            error: updated.error_message,
-          })
          if (updated.status === "completed") {
            if (lipsyncTimerRef.current) clearInterval(lipsyncTimerRef.current)
            setLipsyncStatus("completed")
@@ -139,13 +139,6 @@ export function PanelVoiceSelector({
      }
      const targetId = voice.voice_clone_profile_id || voice.id
      // DEBUG: 打印请求参数，帮助定位 /tts/preview 失败原因
-      console.log("[AI数字人-克隆试听] previewTts 请求:", {
-        voice_id: targetId,
-        voice_name: voice.name,
-        voice_type: voice.type,
-        voice_clone_profile_id: voice.voice_clone_profile_id,
-        voice_id_field: voice.voice_id,
-      })
      setPreviewingId(voice.id)
      try {
        const res = await previewTts({
@@ -154,10 +147,6 @@ export function PanelVoiceSelector({
          speed: speed, // 透传用户选择的语速（#1822）
          emotion: normalizeEmotion(emotion), // 情绪中文→英文枚举
        })
-        console.log("[AI数字人-克隆试听] previewTts 响应:", {
-          audio_url: res.audio_url?.substring(0, 80),
-          duration: res.duration,
-        })
        if (!res.audio_url) {
          setPreviewingId(null)
          message.error("合成试听失败：未返回音频")
@@ -231,9 +231,13 @@ const GeneratePage: React.FC = () => {
  /* ── 批量变体真实片段（#1744）：后端独立选片，预览即成片；失败静默降级本地模拟 ──
     仅批量（N>1）且在第 4 步预览时申请，避免选素材阶段频繁请求；
     变体 0 沿用草稿 plan（与单视频一致），变体 1..N-1 后端 reselect 独立选片 */
+  // P0 fix：批量变体计划请求需携带配音参数，避免后端按"无配音"选片导致 clips 时长与配音错位
+  const batchVoiceLibraryId =
+    voiceMode === "clone" ? selectedClonedVoice || selectedVoice || "" : selectedVoice || ""
  const {
    clipsByVariant: variantClips,
    planIdsByVariant: variantPlanIds,
+    voiceDurationsByVariant: variantVoiceDurations,
    loading: variantClipsLoading,
    error: variantClipsError,
    retry: retryVariantClips,
@@ -243,6 +247,9 @@ const GeneratePage: React.FC = () => {
    templateId: selectedTemplate || "",
    assetIds: previewAssetIds,
    sourcePlanId: storedSourceEditPlanId || sourceEditPlanId || "",
+    voiceLibraryId: batchVoiceLibraryId,
+    voiceLibraryIds: voiceLibraryIds || [],
+    voiceModePerVideo,
  })

  /* ── 批量变体配音预览 URL（#1750）：独立模式每变体挂各自配音，共用模式全挂同一条；
@@ -476,6 +483,7 @@ const GeneratePage: React.FC = () => {
                  titles={previewTitles}
                  titleSettings={titleSettings}
                  voiceAudioUrls={variantVoiceAudioUrls}
+                  voiceDurations={variantVoiceDurations}
                  variantClips={variantClips}
                  clipsLoading={variantClipsLoading}
                  clipsError={variantClipsError}
@@ -31,6 +31,12 @@ interface CanvasPreviewGridProps {
   * 元素为 null 表示该变体暂无音频（AI 音色 TTS 合成中））
   */
  voiceAudioUrls?: (string | null)[]
+  /**
+   * 各变体配音时长（秒）：后端返回 voice_duration 优先；未返回则为 undefined，
+   * 由 FrontendPreviewPlayer 在 audio loadedmetadata 时自测兜底。
+   * 长度=count，undefined 项表示该变体未提供后端时长。
+   */
+  voiceDurations?: (number | undefined)[]
  /**
   * 各变体的后端真实片段（#1744/#1750）：长度=count。
   * 仅 clipsLoading=false 且 clipsError=false 时才会传给播放器。
@@ -56,6 +62,7 @@ const CanvasPreviewGrid: React.FC<CanvasPreviewGridProps> = ({
  titles,
  titleSettings,
  voiceAudioUrls,
+  voiceDurations,
  variantClips,
  clipsLoading = false,
  clipsError = false,
@@ -120,6 +127,7 @@ const CanvasPreviewGrid: React.FC<CanvasPreviewGridProps> = ({
                serverClips={variantClips[i]}
                variantTitle={titles[i] || ""}
                voiceAudioUrl={voiceAudioUrls?.[i] || undefined}
+                voiceDurationHint={voiceDurations?.[i]}
                activePlayToken={activePlayToken}
                onPlayTokenChange={setActivePlayToken}
                compact
@@ -1,26 +1,22 @@
 /**
- * 前端预览播放器 — Canvas + WebCodecs 方案
+ * 前端预览播放器 — 原生 Video 元素方案（浏览器硬件解码，独立线程，不阻塞 UI）
 *
 * 架构：
- * - 浏览器支持 WebCodecs → Canvas 渲染（帧级精确控制 + 标题合成）
- * - 浏览器不支持 → fallback 到多 video 元素方案
+ * - 默认走原生 video 元素多片段切换播放（useSegmentScheduler 调度），
+ *   叠加标题 CSS 浮层、配音音轨（usePreviewAudio）、尾段冻结看门狗、批量播放互斥 token。
+ *   UI 拆分为 PreviewControls（控制条/按钮） + PreviewProgressBar（进度条）两个子组件。
+ * - WebCodecs 路径已废弃（原 useWebCodecs 常量恒为 false，相关死代码已移除），
+ *   保留 useCanvasPlayer hook 文件供未来兜底（不影响当前打包体积）。
 *
- * 对外 API 不变：assets, template, videoRatio, ready, voiceAudioUrl
+ * 对外 API 完全不变：assets / videoRatio / ready / voiceAudioUrl / serverClips 等。
 */
 import React, { useMemo, useCallback, useState, useRef, useEffect } from "react"
-import {
-  PlayCircleOutlined,
-  PauseCircleOutlined,
-  SoundOutlined,
-  LoadingOutlined,
-  AudioOutlined,
-  AudioMutedOutlined,
-} from "@ant-design/icons"
+import { PlayCircleOutlined, SoundOutlined } from "@ant-design/icons"
 import type { AssetItem } from "@/api/assets"
 import type { EditPlanClip } from "@/api/template-editor"
 import { useSegmentScheduler, type PlaybackSegment } from "../hooks/useSegmentScheduler"
-import { useCanvasPlayer } from "../hooks/useCanvasPlayer"
-
+import { usePreviewAudio } from "../hooks/usePreviewAudio"
+import { PreviewControls } from "./PreviewControls"
 interface FrontendPreviewPlayerProps {
  assets: AssetItem[]
  videoRatio: string
@@ -58,12 +54,11 @@ interface FrontendPreviewPlayerProps {
  activePlayToken?: number | null
  /** 播放权变化回调：本实例请求播放时传自身 playToken，暂停时传 null */
  onPlayTokenChange?: (token: number | null) => void
-}
-
-function formatTime(seconds: number): string {
-  const m = Math.floor(seconds / 60)
-  const s = Math.floor(seconds % 60)
-  return `${m}:${s.toString().padStart(2, "0")}`
+  /**
+   * 后端返回的配音时长（秒）P0 对齐：优先以该值作为音画时长锚点；
+   * 未提供则在 audio loadedmetadata 后自测兜底。
+   */
+  voiceDurationHint?: number
 }

 /**
@@ -116,6 +111,7 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
  ready,
  serverClips,
  voiceAudioUrl,
+  voiceDurationHint,
  titleSettings,
  onTitlePositionChange,
  playToken,
@@ -124,26 +120,11 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
  activePlayToken = null,
  onPlayTokenChange,
 }) => {
-  // #1754：测量配音时长，计算缩放因子
-  const [voiceDuration, setVoiceDuration] = useState(0)
-  useEffect(() => {
-    if (!voiceAudioUrl) {
-      setVoiceDuration(0)
-      return
-    }
-    const audio = new Audio()
-    audio.preload = "metadata"
-    const onLoaded = () => {
-      if (audio.duration && isFinite(audio.duration)) {
-        setVoiceDuration(audio.duration)
-      }
-    }
-    audio.addEventListener("loadedmetadata", onLoaded)
-    audio.src = voiceAudioUrl
-    return () => {
-      audio.removeEventListener("loadedmetadata", onLoaded)
-    }
-  }, [voiceAudioUrl])
+  // #1754→P0：配音时长作为音画时长锚点。
+  // 优先使用后端返回的 voiceDurationHint；音频 loadedmetadata 后再以自测值覆盖（更精确）。
+  const [voiceDuration, setVoiceDuration] = useState<number>(() =>
+    voiceDurationHint && voiceDurationHint > 0 ? voiceDurationHint : 0,
+  )

  // #1756：clips 原始总时长 + 转场时长（后端等比分配配音时包含转场占位）
  const rawClipsDuration = useMemo(() => {
@@ -189,9 +170,10 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
      ? (titleSettings.posY / playRes.height) * 100
      : null

-  // ── 拖拽状态（用 ref 避免在每帧渲染中触发重渲染）──
+  // ── 标题拖拽（用 ref 避免每帧触发 React 重渲染）──
  const draggingTitleRef = useRef(false)
  const titleDragRef = useRef<HTMLDivElement>(null)
+  const playerContainerRef = useRef<HTMLDivElement>(null)
  const handleTitlePointerDown = useCallback(
    (e: React.PointerEvent<HTMLDivElement>) => {
      if (!onTitlePositionChange || !playerContainerRef.current) return
@@ -207,7 +189,6 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
    if (!draggingTitleRef.current || !playerContainerRef.current) return
    e.preventDefault()
    e.stopPropagation()
-    // 拖拽过程中直接修改 DOM，不触发 React 渲染（避免频繁重渲染导致换行）
    if (titleDragRef.current) {
      const rect = playerContainerRef.current.getBoundingClientRect()
      const relX = Math.max(0, Math.min(rect.width, e.clientX - rect.left))
@@ -222,7 +203,6 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
    (e: React.PointerEvent<HTMLDivElement>) => {
      if (!draggingTitleRef.current) return
      draggingTitleRef.current = false
-      // 拖拽结束时才调用 onTitlePositionChange 保存最终位置
      if (onTitlePositionChange && playerContainerRef.current) {
        const rect = playerContainerRef.current.getBoundingClientRect()
        const relX = Math.max(0, Math.min(rect.width, e.clientX - rect.left))
@@ -243,7 +223,6 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
    [onTitlePositionChange, playRes.width, playRes.height],
  )

-  const playerContainerRef = useRef<HTMLDivElement>(null)
  const [containerHeight, setContainerHeight] = useState(0)
  useEffect(() => {
    const el = playerContainerRef.current
@@ -268,234 +247,157 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
  const titleSidePct = (TITLE_MARGIN_SIDE / playRes.width) * 100
  const titleTopPct = (TITLE_MARGIN_TOP / playRes.height) * 100
  const titleBottomPct = (TITLE_MARGIN_BOTTOM / playRes.height) * 100
-  // 描边/阴影也要按缩放比例放大
  const titleScale = containerHeight > 0 ? containerHeight / playRes.height : 1
  const titleStrokeWidth = Math.max(1, 2 * titleScale)
  const titleShadowBlur = 4 * titleScale
  const titleShadowOffset = 2 * titleScale

-  // 默认走原生 video 播放（浏览器硬件解码，独立线程，不阻塞 UI）
-  // WebCodecs 仅在明确需要时启用（保留代码作为兜底）
-  const useWebCodecs = false
-
-  // ── 两条路径共用同一个 canvas ref（fallback 路径不使用） ──
-  const canvasRef = useRef<HTMLCanvasElement>(null)
-
-  // ── Canvas 播放器（WebCodecs 路径） ──
-  const canvasTitle = titleSettings
-    ? {
-        text: effectiveTitle || "标题预览",
-        fontSize: titleSettings.size,
-        fontFamily: titleSettings.font || "思源黑体",
-        color: titleSettings.color || "#ffffff",
-        position: titleSettings.position || "top",
-        bold: titleSettings.bold,
-        stroke: titleSettings.stroke,
-        shadow: titleSettings.shadow,
-      }
-    : undefined
-
-  const canvasSegments = useMemo(
-    () =>
-      segments.map((s) => ({
-        assetId: s.assetId,
-        videoUrl: s.videoUrl,
-        startTime: s.startTime,
-        endTime: s.endTime,
-      })),
-    [segments],
-  )
-
-  // WebCodecs 解码失败后强制走 video fallback
-  const [forceVideoFallback, setForceVideoFallback] = useState(false)
-
-  const handleCanvasError = useCallback((err: Error) => {
-    console.error("[FrontendPreviewPlayer] Canvas decode Error, switching to video fallback:", err)
-    setForceVideoFallback(true)
-  }, [])
-
-  const { state: canvasState, controls: canvasControls } = useCanvasPlayer(
-    canvasRef,
-    useWebCodecs && !forceVideoFallback ? canvasSegments : [],
-    useWebCodecs && !forceVideoFallback ? canvasTitle : undefined,
-    handleCanvasError,
-    useWebCodecs && !forceVideoFallback,
-  )
-
-  // WebCodecs 报告解码失败时自动切换到 video fallback
-  useEffect(() => {
-    if (canvasState.hasDecodeError && !forceVideoFallback) {
-      console.warn("[FrontendPreviewPlayer] hasDecodeError detected, forcing video fallback")
-      setForceVideoFallback(true)
-    }
-  }, [canvasState.hasDecodeError, forceVideoFallback])
-
-  // ── Video 播放器（fallback 路径） ──
+  // ── Video 播放器（默认路径，浏览器原生硬件解码） ──
  const {
-    isPlaying: videoIsPlaying,
-    currentTime: videoCurrentTime,
-    totalDuration: videoTotalDuration,
-    currentSegmentIndex: videoCurrentSegIdx,
-    canPlay: videoCanPlay,
-    togglePlayPause: videoTogglePlayPause,
-    seekTo: videoSeekTo,
-    pause: videoPause,
+    isPlaying,
+    currentTime,
+    totalDuration,
+    currentSegmentIndex,
+    canPlay,
+    togglePlayPause,
+    seekTo,
+    pause,
    videoRefs,
  } = useSegmentScheduler(segments)

-  // 选择哪条路径的状态（WebCodecs 解码失败时强制走 video fallback）
-  const effectiveUseWebCodecs = useWebCodecs && !forceVideoFallback
-  const isPlaying = effectiveUseWebCodecs ? canvasState.isPlaying : videoIsPlaying
-  const currentTime = effectiveUseWebCodecs ? canvasState.currentTime : videoCurrentTime
-  const totalDuration = effectiveUseWebCodecs ? canvasState.duration : videoTotalDuration
-  const canPlay = effectiveUseWebCodecs ? canvasState.isReady : videoCanPlay
-  const isBuffering = effectiveUseWebCodecs ? canvasState.isBuffering : false
+  // P0 fix：以配音时长为音画同步锚点。
+  // 有配音时总时长 = 配音时长（短则末帧冻结，长则硬停）；无配音时沿用视频总时长（素材原声兜底）。
+  const effectiveTotalDuration =
+    !!voiceAudioUrl && voiceDuration > 0 ? voiceDuration : totalDuration

-  // ── 配音音频同步 ──
-  const audioRef = useRef<HTMLAudioElement | null>(null)
-  const prevIsPlayingRef = useRef(false)
  // 本卡片静音开关（#1741）：默认有声，用户可点喇叭单独静音某张卡片
  const [muted, setMuted] = useState(false)
  // 有配音时 video 素材保持静音（避免原声与配音混音）；无配音时取消静音，素材原声兜底
  const hasVoice = !!voiceAudioUrl

-  useEffect(() => {
-    if (!voiceAudioUrl) {
-      if (audioRef.current) {
-        audioRef.current.pause()
-        audioRef.current.src = ""
-        audioRef.current = null
-      }
-      return
-    }
-    if (!audioRef.current) {
-      audioRef.current = new Audio()
-      audioRef.current.preload = "auto"
-    }
-    if (audioRef.current.src !== voiceAudioUrl) {
-      audioRef.current.src = voiceAudioUrl
-    }
-    audioRef.current.muted = muted
-  }, [voiceAudioUrl, muted])
+  // 音频 ended：兜底触发暂停与释放播放权
+  const handleAudioEnded = useCallback(() => {
+    if (!isPlaying) return
+    pause()
+    if (playToken != null) onPlayTokenChange?.(null)
+  }, [isPlaying, pause, playToken, onPlayTokenChange])

-  useEffect(() => {
-    const audio = audioRef.current
-    if (!audio || !audio.src) return
-    if (isPlaying && !prevIsPlayingRef.current) {
-      audio.currentTime = currentTime
-      audio.play().catch(() => {})
-    } else if (!isPlaying && prevIsPlayingRef.current) {
-      audio.pause()
-    }
-    prevIsPlayingRef.current = isPlaying
-  }, [isPlaying, currentTime])
+  const {
+    seekTo: audioSeekTo,
+    ensurePlayingAt: audioEnsurePlayingAt,
+    pause: audioPause,
+  } = usePreviewAudio({
+    voiceAudioUrl,
+    voiceDurationHint,
+    muted,
+    isPlaying,
+    currentTime,
+    onVoiceDurationChange: setVoiceDuration,
+    onEnded: handleAudioEnded,
+  })

-  // 片段切换时同步音频（仅 fallback 路径需要）
-  const segmentSyncKey = effectiveUseWebCodecs ? -1 : videoCurrentSegIdx
+  // 片段切换时同步音频时间（video fallback）
  useEffect(() => {
-    const audio = audioRef.current
-    if (!audio || !audio.src || !isPlaying) return
-    audio.currentTime = currentTime
+    if (!isPlaying) return
+    audioSeekTo(currentTime)
    // 注意：不要把 currentTime 放进依赖数组，否则每200ms会重置音频位置导致卡顿
    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [segmentSyncKey, isPlaying])
+  }, [currentSegmentIndex, isPlaying])
+
+  // P0 fix：视频比配音短时的「末帧冻结+音频续播」模式。
+  // 视频调度器播完最后一段自动 pause，此时若配音仍在播，用 rAF 虚拟时钟推进 currentTime 直到配音结束。
+  const [tailCurrentTime, setTailCurrentTime] = useState<number | null>(null)
+  const tailStartRef = useRef<number>(0)
+  const tailBaseRef = useRef<number>(0)
+  const tailAudioRef = useRef({ ensurePlayingAt: audioEnsurePlayingAt, pause: audioPause })
+  tailAudioRef.current = { ensurePlayingAt: audioEnsurePlayingAt, pause: audioPause }
+
+  useEffect(() => {
+    const needTail =
+      !!voiceAudioUrl &&
+      voiceDuration > 0 &&
+      !isPlaying &&
+      typeof currentTime === "number" &&
+      currentTime >= totalDuration - 0.1 &&
+      currentTime < voiceDuration - 0.1
+    if (needTail && tailCurrentTime === null) {
+      tailBaseRef.current = currentTime
+      tailStartRef.current = performance.now()
+      setTailCurrentTime(currentTime)
+      tailAudioRef.current.ensurePlayingAt(currentTime)
+      return
+    }
+    if (!needTail && tailCurrentTime !== null) {
+      setTailCurrentTime(null)
+    }
+  }, [isPlaying, currentTime, totalDuration, voiceDuration, voiceAudioUrl, tailCurrentTime])
+
+  useEffect(() => {
+    if (tailCurrentTime === null) return
+    let raf = 0
+    const tick = () => {
+      const elapsed = (performance.now() - tailStartRef.current) / 1000
+      const t = Math.min(tailBaseRef.current + elapsed, voiceDuration || tailBaseRef.current)
+      setTailCurrentTime(t)
+      tailAudioRef.current.ensurePlayingAt(t)
+      if (t >= (voiceDuration || 0) - 0.05) {
+        tailAudioRef.current.pause()
+        if (playToken != null) onPlayTokenChange?.(null)
+        setTailCurrentTime(null)
+        return
+      }
+      raf = requestAnimationFrame(tick)
+    }
+    raf = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(raf)
+  }, [tailCurrentTime, voiceDuration, playToken, onPlayTokenChange])
+
+  // 呈现给 UI/进度条的「当前时间」：尾段用虚拟时间，否则用视频时间
+  const displayCurrentTime = tailCurrentTime !== null ? tailCurrentTime : currentTime

  const handleSeekTo = useCallback(
    (time: number) => {
-      if (effectiveUseWebCodecs) {
-        canvasControls.seek(time)
-      } else {
-        videoSeekTo(time)
-      }
-      const audio = audioRef.current
-      if (audio && audio.src) {
-        audio.currentTime = time
-      }
+      setTailCurrentTime(null)
+      seekTo(time)
+      audioSeekTo(time)
    },
-    [effectiveUseWebCodecs, canvasControls, videoSeekTo],
+    [seekTo, audioSeekTo],
  )

-  // ── 批量网格播放互斥（#1741）：播放权属于其他实例时，本实例自动暂停（视频+配音） ──
+  // ── 批量网格播放互斥（#1741）：播放权属于其他实例时，本实例自动暂停 ──
  useEffect(() => {
    if (activePlayToken == null || playToken == null || activePlayToken === playToken) return
-    if (effectiveUseWebCodecs) {
-      if (canvasState.isPlaying) canvasControls.pause()
-    } else if (isPlaying) {
-      videoPause()
+    if (isPlaying) {
+      pause()
    }
-    // isPlaying/canvasState.isPlaying 不放依赖：只在 token 变化时执行一次暂停，
-    // token 等于自身时本实例的播放在 handleTogglePlay 里处理
+    // isPlaying 不放依赖：只在 token 变化时执行一次暂停
    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [activePlayToken, playToken, effectiveUseWebCodecs])
+  }, [activePlayToken, playToken])

  const handleTogglePlay = useCallback(() => {
-    if (effectiveUseWebCodecs) {
-      if (canvasState.isPlaying) {
-        canvasControls.pause()
-        onPlayTokenChange?.(null)
-      } else {
-        if (playToken != null) onPlayTokenChange?.(playToken)
-        canvasControls.play()
-      }
-    } else {
-      // video fallback：先上报播放权（暂停其他卡片），再切换本卡片播放/暂停
-      if (playToken != null) onPlayTokenChange?.(isPlaying ? null : playToken)
-      videoTogglePlayPause()
-    }
+    if (playToken != null) onPlayTokenChange?.(isPlaying ? null : playToken)
+    togglePlayPause()
+  }, [togglePlayPause, isPlaying, playToken, onPlayTokenChange])
+
+  // P0 fix：音画同步看门狗——有配音时播放时间达到配音时长立即暂停视频+音频（末帧冻结）
+  useEffect(() => {
+    if (!isPlaying) return
+    if (!voiceAudioUrl || voiceDuration <= 0) return
+    if (displayCurrentTime < voiceDuration - 0.08) return
+    pause()
+    audioPause()
+    if (playToken != null) onPlayTokenChange?.(null)
  }, [
-    effectiveUseWebCodecs,
-    canvasState.isPlaying,
-    canvasControls,
-    videoTogglePlayPause,
    isPlaying,
+    displayCurrentTime,
+    voiceAudioUrl,
+    voiceDuration,
+    pause,
+    audioPause,
    playToken,
    onPlayTokenChange,
  ])

-  // ── 进度条拖拽 ──
-  const [isDragging, setIsDragging] = useState(false)
-  const progressRef = useRef<HTMLDivElement>(null)
-
-  const handleProgressClick = useCallback(
-    (e: React.MouseEvent<HTMLDivElement>) => {
-      if (!progressRef.current || totalDuration <= 0) return
-      const rect = progressRef.current.getBoundingClientRect()
-      const ratio = Math.max(0, Math.min(1, (e.clientX - rect.left) / rect.width))
-      handleSeekTo(ratio * totalDuration)
-    },
-    [totalDuration, handleSeekTo],
-  )
-
-  const handleMouseDown = useCallback(
-    (e: React.MouseEvent<HTMLDivElement>) => {
-      setIsDragging(true)
-      handleProgressClick(e)
-    },
-    [handleProgressClick],
-  )
-
-  useEffect(() => {
-    if (!isDragging) return
-    const handleMouseMove = (e: MouseEvent) => {
-      if (!progressRef.current || totalDuration <= 0) return
-      const rect = progressRef.current.getBoundingClientRect()
-      const ratio = Math.max(0, Math.min(1, (e.clientX - rect.left) / rect.width))
-      handleSeekTo(ratio * totalDuration)
-    }
-    const handleMouseUp = () => setIsDragging(false)
-    window.addEventListener("mousemove", handleMouseMove)
-    window.addEventListener("mouseup", handleMouseUp)
-    return () => {
-      window.removeEventListener("mousemove", handleMouseMove)
-      window.removeEventListener("mouseup", handleMouseUp)
-    }
-  }, [isDragging, totalDuration, handleSeekTo])
-
-  const progressPercent = totalDuration > 0 ? (currentTime / totalDuration) * 100 : 0
-
-  // ── Canvas 容器 ref（保留声明，WebCodecs 兜底路径仍引用） ──
-  const canvasContainerRef = useRef<HTMLDivElement>(null)
-
  // ── 未就绪 ──
  if (!ready || !assets.length) {
    return (
@@ -529,7 +431,6 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({

  // ── 无播放片段 ──
  if (!canPlay) {
-    const showDecodeError = forceVideoFallback && canvasState.hasDecodeError
    return (
      <div
        style={{
@@ -549,48 +450,15 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
          padding: 24,
        }}
      >
-        {isBuffering ? (
-          <>
-            <LoadingOutlined style={{ fontSize: 40, color: "#fff", marginBottom: 12 }} spin />
-            <p style={{ color: "rgba(255,255,255,0.8)", fontSize: 14, margin: 0 }}>加载中...</p>
-          </>
-        ) : showDecodeError ? (
-          <>
-            <PlayCircleOutlined style={{ fontSize: 40, color: "#ef4444", marginBottom: 12 }} />
-            <p
-              style={{
-                color: "rgba(255,255,255,0.9)",
-                fontSize: 14,
-                margin: "0 0 4px",
-                fontWeight: 500,
-              }}
-            >
-              视频解码失败
-            </p>
-            <p
-              style={{
-                color: "rgba(255,255,255,0.5)",
-                fontSize: 12,
-                margin: 0,
-                textAlign: "center",
-              }}
-            >
-              {canvasState.errorMessage || "当前浏览器不支持该视频编码格式，请刷新重试"}
-            </p>
-          </>
-        ) : (
-          <>
-            <PlayCircleOutlined
-              style={{ fontSize: 40, color: "rgba(255,255,255,0.3)", marginBottom: 12 }}
-            />
-            <p style={{ color: "rgba(255,255,255,0.6)", fontSize: 14, margin: "0 0 4px" }}>
-              暂无可播放素材
-            </p>
-            <p style={{ color: "rgba(255,255,255,0.35)", fontSize: 12, margin: 0 }}>
-              请先在左侧选择素材
-            </p>
-          </>
-        )}
+        <PlayCircleOutlined
+          style={{ fontSize: 40, color: "rgba(255,255,255,0.3)", marginBottom: 12 }}
+        />
+        <p style={{ color: "rgba(255,255,255,0.6)", fontSize: 14, margin: "0 0 4px" }}>
+          暂无可播放素材
+        </p>
+        <p style={{ color: "rgba(255,255,255,0.35)", fontSize: 12, margin: 0 }}>
+          请先在左侧选择素材
+        </p>
      </div>
    )
  }
@@ -612,53 +480,30 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
          : "0 4px 6px -1px rgba(0,0,0,0.3), 0 20px 50px -12px rgba(0,0,0,0.5), inset 0 0 0 1px rgba(255,255,255,0.06)",
      }}
    >
-      {/* ── Canvas 渲染层（WebCodecs 路径） ── */}
-      {effectiveUseWebCodecs && (
-        <div
-          ref={canvasContainerRef}
+      {/* ── Video 渲染层（默认路径，浏览器原生硬件解码） ── */}
+      {segments.map((seg, i) => (
+        <video
+          key={seg.assetId}
+          ref={(el) => {
+            videoRefs.current[i] = el
+          }}
+          preload="auto"
+          src={seg.videoUrl}
          style={{
            position: "absolute",
            inset: 0,
-            zIndex: 1,
+            width: "100%",
+            height: "100%",
+            objectFit: "cover",
            background: "#000",
+            zIndex: 1,
+            opacity: i === currentSegmentIndex ? 1 : 0,
+            pointerEvents: i === currentSegmentIndex ? "auto" : "none",
          }}
-        >
-          <canvas
-            ref={canvasRef}
-            style={{
-              width: "100%",
-              height: "100%",
-              objectFit: "cover",
-            }}
-          />
-        </div>
-      )}
-
-      {/* ── Video 渲染层（默认路径，浏览器原生硬件解码） ── */}
-      {!effectiveUseWebCodecs &&
-        segments.map((seg, i) => (
-          <video
-            key={seg.assetId}
-            muted={hasVoice || muted}
-            ref={(el) => {
-              videoRefs.current[i] = el
-            }}
-            preload="auto"
-            src={seg.videoUrl}
-            style={{
-              position: "absolute",
-              inset: 0,
-              width: "100%",
-              height: "100%",
-              objectFit: "cover",
-              background: "#000",
-              zIndex: 1,
-              opacity: i === videoCurrentSegIdx ? 1 : 0,
-              pointerEvents: i === videoCurrentSegIdx ? "auto" : "none",
-            }}
-            playsInline
-          />
-        ))}
+          muted={hasVoice || muted}
+          playsInline
+        />
+      ))}

      {/* 标题CSS叠加层 — 与后端 ASS 烧录坐标系 1:1 对齐 */}
      {titleSettings?.title && (
@@ -735,200 +580,19 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
        </div>
      )}

-      {/* 中央播放按钮 */}
-      {!isPlaying && (
-        <button
-          onClick={handleTogglePlay}
-          style={{
-            position: "absolute",
-            top: "50%",
-            left: "50%",
-            transform: "translate(-50%, -50%)",
-            background: "rgba(0,0,0,0.45)",
-            backdropFilter: "blur(12px)",
-            WebkitBackdropFilter: "blur(12px)",
-            border: "1px solid rgba(255,255,255,0.15)",
-            borderRadius: "50%",
-            width: 52,
-            height: 52,
-            cursor: "pointer",
-            display: "flex",
-            alignItems: "center",
-            justifyContent: "center",
-            color: "#fff",
-            fontSize: 26,
-            zIndex: 10,
-            transition: "transform 0.2s ease, background 0.2s ease",
-            boxShadow: "0 4px 20px rgba(0,0,0,0.4)",
-          }}
-          onMouseEnter={(e) => {
-            e.currentTarget.style.transform = "translate(-50%, -50%) scale(1.08)"
-            e.currentTarget.style.background = "rgba(0,0,0,0.6)"
-          }}
-          onMouseLeave={(e) => {
-            e.currentTarget.style.transform = "translate(-50%, -50%) scale(1)"
-            e.currentTarget.style.background = "rgba(0,0,0,0.45)"
-          }}
-        >
-          <PlayCircleOutlined />
-        </button>
-      )}
-
-      {/* 静音/有声切换（#1741）：左上角，默认有声；批量与单视频均可单独静音 */}
-      {segments.length > 0 && (
-        <button
-          type="button"
-          aria-label={muted ? "取消静音" : "静音"}
-          title={muted ? "取消静音" : "静音"}
-          onClick={() => setMuted((m) => !m)}
-          style={{
-            position: "absolute",
-            top: 8,
-            left: 8,
-            width: compact ? 26 : 30,
-            height: compact ? 26 : 30,
-            display: "flex",
-            alignItems: "center",
-            justifyContent: "center",
-            background: "rgba(0,0,0,0.45)",
-            backdropFilter: "blur(8px)",
-            WebkitBackdropFilter: "blur(8px)",
-            border: "1px solid rgba(255,255,255,0.1)",
-            borderRadius: "50%",
-            color: muted ? "rgba(255,255,255,0.45)" : "rgba(255,255,255,0.92)",
-            fontSize: compact ? 13 : 15,
-            cursor: "pointer",
-            zIndex: 10,
-            padding: 0,
-            transition: "background 0.15s, color 0.15s",
-          }}
-          onMouseEnter={(e) => {
-            e.currentTarget.style.background = "rgba(0,0,0,0.65)"
-          }}
-          onMouseLeave={(e) => {
-            e.currentTarget.style.background = "rgba(0,0,0,0.45)"
-          }}
-        >
-          {muted ? <AudioMutedOutlined /> : <AudioOutlined />}
-        </button>
-      )}
-
-      {/* 片段指示器 — 右上角胶囊 */}
-      <div
-        style={{
-          position: "absolute",
-          top: 8,
-          right: 8,
-          background: "rgba(0,0,0,0.45)",
-          backdropFilter: "blur(8px)",
-          WebkitBackdropFilter: "blur(8px)",
-          color: "rgba(255,255,255,0.9)",
-          fontSize: compact ? 9 : 10,
-          fontWeight: 500,
-          padding: compact ? "1px 6px" : "2px 8px",
-          borderRadius: 999,
-          zIndex: 10,
-          border: "1px solid rgba(255,255,255,0.1)",
-          letterSpacing: 0.3,
-        }}
-      >
-        {`${videoCurrentSegIdx + 1} / ${segments.length}`}
-      </div>
-
-      {/* 控制条 — 手机风格毛玻璃 */}
-      <div
-        style={{
-          position: "absolute",
-          bottom: 0,
-          left: 0,
-          right: 0,
-          display: "flex",
-          alignItems: "center",
-          gap: compact ? 6 : 10,
-          padding: compact ? "8px 10px 10px" : "12px 16px 16px",
-          background: "linear-gradient(transparent, rgba(0,0,0,0.7))",
-          backdropFilter: "blur(4px)",
-          WebkitBackdropFilter: "blur(4px)",
-          zIndex: 10,
-        }}
-      >
-        <button
-          onClick={handleTogglePlay}
-          style={{
-            background: "rgba(255,255,255,0.15)",
-            border: "none",
-            color: "#fff",
-            fontSize: compact ? 14 : 16,
-            cursor: "pointer",
-            width: compact ? 26 : 32,
-            height: compact ? 26 : 32,
-            borderRadius: "50%",
-            display: "flex",
-            alignItems: "center",
-            justifyContent: "center",
-            flexShrink: 0,
-            transition: "background 0.15s",
-          }}
-          onMouseEnter={(e) => {
-            e.currentTarget.style.background = "rgba(255,255,255,0.25)"
-          }}
-          onMouseLeave={(e) => {
-            e.currentTarget.style.background = "rgba(255,255,255,0.15)"
-          }}
-        >
-          {isPlaying ? <PauseCircleOutlined /> : <PlayCircleOutlined />}
-        </button>
-
-        <span
-          style={{
-            fontSize: compact ? 10 : 11,
-            color: "rgba(255,255,255,0.85)",
-            minWidth: compact ? 58 : 72,
-            fontVariantNumeric: "tabular-nums",
-            letterSpacing: 0.2,
-          }}
-        >
-          {formatTime(currentTime)} / {formatTime(totalDuration)}
-        </span>
-
-        <div
-          ref={progressRef}
-          onMouseDown={handleMouseDown}
-          style={{
-            flex: 1,
-            height: 3,
-            background: "rgba(255,255,255,0.2)",
-            borderRadius: 2,
-            cursor: "pointer",
-            position: "relative",
-          }}
-        >
-          <div
-            style={{
-              height: "100%",
-              width: `${progressPercent}%`,
-              background: "#fff",
-              borderRadius: 2,
-              transition: isDragging ? "none" : "width 0.1s linear",
-            }}
-          />
-          <div
-            style={{
-              position: "absolute",
-              top: "50%",
-              left: `${progressPercent}%`,
-              transform: "translate(-50%, -50%)",
-              width: 10,
-              height: 10,
-              borderRadius: "50%",
-              background: "#fff",
-              boxShadow: "0 0 6px rgba(255,255,255,0.5)",
-              opacity: isDragging ? 1 : 0,
-              transition: "opacity 0.15s",
-            }}
-          />
-        </div>
-      </div>
+      <PreviewControls
+        isPlaying={isPlaying}
+        onTogglePlay={handleTogglePlay}
+        muted={muted}
+        onToggleMute={() => setMuted((m) => !m)}
+        hasSegments={segments.length > 0}
+        segmentIndex={currentSegmentIndex}
+        segmentCount={segments.length}
+        currentTime={displayCurrentTime}
+        totalDuration={effectiveTotalDuration}
+        onSeek={handleSeekTo}
+        compact={compact}
+      />
    </div>
  )
 }
@@ -0,0 +1,195 @@
+import React from "react"
+import {
+  PlayCircleOutlined,
+  PauseCircleOutlined,
+  AudioOutlined,
+  AudioMutedOutlined,
+} from "@ant-design/icons"
+import { PreviewProgressBar } from "./PreviewProgressBar"
+
+interface PreviewControlsProps {
+  isPlaying: boolean
+  onTogglePlay: () => void
+  muted: boolean
+  onToggleMute: () => void
+  hasSegments: boolean
+  segmentIndex: number
+  segmentCount: number
+  currentTime: number
+  totalDuration: number
+  onSeek: (time: number) => void
+  compact?: boolean
+}
+
+/**
+ * 播放控制 UI 组件（静音按钮 / 片段指示器 / 中央播放按钮 / 底部毛玻璃控制条）
+ */
+export const PreviewControls: React.FC<PreviewControlsProps> = ({
+  isPlaying,
+  onTogglePlay,
+  muted,
+  onToggleMute,
+  hasSegments,
+  segmentIndex,
+  segmentCount,
+  currentTime,
+  totalDuration,
+  onSeek,
+  compact = false,
+}) => {
+  return (
+    <>
+      {/* 静音/有声切换（#1741）：左上角 */}
+      {hasSegments && (
+        <button
+          type="button"
+          aria-label={muted ? "取消静音" : "静音"}
+          title={muted ? "取消静音" : "静音"}
+          onClick={onToggleMute}
+          style={{
+            position: "absolute",
+            top: 8,
+            left: 8,
+            width: compact ? 26 : 30,
+            height: compact ? 26 : 30,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            background: "rgba(0,0,0,0.45)",
+            backdropFilter: "blur(8px)",
+            WebkitBackdropFilter: "blur(8px)",
+            border: "1px solid rgba(255,255,255,0.1)",
+            borderRadius: "50%",
+            color: muted ? "rgba(255,255,255,0.45)" : "rgba(255,255,255,0.92)",
+            fontSize: compact ? 13 : 15,
+            cursor: "pointer",
+            zIndex: 10,
+            padding: 0,
+            transition: "background 0.15s, color 0.15s",
+          }}
+          onMouseEnter={(e) => {
+            e.currentTarget.style.background = "rgba(0,0,0,0.65)"
+          }}
+          onMouseLeave={(e) => {
+            e.currentTarget.style.background = "rgba(0,0,0,0.45)"
+          }}
+        >
+          {muted ? <AudioMutedOutlined /> : <AudioOutlined />}
+        </button>
+      )}
+
+      {/* 片段指示器 — 右上角胶囊 */}
+      <div
+        style={{
+          position: "absolute",
+          top: 8,
+          right: 8,
+          background: "rgba(0,0,0,0.45)",
+          backdropFilter: "blur(8px)",
+          WebkitBackdropFilter: "blur(8px)",
+          color: "rgba(255,255,255,0.9)",
+          fontSize: compact ? 9 : 10,
+          fontWeight: 500,
+          padding: compact ? "1px 6px" : "2px 8px",
+          borderRadius: 999,
+          zIndex: 10,
+          border: "1px solid rgba(255,255,255,0.1)",
+          letterSpacing: 0.3,
+        }}
+      >
+        {`${segmentIndex + 1} / ${segmentCount}`}
+      </div>
+
+      {/* 中央播放按钮 */}
+      {!isPlaying && (
+        <button
+          onClick={onTogglePlay}
+          style={{
+            position: "absolute",
+            top: "50%",
+            left: "50%",
+            transform: "translate(-50%, -50%)",
+            background: "rgba(0,0,0,0.45)",
+            backdropFilter: "blur(12px)",
+            WebkitBackdropFilter: "blur(12px)",
+            border: "1px solid rgba(255,255,255,0.15)",
+            borderRadius: "50%",
+            width: 52,
+            height: 52,
+            cursor: "pointer",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            color: "#fff",
+            fontSize: 26,
+            zIndex: 10,
+            transition: "transform 0.2s ease, background 0.2s ease",
+            boxShadow: "0 4px 20px rgba(0,0,0,0.4)",
+          }}
+          onMouseEnter={(e) => {
+            e.currentTarget.style.transform = "translate(-50%, -50%) scale(1.08)"
+            e.currentTarget.style.background = "rgba(0,0,0,0.6)"
+          }}
+          onMouseLeave={(e) => {
+            e.currentTarget.style.transform = "translate(-50%, -50%) scale(1)"
+            e.currentTarget.style.background = "rgba(0,0,0,0.45)"
+          }}
+        >
+          <PlayCircleOutlined />
+        </button>
+      )}
+
+      {/* 控制条 — 手机风格毛玻璃 */}
+      <div
+        style={{
+          position: "absolute",
+          bottom: 0,
+          left: 0,
+          right: 0,
+          display: "flex",
+          alignItems: "center",
+          gap: compact ? 6 : 10,
+          padding: compact ? "8px 10px 10px" : "12px 16px 16px",
+          background: "linear-gradient(transparent, rgba(0,0,0,0.7))",
+          backdropFilter: "blur(4px)",
+          WebkitBackdropFilter: "blur(4px)",
+          zIndex: 10,
+        }}
+      >
+        <button
+          onClick={onTogglePlay}
+          style={{
+            background: "rgba(255,255,255,0.15)",
+            border: "none",
+            color: "#fff",
+            fontSize: compact ? 14 : 16,
+            cursor: "pointer",
+            width: compact ? 26 : 32,
+            height: compact ? 26 : 32,
+            borderRadius: "50%",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            flexShrink: 0,
+            transition: "background 0.15s",
+          }}
+          onMouseEnter={(e) => {
+            e.currentTarget.style.background = "rgba(255,255,255,0.25)"
+          }}
+          onMouseLeave={(e) => {
+            e.currentTarget.style.background = "rgba(255,255,255,0.15)"
+          }}
+        >
+          {isPlaying ? <PauseCircleOutlined /> : <PlayCircleOutlined />}
+        </button>
+
+        <PreviewProgressBar
+          currentTime={currentTime}
+          totalDuration={totalDuration}
+          onSeek={onSeek}
+          compact={compact}
+        />
+      </div>
+    </>
+  )
+}
@@ -0,0 +1,108 @@
+import React, { useCallback, useEffect, useRef, useState } from "react"
+import { formatDuration } from "../utils/formatDuration"
+
+interface PreviewProgressBarProps {
+  currentTime: number
+  totalDuration: number
+  onSeek: (time: number) => void
+  compact?: boolean
+}
+
+/**
+ * 进度条组件：点击/拖拽 seek
+ */
+export const PreviewProgressBar: React.FC<PreviewProgressBarProps> = ({
+  currentTime,
+  totalDuration,
+  onSeek,
+  compact = false,
+}) => {
+  const progressRef = useRef<HTMLDivElement>(null)
+  const [isDragging, setIsDragging] = useState(false)
+
+  const seekByClientX = useCallback(
+    (clientX: number) => {
+      if (!progressRef.current || totalDuration <= 0) return
+      const rect = progressRef.current.getBoundingClientRect()
+      const ratio = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width))
+      onSeek(ratio * totalDuration)
+    },
+    [totalDuration, onSeek],
+  )
+
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      setIsDragging(true)
+      seekByClientX(e.clientX)
+    },
+    [seekByClientX],
+  )
+
+  useEffect(() => {
+    if (!isDragging) return
+    const handleMouseMove = (e: MouseEvent) => seekByClientX(e.clientX)
+    const handleMouseUp = () => setIsDragging(false)
+    window.addEventListener("mousemove", handleMouseMove)
+    window.addEventListener("mouseup", handleMouseUp)
+    return () => {
+      window.removeEventListener("mousemove", handleMouseMove)
+      window.removeEventListener("mouseup", handleMouseUp)
+    }
+  }, [isDragging, seekByClientX])
+
+  const progressPercent = totalDuration > 0 ? (currentTime / totalDuration) * 100 : 0
+
+  return (
+    <>
+      <span
+        style={{
+          fontSize: compact ? 10 : 11,
+          color: "rgba(255,255,255,0.85)",
+          minWidth: compact ? 58 : 72,
+          fontVariantNumeric: "tabular-nums",
+          letterSpacing: 0.2,
+        }}
+      >
+        {formatDuration(currentTime)} / {formatDuration(totalDuration)}
+      </span>
+
+      <div
+        ref={progressRef}
+        onMouseDown={handleMouseDown}
+        style={{
+          flex: 1,
+          height: 3,
+          background: "rgba(255,255,255,0.2)",
+          borderRadius: 2,
+          cursor: "pointer",
+          position: "relative",
+        }}
+      >
+        <div
+          style={{
+            height: "100%",
+            width: `${progressPercent}%`,
+            background: "#fff",
+            borderRadius: 2,
+            transition: isDragging ? "none" : "width 0.1s linear",
+          }}
+        />
+        <div
+          style={{
+            position: "absolute",
+            top: "50%",
+            left: `${progressPercent}%`,
+            transform: "translate(-50%, -50%)",
+            width: 10,
+            height: 10,
+            borderRadius: "50%",
+            background: "#fff",
+            boxShadow: "0 0 6px rgba(255,255,255,0.5)",
+            opacity: isDragging ? 1 : 0,
+            transition: "opacity 0.15s",
+          }}
+        />
+      </div>
+    </>
+  )
+}
@@ -171,7 +171,6 @@ export function useBatchCovers({
    let okCount = 0
    let failCount = 0
    for (const i of pending) {
-      // eslint-disable-next-line no-await-in-loop
      const ok = await generateOne(i)
      if (ok) okCount += 1
      else failCount += 1
@@ -26,6 +26,8 @@ export interface BatchVariantClipsState {
  clipsByVariant: EditPlanClip[][]
  /** 各变体的 plan_id（正式生成回传，保证预览即成片）；未就绪为空串 */
  planIdsByVariant: string[]
+  /** 各变体的后端返回配音时长（秒）；未就绪/未返回为 undefined */
+  voiceDurationsByVariant: (number | undefined)[]
  /** 是否正在向后端申请变体计划 */
  loading: boolean
  /** 后端真实片段是否全部可用（每个变体都有 ≥1 条片段） */
@@ -44,6 +46,12 @@ interface UseBatchVariantPlansOptions {
  assetIds: string[]
  /** 源剪辑计划 ID（草稿/预览关联），无则空串由后端兜底最新 plan */
  sourcePlanId?: string
+  /** 统一配音 ID（共用配音模式），参考 useGenerateVideo voiceLibraryId 计算 */
+  voiceLibraryId?: string
+  /** 独立配音 ID 列表（每变体一条），voiceModePerVideo=true 时使用 */
+  voiceLibraryIds?: string[]
+  /** 是否启用独立配音模式（每变体各自一条配音） */
+  voiceModePerVideo?: boolean
 }

 export function useBatchVariantPlans({
@@ -52,9 +60,13 @@ export function useBatchVariantPlans({
  templateId,
  assetIds,
  sourcePlanId = "",
+  voiceLibraryId = "",
+  voiceLibraryIds = [],
+  voiceModePerVideo = false,
 }: UseBatchVariantPlansOptions): BatchVariantClipsState {
  const [clipsByVariant, setClipsByVariant] = useState<EditPlanClip[][]>([])
  const [planIdsByVariant, setPlanIdsByVariant] = useState<string[]>([])
+  const [voiceDurationsByVariant, setVoiceDurationsByVariant] = useState<(number | undefined)[]>([])
  const [loading, setLoading] = useState(false)
  const [error, setError] = useState(false)

@@ -70,17 +82,30 @@ export function useBatchVariantPlans({
    setLoading(true)
    setError(false)
    try {
+      // 配音参数：与 useGenerateVideo 保持一致的传参逻辑
+      // - 独立配音模式 + voiceLibraryIds 非空：传 voice_library_ids
+      // - 统一配音：传 voice_library_id
+      // - 都没选：不传
+      const voiceParam: { voice_library_id?: string; voice_library_ids?: string[] } = {}
+      if (voiceModePerVideo && voiceLibraryIds.length > 0) {
+        voiceParam.voice_library_ids = voiceLibraryIds
+      } else if (voiceLibraryId) {
+        voiceParam.voice_library_id = voiceLibraryId
+      }
+
      const resp = await createBatchVariantPlans({
        template_id: templateId,
        asset_ids: assetIds,
        count,
        ...(sourcePlanId ? { source_edit_plan_id: sourcePlanId } : {}),
+        ...voiceParam,
      })
      if (seq !== requestSeqRef.current) return

      const items: VariantPlan[] = Array.isArray(resp.items) ? resp.items : []
      const clips: EditPlanClip[][] = Array.from({ length: count }, () => [])
      const planIds: string[] = Array.from({ length: count }, () => "")
+      const voiceDurs: (number | undefined)[] = Array.from({ length: count }, () => undefined)
      for (const item of items) {
        const idx = item.variant_index
        if (idx < 0 || idx >= count) continue
@@ -88,6 +113,9 @@ export function useBatchVariantPlans({
        clips[idx] = (item.clips || [])
          .filter((c) => c && c.asset_id && c.status === "ready")
          .sort((a, b) => a.order - b.order)
+        if (typeof item.voice_duration === "number" && item.voice_duration > 0) {
+          voiceDurs[idx] = item.voice_duration
+        }
      }
      // 数据完整性校验：每个变体都必须有真实片段，否则视为失败（不允许假数据冒充）
      const incomplete = clips.some((list) => list.length === 0)
@@ -95,10 +123,12 @@ export function useBatchVariantPlans({
        console.warn("[useBatchVariantPlans] 变体计划数据不完整（存在空片段变体），标记加载失败")
        setClipsByVariant([])
        setPlanIdsByVariant([])
+        setVoiceDurationsByVariant([])
        setError(true)
      } else {
        setClipsByVariant(clips)
        setPlanIdsByVariant(planIds)
+        setVoiceDurationsByVariant(voiceDurs)
        setError(false)
      }
    } catch (err) {
@@ -107,11 +137,20 @@ export function useBatchVariantPlans({
      console.warn("[useBatchVariantPlans] 申请变体计划失败，预览加载失败:", err)
      setClipsByVariant([])
      setPlanIdsByVariant([])
+      setVoiceDurationsByVariant([])
      setError(true)
    } finally {
      if (seq === requestSeqRef.current) setLoading(false)
    }
-  }, [templateId, count, sourcePlanId, assetIds])
+  }, [
+    templateId,
+    count,
+    sourcePlanId,
+    assetIds,
+    voiceLibraryId,
+    voiceLibraryIds,
+    voiceModePerVideo,
+  ])

  /** 用户点击「重试」：nonce +1 驱动 effect 重新发起请求（effect 内 lastKey 校验保证只发一次） */
  const retry = useCallback(() => {
@@ -125,24 +164,40 @@ export function useBatchVariantPlans({
      // 避免父组件传入内联字面量数组导致 effect 每次 render 触发 → 无限 setState 循环
      setClipsByVariant((prev) => (prev.length === 0 ? prev : []))
      setPlanIdsByVariant((prev) => (prev.length === 0 ? prev : []))
+      setVoiceDurationsByVariant((prev) => (prev.length === 0 ? prev : []))
      setLoading((prev) => (prev === false ? prev : false))
      setError((prev) => (prev === false ? prev : false))
      lastKeyRef.current = ""
      return
    }
+    const voiceKey = voiceModePerVideo
+      ? `per:${[...voiceLibraryIds].sort().join(",")}`
+      : `one:${voiceLibraryId}`
    const key = `${retryNonce}|${templateId}|${count}|${sourcePlanId}|${[...assetIds]
      .sort()
-      .join(",")}`
+      .join(",")}|${voiceKey}`
    if (key === lastKeyRef.current) return
    lastKeyRef.current = key
    load()
-  }, [enabled, templateId, count, sourcePlanId, assetIds, load, retryNonce])
+  }, [
+    enabled,
+    templateId,
+    count,
+    sourcePlanId,
+    assetIds,
+    load,
+    retryNonce,
+    voiceLibraryId,
+    voiceLibraryIds,
+    voiceModePerVideo,
+  ])

  const ready = !error && !loading && clipsByVariant.every((list) => list.length > 0)

  return {
    clipsByVariant,
    planIdsByVariant,
+    voiceDurationsByVariant,
    loading,
    ready,
    error,
@@ -51,7 +51,6 @@ export function useTitleCoverSync({
        thumbnail_url: tpl.cover_config!.thumbnail_url || prev.thumbnail_url,
      }))
    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [selectedTemplate, setTitleSettings, setCoverSettings])
  // ↑ 移除 userTemplates，只在 selectedTemplate 真正变化时触发
 }
@@ -0,0 +1,131 @@
+import { useCallback, useEffect, useRef } from "react"
+
+interface UsePreviewAudioOptions {
+  voiceAudioUrl: string | undefined
+  voiceDurationHint: number | undefined
+  muted: boolean
+  isPlaying: boolean
+  currentTime: number
+  onVoiceDurationChange: (d: number) => void
+  onEnded: () => void
+}
+
+interface UsePreviewAudioReturn {
+  seekTo: (time: number) => void
+  ensurePlayingAt: (time: number) => void
+  pause: () => void
+}
+
+/**
+ * 配音音频管理 hook：加载配音、loadedmetadata 自测时长、play/pause 同步、
+ * ended 事件回调、seek 同步、末帧冻结期间续播。
+ */
+export function usePreviewAudio({
+  voiceAudioUrl,
+  voiceDurationHint,
+  muted,
+  isPlaying,
+  currentTime,
+  onVoiceDurationChange,
+  onEnded,
+}: UsePreviewAudioOptions): UsePreviewAudioReturn {
+  const audioRef = useRef<HTMLAudioElement | null>(null)
+  const prevIsPlayingRef = useRef(false)
+
+  // 外部 hint 初始化（自测值前的兜底）
+  useEffect(() => {
+    if (voiceDurationHint && voiceDurationHint > 0) {
+      onVoiceDurationChange(voiceDurationHint)
+    }
+  }, [voiceDurationHint, onVoiceDurationChange])
+
+  // 创建/替换 audio 元素，加载 metadata 时自测时长并监听 ended
+  useEffect(() => {
+    if (!voiceAudioUrl) {
+      if (audioRef.current) {
+        audioRef.current.pause()
+        audioRef.current.src = ""
+        audioRef.current = null
+      }
+      return
+    }
+    if (!audioRef.current) {
+      audioRef.current = new Audio()
+      audioRef.current.preload = "auto"
+    }
+    if (audioRef.current.src !== voiceAudioUrl) {
+      audioRef.current.src = voiceAudioUrl
+    }
+    audioRef.current.muted = muted
+
+    const audio = audioRef.current
+    const onLoaded = () => {
+      if (audio.duration && isFinite(audio.duration) && audio.duration > 0) {
+        onVoiceDurationChange(audio.duration)
+      }
+    }
+    const onEndedHandler = () => onEnded()
+    audio.addEventListener("loadedmetadata", onLoaded)
+    audio.addEventListener("ended", onEndedHandler)
+    return () => {
+      audio.removeEventListener("loadedmetadata", onLoaded)
+      audio.removeEventListener("ended", onEndedHandler)
+    }
+  }, [voiceAudioUrl, muted, onVoiceDurationChange, onEnded])
+
+  // mute 变化即时同步
+  useEffect(() => {
+    if (audioRef.current) audioRef.current.muted = muted
+  }, [muted])
+
+  // 播放/暂停同步（跟随视频 isPlaying）
+  useEffect(() => {
+    const audio = audioRef.current
+    if (!audio || !audio.src) return
+    if (isPlaying && !prevIsPlayingRef.current) {
+      if (Math.abs(audio.currentTime - currentTime) > 0.3) {
+        try {
+          audio.currentTime = currentTime
+        } catch {
+          /* ignore */
+        }
+      }
+      audio.play().catch(() => {})
+    } else if (!isPlaying && prevIsPlayingRef.current) {
+      audio.pause()
+    }
+    prevIsPlayingRef.current = isPlaying
+  }, [isPlaying, currentTime])
+
+  const seekTo = useCallback((time: number) => {
+    const audio = audioRef.current
+    if (audio && audio.src) {
+      try {
+        audio.currentTime = time
+      } catch {
+        /* ignore */
+      }
+    }
+  }, [])
+
+  const ensurePlayingAt = useCallback((time: number) => {
+    const audio = audioRef.current
+    if (!audio || !audio.src) return
+    try {
+      if (Math.abs(audio.currentTime - time) > 0.5) audio.currentTime = time
+      if (audio.paused) audio.play().catch(() => {})
+    } catch {
+      /* ignore */
+    }
+  }, [])
+
+  const pause = useCallback(() => {
+    try {
+      audioRef.current?.pause()
+    } catch {
+      /* ignore */
+    }
+  }, [])
+
+  return { seekTo, ensurePlayingAt, pause }
+}
@@ -125,7 +125,6 @@ export function useVariantVoicePreview({
          continue
        }
        try {
-          // eslint-disable-next-line no-await-in-loop
          const res = await previewTts({ text: job.title, voice_id: job.voiceId })
          if (cancelled || controller.signal.aborted || seq !== seqRef.current) return
          const audioUrl = res.audio_url || ""
@@ -1,7 +1,7 @@
 /**
 * FrontendPreviewPlayer 音频行为单测（Issue #1741 / #1750）
 *
- * useSegmentScheduler/useCanvasPlayer 用 mock 控制播放态，专注验证本组件的音频逻辑：
+ * useSegmentScheduler 用 mock 控制播放态，专注验证本组件的音频逻辑：
 * - 有配音时 video 保持 muted（素材原声不与配音混音）
 * - 无配音时 video 不 muted（素材原声兜底，保证任何情况下播放有声）
 * - 静音按钮：默认有声；点击后切 muted，aria-label 与图标切换
@@ -2301,13 +2301,13 @@ class UnifiedRenderService:
                    filters.append(f"eq=contrast={contrast:.3f}")

            elif filt == "color_balance":
-                # RGB 通道偏移：color_balance=rs=...:gs=...:bs=...
+                # RGB 通道偏移：colorbalance=rs=...:gs=...:bs=...
                r = pixel_pert.get("color_r", 0)
                g = pixel_pert.get("color_g", 0)
                b = pixel_pert.get("color_b", 0)
                if r != 0 or g != 0 or b != 0:
                    # color_balance 参数范围 -1.0 ~ 1.0，这里用 /100 转换
-                    filters.append(f"color_balance=rs={r/100:.3f}:gs={g/100:.3f}:bs={b/100:.3f}")
+                    filters.append(f"colorbalance=rs={r/100:.3f}:gs={g/100:.3f}:bs={b/100:.3f}")

    @staticmethod
    def _clip_volume(clip: ResolvedClip) -> float:
@@ -0,0 +1,259 @@
+"""generation_common 公共服务辅助函数单元测试。
+
+覆盖 query_voice_durations / writeback_edit_plan_config / collect_plan_segments /
+resolve_latest_plan_by_template 四个下沉函数的主路径、边界与容错路径。
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# query_voice_durations
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+class TestQueryVoiceDurations:
+    def _make_db_with_rows(self, rows):
+        """构造 MagicMock db，query().filter().all() 返回 rows。"""
+        db = MagicMock()
+        db.query.return_value.filter.return_value.all.return_value = list(rows)
+        return db
+
+    def test_empty_input_returns_empty_list(self):
+        from app.services.generation_common import query_voice_durations
+
+        db = MagicMock()
+        assert query_voice_durations(db, []) == []
+        assert query_voice_durations(db, None) == []
+        db.query.assert_not_called()
+
+    def test_all_empty_or_falsy_ids_returns_zero_list(self):
+        from app.services.generation_common import query_voice_durations
+
+        db = MagicMock()
+        assert query_voice_durations(db, ["", None, ""]) == [0.0, 0.0, 0.0]
+
+    def test_normal_lookup_returns_durations_in_input_order(self):
+        from app.services.generation_common import query_voice_durations
+
+        db = self._make_db_with_rows([("v1", 3.5), ("v2", 7.2)])
+        result = query_voice_durations(db, ["v1", "v2", "v-missing"])
+        assert result == [3.5, 7.2, 0.0]
+
+    def test_duplicate_ids_returns_consistent_durations_preserves_order(self):
+        """#1855：同配音 id 多次出现应返回相同时长，保持输入顺序/长度。"""
+        from app.services.generation_common import query_voice_durations
+
+        db = self._make_db_with_rows([("v1", 4.0)])
+        result = query_voice_durations(db, ["v1", "v1", "v1"])
+        assert result == [4.0, 4.0, 4.0]
+
+    def test_non_numeric_duration_coerced_to_zero(self):
+        from app.services.generation_common import query_voice_durations
+
+        db = self._make_db_with_rows([("v1", None), ("v2", "not-a-number"), ("v3", 2.0)])
+        result = query_voice_durations(db, ["v1", "v2", "v3"])
+        assert result == [0.0, 0.0, 2.0]
+
+    def test_db_exception_returns_zeros_and_logs(self, caplog):
+        from app.services.generation_common import query_voice_durations
+
+        db = MagicMock()
+        db.query.side_effect = RuntimeError("DB boom")
+        with caplog.at_level("WARNING"):
+            result = query_voice_durations(db, ["v1", "v2"])
+        assert result == [0.0, 0.0]
+        assert any("配音时长查询失败" in rec.message for rec in caplog.records)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# writeback_edit_plan_config
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def _make_plan_model(config=None):
+    plan = MagicMock()
+    plan.config = config if config is not None else {}
+    return plan
+
+
+class TestWritebackEditPlanConfig:
+    def test_empty_plan_id_returns_immediately(self):
+        from app.services.generation_common import writeback_edit_plan_config
+
+        db = MagicMock()
+        writeback_edit_plan_config("", "task1", None, db)
+        db.query.assert_not_called()
+
+    def test_plan_not_found_logs_and_returns(self, caplog):
+        from app.services.generation_common import writeback_edit_plan_config
+
+        db = MagicMock()
+        db.query.return_value.filter.return_value.first.return_value = None
+        with caplog.at_level("WARNING"):
+            writeback_edit_plan_config("p999", "task1", None, db)
+        db.commit.assert_not_called()
+        assert any("plan不存在" in rec.message for rec in caplog.records)
+
+    def test_writes_task_id_preserves_existing_config(self):
+        from app.services.generation_common import writeback_edit_plan_config
+
+        plan = _make_plan_model({"other": "keep-me"})
+        db = MagicMock()
+        db.query.return_value.filter.return_value.first.return_value = plan
+        writeback_edit_plan_config("p1", "task-xyz", None, db)
+        assert plan.config["generation_task_id"] == "task-xyz"
+        assert plan.config["other"] == "keep-me"
+        assert "title_config" not in plan.config
+        db.commit.assert_called_once()
+
+    def test_merges_title_config_without_title_change(self):
+        from app.services.generation_common import writeback_edit_plan_config
+
+        plan = _make_plan_model({"title_config": {"text": "old"}, "cover": "x"})
+        db = MagicMock()
+        db.query.return_value.filter.return_value.first.return_value = plan
+        writeback_edit_plan_config("p1", "t1", {"text": "old"}, db)
+        assert plan.config["title_config"] == {"text": "old"}
+        # 标题未变 → cover 保留
+        assert plan.config.get("cover") == "x"
+
+    def test_title_change_clears_cover(self):
+        from app.services.generation_common import writeback_edit_plan_config
+
+        plan = _make_plan_model({"title_config": {"text": "old"}, "cover": "x"})
+        db = MagicMock()
+        db.query.return_value.filter.return_value.first.return_value = plan
+        writeback_edit_plan_config("p1", "t1", {"text": "new-title"}, db)
+        assert "cover" not in plan.config
+        assert plan.config["title_config"] == {"text": "new-title"}
+
+    def test_config_not_dict_treated_as_empty(self):
+        from app.services.generation_common import writeback_edit_plan_config
+
+        plan = _make_plan_model(config=None)
+        db = MagicMock()
+        db.query.return_value.filter.return_value.first.return_value = plan
+        writeback_edit_plan_config("p1", "t1", {"text": "hi"}, db)
+        assert plan.config["generation_task_id"] == "t1"
+        assert plan.config["title_config"] == {"text": "hi"}
+
+    def test_exception_triggers_rollback_and_logs(self, caplog):
+        from app.services.generation_common import writeback_edit_plan_config
+
+        db = MagicMock()
+        db.query.return_value.filter.return_value.first.side_effect = RuntimeError("fail")
+        with caplog.at_level("WARNING"):
+            writeback_edit_plan_config("p1", "t1", None, db)
+        db.rollback.assert_called_once()
+        assert any("回写plan.config异常" in rec.message for rec in caplog.records)
+
+    def test_exception_with_rollback_also_failing_is_safe(self, caplog):
+        """外层异常后，db.rollback() 自己也抛异常时也不应中断（pass 兜底）。"""
+        from app.services.generation_common import writeback_edit_plan_config
+
+        db = MagicMock()
+        db.query.return_value.filter.return_value.first.side_effect = RuntimeError("fail")
+        db.rollback.side_effect = RuntimeError("rollback boom")
+        with caplog.at_level("WARNING"):
+            # 不应抛出异常
+            writeback_edit_plan_config("p1", "t1", None, db)
+        assert any("回写plan.config异常" in rec.message for rec in caplog.records)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# collect_plan_segments
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+def _make_clip(asset_id, start, duration):
+    c = MagicMock()
+    c.asset_id = asset_id
+    c.start_time = start
+    c.duration = duration
+    return c
+
+
+class TestCollectPlanSegments:
+    def test_empty_plan_returns_empty(self):
+        from app.services.generation_common import collect_plan_segments
+
+        repo = MagicMock()
+        repo.list_by_plan.return_value = []
+        assert collect_plan_segments("p1", repo) == {}
+
+    def test_single_page_collects_segments(self):
+        from app.services.generation_common import collect_plan_segments
+
+        repo = MagicMock()
+        repo.list_by_plan.side_effect = [
+            [_make_clip("a1", 0.0, 5.0), _make_clip("a1", 10.0, 3.0), _make_clip("a2", 2.0, 4.0)],
+            [],
+        ]
+        segs = collect_plan_segments("p1", repo, page_size=500)
+        assert segs["a1"] == [(0.0, 5.0), (10.0, 13.0)]
+        assert segs["a2"] == [(2.0, 6.0)]
+
+    def test_pagination_walks_all_batches(self):
+        from app.services.generation_common import collect_plan_segments
+
+        repo = MagicMock()
+        page1 = [_make_clip("a1", 0.0, 1.0)] * 2
+        page2 = [_make_clip("a2", 0.0, 2.0)] * 2
+        page3 = [_make_clip("a3", 0.0, 1.0)]  # short final batch → stop
+        repo.list_by_plan.side_effect = [page1, page2, page3]
+        segs = collect_plan_segments("p1", repo, page_size=2)
+        assert set(segs.keys()) == {"a1", "a2", "a3"}
+        assert repo.list_by_plan.call_count == 3
+
+    def test_skips_zero_or_negative_duration_clips(self):
+        from app.services.generation_common import collect_plan_segments
+
+        repo = MagicMock()
+        repo.list_by_plan.side_effect = [
+            [_make_clip(None, 0.0, 5.0), _make_clip("a1", 0.0, 0.0), _make_clip("a1", 1.0, -1.0)],
+            [],
+        ]
+        assert collect_plan_segments("p1", repo) == {}
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# resolve_latest_plan_by_template
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+class TestResolveLatestPlanByTemplate:
+    @pytest.mark.parametrize("tid", ["", None, "   "])
+    def test_empty_template_returns_none(self, tid):
+        from app.services.generation_common import resolve_latest_plan_by_template
+
+        db = MagicMock()
+        assert resolve_latest_plan_by_template(db, template_id=tid, user_id="u1") is None
+        db.query.assert_not_called()
+
+    def test_returns_latest_plan_id(self):
+        from app.services.generation_common import resolve_latest_plan_by_template
+
+        db = MagicMock()
+        latest = MagicMock(id="plan-xyz")
+        db.query.return_value.filter.return_value.order_by.return_value.first.return_value = latest
+        assert resolve_latest_plan_by_template(db, template_id=" tpl1 ", user_id="u1") == "plan-xyz"
+
+    def test_no_plan_returns_none(self):
+        from app.services.generation_common import resolve_latest_plan_by_template
+
+        db = MagicMock()
+        db.query.return_value.filter.return_value.order_by.return_value.first.return_value = None
+        assert resolve_latest_plan_by_template(db, template_id="tpl", user_id="u") is None
+
+    def test_db_exception_returns_none_and_logs(self, caplog):
+        from app.services.generation_common import resolve_latest_plan_by_template
+
+        db = MagicMock()
+        db.query.side_effect = RuntimeError("boom")
+        with caplog.at_level("WARNING"):
+            assert resolve_latest_plan_by_template(db, template_id="tpl", user_id="u") is None
+        assert any("查找最新plan失败" in rec.message for rec in caplog.records)