fix(ci): 修复CI Gate失败时返回exit 0而非exit 1的P0 Bug

- 新增纯逻辑模块 multi_track_mixer_pure.py，0 FFmpeg 依赖
- 71个单元测试全绿
- 向后兼容，原 multi_track_mixer.py 未修改

.env.example

@@ -1,60 +1,198 @@
-# 小虾 SaaS 环境变量配置
+# ============================================================
+# 小虾 SaaS 环境变量完整配置
+# ============================================================
+# 本文件列出所有可配置的环境变量及默认值。
+# 复制为 .env 后按需修改；生产环境务必覆盖所有密钥类配置。
+#
+# 配置读取规则（pydantic-settings，大小写不敏感）：
+#   1. 系统环境变量（最高优先级）
+#   2. .env.{APP_ENV} 文件（如 .env.staging）
+#   3. .env 文件
+#   4. 代码中的默认值（最低优先级）
+# ============================================================
 
-# ==================== 应用配置 ====================
-APP_NAME=小虾 SaaS
-APP_BASE_URL=http://localhost:3000
+
+# ==================== 应用基本配置 ====================
+
+# 应用名称
+APP_NAME=xiaoxia-saas
+
+# 应用版本号（展示用，代码中已内置默认）
+APP_VERSION=0.1.61
+
+# 环境标识：development / staging / production
+# 决定读取 .env.{APP_ENV} 还是 .env，也影响部分配置的严格校验
 APP_ENV=development
 
-# ==================== 数据库配置 ====================
-DATABASE_URL=postgresql://xiaoxia_user:your_password@localhost:5432/xiaoxia_saas
-
-# 开发环境：使用内存数据库（不需要 PostgreSQL）
-USE_IN_MEMORY_DB=true
-
-# 生产环境：使用 PostgreSQL
-# USE_IN_MEMORY_DB=false
-
-# ==================== Redis 配置 ====================
-REDIS_URL=redis://localhost:6379/0
-
-# ==================== JWT 配置 ====================
-JWT_SECRET_KEY=your-super-secret-key-change-this-in-production-min-32-chars
-JWT_ALGORITHM=HS256
-JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
-JWT_REFRESH_TOKEN_EXPIRE_DAYS=30
-
-# ==================== 邮件配置 ====================
-SMTP_HOST=smtp.gmail.com
-SMTP_PORT=587
-SMTP_USER=your-email@gmail.com
-SMTP_PASSWORD=your-app-specific-password
-SMTP_FROM_EMAIL=noreply@xiaoxia-saas.com
-SMTP_FROM_NAME=小虾 SaaS
-
-# ==================== 环境配置 ====================
-ENVIRONMENT=development
+# 是否开启 Debug 模式（开发环境 true，生产环境 false）
 DEBUG=true
 
-# ==================== CORS 配置 ====================
-# 逗号分隔的域名列表（Settings 读取 CORS_ORIGINS_RAW）
-CORS_ORIGINS_RAW=http://localhost:3000,http://localhost:5173
+# 应用基础 URL，用于生成认证邮件、回调链接等
+APP_BASE_URL=http://localhost:3000
+
+# API 服务监听地址（容器内绑定，外部暴露由 Docker/Nginx 控制）
+API_HOST=0.0.0.0
+
+# API 服务监听端口
+API_PORT=8000
+
+# 是否自动创建数据库表结构（开发环境可开启，生产环境用 alembic migration）
+AUTO_CREATE_SCHEMA=false
+
+
+# ==================== 数据库配置 ====================
+
+# 数据库连接串（格式：postgresql+psycopg://user:password@host:port/dbname）
+DATABASE_URL=postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas
+
+# 连接池大小（常驻连接数）
+DATABASE_POOL_SIZE=20
+
+# 连接池最大溢出连接数（pool_size + max_overflow = 最大并发连接数）
+DATABASE_MAX_OVERFLOW=10
+
+# 获取连接超时时间（秒）
+DATABASE_POOL_TIMEOUT=30
+
+# 连接回收时间（秒），防止数据库端主动断开导致的死连接
+DATABASE_POOL_RECYCLE=3600
+
+# 是否使用内存数据库（SQLite，仅开发/测试可用；生产务必 false）
+USE_IN_MEMORY_DB=false
+
+
+# ==================== Redis 配置 ====================
+
+# Redis 连接 URL（格式：redis://[:password@]host:port/db）
+REDIS_URL=redis://localhost:6379/0
+
+# 是否使用 Redis 存储 Session（多实例部署时必须开启；开发可用内存存储）
+ENABLE_REDIS_SESSIONS=false
+
+
+# ==================== Celery 任务队列 ====================
+
+# Celery Broker（任务分发），默认用 Redis db0
+CELERY_BROKER_URL=redis://localhost:6379/0
+
+# Celery Result Backend（任务结果存储），默认用 Redis db1
+CELERY_RESULT_BACKEND=redis://localhost:6379/1
+
+
+# ==================== Worker 配置 ====================
+
+# Worker 进程名称
+WORKER_NAME=xiaoxia-saas-worker
+
+# Worker 并发数（同时执行的任务数）
+WORKER_CONCURRENCY=4
+
+# 每个子进程最多处理多少任务后重启（防止内存泄漏）
+WORKER_MAX_TASKS_PER_CHILD=1000
+
+
+# ==================== JWT 认证配置 ====================
+
+# JWT 签名密钥 — 生产环境必须设置为强随机字符串（至少32字符）
+# 内置不安全值会被拒绝：secret / changeme / password / your-secret-key 等
+JWT_SECRET_KEY=your-super-secret-key-change-this-in-production-min-32-chars
+
+# JWT 签名算法
+JWT_ALGORITHM=HS256
+
+# Access Token 过期时间（分钟）
+JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
+
+# Refresh Token 过期时间（天）
+JWT_REFRESH_TOKEN_EXPIRE_DAYS=30
+
+
+# ==================== 邮件配置 ====================
+
+# 是否启用邮件投递（关闭时邮件内容打印到日志，开发调试用）
+ENABLE_EMAIL_DELIVERY=false
+
+# SMTP 服务器地址
+SMTP_HOST=smtp.gmail.com
+
+# SMTP 端口
+SMTP_PORT=587
+
+# SMTP 用户名
+SMTP_USER=your-email@gmail.com
+
+# SMTP 密码 / 应用专用密码
+SMTP_PASSWORD=your-app-specific-password
+
+# 发件人邮箱
+SMTP_FROM_EMAIL=noreply@xiaoxia-saas.com
+
+# 发件人显示名称
+SMTP_FROM_NAME=小虾 SaaS
+
+# 是否启用 TLS
+SMTP_USE_TLS=true
+
 
 # ==================== 阿里云 OSS 配置 ====================
+
+# OSS 区域 endpoint
 OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
+
+# OSS Access Key ID — 非开发环境必须设置
 OSS_ACCESS_KEY_ID=your-access-key-id
+
+# OSS Access Key Secret — 非开发环境必须设置
 OSS_ACCESS_KEY_SECRET=your-access-key-secret
+
+# OSS Bucket 名称
 OSS_BUCKET_NAME=xiaoxia-autocut
 
-# ==================== CosyVoice 语音合成配置 ====================
-# 注意：base_url 只需写到 /api/v1，具体路径由代码拼接
-# 模型: cosyvoice-v3-flash (推荐，支持系统音色，性价比高)
-#       cosyvoice-v3-plus (高质量，系统音色少)
-#       cosyvoice-v3.5-flash / cosyvoice-v3.5-plus (仅支持克隆/设计音色，无系统音色)
-# 音色: v3系列系统音色带 _v3 后缀，如 longxiaochun_v3, longxiaoxia_v3, longanyang (无后缀)
-# 注意：COSYVOICE_* 变量由 packages/shared/config.py 的 SharedSettings 读取
+# 直传最大文件大小（MB）
+OSS_DIRECT_UPLOAD_MAX_MB=2000
+
+# 直传签名有效期（秒）
+OSS_DIRECT_UPLOAD_EXPIRE_SECONDS=900
+
+
+# ==================== CORS 配置 ====================
+
+# 允许跨域的前端域名列表，逗号分隔
+CORS_ORIGINS_RAW=http://localhost:3000,http://localhost:5173,http://localhost:8000
+
+
+# ==================== 渲染引擎配置 ====================
+
+# 渲染引擎选择：
+#   legacy   — 旧 VideoComposeService（稳定，功能完整）
+#   unified  — 新 UnifiedRenderService（新架构，部分场景仍在验证）
+RENDER_ENGINE=legacy
+
+
+# ==================== CosyVoice 语音合成 ====================
+# 阿里云百灵语音合成服务
+# 模型选择：
+#   cosyvoice-v3-flash  — 推荐，系统音色多，性价比高
+#   cosyvoice-v3-plus   — 高质量，系统音色少
+#   cosyvoice-v3.5-flash / cosyvoice-v3.5-plus — 仅支持克隆/设计音色，无系统音色
+# 音色：v3 系列系统音色带 _v3 后缀，如 longxiaochun_v3 / longxiaoxia_v3 / longanyang
+
 COSYVOICE_API_KEY=your-cosyvoice-api-key
 COSYVOICE_BASE_URL=https://dashscope.aliyuncs.com/api/v1
 COSYVOICE_MODEL=cosyvoice-v3-flash
 COSYVOICE_VOICE=longxiaochun_v3
 COSYVOICE_SAMPLE_RATE=22050
 COSYVOICE_FORMAT=mp3
+
+# 音色克隆模型名（固定为 voice-enrollment，通常不需修改）
+COSYVOICE_CLONE_MODEL=voice-enrollment
+
+
+# ==================== 豆包大模型（火山引擎方舟） ====================
+# 用于 AI 文案生成、智能剪辑等需要大模型能力的场景
+
+DOUBAO_API_KEY=your-doubao-api-key
+DOUBAO_MODEL=doubao-seed-1-6-250615
+DOUBAO_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
+DOUBAO_TIMEOUT=30
+DOUBAO_MAX_RETRIES=2

.gitea/workflows/acr-cleanup.yml

