Merge remote-tracking branch 'origin/develop' into ci/matrix-build-parallelism

The check_schema_metadata.py CI step was failing because the
edit_plans table gained a result_count column (INTEGER) in the
SQLAlchemy model but the snapshot was never updated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.gitea/workflows/ci-cd.yml

@@ -5,19 +5,32 @@ on:
     - main
     - develop
     - feature/**
+    - feat/**
     - bugfix/**
+    - fix/**
     - hotfix/**
     - release/**
+    - refactor/**
+    - perf/**
+    - docs/**
+    - chore/**
+    - ci/**
     tags:
     - v*
   pull_request:
     branches:
     - main
     - develop
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: "触发原因"
+        required: false
+        default: "手动触发 - CI漏触发补跑"
 permissions:
   contents: read
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
   cancel-in-progress: true
 jobs:
   validate:
@@ -68,7 +81,7 @@ jobs:
 
         python3 -m isort --version-number
 
-        python3 -m flake8 --version
+        python3 -m ruff --version
 
         bandit --version
 
@@ -79,23 +92,14 @@ jobs:
       shell: sh
       run: "set -eu\necho \"=== Installing detect-secrets ===\"\npython3 -m pip install -q detect-secrets\ndetect-secrets --version\necho \"\"\necho \"=== Running secret scan ===\"\ndetect-secrets scan \\\n  --all-files \\\n  --exclude-files '(^|/)(tests|test|e2e|__tests__|spec|docs|node_modules|site-packages|migrations|alembic|.gitea|.git|.pytest_cache|.next|dist|build)/' \\\n  --exclude-files '\\.(md|rst|txt|lock|example|sample|min\\.js|min\\.css|spec\\.ts|test\\.ts|test\\.py)$' \\\n  --exclude-files '(package-lock|yarn\\.lock|poetry\\.lock|Pipfile\\.lock)$' \\\n  --disable-plugin Base64HighEntropyString \\\n  --disable-plugin HexHighEntropyString \\\n  --disable-plugin BasicAuthDetector \\\n  --disable-plugin KeywordDetector \\\n  --disable-plugin IPPublicDetector \\\n  2>&1 | tee /tmp/secrets-scan.json\n\nFOUND=$(python3 -c \"\nimport json\ntry:\n    with open('/tmp/secrets-scan.json') as f:\n        data = json.load(f)\n    results = data.get('results', {})\n    total = sum(len(v) for\
         \ v in results.values())\n    print(total)\nexcept Exception:\n    print('error')\n\")\necho \"\"\necho \"Secrets detected: $FOUND\"\nif [ \"$FOUND\" != \"0\" ] && [ \"$FOUND\" != \"error\" ]; then\n  echo \"\"\n  echo \"=== Secret details ===\"\n  python3 -c \"\nimport json\nwith open('/tmp/secrets-scan.json') as f:\n    data = json.load(f)\nfor fpath, items in data.get('results', {}).items():\n    for item in items:\n        line = item.get('line_number', '?')\n        stype = item.get('type', '?')\n        hashed = item.get('hashed_secret', '')[:16]\n        print(f'  {fpath}:{line} [{stype}] {hashed}...')\n\"\n  echo \"\"\n  echo \"ERROR: Potential secrets detected in code!\"\n  echo \"If these are false positives, add exclusions in the CI workflow.\"\n  exit 1\nfi\necho \"Secret scan completed - no secrets detected\"\n"
+    - name: Calculate changed Python files (incremental scan)
+      shell: sh
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: "set -eu\nSCAN_MODE=\"full\"\nCHANGED_PY_FILES=\"\"\n\nif [ \"${GITHUB_EVENT_NAME:-}\" = \"pull_request\" ] && [ -n \"${GITHUB_REF_NAME:-}\" ]; then\n  echo \"PR mode (#${GITHUB_REF_NAME}) - fetching changed files from API\"\n\n  PR_NUMBER=$(echo \"$GITHUB_REF\" | sed 's|refs/pull/||; s|/.*||')\n  API_URL=\"${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?limit=100\"\n\n  set +e\n  RESPONSE=$(curl -s -w \"\\n%{http_code}\" -H \"Authorization: token ${GITHUB_TOKEN}\" \"${API_URL}\")\n  HTTP_CODE=$(echo \"$RESPONSE\" | tail -n1)\n  BODY=$(echo \"$RESPONSE\" | sed '$d')\n  set -e\n\n  if [ \"$HTTP_CODE\" = \"200\" ]; then\n    CHANGED_PY_FILES=$(echo \"$BODY\" | python3 -c \"\nimport json, sys\ntry:\n    files = json.load(sys.stdin)\n    py_files = [f['filename'] for f in files\n                if f['filename'].endswith('.py') and f['status'] != 'removed']\n    print(' '.join(py_files))\nexcept Exception:\n    print('')\n\")\n    if [ -n \"$CHANGED_PY_FILES\" ]; then\n      SCAN_MODE=\"incremental\"\n      FILE_COUNT=$(echo \"$CHANGED_PY_FILES\" | wc -w)\n      echo \"Changed Python files: ${FILE_COUNT}\"\n      echo \"$CHANGED_PY_FILES\" | tr ' ' '\\n' | grep -v '^$'\n    else\n      SCAN_MODE=\"skip_py\"\n      echo \"No Python files changed in this PR\"\n    fi\n  else\n    echo \"WARN: API returned HTTP $HTTP_CODE, falling back to full scan\"\n  fi\nelse\n  echo \"Full scan mode (not a PR event)\"\nfi\n\necho \"SCAN_MODE=$SCAN_MODE\" >> $GITHUB_ENV\necho \"CHANGED_PY_FILES=$CHANGED_PY_FILES\" >> $GITHUB_ENV\n"
     - name: Run code quality checks
       shell: sh
-      run: 'set -eu
-
-        python3 -m compileall -q alembic apps packages tests scripts
-
-        python3 -m black --check --fast alembic apps packages tests scripts
-
-        python3 -m isort --check-only alembic apps packages tests scripts
-
-        python3 -m flake8 apps packages tests --count --statistics
-
-        '
-    - name: Ruff lint (advisory mode - 摸底阶段)
-      if: always()
-      shell: sh
-      run: "set +e\necho \"=== Installing ruff ===\"\npython3 -m pip install -q ruff\nruff --version\necho \"\"\necho \"=== Running ruff lint (advisory mode) ===\"\necho \"告警模式，不阻断CI。用于摸底问题数量，后续分批修复后正式替换flake8。\"\necho \"\"\nruff check apps packages tests scripts             --statistics             --output-format concise             2>&1 | tail -30\nEXIT_CODE=$?\necho \"\"\nif [ \"$EXIT_CODE\" != \"0\" ]; then\n  echo \"ruff 发现 lint 问题（告警模式，不阻断）\"\n  echo \"问题分类统计见上方，后续将分批修复\"\nelse\n  echo \"ruff 检查全部通过 ✅\"\nfi\nexit 0\n"
+      run: "set -eu\n\nif [ \"$SCAN_MODE\" = \"incremental\" ]; then\n  echo \"=== Incremental scan mode ===\"\n\n  python3 -m compileall -q $CHANGED_PY_FILES\n\n  python3 -m black --check --fast $CHANGED_PY_FILES\n\n  python3 -m isort --check-only $CHANGED_PY_FILES\n\n  RUFF_FILES=$(echo \"$CHANGED_PY_FILES\" | tr ' ' '\\n' | grep -v '^scripts/' | tr '\\n' ' ')\n  if [ -n \"$RUFF_FILES\" ]; then\n    python3 -m ruff check $RUFF_FILES --statistics\n  else\n    echo \"No ruff-checkable files changed, skipping\"\n  fi\n\nelif [ \"$SCAN_MODE\" = \"skip_py\" ]; then\n  echo \"No Python files changed - skipping Python lint checks\"\n\nelse\n  echo \"=== Full scan mode ===\"\n\n  python3 -m compileall -q alembic apps packages tests scripts\n\n  python3 -m black --check --fast alembic apps packages tests scripts\n\n  python3 -m isort --check-only alembic apps packages tests scripts\n\n  python3 -m ruff check apps packages tests --statistics\nfi\n"
     - name: Type check (mypy, advisory mode)
       if: always()
       shell: sh
@@ -142,7 +146,7 @@ jobs:
       shell: sh
       env:
         GITHUB_TOKEN: ${{ github.token }}
-      run: "set -eu\nif command -v git >/dev/null 2>&1; then\n  git init -q\n  git config user.email \"ci@localhost\"\n  git config user.name \"CI\"\n  git add .\n  git commit -q -m \"current\"\n  REPO_URL=\"https://x-access-token:${GITHUB_TOKEN}@${GITHUB_SERVER_URL#https://}/${GITHUB_REPOSITORY}.git\"\n  git remote add origin \"$REPO_URL\"\n  git fetch origin main --depth=1 -q 2>/dev/null || echo \"WARN: cannot fetch main, will check all migrations\"\nelse\n  echo \"WARN: git not available, will check all migrations\"\nfi\n"
+      run: "set +e\nif command -v git >/dev/null 2>&1; then\n  if [ ! -d .git ]; then\n    git init -q\n    git config user.email \"ci@localhost\"\n    git config user.name \"CI\"\n    git add .\n    git commit -q -m \"current\"\n    REPO_URL=\"https://x-access-token:${GITHUB_TOKEN}@${GITHUB_SERVER_URL#https://}/${GITHUB_REPOSITORY}.git\"\n    git remote add origin \"$REPO_URL\"\n  fi\n  git fetch origin main --depth=1 -q 2>/dev/null || echo \"WARN: cannot fetch main, will check all migrations\"\nelse\n  echo \"WARN: git not available, will check all migrations\"\nfi\nexit 0\n"
     - name: Check migration safety
       shell: sh
       run: "set -eu\nif git rev-parse origin/main >/dev/null 2>&1; then\n  python3 scripts/check_migration_safety.py --allow-medium-risk --diff-against origin/main\nelse\n  python3 scripts/check_migration_safety.py --allow-medium-risk\nfi\n"
@@ -371,19 +375,19 @@ jobs:
         '
     - name: Install dependencies
       shell: sh
-      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'rm -rf node_modules/* 2>/dev/null; npm ci --include=dev'\n"
+      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'PACKAGE_LOCK_HASH=$(md5sum package-lock.json 2>/dev/null | cut -d\" \" -f1)\nCACHE_HASH_FILE=\"node_modules/.package-lock-hash\"\nCACHE_VALID=false\nif [ -f \"$CACHE_HASH_FILE\" ] && [ \"$(cat \"$CACHE_HASH_FILE\")\" = \"$PACKAGE_LOCK_HASH\" ] && [ -x \"node_modules/.bin/eslint\" ] && [ -x \"node_modules/.bin/tsc\" ] && [ -x \"node_modules/.bin/prettier\" ] && [ -x \"node_modules/.bin/vitest\" ]; then\n  CACHE_VALID=true\n  echo \"Cache hit: dependencies valid, skipping npm ci\"\nfi\nif [ \"$CACHE_VALID\" = \"false\" ]; then\n  echo \"Cache miss or invalid: running npm ci...\"\n  if ! npm ci --include=dev; then\n    echo \"npm ci failed, cleaning node_modules and retrying...\"\n    rm -rf node_modules\n    mkdir -p node_modules\n    npm ci --include=dev\n  fi\n  # Post-install integrity check: verify all critical tools exist\n  if [ ! -x \"node_modules/.bin/eslint\" ] || [ ! -x \"node_modules/.bin/tsc\" ] || [ ! -x \"node_modules/.bin/prettier\" ] || [ ! -x \"node_modules/.bin/vitest\" ]; then\n    echo \"Post-install check failed: critical binaries missing, cleaning and retrying...\"\n    rm -rf node_modules\n    mkdir -p node_modules\n    npm ci --include=dev\n  fi\n  echo \"$PACKAGE_LOCK_HASH\" > \"$CACHE_HASH_FILE\"\n  echo \"Dependencies installed, cache updated\"\nfi'\n"
     - name: Run ESLint
       shell: sh
-      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'npx eslint src --ext .ts,.tsx --max-warnings 50'\n"
+      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'npx --no-install eslint src --ext .ts,.tsx --max-warnings 50'\n"
     - name: Run TypeScript type check
       shell: sh
-      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'npx tsc --noEmit'\n"
+      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'npx --no-install tsc --noEmit'\n"
     - name: Run Prettier check
       shell: sh
-      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'npx prettier --check \"src/**/*.{ts,tsx,md}\"'\n"
+      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'npx --no-install prettier --check \"src/**/*.{ts,tsx,md}\"'\n"
     - name: Run Vitest tests
       shell: sh
-      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'ls node_modules/.bin/vitest 2>/dev/null && node_modules/.bin/vitest run src/test || npm exec vitest run src/test'\n"
+      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm \\\n  -v \"$PWD:/workspace\" \\\n  -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\" -w /workspace/apps/web \\\n  docker.m.daocloud.io/library/node:20 \\\n  sh -lc 'npx --no-install vitest run src/test'\n"
     - name: Job duration summary
       if: always()
       shell: sh
@@ -399,140 +403,38 @@ jobs:
         NOTIFY_MODE=failure JOB_NAME="Frontend Lint" python3 scripts/ci_notify.py
 
         '
-  build-staging-api:
-    name: Build Staging API Image
+  build-staging:
+    name: Build Staging ${{ matrix.service_display }} Image
     runs-on:
     - saas
     - build-farm
