refactor(templates): 拆分 MyTemplates 页面，抽离数据 Hook + 卡片组件

主文件 254→130 行（-49%），拆分为：
- useMyTemplates: 模板列表查询、筛选、删除、复制等数据操作
- TemplateCard: 单个模板卡片组件
- MyTemplates: 页面入口 + 布局

导入路径保持向后兼容

.gitea/workflows/ci-health-daily.yml

@@ -8,7 +8,7 @@ permissions:
 jobs:
   ci-health-report:
     name: CI健康度每日巡检
-    runs-on: saas
+    runs-on: ci-l2
     timeout-minutes: 15
     steps:
     - name: Checkout code

.gitea/workflows/ci-pipeline.yml

@@ -58,24 +58,56 @@ jobs:
       run: |
         set -eu
         PR_NUMBER=$(echo "$GITHUB_REF" | sed 's|refs/pull/||; s|/.*||')
-        API_URL="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?limit=300"
-        FILES=$(curl -s -H "Authorization: token ${GITHUB_TOKEN}" "$API_URL" | python3 -c "import sys,json; [print(f['filename']) for f in json.load(sys.stdin)]")
-        FRONTEND_COUNT=$(echo "$FILES" | grep -c '^apps/web/' || true)
-        BACKEND_COUNT=$(echo "$FILES" | grep -cv '^apps/web/' || true)
-        TOTAL=$(echo "$FILES" | grep -cv '^$' || true)
-        echo "变更文件: ${TOTAL} 个 (前端: ${FRONTEND_COUNT}, 后端/公共: ${BACKEND_COUNT})"
-        if [ "$BACKEND_COUNT" = "0" ] && [ "$FRONTEND_COUNT" -gt "0" ]; then
+
+        # 分页获取所有变更文件（修复>300文件时漏判）
+        ALL_FILES=""
+        PAGE=1
+        while true; do
+          API_URL="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?limit=300&page=${PAGE}"
+          PAGE_FILES=$(curl -s -H "Authorization: token ${GITHUB_TOKEN}" "$API_URL" | python3 -c "import sys,json; files=json.load(sys.stdin); [print(f['filename']) for f in files]; sys.exit(0 if len(files)==300 else 1)" 2>/dev/null || true)
+          PAGE_COUNT=$(echo "$PAGE_FILES" | wc -l)
+          if [ "$PAGE_COUNT" -lt 300 ]; then HAS_MORE=1; else HAS_MORE=0; fi
+          ALL_FILES="${ALL_FILES}${PAGE_FILES}"$'\n'
+          if [ "$HAS_MORE" != "0" ]; then
+            break
+          fi
+          PAGE=$((PAGE + 1))
+        done
+
+        FRONTEND_COUNT=$(echo "$ALL_FILES" | grep -c '^apps/web/' || true)
+        TOTAL=$(echo "$ALL_FILES" | grep -cv '^$' || true)
+        BACKEND_COUNT=$(( TOTAL - FRONTEND_COUNT ))
+
+        # 基础设施文件：改了就强制全量CI（不跳过任何检查）
+        INFRA_COUNT=$(echo "$ALL_FILES" | grep -cE '^(infra/|Dockerfile|\.gitea/workflows/|scripts/ci/|docker/)' || true)
+
+        echo "变更文件: ${TOTAL} 个 (前端: ${FRONTEND_COUNT}, 后端/公共: ${BACKEND_COUNT}, 基础设施: ${INFRA_COUNT})"
+
+        # 判定是否纯前端/纯后端
+        PURE_FRONTEND=false
+        PURE_BACKEND=false
+        if [ "$BACKEND_COUNT" = "0" ] && [ "$FRONTEND_COUNT" -gt "0" ] && [ "$INFRA_COUNT" = "0" ]; then
+          PURE_FRONTEND=true
+        elif [ "$FRONTEND_COUNT" = "0" ] && [ "$BACKEND_COUNT" -gt "0" ] && [ "$INFRA_COUNT" = "0" ]; then
+          PURE_BACKEND=true
+        fi
+
+        if [ "$PURE_FRONTEND" = "true" ]; then
           echo "skip_backend=true" >> $GITHUB_OUTPUT
           echo "skip_frontend=false" >> $GITHUB_OUTPUT
           echo "✅ 纯前端改动，跳过后端检查"
-        elif [ "$FRONTEND_COUNT" = "0" ] && [ "$BACKEND_COUNT" -gt "0" ]; then
+        elif [ "$PURE_BACKEND" = "true" ]; then
           echo "skip_backend=false" >> $GITHUB_OUTPUT
           echo "skip_frontend=true" >> $GITHUB_OUTPUT
           echo "🔧 纯后端改动，跳过前端检查"
         else
           echo "skip_backend=false" >> $GITHUB_OUTPUT
           echo "skip_frontend=false" >> $GITHUB_OUTPUT
-          echo "🔧 包含全栈变更，运行完整CI"
+          if [ "$INFRA_COUNT" -gt "0" ]; then
+            echo "🏗️  包含基础设施变更，强制运行完整CI"
+          else
+            echo "🔧 包含全栈变更，运行完整CI"
+          fi
         fi
 
     - name: Report CI trace
@@ -1588,7 +1620,6 @@ jobs:
         set -eu
         python3 scripts/ci/acr_cleanup.py \
           --keep 20 \
-          --pr-days 7 \
           --execute
 
     - name: Job duration summary

.gitea/workflows/ci-trigger-monitor.yml

@@ -16,15 +16,15 @@ permissions:
 jobs:
   monitor:
     name: Monitor CI Trigger Reliability
-    runs-on: ubuntu-latest
+    runs-on: ci-l2
     timeout-minutes: 5
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
-        # 网络波动自动重试2次
-        retry:
-          max_attempts: 2
-          retry_on: error
+        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
       
       - name: Check CI trigger status for all open PRs
         env:

.gitea/workflows/code-review.yml

@@ -15,20 +15,18 @@ concurrency:
 jobs:
   code-review:
     name: AI Code Review
-    runs-on: ubuntu-latest
+    runs-on: ci-l2
     # 跳过草稿 PR
     if: ${{ !gitea.event.pull_request.draft }}
 
     steps:
       # actions/checkout 由 runner 在宿主机层面处理，不受容器网络影响
       - name: Checkout code
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-        # 网络波动自动重试2次
-        retry:
-          max_attempts: 2
-          retry_on: error
+        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
 
       - name: Install dependencies
         run: |

.gitea/workflows/daily-check.yml

@@ -12,7 +12,7 @@ jobs:
   # ── 1. 生产环境冒烟测试 ─────────────────────────────────────────────
   production-smoke:
     name: Production Smoke Test
-    runs-on: saas
+    runs-on: ci-l2
     timeout-minutes: 8
     outputs:
       report: ${{ steps.smoke.outputs.report }}
@@ -121,7 +121,7 @@ jobs:
   # ── 2. Staging API 集成测试 ─────────────────────────────────────────
   staging-api-tests:
     name: Staging API Integration Tests
-    runs-on: saas
+    runs-on: ci-l2
     timeout-minutes: 10
     outputs:
       report: ${{ steps.smoke.outputs.report }}
@@ -176,6 +176,9 @@ jobs:
       - name: Run API smoke test on staging
         id: smoke
         shell: sh
+        env:
+          STAGING_TEST_USER: ${{ secrets.STAGING_TEST_USER }}
+          STAGING_TEST_PASSWORD: ${{ secrets.STAGING_TEST_PASSWORD }}
         run: |
           set +e
           START_TIME=$(date +%s)
@@ -183,8 +186,8 @@ jobs:
           docker run --rm \
             -e BASE_URL=https://staging-api.xiaoxiajianji.com \
             -e WEB_URL=https://staging.xiaoxiajianji.com \
-            -e TEST_USER=18314979086@163.com \
-            -e TEST_PASSWORD=Ying1234 \
+            -e TEST_USER="$STAGING_TEST_USER" \
+            -e TEST_PASSWORD="$STAGING_TEST_PASSWORD" \
             -e CLEANUP_ENABLED=1 \
             -e PERF_CHECK_ENABLED=1 \
             -e PERF_WARN_THRESHOLD_MS=500 \
@@ -270,7 +273,7 @@ jobs:
   # ── 3. Staging 浏览器 E2E ──────────────────────────────────────────
   staging-e2e:
     name: Staging Browser E2E
-    runs-on: saas
+    runs-on: ci-l2
     timeout-minutes: 15
     outputs:
       report: ${{ steps.smoke.outputs.report }}
@@ -371,7 +374,7 @@ jobs:
   # ── 4. 性能基线巡检 ────────────────────────────────────────────────
   performance-check:
     name: Performance Baseline Check
-    runs-on: saas
+    runs-on: ci-l2
     timeout-minutes: 8
     outputs:
       report: ${{ steps.report.outputs.report }}
@@ -380,6 +383,9 @@ jobs:
       - name: Run performance baseline checks
         id: perf
         shell: sh
+        env:
+          STAGING_TEST_USER: ${{ secrets.STAGING_TEST_USER }}
+          STAGING_TEST_PASSWORD: ${{ secrets.STAGING_TEST_PASSWORD }}
         run: |
           set +e
           START_TIME=$(date +%s)
@@ -415,9 +421,10 @@ jobs:
 
           # 先登录获取 token
           echo "--- 准备: 获取测试 Token ---"
+          LOGIN_BODY="{\"email\":\"$STAGING_TEST_USER\",\"password\":\"$STAGING_TEST_PASSWORD\"}"
           AUTH_RESP=$(curl -s -w "\n%{http_code}" -X POST \
             -H "Content-Type: application/json" \
-            -d '{"email":"18314979086@163.com","password":"Ying1234"}' \
+            -d "$LOGIN_BODY" \
             "https://staging-api.xiaoxiajianji.com/api/v1/auth/login" \
             --max-time 10 2>&1)
           AUTH_CODE=$(echo "$AUTH_RESP" | tail -1)
@@ -447,7 +454,7 @@ jobs:
             # 构建 curl 命令
             CURL_ARGS="-s -o /dev/null -w '%{http_code} %{time_total}' --max-time 30"
             if [ "$method" = "POST" ]; then
-              CURL_ARGS="$CURL_ARGS -X POST -H 'Content-Type: application/json' -d '{\"email\":\"18314979086@163.com\",\"password\":\"Ying1234\"}'"
+              CURL_ARGS="$CURL_ARGS -X POST -H 'Content-Type: application/json' -d \"$LOGIN_BODY\""
             fi
             if [ -n "$TOKEN" ] && [ "$name" != "健康检查" ]; then
               CURL_ARGS="$CURL_ARGS -H 'Authorization: Bearer $TOKEN'"
@@ -495,6 +502,9 @@ jobs:
       - name: Generate performance report
         id: report
         shell: sh
+        env:
+          STAGING_TEST_USER: ${{ secrets.STAGING_TEST_USER }}
+          STAGING_TEST_PASSWORD: ${{ secrets.STAGING_TEST_PASSWORD }}
         run: |
           set +e
           echo ""
@@ -509,10 +519,11 @@ jobs:
           RESULTS=""
           START_TIME=$(date +%s)
 
+          LOGIN_BODY="{\"email\":\"$STAGING_TEST_USER\",\"password\":\"$STAGING_TEST_PASSWORD\"}"
           # 先登录获取 token
           AUTH_RESP=$(curl -s -w "\n%{http_code}" -X POST \
             -H "Content-Type: application/json" \
-            -d '{"email":"18314979086@163.com","password":"Ying1234"}' \
+            -d "$LOGIN_BODY" \
             "https://staging-api.xiaoxiajianji.com/api/v1/auth/login" \
             --max-time 10 2>&1)
           AUTH_CODE=$(echo "$AUTH_RESP" | tail -1)
@@ -528,7 +539,7 @@ jobs:
 
             local CURL_ARGS="-s -o /dev/null -w '%{http_code} %{time_total}' --max-time 30"
             if [ "$method" = "POST" ]; then
-              CURL_ARGS="$CURL_ARGS -X POST -H 'Content-Type: application/json' -d '{\"email\":\"18314979086@163.com\",\"password\":\"Ying1234\"}'"
+              CURL_ARGS="$CURL_ARGS -X POST -H 'Content-Type: application/json' -d \"$LOGIN_BODY\""
             fi
             if [ -n "$TOKEN" ] && [ "$name" != "健康检查" ]; then
               CURL_ARGS="$CURL_ARGS -H 'Authorization: Bearer $TOKEN'"
@@ -631,7 +642,7 @@ jobs:
   # ── 5. 每日巡检汇总报告 ────────────────────────────────────────────
   daily-report:
     name: Daily Check Report
-    runs-on: saas
+    runs-on: ci-l2
     timeout-minutes: 2
     if: always()
     needs:

.gitea/workflows/preview-deploy.yml

@@ -93,44 +93,31 @@ jobs:
       shell: sh
       run: |
         set -eu
-        NPM_CACHE_VOLUME="xiaoxia-npm-cache"
-        if ! docker volume inspect "$NPM_CACHE_VOLUME" >/dev/null 2>&1; then
-          docker volume create "$NPM_CACHE_VOLUME" >/dev/null
-          echo "Created npm cache volume: $NPM_CACHE_VOLUME"
-        fi
+        cd apps/web
 
-        docker run --rm \
-          -v "$PWD:/workspace" \
-          -v "$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules" \
-          -w /workspace/apps/web \
-          -e VITE_API_URL=https://staging-api.xiaoxiajianji.com \
-          docker.m.daocloud.io/library/node:20 \
-          sh -lc '
-            PACKAGE_LOCK_HASH=$(md5sum package-lock.json 2>/dev/null | cut -d" " -f1)
-            CACHE_HASH_FILE="node_modules/.package-lock-hash"
-            CACHE_VALID=false
-            if [ -f "$CACHE_HASH_FILE" ] && [ "$(cat "$CACHE_HASH_FILE")" = "$PACKAGE_LOCK_HASH" ] && [ -x "node_modules/.bin/vite" ] && [ -x "node_modules/.bin/tsc" ]; then
-              CACHE_VALID=true
-              echo "Cache hit: dependencies valid, skipping npm ci"
-            fi
-            if [ "$CACHE_VALID" = "false" ]; then
-              echo "Cache miss or invalid: running npm ci..."
-              if ! npm ci; then
-                echo "npm ci failed, cleaning node_modules and retrying..."
-                rm -rf node_modules
-                mkdir -p node_modules
-                npm ci
-              fi
-              echo "$PACKAGE_LOCK_HASH" > "$CACHE_HASH_FILE"
-              echo "Dependencies installed, cache updated"
-            fi
-            echo "Running TypeScript check..."
-            npx --no-install tsc
-            echo "Running Vite build..."
-            npx --no-install vite build
-            echo "Build completed successfully"
-            ls -la dist/
-          '
+        # Config npm mirror for speed
+        npm config set registry https://registry.npmmirror.com
+
+        # Install dependencies with retry
+        for i in 1 2 3; do
+          npm ci --no-audit --no-fund && break
+          echo "npm ci failed, retry $i/3..."
+          [ $i -eq 3 ] && exit 1
+          rm -rf node_modules
+          sleep 5
+        done
+
+        # TypeScript check
+        echo "=== TypeScript check ==="
+        npx --no-install tsc --noEmit
+
+        # Vite build
+        echo "=== Vite build ==="
+        export VITE_API_URL=https://staging-api.xiaoxiajianji.com
+        npx --no-install vite build
+
+        echo "=== Build completed ==="
+        ls -la dist/
 
     - name: Install SSH client and rsync
       shell: sh

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

@@ -26,6 +26,13 @@ from packages.domain.edit_plan import EditPlan
 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
 
 logger = logging.getLogger(__name__)
@@ -163,83 +170,18 @@ class PlanGeneratorService:
         plan_id: str,
         clip_configs: List[TemplateClipConfig],
     ) -> List[EditPlanClip]:
-        """从 TemplateClipConfig 列表创建 EditPlanClip 列表（未持久化）"""
-        clips: List[EditPlanClip] = []
-        # 按 order 排序
-        sorted_configs = sorted(clip_configs, key=lambda c: c.order)
+        """从 TemplateClipConfig 列表创建 EditPlanClip 列表（未持久化）.
 
-        for cfg in sorted_configs:
-            # 计算时长：取 min_duration 和 max_duration 的中间值
-            if cfg.min_duration > 0 and cfg.max_duration > 0:
-                duration = (cfg.min_duration + cfg.max_duration) / 2
-            elif cfg.min_duration > 0:
-                duration = cfg.min_duration
-            elif cfg.max_duration > 0:
-                duration = cfg.max_duration
-            else:
-                duration = _DEFAULT_CLIP_DURATION
-
-            # clip_type 可能是枚举或字符串
-            clip_type = cfg.clip_type.value if hasattr(cfg.clip_type, "value") else cfg.clip_type
-
-            # transition_effect 可能是枚举或字符串
-            transition = (
-                cfg.transition_effect.value if hasattr(cfg.transition_effect, "value") else cfg.transition_effect
-            )
-
-            # 从 clip config 中解析 playback_speed（兼容 speed_ratio 字段名）
-            clip_cfg = cfg.config or {}
-            playback_speed = clip_cfg.get("playback_speed", clip_cfg.get("speed_ratio", 1.0)) or 1.0
-
-            clip = EditPlanClip.create(
-                plan_id=plan_id,
-                clip_type=clip_type,
-                order=cfg.order,
-                template_clip_config_id=cfg.id,
-                text_content=getattr(cfg, "text_template", "") or "",
-                duration=duration,
-                transition_effect=transition or "cut",
-                playback_speed=playback_speed,
-                config=clip_cfg,
-            )
-            clips.append(clip)
-
-        return clips
+        委托给 plan_generator_utils.create_clips_from_configs 纯函数。
+        """
+        return create_clips_from_configs(plan_id, clip_configs)
 
     def _map_clip_types_for_mode(self, clips: List[EditPlanClip], editing_mode: str) -> None:
-        """将模板 clip_config 生成的 MAIN 类型片段，按 editing_mode 映射为对应角色类型。
+        """将 MAIN 类型片段按 editing_mode 映射为对应角色类型.
 
-        模板的 clip_config 使用 ClipType 枚举（main/intro/outro 等），
-        但 PIP / VOICE_PIP 模式的素材分配和渲染分层依赖特定的 clip_type 命名
-        （overlay / background / corner_voice / b_roll）。
-
-        映射规则（仅修改 MAIN 类型片段，非 MAIN 片段保持原类型）：
-        - PIP: 第1个 MAIN → main（背景），其余 MAIN → overlay（画中画）
-        - VOICE_PIP: 第1个 → background，第2个 → corner_voice，第3+个 → b_roll
-        - ONE_TAKE / VOICE_OVER: 保持 main 不变
+        委托给 plan_generator_utils.map_clip_types_for_mode 纯函数。
         """
-        from packages.domain.template_clip_config import ClipType
-
-        main_clips = [c for c in clips if c.clip_type == ClipType.MAIN.value]
-        if not main_clips:
-            return
-
-        if editing_mode == EditingMode.PIP.value:
-            # 第1个 main 保持（背景层），其余改为 overlay（画中画层）
-            for i, clip in enumerate(main_clips):
-                if i > 0:
-                    clip.clip_type = "overlay"
-
-        elif editing_mode == EditingMode.VOICE_PIP.value:
-            for i, clip in enumerate(main_clips):
-                if i == 0:
-                    clip.clip_type = "background"
-                elif i == 1:
-                    clip.clip_type = "corner_voice"
-                else:
-                    clip.clip_type = "b_roll"
-
-        # ONE_TAKE / VOICE_OVER: 保持 main 不变，无需处理
+        map_clip_types_for_mode(clips, editing_mode)
 
     def _generate_default_clips(
         self,
@@ -247,101 +189,11 @@ class PlanGeneratorService:
         editing_mode: str,
         asset_count: int,
     ) -> List[EditPlanClip]:
-        """无 clip_configs 时，根据 editing_mode 生成默认 clip 结构
+        """无 clip_configs 时，根据 editing_mode 生成默认 clip 结构.
 
-        - ONE_TAKE: N 个 main clips（N = asset_count，至少1个）
-        - PIP: 1 个 main + (N-1) 个 overlay（N = asset_count）
-        - VOICE_OVER: N 个 main clips + 标记需要配音
-        - VOICE_PIP: 1 个 background + 1 个 corner_voice + (N-2) 个 b_roll
+        委托给 plan_generator_utils.generate_default_clips 纯函数。
         """
-        n = max(asset_count, 1)
-        clips: List[EditPlanClip] = []
-        order = 0
-
-        if editing_mode == EditingMode.PIP.value:
-            # 1 个 main（全屏背景）
-            clips.append(
-                EditPlanClip.create(
-                    plan_id=plan_id,
-                    clip_type=ClipType.MAIN.value,
-                    order=order,
-                    duration=_DEFAULT_CLIP_DURATION,
-                )
-            )
-            order += 1
-            # 剩余为 overlay
-            for _ in range(1, n):
-                clips.append(
-                    EditPlanClip.create(
-                        plan_id=plan_id,
-                        clip_type="overlay",
-                        order=order,
-                        duration=_DEFAULT_CLIP_DURATION,
-                    )
-                )
-                order += 1
-
-        elif editing_mode == EditingMode.VOICE_OVER.value:
-            # N 个 main clips（B-roll）
-            for _ in range(n):
-                clips.append(
-                    EditPlanClip.create(
-                        plan_id=plan_id,
-                        clip_type=ClipType.MAIN.value,
-                        order=order,
-                        duration=_DEFAULT_CLIP_DURATION,
-                        config={"role": "b_roll"},
-                    )
-                )
-                order += 1
-
-        elif editing_mode == EditingMode.VOICE_PIP.value:
-            # 1 个 background
-            clips.append(
-                EditPlanClip.create(
-                    plan_id=plan_id,
-                    clip_type="background",
-                    order=order,
-                    duration=_DEFAULT_CLIP_DURATION,
-                )
-            )
-            order += 1
-            # 1 个 corner_voice
-            clips.append(
-                EditPlanClip.create(
-                    plan_id=plan_id,
-                    clip_type="corner_voice",
-                    order=order,
-                    duration=_DEFAULT_CLIP_DURATION,
-                )
-            )
-            order += 1
-            # 剩余为 b_roll
-            for _ in range(2, n):
-                clips.append(
-                    EditPlanClip.create(
-                        plan_id=plan_id,
-                        clip_type="b_roll",
-                        order=order,
-                        duration=_DEFAULT_CLIP_DURATION,
-                    )
-                )
-                order += 1
-
-        else:
-            # ONE_TAKE: N 个 main clips
-            for _ in range(n):
-                clips.append(
-                    EditPlanClip.create(
-                        plan_id=plan_id,
-                        clip_type=ClipType.MAIN.value,
-                        order=order,
-                        duration=_DEFAULT_CLIP_DURATION,
-                    )
-                )
-                order += 1
-
-        return clips
+        return generate_default_clips(plan_id, editing_mode, asset_count)
 
     def _distribute_assets(
         self,
@@ -349,89 +201,8 @@ class PlanGeneratorService:
         asset_ids: List[str],
         editing_mode: str,
     ) -> None:
-        """按 editing_mode 将素材分配到 clips（就地修改，未持久化）
+        """按 editing_mode 将素材分配到 clips（就地修改，未持久化）.
 
-        分配策略:
-        - ONE_TAKE: 素材按顺序依次分配给 main 类型 clips
-        - PIP: 第1个素材→main(全屏背景)，其余→交替分配给 overlay clips
-        - VOICE_OVER: 素材→main clips (B-roll)
-        - VOICE_PIP: 第1个→background, 第2个→corner_voice, 其余→b_roll
+        委托给 plan_generator_utils.distribute_assets 纯函数。
         """
-        if not asset_ids or not clips:
-            return
-
-        if editing_mode == EditingMode.ONE_TAKE.value:
-            self._distribute_one_take(clips, asset_ids)
-        elif editing_mode == EditingMode.PIP.value:
-            self._distribute_pip(clips, asset_ids)
-        elif editing_mode == EditingMode.VOICE_OVER.value:
-            self._distribute_voice_over(clips, asset_ids)
-        elif editing_mode == EditingMode.VOICE_PIP.value:
-            self._distribute_voice_pip(clips, asset_ids)
-        else:
-            # 未知模式，退化为 one_take
-            self._distribute_one_take(clips, asset_ids)
-
-    def _distribute_one_take(
-        self,
-        clips: List[EditPlanClip],
-        asset_ids: List[str],
-    ) -> None:
-        """ONE_TAKE: 素材按顺序依次分配给 main 类型 clips"""
-        main_clips = [c for c in clips if c.clip_type == ClipType.MAIN.value]
-        for i, clip in enumerate(main_clips):
-            if i < len(asset_ids):
-                clip.assign_asset(asset_ids[i])
-
-    def _distribute_pip(
-        self,
-        clips: List[EditPlanClip],
-        asset_ids: List[str],
-    ) -> None:
-        """PIP: 第1个素材→main(全屏背景)，其余→overlay clips"""
-        # 第1个素材 → main clip
-        main_clips = [c for c in clips if c.clip_type == ClipType.MAIN.value]
-        if main_clips and asset_ids:
-            main_clips[0].assign_asset(asset_ids[0])
-
-        # 其余素材 → overlay clips
-        overlay_clips = [c for c in clips if c.clip_type == "overlay"]
-        remaining = asset_ids[1:]
-        for i, clip in enumerate(overlay_clips):
-            if i < len(remaining):
-                clip.assign_asset(remaining[i])
-
-    def _distribute_voice_over(
-        self,
-        clips: List[EditPlanClip],
-        asset_ids: List[str],
-    ) -> None:
-        """VOICE_OVER: 素材→main clips (B-roll)"""
-        main_clips = [c for c in clips if c.clip_type == ClipType.MAIN.value]
-        for i, clip in enumerate(main_clips):
-            if i < len(asset_ids):
-                clip.assign_asset(asset_ids[i])
-
-    def _distribute_voice_pip(
-        self,
-        clips: List[EditPlanClip],
-        asset_ids: List[str],
-    ) -> None:
-        """VOICE_PIP: 第1个→background, 第2个→corner_voice, 其余→b_roll"""
-        bg_clips = [c for c in clips if c.clip_type == "background"]
-        corner_clips = [c for c in clips if c.clip_type == "corner_voice"]
-        broll_clips = [c for c in clips if c.clip_type == "b_roll"]
-
-        # 第1个素材 → background
-        if bg_clips and len(asset_ids) > 0:
-            bg_clips[0].assign_asset(asset_ids[0])
-
-        # 第2个素材 → corner_voice
-        if corner_clips and len(asset_ids) > 1:
-            corner_clips[0].assign_asset(asset_ids[1])
-
-        # 其余素材 → b_roll
-        remaining = asset_ids[2:]
-        for i, clip in enumerate(broll_clips):
-            if i < len(remaining):
-                clip.assign_asset(remaining[i])
+        distribute_assets(clips, asset_ids, editing_mode)

apps/api/app/services/smart_asset_selector.py

@@ -13,57 +13,31 @@
   - 最低质量分门槛：自动过滤低质量素材
   - 时长多样性：保证选出的素材时长分布均匀（短/中/长各占一定比例）
   - 兼容全部模式：素材库模式和项目模式都可用
+
+纯逻辑部分已抽离到 packages.domain.asset_scoring。
 """
 
 from __future__ import annotations
 
 import logging
-from dataclasses import dataclass
+
+from packages.domain.asset_scoring import MEDIUM_BUCKET_MAX as _MEDIUM_BUCKET_MAX
+from packages.domain.asset_scoring import MIN_QUALITY_SCORE as _MIN_QUALITY_SCORE
+from packages.domain.asset_scoring import OPTIMAL_DURATION_MAX as _OPTIMAL_DURATION_MAX
+from packages.domain.asset_scoring import OPTIMAL_DURATION_MIN as _OPTIMAL_DURATION_MIN
+from packages.domain.asset_scoring import SHORT_BUCKET_MAX as _SHORT_BUCKET_MAX
+from packages.domain.asset_scoring import TARGET_HEIGHT as _TARGET_HEIGHT
+from packages.domain.asset_scoring import TARGET_WIDTH as _TARGET_WIDTH
+from packages.domain.asset_scoring import (
+    AssetScoreDetail,
+    SmartSelectResult,
+    diverse_selection,
+    filter_candidates,
+    score_asset_detail,
+)
 
 logger = logging.getLogger(__name__)
 
-# ── 评分权重 ──────────────────────────────────────────────────────────────────
-_WEIGHT_QUALITY = 0.5
-_WEIGHT_RESOLUTION = 0.2
-_WEIGHT_DURATION = 0.2
-_WEIGHT_BITRATE = 0.1
-
-# ── 评分参数 ──────────────────────────────────────────────────────────────────
-_TARGET_WIDTH = 1920  # 目标分辨率宽度基准
-_TARGET_HEIGHT = 1080  # 目标分辨率高度基准
-_MIN_QUALITY_SCORE = 30.0  # 最低质量分门槛（低于此值的素材直接排除）
-_OPTIMAL_DURATION_MIN = 3.0  # 最佳时长区间（秒）
-_OPTIMAL_DURATION_MAX = 30.0
-
-# ── 多样性分桶 ───────────────────────────────────────────────────────────────
-_SHORT_BUCKET_MAX = 5.0  # 短素材：< 5s
-_MEDIUM_BUCKET_MAX = 15.0  # 中素材：5-15s
-# 长素材：> 15s
-
-
-@dataclass
-class SmartSelectResult:
-    """智能选择结果."""
-
-    selected_ids: list[str]
-    total_candidates: int
-    filtered_out: int  # 被质量门槛过滤的数量
-    avg_score: float
-    details: list[AssetScoreDetail]
-
-
-@dataclass
-class AssetScoreDetail:
-    """单个素材的评分详情."""
-
-    asset_id: str
-    total_score: float
-    quality_score: float
-    resolution_score: float
-    duration_score: float
-    bitrate_score: float
-    duration: float | None
-
 
 class SmartAssetSelector:
     """智能素材选择器.
@@ -74,9 +48,9 @@ class SmartAssetSelector:
 
     def __init__(
         self,
-        min_quality_score: float = _MIN_QUALITY_SCORE,
-        target_width: int = _TARGET_WIDTH,
-        target_height: int = _TARGET_HEIGHT,
+        min_quality_score: float = 30.0,
+        target_width: int = 1920,
+        target_height: int = 1080,
     ):
         self.min_quality_score = min_quality_score
         self.target_width = target_width
@@ -102,21 +76,7 @@ class SmartAssetSelector:
             SmartSelectResult 选择结果
         """
         # 1. 过滤：只保留 ready 状态的视频素材 + 最低质量分门槛
-        candidates = []
-        filtered_out = 0
-        for asset in assets:
-            status = getattr(asset, "status", None)
-            status_val = status.value if hasattr(status, "value") else str(status)
-            if status_val != "ready":
-                continue
-            mime_type = getattr(asset, "mime_type", "") or ""
-            if not mime_type.startswith("video"):
-                continue
-            quality = getattr(asset, "quality_score", None)
-            if quality is not None and quality < self.min_quality_score:
-                filtered_out += 1
-                continue
-            candidates.append(asset)
+        candidates, filtered_out = filter_candidates(assets, self.min_quality_score)
 
         if not candidates:
             return SmartSelectResult(
@@ -130,7 +90,16 @@ class SmartAssetSelector:
         # 2. 对每个候选素材评分
         scored: list[AssetScoreDetail] = []
         for asset in candidates:
-            detail = self._score_asset(asset)
+            detail = score_asset_detail(
+                asset_id=asset.id,
+                quality=getattr(asset, "quality_score", None),
+                width=getattr(asset, "width", None),
+                height=getattr(asset, "height", None),
+                duration=getattr(asset, "duration", None),
+                file_size=getattr(asset, "file_size", 0) or 0,
+                target_width=self.target_width,
+                target_height=self.target_height,
+            )
             scored.append(detail)
 
         # 3. 按总分降序排列
@@ -138,7 +107,7 @@ class SmartAssetSelector:
 
         # 4. 多样性选择（如果需要且数量有限制）
         if ensure_diversity and count > 0 and len(scored) > count:
-            selected = self._diverse_selection(scored, count)
+            selected = diverse_selection(scored, count)
         else:
             # 无数量限制或不要求多样性，直接按排名取
             selected = scored if count <= 0 else scored[:count]
@@ -162,165 +131,39 @@ class SmartAssetSelector:
         )
         return result
 
-    # ── 内部方法 ──────────────────────────────────────────────────────────────
+    # ── 向后兼容：私有方法别名（委托给 asset_scoring 纯函数） ────────────────
 
     def _score_asset(self, asset) -> AssetScoreDetail:
-        """对单个素材进行多维度评分."""
-        # 质量分
-        quality = getattr(asset, "quality_score", None)
-        quality_score = (quality / 100.0) if quality is not None else 0.5
-
-        # 分辨率评分：越接近目标分辨率得分越高
-        width = getattr(asset, "width", None)
-        height = getattr(asset, "height", None)
-        resolution_score = self._score_resolution(width, height)
-
-        # 时长评分：在最佳区间内得分高，过短过长扣分
-        duration = getattr(asset, "duration", None)
-        duration_score = self._score_duration(duration)
-
-        # 码率评分：用 file_size/duration 估算，适中得分高
-        file_size = getattr(asset, "file_size", 0) or 0
-        bitrate_score = self._score_bitrate(file_size, duration)
-
-        # 加权总分
-        total = (
-            _WEIGHT_QUALITY * quality_score
-            + _WEIGHT_RESOLUTION * resolution_score
-            + _WEIGHT_DURATION * duration_score
-            + _WEIGHT_BITRATE * bitrate_score
-        )
-
-        return AssetScoreDetail(
+        """对单个素材进行多维度评分（向后兼容）."""
+        return score_asset_detail(
             asset_id=asset.id,
-            total_score=round(total, 4),
-            quality_score=round(quality_score, 4),
-            resolution_score=round(resolution_score, 4),
-            duration_score=round(duration_score, 4),
-            bitrate_score=round(bitrate_score, 4),
-            duration=duration,
+            quality=getattr(asset, "quality_score", None),
+            width=getattr(asset, "width", None),
+            height=getattr(asset, "height", None),
+            duration=getattr(asset, "duration", None),
+            file_size=getattr(asset, "file_size", 0) or 0,
+            target_width=self.target_width,
+            target_height=self.target_height,
         )
 
     def _score_resolution(self, width: int | None, height: int | None) -> float:
-        """分辨率评分：越接近目标分辨率得分越高，低于480p扣分严重."""
-        if width is None or height is None or width <= 0 or height <= 0:
-            return 0.5  # 未知分辨率给中评分
+        """分辨率评分（向后兼容）."""
+        from packages.domain.asset_scoring import score_resolution
 
-        target_pixels = self.target_width * self.target_height
-        actual_pixels = width * height
-
-        # 计算像素数比例
-        ratio = actual_pixels / target_pixels
-
-        if ratio >= 1.0:
-            # 高于或等于目标分辨率：满分，略高不扣分（4K也给满分）
-            return 1.0
-        else:
-            # 低于目标分辨率：线性衰减，但最低不低于 0.1
-            # 例如：720p (921600) / 1080p (2073600) = 0.44 → 得分 0.6
-            score = 0.3 + 0.7 * ratio
-            return max(0.1, min(1.0, score))
+        return score_resolution(width, height, self.target_width, self.target_height)
 
     def _score_duration(self, duration: float | None) -> float:
-        """时长评分：3-30秒最佳，过短或过长都扣分."""
-        if duration is None or duration <= 0:
-            return 0.5  # 未知时长给中评分
+        """时长评分（向后兼容）."""
+        from packages.domain.asset_scoring import score_duration
 
-        if _OPTIMAL_DURATION_MIN <= duration <= _OPTIMAL_DURATION_MAX:
-            # 最佳区间：满分
-            return 1.0
-
-        if duration < _OPTIMAL_DURATION_MIN:
-            # 太短：线性衰减，1秒以下给 0.3
-            ratio = duration / _OPTIMAL_DURATION_MIN
-            return 0.3 + 0.7 * ratio
-
-        # 太长：每超过最佳区间上限10秒扣 0.1 分，最低 0.2
-        excess = duration - _OPTIMAL_DURATION_MAX
-        penalty = min(0.8, excess / 10.0 * 0.1)
-        return max(0.2, 1.0 - penalty)
+        return score_duration(duration)
 
     def _score_bitrate(self, file_size: int, duration: float | None) -> float:
-        """码率评分：根据文件大小和时长估算码率，适中得分高."""
-        if not file_size or not duration or duration <= 0:
-            return 0.5  # 未知给中评分
+        """码率评分（向后兼容）."""
+        from packages.domain.asset_scoring import score_bitrate
 
-        # 估算码率（bps）
-        bitrate = (file_size * 8) / duration
-
-        # 最佳码率范围：2-8 Mbps
-        optimal_low = 2_000_000  # 2 Mbps
-        optimal_high = 8_000_000  # 8 Mbps
-
-        if optimal_low <= bitrate <= optimal_high:
-            return 1.0
-
-        if bitrate < optimal_low:
-            # 码率太低：线性衰减
-            ratio = bitrate / optimal_low
-            return 0.3 + 0.7 * ratio
-
-        # 码率太高（文件太大）：适度扣分
-        excess = bitrate / optimal_high - 1.0
-        penalty = min(0.5, excess * 0.2)
-        return max(0.5, 1.0 - penalty)
+        return score_bitrate(file_size, duration)
 
     def _diverse_selection(self, scored: list[AssetScoreDetail], count: int) -> list[AssetScoreDetail]:
-        """多样性选择：按时长分桶，保证每个桶都有素材.
-
-        策略：
-        1. 按时长分为三桶：短(<5s)、中(5-15s)、长(>15s)
-        2. 每个桶配额 = max(1, count / 3)
-        3. 先从每桶按配额取最高分的
-        4. 剩余名额从全局最高分中取（不重复）
-        """
-        # 分桶
-        short_bucket = [d for d in scored if d.duration is not None and d.duration < _SHORT_BUCKET_MAX]
-        medium_bucket = [
-            d for d in scored if d.duration is not None and _SHORT_BUCKET_MAX <= d.duration < _MEDIUM_BUCKET_MAX
-        ]
-        long_bucket = [d for d in scored if d.duration is not None and d.duration >= _MEDIUM_BUCKET_MAX]
-        unknown_bucket = [d for d in scored if d.duration is None]
-
-        buckets = [short_bucket, medium_bucket, long_bucket]
-        bucket_names = ["short", "medium", "long"]
-
-        # 每个桶基础配额（至少1个，如果桶非空且需要的话）
-        base_quota = max(1, count // 3)
-
-        selected: list[AssetScoreDetail] = []
-        selected_ids: set[str] = set()
-
-        # 先按配额从每个桶取
-        for bucket, _name in zip(buckets, bucket_names, strict=False):
-            quota = min(base_quota, len(bucket))
-            if quota <= 0:
-                continue
-            # 桶内已经按分数排好序了，直接取前 quota 个
-            for item in bucket[:quota]:
-                if item.asset_id not in selected_ids:
-                    selected.append(item)
-                    selected_ids.add(item.asset_id)
-                    if len(selected) >= count:
-                        return selected
-
-        # 剩余名额：从全局（未被选中的）中按分数高低取
-        remaining_needed = count - len(selected)
-        if remaining_needed > 0:
-            for item in scored:
-                if item.asset_id not in selected_ids:
-                    selected.append(item)
-                    selected_ids.add(item.asset_id)
-                    if len(selected) >= count:
-                        break
-
-        # 如果还不够（不应该发生），加上未知时长的
-        if len(selected) < count and unknown_bucket:
-            for item in unknown_bucket:
-                if item.asset_id not in selected_ids:
-                    selected.append(item)
-                    selected_ids.add(item.asset_id)
-                    if len(selected) >= count:
-                        break
-
-        return selected[:count]
+        """多样性选择（向后兼容）."""
+        return diverse_selection(scored, count)

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/editing-planner/components/ClipPropertiesPanel.tsx

@@ -2,99 +2,13 @@
  * 右栏设置面板 — V8 原型 1:1 还原
  * 字幕设置 + BGM设置 + 片段详情
  */
-import React, { useRef, useState, useCallback } from "react"
-import { useNavigate } from "react-router-dom"
-import type { TemplateMode } from "@/api/editing-planner"
-import type { ClipData, ClipType } from "../types"
-import { TRANSITION_OPTIONS } from "@/api/template-editor"
-import type { AssetItem } from "@/api/assets"
-
-interface SubtitleSettings {
-  enabled: boolean
-  position: string
-  font: string
-  fontSize: number
-  fontColor: string
-  animation: string
-  mode?: string
-  stroke?: boolean
-  shadow?: boolean
-  asrLanguage?: string
-}
-
-interface BgmSettings {
-  enabled: boolean
-  music_id: string
-  volume?: number
-  fade_in?: number
-  fade_out?: number
-  voice_dodge?: boolean
-}
-
-interface ClipPropertiesPanelProps {
-  selectedClip: ClipData | null
-  subtitleSettings: SubtitleSettings
-  bgmSettings: BgmSettings
-  clipsCount: number
-  totalDuration: number
-  currentMode: TemplateMode
-  onSubtitleSettingsChange: (partial: Partial<SubtitleSettings>) => void
-  onBgmSettingsChange: (partial: Partial<BgmSettings>) => void
-  onClipUpdate: (clipId: string, data: Partial<ClipData>) => void
-  /** 打开 BGM 选择器 Drawer */
-  onOpenBgmDrawer?: () => void
-  /** 打开字幕样式配置 Drawer */
-  onOpenSubtitleDrawer?: () => void
-  /** 配音素材列表（从配音库 API 获取） */
-  voiceMaterials?: AssetItem[]
-  /** 配音素材加载中 */
-  voiceMaterialsLoading?: boolean
-  /** 刷新配音素材列表 */
-  onRefreshVoiceMaterials?: () => void
-  /** 为片段选择配音素材 */
-  onClipVoiceSelect?: (clipId: string, asset: AssetItem | null) => void
-  /** 打开转场特效选择器 Drawer */
-  onOpenTransitionDrawer?: (clipId: string) => void
-  /** 打开片段调速面板 Drawer */
-  onOpenSpeedDrawer?: (clipId: string) => void
-  /** 打开 TTS 配音面板 Drawer */
-  onOpenTtsDrawer?: (clipId: string) => void
-  /** 打开水印设置面板 Drawer */
-  onOpenWatermarkDrawer?: () => void
-  /** 打开片头片尾设置面板 Drawer */
-  onOpenIntroOutroDrawer?: () => void
-  /** 打开混剪设置面板 Drawer */
-  onOpenPipDrawer?: () => void
-  /** 打开滤镜调色面板 Drawer */
-  onOpenFilterDrawer?: () => void
-  /** 打开绿幕抠像面板 Drawer */
-  onOpenGreenScreenDrawer?: () => void
-  /** 打开贴纸面板 Drawer */
-  onOpenStickerDrawer?: () => void
-  /** 打开封面选择器 Drawer */
-}
-
-const POSITION_OPTIONS = [
-  { value: "top", label: "顶部" },
-  { value: "center", label: "居中" },
-  { value: "bottom", label: "底部" },
-]
-
-const FONT_OPTIONS = ["思源黑体", "思源宋体", "苹方", "PingFang", "微软雅黑", "楷体", "华康俪金黑"]
-
-const ANIMATION_OPTIONS = [
-  { value: "none", label: "无" },
-  { value: "fade", label: "淡入淡出" },
-  { value: "slide", label: "滑动" },
-  { value: "typewriter", label: "打字机" },
-]
-
-/** 片段类型图标/标签 */
-const CLIP_TYPE_ICONS: Record<ClipType, string> = { voice: "🎙️", pip: "🖼️" }
-const CLIP_TYPE_LABELS: Record<ClipType, string> = {
-  voice: "口播",
-  pip: "混剪",
-}
+import React from "react"
+import type { ClipPropertiesPanelProps } from "@/pages/editing-planner/types/clipProperties"
+import SubtitleSettingsSection from "./clip-properties/SubtitleSettingsSection"
+import BgmSettingsSection from "./clip-properties/BgmSettingsSection"
+import ClipDetailSection from "./clip-properties/ClipDetailSection"
+import StatsSection from "./clip-properties/StatsSection"
+import { useVoicePreview } from "@/pages/editing-planner/hooks/useVoicePreview"
 
 const ClipPropertiesPanel: React.FC<ClipPropertiesPanelProps> = ({
   selectedClip,
@@ -122,165 +36,19 @@ const ClipPropertiesPanel: React.FC<ClipPropertiesPanelProps> = ({
   onOpenGreenScreenDrawer,
   onOpenStickerDrawer,
 }) => {
-  const navigate = useNavigate()
+  const { previewingId, handlePreviewVoice, stopPreview } = useVoicePreview()
 
-  /* ── 配音试听 ── */
-  const audioRef = useRef<HTMLAudioElement | null>(null)
-  const [previewingId, setPreviewingId] = useState<string | null>(null)
-
-  /** 试听配音素材 */
-  const handlePreviewVoice = useCallback(
-    (asset: AssetItem) => {
-      // 点击同一个 → 暂停
-      if (previewingId === asset.id) {
-        audioRef.current?.pause()
-        setPreviewingId(null)
-        return
-      }
-      // 停止上一个
-      audioRef.current?.pause()
-      const url = asset.file_url || (asset.metadata?.preview_url as string)
-      if (!url) return
-      const audio = new Audio(url)
-      audioRef.current = audio
-      audio.play().catch(() => {})
-      audio.onended = () => setPreviewingId(null)
-      setPreviewingId(asset.id)
-    },
-    [previewingId],
-  )
-
-  /** 从 metadata 取性别标签 */
-  const getGenderLabel = (m: AssetItem): string => {
-    const g = (m.metadata?.gender as string) || ""
-    if (g === "male") return "男"
-    if (g === "female") return "女"
-    return ""
-  }
   return (
     <div className="ep-right-panel">
       {/* ═══ 字幕设置 ═══ */}
-      <div className="ep-settings-section">
-        <div className="ep-section-title">
-          <span className="ep-section-icon">💬</span>
-          字幕设置
-        </div>
-
-        <div className="ep-toggle-row">
-          <span className="ep-toggle-label">启用字幕</span>
-          <div
-            className={`ep-toggle ${subtitleSettings.enabled ? "active" : ""}`}
-            onClick={() =>
-              onSubtitleSettingsChange({
-                enabled: !subtitleSettings.enabled,
-              })
-            }
-          >
-            <div className="ep-toggle-knob" />
-          </div>
-        </div>
-
-        {subtitleSettings.enabled && (
-          <>
-            <div className="ep-field">
-              <label className="ep-field-label">位置</label>
-              <select
-                className="ep-form-select"
-                value={subtitleSettings.position}
-                onChange={(e) => onSubtitleSettingsChange({ position: e.target.value })}
-              >
-                {POSITION_OPTIONS.map((opt) => (
-                  <option key={opt.value} value={opt.value}>
-                    {opt.label}
-                  </option>
-                ))}
-              </select>
-            </div>
-
-            <div className="ep-field">
-              <label className="ep-field-label">字体</label>
-              <select
-                className="ep-form-select"
-                value={subtitleSettings.font}
-                onChange={(e) => onSubtitleSettingsChange({ font: e.target.value })}
-              >
-                {FONT_OPTIONS.map((f) => (
-                  <option key={f} value={f}>
-                    {f}
-                  </option>
-                ))}
-              </select>
-            </div>
-
-            <div className="ep-field">
-              <label className="ep-field-label">大小</label>
-              <div className="ep-slider-row">
-                <input
-                  className="ep-slider"
-                  type="range"
-                  min={12}
-                  max={48}
-                  value={subtitleSettings.fontSize}
-                  onChange={(e) =>
-                    onSubtitleSettingsChange({
-                      fontSize: Number(e.target.value),
-                    })
-                  }
-                />
-                <span className="ep-slider-value">{subtitleSettings.fontSize}px</span>
-              </div>
-            </div>
-
-            <div className="ep-field">
-              <label className="ep-field-label">动画</label>
-              <select
-                className="ep-form-select"
-                value={subtitleSettings.animation}
-                onChange={(e) => onSubtitleSettingsChange({ animation: e.target.value })}
-              >
-                {ANIMATION_OPTIONS.map((opt) => (
-                  <option key={opt.value} value={opt.value}>
-                    {opt.label}
-                  </option>
-                ))}
-              </select>
-            </div>
-
-            {/* 高级配置按钮 */}
-            {onOpenSubtitleDrawer && (
-              <button className="ep-advanced-btn" onClick={onOpenSubtitleDrawer}>
-                🎨 高级字幕样式配置
-              </button>
-            )}
-          </>
-        )}
-      </div>
+      <SubtitleSettingsSection
+        settings={subtitleSettings}
+        onChange={onSubtitleSettingsChange}
+        onOpenSubtitleDrawer={onOpenSubtitleDrawer}
+      />
 
       {/* ═══ BGM 设置 ═══ */}
-      <div className="ep-settings-section">
-        <div className="ep-section-title">
-          <span className="ep-section-icon">🎵</span>
-          BGM 设置
-        </div>
-
-        {bgmSettings.enabled && bgmSettings.music_id ? (
-          <div className="ep-bgm-current">
-            <span className="ep-bgm-current-label">🎵 已选择 BGM</span>
-            <span className="ep-bgm-current-id">{bgmSettings.music_id}</span>
-            {bgmSettings.volume !== undefined && (
-              <span className="ep-bgm-current-vol">音量 {bgmSettings.volume}%</span>
-            )}
-          </div>
-        ) : (
-          <div className="ep-bgm-empty">未选择背景音乐</div>
-        )}
-
-        {onOpenBgmDrawer && (
-          <button className="ep-advanced-btn" onClick={onOpenBgmDrawer}>
-            🎵 {bgmSettings.enabled ? "更换 BGM / 调整混音" : "选择 BGM 音乐"}
-          </button>
-        )}
-      </div>
+      <BgmSettingsSection settings={bgmSettings} onOpenBgmDrawer={onOpenBgmDrawer} />
 
       {/* ═══ 水印设置 ═══ */}
       <div className="ep-settings-section">
@@ -374,258 +142,30 @@ const ClipPropertiesPanel: React.FC<ClipPropertiesPanelProps> = ({
 
       {/* ═══ 片段详情（选中时显示） ═══ */}
       {selectedClip && (
-        <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 =
-                    currentMode === "pip"
-                      ? t !== "pip"
-                      : currentMode === "voice_over"
-                        ? t !== "voice"
-                        : false // voice_pip 可切换
-                  return (
-                    <button
-                      key={t}
-                      className={`ep-clip-type-btn${selectedClip.type === t ? " active" : ""}${disabled ? " disabled" : ""}`}
-                      disabled={disabled}
-                      onClick={() => !disabled && onClipUpdate(selectedClip.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={selectedClip.duration}
-                  onChange={(e) =>
-                    onClipUpdate(selectedClip.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(selectedClip.id)}
-                >
-                  <span className="ep-advanced-btn-icon">🎬</span>
-                  <span className="ep-advanced-btn-label">转场效果</span>
-                  <span className="ep-advanced-btn-value">
-                    {(() => {
-                      const t = selectedClip.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`
-                    })()}
-                  </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(selectedClip.id)}
-                >
-                  <span className="ep-advanced-btn-icon">⚡</span>
-                  <span className="ep-advanced-btn-label">播放速度</span>
-                  <span className="ep-advanced-btn-value">
-                    {selectedClip.speed ? `${selectedClip.speed.rate.toFixed(2)}x` : "1.00x"}
-                  </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(selectedClip.id)}
-                >
-                  <span className="ep-advanced-btn-icon">🎙️</span>
-                  <span className="ep-advanced-btn-label">TTS 配音</span>
-                  <span className="ep-advanced-btn-value">
-                    {(() => {
-                      const tts = selectedClip.tts_config
-                      if (!tts || tts.mode === "none") return "无配音"
-                      if (tts.mode === "upload") return "上传配音"
-                      return `TTS · ${tts.voice_id ? "已选音色" : "未选音色"}`
-                    })()}
-                  </span>
-                  <span className="ep-advanced-btn-arrow">›</span>
-                </button>
-              </div>
-            )}
-
-            {/* 素材起始时间 — 仅 voice 类型显示 */}
-            {selectedClip.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={selectedClip.startOffset}
-                    onChange={(e) =>
-                      onClipUpdate(selectedClip.id, {
-                        startOffset: Math.max(0, Math.min(9999, Number(e.target.value) || 0)),
-                      })
-                    }
-                  />
-                  <span className="ep-clip-detail-unit">秒</span>
-                </div>
-              </div>
-            )}
-
-            {/* 配音素材选择 — 仅 voice 类型显示 */}
-            {selectedClip.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={selectedClip.voice_asset_id ?? ""}
-                        onChange={(e) => {
-                          const assetId = e.target.value
-                          if (!onClipVoiceSelect) return
-                          if (!assetId) {
-                            onClipVoiceSelect(selectedClip.id, null)
-                          } else {
-                            const asset = voiceMaterials.find((m) => m.id === assetId)
-                            if (asset) onClipVoiceSelect(selectedClip.id, asset)
-                          }
-                          // 切换选择时停止试听
-                          audioRef.current?.pause()
-                          setPreviewingId(null)
-                        }}
-                      >
-                        <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>
-                      {/* 试听按钮 */}
-                      {selectedClip.voice_asset_id && (
-                        <button
-                          type="button"
-                          className="ep-voice-preview-btn"
-                          title={previewingId === selectedClip.voice_asset_id ? "暂停" : "试听"}
-                          onClick={() => {
-                            const asset = voiceMaterials.find(
-                              (m) => m.id === selectedClip.voice_asset_id,
-                            )
-                            if (asset) handlePreviewVoice(asset)
-                          }}
-                        >
-                          {previewingId === selectedClip.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>
+        <ClipDetailSection
+          clip={selectedClip}
+          currentMode={currentMode}
+          voiceMaterials={voiceMaterials}
+          voiceMaterialsLoading={voiceMaterialsLoading}
+          onClipUpdate={onClipUpdate}
+          onRefreshVoiceMaterials={onRefreshVoiceMaterials}
+          onClipVoiceSelect={onClipVoiceSelect}
+          onOpenTransitionDrawer={onOpenTransitionDrawer}
+          onOpenSpeedDrawer={onOpenSpeedDrawer}
+          onOpenTtsDrawer={onOpenTtsDrawer}
+          previewingId={previewingId}
+          onPreviewVoice={handlePreviewVoice}
+          onStopPreview={stopPreview}
+        />
       )}
 
-      {/* ═══ 统计信息（始终显示） ═══ */}
+      {/* ═══ 统计信息（未选中时显示） ═══ */}
       {!selectedClip && (
-        <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-detail-value">{clipsCount}</div>
-            </div>
-            <div className="ep-clip-detail-field">
-              <div className="ep-clip-detail-label">总时长</div>
-              <div className="ep-clip-detail-value">{totalDuration.toFixed(1)}s</div>
-            </div>
-            <div className="ep-clip-detail-field">
-              <div className="ep-clip-detail-label">当前模式</div>
-              <div className="ep-clip-detail-value">
-                {currentMode === "pip"
-                  ? "混剪"
-                  : currentMode === "voice_over"
-                    ? "人物口播"
-                    : currentMode === "one_take"
-                      ? "一镜到底"
-                      : "口播+混剪"}
-              </div>
-            </div>
-          </div>
-        </div>
+        <StatsSection
+          clipsCount={clipsCount}
+          totalDuration={totalDuration}
+          currentMode={currentMode}
+        />
       )}
     </div>
   )

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

@@ -4,8 +4,11 @@
  */
 import React, { useCallback } from "react"
 import { Drawer, Switch } from "antd"
-import type { FilterConfig, FilterPreset } from "../types"
-import { DEFAULT_FILTER_CONFIG, FILTER_PRESET_LABELS } from "../types"
+import type { FilterConfig, FilterPreset } from "@/pages/editing-planner/types"
+import { DEFAULT_FILTER_CONFIG } from "@/pages/editing-planner/types"
+import { PRESET_GRADIENTS } from "@/pages/editing-planner/constants/filter"
+import FilterPresetGrid from "./filter/FilterPresetGrid"
+import FilterManualAdjust from "./filter/FilterManualAdjust"
 
 interface FilterPanelProps {
   open: boolean
@@ -14,34 +17,6 @@ interface FilterPanelProps {
   onChange: (config: FilterConfig) => void
 }
 
-/** 所有预设列表 */
-const PRESET_LIST: FilterPreset[] = [
-  "none",
-  "original",
-  "fresh",
-  "warm",
-  "cool",
-  "vintage",
-  "cinema",
-  "bw",
-  "sunshine",
-  "film",
-]
-
-/** 预设对应的示例渐变色（用于视觉预览） */
-const PRESET_GRADIENTS: Record<FilterPreset, string> = {
-  none: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
-  original: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
-  fresh: "linear-gradient(135deg, #a8edea 0%, #fed6e3 100%)",
-  warm: "linear-gradient(135deg, #f093fb 0%, #f5576c 100%)",
-  cool: "linear-gradient(135deg, #4facfe 0%, #00f2fe 100%)",
-  vintage: "linear-gradient(135deg, #c79081 0%, #dfa579 100%)",
-  cinema: "linear-gradient(135deg, #2c3e50 0%, #4ca1af 100%)",
-  bw: "linear-gradient(135deg, #434343 0%, #000000 100%)",
-  sunshine: "linear-gradient(135deg, #f6d365 0%, #fda085 100%)",
-  film: "linear-gradient(135deg, #8e9eab 0%, #eef2f3 100%)",
-}
-
 const FilterPanel: React.FC<FilterPanelProps> = ({ open, onClose, config, onChange }) => {
   const update = useCallback(
     (partial: Partial<FilterConfig>) => {
@@ -54,7 +29,6 @@ const FilterPanel: React.FC<FilterPanelProps> = ({ open, onClose, config, onChan
     onChange({ ...DEFAULT_FILTER_CONFIG, enabled: config.enabled })
   }, [config.enabled, onChange])
 
-  /** 选择预设时重置手动参数 */
   const handlePresetSelect = useCallback(
     (preset: FilterPreset) => {
       if (preset === "none") {
@@ -70,6 +44,13 @@ const FilterPanel: React.FC<FilterPanelProps> = ({ open, onClose, config, onChan
     [config.enabled, onChange],
   )
 
+  const handleManualChange = useCallback(
+    (key: keyof FilterConfig, value: number) => {
+      onChange({ ...config, [key]: value })
+    },
+    [config, onChange],
+  )
+
   return (
     <Drawer
       title="滤镜调色"
@@ -90,110 +71,10 @@ const FilterPanel: React.FC<FilterPanelProps> = ({ open, onClose, config, onChan
       </div>
 
       {/* 预设滤镜选择 */}
-      <div className="filter-section">
-        <div className="filter-section-title">预设滤镜</div>
-        <div className="filter-presets">
-          {PRESET_LIST.map((p) => (
-            <button
-              key={p}
-              className={`filter-preset-item${config.preset === p ? " active" : ""}`}
-              onClick={() => handlePresetSelect(p)}
-            >
-              <div className="filter-preset-preview" style={{ background: PRESET_GRADIENTS[p] }} />
-              <span className="filter-preset-label">{FILTER_PRESET_LABELS[p]}</span>
-            </button>
-          ))}
-        </div>
-      </div>
+      <FilterPresetGrid selectedPreset={config.preset} onPresetSelect={handlePresetSelect} />
 
       {/* 手动调节 */}
-      <div className="filter-section">
-        <div className="filter-section-title">手动调节</div>
-
-        {/* 亮度 */}
-        <div className="filter-slider-row">
-          <span className="filter-slider-label">亮度</span>
-          <input
-            type="range"
-            className="filter-slider"
-            min={-100}
-            max={100}
-            value={config.brightness}
-            onChange={(e) => update({ brightness: Number(e.target.value) })}
-          />
-          <span className="filter-slider-value">{config.brightness}</span>
-        </div>
-
-        {/* 对比度 */}
-        <div className="filter-slider-row">
-          <span className="filter-slider-label">对比度</span>
-          <input
-            type="range"
-            className="filter-slider"
-            min={-100}
-            max={100}
-            value={config.contrast}
-            onChange={(e) => update({ contrast: Number(e.target.value) })}
-          />
-          <span className="filter-slider-value">{config.contrast}</span>
-        </div>
-
-        {/* 饱和度 */}
-        <div className="filter-slider-row">
-          <span className="filter-slider-label">饱和度</span>
-          <input
-            type="range"
-            className="filter-slider"
-            min={-100}
-            max={100}
-            value={config.saturation}
-            onChange={(e) => update({ saturation: Number(e.target.value) })}
-          />
-          <span className="filter-slider-value">{config.saturation}</span>
-        </div>
-
-        {/* 色温 */}
-        <div className="filter-slider-row">
-          <span className="filter-slider-label">色温</span>
-          <input
-            type="range"
-            className="filter-slider"
-            min={-100}
-            max={100}
-            value={config.temperature}
-            onChange={(e) => update({ temperature: Number(e.target.value) })}
-          />
-          <span className="filter-slider-value">{config.temperature}</span>
-        </div>
-
-        {/* 色调 */}
-        <div className="filter-slider-row">
-          <span className="filter-slider-label">色调</span>
-          <input
-            type="range"
-            className="filter-slider"
-            min={-100}
-            max={100}
-            value={config.tint}
-            onChange={(e) => update({ tint: Number(e.target.value) })}
-          />
-          <span className="filter-slider-value">{config.tint}</span>
-        </div>
-
-        {/* 锐度 */}
-        <div className="filter-slider-row">
-          <span className="filter-slider-label">锐度</span>
-          <input
-            type="range"
-            className="filter-slider"
-            min={0}
-            max={100}
-            value={config.sharpness}
-            onChange={(e) => update({ sharpness: Number(e.target.value) })}
-          />
-          <span className="filter-slider-value">{config.sharpness}</span>
-        </div>
-      </div>
+      <FilterManualAdjust config={config} onChange={handleManualChange} />
 
       {/* 预览色块 */}
       <div className="filter-section">

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

@@ -5,19 +5,14 @@
  */
 import React, { useCallback } from "react"
 import { Drawer } from "antd"
-import type { IntroOutroConfig, IntroOutroItem, IntroOutroKind, TransitionType } from "../types"
-import { DEFAULT_INTRO_OUTRO } from "../types"
-import { TRANSITION_OPTIONS } from "@/api/template-editor"
+import type {
+  IntroOutroConfig,
+  IntroOutroItem,
+  IntroOutroKind,
+} from "@/pages/editing-planner/types"
+import { DEFAULT_INTRO_OUTRO } from "@/pages/editing-planner/types"
+import IntroOutroBlock from "./intro-outro/IntroOutroBlock"
 
-/* ──────────── 常量 ──────────── */
-
-const KIND_OPTIONS: { value: IntroOutroKind; label: string; icon: string }[] = [
-  { value: "none", label: "无", icon: "🚫" },
-  { value: "video", label: "视频", icon: "🎬" },
-  { value: "image", label: "图片", icon: "🖼️" },
-]
-
-/* ──────────── Props ──────────── */
 interface IntroOutroPanelProps {
   open: boolean
   onClose: () => void
@@ -73,210 +68,24 @@ const IntroOutroPanel: React.FC<IntroOutroPanelProps> = ({ open, onClose, config
       className="intro-outro-panel-drawer"
     >
       {/* ═══ 片头区块 ═══ */}
-      <div className="iop-block">
-        <div className="iop-block-header">
-          <span className="iop-block-icon">🎞️</span>
-          <span className="iop-block-title">片头</span>
-        </div>
-
-        {/* 类型选择 */}
-        <div className="iop-kind-row">
-          {KIND_OPTIONS.map((opt) => (
-            <button
-              key={opt.value}
-              className={`iop-kind-btn${config.intro.kind === opt.value ? " active" : ""}`}
-              onClick={() => handleIntroKindChange(opt.value)}
-            >
-              <span className="iop-kind-icon">{opt.icon}</span>
-              <span className="iop-kind-label">{opt.label}</span>
-            </button>
-          ))}
-        </div>
-
-        {/* 视频/图片配置 */}
-        {config.intro.kind !== "none" && (
-          <>
-            <div className="iop-field">
-              <label className="iop-field-label">
-                {config.intro.kind === "video" ? "视频" : "图片"} URL
-              </label>
-              <input
-                className="iop-input"
-                type="text"
-                placeholder={
-                  config.intro.kind === "video"
-                    ? "https://example.com/intro.mp4"
-                    : "https://example.com/intro.png"
-                }
-                value={config.intro.url ?? ""}
-                onChange={(e) => handleIntroChange({ url: e.target.value })}
-              />
-            </div>
-
-            <div className="iop-field">
-              <label className="iop-field-label">显示时长</label>
-              <div className="iop-slider-row">
-                <input
-                  className="iop-slider"
-                  type="range"
-                  min={1}
-                  max={15}
-                  step={0.5}
-                  value={config.intro.duration}
-                  onChange={(e) => handleIntroChange({ duration: Number(e.target.value) })}
-                />
-                <span className="iop-slider-value">{config.intro.duration}s</span>
-              </div>
-            </div>
-
-            <div className="iop-field">
-              <label className="iop-field-label">进入过渡动画</label>
-              <select
-                className="iop-select"
-                value={config.intro.transition ?? "none"}
-                onChange={(e) =>
-                  handleIntroChange({
-                    transition: e.target.value as TransitionType,
-                  })
-                }
-              >
-                {TRANSITION_OPTIONS.map((opt) => (
-                  <option key={opt.value} value={opt.value}>
-                    {opt.label}
-                  </option>
-                ))}
-              </select>
-            </div>
-
-            {config.intro.transition && config.intro.transition !== "none" && (
-              <div className="iop-field">
-                <label className="iop-field-label">过渡时长</label>
-                <div className="iop-slider-row">
-                  <input
-                    className="iop-slider"
-                    type="range"
-                    min={0.3}
-                    max={2.0}
-                    step={0.1}
-                    value={config.intro.transition_duration ?? 0.5}
-                    onChange={(e) =>
-                      handleIntroChange({
-                        transition_duration: Number(e.target.value),
-                      })
-                    }
-                  />
-                  <span className="iop-slider-value">
-                    {(config.intro.transition_duration ?? 0.5).toFixed(1)}s
-                  </span>
-                </div>
-              </div>
-            )}
-          </>
-        )}
-      </div>
+      <IntroOutroBlock
+        title="片头"
+        icon="🎞️"
+        item={config.intro}
+        transitionLabel="进入过渡动画"
+        onKindChange={handleIntroKindChange}
+        onChange={handleIntroChange}
+      />
 
       {/* ═══ 片尾区块 ═══ */}
-      <div className="iop-block">
-        <div className="iop-block-header">
-          <span className="iop-block-icon">🏁</span>
-          <span className="iop-block-title">片尾</span>
-        </div>
-
-        {/* 类型选择 */}
-        <div className="iop-kind-row">
-          {KIND_OPTIONS.map((opt) => (
-            <button
-              key={opt.value}
-              className={`iop-kind-btn${config.outro.kind === opt.value ? " active" : ""}`}
-              onClick={() => handleOutroKindChange(opt.value)}
-            >
-              <span className="iop-kind-icon">{opt.icon}</span>
-              <span className="iop-kind-label">{opt.label}</span>
-            </button>
-          ))}
-        </div>
-
-        {/* 视频/图片配置 */}
-        {config.outro.kind !== "none" && (
-          <>
-            <div className="iop-field">
-              <label className="iop-field-label">
-                {config.outro.kind === "video" ? "视频" : "图片"} URL
-              </label>
-              <input
-                className="iop-input"
-                type="text"
-                placeholder={
-                  config.outro.kind === "video"
-                    ? "https://example.com/outro.mp4"
-                    : "https://example.com/outro.png"
-                }
-                value={config.outro.url ?? ""}
-                onChange={(e) => handleOutroChange({ url: e.target.value })}
-              />
-            </div>
-
-            <div className="iop-field">
-              <label className="iop-field-label">显示时长</label>
-              <div className="iop-slider-row">
-                <input
-                  className="iop-slider"
-                  type="range"
-                  min={1}
-                  max={15}
-                  step={0.5}
-                  value={config.outro.duration}
-                  onChange={(e) => handleOutroChange({ duration: Number(e.target.value) })}
-                />
-                <span className="iop-slider-value">{config.outro.duration}s</span>
-              </div>
-            </div>
-
-            <div className="iop-field">
-              <label className="iop-field-label">退出过渡动画</label>
-              <select
-                className="iop-select"
-                value={config.outro.transition ?? "none"}
-                onChange={(e) =>
-                  handleOutroChange({
-                    transition: e.target.value as TransitionType,
-                  })
-                }
-              >
-                {TRANSITION_OPTIONS.map((opt) => (
-                  <option key={opt.value} value={opt.value}>
-                    {opt.label}
-                  </option>
-                ))}
-              </select>
-            </div>
-
-            {config.outro.transition && config.outro.transition !== "none" && (
-              <div className="iop-field">
-                <label className="iop-field-label">过渡时长</label>
-                <div className="iop-slider-row">
-                  <input
-                    className="iop-slider"
-                    type="range"
-                    min={0.3}
-                    max={2.0}
-                    step={0.1}
-                    value={config.outro.transition_duration ?? 0.5}
-                    onChange={(e) =>
-                      handleOutroChange({
-                        transition_duration: Number(e.target.value),
-                      })
-                    }
-                  />
-                  <span className="iop-slider-value">
-                    {(config.outro.transition_duration ?? 0.5).toFixed(1)}s
-                  </span>
-                </div>
-              </div>
-            )}
-          </>
-        )}
-      </div>
+      <IntroOutroBlock
+        title="片尾"
+        icon="🏁"
+        item={config.outro}
+        transitionLabel="退出过渡动画"
+        onKindChange={handleOutroKindChange}
+        onChange={handleOutroChange}
+      />
 
       {/* ── 底部操作 ── */}
       <div className="iop-footer">

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

@@ -2,65 +2,12 @@
  * 混剪配置面板 — Drawer 形式
  * 左侧图层列表 + 右侧单图层配置 + 迷你预览区
  */
-import React, { useCallback, useMemo } from "react"
+import React from "react"
 import { Drawer, Switch } from "antd"
-import type { PipConfig, PipLayer, PipGridPosition, PipAnimType, PipSlideDirection } from "../types"
-import { DEFAULT_PIP_LAYER, DEFAULT_PIP_CONFIG } from "../types"
-
-/* ──────────── 常量 ──────────── */
-
-/** 九宫格位置 → 百分比坐标映射 */
-const GRID_POSITION_MAP: Record<PipGridPosition, { x: number; y: number }> = {
-  top_left: { x: 5, y: 5 },
-  top_center: { x: 37.5, y: 5 },
-  top_right: { x: 70, y: 5 },
-  center_left: { x: 5, y: 37.5 },
-  center: { x: 37.5, y: 37.5 },
-  center_right: { x: 70, y: 37.5 },
-  bottom_left: { x: 5, y: 70 },
-  bottom_center: { x: 37.5, y: 70 },
-  bottom_right: { x: 70, y: 70 },
-}
-
-/** 九宫格位置选项 */
-const GRID_POSITIONS: PipGridPosition[] = [
-  "top_left",
-  "top_center",
-  "top_right",
-  "center_left",
-  "center",
-  "center_right",
-  "bottom_left",
-  "bottom_center",
-  "bottom_right",
-]
-
-/** 入场动画选项 */
-const ANIM_OPTIONS: { value: PipAnimType; label: string }[] = [
-  { value: "none", label: "无" },
-  { value: "fade_in", label: "淡入" },
-  { value: "slide_in", label: "滑入" },
-]
-
-/** 滑入方向选项 */
-const SLIDE_DIR_OPTIONS: { value: PipSlideDirection; label: string }[] = [
-  { value: "left", label: "← 左" },
-  { value: "right", label: "→ 右" },
-  { value: "up", label: "↑ 上" },
-  { value: "down", label: "↓ 下" },
-]
-
-/** 预览图层颜色池 */
-const LAYER_COLORS = [
-  "rgba(22,119,255,0.5)",
-  "rgba(82,196,26,0.5)",
-  "rgba(250,173,20,0.5)",
-  "rgba(255,77,79,0.5)",
-  "rgba(114,46,209,0.5)",
-  "rgba(19,194,194,0.5)",
-]
-
-/* ──────────── Props ──────────── */
+import type { PipConfig } from "@/pages/editing-planner/types"
+import LayerList from "./pip-config/LayerList"
+import LayerConfig from "./pip-config/LayerConfig"
+import { usePipLayers } from "@/pages/editing-planner/hooks/usePipLayers"
 
 interface PipConfigPanelProps {
   open: boolean
@@ -70,13 +17,6 @@ interface PipConfigPanelProps {
   totalDuration: number
 }
 
-/* ──────────── 辅助函数 ──────────── */
-
-let layerIdCounter = 0
-const genLayerId = () => `pip_layer_${Date.now()}_${++layerIdCounter}`
-
-/* ──────────── 组件 ──────────── */
-
 const PipConfigPanel: React.FC<PipConfigPanelProps> = ({
   open,
   onClose,
@@ -84,106 +24,19 @@ const PipConfigPanel: React.FC<PipConfigPanelProps> = ({
   onChange,
   totalDuration,
 }) => {
-  /** 当前选中图层 ID */
-  const [selectedId, setSelectedId] = React.useState<string>("")
-
-  /** 当前选中图层 */
-  const selectedLayer = useMemo(
-    () => config.layers.find((l) => l.id === selectedId) ?? null,
-    [config.layers, selectedId],
-  )
-
-  /* ── 添加图层 ── */
-  const handleAddLayer = useCallback(() => {
-    const newLayer: PipLayer = {
-      ...DEFAULT_PIP_LAYER,
-      id: genLayerId(),
-      name: `图层 ${config.layers.length + 1}`,
-      z_index: config.layers.length + 1,
-    }
-    onChange({
-      ...config,
-      layers: [...config.layers, newLayer],
-    })
-    setSelectedId(newLayer.id)
-  }, [config, onChange])
-
-  /* ── 删除图层 ── */
-  const handleDeleteLayer = useCallback(
-    (id: string) => {
-      const newLayers = config.layers.filter((l) => l.id !== id)
-      onChange({ ...config, layers: newLayers })
-      if (selectedId === id) {
-        setSelectedId(newLayers.length > 0 ? newLayers[0].id : "")
-      }
-    },
-    [config, onChange, selectedId],
-  )
-
-  /* ── 更新图层 ── */
-  const updateLayer = useCallback(
-    (id: string, partial: Partial<PipLayer>) => {
-      onChange({
-        ...config,
-        layers: config.layers.map((l) => (l.id === id ? { ...l, ...partial } : l)),
-      })
-    },
-    [config, onChange],
-  )
-
-  /* ── 切换启用 ── */
-  const handleEnableToggle = useCallback(
-    (checked: boolean) => {
-      onChange({ ...config, enabled: checked })
-    },
-    [config, onChange],
-  )
-
-  /* ── 重置 ── */
-  const handleReset = useCallback(() => {
-    onChange({ ...DEFAULT_PIP_CONFIG })
-    setSelectedId("")
-  }, [onChange])
-
-  /* ── 九宫格点击 ── */
-  const handleGridClick = useCallback(
-    (pos: PipGridPosition) => {
-      if (!selectedLayer) return
-      const coords = GRID_POSITION_MAP[pos]
-      updateLayer(selectedLayer.id, {
-        grid_position: pos,
-        x: coords.x,
-        y: coords.y,
-      })
-    },
-    [selectedLayer, updateLayer],
-  )
-
-  /* ── 宽高比锁定 ── */
-  const handleWidthChange = useCallback(
-    (val: number) => {
-      if (!selectedLayer) return
-      const partial: Partial<PipLayer> = { width: val }
-      if (selectedLayer.aspect_lock) {
-        // 保持宽高比 1:1（百分比相同）
-        partial.height = val
-      }
-      updateLayer(selectedLayer.id, partial)
-    },
-    [selectedLayer, updateLayer],
-  )
-
-  const handleHeightChange = useCallback(
-    (val: number) => {
-      if (!selectedLayer) return
-      const partial: Partial<PipLayer> = { height: val }
-      if (selectedLayer.aspect_lock) {
-        partial.width = val
-      }
-      updateLayer(selectedLayer.id, partial)
-    },
-    [selectedLayer, updateLayer],
-  )
+  const {
+    selectedId,
+    setSelectedId,
+    selectedLayer,
+    handleAddLayer,
+    handleDeleteLayer,
+    updateLayer,
+    handleEnableToggle,
+    handleReset,
+    handleGridClick,
+    handleWidthChange,
+    handleHeightChange,
+  } = usePipLayers({ config, onChange })
 
   return (
     <Drawer
@@ -197,9 +50,7 @@ const PipConfigPanel: React.FC<PipConfigPanelProps> = ({
       {/* ═══ 顶部工具栏 ═══ */}
       <div className="pip-toolbar">
         <div className="pip-toolbar-left">
-          <button className="pip-add-btn" onClick={handleAddLayer}>
-            + 添加图层
-          </button>
+          <span style={{ fontSize: 13, color: "#666" }}>共 {config.layers.length} 个图层</span>
         </div>
         <div className="pip-enable-switch">
           <span>启用</span>
@@ -209,329 +60,22 @@ const PipConfigPanel: React.FC<PipConfigPanelProps> = ({
 
       {/* ═══ 主体：图层列表 + 配置区 ═══ */}
       <div className="pip-body">
-        {/* 左侧图层列表 */}
-        <div className="pip-layer-list">
-          {config.layers.length === 0 ? (
-            <div className="pip-layer-empty">暂无图层，点击上方添加</div>
-          ) : (
-            config.layers.map((layer, idx) => (
-              <div
-                key={layer.id}
-                className={`pip-layer-item${selectedId === layer.id ? " active" : ""}`}
-                onClick={() => setSelectedId(layer.id)}
-              >
-                {layer.thumbnail_url || layer.material_url ? (
-                  <img
-                    className="pip-layer-thumb"
-                    src={layer.thumbnail_url || layer.material_url}
-                    alt={layer.name}
-                  />
-                ) : (
-                  <div
-                    className="pip-layer-thumb"
-                    style={{
-                      background: LAYER_COLORS[idx % LAYER_COLORS.length],
-                    }}
-                  />
-                )}
-                <span className="pip-layer-name">{layer.name}</span>
-                <button
-                  className="pip-layer-delete"
-                  onClick={(e) => {
-                    e.stopPropagation()
-                    handleDeleteLayer(layer.id)
-                  }}
-                  title="删除图层"
-                >
-                  ✕
-                </button>
-              </div>
-            ))
-          )}
-        </div>
-
-        {/* 右侧配置区 */}
-        <div className="pip-config-area">
-          {!selectedLayer ? (
-            <div className="pip-config-empty">选择或添加图层以配置</div>
-          ) : (
-            <>
-              {/* ── 迷你预览 ── */}
-              <div className="pip-preview-box">
-                {config.layers.map((layer, idx) => (
-                  <div
-                    key={layer.id}
-                    className={`pip-preview-layer${selectedId === layer.id ? " selected" : ""}`}
-                    style={{
-                      left: `${layer.x}%`,
-                      top: `${layer.y}%`,
-                      width: `${layer.width}%`,
-                      height: `${layer.height}%`,
-                      background: LAYER_COLORS[idx % LAYER_COLORS.length],
-                      opacity: layer.opacity / 100,
-                      borderRadius: `${layer.border_radius}%`,
-                    }}
-                  >
-                    <span className="pip-preview-label">{layer.name}</span>
-                  </div>
-                ))}
-              </div>
-
-              {/* ── 素材类型 ── */}
-              <div className="pip-field">
-                <label className="pip-field-label">素材类型</label>
-                <div className="pip-type-btns">
-                  <button
-                    className={`pip-type-btn${selectedLayer.material_type === "image" ? " active" : ""}`}
-                    onClick={() => updateLayer(selectedLayer.id, { material_type: "image" })}
-                  >
-                    🖼️ 图片
-                  </button>
-                  <button
-                    className={`pip-type-btn${selectedLayer.material_type === "video" ? " active" : ""}`}
-                    onClick={() => updateLayer(selectedLayer.id, { material_type: "video" })}
-                  >
-                    🎬 视频
-                  </button>
-                </div>
-              </div>
-
-              {/* ── 素材 URL ── */}
-              <div className="pip-field">
-                <label className="pip-field-label">
-                  {selectedLayer.material_type === "image" ? "图片" : "视频"} URL
-                </label>
-                <input
-                  className="pip-input"
-                  type="text"
-                  placeholder={
-                    selectedLayer.material_type === "image"
-                      ? "https://example.com/image.png"
-                      : "https://example.com/video.mp4"
-                  }
-                  value={selectedLayer.material_url}
-                  onChange={(e) =>
-                    updateLayer(selectedLayer.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${selectedLayer.grid_position === pos ? " active" : ""}`}
-                        onClick={() => handleGridClick(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={selectedLayer.x}
-                        onChange={(e) =>
-                          updateLayer(selectedLayer.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={selectedLayer.y}
-                        onChange={(e) =>
-                          updateLayer(selectedLayer.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={selectedLayer.width}
-                    onChange={(e) => handleWidthChange(Number(e.target.value))}
-                  />
-                  <span className="pip-slider-value">{selectedLayer.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={selectedLayer.height}
-                    onChange={(e) => handleHeightChange(Number(e.target.value))}
-                  />
-                  <span className="pip-slider-value">{selectedLayer.height}%</span>
-                </div>
-                <div
-                  className="pip-lock-row"
-                  style={{ marginTop: 6 }}
-                  onClick={() =>
-                    updateLayer(selectedLayer.id, {
-                      aspect_lock: !selectedLayer.aspect_lock,
-                    })
-                  }
-                >
-                  <span className="pip-lock-icon">{selectedLayer.aspect_lock ? "🔒" : "🔓"}</span>
-                  <span>{selectedLayer.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={selectedLayer.border_radius}
-                    onChange={(e) =>
-                      updateLayer(selectedLayer.id, {
-                        border_radius: Number(e.target.value),
-                      })
-                    }
-                  />
-                  <span className="pip-slider-value">{selectedLayer.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={selectedLayer.opacity}
-                    onChange={(e) =>
-                      updateLayer(selectedLayer.id, {
-                        opacity: Number(e.target.value),
-                      })
-                    }
-                  />
-                  <span className="pip-slider-value">{selectedLayer.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={selectedLayer.start_time}
-                      onChange={(e) =>
-                        updateLayer(selectedLayer.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={selectedLayer.duration}
-                      onChange={(e) =>
-                        updateLayer(selectedLayer.id, {
-                          duration: Number(e.target.value),
-                        })
-                      }
-                    />
-                  </div>
-                </div>
-              </div>
-
-              {/* ── 入场动画 ── */}
-              <div className="pip-field">
-                <label className="pip-field-label">入场动画</label>
-                <select
-                  className="pip-select"
-                  value={selectedLayer.animation}
-                  onChange={(e) =>
-                    updateLayer(selectedLayer.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 时显示） */}
-              {selectedLayer.animation === "slide_in" && (
-                <div className="pip-field">
-                  <label className="pip-field-label">滑入方向</label>
-                  <select
-                    className="pip-select"
-                    value={selectedLayer.slide_direction}
-                    onChange={(e) =>
-                      updateLayer(selectedLayer.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>
+        <LayerList
+          layers={config.layers}
+          selectedId={selectedId}
+          onSelect={setSelectedId}
+          onAdd={handleAddLayer}
+          onDelete={handleDeleteLayer}
+        />
+        <LayerConfig
+          layer={selectedLayer}
+          layers={config.layers}
+          totalDuration={totalDuration}
+          onUpdate={updateLayer}
+          onGridClick={handleGridClick}
+          onWidthChange={handleWidthChange}
+          onHeightChange={handleHeightChange}
+        />
       </div>
 
       {/* ── 底部操作 ── */}

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

@@ -2,10 +2,13 @@
  * 贴纸配置面板
  * 贴纸素材库（emoji / 图片）+ 文字花字 + 位置大小调整
  */
-import React, { useCallback, useState } from "react"
+import React from "react"
 import { Drawer, Switch } from "antd"
-import type { StickerConfig, StickerItem, StickerType, TextStickerPreset } from "../types"
-import { DEFAULT_STICKER_CONFIG, DEFAULT_STICKER_ITEM, TEXT_STICKER_PRESET_LABELS } from "../types"
+import type { StickerConfig } from "@/pages/editing-planner/types"
+import StickerLibrary from "./sticker/StickerLibrary"
+import StickerList from "./sticker/StickerList"
+import StickerPropsEditor from "./sticker/StickerPropsEditor"
+import { useStickerItems } from "@/pages/editing-planner/hooks/useStickerItems"
 
 interface StickerPanelProps {
   open: boolean
@@ -15,59 +18,6 @@ interface StickerPanelProps {
   totalDuration: number
 }
 
-/** 常用 emoji 素材 */
-const EMOJI_LIST = [
-  "😀",
-  "😂",
-  "🥰",
-  "😎",
-  "🤩",
-  "😱",
-  "🤔",
-  "😴",
-  "🥳",
-  "😍",
-  "❤️",
-  "🔥",
-  "⭐",
-  "✨",
-  "💯",
-  "👍",
-  "👏",
-  "🎉",
-  "🎵",
-  "💪",
-  "📌",
-  "💡",
-  "🎯",
-  "✅",
-  "❌",
-  "⬆️",
-  "⬇️",
-  "➡️",
-  "⭕",
-  "🔔",
-]
-
-/** 文字花字预设对应的 CSS 样式预览 */
-const TEXT_PRESET_STYLES: Record<TextStickerPreset, React.CSSProperties> = {
-  normal: { color: "#fff", textShadow: "none" },
-  highlight: { color: "#FFD700", textShadow: "0 0 8px rgba(255,215,0,0.6)" },
-  bubble: { color: "#fff", background: "rgba(0,0,0,0.5)", borderRadius: 8 },
-  neon: { color: "#0ff", textShadow: "0 0 6px #0ff, 0 0 12px #0ff" },
-  shadow: { color: "#fff", textShadow: "2px 2px 4px rgba(0,0,0,0.8)" },
-  outline: { color: "#fff", WebkitTextStroke: "1px #000" },
-  gradient: {
-    color: "transparent",
-    background: "linear-gradient(90deg,#f093fb,#f5576c)",
-    WebkitBackgroundClip: "text",
-  },
-  handwrite: { color: "#333", fontStyle: "italic", fontFamily: "cursive" },
-}
-
-/** 生成唯一 ID */
-const genId = () => `sticker_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
-
 const StickerPanel: React.FC<StickerPanelProps> = ({
   open,
   onClose,
@@ -75,63 +25,17 @@ const StickerPanel: React.FC<StickerPanelProps> = ({
   onChange,
   totalDuration,
 }) => {
-  const [selectedId, setSelectedId] = useState<string | null>(null)
-  const [activeTab, setActiveTab] = useState<StickerType>("emoji")
-
-  const selectedSticker = config.items.find((s) => s.id === selectedId) ?? null
-
-  /** 更新单个贴纸 */
-  const updateItem = useCallback(
-    (id: string, partial: Partial<StickerItem>) => {
-      onChange({
-        ...config,
-        items: config.items.map((s) => (s.id === id ? { ...s, ...partial } : s)),
-      })
-    },
-    [config, onChange],
-  )
-
-  /** 添加贴纸 */
-  const addSticker = useCallback(
-    (type: StickerType, content: string) => {
-      const newItem: StickerItem = {
-        ...DEFAULT_STICKER_ITEM,
-        id: genId(),
-        type,
-        content,
-        duration: totalDuration > 0 ? totalDuration : 5,
-        z_index: config.items.length + 1,
-      }
-      onChange({
-        ...config,
-        enabled: true,
-        items: [...config.items, newItem],
-      })
-      setSelectedId(newItem.id)
-    },
-    [config, onChange, totalDuration],
-  )
-
-  /** 删除贴纸 */
-  const removeSticker = useCallback(
-    (id: string) => {
-      onChange({
-        ...config,
-        items: config.items.filter((s) => s.id !== id),
-      })
-      if (selectedId === id) setSelectedId(null)
-    },
-    [config, onChange, selectedId],
-  )
-
-  /** 重置所有 */
-  const handleReset = useCallback(() => {
-    onChange({ ...DEFAULT_STICKER_CONFIG, enabled: config.enabled })
-    setSelectedId(null)
-  }, [config.enabled, onChange])
-
-  /** 文字花字输入 */
-  const [textInput, setTextInput] = useState("")
+  const {
+    selectedId,
+    setSelectedId,
+    activeTab,
+    setActiveTab,
+    selectedSticker,
+    updateItem,
+    addSticker,
+    removeSticker,
+    handleReset,
+  } = useStickerItems({ config, onChange, totalDuration })
 
   return (
     <Drawer
@@ -152,355 +56,24 @@ const StickerPanel: React.FC<StickerPanelProps> = ({
         />
       </div>
 
-      {/* 类型 Tab */}
-      <div className="sticker-tabs">
-        {(["emoji", "image", "text"] as StickerType[]).map((t) => (
-          <button
-            key={t}
-            className={`sticker-tab${activeTab === t ? " active" : ""}`}
-            onClick={() => setActiveTab(t)}
-          >
-            {t === "emoji" ? "表情贴纸" : t === "image" ? "图片贴纸" : "文字花字"}
-          </button>
-        ))}
-      </div>
-
-      {/* Tab 内容区 */}
-      <div className="sticker-tab-content">
-        {/* Emoji 素材库 */}
-        {activeTab === "emoji" && (
-          <div className="sticker-emoji-grid">
-            {EMOJI_LIST.map((emoji) => (
-              <button
-                key={emoji}
-                className="sticker-emoji-btn"
-                onClick={() => addSticker("emoji", emoji)}
-              >
-                {emoji}
-              </button>
-            ))}
-          </div>
-        )}
-
-        {/* 图片贴纸 */}
-        {activeTab === "image" && (
-          <div className="sticker-image-input">
-            <input
-              type="text"
-              className="sticker-url-input"
-              placeholder="输入图片 URL 添加贴纸..."
-              onKeyDown={(e) => {
-                if (e.key === "Enter" && e.currentTarget.value.trim()) {
-                  addSticker("image", e.currentTarget.value.trim())
-                  e.currentTarget.value = ""
-                }
-              }}
-            />
-            <button
-              className="sticker-url-add-btn"
-              onClick={() => {
-                const input = document.querySelector<HTMLInputElement>(".sticker-url-input")
-                if (input?.value.trim()) {
-                  addSticker("image", input.value.trim())
-                  input.value = ""
-                }
-              }}
-            >
-              添加
-            </button>
-          </div>
-        )}
-
-        {/* 文字花字 */}
-        {activeTab === "text" && (
-          <div className="sticker-text-section">
-            <div className="sticker-text-input-row">
-              <input
-                type="text"
-                className="sticker-text-input"
-                placeholder="输入文字内容..."
-                value={textInput}
-                onChange={(e) => setTextInput(e.target.value)}
-              />
-              <button
-                className="sticker-text-add-btn"
-                disabled={!textInput.trim()}
-                onClick={() => {
-                  if (textInput.trim()) {
-                    addSticker("text", textInput.trim())
-                    setTextInput("")
-                  }
-                }}
-              >
-                添加
-              </button>
-            </div>
-            <div className="sticker-text-presets">
-              <div className="sticker-preset-title">花字预设预览</div>
-              <div className="sticker-preset-grid">
-                {(Object.keys(TEXT_STICKER_PRESET_LABELS) as TextStickerPreset[]).map((p) => (
-                  <div
-                    key={p}
-                    className="sticker-preset-preview"
-                    style={{
-                      ...TEXT_PRESET_STYLES[p],
-                      background:
-                        p === "bubble"
-                          ? "rgba(0,0,0,0.5)"
-                          : p === "gradient"
-                            ? "linear-gradient(90deg,#f093fb,#f5576c)"
-                            : "#1a1a2e",
-                    }}
-                  >
-                    <span style={TEXT_PRESET_STYLES[p]}>示例</span>
-                    <div className="sticker-preset-name">{TEXT_STICKER_PRESET_LABELS[p]}</div>
-                  </div>
-                ))}
-              </div>
-            </div>
-          </div>
-        )}
-      </div>
+      {/* 素材库 + 类型Tab */}
+      <StickerLibrary activeTab={activeTab} onTabChange={setActiveTab} onAddSticker={addSticker} />
 
       {/* 已添加贴纸列表 */}
-      {config.items.length > 0 && (
-        <div className="sticker-list-section">
-          <div className="sticker-section-title">已添加贴纸 ({config.items.length})</div>
-          <div className="sticker-list">
-            {config.items.map((item) => (
-              <div
-                key={item.id}
-                className={`sticker-list-item${selectedId === item.id ? " active" : ""}`}
-                onClick={() => setSelectedId(item.id)}
-              >
-                <span className="sticker-list-icon">
-                  {item.type === "emoji" ? item.content : item.type === "text" ? "T" : "🖼"}
-                </span>
-                <span className="sticker-list-name">
-                  {item.type === "text"
-                    ? item.content.slice(0, 10)
-                    : item.type === "emoji"
-                      ? "表情贴纸"
-                      : "图片贴纸"}
-                </span>
-                <button
-                  className="sticker-list-delete"
-                  onClick={(e) => {
-                    e.stopPropagation()
-                    removeSticker(item.id)
-                  }}
-                >
-                  ✕
-                </button>
-              </div>
-            ))}
-          </div>
-        </div>
-      )}
+      <StickerList
+        items={config.items}
+        selectedId={selectedId}
+        onSelect={setSelectedId}
+        onDelete={removeSticker}
+      />
 
       {/* 选中贴纸的属性编辑 */}
       {selectedSticker && (
-        <div className="sticker-props-section">
-          <div className="sticker-section-title">属性调整</div>
-
-          {/* 位置 */}
-          <div className="sticker-prop-row">
-            <span className="sticker-prop-label">位置 X</span>
-            <input
-              type="range"
-              className="sticker-prop-slider"
-              min={0}
-              max={100}
-              value={selectedSticker.x}
-              onChange={(e) => updateItem(selectedSticker.id, { x: Number(e.target.value) })}
-            />
-            <span className="sticker-prop-value">{selectedSticker.x}%</span>
-          </div>
-          <div className="sticker-prop-row">
-            <span className="sticker-prop-label">位置 Y</span>
-            <input
-              type="range"
-              className="sticker-prop-slider"
-              min={0}
-              max={100}
-              value={selectedSticker.y}
-              onChange={(e) => updateItem(selectedSticker.id, { y: Number(e.target.value) })}
-            />
-            <span className="sticker-prop-value">{selectedSticker.y}%</span>
-          </div>
-
-          {/* 尺寸 */}
-          <div className="sticker-prop-row">
-            <span className="sticker-prop-label">大小</span>
-            <input
-              type="range"
-              className="sticker-prop-slider"
-              min={5}
-              max={50}
-              value={selectedSticker.width}
-              onChange={(e) =>
-                updateItem(selectedSticker.id, {
-                  width: Number(e.target.value),
-                  height: Number(e.target.value),
-                })
-              }
-            />
-            <span className="sticker-prop-value">{selectedSticker.width}%</span>
-          </div>
-
-          {/* 旋转 */}
-          <div className="sticker-prop-row">
-            <span className="sticker-prop-label">旋转</span>
-            <input
-              type="range"
-              className="sticker-prop-slider"
-              min={-180}
-              max={180}
-              value={selectedSticker.rotation}
-              onChange={(e) =>
-                updateItem(selectedSticker.id, {
-                  rotation: Number(e.target.value),
-                })
-              }
-            />
-            <span className="sticker-prop-value">{selectedSticker.rotation}°</span>
-          </div>
-
-          {/* 透明度 */}
-          <div className="sticker-prop-row">
-            <span className="sticker-prop-label">透明度</span>
-            <input
-              type="range"
-              className="sticker-prop-slider"
-              min={0}
-              max={100}
-              value={selectedSticker.opacity}
-              onChange={(e) =>
-                updateItem(selectedSticker.id, {
-                  opacity: Number(e.target.value),
-                })
-              }
-            />
-            <span className="sticker-prop-value">{selectedSticker.opacity}%</span>
-          </div>
-
-          {/* 时间 */}
-          <div className="sticker-prop-row">
-            <span className="sticker-prop-label">开始</span>
-            <input
-              type="number"
-              className="sticker-prop-number"
-              min={0}
-              max={totalDuration}
-              step={0.1}
-              value={selectedSticker.start_time}
-              onChange={(e) =>
-                updateItem(selectedSticker.id, {
-                  start_time: Number(e.target.value),
-                })
-              }
-            />
-            <span className="sticker-prop-label">时长</span>
-            <input
-              type="number"
-              className="sticker-prop-number"
-              min={0}
-              max={totalDuration}
-              step={0.1}
-              value={selectedSticker.duration}
-              onChange={(e) =>
-                updateItem(selectedSticker.id, {
-                  duration: Number(e.target.value),
-                })
-              }
-            />
-          </div>
-
-          {/* 文字贴纸特有属性 */}
-          {selectedSticker.type === "text" && (
-            <>
-              <div className="sticker-prop-row">
-                <span className="sticker-prop-label">花字</span>
-                <select
-                  className="sticker-prop-select"
-                  value={selectedSticker.text_preset}
-                  onChange={(e) =>
-                    updateItem(selectedSticker.id, {
-                      text_preset: e.target.value as TextStickerPreset,
-                    })
-                  }
-                >
-                  {(Object.keys(TEXT_STICKER_PRESET_LABELS) as TextStickerPreset[]).map((p) => (
-                    <option key={p} value={p}>
-                      {TEXT_STICKER_PRESET_LABELS[p]}
-                    </option>
-                  ))}
-                </select>
-              </div>
-              <div className="sticker-prop-row">
-                <span className="sticker-prop-label">字号</span>
-                <input
-                  type="range"
-                  className="sticker-prop-slider"
-                  min={12}
-                  max={72}
-                  value={selectedSticker.font_size}
-                  onChange={(e) =>
-                    updateItem(selectedSticker.id, {
-                      font_size: Number(e.target.value),
-                    })
-                  }
-                />
-                <span className="sticker-prop-value">{selectedSticker.font_size}px</span>
-              </div>
-              <div className="sticker-prop-row">
-                <span className="sticker-prop-label">颜色</span>
-                <input
-                  type="color"
-                  className="sticker-prop-color"
-                  value={selectedSticker.text_color}
-                  onChange={(e) =>
-                    updateItem(selectedSticker.id, {
-                      text_color: e.target.value,
-                    })
-                  }
-                />
-              </div>
-            </>
-          )}
-
-          {/* 预览 */}
-          <div className="sticker-preview-box">
-            <div
-              className="sticker-preview-item"
-              style={{
-                left: `${selectedSticker.x}%`,
-                top: `${selectedSticker.y}%`,
-                width: `${selectedSticker.width}%`,
-                height: `${selectedSticker.width}%`,
-                transform: `translate(-50%, -50%) rotate(${selectedSticker.rotation}deg)`,
-                opacity: selectedSticker.opacity / 100,
-                fontSize:
-                  selectedSticker.type === "text" ? `${selectedSticker.font_size}px` : undefined,
-                ...TEXT_PRESET_STYLES[selectedSticker.text_preset],
-              }}
-            >
-              {selectedSticker.type === "emoji" && selectedSticker.content}
-              {selectedSticker.type === "text" && selectedSticker.content}
-              {selectedSticker.type === "image" && (
-                <img
-                  src={selectedSticker.content}
-                  alt="sticker"
-                  style={{
-                    width: "100%",
-                    height: "100%",
-                    objectFit: "contain",
-                  }}
-                />
-              )}
-            </div>
-          </div>
-        </div>
+        <StickerPropsEditor
+          sticker={selectedSticker}
+          totalDuration={totalDuration}
+          onUpdate={updateItem}
+        />
       )}
 
       {/* 底部重置 */}

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

@@ -5,31 +5,14 @@
 import React from "react"
 import { Drawer, Slider, ColorPicker, Select } from "antd"
 import type { Color } from "antd/es/color-picker"
-import type { SubtitleStyleConfig } from "../types/subtitle"
-
-/* ──────────── 选项常量 ──────────── */
-
-const POSITION_OPTIONS = [
-  { value: "top", label: "顶部" },
-  { value: "center", label: "居中" },
-  { value: "bottom", label: "底部" },
-]
-
-const FONT_OPTIONS = ["思源黑体", "思源宋体", "苹方", "PingFang", "微软雅黑", "楷体", "华康俪金黑"]
-
-const ANIMATION_OPTIONS = [
-  { value: "none", label: "无" },
-  { value: "fade", label: "淡入淡出" },
-  { value: "slide", label: "滑动" },
-  { value: "typewriter", label: "打字机" },
-]
-
-const ASR_LANGUAGE_OPTIONS = [
-  { value: "zh", label: "中文" },
-  { value: "en", label: "English" },
-]
-
-/* ──────────── Props ──────────── */
+import type { SubtitleStyleConfig } from "@/pages/editing-planner/types/subtitle"
+import {
+  POSITION_OPTIONS,
+  FONT_OPTIONS,
+  ANIMATION_OPTIONS,
+  ASR_LANGUAGE_OPTIONS,
+} from "@/pages/editing-planner/constants/subtitleStyle"
+import SubtitlePreview from "./subtitle-style/SubtitlePreview"
 
 interface SubtitleStylePanelProps {
   open: boolean
@@ -197,23 +180,7 @@ const SubtitleStylePanel: React.FC<SubtitleStylePanelProps> = ({
           </div>
 
           {/* ── 预览 ── */}
-          <div className="sub-field">
-            <label className="sub-label">预览</label>
-            <div className="sub-preview-box">
-              <span
-                className="sub-preview-text"
-                style={{
-                  fontSize: `${Math.min(config.fontSize, 28)}px`,
-                  color: config.fontColor,
-                  fontFamily: config.font,
-                  WebkitTextStroke: config.stroke ? "1px #000" : undefined,
-                  textShadow: config.shadow ? "2px 2px 4px rgba(0,0,0,0.8)" : undefined,
-                }}
-              >
-                这是一段字幕预览
-              </span>
-            </div>
-          </div>
+          <SubtitlePreview config={config} />
         </>
       )}
     </Drawer>

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

@@ -10,7 +10,24 @@
  */
 import React, { useState, useRef, useCallback, useEffect, useLayoutEffect, useMemo } from "react"
 import type { ClipData, ClipType, TrimConfig } from "../types"
-import { TRANSITION_OPTIONS } from "@/api/template-editor"
+import {
+  DEFAULT_PIXELS_PER_SECOND,
+  MIN_PIXELS_PER_SECOND,
+  MAX_PIXELS_PER_SECOND,
+  ZOOM_STEP,
+  MIN_TRIM_DURATION,
+  DEFAULT_ADD_DURATION,
+  MIN_ADD_DURATION,
+  MAX_ADD_DURATION,
+  TRACK_GAP,
+  ADD_PICKER_WIDTH,
+} from "../constants/timeline"
+import { formatTime } from "../utils/timeline"
+import { ClipCard } from "./timeline/ClipCard"
+import { TimeRuler } from "./timeline/TimeRuler"
+import { AddClipPicker } from "./timeline/AddClipPicker"
+import { TrimPreview } from "./timeline/TrimPreview"
+import { ContextMenu } from "./timeline/ContextMenu"
 
 interface TimelinePanelProps {
   clips: ClipData[]
@@ -38,18 +55,6 @@ interface TimelinePanelProps {
   totalDuration?: number
 }
 
-/** 片段类型图标 */
-const CLIP_TYPE_ICONS: Record<ClipType, string> = {
-  voice: "🎙️",
-  pip: "🖼️",
-}
-
-/** 片段类型标签 */
-const CLIP_TYPE_LABELS: Record<ClipType, string> = {
-  voice: "口播",
-  pip: "混剪",
-}
-
 /** 裁剪拖拽方向 */
 type TrimDirection = "left" | "right"
 
@@ -135,7 +140,7 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
 
   /* ── "+" 卡片：类型+时长选择状态 ── */
   const [addType, setAddType] = useState<ClipType>(defaultAddType)
-  const [addDuration, setAddDuration] = useState<number>(5)
+  const [addDuration, setAddDuration] = useState<number>(DEFAULT_ADD_DURATION)
 
   /* ── 模式切换时自动同步默认添加类型 ── */
   useEffect(() => {
@@ -144,21 +149,17 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
     }
   }, [currentMode, addType, availableTypes, defaultAddType])
 
-  /* ── 面板尺寸 ── */
-  const PICKER_W = 240
-  const GAP = 6
-
   /* ── 计算 picker 初始位置 ── */
   const updatePickerPosition = useCallback(() => {
     if (!addCardRef.current) return
     const rect = addCardRef.current.getBoundingClientRect()
     const vw = window.innerWidth
     const roughHeight = 180
-    let top = rect.top - GAP - roughHeight
+    let top = rect.top - TRACK_GAP - roughHeight
     if (top < 8) top = 8
     let right = vw - rect.right
-    if (rect.right - PICKER_W < 8) {
-      right = vw - PICKER_W - 8
+    if (rect.right - ADD_PICKER_WIDTH < 8) {
+      right = vw - ADD_PICKER_WIDTH - 8
     }
     setPickerPos({ top, right })
   }, [])
@@ -181,9 +182,9 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
     const pickerH = pickerEl.offsetHeight
     const vh = window.innerHeight
     const vw = window.innerWidth
-    let top = addRect.top - GAP - pickerH
+    let top = addRect.top - TRACK_GAP - pickerH
     if (top < 8) {
-      top = addRect.bottom + GAP
+      top = addRect.bottom + TRACK_GAP
       if (top + pickerH > vh - 8) {
         top = vh - 8 - pickerH
         if (top < 8) top = 8
@@ -192,7 +193,7 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
     let right = vw - addRect.right
     const pickerRect = pickerEl.getBoundingClientRect()
     if (pickerRect.left < 8) {
-      right = vw - PICKER_W - 8
+      right = vw - ADD_PICKER_WIDTH - 8
     }
     setPickerPos({ top, right })
   }, [showAddPicker])
@@ -224,7 +225,7 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
   }, [contextMenu])
 
   /* ── 缩放 & 时长 ── */
-  const pps = pixelsPerSecond ?? 40
+  const pps = pixelsPerSecond ?? DEFAULT_PIXELS_PER_SECOND
   const totalDuration = totalDurationProp ?? clips.reduce((s, c) => s + c.duration, 0)
 
   /* ── 播放头拖拽全局 mousemove/mouseup ── */
@@ -344,11 +345,9 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
   useEffect(() => {
     if (!trimDrag) return
 
-    const PX_PER_SECOND = pixelsPerSecond ?? 40 // 与缩放级别同步
-
     const handleMouseMove = (e: MouseEvent) => {
       const dx = e.clientX - trimDrag.startX
-      const dtSec = dx / PX_PER_SECOND
+      const dtSec = dx / pps
       const clip = clips.find((c) => c.id === trimDrag.clipId)
       if (!clip) return
 
@@ -359,10 +358,13 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
 
       if (trimDrag.direction === "left") {
         // 左手柄：调整入点
-        newStart = Math.max(0, Math.min(origTrim.start_time + dtSec, newEnd - 1))
+        newStart = Math.max(0, Math.min(origTrim.start_time + dtSec, newEnd - MIN_TRIM_DURATION))
       } else {
         // 右手柄：调整出点
-        newEnd = Math.max(origTrim.start_time + 1, Math.min(origTrim.end_time + dtSec, origDur))
+        newEnd = Math.max(
+          origTrim.start_time + MIN_TRIM_DURATION,
+          Math.min(origTrim.end_time + dtSec, origDur),
+        )
       }
 
       const newDuration = Math.round((newEnd - newStart) * 10) / 10
@@ -396,7 +398,7 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
       document.removeEventListener("mousemove", handleMouseMove)
       document.removeEventListener("mouseup", handleMouseUp)
     }
-  }, [trimDrag, trimPreview, clips, onClipTrim, pixelsPerSecond])
+  }, [trimDrag, trimPreview, clips, onClipTrim, pps])
 
   /* ── 右键菜单 ── */
   const handleContextMenu = useCallback((e: React.MouseEvent, clipId: string) => {
@@ -428,25 +430,6 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
     setContextMenu(null)
   }, [contextMenu, onClipRemove])
 
-  /* ── 时间标尺 ── */
-  const trackWidth = Math.max(totalDuration * pps, 300)
-  const rulerMarks: number[] = []
-  const step = totalDuration <= 30 ? 5 : totalDuration <= 60 ? 10 : 15
-  for (let t = 0; t <= totalDuration + step; t += step) {
-    rulerMarks.push(t)
-  }
-
-  const formatTime = (sec: number) => {
-    const m = Math.floor(sec / 60)
-    const s = Math.floor(sec % 60)
-    return `${m}:${s.toString().padStart(2, "0")}`
-  }
-
-  /** 格式化裁剪时间（精确到0.1秒） */
-  const formatTrimTime = (sec: number) => {
-    return `${sec.toFixed(1)}s`
-  }
-
   return (
     <div className="ep-timeline-area">
       {/* 时间线头部 */}
@@ -460,7 +443,7 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
           <div className="ep-timeline-zoom">
             <button
               className="ep-zoom-btn"
-              onClick={() => onZoomChange?.(Math.max(10, pps - 10))}
+              onClick={() => onZoomChange?.(Math.max(MIN_PIXELS_PER_SECOND, pps - ZOOM_STEP))}
               title="缩小"
             >
               −
@@ -468,15 +451,15 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
             <input
               type="range"
               className="ep-zoom-slider"
-              min={10}
-              max={120}
+              min={MIN_PIXELS_PER_SECOND}
+              max={MAX_PIXELS_PER_SECOND}
               step={5}
               value={pps}
               onChange={(e) => onZoomChange?.(Number(e.target.value))}
             />
             <button
               className="ep-zoom-btn"
-              onClick={() => onZoomChange?.(Math.min(120, pps + 10))}
+              onClick={() => onZoomChange?.(Math.min(MAX_PIXELS_PER_SECOND, pps + ZOOM_STEP))}
               title="放大"
             >
               +
@@ -506,15 +489,7 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
 
       {/* 时间标尺 */}
       {currentMode !== "one_take" && (
-        <div className="ep-time-ruler" onClick={handleRulerClick}>
-          <div className="ep-time-ruler-inner" style={{ width: trackWidth }}>
-            {rulerMarks.map((t) => (
-              <span key={t} className="ep-time-mark" style={{ left: `${t * pps}px` }}>
-                {t}s
-              </span>
-            ))}
-          </div>
-        </div>
+        <TimeRuler totalDuration={totalDuration} pps={pps} onClick={handleRulerClick} />
       )}
 
       {/* 水平片段轨道 */}
@@ -536,115 +511,30 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
               <div className="ep-track-empty-text">点击右侧 + 添加片段</div>
             </div>
           ) : (
-            clips.map((clip, idx) => {
-              /* 转场指示器 */
-              const trans = clip.transition
-              const showTransition = idx > 0 && trans && trans.type !== "none"
-              const transOpt = showTransition
-                ? TRANSITION_OPTIONS.find((o) => o.value === trans!.type)
-                : undefined
-
-              /* 速度徽章 */
-              const speed = clip.speed
-              const showSpeed = speed && Math.abs(speed.rate - 1.0) > 0.01
-
-              /* 裁剪状态 */
-              const hasTrim = !!clip.trim_config
-              const isHovered = hoveredClipId === clip.id
-
-              return (
-                <React.Fragment key={clip.id}>
-                  {/* 转场指示器 */}
-                  {showTransition && transOpt && (
-                    <div
-                      className="ep-transition-indicator"
-                      title={`${transOpt.label} · ${trans!.duration.toFixed(1)}s`}
-                    >
-                      <span className="ep-trans-icon">{transOpt.icon}</span>
-                      <span className="ep-trans-duration">{trans!.duration.toFixed(1)}s</span>
-                    </div>
-                  )}
-
-                  <div
-                    className={`ep-clip-card ${selectedClipId === clip.id ? "selected" : ""} ${dragIdx === idx ? "dragging" : ""} ${dragOverIdx === idx ? "drag-over" : ""} ${hasTrim ? "trimmed" : ""}`}
-                    style={{ width: Math.max(clip.duration * pps, 60) }}
-                    draggable={!trimDrag}
-                    onDragStart={(e) => handleDragStart(e, idx)}
-                    onDragOver={(e) => handleDragOver(e, idx)}
-                    onDragEnd={handleDragEnd}
-                    onDrop={(e) => handleDrop(e, idx)}
-                    onClick={() => onClipSelect(clip.id)}
-                    onContextMenu={(e) => handleContextMenu(e, clip.id)}
-                    onMouseEnter={() => setHoveredClipId(clip.id)}
-                    onMouseLeave={() => setHoveredClipId(null)}
-                  >
-                    {/* 左裁剪手柄 */}
-                    {isHovered && onClipTrim && (
-                      <div
-                        className="ep-trim-handle ep-trim-handle-left"
-                        onMouseDown={(e) => handleTrimHandleMouseDown(e, clip.id, "left")}
-                        title="拖动调整入点"
-                      >
-                        <div className="ep-trim-handle-line" />
-                      </div>
-                    )}
-
-                    {/* 类型图标 */}
-                    <div className="ep-clip-thumbnail">{CLIP_TYPE_ICONS[clip.type] || "🎬"}</div>
-
-                    {/* 片段信息 */}
-                    <div className="ep-clip-info">
-                      <span className="ep-clip-name">
-                        {CLIP_TYPE_LABELS[clip.type] || "片段"} {idx + 1}
-                      </span>
-                      <span className="ep-clip-duration">
-                        {clip.duration}s
-                        {hasTrim && (
-                          <span className="ep-trim-indicator" title="已裁剪">
-                            ✂
-                          </span>
-                        )}
-                      </span>
-                    </div>
-
-                    {/* 速度徽章 */}
-                    {showSpeed && <span className="ep-speed-badge">{speed!.rate.toFixed(1)}x</span>}
-
-                    {/* 裁剪徽章 */}
-                    {hasTrim && (
-                      <span
-                        className="ep-trim-badge"
-                        title={`入点 ${clip.trim_config!.start_time.toFixed(1)}s / 出点 ${clip.trim_config!.end_time.toFixed(1)}s`}
-                      >
-                        ✂
-                      </span>
-                    )}
-
-                    {/* 右裁剪手柄 */}
-                    {isHovered && onClipTrim && (
-                      <div
-                        className="ep-trim-handle ep-trim-handle-right"
-                        onMouseDown={(e) => handleTrimHandleMouseDown(e, clip.id, "right")}
-                        title="拖动调整出点"
-                      >
-                        <div className="ep-trim-handle-line" />
-                      </div>
-                    )}
-
-                    {/* 删除按钮 */}
-                    <button
-                      className="ep-clip-remove"
-                      onClick={(e) => {
-                        e.stopPropagation()
-                        onClipRemove(clip.id)
-                      }}
-                    >
-                      ✕
-                    </button>
-                  </div>
-                </React.Fragment>
-              )
-            })
+            clips.map((clip, idx) => (
+              <ClipCard
+                key={clip.id}
+                clip={clip}
+                idx={idx}
+                isSelected={selectedClipId === clip.id}
+                isDragging={dragIdx === idx}
+                isDragOver={dragOverIdx === idx}
+                isHovered={hoveredClipId === clip.id}
+                pps={pps}
+                trimDragActive={!!trimDrag}
+                showTrimHandles={!!onClipTrim}
+                onDragStart={handleDragStart}
+                onDragOver={handleDragOver}
+                onDragEnd={handleDragEnd}
+                onDrop={handleDrop}
+                onSelect={onClipSelect}
+                onContextMenu={handleContextMenu}
+                onMouseEnter={() => setHoveredClipId(clip.id)}
+                onMouseLeave={() => setHoveredClipId(null)}
+                onTrimHandleMouseDown={handleTrimHandleMouseDown}
+                onRemove={onClipRemove}
+              />
+            ))
           )}
 
           {/* ── 轨道末尾 "+" 添加卡片 ── */}
@@ -663,109 +553,42 @@ const TimelinePanel: React.FC<TimelinePanelProps> = ({
 
       {/* 裁剪预览 tooltip */}
       {trimPreview && (
-        <div
-          className="ep-trim-preview"
-          style={{
-            position: "fixed",
-            left: trimPreview.x + 12,
-            top: trimPreview.y - 40,
-          }}
-        >
-          <div className="ep-trim-preview-row">
-            <span className="ep-trim-preview-label">入点</span>
-            <span className="ep-trim-preview-value">{formatTrimTime(trimPreview.startTime)}</span>
-          </div>
-          <div className="ep-trim-preview-row">
-            <span className="ep-trim-preview-label">出点</span>
-            <span className="ep-trim-preview-value">{formatTrimTime(trimPreview.endTime)}</span>
-          </div>
-          <div className="ep-trim-preview-row ep-trim-preview-duration">
-            <span className="ep-trim-preview-label">时长</span>
-            <span className="ep-trim-preview-value">{formatTrimTime(trimPreview.duration)}</span>
-          </div>
-        </div>
+        <TrimPreview
+          startTime={trimPreview.startTime}
+          endTime={trimPreview.endTime}
+          duration={trimPreview.duration}
+          x={trimPreview.x}
+          y={trimPreview.y}
+        />
       )}
 
       {/* 右键菜单 */}
       {contextMenu && (
-        <div
-          ref={contextMenuRef}
-          className="ep-context-menu"
-          style={{
-            position: "fixed",
-            left: contextMenu.x,
-            top: contextMenu.y,
-          }}
-        >
-          <div className="ep-context-menu-item" onClick={handleContextSplit}>
-            <span className="ep-context-menu-icon">✂️</span>
-            <span>分割片段</span>
-          </div>
-          {clips.find((c) => c.id === contextMenu.clipId)?.trim_config && (
-            <div className="ep-context-menu-item" onClick={handleContextResetTrim}>
-              <span className="ep-context-menu-icon">↩️</span>
-              <span>恢复原始长度</span>
-            </div>
-          )}
-          <div className="ep-context-menu-divider" />
-          <div
-            className="ep-context-menu-item ep-context-menu-item-danger"
-            onClick={handleContextDelete}
-          >
-            <span className="ep-context-menu-icon">🗑️</span>
-            <span>删除片段</span>
-          </div>
-        </div>
+        <ContextMenu
+          x={contextMenu.x}
+          y={contextMenu.y}
+          menuRef={contextMenuRef}
+          hasTrim={!!clips.find((c) => c.id === contextMenu.clipId)?.trim_config}
+          onSplit={handleContextSplit}
+          onResetTrim={handleContextResetTrim}
+          onDelete={handleContextDelete}
+        />
       )}
 
       {/* 类型+时长选择面板 */}
       {showAddPicker && (
-        <div
-          ref={pickerRef}
-          className="ep-add-clip-picker ep-add-clip-picker--portal"
-          style={{
-            position: "fixed",
-            top: pickerPos.top,
-            right: pickerPos.right,
-          }}
-        >
-          <div className="ep-add-clip-picker-title">添加片段</div>
-
-          {/* 类型选择 */}
-          <div className="ep-add-clip-type-row">
-            <span className="ep-add-clip-type-label">类型:</span>
-            {availableTypes.map((t) => (
-              <button
-                key={t}
-                className={`ep-add-clip-type-btn${addType === t ? " active" : ""}`}
-                onClick={() => setAddType(t)}
-              >
-                {CLIP_TYPE_ICONS[t]} {CLIP_TYPE_LABELS[t]}
-              </button>
-            ))}
-          </div>
-
-          {/* 时长输入 */}
-          <div className="ep-add-clip-duration-row">
-            <span className="ep-add-clip-type-label">时长:</span>
-            <input
-              type="number"
-              className="ep-duration-input"
-              min={1}
-              max={120}
-              value={addDuration}
-              onChange={(e) =>
-                setAddDuration(Math.max(1, Math.min(120, Number(e.target.value) || 1)))
-              }
-            />
-            <span className="ep-add-clip-duration-unit">秒</span>
-          </div>
-
-          {/* 确认按钮 */}
-          <button className="ep-add-clip-confirm-btn" onClick={handleConfirmAdd}>
-            添加
-          </button>
-        </div>
+        <AddClipPicker
+          pickerRef={pickerRef}
+          position={pickerPos}
+          availableTypes={availableTypes}
+          addType={addType}
+          addDuration={addDuration}
+          minDuration={MIN_ADD_DURATION}
+          maxDuration={MAX_ADD_DURATION}
+          onTypeChange={setAddType}
+          onDurationChange={setAddDuration}
+          onConfirm={handleConfirmAdd}
+        />
       )}
     </div>
   )

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

@@ -2,23 +2,14 @@
  * TTS 配音面板 — Drawer 形式
  * 配音模式切换 + 文本输入 + 音色选择 + 语速/语调/音量 + 试听 + 字幕联动
  */
-import React, { useState, useCallback, useEffect, useRef } from "react"
-import { Drawer, Slider, message } from "antd"
-import type { TtsConfig, TtsMode } from "../types"
-import { DEFAULT_TTS_CONFIG } from "../types"
-import { getTtsVoices, previewTts, type TTSVoice } from "@/api/tts"
+import React from "react"
+import { Drawer } from "antd"
+import type { TtsConfig } from "@/pages/editing-planner/types"
+import { TTS_MODE_OPTIONS } from "@/pages/editing-planner/constants/tts"
+import VoiceSelector from "./tts/VoiceSelector"
+import TtsSlider from "./tts/TtsSlider"
+import { useTtsPanel } from "@/pages/editing-planner/hooks/useTtsPanel"
 
-/* ──────────── 音色卡片分类图标 ──────────── */
-const VOICE_CATEGORY_MAP: Record<string, { icon: string; label: string }> = {
-  male: { icon: "👨", label: "男声" },
-  female: { icon: "👩", label: "女声" },
-  young: { icon: "🧑", label: "少年" },
-  service: { icon: "🎧", label: "客服" },
-  news: { icon: "📰", label: "新闻" },
-  emotion: { icon: "🎭", label: "情感" },
-}
-
-/* ──────────── Props ──────────── */
 interface TtsPanelProps {
   open: boolean
   onClose: () => void
@@ -28,126 +19,21 @@ interface TtsPanelProps {
 }
 
 const TtsPanel: React.FC<TtsPanelProps> = ({ open, onClose, config, onChange }) => {
-  /* ── 音色列表 ── */
-  const [voices, setVoices] = useState<TTSVoice[]>([])
-  const [voicesLoading, setVoicesLoading] = useState(false)
-
-  /* ── 试听状态 ── */
-  const [previewLoading, setPreviewLoading] = useState(false)
-  const audioRef = useRef<HTMLAudioElement | null>(null)
-
-  /* ── 加载音色列表 ── */
-  useEffect(() => {
-    if (!open) return
-    setVoicesLoading(true)
-    getTtsVoices()
-      .then((v) => setVoices(v))
-      .catch(() => message.error("加载音色列表失败"))
-      .finally(() => setVoicesLoading(false))
-  }, [open])
-
-  /* ── 切换配音模式 ── */
-  const handleModeChange = useCallback(
-    (mode: TtsMode) => {
-      onChange({ ...config, mode })
-    },
-    [config, onChange],
-  )
-
-  /* ── 文本输入 ── */
-  const handleTextChange = useCallback(
-    (e: React.ChangeEvent<HTMLTextAreaElement>) => {
-      const text = e.target.value.slice(0, 5000)
-      onChange({ ...config, text })
-    },
-    [config, onChange],
-  )
-
-  /* ── 选择音色 ── */
-  const handleVoiceSelect = useCallback(
-    (voiceId: string) => {
-      onChange({ ...config, voice_id: voiceId })
-    },
-    [config, onChange],
-  )
-
-  /* ── 语速 ── */
-  const handleSpeedChange = useCallback(
-    (speed: number) => {
-      onChange({ ...config, speed })
-    },
-    [config, onChange],
-  )
-
-  /* ── 语调 ── */
-  const handlePitchChange = useCallback(
-    (pitch: number) => {
-      onChange({ ...config, pitch })
-    },
-    [config, onChange],
-  )
-
-  /* ── 音量 ── */
-  const handleVolumeChange = useCallback(
-    (volume: number) => {
-      onChange({ ...config, volume })
-    },
-    [config, onChange],
-  )
-
-  /* ── 字幕联动 ── */
-  const handleSubtitleSyncToggle = useCallback(() => {
-    onChange({ ...config, subtitle_sync: !config.subtitle_sync })
-  }, [config, onChange])
-
-  /* ── 试听 ── */
-  const handlePreview = useCallback(async () => {
-    if (!config.text.trim()) {
-      message.warning("请先输入合成文本")
-      return
-    }
-    if (!config.voice_id) {
-      message.warning("请先选择音色")
-      return
-    }
-    setPreviewLoading(true)
-    try {
-      const res = await previewTts({
-        text: config.text.slice(0, 200), // 试听截取前200字
-        voice_id: config.voice_id,
-        speed: config.speed,
-        pitch: config.pitch,
-      })
-      // 停止上一个
-      audioRef.current?.pause()
-      const audio = new Audio(res.audio_url)
-      audioRef.current = audio
-      audio.play().catch(() => message.error("播放失败"))
-      audio.onended = () => {
-        audioRef.current = null
-      }
-      message.success("试听播放中")
-    } catch {
-      message.error("试听生成失败")
-    } finally {
-      setPreviewLoading(false)
-    }
-  }, [config])
-
-  /* ── 重置 ── */
-  const handleReset = useCallback(() => {
-    onChange({ ...DEFAULT_TTS_CONFIG })
-  }, [onChange])
-
-  /* ── 关闭时停止音频 ── */
-  const handleClose = useCallback(() => {
-    audioRef.current?.pause()
-    audioRef.current = null
-    onClose()
-  }, [onClose])
-
-  /* ── 音色分类分组 ── */
-  const voiceCategories = Object.entries(VOICE_CATEGORY_MAP)
+  const {
+    voices,
+    voicesLoading,
+    previewLoading,
+    handleModeChange,
+    handleTextChange,
+    handleVoiceSelect,
+    handleSpeedChange,
+    handlePitchChange,
+    handleVolumeChange,
+    handleSubtitleSyncToggle,
+    handlePreview,
+    handleReset,
+    handleClose,
+  } = useTtsPanel({ open, config, onChange, onClose })
 
   return (
     <Drawer
@@ -162,11 +48,7 @@ const TtsPanel: React.FC<TtsPanelProps> = ({ open, onClose, config, onChange })
       <div className="tts-mode-section">
         <div className="tts-mode-label">配音模式</div>
         <div className="tts-mode-group">
-          {[
-            { mode: "none" as TtsMode, icon: "🔇", label: "无配音" },
-            { mode: "upload" as TtsMode, icon: "📁", label: "上传配音" },
-            { mode: "tts" as TtsMode, icon: "🤖", label: "TTS 合成" },
-          ].map((m) => (
+          {TTS_MODE_OPTIONS.map((m) => (
             <button
               key={m.mode}
               className={`tts-mode-btn${config.mode === m.mode ? " active" : ""}`}
@@ -192,97 +74,57 @@ const TtsPanel: React.FC<TtsPanelProps> = ({ open, onClose, config, onChange })
               className="tts-text-input"
               placeholder="请输入需要合成的文本内容..."
               value={config.text}
-              onChange={handleTextChange}
+              onChange={(e) => handleTextChange(e.target.value)}
               maxLength={5000}
               rows={5}
             />
           </div>
 
           {/* 音色选择 */}
-          <div className="tts-voice-section">
-            <div className="tts-voice-label">
-              选择音色
-              {voicesLoading && <span className="tts-voice-loading">加载中...</span>}
-            </div>
-            <div className="tts-voice-grid">
-              {voiceCategories.map(([cat, info]) => {
-                const voice = voices.find((v) => v.category === cat)
-                const isSelected = voice && config.voice_id === voice.id
-                return (
-                  <button
-                    key={cat}
-                    className={`tts-voice-card${isSelected ? " active" : ""}`}
-                    onClick={() => voice && handleVoiceSelect(voice.id)}
-                    disabled={!voice || voicesLoading}
-                  >
-                    <span className="tts-voice-card-icon">{info.icon}</span>
-                    <span className="tts-voice-card-name">{voice?.name || info.label}</span>
-                  </button>
-                )
-              })}
-            </div>
-          </div>
+          <VoiceSelector
+            voices={voices}
+            voicesLoading={voicesLoading}
+            selectedVoiceId={config.voice_id}
+            onVoiceSelect={handleVoiceSelect}
+          />
 
           {/* 语速滑块 */}
-          <div className="tts-slider-section">
-            <div className="tts-slider-header">
-              <span className="tts-slider-label">语速</span>
-              <span className="tts-slider-value">{config.speed.toFixed(2)}x</span>
-            </div>
-            <Slider
-              min={0.5}
-              max={2.0}
-              step={0.05}
-              value={config.speed}
-              onChange={handleSpeedChange}
-              tooltip={{ formatter: (v) => `${(v as number).toFixed(2)}x` }}
-            />
-            <div className="tts-slider-marks">
-              <span>0.5x</span>
-              <span>1.0x</span>
-              <span>2.0x</span>
-            </div>
-          </div>
+          <TtsSlider
+            label="语速"
+            value={config.speed}
+            min={0.5}
+            max={2.0}
+            step={0.05}
+            unit="x"
+            onChange={handleSpeedChange}
+            marks={["0.5x", "1.0x", "2.0x"]}
+            tooltipFormatter={(v) => `${v.toFixed(2)}x`}
+          />
 
           {/* 语调滑块 */}
-          <div className="tts-slider-section">
-            <div className="tts-slider-header">
-              <span className="tts-slider-label">语调</span>
-              <span className="tts-slider-value">
-                {config.pitch > 0 ? "+" : ""}
-                {config.pitch} 半音
-              </span>
-            </div>
-            <Slider
-              min={-12}
-              max={12}
-              step={1}
-              value={config.pitch}
-              onChange={handlePitchChange}
-              tooltip={{ formatter: (v) => `${v}半音` }}
-            />
-            <div className="tts-slider-marks">
-              <span>-12</span>
-              <span>0</span>
-              <span>+12</span>
-            </div>
-          </div>
+          <TtsSlider
+            label="语调"
+            value={config.pitch}
+            min={-12}
+            max={12}
+            step={1}
+            unit="半音"
+            onChange={handlePitchChange}
+            marks={["-12", "0", "+12"]}
+            tooltipFormatter={(v) => `${v}半音`}
+          />
 
           {/* 音量滑块 */}
-          <div className="tts-slider-section">
-            <div className="tts-slider-header">
-              <span className="tts-slider-label">音量</span>
-              <span className="tts-slider-value">{config.volume}%</span>
-            </div>
-            <Slider
-              min={0}
-              max={100}
-              step={1}
-              value={config.volume}
-              onChange={handleVolumeChange}
-              tooltip={{ formatter: (v) => `${v}%` }}
-            />
-          </div>
+          <TtsSlider
+            label="音量"
+            value={config.volume}
+            min={0}
+            max={100}
+            step={1}
+            unit="%"
+            onChange={handleVolumeChange}
+            tooltipFormatter={(v) => `${v}%`}
+          />
 
           {/* 试听按钮 */}
           <div className="tts-preview-section">

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

@@ -3,38 +3,16 @@
  * 三个 Tab：图片水印 / 文字水印 / 滚动水印
  * 通用设置：位置、不透明度
  */
-import React, { useCallback, useState } from "react"
+import React from "react"
 import { Drawer } from "antd"
-import type { WatermarkConfig, WatermarkType, WatermarkPosition, ScrollDirection } from "../types"
-import { DEFAULT_WATERMARK } from "../types"
+import type { WatermarkConfig } from "@/pages/editing-planner/types"
+import WatermarkTypeTabs from "./watermark/WatermarkTypeTabs"
+import ImageWatermarkSection from "./watermark/ImageWatermarkSection"
+import TextWatermarkSection from "./watermark/TextWatermarkSection"
+import ScrollWatermarkSection from "./watermark/ScrollWatermarkSection"
+import WatermarkCommonSection from "./watermark/WatermarkCommonSection"
+import { useWatermarkConfig } from "@/pages/editing-planner/hooks/useWatermarkConfig"
 
-/* ──────────── 常量 ──────────── */
-
-const WATERMARK_TABS: { key: WatermarkType; label: string; icon: string }[] = [
-  { key: "none", label: "无水印", icon: "🚫" },
-  { key: "image", label: "图片水印", icon: "🖼️" },
-  { key: "text", label: "文字水印", icon: "📝" },
-  { key: "scroll", label: "滚动水印", icon: "📜" },
-]
-
-const POSITION_OPTIONS: { value: WatermarkPosition; label: string }[] = [
-  { value: "top_left", label: "左上角" },
-  { value: "top_right", label: "右上角" },
-  { value: "bottom_left", label: "左下角" },
-  { value: "bottom_right", label: "右下角" },
-  { value: "center", label: "居中" },
-]
-
-const SCROLL_DIRECTION_OPTIONS: {
-  value: ScrollDirection
-  label: string
-}[] = [
-  { value: "horizontal", label: "水平滚动" },
-  { value: "vertical", label: "垂直滚动" },
-  { value: "diagonal", label: "对角滚动" },
-]
-
-/* ──────────── Props ──────────── */
 interface WatermarkPanelProps {
   open: boolean
   onClose: () => void
@@ -43,100 +21,21 @@ interface WatermarkPanelProps {
 }
 
 const WatermarkPanel: React.FC<WatermarkPanelProps> = ({ open, onClose, config, onChange }) => {
-  /* ── 图片上传预览 URL（本地预览用） ── */
-  const [localImageUrl, setLocalImageUrl] = useState<string>("")
-
-  /* ── 切换水印类型 ── */
-  const handleTypeChange = useCallback(
-    (type: WatermarkType) => {
-      onChange({ ...DEFAULT_WATERMARK, type })
-    },
-    [onChange],
-  )
-
-  /* ── 通用设置变更 ── */
-  const handlePositionChange = useCallback(
-    (position: WatermarkPosition) => {
-      onChange({ ...config, position })
-    },
-    [config, onChange],
-  )
-
-  const handleOpacityChange = useCallback(
-    (opacity: number) => {
-      onChange({ ...config, opacity })
-    },
-    [config, onChange],
-  )
-
-  /* ── 图片水印设置 ── */
-  const handleImageUrlChange = useCallback(
-    (url: string) => {
-      setLocalImageUrl(url)
-      onChange({ ...config, image_url: url })
-    },
-    [config, onChange],
-  )
-
-  const handleImageWidthChange = useCallback(
-    (width: number) => {
-      onChange({ ...config, width })
-    },
-    [config, onChange],
-  )
-
-  const handleImageHeightChange = useCallback(
-    (height: number) => {
-      onChange({ ...config, height })
-    },
-    [config, onChange],
-  )
-
-  /* ── 文字水印设置 ── */
-  const handleTextChange = useCallback(
-    (text: string) => {
-      onChange({ ...config, text })
-    },
-    [config, onChange],
-  )
-
-  const handleFontSizeChange = useCallback(
-    (font_size: number) => {
-      onChange({ ...config, font_size })
-    },
-    [config, onChange],
-  )
-
-  const handleColorChange = useCallback(
-    (color: string) => {
-      onChange({ ...config, color })
-    },
-    [config, onChange],
-  )
-
-  /* ── 滚动水印设置 ── */
-  const handleScrollDirectionChange = useCallback(
-    (scroll_direction: ScrollDirection) => {
-      onChange({ ...config, scroll_direction })
-    },
-    [config, onChange],
-  )
-
-  const handleScrollSpeedChange = useCallback(
-    (scroll_speed: number) => {
-      onChange({ ...config, scroll_speed })
-    },
-    [config, onChange],
-  )
-
-  /* ── 重置 ── */
-  const handleReset = useCallback(() => {
-    setLocalImageUrl("")
-    onChange({ ...DEFAULT_WATERMARK })
-  }, [onChange])
-
-  /* ── 当前激活的 Tab ── */
-  const activeTab = config.type
+  const {
+    localImageUrl,
+    handleTypeChange,
+    handlePositionChange,
+    handleOpacityChange,
+    handleImageUrlChange,
+    handleImageWidthChange,
+    handleImageHeightChange,
+    handleTextChange,
+    handleFontSizeChange,
+    handleColorChange,
+    handleScrollDirectionChange,
+    handleScrollSpeedChange,
+    handleReset,
+  } = useWatermarkConfig({ config, onChange })
 
   return (
     <Drawer
@@ -148,18 +47,7 @@ const WatermarkPanel: React.FC<WatermarkPanelProps> = ({ open, onClose, config,
       className="watermark-panel-drawer"
     >
       {/* ── Tab 切换 ── */}
-      <div className="wp-tabs">
-        {WATERMARK_TABS.map((tab) => (
-          <button
-            key={tab.key}
-            className={`wp-tab${activeTab === tab.key ? " active" : ""}`}
-            onClick={() => handleTypeChange(tab.key)}
-          >
-            <span className="wp-tab-icon">{tab.icon}</span>
-            <span className="wp-tab-label">{tab.label}</span>
-          </button>
-        ))}
-      </div>
+      <WatermarkTypeTabs activeTab={config.type} onTypeChange={handleTypeChange} />
 
       {/* ── 无水印提示 ── */}
       {config.type === "none" && (
@@ -172,210 +60,53 @@ const WatermarkPanel: React.FC<WatermarkPanelProps> = ({ open, onClose, config,
 
       {/* ── 图片水印配置 ── */}
       {config.type === "image" && (
-        <div className="wp-section">
-          <div className="wp-field">
-            <label className="wp-field-label">水印图片 URL</label>
-            <input
-              className="wp-input"
-              type="text"
-              placeholder="https://example.com/logo.png"
-              value={localImageUrl || config.image_url || ""}
-              onChange={(e) => handleImageUrlChange(e.target.value)}
-            />
-            {(localImageUrl || config.image_url) && (
-              <div className="wp-image-preview">
-                <img
-                  src={localImageUrl || config.image_url}
-                  alt="水印预览"
-                  onError={(e) => {
-                    ;(e.target as HTMLImageElement).style.display = "none"
-                  }}
-                />
-              </div>
-            )}
-          </div>
-
-          <div className="wp-field">
-            <label className="wp-field-label">宽度（像素，0 表示自适应）</label>
-            <input
-              className="wp-input"
-              type="number"
-              min={0}
-              max={2000}
-              value={config.width ?? 0}
-              onChange={(e) => handleImageWidthChange(Number(e.target.value))}
-            />
-          </div>
-
-          <div className="wp-field">
-            <label className="wp-field-label">高度（像素，0 表示自适应）</label>
-            <input
-              className="wp-input"
-              type="number"
-              min={0}
-              max={2000}
-              value={config.height ?? 0}
-              onChange={(e) => handleImageHeightChange(Number(e.target.value))}
-            />
-          </div>
-        </div>
+        <ImageWatermarkSection
+          imageUrl={config.image_url || ""}
+          localImageUrl={localImageUrl}
+          width={config.width}
+          height={config.height}
+          onImageUrlChange={handleImageUrlChange}
+          onWidthChange={handleImageWidthChange}
+          onHeightChange={handleImageHeightChange}
+        />
       )}
 
       {/* ── 文字水印配置 ── */}
       {config.type === "text" && (
-        <div className="wp-section">
-          <div className="wp-field">
-            <label className="wp-field-label">水印文字</label>
-            <textarea
-              className="wp-textarea"
-              placeholder="输入水印文字内容"
-              rows={3}
-              value={config.text ?? ""}
-              onChange={(e) => handleTextChange(e.target.value)}
-            />
-          </div>
-
-          <div className="wp-field">
-            <label className="wp-field-label">字号</label>
-            <div className="wp-slider-row">
-              <input
-                className="wp-slider"
-                type="range"
-                min={12}
-                max={72}
-                value={config.font_size ?? 24}
-                onChange={(e) => handleFontSizeChange(Number(e.target.value))}
-              />
-              <span className="wp-slider-value">{config.font_size ?? 24}px</span>
-            </div>
-          </div>
-
-          <div className="wp-field">
-            <label className="wp-field-label">文字颜色</label>
-            <div className="wp-color-row">
-              <input
-                className="wp-color-input"
-                type="color"
-                value={config.color ?? "#ffffff"}
-                onChange={(e) => handleColorChange(e.target.value)}
-              />
-              <span className="wp-color-value">{config.color ?? "#ffffff"}</span>
-            </div>
-          </div>
-        </div>
+        <TextWatermarkSection
+          text={config.text || ""}
+          fontSize={config.font_size ?? 24}
+          color={config.color ?? "#ffffff"}
+          onTextChange={handleTextChange}
+          onFontSizeChange={handleFontSizeChange}
+          onColorChange={handleColorChange}
+        />
       )}
 
       {/* ── 滚动水印配置 ── */}
       {config.type === "scroll" && (
-        <div className="wp-section">
-          <div className="wp-field">
-            <label className="wp-field-label">滚动文字</label>
-            <textarea
-              className="wp-textarea"
-              placeholder="输入滚动水印文字"
-              rows={2}
-              value={config.text ?? ""}
-              onChange={(e) => handleTextChange(e.target.value)}
-            />
-          </div>
-
-          <div className="wp-field">
-            <label className="wp-field-label">滚动方向</label>
-            <select
-              className="wp-select"
-              value={config.scroll_direction ?? "horizontal"}
-              onChange={(e) => handleScrollDirectionChange(e.target.value as ScrollDirection)}
-            >
-              {SCROLL_DIRECTION_OPTIONS.map((opt) => (
-                <option key={opt.value} value={opt.value}>
-                  {opt.label}
-                </option>
-              ))}
-            </select>
-          </div>
-
-          <div className="wp-field">
-            <label className="wp-field-label">滚动速度</label>
-            <div className="wp-slider-row">
-              <input
-                className="wp-slider"
-                type="range"
-                min={10}
-                max={200}
-                value={config.scroll_speed ?? 50}
-                onChange={(e) => handleScrollSpeedChange(Number(e.target.value))}
-              />
-              <span className="wp-slider-value">{config.scroll_speed ?? 50}px/s</span>
-            </div>
-          </div>
-
-          <div className="wp-field">
-            <label className="wp-field-label">字号</label>
-            <div className="wp-slider-row">
-              <input
-                className="wp-slider"
-                type="range"
-                min={12}
-                max={72}
-                value={config.font_size ?? 24}
-                onChange={(e) => handleFontSizeChange(Number(e.target.value))}
-              />
-              <span className="wp-slider-value">{config.font_size ?? 24}px</span>
-            </div>
-          </div>
-
-          <div className="wp-field">
-            <label className="wp-field-label">文字颜色</label>
-            <div className="wp-color-row">
-              <input
-                className="wp-color-input"
-                type="color"
-                value={config.color ?? "#ffffff"}
-                onChange={(e) => handleColorChange(e.target.value)}
-              />
-              <span className="wp-color-value">{config.color ?? "#ffffff"}</span>
-            </div>
-          </div>
-        </div>
+        <ScrollWatermarkSection
+          text={config.text || ""}
+          scrollDirection={config.scroll_direction ?? "horizontal"}
+          scrollSpeed={config.scroll_speed ?? 50}
+          fontSize={config.font_size ?? 24}
+          color={config.color ?? "#ffffff"}
+          onTextChange={handleTextChange}
+          onScrollDirectionChange={handleScrollDirectionChange}
+          onScrollSpeedChange={handleScrollSpeedChange}
+          onFontSizeChange={handleFontSizeChange}
+          onColorChange={handleColorChange}
+        />
       )}
 
       {/* ── 通用设置（非 none 时显示） ── */}
       {config.type !== "none" && (
-        <div className="wp-section wp-common-section">
-          <div className="wp-section-divider" />
-          <div className="wp-common-title">通用设置</div>
-
-          <div className="wp-field">
-            <label className="wp-field-label">水印位置</label>
-            <select
-              className="wp-select"
-              value={config.position}
-              onChange={(e) => handlePositionChange(e.target.value as WatermarkPosition)}
-            >
-              {POSITION_OPTIONS.map((opt) => (
-                <option key={opt.value} value={opt.value}>
-                  {opt.label}
-                </option>
-              ))}
-            </select>
-          </div>
-
-          <div className="wp-field">
-            <label className="wp-field-label">不透明度</label>
-            <div className="wp-slider-row">
-              <input
-                className="wp-slider"
-                type="range"
-                min={0}
-                max={1}
-                step={0.05}
-                value={config.opacity}
-                onChange={(e) => handleOpacityChange(Number(e.target.value))}
-              />
-              <span className="wp-slider-value">{Math.round(config.opacity * 100)}%</span>
-            </div>
-          </div>
-        </div>
+        <WatermarkCommonSection
+          position={config.position}
+          opacity={config.opacity}
+          onPositionChange={handlePositionChange}
+          onOpacityChange={handleOpacityChange}
+        />
       )}
 
       {/* ── 底部操作 ── */}

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

@@ -0,0 +1,41 @@
+/**
+ * BGM 设置区块
+ */
+import React from "react"
+import type { BgmSettings } from "@/pages/editing-planner/types/clipProperties"
+
+interface BgmSettingsSectionProps {
+  settings: BgmSettings
+  onOpenBgmDrawer?: () => void
+}
+
+const BgmSettingsSection: React.FC<BgmSettingsSectionProps> = ({ settings, onOpenBgmDrawer }) => {
+  return (
+    <div className="ep-settings-section">
+      <div className="ep-section-title">
+        <span className="ep-section-icon">🎵</span>
+        BGM 设置
+      </div>
+
+      {settings.enabled && settings.music_id ? (
+        <div className="ep-bgm-current">
+          <span className="ep-bgm-current-label">🎵 已选择 BGM</span>
+          <span className="ep-bgm-current-id">{settings.music_id}</span>
+          {settings.volume !== undefined && (
+            <span className="ep-bgm-current-vol">音量 {settings.volume}%</span>
+          )}
+        </div>
+      ) : (
+        <div className="ep-bgm-empty">未选择背景音乐</div>
+      )}
+
+      {onOpenBgmDrawer && (
+        <button className="ep-advanced-btn" onClick={onOpenBgmDrawer}>
+          🎵 {settings.enabled ? "更换 BGM / 调整混音" : "选择 BGM 音乐"}
+        </button>
+      )}
+    </div>
+  )
+}
+
+export default BgmSettingsSection

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

@@ -0,0 +1,266 @@
+/**
+ * 片段详情区块
+ */
+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

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

@@ -0,0 +1,39 @@
+/**
+ * 编辑统计区块
+ */
+import React from "react"
+import { formatModeLabel } from "@/pages/editing-planner/utils/clipProperties"
+import type { TemplateMode } from "@/api/editing-planner"
+
+interface StatsSectionProps {
+  clipsCount: number
+  totalDuration: number
+  currentMode: TemplateMode
+}
+
+const StatsSection: React.FC<StatsSectionProps> = ({ clipsCount, totalDuration, currentMode }) => {
+  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-detail-value">{clipsCount}</div>
+        </div>
+        <div className="ep-clip-detail-field">
+          <div className="ep-clip-detail-label">总时长</div>
+          <div className="ep-clip-detail-value">{totalDuration.toFixed(1)}s</div>
+        </div>
+        <div className="ep-clip-detail-field">
+          <div className="ep-clip-detail-label">当前模式</div>
+          <div className="ep-clip-detail-value">{formatModeLabel(currentMode)}</div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default StatsSection

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

@@ -0,0 +1,113 @@
+/**
+ * 字幕设置区块
+ */
+import React from "react"
+import {
+  POSITION_OPTIONS,
+  FONT_OPTIONS,
+  ANIMATION_OPTIONS,
+} from "@/pages/editing-planner/constants/clipProperties"
+import type { SubtitleSettings } from "@/pages/editing-planner/types/clipProperties"
+
+interface SubtitleSettingsSectionProps {
+  settings: SubtitleSettings
+  onChange: (partial: Partial<SubtitleSettings>) => void
+  onOpenSubtitleDrawer?: () => void
+}
+
+const SubtitleSettingsSection: React.FC<SubtitleSettingsSectionProps> = ({
+  settings,
+  onChange,
+  onOpenSubtitleDrawer,
+}) => {
+  return (
+    <div className="ep-settings-section">
+      <div className="ep-section-title">
+        <span className="ep-section-icon">💬</span>
+        字幕设置
+      </div>
+
+      <div className="ep-toggle-row">
+        <span className="ep-toggle-label">启用字幕</span>
+        <div
+          className={`ep-toggle ${settings.enabled ? "active" : ""}`}
+          onClick={() => onChange({ enabled: !settings.enabled })}
+        >
+          <div className="ep-toggle-knob" />
+        </div>
+      </div>
+
+      {settings.enabled && (
+        <>
+          <div className="ep-field">
+            <label className="ep-field-label">位置</label>
+            <select
+              className="ep-form-select"
+              value={settings.position}
+              onChange={(e) => onChange({ position: e.target.value })}
+            >
+              {POSITION_OPTIONS.map((opt) => (
+                <option key={opt.value} value={opt.value}>
+                  {opt.label}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          <div className="ep-field">
+            <label className="ep-field-label">字体</label>
+            <select
+              className="ep-form-select"
+              value={settings.font}
+              onChange={(e) => onChange({ font: e.target.value })}
+            >
+              {FONT_OPTIONS.map((f) => (
+                <option key={f} value={f}>
+                  {f}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          <div className="ep-field">
+            <label className="ep-field-label">大小</label>
+            <div className="ep-slider-row">
+              <input
+                className="ep-slider"
+                type="range"
+                min={12}
+                max={48}
+                value={settings.fontSize}
+                onChange={(e) => onChange({ fontSize: Number(e.target.value) })}
+              />
+              <span className="ep-slider-value">{settings.fontSize}px</span>
+            </div>
+          </div>
+
+          <div className="ep-field">
+            <label className="ep-field-label">动画</label>
+            <select
+              className="ep-form-select"
+              value={settings.animation}
+              onChange={(e) => onChange({ animation: e.target.value })}
+            >
+              {ANIMATION_OPTIONS.map((opt) => (
+                <option key={opt.value} value={opt.value}>
+                  {opt.label}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          {onOpenSubtitleDrawer && (
+            <button className="ep-advanced-btn" onClick={onOpenSubtitleDrawer}>
+              🎨 高级字幕样式配置
+            </button>
+          )}
+        </>
+      )}
+    </div>
+  )
+}
+
+export default SubtitleSettingsSection

apps/web/src/pages/editing-planner/components/filter/FilterManualAdjust.tsx

@@ -0,0 +1,40 @@
+/**
+ * 滤镜手动调节组件
+ */
+import React from "react"
+import type { FilterConfig } from "../../types"
+import { MANUAL_ADJUST_ITEMS } from "../../constants/filter"
+
+type FilterKey = keyof Pick<
+  FilterConfig,
+  "brightness" | "contrast" | "saturation" | "temperature" | "tint" | "sharpness"
+>
+
+interface FilterManualAdjustProps {
+  config: FilterConfig
+  onChange: (key: FilterKey, value: number) => void
+}
+
+const FilterManualAdjust: React.FC<FilterManualAdjustProps> = ({ config, onChange }) => {
+  return (
+    <div className="filter-section">
+      <div className="filter-section-title">手动调节</div>
+      {MANUAL_ADJUST_ITEMS.map((item) => (
+        <div key={item.key} className="filter-slider-row">
+          <span className="filter-slider-label">{item.label}</span>
+          <input
+            type="range"
+            className="filter-slider"
+            min={item.min}
+            max={item.max}
+            value={config[item.key as FilterKey]}
+            onChange={(e) => onChange(item.key as FilterKey, Number(e.target.value))}
+          />
+          <span className="filter-slider-value">{config[item.key as FilterKey]}</span>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+export default FilterManualAdjust

apps/web/src/pages/editing-planner/components/filter/FilterPresetGrid.tsx

@@ -0,0 +1,34 @@
+/**
+ * 滤镜预设选择组件
+ */
+import React from "react"
+import type { FilterPreset } from "../../types"
+import { FILTER_PRESET_LABELS } from "../../types"
+import { PRESET_LIST, PRESET_GRADIENTS } from "../../constants/filter"
+
+interface FilterPresetGridProps {
+  selectedPreset: FilterPreset
+  onPresetSelect: (preset: FilterPreset) => void
+}
+
+const FilterPresetGrid: React.FC<FilterPresetGridProps> = ({ selectedPreset, onPresetSelect }) => {
+  return (
+    <div className="filter-section">
+      <div className="filter-section-title">预设滤镜</div>
+      <div className="filter-presets">
+        {PRESET_LIST.map((p) => (
+          <button
+            key={p}
+            className={`filter-preset-item${selectedPreset === p ? " active" : ""}`}
+            onClick={() => onPresetSelect(p)}
+          >
+            <div className="filter-preset-preview" style={{ background: PRESET_GRADIENTS[p] }} />
+            <span className="filter-preset-label">{FILTER_PRESET_LABELS[p]}</span>
+          </button>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+export default FilterPresetGrid

apps/web/src/pages/editing-planner/components/intro-outro/IntroOutroBlock.tsx

@@ -0,0 +1,123 @@
+/**
+ * 片头/片尾通用区块组件（片头片尾结构对称，复用同一个组件）
+ */
+import React from "react"
+import type { IntroOutroItem, IntroOutroKind, TransitionType } from "../../types"
+import { TRANSITION_OPTIONS } from "@/api/template-editor"
+import { KIND_OPTIONS } from "../../constants/introOutro"
+
+interface IntroOutroBlockProps {
+  title: string
+  icon: string
+  item: IntroOutroItem
+  transitionLabel: string
+  onKindChange: (kind: IntroOutroKind) => void
+  onChange: (partial: Partial<IntroOutroItem>) => void
+}
+
+const IntroOutroBlock: React.FC<IntroOutroBlockProps> = ({
+  title,
+  icon,
+  item,
+  transitionLabel,
+  onKindChange,
+  onChange,
+}) => {
+  const hasContent = item.kind !== "none"
+
+  return (
+    <div className="iop-block">
+      <div className="iop-block-header">
+        <span className="iop-block-icon">{icon}</span>
+        <span className="iop-block-title">{title}</span>
+      </div>
+
+      {/* 类型选择 */}
+      <div className="iop-kind-row">
+        {KIND_OPTIONS.map((opt) => (
+          <button
+            key={opt.value}
+            className={`iop-kind-btn${item.kind === opt.value ? " active" : ""}`}
+            onClick={() => onKindChange(opt.value)}
+          >
+            <span className="iop-kind-icon">{opt.icon}</span>
+            <span className="iop-kind-label">{opt.label}</span>
+          </button>
+        ))}
+      </div>
+
+      {/* 视频/图片配置 */}
+      {hasContent && (
+        <>
+          <div className="iop-field">
+            <label className="iop-field-label">{item.kind === "video" ? "视频" : "图片"} URL</label>
+            <input
+              className="iop-input"
+              type="text"
+              placeholder={
+                item.kind === "video"
+                  ? `https://example.com/${title}.mp4`
+                  : `https://example.com/${title}.png`
+              }
+              value={item.url ?? ""}
+              onChange={(e) => onChange({ url: e.target.value })}
+            />
+          </div>
+
+          <div className="iop-field">
+            <label className="iop-field-label">显示时长</label>
+            <div className="iop-slider-row">
+              <input
+                className="iop-slider"
+                type="range"
+                min={1}
+                max={15}
+                step={0.5}
+                value={item.duration}
+                onChange={(e) => onChange({ duration: Number(e.target.value) })}
+              />
+              <span className="iop-slider-value">{item.duration}s</span>
+            </div>
+          </div>
+
+          <div className="iop-field">
+            <label className="iop-field-label">{transitionLabel}</label>
+            <select
+              className="iop-select"
+              value={item.transition ?? "none"}
+              onChange={(e) => onChange({ transition: e.target.value as TransitionType })}
+            >
+              {TRANSITION_OPTIONS.map((opt) => (
+                <option key={opt.value} value={opt.value}>
+                  {opt.label}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          {item.transition && item.transition !== "none" && (
+            <div className="iop-field">
+              <label className="iop-field-label">过渡时长</label>
+              <div className="iop-slider-row">
+                <input
+                  className="iop-slider"
+                  type="range"
+                  min={0.3}
+                  max={2.0}
+                  step={0.1}
+                  value={item.transition_duration ?? 0.5}
+                  onChange={(e) => onChange({ transition_duration: Number(e.target.value) })}
+                />
+                <span className="iop-slider-value">
+                  {(item.transition_duration ?? 0.5).toFixed(1)}s
+                </span>
+              </div>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  )
+}
+
+export default IntroOutroBlock

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

@@ -0,0 +1,286 @@
+/**
+ * 混剪单图层配置区
+ */
+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

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

@@ -0,0 +1,65 @@
+/**
+ * 混剪图层列表
+ */
+import React from "react"
+import type { PipLayer } from "@/pages/editing-planner/types"
+import { LAYER_COLORS } from "@/pages/editing-planner/constants/pipConfig"
+
+interface LayerListProps {
+  layers: PipLayer[]
+  selectedId: string
+  onSelect: (id: string) => void
+  onAdd: () => void
+  onDelete: (id: string) => void
+}
+
+const LayerList: React.FC<LayerListProps> = ({ layers, selectedId, onSelect, onAdd, onDelete }) => {
+  return (
+    <div className="pip-layer-list">
+      <div className="pip-toolbar" style={{ marginBottom: 8 }}>
+        <button className="pip-add-btn" onClick={onAdd}>
+          + 添加图层
+        </button>
+      </div>
+      {layers.length === 0 ? (
+        <div className="pip-layer-empty">暂无图层，点击上方添加</div>
+      ) : (
+        layers.map((layer, idx) => (
+          <div
+            key={layer.id}
+            className={`pip-layer-item${selectedId === layer.id ? " active" : ""}`}
+            onClick={() => onSelect(layer.id)}
+          >
+            {layer.thumbnail_url || layer.material_url ? (
+              <img
+                className="pip-layer-thumb"
+                src={layer.thumbnail_url || layer.material_url}
+                alt={layer.name}
+              />
+            ) : (
+              <div
+                className="pip-layer-thumb"
+                style={{
+                  background: LAYER_COLORS[idx % LAYER_COLORS.length],
+                }}
+              />
+            )}
+            <span className="pip-layer-name">{layer.name}</span>
+            <button
+              className="pip-layer-delete"
+              onClick={(e) => {
+                e.stopPropagation()
+                onDelete(layer.id)
+              }}
+              title="删除图层"
+            >
+              ✕
+            </button>
+          </div>
+        ))
+      )}
+    </div>
+  )
+}
+
+export default LayerList

apps/web/src/pages/editing-planner/components/sticker/StickerLibrary.tsx

@@ -0,0 +1,142 @@
+/**
+ * 贴纸素材库（emoji / 图片 / 文字花字）
+ */
+import React, { useState } from "react"
+import type { StickerType, TextStickerPreset } from "@/pages/editing-planner/types"
+import {
+  EMOJI_LIST,
+  STICKER_TYPE_TABS,
+  TEXT_PRESET_STYLES,
+  TEXT_STICKER_PRESET_LABELS,
+} from "@/pages/editing-planner/constants/sticker"
+
+interface StickerLibraryProps {
+  activeTab: StickerType
+  onTabChange: (tab: StickerType) => void
+  onAddSticker: (type: StickerType, content: string) => void
+}
+
+const StickerLibrary: React.FC<StickerLibraryProps> = ({
+  activeTab,
+  onTabChange,
+  onAddSticker,
+}) => {
+  const [textInput, setTextInput] = useState("")
+  const imageInputRef = React.useRef<HTMLInputElement>(null)
+
+  const handleAddImage = () => {
+    const val = imageInputRef.current?.value.trim()
+    if (val) {
+      onAddSticker("image", val)
+      if (imageInputRef.current) imageInputRef.current.value = ""
+    }
+  }
+
+  const handleAddText = () => {
+    if (textInput.trim()) {
+      onAddSticker("text", textInput.trim())
+      setTextInput("")
+    }
+  }
+
+  return (
+    <>
+      {/* 类型 Tab */}
+      <div className="sticker-tabs">
+        {STICKER_TYPE_TABS.map((t) => (
+          <button
+            key={t.value}
+            className={`sticker-tab${activeTab === t.value ? " active" : ""}`}
+            onClick={() => onTabChange(t.value)}
+          >
+            {t.label}
+          </button>
+        ))}
+      </div>
+
+      {/* Tab 内容区 */}
+      <div className="sticker-tab-content">
+        {/* Emoji 素材库 */}
+        {activeTab === "emoji" && (
+          <div className="sticker-emoji-grid">
+            {EMOJI_LIST.map((emoji) => (
+              <button
+                key={emoji}
+                className="sticker-emoji-btn"
+                onClick={() => onAddSticker("emoji", emoji)}
+              >
+                {emoji}
+              </button>
+            ))}
+          </div>
+        )}
+
+        {/* 图片贴纸 */}
+        {activeTab === "image" && (
+          <div className="sticker-image-input">
+            <input
+              ref={imageInputRef}
+              type="text"
+              className="sticker-url-input"
+              placeholder="输入图片 URL 添加贴纸..."
+              onKeyDown={(e) => {
+                if (e.key === "Enter" && e.currentTarget.value.trim()) {
+                  handleAddImage()
+                }
+              }}
+            />
+            <button className="sticker-url-add-btn" onClick={handleAddImage}>
+              添加
+            </button>
+          </div>
+        )}
+
+        {/* 文字花字 */}
+        {activeTab === "text" && (
+          <div className="sticker-text-section">
+            <div className="sticker-text-input-row">
+              <input
+                type="text"
+                className="sticker-text-input"
+                placeholder="输入文字内容..."
+                value={textInput}
+                onChange={(e) => setTextInput(e.target.value)}
+              />
+              <button
+                className="sticker-text-add-btn"
+                disabled={!textInput.trim()}
+                onClick={handleAddText}
+              >
+                添加
+              </button>
+            </div>
+            <div className="sticker-text-presets">
+              <div className="sticker-preset-title">花字预设预览</div>
+              <div className="sticker-preset-grid">
+                {(Object.keys(TEXT_STICKER_PRESET_LABELS) as TextStickerPreset[]).map((p) => (
+                  <div
+                    key={p}
+                    className="sticker-preset-preview"
+                    style={{
+                      background:
+                        p === "bubble"
+                          ? "rgba(0,0,0,0.5)"
+                          : p === "gradient"
+                            ? "linear-gradient(90deg,#f093fb,#f5576c)"
+                            : "#1a1a2e",
+                    }}
+                  >
+                    <span style={TEXT_PRESET_STYLES[p]}>示例</span>
+                    <div className="sticker-preset-name">{TEXT_STICKER_PRESET_LABELS[p]}</div>
+                  </div>
+                ))}
+              </div>
+            </div>
+          </div>
+        )}
+      </div>
+    </>
+  )
+}
+
+export default StickerLibrary

apps/web/src/pages/editing-planner/components/sticker/StickerList.tsx

@@ -0,0 +1,54 @@
+/**
+ * 已添加贴纸列表
+ */
+import React from "react"
+import type { StickerItem } from "@/pages/editing-planner/types"
+
+interface StickerListProps {
+  items: StickerItem[]
+  selectedId: string | null
+  onSelect: (id: string) => void
+  onDelete: (id: string) => void
+}
+
+const StickerList: React.FC<StickerListProps> = ({ items, selectedId, onSelect, onDelete }) => {
+  if (items.length === 0) return null
+
+  const getDisplayContent = (item: StickerItem) => {
+    if (item.type === "emoji") return { icon: item.content, name: "表情贴纸" }
+    if (item.type === "text") return { icon: "T", name: item.content.slice(0, 10) }
+    return { icon: "🖼", name: "图片贴纸" }
+  }
+
+  return (
+    <div className="sticker-list-section">
+      <div className="sticker-section-title">已添加贴纸 ({items.length})</div>
+      <div className="sticker-list">
+        {items.map((item) => {
+          const { icon, name } = getDisplayContent(item)
+          return (
+            <div
+              key={item.id}
+              className={`sticker-list-item${selectedId === item.id ? " active" : ""}`}
+              onClick={() => onSelect(item.id)}
+            >
+              <span className="sticker-list-icon">{icon}</span>
+              <span className="sticker-list-name">{name}</span>
+              <button
+                className="sticker-list-delete"
+                onClick={(e) => {
+                  e.stopPropagation()
+                  onDelete(item.id)
+                }}
+              >
+                ✕
+              </button>
+            </div>
+          )
+        })}
+      </div>
+    </div>
+  )
+}
+
+export default StickerList

apps/web/src/pages/editing-planner/components/sticker/StickerPropsEditor.tsx

@@ -0,0 +1,200 @@
+/**
+ * 选中贴纸的属性编辑器
+ */
+import React from "react"
+import type { StickerItem, TextStickerPreset } from "@/pages/editing-planner/types"
+import {
+  TEXT_PRESET_STYLES,
+  TEXT_STICKER_PRESET_LABELS,
+} from "@/pages/editing-planner/constants/sticker"
+
+interface StickerPropsEditorProps {
+  sticker: StickerItem
+  totalDuration: number
+  onUpdate: (id: string, partial: Partial<StickerItem>) => void
+}
+
+const StickerPropsEditor: React.FC<StickerPropsEditorProps> = ({
+  sticker,
+  totalDuration,
+  onUpdate,
+}) => {
+  return (
+    <div className="sticker-props-section">
+      <div className="sticker-section-title">属性调整</div>
+
+      {/* 位置 */}
+      <div className="sticker-prop-row">
+        <span className="sticker-prop-label">位置 X</span>
+        <input
+          type="range"
+          className="sticker-prop-slider"
+          min={0}
+          max={100}
+          value={sticker.x}
+          onChange={(e) => onUpdate(sticker.id, { x: Number(e.target.value) })}
+        />
+        <span className="sticker-prop-value">{sticker.x}%</span>
+      </div>
+      <div className="sticker-prop-row">
+        <span className="sticker-prop-label">位置 Y</span>
+        <input
+          type="range"
+          className="sticker-prop-slider"
+          min={0}
+          max={100}
+          value={sticker.y}
+          onChange={(e) => onUpdate(sticker.id, { y: Number(e.target.value) })}
+        />
+        <span className="sticker-prop-value">{sticker.y}%</span>
+      </div>
+
+      {/* 尺寸 */}
+      <div className="sticker-prop-row">
+        <span className="sticker-prop-label">大小</span>
+        <input
+          type="range"
+          className="sticker-prop-slider"
+          min={5}
+          max={50}
+          value={sticker.width}
+          onChange={(e) =>
+            onUpdate(sticker.id, {
+              width: Number(e.target.value),
+              height: Number(e.target.value),
+            })
+          }
+        />
+        <span className="sticker-prop-value">{sticker.width}%</span>
+      </div>
+
+      {/* 旋转 */}
+      <div className="sticker-prop-row">
+        <span className="sticker-prop-label">旋转</span>
+        <input
+          type="range"
+          className="sticker-prop-slider"
+          min={-180}
+          max={180}
+          value={sticker.rotation}
+          onChange={(e) => onUpdate(sticker.id, { rotation: Number(e.target.value) })}
+        />
+        <span className="sticker-prop-value">{sticker.rotation}°</span>
+      </div>
+
+      {/* 透明度 */}
+      <div className="sticker-prop-row">
+        <span className="sticker-prop-label">透明度</span>
+        <input
+          type="range"
+          className="sticker-prop-slider"
+          min={0}
+          max={100}
+          value={sticker.opacity}
+          onChange={(e) => onUpdate(sticker.id, { opacity: Number(e.target.value) })}
+        />
+        <span className="sticker-prop-value">{sticker.opacity}%</span>
+      </div>
+
+      {/* 时间 */}
+      <div className="sticker-prop-row">
+        <span className="sticker-prop-label">开始</span>
+        <input
+          type="number"
+          className="sticker-prop-number"
+          min={0}
+          max={totalDuration}
+          step={0.1}
+          value={sticker.start_time}
+          onChange={(e) => onUpdate(sticker.id, { start_time: Number(e.target.value) })}
+        />
+        <span className="sticker-prop-label">时长</span>
+        <input
+          type="number"
+          className="sticker-prop-number"
+          min={0}
+          max={totalDuration}
+          step={0.1}
+          value={sticker.duration}
+          onChange={(e) => onUpdate(sticker.id, { duration: Number(e.target.value) })}
+        />
+      </div>
+
+      {/* 文字贴纸特有属性 */}
+      {sticker.type === "text" && (
+        <>
+          <div className="sticker-prop-row">
+            <span className="sticker-prop-label">花字</span>
+            <select
+              className="sticker-prop-select"
+              value={sticker.text_preset}
+              onChange={(e) =>
+                onUpdate(sticker.id, { text_preset: e.target.value as TextStickerPreset })
+              }
+            >
+              {(Object.keys(TEXT_STICKER_PRESET_LABELS) as TextStickerPreset[]).map((p) => (
+                <option key={p} value={p}>
+                  {TEXT_STICKER_PRESET_LABELS[p]}
+                </option>
+              ))}
+            </select>
+          </div>
+          <div className="sticker-prop-row">
+            <span className="sticker-prop-label">字号</span>
+            <input
+              type="range"
+              className="sticker-prop-slider"
+              min={12}
+              max={72}
+              value={sticker.font_size}
+              onChange={(e) => onUpdate(sticker.id, { font_size: Number(e.target.value) })}
+            />
+            <span className="sticker-prop-value">{sticker.font_size}px</span>
+          </div>
+          <div className="sticker-prop-row">
+            <span className="sticker-prop-label">颜色</span>
+            <input
+              type="color"
+              className="sticker-prop-color"
+              value={sticker.text_color}
+              onChange={(e) => onUpdate(sticker.id, { text_color: e.target.value })}
+            />
+          </div>
+        </>
+      )}
+
+      {/* 预览 */}
+      <div className="sticker-preview-box">
+        <div
+          className="sticker-preview-item"
+          style={{
+            left: `${sticker.x}%`,
+            top: `${sticker.y}%`,
+            width: `${sticker.width}%`,
+            height: `${sticker.width}%`,
+            transform: `translate(-50%, -50%) rotate(${sticker.rotation}deg)`,
+            opacity: sticker.opacity / 100,
+            fontSize: sticker.type === "text" ? `${sticker.font_size}px` : undefined,
+            ...TEXT_PRESET_STYLES[sticker.text_preset],
+          }}
+        >
+          {sticker.type === "emoji" && sticker.content}
+          {sticker.type === "text" && sticker.content}
+          {sticker.type === "image" && (
+            <img
+              src={sticker.content}
+              alt="sticker"
+              style={{
+                width: "100%",
+                height: "100%",
+                objectFit: "contain",
+              }}
+            />
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default StickerPropsEditor

apps/web/src/pages/editing-planner/components/subtitle-style/SubtitlePreview.tsx

@@ -0,0 +1,37 @@
+/**
+ * 字幕预览组件
+ */
+import React from "react"
+import type { SubtitleStyleConfig } from "../../types/subtitle"
+
+interface SubtitlePreviewProps {
+  config: SubtitleStyleConfig
+  previewText?: string
+}
+
+const SubtitlePreview: React.FC<SubtitlePreviewProps> = ({
+  config,
+  previewText = "这是一段字幕预览",
+}) => {
+  return (
+    <div className="sub-field">
+      <label className="sub-label">预览</label>
+      <div className="sub-preview-box">
+        <span
+          className="sub-preview-text"
+          style={{
+            fontSize: `${Math.min(config.fontSize, 28)}px`,
+            color: config.fontColor,
+            fontFamily: config.font,
+            WebkitTextStroke: config.stroke ? "1px #000" : undefined,
+            textShadow: config.shadow ? "2px 2px 4px rgba(0,0,0,0.8)" : undefined,
+          }}
+        >
+          {previewText}
+        </span>
+      </div>
+    </div>
+  )
+}
+
+export default SubtitlePreview

apps/web/src/pages/editing-planner/components/timeline/AddClipPicker.tsx

@@ -0,0 +1,80 @@
+import React from "react"
+import type { ClipType } from "../../types"
+import { CLIP_TYPE_ICONS, CLIP_TYPE_LABELS } from "../../constants/timeline"
+
+interface AddClipPickerProps {
+  pickerRef: React.RefObject<HTMLDivElement>
+  position: { top: number; right: number }
+  availableTypes: ClipType[]
+  addType: ClipType
+  addDuration: number
+  onTypeChange: (type: ClipType) => void
+  onDurationChange: (duration: number) => void
+  onConfirm: () => void
+  minDuration?: number
+  maxDuration?: number
+}
+
+export const AddClipPicker: React.FC<AddClipPickerProps> = ({
+  pickerRef,
+  position,
+  availableTypes,
+  addType,
+  addDuration,
+  onTypeChange,
+  onDurationChange,
+  onConfirm,
+  minDuration = 1,
+  maxDuration = 120,
+}) => {
+  return (
+    <div
+      ref={pickerRef}
+      className="ep-add-clip-picker ep-add-clip-picker--portal"
+      style={{
+        position: "fixed",
+        top: position.top,
+        right: position.right,
+      }}
+    >
+      <div className="ep-add-clip-picker-title">添加片段</div>
+
+      {/* 类型选择 */}
+      <div className="ep-add-clip-type-row">
+        <span className="ep-add-clip-type-label">类型:</span>
+        {availableTypes.map((t) => (
+          <button
+            key={t}
+            className={`ep-add-clip-type-btn${addType === t ? " active" : ""}`}
+            onClick={() => onTypeChange(t)}
+          >
+            {CLIP_TYPE_ICONS[t]} {CLIP_TYPE_LABELS[t]}
+          </button>
+        ))}
+      </div>
+
+      {/* 时长输入 */}
+      <div className="ep-add-clip-duration-row">
+        <span className="ep-add-clip-type-label">时长:</span>
+        <input
+          type="number"
+          className="ep-duration-input"
+          min={minDuration}
+          max={maxDuration}
+          value={addDuration}
+          onChange={(e) =>
+            onDurationChange(
+              Math.max(minDuration, Math.min(maxDuration, Number(e.target.value) || minDuration)),
+            )
+          }
+        />
+        <span className="ep-add-clip-duration-unit">秒</span>
+      </div>
+
+      {/* 确认按钮 */}
+      <button className="ep-add-clip-confirm-btn" onClick={onConfirm}>
+        添加
+      </button>
+    </div>
+  )
+}

apps/web/src/pages/editing-planner/components/timeline/ClipCard.tsx

@@ -0,0 +1,155 @@
+import React from "react"
+import type { ClipData } from "../../types"
+import { TRANSITION_OPTIONS } from "@/api/template-editor"
+import { CLIP_TYPE_ICONS, CLIP_TYPE_LABELS, MIN_CLIP_WIDTH } from "../../constants/timeline"
+
+interface ClipCardProps {
+  clip: ClipData
+  idx: number
+  isSelected: boolean
+  isDragging: boolean
+  isDragOver: boolean
+  isHovered: boolean
+  pps: number
+  trimDragActive: boolean
+  showTrimHandles: boolean
+  onDragStart: (e: React.DragEvent, idx: number) => void
+  onDragOver: (e: React.DragEvent, idx: number) => void
+  onDragEnd: () => void
+  onDrop: (e: React.DragEvent, idx: number) => void
+  onSelect: (clipId: string) => void
+  onContextMenu: (e: React.MouseEvent, clipId: string) => void
+  onMouseEnter: () => void
+  onMouseLeave: () => void
+  onTrimHandleMouseDown: (e: React.MouseEvent, clipId: string, direction: "left" | "right") => void
+  onRemove: (clipId: string) => void
+}
+
+export const ClipCard: React.FC<ClipCardProps> = ({
+  clip,
+  idx,
+  isSelected,
+  isDragging,
+  isDragOver,
+  isHovered,
+  pps,
+  trimDragActive,
+  showTrimHandles,
+  onDragStart,
+  onDragOver,
+  onDragEnd,
+  onDrop,
+  onSelect,
+  onContextMenu,
+  onMouseEnter,
+  onMouseLeave,
+  onTrimHandleMouseDown,
+  onRemove,
+}) => {
+  /* 转场指示器 */
+  const trans = clip.transition
+  const showTransition = idx > 0 && trans && trans.type !== "none"
+  const transOpt = showTransition
+    ? TRANSITION_OPTIONS.find((o) => o.value === trans!.type)
+    : undefined
+
+  /* 速度徽章 */
+  const speed = clip.speed
+  const showSpeed = speed && Math.abs(speed.rate - 1.0) > 0.01
+
+  /* 裁剪状态 */
+  const hasTrim = !!clip.trim_config
+
+  return (
+    <React.Fragment key={clip.id}>
+      {/* 转场指示器 */}
+      {showTransition && transOpt && (
+        <div
+          className="ep-transition-indicator"
+          title={`${transOpt.label} · ${trans!.duration.toFixed(1)}s`}
+        >
+          <span className="ep-trans-icon">{transOpt.icon}</span>
+          <span className="ep-trans-duration">{trans!.duration.toFixed(1)}s</span>
+        </div>
+      )}
+
+      <div
+        className={`ep-clip-card ${isSelected ? "selected" : ""} ${isDragging ? "dragging" : ""} ${isDragOver ? "drag-over" : ""} ${hasTrim ? "trimmed" : ""}`}
+        style={{ width: Math.max(clip.duration * pps, MIN_CLIP_WIDTH) }}
+        draggable={!trimDragActive}
+        onDragStart={(e) => onDragStart(e, idx)}
+        onDragOver={(e) => onDragOver(e, idx)}
+        onDragEnd={onDragEnd}
+        onDrop={(e) => onDrop(e, idx)}
+        onClick={() => onSelect(clip.id)}
+        onContextMenu={(e) => onContextMenu(e, clip.id)}
+        onMouseEnter={onMouseEnter}
+        onMouseLeave={onMouseLeave}
+      >
+        {/* 左裁剪手柄 */}
+        {isHovered && showTrimHandles && (
+          <div
+            className="ep-trim-handle ep-trim-handle-left"
+            onMouseDown={(e) => onTrimHandleMouseDown(e, clip.id, "left")}
+            title="拖动调整入点"
+          >
+            <div className="ep-trim-handle-line" />
+          </div>
+        )}
+
+        {/* 类型图标 */}
+        <div className="ep-clip-thumbnail">{CLIP_TYPE_ICONS[clip.type] || "🎬"}</div>
+
+        {/* 片段信息 */}
+        <div className="ep-clip-info">
+          <span className="ep-clip-name">
+            {CLIP_TYPE_LABELS[clip.type] || "片段"} {idx + 1}
+          </span>
+          <span className="ep-clip-duration">
+            {clip.duration}s
+            {hasTrim && (
+              <span className="ep-trim-indicator" title="已裁剪">
+                ✂
+              </span>
+            )}
+          </span>
+        </div>
+
+        {/* 速度徽章 */}
+        {showSpeed && <span className="ep-speed-badge">{speed!.rate.toFixed(1)}x</span>}
+
+        {/* 裁剪徽章 */}
+        {hasTrim && (
+          <span
+            className="ep-trim-badge"
+            title={`入点 ${clip.trim_config!.start_time.toFixed(1)}s / 出点 ${clip.trim_config!.end_time.toFixed(1)}s`}
+          >
+            ✂
+          </span>
+        )}
+
+        {/* 右裁剪手柄 */}
+        {isHovered && showTrimHandles && (
+          <div
+            className="ep-trim-handle ep-trim-handle-right"
+            onMouseDown={(e) => onTrimHandleMouseDown(e, clip.id, "right")}
+            title="拖动调整出点"
+          >
+            <div className="ep-trim-handle-line" />
+          </div>
+        )}
+
+        {/* 删除按钮 */}
+        <button
+          className="ep-clip-remove"
+          onClick={(e) => {
+            e.stopPropagation()
+            onRemove(clip.id)
+          }}
+        >
+          ✕
+        </button>
+      </div>
+    </React.Fragment>
+  )
+}

apps/web/src/pages/editing-planner/components/timeline/ContextMenu.tsx

@@ -0,0 +1,49 @@
+import React from "react"
+
+interface ContextMenuProps {
+  x: number
+  y: number
+  menuRef: React.RefObject<HTMLDivElement>
+  hasTrim: boolean
+  onSplit: () => void
+  onResetTrim: () => void
+  onDelete: () => void
+}
+
+export const ContextMenu: React.FC<ContextMenuProps> = ({
+  x,
+  y,
+  menuRef,
+  hasTrim,
+  onSplit,
+  onResetTrim,
+  onDelete,
+}) => {
+  return (
+    <div
+      ref={menuRef}
+      className="ep-context-menu"
+      style={{
+        position: "fixed",
+        left: x,
+        top: y,
+      }}
+    >
+      <div className="ep-context-menu-item" onClick={onSplit}>
+        <span className="ep-context-menu-icon">✂️</span>
+        <span>分割片段</span>
+      </div>
+      {hasTrim && (
+        <div className="ep-context-menu-item" onClick={onResetTrim}>
+          <span className="ep-context-menu-icon">↩️</span>
+          <span>恢复原始长度</span>
+        </div>
+      )}
+      <div className="ep-context-menu-divider" />
+      <div className="ep-context-menu-item ep-context-menu-item-danger" onClick={onDelete}>
+        <span className="ep-context-menu-icon">🗑️</span>
+        <span>删除片段</span>
+      </div>
+    </div>
+  )
+}

apps/web/src/pages/editing-planner/components/timeline/TimeRuler.tsx

@@ -0,0 +1,27 @@
+import React from "react"
+import { getRulerStep, MIN_TRACK_WIDTH } from "../../constants/timeline"
+import { generateRulerMarks } from "../../utils/timeline"
+
+interface TimeRulerProps {
+  totalDuration: number
+  pps: number
+  onClick: (e: React.MouseEvent<HTMLDivElement>) => void
+}
+
+export const TimeRuler: React.FC<TimeRulerProps> = ({ totalDuration, pps, onClick }) => {
+  const trackWidth = Math.max(totalDuration * pps, MIN_TRACK_WIDTH)
+  const step = getRulerStep(totalDuration)
+  const marks = generateRulerMarks(totalDuration, step)
+
+  return (
+    <div className="ep-time-ruler" onClick={onClick}>
+      <div className="ep-time-ruler-inner" style={{ width: trackWidth }}>
+        {marks.map((t) => (
+          <span key={t} className="ep-time-mark" style={{ left: `${t * pps}px` }}>
+            {t}s
+          </span>
+        ))}
+      </div>
+    </div>
+  )
+}

apps/web/src/pages/editing-planner/components/timeline/TrimPreview.tsx

@@ -0,0 +1,36 @@
+import React from "react"
+import { formatTrimTime } from "../../utils/timeline"
+
+interface TrimPreviewProps {
+  startTime: number
+  endTime: number
+  duration: number
+  x: number
+  y: number
+}
+
+export const TrimPreview: React.FC<TrimPreviewProps> = ({ startTime, endTime, duration, x, y }) => {
+  return (
+    <div
+      className="ep-trim-preview"
+      style={{
+        position: "fixed",
+        left: x + 12,
+        top: y - 40,
+      }}
+    >
+      <div className="ep-trim-preview-row">
+        <span className="ep-trim-preview-label">入点</span>
+        <span className="ep-trim-preview-value">{formatTrimTime(startTime)}</span>
+      </div>
+      <div className="ep-trim-preview-row">
+        <span className="ep-trim-preview-label">出点</span>
+        <span className="ep-trim-preview-value">{formatTrimTime(endTime)}</span>
+      </div>
+      <div className="ep-trim-preview-row ep-trim-preview-duration">
+        <span className="ep-trim-preview-label">时长</span>
+        <span className="ep-trim-preview-value">{formatTrimTime(duration)}</span>
+      </div>
+    </div>
+  )
+}

apps/web/src/pages/editing-planner/components/tts/TtsSlider.tsx

@@ -0,0 +1,62 @@
+/**
+ * TTS 滑块组件（语速/语调/音量）
+ */
+import React from "react"
+import { Slider } from "antd"
+
+interface TtsSliderProps {
+  label: string
+  value: number
+  min: number
+  max: number
+  step: number
+  unit?: string
+  onChange: (val: number) => void
+  marks?: string[]
+  tooltipFormatter?: (v: number) => string
+}
+
+const TtsSlider: React.FC<TtsSliderProps> = ({
+  label,
+  value,
+  min,
+  max,
+  step,
+  unit = "",
+  onChange,
+  marks,
+  tooltipFormatter,
+}) => {
+  const displayValue =
+    unit === "x"
+      ? `${value.toFixed(2)}x`
+      : label === "语调"
+        ? `${value > 0 ? "+" : ""}${value} 半音`
+        : `${value}${unit}`
+
+  return (
+    <div className="tts-slider-section">
+      <div className="tts-slider-header">
+        <span className="tts-slider-label">{label}</span>
+        <span className="tts-slider-value">{displayValue}</span>
+      </div>
+      <Slider
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        onChange={(v) => onChange(v as number)}
+        tooltip={tooltipFormatter ? { formatter: (v) => tooltipFormatter(v as number) } : undefined}
+      />
+      {marks && (
+        <div className="tts-slider-marks">
+          {marks.map((m, i) => (
+            <span key={i}>{m}</span>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default TtsSlider

apps/web/src/pages/editing-planner/components/tts/VoiceSelector.tsx

@@ -0,0 +1,50 @@
+/**
+ * TTS 音色选择组件
+ */
+import React from "react"
+import type { TTSVoice } from "@/api/tts"
+import { VOICE_CATEGORY_MAP } from "../../constants/tts"
+
+interface VoiceSelectorProps {
+  voices: TTSVoice[]
+  voicesLoading: boolean
+  selectedVoiceId: string
+  onVoiceSelect: (voiceId: string) => void
+}
+
+const VoiceSelector: React.FC<VoiceSelectorProps> = ({
+  voices,
+  voicesLoading,
+  selectedVoiceId,
+  onVoiceSelect,
+}) => {
+  const voiceCategories = Object.entries(VOICE_CATEGORY_MAP)
+
+  return (
+    <div className="tts-voice-section">
+      <div className="tts-voice-label">
+        选择音色
+        {voicesLoading && <span className="tts-voice-loading">加载中...</span>}
+      </div>
+      <div className="tts-voice-grid">
+        {voiceCategories.map(([cat, info]) => {
+          const voice = voices.find((v) => v.category === cat)
+          const isSelected = voice && selectedVoiceId === voice.id
+          return (
+            <button
+              key={cat}
+              className={`tts-voice-card${isSelected ? " active" : ""}`}
+              onClick={() => voice && onVoiceSelect(voice.id)}
+              disabled={!voice || voicesLoading}
+            >
+              <span className="tts-voice-card-icon">{info.icon}</span>
+              <span className="tts-voice-card-name">{voice?.name || info.label}</span>
+            </button>
+          )
+        })}
+      </div>
+    </div>
+  )
+}
+
+export default VoiceSelector

apps/web/src/pages/editing-planner/components/watermark/ImageWatermarkSection.tsx

@@ -0,0 +1,78 @@
+/**
+ * 图片水印配置组件
+ */
+import React from "react"
+
+interface ImageWatermarkSectionProps {
+  imageUrl: string
+  localImageUrl: string
+  width: number | undefined
+  height: number | undefined
+  onImageUrlChange: (url: string) => void
+  onWidthChange: (val: number) => void
+  onHeightChange: (val: number) => void
+}
+
+const ImageWatermarkSection: React.FC<ImageWatermarkSectionProps> = ({
+  imageUrl,
+  localImageUrl,
+  width,
+  height,
+  onImageUrlChange,
+  onWidthChange,
+  onHeightChange,
+}) => {
+  const displayUrl = localImageUrl || imageUrl || ""
+
+  return (
+    <div className="wp-section">
+      <div className="wp-field">
+        <label className="wp-field-label">水印图片 URL</label>
+        <input
+          className="wp-input"
+          type="text"
+          placeholder="https://example.com/logo.png"
+          value={displayUrl}
+          onChange={(e) => onImageUrlChange(e.target.value)}
+        />
+        {displayUrl && (
+          <div className="wp-image-preview">
+            <img
+              src={displayUrl}
+              alt="水印预览"
+              onError={(e) => {
+                ;(e.target as HTMLImageElement).style.display = "none"
+              }}
+            />
+          </div>
+        )}
+      </div>
+
+      <div className="wp-field">
+        <label className="wp-field-label">宽度（像素，0 表示自适应）</label>
+        <input
+          className="wp-input"
+          type="number"
+          min={0}
+          max={2000}
+          value={width ?? 0}
+          onChange={(e) => onWidthChange(Number(e.target.value))}
+        />
+      </div>
+
+      <div className="wp-field">
+        <label className="wp-field-label">高度（像素，0 表示自适应）</label>
+        <input
+          className="wp-input"
+          type="number"
+          min={0}
+          max={2000}
+          value={height ?? 0}
+          onChange={(e) => onHeightChange(Number(e.target.value))}
+        />
+      </div>
+    </div>
+  )
+}
+
+export default ImageWatermarkSection

apps/web/src/pages/editing-planner/components/watermark/ScrollWatermarkSection.tsx

@@ -0,0 +1,107 @@
+/**
+ * 滚动水印配置组件
+ */
+import React from "react"
+import type { ScrollDirection } from "../../types"
+import { SCROLL_DIRECTION_OPTIONS } from "../../constants/watermark"
+
+interface ScrollWatermarkSectionProps {
+  text: string | undefined
+  scrollDirection: ScrollDirection | undefined
+  scrollSpeed: number | undefined
+  fontSize: number | undefined
+  color: string | undefined
+  onTextChange: (text: string) => void
+  onScrollDirectionChange: (dir: ScrollDirection) => void
+  onScrollSpeedChange: (speed: number) => void
+  onFontSizeChange: (size: number) => void
+  onColorChange: (color: string) => void
+}
+
+const ScrollWatermarkSection: React.FC<ScrollWatermarkSectionProps> = ({
+  text,
+  scrollDirection,
+  scrollSpeed,
+  fontSize,
+  color,
+  onTextChange,
+  onScrollDirectionChange,
+  onScrollSpeedChange,
+  onFontSizeChange,
+  onColorChange,
+}) => {
+  return (
+    <div className="wp-section">
+      <div className="wp-field">
+        <label className="wp-field-label">滚动文字</label>
+        <textarea
+          className="wp-textarea"
+          placeholder="输入滚动水印文字"
+          rows={2}
+          value={text ?? ""}
+          onChange={(e) => onTextChange(e.target.value)}
+        />
+      </div>
+
+      <div className="wp-field">
+        <label className="wp-field-label">滚动方向</label>
+        <select
+          className="wp-select"
+          value={scrollDirection ?? "horizontal"}
+          onChange={(e) => onScrollDirectionChange(e.target.value as ScrollDirection)}
+        >
+          {SCROLL_DIRECTION_OPTIONS.map((opt) => (
+            <option key={opt.value} value={opt.value}>
+              {opt.label}
+            </option>
+          ))}
+        </select>
+      </div>
+
+      <div className="wp-field">
+        <label className="wp-field-label">滚动速度</label>
+        <div className="wp-slider-row">
+          <input
+            className="wp-slider"
+            type="range"
+            min={10}
+            max={200}
+            value={scrollSpeed ?? 50}
+            onChange={(e) => onScrollSpeedChange(Number(e.target.value))}
+          />
+          <span className="wp-slider-value">{scrollSpeed ?? 50}px/s</span>
+        </div>
+      </div>
+
+      <div className="wp-field">
+        <label className="wp-field-label">字号</label>
+        <div className="wp-slider-row">
+          <input
+            className="wp-slider"
+            type="range"
+            min={12}
+            max={72}
+            value={fontSize ?? 24}
+            onChange={(e) => onFontSizeChange(Number(e.target.value))}
+          />
+          <span className="wp-slider-value">{fontSize ?? 24}px</span>
+        </div>
+      </div>
+
+      <div className="wp-field">
+        <label className="wp-field-label">文字颜色</label>
+        <div className="wp-color-row">
+          <input
+            className="wp-color-input"
+            type="color"
+            value={color ?? "#ffffff"}
+            onChange={(e) => onColorChange(e.target.value)}
+          />
+          <span className="wp-color-value">{color ?? "#ffffff"}</span>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default ScrollWatermarkSection

apps/web/src/pages/editing-planner/components/watermark/TextWatermarkSection.tsx

@@ -0,0 +1,67 @@
+/**
+ * 文字水印配置组件
+ */
+import React from "react"
+
+interface TextWatermarkSectionProps {
+  text: string | undefined
+  fontSize: number | undefined
+  color: string | undefined
+  onTextChange: (text: string) => void
+  onFontSizeChange: (size: number) => void
+  onColorChange: (color: string) => void
+}
+
+const TextWatermarkSection: React.FC<TextWatermarkSectionProps> = ({
+  text,
+  fontSize,
+  color,
+  onTextChange,
+  onFontSizeChange,
+  onColorChange,
+}) => {
+  return (
+    <div className="wp-section">
+      <div className="wp-field">
+        <label className="wp-field-label">水印文字</label>
+        <textarea
+          className="wp-textarea"
+          placeholder="输入水印文字内容"
+          rows={3}
+          value={text ?? ""}
+          onChange={(e) => onTextChange(e.target.value)}
+        />
+      </div>
+
+      <div className="wp-field">
+        <label className="wp-field-label">字号</label>
+        <div className="wp-slider-row">
+          <input
+            className="wp-slider"
+            type="range"
+            min={12}
+            max={72}
+            value={fontSize ?? 24}
+            onChange={(e) => onFontSizeChange(Number(e.target.value))}
+          />
+          <span className="wp-slider-value">{fontSize ?? 24}px</span>
+        </div>
+      </div>
+
+      <div className="wp-field">
+        <label className="wp-field-label">文字颜色</label>
+        <div className="wp-color-row">
+          <input
+            className="wp-color-input"
+            type="color"
+            value={color ?? "#ffffff"}
+            onChange={(e) => onColorChange(e.target.value)}
+          />
+          <span className="wp-color-value">{color ?? "#ffffff"}</span>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default TextWatermarkSection

apps/web/src/pages/editing-planner/components/watermark/WatermarkCommonSection.tsx

@@ -0,0 +1,60 @@
+/**
+ * 水印通用设置组件（位置 + 透明度）
+ */
+import React from "react"
+import type { WatermarkPosition } from "../../types"
+import { POSITION_OPTIONS } from "../../constants/watermark"
+
+interface WatermarkCommonSectionProps {
+  position: WatermarkPosition
+  opacity: number
+  onPositionChange: (pos: WatermarkPosition) => void
+  onOpacityChange: (opacity: number) => void
+}
+
+const WatermarkCommonSection: React.FC<WatermarkCommonSectionProps> = ({
+  position,
+  opacity,
+  onPositionChange,
+  onOpacityChange,
+}) => {
+  return (
+    <div className="wp-section wp-common-section">
+      <div className="wp-section-divider" />
+      <div className="wp-common-title">通用设置</div>
+
+      <div className="wp-field">
+        <label className="wp-field-label">水印位置</label>
+        <select
+          className="wp-select"
+          value={position}
+          onChange={(e) => onPositionChange(e.target.value as WatermarkPosition)}
+        >
+          {POSITION_OPTIONS.map((opt) => (
+            <option key={opt.value} value={opt.value}>
+              {opt.label}
+            </option>
+          ))}
+        </select>
+      </div>
+
+      <div className="wp-field">
+        <label className="wp-field-label">不透明度</label>
+        <div className="wp-slider-row">
+          <input
+            className="wp-slider"
+            type="range"
+            min={0}
+            max={1}
+            step={0.05}
+            value={opacity}
+            onChange={(e) => onOpacityChange(Number(e.target.value))}
+          />
+          <span className="wp-slider-value">{Math.round(opacity * 100)}%</span>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default WatermarkCommonSection

apps/web/src/pages/editing-planner/components/watermark/WatermarkTypeTabs.tsx

@@ -0,0 +1,30 @@
+/**
+ * 水印类型 Tab 组件
+ */
+import React from "react"
+import type { WatermarkType } from "../../types"
+import { WATERMARK_TABS } from "../../constants/watermark"
+
+interface WatermarkTypeTabsProps {
+  activeTab: WatermarkType
+  onTypeChange: (type: WatermarkType) => void
+}
+
+const WatermarkTypeTabs: React.FC<WatermarkTypeTabsProps> = ({ activeTab, onTypeChange }) => {
+  return (
+    <div className="wp-tabs">
+      {WATERMARK_TABS.map((tab) => (
+        <button
+          key={tab.key}
+          className={`wp-tab${activeTab === tab.key ? " active" : ""}`}
+          onClick={() => onTypeChange(tab.key)}
+        >
+          <span className="wp-tab-icon">{tab.icon}</span>
+          <span className="wp-tab-label">{tab.label}</span>
+        </button>
+      ))}
+    </div>
+  )
+}
+
+export default WatermarkTypeTabs

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

@@ -0,0 +1,34 @@
+/**
+ * ClipPropertiesPanel 常量定义
+ */
+import type { ClipType } from "@/pages/editing-planner/types"
+
+export const POSITION_OPTIONS = [
+  { value: "top", label: "顶部" },
+  { value: "center", label: "居中" },
+  { value: "bottom", label: "底部" },
+]
+
+export const FONT_OPTIONS = [
+  "思源黑体",
+  "思源宋体",
+  "苹方",
+  "PingFang",
+  "微软雅黑",
+  "楷体",
+  "华康俪金黑",
+]
+
+export const ANIMATION_OPTIONS = [
+  { value: "none", label: "无" },
+  { value: "fade", label: "淡入淡出" },
+  { value: "slide", label: "滑动" },
+  { value: "typewriter", label: "打字机" },
+]
+
+/** 片段类型图标/标签 */
+export const CLIP_TYPE_ICONS: Record<ClipType, string> = { voice: "🎙️", pip: "🖼️" }
+export const CLIP_TYPE_LABELS: Record<ClipType, string> = {
+  voice: "口播",
+  pip: "混剪",
+}

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

@@ -0,0 +1,42 @@
+/**
+ * FilterPanel 相关常量
+ */
+import type { FilterPreset } from "../types"
+
+/** 所有预设列表 */
+export const PRESET_LIST: FilterPreset[] = [
+  "none",
+  "original",
+  "fresh",
+  "warm",
+  "cool",
+  "vintage",
+  "cinema",
+  "bw",
+  "sunshine",
+  "film",
+]
+
+/** 预设对应的示例渐变色（用于视觉预览） */
+export const PRESET_GRADIENTS: Record<FilterPreset, string> = {
+  none: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
+  original: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
+  fresh: "linear-gradient(135deg, #a8edea 0%, #fed6e3 100%)",
+  warm: "linear-gradient(135deg, #f093fb 0%, #f5576c 100%)",
+  cool: "linear-gradient(135deg, #4facfe 0%, #00f2fe 100%)",
+  vintage: "linear-gradient(135deg, #c79081 0%, #dfa579 100%)",
+  cinema: "linear-gradient(135deg, #2c3e50 0%, #4ca1af 100%)",
+  bw: "linear-gradient(135deg, #434343 0%, #000000 100%)",
+  sunshine: "linear-gradient(135deg, #f6d365 0%, #fda085 100%)",
+  film: "linear-gradient(135deg, #8e9eab 0%, #eef2f3 100%)",
+}
+
+/** 手动调节项配置 */
+export const MANUAL_ADJUST_ITEMS = [
+  { key: "brightness", label: "亮度", min: -100, max: 100 },
+  { key: "contrast", label: "对比度", min: -100, max: 100 },
+  { key: "saturation", label: "饱和度", min: -100, max: 100 },
+  { key: "temperature", label: "色温", min: -100, max: 100 },
+  { key: "tint", label: "色调", min: -100, max: 100 },
+  { key: "sharpness", label: "锐度", min: 0, max: 100 },
+] as const

apps/web/src/pages/editing-planner/constants/introOutro.ts

@@ -0,0 +1,10 @@
+/**
+ * IntroOutroPanel 相关常量
+ */
+import type { IntroOutroKind } from "../types"
+
+export const KIND_OPTIONS: { value: IntroOutroKind; label: string; icon: string }[] = [
+  { value: "none", label: "无", icon: "🚫" },
+  { value: "video", label: "视频", icon: "🎬" },
+  { value: "image", label: "图片", icon: "🖼️" },
+]

apps/web/src/pages/editing-planner/constants/pipConfig.ts

@@ -0,0 +1,55 @@
+/**
+ * PipConfigPanel 常量定义
+ */
+import type { PipGridPosition, PipAnimType, PipSlideDirection } from "@/pages/editing-planner/types"
+
+/** 九宫格位置 → 百分比坐标映射 */
+export const GRID_POSITION_MAP: Record<PipGridPosition, { x: number; y: number }> = {
+  top_left: { x: 5, y: 5 },
+  top_center: { x: 37.5, y: 5 },
+  top_right: { x: 70, y: 5 },
+  center_left: { x: 5, y: 37.5 },
+  center: { x: 37.5, y: 37.5 },
+  center_right: { x: 70, y: 37.5 },
+  bottom_left: { x: 5, y: 70 },
+  bottom_center: { x: 37.5, y: 70 },
+  bottom_right: { x: 70, y: 70 },
+}
+
+/** 九宫格位置选项 */
+export const GRID_POSITIONS: PipGridPosition[] = [
+  "top_left",
+  "top_center",
+  "top_right",
+  "center_left",
+  "center",
+  "center_right",
+  "bottom_left",
+  "bottom_center",
+  "bottom_right",
+]
+
+/** 入场动画选项 */
+export const ANIM_OPTIONS: { value: PipAnimType; label: string }[] = [
+  { value: "none", label: "无" },
+  { value: "fade_in", label: "淡入" },
+  { value: "slide_in", label: "滑入" },
+]
+
+/** 滑入方向选项 */
+export const SLIDE_DIR_OPTIONS: { value: PipSlideDirection; label: string }[] = [
+  { value: "left", label: "← 左" },
+  { value: "right", label: "→ 右" },
+  { value: "up", label: "↑ 上" },
+  { value: "down", label: "↓ 下" },
+]
+
+/** 预览图层颜色池 */
+export const LAYER_COLORS = [
+  "rgba(22,119,255,0.5)",
+  "rgba(82,196,26,0.5)",
+  "rgba(250,173,20,0.5)",
+  "rgba(255,77,79,0.5)",
+  "rgba(114,46,209,0.5)",
+  "rgba(19,194,194,0.5)",
+]

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

@@ -0,0 +1,64 @@
+/**
+ * StickerPanel 常量定义
+ */
+import type { TextStickerPreset } from "@/pages/editing-planner/types"
+import { TEXT_STICKER_PRESET_LABELS } from "@/pages/editing-planner/types"
+
+export { TEXT_STICKER_PRESET_LABELS }
+
+/** 常用 emoji 素材 */
+export const EMOJI_LIST = [
+  "😀",
+  "😂",
+  "🥰",
+  "😎",
+  "🤩",
+  "😱",
+  "🤔",
+  "😴",
+  "🥳",
+  "😍",
+  "❤️",
+  "🔥",
+  "⭐",
+  "✨",
+  "💯",
+  "👍",
+  "👏",
+  "🎉",
+  "🎵",
+  "💪",
+  "📌",
+  "💡",
+  "🎯",
+  "✅",
+  "❌",
+  "⬆️",
+  "⬇️",
+  "➡️",
+  "⭕",
+  "🔔",
+]
+
+/** 贴纸类型 Tab */
+export const STICKER_TYPE_TABS = [
+  { value: "emoji" as const, label: "表情贴纸" },
+  { value: "image" as const, label: "图片贴纸" },
+  { value: "text" as const, label: "文字花字" },
+]
+
+/** 文字花字预设对应的 CSS 样式预览 */
+export const TEXT_PRESET_STYLES: Record<TextStickerPreset, React.CSSProperties> = {
+  normal: { color: "#fff", textShadow: "none" },
+  highlight: { color: "#FFD700", textShadow: "0 0 8px rgba(255,215,0,0.6)" },
+  bubble: { color: "#fff", background: "rgba(0,0,0,0.5)", borderRadius: 8 },
+  neon: { color: "#0ff", textShadow: "0 0 6px #0ff, 0 0 12px #0ff" },
+  shadow: { color: "#fff", textShadow: "2px 2px 4px rgba(0,0,0,0.8)" },
+  outline: { color: "#fff", WebkitTextStroke: "1px #000" },
+  gradient: {
+    color: "transparent",
+    background: "linear-gradient(90deg,#f093fb,#f5576c)",
+    WebkitBackgroundClip: "text",
+  },
+  handwrite: { color: "#333", fontStyle: "italic", fontFamily: "cursive" },
+}

apps/web/src/pages/editing-planner/constants/subtitleStyle.ts

@@ -0,0 +1,30 @@
+/**
+ * SubtitleStylePanel 相关常量
+ */
+export const POSITION_OPTIONS = [
+  { value: "top", label: "顶部" },
+  { value: "center", label: "居中" },
+  { value: "bottom", label: "底部" },
+]
+
+export const FONT_OPTIONS = [
+  "思源黑体",
+  "思源宋体",
+  "苹方",
+  "PingFang",
+  "微软雅黑",
+  "楷体",
+  "华康俪金黑",
+]
+
+export const ANIMATION_OPTIONS = [
+  { value: "none", label: "无" },
+  { value: "fade", label: "淡入淡出" },
+  { value: "slide", label: "滑动" },
+  { value: "typewriter", label: "打字机" },
+]
+
+export const ASR_LANGUAGE_OPTIONS = [
+  { value: "zh", label: "中文" },
+  { value: "en", label: "English" },
+]

apps/web/src/pages/editing-planner/constants/timeline.ts

@@ -0,0 +1,56 @@
+import type { ClipType } from "../types"
+
+/** 片段类型图标 */
+export const CLIP_TYPE_ICONS: Record<ClipType, string> = {
+  voice: "🎙️",
+  pip: "🖼️",
+}
+
+/** 片段类型标签 */
+export const CLIP_TYPE_LABELS: Record<ClipType, string> = {
+  voice: "口播",
+  pip: "混剪",
+}
+
+/** 默认缩放：每秒像素数 */
+export const DEFAULT_PIXELS_PER_SECOND = 40
+
+/** 最小缩放 */
+export const MIN_PIXELS_PER_SECOND = 10
+
+/** 最大缩放 */
+export const MAX_PIXELS_PER_SECOND = 120
+
+/** 缩放步长 */
+export const ZOOM_STEP = 10
+
+/** 片段卡片最小宽度（px） */
+export const MIN_CLIP_WIDTH = 60
+
+/** 添加面板宽度（px） */
+export const ADD_PICKER_WIDTH = 240
+
+/** 轨道间距（px） */
+export const TRACK_GAP = 6
+
+/** 最小裁剪时长（秒） */
+export const MIN_TRIM_DURATION = 1
+
+/** 默认添加时长（秒） */
+export const DEFAULT_ADD_DURATION = 5
+
+/** 最小添加时长（秒） */
+export const MIN_ADD_DURATION = 1
+
+/** 最大添加时长（秒） */
+export const MAX_ADD_DURATION = 120
+
+/** 轨道最小宽度（px） */
+export const MIN_TRACK_WIDTH = 300
+
+/** 时间标尺刻度计算：根据总时长返回刻度步长（秒） */
+export const getRulerStep = (totalDuration: number): number => {
+  if (totalDuration <= 30) return 5
+  if (totalDuration <= 60) return 10
+  return 15
+}

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

@@ -0,0 +1,19 @@
+/**
+ * TtsPanel 相关常量
+ */
+import type { TtsMode } from "../types"
+
+export const VOICE_CATEGORY_MAP: Record<string, { icon: string; label: string }> = {
+  male: { icon: "👨", label: "男声" },
+  female: { icon: "👩", label: "女声" },
+  young: { icon: "🧑", label: "少年" },
+  service: { icon: "🎧", label: "客服" },
+  news: { icon: "📰", label: "新闻" },
+  emotion: { icon: "🎭", label: "情感" },
+}
+
+export const TTS_MODE_OPTIONS: { mode: TtsMode; icon: string; label: string }[] = [
+  { mode: "none", icon: "🔇", label: "无配音" },
+  { mode: "upload", icon: "📁", label: "上传配音" },
+  { mode: "tts", icon: "🤖", label: "TTS 合成" },
+]

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

@@ -0,0 +1,25 @@
+/**
+ * WatermarkPanel 相关常量
+ */
+import type { WatermarkType, WatermarkPosition, ScrollDirection } from "../types"
+
+export const WATERMARK_TABS: { key: WatermarkType; label: string; icon: string }[] = [
+  { key: "none", label: "无水印", icon: "🚫" },
+  { key: "image", label: "图片水印", icon: "🖼️" },
+  { key: "text", label: "文字水印", icon: "📝" },
+  { key: "scroll", label: "滚动水印", icon: "📜" },
+]
+
+export const POSITION_OPTIONS: { value: WatermarkPosition; label: string }[] = [
+  { value: "top_left", label: "左上角" },
+  { value: "top_right", label: "右上角" },
+  { value: "bottom_left", label: "左下角" },
+  { value: "bottom_right", label: "右下角" },
+  { value: "center", label: "居中" },
+]
+
+export const SCROLL_DIRECTION_OPTIONS: { value: ScrollDirection; label: string }[] = [
+  { value: "horizontal", label: "水平滚动" },
+  { value: "vertical", label: "垂直滚动" },
+  { value: "diagonal", label: "对角滚动" },
+]

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

@@ -0,0 +1,129 @@
+/**
+ * 混剪图层管理 Hook
+ */
+import { useState, useCallback, useMemo } from "react"
+import type { PipConfig, PipLayer, PipGridPosition } from "@/pages/editing-planner/types"
+import { DEFAULT_PIP_LAYER, DEFAULT_PIP_CONFIG } from "@/pages/editing-planner/types"
+import { GRID_POSITION_MAP } from "@/pages/editing-planner/constants/pipConfig"
+
+let layerIdCounter = 0
+const genLayerId = () => `pip_layer_${Date.now()}_${++layerIdCounter}`
+
+interface UsePipLayersOptions {
+  config: PipConfig
+  onChange: (config: PipConfig) => void
+}
+
+export const usePipLayers = ({ config, onChange }: UsePipLayersOptions) => {
+  const [selectedId, setSelectedId] = useState<string>("")
+
+  const selectedLayer = useMemo(
+    () => config.layers.find((l) => l.id === selectedId) ?? null,
+    [config.layers, selectedId],
+  )
+
+  /* ── 添加图层 ── */
+  const handleAddLayer = useCallback(() => {
+    const newLayer: PipLayer = {
+      ...DEFAULT_PIP_LAYER,
+      id: genLayerId(),
+      name: `图层 ${config.layers.length + 1}`,
+      z_index: config.layers.length + 1,
+    }
+    onChange({
+      ...config,
+      layers: [...config.layers, newLayer],
+    })
+    setSelectedId(newLayer.id)
+  }, [config, onChange])
+
+  /* ── 删除图层 ── */
+  const handleDeleteLayer = useCallback(
+    (id: string) => {
+      const newLayers = config.layers.filter((l) => l.id !== id)
+      onChange({ ...config, layers: newLayers })
+      if (selectedId === id) {
+        setSelectedId(newLayers.length > 0 ? newLayers[0].id : "")
+      }
+    },
+    [config, onChange, selectedId],
+  )
+
+  /* ── 更新图层 ── */
+  const updateLayer = useCallback(
+    (id: string, partial: Partial<PipLayer>) => {
+      onChange({
+        ...config,
+        layers: config.layers.map((l) => (l.id === id ? { ...l, ...partial } : l)),
+      })
+    },
+    [config, onChange],
+  )
+
+  /* ── 切换启用 ── */
+  const handleEnableToggle = useCallback(
+    (checked: boolean) => {
+      onChange({ ...config, enabled: checked })
+    },
+    [config, onChange],
+  )
+
+  /* ── 重置 ── */
+  const handleReset = useCallback(() => {
+    onChange({ ...DEFAULT_PIP_CONFIG })
+    setSelectedId("")
+  }, [onChange])
+
+  /* ── 九宫格点击 ── */
+  const handleGridClick = useCallback(
+    (pos: PipGridPosition) => {
+      if (!selectedLayer) return
+      const coords = GRID_POSITION_MAP[pos]
+      updateLayer(selectedLayer.id, {
+        grid_position: pos,
+        x: coords.x,
+        y: coords.y,
+      })
+    },
+    [selectedLayer, updateLayer],
+  )
+
+  /* ── 宽高比锁定 ── */
+  const handleWidthChange = useCallback(
+    (val: number) => {
+      if (!selectedLayer) return
+      const partial: Partial<PipLayer> = { width: val }
+      if (selectedLayer.aspect_lock) {
+        partial.height = val
+      }
+      updateLayer(selectedLayer.id, partial)
+    },
+    [selectedLayer, updateLayer],
+  )
+
+  const handleHeightChange = useCallback(
+    (val: number) => {
+      if (!selectedLayer) return
+      const partial: Partial<PipLayer> = { height: val }
+      if (selectedLayer.aspect_lock) {
+        partial.width = val
+      }
+      updateLayer(selectedLayer.id, partial)
+    },
+    [selectedLayer, updateLayer],
+  )
+
+  return {
+    selectedId,
+    setSelectedId,
+    selectedLayer,
+    handleAddLayer,
+    handleDeleteLayer,
+    updateLayer,
+    handleEnableToggle,
+    handleReset,
+    handleGridClick,
+    handleWidthChange,
+    handleHeightChange,
+  }
+}

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

@@ -0,0 +1,83 @@
+/**
+ * 贴纸项管理 Hook
+ */
+import { useState, useCallback } from "react"
+import type { StickerConfig, StickerItem, StickerType } from "@/pages/editing-planner/types"
+import { DEFAULT_STICKER_ITEM, DEFAULT_STICKER_CONFIG } from "@/pages/editing-planner/types"
+
+const genId = () => `sticker_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+
+interface UseStickerItemsOptions {
+  config: StickerConfig
+  onChange: (config: StickerConfig) => void
+  totalDuration: number
+}
+
+export const useStickerItems = ({ config, onChange, totalDuration }: UseStickerItemsOptions) => {
+  const [selectedId, setSelectedId] = useState<string | null>(null)
+  const [activeTab, setActiveTab] = useState<StickerType>("emoji")
+
+  const selectedSticker = config.items.find((s) => s.id === selectedId) ?? null
+
+  /** 更新单个贴纸 */
+  const updateItem = useCallback(
+    (id: string, partial: Partial<StickerItem>) => {
+      onChange({
+        ...config,
+        items: config.items.map((s) => (s.id === id ? { ...s, ...partial } : s)),
+      })
+    },
+    [config, onChange],
+  )
+
+  /** 添加贴纸 */
+  const addSticker = useCallback(
+    (type: StickerType, content: string) => {
+      const newItem: StickerItem = {
+        ...DEFAULT_STICKER_ITEM,
+        id: genId(),
+        type,
+        content,
+        duration: totalDuration > 0 ? totalDuration : 5,
+        z_index: config.items.length + 1,
+      }
+      onChange({
+        ...config,
+        enabled: true,
+        items: [...config.items, newItem],
+      })
+      setSelectedId(newItem.id)
+    },
+    [config, onChange, totalDuration],
+  )
+
+  /** 删除贴纸 */
+  const removeSticker = useCallback(
+    (id: string) => {
+      onChange({
+        ...config,
+        items: config.items.filter((s) => s.id !== id),
+      })
+      if (selectedId === id) setSelectedId(null)
+    },
+    [config, onChange, selectedId],
+  )
+
+  /** 重置所有 */
+  const handleReset = useCallback(() => {
+    onChange({ ...DEFAULT_STICKER_CONFIG, enabled: config.enabled })
+    setSelectedId(null)
+  }, [config.enabled, onChange])
+
+  return {
+    selectedId,
+    setSelectedId,
+    activeTab,
+    setActiveTab,
+    selectedSticker,
+    updateItem,
+    addSticker,
+    removeSticker,
+    handleReset,
+  }
+}

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

@@ -0,0 +1,152 @@
+/**
+ * TTS 配音 Hook
+ * 管理音色加载、试听、配置变更
+ */
+import { useState, useCallback, useEffect, useRef } from "react"
+import { message } from "antd"
+import type { TtsConfig, TtsMode } from "../types"
+import { DEFAULT_TTS_CONFIG } from "../types"
+import { getTtsVoices, previewTts, type TTSVoice } from "@/api/tts"
+
+interface UseTtsPanelOptions {
+  open: boolean
+  config: TtsConfig
+  onChange: (config: TtsConfig) => void
+  onClose: () => void
+}
+
+export const useTtsPanel = ({ open, config, onChange, onClose }: UseTtsPanelOptions) => {
+  /* ── 音色列表 ── */
+  const [voices, setVoices] = useState<TTSVoice[]>([])
+  const [voicesLoading, setVoicesLoading] = useState(false)
+
+  /* ── 试听状态 ── */
+  const [previewLoading, setPreviewLoading] = useState(false)
+  const audioRef = useRef<HTMLAudioElement | null>(null)
+
+  /* ── 加载音色列表 ── */
+  useEffect(() => {
+    if (!open) return
+    setVoicesLoading(true)
+    getTtsVoices()
+      .then((v) => setVoices(v))
+      .catch(() => message.error("加载音色列表失败"))
+      .finally(() => setVoicesLoading(false))
+  }, [open])
+
+  /* ── 切换配音模式 ── */
+  const handleModeChange = useCallback(
+    (mode: TtsMode) => {
+      onChange({ ...config, mode })
+    },
+    [config, onChange],
+  )
+
+  /* ── 文本输入 ── */
+  const handleTextChange = useCallback(
+    (text: string) => {
+      onChange({ ...config, text: text.slice(0, 5000) })
+    },
+    [config, onChange],
+  )
+
+  /* ── 选择音色 ── */
+  const handleVoiceSelect = useCallback(
+    (voiceId: string) => {
+      onChange({ ...config, voice_id: voiceId })
+    },
+    [config, onChange],
+  )
+
+  /* ── 语速 ── */
+  const handleSpeedChange = useCallback(
+    (speed: number) => {
+      onChange({ ...config, speed })
+    },
+    [config, onChange],
+  )
+
+  /* ── 语调 ── */
+  const handlePitchChange = useCallback(
+    (pitch: number) => {
+      onChange({ ...config, pitch })
+    },
+    [config, onChange],
+  )
+
+  /* ── 音量 ── */
+  const handleVolumeChange = useCallback(
+    (volume: number) => {
+      onChange({ ...config, volume })
+    },
+    [config, onChange],
+  )
+
+  /* ── 字幕联动 ── */
+  const handleSubtitleSyncToggle = useCallback(() => {
+    onChange({ ...config, subtitle_sync: !config.subtitle_sync })
+  }, [config, onChange])
+
+  /* ── 试听 ── */
+  const handlePreview = useCallback(async () => {
+    if (!config.text.trim()) {
+      message.warning("请先输入合成文本")
+      return
+    }
+    if (!config.voice_id) {
+      message.warning("请先选择音色")
+      return
+    }
+    setPreviewLoading(true)
+    try {
+      const res = await previewTts({
+        text: config.text.slice(0, 200),
+        voice_id: config.voice_id,
+        speed: config.speed,
+        pitch: config.pitch,
+      })
+      audioRef.current?.pause()
+      const audio = new Audio(res.audio_url)
+      audioRef.current = audio
+      audio.play().catch(() => message.error("播放失败"))
+      audio.onended = () => {
+        audioRef.current = null
+      }
+      message.success("试听播放中")
+    } catch {
+      message.error("试听生成失败")
+    } finally {
+      setPreviewLoading(false)
+    }
+  }, [config])
+
+  /* ── 重置 ── */
+  const handleReset = useCallback(() => {
+    onChange({ ...DEFAULT_TTS_CONFIG })
+  }, [onChange])
+
+  /* ── 关闭时停止音频 ── */
+  const handleClose = useCallback(() => {
+    audioRef.current?.pause()
+    audioRef.current = null
+    onClose()
+  }, [onClose])
+
+  return {
+    voices,
+    voicesLoading,
+    previewLoading,
+    handleModeChange,
+    handleTextChange,
+    handleVoiceSelect,
+    handleSpeedChange,
+    handlePitchChange,
+    handleVolumeChange,
+    handleSubtitleSyncToggle,
+    handlePreview,
+    handleReset,
+    handleClose,
+  }
+}
+
+export default useTtsPanel

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

@@ -0,0 +1,42 @@
+/**
+ * 配音试听 Hook
+ */
+import { useRef, useState, useCallback } from "react"
+import type { AssetItem } from "@/api/assets"
+
+export const useVoicePreview = () => {
+  const audioRef = useRef<HTMLAudioElement | null>(null)
+  const [previewingId, setPreviewingId] = useState<string | null>(null)
+
+  /** 试听配音素材 */
+  const handlePreviewVoice = useCallback(
+    (asset: AssetItem) => {
+      if (previewingId === asset.id) {
+        audioRef.current?.pause()
+        setPreviewingId(null)
+        return
+      }
+      audioRef.current?.pause()
+      const url = asset.file_url || (asset.metadata?.preview_url as string)
+      if (!url) return
+      const audio = new Audio(url)
+      audioRef.current = audio
+      audio.play().catch(() => {})
+      audio.onended = () => setPreviewingId(null)
+      setPreviewingId(asset.id)
+    },
+    [previewingId],
+  )
+
+  /** 停止试听 */
+  const stopPreview = useCallback(() => {
+    audioRef.current?.pause()
+    setPreviewingId(null)
+  }, [])
+
+  return {
+    previewingId,
+    handlePreviewVoice,
+    stopPreview,
+  }
+}

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

@@ -0,0 +1,126 @@
+/**
+ * 水印配置 Hook
+ * 管理水印类型切换、各项配置变更
+ */
+import { useState, useCallback } from "react"
+import type { WatermarkConfig, WatermarkType, WatermarkPosition, ScrollDirection } from "../types"
+import { DEFAULT_WATERMARK } from "../types"
+
+interface UseWatermarkConfigOptions {
+  config: WatermarkConfig
+  onChange: (config: WatermarkConfig) => void
+}
+
+export const useWatermarkConfig = ({ config, onChange }: UseWatermarkConfigOptions) => {
+  /* ── 图片上传预览 URL（本地预览用） ── */
+  const [localImageUrl, setLocalImageUrl] = useState<string>("")
+
+  /* ── 切换水印类型 ── */
+  const handleTypeChange = useCallback(
+    (type: WatermarkType) => {
+      setLocalImageUrl("")
+      onChange({ ...DEFAULT_WATERMARK, type })
+    },
+    [onChange],
+  )
+
+  /* ── 通用设置变更 ── */
+  const handlePositionChange = useCallback(
+    (position: WatermarkPosition) => {
+      onChange({ ...config, position })
+    },
+    [config, onChange],
+  )
+
+  const handleOpacityChange = useCallback(
+    (opacity: number) => {
+      onChange({ ...config, opacity })
+    },
+    [config, onChange],
+  )
+
+  /* ── 图片水印设置 ── */
+  const handleImageUrlChange = useCallback(
+    (url: string) => {
+      setLocalImageUrl(url)
+      onChange({ ...config, image_url: url })
+    },
+    [config, onChange],
+  )
+
+  const handleImageWidthChange = useCallback(
+    (width: number) => {
+      onChange({ ...config, width })
+    },
+    [config, onChange],
+  )
+
+  const handleImageHeightChange = useCallback(
+    (height: number) => {
+      onChange({ ...config, height })
+    },
+    [config, onChange],
+  )
+
+  /* ── 文字水印设置 ── */
+  const handleTextChange = useCallback(
+    (text: string) => {
+      onChange({ ...config, text })
+    },
+    [config, onChange],
+  )
+
+  const handleFontSizeChange = useCallback(
+    (font_size: number) => {
+      onChange({ ...config, font_size })
+    },
+    [config, onChange],
+  )
+
+  const handleColorChange = useCallback(
+    (color: string) => {
+      onChange({ ...config, color })
+    },
+    [config, onChange],
+  )
+
+  /* ── 滚动水印设置 ── */
+  const handleScrollDirectionChange = useCallback(
+    (scroll_direction: ScrollDirection) => {
+      onChange({ ...config, scroll_direction })
+    },
+    [config, onChange],
+  )
+
+  const handleScrollSpeedChange = useCallback(
+    (scroll_speed: number) => {
+      onChange({ ...config, scroll_speed })
+    },
+    [config, onChange],
+  )
+
+  /* ── 重置 ── */
+  const handleReset = useCallback(() => {
+    setLocalImageUrl("")
+    onChange({ ...DEFAULT_WATERMARK })
+  }, [onChange])
+
+  return {
+    localImageUrl,
+    activeTab: config.type,
+    handleTypeChange,
+    handlePositionChange,
+    handleOpacityChange,
+    handleImageUrlChange,
+    handleImageWidthChange,
+    handleImageHeightChange,
+    handleTextChange,
+    handleFontSizeChange,
+    handleColorChange,
+    handleScrollDirectionChange,
+    handleScrollSpeedChange,
+    handleReset,
+  }
+}
+
+export default useWatermarkConfig

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

@@ -0,0 +1,71 @@
+/**
+ * ClipPropertiesPanel 相关类型定义
+ */
+import type { ClipData } from "@/pages/editing-planner/types"
+import type { TemplateMode } from "@/api/editing-planner"
+import type { AssetItem } from "@/api/assets"
+
+export interface SubtitleSettings {
+  enabled: boolean
+  position: string
+  font: string
+  fontSize: number
+  fontColor: string
+  animation: string
+  mode?: string
+  stroke?: boolean
+  shadow?: boolean
+  asrLanguage?: string
+}
+
+export interface BgmSettings {
+  enabled: boolean
+  music_id: string
+  volume?: number
+  fade_in?: number
+  fade_out?: number
+  voice_dodge?: boolean
+}
+
+export interface ClipPropertiesPanelProps {
+  selectedClip: ClipData | null
+  subtitleSettings: SubtitleSettings
+  bgmSettings: BgmSettings
+  clipsCount: number
+  totalDuration: number
+  currentMode: TemplateMode
+  onSubtitleSettingsChange: (partial: Partial<SubtitleSettings>) => void
+  onBgmSettingsChange: (partial: Partial<BgmSettings>) => void
+  onClipUpdate: (clipId: string, data: Partial<ClipData>) => void
+  /** 打开 BGM 选择器 Drawer */
+  onOpenBgmDrawer?: () => void
+  /** 打开字幕样式配置 Drawer */
+  onOpenSubtitleDrawer?: () => void
+  /** 配音素材列表（从配音库 API 获取） */
+  voiceMaterials?: AssetItem[]
+  /** 配音素材加载中 */
+  voiceMaterialsLoading?: boolean
+  /** 刷新配音素材列表 */
+  onRefreshVoiceMaterials?: () => void
+  /** 为片段选择配音素材 */
+  onClipVoiceSelect?: (clipId: string, asset: AssetItem | null) => void
+  /** 打开转场特效选择器 Drawer */
+  onOpenTransitionDrawer?: (clipId: string) => void
+  /** 打开片段调速面板 Drawer */
+  onOpenSpeedDrawer?: (clipId: string) => void
+  /** 打开 TTS 配音面板 Drawer */
+  onOpenTtsDrawer?: (clipId: string) => void
+  /** 打开水印设置面板 Drawer */
+  onOpenWatermarkDrawer?: () => void
+  /** 打开片头片尾设置面板 Drawer */
+  onOpenIntroOutroDrawer?: () => void
+  /** 打开混剪设置面板 Drawer */
+  onOpenPipDrawer?: () => void
+  /** 打开滤镜调色面板 Drawer */
+  onOpenFilterDrawer?: () => void
+  /** 打开绿幕抠像面板 Drawer */
+  onOpenGreenScreenDrawer?: () => void
+  /** 打开贴纸面板 Drawer */
+  onOpenStickerDrawer?: () => void
+  /** 打开封面选择器 Drawer */
+}

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

@@ -0,0 +1,21 @@
+/**
+ * ClipPropertiesPanel 工具函数
+ */
+import type { AssetItem } from "@/api/assets"
+import type { TemplateMode } from "@/api/editing-planner"
+
+/** 从 metadata 取性别标签 */
+export const getGenderLabel = (m: AssetItem): string => {
+  const g = (m.metadata?.gender as string) || ""
+  if (g === "male") return "男"
+  if (g === "female") return "女"
+  return ""
+}
+
+/** 格式化模式标签 */
+export const formatModeLabel = (mode: TemplateMode): string => {
+  if (mode === "pip") return "混剪"
+  if (mode === "voice_over") return "人物口播"
+  if (mode === "one_take") return "一镜到底"
+  return "口播+混剪"
+}

apps/web/src/pages/editing-planner/utils/timeline.ts

@@ -0,0 +1,20 @@
+/** 格式化时间为 mm:ss */
+export const formatTime = (sec: number): string => {
+  const m = Math.floor(sec / 60)
+  const s = Math.floor(sec % 60)
+  return `${m}:${s.toString().padStart(2, "0")}`
+}
+
+/** 格式化裁剪时间（精确到 0.1 秒） */
+export const formatTrimTime = (sec: number): string => {
+  return `${sec.toFixed(1)}s`
+}
+
+/** 生成时间标尺刻度 */
+export const generateRulerMarks = (totalDuration: number, step: number): number[] => {
+  const marks: number[] = []
+  for (let t = 0; t <= totalDuration + step; t += step) {
+    marks.push(t)
+  }
+  return marks
+}

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

@@ -3,126 +3,43 @@
  * 卡片视图展示用户已保存的剪辑模板
  * 支持搜索、分类筛选、编辑/复制/删除/使用模板生成
  */
-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 React from "react"
+import { Typography, Input, Select, Button, Empty, Spin, Row, Col } from "antd"
 import {
   SearchOutlined,
-  EditOutlined,
-  CopyOutlined,
-  DeleteOutlined,
-  VideoCameraOutlined,
   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 +96,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

@@ -250,10 +250,7 @@ const ProductLibrary: React.FC = () => {
             value={filterProject}
             onChange={setFilterProject}
             style={{ width: 140 }}
-            options={[
-              { value: "all", label: "全部项目" },
-              ...projectOptions,
-            ]}
+            options={[{ value: "all", label: "全部项目" }, ...projectOptions]}
           />
           <Select
             value={filterReviewStatus}

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)
+}

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

@@ -115,6 +115,16 @@ vi.mock("@/api/templates", () => ({
 vi.mock("@/pages/templates/TemplateLibrary.css", () => ({}))
 
 import TemplateLibrary from "@/pages/templates/TemplateLibrary"
+import "@/pages/templates/types/templateLibrary"
+import "@/pages/templates/constants/templateLibrary"
+import "@/pages/templates/utils/templateLibrary"
+import "@/pages/templates/hooks/useTemplateLibrary"
+import "@/pages/templates/hooks/useTemplateDetail"
+import "@/pages/templates/components/template-library/TemplateCard"
+import "@/pages/templates/components/template-library/TemplateDetailModal"
+import "@/pages/templates/components/template-library/TemplateHeader"
+import "@/pages/templates/components/template-library/TemplateToolbar"
+import "@/pages/templates/components/template-library/TemplateGrid"
 
 describe("TemplateLibrary Page", () => {
   it("should render without crashing", () => {

apps/web/src/test/pages/editing-planner/smoke.test.tsx

@@ -10,9 +10,20 @@ import "@/pages/editing-planner/EditingPlanner"
 
 // 常量
 import "@/pages/editing-planner/constants"
+import "@/pages/editing-planner/constants/timeline"
+import "@/pages/editing-planner/constants/clipProperties"
+import "@/pages/editing-planner/constants/pipConfig"
+import "@/pages/editing-planner/constants/sticker"
+import "@/pages/editing-planner/constants/filter"
+import "@/pages/editing-planner/constants/introOutro"
+import "@/pages/editing-planner/constants/subtitleStyle"
+import "@/pages/editing-planner/constants/tts"
+import "@/pages/editing-planner/constants/watermark"
 
 // 工具函数
 import "@/pages/editing-planner/utils/selectors"
+import "@/pages/editing-planner/utils/timeline"
+import "@/pages/editing-planner/utils/clipProperties"
 
 // 子组件
 import "@/pages/editing-planner/components/BgmSelector"
@@ -36,6 +47,31 @@ import "@/pages/editing-planner/components/StatusBar"
 import "@/pages/editing-planner/components/StickerPanel"
 import "@/pages/editing-planner/components/SubtitleStylePanel"
 import "@/pages/editing-planner/components/TimelinePanel"
+import "@/pages/editing-planner/components/timeline/ClipCard"
+import "@/pages/editing-planner/components/timeline/TimeRuler"
+import "@/pages/editing-planner/components/timeline/AddClipPicker"
+import "@/pages/editing-planner/components/timeline/TrimPreview"
+import "@/pages/editing-planner/components/timeline/ContextMenu"
+import "@/pages/editing-planner/components/clip-properties/SubtitleSettingsSection"
+import "@/pages/editing-planner/components/clip-properties/BgmSettingsSection"
+import "@/pages/editing-planner/components/clip-properties/ClipDetailSection"
+import "@/pages/editing-planner/components/clip-properties/StatsSection"
+import "@/pages/editing-planner/components/pip-config/LayerList"
+import "@/pages/editing-planner/components/pip-config/LayerConfig"
+import "@/pages/editing-planner/components/sticker/StickerLibrary"
+import "@/pages/editing-planner/components/sticker/StickerList"
+import "@/pages/editing-planner/components/sticker/StickerPropsEditor"
+import "@/pages/editing-planner/components/filter/FilterPresetGrid"
+import "@/pages/editing-planner/components/filter/FilterManualAdjust"
+import "@/pages/editing-planner/components/intro-outro/IntroOutroBlock"
+import "@/pages/editing-planner/components/subtitle-style/SubtitlePreview"
+import "@/pages/editing-planner/components/tts/VoiceSelector"
+import "@/pages/editing-planner/components/tts/TtsSlider"
+import "@/pages/editing-planner/components/watermark/WatermarkTypeTabs"
+import "@/pages/editing-planner/components/watermark/ImageWatermarkSection"
+import "@/pages/editing-planner/components/watermark/TextWatermarkSection"
+import "@/pages/editing-planner/components/watermark/ScrollWatermarkSection"
+import "@/pages/editing-planner/components/watermark/WatermarkCommonSection"
 import "@/pages/editing-planner/components/TopBar"
 import "@/pages/editing-planner/components/TransitionSelector"
 import "@/pages/editing-planner/components/TtsPanel"
@@ -44,6 +80,7 @@ import "@/pages/editing-planner/components/WatermarkPanel"
 // 类型
 import "@/pages/editing-planner/types"
 import "@/pages/editing-planner/types/subtitle"
+import "@/pages/editing-planner/types/clipProperties"
 
 // Hooks
 import "@/pages/editing-planner/hooks/useUndoRedo"
@@ -52,6 +89,11 @@ import "@/pages/editing-planner/hooks/useEditorDrawers"
 import "@/pages/editing-planner/hooks/usePlaybackControl"
 import "@/pages/editing-planner/hooks/useClipOperations"
 import "@/pages/editing-planner/hooks/useTemplateManagement"
+import "@/pages/editing-planner/hooks/useVoicePreview"
+import "@/pages/editing-planner/hooks/usePipLayers"
+import "@/pages/editing-planner/hooks/useStickerItems"
+import "@/pages/editing-planner/hooks/useTtsPanel"
+import "@/pages/editing-planner/hooks/useWatermarkConfig"
 
 describe("EditingPlanner module smoke test", () => {
   it("should load all editing-planner modules", () => {

apps/worker/video_processing/concat_engine.py

@@ -18,135 +18,22 @@
 from __future__ import annotations
 
 import logging
-from dataclasses import dataclass, field
 from pathlib import Path
 
 from video_processing.ffmpeg_utils import FFMPEG_BIN, probe_duration, probe_video_info, run_ffmpeg
 from video_processing.path_security import PathSecurityError, is_in_allowed_dirs, safe_resolve_path
 
+from packages.domain.video_concat import (  # noqa: F401  向后兼容导出
+    ALLOWED_VIDEO_EXTENSIONS,
+    CONCAT_DEMUXER_REQUIRED_PARAMS,
+    MAX_CONCAT_SEGMENTS,
+    ConcatConfig,
+    ConcatSegment,
+)
+
 logger = logging.getLogger(__name__)
 
 
-# ── 常量 ──────────────────────────────────────────────────────────────────────
-
-MAX_CONCAT_SEGMENTS = 50  # 最大拼接段数（安全上限，防止OOM）
-
-ALLOWED_VIDEO_EXTENSIONS = {".mp4", ".mov", ".avi", ".mkv", ".webm", ".flv", ".wmv"}
-
-# concat demuxer 要求一致的参数列表
-CONCAT_DEMUXER_REQUIRED_PARAMS = [
-    "codec_name",  # 视频编码
-    "width",  # 宽度
-    "height",  # 高度
-    "r_frame_rate",  # 帧率
-    "pix_fmt",  # 像素格式
-    "sample_rate",  # 音频采样率
-    "channels",  # 音频声道数
-    "audio_codec",  # 音频编码
-]
-
-
-# ── 拼接片段配置 ──────────────────────────────────────────────────────────────
-
-
-@dataclass
-class ConcatSegment:
-    """单个拼接片段."""
-
-    video_path: str  # 视频文件路径
-    start_time: float = 0.0  # 开始时间（秒），从视频的哪个位置开始取
-    duration: float = 0.0  # 持续时长（秒），0表示取到末尾
-    has_audio: bool = True  # 是否包含音频
-
-    @classmethod
-    def from_dict(cls, seg: dict) -> "ConcatSegment":
-        """从字典创建拼接片段，带安全类型转换."""
-        try:
-            start_time = max(0.0, float(seg.get("start_time", 0.0)))
-        except (TypeError, ValueError):
-            start_time = 0.0
-
-        try:
-            duration = max(0.0, float(seg.get("duration", 0.0)))
-        except (TypeError, ValueError):
-            duration = 0.0
-
-        return cls(
-            video_path=str(seg.get("video_path", "")),
-            start_time=start_time,
-            duration=duration,
-            has_audio=bool(seg.get("has_audio", True)),
-        )
-
-
-@dataclass
-class ConcatConfig:
-    """视频拼接配置."""
-
-    segments: list[ConcatSegment] = field(default_factory=list)
-    output_width: int = 0  # 输出宽度（0=自动取第一段）
-    output_height: int = 0  # 输出高度（0=自动取第一段）
-    output_fps: float = 0.0  # 输出帧率（0=自动取第一段）
-    force_reencode: bool = False  # 强制重新编码（不用 stream copy）
-    transition: str = "none"  # 转场效果（none/crossfade）- 预留
-    transition_duration: float = 0.3  # 转场时长
-
-    @classmethod
-    def from_config_dict(cls, config: dict | None) -> "ConcatConfig":
-        """从配置字典创建 ConcatConfig."""
-        if not config or not isinstance(config, dict):
-            return cls()
-
-        segments_raw = config.get("segments", [])
-        segments: list[ConcatSegment] = []
-
-        if isinstance(segments_raw, list):
-            for s in segments_raw:
-                if isinstance(s, dict) and s.get("video_path"):
-                    try:
-                        seg = ConcatSegment.from_dict(s)
-                        if seg.video_path:
-                            segments.append(seg)
-                    except Exception:
-                        logger.warning("[concat] skip invalid segment: %s", s)
-                        continue
-
-        try:
-            output_width = max(0, int(config.get("output_width", 0)))
-        except (TypeError, ValueError):
-            output_width = 0
-
-        try:
-            output_height = max(0, int(config.get("output_height", 0)))
-        except (TypeError, ValueError):
-            output_height = 0
-
-        try:
-            output_fps = max(0.0, float(config.get("output_fps", 0.0)))
-        except (TypeError, ValueError):
-            output_fps = 0.0
-
-        return cls(
-            segments=segments,
-            output_width=output_width,
-            output_height=output_height,
-            output_fps=output_fps,
-            force_reencode=bool(config.get("force_reencode", False)),
-            transition=str(config.get("transition", "none")),
-            transition_duration=max(0.1, float(config.get("transition_duration", 0.3))),
-        )
-
-    @property
-    def has_effect(self) -> bool:
-        """是否有有效片段需要拼接."""
-        return len([s for s in self.segments if s.video_path]) >= 2
-
-    @property
-    def total_segments(self) -> int:
-        """有效片段数量."""
-        return len([s for s in self.segments if s.video_path])
-
-
 # ── 路径安全校验 ────────────────────────────────────────────────────────────
 
 

apps/worker/video_processing/subtitle_render_engine.py

@@ -24,264 +24,34 @@
 from __future__ import annotations
 
 import logging
-from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
 
 from video_processing.path_security import PathSecurityError, is_in_allowed_dirs, safe_resolve_path
 
+from packages.domain.subtitle_style import (
+    ALLOWED_SUBTITLE_EXTENSIONS,
+    DEFAULT_COLOR,
+    DEFAULT_FONT,
+    DEFAULT_FONT_SIZE,
+    DEFAULT_MAX_CHARS_PER_LINE,
+    DEFAULT_POSITION,
+    DEFAULT_STROKE_COLOR,
+    DEFAULT_STROKE_WIDTH,
+    POSITION_ALIASES,
+    POSITION_ALIGNMENT,
+    SubtitleSegment,
+    SubtitleStyle,
+)
+from packages.domain.subtitle_style import escape_ass_text as _escape_ass_text  # noqa: F401  向后兼容导出
+from packages.domain.subtitle_style import format_ass_time as _format_ass_time
+from packages.domain.subtitle_style import hex_to_ass_bgr as _hex_to_ass_bgr
+from packages.domain.subtitle_style import hex_to_ass_color as _hex_to_ass_color
+from packages.domain.subtitle_style import opacity_to_ass_alpha as _opacity_to_ass_alpha
+from packages.domain.subtitle_style import wrap_text as _wrap_text
+
 logger = logging.getLogger(__name__)
 
 
-# ── 常量 ──────────────────────────────────────────────────────────────────────
-
-ALLOWED_SUBTITLE_EXTENSIONS = {".srt", ".ass", ".vtt", ".sub"}
-
-# 9宫格位置映射（ASS alignment 编号）
-POSITION_ALIGNMENT = {
-    "top_left": 7,
-    "top_center": 8,
-    "top_right": 9,
-    "middle_left": 4,
-    "center": 5,
-    "middle_right": 6,
-    "bottom_left": 1,
-    "bottom_center": 2,
-    "bottom_right": 3,
-}
-
-# 位置简称兼容
-POSITION_ALIASES = {
-    "top": "top_center",
-    "bottom": "bottom_center",
-    "middle": "center",
-    "left": "middle_left",
-    "right": "middle_right",
-}
-
-DEFAULT_FONT = "思源黑体"
-DEFAULT_FONT_SIZE = 24
-DEFAULT_COLOR = "#FFFFFF"
-DEFAULT_STROKE_COLOR = "#000000"
-DEFAULT_STROKE_WIDTH = 1.5
-DEFAULT_POSITION = "bottom_center"
-DEFAULT_MAX_CHARS_PER_LINE = 20
-
-
-# ── 字幕样式配置 ────────────────────────────────────────────────────────────
-
-
-@dataclass
-class SubtitleStyle:
-    """字幕样式配置."""
-
-    font_name: str = DEFAULT_FONT
-    font_size: int = DEFAULT_FONT_SIZE
-    font_color: str = DEFAULT_COLOR
-    bold: bool = False
-    italic: bool = False
-
-    # 描边
-    stroke_enabled: bool = True
-    stroke_color: str = DEFAULT_STROKE_COLOR
-    stroke_width: float = DEFAULT_STROKE_WIDTH
-
-    # 阴影
-    shadow_enabled: bool = False
-    shadow_color: str = "#000000"
-    shadow_offset_x: int = 2
-    shadow_offset_y: int = 2
-    shadow_blur: float = 0.0
-
-    # 背景框
-    background_enabled: bool = False
-    background_color: str = "#000000"
-    background_opacity: float = 0.5  # 0.0 ~ 1.0
-    background_padding: int = 8
-    background_radius: int = 4
-
-    # 位置
-    position: str = DEFAULT_POSITION  # 9宫格位置名
-    margin_v: int = 60  # 垂直边距
-    margin_l: int = 40  # 左边距
-    margin_r: int = 40  # 右边距
-
-    # 多行
-    max_chars_per_line: int = DEFAULT_MAX_CHARS_PER_LINE
-    line_spacing: int = 0  # 行间距
-
-    # 动画
-    fade_in: float = 0.0  # 淡入时长（秒）
-    fade_out: float = 0.0  # 淡出时长（秒）
-    animation_type: str = "none"  # none/fade/slide/typewriter
-
-    @classmethod
-    def from_dict(cls, config: dict[str, Any] | None) -> "SubtitleStyle":
-        """从字典创建样式配置，带安全类型转换."""
-        if not config or not isinstance(config, dict):
-            return cls()
-
-        def safe_str(key: str, default: str) -> str:
-            val = config.get(key, default)
-            return str(val) if val is not None else default
-
-        def safe_int(key: str, default: int) -> int:
-            try:
-                return int(config.get(key, default))
-            except (TypeError, ValueError):
-                return default
-
-        def safe_float(key: str, default: float) -> float:
-            try:
-                return float(config.get(key, default))
-            except (TypeError, ValueError):
-                return default
-
-        def safe_bool(key: str, default: bool) -> bool:
-            return bool(config.get(key, default))
-
-        position = safe_str("position", DEFAULT_POSITION)
-        position = POSITION_ALIASES.get(position, position)
-        if position not in POSITION_ALIGNMENT:
-            position = DEFAULT_POSITION
-
-        return cls(
-            font_name=safe_str("font", DEFAULT_FONT),
-            font_size=safe_int("size", DEFAULT_FONT_SIZE),
-            font_color=safe_str("color", DEFAULT_COLOR),
-            bold=safe_bool("bold", False),
-            italic=safe_bool("italic", False),
-            stroke_enabled=safe_bool("stroke_enabled", True),
-            stroke_color=safe_str("stroke_color", DEFAULT_STROKE_COLOR),
-            stroke_width=safe_float("stroke_width", DEFAULT_STROKE_WIDTH),
-            shadow_enabled=safe_bool("shadow_enabled", False),
-            shadow_color=safe_str("shadow_color", "#000000"),
-            shadow_offset_x=safe_int("shadow_offset_x", 2),
-            shadow_offset_y=safe_int("shadow_offset_y", 2),
-            shadow_blur=safe_float("shadow_blur", 0.0),
-            background_enabled=safe_bool("background_enabled", False),
-            background_color=safe_str("background_color", "#000000"),
-            background_opacity=max(0.0, min(1.0, safe_float("background_opacity", 0.5))),
-            background_padding=safe_int("background_padding", 8),
-            background_radius=safe_int("background_radius", 4),
-            position=position,
-            margin_v=safe_int("margin_v", 60),
-            margin_l=safe_int("margin_l", 40),
-            margin_r=safe_int("margin_r", 40),
-            max_chars_per_line=safe_int("max_chars_per_line", DEFAULT_MAX_CHARS_PER_LINE),
-            line_spacing=safe_int("line_spacing", 0),
-            fade_in=max(0.0, safe_float("fade_in", 0.0)),
-            fade_out=max(0.0, safe_float("fade_out", 0.0)),
-            animation_type=safe_str("animation_type", "none"),
-        )
-
-    @property
-    def alignment(self) -> int:
-        """获取 ASS alignment 编号."""
-        return POSITION_ALIGNMENT.get(self.position, 2)
-
-    @property
-    def ass_font_color(self) -> str:
-        """ASS 格式颜色 &HAABBGGRR."""
-        return _hex_to_ass_color(self.font_color)
-
-    @property
-    def ass_stroke_color(self) -> str:
-        return _hex_to_ass_color(self.stroke_color)
-
-    @property
-    def ass_shadow_color(self) -> str:
-        return _hex_to_ass_color(self.shadow_color)
-
-    @property
-    def ass_background_color(self) -> str:
-        """背景框颜色（ASS BackColour），带透明度."""
-        alpha_hex = _opacity_to_ass_alpha(self.background_opacity)
-        color_bgr = _hex_to_ass_bgr(self.background_color)
-        return f"&H{alpha_hex}{color_bgr}"
-
-
-# ── 工具函数 ──────────────────────────────────────────────────────────────────
-
-
-def _hex_to_ass_color(hex_color: str) -> str:
-    """HEX → ASS 颜色 &HAABBGGRR（默认不透明）."""
-    hex_color = hex_color.lstrip("#")
-    if len(hex_color) != 6:
-        return "&H00FFFFFF"
-    r, g, b = hex_color[0:2], hex_color[2:4], hex_color[4:6]
-    return f"&H00{b.upper()}{g.upper()}{r.upper()}"
-
-
-def _hex_to_ass_bgr(hex_color: str) -> str:
-    """HEX → ASS BGR 部分（不含 alpha）."""
-    hex_color = hex_color.lstrip("#")
-    if len(hex_color) != 6:
-        return "FFFFFF"
-    r, g, b = hex_color[0:2], hex_color[2:4], hex_color[4:6]
-    return f"{b.upper()}{g.upper()}{r.upper()}"
-
-
-def _opacity_to_ass_alpha(opacity: float) -> str:
-    """不透明度 → ASS alpha（00=不透明，FF=完全透明）."""
-    alpha = 255 - int(opacity * 255)
-    return f"{alpha:02X}"
-
-
-def _escape_ass_text(text: str) -> str:
-    """转义 ASS 文本特殊字符."""
-    text = text.replace("\r\n", "\\N").replace("\n", "\\N").replace("\r", "\\N")
-    text = text.replace("{", "(").replace("}", ")")
-    return text
-
-
-def _format_ass_time(seconds: float) -> str:
-    """秒 → ASS 时间格式 H:MM:SS.cc."""
-    hours = int(seconds // 3600)
-    minutes = int((seconds % 3600) // 60)
-    secs = seconds % 60
-    return f"{hours}:{minutes:02d}:{secs:05.2f}"
-
-
-def _wrap_text(text: str, max_chars: int) -> list[str]:
-    """按字数换行，优先标点断开."""
-    if len(text) <= max_chars:
-        return [text]
-
-    lines: list[str] = []
-    remaining = text
-
-    while len(remaining) > max_chars:
-        break_point = max_chars
-        punctuations = "，。！？、；：,.;:!?"
-
-        for i in range(max_chars, max_chars // 2, -1):
-            if i < len(remaining) and remaining[i] in punctuations:
-                break_point = i + 1
-                break
-
-        lines.append(remaining[:break_point])
-        remaining = remaining[break_point:]
-
-    if remaining:
-        lines.append(remaining)
-
-    return lines
-
-
-# ── 字幕片段 ──────────────────────────────────────────────────────────────────
-
-
-@dataclass
-class SubtitleSegment:
-    """单个字幕片段."""
-
-    start: float  # 开始时间（秒）
-    end: float  # 结束时间（秒）
-    text: str  # 字幕文本
-    style_name: str = "Default"  # 使用的样式名
-
-
 # ── 字幕渲染引擎 ──────────────────────────────────────────────────────────────
 
 

apps/worker/video_processing/unified_render_service.py

@@ -52,6 +52,13 @@ from video_processing.trim_engine import TrimConfig, TrimEngine, extract_trim_fr
 from video_processing.tts_engine import TtsEngine
 from video_processing.watermark_engine import WatermarkConfig, WatermarkEngine
 
+from packages.domain.render_layer_utils import LAYER_Z_INDEX as _IMPORTED_LAYER_Z_INDEX
+from packages.domain.render_layer_utils import can_pass_through as _can_pass_through_pure
+from packages.domain.render_layer_utils import clip_adjusted_duration as _clip_adjusted_duration_pure
+from packages.domain.render_layer_utils import clip_effective_duration as _clip_effective_duration_pure
+from packages.domain.render_layer_utils import clip_playback_speed as _clip_playback_speed_pure
+from packages.domain.render_layer_utils import estimate_total_duration as _estimate_total_duration_pure
+from packages.domain.render_layer_utils import resolve_layer_role as _resolve_layer_role_pure
 from packages.domain.tts_config import TtsConfig
 
 logger = logging.getLogger(__name__)
@@ -107,47 +114,16 @@ class RenderResult:
 
 
 def _resolve_layer_role(clip_type: str, config: dict[str, Any]) -> str:
-    """根据 clip_type 和 config.role 确定图层角色。
+    """根据 clip_type 和 config.role 确定图层角色（向后兼容别名）。
 
-    映射规则：
-      intro / outro         → "main"（按 order 排在首/尾）
-      overlay               → "overlay"（画中画叠加，z=1）
-      corner_voice          → "corner_voice"（右上角小窗，z=1）
-      background            → "background"（全屏底图，z=0）
-      b_roll                → "broll"（z=0）
-      main + config.role=b_roll → "broll"
-      main (default)        → "main"
+    实际实现移至 packages.domain.render_layer_utils.resolve_layer_role。
     """
-    role = config.get("role", "")
-
-    if clip_type in ("intro", "outro"):
-        return "main"
-    if clip_type == "overlay":
-        return "overlay"
-    if clip_type == "corner_voice":
-        return "corner_voice"
-    if clip_type == "background":
-        return "background"
-    if clip_type == "b_roll":
-        return "broll"
-    # main type
-    if role == "b_roll":
-        return "broll"
-    if role == "audio":
-        return "audio"
-    return "main"
+    return _resolve_layer_role_pure(clip_type, config)
 
 
 # ── 图层默认 z_index ─────────────────────────────────────────────────────────
 
-_LAYER_Z_INDEX: dict[str, int] = {
-    "background": -1,
-    "broll": 0,
-    "main": 0,
-    "overlay": 1,
-    "corner_voice": 1,
-    "audio": 2,
-}
+_LAYER_Z_INDEX: dict[str, int] = _IMPORTED_LAYER_Z_INDEX
 
 # 图层默认 PiP 位置（相对输出画布的偏移）
 _PIP_SCALE = 0.25  # PiP 占主画面的比例
@@ -489,29 +465,9 @@ class UnifiedRenderService:
     def _estimate_total_duration(self, layers: list[RenderLayer]) -> float:
         """估算视频总时长（用于字幕等需要）。
 
-        取主图层（main/broll/background）的总时长，转场重叠按 transition_duration 估算。
+        实际实现移至 packages.domain.render_layer_utils.estimate_total_duration。
         """
-        # 找主图层（第一个有视频内容的图层）
-        main_layer = None
-        for role in ("main", "broll", "background"):
-            for layer in layers:
-                if layer.role == role:
-                    main_layer = layer
-                    break
-            if main_layer:
-                break
-
-        if not main_layer or not main_layer.clips:
-            return 0.0
-
-        total = sum(UnifiedRenderService._clip_adjusted_duration(c) for c in main_layer.clips)
-
-        # 减去转场重叠时间（粗略估算）
-        n_clips = len(main_layer.clips)
-        if n_clips > 1:
-            total -= (n_clips - 1) * self.transition_duration
-
-        return max(0.1, total)
+        return _estimate_total_duration_pure(layers, self.transition_duration)
 
     def _maybe_generate_ass(self, video_duration: float) -> Path | None:
         """根据 plan.config 生成 ASS 字幕文件。
@@ -1869,10 +1825,11 @@ class UnifiedRenderService:
 
     @staticmethod
     def _clip_effective_duration(clip: ResolvedClip) -> float:
-        """计算 clip 的有效时长（原速 trim 后时长）."""
-        if clip.duration > 0:
-            return min(clip.duration, clip.actual_duration) if clip.actual_duration > 0 else clip.duration
-        return clip.actual_duration if clip.actual_duration > 0 else 0.0
+        """计算 clip 的有效时长（原速 trim 后时长）。
+
+        实际实现移至 packages.domain.render_layer_utils.clip_effective_duration。
+        """
+        return _clip_effective_duration_pure(clip.duration, clip.actual_duration)
 
     # ── 画中画（PiP）相关方法 ──────────────────────────────────────────────────
 
@@ -1969,17 +1926,20 @@ class UnifiedRenderService:
 
     @staticmethod
     def _clip_speed(clip: ResolvedClip) -> float:
-        """获取 clip 的播放速度，无效值回退到 1.0."""
-        speed = getattr(clip, "playback_speed", 1.0)
-        if not isinstance(speed, (int, float)) or speed <= 0:
-            return 1.0
-        return float(speed)
+        """获取 clip 的播放速度，无效值回退到 1.0。
+
+        实际实现移至 packages.domain.render_layer_utils.clip_playback_speed。
+        """
+        return _clip_playback_speed_pure(getattr(clip, "playback_speed", 1.0))
 
     @staticmethod
     def _clip_adjusted_duration(clip: ResolvedClip) -> float:
-        """计算调速后的 clip 实际时长（用于拼接计算）."""
-        base = UnifiedRenderService._clip_effective_duration(clip)
-        speed = UnifiedRenderService._clip_speed(clip)
-        if abs(speed - 1.0) < 1e-6:
-            return base
-        return base / speed
+        """计算调速后的 clip 实际时长（用于拼接计算）。
+
+        实际实现移至 packages.domain.render_layer_utils.clip_adjusted_duration。
+        """
+        return _clip_adjusted_duration_pure(
+            clip.duration,
+            clip.actual_duration,
+            getattr(clip, "playback_speed", 1.0),
+        )

apps/worker/worker_app/tasks/asset_analyzer.py

@@ -19,74 +19,21 @@ from PIL import Image
 
 from packages.domain.classification import AssetClassification
 
+from .asset_quality_scoring import (
+    AudioAnalysis,
+    ClassificationResult,
+    ColorAnalysis,
+    MotionAnalysis,
+    QualityScore,
+    VideoInfo,
+    calculate_category_scores,
+    calculate_quality_score,
+    classify_from_analysis,
+)
+
 logger = logging.getLogger(__name__)
 
 
-@dataclass
-class VideoInfo:
-    """视频基本信息"""
-
-    width: int = 0
-    height: int = 0
-    fps: float = 0.0
-    duration: float = 0.0
-    bitrate: int = 0
-    codec: str = ""
-    has_audio: bool = False
-    file_size: int = 0
-
-
-@dataclass
-class ColorAnalysis:
-    """色彩分析结果"""
-
-    dominant_hue: float = 0.0  # 主色调 (0-360)
-    green_ratio: float = 0.0  # 绿色占比
-    warm_ratio: float = 0.0  # 暖色调占比
-    cool_ratio: float = 0.0  # 冷色调占比
-    avg_saturation: float = 0.0
-    avg_brightness: float = 0.0
-
-
-@dataclass
-class MotionAnalysis:
-    """运动分析结果"""
-
-    motion_score: float = 0.0  # 运动幅度 (0-1)
-    scene_changes: int = 0  # 场景切换次数
-
-
-@dataclass
-class AudioAnalysis:
-    """音频分析结果"""
-
-    has_audio: bool = False
-    speech_ratio: float = 0.0  # 人声比例
-    music_ratio: float = 0.0  # 音乐比例
-    ambient_ratio: float = 0.0  # 环境音比例
-
-
-@dataclass
-class ClassificationResult:
-    """分类结果"""
-
-    category: AssetClassification
-    confidence: float
-    scores: dict[str, float] = field(default_factory=dict)
-
-
-@dataclass
-class QualityScore:
-    """质量评分结果"""
-
-    total: float
-    resolution_score: float = 0.0
-    fps_score: float = 0.0
-    bitrate_score: float = 0.0
-    clarity_score: float = 0.0
-    stability_score: float = 0.0
-
-
 class AssetAnalyzer:
     """
     轻量级视频素材分析器
@@ -449,316 +396,37 @@ class AssetAnalyzer:
         """
         综合分析得出分类结果
 
+        评分逻辑在 asset_quality_scoring.calculate_category_scores / classify_from_analysis
+        纯函数中，此处只负责采集分析数据后委托计算。
+
         Returns:
             ClassificationResult 对象
         """
-        # 提取分析数据
         frames = self.extract_frames()
         color = self.analyze_color_distribution(frames)
         motion = self.analyze_motion(frames)
         audio = self.analyze_audio()
 
-        # 计算各类别得分
-        scores = self._calculate_category_scores(color, motion, audio)
-
-        # 找最高分
-        if not scores:
-            return ClassificationResult(
-                category=AssetClassification.OTHER,
-                confidence=0.3,
-                scores={},
-            )
-
-        best_category = max(scores.items(), key=lambda x: x[1])
-        category = AssetClassification(best_category[0])
-        confidence = min(0.95, max(0.3, best_category[1]))
-
-        return ClassificationResult(
-            category=category,
-            confidence=confidence,
-            scores=scores,
-        )
-
-    def _calculate_category_scores(
-        self,
-        color: ColorAnalysis,
-        motion: MotionAnalysis,
-        audio: AudioAnalysis,
-    ) -> dict[str, float]:
-        """
-        计算各类别的置信度得分
-
-        Args:
-            color: 色彩分析结果
-            motion: 运动分析结果
-            audio: 音频分析结果
-
-        Returns:
-            各类别得分字典
-        """
-        scores = {}
-
-        # 1. 风景 (scenic) - 绿色、户外、自然
-        scenic_score = 0.0
-        if color.green_ratio > 0.3:
-            scenic_score += 0.4 * color.green_ratio
-        if color.avg_saturation > 0.3:
-            scenic_score += 0.2 * color.avg_saturation
-        if color.avg_brightness > 0.4:
-            scenic_score += 0.2
-        if motion.motion_score > 0.1 and motion.motion_score < 0.5:
-            scenic_score += 0.2  # 适度运动（如云朵、树叶）
-        if not audio.has_audio or audio.ambient_ratio > 0.5:
-            scenic_score += 0.2  # 自然环境音
-        scores[AssetClassification.SCENIC.value] = min(1.0, scenic_score)
-
-        # 2. 产品 (product) - 中等亮度、均匀色彩、低运动
-        product_score = 0.0
-        if 0.3 < color.avg_brightness < 0.7:
-            product_score += 0.3
-        if color.avg_saturation < 0.5:
-            product_score += 0.2
-        if motion.motion_score < 0.15:
-            product_score += 0.4  # 低运动 = 产品展示
-        if color.cool_ratio > 0.3:
-            product_score += 0.2  # 冷色调 = 科技感
-        scores[AssetClassification.PRODUCT.value] = min(1.0, product_score)
-
-        # 3. 人物 (person) - 中等运动、有时有人声
-        person_score = 0.0
-        if 0.1 < motion.motion_score < 0.4:
-            person_score += 0.3  # 适度运动
-        if audio.has_audio and audio.speech_ratio > 0.3:
-            person_score += 0.5  # 有人声
-        if color.avg_brightness > 0.3:
-            person_score += 0.2
-        scores[AssetClassification.PERSON.value] = min(1.0, person_score)
-
-        # 4. 动物 (animal) - 高运动、有时自然音
-        animal_score = 0.0
-        if motion.motion_score > 0.3:
-            animal_score += 0.4  # 高运动
-        if motion.scene_changes > 2:
-            animal_score += 0.2
-        if audio.has_audio and (audio.ambient_ratio > 0.3 or audio.speech_ratio > 0.2):
-            animal_score += 0.3
-        scores[AssetClassification.ANIMAL.value] = min(1.0, animal_score)
-
-        # 5. 美食 (food) - 暖色调、高饱和度
-        food_score = 0.0
-        if color.warm_ratio > 0.4:
-            food_score += 0.5
-        if color.avg_saturation > 0.5:
-            food_score += 0.3
-        if 0.4 < color.avg_brightness < 0.8:
-            food_score += 0.2
-        scores[AssetClassification.FOOD.value] = min(1.0, food_score)
-
-        # 6. 科技 (tech) - 冷色调、低饱和度、低运动
-        tech_score = 0.0
-        if color.cool_ratio > 0.4:
-            tech_score += 0.4
-        if color.avg_saturation < 0.4:
-            tech_score += 0.3
-        if motion.motion_score < 0.2:
-            tech_score += 0.3
-        scores[AssetClassification.TECH.value] = min(1.0, tech_score)
-
-        # 7. 运动 (sport) - 高运动
-        sport_score = 0.0
-        if motion.motion_score > 0.4:
-            sport_score += 0.6
-        if motion.scene_changes > 3:
-            sport_score += 0.2
-        if color.avg_brightness > 0.4:
-            sport_score += 0.2
-        scores[AssetClassification.SPORT.value] = min(1.0, sport_score)
-
-        # 8. 音乐 (music) - 有节奏性音乐
-        music_score = 0.0
-        if audio.has_audio and audio.music_ratio > 0.4:
-            music_score += 0.6
-        # 纯视觉判断：色彩丰富但非自然
-        if color.avg_saturation > 0.5 and color.green_ratio < 0.2:
-            music_score += 0.3
-        scores[AssetClassification.MUSIC.value] = min(1.0, music_score)
-
-        # 9. 其他 (other) - 默认最低分
-        scores[AssetClassification.OTHER.value] = 0.1
-
-        return scores
+        return classify_from_analysis(color, motion, audio)
 
     def calculate_quality_score(self) -> QualityScore:
         """
         计算视频质量综合评分 (0-100)
 
+        评分逻辑在 asset_quality_scoring.calculate_quality_score 纯函数中，
+        此处只负责采集数据后委托计算。
+
         评分维度:
         1. 分辨率得分 (25分)
         2. 帧率得分 (20分)
         3. 码率得分 (20分)
-        4. 清晰度得分 (20分) - Laplacian 方差
-        5. 稳定性得分 (15分) - 帧间位移方差
+        4. 清晰度得分 (20分)
+        5. 稳定性得分 (15分)
         """
         info = self.get_video_info()
         frames = self.extract_frames()
 
-        # 1. 分辨率得分
-        resolution_score = self._score_resolution(info.width, info.height)
-
-        # 2. 帧率得分
-        fps_score = self._score_framerate(info.fps)
-
-        # 3. 码率得分
-        bitrate_score = self._score_bitrate(info.bitrate)
-
-        # 4. 清晰度得分
-        clarity_score = self._score_clarity(frames)
-
-        # 5. 稳定性得分
-        stability_score = self._score_stability(frames)
-
-        total = resolution_score + fps_score + bitrate_score + clarity_score + stability_score
-
-        return QualityScore(
-            total=round(min(100, max(0, total)), 1),
-            resolution_score=resolution_score,
-            fps_score=fps_score,
-            bitrate_score=bitrate_score,
-            clarity_score=clarity_score,
-            stability_score=stability_score,
-        )
-
-    def _score_resolution(self, width: int, height: int) -> float:
-        """分辨率评分 (满分 25)"""
-        pixels = width * height
-
-        if pixels >= 3840 * 2160:  # 4K
-            return 25.0
-        elif pixels >= 2560 * 1440:  # 2K
-            return 22.0
-        elif pixels >= 1920 * 1080:  # 1080p
-            return 20.0
-        elif pixels >= 1280 * 720:  # 720p
-            return 15.0
-        elif pixels >= 854 * 480:  # 480p
-            return 8.0
-        else:
-            return 3.0
-
-    def _score_framerate(self, fps: float) -> float:
-        """帧率评分 (满分 20)"""
-        if fps >= 60:
-            return 20.0
-        elif fps >= 30:
-            return 15.0
-        elif fps >= 24:
-            return 10.0
-        elif fps >= 15:
-            return 7.0
-        else:
-            return 5.0
-
-    def _score_bitrate(self, bitrate: int) -> float:
-        """码率评分 (满分 20)"""
-        bitrate_mbps = bitrate / 1_000_000
-
-        if bitrate_mbps > 10:
-            return 20.0
-        elif bitrate_mbps >= 5:
-            return 15.0
-        elif bitrate_mbps >= 2:
-            return 10.0
-        elif bitrate_mbps >= 0.5:
-            return 5.0
-        else:
-            return 3.0
-
-    def _score_clarity(self, frames: list[np.ndarray]) -> float:
-        """
-        清晰度评分 (满分 20)
-
-        使用 Laplacian 方差评估画面清晰度
-        高方差 = 细节丰富 = 高分
-        """
-        if not frames:
-            return 10.0  # 默认中等分
-
-        try:
-            variances = []
-
-            for frame in frames[:5]:  # 只分析前 5 帧
-                if len(frame.shape) == 3:
-                    # 转灰度
-                    gray = np.dot(frame[..., :3], [0.299, 0.587, 0.114]).astype(np.uint8)
-                else:
-                    gray = frame
-
-                # Laplacian 算子
-                laplacian = np.array([[0, 1, 0], [1, -4, 1], [0, 1, 0]], dtype=np.float32)
-
-                # 手动计算卷积
-                from scipy import signal
-
-                laplacian_img = signal.convolve2d(gray.astype(float), laplacian, mode="same")
-                variance = np.var(laplacian_img)
-                variances.append(variance)
-
-            # 归一化方差到 0-20 分
-            avg_variance = np.mean(variances)
-            # 根据经验值调整
-            score = min(20.0, avg_variance / 100)
-            return float(score)
-
-        except ImportError:
-            # 如果没有 scipy，使用简化方法
-            return 10.0
-        except Exception:
-            return 10.0
-
-    def _score_stability(self, frames: list[np.ndarray]) -> float:
-        """
-        稳定性评分 (满分 15)
-
-        分析帧间位移方差
-        画面稳定 = 高分
-        剧烈抖动 = 低分
-        """
-        if len(frames) < 2:
-            return 10.0  # 默认中等分
-
-        try:
-            displacements = []
-
-            for i in range(len(frames) - 1):
-                # 缩小帧以加速处理
-                scale = 0.25
-                new_h = int(frames[i].shape[0] * scale)
-                new_w = int(frames[i].shape[1] * scale)
-                frame1_small = np.array(Image.fromarray(frames[i]).resize((new_w, new_h)))
-                new_h2 = int(frames[i + 1].shape[0] * scale)
-                new_w2 = int(frames[i + 1].shape[1] * scale)
-                frame2_small = np.array(Image.fromarray(frames[i + 1]).resize((new_w2, new_h2)))
-
-                # 简单位移检测：灰度差
-                gray1 = np.mean(frame1_small, axis=2) if len(frame1_small.shape) == 3 else frame1_small
-                gray2 = np.mean(frame2_small, axis=2) if len(frame2_small.shape) == 3 else frame2_small
-
-                diff = np.abs(gray2.astype(float) - gray1.astype(float))
-                displacement = np.mean(diff) / 255.0
-                displacements.append(displacement)
-
-            # 高位移方差 = 不稳定
-            if displacements:
-                displacement_variance = np.var(displacements)
-                # 归一化
-                instability = min(1.0, displacement_variance * 10)
-                score = 15.0 * (1.0 - instability)
-                return float(max(0.0, score))
-
-            return 10.0
-
-        except Exception:
-            return 10.0
+        return calculate_quality_score(info, frames)
 
 
 def classify_asset_real(video_path: str) -> tuple[str, float]:

apps/worker/worker_app/tasks/asset_quality_scoring.py

@@ -0,0 +1,459 @@
+"""素材质量与分类评分 — 纯逻辑模块.
+
+从 asset_analyzer.py 提取的评分计算逻辑，纯函数，无副作用。
+输入分析结果对象，输出评分/分类结果。
+
+拆分目的：
+1. 大文件瘦身（asset_analyzer.py 799行 → 拆出 200+ 行纯逻辑）
+2. 评分逻辑可独立单测，不依赖 FFmpeg/视频文件
+3. 评分策略调整时不需要触碰分析主流程
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+import numpy as np
+
+from packages.domain.classification import AssetClassification
+
+# ── 数据类 ────────────────────────────────────────────────────────────
+
+
+@dataclass
+class VideoInfo:
+    """视频基本信息"""
+
+    width: int = 0
+    height: int = 0
+    fps: float = 0.0
+    duration: float = 0.0
+    bitrate: int = 0
+    codec: str = ""
+    has_audio: bool = False
+    file_size: int = 0
+
+
+@dataclass
+class ColorAnalysis:
+    """色彩分析结果"""
+
+    dominant_hue: float = 0.0  # 主色调 (0-360)
+    green_ratio: float = 0.0  # 绿色占比
+    warm_ratio: float = 0.0  # 暖色调占比
+    cool_ratio: float = 0.0  # 冷色调占比
+    avg_saturation: float = 0.0
+    avg_brightness: float = 0.0
+
+
+@dataclass
+class MotionAnalysis:
+    """运动分析结果"""
+
+    motion_score: float = 0.0  # 运动幅度 (0-1)
+    scene_changes: int = 0  # 场景切换次数
+
+
+@dataclass
+class AudioAnalysis:
+    """音频分析结果"""
+
+    has_audio: bool = False
+    speech_ratio: float = 0.0  # 人声比例
+    music_ratio: float = 0.0  # 音乐比例
+    ambient_ratio: float = 0.0  # 环境音比例
+
+
+@dataclass
+class ClassificationResult:
+    """分类结果"""
+
+    category: AssetClassification
+    confidence: float
+    scores: dict[str, float] = field(default_factory=dict)
+
+
+@dataclass
+class QualityScore:
+    """质量评分结果"""
+
+    total: float
+    resolution_score: float = 0.0
+    fps_score: float = 0.0
+    bitrate_score: float = 0.0
+    clarity_score: float = 0.0
+    stability_score: float = 0.0
+
+
+# ── 质量评分纯函数 ────────────────────────────────────────────────────
+
+
+def score_resolution(width: int, height: int) -> float:
+    """分辨率评分 (满分 25).
+
+    按像素总数阶梯评分：4K > 2K > 1080p > 720p > 480p > 其他.
+
+    Args:
+        width: 视频宽度（像素）
+        height: 视频高度（像素）
+
+    Returns:
+        float: 0-25 分
+    """
+    pixels = width * height
+
+    if pixels >= 3840 * 2160:  # 4K
+        return 25.0
+    elif pixels >= 2560 * 1440:  # 2K
+        return 22.0
+    elif pixels >= 1920 * 1080:  # 1080p
+        return 20.0
+    elif pixels >= 1280 * 720:  # 720p
+        return 15.0
+    elif pixels >= 854 * 480:  # 480p
+        return 8.0
+    else:
+        return 3.0
+
+
+def score_framerate(fps: float) -> float:
+    """帧率评分 (满分 20).
+
+    60fps 满分，阶梯递减.
+
+    Args:
+        fps: 帧率（帧/秒）
+
+    Returns:
+        float: 0-20 分
+    """
+    if fps >= 60:
+        return 20.0
+    elif fps >= 30:
+        return 15.0
+    elif fps >= 24:
+        return 10.0
+    elif fps >= 15:
+        return 7.0
+    else:
+        return 5.0
+
+
+def score_bitrate(bitrate: int) -> float:
+    """码率评分 (满分 20).
+
+    按 Mbps 阶梯评分.
+
+    Args:
+        bitrate: 码率（bps）
+
+    Returns:
+        float: 0-20 分
+    """
+    bitrate_mbps = bitrate / 1_000_000
+
+    if bitrate_mbps > 10:
+        return 20.0
+    elif bitrate_mbps >= 5:
+        return 15.0
+    elif bitrate_mbps >= 2:
+        return 10.0
+    elif bitrate_mbps >= 0.5:
+        return 5.0
+    else:
+        return 3.0
+
+
+def score_clarity(frames: list[np.ndarray]) -> float:
+    """清晰度评分 (满分 20).
+
+    使用 Laplacian 方差评估画面清晰度。
+    高方差 = 细节丰富 = 高分.
+
+    Args:
+        frames: 视频帧列表（numpy 数组，RGB 或灰度）
+
+    Returns:
+        float: 0-20 分
+    """
+    if not frames:
+        return 10.0  # 默认中等分
+
+    try:
+        variances = []
+
+        for frame in frames[:5]:  # 只分析前 5 帧
+            if len(frame.shape) == 3:
+                # 转灰度
+                gray = np.dot(frame[..., :3], [0.299, 0.587, 0.114]).astype(np.uint8)
+            else:
+                gray = frame
+
+            # Laplacian 算子
+            laplacian = np.array([[0, 1, 0], [1, -4, 1], [0, 1, 0]], dtype=np.float32)
+
+            # 手动计算卷积
+            from scipy import signal
+
+            laplacian_img = signal.convolve2d(gray.astype(float), laplacian, mode="same")
+            variance = np.var(laplacian_img)
+            variances.append(variance)
+
+        # 归一化方差到 0-20 分
+        avg_variance = np.mean(variances)
+        score = min(20.0, avg_variance / 100)
+        return float(score)
+
+    except ImportError:
+        # 如果没有 scipy，使用简化方法
+        return 10.0
+    except Exception:
+        return 10.0
+
+
+def score_stability(frames: list[np.ndarray]) -> float:
+    """稳定性评分 (满分 15).
+
+    分析帧间位移方差。
+    画面稳定 = 高分；剧烈抖动 = 低分.
+
+    Args:
+        frames: 视频帧列表（numpy 数组，RGB 或灰度）
+
+    Returns:
+        float: 0-15 分
+    """
+    if len(frames) < 2:
+        return 10.0  # 默认中等分
+
+    try:
+        from PIL import Image
+
+        displacements = []
+
+        for i in range(len(frames) - 1):
+            # 缩小帧以加速处理
+            scale = 0.25
+            new_h = int(frames[i].shape[0] * scale)
+            new_w = int(frames[i].shape[1] * scale)
+            frame1_small = np.array(Image.fromarray(frames[i]).resize((new_w, new_h)))
+            new_h2 = int(frames[i + 1].shape[0] * scale)
+            new_w2 = int(frames[i + 1].shape[1] * scale)
+            frame2_small = np.array(Image.fromarray(frames[i + 1]).resize((new_w2, new_h2)))
+
+            # 简单位移检测：灰度差
+            gray1 = np.mean(frame1_small, axis=2) if len(frame1_small.shape) == 3 else frame1_small
+            gray2 = np.mean(frame2_small, axis=2) if len(frame2_small.shape) == 3 else frame2_small
+
+            diff = np.abs(gray2.astype(float) - gray1.astype(float))
+            displacement = np.mean(diff) / 255.0
+            displacements.append(displacement)
+
+        # 高位移方差 = 不稳定
+        if displacements:
+            displacement_variance = np.var(displacements)
+            # 归一化
+            instability = min(1.0, displacement_variance * 10)
+            score = 15.0 * (1.0 - instability)
+            return float(max(0.0, score))
+
+        return 10.0
+
+    except Exception:
+        return 10.0
+
+
+def calculate_quality_score(
+    info: VideoInfo,
+    frames: Optional[list[np.ndarray]] = None,
+) -> QualityScore:
+    """计算视频质量综合评分 (0-100).
+
+    评分维度:
+    1. 分辨率得分 (25分)
+    2. 帧率得分 (20分)
+    3. 码率得分 (20分)
+    4. 清晰度得分 (20分) - 无帧时默认10分
+    5. 稳定性得分 (15分) - 帧不足时默认10分
+
+    Args:
+        info: 视频基本信息
+        frames: 采样帧列表（可选，无则清晰度/稳定性给默认分）
+
+    Returns:
+        QualityScore: 各维度得分 + 总分
+    """
+    # 1. 分辨率得分
+    resolution_score = score_resolution(info.width, info.height)
+
+    # 2. 帧率得分
+    fps_score = score_framerate(info.fps)
+
+    # 3. 码率得分
+    bitrate_score = score_bitrate(info.bitrate)
+
+    # 4. 清晰度得分
+    clarity_score = score_clarity(frames) if frames else 10.0
+
+    # 5. 稳定性得分
+    stability_score = score_stability(frames) if frames and len(frames) >= 2 else 10.0
+
+    total = resolution_score + fps_score + bitrate_score + clarity_score + stability_score
+
+    return QualityScore(
+        total=round(min(100.0, max(0.0, total)), 1),
+        resolution_score=resolution_score,
+        fps_score=fps_score,
+        bitrate_score=bitrate_score,
+        clarity_score=clarity_score,
+        stability_score=stability_score,
+    )
+
+
+# ── 分类评分纯函数 ────────────────────────────────────────────────────
+
+
+def calculate_category_scores(
+    color: ColorAnalysis,
+    motion: MotionAnalysis,
+    audio: AudioAnalysis,
+) -> dict[str, float]:
+    """计算各类别的置信度得分.
+
+    9 个分类：风景、产品、人物、动物、美食、科技、运动、音乐、其他.
+
+    Args:
+        color: 色彩分析结果
+        motion: 运动分析结果
+        audio: 音频分析结果
+
+    Returns:
+        dict[str, float]: 各分类名称 -> 得分 (0-1)
+    """
+    scores: dict[str, float] = {}
+
+    # 1. 风景 (scenic) - 绿色、户外、自然
+    scenic_score = 0.0
+    if color.green_ratio > 0.3:
+        scenic_score += 0.4 * color.green_ratio
+    if color.avg_saturation > 0.3:
+        scenic_score += 0.2 * color.avg_saturation
+    if color.avg_brightness > 0.4:
+        scenic_score += 0.2
+    if 0.1 < motion.motion_score < 0.5:
+        scenic_score += 0.2  # 适度运动（如云朵、树叶）
+    if not audio.has_audio or audio.ambient_ratio > 0.5:
+        scenic_score += 0.2  # 自然环境音
+    scores[AssetClassification.SCENIC.value] = min(1.0, scenic_score)
+
+    # 2. 产品 (product) - 中等亮度、均匀色彩、低运动
+    product_score = 0.0
+    if 0.3 < color.avg_brightness < 0.7:
+        product_score += 0.3
+    if color.avg_saturation < 0.5:
+        product_score += 0.2
+    if motion.motion_score < 0.15:
+        product_score += 0.4  # 低运动 = 产品展示
+    if color.cool_ratio > 0.3:
+        product_score += 0.2  # 冷色调 = 科技感
+    scores[AssetClassification.PRODUCT.value] = min(1.0, product_score)
+
+    # 3. 人物 (person) - 中等运动、有时有人声
+    person_score = 0.0
+    if 0.1 < motion.motion_score < 0.4:
+        person_score += 0.3  # 适度运动
+    if audio.has_audio and audio.speech_ratio > 0.3:
+        person_score += 0.5  # 有人声
+    if color.avg_brightness > 0.3:
+        person_score += 0.2
+    scores[AssetClassification.PERSON.value] = min(1.0, person_score)
+
+    # 4. 动物 (animal) - 高运动、有时自然音
+    animal_score = 0.0
+    if motion.motion_score > 0.3:
+        animal_score += 0.4  # 高运动
+    if motion.scene_changes > 2:
+        animal_score += 0.2
+    if audio.has_audio and (audio.ambient_ratio > 0.3 or audio.speech_ratio > 0.2):
+        animal_score += 0.3
+    scores[AssetClassification.ANIMAL.value] = min(1.0, animal_score)
+
+    # 5. 美食 (food) - 暖色调、高饱和度
+    food_score = 0.0
+    if color.warm_ratio > 0.4:
+        food_score += 0.5
+    if color.avg_saturation > 0.5:
+        food_score += 0.3
+    if 0.4 < color.avg_brightness < 0.8:
+        food_score += 0.2
+    scores[AssetClassification.FOOD.value] = min(1.0, food_score)
+
+    # 6. 科技 (tech) - 冷色调、低饱和度、低运动
+    tech_score = 0.0
+    if color.cool_ratio > 0.4:
+        tech_score += 0.4
+    if color.avg_saturation < 0.4:
+        tech_score += 0.3
+    if motion.motion_score < 0.2:
+        tech_score += 0.3
+    scores[AssetClassification.TECH.value] = min(1.0, tech_score)
+
+    # 7. 运动 (sport) - 高运动
+    sport_score = 0.0
+    if motion.motion_score > 0.4:
+        sport_score += 0.6
+    if motion.scene_changes > 3:
+        sport_score += 0.2
+    if color.avg_brightness > 0.4:
+        sport_score += 0.2
+    scores[AssetClassification.SPORT.value] = min(1.0, sport_score)
+
+    # 8. 音乐 (music) - 有节奏性音乐
+    music_score = 0.0
+    if audio.has_audio and audio.music_ratio > 0.4:
+        music_score += 0.6
+    # 纯视觉判断：色彩丰富但非自然
+    if color.avg_saturation > 0.5 and color.green_ratio < 0.2:
+        music_score += 0.3
+    scores[AssetClassification.MUSIC.value] = min(1.0, music_score)
+
+    # 9. 其他 (other) - 默认最低分
+    scores[AssetClassification.OTHER.value] = 0.1
+
+    return scores
+
+
+def classify_from_analysis(
+    color: ColorAnalysis,
+    motion: MotionAnalysis,
+    audio: AudioAnalysis,
+) -> ClassificationResult:
+    """综合分析得出分类结果.
+
+    Args:
+        color: 色彩分析结果
+        motion: 运动分析结果
+        audio: 音频分析结果
+
+    Returns:
+        ClassificationResult: 分类结果（最高分类别 + 置信度 + 全部分数）
+    """
+    scores = calculate_category_scores(color, motion, audio)
+
+    if not scores:
+        return ClassificationResult(
+            category=AssetClassification.OTHER,
+            confidence=0.3,
+            scores={},
+        )
+
+    best_category = max(scores.items(), key=lambda x: x[1])
+    category = AssetClassification(best_category[0])
+    confidence = min(0.95, max(0.3, best_category[1]))
+
+    return ClassificationResult(
+        category=category,
+        confidence=confidence,
+        scores=scores,
+    )

apps/worker/worker_app/tasks/generation.py

@@ -17,12 +17,22 @@ import logging
 import os
 import tempfile
 import time
-from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from video_processing.ffmpeg_utils import probe_duration
 from worker_app.celery_app import celery_app
 from worker_app.db import SessionLocal
+from worker_app.tasks.generation_plan_builder import VirtualClip as _VirtualClip
+from worker_app.tasks.generation_plan_builder import VirtualPlan as _VirtualPlan
+from worker_app.tasks.generation_plan_builder import apply_template_clip_effects as _apply_template_clip_effects
+from worker_app.tasks.generation_plan_builder import (
+    build_clips_by_mode,
+)
+from worker_app.tasks.generation_plan_builder import build_error_info as _build_error_info
+from worker_app.tasks.generation_plan_builder import (
+    extract_intro_outro_from_clip_configs as _extract_intro_outro_from_clip_configs,
+)
 
 from packages.domain.bgm_utils import merge_bgm_config
 
@@ -88,36 +98,6 @@ def _update_task_status(task_id: str, status_action: str, **kwargs) -> bool:
         return False
 
 
-def _build_error_info(error: Exception, stage: str = "render") -> dict:
-    """构建结构化错误信息。
-
-    Args:
-        error: 异常对象
-        stage: 发生错误的阶段（download/render/merge/upload等）
-
-    Returns:
-        包含 error_type, message, stack_trace, stage, failed_at 的字典
-    """
-    import traceback
-    from datetime import datetime, timezone
-
-    tb_str = traceback.format_exc()
-    # 截取堆栈前20行，避免字段过大
-    tb_lines = tb_str.strip().splitlines()
-    if len(tb_lines) > 20:
-        tb_summary = "\n".join(tb_lines[:20]) + f"\n... (truncated, total {len(tb_lines)} lines)"
-    else:
-        tb_summary = tb_str
-
-    return {
-        "error_type": type(error).__name__,
-        "message": str(error),
-        "stack_trace": tb_summary,
-        "stage": stage,
-        "failed_at": datetime.now(timezone.utc).isoformat(),
-    }
-
-
 # ── 日志持久化辅助 ────────────────────────────────────────────────────────────
 
 
@@ -148,36 +128,6 @@ from video_processing.oss_helpers import (
     upload_to_oss,
 )
 
-# ── 虚拟 Plan / Clip（内存中构建，不写数据库） ────────────────────────────────
-
-
-@dataclass
-class _VirtualPlan:
-    """内存中的虚拟剪辑计划，供 UnifiedRenderService 使用。"""
-
-    id: str
-    name: str = ""
-    config: dict[str, Any] = field(default_factory=dict)
-
-
-@dataclass
-class _VirtualClip:
-    """内存中的虚拟剪辑片段，供 UnifiedRenderService 使用。"""
-
-    id: str
-    plan_id: str = ""
-    clip_type: str = "main"
-    order: int = 0
-    asset_id: str = ""
-    text_content: str = ""
-    start_time: float = 0.0
-    duration: float = 0.0
-    transition_effect: str = "cut"
-    transition_duration: float = 0.0  # 0 表示使用全局默认值
-    playback_speed: float = 1.0
-    status: str = "ready"
-    config: dict[str, Any] = field(default_factory=dict)
-
 
 def _load_template_clip_configs(template_id: str) -> list:
     """从数据库读取模板的片段配置列表。
@@ -206,124 +156,6 @@ def _load_template_clip_configs(template_id: str) -> list:
         return []
 
 
-def _extract_intro_outro_from_clip_configs(clip_configs: list) -> dict[str, Any]:
-    """从模板的 intro/outro 类型 clip_config 中提取 plan 级 intro_outro 配置。
-
-    UnifiedRenderService 已支持 plan.config.intro_outro 路径，
-    这里把 intro/outro 片段配置转为统一格式注入。
-    """
-    intro_configs = [
-        c for c in clip_configs if (c.clip_type.value if hasattr(c.clip_type, "value") else c.clip_type) == "intro"
-    ]
-    outro_configs = [
-        c for c in clip_configs if (c.clip_type.value if hasattr(c.clip_type, "value") else c.clip_type) == "outro"
-    ]
-
-    result: dict[str, Any] = {}
-
-    if intro_configs:
-        intro = intro_configs[0]
-        intro_cfg = intro.config or {}
-        result["has_intro"] = True
-        result["intro_type"] = intro_cfg.get("intro_type", "text")
-        result["intro_duration"] = intro.default_duration or 3.0
-        if intro.text_template:
-            result["intro_text"] = intro.text_template
-        # 透传额外配置
-        for key in ("intro_text_color", "intro_bg_color", "intro_font_size", "intro_video_url", "intro_video_path"):
-            if key in intro_cfg:
-                result[key] = intro_cfg[key]
-
-    if outro_configs:
-        outro = outro_configs[0]
-        outro_cfg = outro.config or {}
-        result["has_outro"] = True
-        result["outro_type"] = outro_cfg.get("outro_type", "text")
-        result["outro_duration"] = outro.default_duration or 3.0
-        if outro.text_template:
-            result["outro_text"] = outro.text_template
-        for key in ("outro_text_color", "outro_bg_color", "outro_font_size", "outro_follow_text"):
-            if key in outro_cfg:
-                result[key] = outro_cfg[key]
-
-    return result
-
-
-def _apply_template_clip_effects(
-    clips: list[_VirtualClip],
-    clip_configs: list,
-    mode: str,
-) -> None:
-    """将模板的 clip 级效果层映射到素材 clips 上（就地修改）。
-
-    映射规则：
-    - 只对素材主体 clips 做映射（ONE_TAKE: main, PIP: main+overlay, VOICE_OVER: main, VOICE_PIP: background+b_roll）
-    - 从模板中筛选 main 类型的 clip_config 作为效果模板
-    - 素材 clips 按顺序循环匹配模板 clip_config（素材多的话重复使用最后一个模板配置）
-    - 映射字段：transition_effect, config.color_grade, config.speed
-    """
-    if not clip_configs or not clips:
-        return
-
-    # 筛选 main 类型的模板配置（作为效果模板池）
-    main_configs = [
-        c
-        for c in clip_configs
-        if (c.clip_type.value if hasattr(c.clip_type, "value") else c.clip_type) in ("main", "showcase", "b_roll")
-    ]
-    if not main_configs:
-        return
-
-    # 确定需要映射的素材 clips（排除 corner_voice 等特殊层）
-    target_clips = [c for c in clips if c.clip_type not in ("corner_voice",)]
-
-    for i, clip in enumerate(target_clips):
-        # 循环匹配：素材多了用最后一个模板配置
-        cfg_idx = min(i, len(main_configs) - 1)
-        template_cfg = main_configs[cfg_idx]
-
-        # 1. 转场效果 + 时长
-        transition = (
-            template_cfg.transition_effect.value
-            if hasattr(template_cfg.transition_effect, "value")
-            else template_cfg.transition_effect
-        )
-        if transition and transition != "cut":
-            clip.transition_effect = transition
-            # 同步转场时长（模板 clip_config 里的 transition_duration）
-            tpl_cfg = template_cfg.config or {}
-            tpl_duration = tpl_cfg.get("transition_duration")
-            if tpl_duration:
-                try:
-                    dur_val = float(tpl_duration)
-                    if dur_val > 0:
-                        clip.transition_duration = dur_val
-                except (ValueError, TypeError):
-                    pass
-
-        # 2. clip 级效果配置（滤镜、调速等）
-        template_clip_config = template_cfg.config or {}
-        if template_clip_config:
-            # 合并到 clip.config（保留已有配置如 role 等）
-            existing_config = clip.config or {}
-            # 需要从模板复制的效果层 key
-            effect_keys = ("color_grade", "speed", "playback_speed", "reverse", "chroma_key", "filter")
-            for key in effect_keys:
-                if key in template_clip_config:
-                    existing_config[key] = template_clip_config[key]
-            clip.config = existing_config
-
-            # 3. 调速：同步到 clip.playback_speed 顶级字段（渲染引擎读此字段）
-            template_speed = template_clip_config.get("playback_speed") or template_clip_config.get("speed")
-            if template_speed:
-                try:
-                    speed_val = float(template_speed)
-                    if speed_val > 0:
-                        clip.playback_speed = speed_val
-                except (ValueError, TypeError):
-                    pass
-
-
 def _build_plan_and_clips_from_task(
     task_id: str,
     downloaded_paths: list[Path],

apps/worker/worker_app/tasks/generation_plan_builder.py

@@ -0,0 +1,327 @@
+"""Generation task pure logic utilities — template mapping + plan/clip building.
+
+从 generation.py 抽出来的纯逻辑模块：
+- VirtualPlan / VirtualClip: 内存中的虚拟计划/片段数据类
+- extract_intro_outro_from_clip_configs: 从模板 clip_config 提取片头片尾配置
+- apply_template_clip_effects: 将模板效果层映射到素材 clips
+- build_clips_by_mode: 根据模式和素材列表构建虚拟 clips
+- build_error_info: 构建结构化错误信息
+"""
+
+from __future__ import annotations
+
+import traceback
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+# ── 数据类 ───────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class VirtualPlan:
+    """内存中的虚拟剪辑计划，供 UnifiedRenderService 使用。"""
+
+    id: str
+    name: str = ""
+    config: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class VirtualClip:
+    """内存中的虚拟剪辑片段，供 UnifiedRenderService 使用。"""
+
+    id: str
+    plan_id: str = ""
+    clip_type: str = "main"
+    order: int = 0
+    asset_id: str = ""
+    text_content: str = ""
+    start_time: float = 0.0
+    duration: float = 0.0
+    transition_effect: str = "cut"
+    transition_duration: float = 0.0  # 0 表示使用全局默认值
+    playback_speed: float = 1.0
+    status: str = "ready"
+    config: dict[str, Any] = field(default_factory=dict)
+
+
+# ── 模板片头片尾提取 ────────────────────────────────────────────────────────
+
+
+def _clip_type_value(c: Any) -> str:
+    """获取 clip_config 的 clip_type 字符串值（兼容 Enum 和 str）。"""
+    if hasattr(c, "value"):
+        return str(c.value)
+    return str(c)
+
+
+def _transition_value(t: Any) -> str:
+    """获取 transition_effect 字符串值（兼容 Enum 和 str）。"""
+    if hasattr(t, "value"):
+        return str(t.value)
+    return str(t) if t else ""
+
+
+def extract_intro_outro_from_clip_configs(clip_configs: list) -> dict[str, Any]:
+    """从模板的 intro/outro 类型 clip_config 中提取 plan 级 intro_outro 配置。
+
+    UnifiedRenderService 已支持 plan.config.intro_outro 路径，
+    这里把 intro/outro 片段配置转为统一格式注入。
+    """
+    intro_configs = [c for c in clip_configs if _clip_type_value(c.clip_type) == "intro"]
+    outro_configs = [c for c in clip_configs if _clip_type_value(c.clip_type) == "outro"]
+
+    result: dict[str, Any] = {}
+
+    if intro_configs:
+        intro = intro_configs[0]
+        intro_cfg = intro.config or {}
+        result["has_intro"] = True
+        result["intro_type"] = intro_cfg.get("intro_type", "text")
+        result["intro_duration"] = getattr(intro, "default_duration", 3.0) or 3.0
+        intro_text = getattr(intro, "text_template", "")
+        if intro_text:
+            result["intro_text"] = intro_text
+        # 透传额外配置
+        for key in (
+            "intro_text_color",
+            "intro_bg_color",
+            "intro_font_size",
+            "intro_video_url",
+            "intro_video_path",
+        ):
+            if key in intro_cfg:
+                result[key] = intro_cfg[key]
+
+    if outro_configs:
+        outro = outro_configs[0]
+        outro_cfg = outro.config or {}
+        result["has_outro"] = True
+        result["outro_type"] = outro_cfg.get("outro_type", "text")
+        result["outro_duration"] = getattr(outro, "default_duration", 3.0) or 3.0
+        outro_text = getattr(outro, "text_template", "")
+        if outro_text:
+            result["outro_text"] = outro_text
+        for key in (
+            "outro_text_color",
+            "outro_bg_color",
+            "outro_font_size",
+            "outro_follow_text",
+        ):
+            if key in outro_cfg:
+                result[key] = outro_cfg[key]
+
+    return result
+
+
+# ── 模板效果层映射 ──────────────────────────────────────────────────────────
+
+
+# 需要从模板复制的效果层 key
+_TEMPLATE_EFFECT_KEYS = (
+    "color_grade",
+    "speed",
+    "playback_speed",
+    "reverse",
+    "chroma_key",
+    "filter",
+)
+
+# 各模式下需要应用效果的 clip_type
+_EFFECT_TARGET_TYPES = {
+    "one_take": {"main"},
+    "pip": {"main", "overlay"},
+    "voice_over": {"main"},
+    "voice_pip": {"background", "b_roll"},
+}
+
+# 作为效果模板池的 clip_type
+_TEMPLATE_SOURCE_TYPES = {"main", "showcase", "b_roll"}
+
+# 不应用效果的 clip_type
+_SKIP_TYPES = {"corner_voice"}
+
+
+def apply_template_clip_effects(
+    clips: list[VirtualClip],
+    clip_configs: list,
+    mode: str,
+) -> None:
+    """将模板的 clip 级效果层映射到素材 clips 上（就地修改）。
+
+    映射规则：
+    - 只对素材主体 clips 做映射
+    - 从模板中筛选 main/showcase/b_roll 类型的 clip_config 作为效果模板
+    - 素材 clips 按顺序循环匹配模板 clip_config（素材多的话重复使用最后一个模板配置）
+    - 映射字段：transition_effect, transition_duration, config 中的效果层
+    """
+    if not clip_configs or not clips:
+        return
+
+    # 筛选 main 类型的模板配置（作为效果模板池）
+    main_configs = [c for c in clip_configs if _clip_type_value(c.clip_type) in _TEMPLATE_SOURCE_TYPES]
+    if not main_configs:
+        return
+
+    # 确定需要映射的素材 clips（排除特殊层）
+    target_clips = [c for c in clips if c.clip_type not in _SKIP_TYPES]
+
+    for i, clip in enumerate(target_clips):
+        # 循环匹配：素材多了用最后一个模板配置
+        cfg_idx = min(i, len(main_configs) - 1)
+        template_cfg = main_configs[cfg_idx]
+
+        # 1. 转场效果 + 时长
+        transition = _transition_value(template_cfg.transition_effect)
+        if transition and transition != "cut":
+            clip.transition_effect = transition
+            # 同步转场时长
+            tpl_cfg = template_cfg.config or {}
+            tpl_duration = tpl_cfg.get("transition_duration")
+            if tpl_duration:
+                try:
+                    dur_val = float(tpl_duration)
+                    if dur_val > 0:
+                        clip.transition_duration = dur_val
+                except (ValueError, TypeError):
+                    pass
+
+        # 2. clip 级效果配置（滤镜、调速等）
+        template_clip_config = template_cfg.config or {}
+        if template_clip_config:
+            existing_config = clip.config or {}
+            for key in _TEMPLATE_EFFECT_KEYS:
+                if key in template_clip_config:
+                    existing_config[key] = template_clip_config[key]
+            clip.config = existing_config
+
+            # 3. 调速：同步到 clip.playback_speed 顶级字段
+            template_speed = template_clip_config.get("playback_speed") or template_clip_config.get("speed")
+            if template_speed:
+                try:
+                    speed_val = float(template_speed)
+                    if speed_val > 0:
+                        clip.playback_speed = speed_val
+                except (ValueError, TypeError):
+                    pass
+
+
+# ── 按模式构建 clips ────────────────────────────────────────────────────────
+
+
+def build_clips_by_mode(
+    plan_id: str,
+    asset_infos: list[dict[str, Any]],
+    mode: str,
+) -> list[VirtualClip]:
+    """根据生成模式和素材信息，构建 VirtualClip 列表。
+
+    纯逻辑版本：不依赖 ffmpeg probe 或 DB，完全由输入数据驱动。
+
+    Args:
+        plan_id: 计划 ID
+        asset_infos: 素材信息列表，每项包含 asset_id / duration / path 等
+        mode: 生成模式 (one_take / pip / voice_over / voice_pip)
+
+    Returns:
+        VirtualClip 列表，按 order 排序
+
+    模式 → clip_type 映射：
+      one_take:     N 个 main clips
+      pip:          1 main + N-1 overlay
+      voice_over:   N 个 main (config.role=b_roll)
+      voice_pip:    1 background + 1 corner_voice + N-2 b_roll
+    """
+    clips: list[VirtualClip] = []
+
+    for i, info in enumerate(asset_infos):
+        asset_id = info.get("asset_id", f"asset_{i:03d}")
+        duration = float(info.get("duration", 0.0))
+
+        if mode == "pip":
+            clip_type = "main" if i == 0 else "overlay"
+            clips.append(
+                VirtualClip(
+                    id=f"vc_{i:03d}",
+                    plan_id=plan_id,
+                    clip_type=clip_type,
+                    order=i,
+                    asset_id=asset_id,
+                    duration=duration,
+                )
+            )
+        elif mode == "voice_over":
+            clips.append(
+                VirtualClip(
+                    id=f"vc_{i:03d}",
+                    plan_id=plan_id,
+                    clip_type="main",
+                    order=i,
+                    asset_id=asset_id,
+                    duration=duration,
+                    config={"role": "b_roll"},
+                )
+            )
+        elif mode == "voice_pip":
+            if i == 0:
+                clip_type = "background"
+            elif i == 1:
+                clip_type = "corner_voice"
+            else:
+                clip_type = "b_roll"
+            clips.append(
+                VirtualClip(
+                    id=f"vc_{i:03d}",
+                    plan_id=plan_id,
+                    clip_type=clip_type,
+                    order=i,
+                    asset_id=asset_id,
+                    duration=duration,
+                )
+            )
+        else:
+            # one_take (default): N 个 main clips
+            clips.append(
+                VirtualClip(
+                    id=f"vc_{i:03d}",
+                    plan_id=plan_id,
+                    clip_type="main",
+                    order=i,
+                    asset_id=asset_id,
+                    duration=duration,
+                )
+            )
+
+    return clips
+
+
+# ── 错误信息构建 ────────────────────────────────────────────────────────────
+
+
+def build_error_info(error: Exception, stage: str = "render") -> dict[str, Any]:
+    """构建结构化错误信息。
+
+    Args:
+        error: 异常对象
+        stage: 发生错误的阶段
+
+    Returns:
+        包含 error_type, message, stack_trace, stage, failed_at 的字典
+    """
+    tb_str = traceback.format_exc()
+    # 截取堆栈前20行，避免字段过大
+    tb_lines = tb_str.strip().splitlines()
+    if len(tb_lines) > 20:
+        tb_summary = "\n".join(tb_lines[:20]) + f"\n... (truncated, total {len(tb_lines)} lines)"
+    else:
+        tb_summary = tb_str
+
+    return {
+        "error_type": type(error).__name__,
+        "message": str(error),
+        "stack_trace": tb_summary,
+        "stage": stage,
+        "failed_at": datetime.now(timezone.utc).isoformat(),
+    }

apps/worker/worker_app/tasks/ingest.py

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

packages/domain/asset_scoring.py

@@ -0,0 +1,372 @@
+"""Asset scoring pure logic — multi-dimensional scoring + diverse selection.
+
+从 smart_asset_selector.py 抽出来的纯逻辑模块：
+- 评分维度：质量分、分辨率、时长、码率（加权求和，总分 0-1）
+- 多样性选择：按时长分桶（短/中/长）保证分布均匀
+- 数据类：AssetScoreDetail, SmartSelectResult
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# ── 评分权重（总和 = 1.0） ────────────────────────────────────────────────────
+
+WEIGHT_QUALITY = 0.5
+WEIGHT_RESOLUTION = 0.2
+WEIGHT_DURATION = 0.2
+WEIGHT_BITRATE = 0.1
+
+# ── 评分参数 ──────────────────────────────────────────────────────────────────
+
+TARGET_WIDTH = 1920  # 目标分辨率宽度基准
+TARGET_HEIGHT = 1080  # 目标分辨率高度基准
+MIN_QUALITY_SCORE = 30.0  # 最低质量分门槛（低于此值的素材直接排除）
+OPTIMAL_DURATION_MIN = 3.0  # 最佳时长区间（秒）
+OPTIMAL_DURATION_MAX = 30.0
+
+# ── 多样性分桶阈值 ───────────────────────────────────────────────────────────
+
+SHORT_BUCKET_MAX = 5.0  # 短素材：< 5s
+MEDIUM_BUCKET_MAX = 15.0  # 中素材：5-15s
+# 长素材：>= 15s
+
+
+# ── 数据类 ───────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class AssetScoreDetail:
+    """单个素材的评分详情."""
+
+    asset_id: str
+    total_score: float
+    quality_score: float
+    resolution_score: float
+    duration_score: float
+    bitrate_score: float
+    duration: float | None
+
+
+@dataclass
+class SmartSelectResult:
+    """智能选择结果."""
+
+    selected_ids: list[str]
+    total_candidates: int
+    filtered_out: int  # 被质量门槛过滤的数量
+    avg_score: float
+    details: list[AssetScoreDetail] = field(default_factory=list)
+
+
+# ── 评分函数 ─────────────────────────────────────────────────────────────────
+
+
+def score_resolution(
+    width: int | None,
+    height: int | None,
+    target_width: int = TARGET_WIDTH,
+    target_height: int = TARGET_HEIGHT,
+) -> float:
+    """分辨率评分：越接近目标分辨率得分越高，低于480p扣分严重.
+
+    Args:
+        width: 素材宽度（像素）
+        height: 素材高度（像素）
+        target_width: 目标宽度
+        target_height: 目标高度
+
+    Returns:
+        0.0 - 1.0 之间的评分
+    """
+    if width is None or height is None or width <= 0 or height <= 0:
+        return 0.5  # 未知分辨率给中评分
+
+    target_pixels = target_width * target_height
+    actual_pixels = width * height
+
+    # 计算像素数比例
+    ratio = actual_pixels / target_pixels
+
+    if ratio >= 1.0:
+        # 高于或等于目标分辨率：满分，略高不扣分（4K也给满分）
+        return 1.0
+    else:
+        # 低于目标分辨率：线性衰减，但最低不低于 0.1
+        score = 0.3 + 0.7 * ratio
+        return max(0.1, min(1.0, score))
+
+
+def score_duration(duration: float | None) -> float:
+    """时长评分：3-30秒最佳，过短或过长都扣分.
+
+    Args:
+        duration: 时长（秒）
+
+    Returns:
+        0.0 - 1.0 之间的评分
+    """
+    if duration is None or duration <= 0:
+        return 0.5  # 未知时长给中评分
+
+    if OPTIMAL_DURATION_MIN <= duration <= OPTIMAL_DURATION_MAX:
+        # 最佳区间：满分
+        return 1.0
+
+    if duration < OPTIMAL_DURATION_MIN:
+        # 太短：线性衰减，趋近于 0.3
+        ratio = duration / OPTIMAL_DURATION_MIN
+        return 0.3 + 0.7 * ratio
+
+    # 太长：每超过最佳区间上限10秒扣 0.1 分，最低 0.2
+    excess = duration - OPTIMAL_DURATION_MAX
+    penalty = min(0.8, excess / 10.0 * 0.1)
+    return max(0.2, 1.0 - penalty)
+
+
+def score_bitrate(file_size: int, duration: float | None) -> float:
+    """码率评分：根据文件大小和时长估算码率，适中得分高.
+
+    Args:
+        file_size: 文件大小（字节）
+        duration: 时长（秒）
+
+    Returns:
+        0.0 - 1.0 之间的评分
+    """
+    if not file_size or not duration or duration <= 0:
+        return 0.5  # 未知给中评分
+
+    # 估算码率（bps）
+    bitrate = (file_size * 8) / duration
+
+    # 最佳码率范围：2-8 Mbps
+    optimal_low = 2_000_000  # 2 Mbps
+    optimal_high = 8_000_000  # 8 Mbps
+
+    if optimal_low <= bitrate <= optimal_high:
+        return 1.0
+
+    if bitrate < optimal_low:
+        # 码率太低：线性衰减
+        ratio = bitrate / optimal_low
+        return 0.3 + 0.7 * ratio
+
+    # 码率太高（文件太大）：适度扣分，最低 0.5
+    excess = bitrate / optimal_high - 1.0
+    penalty = min(0.5, excess * 0.2)
+    return max(0.5, 1.0 - penalty)
+
+
+def calculate_total_score(
+    quality_score: float,
+    resolution_score: float,
+    duration_score: float,
+    bitrate_score: float,
+) -> float:
+    """计算加权总分.
+
+    Args:
+        quality_score: 质量分（0-1）
+        resolution_score: 分辨率分（0-1）
+        duration_score: 时长分（0-1）
+        bitrate_score: 码率分（0-1）
+
+    Returns:
+        加权总分（0-1）
+    """
+    total = (
+        WEIGHT_QUALITY * quality_score
+        + WEIGHT_RESOLUTION * resolution_score
+        + WEIGHT_DURATION * duration_score
+        + WEIGHT_BITRATE * bitrate_score
+    )
+    return round(total, 4)
+
+
+def score_asset_detail(
+    asset_id: str,
+    quality: float | None,
+    width: int | None,
+    height: int | None,
+    duration: float | None,
+    file_size: int,
+    target_width: int = TARGET_WIDTH,
+    target_height: int = TARGET_HEIGHT,
+) -> AssetScoreDetail:
+    """对单个素材进行多维度评分，返回详细评分结果.
+
+    Args:
+        asset_id: 素材ID
+        quality: 质量分（0-100，None表示未知）
+        width: 宽度
+        height: 高度
+        duration: 时长
+        file_size: 文件大小
+        target_width: 目标宽度
+        target_height: 目标高度
+
+    Returns:
+        AssetScoreDetail 评分详情
+    """
+    # 质量分归一化到 0-1
+    quality_score = (quality / 100.0) if quality is not None else 0.5
+
+    resolution_score = score_resolution(width, height, target_width, target_height)
+    duration_score = score_duration(duration)
+    bitrate_score = score_bitrate(file_size, duration)
+
+    total_score = calculate_total_score(
+        quality_score,
+        resolution_score,
+        duration_score,
+        bitrate_score,
+    )
+
+    return AssetScoreDetail(
+        asset_id=asset_id,
+        total_score=total_score,
+        quality_score=round(quality_score, 4),
+        resolution_score=round(resolution_score, 4),
+        duration_score=round(duration_score, 4),
+        bitrate_score=round(bitrate_score, 4),
+        duration=duration,
+    )
+
+
+# ── 多样性选择 ───────────────────────────────────────────────────────────────
+
+
+def _bucket_by_duration(item: AssetScoreDetail) -> str:
+    """根据时长判断所属桶.
+
+    Returns:
+        'short' / 'medium' / 'long' / 'unknown'
+    """
+    if item.duration is None:
+        return "unknown"
+    if item.duration < SHORT_BUCKET_MAX:
+        return "short"
+    if item.duration < MEDIUM_BUCKET_MAX:
+        return "medium"
+    return "long"
+
+
+def diverse_selection(
+    scored: list[AssetScoreDetail],
+    count: int,
+) -> list[AssetScoreDetail]:
+    """多样性选择：按时长分桶，保证每个桶都有素材.
+
+    策略：
+    1. 按时长分为三桶：短(<5s)、中(5-15s)、长(>=15s)
+    2. 每个桶配额 = max(1, count // 3)
+    3. 先从每桶按配额取最高分的
+    4. 剩余名额从全局最高分中取（不重复）
+    5. 如果还不够，加上未知时长的
+
+    Args:
+        scored: 已按总分降序排列的评分列表
+        count: 需要选取的数量
+
+    Returns:
+        选中的评分列表（不超过 count 个）
+    """
+    if count <= 0 or not scored:
+        return []
+
+    # 分桶
+    short_bucket = [d for d in scored if _bucket_by_duration(d) == "short"]
+    medium_bucket = [d for d in scored if _bucket_by_duration(d) == "medium"]
+    long_bucket = [d for d in scored if _bucket_by_duration(d) == "long"]
+    unknown_bucket = [d for d in scored if _bucket_by_duration(d) == "unknown"]
+
+    buckets = [short_bucket, medium_bucket, long_bucket]
+
+    # 每个桶基础配额（至少1个，如果桶非空且需要的话）
+    base_quota = max(1, count // 3)
+
+    selected: list[AssetScoreDetail] = []
+    selected_ids: set[str] = set()
+
+    # 先按配额从每个桶取
+    for bucket in buckets:
+        quota = min(base_quota, len(bucket))
+        if quota <= 0:
+            continue
+        # 桶内已经按分数排好序了，直接取前 quota 个
+        for item in bucket[:quota]:
+            if item.asset_id not in selected_ids:
+                selected.append(item)
+                selected_ids.add(item.asset_id)
+                if len(selected) >= count:
+                    return selected
+
+    # 剩余名额：从全局（未被选中的）中按分数高低取
+    remaining_needed = count - len(selected)
+    if remaining_needed > 0:
+        for item in scored:
+            if item.asset_id not in selected_ids:
+                selected.append(item)
+                selected_ids.add(item.asset_id)
+                if len(selected) >= count:
+                    break
+
+    # 如果还不够（不应该发生），加上未知时长的
+    if len(selected) < count and unknown_bucket:
+        for item in unknown_bucket:
+            if item.asset_id not in selected_ids:
+                selected.append(item)
+                selected_ids.add(item.asset_id)
+                if len(selected) >= count:
+                    break
+
+    return selected[:count]
+
+
+# ── 候选过滤 ─────────────────────────────────────────────────────────────────
+
+
+def filter_candidates(
+    assets: list[Any],
+    min_quality_score: float = MIN_QUALITY_SCORE,
+) -> tuple[list[Any], int]:
+    """从素材列表中筛选出合格的候选素材.
+
+    筛选条件：
+    - status == 'ready'
+    - mime_type 以 'video' 开头
+    - quality_score >= min_quality_score（如果quality不为None）
+
+    Args:
+        assets: 素材列表
+        min_quality_score: 最低质量分门槛
+
+    Returns:
+        (合格素材列表, 被质量门槛过滤的数量)
+    """
+    candidates = []
+    filtered_out = 0
+
+    for asset in assets:
+        # 状态检查
+        status = getattr(asset, "status", None)
+        status_val = status.value if hasattr(status, "value") else str(status)
+        if status_val != "ready":
+            continue
+
+        # 类型检查
+        mime_type = getattr(asset, "mime_type", "") or ""
+        if not mime_type.startswith("video"):
+            continue
+
+        # 质量分门槛
+        quality = getattr(asset, "quality_score", None)
+        if quality is not None and quality < min_quality_score:
+            filtered_out += 1
+            continue
+
+        candidates.append(asset)
+
+    return candidates, filtered_out

packages/domain/clip_operations.py

@@ -0,0 +1,267 @@
+"""片段操作工具 — EditPlanClip 分割/合并等纯逻辑操作。
+
+从 edit_plan_service.py 抽离的纯函数集合，专门负责：
+- 片段分割：将一个片段从指定位置拆分为两个
+- 片段合并：将多个连续片段合并为一个
+- Order 重排计算
+
+所有函数均为纯函数，不依赖数据库或外部 IO。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+# ── 常量 ──────────────────────────────────────────────────────────────────────
+
+DEFAULT_SPLIT_DURATION = 5.0
+ROUND_PRECISION = 3
+
+
+# ── 数据结构 ──────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class SplitResult:
+    """片段分割结果。"""
+
+    left_duration: float
+    right_duration: float
+    right_start_time: float
+    left_trim_end: float
+    right_trim_start: float
+
+
+@dataclass(frozen=True)
+class MergeResult:
+    """片段合并结果。"""
+
+    total_duration: float
+    merged_text: str
+    merged_config: dict[str, Any]
+    first_order: int
+    shift_amount: int
+
+
+# ── 分割 ──────────────────────────────────────────────────────────────────────
+
+
+def validate_split_time(split_time: float, duration: float) -> None:
+    """校验分割时间是否合法。
+
+    Args:
+        split_time: 分割点（秒）
+        duration: 原片段时长（秒）
+
+    Raises:
+        ValueError: 分割时间不在 (0, duration) 范围内
+    """
+    if split_time <= 0 or split_time >= duration:
+        raise ValueError(f"分割时间必须在 (0, {duration:.3f}) 范围内，当前: {split_time}")
+
+
+def calculate_split(
+    duration: float,
+    split_time: float,
+    start_time: float = 0.0,
+    *,
+    precision: int = ROUND_PRECISION,
+) -> SplitResult:
+    """计算片段分割后的各项参数。
+
+    左半部分：从 0 到 split_time
+    右半部分：从 split_time 到 duration
+
+    Args:
+        duration: 原片段时长（秒）
+        split_time: 分割点（秒）
+        start_time: 原片段起始时间（秒），右半部分 start_time 需要加上 left_duration
+        precision: 小数精度（默认 3 位，即毫秒）
+
+    Returns:
+        SplitResult 包含左右部分的时长、右半部分 start_time、trim 信息
+    """
+    validate_split_time(split_time, duration)
+
+    left_duration = round(split_time, precision)
+    right_duration = round(duration - split_time, precision)
+    right_start_time = round(start_time + left_duration, precision)
+
+    return SplitResult(
+        left_duration=left_duration,
+        right_duration=right_duration,
+        right_start_time=right_start_time,
+        left_trim_end=right_duration,
+        right_trim_start=left_duration,
+    )
+
+
+# ── 合并 ──────────────────────────────────────────────────────────────────────
+
+
+def validate_merge_clips(clips: list[Any]) -> tuple[str, int]:
+    """校验待合并的片段列表。
+
+    校验项：
+    1. 至少 2 个片段
+    2. 属于同一计划
+    3. order 连续
+    4. 类型一致
+
+    Args:
+        clips: 按任意顺序排列的片段列表（会自动按 order 排序）
+
+    Returns:
+        (plan_id, first_order) 元组
+
+    Raises:
+        ValueError: 校验失败
+    """
+    if len(clips) < 2:
+        raise ValueError("至少需要 2 个片段才能合并")
+
+    # 校验：同一计划
+    plan_id = clips[0].plan_id
+    for c in clips[1:]:
+        if c.plan_id != plan_id:
+            raise ValueError("只能合并同一计划下的片段")
+
+    # 按 order 排序
+    sorted_clips = sorted(clips, key=lambda c: c.order)
+
+    # 校验：order 连续
+    for i in range(1, len(sorted_clips)):
+        if sorted_clips[i].order != sorted_clips[i - 1].order + 1:
+            raise ValueError(f"片段不连续：order {sorted_clips[i-1].order} → {sorted_clips[i].order}")
+
+    # 校验：类型一致
+    clip_type = sorted_clips[0].clip_type
+    for c in sorted_clips[1:]:
+        if c.clip_type != clip_type:
+            raise ValueError("只能合并相同类型的片段")
+
+    return plan_id, sorted_clips[0].order
+
+
+def calculate_merge(
+    clips: list[Any],
+    *,
+    precision: int = ROUND_PRECISION,
+) -> MergeResult:
+    """计算多个片段合并后的参数。
+
+    合并规则：
+    - 时长：所有片段时长之和
+    - 文案：用换行连接非空文案
+    - config：后面的覆盖前面的，移除 trim_start/trim_end
+    - first_order：第一个片段的 order
+    - shift_amount：合并后 order 前移位数（n-1）
+
+    Args:
+        clips: 待合并片段列表（会自动按 order 排序）
+        precision: 时长精度（默认 3 位）
+
+    Returns:
+        MergeResult 合并结果
+    """
+    if not clips:
+        raise ValueError("合并的片段列表不能为空")
+
+    # 按 order 排序
+    sorted_clips = sorted(clips, key=lambda c: c.order)
+
+    # 总时长
+    total_duration = round(sum(c.duration for c in sorted_clips), precision)
+
+    # 合并文案
+    merged_text = "\n".join(c.text_content for c in sorted_clips if c.text_content and c.text_content.strip())
+
+    # 合并 config（后面的覆盖前面的）
+    merged_config: dict[str, Any] = {}
+    for c in sorted_clips:
+        if c.config:
+            merged_config.update(c.config)
+    # 清理 trim 相关字段（合并后就是完整片段了）
+    merged_config.pop("trim_start", None)
+    merged_config.pop("trim_end", None)
+
+    first_order = sorted_clips[0].order
+    shift_amount = len(sorted_clips) - 1
+
+    return MergeResult(
+        total_duration=total_duration,
+        merged_text=merged_text,
+        merged_config=merged_config,
+        first_order=first_order,
+        shift_amount=shift_amount,
+    )
+
+
+# ── Order 重排 ───────────────────────────────────────────────────────────────
+
+
+def calculate_reorder_new_orders(
+    ordered_ids: list[str],
+    current_items: list[Any],
+    *,
+    id_attr: str = "id",
+    order_attr: str = "order",
+) -> dict[str, int]:
+    """根据新顺序计算每个 item 的新 order 值。
+
+    Args:
+        ordered_ids: 按新顺序排列的 ID 列表
+        current_items: 当前所有 item 列表
+        id_attr: ID 属性名
+        order_attr: order 属性名
+
+    Returns:
+        {item_id: new_order} 映射
+
+    Raises:
+        ValueError: ID 列表与当前 items 不匹配
+    """
+    current_ids = {getattr(c, id_attr) for c in current_items}
+    ordered_id_set = set(ordered_ids)
+
+    if ordered_id_set != current_ids:
+        raise ValueError("ID 列表与当前 items 不匹配")
+
+    return {item_id: idx for idx, item_id in enumerate(ordered_ids)}
+
+
+def calculate_shift_orders(
+    items: list[Any],
+    threshold_order: int,
+    shift: int,
+    *,
+    excluded_ids: set[str] | None = None,
+    order_attr: str = "order",
+    id_attr: str = "id",
+) -> list[tuple[Any, int]]:
+    """计算 order 需要偏移的 items 及新 order 值。
+
+    Args:
+        items: 所有 item 列表
+        threshold_order: 只处理 order > threshold_order 的 item
+        shift: 偏移量（正数加，负数减）
+        excluded_ids: 排除的 ID 集合
+        order_attr: order 属性名
+        id_attr: ID 属性名
+
+    Returns:
+        [(item, new_order), ...] 列表
+    """
+    excluded = excluded_ids or set()
+    result: list[tuple[Any, int]] = []
+
+    for item in items:
+        item_id = getattr(item, id_attr)
+        if item_id in excluded:
+            continue
+        current_order = getattr(item, order_attr)
+        if current_order > threshold_order:
+            result.append((item, current_order + shift))
+
+    return result

packages/domain/media_validation.py

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

packages/domain/plan_generator_utils.py

@@ -0,0 +1,343 @@
+"""剪辑计划生成 — 纯逻辑工具函数.
+
+从 PlanGeneratorService 提取的纯业务逻辑：
+- 素材分配策略（4 种 editing_mode）
+- 默认 clip 结构生成
+- clip_type 按模式映射
+- 从 TemplateClipConfig 创建 EditPlanClip
+
+纯函数，无副作用，不依赖 DB/外部服务。
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from packages.domain.edit_plan_clip import EditPlanClip
+from packages.domain.editing_mode import EditingMode
+from packages.domain.template_clip_config import ClipType, TemplateClipConfig
+
+# ── 默认片段时长（秒） ────────────────────────────────────────────────────────
+DEFAULT_CLIP_DURATION = 5.0
+DEFAULT_INTRO_DURATION = 3.0
+DEFAULT_OUTRO_DURATION = 3.0
+
+
+# ── 素材分配 ────────────────────────────────────────────────────────────────
+
+
+def distribute_assets(
+    clips: List[EditPlanClip],
+    asset_ids: List[str],
+    editing_mode: str,
+) -> None:
+    """按 editing_mode 将素材分配到 clips（就地修改）.
+
+    分配策略:
+    - ONE_TAKE: 素材按顺序依次分配给 main 类型 clips
+    - PIP: 第1个素材→main(全屏背景)，其余→overlay clips
+    - VOICE_OVER: 素材→main clips (B-roll)
+    - VOICE_PIP: 第1个→background, 第2个→corner_voice, 其余→b_roll
+
+    Args:
+        clips: 剪辑片段列表（就地修改 asset_id）
+        asset_ids: 素材 ID 列表
+        editing_mode: 剪辑模式字符串
+    """
+    if not asset_ids or not clips:
+        return
+
+    if editing_mode == EditingMode.ONE_TAKE.value:
+        _distribute_one_take(clips, asset_ids)
+    elif editing_mode == EditingMode.PIP.value:
+        _distribute_pip(clips, asset_ids)
+    elif editing_mode == EditingMode.VOICE_OVER.value:
+        _distribute_voice_over(clips, asset_ids)
+    elif editing_mode == EditingMode.VOICE_PIP.value:
+        _distribute_voice_pip(clips, asset_ids)
+    else:
+        # 未知模式，退化为 one_take
+        _distribute_one_take(clips, asset_ids)
+
+
+def _distribute_one_take(
+    clips: List[EditPlanClip],
+    asset_ids: List[str],
+) -> None:
+    """ONE_TAKE: 素材按顺序依次分配给 main 类型 clips."""
+    main_clips = [c for c in clips if c.clip_type == ClipType.MAIN.value]
+    for i, clip in enumerate(main_clips):
+        if i < len(asset_ids):
+            clip.assign_asset(asset_ids[i])
+
+
+def _distribute_pip(
+    clips: List[EditPlanClip],
+    asset_ids: List[str],
+) -> None:
+    """PIP: 第1个素材→main(全屏背景)，其余→overlay clips."""
+    # 第1个素材 → main clip
+    main_clips = [c for c in clips if c.clip_type == ClipType.MAIN.value]
+    if main_clips and asset_ids:
+        main_clips[0].assign_asset(asset_ids[0])
+
+    # 其余素材 → overlay clips
+    overlay_clips = [c for c in clips if c.clip_type == "overlay"]
+    remaining = asset_ids[1:]
+    for i, clip in enumerate(overlay_clips):
+        if i < len(remaining):
+            clip.assign_asset(remaining[i])
+
+
+def _distribute_voice_over(
+    clips: List[EditPlanClip],
+    asset_ids: List[str],
+) -> None:
+    """VOICE_OVER: 素材→main clips (B-roll)."""
+    main_clips = [c for c in clips if c.clip_type == ClipType.MAIN.value]
+    for i, clip in enumerate(main_clips):
+        if i < len(asset_ids):
+            clip.assign_asset(asset_ids[i])
+
+
+def _distribute_voice_pip(
+    clips: List[EditPlanClip],
+    asset_ids: List[str],
+) -> None:
+    """VOICE_PIP: 第1个→background, 第2个→corner_voice, 其余→b_roll."""
+    bg_clips = [c for c in clips if c.clip_type == "background"]
+    voice_clips = [c for c in clips if c.clip_type == "corner_voice"]
+    broll_clips = [c for c in clips if c.clip_type == "b_roll"]
+
+    idx = 0
+
+    # 第1个 → background
+    if idx < len(asset_ids) and bg_clips:
+        bg_clips[0].assign_asset(asset_ids[idx])
+        idx += 1
+
+    # 第2个 → corner_voice
+    if idx < len(asset_ids) and voice_clips:
+        voice_clips[0].assign_asset(asset_ids[idx])
+        idx += 1
+
+    # 剩余 → b_roll clips
+    remaining = asset_ids[idx:]
+    for i, clip in enumerate(broll_clips):
+        if i < len(remaining):
+            clip.assign_asset(remaining[i])
+
+
+# ── clip_type 映射 ────────────────────────────────────────────────────────
+
+
+def map_clip_types_for_mode(
+    clips: List[EditPlanClip],
+    editing_mode: str,
+) -> None:
+    """将 MAIN 类型片段按 editing_mode 映射为对应角色类型.
+
+    模板的 clip_config 使用 ClipType 枚举（main/intro/outro 等），
+    但 PIP / VOICE_PIP 模式的素材分配和渲染分层依赖特定的 clip_type 命名
+    （overlay / background / corner_voice / b_roll）。
+
+    映射规则（仅修改 MAIN 类型片段，非 MAIN 片段保持原类型）：
+    - PIP: 第1个 MAIN → main（背景），其余 MAIN → overlay（画中画）
+    - VOICE_PIP: 第1个 → background，第2个 → corner_voice，第3+个 → b_roll
+    - ONE_TAKE / VOICE_OVER: 保持 main 不变
+
+    Args:
+        clips: 剪辑片段列表（就地修改 clip_type）
+        editing_mode: 剪辑模式字符串
+    """
+    main_clips = [c for c in clips if c.clip_type == ClipType.MAIN.value]
+    if not main_clips:
+        return
+
+    if editing_mode == EditingMode.PIP.value:
+        # 第1个 main 保持（背景层），其余改为 overlay（画中画层）
+        for i, clip in enumerate(main_clips):
+            if i > 0:
+                clip.clip_type = "overlay"
+
+    elif editing_mode == EditingMode.VOICE_PIP.value:
+        for i, clip in enumerate(main_clips):
+            if i == 0:
+                clip.clip_type = "background"
+            elif i == 1:
+                clip.clip_type = "corner_voice"
+            else:
+                clip.clip_type = "b_roll"
+
+    # ONE_TAKE / VOICE_OVER: 保持 main 不变，无需处理
+
+
+# ── 默认 clip 生成 ────────────────────────────────────────────────────────
+
+
+def generate_default_clips(
+    plan_id: str,
+    editing_mode: str,
+    asset_count: int,
+) -> List[EditPlanClip]:
+    """无 clip_configs 时，根据 editing_mode 生成默认 clip 结构.
+
+    - ONE_TAKE: N 个 main clips（N = asset_count，至少1个）
+    - PIP: 1 个 main + (N-1) 个 overlay（N = asset_count）
+    - VOICE_OVER: N 个 main clips + 标记需要配音
+    - VOICE_PIP: 1 个 background + 1 个 corner_voice + (N-2) 个 b_roll
+
+    Args:
+        plan_id: 剪辑计划 ID
+        editing_mode: 剪辑模式字符串
+        asset_count: 素材数量
+
+    Returns:
+        List[EditPlanClip]: 生成的默认剪辑片段列表
+    """
+    n = max(asset_count, 1)
+    clips: List[EditPlanClip] = []
+    order = 0
+
+    if editing_mode == EditingMode.PIP.value:
+        # 1 个 main（全屏背景）
+        clips.append(
+            EditPlanClip.create(
+                plan_id=plan_id,
+                clip_type=ClipType.MAIN.value,
+                order=order,
+                duration=DEFAULT_CLIP_DURATION,
+            )
+        )
+        order += 1
+        # 剩余为 overlay
+        for _ in range(1, n):
+            clips.append(
+                EditPlanClip.create(
+                    plan_id=plan_id,
+                    clip_type="overlay",
+                    order=order,
+                    duration=DEFAULT_CLIP_DURATION,
+                )
+            )
+            order += 1
+
+    elif editing_mode == EditingMode.VOICE_OVER.value:
+        # N 个 main clips（B-roll）
+        for _ in range(n):
+            clips.append(
+                EditPlanClip.create(
+                    plan_id=plan_id,
+                    clip_type=ClipType.MAIN.value,
+                    order=order,
+                    duration=DEFAULT_CLIP_DURATION,
+                    config={"role": "b_roll"},
+                )
+            )
+            order += 1
+
+    elif editing_mode == EditingMode.VOICE_PIP.value:
+        # 1 个 background
+        clips.append(
+            EditPlanClip.create(
+                plan_id=plan_id,
+                clip_type="background",
+                order=order,
+                duration=DEFAULT_CLIP_DURATION,
+            )
+        )
+        order += 1
+        # 1 个 corner_voice（至少有1个素材就有）
+        if n >= 2:
+            clips.append(
+                EditPlanClip.create(
+                    plan_id=plan_id,
+                    clip_type="corner_voice",
+                    order=order,
+                    duration=DEFAULT_CLIP_DURATION,
+                )
+            )
+            order += 1
+        # 剩余为 b_roll
+        for _ in range(2, n):
+            clips.append(
+                EditPlanClip.create(
+                    plan_id=plan_id,
+                    clip_type="b_roll",
+                    order=order,
+                    duration=DEFAULT_CLIP_DURATION,
+                )
+            )
+            order += 1
+
+    else:
+        # ONE_TAKE / 未知模式：N 个 main clips
+        for _ in range(n):
+            clips.append(
+                EditPlanClip.create(
+                    plan_id=plan_id,
+                    clip_type=ClipType.MAIN.value,
+                    order=order,
+                    duration=DEFAULT_CLIP_DURATION,
+                )
+            )
+            order += 1
+
+    return clips
+
+
+# ── 从配置创建 clips ────────────────────────────────────────────────────────
+
+
+def create_clips_from_configs(
+    plan_id: str,
+    clip_configs: List[TemplateClipConfig],
+) -> List[EditPlanClip]:
+    """从 TemplateClipConfig 列表创建 EditPlanClip 列表.
+
+    Args:
+        plan_id: 剪辑计划 ID
+        clip_configs: 模板片段配置列表
+
+    Returns:
+        List[EditPlanClip]: 创建的剪辑片段列表（按 order 排序）
+    """
+    clips: List[EditPlanClip] = []
+    # 按 order 排序
+    sorted_configs = sorted(clip_configs, key=lambda c: c.order)
+
+    for cfg in sorted_configs:
+        # 计算时长：取 min_duration 和 max_duration 的中间值
+        if cfg.min_duration > 0 and cfg.max_duration > 0:
+            duration = (cfg.min_duration + cfg.max_duration) / 2
+        elif cfg.min_duration > 0:
+            duration = cfg.min_duration
+        elif cfg.max_duration > 0:
+            duration = cfg.max_duration
+        else:
+            duration = DEFAULT_CLIP_DURATION
+
+        # clip_type 可能是枚举或字符串
+        clip_type = cfg.clip_type.value if hasattr(cfg.clip_type, "value") else cfg.clip_type
+
+        # transition_effect 可能是枚举或字符串
+        transition = cfg.transition_effect.value if hasattr(cfg.transition_effect, "value") else cfg.transition_effect
+
+        # 从 clip config 中解析 playback_speed（兼容 speed_ratio 字段名）
+        clip_cfg = cfg.config or {}
+        playback_speed = clip_cfg.get("playback_speed", clip_cfg.get("speed_ratio", 1.0)) or 1.0
+
+        clip = EditPlanClip.create(
+            plan_id=plan_id,
+            clip_type=clip_type,
+            order=cfg.order,
+            template_clip_config_id=cfg.id,
+            text_content=getattr(cfg, "text_template", "") or "",
+            duration=duration,
+            transition_effect=transition or "cut",
+            playback_speed=playback_speed,
+            config=clip_cfg,
+        )
+        clips.append(clip)
+
+    return clips

packages/domain/render_layer_utils.py

@@ -0,0 +1,241 @@
+"""渲染图层工具函数 — 纯函数集合.
+
+从 unified_render_service.py 抽离的纯逻辑，负责：
+- clip 时长计算（有效时长、调速后时长）
+- clip_type → layer_role 映射
+- 总时长估算
+- 图层默认属性（z_index 等）
+
+所有函数均为纯函数，不依赖 FFmpeg、数据库或外部 IO。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# ── 图层角色定义 ─────────────────────────────────────────────────────────────
+
+# 图层默认 z_index 映射
+LAYER_Z_INDEX: dict[str, int] = {
+    "background": -1,
+    "broll": 0,
+    "main": 0,
+    "overlay": 1,
+    "corner_voice": 1,
+    "audio": 2,
+}
+
+# 图层默认 PiP 缩放比例（相对于主画面）
+PIP_DEFAULT_SCALE = 0.25
+
+# 主视频图层角色（用于总时长计算、直通判断等）
+MAIN_LAYER_ROLES = frozenset({"main", "broll", "background"})
+
+
+# ── clip_type → layer_role 映射 ──────────────────────────────────────────────
+
+
+def resolve_layer_role(clip_type: str, config: dict[str, Any] | None = None) -> str:
+    """根据 clip_type 和 config.role 确定图层角色。
+
+    映射规则：
+      intro / outro         → "main"（按 order 排在首/尾）
+      overlay                → "overlay"（画中画叠加，z=1）
+      corner_voice           → "corner_voice"（右上角小窗，z=1）
+      background             → "background"（全屏底图，z=0）
+      b_roll                 → "broll"（z=0）
+      main + config.role=b_roll → "broll"
+      main + config.role=audio  → "audio"
+      main (default)         → "main"
+
+    Args:
+        clip_type: 片段类型字符串
+        config: 片段配置字典（可选）
+
+    Returns:
+        图层角色字符串
+    """
+    role = (config or {}).get("role", "") if config else ""
+
+    if clip_type in ("intro", "outro"):
+        return "main"
+    if clip_type == "overlay":
+        return "overlay"
+    if clip_type == "corner_voice":
+        return "corner_voice"
+    if clip_type == "background":
+        return "background"
+    if clip_type == "b_roll":
+        return "broll"
+    # main type
+    if role == "b_roll":
+        return "broll"
+    if role == "audio":
+        return "audio"
+    return "main"
+
+
+def get_layer_z_index(role: str) -> int:
+    """获取图层角色的默认 z_index。
+
+    Args:
+        role: 图层角色
+
+    Returns:
+        z_index 值，未知角色返回 0
+    """
+    return LAYER_Z_INDEX.get(role, 0)
+
+
+# ── clip 时长计算 ──────────────────────────────────────────────────────────
+
+
+def clip_effective_duration(
+    duration: float,
+    actual_duration: float = 0.0,
+) -> float:
+    """计算 clip 的有效时长（原速 trim 后时长）。
+
+    规则：
+    - duration > 0: min(duration, actual_duration)，actual=0 时用 duration
+    - duration <= 0: actual_duration，actual=0 时返回 0
+
+    Args:
+        duration: 配置的时长（0 表示使用完整素材）
+        actual_duration: 素材实际时长（probe 后的结果）
+
+    Returns:
+        有效时长（秒）
+    """
+    if duration > 0:
+        return min(duration, actual_duration) if actual_duration > 0 else duration
+    return actual_duration if actual_duration > 0 else 0.0
+
+
+def clip_playback_speed(playback_speed: Any) -> float:
+    """获取 clip 的播放速度，无效值回退到 1.0。
+
+    Args:
+        playback_speed: 播放速度（可为任意类型
+
+    Returns:
+        有效的播放速度（正数）
+    """
+    if not isinstance(playback_speed, (int, float)):
+        return 1.0
+    if playback_speed <= 0:
+        return 1.0
+    return float(playback_speed)
+
+
+def clip_adjusted_duration(
+    duration: float,
+    actual_duration: float = 0.0,
+    playback_speed: Any = 1.0,
+) -> float:
+    """计算调速后的 clip 实际时长（用于拼接计算）。
+
+    Args:
+        duration: 配置的时长
+        actual_duration: 素材实际时长
+        playback_speed: 播放速度
+
+    Returns:
+        调速后的时长
+    """
+    base = clip_effective_duration(duration, actual_duration)
+    speed = clip_playback_speed(playback_speed)
+    if abs(speed - 1.0) < 1e-6:
+        return base
+    return base / speed
+
+
+# ── 总时长估算 ────────────────────────────────────────────────────────────
+
+
+def estimate_total_duration(
+    layers: list[Any],
+    transition_duration: float = 0.0,
+) -> float:
+    """估算视频总时长。
+
+    取主图层（main/broll/background）的总调整后时长，减去转场重叠时间。
+
+    Args:
+        layers: 图层列表（每个元素需有 role 和 clips 属性，
+                clips 中元素需有 duration/actual_duration/playback_speed 属性）
+        transition_duration: 转场时长（秒），用于估算重叠时间
+
+    Returns:
+        估算的总时长（秒），最小 0.1
+    """
+    # 找主图层（第一个有视频内容的图层）
+    main_layer = None
+    for role in ("main", "broll", "background"):
+        for layer in layers:
+            if getattr(layer, "role", None) == role and getattr(layer, "clips", None):
+                main_layer = layer
+                break
+        if main_layer:
+            break
+
+    if not main_layer or not getattr(main_layer, "clips", None):
+        return 0.0
+
+    clips = getattr(main_layer, "clips", [])
+    total = sum(
+        clip_adjusted_duration(
+            duration=getattr(c, "duration", 0),
+            actual_duration=getattr(c, "actual_duration", 0.0),
+            playback_speed=getattr(c, "playback_speed", 1.0),
+        )
+        for c in clips
+    )
+
+    # 减去转场重叠时间（粗略估算）
+    n_clips = len(clips)
+    if n_clips > 1 and transition_duration > 0:
+        total -= (n_clips - 1) * transition_duration
+
+    return max(0.1, total)
+
+
+# ── 直通 / Stream Copy 判断辅助 ──────────────────────────────────────────────
+
+
+def can_pass_through(
+    layers: list[Any],
+    has_stickers: bool = False,
+    has_watermark: bool = False,
+) -> bool:
+    """判断是否可以走直通优化路径（单 clip 简单场景）。
+
+    条件：
+    1. 只有 1 个图层
+    2. 该图层是视频图层（main/broll/background）
+    3. 该图层只有 1 个 clip（无转场需求）
+    4. 没有贴纸
+    5. 没有水印
+
+    Args:
+        layers: 图层列表
+        has_stickers: 是否有贴纸
+        has_watermark: 是否有水印
+
+    Returns:
+        是否可以走直通
+    """
+    if len(layers) != 1:
+        return False
+    layer = layers[0]
+    role = getattr(layer, "role", "")
+    if role not in MAIN_LAYER_ROLES:
+        return False
+    clips = getattr(layer, "clips", [])
+    if len(clips) != 1:
+        return False
+    if has_stickers:
+        return False
+    if has_watermark:
+        return False
+    return True

packages/domain/subtitle_style.py

@@ -0,0 +1,272 @@
+"""字幕样式领域模型 — 纯逻辑，无外部依赖.
+
+抽离自 subtitle_render_engine.py 的数据类和工具函数，
+方便单测覆盖，同时保持向后兼容。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# ── 常量 ──────────────────────────────────────────────────────────────────────
+
+# 9宫格位置映射（ASS alignment 编号）
+POSITION_ALIGNMENT: dict[str, int] = {
+    "top_left": 7,
+    "top_center": 8,
+    "top_right": 9,
+    "middle_left": 4,
+    "center": 5,
+    "middle_right": 6,
+    "bottom_left": 1,
+    "bottom_center": 2,
+    "bottom_right": 3,
+}
+
+# 位置简称兼容
+POSITION_ALIASES: dict[str, str] = {
+    "top": "top_center",
+    "bottom": "bottom_center",
+    "middle": "center",
+    "left": "middle_left",
+    "right": "middle_right",
+}
+
+DEFAULT_FONT = "思源黑体"
+DEFAULT_FONT_SIZE = 24
+DEFAULT_COLOR = "#FFFFFF"
+DEFAULT_STROKE_COLOR = "#000000"
+DEFAULT_STROKE_WIDTH = 1.5
+DEFAULT_POSITION = "bottom_center"
+DEFAULT_MAX_CHARS_PER_LINE = 20
+
+ALLOWED_SUBTITLE_EXTENSIONS = {".srt", ".ass", ".vtt", ".sub"}
+
+
+# ── 工具函数 ──────────────────────────────────────────────────────────────────
+
+
+def hex_to_ass_color(hex_color: str) -> str:
+    """HEX → ASS 颜色 &HAABBGGRR（默认不透明）."""
+    hex_color = hex_color.lstrip("#")
+    if len(hex_color) != 6:
+        return "&H00FFFFFF"
+    r, g, b = hex_color[0:2], hex_color[2:4], hex_color[4:6]
+    return f"&H00{b.upper()}{g.upper()}{r.upper()}"
+
+
+def hex_to_ass_bgr(hex_color: str) -> str:
+    """HEX → ASS BGR 部分（不含 alpha）."""
+    hex_color = hex_color.lstrip("#")
+    if len(hex_color) != 6:
+        return "FFFFFF"
+    r, g, b = hex_color[0:2], hex_color[2:4], hex_color[4:6]
+    return f"{b.upper()}{g.upper()}{r.upper()}"
+
+
+def opacity_to_ass_alpha(opacity: float) -> str:
+    """不透明度 → ASS alpha（00=不透明，FF=完全透明）."""
+    alpha = 255 - int(max(0.0, min(1.0, opacity)) * 255)
+    return f"{alpha:02X}"
+
+
+def escape_ass_text(text: str) -> str:
+    """转义 ASS 文本特殊字符."""
+    text = text.replace("\r\n", "\\N").replace("\n", "\\N").replace("\r", "\\N")
+    text = text.replace("{", "(").replace("}", ")")
+    return text
+
+
+def format_ass_time(seconds: float) -> str:
+    """秒 → ASS 时间格式 H:MM:SS.cc."""
+    if seconds < 0:
+        seconds = 0.0
+    hours = int(seconds // 3600)
+    minutes = int((seconds % 3600) // 60)
+    secs = seconds % 60
+    return f"{hours}:{minutes:02d}:{secs:05.2f}"
+
+
+def wrap_text(text: str, max_chars: int) -> list[str]:
+    """按字数换行，优先标点断开."""
+    if max_chars <= 0:
+        return [text]
+    if not text or len(text) <= max_chars:
+        return [text]
+
+    lines: list[str] = []
+    remaining = text
+    punctuations = "，。！？、；：,.;:!?"
+
+    while len(remaining) > max_chars:
+        break_point = max_chars
+        # 在 max_chars 到 max_chars//2 之间寻找标点断点
+        for i in range(max_chars, max_chars // 2, -1):
+            if i < len(remaining) and remaining[i] in punctuations:
+                break_point = i + 1
+                break
+
+        lines.append(remaining[:break_point])
+        remaining = remaining[break_point:]
+
+    if remaining:
+        lines.append(remaining)
+
+    return lines
+
+
+# ── 字幕样式配置 ────────────────────────────────────────────────────────────
+
+
+@dataclass
+class SubtitleStyle:
+    """字幕样式配置."""
+
+    font_name: str = DEFAULT_FONT
+    font_size: int = DEFAULT_FONT_SIZE
+    font_color: str = DEFAULT_COLOR
+    bold: bool = False
+    italic: bool = False
+
+    # 描边
+    stroke_enabled: bool = True
+    stroke_color: str = DEFAULT_STROKE_COLOR
+    stroke_width: float = DEFAULT_STROKE_WIDTH
+
+    # 阴影
+    shadow_enabled: bool = False
+    shadow_color: str = "#000000"
+    shadow_offset_x: int = 2
+    shadow_offset_y: int = 2
+    shadow_blur: float = 0.0
+
+    # 背景框
+    background_enabled: bool = False
+    background_color: str = "#000000"
+    background_opacity: float = 0.5
+    background_padding: int = 8
+    background_radius: int = 4
+
+    # 位置
+    position: str = DEFAULT_POSITION
+    margin_v: int = 60
+    margin_l: int = 40
+    margin_r: int = 40
+
+    # 多行
+    max_chars_per_line: int = DEFAULT_MAX_CHARS_PER_LINE
+    line_spacing: int = 0
+
+    # 动画
+    fade_in: float = 0.0
+    fade_out: float = 0.0
+    animation_type: str = "none"
+
+    @classmethod
+    def from_dict(cls, config: dict[str, Any] | None) -> "SubtitleStyle":
+        """从字典创建样式配置，带安全类型转换."""
+        if not config or not isinstance(config, dict):
+            return cls()
+
+        def safe_str(key: str, default: str) -> str:
+            val = config.get(key, default)
+            return str(val) if val is not None else default
+
+        def safe_int(key: str, default: int) -> int:
+            try:
+                return int(config.get(key, default))
+            except (TypeError, ValueError):
+                return default
+
+        def safe_float(key: str, default: float) -> float:
+            try:
+                return float(config.get(key, default))
+            except (TypeError, ValueError):
+                return default
+
+        def safe_bool(key: str, default: bool) -> bool:
+            return bool(config.get(key, default))
+
+        position = safe_str("position", DEFAULT_POSITION)
+        position = POSITION_ALIASES.get(position, position)
+        if position not in POSITION_ALIGNMENT:
+            position = DEFAULT_POSITION
+
+        return cls(
+            font_name=safe_str("font", DEFAULT_FONT),
+            font_size=safe_int("size", DEFAULT_FONT_SIZE),
+            font_color=safe_str("color", DEFAULT_COLOR),
+            bold=safe_bool("bold", False),
+            italic=safe_bool("italic", False),
+            stroke_enabled=safe_bool("stroke_enabled", True),
+            stroke_color=safe_str("stroke_color", DEFAULT_STROKE_COLOR),
+            stroke_width=safe_float("stroke_width", DEFAULT_STROKE_WIDTH),
+            shadow_enabled=safe_bool("shadow_enabled", False),
+            shadow_color=safe_str("shadow_color", "#000000"),
+            shadow_offset_x=safe_int("shadow_offset_x", 2),
+            shadow_offset_y=safe_int("shadow_offset_y", 2),
+            shadow_blur=safe_float("shadow_blur", 0.0),
+            background_enabled=safe_bool("background_enabled", False),
+            background_color=safe_str("background_color", "#000000"),
+            background_opacity=max(0.0, min(1.0, safe_float("background_opacity", 0.5))),
+            background_padding=safe_int("background_padding", 8),
+            background_radius=safe_int("background_radius", 4),
+            position=position,
+            margin_v=safe_int("margin_v", 60),
+            margin_l=safe_int("margin_l", 40),
+            margin_r=safe_int("margin_r", 40),
+            max_chars_per_line=safe_int("max_chars_per_line", DEFAULT_MAX_CHARS_PER_LINE),
+            line_spacing=safe_int("line_spacing", 0),
+            fade_in=max(0.0, safe_float("fade_in", 0.0)),
+            fade_out=max(0.0, safe_float("fade_out", 0.0)),
+            animation_type=safe_str("animation_type", "none"),
+        )
+
+    @property
+    def alignment(self) -> int:
+        """获取 ASS alignment 编号."""
+        return POSITION_ALIGNMENT.get(self.position, 2)
+
+    @property
+    def ass_font_color(self) -> str:
+        """ASS 格式颜色 &HAABBGGRR."""
+        return hex_to_ass_color(self.font_color)
+
+    @property
+    def ass_stroke_color(self) -> str:
+        return hex_to_ass_color(self.stroke_color)
+
+    @property
+    def ass_shadow_color(self) -> str:
+        return hex_to_ass_color(self.shadow_color)
+
+    @property
+    def ass_background_color(self) -> str:
+        """背景框颜色（ASS BackColour），带透明度."""
+        alpha_hex = opacity_to_ass_alpha(self.background_opacity)
+        color_bgr = hex_to_ass_bgr(self.background_color)
+        return f"&H{alpha_hex}{color_bgr}"
+
+
+# ── 字幕片段 ──────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class SubtitleSegment:
+    """单个字幕片段."""
+
+    start: float  # 开始时间（秒）
+    end: float  # 结束时间（秒）
+    text: str  # 字幕文本
+    style_name: str = "Default"  # 使用的样式名
+
+    @property
+    def duration(self) -> float:
+        """字幕时长."""
+        return max(0.0, self.end - self.start)
+
+    @property
+    def is_valid(self) -> bool:
+        """是否有效（有文本且时长>0）."""
+        return bool(self.text) and self.end > self.start

packages/domain/template_clip_converter.py

@@ -0,0 +1,293 @@
+"""模板片段转换器 — 纯函数集合.
+
+从 edit_template_service.py 抽离的纯逻辑，负责在不同数据形态间转换：
+- 剪辑计划片段 (EditPlanClip) → 模板片段配置 (TemplateClipConfig)
+- 模板片段配置 → 版本快照 dict
+- 版本快照 dict → 模板片段配置
+- 计划 config → 模板 config（过滤运行时字段）
+
+所有函数均为纯函数，不依赖数据库或外部 IO。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from packages.domain.template_clip_config import (
+    ClipType,
+    TemplateClipConfig,
+    TransitionEffect,
+)
+
+# ── 安全枚举解析 ────────────────────────────────────────────────────────────
+
+
+def safe_parse_transition_effect(value: Any, default: TransitionEffect = TransitionEffect.CUT) -> TransitionEffect:
+    """安全解析转场效果枚举，解析失败返回默认值。
+
+    Args:
+        value: 待解析的值（枚举、字符串或其他）
+        default: 解析失败时的默认值
+
+    Returns:
+        TransitionEffect 枚举值
+    """
+    if isinstance(value, TransitionEffect):
+        return value
+    try:
+        return TransitionEffect(value)
+    except (ValueError, TypeError):
+        return default
+
+
+def safe_parse_clip_type(value: Any, default: ClipType = ClipType.MAIN) -> ClipType:
+    """安全解析片段类型枚举，解析失败返回默认值。
+
+    Args:
+        value: 待解析的值（枚举、字符串或其他）
+        default: 解析失败时的默认值
+
+    Returns:
+        ClipType 枚举值
+    """
+    if isinstance(value, ClipType):
+        return value
+    try:
+        return ClipType(value)
+    except (ValueError, TypeError):
+        return default
+
+
+# ── Config 字段过滤 ─────────────────────────────────────────────────────────
+
+# 默认需要从 clip config 中移除的素材/运行时字段
+_DEFAULT_CLIP_CONFIG_SKIP_KEYS = frozenset(
+    {
+        "asset_info",
+        "source_asset_id",
+    }
+)
+
+# 默认需要从 plan config 中移除的运行时/实例字段
+_DEFAULT_PLAN_CONFIG_SKIP_KEYS = frozenset(
+    {
+        "is_template_draft",
+        "asset_ids",
+        "source_edit_plan_id",
+        "generation_task_id",
+    }
+)
+
+
+def filter_clip_config(
+    clip_config: dict[str, Any] | None,
+    playback_speed: float | None = None,
+    skip_keys: frozenset[str] | None = None,
+) -> dict[str, Any]:
+    """构建模板片段的 config 字典。
+
+    处理逻辑：
+    1. 如果 playback_speed 存在且不等于 1.0，加入 config
+    2. 合并 clip 自身的 config
+    3. 移除素材相关字段
+
+    Args:
+        clip_config: 原始片段 config（可为 None）
+        playback_speed: 播放速度（可选，1.0 时不写入）
+        skip_keys: 需要跳过的字段集合（None 时用默认）
+
+    Returns:
+        过滤后的 config 字典
+    """
+    skip = skip_keys if skip_keys is not None else _DEFAULT_CLIP_CONFIG_SKIP_KEYS
+    result: dict[str, Any] = {}
+
+    if playback_speed is not None and playback_speed != 1.0:
+        result["playback_speed"] = playback_speed
+
+    if clip_config:
+        result.update(clip_config)
+
+    for key in skip:
+        result.pop(key, None)
+
+    return result
+
+
+def filter_plan_config_to_template(
+    plan_config: dict[str, Any] | None,
+    skip_keys: frozenset[str] | None = None,
+) -> dict[str, Any]:
+    """从计划 config 中提取模板 config（过滤运行时/实例字段）。
+
+    Args:
+        plan_config: 原始计划 config（可为 None）
+        skip_keys: 需要跳过的字段集合（None 时用默认）
+
+    Returns:
+        过滤后的模板 config
+    """
+    skip = skip_keys if skip_keys is not None else _DEFAULT_PLAN_CONFIG_SKIP_KEYS
+    if not plan_config:
+        return {}
+    return {k: v for k, v in plan_config.items() if k not in skip}
+
+
+# ── Clip → TemplateClipConfig 转换 ────────────────────────────────────────
+
+
+def clip_to_template_clip_config(
+    template_id: str,
+    clip: Any,
+) -> TemplateClipConfig:
+    """将剪辑计划片段转换为模板片段配置。
+
+    转换规则：
+    - clip_type → 安全解析后映射
+    - order → 保持不变
+    - duration → min_duration = max_duration = duration（固定时长）
+    - text_content → text_template
+    - transition_effect → 安全解析后映射
+    - playback_speed → 存入 config（非 1.0 时）
+    - clip.config → 合并入 config（过滤素材字段）
+
+    Args:
+        template_id: 目标模板 ID
+        clip: 源片段对象（需有 clip_type/order/duration/text_content/
+              transition_effect/playback_speed/config 属性）
+
+    Returns:
+        新创建的 TemplateClipConfig 实例
+    """
+    clip_type = safe_parse_clip_type(getattr(clip, "clip_type", None))
+    transition = safe_parse_transition_effect(getattr(clip, "transition_effect", None))
+
+    config = filter_clip_config(
+        getattr(clip, "config", None),
+        playback_speed=getattr(clip, "playback_speed", None),
+    )
+
+    duration = getattr(clip, "duration", 0.0) or 0.0
+
+    return TemplateClipConfig.create(
+        template_id=template_id,
+        clip_type=clip_type,
+        order=getattr(clip, "order", 0),
+        min_duration=duration,
+        max_duration=duration,
+        text_template=getattr(clip, "text_content", "") or "",
+        transition_effect=transition,
+        config=config,
+    )
+
+
+def clips_to_template_clip_configs(
+    template_id: str,
+    clips: list[Any],
+) -> list[TemplateClipConfig]:
+    """批量将剪辑计划片段转换为模板片段配置列表。
+
+    Args:
+        template_id: 目标模板 ID
+        clips: 源片段对象列表
+
+    Returns:
+        TemplateClipConfig 实例列表
+    """
+    return [clip_to_template_clip_config(template_id, c) for c in clips]
+
+
+# ── TemplateClipConfig → Snapshot 转换 ────────────────────────────────────
+
+
+def _enum_value(value: Any) -> Any:
+    """获取枚举的 value 值（兼容枚举和字符串）。"""
+    if hasattr(value, "value"):
+        return value.value
+    return value
+
+
+def clip_config_to_snapshot(cfg: Any) -> dict[str, Any]:
+    """将模板片段配置转换为版本快照 dict。
+
+    Args:
+        cfg: TemplateClipConfig 对象（或有对应属性的对象）
+
+    Returns:
+        快照字典，包含 clip_type/order/min_duration/max_duration/
+        text_template/transition_effect/config
+    """
+    return {
+        "clip_type": _enum_value(getattr(cfg, "clip_type", None)),
+        "order": getattr(cfg, "order", 0),
+        "min_duration": getattr(cfg, "min_duration", 0.0),
+        "max_duration": getattr(cfg, "max_duration", 0.0),
+        "text_template": getattr(cfg, "text_template", "") or "",
+        "transition_effect": _enum_value(getattr(cfg, "transition_effect", None)),
+        "config": dict(getattr(cfg, "config", {}) or {}),
+    }
+
+
+def clip_configs_to_snapshots(configs: list[Any]) -> list[dict[str, Any]]:
+    """批量将模板片段配置转换为版本快照列表。"""
+    return [clip_config_to_snapshot(c) for c in configs]
+
+
+# ── Snapshot → TemplateClipConfig 转换 ────────────────────────────────────
+
+
+def snapshot_to_template_clip_config(
+    template_id: str,
+    snapshot: dict[str, Any],
+) -> TemplateClipConfig:
+    """将版本快照 dict 转换为模板片段配置。
+
+    Args:
+        template_id: 目标模板 ID
+        snapshot: 快照字典
+
+    Returns:
+        新创建的 TemplateClipConfig 实例
+    """
+    clip_type = safe_parse_clip_type(snapshot.get("clip_type", "main"))
+    transition = safe_parse_transition_effect(snapshot.get("transition_effect", "cut"))
+
+    return TemplateClipConfig.create(
+        template_id=template_id,
+        clip_type=clip_type,
+        order=snapshot.get("order", 0),
+        min_duration=snapshot.get("min_duration", 0.0),
+        max_duration=snapshot.get("max_duration", 0.0),
+        text_template=snapshot.get("text_template", ""),
+        transition_effect=transition,
+        config=dict(snapshot.get("config", {}) or {}),
+    )
+
+
+def snapshots_to_template_clip_configs(
+    template_id: str,
+    snapshots: list[dict[str, Any]],
+) -> list[TemplateClipConfig]:
+    """批量将版本快照转换为模板片段配置列表。"""
+    return [snapshot_to_template_clip_config(template_id, s) for s in snapshots]
+
+
+# ── 名称校验工具 ──────────────────────────────────────────────────────────
+
+
+def validate_template_name(name: str | None) -> str:
+    """校验并清洗模板名称。
+
+    Args:
+        name: 原始名称
+
+    Returns:
+        清洗后的名称（去除首尾空格）
+
+    Raises:
+        ValueError: 名称为空
+    """
+    clean_name = name.strip() if name else ""
+    if not clean_name:
+        raise ValueError("模板名称不能为空")
+    return clean_name

packages/domain/video_concat.py

@@ -0,0 +1,177 @@
+"""视频拼接领域模型 — 纯逻辑，无外部依赖.
+
+抽离自 concat_engine.py 的数据类和配置解析逻辑，
+方便单测覆盖，同时保持向后兼容。
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# ── 常量 ──────────────────────────────────────────────────────────────────────
+
+MAX_CONCAT_SEGMENTS = 50  # 最大拼接段数（安全上限，防止OOM）
+
+ALLOWED_VIDEO_EXTENSIONS = {".mp4", ".mov", ".avi", ".mkv", ".webm", ".flv", ".wmv"}
+
+# concat demuxer 要求一致的参数列表
+CONCAT_DEMUXER_REQUIRED_PARAMS = [
+    "codec_name",
+    "width",
+    "height",
+    "r_frame_rate",
+    "pix_fmt",
+    "sample_rate",
+    "channels",
+    "audio_codec",
+]
+
+
+# ── 拼接片段配置 ──────────────────────────────────────────────────────────────
+
+
+@dataclass
+class ConcatSegment:
+    """单个拼接片段."""
+
+    video_path: str  # 视频文件路径
+    start_time: float = 0.0  # 开始时间（秒）
+    duration: float = 0.0  # 持续时长（秒），0表示取到末尾
+    has_audio: bool = True  # 是否包含音频
+
+    @classmethod
+    def from_dict(cls, seg: dict[str, Any] | None) -> "ConcatSegment":
+        """从字典创建拼接片段，带安全类型转换."""
+        if not seg or not isinstance(seg, dict):
+            return cls(video_path="")
+
+        try:
+            start_time = max(0.0, float(seg.get("start_time", 0.0)))
+        except (TypeError, ValueError):
+            start_time = 0.0
+
+        try:
+            duration = max(0.0, float(seg.get("duration", 0.0)))
+        except (TypeError, ValueError):
+            duration = 0.0
+
+        return cls(
+            video_path=str(seg.get("video_path", "")),
+            start_time=start_time,
+            duration=duration,
+            has_audio=bool(seg.get("has_audio", True)),
+        )
+
+    @property
+    def is_valid(self) -> bool:
+        """是否为有效片段（有视频路径）."""
+        return bool(self.video_path)
+
+    @property
+    def effective_duration(self) -> float:
+        """有效时长（duration > 0 时取 duration，否则 0）."""
+        return max(0.0, self.duration)
+
+
+@dataclass
+class ConcatConfig:
+    """视频拼接配置."""
+
+    segments: list[ConcatSegment] = field(default_factory=list)
+    output_width: int = 0  # 输出宽度（0=自动取第一段）
+    output_height: int = 0  # 输出高度（0=自动取第一段）
+    output_fps: float = 0.0  # 输出帧率（0=自动取第一段）
+    force_reencode: bool = False  # 强制重新编码
+    transition: str = "none"  # 转场效果（none/crossfade）
+    transition_duration: float = 0.3  # 转场时长
+
+    @classmethod
+    def from_config_dict(cls, config: dict[str, Any] | None) -> "ConcatConfig":
+        """从配置字典创建 ConcatConfig."""
+        if not config or not isinstance(config, dict):
+            return cls()
+
+        segments_raw = config.get("segments", [])
+        segments: list[ConcatSegment] = []
+
+        if isinstance(segments_raw, list):
+            for s in segments_raw:
+                if isinstance(s, dict) and s.get("video_path"):
+                    try:
+                        seg = ConcatSegment.from_dict(s)
+                        if seg.is_valid:
+                            segments.append(seg)
+                    except Exception:
+                        logger.warning("[concat] skip invalid segment: %s", s)
+                        continue
+
+        try:
+            output_width = max(0, int(config.get("output_width", 0)))
+        except (TypeError, ValueError):
+            output_width = 0
+
+        try:
+            output_height = max(0, int(config.get("output_height", 0)))
+        except (TypeError, ValueError):
+            output_height = 0
+
+        try:
+            output_fps = max(0.0, float(config.get("output_fps", 0.0)))
+        except (TypeError, ValueError):
+            output_fps = 0.0
+
+        try:
+            transition_duration = max(0.1, float(config.get("transition_duration", 0.3)))
+        except (TypeError, ValueError):
+            transition_duration = 0.3
+
+        return cls(
+            segments=segments,
+            output_width=output_width,
+            output_height=output_height,
+            output_fps=output_fps,
+            force_reencode=bool(config.get("force_reencode", False)),
+            transition=str(config.get("transition", "none")),
+            transition_duration=transition_duration,
+        )
+
+    @property
+    def has_effect(self) -> bool:
+        """是否有有效片段需要拼接（至少2段）."""
+        return self.valid_segment_count >= 2
+
+    @property
+    def valid_segment_count(self) -> int:
+        """有效片段数量."""
+        return sum(1 for s in self.segments if s.is_valid)
+
+    @property
+    def total_segments(self) -> int:
+        """有效片段数量（向后兼容别名）."""
+        return self.valid_segment_count
+
+    @property
+    def first_valid_segment(self) -> ConcatSegment | None:
+        """第一个有效片段."""
+        for s in self.segments:
+            if s.is_valid:
+                return s
+        return None
+
+    @property
+    def estimated_total_duration(self) -> float:
+        """估算总时长（只统计有明确duration的片段）."""
+        total = 0.0
+        for s in self.segments:
+            if s.is_valid and s.duration > 0:
+                total += s.duration
+        return total
+
+    def clamp_segments(self, max_segments: int = MAX_CONCAT_SEGMENTS) -> None:
+        """截断片段数量，防止OOM."""
+        if len(self.segments) > max_segments:
+            self.segments = self.segments[:max_segments]

packages/domain/video_filter_builder.py

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

packages/shared/ai_service.py

@@ -6,6 +6,7 @@ API 层和 Worker 层都从此模块导入，避免 API 直接依赖 Worker 代
 
 from __future__ import annotations
 
+import copy
 import json
 import logging
 import random
@@ -87,7 +88,7 @@ def _fallback_recommend_clips(
     order += 1
 
     # 生成推荐 config
-    config = DEFAULT_EDIT_PLAN_CONFIG.copy()
+    config = copy.deepcopy(DEFAULT_EDIT_PLAN_CONFIG)
     config["title"]["text"] = f"精选视频 — {len(asset_ids)} 个片段"
     config["title"]["ai_auto"] = True
 
@@ -167,7 +168,7 @@ def _parse_recommend_response(
         for i, clip in enumerate(clips):
             clip["order"] = i
 
-        config = DEFAULT_EDIT_PLAN_CONFIG.copy()
+        config = copy.deepcopy(DEFAULT_EDIT_PLAN_CONFIG)
         title = data.get("title", "")
         if title:
             config["title"]["text"] = str(title)

scripts/ci/run_unit_tests.sh

@@ -45,6 +45,9 @@ for i in 1 2 3; do
 done
 pytest --version
 
+# --- 安装 ffmpeg（视频处理相关测试依赖）---
+bash scripts/ci/step_install_ffmpeg.sh
+
 # 双保险：确保numpy已安装
 python3 -m pip install -q numpy==1.26.4 || true
 

scripts/ci/validate_code_quality.sh

@@ -56,95 +56,18 @@ for fpath, items in data.get('results', {}).items():
 fi
 echo "✅ Secret scan passed"
 
-# --- 增量/全量模式判断 ---
+# --- 代码质量检查（全量，PR 和 push 统一标准）---
+# 历史：PR 侧用增量检查以加速，但会导致 push 侧全量检查失败时 PR 侧感知不到
+# 现在统一全量检查，确保 CI 真正保护主分支（black/isort/ruff 全量仅多几十秒）
 echo ""
-echo "=== [2/6] Code quality checks ==="
+echo "=== [2/6] Code quality checks (full scan) ==="
 SCAN_MODE="full"
-CHANGED_PY_FILES=""
+echo "Full scan mode"
+python3 -m compileall -q alembic apps packages tests scripts
+python3 -m black --check --fast alembic apps packages tests scripts
+python3 -m isort --check-only alembic apps packages tests scripts
+python3 -m ruff check apps packages tests --statistics
 
-if [ "${GITHUB_EVENT_NAME:-}" = "pull_request" ] && [ -n "${GITHUB_REF_NAME:-}" ] && [ -n "${GITHUB_TOKEN:-}" ]; then
-  PR_NUMBER=$(echo "$GITHUB_REF" | sed 's|refs/pull/||; s|/.*||')
-  API_URL="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?limit=100"
-  set +e
-  RESPONSE=$(curl -s -w "\n%{http_code}" -H "Authorization: token ${GITHUB_TOKEN}" "$API_URL")
-  HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
-  BODY=$(echo "$RESPONSE" | sed '$d')
-  set -e
-  if [ "$HTTP_CODE" = "200" ]; then
-    CHANGED_PY_FILES=$(echo "$BODY" | python3 -c "
-import json, sys
-try:
-    files = json.load(sys.stdin)
-    py_files = [f['filename'] for f in files if f['filename'].endswith('.py') and f['status'] != 'removed']
-    print(' '.join(py_files))
-except Exception:
-    print('')
-")
-    # 新增文件(added)强制全量检查，防止增量漏检
-    ADDED_PY_FILES=$(echo "$BODY" | python3 -c "
-import json, sys
-try:
-    files = json.load(sys.stdin)
-    added = [f['filename'] for f in files if f['filename'].endswith('.py') and f['status'] == 'added']
-    print(' '.join(added))
-except Exception:
-    print('')
-")
-    MODIFIED_PY_FILES=$(echo "$BODY" | python3 -c "
-import json, sys
-try:
-    files = json.load(sys.stdin)
-    modified = [f['filename'] for f in files if f['filename'].endswith('.py') and f['status'] not in ('removed', 'added')]
-    print(' '.join(modified))
-except Exception:
-    print('')
-")
-    if [ -n "$CHANGED_PY_FILES" ]; then
-      SCAN_MODE="incremental"
-      echo "Incremental mode: $(echo "$CHANGED_PY_FILES" | wc -w) Python files changed"
-    else
-      SCAN_MODE="skip_py"
-      echo "No Python files changed in this PR"
-    fi
-  else
-    echo "WARN: API returned HTTP $HTTP_CODE, falling back to full scan"
-  fi
-else
-  echo "Full scan mode (not a PR event)"
-fi
-
-if [ "$SCAN_MODE" = "incremental" ]; then
-  # 防御性过滤
-  EXISTING_PY_FILES=""
-  for f in $CHANGED_PY_FILES; do
-    if [ -f "$f" ]; then
-      if [ -z "$EXISTING_PY_FILES" ]; then
-        EXISTING_PY_FILES="$f"
-      else
-        EXISTING_PY_FILES="$EXISTING_PY_FILES $f"
-      fi
-    fi
-  done
-  CHANGED_PY_FILES="$EXISTING_PY_FILES"
-
-  python3 -m compileall -q $CHANGED_PY_FILES
-  python3 -m black --check --fast $CHANGED_PY_FILES
-  python3 -m isort --check-only $CHANGED_PY_FILES
-  RUFF_FILES=$(echo "$CHANGED_PY_FILES" | tr ' ' '\n' | grep -v '^scripts/' | grep -v '^$' | xargs)
-  if [ -n "$RUFF_FILES" ]; then
-    python3 -m ruff check $RUFF_FILES --statistics
-  else
-    echo "No ruff-checkable files changed, skipping"
-  fi
-elif [ "$SCAN_MODE" = "skip_py" ]; then
-  echo "No Python files changed - skipping Python lint checks"
-else
-  echo "Full scan mode"
-  python3 -m compileall -q alembic apps packages tests scripts
-  python3 -m black --check --fast alembic apps packages tests scripts
-  python3 -m isort --check-only alembic apps packages tests scripts
-  python3 -m ruff check apps packages tests --statistics
-fi
 echo "✅ Code quality checks passed"
 
 # --- Bandit 安全扫描（仅告警） ---

tests/unit/test_application_modules.py

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