@@ -0,0 +1,161 @@
+name: ACR Cleanup
+
+on:
+  schedule:
+    - cron: '0 19 * * *'  # UTC 19:00 = 北京时间凌晨3:00
+  workflow_dispatch:
+    inputs:
+      pr_sha:
+        description: "PR commit SHA（仅清理指定PR镜像，留空则全量清理）"
+        required: false
+        default: ""
+      dry_run:
+        description: "预览模式（dry-run），不实际删除"
+        required: false
+        default: "true"
+  pull_request_target:
+    types: [closed]
+    branches: [develop, main]
+
+concurrency:
+  group: acr-cleanup-${{ gitea.ref }}
+  cancel-in-progress: false
+
+jobs:
+  cleanup:
+    name: ACR Image Cleanup
+    runs-on: ci-l2
+    timeout-minutes: 20
+    permissions:
+      contents: read
+    env:
+      ACR_REGISTRY: xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com
+      ACR_NAMESPACE: xiaoxiakeji
+      ACR_SERVICE: registry.aliyuncs.com:cn-hangzhou:china:cri-fvec8o9q4mmxrkaa
+      GITEA_URL: https://git.xiaoxiajianji.com
+      GITEA_REPO: xiaoxia/xiaoxia-saas
+    steps:
+      - name: Checkout code
+        shell: sh
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          curl -sH "Authorization: token $GITHUB_TOKEN"             "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}"             | bash
+
+      # ====== Cron模式：获取staging运行中镜像作为白名单 ======
+      - name: Get staging running images (whitelist)
+        id: protected_images
+        if: gitea.event_name != 'pull_request_target' && !gitea.event.inputs.pr_sha
+        env:
+          STAGING_SSH_KEY: ${{ secrets.PREVIEW_SSH_KEY }}
+        run: |
+          set +e
+          echo "获取staging服务器运行中镜像作为白名单..."
+          mkdir -p ~/.ssh
+          echo "$STAGING_SSH_KEY" > ~/.ssh/id_rsa
+          chmod 600 ~/.ssh/id_rsa
+
+          staging_host="${STAGING_SSH_HOST:-47.98.113.167}"
+          staging_port="${STAGING_SSH_PORT:-22222}"
+
+          ssh-keyscan -p "$staging_port" -H "$staging_host" >> ~/.ssh/known_hosts 2>/dev/null
+
+          # 获取所有运行容器的镜像，提取tag部分
+          IMAGES=$(ssh -p "$staging_port" -i ~/.ssh/id_rsa -o StrictHostKeyChecking=no \
+            "root@$staging_host" "docker ps --format '{{.Image}}' 2>/dev/null" 2>/dev/null | grep -v "^$" | sort -u)
+
+          PROTECTED_TAGS=""
+          if [ -n "$IMAGES" ]; then
+            while IFS= read -r img; do
+              # 从完整镜像名中提取tag（最后一个冒号后）
+              tag=$(echo "$img" | rev | cut -d: -f1 | rev)
+              if [ -n "$tag" ] && [ "$tag" != "latest" ] && [ ${#tag} -gt 5 ]; then
+                if [ -z "$PROTECTED_TAGS" ]; then
+                  PROTECTED_TAGS="$tag"
+                else
+                  PROTECTED_TAGS="$PROTECTED_TAGS,$tag"
+                fi
+              fi
+            done <<< "$IMAGES"
+          fi
+
+          echo "staging运行中镜像tag: ${PROTECTED_TAGS:-（无）}"
+          echo "protected_tags=$PROTECTED_TAGS" >> $GITEA_OUTPUT
+
+      # ====== Docker登录 ======
+      - name: Docker login to ACR
+        env:
+          ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+          ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+        run: |
+          printf '%s' "$ACR_PASSWORD" | docker login "$ACR_REGISTRY" -u "$ACR_USERNAME" --password-stdin
+
+      # ====== 模式1：PR关闭时清理 ======
+      - name: Cleanup PR images (PR closed)
+        if: gitea.event_name == 'pull_request_target'
+        env:
+          ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+          ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          PR_SHA: ${{ gitea.event.pull_request.head.sha }}
+          PR_NUMBER: ${{ gitea.event.pull_request.number }}
+        run: |
+          echo "============================================"
+          echo "  PR #$PR_NUMBER 已关闭，清理对应镜像"
+          echo "  Head SHA: ${PR_SHA::12}"
+          echo "============================================"
+          echo ""
+          python3 scripts/ci/acr_cleanup.py \
+            --pr-sha "$PR_SHA" \
+            --execute
+
+      # ====== 模式2：Cron全量清理 ======
+      - name: Full cleanup (cron / manual)
+        if: gitea.event_name != 'pull_request_target' && !gitea.event.inputs.pr_sha
+        env:
+          ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+          ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          PROTECTED_TAGS: ${{ steps.protected_images.outputs.protected_tags }}
+          DRY_RUN_INPUT: ${{ gitea.event.inputs.dry_run }}
+        run: |
+          echo "============================================"
+          echo "  ACR 全量清理（${{ gitea.event_name }}）"
+          echo "============================================"
+          echo ""
+
+          # 决定是否dry-run
+          DRY_RUN_FLAG=""
+          if [ "$DRY_RUN_INPUT" = "true" ]; then
+            DRY_RUN_FLAG="--dry-run"
+            echo "模式: 预览模式 (dry-run)"
+          else
+            echo "模式: 执行模式"
+          fi
+          echo ""
+
+          python3 scripts/ci/acr_cleanup.py \
+            --keep 20 \
+            --protected-tags "$PROTECTED_TAGS" \
+            $DRY_RUN_FLAG
+
+      # ====== 模式3：手动指定PR SHA清理 ======
+      - name: Cleanup specific PR image (manual)
+        if: gitea.event_name == 'workflow_dispatch' && gitea.event.inputs.pr_sha
+        env:
+          ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+          ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+          PR_SHA: ${{ gitea.event.inputs.pr_sha }}
+          DRY_RUN_INPUT: ${{ gitea.event.inputs.dry_run }}
+        run: |
+          echo "手动清理PR镜像: ${PR_SHA::12}"
+          echo ""
+
+          DRY_RUN_FLAG=""
+          if [ "$DRY_RUN_INPUT" = "true" ]; then
+            DRY_RUN_FLAG="--dry-run"
+          fi
+
+          python3 scripts/ci/acr_cleanup.py \
+            --pr-sha "$PR_SHA" \
+            $DRY_RUN_FLAG

.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

@@ -22,7 +22,8 @@ permissions:
   contents: read
 concurrency:
   group: ci-pipeline-${{ gitea.event_name }}-${{ gitea.ref }}
-  cancel-in-progress: true
+  # PR事件取消进行中的旧run，push事件不取消（确保完整CI跑完）
+  cancel-in-progress: ${{ gitea.event_name == 'pull_request' }}
 jobs:
   check-frontend-only:
     name: Check if frontend-only change
@@ -394,7 +395,9 @@ jobs:
     if: always() && needs.check-frontend-only.outputs.skip_backend != 'true'
     needs:
       - check-frontend-only
-      - validate
+      - validate-code-quality
+      - validate-type-check
+      - validate-migration
     env:
       DATABASE_URL: postgresql+psycopg://postgres:postgres@host.docker.internal:5432/xiaoxia_saas
       USE_IN_MEMORY_DB: 'false'
@@ -642,42 +645,37 @@ jobs:
         else
           echo "基础镜像不存在，本地构建（fallback模式）..."
           
-          # 构建builder基础镜像
-          echo "构建 worker-base-builder..."
-          # 用buildx docker-container驱动构建（兼容DooD模式：普通docker build看不到容器内文件）
+          # 尝试用buildx构建，失败则回退到普通docker build（DooD模式下buildx builder偶发崩溃）
           BUILDER_NAME="ci-pr-builder-${GITHUB_RUN_ID:-local}"
-          if ! docker buildx inspect "$BUILDER_NAME" > /dev/null 2>&1; then
-            docker buildx create --use --name "$BUILDER_NAME" --driver docker-container
-          else
-            docker buildx use "$BUILDER_NAME"
+          BUILDX_AVAILABLE=true
+          if ! docker buildx create --use --name "$BUILDER_NAME" --driver docker-container > /dev/null 2>&1; then
+            BUILDX_AVAILABLE=false
+          fi
+          if [ "$BUILDX_AVAILABLE" = true ] && ! docker buildx inspect --bootstrap > /dev/null 2>&1; then
+            BUILDX_AVAILABLE=false
+            docker buildx rm "$BUILDER_NAME" > /dev/null 2>&1 || true
           fi
-          docker buildx inspect --bootstrap > /dev/null 2>&1
           
-          # 构建builder基础镜像（带重试，buildx容器偶发不稳定）
-          echo "构建 worker-base-builder..."
-          for attempt in 1 2 3; do
-            if docker buildx build --load -f infra/docker/worker-base-builder.Dockerfile -t "$BASE_BUILDER" .; then
-              echo "worker-base-builder 构建成功"
-              break
+          build_base() {
+            local df="$1"
+            local tag="$2"
+            local name="$3"
+            if [ "$BUILDX_AVAILABLE" = true ]; then
+              echo "构建 $name（buildx）..."
+              if docker buildx build --load -f "$df" -t "$tag" . > /dev/null 2>&1; then
+                echo "$name 构建成功"
+                return 0
+              fi
+              echo "buildx失败，回退到普通docker build"
+              BUILDX_AVAILABLE=false
+              docker buildx rm "$BUILDER_NAME" > /dev/null 2>&1 || true
             fi
-            echo "worker-base-builder 构建失败，重试 $attempt/3..."
-            docker buildx rm "$BUILDER_NAME" 2>/dev/null || true
-            docker buildx create --use --name "$BUILDER_NAME" --driver docker-container
-            sleep 3
-          done
+            echo "构建 $name（docker build）..."
+            docker build -f "$df" -t "$tag" .
+          }
           
-          # 构建runtime基础镜像
-          echo "构建 worker-base-runtime..."
-          for attempt in 1 2 3; do
-            if docker buildx build --load -f infra/docker/worker-base-runtime.Dockerfile -t "$BASE_RUNTIME" .; then
-              echo "worker-base-runtime 构建成功"
-              break
-            fi
-            echo "worker-base-runtime 构建失败，重试 $attempt/3..."
-            docker buildx rm "$BUILDER_NAME" 2>/dev/null || true
-            docker buildx create --use --name "$BUILDER_NAME" --driver docker-container
-            sleep 3
-          done
+          build_base infra/docker/worker-base-builder.Dockerfile "$BASE_BUILDER" "worker-base-builder"
+          build_base infra/docker/worker-base-runtime.Dockerfile "$BASE_RUNTIME" "worker-base-runtime"
           
           echo "fallback=true" >> $GITHUB_OUTPUT
           echo "基础镜像本地构建完成"
@@ -1080,18 +1078,26 @@ jobs:
       shell: sh
       run: bash scripts/ci/step_timer_start.sh
     - name: Run Playwright E2E on staging
-      shell: sh
+      shell: bash
       run: |
         set -eu
-        docker run --rm --ipc=host \
+        # DooD模式下不能用-v挂载（宿主机路径与CI容器路径不一致）
+        # 改用 docker create + docker cp 方式把代码拷进容器
+        CONTAINER_NAME="staging-e2e-$$"
+        docker create --name "$CONTAINER_NAME" --ipc=host \
           -e E2E_BASE_URL=https://staging.xiaoxiajianji.com \
           -e E2E_API_BASE=https://staging-api.xiaoxiajianji.com/api/v1 \
           -e E2E_BROWSER_CHANNEL=chromium \
           -e PLAYWRIGHT_HEADLESS=1 \
-          -v "$PWD:/workspace" \
           -w /workspace/apps/web \
           git.xiaoxiajianji.com/xiaoxia/base/playwright:v1.45.0-jammy \
           sh -lc "npm ci && npx playwright test --reporter=line --project=chromium e2e/auth.spec.ts e2e/auth-guard.spec.ts e2e/core-upload.spec.ts e2e/core-generation.spec.ts"
+        docker cp apps "$CONTAINER_NAME:/workspace/"
+        docker cp package-lock.json "$CONTAINER_NAME:/workspace/" 2>/dev/null || true
+        docker start -a "$CONTAINER_NAME"
+        EXIT_CODE=$(docker wait "$CONTAINER_NAME")
+        docker rm "$CONTAINER_NAME" 2>/dev/null || true
+        exit $EXIT_CODE
 
     - name: Job duration summary
       if: always()
@@ -1136,16 +1142,24 @@ jobs:
       shell: sh
       run: bash scripts/ci/step_timer_start.sh
     - name: Run API integration tests on staging
-      shell: sh
+      shell: bash
       run: |
         set -eu
-        docker run --rm \
+        # DooD模式下不能用-v挂载（宿主机路径与CI容器路径不一致）
+        # 改用 docker create + docker cp 方式把代码拷进容器
+        CONTAINER_NAME="staging-api-tests-$$"
+        docker create --name "$CONTAINER_NAME" \
           -e E2E_BASE_URL=https://staging.xiaoxiajianji.com \
           -e E2E_API_BASE=https://staging-api.xiaoxiajianji.com/api/v1 \
-          -v "$PWD:/workspace" \
           -w /workspace/apps/web \
           git.xiaoxiajianji.com/xiaoxia/base/playwright:v1.45.0-jammy \
           sh -lc 'npm ci && npx playwright test --reporter=line e2e/test_auth.spec.ts e2e/test_asset.spec.ts e2e/test_project.spec.ts'
+        docker cp apps "$CONTAINER_NAME:/workspace/"
+        docker cp package-lock.json "$CONTAINER_NAME:/workspace/" 2>/dev/null || true
+        docker start -a "$CONTAINER_NAME"
+        EXIT_CODE=$(docker wait "$CONTAINER_NAME")
+        docker rm "$CONTAINER_NAME" 2>/dev/null || true
+        exit $EXIT_CODE
 
     - name: Job duration summary
       if: always()
@@ -1178,7 +1192,7 @@ jobs:
     runs-on: runtime-builder
     timeout-minutes: ${{ matrix.timeout }}
     needs:
-    if: startsWith(github.ref, 'refs/tags/v')
+    if: startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'push' && github.ref_name == 'main')
     strategy:
       fail-fast: false
       matrix:
@@ -1255,10 +1269,16 @@ jobs:
       run: |
         set -eu
         REGISTRY="xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji"
-        IMAGE_TAG="${REGISTRY}/${{ matrix.image_name }}:${GITHUB_REF_NAME}"
+        # 根据ref类型设置镜像标签：tag用版本号，分支用分支名+sha
+        if [[ "$GITHUB_REF" == refs/tags/* ]]; then
+          TAG_NAME="${GITHUB_REF_NAME}"
+        else
+          TAG_NAME="${GITHUB_REF_NAME}-${GITHUB_SHA::8}"
+        fi
+        IMAGE_TAG="${REGISTRY}/${{ matrix.image_name }}:${TAG_NAME}"
         CACHE_REF="${REGISTRY}/${{ matrix.cache_name }}:main"
 
-        EXTRA_BUILD_ARGS="APP_VERSION=\"${GITHUB_REF_NAME}\""
+        EXTRA_BUILD_ARGS="APP_VERSION=\"${TAG_NAME}\""
         if [ "${{ matrix.service }}" = "web" ]; then
           EXTRA_BUILD_ARGS="$EXTRA_BUILD_ARGS NGINX_CONF=infra/docker/nginx-production.conf"
         fi
@@ -1556,4 +1576,246 @@ jobs:
         [ ${{ job.status }} = "success" ] || STATUS="error"
         START_TIME=""
         [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
-        python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+        python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+
+  canary-release:
+    name: Canary Release to Production
+    runs-on: runtime-builder
+    timeout-minutes: 120
+    concurrency:
+      group: canary-release-production
+      cancel-in-progress: false
+    if: github.event_name == 'push' && github.ref_name == 'main'
+    needs:
+    - build-production
+    - staging-api-tests
+    steps:
+    - name: Checkout code
+      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: Record job start time
+      shell: sh
+      run: bash scripts/ci/step_timer_start.sh
+    - name: Notify canary release start
+      continue-on-error: true
+      shell: sh
+      env:
+        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
+      run: |
+        set +e
+        NOTIFY_MODE=start JOB_NAME="Canary Release" python3 scripts/ci_notify.py
+    - name: Install SSH client
+      shell: sh
+      run: |
+        set -eu
+        apt-get update -qq && apt-get install -y -qq openssh-client curl >/dev/null 2>&1
+        echo "openssh-client installed"
+    - name: Run canary release
+      shell: bash
+      env:
+        PRODUCTION_SSH_HOST: ${{ secrets.PRODUCTION_SSH_HOST }}
+        PRODUCTION_SSH_USER: ${{ secrets.PRODUCTION_SSH_USER }}
+        PRODUCTION_SSH_PORT: ${{ secrets.PRODUCTION_SSH_PORT }}
+        PRODUCTION_SSH_KEY: ${{ secrets.PRODUCTION_SSH_KEY }}
+        ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+        ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
+      run: |
+        set -eu
+        IMAGE_TAG="main-${GITHUB_SHA::8}"
+        export IMAGE_TAG
+        echo "Canary release version: $IMAGE_TAG"
+        bash scripts/ci/canary_release.sh
+    - name: Job duration summary
+      if: always()
+      shell: sh
+      run: bash scripts/ci/step_timer_end.sh
+    - name: Notify on success
+      continue-on-error: true
+      if: success()
+      shell: sh
+      env:
+        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
+      run: |
+        set +e
+        NOTIFY_MODE=success JOB_NAME="Canary Release" python3 scripts/ci_notify.py
+    - name: Notify on failure
+      continue-on-error: true
+      if: failure()
+      shell: sh
+      env:
+        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
+      run: |
+        set +e
+        NOTIFY_MODE=failure JOB_NAME="Canary Release" python3 scripts/ci_notify.py
+    - name: Report CI trace
+      if: always()
+      shell: sh
+      env:
+        AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+      run: |
+        STATUS="ok"
+        [ ${{ job.status }} = "success" ] || STATUS="error"
+        START_TIME=""
+        [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+        python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+
+  ci-gate:
+    name: CI Gate
+    runs-on: ci-l2
+    if: always() && github.event_name == 'pull_request'
+    needs:
+      - check-frontend-only
+      - validate-code-quality
+      - validate-type-check
+      - validate-migration
+      - unit-tests
+      - integration-tests
+      - frontend-lint
+      - frontend-unit-test
+      - build-pr
+    timeout-minutes: 3
+    steps:
+      - name: Checkout code
+        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: Evaluate CI Gate
+        id: gate
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          RESULT_CHECK_FRONTEND: ${{ needs.check-frontend-only.result }}
+          RESULT_CODE_QUALITY: ${{ needs.validate-code-quality.result }}
+          RESULT_TYPE_CHECK: ${{ needs.validate-type-check.result }}
+          RESULT_MIGRATION: ${{ needs.validate-migration.result }}
+          RESULT_UNIT_TESTS: ${{ needs.unit-tests.result }}
+          RESULT_INTEGRATION: ${{ needs.integration-tests.result }}
+          RESULT_FRONTEND_LINT: ${{ needs.frontend-lint.result }}
+          RESULT_FRONTEND_UNIT: ${{ needs.frontend-unit-test.result }}
+          RESULT_BUILD_PR: ${{ needs.build-pr.result }}
+        run: |
+          set -eu
+          echo "=== CI Gate 评估 ==="
+          echo ""
+          echo "各job结果:"
+          echo "  check-frontend-only: $RESULT_CHECK_FRONTEND"
+          echo "  validate-code-quality: $RESULT_CODE_QUALITY"
+          echo "  validate-type-check: $RESULT_TYPE_CHECK"
+          echo "  validate-migration: $RESULT_MIGRATION"
+          echo "  unit-tests: $RESULT_UNIT_TESTS"
+          echo "  integration-tests: $RESULT_INTEGRATION"
+          echo "  frontend-lint: $RESULT_FRONTEND_LINT"
+          echo "  frontend-unit-test: $RESULT_FRONTEND_UNIT"
+          echo "  build-pr: $RESULT_BUILD_PR"
+          echo ""
+
+          # 判断PR类型
+          SKIP_BACKEND="${{ needs.check-frontend-only.outputs.skip_backend }}"
+          SKIP_FRONTEND="${{ needs.check-frontend-only.outputs.skip_frontend }}"
+          echo "PR类型: skip_backend=$SKIP_BACKEND, skip_frontend=$SKIP_FRONTEND"
+
+          # 必填检查项（根据PR类型决定）
+          # 通用检查（所有PR都必须过）
+          REQUIRED_GENERAL=(
+            "validate-code-quality:$RESULT_CODE_QUALITY"
+            "validate-type-check:$RESULT_TYPE_CHECK"
+            "validate-migration:$RESULT_MIGRATION"
+            "frontend-lint:$RESULT_FRONTEND_LINT"
+            "build-pr:$RESULT_BUILD_PR"
+          )
+
+          # 后端检查
+          REQUIRED_BACKEND=(
+            "unit-tests:$RESULT_UNIT_TESTS"
+          )
+
+          # 前端检查
+          REQUIRED_FRONTEND=(
+            "frontend-unit-test:$RESULT_FRONTEND_UNIT"
+          )
+
+          ALL_PASSED=true
+          FAILED_ITEMS=()
+
+          check_job() {
+            local name=$1
+            local result=$2
+            if [ "$result" = "success" ]; then
+              echo "  ✅ $name: success"
+            elif [ "$result" = "skipped" ]; then
+              echo "  ⏭️  $name: skipped（跳过，不影响）"
+            else
+              echo "  ❌ $name: $result"
+              ALL_PASSED=false
+              FAILED_ITEMS+=("$name=$result")
+            fi
+          }
+
+          echo ""
+          echo "=== 通用检查（所有PR必填）==="
+          for item in "${REQUIRED_GENERAL[@]}"; do
+            name="${item%%:*}"
+            result="${item##*:}"
+            check_job "$name" "$result"
+          done
+
+          if [ "$SKIP_BACKEND" != "true" ]; then
+            echo ""
+            echo "=== 后端检查 ==="
+            for item in "${REQUIRED_BACKEND[@]}"; do
+              name="${item%%:*}"
+              result="${item##*:}"
+              check_job "$name" "$result"
+            done
+          else
+            echo ""
+            echo "=== 后端检查（纯前端PR，跳过）==="
+          fi
+
+          if [ "$SKIP_FRONTEND" != "true" ]; then
+            echo ""
+            echo "=== 前端检查 ==="
+            for item in "${REQUIRED_FRONTEND[@]}"; do
+              name="${item%%:*}"
+              result="${item##*:}"
+              check_job "$name" "$result"
+            done
+          else
+            echo ""
+            echo "=== 前端检查（纯后端PR，跳过）==="
+          fi
+
+          echo ""
+          if [ "$ALL_PASSED" = "true" ]; then
+            echo "✅ CI Gate: PASSED"
+            echo "gate_result=success" >> $GITHUB_OUTPUT
+            exit 0
+          else
+            echo "❌ CI Gate: FAILED"
+            echo "失败项: ${FAILED_ITEMS[*]}"
+            echo "gate_result=failure" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+      - name: Report CI trace
+        if: always()
+        shell: sh
+        env:
+          AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+        run: |
+          STATUS="ok"
+          [ "${{ steps.gate.outputs.gate_result }}" = "success" ] || STATUS="error"
+          START_TIME=""
+          [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true

.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: |
@@ -50,6 +48,7 @@ jobs:
           GITEA_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
           REPO_NAME: ${{ gitea.repository }}
           PR_NUMBER: ${{ gitea.event.pull_request.number }}
+          PR_HEAD_SHA: ${{ gitea.event.pull_request.head.sha }}
           # LLM 提供商: coze (扣子原生Bot) / openai (OpenAI兼容)
           LLM_PROVIDER: "coze"
           # 扣子模式配置（默认国内站 api.coze.cn）
@@ -62,8 +61,9 @@ jobs:
           LLM_TIMEOUT: "120"
         run: |
           python3 scripts/ci_code_review.py
-        # 审查脚本异常不影响 CI 通过
-        continue-on-error: true
+        # 注意：脚本退出码决定job状态
+        # - 有阻塞级问题 → exit 1 → job失败 → 门禁拦截
+        # - 无阻塞级问题/LLM异常 → exit 0 → 通过（fail-open）
 
       - name: Report CI trace
         if: always()

.gitea/workflows/daily-check.yml

@@ -1,4 +1,5 @@
 name: Daily Health Check
+# 注意：使用 curl step_checkout.sh 方式以兼容 docker runner
 
 on:
   schedule:
@@ -12,7 +13,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 }}
@@ -23,47 +24,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ github.token }}
         run: |
-          set -eu
-          python3 - <<'PY'
-          import io, os, tarfile, time, urllib.request, urllib.error
-          url = f"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz"
-          request = urllib.request.Request(url, headers={"Authorization": f"token {os.environ['GITHUB_TOKEN']}"})
-          last_err = None
-          for attempt in range(5):
-              try:
-                  with urllib.request.urlopen(request, timeout=120) as response:
-                      archive = response.read()
-                  break
-              except urllib.error.HTTPError as e:
-                  last_err = e
-                  if e.code >= 500 and attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-              except Exception as e:
-                  last_err = e
-                  if attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-          else:
-              raise last_err
-          with tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:
-              root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'
-              for member in tar.getmembers():
-                  name = member.name
-                  if name == root_prefix[:-1]:
-                      continue
-                  if name.startswith(root_prefix):
-                      member.name = name[len(root_prefix):]
-                  if member.name:
-                      tar.extract(member, '.')
-          PY
-
+          curl -sH "Authorization: token $GITHUB_TOKEN" \
+            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}" \
+            | bash
       - name: Production health check & smoke test
         id: smoke
         shell: sh
@@ -121,7 +84,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 }}
@@ -132,50 +95,15 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ github.token }}
         run: |
-          set -eu
-          python3 - <<'PY'
-          import io, os, tarfile, time, urllib.request, urllib.error
-          url = f"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz"
-          request = urllib.request.Request(url, headers={"Authorization": f"token {os.environ['GITHUB_TOKEN']}"})
-          last_err = None
-          for attempt in range(5):
-              try:
-                  with urllib.request.urlopen(request, timeout=120) as response:
-                      archive = response.read()
-                  break
-              except urllib.error.HTTPError as e:
-                  last_err = e
-                  if e.code >= 500 and attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-              except Exception as e:
-                  last_err = e
-                  if attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-          else:
-              raise last_err
-          with tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:
-              root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'
-              for member in tar.getmembers():
-                  name = member.name
-                  if name == root_prefix[:-1]:
-                      continue
-                  if name.startswith(root_prefix):
-                      member.name = name[len(root_prefix):]
-                  if member.name:
-                      tar.extract(member, '.')
-          PY
-
+          curl -sH "Authorization: token $GITHUB_TOKEN" \
+            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}" \
+            | bash
       - name: Run API smoke test on staging
         id: smoke
         shell: sh
+        env:
+          STAGING_TEST_USER: ${{ secrets.STAGING_TEST_USER }}
+          STAGING_TEST_PASSWORD: ${{ secrets.STAGING_TEST_PASSWORD }}
         run: |
           set +e
           START_TIME=$(date +%s)
@@ -183,8 +111,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 +198,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 }}
@@ -281,47 +209,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ github.token }}
         run: |
-          set -eu
-          python3 - <<'PY'
-          import io, os, tarfile, time, urllib.request, urllib.error
-          url = f"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz"
-          request = urllib.request.Request(url, headers={"Authorization": f"token {os.environ['GITHUB_TOKEN']}"})
-          last_err = None
-          for attempt in range(5):
-              try:
-                  with urllib.request.urlopen(request, timeout=120) as response:
-                      archive = response.read()
-                  break
-              except urllib.error.HTTPError as e:
-                  last_err = e
-                  if e.code >= 500 and attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-              except Exception as e:
-                  last_err = e
-                  if attempt < 4:
-                      wait = 2 ** attempt
-                      print(f"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...")
-                      time.sleep(wait)
-                      continue
-                  raise
-          else:
-              raise last_err
-          with tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:
-              root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'
-              for member in tar.getmembers():
-                  name = member.name
-                  if name == root_prefix[:-1]:
-                      continue
-                  if name.startswith(root_prefix):
-                      member.name = name[len(root_prefix):]
-                  if member.name:
-                      tar.extract(member, '.')
-          PY
-
+          curl -sH "Authorization: token $GITHUB_TOKEN" \
+            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}" \
+            | bash
       - name: Run Playwright E2E on staging
         id: e2e
         shell: sh
@@ -371,7 +261,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 +270,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 +308,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 +341,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 +389,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 +406,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 +426,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 +529,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 --include=dev; then
-                echo "npm ci failed, cleaning node_modules and retrying..."
-                rm -rf node_modules
-                mkdir -p node_modules
-                npm ci --include=dev
-              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

alembic/env.py

@@ -1,4 +1,3 @@
-import os
 from logging.config import fileConfig
 
 from sqlalchemy import engine_from_config, pool
@@ -8,13 +7,17 @@ from alembic import context
 # Import your models' Base here
 from packages.adapters.sqlalchemy_impl.models import Base
 
+# 使用统一配置入口获取 database_url，而非直接读环境变量
+from packages.config import get_shared_settings
+
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.
 config = context.config
 
-database_url = os.getenv("DATABASE_URL")
-if database_url:
-    config.set_main_option("sqlalchemy.url", database_url)
+# 从统一配置系统获取 database_url，确保与应用使用同一配置源
+settings = get_shared_settings()
+if settings.database_url:
+    config.set_main_option("sqlalchemy.url", settings.database_url)
 
 # Interpret the config file for Python logging.
 # This line sets up loggers basically.

alembic/versions/052_generation_task_bgm_config.py

@@ -0,0 +1,64 @@
+"""#642 - 生成任务新增 bgm_config 字段
+
+Revision ID: 052_generation_task_bgm_config
+Revises: 051_generation_task_resolution
+Create Date: 2026-07-25
+
+Changes:
+1. generation_tasks 表新增 bgm_config 字段（JSON类型），存储用户自定义BGM配置
+2. 为空时使用默认空字典
+
+背景：
+#642 一键生成支持自定义BGM 功能在 SQLAlchemy 模型中加了 bgm_config 字段，
+但遗漏了 alembic migration，导致 staging 环境数据库没有该列，
+创建生成任务时直接 500。
+"""
+
+import sqlalchemy as sa
+
+from alembic import context, op
+
+revision = "052_generation_task_bgm_config"
+down_revision = "051_generation_task_resolution"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    if context.get_context().dialect.name == "postgresql":
+        # 检查列是否已存在（幂等）
+        result = conn.execute(
+            sa.text(
+                "SELECT column_name FROM information_schema.columns "
+                "WHERE table_name = 'generation_tasks' AND column_name = 'bgm_config'"
+            )
+        )
+        if result.scalar() is not None:
+            return
+
+    op.add_column(
+        "generation_tasks",
+        sa.Column(
+            "bgm_config",
+            sa.JSON,
+            nullable=False,
+            server_default=sa.text("'{}'::json"),
+        ),
+    )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    if context.get_context().dialect.name == "postgresql":
+        # 检查列是否存在（幂等）
+        result = conn.execute(
+            sa.text(
+                "SELECT column_name FROM information_schema.columns "
+                "WHERE table_name = 'generation_tasks' AND column_name = 'bgm_config'"
+            )
+        )
+        if result.scalar() is None:
+            return
+
+    op.drop_column("generation_tasks", "bgm_config")

apps/api/app/api/router.py

@@ -1,3 +1,4 @@
+from app.api.routes.ai import router as ai_router
 from app.api.routes.asset_diagnosis import router as asset_diagnosis_router
 from app.api.routes.asset_libraries import router as asset_libraries_router
 from app.api.routes.assets import router as assets_router
@@ -9,7 +10,6 @@ from app.api.routes.feature_flags import router as feature_flags_router
 from app.api.routes.generation_tasks import router as generation_tasks_router
 from app.api.routes.health import router as health_check_router
 from app.api.routes.ingest_jobs import router as ingest_jobs_router
-from app.api.routes.ai import router as ai_router
 from app.api.routes.internal_render import router as internal_render_router
 from app.api.routes.projects import router as projects_router
 from app.api.routes.share import router as share_router

apps/api/app/api/routes/ai.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-from typing import List, Literal, Optional
+from typing import List, Literal
 
 from app.services.ai_service import TITLE_STYLES, generate_smart_titles, semantic_match_assets
 from fastapi import APIRouter

apps/api/app/api/routes/generation_tasks.py

@@ -30,7 +30,6 @@ from app.schemas.generation_task import (
     GenerationTaskResponse,
     ListGenerationTasksResponse,
 )
-from app.services.smart_asset_selector import SmartAssetSelector
 from fastapi import APIRouter, Depends, HTTPException
 
 from packages.application import (
@@ -61,6 +60,7 @@ def _to_generation_task_response(task) -> GenerationTaskResponse:
         batch_id=getattr(task, "batch_id", ""),
         video_title=getattr(task, "video_title", ""),
         resolution=getattr(task, "resolution", ""),
+        bgm_config=getattr(task, "bgm_config", {}) or {},
         logs=getattr(task, "logs", "[]"),
         status=task.status,
         progress=task.progress,
@@ -289,6 +289,7 @@ def create_generation_task(
                     batch_id=batch_id,
                     video_title=request.video_title,
                     resolution=request.resolution,
+                    bgm_config=request.bgm_config,
                     auto_retry_enabled=request.auto_retry_enabled,
                     auto_retry_max=request.auto_retry_max,
                 )

apps/api/app/api/routes/health.py

@@ -1,4 +1,4 @@
-from datetime import datetime
+from datetime import datetime, timezone
 
 import psycopg2
 import redis
@@ -13,7 +13,7 @@ router = APIRouter(tags=["Health"])
 async def health_check():
     return {
         "status": "healthy",
-        "timestamp": datetime.utcnow().isoformat(),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
         "version": settings.APP_VERSION,
     }
 
@@ -33,7 +33,7 @@ async def startup_check():
     all_ready = all(check["status"] == "healthy" for check in checks.values())
     response = {
         "status": "started" if all_ready else "starting",
-        "timestamp": datetime.utcnow().isoformat(),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
         "checks": checks,
     }
     if not all_ready:

apps/api/app/api/routes/templates_editor/__init__.py

@@ -0,0 +1,65 @@
+"""模板编辑器 API 路由包.
+
+将原来 2560 行的 templates_editor.py 巨无霸拆分为 12 个模块：
+- schemas.py:        所有 Pydantic model
+- dependencies.py:   依赖注入
+- _utils.py:         工具函数
+- _fallback.py:      自动兜底逻辑
+- draft.py:          草稿管理（详情/更新/发布/版本/回滚）
+- clips.py:          片段管理（CRUD/分割/合并/重排/批量删除/从素材创建）
+- adjustments.py:    片段调整（速度/音量/裁剪/批量调速）
+- bgm.py:            BGM 管理
+- effects.py:        转场 + 滤镜
+- export.py:         导出配置
+- cover.py:          封面管理 + AI 生成封面
+- subtitles.py:      字幕管理
+- ai_features.py:    AI 推荐
+- generation.py:     生成（触发/进度/记录）
+- timeline.py:       时间线
+
+挂载路径: /api/v1/templates/{template_id}/editor/
+"""
+
+from __future__ import annotations
+
+# 向后兼容：测试和其他模块可能直接从 templates_editor 导入这些符号
+from app.auth import get_current_user  # noqa: F401
+from app.dependencies import get_db_session  # noqa: F401
+from fastapi import APIRouter
+
+from .adjustments import router as adjustments_router
+from .ai_features import router as ai_features_router
+from .bgm import router as bgm_router
+from .clips import router as clips_router
+from .cover import router as cover_router
+from .dependencies import get_draft_plan_id, get_editor_services  # noqa: F401
+from .draft import router as draft_router
+from .effects import router as effects_router
+from .export import router as export_router
+from .generation import router as generation_router
+from .subtitles import router as subtitles_router
+from .timeline import router as timeline_router
+
+# 主 router，所有子路由都合并到这里
+router = APIRouter(tags=["Template Editor"])
+
+# 合并所有子模块的路由（不用 include_router 是因为子路由有空路径 ""）
+_sub_routers = [
+    draft_router,
+    clips_router,
+    adjustments_router,
+    bgm_router,
+    effects_router,
+    export_router,
+    cover_router,
+    subtitles_router,
+    ai_features_router,
+    generation_router,
+    timeline_router,
+]
+
+for sub in _sub_routers:
+    for route in sub.routes:
+        router.routes.append(route)
+
+__all__ = ["router"]

apps/api/app/api/routes/templates_editor/_fallback.py

@@ -0,0 +1,163 @@
+"""模板编辑器自动兜底逻辑.
+
+generate_editor_draft 触发生成前的自动修复流程：
+1. draft → editing 状态迁移
+2. 无片段时从模板复制片段配置
+3. 为无素材片段分配指定素材
+4. 项目有素材库时自动选素材
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+from typing import Any
+
+from app.services.edit_plan_service import EditPlanService
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.template_clip_config_repository import (
+    SQLAlchemyTemplateClipConfigRepository,
+)
+from packages.adapters.sqlalchemy_impl.template_repository import (
+    SQLAlchemyTemplateRepository,
+)
+from packages.domain.edit_plan import EditPlanStatus
+
+logger = logging.getLogger(__name__)
+
+
+def _auto_fallback_draft_to_editing(
+    svc: EditPlanService, plan_id: str, plan_check
+) -> None:
+    """自动兜底 1: draft → editing"""
+    if plan_check.status == EditPlanStatus.DRAFT:
+        logger.info("模板编辑器自动兜底: plan=%s draft→editing", plan_id)
+        svc.transition_status(plan_id, EditPlanStatus.EDITING)
+
+
+def _auto_fallback_copy_template_clips(
+    svc: EditPlanService, plan_id: str, plan_check, db: Session
+) -> None:
+    """自动兜底 2: 无片段 + 有 template_id → 从模板复制片段配置"""
+    existing_clips = svc.count_clips(plan_id)
+    if existing_clips == 0 and plan_check.template_id:
+        logger.info(
+            "模板编辑器自动兜底: plan=%s 无片段，从模板 %s 复制片段配置",
+            plan_id,
+            plan_check.template_id,
+        )
+        clip_config_repo = SQLAlchemyTemplateClipConfigRepository(db)
+        configs = clip_config_repo.list_by_template(plan_check.template_id)
+        if configs:
+            for cfg in configs:
+                svc.create_clip(
+                    plan_id=plan_id,
+                    clip_type=cfg.clip_type.value
+                    if hasattr(cfg.clip_type, "value")
+                    else cfg.clip_type,
+                    order=cfg.order,
+                    template_clip_config_id=cfg.id,
+                    duration=cfg.default_duration,
+                    transition_effect=cfg.transition_effect.value
+                    if hasattr(cfg.transition_effect, "value")
+                    else cfg.transition_effect,
+                )
+            logger.info(
+                "模板编辑器自动兜底: plan=%s 从 template_clip_configs 复制了 %d 个片段",
+                plan_id,
+                len(configs),
+            )
+        else:
+            tpl_repo = SQLAlchemyTemplateRepository(db)
+            segments = tpl_repo.list_segments(plan_check.template_id)
+            for seg in segments:
+                avg_duration = (seg.duration_min + seg.duration_max) / 2
+                svc.create_clip(
+                    plan_id=plan_id,
+                    clip_type="main",
+                    order=seg.segment_order,
+                    duration=avg_duration,
+                    config={
+                        "material_type": seg.material_type or "",
+                        "template_segment_id": seg.id,
+                    },
+                )
+            logger.info(
+                "模板编辑器自动兜底: plan=%s 从旧模板 segments 复制了 %d 个片段",
+                plan_id,
+                len(segments),
+            )
+
+
+def _auto_fallback_assign_assets(
+    svc: EditPlanService, plan_id: str, plan_check
+) -> list:
+    """自动兜底 3: 为没有素材的片段分配素材。返回剩余无素材片段列表。"""
+    all_clips = svc.list_clips(plan_id)
+    clips_without_asset = [c for c in all_clips if not c.asset_id]
+    config_asset_ids = (plan_check.config or {}).get("asset_ids", [])
+
+    if clips_without_asset and config_asset_ids:
+        logger.info(
+            "模板编辑器自动兜底3: plan=%s 为 %d 个无素材片段分配 %d 个指定素材",
+            plan_id,
+            len(clips_without_asset),
+            len(config_asset_ids),
+        )
+        for i, clip in enumerate(clips_without_asset):
+            asset_idx = i % len(config_asset_ids)
+            svc.assign_asset(clip.id, config_asset_ids[asset_idx])
+        logger.info("模板编辑器自动兜底3: plan=%s 素材分配完成", plan_id)
+        clips_without_asset = []
+
+    return clips_without_asset
+
+
+def _auto_fallback_auto_material_mode(
+    svc: EditPlanService,
+    plan_id: str,
+    plan_check,
+    clips_without_asset: list,
+    asset_library_repo: Any,
+    asset_repo: Any,
+) -> None:
+    """自动兜底 4: 项目有视频素材库时自动选素材"""
+    if not clips_without_asset:
+        return
+    if not plan_check.project_id:
+        return
+
+    logger.info(
+        "模板编辑器自动兜底4: plan=%s 自动选素材分配给 %d 个无素材片段",
+        plan_id,
+        len(clips_without_asset),
+    )
+    libs = asset_library_repo.find_by_project(plan_check.project_id)
+    video_lib = None
+    for lib in libs:
+        lib_kind = lib.kind.value if hasattr(lib.kind, "value") else lib.kind
+        if lib_kind == "video":
+            video_lib = lib
+            break
+
+    if video_lib:
+        assets = asset_repo.find_by_library(video_lib.id)
+        ready_videos = [
+            a
+            for a in assets
+            if (a.status.value if hasattr(a.status, "value") else a.status) == "ready"
+            and a.mime_type
+            and a.mime_type.startswith("video")
+        ]
+        if ready_videos:
+            random.shuffle(ready_videos)
+            for i, clip in enumerate(clips_without_asset):
+                asset = ready_videos[i % len(ready_videos)]
+                svc.assign_asset(clip.id, asset.id)
+            logger.info(
+                "模板编辑器自动兜底4: plan=%s 从素材库 %s 分配了 %d 个素材",
+                plan_id,
+                video_lib.name,
+                len(ready_videos),
+            )

apps/api/app/api/routes/templates_editor/_utils.py

@@ -0,0 +1,109 @@
+"""模板编辑器内部工具函数.
+
+纯函数，不依赖请求上下文。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .schemas import ClipAdjustResponse
+
+# 时间线场景颜色映射
+_CLIP_TYPE_COLORS = {
+    "intro": "#6366f1",
+    "title": "#6366f1",
+    "product": "#818cf8",
+    "showcase": "#10b981",
+    "scene": "#10b981",
+    "subtitle": "#f59e0b",
+    "text": "#f59e0b",
+    "cta": "#ef4444",
+    "outro": "#ef4444",
+    "voiceover": "#8b5cf6",
+    "transition": "#64748b",
+}
+_DEFAULT_COLOR = "#6366f1"
+
+
+def _format_time(seconds: float) -> str:
+    """秒数格式化为 m:ss"""
+    m = int(seconds) // 60
+    s = int(seconds) % 60
+    return f"{m}:{s:02d}"
+
+
+def _clip_type_to_scene_label(clip_type: str, text_content: str) -> str:
+    """片段类型转时间线场景标签"""
+    type_labels = {
+        "intro": "开场",
+        "title": "标题",
+        "product": "产品展示",
+        "showcase": "场景展示",
+        "scene": "场景",
+        "subtitle": "字幕",
+        "text": "文字",
+        "cta": "结尾 CTA",
+        "outro": "结尾",
+        "voiceover": "配音",
+        "transition": "转场",
+    }
+    label = type_labels.get(clip_type, clip_type or "片段")
+    if text_content:
+        short = text_content[:20].strip()
+        if short:
+            return f"{label} - {short}"
+    return label
+
+
+# ── 片段调整相关工具 ────────────────────────────────────────────────────────
+
+
+def _get_clip_config(clip) -> dict:
+    """安全获取 clip.config"""
+    config = getattr(clip, "config", {}) or {}
+    if not isinstance(config, dict):
+        config = {}
+    return config
+
+
+def _get_adjust_volume(clip) -> float:
+    """获取片段音量"""
+    config = _get_clip_config(clip)
+    return float(config.get("volume", 1.0))
+
+
+def _get_adjust_trim(clip) -> tuple[float, float]:
+    """获取片段裁剪起止"""
+    config = _get_clip_config(clip)
+    trim_start = float(config.get("trim_start", 0.0))
+    trim_end = float(config.get("trim_end", 0.0))
+    return trim_start, trim_end
+
+
+def _build_adjust_response(clip) -> ClipAdjustResponse:
+    """构造片段调整响应"""
+    trim_start, trim_end = _get_adjust_trim(clip)
+    return ClipAdjustResponse(
+        clip_id=clip.id,
+        speed=clip.playback_speed,
+        volume=_get_adjust_volume(clip),
+        trim_start=trim_start,
+        trim_end=trim_end,
+        duration=clip.duration,
+    )
+
+
+def _validate_trim(trim_start: float, trim_end: float, total_duration: float) -> None:
+    """校验裁剪时长合法性"""
+    if trim_start + trim_end >= total_duration:
+        raise ValueError(
+            f"裁剪总时长（{trim_start + trim_end:.2f}s）不能大于等于片段总时长（{total_duration:.2f}s）"
+        )
+
+
+def _clip_value(value: Any) -> str:
+    """获取枚举/字符串值的统一方法"""
+    if hasattr(value, "value"):
+        return value.value
+    return str(value)

apps/api/app/api/routes/templates_editor/adjustments.py

@@ -0,0 +1,167 @@
+"""片段调整路由.
+
+端点：
+- PUT /clips/{clip_id}/speed         调速
+- PUT /clips/{clip_id}/volume        调音量
+- PUT /clips/{clip_id}/trim          裁剪
+- PUT /clips/{clip_id}/adjustments   统一调整
+- POST /clips/batch-speed            批量调速
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException
+
+from ._utils import _build_adjust_response, _get_adjust_trim, _get_clip_config, _validate_trim
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import (
+    BatchSpeedRequest,
+    BatchSpeedResponse,
+    ClipAdjustmentsRequest,
+    ClipAdjustResponse,
+    SpeedAdjustRequest,
+    TrimAdjustRequest,
+    VolumeAdjustRequest,
+)
+
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.put("/clips/{clip_id}/speed", response_model=ClipAdjustResponse)
+def adjust_editor_clip_speed(
+    template_id: str,
+    clip_id: str,
+    body: SpeedAdjustRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipAdjustResponse:
+    """调整片段播放速度"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    updated = plan_svc.update_clip(clip_id, playback_speed=body.speed)
+    return _build_adjust_response(updated)
+
+
+@router.put("/clips/{clip_id}/volume", response_model=ClipAdjustResponse)
+def adjust_editor_clip_volume(
+    template_id: str,
+    clip_id: str,
+    body: VolumeAdjustRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipAdjustResponse:
+    """调整片段音量"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    config = dict(_get_clip_config(clip))
+    config["volume"] = body.volume
+    updated = plan_svc.update_clip(clip_id, config=config)
+    return _build_adjust_response(updated)
+
+
+@router.put("/clips/{clip_id}/trim", response_model=ClipAdjustResponse)
+def adjust_editor_clip_trim(
+    template_id: str,
+    clip_id: str,
+    body: TrimAdjustRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipAdjustResponse:
+    """裁剪片段（trim in/out）"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    try:
+        _validate_trim(body.trim_start, body.trim_end, clip.duration)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+    config = dict(_get_clip_config(clip))
+    config["trim_start"] = body.trim_start
+    config["trim_end"] = body.trim_end
+    updated = plan_svc.update_clip(clip_id, config=config)
+    return _build_adjust_response(updated)
+
+
+@router.put("/clips/{clip_id}/adjustments", response_model=ClipAdjustResponse)
+def adjust_editor_clip_all(
+    template_id: str,
+    clip_id: str,
+    body: ClipAdjustmentsRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipAdjustResponse:
+    """统一调整片段的 speed / volume / trim"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    update_kwargs: dict[str, Any] = {}
+    config_updates: dict[str, Any] = {}
+
+    if body.speed is not None:
+        update_kwargs["playback_speed"] = body.speed
+    if body.volume is not None:
+        config_updates["volume"] = body.volume
+    if body.trim_start is not None:
+        config_updates["trim_start"] = body.trim_start
+    if body.trim_end is not None:
+        config_updates["trim_end"] = body.trim_end
+
+    current_trim_start, current_trim_end = _get_adjust_trim(clip)
+    new_trim_start = body.trim_start if body.trim_start is not None else current_trim_start
+    new_trim_end = body.trim_end if body.trim_end is not None else current_trim_end
+
+    if body.trim_start is not None or body.trim_end is not None:
+        try:
+            _validate_trim(new_trim_start, new_trim_end, clip.duration)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e)) from e
+
+    if config_updates:
+        config = dict(_get_clip_config(clip))
+        config.update(config_updates)
+        update_kwargs["config"] = config
+
+    if not update_kwargs:
+        return _build_adjust_response(clip)
+
+    updated = plan_svc.update_clip(clip_id, **update_kwargs)
+    return _build_adjust_response(updated)
+
+
+@router.post("/clips/batch-speed", response_model=BatchSpeedResponse)
+def batch_adjust_editor_speed(
+    template_id: str,
+    body: BatchSpeedRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> BatchSpeedResponse:
+    """批量调整草稿内所有片段的播放速度"""
+    _, plan_svc = services
+    clips = plan_svc.list_clips(plan_id, limit=500, skip=0)
+    count = 0
+    for clip in clips:
+        plan_svc.update_clip(clip.id, playback_speed=body.speed)
+        count += 1
+
+    return BatchSpeedResponse(updated_count=count, plan_id=plan_id)

apps/api/app/api/routes/templates_editor/ai_features.py

@@ -0,0 +1,121 @@
+"""AI 功能路由.
+
+端点：
+- POST /ai-recommend       AI 推荐片段方案
+"""
+
+from __future__ import annotations
+
+import logging
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_db_session
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from packages.domain.config_schemas import normalize_plan_config
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import AIRecommendRequest, AIRecommendResponse
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.post("/ai-recommend", response_model=AIRecommendResponse)
+def editor_ai_recommend(
+    template_id: str,
+    body: AIRecommendRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> AIRecommendResponse:
+    """AI 推荐片段方案"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    plan_status = plan.status.value if hasattr(plan.status, "value") else plan.status
+    if plan_status not in ("draft", "editing"):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="当前草稿状态不支持AI推荐，请先编辑后再试",
+        )
+
+    from packages.shared.ai_service import run_ai_recommend
+
+    result = run_ai_recommend(
+        plan_id=plan_id,
+        template_id=plan.template_id,
+        asset_ids=body.asset_ids,
+        editing_mode=body.editing_mode,
+        target_duration=body.target_duration,
+    )
+
+    try:
+        plan_svc.delete_all_clips(plan_id)
+
+        for clip_data in result["clips"]:
+            plan_svc.create_clip(
+                plan_id=plan_id,
+                clip_type=clip_data["clip_type"],
+                order=clip_data["order"],
+                text_content=clip_data.get("text_content", ""),
+                duration=clip_data["duration"],
+                transition_effect=clip_data.get("transition_effect", "cut"),
+                asset_id=clip_data.get("asset_id", ""),
+                start_time=clip_data.get("start_time", 0.0),
+                config=clip_data.get("config", {}),
+            )
+
+        normalized_config = normalize_plan_config(result.get("config", {}))
+        plan_svc.update_plan(
+            plan_id,
+            config=normalized_config,
+            total_duration=result["total_duration"],
+        )
+    except Exception as _e:
+        logger.exception(
+            "模板编辑器AI推荐写入失败: template_id=%s plan_id=%s",
+            template_id,
+            plan_id,
+        )
+        try:
+            db.rollback()
+        except Exception:
+            pass
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="AI推荐结果保存失败，请稍后重试",
+        ) from _e
+
+    logger.info(
+        "模板编辑器AI推荐: template_id=%s plan_id=%s clips=%d duration=%.1f by user=%s",
+        template_id,
+        plan_id,
+        len(result["clips"]),
+        result["total_duration"],
+        current_user.user.id,
+    )
+
+    return AIRecommendResponse(
+        plan_id=plan_id,
+        clips=[
+            {
+                "clip_type": c["clip_type"],
+                "order": c["order"],
+                "text_content": c.get("text_content", ""),
+                "duration": c["duration"],
+                "transition_effect": c.get("transition_effect", "cut"),
+                "asset_id": c.get("asset_id", ""),
+                "start_time": c.get("start_time", 0.0),
+                "config": c.get("config", {}),
+            }
+            for c in result["clips"]
+        ],
+        config=normalized_config,
+        total_duration=result["total_duration"],
+        confidence=result["confidence"],
+    )

apps/api/app/api/routes/templates_editor/bgm.py

@@ -0,0 +1,133 @@
+"""BGM 管理路由.
+
+端点：
+- GET  /bgm              获取 BGM 配置
+- PUT  /bgm              更新 BGM 配置
+- GET  /bgm/presets      预设 BGM 列表
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import BGMConfigUpdateRequest
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.get("/bgm", response_model=dict[str, Any])
+def get_editor_bgm(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """获取草稿的 BGM 配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+    config = plan.config or {}
+    return {
+        "plan_id": plan.id,
+        "bgm": config.get("bgm", {}),
+    }
+
+
+@router.put("/bgm", response_model=dict[str, Any])
+def update_editor_bgm(
+    template_id: str,
+    body: BGMConfigUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+):
+    """更新草稿的 BGM 配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    config = dict(plan.config) if plan.config else {}
+    current_bgm = dict(config.get("bgm", {}))
+    update_data = body.model_dump(exclude_none=True)
+    current_bgm.update(update_data)
+
+    if current_bgm.get("enabled"):
+        has_source = any(
+            current_bgm.get(key)
+            for key in ("asset_id", "preset_id", "audio_url")
+            if current_bgm.get(key)
+        )
+        if not has_source:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="启用 BGM 时需要指定素材来源（asset_id / preset_id / audio_url）",
+            )
+
+    config["bgm"] = current_bgm
+    updated_plan = plan_svc.update_plan_config(plan_id, config)
+
+    logger.info(
+        "模板编辑器更新BGM: template_id=%s plan_id=%s enabled=%s by user=%s",
+        template_id,
+        plan_id,
+        current_bgm.get("enabled", False),
+        current_user.user.id,
+    )
+
+    return {
+        "plan_id": updated_plan.id,
+        "bgm": current_bgm,
+    }
+
+
+@router.get("/bgm/presets", response_model=dict[str, Any])
+def list_editor_bgm_presets(
+    style: str | None = Query(default=None, description="按风格筛选"),
+    keyword: str | None = Query(default=None, description="关键词搜索"),
+    skip: int = Query(default=0, ge=0, description="分页偏移"),
+    limit: int = Query(default=50, ge=1, le=200, description="每页数量"),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """获取预设 BGM 列表"""
+    from packages.domain.preset_bgm import (
+        BGM_STYLES,
+        PRESET_BGM_LIBRARY,
+        list_preset_bgm_by_style,
+        search_preset_bgm,
+    )
+
+    bgm_list = PRESET_BGM_LIBRARY
+    if keyword:
+        bgm_list = search_preset_bgm(keyword)
+    elif style:
+        bgm_list = list_preset_bgm_by_style(style)
+
+    total = len(bgm_list)
+    paged = bgm_list[skip : skip + limit]
+
+    return {
+        "total": total,
+        "skip": skip,
+        "limit": limit,
+        "styles": BGM_STYLES,
+        "items": [
+            {
+                "id": bgm.id,
+                "name": bgm.name,
+                "style": bgm.style,
+                "style_label": BGM_STYLES.get(bgm.style, bgm.style),
+                "duration": bgm.duration,
+                "artist": bgm.artist,
+                "description": bgm.description,
+                "tags": bgm.tags,
+                "audio_url": bgm.audio_url,
+            }
+            for bgm in paged
+        ],
+    }

apps/api/app/api/routes/templates_editor/clips.py

@@ -0,0 +1,318 @@
+"""片段管理路由.
+
+端点：
+- GET    /clips                    片段列表
+- POST   /clips                    创建片段
+- GET    /clips/{clip_id}          片段详情
+- PUT    /clips/{clip_id}          更新片段
+- DELETE /clips/{clip_id}          删除片段
+- POST   /clips/{clip_id}/split    分割片段
+- POST   /clips/merge              合并片段
+- POST   /clips/reorder            重排片段
+- POST   /clips/batch-delete       批量删除
+- POST   /clips/from-assets        从素材创建片段
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import (
+    ClipBatchDeleteRequest,
+    ClipBatchDeleteResponse,
+    ClipReorderRequest,
+    ClipReorderResponse,
+    ClipsFromAssetsRequest,
+    ClipsFromAssetsResponse,
+    EditorClipCreateRequest,
+    EditorClipListResponse,
+    EditorClipResponse,
+    EditorClipUpdateRequest,
+    MergeClipsRequest,
+    SplitClipRequest,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["Template Editor"])
+
+
+def _clip_to_response(clip) -> EditorClipResponse:
+    """统一构造片段响应"""
+    return EditorClipResponse(
+        id=clip.id,
+        plan_id=clip.plan_id,
+        clip_type=clip.clip_type.value
+        if hasattr(clip.clip_type, "value")
+        else str(clip.clip_type),
+        order=clip.order,
+        duration=clip.duration,
+        text_content=clip.text_content or "",
+        transition_effect=clip.transition_effect.value
+        if hasattr(clip.transition_effect, "value")
+        else str(clip.transition_effect),
+        playback_speed=clip.playback_speed or 1.0,
+        config=clip.config or {},
+    )
+
+
+@router.get("/clips", response_model=EditorClipListResponse)
+def list_draft_clips(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    skip: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=500),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """获取草稿的片段列表"""
+    _, plan_svc = services
+    clips = plan_svc.list_clips(plan_id, skip=skip, limit=limit)
+    total = plan_svc.count_clips(plan_id)
+    return EditorClipListResponse(
+        items=[_clip_to_response(c) for c in clips],
+        total=total,
+    )
+
+
+@router.post("/clips", response_model=EditorClipResponse, status_code=status.HTTP_201_CREATED)
+def create_draft_clip(
+    template_id: str,
+    req: EditorClipCreateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """在草稿中创建新片段"""
+    _, plan_svc = services
+    try:
+        clip = plan_svc.create_clip(
+            plan_id,
+            clip_type=req.clip_type,
+            order=req.order,
+            duration=req.duration,
+            text_content=req.text_content,
+            transition_effect=req.transition_effect,
+            config=req.config,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return _clip_to_response(clip)
+
+
+@router.put("/clips/{clip_id}", response_model=EditorClipResponse)
+def update_draft_clip(
+    template_id: str,
+    clip_id: str,
+    req: EditorClipUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """更新草稿中的片段"""
+    _, plan_svc = services
+    try:
+        clip = plan_svc.update_clip(
+            clip_id,
+            order=req.order,
+            duration=req.duration,
+            text_content=req.text_content,
+            transition_effect=req.transition_effect,
+            playback_speed=req.playback_speed,
+            config=req.config,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return _clip_to_response(clip)
+
+
+@router.delete("/clips/{clip_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_draft_clip(
+    template_id: str,
+    clip_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """删除草稿中的片段"""
+    _, plan_svc = services
+    success = plan_svc.delete_clip(clip_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="片段不存在")
+    return None
+
+
+@router.get("/clips/{clip_id}", response_model=EditorClipResponse)
+def get_draft_clip_detail(
+    template_id: str,
+    clip_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """获取草稿中的片段详情"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if clip is None:
+        raise HTTPException(status_code=404, detail="片段不存在")
+    if clip.plan_id != plan_id:
+        raise HTTPException(status_code=404, detail="片段不存在")
+    return _clip_to_response(clip)
+
+
+@router.post("/clips/{clip_id}/split", response_model=dict[str, Any], status_code=status.HTTP_200_OK)
+def split_draft_clip(
+    template_id: str,
+    clip_id: str,
+    body: SplitClipRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """将一个片段从指定时间点分割为两个片段"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if clip is None or clip.plan_id != plan_id:
+        raise HTTPException(status_code=404, detail="片段不存在")
+    try:
+        result = plan_svc.split_clip(clip_id, body.split_time)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)
+        ) from exc
+    left = result["left_clip"]
+    right = result["right_clip"]
+    return {
+        "left_clip": {
+            "id": left.id,
+            "plan_id": left.plan_id,
+            "clip_type": left.clip_type,
+            "order": left.order,
+            "duration": left.duration,
+            "start_time": left.start_time,
+        },
+        "right_clip": {
+            "id": right.id,
+            "plan_id": right.plan_id,
+            "clip_type": right.clip_type,
+            "order": right.order,
+            "duration": right.duration,
+            "start_time": right.start_time,
+        },
+    }
+
+
+@router.post("/clips/merge", response_model=dict[str, Any], status_code=status.HTTP_200_OK)
+def merge_draft_clips(
+    template_id: str,
+    body: MergeClipsRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """将多个连续的同类型片段合并为一个片段"""
+    _, plan_svc = services
+    for cid in body.clip_ids:
+        clip = plan_svc.get_clip(cid)
+        if clip is None or clip.plan_id != plan_id:
+            raise HTTPException(status_code=404, detail=f"片段不存在: {cid}")
+    try:
+        merged = plan_svc.merge_clips(body.clip_ids)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)
+        ) from exc
+    return {
+        "id": merged.id,
+        "plan_id": merged.plan_id,
+        "clip_type": merged.clip_type,
+        "order": merged.order,
+        "duration": merged.duration,
+        "text_content": merged.text_content,
+    }
+
+
+@router.post("/clips/reorder", response_model=ClipReorderResponse)
+def reorder_editor_clips(
+    template_id: str,
+    body: ClipReorderRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipReorderResponse:
+    """批量重排片段顺序"""
+    _, plan_svc = services
+    count = 0
+    for item in body.items:
+        try:
+            plan_svc.update_clip(item.clip_id, order=item.new_order)
+            count += 1
+        except ValueError:
+            pass
+
+    return ClipReorderResponse(updated_count=count, plan_id=plan_id)
+
+
+@router.post("/clips/batch-delete", response_model=ClipBatchDeleteResponse)
+def batch_delete_editor_clips(
+    template_id: str,
+    body: ClipBatchDeleteRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipBatchDeleteResponse:
+    """批量删除片段"""
+    _, plan_svc = services
+    deleted = 0
+    for clip_id in body.clip_ids:
+        if plan_svc.delete_clip(clip_id):
+            deleted += 1
+
+    return ClipBatchDeleteResponse(deleted_count=deleted, plan_id=plan_id)
+
+
+@router.post("/clips/from-assets", response_model=ClipsFromAssetsResponse)
+def create_clips_from_assets_editor(
+    template_id: str,
+    body: ClipsFromAssetsRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> ClipsFromAssetsResponse:
+    """从素材批量创建片段"""
+    _, plan_svc = services
+    clips = []
+    for i, asset_id in enumerate(body.asset_ids):
+        try:
+            clip = plan_svc.create_clip(
+                plan_id,
+                clip_type="main",
+                order=body.start_order + i if hasattr(body, "start_order") else i,
+                duration=5.0,
+                asset_id=asset_id,
+            )
+            clips.append(clip)
+        except ValueError:
+            pass
+
+    logger.info(
+        "模板编辑器从素材创建片段: template_id=%s plan_id=%s count=%d by user=%s",
+        template_id,
+        plan_id,
+        len(clips),
+        current_user.user.id,
+    )
+
+    return ClipsFromAssetsResponse(
+        created_count=len(clips),
+        plan_id=plan_id,
+        clip_ids=[c.id for c in clips],
+    )

apps/api/app/api/routes/templates_editor/cover.py

@@ -0,0 +1,209 @@
+"""封面管理路由.
+
+端点：
+- GET  /cover              封面配置
+- PUT  /cover              更新封面
+- POST /cover/extract      抽帧生成封面
+- POST /cover/smart        智能选帧
+- POST /generate-cover     AI 生成封面
+"""
+
+from __future__ import annotations
+
+import logging
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException
+
+from packages.domain.config_schemas import normalize_plan_config
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import (
+    CoverConfigResponse,
+    CoverExtractRequest,
+    CoverGenerateResponse,
+    CoverSmartRequest,
+    CoverUpdateRequest,
+    GenerateCoverRequest,
+    GenerateCoverResponse,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.get("/cover", response_model=CoverConfigResponse)
+def get_editor_cover(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> CoverConfigResponse:
+    """获取草稿封面配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+    config = plan.config or {}
+    cover_config = config.get("cover", {})
+
+    return CoverConfigResponse(
+        type=cover_config.get("cover_type", "auto"),
+        image_url=cover_config.get("cover_image_url", ""),
+        frame_time=cover_config.get("frame_time", 0.0),
+    )
+
+
+@router.put("/cover", response_model=CoverConfigResponse)
+def update_editor_cover(
+    template_id: str,
+    body: CoverUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> CoverConfigResponse:
+    """更新草稿封面配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    config = dict(plan.config) if plan.config else {}
+    current_cover = dict(config.get("cover", {}))
+    update_data = body.model_dump(exclude_none=True)
+    current_cover.update(update_data)
+
+    config["cover"] = current_cover
+    normalized = normalize_plan_config(config)
+    plan_svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
+
+    return CoverConfigResponse(
+        type=current_cover.get("cover_type", "auto"),
+        image_url=current_cover.get("cover_image_url", ""),
+        frame_time=current_cover.get("frame_time", 0.0),
+    )
+
+
+@router.post("/cover/extract", response_model=CoverGenerateResponse)
+def extract_editor_cover(
+    template_id: str,
+    body: CoverExtractRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> CoverGenerateResponse:
+    """从指定片段抽帧生成封面"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    clip = plan_svc.get_clip(body.clip_id)
+    if not clip or clip.plan_id != plan_id:
+        raise HTTPException(status_code=400, detail="片段不存在或不属于当前草稿")
+
+    cover_url = f"cover/extract/{plan_id}_{body.clip_id}_{body.frame_time}.jpg"
+
+    config = dict(plan.config) if plan.config else {}
+    cover_config = dict(config.get("cover", {}))
+    cover_config.update(
+        {
+            "cover_type": "extract",
+            "cover_image_url": cover_url,
+            "clip_id": body.clip_id,
+            "frame_time": body.frame_time,
+        }
+    )
+    config["cover"] = cover_config
+    normalized = normalize_plan_config(config)
+    plan_svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
+
+    logger.info(
+        "模板编辑器封面抽帧: template_id=%s plan_id=%s clip_id=%s by user=%s",
+        template_id,
+        plan_id,
+        body.clip_id,
+        current_user.user.id,
+    )
+
+    return CoverGenerateResponse(
+        type="extract",
+        image_url=cover_url,
+        frame_time=body.frame_time,
+    )
+
+
+@router.post("/cover/smart", response_model=CoverGenerateResponse)
+def smart_editor_cover(
+    template_id: str,
+    body: CoverSmartRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> CoverGenerateResponse:
+    """智能选帧生成封面"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    cover_url = f"cover/smart/{plan_id}_smart.jpg"
+    strategy = getattr(body, "strategy", "auto")
+
+    config = dict(plan.config) if plan.config else {}
+    cover_config = dict(config.get("cover", {}))
+    cover_config.update(
+        {
+            "cover_type": "smart",
+            "cover_image_url": cover_url,
+            "strategy": strategy,
+        }
+    )
+    config["cover"] = cover_config
+    normalized = normalize_plan_config(config)
+    plan_svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
+
+    logger.info(
+        "模板编辑器智能封面: template_id=%s plan_id=%s strategy=%s by user=%s",
+        template_id,
+        plan_id,
+        strategy,
+        current_user.user.id,
+    )
+
+    return CoverGenerateResponse(
+        type="smart",
+        image_url=cover_url,
+        frame_time=None,
+    )
+
+
+@router.post("/generate-cover", response_model=GenerateCoverResponse)
+def editor_generate_cover(
+    template_id: str,
+    body: GenerateCoverRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> GenerateCoverResponse:
+    """AI 生成封面"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    from packages.shared.ai_service import run_generate_cover
+
+    cover_data = run_generate_cover(
+        plan_id=plan_id,
+        asset_ids=body.asset_ids,
+        cover_type=body.cover_type,
+        frame_time=body.frame_time,
+    )
+
+    current_config = dict(plan.config) if plan.config else {}
+    current_config["cover"] = cover_data
+    normalized = normalize_plan_config(current_config)
+    plan_svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
+
+    logger.info(
+        "模板编辑器封面生成: template_id=%s plan_id=%s type=%s by user=%s",
+        template_id,
+        plan_id,
+        body.cover_type,
+        current_user.user.id,
+    )
+
+    return GenerateCoverResponse(plan_id=plan_id, cover=cover_data)

apps/api/app/api/routes/templates_editor/dependencies.py

@@ -0,0 +1,141 @@
+"""模板编辑器依赖注入.
+
+核心依赖：
+- get_editor_services: 获取模板+计划服务
+- get_draft_plan_id: 根据 template_id 获取或创建草稿，返回 plan_id
+- _check_queue_limits: 生成队列限流检查
+"""
+
+from __future__ import annotations
+
+import logging
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.core.task_enqueue import GLOBAL_PENDING_LIMIT, USER_PENDING_LIMIT
+from app.dependencies import get_db_session
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.template_repository import (
+    SQLAlchemyTemplateRepository,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def get_editor_services(
+    db: Session = Depends(get_db_session),
+) -> tuple[EditTemplateService, EditPlanService]:
+    """获取模板编辑器所需的两个服务"""
+    return EditTemplateService(db), EditPlanService(db)
+
+
+def get_draft_plan_id(
+    template_id: str,
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    db: Session = Depends(get_db_session),
+) -> str:
+    """路径依赖：根据 template_id 获取或创建草稿，返回 plan_id.
+
+    这是模板编辑器路由的核心依赖——所有编辑器端点都先经过这里，
+    确保 template_id → plan_id 的映射始终存在。
+
+    兼容策略：优先从新模板系统（edit_templates 表）查找，
+    若不存在则回退到旧模板系统（templates 表），确保用户自建模板可用。
+    """
+    tpl_svc, plan_svc = services
+    user_id = str(current_user.user.id)
+
+    # 1. 草稿已存在 → 直接返回
+    draft = tpl_svc.get_template_draft(template_id)
+    if draft is not None:
+        return draft.id
+
+    # 2. 新系统有模板 → 用新服务创建草稿
+    if tpl_svc.get_template(template_id) is not None:
+        draft = tpl_svc.create_template_draft(template_id, user_id=user_id)
+        return draft.id
+
+    # 3. 回退到旧模板系统（templates 表）
+    old_repo = SQLAlchemyTemplateRepository(db)
+    old_template = old_repo.get(template_id, user_id=user_id)
+    if old_template is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="模板不存在")
+
+    # 4. 基于旧模板创建草稿计划
+    from app.services.plan_generator_service import PlanGeneratorService
+
+    from packages.domain.edit_template import EditTemplate, EditTemplateStatus
+    from packages.domain.template_clip_config import ClipType, TemplateClipConfig
+
+    # 构造伪 EditTemplate 对象（只填 generate_from_template 需要的字段）
+    pseudo_template = EditTemplate(
+        id=old_template.id,
+        name=old_template.name,
+        editing_mode=old_template.mode,
+        status=EditTemplateStatus.ACTIVE,
+    )
+
+    # 将旧模板 segments 转换为 clip_configs
+    clip_configs: list[TemplateClipConfig] = []
+    for seg in old_template.segments or []:
+        clip_configs.append(
+            TemplateClipConfig(
+                id=f"seg_{seg.id}",
+                template_id=old_template.id,
+                clip_type=ClipType.MAIN,
+                order=seg.segment_order,
+                min_duration=seg.duration_min,
+                max_duration=seg.duration_max,
+            )
+        )
+
+    generator = PlanGeneratorService(db)
+    result = generator.generate_from_template(
+        template=pseudo_template,
+        clip_configs=clip_configs,
+        asset_ids=[],
+        created_by_user_id=user_id,
+        name=f"{old_template.name} - 草稿",
+    )
+    plan = result["plan"]
+
+    # 标记为模板草稿（后续可复用 tpl_svc.get_template_draft 的查找逻辑）
+    plan_svc.update_plan_config(plan.id, {"is_template_draft": True})
+
+    logger.info(
+        "旧模板自动创建草稿: template_id=%s draft_plan_id=%s user_id=%s",
+        template_id,
+        plan.id,
+        user_id,
+    )
+    return plan.id
+
+
+def _check_queue_limits(gen_task_repo, user_id: str) -> None:
+    """队列限流预检查"""
+    try:
+        has_count = (
+            hasattr(gen_task_repo, "count_pending_by_user")
+            and hasattr(gen_task_repo, "count_pending_total")
+        )
+        if has_count:
+            user_pending = gen_task_repo.count_pending_by_user(user_id)
+            global_pending = gen_task_repo.count_pending_total()
+            if user_pending >= USER_PENDING_LIMIT:
+                raise HTTPException(
+                    status_code=429,
+                    detail=f"您的待处理任务过多（当前 {user_pending}/{USER_PENDING_LIMIT}），请等待完成后再提交",
+                )
+            if global_pending >= GLOBAL_PENDING_LIMIT:
+                raise HTTPException(
+                    status_code=503,
+                    detail="系统繁忙，请稍后再试",
+                )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.warning("[模板编辑器队列限流] 检查失败，跳过: %s", e)

apps/api/app/api/routes/templates_editor/draft.py

@@ -0,0 +1,164 @@
+"""草稿管理路由.
+
+端点：
+- GET    /              获取草稿详情
+- PUT    /              更新草稿
+- POST   /publish       发布草稿到模板
+- GET    /versions      模板版本历史
+- POST   /rollback      回滚到指定版本
+"""
+
+from __future__ import annotations
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import (
+    EditorDraftResponse,
+    EditorPublishResponse,
+    EditorRollbackRequest,
+    EditorRollbackResponse,
+    EditorTemplateVersionItem,
+    EditorUpdateRequest,
+    EditorVersionListResponse,
+)
+
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.get("", response_model=EditorDraftResponse)
+def get_editor_draft(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """获取模板编辑器草稿详情
+
+    首次访问时自动创建草稿。
+    """
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+    clips = plan_svc.list_clips(plan_id)
+    return EditorDraftResponse(
+        plan_id=plan.id,
+        template_id=plan.template_id,
+        name=plan.name,
+        status=plan.status.value if hasattr(plan.status, "value") else str(plan.status),
+        config=plan.config or {},
+        total_duration=plan.total_duration,
+        clip_count=len(clips),
+    )
+
+
+@router.put("", response_model=EditorDraftResponse)
+def update_editor_draft(
+    template_id: str,
+    req: EditorUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """更新模板编辑器草稿"""
+    _, plan_svc = services
+    plan = plan_svc.update_plan(
+        plan_id,
+        name=req.name,
+        config=req.config,
+        total_duration=req.total_duration,
+    )
+    clips = plan_svc.list_clips(plan_id)
+    return EditorDraftResponse(
+        plan_id=plan.id,
+        template_id=plan.template_id,
+        name=plan.name,
+        status=plan.status.value if hasattr(plan.status, "value") else str(plan.status),
+        config=plan.config or {},
+        total_duration=plan.total_duration,
+        clip_count=len(clips),
+    )
+
+
+@router.post("/publish", response_model=EditorPublishResponse, status_code=status.HTTP_200_OK)
+def publish_draft_to_template(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """将草稿发布（同步）到正式模板
+
+    草稿的 config 和 clips 会同步覆盖到模板，事务保证一致性。
+    """
+    tpl_svc, plan_svc = services
+    try:
+        tpl = tpl_svc.publish_template_from_draft(template_id, plan_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    clips = plan_svc.list_clips(plan_id)
+    return EditorPublishResponse(
+        template_id=tpl.id,
+        status="published",
+        clip_count=len(clips),
+        version=tpl.version,
+    )
+
+
+@router.get("/versions", response_model=EditorVersionListResponse)
+def list_template_versions(
+    template_id: str,
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+    limit: int = Query(default=50, ge=1, le=200),
+):
+    """查询模板发布版本历史"""
+    tpl_svc, _ = services
+    versions = tpl_svc.list_template_versions(template_id, limit=limit)
+    items = [
+        EditorTemplateVersionItem(
+            version=v.version,
+            name=v.name,
+            editing_mode=v.editing_mode,
+            clip_count=len(v.clip_configs),
+            change_note=v.change_note,
+            published_by=v.published_by,
+            created_at=(
+                v.created_at.isoformat()
+                if hasattr(v.created_at, "isoformat")
+                else str(v.created_at)
+            ),
+        )
+        for v in versions
+    ]
+    return EditorVersionListResponse(versions=items, total=len(items))
+
+
+@router.post("/rollback", response_model=EditorRollbackResponse, status_code=status.HTTP_200_OK)
+def rollback_template(
+    template_id: str,
+    request: EditorRollbackRequest,
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """回滚模板到指定历史版本
+
+    回滚本身也是一次发布，版本号会 +1，可以再次回滚。
+    """
+    tpl_svc, _ = services
+    try:
+        tpl = tpl_svc.rollback_to_version(template_id, request.version)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    clip_configs = tpl_svc.list_clip_configs(template_id)
+    return EditorRollbackResponse(
+        template_id=tpl.id,
+        status="rolled_back",
+        rollback_to_version=request.version,
+        new_version=tpl.version,
+        clip_count=len(clip_configs),
+    )

apps/api/app/api/routes/templates_editor/effects.py

@@ -0,0 +1,195 @@
+"""转场 & 滤镜路由.
+
+端点：
+- GET  /transition-presets           转场预设列表
+- PUT  /clips/{clip_id}/transition   单片段转场
+- POST /transitions/batch            批量转场
+- GET  /filter-presets               滤镜预设列表
+- GET  /filter                       滤镜配置
+- PUT  /filter                       更新滤镜
+"""
+
+from __future__ import annotations
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException
+
+from packages.domain.config_schemas import normalize_plan_config
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import (
+    BatchTransitionRequest,
+    BatchTransitionResponse,
+    ClipTransitionResponse,
+    FilterConfigResponse,
+    FilterPresetListResponse,
+    FilterUpdateRequest,
+    TransitionPresetListResponse,
+    TransitionUpdateRequest,
+)
+
+router = APIRouter(tags=["Template Editor"])
+
+
+# ── 转场 ────────────────────────────────────────────────────────────────────
+
+
+@router.get("/transition-presets", response_model=TransitionPresetListResponse)
+def list_editor_transition_presets(
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> TransitionPresetListResponse:
+    """获取转场预设列表"""
+    from packages.domain.transition_presets import TRANSITION_PRESETS
+
+    items = [
+        {
+            "id": p["id"],
+            "name": p["name"],
+            "category": p.get("category", "通用"),
+            "duration": p.get("default_duration", 0.5),
+            "description": p.get("description", ""),
+        }
+        for p in TRANSITION_PRESETS
+    ]
+    return TransitionPresetListResponse(items=items, total=len(items))
+
+
+@router.put("/clips/{clip_id}/transition", response_model=ClipTransitionResponse)
+def update_editor_clip_transition(
+    template_id: str,
+    clip_id: str,
+    body: TransitionUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ClipTransitionResponse:
+    """设置单个片段的转场效果"""
+    _, plan_svc = services
+    try:
+        clip = plan_svc.update_clip(
+            clip_id,
+            transition_effect=body.effect,
+            transition_duration=body.duration,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return ClipTransitionResponse(
+        clip_id=clip.id,
+        effect=clip.transition_effect.value
+        if hasattr(clip.transition_effect, "value")
+        else clip.transition_effect,
+        duration=clip.transition_duration or 0.5,
+    )
+
+
+@router.post("/transitions/batch", response_model=BatchTransitionResponse)
+def batch_update_editor_transitions(
+    template_id: str,
+    body: BatchTransitionRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> BatchTransitionResponse:
+    """批量设置所有片段的转场效果"""
+    _, plan_svc = services
+    clips = plan_svc.list_clips(plan_id, limit=500)
+    updated = 0
+    for clip in clips:
+        if clip.order > 0:  # 第一个片段不加转场
+            try:
+                plan_svc.update_clip(
+                    clip.id,
+                    transition_effect=body.effect,
+                    transition_duration=body.duration,
+                )
+                updated += 1
+            except ValueError:
+                pass
+
+    return BatchTransitionResponse(
+        updated_count=updated,
+        plan_id=plan_id,
+    )
+
+
+# ── 滤镜 ────────────────────────────────────────────────────────────────────
+
+
+@router.get("/filter-presets", response_model=FilterPresetListResponse)
+def list_editor_filter_presets(
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> FilterPresetListResponse:
+    """获取滤镜预设列表"""
+    from packages.domain.filter_presets import FILTER_PRESETS
+
+    items = [
+        {
+            "id": p["id"],
+            "name": p["name"],
+            "category": p.get("category", "通用"),
+            "thumbnail": p.get("thumbnail", ""),
+            "description": p.get("description", ""),
+        }
+        for p in FILTER_PRESETS
+    ]
+    return FilterPresetListResponse(items=items, total=len(items))
+
+
+@router.get("/filter", response_model=FilterConfigResponse)
+def get_editor_filter(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> FilterConfigResponse:
+    """获取草稿的全局滤镜配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+    config = plan.config or {}
+    filter_config = config.get("filter", {})
+
+    return FilterConfigResponse(
+        plan_id=plan.id,
+        enabled=filter_config.get("enabled", False),
+        preset_id=filter_config.get("preset_id", ""),
+        intensity=filter_config.get("intensity", 1.0),
+        brightness=filter_config.get("brightness", 0.0),
+        contrast=filter_config.get("contrast", 1.0),
+        saturation=filter_config.get("saturation", 1.0),
+        warmth=filter_config.get("warmth", 0.0),
+    )
+
+
+@router.put("/filter", response_model=FilterConfigResponse)
+def update_editor_filter(
+    template_id: str,
+    body: FilterUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> FilterConfigResponse:
+    """更新草稿的全局滤镜配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    config = dict(plan.config) if plan.config else {}
+    current_filter = dict(config.get("filter", {}))
+    update_data = body.model_dump(exclude_none=True)
+    current_filter.update(update_data)
+
+    config["filter"] = current_filter
+    updated_plan = plan_svc.update_plan_config(plan_id, normalize_plan_config(config))
+
+    return FilterConfigResponse(
+        plan_id=updated_plan.id,
+        enabled=current_filter.get("enabled", False),
+        preset_id=current_filter.get("preset_id", ""),
+        intensity=current_filter.get("intensity", 1.0),
+        brightness=current_filter.get("brightness", 0.0),
+        contrast=current_filter.get("contrast", 1.0),
+        saturation=current_filter.get("saturation", 1.0),
+        warmth=current_filter.get("warmth", 0.0),
+    )

apps/api/app/api/routes/templates_editor/export.py

@@ -0,0 +1,106 @@
+"""导出配置路由.
+
+端点：
+- GET /export-presets      导出预设列表
+- GET /export              导出配置
+- PUT /export              更新导出配置
+"""
+
+from __future__ import annotations
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends
+
+from packages.domain.config_schemas import normalize_plan_config
+
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import ExportConfigResponse, ExportPresetListResponse, ExportUpdateRequest
+
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.get("/export-presets", response_model=ExportPresetListResponse)
+def list_editor_export_presets(
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ExportPresetListResponse:
+    """获取导出预设列表"""
+    from packages.domain.export_presets import EXPORT_PRESETS
+
+    items = [
+        {
+            "id": p["id"],
+            "name": p["name"],
+            "resolution": p.get("resolution", "1080p"),
+            "fps": p.get("fps", 30),
+            "video_bitrate": p.get("bitrate", ""),
+            "audio_bitrate": p.get("audio_bitrate", 128),
+            "format": p.get("format", "mp4"),
+            "quality_preset": p.get("quality_preset", "balanced"),
+            "description": p.get("description", ""),
+            "size_hint": p.get("size_hint", ""),
+        }
+        for p in EXPORT_PRESETS
+    ]
+    return ExportPresetListResponse(items=items, total=len(items))
+
+
+@router.get("/export", response_model=ExportConfigResponse)
+def get_editor_export(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ExportConfigResponse:
+    """获取草稿的导出配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+    config = plan.config or {}
+    export_config = config.get("export", {})
+
+    return ExportConfigResponse(
+        plan_id=plan.id,
+        resolution=export_config.get("resolution", "1080p"),
+        fps=export_config.get("fps", 30),
+        video_bitrate=export_config.get("video_bitrate", 4000),
+        audio_bitrate=export_config.get("audio_bitrate", 128),
+        format=export_config.get("format", "mp4"),
+        quality_preset=export_config.get("quality_preset", "balanced"),
+        watermark_enabled=export_config.get("watermark_enabled", True),
+        watermark_text=export_config.get("watermark_text", ""),
+    )
+
+
+@router.put("/export", response_model=ExportConfigResponse)
+def update_editor_export(
+    template_id: str,
+    body: ExportUpdateRequest,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> ExportConfigResponse:
+    """更新草稿的导出配置"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+
+    config = dict(plan.config) if plan.config else {}
+    current_export = dict(config.get("export", {}))
+    update_data = body.model_dump(exclude_none=True)
+    current_export.update(update_data)
+
+    config["export"] = current_export
+    updated_plan = plan_svc.update_plan_config(plan_id, normalize_plan_config(config))
+    updated_export = (updated_plan.config or {}).get("export", {})
+
+    return ExportConfigResponse(
+        plan_id=updated_plan.id,
+        resolution=updated_export.get("resolution", "1080p"),
+        fps=updated_export.get("fps", 30),
+        video_bitrate=updated_export.get("video_bitrate", 4000),
+        audio_bitrate=updated_export.get("audio_bitrate", 128),
+        format=updated_export.get("format", "mp4"),
+        quality_preset=updated_export.get("quality_preset", "balanced"),
+        watermark_enabled=updated_export.get("watermark_enabled", True),
+        watermark_text=updated_export.get("watermark_text", ""),
+    )

apps/api/app/api/routes/templates_editor/generation.py

@@ -0,0 +1,250 @@
+"""草稿生成路由.
+
+端点：
+- POST /generate              触发生成
+- GET  /generation-status     生成进度
+- GET  /generations           生成记录列表
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.core.celery_app import celery_app
+from app.core.storage import OSSStorageService, get_storage_service
+from app.dependencies import (
+    get_asset_library_repository,
+    get_asset_repository,
+    get_db_session,
+)
+from app.schemas.generation_task import GenerationTaskResponse
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.generation_task_repository import (
+    SQLAlchemyGenerationTaskRepository,
+)
+from packages.application.generation_tasks import (
+    CreateGenerationTaskCommand,
+    CreateGenerationTaskUseCase,
+)
+from packages.domain.edit_plan import EditPlanStatus
+
+from ._fallback import (
+    _auto_fallback_assign_assets,
+    _auto_fallback_auto_material_mode,
+    _auto_fallback_copy_template_clips,
+    _auto_fallback_draft_to_editing,
+)
+from .dependencies import _check_queue_limits, get_draft_plan_id, get_editor_services
+from .schemas import (
+    ClipStatusItem,
+    EditPlanGenerateResponse,
+    EditPlanGenerationsResponse,
+    EditPlanGenerationStatusResponse,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.post("/generate", response_model=EditPlanGenerateResponse)
+def generate_editor_draft(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    asset_library_repo: Any = Depends(get_asset_library_repository),
+    asset_repo: Any = Depends(get_asset_repository),
+) -> EditPlanGenerateResponse:
+    """触发模板草稿渲染生成"""
+    _, plan_svc = services
+    plan_check = plan_svc.get_plan_or_raise(plan_id)
+
+    # 自动兜底流程
+    _auto_fallback_draft_to_editing(plan_svc, plan_id, plan_check)
+    _auto_fallback_copy_template_clips(plan_svc, plan_id, plan_check, db)
+    clips_without_asset = _auto_fallback_assign_assets(plan_svc, plan_id, plan_check)
+    _auto_fallback_auto_material_mode(
+        plan_svc, plan_id, plan_check, clips_without_asset, asset_library_repo, asset_repo
+    )
+
+    # 检查是否可生成
+    try:
+        can_gen, reason = plan_svc.can_generate(plan_id)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)
+        ) from exc
+    if not can_gen:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail=reason
+        )
+
+    try:
+        clip_count = plan_svc.mark_clips_ready(plan_id)
+
+        gen_task_repo = SQLAlchemyGenerationTaskRepository(db)
+        user_id = current_user.user.id
+        _check_queue_limits(gen_task_repo, user_id)
+
+        gen_task_use_case = CreateGenerationTaskUseCase(gen_task_repo)
+        plan = plan_svc.get_plan_or_raise(plan_id)
+        config_asset_ids = (plan.config or {}).get("asset_ids", [])
+        gen_task = gen_task_use_case.execute(
+            CreateGenerationTaskCommand(
+                project_id=plan.project_id or "",
+                template_id=plan.template_id,
+                created_by_user_id=current_user.user.id,
+                source_edit_plan_id=plan_id,
+                asset_ids=list(config_asset_ids) if config_asset_ids else [],
+            ),
+        )
+
+        plan_svc.update_plan_config(plan_id, {"generation_task_id": gen_task.id})
+        plan_svc.transition_status(plan_id, EditPlanStatus.RENDERING)
+        celery_app.send_task("worker.render_edit_plan", args=[plan_id])
+
+        updated_plan = plan_svc.get_plan_or_raise(plan_id)
+
+        logger.info(
+            "模板编辑器触发生成: template_id=%s plan_id=%s gen_task_id=%s clips=%d by user=%s",
+            template_id,
+            plan_id,
+            gen_task.id,
+            clip_count,
+            current_user.user.id,
+        )
+
+        return EditPlanGenerateResponse(
+            plan_id=plan_id,
+            plan_status=updated_plan.status.value
+            if hasattr(updated_plan.status, "value")
+            else updated_plan.status,
+            generation_task_id=gen_task.id,
+            clip_count=clip_count,
+        )
+    except HTTPException:
+        raise
+    except Exception as _e:
+        logger.exception(
+            "模板编辑器触发生成失败: template_id=%s plan_id=%s",
+            template_id,
+            plan_id,
+        )
+        try:
+            plan_svc.transition_status(plan_id, EditPlanStatus.FAILED)
+        except Exception:
+            pass
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="生成失败，请稍后重试",
+        ) from _e
+
+
+@router.get("/generation-status", response_model=EditPlanGenerationStatusResponse)
+def get_editor_generation_status(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    storage_service: OSSStorageService = Depends(get_storage_service),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> EditPlanGenerationStatusResponse:
+    """查询草稿生成进度"""
+    _, plan_svc = services
+    try:
+        gen_status = plan_svc.get_generation_status(plan_id)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)
+        ) from exc
+
+    plan = gen_status["plan"]
+    clips = gen_status["clips"]
+
+    clip_items = [
+        ClipStatusItem(
+            clip_id=c.id,
+            clip_type=c.clip_type,
+            order=c.order,
+            status=c.status.value if hasattr(c.status, "value") else c.status,
+            asset_id=c.asset_id or "",
+            text_content=c.text_content or "",
+            duration=c.duration,
+        )
+        for c in clips
+    ]
+
+    raw_video_url = (plan.config or {}).get("rendered_url", "")
+    video_url = ""
+    if raw_video_url:
+        try:
+            video_url = storage_service.get_download_url(
+                raw_video_url, expires_seconds=86400
+            )
+        except Exception as e:
+            logger.warning(
+                "生成视频签名URL失败: template_id=%s error=%s", template_id, e
+            )
+            video_url = raw_video_url
+
+    progress = gen_status.get("progress", 0.0)
+    error_message = gen_status.get("error_message", "")
+    gen_task_status = gen_status.get("generation_task_status")
+    plan_status_val = (
+        plan.status.value if hasattr(plan.status, "value") else plan.status
+    )
+    if plan_status_val == "completed" and progress < 100:
+        progress = 100.0
+
+    return EditPlanGenerationStatusResponse(
+        plan_id=plan_id,
+        plan_status=plan_status_val,
+        generation_task_id=gen_status["generation_task_id"],
+        generation_task_status=gen_task_status,
+        progress=progress,
+        video_url=video_url,
+        error_message=error_message,
+        clips=clip_items,
+    )
+
+
+@router.get("/generations", response_model=EditPlanGenerationsResponse)
+def list_editor_generations(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    db: Session = Depends(get_db_session),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> EditPlanGenerationsResponse:
+    """查询草稿关联的生成记录列表"""
+    _, plan_svc = services
+    plan_svc.get_plan_or_raise(plan_id)
+
+    gen_task_repo = SQLAlchemyGenerationTaskRepository(db)
+    tasks = gen_task_repo.list_by_source_edit_plan(plan_id)
+    items = [
+        GenerationTaskResponse(
+            id=t.id,
+            project_id=t.project_id,
+            asset_library_id=t.asset_library_id,
+            strategy_id=t.strategy_id,
+            voice_library_id=t.voice_library_id,
+            template_id=t.template_id,
+            asset_ids=t.asset_ids,
+            title_ids=t.title_ids,
+            voice_ids=t.voice_ids,
+            source_edit_plan_id=t.source_edit_plan_id or "",
+            status=t.status.value if hasattr(t.status, "value") else t.status,
+            progress=t.progress,
+            result_count=t.result_count,
+            error_message=t.error_message,
+        )
+        for t in tasks
+    ]
+    return EditPlanGenerationsResponse(items=items, total=len(items))

apps/api/app/api/routes/templates_editor/schemas.py

@@ -0,0 +1,622 @@
+"""模板编辑器所有 Pydantic Schema 定义.
+
+集中管理，避免在路由文件里散落 40+ 个 model。
+"""
+
+from __future__ import annotations
+
+import re as _re
+from typing import Any, List, Optional
+
+from app.schemas.generation_task import GenerationTaskResponse
+from pydantic import BaseModel, Field, validator
+
+_EXPORT_RESOLUTION_PATTERN = _re.compile(r"^\d+x\d+$")
+_EXPORT_VALID_QUALITY_PRESETS = {"ultra_fast", "fast", "balanced", "high", "best"}
+_EXPORT_VALID_FORMATS = {"mp4", "mov"}
+
+
+# ── 生成状态相关 ────────────────────────────────────────────────────────────
+
+
+class ClipStatusItem(BaseModel):
+    """片段生成状态"""
+
+    clip_id: str
+    clip_type: str
+    order: int
+    status: str
+    asset_id: str
+    text_content: str
+    duration: float
+
+
+class EditPlanGenerationStatusResponse(BaseModel):
+    """剪辑计划生成进度响应体"""
+
+    plan_id: str
+    plan_status: str
+    generation_task_id: Optional[str] = None
+    generation_task_status: Optional[str] = None
+    progress: float = 0.0
+    video_url: str = ""
+    error_message: str = ""
+    clips: List[ClipStatusItem]
+
+
+class EditPlanGenerateResponse(BaseModel):
+    """剪辑计划触发生成响应体"""
+
+    plan_id: str
+    plan_status: str
+    generation_task_id: str
+    clip_count: int
+
+
+class EditPlanGenerationsResponse(BaseModel):
+    """剪辑计划关联的生成记录列表响应体"""
+
+    items: List[GenerationTaskResponse]
+    total: int
+
+
+# ── AI 推荐 ────────────────────────────────────────────────────────────────
+
+
+class AIRecommendRequest(BaseModel):
+    """AI 推荐片段方案请求体"""
+
+    asset_ids: List[str] = Field(default_factory=list, description="素材 ID 列表")
+    editing_mode: str = Field(
+        default="one_take", description="剪辑模式: one_take / pip / voice_over / voice_pip"
+    )
+    target_duration: float = Field(
+        default=30.0, ge=1.0, le=600.0, description="目标时长（秒）"
+    )
+
+
+class AIRecommendClipItem(BaseModel):
+    """AI 推荐的单个片段"""
+
+    clip_type: str = Field(..., description="片段类型: intro / showcase / title / subtitle / cta / outro")
+    order: int = Field(..., ge=0, description="片段顺序")
+    text_content: str = Field(default="", description="文字内容")
+    duration: float = Field(..., ge=0.0, description="片段时长（秒）")
+    transition_effect: str = Field(default="cut", description="转场效果")
+    transition_duration: float = Field(default=0.0, ge=0.0, description="转场时长（秒），0 表示使用默认值")
+    asset_id: str = Field(default="", description="关联素材 ID")
+    start_time: float = Field(default=0.0, ge=0.0, description="素材截取起始时间（秒）")
+    config: dict[str, Any] = Field(default_factory=dict, description="片段额外配置")
+
+
+class AIRecommendResponse(BaseModel):
+    """AI 推荐片段方案响应体"""
+
+    plan_id: str = Field(..., description="剪辑计划 ID")
+    clips: List[AIRecommendClipItem] = Field(..., description="推荐的片段列表")
+    config: dict[str, Any] = Field(..., description="推荐的 plan config（cover/title/subtitle/bgm）")
+    total_duration: float = Field(..., ge=0.0, description="推荐方案总时长（秒）")
+    confidence: float = Field(..., ge=0.0, le=1.0, description="AI 推荐置信度 (0~1)")
+
+
+# ── 封面生成 ────────────────────────────────────────────────────────────────
+
+
+class GenerateCoverRequest(BaseModel):
+    """AI 封面生成请求体"""
+
+    asset_ids: List[str] = Field(default_factory=list, description="素材 ID 列表（确定视频来源）")
+    cover_type: str = Field(
+        default="ai_frame",
+        description="封面类型: ai_frame / manual / upload / ai_regenerate",
+    )
+    frame_time: Optional[float] = Field(
+        default=None,
+        ge=0.0,
+        description="手动选帧时间点（秒），仅 cover_type=manual 时有效",
+    )
+
+
+class GenerateCoverResponse(BaseModel):
+    """AI 封面生成响应体"""
+
+    plan_id: str = Field(..., description="剪辑计划 ID")
+    cover: dict[str, Any] = Field(..., description="封面数据（type / image_url / frame_time 等）")
+
+
+# ── BGM ────────────────────────────────────────────────────────────────────
+
+
+class BGMConfigUpdateRequest(BaseModel):
+    """更新BGM配置请求体"""
+
+    enabled: Optional[bool] = Field(default=None, description="是否启用 BGM")
+    source: Optional[str] = Field(default=None, description="BGM 来源: library/upload/ai_recommend")
+    asset_id: Optional[str] = Field(default=None, max_length=64, description="BGM 素材 ID")
+    preset_id: Optional[str] = Field(default=None, max_length=64, description="预设 BGM ID")
+    audio_url: Optional[str] = Field(default=None, max_length=500, description="BGM 音频 URL")
+    volume: Optional[float] = Field(default=None, ge=0.0, le=1.0, description="音量 (0.0 ~ 1.0)")
+    fade_in: Optional[float] = Field(default=None, ge=0.0, le=30.0, description="淡入时长（秒）")
+    fade_out: Optional[float] = Field(default=None, ge=0.0, le=30.0, description="淡出时长（秒）")
+    loop_enabled: Optional[bool] = Field(default=None, description="是否循环播放")
+    sidechain_enabled: Optional[bool] = Field(default=None, description="是否启用人声闪避")
+    sidechain_ratio: Optional[float] = Field(default=None, ge=0.0, le=1.0, description="闪避音量降低比例")
+
+
+# ── 片段调整 ────────────────────────────────────────────────────────────────
+
+
+class SpeedAdjustRequest(BaseModel):
+    """调速请求"""
+
+    speed: float = Field(..., ge=0.25, le=4.0, description="播放速度 0.25~4.0")
+
+
+class VolumeAdjustRequest(BaseModel):
+    """音量调节请求"""
+
+    volume: float = Field(..., ge=0.0, le=2.0, description="音量倍率 0~2.0（1.0=原音量）")
+
+
+class TrimAdjustRequest(BaseModel):
+    """裁剪请求"""
+
+    trim_start: float = Field(0.0, ge=0.0, description="开头裁剪秒数")
+    trim_end: float = Field(0.0, ge=0.0, description="结尾裁剪秒数")
+
+
+class ClipAdjustmentsRequest(BaseModel):
+    """统一调整请求"""
+
+    speed: Optional[float] = Field(default=None, ge=0.25, le=4.0)
+    volume: Optional[float] = Field(default=None, ge=0.0, le=2.0)
+    trim_start: Optional[float] = Field(default=None, ge=0.0)
+    trim_end: Optional[float] = Field(default=None, ge=0.0)
+
+
+class BatchSpeedRequest(BaseModel):
+    """批量调速请求"""
+
+    speed: float = Field(..., ge=0.25, le=4.0, description="播放速度")
+
+
+class ClipAdjustResponse(BaseModel):
+    """片段调整响应"""
+
+    clip_id: str
+    speed: float
+    volume: float
+    trim_start: float
+    trim_end: float
+    duration: float
+
+
+class BatchSpeedResponse(BaseModel):
+    """批量调速响应"""
+
+    updated_count: int
+    plan_id: str
+
+
+# ── 片段批量操作 ────────────────────────────────────────────────────────────
+
+
+class ClipReorderItem(BaseModel):
+    """重排序条目"""
+
+    clip_id: str
+    new_order: int = Field(..., ge=0, description="新的排序序号")
+
+
+class ClipReorderRequest(BaseModel):
+    """片段重排序请求"""
+
+    items: List[ClipReorderItem] = Field(..., min_length=1, max_length=500, description="重排序条目列表")
+
+
+class ClipReorderResponse(BaseModel):
+    """片段重排序响应"""
+
+    success: bool = True
+    updated_count: int
+    message: str = ""
+
+
+class ClipBatchDeleteRequest(BaseModel):
+    """批量删除片段请求"""
+
+    clip_ids: List[str] = Field(..., min_length=1, max_length=500, description="要删除的片段ID列表")
+
+
+class ClipBatchDeleteResponse(BaseModel):
+    """批量删除片段响应"""
+
+    success: bool = True
+    deleted_count: int
+    message: str = ""
+
+
+class ClipsFromAssetsRequest(BaseModel):
+    """从素材批量创建片段请求"""
+
+    asset_ids: List[str] = Field(
+        ..., min_length=1, max_length=200, description="素材 ID 列表，按顺序追加到时间线末尾"
+    )
+    clip_type: str = Field(default="main", description="片段类型，默认 main")
+
+
+class ClipsFromAssetsResponse(BaseModel):
+    """从素材批量创建片段响应"""
+
+    success: bool = True
+    created_count: int
+    message: str = ""
+    clip_ids: List[str] = Field(default_factory=list, description="创建的片段ID列表")
+
+
+# ── 封面配置 ────────────────────────────────────────────────────────────────
+
+
+class CoverConfigResponse(BaseModel):
+    """封面配置响应"""
+
+    type: str = Field(..., description="封面类型: ai_frame / manual / upload")
+    image_url: str = Field(default="", description="封面图片 URL")
+    frame_time: Optional[float] = Field(default=None, description="抽帧时间点（秒）")
+
+
+class CoverUpdateRequest(BaseModel):
+    """更新封面配置请求"""
+
+    type: Optional[str] = Field(default=None, description="封面类型")
+    image_url: Optional[str] = Field(default=None, description="封面图片 URL")
+    frame_time: Optional[float] = Field(default=None, ge=0.0, description="抽帧时间点（秒）")
+
+
+class CoverExtractRequest(BaseModel):
+    """从片段抽帧生成封面请求"""
+
+    clip_id: str = Field(..., description="片段 ID")
+    frame_time: float = Field(1.0, ge=0.0, description="抽帧时间点（秒）")
+
+
+class CoverSmartRequest(BaseModel):
+    """智能选帧请求"""
+
+    clip_id: Optional[str] = Field(default=None, description="指定片段 ID（不传则用第一个视频片段）")
+
+
+class CoverGenerateResponse(BaseModel):
+    """封面生成响应"""
+
+    type: str = Field(..., description="封面类型")
+    image_url: str = Field(..., description="封面图片 URL")
+    frame_time: Optional[float] = Field(default=None, description="抽帧时间点（秒）")
+
+
+# ── 导出配置 ────────────────────────────────────────────────────────────────
+
+
+class ExportConfigResponse(BaseModel):
+    """导出配置响应"""
+
+    resolution: str
+    fps: int
+    video_bitrate: int
+    audio_bitrate: int
+    format: str
+    quality_preset: str
+    watermark_enabled: bool
+    watermark_text: str
+
+
+class ExportUpdateRequest(BaseModel):
+    """更新导出配置请求"""
+
+    resolution: Optional[str] = None
+    fps: Optional[int] = Field(default=None, ge=15, le=60)
+    video_bitrate: Optional[int] = Field(default=None, ge=1000, le=20000)
+    audio_bitrate: Optional[int] = Field(default=None, ge=64, le=320)
+    format: Optional[str] = None
+    quality_preset: Optional[str] = None
+    watermark_enabled: Optional[bool] = None
+    watermark_text: Optional[str] = None
+
+    @validator("resolution")
+    def validate_resolution(cls, v):
+        if v is None:
+            return v
+        if not _EXPORT_RESOLUTION_PATTERN.match(v):
+            raise ValueError("分辨率格式错误，应为 宽x高，如 1080x1920")
+        w, h = v.split("x")
+        if int(w) < 100 or int(h) < 100:
+            raise ValueError("分辨率数值过小")
+        if int(w) > 4096 or int(h) > 4096:
+            raise ValueError("分辨率数值过大，最大 4096x4096")
+        return v
+
+    @validator("format")
+    def validate_format(cls, v):
+        if v is None:
+            return v
+        if v not in _EXPORT_VALID_FORMATS:
+            raise ValueError(f"无效格式: {v}，支持: {_EXPORT_VALID_FORMATS}")
+        return v
+
+    @validator("quality_preset")
+    def validate_quality_preset(cls, v):
+        if v is None:
+            return v
+        if v not in _EXPORT_VALID_QUALITY_PRESETS:
+            raise ValueError(f"无效质量预设: {v}，支持: {_EXPORT_VALID_QUALITY_PRESETS}")
+        return v
+
+
+class ExportPresetItem(BaseModel):
+    """导出预设条目"""
+
+    id: str
+    name: str
+    resolution: str
+    fps: int
+    video_bitrate: int
+    audio_bitrate: int
+    format: str
+    quality_preset: str
+    description: str
+    size_hint: str
+
+
+class ExportPresetListResponse(BaseModel):
+    """导出预设列表响应"""
+
+    items: List[ExportPresetItem]
+    total: int
+
+
+# ── 滤镜 ────────────────────────────────────────────────────────────────────
+
+
+class FilterPresetResponse(BaseModel):
+    """滤镜预设响应"""
+
+    id: str
+    name: str
+    category: str
+    description: str
+    tags: List[str] = Field(default_factory=list)
+
+
+class FilterConfigResponse(BaseModel):
+    """滤镜配置响应"""
+
+    enabled: bool
+    preset_id: str
+    intensity: int
+    brightness: float
+    contrast: float
+    saturation: float
+    warmth: float
+
+
+class FilterUpdateRequest(BaseModel):
+    """更新滤镜配置请求"""
+
+    enabled: Optional[bool] = None
+    preset_id: Optional[str] = None
+    intensity: Optional[int] = Field(default=None, ge=0, le=100)
+    brightness: Optional[float] = Field(default=None, ge=-1.0, le=1.0)
+    contrast: Optional[float] = Field(default=None, ge=0.0, le=2.0)
+    saturation: Optional[float] = Field(default=None, ge=0.0, le=3.0)
+    warmth: Optional[float] = Field(default=None, ge=-1.0, le=1.0)
+
+
+class FilterPresetListResponse(BaseModel):
+    """滤镜预设列表响应"""
+
+    items: List[FilterPresetResponse]
+    total: int
+
+
+# ── 转场 ────────────────────────────────────────────────────────────────────
+
+
+class TransitionPresetResponse(BaseModel):
+    """转场预设响应"""
+
+    id: str
+    name: str
+    category: str
+    description: str
+    tags: List[str] = Field(default_factory=list)
+    default_duration: float
+    min_duration: float
+    max_duration: float
+
+
+class TransitionUpdateRequest(BaseModel):
+    """更新转场请求"""
+
+    effect: str = Field(..., description="转场效果 ID")
+    duration: Optional[float] = Field(default=None, ge=0.0, description="转场时长（秒）")
+
+
+class BatchTransitionRequest(BaseModel):
+    """批量设置转场请求"""
+
+    effect: str = Field(..., description="转场效果 ID")
+    duration: Optional[float] = Field(default=None, ge=0.0, description="转场时长（秒）")
+    apply_to: str = Field(
+        default="all",
+        description="应用范围: all=所有片段, except_first=除第一个外, except_last=除最后一个, middle=中间片段",
+    )
+
+
+class ClipTransitionResponse(BaseModel):
+    """片段转场信息响应"""
+
+    clip_id: str
+    effect: str
+    duration: float
+
+
+class BatchTransitionResponse(BaseModel):
+    """批量转场响应"""
+
+    updated_count: int
+    plan_id: str
+
+
+class TransitionPresetListResponse(BaseModel):
+    """转场预设列表响应"""
+
+    items: List[TransitionPresetResponse]
+    total: int
+
+
+# ── 编辑器草稿 & 片段 ───────────────────────────────────────────────────────
+
+
+class EditorDraftResponse(BaseModel):
+    """模板编辑器草稿详情响应"""
+
+    plan_id: str
+    template_id: str
+    name: str
+    status: str
+    config: dict[str, Any]
+    total_duration: float
+    clip_count: int
+    is_draft: bool = True
+
+
+class EditorUpdateRequest(BaseModel):
+    """更新草稿请求"""
+
+    name: Optional[str] = Field(default=None, min_length=1, max_length=200)
+    config: Optional[dict[str, Any]] = Field(default=None)
+    total_duration: Optional[float] = Field(default=None, ge=0.0)
+
+
+class EditorClipResponse(BaseModel):
+    """片段响应"""
+
+    id: str
+    plan_id: str
+    clip_type: str
+    order: int
+    duration: float
+    text_content: str = ""
+    transition_effect: str = "cut"
+    playback_speed: float = 1.0
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class EditorClipListResponse(BaseModel):
+    """片段列表响应"""
+
+    items: List[EditorClipResponse]
+    total: int
+
+
+class EditorClipCreateRequest(BaseModel):
+    """创建片段请求"""
+
+    clip_type: str = Field(..., min_length=1, max_length=32)
+    order: int = Field(..., ge=0)
+    duration: float = Field(..., gt=0.0)
+    text_content: str = Field(default="", max_length=2000)
+    transition_effect: str = Field(default="cut", max_length=32)
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class EditorClipUpdateRequest(BaseModel):
+    """更新片段请求"""
+
+    order: Optional[int] = Field(default=None, ge=0)
+    duration: Optional[float] = Field(default=None, gt=0.0)
+    text_content: Optional[str] = Field(default=None, max_length=2000)
+    transition_effect: Optional[str] = Field(default=None, max_length=32)
+    playback_speed: Optional[float] = Field(default=None, gt=0.0)
+    config: Optional[dict[str, Any]] = None
+
+
+class EditorPublishResponse(BaseModel):
+    """发布草稿响应"""
+
+    template_id: str
+    status: str = "published"
+    clip_count: int
+    version: int = 1
+
+
+class EditorTemplateVersionItem(BaseModel):
+    """模板版本历史条目"""
+
+    version: int
+    name: str
+    editing_mode: str
+    clip_count: int
+    change_note: str
+    published_by: str
+    created_at: str
+
+
+class EditorVersionListResponse(BaseModel):
+    """模板版本列表响应"""
+
+    versions: list[EditorTemplateVersionItem]
+    total: int
+
+
+class EditorRollbackRequest(BaseModel):
+    """回滚请求体"""
+
+    version: int
+
+
+class EditorRollbackResponse(BaseModel):
+    """回滚响应"""
+
+    template_id: str
+    status: str = "rolled_back"
+    rollback_to_version: int
+    new_version: int
+    clip_count: int
+
+
+# ── 片段分割与合并 ──────────────────────────────────────────────────────────
+
+
+class SplitClipRequest(BaseModel):
+    """分割片段请求体"""
+
+    split_time: float = Field(..., gt=0, description="分割点（秒，相对于片段起始）")
+
+
+class MergeClipsRequest(BaseModel):
+    """合并片段请求体"""
+
+    clip_ids: list[str] = Field(..., min_length=2, description="要合并的片段 ID 列表")
+
+
+# ── 时间线 ──────────────────────────────────────────────────────────────────
+
+
+class EditorTimelineSceneResponse(BaseModel):
+    """时间线场景"""
+
+    scene: str
+    time: str
+    duration: float
+    color: str
+    clip_id: str = ""
+    clip_type: str = ""
+
+
+class EditorTimelineResponse(BaseModel):
+    """时间线响应"""
+
+    plan_id: str
+    total_duration: float
+    scenes: List[EditorTimelineSceneResponse]

apps/api/app/api/routes/templates_editor/subtitles.py

@@ -0,0 +1,173 @@
+"""字幕管理路由.
+
+端点：
+- GET    /clips/{clip_id}/subtitles              字幕列表
+- POST   /clips/{clip_id}/subtitles              新增字幕
+- PUT    /clips/{clip_id}/subtitles/{subtitle_id} 更新字幕
+- DELETE /clips/{clip_id}/subtitles/{subtitle_id} 删除字幕
+- PUT    /clips/{clip_id}/subtitles              批量更新字幕（全量替换）
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from .dependencies import get_draft_plan_id, get_editor_services
+
+router = APIRouter(tags=["Template Editor"])
+
+
+def _get_clip_subtitles(plan_svc: EditPlanService, clip_id: str, plan_id: str) -> list[dict[str, Any]]:
+    """获取片段字幕列表，统一校验"""
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+    if clip.plan_id != plan_id:
+        raise HTTPException(status_code=404, detail="片段不存在")
+    config = clip.config or {}
+    subtitles = config.get("subtitles", [])
+    if not isinstance(subtitles, list):
+        subtitles = []
+    return subtitles
+
+
+@router.get("/clips/{clip_id}/subtitles", response_model=list[dict[str, Any]])
+def get_editor_clip_subtitles(
+    template_id: str,
+    clip_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> list[dict[str, Any]]:
+    """获取片段的字幕列表"""
+    _, plan_svc = services
+    return _get_clip_subtitles(plan_svc, clip_id, plan_id)
+
+
+@router.post("/clips/{clip_id}/subtitles", response_model=dict[str, Any])
+def create_editor_clip_subtitle(
+    template_id: str,
+    clip_id: str,
+    body: dict[str, Any],
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> dict[str, Any]:
+    """新增片段字幕"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    config = dict(clip.config) if clip.config else {}
+    subtitles = config.get("subtitles", [])
+    if not isinstance(subtitles, list):
+        subtitles = []
+
+    new_id = f"sub_{len(subtitles) + 1}"
+    new_subtitle = {
+        "id": body.get("id", new_id),
+        "start_time": body.get("start_time", 0.0),
+        "end_time": body.get("end_time", 0.0),
+        "text": body.get("text", ""),
+        "style": body.get("style", {}),
+    }
+    subtitles.append(new_subtitle)
+    config["subtitles"] = subtitles
+
+    plan_svc.update_clip(clip_id, config=config)
+    return new_subtitle
+
+
+@router.put("/clips/{clip_id}/subtitles/{subtitle_id}", response_model=dict[str, Any])
+def update_editor_clip_subtitle(
+    template_id: str,
+    clip_id: str,
+    subtitle_id: str,
+    body: dict[str, Any],
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> dict[str, Any]:
+    """更新片段字幕"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    config = dict(clip.config) if clip.config else {}
+    subtitles = config.get("subtitles", [])
+    if not isinstance(subtitles, list):
+        subtitles = []
+
+    found = False
+    for i, sub in enumerate(subtitles):
+        if sub.get("id") == subtitle_id:
+            subtitles[i].update(body)
+            found = True
+            break
+
+    if not found:
+        raise HTTPException(status_code=404, detail="字幕不存在")
+
+    config["subtitles"] = subtitles
+    plan_svc.update_clip(clip_id, config=config)
+    return subtitles[i]
+
+
+@router.delete(
+    "/clips/{clip_id}/subtitles/{subtitle_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+def delete_editor_clip_subtitle(
+    template_id: str,
+    clip_id: str,
+    subtitle_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+):
+    """删除片段字幕"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    config = dict(clip.config) if clip.config else {}
+    subtitles = config.get("subtitles", [])
+    if not isinstance(subtitles, list):
+        subtitles = []
+
+    new_subtitles = [s for s in subtitles if s.get("id") != subtitle_id]
+    if len(new_subtitles) == len(subtitles):
+        raise HTTPException(status_code=404, detail="字幕不存在")
+
+    config["subtitles"] = new_subtitles
+    plan_svc.update_clip(clip_id, config=config)
+    return None
+
+
+@router.put("/clips/{clip_id}/subtitles", response_model=list[dict[str, Any]])
+def batch_update_editor_clip_subtitles(
+    template_id: str,
+    clip_id: str,
+    body: list[dict[str, Any]],
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> list[dict[str, Any]]:
+    """批量更新片段字幕（全量替换）"""
+    _, plan_svc = services
+    clip = plan_svc.get_clip(clip_id)
+    if not clip:
+        raise HTTPException(status_code=404, detail="片段不存在")
+
+    config = dict(clip.config) if clip.config else {}
+    config["subtitles"] = body
+    plan_svc.update_clip(clip_id, config=config)
+    return body

apps/api/app/api/routes/templates_editor/timeline.py

@@ -0,0 +1,61 @@
+"""时间线路由.
+
+端点：
+- GET /timeline       时间线场景数据
+"""
+
+from __future__ import annotations
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.services.edit_plan_service import EditPlanService
+from app.services.edit_template_service import EditTemplateService
+from fastapi import APIRouter, Depends
+
+from ._utils import _CLIP_TYPE_COLORS, _DEFAULT_COLOR, _clip_type_to_scene_label, _format_time
+from .dependencies import get_draft_plan_id, get_editor_services
+from .schemas import EditorTimelineResponse, EditorTimelineSceneResponse
+
+router = APIRouter(tags=["Template Editor"])
+
+
+@router.get("/timeline", response_model=EditorTimelineResponse)
+def get_editor_timeline(
+    template_id: str,
+    plan_id: str = Depends(get_draft_plan_id),
+    services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
+    _: AuthenticatedUser = Depends(get_current_user),
+) -> EditorTimelineResponse:
+    """获取草稿的时间线场景数据"""
+    _, plan_svc = services
+    plan = plan_svc.get_plan_or_raise(plan_id)
+    clips = plan_svc.list_clips(plan_id=plan_id, skip=0, limit=200)
+    clips.sort(key=lambda c: c.order)
+
+    scenes = []
+    current_time = 0.0
+
+    for clip in clips:
+        start = current_time
+        end = start + clip.duration
+        color = _CLIP_TYPE_COLORS.get(clip.clip_type, _DEFAULT_COLOR)
+        scene_label = _clip_type_to_scene_label(clip.clip_type, clip.text_content)
+
+        scenes.append(
+            EditorTimelineSceneResponse(
+                scene=scene_label,
+                time=f"{_format_time(start)} - {_format_time(end)}",
+                duration=clip.duration,
+                color=color,
+                clip_id=clip.id,
+                clip_type=clip.clip_type,
+            )
+        )
+        current_time = end
+
+    total_duration = sum(s.duration for s in scenes) or plan.total_duration
+
+    return EditorTimelineResponse(
+        plan_id=plan_id,
+        total_duration=total_duration,
+        scenes=scenes,
+    )

apps/api/app/api/routes/tts.py

@@ -6,6 +6,7 @@ import logging
 from typing import Optional
 
 from app.auth import AuthenticatedUser, get_current_user
+from app.core.celery_app import celery_app
 from app.dependencies import (
     get_audio_url_signer,
     get_cosyvoice_service,
@@ -181,13 +182,9 @@ def synthesize(
 
         try:
             if is_segment:
-                from worker_app.tasks import process_tts_segment_synthesis
-
-                process_tts_segment_synthesis.delay(job.id)
+                celery_app.send_task("worker.process_tts_segment_synthesis", args=[job.id])
             else:
-                from worker_app.tasks import process_tts_synthesis
-
-                process_tts_synthesis.delay(job.id)
+                celery_app.send_task("worker.process_tts_synthesis", args=[job.id])
         except Exception as e:
             # Celery 调度失败，标记 job 为 failed
             try:

apps/api/app/api/routes/voice_clones.py

@@ -6,6 +6,7 @@ import logging
 from typing import Optional
 
 from app.auth import AuthenticatedUser, get_current_user
+from app.core.celery_app import celery_app
 from app.dependencies import get_cosyvoice_service, get_voice_clone_profile_repository
 from app.schemas.voice_clone import (
     CreateVoiceCloneRequest,
@@ -97,9 +98,7 @@ def create_voice_clone(
     task_id = (profile.metadata or {}).get("cosyvoice_task_id", "")
     if profile.status == "processing" and task_id:
         try:
-            from worker_app.tasks import process_voice_clone
-
-            process_voice_clone.delay(profile.id)
+            celery_app.send_task("worker.process_voice_clone", args=[profile.id])
             logger.info(f"Celery task dispatched for voice clone {profile.id}")
         except Exception as e:
             logger.error(f"Failed to dispatch Celery task: {e}")
@@ -213,9 +212,7 @@ def retry_voice_clone(
     task_id = (profile.metadata or {}).get("cosyvoice_task_id", "")
     if profile.status == "processing" and task_id:
         try:
-            from worker_app.tasks import process_voice_clone
-
-            process_voice_clone.delay(profile.id)
+            celery_app.send_task("worker.process_voice_clone", args=[profile.id])
             logger.info(f"Celery task dispatched for voice clone retry {profile.id}")
         except Exception as e:
             logger.error(f"Failed to dispatch Celery task: {e}")

apps/api/app/config.py

@@ -1,171 +1,28 @@
-import os
-from typing import Optional
+"""API 服务配置（向后兼容层）。
 
-from pydantic import AliasChoices, Field, field_validator
-from pydantic_settings import BaseSettings, SettingsConfigDict
+统一配置已迁移到 packages.config.api_settings。
+新代码请使用：
+    from packages.config import APISettings, get_api_settings
 
+本文件保留 Settings 类名、get_settings() 函数、settings 模块级单例，
+确保所有旧的 import 路径仍然有效。
+"""
 
-class Settings(BaseSettings):
-    APP_NAME: str = "xiaoxia-saas"
-    APP_VERSION: str = "0.1.61"
-    ENVIRONMENT: str = "development"
-    DEBUG: bool = True
-
-    # 应用基础 URL，用于生成认证邮件中的链接
-    # 开发环境默认 http://localhost:3000
-    # 生产环境应通过环境变量 APP_BASE_URL 设置
-    APP_BASE_URL: str = "http://localhost:3000"
-
-    # Container bind address; external expose is controlled by Docker/Nginx.
-    API_HOST: str = "0.0.0.0"  # nosec: B104
-    API_PORT: int = 8000
-
-    DATABASE_URL: str = "postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas"
-    DATABASE_POOL_SIZE: int = 20
-    DATABASE_MAX_OVERFLOW: int = 10  # 调整为合理值：pool_size(20) + max_overflow(10) = 最大30连接
-    DATABASE_POOL_TIMEOUT: int = 30
-    DATABASE_POOL_RECYCLE: int = 3600
-    USE_IN_MEMORY_DB: bool = False
-    AUTO_CREATE_SCHEMA: bool = False
-
-    REDIS_URL: str = "redis://localhost:6379/0"
-    ENABLE_REDIS_SESSIONS: bool = False
-
-    # JWT secret key - MUST be set via environment variable, no default allowed
-    JWT_SECRET_KEY: Optional[str] = None
-
-    # JWT 算法与过期时间（与 .env.example 对齐）
-    JWT_ALGORITHM: str = "HS256"
-    JWT_ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
-    JWT_REFRESH_TOKEN_EXPIRE_DAYS: int = 30
-
-    @field_validator("JWT_SECRET_KEY", mode="before")
-    @classmethod
-    def validate_jwt_secret_key(cls, v):
-        if v is None or v == "":
-            raise ValueError(
-                "JWT_SECRET_KEY must be set via environment variable. " "Do not use default value in production!"
-            )
-        # Block known insecure default values
-        insecure_defaults = [
-            "your-secret-key-change-in-production",
-            "your-secret-key",
-            "secret",
-            "changeme",
-            "password",
-        ]
-        if v.lower() in [d.lower() for d in insecure_defaults]:
-            raise ValueError(
-                f"JWT_SECRET_KEY '{v}' is insecure. " "Please set a strong random secret via environment variable."
-            )
-        return v
-
-    ENABLE_EMAIL_DELIVERY: bool = False
-    SMTP_HOST: str = "smtp.gmail.com"
-    SMTP_PORT: int = 587
-    SMTP_USER: str = ""
-    SMTP_PASSWORD: str = ""
-    SMTP_FROM_EMAIL: str = ""
-    SMTP_FROM_NAME: str = "小虾 SaaS"
-    SMTP_USE_TLS: bool = True
-
-    CELERY_BROKER_URL: str = "redis://localhost:6379/0"
-    CELERY_RESULT_BACKEND: str = "redis://localhost:6379/1"
-
-    # OSS 七牛云相关
-    OSS_ENDPOINT: str = "oss-cn-hangzhou.aliyuncs.com"
-    OSS_ACCESS_KEY_ID: str = ""
-    OSS_ACCESS_KEY_SECRET: str = ""
-    OSS_BUCKET_NAME: str = "xiaoxia-autocut"
-
-    @field_validator("OSS_ACCESS_KEY_ID", mode="before")
-    @classmethod
-    def validate_oss_access_key_id(cls, v):
-        if (v is None or v == "") and os.getenv("APP_ENV", "development") != "development":
-            raise ValueError(
-                "OSS_ACCESS_KEY_ID must be set via environment variable in non-development environments. "
-                "Check the server .env file (e.g. /var/lib/xiaoxia-saas-staging/.env)."
-            )
-        return v or ""
-
-    @field_validator("OSS_ACCESS_KEY_SECRET", mode="before")
-    @classmethod
-    def validate_oss_access_key_secret(cls, v):
-        if (v is None or v == "") and os.getenv("APP_ENV", "development") != "development":
-            raise ValueError(
-                "OSS_ACCESS_KEY_SECRET must be set via environment variable in non-development environments. "
-                "Check the server .env file (e.g. /var/lib/xiaoxia-saas-staging/.env)."
-            )
-        return v or ""
-
-    OSS_DIRECT_UPLOAD_MAX_MB: int = Field(
-        default=2000,
-        validation_alias=AliasChoices("OSS_DIRECT_UPLOAD_MAX_MB", "MAX_UPLOAD_SIZE_MB"),
-    )
-    OSS_DIRECT_UPLOAD_EXPIRE_SECONDS: int = 900
-
-    CORS_ORIGINS_RAW: str = "http://localhost:3000,http://localhost:5173,http://localhost:8000"
-
-    # 渲染引擎选择：legacy=旧VideoComposeService，unified=新UnifiedRenderService
-    RENDER_ENGINE: str = "legacy"
-
-    model_config = SettingsConfigDict(
-        env_file=".env",
-        env_file_encoding="utf-8",
-        case_sensitive=False,
-        extra="ignore",
-    )
-
-    @property
-    def CORS_ORIGINS(self) -> list[str]:
-        return [origin.strip() for origin in self.CORS_ORIGINS_RAW.split(",") if origin.strip()]
-
-    @property
-    def database_url(self) -> str:
-        return self.DATABASE_URL
-
-    @property
-    def redis_url(self) -> str:
-        return self.REDIS_URL
-
-    @property
-    def celery_broker_url(self) -> str:
-        return self.CELERY_BROKER_URL
-
-    @property
-    def celery_result_backend(self) -> str:
-        return self.CELERY_RESULT_BACKEND
-
-    @property
-    def oss_endpoint(self) -> str:
-        return self.OSS_ENDPOINT
-
-    @property
-    def oss_access_key_id(self) -> str:
-        return self.OSS_ACCESS_KEY_ID
-
-    @property
-    def oss_access_key_secret(self) -> str:
-        return self.OSS_ACCESS_KEY_SECRET
-
-    @property
-    def oss_bucket_name(self) -> str:
-        return self.OSS_BUCKET_NAME
-
-
-_settings: Optional[Settings] = None
-
-
-def get_settings() -> Settings:
-    global _settings
-    if _settings is None:
-        env = os.getenv("APP_ENV", "development")
-        env_file = f".env.{env}" if env != "development" else ".env"
-        if os.path.exists(env_file):
-            _settings = Settings(_env_file=env_file)
-        else:
-            _settings = Settings()
-    return _settings
-
+from packages.config import APISettings as Settings
+from packages.config import get_api_settings as get_settings
+from packages.config import reload_settings_cache
 
+# 模块级单例（向后兼容）
 settings = get_settings()
+
+
+# 暴露旧的 reload_settings 函数名
+def reload_settings():
+    """重新加载配置（测试用）。"""
+    reload_settings_cache()
+    global settings
+    settings = get_settings()
+    return settings
+
+
+__all__ = ["Settings", "get_settings", "settings", "reload_settings"]

apps/api/app/core/config.py

@@ -1,19 +1,20 @@
-"""Compatibility layer for the canonical API settings module.
+"""向后兼容层 — 配置已统一到 packages.config。
 
-Use `app.config` as the single source of truth for API configuration.
-This module remains only for older imports during migration.
+新代码请使用：
+    from packages.config import get_api_settings, APISettings
 """
 
-from app.config import Settings as AppSettings
-from app.config import get_settings, settings
+from packages.config import APISettings as AppSettings
+from packages.config import get_api_settings as get_settings
+from packages.config import reload_settings_cache
 
 
 def reload_settings() -> AppSettings:
-    """Reload settings for tests and legacy callers."""
-    import app.config as canonical_config
+    """重新加载配置（测试用）。"""
+    reload_settings_cache()
+    return get_settings()
 
-    canonical_config.settings = canonical_config.get_settings()
-    return canonical_config.settings
 
+settings = get_settings()
 
 __all__ = ["AppSettings", "get_settings", "reload_settings", "settings"]

apps/api/app/schemas/generation_task.py

@@ -51,6 +51,11 @@ class CreateGenerationTaskRequest(BaseModel):
         default="",
         description="输出分辨率，格式为 WIDTHxHEIGHT，如 1280x720、1080x1920。为空使用默认 1280x720",
     )
+    # ── 自定义 BGM ──
+    bgm_config: dict = Field(
+        default_factory=dict,
+        description="自定义BGM配置，覆盖模板BGM设置。支持 enabled/source/asset_id/preset_id/audio_url/volume 等字段",
+    )
 
     @model_validator(mode="after")
     def _check_at_least_one_mode(self) -> "CreateGenerationTaskRequest":
@@ -80,6 +85,7 @@ class GenerationTaskResponse(BaseModel):
     batch_id: str = ""
     video_title: str = ""
     resolution: str = ""
+    bgm_config: dict = Field(default_factory=dict)
     status: str
     progress: float
     result_count: int

apps/api/app/services/ai_service.py

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

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,7 +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.template_clip_config import ClipType, TemplateClipConfig
+from packages.domain.plan_generator_utils import (
+    create_clips_from_configs,
+    distribute_assets,
+    generate_default_clips,
+    map_clip_types_for_mode,
+)
+from packages.domain.template_clip_config import TemplateClipConfig
 
 logger = logging.getLogger(__name__)
 
@@ -163,83 +169,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 +188,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 +200,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,26 @@
   - 最低质量分门槛：自动过滤低质量素材
   - 时长多样性：保证选出的素材时长分布均匀（短/中/长各占一定比例）
   - 兼容全部模式：素材库模式和项目模式都可用
+
+纯逻辑部分已抽离到 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  # noqa: F401 - re-export for tests
+from packages.domain.asset_scoring import SHORT_BUCKET_MAX as _SHORT_BUCKET_MAX  # noqa: F401 - re-export for tests
+from packages.domain.asset_scoring import (
+    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 +43,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 +71,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 +85,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 +102,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 +126,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/api/routers.py

@@ -1,8 +0,0 @@
-from fastapi import APIRouter
-
-router = APIRouter()
-
-
-@router.get("/health")
-def health():
-    return {"ok": True, "service": "api"}

apps/web/src/api/assets.ts

@@ -1,443 +0,0 @@
-/**
- * 素材相关 API
- * Phase 1 重构：去掉 project_id，素材直接归属用户
- */
-import apiClient from "./client"
-import { getOrCreateDefaultProject } from "./projects"
-
-/** 素材元数据 */
-export interface AssetMetadata {
-  /** 时长（秒） */
-  duration?: number
-  /** 宽度（像素） */
-  width?: number
-  /** 高度（像素） */
-  height?: number
-  /** 比特率（bps） */
-  bitrate?: number
-  /** 编码格式 */
-  codec?: string
-  /** 帧率 */
-  fps?: number
-  /** 采样率（Hz） */
-  sample_rate?: number
-  /** 声道数 */
-  channels?: number
-  /** 其他扩展字段 */
-  [key: string]: unknown
-}
-
-/** 素材分类状态 */
-export type AssetClassificationStatus = "pending" | "processing" | "completed" | "failed"
-
-/** 素材条目 */
-export interface AssetItem {
-  id: string
-  library_id: string
-  name: string
-  storage_key: string
-  mime_type: string
-  metadata: AssetMetadata
-  file_size?: number
-  file_url?: string
-  thumbnail_url?: string
-  /** 时长（秒），视频/音频素材由后端从 metadata 提取到顶层 */
-  duration?: number
-  status?: string
-  classification_status?: AssetClassificationStatus | null
-  quality_score?: number | null
-  tag_ids?: string[]
-  created_at?: string
-}
-
-/** 素材库 */
-export interface AssetLibraryItem {
-  id: string
-  name: string
-  kind: "video" | "voice" | "image"
-  asset_count?: number
-  total_size?: number
-  created_at?: string
-}
-
-/** 入库任务 */
-export interface IngestJob {
-  id: string
-  library_id: string
-  storage_key: string
-  status: "pending" | "processing" | "completed" | "failed"
-  error_message: string
-  result_asset_id: string
-}
-
-/** 分类任务 */
-export interface ClassificationJob {
-  id: string
-  asset_id: string
-  status: "pending" | "processing" | "completed" | "failed"
-  classification: string
-  confidence: number
-  error_message: string
-}
-
-/** 素材诊断信息 */
-export interface AssetDiagnosis {
-  readiness_score: number
-  readiness_label: string
-  total_assets: number
-  ready_assets: number
-  video_assets: number
-  image_assets: number
-  voice_assets: number
-  total_duration_seconds: number
-  estimated_video_count: number
-  used_assets: number
-  unused_assets: number
-  pending_review_assets: number
-  smart_views: Array<{
-    key: string
-    label: string
-    count: number
-    description: string
-  }>
-  gaps: Array<{
-    key: string
-    severity: "critical" | "warning" | "info"
-    message: string
-    recommendation: string
-  }>
-}
-
-// ─── 素材诊断 ──────────────────────────────────────────────
-
-/** 获取素材诊断信息（可选 asset_id 查单素材，否则全局诊断） */
-export const getAssetDiagnosis = async (assetId?: string): Promise<AssetDiagnosis> => {
-  const params: Record<string, string> = {}
-  if (assetId) params.asset_id = assetId
-  const response = await apiClient.get("/asset-diagnosis", { params })
-  return response.data
-}
-
-// ─── 素材库 ────────────────────────────────────────────────
-
-/** 获取当前用户的所有素材库 */
-export const getAssetLibraries = async (): Promise<AssetLibraryItem[]> => {
-  const response = await apiClient.get("/asset-libraries")
-  return response.data.items || []
-}
-
-/** 创建素材库（自动获取或创建默认项目以提供 project_id） */
-export const createAssetLibrary = async (data: {
-  name: string
-  kind: "video" | "voice" | "image"
-}): Promise<AssetLibraryItem> => {
-  // 后端要求 project_id，前端自动管理默认项目
-  const project = await getOrCreateDefaultProject()
-  const response = await apiClient.post("/asset-libraries", {
-    project_id: project.id,
-    ...data,
-  })
-  return response.data
-}
-
-/** 确保项目下指定 kind 的默认素材库存在（不存在则自动创建） */
-export const ensureDefaultLibrary = async (data: {
-  project_id: string
-  kind: "video" | "voice" | "image"
-}): Promise<AssetLibraryItem> => {
-  const response = await apiClient.post("/asset-libraries/ensure-default", data)
-  return response.data
-}
-
-/** 删除素材库 */
-export const deleteAssetLibrary = async (libraryId: string): Promise<void> => {
-  await apiClient.delete(`/asset-libraries/${libraryId}`)
-}
-
-// ─── 素材 ──────────────────────────────────────────────────
-
-/** 获取素材库下的所有素材 */
-export const getAssets = async (
-  libraryId: string,
-  options?: { status?: string; page?: number; page_size?: number },
-): Promise<{ items: AssetItem[]; total: number }> => {
-  const params: Record<string, string | number> = { library_id: libraryId }
-  // 默认拉取所有非删除状态的素材（ready/ingesting/processing/uploading/error/failed）
-  // 让用户能看到"处理中"的素材，不会以为上传失败了
-  if (options?.status) {
-    params.status = options.status
-  }
-  if (options?.page) params.page = options.page
-  if (options?.page_size) params.page_size = options.page_size
-  const response = await apiClient.get("/assets", { params })
-  const data = response.data || {}
-  const items: AssetItem[] = data.items || []
-  const total: number = typeof data.total === "number" ? data.total : items.length
-  return { items, total }
-}
-
-/** 按类型获取素材（如 voice/video/image），支持可选筛选 */
-export const getAssetsByKind = async (
-  kind: string,
-  filters?: {
-    keyword?: string
-    gender?: string
-    style?: string
-    tag_ids?: string[]
-    limit?: number
-    page?: number
-    page_size?: number
-  },
-): Promise<AssetItem[]> => {
-  const params: Record<string, string | number> = { kind }
-  if (filters?.keyword) params.keyword = filters.keyword
-  if (filters?.gender) params.gender = filters.gender
-  if (filters?.style) params.style = filters.style
-  if (filters?.tag_ids?.length) params.tag_ids = filters.tag_ids.join(",")
-  if (filters?.limit) params.limit = filters.limit
-  if (filters?.page) params.page = filters.page
-  if (filters?.page_size) params.page_size = filters.page_size
-  const response = await apiClient.get("/assets", { params })
-  return response.data.items || []
-}
-
-/** 创建素材（上传文件后调用，附带 metadata） */
-export const createAsset = async (data: {
-  library_id: string
-  name: string
-  storage_key: string
-  mime_type: string
-  metadata?: AssetMetadata
-}): Promise<AssetItem> => {
-  const response = await apiClient.post("/assets", data)
-  return response.data
-}
-
-/** 更新素材（名称、metadata 等） */
-export const updateAsset = async (
-  assetId: string,
-  data: { name?: string; metadata?: AssetMetadata },
-): Promise<AssetItem> => {
-  const response = await apiClient.put(`/assets/${assetId}`, data)
-  return response.data
-}
-
-/** 更新素材审核状态 */
-export const updateAssetReviewStatus = async (
-  assetId: string,
-  reviewStatus: "pending_review" | "approved" | "rejected",
-): Promise<AssetItem> => {
-  const response = await apiClient.patch(`/assets/${assetId}/review`, {
-    review_status: reviewStatus,
-  })
-  return response.data
-}
-
-/** 删除素材 */
-export const deleteAsset = async (assetId: string): Promise<void> => {
-  await apiClient.delete(`/assets/${assetId}`)
-}
-
-// ─── 上传 ──────────────────────────────────────────────────
-
-/** 表单上传素材（小文件） */
-export const uploadAsset = async (
-  formData: FormData,
-): Promise<{ storage_key: string; ingest_job_id: string; url: string }> => {
-  const response = await apiClient.post("/upload", formData, {
-    headers: { "Content-Type": "multipart/form-data" },
-    timeout: 30 * 60 * 1000,
-  })
-  return response.data
-}
-
-/** 预签名直传准备 */
-export const prepareDirectUpload = async (data: {
-  project_id: string
-  library_id: string
-  filename: string
-  content_type: string
-  file_size: number
-}): Promise<{
-  upload_url: string
-  method: string
-  storage_key: string
-  expires_at: string
-  fields: Record<string, string>
-  max_size_bytes: number
-}> => {
-  const response = await apiClient.post("/upload/direct/prepare", data)
-  return response.data
-}
-
-/** 直传完成确认 */
-export const completeDirectUpload = async (data: {
-  project_id: string
-  library_id: string
-  storage_key: string
-}): Promise<{ storage_key: string; ingest_job_id: string }> => {
-  const response = await apiClient.post("/upload/direct/complete", data)
-  return response.data
-}
-
-/** 直传上传（大文件推荐），支持可选进度回调 */
-export const uploadAssetDirect = async (data: {
-  file: File
-  library_id: string
-  onProgress?: (percent: number) => void
-}): Promise<{ storage_key: string; ingest_job_id: string }> => {
-  // 后端要求 project_id，前端自动获取默认项目
-  const project = await getOrCreateDefaultProject()
-
-  const prepared = await prepareDirectUpload({
-    project_id: project.id,
-    library_id: data.library_id,
-    filename: data.file.name,
-    content_type: data.file.type || "application/octet-stream",
-    file_size: data.file.size,
-  })
-
-  const directForm = new FormData()
-  Object.entries(prepared.fields).forEach(([key, value]) => directForm.append(key, value))
-  directForm.append("file", data.file)
-
-  // 使用 XMLHttpRequest 以获取上传进度 + 超时控制 + 详细错误诊断
-  await new Promise<void>((resolve, reject) => {
-    const xhr = new XMLHttpRequest()
-    xhr.open(prepared.method, prepared.upload_url)
-
-    // 超时 10 分钟
-    xhr.timeout = 10 * 60 * 1000
-
-    xhr.upload.onprogress = (e) => {
-      if (e.lengthComputable && data.onProgress) {
-        data.onProgress(Math.round((e.loaded / e.total) * 100))
-      }
-    }
-    xhr.onload = () => {
-      if (xhr.status >= 200 && xhr.status < 300) {
-        resolve()
-      } else {
-        // 解析 OSS 返回的 XML 错误信息
-        let ossError = ""
-        try {
-          const codeMatch = xhr.responseText.match(/<Code>([^<]+)<\/Code>/)
-          const msgMatch = xhr.responseText.match(/<Message>([^<]+)<\/Message>/)
-          if (codeMatch || msgMatch) {
-            ossError = ` [OSS: ${codeMatch?.[1] || "unknown"} - ${msgMatch?.[1] || "unknown"}]`
-          }
-        } catch {
-          // 无法解析响应体
-        }
-        const detail = `OSS 直传失败: HTTP ${xhr.status} ${xhr.statusText}${ossError}`
-        console.error("[OSS Upload] 直传失败:", {
-          url: prepared.upload_url,
-          storage_key: prepared.storage_key,
-          status: xhr.status,
-          statusText: xhr.statusText,
-        })
-        reject(new Error(detail))
-      }
-    }
-    xhr.onerror = () => {
-      console.error("[OSS Upload] 网络错误:", {
-        url: prepared.upload_url,
-        storage_key: prepared.storage_key,
-      })
-      reject(new Error("OSS 上传网络错误，请检查网络连接"))
-    }
-    xhr.ontimeout = () => {
-      console.error("[OSS Upload] 上传超时:", {
-        url: prepared.upload_url,
-        storage_key: prepared.storage_key,
-      })
-      reject(new Error("OSS 上传超时（10分钟），请检查网络或尝试更小的文件"))
-    }
-    xhr.send(directForm)
-  })
-
-  return completeDirectUpload({
-    project_id: project.id,
-    library_id: data.library_id,
-    storage_key: prepared.storage_key,
-  })
-}
-
-// ─── 入库 / 分类任务 ───────────────────────────────────────
-
-/** 查询入库任务状态 */
-export const getIngestJob = async (jobId: string): Promise<IngestJob> => {
-  const response = await apiClient.get(`/ingest-jobs/${jobId}`)
-  return response.data
-}
-
-/** 提交素材分类任务 */
-export const submitClassificationJob = async (data: {
-  asset_id: string
-}): Promise<ClassificationJob> => {
-  const response = await apiClient.post("/classification-jobs", data)
-  return response.data
-}
-
-/** 查询分类任务状态 */
-export const getClassificationJob = async (jobId: string): Promise<ClassificationJob> => {
-  const response = await apiClient.get(`/classification-jobs/${jobId}`)
-  return response.data
-}
-
-// ─── 批量操作 ───────────────────────────────────────────────
-
-/** 批量操作结果 */
-export interface BatchOperationResult {
-  succeeded: string[]
-  failed: string[]
-  total: number
-  success_count: number
-  failure_count: number
-}
-
-/** 统一批量操作结果归一化，防御后端字段缺失或格式不一致 */
-const normalizeBatchResult = (raw: Record<string, unknown>): BatchOperationResult => {
-  const succeeded = Array.isArray(raw.succeeded) ? (raw.succeeded as string[]) : []
-  const failed = Array.isArray(raw.failed) ? (raw.failed as string[]) : []
-  const success_count = typeof raw.success_count === "number" ? raw.success_count : succeeded.length
-  const failure_count = typeof raw.failure_count === "number" ? raw.failure_count : failed.length
-  const total = typeof raw.total === "number" ? raw.total : success_count + failure_count
-  return { succeeded, failed, total, success_count, failure_count }
-}
-
-/** 批量删除素材 */
-export const batchDeleteAssets = async (assetIds: string[]): Promise<BatchOperationResult> => {
-  const response = await apiClient.post("/assets/batch-delete", {
-    asset_ids: assetIds,
-  })
-  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
-}
-
-/** 批量打标签 */
-export const batchTagAssets = async (data: {
-  asset_ids: string[]
-  tags: string[]
-  mode: "add" | "replace"
-}): Promise<BatchOperationResult> => {
-  const response = await apiClient.post("/assets/batch-tag", data)
-  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
-}
-
-/** 批量改分类 */
-export const batchClassifyAssets = async (data: {
-  asset_ids: string[]
-  category: string
-}): Promise<BatchOperationResult> => {
-  const response = await apiClient.post("/assets/batch-classify", data)
-  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
-}
-
-/** 批量智能标记 */
-export const batchMarkAssets = async (data: {
-  asset_ids: string[]
-  smart_view: "recommended" | "caution" | "high_risk"
-}): Promise<BatchOperationResult> => {
-  const response = await apiClient.post("/assets/batch-mark", data)
-  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
-}

apps/web/src/api/assets/assets.ts

@@ -0,0 +1,87 @@
+/**
+ * 素材 CRUD API
+ */
+import apiClient from "../client"
+import type { AssetItem, AssetMetadata } from "./types"
+
+/** 获取素材库下的所有素材 */
+export const getAssets = async (
+  libraryId: string,
+  options?: {
+    status?: string
+    page?: number
+    page_size?: number
+  },
+): Promise<{ items: AssetItem[]; total: number }> => {
+  const params: Record<string, string | number> = { library_id: libraryId }
+  if (options?.status) params.status = options.status
+  if (options?.page) params.page = options.page
+  if (options?.page_size) params.page_size = options.page_size
+  const response = await apiClient.get("/assets", { params })
+  const data = response.data || {}
+  const items: AssetItem[] = data.items || []
+  const total: number = typeof data.total === "number" ? data.total : items.length
+  return { items, total }
+}
+
+/** 按类型获取素材（如 voice/video/image），支持可选筛选 */
+export const getAssetsByKind = async (
+  kind: string,
+  filters?: {
+    keyword?: string
+    gender?: string
+    style?: string
+    tag_ids?: string[]
+    limit?: number
+    page?: number
+    page_size?: number
+  },
+): Promise<AssetItem[]> => {
+  const params: Record<string, string | number> = { kind }
+  if (filters?.keyword) params.keyword = filters.keyword
+  if (filters?.gender) params.gender = filters.gender
+  if (filters?.style) params.style = filters.style
+  if (filters?.tag_ids?.length) params.tag_ids = filters.tag_ids.join(",")
+  if (filters?.limit) params.limit = filters.limit
+  if (filters?.page) params.page = filters.page
+  if (filters?.page_size) params.page_size = filters.page_size
+  const response = await apiClient.get("/assets", { params })
+  return response.data.items || []
+}
+
+/** 创建素材（上传文件后调用，附带 metadata） */
+export const createAsset = async (data: {
+  library_id: string
+  name: string
+  storage_key: string
+  mime_type: string
+  metadata?: AssetMetadata
+}): Promise<AssetItem> => {
+  const response = await apiClient.post("/assets", data)
+  return response.data
+}
+
+/** 更新素材（名称、metadata 等） */
+export const updateAsset = async (
+  assetId: string,
+  data: { name?: string; metadata?: AssetMetadata },
+): Promise<AssetItem> => {
+  const response = await apiClient.put(`/assets/${assetId}`, data)
+  return response.data
+}
+
+/** 更新素材审核状态 */
+export const updateAssetReviewStatus = async (
+  assetId: string,
+  reviewStatus: "pending_review" | "approved" | "rejected",
+): Promise<AssetItem> => {
+  const response = await apiClient.patch(`/assets/${assetId}/review`, {
+    review_status: reviewStatus,
+  })
+  return response.data
+}
+
+/** 删除素材 */
+export const deleteAsset = async (assetId: string): Promise<void> => {
+  await apiClient.delete(`/assets/${assetId}`)
+}

apps/web/src/api/assets/batch.ts

@@ -0,0 +1,51 @@
+/**
+ * 素材批量操作 API
+ */
+import apiClient from "../client"
+import type { BatchOperationResult } from "./types"
+
+/** 统一批量操作结果归一化，防御后端字段缺失或格式不一致 */
+export const normalizeBatchResult = (raw: Record<string, unknown>): BatchOperationResult => {
+  const succeeded = Array.isArray(raw.succeeded) ? (raw.succeeded as string[]) : []
+  const failed = Array.isArray(raw.failed) ? (raw.failed as string[]) : []
+  const success_count = typeof raw.success_count === "number" ? raw.success_count : succeeded.length
+  const failure_count = typeof raw.failure_count === "number" ? raw.failure_count : failed.length
+  const total = typeof raw.total === "number" ? raw.total : success_count + failure_count
+  return { succeeded, failed, total, success_count, failure_count }
+}
+
+/** 批量删除素材 */
+export const batchDeleteAssets = async (assetIds: string[]): Promise<BatchOperationResult> => {
+  const response = await apiClient.post("/assets/batch-delete", {
+    asset_ids: assetIds,
+  })
+  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
+}
+
+/** 批量打标签 */
+export const batchTagAssets = async (data: {
+  asset_ids: string[]
+  tags: string[]
+  mode: "add" | "replace"
+}): Promise<BatchOperationResult> => {
+  const response = await apiClient.post("/assets/batch-tag", data)
+  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
+}
+
+/** 批量改分类 */
+export const batchClassifyAssets = async (data: {
+  asset_ids: string[]
+  category: string
+}): Promise<BatchOperationResult> => {
+  const response = await apiClient.post("/assets/batch-classify", data)
+  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
+}
+
+/** 批量智能标记 */
+export const batchMarkAssets = async (data: {
+  asset_ids: string[]
+  smart_view: "recommended" | "caution" | "high_risk"
+}): Promise<BatchOperationResult> => {
+  const response = await apiClient.post("/assets/batch-mark", data)
+  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
+}

apps/web/src/api/assets/diagnosis.ts

@@ -0,0 +1,13 @@
+/**
+ * 素材诊断 API
+ */
+import apiClient from "../client"
+import type { AssetDiagnosis } from "./types"
+
+/** 获取素材诊断信息（可选 asset_id 查单素材，否则全局诊断） */
+export const getAssetDiagnosis = async (assetId?: string): Promise<AssetDiagnosis> => {
+  const params: Record<string, string> = {}
+  if (assetId) params.asset_id = assetId
+  const response = await apiClient.get("/asset-diagnosis", { params })
+  return response.data
+}

apps/web/src/api/assets/index.ts

@@ -0,0 +1,55 @@
+/**
+ * 素材相关 API — 按模块拆分后的统一入口
+ * 保持与原 assets.ts 相同的导出结构，向后兼容
+ */
+
+// 类型
+export type {
+  AssetMetadata,
+  AssetClassificationStatus,
+  AssetItem,
+  AssetLibraryItem,
+  IngestJob,
+  ClassificationJob,
+  AssetDiagnosis,
+  BatchOperationResult,
+  UploadResult,
+  DirectUploadPrepareResult,
+  DirectUploadCompleteResult,
+} from "./types"
+
+// 素材诊断
+export { getAssetDiagnosis } from "./diagnosis"
+
+// 素材库
+export {
+  getAssetLibraries,
+  createAssetLibrary,
+  ensureDefaultLibrary,
+  deleteAssetLibrary,
+} from "./libraries"
+
+// 素材 CRUD
+export {
+  getAssets,
+  getAssetsByKind,
+  createAsset,
+  updateAsset,
+  updateAssetReviewStatus,
+  deleteAsset,
+} from "./assets"
+
+// 上传
+export { uploadAsset, prepareDirectUpload, completeDirectUpload, uploadAssetDirect } from "./upload"
+
+// 任务
+export { getIngestJob, submitClassificationJob, getClassificationJob } from "./jobs"
+
+// 批量操作
+export {
+  normalizeBatchResult,
+  batchDeleteAssets,
+  batchTagAssets,
+  batchClassifyAssets,
+  batchMarkAssets,
+} from "./batch"

apps/web/src/api/assets/jobs.ts

@@ -0,0 +1,25 @@
+/**
+ * 入库任务 & 分类任务 API
+ */
+import apiClient from "../client"
+import type { IngestJob, ClassificationJob } from "./types"
+
+/** 查询入库任务状态 */
+export const getIngestJob = async (jobId: string): Promise<IngestJob> => {
+  const response = await apiClient.get(`/ingest-jobs/${jobId}`)
+  return response.data
+}
+
+/** 提交素材分类任务 */
+export const submitClassificationJob = async (data: {
+  asset_id: string
+}): Promise<ClassificationJob> => {
+  const response = await apiClient.post("/classification-jobs", data)
+  return response.data
+}
+
+/** 查询分类任务状态 */
+export const getClassificationJob = async (jobId: string): Promise<ClassificationJob> => {
+  const response = await apiClient.get(`/classification-jobs/${jobId}`)
+  return response.data
+}

apps/web/src/api/assets/libraries.ts

@@ -0,0 +1,39 @@
+/**
+ * 素材库 API
+ */
+import apiClient from "../client"
+import { getOrCreateDefaultProject } from "../projects"
+import type { AssetLibraryItem } from "./types"
+
+/** 获取当前用户的所有素材库 */
+export const getAssetLibraries = async (): Promise<AssetLibraryItem[]> => {
+  const response = await apiClient.get("/asset-libraries")
+  return response.data.items || []
+}
+
+/** 创建素材库（自动获取或创建默认项目以提供 project_id） */
+export const createAssetLibrary = async (data: {
+  name: string
+  kind: "video" | "voice" | "image"
+}): Promise<AssetLibraryItem> => {
+  const project = await getOrCreateDefaultProject()
+  const response = await apiClient.post("/asset-libraries", {
+    project_id: project.id,
+    ...data,
+  })
+  return response.data
+}
+
+/** 确保项目下指定 kind 的默认素材库存在 */
+export const ensureDefaultLibrary = async (data: {
+  project_id: string
+  kind: "video" | "voice" | "image"
+}): Promise<AssetLibraryItem> => {
+  const response = await apiClient.post("/asset-libraries/ensure-default", data)
+  return response.data
+}
+
+/** 删除素材库 */
+export const deleteAssetLibrary = async (libraryId: string): Promise<void> => {
+  await apiClient.delete(`/asset-libraries/${libraryId}`)
+}

apps/web/src/api/assets/types.ts

@@ -0,0 +1,138 @@
+/**
+ * 素材相关类型定义
+ */
+
+/** 素材元数据 */
+export interface AssetMetadata {
+  /** 时长（秒） */
+  duration?: number
+  /** 宽度（像素） */
+  width?: number
+  /** 高度（像素） */
+  height?: number
+  /** 比特率（bps） */
+  bitrate?: number
+  /** 编码格式 */
+  codec?: string
+  /** 帧率 */
+  fps?: number
+  /** 采样率（Hz） */
+  sample_rate?: number
+  /** 声道数 */
+  channels?: number
+  /** 其他扩展字段 */
+  [key: string]: unknown
+}
+
+/** 素材分类状态 */
+export type AssetClassificationStatus = "pending" | "processing" | "completed" | "failed"
+
+/** 素材条目 */
+export interface AssetItem {
+  id: string
+  library_id: string
+  name: string
+  storage_key: string
+  mime_type: string
+  metadata: AssetMetadata
+  file_size?: number
+  file_url?: string
+  thumbnail_url?: string
+  /** 时长（秒），视频/音频素材由后端从 metadata 提取到顶层 */
+  duration?: number
+  status?: string
+  classification_status?: AssetClassificationStatus | null
+  quality_score?: number | null
+  tag_ids?: string[]
+  created_at?: string
+}
+
+/** 素材库 */
+export interface AssetLibraryItem {
+  id: string
+  name: string
+  kind: "video" | "voice" | "image"
+  asset_count?: number
+  total_size?: number
+  created_at?: string
+}
+
+/** 入库任务 */
+export interface IngestJob {
+  id: string
+  library_id: string
+  storage_key: string
+  status: "pending" | "processing" | "completed" | "failed"
+  error_message: string
+  result_asset_id: string
+}
+
+/** 分类任务 */
+export interface ClassificationJob {
+  id: string
+  asset_id: string
+  status: "pending" | "processing" | "completed" | "failed"
+  classification: string
+  confidence: number
+  error_message: string
+}
+
+/** 素材诊断信息 */
+export interface AssetDiagnosis {
+  readiness_score: number
+  readiness_label: string
+  total_assets: number
+  ready_assets: number
+  video_assets: number
+  image_assets: number
+  voice_assets: number
+  total_duration_seconds: number
+  estimated_video_count: number
+  used_assets: number
+  unused_assets: number
+  pending_review_assets: number
+  smart_views: Array<{
+    key: string
+    label: string
+    count: number
+    description: string
+  }>
+  gaps: Array<{
+    key: string
+    severity: "critical" | "warning" | "info"
+    message: string
+    recommendation: string
+  }>
+}
+
+/** 批量操作结果 */
+export interface BatchOperationResult {
+  succeeded: string[]
+  failed: string[]
+  total: number
+  success_count: number
+  failure_count: number
+}
+
+/** 上传返回 */
+export interface UploadResult {
+  storage_key: string
+  ingest_job_id: string
+  url: string
+}
+
+/** 预签名直传准备返回 */
+export interface DirectUploadPrepareResult {
+  upload_url: string
+  method: string
+  storage_key: string
+  expires_at: string
+  fields: Record<string, string>
+  max_size_bytes: number
+}
+
+/** 直传完成确认返回 */
+export interface DirectUploadCompleteResult {
+  storage_key: string
+  ingest_job_id: string
+}

apps/web/src/api/assets/upload.ts

@@ -0,0 +1,119 @@
+/**
+ * 上传相关 API（表单上传 + OSS 直传）
+ */
+import apiClient from "../client"
+import { getOrCreateDefaultProject } from "../projects"
+import type { UploadResult, DirectUploadPrepareResult, DirectUploadCompleteResult } from "./types"
+
+/** 表单上传素材（小文件） */
+export const uploadAsset = async (formData: FormData): Promise<UploadResult> => {
+  const response = await apiClient.post("/upload", formData, {
+    headers: { "Content-Type": "multipart/form-data" },
+    timeout: 30 * 60 * 1000,
+  })
+  return response.data
+}
+
+/** 预签名直传准备 */
+export const prepareDirectUpload = async (data: {
+  project_id: string
+  library_id: string
+  filename: string
+  content_type: string
+  file_size: number
+}): Promise<DirectUploadPrepareResult> => {
+  const response = await apiClient.post("/upload/direct/prepare", data)
+  return response.data
+}
+
+/** 直传完成确认 */
+export const completeDirectUpload = async (data: {
+  project_id: string
+  library_id: string
+  storage_key: string
+}): Promise<DirectUploadCompleteResult> => {
+  const response = await apiClient.post("/upload/direct/complete", data)
+  return response.data
+}
+
+/** 直传上传（大文件推荐），支持可选进度回调 */
+export const uploadAssetDirect = async (data: {
+  file: File
+  library_id: string
+  onProgress?: (percent: number) => void
+}): Promise<DirectUploadCompleteResult> => {
+  const project = await getOrCreateDefaultProject()
+
+  const prepared = await prepareDirectUpload({
+    project_id: project.id,
+    library_id: data.library_id,
+    filename: data.file.name,
+    content_type: data.file.type || "application/octet-stream",
+    file_size: data.file.size,
+  })
+
+  const directForm = new FormData()
+  Object.entries(prepared.fields).forEach(([key, value]) => directForm.append(key, value))
+  directForm.append("file", data.file)
+
+  // 使用 XMLHttpRequest 以获取上传进度 + 超时控制 + 详细错误诊断
+  await new Promise<void>((resolve, reject) => {
+    const xhr = new XMLHttpRequest()
+    xhr.open(prepared.method, prepared.upload_url)
+
+    // 超时 10 分钟
+    xhr.timeout = 10 * 60 * 1000
+
+    xhr.upload.onprogress = (e) => {
+      if (e.lengthComputable && data.onProgress) {
+        data.onProgress(Math.round((e.loaded / e.total) * 100))
+      }
+    }
+    xhr.onload = () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        resolve()
+      } else {
+        // 解析 OSS 返回的 XML 错误信息
+        let ossError = ""
+        try {
+          const codeMatch = xhr.responseText.match(/<Code>([^<]+)<\/Code>/)
+          const msgMatch = xhr.responseText.match(/<Message>([^<]+)<\/Message>/)
+          if (codeMatch || msgMatch) {
+            ossError = ` [OSS: ${codeMatch?.[1] || "unknown"} - ${msgMatch?.[1] || "unknown"}]`
+          }
+        } catch {
+          // 无法解析响应体
+        }
+        const detail = `OSS 直传失败: HTTP ${xhr.status} ${xhr.statusText}${ossError}`
+        console.error("[OSS Upload] 直传失败:", {
+          url: prepared.upload_url,
+          storage_key: prepared.storage_key,
+          status: xhr.status,
+          statusText: xhr.statusText,
+        })
+        reject(new Error(detail))
+      }
+    }
+    xhr.onerror = () => {
+      console.error("[OSS Upload] 网络错误:", {
+        url: prepared.upload_url,
+        storage_key: prepared.storage_key,
+      })
+      reject(new Error("OSS 上传网络错误，请检查网络连接"))
+    }
+    xhr.ontimeout = () => {
+      console.error("[OSS Upload] 上传超时:", {
+        url: prepared.upload_url,
+        storage_key: prepared.storage_key,
+      })
+      reject(new Error("OSS 上传超时（10分钟），请检查网络或尝试更小的文件"))
+    }
+    xhr.send(directForm)
+  })
+
+  return completeDirectUpload({
+    project_id: project.id,
+    library_id: data.library_id,
+    storage_key: prepared.storage_key,
+  })
+}

apps/web/src/api/bgm.ts

@@ -1,68 +0,0 @@
-/**
- * BGM 预设音乐 API
- * 对接后端 BGM 混音能力：预设列表查询（按风格分类 + 关键词搜索）
- */
-import apiClient from "./client"
-
-/* ──────────── 类型 ──────────── */
-
-/** BGM 风格分类 */
-export type BgmCategory = "轻快" | "治愈" | "科技" | "电商"
-
-/** BGM 预设项 */
-export interface BgmPreset {
-  id: string
-  name: string
-  category: BgmCategory
-  /** 音频文件 URL */
-  url: string
-  /** 时长（秒） */
-  duration: number
-  /** 关键词标签 */
-  tags: string[]
-  /** 封面图 URL */
-  cover_url?: string
-}
-
-/** BGM 预设列表查询参数 */
-export interface BgmPresetsQuery {
-  category?: BgmCategory | string
-  keyword?: string
-}
-
-/** BGM 混音配置（嵌入模板） */
-export interface BgmMixConfig {
-  /** 是否启用 BGM */
-  enabled: boolean
-  /** 选中的 BGM ID */
-  music_id: string
-  /** BGM 音量 0-100 */
-  volume: number
-  /** 淡入时长（秒） 0-3 */
-  fade_in: number
-  /** 淡出时长（秒） 0-3 */
-  fade_out: number
-  /** 人声闪避（sidechain） */
-  voice_dodge: boolean
-}
-
-/** 默认 BGM 混音配置 */
-export const DEFAULT_BGM_MIX_CONFIG: BgmMixConfig = {
-  enabled: false,
-  music_id: "",
-  volume: 50,
-  fade_in: 0.5,
-  fade_out: 0.5,
-  voice_dodge: true,
-}
-
-/* ──────────── API ──────────── */
-
-/** 获取 BGM 预设列表 */
-export const getBgmPresets = async (params?: BgmPresetsQuery): Promise<BgmPreset[]> => {
-  const searchParams: Record<string, string> = {}
-  if (params?.category) searchParams.category = params.category
-  if (params?.keyword) searchParams.keyword = params.keyword
-  const res = await apiClient.get("/bgm/presets", { params: searchParams })
-  return res.data?.data ?? res.data ?? []
-}

apps/web/src/api/bgm/bgm.ts

@@ -0,0 +1,14 @@
+/**
+ * BGM 预设音乐 API 函数
+ */
+import apiClient from "../client"
+import type { BgmPreset, BgmPresetsQuery } from "./types"
+
+/** 获取 BGM 预设列表 */
+export const getBgmPresets = async (params?: BgmPresetsQuery): Promise<BgmPreset[]> => {
+  const searchParams: Record<string, string> = {}
+  if (params?.category) searchParams.category = params.category
+  if (params?.keyword) searchParams.keyword = params.keyword
+  const res = await apiClient.get("/bgm/presets", { params: searchParams })
+  return res.data?.data ?? res.data ?? []
+}

apps/web/src/api/bgm/constants.ts

@@ -0,0 +1,14 @@
+/**
+ * BGM 相关常量
+ */
+import type { BgmMixConfig } from "./types"
+
+/** 默认 BGM 混音配置 */
+export const DEFAULT_BGM_MIX_CONFIG: BgmMixConfig = {
+  enabled: false,
+  music_id: "",
+  volume: 50,
+  fade_in: 0.5,
+  fade_out: 0.5,
+  voice_dodge: true,
+}

apps/web/src/api/bgm/index.ts

@@ -0,0 +1,13 @@
+/**
+ * BGM API — 目录化入口
+ * 保持与原 bgm.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type { BgmCategory, BgmPreset, BgmPresetsQuery, BgmMixConfig } from "./types"
+
+// 常量
+export { DEFAULT_BGM_MIX_CONFIG } from "./constants"
+
+// API 函数
+export { getBgmPresets } from "./bgm"

apps/web/src/api/bgm/types.ts

@@ -0,0 +1,43 @@
+/**
+ * BGM 相关类型定义
+ */
+
+/** BGM 风格分类 */
+export type BgmCategory = "轻快" | "治愈" | "科技" | "电商"
+
+/** BGM 预设项 */
+export interface BgmPreset {
+  id: string
+  name: string
+  category: BgmCategory
+  /** 音频文件 URL */
+  url: string
+  /** 时长（秒） */
+  duration: number
+  /** 关键词标签 */
+  tags: string[]
+  /** 封面图 URL */
+  cover_url?: string
+}
+
+/** BGM 预设列表查询参数 */
+export interface BgmPresetsQuery {
+  category?: BgmCategory | string
+  keyword?: string
+}
+
+/** BGM 混音配置（嵌入模板） */
+export interface BgmMixConfig {
+  /** 是否启用 BGM */
+  enabled: boolean
+  /** 选中的 BGM ID */
+  music_id: string
+  /** BGM 音量 0-100 */
+  volume: number
+  /** 淡入时长（秒） 0-3 */
+  fade_in: number
+  /** 淡出时长（秒） 0-3 */
+  fade_out: number
+  /** 人声闪避（sidechain） */
+  voice_dodge: boolean
+}

apps/web/src/api/duplication/duplication.ts

@@ -0,0 +1,38 @@
+/**
+ * 查重 API 函数
+ */
+import apiClient from "../client"
+import type { DuplicationDetail, DuplicationRecord, DuplicationUploadResponse } from "./types"
+
+/** 上传视频进行查重 */
+export const uploadForDuplication = async (file: File): Promise<DuplicationUploadResponse> => {
+  const formData = new FormData()
+  formData.append("file", file)
+  const response = await apiClient.post("/duplication/upload", formData, {
+    headers: { "Content-Type": "multipart/form-data" },
+  })
+  return response.data
+}
+
+/** 获取查重记录列表 */
+export const getDuplicationRecords = async (): Promise<DuplicationRecord[]> => {
+  const response = await apiClient.get("/duplication/records")
+  return response.data
+}
+
+/** 获取查重详情 */
+export const getDuplicationDetail = async (recordId: string): Promise<DuplicationDetail> => {
+  const response = await apiClient.get(`/duplication/records/${recordId}`)
+  return response.data
+}
+
+/** 删除查重记录 */
+export const deleteDuplicationRecord = async (recordId: string): Promise<void> => {
+  await apiClient.delete(`/duplication/records/${recordId}`)
+}
+
+/** 重新查重 */
+export const retryDuplication = async (recordId: string): Promise<DuplicationUploadResponse> => {
+  const response = await apiClient.post(`/duplication/records/${recordId}/retry`)
+  return response.data
+}

apps/web/src/api/duplication/index.ts

@@ -0,0 +1,22 @@
+/**
+ * 查重 API — 目录化入口
+ * 保持与原 duplication.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type {
+  DuplicationStatus,
+  DuplicationRecord,
+  DuplicateSegment,
+  DuplicationDetail,
+  DuplicationUploadResponse,
+} from "./types"
+
+// API 函数
+export {
+  uploadForDuplication,
+  getDuplicationRecords,
+  getDuplicationDetail,
+  deleteDuplicationRecord,
+  retryDuplication,
+} from "./duplication"

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

@@ -1,8 +1,6 @@
 /**
- * 查重 API 模块
- * 提供视频查重相关接口
+ * 查重相关类型定义
  */
-import apiClient from "./client"
 
 /** 查重记录状态 */
 export type DuplicationStatus = "pending" | "processing" | "completed" | "failed"
@@ -62,38 +60,3 @@ export interface DuplicationUploadResponse {
   /** 消息 */
   message: string
 }
-
-// ============ API 函数 ============
-
-/** 上传视频进行查重 */
-export const uploadForDuplication = async (file: File): Promise<DuplicationUploadResponse> => {
-  const formData = new FormData()
-  formData.append("file", file)
-  const response = await apiClient.post("/duplication/upload", formData, {
-    headers: { "Content-Type": "multipart/form-data" },
-  })
-  return response.data
-}
-
-/** 获取查重记录列表 */
-export const getDuplicationRecords = async (): Promise<DuplicationRecord[]> => {
-  const response = await apiClient.get("/duplication/records")
-  return response.data
-}
-
-/** 获取查重详情 */
-export const getDuplicationDetail = async (recordId: string): Promise<DuplicationDetail> => {
-  const response = await apiClient.get(`/duplication/records/${recordId}`)
-  return response.data
-}
-
-/** 删除查重记录 */
-export const deleteDuplicationRecord = async (recordId: string): Promise<void> => {
-  await apiClient.delete(`/duplication/records/${recordId}`)
-}
-
-/** 重新查重 */
-export const retryDuplication = async (recordId: string): Promise<DuplicationUploadResponse> => {
-  const response = await apiClient.post(`/duplication/records/${recordId}/retry`)
-  return response.data
-}

apps/web/src/api/editing-planner/constants.ts

@@ -0,0 +1,20 @@
+/**
+ * 模板编辑器常量
+ */
+import type { TemplateMode } from "./types"
+
+/** 模式显示名称映射 */
+export const MODE_LABELS: Record<TemplateMode, string> = {
+  pip: "混剪",
+  voice_over: "人物口播",
+  one_take: "一镜到底",
+  voice_pip: "口播+混剪",
+}
+
+/** 模式颜色映射 */
+export const MODE_COLORS: Record<TemplateMode, string> = {
+  pip: "blue",
+  voice_over: "green",
+  one_take: "orange",
+  voice_pip: "purple",
+}

apps/web/src/api/editing-planner/index.ts

@@ -0,0 +1,36 @@
+/**
+ * 模板编辑器 API — 目录化入口
+ * 保持与原 editing-planner.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type {
+  TemplateMode,
+  TitleConfig,
+  SubtitleConfig,
+  BgmConfig,
+  TemplateSegment,
+  EditingTemplate,
+  TemplateCategory,
+  SaveTemplatePayload,
+  GenerateFromTemplatePayload,
+  ValidationWarningDetails,
+  ValidateWarning,
+  GenerateFromTemplateResponse,
+  ListTemplatesResponse,
+  ListCategoriesResponse,
+} from "./types"
+
+// 常量
+export { MODE_LABELS, MODE_COLORS } from "./constants"
+
+// API 函数
+export {
+  getEditingTemplates,
+  getEditingTemplate,
+  createEditingTemplate,
+  updateEditingTemplate,
+  deleteEditingTemplate,
+  getTemplateCategories,
+  generateFromTemplate,
+} from "./templates"

apps/web/src/api/editing-planner/templates.ts

@@ -0,0 +1,78 @@
+/**
+ * 模板编辑器 API 函数
+ */
+import apiClient from "../client"
+import type {
+  EditingTemplate,
+  TemplateCategory,
+  SaveTemplatePayload,
+  GenerateFromTemplatePayload,
+  GenerateFromTemplateResponse,
+  ListTemplatesResponse,
+  ListCategoriesResponse,
+} from "./types"
+
+/** 获取模板列表 */
+export const getEditingTemplates = async (params?: {
+  category?: string
+  tag?: string
+  skip?: number
+  limit?: number
+}): Promise<EditingTemplate[]> => {
+  const response = await apiClient.get<ListTemplatesResponse>("/templates", {
+    params: {
+      skip: params?.skip ?? 0,
+      limit: params?.limit ?? 50,
+    },
+  })
+  let list = response.data.items
+  if (params?.category) list = list.filter((t) => t.category === params.category)
+  if (params?.tag) list = list.filter((t) => t.tags.includes(params.tag!))
+  return list
+}
+
+/** 获取模板详情 */
+export const getEditingTemplate = async (id: string): Promise<EditingTemplate> => {
+  const response = await apiClient.get<EditingTemplate>(`/templates/${id}`)
+  return response.data
+}
+
+/** 创建模板 */
+export const createEditingTemplate = async (
+  data: SaveTemplatePayload,
+): Promise<EditingTemplate> => {
+  const response = await apiClient.post<EditingTemplate>("/templates", data)
+  return response.data
+}
+
+/** 更新模板 */
+export const updateEditingTemplate = async (
+  id: string,
+  data: SaveTemplatePayload,
+): Promise<EditingTemplate> => {
+  const response = await apiClient.patch<EditingTemplate>(`/templates/${id}`, data)
+  return response.data
+}
+
+/** 删除模板 */
+export const deleteEditingTemplate = async (id: string): Promise<void> => {
+  await apiClient.delete(`/templates/${id}`)
+}
+
+/** 获取模板分类列表 */
+export const getTemplateCategories = async (): Promise<TemplateCategory[]> => {
+  const response = await apiClient.get<ListCategoriesResponse>("/templates/categories/list")
+  return response.data.items
+}
+
+/** 使用模板生成视频（调用 validate 端点） */
+export const generateFromTemplate = async (
+  templateId: string,
+  data: GenerateFromTemplatePayload,
+): Promise<GenerateFromTemplateResponse> => {
+  const response = await apiClient.post<GenerateFromTemplateResponse>(
+    `/templates/${templateId}/validate`,
+    data,
+  )
+  return response.data
+}

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

@@ -0,0 +1,138 @@
+/**
+ * 模板编辑器类型定义
+ */
+import type {
+  WatermarkConfig,
+  IntroOutroConfig,
+  PipConfig,
+  FilterConfig,
+  ChromaKeyConfig,
+  StickerConfig,
+  CoverConfig,
+} from "@/pages/editing-planner/types"
+
+/** 模板模式（后端枚举值） */
+export type TemplateMode = "pip" | "voice_over" | "one_take" | "voice_pip"
+
+/** 标题配置 */
+export interface TitleConfig {
+  ai_auto_select: boolean
+  content: string
+  font_preset: string
+  font_color: string
+  font_size: number
+  position: string
+}
+
+/** 字幕配置 */
+export interface SubtitleConfig {
+  enabled: boolean
+  position: string
+  font: string
+  color: string
+  size: number
+  animation: string
+}
+
+/** BGM 配置 */
+export interface BgmConfig {
+  enabled: boolean
+  music_id: string
+}
+
+/** 模板片段 */
+export interface TemplateSegment {
+  id?: string
+  segment_order: number
+  duration_min: number
+  duration_max: number
+  material_type: string | null
+}
+
+/** 剪辑模板 */
+export interface EditingTemplate {
+  id: string
+  name: string
+  mode: TemplateMode
+  category: string
+  tags: string[]
+  title_config: TitleConfig
+  subtitle_config: SubtitleConfig
+  bgm_config: BgmConfig
+  estimated_duration: number
+  segments: TemplateSegment[]
+  watermark_config?: WatermarkConfig
+  intro_outro_config?: IntroOutroConfig
+  pip_config?: PipConfig
+  filter_config?: FilterConfig
+  green_screen_config?: ChromaKeyConfig
+  sticker_config?: StickerConfig
+  cover_config?: CoverConfig
+  is_active?: boolean
+  created_at: string
+  updated_at: string
+}
+
+/** 模板分类 */
+export interface TemplateCategory {
+  id: string
+  name: string
+  created_at?: string
+}
+
+/** 创建/更新模板请求体 */
+export interface SaveTemplatePayload {
+  name: string
+  mode: TemplateMode
+  category: string
+  tags: string[]
+  title_config: TitleConfig
+  subtitle_config: SubtitleConfig
+  bgm_config: BgmConfig
+  estimated_duration: number
+  segments: Omit<TemplateSegment, "id">[]
+  watermark_config?: WatermarkConfig
+  intro_outro_config?: IntroOutroConfig
+  pip_config?: PipConfig
+  filter_config?: FilterConfig
+  green_screen_config?: ChromaKeyConfig
+  sticker_config?: StickerConfig
+  cover_config?: CoverConfig
+}
+
+/** 使用模板生成请求体 */
+export interface GenerateFromTemplatePayload {
+  voiceover_duration: number
+}
+
+/** 验证警告详情 */
+export interface ValidationWarningDetails {
+  field?: string
+  expected?: string | number
+  actual?: string | number
+  suggested?: string | number
+}
+
+/** 验证警告 */
+export interface ValidateWarning {
+  code: string
+  message: string
+  details?: ValidationWarningDetails
+}
+
+/** 使用模板生成响应 */
+export interface GenerateFromTemplateResponse {
+  template: EditingTemplate
+  warnings: ValidateWarning[]
+}
+
+/** 列表响应（带分页） */
+export interface ListTemplatesResponse {
+  items: EditingTemplate[]
+  total: number
+}
+
+/** 分类列表响应 */
+export interface ListCategoriesResponse {
+  items: TemplateCategory[]
+}

apps/web/src/api/editingPlanner.ts

@@ -1,243 +0,0 @@
-/**
- * 模板编辑器 API
- * 对接后端 /api/v1/templates 路由
- */
-import apiClient from "./client"
-import type {
-  WatermarkConfig,
-  IntroOutroConfig,
-  PipConfig,
-  FilterConfig,
-  ChromaKeyConfig,
-  StickerConfig,
-  CoverConfig,
-} from "@/pages/editing-planner/types"
-
-/* ──────────── 类型定义 ──────────── */
-
-/** 模板模式（后端枚举值） */
-export type TemplateMode = "pip" | "voice_over" | "one_take" | "voice_pip"
-
-/** 模式显示名称映射 */
-export const MODE_LABELS: Record<TemplateMode, string> = {
-  pip: "混剪",
-  voice_over: "人物口播",
-  one_take: "一镜到底",
-  voice_pip: "口播+混剪",
-}
-
-/** 模式颜色映射 */
-export const MODE_COLORS: Record<TemplateMode, string> = {
-  pip: "blue",
-  voice_over: "green",
-  one_take: "orange",
-  voice_pip: "purple",
-}
-
-/** 标题配置 */
-export interface TitleConfig {
-  ai_auto_select: boolean
-  content: string
-  font_preset: string
-  font_color: string
-  font_size: number
-  position: string
-}
-
-/** 字幕配置 */
-export interface SubtitleConfig {
-  enabled: boolean
-  position: string
-  font: string
-  color: string
-  size: number
-  animation: string
-}
-
-/** BGM 配置 */
-export interface BgmConfig {
-  enabled: boolean
-  music_id: string
-}
-
-/** 模板片段 */
-export interface TemplateSegment {
-  id?: string
-  segment_order: number
-  duration_min: number
-  duration_max: number
-  material_type: string | null
-}
-
-/** 剪辑模板 */
-export interface EditingTemplate {
-  id: string
-  name: string
-  mode: TemplateMode
-  category: string
-  tags: string[]
-  title_config: TitleConfig
-  subtitle_config: SubtitleConfig
-  bgm_config: BgmConfig
-  estimated_duration: number
-  segments: TemplateSegment[]
-  /** 水印配置（后端就绪后启用） */
-  watermark_config?: WatermarkConfig
-  /** 片头片尾配置（后端就绪后启用） */
-  intro_outro_config?: IntroOutroConfig
-  /** 混剪配置 */
-  pip_config?: PipConfig
-  /** 滤镜调色配置 */
-  filter_config?: FilterConfig
-  /** 绿幕抠像配置 */
-  green_screen_config?: ChromaKeyConfig
-  /** 贴纸配置 */
-  sticker_config?: StickerConfig
-  /** 封面配置 */
-  cover_config?: CoverConfig
-  is_active?: boolean
-  created_at: string
-  updated_at: string
-}
-
-/** 模板分类 */
-export interface TemplateCategory {
-  id: string
-  name: string
-  created_at?: string
-}
-
-/** 创建/更新模板请求体 */
-export interface SaveTemplatePayload {
-  name: string
-  mode: TemplateMode
-  category: string
-  tags: string[]
-  title_config: TitleConfig
-  subtitle_config: SubtitleConfig
-  bgm_config: BgmConfig
-  estimated_duration: number
-  segments: Omit<TemplateSegment, "id">[]
-  /** 水印配置（后端就绪后启用） */
-  watermark_config?: WatermarkConfig
-  /** 片头片尾配置（后端就绪后启用） */
-  intro_outro_config?: IntroOutroConfig
-  /** 混剪配置 */
-  pip_config?: PipConfig
-  /** 滤镜调色配置 */
-  filter_config?: FilterConfig
-  /** 绿幕抠像配置 */
-  green_screen_config?: ChromaKeyConfig
-  /** 贴纸配置 */
-  sticker_config?: StickerConfig
-  /** 封面配置 */
-  cover_config?: CoverConfig
-}
-
-/** 使用模板生成请求体 */
-export interface GenerateFromTemplatePayload {
-  voiceover_duration: number
-}
-
-/** 验证警告详情 */
-export interface ValidationWarningDetails {
-  /** 相关字段名 */
-  field?: string
-  /** 期望值 */
-  expected?: string | number
-  /** 实际值 */
-  actual?: string | number
-  /** 建议值 */
-  suggested?: string | number
-}
-
-/** 验证/生成响应 */
-export interface ValidateWarning {
-  code: string
-  message: string
-  details?: ValidationWarningDetails
-}
-
-/** 使用模板生成响应 */
-export interface GenerateFromTemplateResponse {
-  template: EditingTemplate
-  warnings: ValidateWarning[]
-}
-
-/** 列表响应（带分页） */
-export interface ListTemplatesResponse {
-  items: EditingTemplate[]
-  total: number
-}
-
-/** 分类列表响应 */
-export interface ListCategoriesResponse {
-  items: TemplateCategory[]
-}
-
-// ============ API 函数 ============
-
-/** 获取模板列表 */
-export const getEditingTemplates = async (params?: {
-  category?: string
-  tag?: string
-  skip?: number
-  limit?: number
-}): Promise<EditingTemplate[]> => {
-  const response = await apiClient.get<ListTemplatesResponse>("/templates", {
-    params: {
-      skip: params?.skip ?? 0,
-      limit: params?.limit ?? 50,
-    },
-  })
-  let list = response.data.items
-  if (params?.category) list = list.filter((t) => t.category === params.category)
-  if (params?.tag) list = list.filter((t) => t.tags.includes(params.tag!))
-  return list
-}
-
-/** 获取模板详情 */
-export const getEditingTemplate = async (id: string): Promise<EditingTemplate> => {
-  const response = await apiClient.get<EditingTemplate>(`/templates/${id}`)
-  return response.data
-}
-
-/** 创建模板 */
-export const createEditingTemplate = async (
-  data: SaveTemplatePayload,
-): Promise<EditingTemplate> => {
-  const response = await apiClient.post<EditingTemplate>("/templates", data)
-  return response.data
-}
-
-/** 更新模板 */
-export const updateEditingTemplate = async (
-  id: string,
-  data: SaveTemplatePayload,
-): Promise<EditingTemplate> => {
-  const response = await apiClient.patch<EditingTemplate>(`/templates/${id}`, data)
-  return response.data
-}
-
-/** 删除模板 */
-export const deleteEditingTemplate = async (id: string): Promise<void> => {
-  await apiClient.delete(`/templates/${id}`)
-}
-
-/** 获取模板分类列表 */
-export const getTemplateCategories = async (): Promise<TemplateCategory[]> => {
-  const response = await apiClient.get<ListCategoriesResponse>("/templates/categories/list")
-  return response.data.items
-}
-
-/** 使用模板生成视频（调用 validate 端点） */
-export const generateFromTemplate = async (
-  templateId: string,
-  data: GenerateFromTemplatePayload,
-): Promise<GenerateFromTemplateResponse> => {
-  const response = await apiClient.post<GenerateFromTemplateResponse>(
-    `/templates/${templateId}/validate`,
-    data,
-  )
-  return response.data
-}

apps/web/src/api/products.ts

@@ -1,174 +0,0 @@
-/**
- * 成品 / 视频相关 API
- * 后端实际接口：/videos
- */
-import apiClient from "./client"
-
-/** 复核状态 */
-export type ReviewStatus = "pending_review" | "approved" | "rejected"
-
-/** 成品条目 */
-export interface ProductItem {
-  id: string
-  title: string
-  video_url?: string
-  thumbnail_url?: string
-  duration_seconds?: number
-  file_size?: number
-  resolution?: string
-  status: "processing" | "completed" | "failed"
-  /** 复核状态 */
-  review_status?: ReviewStatus
-  /** 所属项目 ID */
-  project_id?: string
-  /** 所属项目名称 */
-  project_name?: string
-  /** 查重率（百分比） */
-  duplicate_rate?: number
-  created_at?: string
-  updated_at?: string
-}
-
-/** 列表查询参数 */
-export interface ProductListParams {
-  page?: number
-  page_size?: number
-  project_id?: string
-  review_status?: ReviewStatus | "all"
-}
-
-/** 分页响应 */
-export interface ProductListResponse {
-  items: ProductItem[]
-  total: number
-  page: number
-  page_size: number
-}
-
-/** 批量下载任务状态 */
-export interface BatchDownloadStatus {
-  job_id: string
-  status: "processing" | "completed" | "failed"
-  /** 完成后返回的下载 URL */
-  download_url?: string
-  /** 进度百分比 */
-  progress?: number
-}
-
-/** 后端 /videos 接口返回的原始视频条目 */
-interface VideoItem {
-  id: string
-  project_id: string
-  generation_task_id: string
-  name: string
-  file_url: string
-  file_size: number
-  duration: number
-  thumbnail_url: string | null
-  width: number
-  height: number
-  fps: number
-  status: string
-  review_status: ReviewStatus
-  generation_params: Record<string, unknown>
-  download_url: string
-  generated_at: string
-}
-
-/**
- * 将后端 VideoItem 映射为 ProductItem 格式
- */
-function mapVideoToProductItem(video: VideoItem): ProductItem {
-  return {
-    id: video.id,
-    title: video.name || "未命名视频",
-    // 优先用 download_url（带签名）播放，file_url 无签名无法访问
-    video_url: video.download_url || video.file_url,
-    thumbnail_url: video.thumbnail_url || undefined,
-    duration_seconds: video.duration,
-    file_size: video.file_size,
-    resolution: video.width && video.height ? `${video.width}x${video.height}` : undefined,
-    status:
-      video.status === "completed"
-        ? "completed"
-        : video.status === "failed"
-          ? "failed"
-          : "processing",
-    review_status: video.review_status,
-    project_id: video.project_id,
-    // 后端 /videos 接口暂无 project_name 字段
-    project_name: undefined,
-    // 后端字段名为 generated_at，映射为 created_at 供前端统一使用
-    created_at: video.generated_at,
-    updated_at: video.generated_at,
-    // 后端 /videos 接口暂无 duplicate_rate 字段
-    duplicate_rate: undefined,
-  }
-}
-
-/** 获取成品列表（支持分页和筛选） */
-export const getProducts = async (params?: ProductListParams): Promise<ProductItem[]> => {
-  const response = await apiClient.get("/videos", { params })
-  const data = response.data
-  const videos: VideoItem[] = Array.isArray(data?.items)
-    ? data.items
-    : Array.isArray(data)
-      ? data
-      : []
-  return videos.map(mapVideoToProductItem)
-}
-
-/** 获取单个成品详情 */
-export const getProduct = async (productId: string): Promise<ProductItem> => {
-  const response = await apiClient.get(`/videos/${productId}`)
-  return mapVideoToProductItem(response.data as VideoItem)
-}
-
-/**
- * 删除成品
- * 注意：后端暂未实现 /videos DELETE 接口，调用会返回 405
- * 待后端实现后自动生效
- */
-export const deleteProduct = async (productId: string): Promise<void> => {
-  await apiClient.delete(`/videos/${productId}`)
-}
-
-/**
- * 获取成品下载链接
- * 直接使用列表返回的 download_url（带OSS签名）
- */
-export const getProductDownloadUrl = async (
-  productId: string,
-): Promise<{ url: string; expires_at: string }> => {
-  // 优先从列表缓存取；如果没有则调详情接口
-  const product = await getProduct(productId)
-  if (!product.video_url) throw new Error("下载链接不可用")
-  return { url: product.video_url, expires_at: "" }
-}
-
-/** 更新复核状态 — TODO: 后端暂无对应端点，暂存本地状态 */
-export const updateReviewStatus = async (
-  productId: string,
-  status: ReviewStatus,
-): Promise<ProductItem> => {
-  // 后端暂无 /videos/{id}/review 端点
-  // 暂时返回当前状态，后续可扩展
-  const product = await getProduct(productId)
-  return { ...product, review_status: status }
-}
-
-/** 发起批量下载 — TODO: 后端暂无对应端点 */
-export const batchDownload = async (videoIds: string[]): Promise<{ job_id: string }> => {
-  // 后端暂无 /videos/batch-download 端点
-  // 暂时返回模拟 job_id，后续可扩展
-  console.warn("[batchDownload] 后端暂无批量下载端点", videoIds)
-  return { job_id: `mock-${Date.now()}` }
-}
-
-/** 查询批量下载状态 — TODO: 后端暂无对应端点 */
-export const getBatchDownloadStatus = async (jobId: string): Promise<BatchDownloadStatus> => {
-  // 后端暂无 /videos/batch-download/{jobId} 端点
-  // 暂时返回模拟状态，后续可扩展
-  console.warn("[getBatchDownloadStatus] 后端暂无批量下载状态端点", jobId)
-  return { job_id: jobId, status: "processing", progress: 0 }
-}

apps/web/src/api/products/index.ts

@@ -0,0 +1,28 @@
+/**
+ * 成品 / 视频相关 API — 目录化入口
+ * 保持与原 products.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type {
+  ReviewStatus,
+  ProductItem,
+  ProductListParams,
+  ProductListResponse,
+  BatchDownloadStatus,
+  VideoItem,
+} from "./types"
+
+// 工具函数
+export { mapVideoToProductItem } from "./utils"
+
+// API 函数
+export {
+  getProducts,
+  getProduct,
+  deleteProduct,
+  getProductDownloadUrl,
+  updateReviewStatus,
+  batchDownload,
+  getBatchDownloadStatus,
+} from "./products"

apps/web/src/api/products/products.ts

@@ -0,0 +1,80 @@
+/**
+ * 成品 / 视频相关 API 函数
+ * 后端实际接口：/videos
+ */
+import apiClient from "../client"
+import type {
+  BatchDownloadStatus,
+  ProductItem,
+  ProductListParams,
+  VideoItem,
+  ReviewStatus,
+} from "./types"
+import { mapVideoToProductItem } from "./utils"
+
+/** 获取成品列表（支持分页和筛选） */
+export const getProducts = async (params?: ProductListParams): Promise<ProductItem[]> => {
+  const response = await apiClient.get("/videos", { params })
+  const data = response.data
+  const videos: VideoItem[] = Array.isArray(data?.items)
+    ? data.items
+    : Array.isArray(data)
+      ? data
+      : []
+  return videos.map(mapVideoToProductItem)
+}
+
+/** 获取单个成品详情 */
+export const getProduct = async (productId: string): Promise<ProductItem> => {
+  const response = await apiClient.get(`/videos/${productId}`)
+  return mapVideoToProductItem(response.data as VideoItem)
+}
+
+/**
+ * 删除成品
+ * 注意：后端暂未实现 /videos DELETE 接口，调用会返回 405
+ * 待后端实现后自动生效
+ */
+export const deleteProduct = async (productId: string): Promise<void> => {
+  await apiClient.delete(`/videos/${productId}`)
+}
+
+/**
+ * 获取成品下载链接
+ * 直接使用列表返回的 download_url（带OSS签名）
+ */
+export const getProductDownloadUrl = async (
+  productId: string,
+): Promise<{ url: string; expires_at: string }> => {
+  // 优先从列表缓存取；如果没有则调详情接口
+  const product = await getProduct(productId)
+  if (!product.video_url) throw new Error("下载链接不可用")
+  return { url: product.video_url, expires_at: "" }
+}
+
+/** 更新复核状态 — TODO: 后端暂无对应端点，暂存本地状态 */
+export const updateReviewStatus = async (
+  productId: string,
+  status: ReviewStatus,
+): Promise<ProductItem> => {
+  // 后端暂无 /videos/{id}/review 端点
+  // 暂时返回当前状态，后续可扩展
+  const product = await getProduct(productId)
+  return { ...product, review_status: status }
+}
+
+/** 发起批量下载 — TODO: 后端暂无对应端点 */
+export const batchDownload = async (videoIds: string[]): Promise<{ job_id: string }> => {
+  // 后端暂无 /videos/batch-download 端点
+  // 暂时返回模拟 job_id，后续可扩展
+  console.warn("[batchDownload] 后端暂无批量下载端点", videoIds)
+  return { job_id: `mock-${Date.now()}` }
+}
+
+/** 查询批量下载状态 — TODO: 后端暂无对应端点 */
+export const getBatchDownloadStatus = async (jobId: string): Promise<BatchDownloadStatus> => {
+  // 后端暂无 /videos/batch-download/{jobId} 端点
+  // 暂时返回模拟状态，后续可扩展
+  console.warn("[getBatchDownloadStatus] 后端暂无批量下载状态端点", jobId)
+  return { job_id: jobId, status: "processing", progress: 0 }
+}

apps/web/src/api/products/types.ts

@@ -0,0 +1,74 @@
+/**
+ * 成品 / 视频相关类型定义
+ */
+
+/** 复核状态 */
+export type ReviewStatus = "pending_review" | "approved" | "rejected"
+
+/** 成品条目 */
+export interface ProductItem {
+  id: string
+  title: string
+  video_url?: string
+  thumbnail_url?: string
+  duration_seconds?: number
+  file_size?: number
+  resolution?: string
+  status: "processing" | "completed" | "failed"
+  /** 复核状态 */
+  review_status?: ReviewStatus
+  /** 所属项目 ID */
+  project_id?: string
+  /** 所属项目名称 */
+  project_name?: string
+  /** 查重率（百分比） */
+  duplicate_rate?: number
+  created_at?: string
+  updated_at?: string
+}
+
+/** 列表查询参数 */
+export interface ProductListParams {
+  page?: number
+  page_size?: number
+  project_id?: string
+  review_status?: ReviewStatus | "all"
+}
+
+/** 分页响应 */
+export interface ProductListResponse {
+  items: ProductItem[]
+  total: number
+  page: number
+  page_size: number
+}
+
+/** 批量下载任务状态 */
+export interface BatchDownloadStatus {
+  job_id: string
+  status: "processing" | "completed" | "failed"
+  /** 完成后返回的下载 URL */
+  download_url?: string
+  /** 进度百分比 */
+  progress?: number
+}
+
+/** 后端 /videos 接口返回的原始视频条目 */
+export interface VideoItem {
+  id: string
+  project_id: string
+  generation_task_id: string
+  name: string
+  file_url: string
+  file_size: number
+  duration: number
+  thumbnail_url: string | null
+  width: number
+  height: number
+  fps: number
+  status: string
+  review_status: ReviewStatus
+  generation_params: Record<string, unknown>
+  download_url: string
+  generated_at: string
+}

apps/web/src/api/products/utils.ts

@@ -0,0 +1,35 @@
+/**
+ * 成品数据转换工具函数
+ */
+import type { ProductItem, VideoItem } from "./types"
+
+/**
+ * 将后端 VideoItem 映射为 ProductItem 格式
+ */
+export function mapVideoToProductItem(video: VideoItem): ProductItem {
+  return {
+    id: video.id,
+    title: video.name || "未命名视频",
+    // 优先用 download_url（带签名）播放，file_url 无签名无法访问
+    video_url: video.download_url || video.file_url,
+    thumbnail_url: video.thumbnail_url || undefined,
+    duration_seconds: video.duration,
+    file_size: video.file_size,
+    resolution: video.width && video.height ? `${video.width}x${video.height}` : undefined,
+    status:
+      video.status === "completed"
+        ? "completed"
+        : video.status === "failed"
+          ? "failed"
+          : "processing",
+    review_status: video.review_status,
+    project_id: video.project_id,
+    // 后端 /videos 接口暂无 project_name 字段
+    project_name: undefined,
+    // 后端字段名为 generated_at，映射为 created_at 供前端统一使用
+    created_at: video.generated_at,
+    updated_at: video.generated_at,
+    // 后端 /videos 接口暂无 duplicate_rate 字段
+    duplicate_rate: undefined,
+  }
+}

apps/web/src/api/projects/index.ts

@@ -0,0 +1,13 @@
+/**
+ * 项目 API — 目录化入口
+ * 保持与原 projects.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type { ProjectItem, BackendProjectResponse, BackendListProjectsResponse } from "./types"
+
+// 工具函数
+export { toProjectItem } from "./utils"
+
+// API 函数
+export { getProjects, createProject, getOrCreateDefaultProject } from "./projects"

apps/web/src/api/projects/projects.ts

@@ -1,32 +1,10 @@
 /**
- * 项目相关 API
+ * 项目相关 API 函数
  * 素材库需要 project_id，前端自动管理默认项目
  */
-import apiClient from "./client"
-
-export interface ProjectItem {
-  id: string
-  name: string
-  description: string
-}
-
-/** 后端 ProjectResponse 只返回 id, name, description */
-interface BackendProjectResponse {
-  id: string
-  name: string
-  description: string
-}
-
-/** 后端 ListProjectsResponse 返回 { items: [...] } */
-interface BackendListProjectsResponse {
-  items: BackendProjectResponse[]
-}
-
-const toProjectItem = (item: BackendProjectResponse): ProjectItem => ({
-  id: item.id,
-  name: item.name,
-  description: item.description,
-})
+import apiClient from "../client"
+import type { BackendListProjectsResponse, BackendProjectResponse, ProjectItem } from "./types"
+import { toProjectItem } from "./utils"
 
 /** 获取当前用户的项目列表 */
 export const getProjects = async (): Promise<ProjectItem[]> => {

apps/web/src/api/projects/types.ts

@@ -0,0 +1,21 @@
+/**
+ * 项目相关类型定义
+ */
+
+export interface ProjectItem {
+  id: string
+  name: string
+  description: string
+}
+
+/** 后端 ProjectResponse 只返回 id, name, description */
+export interface BackendProjectResponse {
+  id: string
+  name: string
+  description: string
+}
+
+/** 后端 ListProjectsResponse 返回 { items: [...] } */
+export interface BackendListProjectsResponse {
+  items: BackendProjectResponse[]
+}

apps/web/src/api/projects/utils.ts

@@ -0,0 +1,10 @@
+/**
+ * 项目相关工具函数
+ */
+import type { BackendProjectResponse, ProjectItem } from "./types"
+
+export const toProjectItem = (item: BackendProjectResponse): ProjectItem => ({
+  id: item.id,
+  name: item.name,
+  description: item.description,
+})

apps/web/src/api/subscription/index.ts

@@ -0,0 +1,26 @@
+/**
+ * 订阅 API — 目录化入口
+ * 保持与原 subscription.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type {
+  PlanType,
+  SubscriptionStatus,
+  BillingStatus,
+  BillingCycle,
+  Plan,
+  SubscriptionInfo,
+  BillingRecord,
+  ChangePlanRequest,
+  ChangePlanResponse,
+} from "./types"
+
+// API 函数
+export {
+  getCurrentSubscription,
+  getBillingRecords,
+  changePlan,
+  cancelSubscription,
+  toggleAutoRenew,
+} from "./subscription"

apps/web/src/api/subscription/subscription.ts

@@ -0,0 +1,47 @@
+/**
+ * 订阅相关 API 函数
+ */
+import apiClient from "../client"
+import type {
+  BillingRecord,
+  ChangePlanRequest,
+  ChangePlanResponse,
+  SubscriptionInfo,
+} from "./types"
+
+/** 获取当前订阅信息 */
+export const getCurrentSubscription = async (): Promise<SubscriptionInfo> => {
+  const response = await apiClient.get("/subscription/current")
+  return response.data
+}
+
+/** 获取账单记录列表 */
+export const getBillingRecords = async (): Promise<BillingRecord[]> => {
+  const response = await apiClient.get("/subscription/billing-records")
+  return response.data
+}
+
+/** 升级/降级套餐 */
+export const changePlan = async (request: ChangePlanRequest): Promise<ChangePlanResponse> => {
+  const response = await apiClient.post("/subscription/change-plan", request)
+  return response.data
+}
+
+/** 取消订阅 */
+export const cancelSubscription = async (): Promise<{
+  success: boolean
+  message: string
+}> => {
+  const response = await apiClient.post("/subscription/cancel")
+  return response.data
+}
+
+/** 切换自动续费 */
+export const toggleAutoRenew = async (
+  enabled: boolean,
+): Promise<{ success: boolean; message: string }> => {
+  const response = await apiClient.post("/subscription/toggle-auto-renew", {
+    enabled,
+  })
+  return response.data
+}

apps/web/src/api/subscription/types.ts

@@ -1,8 +1,6 @@
 /**
- * 订阅 API 模块
- * 对接后端订阅管理接口
+ * 订阅相关类型定义
  */
-import apiClient from "./client"
 
 /** 套餐类型 */
 export type PlanType = "free" | "standard" | "pro" | "enterprise"
@@ -65,42 +63,3 @@ export interface ChangePlanResponse {
   message: string
   new_subscription?: SubscriptionInfo
 }
-
-// ============ API 函数 ============
-
-/** 获取当前订阅信息 */
-export const getCurrentSubscription = async (): Promise<SubscriptionInfo> => {
-  const response = await apiClient.get("/subscription/current")
-  return response.data
-}
-
-/** 获取账单记录列表 */
-export const getBillingRecords = async (): Promise<BillingRecord[]> => {
-  const response = await apiClient.get("/subscription/billing-records")
-  return response.data
-}
-
-/** 升级/降级套餐 */
-export const changePlan = async (request: ChangePlanRequest): Promise<ChangePlanResponse> => {
-  const response = await apiClient.post("/subscription/change-plan", request)
-  return response.data
-}
-
-/** 取消订阅 */
-export const cancelSubscription = async (): Promise<{
-  success: boolean
-  message: string
-}> => {
-  const response = await apiClient.post("/subscription/cancel")
-  return response.data
-}
-
-/** 切换自动续费 */
-export const toggleAutoRenew = async (
-  enabled: boolean,
-): Promise<{ success: boolean; message: string }> => {
-  const response = await apiClient.post("/subscription/toggle-auto-renew", {
-    enabled,
-  })
-  return response.data
-}

apps/web/src/api/tags/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 标签 API — 目录化入口
+ * 保持与原 tags.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type { TagItem } from "./types"
+
+// API 函数
+export { getTags, createTag, deleteTag, tagAsset, untagAsset } from "./tags"

apps/web/src/api/tags/tags.ts

@@ -1,15 +1,9 @@
 /**
- * 标签 CRUD API
+ * 标签 CRUD API 函数
  * P3 标签体系：对接后端标签表
  */
-import apiClient from "./client"
-
-export interface TagItem {
-  id: string
-  name: string
-  created_at?: string
-  usage_count?: number
-}
+import apiClient from "../client"
+import type { TagItem } from "./types"
 
 /** 获取当前用户所有标签 */
 export const getTags = async (): Promise<TagItem[]> => {

apps/web/src/api/tags/types.ts

@@ -0,0 +1,10 @@
+/**
+ * 标签相关类型定义
+ */
+
+export interface TagItem {
+  id: string
+  name: string
+  created_at?: string
+  usage_count?: number
+}

apps/web/src/api/tasks/index.ts

@@ -0,0 +1,19 @@
+/**
+ * 任务相关 API — 目录化入口
+ * 保持与原 tasks.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type {
+  TaskStatus,
+  TaskType,
+  TaskErrorInfo,
+  TaskItem,
+  TaskListParams,
+  TaskListResponse,
+  CreateGenerationTaskRequest,
+  CreateGenerationTaskResponse,
+} from "./types"
+
+// API 函数
+export { createGenerationTask, getTasks, getUserTasks, getTask, retryTask } from "./tasks"

apps/web/src/api/tasks/tasks.ts

@@ -0,0 +1,46 @@
+/**
+ * 任务相关 API 函数
+ * 对接后端任务中心 API
+ */
+import apiClient from "../client"
+import type {
+  CreateGenerationTaskRequest,
+  CreateGenerationTaskResponse,
+  TaskItem,
+  TaskListParams,
+  TaskListResponse,
+} from "./types"
+
+/** 创建生成任务（智能剪辑） */
+export const createGenerationTask = async (
+  params: CreateGenerationTaskRequest,
+): Promise<CreateGenerationTaskResponse> => {
+  const { data } = await apiClient.post<CreateGenerationTaskResponse>("/generation/tasks", params)
+  return data
+}
+
+/** 获取任务列表（支持分页和筛选） */
+export const getTasks = async (params?: TaskListParams): Promise<TaskListResponse> => {
+  const { data } = await apiClient.get<TaskListResponse>("/tasks", {
+    params,
+  })
+  return data
+}
+
+/** 获取当前用户的所有任务（兼容旧接口，跨 project） */
+export const getUserTasks = async (): Promise<TaskItem[]> => {
+  const { data } = await apiClient.get("/tasks")
+  return data.items || data || []
+}
+
+/** 获取单个任务详情（含 error_info） */
+export const getTask = async (taskId: string): Promise<TaskItem> => {
+  const { data } = await apiClient.get(`/tasks/${taskId}`)
+  return data
+}
+
+/** 重试失败的任务 */
+export const retryTask = async (taskId: string): Promise<TaskItem> => {
+  const { data } = await apiClient.post(`/tasks/${taskId}/retry`)
+  return data
+}

apps/web/src/api/tasks/types.ts

@@ -1,14 +1,6 @@
 /**
- * 任务相关 API
- * 对接后端任务中心 API：
- * - POST /api/v1/generation/tasks — 创建生成任务
- * - GET  /api/v1/tasks              — 用户级任务列表（支持分页/筛选）
- * - GET  /api/v1/tasks/{task_id}    — 任务详情（含 error_info）
- * - POST /api/v1/tasks/{task_id}/retry — 重试失败任务
+ * 任务相关类型定义
  */
-import apiClient from "./client"
-
-/* ──────────── 类型定义 ──────────── */
 
 /** 任务状态 */
 export type TaskStatus = "pending" | "waiting" | "running" | "completed" | "failed" | "cancelled"
@@ -85,39 +77,3 @@ export interface CreateGenerationTaskResponse {
   result_count: number
   error_message: string
 }
-
-/* ──────────── API 函数 ──────────── */
-
-/** 创建生成任务（智能剪辑） */
-export const createGenerationTask = async (
-  params: CreateGenerationTaskRequest,
-): Promise<CreateGenerationTaskResponse> => {
-  const { data } = await apiClient.post<CreateGenerationTaskResponse>("/generation/tasks", params)
-  return data
-}
-
-/** 获取任务列表（支持分页和筛选） */
-export const getTasks = async (params?: TaskListParams): Promise<TaskListResponse> => {
-  const { data } = await apiClient.get<TaskListResponse>("/tasks", {
-    params,
-  })
-  return data
-}
-
-/** 获取当前用户的所有任务（兼容旧接口，跨 project） */
-export const getUserTasks = async (): Promise<TaskItem[]> => {
-  const { data } = await apiClient.get("/tasks")
-  return data.items || data || []
-}
-
-/** 获取单个任务详情（含 error_info） */
-export const getTask = async (taskId: string): Promise<TaskItem> => {
-  const { data } = await apiClient.get(`/tasks/${taskId}`)
-  return data
-}
-
-/** 重试失败的任务 */
-export const retryTask = async (taskId: string): Promise<TaskItem> => {
-  const { data } = await apiClient.post(`/tasks/${taskId}/retry`)
-  return data
-}

apps/web/src/api/template-editor/aiFeatures.ts

@@ -0,0 +1,28 @@
+/**
+ * AI 推荐 + 封面生成 API
+ */
+import apiClient from "../client"
+import type {
+  AIRecommendRequest,
+  AIRecommendResponse,
+  GenerateCoverRequest,
+  GenerateCoverResponse,
+} from "./types"
+
+/** AI 推荐片段方案 */
+export async function aiRecommendClips(
+  templateId: string,
+  data: AIRecommendRequest,
+): Promise<AIRecommendResponse> {
+  const response = await apiClient.post(`/templates/${templateId}/editor/ai-recommend`, data)
+  return response.data
+}
+
+/** AI 生成封面 */
+export async function generateCover(
+  templateId: string,
+  data: GenerateCoverRequest,
+): Promise<GenerateCoverResponse> {
+  const response = await apiClient.post(`/templates/${templateId}/editor/generate-cover`, data)
+  return response.data
+}

apps/web/src/api/template-editor/clips.ts

@@ -0,0 +1,99 @@
+/**
+ * 片段 CRUD + 批量操作 API
+ */
+import apiClient from "../client"
+import type {
+  EditPlanClip,
+  EditPlanClipListParams,
+  EditPlanClipListResponse,
+  CreateEditPlanClipRequest,
+  UpdateEditPlanClipRequest,
+  ClipReorderItem,
+  ClipReorderResponse,
+  ClipBatchDeleteResponse,
+  ClipsFromAssetsResponse,
+} from "./types"
+
+/** 获取片段列表 */
+export async function getEditPlanClips(
+  templateId: string,
+  params?: EditPlanClipListParams,
+): Promise<EditPlanClipListResponse> {
+  const response = await apiClient.get<EditPlanClipListResponse>(
+    `/templates/${templateId}/editor/clips`,
+    { params },
+  )
+  return response.data
+}
+
+/** 获取单个片段详情 */
+export async function getEditPlanClip(templateId: string, clipId: string): Promise<EditPlanClip> {
+  const response = await apiClient.get<EditPlanClip>(
+    `/templates/${templateId}/editor/clips/${clipId}`,
+  )
+  return response.data
+}
+
+/** 创建片段 */
+export async function createEditPlanClip(
+  templateId: string,
+  data: CreateEditPlanClipRequest,
+): Promise<EditPlanClip> {
+  const response = await apiClient.post<EditPlanClip>(`/templates/${templateId}/editor/clips`, data)
+  return response.data
+}
+
+/** 更新片段 */
+export async function updateEditPlanClip(
+  templateId: string,
+  clipId: string,
+  data: UpdateEditPlanClipRequest,
+): Promise<EditPlanClip> {
+  const response = await apiClient.put<EditPlanClip>(
+    `/templates/${templateId}/editor/clips/${clipId}`,
+    data,
+  )
+  return response.data
+}
+
+/** 删除片段 */
+export async function deleteEditPlanClip(templateId: string, clipId: string): Promise<void> {
+  await apiClient.delete(`/templates/${templateId}/editor/clips/${clipId}`)
+}
+
+/** 片段重排序（拖拽排序后一次性提交） */
+export async function reorderEditPlanClips(
+  templateId: string,
+  items: ClipReorderItem[],
+): Promise<ClipReorderResponse> {
+  const response = await apiClient.post<ClipReorderResponse>(
+    `/templates/${templateId}/editor/clips/reorder`,
+    { items },
+  )
+  return response.data
+}
+
+/** 批量删除片段 */
+export async function batchDeleteEditPlanClips(
+  templateId: string,
+  clipIds: string[],
+): Promise<ClipBatchDeleteResponse> {
+  const response = await apiClient.post<ClipBatchDeleteResponse>(
+    `/templates/${templateId}/editor/clips/batch-delete`,
+    { clip_ids: clipIds },
+  )
+  return response.data
+}
+
+/** 从素材批量创建片段（追加到时间线末尾） */
+export async function createClipsFromAssets(
+  templateId: string,
+  assetIds: string[],
+  clipType = "main",
+): Promise<ClipsFromAssetsResponse> {
+  const response = await apiClient.post<ClipsFromAssetsResponse>(
+    `/templates/${templateId}/editor/clips/from-assets`,
+    { asset_ids: assetIds, clip_type: clipType },
+  )
+  return response.data
+}

apps/web/src/api/template-editor/constants.ts

@@ -0,0 +1,66 @@
+/**
+ * 模板编辑器常量
+ */
+import type { TransitionEffect, EditPlanStatus } from "./types"
+
+/** 转场效果选项（14 种预设） */
+export const TRANSITION_OPTIONS: {
+  value: TransitionEffect["type"]
+  label: string
+  icon: string
+}[] = [
+  { value: "none", label: "无转场", icon: "⊘" },
+  { value: "cut", label: "硬切", icon: "✂" },
+  { value: "fade", label: "淡入淡出", icon: "◐" },
+  { value: "dissolve", label: "溶解", icon: "◈" },
+  { value: "zoom", label: "缩放", icon: "⊕" },
+  { value: "slide_left", label: "左滑", icon: "←" },
+  { value: "slide_right", label: "右滑", icon: "→" },
+  { value: "slide_up", label: "上滑", icon: "↑" },
+  { value: "slide_down", label: "下滑", icon: "↓" },
+  { value: "wipe_left", label: "左擦除", icon: "▸|" },
+  { value: "wipe_right", label: "右擦除", icon: "|◂" },
+  { value: "wipe_up", label: "上擦除", icon: "▴̄" },
+  { value: "wipe_down", label: "下擦除", icon: "▾̄" },
+  { value: "circlecrop", label: "圆形裁切", icon: "●" },
+  { value: "rectcrop", label: "矩形裁切", icon: "■" },
+]
+
+/** 素材类型标签 */
+export const MATERIAL_TYPE_LABELS: Record<string, string> = {
+  video: "视频",
+  image: "图片",
+  audio: "音频",
+  voiceover: "配音",
+}
+
+/** 素材类型图标 */
+export const MATERIAL_TYPE_ICONS: Record<string, string> = {
+  video: "🎬",
+  image: "🖼️",
+  audio: "🎵",
+  voiceover: "🎙️",
+}
+
+/** 计划状态标签 */
+export const PLAN_STATUS_LABELS: Record<EditPlanStatus, string> = {
+  draft: "草稿",
+  editing: "编辑中",
+  rendering: "渲染中",
+  completed: "已完成",
+  failed: "失败",
+  cancelled: "已取消",
+}
+
+/** 质量分筛选选项 */
+export const QUALITY_OPTIONS: {
+  value: string
+  label: string
+  min?: number
+  max?: number
+}[] = [
+  { value: "all", label: "全部质量" },
+  { value: "high", label: "高质量 (80-100)", min: 80, max: 100 },
+  { value: "medium", label: "中质量 (50-79)", min: 50, max: 79 },
+  { value: "low", label: "低质量 (0-49)", min: 0, max: 49 },
+]

apps/web/src/api/template-editor/editPlans.ts

@@ -0,0 +1,91 @@
+/**
+ * 模板草稿 CRUD + 生成相关 API
+ */
+import apiClient from "../client"
+import type {
+  EditPlan,
+  EditPlanListParams,
+  EditPlanListResponse,
+  CreateEditPlanRequest,
+  UpdateEditPlanRequest,
+  GenerateResponse,
+  GenerationStatusResponse,
+  EditPlanGeneration,
+  GeneratedVideo,
+  CopyEditPlanRequest,
+} from "./types"
+
+/** 获取模板草稿列表（支持分页和筛选） */
+export async function getEditPlans(params?: EditPlanListParams): Promise<EditPlanListResponse> {
+  const response = await apiClient.get<EditPlanListResponse>("/templates/drafts", {
+    params,
+  })
+  return response.data
+}
+
+/** 获取单个模板草稿 */
+export async function getEditPlan(templateId: string): Promise<EditPlan> {
+  const response = await apiClient.get(`/templates/${templateId}/editor`)
+  return response.data
+}
+
+/** 创建模板草稿 */
+export async function createEditPlan(data: CreateEditPlanRequest): Promise<EditPlan> {
+  const response = await apiClient.post("/templates/drafts", data)
+  return response.data
+}
+
+/** 更新模板草稿 */
+export async function updateEditPlan(
+  templateId: string,
+  data: UpdateEditPlanRequest,
+): Promise<EditPlan> {
+  const response = await apiClient.put(`/templates/${templateId}/editor`, data)
+  return response.data
+}
+
+/** 删除模板草稿 */
+export async function deleteEditPlan(templateId: string): Promise<void> {
+  await apiClient.delete(`/templates/${templateId}/editor`)
+}
+
+/** 触发生成 */
+export async function generateEditPlan(templateId: string): Promise<GenerateResponse> {
+  const response = await apiClient.post(`/templates/${templateId}/editor/generate`)
+  return response.data
+}
+
+/** 获取生成状态（轮询用） */
+export async function getGenerationStatus(templateId: string): Promise<GenerationStatusResponse> {
+  const response = await apiClient.get(`/templates/${templateId}/editor/generation-status`)
+  return response.data
+}
+
+/** 获取模板草稿关联的生成记录 */
+export async function getEditPlanGenerations(templateId: string): Promise<EditPlanGeneration[]> {
+  const response = await apiClient.get(`/templates/${templateId}/editor/generations`)
+  return response.data.items || []
+}
+
+/** 获取生成任务的视频结果列表 */
+export async function getGenerationTaskResults(taskId: string): Promise<GeneratedVideo[]> {
+  const response = await apiClient.get(`/generation/tasks/${taskId}/results`)
+  return response.data.items || response.data || []
+}
+
+/** 取消生成任务 */
+export async function cancelGeneration(templateId: string): Promise<void> {
+  await apiClient.post(`/templates/${templateId}/editor/cancel`)
+}
+
+/** 复制模板草稿（含所有片段配置） */
+export async function copyEditPlan(
+  templateId: string,
+  data?: CopyEditPlanRequest,
+): Promise<EditPlan> {
+  const response = await apiClient.post<EditPlan>(
+    `/templates/${templateId}/editor/copy`,
+    data || {},
+  )
+  return response.data
+}

apps/web/src/api/template-editor/index.ts

@@ -0,0 +1,88 @@
+/**
+ * 模板编辑器 API — 按模块拆分后的统一入口
+ * 保持与原 template-editor.ts 相同的导出结构，向后兼容
+ */
+
+// 类型
+export type {
+  EditPlanStatus,
+  TitleConfig,
+  SubtitleConfig,
+  BgmConfig,
+  SegmentTtsConfig,
+  SegmentTrimConfig,
+  SegmentTransitionConfig,
+  EditPlanSegment,
+  EditPlanConfig,
+  EditPlan,
+  CreateEditPlanRequest,
+  UpdateEditPlanRequest,
+  EditPlanListParams,
+  EditPlanListResponse,
+  GenerateResponse,
+  EditPlanGeneration,
+  ClipStatusItem,
+  GenerationStatusResponse,
+  GeneratedVideo,
+  AIRecommendRequest,
+  AIRecommendClipItem,
+  AIRecommendResponse,
+  GenerateCoverRequest,
+  GenerateCoverResponse,
+  CoverResult,
+  EditPlanClipStatus,
+  EditPlanClip,
+  CreateEditPlanClipRequest,
+  UpdateEditPlanClipRequest,
+  EditPlanClipListResponse,
+  EditPlanClipListParams,
+  ClipReorderItem,
+  ClipReorderResponse,
+  ClipBatchDeleteResponse,
+  ClipsFromAssetsResponse,
+  CopyEditPlanRequest,
+  TransitionEffect,
+  MediaAsset,
+} from "./types"
+
+// 常量
+export {
+  TRANSITION_OPTIONS,
+  MATERIAL_TYPE_LABELS,
+  MATERIAL_TYPE_ICONS,
+  PLAN_STATUS_LABELS,
+  QUALITY_OPTIONS,
+} from "./constants"
+
+// 模板草稿 CRUD + 生成
+export {
+  getEditPlans,
+  getEditPlan,
+  createEditPlan,
+  updateEditPlan,
+  deleteEditPlan,
+  generateEditPlan,
+  getGenerationStatus,
+  getEditPlanGenerations,
+  getGenerationTaskResults,
+  cancelGeneration,
+  copyEditPlan,
+} from "./editPlans"
+
+// 片段 CRUD + 批量操作
+export {
+  getEditPlanClips,
+  getEditPlanClip,
+  createEditPlanClip,
+  updateEditPlanClip,
+  deleteEditPlanClip,
+  reorderEditPlanClips,
+  batchDeleteEditPlanClips,
+  createClipsFromAssets,
+} from "./clips"
+
+// AI 推荐 + 封面生成
+export { aiRecommendClips, generateCover } from "./aiFeatures"
+
+// 素材库
+export { getMediaAssets, getMediaAsset } from "./mediaAssets"

apps/web/src/api/template-editor/mediaAssets.ts

@@ -0,0 +1,44 @@
+/**
+ * 素材库 API（对接 /assets 接口，映射为 MediaAsset 类型）
+ */
+import apiClient from "../client"
+import type { AssetItem } from "../assets"
+import type { MediaAsset } from "./types"
+
+const inferMediaType = (mimeType: string): "video" | "image" | "audio" => {
+  if (mimeType.startsWith("video/")) return "video"
+  if (mimeType.startsWith("image/")) return "image"
+  return "audio"
+}
+
+const mapAssetToMediaAsset = (asset: AssetItem): MediaAsset => {
+  const metaDuration =
+    typeof asset.metadata?.duration === "number" ? asset.metadata.duration : undefined
+  return {
+    id: asset.id,
+    name: asset.name,
+    type: inferMediaType(asset.mime_type || ""),
+    thumbnail_url: asset.thumbnail_url,
+    duration: asset.duration ?? metaDuration,
+    size: asset.file_size ?? undefined,
+    tags: [],
+    created_at: asset.created_at ?? "",
+    quality_score: asset.quality_score ?? undefined,
+    classification_status: asset.classification_status ?? undefined,
+  }
+}
+
+/** 获取素材库列表 */
+export async function getMediaAssets(libraryId?: string): Promise<MediaAsset[]> {
+  const response = await apiClient.get("/assets", {
+    params: libraryId ? { library_id: libraryId } : undefined,
+  })
+  const items: AssetItem[] = response.data.items || []
+  return items.map(mapAssetToMediaAsset)
+}
+
+/** 获取单个素材 */
+export async function getMediaAsset(id: string): Promise<MediaAsset> {
+  const response = await apiClient.get(`/assets/${id}`)
+  return mapAssetToMediaAsset(response.data)
+}

apps/web/src/api/template-editor/types.ts

@@ -0,0 +1,440 @@
+/**
+ * 模板编辑器 API 类型定义
+ * 字段名严格匹配后端 API 响应
+ */
+import type {
+  WatermarkConfig,
+  IntroOutroConfig,
+  PipConfig,
+  FilterConfig,
+  ChromaKeyConfig,
+  StickerConfig,
+  CoverConfig,
+} from "@/pages/editing-planner/types"
+
+/* ── 模板草稿状态 ── */
+
+export type EditPlanStatus =
+  "draft" | "editing" | "rendering" | "completed" | "failed" | "cancelled"
+
+/* ── 配置相关类型 ── */
+
+/** 标题配置（对齐后端 title_config） */
+export interface TitleConfig {
+  ai_auto_select: boolean
+  content: string
+  font_preset: string
+  font_color: string
+  font_size: number
+  position: string
+}
+
+/** 字幕配置 */
+export interface SubtitleConfig {
+  enabled: boolean
+  position: string
+  font: string
+  color: string
+  size: number
+  animation: string
+}
+
+/** BGM 配置 */
+export interface BgmConfig {
+  enabled: boolean
+  music_id: string
+}
+
+/** 片段 TTS 配置 */
+export interface SegmentTtsConfig {
+  mode: string
+  text: string
+  voice_id: string
+  speed: number
+  pitch: number
+  volume: number
+  subtitle_sync: boolean
+}
+
+/** 片段裁剪配置 */
+export interface SegmentTrimConfig {
+  start_time: number
+  end_time: number
+}
+
+/** 片段转场配置 */
+export interface SegmentTransitionConfig {
+  type: string
+  duration: number
+}
+
+/** 模板草稿中的单个片段 */
+export interface EditPlanSegment {
+  segment_order: number
+  duration_min: number
+  duration_max: number
+  material_type: string
+  transition?: SegmentTransitionConfig
+  playback_speed?: number
+  tts_config?: SegmentTtsConfig
+  trim_config?: SegmentTrimConfig
+}
+
+/** 模板草稿 config 完整类型 */
+export interface EditPlanConfig {
+  title_config?: TitleConfig
+  subtitle_config?: SubtitleConfig
+  bgm_config?: BgmConfig
+  estimated_duration?: number
+  segments?: EditPlanSegment[]
+  watermark_config?: WatermarkConfig
+  intro_outro_config?: IntroOutroConfig
+  pip_config?: PipConfig
+  filter_config?: FilterConfig
+  green_screen_config?: ChromaKeyConfig
+  sticker_config?: StickerConfig
+  cover_config?: CoverConfig
+  /** 前端扩展：关联的素材 ID 列表 */
+  asset_ids?: string[]
+  /** 配音 ID */
+  voice_id?: string
+  /** 克隆音色档案 ID */
+  voice_clone_profile_id?: string
+  /** 自定义配音音频 URL */
+  custom_audio_url?: string
+  /** 自定义配音文本 */
+  custom_text?: string
+  /** 视频比例 */
+  ratio?: string
+  /** 视频风格 */
+  style?: string
+  /** 目标时长（秒） */
+  duration?: number
+  /** 是否自动生成字幕 */
+  auto_subtitles?: boolean
+  /** 是否启用 BGM */
+  bgm?: boolean
+  /** 生成数量 */
+  generate_count?: number
+  /** 素材模式 */
+  material_mode?: string
+}
+
+/* ── 模板草稿主体 ── */
+
+/** 模板草稿（后端响应） */
+export interface EditPlan {
+  id: string
+  template_id: string
+  name: string
+  status: EditPlanStatus
+  total_duration: number
+  /** 生成视频数量 */
+  result_count: number
+  config: EditPlanConfig
+  created_at: string
+  updated_at: string
+}
+
+/** 创建模板草稿请求 */
+export interface CreateEditPlanRequest {
+  template_id: string
+  name: string
+  config?: EditPlanConfig
+  total_duration?: number
+  /** 来源模板草稿 ID */
+  source_edit_plan_id?: string
+}
+
+/** 更新模板草稿请求 */
+export interface UpdateEditPlanRequest {
+  name?: string
+  config?: EditPlanConfig
+  total_duration?: number
+  status?: EditPlanStatus
+}
+
+/** 模板草稿列表查询参数 */
+export interface EditPlanListParams {
+  page?: number
+  page_size?: number
+  template_id?: string
+  status?: string
+}
+
+/** 模板草稿列表分页响应 */
+export interface EditPlanListResponse {
+  items: EditPlan[]
+  total: number
+  page: number
+  page_size: number
+}
+
+/* ── 生成相关 ── */
+
+/** 生成响应 */
+export interface GenerateResponse {
+  plan_id: string
+  plan_status: EditPlanStatus
+  generation_task_id: string
+  clip_count: number
+}
+
+/** 模板草稿关联的生成记录 */
+export interface EditPlanGeneration {
+  id: string
+  source_edit_plan_id: string
+  template_id: string
+  asset_ids: string[]
+  status: EditPlanStatus
+  progress: number
+  result_count: number
+  error_message: string
+  error_info: Record<string, unknown>
+  logs: Array<Record<string, unknown>>
+  retry_count: number
+  created_at?: string
+  updated_at?: string
+}
+
+/** 片段生成状态 */
+export interface ClipStatusItem {
+  clip_id: string
+  clip_type: string
+  order: number
+  status: string
+  asset_id?: string
+  text_content?: string
+  duration?: number
+  error_message?: string
+}
+
+/** 生成状态轮询响应 */
+export interface GenerationStatusResponse {
+  plan_id: string
+  plan_status: EditPlanStatus
+  generation_task_id?: string
+  error_message?: string
+  clips: ClipStatusItem[]
+  error?: string
+  message?: string
+}
+
+/** 生成视频详情 */
+export interface GeneratedVideo {
+  id: string
+  project_id?: string
+  generation_task_id?: string
+  name: string
+  file_url: string
+  file_size?: number
+  duration?: number
+  thumbnail_url?: string
+  width?: number
+  height?: number
+  fps?: number
+  status: string
+  review_status?: string
+  download_url?: string
+  created_at?: string
+  updated_at?: string
+}
+
+/* ── AI 推荐 & 封面生成 ── */
+
+/** AI 推荐请求 */
+export interface AIRecommendRequest {
+  asset_ids: string[]
+  editing_mode?: string
+  target_duration?: number
+}
+
+/** AI 推荐单个片段 */
+export interface AIRecommendClipItem {
+  clip_type: string
+  order: number
+  text_content: string
+  duration: number
+  transition_effect: string
+  asset_id: string
+  start_time: number
+  config: EditPlanConfig
+}
+
+/** AI 推荐响应 */
+export interface AIRecommendResponse {
+  plan_id: string
+  clips: AIRecommendClipItem[]
+  config: EditPlanConfig
+  total_duration: number
+  confidence: number
+}
+
+/** AI 封面生成请求 */
+export interface GenerateCoverRequest {
+  asset_ids: string[]
+  cover_type?: "ai_frame" | "manual" | "upload" | "ai_regenerate"
+  frame_time?: number
+}
+
+/** AI 封面生成响应 */
+export interface GenerateCoverResponse {
+  plan_id: string
+  cover: CoverResult
+}
+
+/** 封面生成结果 */
+export interface CoverResult {
+  scheme?: string
+  asset_id?: string
+  frame_time?: number
+  thumbnail_url?: string
+}
+
+/* ── 片段 CRUD 相关 ── */
+
+/** 片段状态 */
+export type EditPlanClipStatus = "pending" | "processing" | "ready" | "failed"
+
+/** 剪辑片段（后端响应） */
+export interface EditPlanClip {
+  id: string
+  plan_id: string
+  clip_type: string
+  order: number
+  asset_id: string
+  text_content: string
+  start_time: number
+  duration: number
+  transition_effect: string
+  transition_duration: number
+  playback_speed: number
+  status: EditPlanClipStatus
+  config: Record<string, unknown>
+  created_at?: string
+  updated_at?: string
+}
+
+/** 创建片段请求 */
+export interface CreateEditPlanClipRequest {
+  clip_type: string
+  order: number
+  asset_id?: string
+  text_content?: string
+  start_time?: number
+  duration?: number
+  transition_effect?: string
+  transition_duration?: number
+  playback_speed?: number
+  config?: Record<string, unknown>
+}
+
+/** 更新片段请求 */
+export interface UpdateEditPlanClipRequest {
+  clip_type?: string
+  order?: number
+  asset_id?: string
+  text_content?: string
+  start_time?: number
+  duration?: number
+  transition_effect?: string
+  transition_duration?: number
+  playback_speed?: number
+  config?: Record<string, unknown>
+}
+
+/** 片段列表响应 */
+export interface EditPlanClipListResponse {
+  items: EditPlanClip[]
+  total: number
+}
+
+/** 片段列表查询参数 */
+export interface EditPlanClipListParams {
+  status?: string
+  skip?: number
+  limit?: number
+}
+
+/* ── 片段批量操作 ── */
+
+/** 重排序条目 */
+export interface ClipReorderItem {
+  clip_id: string
+  new_order: number
+}
+
+/** 重排序响应 */
+export interface ClipReorderResponse {
+  success: boolean
+  updated_count: number
+  message: string
+}
+
+/** 批量删除响应 */
+export interface ClipBatchDeleteResponse {
+  success: boolean
+  deleted_count: number
+  message: string
+}
+
+/** 从素材批量创建响应 */
+export interface ClipsFromAssetsResponse {
+  success: boolean
+  created_count: number
+  message: string
+  clip_ids: string[]
+}
+
+/* ── 复制计划 ── */
+
+/** 复制计划请求 */
+export interface CopyEditPlanRequest {
+  name?: string
+  project_id?: string
+}
+
+/* ── 前端 UI 类型 ── */
+
+/** 转场效果（14 种预设） */
+export interface TransitionEffect {
+  type:
+    | "none"
+    | "cut"
+    | "fade"
+    | "dissolve"
+    | "zoom"
+    | "slide_left"
+    | "slide_right"
+    | "slide_up"
+    | "slide_down"
+    | "wipe_left"
+    | "wipe_right"
+    | "wipe_up"
+    | "wipe_down"
+    | "circlecrop"
+    | "rectcrop"
+  duration: number
+  /** 播放速度倍率 */
+  playback_speed?: number
+}
+
+/** 素材库资产（UI 层类型） */
+export interface MediaAsset {
+  id: string
+  name: string
+  type: "video" | "image" | "audio"
+  /** 缩略图 URL */
+  thumbnail_url?: string
+  /** 时长（秒），仅 video/audio */
+  duration?: number
+  /** 文件大小（字节） */
+  size?: number
+  /** 标签 */
+  tags: string[]
+  created_at: string
+  /** 质量分 0-100 */
+  quality_score?: number
+  /** 分类状态 */
+  classification_status?: "pending" | "processing" | "completed" | "failed"
+}

apps/web/src/api/templateEditor.ts

@@ -1,744 +0,0 @@
-/**
- * 模板草稿 API — 对接后端 Template Editor Schema
- * 字段名严格匹配后端 API 响应
- */
-import apiClient from "./client"
-import type { AssetItem } from "./assets"
-import type {
-  WatermarkConfig,
-  IntroOutroConfig,
-  PipConfig,
-  FilterConfig,
-  ChromaKeyConfig,
-  StickerConfig,
-  CoverConfig,
-} from "@/pages/editing-planner/types"
-
-/* ============================================================
- * 后端 API 类型（严格匹配后端 Schema）
- * ============================================================ */
-
-/** 模板草稿状态枚举 */
-export type EditPlanStatus =
-  "draft" | "editing" | "rendering" | "completed" | "failed" | "cancelled"
-
-/** 标题配置（对齐后端 title_config） */
-export interface TitleConfig {
-  ai_auto_select: boolean
-  content: string
-  font_preset: string
-  font_color: string
-  font_size: number
-  position: string
-}
-
-/** 字幕配置 */
-export interface SubtitleConfig {
-  enabled: boolean
-  position: string
-  font: string
-  color: string
-  size: number
-  animation: string
-}
-
-/** BGM 配置 */
-export interface BgmConfig {
-  enabled: boolean
-  music_id: string
-}
-
-/** 片段 TTS 配置 */
-export interface SegmentTtsConfig {
-  mode: string
-  text: string
-  voice_id: string
-  speed: number
-  pitch: number
-  volume: number
-  subtitle_sync: boolean
-}
-
-/** 片段裁剪配置 */
-export interface SegmentTrimConfig {
-  start_time: number
-  end_time: number
-}
-
-/** 片段转场配置 */
-export interface SegmentTransitionConfig {
-  type: string
-  duration: number
-}
-
-/** 模板草稿中的单个片段（config 内部 segments 项） */
-export interface EditPlanSegment {
-  segment_order: number
-  duration_min: number
-  duration_max: number
-  material_type: string
-  transition?: SegmentTransitionConfig
-  playback_speed?: number
-  tts_config?: SegmentTtsConfig
-  trim_config?: SegmentTrimConfig
-}
-
-/** 模板草稿 config 完整类型（对齐后端 config JSON 结构） */
-export interface EditPlanConfig {
-  title_config?: TitleConfig
-  subtitle_config?: SubtitleConfig
-  bgm_config?: BgmConfig
-  estimated_duration?: number
-  segments?: EditPlanSegment[]
-  watermark_config?: WatermarkConfig
-  intro_outro_config?: IntroOutroConfig
-  pip_config?: PipConfig
-  filter_config?: FilterConfig
-  green_screen_config?: ChromaKeyConfig
-  sticker_config?: StickerConfig
-  cover_config?: CoverConfig
-  /** 前端扩展：关联的素材 ID 列表 */
-  asset_ids?: string[]
-  /** 配音 ID */
-  voice_id?: string
-  /** 克隆音色档案 ID */
-  voice_clone_profile_id?: string
-  /** 自定义配音音频 URL */
-  custom_audio_url?: string
-  /** 自定义配音文本 */
-  custom_text?: string
-  /** 视频比例 */
-  ratio?: string
-  /** 视频风格 */
-  style?: string
-  /** 目标时长（秒） */
-  duration?: number
-  /** 是否自动生成字幕 */
-  auto_subtitles?: boolean
-  /** 是否启用 BGM */
-  bgm?: boolean
-  /** 生成数量 */
-  generate_count?: number
-  /** 素材模式 */
-  material_mode?: string
-}
-
-/** 模板草稿（后端响应） */
-export interface EditPlan {
-  id: string
-  template_id: string
-  name: string
-  status: EditPlanStatus
-  total_duration: number
-  /** 生成视频数量（后端 EditPlanResponse.result_count） */
-  result_count: number
-  config: EditPlanConfig
-  created_at: string
-  updated_at: string
-}
-
-/** 创建模板草稿请求（后端要求 template_id + name 必填） */
-export interface CreateEditPlanRequest {
-  template_id: string
-  name: string
-  config?: EditPlanConfig
-  total_duration?: number
-  /** 来源模板草稿 ID（从模板编辑器跳转到智能剪辑时关联） */
-  source_edit_plan_id?: string
-}
-
-/** 更新模板草稿请求 */
-export interface UpdateEditPlanRequest {
-  name?: string
-  config?: EditPlanConfig
-  total_duration?: number
-  status?: EditPlanStatus
-}
-
-/** 生成响应 */
-export interface GenerateResponse {
-  plan_id: string
-  plan_status: EditPlanStatus
-  generation_task_id: string
-  clip_count: number
-}
-
-/** 模板草稿关联的生成记录（实际是 GenerationTask 对象） */
-export interface EditPlanGeneration {
-  id: string // 即 generation_task_id
-  source_edit_plan_id: string
-  template_id: string
-  asset_ids: string[]
-  status: EditPlanStatus
-  progress: number
-  result_count: number
-  error_message: string
-  error_info: Record<string, unknown>
-  logs: Array<Record<string, unknown>>
-  retry_count: number
-  created_at?: string
-  updated_at?: string
-}
-
-/** 片段生成状态 */
-export interface ClipStatusItem {
-  clip_id: string
-  clip_type: string
-  order: number
-  status: string
-  asset_id?: string
-  text_content?: string
-  duration?: number
-  error_message?: string
-}
-
-/** 生成状态轮询响应 */
-export interface GenerationStatusResponse {
-  plan_id: string
-  plan_status: EditPlanStatus
-  generation_task_id?: string
-  error_message?: string
-  clips: ClipStatusItem[]
-  error?: string
-  message?: string
-}
-
-/** 生成视频详情（对应后端 GeneratedVideoResponse） */
-export interface GeneratedVideo {
-  id: string
-  project_id?: string
-  generation_task_id?: string
-  name: string
-  file_url: string
-  file_size?: number
-  duration?: number
-  thumbnail_url?: string
-  width?: number
-  height?: number
-  fps?: number
-  status: string
-  review_status?: string
-  download_url?: string
-  created_at?: string
-  updated_at?: string
-}
-
-/* ============================================================
- * AI 推荐 & 封面生成（任务 3.09）
- * ============================================================ */
-
-/** AI 推荐请求 */
-export interface AIRecommendRequest {
-  asset_ids: string[]
-  editing_mode?: string
-  target_duration?: number
-}
-
-/** AI 推荐单个片段 */
-export interface AIRecommendClipItem {
-  clip_type: string
-  order: number
-  text_content: string
-  duration: number
-  transition_effect: string
-  asset_id: string
-  start_time: number
-  config: EditPlanConfig
-}
-
-/** AI 推荐响应 */
-export interface AIRecommendResponse {
-  plan_id: string
-  clips: AIRecommendClipItem[]
-  config: EditPlanConfig
-  total_duration: number
-  confidence: number
-}
-
-/** AI 封面生成请求 */
-export interface GenerateCoverRequest {
-  asset_ids: string[]
-  cover_type?: "ai_frame" | "manual" | "upload" | "ai_regenerate"
-  frame_time?: number
-}
-
-/** AI 封面生成响应 */
-export interface GenerateCoverResponse {
-  plan_id: string
-  cover: CoverResult
-}
-
-/** 封面生成结果 */
-export interface CoverResult {
-  scheme?: string
-  asset_id?: string
-  frame_time?: number
-  thumbnail_url?: string
-}
-
-/* ============================================================
- * 前端 UI 类型（EditingPlanner 组件依赖，保留兼容）
- * ============================================================ */
-
-/** 转场效果（14 种预设） */
-export interface TransitionEffect {
-  type:
-    | "none"
-    | "cut"
-    | "fade"
-    | "dissolve"
-    | "zoom"
-    | "slide_left"
-    | "slide_right"
-    | "slide_up"
-    | "slide_down"
-    | "wipe_left"
-    | "wipe_right"
-    | "wipe_up"
-    | "wipe_down"
-    | "circlecrop"
-    | "rectcrop"
-  duration: number // 转场时长（秒）
-  /** 播放速度倍率 */
-  playback_speed?: number
-}
-
-/** 素材库资产（UI 层类型，映射自后端 AssetResponse） */
-export interface MediaAsset {
-  id: string
-  name: string
-  type: "video" | "image" | "audio"
-  /** 缩略图 URL */
-  thumbnail_url?: string
-  /** 时长（秒），仅 video/audio */
-  duration?: number
-  /** 文件大小（字节） */
-  size?: number
-  /** 标签 */
-  tags: string[]
-  created_at: string
-  /** 质量分 0-100 */
-  quality_score?: number
-  /** 分类状态 */
-  classification_status?: "pending" | "processing" | "completed" | "failed"
-}
-
-/* ============================================================
- * API 函数 — 严格对接后端
- * ============================================================ */
-
-/** 模板草稿列表查询参数 */
-export interface EditPlanListParams {
-  page?: number
-  page_size?: number
-  template_id?: string
-  status?: string
-}
-
-/** 模板草稿列表分页响应 */
-export interface EditPlanListResponse {
-  items: EditPlan[]
-  total: number
-  page: number
-  page_size: number
-}
-
-/** 获取模板草稿列表（支持分页和筛选） */
-export async function getEditPlans(params?: EditPlanListParams): Promise<EditPlanListResponse> {
-  const response = await apiClient.get<EditPlanListResponse>("/templates/drafts", {
-    params,
-  })
-  return response.data
-}
-
-/** 获取单个模板草稿 */
-export async function getEditPlan(templateId: string): Promise<EditPlan> {
-  const response = await apiClient.get(`/templates/${templateId}/editor`)
-  return response.data
-}
-
-/** 创建模板草稿 */
-export async function createEditPlan(data: CreateEditPlanRequest): Promise<EditPlan> {
-  const response = await apiClient.post("/templates/drafts", data)
-  return response.data
-}
-
-/** 更新模板草稿 */
-export async function updateEditPlan(
-  templateId: string,
-  data: UpdateEditPlanRequest,
-): Promise<EditPlan> {
-  const response = await apiClient.put(`/templates/${templateId}/editor`, data)
-  return response.data
-}
-
-/** 删除模板草稿 */
-export async function deleteEditPlan(templateId: string): Promise<void> {
-  await apiClient.delete(`/templates/${templateId}/editor`)
-}
-
-/** 触发生成 */
-export async function generateEditPlan(templateId: string): Promise<GenerateResponse> {
-  const response = await apiClient.post(`/templates/${templateId}/editor/generate`)
-  return response.data
-}
-
-/** 获取生成状态（轮询用） */
-export async function getGenerationStatus(templateId: string): Promise<GenerationStatusResponse> {
-  const response = await apiClient.get(`/templates/${templateId}/editor/generation-status`)
-  return response.data
-}
-
-/** AI 推荐片段方案 */
-export async function aiRecommendClips(
-  templateId: string,
-  data: AIRecommendRequest,
-): Promise<AIRecommendResponse> {
-  const response = await apiClient.post(`/templates/${templateId}/editor/ai-recommend`, data)
-  return response.data
-}
-
-/** AI 生成封面 */
-export async function generateCover(
-  templateId: string,
-  data: GenerateCoverRequest,
-): Promise<GenerateCoverResponse> {
-  const response = await apiClient.post(`/templates/${templateId}/editor/generate-cover`, data)
-  return response.data
-}
-
-/** 获取模板草稿关联的生成记录 */
-export async function getEditPlanGenerations(templateId: string): Promise<EditPlanGeneration[]> {
-  const response = await apiClient.get(`/templates/${templateId}/editor/generations`)
-  return response.data.items || []
-}
-
-/** 获取生成任务的视频结果列表 */
-export async function getGenerationTaskResults(taskId: string): Promise<GeneratedVideo[]> {
-  const response = await apiClient.get(`/generation/tasks/${taskId}/results`)
-  return response.data.items || response.data || []
-}
-
-/** 取消生成任务 */
-export async function cancelGeneration(templateId: string): Promise<void> {
-  await apiClient.post(`/templates/${templateId}/editor/cancel`)
-}
-
-/* ============================================================
- * 片段 CRUD（后端 EditPlanClip 独立表）
- * ============================================================ */
-
-/** 片段状态 */
-export type EditPlanClipStatus = "pending" | "processing" | "ready" | "failed"
-
-/** 剪辑片段（后端响应） */
-export interface EditPlanClip {
-  id: string
-  plan_id: string
-  clip_type: string // main / intro / outro / overlay / background / b_roll 等
-  order: number
-  asset_id: string
-  text_content: string
-  start_time: number
-  duration: number
-  transition_effect: string
-  transition_duration: number
-  playback_speed: number
-  status: EditPlanClipStatus
-  config: Record<string, unknown>
-  created_at?: string
-  updated_at?: string
-}
-
-/** 创建片段请求 */
-export interface CreateEditPlanClipRequest {
-  clip_type: string
-  order: number
-  asset_id?: string
-  text_content?: string
-  start_time?: number
-  duration?: number
-  transition_effect?: string
-  transition_duration?: number
-  playback_speed?: number
-  config?: Record<string, unknown>
-}
-
-/** 更新片段请求 */
-export interface UpdateEditPlanClipRequest {
-  clip_type?: string
-  order?: number
-  asset_id?: string
-  text_content?: string
-  start_time?: number
-  duration?: number
-  transition_effect?: string
-  transition_duration?: number
-  playback_speed?: number
-  config?: Record<string, unknown>
-}
-
-/** 片段列表响应 */
-export interface EditPlanClipListResponse {
-  items: EditPlanClip[]
-  total: number
-}
-
-/** 片段列表查询参数 */
-export interface EditPlanClipListParams {
-  status?: string
-  skip?: number
-  limit?: number
-}
-
-/** 获取片段列表 */
-export async function getEditPlanClips(
-  templateId: string,
-  params?: EditPlanClipListParams,
-): Promise<EditPlanClipListResponse> {
-  const response = await apiClient.get<EditPlanClipListResponse>(
-    `/templates/${templateId}/editor/clips`,
-    {
-      params,
-    },
-  )
-  return response.data
-}
-
-/** 获取单个片段详情 */
-export async function getEditPlanClip(templateId: string, clipId: string): Promise<EditPlanClip> {
-  const response = await apiClient.get<EditPlanClip>(
-    `/templates/${templateId}/editor/clips/${clipId}`,
-  )
-  return response.data
-}
-
-/** 创建片段 */
-export async function createEditPlanClip(
-  templateId: string,
-  data: CreateEditPlanClipRequest,
-): Promise<EditPlanClip> {
-  const response = await apiClient.post<EditPlanClip>(`/templates/${templateId}/editor/clips`, data)
-  return response.data
-}
-
-/** 更新片段 */
-export async function updateEditPlanClip(
-  templateId: string,
-  clipId: string,
-  data: UpdateEditPlanClipRequest,
-): Promise<EditPlanClip> {
-  const response = await apiClient.put<EditPlanClip>(
-    `/templates/${templateId}/editor/clips/${clipId}`,
-    data,
-  )
-  return response.data
-}
-
-/** 删除片段 */
-export async function deleteEditPlanClip(templateId: string, clipId: string): Promise<void> {
-  await apiClient.delete(`/templates/${templateId}/editor/clips/${clipId}`)
-}
-
-/* ============================================================
- * 片段批量操作
- * ============================================================ */
-
-/** 重排序条目 */
-export interface ClipReorderItem {
-  clip_id: string
-  new_order: number
-}
-
-/** 重排序响应 */
-export interface ClipReorderResponse {
-  success: boolean
-  updated_count: number
-  message: string
-}
-
-/** 批量删除响应 */
-export interface ClipBatchDeleteResponse {
-  success: boolean
-  deleted_count: number
-  message: string
-}
-
-/** 从素材批量创建响应 */
-export interface ClipsFromAssetsResponse {
-  success: boolean
-  created_count: number
-  message: string
-  clip_ids: string[]
-}
-
-/** 片段重排序（拖拽排序后一次性提交） */
-export async function reorderEditPlanClips(
-  templateId: string,
-  items: ClipReorderItem[],
-): Promise<ClipReorderResponse> {
-  const response = await apiClient.post<ClipReorderResponse>(
-    `/templates/${templateId}/editor/clips/reorder`,
-    { items },
-  )
-  return response.data
-}
-
-/** 批量删除片段 */
-export async function batchDeleteEditPlanClips(
-  templateId: string,
-  clipIds: string[],
-): Promise<ClipBatchDeleteResponse> {
-  const response = await apiClient.post<ClipBatchDeleteResponse>(
-    `/templates/${templateId}/editor/clips/batch-delete`,
-    { clip_ids: clipIds },
-  )
-  return response.data
-}
-
-/** 从素材批量创建片段（追加到时间线末尾） */
-export async function createClipsFromAssets(
-  templateId: string,
-  assetIds: string[],
-  clipType = "main",
-): Promise<ClipsFromAssetsResponse> {
-  const response = await apiClient.post<ClipsFromAssetsResponse>(
-    `/templates/${templateId}/editor/clips/from-assets`,
-    { asset_ids: assetIds, clip_type: clipType },
-  )
-  return response.data
-}
-
-/* ============================================================
- * 复制计划
- * ============================================================ */
-
-/** 复制计划请求 */
-export interface CopyEditPlanRequest {
-  name?: string
-  project_id?: string
-}
-
-/** 复制模板草稿（含所有片段配置） */
-export async function copyEditPlan(
-  templateId: string,
-  data?: CopyEditPlanRequest,
-): Promise<EditPlan> {
-  const response = await apiClient.post<EditPlan>(
-    `/templates/${templateId}/editor/copy`,
-    data || {},
-  )
-  return response.data
-}
-
-/**
- * 获取素材库列表 — 调用 GET /api/v1/assets?library_id=xxx
- * 将后端 AssetResponse 映射为前端 MediaAsset 类型
- */
-export async function getMediaAssets(libraryId?: string): Promise<MediaAsset[]> {
-  const response = await apiClient.get("/assets", {
-    params: libraryId ? { library_id: libraryId } : undefined,
-  })
-  const items: AssetItem[] = response.data.items || []
-  return items.map(mapAssetToMediaAsset)
-}
-
-/** 获取单个素材 */
-export async function getMediaAsset(id: string): Promise<MediaAsset> {
-  const response = await apiClient.get(`/assets/${id}`)
-  return mapAssetToMediaAsset(response.data)
-}
-
-/* ============================================================
- * 映射函数：AssetResponse → MediaAsset
- * ============================================================ */
-
-function inferMediaType(mimeType: string): "video" | "image" | "audio" {
-  if (mimeType.startsWith("video/")) return "video"
-  if (mimeType.startsWith("image/")) return "image"
-  return "audio"
-}
-
-function mapAssetToMediaAsset(asset: AssetItem): MediaAsset {
-  // 优先取顶层 duration，其次从 metadata 回退
-  const metaDuration =
-    typeof asset.metadata?.duration === "number" ? asset.metadata.duration : undefined
-  return {
-    id: asset.id,
-    name: asset.name,
-    type: inferMediaType(asset.mime_type || ""),
-    thumbnail_url: asset.thumbnail_url,
-    duration: asset.duration ?? metaDuration,
-    size: asset.file_size ?? undefined,
-    tags: [],
-    created_at: asset.created_at ?? "",
-    quality_score: asset.quality_score ?? undefined,
-    classification_status: asset.classification_status ?? undefined,
-  }
-}
-
-/* ============================================================
- * 常量
- * ============================================================ */
-
-/** 转场效果选项（14 种预设） */
-export const TRANSITION_OPTIONS: {
-  value: TransitionEffect["type"]
-  label: string
-  icon: string
-}[] = [
-  { value: "none", label: "无转场", icon: "⊘" },
-  { value: "cut", label: "硬切", icon: "✂" },
-  { value: "fade", label: "淡入淡出", icon: "◐" },
-  { value: "dissolve", label: "溶解", icon: "◈" },
-  { value: "zoom", label: "缩放", icon: "⊕" },
-  { value: "slide_left", label: "左滑", icon: "←" },
-  { value: "slide_right", label: "右滑", icon: "→" },
-  { value: "slide_up", label: "上滑", icon: "↑" },
-  { value: "slide_down", label: "下滑", icon: "↓" },
-  { value: "wipe_left", label: "左擦除", icon: "▸|" },
-  { value: "wipe_right", label: "右擦除", icon: "|◂" },
-  { value: "wipe_up", label: "上擦除", icon: "▴̄" },
-  { value: "wipe_down", label: "下擦除", icon: "▾̄" },
-  { value: "circlecrop", label: "圆形裁切", icon: "●" },
-  { value: "rectcrop", label: "矩形裁切", icon: "■" },
-]
-
-/** 素材类型标签 */
-export const MATERIAL_TYPE_LABELS: Record<string, string> = {
-  video: "视频",
-  image: "图片",
-  audio: "音频",
-  voiceover: "配音",
-}
-
-/** 素材类型图标 */
-export const MATERIAL_TYPE_ICONS: Record<string, string> = {
-  video: "🎬",
-  image: "🖼️",
-  audio: "🎵",
-  voiceover: "🎙️",
-}
-
-/** 计划状态标签 */
-export const PLAN_STATUS_LABELS: Record<EditPlanStatus, string> = {
-  draft: "草稿",
-  editing: "编辑中",
-  rendering: "渲染中",
-  completed: "已完成",
-  failed: "失败",
-  cancelled: "已取消",
-}
-
-/** 质量分筛选选项 */
-export const QUALITY_OPTIONS: {
-  value: string
-  label: string
-  min?: number
-  max?: number
-}[] = [
-  { value: "all", label: "全部质量" },
-  { value: "high", label: "高质量 (80-100)", min: 80, max: 100 },
-  { value: "medium", label: "中质量 (50-79)", min: 50, max: 79 },
-  { value: "low", label: "低质量 (0-49)", min: 0, max: 49 },
-]

apps/web/src/api/templates.ts

@@ -1,168 +0,0 @@
-/**
- * 模板相关 API
- * 对接后端模板管理接口：
- * - GET  /api/v1/templates              — 模板列表（分页/筛选）
- * - GET  /api/v1/templates/{id}         — 模板详情
- * - POST /api/v1/templates/{id}/copy    — 复制模板
- * - POST /api/v1/templates/{id}/generate — 从模板生成
- * - POST /api/v1/templates/{id}/toggle-favorite — 收藏/取消收藏
- */
-import apiClient from "./client"
-import type { TitleConfig, SubtitleConfig, BgmConfig } from "./editingPlanner"
-import type { EditPlanConfig } from "./templateEditor"
-
-/* ──────────── 类型定义 ──────────── */
-
-/** 模板条目（后端 TemplateResponse） */
-export interface TemplateItem {
-  id: string
-  user_id?: string
-  name: string
-  description?: string
-  mode?: string
-  category: string
-  tags?: string[]
-  /** 预估时长（后端字段名 estimated_duration） */
-  estimated_duration?: number
-  /** @deprecated 后端已改名为 estimated_duration，保留兼容 */
-  target_duration?: number
-  clip_count?: number
-  /** 使用次数 */
-  usage_count?: number
-  thumbnail_url?: string
-  preview_url?: string
-  is_active?: boolean
-  is_favorite?: boolean
-  /** 素材规则（片段配置） */
-  segments?: TemplateSegment[]
-  /** 字幕样式 */
-  subtitle_config?: SubtitleConfig
-  /** BGM 配置 */
-  bgm_config?: BgmConfig
-  /** 标题配置 */
-  title_config?: TitleConfig
-  /** 视频比例 */
-  aspect_ratio?: string
-  created_at?: string
-  updated_at?: string
-}
-
-/** 模板片段（素材规则） */
-export interface TemplateSegment {
-  id?: string
-  segment_order: number
-  duration_min: number
-  duration_max: number
-  material_type: string | null
-  description?: string
-}
-
-/** 模板列表查询参数 */
-export interface TemplateListParams {
-  page?: number
-  page_size?: number
-  category?: string
-  tags?: string
-  keyword?: string
-  /** 时长筛选（秒）：short < 30, medium 30-120, long > 120 */
-  duration_range?: "short" | "medium" | "long"
-}
-
-/** 模板列表分页响应 */
-export interface TemplateListResponse {
-  items: TemplateItem[]
-  total: number
-  page: number
-  page_size: number
-}
-
-/** 从模板生成请求 */
-export interface GenerateFromTemplateRequest {
-  asset_ids?: string[]
-  name?: string
-  config?: EditPlanConfig
-}
-
-/** 从模板生成响应 */
-export interface GenerateFromTemplateResponse {
-  plan_id: string
-  template_id: string
-  status: string
-  name: string
-}
-
-/** 复制模板响应 */
-export interface CopyTemplateResponse {
-  id: string
-  name: string
-  source_template_id: string
-}
-
-/* ──────────── API 函数 ──────────── */
-
-/** 获取模板列表（支持分页和筛选） */
-export const getTemplates = async (params?: TemplateListParams): Promise<TemplateListResponse> => {
-  const { data } = await apiClient.get<TemplateListResponse>("/templates", {
-    params,
-  })
-  return data
-}
-
-/** 获取模板列表（兼容旧接口，返回数组） */
-export const getTemplatesList = async (): Promise<TemplateItem[]> => {
-  const response = await apiClient.get("/templates")
-  return response.data.items || response.data || []
-}
-
-/** 获取单个模板详情 */
-export const getTemplate = async (templateId: string): Promise<TemplateItem> => {
-  const response = await apiClient.get(`/templates/${templateId}`)
-  return response.data
-}
-
-/** 收藏 / 取消收藏模板 */
-export const toggleFavoriteTemplate = async (
-  templateId: string,
-): Promise<{ is_favorite: boolean }> => {
-  const response = await apiClient.post(`/templates/${templateId}/toggle-favorite`)
-  return response.data
-}
-
-/** 复制模板（创建副本到我的模板） */
-export const copyTemplate = async (templateId: string): Promise<CopyTemplateResponse> => {
-  const response = await apiClient.post<CopyTemplateResponse>(`/templates/${templateId}/copy`)
-  return response.data
-}
-
-/** 从模板生成 */
-export const generateFromTemplate = async (
-  templateId: string,
-  data?: GenerateFromTemplateRequest,
-): Promise<GenerateFromTemplateResponse> => {
-  const response = await apiClient.post<GenerateFromTemplateResponse>(
-    `/templates/${templateId}/generate`,
-    data,
-  )
-  return response.data
-}
-
-/* ──────────── 常量 ──────────── */
-
-/** 模板分类选项 */
-export const TEMPLATE_CATEGORY_OPTIONS = [
-  { value: "", label: "全部分类" },
-  { value: "口播", label: "口播" },
-  { value: "种草", label: "种草" },
-  { value: "产品", label: "产品" },
-  { value: "品牌", label: "品牌" },
-  { value: "混剪", label: "混剪" },
-  { value: "Vlog", label: "Vlog" },
-]
-
-/** 时长筛选选项 */
-export const TEMPLATE_DURATION_OPTIONS = [
-  { value: "", label: "全部时长" },
-  { value: "short", label: "30秒以内" },
-  { value: "medium", label: "30秒-2分钟" },
-  { value: "long", label: "2分钟以上" },
-]

apps/web/src/api/templates/constants.ts

@@ -0,0 +1,22 @@
+/**
+ * 模板相关常量
+ */
+
+/** 模板分类选项 */
+export const TEMPLATE_CATEGORY_OPTIONS = [
+  { value: "", label: "全部分类" },
+  { value: "口播", label: "口播" },
+  { value: "种草", label: "种草" },
+  { value: "产品", label: "产品" },
+  { value: "品牌", label: "品牌" },
+  { value: "混剪", label: "混剪" },
+  { value: "Vlog", label: "Vlog" },
+]
+
+/** 时长筛选选项 */
+export const TEMPLATE_DURATION_OPTIONS = [
+  { value: "", label: "全部时长" },
+  { value: "short", label: "30秒以内" },
+  { value: "medium", label: "30秒-2分钟" },
+  { value: "long", label: "2分钟以上" },
+]

apps/web/src/api/templates/index.ts

@@ -0,0 +1,28 @@
+/**
+ * 模板相关 API — 目录化入口
+ * 保持与原 templates.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type {
+  TemplateItem,
+  TemplateSegment,
+  TemplateListParams,
+  TemplateListResponse,
+  GenerateFromTemplateRequest,
+  GenerateFromTemplateResponse,
+  CopyTemplateResponse,
+} from "./types"
+
+// 常量
+export { TEMPLATE_CATEGORY_OPTIONS, TEMPLATE_DURATION_OPTIONS } from "./constants"
+
+// API 函数
+export {
+  getTemplates,
+  getTemplatesList,
+  getTemplate,
+  toggleFavoriteTemplate,
+  copyTemplate,
+  generateFromTemplate,
+} from "./templates"

apps/web/src/api/templates/templates.ts

@@ -0,0 +1,59 @@
+/**
+ * 模板相关 API 函数
+ * 对接后端模板管理接口
+ */
+import apiClient from "../client"
+import type {
+  CopyTemplateResponse,
+  GenerateFromTemplateRequest,
+  GenerateFromTemplateResponse,
+  TemplateItem,
+  TemplateListParams,
+  TemplateListResponse,
+} from "./types"
+
+/** 获取模板列表（支持分页和筛选） */
+export const getTemplates = async (params?: TemplateListParams): Promise<TemplateListResponse> => {
+  const { data } = await apiClient.get<TemplateListResponse>("/templates", {
+    params,
+  })
+  return data
+}
+
+/** 获取模板列表（兼容旧接口，返回数组） */
+export const getTemplatesList = async (): Promise<TemplateItem[]> => {
+  const response = await apiClient.get("/templates")
+  return response.data.items || response.data || []
+}
+
+/** 获取单个模板详情 */
+export const getTemplate = async (templateId: string): Promise<TemplateItem> => {
+  const response = await apiClient.get(`/templates/${templateId}`)
+  return response.data
+}
+
+/** 收藏 / 取消收藏模板 */
+export const toggleFavoriteTemplate = async (
+  templateId: string,
+): Promise<{ is_favorite: boolean }> => {
+  const response = await apiClient.post(`/templates/${templateId}/toggle-favorite`)
+  return response.data
+}
+
+/** 复制模板（创建副本到我的模板） */
+export const copyTemplate = async (templateId: string): Promise<CopyTemplateResponse> => {
+  const response = await apiClient.post<CopyTemplateResponse>(`/templates/${templateId}/copy`)
+  return response.data
+}
+
+/** 从模板生成 */
+export const generateFromTemplate = async (
+  templateId: string,
+  data?: GenerateFromTemplateRequest,
+): Promise<GenerateFromTemplateResponse> => {
+  const response = await apiClient.post<GenerateFromTemplateResponse>(
+    `/templates/${templateId}/generate`,
+    data,
+  )
+  return response.data
+}

apps/web/src/api/templates/types.ts

@@ -0,0 +1,90 @@
+/**
+ * 模板相关类型定义
+ */
+import type { TitleConfig, SubtitleConfig, BgmConfig } from "../editing-planner"
+import type { EditPlanConfig } from "../template-editor"
+
+/** 模板条目（后端 TemplateResponse） */
+export interface TemplateItem {
+  id: string
+  user_id?: string
+  name: string
+  description?: string
+  mode?: string
+  category: string
+  tags?: string[]
+  /** 预估时长（后端字段名 estimated_duration） */
+  estimated_duration?: number
+  /** @deprecated 后端已改名为 estimated_duration，保留兼容 */
+  target_duration?: number
+  clip_count?: number
+  /** 使用次数 */
+  usage_count?: number
+  thumbnail_url?: string
+  preview_url?: string
+  is_active?: boolean
+  is_favorite?: boolean
+  /** 素材规则（片段配置） */
+  segments?: TemplateSegment[]
+  /** 字幕样式 */
+  subtitle_config?: SubtitleConfig
+  /** BGM 配置 */
+  bgm_config?: BgmConfig
+  /** 标题配置 */
+  title_config?: TitleConfig
+  /** 视频比例 */
+  aspect_ratio?: string
+  created_at?: string
+  updated_at?: string
+}
+
+/** 模板片段（素材规则） */
+export interface TemplateSegment {
+  id?: string
+  segment_order: number
+  duration_min: number
+  duration_max: number
+  material_type: string | null
+  description?: string
+}
+
+/** 模板列表查询参数 */
+export interface TemplateListParams {
+  page?: number
+  page_size?: number
+  category?: string
+  tags?: string
+  keyword?: string
+  /** 时长筛选（秒）：short < 30, medium 30-120, long > 120 */
+  duration_range?: "short" | "medium" | "long"
+}
+
+/** 模板列表分页响应 */
+export interface TemplateListResponse {
+  items: TemplateItem[]
+  total: number
+  page: number
+  page_size: number
+}
+
+/** 从模板生成请求 */
+export interface GenerateFromTemplateRequest {
+  asset_ids?: string[]
+  name?: string
+  config?: EditPlanConfig
+}
+
+/** 从模板生成响应 */
+export interface GenerateFromTemplateResponse {
+  plan_id: string
+  template_id: string
+  status: string
+  name: string
+}
+
+/** 复制模板响应 */
+export interface CopyTemplateResponse {
+  id: string
+  name: string
+  source_template_id: string
+}

apps/web/src/api/titles/index.ts

@@ -0,0 +1,19 @@
+/**
+ * 标题相关 API — 目录化入口
+ * 保持与原 titles.ts 相同导出，向后兼容
+ */
+
+// 类型
+export type {
+  TitleItem,
+  BackendTitleResponse,
+  BackendCreateTitleRequest,
+  BackendUpdateTitleRequest,
+  CreateTitleRequest,
+} from "./types"
+
+// 工具函数
+export { toTitleItem } from "./utils"
+
+// API 函数
+export { getTitles, createTitle, updateTitle, deleteTitle, batchImportTitles } from "./titles"

apps/web/src/api/titles/titles.ts

@@ -1,70 +1,17 @@
 /**
- * 标题相关 API
+ * 标题相关 API 函数
  * Phase 1 新增：全局标题库
  * 注意：后端 schema 使用 name + text 字段，前端 UI 用 content 展示
  */
-import apiClient from "./client"
-
-/** 标题条目（前端展示用） */
-export interface TitleItem {
-  id: string
-  content: string
-  category?: string
-  source?: string
-  word_count?: number
-  is_favorite?: boolean
-  created_at?: string
-  updated_at?: string
-}
-
-/** 后端标题响应格式 */
-interface BackendTitleResponse {
-  id: string
-  user_id: string
-  name: string
-  text: string
-  category: string
-  description: string
-  tags: string[]
-  usage_count: number
-  is_active: boolean
-  created_at: string
-  updated_at: string
-}
-
-/** 后端创建标题请求格式 */
-interface BackendCreateTitleRequest {
-  name: string
-  text: string
-  category: string
-  description?: string
-  tags?: string[]
-}
-
-/** 后端更新标题请求格式 */
-interface BackendUpdateTitleRequest {
-  name?: string
-  text?: string
-  category?: string
-  description?: string
-  tags?: string[]
-}
-
-/** 将后端响应映射为前端 TitleItem */
-const toTitleItem = (item: BackendTitleResponse): TitleItem => ({
-  id: item.id,
-  content: item.text,
-  category: item.category,
-  word_count: item.text?.length || 0,
-  created_at: item.created_at,
-  updated_at: item.updated_at,
-})
-
-/** 创建标题请求（前端接口，保持向后兼容） */
-export interface CreateTitleRequest {
-  content: string
-  category?: string
-}
+import apiClient from "../client"
+import type {
+  BackendCreateTitleRequest,
+  BackendTitleResponse,
+  BackendUpdateTitleRequest,
+  CreateTitleRequest,
+  TitleItem,
+} from "./types"
+import { toTitleItem } from "./utils"
 
 /** 获取当前用户的所有标题 */
 export const getTitles = async (): Promise<TitleItem[]> => {