-    timeout-minutes: 30
-    needs:
-    - validate
-    - frontend-lint
-    if: github.event_name == 'push' && (github.ref_name == 'main' || github.ref_name == 'develop')
-    steps:
-    - name: Checkout code
-      shell: sh
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: "set -eu\npython3 - <<'INNERPY'\nimport io, os, tarfile, time, urllib.request, urllib.error\nurl = f\"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz\"\nrequest = urllib.request.Request(url, headers={\"Authorization\": f\"token {os.environ['GITHUB_TOKEN']}\"})\nlast_err = None\nfor attempt in range(5):\n    try:\n        with urllib.request.urlopen(request, timeout=120) as response:\n            archive = response.read()\n        break\n    except urllib.error.HTTPError as e:\n        last_err = e\n        if e.code >= 500 and attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...\")\n            time.sleep(wait)\n            continue\n        raise\n    except Exception as e:\n        last_err = e\n        if attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...\"\
-        )\n            time.sleep(wait)\n            continue\nelse:\n    raise last_err\nwith tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:\n    root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'\n    for member in tar.getmembers():\n        name = member.name\n        if name == root_prefix[:-1]:\n            continue\n        if name.startswith(root_prefix):\n            member.name = name[len(root_prefix):]\n        if member.name:\n            tar.extract(member, '.')\nINNERPY\n"
-    - name: Record job start time
-      shell: sh
-      run: 'set -eu
-
-        echo "JOB_START_TIME=$(date +%s)" >> $GITHUB_ENV
-
-        echo "Job started at $(date)"
-
-        '
-    - name: Docker login to Registry
-      shell: sh
-      env:
-        REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
-      run: 'set -eu
-
-        printf ''%s'' "${REGISTRY_TOKEN}" | docker login git.xiaoxiajianji.com -u xiaoxia --password-stdin
-
-        echo "Docker login successful"
-
-        '
-    - name: Setup cache strategy
-      shell: sh
-      run: "set -eu\n# develop/main 分支写回缓存，其他分支只读\nif [ \"${GITHUB_REF_NAME}\" = \"develop\" ] || [ \"${GITHUB_REF_NAME}\" = \"main\" ]; then\n  echo \"CACHE_MODE=read-write\" >> $GITHUB_ENV\n  echo \"Cache mode: read-write (will push cache)\"\nelse\n  echo \"CACHE_MODE=read-only\" >> $GITHUB_ENV\n  echo \"Cache mode: read-only\"\nfi\n"
-    - name: Setup buildx builder (docker-container driver)
-      shell: sh
-      run: "set -eu\n# 确保使用 docker-container driver 以支持 cache export 功能\nif ! docker buildx inspect ci-builder > /dev/null 2>&1; then\n  docker buildx create --use --name ci-builder --driver docker-container\n  echo \"Created ci-builder (docker-container driver)\"\nelse\n  docker buildx use ci-builder\n  echo \"Using existing ci-builder\"\nfi\ndocker buildx inspect --bootstrap\n"
-    - name: Build and push API image (buildx cache)
-      shell: sh
-      run: "set -eu\nREGISTRY=\"git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas\"\nIMAGE_NAME=\"xiaoxia-saas-api\"\nCACHE_REF=\"${REGISTRY}/api-cache:develop\"\n\nCACHE_FROM=\"type=registry,ref=${CACHE_REF},ignore-error=true\"\n\nif [ \"${CACHE_MODE}\" = \"read-write\" ]; then\n  CACHE_TO=\"type=registry,ref=${CACHE_REF},mode=max\"\n  echo \"Building API image with read-write cache...\"\n  docker buildx build             --build-arg APP_VERSION=\"${GITHUB_SHA}\"             --cache-from \"${CACHE_FROM}\"             --cache-to \"${CACHE_TO}\"             -f infra/docker/api.Dockerfile             -t \"${REGISTRY}/${IMAGE_NAME}:${GITHUB_SHA}\"             --push             .\nelse\n  echo \"Building API image with read-only cache...\"\n  docker buildx build             --build-arg APP_VERSION=\"${GITHUB_SHA}\"             --cache-from \"${CACHE_FROM}\"             -f infra/docker/api.Dockerfile             -t \"${REGISTRY}/${IMAGE_NAME}:${GITHUB_SHA}\"             --push             .\nfi\necho\
-        \ \"API image pushed: ${REGISTRY}/${IMAGE_NAME}:${GITHUB_SHA}\"\n"
-    - name: Job duration summary
-      if: always()
-      shell: sh
-      run: "set +eu\nif [ -n \"$JOB_START_TIME\" ]; then\n  END_TIME=$(date +%s)\n  DURATION=$((END_TIME - JOB_START_TIME))\n  MINS=$((DURATION / 60))\n  SECS=$((DURATION % 60))\n  echo \"JOB_DURATION_SECONDS=$DURATION\" >> $GITHUB_ENV\n  echo \"=== Job Duration: ${MINS}m${SECS}s ===\"\nelse\n  echo \"JOB_DURATION_SECONDS=0\" >> $GITHUB_ENV\n  echo \"=== Job Duration: unknown ===\"\nfi\n"
-    - 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="Build Staging API Image" python3 scripts/ci_notify.py
-
-        '
-  build-staging-worker:
-    name: Build Staging Worker Image
-    runs-on:
-    - saas
-    - build-farm
-    timeout-minutes: 40
-    needs:
-    - validate
-    - frontend-lint
-    if: github.event_name == 'push' && (github.ref_name == 'main' || github.ref_name == 'develop')
-    steps:
-    - name: Checkout code
-      shell: sh
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: "set -eu\npython3 - <<'INNERPY'\nimport io, os, tarfile, time, urllib.request, urllib.error\nurl = f\"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz\"\nrequest = urllib.request.Request(url, headers={\"Authorization\": f\"token {os.environ['GITHUB_TOKEN']}\"})\nlast_err = None\nfor attempt in range(5):\n    try:\n        with urllib.request.urlopen(request, timeout=120) as response:\n            archive = response.read()\n        break\n    except urllib.error.HTTPError as e:\n        last_err = e\n        if e.code >= 500 and attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...\")\n            time.sleep(wait)\n            continue\n        raise\n    except Exception as e:\n        last_err = e\n        if attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...\"\
-        )\n            time.sleep(wait)\n            continue\nelse:\n    raise last_err\nwith tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:\n    root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'\n    for member in tar.getmembers():\n        name = member.name\n        if name == root_prefix[:-1]:\n            continue\n        if name.startswith(root_prefix):\n            member.name = name[len(root_prefix):]\n        if member.name:\n            tar.extract(member, '.')\nINNERPY\n"
-    - name: Record job start time
-      shell: sh
-      run: 'set -eu
-
-        echo "JOB_START_TIME=$(date +%s)" >> $GITHUB_ENV
-
-        echo "Job started at $(date)"
-
-        '
-    - name: Docker login to Registry
-      shell: sh
-      env:
-        REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
-      run: 'set -eu
-
-        printf ''%s'' "${REGISTRY_TOKEN}" | docker login git.xiaoxiajianji.com -u xiaoxia --password-stdin
-
-        echo "Docker login successful"
-
-        '
-    - name: Setup cache strategy
-      shell: sh
-      run: "set -eu\n# develop/main 分支写回缓存，其他分支只读\nif [ \"${GITHUB_REF_NAME}\" = \"develop\" ] || [ \"${GITHUB_REF_NAME}\" = \"main\" ]; then\n  echo \"CACHE_MODE=read-write\" >> $GITHUB_ENV\n  echo \"Cache mode: read-write (will push cache)\"\nelse\n  echo \"CACHE_MODE=read-only\" >> $GITHUB_ENV\n  echo \"Cache mode: read-only\"\nfi\n"
-    - name: Setup buildx builder (docker-container driver)
-      shell: sh
-      run: "set -eu\n# 确保使用 docker-container driver 以支持 cache export 功能\nif ! docker buildx inspect ci-builder > /dev/null 2>&1; then\n  docker buildx create --use --name ci-builder --driver docker-container\n  echo \"Created ci-builder (docker-container driver)\"\nelse\n  docker buildx use ci-builder\n  echo \"Using existing ci-builder\"\nfi\ndocker buildx inspect --bootstrap\n"
-    - name: Build and push Worker image (buildx cache)
-      shell: sh
-      run: "set -eu\nREGISTRY=\"git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas\"\nIMAGE_NAME=\"xiaoxia-saas-worker\"\nCACHE_REF=\"${REGISTRY}/worker-cache:develop\"\n\nCACHE_FROM=\"type=registry,ref=${CACHE_REF},ignore-error=true\"\n\nif [ \"${CACHE_MODE}\" = \"read-write\" ]; then\n  CACHE_TO=\"type=registry,ref=${CACHE_REF},mode=min\"\n  echo \"Building Worker image with read-write cache...\"\n  docker buildx build             --build-arg APP_VERSION=\"${GITHUB_SHA}\"             --cache-from \"${CACHE_FROM}\"             --cache-to \"${CACHE_TO}\"             -f infra/docker/worker.Dockerfile             -t \"${REGISTRY}/${IMAGE_NAME}:${GITHUB_SHA}\"             --push             .\nelse\n  echo \"Building Worker image with read-only cache...\"\n  docker buildx build             --build-arg APP_VERSION=\"${GITHUB_SHA}\"             --cache-from \"${CACHE_FROM}\"             -f infra/docker/worker.Dockerfile             -t \"${REGISTRY}/${IMAGE_NAME}:${GITHUB_SHA}\"             --push   \
-        \          .\nfi\necho \"Worker image pushed: ${REGISTRY}/${IMAGE_NAME}:${GITHUB_SHA}\"\n"
-    - name: Job duration summary
-      if: always()
-      shell: sh
-      run: "set +eu\nif [ -n \"$JOB_START_TIME\" ]; then\n  END_TIME=$(date +%s)\n  DURATION=$((END_TIME - JOB_START_TIME))\n  MINS=$((DURATION / 60))\n  SECS=$((DURATION % 60))\n  echo \"JOB_DURATION_SECONDS=$DURATION\" >> $GITHUB_ENV\n  echo \"=== Job Duration: ${MINS}m${SECS}s ===\"\nelse\n  echo \"JOB_DURATION_SECONDS=0\" >> $GITHUB_ENV\n  echo \"=== Job Duration: unknown ===\"\nfi\n"
-    - 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="Build Staging Worker Image" python3 scripts/ci_notify.py
-
-        '
-  build-staging-web:
-    name: Build Staging Web Image
-    runs-on:
-    - saas
-    - build-farm
-    timeout-minutes: 30
+    timeout-minutes: ${{ matrix.timeout }}
     needs:
     - validate
     - frontend-lint
     if: github.event_name == 'push' && (github.ref_name == 'main' || github.ref_name == 'develop')
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - service: api
+          service_display: API
+          dockerfile: infra/docker/api.Dockerfile
+          image_name: xiaoxia-saas-api
+          cache_name: api-cache
+          timeout: 30
+        - service: worker
+          service_display: Worker
+          dockerfile: infra/docker/worker.Dockerfile
+          image_name: xiaoxia-saas-worker
+          cache_name: worker-cache
+          timeout: 40
+        - service: web
+          service_display: Web
+          dockerfile: infra/docker/web.Dockerfile
+          image_name: xiaoxia-saas-web
+          cache_name: web-cache
+          timeout: 30
     steps:
     - name: Checkout code
       shell: sh
@@ -564,15 +466,28 @@ jobs:
       shell: sh
       run: "set -eu\n# develop/main 分支写回缓存，其他分支只读\nif [ \"${GITHUB_REF_NAME}\" = \"develop\" ] || [ \"${GITHUB_REF_NAME}\" = \"main\" ]; then\n  echo \"CACHE_MODE=read-write\" >> $GITHUB_ENV\n  echo \"Cache mode: read-write (will push cache)\"\nelse\n  echo \"CACHE_MODE=read-only\" >> $GITHUB_ENV\n  echo \"Cache mode: read-only\"\nfi\n"
     - name: Build frontend assets (npm build)
+      if: matrix.service == 'web'
       shell: sh
-      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm           -v \"$PWD:/workspace\"           -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\"           -w /workspace/apps/web           docker.m.daocloud.io/library/node:20           sh -lc \"npm ci && npm run build\"\n\ntest -f apps/web/dist/index.html\necho \"Frontend build complete: $(ls apps/web/dist/ | head -5)\"\n"
+      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\n  echo \"Created npm cache volume: $NPM_CACHE_VOLUME\"\nfi\n\ndocker run --rm           -v \"$PWD:/workspace\"           -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\"           -w /workspace/apps/web           docker.m.daocloud.io/library/node:20           sh -lc \"npm ci && npx tsc --incremental --tsBuildInfoFile node_modules/.tsbuildinfo && npx vite build\"\n\ntest -f apps/web/dist/index.html\necho \"Frontend build complete: $(ls apps/web/dist/ | head -5)\"\n"
     - name: Setup buildx builder (docker-container driver)
       shell: sh
       run: "set -eu\n# 确保使用 docker-container driver 以支持 cache export 功能\nif ! docker buildx inspect ci-builder > /dev/null 2>&1; then\n  docker buildx create --use --name ci-builder --driver docker-container\n  echo \"Created ci-builder (docker-container driver)\"\nelse\n  docker buildx use ci-builder\n  echo \"Using existing ci-builder\"\nfi\ndocker buildx inspect --bootstrap\n"
-    - name: Build and push Web image (buildx cache)
+    - name: Build and push ${{ matrix.service_display }} image (buildx cache)
       shell: sh
-      run: "set -eu\nREGISTRY=\"git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas\"\nIMAGE_NAME=\"xiaoxia-saas-web\"\nCACHE_REF=\"${REGISTRY}/web-cache:develop\"\nNGINX_CONF=\"infra/docker/nginx-staging.conf\"\n\nCACHE_FROM=\"type=registry,ref=${CACHE_REF},ignore-error=true\"\n\nif [ \"${CACHE_MODE}\" = \"read-write\" ]; then\n  CACHE_TO=\"type=registry,ref=${CACHE_REF},mode=max\"\n  echo \"Building Web image with read-write cache...\"\n  docker buildx build             --cache-from \"${CACHE_FROM}\"             --cache-to \"${CACHE_TO}\"             -f infra/docker/web-artifact.Dockerfile             --build-arg \"NGINX_CONF=${NGINX_CONF}\"             -t \"${REGISTRY}/${IMAGE_NAME}:${GITHUB_SHA}\"             --push             .\nelse\n  echo \"Building Web image with read-only cache...\"\n  docker buildx build             --cache-from \"${CACHE_FROM}\"             -f infra/docker/web-artifact.Dockerfile             --build-arg \"NGINX_CONF=${NGINX_CONF}\"             -t \"${REGISTRY}/${IMAGE_NAME}:${GITHUB_SHA}\"\
-        \             --push             .\nfi\necho \"Web image pushed: ${REGISTRY}/${IMAGE_NAME}:${GITHUB_SHA}\"\n"
+      run: "set -eu
+REGISTRY=\"git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas\"
+IMAGE_TAG=\"${REGISTRY}/${{ matrix.image_name }}:${GITHUB_SHA}\"
+CACHE_REF=\"${REGISTRY}/${{ matrix.cache_name }}:${GITHUB_REF_NAME}\"
+
+bash scripts/ci/docker_build_push.sh \
+  ${{ matrix.dockerfile }} \
+  \"${IMAGE_TAG}\" \
+  \"${CACHE_REF}\" \
+  APP_VERSION=\"${GITHUB_SHA}\"
+
+echo
+echo \"${{ matrix.service_display }} image pushed: ${IMAGE_TAG}\"
+"
     - name: Job duration summary
       if: always()
       shell: sh
@@ -585,7 +500,7 @@ jobs:
         CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
       run: 'set +e
 
-        NOTIFY_MODE=failure JOB_NAME="Build Staging Web Image" python3 scripts/ci_notify.py
+        NOTIFY_MODE=failure JOB_NAME="Build Staging ${{ matrix.service_display }} Image" python3 scripts/ci_notify.py
 
         '
   deploy-staging:
@@ -593,9 +508,7 @@ jobs:
     runs-on: saas
     timeout-minutes: 15
     needs:
-    - build-staging-api
-    - build-staging-worker
-    - build-staging-web
+    - build-staging
     if: github.event_name == 'push' && (github.ref_name == 'main' || github.ref_name == 'develop')
     steps:
     - name: Checkout code
@@ -779,166 +692,36 @@ jobs:
         NOTIFY_MODE=failure JOB_NAME="Staging API Integration Tests" python3 scripts/ci_notify.py
 
         '
-  build-production-api:
-    name: Build Production API Image
+  build-production:
+    name: Build Production ${{ matrix.service_display }} Image
     runs-on:
     - saas
     - build-farm
-    timeout-minutes: 30
+    timeout-minutes: ${{ matrix.timeout }}
     needs:
