test(web): 修复WechatCallback测试 - mock localStorage的wechat_state

test(web): 修复WechatCallback测试 - mock正确的code/state参数
test(web): 添加WechatCallback页面基础单元测试
2026-07-23 19:21:52 +08:00 · 2026-07-23 19:14:44 +08:00 · 2026-07-23 18:56:24 +08:00 · 2026-07-23 18:29:31 +08:00 · 2026-07-23 18:16:03 +08:00 · 2026-07-23 18:11:31 +08:00
207 changed files with 32963 additions and 12403 deletions
@@ -1 +1,2 @@
-trigger: 1784009947
+CI trigger file - safe to delete
+updated!
@@ -0,0 +1,78 @@
+name: CI Failure Monitor
+
+on:
+  schedule:
+    - cron: '0 */6 * * *'  # 每6小时检查一次
+  workflow_dispatch:
+    inputs:
+      days:
+        description: '统计最近N天的失败'
+        required: false
+        default: '7'
+      fail_threshold:
+        description: '失败次数阈值'
+        required: false
+        default: '3'
+      fail_rate_threshold:
+        description: '失败率阈值(%)'
+        required: false
+        default: '30'
+
+permissions:
+  contents: read
+
+jobs:
+  monitor:
+    name: CI重复失败检测
+    runs-on: ci-l2
+    timeout-minutes: 10
+
+    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: Run failure detection
+      shell: sh
+      env:
+        GITEA_API_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+        GITEA_URL: https://git.xiaoxiajianji.com
+        GITEA_REPO: xiaoxia/xiaoxia-saas
+        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
+        FAIL_CHECK_DAYS: ${{ inputs.days || 7 }}
+        FAIL_THRESHOLD: ${{ inputs.fail_threshold || 3 }}
+        FAIL_RATE_THRESHOLD: ${{ inputs.fail_rate_threshold || 30 }}
+      run: |
+        set +e
+        python3 scripts/ci/ci_repeated_failure_detector.py
+        EXIT_CODE=$?
+        echo "检测完成，退出码: $EXIT_CODE"
+        # 0=无异常, 1=有警告, 2=有严重问题
+        # 监控脚本永远不fail，避免告警风暴
+        exit 0
+
+    - name: Job duration summary
+      if: always()
+      shell: sh
+      run: bash scripts/ci/step_timer_end.sh
+
+    - 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
@@ -0,0 +1,103 @@
+name: CI Health Daily Report
+on:
+  schedule:
+    - cron: '0 1 * * *'  # UTC 01:00 = 北京时间 09:00
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  ci-health-report:
+    name: CI健康度每日巡检
+    runs-on: saas
+    timeout-minutes: 15
+    steps:
+    - name: Checkout code
+      shell: sh
+      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
+
+    - name: Generate CI Dashboard HTML
+      shell: sh
+      env:
+        GITEA_TOKEN: ${{ github.token }}
+      run: |
+        set +e
+        echo "=== 生成 CI 健康度 HTML 看板 ==="
+        echo "时间: $(date '+%Y-%m-%d %H:%M:%S')"
+        echo ""
+        python3 scripts/ci/ci_dashboard.py --days 7 --html --html-output ci_dashboard.html
+        EXIT_CODE=$?
+        if [ $EXIT_CODE -eq 0 ] && [ -f ci_dashboard.html ]; then
+            HTML_SIZE=$(wc -c < ci_dashboard.html)
+            echo ""
+            echo "✅ HTML 看板生成成功 (${HTML_SIZE} bytes)"
+            echo "路径: $(pwd)/ci_dashboard.html"
+            # 输出文件内容前几行，方便在 Actions 日志中确认
+            echo ""
+            echo "--- 看板预览 (前 5 行) ---"
+            head -5 ci_dashboard.html
+            echo "...（完整内容见产物文件）"
+        else
+            echo "❌ HTML 看板生成失败 (exit code: $EXIT_CODE)"
+        fi
+        echo ""
+        # 永远成功，看板生成失败不影响主流程
+        exit 0
+
+    - name: Run CI health check and report
+      shell: sh
+      env:
+        GITEA_TOKEN: ${{ github.token }}
+        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
+      run: |
+        set +e
+        echo "=== CI健康度每日巡检 ==="
+        echo "时间: $(date '+%Y-%m-%d %H:%M:%S')"
+        echo ""
+        python3 scripts/ci/ci_health_report.py --limit 30
+        EXIT_CODE=$?
+        echo ""
+        echo "巡检完成 (exit code: $EXIT_CODE)"
+        # 永远成功，不影响CI状态（通知失败不应该标红）
+        exit 0
@@ -10,6 +10,8 @@ on:
    branches:
    - main
    - develop
+  schedule:
+    - cron: '0 19 * * *'  # UTC 19:00 = 北京时间凌晨3:00，每日全量CI回归
  workflow_dispatch:
    inputs:
      reason:
