refactor(duplication-detail): 三阶段重构 DuplicationDetail（323→110行, -66%）

- Phase 1: 抽 constants（RISK_DESC/RISK_LABEL/ToastState）+ utils（formatTime/formatSize/formatDuration/getRiskLevel）
- Phase 2: 抽 4 个 UI 组件（RiskCard/InfoCard/SegmentsSection/SegmentCard）
- Phase 3: 抽 useDuplicationDetail 业务 Hook
- 主文件 323→110 行，职责清晰

.gitea/workflows/acr-cleanup.yml

@@ -36,12 +36,11 @@ jobs:
       GITEA_REPO: xiaoxia/xiaoxia-saas
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.12'
+        shell: sh
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          curl -sH "Authorization: token $GITHUB_TOKEN"             "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}"             | bash
 
       # ====== Cron模式：获取staging运行中镜像作为白名单 ======
       - name: Get staging running images (whitelist)

.gitea/workflows/daily-check.yml

@@ -1,4 +1,5 @@
 name: Daily Health Check
+# 注意：使用 curl step_checkout.sh 方式以兼容 docker runner
 
 on:
   schedule:
@@ -23,47 +24,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ github.token }}
         run: |
-          set -eu
-          python3 - <<'PY'
-          import io, os, tarfile, time, urllib.request, urllib.error
-          url = f"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz"
-          request = urllib.request.Request(url, headers={"Authorization": f"token {os.environ['GITHUB_TOKEN']}"})
-          last_err = None
-          for attempt in range(5):
-              try:
-                  with urllib.request.urlopen(request, timeout=120) as response:
-                      archive = response.read()
-                  break
-              except urllib.error.HTTPError as e:
-                  last_err = e
-                  if e.code >= 500 and attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-              except Exception as e:
-                  last_err = e
-                  if attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-          else:
-              raise last_err
-          with tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:
-              root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'
-              for member in tar.getmembers():
-                  name = member.name
-                  if name == root_prefix[:-1]:
-                      continue
-                  if name.startswith(root_prefix):
-                      member.name = name[len(root_prefix):]
-                  if member.name:
-                      tar.extract(member, '.')
-          PY
-
+          curl -sH "Authorization: token $GITHUB_TOKEN" \
+            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}" \
+            | bash
       - name: Production health check & smoke test
         id: smoke
         shell: sh
@@ -132,47 +95,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ github.token }}
         run: |
-          set -eu
-          python3 - <<'PY'
-          import io, os, tarfile, time, urllib.request, urllib.error
-          url = f"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz"
-          request = urllib.request.Request(url, headers={"Authorization": f"token {os.environ['GITHUB_TOKEN']}"})
-          last_err = None
-          for attempt in range(5):
-              try:
-                  with urllib.request.urlopen(request, timeout=120) as response:
-                      archive = response.read()
-                  break
-              except urllib.error.HTTPError as e:
-                  last_err = e
-                  if e.code >= 500 and attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-              except Exception as e:
-                  last_err = e
-                  if attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-          else:
-              raise last_err
-          with tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:
-              root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'
-              for member in tar.getmembers():
-                  name = member.name
-                  if name == root_prefix[:-1]:
-                      continue
-                  if name.startswith(root_prefix):
-                      member.name = name[len(root_prefix):]
-                  if member.name:
-                      tar.extract(member, '.')
-          PY
-
+          curl -sH "Authorization: token $GITHUB_TOKEN" \
+            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}" \
+            | bash
       - name: Run API smoke test on staging
         id: smoke
         shell: sh
@@ -284,47 +209,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ github.token }}
         run: |
-          set -eu
-          python3 - <<'PY'
-          import io, os, tarfile, time, urllib.request, urllib.error
-          url = f"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz"
-          request = urllib.request.Request(url, headers={"Authorization": f"token {os.environ['GITHUB_TOKEN']}"})
-          last_err = None
-          for attempt in range(5):
-              try:
-                  with urllib.request.urlopen(request, timeout=120) as response:
-                      archive = response.read()
-                  break
-              except urllib.error.HTTPError as e:
-                  last_err = e
-                  if e.code >= 500 and attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-              except Exception as e:
-                  last_err = e
-                  if attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-          else:
-              raise last_err
-          with tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:
-              root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'
-              for member in tar.getmembers():
-                  name = member.name
-                  if name == root_prefix[:-1]:
-                      continue
-                  if name.startswith(root_prefix):
-                      member.name = name[len(root_prefix):]
-                  if member.name:
-                      tar.extract(member, '.')
-          PY
-
+          curl -sH "Authorization: token $GITHUB_TOKEN" \
+            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}" \
+            | bash
       - name: Run Playwright E2E on staging
         id: e2e
         shell: sh

apps/api/app/services/ai_service.py

@@ -12,12 +12,13 @@
 
 from __future__ import annotations
 
-import json
 import logging
-import math
-import random
 from typing import Any, Dict, List, Optional
 
+from packages.domain.ai_parsing import generate_titles_fallback as _generate_titles_fallback_base
+from packages.domain.ai_parsing import keyword_match_fallback as _semantic_match_fallback_base
+from packages.domain.ai_parsing import parse_semantic_match_response as _parse_semantic_match_base
+from packages.domain.ai_parsing import parse_titles_from_response as _parse_titles_from_response
 from packages.shared.ai_client import get_doubao_client
 
 logger = logging.getLogger(__name__)
@@ -64,85 +65,9 @@ def _generate_titles_fallback(
     style: str = "viral",
     count: int = 5,
 ) -> List[str]:
-    """本地降级：基于模板规则生成标题.
-
-    当豆包 API 不可用或调用失败时使用，保证接口始终有返回。
-    """
+    """本地降级：基于模板规则生成标题（薄包装，转发到 ai_parsing 模块）."""
     style_info = TITLE_STYLES.get(style, TITLE_STYLES["viral"])
-    examples = style_info["examples"]
-
-    # 从描述中提取关键词（取前几个词）
-    keywords = [w for w in description.strip().split() if len(w) > 1][:3]
-    keyword = keywords[0] if keywords else "精彩内容"
-
-    # 基于模板生成
-    templates = [
-        f"「{keyword}」{examples[0][:10]}...",
-        f"{keyword}：{examples[1]}",
-        f"关于{keyword}，你不知道的3件事",
-        f"{keyword}入门指南，新手必看",
-        f"深度解析：{keyword}背后的秘密",
-        f"{keyword}怎么做？手把手教你",
-        f"干货分享 | {keyword}全攻略",
-        f"建议收藏：{keyword}实用技巧",
-        f"{keyword}避坑指南，别再踩雷了",
-        f"一分钟搞懂{keyword}",
-    ]
-
-    random.shuffle(templates)
-    return templates[: min(count, len(templates))]
-
-
-def _parse_titles_from_response(content: str) -> List[str]:
-    """从模型返回中解析标题列表.
-
-    支持多种返回格式：
-    - JSON 数组: ["标题1", "标题2"]
-    - 编号列表: 1. 标题1 / 2. 标题2
-    - 换行分隔: 标题1\n标题2
-    - 带破折号: - 标题1
-    """
-    if not content:
-        return []
-
-    # 尝试解析 JSON
-    try:
-        # 清理可能的 markdown 代码块标记
-        cleaned = content.strip()
-        if cleaned.startswith("```"):
-            cleaned = cleaned.strip("`")
-            if cleaned.lower().startswith("json"):
-                cleaned = cleaned[4:]
-            cleaned = cleaned.strip()
-
-        data = json.loads(cleaned)
-        if isinstance(data, list):
-            return [str(item).strip() for item in data if str(item).strip()]
-        if isinstance(data, dict) and "titles" in data:
-            titles = data["titles"]
-            if isinstance(titles, list):
-                return [str(t).strip() for t in titles if str(t).strip()]
-    except (json.JSONDecodeError, ValueError):
-        pass
-
-    # 尝试按行解析
-    titles: List[str] = []
-    for line in content.strip().split("\n"):
-        line = line.strip()
-        if not line:
-            continue
-        # 去掉编号前缀 "1. " "1、" "（1）"
-        import re
-
-        line = re.sub(r"^[\d]+[\.、\)）]\s*", "", line)
-        # 去掉破折号前缀 "- " "• "
-        line = re.sub(r"^[-•·]\s*", "", line)
-        # 去掉引号
-        line = line.strip('"').strip("'").strip("「」")
-        if line and len(line) < 100:  # 过滤过长的行
-            titles.append(line)
-
-    return titles
+    return _generate_titles_fallback_base(description, style_info, count)
 
 
 def generate_smart_titles(
@@ -241,132 +166,19 @@ def _semantic_match_fallback(
     description: str,
     assets: List[Dict[str, Any]],
 ) -> List[Dict[str, Any]]:
-    """本地降级：基于关键词的简单匹配.
-
-    计算描述中的关键词与素材名称/标签/描述的重叠度，
-    作为匹配度评分。0-1分。
-    """
-    import re
-
-    # 提取关键词（中文按2字以上片段，英文按单词）
-    desc = description.lower()
-    # 简单分词：提取2字以上的中文字符串和英文单词
-    keywords = set()
-    # 英文单词
-    for word in re.findall(r"[a-zA-Z]{3,}", desc):
-        keywords.add(word)
-    # 中文2-4字片段
-    for i in range(len(desc)):
-        for j in range(i + 2, min(i + 5, len(desc) + 1)):
-            fragment = desc[i:j]
-            if all("\u4e00" <= c <= "\u9fff" for c in fragment):
-                keywords.add(fragment)
-
-    if not keywords:
-        # 没有关键词时给所有素材中等分数
-        for asset in assets:
-            asset["match_score"] = 0.5
-            asset["match_reason"] = "fallback_default"
-        return assets
-
-    results = []
-    for asset in assets:
-        # 组合素材的文本信息：名称 + 标签 + 描述
-        asset_text_parts = [
-            str(asset.get("name", "")).lower(),
-            " ".join(str(t) for t in asset.get("tags", [])).lower(),
-            str(asset.get("description", "")).lower(),
-        ]
-        asset_text = " | ".join(asset_text_parts)
-
-        # 计算匹配度：命中关键词占比 + 稀有关键词加权
-        hit_count = 0
-        hit_keywords = []
-        for kw in keywords:
-            if kw in asset_text:
-                hit_count += 1
-                hit_keywords.append(kw)
-
-        # 基础匹配度 = 命中关键词数 / 总关键词数（开根号平滑）
-        base_score = math.sqrt(hit_count / len(keywords)) if keywords else 0.5
-
-        # 名称命中加分（名称匹配更重要）
-        name = str(asset.get("name", "")).lower()
-        name_hits = sum(1 for kw in hit_keywords if kw in name)
-        name_bonus = min(0.2, name_hits * 0.05)
-
-        score = min(1.0, base_score * 0.8 + name_bonus)
-        score = round(score, 3)
-
-        results.append(
-            {
-                **asset,
-                "match_score": score,
-                "match_reason": "fallback_keyword",
-            }
-        )
-
-    # 按匹配度降序
-    results.sort(key=lambda x: x["match_score"], reverse=True)
-    return results
+    """本地降级：基于关键词的简单匹配（薄包装，转发到 ai_parsing 模块）."""
+    return _semantic_match_fallback_base(description, assets)
 
 
 def _parse_semantic_match_response(
     content: str,
     asset_ids: List[str],
 ) -> Optional[Dict[str, float]]:
-    """从模型返回中解析素材匹配度.
-
-    期望格式：JSON 对象 {asset_id: score} 或 {"matches": [{asset_id, score}]}
-    score 范围 0-1。
-    """
-    if not content:
+    """从模型返回中解析素材匹配度（薄包装，转发到 ai_parsing 模块）."""
+    result = _parse_semantic_match_base(content, asset_ids)
+    if result is None:
         return None
-
-    # 尝试解析 JSON
-    try:
-        cleaned = content.strip()
-        if cleaned.startswith("```"):
-            cleaned = cleaned.strip("`")
-            if cleaned.lower().startswith("json"):
-                cleaned = cleaned[4:]
-            cleaned = cleaned.strip()
-
-        data = json.loads(cleaned)
-
-        result: Dict[str, float] = {}
-
-        # 格式1: {"asset_id1": 0.8, "asset_id2": 0.6}
-        if isinstance(data, dict):
-            if "matches" in data and isinstance(data["matches"], list):
-                # 格式2: {"matches": [{"asset_id": "...", "score": 0.8}]}
-                for item in data["matches"]:
-                    if isinstance(item, dict):
-                        aid = item.get("asset_id") or item.get("id")
-                        score = item.get("score", 0)
-                        if aid and isinstance(score, (int, float)):
-                            result[str(aid)] = max(0.0, min(1.0, float(score)))
-            else:
-                for key, value in data.items():
-                    if isinstance(value, (int, float)):
-                        result[str(key)] = max(0.0, min(1.0, float(value)))
-
-        # 格式3: [{"asset_id": "...", "score": 0.8}]
-        elif isinstance(data, list):
-            for item in data:
-                if isinstance(item, dict):
-                    aid = item.get("asset_id") or item.get("id")
-                    score = item.get("score", 0)
-                    if aid and isinstance(score, (int, float)):
-                        result[str(aid)] = max(0.0, min(1.0, float(score)))
-
-        if len(result) >= max(1, len(asset_ids) // 2):  # 至少一半素材有评分才算成功
-            return result
-
-    except (json.JSONDecodeError, ValueError):
-        pass
-
-    return None
+    return dict(result)
 
 
 def semantic_match_assets(

apps/api/app/services/edit_plan_service.py

@@ -16,6 +16,11 @@ from packages.adapters.sqlalchemy_impl import (
     SQLAlchemyEditPlanRepository,
     SQLAlchemyGenerationTaskRepository,
 )
+from packages.domain.clip_operations import calculate_merge as _calc_merge
+from packages.domain.clip_operations import calculate_shift_orders as _calc_shift_orders
+from packages.domain.clip_operations import calculate_split as _calc_split
+from packages.domain.clip_operations import validate_merge_clips as _validate_merge
+from packages.domain.clip_operations import validate_split_time as _validate_split
 from packages.domain.edit_plan import EditPlan, EditPlanStatus
 from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
 
@@ -384,36 +389,45 @@ class EditPlanService:
         clip = self.get_clip_or_raise(clip_id)
         plan_id = clip.plan_id
 
-        if split_time <= 0 or split_time >= clip.duration:
-            raise ValueError(f"分割时间必须在 (0, {clip.duration:.3f}) 范围内，当前: {split_time}")
+        # 纯逻辑：校验 + 计算
+        _validate_split(split_time, clip.duration)
+        split = _calc_split(
+            duration=clip.duration,
+            split_time=split_time,
+            start_time=clip.start_time,
+        )
 
         self._auto_resume_editing(plan_id)
 
-        original_duration = clip.duration
-        left_duration = round(split_time, 3)
-        right_duration = round(original_duration - split_time, 3)
         original_order = clip.order
 
         # 更新左半部分（原片段）
-        clip.duration = left_duration
+        clip.duration = split.left_duration
         left_clip = self._clip_repo.update(clip)
 
         # 后面片段的 order 全部 +1（给右半部分腾位置）
         all_clips = self._clip_repo.list_by_plan(plan_id)
-        for c in all_clips:
-            if c.order > original_order and c.id != clip_id:
-                c.order += 1
-                self._clip_repo.update(c)
+        shifts = _calc_shift_orders(
+            all_clips,
+            threshold_order=original_order,
+            shift=1,
+            excluded_ids={clip_id},
+            id_attr="id",
+            order_attr="order",
+        )
+        for c, new_order in shifts:
+            c.order = new_order
+            self._clip_repo.update(c)
 
         # 创建右半部分新片段（继承原片段的大部分属性）
         right_config = dict(clip.config) if clip.config else {}
         # 素材裁剪信息
         if clip.asset_id:
             # 右半部分从 split_time 开始播放
-            right_config["trim_start"] = left_duration
+            right_config["trim_start"] = split.right_trim_start
             # 左半部分在 split_time 处结束
             left_config = dict(left_clip.config) if left_clip.config else {}
-            left_config["trim_end"] = right_duration
+            left_config["trim_end"] = split.left_trim_end
             left_clip.config = left_config
             left_clip = self._clip_repo.update(left_clip)
 
@@ -424,8 +438,8 @@ class EditPlanService:
             template_clip_config_id=clip.template_clip_config_id,
             asset_id=clip.asset_id,
             text_content=clip.text_content,
-            start_time=clip.start_time + left_duration,
-            duration=right_duration,
+            start_time=split.right_start_time,
+            duration=split.right_duration,
             transition_effect=clip.transition_effect,
             transition_duration=clip.transition_duration,
             playback_speed=clip.playback_speed,
@@ -438,8 +452,8 @@ class EditPlanService:
             clip_id,
             plan_id,
             split_time,
-            left_duration,
-            right_duration,
+            split.left_duration,
+            split.right_duration,
         )
 
         return {
@@ -468,70 +482,45 @@ class EditPlanService:
             clip = self.get_clip_or_raise(cid)
             clips.append(clip)
 
-        # 校验：同一计划
-        plan_id = clips[0].plan_id
-        for c in clips[1:]:
-            if c.plan_id != plan_id:
-                raise ValueError("只能合并同一计划下的片段")
-
-        # 按 order 排序
-        clips.sort(key=lambda c: c.order)
-
-        # 校验：order 连续
-        for i in range(1, len(clips)):
-            if clips[i].order != clips[i - 1].order + 1:
-                raise ValueError(f"片段不连续：order {clips[i-1].order} → {clips[i].order}")
-
-        # 校验：类型一致
-        clip_type = clips[0].clip_type
-        for c in clips[1:]:
-            if c.clip_type != clip_type:
-                raise ValueError("只能合并相同类型的片段")
+        # 纯逻辑：校验 + 计算
+        plan_id, first_order = _validate_merge(clips)
+        merge = _calc_merge(clips)
 
         self._auto_resume_editing(plan_id)
 
-        # 计算合并后的属性
-        first_clip = clips[0]
-        total_duration = round(sum(c.duration for c in clips), 3)
-        first_order = first_clip.order
-
-        # 合并文案（用换行连接）
-        merged_text = "\n".join(c.text_content for c in clips if c.text_content.strip())
-
-        # 合并 config（后面的覆盖前面的）
-        merged_config: Dict[str, Any] = {}
-        for c in clips:
-            if c.config:
-                merged_config.update(c.config)
-        # 清理 trim 相关字段（合并后就是完整片段了）
-        merged_config.pop("trim_start", None)
-        merged_config.pop("trim_end", None)
-
         # 更新第一个片段（保留它作为合并结果）
-        first_clip.duration = total_duration
-        first_clip.text_content = merged_text
-        first_clip.config = merged_config
+        first_clip = sorted(clips, key=lambda c: c.order)[0]
+        first_clip.duration = merge.total_duration
+        first_clip.text_content = merge.merged_text
+        first_clip.config = merge.merged_config
         # 转场保留第一个的（合并后的入点转场）
         # playback_speed 取第一个的
         merged_clip = self._clip_repo.update(first_clip)
 
         # 删除其余片段
-        for c in clips[1:]:
-            self._clip_repo.delete(c.id)
+        rest_ids = [c.id for c in clips if c.id != merged_clip.id]
+        for cid in rest_ids:
+            self._clip_repo.delete(cid)
 
         # 后面的片段 order 前移 (len - 1) 位
-        shift = len(clips) - 1
         all_clips = self._clip_repo.list_by_plan(plan_id)
-        for c in all_clips:
-            if c.order > first_order and c.id != merged_clip.id:
-                c.order -= shift
-                self._clip_repo.update(c)
+        shifts = _calc_shift_orders(
+            all_clips,
+            threshold_order=first_order,
+            shift=-merge.shift_amount,
+            excluded_ids={merged_clip.id},
+            id_attr="id",
+            order_attr="order",
+        )
+        for c, new_order in shifts:
+            c.order = new_order
+            self._clip_repo.update(c)
 
         logger.info(
             "合并片段: plan_id=%s count=%d total_duration=%.3fs",
             plan_id,
             len(clips),
-            total_duration,
+            merge.total_duration,
         )
 
         return merged_clip

apps/api/app/services/edit_template_service.py

@@ -23,6 +23,13 @@ from packages.domain.template_clip_config import (
     TemplateClipConfig,
     TransitionEffect,
 )
+from packages.domain.template_clip_converter import (
+    clip_configs_to_snapshots,
+    clips_to_template_clip_configs,
+    filter_plan_config_to_template,
+    snapshots_to_template_clip_configs,
+    validate_template_name,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -121,9 +128,7 @@ class EditTemplateService:
             ValueError: 名称为空或重复
         """
         # 名称校验
-        clean_name = name.strip()
-        if not clean_name:
-            raise ValueError("模板名称不能为空")
+        clean_name = validate_template_name(name)
 
         # 名称重复检查
         existing = self._template_repo.list_all(skip=0, limit=1000)
@@ -471,12 +476,7 @@ class EditTemplateService:
                 raise ValueError(f"模板名称已存在: {clean_name}")
 
         # 从计划 config 中提取模板级配置，去掉运行时/素材相关字段
-        plan_config = plan.config or {}
-        template_config: dict[str, Any] = {}
-        for key, value in plan_config.items():
-            # 跳过明显的运行时/实例字段，保留风格/模式类配置
-            if key not in {"asset_ids", "source_edit_plan_id", "generation_task_id"}:
-                template_config[key] = value
+        template_config = filter_plan_config_to_template(plan.config)
 
         template = EditTemplate.create(
             name=clean_name,
@@ -497,40 +497,7 @@ class EditTemplateService:
 
         # 5. 转换每个片段为模板片段配置
         created_configs: List[TemplateClipConfig] = []
-        for clip in clips:
-            clip_config: dict[str, Any] = {}
-            # 播放速度存入 config
-            if clip.playback_speed and clip.playback_speed != 1.0:
-                clip_config["playback_speed"] = clip.playback_speed
-            # 片段自有 config 合并（优先级：clip.config 覆盖上面的）
-            if clip.config:
-                clip_config.update(clip.config)
-            # 去掉素材相关字段
-            clip_config.pop("asset_info", None)
-            clip_config.pop("source_asset_id", None)
-
-            # 转场效果兼容校验
-            try:
-                transition = TransitionEffect(clip.transition_effect)
-            except ValueError:
-                transition = TransitionEffect.CUT
-
-            # 片段类型兼容校验
-            try:
-                clip_type = ClipType(clip.clip_type)
-            except ValueError:
-                clip_type = ClipType.MAIN
-
-            clip_config_obj = TemplateClipConfig.create(
-                template_id=created_template.id,
-                clip_type=clip_type,
-                order=clip.order,
-                min_duration=clip.duration,
-                max_duration=clip.duration,
-                text_template=clip.text_content or "",
-                transition_effect=transition,
-                config=clip_config,
-            )
+        for clip_config_obj in clips_to_template_clip_configs(created_template.id, clips):
             created = self._clip_config_repo.create(clip_config_obj)
             created_configs.append(created)
 
@@ -679,8 +646,6 @@ class EditTemplateService:
         Raises:
             ValueError: 模板/草稿不存在，或草稿不属于该模板
         """
-        from packages.domain.template_clip_config import TemplateClipConfig
-
         # 1. 校验模板和草稿
         template = self.get_template_or_raise(template_id)
         draft = self._plan_repo.get(draft_plan_id)
@@ -700,39 +665,14 @@ class EditTemplateService:
         editing_mode = config.get("editing_mode", "one_take")
 
         # 4. 提取模板配置（去掉草稿/运行时字段）
-        draft_config = draft.config or {}
-        template_config: dict[str, Any] = {}
-        skip_keys = {
-            "is_template_draft",
-            "asset_ids",
-            "source_edit_plan_id",
-            "generation_task_id",
-        }
-        for key, value in draft_config.items():
-            if key not in skip_keys:
-                template_config[key] = value
+        template_config = filter_plan_config_to_template(draft.config)
 
         # 5. 事务更新
         try:
             # 5.0 先保存旧版快照（发布前的状态），用于回滚
             old_version = template.version or 1
             old_clip_configs = self._clip_config_repo.list_by_template(template_id)
-            old_clip_snapshots = [
-                {
-                    "clip_type": cfg.clip_type.value if hasattr(cfg.clip_type, "value") else cfg.clip_type,
-                    "order": cfg.order,
-                    "min_duration": cfg.min_duration,
-                    "max_duration": cfg.max_duration,
-                    "text_template": cfg.text_template or "",
-                    "transition_effect": (
-                        cfg.transition_effect.value
-                        if hasattr(cfg.transition_effect, "value")
-                        else cfg.transition_effect
-                    ),
-                    "config": cfg.config or {},
-                }
-                for cfg in old_clip_configs
-            ]
+            old_clip_snapshots = clip_configs_to_snapshots(old_clip_configs)
 
             from packages.domain.template_version import EditTemplateVersion
 
@@ -759,46 +699,7 @@ class EditTemplateService:
 
             # 创建新的片段配置
             created_configs: list[TemplateClipConfig] = []
-            for clip in draft_clips:
-                clip_config: dict[str, Any] = {}
-                # 播放速度存入 config
-                if clip.playback_speed and clip.playback_speed != 1.0:
-                    clip_config["playback_speed"] = clip.playback_speed
-                # 片段自有 config 合并
-                if clip.config:
-                    clip_config.update(clip.config)
-                # 去掉素材相关字段
-                clip_config.pop("asset_info", None)
-                clip_config.pop("source_asset_id", None)
-
-                # 转场效果兼容校验
-                try:
-                    from packages.domain.template_clip_config import (
-                        TransitionEffect,
-                    )
-
-                    transition = TransitionEffect(clip.transition_effect)
-                except (ValueError, ImportError):
-                    transition = TransitionEffect.CUT  # type: ignore
-
-                # 片段类型兼容校验
-                try:
-                    from packages.domain.template_clip_config import ClipType
-
-                    clip_type = ClipType(clip.clip_type)
-                except (ValueError, ImportError):
-                    clip_type = ClipType.MAIN  # type: ignore
-
-                config_obj = TemplateClipConfig.create(
-                    template_id=template_id,
-                    clip_type=clip_type,
-                    order=clip.order,
-                    min_duration=clip.duration,
-                    max_duration=clip.duration,
-                    text_template=clip.text_content or "",
-                    transition_effect=transition,
-                    config=clip_config,
-                )
+            for config_obj in clips_to_template_clip_configs(template_id, draft_clips):
                 created = self._clip_config_repo.create(config_obj)
                 created_configs.append(created)
 
@@ -843,8 +744,6 @@ class EditTemplateService:
         Raises:
             ValueError: 模板/版本不存在
         """
-        from packages.domain.template_clip_config import TemplateClipConfig
-
         template = self.get_template_or_raise(template_id)
 
         # 1. 读取目标版本快照
@@ -857,22 +756,7 @@ class EditTemplateService:
         try:
             # 2. 先保存当前状态快照（当前版本号），确保回滚可撤销
             old_clip_configs = self._clip_config_repo.list_by_template(template_id)
-            old_clip_snapshots = [
-                {
-                    "clip_type": cfg.clip_type.value if hasattr(cfg.clip_type, "value") else cfg.clip_type,
-                    "order": cfg.order,
-                    "min_duration": cfg.min_duration,
-                    "max_duration": cfg.max_duration,
-                    "text_template": cfg.text_template or "",
-                    "transition_effect": (
-                        cfg.transition_effect.value
-                        if hasattr(cfg.transition_effect, "value")
-                        else cfg.transition_effect
-                    ),
-                    "config": cfg.config or {},
-                }
-                for cfg in old_clip_configs
-            ]
+            old_clip_snapshots = clip_configs_to_snapshots(old_clip_configs)
 
             from packages.domain.template_version import EditTemplateVersion
 
@@ -905,37 +789,7 @@ class EditTemplateService:
                 synchronize_session=False
             )
 
-            for clip_snap in target_version.clip_configs:
-                # 转场效果兼容校验
-                try:
-                    from packages.domain.template_clip_config import TransitionEffect
-
-                    transition = TransitionEffect(clip_snap.get("transition_effect", "cut"))
-                except (ValueError, ImportError):
-                    from packages.domain.template_clip_config import TransitionEffect
-
-                    transition = TransitionEffect.CUT
-
-                # 片段类型兼容校验
-                try:
-                    from packages.domain.template_clip_config import ClipType
-
-                    clip_type = ClipType(clip_snap.get("clip_type", "main"))
-                except (ValueError, ImportError):
-                    from packages.domain.template_clip_config import ClipType
-
-                    clip_type = ClipType.MAIN
-
-                config_obj = TemplateClipConfig.create(
-                    template_id=template_id,
-                    clip_type=clip_type,
-                    order=clip_snap.get("order", 0),
-                    min_duration=clip_snap.get("min_duration", 0.0),
-                    max_duration=clip_snap.get("max_duration", 0.0),
-                    text_template=clip_snap.get("text_template", ""),
-                    transition_effect=transition,
-                    config=clip_snap.get("config", {}) or {},
-                )
+            for config_obj in snapshots_to_template_clip_configs(template_id, target_version.clip_configs):
                 self._clip_config_repo.create(config_obj)
 
             self._db.commit()

apps/api/app/services/plan_generator_service.py

@@ -27,13 +27,12 @@ from packages.domain.edit_plan_clip import EditPlanClip
 from packages.domain.edit_template import EditTemplate
 from packages.domain.editing_mode import EditingMode
 from packages.domain.plan_generator_utils import (
-    DEFAULT_CLIP_DURATION,
     create_clips_from_configs,
     distribute_assets,
     generate_default_clips,
     map_clip_types_for_mode,
 )
-from packages.domain.template_clip_config import ClipType, TemplateClipConfig
+from packages.domain.template_clip_config import TemplateClipConfig
 
 logger = logging.getLogger(__name__)
 
@@ -206,4 +205,3 @@ class PlanGeneratorService:
         委托给 plan_generator_utils.distribute_assets 纯函数。
         """
         distribute_assets(clips, asset_ids, editing_mode)
-

apps/api/app/services/smart_asset_selector.py

@@ -21,14 +21,9 @@ from __future__ import annotations
 
 import logging
 
+from packages.domain.asset_scoring import MEDIUM_BUCKET_MAX as _MEDIUM_BUCKET_MAX  # noqa: F401 - re-export for tests
+from packages.domain.asset_scoring import SHORT_BUCKET_MAX as _SHORT_BUCKET_MAX  # noqa: F401 - re-export for tests
 from packages.domain.asset_scoring import (
-    MEDIUM_BUCKET_MAX as _MEDIUM_BUCKET_MAX,
-    MIN_QUALITY_SCORE as _MIN_QUALITY_SCORE,
-    OPTIMAL_DURATION_MAX as _OPTIMAL_DURATION_MAX,
-    OPTIMAL_DURATION_MIN as _OPTIMAL_DURATION_MIN,
-    SHORT_BUCKET_MAX as _SHORT_BUCKET_MAX,
-    TARGET_HEIGHT as _TARGET_HEIGHT,
-    TARGET_WIDTH as _TARGET_WIDTH,
     AssetScoreDetail,
     SmartSelectResult,
     diverse_selection,

apps/api/app/services/video_compose_service.py

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

apps/web/src/pages/duplication/DuplicationDetail.tsx

@@ -3,137 +3,29 @@
  * 风险评估 + 基本信息 + 检测项列表 + 匹配片段
  * 零 antd 依赖
  */
-import React, { useState, useCallback } from "react"
-import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
-import { Button, Tag, Tooltip } from "@/components/ui"
-import { useParams, useNavigate } from "react-router-dom"
-import { getDuplicationDetail, retryDuplication, type DuplicateSegment } from "@/api/duplication"
-import "./duplication.css"
+import React from "react"
+import { Button, Tag } from "@/components/ui"
 import PageHead from "@/components/layout/PageHead"
-
-/** 格式化时间（秒 → mm:ss） */
-const formatTime = (seconds: number) => {
-  const m = Math.floor(seconds / 60)
-  const s = Math.floor(seconds % 60)
-  return `${m.toString().padStart(2, "0")}:${s.toString().padStart(2, "0")}`
-}
-
-/** 格式化文件大小 */
-const formatSize = (bytes: number) => {
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`
-  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`
-  return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`
-}
-
-/** 格式化时长 */
-const formatDuration = (seconds?: number) => {
-  if (!seconds) return "-"
-  const totalSec = Math.round(seconds)
-  const m = Math.floor(totalSec / 60)
-  const s = totalSec % 60
-  return m > 0 ? `${m}分${s}秒` : `${s}秒`
-}
-
-/** 根据查重率获取风险等级 */
-const getRiskLevel = (rate?: number): "low" | "medium" | "high" => {
-  if (rate === undefined) return "low"
-  if (rate <= 10) return "low"
-  if (rate <= 30) return "medium"
-  return "high"
-}
-
-/** 风险等级描述 */
-const RISK_DESC: Record<string, string> = {
-  low: "查重率较低，内容原创度高",
-  medium: "存在一定重复，建议修改部分片段",
-  high: "重复率较高，建议大幅修改或替换",
-}
-
-/** 风险等级标签变体 */
-const RISK_TAG_VARIANT: Record<string, "success" | "warning" | "error"> = {
-  low: "success",
-  medium: "warning",
-  high: "error",
-}
-
-/** 风险等级文字 */
-const RISK_LABEL: Record<string, string> = {
-  low: "低风险",
-  medium: "中风险",
-  high: "高风险",
-}
-
-/** 简易 toast */
-interface ToastState {
-  message: string
-  type: "success" | "error" | "warning"
-}
-
-/** 单个重复片段卡片 */
-const SegmentCard: React.FC<{ segment: DuplicateSegment; index: number }> = ({
-  segment,
-  index,
-}) => {
-  const sourceDuration = segment.source_end - segment.source_start
-  const matchedDuration = segment.matched_end - segment.matched_start
-  const riskLevel = segment.similarity >= 90 ? "high" : segment.similarity >= 70 ? "medium" : "low"
-
-  return (
-    <div className="dup-check-item">
-      <div className="dup-check-icon">🎬</div>
-      <div className="dup-check-body">
-        <h4>
-          片段 {index + 1}：{segment.matched_video_name}
-        </h4>
-        <p>
-          原始 {formatTime(segment.source_start)} - {formatTime(segment.source_end)}（
-          {sourceDuration.toFixed(0)}s）→ 匹配 {formatTime(segment.matched_start)} -{" "}
-          {formatTime(segment.matched_end)}（{matchedDuration.toFixed(0)}s）
-        </p>
-      </div>
-      <div className={`dup-check-bar`}>
-        <div
-          className={`dup-check-bar-fill ${riskLevel}`}
-          style={{ width: `${Math.min(segment.similarity, 100)}%` }}
-        />
-      </div>
-      <span className={`dup-check-value ${riskLevel}`}>{segment.similarity.toFixed(1)}%</span>
-    </div>
-  )
-}
+import { RiskCard } from "./components/RiskCard"
+import { InfoCard } from "./components/InfoCard"
+import { SegmentsSection } from "./components/SegmentsSection"
+import { useDuplicationDetail } from "./hooks/useDuplicationDetail"
+import { RISK_TAG_VARIANT, RISK_LABEL } from "./constants"
+import { formatSize, formatDuration } from "./utils"
+import "./duplication.css"
 
 const DuplicationDetail: React.FC = () => {
-  const { id } = useParams<{ id: string }>()
-  const navigate = useNavigate()
-  const queryClient = useQueryClient()
-  const [toast, setToast] = useState<ToastState | null>(null)
-
-  const showToast = useCallback((message: string, type: "success" | "error" | "warning") => {
-    setToast({ message, type })
-    setTimeout(() => setToast(null), 3000)
-  }, [])
-
   const {
-    data: detail,
+    detail,
     isLoading,
     isError,
-  } = useQuery({
-    queryKey: ["duplication-detail", id],
-    queryFn: () => getDuplicationDetail(id!),
-    enabled: !!id,
-  })
-
-  // 重新查重
-  const retryMutation = useMutation({
-    mutationFn: retryDuplication,
-    onSuccess: () => {
-      showToast("已重新提交查重", "success")
-      queryClient.invalidateQueries({ queryKey: ["duplication-detail", id] })
-    },
-    onError: () => {
-      showToast("重新查重失败", "error")
-    },
-  })
+    toast,
+    riskLevel,
+    similarityPercent,
+    handleRetry,
+    handleDownloadReport,
+    handleBack,
+  } = useDuplicationDetail()
 
   if (isLoading) {
     return (
@@ -155,7 +47,7 @@ const DuplicationDetail: React.FC = () => {
           <Button
             buttonType="primary"
             buttonSize="md"
-            onClick={() => navigate("/app/duplication/results")}
+            onClick={handleBack}
             style={{ marginTop: 16 }}
           >
             返回列表
@@ -165,10 +57,6 @@ const DuplicationDetail: React.FC = () => {
     )
   }
 
-  const riskLevel = getRiskLevel(detail.duplicate_rate)
-  const similarityPercent =
-    detail.duplicate_rate !== undefined ? detail.duplicate_rate.toFixed(1) : "—"
-
   return (
     <div className="dup-page">
       {/* Toast */}
@@ -194,21 +82,11 @@ const DuplicationDetail: React.FC = () => {
         }
         actions={
           <div className="dup-detail-actions" style={{ display: "flex", gap: 8 }}>
-            <Button
-              buttonType="secondary"
-              buttonSize="md"
-              onClick={() => {
-                showToast("报告下载功能开发中", "warning")
-              }}
-            >
+            <Button buttonType="secondary" buttonSize="md" onClick={handleDownloadReport}>
               📥 下载报告
             </Button>
             {detail.status === "failed" && (
-              <Button
-                buttonType="primary"
-                buttonSize="md"
-                onClick={() => retryMutation.mutate(detail.id)}
-              >
+              <Button buttonType="primary" buttonSize="md" onClick={handleRetry}>
                 🔄 重新查重
               </Button>
             )}
@@ -218,103 +96,9 @@ const DuplicationDetail: React.FC = () => {
 
       {/* 内容网格 */}
       <div className="dup-detail-grid">
-        {/* 风险评估卡片 */}
-        <div className="dup-risk-card">
-          <h3>📊 风险评估</h3>
-          <div className={`dup-risk-circle ${riskLevel}`}>
-            <span className="dup-risk-value">{similarityPercent}%</span>
-            <span className="dup-risk-label">查重率</span>
-          </div>
-          <p className="dup-risk-desc">{RISK_DESC[riskLevel]}</p>
-        </div>
-
-        {/* 基本信息卡片 */}
-        <div className="dup-info-detail-card">
-          <h3>📋 基本信息</h3>
-          <div className="dup-info-rows">
-            <div className="dup-info-row">
-              <span className="dup-info-row-label">文件名</span>
-              <Tooltip title={detail.filename}>
-                <span
-                  className="dup-info-row-value"
-                  style={{
-                    maxWidth: 200,
-                    overflow: "hidden",
-                    textOverflow: "ellipsis",
-                    whiteSpace: "nowrap",
-                  }}
-                >
-                  {detail.filename}
-                </span>
-              </Tooltip>
-            </div>
-            <div className="dup-info-row">
-              <span className="dup-info-row-label">文件大小</span>
-              <span className="dup-info-row-value">{formatSize(detail.file_size)}</span>
-            </div>
-            <div className="dup-info-row">
-              <span className="dup-info-row-label">视频时长</span>
-              <span className="dup-info-row-value">{formatDuration(detail.duration_seconds)}</span>
-            </div>
-            <div className="dup-info-row">
-              <span className="dup-info-row-label">查重状态</span>
-              <span className="dup-info-row-value">
-                <Tag
-                  variant={
-                    detail.status === "completed"
-                      ? "success"
-                      : detail.status === "failed"
-                        ? "error"
-                        : detail.status === "processing"
-                          ? "warning"
-                          : "info"
-                  }
-                >
-                  {detail.status === "completed"
-                    ? "✅ 已完成"
-                    : detail.status === "failed"
-                      ? "❌ 失败"
-                      : detail.status === "processing"
-                        ? "🔄 查重中"
-                        : "⏳ 等待中"}
-                </Tag>
-              </span>
-            </div>
-            <div className="dup-info-row">
-              <span className="dup-info-row-label">重复片段数</span>
-              <span className="dup-info-row-value">{detail.duplicate_count ?? 0} 个</span>
-            </div>
-            <div className="dup-info-row">
-              <span className="dup-info-row-label">提交时间</span>
-              <span className="dup-info-row-value">
-                {new Date(detail.created_at).toLocaleString("zh-CN")}
-              </span>
-            </div>
-          </div>
-        </div>
-
-        {/* 检测项列表 */}
-        <div className="dup-checks-section">
-          <h3>
-            🔍 重复片段详情
-            <Tag variant="primary" style={{ marginLeft: 8 }}>
-              {detail.segments?.length ?? 0} 个片段
-            </Tag>
-          </h3>
-
-          {detail.segments && detail.segments.length > 0 ? (
-            <div className="dup-checks-list">
-              {detail.segments.map((segment, index) => (
-                <SegmentCard key={segment.id} segment={segment} index={index} />
-              ))}
-            </div>
-          ) : (
-            <div className="dup-results-empty" style={{ padding: "32px 0" }}>
-              <div className="dup-results-empty-icon">🎉</div>
-              <p>未发现重复片段，内容原创度很高</p>
-            </div>
-          )}
-        </div>
+        <RiskCard riskLevel={riskLevel} similarityPercent={similarityPercent} />
+        <InfoCard detail={detail} />
+        <SegmentsSection segments={detail.segments} />
       </div>
     </div>
   )

apps/web/src/pages/duplication/DuplicationResults.tsx

@@ -2,130 +2,27 @@
  * 查重结果列表页面 — V21 设计系统
  * 胶囊筛选 + 卡片列表，零 antd 依赖
  */
-import React, { useState, useMemo } from "react"
-import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
-import { Button, Tag, Tooltip } from "@/components/ui"
-import { useNavigate } from "react-router-dom"
-import {
-  getDuplicationRecords,
-  deleteDuplicationRecord,
-  retryDuplication,
-  type DuplicationStatus,
-} from "@/api/duplication"
-import "./duplication.css"
+import React from "react"
+import { Button } from "@/components/ui"
 import PageHead from "@/components/layout/PageHead"
-
-/** 风险等级分类 */
-type RiskFilter = "all" | "high" | "medium" | "low"
-
-/** 状态配置 */
-const STATUS_CONFIG: Record<
-  DuplicationStatus,
-  {
-    variant: "primary" | "warning" | "success" | "error"
-    text: string
-    icon: string
-  }
-> = {
-  pending: { variant: "primary", text: "等待中", icon: "⏳" },
-  processing: { variant: "warning", text: "查重中", icon: "🔄" },
-  completed: { variant: "success", text: "已完成", icon: "✅" },
-  failed: { variant: "error", text: "失败", icon: "❌" },
-}
-
-/** 根据查重率获取风险等级 */
-const getRiskLevel = (rate?: number): "low" | "medium" | "high" => {
-  if (rate === undefined) return "low"
-  if (rate <= 10) return "low"
-  if (rate <= 30) return "medium"
-  return "high"
-}
-
-/** 风险等级标签 */
-const RISK_LABELS: Record<string, string> = {
-  low: "低风险",
-  medium: "中风险",
-  high: "高风险",
-}
-
-/** 格式化文件大小 */
-const formatSize = (bytes: number) => {
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`
-  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`
-  return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`
-}
-
-/** 格式化时长 */
-const formatDuration = (seconds?: number) => {
-  if (!seconds) return "-"
-  const totalSec = Math.round(seconds)
-  const m = Math.floor(totalSec / 60)
-  const s = totalSec % 60
-  return m > 0 ? `${m}分${s}秒` : `${s}秒`
-}
-
-/** 简易 toast */
-interface ToastState {
-  message: string
-  type: "success" | "error" | "warning"
-}
-
-const FILTER_OPTIONS: { key: RiskFilter; label: string }[] = [
-  { key: "all", label: "全部" },
-  { key: "low", label: "低风险" },
-  { key: "medium", label: "中风险" },
-  { key: "high", label: "高风险" },
-]
+import "./duplication.css"
+import useDuplicationResults from "./hooks/useDuplicationResults"
+import FilterBar from "./components/FilterBar"
+import EmptyState from "./components/EmptyState"
+import ResultCard from "./components/ResultCard"
 
 const DuplicationResults: React.FC = () => {
-  const navigate = useNavigate()
-  const queryClient = useQueryClient()
-  const [riskFilter, setRiskFilter] = useState<RiskFilter>("all")
-  const [toast, setToast] = useState<ToastState | null>(null)
-
-  const showToast = (message: string, type: "success" | "error" | "warning") => {
-    setToast({ message, type })
-    setTimeout(() => setToast(null), 3000)
-  }
-
-  // 获取查重记录
-  const { data: records = [], isLoading } = useQuery({
-    queryKey: ["duplication-records"],
-    queryFn: getDuplicationRecords,
-  })
-
-  // 删除
-  const deleteMutation = useMutation({
-    mutationFn: deleteDuplicationRecord,
-    onSuccess: () => {
-      showToast("已删除", "success")
-      queryClient.invalidateQueries({ queryKey: ["duplication-records"] })
-    },
-    onError: () => {
-      showToast("删除失败", "error")
-    },
-  })
-
-  // 重新查重
-  const retryMutation = useMutation({
-    mutationFn: retryDuplication,
-    onSuccess: () => {
-      showToast("已重新提交查重", "success")
-      queryClient.invalidateQueries({ queryKey: ["duplication-records"] })
-    },
-    onError: () => {
-      showToast("重新查重失败", "error")
-    },
-  })
-
-  /** 按风险等级筛选 */
-  const filteredRecords = useMemo(() => {
-    if (riskFilter === "all") return records
-    return records.filter((r) => {
-      if (r.status !== "completed") return riskFilter === "low"
-      return getRiskLevel(r.duplicate_rate) === riskFilter
-    })
-  }, [records, riskFilter])
+  const {
+    isLoading,
+    filteredRecords,
+    riskFilter,
+    setRiskFilter,
+    toast,
+    handleDelete,
+    handleRetry,
+    handleView,
+    handleUpload,
+  } = useDuplicationResults()
 
   return (
     <div className="dup-page">
@@ -136,136 +33,31 @@ const DuplicationResults: React.FC = () => {
         title="查重记录"
         actions={
           <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
-            {/* 筛选胶囊 */}
-            <div className="dup-filter">
-              {FILTER_OPTIONS.map((opt) => (
-                <button
-                  key={opt.key}
-                  className={`dup-filter-btn ${riskFilter === opt.key ? "active" : ""}`}
-                  onClick={() => setRiskFilter(opt.key)}
-                >
-                  {opt.label}
-                </button>
-              ))}
-            </div>
-            <Button
-              buttonType="primary"
-              buttonSize="md"
-              onClick={() => navigate("/app/duplication")}
-            >
+            <FilterBar value={riskFilter} onChange={setRiskFilter} />
+            <Button buttonType="primary" buttonSize="md" onClick={handleUpload}>
               📤 上传查重
             </Button>
           </div>
         }
       />
 
-      {/* 加载中 */}
-      {isLoading && (
-        <div className="dup-results-empty">
-          <div className="dup-results-empty-icon">⏳</div>
-          <p>加载中...</p>
-        </div>
-      )}
-
-      {/* 空状态 */}
-      {!isLoading && filteredRecords.length === 0 && (
-        <div className="dup-results-empty">
-          <div className="dup-results-empty-icon">📭</div>
-          <p>
-            {riskFilter === "all"
-              ? "暂无查重记录，上传视频开始查重吧"
-              : `没有${RISK_LABELS[riskFilter]}的记录`}
-          </p>
-        </div>
+      {/* 加载中 / 空状态 */}
+      {(isLoading || filteredRecords.length === 0) && (
+        <EmptyState isLoading={isLoading} riskFilter={riskFilter} />
       )}
 
       {/* 结果卡片列表 */}
       {!isLoading && filteredRecords.length > 0 && (
         <div className="dup-results-list">
-          {filteredRecords.map((record) => {
-            const statusCfg = STATUS_CONFIG[record.status]
-            const riskLevel = getRiskLevel(record.duplicate_rate)
-            const rateValue = record.duplicate_rate
-
-            return (
-              <div
-                key={record.id}
-                className="dup-result-card"
-                onClick={() => {
-                  if (record.status === "completed") {
-                    navigate(`/duplication/${record.id}`)
-                  }
-                }}
-              >
-                {/* 缩略图 */}
-                <div className="dup-result-card-thumb">🎬</div>
-
-                {/* 信息区 */}
-                <div className="dup-result-card-body">
-                  <h4>{record.filename}</h4>
-                  <div className="dup-result-card-meta">
-                    <Tag variant={statusCfg.variant}>
-                      {statusCfg.icon} {statusCfg.text}
-                    </Tag>
-                    <span>{formatSize(record.file_size)}</span>
-                    <span>{formatDuration(record.duration_seconds)}</span>
-                    <span>{new Date(record.created_at).toLocaleDateString("zh-CN")}</span>
-                    {record.status === "completed" && record.duplicate_count !== undefined && (
-                      <span>{record.duplicate_count} 个重复片段</span>
-                    )}
-                  </div>
-                </div>
-
-                {/* 查重率 */}
-                <div className="dup-result-card-score">
-                  {record.status === "completed" && rateValue !== undefined ? (
-                    <>
-                      <div className="dup-score-bar">
-                        <div
-                          className={`dup-score-bar-fill ${riskLevel}`}
-                          style={{ width: `${Math.min(rateValue, 100)}%` }}
-                        />
-                      </div>
-                      <span className={`dup-score-value ${riskLevel}`}>
-                        {rateValue.toFixed(1)}%
-                      </span>
-                    </>
-                  ) : record.status === "failed" ? (
-                    <Tooltip title="重新查重">
-                      <Button
-                        buttonType="ghost"
-                        buttonSize="sm"
-                        onClick={(e) => {
-                          e.stopPropagation()
-                          retryMutation.mutate(record.id)
-                        }}
-                      >
-                        🔄 重试
-                      </Button>
-                    </Tooltip>
-                  ) : (
-                    <span style={{ color: "var(--text-secondary)", fontSize: 12 }}>
-                      {record.status === "processing" ? "分析中..." : "—"}
-                    </span>
-                  )}
-                </div>
-
-                {/* 删除按钮 */}
-                <Button
-                  buttonType="ghost"
-                  buttonSize="sm"
-                  onClick={(e) => {
-                    e.stopPropagation()
-                    if (window.confirm("确定删除此记录？")) {
-                      deleteMutation.mutate(record.id)
-                    }
-                  }}
-                >
-                  🗑️
-                </Button>
-              </div>
-            )
-          })}
+          {filteredRecords.map((record) => (
+            <ResultCard
+              key={record.id}
+              record={record}
+              onView={handleView}
+              onDelete={handleDelete}
+              onRetry={handleRetry}
+            />
+          ))}
         </div>
       )}
     </div>

apps/web/src/pages/duplication/components/EmptyState.tsx

@@ -0,0 +1,32 @@
+import React from "react"
+import { RISK_LABELS } from "../constants"
+import type { RiskFilter } from "../types"
+
+interface EmptyStateProps {
+  isLoading: boolean
+  riskFilter: RiskFilter
+}
+
+const EmptyState: React.FC<EmptyStateProps> = ({ isLoading, riskFilter }) => {
+  if (isLoading) {
+    return (
+      <div className="dup-results-empty">
+        <div className="dup-results-empty-icon">⏳</div>
+        <p>加载中...</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="dup-results-empty">
+      <div className="dup-results-empty-icon">📭</div>
+      <p>
+        {riskFilter === "all"
+          ? "暂无查重记录，上传视频开始查重吧"
+          : `没有${RISK_LABELS[riskFilter]}的记录`}
+      </p>
+    </div>
+  )
+}
+
+export default EmptyState

apps/web/src/pages/duplication/components/FilterBar.tsx

@@ -0,0 +1,26 @@
+import React from "react"
+import type { RiskFilter } from "../types"
+import { FILTER_OPTIONS } from "../constants"
+
+interface FilterBarProps {
+  value: RiskFilter
+  onChange: (value: RiskFilter) => void
+}
+
+const FilterBar: React.FC<FilterBarProps> = ({ value, onChange }) => {
+  return (
+    <div className="dup-filter">
+      {FILTER_OPTIONS.map((opt) => (
+        <button
+          key={opt.key}
+          className={`dup-filter-btn ${value === opt.key ? "active" : ""}`}
+          onClick={() => onChange(opt.key)}
+        >
+          {opt.label}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+export default FilterBar

apps/web/src/pages/duplication/components/InfoCard.tsx

@@ -0,0 +1,72 @@
+import React from "react"
+import { Tag, Tooltip } from "@/components/ui"
+import { formatSize, formatDuration } from "../utils"
+import type { DuplicationDetail } from "@/api/duplication"
+
+interface InfoCardProps {
+  detail: DuplicationDetail
+}
+
+/**
+ * 基本信息卡片
+ */
+export const InfoCard: React.FC<InfoCardProps> = ({ detail }) => {
+  const statusMap: Record<string, { text: string; variant: string }> = {
+    completed: { text: "✅ 已完成", variant: "success" },
+    failed: { text: "❌ 失败", variant: "error" },
+    processing: { text: "🔄 查重中", variant: "warning" },
+    pending: { text: "⏳ 等待中", variant: "info" },
+  }
+  const status = statusMap[detail.status] || {
+    text: detail.status,
+    variant: "info",
+  }
+
+  return (
+    <div className="dup-info-detail-card">
+      <h3>📋 基本信息</h3>
+      <div className="dup-info-rows">
+        <div className="dup-info-row">
+          <span className="dup-info-row-label">文件名</span>
+          <Tooltip title={detail.filename}>
+            <span
+              className="dup-info-row-value"
+              style={{
+                maxWidth: 200,
+                overflow: "hidden",
+                textOverflow: "ellipsis",
+                whiteSpace: "nowrap",
+              }}
+            >
+              {detail.filename}
+            </span>
+          </Tooltip>
+        </div>
+        <div className="dup-info-row">
+          <span className="dup-info-row-label">文件大小</span>
+          <span className="dup-info-row-value">{formatSize(detail.file_size)}</span>
+        </div>
+        <div className="dup-info-row">
+          <span className="dup-info-row-label">视频时长</span>
+          <span className="dup-info-row-value">{formatDuration(detail.duration_seconds)}</span>
+        </div>
+        <div className="dup-info-row">
+          <span className="dup-info-row-label">查重状态</span>
+          <span className="dup-info-row-value">
+            <Tag variant={status.variant as "success"}>{status.text}</Tag>
+          </span>
+        </div>
+        <div className="dup-info-row">
+          <span className="dup-info-row-label">重复片段数</span>
+          <span className="dup-info-row-value">{detail.duplicate_count ?? 0} 个</span>
+        </div>
+        <div className="dup-info-row">
+          <span className="dup-info-row-label">提交时间</span>
+          <span className="dup-info-row-value">
+            {new Date(detail.created_at).toLocaleString("zh-CN")}
+          </span>
+        </div>
+      </div>
+    </div>
+  )
+}

apps/web/src/pages/duplication/components/ResultCard.tsx

@@ -0,0 +1,95 @@
+import React from "react"
+import { Button, Tag, Tooltip } from "@/components/ui"
+import type { DuplicationRecord } from "@/api/duplication"
+import { STATUS_CONFIG } from "../constants"
+import { getRiskLevel, formatSize, formatDuration } from "../utils"
+
+interface ResultCardProps {
+  record: DuplicationRecord
+  onView: (id: string) => void
+  onDelete: (id: string) => void
+  onRetry: (id: string) => void
+}
+
+const ResultCard: React.FC<ResultCardProps> = ({ record, onView, onDelete, onRetry }) => {
+  const statusCfg = STATUS_CONFIG[record.status]
+  const riskLevel = getRiskLevel(record.duplicate_rate)
+  const rateValue = record.duplicate_rate
+
+  const handleClick = () => {
+    if (record.status === "completed") {
+      onView(record.id)
+    }
+  }
+
+  return (
+    <div key={record.id} className="dup-result-card" onClick={handleClick}>
+      {/* 缩略图 */}
+      <div className="dup-result-card-thumb">🎬</div>
+
+      {/* 信息区 */}
+      <div className="dup-result-card-body">
+        <h4>{record.filename}</h4>
+        <div className="dup-result-card-meta">
+          <Tag variant={statusCfg.variant}>
+            {statusCfg.icon} {statusCfg.text}
+          </Tag>
+          <span>{formatSize(record.file_size)}</span>
+          <span>{formatDuration(record.duration_seconds)}</span>
+          <span>{new Date(record.created_at).toLocaleDateString("zh-CN")}</span>
+          {record.status === "completed" && record.duplicate_count !== undefined && (
+            <span>{record.duplicate_count} 个重复片段</span>
+          )}
+        </div>
+      </div>
+
+      {/* 查重率 */}
+      <div className="dup-result-card-score">
+        {record.status === "completed" && rateValue !== undefined ? (
+          <>
+            <div className="dup-score-bar">
+              <div
+                className={`dup-score-bar-fill ${riskLevel}`}
+                style={{ width: `${Math.min(rateValue, 100)}%` }}
+              />
+            </div>
+            <span className={`dup-score-value ${riskLevel}`}>{rateValue.toFixed(1)}%</span>
+          </>
+        ) : record.status === "failed" ? (
+          <Tooltip title="重新查重">
+            <Button
+              buttonType="ghost"
+              buttonSize="sm"
+              onClick={(e) => {
+                e.stopPropagation()
+                onRetry(record.id)
+              }}
+            >
+              🔄 重试
+            </Button>
+          </Tooltip>
+        ) : (
+          <span style={{ color: "var(--text-secondary)", fontSize: 12 }}>
+            {record.status === "processing" ? "分析中..." : "—"}
+          </span>
+        )}
+      </div>
+
+      {/* 删除按钮 */}
+      <Button
+        buttonType="ghost"
+        buttonSize="sm"
+        onClick={(e) => {
+          e.stopPropagation()
+          if (window.confirm("确定删除此记录？")) {
+            onDelete(record.id)
+          }
+        }}
+      >
+        🗑️
+      </Button>
+    </div>
+  )
+}
+
+export default ResultCard

apps/web/src/pages/duplication/components/RiskCard.tsx

@@ -0,0 +1,21 @@
+import React from "react"
+import { RISK_DESC } from "../constants"
+
+interface RiskCardProps {
+  riskLevel: string
+  similarityPercent: string
+}
+
+/**
+ * 风险评估卡片
+ */
+export const RiskCard: React.FC<RiskCardProps> = ({ riskLevel, similarityPercent }) => (
+  <div className="dup-risk-card">
+    <h3>📊 风险评估</h3>
+    <div className={`dup-risk-circle ${riskLevel}`}>
+      <span className="dup-risk-value">{similarityPercent}%</span>
+      <span className="dup-risk-label">查重率</span>
+    </div>
+    <p className="dup-risk-desc">{RISK_DESC[riskLevel]}</p>
+  </div>
+)

apps/web/src/pages/duplication/components/SegmentCard.tsx

@@ -0,0 +1,40 @@
+import React from "react"
+import type { DuplicateSegment } from "@/api/duplication"
+import { formatTime } from "../utils"
+
+interface SegmentCardProps {
+  segment: DuplicateSegment
+  index: number
+}
+
+/**
+ * 单个重复片段卡片
+ */
+export const SegmentCard: React.FC<SegmentCardProps> = ({ segment, index }) => {
+  const sourceDuration = segment.source_end - segment.source_start
+  const matchedDuration = segment.matched_end - segment.matched_start
+  const riskLevel = segment.similarity >= 90 ? "high" : segment.similarity >= 70 ? "medium" : "low"
+
+  return (
+    <div className="dup-check-item">
+      <div className="dup-check-icon">🎬</div>
+      <div className="dup-check-body">
+        <h4>
+          片段 {index + 1}：{segment.matched_video_name}
+        </h4>
+        <p>
+          原始 {formatTime(segment.source_start)} - {formatTime(segment.source_end)}（
+          {sourceDuration.toFixed(0)}s）→ 匹配 {formatTime(segment.matched_start)} -{" "}
+          {formatTime(segment.matched_end)}（{matchedDuration.toFixed(0)}s）
+        </p>
+      </div>
+      <div className={`dup-check-bar`}>
+        <div
+          className={`dup-check-bar-fill ${riskLevel}`}
+          style={{ width: `${Math.min(segment.similarity, 100)}%` }}
+        />
+      </div>
+      <span className={`dup-check-value ${riskLevel}`}>{segment.similarity.toFixed(1)}%</span>
+    </div>
+  )
+}

apps/web/src/pages/duplication/components/SegmentsSection.tsx

@@ -0,0 +1,35 @@
+import React from "react"
+import { Tag } from "@/components/ui"
+import type { DuplicateSegment } from "@/api/duplication"
+import { SegmentCard } from "./SegmentCard"
+
+interface SegmentsSectionProps {
+  segments?: DuplicateSegment[]
+}
+
+/**
+ * 重复片段列表区域
+ */
+export const SegmentsSection: React.FC<SegmentsSectionProps> = ({ segments = [] }) => (
+  <div className="dup-checks-section">
+    <h3>
+      🔍 重复片段详情
+      <Tag variant="primary" style={{ marginLeft: 8 }}>
+        {segments.length} 个片段
+      </Tag>
+    </h3>
+
+    {segments.length > 0 ? (
+      <div className="dup-checks-list">
+        {segments.map((segment, index) => (
+          <SegmentCard key={segment.id} segment={segment} index={index} />
+        ))}
+      </div>
+    ) : (
+      <div className="dup-results-empty" style={{ padding: "32px 0" }}>
+        <div className="dup-results-empty-icon">🎉</div>
+        <p>未发现重复片段，内容原创度很高</p>
+      </div>
+    )}
+  </div>
+)

apps/web/src/pages/duplication/constants.ts

@@ -0,0 +1,58 @@
+import type { DuplicationStatus } from "@/api/duplication"
+import type { RiskFilter } from "./types"
+
+/** 状态配置 */
+export const STATUS_CONFIG: Record<
+  DuplicationStatus,
+  {
+    variant: "primary" | "warning" | "success" | "error"
+    text: string
+    icon: string
+  }
+> = {
+  pending: { variant: "primary", text: "等待中", icon: "⏳" },
+  processing: { variant: "warning", text: "查重中", icon: "🔄" },
+  completed: { variant: "success", text: "已完成", icon: "✅" },
+  failed: { variant: "error", text: "失败", icon: "❌" },
+}
+
+/** 风险等级描述 */
+export const RISK_DESC: Record<string, string> = {
+  low: "查重率较低，内容原创度高",
+  medium: "存在一定重复，建议修改部分片段",
+  high: "重复率较高，建议大幅修改或替换",
+}
+
+/** 风险等级标签变体 */
+export const RISK_TAG_VARIANT: Record<string, "success" | "warning" | "error"> = {
+  low: "success",
+  medium: "warning",
+  high: "error",
+}
+
+/** 风险等级文字（详情页用） */
+export const RISK_LABEL: Record<string, string> = {
+  low: "低风险",
+  medium: "中风险",
+  high: "高风险",
+}
+
+/** 风险等级标签（列表页用） */
+export const RISK_LABELS: Record<string, string> = {
+  low: "低风险",
+  medium: "中风险",
+  high: "高风险",
+}
+
+export const FILTER_OPTIONS: { key: RiskFilter; label: string }[] = [
+  { key: "all", label: "全部" },
+  { key: "low", label: "低风险" },
+  { key: "medium", label: "中风险" },
+  { key: "high", label: "高风险" },
+]
+
+/** Toast 类型 */
+export interface ToastState {
+  message: string
+  type: "success" | "error" | "warning"
+}

apps/web/src/pages/duplication/hooks/useDuplicationDetail.ts

@@ -0,0 +1,77 @@
+import { useState, useCallback } from "react"
+import { useParams, useNavigate } from "react-router-dom"
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
+import { getDuplicationDetail, retryDuplication } from "@/api/duplication"
+import type { ToastState } from "../constants"
+import { getRiskLevel } from "../utils"
+
+/**
+ * 查重详情业务 Hook
+ */
+export const useDuplicationDetail = () => {
+  const { id } = useParams<{ id: string }>()
+  const navigate = useNavigate()
+  const queryClient = useQueryClient()
+  const [toast, setToast] = useState<ToastState | null>(null)
+
+  const showToast = useCallback((message: string, type: "success" | "error" | "warning") => {
+    setToast({ message, type })
+    setTimeout(() => setToast(null), 3000)
+  }, [])
+
+  const {
+    data: detail,
+    isLoading,
+    isError,
+  } = useQuery({
+    queryKey: ["duplication-detail", id],
+    queryFn: () => getDuplicationDetail(id!),
+    enabled: !!id,
+  })
+
+  // 重新查重
+  const retryMutation = useMutation({
+    mutationFn: retryDuplication,
+    onSuccess: () => {
+      showToast("已重新提交查重", "success")
+      queryClient.invalidateQueries({ queryKey: ["duplication-detail", id] })
+    },
+    onError: () => {
+      showToast("重新查重失败", "error")
+    },
+  })
+
+  const handleRetry = useCallback(() => {
+    if (!detail) return
+    retryMutation.mutate(detail.id)
+  }, [detail, retryMutation])
+
+  const handleDownloadReport = useCallback(() => {
+    showToast("报告下载功能开发中", "warning")
+  }, [showToast])
+
+  const handleBack = useCallback(() => {
+    navigate("/app/duplication/results")
+  }, [navigate])
+
+  const riskLevel = detail ? getRiskLevel(detail.duplicate_rate) : "low"
+  const similarityPercent =
+    detail?.duplicate_rate !== undefined ? detail.duplicate_rate.toFixed(1) : "—"
+
+  return {
+    // 数据
+    detail,
+    isLoading,
+    isError,
+    // 状态
+    toast,
+    riskLevel,
+    similarityPercent,
+    retryLoading: retryMutation.isPending,
+    // 操作
+    showToast,
+    handleRetry,
+    handleDownloadReport,
+    handleBack,
+  }
+}

apps/web/src/pages/duplication/hooks/useDuplicationResults.ts

@@ -0,0 +1,106 @@
+import { useState, useMemo } from "react"
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
+import { useNavigate } from "react-router-dom"
+import {
+  getDuplicationRecords,
+  deleteDuplicationRecord,
+  retryDuplication,
+  type DuplicationRecord,
+} from "@/api/duplication"
+import type { RiskFilter, ToastState } from "../types"
+import { getRiskLevel } from "../utils"
+
+interface UseDuplicationResultsReturn {
+  records: DuplicationRecord[]
+  isLoading: boolean
+  filteredRecords: DuplicationRecord[]
+  riskFilter: RiskFilter
+  setRiskFilter: (filter: RiskFilter) => void
+  toast: ToastState | null
+  handleDelete: (id: string) => void
+  handleRetry: (id: string) => void
+  handleView: (id: string) => void
+  handleUpload: () => void
+}
+
+const useDuplicationResults = (): UseDuplicationResultsReturn => {
+  const navigate = useNavigate()
+  const queryClient = useQueryClient()
+  const [riskFilter, setRiskFilter] = useState<RiskFilter>("all")
+  const [toast, setToast] = useState<ToastState | null>(null)
+
+  const showToast = (message: string, type: "success" | "error" | "warning") => {
+    setToast({ message, type })
+    setTimeout(() => setToast(null), 3000)
+  }
+
+  // 获取查重记录
+  const { data: records = [], isLoading } = useQuery({
+    queryKey: ["duplication-records"],
+    queryFn: getDuplicationRecords,
+  })
+
+  // 删除
+  const deleteMutation = useMutation({
+    mutationFn: deleteDuplicationRecord,
+    onSuccess: () => {
+      showToast("已删除", "success")
+      queryClient.invalidateQueries({ queryKey: ["duplication-records"] })
+    },
+    onError: () => {
+      showToast("删除失败", "error")
+    },
+  })
+
+  // 重新查重
+  const retryMutation = useMutation({
+    mutationFn: retryDuplication,
+    onSuccess: () => {
+      showToast("已重新提交查重", "success")
+      queryClient.invalidateQueries({ queryKey: ["duplication-records"] })
+    },
+    onError: () => {
+      showToast("重新查重失败", "error")
+    },
+  })
+
+  /** 按风险等级筛选 */
+  const filteredRecords = useMemo(() => {
+    if (riskFilter === "all") return records
+    return records.filter((r) => {
+      if (r.status !== "completed") return riskFilter === "low"
+      return getRiskLevel(r.duplicate_rate) === riskFilter
+    })
+  }, [records, riskFilter])
+
+  const handleDelete = (id: string) => {
+    deleteMutation.mutate(id)
+  }
+
+  const handleRetry = (id: string) => {
+    retryMutation.mutate(id)
+  }
+
+  const handleView = (id: string) => {
+    navigate(`/duplication/${id}`)
+  }
+
+  const handleUpload = () => {
+    navigate("/app/duplication")
+  }
+
+  return {
+    records,
+    isLoading,
+    filteredRecords,
+    riskFilter,
+    setRiskFilter,
+    toast,
+    handleDelete,
+    handleRetry,
+    handleView,
+    handleUpload,
+  }
+}
+
+export default useDuplicationResults

apps/web/src/pages/duplication/types.ts

@@ -0,0 +1,8 @@
+/** 风险等级分类 */
+export type RiskFilter = "all" | "high" | "medium" | "low"
+
+/** 简易 toast */
+export interface ToastState {
+  message: string
+  type: "success" | "error" | "warning"
+}

apps/web/src/pages/duplication/utils.ts

@@ -0,0 +1,30 @@
+/** 根据查重率获取风险等级 */
+export const getRiskLevel = (rate?: number): "low" | "medium" | "high" => {
+  if (rate === undefined) return "low"
+  if (rate <= 10) return "low"
+  if (rate <= 30) return "medium"
+  return "high"
+}
+
+/** 格式化时间（秒 → mm:ss） */
+export const formatTime = (seconds: number) => {
+  const m = Math.floor(seconds / 60)
+  const s = Math.floor(seconds % 60)
+  return `${m.toString().padStart(2, "0")}:${s.toString().padStart(2, "0")}`
+}
+
+/** 格式化文件大小 */
+export const formatSize = (bytes: number) => {
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`
+  return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`
+}
+
+/** 格式化时长 */
+export const formatDuration = (seconds?: number) => {
+  if (!seconds) return "-"
+  const totalSec = Math.round(seconds)
+  const m = Math.floor(totalSec / 60)
+  const s = totalSec % 60
+  return m > 0 ? `${m}分${s}秒` : `${s}秒`
+}

apps/web/src/pages/editing-planner/EditingPlanner.tsx

@@ -1,15 +1,21 @@
 /**
  * 模板编辑器 — 制作/编辑剪辑模板
  * 四行布局：顶栏(42px) → 模式栏(48px) → 三栏主体 → 底栏(40px)
+ *
+ * 主组件仅保留 Hook 组装与整体布局
+ * 全局配置 → hooks/useGlobalSettings
+ * 配音素材 → hooks/useVoiceMaterials
+ * 撤销重做 → hooks/useUndoRedo
+ * 抽屉管理 → hooks/useEditorDrawers
+ * 播放控制 → hooks/usePlaybackControl
+ * 片段操作 → hooks/useClipOperations
+ * 模板管理 → hooks/useTemplateManagement
  */
 import React, { useState } from "react"
 import { useSearchParams } from "react-router-dom"
-import { useQuery } from "@tanstack/react-query"
 import { MODE_LABELS } from "@/api/editing-planner"
 import { MODE_LIST } from "./constants"
-import type { MediaAsset, TitleConfig } from "@/api/template-editor"
-import { ensureDefaultLibrary, getAssetsByKind, type AssetItem } from "@/api/assets"
-import { getOrCreateDefaultProject } from "@/api/projects"
+import type { MediaAsset } from "@/api/template-editor"
 
 import MediaPanel from "./components/MediaPanel"
 import PreviewPlayer from "./components/PreviewPlayer"
@@ -26,36 +32,12 @@ import { useEditorDrawers } from "./hooks/useEditorDrawers"
 import { usePlaybackControl } from "./hooks/usePlaybackControl"
 import { useClipOperations } from "./hooks/useClipOperations"
 import { useTemplateManagement, FILTER_CATEGORIES } from "./hooks/useTemplateManagement"
+import { useGlobalSettings } from "./hooks/useGlobalSettings"
+import { useVoiceMaterials } from "./hooks/useVoiceMaterials"
 
-import type {
-  ClipData,
-  WatermarkConfig,
-  IntroOutroConfig,
-  PipConfig,
-  FilterConfig,
-  ChromaKeyConfig,
-  StickerConfig,
-  CoverConfig,
-} from "./types"
-import {
-  DEFAULT_WATERMARK,
-  DEFAULT_INTRO_OUTRO,
-  DEFAULT_PIP_CONFIG,
-  DEFAULT_FILTER_CONFIG,
-  DEFAULT_CHROMA_KEY_CONFIG,
-  DEFAULT_STICKER_CONFIG,
-  DEFAULT_COVER_CONFIG,
-} from "./types"
-
-import type { SubtitleStyleConfig } from "./types/subtitle"
-import { DEFAULT_SUBTITLE_STYLE } from "./types/subtitle"
-import { DEFAULT_BGM_MIX_CONFIG, type BgmMixConfig } from "@/api/bgm"
+import type { ClipData } from "./types"
 import "./EditingPlanner.css"
 
-/* ──────────── 常量 ──────────── */
-
-/* ──────────── 组件 ──────────── */
-
 const EditingPlanner: React.FC = () => {
   const [searchParams] = useSearchParams()
   const urlTemplateId = searchParams.get("templateId") || ""
@@ -72,50 +54,29 @@ const EditingPlanner: React.FC = () => {
     reset: resetClips,
   } = useUndoRedo<ClipData[]>([])
 
-  /* ── 全局配置 state ── */
-  const [titleConfig, setTitleConfig] = useState<TitleConfig>({
-    ai_auto_select: false,
-    content: "",
-    position: "bottom",
-    font_preset: "思源黑体",
-    font_size: 28,
-    font_color: "#ffffff",
-  })
-
-  const [subtitleSettings, setSubtitleSettings] = useState<SubtitleStyleConfig>({
-    ...DEFAULT_SUBTITLE_STYLE,
-  })
-
-  const [bgmSettings, setBgmSettings] = useState<BgmMixConfig>({
-    ...DEFAULT_BGM_MIX_CONFIG,
-  })
-
-  const [watermarkSettings, setWatermarkSettings] = useState<WatermarkConfig>({
-    ...DEFAULT_WATERMARK,
-  })
-  const [introOutroSettings, setIntroOutroSettings] = useState<IntroOutroConfig>({
-    ...DEFAULT_INTRO_OUTRO,
-  })
-
-  const [pipSettings, setPipSettings] = useState<PipConfig>({
-    ...DEFAULT_PIP_CONFIG,
-  })
-
-  const [filterSettings, setFilterSettings] = useState<FilterConfig>({
-    ...DEFAULT_FILTER_CONFIG,
-  })
-
-  const [chromaKeySettings, setChromaKeySettings] = useState<ChromaKeyConfig>({
-    ...DEFAULT_CHROMA_KEY_CONFIG,
-  })
-
-  const [stickerSettings, setStickerSettings] = useState<StickerConfig>({
-    ...DEFAULT_STICKER_CONFIG,
-  })
-
-  const [coverConfig, setCoverConfig] = useState<CoverConfig>({
-    ...DEFAULT_COVER_CONFIG,
-  })
+  /* ── 全局配置 ── */
+  const {
+    titleConfig,
+    setTitleConfig,
+    subtitleSettings,
+    setSubtitleSettings,
+    bgmSettings,
+    setBgmSettings,
+    watermarkSettings,
+    setWatermarkSettings,
+    introOutroSettings,
+    setIntroOutroSettings,
+    pipSettings,
+    setPipSettings,
+    filterSettings,
+    setFilterSettings,
+    chromaKeySettings,
+    setChromaKeySettings,
+    stickerSettings,
+    setStickerSettings,
+    coverConfig,
+    setCoverConfig,
+  } = useGlobalSettings()
 
   /* ── 右侧栏 Tab ── */
   const [rightTab, setRightTab] = useState<"properties" | "clips">("properties")
@@ -128,18 +89,12 @@ const EditingPlanner: React.FC = () => {
     setSelectedAssetIds(ids)
   }
 
-  /* ── 配音素材（queryKey 与 VoiceMaterialLibrary 共享缓存） ── */
-  const voiceMaterialsQuery = useQuery({
-    queryKey: ["assets", "voice"],
-    queryFn: async () => {
-      const project = await getOrCreateDefaultProject()
-      await ensureDefaultLibrary({ project_id: project.id, kind: "voice" })
-      const assets = await getAssetsByKind("voice")
-      return assets
-    },
-    staleTime: 30_000,
-  })
-  const voiceMaterials: AssetItem[] = voiceMaterialsQuery.data ?? []
+  /* ── 配音素材 ── */
+  const {
+    voiceMaterials,
+    loading: voiceMaterialsLoading,
+    refetch: refetchVoiceMaterials,
+  } = useVoiceMaterials()
 
   /* ── 派生计算 ── */
   const totalDuration = clips.reduce((sum, c) => sum + c.duration, 0)
@@ -179,31 +134,6 @@ const EditingPlanner: React.FC = () => {
     coverConfig,
   })
 
-  /* ── 配置变更 handlers ── */
-  const handleWatermarkChange = (config: WatermarkConfig) => {
-    setWatermarkSettings(config)
-  }
-
-  const handleIntroOutroChange = (config: IntroOutroConfig) => {
-    setIntroOutroSettings(config)
-  }
-
-  const handlePipChange = (config: PipConfig) => {
-    setPipSettings(config)
-  }
-
-  const handleFilterChange = (config: FilterConfig) => {
-    setFilterSettings(config)
-  }
-
-  const handleChromaKeyChange = (config: ChromaKeyConfig) => {
-    setChromaKeySettings(config)
-  }
-
-  const handleStickerChange = (config: StickerConfig) => {
-    setStickerSettings(config)
-  }
-
   /* ──────────── 渲染 ──────────── */
 
   return (
@@ -294,15 +224,15 @@ const EditingPlanner: React.FC = () => {
           totalDuration={totalDuration}
           currentMode={tpl.currentMode}
           onSubtitleSettingsChange={(partial) =>
-            setSubtitleSettings((prev) => ({ ...prev, ...partial }) as SubtitleStyleConfig)
+            setSubtitleSettings((prev) => ({ ...prev, ...partial }))
           }
           onBgmSettingsChange={(partial) => setBgmSettings((prev) => ({ ...prev, ...partial }))}
           onClipUpdate={clipOps.handleClipUpdate}
           onOpenBgmDrawer={() => drawers.setBgmDrawerOpen(true)}
           onOpenSubtitleDrawer={() => drawers.setSubtitleDrawerOpen(true)}
           voiceMaterials={voiceMaterials}
-          voiceMaterialsLoading={voiceMaterialsQuery.isLoading}
-          onRefreshVoiceMaterials={() => voiceMaterialsQuery.refetch()}
+          voiceMaterialsLoading={voiceMaterialsLoading}
+          onRefreshVoiceMaterials={refetchVoiceMaterials}
           onClipVoiceSelect={clipOps.handleClipVoiceSelect}
           onOpenTransitionDrawer={drawers.openTransitionDrawer}
           onOpenSpeedDrawer={drawers.openSpeedDrawer}
@@ -382,28 +312,28 @@ const EditingPlanner: React.FC = () => {
         onCloseTtsDrawer={() => drawers.setTtsDrawerOpen(false)}
         watermarkDrawerOpen={drawers.watermarkDrawerOpen}
         watermarkSettings={watermarkSettings}
-        onWatermarkChange={handleWatermarkChange}
+        onWatermarkChange={setWatermarkSettings}
         onCloseWatermarkDrawer={() => drawers.setWatermarkDrawerOpen(false)}
         introOutroDrawerOpen={drawers.introOutroDrawerOpen}
         introOutroSettings={introOutroSettings}
-        onIntroOutroChange={handleIntroOutroChange}
+        onIntroOutroChange={setIntroOutroSettings}
         onCloseIntroOutroDrawer={() => drawers.setIntroOutroDrawerOpen(false)}
         pipDrawerOpen={drawers.pipDrawerOpen}
         pipSettings={pipSettings}
         totalDuration={totalDuration}
-        onPipChange={handlePipChange}
+        onPipChange={setPipSettings}
         onClosePipDrawer={() => drawers.setPipDrawerOpen(false)}
         filterDrawerOpen={drawers.filterDrawerOpen}
         filterSettings={filterSettings}
-        onFilterChange={handleFilterChange}
+        onFilterChange={setFilterSettings}
         onCloseFilterDrawer={() => drawers.setFilterDrawerOpen(false)}
         chromaKeyDrawerOpen={drawers.chromaKeyDrawerOpen}
         chromaKeySettings={chromaKeySettings}
-        onChromaKeyChange={handleChromaKeyChange}
+        onChromaKeyChange={setChromaKeySettings}
         onCloseChromaKeyDrawer={() => drawers.setChromaKeyDrawerOpen(false)}
         stickerDrawerOpen={drawers.stickerDrawerOpen}
         stickerSettings={stickerSettings}
-        onStickerChange={handleStickerChange}
+        onStickerChange={setStickerSettings}
         onCloseStickerDrawer={() => drawers.setStickerDrawerOpen(false)}
       />
     </div>

apps/web/src/pages/editing-planner/components/CoverSelector.tsx

@@ -1,286 +1,5 @@
 /**
- * 封面选择器
- * 抽帧选封面 + 上传自定义封面 + 智能封面推荐
+ * 封面选择器入口（向后兼容）
+ * 实际实现位于 ./cover-selector/ 目录
  */
-import React, { useCallback, useRef, useState } from "react"
-import { Drawer } from "antd"
-import type { CoverConfig, CoverMode } from "../types"
-import { DEFAULT_COVER_CONFIG } from "../types"
-
-interface CoverSelectorProps {
-  open: boolean
-  onClose: () => void
-  config: CoverConfig
-  onChange: (config: CoverConfig) => void
-  totalDuration: number
-}
-
-/** 封面模式标签 */
-const MODE_LABELS: Record<CoverMode, string> = {
-  auto: "智能封面",
-  frame: "抽帧选封面",
-  upload: "上传封面",
-}
-
-/** 封面模式图标 */
-const MODE_ICONS: Record<CoverMode, string> = {
-  auto: "🤖",
-  frame: "🎞️",
-  upload: "📤",
-}
-
-const CoverSelector: React.FC<CoverSelectorProps> = ({
-  open,
-  onClose,
-  config,
-  onChange,
-  totalDuration,
-}) => {
-  const fileInputRef = useRef<HTMLInputElement>(null)
-  const [isDragging, setIsDragging] = useState(false)
-
-  const update = useCallback(
-    (partial: Partial<CoverConfig>) => {
-      onChange({ ...config, ...partial })
-    },
-    [config, onChange],
-  )
-
-  const handleReset = useCallback(() => {
-    onChange({ ...DEFAULT_COVER_CONFIG, enabled: config.enabled })
-  }, [config.enabled, onChange])
-
-  /** 切换模式 */
-  const handleModeChange = useCallback(
-    (mode: CoverMode) => {
-      update({ mode })
-    },
-    [update],
-  )
-
-  /** 处理文件上传 */
-  const handleFileUpload = useCallback(
-    (file: File) => {
-      if (!file.type.startsWith("image/")) return
-      const reader = new FileReader()
-      reader.onload = (e) => {
-        const url = e.target?.result as string
-        update({ upload_url: url, thumbnail_url: url, mode: "upload" })
-      }
-      reader.readAsDataURL(file)
-    },
-    [update],
-  )
-
-  /** 拖拽上传 */
-  const handleDrop = useCallback(
-    (e: React.DragEvent) => {
-      e.preventDefault()
-      setIsDragging(false)
-      const file = e.dataTransfer.files[0]
-      if (file) handleFileUpload(file)
-    },
-    [handleFileUpload],
-  )
-
-  /** 使用 AI 推荐时间 */
-  const handleUseAiSuggestion = useCallback(() => {
-    if (config.ai_suggested_time !== null) {
-      update({ frame_time: config.ai_suggested_time, mode: "frame" })
-    }
-  }, [config.ai_suggested_time, update])
-
-  /** 格式化时间 */
-  const formatTime = (seconds: number) => {
-    const m = Math.floor(seconds / 60)
-    const s = Math.floor(seconds % 60)
-    const ms = Math.floor((seconds % 1) * 10)
-    return `${m.toString().padStart(2, "0")}:${s.toString().padStart(2, "0")}.${ms}`
-  }
-
-  return (
-    <Drawer
-      title="封面选择"
-      placement="right"
-      width={440}
-      open={open}
-      onClose={onClose}
-      className="cover-selector-drawer"
-    >
-      {/* 顶部开关 */}
-      <div className="cover-header">
-        <span className="cover-header-label">启用自定义封面</span>
-        <label className="cover-switch">
-          <input
-            type="checkbox"
-            checked={config.enabled}
-            onChange={(e) => update({ enabled: e.target.checked })}
-          />
-          <span className="cover-switch-slider" />
-        </label>
-      </div>
-
-      {/* 模式选择 */}
-      <div className="cover-mode-section">
-        <div className="cover-section-title">封面来源</div>
-        <div className="cover-mode-tabs">
-          {(["auto", "frame", "upload"] as CoverMode[]).map((m) => (
-            <button
-              key={m}
-              className={`cover-mode-tab${config.mode === m ? " active" : ""}`}
-              onClick={() => handleModeChange(m)}
-            >
-              <span className="cover-mode-icon">{MODE_ICONS[m]}</span>
-              <span className="cover-mode-label">{MODE_LABELS[m]}</span>
-            </button>
-          ))}
-        </div>
-      </div>
-
-      {/* 模式内容区 */}
-      <div className="cover-mode-content">
-        {/* 智能封面 */}
-        {config.mode === "auto" && (
-          <div className="cover-auto-section">
-            <div className="cover-auto-desc">
-              AI 将分析视频内容，自动选择最具吸引力的画面作为封面。
-            </div>
-            {config.ai_suggested_time !== null ? (
-              <div className="cover-auto-suggestion">
-                <div className="cover-auto-badge">AI 推荐</div>
-                <div className="cover-auto-time">
-                  推荐时间点：{formatTime(config.ai_suggested_time)}
-                </div>
-                <button className="cover-auto-use-btn" onClick={handleUseAiSuggestion}>
-                  使用此时间点
-                </button>
-              </div>
-            ) : (
-              <div className="cover-auto-pending">
-                <div className="cover-auto-spinner" />
-                <span>AI 分析中...（生成视频后自动推荐）</span>
-              </div>
-            )}
-          </div>
-        )}
-
-        {/* 抽帧选封面 */}
-        {config.mode === "frame" && (
-          <div className="cover-frame-section">
-            <div className="cover-frame-preview">
-              <div className="cover-frame-placeholder">
-                <span className="cover-frame-icon">🎞️</span>
-                <span className="cover-frame-time">{formatTime(config.frame_time)}</span>
-              </div>
-            </div>
-            <div className="cover-frame-timeline">
-              <div className="cover-frame-slider-header">
-                <span className="cover-frame-slider-label">拖动选择封面帧</span>
-                <span className="cover-frame-slider-value">{formatTime(config.frame_time)}</span>
-              </div>
-              <input
-                type="range"
-                className="cover-frame-slider"
-                min={0}
-                max={Math.max(totalDuration, 1)}
-                step={0.1}
-                value={config.frame_time}
-                onChange={(e) => update({ frame_time: Number(e.target.value) })}
-              />
-              <div className="cover-frame-range">
-                <span>00:00</span>
-                <span>{formatTime(totalDuration)}</span>
-              </div>
-            </div>
-            {/* 快捷时间点 */}
-            <div className="cover-frame-quick">
-              <span className="cover-quick-label">快捷选帧：</span>
-              {[0, 0.25, 0.5, 0.75].map((ratio) => {
-                const t = totalDuration * ratio
-                return (
-                  <button
-                    key={ratio}
-                    className="cover-quick-btn"
-                    onClick={() => update({ frame_time: t })}
-                  >
-                    {formatTime(t)}
-                  </button>
-                )
-              })}
-            </div>
-          </div>
-        )}
-
-        {/* 上传封面 */}
-        {config.mode === "upload" && (
-          <div className="cover-upload-section">
-            <div
-              className={`cover-upload-area${isDragging ? " dragging" : ""}`}
-              onDragOver={(e) => {
-                e.preventDefault()
-                setIsDragging(true)
-              }}
-              onDragLeave={() => setIsDragging(false)}
-              onDrop={handleDrop}
-              onClick={() => fileInputRef.current?.click()}
-            >
-              {config.upload_url ? (
-                <div className="cover-upload-preview">
-                  <img src={config.upload_url} alt="封面预览" />
-                  <div className="cover-upload-overlay">点击更换</div>
-                </div>
-              ) : (
-                <div className="cover-upload-placeholder">
-                  <span className="cover-upload-icon">📤</span>
-                  <span className="cover-upload-text">点击或拖拽上传封面图片</span>
-                  <span className="cover-upload-hint">支持 JPG / PNG，建议 16:9 比例</span>
-                </div>
-              )}
-              <input
-                ref={fileInputRef}
-                type="file"
-                accept="image/*"
-                style={{ display: "none" }}
-                onChange={(e) => {
-                  const file = e.target.files?.[0]
-                  if (file) handleFileUpload(file)
-                }}
-              />
-            </div>
-          </div>
-        )}
-      </div>
-
-      {/* 封面预览 */}
-      <div className="cover-preview-section">
-        <div className="cover-section-title">封面预览</div>
-        <div className="cover-preview-box">
-          {config.upload_url ? (
-            <img src={config.upload_url} alt="封面预览" className="cover-preview-img" />
-          ) : (
-            <div className="cover-preview-placeholder">
-              <span className="cover-preview-icon">🖼️</span>
-              <span className="cover-preview-text">
-                {config.mode === "auto"
-                  ? "AI 智能选择"
-                  : config.mode === "frame"
-                    ? `帧 ${formatTime(config.frame_time)}`
-                    : "未上传封面"}
-              </span>
-            </div>
-          )}
-          <div className="cover-preview-ratio">16:9</div>
-        </div>
-      </div>
-
-      {/* 底部 */}
-      <div className="cover-footer">
-        <button className="cover-reset-btn" onClick={handleReset}>
-          重置封面
-        </button>
-      </div>
-    </Drawer>
-  )
-}
-
-export default CoverSelector
+export { default } from "./cover-selector"

apps/web/src/pages/editing-planner/components/EditingDrawers.tsx

@@ -3,189 +3,32 @@
  * 纯渲染层，业务逻辑和 state 留在父组件
  */
 import React from "react"
-import type { TemplateCategory } from "@/api/editing-planner"
-import type {
-  ClipData,
-  TransitionConfig,
-  SpeedConfig,
-  TtsConfig,
-  WatermarkConfig,
-  IntroOutroConfig,
-  PipConfig,
-  FilterConfig,
-  ChromaKeyConfig,
-  StickerConfig,
-} from "../types"
-import { DEFAULT_TRANSITION, DEFAULT_SPEED, DEFAULT_TTS_CONFIG } from "../types"
-import type { SubtitleStyleConfig } from "../types/subtitle"
-import type { BgmMixConfig } from "@/api/bgm"
 import SaveModal from "./SaveModal"
-import BgmSelector from "./BgmSelector"
-import SubtitleStylePanel from "./SubtitleStylePanel"
-import TransitionSelector from "./TransitionSelector"
-import SpeedPanel from "./SpeedPanel"
-import TtsPanel from "./TtsPanel"
-import WatermarkPanel from "./WatermarkPanel"
-import IntroOutroPanel from "./IntroOutroPanel"
-import PipConfigPanel from "./PipConfigPanel"
-import FilterPanel from "./FilterPanel"
-import GreenScreenPanel from "./GreenScreenPanel"
-import StickerPanel from "./StickerPanel"
+import { ClipLevelDrawers } from "./editing-drawers/ClipLevelDrawers"
+import { GlobalDrawers } from "./editing-drawers/GlobalDrawers"
+import type { EditingDrawersProps } from "./editing-drawers/types"
 
-interface EditingDrawersProps {
-  /* 保存弹窗 */
-  saveModalOpen: boolean
-  saveLoading: boolean
-  isUpdate: boolean
-  draftName: string
-  draftCategory: string
-  draftTags: string
-  categories: TemplateCategory[]
-  estimatedDuration: number
-  onNameChange: (name: string) => void
-  onCategoryChange: (cat: string) => void
-  onTagsChange: (tags: string) => void
-  onSave: () => Promise<void>
-  onCancelSave: () => void
-  /* BGM */
-  bgmDrawerOpen: boolean
-  bgmSettings: BgmMixConfig
-  onCloseBgmDrawer: () => void
-  onChangeBgmSettings: (config: BgmMixConfig) => void
-  /* 字幕 */
-  subtitleDrawerOpen: boolean
-  subtitleSettings: SubtitleStyleConfig
-  onCloseSubtitleDrawer: () => void
-  onChangeSubtitleSettings: (config: SubtitleStyleConfig) => void
-  /* 转场 */
-  transitionDrawerOpen: boolean
-  transitionTargetClipId: string | null
-  onCloseTransitionDrawer: () => void
-  onTransitionChange: (config: TransitionConfig) => void
-  /* 调速 */
-  speedDrawerOpen: boolean
-  speedTargetClipId: string | null
-  onCloseSpeedDrawer: () => void
-  onSpeedChange: (config: SpeedConfig) => void
-  onApplySpeedAll: (config: SpeedConfig) => void
-  /* TTS 配音 */
-  ttsDrawerOpen: boolean
-  ttsTargetClipId: string | null
-  onCloseTtsDrawer: () => void
-  onTtsChange: (config: TtsConfig) => void
-  /* 水印 */
-  watermarkDrawerOpen: boolean
-  watermarkSettings: WatermarkConfig
-  onCloseWatermarkDrawer: () => void
-  onWatermarkChange: (config: WatermarkConfig) => void
-  /* 片头片尾 */
-  introOutroDrawerOpen: boolean
-  introOutroSettings: IntroOutroConfig
-  onCloseIntroOutroDrawer: () => void
-  onIntroOutroChange: (config: IntroOutroConfig) => void
-  /* 混剪 */
-  pipDrawerOpen: boolean
-  pipSettings: PipConfig
-  onClosePipDrawer: () => void
-  onPipChange: (config: PipConfig) => void
-  /* 滤镜调色 */
-  filterDrawerOpen: boolean
-  filterSettings: FilterConfig
-  onCloseFilterDrawer: () => void
-  onFilterChange: (config: FilterConfig) => void
-  /* 绿幕抠像 */
-  chromaKeyDrawerOpen: boolean
-  chromaKeySettings: ChromaKeyConfig
-  onCloseChromaKeyDrawer: () => void
-  onChromaKeyChange: (config: ChromaKeyConfig) => void
-  /* 贴纸 */
-  stickerDrawerOpen: boolean
-  stickerSettings: StickerConfig
-  onCloseStickerDrawer: () => void
-  onStickerChange: (config: StickerConfig) => void
-  /* 共享数据 */
-  clips: ClipData[]
-  totalDuration: number
-}
-
-const EditingDrawers: React.FC<EditingDrawersProps> = ({
-  saveModalOpen,
-  saveLoading,
-  isUpdate,
-  draftName,
-  draftCategory,
-  draftTags,
-  categories,
-  estimatedDuration,
-  onNameChange,
-  onCategoryChange,
-  onTagsChange,
-  onSave,
-  onCancelSave,
-  bgmDrawerOpen,
-  bgmSettings,
-  onCloseBgmDrawer,
-  onChangeBgmSettings,
-  subtitleDrawerOpen,
-  subtitleSettings,
-  onCloseSubtitleDrawer,
-  onChangeSubtitleSettings,
-  transitionDrawerOpen,
-  transitionTargetClipId,
-  onCloseTransitionDrawer,
-  onTransitionChange,
-  speedDrawerOpen,
-  speedTargetClipId,
-  onCloseSpeedDrawer,
-  onSpeedChange,
-  onApplySpeedAll,
-  ttsDrawerOpen,
-  ttsTargetClipId,
-  onCloseTtsDrawer,
-  onTtsChange,
-  watermarkDrawerOpen,
-  watermarkSettings,
-  onCloseWatermarkDrawer,
-  onWatermarkChange,
-  introOutroDrawerOpen,
-  introOutroSettings,
-  onCloseIntroOutroDrawer,
-  onIntroOutroChange,
-  pipDrawerOpen,
-  pipSettings,
-  onClosePipDrawer,
-  onPipChange,
-  filterDrawerOpen,
-  filterSettings,
-  onCloseFilterDrawer,
-  onFilterChange,
-  chromaKeyDrawerOpen,
-  chromaKeySettings,
-  onCloseChromaKeyDrawer,
-  onChromaKeyChange,
-  stickerDrawerOpen,
-  stickerSettings,
-  onCloseStickerDrawer,
-  onStickerChange,
-  clips,
-  totalDuration,
-}) => {
-  const transitionConfig = transitionTargetClipId
-    ? (clips.find((c) => c.id === transitionTargetClipId)?.transition ?? DEFAULT_TRANSITION)
-    : DEFAULT_TRANSITION
-  const transitionTitle = transitionTargetClipId ? "片段转场设置" : "全局默认转场"
-
-  const speedConfig = speedTargetClipId
-    ? (clips.find((c) => c.id === speedTargetClipId)?.speed ?? DEFAULT_SPEED)
-    : DEFAULT_SPEED
-
-  const ttsConfig = ttsTargetClipId
-    ? (clips.find((c) => c.id === ttsTargetClipId)?.tts_config ?? DEFAULT_TTS_CONFIG)
-    : DEFAULT_TTS_CONFIG
+const EditingDrawers: React.FC<EditingDrawersProps> = (props) => {
+  const {
+    saveModalOpen,
+    saveLoading,
+    isUpdate,
+    draftName,
+    draftCategory,
+    draftTags,
+    categories,
+    estimatedDuration,
+    onNameChange,
+    onCategoryChange,
+    onTagsChange,
+    onSave,
+    onCancelSave,
+    clips,
+  } = props
 
   return (
     <>
-      {/* ═══ 保存弹窗 ═══ */}
+      {/* 保存弹窗 */}
       <SaveModal
         open={saveModalOpen}
         loading={saveLoading}
@@ -202,100 +45,59 @@ const EditingDrawers: React.FC<EditingDrawersProps> = ({
         onCancel={onCancelSave}
       />
 
-      {/* ═══ BGM 选择器 Drawer ═══ */}
-      <BgmSelector
-        open={bgmDrawerOpen}
-        onClose={onCloseBgmDrawer}
-        config={bgmSettings}
-        onChange={onChangeBgmSettings}
+      {/* 片段级抽屉（转场/调速/TTS） */}
+      <ClipLevelDrawers
+        clips={clips}
+        transitionDrawerOpen={props.transitionDrawerOpen}
+        transitionTargetClipId={props.transitionTargetClipId}
+        onCloseTransitionDrawer={props.onCloseTransitionDrawer}
+        onTransitionChange={props.onTransitionChange}
+        speedDrawerOpen={props.speedDrawerOpen}
+        speedTargetClipId={props.speedTargetClipId}
+        onCloseSpeedDrawer={props.onCloseSpeedDrawer}
+        onSpeedChange={props.onSpeedChange}
+        onApplySpeedAll={props.onApplySpeedAll}
+        ttsDrawerOpen={props.ttsDrawerOpen}
+        ttsTargetClipId={props.ttsTargetClipId}
+        onCloseTtsDrawer={props.onCloseTtsDrawer}
+        onTtsChange={props.onTtsChange}
       />
 
-      {/* ═══ 字幕样式配置 Drawer ═══ */}
-      <SubtitleStylePanel
-        open={subtitleDrawerOpen}
-        onClose={onCloseSubtitleDrawer}
-        config={subtitleSettings}
-        onChange={onChangeSubtitleSettings}
-      />
-
-      {/* ═══ 转场特效选择器 Drawer ═══ */}
-      <TransitionSelector
-        open={transitionDrawerOpen}
-        onClose={onCloseTransitionDrawer}
-        config={transitionConfig}
-        onChange={onTransitionChange}
-        title={transitionTitle}
-      />
-
-      {/* ═══ 片段调速面板 Drawer ═══ */}
-      {speedTargetClipId && (
-        <SpeedPanel
-          open={speedDrawerOpen}
-          onClose={onCloseSpeedDrawer}
-          config={speedConfig}
-          onChange={onSpeedChange}
-          onApplyAll={onApplySpeedAll}
-        />
-      )}
-
-      {/* ═══ TTS 配音面板 Drawer ═══ */}
-      {ttsTargetClipId && (
-        <TtsPanel
-          open={ttsDrawerOpen}
-          onClose={onCloseTtsDrawer}
-          config={ttsConfig}
-          onChange={onTtsChange}
-        />
-      )}
-
-      {/* ═══ 水印配置面板 ═══ */}
-      <WatermarkPanel
-        open={watermarkDrawerOpen}
-        onClose={onCloseWatermarkDrawer}
-        config={watermarkSettings}
-        onChange={onWatermarkChange}
-      />
-
-      {/* ═══ 片头片尾配置面板 ═══ */}
-      <IntroOutroPanel
-        open={introOutroDrawerOpen}
-        onClose={onCloseIntroOutroDrawer}
-        config={introOutroSettings}
-        onChange={onIntroOutroChange}
-      />
-
-      {/* ═══ 混剪配置面板 ═══ */}
-      <PipConfigPanel
-        open={pipDrawerOpen}
-        onClose={onClosePipDrawer}
-        config={pipSettings}
-        onChange={onPipChange}
-        totalDuration={totalDuration}
-      />
-
-      {/* ═══ 滤镜调色面板 ═══ */}
-      <FilterPanel
-        open={filterDrawerOpen}
-        onClose={onCloseFilterDrawer}
-        config={filterSettings}
-        onChange={onFilterChange}
-      />
-
-      {/* ═══ 绿幕抠像面板 ═══ */}
-      <GreenScreenPanel
-        open={chromaKeyDrawerOpen}
-        onClose={onCloseChromaKeyDrawer}
-        config={chromaKeySettings}
-        onChange={onChromaKeyChange}
-      />
-
-      {/* ═══ 贴纸面板 ═══ */}
-      <StickerPanel
-        open={stickerDrawerOpen}
-        onClose={onCloseStickerDrawer}
-        config={stickerSettings}
-        onChange={onStickerChange}
-        totalDuration={totalDuration}
+      {/* 全局设置抽屉（BGM/字幕/水印/片头片尾/混剪/滤镜/绿幕/贴纸） */}
+      <GlobalDrawers
+        bgmDrawerOpen={props.bgmDrawerOpen}
+        bgmSettings={props.bgmSettings}
+        onCloseBgmDrawer={props.onCloseBgmDrawer}
+        onChangeBgmSettings={props.onChangeBgmSettings}
+        subtitleDrawerOpen={props.subtitleDrawerOpen}
+        subtitleSettings={props.subtitleSettings}
+        onCloseSubtitleDrawer={props.onCloseSubtitleDrawer}
+        onChangeSubtitleSettings={props.onChangeSubtitleSettings}
+        totalDuration={props.totalDuration}
+        watermarkDrawerOpen={props.watermarkDrawerOpen}
+        watermarkSettings={props.watermarkSettings}
+        onCloseWatermarkDrawer={props.onCloseWatermarkDrawer}
+        onWatermarkChange={props.onWatermarkChange}
+        introOutroDrawerOpen={props.introOutroDrawerOpen}
+        introOutroSettings={props.introOutroSettings}
+        onCloseIntroOutroDrawer={props.onCloseIntroOutroDrawer}
+        onIntroOutroChange={props.onIntroOutroChange}
+        pipDrawerOpen={props.pipDrawerOpen}
+        pipSettings={props.pipSettings}
+        onClosePipDrawer={props.onClosePipDrawer}
+        onPipChange={props.onPipChange}
+        filterDrawerOpen={props.filterDrawerOpen}
+        filterSettings={props.filterSettings}
+        onCloseFilterDrawer={props.onCloseFilterDrawer}
+        onFilterChange={props.onFilterChange}
+        chromaKeyDrawerOpen={props.chromaKeyDrawerOpen}
+        chromaKeySettings={props.chromaKeySettings}
+        onCloseChromaKeyDrawer={props.onCloseChromaKeyDrawer}
+        onChromaKeyChange={props.onChromaKeyChange}
+        stickerDrawerOpen={props.stickerDrawerOpen}
+        stickerSettings={props.stickerSettings}
+        onCloseStickerDrawer={props.onCloseStickerDrawer}
+        onStickerChange={props.onStickerChange}
       />
     </>
   )

apps/web/src/pages/editing-planner/components/clip-properties/ClipDetailSection.tsx

@@ -1,266 +1,5 @@
 /**
- * 片段详情区块
+ * ClipDetailSection 入口（向后兼容）
+ * 实际实现位于 ./clip-detail-section/ 目录
  */
-import React from "react"
-import { useNavigate } from "react-router-dom"
-import { TRANSITION_OPTIONS } from "@/api/template-editor"
-import type { ClipData, ClipType } from "@/pages/editing-planner/types"
-import { CLIP_TYPE_ICONS, CLIP_TYPE_LABELS } from "@/pages/editing-planner/constants/clipProperties"
-import { getGenderLabel } from "@/pages/editing-planner/utils/clipProperties"
-import type { AssetItem } from "@/api/assets"
-import type { TemplateMode } from "@/api/editing-planner"
-
-interface ClipDetailSectionProps {
-  clip: ClipData
-  currentMode: TemplateMode
-  voiceMaterials?: AssetItem[]
-  voiceMaterialsLoading?: boolean
-  onClipUpdate: (clipId: string, data: Partial<ClipData>) => void
-  onRefreshVoiceMaterials?: () => void
-  onClipVoiceSelect?: (clipId: string, asset: AssetItem | null) => void
-  onOpenTransitionDrawer?: (clipId: string) => void
-  onOpenSpeedDrawer?: (clipId: string) => void
-  onOpenTtsDrawer?: (clipId: string) => void
-  previewingId: string | null
-  onPreviewVoice: (asset: AssetItem) => void
-  onStopPreview: () => void
-}
-
-const ClipDetailSection: React.FC<ClipDetailSectionProps> = ({
-  clip,
-  currentMode,
-  voiceMaterials = [],
-  voiceMaterialsLoading = false,
-  onClipUpdate,
-  onRefreshVoiceMaterials,
-  onClipVoiceSelect,
-  onOpenTransitionDrawer,
-  onOpenSpeedDrawer,
-  onOpenTtsDrawer,
-  previewingId,
-  onPreviewVoice,
-  onStopPreview,
-}) => {
-  const navigate = useNavigate()
-
-  const isTypeDisabled = (t: ClipType) => {
-    if (currentMode === "pip") return t !== "pip"
-    if (currentMode === "voice_over") return t !== "voice"
-    return false
-  }
-
-  const transitionLabel = (() => {
-    const t = clip.transition
-    if (!t || t.type === "none") return "无转场"
-    const opt = TRANSITION_OPTIONS.find((o) => o.value === t.type)
-    return `${opt?.label ?? t.type} · ${t.duration.toFixed(1)}s`
-  })()
-
-  const speedLabel = clip.speed ? `${clip.speed.rate.toFixed(2)}x` : "1.00x"
-
-  const ttsLabel = (() => {
-    const tts = clip.tts_config
-    if (!tts || tts.mode === "none") return "无配音"
-    if (tts.mode === "upload") return "上传配音"
-    return `TTS · ${tts.voice_id ? "已选音色" : "未选音色"}`
-  })()
-
-  return (
-    <div className="ep-settings-section">
-      <div className="ep-section-title">
-        <span className="ep-section-icon">🎞️</span>
-        片段详情
-      </div>
-
-      <div className="ep-clip-detail">
-        {/* 类型选择器 */}
-        <div className="ep-clip-detail-field">
-          <div className="ep-clip-detail-label">类型</div>
-          <div className="ep-clip-type-selector">
-            {(["voice", "pip"] as ClipType[]).map((t) => {
-              const disabled = isTypeDisabled(t)
-              return (
-                <button
-                  key={t}
-                  className={`ep-clip-type-btn${clip.type === t ? " active" : ""}${disabled ? " disabled" : ""}`}
-                  disabled={disabled}
-                  onClick={() => !disabled && onClipUpdate(clip.id, { type: t })}
-                >
-                  {CLIP_TYPE_ICONS[t]} {CLIP_TYPE_LABELS[t]}
-                </button>
-              )
-            })}
-          </div>
-        </div>
-
-        {/* 时长 */}
-        <div className="ep-clip-detail-field">
-          <div className="ep-clip-detail-label">时长</div>
-          <div className="ep-clip-detail-row">
-            <input
-              className="ep-duration-input"
-              type="number"
-              min={1}
-              max={120}
-              value={clip.duration}
-              onChange={(e) =>
-                onClipUpdate(clip.id, {
-                  duration: Math.max(1, Math.min(120, Number(e.target.value) || 1)),
-                })
-              }
-            />
-            <span className="ep-clip-detail-unit">秒</span>
-          </div>
-        </div>
-
-        {/* 转场效果入口 */}
-        {onOpenTransitionDrawer && (
-          <div className="ep-clip-detail-field">
-            <button
-              className="ep-advanced-btn ep-advanced-btn--transition"
-              onClick={() => onOpenTransitionDrawer(clip.id)}
-            >
-              <span className="ep-advanced-btn-icon">🎬</span>
-              <span className="ep-advanced-btn-label">转场效果</span>
-              <span className="ep-advanced-btn-value">{transitionLabel}</span>
-              <span className="ep-advanced-btn-arrow">›</span>
-            </button>
-          </div>
-        )}
-
-        {/* 播放速度入口 */}
-        {onOpenSpeedDrawer && (
-          <div className="ep-clip-detail-field">
-            <button
-              className="ep-advanced-btn ep-advanced-btn--speed"
-              onClick={() => onOpenSpeedDrawer(clip.id)}
-            >
-              <span className="ep-advanced-btn-icon">⚡</span>
-              <span className="ep-advanced-btn-label">播放速度</span>
-              <span className="ep-advanced-btn-value">{speedLabel}</span>
-              <span className="ep-advanced-btn-arrow">›</span>
-            </button>
-          </div>
-        )}
-
-        {/* TTS 配音入口 */}
-        {onOpenTtsDrawer && (
-          <div className="ep-clip-detail-field">
-            <button
-              className="ep-advanced-btn ep-advanced-btn--tts"
-              onClick={() => onOpenTtsDrawer(clip.id)}
-            >
-              <span className="ep-advanced-btn-icon">🎙️</span>
-              <span className="ep-advanced-btn-label">TTS 配音</span>
-              <span className="ep-advanced-btn-value">{ttsLabel}</span>
-              <span className="ep-advanced-btn-arrow">›</span>
-            </button>
-          </div>
-        )}
-
-        {/* 素材起始时间 — 仅 voice 类型显示 */}
-        {clip.type === "voice" && (
-          <div className="ep-clip-detail-field">
-            <div className="ep-clip-detail-label">素材起始时间</div>
-            <div className="ep-clip-detail-row">
-              <input
-                className="ep-duration-input"
-                type="number"
-                min={0}
-                max={9999}
-                step={0.1}
-                value={clip.startOffset}
-                onChange={(e) =>
-                  onClipUpdate(clip.id, {
-                    startOffset: Math.max(0, Math.min(9999, Number(e.target.value) || 0)),
-                  })
-                }
-              />
-              <span className="ep-clip-detail-unit">秒</span>
-            </div>
-          </div>
-        )}
-
-        {/* 配音素材选择 — 仅 voice 类型显示 */}
-        {clip.type === "voice" && (
-          <div className="ep-clip-detail-field">
-            <div className="ep-clip-detail-label">
-              配音素材
-              {onRefreshVoiceMaterials && (
-                <button
-                  type="button"
-                  className="ep-voice-refresh-btn"
-                  title="刷新配音列表"
-                  onClick={() => onRefreshVoiceMaterials()}
-                  disabled={voiceMaterialsLoading}
-                >
-                  {voiceMaterialsLoading ? "⏳" : "🔄"}
-                </button>
-              )}
-            </div>
-
-            {voiceMaterialsLoading && voiceMaterials.length === 0 ? (
-              <div className="ep-voice-loading">加载中...</div>
-            ) : (
-              <>
-                <div className="ep-voice-select-row">
-                  <select
-                    className="ep-clip-detail-select"
-                    value={clip.voice_asset_id ?? ""}
-                    onChange={(e) => {
-                      const assetId = e.target.value
-                      if (!onClipVoiceSelect) return
-                      if (!assetId) {
-                        onClipVoiceSelect(clip.id, null)
-                      } else {
-                        const asset = voiceMaterials.find((m) => m.id === assetId)
-                        if (asset) onClipVoiceSelect(clip.id, asset)
-                      }
-                      onStopPreview()
-                    }}
-                  >
-                    <option value="">未选择</option>
-                    {voiceMaterials.map((m) => {
-                      const gender = getGenderLabel(m)
-                      const label = gender ? `${m.name}（${gender}）` : m.name
-                      return (
-                        <option key={m.id} value={m.id}>
-                          {label}
-                        </option>
-                      )
-                    })}
-                  </select>
-                  {clip.voice_asset_id && (
-                    <button
-                      type="button"
-                      className="ep-voice-preview-btn"
-                      title={previewingId === clip.voice_asset_id ? "暂停" : "试听"}
-                      onClick={() => {
-                        const asset = voiceMaterials.find((m) => m.id === clip.voice_asset_id)
-                        if (asset) onPreviewVoice(asset)
-                      }}
-                    >
-                      {previewingId === clip.voice_asset_id ? "⏸" : "▶️"}
-                    </button>
-                  )}
-                </div>
-                {voiceMaterials.length === 0 && (
-                  <div className="ep-voice-empty">暂无配音素材，请先上传</div>
-                )}
-              </>
-            )}
-
-            <button
-              className="ep-voice-upload-btn"
-              onClick={() => navigate("/app/voice-materials")}
-            >
-              + 上传新配音
-            </button>
-          </div>
-        )}
-      </div>
-    </div>
-  )
-}
-
-export default ClipDetailSection
+export { default } from "./clip-detail-section"

apps/web/src/pages/editing-planner/components/clip-properties/clip-detail-section/AdvancedEntries.tsx

@@ -0,0 +1,85 @@
+import React from "react"
+import { TRANSITION_OPTIONS } from "@/api/template-editor"
+import type { ClipData } from "@/pages/editing-planner/types"
+
+interface AdvancedEntriesProps {
+  clip: ClipData
+  onOpenTransitionDrawer?: (clipId: string) => void
+  onOpenSpeedDrawer?: (clipId: string) => void
+  onOpenTtsDrawer?: (clipId: string) => void
+}
+
+/**
+ * 高级功能入口按钮（转场/调速/TTS）
+ */
+export const AdvancedEntries: React.FC<AdvancedEntriesProps> = ({
+  clip,
+  onOpenTransitionDrawer,
+  onOpenSpeedDrawer,
+  onOpenTtsDrawer,
+}) => {
+  const transitionLabel = (() => {
+    const t = clip.transition
+    if (!t || t.type === "none") return "无转场"
+    const opt = TRANSITION_OPTIONS.find((o) => o.value === t.type)
+    return `${opt?.label ?? t.type} · ${t.duration.toFixed(1)}s`
+  })()
+
+  const speedLabel = clip.speed ? `${clip.speed.rate.toFixed(2)}x` : "1.00x"
+
+  const ttsLabel = (() => {
+    const tts = clip.tts_config
+    if (!tts || tts.mode === "none") return "无配音"
+    if (tts.mode === "upload") return "上传配音"
+    return `TTS · ${tts.voice_id ? "已选音色" : "未选音色"}`
+  })()
+
+  return (
+    <>
+      {/* 转场效果入口 */}
+      {onOpenTransitionDrawer && (
+        <div className="ep-clip-detail-field">
+          <button
+            className="ep-advanced-btn ep-advanced-btn--transition"
+            onClick={() => onOpenTransitionDrawer(clip.id)}
+          >
+            <span className="ep-advanced-btn-icon">🎬</span>
+            <span className="ep-advanced-btn-label">转场效果</span>
+            <span className="ep-advanced-btn-value">{transitionLabel}</span>
+            <span className="ep-advanced-btn-arrow">›</span>
+          </button>
+        </div>
+      )}
+
+      {/* 播放速度入口 */}
+      {onOpenSpeedDrawer && (
+        <div className="ep-clip-detail-field">
+          <button
+            className="ep-advanced-btn ep-advanced-btn--speed"
+            onClick={() => onOpenSpeedDrawer(clip.id)}
+          >
+            <span className="ep-advanced-btn-icon">⚡</span>
+            <span className="ep-advanced-btn-label">播放速度</span>
+            <span className="ep-advanced-btn-value">{speedLabel}</span>
+            <span className="ep-advanced-btn-arrow">›</span>
+          </button>
+        </div>
+      )}
+
+      {/* TTS 配音入口 */}
+      {onOpenTtsDrawer && (
+        <div className="ep-clip-detail-field">
+          <button
+            className="ep-advanced-btn ep-advanced-btn--tts"
+            onClick={() => onOpenTtsDrawer(clip.id)}
+          >
+            <span className="ep-advanced-btn-icon">🎙️</span>
+            <span className="ep-advanced-btn-label">TTS 配音</span>
+            <span className="ep-advanced-btn-value">{ttsLabel}</span>
+            <span className="ep-advanced-btn-arrow">›</span>
+          </button>
+        </div>
+      )}
+    </>
+  )
+}

apps/web/src/pages/editing-planner/components/clip-properties/clip-detail-section/ClipTypeAndDuration.tsx

@@ -0,0 +1,69 @@
+import React from "react"
+import type { ClipData, ClipType } from "@/pages/editing-planner/types"
+import { CLIP_TYPE_ICONS, CLIP_TYPE_LABELS } from "@/pages/editing-planner/constants/clipProperties"
+import type { TemplateMode } from "@/api/editing-planner"
+
+interface ClipTypeAndDurationProps {
+  clip: ClipData
+  currentMode: TemplateMode
+  onClipUpdate: (clipId: string, data: Partial<ClipData>) => void
+}
+
+/**
+ * 片段类型选择 + 时长设置
+ */
+export const ClipTypeAndDuration: React.FC<ClipTypeAndDurationProps> = ({
+  clip,
+  currentMode,
+  onClipUpdate,
+}) => {
+  const isTypeDisabled = (t: ClipType) => {
+    if (currentMode === "pip") return t !== "pip"
+    if (currentMode === "voice_over") return t !== "voice"
+    return false
+  }
+
+  return (
+    <>
+      {/* 类型选择器 */}
+      <div className="ep-clip-detail-field">
+        <div className="ep-clip-detail-label">类型</div>
+        <div className="ep-clip-type-selector">
+          {(["voice", "pip"] as ClipType[]).map((t) => {
+            const disabled = isTypeDisabled(t)
+            return (
+              <button
+                key={t}
+                className={`ep-clip-type-btn${clip.type === t ? " active" : ""}${disabled ? " disabled" : ""}`}
+                disabled={disabled}
+                onClick={() => !disabled && onClipUpdate(clip.id, { type: t })}
+              >
+                {CLIP_TYPE_ICONS[t]} {CLIP_TYPE_LABELS[t]}
+              </button>
+            )
+          })}
+        </div>
+      </div>
+
+      {/* 时长 */}
+      <div className="ep-clip-detail-field">
+        <div className="ep-clip-detail-label">时长</div>
+        <div className="ep-clip-detail-row">
+          <input
+            className="ep-duration-input"
+            type="number"
+            min={1}
+            max={120}
+            value={clip.duration}
+            onChange={(e) =>
+              onClipUpdate(clip.id, {
+                duration: Math.max(1, Math.min(120, Number(e.target.value) || 1)),
+              })
+            }
+          />
+          <span className="ep-clip-detail-unit">秒</span>
+        </div>
+      </div>
+    </>
+  )
+}

apps/web/src/pages/editing-planner/components/clip-properties/clip-detail-section/VoiceMaterialSection.tsx

@@ -0,0 +1,132 @@
+import React from "react"
+import { useNavigate } from "react-router-dom"
+import type { ClipData } from "@/pages/editing-planner/types"
+import { getGenderLabel } from "@/pages/editing-planner/utils/clipProperties"
+import type { AssetItem } from "@/api/assets"
+
+interface VoiceMaterialSectionProps {
+  clip: ClipData
+  voiceMaterials: AssetItem[]
+  voiceMaterialsLoading: boolean
+  onClipUpdate: (clipId: string, data: Partial<ClipData>) => void
+  onRefreshVoiceMaterials?: () => void
+  onClipVoiceSelect?: (clipId: string, asset: AssetItem | null) => void
+  previewingId: string | null
+  onPreviewVoice: (asset: AssetItem) => void
+  onStopPreview: () => void
+}
+
+/**
+ * 配音素材选择区（仅 voice 类型显示）
+ */
+export const VoiceMaterialSection: React.FC<VoiceMaterialSectionProps> = ({
+  clip,
+  voiceMaterials,
+  voiceMaterialsLoading,
+  onClipUpdate,
+  onRefreshVoiceMaterials,
+  onClipVoiceSelect,
+  previewingId,
+  onPreviewVoice,
+  onStopPreview,
+}) => {
+  const navigate = useNavigate()
+
+  return (
+    <>
+      {/* 素材起始时间 */}
+      <div className="ep-clip-detail-field">
+        <div className="ep-clip-detail-label">素材起始时间</div>
+        <div className="ep-clip-detail-row">
+          <input
+            className="ep-duration-input"
+            type="number"
+            min={0}
+            max={9999}
+            step={0.1}
+            value={clip.startOffset}
+            onChange={(e) =>
+              onClipUpdate(clip.id, {
+                startOffset: Math.max(0, Math.min(9999, Number(e.target.value) || 0)),
+              })
+            }
+          />
+          <span className="ep-clip-detail-unit">秒</span>
+        </div>
+      </div>
+
+      {/* 配音素材选择 */}
+      <div className="ep-clip-detail-field">
+        <div className="ep-clip-detail-label">
+          配音素材
+          {onRefreshVoiceMaterials && (
+            <button
+              type="button"
+              className="ep-voice-refresh-btn"
+              title="刷新配音列表"
+              onClick={() => onRefreshVoiceMaterials()}
+              disabled={voiceMaterialsLoading}
+            >
+              {voiceMaterialsLoading ? "⏳" : "🔄"}
+            </button>
+          )}
+        </div>
+
+        {voiceMaterialsLoading && voiceMaterials.length === 0 ? (
+          <div className="ep-voice-loading">加载中...</div>
+        ) : (
+          <>
+            <div className="ep-voice-select-row">
+              <select
+                className="ep-clip-detail-select"
+                value={clip.voice_asset_id ?? ""}
+                onChange={(e) => {
+                  const assetId = e.target.value
+                  if (!onClipVoiceSelect) return
+                  if (!assetId) {
+                    onClipVoiceSelect(clip.id, null)
+                  } else {
+                    const asset = voiceMaterials.find((m) => m.id === assetId)
+                    if (asset) onClipVoiceSelect(clip.id, asset)
+                  }
+                  onStopPreview()
+                }}
+              >
+                <option value="">未选择</option>
+                {voiceMaterials.map((m) => {
+                  const gender = getGenderLabel(m)
+                  const label = gender ? `${m.name}（${gender}）` : m.name
+                  return (
+                    <option key={m.id} value={m.id}>
+                      {label}
+                    </option>
+                  )
+                })}
+              </select>
+              {clip.voice_asset_id && (
+                <button
+                  type="button"
+                  className="ep-voice-preview-btn"
+                  title={previewingId === clip.voice_asset_id ? "暂停" : "试听"}
+                  onClick={() => {
+                    const asset = voiceMaterials.find((m) => m.id === clip.voice_asset_id)
+                    if (asset) onPreviewVoice(asset)
+                  }}
+                >
+                  {previewingId === clip.voice_asset_id ? "⏸" : "▶️"}
+                </button>
+              )}
+            </div>
+            {voiceMaterials.length === 0 && (
+              <div className="ep-voice-empty">暂无配音素材，请先上传</div>
+            )}
+          </>
+        )}
+
+        <button className="ep-voice-upload-btn" onClick={() => navigate("/app/voice-materials")}>
+          + 上传新配音
+        </button>
+      </div>
+    </>
+  )
+}

apps/web/src/pages/editing-planner/components/clip-properties/clip-detail-section/index.tsx

@@ -0,0 +1,78 @@
+/**
+ * 片段详情区块
+ */
+import React from "react"
+import type { ClipData } from "@/pages/editing-planner/types"
+import type { AssetItem } from "@/api/assets"
+import type { TemplateMode } from "@/api/editing-planner"
+import { ClipTypeAndDuration } from "./ClipTypeAndDuration"
+import { AdvancedEntries } from "./AdvancedEntries"
+import { VoiceMaterialSection } from "./VoiceMaterialSection"
+
+interface ClipDetailSectionProps {
+  clip: ClipData
+  currentMode: TemplateMode
+  voiceMaterials?: AssetItem[]
+  voiceMaterialsLoading?: boolean
+  onClipUpdate: (clipId: string, data: Partial<ClipData>) => void
+  onRefreshVoiceMaterials?: () => void
+  onClipVoiceSelect?: (clipId: string, asset: AssetItem | null) => void
+  onOpenTransitionDrawer?: (clipId: string) => void
+  onOpenSpeedDrawer?: (clipId: string) => void
+  onOpenTtsDrawer?: (clipId: string) => void
+  previewingId: string | null
+  onPreviewVoice: (asset: AssetItem) => void
+  onStopPreview: () => void
+}
+
+const ClipDetailSection: React.FC<ClipDetailSectionProps> = ({
+  clip,
+  currentMode,
+  voiceMaterials = [],
+  voiceMaterialsLoading = false,
+  onClipUpdate,
+  onRefreshVoiceMaterials,
+  onClipVoiceSelect,
+  onOpenTransitionDrawer,
+  onOpenSpeedDrawer,
+  onOpenTtsDrawer,
+  previewingId,
+  onPreviewVoice,
+  onStopPreview,
+}) => {
+  return (
+    <div className="ep-settings-section">
+      <div className="ep-section-title">
+        <span className="ep-section-icon">🎞️</span>
+        片段详情
+      </div>
+
+      <div className="ep-clip-detail">
+        <ClipTypeAndDuration clip={clip} currentMode={currentMode} onClipUpdate={onClipUpdate} />
+
+        <AdvancedEntries
+          clip={clip}
+          onOpenTransitionDrawer={onOpenTransitionDrawer}
+          onOpenSpeedDrawer={onOpenSpeedDrawer}
+          onOpenTtsDrawer={onOpenTtsDrawer}
+        />
+
+        {clip.type === "voice" && (
+          <VoiceMaterialSection
+            clip={clip}
+            voiceMaterials={voiceMaterials}
+            voiceMaterialsLoading={voiceMaterialsLoading}
+            onClipUpdate={onClipUpdate}
+            onRefreshVoiceMaterials={onRefreshVoiceMaterials}
+            onClipVoiceSelect={onClipVoiceSelect}
+            previewingId={previewingId}
+            onPreviewVoice={onPreviewVoice}
+            onStopPreview={onStopPreview}
+          />
+        )}
+      </div>
+    </div>
+  )
+}
+
+export default ClipDetailSection

apps/web/src/pages/editing-planner/components/cover-selector/CoverModePanels.tsx

@@ -0,0 +1,143 @@
+import React from "react"
+import type { CoverConfig } from "../../types"
+
+interface CoverAutoModeProps {
+  config: CoverConfig
+  formatTime: (s: number) => string
+  onUseAiSuggestion: () => void
+}
+
+/** 智能封面模式面板 */
+export const CoverAutoMode: React.FC<CoverAutoModeProps> = ({
+  config,
+  formatTime,
+  onUseAiSuggestion,
+}) => (
+  <div className="cover-auto-section">
+    <div className="cover-auto-desc">AI 将分析视频内容，自动选择最具吸引力的画面作为封面。</div>
+    {config.ai_suggested_time !== null ? (
+      <div className="cover-auto-suggestion">
+        <div className="cover-auto-badge">AI 推荐</div>
+        <div className="cover-auto-time">推荐时间点：{formatTime(config.ai_suggested_time)}</div>
+        <button className="cover-auto-use-btn" onClick={onUseAiSuggestion}>
+          使用此时间点
+        </button>
+      </div>
+    ) : (
+      <div className="cover-auto-pending">
+        <div className="cover-auto-spinner" />
+        <span>AI 分析中...（生成视频后自动推荐）</span>
+      </div>
+    )}
+  </div>
+)
+
+interface CoverFrameModeProps {
+  config: CoverConfig
+  totalDuration: number
+  formatTime: (s: number) => string
+  onFrameTimeChange: (time: number) => void
+}
+
+/** 抽帧选封面模式面板 */
+export const CoverFrameMode: React.FC<CoverFrameModeProps> = ({
+  config,
+  totalDuration,
+  formatTime,
+  onFrameTimeChange,
+}) => (
+  <div className="cover-frame-section">
+    <div className="cover-frame-preview">
+      <div className="cover-frame-placeholder">
+        <span className="cover-frame-icon">🎞️</span>
+        <span className="cover-frame-time">{formatTime(config.frame_time)}</span>
+      </div>
+    </div>
+    <div className="cover-frame-timeline">
+      <div className="cover-frame-slider-header">
+        <span className="cover-frame-slider-label">拖动选择封面帧</span>
+        <span className="cover-frame-slider-value">{formatTime(config.frame_time)}</span>
+      </div>
+      <input
+        type="range"
+        className="cover-frame-slider"
+        min={0}
+        max={Math.max(totalDuration, 1)}
+        step={0.1}
+        value={config.frame_time}
+        onChange={(e) => onFrameTimeChange(Number(e.target.value))}
+      />
+      <div className="cover-frame-range">
+        <span>00:00</span>
+        <span>{formatTime(totalDuration)}</span>
+      </div>
+    </div>
+    <div className="cover-frame-quick">
+      <span className="cover-quick-label">快捷选帧：</span>
+      {[0, 0.25, 0.5, 0.75].map((ratio) => {
+        const t = totalDuration * ratio
+        return (
+          <button key={ratio} className="cover-quick-btn" onClick={() => onFrameTimeChange(t)}>
+            {formatTime(t)}
+          </button>
+        )
+      })}
+    </div>
+  </div>
+)
+
+interface CoverUploadModeProps {
+  config: CoverConfig
+  isDragging: boolean
+  fileInputRef: React.RefObject<HTMLInputElement>
+  onDragOver: (e: React.DragEvent) => void
+  onDragLeave: () => void
+  onDrop: (e: React.DragEvent) => void
+  onAreaClick: () => void
+  onFileChange: (file: File) => void
+}
+
+/** 上传封面模式面板 */
+export const CoverUploadMode: React.FC<CoverUploadModeProps> = ({
+  config,
+  isDragging,
+  fileInputRef,
+  onDragOver,
+  onDragLeave,
+  onDrop,
+  onAreaClick,
+  onFileChange,
+}) => (
+  <div className="cover-upload-section">
+    <div
+      className={`cover-upload-area${isDragging ? " dragging" : ""}`}
+      onDragOver={onDragOver}
+      onDragLeave={onDragLeave}
+      onDrop={onDrop}
+      onClick={onAreaClick}
+    >
+      {config.upload_url ? (
+        <div className="cover-upload-preview">
+          <img src={config.upload_url} alt="封面预览" />
+          <div className="cover-upload-overlay">点击更换</div>
+        </div>
+      ) : (
+        <div className="cover-upload-placeholder">
+          <span className="cover-upload-icon">📤</span>
+          <span className="cover-upload-text">点击或拖拽上传封面图片</span>
+          <span className="cover-upload-hint">支持 JPG / PNG，建议 16:9 比例</span>
+        </div>
+      )}
+      <input
+        ref={fileInputRef}
+        type="file"
+        accept="image/*"
+        style={{ display: "none" }}
+        onChange={(e) => {
+          const file = e.target.files?.[0]
+          if (file) onFileChange(file)
+        }}
+      />
+    </div>
+  </div>
+)

apps/web/src/pages/editing-planner/components/cover-selector/index.tsx

@@ -0,0 +1,146 @@
+/**
+ * 封面选择器
+ * 抽帧选封面 + 上传自定义封面 + 智能封面推荐
+ */
+import React from "react"
+import { Drawer } from "antd"
+import type { CoverConfig, CoverMode } from "../../types"
+import { useCoverSelector, MODE_LABELS, MODE_ICONS } from "./useCoverSelector"
+import { CoverAutoMode, CoverFrameMode, CoverUploadMode } from "./CoverModePanels"
+
+interface CoverSelectorProps {
+  open: boolean
+  onClose: () => void
+  config: CoverConfig
+  onChange: (config: CoverConfig) => void
+  totalDuration: number
+}
+
+const CoverSelector: React.FC<CoverSelectorProps> = ({
+  open,
+  onClose,
+  config,
+  onChange,
+  totalDuration,
+}) => {
+  const {
+    fileInputRef,
+    isDragging,
+    setIsDragging,
+    update,
+    handleReset,
+    handleModeChange,
+    handleFileUpload,
+    handleDrop,
+    handleUseAiSuggestion,
+    formatTime,
+  } = useCoverSelector({ config, onChange })
+
+  return (
+    <Drawer
+      title="封面选择"
+      placement="right"
+      width={440}
+      open={open}
+      onClose={onClose}
+      className="cover-selector-drawer"
+    >
+      {/* 顶部开关 */}
+      <div className="cover-header">
+        <span className="cover-header-label">启用自定义封面</span>
+        <label className="cover-switch">
+          <input
+            type="checkbox"
+            checked={config.enabled}
+            onChange={(e) => update({ enabled: e.target.checked })}
+          />
+          <span className="cover-switch-slider" />
+        </label>
+      </div>
+
+      {/* 模式选择 */}
+      <div className="cover-mode-section">
+        <div className="cover-section-title">封面来源</div>
+        <div className="cover-mode-tabs">
+          {(["auto", "frame", "upload"] as CoverMode[]).map((m) => (
+            <button
+              key={m}
+              className={`cover-mode-tab${config.mode === m ? " active" : ""}`}
+              onClick={() => handleModeChange(m)}
+            >
+              <span className="cover-mode-icon">{MODE_ICONS[m]}</span>
+              <span className="cover-mode-label">{MODE_LABELS[m]}</span>
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {/* 模式内容区 */}
+      <div className="cover-mode-content">
+        {config.mode === "auto" && (
+          <CoverAutoMode
+            config={config}
+            formatTime={formatTime}
+            onUseAiSuggestion={handleUseAiSuggestion}
+          />
+        )}
+
+        {config.mode === "frame" && (
+          <CoverFrameMode
+            config={config}
+            totalDuration={totalDuration}
+            formatTime={formatTime}
+            onFrameTimeChange={(t) => update({ frame_time: t })}
+          />
+        )}
+
+        {config.mode === "upload" && (
+          <CoverUploadMode
+            config={config}
+            isDragging={isDragging}
+            fileInputRef={fileInputRef}
+            onDragOver={(e) => {
+              e.preventDefault()
+              setIsDragging(true)
+            }}
+            onDragLeave={() => setIsDragging(false)}
+            onDrop={handleDrop}
+            onAreaClick={() => fileInputRef.current?.click()}
+            onFileChange={handleFileUpload}
+          />
+        )}
+      </div>
+
+      {/* 封面预览 */}
+      <div className="cover-preview-section">
+        <div className="cover-section-title">封面预览</div>
+        <div className="cover-preview-box">
+          {config.upload_url ? (
+            <img src={config.upload_url} alt="封面预览" className="cover-preview-img" />
+          ) : (
+            <div className="cover-preview-placeholder">
+              <span className="cover-preview-icon">🖼️</span>
+              <span className="cover-preview-text">
+                {config.mode === "auto"
+                  ? "AI 智能选择"
+                  : config.mode === "frame"
+                    ? `帧 ${formatTime(config.frame_time)}`
+                    : "未上传封面"}
+              </span>
+            </div>
+          )}
+          <div className="cover-preview-ratio">16:9</div>
+        </div>
+      </div>
+
+      {/* 底部 */}
+      <div className="cover-footer">
+        <button className="cover-reset-btn" onClick={handleReset}>
+          重置封面
+        </button>
+      </div>
+    </Drawer>
+  )
+}
+
+export default CoverSelector

apps/web/src/pages/editing-planner/components/cover-selector/useCoverSelector.ts

@@ -0,0 +1,98 @@
+import { useCallback, useRef, useState } from "react"
+import type { CoverConfig, CoverMode } from "../../types"
+import { DEFAULT_COVER_CONFIG } from "../../types"
+
+/** 封面模式标签 */
+export const MODE_LABELS: Record<CoverMode, string> = {
+  auto: "智能封面",
+  frame: "抽帧选封面",
+  upload: "上传封面",
+}
+
+/** 封面模式图标 */
+export const MODE_ICONS: Record<CoverMode, string> = {
+  auto: "🤖",
+  frame: "🎞️",
+  upload: "📤",
+}
+
+interface UseCoverSelectorOptions {
+  config: CoverConfig
+  onChange: (config: CoverConfig) => void
+}
+
+/**
+ * 封面选择器 Hook
+ * 封装状态管理、文件上传、模式切换等逻辑
+ */
+export function useCoverSelector({ config, onChange }: UseCoverSelectorOptions) {
+  const fileInputRef = useRef<HTMLInputElement>(null)
+  const [isDragging, setIsDragging] = useState(false)
+
+  const update = useCallback(
+    (partial: Partial<CoverConfig>) => {
+      onChange({ ...config, ...partial })
+    },
+    [config, onChange],
+  )
+
+  const handleReset = useCallback(() => {
+    onChange({ ...DEFAULT_COVER_CONFIG, enabled: config.enabled })
+  }, [config.enabled, onChange])
+
+  const handleModeChange = useCallback(
+    (mode: CoverMode) => {
+      update({ mode })
+    },
+    [update],
+  )
+
+  const handleFileUpload = useCallback(
+    (file: File) => {
+      if (!file.type.startsWith("image/")) return
+      const reader = new FileReader()
+      reader.onload = (e) => {
+        const url = e.target?.result as string
+        update({ upload_url: url, thumbnail_url: url, mode: "upload" })
+      }
+      reader.readAsDataURL(file)
+    },
+    [update],
+  )
+
+  const handleDrop = useCallback(
+    (e: React.DragEvent) => {
+      e.preventDefault()
+      setIsDragging(false)
+      const file = e.dataTransfer.files[0]
+      if (file) handleFileUpload(file)
+    },
+    [handleFileUpload],
+  )
+
+  const handleUseAiSuggestion = useCallback(() => {
+    if (config.ai_suggested_time !== null) {
+      update({ frame_time: config.ai_suggested_time, mode: "frame" })
+    }
+  }, [config.ai_suggested_time, update])
+
+  const formatTime = (seconds: number) => {
+    const m = Math.floor(seconds / 60)
+    const s = Math.floor(seconds % 60)
+    const ms = Math.floor((seconds % 1) * 10)
+    return `${m.toString().padStart(2, "0")}:${s.toString().padStart(2, "0")}.${ms}`
+  }
+
+  return {
+    fileInputRef,
+    isDragging,
+    setIsDragging,
+    update,
+    handleReset,
+    handleModeChange,
+    handleFileUpload,
+    handleDrop,
+    handleUseAiSuggestion,
+    formatTime,
+  }
+}

apps/web/src/pages/editing-planner/components/editing-drawers/ClipLevelDrawers.tsx

@@ -0,0 +1,74 @@
+import React from "react"
+import { DEFAULT_TRANSITION, DEFAULT_SPEED, DEFAULT_TTS_CONFIG } from "../../types"
+import TransitionSelector from "../TransitionSelector"
+import SpeedPanel from "../SpeedPanel"
+import TtsPanel from "../TtsPanel"
+import type { ClipLevelDrawersProps } from "./types"
+
+/**
+ * 片段级抽屉（转场/调速/TTS）
+ * 这些抽屉针对特定片段，需要 targetClipId 来定位和读取当前配置
+ */
+export const ClipLevelDrawers: React.FC<ClipLevelDrawersProps> = ({
+  clips,
+  transitionDrawerOpen,
+  transitionTargetClipId,
+  onCloseTransitionDrawer,
+  onTransitionChange,
+  speedDrawerOpen,
+  speedTargetClipId,
+  onCloseSpeedDrawer,
+  onSpeedChange,
+  onApplySpeedAll,
+  ttsDrawerOpen,
+  ttsTargetClipId,
+  onCloseTtsDrawer,
+  onTtsChange,
+}) => {
+  const transitionConfig = transitionTargetClipId
+    ? (clips.find((c) => c.id === transitionTargetClipId)?.transition ?? DEFAULT_TRANSITION)
+    : DEFAULT_TRANSITION
+  const transitionTitle = transitionTargetClipId ? "片段转场设置" : "全局默认转场"
+
+  const speedConfig = speedTargetClipId
+    ? (clips.find((c) => c.id === speedTargetClipId)?.speed ?? DEFAULT_SPEED)
+    : DEFAULT_SPEED
+
+  const ttsConfig = ttsTargetClipId
+    ? (clips.find((c) => c.id === ttsTargetClipId)?.tts_config ?? DEFAULT_TTS_CONFIG)
+    : DEFAULT_TTS_CONFIG
+
+  return (
+    <>
+      {/* 转场特效选择器 */}
+      <TransitionSelector
+        open={transitionDrawerOpen}
+        onClose={onCloseTransitionDrawer}
+        config={transitionConfig}
+        onChange={onTransitionChange}
+        title={transitionTitle}
+      />
+
+      {/* 片段调速面板 */}
+      {speedTargetClipId && (
+        <SpeedPanel
+          open={speedDrawerOpen}
+          onClose={onCloseSpeedDrawer}
+          config={speedConfig}
+          onChange={onSpeedChange}
+          onApplyAll={onApplySpeedAll}
+        />
+      )}
+
+      {/* TTS 配音面板 */}
+      {ttsTargetClipId && (
+        <TtsPanel
+          open={ttsDrawerOpen}
+          onClose={onCloseTtsDrawer}
+          config={ttsConfig}
+          onChange={onTtsChange}
+        />
+      )}
+    </>
+  )
+}

apps/web/src/pages/editing-planner/components/editing-drawers/GlobalDrawers.tsx

@@ -0,0 +1,119 @@
+import React from "react"
+import BgmSelector from "../BgmSelector"
+import SubtitleStylePanel from "../SubtitleStylePanel"
+import WatermarkPanel from "../WatermarkPanel"
+import IntroOutroPanel from "../IntroOutroPanel"
+import PipConfigPanel from "../PipConfigPanel"
+import FilterPanel from "../FilterPanel"
+import GreenScreenPanel from "../GreenScreenPanel"
+import StickerPanel from "../StickerPanel"
+import type { GlobalDrawersProps, BgmDrawerProps, SubtitleDrawerProps } from "./types"
+
+/**
+ * 全局设置抽屉（BGM/字幕/水印/片头片尾/混剪/滤镜/绿幕/贴纸）
+ */
+export const GlobalDrawers: React.FC<BgmDrawerProps & SubtitleDrawerProps & GlobalDrawersProps> = ({
+  bgmDrawerOpen,
+  bgmSettings,
+  onCloseBgmDrawer,
+  onChangeBgmSettings,
+  subtitleDrawerOpen,
+  subtitleSettings,
+  onCloseSubtitleDrawer,
+  onChangeSubtitleSettings,
+  totalDuration,
+  watermarkDrawerOpen,
+  watermarkSettings,
+  onCloseWatermarkDrawer,
+  onWatermarkChange,
+  introOutroDrawerOpen,
+  introOutroSettings,
+  onCloseIntroOutroDrawer,
+  onIntroOutroChange,
+  pipDrawerOpen,
+  pipSettings,
+  onClosePipDrawer,
+  onPipChange,
+  filterDrawerOpen,
+  filterSettings,
+  onCloseFilterDrawer,
+  onFilterChange,
+  chromaKeyDrawerOpen,
+  chromaKeySettings,
+  onCloseChromaKeyDrawer,
+  onChromaKeyChange,
+  stickerDrawerOpen,
+  stickerSettings,
+  onCloseStickerDrawer,
+  onStickerChange,
+}) => {
+  return (
+    <>
+      {/* BGM 选择器 */}
+      <BgmSelector
+        open={bgmDrawerOpen}
+        onClose={onCloseBgmDrawer}
+        config={bgmSettings}
+        onChange={onChangeBgmSettings}
+      />
+
+      {/* 字幕样式配置 */}
+      <SubtitleStylePanel
+        open={subtitleDrawerOpen}
+        onClose={onCloseSubtitleDrawer}
+        config={subtitleSettings}
+        onChange={onChangeSubtitleSettings}
+      />
+
+      {/* 水印配置面板 */}
+      <WatermarkPanel
+        open={watermarkDrawerOpen}
+        onClose={onCloseWatermarkDrawer}
+        config={watermarkSettings}
+        onChange={onWatermarkChange}
+      />
+
+      {/* 片头片尾配置面板 */}
+      <IntroOutroPanel
+        open={introOutroDrawerOpen}
+        onClose={onCloseIntroOutroDrawer}
+        config={introOutroSettings}
+        onChange={onIntroOutroChange}
+      />
+
+      {/* 混剪配置面板 */}
+      <PipConfigPanel
+        open={pipDrawerOpen}
+        onClose={onClosePipDrawer}
+        config={pipSettings}
+        onChange={onPipChange}
+        totalDuration={totalDuration}
+      />
+
+      {/* 滤镜调色面板 */}
+      <FilterPanel
+        open={filterDrawerOpen}
+        onClose={onCloseFilterDrawer}
+        config={filterSettings}
+        onChange={onFilterChange}
+      />
+
+      {/* 绿幕抠像面板 */}
+      <GreenScreenPanel
+        open={chromaKeyDrawerOpen}
+        onClose={onCloseChromaKeyDrawer}
+        config={chromaKeySettings}
+        onChange={onChromaKeyChange}
+      />
+
+      {/* 贴纸面板 */}
+      <StickerPanel
+        open={stickerDrawerOpen}
+        onClose={onCloseStickerDrawer}
+        config={stickerSettings}
+        onChange={onStickerChange}
+        totalDuration={totalDuration}
+      />
+    </>
+  )
+}

apps/web/src/pages/editing-planner/components/editing-drawers/types.ts

@@ -0,0 +1,101 @@
+import type { TemplateCategory } from "@/api/editing-planner"
+import type {
+  ClipData,
+  TransitionConfig,
+  SpeedConfig,
+  TtsConfig,
+  WatermarkConfig,
+  IntroOutroConfig,
+  PipConfig,
+  FilterConfig,
+  ChromaKeyConfig,
+  StickerConfig,
+} from "../../types"
+import type { SubtitleStyleConfig } from "../../types/subtitle"
+import type { BgmMixConfig } from "@/api/bgm"
+
+/** 保存弹窗 Props */
+export interface SaveModalDrawerProps {
+  saveModalOpen: boolean
+  saveLoading: boolean
+  isUpdate: boolean
+  draftName: string
+  draftCategory: string
+  draftTags: string
+  categories: TemplateCategory[]
+  estimatedDuration: number
+  onNameChange: (name: string) => void
+  onCategoryChange: (cat: string) => void
+  onTagsChange: (tags: string) => void
+  onSave: () => Promise<void>
+  onCancelSave: () => void
+}
+
+/** BGM 抽屉 Props */
+export interface BgmDrawerProps {
+  bgmDrawerOpen: boolean
+  bgmSettings: BgmMixConfig
+  onCloseBgmDrawer: () => void
+  onChangeBgmSettings: (config: BgmMixConfig) => void
+}
+
+/** 字幕抽屉 Props */
+export interface SubtitleDrawerProps {
+  subtitleDrawerOpen: boolean
+  subtitleSettings: SubtitleStyleConfig
+  onCloseSubtitleDrawer: () => void
+  onChangeSubtitleSettings: (config: SubtitleStyleConfig) => void
+}
+
+/** 单个片段级抽屉通用 Props */
+export interface ClipLevelDrawersProps {
+  clips: ClipData[]
+  transitionDrawerOpen: boolean
+  transitionTargetClipId: string | null
+  onCloseTransitionDrawer: () => void
+  onTransitionChange: (config: TransitionConfig) => void
+  speedDrawerOpen: boolean
+  speedTargetClipId: string | null
+  onCloseSpeedDrawer: () => void
+  onSpeedChange: (config: SpeedConfig) => void
+  onApplySpeedAll: (config: SpeedConfig) => void
+  ttsDrawerOpen: boolean
+  ttsTargetClipId: string | null
+  onCloseTtsDrawer: () => void
+  onTtsChange: (config: TtsConfig) => void
+}
+
+/** 全局设置抽屉 Props */
+export interface GlobalDrawersProps {
+  totalDuration: number
+  watermarkDrawerOpen: boolean
+  watermarkSettings: WatermarkConfig
+  onCloseWatermarkDrawer: () => void
+  onWatermarkChange: (config: WatermarkConfig) => void
+  introOutroDrawerOpen: boolean
+  introOutroSettings: IntroOutroConfig
+  onCloseIntroOutroDrawer: () => void
+  onIntroOutroChange: (config: IntroOutroConfig) => void
+  pipDrawerOpen: boolean
+  pipSettings: PipConfig
+  onClosePipDrawer: () => void
+  onPipChange: (config: PipConfig) => void
+  filterDrawerOpen: boolean
+  filterSettings: FilterConfig
+  onCloseFilterDrawer: () => void
+  onFilterChange: (config: FilterConfig) => void
+  chromaKeyDrawerOpen: boolean
+  chromaKeySettings: ChromaKeyConfig
+  onCloseChromaKeyDrawer: () => void
+  onChromaKeyChange: (config: ChromaKeyConfig) => void
+  stickerDrawerOpen: boolean
+  stickerSettings: StickerConfig
+  onCloseStickerDrawer: () => void
+  onStickerChange: (config: StickerConfig) => void
+}
+
+export type EditingDrawersProps = SaveModalDrawerProps &
+  BgmDrawerProps &
+  SubtitleDrawerProps &
+  ClipLevelDrawersProps &
+  GlobalDrawersProps

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

@@ -1,281 +1,5 @@
 /**
- * 混剪单图层配置区
+ * LayerConfig 入口（向后兼容）
+ * 实际实现位于 ./layer-config/ 目录
  */
-import React from "react"
-import type { PipLayer, PipAnimType, PipSlideDirection, PipGridPosition } from "@/pages/editing-planner/types"
-import {
-  GRID_POSITIONS,
-  ANIM_OPTIONS,
-  SLIDE_DIR_OPTIONS,
-  LAYER_COLORS,
-} from "@/pages/editing-planner/constants/pipConfig"
-
-interface LayerConfigProps {
-  layer: PipLayer | null
-  layers: PipLayer[]
-  totalDuration: number
-  onUpdate: (id: string, partial: Partial<PipLayer>) => void
-  onGridClick: (pos: PipGridPosition) => void
-  onWidthChange: (val: number) => void
-  onHeightChange: (val: number) => void
-}
-
-const LayerConfig: React.FC<LayerConfigProps> = ({
-  layer,
-  layers,
-  totalDuration,
-  onUpdate,
-  onGridClick,
-  onWidthChange,
-  onHeightChange,
-}) => {
-  if (!layer) {
-    return (
-      <div className="pip-config-area">
-        <div className="pip-config-empty">选择或添加图层以配置</div>
-      </div>
-    )
-  }
-
-  return (
-    <div className="pip-config-area">
-      {/* ── 迷你预览 ── */}
-      <div className="pip-preview-box">
-        {layers.map((l, idx) => (
-          <div
-            key={l.id}
-            className={`pip-preview-layer${layer.id === l.id ? " selected" : ""}`}
-            style={{
-              left: `${l.x}%`,
-              top: `${l.y}%`,
-              width: `${l.width}%`,
-              height: `${l.height}%`,
-              background: LAYER_COLORS[idx % LAYER_COLORS.length],
-              opacity: l.opacity / 100,
-              borderRadius: `${l.border_radius}%`,
-            }}
-          >
-            <span className="pip-preview-label">{l.name}</span>
-          </div>
-        ))}
-      </div>
-
-      {/* ── 素材类型 ── */}
-      <div className="pip-field">
-        <label className="pip-field-label">素材类型</label>
-        <div className="pip-type-btns">
-          <button
-            className={`pip-type-btn${layer.material_type === "image" ? " active" : ""}`}
-            onClick={() => onUpdate(layer.id, { material_type: "image" })}
-          >
-            🖼️ 图片
-          </button>
-          <button
-            className={`pip-type-btn${layer.material_type === "video" ? " active" : ""}`}
-            onClick={() => onUpdate(layer.id, { material_type: "video" })}
-          >
-            🎬 视频
-          </button>
-        </div>
-      </div>
-
-      {/* ── 素材 URL ── */}
-      <div className="pip-field">
-        <label className="pip-field-label">
-          {layer.material_type === "image" ? "图片" : "视频"} URL
-        </label>
-        <input
-          className="pip-input"
-          type="text"
-          placeholder={
-            layer.material_type === "image"
-              ? "https://example.com/image.png"
-              : "https://example.com/video.mp4"
-          }
-          value={layer.material_url}
-          onChange={(e) => onUpdate(layer.id, { material_url: e.target.value })}
-        />
-      </div>
-
-      {/* ── 位置：九宫格 + 坐标 ── */}
-      <div className="pip-field">
-        <label className="pip-field-label">位置</label>
-        <div style={{ display: "flex", gap: 16, alignItems: "flex-start" }}>
-          <div className="pip-grid">
-            {GRID_POSITIONS.map((pos) => (
-              <button
-                key={pos}
-                className={`pip-grid-btn${layer.grid_position === pos ? " active" : ""}`}
-                onClick={() => onGridClick(pos)}
-              >
-                <span className="pip-grid-dot" />
-              </button>
-            ))}
-          </div>
-          <div className="pip-field-row" style={{ flex: 1 }}>
-            <div>
-              <label className="pip-field-label">X (%)</label>
-              <input
-                className="pip-number"
-                type="number"
-                min={0}
-                max={100}
-                value={layer.x}
-                onChange={(e) => onUpdate(layer.id, { x: Number(e.target.value) })}
-              />
-            </div>
-            <div>
-              <label className="pip-field-label">Y (%)</label>
-              <input
-                className="pip-number"
-                type="number"
-                min={0}
-                max={100}
-                value={layer.y}
-                onChange={(e) => onUpdate(layer.id, { y: Number(e.target.value) })}
-              />
-            </div>
-          </div>
-        </div>
-      </div>
-
-      {/* ── 尺寸 ── */}
-      <div className="pip-field">
-        <label className="pip-field-label">尺寸</label>
-        <div className="pip-slider-row">
-          <span style={{ fontSize: 12, color: "#999", width: 20 }}>宽</span>
-          <input
-            className="pip-slider"
-            type="range"
-            min={10}
-            max={80}
-            value={layer.width}
-            onChange={(e) => onWidthChange(Number(e.target.value))}
-          />
-          <span className="pip-slider-value">{layer.width}%</span>
-        </div>
-        <div className="pip-slider-row" style={{ marginTop: 6 }}>
-          <span style={{ fontSize: 12, color: "#999", width: 20 }}>高</span>
-          <input
-            className="pip-slider"
-            type="range"
-            min={10}
-            max={80}
-            value={layer.height}
-            onChange={(e) => onHeightChange(Number(e.target.value))}
-          />
-          <span className="pip-slider-value">{layer.height}%</span>
-        </div>
-        <div
-          className="pip-lock-row"
-          style={{ marginTop: 6 }}
-          onClick={() => onUpdate(layer.id, { aspect_lock: !layer.aspect_lock })}
-        >
-          <span className="pip-lock-icon">{layer.aspect_lock ? "🔒" : "🔓"}</span>
-          <span>{layer.aspect_lock ? "已锁定比例" : "锁定宽高比"}</span>
-        </div>
-      </div>
-
-      {/* ── 圆角 ── */}
-      <div className="pip-field">
-        <label className="pip-field-label">圆角</label>
-        <div className="pip-slider-row">
-          <input
-            className="pip-slider"
-            type="range"
-            min={0}
-            max={50}
-            value={layer.border_radius}
-            onChange={(e) => onUpdate(layer.id, { border_radius: Number(e.target.value) })}
-          />
-          <span className="pip-slider-value">{layer.border_radius}%</span>
-        </div>
-      </div>
-
-      {/* ── 透明度 ── */}
-      <div className="pip-field">
-        <label className="pip-field-label">透明度</label>
-        <div className="pip-slider-row">
-          <input
-            className="pip-slider"
-            type="range"
-            min={0}
-            max={100}
-            value={layer.opacity}
-            onChange={(e) => onUpdate(layer.id, { opacity: Number(e.target.value) })}
-          />
-          <span className="pip-slider-value">{layer.opacity}%</span>
-        </div>
-      </div>
-
-      {/* ── 时间 ── */}
-      <div className="pip-field">
-        <label className="pip-field-label">时间</label>
-        <div className="pip-field-row">
-          <div>
-            <label className="pip-field-label">开始 (s)</label>
-            <input
-              className="pip-number"
-              type="number"
-              min={0}
-              max={totalDuration || 999}
-              step={0.1}
-              value={layer.start_time}
-              onChange={(e) => onUpdate(layer.id, { start_time: Number(e.target.value) })}
-            />
-          </div>
-          <div>
-            <label className="pip-field-label">持续 (s)</label>
-            <input
-              className="pip-number"
-              type="number"
-              min={0.1}
-              max={totalDuration || 999}
-              step={0.1}
-              value={layer.duration}
-              onChange={(e) => onUpdate(layer.id, { duration: Number(e.target.value) })}
-            />
-          </div>
-        </div>
-      </div>
-
-      {/* ── 入场动画 ── */}
-      <div className="pip-field">
-        <label className="pip-field-label">入场动画</label>
-        <select
-          className="pip-select"
-          value={layer.animation}
-          onChange={(e) => onUpdate(layer.id, { animation: e.target.value as PipAnimType })}
-        >
-          {ANIM_OPTIONS.map((opt) => (
-            <option key={opt.value} value={opt.value}>
-              {opt.label}
-            </option>
-          ))}
-        </select>
-      </div>
-
-      {/* 滑入方向（仅 slide_in 时显示） */}
-      {layer.animation === "slide_in" && (
-        <div className="pip-field">
-          <label className="pip-field-label">滑入方向</label>
-          <select
-            className="pip-select"
-            value={layer.slide_direction}
-            onChange={(e) =>
-              onUpdate(layer.id, { slide_direction: e.target.value as PipSlideDirection })
-            }
-          >
-            {SLIDE_DIR_OPTIONS.map((opt) => (
-              <option key={opt.value} value={opt.value}>
-                {opt.label}
-              </option>
-            ))}
-          </select>
-        </div>
-      )}
-    </div>
-  )
-}
-
-export default LayerConfig
+export { default } from "./layer-config"

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

@@ -0,0 +1,172 @@
+import React from "react"
+import type { PipLayer, PipGridPosition } from "@/pages/editing-planner/types"
+import { GRID_POSITIONS } from "@/pages/editing-planner/constants/pipConfig"
+
+interface LayerPositionSizeProps {
+  layer: PipLayer
+  onUpdate: (id: string, partial: Partial<PipLayer>) => void
+  onGridClick: (pos: PipGridPosition) => void
+  onWidthChange: (val: number) => void
+  onHeightChange: (val: number) => void
+}
+
+/**
+ * 图层位置与尺寸配置面板
+ */
+export const LayerPositionSize: React.FC<LayerPositionSizeProps> = ({
+  layer,
+  onUpdate,
+  onGridClick,
+  onWidthChange,
+  onHeightChange,
+}) => (
+  <>
+    {/* 素材类型 */}
+    <div className="pip-field">
+      <label className="pip-field-label">素材类型</label>
+      <div className="pip-type-btns">
+        <button
+          className={`pip-type-btn${layer.material_type === "image" ? " active" : ""}`}
+          onClick={() => onUpdate(layer.id, { material_type: "image" })}
+        >
+          🖼️ 图片
+        </button>
+        <button
+          className={`pip-type-btn${layer.material_type === "video" ? " active" : ""}`}
+          onClick={() => onUpdate(layer.id, { material_type: "video" })}
+        >
+          🎬 视频
+        </button>
+      </div>
+    </div>
+
+    {/* 素材 URL */}
+    <div className="pip-field">
+      <label className="pip-field-label">
+        {layer.material_type === "image" ? "图片" : "视频"} URL
+      </label>
+      <input
+        className="pip-input"
+        type="text"
+        placeholder={
+          layer.material_type === "image"
+            ? "https://example.com/image.png"
+            : "https://example.com/video.mp4"
+        }
+        value={layer.material_url}
+        onChange={(e) => onUpdate(layer.id, { material_url: e.target.value })}
+      />
+    </div>
+
+    {/* 位置：九宫格 + 坐标 */}
+    <div className="pip-field">
+      <label className="pip-field-label">位置</label>
+      <div style={{ display: "flex", gap: 16, alignItems: "flex-start" }}>
+        <div className="pip-grid">
+          {GRID_POSITIONS.map((pos) => (
+            <button
+              key={pos}
+              className={`pip-grid-btn${layer.grid_position === pos ? " active" : ""}`}
+              onClick={() => onGridClick(pos)}
+            >
+              <span className="pip-grid-dot" />
+            </button>
+          ))}
+        </div>
+        <div className="pip-field-row" style={{ flex: 1 }}>
+          <div>
+            <label className="pip-field-label">X (%)</label>
+            <input
+              className="pip-number"
+              type="number"
+              min={0}
+              max={100}
+              value={layer.x}
+              onChange={(e) => onUpdate(layer.id, { x: Number(e.target.value) })}
+            />
+          </div>
+          <div>
+            <label className="pip-field-label">Y (%)</label>
+            <input
+              className="pip-number"
+              type="number"
+              min={0}
+              max={100}
+              value={layer.y}
+              onChange={(e) => onUpdate(layer.id, { y: Number(e.target.value) })}
+            />
+          </div>
+        </div>
+      </div>
+    </div>
+
+    {/* 尺寸 */}
+    <div className="pip-field">
+      <label className="pip-field-label">尺寸</label>
+      <div className="pip-slider-row">
+        <span style={{ fontSize: 12, color: "#999", width: 20 }}>宽</span>
+        <input
+          className="pip-slider"
+          type="range"
+          min={10}
+          max={80}
+          value={layer.width}
+          onChange={(e) => onWidthChange(Number(e.target.value))}
+        />
+        <span className="pip-slider-value">{layer.width}%</span>
+      </div>
+      <div className="pip-slider-row" style={{ marginTop: 6 }}>
+        <span style={{ fontSize: 12, color: "#999", width: 20 }}>高</span>
+        <input
+          className="pip-slider"
+          type="range"
+          min={10}
+          max={80}
+          value={layer.height}
+          onChange={(e) => onHeightChange(Number(e.target.value))}
+        />
+        <span className="pip-slider-value">{layer.height}%</span>
+      </div>
+      <div
+        className="pip-lock-row"
+        style={{ marginTop: 6 }}
+        onClick={() => onUpdate(layer.id, { aspect_lock: !layer.aspect_lock })}
+      >
+        <span className="pip-lock-icon">{layer.aspect_lock ? "🔒" : "🔓"}</span>
+        <span>{layer.aspect_lock ? "已锁定比例" : "锁定宽高比"}</span>
+      </div>
+    </div>
+
+    {/* 圆角 */}
+    <div className="pip-field">
+      <label className="pip-field-label">圆角</label>
+      <div className="pip-slider-row">
+        <input
+          className="pip-slider"
+          type="range"
+          min={0}
+          max={50}
+          value={layer.border_radius}
+          onChange={(e) => onUpdate(layer.id, { border_radius: Number(e.target.value) })}
+        />
+        <span className="pip-slider-value">{layer.border_radius}%</span>
+      </div>
+    </div>
+
+    {/* 透明度 */}
+    <div className="pip-field">
+      <label className="pip-field-label">透明度</label>
+      <div className="pip-slider-row">
+        <input
+          className="pip-slider"
+          type="range"
+          min={0}
+          max={100}
+          value={layer.opacity}
+          onChange={(e) => onUpdate(layer.id, { opacity: Number(e.target.value) })}
+        />
+        <span className="pip-slider-value">{layer.opacity}%</span>
+      </div>
+    </div>
+  </>
+)

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

@@ -0,0 +1,87 @@
+import React from "react"
+import type { PipLayer, PipAnimType, PipSlideDirection } from "@/pages/editing-planner/types"
+import { ANIM_OPTIONS, SLIDE_DIR_OPTIONS } from "@/pages/editing-planner/constants/pipConfig"
+
+interface LayerTimingAnimationProps {
+  layer: PipLayer
+  totalDuration: number
+  onUpdate: (id: string, partial: Partial<PipLayer>) => void
+}
+
+/**
+ * 图层时间与动画配置面板
+ */
+export const LayerTimingAnimation: React.FC<LayerTimingAnimationProps> = ({
+  layer,
+  totalDuration,
+  onUpdate,
+}) => (
+  <>
+    {/* 时间 */}
+    <div className="pip-field">
+      <label className="pip-field-label">时间</label>
+      <div className="pip-field-row">
+        <div>
+          <label className="pip-field-label">开始 (s)</label>
+          <input
+            className="pip-number"
+            type="number"
+            min={0}
+            max={totalDuration || 999}
+            step={0.1}
+            value={layer.start_time}
+            onChange={(e) => onUpdate(layer.id, { start_time: Number(e.target.value) })}
+          />
+        </div>
+        <div>
+          <label className="pip-field-label">持续 (s)</label>
+          <input
+            className="pip-number"
+            type="number"
+            min={0.1}
+            max={totalDuration || 999}
+            step={0.1}
+            value={layer.duration}
+            onChange={(e) => onUpdate(layer.id, { duration: Number(e.target.value) })}
+          />
+        </div>
+      </div>
+    </div>
+
+    {/* 入场动画 */}
+    <div className="pip-field">
+      <label className="pip-field-label">入场动画</label>
+      <select
+        className="pip-select"
+        value={layer.animation}
+        onChange={(e) => onUpdate(layer.id, { animation: e.target.value as PipAnimType })}
+      >
+        {ANIM_OPTIONS.map((opt) => (
+          <option key={opt.value} value={opt.value}>
+            {opt.label}
+          </option>
+        ))}
+      </select>
+    </div>
+
+    {/* 滑入方向（仅 slide_in 时显示） */}
+    {layer.animation === "slide_in" && (
+      <div className="pip-field">
+        <label className="pip-field-label">滑入方向</label>
+        <select
+          className="pip-select"
+          value={layer.slide_direction}
+          onChange={(e) =>
+            onUpdate(layer.id, { slide_direction: e.target.value as PipSlideDirection })
+          }
+        >
+          {SLIDE_DIR_OPTIONS.map((opt) => (
+            <option key={opt.value} value={opt.value}>
+              {opt.label}
+            </option>
+          ))}
+        </select>
+      </div>
+    )}
+  </>
+)

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

@@ -0,0 +1,33 @@
+import React from "react"
+import type { PipLayer } from "@/pages/editing-planner/types"
+import { LAYER_COLORS } from "@/pages/editing-planner/constants/pipConfig"
+
+interface PipPreviewProps {
+  layers: PipLayer[]
+  selectedId: string
+}
+
+/**
+ * PIP 图层迷你预览组件
+ */
+export const PipPreview: React.FC<PipPreviewProps> = ({ layers, selectedId }) => (
+  <div className="pip-preview-box">
+    {layers.map((l, idx) => (
+      <div
+        key={l.id}
+        className={`pip-preview-layer${selectedId === l.id ? " selected" : ""}`}
+        style={{
+          left: `${l.x}%`,
+          top: `${l.y}%`,
+          width: `${l.width}%`,
+          height: `${l.height}%`,
+          background: LAYER_COLORS[idx % LAYER_COLORS.length],
+          opacity: l.opacity / 100,
+          borderRadius: `${l.border_radius}%`,
+        }}
+      >
+        <span className="pip-preview-label">{l.name}</span>
+      </div>
+    ))}
+  </div>
+)

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

@@ -0,0 +1,57 @@
+/**
+ * 混剪单图层配置区
+ */
+import React from "react"
+import type { PipLayer, PipGridPosition } from "@/pages/editing-planner/types"
+import { PipPreview } from "./PipPreview"
+import { LayerPositionSize } from "./LayerPositionSize"
+import { LayerTimingAnimation } from "./LayerTimingAnimation"
+
+interface LayerConfigProps {
+  layer: PipLayer | null
+  layers: PipLayer[]
+  totalDuration: number
+  onUpdate: (id: string, partial: Partial<PipLayer>) => void
+  onGridClick: (pos: PipGridPosition) => void
+  onWidthChange: (val: number) => void
+  onHeightChange: (val: number) => void
+}
+
+const LayerConfig: React.FC<LayerConfigProps> = ({
+  layer,
+  layers,
+  totalDuration,
+  onUpdate,
+  onGridClick,
+  onWidthChange,
+  onHeightChange,
+}) => {
+  if (!layer) {
+    return (
+      <div className="pip-config-area">
+        <div className="pip-config-empty">选择或添加图层以配置</div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="pip-config-area">
+      {/* 迷你预览 */}
+      <PipPreview layers={layers} selectedId={layer.id} />
+
+      {/* 位置与尺寸 */}
+      <LayerPositionSize
+        layer={layer}
+        onUpdate={onUpdate}
+        onGridClick={onGridClick}
+        onWidthChange={onWidthChange}
+        onHeightChange={onHeightChange}
+      />
+
+      {/* 时间与动画 */}
+      <LayerTimingAnimation layer={layer} totalDuration={totalDuration} onUpdate={onUpdate} />
+    </div>
+  )
+}
+
+export default LayerConfig

apps/web/src/pages/editing-planner/hooks/useEditPlanClips/index.ts

@@ -0,0 +1,83 @@
+import { useUndoRedo } from "../useUndoRedo"
+import type { EditPlanClip } from "@/api/template-editor"
+import { useEditPlanClipList } from "./useEditPlanClipList"
+import { useEditPlanClipMutations } from "./useEditPlanClipMutations"
+
+/**
+ * 模板片段管理 Hook
+ * 对接后端 PR#389 片段 CRUD API
+ *
+ * 功能：
+ * - 加载/刷新片段列表
+ * - 单个增删改查
+ * - 批量删除
+ * - 拖拽重排序
+ * - 从素材批量导入
+ * - 乐观更新 + 撤销重做
+ */
+export function useEditPlanClips(planId: string | undefined) {
+  // 列表数据 + 选中状态
+  const {
+    clips,
+    clipsTotal,
+    clipsLoading,
+    refetchClips,
+    selectedClipId,
+    setSelectedClipId,
+    selectedClip,
+  } = useEditPlanClipList(planId)
+
+  // CRUD 操作
+  const mutations = useEditPlanClipMutations({
+    planId,
+    selectedClipId,
+    setSelectedClipId,
+    clipsLength: clips.length,
+  })
+
+  // 本地撤销重做（供拖拽等即时操作使用）
+  const {
+    state: localClips,
+    set: setLocalClips,
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+    reset: resetLocalClips,
+  } = useUndoRedo<EditPlanClip[]>([])
+
+  return {
+    // 数据
+    clips,
+    clipsTotal,
+    clipsLoading,
+    selectedClipId,
+    selectedClip,
+    // 选中
+    setSelectedClipId,
+    // 操作
+    addClip: mutations.addClip,
+    updateClip: mutations.updateClip,
+    removeClip: mutations.removeClip,
+    batchRemoveClips: mutations.batchRemoveClips,
+    reorderClips: mutations.reorderClips,
+    importFromAssets: mutations.importFromAssets,
+    refetchClips,
+    // 状态
+    isCreating: mutations.isCreating,
+    isUpdating: mutations.isUpdating,
+    isDeleting: mutations.isDeleting,
+    isReordering: mutations.isReordering,
+    isImporting: mutations.isImporting,
+    // 本地撤销重做
+    localClips,
+    setLocalClips,
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+    resetLocalClips,
+  }
+}
+
+export default useEditPlanClips

apps/web/src/pages/editing-planner/hooks/useEditPlanClips/useEditPlanClipList.ts

@@ -0,0 +1,49 @@
+import { useState } from "react"
+import { useQuery } from "@tanstack/react-query"
+import type { EditPlanClip } from "@/api/template-editor"
+import { getEditPlanClips } from "@/api/template-editor"
+
+const QUERY_KEY = "editPlanClips"
+
+interface UseEditPlanClipListResult {
+  clips: EditPlanClip[]
+  clipsTotal: number
+  clipsLoading: boolean
+  refetchClips: () => void
+  selectedClipId: string | null
+  setSelectedClipId: (id: string | null) => void
+  selectedClip: EditPlanClip | null
+}
+
+/**
+ * 编辑计划片段列表 Hook
+ * 封装片段列表查询、选中状态
+ */
+export function useEditPlanClipList(planId: string | undefined): UseEditPlanClipListResult {
+  const {
+    data: clipListData,
+    isLoading: clipsLoading,
+    refetch: refetchClips,
+  } = useQuery({
+    queryKey: [QUERY_KEY, planId],
+    queryFn: () => getEditPlanClips(planId!, { limit: 500 }),
+    enabled: !!planId,
+    staleTime: 30_000,
+  })
+
+  const clips: EditPlanClip[] = clipListData?.items ?? []
+  const clipsTotal = clipListData?.total ?? 0
+
+  const [selectedClipId, setSelectedClipId] = useState<string | null>(null)
+  const selectedClip = clips.find((c) => c.id === selectedClipId) ?? null
+
+  return {
+    clips,
+    clipsTotal,
+    clipsLoading,
+    refetchClips,
+    selectedClipId,
+    setSelectedClipId,
+    selectedClip,
+  }
+}

apps/web/src/pages/editing-planner/hooks/useEditPlanClips/useEditPlanClipMutations.ts

@@ -1,26 +1,12 @@
-/**
- * 模板片段管理 Hook
- * 对接后端 PR#389 片段 CRUD API，替代原来的 config.segments 模式
- *
- * 功能：
- * - 加载/刷新片段列表
- * - 单个增删改查
- * - 批量删除
- * - 拖拽重排序
- * - 从素材批量导入
- * - 乐观更新 + 撤销重做
- */
-import { useCallback, useState } from "react"
+import { useCallback } from "react"
 import { message } from "antd"
-import { useQuery, useQueryClient, useMutation } from "@tanstack/react-query"
+import { useQueryClient, useMutation } from "@tanstack/react-query"
 import type {
-  EditPlanClip,
   CreateEditPlanClipRequest,
   UpdateEditPlanClipRequest,
   ClipReorderItem,
 } from "@/api/template-editor"
 import {
-  getEditPlanClips,
   createEditPlanClip,
   updateEditPlanClip,
   deleteEditPlanClip,
@@ -28,51 +14,37 @@ import {
   batchDeleteEditPlanClips,
   createClipsFromAssets,
 } from "@/api/template-editor"
-import { useUndoRedo } from "./useUndoRedo"
 
 const QUERY_KEY = "editPlanClips"
 
-export function useEditPlanClips(planId: string | undefined) {
+interface UseEditPlanClipMutationsOptions {
+  planId: string | undefined
+  selectedClipId: string | null
+  setSelectedClipId: (id: string | null) => void
+  clipsLength: number
+}
+
+/**
+ * 编辑计划片段 CRUD Hook
+ * 封装创建、更新、删除、批量删除、重排序、素材导入等操作
+ */
+export function useEditPlanClipMutations({
+  planId,
+  selectedClipId,
+  setSelectedClipId,
+  clipsLength,
+}: UseEditPlanClipMutationsOptions) {
   const queryClient = useQueryClient()
 
-  /* ── 片段列表查询 ── */
-  const {
-    data: clipListData,
-    isLoading: clipsLoading,
-    refetch: refetchClips,
-  } = useQuery({
-    queryKey: [QUERY_KEY, planId],
-    queryFn: () => getEditPlanClips(planId!, { limit: 500 }),
-    enabled: !!planId,
-    staleTime: 30_000,
-  })
-
-  const clips: EditPlanClip[] = clipListData?.items ?? []
-  const clipsTotal = clipListData?.total ?? 0
-
-  /* ── 选中片段 ── */
-  const [selectedClipId, setSelectedClipId] = useState<string | null>(null)
-  const selectedClip = clips.find((c) => c.id === selectedClipId) ?? null
-
-  /* ── 本地撤销/重做（用于拖拽等即时操作的回退） ── */
-  const {
-    state: localClips,
-    set: setLocalClips,
-    undo,
-    redo,
-    canUndo,
-    canRedo,
-    reset: resetLocalClips,
-  } = useUndoRedo<EditPlanClip[]>([])
-
-  // 当服务端数据变化时同步本地
-  // 注意：实际使用时以服务端为准，本地仅用于拖拽等临时操作
+  const invalidate = () => {
+    queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] })
+  }
 
   /* ── 创建片段 ── */
   const createMutation = useMutation({
     mutationFn: (data: CreateEditPlanClipRequest) => createEditPlanClip(planId!, data),
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] })
+      invalidate()
       message.success("片段已添加")
     },
     onError: () => {
@@ -83,10 +55,10 @@ export function useEditPlanClips(planId: string | undefined) {
   const addClip = useCallback(
     (data: Omit<CreateEditPlanClipRequest, "order"> & { order?: number }) => {
       if (!planId) return
-      const order = data.order ?? clips.length
+      const order = data.order ?? clipsLength
       createMutation.mutate({ ...data, order })
     },
-    [planId, clips.length, createMutation],
+    [planId, clipsLength, createMutation],
   )
 
   /* ── 更新片段 ── */
@@ -94,7 +66,7 @@ export function useEditPlanClips(planId: string | undefined) {
     mutationFn: ({ clipId, data }: { clipId: string; data: UpdateEditPlanClipRequest }) =>
       updateEditPlanClip(planId!, clipId, data),
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] })
+      invalidate()
     },
     onError: () => {
       message.error("更新片段失败")
@@ -113,7 +85,7 @@ export function useEditPlanClips(planId: string | undefined) {
   const deleteMutation = useMutation({
     mutationFn: (clipId: string) => deleteEditPlanClip(planId!, clipId),
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] })
+      invalidate()
       message.success("片段已删除")
     },
     onError: () => {
@@ -129,14 +101,14 @@ export function useEditPlanClips(planId: string | undefined) {
       }
       deleteMutation.mutate(clipId)
     },
-    [planId, selectedClipId, deleteMutation],
+    [planId, selectedClipId, setSelectedClipId, deleteMutation],
   )
 
   /* ── 批量删除 ── */
   const batchDeleteMutation = useMutation({
     mutationFn: (clipIds: string[]) => batchDeleteEditPlanClips(planId!, clipIds),
     onSuccess: (res) => {
-      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] })
+      invalidate()
       message.success(`已删除 ${res.deleted_count} 个片段`)
     },
     onError: () => {
@@ -152,19 +124,18 @@ export function useEditPlanClips(planId: string | undefined) {
       }
       batchDeleteMutation.mutate(clipIds)
     },
-    [planId, selectedClipId, batchDeleteMutation],
+    [planId, selectedClipId, setSelectedClipId, batchDeleteMutation],
   )
 
-  /* ── 重排序（拖拽结束后一次性提交） ── */
+  /* ── 重排序 ── */
   const reorderMutation = useMutation({
     mutationFn: (items: ClipReorderItem[]) => reorderEditPlanClips(planId!, items),
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] })
+      invalidate()
     },
     onError: () => {
       message.error("排序失败")
-      // 失败后刷新回服务端状态
-      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] })
+      invalidate()
     },
   })
 
@@ -180,7 +151,7 @@ export function useEditPlanClips(planId: string | undefined) {
   const importFromAssetsMutation = useMutation({
     mutationFn: (assetIds: string[]) => createClipsFromAssets(planId!, assetIds),
     onSuccess: (res) => {
-      queryClient.invalidateQueries({ queryKey: [QUERY_KEY, planId] })
+      invalidate()
       message.success(`已导入 ${res.created_count} 个素材片段`)
     },
     onError: () => {
@@ -197,37 +168,16 @@ export function useEditPlanClips(planId: string | undefined) {
   )
 
   return {
-    // 数据
-    clips,
-    clipsTotal,
-    clipsLoading,
-    selectedClipId,
-    selectedClip,
-    // 选中
-    setSelectedClipId,
-    // 操作
     addClip,
     updateClip,
     removeClip,
     batchRemoveClips,
     reorderClips,
     importFromAssets,
-    refetchClips,
-    // 状态
     isCreating: createMutation.isPending,
     isUpdating: updateMutation.isPending,
     isDeleting: deleteMutation.isPending,
     isReordering: reorderMutation.isPending,
     isImporting: importFromAssetsMutation.isPending,
-    // 本地撤销重做（供拖拽等场景使用）
-    localClips,
-    setLocalClips,
-    undo,
-    redo,
-    canUndo,
-    canRedo,
-    resetLocalClips,
   }
 }
-
-export default useEditPlanClips

apps/web/src/pages/editing-planner/hooks/useGlobalSettings.ts

@@ -0,0 +1,121 @@
+/**
+ * EditingPlanner 全局配置状态管理
+ * 集中管理 9 个全局配置：标题/字幕/BGM/水印/片头片尾/画中画/滤镜/绿幕/贴纸/封面
+ */
+import { useState } from "react"
+import type { TitleConfig } from "@/api/template-editor"
+import type {
+  WatermarkConfig,
+  IntroOutroConfig,
+  PipConfig,
+  FilterConfig,
+  ChromaKeyConfig,
+  StickerConfig,
+  CoverConfig,
+} from "../types"
+import {
+  DEFAULT_WATERMARK,
+  DEFAULT_INTRO_OUTRO,
+  DEFAULT_PIP_CONFIG,
+  DEFAULT_FILTER_CONFIG,
+  DEFAULT_CHROMA_KEY_CONFIG,
+  DEFAULT_STICKER_CONFIG,
+  DEFAULT_COVER_CONFIG,
+} from "../types"
+import type { SubtitleStyleConfig } from "../types/subtitle"
+import { DEFAULT_SUBTITLE_STYLE } from "../types/subtitle"
+import { DEFAULT_BGM_MIX_CONFIG, type BgmMixConfig } from "@/api/bgm"
+
+export interface GlobalSettings {
+  titleConfig: TitleConfig
+  setTitleConfig: (config: TitleConfig | ((prev: TitleConfig) => TitleConfig)) => void
+  subtitleSettings: SubtitleStyleConfig
+  setSubtitleSettings: (
+    settings: SubtitleStyleConfig | ((prev: SubtitleStyleConfig) => SubtitleStyleConfig),
+  ) => void
+  bgmSettings: BgmMixConfig
+  setBgmSettings: (settings: BgmMixConfig | ((prev: BgmMixConfig) => BgmMixConfig)) => void
+  watermarkSettings: WatermarkConfig
+  setWatermarkSettings: (config: WatermarkConfig) => void
+  introOutroSettings: IntroOutroConfig
+  setIntroOutroSettings: (config: IntroOutroConfig) => void
+  pipSettings: PipConfig
+  setPipSettings: (config: PipConfig) => void
+  filterSettings: FilterConfig
+  setFilterSettings: (config: FilterConfig) => void
+  chromaKeySettings: ChromaKeyConfig
+  setChromaKeySettings: (config: ChromaKeyConfig) => void
+  stickerSettings: StickerConfig
+  setStickerSettings: (config: StickerConfig) => void
+  coverConfig: CoverConfig
+  setCoverConfig: (config: CoverConfig | ((prev: CoverConfig) => CoverConfig)) => void
+}
+
+export const useGlobalSettings = (): GlobalSettings => {
+  const [titleConfig, setTitleConfig] = useState<TitleConfig>({
+    ai_auto_select: false,
+    content: "",
+    position: "bottom",
+    font_preset: "思源黑体",
+    font_size: 28,
+    font_color: "#ffffff",
+  })
+
+  const [subtitleSettings, setSubtitleSettings] = useState<SubtitleStyleConfig>({
+    ...DEFAULT_SUBTITLE_STYLE,
+  })
+
+  const [bgmSettings, setBgmSettings] = useState<BgmMixConfig>({
+    ...DEFAULT_BGM_MIX_CONFIG,
+  })
+
+  const [watermarkSettings, setWatermarkSettings] = useState<WatermarkConfig>({
+    ...DEFAULT_WATERMARK,
+  })
+  const [introOutroSettings, setIntroOutroSettings] = useState<IntroOutroConfig>({
+    ...DEFAULT_INTRO_OUTRO,
+  })
+
+  const [pipSettings, setPipSettings] = useState<PipConfig>({
+    ...DEFAULT_PIP_CONFIG,
+  })
+
+  const [filterSettings, setFilterSettings] = useState<FilterConfig>({
+    ...DEFAULT_FILTER_CONFIG,
+  })
+
+  const [chromaKeySettings, setChromaKeySettings] = useState<ChromaKeyConfig>({
+    ...DEFAULT_CHROMA_KEY_CONFIG,
+  })
+
+  const [stickerSettings, setStickerSettings] = useState<StickerConfig>({
+    ...DEFAULT_STICKER_CONFIG,
+  })
+
+  const [coverConfig, setCoverConfig] = useState<CoverConfig>({
+    ...DEFAULT_COVER_CONFIG,
+  })
+
+  return {
+    titleConfig,
+    setTitleConfig,
+    subtitleSettings,
+    setSubtitleSettings,
+    bgmSettings,
+    setBgmSettings,
+    watermarkSettings,
+    setWatermarkSettings,
+    introOutroSettings,
+    setIntroOutroSettings,
+    pipSettings,
+    setPipSettings,
+    filterSettings,
+    setFilterSettings,
+    chromaKeySettings,
+    setChromaKeySettings,
+    stickerSettings,
+    setStickerSettings,
+    coverConfig,
+    setCoverConfig,
+  }
+}

apps/web/src/pages/editing-planner/hooks/useVoiceMaterials.ts

@@ -0,0 +1,32 @@
+/**
+ * EditingPlanner 配音素材数据加载
+ * queryKey 与 VoiceMaterialLibrary 共享缓存
+ */
+import { useQuery } from "@tanstack/react-query"
+import { ensureDefaultLibrary, getAssetsByKind, type AssetItem } from "@/api/assets"
+import { getOrCreateDefaultProject } from "@/api/projects"
+
+export interface UseVoiceMaterialsReturn {
+  voiceMaterials: AssetItem[]
+  loading: boolean
+  refetch: () => Promise<unknown>
+}
+
+export const useVoiceMaterials = (): UseVoiceMaterialsReturn => {
+  const query = useQuery({
+    queryKey: ["assets", "voice"],
+    queryFn: async () => {
+      const project = await getOrCreateDefaultProject()
+      await ensureDefaultLibrary({ project_id: project.id, kind: "voice" })
+      const assets = await getAssetsByKind("voice")
+      return assets
+    },
+    staleTime: 30_000,
+  })
+
+  return {
+    voiceMaterials: query.data ?? [],
+    loading: query.isLoading,
+    refetch: query.refetch,
+  }
+}

apps/web/src/pages/editing-planner/types.ts

@@ -1,550 +0,0 @@
-/**
- * 片段（Clip）统一类型定义
- * 片段 = 时间规划 + 类型标记，不绑定任何素材
- */
-
-export type ClipType = "voice" | "pip"
-
-/* ──────── 转场特效 ──────── */
-
-/** 14 种转场类型 */
-export type TransitionType =
-  | "none"
-  | "cut"
-  | "fade"
-  | "dissolve"
-  | "zoom"
-  | "slide_left"
-  | "slide_right"
-  | "slide_up"
-  | "slide_down"
-  | "wipe_left"
-  | "wipe_right"
-  | "wipe_up"
-  | "wipe_down"
-  | "circlecrop"
-  | "rectcrop"
-
-/** 片段间转场配置 */
-export interface TransitionConfig {
-  /** 转场类型 */
-  type: TransitionType
-  /** 转场时长（秒），0.3 ~ 2.0 */
-  duration: number
-}
-
-/** 默认转场配置 */
-export const DEFAULT_TRANSITION: TransitionConfig = {
-  type: "none",
-  duration: 0.5,
-}
-
-/* ──────── 片段调速 ──────── */
-
-/** 片段调速配置 */
-export interface SpeedConfig {
-  /** 播放速度，0.25 ~ 4.0 */
-  rate: number
-  /** 音调修正（变速不变调） */
-  pitchCorrection: boolean
-}
-
-/** 默认调速配置 */
-export const DEFAULT_SPEED: SpeedConfig = {
-  rate: 1.0,
-  pitchCorrection: true,
-}
-
-/* ──────── TTS 配音 ──────── */
-
-/** 配音模式 */
-export type TtsMode = "none" | "upload" | "tts"
-
-/** TTS 配音配置 */
-export interface TtsConfig {
-  /** 配音模式 */
-  mode: TtsMode
-  /** TTS 合成文本 */
-  text: string
-  /** 音色 ID */
-  voice_id: string
-  /** 语速 0.5 ~ 2.0 */
-  speed: number
-  /** 语调（半音）-12 ~ +12 */
-  pitch: number
-  /** 音量 0 ~ 100 */
-  volume: number
-  /** 字幕联动 */
-  subtitle_sync: boolean
-}
-
-/** 默认 TTS 配置 */
-export const DEFAULT_TTS_CONFIG: TtsConfig = {
-  mode: "none",
-  text: "",
-  voice_id: "",
-  speed: 1.0,
-  pitch: 0,
-  volume: 100,
-  subtitle_sync: true,
-}
-
-/* ──────── 裁剪配置 ──────── */
-
-/** 片段裁剪配置 — 定义素材的入点/出点 */
-export interface TrimConfig {
-  /** 入点（秒），素材原始时间轴上的起始位置 */
-  start_time: number
-  /** 出点（秒），素材原始时间轴上的结束位置 */
-  end_time: number
-  /** 素材原始总时长（秒），用于"恢复原始长度" */
-  original_duration?: number
-}
-
-/* ──────── 水印配置 ──────── */
-
-/** 水印类型 */
-export type WatermarkType = "none" | "image" | "text" | "scroll"
-
-/** 水印位置 */
-export type WatermarkPosition = "top_left" | "top_right" | "bottom_left" | "bottom_right" | "center"
-
-/** 滚动水印方向 */
-export type ScrollDirection = "horizontal" | "vertical" | "diagonal"
-
-/** 水印配置 */
-export interface WatermarkConfig {
-  /** 水印类型 */
-  type: WatermarkType
-  /** 图片水印 URL */
-  image_url?: string
-  /** 水印宽度（像素或百分比 0~1） */
-  width?: number
-  /** 水印高度（像素或百分比 0~1） */
-  height?: number
-  /** 水印位置 */
-  position: WatermarkPosition
-  /** 水印不透明度 0~1 */
-  opacity: number
-  /** 文字水印内容 */
-  text?: string
-  /** 文字水印字号 */
-  font_size?: number
-  /** 文字水印颜色 */
-  color?: string
-  /** 滚动水印方向 */
-  scroll_direction?: ScrollDirection
-  /** 滚动水印速度（像素/秒） */
-  scroll_speed?: number
-}
-
-/** 默认水印配置 */
-export const DEFAULT_WATERMARK: WatermarkConfig = {
-  type: "none",
-  position: "bottom_right",
-  opacity: 0.7,
-}
-
-/* ──────── 片头片尾配置 ──────── */
-
-/** 片头片尾素材类型 */
-export type IntroOutroKind = "none" | "video" | "image"
-
-/** 片头/片尾单项配置 */
-export interface IntroOutroItem {
-  /** 素材类型 */
-  kind: IntroOutroKind
-  /** 素材 URL */
-  url?: string
-  /** 显示时长（秒） */
-  duration: number
-  /** 过渡动画 */
-  transition?: TransitionType
-  /** 过渡时长（秒） */
-  transition_duration?: number
-}
-
-/** 片头片尾完整配置 */
-export interface IntroOutroConfig {
-  intro: IntroOutroItem
-  outro: IntroOutroItem
-}
-
-/** 默认片头片尾配置 */
-export const DEFAULT_INTRO_OUTRO: IntroOutroConfig = {
-  intro: { kind: "none", duration: 3 },
-  outro: { kind: "none", duration: 3 },
-}
-
-/* ──────── 混剪配置 ──────── */
-
-/** 九宫格位置 */
-export type PipGridPosition =
-  | "top_left"
-  | "top_center"
-  | "top_right"
-  | "center_left"
-  | "center"
-  | "center_right"
-  | "bottom_left"
-  | "bottom_center"
-  | "bottom_right"
-
-/** 入场动画类型 */
-export type PipAnimType = "none" | "fade_in" | "slide_in"
-
-/** 入场方向 */
-export type PipSlideDirection = "left" | "right" | "up" | "down"
-
-/** 混剪图层 */
-export interface PipLayer {
-  id: string
-  /** 图层名称（用户可编辑） */
-  name: string
-  /** 素材类型 */
-  material_type: "image" | "video"
-  /** 素材 URL */
-  material_url: string
-  /** 素材缩略图 */
-  thumbnail_url?: string
-  /** 九宫格快捷位置 */
-  grid_position: PipGridPosition
-  /** 精确 X 坐标（百分比 0~100） */
-  x: number
-  /** 精确 Y 坐标（百分比 0~100） */
-  y: number
-  /** 宽度（百分比 0~100，相对主画面） */
-  width: number
-  /** 高度（百分比 0~100，相对主画面） */
-  height: number
-  /** 锁定宽高比 */
-  aspect_lock: boolean
-  /** 圆角（百分比 0~50） */
-  border_radius: number
-  /** 不透明度（0~100） */
-  opacity: number
-  /** 开始时间（秒） */
-  start_time: number
-  /** 持续时长（秒） */
-  duration: number
-  /** 入场动画 */
-  animation: PipAnimType
-  /** 入场方向 */
-  slide_direction: PipSlideDirection
-  /** 图层顺序（z-index） */
-  z_index: number
-}
-
-/** 混剪配置 */
-export interface PipConfig {
-  /** 是否启用混剪 */
-  enabled: boolean
-  /** 图层列表 */
-  layers: PipLayer[]
-}
-
-/** 默认 PiP 图层 */
-export const DEFAULT_PIP_LAYER: PipLayer = {
-  id: "",
-  name: "图层",
-  material_type: "image",
-  material_url: "",
-  grid_position: "top_right",
-  x: 70,
-  y: 5,
-  width: 25,
-  height: 25,
-  aspect_lock: true,
-  border_radius: 0,
-  opacity: 100,
-  start_time: 0,
-  duration: 5,
-  animation: "none",
-  slide_direction: "right",
-  z_index: 1,
-}
-
-/** 默认 PiP 配置 */
-export const DEFAULT_PIP_CONFIG: PipConfig = {
-  enabled: false,
-  layers: [],
-}
-
-/* ──────── 滤镜调色 ──────── */
-
-/** 预设滤镜 */
-export type FilterPreset =
-  | "none"
-  | "original"
-  | "fresh"
-  | "warm"
-  | "cool"
-  | "vintage"
-  | "cinema"
-  | "bw"
-  | "sunshine"
-  | "film"
-
-/** 预设滤镜标签 */
-export const FILTER_PRESET_LABELS: Record<FilterPreset, string> = {
-  none: "无",
-  original: "原片",
-  fresh: "清新",
-  warm: "暖调",
-  cool: "冷色",
-  vintage: "复古",
-  cinema: "电影",
-  bw: "黑白",
-  sunshine: "暖阳",
-  film: "胶片",
-}
-
-/** 滤镜调色配置 */
-export interface FilterConfig {
-  /** 是否启用滤镜 */
-  enabled: boolean
-  /** 预设滤镜 */
-  preset: FilterPreset
-  /** 亮度（-100 ~ 100） */
-  brightness: number
-  /** 对比度（-100 ~ 100） */
-  contrast: number
-  /** 饱和度（-100 ~ 100） */
-  saturation: number
-  /** 色温（-100 ~ 100，负值偏蓝，正值偏黄） */
-  temperature: number
-  /** 色调（-100 ~ 100，负值偏绿，正值偏品红） */
-  tint: number
-  /** 锐度（0 ~ 100） */
-  sharpness: number
-}
-
-/** 默认滤镜调色配置 */
-export const DEFAULT_FILTER_CONFIG: FilterConfig = {
-  enabled: false,
-  preset: "none",
-  brightness: 0,
-  contrast: 0,
-  saturation: 0,
-  temperature: 0,
-  tint: 0,
-  sharpness: 0,
-}
-
-/* ──────── 绿幕抠像 ──────── */
-
-/** 绿幕抠像颜色预设 */
-export type ChromaKeyColorPreset = "green" | "blue" | "red" | "pure_green" | "soft_green"
-
-/** 颜色预设标签 */
-export const CHROMA_KEY_PRESET_LABELS: Record<ChromaKeyColorPreset, string> = {
-  green: "绿",
-  blue: "蓝",
-  red: "红",
-  pure_green: "精绿",
-  soft_green: "柔绿",
-}
-
-/** 颜色预设对应的默认色值 */
-export const CHROMA_KEY_PRESET_COLORS: Record<ChromaKeyColorPreset, string> = {
-  green: "#00FF00",
-  blue: "#0000FF",
-  red: "#FF0000",
-  pure_green: "#00C800",
-  soft_green: "#40E040",
-}
-
-/** 绿幕抠像配置 */
-export interface ChromaKeyConfig {
-  /** 是否启用绿幕抠像 */
-  enabled: boolean
-  /** 颜色预设 */
-  color_preset: ChromaKeyColorPreset
-  /** 抠像目标颜色（HEX） */
-  color: string
-  /** 相似度（0 ~ 100，越大容忍的色差范围越广） */
-  similarity: number
-  /** 边缘平滑（0 ~ 100，越大边缘越柔和） */
-  blend: number
-  /** 溢色抑制（0 ~ 100，去除边缘颜色溢出） */
-  spill: number
-}
-
-/** 默认绿幕抠像配置 */
-export const DEFAULT_CHROMA_KEY_CONFIG: ChromaKeyConfig = {
-  enabled: false,
-  color_preset: "green",
-  color: "#00FF00",
-  similarity: 30,
-  blend: 10,
-  spill: 20,
-}
-
-/* ──────── 贴纸配置 ──────── */
-
-/** 贴纸类型 */
-export type StickerType = "emoji" | "image" | "text"
-
-/** 文字花字预设 */
-export type TextStickerPreset =
-  | "normal" // 普通
-  | "highlight" // 高亮
-  | "bubble" // 气泡
-  | "neon" // 霓虹
-  | "shadow" // 投影
-  | "outline" // 描边
-  | "gradient" // 渐变
-  | "handwrite" // 手写
-
-/** 贴纸项 */
-export interface StickerItem {
-  id: string
-  /** 贴纸类型 */
-  type: StickerType
-  /** 内容（emoji 字符 / 图片 URL / 文字内容） */
-  content: string
-  /** X 坐标（百分比 0~100） */
-  x: number
-  /** Y 坐标（百分比 0~100） */
-  y: number
-  /** 宽度（百分比 0~100） */
-  width: number
-  /** 高度（百分比 0~100） */
-  height: number
-  /** 旋转角度（度 -180~180） */
-  rotation: number
-  /** 不透明度（0~100） */
-  opacity: number
-  /** 开始时间（秒） */
-  start_time: number
-  /** 持续时长（秒，0 表示全程显示） */
-  duration: number
-  /** 图层顺序 */
-  z_index: number
-  /** 文字花字预设（仅 type=text 时有效） */
-  text_preset: TextStickerPreset
-  /** 文字颜色（仅 type=text 时有效） */
-  text_color: string
-  /** 文字大小（px，仅 type=text 时有效） */
-  font_size: number
-}
-
-/** 贴纸配置 */
-export interface StickerConfig {
-  enabled: boolean
-  items: StickerItem[]
-}
-
-/** 默认贴纸项 */
-export const DEFAULT_STICKER_ITEM: StickerItem = {
-  id: "",
-  type: "emoji",
-  content: "😀",
-  x: 50,
-  y: 50,
-  width: 15,
-  height: 15,
-  rotation: 0,
-  opacity: 100,
-  start_time: 0,
-  duration: 0,
-  z_index: 1,
-  text_preset: "normal",
-  text_color: "#FFFFFF",
-  font_size: 24,
-}
-
-/** 默认贴纸配置 */
-export const DEFAULT_STICKER_CONFIG: StickerConfig = {
-  enabled: false,
-  items: [],
-}
-
-/** 文字花字预设标签 */
-export const TEXT_STICKER_PRESET_LABELS: Record<TextStickerPreset, string> = {
-  normal: "普通",
-  highlight: "高亮",
-  bubble: "气泡",
-  neon: "霓虹",
-  shadow: "投影",
-  outline: "描边",
-  gradient: "渐变",
-  handwrite: "手写",
-}
-
-/* ──────── 封面配置 ──────── */
-
-/** 封面来源模式 */
-export type CoverMode = "auto" | "frame" | "upload"
-
-/** 封面配置 */
-export interface CoverConfig {
-  /** 是否启用自定义封面 */
-  enabled: boolean
-  /** 封面来源模式 */
-  mode: CoverMode
-  /** 抽帧时间点（秒，mode=frame 时使用） */
-  frame_time: number
-  /** 上传的封面 URL（mode=upload 时使用） */
-  upload_url: string
-  /** AI 智能推荐的抽帧时间（由后端分析得出） */
-  ai_suggested_time: number | null
-  /** 封面缩略图 URL */
-  thumbnail_url: string
-}
-
-/** 默认封面配置 */
-export const DEFAULT_COVER_CONFIG: CoverConfig = {
-  enabled: false,
-  mode: "auto",
-  frame_time: 0,
-  upload_url: "",
-  ai_suggested_time: null,
-  thumbnail_url: "",
-}
-
-/* ──────── 片段数据 ──────── */
-
-export interface ClipData {
-  id: string
-  type: ClipType // 片段类型：voice（口播）或 pip（混剪）
-  duration: number // 时长（秒）
-  startOffset: number // 仅 voice 类型：在口播素材中的起始时间（秒）
-  /** 素材库素材 ID（main/pip 类型片段使用） */
-  media_asset_id?: string
-  // 保留兼容字段（后端序列化需要）
-  template_segment_id?: string
-  script_text?: string
-  order?: number
-  /** 配音素材 ID（voice 类型片段使用） */
-  voice_asset_id?: string
-  /** 配音素材文件 URL（voice 类型片段使用） */
-  voice_file_url?: string
-  /** 与前一片段之间的转场效果 */
-  transition?: TransitionConfig
-  /** 播放速度配置 */
-  speed?: SpeedConfig
-  /** TTS 配音配置 */
-  tts_config?: TtsConfig
-  /** 裁剪配置 — 定义素材入点/出点 */
-  trim_config?: TrimConfig
-}
-
-/* ──────── 标题设置 ──────── */
-
-/**
- * 标题设置 — 对齐后端 title_config 字段
- * 前端 UI 使用 camelCase，发送到后端时映射为 snake_case
- */
-export interface TitleSettings {
-  aiAutoSelect: boolean
-  title: string
-  position: string
-  font: string
-  size: number
-  bold: boolean
-  italic: boolean
-  stroke: boolean
-  shadow: boolean
-  color: string
-}

apps/web/src/pages/editing-planner/types/chroma-key.ts

@@ -0,0 +1,50 @@
+/**
+ * 绿幕抠像类型
+ */
+
+/** 绿幕抠像颜色预设 */
+export type ChromaKeyColorPreset = "green" | "blue" | "red" | "pure_green" | "soft_green"
+
+/** 颜色预设标签 */
+export const CHROMA_KEY_PRESET_LABELS: Record<ChromaKeyColorPreset, string> = {
+  green: "绿",
+  blue: "蓝",
+  red: "红",
+  pure_green: "精绿",
+  soft_green: "柔绿",
+}
+
+/** 颜色预设对应的默认色值 */
+export const CHROMA_KEY_PRESET_COLORS: Record<ChromaKeyColorPreset, string> = {
+  green: "#00FF00",
+  blue: "#0000FF",
+  red: "#FF0000",
+  pure_green: "#00C800",
+  soft_green: "#40E040",
+}
+
+/** 绿幕抠像配置 */
+export interface ChromaKeyConfig {
+  /** 是否启用绿幕抠像 */
+  enabled: boolean
+  /** 颜色预设 */
+  color_preset: ChromaKeyColorPreset
+  /** 抠像目标颜色（HEX） */
+  color: string
+  /** 相似度（0 ~ 100，越大容忍的色差范围越广） */
+  similarity: number
+  /** 边缘平滑（0 ~ 100，越大边缘越柔和） */
+  blend: number
+  /** 溢色抑制（0 ~ 100，去除边缘颜色溢出） */
+  spill: number
+}
+
+/** 默认绿幕抠像配置 */
+export const DEFAULT_CHROMA_KEY_CONFIG: ChromaKeyConfig = {
+  enabled: false,
+  color_preset: "green",
+  color: "#00FF00",
+  similarity: 30,
+  blend: 10,
+  spill: 20,
+}

apps/web/src/pages/editing-planner/types/clip.ts

@@ -0,0 +1,36 @@
+/**
+ * 片段数据类型
+ */
+import type { TransitionConfig } from "./transition"
+import type { SpeedConfig } from "./speed"
+import type { TtsConfig } from "./tts"
+import type { TrimConfig } from "./trim"
+
+/** 片段类型 */
+export type ClipType = "voice" | "pip"
+
+/** 片段数据 — 时间规划 + 类型标记，不绑定任何素材 */
+export interface ClipData {
+  id: string
+  type: ClipType // 片段类型：voice（口播）或 pip（混剪）
+  duration: number // 时长（秒）
+  startOffset: number // 仅 voice 类型：在口播素材中的起始时间（秒）
+  /** 素材库素材 ID（main/pip 类型片段使用） */
+  media_asset_id?: string
+  // 保留兼容字段（后端序列化需要）
+  template_segment_id?: string
+  script_text?: string
+  order?: number
+  /** 配音素材 ID（voice 类型片段使用） */
+  voice_asset_id?: string
+  /** 配音素材文件 URL（voice 类型片段使用） */
+  voice_file_url?: string
+  /** 与前一片段之间的转场效果 */
+  transition?: TransitionConfig
+  /** 播放速度配置 */
+  speed?: SpeedConfig
+  /** TTS 配音配置 */
+  tts_config?: TtsConfig
+  /** 裁剪配置 — 定义素材入点/出点 */
+  trim_config?: TrimConfig
+}

apps/web/src/pages/editing-planner/types/clipProperties.ts

@@ -1,7 +1,7 @@
 /**
  * ClipPropertiesPanel 相关类型定义
  */
-import type { ClipData } from "@/pages/editing-planner/types"
+import type { ClipData } from "./clip"
 import type { TemplateMode } from "@/api/editing-planner"
 import type { AssetItem } from "@/api/assets"
 

apps/web/src/pages/editing-planner/types/cover.ts

@@ -0,0 +1,32 @@
+/**
+ * 封面配置类型
+ */
+
+/** 封面来源模式 */
+export type CoverMode = "auto" | "frame" | "upload"
+
+/** 封面配置 */
+export interface CoverConfig {
+  /** 是否启用自定义封面 */
+  enabled: boolean
+  /** 封面来源模式 */
+  mode: CoverMode
+  /** 抽帧时间点（秒，mode=frame 时使用） */
+  frame_time: number
+  /** 上传的封面 URL（mode=upload 时使用） */
+  upload_url: string
+  /** AI 智能推荐的抽帧时间（由后端分析得出） */
+  ai_suggested_time: number | null
+  /** 封面缩略图 URL */
+  thumbnail_url: string
+}
+
+/** 默认封面配置 */
+export const DEFAULT_COVER_CONFIG: CoverConfig = {
+  enabled: false,
+  mode: "auto",
+  frame_time: 0,
+  upload_url: "",
+  ai_suggested_time: null,
+  thumbnail_url: "",
+}

apps/web/src/pages/editing-planner/types/filter.ts

@@ -0,0 +1,62 @@
+/**
+ * 滤镜调色类型
+ */
+
+/** 预设滤镜 */
+export type FilterPreset =
+  | "none"
+  | "original"
+  | "fresh"
+  | "warm"
+  | "cool"
+  | "vintage"
+  | "cinema"
+  | "bw"
+  | "sunshine"
+  | "film"
+
+/** 预设滤镜标签 */
+export const FILTER_PRESET_LABELS: Record<FilterPreset, string> = {
+  none: "无",
+  original: "原片",
+  fresh: "清新",
+  warm: "暖调",
+  cool: "冷色",
+  vintage: "复古",
+  cinema: "电影",
+  bw: "黑白",
+  sunshine: "暖阳",
+  film: "胶片",
+}
+
+/** 滤镜调色配置 */
+export interface FilterConfig {
+  /** 是否启用滤镜 */
+  enabled: boolean
+  /** 预设滤镜 */
+  preset: FilterPreset
+  /** 亮度（-100 ~ 100） */
+  brightness: number
+  /** 对比度（-100 ~ 100） */
+  contrast: number
+  /** 饱和度（-100 ~ 100） */
+  saturation: number
+  /** 色温（-100 ~ 100，负值偏蓝，正值偏黄） */
+  temperature: number
+  /** 色调（-100 ~ 100，负值偏绿，正值偏品红） */
+  tint: number
+  /** 锐度（0 ~ 100） */
+  sharpness: number
+}
+
+/** 默认滤镜调色配置 */
+export const DEFAULT_FILTER_CONFIG: FilterConfig = {
+  enabled: false,
+  preset: "none",
+  brightness: 0,
+  contrast: 0,
+  saturation: 0,
+  temperature: 0,
+  tint: 0,
+  sharpness: 0,
+}

apps/web/src/pages/editing-planner/types/index.ts

@@ -0,0 +1,84 @@
+/**
+ * EditingPlanner 类型定义入口
+ * 按功能模块拆分，统一从这里导出
+ */
+
+/* 转场 */
+export { type TransitionType, type TransitionConfig, DEFAULT_TRANSITION } from "./transition"
+
+/* 调速 */
+export { type SpeedConfig, DEFAULT_SPEED } from "./speed"
+
+/* TTS 配音 */
+export { type TtsMode, type TtsConfig, DEFAULT_TTS_CONFIG } from "./tts"
+
+/* 裁剪 */
+export { type TrimConfig } from "./trim"
+
+/* 水印 */
+export {
+  type WatermarkType,
+  type WatermarkPosition,
+  type ScrollDirection,
+  type WatermarkConfig,
+  DEFAULT_WATERMARK,
+} from "./watermark"
+
+/* 片头片尾 */
+export {
+  type IntroOutroKind,
+  type IntroOutroItem,
+  type IntroOutroConfig,
+  DEFAULT_INTRO_OUTRO,
+} from "./intro-outro"
+
+/* 混剪 PiP */
+export {
+  type PipGridPosition,
+  type PipAnimType,
+  type PipSlideDirection,
+  type PipLayer,
+  type PipConfig,
+  DEFAULT_PIP_LAYER,
+  DEFAULT_PIP_CONFIG,
+} from "./pip"
+
+/* 滤镜调色 */
+export {
+  type FilterPreset,
+  FILTER_PRESET_LABELS,
+  type FilterConfig,
+  DEFAULT_FILTER_CONFIG,
+} from "./filter"
+
+/* 绿幕抠像 */
+export {
+  type ChromaKeyColorPreset,
+  CHROMA_KEY_PRESET_LABELS,
+  CHROMA_KEY_PRESET_COLORS,
+  type ChromaKeyConfig,
+  DEFAULT_CHROMA_KEY_CONFIG,
+} from "./chroma-key"
+
+/* 贴纸 */
+export {
+  type StickerType,
+  type TextStickerPreset,
+  type StickerItem,
+  type StickerConfig,
+  DEFAULT_STICKER_ITEM,
+  DEFAULT_STICKER_CONFIG,
+  TEXT_STICKER_PRESET_LABELS,
+} from "./sticker"
+
+/* 封面 */
+export { type CoverMode, type CoverConfig, DEFAULT_COVER_CONFIG } from "./cover"
+
+/* 片段数据 */
+export { type ClipType, type ClipData } from "./clip"
+
+/* 标题设置 */
+export { type TitleSettings } from "./title"
+
+/* 字幕样式 */
+export { type SubtitleStyleConfig, DEFAULT_SUBTITLE_STYLE } from "./subtitle"

apps/web/src/pages/editing-planner/types/intro-outro.ts

@@ -0,0 +1,33 @@
+/**
+ * 片头片尾配置类型
+ */
+import type { TransitionType } from "./transition"
+
+/** 片头片尾素材类型 */
+export type IntroOutroKind = "none" | "video" | "image"
+
+/** 片头/片尾单项配置 */
+export interface IntroOutroItem {
+  /** 素材类型 */
+  kind: IntroOutroKind
+  /** 素材 URL */
+  url?: string
+  /** 显示时长（秒） */
+  duration: number
+  /** 过渡动画 */
+  transition?: TransitionType
+  /** 过渡时长（秒） */
+  transition_duration?: number
+}
+
+/** 片头片尾完整配置 */
+export interface IntroOutroConfig {
+  intro: IntroOutroItem
+  outro: IntroOutroItem
+}
+
+/** 默认片头片尾配置 */
+export const DEFAULT_INTRO_OUTRO: IntroOutroConfig = {
+  intro: { kind: "none", duration: 3 },
+  outro: { kind: "none", duration: 3 },
+}

apps/web/src/pages/editing-planner/types/pip.ts

@@ -0,0 +1,95 @@
+/**
+ * 混剪（PiP）配置类型
+ */
+
+/** 九宫格位置 */
+export type PipGridPosition =
+  | "top_left"
+  | "top_center"
+  | "top_right"
+  | "center_left"
+  | "center"
+  | "center_right"
+  | "bottom_left"
+  | "bottom_center"
+  | "bottom_right"
+
+/** 入场动画类型 */
+export type PipAnimType = "none" | "fade_in" | "slide_in"
+
+/** 入场方向 */
+export type PipSlideDirection = "left" | "right" | "up" | "down"
+
+/** 混剪图层 */
+export interface PipLayer {
+  id: string
+  /** 图层名称（用户可编辑） */
+  name: string
+  /** 素材类型 */
+  material_type: "image" | "video"
+  /** 素材 URL */
+  material_url: string
+  /** 素材缩略图 */
+  thumbnail_url?: string
+  /** 九宫格快捷位置 */
+  grid_position: PipGridPosition
+  /** 精确 X 坐标（百分比 0~100） */
+  x: number
+  /** 精确 Y 坐标（百分比 0~100） */
+  y: number
+  /** 宽度（百分比 0~100，相对主画面） */
+  width: number
+  /** 高度（百分比 0~100，相对主画面） */
+  height: number
+  /** 锁定宽高比 */
+  aspect_lock: boolean
+  /** 圆角（百分比 0~50） */
+  border_radius: number
+  /** 不透明度（0~100） */
+  opacity: number
+  /** 开始时间（秒） */
+  start_time: number
+  /** 持续时长（秒） */
+  duration: number
+  /** 入场动画 */
+  animation: PipAnimType
+  /** 入场方向 */
+  slide_direction: PipSlideDirection
+  /** 图层顺序（z-index） */
+  z_index: number
+}
+
+/** 混剪配置 */
+export interface PipConfig {
+  /** 是否启用混剪 */
+  enabled: boolean
+  /** 图层列表 */
+  layers: PipLayer[]
+}
+
+/** 默认 PiP 图层 */
+export const DEFAULT_PIP_LAYER: PipLayer = {
+  id: "",
+  name: "图层",
+  material_type: "image",
+  material_url: "",
+  grid_position: "top_right",
+  x: 70,
+  y: 5,
+  width: 25,
+  height: 25,
+  aspect_lock: true,
+  border_radius: 0,
+  opacity: 100,
+  start_time: 0,
+  duration: 5,
+  animation: "none",
+  slide_direction: "right",
+  z_index: 1,
+}
+
+/** 默认 PiP 配置 */
+export const DEFAULT_PIP_CONFIG: PipConfig = {
+  enabled: false,
+  layers: [],
+}

apps/web/src/pages/editing-planner/types/speed.ts

@@ -0,0 +1,17 @@
+/**
+ * 片段调速类型
+ */
+
+/** 片段调速配置 */
+export interface SpeedConfig {
+  /** 播放速度，0.25 ~ 4.0 */
+  rate: number
+  /** 音调修正（变速不变调） */
+  pitchCorrection: boolean
+}
+
+/** 默认调速配置 */
+export const DEFAULT_SPEED: SpeedConfig = {
+  rate: 1.0,
+  pitchCorrection: true,
+}

apps/web/src/pages/editing-planner/types/sticker.ts

@@ -0,0 +1,93 @@
+/**
+ * 贴纸配置类型
+ */
+
+/** 贴纸类型 */
+export type StickerType = "emoji" | "image" | "text"
+
+/** 文字花字预设 */
+export type TextStickerPreset =
+  | "normal" // 普通
+  | "highlight" // 高亮
+  | "bubble" // 气泡
+  | "neon" // 霓虹
+  | "shadow" // 投影
+  | "outline" // 描边
+  | "gradient" // 渐变
+  | "handwrite" // 手写
+
+/** 贴纸项 */
+export interface StickerItem {
+  id: string
+  /** 贴纸类型 */
+  type: StickerType
+  /** 内容（emoji 字符 / 图片 URL / 文字内容） */
+  content: string
+  /** X 坐标（百分比 0~100） */
+  x: number
+  /** Y 坐标（百分比 0~100） */
+  y: number
+  /** 宽度（百分比 0~100） */
+  width: number
+  /** 高度（百分比 0~100） */
+  height: number
+  /** 旋转角度（度 -180~180） */
+  rotation: number
+  /** 不透明度（0~100） */
+  opacity: number
+  /** 开始时间（秒） */
+  start_time: number
+  /** 持续时长（秒，0 表示全程显示） */
+  duration: number
+  /** 图层顺序 */
+  z_index: number
+  /** 文字花字预设（仅 type=text 时有效） */
+  text_preset: TextStickerPreset
+  /** 文字颜色（仅 type=text 时有效） */
+  text_color: string
+  /** 文字大小（px，仅 type=text 时有效） */
+  font_size: number
+}
+
+/** 贴纸配置 */
+export interface StickerConfig {
+  enabled: boolean
+  items: StickerItem[]
+}
+
+/** 默认贴纸项 */
+export const DEFAULT_STICKER_ITEM: StickerItem = {
+  id: "",
+  type: "emoji",
+  content: "😀",
+  x: 50,
+  y: 50,
+  width: 15,
+  height: 15,
+  rotation: 0,
+  opacity: 100,
+  start_time: 0,
+  duration: 0,
+  z_index: 1,
+  text_preset: "normal",
+  text_color: "#FFFFFF",
+  font_size: 24,
+}
+
+/** 默认贴纸配置 */
+export const DEFAULT_STICKER_CONFIG: StickerConfig = {
+  enabled: false,
+  items: [],
+}
+
+/** 文字花字预设标签 */
+export const TEXT_STICKER_PRESET_LABELS: Record<TextStickerPreset, string> = {
+  normal: "普通",
+  highlight: "高亮",
+  bubble: "气泡",
+  neon: "霓虹",
+  shadow: "投影",
+  outline: "描边",
+  gradient: "渐变",
+  handwrite: "手写",
+}

apps/web/src/pages/editing-planner/types/title.ts

@@ -0,0 +1,20 @@
+/**
+ * 标题设置类型
+ */
+
+/**
+ * 标题设置 — 对齐后端 title_config 字段
+ * 前端 UI 使用 camelCase，发送到后端时映射为 snake_case
+ */
+export interface TitleSettings {
+  aiAutoSelect: boolean
+  title: string
+  position: string
+  font: string
+  size: number
+  bold: boolean
+  italic: boolean
+  stroke: boolean
+  shadow: boolean
+  color: string
+}

apps/web/src/pages/editing-planner/types/transition.ts

@@ -0,0 +1,35 @@
+/**
+ * 转场特效类型
+ */
+
+/** 14 种转场类型 */
+export type TransitionType =
+  | "none"
+  | "cut"
+  | "fade"
+  | "dissolve"
+  | "zoom"
+  | "slide_left"
+  | "slide_right"
+  | "slide_up"
+  | "slide_down"
+  | "wipe_left"
+  | "wipe_right"
+  | "wipe_up"
+  | "wipe_down"
+  | "circlecrop"
+  | "rectcrop"
+
+/** 片段间转场配置 */
+export interface TransitionConfig {
+  /** 转场类型 */
+  type: TransitionType
+  /** 转场时长（秒），0.3 ~ 2.0 */
+  duration: number
+}
+
+/** 默认转场配置 */
+export const DEFAULT_TRANSITION: TransitionConfig = {
+  type: "none",
+  duration: 0.5,
+}

apps/web/src/pages/editing-planner/types/trim.ts

@@ -0,0 +1,13 @@
+/**
+ * 片段裁剪类型
+ */
+
+/** 片段裁剪配置 — 定义素材的入点/出点 */
+export interface TrimConfig {
+  /** 入点（秒），素材原始时间轴上的起始位置 */
+  start_time: number
+  /** 出点（秒），素材原始时间轴上的结束位置 */
+  end_time: number
+  /** 素材原始总时长（秒），用于"恢复原始长度" */
+  original_duration?: number
+}

apps/web/src/pages/editing-planner/types/tts.ts

@@ -0,0 +1,35 @@
+/**
+ * TTS 配音类型
+ */
+
+/** 配音模式 */
+export type TtsMode = "none" | "upload" | "tts"
+
+/** TTS 配音配置 */
+export interface TtsConfig {
+  /** 配音模式 */
+  mode: TtsMode
+  /** TTS 合成文本 */
+  text: string
+  /** 音色 ID */
+  voice_id: string
+  /** 语速 0.5 ~ 2.0 */
+  speed: number
+  /** 语调（半音）-12 ~ +12 */
+  pitch: number
+  /** 音量 0 ~ 100 */
+  volume: number
+  /** 字幕联动 */
+  subtitle_sync: boolean
+}
+
+/** 默认 TTS 配置 */
+export const DEFAULT_TTS_CONFIG: TtsConfig = {
+  mode: "none",
+  text: "",
+  voice_id: "",
+  speed: 1.0,
+  pitch: 0,
+  volume: 100,
+  subtitle_sync: true,
+}

apps/web/src/pages/editing-planner/types/watermark.ts

@@ -0,0 +1,45 @@
+/**
+ * 水印配置类型
+ */
+
+/** 水印类型 */
+export type WatermarkType = "none" | "image" | "text" | "scroll"
+
+/** 水印位置 */
+export type WatermarkPosition = "top_left" | "top_right" | "bottom_left" | "bottom_right" | "center"
+
+/** 滚动水印方向 */
+export type ScrollDirection = "horizontal" | "vertical" | "diagonal"
+
+/** 水印配置 */
+export interface WatermarkConfig {
+  /** 水印类型 */
+  type: WatermarkType
+  /** 图片水印 URL */
+  image_url?: string
+  /** 水印宽度（像素或百分比 0~1） */
+  width?: number
+  /** 水印高度（像素或百分比 0~1） */
+  height?: number
+  /** 水印位置 */
+  position: WatermarkPosition
+  /** 水印不透明度 0~1 */
+  opacity: number
+  /** 文字水印内容 */
+  text?: string
+  /** 文字水印字号 */
+  font_size?: number
+  /** 文字水印颜色 */
+  color?: string
+  /** 滚动水印方向 */
+  scroll_direction?: ScrollDirection
+  /** 滚动水印速度（像素/秒） */
+  scroll_speed?: number
+}
+
+/** 默认水印配置 */
+export const DEFAULT_WATERMARK: WatermarkConfig = {
+  type: "none",
+  position: "bottom_right",
+  opacity: 0.7,
+}

apps/web/src/pages/generate/hooks/step5-voice/useSaveToLibrary.tsx

@@ -0,0 +1,113 @@
+import { useState, useCallback } from "react"
+import { useNavigate } from "react-router-dom"
+import { message } from "antd"
+import { useQuery, useMutation } from "@tanstack/react-query"
+import { saveTtsToLibrary } from "@/api/tts"
+import { getTags, createTag } from "@/api/tags"
+
+/**
+ * 存为素材（配音库）弹窗逻辑
+ */
+export function useSaveToLibrary(completedTtsJobId: string | null, resetTtsState: () => void) {
+  const navigate = useNavigate()
+
+  const [saveModalOpen, setSaveModalOpen] = useState(false)
+  const [saveName, setSaveName] = useState("")
+  const [saveTagIds, setSaveTagIds] = useState<string[]>([])
+  const [saveNewTag, setSaveNewTag] = useState("")
+
+  const { data: allTags = [] } = useQuery({
+    queryKey: ["generate-save-tags"],
+    queryFn: getTags,
+    staleTime: 30_000,
+  })
+
+  const handleGoToLibrary = useCallback(() => {
+    navigate("/app/voice-materials")
+  }, [navigate])
+
+  const saveToLibraryMutation = useMutation({
+    mutationFn: (params: { name?: string; tag_ids?: string[] }) =>
+      saveTtsToLibrary(completedTtsJobId!, params),
+    onSuccess: () => {
+      message.success({
+        content: (
+          <span>
+            已保存到配音库！{" "}
+            <a
+              onClick={handleGoToLibrary}
+              style={{
+                color: "var(--primary-500, #6366f1)",
+                cursor: "pointer",
+              }}
+            >
+              去视频库查看
+            </a>
+          </span>
+        ),
+        duration: 5,
+      })
+      setSaveModalOpen(false)
+      setSaveName("")
+      setSaveTagIds([])
+      setSaveNewTag("")
+      resetTtsState()
+    },
+    onError: (err: Error) => {
+      message.error(`保存失败：${err.message || "请重试"}`)
+    },
+  })
+
+  const handleOpenSaveModal = useCallback(() => {
+    setSaveName("")
+    setSaveTagIds([])
+    setSaveNewTag("")
+    setSaveModalOpen(true)
+  }, [])
+
+  const handleConfirmSave = useCallback(() => {
+    if (!completedTtsJobId) return
+    saveToLibraryMutation.mutate({
+      name: saveName.trim() || undefined,
+      tag_ids: saveTagIds.length > 0 ? saveTagIds : undefined,
+    })
+  }, [completedTtsJobId, saveName, saveTagIds, saveToLibraryMutation])
+
+  const handleAddTagInModal = useCallback(
+    async (tagName: string) => {
+      const trimmed = tagName.trim()
+      if (!trimmed) return
+      const existing = allTags.find((t) => t.name === trimmed)
+      if (existing) {
+        if (!saveTagIds.includes(existing.id)) {
+          setSaveTagIds((prev) => [...prev, existing.id])
+        }
+        return
+      }
+      try {
+        const created = await createTag(trimmed)
+        setSaveTagIds((prev) => [...prev, created.id])
+        setSaveNewTag("")
+      } catch {
+        message.error(`创建标签"${trimmed}"失败`)
+      }
+    },
+    [allTags, saveTagIds],
+  )
+
+  return {
+    saveModalOpen,
+    setSaveModalOpen,
+    saveName,
+    setSaveName,
+    saveTagIds,
+    setSaveTagIds,
+    saveNewTag,
+    setSaveNewTag,
+    allTags,
+    saveToLibraryMutation,
+    handleOpenSaveModal,
+    handleConfirmSave,
+    handleAddTagInModal,
+  }
+}

apps/web/src/pages/generate/hooks/step5-voice/useTtsSynthesis.ts

@@ -0,0 +1,96 @@
+import { useState, useCallback, useEffect } from "react"
+import { message } from "antd"
+import { useMutation } from "@tanstack/react-query"
+import { synthesizeSpeech, getTTSJobStatus } from "@/api/tts"
+
+/**
+ * TTS 自定义合成 + 轮询状态
+ */
+export function useTtsSynthesis(selectedVoice: string) {
+  const [customVoiceText, setCustomVoiceText] = useState("")
+  const [customAudioUrl, setCustomAudioUrl] = useState<string | null>(null)
+  const [ttsError, setTtsError] = useState<string | null>(null)
+  const [ttsJobId, setTtsJobId] = useState<string | null>(null)
+  const [completedTtsJobId, setCompletedTtsJobId] = useState<string | null>(null)
+
+  const synthesizeMutation = useMutation({
+    mutationFn: synthesizeSpeech,
+    onSuccess: (data) => {
+      setTtsJobId(data.job_id)
+      message.info("语音合成已提交，等待处理…")
+    },
+    onError: () => {
+      setTtsError("语音合成请求失败，请重试")
+    },
+  })
+
+  /* 轮询 TTS 任务状态 */
+  useEffect(() => {
+    if (!ttsJobId) return
+    let cancelled = false
+    let timer: ReturnType<typeof setTimeout>
+
+    const poll = async () => {
+      try {
+        const status = await getTTSJobStatus(ttsJobId)
+        if (cancelled) return
+        if (status.status === "completed") {
+          setCustomAudioUrl(status.output_audio_url)
+          setCompletedTtsJobId(ttsJobId)
+          setTtsJobId(null)
+          setTtsError(null)
+          message.success("语音合成完成！")
+          return
+        }
+        if (status.status === "failed" || status.status === "cancelled") {
+          setTtsError(status.error_message || "语音合成失败")
+          setTtsJobId(null)
+          return
+        }
+        timer = setTimeout(poll, 2000)
+      } catch {
+        if (!cancelled) {
+          setTtsError("查询合成状态失败")
+          setTtsJobId(null)
+        }
+      }
+    }
+
+    timer = setTimeout(poll, 2000)
+    return () => {
+      cancelled = true
+      clearTimeout(timer)
+    }
+  }, [ttsJobId])
+
+  const handleSynthesizeVoice = useCallback(() => {
+    if (!customVoiceText.trim()) {
+      message.warning("请先输入配音文案")
+      return
+    }
+    setTtsError(null)
+    setCustomAudioUrl(null)
+    synthesizeMutation.mutate({
+      text: customVoiceText.trim(),
+      voice_id: selectedVoice || undefined,
+      language: "zh-CN",
+    })
+  }, [customVoiceText, selectedVoice, synthesizeMutation])
+
+  const resetTtsState = useCallback(() => {
+    setCompletedTtsJobId(null)
+    setCustomAudioUrl(null)
+  }, [])
+
+  return {
+    customVoiceText,
+    setCustomVoiceText,
+    customAudioUrl,
+    ttsError,
+    ttsJobId,
+    completedTtsJobId,
+    synthesizeMutation,
+    handleSynthesizeVoice,
+    resetTtsState,
+  }
+}

apps/web/src/pages/generate/hooks/step5-voice/useVoiceAudio.ts

@@ -0,0 +1,39 @@
+import { useState, useRef, useCallback } from "react"
+import { message } from "antd"
+
+/**
+ * 音色试听播放控制
+ */
+export function useVoiceAudio() {
+  const audioRef = useRef<HTMLAudioElement | null>(null)
+  const [playingVoice, setPlayingVoice] = useState<string | null>(null)
+
+  const toggleVoicePlay = useCallback(
+    (voiceId: string, previewUrl: string | null) => {
+      if (playingVoice === voiceId) {
+        audioRef.current?.pause()
+        audioRef.current = null
+        setPlayingVoice(null)
+        return
+      }
+      audioRef.current?.pause()
+      if (!previewUrl) {
+        message.warning("该音色暂无试听音频")
+        return
+      }
+      const audio = new Audio(previewUrl)
+      audioRef.current = audio
+      audio.play().catch(() => {
+        message.error("播放失败，请检查网络")
+      })
+      audio.onended = () => {
+        setPlayingVoice(null)
+        audioRef.current = null
+      }
+      setPlayingVoice(voiceId)
+    },
+    [playingVoice],
+  )
+
+  return { playingVoice, toggleVoicePlay }
+}

apps/web/src/pages/generate/hooks/step5-voice/useVoiceRecommend.ts

@@ -0,0 +1,68 @@
+import { useState, useCallback, useMemo } from "react"
+import { useQuery } from "@tanstack/react-query"
+import { fetchPresetVoices } from "@/api/voices"
+import type { PresetVoiceItem } from "@/api/voices"
+
+/**
+ * 智能配音推荐
+ * 根据标题内容风格模拟推荐音色
+ */
+export function useVoiceRecommend(titleText: string) {
+  const { data: presetVoicesData, isLoading: presetVoicesLoading } = useQuery({
+    queryKey: ["preset-voices"],
+    queryFn: fetchPresetVoices,
+  })
+
+  const presetVoices: PresetVoiceItem[] = useMemo(
+    () => presetVoicesData?.items ?? [],
+    [presetVoicesData],
+  )
+
+  const [voiceRecommendLoading, setVoiceRecommendLoading] = useState(false)
+  const [voiceRecommendations, setVoiceRecommendations] = useState<string[]>([])
+  const [hasVoiceRecommend, setHasVoiceRecommend] = useState(false)
+
+  const handleVoiceRecommend = useCallback(async () => {
+    if (presetVoices.length === 0) return
+    setVoiceRecommendLoading(true)
+    setHasVoiceRecommend(true)
+
+    await new Promise((resolve) => setTimeout(resolve, 1000))
+
+    const title = titleText.toLowerCase()
+    let recommended: string[] = []
+
+    const femaleVoices = presetVoices.filter((v) => v.gender === "female").map((v) => v.voice_id)
+    const maleVoices = presetVoices.filter((v) => v.gender === "male").map((v) => v.voice_id)
+    const childVoices = presetVoices.filter((v) => v.gender === "child").map((v) => v.voice_id)
+
+    if (/情感|感人|温暖|治愈|故事|回忆/.test(title)) {
+      recommended = femaleVoices.slice(0, 3)
+    } else if (/教程|知识|科普|干货|讲解|分析/.test(title)) {
+      recommended = maleVoices.slice(0, 2).concat(femaleVoices.slice(0, 1))
+    } else if (/活力|热血|运动|搞笑|有趣/.test(title)) {
+      recommended = childVoices.slice(0, 1).concat(maleVoices.slice(0, 1), femaleVoices.slice(0, 1))
+    } else {
+      recommended = presetVoices.slice(0, 3).map((v) => v.voice_id)
+    }
+
+    if (recommended.length < 3) {
+      const others = presetVoices
+        .filter((v) => !recommended.includes(v.voice_id))
+        .map((v) => v.voice_id)
+      recommended = recommended.concat(others.slice(0, 3 - recommended.length))
+    }
+
+    setVoiceRecommendations(recommended)
+    setVoiceRecommendLoading(false)
+  }, [presetVoices, titleText])
+
+  return {
+    presetVoices,
+    presetVoicesLoading,
+    voiceRecommendLoading,
+    voiceRecommendations,
+    hasVoiceRecommend,
+    handleVoiceRecommend,
+  }
+}

apps/web/src/pages/generate/hooks/useStep4Title.ts

@@ -1,251 +0,0 @@
-/**
- * Step 4 标题设置 Hook
- * 封装 AI 标题生成、标题样式设置等逻辑
- */
-import { useState, useCallback, useMemo } from "react"
-import { message } from "antd"
-import { useQuery } from "@tanstack/react-query"
-import { getTitles } from "@/api/titles"
-import { TITLE_PRESETS, AI_TITLE_TEMPLATES } from "../constants"
-import type { TitleSettings } from "../types"
-
-interface UseStep4TitleProps {
-  titleSettings: TitleSettings
-  onTitleSettingsChange: (settings: TitleSettings) => void
-}
-
-interface AiTitleItem {
-  title: string
-  highlight: string
-  style: "catchy" | "emotional" | "informative"
-}
-
-export function useStep4Title({ titleSettings, onTitleSettingsChange }: UseStep4TitleProps) {
-  /* ── 标题库 API ── */
-  const { data: userTitles = [] } = useQuery({
-    queryKey: ["titles"],
-    queryFn: () => getTitles(),
-    staleTime: 30_000,
-  })
-
-  /* ── AI 标题生成状态 ── */
-  const [aiTitleInput, setAiTitleInput] = useState("")
-  const [aiTitleGenerating, setAiTitleGenerating] = useState(false)
-  const [aiTitleResults, setAiTitleResults] = useState<AiTitleItem[]>([])
-  const [hasGeneratedTitles, setHasGeneratedTitles] = useState(false)
-
-  /* ── 辅助函数 ── */
-  const extractTopic = (text: string): string => {
-    const keywords = text
-      .replace(/[，。！？、,.!?]/g, " ")
-      .split(/\s+/)
-      .filter(Boolean)
-    if (keywords.length === 0) return "这个话题"
-    // 取前3个关键词组合
-    return keywords.slice(0, 3).join("")
-  }
-
-  const getActivePreset = (settings: TitleSettings): string | null => {
-    for (const p of TITLE_PRESETS) {
-      if (
-        settings.size === p.style.size &&
-        settings.color === p.style.color &&
-        settings.bold === p.style.bold &&
-        settings.italic === p.style.italic &&
-        settings.stroke === p.style.stroke &&
-        settings.shadow === p.style.shadow
-      ) {
-        return p.key
-      }
-    }
-    return null
-  }
-
-  const activePreset = useMemo(() => getActivePreset(titleSettings), [titleSettings])
-
-  /* ── AI 标题生成 ── */
-  const handleGenerateAiTitles = useCallback(async () => {
-    if (!aiTitleInput.trim()) {
-      message.warning("请先输入视频描述或关键词")
-      return
-    }
-    setAiTitleGenerating(true)
-    setHasGeneratedTitles(true)
-
-    // 模拟 AI 生成延迟
-    await new Promise((resolve) => setTimeout(resolve, 1200))
-
-    const topic = extractTopic(aiTitleInput)
-    const results: AiTitleItem[] = []
-
-    const styles: Array<"catchy" | "emotional" | "informative"> = [
-      "catchy",
-      "emotional",
-      "informative",
-    ]
-    styles.forEach((style) => {
-      const templates = AI_TITLE_TEMPLATES[style]
-      // 每种风格随机选2个
-      const shuffled = [...templates].sort(() => Math.random() - 0.5).slice(0, 2)
-      shuffled.forEach((tpl) => {
-        const title = tpl.replace(/\{topic\}/g, topic)
-        const highlights = {
-          catchy: "吸睛标题",
-          emotional: "情感共鸣",
-          informative: "知识干货",
-        }
-        results.push({
-          title,
-          highlight: highlights[style],
-          style,
-        })
-      })
-    })
-
-    // 打乱顺序
-    results.sort(() => Math.random() - 0.5)
-    setAiTitleResults(results)
-    setAiTitleGenerating(false)
-  }, [aiTitleInput])
-
-  const handleSelectAiTitle = useCallback(
-    (title: string) => {
-      onTitleSettingsChange({ ...titleSettings, title, aiAutoSelect: false })
-      message.success("已选用此标题")
-    },
-    [titleSettings, onTitleSettingsChange],
-  )
-
-  const handleRefreshAiTitles = useCallback(async () => {
-    if (!aiTitleInput.trim()) return
-    setAiTitleGenerating(true)
-    await new Promise((resolve) => setTimeout(resolve, 800))
-    // 重新生成一批
-    const topic = extractTopic(aiTitleInput)
-    const results: AiTitleItem[] = []
-    const styles: Array<"catchy" | "emotional" | "informative"> = [
-      "catchy",
-      "emotional",
-      "informative",
-    ]
-    const highlights = { catchy: "吸睛标题", emotional: "情感共鸣", informative: "知识干货" }
-    styles.forEach((style) => {
-      const templates = AI_TITLE_TEMPLATES[style]
-      const shuffled = [...templates].sort(() => Math.random() - 0.5).slice(0, 2)
-      shuffled.forEach((tpl) => {
-        results.push({
-          title: tpl.replace(/\{topic\}/g, topic),
-          highlight: highlights[style],
-          style,
-        })
-      })
-    })
-    results.sort(() => Math.random() - 0.5)
-    setAiTitleResults(results)
-    setAiTitleGenerating(false)
-  }, [aiTitleInput])
-
-  /* ── 标题设置更新 ── */
-  const updateTitle = useCallback(
-    (title: string) => {
-      onTitleSettingsChange({ ...titleSettings, title })
-    },
-    [titleSettings, onTitleSettingsChange],
-  )
-
-  const toggleAiAutoSelect = useCallback(() => {
-    onTitleSettingsChange({ ...titleSettings, aiAutoSelect: !titleSettings.aiAutoSelect })
-  }, [titleSettings, onTitleSettingsChange])
-
-  const updatePosition = useCallback(
-    (position: string) => {
-      onTitleSettingsChange({ ...titleSettings, position })
-    },
-    [titleSettings, onTitleSettingsChange],
-  )
-
-  const updateFont = useCallback(
-    (font: string) => {
-      onTitleSettingsChange({ ...titleSettings, font })
-    },
-    [titleSettings, onTitleSettingsChange],
-  )
-
-  const updateSize = useCallback(
-    (size: number) => {
-      onTitleSettingsChange({ ...titleSettings, size })
-    },
-    [titleSettings, onTitleSettingsChange],
-  )
-
-  const updateColor = useCallback(
-    (color: string) => {
-      onTitleSettingsChange({ ...titleSettings, color })
-    },
-    [titleSettings, onTitleSettingsChange],
-  )
-
-  const toggleBold = useCallback(() => {
-    onTitleSettingsChange({ ...titleSettings, bold: !titleSettings.bold })
-  }, [titleSettings, onTitleSettingsChange])
-
-  const toggleItalic = useCallback(() => {
-    onTitleSettingsChange({ ...titleSettings, italic: !titleSettings.italic })
-  }, [titleSettings, onTitleSettingsChange])
-
-  const toggleStroke = useCallback(() => {
-    onTitleSettingsChange({ ...titleSettings, stroke: !titleSettings.stroke })
-  }, [titleSettings, onTitleSettingsChange])
-
-  const toggleShadow = useCallback(() => {
-    onTitleSettingsChange({ ...titleSettings, shadow: !titleSettings.shadow })
-  }, [titleSettings, onTitleSettingsChange])
-
-  const applyPreset = useCallback(
-    (presetKey: string) => {
-      const preset = TITLE_PRESETS.find((p) => p.key === presetKey)
-      if (!preset) return
-      onTitleSettingsChange({
-        ...titleSettings,
-        size: preset.style.size,
-        color: preset.style.color,
-        bold: preset.style.bold,
-        italic: preset.style.italic,
-        stroke: preset.style.stroke,
-        shadow: preset.style.shadow,
-      })
-    },
-    [titleSettings, onTitleSettingsChange],
-  )
-
-  return {
-    // 数据
-    userTitles,
-    titleSettings,
-    aiTitleInput,
-    setAiTitleInput,
-    aiTitleGenerating,
-    aiTitleResults,
-    hasGeneratedTitles,
-    activePreset,
-    titlePresets: TITLE_PRESETS,
-    // AI 标题操作
-    handleGenerateAiTitles,
-    handleSelectAiTitle,
-    handleRefreshAiTitles,
-    // 标题设置操作
-    updateTitle,
-    toggleAiAutoSelect,
-    updatePosition,
-    updateFont,
-    updateSize,
-    updateColor,
-    toggleBold,
-    toggleItalic,
-    toggleStroke,
-    toggleShadow,
-    applyPreset,
-  }
-}
-
-export default useStep4Title

apps/web/src/pages/generate/hooks/useStep4Title/index.ts

@@ -0,0 +1,61 @@
+import { useQuery } from "@tanstack/react-query"
+import { getTitles } from "@/api/titles"
+import type { TitleSettings } from "../../types"
+import { useAiTitleGenerator } from "./useAiTitleGenerator"
+import { useTitleStyleUpdaters } from "./useTitleStyleUpdaters"
+
+interface UseStep4TitleProps {
+  titleSettings: TitleSettings
+  onTitleSettingsChange: (settings: TitleSettings) => void
+}
+
+/**
+ * Step 4 标题设置 Hook
+ * 封装 AI 标题生成、标题样式设置等逻辑
+ */
+export function useStep4Title({ titleSettings, onTitleSettingsChange }: UseStep4TitleProps) {
+  // 标题库数据
+  const { data: userTitles = [] } = useQuery({
+    queryKey: ["titles"],
+    queryFn: () => getTitles(),
+    staleTime: 30_000,
+  })
+
+  // AI 标题生成
+  const aiGenerator = useAiTitleGenerator({ titleSettings, onTitleSettingsChange })
+
+  // 样式更新
+  const styleUpdaters = useTitleStyleUpdaters({ titleSettings, onTitleSettingsChange })
+
+  return {
+    // 数据
+    userTitles,
+    titleSettings,
+    // AI 标题状态
+    aiTitleInput: aiGenerator.aiTitleInput,
+    setAiTitleInput: aiGenerator.setAiTitleInput,
+    aiTitleGenerating: aiGenerator.aiTitleGenerating,
+    aiTitleResults: aiGenerator.aiTitleResults,
+    hasGeneratedTitles: aiGenerator.hasGeneratedTitles,
+    activePreset: styleUpdaters.activePreset,
+    titlePresets: styleUpdaters.titlePresets,
+    // AI 标题操作
+    handleGenerateAiTitles: aiGenerator.handleGenerateAiTitles,
+    handleSelectAiTitle: aiGenerator.handleSelectAiTitle,
+    handleRefreshAiTitles: aiGenerator.handleRefreshAiTitles,
+    // 标题设置操作
+    updateTitle: styleUpdaters.updateTitle,
+    toggleAiAutoSelect: styleUpdaters.toggleAiAutoSelect,
+    updatePosition: styleUpdaters.updatePosition,
+    updateFont: styleUpdaters.updateFont,
+    updateSize: styleUpdaters.updateSize,
+    updateColor: styleUpdaters.updateColor,
+    toggleBold: styleUpdaters.toggleBold,
+    toggleItalic: styleUpdaters.toggleItalic,
+    toggleStroke: styleUpdaters.toggleStroke,
+    toggleShadow: styleUpdaters.toggleShadow,
+    applyPreset: styleUpdaters.applyPreset,
+  }
+}
+
+export default useStep4Title

apps/web/src/pages/generate/hooks/useStep4Title/useAiTitleGenerator.ts

@@ -0,0 +1,102 @@
+import { useState, useCallback } from "react"
+import { message } from "antd"
+import { AI_TITLE_TEMPLATES } from "../../constants"
+import type { TitleSettings } from "../../types"
+
+export interface AiTitleItem {
+  title: string
+  highlight: string
+  style: "catchy" | "emotional" | "informative"
+}
+
+interface UseAiTitleGeneratorOptions {
+  titleSettings: TitleSettings
+  onTitleSettingsChange: (settings: TitleSettings) => void
+}
+
+/**
+ * AI 标题生成 Hook
+ * 封装 AI 标题生成、刷新、选择等逻辑
+ */
+export function useAiTitleGenerator({
+  titleSettings,
+  onTitleSettingsChange,
+}: UseAiTitleGeneratorOptions) {
+  const [aiTitleInput, setAiTitleInput] = useState("")
+  const [aiTitleGenerating, setAiTitleGenerating] = useState(false)
+  const [aiTitleResults, setAiTitleResults] = useState<AiTitleItem[]>([])
+  const [hasGeneratedTitles, setHasGeneratedTitles] = useState(false)
+
+  const extractTopic = (text: string): string => {
+    const keywords = text
+      .replace(/[，。！？、,.!?]/g, " ")
+      .split(/\s+/)
+      .filter(Boolean)
+    if (keywords.length === 0) return "这个话题"
+    return keywords.slice(0, 3).join("")
+  }
+
+  const generateTitlesFromTopic = (topic: string): AiTitleItem[] => {
+    const results: AiTitleItem[] = []
+    const styles: Array<"catchy" | "emotional" | "informative"> = [
+      "catchy",
+      "emotional",
+      "informative",
+    ]
+    const highlights = { catchy: "吸睛标题", emotional: "情感共鸣", informative: "知识干货" }
+    styles.forEach((style) => {
+      const templates = AI_TITLE_TEMPLATES[style]
+      const shuffled = [...templates].sort(() => Math.random() - 0.5).slice(0, 2)
+      shuffled.forEach((tpl) => {
+        results.push({
+          title: tpl.replace(/\{topic\}/g, topic),
+          highlight: highlights[style],
+          style,
+        })
+      })
+    })
+    results.sort(() => Math.random() - 0.5)
+    return results
+  }
+
+  const handleGenerateAiTitles = useCallback(async () => {
+    if (!aiTitleInput.trim()) {
+      message.warning("请先输入视频描述或关键词")
+      return
+    }
+    setAiTitleGenerating(true)
+    setHasGeneratedTitles(true)
+    await new Promise((resolve) => setTimeout(resolve, 1200))
+    const topic = extractTopic(aiTitleInput)
+    setAiTitleResults(generateTitlesFromTopic(topic))
+    setAiTitleGenerating(false)
+  }, [aiTitleInput])
+
+  const handleSelectAiTitle = useCallback(
+    (title: string) => {
+      onTitleSettingsChange({ ...titleSettings, title, aiAutoSelect: false })
+      message.success("已选用此标题")
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  const handleRefreshAiTitles = useCallback(async () => {
+    if (!aiTitleInput.trim()) return
+    setAiTitleGenerating(true)
+    await new Promise((resolve) => setTimeout(resolve, 800))
+    const topic = extractTopic(aiTitleInput)
+    setAiTitleResults(generateTitlesFromTopic(topic))
+    setAiTitleGenerating(false)
+  }, [aiTitleInput])
+
+  return {
+    aiTitleInput,
+    setAiTitleInput,
+    aiTitleGenerating,
+    aiTitleResults,
+    hasGeneratedTitles,
+    handleGenerateAiTitles,
+    handleSelectAiTitle,
+    handleRefreshAiTitles,
+  }
+}

apps/web/src/pages/generate/hooks/useStep4Title/useTitleStyleUpdaters.ts

@@ -0,0 +1,123 @@
+import { useCallback, useMemo } from "react"
+import { TITLE_PRESETS } from "../../constants"
+import type { TitleSettings } from "../../types"
+
+interface UseTitleStyleUpdatersOptions {
+  titleSettings: TitleSettings
+  onTitleSettingsChange: (settings: TitleSettings) => void
+}
+
+/**
+ * 标题样式更新 Hook
+ * 封装标题文字、位置、字体、样式等所有设置更新函数
+ */
+export function useTitleStyleUpdaters({
+  titleSettings,
+  onTitleSettingsChange,
+}: UseTitleStyleUpdatersOptions) {
+  const getActivePreset = (settings: TitleSettings): string | null => {
+    for (const p of TITLE_PRESETS) {
+      if (
+        settings.size === p.style.size &&
+        settings.color === p.style.color &&
+        settings.bold === p.style.bold &&
+        settings.italic === p.style.italic &&
+        settings.stroke === p.style.stroke &&
+        settings.shadow === p.style.shadow
+      ) {
+        return p.key
+      }
+    }
+    return null
+  }
+
+  const activePreset = useMemo(() => getActivePreset(titleSettings), [titleSettings])
+
+  const updateTitle = useCallback(
+    (title: string) => {
+      onTitleSettingsChange({ ...titleSettings, title })
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  const toggleAiAutoSelect = useCallback(() => {
+    onTitleSettingsChange({ ...titleSettings, aiAutoSelect: !titleSettings.aiAutoSelect })
+  }, [titleSettings, onTitleSettingsChange])
+
+  const updatePosition = useCallback(
+    (position: string) => {
+      onTitleSettingsChange({ ...titleSettings, position })
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  const updateFont = useCallback(
+    (font: string) => {
+      onTitleSettingsChange({ ...titleSettings, font })
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  const updateSize = useCallback(
+    (size: number) => {
+      onTitleSettingsChange({ ...titleSettings, size })
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  const updateColor = useCallback(
+    (color: string) => {
+      onTitleSettingsChange({ ...titleSettings, color })
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  const toggleBold = useCallback(() => {
+    onTitleSettingsChange({ ...titleSettings, bold: !titleSettings.bold })
+  }, [titleSettings, onTitleSettingsChange])
+
+  const toggleItalic = useCallback(() => {
+    onTitleSettingsChange({ ...titleSettings, italic: !titleSettings.italic })
+  }, [titleSettings, onTitleSettingsChange])
+
+  const toggleStroke = useCallback(() => {
+    onTitleSettingsChange({ ...titleSettings, stroke: !titleSettings.stroke })
+  }, [titleSettings, onTitleSettingsChange])
+
+  const toggleShadow = useCallback(() => {
+    onTitleSettingsChange({ ...titleSettings, shadow: !titleSettings.shadow })
+  }, [titleSettings, onTitleSettingsChange])
+
+  const applyPreset = useCallback(
+    (presetKey: string) => {
+      const preset = TITLE_PRESETS.find((p) => p.key === presetKey)
+      if (!preset) return
+      onTitleSettingsChange({
+        ...titleSettings,
+        size: preset.style.size,
+        color: preset.style.color,
+        bold: preset.style.bold,
+        italic: preset.style.italic,
+        stroke: preset.style.stroke,
+        shadow: preset.style.shadow,
+      })
+    },
+    [titleSettings, onTitleSettingsChange],
+  )
+
+  return {
+    activePreset,
+    titlePresets: TITLE_PRESETS,
+    updateTitle,
+    toggleAiAutoSelect,
+    updatePosition,
+    updateFont,
+    updateSize,
+    updateColor,
+    toggleBold,
+    toggleItalic,
+    toggleStroke,
+    toggleShadow,
+    applyPreset,
+  }
+}

apps/web/src/pages/generate/hooks/useStep5Voice.tsx

@@ -2,17 +2,15 @@
  * Step 5 配音选择 Hook
  * 封装 AI 推荐、预设音色试听、TTS 自定义合成、存为素材等逻辑
  */
-import { useState, useRef, useCallback, useEffect, useMemo } from "react"
-import { useNavigate } from "react-router-dom"
-import { message } from "antd"
-import { useQuery, useMutation } from "@tanstack/react-query"
-import type { PresetVoiceItem } from "@/api/voices"
-import { fetchPresetVoices } from "@/api/voices"
-import { synthesizeSpeech, getTTSJobStatus, saveTtsToLibrary } from "@/api/tts"
-import { getTags, createTag } from "@/api/tags"
-import { formatDuration } from "../utils/formatDuration"
+import { useCallback } from "react"
 import type { VoiceClone } from "@/api/voice-clone"
+import { message } from "antd"
 import { VOICE_GENDER_ICON, CLONE_STATUS_CONFIG } from "../constants"
+import { formatDuration } from "../utils/formatDuration"
+import { useVoiceAudio } from "./step5-voice/useVoiceAudio"
+import { useVoiceRecommend } from "./step5-voice/useVoiceRecommend"
+import { useTtsSynthesis } from "./step5-voice/useTtsSynthesis"
+import { useSaveToLibrary } from "./step5-voice/useSaveToLibrary"
 
 interface UseStep5VoiceProps {
   selectedVoice: string
@@ -43,91 +41,47 @@ export function useStep5Voice({
   onCloneModalOpenChange,
   titleText,
 }: UseStep5VoiceProps) {
-  const navigate = useNavigate()
-  /* ── 预置音色 API ── */
-  const { data: presetVoicesData, isLoading: presetVoicesLoading } = useQuery({
-    queryKey: ["preset-voices"],
-    queryFn: fetchPresetVoices,
-  })
-  const presetVoices: PresetVoiceItem[] = useMemo(
-    () => presetVoicesData?.items ?? [],
-    [presetVoicesData],
-  )
+  /* ── 子模块 ── */
+  const { playingVoice, toggleVoicePlay } = useVoiceAudio()
 
-  /* ── 音频播放 ── */
-  const audioRef = useRef<HTMLAudioElement | null>(null)
-  const [playingVoice, setPlayingVoice] = useState<string | null>(null)
+  const {
+    presetVoices,
+    presetVoicesLoading,
+    voiceRecommendLoading,
+    voiceRecommendations,
+    hasVoiceRecommend,
+    handleVoiceRecommend,
+  } = useVoiceRecommend(titleText)
 
-  const toggleVoicePlay = useCallback(
-    (voiceId: string, previewUrl: string | null) => {
-      if (playingVoice === voiceId) {
-        audioRef.current?.pause()
-        audioRef.current = null
-        setPlayingVoice(null)
-        return
-      }
-      audioRef.current?.pause()
-      if (!previewUrl) {
-        message.warning("该音色暂无试听音频")
-        return
-      }
-      const audio = new Audio(previewUrl)
-      audioRef.current = audio
-      audio.play().catch(() => {
-        message.error("播放失败，请检查网络")
-      })
-      audio.onended = () => {
-        setPlayingVoice(null)
-        audioRef.current = null
-      }
-      setPlayingVoice(voiceId)
-    },
-    [playingVoice],
-  )
+  const {
+    customVoiceText,
+    setCustomVoiceText,
+    customAudioUrl,
+    ttsError,
+    ttsJobId,
+    completedTtsJobId,
+    synthesizeMutation,
+    handleSynthesizeVoice,
+    resetTtsState,
+  } = useTtsSynthesis(selectedVoice)
 
-  /* ── 智能配音推荐 ── */
-  const [voiceRecommendLoading, setVoiceRecommendLoading] = useState(false)
-  const [voiceRecommendations, setVoiceRecommendations] = useState<string[]>([])
-  const [hasVoiceRecommend, setHasVoiceRecommend] = useState(false)
-
-  const handleVoiceRecommend = useCallback(async () => {
-    if (presetVoices.length === 0) return
-    setVoiceRecommendLoading(true)
-    setHasVoiceRecommend(true)
-
-    await new Promise((resolve) => setTimeout(resolve, 1000))
-
-    // 根据标题内容风格模拟推荐：情感类→温柔女声，知识类→沉稳男声，活力类→阳光少年
-    const title = titleText.toLowerCase()
-    let recommended: string[] = []
-
-    const femaleVoices = presetVoices.filter((v) => v.gender === "female").map((v) => v.voice_id)
-    const maleVoices = presetVoices.filter((v) => v.gender === "male").map((v) => v.voice_id)
-    const childVoices = presetVoices.filter((v) => v.gender === "child").map((v) => v.voice_id)
-
-    if (/情感|感人|温暖|治愈|故事|回忆/.test(title)) {
-      recommended = femaleVoices.slice(0, 3)
-    } else if (/教程|知识|科普|干货|讲解|分析/.test(title)) {
-      recommended = maleVoices.slice(0, 2).concat(femaleVoices.slice(0, 1))
-    } else if (/活力|热血|运动|搞笑|有趣/.test(title)) {
-      recommended = childVoices.slice(0, 1).concat(maleVoices.slice(0, 1), femaleVoices.slice(0, 1))
-    } else {
-      // 默认推荐前3个
-      recommended = presetVoices.slice(0, 3).map((v) => v.voice_id)
-    }
-
-    // 不足3个时补足
-    if (recommended.length < 3) {
-      const others = presetVoices
-        .filter((v) => !recommended.includes(v.voice_id))
-        .map((v) => v.voice_id)
-      recommended = recommended.concat(others.slice(0, 3 - recommended.length))
-    }
-
-    setVoiceRecommendations(recommended)
-    setVoiceRecommendLoading(false)
-  }, [presetVoices, titleText])
+  const {
+    saveModalOpen,
+    setSaveModalOpen,
+    saveName,
+    setSaveName,
+    saveTagIds,
+    setSaveTagIds,
+    saveNewTag,
+    setSaveNewTag,
+    allTags,
+    saveToLibraryMutation,
+    handleOpenSaveModal,
+    handleConfirmSave,
+    handleAddTagInModal,
+  } = useSaveToLibrary(completedTtsJobId, resetTtsState)
 
+  /* ── 推荐音色选择 ── */
   const handleSelectRecommendedVoice = useCallback(
     (voiceId: string) => {
       onVoiceModeChange("preset")
@@ -136,173 +90,6 @@ export function useStep5Voice({
     [onVoiceModeChange, onSelectedVoiceChange],
   )
 
-  /* ── TTS 自定义合成状态 ── */
-  const [customVoiceText, setCustomVoiceText] = useState("")
-  const [customAudioUrl, setCustomAudioUrl] = useState<string | null>(null)
-  const [ttsError, setTtsError] = useState<string | null>(null)
-  const [ttsJobId, setTtsJobId] = useState<string | null>(null)
-  /** 合成完成后保留的 job ID，用于"存为素材" */
-  const [completedTtsJobId, setCompletedTtsJobId] = useState<string | null>(null)
-
-  /* ── TTS mutation ── */
-  const synthesizeMutation = useMutation({
-    mutationFn: synthesizeSpeech,
-    onSuccess: (data) => {
-      setTtsJobId(data.job_id)
-      message.info("语音合成已提交，等待处理…")
-    },
-    onError: () => {
-      setTtsError("语音合成请求失败，请重试")
-    },
-  })
-
-  /** 轮询 TTS 任务状态 */
-  useEffect(() => {
-    if (!ttsJobId) return
-    let cancelled = false
-    let timer: ReturnType<typeof setTimeout>
-
-    const poll = async () => {
-      try {
-        const status = await getTTSJobStatus(ttsJobId)
-        if (cancelled) return
-        if (status.status === "completed") {
-          setCustomAudioUrl(status.output_audio_url)
-          setCompletedTtsJobId(ttsJobId)
-          setTtsJobId(null)
-          setTtsError(null)
-          message.success("语音合成完成！")
-          return
-        }
-        if (status.status === "failed" || status.status === "cancelled") {
-          setTtsError(status.error_message || "语音合成失败")
-          setTtsJobId(null)
-          return
-        }
-        timer = setTimeout(poll, 2000)
-      } catch {
-        if (!cancelled) {
-          setTtsError("查询合成状态失败")
-          setTtsJobId(null)
-        }
-      }
-    }
-
-    timer = setTimeout(poll, 2000)
-    return () => {
-      cancelled = true
-      clearTimeout(timer)
-    }
-  }, [ttsJobId])
-
-  /** 触发自定义文本 TTS 合成 */
-  const handleSynthesizeVoice = useCallback(() => {
-    if (!customVoiceText.trim()) {
-      message.warning("请先输入配音文案")
-      return
-    }
-    setTtsError(null)
-    setCustomAudioUrl(null)
-    synthesizeMutation.mutate({
-      text: customVoiceText.trim(),
-      voice_id: selectedVoice || undefined,
-      language: "zh-CN",
-    })
-  }, [customVoiceText, selectedVoice, synthesizeMutation])
-
-  /* ── 存为素材弹窗状态 ── */
-  const [saveModalOpen, setSaveModalOpen] = useState(false)
-  const [saveName, setSaveName] = useState("")
-  const [saveTagIds, setSaveTagIds] = useState<string[]>([])
-  const [saveNewTag, setSaveNewTag] = useState("")
-
-  /* ── 标签列表（用于存为素材弹窗） ── */
-  const { data: allTags = [] } = useQuery({
-    queryKey: ["generate-save-tags"],
-    queryFn: getTags,
-    staleTime: 30_000,
-  })
-
-  /* ── 存为素材 mutation ── */
-  const saveToLibraryMutation = useMutation({
-    mutationFn: (params: { name?: string; tag_ids?: string[] }) =>
-      saveTtsToLibrary(completedTtsJobId!, params),
-    onSuccess: () => {
-      message.success({
-        content: (
-          <span>
-            已保存到配音库！{" "}
-            <a
-              onClick={handleGoToLibrary}
-              style={{
-                color: "var(--primary-500, #6366f1)",
-                cursor: "pointer",
-              }}
-            >
-              去视频库查看
-            </a>
-          </span>
-        ),
-        duration: 5,
-      })
-      setSaveModalOpen(false)
-      setSaveName("")
-      setSaveTagIds([])
-      setSaveNewTag("")
-      setCompletedTtsJobId(null)
-      setCustomAudioUrl(null)
-    },
-    onError: (err: Error) => {
-      message.error(`保存失败：${err.message || "请重试"}`)
-    },
-  })
-
-  /** 打开存为素材弹窗 */
-  const handleOpenSaveModal = useCallback(() => {
-    setSaveName("")
-    setSaveTagIds([])
-    setSaveNewTag("")
-    setSaveModalOpen(true)
-  }, [])
-
-  /** 确认保存 */
-  const handleConfirmSave = useCallback(() => {
-    if (!completedTtsJobId) return
-    saveToLibraryMutation.mutate({
-      name: saveName.trim() || undefined,
-      tag_ids: saveTagIds.length > 0 ? saveTagIds : undefined,
-    })
-  }, [completedTtsJobId, saveName, saveTagIds, saveToLibraryMutation])
-
-  /** 在弹窗中新增标签（先创建再选中） */
-  const handleAddTagInModal = useCallback(
-    async (tagName: string) => {
-      const trimmed = tagName.trim()
-      if (!trimmed) return
-      /* 已在选中列表则跳过 */
-      const existing = allTags.find((t) => t.name === trimmed)
-      if (existing) {
-        if (!saveTagIds.includes(existing.id)) {
-          setSaveTagIds((prev) => [...prev, existing.id])
-        }
-        return
-      }
-      try {
-        const created = await createTag(trimmed)
-        setSaveTagIds((prev) => [...prev, created.id])
-        setSaveNewTag("")
-      } catch {
-        message.error(`创建标签"${trimmed}"失败`)
-      }
-    },
-    [allTags, saveTagIds],
-  )
-
-  /** 保存成功后跳转到视频库 */
-  const handleGoToLibrary = useCallback(() => {
-    navigate("/app/voice-materials")
-  }, [navigate])
-
   /* ── 克隆成功回调 ── */
   const handleCloneSuccess = useCallback(
     (voice: VoiceClone) => {

apps/web/src/pages/home/HomePage.tsx

@@ -8,249 +8,15 @@
  */
 import React from "react"
 import { useNavigate } from "react-router-dom"
-import { Button } from "@/components/ui"
 import { useAuthStore } from "@/store/authStore"
+import { NavBar, Footer } from "./sections/Layout"
+import { HeroSection } from "./sections/HeroSection"
+import { FeatureSection } from "./sections/FeatureSection"
+import { WorkflowSection } from "./sections/WorkflowSection"
+import { PricingSection } from "./sections/PricingSection"
+import { CTASection } from "./sections/CTASection"
 import "./home-page.css"
 
-/* ── HeroSection ─────────────────────────────────────────── */
-
-const HeroSection: React.FC = () => {
-  const navigate = useNavigate()
-
-  return (
-    <section className="hp-hero">
-      <div className="hp-hero-inner">
-        {/* 左侧文案 */}
-        <div className="hp-hero-content">
-          <span className="hp-hero-tag">🦐 小虾智剪 · AI智能视频创作平台</span>
-          <h1 className="hp-hero-title">
-            上传素材，AI自动剪辑
-            <br />
-            智能剪辑短视频
-          </h1>
-          <p className="hp-hero-desc">
-            基于先进的 AI 技术，自动识别视频亮点，智能剪辑、配音、加字幕。 30
-            秒内将长视频转化为适合各平台传播的精品短视频。
-          </p>
-          <div className="hp-hero-actions">
-            <Button buttonType="primary" buttonSize="lg" onClick={() => navigate("/register")}>
-              立即免费开始
-            </Button>
-            <Button buttonType="secondary" buttonSize="lg" onClick={() => navigate("/pricing")}>
-              查看定价方案
-            </Button>
-          </div>
-        </div>
-
-        {/* 右侧视觉 */}
-        <div className="hp-hero-visual">
-          <div className="hp-hero-video">
-            <div className="hp-hero-video-inner">
-              <span className="hp-hero-video-placeholder">🎬</span>
-            </div>
-            <button className="hp-hero-play" type="button" aria-label="播放演示视频">
-              ▶
-            </button>
-          </div>
-          <div className="hp-hero-info">
-            <div className="hp-hero-badges">
-              <span className="hp-hero-badge">✨ AI智能剪辑</span>
-              <span className="hp-hero-badge">⚡ 30秒生成</span>
-            </div>
-            <span className="hp-hero-pill">可发布</span>
-          </div>
-        </div>
-      </div>
-    </section>
-  )
-}
-
-/* ── FeatureSection ──────────────────────────────────────── */
-
-const FEATURES = [
-  {
-    icon: "🤖",
-    title: "AI 智能剪辑",
-    desc: "自动识别视频高光片段，智能去除冗余内容，智能剪辑精彩短视频。",
-  },
-  {
-    icon: "🎙️",
-    title: "AI 配音克隆",
-    desc: "克隆您的声音，支持多种音色风格，自动生成自然流畅的配音。",
-  },
-  {
-    icon: "📝",
-    title: "智能字幕标题",
-    desc: "自动语音识别生成精准字幕，AI 创作吸睛标题，提升内容传播力。",
-  },
-  {
-    icon: "📱",
-    title: "多平台一键发布",
-    desc: "支持抖音、快手、小红书、微信视频号等主流平台，一键同步发布。",
-  },
-]
-
-const FeatureSection: React.FC = () => {
-  return (
-    <section className="hp-features">
-      <div className="hp-section-inner">
-        <h2 className="hp-section-title">核心功能</h2>
-        <p className="hp-section-desc">从素材上传到视频发布，全流程 AI 赋能，让短视频创作更简单</p>
-        <div className="hp-feature-grid">
-          {FEATURES.map((f) => (
-            <div key={f.title} className="hp-feature-card">
-              <div className="hp-feature-icon">{f.icon}</div>
-              <h3 className="hp-feature-title">{f.title}</h3>
-              <p className="hp-feature-desc">{f.desc}</p>
-            </div>
-          ))}
-        </div>
-      </div>
-    </section>
-  )
-}
-
-/* ── WorkflowSection ─────────────────────────────────────── */
-
-const STEPS = [
-  { icon: "📤", title: "上传素材", desc: "拖拽或选择视频素材，支持批量上传" },
-  { icon: "🧠", title: "AI 处理", desc: "AI 自动分析、剪辑、配音、加字幕" },
-  { icon: "👀", title: "预览调整", desc: "在线预览生成结果，支持微调编辑" },
-  { icon: "🚀", title: "一键发布", desc: "多平台同步发布，追踪数据表现" },
-]
-
-const WorkflowSection: React.FC = () => {
-  return (
-    <section className="hp-workflow">
-      <div className="hp-section-inner">
-        <h2 className="hp-section-title">工作流程</h2>
-        <p className="hp-section-desc">四步完成短视频创作，从素材到发布仅需 30 秒</p>
-        <div className="hp-step-grid">
-          {STEPS.map((step, idx) => (
-            <div key={step.title} className="hp-step-card">
-              <div className="hp-step-number">{idx + 1}</div>
-              <div className="hp-step-icon">{step.icon}</div>
-              <h3 className="hp-step-title">{step.title}</h3>
-              <p className="hp-step-desc">{step.desc}</p>
-              {idx < STEPS.length - 1 && <div className="hp-step-arrow">→</div>}
-            </div>
-          ))}
-        </div>
-      </div>
-    </section>
-  )
-}
-
-/* ── PricingSection ──────────────────────────────────────── */
-
-const PLANS = [
-  {
-    name: "基础版",
-    price: "免费",
-    period: "",
-    desc: "适合个人体验，快速上手",
-    features: ["每月 5 次 AI 生成", "720p 视频导出", "基础模板库", "1 个平台账号绑定"],
-    highlighted: false,
-    cta: "免费开始",
-  },
-  {
-    name: "专业版",
-    price: "¥99",
-    period: "/月",
-    desc: "适合内容创作者，高效产出",
-    features: [
-      "每月 100 次 AI 生成",
-      "1080p 视频导出",
-      "全部模板库",
-      "4 个平台账号绑定",
-      "AI 配音克隆",
-      "优先客服支持",
-    ],
-    highlighted: true,
-    cta: "立即订阅",
-  },
-  {
-    name: "企业版",
-    price: "¥399",
-    period: "/月",
-    desc: "适合团队与企业，规模化运营",
-    features: [
-      "无限次 AI 生成",
-      "4K 视频导出",
-      "全部模板 + 定制模板",
-      "无限平台账号绑定",
-      "团队协作管理",
-      "API 接入支持",
-      "专属客户经理",
-    ],
-    highlighted: false,
-    cta: "联系销售",
-  },
-]
-
-const PricingSection: React.FC = () => {
-  const navigate = useNavigate()
-
-  return (
-    <section className="hp-pricing">
-      <div className="hp-section-inner">
-        <h2 className="hp-section-title">定价方案</h2>
-        <p className="hp-section-desc">选择适合您的方案，随时升级或取消</p>
-        <div className="hp-pricing-grid">
-          {PLANS.map((plan) => (
-            <div
-              key={plan.name}
-              className={`hp-pricing-card${plan.highlighted ? " hp-pricing-card--highlight" : ""}`}
-            >
-              {plan.highlighted && <div className="hp-pricing-badge">推荐</div>}
-              <h3 className="hp-pricing-name">{plan.name}</h3>
-              <div className="hp-pricing-price">
-                {plan.price}
-                {plan.period && <span className="hp-pricing-period">{plan.period}</span>}
-              </div>
-              <p className="hp-pricing-desc">{plan.desc}</p>
-              <ul className="hp-pricing-features">
-                {plan.features.map((f) => (
-                  <li key={f}>
-                    <span className="hp-pricing-check">✓</span>
-                    {f}
-                  </li>
-                ))}
-              </ul>
-              <Button
-                buttonType={plan.highlighted ? "primary" : "secondary"}
-                onClick={() => navigate("/register")}
-              >
-                {plan.cta}
-              </Button>
-            </div>
-          ))}
-        </div>
-      </div>
-    </section>
-  )
-}
-
-/* ── CTASection ──────────────────────────────────────────── */
-
-const CTASection: React.FC = () => {
-  const navigate = useNavigate()
-
-  return (
-    <section className="hp-cta">
-      <div className="hp-cta-inner">
-        <h2 className="hp-cta-title">开始用 AI 创作短视频</h2>
-        <p className="hp-cta-desc">免费注册，立即体验 AI 智能视频创作。无需信用卡，零风险上手。</p>
-        <Button buttonType="primary" buttonSize="lg" onClick={() => navigate("/register")}>
-          免费注册
-        </Button>
-      </div>
-    </section>
-  )
-}
-
-/* ── 主页面 ─────────────────────────────────────────────── */
-
 const HomePage: React.FC = () => {
   const isAuthenticated = useAuthStore((state) => state.isAuthenticated)
   const navigate = useNavigate()
@@ -264,35 +30,13 @@ const HomePage: React.FC = () => {
 
   return (
     <div className="hp-page">
-      {/* 顶部导航栏 */}
-      <header className="hp-nav">
-        <div className="hp-nav-inner">
-          <button className="hp-nav-brand" type="button" onClick={() => navigate("/")}>
-            <span className="hp-nav-logo">🦐</span>
-            <span className="hp-nav-brand-text">小虾智剪</span>
-          </button>
-          <div className="hp-nav-actions">
-            <Button buttonType="ghost" buttonSize="sm" onClick={() => navigate("/login")}>
-              登录
-            </Button>
-            <Button buttonType="primary" buttonSize="sm" onClick={() => navigate("/register")}>
-              免费注册
-            </Button>
-          </div>
-        </div>
-      </header>
-
-      {/* 5 个区域 */}
+      <NavBar />
       <HeroSection />
       <FeatureSection />
       <WorkflowSection />
       <PricingSection />
       <CTASection />
-
-      {/* 底部 */}
-      <footer className="hp-footer">
-        <p>© 2026 小虾智剪 · AI智能视频创作平台</p>
-      </footer>
+      <Footer />
     </div>
   )
 }

apps/web/src/pages/home/sections/CTASection.tsx

@@ -0,0 +1,20 @@
+import React from "react"
+import { useNavigate } from "react-router-dom"
+import { Button } from "@/components/ui"
+
+/** CTA 行动号召区域 */
+export const CTASection: React.FC = () => {
+  const navigate = useNavigate()
+
+  return (
+    <section className="hp-cta">
+      <div className="hp-cta-inner">
+        <h2 className="hp-cta-title">开始用 AI 创作短视频</h2>
+        <p className="hp-cta-desc">免费注册，立即体验 AI 智能视频创作。无需信用卡，零风险上手。</p>
+        <Button buttonType="primary" buttonSize="lg" onClick={() => navigate("/register")}>
+          免费注册
+        </Button>
+      </div>
+    </section>
+  )
+}

apps/web/src/pages/home/sections/FeatureSection.tsx

@@ -0,0 +1,45 @@
+import React from "react"
+
+const FEATURES = [
+  {
+    icon: "🤖",
+    title: "AI 智能剪辑",
+    desc: "自动识别视频高光片段，智能去除冗余内容，智能剪辑精彩短视频。",
+  },
+  {
+    icon: "🎙️",
+    title: "AI 配音克隆",
+    desc: "克隆您的声音，支持多种音色风格，自动生成自然流畅的配音。",
+  },
+  {
+    icon: "📝",
+    title: "智能字幕标题",
+    desc: "自动语音识别生成精准字幕，AI 创作吸睛标题，提升内容传播力。",
+  },
+  {
+    icon: "📱",
+    title: "多平台一键发布",
+    desc: "支持抖音、快手、小红书、微信视频号等主流平台，一键同步发布。",
+  },
+]
+
+/** 核心功能区域 */
+export const FeatureSection: React.FC = () => {
+  return (
+    <section className="hp-features">
+      <div className="hp-section-inner">
+        <h2 className="hp-section-title">核心功能</h2>
+        <p className="hp-section-desc">从素材上传到视频发布，全流程 AI 赋能，让短视频创作更简单</p>
+        <div className="hp-feature-grid">
+          {FEATURES.map((f) => (
+            <div key={f.title} className="hp-feature-card">
+              <div className="hp-feature-icon">{f.icon}</div>
+              <h3 className="hp-feature-title">{f.title}</h3>
+              <p className="hp-feature-desc">{f.desc}</p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  )
+}

apps/web/src/pages/home/sections/HeroSection.tsx

@@ -0,0 +1,55 @@
+import React from "react"
+import { useNavigate } from "react-router-dom"
+import { Button } from "@/components/ui"
+
+/** Hero 首屏区域 */
+export const HeroSection: React.FC = () => {
+  const navigate = useNavigate()
+
+  return (
+    <section className="hp-hero">
+      <div className="hp-hero-inner">
+        {/* 左侧文案 */}
+        <div className="hp-hero-content">
+          <span className="hp-hero-tag">🦐 小虾智剪 · AI智能视频创作平台</span>
+          <h1 className="hp-hero-title">
+            上传素材，AI自动剪辑
+            <br />
+            智能剪辑短视频
+          </h1>
+          <p className="hp-hero-desc">
+            基于先进的 AI 技术，自动识别视频亮点，智能剪辑、配音、加字幕。 30
+            秒内将长视频转化为适合各平台传播的精品短视频。
+          </p>
+          <div className="hp-hero-actions">
+            <Button buttonType="primary" buttonSize="lg" onClick={() => navigate("/register")}>
+              立即免费开始
+            </Button>
+            <Button buttonType="secondary" buttonSize="lg" onClick={() => navigate("/pricing")}>
+              查看定价方案
+            </Button>
+          </div>
+        </div>
+
+        {/* 右侧视觉 */}
+        <div className="hp-hero-visual">
+          <div className="hp-hero-video">
+            <div className="hp-hero-video-inner">
+              <span className="hp-hero-video-placeholder">🎬</span>
+            </div>
+            <button className="hp-hero-play" type="button" aria-label="播放演示视频">
+              ▶
+            </button>
+          </div>
+          <div className="hp-hero-info">
+            <div className="hp-hero-badges">
+              <span className="hp-hero-badge">✨ AI智能剪辑</span>
+              <span className="hp-hero-badge">⚡ 30秒生成</span>
+            </div>
+            <span className="hp-hero-pill">可发布</span>
+          </div>
+        </div>
+      </div>
+    </section>
+  )
+}

apps/web/src/pages/home/sections/Layout.tsx

@@ -0,0 +1,34 @@
+import React from "react"
+import { useNavigate } from "react-router-dom"
+import { Button } from "@/components/ui"
+
+/** 顶部导航栏 */
+export const NavBar: React.FC = () => {
+  const navigate = useNavigate()
+
+  return (
+    <header className="hp-nav">
+      <div className="hp-nav-inner">
+        <button className="hp-nav-brand" type="button" onClick={() => navigate("/")}>
+          <span className="hp-nav-logo">🦐</span>
+          <span className="hp-nav-brand-text">小虾智剪</span>
+        </button>
+        <div className="hp-nav-actions">
+          <Button buttonType="ghost" buttonSize="sm" onClick={() => navigate("/login")}>
+            登录
+          </Button>
+          <Button buttonType="primary" buttonSize="sm" onClick={() => navigate("/register")}>
+            免费注册
+          </Button>
+        </div>
+      </div>
+    </header>
+  )
+}
+
+/** 页脚 */
+export const Footer: React.FC = () => (
+  <footer className="hp-footer">
+    <p>© 2026 小虾智剪 · AI智能视频创作平台</p>
+  </footer>
+)

apps/web/src/pages/home/sections/PricingSection.tsx

@@ -0,0 +1,102 @@
+import React from "react"
+import { useNavigate } from "react-router-dom"
+import { Button } from "@/components/ui"
+
+interface Plan {
+  name: string
+  price: string
+  period: string
+  desc: string
+  features: string[]
+  highlighted: boolean
+  cta: string
+}
+
+const PLANS: Plan[] = [
+  {
+    name: "基础版",
+    price: "免费",
+    period: "",
+    desc: "适合个人体验，快速上手",
+    features: ["每月 5 次 AI 生成", "720p 视频导出", "基础模板库", "1 个平台账号绑定"],
+    highlighted: false,
+    cta: "免费开始",
+  },
+  {
+    name: "专业版",
+    price: "¥99",
+    period: "/月",
+    desc: "适合内容创作者，高效产出",
+    features: [
+      "每月 100 次 AI 生成",
+      "1080p 视频导出",
+      "全部模板库",
+      "4 个平台账号绑定",
+      "AI 配音克隆",
+      "优先客服支持",
+    ],
+    highlighted: true,
+    cta: "立即订阅",
+  },
+  {
+    name: "企业版",
+    price: "¥399",
+    period: "/月",
+    desc: "适合团队与企业，规模化运营",
+    features: [
+      "无限次 AI 生成",
+      "4K 视频导出",
+      "全部模板 + 定制模板",
+      "无限平台账号绑定",
+      "团队协作管理",
+      "API 接入支持",
+      "专属客户经理",
+    ],
+    highlighted: false,
+    cta: "联系销售",
+  },
+]
+
+/** 定价方案区域 */
+export const PricingSection: React.FC = () => {
+  const navigate = useNavigate()
+
+  return (
+    <section className="hp-pricing">
+      <div className="hp-section-inner">
+        <h2 className="hp-section-title">定价方案</h2>
+        <p className="hp-section-desc">选择适合您的方案，随时升级或取消</p>
+        <div className="hp-pricing-grid">
+          {PLANS.map((plan) => (
+            <div
+              key={plan.name}
+              className={`hp-pricing-card${plan.highlighted ? " hp-pricing-card--highlight" : ""}`}
+            >
+              {plan.highlighted && <div className="hp-pricing-badge">推荐</div>}
+              <h3 className="hp-pricing-name">{plan.name}</h3>
+              <div className="hp-pricing-price">
+                {plan.price}
+                {plan.period && <span className="hp-pricing-period">{plan.period}</span>}
+              </div>
+              <p className="hp-pricing-desc">{plan.desc}</p>
+              <ul className="hp-pricing-features">
+                {plan.features.map((f) => (
+                  <li key={f}>
+                    <span className="hp-pricing-check">✓</span>
+                    {f}
+                  </li>
+                ))}
+              </ul>
+              <Button
+                buttonType={plan.highlighted ? "primary" : "secondary"}
+                onClick={() => navigate("/register")}
+              >
+                {plan.cta}
+              </Button>
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  )
+}

apps/web/src/pages/home/sections/WorkflowSection.tsx

@@ -0,0 +1,31 @@
+import React from "react"
+
+const STEPS = [
+  { icon: "📤", title: "上传素材", desc: "拖拽或选择视频素材，支持批量上传" },
+  { icon: "🧠", title: "AI 处理", desc: "AI 自动分析、剪辑、配音、加字幕" },
+  { icon: "👀", title: "预览调整", desc: "在线预览生成结果，支持微调编辑" },
+  { icon: "🚀", title: "一键发布", desc: "多平台同步发布，追踪数据表现" },
+]
+
+/** 工作流程区域 */
+export const WorkflowSection: React.FC = () => {
+  return (
+    <section className="hp-workflow">
+      <div className="hp-section-inner">
+        <h2 className="hp-section-title">工作流程</h2>
+        <p className="hp-section-desc">四步完成短视频创作，从素材到发布仅需 30 秒</p>
+        <div className="hp-step-grid">
+          {STEPS.map((step, idx) => (
+            <div key={step.title} className="hp-step-card">
+              <div className="hp-step-number">{idx + 1}</div>
+              <div className="hp-step-icon">{step.icon}</div>
+              <h3 className="hp-step-title">{step.title}</h3>
+              <p className="hp-step-desc">{step.desc}</p>
+              {idx < STEPS.length - 1 && <div className="hp-step-arrow">→</div>}
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  )
+}

apps/web/src/pages/my-templates/MyTemplates.tsx

@@ -3,126 +3,39 @@
  * 卡片视图展示用户已保存的剪辑模板
  * 支持搜索、分类筛选、编辑/复制/删除/使用模板生成
  */
-import React, { useState } from "react"
-import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
-import {
-  Typography,
-  Card,
-  Input,
-  Select,
-  Tag,
-  Button,
-  Space,
-  Empty,
-  Spin,
-  Tooltip,
-  message,
-  Popconfirm,
-  Row,
-  Col,
-} from "antd"
-import {
-  SearchOutlined,
-  EditOutlined,
-  CopyOutlined,
-  DeleteOutlined,
-  VideoCameraOutlined,
-  AppstoreOutlined,
-  PlusOutlined,
-} from "@ant-design/icons"
+import React from "react"
+import { Typography, Input, Select, Button, Empty, Spin, Row, Col } from "antd"
+import { SearchOutlined, AppstoreOutlined, PlusOutlined } from "@ant-design/icons"
 import { useNavigate } from "react-router-dom"
-import {
-  getEditingTemplates,
-  getTemplateCategories,
-  deleteEditingTemplate,
-  createEditingTemplate,
-  MODE_LABELS,
-  MODE_COLORS,
-  type EditingTemplate,
-  type TemplateMode,
-} from "@/api/editing-planner"
+import type { EditingTemplate } from "@/api/editing-planner"
+import { useMyTemplates } from "./hooks/useMyTemplates"
+import { TemplateCard } from "./components/TemplateCard"
 import "./MyTemplates.css"
 
 const { Title, Text } = Typography
 
 const MyTemplates: React.FC = () => {
   const navigate = useNavigate()
-  const queryClient = useQueryClient()
+  const {
+    searchText,
+    setSearchText,
+    filterCategory,
+    setFilterCategory,
+    templates,
+    categories,
+    isLoading,
+    handleCopy,
+    handleDelete,
+  } = useMyTemplates()
 
-  const [searchText, setSearchText] = useState("")
-  const [filterCategory, setFilterCategory] = useState("")
-
-  /* ── 数据查询 ── */
-  const { data: templates = [], isLoading } = useQuery({
-    queryKey: ["editing-templates", filterCategory, searchText],
-    queryFn: () =>
-      getEditingTemplates({
-        category: filterCategory || undefined,
-        tag: searchText || undefined,
-      }),
-  })
-
-  const { data: categories = [] } = useQuery({
-    queryKey: ["template-categories"],
-    queryFn: getTemplateCategories,
-  })
-
-  /* ── Mutations ── */
-  const deleteMutation = useMutation({
-    mutationFn: deleteEditingTemplate,
-    onSuccess: () => {
-      message.success("模板已删除")
-      queryClient.invalidateQueries({ queryKey: ["editing-templates"] })
-    },
-    onError: (err: unknown) => {
-      if (!(err as { __msgShown?: boolean })?.__msgShown) message.error("删除失败")
-    },
-  })
-
-  const copyMutation = useMutation({
-    mutationFn: (tpl: EditingTemplate) =>
-      createEditingTemplate({
-        name: `${tpl.name}（副本）`,
-        mode: tpl.mode,
-        category: tpl.category,
-        tags: tpl.tags,
-        title_config: tpl.title_config,
-        subtitle_config: tpl.subtitle_config,
-        bgm_config: tpl.bgm_config,
-        estimated_duration:
-          tpl.estimated_duration ??
-          Math.round(
-            tpl.segments.reduce((s, seg) => s + (seg.duration_min + seg.duration_max) / 2, 0),
-          ),
-        segments: tpl.segments.map(({ id: _id, ...rest }) => rest),
-      }),
-    onSuccess: () => {
-      message.success("模板已复制")
-      queryClient.invalidateQueries({ queryKey: ["editing-templates"] })
-    },
-    onError: (err: unknown) => {
-      if (!(err as { __msgShown?: boolean })?.__msgShown) message.error("复制失败")
-    },
-  })
-
-  /* ── 操作 ── */
   const handleEdit = (tpl: EditingTemplate) => {
     navigate(`/editing-planner?template=${tpl.id}`)
   }
 
   const handleGenerate = (tpl: EditingTemplate) => {
-    // 跳转到智能剪辑页面，统一从智能剪辑出片
     navigate(`/generate?templateId=${tpl.id}`)
   }
 
-  const handleCopy = (tpl: EditingTemplate) => {
-    copyMutation.mutate(tpl)
-  }
-
-  const handleDelete = (id: string) => {
-    deleteMutation.mutate(id)
-  }
-
   return (
     <div className="mt-page">
       {/* 页面头部 */}
@@ -179,69 +92,13 @@ const MyTemplates: React.FC = () => {
           <Row gutter={[16, 16]}>
             {templates.map((tpl) => (
               <Col key={tpl.id} xs={24} sm={12} md={8} lg={6}>
-                <Card
-                  className="mt-card"
-                  hoverable
-                  actions={[
-                    <Tooltip title="编辑" key="edit">
-                      <EditOutlined onClick={() => handleEdit(tpl)} />
-                    </Tooltip>,
-                    <Tooltip title="复制" key="copy">
-                      <CopyOutlined onClick={() => handleCopy(tpl)} />
-                    </Tooltip>,
-                    <Tooltip title="使用模板生成" key="generate">
-                      <VideoCameraOutlined onClick={() => handleGenerate(tpl)} />
-                    </Tooltip>,
-                    <Popconfirm
-                      key="delete"
-                      title="确定删除此模板？"
-                      onConfirm={() => handleDelete(tpl.id)}
-                      okText="删除"
-                      cancelText="取消"
-                    >
-                      <Tooltip title="删除">
-                        <DeleteOutlined style={{ color: "#ff4d4f" }} />
-                      </Tooltip>
-                    </Popconfirm>,
-                  ]}
-                >
-                  <div className="mt-card-head">
-                    <Text strong ellipsis style={{ fontSize: 15 }}>
-                      {tpl.name}
-                    </Text>
-                    <Tag color={MODE_COLORS[tpl.mode as TemplateMode] || "default"}>
-                      {MODE_LABELS[tpl.mode as TemplateMode] || tpl.mode}
-                    </Tag>
-                    <Tag color="green">用户自制</Tag>
-                  </div>
-
-                  <div className="mt-card-meta">
-                    <Text type="secondary" style={{ fontSize: 12 }}>
-                      {tpl.segments.length} 片段 · 预估 ~{tpl.estimated_duration}s
-                    </Text>
-                    {tpl.category && (
-                      <Tag style={{ fontSize: 11, marginTop: 4 }}>{tpl.category}</Tag>
-                    )}
-                  </div>
-
-                  {tpl.tags.length > 0 && (
-                    <div className="mt-card-tags">
-                      {tpl.tags.map((tag) => (
-                        <Tag key={tag} style={{ fontSize: 11 }}>
-                          {tag}
-                        </Tag>
-                      ))}
-                    </div>
-                  )}
-
-                  <div className="mt-card-config">
-                    <Space size={4} wrap>
-                      {tpl.title_config.ai_auto_select && <Tag color="cyan">AI标题</Tag>}
-                      {tpl.subtitle_config.enabled && <Tag color="geekblue">字幕</Tag>}
-                      {tpl.bgm_config.enabled && <Tag color="pink">BGM</Tag>}
-                    </Space>
-                  </div>
-                </Card>
+                <TemplateCard
+                  tpl={tpl}
+                  onEdit={handleEdit}
+                  onCopy={handleCopy}
+                  onGenerate={handleGenerate}
+                  onDelete={handleDelete}
+                />
               </Col>
             ))}
           </Row>

apps/web/src/pages/my-templates/components/TemplateCard.tsx

@@ -0,0 +1,92 @@
+import React from "react"
+import { Card, Tag, Tooltip, Popconfirm, Space, Typography } from "antd"
+import { EditOutlined, CopyOutlined, DeleteOutlined, VideoCameraOutlined } from "@ant-design/icons"
+import {
+  MODE_LABELS,
+  MODE_COLORS,
+  type EditingTemplate,
+  type TemplateMode,
+} from "@/api/editing-planner"
+
+const { Text } = Typography
+
+interface TemplateCardProps {
+  tpl: EditingTemplate
+  onEdit: (tpl: EditingTemplate) => void
+  onCopy: (tpl: EditingTemplate) => void
+  onGenerate: (tpl: EditingTemplate) => void
+  onDelete: (id: string) => void
+}
+
+/**
+ * 单个模板卡片组件
+ */
+export const TemplateCard: React.FC<TemplateCardProps> = ({
+  tpl,
+  onEdit,
+  onCopy,
+  onGenerate,
+  onDelete,
+}) => (
+  <Card
+    className="mt-card"
+    hoverable
+    actions={[
+      <Tooltip title="编辑" key="edit">
+        <EditOutlined onClick={() => onEdit(tpl)} />
+      </Tooltip>,
+      <Tooltip title="复制" key="copy">
+        <CopyOutlined onClick={() => onCopy(tpl)} />
+      </Tooltip>,
+      <Tooltip title="使用模板生成" key="generate">
+        <VideoCameraOutlined onClick={() => onGenerate(tpl)} />
+      </Tooltip>,
+      <Popconfirm
+        key="delete"
+        title="确定删除此模板？"
+        onConfirm={() => onDelete(tpl.id)}
+        okText="删除"
+        cancelText="取消"
+      >
+        <Tooltip title="删除">
+          <DeleteOutlined style={{ color: "#ff4d4f" }} />
+        </Tooltip>
+      </Popconfirm>,
+    ]}
+  >
+    <div className="mt-card-head">
+      <Text strong ellipsis style={{ fontSize: 15 }}>
+        {tpl.name}
+      </Text>
+      <Tag color={MODE_COLORS[tpl.mode as TemplateMode] || "default"}>
+        {MODE_LABELS[tpl.mode as TemplateMode] || tpl.mode}
+      </Tag>
+      <Tag color="green">用户自制</Tag>
+    </div>
+
+    <div className="mt-card-meta">
+      <Text type="secondary" style={{ fontSize: 12 }}>
+        {tpl.segments.length} 片段 · 预估 ~{tpl.estimated_duration}s
+      </Text>
+      {tpl.category && <Tag style={{ fontSize: 11, marginTop: 4 }}>{tpl.category}</Tag>}
+    </div>
+
+    {tpl.tags.length > 0 && (
+      <div className="mt-card-tags">
+        {tpl.tags.map((tag) => (
+          <Tag key={tag} style={{ fontSize: 11 }}>
+            {tag}
+          </Tag>
+        ))}
+      </div>
+    )}
+
+    <div className="mt-card-config">
+      <Space size={4} wrap>
+        {tpl.title_config.ai_auto_select && <Tag color="cyan">AI标题</Tag>}
+        {tpl.subtitle_config.enabled && <Tag color="geekblue">字幕</Tag>}
+        {tpl.bgm_config.enabled && <Tag color="pink">BGM</Tag>}
+      </Space>
+    </div>
+  </Card>
+)

apps/web/src/pages/my-templates/hooks/useMyTemplates.ts

@@ -0,0 +1,100 @@
+import { useState } from "react"
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
+import { message } from "antd"
+import {
+  getEditingTemplates,
+  getTemplateCategories,
+  deleteEditingTemplate,
+  createEditingTemplate,
+  type EditingTemplate,
+} from "@/api/editing-planner"
+
+/**
+ * 我的模板数据 Hook
+ * 封装模板列表查询、筛选、删除、复制等数据操作
+ */
+export function useMyTemplates() {
+  const queryClient = useQueryClient()
+  const [searchText, setSearchText] = useState("")
+  const [filterCategory, setFilterCategory] = useState("")
+
+  /* 模板列表 */
+  const { data: templates = [], isLoading } = useQuery({
+    queryKey: ["editing-templates", filterCategory, searchText],
+    queryFn: () =>
+      getEditingTemplates({
+        category: filterCategory || undefined,
+        tag: searchText || undefined,
+      }),
+  })
+
+  /* 分类列表 */
+  const { data: categories = [] } = useQuery({
+    queryKey: ["template-categories"],
+    queryFn: getTemplateCategories,
+  })
+
+  /* 删除 mutation */
+  const deleteMutation = useMutation({
+    mutationFn: deleteEditingTemplate,
+    onSuccess: () => {
+      message.success("模板已删除")
+      queryClient.invalidateQueries({ queryKey: ["editing-templates"] })
+    },
+    onError: (err: unknown) => {
+      if (!(err as { __msgShown?: boolean })?.__msgShown) message.error("删除失败")
+    },
+  })
+
+  /* 复制 mutation */
+  const copyMutation = useMutation({
+    mutationFn: (tpl: EditingTemplate) =>
+      createEditingTemplate({
+        name: `${tpl.name}（副本）`,
+        mode: tpl.mode,
+        category: tpl.category,
+        tags: tpl.tags,
+        title_config: tpl.title_config,
+        subtitle_config: tpl.subtitle_config,
+        bgm_config: tpl.bgm_config,
+        estimated_duration:
+          tpl.estimated_duration ??
+          Math.round(
+            tpl.segments.reduce((s, seg) => s + (seg.duration_min + seg.duration_max) / 2, 0),
+          ),
+        segments: tpl.segments.map(({ id: _id, ...rest }) => rest),
+      }),
+    onSuccess: () => {
+      message.success("模板已复制")
+      queryClient.invalidateQueries({ queryKey: ["editing-templates"] })
+    },
+    onError: (err: unknown) => {
+      if (!(err as { __msgShown?: boolean })?.__msgShown) message.error("复制失败")
+    },
+  })
+
+  const handleCopy = (tpl: EditingTemplate) => {
+    copyMutation.mutate(tpl)
+  }
+
+  const handleDelete = (id: string) => {
+    deleteMutation.mutate(id)
+  }
+
+  return {
+    // 状态
+    searchText,
+    setSearchText,
+    filterCategory,
+    setFilterCategory,
+    // 数据
+    templates,
+    categories,
+    isLoading,
+    // 操作
+    handleCopy,
+    handleDelete,
+    isDeleting: deleteMutation.isPending,
+    isCopying: copyMutation.isPending,
+  }
+}

apps/web/src/pages/products/ProductLibrary.tsx

@@ -1,38 +1,29 @@
 /**
  * 成片库页面 — V21 设计系统
  * 卡片网格布局，支持视频播放/下载/分享、批量操作、筛选
- * 使用 useQuery 对接后端真实 API（api/products.ts）
  *
- * 代码结构（三阶段重构后）：
- * - types.ts: 类型定义
- * - constants.ts: 常量配置
- * - utils/index.ts: 工具函数
- * - components/ProductCard.tsx: 产品卡片组件
- * - components/VideoPlayer.tsx: 视频播放器组件
- * - hooks/useProductList.ts: 列表查询与筛选
- * - hooks/useProductActions.ts: 单个/批量操作
+ * 主组件仅保留 Hook 组装与整体布局
+ * 列表查询 → hooks/useProductList
+ * 操作逻辑 → hooks/useProductActions
+ * 筛选栏 → components/ProductFilterBar
+ * 批量操作栏 → components/ProductBatchBar
+ * 空状态 → components/ProductEmptyState
+ * 产品卡片 → components/ProductCard
+ * 视频播放 → components/VideoPlayer
  */
 import React, { useState } from "react"
-import { Popconfirm, message } from "antd"
-import {
-  SearchOutlined,
-  VideoCameraOutlined,
-  DownloadOutlined,
-  DeleteOutlined,
-  CheckOutlined,
-  CloudUploadOutlined,
-} from "@ant-design/icons"
-import { Button, Input, Select } from "@/components/ui"
+import { VideoCameraOutlined, DownloadOutlined } from "@ant-design/icons"
+import { Button } from "@/components/ui"
 import type { ProductItem } from "./types"
 import { ProductCard } from "./components/ProductCard"
 import { VideoPlayer } from "./components/VideoPlayer"
+import { ProductFilterBar } from "./components/ProductFilterBar"
+import { ProductBatchBar } from "./components/ProductBatchBar"
+import { ProductEmptyState } from "./components/ProductEmptyState"
 import { useProductList } from "./hooks/useProductList"
 import { useProductActions } from "./hooks/useProductActions"
 import "./products.css"
 
-/* ============================================================
- * 主组件
- * ============================================================ */
 const ProductLibrary: React.FC = () => {
   const {
     products,
@@ -83,58 +74,20 @@ const ProductLibrary: React.FC = () => {
     setPlayingProduct,
   })
 
+  // ── Loading 状态 ──
   if (isLoading) {
-    return (
-      <div className="xx-products-page">
-        <div className="xx-products-empty">
-          <div className="xx-products-empty-icon">⏳</div>
-          <p>加载中...</p>
-        </div>
-      </div>
-    )
+    return <ProductEmptyState type="loading" />
   }
 
   // ── Error 状态 ──
   if (isError) {
     console.error("[ProductLibrary] 加载失败:", error)
     const errorMsg = error?.message || "加载失败"
-    // 404 视为空数据（API 尚未就绪或无数据）
     const is404 = errorMsg.includes("404") || errorMsg.includes("Not Found")
     if (is404) {
-      return (
-        <div className="xx-products-page">
-          <div className="xx-products-header">
-            <h2>
-              <VideoCameraOutlined /> 成片库
-            </h2>
-          </div>
-          <div className="xx-products-empty">
-            <div className="xx-products-empty-icon">🎬</div>
-            <p>暂无成片数据</p>
-            <p
-              style={{
-                fontSize: 12,
-                color: "var(--text-tertiary)",
-                marginTop: 4,
-              }}
-            >
-              完成视频生成后，成片将自动保存到这里
-            </p>
-          </div>
-        </div>
-      )
+      return <ProductEmptyState type="404" />
     }
-    return (
-      <div className="xx-products-page">
-        <div className="xx-products-empty">
-          <div className="xx-products-empty-icon">❌</div>
-          <p>{errorMsg || "加载失败，请稍后重试"}</p>
-          <Button buttonType="primary" buttonSize="sm" onClick={() => refetch()}>
-            重新加载
-          </Button>
-        </div>
-      </div>
-    )
+    return <ProductEmptyState type="error" errorMessage={errorMsg} onRetry={refetch} />
   }
 
   return (
@@ -153,129 +106,35 @@ const ProductLibrary: React.FC = () => {
 
       {/* 批量操作栏 */}
       {batchMode && (
-        <div className="xx-products-batch-bar">
-          <div className="xx-products-batch-bar-left">
-            <div
-              className={`xx-products-checkbox${allSelected ? " checked" : ""}`}
-              onClick={handleSelectAll}
-            >
-              {allSelected && <CheckOutlined />}
-            </div>
-            <span className="xx-products-select-all" onClick={handleSelectAll}>
-              {allSelected ? "取消全选" : "全选"}
-            </span>
-            <span className="xx-products-batch-count">已选择 {selectedIds.size} 项</span>
-          </div>
-          <div className="xx-products-batch-bar-right">
-            <Button
-              buttonType="ghost"
-              buttonSize="sm"
-              icon={<DownloadOutlined />}
-              onClick={handleBatchDownload}
-              disabled={batchDownloading}
-            >
-              {batchDownloading ? "打包中..." : "批量下载"}
-            </Button>
-            <Button
-              buttonType="primary"
-              buttonSize="sm"
-              icon={<CloudUploadOutlined />}
-              onClick={handleBatchPublish}
-            >
-              批量发布
-            </Button>
-            <Popconfirm
-              title={`确定删除选中的 ${selectedIds.size} 个视频？`}
-              onConfirm={handleBatchDelete}
-              okText="删除"
-              cancelText="取消"
-            >
-              <Button buttonType="danger" buttonSize="sm" icon={<DeleteOutlined />}>
-                批量删除
-              </Button>
-            </Popconfirm>
-            <Button buttonType="ghost" buttonSize="sm" onClick={clearSelection}>
-              取消选择
-            </Button>
-          </div>
-        </div>
+        <ProductBatchBar
+          allSelected={allSelected}
+          selectedCount={selectedIds.size}
+          batchDownloading={batchDownloading}
+          onSelectAll={handleSelectAll}
+          onBatchDownload={handleBatchDownload}
+          onBatchPublish={handleBatchPublish}
+          onBatchDelete={handleBatchDelete}
+          onClearSelection={clearSelection}
+        />
       )}
 
       {/* 筛选栏 */}
-      <div className="xx-products-filters">
-        <div className="xx-products-filters-left">
-          <Input
-            placeholder="搜索成片名称..."
-            prefix={<SearchOutlined />}
-            value={searchText}
-            onChange={(e) => setSearchText(e.target.value)}
-            allowClear
-            style={{ width: 220 }}
-          />
-          <Select
-            value={filterStatus}
-            onChange={setFilterStatus}
-            style={{ width: 120 }}
-            options={[
-              { value: "all", label: "全部状态" },
-              { value: "completed", label: "已完成" },
-              { value: "processing", label: "处理中" },
-              { value: "review", label: "待复核" },
-              { value: "failed", label: "失败" },
-            ]}
-          />
-          <Select
-            value={filterTime}
-            onChange={setFilterTime}
-            style={{ width: 120 }}
-            options={[
-              { value: "all", label: "全部时间" },
-              { value: "today", label: "今天" },
-              { value: "week", label: "近一周" },
-              { value: "month", label: "近一月" },
-            ]}
-          />
-          <Select
-            value={filterDuration}
-            onChange={setFilterDuration}
-            style={{ width: 120 }}
-            options={[
-              { value: "all", label: "全部时长" },
-              { value: "short", label: "≤1分钟" },
-              { value: "medium", label: "1-3分钟" },
-              { value: "long", label: ">3分钟" },
-            ]}
-          />
-          <Select
-            value={filterProject}
-            onChange={setFilterProject}
-            style={{ width: 140 }}
-            options={[{ value: "all", label: "全部项目" }, ...projectOptions]}
-          />
-          <Select
-            value={filterReviewStatus}
-            onChange={setFilterReviewStatus}
-            style={{ width: 130 }}
-            options={[
-              { value: "all", label: "全部复核" },
-              { value: "none", label: "未设置" },
-              { value: "pending_review", label: "待复核" },
-              { value: "approved", label: "已通过" },
-              { value: "rejected", label: "需修改" },
-            ]}
-          />
-        </div>
-        <div className="xx-products-filters-right">
-          <span
-            style={{
-              fontSize: "var(--font-size-sm)",
-              color: "var(--text-tertiary)",
-            }}
-          >
-            共 {filteredProducts.length} 个成片
-          </span>
-        </div>
-      </div>
+      <ProductFilterBar
+        searchText={searchText}
+        onSearchChange={setSearchText}
+        filterStatus={filterStatus}
+        onFilterStatusChange={setFilterStatus}
+        filterTime={filterTime}
+        onFilterTimeChange={setFilterTime}
+        filterDuration={filterDuration}
+        onFilterDurationChange={setFilterDuration}
+        filterProject={filterProject}
+        onFilterProjectChange={setFilterProject}
+        filterReviewStatus={filterReviewStatus}
+        onFilterReviewStatusChange={setFilterReviewStatus}
+        projectOptions={projectOptions}
+        resultCount={filteredProducts.length}
+      />
 
       {/* 卡片网格 */}
       {filteredProducts.length > 0 ? (
@@ -297,19 +156,7 @@ const ProductLibrary: React.FC = () => {
           ))}
         </div>
       ) : (
-        <div className="xx-products-empty">
-          <div className="xx-products-empty-icon">
-            <VideoCameraOutlined />
-          </div>
-          <p>暂无成片，去智能剪辑吧</p>
-          <Button
-            buttonType="primary"
-            buttonSize="sm"
-            onClick={() => message.info("跳转到生成页面")}
-          >
-            去生成
-          </Button>
-        </div>
+        <ProductEmptyState type="empty" />
       )}
 
       {/* 视频播放弹窗 */}

apps/web/src/pages/products/components/ProductBatchBar.tsx

@@ -0,0 +1,85 @@
+/**
+ * ProductLibrary 批量操作栏
+ */
+import React from "react"
+import {
+  CheckOutlined,
+  DownloadOutlined,
+  DeleteOutlined,
+  CloudUploadOutlined,
+} from "@ant-design/icons"
+import { Button } from "@/components/ui"
+import { Popconfirm } from "antd"
+
+export interface ProductBatchBarProps {
+  allSelected: boolean
+  selectedCount: number
+  batchDownloading: boolean
+  onSelectAll: () => void
+  onBatchDownload: () => void
+  onBatchPublish: () => void
+  onBatchDelete: () => void
+  onClearSelection: () => void
+}
+
+export const ProductBatchBar: React.FC<ProductBatchBarProps> = ({
+  allSelected,
+  selectedCount,
+  batchDownloading,
+  onSelectAll,
+  onBatchDownload,
+  onBatchPublish,
+  onBatchDelete,
+  onClearSelection,
+}) => {
+  return (
+    <div className="xx-products-batch-bar">
+      <div className="xx-products-batch-bar-left">
+        <div
+          className={`xx-products-checkbox${allSelected ? " checked" : ""}`}
+          onClick={onSelectAll}
+        >
+          {allSelected && <CheckOutlined />}
+        </div>
+        <span className="xx-products-select-all" onClick={onSelectAll}>
+          {allSelected ? "取消全选" : "全选"}
+        </span>
+        <span className="xx-products-batch-count">已选择 {selectedCount} 项</span>
+      </div>
+      <div className="xx-products-batch-bar-right">
+        <Button
+          buttonType="ghost"
+          buttonSize="sm"
+          icon={<DownloadOutlined />}
+          onClick={onBatchDownload}
+          disabled={batchDownloading}
+        >
+          {batchDownloading ? "打包中..." : "批量下载"}
+        </Button>
+        <Button
+          buttonType="primary"
+          buttonSize="sm"
+          icon={<CloudUploadOutlined />}
+          onClick={onBatchPublish}
+        >
+          批量发布
+        </Button>
+        <Popconfirm
+          title={`确定删除选中的 ${selectedCount} 个视频？`}
+          onConfirm={onBatchDelete}
+          okText="删除"
+          cancelText="取消"
+        >
+          <Button buttonType="danger" buttonSize="sm" icon={<DeleteOutlined />}>
+            批量删除
+          </Button>
+        </Popconfirm>
+        <Button buttonType="ghost" buttonSize="sm" onClick={onClearSelection}>
+          取消选择
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+export default ProductBatchBar

apps/web/src/pages/products/components/ProductEmptyState.tsx

@@ -0,0 +1,88 @@
+/**
+ * ProductLibrary 空状态/加载/错误页面
+ */
+import React from "react"
+import { VideoCameraOutlined } from "@ant-design/icons"
+import { Button } from "@/components/ui"
+import { message } from "antd"
+
+export type ProductEmptyStateType = "loading" | "empty" | "404" | "error"
+
+export interface ProductEmptyStateProps {
+  type: ProductEmptyStateType
+  errorMessage?: string
+  onRetry?: () => void
+}
+
+export const ProductEmptyState: React.FC<ProductEmptyStateProps> = ({
+  type,
+  errorMessage,
+  onRetry,
+}) => {
+  if (type === "loading") {
+    return (
+      <div className="xx-products-page">
+        <div className="xx-products-empty">
+          <div className="xx-products-empty-icon">⏳</div>
+          <p>加载中...</p>
+        </div>
+      </div>
+    )
+  }
+
+  if (type === "404") {
+    return (
+      <div className="xx-products-page">
+        <div className="xx-products-header">
+          <h2>
+            <VideoCameraOutlined /> 成片库
+          </h2>
+        </div>
+        <div className="xx-products-empty">
+          <div className="xx-products-empty-icon">🎬</div>
+          <p>暂无成片数据</p>
+          <p
+            style={{
+              fontSize: 12,
+              color: "var(--text-tertiary)",
+              marginTop: 4,
+            }}
+          >
+            完成视频生成后，成片将自动保存到这里
+          </p>
+        </div>
+      </div>
+    )
+  }
+
+  if (type === "error") {
+    return (
+      <div className="xx-products-page">
+        <div className="xx-products-empty">
+          <div className="xx-products-empty-icon">❌</div>
+          <p>{errorMessage || "加载失败，请稍后重试"}</p>
+          {onRetry && (
+            <Button buttonType="primary" buttonSize="sm" onClick={onRetry}>
+              重新加载
+            </Button>
+          )}
+        </div>
+      </div>
+    )
+  }
+
+  // empty
+  return (
+    <div className="xx-products-empty">
+      <div className="xx-products-empty-icon">
+        <VideoCameraOutlined />
+      </div>
+      <p>暂无成片，去智能剪辑吧</p>
+      <Button buttonType="primary" buttonSize="sm" onClick={() => message.info("跳转到生成页面")}>
+        去生成
+      </Button>
+    </div>
+  )
+}
+
+export default ProductEmptyState

apps/web/src/pages/products/components/ProductFilterBar.tsx

@@ -0,0 +1,119 @@
+/**
+ * ProductLibrary 筛选栏
+ */
+import React from "react"
+import { SearchOutlined } from "@ant-design/icons"
+import { Input, Select } from "@/components/ui"
+
+export interface ProductFilterBarProps {
+  searchText: string
+  onSearchChange: (text: string) => void
+  filterStatus: string
+  onFilterStatusChange: (val: string) => void
+  filterTime: string
+  onFilterTimeChange: (val: string) => void
+  filterDuration: string
+  onFilterDurationChange: (val: string) => void
+  filterProject: string
+  onFilterProjectChange: (val: string) => void
+  filterReviewStatus: string
+  onFilterReviewStatusChange: (val: string) => void
+  projectOptions: Array<{ value: string; label: string }>
+  resultCount: number
+}
+
+export const ProductFilterBar: React.FC<ProductFilterBarProps> = ({
+  searchText,
+  onSearchChange,
+  filterStatus,
+  onFilterStatusChange,
+  filterTime,
+  onFilterTimeChange,
+  filterDuration,
+  onFilterDurationChange,
+  filterProject,
+  onFilterProjectChange,
+  filterReviewStatus,
+  onFilterReviewStatusChange,
+  projectOptions,
+  resultCount,
+}) => {
+  return (
+    <div className="xx-products-filters">
+      <div className="xx-products-filters-left">
+        <Input
+          placeholder="搜索成片名称..."
+          prefix={<SearchOutlined />}
+          value={searchText}
+          onChange={(e) => onSearchChange(e.target.value)}
+          allowClear
+          style={{ width: 220 }}
+        />
+        <Select
+          value={filterStatus}
+          onChange={onFilterStatusChange}
+          style={{ width: 120 }}
+          options={[
+            { value: "all", label: "全部状态" },
+            { value: "completed", label: "已完成" },
+            { value: "processing", label: "处理中" },
+            { value: "review", label: "待复核" },
+            { value: "failed", label: "失败" },
+          ]}
+        />
+        <Select
+          value={filterTime}
+          onChange={onFilterTimeChange}
+          style={{ width: 120 }}
+          options={[
+            { value: "all", label: "全部时间" },
+            { value: "today", label: "今天" },
+            { value: "week", label: "近一周" },
+            { value: "month", label: "近一月" },
+          ]}
+        />
+        <Select
+          value={filterDuration}
+          onChange={onFilterDurationChange}
+          style={{ width: 120 }}
+          options={[
+            { value: "all", label: "全部时长" },
+            { value: "short", label: "≤1分钟" },
+            { value: "medium", label: "1-3分钟" },
+            { value: "long", label: ">3分钟" },
+          ]}
+        />
+        <Select
+          value={filterProject}
+          onChange={onFilterProjectChange}
+          style={{ width: 140 }}
+          options={[{ value: "all", label: "全部项目" }, ...projectOptions]}
+        />
+        <Select
+          value={filterReviewStatus}
+          onChange={onFilterReviewStatusChange}
+          style={{ width: 130 }}
+          options={[
+            { value: "all", label: "全部复核" },
+            { value: "none", label: "未设置" },
+            { value: "pending_review", label: "待复核" },
+            { value: "approved", label: "已通过" },
+            { value: "rejected", label: "需修改" },
+          ]}
+        />
+      </div>
+      <div className="xx-products-filters-right">
+        <span
+          style={{
+            fontSize: "var(--font-size-sm)",
+            color: "var(--text-tertiary)",
+          }}
+        >
+          共 {resultCount} 个成片
+        </span>
+      </div>
+    </div>
+  )
+}
+
+export default ProductFilterBar

apps/web/src/pages/subscription/UpgradeSubscription.tsx

@@ -2,151 +2,59 @@
  * 升级/降级/续费页面
  * P1-3: antd Button/Modal/Radio/Spin → 自定义 UI 组件
  */
-import React, { useState, useEffect } from "react"
-import { message } from "antd"
-import { Button, Modal } from "@/components/ui"
+import React from "react"
+import { Modal } from "@/components/ui"
 import { useNavigate } from "react-router-dom"
-import {
-  getCurrentSubscription,
-  changePlan,
-  toggleAutoRenew,
-  cancelSubscription,
-} from "@/api/subscription"
-import type { SubscriptionInfo, PlanType, BillingCycle } from "@/api/subscription"
+import type { PlanType } from "@/api/subscription"
 import PageHead from "@/components/layout/PageHead"
+import { Button } from "@/components/ui"
+import { PLANS_META, getPlanName, getPlanPrice } from "./constants"
+import { BillingCycleSwitch, Spinner } from "./components/SubscriptionUI"
+import { useSubscription } from "./hooks/useSubscription"
 import "./UpgradeSubscription.css"
 
-const PLANS_META: Record<string, { name: string; price: number; yearlyPrice: number }> = {
-  free: { name: "体验版", price: 0, yearlyPrice: 0 },
-  standard: { name: "标准版", price: 99, yearlyPrice: 990 },
-  pro: { name: "专业版", price: 299, yearlyPrice: 2990 },
-  enterprise: { name: "企业版", price: 0, yearlyPrice: 0 },
-}
-
-/** 自定义计费周期切换组件 */
-const BillingCycleSwitch: React.FC<{
-  value: BillingCycle
-  onChange: (cycle: BillingCycle) => void
-  monthlyPrice: number
-  yearlyPrice: number
-}> = ({ value, onChange, monthlyPrice, yearlyPrice }) => (
-  <div className="xx-billing-cycle-switch">
-    <button
-      type="button"
-      className={`xx-billing-cycle-btn ${value === "monthly" ? "active" : ""}`}
-      onClick={() => onChange("monthly")}
-    >
-      ¥{monthlyPrice}/月
-    </button>
-    <button
-      type="button"
-      className={`xx-billing-cycle-btn ${value === "yearly" ? "active" : ""}`}
-      onClick={() => onChange("yearly")}
-    >
-      ¥{yearlyPrice}/年
-      {yearlyPrice > 0 && monthlyPrice > 0 && (
-        <span className="xx-save">省 ¥{monthlyPrice * 12 - yearlyPrice}</span>
-      )}
-    </button>
-  </div>
-)
-
-/** 自定义 Spinner 组件 */
-const Spinner: React.FC<{ size?: "small" | "large" }> = ({ size = "large" }) => (
-  <div className={`xx-spinner xx-spinner--${size}`}>
-    <div className="xx-spinner-dot" />
-    <div className="xx-spinner-dot" />
-    <div className="xx-spinner-dot" />
-  </div>
-)
-
 const UpgradeSubscription: React.FC = () => {
   const navigate = useNavigate()
-  const [subscription, setSubscription] = useState<SubscriptionInfo | null>(null)
-  const [loading, setLoading] = useState(true)
-  const [submitting, setSubmitting] = useState(false)
-  const [selectedPlan, setSelectedPlan] = useState<PlanType>("standard")
-  const [billingCycle, setBillingCycle] = useState<BillingCycle>("monthly")
+  const {
+    subscription,
+    loading,
+    submitting,
+    selectedPlan,
+    billingCycle,
+    setSelectedPlan,
+    setBillingCycle,
+    executeChangePlan,
+    handleToggleAutoRenew,
+    handleCancel,
+  } = useSubscription()
 
-  useEffect(() => {
-    loadSubscription()
-  }, [])
-
-  const loadSubscription = async () => {
-    try {
-      const data = await getCurrentSubscription()
-      setSubscription(data)
-      setSelectedPlan(data.plan_id)
-    } catch (err: unknown) {
-      if (!(err as { __msgShown?: boolean })?.__msgShown) message.error("获取订阅信息失败")
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  const handleUpgrade = async () => {
+  const handleUpgradeClick = () => {
     if (!subscription) return
     if (selectedPlan === subscription.plan_id && billingCycle === subscription.billing_cycle) {
-      message.info("当前已是该套餐")
       return
     }
 
     const plan = PLANS_META[selectedPlan]
-    const price = billingCycle === "yearly" ? plan.yearlyPrice : plan.price
+    const price = getPlanPrice(selectedPlan, billingCycle)
 
     Modal.confirm({
       title: "确认变更套餐",
       content: `即将变更为「${plan.name}」（${billingCycle === "monthly" ? "月付" : "年付"}），${price > 0 ? `费用 ¥${price}${billingCycle === "monthly" ? "/月" : "/年"}` : "免费"}。变更立即生效。`,
       okText: "确认变更",
       cancelText: "取消",
-      onOk: async () => {
-        try {
-          setSubmitting(true)
-          const res = await changePlan({
-            target_plan_id: selectedPlan,
-            billing_cycle: billingCycle,
-          })
-          if (res.success) {
-            message.success(res.message)
-            setSubscription(res.new_subscription ?? null)
-          } else {
-            message.error(res.message)
-          }
-        } catch (err: unknown) {
-          if (!(err as { __msgShown?: boolean })?.__msgShown) message.error("套餐变更失败，请重试")
-        } finally {
-          setSubmitting(false)
-        }
-      },
+      onOk: executeChangePlan,
     })
   }
 
-  const handleToggleAutoRenew = async (enabled: boolean) => {
-    try {
-      const res = await toggleAutoRenew(enabled)
-      message.success(res.message)
-      if (subscription) {
-        setSubscription({ ...subscription, auto_renew: enabled })
-      }
-    } catch (err: unknown) {
-      if (!(err as { __msgShown?: boolean })?.__msgShown) message.error("操作失败")
-    }
-  }
-
-  const handleCancel = () => {
+  const handleCancelClick = () => {
     Modal.confirm({
       title: "确认取消订阅",
       content: "取消后，当前周期结束前仍可正常使用，到期后降级为体验版。",
       okText: "确认取消",
       cancelText: "再想想",
       onOk: async () => {
-        try {
-          const res = await cancelSubscription()
-          message.success(res.message)
-          navigate("/app/subscription")
-        } catch (err: unknown) {
-          if (!(err as { __msgShown?: boolean })?.__msgShown) message.error("取消失败")
-        }
+        const ok = await handleCancel()
+        if (ok) navigate("/app/subscription")
       },
     })
   }
@@ -163,10 +71,7 @@ const UpgradeSubscription: React.FC = () => {
 
   return (
     <div className="xx-upgrade-page">
-      <PageHead
-        title="变更订阅方案"
-        description={`当前套餐：${PLANS_META[currentPlan]?.name ?? "体验版"}`}
-      />
+      <PageHead title="变更订阅方案" description={`当前套餐：${getPlanName(currentPlan)}`} />
 
       <div className="xx-upgrade-plans">
         {(["standard", "pro", "enterprise"] as PlanType[]).map((planId) => {
@@ -198,7 +103,7 @@ const UpgradeSubscription: React.FC = () => {
           buttonType="primary"
           buttonSize="lg"
           disabled={submitting || selectedPlan === currentPlan}
-          onClick={handleUpgrade}
+          onClick={handleUpgradeClick}
         >
           {submitting ? "处理中..." : "确认变更"}
         </Button>
@@ -220,7 +125,7 @@ const UpgradeSubscription: React.FC = () => {
           <Button
             buttonType="danger"
             buttonSize="sm"
-            onClick={handleCancel}
+            onClick={handleCancelClick}
             className="xx-cancel-btn"
           >
             取消订阅

apps/web/src/pages/subscription/components/SubscriptionUI.tsx

@@ -0,0 +1,50 @@
+import React from "react"
+import type { BillingCycle } from "@/api/subscription"
+
+interface BillingCycleSwitchProps {
+  value: BillingCycle
+  onChange: (cycle: BillingCycle) => void
+  monthlyPrice: number
+  yearlyPrice: number
+}
+
+/** 自定义计费周期切换组件 */
+export const BillingCycleSwitch: React.FC<BillingCycleSwitchProps> = ({
+  value,
+  onChange,
+  monthlyPrice,
+  yearlyPrice,
+}) => (
+  <div className="xx-billing-cycle-switch">
+    <button
+      type="button"
+      className={`xx-billing-cycle-btn ${value === "monthly" ? "active" : ""}`}
+      onClick={() => onChange("monthly")}
+    >
+      ¥{monthlyPrice}/月
+    </button>
+    <button
+      type="button"
+      className={`xx-billing-cycle-btn ${value === "yearly" ? "active" : ""}`}
+      onClick={() => onChange("yearly")}
+    >
+      ¥{yearlyPrice}/年
+      {yearlyPrice > 0 && monthlyPrice > 0 && (
+        <span className="xx-save">省 ¥{monthlyPrice * 12 - yearlyPrice}</span>
+      )}
+    </button>
+  </div>
+)
+
+interface SpinnerProps {
+  size?: "small" | "large"
+}
+
+/** 自定义 Spinner 组件 */
+export const Spinner: React.FC<SpinnerProps> = ({ size = "large" }) => (
+  <div className={`xx-spinner xx-spinner--${size}`}>
+    <div className="xx-spinner-dot" />
+    <div className="xx-spinner-dot" />
+    <div className="xx-spinner-dot" />
+  </div>
+)

apps/web/src/pages/subscription/constants.ts

@@ -0,0 +1,16 @@
+import type { PlanType, BillingCycle } from "@/api/subscription"
+
+export const PLANS_META: Record<string, { name: string; price: number; yearlyPrice: number }> = {
+  free: { name: "体验版", price: 0, yearlyPrice: 0 },
+  standard: { name: "标准版", price: 99, yearlyPrice: 990 },
+  pro: { name: "专业版", price: 299, yearlyPrice: 2990 },
+  enterprise: { name: "企业版", price: 0, yearlyPrice: 0 },
+}
+
+export const getPlanName = (planId: PlanType | string) => PLANS_META[planId]?.name ?? "体验版"
+
+export const getPlanPrice = (planId: PlanType | string, cycle: BillingCycle) => {
+  const plan = PLANS_META[planId]
+  if (!plan) return 0
+  return cycle === "yearly" ? plan.yearlyPrice : plan.price
+}

apps/web/src/pages/subscription/hooks/useSubscription.ts

@@ -0,0 +1,111 @@
+import { useState, useEffect, useCallback } from "react"
+import { message } from "antd"
+import {
+  getCurrentSubscription,
+  changePlan,
+  toggleAutoRenew,
+  cancelSubscription,
+  type SubscriptionInfo,
+  type PlanType,
+  type BillingCycle,
+} from "@/api/subscription"
+
+/**
+ * 订阅管理 Hook
+ * 封装订阅信息查询、套餐变更、自动续费切换、取消订阅等逻辑
+ */
+export function useSubscription() {
+  const [subscription, setSubscription] = useState<SubscriptionInfo | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [submitting, setSubmitting] = useState(false)
+  const [selectedPlan, setSelectedPlan] = useState<PlanType>("standard")
+  const [billingCycle, setBillingCycle] = useState<BillingCycle>("monthly")
+
+  const loadSubscription = useCallback(async () => {
+    try {
+      const data = await getCurrentSubscription()
+      setSubscription(data)
+      setSelectedPlan(data.plan_id)
+    } catch (err: unknown) {
+      if (!(err as { __msgShown?: boolean })?.__msgShown) message.error("获取订阅信息失败")
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    loadSubscription()
+  }, [loadSubscription])
+
+  const handleUpgrade = useCallback(async () => {
+    if (!subscription) return
+    if (selectedPlan === subscription.plan_id && billingCycle === subscription.billing_cycle) {
+      message.info("当前已是该套餐")
+      return
+    }
+    // 由调用方决定是否弹确认框
+  }, [subscription, selectedPlan, billingCycle])
+
+  const executeChangePlan = useCallback(async () => {
+    try {
+      setSubmitting(true)
+      const res = await changePlan({
+        target_plan_id: selectedPlan,
+        billing_cycle: billingCycle,
+      })
+      if (res.success) {
+        message.success(res.message)
+        setSubscription(res.new_subscription ?? null)
+      } else {
+        message.error(res.message)
+      }
+    } catch (err: unknown) {
+      if (!(err as { __msgShown?: boolean })?.__msgShown) message.error("套餐变更失败，请重试")
+    } finally {
+      setSubmitting(false)
+    }
+  }, [selectedPlan, billingCycle])
+
+  const handleToggleAutoRenew = useCallback(
+    async (enabled: boolean) => {
+      try {
+        const res = await toggleAutoRenew(enabled)
+        message.success(res.message)
+        if (subscription) {
+          setSubscription({ ...subscription, auto_renew: enabled })
+        }
+      } catch (err: unknown) {
+        if (!(err as { __msgShown?: boolean })?.__msgShown) message.error("操作失败")
+      }
+    },
+    [subscription],
+  )
+
+  const handleCancel = useCallback(async () => {
+    try {
+      const res = await cancelSubscription()
+      message.success(res.message)
+      return true
+    } catch (err: unknown) {
+      if (!(err as { __msgShown?: boolean })?.__msgShown) message.error("取消失败")
+      return false
+    }
+  }, [])
+
+  return {
+    // 状态
+    subscription,
+    loading,
+    submitting,
+    selectedPlan,
+    billingCycle,
+    setSelectedPlan,
+    setBillingCycle,
+    // 操作
+    loadSubscription,
+    handleUpgrade,
+    executeChangePlan,
+    handleToggleAutoRenew,
+    handleCancel,
+  }
+}

apps/web/src/pages/templates/TemplateLibrary.tsx

@@ -6,708 +6,99 @@
  * - 复制模板 / 从模板生成
  * - 卡片网格布局 + 类型筛选 + 搜索 + 收藏
  */
-import React, { useState, useMemo, useCallback } from "react"
-import { useNavigate } from "react-router-dom"
-import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
-import { Button, message, Pagination, Tooltip, Tag, Descriptions } from "antd"
-import {
-  LoadingOutlined,
-  ExclamationCircleOutlined,
-  InboxOutlined,
-  SearchOutlined,
-  CopyOutlined,
-  ThunderboltOutlined,
-} from "@ant-design/icons"
-import {
-  getTemplates,
-  getTemplate,
-  toggleFavoriteTemplate,
-  copyTemplate,
-  type TemplateItem,
-  type TemplateListParams,
-  type TemplateSegment,
-} from "@/api/templates"
+import React from "react"
+import { useTemplateLibrary } from "./hooks/useTemplateLibrary"
+import { useTemplateDetail } from "./hooks/useTemplateDetail"
+import { TemplateHeader } from "./components/template-library/TemplateHeader"
+import { TemplateToolbar } from "./components/template-library/TemplateToolbar"
+import { TemplateGrid } from "./components/template-library/TemplateGrid"
+import { TemplateDetailModal } from "./components/template-library/TemplateDetailModal"
 import "./templates.css"
 
-/* ============================================================
- * 类型定义
- * ============================================================ */
-
-/** 模板类型 */
-type EditTemplateType = "口播" | "种草" | "产品" | "品牌" | "混剪" | "Vlog"
-
-/* ============================================================
- * 模板类型配置
- * ============================================================ */
-
-const TEMPLATE_TYPES: Array<{
-  type: EditTemplateType | "全部"
-  label: string
-  icon: string
-  color: string
-}> = [
-  { type: "全部", label: "全部", icon: "📋", color: "#6366f1" },
-  { type: "口播", label: "口播", icon: "🎙️", color: "#6366f1" },
-  { type: "种草", label: "种草", icon: "🌱", color: "#10b981" },
-  { type: "产品", label: "产品", icon: "📦", color: "#0ea5e9" },
-  { type: "品牌", label: "品牌", icon: "🏷️", color: "#f59e0b" },
-  { type: "混剪", label: "混剪", icon: "🎬", color: "#8b5cf6" },
-  { type: "Vlog", label: "Vlog", icon: "📹", color: "#ec4899" },
-]
-
-/** 时长筛选选项 */
-const DURATION_OPTIONS: Array<{
-  value: "" | "short" | "medium" | "long"
-  label: string
-}> = [
-  { value: "", label: "全部时长" },
-  { value: "short", label: "30秒以内" },
-  { value: "medium", label: "30秒-2分钟" },
-  { value: "long", label: "2分钟以上" },
-]
-
-/* ============================================================
- * 辅助函数
- * ============================================================ */
-
-/** 获取类型对应颜色 */
-const getTypeColor = (type: string): string => {
-  const found = TEMPLATE_TYPES.find((t) => t.type === type)
-  return found?.color ?? "#6366f1"
-}
-
-/** 根据 category 生成占位渐变色 */
-const gradientForCategory = (category: string): string => {
-  const gradients: Record<string, string> = {
-    口播: "linear-gradient(135deg, #6366f1, #8b5cf6)",
-    种草: "linear-gradient(135deg, #10b981, #059669)",
-    产品: "linear-gradient(135deg, #0ea5e9, #0284c7)",
-    品牌: "linear-gradient(135deg, #f59e0b, #d97706)",
-    混剪: "linear-gradient(135deg, #8b5cf6, #6d28d9)",
-    Vlog: "linear-gradient(135deg, #ec4899, #db2777)",
-  }
-  return gradients[category] ?? "linear-gradient(135deg, #6366f1, #8b5cf6)"
-}
-
-/** 格式化时长 */
-const formatDuration = (seconds: number | undefined | null): string => {
-  if (!seconds || seconds <= 0) return "0秒"
-  const totalSec = Math.round(seconds)
-  const m = Math.floor(totalSec / 60)
-  const s = totalSec % 60
-  if (m === 0) return `${s}秒`
-  return `${m}分${s > 0 ? `${s}秒` : ""}`
-}
-
-/** 配置展示字段（formatConfig 提取通用配置的可读属性） */
-interface ConfigDisplayFields {
-  font_size?: string | number
-  font_family?: string
-  color?: string
-  position?: string
-  volume?: string | number
-  name?: string
-}
-
-/** 格式化配置对象为可读文本 */
-const formatConfig = (config?: object): string => {
-  if (!config || Object.keys(config).length === 0) return "默认"
-  const c = config as ConfigDisplayFields
-  const parts: string[] = []
-  if (c.font_size) parts.push(`字号: ${c.font_size}`)
-  if (c.font_family) parts.push(`字体: ${c.font_family}`)
-  if (c.color) parts.push(`颜色: ${c.color}`)
-  if (c.position) parts.push(`位置: ${c.position}`)
-  if (c.volume !== undefined) parts.push(`音量: ${c.volume}%`)
-  if (c.name) parts.push(String(c.name))
-  return parts.length > 0 ? parts.join(" / ") : JSON.stringify(config)
-}
-
-/** 素材类型标签 */
-const MATERIAL_TYPE_LABELS: Record<string, string> = {
-  video: "视频",
-  image: "图片",
-  audio: "音频",
-  voiceover: "配音",
-  subtitle: "字幕",
-  null: "不限",
-}
-
-/* ============================================================
- * 模板详情弹窗组件
- * ============================================================ */
-
-interface TemplateDetailModalProps {
-  template: TemplateItem
-  isFavorite: boolean
-  onClose: () => void
-  onToggleFavorite: (id: string) => void
-  onUse: (template: TemplateItem) => void
-  onCopy: (template: TemplateItem) => void
-}
-
-const TemplateDetailModal: React.FC<TemplateDetailModalProps> = ({
-  template,
-  isFavorite,
-  onClose,
-  onToggleFavorite,
-  onUse,
-  onCopy,
-}) => {
-  const segments = template.segments ?? []
-  const totalSegmentDuration = segments.reduce(
-    (sum, s) => sum + (s.duration_min + s.duration_max) / 2,
-    0,
-  )
-
-  return (
-    <div className="xx-template-modal-overlay" onClick={onClose}>
-      <div
-        className="xx-template-modal xx-template-modal-wide"
-        onClick={(e) => e.stopPropagation()}
-      >
-        {/* 关闭按钮 */}
-        <button className="xx-template-modal-close" onClick={onClose} title="关闭">
-          ✕
-        </button>
-
-        {/* 预览区域 */}
-        <div
-          className="xx-template-modal-preview"
-          style={{ background: gradientForCategory(template.category) }}
-        >
-          {template.thumbnail_url ? (
-            <img
-              src={template.thumbnail_url}
-              alt={template.name}
-              className="xx-template-modal-thumb-img"
-            />
-          ) : (
-            <div className="xx-template-modal-preview-content">
-              <span className="xx-template-preview-icon">
-                {TEMPLATE_TYPES.find((t) => t.type === template.category)?.icon ?? "📋"}
-              </span>
-              <span className="xx-template-preview-title">{template.name}</span>
-            </div>
-          )}
-        </div>
-
-        {/* 内容区域 */}
-        <div className="xx-template-modal-content">
-          {/* 标题行 */}
-          <div className="xx-template-modal-title-row">
-            <h3>{template.name}</h3>
-            <span
-              className="xx-template-modal-type-badge"
-              style={{
-                color: getTypeColor(template.category),
-                background: `${getTypeColor(template.category)}18`,
-              }}
-            >
-              {TEMPLATE_TYPES.find((t) => t.type === template.category)?.icon} {template.category}
-            </span>
-          </div>
-
-          {/* 描述 */}
-          <p className="xx-template-modal-desc">{template.description}</p>
-
-          {/* 标签 */}
-          {(template.tags?.length ?? 0) > 0 && (
-            <div className="xx-template-modal-tags">
-              {template.tags!.map((tag) => (
-                <span key={tag} className="xx-template-modal-tag">
-                  #{tag}
-                </span>
-              ))}
-            </div>
-          )}
-
-          {/* 基本信息 */}
-          <Descriptions
-            column={2}
-            size="small"
-            className="xx-template-modal-desc-table"
-            items={[
-              {
-                key: "duration",
-                label: "目标时长",
-                children: formatDuration(template.estimated_duration ?? template.target_duration),
-              },
-              {
-                key: "clips",
-                label: "片段数量",
-                children: `${template.clip_count} 个`,
-              },
-              {
-                key: "ratio",
-                label: "视频比例",
-                children: template.aspect_ratio ?? "16:9",
-              },
-              {
-                key: "usage",
-                label: "使用次数",
-                children: `${template.usage_count ?? 0} 次`,
-              },
-            ]}
-          />
-
-          {/* 素材规则（片段配置） */}
-          {segments.length > 0 && (
-            <div className="xx-template-modal-section">
-              <h4>🎬 素材规则</h4>
-              <div className="xx-template-modal-clip-list">
-                {segments
-                  .sort((a, b) => a.segment_order - b.segment_order)
-                  .map((seg: TemplateSegment, idx: number) => (
-                    <div key={seg.id ?? idx} className="xx-template-modal-clip-item">
-                      <span className="xx-template-modal-clip-order">#{seg.segment_order}</span>
-                      <span
-                        className="xx-template-modal-clip-badge"
-                        style={{
-                          color: seg.material_type ? getTypeColor(seg.material_type) : "#64748b",
-                          background: seg.material_type
-                            ? `${getTypeColor(seg.material_type)}18`
-                            : "#f1f5f9",
-                        }}
-                      >
-                        {MATERIAL_TYPE_LABELS[seg.material_type ?? "null"] ??
-                          seg.material_type ??
-                          "不限"}
-                      </span>
-                      <span className="xx-template-modal-clip-desc">
-                        {seg.description || `片段 ${seg.segment_order}`}
-                      </span>
-                      <Tooltip title={`时长范围: ${seg.duration_min}秒 - ${seg.duration_max}秒`}>
-                        <span className="xx-template-modal-clip-duration">
-                          {seg.duration_min}-{seg.duration_max}秒
-                        </span>
-                      </Tooltip>
-                    </div>
-                  ))}
-              </div>
-              <div className="xx-template-modal-total-duration">
-                预估总时长：{formatDuration(Math.round(totalSegmentDuration))}
-              </div>
-            </div>
-          )}
-
-          {/* 样式配置 */}
-          <div className="xx-template-modal-section">
-            <h4>🎨 样式配置</h4>
-            <div className="xx-template-modal-style-grid">
-              <div className="xx-template-modal-style-item">
-                <span className="xx-template-modal-style-label">字幕样式</span>
-                <span className="xx-template-modal-style-value">
-                  {formatConfig(template.subtitle_config)}
-                </span>
-              </div>
-              <div className="xx-template-modal-style-item">
-                <span className="xx-template-modal-style-label">标题样式</span>
-                <span className="xx-template-modal-style-value">
-                  {formatConfig(template.title_config)}
-                </span>
-              </div>
-              <div className="xx-template-modal-style-item">
-                <span className="xx-template-modal-style-label">BGM 配置</span>
-                <span className="xx-template-modal-style-value">
-                  {formatConfig(template.bgm_config)}
-                </span>
-              </div>
-              <div className="xx-template-modal-style-item">
-                <span className="xx-template-modal-style-label">视频比例</span>
-                <span className="xx-template-modal-style-value">
-                  {template.aspect_ratio ?? "16:9"}
-                </span>
-              </div>
-            </div>
-          </div>
-
-          {/* 统计信息 */}
-          <div className="xx-template-modal-stats">
-            <span>已使用 {template.usage_count ?? 0} 次</span>
-            <button
-              className={`xx-template-modal-fav-btn${isFavorite ? " is-favorite" : ""}`}
-              onClick={() => onToggleFavorite(template.id)}
-            >
-              {isFavorite ? "★ 已收藏" : "☆ 收藏"}
-            </button>
-          </div>
-
-          {/* 操作按钮 */}
-          <div className="xx-template-modal-actions">
-            <Button icon={<CopyOutlined />} onClick={() => onCopy(template)}>
-              复制模板
-            </Button>
-            <Button type="primary" icon={<ThunderboltOutlined />} onClick={() => onUse(template)}>
-              使用此模板生成
-            </Button>
-          </div>
-        </div>
-      </div>
-    </div>
-  )
-}
-
-/* ============================================================
- * 模板卡片组件
- * ============================================================ */
-
-interface TemplateCardProps {
-  template: TemplateItem
-  isFavorite: boolean
-  onPreview: (template: TemplateItem) => void
-  onToggleFavorite: (id: string, e: React.MouseEvent) => void
-  onUse: (template: TemplateItem) => void
-}
-
-const TemplateCard: React.FC<TemplateCardProps> = ({
-  template,
-  isFavorite,
-  onPreview,
-  onToggleFavorite,
-  onUse,
-}) => {
-  return (
-    <div className="xx-template-card" onClick={() => onPreview(template)}>
-      {/* 缩略图 */}
-      <div className="xx-template-thumb">
-        {template.thumbnail_url ? (
-          <img src={template.thumbnail_url} alt={template.name} className="xx-template-thumb-img" />
-        ) : (
-          <div
-            className="xx-template-thumb-bg"
-            style={{ background: gradientForCategory(template.category) }}
-          >
-            {(template.description ?? "").slice(0, 80)}
-            {(template.description ?? "").length > 80 ? "..." : ""}
-          </div>
-        )}
-        <div className="xx-template-thumb-overlay" />
-        <div className="xx-template-thumb-name">{template.name}</div>
-        <div className="xx-template-thumb-meta">
-          <span className="xx-template-thumb-duration">
-            {formatDuration(template.estimated_duration ?? template.target_duration)}
-          </span>
-        </div>
-        <div className="xx-template-preview-hint">点击查看详情</div>
-        <button
-          className={`xx-template-fav-btn${isFavorite ? " is-favorite" : ""}`}
-          onClick={(e) => onToggleFavorite(template.id, e)}
-          title={isFavorite ? "取消收藏" : "收藏"}
-        >
-          {isFavorite ? "★" : "☆"}
-        </button>
-      </div>
-
-      {/* 信息区 */}
-      <div className="xx-template-info">
-        <div className="xx-template-info-top">
-          <span
-            className="xx-template-category-pill"
-            style={{
-              color: getTypeColor(template.category),
-              background: `${getTypeColor(template.category)}18`,
-            }}
-          >
-            {template.category}
-          </span>
-          {(template.tags ?? []).slice(0, 2).map((tag) => (
-            <Tag key={tag} className="xx-template-tag-pill" bordered={false}>
-              {tag}
-            </Tag>
-          ))}
-        </div>
-        <p className="xx-template-desc">{template.description ?? ""}</p>
-        <div className="xx-template-meta">
-          <span className="xx-template-usage">已使用 {template.usage_count ?? 0} 次</span>
-          <button
-            className="xx-template-use-btn"
-            onClick={(e) => {
-              e.stopPropagation()
-              onUse(template)
-            }}
-          >
-            使用此模板
-          </button>
-        </div>
-      </div>
-    </div>
-  )
-}
-
-/* ============================================================
- * 主组件
- * ============================================================ */
-
 const TemplateLibrary: React.FC = () => {
-  const navigate = useNavigate()
-  const queryClient = useQueryClient()
-
-  // 筛选状态
-  const [searchText, setSearchText] = useState("")
-  const [activeType, setActiveType] = useState<EditTemplateType | "全部">("全部")
-  const [durationRange, setDurationRange] = useState<"" | "short" | "medium" | "long">("")
-  const [page, setPage] = useState(1)
-  const [pageSize] = useState(12)
-
-  // 弹窗状态
-  const [previewTemplate, setPreviewTemplate] = useState<TemplateItem | null>(null)
-  const [detailLoading, setDetailLoading] = useState(false)
-
-  // ── 构建查询参数 ──
-  const queryParams: TemplateListParams = useMemo(() => {
-    const params: TemplateListParams = {
-      page,
-      page_size: pageSize,
-    }
-    if (activeType !== "全部") params.category = activeType
-    if (searchText.trim()) params.keyword = searchText.trim()
-    if (durationRange) params.duration_range = durationRange
-    return params
-  }, [page, pageSize, activeType, searchText, durationRange])
-
-  // ── 获取模板列表（后端分页 + 筛选） ──
   const {
-    data: templateData,
+    templates,
+    totalTemplates,
     isLoading,
     isError,
     error,
-  } = useQuery({
-    queryKey: ["templates", queryParams],
-    queryFn: () => getTemplates(queryParams),
-    staleTime: 30_000,
+    searchText,
+    activeType,
+    durationRange,
+    page,
+    pageSize,
+    setPage,
+    toggleFavorite,
+    handleCopy,
+    handleUse,
+    handleCreate,
+    handleSearchChange,
+    handleCategoryChange,
+    handleDurationChange,
+  } = useTemplateLibrary()
+
+  const {
+    previewTemplate,
+    detailLoading,
+    handlePreview,
+    handleClose,
+    handleToggleFavorite,
+    handleUse: handleUseFromDetail,
+    handleCopy: handleCopyFromDetail,
+  } = useTemplateDetail({
+    onToggleFavorite: (id) => toggleFavorite(id),
+    onUse: handleUse,
+    onCopy: handleCopy,
   })
 
-  const templates = templateData?.items ?? []
-  const totalTemplates = templateData?.total ?? 0
-
-  // ── 收藏 mutation ──
-  const favMutation = useMutation({
-    mutationFn: toggleFavoriteTemplate,
-    onSuccess: (_data, templateId) => {
-      queryClient.invalidateQueries({ queryKey: ["templates"] })
-      if (previewTemplate && previewTemplate.id === templateId) {
-        setPreviewTemplate((prev) => (prev ? { ...prev, is_favorite: !prev.is_favorite } : prev))
-      }
-    },
-  })
-
-  // ── 复制模板 mutation ──
-  const copyMutation = useMutation({
-    mutationFn: copyTemplate,
-    onSuccess: (data) => {
-      message.success(`模板「${data.name}」已复制到「我的模板」`)
-      queryClient.invalidateQueries({ queryKey: ["templates"] })
-    },
-    onError: () => {
-      message.error("复制模板失败，请稍后重试")
-    },
-  })
-
-  /** 切换收藏 */
-  const toggleFavorite = useCallback(
-    (id: string, e?: React.MouseEvent) => {
-      e?.stopPropagation()
-      favMutation.mutate(id)
-    },
-    [favMutation],
-  )
-
-  /** 点击卡片 → 获取详情并展示弹窗 */
-  const handlePreview = useCallback(async (template: TemplateItem) => {
-    setDetailLoading(true)
-    setPreviewTemplate(template)
-    try {
-      const detail = await getTemplate(template.id)
-      setPreviewTemplate(detail)
-    } catch {
-      // 详情加载失败时使用列表数据
-      message.warning("模板详情加载失败，显示摘要信息")
-    } finally {
-      setDetailLoading(false)
-    }
-  }, [])
-
-  /** 复制模板 */
-  const handleCopy = useCallback(
-    (template: TemplateItem) => {
-      copyMutation.mutate(template.id)
-    },
-    [copyMutation],
-  )
-
-  /** 使用模板 → 进入剪辑编辑器配置 */
-  const handleUse = useCallback(
-    (template: TemplateItem) => {
-      navigate(`/app/editing-planner?templateId=${template.id}`)
-    },
-    [navigate],
-  )
-
-  /** 搜索防抖处理 */
-  const handleSearchChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
-    setSearchText(e.target.value)
-    setPage(1)
-  }, [])
-
-  /** 切换分类 */
-  const handleCategoryChange = useCallback((type: EditTemplateType | "全部") => {
-    setActiveType(type)
-    setPage(1)
-  }, [])
-
-  /** 切换时长筛选 */
-  const handleDurationChange = useCallback((value: "" | "short" | "medium" | "long") => {
-    setDurationRange(value)
-    setPage(1)
-  }, [])
-
-  // ── Loading 状态 ──
-  if (isLoading) {
-    return (
-      <div className="xx-templates-page">
-        <div className="xx-templates-empty">
-          <div className="xx-templates-empty-icon">
-            <LoadingOutlined />
-          </div>
-          <h3>加载模板中...</h3>
-        </div>
-      </div>
-    )
-  }
-
-  // ── Error 状态 ──
-  if (isError) {
-    return (
-      <div className="xx-templates-page">
-        <div className="xx-templates-empty">
-          <div className="xx-templates-empty-icon">
-            <ExclamationCircleOutlined />
-          </div>
-          <h3>加载失败</h3>
-          <p>{error?.message || "网络异常，请稍后重试"}</p>
-        </div>
-      </div>
-    )
-  }
-
   return (
     <div className="xx-templates-page">
-      {/* ── 页面头部 ──────────────────────────────────────────── */}
-      <div className="xx-templates-header">
-        <div className="xx-templates-header-text">
-          <h2>模板库</h2>
-          <p>选择模板快速创建，支持自定义修改</p>
-        </div>
-        <Button type="primary" onClick={() => navigate("/app/editing-planner")}>
-          + 创建模板
-        </Button>
-      </div>
+      {/* 页面头部 */}
+      <TemplateHeader onCreateClick={handleCreate} />
 
-      {/* ── 工具栏：搜索 + 类型按钮组 + 时长筛选 ─────────────── */}
-      <div className="xx-templates-toolbar">
-        <div className="xx-templates-search">
-          <span className="xx-templates-search-icon">
-            <SearchOutlined />
-          </span>
-          <input
-            className="xx-templates-search-input"
-            type="text"
-            placeholder="搜索模板名称、描述或标签..."
-            value={searchText}
-            onChange={handleSearchChange}
-          />
-        </div>
-        <div className="xx-templates-categories">
-          {TEMPLATE_TYPES.map((cat) => (
-            <button
-              key={cat.type}
-              className={`xx-templates-cat-btn${activeType === cat.type ? " active" : ""}`}
-              onClick={() => handleCategoryChange(cat.type)}
-            >
-              <span className="xx-templates-cat-icon">{cat.icon}</span>
-              {cat.label}
-            </button>
-          ))}
-        </div>
-        {/* 时长筛选 */}
-        <div className="xx-templates-duration-filter">
-          {DURATION_OPTIONS.map((opt) => (
-            <button
-              key={opt.value}
-              className={`xx-templates-duration-btn${durationRange === opt.value ? " active" : ""}`}
-              onClick={() => handleDurationChange(opt.value)}
-            >
-              {opt.label}
-            </button>
-          ))}
-        </div>
-      </div>
+      {/* 工具栏：搜索 + 类型按钮组 + 时长筛选 */}
+      <TemplateToolbar
+        searchText={searchText}
+        onSearchChange={handleSearchChange}
+        activeType={activeType}
+        onTypeChange={handleCategoryChange}
+        durationRange={durationRange}
+        onDurationChange={handleDurationChange}
+      />
 
-      {/* ── 模板展示区 ────────────────────────────────────────── */}
-      {templates.length === 0 ? (
-        <div className="xx-templates-empty">
-          <div className="xx-templates-empty-icon">
-            <InboxOutlined />
-          </div>
-          <h3>
-            {searchText || activeType !== "全部" || durationRange ? "未找到匹配的模板" : "暂无模板"}
-          </h3>
-          <p>
-            {searchText || activeType !== "全部" || durationRange
-              ? "试试调整搜索条件或切换类型"
-              : "点击上方「创建模板」开始创作"}
-          </p>
-        </div>
-      ) : (
-        <>
-          <div className="xx-templates-grid">
-            {templates.map((tpl) => (
-              <TemplateCard
-                key={tpl.id}
-                template={tpl}
-                isFavorite={tpl.is_favorite ?? false}
-                onPreview={handlePreview}
-                onToggleFavorite={toggleFavorite}
-                onUse={handleUse}
-              />
-            ))}
-          </div>
+      {/* 模板展示区 */}
+      <TemplateGrid
+        templates={templates}
+        total={totalTemplates}
+        page={page}
+        pageSize={pageSize}
+        isLoading={isLoading}
+        isError={isError}
+        errorMessage={error?.message}
+        searchText={searchText}
+        activeType={activeType}
+        durationRange={durationRange}
+        onPageChange={setPage}
+        onPreview={handlePreview}
+        onToggleFavorite={toggleFavorite}
+        onUse={handleUse}
+      />
 
-          {/* 分页 */}
-          {totalTemplates > pageSize && (
-            <div className="xx-templates-pagination">
-              <Pagination
-                current={page}
-                pageSize={pageSize}
-                total={totalTemplates}
-                showSizeChanger={false}
-                showQuickJumper
-                showTotal={(total) => `共 ${total} 个模板`}
-                onChange={(p) => setPage(p)}
-              />
-            </div>
-          )}
-        </>
-      )}
-
-      {/* ── 详情弹窗 ──────────────────────────────────────────── */}
+      {/* 详情弹窗 */}
       {previewTemplate && (
         <TemplateDetailModal
           template={previewTemplate}
           isFavorite={previewTemplate.is_favorite ?? false}
-          onClose={() => setPreviewTemplate(null)}
-          onToggleFavorite={toggleFavorite}
-          onUse={handleUse}
-          onCopy={handleCopy}
+          onClose={handleClose}
+          onToggleFavorite={handleToggleFavorite}
+          onUse={handleUseFromDetail}
+          onCopy={handleCopyFromDetail}
         />
       )}
 
-      {/* 详情加载中的提示（可选覆盖层） */}
+      {/* 详情加载中的提示 */}
       {detailLoading && previewTemplate && (
-        <div className="xx-template-detail-loading">
-          <LoadingOutlined /> 加载中...
-        </div>
+        <div className="xx-template-detail-loading">加载中...</div>
       )}
     </div>
   )

apps/web/src/pages/templates/components/template-library/TemplateCard.tsx

@@ -0,0 +1,87 @@
+import React from "react"
+import { Tag } from "antd"
+import type { TemplateItem } from "@/api/templates"
+import { gradientForCategory, getTypeColor, formatDuration } from "../../utils/templateLibrary"
+
+interface TemplateCardProps {
+  template: TemplateItem
+  isFavorite: boolean
+  onPreview: (template: TemplateItem) => void
+  onToggleFavorite: (id: string, e: React.MouseEvent) => void
+  onUse: (template: TemplateItem) => void
+}
+
+export const TemplateCard: React.FC<TemplateCardProps> = ({
+  template,
+  isFavorite,
+  onPreview,
+  onToggleFavorite,
+  onUse,
+}) => {
+  return (
+    <div className="xx-template-card" onClick={() => onPreview(template)}>
+      {/* 缩略图 */}
+      <div className="xx-template-thumb">
+        {template.thumbnail_url ? (
+          <img src={template.thumbnail_url} alt={template.name} className="xx-template-thumb-img" />
+        ) : (
+          <div
+            className="xx-template-thumb-bg"
+            style={{ background: gradientForCategory(template.category) }}
+          >
+            {(template.description ?? "").slice(0, 80)}
+            {(template.description ?? "").length > 80 ? "..." : ""}
+          </div>
+        )}
+        <div className="xx-template-thumb-overlay" />
+        <div className="xx-template-thumb-name">{template.name}</div>
+        <div className="xx-template-thumb-meta">
+          <span className="xx-template-thumb-duration">
+            {formatDuration(template.estimated_duration ?? template.target_duration)}
+          </span>
+        </div>
+        <div className="xx-template-preview-hint">点击查看详情</div>
+        <button
+          className={`xx-template-fav-btn${isFavorite ? " is-favorite" : ""}`}
+          onClick={(e) => onToggleFavorite(template.id, e)}
+          title={isFavorite ? "取消收藏" : "收藏"}
+        >
+          {isFavorite ? "★" : "☆"}
+        </button>
+      </div>
+
+      {/* 信息区 */}
+      <div className="xx-template-info">
+        <div className="xx-template-info-top">
+          <span
+            className="xx-template-category-pill"
+            style={{
+              color: getTypeColor(template.category),
+              background: `${getTypeColor(template.category)}18`,
+            }}
+          >
+            {template.category}
+          </span>
+          {(template.tags ?? []).slice(0, 2).map((tag) => (
+            <Tag key={tag} className="xx-template-tag-pill" bordered={false}>
+              {tag}
+            </Tag>
+          ))}
+        </div>
+        <p className="xx-template-desc">{template.description ?? ""}</p>
+        <div className="xx-template-meta">
+          <span className="xx-template-usage">已使用 {template.usage_count ?? 0} 次</span>
+          <button
+            className="xx-template-use-btn"
+            onClick={(e) => {
+              e.stopPropagation()
+              onUse(template)
+            }}
+          >
+            使用此模板
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

apps/web/src/pages/templates/components/template-library/TemplateDetailModal.tsx

@@ -0,0 +1,219 @@
+import React from "react"
+import { Button, Descriptions, Tooltip } from "antd"
+import { CopyOutlined, ThunderboltOutlined } from "@ant-design/icons"
+import type { TemplateItem, TemplateSegment } from "@/api/templates"
+import {
+  gradientForCategory,
+  getTypeColor,
+  formatDuration,
+  formatConfig,
+  getMaterialTypeLabel,
+  calcTotalSegmentDuration,
+} from "../../utils/templateLibrary"
+import { TEMPLATE_TYPES } from "../../constants/templateLibrary"
+
+interface TemplateDetailModalProps {
+  template: TemplateItem
+  isFavorite: boolean
+  onClose: () => void
+  onToggleFavorite: (id: string) => void
+  onUse: (template: TemplateItem) => void
+  onCopy: (template: TemplateItem) => void
+}
+
+export const TemplateDetailModal: React.FC<TemplateDetailModalProps> = ({
+  template,
+  isFavorite,
+  onClose,
+  onToggleFavorite,
+  onUse,
+  onCopy,
+}) => {
+  const segments = template.segments ?? []
+  const totalSegmentDuration = calcTotalSegmentDuration(segments)
+
+  return (
+    <div className="xx-template-modal-overlay" onClick={onClose}>
+      <div
+        className="xx-template-modal xx-template-modal-wide"
+        onClick={(e) => e.stopPropagation()}
+      >
+        {/* 关闭按钮 */}
+        <button className="xx-template-modal-close" onClick={onClose} title="关闭">
+          ✕
+        </button>
+
+        {/* 预览区域 */}
+        <div
+          className="xx-template-modal-preview"
+          style={{ background: gradientForCategory(template.category) }}
+        >
+          {template.thumbnail_url ? (
+            <img
+              src={template.thumbnail_url}
+              alt={template.name}
+              className="xx-template-modal-thumb-img"
+            />
+          ) : (
+            <div className="xx-template-modal-preview-content">
+              <span className="xx-template-preview-icon">
+                {TEMPLATE_TYPES.find((t) => t.type === template.category)?.icon ?? "📋"}
+              </span>
+              <span className="xx-template-preview-title">{template.name}</span>
+            </div>
+          )}
+        </div>
+
+        {/* 内容区域 */}
+        <div className="xx-template-modal-content">
+          {/* 标题行 */}
+          <div className="xx-template-modal-title-row">
+            <h3>{template.name}</h3>
+            <span
+              className="xx-template-modal-type-badge"
+              style={{
+                color: getTypeColor(template.category),
+                background: `${getTypeColor(template.category)}18`,
+              }}
+            >
+              {TEMPLATE_TYPES.find((t) => t.type === template.category)?.icon} {template.category}
+            </span>
+          </div>
+
+          {/* 描述 */}
+          <p className="xx-template-modal-desc">{template.description}</p>
+
+          {/* 标签 */}
+          {(template.tags?.length ?? 0) > 0 && (
+            <div className="xx-template-modal-tags">
+              {template.tags!.map((tag) => (
+                <span key={tag} className="xx-template-modal-tag">
+                  #{tag}
+                </span>
+              ))}
+            </div>
+          )}
+
+          {/* 基本信息 */}
+          <Descriptions
+            column={2}
+            size="small"
+            className="xx-template-modal-desc-table"
+            items={[
+              {
+                key: "duration",
+                label: "目标时长",
+                children: formatDuration(template.estimated_duration ?? template.target_duration),
+              },
+              {
+                key: "clips",
+                label: "片段数量",
+                children: `${template.clip_count} 个`,
+              },
+              {
+                key: "ratio",
+                label: "视频比例",
+                children: template.aspect_ratio ?? "16:9",
+              },
+              {
+                key: "usage",
+                label: "使用次数",
+                children: `${template.usage_count ?? 0} 次`,
+              },
+            ]}
+          />
+
+          {/* 素材规则（片段配置） */}
+          {segments.length > 0 && (
+            <div className="xx-template-modal-section">
+              <h4>🎬 素材规则</h4>
+              <div className="xx-template-modal-clip-list">
+                {segments
+                  .sort((a, b) => a.segment_order - b.segment_order)
+                  .map((seg: TemplateSegment, idx: number) => (
+                    <div key={seg.id ?? idx} className="xx-template-modal-clip-item">
+                      <span className="xx-template-modal-clip-order">#{seg.segment_order}</span>
+                      <span
+                        className="xx-template-modal-clip-badge"
+                        style={{
+                          color: seg.material_type ? getTypeColor(seg.material_type) : "#64748b",
+                          background: seg.material_type
+                            ? `${getTypeColor(seg.material_type)}18`
+                            : "#f1f5f9",
+                        }}
+                      >
+                        {getMaterialTypeLabel(seg.material_type)}
+                      </span>
+                      <span className="xx-template-modal-clip-desc">
+                        {seg.description || `片段 ${seg.segment_order}`}
+                      </span>
+                      <Tooltip title={`时长范围: ${seg.duration_min}秒 - ${seg.duration_max}秒`}>
+                        <span className="xx-template-modal-clip-duration">
+                          {seg.duration_min}-{seg.duration_max}秒
+                        </span>
+                      </Tooltip>
+                    </div>
+                  ))}
+              </div>
+              <div className="xx-template-modal-total-duration">
+                预估总时长：{formatDuration(Math.round(totalSegmentDuration))}
+              </div>
+            </div>
+          )}
+
+          {/* 样式配置 */}
+          <div className="xx-template-modal-section">
+            <h4>🎨 样式配置</h4>
+            <div className="xx-template-modal-style-grid">
+              <div className="xx-template-modal-style-item">
+                <span className="xx-template-modal-style-label">字幕样式</span>
+                <span className="xx-template-modal-style-value">
+                  {formatConfig(template.subtitle_config)}
+                </span>
+              </div>
+              <div className="xx-template-modal-style-item">
+                <span className="xx-template-modal-style-label">标题样式</span>
+                <span className="xx-template-modal-style-value">
+                  {formatConfig(template.title_config)}
+                </span>
+              </div>
+              <div className="xx-template-modal-style-item">
+                <span className="xx-template-modal-style-label">BGM 配置</span>
+                <span className="xx-template-modal-style-value">
+                  {formatConfig(template.bgm_config)}
+                </span>
+              </div>
+              <div className="xx-template-modal-style-item">
+                <span className="xx-template-modal-style-label">视频比例</span>
+                <span className="xx-template-modal-style-value">
+                  {template.aspect_ratio ?? "16:9"}
+                </span>
+              </div>
+            </div>
+          </div>
+
+          {/* 统计信息 */}
+          <div className="xx-template-modal-stats">
+            <span>已使用 {template.usage_count ?? 0} 次</span>
+            <button
+              className={`xx-template-modal-fav-btn${isFavorite ? " is-favorite" : ""}`}
+              onClick={() => onToggleFavorite(template.id)}
+            >
+              {isFavorite ? "★ 已收藏" : "☆ 收藏"}
+            </button>
+          </div>
+
+          {/* 操作按钮 */}
+          <div className="xx-template-modal-actions">
+            <Button icon={<CopyOutlined />} onClick={() => onCopy(template)}>
+              复制模板
+            </Button>
+            <Button type="primary" icon={<ThunderboltOutlined />} onClick={() => onUse(template)}>
+              使用此模板生成
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

apps/web/src/pages/templates/components/template-library/TemplateGrid.tsx

@@ -0,0 +1,110 @@
+import React from "react"
+import { Pagination } from "antd"
+import { InboxOutlined, LoadingOutlined, ExclamationCircleOutlined } from "@ant-design/icons"
+import { TemplateCard } from "./TemplateCard"
+import type { TemplateItem } from "@/api/templates"
+
+interface TemplateGridProps {
+  templates: TemplateItem[]
+  total: number
+  page: number
+  pageSize: number
+  isLoading: boolean
+  isError: boolean
+  errorMessage?: string
+  searchText: string
+  activeType: string
+  durationRange: string
+  onPageChange: (page: number) => void
+  onPreview: (template: TemplateItem) => void
+  onToggleFavorite: (id: string, e: React.MouseEvent) => void
+  onUse: (template: TemplateItem) => void
+}
+
+export const TemplateGrid: React.FC<TemplateGridProps> = ({
+  templates,
+  total,
+  page,
+  pageSize,
+  isLoading,
+  isError,
+  errorMessage,
+  searchText,
+  activeType,
+  durationRange,
+  onPageChange,
+  onPreview,
+  onToggleFavorite,
+  onUse,
+}) => {
+  // Loading 状态
+  if (isLoading) {
+    return (
+      <div className="xx-templates-empty">
+        <div className="xx-templates-empty-icon">
+          <LoadingOutlined />
+        </div>
+        <h3>加载模板中...</h3>
+      </div>
+    )
+  }
+
+  // Error 状态
+  if (isError) {
+    return (
+      <div className="xx-templates-empty">
+        <div className="xx-templates-empty-icon">
+          <ExclamationCircleOutlined />
+        </div>
+        <h3>加载失败</h3>
+        <p>{errorMessage || "网络异常，请稍后重试"}</p>
+      </div>
+    )
+  }
+
+  // 空状态
+  if (templates.length === 0) {
+    const hasFilter = !!searchText || activeType !== "全部" || !!durationRange
+    return (
+      <div className="xx-templates-empty">
+        <div className="xx-templates-empty-icon">
+          <InboxOutlined />
+        </div>
+        <h3>{hasFilter ? "未找到匹配的模板" : "暂无模板"}</h3>
+        <p>{hasFilter ? "试试调整搜索条件或切换类型" : "点击上方「创建模板」开始创作"}</p>
+      </div>
+    )
+  }
+
+  return (
+    <>
+      <div className="xx-templates-grid">
+        {templates.map((tpl) => (
+          <TemplateCard
+            key={tpl.id}
+            template={tpl}
+            isFavorite={tpl.is_favorite ?? false}
+            onPreview={onPreview}
+            onToggleFavorite={onToggleFavorite}
+            onUse={onUse}
+          />
+        ))}
+      </div>
+
+      {/* 分页 */}
+      {total > pageSize && (
+        <div className="xx-templates-pagination">
+          <Pagination
+            current={page}
+            pageSize={pageSize}
+            total={total}
+            showSizeChanger={false}
+            showQuickJumper
+            showTotal={(t) => `共 ${t} 个模板`}
+            onChange={onPageChange}
+          />
+        </div>
+      )}
+    </>
+  )
+}

apps/web/src/pages/templates/components/template-library/TemplateHeader.tsx

@@ -0,0 +1,20 @@
+import React from "react"
+import { Button } from "antd"
+
+interface TemplateHeaderProps {
+  onCreateClick: () => void
+}
+
+export const TemplateHeader: React.FC<TemplateHeaderProps> = ({ onCreateClick }) => {
+  return (
+    <div className="xx-templates-header">
+      <div className="xx-templates-header-text">
+        <h2>模板库</h2>
+        <p>选择模板快速创建，支持自定义修改</p>
+      </div>
+      <Button type="primary" onClick={onCreateClick}>
+        + 创建模板
+      </Button>
+    </div>
+  )
+}

apps/web/src/pages/templates/components/template-library/TemplateToolbar.tsx

@@ -0,0 +1,63 @@
+import React from "react"
+import { SearchOutlined } from "@ant-design/icons"
+import type { EditTemplateType, DurationRange } from "../../types/templateLibrary"
+import { TEMPLATE_TYPES, DURATION_OPTIONS } from "../../constants/templateLibrary"
+
+interface TemplateToolbarProps {
+  searchText: string
+  onSearchChange: (e: React.ChangeEvent<HTMLInputElement>) => void
+  activeType: EditTemplateType | "全部"
+  onTypeChange: (type: EditTemplateType | "全部") => void
+  durationRange: DurationRange
+  onDurationChange: (value: DurationRange) => void
+}
+
+export const TemplateToolbar: React.FC<TemplateToolbarProps> = ({
+  searchText,
+  onSearchChange,
+  activeType,
+  onTypeChange,
+  durationRange,
+  onDurationChange,
+}) => {
+  return (
+    <div className="xx-templates-toolbar">
+      <div className="xx-templates-search">
+        <span className="xx-templates-search-icon">
+          <SearchOutlined />
+        </span>
+        <input
+          className="xx-templates-search-input"
+          type="text"
+          placeholder="搜索模板名称、描述或标签..."
+          value={searchText}
+          onChange={onSearchChange}
+        />
+      </div>
+      <div className="xx-templates-categories">
+        {TEMPLATE_TYPES.map((cat) => (
+          <button
+            key={cat.type}
+            className={`xx-templates-cat-btn${activeType === cat.type ? " active" : ""}`}
+            onClick={() => onTypeChange(cat.type)}
+          >
+            <span className="xx-templates-cat-icon">{cat.icon}</span>
+            {cat.label}
+          </button>
+        ))}
+      </div>
+      {/* 时长筛选 */}
+      <div className="xx-templates-duration-filter">
+        {DURATION_OPTIONS.map((opt) => (
+          <button
+            key={opt.value}
+            className={`xx-templates-duration-btn${durationRange === opt.value ? " active" : ""}`}
+            onClick={() => onDurationChange(opt.value)}
+          >
+            {opt.label}
+          </button>
+        ))}
+      </div>
+    </div>
+  )
+}

apps/web/src/pages/templates/constants/templateLibrary.ts

@@ -0,0 +1,46 @@
+import type { EditTemplateType, DurationRange } from "../types/templateLibrary"
+
+export const TEMPLATE_TYPES: Array<{
+  type: EditTemplateType | "全部"
+  label: string
+  icon: string
+  color: string
+}> = [
+  { type: "全部", label: "全部", icon: "📋", color: "#6366f1" },
+  { type: "口播", label: "口播", icon: "🎙️", color: "#6366f1" },
+  { type: "种草", label: "种草", icon: "🌱", color: "#10b981" },
+  { type: "产品", label: "产品", icon: "📦", color: "#0ea5e9" },
+  { type: "品牌", label: "品牌", icon: "🏷️", color: "#f59e0b" },
+  { type: "混剪", label: "混剪", icon: "🎬", color: "#8b5cf6" },
+  { type: "Vlog", label: "Vlog", icon: "📹", color: "#ec4899" },
+]
+
+export const DURATION_OPTIONS: Array<{
+  value: DurationRange
+  label: string
+}> = [
+  { value: "", label: "全部时长" },
+  { value: "short", label: "30秒以内" },
+  { value: "medium", label: "30秒-2分钟" },
+  { value: "long", label: "2分钟以上" },
+]
+
+export const MATERIAL_TYPE_LABELS: Record<string, string> = {
+  video: "视频",
+  image: "图片",
+  audio: "音频",
+  voiceover: "配音",
+  subtitle: "字幕",
+  null: "不限",
+}
+
+export const DEFAULT_PAGE_SIZE = 12
+export const CATEGORY_GRADIENT_MAP: Record<string, string> = {
+  口播: "linear-gradient(135deg, #6366f1, #8b5cf6)",
+  种草: "linear-gradient(135deg, #10b981, #059669)",
+  产品: "linear-gradient(135deg, #0ea5e9, #0284c7)",
+  品牌: "linear-gradient(135deg, #f59e0b, #d97706)",
+  混剪: "linear-gradient(135deg, #8b5cf6, #6d28d9)",
+  Vlog: "linear-gradient(135deg, #ec4899, #db2777)",
+}
+export const DEFAULT_GRADIENT = "linear-gradient(135deg, #6366f1, #8b5cf6)"

apps/web/src/pages/templates/hooks/useTemplateDetail.ts

@@ -0,0 +1,62 @@
+import { useState, useCallback } from "react"
+import { useQueryClient } from "@tanstack/react-query"
+import { message } from "antd"
+import { getTemplate, type TemplateItem } from "@/api/templates"
+
+interface UseTemplateDetailProps {
+  onToggleFavorite: (id: string) => void
+  onUse: (template: TemplateItem) => void
+  onCopy: (template: TemplateItem) => void
+}
+
+export const useTemplateDetail = ({ onToggleFavorite, onUse, onCopy }: UseTemplateDetailProps) => {
+  const queryClient = useQueryClient()
+
+  /* 弹窗状态 */
+  const [previewTemplate, setPreviewTemplate] = useState<TemplateItem | null>(null)
+  const [detailLoading, setDetailLoading] = useState(false)
+
+  /* 点击卡片 → 获取详情并展示弹窗 */
+  const handlePreview = useCallback(async (template: TemplateItem) => {
+    setDetailLoading(true)
+    setPreviewTemplate(template)
+    try {
+      const detail = await getTemplate(template.id)
+      setPreviewTemplate(detail)
+    } catch {
+      message.warning("模板详情加载失败，显示摘要信息")
+    } finally {
+      setDetailLoading(false)
+    }
+  }, [])
+
+  /* 关闭弹窗 */
+  const handleClose = useCallback(() => {
+    setPreviewTemplate(null)
+    setDetailLoading(false)
+  }, [])
+
+  /* 收藏切换（同时更新预览模板的状态） */
+  const handleToggleFavorite = useCallback(
+    (id: string) => {
+      onToggleFavorite(id)
+      /* 乐观更新详情弹窗的收藏状态 */
+      setPreviewTemplate((prev) =>
+        prev && prev.id === id ? { ...prev, is_favorite: !prev.is_favorite } : prev,
+      )
+      /* 刷新列表缓存 */
+      queryClient.invalidateQueries({ queryKey: ["templates"] })
+    },
+    [onToggleFavorite, queryClient],
+  )
+
+  return {
+    previewTemplate,
+    detailLoading,
+    handlePreview,
+    handleClose,
+    handleToggleFavorite,
+    handleUse: onUse,
+    handleCopy: onCopy,
+  }
+}

apps/web/src/pages/templates/hooks/useTemplateLibrary.ts

@@ -0,0 +1,147 @@
+import { useState, useMemo, useCallback } from "react"
+import { useNavigate } from "react-router-dom"
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
+import { message } from "antd"
+import {
+  getTemplates,
+  toggleFavoriteTemplate,
+  copyTemplate,
+  type TemplateItem,
+  type TemplateListParams,
+} from "@/api/templates"
+import type { EditTemplateType, DurationRange } from "../types/templateLibrary"
+import { DEFAULT_PAGE_SIZE } from "../constants/templateLibrary"
+
+export const useTemplateLibrary = () => {
+  const navigate = useNavigate()
+  const queryClient = useQueryClient()
+
+  /* 筛选状态 */
+  const [searchText, setSearchText] = useState("")
+  const [activeType, setActiveType] = useState<EditTemplateType | "全部">("全部")
+  const [durationRange, setDurationRange] = useState<DurationRange>("")
+  const [page, setPage] = useState(1)
+  const [pageSize] = useState(DEFAULT_PAGE_SIZE)
+
+  /* 构建查询参数 */
+  const queryParams: TemplateListParams = useMemo(() => {
+    const params: TemplateListParams = {
+      page,
+      page_size: pageSize,
+    }
+    if (activeType !== "全部") params.category = activeType
+    if (searchText.trim()) params.keyword = searchText.trim()
+    if (durationRange) params.duration_range = durationRange
+    return params
+  }, [page, pageSize, activeType, searchText, durationRange])
+
+  /* 获取模板列表 */
+  const {
+    data: templateData,
+    isLoading,
+    isError,
+    error,
+  } = useQuery({
+    queryKey: ["templates", queryParams],
+    queryFn: () => getTemplates(queryParams),
+    staleTime: 30_000,
+  })
+
+  const templates = templateData?.items ?? []
+  const totalTemplates = templateData?.total ?? 0
+
+  /* 收藏 mutation */
+  const favMutation = useMutation({
+    mutationFn: toggleFavoriteTemplate,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["templates"] })
+    },
+  })
+
+  /* 复制模板 mutation */
+  const copyMutation = useMutation({
+    mutationFn: copyTemplate,
+    onSuccess: (data) => {
+      message.success(`模板「${data.name}」已复制到「我的模板」`)
+      queryClient.invalidateQueries({ queryKey: ["templates"] })
+    },
+    onError: () => {
+      message.error("复制模板失败，请稍后重试")
+    },
+  })
+
+  /* 操作：切换收藏 */
+  const toggleFavorite = useCallback(
+    (id: string, e?: React.MouseEvent) => {
+      e?.stopPropagation()
+      favMutation.mutate(id)
+    },
+    [favMutation],
+  )
+
+  /* 操作：复制模板 */
+  const handleCopy = useCallback(
+    (template: TemplateItem) => {
+      copyMutation.mutate(template.id)
+    },
+    [copyMutation],
+  )
+
+  /* 操作：使用模板 → 跳转剪辑编辑器 */
+  const handleUse = useCallback(
+    (template: TemplateItem) => {
+      navigate(`/app/editing-planner?templateId=${template.id}`)
+    },
+    [navigate],
+  )
+
+  /* 操作：创建模板 */
+  const handleCreate = useCallback(() => {
+    navigate("/app/editing-planner")
+  }, [navigate])
+
+  /* 搜索 */
+  const handleSearchChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    setSearchText(e.target.value)
+    setPage(1)
+  }, [])
+
+  /* 切换分类 */
+  const handleCategoryChange = useCallback((type: EditTemplateType | "全部") => {
+    setActiveType(type)
+    setPage(1)
+  }, [])
+
+  /* 切换时长筛选 */
+  const handleDurationChange = useCallback((value: DurationRange) => {
+    setDurationRange(value)
+    setPage(1)
+  }, [])
+
+  return {
+    /* 状态 */
+    templates,
+    totalTemplates,
+    isLoading,
+    isError,
+    error,
+    searchText,
+    activeType,
+    durationRange,
+    page,
+    pageSize,
+    /* mutations */
+    favMutation,
+    copyMutation,
+    /* setters */
+    setPage,
+    /* handlers */
+    toggleFavorite,
+    handleCopy,
+    handleUse,
+    handleCreate,
+    handleSearchChange,
+    handleCategoryChange,
+    handleDurationChange,
+  }
+}

apps/web/src/pages/templates/types/templateLibrary.ts

@@ -0,0 +1,15 @@
+/** 模板类型 */
+export type EditTemplateType = "口播" | "种草" | "产品" | "品牌" | "混剪" | "Vlog"
+
+/** 时长筛选值 */
+export type DurationRange = "" | "short" | "medium" | "long"
+
+/** 配置展示字段 */
+export interface ConfigDisplayFields {
+  font_size?: string | number
+  font_family?: string
+  color?: string
+  position?: string
+  volume?: string | number
+  name?: string
+}

apps/web/src/pages/templates/utils/templateLibrary.ts

@@ -0,0 +1,54 @@
+import type { ConfigDisplayFields } from "../types/templateLibrary"
+import {
+  TEMPLATE_TYPES,
+  CATEGORY_GRADIENT_MAP,
+  DEFAULT_GRADIENT,
+  MATERIAL_TYPE_LABELS,
+} from "../constants/templateLibrary"
+import type { TemplateSegment } from "@/api/templates"
+
+/** 获取类型对应颜色 */
+export const getTypeColor = (type: string): string => {
+  const found = TEMPLATE_TYPES.find((t) => t.type === type)
+  return found?.color ?? "#6366f1"
+}
+
+/** 根据 category 生成占位渐变色 */
+export const gradientForCategory = (category: string): string => {
+  return CATEGORY_GRADIENT_MAP[category] ?? DEFAULT_GRADIENT
+}
+
+/** 格式化时长 */
+export const formatDuration = (seconds: number | undefined | null): string => {
+  if (!seconds || seconds <= 0) return "0秒"
+  const totalSec = Math.round(seconds)
+  const m = Math.floor(totalSec / 60)
+  const s = totalSec % 60
+  if (m === 0) return `${s}秒`
+  return `${m}分${s > 0 ? `${s}秒` : ""}`
+}
+
+/** 格式化配置对象为可读文本 */
+export const formatConfig = (config?: object): string => {
+  if (!config || Object.keys(config).length === 0) return "默认"
+  const c = config as ConfigDisplayFields
+  const parts: string[] = []
+  if (c.font_size) parts.push(`字号: ${c.font_size}`)
+  if (c.font_family) parts.push(`字体: ${c.font_family}`)
+  if (c.color) parts.push(`颜色: ${c.color}`)
+  if (c.position) parts.push(`位置: ${c.position}`)
+  if (c.volume !== undefined) parts.push(`音量: ${c.volume}%`)
+  if (c.name) parts.push(String(c.name))
+  return parts.length > 0 ? parts.join(" / ") : JSON.stringify(config)
+}
+
+/** 获取素材类型标签文本 */
+export const getMaterialTypeLabel = (materialType: string | null | undefined): string => {
+  if (!materialType) return "不限"
+  return MATERIAL_TYPE_LABELS[materialType] ?? materialType
+}
+
+/** 计算片段总时长（取每个片段 min/max 的平均值） */
+export const calcTotalSegmentDuration = (segments: TemplateSegment[]): number => {
+  return segments.reduce((sum, s) => sum + (s.duration_min + s.duration_max) / 2, 0)
+}