-    - validate
-    - frontend-lint
-    if: startsWith(github.ref, 'refs/tags/v')
-    steps:
-    - name: Checkout code
-      shell: sh
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: "set -eu\npython3 - <<'INNERPY'\nimport io, os, tarfile, time, urllib.request, urllib.error\nurl = f\"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz\"\nrequest = urllib.request.Request(url, headers={\"Authorization\": f\"token {os.environ['GITHUB_TOKEN']}\"})\nlast_err = None\nfor attempt in range(5):\n    try:\n        with urllib.request.urlopen(request, timeout=120) as response:\n            archive = response.read()\n        break\n    except urllib.error.HTTPError as e:\n        last_err = e\n        if e.code >= 500 and attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...\")\n            time.sleep(wait)\n            continue\n        raise\n    except Exception as e:\n        last_err = e\n        if attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...\"\
-        )\n            time.sleep(wait)\n            continue\nelse:\n    raise last_err\nwith tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:\n    root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'\n    for member in tar.getmembers():\n        name = member.name\n        if name == root_prefix[:-1]:\n            continue\n        if name.startswith(root_prefix):\n            member.name = name[len(root_prefix):]\n        if member.name:\n            tar.extract(member, '.')\nINNERPY\n"
-    - name: Record job start time
-      shell: sh
-      run: 'set -eu
-
-        echo "JOB_START_TIME=$(date +%s)" >> $GITHUB_ENV
-
-        echo "Job started at $(date)"
-
-        '
-    - name: Docker login to Registry
-      shell: sh
-      env:
-        REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
-      run: 'set -eu
-
-        printf ''%s'' "${REGISTRY_TOKEN}" | docker login git.xiaoxiajianji.com -u xiaoxia --password-stdin
-
-        echo "Docker login successful"
-
-        '
-    - name: Setup buildx builder (docker-container driver)
-      shell: sh
-      run: "set -eu\n# 确保使用 docker-container driver 以支持 cache export 功能\nif ! docker buildx inspect ci-builder > /dev/null 2>&1; then\n  docker buildx create --use --name ci-builder --driver docker-container\n  echo \"Created ci-builder (docker-container driver)\"\nelse\n  docker buildx use ci-builder\n  echo \"Using existing ci-builder\"\nfi\ndocker buildx inspect --bootstrap\n"
-    - name: Build and push API image (buildx cache)
-      shell: sh
-      run: 'set -eu
-
-        REGISTRY="git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas"
-
-        IMAGE_NAME="xiaoxia-saas-api"
-
-        VERSION="${GITHUB_REF_NAME}"
-
-        CACHE_REF="${REGISTRY}/api-cache:main"
-
-
-        echo "Building Production API image: ${VERSION}"
-
-        docker buildx build           --build-arg APP_VERSION="${VERSION}"           --cache-from "type=registry,ref=${CACHE_REF},ignore-error=true"           --cache-to "type=registry,ref=${CACHE_REF},mode=max"           -f infra/docker/api.Dockerfile           -t "${REGISTRY}/${IMAGE_NAME}:${VERSION}"           --push           .
-
-        echo "Production API image pushed: ${REGISTRY}/${IMAGE_NAME}:${VERSION}"
-
-        '
-    - name: Job duration summary
-      if: always()
-      shell: sh
-      run: "set +eu\nif [ -n \"$JOB_START_TIME\" ]; then\n  END_TIME=$(date +%s)\n  DURATION=$((END_TIME - JOB_START_TIME))\n  MINS=$((DURATION / 60))\n  SECS=$((DURATION % 60))\n  echo \"JOB_DURATION_SECONDS=$DURATION\" >> $GITHUB_ENV\n  echo \"=== Job Duration: ${MINS}m${SECS}s ===\"\nelse\n  echo \"JOB_DURATION_SECONDS=0\" >> $GITHUB_ENV\n  echo \"=== Job Duration: unknown ===\"\nfi\n"
-    - 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="Build Production API Image" python3 scripts/ci_notify.py
-
-        '
-  build-production-worker:
-    name: Build Production Worker Image
-    runs-on:
-    - saas
-    - build-farm
-    timeout-minutes: 40
-    needs:
-    - validate
-    - frontend-lint
-    if: startsWith(github.ref, 'refs/tags/v')
-    steps:
-    - name: Checkout code
-      shell: sh
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: "set -eu\npython3 - <<'INNERPY'\nimport io, os, tarfile, time, urllib.request, urllib.error\nurl = f\"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz\"\nrequest = urllib.request.Request(url, headers={\"Authorization\": f\"token {os.environ['GITHUB_TOKEN']}\"})\nlast_err = None\nfor attempt in range(5):\n    try:\n        with urllib.request.urlopen(request, timeout=120) as response:\n            archive = response.read()\n        break\n    except urllib.error.HTTPError as e:\n        last_err = e\n        if e.code >= 500 and attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...\")\n            time.sleep(wait)\n            continue\n        raise\n    except Exception as e:\n        last_err = e\n        if attempt < 4:\n            wait = 2 ** attempt\n            print(f\"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...\"\
-        )\n            time.sleep(wait)\n            continue\nelse:\n    raise last_err\nwith tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:\n    root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'\n    for member in tar.getmembers():\n        name = member.name\n        if name == root_prefix[:-1]:\n            continue\n        if name.startswith(root_prefix):\n            member.name = name[len(root_prefix):]\n        if member.name:\n            tar.extract(member, '.')\nINNERPY\n"
-    - name: Record job start time
-      shell: sh
-      run: 'set -eu
-
-        echo "JOB_START_TIME=$(date +%s)" >> $GITHUB_ENV
-
-        echo "Job started at $(date)"
-
-        '
-    - name: Docker login to Registry
-      shell: sh
-      env:
-        REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
-      run: 'set -eu
-
-        printf ''%s'' "${REGISTRY_TOKEN}" | docker login git.xiaoxiajianji.com -u xiaoxia --password-stdin
-
-        echo "Docker login successful"
-
-        '
-    - name: Setup buildx builder (docker-container driver)
-      shell: sh
-      run: "set -eu\n# 确保使用 docker-container driver 以支持 cache export 功能\nif ! docker buildx inspect ci-builder > /dev/null 2>&1; then\n  docker buildx create --use --name ci-builder --driver docker-container\n  echo \"Created ci-builder (docker-container driver)\"\nelse\n  docker buildx use ci-builder\n  echo \"Using existing ci-builder\"\nfi\ndocker buildx inspect --bootstrap\n"
-    - name: Build and push Worker image (buildx cache)
-      shell: sh
-      run: 'set -eu
-
-        REGISTRY="git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas"
-
-        IMAGE_NAME="xiaoxia-saas-worker"
-
-        VERSION="${GITHUB_REF_NAME}"
-
-        CACHE_REF="${REGISTRY}/worker-cache:main"
-
-
-        echo "Building Production Worker image: ${VERSION}"
-
-        docker buildx build           --build-arg APP_VERSION="${VERSION}"           --cache-from "type=registry,ref=${CACHE_REF},ignore-error=true"           --cache-to "type=registry,ref=${CACHE_REF},mode=min"           -f infra/docker/worker.Dockerfile           -t "${REGISTRY}/${IMAGE_NAME}:${VERSION}"           --push           .
-
-        echo "Production Worker image pushed: ${REGISTRY}/${IMAGE_NAME}:${VERSION}"
-
-        '
-    - name: Job duration summary
-      if: always()
-      shell: sh
-      run: "set +eu\nif [ -n \"$JOB_START_TIME\" ]; then\n  END_TIME=$(date +%s)\n  DURATION=$((END_TIME - JOB_START_TIME))\n  MINS=$((DURATION / 60))\n  SECS=$((DURATION % 60))\n  echo \"JOB_DURATION_SECONDS=$DURATION\" >> $GITHUB_ENV\n  echo \"=== Job Duration: ${MINS}m${SECS}s ===\"\nelse\n  echo \"JOB_DURATION_SECONDS=0\" >> $GITHUB_ENV\n  echo \"=== Job Duration: unknown ===\"\nfi\n"
-    - 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="Build Production Worker Image" python3 scripts/ci_notify.py
-
-        '
-  build-production-web:
-    name: Build Production Web Image
-    runs-on:
-    - saas
-    - build-farm
-    timeout-minutes: 30
-    needs:
-    - validate
-    - frontend-lint
     if: startsWith(github.ref, 'refs/tags/v')
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - service: api
+          service_display: API
+          dockerfile: infra/docker/api.Dockerfile
+          image_name: xiaoxia-saas-api
+          cache_name: api-cache
+          timeout: 30
+        - service: worker
+          service_display: Worker
+          dockerfile: infra/docker/worker.Dockerfile
+          image_name: xiaoxia-saas-worker
+          cache_name: worker-cache
+          timeout: 40
+        - service: web
+          service_display: Web
+          dockerfile: infra/docker/web.Dockerfile
+          image_name: xiaoxia-saas-web
+          cache_name: web-cache
+          timeout: 30
     steps:
     - name: Checkout code
       shell: sh
@@ -967,35 +750,30 @@ jobs:
 
         '
     - name: Build frontend assets (npm build)
+      if: matrix.service == 'web'
       shell: sh
-      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\nfi\n\ndocker run --rm           -v \"$PWD:/workspace\"           -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\"           -w /workspace/apps/web           docker.m.daocloud.io/library/node:20           sh -lc \"npm ci && npm run build\"\n\ntest -f apps/web/dist/index.html\necho \"Frontend build complete\"\n"
+      run: "set -eu\nNPM_CACHE_VOLUME=\"xiaoxia-npm-cache\"\nif ! docker volume inspect \"$NPM_CACHE_VOLUME\" >/dev/null 2>&1; then\n  docker volume create \"$NPM_CACHE_VOLUME\" >/dev/null\nfi\n\ndocker run --rm           -v \"$PWD:/workspace\"           -v \"$NPM_CACHE_VOLUME:/workspace/apps/web/node_modules\"           -w /workspace/apps/web           docker.m.daocloud.io/library/node:20           sh -lc \"npm ci && npx tsc --incremental --tsBuildInfoFile node_modules/.tsbuildinfo && npx vite build\"\n\ntest -f apps/web/dist/index.html\necho \"Frontend build complete\"\n"
     - name: Setup buildx builder (docker-container driver)
       shell: sh
       run: "set -eu\n# 确保使用 docker-container driver 以支持 cache export 功能\nif ! docker buildx inspect ci-builder > /dev/null 2>&1; then\n  docker buildx create --use --name ci-builder --driver docker-container\n  echo \"Created ci-builder (docker-container driver)\"\nelse\n  docker buildx use ci-builder\n  echo \"Using existing ci-builder\"\nfi\ndocker buildx inspect --bootstrap\n"
-    - name: Build and push Web image (buildx cache)
+    - name: Build and push ${{ matrix.service_display }} image (buildx cache)
       shell: sh
-      run: 'set -eu
+      run: "set -eu
+REGISTRY=\"git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas\"
+IMAGE_TAG=\"${REGISTRY}/${{ matrix.image_name }}:${GITHUB_SHA}\"
+CACHE_REF=\"${REGISTRY}/${{ matrix.cache_name }}:${GITHUB_REF_NAME}\"
 
-        REGISTRY="git.xiaoxiajianji.com/xiaoxia/xiaoxia-saas"
+bash scripts/ci/docker_build_push.sh \
+  ${{ matrix.dockerfile }} \
+  \"${IMAGE_TAG}\" \
+  \"${CACHE_REF}\" \
+  APP_VERSION=\"${GITHUB_SHA}\"
 
-        IMAGE_NAME="xiaoxia-saas-web"
-
-        VERSION="${GITHUB_REF_NAME}"
-
-        CACHE_REF="${REGISTRY}/web-cache:main"
-
-        NGINX_CONF="infra/docker/nginx-production.conf"
-
-
-        echo "Building Production Web image: ${VERSION}"
-
-        docker buildx build           --cache-from "type=registry,ref=${CACHE_REF},ignore-error=true"           --cache-to "type=registry,ref=${CACHE_REF},mode=max"           -f infra/docker/web-artifact.Dockerfile           --build-arg "NGINX_CONF=${NGINX_CONF}"           -t "${REGISTRY}/${IMAGE_NAME}:${VERSION}"           --push           .
-
-        echo "Production Web image pushed: ${REGISTRY}/${IMAGE_NAME}:${VERSION}"
-
-        '
+echo
+echo \"${{ matrix.service_display }} image pushed: ${IMAGE_TAG}\"
+"
     - name: Cleanup old Docker images
-      if: always()
+      if: always() && matrix.service == 'web'
       shell: sh
       run: "set -eu\nif [ -f scripts/cleanup_old_images.sh ]; then\n  chmod +x scripts/cleanup_old_images.sh\n  scripts/cleanup_old_images.sh\nelse\n  echo \"Cleanup script not found, doing basic prune...\"\n  docker image prune -f 2>/dev/null || true\nfi\necho \"Disk usage after cleanup:\"\ndf -h / | tail -1\n"
     - name: Job duration summary
@@ -1010,7 +788,7 @@ jobs:
         CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
       run: 'set +e
 
-        NOTIFY_MODE=failure JOB_NAME="Build Production Web Image" python3 scripts/ci_notify.py
+        NOTIFY_MODE=failure JOB_NAME="Build Production ${{ matrix.service_display }} Image" python3 scripts/ci_notify.py
 
         '
   deploy-production:
@@ -1019,9 +797,7 @@ jobs:
     timeout-minutes: 30
     if: startsWith(github.ref, 'refs/tags/v')
     needs:
-    - build-production-api
-    - build-production-worker
-    - build-production-web
+    - build-production
     steps:
     - name: Checkout code
       shell: sh

alembic/versions/041_add_result_count_to_edit_plans.py

