Merge pull request 'fix: 确认生成 API 改为复用 worker.generate_video 渲染路径' (#1308) from fix/confirm-generation-api into main

- 新增 ConfirmGenerationRequest schema 和 POST /tasks/{task_id}/confirm 端点
- 确认生成复用 worker.generate_video 完整渲染路径（不再走 edit_plan_generation.py）
- 默认分辨率 1080x1920（竖屏），支持自定义封面和标题
- 新增字段: is_preview, source_task_id, output_width, output_height, cover_url, custom_title
- 贯穿 Schema → Domain → Application → DB Model → Repository → Worker 全链路
- 更新 task_center.py 和 generation_tasks.py 的重试逻辑传递新字段
- Alembic 迁移 034: 为 generation_tasks 表添加 6 个新列
- 7 个单元测试覆盖确认生成的正常/异常流程
- 使用 getattr 带默认值确保向后兼容

.env.example

@@ -42,3 +42,11 @@ OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
 OSS_ACCESS_KEY_ID=your-access-key-id
 OSS_ACCESS_KEY_SECRET=your-access-key-secret
 OSS_BUCKET_NAME=xiaoxia-autocut
+
+# ==================== CosyVoice 语音合成配置 ====================
+COSYVOICE_API_KEY=your-cosyvoice-api-key
+COSYVOICE_BASE_URL=https://dashscope.aliyuncs.com/api/v1/services/aigc/text2audio
+COSYVOICE_MODEL=cosyvoice-v1
+COSYVOICE_VOICE=longxiaochun
+COSYVOICE_SAMPLE_RATE=22050
+COSYVOICE_FORMAT=mp3

.env.production.example

@@ -41,6 +41,14 @@ OSS_BUCKET_NAME=xiaoxia-autocut
 OSS_DIRECT_UPLOAD_MAX_MB=2000
 OSS_DIRECT_UPLOAD_EXPIRE_SECONDS=900
 
+# ==================== CosyVoice 语音合成（必须配置）====================
+COSYVOICE_API_KEY=CHANGE_ME_COSYVOICE_API_KEY
+COSYVOICE_BASE_URL=https://dashscope.aliyuncs.com/api/v1/services/aigc/text2audio
+COSYVOICE_MODEL=cosyvoice-v1
+COSYVOICE_VOICE=longxiaochun
+COSYVOICE_SAMPLE_RATE=22050
+COSYVOICE_FORMAT=mp3
+
 # ==================== 生成文件 ====================
 GENERATED_FILES_DIR=/app/generated
 GENERATED_FILES_URL_PREFIX=/generated-files

.gitea/workflows/acr-cleanup.yml

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

.gitea/workflows/auto-merge.yml

@@ -1,21 +0,0 @@
-name: Auto Merge PRs
-
-on:
-  schedule:
-    - cron: '0 */6 * * *'
-  workflow_dispatch:
-
-jobs:
-  auto-merge:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      
-      - name: Auto merge develop PRs
-        run: |
-          bash scripts/auto_merge_prs.sh develop
-      
-      - name: Auto merge main PRs (release only)
-        run: |
-          bash scripts/auto_merge_prs.sh main

.gitea/workflows/ci-cd.yml

@@ -1,178 +0,0 @@
-name: CI/CD Pipeline
-
-on:
-  push:
-    branches:
-      - main
-      - develop
-      - 'feature/**'
-      - 'bugfix/**'
-      - 'hotfix/**'
-      - 'release/**'
-  pull_request:
-    branches:
-      - main
-      - develop
-
-jobs:
-  validate:
-    name: Validate Code Quality And Tests
-    runs-on: ubuntu-22.04
-
-
-    steps:
-      - name: Checkout code
-        shell: sh
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
-        run: |
-          set -eu
-          python3 - <<'PY'
-          import io, os, tarfile, urllib.request
-          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']}"})
-          with urllib.request.urlopen(request, timeout=120) as response:
-              archive = response.read()
-          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: Verify CI environment
-        shell: sh
-        run: |
-          set -eu
-          python --version
-          python3 -m pip --version
-          python3 -m black --version
-          python3 -m isort --version-number
-          python3 -m flake8 --version
-          bandit --version
-          pytest --version
-          echo "CI environment is ready"
-
-      - name: Run code quality checks
-        shell: sh
-        run: |
-          set -eu
-          python3 -m compileall -q alembic apps packages tests scripts
-          python3 -m black --check alembic apps packages tests scripts
-          python3 -m isort --check-only alembic apps packages tests scripts
-          python3 -m flake8 apps packages tests --count --statistics
-
-      - name: Run security scan
-        shell: sh
-        run: |
-          set -eu
-          bandit -r apps packages -q -ll
-
-      - name: Validate release scripts syntax
-        shell: sh
-        run: |
-          set -eu
-          bash -n scripts/backup_postgres.sh
-          bash -n scripts/restore_postgres_plan.sh
-          bash -n scripts/init_production_env.sh
-
-      - name: Validate Alembic migrations
-        shell: sh
-        run: |
-          set -eu
-          DATABASE_URL=postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas \
-            python3 -m alembic upgrade head --sql > /tmp/alembic-upgrade.sql
-          test -s /tmp/alembic-upgrade.sql
-          grep -q "Running upgrade" /tmp/alembic-upgrade.sql
-          python3 scripts/check_schema_metadata.py
-
-      - name: Run tests
-        shell: sh
-        run: |
-          set -eu
-          PYTHONPATH="$PWD/apps/api:$PWD" python3 -m pytest tests/unit -q
-
-      - name: Build summary
-        if: github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/main'
-        shell: sh
-        run: |
-          set -eu
-          echo "Build completed successfully!"
-          echo "Branch: ${GITHUB_REF_NAME}"
-          echo "Commit: ${GITHUB_SHA}"
-
-  frontend-lint:
-    name: Frontend Lint
-    runs-on: ubuntu-22.04
-
-    steps:
-      - name: Checkout code
-        shell: sh
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
-        run: |
-          set -eu
-          archive_url="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/archive/${GITHUB_SHA}.tar.gz"
-          wget --header="Authorization: token ${GITHUB_TOKEN}" -O /tmp/repo.tar.gz "$archive_url"
-          tar -xzf /tmp/repo.tar.gz --strip-components=1 -C .
-          rm -f /tmp/repo.tar.gz
-
-      - name: Install dependencies
-        shell: sh
-        run: |
-          set -eu
-          docker run --rm \
-            --pull=never \
-            -v "$PWD:/workspace" \
-            -w /workspace/apps/web \
-            docker.m.daocloud.io/library/node:20 \
-            sh -lc 'npm ci'
-
-      - name: Run ESLint
-        shell: sh
-        run: |
-          set -eu
-          docker run --rm \
-            --pull=never \
-            -v "$PWD:/workspace" \
-            -w /workspace/apps/web \
-            docker.m.daocloud.io/library/node:20 \
-            sh -lc 'npx eslint src --ext .ts,.tsx --max-warnings 50'
-
-      - name: Run TypeScript type check
-        shell: sh
-        run: |
-          set -eu
-          docker run --rm \
-            --pull=never \
-            -v "$PWD:/workspace" \
-            -w /workspace/apps/web \
-            docker.m.daocloud.io/library/node:20 \
-            sh -lc 'npx tsc --noEmit'
-
-      - name: Run Prettier check
-        shell: sh
-        run: |
-          set -eu
-          docker run --rm \
-            --pull=never \
-            -v "$PWD:/workspace" \
-            -w /workspace/apps/web \
-            docker.m.daocloud.io/library/node:20 \
-            sh -lc 'npx prettier --check "src/**/*.{ts,tsx,css,md}"'
-
-      - name: Run Vitest tests
-        shell: sh
-        run: |
-          set -eu
-          docker run --rm \
-            --pull=never \
-            -v "$PWD:/workspace" \
-            -w /workspace/apps/web \
-            docker.m.daocloud.io/library/node:20 \
-            sh -lc 'npx vitest run src/test'

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

@@ -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

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

@@ -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: ci-l2
+    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

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

@@ -0,0 +1,52 @@
+name: CI Trigger Monitor
+
+on:
+  schedule:
+    - cron: '*/5 * * * *'  # 每5分钟检查一次
+  workflow_dispatch:
+    inputs:
+      stale_threshold:
+        description: 'CI未触发告警阈值（分钟）'
+        required: false
+        default: '5'
+
+permissions:
+  contents: read
+
+jobs:
+  monitor:
+    name: Monitor CI Trigger Reliability
+    runs-on: ci-l2
+    timeout-minutes: 5
+    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: Check CI trigger status for all open PRs
+        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 }}
+          STALE_THRESHOLD_MIN: ${{ inputs.stale_threshold || 5 }}
+        run: |
+          set +e
+          python3 scripts/ci_trigger_monitor.py
+          # 监控脚本永远不fail，避免告警风暴
+          exit 0
+      - 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
+

.gitea/workflows/code-review.yml

@@ -0,0 +1,79 @@
+name: AI Code Review
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+# 同一个 PR 只跑一个 review，新的取消旧的
+concurrency:
+  group: code-review-${{ gitea.repository }}-${{ gitea.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  code-review:
+    name: AI Code Review
+    runs-on: ci-l2
+    # 跳过草稿 PR
+    if: ${{ !gitea.event.pull_request.draft }}
+
+    steps:
+      # actions/checkout 由 runner 在宿主机层面处理，不受容器网络影响
+      - 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: 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
+
+      - name: Run AI Code Review
+        env:
+          # Gitea 配置（自动从运行环境获取）
+          GITEA_API_URL: ${{ gitea.server_url }}
+          GITEA_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+          REPO_NAME: ${{ gitea.repository }}
+          PR_NUMBER: ${{ gitea.event.pull_request.number }}
+          PR_HEAD_SHA: ${{ gitea.event.pull_request.head.sha }}
+          # LLM 提供商: coze (扣子原生Bot) / openai (OpenAI兼容)
+          LLM_PROVIDER: "coze"
+          # 扣子模式配置（默认国内站 api.coze.cn）
+          LLM_BASE_URL: ${{ secrets.LLM_BASE_URL }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          COZE_BOT_ID: ${{ secrets.COZE_BOT_ID }}
+          LLM_MODEL: ${{ secrets.LLM_MODEL }}
+          # 可选参数
+          MAX_DIFF_CHARS: "30000"
+          LLM_TIMEOUT: "120"
+        run: |
+          python3 scripts/ci_code_review.py
+        # 注意：脚本退出码决定job状态
+        # - 有阻塞级问题 → exit 1 → job失败 → 门禁拦截
+        # - 无阻塞级问题/LLM异常 → exit 0 → 通过（fail-open）
+
+      - 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
+

.gitea/workflows/daily-check.yml

@@ -0,0 +1,624 @@
+name: Daily Health Check
+# 注意：使用 curl step_checkout.sh 方式以兼容 docker runner
+
+on:
+  schedule:
+    - cron: '0 19 * * *'  # UTC 19:00 = 北京时间凌晨 3:00
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # ── 1. 生产环境冒烟测试 ─────────────────────────────────────────────
+  production-smoke:
+    name: Production Smoke Test
+    runs-on: ci-l2
+    timeout-minutes: 8
+    outputs:
+      report: ${{ steps.smoke.outputs.report }}
+
+    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: Production health check & smoke test
+        id: smoke
+        shell: bash
+        env:
+          SMOKE_ENV: production
+          EXISTING_TOKEN: ${{ secrets.PROD_E2E_TOKEN }}
+          MODULES: health,assets,generation,subscription,nginx
+        run: |
+          set +e
+          START_TIME=$(date +%s)
+          chmod +x tests/e2e/api_smoke_test.sh
+          BASE_URL="https://api.xiaoxiajianji.com" \
+          WEB_URL="https://saas.xiaoxiajianji.com" \
+          SMOKE_ENV="${SMOKE_ENV}" \
+          EXISTING_TOKEN="${EXISTING_TOKEN}" \
+          MODULES="${MODULES}" \
+          CLEANUP_ENABLED=0 \
+          PERF_CHECK_ENABLED=1 \
+          PERF_WARN_THRESHOLD_MS=500 \
+          PERF_FAIL_THRESHOLD_MS=5000 \
+          bash tests/e2e/api_smoke_test.sh 2>&1 | tee /tmp/prod-smoke.log
+          SMOKE_EXIT=${PIPESTATUS[0]}
+          END_TIME=$(date +%s)
+          ELAPSED=$((END_TIME - START_TIME))
+
+          echo ""
+          echo "========== 生产冒烟测试报告 =========="
+          echo "环境: https://api.xiaoxiajianji.com"
+          echo "耗时: ${ELAPSED}s"
+          # 提取通过/失败数
+          grep "测试完成:" /tmp/prod-smoke.log || true
+          if [ "$SMOKE_EXIT" -eq 0 ]; then
+            echo "结果: PASS"
+            echo "report=PASS" >> "${GITHUB_OUTPUT}"
+          else
+            echo "结果: FAIL"
+            grep "失败用例:" /tmp/prod-smoke.log || true
+            echo "report=FAIL" >> "${GITHUB_OUTPUT}"
+          fi
+          echo "======================================"
+          exit $SMOKE_EXIT
+
+      - 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
+
+  # ── 2. Staging API 集成测试 ─────────────────────────────────────────
+  staging-api-tests:
+    name: Staging API Integration Tests
+    runs-on: ci-l2
+    timeout-minutes: 10
+    outputs:
+      report: ${{ steps.report.outputs.report }}
+
+    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: Run API smoke test on staging
+        id: smoke
+        shell: bash
+        env:
+          STAGING_TEST_USER: ${{ secrets.STAGING_TEST_USER }}
+          STAGING_TEST_PASSWORD: ${{ secrets.STAGING_TEST_PASSWORD }}
+        run: |
+          set +e
+          START_TIME=$(date +%s)
+          chmod +x tests/e2e/api_smoke_test.sh
+          CONTAINER_NAME="ci-test-$$"
+          docker create --name "$CONTAINER_NAME" \
+            -e BASE_URL=https://staging-api.xiaoxiajianji.com \
+            -e WEB_URL=https://staging.xiaoxiajianji.com \
+            -e TEST_USER="$STAGING_TEST_USER" \
+            -e TEST_PASSWORD="$STAGING_TEST_PASSWORD" \
+            -e CLEANUP_ENABLED=1 \
+            -e PERF_CHECK_ENABLED=1 \
+            -e PERF_WARN_THRESHOLD_MS=500 \
+            -e PERF_FAIL_THRESHOLD_MS=3000 \
+            -w /workspace \
+            git.xiaoxiajianji.com/xiaoxia/base/playwright:v1.45.0-jammy \
+            bash tests/e2e/api_smoke_test.sh 2>&1
+          docker cp . "$CONTAINER_NAME:/workspace"
+          docker start -a "$CONTAINER_NAME" 2>&1 | tee /tmp/staging-api-smoke.log
+          SMOKE_EXIT=${PIPESTATUS[0]}
+          docker rm "$CONTAINER_NAME" > /dev/null 2>&1 || true
+          END_TIME=$(date +%s)
+          ELAPSED=$((END_TIME - START_TIME))
+
+          echo ""
+          echo "========== Staging API 冒烟测试报告 =========="
+          echo "环境: https://staging-api.xiaoxiajianji.com"
+          echo "耗时: ${ELAPSED}s"
+          grep "测试完成:" /tmp/staging-api-smoke.log || true
+          if [ "$SMOKE_EXIT" -eq 0 ]; then
+            echo "结果: PASS"
+            echo "api_report=PASS" >> "${GITHUB_OUTPUT}"
+          else
+            echo "结果: FAIL"
+            grep "失败用例:" /tmp/staging-api-smoke.log || true
+            echo "api_report=FAIL" >> "${GITHUB_OUTPUT}"
+          fi
+          echo "=============================================="
+          exit $SMOKE_EXIT
+
+      - name: Run Staging API Integration Tests (Playwright)
+        id: e2e_api
+        shell: bash
+        run: |
+          set +e
+          START_TIME=$(date +%s)
+          CONTAINER_NAME="ci-test-$$"
+          docker create --name "$CONTAINER_NAME" \
+            -e E2E_BASE_URL=https://staging.xiaoxiajianji.com \
+            -e E2E_API_BASE=https://staging-api.xiaoxiajianji.com/api/v1 \
+            -w /workspace/apps/web \
+            git.xiaoxiajianji.com/xiaoxia/base/playwright:v1.45.0-jammy \
+            sh -lc "npm ci && npx playwright test --reporter=line e2e/test_auth.spec.ts e2e/test_asset.spec.ts e2e/test_project.spec.ts" 2>&1
+          docker cp . "$CONTAINER_NAME:/workspace"
+          docker start -a "$CONTAINER_NAME" 2>&1 | tee /tmp/staging-api-e2e.log
+          EXIT_CODE=${PIPESTATUS[0]}
+          docker rm "$CONTAINER_NAME" > /dev/null 2>&1 || true
+          END_TIME=$(date +%s)
+          ELAPSED=$((END_TIME - START_TIME))
+
+          echo ""
+          echo "========== Staging API 集成测试报告 =========="
+          echo "环境: https://staging-api.xiaoxiajianji.com"
+          echo "耗时: ${ELAPSED}s"
+          grep -E "passed|failed|timed out" /tmp/staging-api-e2e.log || true
+          if [ "$EXIT_CODE" -eq 0 ]; then
+            echo "结果: PASS"
+            echo "int_report=PASS" >> "${GITHUB_OUTPUT}"
+          else
+            echo "结果: FAIL"
+            echo "int_report=FAIL" >> "${GITHUB_OUTPUT}"
+          fi
+          echo "=============================================="
+          exit $EXIT_CODE
+
+      - name: Set report output
+        id: report
+        shell: sh
+        run: |
+          if [ "${{ steps.smoke.outputs.api_report }}" = "PASS" ] && [ "${{ steps.e2e_api.outputs.int_report }}" = "PASS" ]; then
+            echo "report=PASS" >> "${GITHUB_OUTPUT}"
+          else
+            echo "report=FAIL" >> "${GITHUB_OUTPUT}"
+          fi
+
+      - 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
+
+  # ── 3. Staging 浏览器 E2E ──────────────────────────────────────────
+  staging-e2e:
+    name: Staging Browser E2E
+    runs-on: ci-l2
+    timeout-minutes: 15
+    outputs:
+      report: ${{ steps.e2e.outputs.report }}
+
+    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: Run Playwright E2E on staging
+        id: e2e
+        shell: bash
+        run: |
+          set +e
+          START_TIME=$(date +%s)
+          CONTAINER_NAME="ci-test-$$"
+          docker create --name "$CONTAINER_NAME" --ipc=host \
+            -e E2E_BASE_URL=https://staging.xiaoxiajianji.com \
+            -e E2E_API_BASE=https://staging-api.xiaoxiajianji.com/api/v1 \
+            -e E2E_BROWSER_CHANNEL=chromium \
+            -e PLAYWRIGHT_HEADLESS=1 \
+            -w /workspace/apps/web \
+            git.xiaoxiajianji.com/xiaoxia/base/playwright:v1.45.0-jammy \
+            sh -lc 'npm ci && npx playwright test --reporter=line --project=chromium e2e/auth.spec.ts e2e/auth-guard.spec.ts e2e/core-upload.spec.ts e2e/core-generation.spec.ts e2e/core-titles.spec.ts' 2>&1
+          docker cp . "$CONTAINER_NAME:/workspace"
+          docker start -a "$CONTAINER_NAME" 2>&1 | tee /tmp/staging-e2e.log
+          EXIT_CODE=${PIPESTATUS[0]}
+          docker rm "$CONTAINER_NAME" > /dev/null 2>&1 || true
+          END_TIME=$(date +%s)
+          ELAPSED=$((END_TIME - START_TIME))
+
+          echo ""
+          echo "========== Staging E2E 测试报告 =========="
+          echo "环境: https://staging.xiaoxiajianji.com"
+          echo "耗时: ${ELAPSED}s"
+          grep -E "passed|failed|timed out" /tmp/staging-e2e.log || true
+          if [ "$EXIT_CODE" -eq 0 ]; then
+            echo "结果: PASS"
+            echo "report=PASS" >> "${GITHUB_OUTPUT}"
+          else
+            echo "结果: FAIL"
+            echo "report=FAIL" >> "${GITHUB_OUTPUT}"
+          fi
+          echo "=========================================="
+          exit $EXIT_CODE
+
+      - 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
+
+  # ── 4. 性能基线巡检 ────────────────────────────────────────────────
+  performance-check:
+    name: Performance Baseline Check
+    runs-on: ci-l2
+    timeout-minutes: 8
+    outputs:
+      report: ${{ steps.report.outputs.report }}
+
+    steps:
+      - name: Run performance baseline checks
+        id: perf
+        shell: sh
+        env:
+          STAGING_TEST_USER: ${{ secrets.STAGING_TEST_USER }}
+          STAGING_TEST_PASSWORD: ${{ secrets.STAGING_TEST_PASSWORD }}
+        run: |
+          set +e
+          START_TIME=$(date +%s)
+          echo "=========================================="
+          echo "  性能基线巡检 - Staging API"
+          echo "  目标: https://staging-api.xiaoxiajianji.com"
+          echo "=========================================="
+          echo ""
+
+          TOTAL=0
+          PASS=0
+          FAIL=0
+          WARN=0
+          WARN_LIST=""
+          FAIL_LIST=""
+
+          # 核心接口配置: 名称|路径|方法|阈值(ms)|失败阈值(ms)
+          # 核心接口(core): 500ms
+          # 普通接口(normal): 1000ms
+          # 重操作接口(heavy): 3000ms
+          ENDPOINTS="
+          登录|/api/v1/auth/login|POST|500|3000
+          获取当前用户|/api/v1/auth/me|GET|500|3000
+          项目列表|/api/v1/projects|GET|500|3000
+          素材列表|/api/v1/assets|GET|500|3000
+          模板列表|/api/v1/templates|GET|500|3000
+          剪辑计划列表|/api/v1/edit-plans|GET|500|3000
+          生成任务列表|/api/v1/generation/tasks|GET|500|3000
+          订阅信息|/api/v1/subscription/current|GET|500|3000
+          音色列表|/api/v1/voices|GET|1000|5000
+          健康检查|/health|GET|200|1000
+          "
+
+          # 先登录获取 token
+          echo "--- 准备: 获取测试 Token ---"
+          LOGIN_BODY="{\"email\":\"$STAGING_TEST_USER\",\"password\":\"$STAGING_TEST_PASSWORD\"}"
+          AUTH_RESP=$(curl -s -w "\n%{http_code}" -X POST \
+            -H "Content-Type: application/json" \
+            -d "$LOGIN_BODY" \
+            "https://staging-api.xiaoxiajianji.com/api/v1/auth/login" \
+            --max-time 10 2>&1)
+          AUTH_CODE=$(echo "$AUTH_RESP" | tail -1)
+          AUTH_BODY=$(echo "$AUTH_RESP" | sed '$d')
+
+          if [ "$AUTH_CODE" = "200" ]; then
+            TOKEN=$(echo "$AUTH_BODY" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('access_token',''))" 2>/dev/null)
+            if [ -n "$TOKEN" ]; then
+              echo "Token 获取成功"
+            else
+              echo "Token 解析失败，部分接口可能无法测试"
+              TOKEN=""
+            fi
+          else
+            echo "登录失败 (HTTP $AUTH_CODE)，部分接口将跳过鉴权测试"
+            TOKEN=""
+          fi
+
+          echo ""
+          echo "--- 开始性能测试 ---"
+          echo ""
+
+          echo "$ENDPOINTS" | while IFS='|' read -r name path method warn_ms fail_ms; do
+            [ -z "$name" ] && continue
+            TOTAL=$((TOTAL + 1))
+
+            # 构建 curl 命令
+            CURL_ARGS="-s -o /dev/null -w '%{http_code} %{time_total}' --max-time 30"
+            if [ "$method" = "POST" ]; then
+              CURL_ARGS="$CURL_ARGS -X POST -H 'Content-Type: application/json' -d \"$LOGIN_BODY\""
+            fi
+            if [ -n "$TOKEN" ] && [ "$name" != "健康检查" ]; then
+              CURL_ARGS="$CURL_ARGS -H 'Authorization: Bearer $TOKEN'"
+            fi
+
+            # 执行请求
+            RESP=$(eval curl $CURL_ARGS "https://staging-api.xiaoxiajianji.com${path}" 2>&1)
+            HTTP_CODE=$(echo "$RESP" | awk '{print $1}')
+            TIME_TOTAL=$(echo "$RESP" | awk '{print $2}')
+            ELAPSED_MS=$(python3 -c "print(int(float('${TIME_TOTAL:-0}') * 1000))" 2>/dev/null || echo "0")
+
+            if [ "$HTTP_CODE" -ge 500 ] 2>/dev/null; then
+              FAIL=$((FAIL + 1))
+              FAIL_LIST="$FAIL_LIST\n  ❌ $name - HTTP $HTTP_CODE (${ELAPSED_MS}ms)"
+              echo "❌ $name - HTTP $HTTP_CODE - ${ELAPSED_MS}ms (FAIL)"
+            elif [ "$ELAPSED_MS" -ge "$fail_ms" ] 2>/dev/null; then
+              FAIL=$((FAIL + 1))
+              FAIL_LIST="$FAIL_LIST\n  ❌ $name - ${ELAPSED_MS}ms > ${fail_ms}ms"
+              echo "❌ $name - ${ELAPSED_MS}ms > ${fail_ms}ms (FAIL)"
+            elif [ "$ELAPSED_MS" -ge "$warn_ms" ] 2>/dev/null; then
+              WARN=$((WARN + 1))
+              WARN_LIST="$WARN_LIST\n  ⚠️  $name - ${ELAPSED_MS}ms > ${warn_ms}ms"
+              echo "⚠️  $name - ${ELAPSED_MS}ms (WARN, threshold: ${warn_ms}ms)"
+              PASS=$((PASS + 1))
+            else
+              PASS=$((PASS + 1))
+              echo "✅ $name - ${ELAPSED_MS}ms (OK, threshold: ${warn_ms}ms)"
+            fi
+          done
+
+          # 由于 while 在子 shell 中执行，用文件传递结果
+          # 重新跑一次用文件计数方式
+          echo ""
+          echo "--- 汇总性能数据 ---"
+
+          END_TIME=$(date +%s)
+          ELAPSED=$((END_TIME - START_TIME))
+
+          echo ""
+          echo "========== 性能基线巡检报告 =========="
+          echo "环境: https://staging-api.xiaoxiajianji.com"
+          echo "耗时: ${ELAPSED}s"
+          echo "======================================"
+
+      - name: Generate performance report
+        id: report
+        shell: sh
+        env:
+          STAGING_TEST_USER: ${{ secrets.STAGING_TEST_USER }}
+          STAGING_TEST_PASSWORD: ${{ secrets.STAGING_TEST_PASSWORD }}
+        run: |
+          set +e
+          echo ""
+          echo "=========================================="
+          echo "  性能基线巡检 - 详细报告"
+          echo "=========================================="
+
+          TOTAL=0
+          PASS=0
+          FAIL=0
+          WARN=0
+          RESULTS=""
+          START_TIME=$(date +%s)
+
+          LOGIN_BODY="{\"email\":\"$STAGING_TEST_USER\",\"password\":\"$STAGING_TEST_PASSWORD\"}"
+          # 先登录获取 token
+          AUTH_RESP=$(curl -s -w "\n%{http_code}" -X POST \
+            -H "Content-Type: application/json" \
+            -d "$LOGIN_BODY" \
+            "https://staging-api.xiaoxiajianji.com/api/v1/auth/login" \
+            --max-time 10 2>&1)
+          AUTH_CODE=$(echo "$AUTH_RESP" | tail -1)
+          AUTH_BODY=$(echo "$AUTH_RESP" | sed '$d')
+          TOKEN=""
+          if [ "$AUTH_CODE" = "200" ]; then
+            TOKEN=$(echo "$AUTH_BODY" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('access_token',''))" 2>/dev/null || echo "")
+          fi
+
+          run_perf_test() {
+            local name="$1" path="$2" method="$3" warn_ms="$4" fail_ms="$5"
+            TOTAL=$((TOTAL + 1))
+
+            local CURL_ARGS="-s -o /dev/null -w '%{http_code} %{time_total}' --max-time 30"
+            if [ "$method" = "POST" ]; then
+              CURL_ARGS="$CURL_ARGS -X POST -H 'Content-Type: application/json' -d \"$LOGIN_BODY\""
+            fi
+            if [ -n "$TOKEN" ] && [ "$name" != "健康检查" ]; then
+              CURL_ARGS="$CURL_ARGS -H 'Authorization: Bearer $TOKEN'"
+            fi
+
+            local RESP=$(eval curl $CURL_ARGS "https://staging-api.xiaoxiajianji.com${path}" 2>&1)
+            local HTTP_CODE=$(echo "$RESP" | awk '{print $1}')
+            local TIME_TOTAL=$(echo "$RESP" | awk '{print $2}')
+            local ELAPSED_MS=$(python3 -c "print(int(float('${TIME_TOTAL:-0}') * 1000))" 2>/dev/null || echo "0")
+
+            if echo "$HTTP_CODE" | grep -q "^[5]"; then
+              FAIL=$((FAIL + 1))
+              RESULTS="$RESULTS\n  ❌ $name - HTTP $HTTP_CODE (${ELAPSED_MS}ms)"
+              echo "❌ $name - HTTP $HTTP_CODE - ${ELAPSED_MS}ms [FAIL]"
+              return 1
+            elif [ "$ELAPSED_MS" -ge "$fail_ms" ] 2>/dev/null; then
+              FAIL=$((FAIL + 1))
+              RESULTS="$RESULTS\n  ❌ $name - ${ELAPSED_MS}ms > ${fail_ms}ms [FAIL]"
+              echo "❌ $name - ${ELAPSED_MS}ms > ${fail_ms}ms [FAIL]"
+              return 1
+            elif [ "$ELAPSED_MS" -ge "$warn_ms" ] 2>/dev/null; then
+              WARN=$((WARN + 1))
+              PASS=$((PASS + 1))
+              RESULTS="$RESULTS\n  ⚠️  $name - ${ELAPSED_MS}ms (阈值: ${warn_ms}ms) [WARN]"
+              echo "⚠️  $name - ${ELAPSED_MS}ms > 阈值 ${warn_ms}ms [WARN]"
+              return 0
+            else
+              PASS=$((PASS + 1))
+              RESULTS="$RESULTS\n  ✅ $name - ${ELAPSED_MS}ms (阈值: ${warn_ms}ms) [OK]"
+              echo "✅ $name - ${ELAPSED_MS}ms (阈值: ${warn_ms}ms) [OK]"
+              return 0
+            fi
+          }
+
+          echo ""
+          echo "=== 核心接口 (阈值: 500ms / 3000ms) ==="
+          run_perf_test "登录" "/api/v1/auth/login" "POST" 500 3000 || true
+          run_perf_test "获取当前用户" "/api/v1/auth/me" "GET" 500 3000 || true
+          run_perf_test "项目列表" "/api/v1/projects" "GET" 500 3000 || true
+          run_perf_test "素材列表" "/api/v1/assets" "GET" 500 3000 || true
+          run_perf_test "模板列表" "/api/v1/templates" "GET" 500 3000 || true
+          run_perf_test "剪辑计划列表" "/api/v1/edit-plans" "GET" 500 3000 || true
+          run_perf_test "生成任务列表" "/api/v1/generation/tasks" "GET" 500 3000 || true
+          run_perf_test "订阅信息" "/api/v1/subscription/current" "GET" 500 3000 || true
+
+          echo ""
+          echo "=== 普通接口 (阈值: 1000ms / 5000ms) ==="
+          run_perf_test "音色列表" "/api/v1/voices" "GET" 1000 5000 || true
+
+          echo ""
+          echo "=== 基础接口 (阈值: 200ms / 1000ms) ==="
+          run_perf_test "健康检查" "/health" "GET" 200 1000 || true
+
+          END_TIME=$(date +%s)
+          ELAPSED=$((END_TIME - START_TIME))
+
+          echo ""
+          echo "========== 性能基线巡检报告 =========="
+          echo "环境: https://staging-api.xiaoxiajianji.com"
+          echo "总接口: ${TOTAL}"
+          echo "通过: ${PASS}"
+          echo "失败: ${FAIL}"
+          echo "警告: ${WARN}"
+          echo "耗时: ${ELAPSED}s"
+          echo "======================================"
+
+          # 写入结果文件供 report job 使用
+          echo "${TOTAL}" > /tmp/perf_total
+          echo "${PASS}" > /tmp/perf_pass
+          echo "${FAIL}" > /tmp/perf_fail
+          echo "${WARN}" > /tmp/perf_warn
+          echo "${ELAPSED}" > /tmp/perf_elapsed
+
+          if [ "$FAIL" -gt 0 ]; then
+            echo "report=FAIL" >> "${GITHUB_OUTPUT}"
+            echo "perf_detail=fail:${FAIL}:warn:${WARN}" >> "${GITHUB_OUTPUT}"
+            exit 1
+          else
+            echo "report=PASS" >> "${GITHUB_OUTPUT}"
+            if [ "$WARN" -gt 0 ]; then
+              echo "perf_detail=pass:warn:${WARN}" >> "${GITHUB_OUTPUT}"
+            else
+              echo "perf_detail=pass" >> "${GITHUB_OUTPUT}"
+            fi
+            exit 0
+          fi
+
+      - 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
+
+  # ── 5. 每日巡检汇总报告 ────────────────────────────────────────────
+  daily-report:
+    name: Daily Check Report
+    runs-on: ci-l2
+    timeout-minutes: 2
+    if: always()
+    needs:
+      - production-smoke
+      - staging-api-tests
+      - staging-e2e
+      - performance-check
+
+    steps:
+      - name: Print summary report
+        shell: sh
+        run: |
+          echo ""
+          echo "╔══════════════════════════════════════════════════════╗"
+          echo "║              每日巡检报告                             ║"
+          echo "╠══════════════════════════════════════════════════════╣"
+
+          # 获取各 job 状态
+          PROD_STATUS="${{ needs.production-smoke.result }}"
+          STAGING_API_STATUS="${{ needs.staging-api-tests.result }}"
+          STAGING_E2E_STATUS="${{ needs.staging-e2e.result }}"
+          PERF_STATUS="${{ needs.performance-check.result }}"
+
+          format_result() {
+            if [ "$1" = "success" ]; then
+              echo "✅ PASS"
+            elif [ "$1" = "failure" ]; then
+              echo "❌ FAIL"
+            elif [ "$1" = "skipped" ]; then
+              echo "⏭️  SKIP"
+            else
+              echo "❓ UNKNOWN ($1)"
+            fi
+          }
+
+          echo "║"
+          echo "║  生产冒烟测试:   $(format_result "$PROD_STATUS")"
+          echo "║  Staging API:    $(format_result "$STAGING_API_STATUS")"
+          echo "║  Staging E2E:    $(format_result "$STAGING_E2E_STATUS")"
+          echo "║  性能基线巡检:   $(format_result "$PERF_STATUS")"
+          echo "║"
+          echo "║  巡检时间: $(date '+%Y-%m-%d %H:%M:%S UTC')"
+          echo "║"
+
+          # 判断整体状态
+          ALL_PASS=true
+          FAILED_ITEMS=""
+          for status_name in "$PROD_STATUS:生产冒烟" "$STAGING_API_STATUS:Staging API" "$STAGING_E2E_STATUS:Staging E2E" "$PERF_STATUS:性能基线"; do
+            STATUS=$(echo "$status_name" | cut -d: -f1)
+            NAME=$(echo "$status_name" | cut -d: -f2)
+            if [ "$STATUS" != "success" ] && [ "$STATUS" != "skipped" ]; then
+              ALL_PASS=false
+              FAILED_ITEMS="$FAILED_ITEMS $NAME"
+            fi
+          done
+
+          echo "╠══════════════════════════════════════════════════════╣"
+          if [ "$ALL_PASS" = "true" ]; then
+            echo "║  整体状态: ✅ 全部通过                                 ║"
+          else
+            echo "║  整体状态: ❌ 存在失败                                 ║"
+            echo "║  失败项: ${FAILED_ITEMS}                              ║"
+          fi
+          echo "╚══════════════════════════════════════════════════════╝"
+          echo ""
+
+          # 如果有失败项，以非零退出码结束（方便 Gitea 标记流水线失败）
+          if [ "$ALL_PASS" = "false" ]; then
+            echo "⚠️  部分巡检项失败，请检查上方日志获取详细信息。"
+            # 不 exit 1，因为我们用了 always()，保持 report job 成功，
+            # 但其他失败的 job 已经让整体流水线标记为失败
+          fi
+      - 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

.gitea/workflows/deploy.yml

@@ -1,333 +0,0 @@
-name: Deploy
-
-on:
-  push:
-    branches: [ main, develop, "feature/**" ]
-    tags:
-      - 'v*'
-
-jobs:
-  deploy-staging:
-    name: Deploy Staging
-    runs-on: ubuntu-22.04
-    if: github.ref_name == 'main' || github.ref_name == 'develop' || startsWith(github.ref_name, 'feature/')
-
-    steps:
-    - name: Checkout code
-      shell: sh
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: |
-        set -eu
-        python3 - <<'PY'
-        import io, os, tarfile, urllib.request
-        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']}"})
-        with urllib.request.urlopen(request, timeout=120) as response:
-            archive = response.read()
-        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: Install SSH client
-      shell: sh
-      run: |
-        set -eu
-        apt-get update -qq && apt-get install -y -qq openssh-client >/dev/null 2>&1
-        echo "openssh-client installed"
-
-    - name: Build staging web artifact
-      shell: sh
-      run: |
-        set -eu
-        docker run --rm \
-          --pull=never \
-          -v "$PWD:/workspace" \
-          -w /workspace/apps/web \
-          docker.m.daocloud.io/library/node:20 \
-          sh -lc 'npm ci && npm run build'
-        docker build --pull=false \
-          -f infra/docker/web-artifact.Dockerfile \
-          -t "xiaoxia-saas-web:staging-${GITHUB_SHA}" \
-          .
-        test -f apps/web/dist/index.html
-
-
-    - name: Build and push staging API/Worker images
-      shell: sh
-      run: |
-        set -eu
-        REGISTRY="172.30.18.198:5000"
-        docker build --pull=false \
-          -f infra/docker/api.Dockerfile \
-          -t "${REGISTRY}/xiaoxia-saas-api:dev" \
-          .
-        docker build --pull=false \
-          -f infra/docker/worker.Dockerfile \
-          -t "${REGISTRY}/xiaoxia-saas-worker:dev" \
-          .
-        docker push "${REGISTRY}/xiaoxia-saas-api:dev"
-        docker push "${REGISTRY}/xiaoxia-saas-worker:dev"
-
-    - name: Package staging release artifact
-      shell: sh
-      run: |
-        set -eu
-        rm -rf dist/staging-artifacts
-        mkdir -p dist/staging-artifacts
-        tar --exclude=.git --exclude=apps/web/node_modules --exclude=./dist \
-          -czf dist/staging-artifacts/xiaoxia-staging-${GITHUB_SHA}.tar.gz .
-        docker save -o "dist/staging-artifacts/xiaoxia-web-staging-${GITHUB_SHA}.tar" "xiaoxia-saas-web:staging-${GITHUB_SHA}"
-
-    - name: Upload staging artifact to business host
-      shell: sh
-      env:
-        STAGING_SSH_HOST: ${{ secrets.STAGING_SSH_HOST }}
-        STAGING_SSH_USER: ${{ secrets.STAGING_SSH_USER }}
-        STAGING_SSH_KEY: ${{ secrets.STAGING_SSH_KEY }}
-      run: |
-        set -eu
-        staging_host="${STAGING_SSH_HOST:-47.98.113.167}"
-        staging_user="${STAGING_SSH_USER:-root}"
-        mkdir -p ~/.ssh
-        # Prefer host key if available (more reliable), fallback to secrets
-        if [ -f /root/.ssh/xiaoxia_runtime_builder ]; then
-          key_path="/root/.ssh/xiaoxia_runtime_builder"
-          echo "Using host SSH key: $key_path"
-        elif [ -n "${STAGING_SSH_KEY:-}" ]; then
-          key_path="$HOME/.ssh/id_ed25519"
-          printf '%s\n' "$STAGING_SSH_KEY" > "$key_path"
-          chmod 600 "$key_path"
-          echo "Using secret SSH key: $key_path"
-        else
-          echo "ERROR: No SSH key available"
-          exit 1
-        fi
-        ssh-keyscan -H "$staging_host" >> ~/.ssh/known_hosts
-        ssh -i "$key_path" "$staging_user@$staging_host" "mkdir -p /var/lib/xiaoxia-saas-staging/artifacts"
-        scp -i "$key_path" "dist/staging-artifacts/xiaoxia-staging-${GITHUB_SHA}.tar.gz" \
-          "$staging_user@$staging_host:/var/lib/xiaoxia-saas-staging/artifacts/xiaoxia-staging-${GITHUB_SHA}.tar.gz"
-        scp -i "$key_path" "dist/staging-artifacts/xiaoxia-web-staging-${GITHUB_SHA}.tar" \
-          "$staging_user@$staging_host:/var/lib/xiaoxia-saas-staging/artifacts/xiaoxia-web-staging-${GITHUB_SHA}.tar"
-
-    - name: Deploy staging stack on business host
-      shell: sh
-      env:
-        STAGING_SSH_HOST: ${{ secrets.STAGING_SSH_HOST }}
-        STAGING_SSH_USER: ${{ secrets.STAGING_SSH_USER }}
-        STAGING_SSH_KEY: ${{ secrets.STAGING_SSH_KEY }}
-      run: |
-        set -eu
-        staging_host="${STAGING_SSH_HOST:-47.98.113.167}"
-        staging_user="${STAGING_SSH_USER:-root}"
-        if [ -f /root/.ssh/xiaoxia_runtime_builder ]; then
-          key_path="/root/.ssh/xiaoxia_runtime_builder"
-        elif [ -n "${STAGING_SSH_KEY:-}" ]; then
-          key_path="$HOME/.ssh/id_ed25519"
-        else
-          echo "ERROR: No SSH key available"
-          exit 1
-        fi
-        echo 'c2V0IC1ldQphcnRpZmFjdD0iL3Zhci9saWIveGlhb3hpYS1zYWFzLXN0YWdpbmcvYXJ0aWZhY3RzL3hpYW94aWEtc3RhZ2luZy0ke0dJVEhVQl9TSEF9LnRhci5neiIKaW1hZ2VfdGFyPSIvdmFyL2xpYi94aWFveGlhLXNhYXMtc3RhZ2luZy9hcnRpZmFjdHMveGlhb3hpYS13ZWItc3RhZ2luZy0ke0dJVEhVQl9TSEF9LnRhciIKdGVzdCAtZiAiJGFydGlmYWN0Igp0ZXN0IC1mICIkaW1hZ2VfdGFyIgp0ZXN0IC1mIC92YXIvbGliL3hpYW94aWEtc2Fhcy1zdGFnaW5nLy5lbnYKZG9ja2VyIGxvYWQgLWkgIiRpbWFnZV90YXIiCnJtIC1yZiAvdmFyL2xpYi94aWFveGlhLXNhYXMtc3RhZ2luZy9yZXBvCm1rZGlyIC1wIC92YXIvbGliL3hpYW94aWEtc2Fhcy1zdGFnaW5nL3JlcG8KdGFyIC14emYgIiRhcnRpZmFjdCIgLUMgL3Zhci9saWIveGlhb3hpYS1zYWFzLXN0YWdpbmcvcmVwbwp0ZXN0IC1mIC92YXIvbGliL3hpYW94aWEtc2Fhcy1zdGFnaW5nL3JlcG8vYXBwcy93ZWIvZGlzdC9pbmRleC5odG1sCmNwIC92YXIvbGliL3hpYW94aWEtc2Fhcy1zdGFnaW5nLy5lbnYgL3Zhci9saWIveGlhb3hpYS1zYWFzLXN0YWdpbmcvcmVwby8uZW52CmNobW9kICt4IC92YXIvbGliL3hpYW94aWEtc2Fhcy1zdGFnaW5nL3JlcG8vaW5mcmEvZG9ja2VyL2RlcGxveS1zdGFnaW5nLnNoClJFR0lTVFJZPSIxNzIuMzAuMTguMTk4OjUwMDAiIEFQSV9JTUFHRT0iJHtSRUdJU1RSWX0veGlhb3hpYS1zYWFzLWFwaTpkZXYiIFdPUktFUl9JTUFHRT0iJHtSRUdJU1RSWX0veGlhb3hpYS1zYWFzLXdvcmtlcjpkZXYiIFdFQl9JTUFHRT0ieGlhb3hpYS1zYWFzLXdlYjpzdGFnaW5nLSR7R0lUSFVCX1NIQX0iIEhPU1RfUFJFRklYPSBXRUJfUE9SVD0zMDAxIFJFQlVJTERfQkFDS0VORD0wIEJVSUxEX1dFQj0wIFJVTl9NSUdSQVRJT05TPTAgL3Zhci9saWIveGlhb3hpYS1zYWFzLXN0YWdpbmcvcmVwby9pbmZyYS9kb2NrZXIvZGVwbG95LXN0YWdpbmcuc2gKaT0wCndoaWxlIFsgIiRpIiAtbHQgMzAgXTsgZG8KICBpZiB3Z2V0IC1xTy0gaHR0cDovLzEyNy4wLjAuMTo4MDAwL2hlYWx0aDsgdGhlbgogICAgZXhpdCAwCiAgZmkKICBpPSQoKGkgKyAxKSkKICBzbGVlcCAyCmRvbmUKZXhpdCAxCg==' | base64 -d | ssh -i "$key_path" "$staging_user@$staging_host" "GITHUB_SHA='${GITHUB_SHA}' sh"
-
-  build-production-runtime-images:
-    name: Build Production Runtime Images
-    runs-on: ubuntu-22.04
-    if: startsWith(github.ref, 'refs/tags/v')
-
-    steps:
-    - name: Checkout code
-      shell: sh
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: |
-        set -eu
-        python3 - <<'PY'
-        import io, os, tarfile, urllib.request
-        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']}"})
-        with urllib.request.urlopen(request, timeout=120) as response:
-            archive = response.read()
-        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: Build runtime image artifact
-      shell: sh
-      run: |
-        set -eu
-        chmod +x scripts/build_release_images.sh
-        scripts/build_release_images.sh "${GITHUB_REF_NAME}"
-
-    - name: Build production web artifact
-      shell: sh
-      run: |
-        set -eu
-        docker run --rm \
-          --pull=never \
-          -v "$PWD:/workspace" \
-          -w /workspace/apps/web \
-          docker.m.daocloud.io/library/node:20 \
-          sh -lc 'npm ci && npm run build'
-        docker build --pull=false \
-          -f infra/docker/web-artifact.Dockerfile \
-          -t "xiaoxia-saas-web:${GITHUB_REF_NAME}" \
-          .
-        test -f apps/web/dist/index.html
-
-    - name: Package release source artifact
-      shell: sh
-      run: |
-        set -eu
-        mkdir -p dist/release-artifacts
-        tar --exclude=.git --exclude=apps/web/node_modules --exclude=./dist \
-          -czf "dist/release-artifacts/xiaoxia-release-${GITHUB_REF_NAME}.tar.gz" .
-        docker save -o "dist/release-artifacts/xiaoxia-web-${GITHUB_REF_NAME}.tar" "xiaoxia-saas-web:${GITHUB_REF_NAME}"
-
-    - name: Upload runtime image and release artifacts
-      shell: sh
-      env:
-        PRODUCTION_SSH_HOST: ${{ secrets.PRODUCTION_SSH_HOST }}
-        PRODUCTION_SSH_USER: ${{ secrets.PRODUCTION_SSH_USER }}
-        PRODUCTION_SSH_KEY: ${{ secrets.PRODUCTION_SSH_KEY }}
-      run: |
-        set -eu
-        production_host="${PRODUCTION_SSH_HOST:-47.98.113.167}"
-        production_user="${PRODUCTION_SSH_USER:-root}"
-        mkdir -p ~/.ssh
-        # Prefer host key if available (more reliable), fallback to secrets
-        if [ -f /root/.ssh/xiaoxia_runtime_builder ]; then
-          key_path="/root/.ssh/xiaoxia_runtime_builder"
-          echo "Using host SSH key: $key_path"
-        elif [ -n "${PRODUCTION_SSH_KEY:-}" ]; then
-          key_path="$HOME/.ssh/id_ed25519"
-          printf '%s\n' "$PRODUCTION_SSH_KEY" > "$key_path"
-          chmod 600 "$key_path"
-          echo "Using secret SSH key: $key_path"
-        else
-          echo "ERROR: No SSH key available"
-          exit 1
-        fi
-        ssh-keyscan -H "$production_host" >> ~/.ssh/known_hosts
-        scp -i "$key_path" "dist/release-images/xiaoxia-runtime-images-${GITHUB_REF_NAME}.tar" \
-          "$production_user@$production_host:/var/lib/xiaoxia-saas-production/runtime-images-${GITHUB_REF_NAME}.tar"
-        scp -i "$key_path" "dist/release-artifacts/xiaoxia-release-${GITHUB_REF_NAME}.tar.gz" \
-          "$production_user@$production_host:/var/lib/xiaoxia-saas-production/release-${GITHUB_REF_NAME}.tar.gz"
-        scp -i "$key_path" "dist/release-artifacts/xiaoxia-web-${GITHUB_REF_NAME}.tar" \
-          "$production_user@$production_host:/var/lib/xiaoxia-saas-production/web-${GITHUB_REF_NAME}.tar"
-
-    - name: Cleanup old Docker images
-      if: always()
-      shell: sh
-      run: |
-        set -eu
-        if [ -f scripts/cleanup_old_images.sh ]; then
-          chmod +x scripts/cleanup_old_images.sh
-          scripts/cleanup_old_images.sh
-        else
-          echo "Cleanup script not found, doing basic prune..."
-          docker image prune -f 2>/dev/null || true
-        fi
-        echo "Disk usage after cleanup:"
-        df -h / | tail -1
-
-  deploy-production:
-    name: Deploy Production
-    runs-on: ubuntu-22.04
-    if: startsWith(github.ref, 'refs/tags/v')
-    needs: build-production-runtime-images
-
-    steps:
-    - name: Install SSH client
-      shell: sh
-      run: |
-        set -eu
-        apt-get update -qq && apt-get install -y -qq openssh-client >/dev/null 2>&1
-        echo "openssh-client installed"
-
-    - name: Deploy production over SSH
-      shell: sh
-      env:
-        PRODUCTION_SSH_HOST: ${{ secrets.PRODUCTION_SSH_HOST }}
-        PRODUCTION_SSH_USER: ${{ secrets.PRODUCTION_SSH_USER }}
-        PRODUCTION_SSH_KEY: ${{ secrets.PRODUCTION_SSH_KEY }}
-      run: |
-        set -eu
-        production_host="${PRODUCTION_SSH_HOST:-47.98.113.167}"
-        production_user="${PRODUCTION_SSH_USER:-root}"
-        mkdir -p ~/.ssh
-        # Prefer host key if available (more reliable), fallback to secrets
-        if [ -f /root/.ssh/xiaoxia_runtime_builder ]; then
-          key_path="/root/.ssh/xiaoxia_runtime_builder"
-          echo "Using host SSH key: $key_path"
-        elif [ -n "${PRODUCTION_SSH_KEY:-}" ]; then
-          key_path="$HOME/.ssh/id_ed25519"
-          printf '%s\n' "$PRODUCTION_SSH_KEY" > "$key_path"
-          chmod 600 "$key_path"
-          echo "Using secret SSH key: $key_path"
-        else
-          echo "ERROR: No SSH key available"
-          exit 1
-        fi
-        ssh-keyscan -H "$production_host" >> ~/.ssh/known_hosts
-          echo 'c2V0IC1ldQpyZWxlYXNlX3Rhcj0iL3Zhci9saWIveGlhb3hpYS1zYWFzLXByb2R1Y3Rpb24vcmVsZWFzZS0ke1JFTEVBU0VfVkVSU0lPTn0udGFyLmd6Igp0ZXN0IC1mICIkcmVsZWFzZV90YXIiCnRlc3QgLWYgIi92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3J1bnRpbWUtaW1hZ2VzLSR7UkVMRUFTRV9WRVJTSU9OfS50YXIiCnRlc3QgLWYgIi92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3dlYi0ke1JFTEVBU0VfVkVSU0lPTn0udGFyIgpta2RpciAtcCAvdmFyL2xpYi94aWFveGlhLXNhYXMtcHJvZHVjdGlvbgpvbGRfYXNzZXRzX2Rpcj0iL3RtcC94aWFveGlhLXByZXZpb3VzLXdlYi1hc3NldHMtJHtSRUxFQVNFX1ZFUlNJT059IgpybSAtcmYgIiRvbGRfYXNzZXRzX2RpciIKbWtkaXIgLXAgIiRvbGRfYXNzZXRzX2RpciIKaWYgZG9ja2VyIGluc3BlY3QgeGlhb3hpYS13ZWItcHJvZHVjdGlvbiA+L2Rldi9udWxsIDI+JjE7IHRoZW4KICBkb2NrZXIgY3AgeGlhb3hpYS13ZWItcHJvZHVjdGlvbjovdXNyL3NoYXJlL25naW54L2h0bWwvYXNzZXRzLy4gIiRvbGRfYXNzZXRzX2RpciIvIDI+L2Rldi9udWxsIHx8IHRydWUKZmkKaWYgWyAtZCAvdmFyL2xpYi94aWFveGlhLXNhYXMtcHJvZHVjdGlvbi9yZXBvL2FwcHMvd2ViL2Rpc3QvYXNzZXRzIF07IHRoZW4KICBjcCAtYSAvdmFyL2xpYi94aWFveGlhLXNhYXMtcHJvZHVjdGlvbi9yZXBvL2FwcHMvd2ViL2Rpc3QvYXNzZXRzLy4gIiRvbGRfYXNzZXRzX2RpciIvCmZpCnJtIC1yZiAvdmFyL2xpYi94aWFveGlhLXNhYXMtcHJvZHVjdGlvbi9yZXBvCm1rZGlyIC1wIC92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3JlcG8KdGFyIC14emYgIiRyZWxlYXNlX3RhciIgLUMgL3Zhci9saWIveGlhb3hpYS1zYWFzLXByb2R1Y3Rpb24vcmVwbwp0ZXN0IC1mIC92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3JlcG8vYXBwcy93ZWIvZGlzdC9pbmRleC5odG1sCmlmIFsgLWQgIiRvbGRfYXNzZXRzX2RpciIgXTsgdGhlbgogIG1rZGlyIC1wIC92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3JlcG8vYXBwcy93ZWIvZGlzdC9hc3NldHMKICBmb3IgYXNzZXQgaW4gIiRvbGRfYXNzZXRzX2RpciIvKjsgZG8KICAgIFsgLWUgIiRhc3NldCIgXSB8fCBjb250aW51ZQogICAgbmFtZT0iJChiYXNlbmFtZSAiJGFzc2V0IikiCiAgICBpZiBbICEgLWUgIi92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3JlcG8vYXBwcy93ZWIvZGlzdC9hc3NldHMvJG5hbWUiIF07IHRoZW4KICAgICAgY3AgLWEgIiRhc3NldCIgIi92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3JlcG8vYXBwcy93ZWIvZGlzdC9hc3NldHMvJG5hbWUiCiAgICBmaQogIGRvbmUKICBybSAtcmYgIiRvbGRfYXNzZXRzX2RpciIKZmkKdGVzdCAtZiAvdmFyL2xpYi94aWFveGlhLXNhYXMtcHJvZHVjdGlvbi8uZW52CmNwIC92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uLy5lbnYgL3Zhci9saWIveGlhb3hpYS1zYWFzLXByb2R1Y3Rpb24vcmVwby8uZW52CkhPU1RfUFJFRklYPSBXRUJfSU1BR0U9InhpYW94aWEtc2Fhcy13ZWI6JHtSRUxFQVNFX1ZFUlNJT059IiBXRUJfSU1BR0VfVEFSPSIvdmFyL2xpYi94aWFveGlhLXNhYXMtcHJvZHVjdGlvbi93ZWItJHtSRUxFQVNFX1ZFUlNJT059LnRhciIgc2ggL3Zhci9saWIveGlhb3hpYS1zYWFzLXByb2R1Y3Rpb24vcmVwby9pbmZyYS9kb2NrZXIvZGVwbG95LXByb2R1Y3Rpb24uc2gKaT0wCndoaWxlIFsgIiRpIiAtbHQgMzAgXTsgZG8KICBpZiB3Z2V0IC1xTy0gaHR0cDovLzEyNy4wLjAuMTo4MDAxL2hlYWx0aDsgdGhlbgogICAgZXhpdCAwCiAgZmkKICBpPSQoKGkgKyAxKSkKICBzbGVlcCAyCmRvbmUKZXhpdCAxCg==' | base64 -d | ssh -i "$key_path" "$production_user@$production_host" "RELEASE_VERSION='${GITHUB_REF_NAME}' sh"
-
-  production-e2e:
-    name: Production Browser E2E
-    runs-on: ubuntu-22.04
-    if: startsWith(github.ref, 'refs/tags/v')
-    needs: deploy-production
-
-    steps:
-    - name: Checkout code
-      shell: sh
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: |
-        set -eu
-        python3 - <<'PY'
-        import io, os, tarfile, urllib.request
-        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']}"})
-        with urllib.request.urlopen(request, timeout=120) as response:
-            archive = response.read()
-        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: Run production browser E2E
-      shell: sh
-      run: |
-        set -eu
-        docker run --rm \
-          -e E2E_BASE_URL=https://saas.xiaoxiajianji.com \
-          -e E2E_API_BASE=https://api.xiaoxiajianji.com/api/v1 \
-          -e E2E_BROWSER_CHANNEL=chromium \
-          -v "$PWD:/workspace" \
-          -w /workspace/apps/web \
-          mcr.microsoft.com/playwright:v1.45.0-jammy \
-          sh -lc 'npm ci && npx playwright test --reporter=line --project=chromium e2e/core-upload.spec.ts e2e/core-generation.spec.ts e2e/core-titles.spec.ts'

.gitea/workflows/pr-auto-scan.yml

@@ -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

.gitea/workflows/pr-automation.yml

@@ -0,0 +1,117 @@
+name: PR Automation
+
+on:
+  pull_request:
+    types: [synchronize, opened, ready_for_review, review_requested]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pr-automation-${{ gitea.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  auto-approve:
+    name: Auto Approve on CI Green
+    runs-on: ci-check
+    if: github.event_name == 'pull_request' && !github.event.pull_request.draft
+    timeout-minutes: 3  # 长等待模式：等CI全绿后自动合并，不遗漏任何PR
+    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: "🔍 脚本语法自检"
+        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:
+          GITHUB_TOKEN: ${{ github.token }}
+          REVIEW_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          bash scripts/ci/auto_approve.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
+
+  auto-merge:
+    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: 3  # 短作业模式：检查一次，不满足就退出，由pr-auto-scan每5分钟定时兜底
+    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: "🔍 脚本语法自检（防止脚本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:
+          GITHUB_TOKEN: ${{ github.token }}
+          MERGE_TOKEN: ${{ secrets.REVIEW_GITEA_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+        run: |
+          bash scripts/ci/auto_merge.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

.gitea/workflows/preview-cleanup.yml

@@ -0,0 +1,207 @@
+name: Preview Cleanup
+on:
+  pull_request:
+    types:
+    - closed
+    branches:
+    - main
+    - develop
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  cleanup-preview:
+    name: Cleanup Preview Environment
+    runs-on: runtime-builder
+    timeout-minutes: 10
+    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: Extract PR number
+      shell: sh
+      run: |
+        set -eu
+        # 优先从event payload中读取（兼容所有PR事件类型）
+        if [ -n "${GITHUB_EVENT_PATH:-}" ] && [ -f "$GITHUB_EVENT_PATH" ]; then
+          PR_NUMBER=$(python3 -c "import json,sys; print(json.load(sys.stdin).get('number',''))" < "$GITHUB_EVENT_PATH")
+        fi
+        # fallback: 从GITHUB_REF中提取
+        if [ -z "${PR_NUMBER:-}" ]; then
+          PR_NUMBER=$(echo "$GITHUB_REF" | sed -n 's|refs/pull/\([0-9]*\)/.*|\1|p')
+        fi
+        # 再fallback: 兼容纯数字ref
+        if [ -z "${PR_NUMBER:-}" ] || ! echo "$PR_NUMBER" | grep -qE '^[0-9]+$'; then
+          echo "WARNING: Could not extract PR number cleanly, using raw ref suffix"
+          PR_NUMBER=$(echo "$GITHUB_REF" | sed 's|refs/pull/||; s|/.*||')
+        fi
+        echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
+        echo "PR number: $PR_NUMBER"
+        echo "Preview dir: /var/www/preview/pr-${PR_NUMBER}"
+
+    - name: Install SSH client
+      shell: sh
+      run: |
+        set -eu
+        # 先检查是否已存在ssh
+        if command -v ssh >/dev/null 2>&1 && command -v ssh-keyscan >/dev/null 2>&1; then
+          echo "SSH client already available: $(ssh -V 2>&1)"
+          exit 0
+        fi
+        # 尝试多种包管理器安装
+        if command -v apk >/dev/null 2>&1; then
+          apk add --no-cache openssh-client >/dev/null 2>&1
+          echo "openssh-client installed via apk"
+        elif command -v apt-get >/dev/null 2>&1; then
+          apt-get update -qq && apt-get install -y -qq openssh-client >/dev/null 2>&1
+          echo "openssh-client installed via apt-get"
+        elif command -v yum >/dev/null 2>&1; then
+          yum install -y openssh-clients >/dev/null 2>&1
+          echo "openssh-client installed via yum"
+        elif command -v dnf >/dev/null 2>&1; then
+          dnf install -y openssh-clients >/dev/null 2>&1
+          echo "openssh-client installed via dnf"
+        else
+          echo "ERROR: No package manager found and ssh not pre-installed"
+          which ssh 2>/dev/null || echo "  ssh: not found"
+          which ssh-keyscan 2>/dev/null || echo "  ssh-keyscan: not found"
+          exit 1
+        fi
+
+    - name: Remove preview directory from server
+      shell: sh
+      env:
+        PREVIEW_SSH_HOST: ${{ secrets.PREVIEW_SSH_HOST }}
+        PREVIEW_SSH_USER: ${{ secrets.PREVIEW_SSH_USER }}
+        PREVIEW_SSH_PORT: ${{ secrets.PREVIEW_SSH_PORT }}
+        PREVIEW_SSH_KEY: ${{ secrets.PREVIEW_SSH_KEY }}
+      run: |
+        set -eux
+        preview_host="${PREVIEW_SSH_HOST:-47.98.113.167}"
+        preview_user="${PREVIEW_SSH_USER:-root}"
+        preview_port="${PREVIEW_SSH_PORT:-22222}"
+        preview_dir="/var/www/preview/pr-${PR_NUMBER}"
+
+        mkdir -p ~/.ssh
+
+        # 查找可用的SSH密钥（优先用 secret 里专门为 preview 配置的 key）
+        key_path=""
+        if [ -n "${PREVIEW_SSH_KEY:-}" ]; then
+          key_path="$HOME/.ssh/id_ed25519"
+          printf '%s\n' "$PREVIEW_SSH_KEY" > "$key_path"
+          chmod 600 "$key_path"
+          echo "Using key from PREVIEW_SSH_KEY secret"
+        elif [ -f /root/.ssh/xiaoxia_runtime_builder ]; then
+          key_path="/root/.ssh/xiaoxia_runtime_builder"
+          echo "Using key: $key_path (builder key)"
+        elif [ -f "$HOME/.ssh/xiaoxia_runtime_builder" ]; then
+          key_path="$HOME/.ssh/xiaoxia_runtime_builder"
+          echo "Using key: $key_path (home key)"
+        else
+          echo "ERROR: No SSH key available"
+          ls -la ~/.ssh/ 2>/dev/null || true
+          ls -la /root/.ssh/ 2>/dev/null || true
+          exit 1
+        fi
+
+        ssh-keyscan -p "$preview_port" -H "$preview_host" >> ~/.ssh/known_hosts 2>/dev/null
+        echo "SSH keyscan done"
+
+        # 测试SSH连接
+        ssh -p "$preview_port" -i "$key_path" -o StrictHostKeyChecking=no "${preview_user}@${preview_host}" "echo SSH_CONNECTION_OK && hostname"
+        echo "SSH connection verified"
+
+        # 检查目录是否存在
+        DIR_EXISTS=$(ssh -p "$preview_port" -i "$key_path" -o StrictHostKeyChecking=no "${preview_user}@${preview_host}" \
+          "if [ -d '${preview_dir}' ]; then echo 'yes'; else echo 'no'; fi")
+
+        if [ "$DIR_EXISTS" = "yes" ]; then
+          echo "Removing preview directory: ${preview_dir}"
+          ssh -p "$preview_port" -i "$key_path" -o StrictHostKeyChecking=no "${preview_user}@${preview_host}" \
+            "rm -rf ${preview_dir} && echo 'Preview directory removed successfully'"
+          echo "Cleanup completed: ${preview_dir}"
+        else
+          echo "Preview directory does not exist: ${preview_dir}, nothing to clean up"
+        fi
+
+    - name: Comment cleanup notice on PR
+      if: success()
+      shell: sh
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: |
+        set -eu
+        # 从event payload读取PR号（最可靠）
+        if [ -n "${GITHUB_EVENT_PATH:-}" ] && [ -f "$GITHUB_EVENT_PATH" ]; then
+          PR_NUMBER=$(python3 -c "import json,sys; print(json.load(sys.stdin).get('number',''))" < "$GITHUB_EVENT_PATH")
+        else
+          PR_NUMBER=$(echo "$GITHUB_REF" | sed -n 's|refs/pull/\([0-9]*\)/.*|\1|p')
+        fi
+        export PR_NUMBER
+
+        COMMENT_BODY=$(python3 scripts/ci/preview_comment.py cleanup)
+
+        API_URL="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments"
+        curl -s -X POST \
+          -H "Authorization: token ${GITHUB_TOKEN}" \
+          -H "Content-Type: application/json" \
+          -d "$COMMENT_BODY" \
+          "$API_URL" \
+          > /dev/null
+        echo "Cleanup comment posted"
+
+    - 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
+

.gitea/workflows/preview-deploy.yml

@@ -0,0 +1,296 @@
+name: Preview Deploy
+on:
+  pull_request:
+    types:
+    - opened
+    - synchronize
+    - reopened
+    branches:
+    - main
+    - develop
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: "触发原因"
+        required: false
+        default: "手动触发 - 预览环境补跑"
+permissions:
+  contents: read
+  pull-requests: write
+concurrency:
+  group: preview-deploy-${{ gitea.ref }}
+  cancel-in-progress: true
+jobs:
+  deploy-preview:
+    name: Deploy Preview Environment
+    runs-on: runtime-builder
+    timeout-minutes: 20
+    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: Record job start time
+      shell: sh
+      run: |
+        set -eu
+        echo "JOB_START_TIME=$(date +%s)" >> $GITHUB_ENV
+        echo "Job started at $(date)"
+
+    - name: Extract PR number
+      shell: sh
+      run: |
+        set -eu
+        PR_NUMBER=$(echo "$GITHUB_REF" | sed 's|refs/pull/||; s|/.*||')
+        echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
+        echo "PR number: $PR_NUMBER"
+        echo "PREVIEW_URL=https://pr-${PR_NUMBER}.preview.xiaoxiajianji.com" >> $GITHUB_ENV
+        echo "Preview URL: https://pr-${PR_NUMBER}.preview.xiaoxiajianji.com"
+
+    - name: Build frontend
+      shell: sh
+      run: |
+        set -eu
+        NPM_CACHE_VOLUME="xiaoxia-npm-cache"
+        if ! docker volume inspect "$NPM_CACHE_VOLUME" >/dev/null 2>&1; then
+          docker volume create "$NPM_CACHE_VOLUME" >/dev/null
+          echo "Created npm cache volume: $NPM_CACHE_VOLUME"
+        fi
+
+        docker run --rm \
+          -v "$PWD:/workspace" \
+          -v "$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules" \
+          -w /workspace/apps/web \
+          -e VITE_API_URL=https://staging-api.xiaoxiajianji.com \
+          docker.m.daocloud.io/library/node:20 \
+          sh -lc '
+            PACKAGE_LOCK_HASH=$(md5sum package-lock.json 2>/dev/null | cut -d" " -f1)
+            CACHE_HASH_FILE="node_modules/.package-lock-hash"
+            CACHE_VALID=false
+            if [ -f "$CACHE_HASH_FILE" ] && [ "$(cat "$CACHE_HASH_FILE")" = "$PACKAGE_LOCK_HASH" ] && [ -x "node_modules/.bin/vite" ] && [ -x "node_modules/.bin/tsc" ]; then
+              CACHE_VALID=true
+              echo "Cache hit: dependencies valid, skipping npm install"
+            fi
+            if [ "$CACHE_VALID" = "false" ]; then
+              echo "Cache miss or invalid: running npm install..."
+              if ! npm install --include=dev; then
+                echo "npm install failed, cleaning node_modules and retrying..."
+                rm -rf node_modules
+                mkdir -p node_modules
+                npm install --include=dev
+              fi
+              echo "$PACKAGE_LOCK_HASH" > "$CACHE_HASH_FILE"
+              echo "Dependencies installed, cache updated"
+            fi
+            echo "Running TypeScript check..."
+            npx --no-install tsc
+            echo "Running Vite build..."
+            npx --no-install vite build
+            echo "Build completed successfully"
+            ls -la dist/
+          '
+
+    - name: Install SSH client and rsync
+      shell: sh
+      run: |
+        set -eu
+        if command -v apk >/dev/null 2>&1; then
+          apk add --no-cache openssh-client rsync >/dev/null 2>&1
+        elif command -v apt-get >/dev/null 2>&1; then
+          apt-get update -qq && apt-get install -y -qq openssh-client rsync >/dev/null 2>&1
+        elif command -v yum >/dev/null 2>&1; then
+          yum install -y openssh-clients rsync >/dev/null 2>&1
+        else
+          echo "ERROR: No package manager found"
+          exit 1
+        fi
+        echo "openssh-client and rsync installed"
+
+    - name: Deploy preview to server
+      shell: sh
+      env:
+        PREVIEW_SSH_HOST: ${{ secrets.PREVIEW_SSH_HOST }}
+        PREVIEW_SSH_USER: ${{ secrets.PREVIEW_SSH_USER }}
+        PREVIEW_SSH_PORT: ${{ secrets.PREVIEW_SSH_PORT }}
+        PREVIEW_SSH_KEY: ${{ secrets.PREVIEW_SSH_KEY }}
+      run: |
+        set -eux
+        preview_host="${PREVIEW_SSH_HOST:-47.98.113.167}"
+        preview_user="${PREVIEW_SSH_USER:-root}"
+        preview_port="${PREVIEW_SSH_PORT:-22222}"
+        preview_dir="/var/www/preview/pr-${PR_NUMBER}"
+
+        mkdir -p ~/.ssh
+
+        # 查找可用的SSH密钥（优先用 secret 里专门为 preview 配置的 key）
+        key_path=""
+        if [ -n "${PREVIEW_SSH_KEY:-}" ]; then
+          key_path="$HOME/.ssh/id_ed25519"
+          printf '%s\n' "$PREVIEW_SSH_KEY" > "$key_path"
+          chmod 600 "$key_path"
+          echo "Using key from PREVIEW_SSH_KEY secret"
+        elif [ -f /root/.ssh/xiaoxia_runtime_builder ]; then
+          key_path="/root/.ssh/xiaoxia_runtime_builder"
+          echo "Using key: $key_path (builder key)"
+        elif [ -f "$HOME/.ssh/xiaoxia_runtime_builder" ]; then
+          key_path="$HOME/.ssh/xiaoxia_runtime_builder"
+          echo "Using key: $key_path (home key)"
+        else
+          echo "ERROR: No SSH key available"
+          ls -la ~/.ssh/ 2>/dev/null || true
+          ls -la /root/.ssh/ 2>/dev/null || true
+          exit 1
+        fi
+
+        # SSH密钥完整性自检
+        if ! ssh-keygen -y -f "$key_path" > /dev/null 2>&1; then
+          echo "ERROR: SSH密钥损坏（private key contents do not match public）"
+          echo "请检查 PREVIEW_SSH_KEY secret 中的私钥是否完整正确"
+          echo "私钥文件大小: $(wc -c < "$key_path") 字节"
+          head -2 "$key_path"
+          exit 1
+        fi
+        echo "SSH key integrity check passed"
+
+        ssh-keyscan -p "$preview_port" -H "$preview_host" >> ~/.ssh/known_hosts 2>/dev/null
+        echo "SSH keyscan done"
+
+        # 测试SSH连接
+        ssh -p "$preview_port" -i "$key_path" -o StrictHostKeyChecking=no "${preview_user}@${preview_host}" "echo SSH_CONNECTION_OK && hostname"
+        echo "SSH connection verified"
+
+        # 创建预览目录并上传文件
+        ssh -p "$preview_port" -i "$key_path" -o StrictHostKeyChecking=no "${preview_user}@${preview_host}" \
+          "mkdir -p ${preview_dir} && echo 'Preview directory created: ${preview_dir}'"
+
+        # 使用rsync上传dist目录内容
+        rsync -avz --delete -e "ssh -p ${preview_port} -i ${key_path} -o StrictHostKeyChecking=no" \
+          apps/web/dist/ \
+          "${preview_user}@${preview_host}:${preview_dir}/"
+
+        echo "Preview deployed to: ${preview_dir}"
+        echo "Preview URL: https://pr-${PR_NUMBER}.preview.xiaoxiajianji.com"
+
+    - name: Comment preview link on PR
+      shell: sh
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: |
+        set -eu
+        PR_NUMBER=$(echo "$GITHUB_REF" | sed 's|refs/pull/||; s|/.*||')
+        PREVIEW_URL="https://pr-${PR_NUMBER}.preview.xiaoxiajianji.com"
+        export PR_NUMBER PREVIEW_URL
+
+        COMMENT_BODY=$(python3 scripts/ci/preview_comment.py deploy)
+
+        API_URL="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments"
+
+        EXISTING_COMMENT_ID=$(curl -s -H "Authorization: token ${GITHUB_TOKEN}" "$API_URL" | python3 -c "
+        import sys, json
+        try:
+            for c in json.load(sys.stdin):
+                if '预览环境已部署' in c.get('body', ''):
+                    print(c['id'])
+                    break
+        except Exception:
+            pass
+        ")
+
+        if [ -n "$EXISTING_COMMENT_ID" ]; then
+          curl -s -X PATCH \
+            -H "Authorization: token ${GITHUB_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "$COMMENT_BODY" \
+            "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues/comments/${EXISTING_COMMENT_ID}" \
+            > /dev/null
+          echo "Comment updated"
+        else
+          curl -s -X POST \
+            -H "Authorization: token ${GITHUB_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "$COMMENT_BODY" \
+            "$API_URL" \
+            > /dev/null
+          echo "Comment posted"
+        fi
+
+    - name: Job duration summary
+      if: always()
+      shell: sh
+      run: |
+        set +eu
+        if [ -n "$JOB_START_TIME" ]; then
+          END_TIME=$(date +%s)
+          DURATION=$((END_TIME - JOB_START_TIME))
+          MINS=$((DURATION / 60))
+          SECS=$((DURATION % 60))
+          echo "JOB_DURATION_SECONDS=$DURATION" >> $GITHUB_ENV
+          echo "=== Job Duration: ${MINS}m${SECS}s ==="
+        else
+          echo "JOB_DURATION_SECONDS=0" >> $GITHUB_ENV
+          echo "=== Job Duration: unknown ==="
+        fi
+
+    - 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="Deploy Preview Environment" 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
+

.gitea/workflows/test-ssh-secret.yml

@@ -1,69 +0,0 @@
-name: Test SSH Secret
-on:
-  push:
-    branches: [develop]
-    paths:
-      - '.gitea/workflows/test-ssh-secret.yml'
-
-jobs:
-  test-ssh:
-    runs-on: ubuntu-22.04
-    steps:
-      - name: Install SSH client
-        run: |
-          which ssh || (apt-get update && apt-get install -y openssh-client)
-          ssh -V
-
-      - name: Debug environment
-        run: |
-          echo "=== Environment ==="
-          echo "Runner hostname: $(hostname)"
-          echo "Runner IP: $(hostname -i || echo 'unknown')"
-          echo "Current user: $(whoami)"
-          echo "=== Secrets check ==="
-          if [ -n "$STAGING_SSH_HOST" ]; then
-            echo "STAGING_SSH_HOST: [SET] value_length=${#STAGING_SSH_HOST}"
-          else
-            echo "STAGING_SSH_HOST: [EMPTY]"
-          fi
-          if [ -n "$STAGING_SSH_USER" ]; then
-            echo "STAGING_SSH_USER: [SET] value_length=${#STAGING_SSH_USER}"
-          else
-            echo "STAGING_SSH_USER: [EMPTY]"
-          fi
-          if [ -n "$STAGING_SSH_KEY" ]; then
-            echo "STAGING_SSH_KEY: [SET] value_length=${#STAGING_SSH_KEY}"
-          else
-            echo "STAGING_SSH_KEY: [EMPTY]"
-          fi
-        env:
-          STAGING_SSH_HOST: ${{ secrets.STAGING_SSH_HOST }}
-          STAGING_SSH_USER: ${{ secrets.STAGING_SSH_USER }}
-          STAGING_SSH_KEY: ${{ secrets.STAGING_SSH_KEY }}
-
-      - name: Setup SSH key
-        run: |
-          mkdir -p ~/.ssh
-          chmod 700 ~/.ssh
-          echo "$STAGING_SSH_KEY" > ~/.ssh/id_ed25519
-          chmod 600 ~/.ssh/id_ed25519
-          ssh-keygen -y -f ~/.ssh/id_ed25519 > ~/.ssh/id_ed25519.pub 2>/dev/null || echo "No public key generated"
-          echo "=== SSH Key fingerprint ==="
-          ssh-keygen -lf ~/.ssh/id_ed25519 || echo "Key fingerprint failed"
-        env:
-          STAGING_SSH_KEY: ${{ secrets.STAGING_SSH_KEY }}
-
-      - name: Test SSH connection
-        run: |
-          echo "Attempting SSH connection to $STAGING_SSH_HOST..."
-          ssh -i ~/.ssh/id_ed25519 \
-            -o StrictHostKeyChecking=no \
-            -o UserKnownHostsFile=/dev/null \
-            -o ConnectTimeout=10 \
-            -o BatchMode=yes \
-            -v \
-            $STAGING_SSH_USER@$STAGING_SSH_HOST "echo 'SSH_CONNECTION_SUCCESS' && hostname && whoami"
-          echo "=== SSH Test Complete ==="
-        env:
-          STAGING_SSH_HOST: ${{ secrets.STAGING_SSH_HOST }}
-          STAGING_SSH_USER: ${{ secrets.STAGING_SSH_USER }}

.gitea/workflows/tests.yml

@@ -1,113 +0,0 @@
-name: Tests
-
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    container:
-      image: xiaoxia-ci-python:3.12
-
-    steps:
-    - name: Checkout code
-      shell: sh
-      run: |
-        set -eu
-        python - <<'PY'
-        import io
-        import os
-        import tarfile
-        import urllib.request
-
-        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']}"})
-        with urllib.request.urlopen(request, timeout=120) as response:
-            archive = response.read()
-
-        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: Show Python version
-      shell: sh
-      run: |
-        set -eu
-        python --version
-        python -m pip --version
-
-    - name: Install dependencies
-      shell: sh
-      run: |
-        set -eu
-        python -m pip install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
-        python -m pip install -r requirements.txt -r requirements-dev.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
-
-    - name: Run tests
-      shell: sh
-      run: |
-        set -eu
-        PYTHONPATH="$PWD/apps/api:$PWD" python -m pytest tests/unit -q
-
-  lint:
-    runs-on: ubuntu-latest
-    container:
-      image: xiaoxia-ci-python:3.12
-
-    steps:
-    - name: Checkout code
-      shell: sh
-      run: |
-        set -eu
-        python - <<'PY'
-        import io
-        import os
-        import tarfile
-        import urllib.request
-
-        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']}"})
-        with urllib.request.urlopen(request, timeout=120) as response:
-            archive = response.read()
-
-        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: Install dependencies
-      shell: sh
-      run: |
-        set -eu
-        python -m pip install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
-        python -m pip install -r requirements.txt -r requirements-dev.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
-
-    - name: Run Black (check only)
-      shell: sh
-      run: |
-        set -eu
-        python -m black --check alembic apps packages tests scripts
-
-    - name: Run Flake8
-      shell: sh
-      run: |
-        set -eu
-        python -m flake8 apps packages tests --count --statistics

.gitea/workflows/worker-base-image.yml

@@ -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"

.gitignore

@@ -47,3 +47,4 @@ build/
 # Tracker temp files
 tracker_tasks.json
 
+frontend-v21-ui-prototype-final.html

CHANGELOG.md

@@ -1,3 +1,61 @@
+## [v0.1.110] - 2026-07-03
+
+### 🔒 安全修复
+
+- 注册登录接口添加 RateLimitMiddleware 防止暴力破解
+- JWT logout 黑名单机制，防止令牌重放攻击
+- 生产环境禁用 Swagger 文档防止信息泄露
+- `/metrics` 端点添加 Bearer Token 认证
+- 禁用 SVG 上传防止 XSS 风险
+- 删除 `decode_token_unsafe()` 方法，消除不安全的 JWT 解码
+- 移除遗留 `tasks.py` 消除 Celery 任务名冲突
+- 清理全局 `except:pass`（22处）改为 `logger.warning` 记录异常
+
+### ✨ 功能
+
+- 添加剪辑计划时间线场景 API (`GET /edit-plans/{id}/timeline`)
+- 前端对接真实 API 替换 mock 数据
+
+### 🐛 Bug 修复
+
+- **[P1]** 修复登录故障 — `password_hasher` 导入错误
+- 订阅续费事务修复 — 支付回调在数据库事务中更新订阅状态
+- 账单返回空数组修复 — 从数据库查询账单记录
+- 修复 `Image.open()` 资源泄漏
+- 清理已移除 workspace 概念的残留引用
+- 修复 AssetLibrary/TemplateLibrary 类型错误
+- 修复前端 workspace 残留导致项目创建失败
+- 永久修复 nginx `proxy_pass` 配置
+- 添加 Docker DNS resolver 防止 API 容器重启后 502
+- 修复 worker healthcheck YAML 语法
+- 修复 204 响应体断言崩溃
+- 修复 Alembic 元数据漂移检测
+- 修复 migration 009 DEFAULT 表达式 PostgreSQL 兼容性
+
+### 🔄 重构与清理
+
+- 后端代码清理 — 移除死代码和无用文件
+- 前端代码清理 — 移除无用代码和遗留 demo
+- 代码精简优化 — 移除无用代码和重复定义
+- 后端代码 black/isort 格式化
+
+### 🧪 测试
+
+- 完善 E2E 错误场景测试，Playwright 接入 CI
+- API 集成测试补充（145 项通过）
+- 添加核心流程 E2E 测试
+
+### 🚀 CI/CD & 基础设施
+
+- Validate 阶段添加 PostgreSQL 服务支持
+- 所有 workflow checkout 添加 5 次指数退避重试
+- 启用 BuildKit 分布式缓存 + Gitea Registry 优化构建速度
+- Deploy 阶段全面修复（E2E 服务器/Worker venv/Registry 登录）
+- Docker 网络隔离 staging/production 环境
+- 修复 CI 代码质量检查（black/flake8/bandit）
+
+---
+
 ## [v0.1.88] - 2026-06-29
 
 ### Phase 2 前端优化 - 完成 ✅

alembic/versions/009_remove_workspace_concept.py

@@ -30,11 +30,11 @@ def upgrade() -> None:
     # Step 1: Add subscription/quota fields to users table
     conn.execute(text("""
         ALTER TABLE users
-        ADD COLUMN IF NOT EXISTS subscription_plan VARCHAR(20) NOT NULL DEFAULT free
+        ADD COLUMN IF NOT EXISTS subscription_plan VARCHAR(20) NOT NULL DEFAULT 'free'
     """))
     conn.execute(text("""
         ALTER TABLE users
-        ADD COLUMN IF NOT EXISTS subscription_status VARCHAR(20) NOT NULL DEFAULT active
+        ADD COLUMN IF NOT EXISTS subscription_status VARCHAR(20) NOT NULL DEFAULT 'active'
     """))
     conn.execute(text("""
         ALTER TABLE users
@@ -138,8 +138,8 @@ def downgrade() -> None:
             id VARCHAR(36) PRIMARY KEY,
             name VARCHAR(100) NOT NULL,
             owner_user_id VARCHAR(36) NOT NULL,
-            subscription_plan VARCHAR(20) NOT NULL DEFAULT free,
-            subscription_status VARCHAR(20) NOT NULL DEFAULT active,
+            subscription_plan VARCHAR(20) NOT NULL DEFAULT 'free',
+            subscription_status VARCHAR(20) NOT NULL DEFAULT 'active',
             subscription_expires_at TIMESTAMP,
             max_projects FLOAT NOT NULL DEFAULT 3,
             max_storage_gb FLOAT NOT NULL DEFAULT 10,
@@ -168,7 +168,7 @@ def downgrade() -> None:
             invitee_email VARCHAR(255) NOT NULL,
             role VARCHAR(20) NOT NULL,
             invitation_token VARCHAR(255) NOT NULL UNIQUE,
-            status VARCHAR(20) NOT NULL DEFAULT pending,
+            status VARCHAR(20) NOT NULL DEFAULT 'pending',
             expires_at TIMESTAMP,
             accepted_at TIMESTAMP,
             created_at TIMESTAMP NOT NULL DEFAULT NOW()

alembic/versions/016_phase8_edit_template_plan.py

@@ -6,6 +6,7 @@ Create Date: 2026-07-01
 """
 
 import sqlalchemy as sa
+
 from alembic import op
 
 revision = "016"

alembic/versions/017_phase8_clip_config_plan_clip.py

@@ -0,0 +1,82 @@
+"""Phase 8: Create template_clip_configs and edit_plan_clips tables
+
+Revision ID: 017
+Revises: 016
+Create Date: 2026-07-01
+
+新增两张表：
+- template_clip_configs: 模板片段配置（定义模板中每个片段的规则）
+- edit_plan_clips: 剪辑计划片段（剪辑计划中的具体片段实例）
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "017"
+down_revision = "016"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # template_clip_configs: 模板片段配置表
+    op.create_table(
+        "template_clip_configs",
+        sa.Column("id", sa.String(32), primary_key=True),
+        sa.Column("template_id", sa.String(32), nullable=False, index=True),
+        sa.Column("clip_type", sa.String(20), nullable=False, index=True),
+        sa.Column("order", sa.Integer, nullable=False),
+        sa.Column("min_duration", sa.Float, nullable=False, server_default="0.0"),
+        sa.Column("max_duration", sa.Float, nullable=False, server_default="0.0"),
+        sa.Column("text_template", sa.Text, nullable=False, server_default=""),
+        sa.Column("material_requirements", sa.JSON, nullable=False, server_default="{}"),
+        sa.Column("transition_effect", sa.String(20), nullable=False, server_default="cut"),
+        sa.Column("config", sa.JSON, nullable=False, server_default="{}"),
+        sa.Column(
+            "created_at",
+            sa.DateTime,
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime,
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+    )
+
+    # edit_plan_clips: 剪辑计划片段表
+    op.create_table(
+        "edit_plan_clips",
+        sa.Column("id", sa.String(32), primary_key=True),
+        sa.Column("plan_id", sa.String(32), nullable=False, index=True),
+        sa.Column("clip_type", sa.String(20), nullable=False, index=True),
+        sa.Column("order", sa.Integer, nullable=False),
+        sa.Column("template_clip_config_id", sa.String(32), nullable=False, server_default="", index=True),
+        sa.Column("asset_id", sa.String(32), nullable=False, server_default="", index=True),
+        sa.Column("text_content", sa.Text, nullable=False, server_default=""),
+        sa.Column("start_time", sa.Float, nullable=False, server_default="0.0"),
+        sa.Column("duration", sa.Float, nullable=False, server_default="0.0"),
+        sa.Column("transition_effect", sa.String(20), nullable=False, server_default="cut"),
+        sa.Column("status", sa.String(20), nullable=False, server_default="pending", index=True),
+        sa.Column("config", sa.JSON, nullable=False, server_default="{}"),
+        sa.Column(
+            "created_at",
+            sa.DateTime,
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime,
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("edit_plan_clips")
+    op.drop_table("template_clip_configs")

alembic/versions/018_add_jobs_table.py

@@ -0,0 +1,55 @@
+"""Phase 8 任务 2.10: Create jobs table for unified async task management
+
+Revision ID: 018
+Revises: 017
+Create Date: 2026-07-01
+
+新增 jobs 表，用于统一管理异步任务（视频合成、渲染等）的生命周期。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "018"
+down_revision = "017"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "jobs",
+        sa.Column("id", sa.String(32), primary_key=True),
+        sa.Column("project_id", sa.String(32), nullable=False, index=True),
+        sa.Column("job_type", sa.String(30), nullable=False, index=True),
+        sa.Column("status", sa.String(20), nullable=False, server_default="pending", index=True),
+        sa.Column("progress", sa.Float, nullable=False, server_default="0.0"),
+        sa.Column("current_stage", sa.String(200), nullable=False, server_default=""),
+        sa.Column("payload", sa.JSON, nullable=False, server_default="{}"),
+        sa.Column("result", sa.JSON, nullable=False, server_default="{}"),
+        sa.Column("error_message", sa.Text, nullable=False, server_default=""),
+        sa.Column("retry_count", sa.Integer, nullable=False, server_default="0"),
+        sa.Column("max_retries", sa.Integer, nullable=False, server_default="3"),
+        sa.Column("celery_task_id", sa.String(100), nullable=False, server_default=""),
+        sa.Column("source_id", sa.String(32), nullable=False, server_default="", index=True),
+        sa.Column("created_by_user_id", sa.String(32), nullable=False, server_default="", index=True),
+        sa.Column("started_at", sa.DateTime, nullable=True),
+        sa.Column("completed_at", sa.DateTime, nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime,
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime,
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("jobs")

alembic/versions/019_add_voice_clone_profiles_table.py

@@ -0,0 +1,53 @@
+"""Task 3.05: Create voice_clone_profiles table
+
+Revision ID: 019
+Revises: 018
+Create Date: 2026-07-02
+
+新增 voice_clone_profiles 表，用于存储音色克隆档案。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "019"
+down_revision = "018"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "voice_clone_profiles",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("user_id", sa.String(36), nullable=False, index=True),
+        sa.Column("name", sa.String(100), nullable=False),
+        sa.Column("description", sa.Text(), nullable=False, server_default=""),
+        sa.Column("source_audio_url", sa.Text(), nullable=False, server_default=""),
+        sa.Column("voice_id", sa.String(100), nullable=False, server_default=""),
+        sa.Column("voice_model", sa.String(100), nullable=False, server_default=""),
+        sa.Column("language", sa.String(20), nullable=False, server_default="zh-CN"),
+        sa.Column("gender", sa.String(20), nullable=False, server_default="unknown"),
+        sa.Column("status", sa.String(20), nullable=False, server_default="pending", index=True),
+        sa.Column("error_message", sa.Text(), nullable=False, server_default=""),
+        sa.Column("retry_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("max_retries", sa.Integer(), nullable=False, server_default="3"),
+        sa.Column("metadata", sa.JSON(), nullable=False, server_default="{}"),
+        sa.Column(
+            "created_at",
+            sa.DateTime(),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("voice_clone_profiles")

alembic/versions/020_add_tts_jobs_table.py

@@ -0,0 +1,59 @@
+"""Task 3.06: Create tts_jobs table
+
+Revision ID: 020
+Revises: 019
+Create Date: 2026-07-02
+
+新增 tts_jobs 表，用于存储 TTS 合成任务。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "020"
+down_revision = "019"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "tts_jobs",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("user_id", sa.String(36), nullable=False, index=True),
+        sa.Column("input_text", sa.Text(), nullable=False),
+        sa.Column("voice_id", sa.String(100), nullable=False, server_default=""),
+        sa.Column("voice_model", sa.String(100), nullable=False, server_default=""),
+        sa.Column("project_id", sa.String(36), nullable=False, server_default=""),
+        sa.Column("voice_clone_profile_id", sa.String(36), nullable=False, server_default=""),
+        sa.Column("status", sa.String(20), nullable=False, server_default="pending", index=True),
+        sa.Column("output_audio_url", sa.Text(), nullable=False, server_default=""),
+        sa.Column("output_audio_key", sa.String(500), nullable=False, server_default=""),
+        sa.Column("duration", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("file_size", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("sample_rate", sa.Integer(), nullable=False, server_default="22050"),
+        sa.Column("format", sa.String(20), nullable=False, server_default="mp3"),
+        sa.Column("error_message", sa.Text(), nullable=False, server_default=""),
+        sa.Column("retry_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("max_retries", sa.Integer(), nullable=False, server_default="3"),
+        sa.Column("metadata", sa.JSON(), nullable=False, server_default="{}"),
+        sa.Column("started_at", sa.DateTime(), nullable=True),
+        sa.Column("completed_at", sa.DateTime(), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("tts_jobs")

alembic/versions/021_add_billing_records_table.py

@@ -0,0 +1,43 @@
+"""Task 3.09: Create billing_records table
+
+Revision ID: 021
+Revises: 020
+Create Date: 2026-07-03
+
+新增 billing_records 表，用于存储账单记录。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "021"
+down_revision = "020"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "billing_records",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("user_id", sa.String(36), nullable=False, index=True),
+        sa.Column("plan_name", sa.String(50), nullable=False),
+        sa.Column("amount", sa.Float, nullable=False),
+        sa.Column("billing_cycle", sa.String(20), nullable=False),
+        sa.Column("status", sa.String(20), nullable=False, server_default="pending"),
+        sa.Column("payment_method", sa.String(50), nullable=True),
+        sa.Column("payment_id", sa.String(100), nullable=True),
+        sa.Column("invoice_url", sa.String(500), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column("paid_at", sa.DateTime(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("billing_records")

alembic/versions/022_add_source_edit_plan_id.py

@@ -0,0 +1,56 @@
+"""Task: Add source_edit_plan_id to edit_plans and generation_tasks
+
+Revision ID: 022
+Revises: 021
+Create Date: 2026-07-04
+
+新增 source_edit_plan_id 字段到 edit_plans 和 generation_tasks 表，
+用于关联生成记录到其来源的剪辑计划。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "022"
+down_revision = "021"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "edit_plans",
+        sa.Column("source_edit_plan_id", sa.String(32), nullable=True),
+    )
+    op.create_index(
+        op.f("ix_edit_plans_source_edit_plan_id"),
+        "edit_plans",
+        ["source_edit_plan_id"],
+        unique=False,
+    )
+
+    op.add_column(
+        "generation_tasks",
+        sa.Column("source_edit_plan_id", sa.String(32), nullable=True),
+    )
+    op.create_index(
+        op.f("ix_generation_tasks_source_edit_plan_id"),
+        "generation_tasks",
+        ["source_edit_plan_id"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        op.f("ix_generation_tasks_source_edit_plan_id"),
+        table_name="generation_tasks",
+    )
+    op.drop_column("generation_tasks", "source_edit_plan_id")
+
+    op.drop_index(
+        op.f("ix_edit_plans_source_edit_plan_id"),
+        table_name="edit_plans",
+    )
+    op.drop_column("edit_plans", "source_edit_plan_id")

alembic/versions/023_add_edit_plan_project_and_user.py

@@ -0,0 +1,56 @@
+"""Task: Add project_id and created_by_user_id to edit_plans
+
+Revision ID: 023
+Revises: 022
+Create Date: 2026-07-05
+
+新增 project_id 和 created_by_user_id 字段到 edit_plans 表，
+用于项目归属鉴权和用户归属追踪，修复审计发现的 P1 越权漏洞。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "023"
+down_revision = "022"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "edit_plans",
+        sa.Column("project_id", sa.String(32), nullable=False, server_default=""),
+    )
+    op.create_index(
+        op.f("ix_edit_plans_project_id"),
+        "edit_plans",
+        ["project_id"],
+        unique=False,
+    )
+
+    op.add_column(
+        "edit_plans",
+        sa.Column("created_by_user_id", sa.String(32), nullable=False, server_default=""),
+    )
+    op.create_index(
+        op.f("ix_edit_plans_created_by_user_id"),
+        "edit_plans",
+        ["created_by_user_id"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        op.f("ix_edit_plans_created_by_user_id"),
+        table_name="edit_plans",
+    )
+    op.drop_column("edit_plans", "created_by_user_id")
+
+    op.drop_index(
+        op.f("ix_edit_plans_project_id"),
+        table_name="edit_plans",
+    )
+    op.drop_column("edit_plans", "project_id")

alembic/versions/024_add_user_is_admin.py

@@ -0,0 +1,28 @@
+"""Task: Add is_admin to users
+
+Revision ID: 024
+Revises: 023
+Create Date: 2026-07-05
+
+新增 is_admin 字段到 users 表，用于模板管理等管理员权限校验。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "024"
+down_revision = "023"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "users",
+        sa.Column("is_admin", sa.Boolean(), nullable=False, server_default=sa.text("false")),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("users", "is_admin")

alembic/versions/025_add_user_wechat_fields.py

@@ -0,0 +1,79 @@
+"""Task: Add wechat_openid / wechat_unionid to users
+
+Revision ID: 025
+Revises: 024
+Create Date: 2026-07-05
+
+补录微信小程序登录所需的 wechat 字段。
+生产数据库已手动添加过这些字段和索引，因此 upgrade 做幂等检查，
+避免在已有字段的库上执行报错。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "025"
+down_revision = "024"
+branch_labels = None
+depends_on = None
+
+
+def _column_exists(table: str, column: str) -> bool:
+    """检查列是否已存在。离线模式下返回 False。"""
+    conn = op.get_bind()
+    try:
+        result = conn.execute(
+            sa.text("SELECT 1 FROM information_schema.columns " "WHERE table_name = :table AND column_name = :column"),
+            {"table": table, "column": column},
+        )
+        if result is None:
+            return False
+        return result.scalar() is not None
+    except Exception:
+        return False
+
+
+def _index_exists(index: str) -> bool:
+    """检查索引是否已存在。离线模式下返回 False。"""
+    conn = op.get_bind()
+    try:
+        result = conn.execute(
+            sa.text("SELECT 1 FROM pg_indexes WHERE indexname = :index"),
+            {"index": index},
+        )
+        if result is None:
+            return False
+        return result.scalar() is not None
+    except Exception:
+        return False
+
+
+def upgrade() -> None:
+    # wechat_openid
+    if not _column_exists("users", "wechat_openid"):
+        op.add_column(
+            "users",
+            sa.Column("wechat_openid", sa.String(length=128), nullable=True),
+        )
+
+    # wechat_unionid
+    if not _column_exists("users", "wechat_unionid"):
+        op.add_column(
+            "users",
+            sa.Column("wechat_unionid", sa.String(length=128), nullable=True),
+        )
+
+    # 唯一索引
+    if not _index_exists("ix_users_wechat_openid"):
+        op.create_index("ix_users_wechat_openid", "users", ["wechat_openid"], unique=True)
+
+    if not _index_exists("ix_users_wechat_unionid"):
+        op.create_index("ix_users_wechat_unionid", "users", ["wechat_unionid"], unique=True)
+
+
+def downgrade() -> None:
+    op.drop_index("ix_users_wechat_unionid", table_name="users")
+    op.drop_index("ix_users_wechat_openid", table_name="users")
+    op.drop_column("users", "wechat_unionid")
+    op.drop_column("users", "wechat_openid")

alembic/versions/026_add_user_profile_fields.py

@@ -0,0 +1,56 @@
+"""Add user profile fields (name, avatar, updated_at)
+
+Revision ID: 026
+Revises: 025
+Create Date: 2026-07-05
+
+补录用户资料字段。生产数据库已手动添加过这些字段，
+因此 upgrade 做幂等检查，避免在已有字段的库上执行报错。
+"""
+
+import sqlalchemy as sa
+
+from alembic import context, op
+
+revision = "026"
+down_revision = "025"
+branch_labels = None
+depends_on = None
+
+
+def _column_exists(table: str, column: str) -> bool:
+    if context.is_offline_mode():
+        return False
+    conn = op.get_bind()
+    result = conn.execute(
+        sa.text(
+            "SELECT COUNT(*) FROM information_schema.columns " "WHERE table_name = :table AND column_name = :column"
+        ),
+        {"table": table, "column": column},
+    )
+    return result.scalar() > 0
+
+
+def upgrade() -> None:
+    if not _column_exists("users", "name"):
+        op.add_column("users", sa.Column("name", sa.String(100), nullable=True))
+
+    if not _column_exists("users", "avatar"):
+        op.add_column("users", sa.Column("avatar", sa.String(500), nullable=True))
+
+    if not _column_exists("users", "updated_at"):
+        op.add_column(
+            "users",
+            sa.Column(
+                "updated_at",
+                sa.DateTime(),
+                nullable=True,
+                server_default=sa.func.now(),
+            ),
+        )
+
+
+def downgrade() -> None:
+    op.drop_column("users", "updated_at")
+    op.drop_column("users", "avatar")
+    op.drop_column("users", "name")

alembic/versions/027_add_user_ban_fields.py

@@ -0,0 +1,44 @@
+"""Add user ban fields (ban_reason, ban_at)
+
+Revision ID: 027
+Revises: 026
+Create Date: 2026-07-05
+
+补录用户封禁字段。生产数据库已手动添加过这些字段，
+因此 upgrade 做幂等检查。
+"""
+
+import sqlalchemy as sa
+
+from alembic import context, op
+
+revision = "027"
+down_revision = "026"
+branch_labels = None
+depends_on = None
+
+
+def _column_exists(table: str, column: str) -> bool:
+    if context.is_offline_mode():
+        return False
+    conn = op.get_bind()
+    result = conn.execute(
+        sa.text(
+            "SELECT COUNT(*) FROM information_schema.columns " "WHERE table_name = :table AND column_name = :column"
+        ),
+        {"table": table, "column": column},
+    )
+    return result.scalar() > 0
+
+
+def upgrade() -> None:
+    if not _column_exists("users", "ban_reason"):
+        op.add_column("users", sa.Column("ban_reason", sa.Text(), nullable=True))
+
+    if not _column_exists("users", "ban_at"):
+        op.add_column("users", sa.Column("ban_at", sa.DateTime(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("users", "ban_at")
+    op.drop_column("users", "ban_reason")

alembic/versions/028_add_user_admin_fields.py

@@ -0,0 +1,44 @@
+"""Add user admin fields (admin_status, admin_remarks)
+
+Revision ID: 028
+Revises: 027
+Create Date: 2026-07-05
+
+补录管理员备注字段。生产数据库已手动添加过这些字段，
+因此 upgrade 做幂等检查。
+"""
+
+import sqlalchemy as sa
+
+from alembic import context, op
+
+revision = "028"
+down_revision = "027"
+branch_labels = None
+depends_on = None
+
+
+def _column_exists(table: str, column: str) -> bool:
+    if context.is_offline_mode():
+        return False
+    conn = op.get_bind()
+    result = conn.execute(
+        sa.text(
+            "SELECT COUNT(*) FROM information_schema.columns " "WHERE table_name = :table AND column_name = :column"
+        ),
+        {"table": table, "column": column},
+    )
+    return result.scalar() > 0
+
+
+def upgrade() -> None:
+    if not _column_exists("users", "admin_status"):
+        op.add_column("users", sa.Column("admin_status", sa.String(50), nullable=True))
+
+    if not _column_exists("users", "admin_remarks"):
+        op.add_column("users", sa.Column("admin_remarks", sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("users", "admin_remarks")
+    op.drop_column("users", "admin_status")

alembic/versions/029_add_user_phone.py

@@ -0,0 +1,40 @@
+"""Add user phone field
+
+Revision ID: 029
+Revises: 028
+Create Date: 2026-07-05
+
+补录用户手机号字段。生产数据库已手动添加过该字段，
+因此 upgrade 做幂等检查。
+"""
+
+import sqlalchemy as sa
+
+from alembic import context, op
+
+revision = "029"
+down_revision = "028"
+branch_labels = None
+depends_on = None
+
+
+def _column_exists(table: str, column: str) -> bool:
+    if context.is_offline_mode():
+        return False
+    conn = op.get_bind()
+    result = conn.execute(
+        sa.text(
+            "SELECT COUNT(*) FROM information_schema.columns " "WHERE table_name = :table AND column_name = :column"
+        ),
+        {"table": table, "column": column},
+    )
+    return result.scalar() > 0
+
+
+def upgrade() -> None:
+    if not _column_exists("users", "phone"):
+        op.add_column("users", sa.Column("phone", sa.String(20), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("users", "phone")

alembic/versions/030_add_tags_and_asset_tags.py

@@ -0,0 +1,68 @@
+"""Add tags and asset_tags tables
+
+Revision ID: 030
+Revises: 029
+Create Date: 2026-07-07
+
+新增标签表和素材-标签关联表，支持规范化多对多标签管理。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "030"
+down_revision = "029"
+branch_labels = None
+depends_on = None
+
+
+def _table_exists(table: str) -> bool:
+    ctx = op.get_context()
+    if ctx.as_sql:
+        return False
+    conn = op.get_bind()
+    result = conn.execute(
+        sa.text("SELECT COUNT(*) FROM information_schema.tables WHERE table_name = :table"),
+        {"table": table},
+    )
+    return (result.scalar() or 0) > 0
+
+
+def upgrade() -> None:
+    if not _table_exists("tags"):
+        op.create_table(
+            "tags",
+            sa.Column("id", sa.String(36), primary_key=True),
+            sa.Column("user_id", sa.String(36), nullable=False),
+            sa.Column("name", sa.String(100), nullable=False),
+            sa.Column(
+                "created_at",
+                sa.DateTime(),
+                nullable=False,
+                server_default=sa.func.now(),
+            ),
+            sa.UniqueConstraint("user_id", "name", name="uq_tags_user_name"),
+        )
+        op.create_index("ix_tags_user_id", "tags", ["user_id"])
+
+    if not _table_exists("asset_tags"):
+        op.create_table(
+            "asset_tags",
+            sa.Column("asset_id", sa.String(36), primary_key=True),
+            sa.Column("tag_id", sa.String(36), primary_key=True),
+            sa.Column(
+                "created_at",
+                sa.DateTime(),
+                nullable=False,
+                server_default=sa.func.now(),
+            ),
+        )
+        op.create_index("ix_asset_tags_tag_id", "asset_tags", ["tag_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_asset_tags_tag_id", table_name="asset_tags")
+    op.drop_table("asset_tags")
+    op.drop_index("ix_tags_user_id", table_name="tags")
+    op.drop_table("tags")

alembic/versions/031_add_file_hash_to_assets_and_ing_jobs.py

@@ -0,0 +1,33 @@
+"""Add file_hash to assets and ingest_jobs
+
+Revision ID: 031
+Revises: 030
+Create Date: 2026-07-07
+
+为素材去重检测功能添加 file_hash 字段。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "031"
+down_revision = "030"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("assets", sa.Column("file_hash", sa.String(64), nullable=True))
+    op.create_index(op.f("ix_assets_file_hash"), "assets", ["file_hash"])
+
+    op.add_column("ingest_jobs", sa.Column("file_hash", sa.String(64), nullable=True))
+    op.create_index(op.f("ix_ingest_jobs_file_hash"), "ingest_jobs", ["file_hash"])
+
+
+def downgrade() -> None:
+    op.drop_index(op.f("ix_ingest_jobs_file_hash"), table_name="ingest_jobs")
+    op.drop_column("ingest_jobs", "file_hash")
+
+    op.drop_index(op.f("ix_assets_file_hash"), table_name="assets")
+    op.drop_column("assets", "file_hash")

alembic/versions/032_add_asset_select_mode_to_generation_tasks.py

@@ -0,0 +1,28 @@
+"""Add asset_select_mode to generation_tasks
+
+Revision ID: 032
+Revises: 031
+Create Date: 2026-07-07
+
+素材库自动匹配功能：为 generation_tasks 表添加 asset_select_mode 字段。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "032"
+down_revision = "031"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "generation_tasks",
+        sa.Column("asset_select_mode", sa.String(20), nullable=False, server_default=""),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("generation_tasks", "asset_select_mode")

alembic/versions/033_add_batch_id_to_generation_tasks.py

@@ -0,0 +1,31 @@
+"""Add batch_id to generation_tasks
+
+Revision ID: 033
+Revises: 032
+Create Date: 2026-07-07
+
+视频查重功能：为 generation_tasks 表添加 batch_id 字段，
+用于关联同一次批量生成请求中的多个任务。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "033"
+down_revision = "032"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "generation_tasks",
+        sa.Column("batch_id", sa.String(32), nullable=False, server_default=""),
+    )
+    op.create_index(op.f("ix_generation_tasks_batch_id"), "generation_tasks", ["batch_id"])
+
+
+def downgrade() -> None:
+    op.drop_index(op.f("ix_generation_tasks_batch_id"), table_name="generation_tasks")
+    op.drop_column("generation_tasks", "batch_id")

alembic/versions/034_add_confirm_generation_fields.py

@@ -0,0 +1,60 @@
+"""Add confirm generation fields
+
+Revision ID: 034
+Revises: 033
+Create Date: 2026-07-08
+
+确认生成 API 改造：为 generation_tasks 表添加 is_preview、source_task_id、
+output_width、output_height、cover_url、custom_title 字段。
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "034"
+down_revision = "033"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "generation_tasks",
+        sa.Column("is_preview", sa.Boolean(), nullable=False, server_default=sa.true()),
+    )
+    op.add_column(
+        "generation_tasks",
+        sa.Column("source_task_id", sa.String(32), nullable=False, server_default=""),
+    )
+    op.add_column(
+        "generation_tasks",
+        sa.Column("output_width", sa.Integer(), nullable=False, server_default=sa.text("1280")),
+    )
+    op.add_column(
+        "generation_tasks",
+        sa.Column("output_height", sa.Integer(), nullable=False, server_default=sa.text("720")),
+    )
+    op.add_column(
+        "generation_tasks",
+        sa.Column("cover_url", sa.String(1000), nullable=False, server_default=""),
+    )
+    op.add_column(
+        "generation_tasks",
+        sa.Column("custom_title", sa.String(500), nullable=False, server_default=""),
+    )
+    op.create_index(
+        op.f("ix_generation_tasks_source_task_id"),
+        "generation_tasks",
+        ["source_task_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(op.f("ix_generation_tasks_source_task_id"), table_name="generation_tasks")
+    op.drop_column("generation_tasks", "custom_title")
+    op.drop_column("generation_tasks", "cover_url")
+    op.drop_column("generation_tasks", "output_height")
+    op.drop_column("generation_tasks", "output_width")
+    op.drop_column("generation_tasks", "source_task_id")
+    op.drop_column("generation_tasks", "is_preview")

apps/api/app/api/router.py

@@ -6,17 +6,23 @@ 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.dashboard import router as dashboard_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.edit_templates import router as edit_templates_router
 from app.api.routes.generated_videos import router as generated_videos_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.jobs import router as jobs_router
 from app.api.routes.projects import router as projects_router
 from app.api.routes.recipes import router as recipes_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
 from app.api.routes.templates import router as templates_router
 from app.api.routes.titles import router as titles_router
+from app.api.routes.tts import router as tts_router
 from app.api.routes.upload import router as upload_router
+from app.api.routes.voice_clones import router as voice_clones_router
 from app.api.routes.voices import router as voices_router
 from fastapi import APIRouter
 
@@ -33,6 +39,11 @@ api_router.include_router(
     prefix="/projects",
     tags=["Project"],
 )
+api_router.include_router(
+    tags_router,
+    prefix="/tags",
+    tags=["Tag"],
+)
 api_router.include_router(
     task_center_router,
     tags=["TaskCenter"],
@@ -76,6 +87,10 @@ api_router.include_router(
     prefix="/generation",
     tags=["Generation"],
 )
+api_router.include_router(
+    jobs_router,
+    tags=["Job"],
+)
 api_router.include_router(
     generated_videos_router,
     prefix="/generated-videos",
@@ -91,6 +106,11 @@ api_router.include_router(
     prefix="/voices",
     tags=["VoiceLibrary"],
 )
+api_router.include_router(
+    voice_clones_router,
+    prefix="/voice-clones",
+    tags=["VoiceClone"],
+)
 api_router.include_router(
     duplication_router,
     prefix="/duplication",
@@ -116,3 +136,18 @@ api_router.include_router(
     prefix="/dashboard",
     tags=["Dashboard"],
 )
+api_router.include_router(
+    edit_templates_router,
+    prefix="/edit-templates",
+    tags=["EditTemplate"],
+)
+api_router.include_router(
+    edit_plans_router,
+    prefix="/edit-plans",
+    tags=["EditPlan"],
+)
+api_router.include_router(
+    tts_router,
+    prefix="/tts",
+    tags=["TTS"],
+)

apps/api/app/api/routes/asset_diagnosis.py

@@ -1,4 +1,5 @@
-from typing import Any
+import logging
+from typing import Any, Optional
 
 from app.auth import AuthenticatedUser, get_current_user
 from app.dependencies import (
@@ -7,10 +8,12 @@ from app.dependencies import (
     get_project_repository,
 )
 from app.schemas.asset_diagnosis import AssetGapItem, AssetSmartViewItem, ProjectAssetDiagnosisResponse
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Query
 
 from packages.domain import Asset, AssetLibraryKind, AssetStatus
 
+logger = logging.getLogger(__name__)
+
 router = APIRouter()
 
 
@@ -190,21 +193,152 @@ def _build_diagnosis(project_id: str, assets: list[Asset]) -> ProjectAssetDiagno
     )
 
 
+def _build_single_asset_diagnosis(project_id: str, asset: Asset) -> ProjectAssetDiagnosisResponse:
+    """为单个素材构建诊断结果"""
+    kind = _asset_kind(asset)
+    is_ready = asset.status == AssetStatus.READY
+    is_problem = asset.status in {AssetStatus.ERROR, AssetStatus.UPLOADING, AssetStatus.PROCESSING}
+    is_risky = is_ready and (
+        (asset.quality_score is not None and asset.quality_score < 60)
+        or asset.metadata.get("review_status") == "rejected"
+        or asset.status == AssetStatus.ERROR
+    )
+    is_unclassified = is_ready and asset.classification_status.value in {"pending", "failed"}
+
+    # 单素材评分
+    score = 0
+    if is_ready:
+        score = 60
+        if kind == "video":
+            score += 20
+        if asset.duration and asset.duration >= 5:
+            score += 10
+        if asset.quality_score and asset.quality_score >= 60:
+            score += 10
+    if is_problem:
+        score = max(score - 30, 0)
+    if is_risky:
+        score = max(score - 20, 0)
+    score = max(0, min(100, score))
+
+    gaps: list[AssetGapItem] = []
+    if not is_ready:
+        gaps.append(
+            AssetGapItem(
+                key="asset_not_ready",
+                severity="critical",
+                message=f"素材状态为 {asset.status.value}，尚未就绪",
+                recommendation="等待素材导入完成后再使用。",
+            )
+        )
+    if is_risky:
+        gaps.append(
+            AssetGapItem(
+                key="asset_low_quality",
+                severity="warning",
+                message="素材质量分偏低或已被拒绝",
+                recommendation="建议使用更清晰、稳定的素材替代。",
+            )
+        )
+    if is_unclassified:
+        gaps.append(
+            AssetGapItem(
+                key="asset_unclassified",
+                severity="info",
+                message="素材尚未完成分类",
+                recommendation="等待分类完成或手动检查素材类型。",
+            )
+        )
+    if kind == "video" and (asset.duration is None or asset.duration < 5):
+        gaps.append(
+            AssetGapItem(
+                key="short_video",
+                severity="warning",
+                message="视频时长偏短",
+                recommendation="建议使用时长 5 秒以上的视频素材。",
+            )
+        )
+
+    used_count = int(asset.metadata.get("generation_use_count") or 0)
+    smart_views = [
+        AssetSmartViewItem(
+            key="asset_info",
+            label="素材信息",
+            count=1,
+            description=f"类型: {kind}，状态: {asset.status.value}",
+        ),
+        AssetSmartViewItem(
+            key="asset_quality",
+            label="质量评分",
+            count=int(asset.quality_score or 0),
+            description=f"质量分: {asset.quality_score or '未评分'}",
+        ),
+        AssetSmartViewItem(
+            key="asset_usage",
+            label="使用次数",
+            count=used_count,
+            description=f"参与生成 {used_count} 次",
+        ),
+    ]
+
+    video_count = 1 if kind == "video" and is_ready else 0
+    image_count = 1 if kind == "image" and is_ready else 0
+    voice_count = 1 if kind == "voice" and is_ready else 0
+    total_duration = round(float(asset.duration or 0), 2) if kind == "video" else 0.0
+
+    return ProjectAssetDiagnosisResponse(
+        project_id=project_id,
+        readiness_score=score,
+        readiness_label=_readiness_label(score),
+        total_assets=1,
+        ready_assets=1 if is_ready else 0,
+        video_assets=video_count,
+        image_assets=image_count,
+        voice_assets=voice_count,
+        total_duration_seconds=total_duration,
+        estimated_video_count=1 if video_count and total_duration >= 5 else 0,
+        used_assets=1 if used_count > 0 else 0,
+        unused_assets=1 if used_count == 0 and is_ready else 0,
+        pending_review_assets=1 if asset.metadata.get("review_status") == "pending_review" else 0,
+        smart_views=smart_views,
+        gaps=gaps,
+    )
+
+
 @router.get("/projects/{project_id}/asset-diagnosis", response_model=ProjectAssetDiagnosisResponse)
 def get_project_asset_diagnosis(
     project_id: str,
+    asset_id: Optional[str] = Query(None),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     project_repository: Any = Depends(get_project_repository),
     asset_library_repository: Any = Depends(get_asset_library_repository),
     asset_repository: Any = Depends(get_asset_repository),
 ) -> ProjectAssetDiagnosisResponse:
-    project = project_repository.find_by_id(project_id)
-    if project is None:
-        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
+    try:
+        project = project_repository.find_by_id(project_id)
+        if project is None:
+            raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
+        if not project.can_access(authenticated_user.user.id):
+            raise HTTPException(status_code=403, detail="Access denied to project")
 
-    libraries = asset_library_repository.find_by_project(project_id)
-    assets: list[Asset] = []
-    for library in libraries:
-        assets.extend(asset_repository.list_by_library(library.id))
+        # 单素材诊断模式
+        if asset_id:
+            asset = asset_repository.get(asset_id)
+            if asset is None:
+                raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
+            if asset.project_id != project_id:
+                raise HTTPException(status_code=403, detail="Asset does not belong to this project")
+            return _build_single_asset_diagnosis(project_id, asset)
+
+        libraries = asset_library_repository.find_by_project(project_id)
+        assets: list[Asset] = []
+        for library in libraries:
+            assets.extend(asset_repository.list_by_library(library.id))
+    except HTTPException:
+        raise
+    except Exception:
+        logger.exception("素材诊断查询失败: project_id=%s", project_id)
+        # 返回空诊断结果，避免 500
+        return _build_diagnosis(project_id, [])
 
     return _build_diagnosis(project_id, assets)

apps/api/app/api/routes/asset_libraries.py

@@ -5,6 +5,7 @@ from app.dependencies import get_asset_library_repository, get_project_repositor
 from app.schemas.asset_library import (
     AssetLibraryResponse,
     CreateAssetLibraryRequest,
+    EnsureDefaultLibraryRequest,
     ListAssetLibrariesResponse,
 )
 from fastapi import APIRouter, Depends, HTTPException, Query, status
@@ -15,7 +16,7 @@ from packages.application import (
     GetProjectUseCase,
     ListAssetLibrariesUseCase,
 )
-from packages.domain import AssetLibraryKind
+from packages.domain import AssetLibrary, AssetLibraryKind
 
 router = APIRouter()
 
@@ -43,6 +44,7 @@ def _to_asset_library_response(item) -> AssetLibraryResponse:
 @router.get("", response_model=ListAssetLibrariesResponse)
 def list_asset_libraries(
     project_id: str | None = Query(None),
+    kind: str | None = Query(None, pattern="^(video|voice|image)$"),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     asset_library_repository: Any = Depends(get_asset_library_repository),
     project_repository: Any = Depends(get_project_repository),
@@ -66,6 +68,11 @@ def list_asset_libraries(
             all_items.extend(use_case.execute(proj.id))
         items = all_items
 
+    # 按 kind 过滤（可选）
+    if kind:
+        kind_enum = AssetLibraryKind(kind)
+        items = [item for item in items if item.kind == kind_enum]
+
     return ListAssetLibrariesResponse(items=[_to_asset_library_response(item) for item in items])
 
 
@@ -90,3 +97,53 @@ def create_asset_library(
         )
     )
     return _to_asset_library_response(item)
+
+
+# 默认素材库名称映射
+_DEFAULT_LIBRARY_NAMES = {
+    "video": "视频素材库",
+    "voice": "配音素材库",
+    "image": "图片素材库",
+}
+
+
+@router.post("/ensure-default", response_model=AssetLibraryResponse)
+def ensure_default_library(
+    request: EnsureDefaultLibraryRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_library_repository: Any = Depends(get_asset_library_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> AssetLibraryResponse:
+    """确保项目下指定 kind 的默认素材库存在，已存在则直接返回，不存在则自动创建。"""
+    project = project_repository.find_by_id(request.project_id)
+    if project is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+    if not project.can_access(authenticated_user.user.id):
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied to project")
+
+    kind = AssetLibraryKind(request.kind)
+
+    # 查找该项目下同 kind 的素材库，返回第一个
+    existing = asset_library_repository.find_by_project(request.project_id)
+    for lib in existing:
+        if lib.kind == kind:
+            return _to_asset_library_response(lib)
+
+    # 不存在 → 自动创建
+    import uuid
+    from datetime import datetime, timezone
+
+    now = datetime.now(timezone.utc)
+    default_name = _DEFAULT_LIBRARY_NAMES.get(request.kind, f"{request.kind}素材库")
+    library = AssetLibrary(
+        id=str(uuid.uuid4()),
+        project_id=request.project_id,
+        name=default_name,
+        kind=kind,
+        asset_count=0,
+        total_size=0,
+        created_at=now,
+        updated_at=now,
+    )
+    created = asset_library_repository.create(library)
+    return _to_asset_library_response(created)

apps/api/app/api/routes/assets.py

@@ -1,25 +1,53 @@
-from typing import Any
+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_library_repository,
     get_asset_repository,
     get_project_repository,
+    get_tag_repository,
 )
-from app.schemas.asset import AssetResponse, CreateAssetRequest, ListAssetsResponse, UpdateAssetReviewRequest
-from fastapi import APIRouter, Depends, HTTPException
+from app.schemas.asset import (
+    AssetResponse,
+    BatchDeleteRequest,
+    BatchDeleteResponse,
+    CreateAssetRequest,
+    ListAssetsResponse,
+    UpdateAssetRequest,
+    UpdateAssetReviewRequest,
+)
+from app.schemas.tag import TagAssetsRequest
+from fastapi import APIRouter, Depends, HTTPException, Query
 
 from packages.application import (
     CreateAssetCommand,
     CreateAssetUseCase,
-    ListAssetsUseCase,
 )
 from packages.domain import AssetStatus, ClassificationStatus
 
+logger = logging.getLogger(__name__)
+
 router = APIRouter()
 
 
-def _to_asset_response(item) -> AssetResponse:
+def _to_asset_response(item, storage_service=None) -> AssetResponse:
+    # 生成签名文件 URL（用于视频播放 / 文件下载）
+    file_url = None
+    if item.storage_key:
+        try:
+            svc = storage_service or get_storage_service()
+            file_url = svc.get_download_url(item.storage_key)
+        except Exception:
+            logger.warning("生成签名URL失败: storage_key=%s", item.storage_key, exc_info=True)
+            file_url = None
+
+    # 缩略图：优先用已有 thumbnail_url，否则对视频素材复用文件签名 URL
+    thumbnail_url = item.thumbnail_url
+    if not thumbnail_url and item.mime_type and item.mime_type.startswith("video") and file_url:
+        thumbnail_url = file_url
+
     return AssetResponse(
         id=item.id,
         project_id=item.project_id,
@@ -29,7 +57,8 @@ def _to_asset_response(item) -> AssetResponse:
         mime_type=item.mime_type,
         metadata=item.metadata,
         file_size=item.file_size,
-        thumbnail_url=item.thumbnail_url,
+        file_url=file_url,
+        thumbnail_url=thumbnail_url,
         duration=item.duration,
         width=item.width,
         height=item.height,
@@ -39,6 +68,7 @@ def _to_asset_response(item) -> AssetResponse:
         classification_status=item.classification_status.value,
         quality_score=item.quality_score,
         uploaded_by_user_id=item.uploaded_by_user_id,
+        tag_ids=getattr(item, "tag_ids", []),
     )
 
 
@@ -53,19 +83,164 @@ def _check_project_access(project_id: str, user_id: str, project_repository) ->
 
 @router.get("", response_model=ListAssetsResponse)
 def list_assets(
-    library_id: str,
+    library_id: Optional[str] = Query(None),
+    project_id: Optional[str] = Query(None),
+    kind: Optional[str] = Query(None, pattern="^(video|voice|image)$"),
+    keyword: Optional[str] = Query(None, description="按名称模糊匹配"),
+    gender: Optional[str] = Query(None, description="按 metadata.gender 筛选"),
+    style: Optional[str] = Query(None, description="按 metadata.style 筛选"),
+    tag_ids: Optional[str] = Query(None, description="按标签 ID 筛选（逗号分隔，取交集）"),
+    skip: int = Query(0, ge=0),
+    limit: int = Query(100, ge=1, le=500),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     asset_repository: Any = Depends(get_asset_repository),
     asset_library_repository: Any = Depends(get_asset_library_repository),
     project_repository: Any = Depends(get_project_repository),
 ) -> ListAssetsResponse:
-    library = asset_library_repository.get(library_id)
-    if library is None:
-        raise HTTPException(status_code=404, detail=f"AssetLibrary {library_id} not found")
-    _check_project_access(library.project_id, authenticated_user.user.id, project_repository)
-    use_case = ListAssetsUseCase(asset_repository)
-    items = use_case.execute(library_id)
-    return ListAssetsResponse(items=[_to_asset_response(item) for item in items])
+    user_id = authenticated_user.user.id
+
+    # kind → file_type 映射（voice 对应 audio）
+    kind_to_file_type = {"video": "video", "voice": "audio", "image": "image"}
+
+    # 解析 tag_ids 参数（逗号分隔）
+    filter_tag_ids: list[str] | None = None
+    if tag_ids:
+        filter_tag_ids = [t.strip() for t in tag_ids.split(",") if t.strip()]
+        if not filter_tag_ids:
+            filter_tag_ids = None
+
+    # 需要内存过滤的标志（keyword/gender/style/tag_ids 无法在 DB 层过滤）
+    needs_memory_filter = bool(keyword or gender or style or filter_tag_ids)
+
+    def _apply_memory_filters(items):
+        """应用 keyword / gender / style / tag_ids 内存过滤。"""
+        result = items
+        if keyword:
+            kw = keyword.lower()
+            result = [i for i in result if kw in (i.name or "").lower()]
+        if gender:
+            result = [i for i in result if (i.metadata or {}).get("gender") == gender]
+        if style:
+            result = [i for i in result if (i.metadata or {}).get("style") == style]
+        if filter_tag_ids:
+            tag_set = set(filter_tag_ids)
+            result = [i for i in result if tag_set.issubset(set(getattr(i, "tag_ids", [])))]
+        return result
+
+    # ── 优化路径：无内存过滤时，使用 DB 级分页 ──
+    if not needs_memory_filter:
+        ft = kind_to_file_type.get(kind) if kind else None
+
+        # 模式1：指定 library_id
+        if library_id:
+            library = asset_library_repository.get(library_id)
+            if library is None:
+                raise HTTPException(status_code=404, detail=f"AssetLibrary {library_id} not found")
+            _check_project_access(library.project_id, user_id, project_repository)
+            if ft:
+                items = asset_repository.find_by_library_and_file_type(library_id, ft, skip=skip, limit=limit)
+                total = asset_repository.count_by_project(library.project_id) if not kind else len(items)
+            else:
+                items = asset_repository.find_by_library(library_id, skip=skip, limit=limit)
+                total = asset_repository.count_by_project(library.project_id)
+            return ListAssetsResponse(
+                items=[_to_asset_response(item) for item in items],
+                total=total,
+                skip=skip,
+                limit=limit,
+            )
+
+        # 模式2：指定 project_id
+        if project_id:
+            _check_project_access(project_id, user_id, project_repository)
+            if ft:
+                # 无直接方法，加载后按 file_type 过滤（仍比全量加载好）
+                all_items = asset_repository.find_by_project(project_id)
+                items = [i for i in all_items if i.mime_type and i.mime_type.startswith(ft)]
+                total = len(items)
+                paged = items[skip : skip + limit]
+            else:
+                items = asset_repository.find_by_project(project_id, skip=skip, limit=limit)
+                total = asset_repository.count_by_project(project_id)
+                paged = items
+            return ListAssetsResponse(
+                items=[_to_asset_response(item) for item in paged],
+                total=total,
+                skip=skip,
+                limit=limit,
+            )
+
+        # 模式3：跨项目（无 library_id/project_id）
+        try:
+            projects = project_repository.find_accessible_projects(user_id)
+        except Exception:
+            logger.exception("查询用户可访问项目失败: user_id=%s", user_id)
+            return ListAssetsResponse(items=[], total=0, skip=skip, limit=limit)
+
+        project_ids = [p.id for p in projects]
+        if not project_ids:
+            return ListAssetsResponse(items=[], total=0, skip=skip, limit=limit)
+
+        total = asset_repository.count_by_project_ids(project_ids)
+        # 跨项目分页：逐项目累积直到凑够一页
+        paged_items: list = []
+        offset = skip
+        remaining = limit
+        for pid in project_ids:
+            proj_total = asset_repository.count_by_project(pid)
+            if offset >= proj_total:
+                offset -= proj_total
+                continue
+            proj_items = asset_repository.find_by_project(pid, skip=offset, limit=remaining)
+            paged_items.extend(proj_items)
+            remaining -= len(proj_items)
+            offset = 0
+            if remaining <= 0:
+                break
+
+        return ListAssetsResponse(
+            items=[_to_asset_response(item) for item in paged_items],
+            total=total,
+            skip=skip,
+            limit=limit,
+        )
+
+    # ── 内存过滤路径：有 keyword/gender/style 时，加载全量后内存过滤 ──
+    if library_id:
+        library = asset_library_repository.get(library_id)
+        if library is None:
+            raise HTTPException(status_code=404, detail=f"AssetLibrary {library_id} not found")
+        _check_project_access(library.project_id, user_id, project_repository)
+        if kind:
+            all_items = asset_repository.find_by_library_and_file_type(library_id, kind_to_file_type[kind])
+        else:
+            all_items = asset_repository.find_by_library(library_id)
+    elif project_id:
+        _check_project_access(project_id, user_id, project_repository)
+        all_items = asset_repository.find_by_project(project_id)
+    else:
+        try:
+            projects = project_repository.find_accessible_projects(user_id)
+        except Exception:
+            logger.exception("查询用户可访问项目失败: user_id=%s", user_id)
+            return ListAssetsResponse(items=[], total=0, skip=skip, limit=limit)
+        all_items = []
+        for proj in projects:
+            all_items.extend(asset_repository.find_by_project(proj.id))
+
+    # 应用 kind 过滤（如果有）+ keyword/gender/style
+    if kind:
+        ft = kind_to_file_type.get(kind)
+        all_items = [i for i in all_items if i.mime_type and i.mime_type.startswith(ft or "")]
+    filtered = _apply_memory_filters(all_items)
+    total = len(filtered)
+    paged = filtered[skip : skip + limit]
+    return ListAssetsResponse(
+        items=[_to_asset_response(item) for item in paged],
+        total=total,
+        skip=skip,
+        limit=limit,
+    )
 
 
 def _apply_asset_review_status(item, review_status: str):
@@ -93,6 +268,130 @@ def update_asset_review_status(
     return _to_asset_response(updated)
 
 
+@router.post("/batch-delete", response_model=BatchDeleteResponse)
+def batch_delete_assets(
+    request: BatchDeleteRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> BatchDeleteResponse:
+    """批量删除素材（配音素材等），需逐项校验项目权限。"""
+    user_id = authenticated_user.user.id
+    deleted_ids: list[str] = []
+    failed_ids: list[str] = []
+
+    for asset_id in request.ids:
+        item = asset_repository.find_by_id(asset_id)
+        if item is None:
+            failed_ids.append(asset_id)
+            continue
+        try:
+            _check_project_access(item.project_id, user_id, project_repository)
+            deleted_ids.append(asset_id)
+        except HTTPException:
+            failed_ids.append(asset_id)
+
+    if deleted_ids:
+        asset_repository.batch_delete(deleted_ids)
+
+    return BatchDeleteResponse(deleted_count=len(deleted_ids), failed_ids=failed_ids)
+
+
+@router.get("/{asset_id}", response_model=AssetResponse)
+def get_asset(
+    asset_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> AssetResponse:
+    item = asset_repository.find_by_id(asset_id)
+    if item is None:
+        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
+    _check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    return _to_asset_response(item)
+
+
+@router.put("/{asset_id}", response_model=AssetResponse)
+def update_asset(
+    asset_id: str,
+    request: UpdateAssetRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> AssetResponse:
+    item = asset_repository.find_by_id(asset_id)
+    if item is None:
+        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
+    _check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+
+    # 合并可修改字段
+    if request.name is not None:
+        item.name = request.name
+    if request.metadata is not None:
+        item.metadata = {**item.metadata, **request.metadata}
+    if request.tags is not None:
+        item.metadata = {**item.metadata, "tags": request.tags}
+
+    updated = asset_repository.update(item)
+    return _to_asset_response(updated)
+
+
+@router.delete("/{asset_id}", status_code=204)
+def delete_asset(
+    asset_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> None:
+    item = asset_repository.find_by_id(asset_id)
+    if item is None:
+        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
+    _check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    asset_repository.delete(asset_id)
+
+
+@router.post("/{asset_id}/tags", response_model=AssetResponse)
+def tag_asset(
+    asset_id: str,
+    request: TagAssetsRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+    tag_repository: Any = Depends(get_tag_repository),
+) -> AssetResponse:
+    """给素材打标签。"""
+    item = asset_repository.find_by_id(asset_id)
+    if item is None:
+        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
+    _check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    for tag_id in request.tag_ids:
+        tag = tag_repository.get(tag_id)
+        if tag is None:
+            raise HTTPException(status_code=404, detail=f"Tag {tag_id} not found")
+        if tag.user_id != authenticated_user.user.id:
+            raise HTTPException(status_code=403, detail=f"无权使用标签 {tag_id}")
+        item.add_tag(tag_id)
+    updated = asset_repository.update(item)
+    return _to_asset_response(updated)
+
+
+@router.delete("/{asset_id}/tags/{tag_id}", status_code=204)
+def untag_asset(
+    asset_id: str,
+    tag_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> None:
+    """取消素材的标签。"""
+    item = asset_repository.find_by_id(asset_id)
+    if item is None:
+        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
+    _check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    item.remove_tag(tag_id)
+    asset_repository.update(item)
+
+
 @router.post("", response_model=AssetResponse)
 def create_asset(
     request: CreateAssetRequest,

apps/api/app/api/routes/auth.py

@@ -5,12 +5,16 @@ The route layer is intentionally thin: repository construction lives in
 app.dependencies and authentication behavior lives in application use cases.
 """
 
+import logging
+import os
 from typing import Optional
 
-from app.auth import AuthenticatedUser, get_current_user
+import jwt
+from app.auth import AuthenticatedUser, blacklist_token, get_current_user
 from app.config import settings
 from app.dependencies import get_auth_email_service, get_auth_session_store, get_user_repository
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, Header, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from pydantic import BaseModel, EmailStr
 
 from packages.adapters.redis import NoopSessionStore
@@ -29,6 +33,10 @@ from packages.application.auth.register_user_use_case import RegisterUserRequest
 from packages.application.auth.register_user_use_case import RegisterUserUseCase, VerifyEmailRequest, VerifyEmailUseCase
 from packages.ports.user_repository import UserRepository
 
+logger = logging.getLogger(__name__)
+
+bearer_scheme = HTTPBearer(auto_error=False)
+
 router = APIRouter(prefix="/auth", tags=["认证"])
 
 
@@ -229,6 +237,24 @@ async def reset_password(
     return MessageResponse(message="密码重置成功")
 
 
+@router.post("/logout")
+async def logout(
+    credentials: HTTPAuthorizationCredentials | None = Depends(bearer_scheme),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+):
+    """登出 - 将当前 token 加入黑名单"""
+    from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+    if credentials:
+        try:
+            payload = jwt.decode(credentials.credentials, settings.JWT_SECRET_KEY, algorithms=["HS256"])
+            exp = payload.get("exp", 0)
+            blacklist_token(credentials.credentials, exp)
+        except Exception as e:
+            logger.warning(f"Operation failed in apps/api/app/api/routes/auth.py: {e}", exc_info=True)
+    return MessageResponse(message="已登出")
+
+
 @router.get("/me", response_model=CurrentUserResponse)
 async def get_current_user_info(
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -259,3 +285,99 @@ def _translate_auth_error(error: str | None) -> str:
         "Display name is required": "显示名称不能为空",
     }
     return translations.get(error or "", error or "注册失败")
+
+
+class WechatSyncRequest(BaseModel):
+    openid: str
+    unionid: Optional[str] = None
+    nickname: Optional[str] = None
+    avatar_url: Optional[str] = None
+    source: str = "miniapp"
+
+
+class WechatSyncResponse(BaseModel):
+    access_token: str
+    token: str
+    refresh_token: str
+    user_id: str
+    user: dict
+    user_info: dict
+    is_new_user: bool
+    expires_in: int
+
+
+def _get_internal_api_keys() -> list[str]:
+    """获取内部 API Key 列表
+
+    优先级:
+    1. INTERNAL_API_KEYS 环境变量
+    2. /app/generated/internal_api_keys.txt 文件 (volume 持久化)
+    """
+    env_keys = os.environ.get("INTERNAL_API_KEYS", "")
+    if env_keys:
+        return [k.strip() for k in env_keys.split(",") if k.strip()]
+
+    # 从持久化文件读取
+    try:
+        with open("/app/generated/internal_api_keys.txt", "r") as f:
+            content = f.read().strip()
+            if content:
+                return [k.strip() for k in content.split(",") if k.strip()]
+    except Exception:
+        logger.debug("Failed to read internal API keys from file", exc_info=True)
+
+    return []
+
+
+def _verify_internal_api_key(x_api_key: str | None = Header(None)) -> bool:
+    """验证内部 API Key
+
+    - 已配置时：必须匹配 INTERNAL_API_KEYS 中的 key
+    - 未配置且非生产环境：放行（方便开发）
+    - 未配置且生产环境：拒绝
+    """
+    env = os.environ.get("APP_ENV", os.environ.get("ENV", "development")).lower()
+    key_list = _get_internal_api_keys()
+
+    if not key_list:
+        if env in ("production", "prod"):
+            raise HTTPException(status_code=401, detail="内部接口未配置 API Key")
+        return True
+
+    if x_api_key and x_api_key.strip() in key_list:
+        return True
+
+    raise HTTPException(status_code=401, detail="无效的 API Key")
+
+
+@router.post("/wechat-sync", response_model=WechatSyncResponse, include_in_schema=False)
+async def wechat_sync(
+    request: WechatSyncRequest,
+    user_repository: UserRepository = Depends(get_user_repository),
+    _: bool = Depends(_verify_internal_api_key),
+):
+    """
+    微信同步登录/注册（系统级内部接口）
+
+    由 BFF 层通过 API Key 调用，不直接面向终端用户。
+    根据 openid 查找或创建用户，返回 SaaS token。
+    """
+    from packages.application.auth.wechat_sync_use_case import WechatSyncRequest as UseCaseRequest
+    from packages.application.auth.wechat_sync_use_case import (
+        WechatSyncUseCase,
+    )
+
+    use_case = WechatSyncUseCase(user_repository=user_repository)
+    use_case_request = UseCaseRequest(
+        openid=request.openid,
+        unionid=request.unionid,
+        nickname=request.nickname,
+        avatar_url=request.avatar_url,
+        source=request.source,
+    )
+
+    response, error = use_case.execute(use_case_request)
+    if error:
+        raise HTTPException(status_code=400, detail=error)
+
+    return WechatSyncResponse(**response.to_dict())

apps/api/app/api/routes/chunked_upload.py

@@ -6,7 +6,6 @@ Supports chunked upload, resume, and automatic cleanup of expired uploads.
 import fcntl
 import json
 import logging
-import os
 import shutil
 import tempfile
 from datetime import datetime, timedelta, timezone
@@ -20,6 +19,7 @@ from app.core.celery_app import celery_app
 from app.core.storage import OSSStorageService, get_storage_service
 from app.dependencies import (
     get_asset_library_repository,
+    get_asset_repository,
     get_ingest_job_repository,
     get_project_repository,
 )
@@ -43,20 +43,33 @@ DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024  # 5MB
 MAX_FILE_SIZE = 2 * 1024 * 1024 * 1024  # 2GB
 CHUNK_EXPIRY_HOURS = 24
 
-# Allowed file types (consistent with existing upload.py)
+# Allowed file types — must stay in sync with upload.py ALLOWED_MIME_TYPES
 ALLOWED_MIME_TYPES = {
+    # Images
     "image/jpeg",
     "image/png",
     "image/gif",
     "image/webp",
+    "image/bmp",
+    "image/tiff",
+    "image/svg+xml",
+    # Video
     "video/mp4",
     "video/quicktime",
+    "video/mpeg",
     "video/x-msvideo",
     "video/webm",
+    "video/x-matroska",
+    "video/3gpp",
+    # Audio
     "audio/mpeg",
     "audio/wav",
     "audio/ogg",
     "audio/mp3",
+    "audio/flac",
+    "audio/aac",
+    "audio/x-m4a",
+    "audio/webm",
 }
 
 # Chunk storage root directory
@@ -361,6 +374,7 @@ async def complete_chunked_upload(
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     project_repository: Any = Depends(get_project_repository),
     asset_library_repository: Any = Depends(get_asset_library_repository),
+    asset_repository: Any = Depends(get_asset_repository),
     ingest_job_repository: Any = Depends(get_ingest_job_repository),
     storage_service: OSSStorageService = Depends(get_storage_service),
 ) -> ChunkedUploadCompleteResponse:
@@ -424,6 +438,29 @@ async def complete_chunked_upload(
             content_type=meta["content_type"],
         )
 
+        # ── 素材去重检测：同素材库 + 同 file_hash 视为重复 ──
+        if request.file_hash:
+            existing = asset_repository.find_by_library_and_file_hash(
+                library_id=request.library_id,
+                file_hash=request.file_hash,
+            )
+            if existing is not None:
+                logger.info(
+                    "素材去重命中(chunked): library=%s hash=%s existing_asset=%s",
+                    request.library_id,
+                    request.file_hash,
+                    existing.id,
+                )
+                meta["status"] = "completed"
+                _save_upload_meta(upload_id, meta)
+                return ChunkedUploadCompleteResponse(
+                    storage_key=storage_key,
+                    ingest_job_id="",
+                    url=file_url,
+                    duplicated=True,
+                    asset_id=existing.id,
+                )
+
         # Create ingest job
         use_case = SubmitIngestJobUseCase(ingest_job_repository)
         job = use_case.execute(
@@ -431,6 +468,7 @@ async def complete_chunked_upload(
                 project_id=meta["project_id"],
                 library_id=meta["library_id"],
                 storage_key=storage_key,
+                file_hash=request.file_hash,
             )
         )
         celery_app.send_task("worker.ingest_asset", args=[job.id])

apps/api/app/api/routes/classification_jobs.py

@@ -1,4 +1,3 @@
-from datetime import datetime, timezone
 from typing import Any
 
 from app.core.celery_app import celery_app

apps/api/app/api/routes/duplication.py

@@ -15,7 +15,7 @@ from app.schemas.duplication import (
     DuplicationRecordResponse,
     DuplicationUploadResponse,
 )
-from fastapi import APIRouter, Depends, File, HTTPException, Response, UploadFile, status
+from fastapi import APIRouter, Depends, File, HTTPException, Query, Response, UploadFile, status
 
 from packages.application import (
     DeleteDuplicationRecordUseCase,
@@ -29,7 +29,9 @@ from packages.domain.duplication import DuplicationRecord
 
 logger = logging.getLogger(__name__)
 
-router = APIRouter()
+router = APIRouter(
+    tags=["查重"],
+)
 
 # 查重功能只接受视频文件
 ALLOWED_VIDEO_MIME_TYPES = frozenset(
@@ -199,12 +201,19 @@ async def upload_for_duplication(
 
 @router.get("/records", response_model=list[DuplicationRecordResponse])
 def list_duplication_records(
+    offset: int = Query(0, ge=0, description="分页偏移量"),
+    limit: int = Query(50, ge=1, le=200, description="每页数量，最大 200"),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     duplication_repository: Any = Depends(get_duplication_repository),
 ) -> list[DuplicationRecordResponse]:
-    """获取当前用户的查重记录列表。"""
+    """
+    获取当前用户的查重记录列表。
+
+    支持分页：通过 offset 和 limit 参数控制。
+    返回按创建时间倒序排列的记录。
+    """
     use_case = ListDuplicationRecordsUseCase(duplication_repository)
-    records = use_case.execute(authenticated_user.user.id)
+    records = use_case.execute(user_id=authenticated_user.user.id, offset=offset, limit=limit)
     return [_to_record_response(r) for r in records]
 
 
@@ -230,7 +239,7 @@ def get_duplication_detail(
     return _to_detail_response(record)
 
 
-@router.delete("/records/{record_id}", status_code=status.HTTP_204_NO_CONTENT, response_class=Response)
+@router.delete("/records/{record_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
 def delete_duplication_record(
     record_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -257,7 +266,11 @@ def retry_duplication(
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     duplication_repository: Any = Depends(get_duplication_repository),
 ) -> DuplicationUploadResponse:
-    """重新提交查重。"""
+    """
+    重新提交查重。
+
+    仅 failed 状态的记录允许重试，其他状态返回 400。
+    """
     # 检查记录存在且属于当前用户
     detail_uc = GetDuplicationDetailUseCase(duplication_repository)
     record = detail_uc.execute(record_id)
@@ -268,7 +281,13 @@ def retry_duplication(
         )
 
     use_case = RetryDuplicationUseCase(duplication_repository)
-    updated = use_case.execute(record_id)
+    try:
+        updated = use_case.execute(record_id)
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        )
     if updated is None:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,

apps/api/app/api/routes/edit_plans.py

@@ -0,0 +1,935 @@
+"""剪辑计划管理 API — Phase 8 模板编排引擎.
+
+RESTful CRUD for EditPlan:
+- GET    /api/v1/edit-plans            列表（分页 + 状态/模板筛选）
+- GET    /api/v1/edit-plans/{id}       详情
+- POST   /api/v1/edit-plans            创建
+- PUT    /api/v1/edit-plans/{id}       更新（含状态机流转）
+- DELETE /api/v1/edit-plans/{id}       删除
+- POST   /api/v1/edit-plans/{id}/generate          触发剪辑渲染生成（任务 2.05）
+- GET    /api/v1/edit-plans/{id}/generation-status  查询生成进度（任务 2.05）
+- POST   /api/v1/edit-plans/{id}/ai-recommend       AI 推荐片段方案（任务 3.09）
+- POST   /api/v1/edit-plans/{id}/generate-cover     AI 生成封面（任务 3.09）
+
+业务逻辑委托给 EditPlanService 服务层。
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any, List, Optional
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.core.celery_app import celery_app
+from app.dependencies import get_db_session, get_project_repository
+from app.schemas.generation_task import GenerationTaskResponse
+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.adapters.sqlalchemy_impl.generation_task_repository import (
+    SQLAlchemyGenerationTaskRepository,
+)
+from packages.application.generation_tasks import (
+    CreateGenerationTaskCommand,
+    CreateGenerationTaskUseCase,
+)
+from packages.domain.config_schemas import normalize_plan_config
+from packages.domain.edit_plan import EditPlan, EditPlanStatus
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# ── Pydantic Schemas ─────────────────────────────────────────────────────────
+
+
+class EditPlanCreateRequest(BaseModel):
+    """创建剪辑计划请求体"""
+
+    template_id: str = Field(..., min_length=1, max_length=32, description="关联模板 ID")
+    name: str = Field(..., min_length=1, max_length=200, description="计划名称")
+    config: dict[str, Any] = Field(default_factory=dict, description="计划配置 (JSON)")
+    total_duration: float = Field(default=0.0, ge=0.0, description="总时长 (秒)")
+    project_id: str = Field(default="", description="所属项目 ID")
+
+
+class EditPlanUpdateRequest(BaseModel):
+    """更新剪辑计划请求体"""
+
+    name: Optional[str] = Field(default=None, min_length=1, max_length=200, description="计划名称")
+    config: Optional[dict[str, Any]] = Field(default=None, description="计划配置 (JSON)")
+    total_duration: Optional[float] = Field(default=None, ge=0.0, description="总时长 (秒)")
+    status: Optional[str] = Field(
+        default=None,
+        description="目标状态 (通过状态机流转): editing / rendering / completed / failed / draft",
+    )
+
+
+class EditPlanResponse(BaseModel):
+    """剪辑计划响应体"""
+
+    id: str
+    template_id: str
+    name: str
+    status: str
+    total_duration: float
+    project_id: str = ""
+    created_by_user_id: str = ""
+    config: dict[str, Any]
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class EditPlanListResponse(BaseModel):
+    """剪辑计划列表响应体"""
+
+    items: List[EditPlanResponse]
+    total: int
+    page: int
+    page_size: int
+
+
+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
+    clips: List[ClipStatusItem]
+
+
+class EditPlanGenerateResponse(BaseModel):
+    """剪辑计划触发生成响应体"""
+
+    plan_id: str
+    plan_status: str
+    generation_task_id: str
+    clip_count: int
+
+
+class EditPlanGenerationsResponse(BaseModel):
+    """剪辑计划关联的生成记录列表响应体"""
+
+    items: List[GenerationTaskResponse]
+    total: int
+
+
+# ── AI 推荐片段方案 Schemas（任务 3.09） ──────────────────────────────────────
+
+
+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="转场效果")
+    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)")
+
+
+# ── AI 封面生成 Schemas（任务 3.09） ─────────────────────────────────────────
+
+
+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 等）")
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _check_project_access(project_id: str, user_id: str, project_repository: Any) -> None:
+    """校验用户对项目的访问权限（参照 assets.py 的 can_access 模式）"""
+    if not project_id or not project_id.strip():
+        return
+    project = project_repository.find_by_id(project_id)
+    if project is None:
+        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
+    if not project.can_access(user_id):
+        raise HTTPException(status_code=403, detail="Access denied to project")
+
+
+def _to_response(p: EditPlan) -> EditPlanResponse:
+    return EditPlanResponse(
+        id=p.id,
+        template_id=p.template_id,
+        name=p.name,
+        status=p.status.value if hasattr(p.status, "value") else p.status,
+        total_duration=p.total_duration,
+        project_id=p.project_id or "",
+        created_by_user_id=p.created_by_user_id or "",
+        config=p.config,
+        created_at=p.created_at,
+        updated_at=p.updated_at,
+    )
+
+
+# ── Routes ────────────────────────────────────────────────────────────────────
+
+
+@router.get("", response_model=EditPlanListResponse)
+def list_plans(
+    page: int = Query(default=1, ge=1, description="页码"),
+    page_size: int = Query(default=20, ge=1, le=100, description="每页数量"),
+    template_id: Optional[str] = Query(default=None, description="按模板 ID 筛选"),
+    project_id: Optional[str] = Query(default=None, description="按项目 ID 筛选"),
+    status_filter: Optional[str] = Query(
+        default=None,
+        alias="status",
+        description="按状态筛选: draft / editing / rendering / completed / failed",
+    ),
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> EditPlanListResponse:
+    """获取剪辑计划列表（支持分页、按模板/状态/项目筛选）"""
+    svc = EditPlanService(db)
+
+    # 空串 project_id 视为未传（避免 DB 中匹配到空串记录）
+    if project_id is not None and not project_id.strip():
+        project_id = None
+
+    # 解析状态筛选
+    status_enum: Optional[EditPlanStatus] = None
+    if status_filter:
+        try:
+            status_enum = EditPlanStatus(status_filter)
+        except ValueError:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=(f"无效的状态值: {status_filter}，" f"可选值: draft, editing, rendering, completed, failed"),
+            )
+
+    # 项目鉴权：如果指定了 project_id，校验用户是否有权访问
+    if project_id:
+        _check_project_access(project_id, current_user.user.id, project_repository)
+
+    skip = (page - 1) * page_size
+    plans = svc.list_plans(
+        template_id=template_id,
+        project_id=project_id,
+        status=status_enum,
+        skip=skip,
+        limit=page_size,
+    )
+    total = svc.count_plans(
+        template_id=template_id,
+        project_id=project_id,
+        status=status_enum,
+    )
+
+    return EditPlanListResponse(
+        items=[_to_response(p) for p in plans],
+        total=total,
+        page=page,
+        page_size=page_size,
+    )
+
+
+@router.get("/{plan_id}", response_model=EditPlanResponse)
+def get_plan(
+    plan_id: str,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> EditPlanResponse:
+    """获取单个剪辑计划详情"""
+    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),
+        )
+    # 项目鉴权
+    if plan.project_id:
+        _check_project_access(plan.project_id, current_user.user.id, project_repository)
+    return _to_response(plan)
+
+
+@router.post("", response_model=EditPlanResponse, status_code=status.HTTP_201_CREATED)
+def create_plan(
+    body: EditPlanCreateRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> EditPlanResponse:
+    """创建剪辑计划"""
+    # 空串 project_id 统一为 ""
+    project_id = (body.project_id or "").strip()
+    # 项目鉴权
+    if project_id:
+        _check_project_access(project_id, current_user.user.id, project_repository)
+    svc = EditPlanService(db)
+    # 标准化 config，填充 cover/title/subtitle/bgm 默认值
+    normalized_config = normalize_plan_config(body.config)
+    try:
+        created = svc.create_plan(
+            template_id=body.template_id,
+            name=body.name,
+            config=normalized_config,
+            total_duration=body.total_duration,
+            project_id=project_id,
+            created_by_user_id=current_user.user.id,
+        )
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(exc),
+        )
+    logger.info(
+        "创建剪辑计划: id=%s name=%s by user=%s",
+        created.id,
+        created.name,
+        current_user.user.id,
+    )
+    return _to_response(created)
+
+
+@router.put("/{plan_id}", response_model=EditPlanResponse)
+def update_plan(
+    plan_id: str,
+    body: EditPlanUpdateRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> EditPlanResponse:
+    """更新剪辑计划（支持状态机流转）"""
+    svc = EditPlanService(db)
+    # 项目鉴权
+    existing = svc.get_plan(plan_id)
+    if existing is None:
+        raise HTTPException(status_code=404, detail=f"剪辑计划不存在: {plan_id}")
+    if existing.project_id:
+        _check_project_access(existing.project_id, current_user.user.id, project_repository)
+
+    # 基础字段更新
+    try:
+        if body.name is not None or body.config is not None or body.total_duration is not None:
+            # 标准化 config（如果提供了）
+            config_to_update = normalize_plan_config(body.config) if body.config is not None else None
+            svc.update_plan(
+                plan_id,
+                name=body.name,
+                config=config_to_update,
+                total_duration=body.total_duration,
+            )
+
+        # 状态机流转
+        if body.status is not None:
+            try:
+                target_status = EditPlanStatus(body.status)
+            except ValueError:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=(f"无效的状态值: {body.status}，" f"可选值: draft, editing, rendering, completed, failed"),
+                )
+            svc.transition_status(plan_id, target_status)
+    except ValueError as exc:
+        err_msg = str(exc)
+        if "不存在" in err_msg:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=err_msg,
+            )
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=err_msg,
+        )
+
+    # 返回最新状态
+    result = svc.get_plan_or_raise(plan_id)
+    logger.info("更新剪辑计划: id=%s by user=%s", plan_id, current_user.user.id)
+    return _to_response(result)
+
+
+@router.delete("/{plan_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
+def delete_plan(
+    plan_id: str,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> None:
+    """删除剪辑计划"""
+    svc = EditPlanService(db)
+    # 项目鉴权
+    existing = svc.get_plan(plan_id)
+    if existing and existing.project_id:
+        _check_project_access(existing.project_id, current_user.user.id, project_repository)
+    deleted = svc.delete_plan(plan_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+    logger.info(
+        "删除剪辑计划: id=%s by user=%s",
+        plan_id,
+        current_user.user.id,
+    )
+
+
+# ── 生成相关端点（任务 2.05） ─────────────────────────────────────────────────
+
+
+@router.post("/{plan_id}/generate", response_model=EditPlanGenerateResponse)
+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),
+) -> 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)
+
+    # 检查是否可生成
+    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),
+        )
+    if not can_gen:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=reason,
+        )
+
+    # 将 pending 片段标记为 ready
+    clip_count = svc.mark_clips_ready(plan_id)
+
+    # 创建 GenerationTask
+    gen_task_repo = SQLAlchemyGenerationTaskRepository(db)
+    gen_task_use_case = CreateGenerationTaskUseCase(gen_task_repo)
+    plan = svc.get_plan_or_raise(plan_id)
+    gen_task = gen_task_use_case.execute(
+        CreateGenerationTaskCommand(
+            project_id="",
+            template_id=plan.template_id,
+            created_by_user_id=current_user.user.id,
+            source_edit_plan_id=plan_id,
+        )
+    )
+
+    # 将 generation_task_id 存入 plan config
+    svc.update_plan_config(plan_id, {"generation_task_id": gen_task.id})
+
+    # 流转状态为 rendering
+    svc.transition_status(plan_id, EditPlanStatus.RENDERING)
+
+    # 调度 Celery 任务
+    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,
+    )
+
+
+@router.get(
+    "/{plan_id}/generation-status",
+    response_model=EditPlanGenerationStatusResponse,
+)
+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),
+) -> EditPlanGenerationStatusResponse:
+    """查询剪辑计划生成进度
+
+    返回计划状态、关联的 GenerationTask ID、以及每个片段的状态。
+    """
+    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),
+        )
+
+    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
+    ]
+
+    return EditPlanGenerationStatusResponse(
+        plan_id=plan_id,
+        plan_status=plan.status.value if hasattr(plan.status, "value") else plan.status,
+        generation_task_id=gen_status["generation_task_id"],
+        clips=clip_items,
+    )
+
+
+@router.get(
+    "/{plan_id}/generations",
+    response_model=EditPlanGenerationsResponse,
+)
+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:
+    """查询剪辑计划关联的所有生成记录
+
+    返回该剪辑计划触发的所有 GenerationTask，按创建时间倒序。
+    """
+    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)
+
+    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))
+
+
+# ── AI 推荐 & 封面生成端点（任务 3.09） ────────────────────────────────────────
+
+
+@router.post(
+    "/{plan_id}/ai-recommend",
+    response_model=AIRecommendResponse,
+)
+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. 返回推荐方案详情
+
+    前端对接：
+    - 请求体只需传 asset_ids（必填），editing_mode 和 target_duration 可选
+    - 返回的 clips 可直接渲染到时间线
+    - 返回的 config 包含推荐的封面/标题/字幕/BGM 配置
+    """
+    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),
+        )
+
+    # 项目鉴权
+    if plan.project_id:
+        _check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    # 验证状态：只允许 draft 或 editing
+    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=f"AI 推荐仅支持 draft/editing 状态的计划，当前状态: {plan_status}",
+        )
+
+    # 调用 AI 推荐服务（同步调用 stub，后续改为 Celery 异步）
+    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,
+    )
+
+    # ── 事务保护：清除 → 重建 → 更新 必须在同一逻辑事务中 ──
+    # TODO: 当前各 repo 方法内部 commit()，无法真正回滚。
+    #       后续重构 repo 为 flush() 模式后，此处改为统一 commit。
+    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", {}),
+            )
+
+        # 更新计划 config 和 total_duration
+        normalized_config = normalize_plan_config(result.get("config", {}))
+        svc.update_plan(
+            plan_id,
+            config=normalized_config,
+            total_duration=result["total_duration"],
+        )
+    except Exception as exc:
+        logger.exception("AI 推荐写入失败，plan_id=%s 数据可能不一致", plan_id)
+        # 尝试回滚未提交的变更
+        try:
+            db.rollback()
+        except Exception:
+            pass
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"AI 推荐结果写入失败: {exc}",
+        )
+
+    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,
+)
+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。
+
+    流程：
+    1. 验证计划存在
+    2. 调用 AI 封面生成服务（当前为 stub，后续接入真实 AI）
+    3. 更新 plan.config["cover"] 为生成的封面数据
+    4. 返回封面数据
+
+    前端对接：
+    - cover_type=ai_frame: AI 智能选帧（默认）
+    - cover_type=manual: 手动选帧，需传 frame_time
+    - cover_type=upload: 用户上传，接口返回空 image_url，前端自行上传后更新
+    - cover_type=ai_regenerate: AI 重新生成
+    """
+    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),
+        )
+
+    # 项目鉴权
+    if plan.project_id:
+        _check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    # 调用 AI 封面生成服务
+    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,
+    )
+
+    # 更新 plan.config["cover"]
+    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,
+    )
+
+
+# ── Timeline / Scene 端点（P2-6） ─────────────────────────────────────────────
+
+
+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:
+        # 截取前 20 个字符作为副标题
+        short = text_content[:20].strip()
+        if short:
+            return f"{label} - {short}"
+    return label
+
+
+@router.get(
+    "/{plan_id}/timeline",
+    response_model=TimelineResponse,
+)
+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:
+    """获取剪辑计划的时间线场景数据
+
+    返回按计划片段排序的时间线场景列表，供前端 GeneratePage 渲染使用。
+    """
+    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)
+    # 按 order 排序
+    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,
+    )

apps/api/app/api/routes/edit_templates.py

@@ -0,0 +1,279 @@
+"""模板管理 API — Phase 8 模板编排引擎.
+
+RESTful CRUD for EditTemplate:
+- GET  /api/v1/edit-templates      列表（分页 + 类型筛选）
+- GET  /api/v1/edit-templates/{id} 详情
+- POST /api/v1/edit-templates      创建（管理员）
+- PUT  /api/v1/edit-templates/{id} 更新
+- DELETE /api/v1/edit-templates/{id} 删除（软删除 → inactive）
+
+业务逻辑委托给 EditTemplateService 服务层。
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any, List, Optional
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_db_session
+from app.services import EditTemplateService
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi.responses import Response
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
+
+from packages.domain.config_schemas import normalize_template_config
+from packages.domain.edit_template import EditTemplate, EditTemplateStatus
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# ── Pydantic Schemas ─────────────────────────────────────────────────────────
+
+
+class EditTemplateCreateRequest(BaseModel):
+    """创建模板请求体"""
+
+    name: str = Field(..., min_length=1, max_length=200, description="模板名称")
+    description: str = Field(default="", max_length=2000, description="模板描述")
+    template_type: str = Field(default="default", max_length=50, description="模板类型")
+    config: dict[str, Any] = Field(default_factory=dict, description="模板配置 (JSON)")
+    preview_url: str = Field(default="", max_length=500, description="预览地址")
+    sort_weight: int = Field(default=0, ge=0, le=9999, description="排序权重")
+
+
+class EditTemplateUpdateRequest(BaseModel):
+    """更新模板请求体"""
+
+    name: Optional[str] = Field(default=None, min_length=1, max_length=200, description="模板名称")
+    description: Optional[str] = Field(default=None, max_length=2000, description="模板描述")
+    template_type: Optional[str] = Field(default=None, max_length=50, description="模板类型")
+    config: Optional[dict[str, Any]] = Field(default=None, description="模板配置 (JSON)")
+    preview_url: Optional[str] = Field(default=None, max_length=500, description="预览地址")
+    sort_weight: Optional[int] = Field(default=None, ge=0, le=9999, description="排序权重")
+    status: Optional[str] = Field(default=None, description="状态: active / inactive")
+
+
+class EditTemplateResponse(BaseModel):
+    """模板响应体"""
+
+    id: str
+    name: str
+    description: str
+    template_type: str
+    config: dict[str, Any]
+    preview_url: str
+    sort_weight: int
+    status: str
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class EditTemplateListResponse(BaseModel):
+    """模板列表响应体"""
+
+    items: List[EditTemplateResponse]
+    total: int
+    page: int
+    page_size: int
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _require_admin(current_user: AuthenticatedUser) -> None:
+    """校验当前用户是否为管理员，非管理员返回 403"""
+    if not getattr(current_user.user, "is_admin", False):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="仅管理员可执行此操作",
+        )
+
+
+def _to_response(t: EditTemplate) -> EditTemplateResponse:
+    return EditTemplateResponse(
+        id=t.id,
+        name=t.name,
+        description=t.description,
+        template_type=t.template_type,
+        config=t.config,
+        preview_url=t.preview_url,
+        sort_weight=t.sort_weight,
+        status=t.status.value if hasattr(t.status, "value") else t.status,
+        created_at=t.created_at,
+        updated_at=t.updated_at,
+    )
+
+
+# ── Routes ────────────────────────────────────────────────────────────────────
+
+
+@router.get("", response_model=EditTemplateListResponse)
+def list_templates(
+    page: int = Query(default=1, ge=1, description="页码"),
+    page_size: int = Query(default=20, ge=1, le=100, description="每页数量"),
+    template_type: Optional[str] = Query(default=None, description="按类型筛选"),
+    status_filter: Optional[str] = Query(
+        default=None,
+        alias="status",
+        description="按状态筛选: active / inactive",
+    ),
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> EditTemplateListResponse:
+    """获取模板列表（支持分页、按类型/状态筛选）"""
+    svc = EditTemplateService(db)
+
+    # 解析状态筛选
+    status_enum: Optional[EditTemplateStatus] = None
+    if status_filter:
+        try:
+            status_enum = EditTemplateStatus(status_filter)
+        except ValueError:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"无效的状态值: {status_filter}，可选值: active, inactive",
+            )
+
+    skip = (page - 1) * page_size
+    templates = svc.list_templates(
+        template_type=template_type,
+        status=status_enum,
+        skip=skip,
+        limit=page_size,
+    )
+    total = svc.count_templates(
+        template_type=template_type,
+        status=status_enum,
+    )
+
+    return EditTemplateListResponse(
+        items=[_to_response(t) for t in templates],
+        total=total,
+        page=page,
+        page_size=page_size,
+    )
+
+
+@router.get("/{template_id}", response_model=EditTemplateResponse)
+def get_template(
+    template_id: str,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> EditTemplateResponse:
+    """获取单个模板详情"""
+    svc = EditTemplateService(db)
+    try:
+        template = svc.get_template_or_raise(template_id)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(exc),
+        )
+    return _to_response(template)
+
+
+@router.post("", response_model=EditTemplateResponse, status_code=status.HTTP_201_CREATED)
+def create_template(
+    body: EditTemplateCreateRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> EditTemplateResponse:
+    """创建模板（管理员）"""
+    _require_admin(current_user)
+    svc = EditTemplateService(db)
+    # 标准化 config，填充 cover/title/subtitle/bgm 默认值
+    normalized_config = normalize_template_config(body.config)
+    try:
+        created = svc.create_template(
+            name=body.name,
+            description=body.description,
+            template_type=body.template_type,
+            config=normalized_config,
+            preview_url=body.preview_url,
+            sort_weight=body.sort_weight,
+        )
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(exc),
+        )
+    logger.info("创建模板: id=%s name=%s by user=%s", created.id, created.name, current_user.user.id)
+    return _to_response(created)
+
+
+@router.put("/{template_id}", response_model=EditTemplateResponse)
+def update_template(
+    template_id: str,
+    body: EditTemplateUpdateRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> EditTemplateResponse:
+    """更新模板"""
+    _require_admin(current_user)
+    svc = EditTemplateService(db)
+
+    # 解析状态
+    status_enum: Optional[EditTemplateStatus] = None
+    if body.status is not None:
+        try:
+            status_enum = EditTemplateStatus(body.status)
+        except ValueError:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"无效的状态值: {body.status}，可选值: active, inactive",
+            )
+
+    # 标准化 config（如果提供了）
+    config_to_update = normalize_template_config(body.config) if body.config is not None else None
+
+    try:
+        result = svc.update_template(
+            template_id,
+            name=body.name,
+            description=body.description,
+            template_type=body.template_type,
+            config=config_to_update,
+            preview_url=body.preview_url,
+            sort_weight=body.sort_weight,
+            status=status_enum,
+        )
+    except ValueError as exc:
+        err_msg = str(exc)
+        if "不存在" in err_msg:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=err_msg,
+            )
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=err_msg,
+        )
+    logger.info("更新模板: id=%s by user=%s", template_id, current_user.user.id)
+    return _to_response(result)
+
+
+@router.delete("/{template_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
+def delete_template(
+    template_id: str,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+) -> Response:
+    """删除模板（软删除 → 设为 inactive）"""
+    _require_admin(current_user)
+    svc = EditTemplateService(db)
+    try:
+        svc.deactivate_template(template_id)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(exc),
+        )
+    logger.info("删除模板(软删除): id=%s by user=%s", template_id, current_user.user.id)
+    return Response(status_code=204)

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

@@ -1,3 +1,5 @@
+import random
+import uuid
 from typing import Any
 
 from app.auth import AuthenticatedUser, get_current_user
@@ -14,6 +16,8 @@ from app.schemas.generated_video import (
     ListGeneratedVideosResponse,
 )
 from app.schemas.generation_task import (
+    BatchGenerationTaskResponse,
+    ConfirmGenerationRequest,
     CreateGenerationTaskRequest,
     GenerationTaskResponse,
     ListGenerationTasksResponse,
@@ -50,6 +54,15 @@ def _to_generation_task_response(task) -> GenerationTaskResponse:
         asset_ids=task.asset_ids,
         title_ids=task.title_ids,
         voice_ids=task.voice_ids,
+        source_edit_plan_id=task.source_edit_plan_id or "",
+        asset_select_mode=getattr(task, "asset_select_mode", ""),
+        batch_id=getattr(task, "batch_id", ""),
+        is_preview=getattr(task, "is_preview", True),
+        source_task_id=getattr(task, "source_task_id", ""),
+        output_width=getattr(task, "output_width", 1280),
+        output_height=getattr(task, "output_height", 720),
+        cover_url=getattr(task, "cover_url", ""),
+        custom_title=getattr(task, "custom_title", ""),
         status=task.status,
         progress=task.progress,
         result_count=task.result_count,
@@ -84,6 +97,49 @@ def _ensure_library_has_ready_video_assets(assets) -> None:
         )
 
 
+def _select_assets_from_library(
+    assets: list,
+    mode: str,
+    count: int,
+) -> list[str]:
+    """根据选取模式从素材库中选取 ready 状态的视频素材 ID。
+
+    Args:
+        assets: 素材库中所有素材（Asset 实体列表）
+        mode: 选取模式 — all=全部, random=随机, smart=按质量评分
+        count: 选取数量，0 表示全部（仅 random/smart 模式有效）
+
+    Returns:
+        选中的素材 ID 列表
+    """
+    ready_video_assets = [a for a in assets if a.status.value == "ready" and a.mime_type.startswith("video")]
+
+    if not ready_video_assets:
+        return []
+
+    if mode == "random":
+        selected = (
+            ready_video_assets if count <= 0 else random.sample(ready_video_assets, min(count, len(ready_video_assets)))
+        )
+        return [a.id for a in selected]
+
+    if mode == "smart":
+        # 按质量分降序排列（质量分高的优先），质量分相同时按时长降序
+        sorted_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,
+            ),
+            reverse=True,
+        )
+        selected = sorted_assets if count <= 0 else sorted_assets[:count]
+        return [a.id for a in selected]
+
+    # 默认 all 模式：返回全部 ready 视频素材
+    return [a.id for a in ready_video_assets]
+
+
 def _resolve_project_and_library(
     request: CreateGenerationTaskRequest,
     project_repository: Any,
@@ -121,7 +177,7 @@ def _resolve_project_and_library(
     return project_id, asset_library_id
 
 
-@router.post("/tasks", response_model=GenerationTaskResponse)
+@router.post("/tasks", response_model=BatchGenerationTaskResponse)
 def create_generation_task(
     request: CreateGenerationTaskRequest,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -129,12 +185,13 @@ def create_generation_task(
     project_repository: Any = Depends(get_project_repository),
     asset_library_repository: Any = Depends(get_asset_library_repository),
     asset_repository: Any = Depends(get_asset_repository),
-) -> GenerationTaskResponse:
+) -> BatchGenerationTaskResponse:
     project_id, asset_library_id = _resolve_project_and_library(
         request, project_repository, asset_library_repository, asset_repository, authenticated_user
     )
 
     # asset_library 存在性校验（仅在提供了 asset_library_id 时）
+    resolved_asset_ids: list[str] = list(request.asset_ids)
     if asset_library_id:
         library = asset_library_repository.get(asset_library_id)
         if library is None or (project_id and library.project_id != project_id):
@@ -143,22 +200,105 @@ def create_generation_task(
         assets = asset_repository.find_by_library(asset_library_id)
         _ensure_library_has_ready_video_assets(assets)
 
+        # 素材库自动匹配：当未显式指定 asset_ids 时，按模式自动选取
+        if not resolved_asset_ids:
+            resolved_asset_ids = _select_assets_from_library(
+                assets,
+                mode=request.asset_select_mode,
+                count=request.asset_select_count,
+            )
+
     use_case = CreateGenerationTaskUseCase(generation_task_repository)
-    task = use_case.execute(
+    count = request.count
+    created_tasks = []
+    # 同批次任务共享 batch_id，用于视频查重时批次内比对
+    batch_id = uuid.uuid4().hex if count > 1 else ""
+
+    for _ in range(count):
+        task = use_case.execute(
+            CreateGenerationTaskCommand(
+                project_id=project_id,
+                asset_library_id=asset_library_id,
+                strategy_id=request.strategy_id,
+                voice_library_id=request.voice_library_id,
+                template_id=request.template_id,
+                asset_ids=resolved_asset_ids,
+                title_ids=request.title_ids,
+                voice_ids=request.voice_ids,
+                created_by_user_id=authenticated_user.user.id,
+                source_edit_plan_id=request.source_edit_plan_id,
+                asset_select_mode=request.asset_select_mode,
+                batch_id=batch_id,
+                is_preview=request.is_preview,
+                source_task_id=request.source_task_id,
+                output_width=request.output_width,
+                output_height=request.output_height,
+                cover_url=request.cover_url,
+                custom_title=request.custom_title,
+            )
+        )
+        celery_app.send_task("worker.generate_video", args=[task.id])
+        created_tasks.append(task)
+
+    items = [_to_generation_task_response(t) for t in created_tasks]
+    return BatchGenerationTaskResponse(items=items, total=len(items))
+
+
+@router.post("/tasks/{task_id}/confirm", response_model=BatchGenerationTaskResponse)
+def confirm_generation(
+    task_id: str,
+    request: ConfirmGenerationRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    generation_task_repository: Any = Depends(get_generation_task_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> BatchGenerationTaskResponse:
+    """确认生成 — 基于预览任务创建正式生成任务。
+
+    查找预览任务，复制其配置，创建新的正式生成任务（is_preview=False），
+    使用高分辨率，复用 worker.generate_video 渲染路径。
+    """
+    # 1. 查找源预览任务
+    source_task = generation_task_repository.get(task_id)
+    if source_task is None:
+        raise HTTPException(status_code=404, detail=f"Preview task {task_id} not found")
+
+    # 2. 权限检查
+    if source_task.created_by_user_id and source_task.created_by_user_id != authenticated_user.user.id:
+        raise HTTPException(status_code=403, detail="Access denied to this task")
+    if source_task.project_id:
+        _check_project_access(source_task.project_id, authenticated_user.user.id, project_repository)
+
+    # 3. 创建正式生成任务，复制预览任务的配置
+    use_case = CreateGenerationTaskUseCase(generation_task_repository)
+    new_task = use_case.execute(
         CreateGenerationTaskCommand(
-            project_id=project_id,
-            asset_library_id=asset_library_id,
-            strategy_id=request.strategy_id,
-            voice_library_id=request.voice_library_id,
-            template_id=request.template_id,
-            asset_ids=request.asset_ids,
-            title_ids=request.title_ids,
-            voice_ids=request.voice_ids,
+            project_id=source_task.project_id,
+            asset_library_id=source_task.asset_library_id,
+            strategy_id=source_task.strategy_id,
+            voice_library_id=source_task.voice_library_id,
+            template_id=source_task.template_id,
+            asset_ids=source_task.asset_ids,
+            title_ids=source_task.title_ids,
+            voice_ids=source_task.voice_ids,
             created_by_user_id=authenticated_user.user.id,
+            source_edit_plan_id=source_task.source_edit_plan_id or "",
+            asset_select_mode=source_task.asset_select_mode,
+            is_preview=False,
+            source_task_id=task_id,
+            output_width=request.output_width,
+            output_height=request.output_height,
+            cover_url=request.cover_url,
+            custom_title=request.custom_title,
         )
     )
-    celery_app.send_task("worker.generate_video", args=[task.id])
-    return _to_generation_task_response(task)
+
+    # 4. 调度 worker.generate_video（同一条渲染路径）
+    celery_app.send_task("worker.generate_video", args=[new_task.id])
+
+    return BatchGenerationTaskResponse(
+        items=[_to_generation_task_response(new_task)],
+        total=1,
+    )
 
 
 @router.get("/tasks", response_model=ListGenerationTasksResponse)
@@ -234,6 +374,14 @@ def retry_generation_task(
             title_ids=task.title_ids,
             voice_ids=task.voice_ids,
             created_by_user_id=authenticated_user.user.id,
+            source_edit_plan_id=task.source_edit_plan_id or "",
+            asset_select_mode=getattr(task, "asset_select_mode", ""),
+            is_preview=getattr(task, "is_preview", True),
+            source_task_id=getattr(task, "source_task_id", ""),
+            output_width=getattr(task, "output_width", 1280),
+            output_height=getattr(task, "output_height", 720),
+            cover_url=getattr(task, "cover_url", ""),
+            custom_title=getattr(task, "custom_title", ""),
         )
     )
     celery_app.send_task("worker.generate_video", args=[retried.id])

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

@@ -5,7 +5,6 @@ import redis
 from app.config import settings
 from fastapi import APIRouter, status
 from fastapi.responses import JSONResponse
-from pydantic import BaseModel
 
 router = APIRouter(tags=["Health"])
 
@@ -21,20 +20,8 @@ async def health_check():
 
 @router.get("/ready", status_code=status.HTTP_200_OK)
 async def readiness_check():
-    checks = {
-        "database": await _check_database(),
-        "redis": await _check_redis(),
-        "oss": _check_oss(),
-    }
-    all_healthy = all(check["status"] == "healthy" for check in checks.values())
-    response = {
-        "status": "ready" if all_healthy else "not_ready",
-        "timestamp": datetime.utcnow().isoformat(),
-        "checks": checks,
-    }
-    if not all_healthy:
-        return JSONResponse(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, content=response)
-    return response
+    """简单的就绪检查，仅返回状态。详细健康检查请使用 /health 端点。"""
+    return {"status": "ready"}
 
 
 @router.get("/startup", status_code=status.HTTP_200_OK)

apps/api/app/api/routes/jobs.py

@@ -0,0 +1,332 @@
+"""Job API 路由 — Phase 8 任务 2.10.
+
+提供统一异步任务管理 RESTful 接口：
+- POST   /api/v1/jobs                        创建任务
+- GET    /api/v1/jobs/{job_id}                任务详情
+- GET    /api/v1/projects/{project_id}/jobs   项目任务列表
+- GET    /api/v1/projects/{project_id}/jobs/stats  任务统计
+- PUT    /api/v1/jobs/{job_id}/progress       更新进度
+- POST   /api/v1/jobs/{job_id}/complete       标记完成
+- POST   /api/v1/jobs/{job_id}/fail           标记失败
+- POST   /api/v1/jobs/{job_id}/retry          重试任务
+- POST   /api/v1/jobs/{job_id}/cancel         取消任务
+- POST   /api/v1/jobs/{job_id}/submit         提交执行
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.core.celery_app import celery_app
+from app.dependencies import get_db_session, get_job_repository, get_project_repository
+from app.schemas.job import (
+    CompleteJobRequest,
+    CreateJobRequest,
+    FailJobRequest,
+    JobResponse,
+    JobStatisticsResponse,
+    ListJobsResponse,
+    UpdateProgressRequest,
+    job_to_response,
+)
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from packages.application.jobs import (
+    CancelJobUseCase,
+    CompleteJobCommand,
+    CompleteJobUseCase,
+    CreateJobCommand,
+    CreateJobUseCase,
+    FailJobCommand,
+    FailJobUseCase,
+    GetJobStatisticsUseCase,
+    GetJobUseCase,
+    ListJobsUseCase,
+    RetryJobUseCase,
+    SubmitJobUseCase,
+    UpdateJobProgressCommand,
+    UpdateJobProgressUseCase,
+)
+from packages.domain.job import JobType
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+# 任务类型 → Celery task name 映射
+_JOB_TYPE_TO_CELERY_TASK: dict[str, str] = {
+    JobType.VIDEO_COMPOSE: "worker.compose_video",
+    JobType.RENDER_EDIT_PLAN: "worker.render_edit_plan",
+    JobType.ASSET_INGEST: "worker.ingest_asset",
+    JobType.CLASSIFICATION: "worker.classify_asset",
+    JobType.VOICE_EXTRACTION: "worker.extract_voice",
+    JobType.GENERATION: "worker.generate_video",
+}
+
+
+def _check_project_access(project_id: str, user_id: str, project_repository) -> None:
+    """检查用户是否有项目访问权限。"""
+    project = project_repository.find_by_id(project_id)
+    if project is None:
+        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
+    if not project.can_access(user_id):
+        raise HTTPException(status_code=403, detail="Access denied to project")
+
+
+# ── 创建任务 ──────────────────────────────────────────────────────────────────
+
+
+@router.post("/jobs", response_model=JobResponse, status_code=status.HTTP_201_CREATED)
+def create_job(
+    request: CreateJobRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    job_repo: Any = Depends(get_job_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> JobResponse:
+    """创建异步任务。
+
+    创建后任务处于 pending 状态，需要调用 /submit 提交执行。
+    """
+    _check_project_access(request.project_id, authenticated_user.user.id, project_repository)
+
+    # 校验 job_type
+    try:
+        JobType(request.job_type)
+    except ValueError:
+        raise HTTPException(
+            status_code=400,
+            detail=f"不支持的任务类型: {request.job_type}，" f"可选值: {[t.value for t in JobType]}",
+        )
+
+    use_case = CreateJobUseCase(job_repo)
+    job = use_case.execute(
+        CreateJobCommand(
+            project_id=request.project_id,
+            job_type=request.job_type,
+            payload=request.payload,
+            source_id=request.source_id,
+            created_by_user_id=authenticated_user.user.id,
+            max_retries=request.max_retries,
+        )
+    )
+
+    return job_to_response(job)
+
+
+# ── 提交执行 ──────────────────────────────────────────────────────────────────
+
+
+@router.post("/jobs/{job_id}/submit", response_model=JobResponse)
+def submit_job(
+    job_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    job_repo: Any = Depends(get_job_repository),
+) -> JobResponse:
+    """提交任务执行。
+
+    将任务状态从 pending 切换为 running，并 dispatch Celery 异步任务。
+    """
+    # 权限检查：先获取任务并验证权限，再执行状态变更
+    job = job_repo.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail=f"Job {job_id} not found")
+    if job.created_by_user_id and job.created_by_user_id != authenticated_user.user.id:
+        raise HTTPException(status_code=403, detail="Access denied to this job")
+
+    use_case = SubmitJobUseCase(job_repo)
+
+    try:
+        job = use_case.execute(job_id)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    # Dispatch Celery 任务
+    celery_task_name = _JOB_TYPE_TO_CELERY_TASK.get(job.job_type.value)
+    if celery_task_name:
+        result = celery_app.send_task(celery_task_name, args=[job.id], kwargs=job.payload)
+        job.celery_task_id = result.id
+        job_repo.update(job)
+        logger.info("已提交 Celery 任务: job_id=%s celery_task_id=%s", job.id, result.id)
+
+    return job_to_response(job)
+
+
+# ── 查询接口 ──────────────────────────────────────────────────────────────────
+
+
+@router.get("/jobs/{job_id}", response_model=JobResponse)
+def get_job(
+    job_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    job_repo: Any = Depends(get_job_repository),
+) -> JobResponse:
+    """获取任务详情。"""
+    use_case = GetJobUseCase(job_repo)
+    job = use_case.execute(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail=f"Job {job_id} not found")
+    return job_to_response(job)
+
+
+@router.get("/projects/{project_id}/jobs", response_model=ListJobsResponse)
+def list_project_jobs(
+    project_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    job_repo: Any = Depends(get_job_repository),
+    project_repository: Any = Depends(get_project_repository),
+    job_type: str | None = Query(default=None, description="按任务类型过滤"),
+    status_filter: str | None = Query(default=None, alias="status", description="按状态过滤"),
+    limit: int = Query(default=50, ge=1, le=200),
+    offset: int = Query(default=0, ge=0),
+) -> ListJobsResponse:
+    """获取项目下的任务列表。"""
+    _check_project_access(project_id, authenticated_user.user.id, project_repository)
+
+    use_case = ListJobsUseCase(job_repo)
+    jobs = use_case.execute(
+        project_id=project_id,
+        job_type=job_type,
+        status=status_filter,
+        limit=limit,
+        offset=offset,
+    )
+    items = [job_to_response(j) for j in jobs]
+    return ListJobsResponse(items=items, total=len(items))
+
+
+@router.get("/projects/{project_id}/jobs/stats", response_model=JobStatisticsResponse)
+def get_job_statistics(
+    project_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    job_repo: Any = Depends(get_job_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> JobStatisticsResponse:
+    """获取项目任务统计摘要。"""
+    _check_project_access(project_id, authenticated_user.user.id, project_repository)
+
+    use_case = GetJobStatisticsUseCase(job_repo)
+    stats = use_case.execute(project_id)
+    return JobStatisticsResponse(**stats)
+
+
+# ── 进度更新 ──────────────────────────────────────────────────────────────────
+
+
+@router.put("/jobs/{job_id}/progress", response_model=JobResponse)
+def update_job_progress(
+    job_id: str,
+    request: UpdateProgressRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    job_repo: Any = Depends(get_job_repository),
+) -> JobResponse:
+    """更新任务进度。"""
+    use_case = UpdateJobProgressUseCase(job_repo)
+
+    try:
+        job = use_case.execute(
+            UpdateJobProgressCommand(
+                job_id=job_id,
+                progress=request.progress,
+                current_stage=request.current_stage,
+            )
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    return job_to_response(job)
+
+
+# ── 完成 / 失败 ────────────────────────────────────────────────────────────────
+
+
+@router.post("/jobs/{job_id}/complete", response_model=JobResponse)
+def complete_job(
+    job_id: str,
+    request: CompleteJobRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    job_repo: Any = Depends(get_job_repository),
+) -> JobResponse:
+    """标记任务完成。"""
+    use_case = CompleteJobUseCase(job_repo)
+
+    try:
+        job = use_case.execute(CompleteJobCommand(job_id=job_id, result=request.result))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    return job_to_response(job)
+
+
+@router.post("/jobs/{job_id}/fail", response_model=JobResponse)
+def fail_job(
+    job_id: str,
+    request: FailJobRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    job_repo: Any = Depends(get_job_repository),
+) -> JobResponse:
+    """标记任务失败。"""
+    use_case = FailJobUseCase(job_repo)
+
+    try:
+        job = use_case.execute(FailJobCommand(job_id=job_id, error_message=request.error_message))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    return job_to_response(job)
+
+
+# ── 重试 / 取消 ────────────────────────────────────────────────────────────────
+
+
+@router.post("/jobs/{job_id}/retry", response_model=JobResponse)
+def retry_job(
+    job_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    job_repo: Any = Depends(get_job_repository),
+) -> JobResponse:
+    """重试失败任务。
+
+    将任务重置为 pending，retry_count + 1，但不自动 dispatch。
+    需要再次调用 /submit 提交执行。
+    """
+    # 权限检查：先获取任务并验证权限，再执行状态变更
+    job = job_repo.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail=f"Job {job_id} not found")
+    if job.created_by_user_id and job.created_by_user_id != authenticated_user.user.id:
+        raise HTTPException(status_code=403, detail="Access denied to this job")
+
+    use_case = RetryJobUseCase(job_repo)
+
+    try:
+        job = use_case.execute(job_id)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    return job_to_response(job)
+
+
+@router.post("/jobs/{job_id}/cancel", response_model=JobResponse)
+def cancel_job(
+    job_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    job_repo: Any = Depends(get_job_repository),
+) -> JobResponse:
+    """取消任务。"""
+    # 权限检查：先获取任务并验证权限，再执行状态变更
+    job = job_repo.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail=f"Job {job_id} not found")
+    if job.created_by_user_id and job.created_by_user_id != authenticated_user.user.id:
+        raise HTTPException(status_code=403, detail="Access denied to this job")
+
+    use_case = CancelJobUseCase(job_repo)
+
+    try:
+        job = use_case.execute(job_id)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    return job_to_response(job)

apps/api/app/api/routes/permissions.py

@@ -1,2 +0,0 @@
-# Compatibility module - workspace concept has been removed.
-# All permission checks are handled at the project level (see packages.domain.permissions).

apps/api/app/api/routes/projects.py

@@ -12,6 +12,7 @@ from fastapi import APIRouter, Depends, HTTPException, status
 from packages.application import (
     CreateProjectCommand,
     CreateProjectUseCase,
+    DeleteProjectUseCase,
     GetProjectUseCase,
     ListProjectsUseCase,
 )
@@ -39,6 +40,8 @@ def get_project(
     project = use_case.execute(project_id)
     if project is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+    if not project.can_access(authenticated_user.user.id):
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied to project")
     return _to_project_response(project)
 
 
@@ -67,3 +70,22 @@ def create_project(
         owner_user_id=authenticated_user.user.id,
     )
     return _to_project_response(project)
+
+
+@router.delete("/{project_id}")
+def delete_project(
+    project_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+):
+    use_case = DeleteProjectUseCase(project_repository)
+    try:
+        deleted = use_case.execute(project_id, authenticated_user.user.id)
+    except PermissionError:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Only the project owner can delete this project",
+        )
+    if not deleted:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+    return {"message": "Project deleted successfully"}

apps/api/app/api/routes/recipes.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-from typing import List
-
 from app.auth import AuthenticatedUser, get_current_user
 from app.dependencies import get_db_session, get_user_repository
 from app.schemas.recipe import (
@@ -174,7 +172,7 @@ def update_recipe(
     return _to_response(recipe)
 
 
-@router.delete("/{recipe_id}", status_code=status.HTTP_204_NO_CONTENT, response_class=Response)
+@router.delete("/{recipe_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
 def delete_recipe(
     recipe_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),

apps/api/app/api/routes/subscription.py

@@ -102,8 +102,31 @@ async def get_billing_records(
     current_user: AuthenticatedUser = Depends(get_current_user),
 ):
     """获取账单记录列表"""
-    # TODO: 从数据库查询账单记录
-    return []
+    from packages.adapters.sqlalchemy_impl.billing_repository import SQLAlchemyBillingRepository
+    from packages.adapters.sqlalchemy_impl.session import SessionLocal
+
+    if SessionLocal is None:
+        return []
+
+    session = SessionLocal()
+    try:
+        repo = SQLAlchemyBillingRepository(session)
+        records = repo.find_by_user(current_user.user.id)
+        return [
+            BillingRecord(
+                id=r.id,
+                plan_name=r.plan_name,
+                amount=r.amount,
+                billing_cycle=r.billing_cycle,
+                status=r.status,
+                payment_method=r.payment_method or "未支付",
+                created_at=r.created_at.isoformat() if r.created_at else "",
+                invoice_url=r.invoice_url,
+            )
+            for r in records
+        ]
+    finally:
+        session.close()
 
 
 @router.post("/change-plan", response_model=ChangePlanResponse)
@@ -181,6 +204,61 @@ async def cancel_subscription(
     )
 
 
+@router.post("/payment-callback")
+async def payment_callback(
+    user_id: str,
+    plan: str,
+    billing_cycle: str,
+    amount: float,
+    payment_method: str = "alipay",
+    payment_id: str = "",
+):
+    """支付回调 - 在事务中更新账单和订阅状态
+
+    注意：生产环境需要验证支付签名
+    """
+    import uuid
+    from datetime import timedelta
+
+    from packages.adapters.sqlalchemy_impl.billing_repository import SQLAlchemyBillingRepository
+    from packages.adapters.sqlalchemy_impl.session import SessionLocal
+
+    if SessionLocal is None:
+        raise HTTPException(status_code=500, detail="Database not available")
+
+    session = SessionLocal()
+    try:
+        repo = SQLAlchemyBillingRepository(session)
+
+        # 创建账单记录
+        record_id = uuid.uuid4().hex
+        record = repo.create(
+            {
+                "id": record_id,
+                "user_id": user_id,
+                "plan_name": _get_plan_name(plan),
+                "amount": amount,
+                "billing_cycle": billing_cycle,
+                "status": "pending",
+            }
+        )
+
+        # 在事务中标记支付成功并更新订阅
+        repo.mark_paid(record_id, payment_method, payment_id)
+
+        # 计算到期时间
+        days = 365 if billing_cycle == "yearly" else 30
+        expires_at = datetime.now(timezone.utc) + timedelta(days=days)
+        repo.update_subscription_on_payment(user_id, plan, expires_at)
+
+        return {"success": True, "message": "支付成功", "record_id": record_id}
+    except Exception as e:
+        session.rollback()
+        raise HTTPException(status_code=500, detail=f"支付处理失败: {str(e)}")
+    finally:
+        session.close()
+
+
 @router.post("/toggle-auto-renew", response_model=SimpleResponse)
 async def toggle_auto_renew(
     request: ToggleAutoRenewRequest,

apps/api/app/api/routes/tags.py

@@ -0,0 +1,67 @@
+"""标签 CRUD 路由。"""
+
+import logging
+from typing import Any
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_tag_repository
+from app.schemas.tag import (
+    CreateTagRequest,
+    ListTagsResponse,
+    TagResponse,
+)
+from fastapi import APIRouter, Depends, HTTPException
+
+from packages.domain import Tag
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.get("", response_model=ListTagsResponse)
+def list_tags(
+    skip: int = 0,
+    limit: int = 100,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    tag_repository: Any = Depends(get_tag_repository),
+) -> ListTagsResponse:
+    """列出当前用户的标签。"""
+    user_id = authenticated_user.user.id
+    items = tag_repository.list_by_user(user_id, skip=skip, limit=limit)
+    total = tag_repository.count_by_user(user_id)
+    return ListTagsResponse(
+        items=[TagResponse(id=t.id, name=t.name, created_at=t.created_at) for t in items],
+        total=total,
+    )
+
+
+@router.post("", response_model=TagResponse, status_code=201)
+def create_tag(
+    request: CreateTagRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    tag_repository: Any = Depends(get_tag_repository),
+) -> TagResponse:
+    """创建标签（同用户同名去重，返回 409）。"""
+    user_id = authenticated_user.user.id
+    existing = tag_repository.find_by_name(user_id, request.name)
+    if existing:
+        raise HTTPException(status_code=409, detail="标签名称已存在")
+    tag = Tag.create(user_id=user_id, name=request.name)
+    created = tag_repository.create(tag)
+    return TagResponse(id=created.id, name=created.name, created_at=created.created_at)
+
+
+@router.delete("/{tag_id}", status_code=204)
+def delete_tag(
+    tag_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    tag_repository: Any = Depends(get_tag_repository),
+) -> None:
+    """删除标签（同时清理素材关联）。"""
+    tag = tag_repository.get(tag_id)
+    if tag is None:
+        raise HTTPException(status_code=404, detail="标签不存在")
+    if tag.user_id != authenticated_user.user.id:
+        raise HTTPException(status_code=403, detail="无权删除该标签")
+    tag_repository.delete(tag_id)

apps/api/app/api/routes/task_center.py

@@ -151,6 +151,12 @@ def retry_task_by_id(
             title_ids=task.title_ids,
             voice_ids=task.voice_ids,
             created_by_user_id=authenticated_user.user.id,
+            is_preview=getattr(task, "is_preview", True),
+            source_task_id=getattr(task, "source_task_id", ""),
+            output_width=getattr(task, "output_width", 1280),
+            output_height=getattr(task, "output_height", 720),
+            cover_url=getattr(task, "cover_url", ""),
+            custom_title=getattr(task, "custom_title", ""),
         )
     )
     celery_app.send_task("worker.generate_video", args=[retried.id])
@@ -233,6 +239,12 @@ def retry_project_task(
                 title_ids=task.title_ids,
                 voice_ids=task.voice_ids,
                 created_by_user_id=authenticated_user.user.id,
+                is_preview=getattr(task, "is_preview", True),
+                source_task_id=getattr(task, "source_task_id", ""),
+                output_width=getattr(task, "output_width", 1280),
+                output_height=getattr(task, "output_height", 720),
+                cover_url=getattr(task, "cover_url", ""),
+                custom_title=getattr(task, "custom_title", ""),
             )
         )
         celery_app.send_task("worker.generate_video", args=[retried.id])

apps/api/app/api/routes/templates.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import List
+import logging
 
 from app.auth import AuthenticatedUser, get_current_user
 from app.dependencies import get_db_session
@@ -15,6 +15,7 @@ from app.schemas.template import (
     ListTemplatesResponse,
     SegmentResponse,
     TemplateResponse,
+    ToggleFavoriteResponse,
     UpdateTemplateRequest,
     ValidateTemplateRequest,
     ValidateTemplateResponse,
@@ -22,6 +23,8 @@ from app.schemas.template import (
 from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
 from sqlalchemy.orm import Session
 
+logger = logging.getLogger(__name__)
+
 from packages.adapters.sqlalchemy_impl.template_repository import SQLAlchemyTemplateRepository
 from packages.application.template.commands import (
     CreateCategoryCommand,
@@ -94,9 +97,13 @@ def list_templates(
     template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
 ) -> ListTemplatesResponse:
     user_id = authenticated_user.user.id
-    use_case = ListTemplatesUseCase(template_repository)
-    templates = use_case.execute(user_id, skip=skip, limit=limit)
-    total = template_repository.count_by_user(user_id)
+    try:
+        use_case = ListTemplatesUseCase(template_repository)
+        templates = use_case.execute(user_id, skip=skip, limit=limit)
+        total = template_repository.count_by_user(user_id)
+    except Exception:
+        logger.exception("list_templates 查询失败: user_id=%s", user_id)
+        return ListTemplatesResponse(items=[], total=0)
     return ListTemplatesResponse(
         items=[_to_response(t) for t in templates],
         total=total,
@@ -110,8 +117,12 @@ def get_template(
     template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
 ) -> TemplateResponse:
     user_id = authenticated_user.user.id
-    use_case = GetTemplateUseCase(template_repository)
-    template = use_case.execute(template_id, user_id)
+    try:
+        use_case = GetTemplateUseCase(template_repository)
+        template = use_case.execute(template_id, user_id)
+    except Exception:
+        logger.exception("get_template 查询失败: template_id=%s", template_id)
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="模板查询失败")
     if template is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
     return _to_response(template)
@@ -195,7 +206,7 @@ def update_template(
     return _to_response(template)
 
 
-@router.delete("/{template_id}", status_code=status.HTTP_204_NO_CONTENT, response_class=Response)
+@router.delete("/{template_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
 def delete_template(
     template_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -209,6 +220,25 @@ def delete_template(
     return Response(status_code=204)
 
 
+@router.post("/{template_id}/toggle-favorite", response_model=ToggleFavoriteResponse)
+def toggle_favorite(
+    template_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> ToggleFavoriteResponse:
+    """切换模板收藏状态（当前为兼容端点，始终返回 false）"""
+    user_id = authenticated_user.user.id
+    use_case = GetTemplateUseCase(template_repository)
+    try:
+        template = use_case.execute(template_id, user_id)
+    except Exception:
+        logger.exception("toggle_favorite 查询失败: template_id=%s", template_id)
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
+    if template is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
+    return ToggleFavoriteResponse(id=template_id, is_favorite=False)
+
+
 # ── Validate template ──
 
 
@@ -248,8 +278,12 @@ def list_categories(
     template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
 ) -> ListCategoriesResponse:
     user_id = authenticated_user.user.id
-    use_case = ListCategoriesUseCase(template_repository)
-    categories = use_case.execute(user_id)
+    try:
+        use_case = ListCategoriesUseCase(template_repository)
+        categories = use_case.execute(user_id)
+    except Exception:
+        logger.exception("list_categories 查询失败: user_id=%s", user_id)
+        return ListCategoriesResponse(items=[])
     return ListCategoriesResponse(
         items=[CategoryResponse(id=c.id, user_id=c.user_id, name=c.name, created_at=c.created_at) for c in categories],
     )
@@ -273,7 +307,7 @@ def create_category(
     )
 
 
-@router.delete("/categories/{category_id}", status_code=status.HTTP_204_NO_CONTENT, response_class=Response)
+@router.delete("/categories/{category_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
 def delete_category(
     category_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),

apps/api/app/api/routes/titles.py

@@ -143,7 +143,7 @@ def update_title(
     return _to_response(item)
 
 
-@router.delete("/{title_id}", status_code=status.HTTP_204_NO_CONTENT, response_class=Response)
+@router.delete("/{title_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
 def delete_title(
     title_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),

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

@@ -0,0 +1,370 @@
+"""TTS 合成 API 路由。"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import (
+    get_cosyvoice_service,
+    get_db_session,
+    get_user_repository,
+    get_voice_clone_profile_repository,
+    get_voice_library_repository,
+)
+from app.schemas.tts import (
+    ListTTSJobResponse,
+    SaveToLibraryRequest,
+    SaveToLibraryResponse,
+    TTSJobResponse,
+    TTSStatusResponse,
+    TTSSynthesizeRequest,
+    TTSSynthesizeResponse,
+)
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, WebSocket, WebSocketDisconnect, status
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.tts_job_repository import (
+    SQLAlchemyTTSJobRepository,
+)
+from packages.adapters.sqlalchemy_impl.voice_library_repository import SQLAlchemyVoiceLibraryRepository
+from packages.application.cosyvoice_service import CosyVoiceService
+from packages.application.tts_job.streaming_service import TTSStreamingService
+from packages.application.tts_job.use_cases import (
+    CreateTTSJobUseCase,
+    DeleteTTSJobUseCase,
+    GetTTSJobStatusUseCase,
+    GetTTSJobUseCase,
+    ListTTSJobsUseCase,
+    TTSJobNotFoundError,
+)
+from packages.application.tts_job.workflow import TTSWorkflowService
+from packages.application.voice_library.commands import CreateVoiceLibraryCommand
+from packages.application.voice_library.use_cases import (
+    CreateVoiceLibraryUseCase,
+    QuotaExceededError,
+)
+from packages.ports.user_repository import UserRepository
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _get_repository(session: Session = Depends(get_db_session)) -> SQLAlchemyTTSJobRepository:
+    return SQLAlchemyTTSJobRepository(session)
+
+
+def _to_response(job) -> TTSJobResponse:
+    return TTSJobResponse(
+        id=job.id,
+        user_id=job.user_id,
+        input_text=job.input_text,
+        voice_id=job.voice_id,
+        voice_model=job.voice_model,
+        project_id=job.project_id,
+        voice_clone_profile_id=job.voice_clone_profile_id,
+        status=job.status,
+        output_audio_url=job.output_audio_url,
+        output_audio_key=job.output_audio_key,
+        duration=job.duration,
+        file_size=job.file_size,
+        sample_rate=job.sample_rate,
+        format=job.format,
+        error_message=job.error_message,
+        retry_count=job.retry_count,
+        max_retries=job.max_retries,
+        metadata=job.metadata,
+        started_at=job.started_at,
+        completed_at=job.completed_at,
+        created_at=job.created_at,
+        updated_at=job.updated_at,
+    )
+
+
+@router.post("/synthesize", response_model=TTSSynthesizeResponse, status_code=status.HTTP_201_CREATED)
+def synthesize(
+    request: TTSSynthesizeRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    repository: SQLAlchemyTTSJobRepository = Depends(_get_repository),
+    cosyvoice_service: CosyVoiceService = Depends(get_cosyvoice_service),
+    voice_clone_repo=Depends(get_voice_clone_profile_repository),
+) -> TTSSynthesizeResponse:
+    """发起 TTS 合成任务。
+
+    创建 TTS 任务 → 提交 CosyVoice 合成 → 触发 Celery 异步轮询。
+    与音色克隆接口保持一致：CosyVoice 失败时不抛 500，而是返回 201 + failed 状态任务记录。
+    """
+    user_id = authenticated_user.user.id
+
+    # 校验 voice_clone_profile_id 归属（防止越权使用他人克隆音色）
+    if request.voice_clone_profile_id:
+        profile = voice_clone_repo.get(request.voice_clone_profile_id)
+        if profile is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Voice clone profile not found",
+            )
+        if profile.user_id != user_id:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Access denied to voice clone profile",
+            )
+
+    use_case = CreateTTSJobUseCase(repository)
+    job = use_case.execute(
+        user_id=user_id,
+        input_text=request.text,
+        voice_id=request.voice_id,
+        voice_model=request.voice_model,
+        voice_clone_profile_id=request.voice_clone_profile_id,
+        metadata=request.metadata_,
+    )
+
+    # 提交 CosyVoice 合成任务
+    workflow = TTSWorkflowService(
+        repository=repository,
+        cosyvoice_service=cosyvoice_service,
+    )
+
+    try:
+        job = workflow.start_synthesis(job.id)
+    except Exception as e:
+        # 兜底：workflow 内部已捕获 CosyVoiceError / ValueError，
+        # 但 DB 异常、网络异常等意外错误可能逃逸。
+        # 与音色克隆接口保持一致：标记 failed，返回 201，不抛 500。
+        logger.error(f"TTS 合成异常: job_id={job.id}, error={e}", exc_info=True)
+        try:
+            job = workflow.process_synthesis_failure(job.id, str(e))
+        except Exception as inner_e:
+            logger.error(f"标记 TTS job 失败时出错: job_id={job.id}, error={inner_e}")
+
+    # 若任务处于 processing 状态（异步模式），触发 Celery 后台轮询
+    if job.status.value == "processing":
+        # 分段合成任务 vs 普通单段任务
+        segment_task_ids = (job.metadata or {}).get("segment_task_ids", [])
+        is_segment = len(segment_task_ids) > 0
+
+        try:
+            if is_segment:
+                from worker_app.tasks import process_tts_segment_synthesis
+
+                process_tts_segment_synthesis.delay(job.id)
+            else:
+                from worker_app.tasks import process_tts_synthesis
+
+                process_tts_synthesis.delay(job.id)
+        except Exception as e:
+            # Celery 调度失败，标记 job 为 failed
+            try:
+                workflow.process_synthesis_failure(job.id, f"Celery 任务调度失败: {e}")
+            except Exception as inner_e:
+                logger.error(f"Celery 调度后标记失败时出错: job_id={job.id}, error={inner_e}")
+
+    return TTSSynthesizeResponse(
+        job_id=job.id,
+        status=job.status,
+        message="合成任务已创建",
+    )
+
+
+@router.get("/jobs", response_model=ListTTSJobResponse)
+def list_tts_jobs(
+    page: int = Query(default=1, ge=1, description="页码"),
+    page_size: int = Query(default=20, ge=1, le=100, description="每页数量"),
+    status_filter: Optional[str] = Query(None, alias="status"),
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    repository: SQLAlchemyTTSJobRepository = Depends(_get_repository),
+) -> ListTTSJobResponse:
+    """列出用户的 TTS 合成任务。"""
+    user_id = authenticated_user.user.id
+    use_case = ListTTSJobsUseCase(repository)
+    skip = (page - 1) * page_size
+    items, total = use_case.execute(user_id, status=status_filter, skip=skip, limit=page_size)
+    return ListTTSJobResponse(
+        items=[_to_response(j) for j in items],
+        total=total,
+        page=page,
+        page_size=page_size,
+    )
+
+
+@router.get("/jobs/{job_id}", response_model=TTSJobResponse)
+def get_tts_job(
+    job_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    repository: SQLAlchemyTTSJobRepository = Depends(_get_repository),
+) -> TTSJobResponse:
+    """获取 TTS 任务详情。"""
+    user_id = authenticated_user.user.id
+    use_case = GetTTSJobUseCase(repository)
+    try:
+        job = use_case.execute(job_id, user_id)
+    except TTSJobNotFoundError:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="TTS job not found")
+    return _to_response(job)
+
+
+@router.get("/jobs/{job_id}/status", response_model=TTSStatusResponse)
+def get_tts_job_status(
+    job_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    repository: SQLAlchemyTTSJobRepository = Depends(_get_repository),
+) -> TTSStatusResponse:
+    """查询 TTS 合成状态（用于前端轮询）。"""
+    user_id = authenticated_user.user.id
+    use_case = GetTTSJobStatusUseCase(repository)
+    try:
+        job = use_case.execute(job_id, user_id)
+    except TTSJobNotFoundError:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="TTS job not found")
+    return TTSStatusResponse(
+        id=job.id,
+        status=job.status,
+        output_audio_url=job.output_audio_url,
+        error_message=job.error_message,
+        duration=job.duration,
+        retry_count=job.retry_count,
+        created_at=job.created_at,
+        updated_at=job.updated_at,
+    )
+
+
+@router.delete("/jobs/{job_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
+def delete_tts_job(
+    job_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    repository: SQLAlchemyTTSJobRepository = Depends(_get_repository),
+) -> Response:
+    """删除 TTS 合成任务。"""
+    user_id = authenticated_user.user.id
+    use_case = DeleteTTSJobUseCase(repository)
+    deleted = use_case.execute(job_id, user_id)
+    if not deleted:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="TTS job not found")
+    return Response(status_code=204)
+
+
+@router.post(
+    "/jobs/{job_id}/save-to-library",
+    response_model=SaveToLibraryResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+def save_tts_job_to_library(
+    job_id: str,
+    request: SaveToLibraryRequest = SaveToLibraryRequest(),
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    tts_repository: SQLAlchemyTTSJobRepository = Depends(_get_repository),
+    voice_library_repository: SQLAlchemyVoiceLibraryRepository = Depends(get_voice_library_repository),
+    user_repository: UserRepository = Depends(get_user_repository),
+) -> SaveToLibraryResponse:
+    """将已完成的 TTS 合成结果保存到配音库。
+
+    自动携带音色名、时长、语速等元信息。
+    """
+    user_id = authenticated_user.user.id
+
+    # 获取 TTS job
+    get_use_case = GetTTSJobUseCase(tts_repository)
+    try:
+        job = get_use_case.execute(job_id, user_id)
+    except TTSJobNotFoundError:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="TTS job not found")
+
+    # 校验已完成
+    if not job.is_completed:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="TTS job is not completed yet",
+        )
+
+    # 构建配音素材名称
+    name = request.name or f"TTS-{job.id[:8]}"
+
+    # 构建元信息
+    metadata_ = {
+        "source": "tts_job",
+        "tts_job_id": job.id,
+        "format": job.format,
+        "sample_rate": job.sample_rate,
+    }
+    if job.metadata:
+        # 保留原始 job 的有用元信息
+        for key in ("speed", "language"):
+            if key in job.metadata:
+                metadata_[key] = job.metadata[key]
+
+    # 获取用户套餐（用于配额检查）
+    user = user_repository.find_by_id(user_id)
+    plan_name = getattr(user, "subscription_plan", "free") if user else "free"
+
+    # 构建命令并执行
+    command = CreateVoiceLibraryCommand(
+        user_id=user_id,
+        name=name,
+        text=job.input_text,
+        voice_provider="cosyvoice",
+        voice_id=job.voice_id,
+        voice_name=job.voice_model or "",
+        audio_url=job.output_audio_url,
+        duration=job.duration,
+        file_size=job.file_size,
+        status="completed",
+        project_id=job.project_id or "",
+        tags=[],
+        metadata_=metadata_,
+    )
+
+    use_case = CreateVoiceLibraryUseCase(voice_library_repository)
+    try:
+        item = use_case.execute(command, plan_name=plan_name or "free")
+    except QuotaExceededError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail=f"配音库配额已满（{exc.used}/{exc.limit}），请升级套餐",
+        )
+
+    return SaveToLibraryResponse(
+        id=item.id,
+        name=item.name,
+        audio_url=item.audio_url,
+        duration=item.duration,
+        voice_id=item.voice_id,
+        voice_name=item.voice_name,
+        status=item.status,
+    )
+
+
+@router.websocket("/ws/tts/stream")
+async def tts_websocket_stream(
+    websocket: WebSocket,
+    cosyvoice_service: CosyVoiceService = Depends(get_cosyvoice_service),
+) -> None:
+    """WebSocket 流式 TTS 合成。
+
+    协议：
+    1. 客户端发送 JSON 文本帧: {"text": "...", "voice_id": "...", ...}
+    2. 服务端发送 JSON 状态帧 + 二进制音频帧
+    3. 完成时发送 JSON 结束帧
+    """
+    await websocket.accept()
+    try:
+        message = await websocket.receive_json()
+        params = {
+            "text": message.get("text", ""),
+            "voice_id": message.get("voice_id", ""),
+            "sample_rate": message.get("sample_rate", 0),
+            "format": message.get("format", "mp3"),
+            "speed": message.get("speed", 1.0),
+        }
+        streaming_service = TTSStreamingService(cosyvoice_service)
+        await streaming_service.synthesize_and_stream(websocket, params)
+    except WebSocketDisconnect:
+        logger.info("WebSocket 客户端断开连接")
+    except Exception as e:
+        logger.error(f"WebSocket 流式合成异常: {e}", exc_info=True)
+        try:
+            await websocket.send_json({"type": "error", "message": f"服务异常: {e}"})
+        except Exception:
+            pass

apps/api/app/api/routes/upload.py

@@ -8,6 +8,7 @@ from app.core.celery_app import celery_app
 from app.core.storage import OSSStorageService, get_storage_service
 from app.dependencies import (
     get_asset_library_repository,
+    get_asset_repository,
     get_ingest_job_repository,
     get_project_repository,
 )
@@ -53,8 +54,8 @@ ALLOWED_MIME_TYPES = frozenset(
         "image/gif",
         "image/webp",
         "image/bmp",
-        "image/svg+xml",
         "image/tiff",
+        "image/svg+xml",
     }
 )
 
@@ -99,6 +100,7 @@ def _submit_ingest_job(
     library_id: str,
     storage_key: str,
     ingest_job_repository: Any,
+    file_hash: str = "",
 ) -> Any:
     use_case = SubmitIngestJobUseCase(ingest_job_repository)
     job = use_case.execute(
@@ -106,6 +108,7 @@ def _submit_ingest_job(
             project_id=project_id,
             library_id=library_id,
             storage_key=storage_key,
+            file_hash=file_hash,
         )
     )
     celery_app.send_task("worker.ingest_asset", args=[job.id])
@@ -176,6 +179,7 @@ async def complete_direct_upload(
     ingest_job_repository: Any = Depends(get_ingest_job_repository),
     project_repository: Any = Depends(get_project_repository),
     asset_library_repository: Any = Depends(get_asset_library_repository),
+    asset_repository: Any = Depends(get_asset_repository),
     storage_service: OSSStorageService = Depends(get_storage_service),
 ) -> DirectUploadCompleteResponse:
     """确认浏览器直传完成并创建导入任务。"""
@@ -199,11 +203,32 @@ async def complete_direct_upload(
     if not file_exists:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Uploaded file not found")
 
+    # ── 素材去重检测：同素材库 + 同 file_hash 视为重复 ──
+    if request.file_hash:
+        existing = asset_repository.find_by_library_and_file_hash(
+            library_id=request.library_id,
+            file_hash=request.file_hash,
+        )
+        if existing is not None:
+            logger.info(
+                "素材去重命中: library=%s hash=%s existing_asset=%s",
+                request.library_id,
+                request.file_hash,
+                existing.id,
+            )
+            return DirectUploadCompleteResponse(
+                storage_key=normalized_key,
+                ingest_job_id="",
+                duplicated=True,
+                asset_id=existing.id,
+            )
+
     job = _submit_ingest_job(
         project_id=request.project_id,
         library_id=request.library_id,
         storage_key=normalized_key,
         ingest_job_repository=ingest_job_repository,
+        file_hash=request.file_hash,
     )
     return DirectUploadCompleteResponse(storage_key=normalized_key, ingest_job_id=job.id)
 
@@ -218,15 +243,38 @@ async def upload_asset(
     project_id: str = Form(..., min_length=1, description="项目 ID"),
     library_id: str = Form(..., min_length=1, description="素材库 ID"),
     file: UploadFile = File(..., description="要上传的文件（视频、音频、图片等）"),
+    file_hash: str = Form(default="", description="文件 MD5 哈希，用于去重检测"),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     ingest_job_repository: Any = Depends(get_ingest_job_repository),
     project_repository: Any = Depends(get_project_repository),
     asset_library_repository: Any = Depends(get_asset_library_repository),
+    asset_repository: Any = Depends(get_asset_repository),
     storage_service: OSSStorageService = Depends(get_storage_service),
 ) -> UploadAssetResponse:
     """上传素材文件并触发导入流水线。"""
     _require_project_and_library(project_id, library_id, project_repository, asset_library_repository)
 
+    # ── 素材去重检测：上传前检查同素材库 + 同 file_hash ──
+    if file_hash:
+        existing = asset_repository.find_by_library_and_file_hash(
+            library_id=library_id,
+            file_hash=file_hash,
+        )
+        if existing is not None:
+            logger.info(
+                "素材去重命中(multipart): library=%s hash=%s existing_asset=%s",
+                library_id,
+                file_hash,
+                existing.id,
+            )
+            return UploadAssetResponse(
+                storage_key=existing.storage_key,
+                ingest_job_id="",
+                url="",
+                duplicated=True,
+                asset_id=existing.id,
+            )
+
     # P2-5: 服务端验证 MIME 类型
     validated_content_type = _validate_mime_type(file.content_type)
 
@@ -255,6 +303,7 @@ async def upload_asset(
         library_id=library_id,
         storage_key=storage_key,
         ingest_job_repository=ingest_job_repository,
+        file_hash=file_hash,
     )
 
     return UploadAssetResponse(

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

@@ -0,0 +1,227 @@
+"""音色克隆 API 路由。"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_cosyvoice_service, get_voice_clone_profile_repository
+from app.schemas.voice_clone import (
+    CreateVoiceCloneRequest,
+    ListVoiceCloneResponse,
+    VoiceCloneProfileResponse,
+    VoiceCloneStatusResponse,
+)
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+
+from packages.adapters.sqlalchemy_impl.voice_clone_profile_repository import (
+    SQLAlchemyVoiceCloneProfileRepository,
+)
+from packages.application.cosyvoice_service import CosyVoiceService
+from packages.application.voice_clone.use_cases import (
+    DeleteVoiceCloneUseCase,
+    GetVoiceCloneStatusUseCase,
+    GetVoiceCloneUseCase,
+    ListVoiceClonesUseCase,
+    VoiceCloneNotFoundError,
+    VoiceCloneNotRetryableError,
+)
+from packages.application.voice_clone.workflow import (
+    VoiceCloneWorkflowError,
+    VoiceCloneWorkflowService,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _to_response(profile) -> VoiceCloneProfileResponse:
+    return VoiceCloneProfileResponse(
+        id=profile.id,
+        user_id=profile.user_id,
+        name=profile.name,
+        description=profile.description,
+        source_audio_url=profile.source_audio_url,
+        voice_id=profile.voice_id,
+        voice_model=profile.voice_model,
+        language=profile.language,
+        gender=profile.gender,
+        status=profile.status,
+        error_message=profile.error_message,
+        retry_count=profile.retry_count,
+        max_retries=profile.max_retries,
+        metadata=profile.metadata,
+        created_at=profile.created_at,
+        updated_at=profile.updated_at,
+    )
+
+
+def _get_workflow_service(
+    repository: SQLAlchemyVoiceCloneProfileRepository = Depends(get_voice_clone_profile_repository),
+    cosyvoice_service: CosyVoiceService = Depends(get_cosyvoice_service),
+) -> VoiceCloneWorkflowService:
+    return VoiceCloneWorkflowService(repository=repository, cosyvoice_service=cosyvoice_service)
+
+
+@router.post(
+    "",
+    response_model=VoiceCloneProfileResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+def create_voice_clone(
+    request: CreateVoiceCloneRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    workflow: VoiceCloneWorkflowService = Depends(_get_workflow_service),
+) -> VoiceCloneProfileResponse:
+    """创建音色克隆任务。
+
+    创建 VoiceCloneProfile → 提交 CosyVoice 克隆任务 → 触发 Celery 异步轮询。
+    如果有 source_audio_url，状态会变为 processing；否则保持 pending。
+    """
+    user_id = authenticated_user.user.id
+    profile = workflow.start_clone(
+        user_id=user_id,
+        name=request.name,
+        description=request.description,
+        source_audio_url=request.source_audio_url,
+        voice_model=request.voice_model,
+        language=request.language,
+        gender=request.gender,
+        max_retries=request.max_retries,
+        metadata=request.metadata_,
+    )
+
+    # 如果 profile 处于 processing 且有 task_id，触发 Celery 异步轮询
+    task_id = (profile.metadata or {}).get("cosyvoice_task_id", "")
+    if profile.status == "processing" and task_id:
+        try:
+            from worker_app.tasks import process_voice_clone
+
+            process_voice_clone.delay(profile.id)
+            logger.info(f"Celery task dispatched for voice clone {profile.id}")
+        except Exception as e:
+            logger.error(f"Failed to dispatch Celery task: {e}")
+            # P2-3: Celery 调度失败时标记 profile 为 failed，避免永久卡在 processing
+            try:
+                workflow.process_clone_failure(profile.id, f"Celery 任务调度失败: {e}")
+            except Exception as inner_e:
+                logger.error(f"Failed to mark profile as failed after dispatch error: {inner_e}")
+
+    return _to_response(profile)
+
+
+@router.get("", response_model=ListVoiceCloneResponse)
+def list_voice_clones(
+    status_filter: Optional[str] = Query(None, alias="status"),
+    skip: int = Query(0, ge=0),
+    limit: int = Query(50, ge=1, le=200),
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    repository: SQLAlchemyVoiceCloneProfileRepository = Depends(get_voice_clone_profile_repository),
+) -> ListVoiceCloneResponse:
+    """获取用户的音色克隆列表。"""
+    user_id = authenticated_user.user.id
+    use_case = ListVoiceClonesUseCase(repository)
+    items, total = use_case.execute(user_id, status=status_filter, skip=skip, limit=limit)
+    return ListVoiceCloneResponse(
+        items=[_to_response(p) for p in items],
+        total=total,
+    )
+
+
+@router.get("/{clone_id}", response_model=VoiceCloneProfileResponse)
+def get_voice_clone(
+    clone_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    repository: SQLAlchemyVoiceCloneProfileRepository = Depends(get_voice_clone_profile_repository),
+) -> VoiceCloneProfileResponse:
+    """获取音色克隆详情。"""
+    user_id = authenticated_user.user.id
+    use_case = GetVoiceCloneUseCase(repository)
+    try:
+        profile = use_case.execute(clone_id, user_id)
+    except VoiceCloneNotFoundError:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice clone not found")
+    return _to_response(profile)
+
+
+@router.get("/{clone_id}/status", response_model=VoiceCloneStatusResponse)
+def get_voice_clone_status(
+    clone_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    repository: SQLAlchemyVoiceCloneProfileRepository = Depends(get_voice_clone_profile_repository),
+) -> VoiceCloneStatusResponse:
+    """查询音色克隆状态（用于前端轮询）。"""
+    user_id = authenticated_user.user.id
+    use_case = GetVoiceCloneStatusUseCase(repository)
+    try:
+        profile = use_case.execute(clone_id, user_id)
+    except VoiceCloneNotFoundError:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice clone not found")
+    return VoiceCloneStatusResponse(
+        id=profile.id,
+        status=profile.status,
+        error_message=profile.error_message,
+        voice_id=profile.voice_id,
+        retry_count=profile.retry_count,
+    )
+
+
+@router.delete(
+    "/{clone_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    response_model=None,
+)
+def delete_voice_clone(
+    clone_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    repository: SQLAlchemyVoiceCloneProfileRepository = Depends(get_voice_clone_profile_repository),
+) -> Response:
+    """删除音色克隆档案。"""
+    user_id = authenticated_user.user.id
+    use_case = DeleteVoiceCloneUseCase(repository)
+    deleted = use_case.execute(clone_id, user_id)
+    if not deleted:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice clone not found")
+    return Response(status_code=204)
+
+
+@router.post("/{clone_id}/retry", response_model=VoiceCloneProfileResponse)
+def retry_voice_clone(
+    clone_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    workflow: VoiceCloneWorkflowService = Depends(_get_workflow_service),
+) -> VoiceCloneProfileResponse:
+    """重试失败的音色克隆。
+
+    仅当状态为 failed 时可重试，重试后重新提交 CosyVoice 克隆任务。
+    """
+    user_id = authenticated_user.user.id
+    try:
+        profile = workflow.retry_clone(clone_id, user_id)
+    except VoiceCloneNotFoundError:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice clone not found")
+    except VoiceCloneNotRetryableError:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Voice clone is not retryable (only failed clones can be retried)",
+        )
+
+    # 如果 profile 处于 processing 且有 task_id，触发 Celery 异步轮询
+    task_id = (profile.metadata or {}).get("cosyvoice_task_id", "")
+    if profile.status == "processing" and task_id:
+        try:
+            from worker_app.tasks import process_voice_clone
+
+            process_voice_clone.delay(profile.id)
+            logger.info(f"Celery task dispatched for voice clone retry {profile.id}")
+        except Exception as e:
+            logger.error(f"Failed to dispatch Celery task: {e}")
+            # P2-3: Celery 调度失败时标记 profile 为 failed，避免永久卡在 processing
+            try:
+                workflow.process_clone_failure(profile.id, f"Celery 任务调度失败: {e}")
+            except Exception as inner_e:
+                logger.error(f"Failed to mark profile as failed after dispatch error: {inner_e}")
+
+    return _to_response(profile)

apps/api/app/api/routes/voices.py

@@ -1,11 +1,20 @@
-"""Voice library CRUD routes."""
+"""Voice library CRUD routes — Phase 3 增强版.
+
+支持预置音色和克隆音色的统一列表。
+"""
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import Literal, Optional
 
 from app.auth import AuthenticatedUser, get_current_user
 from app.dependencies import get_db_session, get_user_repository
+from app.schemas.voice import (
+    PresetVoiceItemResponse,
+    PresetVoiceListResponse,
+    UnifiedVoiceItemResponse,
+    UnifiedVoiceListResponse,
+)
 from app.schemas.voice_library import (
     CreateVoiceLibraryRequest,
     ListVoiceLibraryResponse,
@@ -15,6 +24,7 @@ from app.schemas.voice_library import (
 from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
 from sqlalchemy.orm import Session
 
+from packages.adapters.sqlalchemy_impl.voice_clone_profile_repository import SQLAlchemyVoiceCloneProfileRepository
 from packages.adapters.sqlalchemy_impl.voice_library_repository import SQLAlchemyVoiceLibraryRepository
 from packages.application.voice_library.commands import CreateVoiceLibraryCommand, UpdateVoiceLibraryCommand
 from packages.application.voice_library.use_cases import (
@@ -26,6 +36,7 @@ from packages.application.voice_library.use_cases import (
     QuotaExceededError,
     UpdateVoiceLibraryUseCase,
 )
+from packages.domain.preset_voices import PRESET_VOICES
 from packages.ports.user_repository import UserRepository
 
 router = APIRouter()
@@ -35,6 +46,10 @@ def _get_voice_repository(session: Session = Depends(get_db_session)) -> SQLAlch
     return SQLAlchemyVoiceLibraryRepository(session)
 
 
+def _get_clone_profile_repository(session: Session = Depends(get_db_session)) -> SQLAlchemyVoiceCloneProfileRepository:
+    return SQLAlchemyVoiceCloneProfileRepository(session)
+
+
 def _to_response(item) -> VoiceLibraryItemResponse:
     return VoiceLibraryItemResponse(
         id=item.id,
@@ -55,6 +70,54 @@ def _to_response(item) -> VoiceLibraryItemResponse:
     )
 
 
+def _to_unified_response(item, profile_id_map: dict | None = None) -> UnifiedVoiceItemResponse:
+    """将数据库音色转换为统一响应格式。
+
+    Args:
+        item: VoiceLibraryItem
+        profile_id_map: voice_id → profile_id 映射，用于填充 voice_clone_profile_id
+    """
+    profile_id = None
+    if profile_id_map and item.voice_id:
+        profile_id = profile_id_map.get(item.voice_id)
+    return UnifiedVoiceItemResponse(
+        id=item.id,
+        type="clone",
+        name=item.name,
+        description=item.text,
+        gender="unknown",
+        language="zh-CN",
+        voice_id=item.voice_id,
+        voice_provider=item.voice_provider or "cosyvoice",
+        audio_url=item.audio_url,
+        duration=item.duration,
+        file_size=item.file_size,
+        status=item.status,
+        tags=item.tags,
+        user_id=item.user_id,
+        project_id=item.project_id,
+        voice_clone_profile_id=profile_id,
+        created_at=item.created_at,
+        updated_at=item.updated_at,
+    )
+
+
+def _preset_to_unified_response(preset) -> UnifiedVoiceItemResponse:
+    """将预置音色转换为统一响应格式。"""
+    return UnifiedVoiceItemResponse(
+        id=preset.voice_id,
+        type="preset",
+        name=preset.name,
+        description=preset.description,
+        gender=preset.gender,
+        language=preset.language,
+        voice_id=preset.voice_id,
+        voice_provider="cosyvoice",
+        preview_url=preset.preview_url,
+        tags=preset.tags or [],
+    )
+
+
 def _get_user_plan(user_id: str, user_repository: UserRepository) -> str:
     user = user_repository.find_by_id(user_id)
     if user is None:
@@ -62,18 +125,113 @@ def _get_user_plan(user_id: str, user_repository: UserRepository) -> str:
     return getattr(user, "subscription_plan", "free") or "free"
 
 
-@router.get("", response_model=ListVoiceLibraryResponse)
-def list_voices(
+# ==================== 统一配音列表（预置 + 克隆）====================
+
+
+@router.get("", response_model=UnifiedVoiceListResponse)
+def list_voices_unified(
+    type: Optional[Literal["preset", "clone"]] = Query(
+        None,
+        description="音色类型过滤：preset=仅预置，clone=仅克隆，不传=全部",
+    ),
+    status_filter: Optional[str] = Query(None, alias="status"),
+    skip: int = Query(0, ge=0),
+    limit: int = Query(50, ge=1, le=200),
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    voice_repository: SQLAlchemyVoiceLibraryRepository = Depends(_get_voice_repository),
+    clone_profile_repository: SQLAlchemyVoiceCloneProfileRepository = Depends(_get_clone_profile_repository),
+) -> UnifiedVoiceListResponse:
+    """获取配音列表（预置音色 + 用户克隆音色）。
+
+    - 不传 type：返回预置音色 + 用户克隆音色，预置音色在前
+    - type=preset：仅返回预置音色
+    - type=clone：仅返回用户克隆音色
+    """
+    user_id = authenticated_user.user.id
+    items: list[UnifiedVoiceItemResponse] = []
+    preset_count = 0
+    clone_count = 0
+
+    has_preset = type is None or type == "preset"
+    has_clone = type is None or type == "clone"
+
+    # 获取预置音色
+    if has_preset:
+        preset_items = [_preset_to_unified_response(p) for p in PRESET_VOICES]
+        preset_count = len(preset_items)
+
+    # 获取克隆音色
+    if has_clone:
+        use_case = ListVoiceLibraryUseCase(voice_repository)
+        clone_items_raw, clone_count = use_case.execute(user_id, status=status_filter, skip=skip, limit=limit)
+        # 批量查询 voice_id → profile_id 映射，填充 voice_clone_profile_id
+        voice_ids = [i.voice_id for i in clone_items_raw if i.voice_id]
+        profile_id_map = clone_profile_repository.find_profile_ids_by_voice_ids(voice_ids) if voice_ids else {}
+        clone_items = [_to_unified_response(i, profile_id_map) for i in clone_items_raw]
+
+    # 组装结果
+    if type == "preset":
+        items = preset_items[skip : skip + limit]
+        total = preset_count
+    elif type == "clone":
+        items = clone_items
+        total = clone_count
+    else:
+        # 全量模式：预置在前，克隆补位
+        all_items = preset_items + clone_items
+        total = preset_count + clone_count
+        items = all_items[skip : skip + limit]
+
+    return UnifiedVoiceListResponse(
+        items=items,
+        total=total,
+        preset_count=preset_count if has_preset else 0,
+        clone_count=clone_count if has_clone else 0,
+    )
+
+
+# ==================== 预置音色专用端点 ====================
+
+
+@router.get("/presets", response_model=PresetVoiceListResponse)
+def list_preset_voices() -> PresetVoiceListResponse:
+    """获取预置音色列表。
+
+    不需要认证，返回所有系统预置的 CosyVoice 音色。
+    """
+    items = [
+        PresetVoiceItemResponse(
+            voice_id=p.voice_id,
+            name=p.name,
+            description=p.description,
+            gender=p.gender,
+            language=p.language,
+            preview_url=p.preview_url,
+            tags=p.tags or [],
+        )
+        for p in PRESET_VOICES
+    ]
+    return PresetVoiceListResponse(items=items, total=len(items))
+
+
+# ==================== 原有 CRUD 端点（保持向后兼容）====================
+
+
+@router.get("/legacy", response_model=ListVoiceLibraryResponse)
+def list_voices_legacy(
     status_filter: Optional[str] = Query(None, alias="status"),
     skip: int = Query(0, ge=0),
     limit: int = Query(50, ge=1, le=200),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     voice_repository: SQLAlchemyVoiceLibraryRepository = Depends(_get_voice_repository),
 ) -> ListVoiceLibraryResponse:
+    """原有配音列表接口（仅返回用户克隆音色）。
+
+    保留用于向后兼容，新客户端请使用 GET /api/v1/voices。
+    """
     user_id = authenticated_user.user.id
     use_case = ListVoiceLibraryUseCase(voice_repository)
-    items = use_case.execute(user_id, status=status_filter, skip=skip, limit=limit)
-    total = voice_repository.count_by_user(user_id)
+    items, total = use_case.execute(user_id, status=status_filter, skip=skip, limit=limit)
     return ListVoiceLibraryResponse(
         items=[_to_response(i) for i in items],
         total=total,
@@ -158,7 +316,7 @@ def update_voice(
     return _to_response(item)
 
 
-@router.delete("/{voice_id}", status_code=status.HTTP_204_NO_CONTENT, response_class=Response)
+@router.delete("/{voice_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
 def delete_voice(
     voice_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),

apps/api/app/auth.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 from dataclasses import dataclass
 
 import jwt
@@ -23,6 +24,35 @@ class AuthenticatedUser:
     token_type: str | None = None
 
 
+def _get_redis_client():
+    """获取 Redis 客户端用于 JWT 黑名单"""
+    import redis as redis_lib
+
+    return redis_lib.from_url(settings.REDIS_URL, decode_responses=True)
+
+
+def _token_fingerprint(token: str) -> str:
+    """计算 token 的哈希指纹"""
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+def blacklist_token(token: str, exp: int) -> None:
+    """将 token 加入黑名单，TTL 为 token 剩余有效期"""
+    import time
+
+    redis_client = _get_redis_client()
+    key = f"jwt:blacklist:{_token_fingerprint(token)}"
+    ttl = max(exp - int(time.time()), 1)
+    redis_client.setex(key, ttl, "revoked")
+
+
+def is_token_blacklisted(token: str) -> bool:
+    """检查 token 是否在黑名单中"""
+    redis_client = _get_redis_client()
+    key = f"jwt:blacklist:{_token_fingerprint(token)}"
+    return redis_client.exists(key) > 0
+
+
 async def get_current_user(
     credentials: HTTPAuthorizationCredentials | None = Depends(bearer_scheme),
     user_repository: UserRepository = Depends(get_user_repository),
@@ -56,6 +86,11 @@ def _decode_user_token(token: str) -> dict:
 
     if payload.get("type") not in {"user_auth", "access"}:
         raise _unauthorized("Invalid token type")
+
+    # 检查 token 是否在黑名单中
+    if is_token_blacklisted(token):
+        raise _unauthorized("Token has been revoked")
+
     return payload
 
 

apps/api/app/core/database.py

@@ -1,49 +0,0 @@
-"""Database session management and engine configuration.
-
-统一使用 app.config 中的数据库配置，移除重复的 DatabaseSettings。
-"""
-
-from contextlib import contextmanager
-from typing import Generator
-
-from app.config import settings
-from sqlalchemy import create_engine
-from sqlalchemy.orm import Session, sessionmaker
-
-engine = create_engine(
-    settings.database_url,
-    pool_size=settings.DATABASE_POOL_SIZE,
-    max_overflow=settings.DATABASE_MAX_OVERFLOW,
-    pool_timeout=settings.DATABASE_POOL_TIMEOUT,
-    pool_recycle=settings.DATABASE_POOL_RECYCLE,
-)
-
-SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
-
-
-def get_db() -> Generator[Session, None, None]:
-    """Dependency for getting database sessions."""
-    db = SessionLocal()
-    try:
-        yield db
-    finally:
-        db.close()
-
-
-@contextmanager
-def get_db_context() -> Generator[Session, None, None]:
-    """Context manager for database sessions.
-
-    Usage:
-        with get_db_context() as db:
-            db.query(Model).all()
-    """
-    db = SessionLocal()
-    try:
-        yield db
-        db.commit()
-    except Exception:
-        db.rollback()
-        raise
-    finally:
-        db.close()

apps/api/app/db.py

@@ -1,7 +1,4 @@
-from collections.abc import Generator
-
 from app.config import settings
-from sqlalchemy.orm import Session
 
 from packages.adapters.sqlalchemy_impl import (
     build_session_factory,
@@ -21,11 +18,3 @@ engine, SessionLocal = build_session_factory(
 assert_auto_create_schema_allowed(settings.ENVIRONMENT, settings.AUTO_CREATE_SCHEMA)
 if settings.AUTO_CREATE_SCHEMA:
     initialize_database(engine)
-
-
-def get_db() -> Generator[Session, None, None]:
-    db = SessionLocal()
-    try:
-        yield db
-    finally:
-        db.close()

apps/api/app/dependencies.py

@@ -34,14 +34,19 @@ from packages.adapters.sqlalchemy_impl.generation_task_repository import (
 from packages.adapters.sqlalchemy_impl.ingest_job_repository import (
     SQLAlchemyIngestJobRepository,
 )
+from packages.adapters.sqlalchemy_impl.job_repository import SQLAlchemyJobRepository
 from packages.adapters.sqlalchemy_impl.project_repository import (
     SQLAlchemyProjectRepository,
 )
 from packages.adapters.sqlalchemy_impl.session import build_session_factory
+from packages.adapters.sqlalchemy_impl.tag_repository import SQLAlchemyTagRepository
 from packages.adapters.sqlalchemy_impl.title_library_repository import (
     SQLAlchemyTitleLibraryRepository,
 )
 from packages.adapters.sqlalchemy_impl.user_repository import SQLAlchemyUserRepository
+from packages.adapters.sqlalchemy_impl.voice_clone_profile_repository import (
+    SQLAlchemyVoiceCloneProfileRepository,
+)
 from packages.adapters.sqlalchemy_impl.voice_library_repository import (
     SQLAlchemyVoiceLibraryRepository,
 )
@@ -52,9 +57,12 @@ from packages.ports.duplication_repository import DuplicationRecordRepository
 from packages.ports.generated_video_repository import GeneratedVideoRepository
 from packages.ports.generation_task_repository import GenerationTaskRepository
 from packages.ports.ingest_job_repository import IngestJobRepository
+from packages.ports.job_repository import JobRepository
 from packages.ports.project_repository import ProjectRepository
+from packages.ports.tag_repository import TagRepository
 from packages.ports.title_library_repository import TitleLibraryRepository
 from packages.ports.user_repository import UserRepository
+from packages.ports.voice_clone_profile_repository import VoiceCloneProfileRepository
 from packages.ports.voice_library_repository import VoiceLibraryRepository
 
 _engine, _SessionLocal = build_session_factory(settings.DATABASE_URL)
@@ -104,6 +112,13 @@ def get_generation_task_repository(
     return SQLAlchemyGenerationTaskRepository(session)
 
 
+def get_job_repository(
+    session: Session = Depends(get_db_session),
+) -> SQLAlchemyJobRepository:
+    """Provide the SQLAlchemy job repository implementation."""
+    return SQLAlchemyJobRepository(session)
+
+
 def get_generated_video_repository(
     session: Session = Depends(get_db_session),
 ) -> SQLAlchemyGeneratedVideoRepository:
@@ -125,6 +140,13 @@ def get_project_repository(
     return SQLAlchemyProjectRepository(session)
 
 
+def get_tag_repository(
+    session: Session = Depends(get_db_session),
+) -> TagRepository:
+    """Provide the SQLAlchemy tag repository implementation."""
+    return SQLAlchemyTagRepository(session)
+
+
 def get_user_repository(
     session: Session = Depends(get_db_session),
 ) -> UserRepository:
@@ -169,3 +191,17 @@ def get_voice_library_repository(
 ) -> SQLAlchemyVoiceLibraryRepository:
     """Provide the SQLAlchemy voice library repository implementation."""
     return SQLAlchemyVoiceLibraryRepository(session)
+
+
+def get_voice_clone_profile_repository(
+    session: Session = Depends(get_db_session),
+) -> SQLAlchemyVoiceCloneProfileRepository:
+    """Provide the SQLAlchemy voice clone profile repository implementation."""
+    return SQLAlchemyVoiceCloneProfileRepository(session)
+
+
+def get_cosyvoice_service():
+    """Provide the CosyVoice service instance."""
+    from packages.application.cosyvoice_service import CosyVoiceService
+
+    return CosyVoiceService()

apps/api/app/middleware/auth.py

@@ -1,8 +1,8 @@
 """
 Authentication dependency compatibility layer.
 
-Canonical bearer-token parsing lives in app.auth. This module remains only so
-legacy imports have a safe target while workspace dependencies are rebuilt.
+Canonical bearer-token parsing lives in app.auth. This module re-exports
+common auth dependencies for backward compatibility.
 """
 
 from __future__ import annotations
@@ -10,7 +10,7 @@ from __future__ import annotations
 from app.auth import AuthenticatedUser
 from app.auth import get_current_user as get_authenticated_user
 from app.dependencies import get_user_repository
-from fastapi import Depends
+from fastapi import Depends, HTTPException
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 
 from packages.domain.entities import User

apps/api/app/middleware/exceptions.py

@@ -3,7 +3,6 @@
 """
 
 import logging
-import traceback
 
 from fastapi import Request, status
 from fastapi.exceptions import RequestValidationError

apps/api/app/middleware/logging.py

@@ -91,15 +91,27 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
 
 
 class RateLimitMiddleware(BaseHTTPMiddleware):
-    """基于 IP 的简单限流中间件"""
+    """基于 IP 的简单限流中间件
 
-    def __init__(self, app, max_requests: int = 100, window_seconds: int = 60):
+    Args:
+        app: ASGI 应用
+        max_requests: 窗口期内最大请求数
+        window_seconds: 时间窗口（秒）
+        paths: 限流的路径列表，None 表示所有路径
+    """
+
+    def __init__(self, app, max_requests: int = 100, window_seconds: int = 60, paths: list[str] | None = None):
         super().__init__(app)
         self.max_requests = max_requests
         self.window_seconds = window_seconds
+        self.paths = set(paths) if paths else None
         self.requests = {}  # {ip: [timestamps]}
 
     async def dispatch(self, request: Request, call_next):
+        # 如果配置了路径过滤，只对指定路径限流
+        if self.paths is not None and request.url.path not in self.paths:
+            return await call_next(request)
+
         # 获取客户端 IP
         client_ip = request.client.host
 

apps/api/app/middleware/prometheus_metrics.py

@@ -121,9 +121,19 @@ class PrometheusMetricsMiddleware(BaseHTTPMiddleware):
 
 
 async def metrics_endpoint(request: Request) -> PlainTextResponse:
-    """FastAPI endpoint that returns Prometheus metrics in text format."""
+    """FastAPI endpoint that returns Prometheus metrics in text format.
+
+    需要 Bearer Token 认证，Token 通过 METRICS_AUTH_TOKEN 环境变量配置。
+    """
     import os
 
+    # Bearer Token 认证
+    auth_token = os.getenv("METRICS_AUTH_TOKEN", "")
+    if auth_token:
+        auth_header = request.headers.get("Authorization", "")
+        if not auth_header.startswith("Bearer ") or auth_header[7:] != auth_token:
+            return PlainTextResponse(content="Unauthorized", status_code=401)
+
     version = os.getenv("APP_VERSION", "unknown")
     environment = os.getenv("APP_ENV", "unknown")
     APP_INFO.labels(version=version, environment=environment).set(1)

apps/api/app/middleware/versioning.py

@@ -2,8 +2,6 @@
 API 版本管理中间件
 """
 
-from datetime import datetime
-
 from fastapi import Request
 from starlette.middleware.base import BaseHTTPMiddleware
 

apps/api/app/schemas/asset.py

@@ -25,6 +25,12 @@ class UpdateAssetReviewRequest(BaseModel):
     review_status: str = Field(..., pattern="^(pending_review|approved|rejected)$")
 
 
+class UpdateAssetRequest(BaseModel):
+    name: str | None = Field(default=None, min_length=1, max_length=100)
+    metadata: dict[str, object] | None = None
+    tags: list[str] | None = None
+
+
 class AssetResponse(BaseModel):
     id: str
     project_id: str
@@ -34,6 +40,7 @@ class AssetResponse(BaseModel):
     mime_type: str
     metadata: dict[str, object]
     file_size: int
+    file_url: str | None = None
     thumbnail_url: str | None = None
     duration: float | None = None
     width: int | None = None
@@ -44,7 +51,24 @@ class AssetResponse(BaseModel):
     classification_status: str
     quality_score: float | None = None
     uploaded_by_user_id: str
+    tag_ids: list[str] = Field(default_factory=list)
+
+
+class BatchDeleteRequest(BaseModel):
+    """批量删除请求。"""
+
+    ids: list[str] = Field(..., min_length=1, max_length=100, description="要删除的素材 ID 列表")
+
+
+class BatchDeleteResponse(BaseModel):
+    """批量删除响应。"""
+
+    deleted_count: int = Field(..., ge=0, description="实际删除数量")
+    failed_ids: list[str] = Field(default_factory=list, description="删除失败的 ID 列表")
 
 
 class ListAssetsResponse(BaseModel):
     items: list[AssetResponse]
+    total: int = Field(default=0, ge=0)
+    skip: int = Field(default=0, ge=0)
+    limit: int = Field(default=100, ge=1)

apps/api/app/schemas/asset_library.py

@@ -18,3 +18,8 @@ class AssetLibraryResponse(BaseModel):
 
 class ListAssetLibrariesResponse(BaseModel):
     items: list[AssetLibraryResponse]
+
+
+class EnsureDefaultLibraryRequest(BaseModel):
+    project_id: str = Field(..., min_length=1)
+    kind: str = Field(..., pattern="^(video|voice|image)$")

apps/api/app/schemas/chunked_upload.py

@@ -36,9 +36,12 @@ class ChunkedUploadStatusResponse(BaseModel):
 class ChunkedUploadCompleteRequest(BaseModel):
     project_id: str = Field(..., min_length=1, description="Project ID")
     library_id: str = Field(..., min_length=1, description="Asset library ID")
+    file_hash: str = Field(default="", max_length=64, description="文件 MD5 哈希，用于去重检测")
 
 
 class ChunkedUploadCompleteResponse(BaseModel):
     storage_key: str = Field(..., description="Storage key")
     ingest_job_id: str = Field(..., description="Ingest job ID")
     url: str = Field(..., description="File URL")
+    duplicated: bool = Field(default=False, description="是否为重复素材（命中去重）")
+    asset_id: str = Field(default="", description="重复素材的 asset_id（duplicated=true 时返回）")

apps/api/app/schemas/generation_task.py

@@ -1,6 +1,15 @@
 from pydantic import BaseModel, Field, model_validator
 
 
+class ConfirmGenerationRequest(BaseModel):
+    """确认生成请求体 — 基于预览任务创建正式生成任务"""
+
+    output_width: int = Field(default=1080, description="输出视频宽度")
+    output_height: int = Field(default=1920, description="输出视频高度")
+    cover_url: str = Field(default="", description="自定义封面图片 URL")
+    custom_title: str = Field(default="", description="自定义视频标题")
+
+
 class CreateGenerationTaskRequest(BaseModel):
     """创建生成任务请求。
 
@@ -19,6 +28,25 @@ class CreateGenerationTaskRequest(BaseModel):
     asset_ids: list[str] = Field(default_factory=list)
     title_ids: list[str] = Field(default_factory=list)
     voice_ids: list[str] = Field(default_factory=list)
+    # ── 来源剪辑计划 ──
+    source_edit_plan_id: str = ""
+    # ── 批量生成 ──
+    count: int = Field(default=1, ge=1, le=50, description="批量生成数量，默认1，最大50")
+    # ── 素材库自动匹配 ──
+    asset_select_mode: str = Field(
+        default="all",
+        description="素材选取模式：all=全部ready视频, random=随机选取, smart=智能匹配（按质量/时长评分）",
+    )
+    asset_select_count: int = Field(
+        default=0, ge=0, le=100, description="选取数量，0表示全部（仅 random/smart 模式有效）"
+    )
+    # ── 预览 / 确认生成 ──
+    is_preview: bool = Field(default=True, description="是否为预览任务")
+    source_task_id: str = Field(default="", description="来源预览任务 ID（确认生成时传入）")
+    output_width: int = Field(default=1280, description="输出视频宽度")
+    output_height: int = Field(default=720, description="输出视频高度")
+    cover_url: str = Field(default="", description="封面图片 URL")
+    custom_title: str = Field(default="", description="自定义视频标题")
 
     @model_validator(mode="after")
     def _check_at_least_one_mode(self) -> "CreateGenerationTaskRequest":
@@ -43,12 +71,28 @@ class GenerationTaskResponse(BaseModel):
     asset_ids: list[str] = Field(default_factory=list)
     title_ids: list[str] = Field(default_factory=list)
     voice_ids: list[str] = Field(default_factory=list)
+    source_edit_plan_id: str = ""
+    asset_select_mode: str = ""
+    batch_id: str = ""
+    is_preview: bool = True
+    source_task_id: str = ""
+    output_width: int = 1280
+    output_height: int = 720
+    cover_url: str = ""
+    custom_title: str = ""
     status: str
     progress: float
     result_count: int
     error_message: str
 
 
+class BatchGenerationTaskResponse(BaseModel):
+    """批量生成任务响应。"""
+
+    items: list[GenerationTaskResponse]
+    total: int
+
+
 class ListGenerationTasksResponse(BaseModel):
     """用户级生成任务列表响应（跨 project）。"""
 

apps/api/app/schemas/ingest_job.py

@@ -14,4 +14,4 @@ class IngestJobResponse(BaseModel):
     storage_key: str
     status: str
     error_message: str
-    result_asset_id: str
+    result_asset_id: str | None

apps/api/app/schemas/job.py

@@ -0,0 +1,109 @@
+"""Job API schemas — Phase 8 任务 2.10."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class CreateJobRequest(BaseModel):
+    """创建任务请求体。"""
+
+    project_id: str = Field(..., min_length=1, description="项目 ID")
+    job_type: str = Field(
+        ...,
+        description="任务类型: video_compose / render_edit_plan / asset_ingest / classification / voice_extraction / generation",
+    )
+    payload: dict[str, Any] = Field(default_factory=dict, description="任务输入参数")
+    source_id: str = Field(default="", description="关联的业务实体 ID（如 edit_plan_id）")
+    max_retries: int = Field(default=3, ge=0, le=10, description="最大重试次数")
+
+
+class UpdateProgressRequest(BaseModel):
+    """更新任务进度请求体。"""
+
+    progress: float = Field(..., ge=0.0, le=100.0, description="进度百分比")
+    current_stage: str = Field(default="", description="当前阶段描述")
+
+
+class CompleteJobRequest(BaseModel):
+    """完成任务请求体。"""
+
+    result: dict[str, Any] = Field(default_factory=dict, description="任务结果")
+
+
+class FailJobRequest(BaseModel):
+    """标记任务失败请求体。"""
+
+    error_message: str = Field(..., min_length=1, description="错误信息")
+
+
+class JobResponse(BaseModel):
+    """任务响应体。"""
+
+    id: str
+    project_id: str
+    job_type: str
+    status: str
+    progress: float
+    current_stage: str
+    payload: dict[str, Any]
+    result: dict[str, Any]
+    error_message: str
+    retry_count: int
+    max_retries: int
+    celery_task_id: str
+    source_id: str
+    created_by_user_id: str
+    is_retryable: bool
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class ListJobsResponse(BaseModel):
+    """任务列表响应体。"""
+
+    items: list[JobResponse]
+    total: int
+
+
+class JobStatisticsResponse(BaseModel):
+    """任务统计响应体。"""
+
+    project_id: str
+    total: int
+    pending: int
+    running: int
+    success: int
+    failed: int
+
+
+def job_to_response(job) -> JobResponse:
+    """将 Job 领域对象转换为 API 响应。"""
+    return JobResponse(
+        id=job.id,
+        project_id=job.project_id,
+        job_type=job.job_type.value if hasattr(job.job_type, "value") else str(job.job_type),
+        status=job.status.value if hasattr(job.status, "value") else str(job.status),
+        progress=job.progress,
+        current_stage=job.current_stage,
+        payload=job.payload,
+        result=job.result,
+        error_message=job.error_message,
+        retry_count=job.retry_count,
+        max_retries=job.max_retries,
+        celery_task_id=job.celery_task_id,
+        source_id=job.source_id,
+        created_by_user_id=job.created_by_user_id,
+        is_retryable=job.is_retryable,
+        started_at=job.started_at,
+        completed_at=job.completed_at,
+        created_at=job.created_at,
+        updated_at=job.updated_at,
+    )

apps/api/app/schemas/tag.py

@@ -0,0 +1,24 @@
+"""标签相关 Schema。"""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class CreateTagRequest(BaseModel):
+    name: str = Field(..., min_length=1, max_length=100)
+
+
+class TagResponse(BaseModel):
+    id: str
+    name: str
+    created_at: datetime
+
+
+class ListTagsResponse(BaseModel):
+    items: list[TagResponse]
+    total: int = Field(default=0, ge=0)
+
+
+class TagAssetsRequest(BaseModel):
+    tag_ids: list[str] = Field(..., min_length=1, max_length=50)

apps/api/app/schemas/template.py

@@ -44,10 +44,16 @@ class TemplateResponse(BaseModel):
     estimated_duration: float = 0.0
     segments: List[SegmentResponse] = Field(default_factory=list)
     is_active: bool = True
+    is_favorite: bool = False
     created_at: datetime
     updated_at: datetime
 
 
+class ToggleFavoriteResponse(BaseModel):
+    id: str
+    is_favorite: bool
+
+
 class ListTemplatesResponse(BaseModel):
     items: List[TemplateResponse]
     total: int = 0

apps/api/app/schemas/tts.py

@@ -0,0 +1,103 @@
+"""TTS 合成 API Schema。"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class TTSSynthesizeRequest(BaseModel):
+    """TTS 合成请求。"""
+
+    text: str = Field(..., min_length=1, max_length=10000, description="合成文本")
+    voice_id: str = Field("", description="音色 ID")
+    output_name: str = Field("", description="输出文件名")
+    language: str = Field("zh-CN", description="语言")
+    speed: float = Field(1.0, ge=0.5, le=2.0, description="语速")
+    voice_model: str = Field("", description="语音模型名称")
+    voice_clone_profile_id: str = Field("", description="关联的音色克隆档案 ID")
+    format: str = Field("mp3", description="输出格式（mp3/wav/pcm）")
+    metadata_: Optional[Dict[str, Any]] = Field(default=None, alias="metadata", description="额外元数据")
+
+    class Config:
+        populate_by_name = True
+
+
+class TTSJobResponse(BaseModel):
+    """TTS 任务响应。"""
+
+    id: str
+    user_id: str
+    input_text: str
+    voice_id: str = ""
+    voice_model: str = ""
+    project_id: str = ""
+    voice_clone_profile_id: str = ""
+    status: str
+    output_audio_url: str = ""
+    output_audio_key: str = ""
+    duration: float = 0.0
+    file_size: int = 0
+    sample_rate: int = 22050
+    format: str = "mp3"
+    error_message: str = ""
+    retry_count: int = 0
+    max_retries: int = 3
+    metadata_: Optional[Dict[str, Any]] = Field(default=None, alias="metadata", description="额外元数据")
+    started_at: Optional[datetime] = None
+    completed_at: Optional[datetime] = None
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        populate_by_name = True
+
+
+class TTSStatusResponse(BaseModel):
+    """TTS 任务状态响应（用于轮询）。"""
+
+    id: str
+    status: str
+    output_audio_url: str = ""
+    error_message: str = ""
+    duration: float = 0.0
+    retry_count: int = 0
+    created_at: datetime
+    updated_at: datetime
+
+
+class TTSSynthesizeResponse(BaseModel):
+    """TTS 合成创建响应。"""
+
+    job_id: str
+    status: str
+    message: str = "合成任务已创建"
+
+
+class ListTTSJobResponse(BaseModel):
+    """TTS 任务列表响应。"""
+
+    items: List[TTSJobResponse]
+    total: int
+    page: int
+    page_size: int
+
+
+class SaveToLibraryRequest(BaseModel):
+    """保存到配音库请求。"""
+
+    name: Optional[str] = Field(None, description="配音素材名称，留空则自动生成")
+
+
+class SaveToLibraryResponse(BaseModel):
+    """保存到配音库响应。"""
+
+    id: str
+    name: str
+    audio_url: str
+    duration: float
+    voice_id: str
+    voice_name: str
+    status: str

apps/api/app/schemas/upload.py

@@ -6,12 +6,7 @@ class UploadAssetRequest(BaseModel):
 
     project_id: str = Field(..., min_length=1, description="项目 ID")
     library_id: str = Field(..., min_length=1, description="素材库 ID")
-
-
-class UploadAssetResponse(BaseModel):
-    storage_key: str
-    ingest_job_id: str
-    url: str = Field(..., description="Public URL of uploaded file")
+    file_hash: str = Field(default="", max_length=64, description="文件 MD5 哈希，用于去重检测")
 
 
 class DirectUploadPrepareRequest(BaseModel):
@@ -20,6 +15,7 @@ class DirectUploadPrepareRequest(BaseModel):
     filename: str = Field(..., min_length=1, max_length=255)
     content_type: str = Field(default="application/octet-stream", min_length=1, max_length=100)
     file_size: int = Field(..., gt=0)
+    file_hash: str = Field(default="", max_length=64, description="文件 MD5 哈希，用于去重检测")
 
 
 class DirectUploadPrepareResponse(BaseModel):
@@ -35,8 +31,19 @@ class DirectUploadCompleteRequest(BaseModel):
     project_id: str = Field(..., min_length=1)
     library_id: str = Field(..., min_length=1)
     storage_key: str = Field(..., min_length=1, max_length=255)
+    file_hash: str = Field(default="", max_length=64, description="文件 MD5 哈希，用于去重检测")
 
 
 class DirectUploadCompleteResponse(BaseModel):
     storage_key: str
     ingest_job_id: str
+    duplicated: bool = Field(default=False, description="是否为重复素材（命中去重）")
+    asset_id: str = Field(default="", description="重复素材的 asset_id（duplicated=true 时返回）")
+
+
+class UploadAssetResponse(BaseModel):
+    storage_key: str
+    ingest_job_id: str
+    url: str = Field(..., description="Public URL of uploaded file")
+    duplicated: bool = Field(default=False, description="是否为重复素材（命中去重）")
+    asset_id: str = Field(default="", description="重复素材的 asset_id（duplicated=true 时返回）")

apps/api/app/schemas/voice.py

@@ -0,0 +1,127 @@
+"""统一配音响应 Schema — Phase 3 CosyVoice 集成.
+
+支持预置音色和克隆音色的统一响应格式。
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class UnifiedVoiceItemResponse(BaseModel):
+    """统一配音项响应。
+
+    同时支持预置音色（type=preset）和克隆音色（type=clone）。
+    """
+
+    id: str
+    """音色 ID（预置音色为 voice_id，克隆音色为数据库 ID）"""
+
+    type: Literal["preset", "clone"]
+    """音色类型：preset=预置音色，clone=用户克隆音色"""
+
+    name: str
+    """音色展示名称"""
+
+    description: str = ""
+    """音色描述"""
+
+    gender: str = "unknown"
+    """性别：male/female/unknown"""
+
+    language: str = "zh-CN"
+    """语言代码"""
+
+    voice_id: str = ""
+    """CosyVoice 模型音色名"""
+
+    voice_provider: str = "cosyvoice"
+    """语音服务商"""
+
+    audio_url: str = ""
+    """音频 URL（克隆音色为上传的音频，预置音色为空）"""
+
+    preview_url: str = ""
+    """预览音频 URL（预置音色可能有）"""
+
+    duration: float = 0
+    """音频时长（秒）"""
+
+    file_size: int = 0
+    """文件大小（字节）"""
+
+    status: str = "completed"
+    """状态"""
+
+    tags: List[str] = Field(default_factory=list)
+    """标签列表"""
+
+    # 克隆音色特有字段
+    user_id: Optional[str] = None
+    """所属用户 ID（仅克隆音色）"""
+
+    project_id: Optional[str] = None
+    """所属项目 ID（仅克隆音色）"""
+
+    voice_clone_profile_id: Optional[str] = None
+    """关联的音色克隆档案 ID（仅克隆音色）"""
+
+    created_at: Optional[datetime] = None
+    """创建时间（仅克隆音色）"""
+
+    updated_at: Optional[datetime] = None
+    """更新时间（仅克隆音色）"""
+
+
+class UnifiedVoiceListResponse(BaseModel):
+    """统一配音列表响应。"""
+
+    items: list[UnifiedVoiceItemResponse]
+    """音色列表（预置音色在前）"""
+
+    total: int = 0
+    """总数"""
+
+    preset_count: int = 0
+    """预置音色数量"""
+
+    clone_count: int = 0
+    """克隆音色数量"""
+
+
+class PresetVoiceItemResponse(BaseModel):
+    """预置音色项响应。"""
+
+    voice_id: str
+    """CosyVoice 模型音色名"""
+
+    name: str
+    """中文展示名"""
+
+    description: str
+    """音色描述"""
+
+    gender: str
+    """性别"""
+
+    language: str = "zh-CN"
+    """语言代码"""
+
+    preview_url: str = ""
+    """预览音频 URL"""
+
+    tags: List[str] = Field(default_factory=list)
+    """标签列表"""
+
+
+class PresetVoiceListResponse(BaseModel):
+    """预置音色列表响应。"""
+
+    items: list[PresetVoiceItemResponse]
+    """预置音色列表"""
+
+    total: int = 0
+    """总数"""

apps/api/app/schemas/voice_clone.py

@@ -0,0 +1,65 @@
+"""音色克隆 API Schema。"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class CreateVoiceCloneRequest(BaseModel):
+    """创建音色克隆请求。"""
+
+    name: str = Field(..., min_length=1, max_length=100, description="音色名称")
+    description: str = Field("", description="音色描述")
+    source_audio_url: str = Field("", description="参考音频 URL")
+    voice_model: str = Field("", description="语音模型名称")
+    language: str = Field("zh-CN", description="语言")
+    gender: str = Field("unknown", description="性别")
+    max_retries: int = Field(3, ge=1, le=10, description="最大重试次数")
+    metadata_: Optional[Dict[str, Any]] = Field(default=None, alias="metadata", description="额外元数据")
+
+    class Config:
+        populate_by_name = True
+
+
+class VoiceCloneProfileResponse(BaseModel):
+    """音色克隆档案响应。"""
+
+    id: str
+    user_id: str
+    name: str
+    description: str = ""
+    source_audio_url: str = ""
+    voice_id: str = ""
+    voice_model: str = ""
+    language: str = "zh-CN"
+    gender: str = "unknown"
+    status: str
+    error_message: str = ""
+    retry_count: int = 0
+    max_retries: int = 3
+    metadata_: Optional[Dict[str, Any]] = Field(default=None, alias="metadata", description="额外元数据")
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        populate_by_name = True
+
+
+class VoiceCloneStatusResponse(BaseModel):
+    """音色克隆状态响应（用于轮询）。"""
+
+    id: str
+    status: str
+    error_message: str = ""
+    voice_id: str = ""
+    retry_count: int = 0
+
+
+class ListVoiceCloneResponse(BaseModel):
+    """音色克隆列表响应。"""
+
+    items: List[VoiceCloneProfileResponse]
+    total: int

apps/api/app/services/__init__.py

@@ -0,0 +1,15 @@
+"""Service layer exports for Phase 8 模板编排引擎."""
+
+from .auto_clip_service import AutoClipService
+from .edit_plan_service import EditPlanService
+from .edit_template_service import EditTemplateService
+from .job_service import JobService
+from .video_compose_service import VideoComposeService
+
+__all__ = [
+    "AutoClipService",
+    "EditPlanService",
+    "EditTemplateService",
+    "JobService",
+    "VideoComposeService",
+]

apps/api/app/services/auto_clip_service.py

@@ -0,0 +1,340 @@
+"""AutoClipService — 智能选片服务.
+
+根据模板片段配置 (TemplateClipConfig) 的素材需求 (material_requirements)，
+自动从项目素材库中筛选、评分并分配最佳素材到剪辑计划片段 (EditPlanClip)。
+
+评分规则：
+- 质量分 (quality_score)：权重 0.5
+- 时长匹配度：权重 0.3（越接近目标时长得分越高）
+- 分类匹配度：权重 0.2（分类完全匹配得满分，部分匹配按比例得分）
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl import (
+    SQLAlchemyAssetRepository,
+    SQLAlchemyEditPlanClipRepository,
+    SQLAlchemyEditPlanRepository,
+    SQLAlchemyTemplateClipConfigRepository,
+)
+from packages.domain.asset import AssetType
+from packages.domain.classification import AssetClassification
+from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
+
+logger = logging.getLogger(__name__)
+
+# ── 评分权重 ──────────────────────────────────────────────────────────────────
+_WEIGHT_QUALITY = 0.5
+_WEIGHT_DURATION = 0.3
+_WEIGHT_CLASSIFICATION = 0.2
+
+
+@dataclass
+class AutoSelectResult:
+    """智能选片结果。"""
+
+    plan_id: str
+    total_clips: int
+    assigned_clips: int
+    unassigned_clips: int
+    details: list[ClipAssignDetail]
+
+
+@dataclass
+class ClipAssignDetail:
+    """单个片段的分配详情。"""
+
+    clip_id: str
+    clip_type: str
+    assigned_asset_id: str | None
+    candidate_count: int
+    score: float | None
+    reason: str
+
+
+class AutoClipService:
+    """智能选片服务 — 自动为剪辑计划片段分配最佳素材。"""
+
+    def __init__(self, db: Session) -> None:
+        self._plan_repo = SQLAlchemyEditPlanRepository(db)
+        self._clip_repo = SQLAlchemyEditPlanClipRepository(db)
+        self._config_repo = SQLAlchemyTemplateClipConfigRepository(db)
+        self._asset_repo = SQLAlchemyAssetRepository(db)
+
+    # ── 公开方法 ──────────────────────────────────────────────────────────────
+
+    def auto_select_assets(self, plan_id: str, project_id: str) -> AutoSelectResult:
+        """为剪辑计划的所有片段自动分配素材。
+
+        流程：
+        1. 获取剪辑计划 → 读取 template_id
+        2. 获取模板的所有片段配置 (TemplateClipConfig)
+        3. 获取计划的所有片段 (EditPlanClip)
+        4. 对每个片段，根据其关联的 config 筛选候选素材并评分
+        5. 将最佳素材分配给片段，标记为 READY
+
+        Args:
+            plan_id: 剪辑计划 ID
+            project_id: 项目 ID（素材所属项目）
+
+        Returns:
+            AutoSelectResult 包含分配统计和每个片段的详情
+
+        Raises:
+            ValueError: 计划不存在
+        """
+        plan = self._plan_repo.get(plan_id)
+        if plan is None:
+            raise ValueError(f"剪辑计划不存在: {plan_id}")
+
+        # 获取模板片段配置（按 order 排序）
+        configs = self._config_repo.list_by_template(plan.template_id)
+        config_map = {c.id: c for c in configs}
+
+        # 获取计划的所有片段
+        clips = self._clip_repo.list_by_plan(plan_id)
+
+        details: list[ClipAssignDetail] = []
+        assigned_count = 0
+
+        for clip in clips:
+            detail = self._assign_single_clip(clip, project_id, config_map)
+            details.append(detail)
+            if detail.assigned_asset_id is not None:
+                assigned_count += 1
+
+        result = AutoSelectResult(
+            plan_id=plan_id,
+            total_clips=len(clips),
+            assigned_clips=assigned_count,
+            unassigned_clips=len(clips) - assigned_count,
+            details=details,
+        )
+        logger.info(
+            "智能选片完成: plan=%s total=%d assigned=%d unassigned=%d",
+            plan_id,
+            result.total_clips,
+            result.assigned_clips,
+            result.unassigned_clips,
+        )
+        return result
+
+    def select_for_clip(self, clip_id: str, project_id: str) -> ClipAssignDetail:
+        """为单个片段选择并分配最佳素材。
+
+        Args:
+            clip_id: 片段 ID
+            project_id: 项目 ID（素材所属项目）
+
+        Returns:
+            ClipAssignDetail 分配详情
+
+        Raises:
+            ValueError: 片段不存在或缺少关联配置
+        """
+        clip = self._clip_repo.get(clip_id)
+        if clip is None:
+            raise ValueError(f"片段不存在: {clip_id}")
+
+        # 获取关联的模板配置
+        config = None
+        if clip.template_clip_config_id:
+            config = self._config_repo.get(clip.template_clip_config_id)
+
+        config_map = {config.id: config} if config else {}
+        return self._assign_single_clip(clip, project_id, config_map)
+
+    # ── 内部方法 ──────────────────────────────────────────────────────────────
+
+    def _assign_single_clip(
+        self,
+        clip: EditPlanClip,
+        project_id: str,
+        config_map: dict[str, object],
+    ) -> ClipAssignDetail:
+        """为单个片段分配素材。"""
+        config = config_map.get(clip.template_clip_config_id) if clip.template_clip_config_id else None
+
+        # 解析素材需求
+        requirements = self._parse_material_requirements(config)
+
+        # 搜索候选素材
+        candidates = self._asset_repo.search_candidates(
+            project_id=project_id,
+            file_type=requirements.get("file_type"),
+            min_quality_score=requirements.get("min_quality_score"),
+            min_duration=requirements.get("min_duration"),
+            max_duration=requirements.get("max_duration"),
+            classification_category=requirements.get("classification_category"),
+            tags=requirements.get("tags"),
+            status="completed",
+            limit=50,
+        )
+
+        if not candidates:
+            return ClipAssignDetail(
+                clip_id=clip.id,
+                clip_type=requirements.get("clip_type", "unknown"),
+                assigned_asset_id=None,
+                candidate_count=0,
+                score=None,
+                reason="无符合条件的候选素材",
+            )
+
+        # 评分并选择最佳素材
+        target_duration = requirements.get("target_duration")
+        target_category = requirements.get("classification_category")
+
+        best_asset = None
+        best_score = -1.0
+        for asset in candidates:
+            score = self._score_candidate(
+                asset,
+                target_duration=target_duration,
+                target_category=target_category,
+            )
+            if score > best_score:
+                best_score = score
+                best_asset = asset
+
+        if best_asset is None:
+            return ClipAssignDetail(
+                clip_id=clip.id,
+                clip_type=requirements.get("clip_type", "unknown"),
+                assigned_asset_id=None,
+                candidate_count=len(candidates),
+                score=None,
+                reason="候选素材评分均不合格",
+            )
+
+        # 分配素材并标记就绪
+        clip.assign_asset(best_asset.id)
+        clip.mark_ready()
+        self._clip_repo.update(clip)
+
+        return ClipAssignDetail(
+            clip_id=clip.id,
+            clip_type=requirements.get("clip_type", "unknown"),
+            assigned_asset_id=best_asset.id,
+            candidate_count=len(candidates),
+            score=round(best_score, 4),
+            reason=f"最佳匹配 (score={best_score:.4f})",
+        )
+
+    @staticmethod
+    def _score_candidate(
+        asset: object,
+        *,
+        target_duration: float | None = None,
+        target_category: str | None = None,
+    ) -> float:
+        """对候选素材评分 (0.0 ~ 1.0)。
+
+        评分维度：
+        - 质量分 (quality_score)：归一化到 0-1，权重 0.5
+        - 时长匹配度：越接近目标时长得分越高，权重 0.3
+        - 分类匹配度：完全匹配得 1.0，无分类得 0.0，权重 0.2
+        """
+        # 质量分 (0-100 → 0-1)
+        quality = getattr(asset, "quality_score", None)
+        quality_score = (quality / 100.0) if quality is not None else 0.5
+
+        # 时长匹配度
+        duration_score = 0.5  # 无目标时长的默认分
+        if target_duration is not None and target_duration > 0:
+            asset_duration = getattr(asset, "duration", None)
+            if asset_duration is not None and asset_duration > 0:
+                ratio = asset_duration / target_duration
+                # 比率越接近 1.0 得分越高，使用高斯衰减
+                duration_score = max(0.0, 1.0 - abs(1.0 - ratio) * 2)
+            # 无时长的素材得 0 分
+            else:
+                duration_score = 0.0
+
+        # 分类匹配度
+        classification_score = 0.0
+        if target_category is not None:
+            metadata = getattr(asset, "metadata", {}) or {}
+            asset_category = metadata.get("category", "")
+            if asset_category == target_category:
+                classification_score = 1.0
+            elif asset_category:
+                # 部分匹配（同大类）给 0.5
+                classification_score = 0.3
+        else:
+            # 无分类要求，所有素材得满分
+            classification_score = 1.0
+
+        total = (
+            _WEIGHT_QUALITY * quality_score
+            + _WEIGHT_DURATION * duration_score
+            + _WEIGHT_CLASSIFICATION * classification_score
+        )
+        return total
+
+    @staticmethod
+    def _parse_material_requirements(config: object | None) -> dict:
+        """从 TemplateClipConfig 解析素材筛选条件。
+
+        将 material_requirements JSON 和 config 自身的时长/类型字段
+        统一转换为 search_candidates 可用的筛选参数。
+        """
+        result: dict = {}
+        if config is None:
+            return result
+
+        # 从 material_requirements 提取筛选条件
+        requirements = getattr(config, "material_requirements", {}) or {}
+        # 素材类型: material_requirements 中的 "type" 字段
+        req_type = requirements.get("type")
+        if req_type and req_type in (AssetType.VIDEO, AssetType.IMAGE, AssetType.AUDIO):
+            result["file_type"] = req_type
+
+        # 最低质量分
+        min_quality = requirements.get("min_quality_score") or requirements.get("min_quality")
+        if min_quality is not None:
+            try:
+                result["min_quality_score"] = float(min_quality)
+            except (TypeError, ValueError) as e:
+                logger.warning(f"Operation failed in apps/api/app/services/auto_clip_service.py: {e}", exc_info=True)
+
+        # 分类筛选
+        category = requirements.get("category") or requirements.get("classification")
+        if category:
+            # 验证是否为有效分类
+            valid_categories = {c.value for c in AssetClassification}
+            if category in valid_categories:
+                result["classification_category"] = category
+
+        # 标签筛选
+        tags = requirements.get("tags")
+        if isinstance(tags, list) and tags:
+            result["tags"] = tags
+
+        # 时长范围：优先使用 config 的 min/max_duration，其次 material_requirements
+        min_dur = getattr(config, "min_duration", None) or requirements.get("min_duration")
+        max_dur = getattr(config, "max_duration", None) or requirements.get("max_duration")
+        if min_dur is not None and min_dur > 0:
+            result["min_duration"] = float(min_dur)
+        if max_dur is not None and max_dur > 0:
+            result["max_duration"] = float(max_dur)
+
+        # 目标时长（用于评分）
+        if min_dur and max_dur:
+            result["target_duration"] = (float(min_dur) + float(max_dur)) / 2
+        elif min_dur:
+            result["target_duration"] = float(min_dur) * 1.2
+        elif max_dur:
+            result["target_duration"] = float(max_dur) * 0.8
+
+        # 片段类型（用于日志）
+        clip_type = getattr(config, "clip_type", None)
+        if clip_type:
+            result["clip_type"] = clip_type.value if hasattr(clip_type, "value") else str(clip_type)
+
+        return result

apps/api/app/services/edit_plan_service.py

@@ -0,0 +1,503 @@
+"""EditPlanService — 剪辑计划管理业务逻辑.
+
+封装 EditPlan 和 EditPlanClip 的 CRUD 操作、状态机流转、
+以及渲染生成流程，提供统一的业务接口供 API 路由层调用。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl import (
+    SQLAlchemyEditPlanClipRepository,
+    SQLAlchemyEditPlanRepository,
+    SQLAlchemyGenerationTaskRepository,
+)
+from packages.domain.edit_plan import EditPlan, EditPlanStatus
+from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
+from packages.domain.generation_task import GenerationTaskStatus
+
+logger = logging.getLogger(__name__)
+
+
+class EditPlanService:
+    """剪辑计划管理服务
+
+    职责:
+    - 剪辑计划 CRUD（创建、查询、更新、删除）
+    - 剪辑片段管理（增删改查、分配素材）
+    - 状态机流转（draft → editing → rendering → completed/failed）
+    - 渲染生成流程（触发 Celery 任务、查询进度）
+    """
+
+    def __init__(self, db: Session) -> None:
+        self._plan_repo = SQLAlchemyEditPlanRepository(db)
+        self._clip_repo = SQLAlchemyEditPlanClipRepository(db)
+        self._generation_task_repo = SQLAlchemyGenerationTaskRepository(db)
+
+    # ── 剪辑计划 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)
+
+    def get_plan_or_raise(self, plan_id: str) -> EditPlan:
+        """获取计划，不存在则抛出 ValueError"""
+        plan = self._plan_repo.get(plan_id)
+        if plan is None:
+            raise ValueError(f"剪辑计划不存在: {plan_id}")
+        return plan
+
+    def create_plan(
+        self,
+        template_id: str,
+        name: str,
+        *,
+        config: Optional[dict[str, Any]] = None,
+        total_duration: float = 0.0,
+        project_id: str = "",
+        created_by_user_id: str = "",
+    ) -> EditPlan:
+        """创建剪辑计划
+
+        Raises:
+            ValueError: 参数校验失败
+        """
+        plan = EditPlan.create(
+            template_id=template_id,
+            name=name,
+            config=config,
+            total_duration=total_duration,
+            project_id=project_id,
+            created_by_user_id=created_by_user_id,
+        )
+        created = self._plan_repo.create(plan)
+        logger.info("创建剪辑计划: id=%s name=%s", created.id, created.name)
+        return created
+
+    def update_plan(
+        self,
+        plan_id: str,
+        *,
+        name: Optional[str] = None,
+        config: Optional[dict[str, Any]] = None,
+        total_duration: Optional[float] = None,
+    ) -> EditPlan:
+        """更新计划基础字段
+
+        Raises:
+            ValueError: 计划不存在
+        """
+        existing = self.get_plan_or_raise(plan_id)
+
+        updated = EditPlan(
+            id=existing.id,
+            template_id=existing.template_id,
+            name=name.strip() if name is not None else existing.name,
+            status=existing.status,
+            total_duration=total_duration if total_duration is not None else existing.total_duration,
+            source_edit_plan_id=existing.source_edit_plan_id,
+            project_id=existing.project_id,
+            created_by_user_id=existing.created_by_user_id,
+            config=config if config is not None else existing.config,
+            created_at=existing.created_at,
+            updated_at=existing.updated_at,
+        )
+        result = self._plan_repo.update(updated)
+        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:
+        """流转计划状态
+
+        状态流转规则:
+        - draft → editing (start_editing)
+        - editing → rendering (start_rendering)
+        - rendering → completed (mark_completed)
+        - rendering → failed (mark_failed)
+        - failed → draft (reset_to_draft)
+
+        Raises:
+            ValueError: 计划不存在或状态流转非法
+        """
+        plan = self.get_plan_or_raise(plan_id)
+
+        # 如果已是目标状态，直接返回
+        if plan.status == target_status:
+            return plan
+
+        # 根据目标状态调用对应的状态机方法
+        transition_map = {
+            EditPlanStatus.EDITING: plan.start_editing,
+            EditPlanStatus.RENDERING: plan.start_rendering,
+            EditPlanStatus.COMPLETED: plan.mark_completed,
+            EditPlanStatus.FAILED: plan.mark_failed,
+            EditPlanStatus.DRAFT: plan.reset_to_draft,
+        }
+
+        transition_fn = transition_map.get(target_status)
+        if transition_fn is None:
+            raise ValueError(f"无效的目标状态: {target_status}")
+
+        transition_fn()
+        result = self._plan_repo.update(plan)
+        logger.info(
+            "状态流转: plan_id=%s %s → %s",
+            plan_id,
+            plan.status,
+            target_status,
+        )
+        return result
+
+    # ── 剪辑片段管理 ────────────────────────────────────────────────────────
+
+    def list_clips(
+        self,
+        plan_id: str,
+        *,
+        status: Optional[EditPlanClipStatus] = None,
+        skip: int = 0,
+        limit: int = 100,
+    ) -> List[EditPlanClip]:
+        """列出计划的片段"""
+        # 确保计划存在
+        self.get_plan_or_raise(plan_id)
+        return self._clip_repo.list_by_plan(plan_id, status=status, skip=skip, limit=limit)
+
+    def count_clips(
+        self,
+        plan_id: str,
+        *,
+        status: Optional[EditPlanClipStatus] = None,
+    ) -> int:
+        """统计片段数量"""
+        return self._clip_repo.count(plan_id=plan_id, status=status)
+
+    def get_clip(self, clip_id: str) -> Optional[EditPlanClip]:
+        """获取片段详情"""
+        return self._clip_repo.get(clip_id)
+
+    def get_clip_or_raise(self, clip_id: str) -> EditPlanClip:
+        """获取片段，不存在则抛出 ValueError"""
+        clip = self._clip_repo.get(clip_id)
+        if clip is None:
+            raise ValueError(f"片段不存在: {clip_id}")
+        return clip
+
+    def create_clip(
+        self,
+        plan_id: str,
+        clip_type: str,
+        order: int,
+        *,
+        template_clip_config_id: str = "",
+        asset_id: str = "",
+        text_content: str = "",
+        start_time: float = 0.0,
+        duration: float = 0.0,
+        transition_effect: str = "cut",
+        config: Optional[dict[str, Any]] = None,
+    ) -> EditPlanClip:
+        """创建片段
+
+        Raises:
+            ValueError: 计划不存在或参数校验失败
+        """
+        # 确保计划存在
+        self.get_plan_or_raise(plan_id)
+
+        clip = EditPlanClip.create(
+            plan_id=plan_id,
+            clip_type=clip_type,
+            order=order,
+            template_clip_config_id=template_clip_config_id,
+            asset_id=asset_id,
+            text_content=text_content,
+            start_time=start_time,
+            duration=duration,
+            transition_effect=transition_effect,
+            config=config,
+        )
+        created = self._clip_repo.create(clip)
+        logger.info(
+            "创建片段: id=%s plan_id=%s clip_type=%s order=%d",
+            created.id,
+            plan_id,
+            created.clip_type,
+            created.order,
+        )
+        return created
+
+    def update_clip(
+        self,
+        clip_id: str,
+        *,
+        clip_type: Optional[str] = None,
+        order: Optional[int] = None,
+        asset_id: Optional[str] = None,
+        text_content: Optional[str] = None,
+        start_time: Optional[float] = None,
+        duration: Optional[float] = None,
+        transition_effect: Optional[str] = None,
+        config: Optional[dict[str, Any]] = None,
+    ) -> EditPlanClip:
+        """更新片段
+
+        Raises:
+            ValueError: 片段不存在
+        """
+        existing = self.get_clip_or_raise(clip_id)
+
+        updated = EditPlanClip(
+            id=existing.id,
+            plan_id=existing.plan_id,
+            clip_type=clip_type.strip() if clip_type is not None else existing.clip_type,
+            order=order if order is not None else existing.order,
+            template_clip_config_id=existing.template_clip_config_id,
+            asset_id=asset_id.strip() if asset_id is not None else existing.asset_id,
+            text_content=text_content.strip() if text_content is not None else existing.text_content,
+            start_time=start_time if start_time is not None else existing.start_time,
+            duration=duration if duration is not None else existing.duration,
+            transition_effect=(
+                transition_effect.strip() if transition_effect is not None else existing.transition_effect
+            ),
+            status=existing.status,
+            config=config if config is not None else existing.config,
+            created_at=existing.created_at,
+            updated_at=existing.updated_at,
+        )
+        result = self._clip_repo.update(updated)
+        logger.info("更新片段: id=%s", clip_id)
+        return result
+
+    def assign_asset(self, clip_id: str, asset_id: str) -> EditPlanClip:
+        """为片段分配素材
+
+        Raises:
+            ValueError: 片段不存在或 asset_id 为空
+        """
+        clip = self.get_clip_or_raise(clip_id)
+        clip.assign_asset(asset_id)
+        result = self._clip_repo.update(clip)
+        logger.info("分配素材: clip_id=%s asset_id=%s", clip_id, asset_id)
+        return result
+
+    def delete_clip(self, clip_id: str) -> bool:
+        """删除片段
+
+        Returns:
+            bool: 是否删除成功
+        """
+        deleted = self._clip_repo.delete(clip_id)
+        if deleted:
+            logger.info("删除片段: id=%s", clip_id)
+        return deleted
+
+    def delete_all_clips(self, plan_id: str) -> int:
+        """删除计划下所有片段
+
+        Returns:
+            int: 删除的片段数量
+        """
+        count = self._clip_repo.delete_by_plan(plan_id)
+        logger.info("删除所有片段: plan_id=%s count=%d", plan_id, count)
+        return count
+
+    # ── 渲染生成流程 ────────────────────────────────────────────────────────
+
+    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]:
+        """获取渲染进度状态
+
+        Returns:
+            dict: {
+                "plan": EditPlan,
+                "clips": List[EditPlanClip],
+                "generation_task_id": Optional[str],
+                "generation_task_status": Optional[str],
+            }
+
+        Raises:
+            ValueError: 计划不存在
+        """
+        plan = self.get_plan_or_raise(plan_id)
+        clips = self._clip_repo.list_by_plan(plan_id)
+
+        # 从 plan.config 中获取 generation_task_id
+        generation_task_id = plan.config.get("generation_task_id")
+        generation_task_status = None
+
+        if generation_task_id:
+            task = self._generation_task_repo.get(generation_task_id)
+            if task:
+                generation_task_status = task.status.value if hasattr(task.status, "value") else task.status
+
+        return {
+            "plan": plan,
+            "clips": clips,
+            "generation_task_id": generation_task_id,
+            "generation_task_status": generation_task_status,
+        }
+
+    def can_generate(self, plan_id: str) -> tuple[bool, str]:
+        """检查是否可以触发渲染
+
+        Returns:
+            tuple: (can_generate, reason)
+        """
+        plan = self.get_plan_or_raise(plan_id)
+
+        # 检查状态
+        if plan.status != EditPlanStatus.EDITING:
+            return False, f"只有 editing 状态的计划可以触发渲染，当前状态: {plan.status}"
+
+        # 检查是否有片段
+        clips = self._clip_repo.list_by_plan(plan_id)
+        if not clips:
+            return False, "计划下没有片段，无法触发渲染"
+
+        return True, ""
+
+    def mark_clips_ready(self, plan_id: str) -> int:
+        """将所有 pending 状态的片段标记为 ready
+
+        Returns:
+            int: 标记的片段数量
+        """
+        clips = self._clip_repo.list_by_plan(
+            plan_id,
+            status=EditPlanClipStatus.PENDING,
+        )
+        count = 0
+        for clip in clips:
+            clip.mark_ready()
+            self._clip_repo.update(clip)
+            count += 1
+        logger.info("标记片段就绪: plan_id=%s count=%d", plan_id, count)
+        return count
+
+    def update_plan_config(self, plan_id: str, config_updates: Dict[str, Any]) -> EditPlan:
+        """更新计划配置（合并更新）
+
+        Args:
+            plan_id: 计划 ID
+            config_updates: 要合并的配置
+
+        Returns:
+            更新后的计划
+        """
+        plan = self.get_plan_or_raise(plan_id)
+        new_config = {**plan.config, **config_updates}
+
+        updated = EditPlan(
+            id=plan.id,
+            template_id=plan.template_id,
+            name=plan.name,
+            status=plan.status,
+            total_duration=plan.total_duration,
+            source_edit_plan_id=plan.source_edit_plan_id,
+            project_id=plan.project_id,
+            created_by_user_id=plan.created_by_user_id,
+            config=new_config,
+            created_at=plan.created_at,
+            updated_at=plan.updated_at,
+        )
+        return self._plan_repo.update(updated)

apps/api/app/services/edit_template_service.py

@@ -0,0 +1,392 @@
+"""EditTemplateService — 模板管理业务逻辑.
+
+封装 EditTemplate 和 TemplateClipConfig 的 CRUD 操作，
+提供统一的业务接口供 API 路由层调用。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, List, Optional
+
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl import (
+    SQLAlchemyEditTemplateRepository,
+    SQLAlchemyTemplateClipConfigRepository,
+)
+from packages.domain.edit_template import EditTemplate, EditTemplateStatus
+from packages.domain.template_clip_config import (
+    ClipType,
+    TemplateClipConfig,
+    TransitionEffect,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class EditTemplateService:
+    """模板管理服务
+
+    职责:
+    - 模板 CRUD（创建、查询、更新、软删除）
+    - 模板片段配置管理（增删改查）
+    - 业务校验（名称去重、状态合法性等）
+    """
+
+    def __init__(self, db: Session) -> None:
+        self._template_repo = SQLAlchemyEditTemplateRepository(db)
+        self._clip_config_repo = SQLAlchemyTemplateClipConfigRepository(db)
+
+    # ── 模板 CRUD ──────────────────────────────────────────────────────────
+
+    def list_templates(
+        self,
+        *,
+        template_type: Optional[str] = None,
+        status: Optional[EditTemplateStatus] = None,
+        active_only: bool = False,
+        skip: int = 0,
+        limit: int = 50,
+    ) -> List[EditTemplate]:
+        """列出模板
+
+        Args:
+            template_type: 按类型筛选
+            status: 按状态筛选
+            active_only: 仅返回激活模板
+            skip: 分页偏移
+            limit: 每页数量
+        """
+        if active_only:
+            return self._template_repo.list_active(
+                template_type=template_type,
+                skip=skip,
+                limit=limit,
+            )
+        return self._template_repo.list_all(
+            template_type=template_type,
+            status=status,
+            skip=skip,
+            limit=limit,
+        )
+
+    def count_templates(
+        self,
+        *,
+        template_type: Optional[str] = None,
+        status: Optional[EditTemplateStatus] = None,
+    ) -> int:
+        """统计模板数量"""
+        return self._template_repo.count(
+            template_type=template_type,
+            status=status,
+        )
+
+    def get_template(self, template_id: str) -> Optional[EditTemplate]:
+        """获取模板详情"""
+        return self._template_repo.get(template_id)
+
+    def get_template_or_raise(self, template_id: str) -> EditTemplate:
+        """获取模板，不存在则抛出 ValueError"""
+        template = self._template_repo.get(template_id)
+        if template is None:
+            raise ValueError(f"模板不存在: {template_id}")
+        return template
+
+    def create_template(
+        self,
+        name: str,
+        *,
+        description: str = "",
+        template_type: str = "default",
+        config: Optional[dict[str, Any]] = None,
+        preview_url: str = "",
+        sort_weight: int = 0,
+    ) -> EditTemplate:
+        """创建模板
+
+        Raises:
+            ValueError: 名称为空或重复
+        """
+        # 名称校验
+        clean_name = name.strip()
+        if not clean_name:
+            raise ValueError("模板名称不能为空")
+
+        # 名称重复检查
+        existing = self._template_repo.list_all(skip=0, limit=1000)
+        for t in existing:
+            if t.name == clean_name and t.status == EditTemplateStatus.ACTIVE:
+                raise ValueError(f"模板名称已存在: {clean_name}")
+
+        template = EditTemplate.create(
+            name=clean_name,
+            description=description,
+            template_type=template_type,
+            config=config,
+            preview_url=preview_url,
+            sort_weight=sort_weight,
+        )
+        created = self._template_repo.create(template)
+        logger.info("创建模板: id=%s name=%s", created.id, created.name)
+        return created
+
+    def update_template(
+        self,
+        template_id: str,
+        *,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        template_type: Optional[str] = None,
+        config: Optional[dict[str, Any]] = None,
+        preview_url: Optional[str] = None,
+        sort_weight: Optional[int] = None,
+        status: Optional[EditTemplateStatus] = None,
+    ) -> EditTemplate:
+        """更新模板
+
+        Raises:
+            ValueError: 模板不存在或名称重复
+        """
+        existing = self.get_template_or_raise(template_id)
+
+        # 名称重复检查（排除自身）
+        new_name = name.strip() if name is not None else existing.name
+        if name is not None and new_name != existing.name:
+            all_templates = self._template_repo.list_all(skip=0, limit=1000)
+            for t in all_templates:
+                if t.id != template_id and t.name == new_name and t.status == EditTemplateStatus.ACTIVE:
+                    raise ValueError(f"模板名称已存在: {new_name}")
+
+        # 构建更新后的实体
+        updated = EditTemplate(
+            id=existing.id,
+            name=new_name,
+            description=description.strip() if description is not None else existing.description,
+            template_type=template_type.strip() if template_type is not None else existing.template_type,
+            config=config if config is not None else existing.config,
+            preview_url=preview_url.strip() if preview_url is not None else existing.preview_url,
+            sort_weight=sort_weight if sort_weight is not None else existing.sort_weight,
+            status=status if status is not None else existing.status,
+            created_at=existing.created_at,
+            updated_at=existing.updated_at,
+        )
+        result = self._template_repo.update(updated)
+        logger.info("更新模板: id=%s", template_id)
+        return result
+
+    def deactivate_template(self, template_id: str) -> EditTemplate:
+        """软删除模板（设为 inactive）
+
+        Raises:
+            ValueError: 模板不存在
+        """
+        existing = self.get_template_or_raise(template_id)
+        existing.deactivate()
+        result = self._template_repo.update(existing)
+        logger.info("停用模板: id=%s", template_id)
+        return result
+
+    # ── 模板片段配置管理 ────────────────────────────────────────────────────
+
+    def list_clip_configs(
+        self,
+        template_id: str,
+        *,
+        clip_type: Optional[ClipType] = None,
+        skip: int = 0,
+        limit: int = 100,
+    ) -> List[TemplateClipConfig]:
+        """列出模板的片段配置"""
+        # 确保模板存在
+        self.get_template_or_raise(template_id)
+        return self._clip_config_repo.list_by_template(
+            template_id,
+            clip_type=clip_type,
+            skip=skip,
+            limit=limit,
+        )
+
+    def get_clip_config(self, config_id: str) -> Optional[TemplateClipConfig]:
+        """获取片段配置详情"""
+        return self._clip_config_repo.get(config_id)
+
+    def get_clip_config_or_raise(self, config_id: str) -> TemplateClipConfig:
+        """获取片段配置，不存在则抛出 ValueError"""
+        config = self._clip_config_repo.get(config_id)
+        if config is None:
+            raise ValueError(f"片段配置不存在: {config_id}")
+        return config
+
+    def create_clip_config(
+        self,
+        template_id: str,
+        clip_type: ClipType | str,
+        order: int,
+        *,
+        min_duration: float = 0.0,
+        max_duration: float = 0.0,
+        text_template: str = "",
+        material_requirements: Optional[dict[str, Any]] = None,
+        transition_effect: TransitionEffect | str = TransitionEffect.CUT,
+        config: Optional[dict[str, Any]] = None,
+    ) -> TemplateClipConfig:
+        """创建片段配置
+
+        Raises:
+            ValueError: 模板不存在或参数校验失败
+        """
+        # 确保模板存在
+        self.get_template_or_raise(template_id)
+
+        clip_config = TemplateClipConfig.create(
+            template_id=template_id,
+            clip_type=clip_type,
+            order=order,
+            min_duration=min_duration,
+            max_duration=max_duration,
+            text_template=text_template,
+            material_requirements=material_requirements,
+            transition_effect=transition_effect,
+            config=config,
+        )
+        created = self._clip_config_repo.create(clip_config)
+        logger.info(
+            "创建片段配置: id=%s template_id=%s clip_type=%s order=%d",
+            created.id,
+            template_id,
+            created.clip_type,
+            created.order,
+        )
+        return created
+
+    def update_clip_config(
+        self,
+        config_id: str,
+        *,
+        clip_type: Optional[ClipType | str] = None,
+        order: Optional[int] = None,
+        min_duration: Optional[float] = None,
+        max_duration: Optional[float] = None,
+        text_template: Optional[str] = None,
+        material_requirements: Optional[dict[str, Any]] = None,
+        transition_effect: Optional[TransitionEffect | str] = None,
+        config: Optional[dict[str, Any]] = None,
+    ) -> TemplateClipConfig:
+        """更新片段配置
+
+        Raises:
+            ValueError: 配置不存在或参数校验失败
+        """
+        existing = self.get_clip_config_or_raise(config_id)
+
+        # 解析枚举类型
+        new_clip_type = ClipType(clip_type) if clip_type is not None else existing.clip_type
+        new_transition = (
+            TransitionEffect(transition_effect) if transition_effect is not None else existing.transition_effect
+        )
+
+        updated = TemplateClipConfig(
+            id=existing.id,
+            template_id=existing.template_id,
+            clip_type=new_clip_type,
+            order=order if order is not None else existing.order,
+            min_duration=min_duration if min_duration is not None else existing.min_duration,
+            max_duration=max_duration if max_duration is not None else existing.max_duration,
+            text_template=text_template.strip() if text_template is not None else existing.text_template,
+            material_requirements=(
+                material_requirements if material_requirements is not None else existing.material_requirements
+            ),
+            transition_effect=new_transition,
+            config=config if config is not None else existing.config,
+            created_at=existing.created_at,
+            updated_at=existing.updated_at,
+        )
+        result = self._clip_config_repo.update(updated)
+        logger.info("更新片段配置: id=%s", config_id)
+        return result
+
+    def delete_clip_config(self, config_id: str) -> bool:
+        """删除片段配置
+
+        Returns:
+            bool: 是否删除成功
+        """
+        deleted = self._clip_config_repo.delete(config_id)
+        if deleted:
+            logger.info("删除片段配置: id=%s", config_id)
+        return deleted
+
+    def reorder_clip_configs(
+        self,
+        template_id: str,
+        config_ids: List[str],
+    ) -> List[TemplateClipConfig]:
+        """重新排序片段配置
+
+        Args:
+            template_id: 模板 ID
+            config_ids: 按新顺序排列的配置 ID 列表
+
+        Returns:
+            更新后的配置列表
+
+        Raises:
+            ValueError: 模板不存在或配置 ID 不匹配
+        """
+        # 确保模板存在
+        self.get_template_or_raise(template_id)
+
+        # 获取当前配置
+        current_configs = self._clip_config_repo.list_by_template(template_id)
+        current_ids = {c.id for c in current_configs}
+
+        # 校验 ID 列表
+        if set(config_ids) != current_ids:
+            raise ValueError("配置 ID 列表与模板下的配置不匹配")
+
+        # 更新 order
+        results = []
+        for new_order, config_id in enumerate(config_ids):
+            config = self._clip_config_repo.get(config_id)
+            if config is None:
+                continue
+            updated = TemplateClipConfig(
+                id=config.id,
+                template_id=config.template_id,
+                clip_type=config.clip_type,
+                order=new_order,
+                min_duration=config.min_duration,
+                max_duration=config.max_duration,
+                text_template=config.text_template,
+                material_requirements=config.material_requirements,
+                transition_effect=config.transition_effect,
+                config=config.config,
+                created_at=config.created_at,
+                updated_at=config.updated_at,
+            )
+            results.append(self._clip_config_repo.update(updated))
+
+        logger.info(
+            "重排序片段配置: template_id=%s count=%d",
+            template_id,
+            len(config_ids),
+        )
+        return results
+
+    def get_template_with_configs(
+        self,
+        template_id: str,
+    ) -> dict:
+        """获取模板及其所有片段配置
+
+        Returns:
+            dict: {"template": EditTemplate, "clip_configs": List[TemplateClipConfig]}
+        """
+        template = self.get_template_or_raise(template_id)
+        clip_configs = self._clip_config_repo.list_by_template(template_id)
+        return {
+            "template": template,
+            "clip_configs": clip_configs,
+        }

apps/api/app/services/job_service.py

@@ -0,0 +1,268 @@
+"""JobService 服务层 — Phase 8 任务 2.10.
+
+将 JobService 与 VideoComposeService 集成，提供视频合成的完整异步工作流：
+1. 创建 Job（记录任务元数据）
+2. 提交执行（dispatch Celery 任务）
+3. Celery 任务中更新进度、处理完成/失败
+
+同时也提供通用的 Job 管理能力，供 ClipPlanService、RenderOrchestrator 等使用。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from sqlalchemy.orm import Session
+
+from packages.application.jobs import (
+    CancelJobUseCase,
+    CompleteJobCommand,
+    CompleteJobUseCase,
+    CreateJobCommand,
+    CreateJobUseCase,
+    FailJobCommand,
+    FailJobUseCase,
+    GetJobStatisticsUseCase,
+    GetJobUseCase,
+    ListJobsUseCase,
+    RetryJobUseCase,
+    SubmitJobUseCase,
+    UpdateJobProgressCommand,
+    UpdateJobProgressUseCase,
+)
+from packages.domain.job import Job, JobStatus, JobType
+from packages.ports.job_repository import JobRepository
+
+logger = logging.getLogger(__name__)
+
+
+class JobService:
+    """统一异步任务管理服务。
+
+    职责：
+    - 为视频合成等耗时操作提供统一的异步任务管理
+    - 封装 Use Case 的调用，提供简洁的服务接口
+    - 与 VideoComposeService 集成，支持视频合成工作流
+
+    用法::
+
+        job_service = JobService(db)
+        job = job_service.create_compose_job(
+            project_id="xxx",
+            plan_id="yyy",
+            user_id="zzz",
+        )
+        job_service.submit_job(job.id, celery_task_id="celery-xxx")
+    """
+
+    def __init__(self, job_repo: JobRepository):
+        self._job_repo = job_repo
+
+    # ── 创建任务 ──────────────────────────────────────────────────────────
+
+    def create_compose_job(
+        self,
+        project_id: str,
+        plan_id: str,
+        user_id: str,
+        *,
+        max_retries: int = 3,
+    ) -> Job:
+        """创建视频合成任务。
+
+        Args:
+            project_id: 项目 ID
+            plan_id: EditPlan ID
+            user_id: 创建人 ID
+            max_retries: 最大重试次数
+
+        Returns:
+            创建的 Job 实例
+        """
+        use_case = CreateJobUseCase(self._job_repo)
+        return use_case.execute(
+            CreateJobCommand(
+                project_id=project_id,
+                job_type=JobType.VIDEO_COMPOSE,
+                payload={"plan_id": plan_id},
+                source_id=plan_id,
+                created_by_user_id=user_id,
+                max_retries=max_retries,
+            )
+        )
+
+    def create_render_job(
+        self,
+        project_id: str,
+        plan_id: str,
+        user_id: str,
+        *,
+        max_retries: int = 3,
+    ) -> Job:
+        """创建剪辑计划渲染任务。"""
+        use_case = CreateJobUseCase(self._job_repo)
+        return use_case.execute(
+            CreateJobCommand(
+                project_id=project_id,
+                job_type=JobType.RENDER_EDIT_PLAN,
+                payload={"plan_id": plan_id},
+                source_id=plan_id,
+                created_by_user_id=user_id,
+                max_retries=max_retries,
+            )
+        )
+
+    def create_job(
+        self,
+        project_id: str,
+        job_type: JobType | str,
+        *,
+        payload: dict | None = None,
+        source_id: str = "",
+        user_id: str = "",
+        max_retries: int = 3,
+    ) -> Job:
+        """创建通用任务。"""
+        use_case = CreateJobUseCase(self._job_repo)
+        return use_case.execute(
+            CreateJobCommand(
+                project_id=project_id,
+                job_type=job_type,
+                payload=payload or {},
+                source_id=source_id,
+                created_by_user_id=user_id,
+                max_retries=max_retries,
+            )
+        )
+
+    # ── 提交执行 ──────────────────────────────────────────────────────────
+
+    def submit_job(self, job_id: str, celery_task_id: str = "") -> Job:
+        """提交任务执行。"""
+        use_case = SubmitJobUseCase(self._job_repo)
+        return use_case.execute(job_id, celery_task_id)
+
+    # ── 进度更新 ──────────────────────────────────────────────────────────
+
+    def update_progress(self, job_id: str, progress: float, stage: str = "") -> Job:
+        """更新任务进度。"""
+        use_case = UpdateJobProgressUseCase(self._job_repo)
+        return use_case.execute(
+            UpdateJobProgressCommand(
+                job_id=job_id,
+                progress=progress,
+                current_stage=stage,
+            )
+        )
+
+    # ── 完成 / 失败 ────────────────────────────────────────────────────────
+
+    def complete_job(self, job_id: str, result: dict | None = None) -> Job:
+        """标记任务完成。"""
+        use_case = CompleteJobUseCase(self._job_repo)
+        return use_case.execute(CompleteJobCommand(job_id=job_id, result=result or {}))
+
+    def fail_job(self, job_id: str, error_message: str) -> Job:
+        """标记任务失败。"""
+        use_case = FailJobUseCase(self._job_repo)
+        return use_case.execute(FailJobCommand(job_id=job_id, error_message=error_message))
+
+    # ── 重试 / 取消 ────────────────────────────────────────────────────────
+
+    def retry_job(self, job_id: str) -> Job:
+        """重试失败任务。"""
+        use_case = RetryJobUseCase(self._job_repo)
+        return use_case.execute(job_id)
+
+    def cancel_job(self, job_id: str) -> Job:
+        """取消任务。"""
+        use_case = CancelJobUseCase(self._job_repo)
+        return use_case.execute(job_id)
+
+    # ── 查询 ─────────────────────────────────────────────────────────────
+
+    def get_job(self, job_id: str) -> Job | None:
+        """获取任务详情。"""
+        use_case = GetJobUseCase(self._job_repo)
+        return use_case.execute(job_id)
+
+    def list_project_jobs(
+        self,
+        project_id: str,
+        *,
+        job_type: JobType | str | None = None,
+        status: JobStatus | str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[Job]:
+        """获取项目下的任务列表。"""
+        use_case = ListJobsUseCase(self._job_repo)
+        return use_case.execute(
+            project_id=project_id,
+            job_type=job_type,
+            status=status,
+            limit=limit,
+            offset=offset,
+        )
+
+    def list_user_jobs(
+        self,
+        user_id: str,
+        *,
+        job_type: JobType | str | None = None,
+        status: JobStatus | str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[Job]:
+        """获取用户的任务列表。"""
+        use_case = ListJobsUseCase(self._job_repo)
+        return use_case.execute(
+            user_id=user_id,
+            job_type=job_type,
+            status=status,
+            limit=limit,
+            offset=offset,
+        )
+
+    def get_statistics(self, project_id: str) -> dict[str, Any]:
+        """获取项目任务统计。"""
+        use_case = GetJobStatisticsUseCase(self._job_repo)
+        return use_case.execute(project_id)
+
+    # ── 防重复检查 ────────────────────────────────────────────────────────
+
+    def has_active_job_for_source(self, source_id: str, job_type: JobType | str) -> bool:
+        """检查是否已有活跃任务（防止重复提交）。
+
+        Args:
+            source_id: 关联的业务实体 ID
+            job_type: 任务类型
+
+        Returns:
+            True 如果存在活跃任务
+        """
+        return self._job_repo.find_active_by_source(source_id, job_type) is not None
+
+    # ── 便捷方法：带防重的视频合成提交 ──────────────────────────────────────
+
+    def submit_compose_if_not_exists(
+        self,
+        project_id: str,
+        plan_id: str,
+        user_id: str,
+        celery_task_id: str = "",
+    ) -> tuple[Job, bool]:
+        """创建并提交视频合成任务（防重复）。
+
+        Returns:
+            (job, created): job 实例和是否新创建的标志
+        """
+        if self.has_active_job_for_source(plan_id, JobType.VIDEO_COMPOSE):
+            existing = self._job_repo.find_active_by_source(plan_id, JobType.VIDEO_COMPOSE)
+            logger.info("已存在活跃的视频合成任务: job_id=%s plan_id=%s", existing.id, plan_id)
+            return existing, False
+
+        job = self.create_compose_job(project_id, plan_id, user_id)
+        job = self.submit_job(job.id, celery_task_id)
+        return job, True

apps/api/app/services/video_compose_service.py

@@ -0,0 +1,624 @@
+"""VideoComposeService — Phase 8 任务 2.09.
+
+FFmpeg 视频合成编排服务：
+  1. 根据 EditPlan + EditPlanClips 生成 FFmpeg filter_complex 命令
+  2. 支持逐片段 scale / crop / trim / setpts 滤镜
+  3. 支持转场效果（fade / slide / dissolve / wipe）
+  4. 支持音频流合并
+  5. 提供合成前校验逻辑
+
+设计原则：
+  - 本服务只负责 **命令生成 + 校验**，不执行 FFmpeg
+  - Worker 层（Celery task）调用本服务生成命令后执行
+  - API 层可调用 build_compose_command 做预览 / 调试
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.edit_plan_clip_repository import (
+    SQLAlchemyEditPlanClipRepository,
+)
+from packages.adapters.sqlalchemy_impl.edit_plan_repository import (
+    SQLAlchemyEditPlanRepository,
+)
+from packages.domain.edit_plan import EditPlan, EditPlanStatus
+from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
+from packages.domain.template_clip_config import TransitionEffect
+
+logger = logging.getLogger(__name__)
+
+# ── 常量 ──────────────────────────────────────────────────────────────────────
+
+DEFAULT_OUTPUT_WIDTH = 1280
+DEFAULT_OUTPUT_HEIGHT = 720
+DEFAULT_FPS = 25
+DEFAULT_CODEC = "libx264"
+DEFAULT_CRF = 23
+DEFAULT_PRESET = "medium"
+
+# xfade 转场映射：TransitionEffect → FFmpeg xfade transition 名称
+_XFADE_TRANSITION_MAP: dict[str, str] = {
+    TransitionEffect.FADE: "fade",
+    TransitionEffect.SLIDE_LEFT: "slideleft",
+    TransitionEffect.SLIDE_RIGHT: "slideright",
+    TransitionEffect.DISSOLVE: "dissolve",
+    TransitionEffect.WIPE: "wipeleft",
+}
+
+# 转场默认时长（秒）
+DEFAULT_TRANSITION_DURATION = 0.5
+
+
+# ── 数据结构 ──────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class ClipFilterChain:
+    """单个片段的滤镜链描述。"""
+
+    clip_id: str
+    input_index: int
+    video_label: str
+    audio_label: str | None
+    filters: list[str]
+    duration: float
+
+
+@dataclass(frozen=True)
+class ComposeCommand:
+    """完整的 FFmpeg 合成命令描述。"""
+
+    command: list[str]
+    """可直接传给 subprocess.run 的命令列表。"""
+
+    filter_complex: str
+    """-filter_complex 参数值（方便调试 / 日志）。"""
+
+    input_paths: list[str]
+    """输入文件路径列表。"""
+
+    output_path: str
+    """输出文件路径。"""
+
+    estimated_duration: float
+    """预估输出时长（秒）。"""
+
+    clip_chains: list[ClipFilterChain]
+    """每个片段的滤镜链描述。"""
+
+
+@dataclass(frozen=True)
+class ComposeValidation:
+    """合成前校验结果。"""
+
+    valid: bool
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    ready_clip_count: int = 0
+    total_clip_count: int = 0
+
+
+# ── 服务主体 ──────────────────────────────────────────────────────────────────
+
+
+class VideoComposeService:
+    """FFmpeg 视频合成编排服务。
+
+    职责：
+    - 根据 EditPlan 及其 Clips 生成 FFmpeg filter_complex 命令
+    - 校验合成前置条件
+    - 提供合成状态查询
+
+    用法::
+
+        svc = VideoComposeService(db)
+        validation = svc.validate_compose(plan_id)
+        if validation.valid:
+            cmd = svc.build_compose_command(plan_id, output_path="/tmp/out.mp4")
+            subprocess.run(cmd.command, check=True)
+    """
+
+    def __init__(self, db: Session) -> None:
+        self._db = db
+        self._plan_repo = SQLAlchemyEditPlanRepository(db)
+        self._clip_repo = SQLAlchemyEditPlanClipRepository(db)
+
+    # ── 公开方法 ──────────────────────────────────────────────────────────
+
+    def validate_compose(self, plan_id: str) -> ComposeValidation:
+        """校验剪辑计划是否可以合成。
+
+        检查项：
+        1. 计划存在
+        2. 计划状态为 editing 或 rendering
+        3. 至少有一个 ready 状态的片段
+        4. 每个 ready 片段都有 asset_id
+        5. 每个 ready 片段都有 duration > 0
+        """
+        errors: list[str] = []
+        warnings: list[str] = []
+
+        plan = self._plan_repo.get(plan_id)
+        if plan is None:
+            return ComposeValidation(
+                valid=False,
+                errors=[f"剪辑计划不存在: {plan_id}"],
+            )
+
+        # 状态检查
+        if plan.status not in (EditPlanStatus.EDITING, EditPlanStatus.RENDERING):
+            errors.append(f"计划状态不正确，需要 editing 或 rendering，当前: {plan.status.value}")
+
+        # 加载片段
+        clips = self._clip_repo.list_by_plan(plan_id, skip=0, limit=10000)
+        if not clips:
+            errors.append("计划没有任何片段")
+            return ComposeValidation(
+                valid=False,
+                errors=errors,
+                total_clip_count=0,
+            )
+
+        # 按 order 排序
+        clips.sort(key=lambda c: c.order)
+
+        ready_count = 0
+        pending_count = 0
+        no_asset_count = 0
+        no_duration_count = 0
+
+        for clip in clips:
+            if clip.status == EditPlanClipStatus.READY:
+                ready_count += 1
+                if not clip.asset_id:
+                    errors.append(f"片段 {clip.id} (order={clip.order}) 没有分配素材")
+                    no_asset_count += 1
+                if clip.duration <= 0:
+                    warnings.append(f"片段 {clip.id} (order={clip.order}) 时长为 0，将使用默认时长")
+                    no_duration_count += 1
+            elif clip.status == EditPlanClipStatus.PENDING:
+                pending_count += 1
+            elif clip.status == EditPlanClipStatus.FAILED:
+                warnings.append(f"片段 {clip.id} (order={clip.order}) 状态为 failed，已跳过")
+
+        if ready_count == 0:
+            errors.append("没有就绪（ready）的片段可以合成")
+
+        if pending_count > 0:
+            warnings.append(f"有 {pending_count} 个片段仍处于 pending 状态")
+
+        return ComposeValidation(
+            valid=len(errors) == 0,
+            errors=errors,
+            warnings=warnings,
+            ready_clip_count=ready_count,
+            total_clip_count=len(clips),
+        )
+
+    def build_compose_command(
+        self,
+        plan_id: str,
+        output_path: str,
+        *,
+        output_width: int = DEFAULT_OUTPUT_WIDTH,
+        output_height: int = DEFAULT_OUTPUT_HEIGHT,
+        fps: int = DEFAULT_FPS,
+        codec: str = DEFAULT_CODEC,
+        crf: int = DEFAULT_CRF,
+        preset: str = DEFAULT_PRESET,
+        transition_duration: float = DEFAULT_TRANSITION_DURATION,
+    ) -> ComposeCommand:
+        """构建 FFmpeg 合成命令。
+
+        根据 EditPlan 的所有 ready 片段，生成完整的 filter_complex 命令。
+
+        滤镜链逻辑：
+        - 每个片段：scale → crop → setpts → trim → atrim
+        - 多片段之间：concat 滤镜 或 xfade 转场
+        - 最终输出：-map '[outv]' -map '[outa]'（如有音频）
+        """
+        plan = self._plan_repo.get(plan_id)
+        if plan is None:
+            raise ValueError(f"剪辑计划不存在: {plan_id}")
+
+        clips = self._clip_repo.list_by_plan(plan_id, skip=0, limit=10000)
+        if not clips:
+            raise ValueError(f"剪辑计划没有片段: {plan_id}")
+
+        # 只处理 ready 且有 asset_id 的片段
+        ready_clips = [c for c in clips if c.status == EditPlanClipStatus.READY and c.asset_id]
+        ready_clips.sort(key=lambda c: c.order)
+
+        if not ready_clips:
+            raise ValueError(f"剪辑计划没有可合成的片段: {plan_id}")
+
+        # 构建每个片段的滤镜链
+        clip_chains: list[ClipFilterChain] = []
+        input_paths: list[str] = []
+
+        for idx, clip in enumerate(ready_clips):
+            chain = self._build_clip_filter(
+                clip=clip,
+                input_index=idx,
+                output_width=output_width,
+                output_height=output_height,
+                fps=fps,
+            )
+            clip_chains.append(chain)
+            input_paths.append(clip.asset_id)  # asset_id 存储的是 storage_key / URL
+
+        # 构建 filter_complex
+        filter_complex, estimated_duration = self._build_filter_complex(
+            clip_chains=clip_chains,
+            output_width=output_width,
+            output_height=output_height,
+            transition_duration=transition_duration,
+            transitions=[c.transition_effect for c in ready_clips],
+        )
+
+        # 构建完整命令
+        command: list[str] = ["ffmpeg", "-y"]
+
+        # 输入文件
+        for path in input_paths:
+            command.extend(["-i", path])
+
+        # filter_complex
+        command.extend(["-filter_complex", filter_complex])
+
+        # 映射输出流
+        command.extend(["-map", "[outv]"])
+        if self._has_audio(clip_chains):
+            command.extend(["-map", "[outa]"])
+
+        # 编码参数
+        command.extend(
+            [
+                "-c:v",
+                codec,
+                "-crf",
+                str(crf),
+                "-preset",
+                preset,
+                "-c:a",
+                "aac",
+                "-b:a",
+                "192k",
+            ]
+        )
+
+        # 输出
+        command.append(output_path)
+
+        return ComposeCommand(
+            command=command,
+            filter_complex=filter_complex,
+            input_paths=input_paths,
+            output_path=output_path,
+            estimated_duration=estimated_duration,
+            clip_chains=clip_chains,
+        )
+
+    def build_single_clip_command(
+        self,
+        clip_id: str,
+        output_path: str,
+        *,
+        output_width: int = DEFAULT_OUTPUT_WIDTH,
+        output_height: int = DEFAULT_OUTPUT_HEIGHT,
+        fps: int = DEFAULT_FPS,
+    ) -> ComposeCommand:
+        """为单个片段构建 FFmpeg 命令（预览 / 调试用）。"""
+        clip = self._clip_repo.get(clip_id)
+        if clip is None:
+            raise ValueError(f"片段不存在: {clip_id}")
+        if not clip.asset_id:
+            raise ValueError(f"片段没有分配素材: {clip_id}")
+
+        chain = self._build_clip_filter(
+            clip=clip,
+            input_index=0,
+            output_width=output_width,
+            output_height=output_height,
+            fps=fps,
+        )
+
+        # 简单命令：input → filter → output
+        filter_str = ",".join(chain.filters)
+        command = [
+            "ffmpeg",
+            "-y",
+            "-i",
+            clip.asset_id,
+            "-filter_complex",
+            f"{filter_str}[outv]",
+            "-map",
+            "[outv]",
+            "-c:v",
+            DEFAULT_CODEC,
+            "-crf",
+            str(DEFAULT_CRF),
+            "-preset",
+            DEFAULT_PRESET,
+            output_path,
+        ]
+
+        return ComposeCommand(
+            command=command,
+            filter_complex=filter_str,
+            input_paths=[clip.asset_id],
+            output_path=output_path,
+            estimated_duration=clip.duration,
+            clip_chains=[chain],
+        )
+
+    def get_compose_status(self, plan_id: str) -> dict[str, Any]:
+        """获取合成状态摘要。"""
+        plan = self._plan_repo.get(plan_id)
+        if plan is None:
+            raise ValueError(f"剪辑计划不存在: {plan_id}")
+
+        clips = self._clip_repo.list_by_plan(plan_id, skip=0, limit=10000)
+        clips.sort(key=lambda c: c.order)
+
+        total_duration = sum(c.duration for c in clips if c.duration > 0)
+        ready_clips = [c for c in clips if c.status == EditPlanClipStatus.READY]
+        pending_clips = [c for c in clips if c.status == EditPlanClipStatus.PENDING]
+        rendered_clips = [c for c in clips if c.status == EditPlanClipStatus.RENDERED]
+        failed_clips = [c for c in clips if c.status == EditPlanClipStatus.FAILED]
+
+        return {
+            "plan_id": plan_id,
+            "plan_status": plan.status.value,
+            "total_clips": len(clips),
+            "ready_clips": len(ready_clips),
+            "pending_clips": len(pending_clips),
+            "rendered_clips": len(rendered_clips),
+            "failed_clips": len(failed_clips),
+            "total_duration": total_duration,
+            "can_compose": len(ready_clips) > 0
+            and plan.status
+            in (
+                EditPlanStatus.EDITING,
+                EditPlanStatus.RENDERING,
+            ),
+            "rendered_url": plan.config.get("rendered_url", ""),
+        }
+
+    # ── 内部方法 ──────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _build_clip_filter(
+        clip: EditPlanClip,
+        input_index: int,
+        output_width: int,
+        output_height: int,
+        fps: int,
+    ) -> ClipFilterChain:
+        """为单个片段构建滤镜链。
+
+        滤镜顺序：
+        1. scale — 等比缩放到目标分辨率（保证覆盖）
+        2. crop — 居中裁剪到目标分辨率
+        3. setpts — 重置时间戳 + 偏移
+        4. trim — 视频时长裁剪
+        5. atrim — 音频时长裁剪（如有音频流）
+        """
+        duration = clip.duration if clip.duration > 0 else 5.0  # 默认 5 秒
+        start = clip.start_time
+
+        filters: list[str] = []
+
+        # 1. scale: 等比缩放，保证覆盖目标区域（scale to larger, then crop）
+        filters.append(f"scale={output_width}:{output_height}" f":force_original_aspect_ratio=increase")
+
+        # 2. crop: 居中裁剪
+        filters.append(f"crop={output_width}:{output_height}")
+
+        # 3. setpts: 重置时间戳
+        if start > 0:
+            filters.append(f"setpts=PTS-STARTPTS+{start}/TB")
+        else:
+            filters.append("setpts=PTS-STARTPTS")
+
+        # 4. trim: 视频时长
+        filters.append(f"trim=0:{duration}")
+        filters.append("setpts=PTS-STARTPTS")  # trim 后需要重置 PTS
+
+        video_label = f"v{input_index}"
+
+        # 5. 音频标签：仅当片段类型可能有音频时才设置
+        # title/subtitle 是纯文字/图片卡片，没有音频流
+        clip_type = clip.clip_type.lower() if clip.clip_type else ""
+        has_audio_stream = clip_type not in ("title", "subtitle")
+        audio_label = f"a{input_index}" if has_audio_stream else None
+
+        return ClipFilterChain(
+            clip_id=clip.id,
+            input_index=input_index,
+            video_label=video_label,
+            audio_label=audio_label,
+            filters=filters,
+            duration=duration,
+        )
+
+    @staticmethod
+    def _build_filter_complex(
+        clip_chains: list[ClipFilterChain],
+        output_width: int,
+        output_height: int,
+        transition_duration: float,
+        transitions: list[str],
+    ) -> tuple[str, float]:
+        """构建完整的 filter_complex 字符串。
+
+        策略：
+        - 单片段：直接输出
+        - 多片段 + 全 cut：使用 concat 滤镜（高效）
+        - 多片段 + 有转场：使用 xfade 滤镜链
+
+        返回 (filter_complex_string, estimated_total_duration)。
+        """
+        n = len(clip_chains)
+
+        if n == 0:
+            return "", 0.0
+
+        # ── 单片段 ─────────────────────────────────────────────────────
+        if n == 1:
+            chain = clip_chains[0]
+            filter_str = _chain_filters(chain.filters, chain.video_label)
+            # 音频
+            if chain.audio_label:
+                filter_str += f";[0:a]{chain.audio_label}"
+            total_duration = chain.duration
+            return filter_str, total_duration
+
+        # ── 检查是否有转场 ─────────────────────────────────────────────
+        has_transitions = any(t != TransitionEffect.CUT and t != "cut" for t in transitions)
+
+        if not has_transitions:
+            return _build_concat_filter(clip_chains)
+
+        # ── 有转场：使用 xfade ─────────────────────────────────────────
+        return _build_xfade_filter(
+            clip_chains=clip_chains,
+            transition_duration=transition_duration,
+            transitions=transitions,
+        )
+
+    @staticmethod
+    def _has_audio(clip_chains: list[ClipFilterChain]) -> bool:
+        """是否有任何片段包含音频流。"""
+        return any(c.audio_label is not None for c in clip_chains)
+
+
+# ── 模块级辅助函数 ────────────────────────────────────────────────────────────
+
+
+def _chain_filters(filters: list[str], output_label: str) -> str:
+    """将滤镜列表串联为 FFmpeg 滤镜字符串。"""
+    filter_body = ",".join(filters)
+    return f"[0:v]{filter_body}[{output_label}]"
+
+
+def _build_concat_filter(
+    clip_chains: list[ClipFilterChain],
+) -> tuple[str, float]:
+    """构建 concat 滤镜（无转场，高效拼接）。
+
+    格式：
+    [0:v]filters[v0]; [1:v]filters[v1]; ...
+    [v0][v1]...[vN]concat=n=N:v=1:a=0[outv]
+    """
+    n = len(clip_chains)
+    parts: list[str] = []
+    total_duration = 0.0
+
+    # 每个片段的滤镜链
+    for idx, chain in enumerate(clip_chains):
+        filter_body = ",".join(chain.filters)
+        parts.append(f"[{idx}:v]{filter_body}[{chain.video_label}]")
+        total_duration += chain.duration
+
+    # concat 滤镜
+    concat_inputs = "".join(f"[{c.video_label}]" for c in clip_chains)
+    concat_filter = f"{concat_inputs}concat=n={n}:v=1:a=0[outv]"
+    parts.append(concat_filter)
+
+    # 音频 concat（如果有）
+    audio_parts: list[str] = []
+    for idx, chain in enumerate(clip_chains):
+        if chain.audio_label:
+            audio_parts.append(f"[{idx}:a]atrim=0:{chain.duration},asetpts=PTS-STARTPTS[{chain.audio_label}]")
+
+    if audio_parts:
+        parts.extend(audio_parts)
+        audio_inputs = "".join(f"[{c.audio_label}]" for c in clip_chains if c.audio_label)
+        audio_count = sum(1 for c in clip_chains if c.audio_label)
+        if audio_count > 0:
+            parts.append(f"{audio_inputs}concat=n={audio_count}:v=0:a=1[outa]")
+
+    return ";".join(parts), total_duration
+
+
+def _build_xfade_filter(
+    clip_chains: list[ClipFilterChain],
+    transition_duration: float,
+    transitions: list[str],
+) -> tuple[str, float]:
+    """构建 xfade 转场滤镜链。
+
+    每两个相邻片段之间插入 xfade 转场。
+    offset = 前一个片段的累积时长 - 转场时长。
+
+    格式（2 片段）：
+    [0:v]filters[v0]; [1:v]filters[v1];
+    [v0][v1]xfade=transition=fade:duration=0.5:offset=4.5[outv]
+
+    格式（3+ 片段）：
+    [v0][v1]xfade=...[tmp1]; [tmp1][v2]xfade=...[outv]
+    """
+    n = len(clip_chains)
+    parts: list[str] = []
+    total_duration = 0.0
+
+    # 每个片段的滤镜链
+    for idx, chain in enumerate(clip_chains):
+        filter_body = ",".join(chain.filters)
+        parts.append(f"[{idx}:v]{filter_body}[{chain.video_label}]")
+        total_duration += chain.duration
+
+    # xfade 链
+    if n == 1:
+        # 单片段不需要 xfade
+        parts.append(f"[{clip_chains[0].video_label}]copy[outv]")
+        return ";".join(parts), total_duration
+
+    # 计算每个转场的 offset
+    cumulative = 0.0
+    prev_label = clip_chains[0].video_label
+
+    for i in range(1, n):
+        cumulative += clip_chains[i - 1].duration
+        offset = max(0.0, cumulative - transition_duration * i)
+
+        # 获取转场类型
+        transition = transitions[i] if i < len(transitions) else "cut"
+        xfade_transition = _XFADE_TRANSITION_MAP.get(transition, "fade")
+
+        if i == n - 1:
+            # 最后一个转场，输出到 [outv]
+            out_label = "outv"
+        else:
+            out_label = f"xf{i}"
+
+        parts.append(
+            f"[{prev_label}][{clip_chains[i].video_label}]"
+            f"xfade=transition={xfade_transition}"
+            f":duration={transition_duration}"
+            f":offset={offset:.3f}"
+            f"[{out_label}]"
+        )
+        prev_label = out_label
+
+    # 总时长需要减去转场重叠部分
+    total_duration -= transition_duration * (n - 1)
+
+    # 音频 crossfade（简化处理：使用 adelay + amix）
+    audio_labels = [c.audio_label for c in clip_chains if c.audio_label]
+    if len(audio_labels) >= 2:
+        # 简单拼接音频（不做 crossfade）
+        audio_inputs = "".join(f"[{label}]" for label in audio_labels)
+        parts.append(f"{audio_inputs}concat=n={len(audio_labels)}:v=0:a=1[outa]")
+    elif len(audio_labels) == 1:
+        parts.append(f"[{audio_labels[0]}]acopy[outa]")
+
+    return ";".join(parts), max(0.0, total_duration)

apps/api/main.py

@@ -9,7 +9,7 @@ from app.middleware.exceptions import (
     http_exception_handler,
     validation_exception_handler,
 )
-from app.middleware.logging import RequestLoggingMiddleware
+from app.middleware.logging import RateLimitMiddleware, RequestLoggingMiddleware
 from app.middleware.prometheus_metrics import PrometheusMetricsMiddleware, metrics_endpoint
 from fastapi import FastAPI
 from fastapi.exceptions import RequestValidationError
@@ -22,8 +22,9 @@ app = FastAPI(
     title="小虾 SaaS API",
     description="自动化剪辑 SaaS 平台 API",
     version=settings.APP_VERSION,
-    docs_url="/docs",
-    redoc_url="/redoc",
+    docs_url=None if settings.ENVIRONMENT == "production" else "/docs",
+    redoc_url=None if settings.ENVIRONMENT == "production" else "/redoc",
+    openapi_url=None if settings.ENVIRONMENT == "production" else "/openapi.json",
     redirect_slashes=False,
 )
 
@@ -53,6 +54,8 @@ app.add_middleware(
     allow_headers=["Authorization", "Content-Type"],
 )
 app.add_middleware(GZipMiddleware, minimum_size=1000)
+# P0-1: 登录接口限流 - 每 IP 每分钟最多 10 次登录尝试
+app.add_middleware(RateLimitMiddleware, max_requests=10, window_seconds=60, paths=["/api/v1/auth/login"])
 app.add_middleware(RequestLoggingMiddleware)
 app.add_middleware(PrometheusMetricsMiddleware)
 

apps/web/.eslintrc.cjs

@@ -5,19 +5,19 @@ module.exports = {
   root: true,
   env: { browser: true, es2020: true },
   extends: [
-    'eslint:recommended',
-    'plugin:@typescript-eslint/recommended',
-    'plugin:react-hooks/recommended',
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:react-hooks/recommended",
   ],
-  ignorePatterns: ['dist', '.eslintrc.cjs'],
-  parser: '@typescript-eslint/parser',
-  plugins: ['react-refresh'],
+  ignorePatterns: ["dist", ".eslintrc.cjs"],
+  parser: "@typescript-eslint/parser",
+  plugins: ["react-refresh"],
   rules: {
-    'react-refresh/only-export-components': [
-      'warn',
+    "react-refresh/only-export-components": [
+      "warn",
       { allowConstantExport: true },
     ],
-    '@typescript-eslint/no-explicit-any': 'warn',
-    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/no-unused-vars": ["warn", { argsIgnorePattern: "^_" }],
   },
-}
+};

apps/web/README.md

@@ -91,7 +91,7 @@ VITE_API_URL=http://localhost:8000
 使用 Zustand 创建 Store：
 
 ```typescript
-import { create } from 'zustand';
+import { create } from "zustand";
 
 interface MyStore {
   data: any;

apps/web/app/components/CreateIssueForm.tsx

@@ -1,147 +0,0 @@
-'use client';
-
-import { useState } from 'react';
-
-const API_BASE = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000';
-
-interface CreateIssueFormProps {
-  taskId: string;
-  projectId: string;
-  workspaceId: string;
-  onSuccess: () => void;
-  onCancel: () => void;
-}
-
-export default function CreateIssueForm({ taskId, projectId, workspaceId, onSuccess, onCancel }: CreateIssueFormProps) {
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState('');
-  const [formData, setFormData] = useState({
-    title: '',
-    description: '',
-  });
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    setLoading(true);
-    setError('');
-
-    try {
-      const res = await fetch(`${API_BASE}/api/v1/project-management/issues`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          task_id: taskId,
-          project_id: projectId,
-          workspace_id: workspaceId,
-          ...formData,
-        }),
-      });
-
-      if (!res.ok) {
-        const data = await res.json();
-        throw new Error(data.detail || '创建失败');
-      }
-
-      onSuccess();
-    } catch (err: unknown) {
-      setError(err instanceof Error ? err.message : String(err));
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return (
-    <form onSubmit={handleSubmit} style={{
-      background: 'var(--bg-white)',
-      padding: '20px',
-      borderRadius: '8px',
-      border: '1px solid var(--border)',
-    }}>
-      {error && (
-        <div style={{
-          padding: '12px',
-          background: '#FFECE8',
-          border: '1px solid var(--error)',
-          borderRadius: '4px',
-          color: 'var(--error)',
-          marginBottom: '16px',
-        }}>
-          {error}
-        </div>
-      )}
-
-      <div style={{ marginBottom: '12px' }}>
-        <label style={{ display: 'block', marginBottom: '6px', fontWeight: '500' }}>
-          问题标题 <span style={{ color: 'var(--error)' }}>*</span>
-        </label>
-        <input
-          type="text"
-          required
-          value={formData.title}
-          onChange={(e) => setFormData({ ...formData, title: e.target.value })}
-          style={{
-            width: '100%',
-            padding: '8px 12px',
-            border: '1px solid var(--border)',
-            borderRadius: '4px',
-            fontSize: '14px',
-          }}
-          placeholder="简要描述问题"
-        />
-      </div>
-
-      <div style={{ marginBottom: '16px' }}>
-        <label style={{ display: 'block', marginBottom: '6px', fontWeight: '500' }}>
-          详细描述
-        </label>
-        <textarea
-          value={formData.description}
-          onChange={(e) => setFormData({ ...formData, description: e.target.value })}
-          rows={3}
-          style={{
-            width: '100%',
-            padding: '8px 12px',
-            border: '1px solid var(--border)',
-            borderRadius: '4px',
-            fontSize: '14px',
-            resize: 'vertical',
-          }}
-          placeholder="详细说明问题情况"
-        />
-      </div>
-
-      <div style={{ display: 'flex', gap: '10px' }}>
-        <button
-          type="submit"
-          disabled={loading}
-          style={{
-            flex: 1,
-            padding: '8px',
-            borderRadius: '4px',
-            border: 'none',
-            background: loading ? '#ccc' : 'var(--primary)',
-            color: 'white',
-            fontWeight: 'bold',
-            cursor: loading ? 'not-allowed' : 'pointer',
-          }}
-        >
-          {loading ? '创建中...' : '创建问题'}
-        </button>
-        <button
-          type="button"
-          onClick={onCancel}
-          style={{
-            flex: 1,
-            padding: '8px',
-            borderRadius: '4px',
-            border: '1px solid var(--border)',
-            background: 'white',
-            cursor: 'pointer',
-          }}
-        >
-          取消
-        </button>
-      </div>
-    </form>
-  );
-}

apps/web/app/components/CreateTaskForm.tsx

@@ -1,200 +0,0 @@
-'use client';
-
-import { useState } from 'react';
-import { useRouter } from 'next/navigation';
-
-const API_BASE = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000';
-
-interface CreateTaskFormProps {
-  projectId: string;
-  workspaceId: string;
-  onSuccess?: () => void;
-  onCancel?: () => void;
-}
-
-export default function CreateTaskForm({ projectId, workspaceId, onSuccess, onCancel }: CreateTaskFormProps) {
-  const router = useRouter();
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState('');
-  const [formData, setFormData] = useState({
-    name: '',
-    description: '',
-    priority: 'medium',
-    assignee_user_id: '',
-    parent_task_id: '',
-  });
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    setLoading(true);
-    setError('');
-
-    try {
-      const res = await fetch(`${API_BASE}/api/v1/project-management/tasks`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          project_id: projectId,
-          workspace_id: workspaceId,
-          ...formData,
-        }),
-      });
-
-      if (!res.ok) {
-        const data = await res.json();
-        throw new Error(data.detail || '创建失败');
-      }
-
-      if (onSuccess) {
-        onSuccess();
-      } else {
-        router.push('/projects');
-      }
-    } catch (err: unknown) {
-      setError(err instanceof Error ? err.message : String(err));
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return (
-    <form onSubmit={handleSubmit} style={{
-      background: 'var(--bg-white)',
-      padding: '24px',
-      borderRadius: '8px',
-      maxWidth: '600px',
-      margin: '0 auto',
-    }}>
-      <h2 style={{ marginBottom: '20px', fontSize: '20px', fontWeight: 'bold' }}>新增任务</h2>
-
-      {error && (
-        <div style={{
-          padding: '12px',
-          background: '#FFECE8',
-          border: '1px solid var(--error)',
-          borderRadius: '4px',
-          color: 'var(--error)',
-          marginBottom: '20px',
-        }}>
-          {error}
-        </div>
-      )}
-
-      <div style={{ marginBottom: '16px' }}>
-        <label style={{ display: 'block', marginBottom: '8px', fontWeight: '500' }}>
-          任务名称 <span style={{ color: 'var(--error)' }}>*</span>
-        </label>
-        <input
-          type="text"
-          required
-          value={formData.name}
-          onChange={(e) => setFormData({ ...formData, name: e.target.value })}
-          style={{
-            width: '100%',
-            padding: '8px 12px',
-            border: '1px solid var(--border)',
-            borderRadius: '4px',
-            fontSize: '14px',
-          }}
-          placeholder="输入任务名称"
-        />
-      </div>
-
-      <div style={{ marginBottom: '16px' }}>
-        <label style={{ display: 'block', marginBottom: '8px', fontWeight: '500' }}>
-          任务描述
-        </label>
-        <textarea
-          value={formData.description}
-          onChange={(e) => setFormData({ ...formData, description: e.target.value })}
-          rows={4}
-          style={{
-            width: '100%',
-            padding: '8px 12px',
-            border: '1px solid var(--border)',
-            borderRadius: '4px',
-            fontSize: '14px',
-            resize: 'vertical',
-          }}
-          placeholder="详细描述任务内容"
-        />
-      </div>
-
-      <div style={{ marginBottom: '16px' }}>
-        <label style={{ display: 'block', marginBottom: '8px', fontWeight: '500' }}>
-          优先级
-        </label>
-        <select
-          value={formData.priority}
-          onChange={(e) => setFormData({ ...formData, priority: e.target.value })}
-          style={{
-            width: '100%',
-            padding: '8px 12px',
-            border: '1px solid var(--border)',
-            borderRadius: '4px',
-            fontSize: '14px',
-          }}
-        >
-          <option value="low">低</option>
-          <option value="medium">中</option>
-          <option value="high">高</option>
-          <option value="urgent">紧急</option>
-        </select>
-      </div>
-
-      <div style={{ marginBottom: '16px' }}>
-        <label style={{ display: 'block', marginBottom: '8px', fontWeight: '500' }}>
-          负责人 ID（可选）
-        </label>
-        <input
-          type="text"
-          value={formData.assignee_user_id}
-          onChange={(e) => setFormData({ ...formData, assignee_user_id: e.target.value })}
-          style={{
-            width: '100%',
-            padding: '8px 12px',
-            border: '1px solid var(--border)',
-            borderRadius: '4px',
-            fontSize: '14px',
-          }}
-          placeholder="输入负责人 ID"
-        />
-      </div>
-
-      <div style={{ display: 'flex', gap: '12px', marginTop: '24px' }}>
-        <button
-          type="submit"
-          disabled={loading}
-          style={{
-            flex: 1,
-            padding: '10px',
-            borderRadius: '4px',
-            border: 'none',
-            background: loading ? '#ccc' : 'var(--primary)',
-            color: 'white',
-            fontWeight: 'bold',
-            cursor: loading ? 'not-allowed' : 'pointer',
-          }}
-        >
-          {loading ? '创建中...' : '创建任务'}
-        </button>
-        {onCancel && (
-          <button
-            type="button"
-            onClick={onCancel}
-            style={{
-              flex: 1,
-              padding: '10px',
-              borderRadius: '4px',
-              border: '1px solid var(--border)',
-              background: 'white',
-              cursor: 'pointer',
-            }}
-          >
-            取消
-          </button>
-        )}
-      </div>
-    </form>
-  );
-}

apps/web/app/components/EditTaskForm.tsx

@@ -1,167 +0,0 @@
-'use client';
-
-import { useState } from 'react';
-
-const API_BASE = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000';
-
-interface EditTaskFormProps {
-  taskId: string;
-  initialData: {
-    name: string;
-    description: string;
-    priority: string;
-    assignee_user_id: string;
-  };
-  onSuccess?: () => void;
-  onCancel?: () => void;
-}
-
-export default function EditTaskForm({ taskId, initialData, onSuccess, onCancel }: EditTaskFormProps) {
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState('');
-  const [formData, setFormData] = useState(initialData);
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    setLoading(true);
-    setError('');
-
-    try {
-      const res = await fetch(`${API_BASE}/api/v1/project-management/tasks/${taskId}`, {
-        method: 'PATCH',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(formData),
-      });
-      
-      if (!res.ok) {
-        const data = await res.json();
-        throw new Error(data.detail || '保存失败');
-      }
-      
-      if (onSuccess) onSuccess();
-    } catch (err: unknown) {
-      setError(err instanceof Error ? err.message : String(err));
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return (
-    <form onSubmit={handleSubmit} style={{
-      background: 'var(--bg-white)',
-      padding: '24px',
-      borderRadius: '8px',
-      border: '1px solid var(--border)',
-    }}>
-      <h3 style={{ marginBottom: '20px', fontSize: '18px', fontWeight: 'bold' }}>编辑任务</h3>
-
-      {error && (
-        <div style={{
-          padding: '12px',
-          background: '#FFECE8',
-          border: '1px solid var(--error)',
-          borderRadius: '4px',
-          color: 'var(--error)',
-          marginBottom: '20px',
-        }}>
-          {error}
-        </div>
-      )}
-
-      <div style={{ marginBottom: '16px' }}>
-        <label style={{ display: 'block', marginBottom: '8px', fontWeight: '500' }}>
-          任务名称 <span style={{ color: 'var(--error)' }}>*</span>
-        </label>
-        <input
-          type="text"
-          required
-          value={formData.name}
-          onChange={(e) => setFormData({ ...formData, name: e.target.value })}
-          style={{
-            width: '100%',
-            padding: '8px 12px',
-            border: '1px solid var(--border)',
-            borderRadius: '4px',
-            fontSize: '14px',
-          }}
-        />
-      </div>
-
-      <div style={{ marginBottom: '16px' }}>
-        <label style={{ display: 'block', marginBottom: '8px', fontWeight: '500' }}>
-          任务描述
-        </label>
-        <textarea
-          value={formData.description}
-          onChange={(e) => setFormData({ ...formData, description: e.target.value })}
-          rows={4}
-          style={{
-            width: '100%',
-            padding: '8px 12px',
-            border: '1px solid var(--border)',
-            borderRadius: '4px',
-            fontSize: '14px',
-            resize: 'vertical',
-          }}
-        />
-      </div>
-
-      <div style={{ marginBottom: '16px' }}>
-        <label style={{ display: 'block', marginBottom: '8px', fontWeight: '500' }}>
-          优先级
-        </label>
-        <select
-          value={formData.priority}
-          onChange={(e) => setFormData({ ...formData, priority: e.target.value })}
-          style={{
-            width: '100%',
-            padding: '8px 12px',
-            border: '1px solid var(--border)',
-            borderRadius: '4px',
-            fontSize: '14px',
-          }}
-        >
-          <option value="low">低</option>
-          <option value="medium">中</option>
-          <option value="high">高</option>
-          <option value="urgent">紧急</option>
-        </select>
-      </div>
-
-      <div style={{ display: 'flex', gap: '12px', marginTop: '24px' }}>
-        <button
-          type="submit"
-          disabled={loading}
-          style={{
-            flex: 1,
-            padding: '10px',
-            borderRadius: '4px',
-            border: 'none',
-            background: loading ? '#ccc' : 'var(--primary)',
-            color: 'white',
-            fontWeight: 'bold',
-            cursor: loading ? 'not-allowed' : 'pointer',
-          }}
-        >
-          {loading ? '保存中...' : '保存修改'}
-        </button>
-        {onCancel && (
-          <button
-            type="button"
-            onClick={onCancel}
-            style={{
-              flex: 1,
-              padding: '10px',
-              borderRadius: '4px',
-              border: '1px solid var(--border)',
-              background: 'white',
-              cursor: 'pointer',
-            }}
-          >
-            取消
-          </button>
-        )}
-      </div>
-    </form>
-  );
-}

apps/web/app/globals.css

@@ -1,26 +0,0 @@
-* {
-  margin: 0;
-  padding: 0;
-  box-sizing: border-box;
-}
-
-body {
-  font-family: -apple-system, BlinkMacSystemFont, "Microsoft YaHei", sans-serif;
-  background: #F5F7FA;
-  color: #1D2129;
-  height: 100vh;
-  overflow: hidden;
-}
-
-:root {
-  --primary: #165DFF;
-  --primary-hover: #0e48d1;
-  --border: #E5E6EB;
-  --bg-white: #fff;
-  --bg-gray: #F5F7FA;
-  --text-primary: #1D2129;
-  --text-secondary: #6E7681;
-  --success: #00B42A;
-  --warning: #FF7D00;
-  --error: #F53F3F;
-}