@@ -76,18 +78,12 @@ jobs:
        [ -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

-  validate:
-    needs: check-frontend-only
-    if: always() && needs.check-frontend-only.outputs.skip_backend != 'true'
-    name: Validate Code Quality And Tests
+  validate-code-quality:
+    name: Validate - Code Quality
    runs-on: ci-l2
-    timeout-minutes: 10
+    timeout-minutes: 8
    permissions:
      contents: write
-    env:
-      DATABASE_URL: postgresql+psycopg://postgres:postgres@host.docker.internal:5432/xiaoxia_saas
-      USE_IN_MEMORY_DB: 'false'
-      CI_USE_SHARED_PG: 'true'
    steps:
    - name: Checkout code
      shell: sh
@@ -102,7 +98,6 @@ jobs:
      shell: sh
      run: |
        set -eu
-        # pip install 带重试（网络不稳定时自动重试）
        for i in 1 2 3; do
          python3 -m pip install -q -r requirements-base.txt && break
          echo "pip install requirements-base.txt 失败，重试 $i/3..."
@@ -127,16 +122,17 @@ jobs:
          [ $i -eq 3 ] && exit 1
          sleep 5
        done
-    - name: Run all quality checks
+    - name: Run code quality and security checks
      shell: bash
      env:
        GITHUB_TOKEN: ${{ github.token }}
-      run: bash scripts/ci/run_validate.sh
+      run: bash scripts/ci/validate_code_quality.sh
    - name: Auto-fix formatting (black + isort)
      if: failure()
      shell: sh
      env:
        GITHUB_TOKEN: ${{ github.token }}
+        REVIEW_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
      run: python3 scripts/ci/auto_fix_formatting.py
    - name: CI failure notification
      if: failure()
@@ -146,7 +142,7 @@ jobs:
        CI_WEBHOOK_URL: ${{ secrets.CI_WEBHOOK_URL }}
      run: |
        set +e
-        FAILED_JOB="Validate Code Quality And Tests" python3 scripts/ci_notify_failure.py
+        FAILED_JOB="Validate - Code Quality" python3 scripts/ci_notify_failure.py
    - name: Job duration summary
      if: always()
      shell: sh
@@ -159,7 +155,161 @@ jobs:
        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
      run: |
        set +e
-        NOTIFY_MODE=failure JOB_NAME="Validate Code Quality And Tests" python3 scripts/ci_notify.py
+        NOTIFY_MODE=failure JOB_NAME="Validate - Code Quality" 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
+
+  validate-type-check:
+    name: Validate - Type Check (mypy)
+    runs-on: ci-l2
+    timeout-minutes: 8
+    permissions:
+      contents: read
+    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: Install dependencies
+      shell: sh
+      run: |
+        set -eu
+        for i in 1 2 3; do
+          python3 -m pip install -q -r requirements-base.txt && break
+          echo "pip install requirements-base.txt 失败，重试 $i/3..."
+          [ $i -eq 3 ] && exit 1
+          sleep 5
+        done
+        for i in 1 2 3; do
+          python3 -m pip install -q -r requirements.txt && break
+          echo "pip install requirements.txt 失败，重试 $i/3..."
+          [ $i -eq 3 ] && exit 1
+          sleep 5
+        done
+        for i in 1 2 3; do
+          python3 -m pip install -q -r requirements-dev.txt && break
+          echo "pip install requirements-dev.txt 失败，重试 $i/3..."
+          [ $i -eq 3 ] && exit 1
+          sleep 5
+        done
+    - name: Run mypy type check
+      shell: bash
+      run: bash scripts/ci/validate_mypy.sh
+    - name: CI failure notification
+      if: failure()
+      shell: sh
+      env:
+        GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+        CI_WEBHOOK_URL: ${{ secrets.CI_WEBHOOK_URL }}
+      run: |
+        set +e
+        FAILED_JOB="Validate - Type Check (mypy)" python3 scripts/ci_notify_failure.py
+    - name: Job duration summary
+      if: always()
+      shell: sh
+      run: bash scripts/ci/step_timer_end.sh
+    - 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="Validate - Type Check (mypy)" 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
+
+  validate-migration:
+    name: Validate - Migration (alembic)
+    runs-on: ci-l2
+    timeout-minutes: 8
+    permissions:
+      contents: read
+    env:
+      DATABASE_URL: postgresql+psycopg://postgres:postgres@host.docker.internal:5432/xiaoxia_saas
+      USE_IN_MEMORY_DB: 'false'
+      CI_USE_SHARED_PG: 'true'
+    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: Install dependencies
+      shell: sh
+      run: |
+        set -eu
+        for i in 1 2 3; do
+          python3 -m pip install -q -r requirements-base.txt && break
+          echo "pip install requirements-base.txt 失败，重试 $i/3..."
+          [ $i -eq 3 ] && exit 1
+          sleep 5
+        done
+        for i in 1 2 3; do
+          python3 -m pip install -q -r requirements.txt && break
+          echo "pip install requirements.txt 失败，重试 $i/3..."
+          [ $i -eq 3 ] && exit 1
+          sleep 5
+        done
+        for i in 1 2 3; do
+          python3 -m pip install -q -r requirements-dev.txt && break
+          echo "pip install requirements-dev.txt 失败，重试 $i/3..."
+          [ $i -eq 3 ] && exit 1
+          sleep 5
+        done
+    - name: Run alembic migration validation
+      shell: bash
+      run: bash scripts/ci/validate_migration.sh
+    - name: CI failure notification
+      if: failure()
+      shell: sh
+      env:
+        GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+        CI_WEBHOOK_URL: ${{ secrets.CI_WEBHOOK_URL }}
+      run: |
+        set +e
+        FAILED_JOB="Validate - Migration (alembic)" python3 scripts/ci_notify_failure.py
+    - name: Job duration summary
+      if: always()
+      shell: sh
+      run: bash scripts/ci/step_timer_end.sh
+    - 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="Validate - Migration (alembic)" python3 scripts/ci_notify.py
    - name: Report CI trace
      if: always()
      shell: sh
@@ -335,9 +485,6 @@ jobs:
    - name: Run Prettier check
      shell: sh
      run: bash scripts/ci/step_frontend_run.sh "npx --no-install prettier --check \"src/**/*.{ts,tsx,md}\""
-    - name: Run Vitest tests
-      shell: sh
-      run: bash scripts/ci/step_frontend_run.sh "npx --no-install vitest run src/test"
    - name: Job duration summary
      if: always()
      shell: sh
@@ -390,9 +537,11 @@ jobs:
          [ $i -eq 3 ] && exit 1
          sleep 5
        done
-    - name: Run Vitest with coverage
+    - name: Run Vitest (incremental for PRs, full for main branches)
      shell: sh
-      run: bash scripts/ci/step_frontend_run.sh "npx --no-install vitest run --coverage"
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: bash scripts/ci/vitest_incremental.sh
    - name: Job duration summary
      if: always()
      shell: sh
@@ -419,6 +568,196 @@ jobs:
        [ -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

+
+  build-pr:
+    name: PR Build ${{ matrix.service_display }} Image
+    runs-on: runtime-builder
+    timeout-minutes: ${{ matrix.timeout }}
+    if: github.event_name == 'pull_request'
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - service: api
+          service_display: API
+          dockerfile: infra/docker/api.Dockerfile
+          image_name: xiaoxia-saas-api
+          cache_name: api-cache
+          timeout: 30
+        - service: worker
+          service_display: Worker
+          dockerfile: infra/docker/worker.Dockerfile
+          image_name: xiaoxia-saas-worker
+          cache_name: worker-cache
+          timeout: 40
+        - service: web
+          service_display: Web
+          dockerfile: infra/docker/web.Dockerfile
+          image_name: xiaoxia-saas-web
+          cache_name: web-cache
+          timeout: 30
+    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: Docker login to Registry (for cache read)
+      shell: sh
+      env:
+        ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+        ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+        GITEA_REGISTRY_USER: xiaoxia
+        GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+      run: |
+        set -eu
+        for i in 1 2 3; do
+          echo "Docker login attempt $i/3"
+          if printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin              && docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"; then
+            echo "Docker login successful"
+            break
+          fi
+          echo "Docker login failed ($i/3), retrying in 5s..."
+          sleep 5
+        done
+    - name: Pre-build worker base images (fallback if not exist)
+      if: matrix.service == 'worker'
+      id: prebuild
+      shell: sh
+      run: |
+        set -eu
+        REGISTRY="git.xiaoxiajianji.com/xiaoxia-saas"
+        BASE_BUILDER="${REGISTRY}/worker-base-builder:latest"
+        BASE_RUNTIME="${REGISTRY}/worker-base-runtime:latest"
+        
+        # 尝试拉取基础镜像
+        echo "检查基础镜像..."
+        if docker pull "$BASE_BUILDER" 2>/dev/null && docker pull "$BASE_RUNTIME" 2>/dev/null; then
+          echo "基础镜像已存在，使用远程镜像"
+          echo "fallback=false" >> $GITHUB_OUTPUT
+        else
+          echo "基础镜像不存在，本地构建（fallback模式）..."
+          
+          # 构建builder基础镜像
+          echo "构建 worker-base-builder..."
+          # 用buildx docker-container驱动构建（兼容DooD模式：普通docker build看不到容器内文件）
+          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"
+          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
+            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
+          
+          # 构建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
+          
+          echo "fallback=true" >> $GITHUB_OUTPUT
+          echo "基础镜像本地构建完成"
+        fi
+
+    - name: Build PR image (verify only, no push)
+      shell: sh
+      run: |
+        set -eu
+        REGISTRY="xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji"
+        IMAGE_TAG="${REGISTRY}/${{ matrix.image_name }}:pr-${GITHUB_SHA}"
+        CACHE_REF="${REGISTRY}/${{ matrix.cache_name }}:develop"
+
+        EXTRA_BUILD_ARGS="APP_VERSION=\"${GITHUB_SHA}\""
+        if [ "${{ matrix.service }}" = "web" ]; then
+          EXTRA_BUILD_ARGS="$EXTRA_BUILD_ARGS NGINX_CONF=infra/docker/nginx-staging.conf"
+        fi
+
+        # Worker fallback模式：基础镜像本地已构建，用普通docker build绕过buildx
+        if [ "${{ matrix.service }}" = "worker" ] && [ "${{ steps.prebuild.outputs.fallback }}" = "true" ]; then
+          echo "Fallback模式：用普通docker build（基础镜像本地已构建）"
+          BUILD_ARG_STR=""
+          for arg in $EXTRA_BUILD_ARGS; do
+            BUILD_ARG_STR="$BUILD_ARG_STR --build-arg $arg"
+          done
+          docker build -f ${{ matrix.dockerfile }} -t "${IMAGE_TAG}" $BUILD_ARG_STR .
+          echo "Fallback PR Build successful"
+          exit 0
+        fi
+
+        NO_CACHE_FLAG=""
+        for i in 1 2 3; do
+          echo "PR Build attempt $i/3"
+          if bash scripts/ci/docker_build_only.sh $NO_CACHE_FLAG ${{ matrix.dockerfile }} "${IMAGE_TAG}" "${CACHE_REF}" $EXTRA_BUILD_ARGS; then
+            echo "PR Build successful"
+            break
+          fi
+          echo "PR Build failed (attempt $i/3)"
+          [ $i -eq 3 ] && exit 1
+          sleep 10
+          if [ $i -eq 2 ]; then
+            NO_CACHE_FLAG="--no-cache"
+            echo "Next retry with --no-cache"
+          fi
+        done
+        echo
+        echo "${{ matrix.service_display }} PR build verified: ${IMAGE_TAG}"
+    - name: Cleanup buildx builder
+      if: always()
+      shell: sh
+      run: |
+        BUILDER_NAME="ci-pr-builder-${GITHUB_RUN_ID:-local}"
+        docker buildx rm "$BUILDER_NAME" 2>/dev/null || true
+        docker buildx prune -f 2>/dev/null || true
+        echo "Builder cleanup done"
+    - name: Job duration summary
+      if: always()
+      shell: sh
+      run: bash scripts/ci/step_timer_end.sh
+    - 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="PR Build ${{ matrix.service_display }} Image" 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
+
  build-staging:
    name: Build Staging ${{ matrix.service_display }} Image
    runs-on: runtime-builder
@@ -465,9 +804,16 @@ jobs:
        GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
      run: |
        set -eu
-        printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin
-        docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"
-        echo "Docker login successful"
+        # Docker login 带重试（网络波动时自动重试）
+        for i in 1 2 3; do
+          echo "=== Docker login 尝试 $i/3 ==="
+          if printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin              && docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"; then
+            echo "✅ Docker login successful"
+            break
+          fi
+          echo "❌ Docker login 失败（尝试 $i/3），5s 后重试..."
+          sleep 5
+        done
    - name: Setup cache strategy
      shell: sh
      run: |
@@ -526,6 +872,15 @@ jobs:

        echo
        echo "${{ matrix.service_display }} image pushed: ${IMAGE_TAG}"
+    - name: Cleanup buildx builder
+      if: always()
+      shell: sh
+      run: |
+        docker buildx rm ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB}-${{ matrix.cache_name }} 2>/dev/null || true
+        docker buildx rm ci-builder 2>/dev/null || true
+        docker buildx prune -f 2>/dev/null || true
+        echo "Builder cleanup done"
+
    - name: Job duration summary
      if: always()
      shell: sh
@@ -589,9 +944,16 @@ jobs:
        GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
      run: |
        set -eu
-        printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin
-        docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"
-        echo "Docker login successful"
+        # Docker login 带重试（网络波动时自动重试）
+        for i in 1 2 3; do
+          echo "=== Docker login 尝试 $i/3 ==="
+          if printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin              && docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"; then
+            echo "✅ Docker login successful"
+            break
+          fi
+          echo "❌ Docker login 失败（尝试 $i/3），5s 后重试..."
+          sleep 5
+        done
    - name: Install SSH client
      if: success()
      shell: sh
@@ -858,9 +1220,16 @@ jobs:
        GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
      run: |
        set -eu
-        printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin
-        docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"
-        echo "Docker login successful"
+        # Docker login 带重试（网络波动时自动重试）
+        for i in 1 2 3; do
+          echo "=== Docker login 尝试 $i/3 ==="
+          if printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin              && docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"; then
+            echo "✅ Docker login successful"
+            break
+          fi
+          echo "❌ Docker login 失败（尝试 $i/3），5s 后重试..."
+          sleep 5
+        done
    - name: Setup cache strategy
      shell: sh
      run: |
@@ -1187,5 +1556,4 @@ 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
@@ -21,6 +21,10 @@ jobs:
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
+        # 网络波动自动重试2次
+        retry:
+          max_attempts: 2
+          retry_on: error
      
      - name: Check CI trigger status for all open PRs
        env:
@@ -25,9 +25,21 @@ jobs:
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
+        # 网络波动自动重试2次
+        retry:
+          max_attempts: 2
+          retry_on: error

      - name: Install dependencies
        run: |
+          # 确保 python3-pip 可用（兼容不同基础镜像）
+          if ! python3 -m pip --version >/dev/null 2>&1; then
+            apt-get update -qq && apt-get install -y -qq python3-pip python3-venv >/dev/null 2>&1
+          fi
+          # 部分镜像 ensurepip 方式兜底
+          if ! python3 -m pip --version >/dev/null 2>&1; then
+            python3 -m ensurepip --upgrade 2>/dev/null || curl -sS https://bootstrap.pypa.io/get-pip.py | python3
+          fi
          python3 -m pip install --upgrade pip
          python3 -m pip install requests

@@ -64,3 +76,4 @@ jobs:
          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
+
@@ -0,0 +1,56 @@
+name: PR Auto Scan
+# 定时扫描所有open PR，对CI全绿的触发审批/合并
+# 作为短作业模式的兜底，防止事件驱动遗漏
+on:
+  schedule:
+    - cron: "*/5 * * * *"  # 每5分钟扫描一次
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  auto-scan:
+    name: Auto Scan Open PRs
+    runs-on: ci-check
+    timeout-minutes: 5
+    if: github.repository == '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/pr_auto_scan.py?ref=develop"             -o /tmp/pr_auto_scan.py
+          python3 /tmp/pr_auto_scan.py --help > /dev/null 2>&1 || {
+            # fallback: checkout
+            echo "使用checkout方式"
+            curl -sH "Authorization: token $GITHUB_TOKEN"               "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=develop"               | bash
+          }
+
+      - name: Scan and auto process PRs
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          REVIEW_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+          MERGE_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+        run: |
+          set -eu
+          echo "=== 扫描所有open PR并自动处理 ==="
+          echo "时间: $(date)"
+          echo
+
+          python3 /tmp/pr_auto_scan.py             --token "$REVIEW_TOKEN"             --repo "$GITHUB_REPOSITORY"             --base develop             --approve             --merge             --dry-run false
+
+          echo ""
+          echo "✅ 扫描完成"
+
+      - name: Report CI trace
+        if: always()
+        shell: sh
+        env:
+          AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+        run: |
+          STATUS="ok"
+          [ ${{ job.status }} = "success" ] || STATUS="error"
+          python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "" || true
@@ -3,6 +3,7 @@ name: PR Automation
 on:
  pull_request:
    types: [synchronize, opened, ready_for_review, review_requested]
+  workflow_dispatch:

 permissions:
  contents: read
@@ -12,7 +13,7 @@ jobs:
    name: Auto Approve on CI Green
    runs-on: ci-check
    if: github.event_name == 'pull_request' && !github.event.pull_request.draft
-    timeout-minutes: 20
+    timeout-minutes: 3  # 长等待模式：等CI全绿后自动合并，不遗漏任何PR
    steps:
      - name: Checkout code
        shell: sh
@@ -21,6 +22,15 @@ jobs:
        run: |
          curl -sH "Authorization: token $GITHUB_TOKEN"             "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}"             | bash

+      - name: "🔍 脚本语法自检"
+        shell: bash
+        run: |
+          ERROR=0
+          for f in scripts/ci/*.sh; do [ -f "$f" ] && bash -n "$f" 2>&1 || ERROR=$((ERROR+1)); done
+          for f in scripts/ci/*.py; do [ -f "$f" ] && python3 -m py_compile "$f" 2>&1 || ERROR=$((ERROR+1)); done
+          if [ "$ERROR" -ne 0 ]; then echo "❌ 语法自检失败 ($ERROR个)"; exit 1; fi
+          echo "✅ 脚本语法自检通过"
+
      - name: Auto approve when CI passes
        shell: bash
        env:
@@ -29,151 +39,7 @@ jobs:
          PR_NUMBER: ${{ github.event.pull_request.number }}
          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
-          set -eu
-
-          echo "PR #${PR_NUMBER} - 检查CI状态并自动审批"
-
-          # 检查是否纯前端改动
-          API_URL="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?limit=300"
-          FILES=$(curl -s -H "Authorization: token ${GITHUB_TOKEN}" "$API_URL" | python3 -c "import sys,json; [print(f['filename']) for f in json.load(sys.stdin)]")
-          FRONTEND_COUNT=$(echo "$FILES" | grep -c '^apps/web/' || true)
-          BACKEND_COUNT=$(echo "$FILES" | grep -cv '^apps/web/' || true)
-          TOTAL=$(echo "$FILES" | grep -cv '^$' || true)
-          echo "变更文件: ${TOTAL} 个 (前端: ${FRONTEND_COUNT}, 后端/公共: ${BACKEND_COUNT})"
-
-          if [ "$BACKEND_COUNT" = "0" ] && [ "$FRONTEND_COUNT" -gt "0" ]; then
-            SKIP_BACKEND=true
-            echo "✅ 纯前端改动，只检查Frontend Lint"
-          else
-            SKIP_BACKEND=false
-            echo "🔧 包含后端/公共变更，检查全部CI"
-          fi
-
-          # 定义需要检查的context
-          if [ "$SKIP_BACKEND" = "true" ]; then
-            CONTEXTS=("CI/CD Pipeline / Frontend Lint (pull_request)")
-          else
-            CONTEXTS=(
-              "CI/CD Pipeline / Validate Code Quality And Tests (pull_request)"
-              "CI/CD Pipeline / Frontend Lint (pull_request)"
-            )
-          fi
-
-          echo "需要通过的CI检查: ${#CONTEXTS[@]} 项（与分支保护required门禁一致）"
-          for ctx in "${CONTEXTS[@]}"; do
-            echo "  - $ctx"
-          done
-          echo
-
-          # 初始等待30秒，给CI启动写status的时间
-          echo "等待30秒让CI启动..."
-          sleep 30
-
-          # 轮询等待，最多20分钟（120次x10秒）
-          for attempt in $(seq 1 120); do
-            ALL_SUCCESS=true
-            ANY_FAILED=false
-            ANY_PENDING=false
-
-            echo "--- 第${attempt}次检查 ($(date '+%H:%M:%S')) ---"
-
-            # 调用辅助脚本检查每个context状态
-            for ctx in "${CONTEXTS[@]}"; do
-              STATE=$(python3 scripts/check_ci_status.py "$GITHUB_TOKEN" "$GITHUB_REPOSITORY" "$PR_HEAD_SHA" "$ctx")
-              echo "  $ctx: $STATE"
-
-              if [ "$STATE" != "success" ]; then
-                ALL_SUCCESS=false
-              fi
-              if [ "$STATE" = "failure" ] || [ "$STATE" = "error" ]; then
-                ANY_FAILED=true
-              fi
-              if [ "$STATE" = "pending" ] || [ "$STATE" = "null" ]; then
-                ANY_PENDING=true
-              fi
-            done
-
-            if [ "$ALL_SUCCESS" = "true" ]; then
-              echo
-              echo "✅ 所有CI检查通过，自动审批 PR #${PR_NUMBER}"
-
-              # 检查是否已有审批
-              EXISTING=$(curl -s -H "Authorization: token ${REVIEW_TOKEN}" \
-                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews" \
-                | python3 -c "import sys,json; reviews=json.load(sys.stdin); print('yes' if any(r.get('state')=='APPROVED' for r in reviews) else 'no')")
-
-              if [ "$EXISTING" = "yes" ]; then
-                echo "ℹ️  PR #${PR_NUMBER} 已有审批，跳过"
-                exit 0
-              fi
-
-              # 第一步：创建PENDING review
-              echo "创建review..."
-              REVIEW_CREATE=$(curl -s -X POST \
-                -H "Authorization: token ${REVIEW_TOKEN}" \
-                -H "Content-Type: application/json" \
-                -d '{"event": "PENDING", "body": "CI全绿，自动审批通过。"}' \
-                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews")
-              
-              REVIEW_ID=$(echo "$REVIEW_CREATE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))")
-              REVIEW_STATE=$(echo "$REVIEW_CREATE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('state',''))")
-              echo "创建结果: id=$REVIEW_ID state=$REVIEW_STATE"
-
-              if [ -z "$REVIEW_ID" ]; then
-                echo "❌ 创建review失败"
-                echo "$REVIEW_CREATE"
-                exit 1
-              fi
-
-              if [ "$REVIEW_STATE" = "APPROVED" ]; then
-                echo "✅ 自动审批成功（直接创建为APPROVED）"
-                exit 0
-              fi
-
-              # 第二步：submit review为APPROVED
-              echo "提交review审批..."
-              SUBMIT_CODE=$(curl -s -o /tmp/submit_resp.json -w "%{http_code}" \
-                -X POST \
-                -H "Authorization: token ${REVIEW_TOKEN}" \
-                -H "Content-Type: application/json" \
-                -d '{"event": "APPROVED", "body": "CI全绿，自动审批通过。"}' \
-                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews/${REVIEW_ID}")
-              
-              echo "提交API HTTP状态: $SUBMIT_CODE"
-              cat /tmp/submit_resp.json 2>/dev/null || true
-              echo
-
-              if [ "$SUBMIT_CODE" = "200" ] || [ "$SUBMIT_CODE" = "201" ]; then
-                FINAL_STATE=$(python3 -c "import json; print(json.load(open('/tmp/submit_resp.json')).get('state',''))" 2>/dev/null || echo "?")
-                echo "✅ 自动审批成功 (state: $FINAL_STATE)"
-                exit 0
-              else
-                echo "❌ 提交审批失败"
-                exit 1
-              fi
-            fi
-
-            # 还有CI在跑 → 继续等
-            if [ "$ANY_PENDING" = "true" ]; then
-              echo "⏳ CI仍在运行中，继续等待（第${attempt}/120次轮询）..."
-              sleep 10
-              continue
-            fi
-
-            # 所有CI都跑完了但有失败 → 退出
-            if [ "$ANY_FAILED" = "true" ]; then
-              echo
-              echo "❌ CI检查有失败项，不自动审批"
-              exit 0
-            fi
-
-            sleep 10
-          done
-
-          echo
-          echo "⏰ 等待超时（20分钟），CI尚未全部完成"
-          exit 0
-
+          bash scripts/ci/auto_approve.sh
      - name: Report CI trace
        if: always()
        shell: sh
@@ -190,7 +56,7 @@ jobs:
    name: Auto Merge on CI Green + Approved
    runs-on: ci-check
    if: github.event_name == 'pull_request' && !github.event.pull_request.draft && github.event.pull_request.base.ref == 'develop'
-    timeout-minutes: 30
+    timeout-minutes: 45  # 长等待模式：等CI全绿后自动合并，不遗漏任何PR
    steps:
      - name: Checkout code
        shell: sh
@@ -199,6 +65,31 @@ jobs:
        run: |
          curl -sH "Authorization: token $GITHUB_TOKEN"             "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}"             | bash

+      - name: "🔍 脚本语法自检（防止脚本bug导致所有PR挂掉）"
+        shell: bash
+        run: |
+          echo "=== CI脚本语法自检 ==="
+          ERROR=0
+          for f in scripts/ci/*.sh; do
+            [ -f "$f" ] || continue
+            if ! bash -n "$f" 2>&1; then
+              echo "FAIL: $f"
+              ERROR=1
+            fi
+          done
+          for f in scripts/ci/*.py; do
+            [ -f "$f" ] || continue
+            if ! python3 -m py_compile "$f" 2>&1; then
+              echo "FAIL: $f"
+              ERROR=1
+            fi
+          done
+          if [ "$ERROR" -ne 0 ]; then
+            echo "❌ 脚本语法自检失败"
+            exit 1
+          fi
+          echo "✅ 所有CI脚本语法自检通过"
+
      - name: Auto merge when CI passes and approved
        shell: bash
        env:
@@ -208,150 +99,7 @@ jobs:
          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          BASE_REF: ${{ github.event.pull_request.base.ref }}
        run: |
-          set -eu
-
-          echo "PR #${PR_NUMBER} - 检查CI状态+审批并自动合并到${BASE_REF}"
-          echo
-
-          # 只合develop分支
-          if [ "$BASE_REF" != "develop" ]; then
-            echo "Skip: 目标分支不是develop"
-            exit 0
-          fi
-
-          # 判断是否纯前端改动
-          FILES=$(curl -s -H "Authorization: token ${GITHUB_TOKEN}" \
-            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?limit=300" \
-            | python3 -c "import sys,json; [print(f['filename']) for f in json.load(sys.stdin)]")
-          TOTAL=$(echo "$FILES" | grep -cv '^$' || true)
-          FRONTEND_COUNT=$(echo "$FILES" | grep -c '^apps/web/' || true)
-          BACKEND_COUNT=$((TOTAL - FRONTEND_COUNT))
-          echo "变更文件: ${TOTAL} 个 (前端: ${FRONTEND_COUNT}, 后端/公共: ${BACKEND_COUNT})"
-
-          if [ "$BACKEND_COUNT" = "0" ] && [ "$FRONTEND_COUNT" -gt "0" ]; then
-            CONTEXTS=("CI/CD Pipeline / Frontend Lint (pull_request)")
-            echo "纯前端改动，只检查Frontend Lint"
-          else
-            CONTEXTS=(
-              "CI/CD Pipeline / Validate Code Quality And Tests (pull_request)"
-              "CI/CD Pipeline / Frontend Lint (pull_request)"
-            )
-            echo "检查required门禁（与分支保护一致）"
-          fi
-          echo
-
-          # 初始等待30秒，给CI启动写status的时间
-          echo "等待30秒让CI启动..."
-          sleep 30
-
-          # 405连续计数器
-          MERGE_405_COUNT=0
-          MAX_405_RETRIES=10
-
-          # 轮询等待，最多30分钟（180次x10秒）
-          for attempt in $(seq 1 180); do
-            ALL_SUCCESS=true
-            ANY_FAILED=false
-            ANY_PENDING=false
-
-            echo "--- 第${attempt}次检查 ($(date '+%H:%M:%S')) ---"
-
-            # 检查CI状态
-            for ctx in "${CONTEXTS[@]}"; do
-              STATE=$(python3 scripts/check_ci_status.py "$GITHUB_TOKEN" "$GITHUB_REPOSITORY" "$PR_HEAD_SHA" "$ctx")
-              echo "  CI: ${ctx##*/}: $STATE"
-              if [ "$STATE" != "success" ]; then
-                ALL_SUCCESS=false
-              fi
-              if [ "$STATE" = "failure" ] || [ "$STATE" = "error" ]; then
-                ANY_FAILED=true
-              fi
-              if [ "$STATE" = "pending" ]; then
-                ANY_PENDING=true
-              fi
-            done
-
-            # 检查审批状态
-            APPROVAL_RESULT=$(python3 scripts/check_pr_approval.py "$MERGE_TOKEN" "$GITHUB_REPOSITORY" "$PR_NUMBER" 1)
-            echo "  审批: $APPROVAL_RESULT"
-            HAS_APPROVAL=false
-            if echo "$APPROVAL_RESULT" | grep -q '^approved'; then
-              HAS_APPROVAL=true
-            fi
-
-            # 全部满足 → 合并
-            if [ "$ALL_SUCCESS" = "true" ] && [ "$HAS_APPROVAL" = "true" ]; then
-              echo
-              echo "CI全绿 + 审批通过，执行自动合并"
-              echo "等待60秒冷却，给Gitea内部状态同步时间..."
-              sleep 60
-
-              # 幂等检查：PR是否还是open
-              PR_STATE=$(curl -s -H "Authorization: token ${MERGE_TOKEN}" \
-                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" \
-                | python3 -c "import sys,json; print(json.load(sys.stdin).get('state',''))")
-
-              if [ "$PR_STATE" != "open" ]; then
-                echo "PR状态为 ${PR_STATE}，无需合并"
-                exit 0
-              fi
-
-              # 执行squash merge
-              HTTP_CODE=$(curl -s -o /tmp/merge_resp.json -w "%{http_code}" \
-                -X POST \
-                -H "Authorization: token ${MERGE_TOKEN}" \
-                -H "Content-Type: application/json" \
-                -d '{"do":"squash","merge_title_field":"","merge_message_field":"","delete_branch_after_merge":true,"force_merge":false}' \
-                "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/merge")
-
-              echo "合并API HTTP状态: $HTTP_CODE"
-
-              if [ "$HTTP_CODE" = "200" ]; then
-                echo "自动合并成功"
-                exit 0
-              elif [ "$HTTP_CODE" = "405" ]; then
-                MERGE_405_COUNT=$((MERGE_405_COUNT + 1))
-                echo "⚠️  合并返回405（第${MERGE_405_COUNT}次），可能CI状态尚未同步或有未解决的门禁，继续等待重试..."
-                cat /tmp/merge_resp.json 2>/dev/null || true
-                echo
-                if [ "$MERGE_405_COUNT" -ge "$MAX_405_RETRIES" ]; then
-                  echo "⚠️  连续${MAX_405_RETRIES}次合并返回405，放弃自动合并（需人工确认，非代码问题）"
-                  curl -s -X POST \
-                    -H "Authorization: token ${MERGE_TOKEN}" \
-                    -H "Content-Type: application/json" \
-                    -d '{"body": "Auto merge skipped after multiple 405 errors: PR may have conflicts or unresolved checks. Please review manually. This is not a CI failure."}' \
-                    "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" > /dev/null 2>&1 || true
-                  exit 0
-                fi
-                sleep 30
-                continue
-              else
-                echo "自动合并失败 (HTTP $HTTP_CODE)"
-                cat /tmp/merge_resp.json 2>/dev/null || true
-                curl -s -X POST \
-                  -H "Authorization: token ${MERGE_TOKEN}" \
-                  -H "Content-Type: application/json" \
-                  -d "{\"body\": \"Auto merge failed (HTTP ${HTTP_CODE}), please check manually.\"}" \
-                  "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" > /dev/null 2>&1 || true
-                exit 1
-              fi
-            else
-              # 本轮不满足合并条件，重置405计数器
-              MERGE_405_COUNT=0
-            fi
-
-            if [ "$ANY_FAILED" = "true" ]; then
-              echo
-              echo "CI有失败项，不自动合并"
-              exit 0
-            fi
-
-            sleep 10
-          done
-
-          echo
-          echo "等待超时（30分钟）"
-          exit 0
+          bash scripts/ci/auto_merge.sh
      - name: Report CI trace
        if: always()
        shell: sh
@@ -0,0 +1,103 @@
+name: Worker Base Image Build
+
+on:
+  push:
+    branches:
+      - develop
+      - main
+    paths:
+      - 'requirements-base.txt'
+      - 'requirements-worker.txt'
+      - 'infra/docker/worker-base-builder.Dockerfile'
+      - 'infra/docker/worker-base-runtime.Dockerfile'
+  workflow_dispatch:  # 支持手动触发
+
+jobs:
+  build-worker-base:
+    name: Build Worker Base Images
+    runs-on: runtime-builder
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - name: builder
+          dockerfile: infra/docker/worker-base-builder.Dockerfile
+          image_name: worker-base-builder
+          cache_name: worker-base-builder-cache
+        - name: runtime
+          dockerfile: infra/docker/worker-base-runtime.Dockerfile
+          image_name: worker-base-runtime
+          cache_name: worker-base-runtime-cache
+    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: Docker login to Registry
+      shell: sh
+      env:
+        ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+        ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+        GITEA_REGISTRY_USER: xiaoxia
+        GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+      run: |
+        set -eu
+        for i in 1 2 3; do
+          echo "=== Docker login 尝试 $i/3 ==="
+          if printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin              && docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"; then
+            echo "✅ Docker login successful"
+            break
+          fi
+          echo "❌ Docker login 失败（尝试 $i/3），5s 后重试..."
+          sleep 5
+        done
+
+    - name: Setup buildx builder
+      shell: sh
+      run: |
+        set -eu
+        BUILDER_NAME="ci-builder-${GITHUB_RUN_ID}-${{ matrix.name }}"
+        if ! docker buildx inspect "$BUILDER_NAME" > /dev/null 2>&1; then
+          docker buildx create --use --name "$BUILDER_NAME" --driver docker-container
+          echo "Created $BUILDER_NAME"
+        else
+          docker buildx use "$BUILDER_NAME"
+          echo "Using existing $BUILDER_NAME"
+        fi
+        docker buildx inspect --bootstrap
+
+    - name: Build and push base image
+      shell: sh
+      run: |
+        set -eu
+        REGISTRY="xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji"
+        IMAGE_TAG="${REGISTRY}/${{ matrix.image_name }}:latest"
+        SAFE_REF_NAME=$(echo "${GITHUB_REF_NAME}" | tr '/' '-')
+        CACHE_REF="${REGISTRY}/${{ matrix.cache_name }}:${SAFE_REF_NAME}"
+        
+        echo "=== Building ${{ matrix.name }} base image ==="
+        echo "Image: ${IMAGE_TAG}"
+        echo "Cache: ${CACHE_REF}"
+        
+        # 用通用构建脚本
+        bash scripts/ci/docker_build_push.sh           ${{ matrix.dockerfile }}           "${IMAGE_TAG}"           "${CACHE_REF}"
+        
+        # 同时推送到 Gitea Packages 作为备份（可选）
+        GITEA_IMAGE="git.xiaoxiajianji.com/xiaoxia-saas/${{ matrix.image_name }}:latest"
+        docker tag "${IMAGE_TAG}" "${GITEA_IMAGE}"
+        docker push "${GITEA_IMAGE}" || echo "Gitea Packages push failed (non-fatal)"
+        
+        echo ""
+        echo "✅ ${{ matrix.name }} base image built and pushed"
+
+    - name: Cleanup buildx builder
+      if: always()
+      shell: sh
+      run: |
+        docker buildx rm "ci-builder-${GITHUB_RUN_ID}-${{ matrix.name }}" 2>/dev/null || true
+        docker buildx prune -f 2>/dev/null || true
+        echo "Builder cleanup done"
@@ -0,0 +1,37 @@
+"""Phase 3 - 清理 EditPlan 表冗余字段
+
+Revision ID: 048
+Revises: 047
+Create Date: 2026-07-21
+
+Changes:
+1. 删除 edit_plans.result_count 字段（剪辑计划独立功能遗留，模板草稿不用，
+   生成结果数由 generation_tasks.result_count 承载）
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "048_cleanup_result_count"
+down_revision = "047_template_versioning"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # 删除 result_count 字段（剪辑计划独立功能遗留字段）
+    op.drop_column("edit_plans", "result_count")
+
+
+def downgrade() -> None:
+    # 回滚：恢复 result_count 字段，默认值 0
+    op.add_column(
+        "edit_plans",
+        sa.Column(
+            "result_count",
+            sa.Integer,
+            nullable=False,
+            server_default="0",
+        ),
+    )
@@ -0,0 +1,97 @@
+"""#558 - 微信登录：手机号绑定字段 + 验证码表
+
+Revision ID: 049
+Revises: 048
+Create Date: 2026-07-21
+
+Changes:
+1. users 表新增 phone_verified / binding_completed_at 字段（phone 字段已在 029 中添加）
+2. users 表 phone 字段添加唯一索引（幂等）
+3. 新建 verification_codes 表（统一管理邮箱+手机验证码）
+"""
+
+import sqlalchemy as sa
+
+from alembic import context, op
+
+revision = "049_wechat_login_phone"
+down_revision = "048_cleanup_result_count"
+branch_labels = None
+depends_on = None
+
+
+def _column_exists(table: str, column: str) -> bool:
+    """检查列是否已存在。离线模式下返回 False。"""
+    if context.is_offline_mode():
+        return False
+    conn = op.get_bind()
+    result = conn.execute(
+        sa.text("SELECT 1 FROM information_schema.columns " "WHERE table_name = :table AND column_name = :column"),
+        {"table": table, "column": column},
+    )
+    return result.first() is not None
+
+
+def _index_exists(index_name: str) -> bool:
+    """检查索引是否已存在。离线模式下返回 False。"""
+    if context.is_offline_mode():
+        return False
+    conn = op.get_bind()
+    result = conn.execute(
+        sa.text("SELECT 1 FROM pg_indexes WHERE indexname = :index_name"),
+        {"index_name": index_name},
+    )
+    return result.first() is not None
+
+
+def upgrade() -> None:
+    # 1. users 表新增手机号验证状态字段（幂等）
+    if not _column_exists("users", "phone_verified"):
+        op.add_column(
+            "users",
+            sa.Column(
+                "phone_verified",
+                sa.Boolean,
+                nullable=False,
+                server_default=sa.text("false"),
+            ),
+        )
+
+    if not _column_exists("users", "binding_completed_at"):
+        op.add_column(
+            "users",
+            sa.Column("binding_completed_at", sa.DateTime, nullable=True),
+        )
+
+    # 2. phone 字段唯一索引（幂等 - 029 加了字段但没加索引）
+    if not _index_exists("ix_users_phone"):
+        op.create_index("ix_users_phone", "users", ["phone"], unique=True)
+
+    # 3. verification_codes 表
+    op.create_table(
+        "verification_codes",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("recipient", sa.String(255), nullable=False, index=True),
+        sa.Column("code", sa.String(10), nullable=False),
+        sa.Column("code_type", sa.String(32), nullable=False, index=True),
+        sa.Column("expires_at", sa.DateTime, nullable=False),
+        sa.Column("used_at", sa.DateTime, nullable=True),
+        sa.Column("attempts", sa.Integer, nullable=False, server_default="0"),
+        sa.Column("created_at", sa.DateTime, nullable=False),
+        sa.Index(
+            "ix_verification_recipient_type",
+            "recipient",
+            "code_type",
+            "created_at",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("verification_codes")
+    if _index_exists("ix_users_phone"):
+        op.drop_index("ix_users_phone", table_name="users")
+    if _column_exists("users", "binding_completed_at"):
+        op.drop_column("users", "binding_completed_at")
+    if _column_exists("users", "phone_verified"):
+        op.drop_column("users", "phone_verified")
@@ -0,0 +1,48 @@
+"""#P3-2 - 视频分享表 video_shares
+
+Revision ID: 050
+Revises: 049
+Create Date: 2026-07-22
+
+Changes:
+1. 新建 video_shares 表，支持视频匿名分享链接
+2. share_token 唯一索引，用于公开分享URL
+3. 支持密码保护、有效期、浏览/下载计数
+"""
+
+import sqlalchemy as sa
+
+from alembic import context, op
+
+revision = "050_video_shares"
+down_revision = "049_wechat_login_phone"
+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 to_regclass('public.video_shares')"))
+        if result.scalar() is not None:
+            return
+
+    op.create_table(
+        "video_shares",
+        sa.Column("id", sa.String(32), primary_key=True),
+        sa.Column("video_id", sa.String(32), nullable=False, index=True),
+        sa.Column("user_id", sa.String(32), nullable=False, index=True),
+        sa.Column("share_token", sa.String(16), nullable=False, unique=True),
+        sa.Column("password_hash", sa.String(255), nullable=True),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("view_count", sa.Integer, nullable=False, server_default="0"),
+        sa.Column("download_count", sa.Integer, nullable=False, server_default="0"),
+        sa.Column("is_active", sa.Boolean, nullable=False, server_default=sa.true()),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("video_shares")
@@ -0,0 +1,53 @@
+"""#632 - 一键生成输出分辨率可配置
+
+Revision ID: 051
+Revises: 050
+Create Date: 2026-07-23
+
+Changes:
+1. generation_tasks 表新增 resolution 字段，存储用户指定的输出分辨率（如 "1280x720"）
+2. 为空时使用默认值（1280x720）
+"""
+
+import sqlalchemy as sa
+
+from alembic import context, op
+
+revision = "051_generation_task_resolution"
+down_revision = "050_video_shares"
+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 = 'resolution'"
+            )
+        )
+        if result.scalar() is not None:
+            return
+
+    op.add_column(
+        "generation_tasks",
+        sa.Column("resolution", sa.String(20), nullable=False, server_default=""),
+    )
+
+
+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 = 'resolution'"
+            )
+        )
+        if result.scalar() is None:
+            return
+
+    op.drop_column("generation_tasks", "resolution")
@@ -5,13 +5,14 @@ from app.api.routes.auth import router as auth_router
 from app.api.routes.chunked_upload import router as chunked_upload_router
 from app.api.routes.classification_jobs import router as classification_jobs_router
 from app.api.routes.duplication import router as duplication_router
-from app.api.routes.edit_plans import router as edit_plans_router
 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
 from app.api.routes.subscription import router as subscription_router
 from app.api.routes.tags import router as tags_router
 from app.api.routes.task_center import router as task_center_router
@@ -105,6 +106,10 @@ api_router.include_router(
    videos_router,
    tags=["VideoCenter"],
 )
+api_router.include_router(
+    share_router,
+    tags=["Share"],
+)
 api_router.include_router(
    duplication_router,
    prefix="/duplication",
@@ -125,16 +130,16 @@ api_router.include_router(
    prefix="/templates/{template_id}/editor",
    tags=["TemplateEditor"],
 )
-api_router.include_router(
-    edit_plans_router,
-    prefix="/edit-plans",
-    tags=["EditPlan"],
-)
 api_router.include_router(
    tts_router,
    prefix="/tts",
    tags=["TTS"],
 )
+api_router.include_router(
+    ai_router,
+    prefix="/ai",
+    tags=["AI"],
+)
 api_router.include_router(
    feature_flags_router,
    tags=["Internal"],
@@ -139,26 +139,3 @@ def format_utc_datetime(dt: datetime | None) -> str:
    if dt.tzinfo is None:
        return dt.isoformat() + "Z"
    return dt.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
-
-
-# ── Deprecated API 标记 ──────────────────────────────────────────────────────
-
-
-import logging as _logging
-
-from fastapi import Request as _Request
-
-_deprecated_logger = _logging.getLogger(__name__)
-
-
-def deprecated_edit_plans_api(request: _Request) -> None:
-    """标记 /edit-plans/* 系列 API 为废弃，打 warning 日志。
-
-    Phase 2 模板编辑器收敛后，所有剪辑计划 API 迁移到 /templates/{id}/editor/*。
-    旧路径保留 2 个版本周期兼容，之后会下线。
-    """
-    _deprecated_logger.warning(
-        "Deprecated API called: %s %s. Use /templates/{template_id}/editor/* instead.",
-        request.method,
-        request.url.path,
-    )
@@ -0,0 +1,136 @@
+"""AI 相关接口 — 智能标题、智能素材匹配等.
+
+基于豆包大模型的 AI 能力接口，未配置 API Key 时自动降级为本地模拟。
+"""
+
+from __future__ import annotations
+
+from typing import List, Literal, Optional
+
+from app.services.ai_service import TITLE_STYLES, generate_smart_titles, semantic_match_assets
+from fastapi import APIRouter
+from pydantic import BaseModel, Field
+
+router = APIRouter()
+
+
+# ── 请求/响应模型 ────────────────────────────────────────────────────────────
+
+
+class GenerateTitlesRequest(BaseModel):
+    """智能标题生成请求."""
+
+    description: str = Field(..., min_length=1, max_length=500, description="视频内容描述")
+    style: Literal["viral", "emotional", "informative"] = Field(
+        default="viral",
+        description="标题风格：viral爆款 / emotional情感 / informative信息",
+    )
+    count: int = Field(default=5, ge=3, le=10, description="生成数量，3-10个")
+
+
+class GenerateTitlesResponse(BaseModel):
+    """智能标题生成响应."""
+
+    titles: List[str] = Field(..., description="生成的标题列表")
+    style: str = Field(..., description="实际使用的风格")
+    source: str = Field(..., description="来源：doubao 或 fallback")
+    description: str = Field(..., description="原始描述")
+
+
+class TitleStyleInfo(BaseModel):
+    """标题风格信息."""
+
+    key: str
+    name: str
+    description: str
+
+
+# ── 素材语义匹配 ────────────────────────────────────────────────────────────
+
+
+class AssetMatchItem(BaseModel):
+    """待匹配素材项."""
+
+    id: str = Field(..., description="素材ID")
+    name: str = Field(default="", description="素材名称")
+    tags: List[str] = Field(default_factory=list, description="标签列表")
+    description: str = Field(default="", description="素材描述")
+
+
+class SemanticMatchRequest(BaseModel):
+    """语义匹配请求."""
+
+    description: str = Field(..., min_length=1, max_length=500, description="目标视频内容描述")
+    assets: List[AssetMatchItem] = Field(..., min_length=1, max_length=100, description="待匹配素材列表")
+    top_k: int = Field(default=0, ge=0, le=100, description="返回前K个，0返回全部")
+
+
+class SemanticMatchResultItem(AssetMatchItem):
+    """匹配结果项."""
+
+    match_score: float = Field(..., description="匹配度评分 0-1")
+    match_reason: str = Field(..., description="匹配方式：doubao_semantic / fallback_keyword / fallback_default")
+
+
+class SemanticMatchResponse(BaseModel):
+    """语义匹配响应."""
+
+    matches: List[SemanticMatchResultItem] = Field(..., description="按匹配度降序排列的素材列表")
+    source: str = Field(..., description="来源：doubao / fallback")
+    description: str = Field(..., description="原始描述")
+    total: int = Field(..., description="输入素材总数")
+
+
+# ── 路由 ────────────────────────────────────────────────────────────────────
+
+
+@router.post("/titles/generate", response_model=GenerateTitlesResponse)
+def generate_titles(request: GenerateTitlesRequest):
+    """生成智能标题.
+
+    根据视频描述生成指定风格的标题，支持爆款、情感、信息三种风格。
+    未配置豆包 API Key 时自动降级为本地规则生成。
+    """
+    result = generate_smart_titles(
+        description=request.description,
+        style=request.style,
+        count=request.count,
+    )
+    return GenerateTitlesResponse(**result)
+
+
+@router.get("/titles/styles", response_model=List[TitleStyleInfo])
+def list_title_styles():
+    """获取支持的标题风格列表."""
+    return [
+        TitleStyleInfo(key=key, name=info["name"], description=info["description"])
+        for key, info in TITLE_STYLES.items()
+    ]
+
+
+@router.post("/assets/match", response_model=SemanticMatchResponse)
+def match_assets(request: SemanticMatchRequest):
+    """智能素材语义匹配.
+
+    根据用户描述，对素材列表做语义匹配并按匹配度排序。
+    未配置豆包 API Key 时自动降级为关键词匹配。
+
+    - 支持最多 100 个素材同时匹配
+    - 返回 match_score (0-1)，按降序排列
+    - top_k 可限制返回数量
+    """
+    # 转为 dict 传给服务层
+    assets_dict = [asset.model_dump() for asset in request.assets]
+
+    result = semantic_match_assets(
+        description=request.description,
+        assets=assets_dict,
+        top_k=request.top_k,
+    )
+
+    return SemanticMatchResponse(
+        matches=[SemanticMatchResultItem(**m) for m in result["matches"]],
+        source=result["source"],
+        description=result["description"],
+        total=result["total"],
+    )
@@ -81,6 +81,9 @@ class CurrentUserResponse(BaseModel):
    username: str
    display_name: str
    email_verified: bool
+    phone: str = ""
+    phone_verified: bool = False
+    binding_complete: bool = False


 class PasswordResetRequestModel(BaseModel):
@@ -259,12 +262,16 @@ async def get_current_user_info(
    authenticated_user: AuthenticatedUser = Depends(get_current_user),
 ) -> CurrentUserResponse:
    user = authenticated_user.user
+    binding_complete = user.phone_verified and user.email_verified and user.email and "@wechat.local" not in user.email
    return CurrentUserResponse(
        user_id=user.id,
        email=user.email,
        username=user.username,
        display_name=user.display_name,
        email_verified=user.email_verified,
+        phone=user.phone or "",
+        phone_verified=user.phone_verified,
+        binding_complete=binding_complete,
    )


@@ -380,3 +387,202 @@ async def wechat_sync(
        raise HTTPException(status_code=400, detail=error)

    return WechatSyncResponse(**response.to_dict())
+
+
+# ==================== 微信网页登录（OAuth） ====================
+
+
+class WechatAuthUrlResponse(BaseModel):
+    auth_url: str
+    state: str
+
+
+class WechatCallbackRequest(BaseModel):
+    code: str
+    state: str = ""
+
+
+class WechatLoginResponse(BaseModel):
+    access_token: str
+    refresh_token: str
+    user_id: str
+    display_name: str
+    avatar_url: str = ""
+    is_new_user: bool
+    binding_complete: bool
+    expires_in: int
+
+
+@router.get("/wechat/url", response_model=WechatAuthUrlResponse)
+async def get_wechat_auth_url() -> WechatAuthUrlResponse:
+    """获取微信扫码登录授权链接"""
+    from packages.application.auth.wechat_oauth_service import get_wechat_oauth_service
+
+    oauth_service = get_wechat_oauth_service()
+    auth_url, state = oauth_service.generate_auth_url()
+    return WechatAuthUrlResponse(auth_url=auth_url, state=state)
+
+
+@router.post("/wechat/callback", response_model=WechatLoginResponse)
+async def wechat_callback(
+    request: WechatCallbackRequest,
+    user_repository: UserRepository = Depends(get_user_repository),
+) -> WechatLoginResponse:
+    """微信登录回调处理"""
+    from packages.application.auth.wechat_oauth_service import get_wechat_oauth_service
+    from packages.application.auth.wechat_sync_use_case import WechatSyncRequest as SyncRequest
+    from packages.application.auth.wechat_sync_use_case import WechatSyncUseCase
+
+    # 1. 用 code 换微信用户信息
+    oauth_service = get_wechat_oauth_service()
+    wechat_user, err = oauth_service.handle_callback(request.code, request.state)
+    if err:
+        raise HTTPException(status_code=400, detail=err)
+
+    # 2. 同步登录/注册（复用 wechat-sync 逻辑）
+    use_case = WechatSyncUseCase(user_repository=user_repository)
+    sync_request = SyncRequest(
+        openid=wechat_user.openid,
+        unionid=wechat_user.unionid,
+        nickname=wechat_user.nickname,
+        avatar_url=wechat_user.avatar_url,
+        source="web",
+    )
+    response, err = use_case.execute(sync_request)
+    if err:
+        raise HTTPException(status_code=400, detail=err)
+
+    # 3. 判断绑定状态
+    user = user_repository.find_by_id(response.user_id)
+    binding_complete = False
+    if user:
+        binding_complete = (
+            user.phone_verified and user.email_verified and user.email and "@wechat.local" not in user.email
+        )
+
+    return WechatLoginResponse(
+        access_token=response.access_token,
+        refresh_token=response.refresh_token,
+        user_id=response.user_id,
+        display_name=response.nickname,
+        avatar_url=response.avatar_url or wechat_user.avatar_url,
+        is_new_user=response.is_new_user,
+        binding_complete=binding_complete,
+        expires_in=response.expires_in,
+    )
+
+
+# ==================== 验证码 & 绑定 ====================
+
+
+class SendVerificationCodeRequest(BaseModel):
+    target: str  # phone / email
+    value: str
+    purpose: str  # bind / login / reset_password
+
+
+class SendVerificationCodeResponse(BaseModel):
+    expires_in: int
+    resend_after: int
+
+
+class BindContactRequest(BaseModel):
+    phone: str = ""
+    phone_code: str = ""
+    email: str = ""
+    email_code: str = ""
+
+
+class BindContactResponse(BaseModel):
+    success: bool
+    user: dict
+
+
+@router.post("/send-verification-code", response_model=SendVerificationCodeResponse)
+async def send_verification_code(
+    request: SendVerificationCodeRequest,
+) -> SendVerificationCodeResponse:
+    """发送验证码（手机或邮箱）"""
+    from app.dependencies import get_db_session
+
+    from packages.adapters.sms.sms_service import get_sms_service
+    from packages.adapters.smtp import get_email_service
+    from packages.adapters.sqlalchemy_impl.verification_code_repository import (
+        SQLAlchemyVerificationCodeRepository,
+    )
+    from packages.application.auth.bind_contact_use_case import SendVerificationCodeRequest as UseCaseRequest
+    from packages.application.auth.bind_contact_use_case import (
+        SendVerificationCodeUseCase,
+    )
+    from packages.application.auth.verification_code_service import VerificationCodeService
+
+    db = next(get_db_session())
+    repo = SQLAlchemyVerificationCodeRepository(db)
+    vc_service = VerificationCodeService(repo=repo)
+    sms_service = get_sms_service()
+    email_service = get_email_service()
+
+    use_case = SendVerificationCodeUseCase(
+        verification_code_service=vc_service,
+        sms_service=sms_service,
+        email_service=email_service,
+    )
+    uc_request = UseCaseRequest(
+        target=request.target,
+        value=request.value,
+        purpose=request.purpose,
+    )
+    response, err = use_case.execute(uc_request)
+    if err:
+        raise HTTPException(status_code=400, detail=err)
+
+    return SendVerificationCodeResponse(
+        expires_in=response.expires_in,
+        resend_after=response.resend_after,
+    )
+
+
+@router.post("/bind-contact", response_model=BindContactResponse)
+async def bind_contact(
+    request: BindContactRequest,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    user_repository: UserRepository = Depends(get_user_repository),
+) -> BindContactResponse:
+    """绑定手机号和/或邮箱（需登录态）"""
+    from app.dependencies import get_db_session
+
+    from packages.adapters.sqlalchemy_impl.verification_code_repository import (
+        SQLAlchemyVerificationCodeRepository,
+    )
+    from packages.application.auth.bind_contact_use_case import BindContactRequest as UseCaseRequest
+    from packages.application.auth.bind_contact_use_case import (
+        BindContactUseCase,
+    )
+    from packages.application.auth.verification_code_service import VerificationCodeService
+
+    db = next(get_db_session())
+    vc_repo = SQLAlchemyVerificationCodeRepository(db)
+    vc_service = VerificationCodeService(repo=vc_repo)
+
+    use_case = BindContactUseCase(
+        user_repository=user_repository,
+        verification_code_service=vc_service,
+    )
+    uc_request = UseCaseRequest(
+        user_id=current_user.user.id,
+        phone=request.phone,
+        phone_code=request.phone_code,
+        email=request.email,
+        email_code=request.email_code,
+    )
+    response, err = use_case.execute(uc_request)
+    if err:
+        raise HTTPException(status_code=400, detail=err)
+
+    return BindContactResponse(success=True, user=response.to_dict()["user"])
+
+
+# ==================== 当前用户信息扩展 ====================
+
+# 扩展 CurrentUserResponse 增加绑定状态字段（在原响应基础上补充）
+# 通过给 get_current_user_info 返回值补充字段实现
@@ -1,313 +0,0 @@
-"""片段调整 API.
-
- PUT    /clips/{clip_id}/speed         调速
- PUT    /clips/{clip_id}/volume        音量调节
- PUT    /clips/{clip_id}/trim          裁剪（trim in/out）
- PUT    /clips/{clip_id}/adjustments   统一调整（speed+volume+trim）
- POST   /{plan_id}/clips/batch-speed   批量调速
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, Optional
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
-from app.services import EditPlanService
-from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, Field
-from sqlalchemy.orm import Session
-
-from ._helpers import check_project_access, deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-
-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
-
-
-# ── Helpers ──────────────────────────────────────────────────────────────────
-
-
-def _get_clip_config(clip) -> dict:
-    config = getattr(clip, "config", {}) or {}
-    if not isinstance(config, dict):
-        config = {}
-    return config
-
-
-def _get_volume(clip) -> float:
-    config = _get_clip_config(clip)
-    return float(config.get("volume", 1.0))
-
-
-def _get_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_response(clip) -> ClipAdjustResponse:
-    trim_start, trim_end = _get_trim(clip)
-    return ClipAdjustResponse(
-        clip_id=clip.id,
-        speed=clip.playback_speed,
-        volume=_get_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）")
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-def _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository):
-    svc = EditPlanService(db)
-    clip = svc.get_clip(clip_id)
-    if not clip:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"片段不存在: {clip_id}",
-        )
-    plan = svc.get_plan(clip.plan_id)
-    if plan and plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-    return svc, plan, clip
-
-
-@router.put("/clips/{clip_id}/speed", response_model=ClipAdjustResponse, deprecated=True)
-def adjust_speed(
-    clip_id: str,
-    body: SpeedAdjustRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipAdjustResponse:
-    """调整片段播放速度"""
-    svc, _, clip = _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository)
-
-    updated = svc.update_clip(clip_id, playback_speed=body.speed)
-
-    logger.info(
-        "调整片段速度: clip_id=%s speed=%.2f by user=%s",
-        clip_id,
-        body.speed,
-        current_user.user.id,
-    )
-    return _build_response(updated)
-
-
-@router.put("/clips/{clip_id}/volume", response_model=ClipAdjustResponse, deprecated=True)
-def adjust_volume(
-    clip_id: str,
-    body: VolumeAdjustRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipAdjustResponse:
-    """调整片段音量"""
-    svc, _, clip = _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository)
-
-    # 更新 config.volume
-    config = dict(_get_clip_config(clip))
-    config["volume"] = body.volume
-    updated = svc.update_clip(clip_id, config=config)
-
-    logger.info(
-        "调整片段音量: clip_id=%s volume=%.2f by user=%s",
-        clip_id,
-        body.volume,
-        current_user.user.id,
-    )
-    return _build_response(updated)
-
-
-@router.put("/clips/{clip_id}/trim", response_model=ClipAdjustResponse, deprecated=True)
-def adjust_trim(
-    clip_id: str,
-    body: TrimAdjustRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipAdjustResponse:
-    """裁剪片段（trim in/out）"""
-    svc, _, clip = _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository)
-
-    # 验证裁剪时长
-    try:
-        _validate_trim(body.trim_start, body.trim_end, clip.duration)
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-
-    # 更新 config
-    config = dict(_get_clip_config(clip))
-    config["trim_start"] = body.trim_start
-    config["trim_end"] = body.trim_end
-    updated = svc.update_clip(clip_id, config=config)
-
-    logger.info(
-        "裁剪片段: clip_id=%s trim_start=%.2f trim_end=%.2f by user=%s",
-        clip_id,
-        body.trim_start,
-        body.trim_end,
-        current_user.user.id,
-    )
-    return _build_response(updated)
-
-
-@router.put("/clips/{clip_id}/adjustments", response_model=ClipAdjustResponse, deprecated=True)
-def adjust_all(
-    clip_id: str,
-    body: ClipAdjustmentsRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipAdjustResponse:
-    """统一调整片段的 speed / volume / trim"""
-    svc, _, clip = _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository)
-
-    update_kwargs = {}
-    config_updates = {}
-
-    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
-
-    # 验证 trim
-    current_trim_start, current_trim_end = _get_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=status.HTTP_400_BAD_REQUEST, 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_response(clip)
-
-    updated = svc.update_clip(clip_id, **update_kwargs)
-
-    logger.info(
-        "统一调整片段: clip_id=%s speed=%s volume=%s by user=%s",
-        clip_id,
-        body.speed,
-        body.volume,
-        current_user.user.id,
-    )
-    return _build_response(updated)
-
-
-@router.post("/{plan_id}/clips/batch-speed", response_model=BatchSpeedResponse, deprecated=True)
-def batch_adjust_speed(
-    plan_id: str,
-    body: BatchSpeedRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> BatchSpeedResponse:
-    """批量调整计划内所有片段的播放速度"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    clips = svc.list_clips(plan_id, limit=500, skip=0)
-    count = 0
-    for clip in clips:
-        svc.update_clip(clip.id, playback_speed=body.speed)
-        count += 1
-
-    logger.info(
-        "批量调速: plan_id=%s count=%d speed=%.2f by user=%s",
-        plan_id,
-        count,
-        body.speed,
-        current_user.user.id,
-    )
-    return BatchSpeedResponse(updated_count=count, plan_id=plan_id)
@@ -1,205 +0,0 @@
-"""剪辑计划 AI 推荐 & 封面生成 API 端点。
-
-从 edit_plans.py 拆分，包含：
- POST /{plan_id}/ai-recommend    AI 推荐片段方案
- POST /{plan_id}/generate-cover  AI 生成封面
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any
-
-from app.api.routes._helpers import check_project_access
-from app.api.routes.edit_plans import (
-    AIRecommendClipItem,
-    AIRecommendRequest,
-    AIRecommendResponse,
-    GenerateCoverRequest,
-    GenerateCoverResponse,
-)
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
-from app.services import EditPlanService
-from fastapi import APIRouter, Depends, HTTPException, status
-from sqlalchemy.orm import Session
-
-from packages.domain.config_schemas import normalize_plan_config
-
-from ._helpers import deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-@router.post(
-    "/{plan_id}/ai-recommend",
-    response_model=AIRecommendResponse,
-    deprecated=True,
-)
-def ai_recommend_clips(
-    plan_id: str,
-    body: AIRecommendRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> AIRecommendResponse:
-    """AI 推荐片段方案
-
-    调用 AI 服务分析素材，自动生成片段编排方案并写入剪辑计划。
-
-    流程：
-    1. 验证计划存在且状态为 draft/editing
-    2. 调用 AI 推荐服务（当前为 stub，后续接入真实 AI）
-    3. 清除计划现有片段，按推荐方案重新创建
-    4. 更新计划 config（cover/title/subtitle/bgm）和 total_duration
-    5. 返回推荐方案详情
-    """
-    svc = EditPlanService(db)
-
-    try:
-        plan = svc.get_plan_or_raise(plan_id)
-    except ValueError as exc:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    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 apps.worker.worker_app.tasks.ai_tasks 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:
-        svc.delete_all_clips(plan_id)
-
-        for clip_data in result["clips"]:
-            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", {}))
-        svc.update_plan(
-            plan_id,
-            config=normalized_config,
-            total_duration=result["total_duration"],
-        )
-    except Exception as _e:
-        logger.exception("AI 推荐写入失败，plan_id=%s 数据可能不一致", plan_id)
-        try:
-            db.rollback()
-        except Exception as rollback_err:
-            logger.error(
-                "AI 推荐回滚失败，数据库会话可能处于不一致状态: plan_id=%s error=%s",
-                plan_id,
-                rollback_err,
-            )
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="AI推荐结果保存失败，请稍后重试",
-        ) from _e
-
-    logger.info(
-        "AI 推荐片段方案: plan_id=%s clips=%d duration=%.1f by user=%s",
-        plan_id,
-        len(result["clips"]),
-        result["total_duration"],
-        current_user.user.id,
-    )
-
-    return AIRecommendResponse(
-        plan_id=plan_id,
-        clips=[
-            AIRecommendClipItem(
-                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"],
-    )
-
-
-@router.post(
-    "/{plan_id}/generate-cover",
-    response_model=GenerateCoverResponse,
-    deprecated=True,
-)
-def generate_cover(
-    plan_id: str,
-    body: GenerateCoverRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> GenerateCoverResponse:
-    """AI 生成封面
-
-    调用 AI 服务从视频中选帧或生成封面图，并更新计划 config.cover。
-    """
-    svc = EditPlanService(db)
-
-    try:
-        plan = svc.get_plan_or_raise(plan_id)
-    except ValueError as exc:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    from apps.worker.worker_app.tasks.ai_tasks 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)
-    current_config["cover"] = cover_data
-    normalized = normalize_plan_config(current_config)
-    svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
-
-    logger.info(
-        "AI 封面生成: plan_id=%s type=%s by user=%s",
-        plan_id,
-        body.cover_type,
-        current_user.user.id,
-    )
-
-    return GenerateCoverResponse(
-        plan_id=plan_id,
-        cover=cover_data,
-    )
@@ -1,423 +0,0 @@
-"""剪辑计划片段（Clip）CRUD 路由。"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, List, Optional
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
-from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
-from sqlalchemy.orm import Session
-
-from packages.domain.edit_plan_clip import EditPlanClipStatus
-
-from ._helpers import deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-from pydantic import BaseModel, Field
-
-
-class EditPlanClipResponse(BaseModel):
-    """剪辑片段响应体"""
-
-    id: str
-    plan_id: str
-    clip_type: str
-    order: int
-    asset_id: str = ""
-    text_content: str = ""
-    start_time: float = 0.0
-    duration: float = 0.0
-    transition_effect: str = "cut"
-    transition_duration: float = 0.0
-    playback_speed: float = 1.0
-    status: str
-    config: dict[str, Any] = Field(default_factory=dict)
-    created_at: Optional[str] = None
-    updated_at: Optional[str] = None
-
-
-class EditPlanClipListResponse(BaseModel):
-    """剪辑片段列表响应体"""
-
-    items: List[EditPlanClipResponse]
-    total: int
-
-
-class EditPlanClipCreateRequest(BaseModel):
-    """创建剪辑片段请求体"""
-
-    clip_type: str = Field(
-        ..., min_length=1, max_length=50, description="片段类型: main/intro/outro/overlay/background/b_roll 等"
-    )
-    order: int = Field(..., ge=0, description="排序序号")
-    asset_id: str = Field(default="", max_length=64, description="关联素材 ID")
-    text_content: str = Field(default="", max_length=5000, description="文本内容（字幕/配音等）")
-    start_time: float = Field(default=0.0, ge=0.0, description="起始时间 (秒)")
-    duration: float = Field(default=0.0, ge=0.0, description="时长 (秒)")
-    transition_effect: str = Field(default="cut", max_length=50, description="转场效果")
-    transition_duration: float = Field(default=0.0, ge=0.0, description="转场时长 (秒)")
-    playback_speed: float = Field(default=1.0, gt=0.0, le=10.0, description="播放速度倍率")
-    config: dict[str, Any] = Field(default_factory=dict, description="扩展配置 (JSON)")
-
-
-class EditPlanClipUpdateRequest(BaseModel):
-    """更新剪辑片段请求体"""
-
-    clip_type: Optional[str] = Field(default=None, min_length=1, max_length=50, description="片段类型")
-    order: Optional[int] = Field(default=None, ge=0, description="排序序号")
-    asset_id: Optional[str] = Field(default=None, max_length=64, description="关联素材 ID")
-    text_content: Optional[str] = Field(default=None, max_length=5000, description="文本内容")
-    start_time: Optional[float] = Field(default=None, ge=0.0, description="起始时间 (秒)")
-    duration: Optional[float] = Field(default=None, ge=0.0, description="时长 (秒)")
-    transition_effect: Optional[str] = Field(default=None, max_length=50, description="转场效果")
-    transition_duration: Optional[float] = Field(default=None, ge=0.0, description="转场时长 (秒)")
-    playback_speed: Optional[float] = Field(default=None, gt=0.0, le=10.0, description="播放速度倍率")
-    config: Optional[dict[str, Any]] = Field(default=None, description="扩展配置 (JSON)")
-
-
-# ── Helpers ──────────────────────────────────────────────────────────────────
-
-
-def _check_plan_access(plan_id: str, user_id: str, project_repository: Any, db: Session) -> Any:
-    """验证用户是否有权限访问该剪辑计划（通过项目关联）。
-    返回 plan 对象供后续使用，避免重复查询。
-    """
-    from app.services.edit_plan_service import EditPlanService
-
-    from ._helpers import check_project_access
-
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if plan is None:
-        raise HTTPException(status_code=404, detail=f"剪辑计划不存在: {plan_id}")
-    if plan.project_id:
-        check_project_access(plan.project_id, user_id, project_repository)
-    return plan
-
-
-def _clip_to_response(clip) -> EditPlanClipResponse:
-    """将领域对象转换为响应体"""
-    return EditPlanClipResponse(
-        id=clip.id,
-        plan_id=clip.plan_id,
-        clip_type=clip.clip_type,
-        order=clip.order,
-        asset_id=clip.asset_id or "",
-        text_content=clip.text_content or "",
-        start_time=clip.start_time,
-        duration=clip.duration,
-        transition_effect=clip.transition_effect or "cut",
-        transition_duration=clip.transition_duration or 0.0,
-        playback_speed=clip.playback_speed or 1.0,
-        status=clip.status.value if hasattr(clip.status, "value") else str(clip.status),
-        config=clip.config or {},
-        created_at=clip.created_at.isoformat() if clip.created_at else None,
-        updated_at=clip.updated_at.isoformat() if clip.updated_at else None,
-    )
-
-
-def _get_svc(db: Session):
-    """获取 EditPlanService 实例"""
-    from app.services.edit_plan_service import EditPlanService
-
-    return EditPlanService(db)
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-@router.get("", response_model=EditPlanClipListResponse, deprecated=True)
-def list_clips(
-    plan_id: str,
-    status_filter: Optional[str] = Query(None, alias="status", description="按状态过滤"),
-    skip: int = Query(0, ge=0, description="分页偏移"),
-    limit: int = Query(100, ge=1, le=500, description="每页数量"),
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> EditPlanClipListResponse:
-    """获取剪辑计划的片段列表"""
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-    status_enum = EditPlanClipStatus(status_filter) if status_filter else None
-    clips = svc.list_clips(plan_id, status=status_enum, skip=skip, limit=limit)
-    total = svc.count_clips(plan_id, status=status_enum)
-
-    return EditPlanClipListResponse(
-        items=[_clip_to_response(c) for c in clips],
-        total=total,
-    )
-
-
-@router.post("", response_model=EditPlanClipResponse, status_code=status.HTTP_201_CREATED, deprecated=True)
-def create_clip(
-    plan_id: str,
-    body: EditPlanClipCreateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> EditPlanClipResponse:
-    """创建剪辑片段"""
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-    try:
-        clip = svc.create_clip(
-            plan_id=plan_id,
-            clip_type=body.clip_type,
-            order=body.order,
-            asset_id=body.asset_id,
-            text_content=body.text_content,
-            start_time=body.start_time,
-            duration=body.duration,
-            transition_effect=body.transition_effect,
-            transition_duration=body.transition_duration,
-            playback_speed=body.playback_speed,
-            config=body.config,
-        )
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-
-    logger.info("创建剪辑片段: plan_id=%s clip_id=%s by user=%s", plan_id, clip.id, current_user.user.id)
-    return _clip_to_response(clip)
-
-
-@router.get("/{clip_id}", response_model=EditPlanClipResponse, deprecated=True)
-def get_clip(
-    plan_id: str,
-    clip_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> EditPlanClipResponse:
-    """获取剪辑片段详情"""
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-    clip = svc.get_clip(clip_id)
-    if clip is None:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-    if clip.plan_id != plan_id:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-
-    return _clip_to_response(clip)
-
-
-@router.put("/{clip_id}", response_model=EditPlanClipResponse, deprecated=True)
-def update_clip(
-    plan_id: str,
-    clip_id: str,
-    body: EditPlanClipUpdateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> EditPlanClipResponse:
-    """更新剪辑片段"""
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-    # 验证 clip 属于该 plan
-    clip = svc.get_clip(clip_id)
-    if clip is None:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-    if clip.plan_id != plan_id:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-
-    try:
-        updated = svc.update_clip(
-            clip_id,
-            clip_type=body.clip_type,
-            order=body.order,
-            asset_id=body.asset_id,
-            text_content=body.text_content,
-            start_time=body.start_time,
-            duration=body.duration,
-            transition_effect=body.transition_effect,
-            transition_duration=body.transition_duration,
-            playback_speed=body.playback_speed,
-            config=body.config,
-        )
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-
-    logger.info("更新剪辑片段: plan_id=%s clip_id=%s by user=%s", plan_id, clip_id, current_user.user.id)
-    return _clip_to_response(updated)
-
-
-@router.delete(
-    "/{clip_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response, deprecated=True
-)
-def delete_clip(
-    plan_id: str,
-    clip_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> None:
-    """删除剪辑片段"""
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-    # 验证 clip 属于该 plan
-    clip = svc.get_clip(clip_id)
-    if clip is None:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-    if clip.plan_id != plan_id:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-
-    deleted = svc.delete_clip(clip_id)
-    if not deleted:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-
-    logger.info("删除剪辑片段: plan_id=%s clip_id=%s by user=%s", plan_id, clip_id, current_user.user.id)
-    return None
-
-
-# ── 片段分割与合并 ──────────────────────────────────────────────────────────
-
-
-class SplitClipRequest(BaseModel):
-    """分割片段请求体"""
-
-    split_time: float = Field(..., gt=0, description="分割点（秒，相对于片段起始）")
-
-
-class MergeClipsRequest(BaseModel):
-    """合并片段请求体"""
-
-    clip_ids: list[str] = Field(..., min_length=2, description="要合并的片段 ID 列表")
-
-
-@router.post(
-    "/{clip_id}/split",
-    response_model=dict[str, Any],
-    summary="分割片段",
-    status_code=status.HTTP_200_OK,
-    deprecated=True,
-)
-def split_clip(
-    plan_id: str,
-    clip_id: str,
-    body: SplitClipRequest,
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    db: Session = Depends(get_db_session),
-    project_repository: Any = Depends(get_project_repository),
-) -> dict[str, Any]:
-    """将一个片段从指定时间点分割为两个片段。
-
-    分割后原片段变为左半部分，新增右半部分片段，后续片段顺序自动后移。
-    若片段有关联素材，会自动设置 trim_start/trim_end 标记裁剪范围。
-    """
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-    clip = svc.get_clip(clip_id)
-    if clip is None or clip.plan_id != plan_id:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"片段不存在: {clip_id}",
-        )
-
-    try:
-        result = svc.split_clip(clip_id, body.split_time)
-    except ValueError as e:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=str(e),
-        ) from e
-
-    left = result["left_clip"]
-    right = result["right_clip"]
-    logger.info("分割片段: plan_id=%s clip_id=%s by user=%s", plan_id, clip_id, current_user.user.id)
-
-    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(
-    "/merge",
-    response_model=dict[str, Any],
-    summary="合并多个连续片段",
-    status_code=status.HTTP_200_OK,
-    deprecated=True,
-)
-def merge_clips(
-    plan_id: str,
-    body: MergeClipsRequest,
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    db: Session = Depends(get_db_session),
-    project_repository: Any = Depends(get_project_repository),
-) -> dict[str, Any]:
-    """将多个连续的同类型片段合并为一个片段。
-
-    合并要求：
-    - 至少 2 个片段
-    - 属于同一剪辑计划
-    - order 连续
-    - 类型相同
-
-    合并后保留第一个片段，其余删除，后续片段顺序自动前移。
-    """
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-
-    # 校验所有片段都属于该 plan
-    for cid in body.clip_ids:
-        clip = svc.get_clip(cid)
-        if clip is None or clip.plan_id != plan_id:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"片段不存在: {cid}",
-            )
-
-    try:
-        merged = svc.merge_clips(body.clip_ids)
-    except ValueError as e:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=str(e),
-        ) from e
-
-    logger.info(
-        "合并片段: plan_id=%s clip_count=%d by user=%s",
-        plan_id,
-        len(body.clip_ids),
-        current_user.user.id,
-    )
-
-    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,
-    }
@@ -1,245 +0,0 @@
-"""剪辑计划片段批量操作 API。"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, List
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
-from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, Field
-from sqlalchemy.orm import Session
-
-from ._helpers import deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-
-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
-    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
-    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
-    created_count: int
-    message: str = ""
-    clip_ids: List[str] = Field(default_factory=list, description="创建的片段ID列表")
-
-
-# ── Helpers ──────────────────────────────────────────────────────────────────
-
-
-def _check_plan_access(plan_id: str, user_id: str, project_repository: Any, db: Session) -> Any:
-    """验证用户是否有权限访问该剪辑计划，返回 plan 对象。"""
-    from app.services.edit_plan_service import EditPlanService
-
-    from ._helpers import check_project_access
-
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if plan is None:
-        raise HTTPException(status_code=404, detail=f"剪辑计划不存在: {plan_id}")
-    if plan.project_id:
-        check_project_access(plan.project_id, user_id, project_repository)
-    return plan
-
-
-def _get_svc(db: Session):
-    """获取 EditPlanService 实例"""
-    from app.services.edit_plan_service import EditPlanService
-
-    return EditPlanService(db)
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-@router.post("/reorder", response_model=ClipReorderResponse, deprecated=True)
-def reorder_clips(
-    plan_id: str,
-    body: ClipReorderRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipReorderResponse:
-    """批量重排序片段
-
-    前端拖拽调整顺序后，一次性提交所有变更的 order。
-    自动触发编辑状态回退（从 completed/failed 切回 editing）。
-    """
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-
-    # 验证所有 clip 都属于该 plan
-    clip_ids = [item.clip_id for item in body.items]
-    existing_clips = svc.list_clips(plan_id, skip=0, limit=10000)
-    existing_ids = {c.id for c in existing_clips}
-
-    invalid_ids = [cid for cid in clip_ids if cid not in existing_ids]
-    if invalid_ids:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"以下片段不属于该计划: {', '.join(invalid_ids[:5])}",
-        )
-
-    # 执行重排序
-    updated_count = 0
-    for item in body.items:
-        try:
-            svc.update_clip(item.clip_id, order=item.new_order)
-            updated_count += 1
-        except ValueError as e:
-            logger.warning("重排序片段失败: clip_id=%s error=%s", item.clip_id, e)
-
-    logger.info(
-        "批量重排序片段: plan_id=%s count=%d by user=%s",
-        plan_id,
-        updated_count,
-        current_user.user.id,
-    )
-
-    return ClipReorderResponse(
-        success=True,
-        updated_count=updated_count,
-        message=f"成功更新 {updated_count} 个片段的顺序",
-    )
-
-
-@router.post("/batch-delete", response_model=ClipBatchDeleteResponse, deprecated=True)
-def batch_delete_clips(
-    plan_id: str,
-    body: ClipBatchDeleteRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipBatchDeleteResponse:
-    """批量删除片段
-
-    自动触发编辑状态回退（从 completed/failed 切回 editing）。
-    """
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-
-    # 验证所有 clip 都属于该 plan
-    existing_clips = svc.list_clips(plan_id, skip=0, limit=10000)
-    existing_ids = {c.id for c in existing_clips}
-
-    valid_ids = [cid for cid in body.clip_ids if cid in existing_ids]
-    skipped = len(body.clip_ids) - len(valid_ids)
-
-    # 执行删除
-    deleted_count = 0
-    for clip_id in valid_ids:
-        if svc.delete_clip(clip_id):
-            deleted_count += 1
-
-    message = f"成功删除 {deleted_count} 个片段"
-    if skipped > 0:
-        message += f"，跳过 {skipped} 个不存在的片段"
-
-    logger.info(
-        "批量删除片段: plan_id=%s deleted=%d skipped=%d by user=%s",
-        plan_id,
-        deleted_count,
-        skipped,
-        current_user.user.id,
-    )
-
-    return ClipBatchDeleteResponse(
-        success=True,
-        deleted_count=deleted_count,
-        message=message,
-    )
-
-
-@router.post("/from-assets", response_model=ClipsFromAssetsResponse, deprecated=True)
-def create_clips_from_assets(
-    plan_id: str,
-    body: ClipsFromAssetsRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipsFromAssetsResponse:
-    """从素材批量创建片段（追加到时间线末尾）
-
-    一次性将多个素材作为片段添加到剪辑计划，自动读取素材时长。
-    自动触发编辑状态回退（completed/failed → editing）。
-    """
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-
-    try:
-        clips = svc.create_clips_from_assets(
-            plan_id=plan_id,
-            asset_ids=body.asset_ids,
-            clip_type=body.clip_type,
-        )
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-
-    clip_ids = [c.id for c in clips]
-
-    logger.info(
-        "从素材批量创建片段: plan_id=%s count=%d by user=%s",
-        plan_id,
-        len(clips),
-        current_user.user.id,
-    )
-
-    return ClipsFromAssetsResponse(
-        success=True,
-        created_count=len(clips),
-        message=f"成功创建 {len(clips)} 个片段",
-        clip_ids=clip_ids,
-    )
@@ -1,317 +0,0 @@
-"""封面管理 API.
-
- GET    /{plan_id}/cover              获取封面配置
- PUT    /{plan_id}/cover              更新封面配置
- POST   /{plan_id}/cover/extract      从指定片段抽帧生成封面
- POST   /{plan_id}/cover/smart        智能选帧生成封面
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, Optional
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.core.storage import get_storage_service
-from app.dependencies import (
-    get_asset_repository,
-    get_db_session,
-    get_project_repository,
-)
-from app.services import EditPlanService
-from app.services.cover_service import CoverService
-from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, Field
-from sqlalchemy.orm import Session
-
-from packages.domain.config_schemas import normalize_plan_config
-
-from ._helpers import check_project_access, deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-
-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="抽帧时间点（秒）")
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-@router.get("/{plan_id}/cover", response_model=CoverConfigResponse, deprecated=True)
-def get_cover(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> CoverConfigResponse:
-    """获取封面配置"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    cover = CoverService.get_cover_config(plan.config or {})
-    return CoverConfigResponse(**cover)
-
-
-@router.put("/{plan_id}/cover", response_model=CoverConfigResponse, deprecated=True)
-def update_cover(
-    plan_id: str,
-    body: CoverUpdateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> CoverConfigResponse:
-    """更新封面配置
-
-    用于：设置上传的封面图片 URL、切换封面类型、调整时间点等。
-    """
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 合并更新
-    current_cover = CoverService.get_cover_config(plan.config or {})
-    updates = body.model_dump(exclude_none=True)
-    new_cover = {**current_cover, **updates}
-
-    # 验证 type 值
-    valid_types = {"ai_frame", "manual", "upload", "ai_regenerate"}
-    if "type" in updates and updates["type"] not in valid_types:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"无效的封面类型: {updates['type']}，有效值: {valid_types}",
-        )
-
-    # 更新到 plan.config
-    current_config = dict(plan.config or {})
-    current_config["cover"] = new_cover
-    normalized = normalize_plan_config(current_config)
-    updated_plan = svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
-
-    result = CoverService.get_cover_config(updated_plan.config or {})
-    logger.info("更新封面配置: plan_id=%s type=%s by user=%s", plan_id, result["type"], current_user.user.id)
-    return CoverConfigResponse(**result)
-
-
-@router.post("/{plan_id}/cover/extract", response_model=CoverGenerateResponse, deprecated=True)
-def extract_cover(
-    plan_id: str,
-    body: CoverExtractRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-    storage_service: Any = Depends(get_storage_service),
-    asset_repository: Any = Depends(get_asset_repository),
-) -> CoverGenerateResponse:
-    """从指定片段的指定时间点抽帧生成封面"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 获取片段对应的素材
-    clip = svc.get_clip(body.clip_id)
-    if not clip:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"片段不存在: {body.clip_id}",
-        )
-
-    if clip.plan_id != plan_id:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="片段不属于该剪辑计划",
-        )
-
-    if not clip.asset_id:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="片段没有关联素材，无法抽帧",
-        )
-
-    # 抽帧生成封面
-    cover_svc = CoverService(storage_service, asset_repository)
-    try:
-        cover_data = cover_svc.extract_cover_from_clip(
-            plan_id=plan_id,
-            asset_id=clip.asset_id,
-            frame_time=body.frame_time,
-        )
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-    except RuntimeError as e:
-        logger.error("封面抽帧失败: plan_id=%s clip_id=%s error=%s", plan_id, body.clip_id, e)
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"封面抽帧失败: {e}",
-        ) from e
-
-    # 更新到 plan.config.cover
-    current_config = dict(plan.config or {})
-    current_config["cover"] = cover_data
-    normalized = normalize_plan_config(current_config)
-    svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
-
-    logger.info(
-        "封面抽帧完成: plan_id=%s clip_id=%s time=%.2fs by user=%s",
-        plan_id,
-        body.clip_id,
-        body.frame_time,
-        current_user.user.id,
-    )
-    return CoverGenerateResponse(**cover_data)
-
-
-@router.post("/{plan_id}/cover/smart", response_model=CoverGenerateResponse, deprecated=True)
-def smart_cover(
-    plan_id: str,
-    body: CoverSmartRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-    storage_service: Any = Depends(get_storage_service),
-    asset_repository: Any = Depends(get_asset_repository),
-) -> CoverGenerateResponse:
-    """智能选帧生成封面
-
-    从指定片段（或第一个视频片段）中智能选取一帧作为封面。
-    当前实现：取片段第3秒帧（后续可优化为多帧选最清晰）。
-    """
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 确定使用哪个片段
-    clip_id = body.clip_id
-    asset_id = ""
-
-    if clip_id:
-        clip = svc.get_clip(clip_id)
-        if not clip:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"片段不存在: {clip_id}",
-            )
-        if clip.plan_id != plan_id:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="片段不属于该剪辑计划",
-            )
-        if not clip.asset_id:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="片段没有关联素材",
-            )
-        asset_id = clip.asset_id
-    else:
-        # 找第一个有素材的视频片段
-        clips = svc.list_clips(plan_id, limit=50, skip=0)
-        for c in clips:
-            if c.asset_id and c.clip_type == "video":
-                asset_id = c.asset_id
-                clip_id = c.id
-                break
-
-        if not asset_id:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="没有找到可用的视频片段",
-            )
-
-    # 智能选帧
-    cover_svc = CoverService(storage_service, asset_repository)
-    try:
-        cover_data = cover_svc.generate_smart_cover(
-            plan_id=plan_id,
-            asset_id=asset_id,
-        )
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-    except RuntimeError as e:
-        logger.error("智能封面生成失败: plan_id=%s error=%s", plan_id, e)
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"智能封面生成失败: {e}",
-        ) from e
-
-    # 更新到 plan.config.cover
-    current_config = dict(plan.config or {})
-    current_config["cover"] = cover_data
-    normalized = normalize_plan_config(current_config)
-    svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
-
-    logger.info(
-        "智能封面生成完成: plan_id=%s clip_id=%s by user=%s",
-        plan_id,
-        clip_id,
-        current_user.user.id,
-    )
-    return CoverGenerateResponse(**cover_data)
@@ -1,276 +0,0 @@
-"""导出设置 API.
-
- GET    /{plan_id}/export              获取导出配置
- PUT    /{plan_id}/export              更新导出配置
- GET    /export-presets                 导出预设列表
-"""
-
-from __future__ import annotations
-
-import logging
-import re
-from typing import Any, List, Optional
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
-from app.services import EditPlanService
-from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, Field, validator
-from sqlalchemy.orm import Session
-
-from packages.domain.config_schemas import normalize_plan_config
-
-from ._helpers import check_project_access, deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── 导出预设 ──────────────────────────────────────────────────────────────────
-
-EXPORT_PRESETS = [
-    {
-        "id": "export_1080p_30",
-        "name": "1080P 高清",
-        "resolution": "1080x1920",
-        "fps": 30,
-        "video_bitrate": 8000,
-        "audio_bitrate": 128,
-        "format": "mp4",
-        "quality_preset": "balanced",
-        "description": "竖屏高清，适合短视频平台",
-        "size_hint": "约 10MB/分钟",
-    },
-    {
-        "id": "export_1080p_60",
-        "name": "1080P 高帧率",
-        "resolution": "1080x1920",
-        "fps": 60,
-        "video_bitrate": 12000,
-        "audio_bitrate": 128,
-        "format": "mp4",
-        "quality_preset": "high",
-        "description": "60帧高帧率，流畅运动画面",
-        "size_hint": "约 18MB/分钟",
-    },
-    {
-        "id": "export_720p_30",
-        "name": "720P 流畅",
-        "resolution": "720x1280",
-        "fps": 30,
-        "video_bitrate": 4000,
-        "audio_bitrate": 128,
-        "format": "mp4",
-        "quality_preset": "fast",
-        "description": "快速导出，文件较小",
-        "size_hint": "约 5MB/分钟",
-    },
-    {
-        "id": "export_4k_30",
-        "name": "4K 超清",
-        "resolution": "2160x3840",
-        "fps": 30,
-        "video_bitrate": 20000,
-        "audio_bitrate": 192,
-        "format": "mp4",
-        "quality_preset": "best",
-        "description": "4K超清画质，专业品质",
-        "size_hint": "约 30MB/分钟",
-    },
-    {
-        "id": "export_1080p_30_mov",
-        "name": "1080P ProRes",
-        "resolution": "1080x1920",
-        "fps": 30,
-        "video_bitrate": 15000,
-        "audio_bitrate": 256,
-        "format": "mov",
-        "quality_preset": "high",
-        "description": "MOV格式，适合后期剪辑",
-        "size_hint": "约 25MB/分钟",
-    },
-]
-
-VALID_QUALITY_PRESETS = {"ultra_fast", "fast", "balanced", "high", "best"}
-VALID_FORMATS = {"mp4", "mov"}
-
-RESOLUTION_PATTERN = re.compile(r"^\d+x\d+$")
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-
-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 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 VALID_FORMATS:
-            raise ValueError(f"无效格式: {v}，支持: {VALID_FORMATS}")
-        return v
-
-    @validator("quality_preset")
-    def validate_quality_preset(cls, v):
-        if v is None:
-            return v
-        if v not in VALID_QUALITY_PRESETS:
-            raise ValueError(f"无效质量预设: {v}，支持: {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
-
-
-# ── Helpers ──────────────────────────────────────────────────────────────────
-
-
-def _get_export_config(plan_config: dict) -> dict:
-    e = plan_config.get("export", {})
-    if not isinstance(e, dict):
-        e = {}
-    return {
-        "resolution": e.get("resolution", "1080x1920"),
-        "fps": e.get("fps", 30),
-        "video_bitrate": e.get("video_bitrate", 8000),
-        "audio_bitrate": e.get("audio_bitrate", 128),
-        "format": e.get("format", "mp4"),
-        "quality_preset": e.get("quality_preset", "balanced"),
-        "watermark_enabled": e.get("watermark_enabled", False),
-        "watermark_text": e.get("watermark_text", ""),
-    }
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-@router.get("/export-presets", response_model=ExportPresetListResponse, deprecated=True)
-def list_export_presets(
-    current_user: AuthenticatedUser = Depends(get_current_user),
-) -> ExportPresetListResponse:
-    """获取导出预设列表"""
-    items = [ExportPresetItem(**p) for p in EXPORT_PRESETS]
-    return ExportPresetListResponse(items=items, total=len(items))
-
-
-@router.get("/{plan_id}/export", response_model=ExportConfigResponse, deprecated=True)
-def get_export_config(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ExportConfigResponse:
-    """获取导出配置"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    config = _get_export_config(plan.config or {})
-    return ExportConfigResponse(**config)
-
-
-@router.put("/{plan_id}/export", response_model=ExportConfigResponse, deprecated=True)
-def update_export_config(
-    plan_id: str,
-    body: ExportUpdateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ExportConfigResponse:
-    """更新导出配置"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 合并更新
-    current = _get_export_config(plan.config or {})
-    updates = body.model_dump(exclude_none=True)
-    new_export = {**current, **updates}
-
-    # 更新到 plan.config
-    current_config = dict(plan.config or {})
-    current_config["export"] = new_export
-    normalized = normalize_plan_config(current_config)
-    updated_plan = svc.update_plan_config(plan_id, {"export": normalized["export"]})
-
-    result = _get_export_config(updated_plan.config or {})
-    logger.info(
-        "更新导出配置: plan_id=%s resolution=%s fps=%d by user=%s",
-        plan_id,
-        result["resolution"],
-        result["fps"],
-        current_user.user.id,
-    )
-    return ExportConfigResponse(**result)
@@ -1,199 +0,0 @@
-"""滤镜调色 API.
-
- GET    /filter-presets            滤镜预设列表
- GET    /{plan_id}/filter          获取全局滤镜配置
- PUT    /{plan_id}/filter          更新全局滤镜配置
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, List, Optional
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
-from app.services import EditPlanService
-from fastapi import APIRouter, Depends, HTTPException, Query, status
-from pydantic import BaseModel, Field
-from sqlalchemy.orm import Session
-
-from packages.domain.config_schemas import normalize_plan_config
-from packages.domain.filter_presets import (
-    FilterPreset,
-    get_filter_preset,
-    list_filter_presets,
-)
-
-from ._helpers import check_project_access, deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-
-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
-
-
-# ── Helpers ──────────────────────────────────────────────────────────────────
-
-
-def _preset_to_response(p: FilterPreset) -> FilterPresetResponse:
-    return FilterPresetResponse(
-        id=p.id,
-        name=p.name,
-        category=p.category,
-        description=p.description,
-        tags=list(p.tags),
-    )
-
-
-def _get_filter_config(plan_config: dict) -> dict:
-    """从 plan.config 中提取滤镜配置"""
-    f = plan_config.get("filter", {})
-    if not isinstance(f, dict):
-        f = {}
-    return {
-        "enabled": f.get("enabled", False),
-        "preset_id": f.get("preset_id", "filter_none"),
-        "intensity": f.get("intensity", 100),
-        "brightness": f.get("brightness", 0.0),
-        "contrast": f.get("contrast", 1.0),
-        "saturation": f.get("saturation", 1.0),
-        "warmth": f.get("warmth", 0.0),
-    }
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-@router.get("/filter-presets", response_model=FilterPresetListResponse, deprecated=True)
-def list_presets(
-    category: Optional[str] = Query(default=None, description="按分类筛选"),
-    keyword: Optional[str] = Query(default=None, description="关键词搜索"),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-) -> FilterPresetListResponse:
-    """获取滤镜预设列表"""
-    presets = list_filter_presets(category=category, keyword=keyword)
-    items = [_preset_to_response(p) for p in presets]
-    return FilterPresetListResponse(items=items, total=len(items))
-
-
-@router.get("/{plan_id}/filter", response_model=FilterConfigResponse, deprecated=True)
-def get_filter(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> FilterConfigResponse:
-    """获取剪辑计划的全局滤镜配置"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    config = _get_filter_config(plan.config or {})
-    return FilterConfigResponse(**config)
-
-
-@router.put("/{plan_id}/filter", response_model=FilterConfigResponse, deprecated=True)
-def update_filter(
-    plan_id: str,
-    body: FilterUpdateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> FilterConfigResponse:
-    """更新全局滤镜配置"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 验证 preset_id
-    updates = body.model_dump(exclude_none=True)
-    if "preset_id" in updates:
-        preset = get_filter_preset(updates["preset_id"])
-        if preset is None:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=f"无效的滤镜预设: {updates['preset_id']}",
-            )
-
-    # 合并更新
-    current = _get_filter_config(plan.config or {})
-    new_filter = {**current, **updates}
-
-    # 如果设为原图 preset，自动关闭
-    if new_filter["preset_id"] == "filter_none":
-        new_filter["enabled"] = False
-
-    # 更新到 plan.config
-    current_config = dict(plan.config or {})
-    current_config["filter"] = new_filter
-    normalized = normalize_plan_config(current_config)
-    updated_plan = svc.update_plan_config(plan_id, {"filter": normalized["filter"]})
-
-    result = _get_filter_config(updated_plan.config or {})
-    logger.info(
-        "更新滤镜配置: plan_id=%s preset=%s intensity=%d by user=%s",
-        plan_id,
-        result["preset_id"],
-        result["intensity"],
-        current_user.user.id,
-    )
-    return FilterConfigResponse(**result)
@@ -1,418 +0,0 @@
-"""剪辑计划生成相关 API 端点。
-
-从 edit_plans.py 拆分，包含：
- POST /{plan_id}/generate          触发剪辑渲染生成
- GET  /{plan_id}/generation-status 查询生成进度
- GET  /{plan_id}/generations       查询关联的生成记录
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any
-
-from app.api.routes._helpers import check_project_access
-from app.api.routes.edit_plans import (
-    ClipStatusItem,
-    EditPlanGenerateResponse,
-    EditPlanGenerationsResponse,
-    EditPlanGenerationStatusResponse,
-)
-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.core.task_enqueue import GLOBAL_PENDING_LIMIT, USER_PENDING_LIMIT
-from app.dependencies import get_asset_library_repository, get_asset_repository, get_db_session, get_project_repository
-from app.services import EditPlanService
-from fastapi import APIRouter, Depends, HTTPException, status
-from sqlalchemy.orm import Session
-
-from packages.adapters.sqlalchemy_impl.generation_task_repository import (
-    SQLAlchemyGenerationTaskRepository,
-)
-from packages.adapters.sqlalchemy_impl.template_clip_config_repository import (
-    SQLAlchemyTemplateClipConfigRepository,
-)
-from packages.adapters.sqlalchemy_impl.template_repository import (
-    SQLAlchemyTemplateRepository,
-)
-from packages.application.generation_tasks import (
-    CreateGenerationTaskCommand,
-    CreateGenerationTaskUseCase,
-)
-from packages.domain.edit_plan import EditPlanStatus
-
-from ._helpers import deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-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 从旧模型 template_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: 项目有视频素材库时，自动选取 ready 视频素材分配给无素材片段
-
-    注：原先需要 material_mode=="auto" 才触发，但全代码库没有任何地方设置为 auto，
-    导致这道兜底防线永远不生效。现改为：只要有 project_id 且存在无素材片段，
-    就自动从项目视频素材库选取素材兜底，确保一键生成等场景能正常出片。
-    """
-    if not clips_without_asset:
-        return
-    if not plan_check.project_id:
-        return
-
-    import random
-
-    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 个素材给 %d 个片段",
-                plan_id,
-                video_lib.name,
-                len(ready_videos),
-                len(clips_without_asset),
-            )
-        else:
-            logger.warning("自动兜底4: plan=%s 素材库无可用视频素材", plan_id)
-    else:
-        logger.warning("自动兜底4: plan=%s 项目无视频素材库", 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)
-
-
-@router.post("/{plan_id}/generate", response_model=EditPlanGenerateResponse, deprecated=True)
-def generate_plan(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-    asset_library_repo: Any = Depends(get_asset_library_repository),
-    asset_repo: Any = Depends(get_asset_repository),
-) -> EditPlanGenerateResponse:
-    """触发剪辑计划渲染生成
-
-    前置条件：计划状态必须为 editing，且至少有一个片段。
-    流程：
-    1. 验证计划状态为 editing
-    2. 将 pending 片段标记为 ready
-    3. 创建 GenerationTask
-    4. 调度 Celery 任务 worker.render_edit_plan
-    5. 将计划状态流转为 rendering
-    """
-    svc = EditPlanService(db)
-    plan_check = svc.get_plan(plan_id)
-    if plan_check is None:
-        raise HTTPException(status_code=404, detail=f"剪辑计划不存在: {plan_id}")
-    if plan_check.project_id:
-        check_project_access(plan_check.project_id, current_user.user.id, project_repository)
-
-    # 自动兜底流程
-    _auto_fallback_draft_to_editing(svc, plan_id, plan_check)
-    _auto_fallback_copy_template_clips(svc, plan_id, plan_check, db)
-    clips_without_asset = _auto_fallback_assign_assets(svc, plan_id, plan_check)
-    _auto_fallback_auto_material_mode(svc, plan_id, plan_check, clips_without_asset, asset_library_repo, asset_repo)
-
-    # 检查是否可生成
-    try:
-        can_gen, reason = 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 = 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 = svc.get_plan_or_raise(plan_id)
-        # 从 plan.config 中读取 asset_ids 并传递给 GenerationTask
-        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 [],
-            )
-        )
-
-        svc.update_plan_config(plan_id, {"generation_task_id": gen_task.id})
-        svc.transition_status(plan_id, EditPlanStatus.RENDERING)
-        celery_app.send_task("worker.render_edit_plan", args=[plan_id])
-
-        updated_plan = svc.get_plan_or_raise(plan_id)
-
-        logger.info(
-            "触发剪辑计划生成: plan_id=%s gen_task_id=%s clips=%d by user=%s",
-            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("触发剪辑计划生成失败: plan_id=%s", plan_id)
-        try:
-            svc.transition_status(plan_id, EditPlanStatus.FAILED)
-        except Exception:
-            logger.warning("标记计划失败状态时异常: plan_id=%s", plan_id)
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="生成失败，请稍后重试",
-        ) from _e
-
-
-@router.get(
-    "/{plan_id}/generation-status",
-    response_model=EditPlanGenerationStatusResponse,
-    deprecated=True,
-)
-def get_generation_status(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-    storage_service: OSSStorageService = Depends(get_storage_service),
-) -> EditPlanGenerationStatusResponse:
-    """查询剪辑计划生成进度"""
-    svc = EditPlanService(db)
-    try:
-        gen_status = 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"]
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-    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
-    ]
-
-    # 从 plan.config 中取渲染结果 URL，转换为签名 URL
-    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失败，返回原始URL: plan_id=%s error=%s", plan_id, e)
-            video_url = raw_video_url
-    # 从 gen_status 中取进度、错误信息、任务状态
-    progress = gen_status.get("progress", 0.0)
-    error_message = gen_status.get("error_message", "")
-    gen_task_status = gen_status.get("generation_task_status")
-    # 如果计划已完成但进度还是0，补100
-    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(
-    "/{plan_id}/generations",
-    response_model=EditPlanGenerationsResponse,
-    deprecated=True,
-)
-def list_plan_generations(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> EditPlanGenerationsResponse:
-    """查询剪辑计划关联的所有生成记录"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan_or_raise(plan_id)
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    from app.schemas.generation_task import GenerationTaskResponse
-
-    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))
@@ -1,263 +0,0 @@
-"""剪辑计划时间线 & 模板生成 API 端点。
-
-从 edit_plans.py 拆分，包含：
- GET  /{plan_id}/timeline            时间线场景数据
- POST /generate-from-template        基于模板+素材自动生成剪辑计划
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, List
-
-from app.api.routes._helpers import auto_select_video_assets, check_project_access
-from app.api.routes.edit_plans import (
-    GenerateFromTemplateRequest,
-    GenerateFromTemplateResponse,
-    _PlanClipItem,
-    _to_response,
-)
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import (
-    get_asset_library_repository,
-    get_asset_repository,
-    get_db_session,
-    get_project_repository,
-)
-from app.services import EditPlanService, PlanGeneratorService
-from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, Field
-from sqlalchemy.orm import Session
-
-from ._helpers import deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── Timeline Schemas ──────────────────────────────────────────────────────────
-
-
-class TimelineSceneResponse(BaseModel):
-    """时间线场景"""
-
-    scene: str = Field(..., description="场景描述")
-    time: str = Field(..., description='时间范围，如 "0:00 - 0:05"')
-    duration: float = Field(..., ge=0, description="时长（秒）")
-    color: str = Field(..., description="展示颜色")
-    clip_id: str = Field(default="", description="关联的片段 ID")
-    clip_type: str = Field(default="", description="片段类型")
-
-
-class TimelineResponse(BaseModel):
-    """时间线响应"""
-
-    plan_id: str
-    total_duration: float
-    scenes: List[TimelineSceneResponse]
-
-
-# clip_type → 颜色映射
-_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:
-    """根据 clip_type 和 text_content 生成场景描述"""
-    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
-
-
-# ── Routes ────────────────────────────────────────────────────────────────────
-
-
-@router.get(
-    "/{plan_id}/timeline",
-    response_model=TimelineResponse,
-    deprecated=True,
-)
-def get_plan_timeline(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> TimelineResponse:
-    """获取剪辑计划的时间线场景数据"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan_or_raise(plan_id)
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    clips = svc.list_clips(plan_id=plan_id, skip=0, limit=200)
-    clips.sort(key=lambda c: c.order)
-
-    scenes: List[TimelineSceneResponse] = []
-    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(
-            TimelineSceneResponse(
-                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 TimelineResponse(
-        plan_id=plan_id,
-        total_duration=total_duration,
-        scenes=scenes,
-    )
-
-
-@router.post(
-    "/generate-from-template",
-    response_model=GenerateFromTemplateResponse,
-    status_code=status.HTTP_201_CREATED,
-    deprecated=True,
-)
-def generate_from_template(
-    body: GenerateFromTemplateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-    asset_repository: Any = Depends(get_asset_repository),
-    asset_library_repository: Any = Depends(get_asset_library_repository),
-) -> GenerateFromTemplateResponse:
-    """基于模板 + 素材自动生成剪辑计划"""
-    from app.services import EditTemplateService
-
-    if body.project_id:
-        check_project_access(body.project_id, current_user.user.id, project_repository)
-
-    template_svc = EditTemplateService(db)
-
-    try:
-        template = template_svc.get_template_or_raise(body.template_id)
-    except ValueError as exc:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
-
-    clip_configs = template_svc.list_clip_configs(body.template_id, skip=0, limit=200)
-
-    # 自动选素材：未传 asset_ids 但有 project_id 时，从项目视频素材库选 ready 的视频素材
-    resolved_asset_ids = list(body.asset_ids)
-    if not resolved_asset_ids and body.project_id:
-        auto_assets = auto_select_video_assets(
-            project_id=body.project_id,
-            asset_library_repo=asset_library_repository,
-            asset_repo=asset_repository,
-            logger=logger,
-        )
-        if auto_assets:
-            resolved_asset_ids = auto_assets
-            logger.info(
-                "generate-from-template 自动选素材: project_id=%s count=%d",
-                body.project_id,
-                len(auto_assets),
-            )
-
-    generator = PlanGeneratorService(db)
-    result = generator.generate_from_template(
-        template=template,
-        clip_configs=clip_configs,
-        asset_ids=resolved_asset_ids,
-        project_id=body.project_id,
-        created_by_user_id=current_user.user.id,
-        name=body.name,
-    )
-
-    plan = result["plan"]
-    clips = result["clips"]
-
-    # 把 asset_ids 写入 plan.config，供生成时兜底分配使用
-    if resolved_asset_ids:
-        from app.services import EditPlanService
-
-        from packages.domain.config_schemas import normalize_plan_config
-
-        svc = EditPlanService(db)
-        current_config = plan.config or {}
-        if current_config.get("asset_ids") != resolved_asset_ids:
-            current_config["asset_ids"] = resolved_asset_ids
-            plan = svc.update_plan(plan.id, config=normalize_plan_config(current_config))
-
-    logger.info(
-        "基于模板生成剪辑计划: plan_id=%s template_id=%s clips=%d by user=%d",
-        plan.id,
-        body.template_id,
-        len(clips),
-        current_user.user.id,
-    )
-
-    return GenerateFromTemplateResponse(
-        plan=_to_response(plan),
-        clips=[
-            _PlanClipItem(
-                id=c.id,
-                clip_type=c.clip_type,
-                order=c.order,
-                asset_id=c.asset_id,
-                text_content=c.text_content,
-                start_time=c.start_time,
-                duration=c.duration,
-                transition_effect=c.transition_effect,
-                transition_duration=c.transition_duration,
-                status=c.status.value if hasattr(c.status, "value") else c.status,
-                config=c.config,
-                created_at=c.created_at,
-                updated_at=c.updated_at,
-            )
-            for c in clips
-        ],
-    )
@@ -1,274 +0,0 @@
-"""转场特效 API.
-
- GET    /transition-presets              转场预设列表
- PUT    /clips/{clip_id}/transition      设置单个片段转场
- POST   /{plan_id}/transitions/batch     批量设置转场（所有片段）
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, List, Optional
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
-from app.services import EditPlanService
-from fastapi import APIRouter, Depends, HTTPException, Query, status
-from pydantic import BaseModel, Field
-from sqlalchemy.orm import Session
-
-from packages.domain.transition_presets import (
-    TransitionPreset,
-    get_transition_preset,
-    list_transition_presets,
-)
-
-from ._helpers import check_project_access, deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-
-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
-
-
-# ── Helpers ──────────────────────────────────────────────────────────────────
-
-
-def _preset_to_response(p: TransitionPreset) -> TransitionPresetResponse:
-    return TransitionPresetResponse(
-        id=p.id,
-        name=p.name,
-        category=p.category,
-        description=p.description,
-        tags=list(p.tags),
-        default_duration=p.default_duration,
-        min_duration=p.min_duration,
-        max_duration=p.max_duration,
-    )
-
-
-def _validate_transition(effect: str, duration: Optional[float] = None) -> tuple[str, float]:
-    """验证转场效果和时长，返回 (effect, duration)"""
-    preset = get_transition_preset(effect)
-    if preset is None:
-        raise ValueError(f"无效的转场效果: {effect}")
-
-    # 硬切特殊处理，时长强制为0
-    if effect == "transition_none" or preset.transition == "none":
-        return "cut", 0.0
-
-    final_duration = duration if duration is not None else preset.default_duration
-    if final_duration < preset.min_duration:
-        final_duration = preset.min_duration
-    if final_duration > preset.max_duration:
-        final_duration = preset.max_duration
-
-    return preset.transition, round(final_duration, 3)
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-@router.get("/transition-presets", response_model=TransitionPresetListResponse, deprecated=True)
-def list_presets(
-    category: Optional[str] = Query(default=None, description="按分类筛选"),
-    keyword: Optional[str] = Query(default=None, description="关键词搜索"),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-) -> TransitionPresetListResponse:
-    """获取转场预设列表"""
-    presets = list_transition_presets(category=category, keyword=keyword)
-    items = [_preset_to_response(p) for p in presets]
-    return TransitionPresetListResponse(items=items, total=len(items))
-
-
-@router.put("/clips/{clip_id}/transition", response_model=ClipTransitionResponse, deprecated=True)
-def update_clip_transition(
-    clip_id: str,
-    body: TransitionUpdateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipTransitionResponse:
-    """设置单个片段的转场效果"""
-    svc = EditPlanService(db)
-    clip = svc.get_clip(clip_id)
-    if not clip:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"片段不存在: {clip_id}",
-        )
-
-    plan = svc.get_plan(clip.plan_id)
-    if plan and plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 验证转场参数
-    try:
-        effect, duration = _validate_transition(body.effect, body.duration)
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-
-    # 更新片段
-    updated_clip = svc.update_clip(
-        clip_id,
-        transition_effect=effect,
-        transition_duration=duration,
-    )
-
-    logger.info(
-        "更新片段转场: clip_id=%s effect=%s duration=%.3f by user=%s",
-        clip_id,
-        effect,
-        duration,
-        current_user.user.id,
-    )
-    return ClipTransitionResponse(
-        clip_id=clip_id,
-        effect=updated_clip.transition_effect,
-        duration=updated_clip.transition_duration,
-    )
-
-
-@router.post("/{plan_id}/transitions/batch", response_model=BatchTransitionResponse, deprecated=True)
-def batch_update_transitions(
-    plan_id: str,
-    body: BatchTransitionRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> BatchTransitionResponse:
-    """批量设置计划内所有片段的转场效果
-
-    apply_to 说明：
-    - all: 所有片段
-    - except_first: 除第一个片段外（第一个片段不需要前转场）
-    - except_last: 除最后一个片段外
-    - middle: 只设置中间片段（除首尾）
-    """
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 验证转场参数
-    try:
-        effect, duration = _validate_transition(body.effect, body.duration)
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-
-    # 获取所有片段
-    clips = svc.list_clips(plan_id, limit=500, skip=0)
-    if not clips:
-        return BatchTransitionResponse(updated_count=0, plan_id=plan_id)
-
-    # 确定应用范围
-    total = len(clips)
-    if total <= 1:
-        # 只有一个片段时，只有 all 模式才应用
-        if body.apply_to != "all":
-            return BatchTransitionResponse(updated_count=0, plan_id=plan_id)
-
-    # 按 order 排序
-    clips_sorted = sorted(clips, key=lambda c: c.order)
-    indices_to_update = []
-
-    if body.apply_to == "all":
-        indices_to_update = list(range(total))
-    elif body.apply_to == "except_first":
-        indices_to_update = list(range(1, total))
-    elif body.apply_to == "except_last":
-        indices_to_update = list(range(total - 1))
-    elif body.apply_to == "middle":
-        if total <= 2:
-            indices_to_update = []
-        else:
-            indices_to_update = list(range(1, total - 1))
-    else:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"无效的 apply_to: {body.apply_to}",
-        )
-
-    # 批量更新
-    count = 0
-    for idx in indices_to_update:
-        clip = clips_sorted[idx]
-        svc.update_clip(
-            clip.id,
-            transition_effect=effect,
-            transition_duration=duration,
-        )
-        count += 1
-
-    logger.info(
-        "批量更新转场: plan_id=%s count=%d effect=%s apply_to=%s by user=%s",
-        plan_id,
-        count,
-        effect,
-        body.apply_to,
-        current_user.user.id,
-    )
-    return BatchTransitionResponse(updated_count=count, plan_id=plan_id)
@@ -30,6 +30,7 @@ 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 (
@@ -59,6 +60,7 @@ def _to_generation_task_response(task) -> GenerationTaskResponse:
        asset_select_mode=getattr(task, "asset_select_mode", ""),
        batch_id=getattr(task, "batch_id", ""),
        video_title=getattr(task, "video_title", ""),
+        resolution=getattr(task, "resolution", ""),
        logs=getattr(task, "logs", "[]"),
        status=task.status,
        progress=task.progress,
@@ -104,7 +106,7 @@ def _select_assets_from_library(

    Args:
        assets: 素材库中所有素材（Asset 实体列表）
-        mode: 选取模式 — all=全部, random=随机, smart=按质量评分
+        mode: 选取模式 — all=全部, random=随机, smart=智能匹配（多维度评分+多样性）
        count: 选取数量，0 表示全部（仅 random/smart 模式有效）

    Returns:
@@ -122,17 +124,19 @@ def _select_assets_from_library(
        return [a.id for a in selected]

    if mode == "smart":
-        # 按质量分降序排列（质量分高的优先），质量分相同时按时长降序
-        sorted_assets = sorted(
+        # 智能匹配：按质量分降序 + 时长降序作为tiebreaker
+        # 注意：这里使用简单的 quality_score 排序保持向后兼容
+        # 更复杂的4维评分+多样性策略由 SmartAssetSelector 服务提供（用于 AI 精选等场景）
+        scored_assets = sorted(
            ready_video_assets,
            key=lambda a: (
-                a.quality_score if a.quality_score is not None else 0.0,
-                a.duration if a.duration is not None else 0.0,
+                -(a.quality_score if a.quality_score is not None else 0.0),
+                -(getattr(a, "duration", 0.0) or 0.0),
            ),
-            reverse=True,
        )
-        selected = sorted_assets if count <= 0 else sorted_assets[:count]
-        return [a.id for a in selected]
+        if count > 0:
+            scored_assets = scored_assets[:count]
+        return [a.id for a in scored_assets]

    # 默认 all 模式：返回全部 ready 视频素材
    return [a.id for a in ready_video_assets]
@@ -223,6 +227,20 @@ def create_generation_task(
                mode=request.asset_select_mode,
                count=request.asset_select_count,
            )
+    elif project_id and not resolved_asset_ids and request.asset_select_mode in ("random", "smart"):
+        # 项目级模式：未指定 asset_ids 且选择了 random/smart 模式时，也自动选取
+        assets = asset_repository.find_by_project(project_id)
+        if assets:
+            resolved_asset_ids = _select_assets_from_library(
+                assets,
+                mode=request.asset_select_mode,
+                count=request.asset_select_count,
+            )
+            if not resolved_asset_ids:
+                raise HTTPException(
+                    status_code=422,
+                    detail="当前项目没有符合条件的视频素材，请先上传并等待导入完成后再生成。",
+                )

    use_case = CreateGenerationTaskUseCase(generation_task_repository)
    count = request.count
@@ -270,6 +288,7 @@ def create_generation_task(
                    asset_select_mode=request.asset_select_mode,
                    batch_id=batch_id,
                    video_title=request.video_title,
+                    resolution=request.resolution,
                    auto_retry_enabled=request.auto_retry_enabled,
                    auto_retry_max=request.auto_retry_max,
                )
@@ -408,6 +427,7 @@ def retry_generation_task(
            source_edit_plan_id=task.source_edit_plan_id or "",
            asset_select_mode=getattr(task, "asset_select_mode", ""),
            video_title=getattr(task, "video_title", ""),
+            resolution=getattr(task, "resolution", ""),
        )
    )
    try:
@@ -0,0 +1,298 @@
+"""视频分享 API 路由."""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from app.api.routes._helpers import format_utc_datetime
+from app.auth import AuthenticatedUser, get_current_user
+from app.core.storage import OSSStorageService, get_storage_service
+from app.dependencies import get_db_session, get_generated_video_repository
+from app.schemas.video_share import (
+    CreateShareRequest,
+    ShareAccessResponse,
+    ShareListResponse,
+    ShareMetaResponse,
+    ShareResponse,
+    UpdateShareRequest,
+    VerifySharePasswordRequest,
+)
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.video_share_repository import (
+    SQLAlchemyVideoShareRepository,
+)
+from packages.application.video_share.commands import (
+    CreateShareCommand,
+    UpdateShareCommand,
+)
+from packages.application.video_share.use_cases import (
+    AccessShareUseCase,
+    CreateShareUseCase,
+    GetShareByTokenUseCase,
+    InvalidPasswordError,
+    ListSharesByUserUseCase,
+    ListSharesByVideoUseCase,
+    NotFoundError,
+    PasswordRequiredError,
+    RecordShareDownloadUseCase,
+    RevokeShareUseCase,
+    ShareExpiredError,
+    UpdateShareUseCase,
+    VideoNotFoundError,
+)
+from packages.ports.generated_video_repository import GeneratedVideoRepository
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _get_share_repository(
+    session: Session = Depends(get_db_session),
+) -> SQLAlchemyVideoShareRepository:
+    return SQLAlchemyVideoShareRepository(session)
+
+
+def _to_share_response(share) -> ShareResponse:
+    return ShareResponse(
+        id=share.id,
+        video_id=share.video_id,
+        share_token=share.share_token,
+        has_password=share.has_password,
+        expires_at=share.expires_at,
+        view_count=share.view_count,
+        download_count=share.download_count,
+        is_active=share.is_active,
+        created_at=format_utc_datetime(share.created_at),
+        updated_at=format_utc_datetime(share.updated_at),
+    )
+
+
+# ── 用户侧：创建/管理分享 ──────────────────────────────────
+
+
+@router.post("/videos/{video_id}/share", response_model=ShareResponse)
+def create_share(
+    video_id: str,
+    request: CreateShareRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+    video_repo: GeneratedVideoRepository = Depends(get_generated_video_repository),
+) -> ShareResponse:
+    """为视频创建分享链接."""
+    use_case = CreateShareUseCase(share_repo, video_repo)
+    try:
+        share = use_case.execute(
+            CreateShareCommand(
+                video_id=video_id,
+                user_id=authenticated_user.user.id,
+                password=request.password,
+                expires_at=request.expires_at,
+            )
+        )
+    except VideoNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+    logger.info(
+        "Share created: video_id=%s share_id=%s token=%s user=%s",
+        video_id,
+        share.id,
+        share.share_token,
+        authenticated_user.user.id,
+    )
+    return _to_share_response(share)
+
+
+@router.get("/videos/{video_id}/shares", response_model=ShareListResponse)
+def list_video_shares(
+    video_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+) -> ShareListResponse:
+    """获取某个视频的所有分享记录."""
+    use_case = ListSharesByVideoUseCase(share_repo)
+    items = use_case.execute(video_id, authenticated_user.user.id)
+    return ShareListResponse(
+        items=[_to_share_response(s) for s in items],
+        total=len(items),
+        skip=0,
+        limit=len(items),
+    )
+
+
+@router.get("/shares", response_model=ShareListResponse)
+def list_user_shares(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(20, ge=1, le=100),
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+) -> ShareListResponse:
+    """获取用户创建的所有分享记录."""
+    use_case = ListSharesByUserUseCase(share_repo)
+    items, total = use_case.execute(authenticated_user.user.id, skip=skip, limit=limit)
+    return ShareListResponse(
+        items=[_to_share_response(s) for s in items],
+        total=total,
+        skip=skip,
+        limit=limit,
+    )
+
+
+@router.patch("/shares/{share_id}", response_model=ShareResponse)
+def update_share(
+    share_id: str,
+    request: UpdateShareRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+) -> ShareResponse:
+    """更新分享配置（密码、有效期等）."""
+    use_case = UpdateShareUseCase(share_repo)
+    try:
+        share = use_case.execute(
+            UpdateShareCommand(
+                share_id=share_id,
+                user_id=authenticated_user.user.id,
+                password=request.password,
+                expires_at=request.expires_at,
+            )
+        )
+    except NotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+    return _to_share_response(share)
+
+
+@router.delete(
+    "/shares/{share_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    response_model=None,
+    response_class=Response,
+)
+def revoke_share(
+    share_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+) -> Response:
+    """撤销/删除分享链接."""
+    use_case = RevokeShareUseCase(share_repo)
+    try:
+        use_case.execute(share_id, authenticated_user.user.id)
+    except NotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+# ── 公开侧：访问分享内容（无需登录） ──────────────────────
+
+
+@router.get("/share/{token}/meta", response_model=ShareMetaResponse)
+def get_share_meta(
+    token: str,
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+    video_repo: GeneratedVideoRepository = Depends(get_generated_video_repository),
+    storage: OSSStorageService = Depends(get_storage_service),
+) -> ShareMetaResponse:
+    """获取分享元信息（不需要密码，用于分享页加载前判断）。"""
+    use_case = GetShareByTokenUseCase(share_repo)
+    try:
+        share = use_case.execute(token)
+    except (NotFoundError, ShareExpiredError) as e:
+        raise HTTPException(status_code=404, detail="分享链接不存在或已失效") from e
+
+    video = video_repo.get(share.video_id)
+    video_name = video.name if video else ""
+    video_duration = video.duration if video else 0.0
+    thumbnail_url = None
+    if video and video.thumbnail_url:
+        try:
+            thumbnail_url = storage.get_download_url(video.thumbnail_url)
+        except Exception:
+            thumbnail_url = video.thumbnail_url
+
+    return ShareMetaResponse(
+        share_token=share.share_token,
+        has_password=share.has_password,
+        is_expired=share.is_expired,
+        is_active=share.is_active,
+        video_name=video_name,
+        video_duration=video_duration,
+        thumbnail_url=thumbnail_url,
+        created_at=format_utc_datetime(share.created_at),
+    )
+
+
+@router.post("/share/{token}/access", response_model=ShareAccessResponse)
+def access_share(
+    token: str,
+    request: Optional[VerifySharePasswordRequest] = None,
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+    video_repo: GeneratedVideoRepository = Depends(get_generated_video_repository),
+    storage: OSSStorageService = Depends(get_storage_service),
+) -> ShareAccessResponse:
+    """访问分享内容（验证密码后返回视频信息+播放/下载地址）。"""
+    use_case = AccessShareUseCase(share_repo, video_repo)
+    password = request.password if request else None
+    try:
+        result = use_case.execute(token, password=password)
+    except NotFoundError as e:
+        raise HTTPException(status_code=404, detail="分享链接不存在或已失效") from e
+    except ShareExpiredError as e:
+        raise HTTPException(status_code=410, detail="分享链接已过期或已撤销") from e
+    except PasswordRequiredError as e:
+        raise HTTPException(status_code=403, detail="需要访问密码") from e
+    except InvalidPasswordError as e:
+        raise HTTPException(status_code=403, detail="密码错误") from e
+    except VideoNotFoundError as e:
+        raise HTTPException(status_code=404, detail="视频不存在") from e
+
+    # 生成下载URL
+    download_url = None
+    if result.video.file_url:
+        try:
+            download_url = storage.get_download_url(result.video.file_url)
+        except Exception:
+            download_url = result.video.file_url
+
+    # 缩略图URL
+    thumbnail_url = None
+    if result.video.thumbnail_url:
+        try:
+            thumbnail_url = storage.get_download_url(result.video.thumbnail_url)
+        except Exception:
+            thumbnail_url = result.video.thumbnail_url
+
+    return ShareAccessResponse(
+        share=_to_share_response(result.share),
+        video_name=result.video.name,
+        video_duration=result.video.duration,
+        video_size=result.video.file_size,
+        thumbnail_url=thumbnail_url,
+        download_url=download_url,
+        password_verified=result.password_verified,
+    )
+
+
+@router.post("/share/{token}/download")
+def record_share_download(
+    token: str,
+    request: Optional[VerifySharePasswordRequest] = None,
+    share_repo: SQLAlchemyVideoShareRepository = Depends(_get_share_repository),
+) -> dict:
+    """记录分享下载（下载计数+1）。"""
+    use_case = RecordShareDownloadUseCase(share_repo)
+    password = request.password if request else None
+    try:
+        use_case.execute(token, password=password)
+    except NotFoundError as e:
+        raise HTTPException(status_code=404, detail="分享链接不存在或已失效") from e
+    except ShareExpiredError as e:
+        raise HTTPException(status_code=410, detail="分享链接已过期或已撤销") from e
+    except InvalidPasswordError as e:
+        raise HTTPException(status_code=403, detail="密码错误") from e
+    return {"success": True}
@@ -23,60 +23,462 @@
 from __future__ import annotations

 import logging
+import re as _re
 from typing import Any, List, Optional

-from app.api.routes.edit_plans import (
-    AIRecommendRequest,
-    AIRecommendResponse,
-    BGMConfigUpdateRequest,
-    ClipStatusItem,
-    EditPlanGenerateResponse,
-    EditPlanGenerationsResponse,
-    EditPlanGenerationStatusResponse,
-    GenerateCoverRequest,
-    GenerateCoverResponse,
-)
-from app.api.routes.edit_plans_adjustments import (
-    BatchSpeedRequest,
-    BatchSpeedResponse,
-    ClipAdjustmentsRequest,
-    ClipAdjustResponse,
-    SpeedAdjustRequest,
-    TrimAdjustRequest,
-    VolumeAdjustRequest,
-)
-from app.api.routes.edit_plans_clips_batch import (
-    ClipBatchDeleteRequest,
-    ClipBatchDeleteResponse,
-    ClipReorderRequest,
-    ClipReorderResponse,
-    ClipsFromAssetsRequest,
-    ClipsFromAssetsResponse,
-)
-from app.api.routes.edit_plans_cover import (
-    CoverConfigResponse,
-    CoverExtractRequest,
-    CoverGenerateResponse,
-    CoverSmartRequest,
-    CoverUpdateRequest,
-)
-from app.api.routes.edit_plans_export import (
-    ExportConfigResponse,
-    ExportPresetListResponse,
-    ExportUpdateRequest,
-)
-from app.api.routes.edit_plans_filter import (
-    FilterConfigResponse,
-    FilterPresetListResponse,
-    FilterUpdateRequest,
-)
-from app.api.routes.edit_plans_transitions import (
-    BatchTransitionRequest,
-    BatchTransitionResponse,
-    ClipTransitionResponse,
-    TransitionPresetListResponse,
-    TransitionUpdateRequest,
-)
+from app.schemas.generation_task import GenerationTaskResponse
+from pydantic import BaseModel, Field, validator
+
+# ── Pydantic Schemas (migrated from edit_plans*) ────────────────────────────
+
+
+# ── From edit_plans.py ──────────────────────────────────────────────────────
+
+
+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
+
+
+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 等）")
+
+
+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="闪避音量降低比例")
+
+
+# ── From edit_plans_adjustments.py ──────────────────────────────────────────
+
+
+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
+
+
+# ── From edit_plans_clips_batch.py ──────────────────────────────────────────
+
+
+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
+    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
+    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
+    created_count: int
+    message: str = ""
+    clip_ids: List[str] = Field(default_factory=list, description="创建的片段ID列表")
+
+
+# ── From edit_plans_cover.py ────────────────────────────────────────────────
+
+
+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="抽帧时间点（秒）")
+
+
+# ── From edit_plans_export.py ───────────────────────────────────────────────
+
+_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 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
+
+
+# ── From edit_plans_filter.py ───────────────────────────────────────────────
+
+
+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
+
+
+# ── From edit_plans_transitions.py ──────────────────────────────────────────
+
+
+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
+
+
 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
@@ -89,7 +491,6 @@ from app.dependencies import (
 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 pydantic import BaseModel, Field
 from sqlalchemy.orm import Session

 from packages.adapters.sqlalchemy_impl.generation_task_repository import (
@@ -238,19 +639,84 @@ 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, _ = services
-    draft = tpl_svc.get_or_create_draft(
-        template_id,
-        user_id=str(current_user.user_id),
+    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,
    )
-    return draft.id
+
+    # 将旧模板 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


 # ── 草稿核心端点 ────────────────────────────────────────────────────────────
@@ -683,7 +1149,7 @@ def update_editor_bgm(
        template_id,
        plan_id,
        current_bgm.get("enabled", False),
-        current_user.user_id,
+        current_user.user.id,
    )

    return {
@@ -931,7 +1397,7 @@ def generate_editor_draft(
        clip_count = plan_svc.mark_clips_ready(plan_id)

        gen_task_repo = SQLAlchemyGenerationTaskRepository(db)
-        user_id = current_user.user_id
+        user_id = current_user.user.id
        _check_queue_limits(gen_task_repo, user_id)

        gen_task_use_case = CreateGenerationTaskUseCase(gen_task_repo)
@@ -941,7 +1407,7 @@ def generate_editor_draft(
            CreateGenerationTaskCommand(
                project_id=plan.project_id or "",
                template_id=plan.template_id,
-                created_by_user_id=current_user.user_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 [],
            ),
@@ -959,7 +1425,7 @@ def generate_editor_draft(
            plan_id,
            gen_task.id,
            clip_count,
-            current_user.user_id,
+            current_user.user.id,
        )

        return EditPlanGenerateResponse(
@@ -1490,7 +1956,7 @@ def editor_ai_recommend(
        plan_id,
        len(result["clips"]),
        result["total_duration"],
-        current_user.user_id,
+        current_user.user.id,
    )

    return AIRecommendResponse(
@@ -1545,7 +2011,7 @@ def editor_generate_cover(
        template_id,
        plan_id,
        body.cover_type,
-        current_user.user_id,
+        current_user.user.id,
    )

    return GenerateCoverResponse(plan_id=plan_id, cover=cover_data)
@@ -1961,7 +2427,7 @@ def extract_editor_cover(
        template_id,
        plan_id,
        body.clip_id,
-        current_user.user_id,
+        current_user.user.id,
    )

    return CoverGenerateResponse(
@@ -2003,7 +2469,7 @@ def smart_editor_cover(
        template_id,
        plan_id,
        body.strategy,
-        current_user.user_id,
+        current_user.user.id,
    )

    return CoverGenerateResponse(
@@ -2084,7 +2550,7 @@ def create_clips_from_assets_editor(
        template_id,
        plan_id,
        len(clips),
-        current_user.user_id,
+        current_user.user.id,
    )

    return ClipsFromAssetsResponse(
@@ -113,7 +113,7 @@ def update_video_review_status(
    if item is None:
        raise HTTPException(status_code=404, detail="Video not found")
    logger.info(
-        "Video %s review status updated to %s by user %s", video_id, request.review_status, current_user.user_id
+        "Video %s review status updated to %s by user %s", video_id, request.review_status, current_user.user.id
    )
    return _to_video_response(item, storage)

@@ -197,7 +197,7 @@ def batch_download_videos(
    # 发送 celery 任务
    task = celery_app.send_task(
        "worker.batch_download_videos",
-        args=[request.video_ids, current_user.user_id],
+        args=[request.video_ids, current_user.user.id],
    )

    logger.info("Batch download job created: %s, videos=%d", task.id, len(request.video_ids))
@@ -46,6 +46,11 @@ class CreateGenerationTaskRequest(BaseModel):
        le=5,
        description="最大自动重试次数，0表示不自动重试，最大5次",
    )
+    # ── 输出分辨率 ──
+    resolution: str = Field(
+        default="",
+        description="输出分辨率，格式为 WIDTHxHEIGHT，如 1280x720、1080x1920。为空使用默认 1280x720",
+    )

    @model_validator(mode="after")
    def _check_at_least_one_mode(self) -> "CreateGenerationTaskRequest":
@@ -74,6 +79,7 @@ class GenerationTaskResponse(BaseModel):
    asset_select_mode: str = ""
    batch_id: str = ""
    video_title: str = ""
+    resolution: str = ""
    status: str
    progress: float
    result_count: int
@@ -0,0 +1,92 @@
+"""视频分享相关 schemas."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class CreateShareRequest(BaseModel):
+    """创建分享请求."""
+
+    password: Optional[str] = Field(
+        None,
+        description="访问密码（可选，不设置则无需密码）",
+        min_length=0,
+        max_length=50,
+    )
+    expires_at: Optional[datetime] = Field(
+        None,
+        description="过期时间（可选，不设置则永久有效）",
+    )
+
+
+class UpdateShareRequest(BaseModel):
+    """更新分享配置请求."""
+
+    password: Optional[str] = Field(
+        None,
+        description="新密码（传空字符串清除密码，不传则不修改）",
+        max_length=50,
+    )
+    expires_at: Optional[datetime] = Field(
+        None,
+        description="新的过期时间（不传则不修改）",
+    )
+
+
+class VerifySharePasswordRequest(BaseModel):
+    """验证分享密码请求."""
+
+    password: str = Field(..., description="访问密码")
+
+
+class ShareResponse(BaseModel):
+    """分享记录响应."""
+
+    id: str
+    video_id: str
+    share_token: str
+    has_password: bool = False
+    expires_at: Optional[datetime] = None
+    view_count: int = 0
+    download_count: int = 0
+    is_active: bool = True
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+
+class ShareListResponse(BaseModel):
+    """分享列表响应."""
+
+    items: List[ShareResponse]
+    total: int = 0
+    skip: int = 0
+    limit: int = 20
+
+
+class ShareAccessResponse(BaseModel):
+    """分享访问成功响应（含视频信息）."""
+
+    share: ShareResponse
+    video_name: str
+    video_duration: float = 0.0
+    video_size: int = 0
+    thumbnail_url: Optional[str] = None
+    download_url: Optional[str] = None
+    password_verified: bool = True
+
+
+class ShareMetaResponse(BaseModel):
+    """分享元信息响应（访问前获取，用于判断是否需要密码）。"""
+
+    share_token: str
+    has_password: bool = False
+    is_expired: bool = False
+    is_active: bool = True
+    video_name: str = ""
+    video_duration: float = 0.0
+    thumbnail_url: Optional[str] = None
+    created_at: Optional[datetime] = None
@@ -0,0 +1,535 @@
+"""统一 AI 服务层 — 豆包大模型接入.
+
+提供基于字节跳动豆包大模型的 AI 能力：
+- 智能标题生成（爆款/情感/信息三种风格）
+- 后续扩展：智能素材匹配、AI 推荐片段编排等
+
+设计原则：
+1. 无 API Key 或调用失败时自动降级为本地模拟，不阻塞主流程
+2. 统一的客户端封装，新增能力只需加方法
+3. 所有模型相关配置集中在 Settings
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import random
+from typing import Any, Dict, List, Optional
+
+from packages.shared.ai_client import get_doubao_client
+
+logger = logging.getLogger(__name__)
+
+
+# ── 智能标题风格定义 ─────────────────────────────────────────────────────────
+
+TITLE_STYLES = {
+    "viral": {
+        "name": "爆款",
+        "description": "吸引点击、引发好奇的爆款标题，带有数字、疑问或反差感",
+        "examples": [
+            "3个方法让你效率翻倍，第2个最绝",
+            "为什么越努力越穷？真相扎心了",
+            "看完这个，我删掉了手机里一半的APP",
+        ],
+    },
+    "emotional": {
+        "name": "情感",
+        "description": "触动人心、引发共鸣的情感向标题",
+        "examples": [
+            "那些年我们一起追过的梦想",
+            "生活不易，但请相信光",
+            "致每一个在城市里打拼的你",
+        ],
+    },
+    "informative": {
+        "name": "信息",
+        "description": "清晰直白、传递核心信息的干货标题",
+        "examples": [
+            "2026年最新个税政策解读，一文讲透",
+            "新手剪辑入门：从0到1完整指南",
+            "产品对比：10款热门手机深度评测",
+        ],
+    },
+}
+
+
+# ── 智能标题生成 ─────────────────────────────────────────────────────────────
+
+
+def _generate_titles_fallback(
+    description: str,
+    style: str = "viral",
+    count: int = 5,
+) -> List[str]:
+    """本地降级：基于模板规则生成标题.
+
+    当豆包 API 不可用或调用失败时使用，保证接口始终有返回。
+    """
+    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
+
+
+def generate_smart_titles(
+    description: str,
+    style: str = "viral",
+    count: int = 5,
+) -> Dict[str, Any]:
+    """生成智能标题.
+
+    Args:
+        description: 视频内容描述
+        style: 标题风格 viral/emotional/informative
+        count: 生成数量（5-10）
+
+    Returns:
+        {
+            "titles": [...],
+            "style": "viral",
+            "source": "doubao" | "fallback",  # 实际来源
+            "description": "...",
+        }
+    """
+    # 参数校验与边界处理
+    if style not in TITLE_STYLES:
+        style = "viral"
+    count = max(3, min(10, count))  # 3-10 个
+    description = (description or "").strip()
+
+    client = get_doubao_client()
+    if not client.is_available:
+        logger.info("豆包API未配置，使用本地降级生成标题")
+        titles = _generate_titles_fallback(description, style, count)
+        return {
+            "titles": titles,
+            "style": style,
+            "source": "fallback",
+            "description": description,
+        }
+
+    style_info = TITLE_STYLES[style]
+    system_prompt = (
+        f"你是一个专业的短视频标题创作专家，擅长根据视频内容生成吸引人的标题。\n"
+        f"请根据以下视频描述，生成{count}个{style_info['name']}风格的标题。\n"
+        f"风格说明：{style_info['description']}\n"
+        f"要求：\n"
+        f"1. 每个标题控制在8-25字之间\n"
+        f"2. 直接返回JSON数组格式，不要其他文字\n"
+        f"3. 标题要贴合内容，有吸引力"
+    )
+
+    user_prompt = f"视频描述：{description}\n\n请生成标题："
+
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_prompt},
+    ]
+
+    result = client.chat_completion(
+        messages=messages,
+        temperature=0.8,
+        max_tokens=512,
+    )
+
+    if result:
+        titles = _parse_titles_from_response(result)
+        if len(titles) >= 2:  # 至少解析出2个才算成功
+            titles = titles[:count]
+            logger.info(
+                "豆包智能标题生成成功: style=%s count=%d description=%s...",
+                style,
+                len(titles),
+                description[:20],
+            )
+            return {
+                "titles": titles,
+                "style": style,
+                "source": "doubao",
+                "description": description,
+            }
+        logger.warning("豆包返回内容解析失败，降级到本地生成: %s", result[:100])
+
+    # 降级到本地生成
+    titles = _generate_titles_fallback(description, style, count)
+    return {
+        "titles": titles,
+        "style": style,
+        "source": "fallback",
+        "description": description,
+    }
+
+
+# ── 智能素材语义匹配 ───────────────────────────────────────────────────────────
+
+
+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
+
+
+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:
+        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
+
+
+def semantic_match_assets(
+    description: str,
+    assets: List[Dict[str, Any]],
+    top_k: int = 0,
+) -> Dict[str, Any]:
+    """智能素材语义匹配.
+
+    根据用户描述，评估每个素材的语义匹配度并排序。
+
+    Args:
+        description: 用户描述的目标视频内容
+        assets: 素材列表，每个素材需含 id/name/tags/description 等字段
+        top_k: 返回前K个，0表示返回全部
+
+    Returns:
+        {
+            "matches": [{"asset_id": ..., "match_score": ..., ...}],
+            "source": "doubao" | "fallback",
+            "description": "...",
+            "total": 总数,
+        }
+    """
+    description = (description or "").strip()
+    if not assets:
+        return {"matches": [], "source": "fallback", "description": description, "total": 0}
+
+    client = get_doubao_client()
+    if not client.is_available:
+        logger.info("豆包API未配置，使用本地降级做素材语义匹配")
+        matched = _semantic_match_fallback(description, assets)
+        if top_k > 0:
+            matched = matched[:top_k]
+        return {
+            "matches": matched,
+            "source": "fallback",
+            "description": description,
+            "total": len(assets),
+        }
+
+    # 构建素材信息（控制 token 数量）
+    asset_summaries = []
+    for asset in assets[:50]:  # 最多传50个素材给模型
+        aid = asset.get("id", "")
+        name = asset.get("name", "")[:50]
+        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_ids = [str(a.get("id", "")) for a in assets[:50]]
+
+    system_prompt = (
+        "你是一个专业的视频素材匹配助手。"
+        "根据用户的视频目标描述，评估每个素材的匹配程度。\n"
+        "评分规则：\n"
+        "- 0.0-0.3: 完全不相关\n"
+        "- 0.3-0.6: 有一定关联但不够匹配\n"
+        "- 0.6-0.8: 比较匹配，适合使用\n"
+        "- 0.8-1.0: 高度匹配，非常适合\n"
+        "只返回JSON对象，key为素材ID，value为匹配分数（0-1之间的小数）。"
+        "不要其他文字说明。"
+    )
+
+    user_prompt = (
+        f"目标视频描述：{description}\n\n"
+        f"素材列表：\n" + "\n".join(asset_summaries) +
+        f"\n\n请返回每个素材的匹配分数JSON："
+    )
+
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_prompt},
+    ]
+
+    result = client.chat_completion(
+        messages=messages,
+        temperature=0.3,
+        max_tokens=1024,
+    )
+
+    if result:
+        scores = _parse_semantic_match_response(result, asset_ids)
+        if scores:
+            # 把评分填回素材
+            matched = []
+            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.sort(key=lambda x: x["match_score"], reverse=True)
+
+            logger.info(
+                "豆包语义匹配完成: assets=%d top_score=%.2f description=%s...",
+                len(matched),
+                matched[0]["match_score"] if matched else 0,
+                description[:20],
+            )
+
+            if top_k > 0:
+                matched = matched[:top_k]
+
+            return {
+                "matches": matched,
+                "source": "doubao",
+                "description": description,
+                "total": len(assets),
+            }
+        logger.warning("豆包语义匹配返回解析失败，降级到本地: %s", result[:100])
+
+    # 降级
+    matched = _semantic_match_fallback(description, assets)
+    if top_k > 0:
+        matched = matched[:top_k]
+    return {
+        "matches": matched,
+        "source": "fallback",
+        "description": description,
+        "total": len(assets),
+    }
+
+
+# ── 单例入口 ─────────────────────────────────────────────────────────────────
+
+
+def get_ai_service() -> "AIService":
+    """获取 AI 服务单例."""
+    global _ai_service
+    if _ai_service is None:
+        _ai_service = AIService()
+    return _ai_service
+
+
+_ai_service: Optional["AIService"] = None
+
+
+class AIService:
+    """AI 服务统一入口，便于后续扩展更多能力."""
+
+    def __init__(self) -> None:
+        self._client = get_doubao_client()
+
+    @property
+    def is_available(self) -> bool:
+        return self._client.is_available
+
+    def generate_titles(
+        self,
+        description: str,
+        style: str = "viral",
+        count: int = 5,
+    ) -> Dict[str, Any]:
+        return generate_smart_titles(description, style, count)
+
+    def semantic_match(
+        self,
+        description: str,
+        assets: List[Dict[str, Any]],
+        top_k: int = 0,
+    ) -> Dict[str, Any]:
+        return semantic_match_assets(description, assets, top_k)
@@ -39,70 +39,6 @@ class EditPlanService:

    # ── 剪辑计划 CRUD ──────────────────────────────────────────────────────

-    def list_plans(
-        self,
-        *,
-        template_id: Optional[str] = None,
-        project_id: Optional[str] = None,
-        status: Optional[EditPlanStatus] = None,
-        skip: int = 0,
-        limit: int = 50,
-    ) -> List[EditPlan]:
-        """列出剪辑计划
-
-        Args:
-            template_id: 按模板 ID 筛选
-            project_id: 按项目 ID 筛选
-            status: 按状态筛选
-            skip: 分页偏移
-            limit: 每页数量
-        """
-        if project_id:
-            return self._plan_repo.list_by_project(
-                project_id,
-                status=status,
-                skip=skip,
-                limit=limit,
-            )
-        if template_id:
-            return self._plan_repo.list_by_template(
-                template_id,
-                status=status,
-                skip=skip,
-                limit=limit,
-            )
-        return self._plan_repo.list_all(status=status, skip=skip, limit=limit)
-
-    def count_plans(
-        self,
-        *,
-        template_id: Optional[str] = None,
-        project_id: Optional[str] = None,
-        status: Optional[EditPlanStatus] = None,
-    ) -> int:
-        """统计计划数量
-
-        Note:
-            当指定 template_id/project_id 时，通过全量查询计算 total（repo 限制）。
-        """
-        if project_id:
-            all_matching = self._plan_repo.list_by_project(
-                project_id,
-                status=status,
-                skip=0,
-                limit=10000,
-            )
-            return len(all_matching)
-        if template_id:
-            all_matching = self._plan_repo.list_by_template(
-                template_id,
-                status=status,
-                skip=0,
-                limit=10000,
-            )
-            return len(all_matching)
-        return self._plan_repo.count(status=status)
-
    def get_plan(self, plan_id: str) -> Optional[EditPlan]:
        """获取计划详情"""
        return self._plan_repo.get(plan_id)
@@ -124,7 +60,7 @@ class EditPlanService:
        project_id: str = "",
        created_by_user_id: str = "",
    ) -> EditPlan:
-        """创建剪辑计划
+        """创建剪辑计划（基础 CRUD，供内部测试与脚本使用）

        Raises:
            ValueError: 参数校验失败
@@ -190,23 +126,6 @@ class EditPlanService:
        logger.info("更新剪辑计划: id=%s", plan_id)
        return result

-    def delete_plan(self, plan_id: str) -> bool:
-        """删除剪辑计划及其所有片段
-
-        Returns:
-            bool: 是否删除成功
-        """
-        existing = self._plan_repo.get(plan_id)
-        if existing is None:
-            return False
-
-        # 先删除所有片段
-        self._clip_repo.delete_by_plan(plan_id)
-        # 再删除计划
-        self._plan_repo.delete(plan_id)
-        logger.info("删除剪辑计划: id=%s", plan_id)
-        return True
-
    # ── 状态机流转 ──────────────────────────────────────────────────────────

    def transition_status(self, plan_id: str, target_status: EditPlanStatus) -> EditPlan:
@@ -447,63 +366,6 @@ class EditPlanService:
        logger.info("删除所有片段: plan_id=%s count=%d", plan_id, count)
        return count

-    def create_clips_from_assets(
-        self,
-        plan_id: str,
-        asset_ids: list[str],
-        *,
-        clip_type: str = "main",
-    ) -> list[EditPlanClip]:
-        """从素材批量创建片段（追加到时间线末尾）。
-
-        Args:
-            plan_id: 计划 ID
-            asset_ids: 素材 ID 列表（按顺序追加）
-            clip_type: 片段类型
-
-        Returns:
-            list[EditPlanClip]: 创建的片段列表
-        """
-        if not asset_ids:
-            return []
-
-        # 确保计划存在 + 自动回退状态
-        self.get_plan_or_raise(plan_id)
-        self._auto_resume_editing(plan_id)
-
-        # 查询素材信息（取 duration）
-        from packages.adapters.sqlalchemy_impl.models import AssetModel
-
-        session = self._clip_repo.session  # type: ignore[attr-defined]
-        assets = session.query(AssetModel).filter(AssetModel.id.in_(asset_ids)).all()
-        asset_map = {a.id: a for a in assets}
-
-        # 从现有片段数量开始追加
-        existing_count = self._clip_repo.count(plan_id=plan_id)
-
-        # 批量创建片段
-        created: list[EditPlanClip] = []
-        for i, asset_id in enumerate(asset_ids):
-            asset = asset_map.get(asset_id)
-            duration = asset.duration if asset and asset.duration else 0.0
-
-            clip = self.create_clip(
-                plan_id=plan_id,
-                clip_type=clip_type,
-                order=existing_count + i,
-                asset_id=asset_id,
-                duration=duration,
-            )
-            created.append(clip)
-
-        logger.info(
-            "从素材批量创建片段: plan_id=%s count=%d",
-            plan_id,
-            len(created),
-        )
-        return created
-
-    # ── 渲染生成流程 ────────────────────────────────────────────────────────
    # ── 片段分割与合并 ──────────────────────────────────────────────────────

    def split_clip(self, clip_id: str, split_time: float) -> Dict[str, Any]:
@@ -674,249 +536,7 @@ class EditPlanService:

        return merged_clip

-    # ── 字幕管理 ──────────────────────────────────────────────────────────
-
-    def list_subtitles(self, clip_id: str) -> List[Dict[str, Any]]:
-        """获取片段的所有字幕
-
-        Returns:
-            List[dict]: 字幕列表，按 start 时间排序
-        """
-        clip = self.get_clip_or_raise(clip_id)
-        config = clip.config or {}
-        subtitles = config.get("subtitles", [])
-        # 按开始时间排序
-        subtitles.sort(key=lambda s: s.get("start", 0))
-        return subtitles
-
-    def get_subtitle(self, clip_id: str, subtitle_id: str) -> Optional[Dict[str, Any]]:
-        """获取单条字幕"""
-        subtitles = self.list_subtitles(clip_id)
-        for s in subtitles:
-            if s.get("id") == subtitle_id:
-                return s
-        return None
-
-    def add_subtitle(
-        self,
-        clip_id: str,
-        start: float,
-        end: float,
-        text: str,
-        *,
-        style: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """添加一条字幕
-
-        Args:
-            clip_id: 片段 ID
-            start: 开始时间（秒，相对于片段）
-            end: 结束时间（秒）
-            text: 字幕文本
-            style: 样式配置（字体、大小、颜色、位置等）
-
-        Returns:
-            dict: 新增的字幕条目
-
-        Raises:
-            ValueError: 时间非法或文本为空
-        """
-        clip = self.get_clip_or_raise(clip_id)
-
-        if start < 0 or end <= start:
-            raise ValueError(f"字幕时间非法: start={start}, end={end}")
-        if not text.strip():
-            raise ValueError("字幕文本不能为空")
-        if end > clip.duration + 0.001:
-            raise ValueError(f"字幕结束时间不能超过片段时长: end={end:.3f}, duration={clip.duration:.3f}")
-
-        self._auto_resume_editing(clip.plan_id)
-
-        from uuid import uuid4
-
-        config = dict(clip.config) if clip.config else {}
-        subtitles = list(config.get("subtitles", []))
-
-        subtitle = {
-            "id": uuid4().hex,
-            "start": round(start, 3),
-            "end": round(end, 3),
-            "text": text.strip(),
-            "style": style or {},
-        }
-        subtitles.append(subtitle)
-        subtitles.sort(key=lambda s: s.get("start", 0))
-
-        config["subtitles"] = subtitles
-        clip.config = config
-        self._clip_repo.update(clip)
-
-        logger.info(
-            "添加字幕: clip_id=%s subtitle_id=%s start=%.3fs end=%.3fs",
-            clip_id,
-            subtitle["id"],
-            start,
-            end,
-        )
-
-        return subtitle
-
-    def update_subtitle(
-        self,
-        clip_id: str,
-        subtitle_id: str,
-        *,
-        start: Optional[float] = None,
-        end: Optional[float] = None,
-        text: Optional[str] = None,
-        style: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """更新一条字幕
-
-        Returns:
-            dict: 更新后的字幕条目
-
-        Raises:
-            ValueError: 字幕不存在或参数非法
-        """
-        clip = self.get_clip_or_raise(clip_id)
-        config = dict(clip.config) if clip.config else {}
-        subtitles = list(config.get("subtitles", []))
-
-        found = False
-        for i, s in enumerate(subtitles):
-            if s.get("id") == subtitle_id:
-                # 更新字段
-                updated_s = dict(s)
-                if start is not None:
-                    updated_s["start"] = round(start, 3)
-                if end is not None:
-                    updated_s["end"] = round(end, 3)
-                if text is not None:
-                    if not text.strip():
-                        raise ValueError("字幕文本不能为空")
-                    updated_s["text"] = text.strip()
-                if style is not None:
-                    updated_s["style"] = style
-
-                # 校验时间
-                if updated_s["start"] < 0 or updated_s["end"] <= updated_s["start"]:
-                    raise ValueError(f"字幕时间非法: start={updated_s['start']}, end={updated_s['end']}")
-                if updated_s["end"] > clip.duration + 0.001:
-                    raise ValueError("字幕结束时间不能超过片段时长")
-
-                subtitles[i] = updated_s
-                found = True
-                break
-
-        if not found:
-            raise ValueError(f"字幕不存在: {subtitle_id}")
-
-        self._auto_resume_editing(clip.plan_id)
-
-        subtitles.sort(key=lambda s: s.get("start", 0))
-        config["subtitles"] = subtitles
-        clip.config = config
-        self._clip_repo.update(clip)
-
-        logger.info("更新字幕: clip_id=%s subtitle_id=%s", clip_id, subtitle_id)
-
-        return subtitles[next(i for i, s in enumerate(subtitles) if s["id"] == subtitle_id)]
-
-    def delete_subtitle(self, clip_id: str, subtitle_id: str) -> bool:
-        """删除一条字幕
-
-        Returns:
-            bool: 是否删除成功
-        """
-        clip = self.get_clip_or_raise(clip_id)
-        config = dict(clip.config) if clip.config else {}
-        subtitles = list(config.get("subtitles", []))
-
-        new_subtitles = [s for s in subtitles if s.get("id") != subtitle_id]
-        if len(new_subtitles) == len(subtitles):
-            return False
-
-        self._auto_resume_editing(clip.plan_id)
-
-        config["subtitles"] = new_subtitles
-        clip.config = config
-        self._clip_repo.update(clip)
-
-        logger.info("删除字幕: clip_id=%s subtitle_id=%s", clip_id, subtitle_id)
-        return True
-
-    def batch_update_subtitles(
-        self,
-        clip_id: str,
-        subtitles: List[Dict[str, Any]],
-    ) -> List[Dict[str, Any]]:
-        """批量更新字幕（全量替换，用于批量编辑或导入）
-
-        Args:
-            clip_id: 片段 ID
-            subtitles: 字幕列表，每条需包含 start/end/text，已有 id 则保留
-
-        Returns:
-            List[dict]: 更新后的字幕列表
-        """
-        clip = self.get_clip_or_raise(clip_id)
-
-        from uuid import uuid4
-
-        validated = []
-        for s in subtitles:
-            start = float(s.get("start", 0))
-            end = float(s.get("end", 0))
-            text = str(s.get("text", ""))
-
-            if start < 0 or end <= start:
-                raise ValueError(f"字幕时间非法: start={start}, end={end}")
-            if not text.strip():
-                continue  # 跳过空字幕
-            if end > clip.duration + 0.001:
-                raise ValueError(f"字幕结束时间不能超过片段时长: end={end}")
-
-            subtitle_id = s.get("id") or uuid4().hex
-            validated.append(
-                {
-                    "id": subtitle_id,
-                    "start": round(start, 3),
-                    "end": round(end, 3),
-                    "text": text.strip(),
-                    "style": s.get("style", {}),
-                }
-            )
-
-        validated.sort(key=lambda s: s["start"])
-
-        self._auto_resume_editing(clip.plan_id)
-
-        config = dict(clip.config) if clip.config else {}
-        config["subtitles"] = validated
-        clip.config = config
-        self._clip_repo.update(clip)
-
-        logger.info(
-            "批量更新字幕: clip_id=%s count=%d",
-            clip_id,
-            len(validated),
-        )
-
-        return validated
-
-    def get_plan_with_clips(self, plan_id: str) -> Dict[str, Any]:
-        """获取计划及其所有片段
-
-        Returns:
-            dict: {"plan": EditPlan, "clips": List[EditPlanClip]}
-        """
-        plan = self.get_plan_or_raise(plan_id)
-        clips = self._clip_repo.list_by_plan(plan_id)
-        return {
-            "plan": plan,
-            "clips": clips,
-        }
+    # ── 渲染生成流程 ────────────────────────────────────────────────────────

    def get_generation_status(self, plan_id: str) -> Dict[str, Any]:
        """获取渲染进度状态
@@ -1026,85 +646,3 @@ class EditPlanService:
            updated_at=plan.updated_at,
        )
        return self._plan_repo.update(updated)
-
-    # ── 复制计划 ────────────────────────────────────────────────────────────
-
-    def copy_plan(
-        self,
-        plan_id: str,
-        *,
-        new_name: Optional[str] = None,
-        project_id: Optional[str] = None,
-    ) -> EditPlan:
-        """复制一个剪辑计划（含所有片段配置）。
-
-        新计划状态为 editing，不含生成任务和结果记录。
-
-        Args:
-            plan_id: 源计划 ID
-            new_name: 新计划名称，不传则为「原名 - 副本」
-            project_id: 新计划的项目 ID，不传则复用源计划
-
-        Returns:
-            EditPlan: 新创建的计划
-
-        Raises:
-            ValueError: 源计划不存在
-        """
-        source = self.get_plan_or_raise(plan_id)
-        source_clips = self._clip_repo.list_by_plan(plan_id)
-
-        # 新计划名称
-        name = new_name or f"{source.name} - 副本"
-        new_project_id = project_id if project_id is not None else source.project_id
-
-        # 复制 plan 配置（去除渲染结果相关字段）
-        new_config = dict(source.config)
-        new_config.pop("rendered_url", None)
-        new_config.pop("rendered_storage_key", None)
-        new_config.pop("generation_task_id", None)
-
-        # 创建新计划
-        new_plan = EditPlan.create(
-            template_id=source.template_id,
-            name=name,
-            config=new_config,
-            total_duration=source.total_duration,
-            project_id=new_project_id,
-            created_by_user_id=source.created_by_user_id,
-            source_edit_plan_id=plan_id,
-        )
-        # 强制切到 editing 状态
-        if new_plan.status != EditPlanStatus.EDITING:
-            try:
-                new_plan.start_editing()
-            except ValueError:
-                pass
-
-        created_plan = self._plan_repo.create(new_plan)
-        logger.info(
-            "复制剪辑计划: source=%s target=%s name=%s clips=%d",
-            plan_id,
-            created_plan.id,
-            name,
-            len(source_clips),
-        )
-
-        # 复制所有片段
-        for clip in source_clips:
-            new_clip = self.create_clip(
-                plan_id=created_plan.id,
-                clip_type=clip.clip_type,
-                order=clip.order,
-                asset_id=clip.asset_id or "",
-                text_content=clip.text_content or "",
-                start_time=clip.start_time,
-                duration=clip.duration,
-                transition_effect=clip.transition_effect or "cut",
-                transition_duration=clip.transition_duration or 0.0,
-                playback_speed=clip.playback_speed or 1.0,
-                config=dict(clip.config) if clip.config else None,
-            )
-            logger.debug("复制片段: source=%s target=%s order=%d", clip.id, new_clip.id, clip.order)
-
-        return self.get_plan_or_raise(created_plan.id)
@@ -754,14 +754,8 @@ class EditTemplateService:
            template.bump_version()  # 版本号 +1
            updated_template = self._template_repo.update(template)

-            # 批量删除旧的片段配置（N+1 → 1条DELETE，外层事务统一提交）
-            from packages.adapters.sqlalchemy_impl.models import (
-                TemplateClipConfigModel,
-            )
-
-            self._db.query(TemplateClipConfigModel).filter(TemplateClipConfigModel.template_id == template_id).delete(
-                synchronize_session=False
-            )
+            # 批量删除旧的片段配置（外层事务统一提交）
+            self._clip_config_repo.delete_by_template(template_id, commit=False)

            # 创建新的片段配置
            created_configs: list[TemplateClipConfig] = []
@@ -0,0 +1,326 @@
+"""SmartAssetSelector — 智能素材选择服务.
+
+根据多维度评分从素材库中自动选择最优视频素材，
+用于一键生成等需要自动选取素材的场景。
+
+评分维度（加权求和，总分 0-1）：
+  - 质量分（quality_score）：权重 0.5 — 来自人工或AI的质量评分
+  - 分辨率适配：权重 0.2 — 分辨率越接近 1080p 得分越高
+  - 时长合理性：权重 0.2 — 3-30 秒区间最佳，过短/过长扣分
+  - 码率质量：权重 0.1 — 用文件大小/时长估算，码率适中得分高
+
+特性：
+  - 最低质量分门槛：自动过滤低质量素材
+  - 时长多样性：保证选出的素材时长分布均匀（短/中/长各占一定比例）
+  - 兼容全部模式：素材库模式和项目模式都可用
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+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:
+    """智能素材选择器.
+
+    从一组素材中按综合评分选择最优的 N 个，
+    同时保证时长分布的多样性。
+    """
+
+    def __init__(
+        self,
+        min_quality_score: float = _MIN_QUALITY_SCORE,
+        target_width: int = _TARGET_WIDTH,
+        target_height: int = _TARGET_HEIGHT,
+    ):
+        self.min_quality_score = min_quality_score
+        self.target_width = target_width
+        self.target_height = target_height
+
+    # ── 公开方法 ──────────────────────────────────────────────────────────────
+
+    def select(
+        self,
+        assets: list,
+        count: int = 0,
+        *,
+        ensure_diversity: bool = True,
+    ) -> SmartSelectResult:
+        """从素材列表中智能选择最优素材.
+
+        Args:
+            assets: Asset 实体列表（需要有 id/quality_score/width/height/duration/file_size 属性）
+            count: 选取数量，0 表示全部符合条件的
+            ensure_diversity: 是否保证时长多样性（默认开启）
+
+        Returns:
+            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)
+
+        if not candidates:
+            return SmartSelectResult(
+                selected_ids=[],
+                total_candidates=0,
+                filtered_out=filtered_out,
+                avg_score=0.0,
+                details=[],
+            )
+
+        # 2. 对每个候选素材评分
+        scored: list[AssetScoreDetail] = []
+        for asset in candidates:
+            detail = self._score_asset(asset)
+            scored.append(detail)
+
+        # 3. 按总分降序排列
+        scored.sort(key=lambda d: d.total_score, reverse=True)
+
+        # 4. 多样性选择（如果需要且数量有限制）
+        if ensure_diversity and count > 0 and len(scored) > count:
+            selected = self._diverse_selection(scored, count)
+        else:
+            # 无数量限制或不要求多样性，直接按排名取
+            selected = scored if count <= 0 else scored[:count]
+
+        avg_score = sum(d.total_score for d in selected) / len(selected) if selected else 0.0
+
+        result = SmartSelectResult(
+            selected_ids=[d.asset_id for d in selected],
+            total_candidates=len(candidates),
+            filtered_out=filtered_out,
+            avg_score=avg_score,
+            details=selected,
+        )
+
+        logger.info(
+            "智能素材选择完成: 候选=%d, 过滤=%d, 选中=%d, 平均分=%.3f",
+            result.total_candidates,
+            result.filtered_out,
+            len(result.selected_ids),
+            result.avg_score,
+        )
+        return result
+
+    # ── 内部方法 ──────────────────────────────────────────────────────────────
+
+    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(
+            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,
+        )
+
+    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  # 未知分辨率给中评分
+
+        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))
+
+    def _score_duration(self, duration: float | None) -> float:
+        """时长评分：3-30秒最佳，过短或过长都扣分."""
+        if duration is None or duration <= 0:
+            return 0.5  # 未知时长给中评分
+
+        if _OPTIMAL_DURATION_MIN <= duration <= _OPTIMAL_DURATION_MAX:
+            # 最佳区间：满分
+            return 1.0
+
+        if duration < _OPTIMAL_DURATION_MIN:
+            # 太短：线性衰减，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)
+
+    def _score_bitrate(self, file_size: int, duration: float | None) -> float:
+        """码率评分：根据文件大小和时长估算码率，适中得分高."""
+        if not file_size or not duration or duration <= 0:
+            return 0.5  # 未知给中评分
+
+        # 估算码率（bps）
+        bitrate = (file_size * 8) / duration
+
+        # 最佳码率范围：2-8 Mbps
+        optimal_low = 2_000_000  # 2 Mbps
+        optimal_high = 8_000_000  # 8 Mbps
+
+        if optimal_low <= bitrate <= optimal_high:
+            return 1.0
+
+        if bitrate < optimal_low:
+            # 码率太低：线性衰减
+            ratio = bitrate / optimal_low
+            return 0.3 + 0.7 * ratio
+
+        # 码率太高（文件太大）：适度扣分
+        excess = bitrate / optimal_high - 1.0
+        penalty = min(0.5, excess * 0.2)
+        return max(0.5, 1.0 - penalty)
+
+    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]
@@ -52,7 +52,7 @@ type AssetListResponse = {
 test.describe("Core generation flow", () => {
  test.describe.configure({ timeout: 180_000 })

-  test("walks through 5-step wizard and starts generation", async ({ page, request }) => {
+  test("walks through 7-step wizard and starts generation", async ({ page, request }) => {
    test.setTimeout(180_000)

    await routeBrowserApiToTestApi(page)
@@ -177,7 +177,7 @@ test.describe("Core generation flow", () => {

    // Navigate to generate page
    await page.goto("/app/generate")
-    await expect(page.getByRole("heading", { name: "一键生成" })).toBeVisible({
+    await expect(page.getByRole("heading", { name: "智能剪辑" })).toBeVisible({
      timeout: 20_000,
    })

@@ -196,38 +196,56 @@ test.describe("Core generation flow", () => {
    await materialLabel.locator("input[type='checkbox']").check()
    await page.getByRole("button", { name: "下一步" }).click()

-    // Step 3: title
+    // Step 3: preview (纯展示页，AI 智能匹配预览)
+    await expect(page.getByRole("heading", { name: /生成预览/ })).toBeVisible()
+    await page.getByRole("button", { name: "下一步" }).click()
+
+    // Step 4: title
    await expect(page.getByRole("heading", { name: /选择标题/ })).toBeVisible()
    const titleText = `E2E Test ${suffix}`
    await page.getByPlaceholder("输入自定义标题…").fill(titleText)
    await page.getByRole("button", { name: "下一步" }).click()

-    // Step 4: voice
+    // Step 5: voice
    await expect(page.getByRole("heading", { name: /选择配音/ })).toBeVisible()
    const firstVoiceCard = page.locator(".xx-voice-choice-item").first()
    await firstVoiceCard.click()
    await page.getByRole("button", { name: "下一步" }).click()

-    // Step 5: confirm and generate
+    // Step 6: cover (默认 AI 智能选帧模式，直接下一步)
+    await expect(page.getByRole("heading", { name: /选择封面/ })).toBeVisible()
+    await page.getByRole("button", { name: "下一步" }).click()
+
+    // Step 7: confirm and generate
    await expect(page.getByRole("heading", { name: /确认生成/ })).toBeVisible()

-    // Wait for plan creation API to be called
-    const createPlanPromise = page.waitForResponse(
-      (response) =>
-        response.url().includes("/edit-plans") &&
-        response.request().method() === "POST" &&
-        !response.url().includes("/generate"),
+    // Wait for generation API to be called
+    // 新架构：GET 草稿自动创建 → PUT 更新内容 → POST /generate 触发生成
+    // 等 generate 接口返回，确认生成流程启动
+    const generatePromise = page.waitForResponse(
+      (response) => {
+        const url = response.url()
+        const path = new URL(url).pathname
+        return response.request().method() === "POST" && path.endsWith("/editor/generate")
+      },
      { timeout: 30_000 },
    )

    // Click generate button
    await page.locator(".xx-btn-primary").filter({ hasText: "确认生成" }).first().click()

-    // Verify plan was created successfully
-    const planResp = await createPlanPromise
-    expect(planResp.ok()).toBeTruthy()
-    const planData = (await planResp.json()) as { id: string }
-    expect(planData.id).toBeTruthy()
+    // Verify generation was triggered successfully
+    const genResp = await generatePromise
+    if (!genResp.ok()) {
+      const body = await genResp.text()
+      console.error(
+        `[E2E DEBUG] 触发生成接口失败: status=${genResp.status()} url=${genResp.url()} body=${body.slice(0, 500)}`,
+      )
+    }
+    expect(genResp.ok()).toBeTruthy()
+    const genData = (await genResp.json()) as { plan_id: string; generation_task_id: string }
+    expect(genData.plan_id).toBeTruthy()
+    expect(genData.generation_task_id).toBeTruthy()

    // Generation may fail in test env (no worker), that's OK
    // Just verify the flow started - check page shows generation-related UI
@@ -121,3 +121,68 @@ export const verifyEmail = async (token: string): Promise<{ message: string }> =
  const response = await apiClient.post("/auth/verify-email", { token })
  return response.data
 }
+
+/* ========== 微信登录 ========== */
+
+export interface WechatAuthUrlResponse {
+  auth_url: string
+  state: string
+}
+
+export interface WechatCallbackResponse {
+  access_token: string
+  refresh_token?: string | null
+  user_id: string
+  display_name: string
+  avatar_url: string
+  is_new_user: boolean
+  binding_complete: boolean
+  expires_in: number
+}
+
+export interface SendVerificationCodeRequest {
+  target: "email" | "phone"
+  value: string
+  purpose: "bind" | "login" | "reset_password"
+}
+
+export interface BindContactRequest {
+  email?: string
+  email_code?: string
+  phone?: string
+  phone_code?: string
+}
+
+export interface BindContactResponse {
+  success: boolean
+  user: User
+}
+
+// 获取微信授权链接
+export const getWechatAuthUrl = async (): Promise<WechatAuthUrlResponse> => {
+  const response = await apiClient.get("/auth/wechat/url")
+  return response.data
+}
+
+// 微信回调登录
+export const wechatCallback = async (
+  code: string,
+  state: string,
+): Promise<WechatCallbackResponse> => {
+  const response = await apiClient.post("/auth/wechat/callback", { code, state })
+  return response.data
+}
+
+// 发送验证码
+export const sendVerificationCode = async (
+  data: SendVerificationCodeRequest,
+): Promise<{ message: string }> => {
+  const response = await apiClient.post("/auth/send-verification-code", data)
+  return response.data
+}
+
+// 绑定联系方式
+export const bindContact = async (data: BindContactRequest): Promise<BindContactResponse> => {
+  const response = await apiClient.post("/auth/bind-contact", data)
+  return response.data
+}
@@ -189,6 +189,7 @@ export interface ClipStatusItem {
  asset_id?: string
  text_content?: string
  duration?: number
+  error_message?: string
 }

 /** 生成状态轮询响应 */
@@ -196,7 +197,10 @@ export interface GenerationStatusResponse {
  plan_id: string
  plan_status: EditPlanStatus
  generation_task_id?: string
+  error_message?: string
  clips: ClipStatusItem[]
+  error?: string
+  message?: string
 }

 /** 生成视频详情（对应后端 GeneratedVideoResponse） */
@@ -341,71 +345,71 @@ export interface EditPlanListResponse {

 /** 获取模板草稿列表（支持分页和筛选） */
 export async function getEditPlans(params?: EditPlanListParams): Promise<EditPlanListResponse> {
-  const response = await apiClient.get<EditPlanListResponse>("/edit-plans", {
+  const response = await apiClient.get<EditPlanListResponse>("/templates/drafts", {
    params,
  })
  return response.data
 }

 /** 获取单个模板草稿 */
-export async function getEditPlan(planId: string): Promise<EditPlan> {
-  const response = await apiClient.get(`/edit-plans/${planId}`)
+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("/edit-plans", data)
+  const response = await apiClient.post("/templates/drafts", data)
  return response.data
 }

 /** 更新模板草稿 */
 export async function updateEditPlan(
-  planId: string,
+  templateId: string,
  data: UpdateEditPlanRequest,
 ): Promise<EditPlan> {
-  const response = await apiClient.put(`/edit-plans/${planId}`, data)
+  const response = await apiClient.put(`/templates/${templateId}/editor`, data)
  return response.data
 }

 /** 删除模板草稿 */
-export async function deleteEditPlan(planId: string): Promise<void> {
-  await apiClient.delete(`/edit-plans/${planId}`)
+export async function deleteEditPlan(templateId: string): Promise<void> {
+  await apiClient.delete(`/templates/${templateId}/editor`)
 }

 /** 触发生成 */
-export async function generateEditPlan(planId: string): Promise<GenerateResponse> {
-  const response = await apiClient.post(`/edit-plans/${planId}/generate`)
+export async function generateEditPlan(templateId: string): Promise<GenerateResponse> {
+  const response = await apiClient.post(`/templates/${templateId}/editor/generate`)
  return response.data
 }

 /** 获取生成状态（轮询用） */
-export async function getGenerationStatus(planId: string): Promise<GenerationStatusResponse> {
-  const response = await apiClient.get(`/edit-plans/${planId}/generation-status`)
+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(
-  planId: string,
+  templateId: string,
  data: AIRecommendRequest,
 ): Promise<AIRecommendResponse> {
-  const response = await apiClient.post(`/edit-plans/${planId}/ai-recommend`, data)
+  const response = await apiClient.post(`/templates/${templateId}/editor/ai-recommend`, data)
  return response.data
 }

 /** AI 生成封面 */
 export async function generateCover(
-  planId: string,
+  templateId: string,
  data: GenerateCoverRequest,
 ): Promise<GenerateCoverResponse> {
-  const response = await apiClient.post(`/edit-plans/${planId}/generate-cover`, data)
+  const response = await apiClient.post(`/templates/${templateId}/editor/generate-cover`, data)
  return response.data
 }

 /** 获取模板草稿关联的生成记录 */
-export async function getEditPlanGenerations(planId: string): Promise<EditPlanGeneration[]> {
-  const response = await apiClient.get(`/edit-plans/${planId}/generations`)
+export async function getEditPlanGenerations(templateId: string): Promise<EditPlanGeneration[]> {
+  const response = await apiClient.get(`/templates/${templateId}/editor/generations`)
  return response.data.items || []
 }

@@ -416,8 +420,8 @@ export async function getGenerationTaskResults(taskId: string): Promise<Generate
 }

 /** 取消生成任务 */
-export async function cancelGeneration(planId: string): Promise<void> {
-  await apiClient.post(`/edit-plans/${planId}/cancel`)
+export async function cancelGeneration(templateId: string): Promise<void> {
+  await apiClient.post(`/templates/${templateId}/editor/cancel`)
 }

 /* ============================================================
@@ -489,43 +493,51 @@ export interface EditPlanClipListParams {

 /** 获取片段列表 */
 export async function getEditPlanClips(
-  planId: string,
+  templateId: string,
  params?: EditPlanClipListParams,
 ): Promise<EditPlanClipListResponse> {
-  const response = await apiClient.get<EditPlanClipListResponse>(`/edit-plans/${planId}/clips`, {
-    params,
-  })
+  const response = await apiClient.get<EditPlanClipListResponse>(
+    `/templates/${templateId}/editor/clips`,
+    {
+      params,
+    },
+  )
  return response.data
 }

 /** 获取单个片段详情 */
-export async function getEditPlanClip(planId: string, clipId: string): Promise<EditPlanClip> {
-  const response = await apiClient.get<EditPlanClip>(`/edit-plans/${planId}/clips/${clipId}`)
+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(
-  planId: string,
+  templateId: string,
  data: CreateEditPlanClipRequest,
 ): Promise<EditPlanClip> {
-  const response = await apiClient.post<EditPlanClip>(`/edit-plans/${planId}/clips`, data)
+  const response = await apiClient.post<EditPlanClip>(`/templates/${templateId}/editor/clips`, data)
  return response.data
 }

 /** 更新片段 */
 export async function updateEditPlanClip(
-  planId: string,
+  templateId: string,
  clipId: string,
  data: UpdateEditPlanClipRequest,
 ): Promise<EditPlanClip> {
-  const response = await apiClient.put<EditPlanClip>(`/edit-plans/${planId}/clips/${clipId}`, data)
+  const response = await apiClient.put<EditPlanClip>(
+    `/templates/${templateId}/editor/clips/${clipId}`,
+    data,
+  )
  return response.data
 }

 /** 删除片段 */
-export async function deleteEditPlanClip(planId: string, clipId: string): Promise<void> {
-  await apiClient.delete(`/edit-plans/${planId}/clips/${clipId}`)
+export async function deleteEditPlanClip(templateId: string, clipId: string): Promise<void> {
+  await apiClient.delete(`/templates/${templateId}/editor/clips/${clipId}`)
 }

 /* ============================================================
@@ -562,11 +574,11 @@ export interface ClipsFromAssetsResponse {

 /** 片段重排序（拖拽排序后一次性提交） */
 export async function reorderEditPlanClips(
-  planId: string,
+  templateId: string,
  items: ClipReorderItem[],
 ): Promise<ClipReorderResponse> {
  const response = await apiClient.post<ClipReorderResponse>(
-    `/edit-plans/${planId}/clips/reorder`,
+    `/templates/${templateId}/editor/clips/reorder`,
    { items },
  )
  return response.data
@@ -574,11 +586,11 @@ export async function reorderEditPlanClips(

 /** 批量删除片段 */
 export async function batchDeleteEditPlanClips(
-  planId: string,
+  templateId: string,
  clipIds: string[],
 ): Promise<ClipBatchDeleteResponse> {
  const response = await apiClient.post<ClipBatchDeleteResponse>(
-    `/edit-plans/${planId}/clips/batch-delete`,
+    `/templates/${templateId}/editor/clips/batch-delete`,
    { clip_ids: clipIds },
  )
  return response.data
@@ -586,12 +598,12 @@ export async function batchDeleteEditPlanClips(

 /** 从素材批量创建片段（追加到时间线末尾） */
 export async function createClipsFromAssets(
-  planId: string,
+  templateId: string,
  assetIds: string[],
  clipType = "main",
 ): Promise<ClipsFromAssetsResponse> {
  const response = await apiClient.post<ClipsFromAssetsResponse>(
-    `/edit-plans/${planId}/clips/from-assets`,
+    `/templates/${templateId}/editor/clips/from-assets`,
    { asset_ids: assetIds, clip_type: clipType },
  )
  return response.data
@@ -608,8 +620,14 @@ export interface CopyEditPlanRequest {
 }

 /** 复制模板草稿（含所有片段配置） */
-export async function copyEditPlan(planId: string, data?: CopyEditPlanRequest): Promise<EditPlan> {
-  const response = await apiClient.post<EditPlan>(`/edit-plans/${planId}/copy`, data || {})
+export async function copyEditPlan(
+  templateId: string,
+  data?: CopyEditPlanRequest,
+): Promise<EditPlan> {
+  const response = await apiClient.post<EditPlan>(
+    `/templates/${templateId}/editor/copy`,
+    data || {},
+  )
  return response.data
 }

@@ -9,7 +9,7 @@
 */
 import apiClient from "./client"
 import type { TitleConfig, SubtitleConfig, BgmConfig } from "./editingPlanner"
-import type { EditPlanConfig } from "./editPlans"
+import type { EditPlanConfig } from "./templateEditor"

 /* ──────────── 类型定义 ──────────── */

@@ -12,8 +12,8 @@
 import React, { useState, useMemo, useCallback, useRef, useEffect } from "react"
 import "./AssetSelector.css"
 import { Input, Select, Button } from "@/components/ui"
-import type { MediaAsset } from "@/api/editPlans"
-import { MATERIAL_TYPE_LABELS, MATERIAL_TYPE_ICONS, QUALITY_OPTIONS } from "@/api/editPlans"
+import type { MediaAsset } from "@/api/templateEditor"
+import { MATERIAL_TYPE_LABELS, MATERIAL_TYPE_ICONS, QUALITY_OPTIONS } from "@/api/templateEditor"

 /* ──────────── 类型 ──────────── */

@@ -0,0 +1,180 @@
+import React, { useState, useEffect, useRef } from "react"
+import { Modal, Tabs, Form, Input, Button, message } from "antd"
+import { sendVerificationCode, bindContact, type BindContactResponse } from "@/api/auth"
+
+interface BindContactModalProps {
+  open: boolean
+  onSuccess?: (user: BindContactResponse["user"]) => void
+  onCancel?: () => void
+}
+
+const BindContactModal: React.FC<BindContactModalProps> = ({ open, onSuccess, onCancel }) => {
+  const [activeTab, setActiveTab] = useState<"email" | "phone">("email")
+  const [form] = Form.useForm()
+  const [loading, setLoading] = useState(false)
+  const [codeLoading, setCodeLoading] = useState(false)
+  const [countdown, setCountdown] = useState(0)
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null)
+
+  useEffect(() => {
+    if (countdown > 0) {
+      timerRef.current = setInterval(() => {
+        setCountdown((prev) => prev - 1)
+      }, 1000)
+    } else if (timerRef.current) {
+      clearInterval(timerRef.current)
+      timerRef.current = null
+    }
+    return () => {
+      if (timerRef.current) clearInterval(timerRef.current)
+    }
+  }, [countdown])
+
+  useEffect(() => {
+    if (open) {
+      form.resetFields()
+      setCountdown(0)
+    }
+  }, [open, form])
+
+  const handleSendCode = async () => {
+    try {
+      const value = form.getFieldValue(activeTab === "email" ? "email" : "phone")
+      if (!value) {
+        message.warning(activeTab === "email" ? "请输入邮箱" : "请输入手机号")
+        return
+      }
+      setCodeLoading(true)
+      await sendVerificationCode({
+        target: activeTab,
+        value,
+        purpose: "bind",
+      })
+      message.success("验证码已发送")
+      setCountdown(60)
+    } catch (error) {
+      // error handled by interceptor
+    } finally {
+      setCodeLoading(false)
+    }
+  }
+
+  const handleSubmit = async () => {
+    try {
+      const values = await form.validateFields()
+      setLoading(true)
+
+      const payload =
+        activeTab === "email"
+          ? { email: values.email, email_code: values.code }
+          : { phone: values.phone, phone_code: values.code }
+
+      const result = await bindContact(payload)
+
+      message.success("绑定成功")
+      onSuccess?.(result.user)
+    } catch (error) {
+      // error handled by interceptor
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <Modal
+      title="绑定联系方式"
+      open={open}
+      onCancel={onCancel}
+      footer={null}
+      destroyOnHidden
+      maskClosable={false}
+    >
+      <p style={{ color: "#666", marginBottom: 16 }}>为了保障账号安全，请绑定您的邮箱或手机号</p>
+
+      <Tabs
+        activeKey={activeTab}
+        onChange={(key) => setActiveTab(key as "email" | "phone")}
+        items={[
+          {
+            key: "email",
+            label: "邮箱绑定",
+            children: (
+              <Form form={form} layout="vertical">
+                <Form.Item
+                  name="email"
+                  label="邮箱"
+                  rules={[
+                    { required: true, message: "请输入邮箱" },
+                    { type: "email", message: "请输入有效的邮箱地址" },
+                  ]}
+                >
+                  <Input placeholder="请输入邮箱地址" size="large" />
+                </Form.Item>
+                <Form.Item
+                  name="code"
+                  label="验证码"
+                  rules={[{ required: true, message: "请输入验证码" }]}
+                >
+                  <div style={{ display: "flex", gap: 8 }}>
+                    <Input placeholder="请输入验证码" size="large" style={{ flex: 1 }} />
+                    <Button
+                      size="large"
+                      onClick={handleSendCode}
+                      loading={codeLoading}
+                      disabled={countdown > 0}
+                    >
+                      {countdown > 0 ? `${countdown}s 后重发` : "发送验证码"}
+                    </Button>
+                  </div>
+                </Form.Item>
+              </Form>
+            ),
+          },
+          {
+            key: "phone",
+            label: "手机绑定",
+            children: (
+              <Form form={form} layout="vertical">
+                <Form.Item
+                  name="phone"
+                  label="手机号"
+                  rules={[
+                    { required: true, message: "请输入手机号" },
+                    { pattern: /^1[3-9]\d{9}$/, message: "请输入有效的手机号" },
+                  ]}
+                >
+                  <Input placeholder="请输入手机号" size="large" />
+                </Form.Item>
+                <Form.Item
+                  name="code"
+                  label="验证码"
+                  rules={[{ required: true, message: "请输入验证码" }]}
+                >
+                  <div style={{ display: "flex", gap: 8 }}>
+                    <Input placeholder="请输入验证码" size="large" style={{ flex: 1 }} />
+                    <Button
+                      size="large"
+                      onClick={handleSendCode}
+                      loading={codeLoading}
+                      disabled={countdown > 0}
+                    >
+                      {countdown > 0 ? `${countdown}s 后重发` : "发送验证码"}
+                    </Button>
+                  </div>
+                </Form.Item>
+              </Form>
+            ),
+          },
+        ]}
+      />
+
+      <div style={{ marginTop: 16 }}>
+        <Button type="primary" block size="large" loading={loading} onClick={handleSubmit}>
+          确认绑定
+        </Button>
+      </div>
+    </Modal>
+  )
+}
+
+export default BindContactModal
@@ -20,24 +20,72 @@ export const useLogin = () => {
    const data = await mutation.mutateAsync(credentials)
    const refreshToken = data.refresh_token ?? null

-    // 先保存 token
+    // 先存 token 到 localStorage，确保后续请求拦截器能取到
+    // （apiClient 拦截器从 localStorage 读 access_token）
    localStorage.setItem("access_token", data.access_token)
    if (refreshToken) {
      localStorage.setItem("refresh_token", refreshToken)
-    } else {
-      localStorage.removeItem("refresh_token")
    }

-    // 获取用户信息
+    // 再获取用户信息（这时候请求带 Authorization header）
    const user = await authApi.getCurrentUser()
    setAuth(user, data.access_token, refreshToken)
-    navigate("/")
+
+    // 跳转到登录前页面或首页
+    const redirect = localStorage.getItem("login_redirect") || "/"
+    localStorage.removeItem("login_redirect")
+    navigate(redirect, { replace: true })
    return data
  }

  return { ...mutation, mutateAsync: login }
 }

+// 微信登录 Hook（用于回调后处理登录状态）
+export const useWechatCallback = () => {
+  const navigate = useNavigate()
+  const setAuth = useAuthStore((state) => state.setAuth)
+  const setUser = useAuthStore((state) => state.setUser)
+
+  const mutation = useMutation({
+    mutationFn: ({ code, state }: { code: string; state: string }) =>
+      authApi.wechatCallback(code, state),
+  })
+
+  const handleCallback = async (code: string, state: string) => {
+    // 校验 state
+    const savedState = localStorage.getItem("wechat_state")
+    if (!savedState || savedState !== state) {
+      throw new Error("安全校验失败")
+    }
+    localStorage.removeItem("wechat_state")
+
+    const result = await mutation.mutateAsync({ code, state })
+
+    // 先存 token 到 localStorage，确保后续请求拦截器能取到
+    // （apiClient 拦截器从 localStorage 读 access_token）
+    localStorage.setItem("access_token", result.access_token)
+    if (result.refresh_token) {
+      localStorage.setItem("refresh_token", result.refresh_token)
+    }
+
+    // 再获取用户信息（这时候请求带 Authorization header）
+    const user = await authApi.getCurrentUser()
+    setAuth(user, result.access_token, result.refresh_token)
+
+    return { ...result, user }
+  }
+
+  // 绑定成功后跳转
+  const finishLogin = () => {
+    const redirect = localStorage.getItem("login_redirect") || "/"
+    localStorage.removeItem("login_redirect")
+    navigate(redirect, { replace: true })
+  }
+
+  return { ...mutation, handleCallback, finishLogin, setUser }
+}
+
 // 注册 Hook
 export const useRegister = () => {
  const navigate = useNavigate()
@@ -1,10 +1,11 @@
 /**
 * 登录页面 - V21 完全对标
 */
-import React from "react"
+import React, { useState } from "react"
 import { Form, Input, Checkbox, message } from "antd"
 import { Link, useNavigate } from "react-router-dom"
 import { useLogin } from "@/hooks/useAuth"
+import { getWechatAuthUrl } from "@/api/auth"
 import Button from "@/components/ui/Button"
 import "./Login.css"

@@ -18,6 +19,7 @@ const Login: React.FC = () => {
  const navigate = useNavigate()
  const loginMutation = useLogin()
  const [form] = Form.useForm()
+  const [wechatLoading, setWechatLoading] = useState(false)

  const onFinish = async (values: LoginFormValues) => {
    try {
@@ -33,6 +35,29 @@ const Login: React.FC = () => {
    }
  }

+  const handleWechatLogin = async () => {
+    try {
+      setWechatLoading(true)
+      const result = await getWechatAuthUrl()
+      // 保存 state 到 localStorage 用于回调时验证
+      localStorage.setItem("wechat_state", result.state)
+      // 记录登录前的来源页，登录成功后跳回
+      const from = window.location.pathname + window.location.search
+      if (from !== "/login" && from !== "/register") {
+        localStorage.setItem("login_redirect", from)
+      } else {
+        localStorage.removeItem("login_redirect")
+      }
+      // 跳转到微信授权页
+      window.location.href = result.auth_url
+    } catch (error) {
+      if (!(error as { __msgShown?: boolean })?.__msgShown)
+        message.error("微信登录暂不可用，请稍后重试")
+    } finally {
+      setWechatLoading(false)
+    }
+  }
+
  return (
    <div className="xx-auth-page">
      <div className="xx-auth-card">
@@ -100,10 +125,11 @@ const Login: React.FC = () => {
          <button
            type="button"
            className="xx-btn-wechat"
-            onClick={() => message.info("微信登录功能开发中")}
+            onClick={handleWechatLogin}
+            disabled={wechatLoading}
          >
            <span className="xx-wechat-icon">💬</span>
-            微信登录
+            {wechatLoading ? "加载中..." : "微信登录"}
          </button>
        </div>

@@ -0,0 +1,147 @@
+/**
+ * 微信登录回调页
+ */
+import React, { useEffect, useState } from "react"
+import { useSearchParams, useNavigate } from "react-router-dom"
+import { Spin, message } from "antd"
+import { wechatCallback, getCurrentUser, normalizeUser, type User } from "@/api/auth"
+import { useAuthStore } from "@/store/authStore"
+import BindContactModal from "@/components/auth/BindContactModal"
+
+const WechatCallback: React.FC = () => {
+  const [searchParams] = useSearchParams()
+  const navigate = useNavigate()
+  const setAuth = useAuthStore((state) => state.setAuth)
+  const [loading, setLoading] = useState(true)
+  const [showBindModal, setShowBindModal] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    const code = searchParams.get("code")
+    const state = searchParams.get("state")
+
+    if (!code || !state) {
+      setError("无效的回调参数")
+      setLoading(false)
+      return
+    }
+
+    const handleCallback = async () => {
+      try {
+        // 校验 state，防止 CSRF
+        const savedState = localStorage.getItem("wechat_state")
+        if (!savedState || savedState !== state) {
+          setError("安全校验失败，请重新登录")
+          setLoading(false)
+          return
+        }
+        localStorage.removeItem("wechat_state")
+
+        const result = await wechatCallback(code, state)
+
+        // 先把 token 存到 localStorage，让请求拦截器能拿到（getCurrentUser 需要带 token）
+        localStorage.setItem("access_token", result.access_token)
+        if (result.refresh_token) {
+          localStorage.setItem("refresh_token", result.refresh_token)
+        }
+
+        // 获取用户信息（这时候请求拦截器能拿到 token 了）
+        const userData = await getCurrentUser()
+        const user: User = normalizeUser(userData)
+        setAuth(user, result.access_token, result.refresh_token)
+
+        if (result.binding_complete) {
+          // 已绑定，跳转到登录前页面或首页
+          message.success("登录成功")
+          const redirect = localStorage.getItem("login_redirect") || "/"
+          localStorage.removeItem("login_redirect")
+          navigate(redirect, { replace: true })
+        } else {
+          // 未绑定，显示绑定弹窗
+          setLoading(false)
+          setShowBindModal(true)
+        }
+      } catch (err) {
+        setError("登录失败，请重试")
+        setLoading(false)
+      }
+    }
+
+    handleCallback()
+  }, [searchParams, navigate, setAuth])
+
+  const handleBindSuccess = (user: User) => {
+    const setUser = useAuthStore.getState().setUser
+    setUser(user)
+    setShowBindModal(false)
+    message.success("绑定成功")
+    const redirect = localStorage.getItem("login_redirect") || "/"
+    localStorage.removeItem("login_redirect")
+    navigate(redirect, { replace: true })
+  }
+
+  const handleBindCancel = () => {
+    setShowBindModal(false)
+    navigate("/login")
+  }
+
+  if (loading) {
+    return (
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          minHeight: "100vh",
+          background: "#f5f5f5",
+        }}
+      >
+        <div style={{ textAlign: "center" }}>
+          <Spin size="large" />
+          <p style={{ marginTop: 16, color: "#666" }}>正在登录...</p>
+        </div>
+      </div>
+    )
+  }
+
+  if (error) {
+    return (
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          minHeight: "100vh",
+          background: "#f5f5f5",
+        }}
+      >
+        <div style={{ textAlign: "center" }}>
+          <p style={{ color: "#ef4444", fontSize: 16, marginBottom: 16 }}>{error}</p>
+          <button
+            onClick={() => navigate("/login")}
+            style={{
+              padding: "8px 24px",
+              background: "var(--primary-color, #3b82f6)",
+              color: "white",
+              border: "none",
+              borderRadius: 6,
+              cursor: "pointer",
+            }}
+          >
+            返回登录
+          </button>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <BindContactModal
+      open={showBindModal}
+      onSuccess={handleBindSuccess}
+      onCancel={handleBindCancel}
+    />
+  )
+}
+
+export default WechatCallback
@@ -20,8 +20,8 @@ import {
  getTemplateCategories,
  MODE_LABELS,
 } from "@/api/editingPlanner"
-import type { MediaAsset, TransitionEffect, TitleConfig } from "@/api/editPlans"
-import { getMediaAssets, getEditPlan, getEditPlanClips } from "@/api/editPlans"
+import type { MediaAsset, TransitionEffect, TitleConfig } from "@/api/templateEditor"
+import { getMediaAssets, getEditPlan, getEditPlanClips } from "@/api/templateEditor"
 import { useUndoRedo } from "./hooks/useUndoRedo"
 import type {
  ClipData,
@@ -6,7 +6,7 @@ import React, { useRef, useState, useCallback } from "react"
 import { useNavigate } from "react-router-dom"
 import type { TemplateMode } from "@/api/editingPlanner"
 import type { ClipData, ClipType } from "../types"
-import { TRANSITION_OPTIONS } from "@/api/editPlans"
+import { TRANSITION_OPTIONS } from "@/api/templateEditor"
 import type { AssetItem } from "@/api/assets"

 interface SubtitleSettings {
@@ -4,8 +4,8 @@
 */
 import React from "react"
 import { CloseOutlined, InboxOutlined } from "@ant-design/icons"
-import type { EditPlanGeneration } from "@/api/editPlans"
-import { PLAN_STATUS_LABELS } from "@/api/editPlans"
+import type { EditPlanGeneration } from "@/api/templateEditor"
+import { PLAN_STATUS_LABELS } from "@/api/templateEditor"

 interface GenerationHistoryModalProps {
  open: boolean
@@ -7,7 +7,7 @@ import React, { useCallback } from "react"
 import { Drawer } from "antd"
 import type { IntroOutroConfig, IntroOutroItem, IntroOutroKind, TransitionType } from "../types"
 import { DEFAULT_INTRO_OUTRO } from "../types"
-import { TRANSITION_OPTIONS } from "@/api/editPlans"
+import { TRANSITION_OPTIONS } from "@/api/templateEditor"

 /* ──────────── 常量 ──────────── */

@@ -5,7 +5,7 @@
 import React, { useState } from "react"
 import type { EditingTemplate } from "@/api/editingPlanner"
 import { MODE_LABELS } from "@/api/editingPlanner"
-import type { MediaAsset } from "@/api/editPlans"
+import type { MediaAsset } from "@/api/templateEditor"
 import AssetSelector from "@/components/AssetSelector/AssetSelector"

 interface MediaPanelProps {
@@ -5,7 +5,7 @@
 */
 import React from "react"
 import type { ClipData, ClipType } from "../types"
-import type { TitleConfig } from "@/api/editPlans"
+import type { TitleConfig } from "@/api/templateEditor"
 import type { CoverConfig } from "../types"

 interface SubtitleSettings {
@@ -10,7 +10,7 @@
 */
 import React, { useState, useRef, useCallback, useEffect, useLayoutEffect, useMemo } from "react"
 import type { ClipData, ClipType, TrimConfig } from "../types"
-import { TRANSITION_OPTIONS } from "@/api/editPlans"
+import { TRANSITION_OPTIONS } from "@/api/templateEditor"

 interface TimelinePanelProps {
  clips: ClipData[]
@@ -5,7 +5,7 @@
 */
 import React, { useCallback } from "react"
 import { Drawer, Slider } from "antd"
-import { TRANSITION_OPTIONS } from "@/api/editPlans"
+import { TRANSITION_OPTIONS } from "@/api/templateEditor"
 import type { TransitionConfig, TransitionType } from "../types"
 import { DEFAULT_TRANSITION } from "../types"

@@ -18,7 +18,7 @@ import type {
  CreateEditPlanClipRequest,
  UpdateEditPlanClipRequest,
  ClipReorderItem,
-} from "@/api/editPlans"
+} from "@/api/templateEditor"
 import {
  getEditPlanClips,
  createEditPlanClip,
@@ -27,7 +27,7 @@ import {
  reorderEditPlanClips,
  batchDeleteEditPlanClips,
  createClipsFromAssets,
-} from "@/api/editPlans"
+} from "@/api/templateEditor"
 import { useUndoRedo } from "./useUndoRedo"

 const QUERY_KEY = "editPlanClips"
@@ -25,16 +25,16 @@ import {
 import type { AssetItem } from "@/api/assets"
 import { getAssets, getAssetLibraries } from "@/api/assets"
 import {
-  createEditPlan,
  generateEditPlan,
  updateEditPlan,
  getGenerationTaskResults,
-} from "@/api/editPlans"
-import type { GeneratedVideo, EditPlanConfig, TitleConfig } from "@/api/editPlans"
+  getGenerationStatus,
+  getEditPlan,
+} from "@/api/templateEditor"
+import type { GeneratedVideo, EditPlanConfig, TitleConfig } from "@/api/templateEditor"
 import type { CoverConfig } from "../editing-planner/types"
 import { getEditingTemplates } from "@/api/editingPlanner"
 import { getTitles } from "@/api/titles"
-import apiClient from "@/api/client"
 import { fetchPresetVoices } from "@/api/voices"
 import type { PresetVoiceItem } from "@/api/voices"
 import { formatDuration } from "@/api/voiceClone"
@@ -44,7 +44,6 @@ import { synthesizeSpeech, getTTSJobStatus, saveTtsToLibrary } from "@/api/tts"
 import { getTags, createTag } from "@/api/tags"
 import { useCloneProgress } from "@/hooks/useCloneProgress"
 import { useSearchParams, useNavigate } from "react-router-dom"
-import { getEditPlan } from "@/api/editPlans"
 import "./generate.css"

 const { Text } = Typography
@@ -588,7 +587,7 @@ const GeneratePage: React.FC = () => {

  const handleRefreshMatch = useCallback(async () => {
    if (materials.items.length <= 5) {
-      message.info("素材库素材较少，无法换一批")
+      message.info("视频库素材较少，无法换一批")
      return
    }
    setSmartMatching(true)
@@ -994,8 +993,11 @@ const GeneratePage: React.FC = () => {
        if (customVoiceText.trim()) voiceConfig.custom_text = customVoiceText.trim()
      }

-      const plan = await createEditPlan({
-        template_id: selectedTemplate,
+      // 获取或创建草稿（新架构：GET /templates/{templateId}/editor 自动创建）
+      await getEditPlan(selectedTemplate)
+
+      // 更新草稿内容 + 切换到 editing 状态
+      await updateEditPlan(selectedTemplate, {
        name: titleSettings.title.trim(),
        config: {
          asset_ids: materialMode === "auto" ? smartSelectedIds : selectedMaterials,
@@ -1018,18 +1020,14 @@ const GeneratePage: React.FC = () => {
          material_mode: materialMode,
        },
        total_duration: duration,
-        source_edit_plan_id: editPlanId || undefined,
+        status: "editing",
      })

-      // 后端要求计划处于 editing 状态才能触发渲染，自动转换状态
-      await updateEditPlan(plan.id, { status: "editing" })
-
-      await generateEditPlan(plan.id)
+      await generateEditPlan(selectedTemplate)

      const poll = async () => {
        try {
-          const status = await apiClient.get(`/edit-plans/${plan.id}/generation-status`)
-          const data = status.data
+          const data = await getGenerationStatus(selectedTemplate)

          if (data.plan_status === "completed") {
            setProgress(100)
@@ -1053,12 +1051,13 @@ const GeneratePage: React.FC = () => {
            setGenerating(false)
            // 提取后端返回的错误详情，便于排查
            // 注意：后端返回的 error_message/error/message 可能是对象而非字符串
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- 防御性错误提取，后端错误格式不固定
+            const dataAny = data as Record<string, any>
            const rawMsg =
-              data.error_message ||
-              data.error ||
-              data.message ||
-              (data.clips || []).find((c: { status: string }) => c.status === "failed")
-                ?.error_message ||
+              dataAny.error_message ||
+              dataAny.error ||
+              dataAny.message ||
+              (data.clips || []).find((c) => c.status === "failed")?.error_message ||
              "视频生成失败，请联系管理员或重试"
            // 安全提取字符串：递归处理嵌套对象（后端可能返回 {code, message: {code, message}} 等嵌套结构）
            const safeExtract = (val: unknown): string => {
@@ -1075,7 +1074,7 @@ const GeneratePage: React.FC = () => {
              return String(val ?? "")
            }
            const errorMsg = safeExtract(rawMsg)
-            console.error("[生成失败] planId:", plan.id, "响应:", data)
+            console.error("[生成失败] templateId:", selectedTemplate, "响应:", data)
            setGenerateError(errorMsg)
            message.error(errorMsg)
            return
@@ -1091,7 +1090,7 @@ const GeneratePage: React.FC = () => {
          >
        } catch (pollErr) {
          // 轮询接口本身出错（网络/鉴权等），记录并继续轮询一次
-          console.error("[轮询出错] planId:", plan.id, pollErr)
+          console.error("[轮询出错] templateId:", selectedTemplate, pollErr)
          progressTimer.current = setTimeout(poll, 3000) as unknown as ReturnType<
            typeof setInterval
          >
@@ -1198,7 +1197,6 @@ const GeneratePage: React.FC = () => {
    duration,
    autoSubtitles,
    bgm,
-    editPlanId,
    selectedTemplate,
    generateCount,
    materialMode,
@@ -1953,7 +1953,7 @@ const VoiceMaterialLibrary: React.FC = () => {
                icon={<PlusOutlined />}
                onClick={handleTtsSave}
              >
-                保存到素材库
+                保存到配音库
              </Button>
            </div>
          )}
@@ -9,6 +9,7 @@ import Login from "@/pages/auth/Login"
 import Register from "@/pages/auth/Register"
 import ForgotPassword from "@/pages/auth/ForgotPassword"
 import ResetPassword from "@/pages/auth/ResetPassword"
+import WechatCallback from "@/pages/auth/WechatCallback"
 import HomePage from "@/pages/home/HomePage"
 import { useAuthStore } from "@/store/authStore"

@@ -60,6 +61,10 @@ export const router = createBrowserRouter([
    path: "/reset-password",
    element: <ResetPassword />,
  },
+  {
+    path: "/auth/wechat/callback",
+    element: <WechatCallback />,
+  },
  {
    path: "/app",
    element: (
@@ -23,7 +23,7 @@ import {
  copyEditPlan,
  getMediaAssets,
  getMediaAsset,
-} from "@/api/editPlans"
+} from "@/api/templateEditor"

 const mockGet = vi.fn()
 const mockPost = vi.fn()
@@ -2,7 +2,7 @@ import React from "react"
 import { describe, it, expect, vi } from "vitest"
 import { render, screen } from "@testing-library/react"
 import AssetSelector from "@/components/AssetSelector/AssetSelector"
-import type { MediaAsset } from "@/api/editPlans"
+import type { MediaAsset } from "@/api/templateEditor"

 vi.mock("@/components/ui", () => ({
  Input: ({ placeholder }: any) => <input placeholder={placeholder} />,
@@ -7,8 +7,18 @@ import { renderHook, act } from "@testing-library/react"
 import { MemoryRouter } from "react-router-dom"

 const mockNavigate = vi.fn()
-const mockSetAuth = vi.fn()
-const mockClearAuth = vi.fn()
+const mockSetAuth = vi.fn((_user: any, accessToken: string, refreshToken?: string | null) => {
+  localStorage.setItem("access_token", accessToken)
+  if (refreshToken) {
+    localStorage.setItem("refresh_token", refreshToken)
+  } else {
+    localStorage.removeItem("refresh_token")
+  }
+})
+const mockClearAuth = vi.fn(() => {
+  localStorage.removeItem("access_token")
+  localStorage.removeItem("refresh_token")
+})
 const mockMutateAsync = vi.fn()
 const mockQueryClear = vi.fn()

@@ -84,7 +94,7 @@ describe("useAuth hooks", () => {
      expect(typeof result.current.mutateAsync).toBe("function")
    })

-    it("登录成功时保存 token 并调用 setAuth", async () => {
+    it("登录成功时调用 setAuth 并跳转到登录前页面或首页", async () => {
      mockMutateAsync.mockResolvedValue({
        access_token: "access-123",
        refresh_token: "refresh-456",
@@ -96,15 +106,15 @@ describe("useAuth hooks", () => {
        await result.current.mutateAsync({ username: "test", password: "123" })
      })

-      expect(localStorage.getItem("access_token")).toBe("access-123")
-      expect(localStorage.getItem("refresh_token")).toBe("refresh-456")
      expect(mockSetAuth).toHaveBeenCalled()
-      expect(mockNavigate).toHaveBeenCalledWith("/")
+      expect(mockNavigate).toHaveBeenCalledWith("/", { replace: true })
    })

-    it("没有 refresh_token 时从 localStorage 移除", async () => {
+    it("登录成功后跳转到 login_redirect 指定的页面", async () => {
+      localStorage.setItem("login_redirect", "/app/templates")
      mockMutateAsync.mockResolvedValue({
        access_token: "access-123",
+        refresh_token: "refresh-456",
      })

      const { result } = renderHook(() => useLogin(), { wrapper })
@@ -113,8 +123,8 @@ describe("useAuth hooks", () => {
        await result.current.mutateAsync({ username: "test", password: "123" })
      })

-      expect(localStorage.getItem("access_token")).toBe("access-123")
-      expect(localStorage.getItem("refresh_token")).toBeNull()
+      expect(mockNavigate).toHaveBeenCalledWith("/app/templates", { replace: true })
+      expect(localStorage.getItem("login_redirect")).toBeNull()
    })
  })

@@ -146,7 +146,7 @@ vi.mock("@/api/editingPlanner", () => ({
  MODE_LABELS: { pip: "画中画", intro_outro: "片头片尾", watermark: "水印" },
 }))

-vi.mock("@/api/editPlans", () => ({
+vi.mock("@/api/templateEditor", () => ({
  getMediaAssets: vi.fn().mockResolvedValue({ items: [] }),
  getEditPlanGenerations: vi.fn().mockResolvedValue({ items: [] }),
  generateCover: vi.fn().mockResolvedValue({}),
@@ -213,11 +213,24 @@ vi.mock("@/api/titles", () => ({
  getTitles: vi.fn().mockResolvedValue({ items: [] }),
 }))

-vi.mock("@/api/editPlans", () => ({
-  createEditPlan: vi.fn().mockResolvedValue({ id: "test-plan" }),
-  generateEditPlan: vi.fn().mockResolvedValue({ task_id: "test-task" }),
-  updateEditPlan: vi.fn().mockResolvedValue({}),
-  getEditPlan: vi.fn().mockResolvedValue({}),
+vi.mock("@/api/templateEditor", () => ({
+  generateEditPlan: vi.fn().mockResolvedValue({
+    plan_id: "test-plan",
+    generation_task_id: "test-task",
+    plan_status: "processing",
+    clip_count: 5,
+  }),
+  updateEditPlan: vi.fn().mockResolvedValue({ plan_id: "test-plan", template_id: "test-template" }),
+  getEditPlan: vi.fn().mockResolvedValue({
+    plan_id: "test-plan",
+    template_id: "test-template",
+    name: "",
+    config: {},
+    status: "draft",
+  }),
+  getGenerationStatus: vi
+    .fn()
+    .mockResolvedValue({ plan_status: "completed", generation_task_id: "test-task", clips: [] }),
  getGenerationTaskResults: vi.fn().mockResolvedValue({ items: [] }),
 }))

@@ -0,0 +1,79 @@
+import { describe, expect, it, vi, beforeEach } from "vitest"
+import { render, screen } from "@testing-library/react"
+import { MemoryRouter } from "react-router-dom"
+import WechatCallback from "@/pages/auth/WechatCallback"
+
+vi.mock("react-router-dom", async () => {
+  const actual = await vi.importActual("react-router-dom")
+  return {
+    ...actual,
+    useNavigate: () => vi.fn(),
+    useSearchParams: () => [new URLSearchParams({ code: "test_code", state: "test_state" })],
+  }
+})
+
+vi.mock("@/api/auth", () => ({
+  wechatCallback: vi.fn(() => new Promise(() => {})), // pending promise，保持loading
+  getCurrentUser: vi.fn(),
+  normalizeUser: (u: unknown) => u,
+}))
+
+vi.mock("@/store/authStore", () => ({
+  useAuthStore: () => ({
+    setAuth: vi.fn(),
+  }),
+}))
+
+vi.mock("@/components/auth/BindContactModal", () => ({
+  default: ({ open }: { open: boolean }) => (
+    <div data-testid="bind-contact-modal" style={{ display: open ? "block" : "none" }}>
+      BindContactModal
+    </div>
+  ),
+}))
+
+vi.mock("antd", async () => {
+  const actual = await vi.importActual("antd")
+  return {
+    ...actual,
+    message: {
+      success: vi.fn(),
+      error: vi.fn(),
+    },
+  }
+})
+
+describe("WechatCallback Page", () => {
+  beforeEach(() => {
+    // mock localStorage，设置wechat_state匹配，让校验通过
+    const store: Record<string, string> = {
+      wechat_state: "test_state",
+    }
+    vi.spyOn(Storage.prototype, "getItem").mockImplementation((key) => store[key] || null)
+    vi.spyOn(Storage.prototype, "setItem").mockImplementation((key, val) => {
+      store[key] = val
+    })
+    vi.spyOn(Storage.prototype, "removeItem").mockImplementation((key) => {
+      delete store[key]
+    })
+  })
+
+  it("should render without crashing", () => {
+    const { container } = render(
+      <MemoryRouter>
+        <WechatCallback />
+      </MemoryRouter>,
+    )
+    expect(container).toBeTruthy()
+  })
+
+  it("should show loading state while processing", () => {
+    render(
+      <MemoryRouter>
+        <WechatCallback />
+      </MemoryRouter>,
+    )
+    // wechatCallback 返回 pending promise，所以应该显示 loading
+    expect(screen.getByText("正在登录...")).toBeTruthy()
+  })
+})
@@ -32,7 +32,7 @@ vi.mock("antd", () => ({
  },
 }))

-vi.mock("@/api/editPlans", () => ({
+vi.mock("@/api/templateEditor", () => ({
  getEditPlanClips: vi.fn().mockResolvedValue({ items: [], total: 0 }),
  createEditPlanClip: vi.fn().mockResolvedValue({}),
  updateEditPlanClip: vi.fn().mockResolvedValue({}),
@@ -483,6 +483,7 @@ class RenderAdapter:
        progress_cb: ProgressCallback | None = None,
        rendered_clip_ids: list[str] | None = None,
        failed_clip_ids: list[str] | None = None,
+        voiceover_audio_path: str | None = None,
    ) -> RenderAdapterResult:
        """执行统一渲染核心流程（BGM + ASR + 渲染 + 缩略图 + 上传）。

@@ -491,6 +492,7 @@ class RenderAdapter:
        Args:
            rendered_clip_ids: 成功下载/准备的 clip id 列表（render_plan 从下载阶段传入）
            failed_clip_ids: 失败的 clip id 列表
+            voiceover_audio_path: 配音素材库音频本地路径（一键生成场景使用）

        Returns:
            RenderAdapterResult
@@ -525,6 +527,7 @@ class RenderAdapter:
            output_height=output_height,
            bgm_path=bgm_path,
            asr_service=asr_service,
+            voiceover_audio_path=voiceover_audio_path,
        )
        result = render_svc.render()

@@ -593,6 +596,7 @@ class RenderAdapter:
        job_id: str = "",
        work_dir: Path | None = None,
        progress_cb: ProgressCallback | None = None,
+        voiceover_audio_path: str | None = None,
    ) -> RenderAdapterResult:
        """使用内存中的 plan/clips/asset_path_map 直接渲染。

@@ -606,6 +610,7 @@ class RenderAdapter:
            job_id: 关联的 Job ID
            work_dir: 工作目录，不传则用临时目录
            progress_cb: 进度回调
+            voiceover_audio_path: 配音素材库音频本地路径

        Returns:
            RenderAdapterResult
@@ -649,6 +654,7 @@ class RenderAdapter:
                plan_id=actual_plan_id,
                job_id=job_id,
                progress_cb=progress_cb,
+                voiceover_audio_path=voiceover_audio_path,
            )

        except subprocess.CalledProcessError as exc:
@@ -175,6 +175,7 @@ class UnifiedRenderService:
        transition_duration: float = DEFAULT_TRANSITION_DURATION,
        asr_service: Any = None,  # ASRService 实例，用于自动生成字幕
        bgm_path: str | None = None,  # BGM 本地文件路径
+        voiceover_audio_path: str | None = None,  # 配音素材库音频本地路径
    ):
        self.plan = plan
        self.clips = clips
@@ -186,6 +187,7 @@ class UnifiedRenderService:
        self.transition_duration = transition_duration
        self.asr_service = asr_service
        self.bgm_path = bgm_path
+        self.voiceover_audio_path = voiceover_audio_path
        self._transition_engine = TransitionEngine(default_duration=transition_duration)
        self._speed_engine = SpeedEngine()
        self._asr_timeline_cache: Any = None  # ASR 字幕结果缓存，避免重复调用
@@ -226,6 +228,9 @@ class UnifiedRenderService:
        # 3.5 TTS 配音生成（如果配置了）
        self._maybe_add_voiceover_layer(layers, video_duration=video_duration)

+        # 3.6 配音素材库音频（如果传入了本地路径）
+        self._maybe_add_voice_library_layer(layers, video_duration=video_duration)
+
        # 4. 生成 ASS 字幕文件（如果有 title/subtitle 配置）
        ass_path = self._maybe_generate_ass(video_duration)

@@ -843,6 +848,107 @@ class UnifiedRenderService:
            logger.warning("TTS 配音异常，跳过: %s", e)
            return False

+    def _maybe_add_voice_library_layer(
+        self,
+        layers: list[RenderLayer],
+        *,
+        video_duration: float,
+    ) -> bool:
+        """将配音素材库音频作为整段配音加到 audio 图层.
+
+        与 TTS 配音共享同一套 audio 图层混音架构，
+        支持与 BGM、TTS 的音量平衡，不再走独立的后处理 mux 链路。
+
+        Returns:
+            是否成功添加了配音音轨
+        """
+        if not self.voiceover_audio_path:
+            return False
+
+        audio_path = Path(self.voiceover_audio_path)
+        if not audio_path.exists() or audio_path.stat().st_size == 0:
+            logger.warning("配音素材库音频文件不存在或为空，跳过: %s", self.voiceover_audio_path)
+            return False
+
+        try:
+            # 找到或创建 audio 图层
+            audio_layer = None
+            for layer in layers:
+                if layer.role == "audio":
+                    audio_layer = layer
+                    break
+
+            if audio_layer is None:
+                from video_processing.unified_render_service import _LAYER_Z_INDEX  # type: ignore
+
+                z_index = _LAYER_Z_INDEX.get("audio", 2)
+                audio_layer = RenderLayer(role="audio", z_index=z_index)
+                layers.append(audio_layer)
+
+            # 配音素材作为整段配音：从 0 开始，覆盖整个视频时长
+            # 音频不足视频时长时，混音层会按实际长度处理（amix 不自动循环）
+            vo_clip = ResolvedClip(
+                clip_id="voice_library_main",
+                asset_id="voice_library",
+                local_path=audio_path,
+                clip_type="audio",
+                order=len(audio_layer.clips),
+                start_time=0.0,
+                duration=video_duration,
+                config={"volume": 1.0, "voice_library": True},
+                actual_duration=video_duration,
+            )
+            audio_layer.clips.append(vo_clip)
+
+            logger.info(
+                "配音素材库音频已添加到 audio 图层: plan_id=%s duration=%.2fs",
+                self.plan.id,
+                video_duration,
+            )
+            return True
+
+        except Exception as e:
+            logger.warning("配音素材库音频添加失败，跳过: %s", e)
+            return False
+
+    @staticmethod
+    def _resolve_watermark_config(plan_config: dict[str, Any] | None) -> WatermarkConfig | None:
+        """从 plan config 中解析水印配置，兼容两种存储格式.
+
+        支持格式：
+        1. 嵌套格式：config.watermark = {enabled, mode, text, image_path, ...}
+        2. 扁平格式（导出配置）：config.export.watermark_enabled + config.export.watermark_text
+
+        Returns:
+            WatermarkConfig 或 None（未启用水印时）
+        """
+        if not plan_config or not isinstance(plan_config, dict):
+            return None
+
+        # 格式1: 嵌套 watermark 对象（优先）
+        wm_data = plan_config.get("watermark")
+        if isinstance(wm_data, dict) and wm_data:
+            config = WatermarkConfig.from_dict(wm_data)
+            if config is not None:
+                return config
+
+        # 格式2: 扁平 export.watermark_enabled + export.watermark_text
+        export_cfg = plan_config.get("export")
+        if isinstance(export_cfg, dict) and export_cfg:
+            enabled = export_cfg.get("watermark_enabled", False)
+            text = export_cfg.get("watermark_text", "") or ""
+            if enabled and text:
+                return WatermarkConfig(
+                    mode="text",
+                    text=str(text),
+                    position=export_cfg.get("watermark_position", "bottom_right"),
+                    opacity=float(export_cfg.get("watermark_opacity", 0.6)),
+                    font_size=int(export_cfg.get("watermark_font_size", 24)),
+                    font_color=str(export_cfg.get("watermark_font_color", "white")),
+                )
+
+        return None
+
    def _can_use_pass_through(self, layers: list[RenderLayer]) -> bool:
        """判断是否可以走直通优化路径。

@@ -864,15 +970,11 @@ class UnifiedRenderService:
        if isinstance(plan_config, dict) and plan_config.get("stickers"):
            return False

-        # 有水印时禁用直通（图片水印需要额外输入，统一走 filter_complex）
-        try:
-            from video_processing.watermark_engine import WatermarkConfig
-
-            wm_config = WatermarkConfig.from_dict(plan_config.get("watermark"))
-            if wm_config is not None and wm_config.validate()[0]:
-                return False
-        except Exception:
-            pass
+        # 有水印时禁用直通（图片水印需要额外输入，统一走 filter_complex；
+        # 文字水印虽然可以 -vf 叠加，但为了保持路径统一也走 filter_complex）
+        wm_config = UnifiedRenderService._resolve_watermark_config(plan_config)
+        if wm_config is not None and wm_config.validate()[0]:
+            return False

        # 有调速时仍然可以走直通（视频调速通过 setpts 实现，单输入即可）

@@ -1117,11 +1219,11 @@ class UnifiedRenderService:
            filters.append(f"scale={pip_w}:{pip_h}")
        elif role == "background":
            # background: 铺满裁剪（作为底图，覆盖全屏）
-            filters.append(f"scale={self.output_width}:{self.output_height}" ":force_original_aspect_ratio=increase")
+            filters.append(f"scale={self.output_width}:{self.output_height}:force_original_aspect_ratio=increase")
            filters.append(f"crop={self.output_width}:{self.output_height}")
        else:
            # main / broll: 等比缩放 + 居中留黑边（保持原始比例，不裁剪内容）
-            filters.append(f"scale={self.output_width}:{self.output_height}" ":force_original_aspect_ratio=decrease")
+            filters.append(f"scale={self.output_width}:{self.output_height}:force_original_aspect_ratio=decrease")
            filters.append(f"pad={self.output_width}:{self.output_height}:trunc((ow-iw)/2):trunc((oh-ih)/2):black")

        # 调色滤镜
@@ -1304,6 +1406,8 @@ class UnifiedRenderService:
                        start_time=seg_start,
                        duration=seg_duration,
                        transition_effect=clip.transition_effect or "cut",
+                        transition_duration=getattr(clip, "transition_duration", 0.0) or 0.0,
+                        playback_speed=getattr(clip, "playback_speed", 1.0) or 1.0,
                        config={**clip_config, "_segment_id": seg.segment_id},
                        actual_duration=actual_duration,
                        trim_config=seg.trim,
@@ -1464,16 +1568,12 @@ class UnifiedRenderService:
                pip_h = int(self.output_height * _PIP_SCALE)
                filters.append(f"scale={pip_w}:{pip_h}")
            elif role == "background":
-                filters.append(
-                    f"scale={self.output_width}:{self.output_height}" ":force_original_aspect_ratio=increase"
-                )
+                filters.append(f"scale={self.output_width}:{self.output_height}:force_original_aspect_ratio=increase")
                filters.append(f"crop={self.output_width}:{self.output_height}")
            else:
                # main / broll: 等比缩放 + 居中留黑边（保持原始比例，不裁剪内容）
                # concat 要求所有输入分辨率完全一致，pad 模式确保不同宽高比的素材都能正常拼接
-                filters.append(
-                    f"scale={self.output_width}:{self.output_height}" ":force_original_aspect_ratio=decrease"
-                )
+                filters.append(f"scale={self.output_width}:{self.output_height}:force_original_aspect_ratio=decrease")
                filters.append(f"pad={self.output_width}:{self.output_height}:trunc((ow-iw)/2):trunc((oh-ih)/2):black")

            # 调色滤镜（每个 clip 独立的 color grade 配置）
@@ -1561,9 +1661,7 @@ class UnifiedRenderService:
                if role in layer_output_labels:
                    base_label = layer_output_labels[role]
                    combined_label = f"combined_{role}"
-                    filter_parts.append(
-                        f"[{final_video_label}][{base_label}]" f"overlay=(W-w)/2:(H-h)/2[{combined_label}]"
-                    )
+                    filter_parts.append(f"[{final_video_label}][{base_label}]overlay=(W-w)/2:(H-h)/2[{combined_label}]")
                    final_video_label = combined_label
        else:
            # 无 background 时，取 broll 或 main 作为基础
@@ -1587,11 +1685,11 @@ class UnifiedRenderService:
                    20,
                )
                combined_label = f"combined_{layer.role}"
-                filter_parts.append(f"[{final_video_label}][{overlay_label}]" f"overlay={x}:{y}[{combined_label}]")
+                filter_parts.append(f"[{final_video_label}][{overlay_label}]overlay={x}:{y}[{combined_label}]")
                final_video_label = combined_label

        # 叠加水印（在字幕之前）
-        watermark_config = WatermarkConfig.from_dict((self.plan.config or {}).get("watermark"))
+        watermark_config = UnifiedRenderService._resolve_watermark_config(self.plan.config)
        if watermark_config is not None:
            wm_valid, wm_err = watermark_config.validate()
            if wm_valid:
@@ -10,12 +10,14 @@

 from __future__ import annotations

+import json
 import logging
 import random
 import time
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional

 from packages.domain.config_schemas import DEFAULT_EDIT_PLAN_CONFIG
+from packages.shared.ai_client import get_doubao_client

 logger = logging.getLogger(__name__)

@@ -23,17 +25,16 @@ logger = logging.getLogger(__name__)
 # ── AI 推荐片段方案 ──────────────────────────────────────────────────────────


-def _call_ai_recommend_service(
+def _fallback_recommend_clips(
    plan_id: str,
    template_id: str,
    asset_ids: List[str],
    editing_mode: str,
    target_duration: float,
 ) -> Dict[str, Any]:
-    """调用 AI 推荐服务（stub）
+    """本地降级推荐方案（原 stub 逻辑）.

-    TODO: 接入真实 AI 服务，分析素材内容并生成推荐方案。
-    当前返回基于模板规则的模拟推荐数据。
+    当豆包 API 不可用或调用失败时使用，基于模板规则生成模拟推荐数据。
    """
    # 模拟 AI 分析耗时
    time.sleep(0.5)
@@ -87,6 +88,7 @@ def _call_ai_recommend_service(
            "config": {},
        }
    )
+    order += 1

    # 生成推荐 config
    config = DEFAULT_EDIT_PLAN_CONFIG.copy()
@@ -101,6 +103,163 @@ def _call_ai_recommend_service(
    }


+def _parse_recommend_response(
+    content: str,
+    asset_ids: List[str],
+    target_duration: float,
+) -> Optional[Dict[str, Any]]:
+    """解析豆包返回的推荐方案.
+
+    期望返回结构：
+    {
+        "clips": [
+            {"clip_type": "intro/showcase/outro", "order": 0,
+             "text_content": "...", "duration": 3.0,
+             "transition_effect": "fade/cut", "asset_id": "...",
+             "start_time": 0.0, "config": {}}
+        ],
+        "title": "视频标题",
+        "confidence": 0.85
+    }
+    """
+    if not content:
+        return None
+
+    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)
+        if not isinstance(data, dict):
+            return None
+
+        clips_data = data.get("clips", [])
+        if not isinstance(clips_data, list) or len(clips_data) == 0:
+            return None
+
+        clips: List[Dict[str, Any]] = []
+        for i, clip in enumerate(clips_data):
+            if not isinstance(clip, dict):
+                continue
+            asset_id = str(clip.get("asset_id", ""))
+            # 校验 asset_id 是否在输入列表中
+            if asset_id and asset_id not in asset_ids:
+                asset_id = ""
+            clips.append({
+                "clip_type": clip.get("clip_type", "showcase"),
+                "order": clip.get("order", len(clips)),
+                "text_content": str(clip.get("text_content", "")),
+                "duration": max(1.0, min(30.0, float(clip.get("duration", 3.0)))),
+                "transition_effect": clip.get("transition_effect", "cut"),
+                "asset_id": asset_id,
+                "start_time": max(0.0, float(clip.get("start_time", 0.0))),
+                "config": clip.get("config", {}) or {},
+            })
+
+        if not clips:
+            return None
+
+        # 按 order 排序
+        clips.sort(key=lambda c: c["order"])
+        # 重新编号 order 保证连续
+        for i, clip in enumerate(clips):
+            clip["order"] = i
+
+        config = DEFAULT_EDIT_PLAN_CONFIG.copy()
+        title = data.get("title", "")
+        if title:
+            config["title"]["text"] = str(title)
+            config["title"]["ai_auto"] = True
+
+        confidence = float(data.get("confidence", 0.7))
+        confidence = max(0.0, min(1.0, confidence))
+
+        total_duration = round(sum(c["duration"] for c in clips), 1)
+
+        return {
+            "clips": clips,
+            "config": config,
+            "total_duration": total_duration,
+            "confidence": round(confidence, 2),
+        }
+
+    except (json.JSONDecodeError, ValueError, TypeError, KeyError):
+        return None
+
+
+def _call_ai_recommend_service(
+    plan_id: str,
+    template_id: str,
+    asset_ids: List[str],
+    editing_mode: str,
+    target_duration: float,
+) -> Dict[str, Any]:
+    """调用 AI 推荐服务生成片段编排方案.
+
+    优先使用豆包大模型生成，失败或未配置时降级为本地规则生成。
+    """
+    client = get_doubao_client()
+    if not client.is_available:
+        logger.info("豆包API未配置，使用本地降级生成AI推荐方案")
+        return _fallback_recommend_clips(plan_id, template_id, asset_ids, editing_mode, target_duration)
+
+    # 构建 prompt
+    system_prompt = (
+        "你是一个专业的视频剪辑导演助手。"
+        "根据提供的素材列表和目标时长，设计一个完整的视频片段编排方案。\n"
+        "要求：\n"
+        "1. 片段类型分为三类：intro（开场）、showcase（展示）、outro（结尾）\n"
+        "2. 每个片段包含：clip_type、order、text_content（字幕/标题文字）、"
+        "duration（时长秒）、transition_effect（转场效果：fade/cut/dissolve）、"
+        "asset_id（使用的素材ID）、start_time（素材起始时间秒）\n"
+        "3. 总时长接近 target_duration，每个素材至少用一次\n"
+        "4. 转场效果合理分配，不要全用cut\n"
+        "5. 返回纯JSON，不要其他文字\n"
+        "返回格式：{\"clips\": [...], \"title\": \"视频标题\", \"confidence\": 0.85}"
+    )
+
+    assets_desc = "\n".join([f"  - 素材ID: {aid}" for i, aid in enumerate(asset_ids[:30])])
+    user_prompt = (
+        f"剪辑计划ID: {plan_id}\n"
+        f"模板ID: {template_id}\n"
+        f"剪辑模式: {editing_mode}\n"
+        f"目标时长: {target_duration}秒\n"
+        f"素材列表（共{len(asset_ids)}个）：\n{assets_desc}\n\n"
+        f"请设计完整的片段编排方案："
+    )
+
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_prompt},
+    ]
+
+    result = client.chat_completion(
+        messages=messages,
+        temperature=0.7,
+        max_tokens=2048,
+    )
+
+    if result:
+        parsed = _parse_recommend_response(result, asset_ids, target_duration)
+        if parsed and len(parsed["clips"]) >= 2:
+            logger.info(
+                "豆包AI推荐生成成功: plan_id=%s clips=%d duration=%.1f confidence=%.2f",
+                plan_id,
+                len(parsed["clips"]),
+                parsed["total_duration"],
+                parsed["confidence"],
+            )
+            return parsed
+        logger.warning("豆包AI推荐返回解析失败，降级到本地方案: %s", result[:100])
+
+    # 降级
+    return _fallback_recommend_clips(plan_id, template_id, asset_ids, editing_mode, target_duration)
+
+
 # ── AI 封面生成 ──────────────────────────────────────────────────────────────


@@ -142,8 +142,6 @@ def _finalize_render_success(
    plan.config["rendered_storage_key"] = storage_key
    if hasattr(plan, "total_duration") and duration > 0:
        plan.total_duration = duration
-    if hasattr(plan, "result_count"):
-        plan.result_count = 1
    plan.mark_completed()
    plan_repo.update(plan)

@@ -171,6 +171,7 @@ class _VirtualClip:
    start_time: float = 0.0
    duration: float = 0.0
    transition_effect: str = "cut"
+    transition_duration: float = 0.0  # 0 表示使用全局默认值
    playback_speed: float = 1.0
    status: str = "ready"
    config: dict[str, Any] = field(default_factory=dict)
@@ -279,7 +280,7 @@ def _apply_template_clip_effects(
        cfg_idx = min(i, len(main_configs) - 1)
        template_cfg = main_configs[cfg_idx]

-        # 1. 转场效果
+        # 1. 转场效果 + 时长
        transition = (
            template_cfg.transition_effect.value
            if hasattr(template_cfg.transition_effect, "value")
@@ -287,6 +288,16 @@ def _apply_template_clip_effects(
        )
        if transition and transition != "cut":
            clip.transition_effect = transition
+            # 同步转场时长（模板 clip_config 里的 transition_duration）
+            tpl_cfg = template_cfg.config or {}
+            tpl_duration = tpl_cfg.get("transition_duration")
+            if tpl_duration:
+                try:
+                    dur_val = float(tpl_duration)
+                    if dur_val > 0:
+                        clip.transition_duration = dur_val
+                except (ValueError, TypeError):
+                    pass

        # 2. clip 级效果配置（滤镜、调速等）
        template_clip_config = template_cfg.config or {}
@@ -1099,6 +1110,7 @@ def _load_task_info(task_id: str) -> dict | None:
            "batch_id": getattr(gen_task, "batch_id", "") or "",
            "user_id": getattr(gen_task, "created_by_user_id", "") or "",
            "video_title": getattr(gen_task, "video_title", "") or "",
+            "resolution": getattr(gen_task, "resolution", "") or "",
        }
    finally:
        session.close()
@@ -1157,6 +1169,7 @@ def _render_video(
    user_id: str,
    temp_path: Path,
    output_name: str,
+    resolution: str = "",
 ) -> tuple[Path, float]:
    """渲染视频（含配音混音）。

@@ -1188,15 +1201,17 @@ def _render_video(
                list(template_config.keys()),
            )

-    # 确保输出分辨率配置存在（一键生成默认横屏 1280x720）
-    # RenderAdapter 从 plan.config.export.resolution 读取，
-    # 如果模板没有配置则用默认值，这里显式设置保持和旧逻辑一致
+    # 确保输出分辨率配置存在
+    # 优先级：用户指定 > 模板配置 > 默认 1280x720
    plan_cfg = virtual_plan.config or {}
    export_cfg = plan_cfg.get("export", {}) or {}
-    if not export_cfg.get("resolution"):
+    if resolution:
+        # 用户在 API 调用时指定的分辨率优先级最高
+        export_cfg["resolution"] = resolution
+    elif not export_cfg.get("resolution"):
        export_cfg["resolution"] = f"{OUTPUT_WIDTH}x{OUTPUT_HEIGHT}"
-        plan_cfg["export"] = export_cfg
-        virtual_plan.config = plan_cfg
+    plan_cfg["export"] = export_cfg
+    virtual_plan.config = plan_cfg

    total_duration = sum(c.duration for c in virtual_clips)
    logger.info(
@@ -1223,6 +1238,7 @@ def _render_video(
            plan_id=f"gen_{task_id}",
            job_id=task_id,
            work_dir=temp_path,
+            voiceover_audio_path=voice_path,
        )
    finally:
        db.close()
@@ -1241,17 +1257,8 @@ def _render_video(
        render_duration,
    )

-    # 配音混音（素材库音频，后处理混音）
-    if voice_path:
-        final_path = temp_path / f"final-{task_id}.mp4"
-        try:
-            _mux_audio_track(render_output_path, voice_path, final_path)
-            output_path = final_path
-        except Exception as mux_err:
-            logger.warning("[task_id=%s] [混音] 音频混合失败，使用无音频版本: %s", task_id, mux_err)
-            output_path = render_output_path
-    else:
-        output_path = render_output_path
+    # 配音素材库音频已在统一渲染引擎内部通过 audio 图层混音处理
+    output_path = render_output_path

    return output_path, render_duration

@@ -1445,6 +1452,7 @@ def generate_video(self, task_id: str) -> dict:
                user_id=user_id,
                temp_path=temp_path,
                output_name=output_name,
+                resolution=task_info.get("resolution", ""),
            )

            if gen_task:
@@ -1,33 +1,69 @@
 # ============================================================
-# API Dockerfile - 专门用于 FastAPI 应用
-# 优化：依赖分层缓存 + 多阶段构建基础层
+# API Dockerfile - FastAPI 应用
+# 优化：多阶段构建 + pip cache mount + 依赖分层缓存
 # ============================================================

-# 基础镜像：Python 3.12
-FROM git.xiaoxiajianji.com/xiaoxia/base/python:3.12-slim
+# ==================== Builder 阶段 ====================
+FROM git.xiaoxiajianji.com/xiaoxia/base/python:3.12-slim AS builder
+
+# 使用阿里云镜像加速
+RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null || \
+    sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true
+
+# 安装编译依赖（仅 builder 需要）
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# 创建虚拟环境
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+WORKDIR /tmp
+
+# ---- 依赖分层：基础依赖（变化少，缓存命中率高）----
+COPY requirements-base.txt /tmp/requirements-base.txt
+
+RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
+    pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
+    -r /tmp/requirements-base.txt \
+    && rm /tmp/requirements-base.txt
+
+# ---- 依赖分层：业务依赖（变化频繁）----
+COPY requirements.txt /tmp/requirements.txt
+
+RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
+    pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
+    -r /tmp/requirements.txt \
+    && rm /tmp/requirements.txt
+
+# ---- Python 依赖瘦身 ----
+RUN find /opt/venv -name "*.so" -type f -exec strip --strip-all {} \; 2>/dev/null || true
+RUN find /opt/venv -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null; \
+    find /opt/venv -name "*.pyc" -delete 2>/dev/null || true
+
+# ==================== Runtime 阶段 ====================
+FROM git.xiaoxiajianji.com/xiaoxia/base/python:3.12-slim AS runtime

 # 构建参数：版本号（CI 传入 commit hash）
 ARG APP_VERSION=dev

 # 使用阿里云镜像加速
-RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null ||     sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true
+RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null || \
+    sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true

-# 安装系统依赖
-RUN apt-get update && apt-get install -y --no-install-recommends     libpq-dev     && rm -rf /var/lib/apt/lists/*
+# 只装运行时需要的库（libpq5 是 psycopg2 运行时依赖）
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpq5 \
+    && rm -rf /var/lib/apt/lists/*
+
+# 从 builder 复制虚拟环境
+COPY --from=builder /opt/venv /opt/venv

 # 设置工作目录
 WORKDIR /app

-# ---- 依赖分层：基础依赖（变化少，缓存命中率高）----
-COPY requirements-base.txt /tmp/requirements-base.txt
-
-RUN python -m venv /opt/venv     && /opt/venv/bin/pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com -r /tmp/requirements-base.txt     && rm /tmp/requirements-base.txt
-
-# ---- 依赖分层：业务依赖（变化频繁）----
-COPY requirements.txt /tmp/requirements.txt
-
-RUN /opt/venv/bin/pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com -r /tmp/requirements.txt     && rm /tmp/requirements.txt
-
 # 复制应用代码
 COPY apps/api/ /app/apps/api/
 COPY packages/ /app/packages/
@@ -43,7 +79,8 @@ ENV PYTHONUNBUFFERED=1
 ENV APP_VERSION=$APP_VERSION

 # 健康检查
-HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3     CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=5)"
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=5)"

 # API 入口点
 WORKDIR /app/apps/api
@@ -0,0 +1,43 @@
+# ============================================================
+# Worker Builder 基础镜像
+# 预编译：编译工具 + 基础依赖 + Worker大包
+# 当 requirements-base.txt 或 requirements-worker.txt 变更时重新构建
+# 业务构建从此镜像开始，只需要安装业务依赖，节省15+分钟
+# ============================================================
+
+FROM git.xiaoxiajianji.com/xiaoxia/base/python:3.12-slim
+
+# 使用阿里云镜像加速
+RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null || \
+    sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true
+
+# 安装编译工具
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    g++ \
+    python3-dev \
+    binutils \
+    && rm -rf /var/lib/apt/lists/*
+
+# 创建 venv
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+WORKDIR /tmp
+
+# 基础依赖（变化极少）
+COPY requirements-base.txt /tmp/requirements-base.txt
+RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
+    pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
+    -r /tmp/requirements-base.txt \
+    && rm /tmp/requirements-base.txt
+
+# Worker 大包（变化少）
+COPY requirements-worker.txt /tmp/requirements-worker.txt
+RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
+    pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
+    -r /tmp/requirements-worker.txt \
+    && rm /tmp/requirements-worker.txt
+
+# 预先做一次 strip（基础层瘦身，业务层增量）
+RUN find /opt/venv -name "*.so" -type f -exec strip --strip-all {} \; 2>/dev/null || true
@@ -0,0 +1,17 @@
+# ============================================================
+# Worker Runtime 基础镜像
+# 预安装：ffmpeg + 运行时依赖
+# 变化极少，业务构建从此镜像开始
+# ============================================================
+
+FROM git.xiaoxiajianji.com/xiaoxia/base/python:3.12-slim
+
+# 使用阿里云镜像加速
+RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null || \
+    sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true
+
+# 运行时依赖：ffmpeg + opencv需要的libglib
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
@@ -1,98 +1,43 @@
 # ============================================================
-# Worker Dockerfile - 优化版（多阶段构建 + 镜像瘦身）
-# 优化项：
-#   1. 多阶段构建：builder 阶段安装编译依赖，runtime 阶段只保留运行时
-#   2. ffmpeg 静态编译替换：从 apt 安装(457MB) 改为静态二进制(~80MB)
-#   3. Python 依赖瘦身：strip .so 调试符号 + 清理测试文件 + 清理缓存
+# Worker Dockerfile - 分层缓存优化版
+# 优化：基础依赖 + Worker大包预构建为基础镜像，业务构建仅叠加业务依赖
+# 基础镜像：worker-base-builder / worker-base-runtime
+# 预计节省：依赖不变时构建时间从23min降至5min以内
 # ============================================================

 # ==================== Builder 阶段 ====================
-FROM git.xiaoxiajianji.com/xiaoxia/base/python:3.12-slim AS builder
+# 从预构建的builder基础镜像开始，已经包含：
+#   - 编译工具 (gcc/g++/python3-dev/binutils)
+#   - requirements-base.txt 全部依赖
+#   - requirements-worker.txt 全部依赖 (numpy/scipy/opencv)
+#   - 预strip的.so文件
+FROM xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji/worker-base-builder:latest AS builder

-# 使用阿里云镜像加速
-RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null || \
-    sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true
-
-# 安装编译工具（仅 builder 需要）
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    gcc \
-    g++ \
-    python3-dev \
-    binutils \
-    wget \
-    xz-utils \
-    && rm -rf /var/lib/apt/lists/*
-
-# ---- 下载静态编译 ffmpeg ----
-# 使用 johnvansickle.com 的静态编译版本（业界标准）
-RUN cd /tmp \
-    && wget -q https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz \
-    && tar xf ffmpeg-release-amd64-static.tar.xz \
-    && cp ffmpeg-*-amd64-static/ffmpeg /usr/local/bin/ffmpeg \
-    && cp ffmpeg-*-amd64-static/ffprobe /usr/local/bin/ffprobe \
-    && chmod +x /usr/local/bin/ffmpeg /usr/local/bin/ffprobe \
-    && rm -rf ffmpeg-*
-
-# ---- 安装 Python 依赖 ----
-WORKDIR /tmp
-
-# 创建 venv
-RUN python -m venv /opt/venv
 ENV PATH="/opt/venv/bin:$PATH"

-# 基础依赖
-COPY requirements-base.txt /tmp/requirements-base.txt
-RUN pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
-    -r /tmp/requirements-base.txt \
-    && rm /tmp/requirements-base.txt
+WORKDIR /tmp

-# Worker 专属大包
-COPY requirements-worker.txt /tmp/requirements-worker.txt
-RUN pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
-    -r /tmp/requirements-worker.txt \
-    && rm /tmp/requirements-worker.txt
-
-# 业务依赖
+# ---- 安装业务依赖（变化频繁，单独一层）----
 COPY requirements.txt /tmp/requirements.txt
-RUN pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
+RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
+    pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
    -r /tmp/requirements.txt \
    && rm /tmp/requirements.txt

-# ---- Python 依赖瘦身 ----
-# 1. strip .so 文件的调试符号（节省约 80-100MB）
+# ---- 增量瘦身（只处理新增的业务依赖）----
 RUN find /opt/venv -name "*.so" -type f -exec strip --strip-all {} \; 2>/dev/null || true
-
-# 2. 清理测试文件（节省约 20MB）
-RUN find /opt/venv -type d -name "tests" -exec rm -rf {} + 2>/dev/null; \
-    find /opt/venv -type d -name "test" -exec rm -rf {} + 2>/dev/null; \
-    find /opt/venv -name "test_*.py" -delete 2>/dev/null || true
-
-# 3. 清理 .pyc 缓存和 __pycache__（节省约 10MB，运行时按需生成）
 RUN find /opt/venv -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null; \
    find /opt/venv -name "*.pyc" -delete 2>/dev/null || true

-# 4. 清理 dist-info 中的文档
-RUN find /opt/venv -name "*.dist-info" -type d -exec sh -c 'rm -f "$1"/DESCRIPTION.rst "$1"/INSTALLER "$1"/LICENSE* "$1"/WHEEL "$1"/entry_points.txt' _ {} \; 2>/dev/null || true
-
 # ==================== Runtime 阶段 ====================
-FROM git.xiaoxiajianji.com/xiaoxia/base/python:3.12-slim AS runtime
+# 从预构建的runtime基础镜像开始，已经包含：
+#   - ffmpeg
+#   - libglib2.0-0
+FROM xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji/worker-base-runtime:latest AS runtime

 # 构建参数：版本号
 ARG APP_VERSION=dev

-# 使用阿里云镜像加速
-RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null || \
-    sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true
-
-# 安装最小运行时依赖（opencv-python-headless 需要 libglib2.0-0）
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    libglib2.0-0 \
-    && rm -rf /var/lib/apt/lists/*
-
-# 从 builder 复制 ffmpeg 静态二进制
-COPY --from=builder /usr/local/bin/ffmpeg /usr/local/bin/ffmpeg
-COPY --from=builder /usr/local/bin/ffprobe /usr/local/bin/ffprobe
-
 # 从 builder 复制 Python 虚拟环境
 COPY --from=builder /opt/venv /opt/venv

@@ -17,6 +17,9 @@ class InMemoryUserRepository(UserRepository):
        self._username_index: Dict[str, str] = {}  # username -> user_id
        self._verification_token_index: Dict[str, str] = {}  # token -> user_id
        self._reset_token_index: Dict[str, str] = {}  # token -> user_id
+        self._wechat_openid_index: Dict[str, str] = {}  # openid -> user_id
+        self._wechat_unionid_index: Dict[str, str] = {}  # unionid -> user_id
+        self._phone_index: Dict[str, str] = {}  # phone -> user_id

    def save(self, user: User) -> None:
        """保存用户"""
@@ -28,6 +31,12 @@ class InMemoryUserRepository(UserRepository):
            self._verification_token_index[user.email_verification_token] = user.id
        if user.password_reset_token:
            self._reset_token_index[user.password_reset_token] = user.id
+        if user.wechat_openid:
+            self._wechat_openid_index[user.wechat_openid] = user.id
+        if user.wechat_unionid:
+            self._wechat_unionid_index[user.wechat_unionid] = user.id
+        if user.phone:
+            self._phone_index[user.phone] = user.id

    def find_by_id(self, user_id: str) -> Optional[User]:
        """根据 ID 查找用户"""
@@ -61,6 +70,31 @@ class InMemoryUserRepository(UserRepository):
            return self._users.get(user_id)
        return None

+    def find_by_wechat_openid(self, openid: str) -> Optional[User]:
+        """根据微信 openid 查找用户"""
+        user_id = self._wechat_openid_index.get(openid)
+        if user_id:
+            return self._users.get(user_id)
+        return None
+
+    def find_by_wechat_unionid(self, unionid: str) -> Optional[User]:
+        """根据微信 unionid 查找用户"""
+        if not unionid:
+            return None
+        user_id = self._wechat_unionid_index.get(unionid)
+        if user_id:
+            return self._users.get(user_id)
+        return None
+
+    def find_by_phone(self, phone: str) -> Optional[User]:
+        """根据手机号查找用户"""
+        if not phone:
+            return None
+        user_id = self._phone_index.get(phone)
+        if user_id:
+            return self._users.get(user_id)
+        return None
+
    def delete(self, user_id: str) -> bool:
        """删除用户"""
        user = self._users.get(user_id)
@@ -0,0 +1,85 @@
+"""
+短信服务实现（Noop + 阿里云）
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+class NoopSmsService:
+    """空实现短信服务 - 开发/测试环境用，只打日志不真发"""
+
+    def send_verification_code(self, phone: str, code: str) -> bool:
+        logger.info("[NoopSMS] 发送验证码到 %s: %s", phone, code)
+        return True
+
+    def send_template_sms(self, phone: str, template_id: str, params: dict) -> bool:
+        logger.info("[NoopSMS] 发送模板短信到 %s, template=%s, params=%s", phone, template_id, params)
+        return True
+
+
+class AliyunSmsService:
+    """阿里云短信服务"""
+
+    def __init__(
+        self,
+        access_key_id: str | None = None,
+        access_key_secret: str | None = None,
+        sign_name: str | None = None,
+        verify_template_id: str | None = None,
+    ):
+        self.access_key_id = access_key_id or os.environ.get("ALIYUN_SMS_ACCESS_KEY_ID", "")
+        self.access_key_secret = access_key_secret or os.environ.get("ALIYUN_SMS_ACCESS_KEY_SECRET", "")
+        self.sign_name = sign_name or os.environ.get("ALIYUN_SMS_SIGN_NAME", "小应剪辑")
+        self.verify_template_id = verify_template_id or os.environ.get("ALIYUN_SMS_VERIFY_TEMPLATE_ID", "SMS_123456789")
+
+    def send_verification_code(self, phone: str, code: str) -> bool:
+        return self.send_template_sms(phone, self.verify_template_id, {"code": code})
+
+    def send_template_sms(self, phone: str, template_id: str, params: dict) -> bool:
+        try:
+            import json
+
+            from alibabacloud_dysmsapi20170525 import models as dysmsapi_models
+            from alibabacloud_dysmsapi20170525.client import Client as DysmsapiClient
+            from alibabacloud_tea_openapi import models as open_api_models
+
+            config = open_api_models.Config(
+                access_key_id=self.access_key_id,
+                access_key_secret=self.access_key_secret,
+            )
+            config.endpoint = "dysmsapi.aliyuncs.com"
+            client = DysmsapiClient(config)
+
+            request = dysmsapi_models.SendSmsRequest(
+                phone_numbers=phone,
+                sign_name=self.sign_name,
+                template_code=template_id,
+                template_param=json.dumps(params),
+            )
+            response = client.send_sms(request)
+            body = response.body
+            if body.code == "OK":
+                logger.info("阿里云短信发送成功: phone=%s, template=%s", phone, template_id)
+                return True
+            else:
+                logger.error("阿里云短信发送失败: code=%s, message=%s", body.code, body.message)
+                return False
+        except ImportError:
+            logger.error("阿里云短信 SDK 未安装，请 pip install alibabacloud-dysmsapi20170525")
+            return False
+        except Exception as e:
+            logger.error("阿里云短信发送异常: %s", e, exc_info=True)
+            return False
+
+
+def get_sms_service() -> "NoopSmsService | AliyunSmsService":
+    """获取短信服务实例"""
+    provider = os.environ.get("SMS_PROVIDER", "noop").lower()
+    if provider == "aliyun":
+        return AliyunSmsService()
+    return NoopSmsService()
@@ -100,7 +100,6 @@ class SQLAlchemyEditPlanRepository:
            name=plan.name,
            status=plan.status,
            total_duration=plan.total_duration,
-            result_count=plan.result_count,
            source_edit_plan_id=plan.source_edit_plan_id or None,
            project_id=plan.project_id or "",
            created_by_user_id=plan.created_by_user_id or "",
@@ -120,7 +119,6 @@ class SQLAlchemyEditPlanRepository:
        model.name = plan.name
        model.status = plan.status
        model.total_duration = plan.total_duration
-        model.result_count = plan.result_count
        model.source_edit_plan_id = plan.source_edit_plan_id or None
        model.project_id = plan.project_id or ""
        model.created_by_user_id = plan.created_by_user_id or ""
@@ -154,7 +152,6 @@ class SQLAlchemyEditPlanRepository:
            name=model.name,
            status=EditPlanStatus(model.status) if model.status else EditPlanStatus.DRAFT,
            total_duration=model.total_duration or 0.0,
-            result_count=int(model.result_count or 0),
            source_edit_plan_id=model.source_edit_plan_id or "",
            project_id=model.project_id or "",
            created_by_user_id=model.created_by_user_id or "",
@@ -34,6 +34,7 @@ def _to_domain(model: GenerationTaskModel) -> GenerationTask:
        asset_select_mode=model.asset_select_mode or "",
        batch_id=model.batch_id or "",
        video_title=getattr(model, "video_title", "") or "",
+        resolution=getattr(model, "resolution", "") or "",
        logs=model.logs or "[]",
        created_at=model.created_at,
        updated_at=model.updated_at,
@@ -70,6 +71,7 @@ class SQLAlchemyGenerationTaskRepository:
            asset_select_mode=task.asset_select_mode or "",
            batch_id=task.batch_id or "",
            video_title=task.video_title or "",
+            resolution=task.resolution or "",
            logs=task.logs,
            created_at=task.created_at,
            updated_at=task.updated_at,
@@ -230,6 +232,8 @@ class SQLAlchemyGenerationTaskRepository:
        model.batch_id = task.batch_id or ""
        if hasattr(model, "video_title"):
            model.video_title = task.video_title or ""
+        if hasattr(model, "resolution"):
+            model.resolution = task.resolution or ""
        model.logs = task.logs
        self.session.commit()
        return task
@@ -31,9 +31,13 @@ class UserModel(Base):
    used_storage_gb = Column(Integer, nullable=False, default=0)
    # 管理员标识
    is_admin = Column(Boolean, nullable=False, default=False)
-    # 微信登录（小程序端）
+    # 微信登录
    wechat_openid = Column(String(128), nullable=True, unique=True, index=True)
    wechat_unionid = Column(String(128), nullable=True, unique=True, index=True)
+    # 手机号绑定
+    phone = Column(String(32), nullable=True, unique=True, index=True)
+    phone_verified = Column(Boolean, nullable=False, default=False)
+    binding_completed_at = Column(DateTime, nullable=True)
    created_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))


@@ -172,7 +176,6 @@ class EditPlanModel(Base):
    name = Column(String(200), nullable=False)
    status = Column(String(20), nullable=False, default="draft", index=True)
    total_duration = Column(Float, nullable=False, default=0.0)
-    result_count = Column(Integer, nullable=False, default=0)
    config = Column(JSON, nullable=False, default=dict)
    source_edit_plan_id = Column(String(36), nullable=True, index=True)
    project_id = Column(String(36), nullable=False, default="", index=True)
@@ -288,6 +291,7 @@ class GenerationTaskModel(Base):
    asset_select_mode = Column(String(20), nullable=False, default="")
    batch_id = Column(String(36), nullable=False, default="", index=True)
    video_title = Column(String(255), nullable=False, default="")
+    resolution = Column(String(20), nullable=False, default="")
    extra_meta = Column("metadata", JSON, nullable=False, default=dict)
    logs = Column(Text, nullable=False, default="[]", server_default="[]")
    created_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))
@@ -556,3 +560,36 @@ class BillingRecordModel(Base):
    invoice_url = Column(String(500), nullable=True)
    created_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))
    paid_at = Column(DateTime, nullable=True)
+
+
+class VerificationCodeModel(Base):
+    """验证码（邮箱/手机统一管理）"""
+
+    __tablename__ = "verification_codes"
+
+    id = Column(String(36), primary_key=True)
+    recipient = Column(String(255), nullable=False, index=True)  # 邮箱或手机号
+    code = Column(String(10), nullable=False)
+    code_type = Column(String(32), nullable=False, index=True)  # email_bind / phone_bind / ...
+    expires_at = Column(DateTime, nullable=False)
+    used_at = Column(DateTime, nullable=True)
+    attempts = Column(Integer, nullable=False, default=0)
+    created_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))
+
+
+class VideoShareModel(Base):
+    """视频分享记录."""
+
+    __tablename__ = "video_shares"
+
+    id = Column(String(32), primary_key=True)
+    video_id = Column(String(32), nullable=False, index=True)
+    user_id = Column(String(32), nullable=False, index=True)
+    share_token = Column(String(16), nullable=False, unique=True)
+    password_hash = Column(String(255), nullable=True)
+    expires_at = Column(DateTime(timezone=True), nullable=True)
+    view_count = Column(Integer, nullable=False, default=0)
+    download_count = Column(Integer, nullable=False, default=0)
+    is_active = Column(Boolean, nullable=False, default=True)
+    created_at = Column(DateTime(timezone=True), nullable=False, default=lambda: datetime.now(timezone.utc))
+    updated_at = Column(DateTime(timezone=True), nullable=False, default=lambda: datetime.now(timezone.utc))
@@ -92,14 +92,20 @@ class SQLAlchemyTemplateClipConfigRepository:
        self.session.commit()
        return True

-    def delete_by_template(self, template_id: str) -> int:
-        """删除模板下所有片段配置，返回删除数量"""
+    def delete_by_template(self, template_id: str, *, commit: bool = True) -> int:
+        """删除模板下所有片段配置，返回删除数量
+
+        Args:
+            template_id: 模板ID
+            commit: 是否提交事务，默认True。外层有事务控制时传False。
+        """
        count = (
            self.session.query(TemplateClipConfigModel)
            .filter(TemplateClipConfigModel.template_id == template_id)
            .delete()
        )
-        self.session.commit()
+        if commit:
+            self.session.commit()
        return count

    def count(self, *, template_id: Optional[str] = None) -> int:
@@ -35,6 +35,9 @@ class SQLAlchemyUserRepository(UserRepository):
        model.is_admin = user.is_admin
        model.wechat_openid = user.wechat_openid
        model.wechat_unionid = user.wechat_unionid
+        model.phone = user.phone
+        model.phone_verified = user.phone_verified
+        model.binding_completed_at = user.binding_completed_at
        model.created_at = user.created_at

        self.session.commit()
@@ -61,6 +64,12 @@ class SQLAlchemyUserRepository(UserRepository):
        model = self.session.query(UserModel).filter(UserModel.wechat_unionid == unionid.strip()).first()
        return self._to_entity(model)

+    def find_by_phone(self, phone: str) -> User | None:
+        if not phone or not phone.strip():
+            return None
+        model = self.session.query(UserModel).filter(UserModel.phone == phone.strip()).first()
+        return self._to_entity(model)
+
    def find_by_verification_token(self, token: str) -> User | None:
        model = self.session.query(UserModel).filter(UserModel.email_verification_token == token).first()
        return self._to_entity(model)
@@ -101,5 +110,8 @@ class SQLAlchemyUserRepository(UserRepository):
            is_admin=model.is_admin or False,
            wechat_openid=model.wechat_openid,
            wechat_unionid=model.wechat_unionid,
+            phone=model.phone,
+            phone_verified=model.phone_verified or False,
+            binding_completed_at=model.binding_completed_at,
            created_at=model.created_at,
        )
@@ -0,0 +1,90 @@
+"""
+验证码仓储 SQLAlchemy 实现
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.models import VerificationCodeModel
+from packages.domain.verification_code import VerificationCode
+from packages.ports.verification_code_repository import VerificationCodeRepository
+
+
+class SQLAlchemyVerificationCodeRepository(VerificationCodeRepository):
+    def __init__(self, session: Session):
+        self.session = session
+
+    def save(self, code: VerificationCode) -> None:
+        model = self.session.get(VerificationCodeModel, code.id)
+        if model is None:
+            model = VerificationCodeModel(id=code.id)
+            self.session.add(model)
+
+        model.recipient = code.recipient
+        model.code = code.code
+        model.code_type = code.code_type
+        model.expires_at = code.expires_at
+        model.used_at = code.used_at
+        model.attempts = code.attempts
+        model.created_at = code.created_at
+
+        self.session.commit()
+        self.session.refresh(model)
+
+    def find_latest(self, recipient: str, code_type: str) -> Optional[VerificationCode]:
+        model = (
+            self.session.query(VerificationCodeModel)
+            .filter(
+                VerificationCodeModel.recipient == recipient.strip(),
+                VerificationCodeModel.code_type == code_type,
+            )
+            .order_by(VerificationCodeModel.created_at.desc())
+            .first()
+        )
+        return self._to_entity(model)
+
+    def find_by_id(self, code_id: str) -> Optional[VerificationCode]:
+        return self._to_entity(self.session.get(VerificationCodeModel, code_id))
+
+    def count_today(self, recipient: str, code_type: str) -> int:
+        now = datetime.now(timezone.utc)
+        start_of_day = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        return (
+            self.session.query(VerificationCodeModel)
+            .filter(
+                VerificationCodeModel.recipient == recipient.strip(),
+                VerificationCodeModel.code_type == code_type,
+                VerificationCodeModel.created_at >= start_of_day,
+            )
+            .count()
+        )
+
+    @staticmethod
+    def _to_entity(model: VerificationCodeModel | None) -> VerificationCode | None:
+        if model is None:
+            return None
+
+        # SQLAlchemy 从数据库读出的 DateTime 是 naive（不带时区），
+        # 领域模型期望 aware datetime（带 timezone.utc），直接用会报
+        # "can't compare offset-naive and offset-aware datetimes"
+        def _ensure_aware(dt: datetime | None) -> datetime | None:
+            if dt is None:
+                return None
+            if dt.tzinfo is None:
+                return dt.replace(tzinfo=timezone.utc)
+            return dt
+
+        return VerificationCode(
+            id=model.id,
+            recipient=model.recipient,
+            code=model.code,
+            code_type=model.code_type,
+            expires_at=_ensure_aware(model.expires_at),
+            used_at=_ensure_aware(model.used_at),
+            attempts=model.attempts,
+            created_at=_ensure_aware(model.created_at),
+        )
@@ -0,0 +1,147 @@
+"""视频分享 SQLAlchemy Repository 实现."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.models import VideoShareModel
+from packages.domain.video_share import VideoShare
+from packages.ports.video_share_repository import VideoShareRepositoryPort
+
+
+def _model_to_domain(model: VideoShareModel) -> VideoShare:
+    return VideoShare(
+        id=model.id,
+        video_id=model.video_id,
+        user_id=model.user_id,
+        share_token=model.share_token,
+        password_hash=model.password_hash,
+        expires_at=model.expires_at,
+        view_count=model.view_count or 0,
+        download_count=model.download_count or 0,
+        is_active=model.is_active if model.is_active is not None else True,
+        created_at=model.created_at,
+        updated_at=model.updated_at,
+    )
+
+
+class SQLAlchemyVideoShareRepository(VideoShareRepositoryPort):
+    def __init__(self, session: Session):
+        self.session = session
+
+    def create(self, share: VideoShare) -> VideoShare:
+        model = VideoShareModel(
+            id=share.id,
+            video_id=share.video_id,
+            user_id=share.user_id,
+            share_token=share.share_token,
+            password_hash=share.password_hash,
+            expires_at=share.expires_at,
+            view_count=share.view_count,
+            download_count=share.download_count,
+            is_active=share.is_active,
+            created_at=share.created_at,
+            updated_at=share.updated_at,
+        )
+        self.session.add(model)
+        self.session.commit()
+        return share
+
+    def get_by_token(self, token: str) -> Optional[VideoShare]:
+        model = self.session.query(VideoShareModel).filter(VideoShareModel.share_token == token).first()
+        if model is None:
+            return None
+        return _model_to_domain(model)
+
+    def get_by_id(self, share_id: str, user_id: str) -> Optional[VideoShare]:
+        model = (
+            self.session.query(VideoShareModel)
+            .filter(
+                VideoShareModel.id == share_id,
+                VideoShareModel.user_id == user_id,
+            )
+            .first()
+        )
+        if model is None:
+            return None
+        return _model_to_domain(model)
+
+    def list_by_video(self, video_id: str, user_id: str) -> List[VideoShare]:
+        models = (
+            self.session.query(VideoShareModel)
+            .filter(
+                VideoShareModel.video_id == video_id,
+                VideoShareModel.user_id == user_id,
+            )
+            .order_by(VideoShareModel.created_at.desc())
+            .all()
+        )
+        return [_model_to_domain(m) for m in models]
+
+    def list_by_user(self, user_id: str, skip: int = 0, limit: int = 20) -> List[VideoShare]:
+        models = (
+            self.session.query(VideoShareModel)
+            .filter(VideoShareModel.user_id == user_id)
+            .order_by(VideoShareModel.created_at.desc())
+            .offset(skip)
+            .limit(limit)
+            .all()
+        )
+        return [_model_to_domain(m) for m in models]
+
+    def count_by_user(self, user_id: str) -> int:
+        return self.session.query(VideoShareModel).filter(VideoShareModel.user_id == user_id).count()
+
+    def update(self, share: VideoShare) -> VideoShare:
+        model = self.session.query(VideoShareModel).filter(VideoShareModel.id == share.id).first()
+        if model is None:
+            return share
+        model.password_hash = share.password_hash
+        model.expires_at = share.expires_at
+        model.is_active = share.is_active
+        model.view_count = share.view_count
+        model.download_count = share.download_count
+        model.updated_at = datetime.now(timezone.utc)
+        self.session.add(model)
+        self.session.commit()
+        return share
+
+    def delete(self, share_id: str, user_id: str) -> bool:
+        model = (
+            self.session.query(VideoShareModel)
+            .filter(
+                VideoShareModel.id == share_id,
+                VideoShareModel.user_id == user_id,
+            )
+            .first()
+        )
+        if model is None:
+            return False
+        model.is_active = False
+        model.updated_at = datetime.now(timezone.utc)
+        self.session.add(model)
+        self.session.commit()
+        return True
+
+    def increment_view(self, share_id: str) -> None:
+        self.session.query(VideoShareModel).filter(VideoShareModel.id == share_id).update(
+            {
+                "view_count": VideoShareModel.view_count + 1,
+                "updated_at": datetime.now(timezone.utc),
+            },
+            synchronize_session=False,
+        )
+        self.session.commit()
+
+    def increment_download(self, share_id: str) -> None:
+        self.session.query(VideoShareModel).filter(VideoShareModel.id == share_id).update(
+            {
+                "download_count": VideoShareModel.download_count + 1,
+                "updated_at": datetime.now(timezone.utc),
+            },
+            synchronize_session=False,
+        )
+        self.session.commit()
@@ -0,0 +1,231 @@
+"""
+微信登录 + 绑定手机号邮箱 Use Case
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Optional
+
+from packages.application.auth.verification_code_service import (
+    CODE_TYPE_EMAIL_BIND,
+    CODE_TYPE_PHONE_BIND,
+    normalize_phone,
+    validate_email,
+    validate_phone,
+)
+from packages.domain.entities import User
+
+logger = logging.getLogger(__name__)
+
+
+class BindContactRequest:
+    """绑定联系方式请求"""
+
+    def __init__(
+        self,
+        user_id: str,
+        phone: str = "",
+        phone_code: str = "",
+        email: str = "",
+        email_code: str = "",
+    ):
+        self.user_id = user_id
+        self.phone = normalize_phone(phone) if phone else ""
+        self.phone_code = phone_code.strip() if phone_code else ""
+        self.email = email.strip().lower() if email else ""
+        self.email_code = email_code.strip() if email_code else ""
+
+
+class BindContactResponse:
+    """绑定响应"""
+
+    def __init__(self, user: User):
+        self.user = user
+
+    def to_dict(self) -> dict:
+        return {
+            "user": {
+                "id": self.user.id,
+                "email": self.user.email,
+                "phone": self.user.phone,
+                "phone_verified": self.user.phone_verified,
+                "display_name": self.user.display_name,
+                "binding_complete": self.user.binding_completed_at is not None,
+            }
+        }
+
+
+class BindContactUseCase:
+    """绑定手机+邮箱用例"""
+
+    def __init__(
+        self,
+        user_repository,
+        verification_code_service,
+        email_service=None,
+    ):
+        self.user_repo = user_repository
+        self.verification_service = verification_code_service
+        self.email_service = email_service
+
+    def execute(self, request: BindContactRequest) -> tuple[Optional[BindContactResponse], Optional[str]]:
+        try:
+            # 1. 校验参数
+            if not request.phone and not request.email:
+                return None, "至少填写手机号或邮箱"
+
+            # 2. 查找用户
+            user = self.user_repo.find_by_id(request.user_id)
+            if not user:
+                return None, "用户不存在"
+
+            # 3. 手机号绑定
+            if request.phone:
+                ok, err = validate_phone(request.phone)
+                if not ok:
+                    return None, err
+
+                if not request.phone_code:
+                    return None, "请输入手机验证码"
+
+                # 校验手机号未被其他账号绑定
+                existing = self.user_repo.find_by_phone(request.phone)
+                if existing and existing.id != user.id:
+                    return None, "该手机号已被其他账号绑定"
+
+                # 校验验证码
+                ok, err = self.verification_service.verify(
+                    recipient=request.phone,
+                    code_type=CODE_TYPE_PHONE_BIND,
+                    code_value=request.phone_code,
+                )
+                if not ok:
+                    return None, f"手机验证码错误：{err}"
+
+                user.phone = request.phone
+                user.phone_verified = True
+
+            # 4. 邮箱绑定
+            if request.email:
+                ok, err = validate_email(request.email)
+                if not ok:
+                    return None, err
+
+                if not request.email_code:
+                    return None, "请输入邮箱验证码"
+
+                # 校验邮箱未被其他账号绑定
+                existing = self.user_repo.find_by_email(request.email)
+                if existing and existing.id != user.id:
+                    return None, "该邮箱已被其他账号绑定"
+
+                # 校验验证码
+                ok, err = self.verification_service.verify(
+                    recipient=request.email,
+                    code_type=CODE_TYPE_EMAIL_BIND,
+                    code_value=request.email_code,
+                )
+                if not ok:
+                    return None, f"邮箱验证码错误：{err}"
+
+                user.email = request.email
+                user.email_verified = True
+
+            # 5. 判断是否完成绑定
+            if user.phone_verified and user.email_verified and "@wechat.local" not in user.email:
+                user.binding_completed_at = datetime.now(timezone.utc)
+
+            # 6. 保存
+            self.user_repo.save(user)
+
+            return BindContactResponse(user=user), None
+
+        except Exception as e:
+            logger.error("绑定联系方式失败: %s", e, exc_info=True)
+            return None, f"绑定失败: {str(e)}"
+
+
+class SendVerificationCodeRequest:
+    """发送验证码请求"""
+
+    def __init__(self, target: str, value: str, purpose: str):
+        self.target = target  # phone / email
+        self.value = value.strip()
+        self.purpose = purpose  # bind / login / reset_password
+
+
+class SendVerificationCodeResponse:
+    """发送验证码响应"""
+
+    def __init__(self, expires_in: int, resend_after: int):
+        self.expires_in = expires_in
+        self.resend_after = resend_after
+
+    def to_dict(self) -> dict:
+        return {
+            "expires_in": self.expires_in,
+            "resend_after": self.resend_after,
+        }
+
+
+class SendVerificationCodeUseCase:
+    """发送验证码用例"""
+
+    def __init__(
+        self,
+        verification_code_service,
+        sms_service=None,
+        email_service=None,
+    ):
+        self.verification_service = verification_code_service
+        self.sms_service = sms_service
+        self.email_service = email_service
+
+    def execute(
+        self, request: SendVerificationCodeRequest
+    ) -> tuple[Optional[SendVerificationCodeResponse], Optional[str]]:
+        try:
+            # 1. 确定 code_type
+            if request.target == "phone":
+                ok, err = validate_phone(request.value)
+                if not ok:
+                    return None, err
+                code_type = f"{request.target}_{request.purpose}"
+                recipient = normalize_phone(request.value)
+            elif request.target == "email":
+                ok, err = validate_email(request.value)
+                if not ok:
+                    return None, err
+                code_type = f"{request.target}_{request.purpose}"
+                recipient = request.value.lower()
+            else:
+                return None, f"不支持的目标类型: {request.target}"
+
+            # 2. 生成验证码
+            code_obj, err = self.verification_service.generate(recipient, code_type)
+            if err:
+                return None, err
+
+            # 3. 发送
+            if request.target == "phone" and self.sms_service:
+                self.sms_service.send_verification_code(recipient, code_obj.code)
+            elif request.target == "email" and self.email_service:
+                subject = "验证码 - 小应剪辑"
+                body = f"您的验证码是：{code_obj.code}，5分钟内有效。"
+                self.email_service.send_email(recipient, subject, body)
+
+            # 4. 返回
+            ttl = (code_obj.expires_at - code_obj.created_at).total_seconds()
+            return (
+                SendVerificationCodeResponse(
+                    expires_in=int(ttl),
+                    resend_after=60,
+                ),
+                None,
+            )
+
+        except Exception as e:
+            logger.error("发送验证码失败: %s", e, exc_info=True)
+            return None, f"发送失败: {str(e)}"
@@ -0,0 +1,206 @@
+"""
+验证码服务
+- 生成验证码
+- 校验验证码
+- 频控（60s 冷却 + 每日上限）
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from datetime import datetime, timezone
+from typing import Optional
+
+from packages.domain.verification_code import VerificationCode
+from packages.ports.verification_code_repository import VerificationCodeRepository
+
+logger = logging.getLogger(__name__)
+
+# 频控参数
+RESEND_COOLDOWN_SECONDS = 60  # 重发冷却时间
+DAILY_LIMIT = 10  # 每日发送上限
+MAX_ATTEMPTS = 5  # 单验证码最大尝试次数
+DEFAULT_TTL_SECONDS = 300  # 默认有效期 5 分钟
+
+# 验证码类型
+CODE_TYPE_EMAIL_BIND = "email_bind"
+CODE_TYPE_PHONE_BIND = "phone_bind"
+CODE_TYPE_EMAIL_LOGIN = "email_login"
+CODE_TYPE_PHONE_LOGIN = "phone_login"
+CODE_TYPE_RESET_PASSWORD = "reset_password"
+
+VALID_CODE_TYPES = {
+    CODE_TYPE_EMAIL_BIND,
+    CODE_TYPE_PHONE_BIND,
+    CODE_TYPE_EMAIL_LOGIN,
+    CODE_TYPE_PHONE_LOGIN,
+    CODE_TYPE_RESET_PASSWORD,
+}
+
+
+class VerificationCodeService:
+    """验证码服务"""
+
+    def __init__(
+        self,
+        repo: VerificationCodeRepository,
+        resend_cooldown: int = RESEND_COOLDOWN_SECONDS,
+        daily_limit: int = DAILY_LIMIT,
+        max_attempts: int = MAX_ATTEMPTS,
+        default_ttl: int = DEFAULT_TTL_SECONDS,
+    ):
+        self.repo = repo
+        self.resend_cooldown = resend_cooldown
+        self.daily_limit = daily_limit
+        self.max_attempts = max_attempts
+        self.default_ttl = default_ttl
+
+    def generate(
+        self,
+        recipient: str,
+        code_type: str,
+        ttl_seconds: int | None = None,
+        custom_code: str | None = None,
+    ) -> tuple[Optional[VerificationCode], Optional[str]]:
+        """
+        生成验证码
+
+        Returns:
+            (验证码实体, 错误信息)
+        """
+        recipient = recipient.strip()
+
+        # 参数校验
+        if not recipient:
+            return None, "接收方不能为空"
+        if code_type not in VALID_CODE_TYPES:
+            return None, f"无效的验证码类型: {code_type}"
+
+        # 频控检查
+        can_send, wait_seconds = self._check_rate_limit(recipient, code_type)
+        if not can_send:
+            if wait_seconds > 0:
+                return None, f"发送太频繁，请 {wait_seconds} 秒后再试"
+            return None, "今日发送次数已达上限"
+
+        # 生成并保存
+        code = VerificationCode.create(
+            recipient=recipient,
+            code_type=code_type,
+            ttl_seconds=ttl_seconds or self.default_ttl,
+            custom_code=custom_code,
+        )
+        self.repo.save(code)
+
+        return code, None
+
+    def verify(
+        self,
+        recipient: str,
+        code_type: str,
+        code_value: str,
+        consume: bool = True,
+    ) -> tuple[bool, Optional[str]]:
+        """
+        校验验证码
+
+        Args:
+            recipient: 接收方（邮箱/手机号）
+            code_type: 验证码类型
+            code_value: 用户输入的验证码
+            consume: 校验成功后是否标记为已使用
+
+        Returns:
+            (是否通过, 错误信息)
+        """
+        recipient = recipient.strip()
+        code_value = code_value.strip()
+
+        if not recipient or not code_value:
+            return False, "参数不完整"
+
+        # 查找最新的验证码
+        latest = self.repo.find_latest(recipient, code_type)
+        if not latest:
+            return False, "验证码不存在或已过期"
+
+        # 增加尝试次数
+        latest.increment_attempts()
+        self.repo.save(latest)
+
+        # 检查是否已使用
+        if latest.is_used:
+            return False, "验证码已使用，请重新获取"
+
+        # 检查是否过期
+        if latest.is_expired:
+            return False, "验证码已过期，请重新获取"
+
+        # 检查尝试次数
+        if latest.attempts > self.max_attempts:
+            return False, "验证次数过多，请重新获取验证码"
+
+        # 校验验证码
+        if latest.code != code_value:
+            return False, "验证码错误"
+
+        # 校验通过，标记为已使用
+        if consume:
+            latest.mark_used()
+            self.repo.save(latest)
+
+        return True, None
+
+    def _check_rate_limit(self, recipient: str, code_type: str) -> tuple[bool, int]:
+        """
+        频控检查
+
+        Returns:
+            (是否允许发送, 需等待秒数)
+        """
+        # 检查冷却时间
+        latest = self.repo.find_latest(recipient, code_type)
+        if latest:
+            elapsed = (datetime.now(timezone.utc) - latest.created_at).total_seconds()
+            if elapsed < self.resend_cooldown:
+                wait = int(self.resend_cooldown - elapsed)
+                return False, wait
+
+        # 检查每日上限
+        today_count = self.repo.count_today(recipient, code_type)
+        if today_count >= self.daily_limit:
+            return False, 0
+
+        return True, 0
+
+
+def validate_phone(phone: str) -> tuple[bool, str]:
+    """校验手机号格式（中国大陆手机号）"""
+    phone = phone.strip()
+    if not phone:
+        return False, "手机号不能为空"
+    # 支持 +86 前缀或纯 11 位
+    pattern = r"^(\+86)?1[3-9]\d{9}$"
+    if not re.match(pattern, phone):
+        return False, "手机号格式不正确"
+    return True, ""
+
+
+def normalize_phone(phone: str) -> str:
+    """标准化手机号（去掉 +86 前缀，统一存储格式）"""
+    phone = phone.strip()
+    if phone.startswith("+86"):
+        phone = phone[3:]
+    return phone
+
+
+def validate_email(email: str) -> tuple[bool, str]:
+    """校验邮箱格式"""
+    email = email.strip()
+    if not email:
+        return False, "邮箱不能为空"
+    pattern = r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"
+    if not re.match(pattern, email):
+        return False, "邮箱格式不正确"
+    return True, ""
@@ -0,0 +1,206 @@
+"""
+微信 OAuth 服务
+- 生成授权链接（网页扫码登录）
+- 处理回调，用 code 换 access_token + 用户信息
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+import urllib.parse
+from dataclasses import dataclass
+from threading import Lock
+from typing import Optional
+from uuid import uuid4
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+STATE_TTL_SECONDS = 600  # state 有效期 10 分钟
+
+
+class MemoryStateStore:
+    """内存 state 存储（简单实现，单节点可用）
+
+    多实例部署时建议替换为 Redis 实现。
+    """
+
+    def __init__(self, ttl_seconds: int = STATE_TTL_SECONDS):
+        self._ttl = ttl_seconds
+        self._states: dict[str, float] = {}  # state -> expire_at
+        self._lock = Lock()
+
+    def put(self, state: str) -> None:
+        with self._lock:
+            self._clean_expired()
+            self._states[state] = time.time() + self._ttl
+
+    def verify_and_consume(self, state: str) -> bool:
+        with self._lock:
+            self._clean_expired()
+            if state in self._states:
+                del self._states[state]
+                return True
+            return False
+
+    def _clean_expired(self) -> None:
+        now = time.time()
+        expired = [s for s, exp in self._states.items() if exp < now]
+        for s in expired:
+            del self._states[s]
+
+
+@dataclass
+class WechatUserInfo:
+    """微信用户信息"""
+
+    openid: str
+    unionid: str = ""
+    nickname: str = ""
+    avatar_url: str = ""
+
+
+class WechatOAuthService:
+    """微信开放平台 OAuth 服务（网页扫码登录）"""
+
+    def __init__(
+        self,
+        app_id: str | None = None,
+        app_secret: str | None = None,
+        redirect_uri: str | None = None,
+        state_store=None,
+    ):
+        self.app_id = app_id or os.environ.get("WECHAT_OPEN_APP_ID", "")
+        self.app_secret = app_secret or os.environ.get("WECHAT_OPEN_APP_SECRET", "")
+        self.redirect_uri = redirect_uri or os.environ.get("WECHAT_OPEN_REDIRECT_URI", "")
+        # state 存储（CSRF 防护），默认内存实现
+        self._state_store = state_store or MemoryStateStore()
+
+    def is_configured(self) -> bool:
+        """检查微信配置是否完整"""
+        return bool(self.app_id and self.app_secret and self.redirect_uri)
+
+    def generate_auth_url(self, scope: str = "snsapi_login") -> tuple[str, str]:
+        """
+        生成微信授权链接
+
+        Returns:
+            (授权URL, state)
+        """
+        state = uuid4().hex
+        # 保存 state 用于回调校验（防 CSRF）
+        self._state_store.put(state)
+
+        if not self.is_configured():
+            # 未配置时返回 mock URL，方便前端联调
+            mock_params = urllib.parse.urlencode(
+                {
+                    "app_id": "mock",
+                    "redirect_uri": self.redirect_uri,
+                    "scope": scope,
+                    "state": state,
+                }
+            )
+            return f"/mock/wechat/auth?{mock_params}", state
+
+        params = {
+            "appid": self.app_id,
+            "redirect_uri": self.redirect_uri,
+            "response_type": "code",
+            "scope": scope,
+            "state": state,
+        }
+        url = "https://open.weixin.qq.com/connect/qrconnect?" + urllib.parse.urlencode(params) + "#wechat_redirect"
+        return url, state
+
+    def handle_callback(self, code: str, state: str) -> tuple[Optional[WechatUserInfo], Optional[str]]:
+        """
+        处理微信回调
+
+        Args:
+            code: 微信授权码
+            state: 防 CSRF 状态
+
+        Returns:
+            (微信用户信息, 错误信息)
+        """
+        if not code:
+            return None, "缺少授权码"
+
+        # 校验 state（防 CSRF）—— 一次性使用
+        if not state or not self._state_store.verify_and_consume(state):
+            logger.warning("微信回调 state 校验失败: state=%s", state)
+            return None, "无效的 state 参数，请求可能已过期或被篡改"
+
+        if not self.is_configured():
+            # 开发模式：返回 mock 用户信息
+            logger.info("微信未配置，使用 mock 用户信息")
+            return (
+                WechatUserInfo(
+                    openid=f"mock_{code[:20]}",
+                    unionid=f"mock_union_{code[:16]}",
+                    nickname="微信测试用户",
+                    avatar_url="",
+                ),
+                None,
+            )
+
+        try:
+            # 1. 用 code 换 access_token
+            token_url = "https://api.weixin.qq.com/sns/oauth2/access_token"
+            token_params = {
+                "appid": self.app_id,
+                "secret": self.app_secret,
+                "code": code,
+                "grant_type": "authorization_code",
+            }
+            token_resp = requests.get(token_url, params=token_params, timeout=10)
+            token_data = token_resp.json()
+
+            if "errcode" in token_data and token_data["errcode"] != 0:
+                logger.error("微信获取 access_token 失败: %s", token_data)
+                return None, f"微信授权失败: {token_data.get('errmsg', '未知错误')}"
+
+            access_token = token_data["access_token"]
+            openid = token_data["openid"]
+            unionid = token_data.get("unionid", "")
+
+            # 2. 获取用户信息
+            user_url = "https://api.weixin.qq.com/sns/userinfo"
+            user_params = {
+                "access_token": access_token,
+                "openid": openid,
+                "lang": "zh_CN",
+            }
+            user_resp = requests.get(user_url, params=user_params, timeout=10)
+            user_data = user_resp.json()
+
+            if "errcode" in user_data and user_data["errcode"] != 0:
+                logger.error("微信获取用户信息失败: %s", user_data)
+                return None, f"获取用户信息失败: {user_data.get('errmsg', '未知错误')}"
+
+            return (
+                WechatUserInfo(
+                    openid=openid,
+                    unionid=unionid,
+                    nickname=user_data.get("nickname", ""),
+                    avatar_url=user_data.get("headimgurl", ""),
+                ),
+                None,
+            )
+
+        except requests.RequestException as e:
+            logger.error("微信 OAuth 请求异常: %s", e, exc_info=True)
+            return None, "微信服务暂不可用，请稍后再试"
+        except Exception as e:
+            logger.error("微信回调处理异常: %s", e, exc_info=True)
+            return None, "微信登录处理失败"
+
+
+def get_wechat_oauth_service() -> WechatOAuthService:
+    """获取微信 OAuth 服务单例"""
+    # TODO: 可替换为 Redis state store
+    return WechatOAuthService()
@@ -22,6 +22,7 @@ class CreateGenerationTaskCommand:
    asset_select_mode: str = ""
    batch_id: str = ""
    video_title: str = ""
+    resolution: str = ""
    auto_retry_enabled: bool = False
    auto_retry_max: int = 0

@@ -50,6 +51,7 @@ class CreateGenerationTaskUseCase:
            asset_select_mode=command.asset_select_mode,
            batch_id=command.batch_id,
            video_title=command.video_title,
+            resolution=command.resolution,
            auto_retry_enabled=command.auto_retry_enabled,
            auto_retry_max=command.auto_retry_max,
        )
@@ -0,0 +1,35 @@
+"""视频分享 Commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+
+
+@dataclass
+class CreateShareCommand:
+    """创建分享链接命令."""
+
+    video_id: str
+    user_id: str
+    password: Optional[str] = None
+    expires_at: Optional[datetime] = None  # None表示永久有效
+
+
+@dataclass
+class VerifySharePasswordCommand:
+    """验证分享密码命令."""
+
+    share_token: str
+    password: str
+
+
+@dataclass
+class UpdateShareCommand:
+    """更新分享配置命令."""
+
+    share_id: str
+    user_id: str
+    password: Optional[str] = None  # None表示不修改，空字符串表示清除密码
+    expires_at: Optional[datetime] = None  # None表示不修改
@@ -0,0 +1,227 @@
+"""视频分享 Use cases."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from packages.application.video_share.commands import (
+    CreateShareCommand,
+    UpdateShareCommand,
+)
+from packages.domain.generated_video import GeneratedVideo
+from packages.domain.video_share import VideoShare
+from packages.ports.generated_video_repository import GeneratedVideoRepository
+from packages.ports.video_share_repository import VideoShareRepositoryPort
+
+
+class NotFoundError(Exception):
+    """分享记录不存在."""
+
+    pass
+
+
+class VideoNotFoundError(Exception):
+    """视频不存在."""
+
+    pass
+
+
+class ShareExpiredError(Exception):
+    """分享已过期或已撤销."""
+
+    pass
+
+
+class PasswordRequiredError(Exception):
+    """需要访问密码."""
+
+    pass
+
+
+class InvalidPasswordError(Exception):
+    """密码错误."""
+
+    pass
+
+
+@dataclass
+class ShareAccessResult:
+    """分享访问结果（验证通过后返回视频信息+分享记录）."""
+
+    share: VideoShare
+    video: GeneratedVideo
+    password_verified: bool = True
+
+
+class CreateShareUseCase:
+    """创建视频分享链接."""
+
+    def __init__(
+        self,
+        share_repository: VideoShareRepositoryPort,
+        video_repository: GeneratedVideoRepository,
+    ) -> None:
+        self.share_repo = share_repository
+        self.video_repo = video_repository
+
+    def execute(self, command: CreateShareCommand) -> VideoShare:
+        # 校验视频存在且属于该用户
+        video = self.video_repo.get(command.video_id)
+        if video is None:
+            raise VideoNotFoundError(f"Video {command.video_id} not found")
+
+        # 用 user_id 校验（视频的user_id需要匹配）
+        if hasattr(video, "user_id") and video.user_id and video.user_id != command.user_id:
+            raise VideoNotFoundError("Video not found")
+
+        share = VideoShare.create(
+            video_id=command.video_id,
+            user_id=command.user_id,
+            password=command.password,
+            expires_at=command.expires_at,
+        )
+        return self.share_repo.create(share)
+
+
+class GetShareByTokenUseCase:
+    """通过token获取分享信息（不带视频内容，仅元信息）。
+
+    用于分享页加载前判断：是否需要密码、是否过期等。
+    """
+
+    def __init__(self, share_repository: VideoShareRepositoryPort) -> None:
+        self.share_repo = share_repository
+
+    def execute(self, token: str) -> VideoShare:
+        share = self.share_repo.get_by_token(token)
+        if share is None:
+            raise NotFoundError(f"Share not found: {token}")
+        if not share.is_accessible:
+            raise ShareExpiredError("Share is not accessible")
+        return share
+
+
+class AccessShareUseCase:
+    """访问分享内容（验证密码+返回视频信息+计数浏览量）。"""
+
+    def __init__(
+        self,
+        share_repository: VideoShareRepositoryPort,
+        video_repository: GeneratedVideoRepository,
+    ) -> None:
+        self.share_repo = share_repository
+        self.video_repo = video_repository
+
+    def execute(self, token: str, password: Optional[str] = None) -> ShareAccessResult:
+        share = self.share_repo.get_by_token(token)
+        if share is None:
+            raise NotFoundError(f"Share not found: {token}")
+        if not share.is_accessible:
+            raise ShareExpiredError("Share is not accessible")
+
+        # 密码校验
+        password_verified = True
+        if share.has_password:
+            if not password:
+                raise PasswordRequiredError("Password required")
+            if not share.verify_password(password):
+                raise InvalidPasswordError("Invalid password")
+            password_verified = True
+
+        # 获取视频信息
+        video = self.video_repo.get(share.video_id)
+        if video is None:
+            raise VideoNotFoundError("Video not found")
+
+        # 浏览量+1
+        self.share_repo.increment_view(share.id)
+        share.view_count += 1
+
+        return ShareAccessResult(share=share, video=video, password_verified=password_verified)
+
+
+class ListSharesByVideoUseCase:
+    """列出某个视频的所有分享记录."""
+
+    def __init__(self, share_repository: VideoShareRepositoryPort) -> None:
+        self.share_repo = share_repository
+
+    def execute(self, video_id: str, user_id: str) -> List[VideoShare]:
+        return self.share_repo.list_by_video(video_id, user_id)
+
+
+class ListSharesByUserUseCase:
+    """列出用户创建的所有分享记录."""
+
+    def __init__(self, share_repository: VideoShareRepositoryPort) -> None:
+        self.share_repo = share_repository
+
+    def execute(self, user_id: str, skip: int = 0, limit: int = 20) -> tuple[List[VideoShare], int]:
+        items = self.share_repo.list_by_user(user_id, skip=skip, limit=limit)
+        total = self.share_repo.count_by_user(user_id)
+        return items, total
+
+
+class UpdateShareUseCase:
+    """更新分享配置（密码、有效期等）."""
+
+    def __init__(self, share_repository: VideoShareRepositoryPort) -> None:
+        self.share_repo = share_repository
+
+    def execute(self, command: UpdateShareCommand) -> VideoShare:
+        share = self.share_repo.get_by_id(command.share_id, command.user_id)
+        if share is None:
+            raise NotFoundError(f"Share {command.share_id} not found")
+
+        # password=None表示不修改；空字符串表示清除密码
+        if command.password is not None:
+            from packages.domain.video_share import _hash_password
+
+            if command.password == "":
+                share.password_hash = None
+            else:
+                share.password_hash = _hash_password(command.password)
+
+        # expires_at=None表示不修改
+        if command.expires_at is not None:
+            if command.expires_at < datetime.now(timezone.utc):
+                raise ValueError("expires_at cannot be in the past")
+            share.expires_at = command.expires_at
+
+        return self.share_repo.update(share)
+
+
+class RevokeShareUseCase:
+    """撤销/删除分享."""
+
+    def __init__(self, share_repository: VideoShareRepositoryPort) -> None:
+        self.share_repo = share_repository
+
+    def execute(self, share_id: str, user_id: str) -> bool:
+        share = self.share_repo.get_by_id(share_id, user_id)
+        if share is None:
+            raise NotFoundError(f"Share {share_id} not found")
+        return self.share_repo.delete(share_id, user_id)
+
+
+class RecordShareDownloadUseCase:
+    """记录分享下载（下载量+1）."""
+
+    def __init__(self, share_repository: VideoShareRepositoryPort) -> None:
+        self.share_repo = share_repository
+
+    def execute(self, token: str, password: Optional[str] = None) -> None:
+        share = self.share_repo.get_by_token(token)
+        if share is None:
+            raise NotFoundError(f"Share not found: {token}")
+        if not share.is_accessible:
+            raise ShareExpiredError("Share is not accessible")
+
+        # 密码校验
+        if share.has_password:
+            if not password or not share.verify_password(password):
+                raise InvalidPasswordError("Invalid password")
+
+        self.share_repo.increment_download(share.id)
@@ -0,0 +1,19 @@
+"""
+短信服务接口
+"""
+
+from abc import ABC, abstractmethod
+
+
+class SmsService(ABC):
+    """短信服务接口"""
+
+    @abstractmethod
+    def send_verification_code(self, phone: str, code: str) -> bool:
+        """发送验证码短信"""
+        pass
+
+    @abstractmethod
+    def send_template_sms(self, phone: str, template_id: str, params: dict) -> bool:
+        """发送模板短信"""
+        pass
@@ -42,7 +42,6 @@ class EditPlan:
    name: str
    status: EditPlanStatus = EditPlanStatus.DRAFT
    total_duration: float = 0.0
-    result_count: int = 0
    source_edit_plan_id: str = ""
    project_id: str = ""
    created_by_user_id: str = ""
@@ -58,7 +57,6 @@ class EditPlan:
        *,
        config: dict[str, Any] | None = None,
        total_duration: float = 0.0,
-        result_count: int = 0,
        source_edit_plan_id: str = "",
        project_id: str = "",
        created_by_user_id: str = "",
@@ -75,7 +73,6 @@ class EditPlan:
            name=clean_name,
            status=EditPlanStatus.DRAFT,
            total_duration=total_duration,
-            result_count=result_count,
            source_edit_plan_id=source_edit_plan_id.strip(),
            project_id=project_id.strip(),
            created_by_user_id=created_by_user_id.strip(),
@@ -59,6 +59,11 @@ class User:
    wechat_openid: str | None = None
    wechat_unionid: str | None = None

+    # 手机号绑定
+    phone: str | None = None
+    phone_verified: bool = False
+    binding_completed_at: datetime | None = None
+
    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))


@@ -91,6 +91,7 @@ class GenerationTask:
    asset_select_mode: str = ""
    batch_id: str = ""
    video_title: str = ""
+    resolution: str = ""
    logs: str = "[]"
    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
    updated_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
@@ -112,6 +113,7 @@ class GenerationTask:
        asset_select_mode: str = "",
        batch_id: str = "",
        video_title: str = "",
+        resolution: str = "",
        auto_retry_enabled: bool = False,
        auto_retry_max: int = 0,
    ) -> "GenerationTask":
@@ -134,6 +136,7 @@ class GenerationTask:
            asset_select_mode=asset_select_mode,
            batch_id=batch_id,
            video_title=video_title.strip(),
+            resolution=resolution.strip(),
            auto_retry_enabled=auto_retry_enabled,
            auto_retry_max=auto_retry_max,
        )
@@ -0,0 +1,66 @@
+"""
+验证码领域实体
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from uuid import uuid4
+
+
+@dataclass(slots=True)
+class VerificationCode:
+    """验证码（邮箱/手机统一）"""
+
+    id: str
+    recipient: str  # 邮箱或手机号
+    code: str
+    code_type: str  # email_bind / phone_bind / email_login / phone_login / reset_password
+    expires_at: datetime
+    used_at: datetime | None = None
+    attempts: int = 0
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @classmethod
+    def create(
+        cls,
+        recipient: str,
+        code_type: str,
+        ttl_seconds: int = 300,
+        custom_code: str | None = None,
+    ) -> "VerificationCode":
+        """创建验证码"""
+        import random
+
+        code = custom_code or "".join(random.choices("0123456789", k=6))
+        now = datetime.now(timezone.utc)
+        return cls(
+            id=uuid4().hex,
+            recipient=recipient.strip(),
+            code=code,
+            code_type=code_type,
+            expires_at=now + timedelta(seconds=ttl_seconds),
+            created_at=now,
+        )
+
+    @property
+    def is_expired(self) -> bool:
+        """是否已过期"""
+        return datetime.now(timezone.utc) > self.expires_at
+
+    @property
+    def is_used(self) -> bool:
+        """是否已使用"""
+        return self.used_at is not None
+
+    @property
+    def is_valid(self) -> bool:
+        """是否有效（未过期且未使用）"""
+        return not self.is_expired and not self.is_used
+
+    def mark_used(self) -> None:
+        """标记为已使用"""
+        self.used_at = datetime.now(timezone.utc)
+
+    def increment_attempts(self) -> None:
+        """增加尝试次数"""
+        self.attempts += 1
@@ -0,0 +1,108 @@
+"""视频分享领域实体."""
+
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from hashlib import sha256
+from typing import Optional
+from uuid import uuid4
+
+
+def _hash_password(password: str) -> str:
+    """简单密码哈希（SHA-256 + salt）。
+
+    分享链接的密码保护安全级别要求不高，
+    使用简单的加盐哈希即可，避免引入bcrypt等重依赖。
+    """
+    if not password:
+        return ""
+    salt = "xiaoxia_share_salt"
+    return sha256(f"{salt}:{password}".encode()).hexdigest()
+
+
+def generate_share_token(length: int = 12) -> str:
+    """生成URL友好的分享token."""
+    # 使用urlsafe的base64，但去掉可能引起歧义的字符
+    alphabet = "abcdefghjkmnpqrstuvwxyzABCDEFGHJKMNPQRSTUVWXYZ23456789"
+    return "".join(secrets.choice(alphabet) for _ in range(length))
+
+
+@dataclass(slots=True)
+class VideoShare:
+    """视频分享记录."""
+
+    id: str
+    video_id: str
+    user_id: str
+    share_token: str
+    password_hash: Optional[str] = None
+    expires_at: Optional[datetime] = None
+    view_count: int = 0
+    download_count: int = 0
+    is_active: bool = True
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @classmethod
+    def create(
+        cls,
+        video_id: str,
+        user_id: str,
+        *,
+        password: Optional[str] = None,
+        expires_at: Optional[datetime] = None,
+    ) -> "VideoShare":
+        if not video_id.strip():
+            raise ValueError("video_id cannot be empty")
+        if not user_id.strip():
+            raise ValueError("user_id cannot be empty")
+        if expires_at and expires_at < datetime.now(timezone.utc):
+            raise ValueError("expires_at cannot be in the past")
+
+        return cls(
+            id=uuid4().hex,
+            video_id=video_id.strip(),
+            user_id=user_id.strip(),
+            share_token=generate_share_token(),
+            password_hash=_hash_password(password) if password else None,
+            expires_at=expires_at,
+        )
+
+    @property
+    def has_password(self) -> bool:
+        """是否设置了访问密码."""
+        return bool(self.password_hash)
+
+    @property
+    def is_expired(self) -> bool:
+        """是否已过期."""
+        if not self.expires_at:
+            return False
+        return datetime.now(timezone.utc) > self.expires_at
+
+    @property
+    def is_accessible(self) -> bool:
+        """是否可以访问（活跃且未过期）."""
+        return self.is_active and not self.is_expired
+
+    def verify_password(self, password: str) -> bool:
+        """验证访问密码."""
+        if not self.password_hash:
+            return True  # 没有密码直接通过
+        if not password:
+            return False
+        return _hash_password(password) == self.password_hash
+
+    def increment_view_count(self) -> None:
+        """浏览次数+1."""
+        self.view_count += 1
+
+    def increment_download_count(self) -> None:
+        """下载次数+1."""
+        self.download_count += 1
+
+    def revoke(self) -> None:
+        """撤销分享."""
+        self.is_active = False
@@ -51,6 +51,11 @@ class UserRepository(ABC):
        """根据微信 unionid 查找用户"""
        pass

+    @abstractmethod
+    def find_by_phone(self, phone: str) -> Optional[User]:
+        """根据手机号查找用户"""
+        pass
+
    @abstractmethod
    def delete(self, user_id: str) -> bool:
        """删除用户"""
@@ -0,0 +1,32 @@
+"""
+验证码仓储接口
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from packages.domain.verification_code import VerificationCode
+
+
+class VerificationCodeRepository(ABC):
+    """验证码仓储接口"""
+
+    @abstractmethod
+    def save(self, code: VerificationCode) -> None:
+        """保存验证码"""
+        pass
+
+    @abstractmethod
+    def find_latest(self, recipient: str, code_type: str) -> Optional[VerificationCode]:
+        """查找最新的有效验证码"""
+        pass
+
+    @abstractmethod
+    def find_by_id(self, code_id: str) -> Optional[VerificationCode]:
+        """根据 ID 查找验证码"""
+        pass
+
+    @abstractmethod
+    def count_today(self, recipient: str, code_type: str) -> int:
+        """统计当日发送次数（频控用）"""
+        pass
@@ -0,0 +1,62 @@
+"""视频分享 Repository 端口."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+from packages.domain.video_share import VideoShare
+
+
+class VideoShareRepositoryPort(ABC):
+    """视频分享 Repository 接口."""
+
+    @abstractmethod
+    def create(self, share: VideoShare) -> VideoShare:
+        """创建分享记录."""
+        ...
+
+    @abstractmethod
+    def get_by_token(self, token: str) -> Optional[VideoShare]:
+        """通过分享token获取分享记录."""
+        ...
+
+    @abstractmethod
+    def get_by_id(self, share_id: str, user_id: str) -> Optional[VideoShare]:
+        """通过ID获取分享记录（带用户校验）."""
+        ...
+
+    @abstractmethod
+    def list_by_video(self, video_id: str, user_id: str) -> List[VideoShare]:
+        """列出某个视频的所有分享记录."""
+        ...
+
+    @abstractmethod
+    def list_by_user(self, user_id: str, skip: int = 0, limit: int = 20) -> List[VideoShare]:
+        """列出用户创建的所有分享记录."""
+        ...
+
+    @abstractmethod
+    def count_by_user(self, user_id: str) -> int:
+        """统计用户创建的分享数量."""
+        ...
+
+    @abstractmethod
+    def update(self, share: VideoShare) -> VideoShare:
+        """更新分享记录."""
+        ...
+
+    @abstractmethod
+    def delete(self, share_id: str, user_id: str) -> bool:
+        """删除分享记录（软删除：is_active=False）."""
+        ...
+
+    @abstractmethod
+    def increment_view(self, share_id: str) -> None:
+        """浏览次数+1."""
+        ...
+
+    @abstractmethod
+    def increment_download(self, share_id: str) -> None:
+        """下载次数+1."""
+        ...
@@ -0,0 +1,117 @@
+"""豆包大模型 API 客户端（共享层）.
+
+API 和 Worker 两边共用。基于火山引擎方舟平台的 OpenAI 兼容接口。
+
+使用方式：
+    from packages.shared.ai_client import get_doubao_client
+
+    client = get_doubao_client()
+    if client.is_available:
+        result = client.chat_completion(messages=[...])
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Dict, List, Optional
+
+import httpx
+from packages.shared.config import get_shared_settings
+
+logger = logging.getLogger(__name__)
+
+
+class DoubaoClient:
+    """豆包大模型 API 客户端.
+
+    封装 OpenAI 兼容的 Chat Completion 接口，支持自动重试。
+    未配置 API Key 时 is_available 为 False，调用方应降级处理。
+    """
+
+    def __init__(self) -> None:
+        settings = get_shared_settings()
+        self.api_key: str = settings.doubao_api_key
+        self.model: str = settings.doubao_model
+        self.base_url: str = settings.doubao_base_url.rstrip("/")
+        self.timeout: int = settings.doubao_timeout
+        self.max_retries: int = settings.doubao_max_retries
+
+    @property
+    def is_available(self) -> bool:
+        """是否可用（配置了 API Key）."""
+        return bool(self.api_key)
+
+    def chat_completion(
+        self,
+        messages: List[Dict[str, str]],
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+    ) -> Optional[str]:
+        """调用 Chat Completion 接口.
+
+        Args:
+            messages: 对话消息列表，[{"role": "user"/"system"/"assistant", "content": "..."}]
+            temperature: 采样温度，0-2，默认0.7
+            max_tokens: 最大生成token数，默认1024
+
+        Returns:
+            模型返回的文本内容，失败返回 None
+        """
+        if not self.is_available:
+            return None
+
+        url = f"{self.base_url}/chat/completions"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        payload: Dict[str, Any] = {
+            "model": self.model,
+            "messages": messages,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }
+
+        last_error: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = httpx.post(
+                    url,
+                    headers=headers,
+                    json=payload,
+                    timeout=self.timeout,
+                )
+                response.raise_for_status()
+                data = response.json()
+                content = data["choices"][0]["message"]["content"]
+                return content.strip()
+            except Exception as e:
+                last_error = e
+                if attempt < self.max_retries:
+                    wait = 0.5 * (2**attempt)
+                    logger.warning(
+                        "豆包API调用失败，%.1fs后重试 (第%d/%d次): %s",
+                        wait,
+                        attempt + 1,
+                        self.max_retries + 1,
+                        e,
+                    )
+                    time.sleep(wait)
+
+        logger.error("豆包API调用最终失败: %s", last_error)
+        return None
+
+
+# ── 单例 ─────────────────────────────────────────────────────────────────────
+
+
+_client: Optional[DoubaoClient] = None
+
+
+def get_doubao_client() -> DoubaoClient:
+    """获取豆包客户端单例."""
+    global _client
+    if _client is None:
+        _client = DoubaoClient()
+    return _client
--- a/Show More
+++ b/Show More