@@ -0,0 +1,29 @@
+"""add result_count to edit_plans
+
+Revision ID: 041_result_count
+Revises: 040_playback_speed
+Create Date: 2026-07-15 14:05:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "041_result_count"
+down_revision = "040_playback_speed"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "edit_plans",
+        sa.Column("result_count", sa.Integer(), nullable=False, server_default="0"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("edit_plans", "result_count")

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

@@ -239,7 +239,9 @@ def get_duplication_detail(
     return _to_detail_response(record)
 
 
-@router.delete("/records/{record_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
+@router.delete(
+    "/records/{record_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response
+)
 def delete_duplication_record(
     record_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -287,7 +289,7 @@ def retry_duplication(
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail=str(e),
-        )
+        ) from e
     if updated is None:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,

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

@@ -108,6 +108,10 @@ class EditPlanGenerationStatusResponse(BaseModel):
     plan_id: str
     plan_status: str
     generation_task_id: Optional[str] = None
+    generation_task_status: Optional[str] = None
+    progress: float = 0.0
+    video_url: str = ""
+    error_message: str = ""
     clips: List[ClipStatusItem]
 
 
@@ -275,11 +279,11 @@ def list_plans(
     if status_filter:
         try:
             status_enum = EditPlanStatus(status_filter)
-        except ValueError:
+        except ValueError as _e:
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
                 detail="无效的筛选条件，请选择正确的状态",
-            )
+            ) from _e
 
     # 项目鉴权：如果指定了 project_id，校验用户是否有权访问
     if project_id:
@@ -322,7 +326,7 @@ def get_plan(
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
             detail=str(exc),
-        )
+        ) from exc
     # 项目鉴权
     if plan.project_id:
         check_project_access(plan.project_id, current_user.user.id, project_repository)
@@ -358,7 +362,7 @@ def create_plan(
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail=str(exc),
-        )
+        ) from exc
     logger.info(
         "创建剪辑计划: id=%s name=%s by user=%s",
         created.id,
@@ -401,11 +405,11 @@ def update_plan(
         if body.status is not None:
             try:
                 target_status = EditPlanStatus(body.status)
-            except ValueError:
+            except ValueError as _e:
                 raise HTTPException(
                     status_code=status.HTTP_400_BAD_REQUEST,
                     detail="无效的状态值，请选择正确的状态",
-                )
+                ) from _e
             svc.transition_status(plan_id, target_status)
     except ValueError as exc:
         err_msg = str(exc)
@@ -413,11 +417,11 @@ def update_plan(
             raise HTTPException(
                 status_code=status.HTTP_404_NOT_FOUND,
                 detail=err_msg,
-            )
+            ) from exc
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail=err_msg,
-        )
+        ) from exc
 
     # 返回最新状态
     result = svc.get_plan_or_raise(plan_id)

apps/api/app/api/routes/edit_plans_ai.py

@@ -58,7 +58,7 @@ def ai_recommend_clips(
     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))
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
 
     if plan.project_id:
         check_project_access(plan.project_id, current_user.user.id, project_repository)
@@ -103,7 +103,7 @@ def ai_recommend_clips(
             config=normalized_config,
             total_duration=result["total_duration"],
         )
-    except Exception:
+    except Exception as _e:
         logger.exception("AI 推荐写入失败，plan_id=%s 数据可能不一致", plan_id)
         try:
             db.rollback()
@@ -116,7 +116,7 @@ def ai_recommend_clips(
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail="AI推荐结果保存失败，请稍后重试",
-        )
+        ) from _e
 
     logger.info(
         "AI 推荐片段方案: plan_id=%s clips=%d duration=%.1f by user=%s",
@@ -167,7 +167,7 @@ def generate_cover(
     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))
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
 
     if plan.project_id:
         check_project_access(plan.project_id, current_user.user.id, project_repository)

apps/api/app/api/routes/edit_plans_generation.py

@@ -183,9 +183,7 @@ def _auto_fallback_auto_material_mode(
 def _check_queue_limits(gen_task_repo, user_id: str) -> None:
     """队列限流预检查"""
     try:
-        has_count = hasattr(gen_task_repo, "count_pending_by_user") and hasattr(
-            gen_task_repo, "count_pending_total"
-        )
+        has_count = hasattr(gen_task_repo, "count_pending_by_user") and hasattr(gen_task_repo, "count_pending_total")
         if has_count:
             user_pending = gen_task_repo.count_pending_by_user(user_id)
             global_pending = gen_task_repo.count_pending_total()
@@ -241,7 +239,7 @@ def generate_plan(
     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))
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
     if not can_gen:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=reason)
 
@@ -255,12 +253,15 @@ def generate_plan(
 
         gen_task_use_case = CreateGenerationTaskUseCase(gen_task_repo)
         plan = svc.get_plan_or_raise(plan_id)
+        # 从 plan.config 中读取 asset_ids 并传递给 GenerationTask
+        config_asset_ids = (plan.config or {}).get("asset_ids", [])
         gen_task = gen_task_use_case.execute(
             CreateGenerationTaskCommand(
-                project_id="",
+                project_id=plan.project_id or "",
                 template_id=plan.template_id,
                 created_by_user_id=current_user.user.id,
                 source_edit_plan_id=plan_id,
+                asset_ids=list(config_asset_ids) if config_asset_ids else [],
             )
         )
 
@@ -286,7 +287,7 @@ def generate_plan(
         )
     except HTTPException:
         raise
-    except Exception:
+    except Exception as _e:
         logger.exception("触发剪辑计划生成失败: plan_id=%s", plan_id)
         try:
             svc.transition_status(plan_id, EditPlanStatus.FAILED)
@@ -295,7 +296,7 @@ def generate_plan(
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail="生成失败，请稍后重试",
-        )
+        ) from _e
 
 
 @router.get(
@@ -313,7 +314,7 @@ def get_generation_status(
     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))
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
 
     plan = gen_status["plan"]
     if plan.project_id:
@@ -333,10 +334,25 @@ def get_generation_status(
         for c in clips
     ]
 
+    # 从 plan.config 中取渲染结果 URL
+    video_url = (plan.config or {}).get("rendered_url", "")
+    # 从 gen_status 中取进度、错误信息、任务状态
+    progress = gen_status.get("progress", 0.0)
+    error_message = gen_status.get("error_message", "")
+    gen_task_status = gen_status.get("generation_task_status")
+    # 如果计划已完成但进度还是0，补100
+    plan_status_val = plan.status.value if hasattr(plan.status, "value") else plan.status
+    if plan_status_val == "completed" and progress < 100:
+        progress = 100.0
+
     return EditPlanGenerationStatusResponse(
         plan_id=plan_id,
-        plan_status=plan.status.value if hasattr(plan.status, "value") else plan.status,
+        plan_status=plan_status_val,
         generation_task_id=gen_status["generation_task_id"],
+        generation_task_status=gen_task_status,
+        progress=progress,
+        video_url=video_url,
+        error_message=error_message,
         clips=clip_items,
     )
 

apps/api/app/api/routes/edit_plans_timeline.py

@@ -173,7 +173,7 @@ def generate_from_template(
     try:
         template = template_svc.get_template_or_raise(body.template_id)
     except ValueError as exc:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
 
     clip_configs = template_svc.list_clip_configs(body.template_id, skip=0, limit=200)
 

apps/api/app/api/routes/feature_flags.py

@@ -105,7 +105,7 @@ async def list_feature_flags(
         return sorted(result, key=lambda x: x.name)
     except Exception as exc:
         logger.error("Failed to list feature flags: %s", exc)
-        raise HTTPException(status_code=500, detail=f"Failed to list flags: {exc}")
+        raise HTTPException(status_code=500, detail=f"Failed to list flags: {exc}") from exc
 
 
 @router.get("/{name}", response_model=FeatureFlagResponse)
@@ -120,7 +120,7 @@ async def get_feature_flag(
         return FeatureFlagResponse.from_config(config)
     except Exception as exc:
         logger.error("Failed to get feature flag %s: %s", name, exc)
-        raise HTTPException(status_code=500, detail=f"Failed to get flag: {exc}")
+        raise HTTPException(status_code=500, detail=f"Failed to get flag: {exc}") from exc
 
 
 @router.get("/{name}/check", response_model=FeatureFlagCheckResponse)
@@ -136,7 +136,7 @@ async def check_feature_flag(
         return FeatureFlagCheckResponse(name=name, active=active, identifier=identifier)
     except Exception as exc:
         logger.error("Failed to check feature flag %s: %s", name, exc)
-        raise HTTPException(status_code=500, detail=f"Failed to check flag: {exc}")
+        raise HTTPException(status_code=500, detail=f"Failed to check flag: {exc}") from exc
 
 
 @router.put("/{name}", response_model=FeatureFlagResponse)
@@ -170,7 +170,7 @@ async def update_feature_flag(
         return FeatureFlagResponse.from_config(config)
     except Exception as exc:
         logger.error("Failed to update feature flag %s: %s", name, exc)
-        raise HTTPException(status_code=500, detail=f"Failed to update flag: {exc}")
+        raise HTTPException(status_code=500, detail=f"Failed to update flag: {exc}") from exc
 
 
 @router.delete("/{name}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
@@ -178,7 +178,7 @@ async def delete_feature_flag(
     name: str,
     _: bool = Depends(_verify_internal_api_key),
     store: RedisFeatureFlagStore = Depends(_get_feature_flag_store),
-) :
+):
     """删除 Feature Flag。
 
     只允许删除 ALLOWED_FLAGS 列表中的 flag。
@@ -191,4 +191,4 @@ async def delete_feature_flag(
         pass
     except Exception as exc:
         logger.error("Failed to delete feature flag %s: %s", name, exc)
-        raise HTTPException(status_code=500, detail=f"Failed to delete flag: {exc}")
+        raise HTTPException(status_code=500, detail=f"Failed to delete flag: {exc}") from exc

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

@@ -43,6 +43,7 @@ logger = logging.getLogger(__name__)
 
 router = APIRouter()
 
+
 def _to_generation_task_response(task) -> GenerationTaskResponse:
     return GenerationTaskResponse(
         id=task.id,
@@ -282,28 +283,28 @@ def create_generation_task(
                     created_tasks.append(task)
                 else:
                     failed_tasks.append(task)
-            except UserPendingLimitExceeded:
+            except UserPendingLimitExceeded as _e:
                 # 兜底：如果预检查后又并发提交了，在这里也拦住
                 failed_tasks.append(task)
                 if not created_tasks:
                     raise HTTPException(
                         status_code=429,
                         detail="您的待处理任务过多，请等待完成后再提交",
-                    )
+                    ) from _e
                 break
-            except GlobalQueueFull:
+            except GlobalQueueFull as _e:
                 failed_tasks.append(task)
                 if not created_tasks:
                     raise HTTPException(
                         status_code=503,
                         detail="系统繁忙，请稍后再试",
-                    )
+                    ) from _e
                 break
     except HTTPException:
         raise
     except Exception as e:
         logger.error("[生成任务] 创建失败: %s", e, exc_info=True)
-        raise HTTPException(status_code=500, detail="创建生成任务失败，请稍后重试或查看任务日志")
+        raise HTTPException(status_code=500, detail="创建生成任务失败，请稍后重试或查看任务日志") from e
 
     items = [_to_generation_task_response(t) for t in created_tasks + failed_tasks]
     return BatchGenerationTaskResponse(items=items, total=len(items))

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

@@ -81,11 +81,11 @@ def delete_project(
     use_case = DeleteProjectUseCase(project_repository)
     try:
         deleted = use_case.execute(project_id, authenticated_user.user.id)
-    except PermissionError:
+    except PermissionError as _e:
         raise HTTPException(
             status_code=status.HTTP_403_FORBIDDEN,
             detail="Only the project owner can delete this project",
-        )
+        ) from _e
     if not deleted:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
     return

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

@@ -254,7 +254,7 @@ async def payment_callback(
         return {"success": True, "message": "支付成功", "record_id": record_id}
     except Exception as e:
         session.rollback()
-        raise HTTPException(status_code=500, detail=f"支付处理失败: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"支付处理失败: {str(e)}") from e
     finally:
         session.close()
 

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

@@ -147,9 +147,9 @@ def get_template(
         use_case = GetTemplateUseCase(template_repository)
         template = use_case.execute(template_id, user_id)
         usage = template_repository.get_usage_count(template_id)
-    except Exception:
+    except Exception as _e:
         logger.exception("get_template 查询失败: template_id=%s", template_id)
-        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="模板查询失败")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="模板查询失败") from _e
     if template is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
     return _to_response(template, usage_count=usage)
@@ -186,7 +186,7 @@ def create_template(
     try:
         template = use_case.execute(command)
     except ValidationError as exc:
-        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc))
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)) from exc
     return _to_response(template)
 
 
@@ -226,10 +226,10 @@ def update_template(
     use_case = UpdateTemplateUseCase(template_repository)
     try:
         template = use_case.execute(command)
-    except NotFoundError:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
+    except NotFoundError as _e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found") from _e
     except ValidationError as exc:
-        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc))
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)) from exc
     return _to_response(template)
 
 
@@ -264,10 +264,10 @@ def copy_template(
     use_case = CopyTemplateUseCase(template_repository)
     try:
         template = use_case.execute(command)
-    except NotFoundError:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
+    except NotFoundError as _e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found") from _e
     except ValidationError as exc:
-        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc))
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)) from exc
     return _to_response(template)
 
 
@@ -299,9 +299,9 @@ def toggle_favorite(
     use_case = GetTemplateUseCase(template_repository)
     try:
         template = use_case.execute(template_id, user_id)
-    except Exception:
+    except Exception as _e:
         logger.exception("toggle_favorite 查询失败: template_id=%s", template_id)
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found") from _e
     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)
@@ -326,10 +326,10 @@ def validate_template(
     use_case = ValidateTemplateUseCase(template_repository)
     try:
         result = use_case.execute(command)
-    except NotFoundError:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
+    except NotFoundError as _e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found") from _e
     except ValidationError as exc:
-        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc))
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)) from exc
 
     return ValidateTemplateResponse(
         template=_to_response(result.template),
@@ -375,7 +375,9 @@ def create_category(
     )
 
 
-@router.delete("/categories/{category_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
+@router.delete(
+    "/categories/{category_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response
+)
 def delete_category(
     category_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),

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

@@ -148,7 +148,7 @@ def create_title(
         raise HTTPException(
             status_code=status.HTTP_429_TOO_MANY_REQUESTS,
             detail=f"标题库配额已满（{exc.used}/{exc.limit}），请升级套餐",
-        )
+        ) from exc
     return _to_response(item)
 
 
@@ -172,8 +172,8 @@ def update_title(
     use_case = UpdateTitleLibraryUseCase(title_repository)
     try:
         item = use_case.execute(command)
-    except NotFoundError:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Title not found")
+    except NotFoundError as _e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Title not found") from _e
     return _to_response(item)
 
 

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

@@ -236,8 +236,8 @@ def get_tts_job(
     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")
+    except TTSJobNotFoundError as _e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="TTS job not found") from _e
     return _to_response(job, sign_url)
 
 
@@ -253,8 +253,8 @@ def get_tts_job_status(
     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")
+    except TTSJobNotFoundError as _e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="TTS job not found") from _e
     output_url = job.output_audio_url
     if output_url:
         output_url = sign_url(output_url)
@@ -309,8 +309,8 @@ def save_tts_job_to_library(
     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")
+    except TTSJobNotFoundError as _e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="TTS job not found") from _e
 
     # 校验已完成
     if not job.is_completed:
@@ -363,7 +363,7 @@ def save_tts_job_to_library(
         raise HTTPException(
             status_code=status.HTTP_429_TOO_MANY_REQUESTS,
             detail=f"配音库配额已满（{exc.used}/{exc.limit}），请升级套餐",
-        )
+        ) from exc
 
     return SaveToLibraryResponse(
         id=item.id,

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

@@ -141,8 +141,8 @@ def get_voice_clone(
     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")
+    except VoiceCloneNotFoundError as _e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice clone not found") from _e
     return _to_response(profile)
 
 
@@ -157,8 +157,8 @@ def get_voice_clone_status(
     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")
+    except VoiceCloneNotFoundError as _e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice clone not found") from _e
     return VoiceCloneStatusResponse(
         id=profile.id,
         status=profile.status,
@@ -201,13 +201,13 @@ def retry_voice_clone(
     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:
+    except VoiceCloneNotFoundError as _e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice clone not found") from _e
+    except VoiceCloneNotRetryableError as _e:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail="Voice clone is not retryable (only failed clones can be retried)",
-        )
+        ) from _e
 
     # 如果 profile 处于 processing 且有 task_id，触发 Celery 异步轮询
     task_id = (profile.metadata or {}).get("cosyvoice_task_id", "")

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

@@ -287,7 +287,7 @@ def create_voice(
         raise HTTPException(
             status_code=status.HTTP_429_TOO_MANY_REQUESTS,
             detail=f"配音库配额已满（{exc.used}/{exc.limit}），请升级套餐",
-        )
+        ) from exc
     return _to_response(item, sign_url)
 
 
@@ -317,8 +317,8 @@ def update_voice(
     use_case = UpdateVoiceLibraryUseCase(voice_repository)
     try:
         item = use_case.execute(command)
-    except NotFoundError:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice not found")
+    except NotFoundError as _e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice not found") from _e
     return _to_response(item, sign_url)
 
 

apps/api/app/services/edit_plan_service.py

@@ -431,6 +431,8 @@ class EditPlanService:
                 "clips": List[EditPlanClip],
                 "generation_task_id": Optional[str],
                 "generation_task_status": Optional[str],
+                "progress": float,
+                "error_message": str,
             }
 
         Raises:
@@ -442,17 +444,23 @@ class EditPlanService:
         # 从 plan.config 中获取 generation_task_id
         generation_task_id = plan.config.get("generation_task_id")
         generation_task_status = None
+        progress = 0.0
+        error_message = ""
 
         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
+                progress = getattr(task, "progress", 0.0) or 0.0
+                error_message = getattr(task, "error_message", "") or ""
 
         return {
             "plan": plan,
             "clips": clips,
             "generation_task_id": generation_task_id,
             "generation_task_status": generation_task_status,
+            "progress": progress,
+            "error_message": error_message,
         }
 
     def can_generate(self, plan_id: str) -> tuple[bool, str]:

apps/api/app/services/plan_generator_service.py

@@ -224,7 +224,7 @@ class PlanGeneratorService:
             )
             order += 1
             # 剩余为 overlay
-            for i in range(1, n):
+            for _ in range(1, n):
                 clips.append(
                     EditPlanClip.create(
                         plan_id=plan_id,
@@ -237,7 +237,7 @@ class PlanGeneratorService:
 
         elif editing_mode == EditingMode.VOICE_OVER.value:
             # N 个 main clips（B-roll）
-            for i in range(n):
+            for _ in range(n):
                 clips.append(
                     EditPlanClip.create(
                         plan_id=plan_id,
@@ -271,7 +271,7 @@ class PlanGeneratorService:
             )
             order += 1
             # 剩余为 b_roll
-            for i in range(2, n):
+            for _ in range(2, n):
                 clips.append(
                     EditPlanClip.create(
                         plan_id=plan_id,
@@ -284,7 +284,7 @@ class PlanGeneratorService:
 
         else:
             # ONE_TAKE: N 个 main clips
-            for i in range(n):
+            for _ in range(n):
                 clips.append(
                     EditPlanClip.create(
                         plan_id=plan_id,

apps/web/package-lock.json

@@ -33,6 +33,7 @@
         "eslint-plugin-react-hooks": "^4.6.2",
         "eslint-plugin-react-refresh": "^0.4.7",
         "jsdom": "^24.1.0",
+        "prettier": "^3.0.0",
         "typescript": "^5.5.3",
         "vite": "^5.3.1",
         "vitest": "^1.6.0"
@@ -4828,6 +4829,22 @@
         "node": ">= 0.8.0"
       }
     },
+    "node_modules/prettier": {
+      "version": "3.9.5",
+      "resolved": "https://registry.npmmirror.com/prettier/-/prettier-3.9.5.tgz",
+      "integrity": "sha512-/FVl766LpUfB5vXgCYOYa0MeV/441Ia99AeICQIQFTY/Nw0roZwULcXpku5i1/m5kt/baz+s4Zogspd839HSMg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "prettier": "bin/prettier.cjs"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/prettier/prettier?sponsor=1"
+      }
+    },
     "node_modules/pretty-format": {
       "version": "27.5.1",
       "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-27.5.1.tgz",

apps/web/package.json

@@ -42,6 +42,7 @@
     "eslint-plugin-react-hooks": "^4.6.2",
     "eslint-plugin-react-refresh": "^0.4.7",
     "jsdom": "^24.1.0",
+    "prettier": "^3.0.0",
     "typescript": "^5.5.3",
     "vite": "^5.3.1",
     "vitest": "^1.6.0"

apps/web/src/api/products.ts

@@ -1,5 +1,6 @@
 /**
  * 成品 / 视频相关 API
+ * 包含：列表查询、复核状态、批量下载
  * 后端无 /products 路由，实际从 /generation/tasks 端点获取数据
  */
 import apiClient from "./client";

apps/web/src/api/templates.ts

@@ -16,17 +16,22 @@ import type { EditPlanConfig } from "./editPlans";
 /** 模板条目（后端 TemplateResponse） */
 export interface TemplateItem {
   id: string;
+  user_id?: string;
   name: string;
-  description: string;
+  description?: string;
+  mode?: string;
   category: string;
   tags?: string[];
-  target_duration: number;
-  clip_count: number;
+  /** 预估时长（后端字段名 estimated_duration） */
+  estimated_duration?: number;
+  /** @deprecated 后端已改名为 estimated_duration，保留兼容 */
+  target_duration?: number;
+  clip_count?: number;
   /** 使用次数 */
   usage_count?: number;
   thumbnail_url?: string;
   preview_url?: string;
-  is_active: boolean;
+  is_active?: boolean;
   is_favorite?: boolean;
   /** 素材规则（片段配置） */
   segments?: TemplateSegment[];

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

@@ -3,8 +3,8 @@
  * 四行布局：顶栏(42px) → 模式栏(48px) → 三栏主体 → 底栏(40px)
  */
 import React, { useState, useCallback, useEffect, useRef } from "react";
-import { useSearchParams, useNavigate } from "react-router-dom";
-import { message } from "antd";
+import { useSearchParams } from "react-router-dom";
+import { message, Modal, Progress, Button } from "antd";
 import { useQuery } from "@tanstack/react-query";
 import type {
   EditingTemplate,
@@ -20,11 +20,23 @@ import {
   getTemplateCategories,
   MODE_LABELS,
 } from "@/api/editingPlanner";
-import type { EditPlanGeneration, MediaAsset } from "@/api/editPlans";
+import type {
+  EditPlanGeneration,
+  EditPlanConfig,
+  GeneratedVideo,
+  MediaAsset,
+  TransitionEffect,
+} from "@/api/editPlans";
 import {
   getMediaAssets,
   getEditPlanGenerations,
   generateCover,
+  getEditPlan,
+  createEditPlan,
+  updateEditPlan,
+  generateEditPlan,
+  getGenerationStatus,
+  getGenerationTaskResults,
 } from "@/api/editPlans";
 import { useUndoRedo } from "./hooks/useUndoRedo";
 import type {
@@ -33,6 +45,7 @@ import type {
   TransitionConfig,
   SpeedConfig,
   TtsConfig,
+  TtsMode,
   TrimConfig,
   WatermarkConfig,
   IntroOutroConfig,
@@ -107,8 +120,8 @@ const FILTER_CATEGORIES = ["全部", "种草", "知识", "日常", "推荐"];
 
 const EditingPlanner: React.FC = () => {
   const [searchParams] = useSearchParams();
-  const navigate = useNavigate();
   const urlTemplateId = searchParams.get("templateId") || "";
+  const urlPlanId = searchParams.get("planId") || "";
 
   /* ── 模板列表 ── */
   const [templates, setTemplates] = useState<EditingTemplate[]>([]);
@@ -244,6 +257,21 @@ const EditingPlanner: React.FC = () => {
   const [genHistory, setGenHistory] = useState<EditPlanGeneration[]>([]);
   const [genHistoryLoading, setGenHistoryLoading] = useState(false);
 
+  /* ── 剪辑计划（从列表页编辑进入时） ── */
+  const [loadedPlanId, setLoadedPlanId] = useState<string | null>(
+    urlPlanId || null,
+  );
+
+  /* ── 生成进度 ── */
+  const [generating, setGenerating] = useState(false);
+  const [genProgress, setGenProgress] = useState(0);
+  const [genTotalClips, setGenTotalClips] = useState(0);
+  const [genDoneClips, setGenDoneClips] = useState(0);
+  const [generated, setGenerated] = useState(false);
+  const [generatedVideos, setGeneratedVideos] = useState<GeneratedVideo[]>([]);
+  const [genError, setGenError] = useState<string | null>(null);
+  const genTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
   /* ── 播放 ── */
   const [isPlaying, setIsPlaying] = useState(false);
   const [currentTime, setCurrentTime] = useState(0);
@@ -374,6 +402,85 @@ const EditingPlanner: React.FC = () => {
       .catch(() => message.error("加载模板详情失败"));
   }, [loadedTemplateId, resetClips]);
 
+  /**
+   * 加载已有剪辑计划数据到编辑器
+   * 从列表页"编辑"按钮进入时，URL 带 planId，需要还原计划配置
+   */
+  useEffect(() => {
+    if (!loadedPlanId) return;
+    getEditPlan(loadedPlanId)
+      .then((plan) => {
+        // 设置关联的模板（触发模板加载 effect）
+        setLoadedTemplateId(plan.template_id);
+
+        // 还原基本信息
+        setDraftName(plan.name);
+
+        // 还原 config 中的编辑器状态
+        const cfg = plan.config;
+        if (cfg.title_config) {
+          setTitleSettings((prev) => ({
+            ...prev,
+            aiAutoSelect: cfg.title_config!.ai_auto_select,
+            title: cfg.title_config!.content,
+            position: cfg.title_config!.position,
+            font: cfg.title_config!.font_preset,
+            size: cfg.title_config!.font_size,
+            color: cfg.title_config!.font_color || "#ffffff",
+          }));
+        }
+        if (cfg.subtitle_config) {
+          setSubtitleSettings((prev) => ({
+            ...prev,
+            enabled: cfg.subtitle_config!.enabled,
+            position: (cfg.subtitle_config!.position ||
+              "bottom") as SubtitleStyleConfig["position"],
+            font: cfg.subtitle_config!.font,
+            fontSize: cfg.subtitle_config!.size,
+            fontColor: cfg.subtitle_config!.color || "#ffffff",
+            animation: cfg.subtitle_config!.animation,
+          }));
+        }
+        if (cfg.bgm_config) {
+          setBgmSettings((prev) => ({
+            ...prev,
+            enabled: cfg.bgm_config!.enabled,
+            music_id: cfg.bgm_config!.music_id || "",
+          }));
+        }
+
+        // 还原片段 — 延迟设置，等模板加载 effect 先执行 resetClips
+        if (cfg.segments && cfg.segments.length > 0) {
+          const mapped: ClipData[] = cfg.segments.map((seg, idx) => ({
+            id: `seg-${idx}`,
+            template_segment_id: `seg-${idx}`,
+            type: (seg.material_type === "voiceover"
+              ? "voice"
+              : "pip") as ClipType,
+            duration: (seg.duration_min + seg.duration_max) / 2,
+            startOffset: 0,
+            script_text: "",
+            order: seg.segment_order,
+            transition: seg.transition
+              ? {
+                  type: seg.transition.type as TransitionEffect["type"],
+                  duration: seg.transition.duration,
+                }
+              : undefined,
+            speed: seg.playback_speed
+              ? { rate: seg.playback_speed, pitchCorrection: true }
+              : undefined,
+            tts_config: seg.tts_config
+              ? { ...seg.tts_config, mode: seg.tts_config.mode as TtsMode }
+              : undefined,
+            trim_config: seg.trim_config || undefined,
+          }));
+          setTimeout(() => resetClips(mapped), 100);
+        }
+      })
+      .catch(() => message.error("加载剪辑计划失败"));
+  }, [loadedPlanId, resetClips]);
+
   /* ──────────── 计算 ──────────── */
 
   const currentTemplate = templates.find((t) => t.id === loadedTemplateId);
@@ -671,6 +778,65 @@ const EditingPlanner: React.FC = () => {
     }
   };
 
+  /** 构建剪辑计划 config（编辑器状态 → API config） */
+  const buildPlanConfig = (): EditPlanConfig => ({
+    title_config: {
+      ai_auto_select: titleSettings.aiAutoSelect,
+      content: titleSettings.title,
+      position: titleSettings.position,
+      font_preset: titleSettings.font,
+      font_color: titleSettings.color,
+      font_size: titleSettings.size,
+    },
+    subtitle_config: {
+      enabled: subtitleSettings.enabled,
+      position: subtitleSettings.position,
+      font: subtitleSettings.font,
+      color: subtitleSettings.fontColor,
+      size: subtitleSettings.fontSize,
+      animation: subtitleSettings.animation,
+    },
+    bgm_config: {
+      enabled: bgmSettings.enabled,
+      music_id: bgmSettings.music_id,
+    },
+    estimated_duration: totalDuration,
+    segments: clips.map((c, i) => ({
+      segment_order: i,
+      duration_min: Math.max(1, c.duration - 2),
+      duration_max: c.duration + 2,
+      material_type: c.type === "voice" ? "voiceover" : "video",
+      transition: c.transition
+        ? { type: c.transition.type, duration: c.transition.duration }
+        : undefined,
+      playback_speed: c.speed ? c.speed.rate : undefined,
+      tts_config: c.tts_config
+        ? {
+            mode: c.tts_config.mode,
+            text: c.tts_config.text,
+            voice_id: c.tts_config.voice_id,
+            speed: c.tts_config.speed,
+            pitch: c.tts_config.pitch,
+            volume: c.tts_config.volume,
+            subtitle_sync: c.tts_config.subtitle_sync,
+          }
+        : undefined,
+      trim_config: c.trim_config
+        ? {
+            start_time: c.trim_config.start_time,
+            end_time: c.trim_config.end_time,
+          }
+        : undefined,
+    })),
+    watermark_config: { ...watermarkSettings },
+    intro_outro_config: { ...introOutroSettings },
+    pip_config: { ...pipSettings },
+    filter_config: { ...filterSettings },
+    green_screen_config: { ...chromaKeySettings },
+    sticker_config: { ...stickerSettings },
+    cover_config: { ...coverSettings },
+  });
+
   /* 保存 — 无论是否已加载模板，都打开保存弹窗；未加载时创建新模板 */
   const handleOpenSaveModal = () => {
     setSaveModalOpen(true);
@@ -763,94 +929,139 @@ const EditingPlanner: React.FC = () => {
   };
 
   /**
-   * 跳转到一键生成页面
-   * 通过 URL SearchParams 传递 edit_plan_id 和完整 planConfig（JSON 序列化）
-   * 一键生成页面从 params 解析配置，无需重复请求接口
+   * 剪辑计划生成
+   * 1. 有 planId → 更新计划配置 + 触发生成
+   * 2. 无 planId（从模板库直接进入）→ 先创建计划 + 触发生成
+   * 3. 触发生成后轮询状态，完成后获取视频结果
    */
-  const handleGoToGenerate = () => {
-    const planConfig = {
-      title_config: {
-        ai_auto_select: titleSettings.aiAutoSelect,
-        content: titleSettings.title,
-        position: titleSettings.position,
-        font_preset: titleSettings.font,
-        font_color: titleSettings.color,
-        font_size: titleSettings.size,
-        bold: titleSettings.bold,
-        italic: titleSettings.italic,
-        stroke: titleSettings.stroke,
-        shadow: titleSettings.shadow,
-      },
-      subtitle_config: {
-        enabled: subtitleSettings.enabled,
-        position: subtitleSettings.position,
-        font: subtitleSettings.font,
-        color: subtitleSettings.fontColor,
-        size: subtitleSettings.fontSize,
-        animation: subtitleSettings.animation,
-      },
-      bgm_config: {
-        enabled: bgmSettings.enabled,
-        music_id: bgmSettings.music_id,
-      },
-      mode: currentMode,
-      total_duration: totalDuration,
-      segments: clips.map((c, i) => ({
-        order: i,
-        material_type: c.type === "voice" ? "voiceover" : "video",
-        duration: c.duration,
-        template_segment_id: c.template_segment_id,
-        script_text: c.script_text,
-        voice_asset_id: c.voice_asset_id,
-        voice_file_url: c.voice_file_url,
-        transition: c.transition
-          ? { type: c.transition.type, duration: c.transition.duration }
-          : undefined,
-        playback_speed: c.speed ? c.speed.rate : undefined,
-        tts_config: c.tts_config
-          ? {
-              mode: c.tts_config.mode,
-              text: c.tts_config.text,
-              voice_id: c.tts_config.voice_id,
-              speed: c.tts_config.speed,
-              pitch: c.tts_config.pitch,
-              volume: c.tts_config.volume,
-              subtitle_sync: c.tts_config.subtitle_sync,
-            }
-          : undefined,
-        trim_config: c.trim_config
-          ? {
-              start_time: c.trim_config.start_time,
-              end_time: c.trim_config.end_time,
-            }
-          : undefined,
-      })),
-      watermark_config: { ...watermarkSettings },
-      intro_outro_config: { ...introOutroSettings },
-      pip_config: { ...pipSettings },
-      filter_config: { ...filterSettings },
-      green_screen_config: { ...chromaKeySettings },
-      sticker_config: { ...stickerSettings },
-      cover_config: { ...coverSettings },
-    };
-    const params = new URLSearchParams();
-    if (loadedTemplateId) {
-      params.set("edit_plan_id", loadedTemplateId);
+  const handleGoToGenerate = async () => {
+    if (!loadedTemplateId) {
+      message.warning("请先选择一个模板");
+      return;
+    }
+    if (clips.length === 0) {
+      message.warning("请先添加片段");
+      return;
+    }
+
+    setGenerating(true);
+    setGenerated(false);
+    setGeneratedVideos([]);
+    setGenError(null);
+    setGenProgress(0);
+
+    try {
+      const config = buildPlanConfig();
+      let planId = loadedPlanId;
+
+      if (planId) {
+        // 已有计划 → 更新配置
+        await updateEditPlan(planId, {
+          config,
+          total_duration: totalDuration,
+          status: "editing",
+        });
+      } else {
+        // 无计划 → 创建新计划
+        const plan = await createEditPlan({
+          template_id: loadedTemplateId,
+          name: draftName || "未命名计划",
+          config,
+          total_duration: totalDuration,
+        });
+        planId = plan.id;
+        setLoadedPlanId(planId);
+        // 更新 URL 参数（不刷新页面）
+        const params = new URLSearchParams(window.location.search);
+        params.set("planId", planId);
+        window.history.replaceState(null, "", `?${params.toString()}`);
+      }
+
+      // 触发生成
+      const genRes = await generateEditPlan(planId);
+      setGenTotalClips(genRes.clip_count);
+      message.info("已提交生成，等待处理...");
+
+      // 开始轮询
+      startPolling(planId);
+    } catch (err) {
+      console.error("[生成失败]", err);
+      setGenError("生成提交失败，请重试");
+      setGenerating(false);
     }
-    params.set("plan_config", JSON.stringify(planConfig));
-    navigate(`/app/generate?${params.toString()}`);
   };
 
+  /** 轮询生成状态，每 2 秒一次 */
+  const startPolling = (planId: string) => {
+    const poll = async () => {
+      try {
+        const status = await getGenerationStatus(planId);
+
+        // 计算进度
+        const total = status.clips.length || genTotalClips;
+        const done = status.clips.filter(
+          (c) => c.status === "completed" || c.status === "failed",
+        ).length;
+        setGenDoneClips(done);
+        setGenTotalClips(total);
+        setGenProgress(total > 0 ? Math.round((done / total) * 100) : 5);
+
+        if (status.plan_status === "completed") {
+          setGenProgress(100);
+          setGenerating(false);
+          setGenerated(true);
+
+          // 获取视频结果
+          if (status.generation_task_id) {
+            try {
+              const videos = await getGenerationTaskResults(
+                status.generation_task_id,
+              );
+              setGeneratedVideos(videos);
+            } catch (e) {
+              console.error("[获取视频结果失败]", e);
+            }
+          }
+          message.success("视频生成完成！");
+          return; // 停止轮询
+        }
+
+        if (status.plan_status === "failed") {
+          setGenerating(false);
+          setGenError("生成失败，请重试");
+          return; // 停止轮询
+        }
+
+        // 继续轮询
+        genTimerRef.current = setTimeout(poll, 2000);
+      } catch (err) {
+        console.error("[轮询状态失败]", err);
+        genTimerRef.current = setTimeout(poll, 5000); // 出错后 5 秒重试
+      }
+    };
+
+    // 首次延迟 2 秒后开始
+    genTimerRef.current = setTimeout(poll, 2000);
+  };
+
+  /** 清理轮询定时器 */
+  useEffect(() => {
+    return () => {
+      if (genTimerRef.current) clearTimeout(genTimerRef.current);
+    };
+  }, []);
+
   /* 查看生成历史 */
   const handleViewGenHistory = async () => {
-    if (!loadedTemplateId) {
-      message.warning("请先加载一个模板");
+    const targetId = loadedPlanId || loadedTemplateId;
+    if (!targetId) {
+      message.warning("请先加载一个模板或计划");
       return;
     }
     setGenHistoryOpen(true);
     setGenHistoryLoading(true);
     try {
-      const items = await getEditPlanGenerations(loadedTemplateId);
+      const items = await getEditPlanGenerations(targetId);
       setGenHistory(items);
     } catch {
       message.error("加载生成历史失败");
@@ -899,8 +1110,9 @@ const EditingPlanner: React.FC = () => {
           <button
             className="ep-btn ep-btn-primary"
             onClick={handleGoToGenerate}
+            disabled={generating}
           >
-            🎬 使用此模板生成
+            {loadedPlanId ? "🎬 生成视频" : "🎬 创建计划并生成"}
           </button>
         </div>
       </div>
@@ -1065,6 +1277,111 @@ const EditingPlanner: React.FC = () => {
         onClose={() => setGenHistoryOpen(false)}
       />
 
+      {/* ═══ 生成进度弹窗 ═══ */}
+      <Modal
+        title={generated ? "生成完成" : "正在生成视频"}
+        open={generating || generated}
+        footer={
+          generated
+            ? [
+                <Button
+                  key="close"
+                  onClick={() => {
+                    setGenerated(false);
+                    setGenerating(false);
+                  }}
+                >
+                  关闭
+                </Button>,
+                generatedVideos.length > 0 && (
+                  <Button
+                    key="download"
+                    type="primary"
+                    onClick={() => {
+                      const v = generatedVideos[0];
+                      const url = v.download_url || v.file_url;
+                      if (url) {
+                        const a = document.createElement("a");
+                        a.href = url;
+                        a.download = v.name || "video.mp4";
+                        a.target = "_blank";
+                        document.body.appendChild(a);
+                        a.click();
+                        document.body.removeChild(a);
+                      }
+                    }}
+                  >
+                    下载视频
+                  </Button>
+                ),
+              ]
+            : null
+        }
+        closable={!generating}
+        maskClosable={false}
+        width={520}
+      >
+        {generating && (
+          <div style={{ padding: "16px 0" }}>
+            <Progress percent={genProgress} status="active" />
+            <p style={{ marginTop: 8, color: "var(--text-secondary)" }}>
+              已处理 {genDoneClips}/{genTotalClips} 个片段
+            </p>
+            <p style={{ color: "var(--text-secondary)", fontSize: 12 }}>
+              请耐心等待，生成过程中请勿关闭页面
+            </p>
+          </div>
+        )}
+        {generated && generatedVideos.length > 0 && (
+          <div style={{ padding: "8px 0" }}>
+            <video
+              src={
+                generatedVideos[0].file_url || generatedVideos[0].download_url
+              }
+              controls
+              preload="metadata"
+              style={{ width: "100%", maxHeight: 320, borderRadius: 8 }}
+            />
+            <p
+              style={{
+                marginTop: 8,
+                textAlign: "center",
+                color: "var(--text-secondary)",
+              }}
+            >
+              {generatedVideos[0].name}
+            </p>
+          </div>
+        )}
+        {generated && !generatedVideos.length && (
+          <div style={{ padding: "24px 0", textAlign: "center" }}>
+            <p>生成完成，但暂未获取到视频结果</p>
+            <p style={{ color: "var(--text-secondary)", fontSize: 12 }}>
+              请稍后在剪辑计划列表中查看
+            </p>
+          </div>
+        )}
+        {genError && (
+          <div
+            style={{
+              padding: "16px 0",
+              textAlign: "center",
+              color: "#ff4d4f",
+            }}
+          >
+            <p>{genError}</p>
+            <Button
+              onClick={() => {
+                setGenError(null);
+                setGenerating(false);
+              }}
+            >
+              关闭
+            </Button>
+          </div>
+        )}
+      </Modal>
+
       {/* ═══ BGM 选择器 Drawer ═══ */}
       <BgmSelector
         open={bgmDrawerOpen}

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

@@ -23,7 +23,6 @@ import {
   getTemplate,
   toggleFavoriteTemplate,
   copyTemplate,
-  generateFromTemplate,
   type TemplateItem,
   type TemplateListParams,
   type TemplateSegment,
@@ -91,8 +90,8 @@ const gradientForCategory = (category: string): string => {
 };
 
 /** 格式化时长 */
-const formatDuration = (seconds: number): string => {
-  if (seconds <= 0) return "0秒";
+const formatDuration = (seconds: number | undefined | null): string => {
+  if (!seconds || seconds <= 0) return "0秒";
   const m = Math.floor(seconds / 60);
   const s = seconds % 60;
   if (m === 0) return `${s}秒`;
@@ -237,7 +236,9 @@ const TemplateDetailModal: React.FC<TemplateDetailModalProps> = ({
               {
                 key: "duration",
                 label: "目标时长",
-                children: formatDuration(template.target_duration),
+                children: formatDuration(
+                  template.estimated_duration ?? template.target_duration,
+                ),
               },
               {
                 key: "clips",
@@ -409,7 +410,9 @@ const TemplateCard: React.FC<TemplateCardProps> = ({
         <div className="xx-template-thumb-name">{template.name}</div>
         <div className="xx-template-thumb-meta">
           <span className="xx-template-thumb-duration">
-            {formatDuration(template.target_duration)}
+            {formatDuration(
+              template.estimated_duration ?? template.target_duration,
+            )}
           </span>
         </div>
         <div className="xx-template-preview-hint">点击查看详情</div>
@@ -537,19 +540,6 @@ const TemplateLibrary: React.FC = () => {
     },
   });
 
-  // ── 从模板生成剪辑计划 mutation ──
-  const generateMutation = useMutation({
-    mutationFn: ({ templateId, name }: { templateId: string; name: string }) =>
-      generateFromTemplate(templateId, { name }),
-    onSuccess: (data) => {
-      message.success(`剪辑计划「${data.name}」已创建`);
-      navigate("/app/edit-plans");
-    },
-    onError: () => {
-      message.error("生成剪辑计划失败，请稍后重试");
-    },
-  });
-
   /** 切换收藏 */
   const toggleFavorite = useCallback(
     (id: string, e?: React.MouseEvent) => {
@@ -582,15 +572,12 @@ const TemplateLibrary: React.FC = () => {
     [copyMutation],
   );
 
-  /** 使用模板 → 生成剪辑计划 */
+  /** 使用模板 → 进入剪辑编辑器配置 */
   const handleUse = useCallback(
     (template: TemplateItem) => {
-      generateMutation.mutate({
-        templateId: template.id,
-        name: `基于「${template.name}」的剪辑计划`,
-      });
+      navigate(`/app/editing-planner?templateId=${template.id}`);
     },
-    [generateMutation, navigate],
+    [navigate],
   );
 
   /** 搜索防抖处理 */

apps/web/vite.config.ts

@@ -37,6 +37,7 @@ export default defineConfig({
     },
   },
   build: {
+    cache: true,
     rollupOptions: {
       output: {
         manualChunks: {

apps/worker/video_processing/concat_engine.py

@@ -181,9 +181,9 @@ def _validate_video_path(video_path: str, work_dir: Path) -> None:
             resolved_work_dir = work_dir.resolve()
             try:
                 resolved_path.relative_to(resolved_work_dir)
-            except ValueError:
+            except ValueError as _e:
                 if not is_in_allowed_dirs(resolved_path):
-                    raise PathSecurityError(f"视频路径不在允许目录内: {video_path[:80]}")
+                    raise PathSecurityError(f"视频路径不在允许目录内: {video_path[:80]}") from _e
     # URL类型路径不做本地路径校验（由下载阶段的SSRF防护负责）
     # 但检查扩展名
     else:

apps/worker/video_processing/dedup.py

@@ -356,7 +356,7 @@ def check_duplicate_task(self: Task, generated_video_id: str) -> dict:
     except Exception as e:
         logger.error(f"Duplicate check failed for {generated_video_id}: {str(e)}")
         session.rollback()
-        raise self.retry(exc=e, countdown=60)
+        raise self.retry(exc=e, countdown=60) from e
     finally:
         session.close()
         import shutil

apps/worker/video_processing/multi_track_mixer.py

@@ -191,9 +191,9 @@ def _validate_audio_path(audio_path: str, work_dir: Path) -> None:
             resolved_work_dir = work_dir.resolve()
             try:
                 resolved_path.relative_to(resolved_work_dir)
-            except ValueError:
+            except ValueError as _e:
                 if not is_in_allowed_dirs(resolved_path):
-                    raise PathSecurityError(f"音频路径不在允许目录内: {audio_path[:80]}")
+                    raise PathSecurityError(f"音频路径不在允许目录内: {audio_path[:80]}") from _e
     # URL类型路径不做本地路径校验（由下载阶段的SSRF防护负责）
     # 但检查扩展名
     else:

apps/worker/video_processing/path_security.py

@@ -129,8 +129,8 @@ def safe_resolve_path(
     if not allow_outside:
         try:
             full_path.relative_to(base_dir)
-        except ValueError:
-            raise PathSecurityError(f"路径遍历检测：路径 '{path_str}' 超出基路径 '{base_dir}' 范围")
+        except ValueError as _e:
+            raise PathSecurityError(f"路径遍历检测：路径 '{path_str}' 超出基路径 '{base_dir}' 范围") from _e
 
     # 扩展名校验
     if allowed_extensions is not None:

apps/worker/video_processing/pip_engine.py

@@ -403,7 +403,7 @@ class PiPEngine:
         input_args: list[str] = []
         current_label = base_label
 
-        for i, (input_label, layer, path) in enumerate(pip_sources):
+        for i, (_input_label, layer, path) in enumerate(pip_sources):
             # 添加输入
             input_args.extend(["-i", str(path)])
 

apps/worker/video_processing/sticker_engine.py

@@ -359,7 +359,7 @@ class StickerEngine:
         image_stickers: list[ImageStickerConfig] = []
         image_paths: list[str] = []
 
-        for i, s in enumerate(stickers):
+        for _, s in enumerate(stickers):
             try:
                 sticker_type = s.get("type", "image")
                 z = int(s.get("z_index", 10))

apps/worker/video_processing/subtitle_render_engine.py

@@ -682,6 +682,6 @@ def _validate_subtitle_path(subtitle_path: str, work_dir: Path) -> None:
         resolved_work_dir = work_dir.resolve()
         try:
             resolved_path.relative_to(resolved_work_dir)
-        except ValueError:
+        except ValueError as _e:
             if not is_in_allowed_dirs(resolved_path):
-                raise PathSecurityError(f"字幕路径不在允许目录内: {subtitle_path[:80]}")
+                raise PathSecurityError(f"字幕路径不在允许目录内: {subtitle_path[:80]}") from _e

apps/worker/video_processing/unified_render_service.py

@@ -1363,23 +1363,37 @@ class UnifiedRenderService:
                 # 单 clip 层，直接使用预处理标签
                 layer_output_labels[layer.role] = layer_labels[0]
             else:
-                # 多 clip 层，用 TransitionEngine 构建转场链
                 out_label = f"{layer.role}_merged"
-                # 计算该层使用的转场时长（取首个非零值，否则用默认）
-                layer_dur = 0.0
-                for d in layer_transition_durations:
-                    if d > 0:
-                        layer_dur = d
-                        break
-                xfade_filter, _ = self._transition_engine.build_xfade_chain(
-                    clip_durations=layer_durations,
-                    clip_video_labels=layer_labels,
-                    transitions=layer_transitions,
-                    transition_duration=layer_dur if layer_dur > 0 else None,
-                    output_label=out_label,
+                # 判断是否全部为硬切：是则用 concat filter，否则用 xfade 转场链
+                all_cut = all(
+                    t is None or t == "" or str(t).lower() == "cut"
+                    for t in layer_transitions[1:]  # 第一个 clip 的转场忽略
                 )
-                if xfade_filter:
-                    filter_parts.append(xfade_filter)
+                if all_cut:
+                    # 全硬切：用 concat filter，性能远优于 xfade
+                    concat_inputs = "".join(f"[{label}]" for label in layer_labels)
+                    filter_parts.append(f"{concat_inputs}concat=n={len(layer_labels)}:v=1:a=0[{out_label}]")
+                    logger.info(
+                        "[unified-render] layer=%s clips=%d using concat (all hard-cut)",
+                        layer.role,
+                        len(layer_labels),
+                    )
+                else:
+                    # 有转场效果：用 TransitionEngine 构建 xfade 链
+                    layer_dur = 0.0
+                    for d in layer_transition_durations:
+                        if d > 0:
+                            layer_dur = d
+                            break
+                    xfade_filter, _ = self._transition_engine.build_xfade_chain(
+                        clip_durations=layer_durations,
+                        clip_video_labels=layer_labels,
+                        transitions=layer_transitions,
+                        transition_duration=layer_dur if layer_dur > 0 else None,
+                        output_label=out_label,
+                    )
+                    if xfade_filter:
+                        filter_parts.append(xfade_filter)
                 layer_output_labels[layer.role] = out_label
 
         # Step 3: 合成各层

apps/worker/worker_app/tasks/compose_video.py

@@ -63,6 +63,18 @@ def compose_video(self, job_id: str, **kwargs):
         resolver = get_render_engine_resolver()
         user_id = job.created_by_user_id or None
         engine = resolver.get_engine(user_id=user_id)
+        # 灰度期间打印详细 flag 配置，便于排查
+        config = resolver.get_config_snapshot()
+        logger.info(
+            "compose_video 引擎选择: job_id=%s engine=%s user_id=%s enabled=%s percentage=%s whitelist=%d default=%s",
+            job_id,
+            engine,
+            user_id,
+            config.get("enabled"),
+            config.get("percentage"),
+            len(config.get("whitelist", [])),
+            config.get("default_engine"),
+        )
 
         if engine == "unified":
             return _compose_with_unified_engine(self, job_service, job, plan_id, db)
@@ -78,7 +90,7 @@ def compose_video(self, job_id: str, **kwargs):
             job_service.fail_job(job_id, str(exc)[:500])
         except Exception:
             logger.exception("更新 Job 失败状态时出错")
-        raise self.retry(exc=exc, countdown=60)
+        raise self.retry(exc=exc, countdown=60) from exc
     finally:
         db.close()
 

apps/worker/worker_app/tasks/edit_plan_generation.py

@@ -77,9 +77,21 @@ def _resolve_render_engine(user_id: str) -> str:
         from video_processing.render_engine_resolver import get_render_engine_resolver
 
         resolver = get_render_engine_resolver()
-        return resolver.get_engine(user_id=user_id)
+        engine = resolver.get_engine(user_id=user_id)
+        # 灰度期间打印详细 flag 配置，便于排查
+        config = resolver.get_config_snapshot()
+        logger.info(
+            "edit_plan 引擎选择: user_id=%s engine=%s enabled=%s percentage=%s whitelist=%d default=%s",
+            user_id,
+            engine,
+            config.get("enabled"),
+            config.get("percentage"),
+            len(config.get("whitelist", [])),
+            config.get("default_engine"),
+        )
+        return engine
     except Exception as exc:
-        logger.warning("获取渲染引擎配置失败，fallback 到 legacy: %s", exc)
+        logger.warning("获取渲染引擎配置失败，fallback 到 legacy: %s", exc, exc_info=True)
         return "legacy"
 
 
@@ -95,6 +107,14 @@ def _mark_plan_failed(plan_repo, plan_id, gen_task_repo, generation_task_id, err
             gen_task.status = "failed"
             gen_task.error_message = error_msg
             gen_task.completed_at = datetime.now(timezone.utc)
+            try:
+                gen_task.append_log(
+                    stage="render_failed",
+                    message=error_msg[:500],
+                    level="ERROR",
+                )
+            except Exception:
+                pass
             gen_task_repo.update(gen_task)
 
 
@@ -148,9 +168,13 @@ def _finalize_render_success(
             clip.mark_rendered()
             clip_repo.update(clip)
 
-    # 更新 EditPlan 状态为 completed
+    # 更新 EditPlan 状态为 completed + 回写实际渲染时长 + 结果数
     plan.config["rendered_url"] = output_url or ""
     plan.config["rendered_storage_key"] = storage_key
+    if hasattr(plan, "total_duration") and duration > 0:
+        plan.total_duration = duration
+    if hasattr(plan, "result_count"):
+        plan.result_count = 1
     plan.mark_completed()
     plan_repo.update(plan)
 
@@ -160,7 +184,15 @@ def _finalize_render_success(
         if gen_task:
             gen_task.status = "completed"
             gen_task.progress = 100.0
-            gen_task.result_count = len(rendered_clip_ids)
+            # 剪辑计划是多片段合成 1 个成片，result_count = 1
+            gen_task.result_count = 1
+            gen_task.append_log(
+                stage="render_complete",
+                message=f"渲染完成，输出时长 {duration:.1f}s",
+                level="INFO",
+                engine=engine,
+                clip_count=len(rendered_clip_ids),
+            )
             gen_task.completed_at = datetime.now(timezone.utc)
             gen_task_repo.update(gen_task)
 
@@ -365,6 +397,13 @@ def render_edit_plan(self, plan_id: str) -> dict:
                 if gen_task:
                     gen_task.status = "running"
                     gen_task.started_at = datetime.now(timezone.utc)
+                    gen_task.append_log(
+                        stage="render_start",
+                        message=f"开始渲染，引擎 {engine}，片段数 {len(clips)}",
+                        level="INFO",
+                        engine=engine,
+                        clip_count=len(clips),
+                    )
                     gen_task_repo.update(gen_task)
 
             # 3. 下载素材并构建 asset_path_map
@@ -429,9 +468,28 @@ def render_edit_plan(self, plan_id: str) -> dict:
                             gen_task.status = "failed"
                             gen_task.error_message = "所有片段素材下载失败"
                             gen_task.completed_at = datetime.now(timezone.utc)
+                            gen_task.append_log(
+                                stage="download_failed",
+                                message="所有片段素材下载失败",
+                                level="ERROR",
+                            )
                             gen_task_repo.update(gen_task)
                     return {"status": "error", "message": "所有片段素材下载失败"}
 
+                # 素材下载完成，记录日志
+                if generation_task_id:
+                    gen_task = gen_task_repo.get(generation_task_id)
+                    if gen_task:
+                        gen_task.append_log(
+                            stage="download_done",
+                            message=f"素材下载完成，成功 {len(asset_path_map)} 个，失败 {len(failed_clip_ids)} 个",
+                            level="INFO",
+                            success_count=len(asset_path_map),
+                            failed_count=len(failed_clip_ids),
+                        )
+                        gen_task.progress = 30.0
+                        gen_task_repo.update(gen_task)
+
                 # 4. 根据引擎选择渲染方式
                 if engine == "unified":
                     result = _render_with_unified(
@@ -483,6 +541,15 @@ def render_edit_plan(self, plan_id: str) -> dict:
                         gen_task.status = "failed"
                         gen_task.error_message = f"渲染异常: {type(exc).__name__}: {exc}"
                         gen_task.completed_at = datetime.now(timezone.utc)
+                        try:
+                            gen_task.append_log(
+                                stage="render_failed",
+                                message=f"渲染异常: {type(exc).__name__}: {str(exc)[:500]}",
+                                level="ERROR",
+                                exception_type=type(exc).__name__,
+                            )
+                        except Exception:
+                            pass
                         gen_task_repo.update(gen_task)
                         logger.info(
                             "GenerationTask 已标记为 failed: task_id=%s plan_id=%s",
@@ -493,6 +560,6 @@ def render_edit_plan(self, plan_id: str) -> dict:
                 logger.warning(
                     "更新 GenerationTask 失败状态时异常: task_id=%s error=%s", generation_task_id, e, exc_info=True
                 )
-            raise self.retry(exc=exc, countdown=60)
+            raise self.retry(exc=exc, countdown=60) from exc
 
     return {"status": "error", "message": "数据库连接失败"}

apps/worker/worker_app/tasks/generation.py

@@ -787,10 +787,23 @@ def _resolve_render_engine(user_id: str) -> str:
         from video_processing.render_engine_resolver import get_render_engine_resolver
 
         resolver = get_render_engine_resolver()
-        return resolver.get_engine(user_id=user_id)
+        engine = resolver.get_engine(user_id=user_id)
+        # 灰度期间打印详细 flag 配置，便于排查
+        config = resolver.get_config_snapshot()
+        logger.info(
+            "[渲染引擎] flag 解析: user_id=%s engine=%s enabled=%s percentage=%s whitelist=%d default=%s",
+            user_id,
+            engine,
+            config.get("enabled"),
+            config.get("percentage"),
+            len(config.get("whitelist", [])),
+            config.get("default_engine"),
+        )
+        return engine
     except Exception as exc:
-        logger.warning("获取渲染引擎配置失败，fallback 到 unified: %s", exc)
-        return ENGINE_UNIFIED
+        # 异常时 fallback 到 legacy（保守策略，与 edit_plan_generation 一致）
+        logger.warning("获取渲染引擎配置失败，fallback 到 legacy: %s", exc, exc_info=True)
+        return ENGINE_LEGACY
 
 
 # ── 旧引擎渲染（FFmpeg filter_complex） ────────────────────────────────────────

apps/worker/worker_app/tasks/tts_synthesis.py

@@ -63,7 +63,7 @@ def process_tts_synthesis(self: Task, job_id: str) -> dict:
         if session is not None:
             session.rollback()
         # 超时重试，指数退避
-        raise self.retry(exc=e, countdown=30)
+        raise self.retry(exc=e, countdown=30) from e
 
     except CosyVoiceError as e:
         logger.error(f"TTS synthesis failed for {job_id}: {e}")
@@ -139,7 +139,7 @@ def process_tts_segment_synthesis(self: Task, job_id: str) -> dict:
         logger.warning(f"TTS segment synthesis timeout for {job_id}: {e}")
         if session is not None:
             session.rollback()
-        raise self.retry(exc=e, countdown=60)
+        raise self.retry(exc=e, countdown=60) from e
 
     except CosyVoiceError as e:
         logger.error(f"TTS segment synthesis failed for {job_id}: {e}")

apps/worker/worker_app/tasks/voice_clone.py

@@ -73,7 +73,7 @@ def process_voice_clone(self: Task, profile_id: str) -> dict:
         if session is not None:
             session.rollback()
         # 超时属于临时性故障，延迟 30 秒后重试
-        raise self.retry(exc=e, countdown=30)
+        raise self.retry(exc=e, countdown=30) from e
 
     except CosyVoiceError as e:
         logger.error(f"Voice clone failed for {profile_id}: {e}")

apps/worker/worker_app/tasks/voice_extraction.py

@@ -105,7 +105,7 @@ def extract_voice_task(self: Task, asset_id: str) -> dict:
     except Exception as e:
         logger.error(f"Voice extraction failed for {asset_id}: {str(e)}")
         session.rollback()
-        raise self.retry(exc=e, countdown=60)
+        raise self.retry(exc=e, countdown=60) from e
     finally:
         session.close()
         import shutil
@@ -141,7 +141,7 @@ def extract_background_task(self: Task, asset_id: str) -> dict:
     except Exception as e:
         logger.error(f"Background extraction failed for {asset_id}: {str(e)}")
         session.rollback()
-        raise self.retry(exc=e, countdown=60)
+        raise self.retry(exc=e, countdown=60) from e
     finally:
         session.close()
         import shutil

docs/schema-metadata-snapshot.json

@@ -990,6 +990,14 @@
           "type": "FLOAT",
           "unique": false
         },
+        {
+          "index": false,
+          "name": "result_count",
+          "nullable": false,
+          "primary_key": false,
+          "type": "INTEGER",
+          "unique": false
+        },
         {
           "index": false,
           "name": "config",

infra/docker/worker.Dockerfile

@@ -113,7 +113,7 @@ RUN chmod +x /usr/local/bin/entrypoint-worker.sh
 
 # 设置 Python 路径
 ENV PATH="/opt/venv/bin:$PATH"
-ENV PYTHONPATH=/app
+ENV PYTHONPATH=/app:/app/packages
 ENV PYTHONUNBUFFERED=1
 ENV APP_VERSION=$APP_VERSION
 

packages/adapters/sqlalchemy_impl/edit_plan_repository.py

@@ -100,6 +100,7 @@ class SQLAlchemyEditPlanRepository:
             name=plan.name,
             status=plan.status,
             total_duration=plan.total_duration,
+            result_count=plan.result_count,
             source_edit_plan_id=plan.source_edit_plan_id or None,
             project_id=plan.project_id or "",
             created_by_user_id=plan.created_by_user_id or "",
@@ -119,6 +120,7 @@ class SQLAlchemyEditPlanRepository:
         model.name = plan.name
         model.status = plan.status
         model.total_duration = plan.total_duration
+        model.result_count = plan.result_count
         model.source_edit_plan_id = plan.source_edit_plan_id or None
         model.project_id = plan.project_id or ""
         model.created_by_user_id = plan.created_by_user_id or ""
@@ -152,6 +154,7 @@ class SQLAlchemyEditPlanRepository:
             name=model.name,
             status=EditPlanStatus(model.status) if model.status else EditPlanStatus.DRAFT,
             total_duration=model.total_duration or 0.0,
+            result_count=int(model.result_count or 0),
             source_edit_plan_id=model.source_edit_plan_id or "",
             project_id=model.project_id or "",
             created_by_user_id=model.created_by_user_id or "",

packages/adapters/sqlalchemy_impl/models.py

@@ -148,6 +148,7 @@ class EditPlanModel(Base):
     name = Column(String(200), nullable=False)
     status = Column(String(20), nullable=False, default="draft", index=True)
     total_duration = Column(Float, nullable=False, default=0.0)
+    result_count = Column(Integer, nullable=False, default=0)
     config = Column(JSON, nullable=False, default=dict)
     source_edit_plan_id = Column(String(36), nullable=True, index=True)
     project_id = Column(String(36), nullable=False, default="", index=True)

packages/application/auth/jwt_service.py

@@ -147,10 +147,10 @@ class JWTService:
                 algorithms=[self.config.ALGORITHM],
             )
             return payload
-        except ExpiredSignatureError:
-            raise ExpiredSignatureError("Token has expired")
+        except ExpiredSignatureError as _e:
+            raise ExpiredSignatureError("Token has expired") from _e
         except InvalidTokenError as e:
-            raise InvalidTokenError(f"Invalid token: {str(e)}")
+            raise InvalidTokenError(f"Invalid token: {str(e)}") from e
 
     def verify_access_token(self, token: str) -> Dict[str, Any]:
         """

packages/application/cosyvoice_service.py

@@ -656,8 +656,8 @@ class CosyVoiceService:
                         code = body.get("code", "")
                         message = body.get("message", "")
                         raise CosyVoiceError(f"CosyVoice API 参数错误: HTTP 400, " f"code={code}, message={message}")
-                    except ValueError:
-                        raise CosyVoiceError(f"CosyVoice API 调用失败: HTTP 400, body={body_text}")
+                    except ValueError as _e:
+                        raise CosyVoiceError(f"CosyVoice API 调用失败: HTTP 400, body={body_text}") from _e
                 elif response.status_code >= 500:
                     # 服务端错误，可重试
                     last_error = CosyVoiceError(f"CosyVoice API 服务端错误: HTTP {response.status_code}")

packages/application/tts_job/audio_merger.py

@@ -78,16 +78,16 @@ class AudioMerger:
                 run_ffmpeg(cmd, timeout=120)
             except CalledProcessError as e:
                 logger.error(f"FFmpeg 合并失败: stderr={e.stderr}")
-                raise AudioMergeError(f"FFmpeg 合并失败: {str(e)[:500]}")
+                raise AudioMergeError(f"FFmpeg 合并失败: {str(e)[:500]}") from e
 
             with open(output_path, "rb") as f:
                 return f.read()
 
-        except TimeoutExpired:
-            raise AudioMergeError("FFmpeg 合并超时（120 秒）")
+        except TimeoutExpired as _e:
+            raise AudioMergeError("FFmpeg 合并超时（120 秒）") from _e
         except AudioMergeError:
             raise
         except Exception as e:
-            raise AudioMergeError(f"音频合并失败: {e}")
+            raise AudioMergeError(f"音频合并失败: {e}") from e
         finally:
             shutil.rmtree(temp_dir, ignore_errors=True)

packages/domain/edit_plan.py

@@ -42,6 +42,7 @@ class EditPlan:
     name: str
     status: EditPlanStatus = EditPlanStatus.DRAFT
     total_duration: float = 0.0
+    result_count: int = 0
     source_edit_plan_id: str = ""
     project_id: str = ""
     created_by_user_id: str = ""
@@ -57,6 +58,7 @@ class EditPlan:
         *,
         config: dict[str, Any] | None = None,
         total_duration: float = 0.0,
+        result_count: int = 0,
         source_edit_plan_id: str = "",
         project_id: str = "",
         created_by_user_id: str = "",
@@ -73,6 +75,7 @@ class EditPlan:
             name=clean_name,
             status=EditPlanStatus.DRAFT,
             total_duration=total_duration,
+            result_count=result_count,
             source_edit_plan_id=source_edit_plan_id.strip(),
             project_id=project_id.strip(),
             created_by_user_id=created_by_user_id.strip(),

packages/domain/generation_task.py

@@ -170,8 +170,8 @@ class GenerationTask:
         if isinstance(new_status, str):
             try:
                 new_status = GenerationTaskStatus(new_status)
-            except ValueError:
-                raise ValueError(f"无效状态: {new_status}")
+            except ValueError as _e:
+                raise ValueError(f"无效状态: {new_status}") from _e
 
         allowed = _VALID_TRANSITIONS.get(self.status, set())
         if new_status not in allowed:

packages/domain/job.py

@@ -147,8 +147,8 @@ class Job:
         if isinstance(job_type, str):
             try:
                 job_type = JobType(job_type)
-            except ValueError:
-                raise ValueError(f"不支持的任务类型: {job_type}")
+            except ValueError as _e:
+                raise ValueError(f"不支持的任务类型: {job_type}") from _e
 
         return cls(
             id=uuid4().hex,
@@ -182,8 +182,8 @@ class Job:
         if isinstance(new_status, str):
             try:
                 new_status = JobStatus(new_status)
-            except ValueError:
-                raise ValueError(f"无效状态: {new_status}")
+            except ValueError as _e:
+                raise ValueError(f"无效状态: {new_status}") from _e
 
         allowed = _VALID_TRANSITIONS.get(self.status, set())
         if new_status not in allowed:

packages/domain/tts_job.py

@@ -193,8 +193,8 @@ class TTSJob:
         if isinstance(new_status, str):
             try:
                 new_status = TTSJobStatus(new_status)
-            except ValueError:
-                raise ValueError(f"无效状态: {new_status}")
+            except ValueError as _e:
+                raise ValueError(f"无效状态: {new_status}") from _e
 
         allowed = _VALID_TRANSITIONS.get(self.status, set())
         if new_status not in allowed:

packages/domain/voice_clone_profile.py

@@ -177,8 +177,8 @@ class VoiceCloneProfile:
         if isinstance(new_status, str):
             try:
                 new_status = VoiceCloneStatus(new_status)
-            except ValueError:
-                raise ValueError(f"无效状态: {new_status}")
+            except ValueError as _e:
+                raise ValueError(f"无效状态: {new_status}") from _e
 
         allowed = _VALID_TRANSITIONS.get(self.status, set())
         if new_status not in allowed:

packages/shared/storage.py

@@ -114,7 +114,7 @@ class SharedStorageService:
                 self.bucket.put_object(storage_key, file_or_path, headers={"Content-Type": content_type})
             return f"{self.public_url}/{storage_key}"
         except Exception as e:
-            raise Exception(f"Failed to upload file to OSS: {e}")
+            raise Exception(f"Failed to upload file to OSS: {e}") from e
 
     def get_url(self, storage_key: str) -> str:
         """Get public URL for a file."""
@@ -129,7 +129,7 @@ class SharedStorageService:
             os.makedirs(os.path.dirname(local_path), exist_ok=True)
             self.bucket.get_object_to_file(storage_key, local_path)
         except Exception as e:
-            raise Exception(f"Failed to download file from OSS: {e}")
+            raise Exception(f"Failed to download file from OSS: {e}") from e
 
     def get_download_url(self, storage_key_or_url: str, expires_seconds: int = 3600) -> str:
         """Get signed download URL."""

pyproject.toml

@@ -66,18 +66,19 @@ exclude = [
 ]
 
 [tool.ruff.lint]
-# 当前阶段：摸底模式，规则集与原flake8对齐
+# 正式替换 flake8：规则集与原 flake8 完全对齐
 # 后续迭代计划：
-#   Phase 1: 修完 bugbear 后正式替换 flake8
-#   Phase 2: 启用 UP(pyupgrade) + SIM(simplify)
-#   Phase 3: 启用 RET(return) + ARG(unused-args)
+#   Phase 2: 加入 B (flake8-bugbear)，修完后升级为阻断级
+#   Phase 3: 启用 UP(pyupgrade) + SIM(simplify)
+#   Phase 4: 启用 RET(return) + ARG(unused-args)
 select = [
-  "E",   # pycodestyle errors（同flake8）
-  "F",   # pyflakes（同flake8）
-  "W",   # pycodestyle warnings（同flake8）
-  "B",   # flake8-bugbear（新增，摸底用）
+  "E",   # pycodestyle errors（同 flake8）
+  "F",   # pyflakes（同 flake8）
+  "W",   # pycodestyle warnings（同 flake8）
+  "B",   # flake8-bugbear（P0-5 Step 2 已完成修复）
 ]
-# 与原 setup.cfg flake8 配置对齐，确保不新增阻断
+# 与原 setup.cfg + .flake8 的 flake8 配置完全对齐
+# 注意：W503 在 ruff≥0.14 中已被移除（行为变默认），故不列入
 ignore = [
   "E203",
   "E501",  # line-too-long（black管）
@@ -86,16 +87,19 @@ ignore = [
   "E722",  # bare-except
   "W291",
   "W293",
+  "B008",  # function-call-in-default-argument（FastAPI 依赖注入模式，大量使用）
   "F401",  # unused-import
   "F403",
   "F405",
   "F841",  # unused-variable
-  "B008",  # do-not-perform-callback-from-arg（fastapi依赖注入）
 ]
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401", "F403", "F405"]
-"tests/*" = ["E402", "F401", "F841"]
-"packages/ports/*" = ["E301"]
+"tests/*" = ["E402", "F401", "F821", "F841"]
+"packages/ports/*" = ["E301"]  # E704 在 ruff≥0.14 已移除
+"apps/api/app/api/routes/auth.py" = ["ALL"]
+"apps/api/app/api/routes/workspaces.py" = ["ALL"]
+"apps/api/app/middleware/auth.py" = ["ALL"]
 "apps/*/migrations/*" = ["ALL"]
 "alembic/*" = ["ALL"]

requirements-dev.txt

@@ -3,7 +3,7 @@
 # 代码质量
 black==26.5.1
 isort==8.0.1
-flake8==7.3.0
+ruff==0.14.0
 bandit==1.9.4
 
 # 测试

scripts/ci/docker_build_push.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+# 通用Docker镜像构建+推送脚本（local cache为主 + registry cache兜底）
+# M-2优化：解决registry缓存导入慢(247s)和推送不稳定问题
+# 用法: docker_build_push.sh <Dockerfile> <image_tag> <cache_ref> [build_arg...]
+set -eu
+
+DOCKERFILE="$1"
+IMAGE_TAG="$2"
+CACHE_REF="$3"
+shift 3
+BUILD_ARGS=""
+for arg in "$@"; do
+  BUILD_ARGS="$BUILD_ARGS --build-arg $arg"
+done
+
+if ! docker buildx inspect ci-builder > /dev/null 2>&1; then
+  docker buildx create --use --name ci-builder --driver docker-container
+  echo "Created ci-builder"
+else
+  docker buildx use ci-builder
+  echo "Using existing ci-builder"
+fi
+docker buildx inspect --bootstrap
+
+# 从cache_ref中提取缓存名称（如 api-cache:develop -> api-cache-develop）
+CACHE_NAME=$(echo "$CACHE_REF" | tr '/' '_' | tr ':' '-')
+LOCAL_CACHE_DIR="/tmp/buildx-cache/${CACHE_NAME}"
+
+mkdir -p "$LOCAL_CACHE_DIR"
+
+# 缓存源：local优先，registry兜底
+CACHE_FROM_LOCAL="type=local,src=${LOCAL_CACHE_DIR}"
+CACHE_FROM_REGISTRY="type=registry,ref=${CACHE_REF},ignore-error=true"
+
+# 本地缓存目标（必选，mode=max最大化命中率）
+CACHE_TO_LOCAL="type=local,dest=${LOCAL_CACHE_DIR},mode=max"
+
+echo "=== Step 1: Build & push image (local cache read-write + registry read) ==="
+echo "Local cache: ${LOCAL_CACHE_DIR}"
+echo "Registry cache: ${CACHE_REF}"
+echo ""
+
+docker buildx build \
+  $BUILD_ARGS \
+  --cache-from "${CACHE_FROM_LOCAL}" \
+  --cache-from "${CACHE_FROM_REGISTRY}" \
+  --cache-to "${CACHE_TO_LOCAL}" \
+  -f "${DOCKERFILE}" \
+  -t "${IMAGE_TAG}" \
+  --push \
+  .
+
+echo ""
+echo "Image pushed: ${IMAGE_TAG}"
+echo "Local cache updated"
+
+echo ""
+echo "=== Step 2: Sync registry cache (best effort, retries 3x) ==="
+CACHE_TO_REGISTRY="type=registry,ref=${CACHE_REF},mode=max,compression=zstd"
+
+MAX_RETRIES=3
+SUCCESS=0
+for attempt in $(seq 1 $MAX_RETRIES); do
+  echo "Registry cache sync attempt $attempt/$MAX_RETRIES"
+  if docker buildx build \
+    $BUILD_ARGS \
+    --cache-from "${CACHE_FROM_LOCAL}" \
+    --cache-to "${CACHE_TO_REGISTRY}" \
+    -f "${DOCKERFILE}" \
+    -t "${IMAGE_TAG}" \
+    --push \
+    .; then
+    echo "Registry cache synced (attempt $attempt)"
+    SUCCESS=1
+    break
+  else
+    echo "Registry cache sync failed (attempt $attempt)"
+    if [ $attempt -lt $MAX_RETRIES ]; then
+      WAIT=$((attempt * 5))
+      echo "Retrying in ${WAIT}s..."
+      sleep $WAIT
+    fi
+  fi
+done
+
+if [ $SUCCESS -eq 0 ]; then
+  echo "WARNING: Registry cache sync failed after $MAX_RETRIES attempts (non-fatal, local cache still works)"
+fi
+
+echo ""
+echo "Build completed: ${IMAGE_TAG}"

tests/integration/conftest.py

@@ -137,7 +137,7 @@ class PerfAssert:
             result = PerfResult(name=name or threshold_level, threshold_ms=threshold_ms)
 
             last_response = None
-            for i in range(num_samples):
+            for _ in range(num_samples):
                 start = time.perf_counter()
                 last_response = func()
                 elapsed = (time.perf_counter() - start) * 1000
@@ -261,7 +261,7 @@ def run_perf_test(
     result = PerfResult(name=name, threshold_ms=threshold_ms)
 
     last_response = None
-    for i in range(samples):
+    for _ in range(samples):
         start = time.perf_counter()
         last_response = func()
         elapsed = (time.perf_counter() - start) * 1000

tests/integration/test_error_scenarios.py

@@ -530,7 +530,7 @@ class TestLargeDataRequests:
     def test_rapid_sequential_requests(self, auth_headers):
         """快速连续请求不应触发限流导致 500。"""
         statuses = []
-        for i in range(20):
+        for _ in range(20):
             resp = client.get("/api/v1/projects", headers=auth_headers)
             statuses.append(resp.status_code)
 

tests/unit/test_edit_plan_generation_api.py

@@ -665,7 +665,16 @@ class TestResponseSchema:
         resp = client.get(f"/api/v1/edit-plans/{plan.id}/generation-status")
         assert resp.status_code == 200
         data = resp.json()
-        expected_keys = {"plan_id", "plan_status", "generation_task_id", "clips"}
+        expected_keys = {
+            "plan_id",
+            "plan_status",
+            "generation_task_id",
+            "generation_task_status",
+            "progress",
+            "video_url",
+            "error_message",
+            "clips",
+        }
         assert set(data.keys()) == expected_keys
 
 

tests/unit/test_phase8_edit_models.py

@@ -44,7 +44,7 @@ class TestEditTemplate:
     def test_create_empty_name_raises(self):
         try:
             EditTemplate.create("   ")
-            assert False, "应该抛出 ValueError"
+            raise AssertionError("应该抛出 ValueError")
         except ValueError as e:
             assert "模板名称不能为空" in str(e)
 
@@ -74,14 +74,14 @@ class TestEditPlan:
     def test_create_empty_name_raises(self):
         try:
             EditPlan.create("tpl-1", "  ")
-            assert False, "应该抛出 ValueError"
+            raise AssertionError("应该抛出 ValueError")
         except ValueError as e:
             assert "计划名称不能为空" in str(e)
 
     def test_create_empty_template_id_raises(self):
         try:
             EditPlan.create("  ", "test")
-            assert False, "应该抛出 ValueError"
+            raise AssertionError("应该抛出 ValueError")
         except ValueError as e:
             assert "template_id 不能为空" in str(e)
 
@@ -112,7 +112,7 @@ class TestEditPlan:
         p = EditPlan.create("tpl-1", "test")
         try:
             p.start_rendering()  # draft → rendering 不合法
-            assert False, "应该抛出 ValueError"
+            raise AssertionError("应该抛出 ValueError")
         except ValueError as e:
             logger.warning(f"Operation failed in tests/unit/test_phase8_edit_models.py: {e}", exc_info=True)
 
@@ -120,7 +120,7 @@ class TestEditPlan:
         p = EditPlan.create("tpl-1", "test")
         try:
             p.mark_completed()  # draft → completed 不合法
-            assert False, "应该抛出 ValueError"
+            raise AssertionError("应该抛出 ValueError")
         except ValueError as e:
             logger.warning(f"Operation failed in tests/unit/test_phase8_edit_models.py: {e}", exc_info=True)
 
@@ -128,7 +128,7 @@ class TestEditPlan:
         p = EditPlan.create("tpl-1", "test")
         try:
             p.reset_to_draft()  # draft → draft 不合法
-            assert False, "应该抛出 ValueError"
+            raise AssertionError("应该抛出 ValueError")
         except ValueError as e:
             logger.warning(f"Operation failed in tests/unit/test_phase8_edit_models.py: {e}", exc_info=True)
 

tests/unit/test_pr312_security_debt.py

@@ -253,7 +253,7 @@ class TestConcatSecurity:
 
         # 创建超过上限的段数
         segments = []
-        for i in range(MAX_CONCAT_SEGMENTS + 5):
+        for _ in range(MAX_CONCAT_SEGMENTS + 5):
             segments.append(ConcatSegment(video_path=str(sample_video)))
 
         config = ConcatConfig(segments=segments)

tests/unit/test_tech_debt_security_round2.py

@@ -367,7 +367,7 @@ class TestVerifyUrlRedirectValidation:
                     except urllib.error.HTTPError as e:
                         if 300 <= e.code < 400 and e.headers.get("Location"):
                             if redirect_count >= max_redirects:
-                                raise Exception(f"重定向次数超过上限 ({max_redirects})")
+                                raise Exception(f"重定向次数超过上限 ({max_redirects})") from e
                             location = e.headers["Location"]
                             current = urljoin(safe_url, location)
                             redirect_count += 1

tests/unit/test_tts_segment_synthesis.py

@@ -115,7 +115,7 @@ class TestAudioMerger:
 
         # 创建临时文件
         paths = []
-        for i in range(3):
+        for _ in range(3):
             with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as f:
                 f.write(b"audio")
                 paths.append(f.name)
@@ -151,7 +151,7 @@ class TestAudioMerger:
         mock_run_ffmpeg.side_effect = CalledProcessError(returncode=1, cmd=["ffmpeg"], stderr="error details")
 
         paths = []
-        for i in range(2):
+        for _ in range(2):
             with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as f:
                 f.write(b"audio")
                 paths.append(f.name)

tests/unit/test_unified_render_service.py

@@ -45,6 +45,7 @@ class FakeClip:
     start_time: float = 0.0
     duration: float = 0.0
     transition_effect: str = "cut"
+    transition_duration: float = 0.0
     status: str = "ready"
     config: dict[str, Any] = field(default_factory=dict)
 
@@ -65,6 +66,7 @@ def _make_clip(
     asset_id: str = "",
     duration: float = 0.0,
     transition_effect: str = "cut",
+    transition_duration: float = 0.0,
     config: dict[str, Any] | None = None,
 ) -> FakeClip:
     return FakeClip(
@@ -74,6 +76,7 @@ def _make_clip(
         asset_id=asset_id or f"asset_{clip_id}.mp4",
         duration=duration,
         transition_effect=transition_effect,
+        transition_duration=transition_duration,
         config=config or {},
     )
 
@@ -332,7 +335,7 @@ class TestBuildFilterComplex:
         assert "[final_video]" in fc
 
     def test_single_layer_multi_clips(self):
-        """多个 main clips → xfade 串联。"""
+        """多个 main clips（默认硬切）→ concat 串联。"""
         clips = [
             _make_clip("c1", "main", order=0, duration=3.0),
             _make_clip("c2", "main", order=1, duration=3.0),
@@ -343,6 +346,35 @@ class TestBuildFilterComplex:
         }
         svc = _make_service(clips, asset_paths)
 
+        with _patch_path_exists(), patch("video_processing.unified_render_service.probe_duration", return_value=5.0):
+            resolved = svc._resolve_clips()
+            layers = svc._group_clips_into_layers(resolved)
+            fc, input_args = svc._build_filter_complex(layers)
+
+        assert input_args.count("-i") == 2
+        # 全硬切场景走 concat filter（性能远优于 xfade）
+        assert "concat=n=2:v=1:a=0" in fc
+        assert "[final_video]" in fc
+
+    def test_single_layer_multi_clips_with_transition(self):
+        """多个 main clips 带转场效果 → xfade 串联。"""
+        clips = [
+            _make_clip("c1", "main", order=0, duration=3.0),
+            _make_clip(
+                "c2",
+                "main",
+                order=1,
+                duration=3.0,
+                transition_effect="fade",
+                transition_duration=0.5,
+            ),
+        ]
+        asset_paths = {
+            "asset_c1.mp4": Path("/tmp/asset_c1.mp4"),
+            "asset_c2.mp4": Path("/tmp/asset_c2.mp4"),
+        }
+        svc = _make_service(clips, asset_paths)
+
         with _patch_path_exists(), patch("video_processing.unified_render_service.probe_duration", return_value=5.0):
             resolved = svc._resolve_clips()
             layers = svc._group_clips_into_layers(resolved)
@@ -380,7 +412,7 @@ class TestBuildFilterComplex:
         """
         clips = [
             _make_clip("c1", "main", order=0, duration=3.0),
-            _make_clip("c2", "main", order=1, duration=5.0),
+            _make_clip("c2", "main", order=1, duration=5.0, transition_effect="fade", transition_duration=0.5),
         ]
         asset_paths = {
             "asset_c1.mp4": Path("/tmp/asset_c1.mp4"),