fix(worker): 修复瘦身后PYTHONPATH缺少packages目录导致shared模块无法导入

- 修复 ruff 配置：移除已废弃规则 W503/E704（ruff 0.14+ 不兼容）
- 修复 F541 (13处)：f-string 无占位符改为普通字符串
- 修复 B017 (1处)：pytest.raises(Exception) 改为 ValidationError
- 修复 vulture 死代码：trim_engine 中 if False 的三元表达式
- 修复 mypy var-annotated：SUNSET_VERSIONS 加类型标注

.ci-retrigger

@@ -0,0 +1 @@
+re-trigger

.ci-trigger

@@ -1 +1 @@
-# CI trigger Fri Jun 26 09:53:28 PM CST 2026
+trigger: 1784009947

.env.example

@@ -3,6 +3,7 @@
 # ==================== 应用配置 ====================
 APP_NAME=小虾 SaaS
 APP_BASE_URL=http://localhost:3000
+APP_ENV=development
 
 # ==================== 数据库配置 ====================
 DATABASE_URL=postgresql://xiaoxia_user:your_password@localhost:5432/xiaoxia_saas
@@ -35,10 +36,25 @@ ENVIRONMENT=development
 DEBUG=true
 
 # ==================== CORS 配置 ====================
-CORS_ORIGINS=["http://localhost:3000","http://localhost:5173"]
+# 逗号分隔的域名列表（Settings 读取 CORS_ORIGINS_RAW）
+CORS_ORIGINS_RAW=http://localhost:3000,http://localhost:5173
 
 # ==================== 阿里云 OSS 配置 ====================
 OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
 OSS_ACCESS_KEY_ID=your-access-key-id
 OSS_ACCESS_KEY_SECRET=your-access-key-secret
 OSS_BUCKET_NAME=xiaoxia-autocut
+
+# ==================== CosyVoice 语音合成配置 ====================
+# 注意：base_url 只需写到 /api/v1，具体路径由代码拼接
+# 模型: cosyvoice-v3-flash (推荐，支持系统音色，性价比高)
+#       cosyvoice-v3-plus (高质量，系统音色少)
+#       cosyvoice-v3.5-flash / cosyvoice-v3.5-plus (仅支持克隆/设计音色，无系统音色)
+# 音色: v3系列系统音色带 _v3 后缀，如 longxiaochun_v3, longxiaoxia_v3, longanyang (无后缀)
+# 注意：COSYVOICE_* 变量由 packages/shared/config.py 的 SharedSettings 读取
+COSYVOICE_API_KEY=your-cosyvoice-api-key
+COSYVOICE_BASE_URL=https://dashscope.aliyuncs.com/api/v1
+COSYVOICE_MODEL=cosyvoice-v3-flash
+COSYVOICE_VOICE=longxiaochun_v3
+COSYVOICE_SAMPLE_RATE=22050
+COSYVOICE_FORMAT=mp3

.env.production.example

@@ -1,30 +1,66 @@
 # 生产环境配置模板（实际使用时复制为 .env.production）
+
+# ==================== 基础配置 ====================
+APP_ENV=production
 ENVIRONMENT=production
 DEBUG=false
 USE_IN_MEMORY_DB=false
-LOG_LEVEL=WARNING
 
-# 数据库（必须修改）
+# ==================== 数据库（必须修改）====================
 DATABASE_URL=postgresql://prod_user:CHANGE_THIS_PASSWORD@db-prod:5432/xiaoxia_prod
 
-# Redis（必须修改）
+# ==================== Redis（必须修改）====================
 REDIS_URL=redis://:CHANGE_THIS_PASSWORD@redis-prod:6379/0
+ENABLE_REDIS_SESSIONS=false
 
-# JWT（必须修改，至少 32 字符）
+# ==================== JWT（必须修改，至少 32 字符）====================
 JWT_SECRET_KEY=CHANGE_THIS_TO_A_RANDOM_SECRET_KEY_AT_LEAST_32_CHARS
 
-# SMTP（必须配置）
+# ==================== 邮件（必须配置）====================
+ENABLE_EMAIL_DELIVERY=false
 SMTP_HOST=smtp.gmail.com
 SMTP_PORT=587
-SMTP_USER=your-email@gmail.com
-SMTP_PASSWORD=your-app-specific-password
+SMTP_USER=CHANGE_ME_SMTP_USER
+SMTP_PASSWORD=CHANGE_ME_SMTP_PASSWORD
 SMTP_FROM_EMAIL=noreply@yourdomain.com
+SMTP_FROM_NAME=小虾 SaaS
+SMTP_USE_TLS=true
 
-# 应用配置
-BASE_URL=https://yourdomain.com
+# ==================== 应用配置 ====================
+APP_BASE_URL=https://yourdomain.com
 
-# CORS（修改为实际域名）
-CORS_ORIGINS=["https://yourdomain.com","https://app.yourdomain.com"]
+# ==================== CORS（修改为实际域名，逗号分隔）====================
+CORS_ORIGINS_RAW=https://yourdomain.com,https://app.yourdomain.com
 
-# 监控（可选）
-SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
+# ==================== 阿里云 OSS（必须配置）====================
+OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
+OSS_ACCESS_KEY_ID=CHANGE_ME_ACCESS_KEY_ID
+OSS_ACCESS_KEY_SECRET=CHANGE_ME_ACCESS_KEY_SECRET
+OSS_BUCKET_NAME=xiaoxia-autocut
+OSS_DIRECT_UPLOAD_MAX_MB=2000
+OSS_DIRECT_UPLOAD_EXPIRE_SECONDS=900
+
+# ==================== CosyVoice 语音合成（必须配置）====================
+# 注意：base_url 只需写到 /api/v1，具体路径由代码拼接
+# 模型: cosyvoice-v3-flash (推荐，支持系统音色，性价比高)
+#       cosyvoice-v3-plus (高质量，系统音色少)
+#       cosyvoice-v3.5-flash / cosyvoice-v3.5-plus (仅支持克隆/设计音色，无系统音色)
+# 音色: v3系列系统音色带 _v3 后缀，如 longxiaochun_v3, longxiaoxia_v3, longanyang (无后缀)
+COSYVOICE_API_KEY=CHANGE_ME_COSYVOICE_API_KEY
+COSYVOICE_BASE_URL=https://dashscope.aliyuncs.com/api/v1
+COSYVOICE_MODEL=cosyvoice-v3-flash
+COSYVOICE_VOICE=longxiaochun_v3
+COSYVOICE_SAMPLE_RATE=22050
+COSYVOICE_FORMAT=mp3
+
+# ==================== 生成文件 ====================
+GENERATED_FILES_DIR=/app/generated
+GENERATED_FILES_URL_PREFIX=/generated-files
+PUBLIC_API_BASE_URL=https://api.xiaoxiajianji.com
+
+# ==================== Celery ====================
+CELERY_BROKER_URL=redis://:CHANGE_THIS_PASSWORD@redis-prod:6379/0
+CELERY_RESULT_BACKEND=redis://:CHANGE_THIS_PASSWORD@redis-prod:6379/1
+
+# ==================== 监控（可选）====================
+# SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id

.flake8

@@ -0,0 +1,14 @@
+[flake8]
+max-line-length = 120
+exclude =
+    .git,
+    .cache,
+    __pycache__,
+    .venv,
+    venv,
+    node_modules,
+    alembic
+
+per-file-ignores =
+    tests/integration/*:F821
+    tests/unit/*:F821

.gitea/workflows/auto-merge.yml

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

.gitea/workflows/daily-check.yml

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

.gitea/workflows/deploy.yml

@@ -1,219 +0,0 @@
-name: Deploy
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  deploy-staging:
-    name: Deploy Staging
-    runs-on: runtime-builder
-    if: github.ref_name == 'main' || github.ref_name == 'develop' || startsWith(github.ref_name, 'feature/')
-
-    steps:
-    - name: Checkout code
-      shell: sh
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: |
-        set -eu
-        archive_url="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/archive/${GITHUB_SHA}.tar.gz"
-        wget --header="Authorization: token ${GITHUB_TOKEN}" -O /tmp/repo.tar.gz "$archive_url"
-        tar -xzf /tmp/repo.tar.gz --strip-components=1 -C .
-        rm -f /tmp/repo.tar.gz
-
-    - name: Build staging web artifact
-      shell: sh
-      run: |
-        set -eu
-        docker run --rm \
-          --pull=never \
-          -v "$PWD:/workspace" \
-          -w /workspace/apps/web \
-          node:20 \
-          sh -lc 'npm ci && npm run build'
-        docker build --pull=false \
-          -f infra/docker/web-artifact.Dockerfile \
-          -t "xiaoxia-saas-web:staging-${GITHUB_SHA}" \
-          .
-        test -f apps/web/dist/index.html
-
-    - name: Package staging release artifact
-      shell: sh
-      run: |
-        set -eu
-        rm -rf dist/staging-artifacts
-        mkdir -p dist/staging-artifacts
-        tar --exclude=.git --exclude=apps/web/node_modules --exclude=./dist \
-          -czf dist/staging-artifacts/xiaoxia-staging-${GITHUB_SHA}.tar.gz .
-        docker save -o "dist/staging-artifacts/xiaoxia-web-staging-${GITHUB_SHA}.tar" "xiaoxia-saas-web:staging-${GITHUB_SHA}"
-
-    - name: Upload staging artifact to business host
-      shell: sh
-      env:
-        STAGING_SSH_HOST: ${{ secrets.STAGING_SSH_HOST }}
-        STAGING_SSH_USER: ${{ secrets.STAGING_SSH_USER }}
-        STAGING_SSH_KEY: ${{ secrets.STAGING_SSH_KEY }}
-      run: |
-        set -eu
-        staging_host="${STAGING_SSH_HOST:-47.98.113.167}"
-        [ -z "$staging_host" ] && staging_host="47.98.113.167"
-        staging_user="${STAGING_SSH_USER:-root}"
-        mkdir -p ~/.ssh
-        key_path="/root/.ssh/xiaoxia_runtime_builder"
-        echo "Using SSH key: $key_path"
-        ls -la "$key_path"
-        test -f "$key_path" || { echo "ERROR: SSH key not found"; exit 1; }
-        ssh-keyscan -H "$staging_host" >> ~/.ssh/known_hosts
-        ssh -i "$key_path" "$staging_user@$staging_host" "mkdir -p /var/lib/xiaoxia-saas-staging/artifacts"
-        scp -i "$key_path" "dist/staging-artifacts/xiaoxia-staging-${GITHUB_SHA}.tar.gz" \
-          "$staging_user@$staging_host:/var/lib/xiaoxia-saas-staging/artifacts/xiaoxia-staging-${GITHUB_SHA}.tar.gz"
-        scp -i "$key_path" "dist/staging-artifacts/xiaoxia-web-staging-${GITHUB_SHA}.tar" \
-          "$staging_user@$staging_host:/var/lib/xiaoxia-saas-staging/artifacts/xiaoxia-web-staging-${GITHUB_SHA}.tar"
-
-    - name: Deploy staging stack on business host
-      shell: sh
-      env:
-        STAGING_SSH_HOST: ${{ secrets.STAGING_SSH_HOST }}
-        STAGING_SSH_USER: ${{ secrets.STAGING_SSH_USER }}
-        STAGING_SSH_KEY: ${{ secrets.STAGING_SSH_KEY }}
-      run: |
-        set -eu
-        staging_host="${STAGING_SSH_HOST:-47.98.113.167}"
-        [ -z "$staging_host" ] && staging_host="47.98.113.167"
-        staging_user="${STAGING_SSH_USER:-root}"
-        key_path="/root/.ssh/xiaoxia_runtime_builder"
-        echo "Using SSH key: $key_path"
-        ls -la "$key_path"
-        test -f "$key_path" || { echo "ERROR: SSH key not found"; exit 1; }
-
-  build-production-runtime-images:
-    name: Build Production Runtime Images
-    runs-on: runtime-builder
-    if: github.ref_type == 'tag'
-
-    steps:
-    - name: Checkout code
-      shell: sh
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: |
-        set -eu
-        archive_url="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/archive/${GITHUB_SHA}.tar.gz"
-        wget --header="Authorization: token ${GITHUB_TOKEN}" -O /tmp/repo.tar.gz "$archive_url"
-        tar -xzf /tmp/repo.tar.gz --strip-components=1 -C .
-        rm -f /tmp/repo.tar.gz
-
-    - name: Build runtime image artifact
-      shell: sh
-      run: |
-        set -eu
-        chmod +x scripts/build_release_images.sh
-        scripts/build_release_images.sh "${GITHUB_REF_NAME}"
-
-    - name: Build production web artifact
-      shell: sh
-      run: |
-        set -eu
-        docker run --rm \
-          --pull=never \
-          -v "$PWD:/workspace" \
-          -w /workspace/apps/web \
-          node:20 \
-          sh -lc 'npm ci && npm run build'
-        docker build --pull=false \
-          -f infra/docker/web-artifact.Dockerfile \
-          -t "xiaoxia-saas-web:${GITHUB_REF_NAME}" \
-          .
-        test -f apps/web/dist/index.html
-
-    - name: Package release source artifact
-      shell: sh
-      run: |
-        set -eu
-        mkdir -p dist/release-artifacts
-        tar --exclude=.git --exclude=apps/web/node_modules --exclude=./dist \
-          -czf "dist/release-artifacts/xiaoxia-release-${GITHUB_REF_NAME}.tar.gz" .
-        docker save -o "dist/release-artifacts/xiaoxia-web-${GITHUB_REF_NAME}.tar" "xiaoxia-saas-web:${GITHUB_REF_NAME}"
-
-    - name: Upload runtime image and release artifacts
-      shell: sh
-      env:
-        PRODUCTION_SSH_HOST: ${{ secrets.PRODUCTION_SSH_HOST }}
-        PRODUCTION_SSH_USER: ${{ secrets.PRODUCTION_SSH_USER }}
-        PRODUCTION_SSH_KEY: ${{ secrets.PRODUCTION_SSH_KEY }}
-      run: |
-        set -eu
-        production_host="${PRODUCTION_SSH_HOST:-47.98.113.167}"
-        [ -z "$production_host" ] && production_host="47.98.113.167"
-        production_user="${PRODUCTION_SSH_USER:-root}"
-        mkdir -p ~/.ssh
-        key_path="/root/.ssh/xiaoxia_runtime_builder"
-        echo "Using SSH key: $key_path"
-        ls -la "$key_path"
-        test -f "$key_path" || { echo "ERROR: SSH key not found"; exit 1; }
-        ssh-keyscan -H "$production_host" >> ~/.ssh/known_hosts
-        ssh -i "$key_path" -o BatchMode=yes -o StrictHostKeyChecking=no "$production_user@$production_host" "echo SSH_OK" || { echo "SSH FAILED"; exit 1; }
-        scp -i "$key_path" "dist/release-images/xiaoxia-runtime-images-${GITHUB_REF_NAME}.tar" \
-          "$production_user@$production_host:/var/lib/xiaoxia-saas-production/runtime-images-${GITHUB_REF_NAME}.tar"
-        scp -i "$key_path" "dist/release-artifacts/xiaoxia-release-${GITHUB_REF_NAME}.tar.gz" \
-          "$production_user@$production_host:/var/lib/xiaoxia-saas-production/release-${GITHUB_REF_NAME}.tar.gz"
-        scp -i "$key_path" "dist/release-artifacts/xiaoxia-web-${GITHUB_REF_NAME}.tar" \
-          "$production_user@$production_host:/var/lib/xiaoxia-saas-production/web-${GITHUB_REF_NAME}.tar"
-
-  deploy-production:
-    name: Deploy Production
-    runs-on: runtime-builder
-    needs: build-production-runtime-images
-
-    steps:
-    - name: Deploy production over SSH
-      shell: sh
-      env:
-        PRODUCTION_SSH_HOST: ${{ secrets.PRODUCTION_SSH_HOST }}
-        PRODUCTION_SSH_USER: ${{ secrets.PRODUCTION_SSH_USER }}
-        PRODUCTION_SSH_KEY: ${{ secrets.PRODUCTION_SSH_KEY }}
-      run: |
-        set -eu
-        production_host="${PRODUCTION_SSH_HOST:-47.98.113.167}"
-        [ -z "$production_host" ] && production_host="47.98.113.167"
-        production_user="${PRODUCTION_SSH_USER:-root}"
-        mkdir -p ~/.ssh
-        key_path="/root/.ssh/xiaoxia_runtime_builder"
-        echo "Using SSH key: $key_path"
-        ls -la "$key_path"
-        test -f "$key_path" || { echo "ERROR: SSH key not found"; exit 1; }
-        ssh-keyscan -H "$production_host" >> ~/.ssh/known_hosts
-          echo 'c2V0IC1ldQpyZWxlYXNlX3Rhcj0iL3Zhci9saWIveGlhb3hpYS1zYWFzLXByb2R1Y3Rpb24vcmVsZWFzZS0ke1JFTEVBU0VfVkVSU0lPTn0udGFyLmd6Igp0ZXN0IC1mICIkcmVsZWFzZV90YXIiCnRlc3QgLWYgIi92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3J1bnRpbWUtaW1hZ2VzLSR7UkVMRUFTRV9WRVJTSU9OfS50YXIiCnRlc3QgLWYgIi92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3dlYi0ke1JFTEVBU0VfVkVSU0lPTn0udGFyIgpta2RpciAtcCAvdmFyL2xpYi94aWFveGlhLXNhYXMtcHJvZHVjdGlvbgpvbGRfYXNzZXRzX2Rpcj0iL3RtcC94aWFveGlhLXByZXZpb3VzLXdlYi1hc3NldHMtJHtSRUxFQVNFX1ZFUlNJT059IgpybSAtcmYgIiRvbGRfYXNzZXRzX2RpciIKbWtkaXIgLXAgIiRvbGRfYXNzZXRzX2RpciIKaWYgZG9ja2VyIGluc3BlY3QgeGlhb3hpYS13ZWItcHJvZHVjdGlvbiA+L2Rldi9udWxsIDI+JjE7IHRoZW4KICBkb2NrZXIgY3AgeGlhb3hpYS13ZWItcHJvZHVjdGlvbjovdXNyL3NoYXJlL25naW54L2h0bWwvYXNzZXRzLy4gIiRvbGRfYXNzZXRzX2RpciIvIDI+L2Rldi9udWxsIHx8IHRydWUKZmkKaWYgWyAtZCAvdmFyL2xpYi94aWFveGlhLXNhYXMtcHJvZHVjdGlvbi9yZXBvL2FwcHMvd2ViL2Rpc3QvYXNzZXRzIF07IHRoZW4KICBjcCAtYSAvdmFyL2xpYi94aWFveGlhLXNhYXMtcHJvZHVjdGlvbi9yZXBvL2FwcHMvd2ViL2Rpc3QvYXNzZXRzLy4gIiRvbGRfYXNzZXRzX2RpciIvCmZpCnJtIC1yZiAvdmFyL2xpYi94aWFveGlhLXNhYXMtcHJvZHVjdGlvbi9yZXBvCm1rZGlyIC1wIC92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3JlcG8KdGFyIC14emYgIiRyZWxlYXNlX3RhciIgLUMgL3Zhci9saWIveGlhb3hpYS1zYWFzLXByb2R1Y3Rpb24vcmVwbwp0ZXN0IC1mIC92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3JlcG8vYXBwcy93ZWIvZGlzdC9pbmRleC5odG1sCmlmIFsgLWQgIiRvbGRfYXNzZXRzX2RpciIgXTsgdGhlbgogIG1rZGlyIC1wIC92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3JlcG8vYXBwcy93ZWIvZGlzdC9hc3NldHMKICBmb3IgYXNzZXQgaW4gIiRvbGRfYXNzZXRzX2RpciIvKjsgZG8KICAgIFsgLWUgIiRhc3NldCIgXSB8fCBjb250aW51ZQogICAgbmFtZT0iJChiYXNlbmFtZSAiJGFzc2V0IikiCiAgICBpZiBbICEgLWUgIi92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3JlcG8vYXBwcy93ZWIvZGlzdC9hc3NldHMvJG5hbWUiIF07IHRoZW4KICAgICAgY3AgLWEgIiRhc3NldCIgIi92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uL3JlcG8vYXBwcy93ZWIvZGlzdC9hc3NldHMvJG5hbWUiCiAgICBmaQogIGRvbmUKICBybSAtcmYgIiRvbGRfYXNzZXRzX2RpciIKZmkKdGVzdCAtZiAvdmFyL2xpYi94aWFveGlhLXNhYXMtcHJvZHVjdGlvbi8uZW52CmNwIC92YXIvbGliL3hpYW94aWEtc2Fhcy1wcm9kdWN0aW9uLy5lbnYgL3Zhci9saWIveGlhb3hpYS1zYWFzLXByb2R1Y3Rpb24vcmVwby8uZW52CkhPU1RfUFJFRklYPSBXRUJfSU1BR0U9InhpYW94aWEtc2Fhcy13ZWI6JHtSRUxFQVNFX1ZFUlNJT059IiBXRUJfSU1BR0VfVEFSPSIvdmFyL2xpYi94aWFveGlhLXNhYXMtcHJvZHVjdGlvbi93ZWItJHtSRUxFQVNFX1ZFUlNJT059LnRhciIgc2ggL3Zhci9saWIveGlhb3hpYS1zYWFzLXByb2R1Y3Rpb24vcmVwby9pbmZyYS9kb2NrZXIvZGVwbG95LXByb2R1Y3Rpb24uc2gKaT0wCndoaWxlIFsgIiRpIiAtbHQgMzAgXTsgZG8KICBpZiB3Z2V0IC1xTy0gaHR0cDovLzEyNy4wLjAuMTo4MDAxL2hlYWx0aDsgdGhlbgogICAgZXhpdCAwCiAgZmkKICBpPSQoKGkgKyAxKSkKICBzbGVlcCAyCmRvbmUKZXhpdCAxCg==' | base64 -d | ssh -i "$key_path" "$production_user@$production_host" "RELEASE_VERSION='${GITHUB_REF_NAME}' sh"
-
-  production-e2e:
-    name: Production Browser E2E
-    runs-on: runtime-builder
-    needs: deploy-production
-
-    steps:
-    - name: Checkout code
-      shell: sh
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: |
-        set -eu
-        archive_url="${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/archive/${GITHUB_SHA}.tar.gz"
-        wget --header="Authorization: token ${GITHUB_TOKEN}" -O /tmp/repo.tar.gz "$archive_url"
-        tar -xzf /tmp/repo.tar.gz --strip-components=1 -C .
-        rm -f /tmp/repo.tar.gz
-
-    - name: Run production browser E2E
-      shell: sh
-      run: |
-        set -eu
-        docker run --rm \
-          -e E2E_BASE_URL=https://saas.xiaoxiajianji.com \
-          -e E2E_API_BASE=https://api.xiaoxiajianji.com/api/v1 \
-          -e E2E_BROWSER_CHANNEL=chromium \
-          -v "$PWD:/workspace" \
-          -w /workspace/apps/web \
-          mcr.microsoft.com/playwright:v1.45.0-jammy \
-          sh -lc 'npm ci && npx playwright test --reporter=line --project=chromium e2e/core-upload.spec.ts e2e/core-generation.spec.ts e2e/core-titles.spec.ts'
-

.gitea/workflows/tests.yml

@@ -1,107 +0,0 @@
-name: Tests
-
-on:
-  pull_request:
-    branches: [ main ]
-
-jobs:
-  test:
-    runs-on: runtime-builder
-
-    steps:
-    - name: Checkout code
-      shell: sh
-      run: |
-        set -eu
-        python - <<'PY'
-        import io
-        import os
-        import tarfile
-        import urllib.request
-
-        url = f"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz"
-        request = urllib.request.Request(url, headers={"Authorization": f"token {os.environ['GITHUB_TOKEN']}"})
-        with urllib.request.urlopen(request, timeout=120) as response:
-            archive = response.read()
-
-        with tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:
-            root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'
-            for member in tar.getmembers():
-                name = member.name
-                if name == root_prefix[:-1]:
-                    continue
-                if name.startswith(root_prefix):
-                    member.name = name[len(root_prefix):]
-                if member.name:
-                    tar.extract(member, '.')
-        PY
-
-    - name: Show Python version
-      shell: sh
-      run: |
-        set -eu
-        python --version
-        python -m pip --version
-
-    - name: Install dependencies
-      shell: sh
-      run: |
-        set -eu
-        python -m pip install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
-        python -m pip install -r requirements.txt -r requirements-dev.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
-
-    - name: Run tests
-      shell: sh
-      run: |
-        set -eu
-        PYTHONPATH="$PWD/apps/api:$PWD" python -m pytest tests/unit -q
-
-  lint:
-    runs-on: runtime-builder
-
-    steps:
-    - name: Checkout code
-      shell: sh
-      run: |
-        set -eu
-        python - <<'PY'
-        import io
-        import os
-        import tarfile
-        import urllib.request
-
-        url = f"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz"
-        request = urllib.request.Request(url, headers={"Authorization": f"token {os.environ['GITHUB_TOKEN']}"})
-        with urllib.request.urlopen(request, timeout=120) as response:
-            archive = response.read()
-
-        with tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:
-            root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'
-            for member in tar.getmembers():
-                name = member.name
-                if name == root_prefix[:-1]:
-                    continue
-                if name.startswith(root_prefix):
-                    member.name = name[len(root_prefix):]
-                if member.name:
-                    tar.extract(member, '.')
-        PY
-
-    - name: Install dependencies
-      shell: sh
-      run: |
-        set -eu
-        python -m pip install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
-        python -m pip install -r requirements.txt -r requirements-dev.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
-
-    - name: Run Black (check only)
-      shell: sh
-      run: |
-        set -eu
-        python -m black --check alembic apps packages tests scripts
-
-    - name: Run Flake8
-      shell: sh
-      run: |
-        set -eu
-        python -m flake8 apps packages tests --count --statistics

.gitignore

@@ -6,6 +6,7 @@ dist/
 coverage/
 
 # Python / backend
+.cache/
 .venv/
 venv/
 .venv-ci-root/
@@ -47,5 +48,4 @@ build/
 # Tracker temp files
 tracker_tasks.json
 
-# Schema metadata snapshot
-schema-metadata-snapshot.json
+frontend-v21-ui-prototype-final.html

CHANGELOG.md

@@ -1,19 +1,276 @@
-# Changelog
+## [v0.1.110] - 2026-07-03
 
-All notable changes to this project will be documented in this file.
+### 🔒 安全修复
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+- 注册登录接口添加 RateLimitMiddleware 防止暴力破解
+- JWT logout 黑名单机制，防止令牌重放攻击
+- 生产环境禁用 Swagger 文档防止信息泄露
+- `/metrics` 端点添加 Bearer Token 认证
+- 禁用 SVG 上传防止 XSS 风险
+- 删除 `decode_token_unsafe()` 方法，消除不安全的 JWT 解码
+- 移除遗留 `tasks.py` 消除 Celery 任务名冲突
+- 清理全局 `except:pass`（22处）改为 `logger.warning` 记录异常
+
+### ✨ 功能
+
+- 添加剪辑计划时间线场景 API (`GET /edit-plans/{id}/timeline`)
+- 前端对接真实 API 替换 mock 数据
+
+### 🐛 Bug 修复
+
+- **[P1]** 修复登录故障 — `password_hasher` 导入错误
+- 订阅续费事务修复 — 支付回调在数据库事务中更新订阅状态
+- 账单返回空数组修复 — 从数据库查询账单记录
+- 修复 `Image.open()` 资源泄漏
+- 清理已移除 workspace 概念的残留引用
+- 修复 AssetLibrary/TemplateLibrary 类型错误
+- 修复前端 workspace 残留导致项目创建失败
+- 永久修复 nginx `proxy_pass` 配置
+- 添加 Docker DNS resolver 防止 API 容器重启后 502
+- 修复 worker healthcheck YAML 语法
+- 修复 204 响应体断言崩溃
+- 修复 Alembic 元数据漂移检测
+- 修复 migration 009 DEFAULT 表达式 PostgreSQL 兼容性
+
+### 🔄 重构与清理
+
+- 后端代码清理 — 移除死代码和无用文件
+- 前端代码清理 — 移除无用代码和遗留 demo
+- 代码精简优化 — 移除无用代码和重复定义
+- 后端代码 black/isort 格式化
+
+### 🧪 测试
+
+- 完善 E2E 错误场景测试，Playwright 接入 CI
+- API 集成测试补充（145 项通过）
+- 添加核心流程 E2E 测试
+
+### 🚀 CI/CD & 基础设施
+
+- Validate 阶段添加 PostgreSQL 服务支持
+- 所有 workflow checkout 添加 5 次指数退避重试
+- 启用 BuildKit 分布式缓存 + Gitea Registry 优化构建速度
+- Deploy 阶段全面修复（E2E 服务器/Worker venv/Registry 登录）
+- Docker 网络隔离 staging/production 环境
+- 修复 CI 代码质量检查（black/flake8/bandit）
+
+---
+
+## [v0.1.88] - 2026-06-29
+
+### Phase 2 前端优化 - 完成 ✅
+
+**前端交互全面优化:**
+
+- 素材上传添加 project_id 参数
+- Drager 组件显示上传列表
+- 按钮防重复提交
+- 前端交互状态反馈补充（P0 第一批）
+
+---
+
+## [v0.1.87] - 2026-06-29
+
+### Bug 修复
+
+- Docker compose 修复 mem_limit 冲突
+
+---
+
+## [v0.1.86] - 2026-06-29
+
+### CI/CD 优化
+
+- CI 优化
+
+---
+
+## [v0.1.85] - 2026-06-29
+
+### CI/CD 优化
+
+- CI 优化
+
+---
+
+## [v0.1.84] - 2026-06-29
+
+### CI/CD 优化
+
+- CI runner label 匹配修复
+
+---
+
+## [v0.1.83] - 2026-06-29
+
+### CI/CD 优化
+
+- CI SSH debug 修正
+
+---
+
+## [v0.1.82] - 2026-06-29
+
+### CI/CD 优化
+
+- CI SSH debug 修正
+
+---
+
+## [v0.1.81] - 2026-06-29
+
+### CI/CD 优化
+
+- CI runner label 匹配修复
+
+---
+
+## [v0.1.80] - 2026-06-28
+
+### Bug 修复
+
+- 修复 redirect_slashes + 标题字段匹配
+
+---
+
+## [v0.1.79] - 2026-06-28
+
+### Deployment
+
+- Re-trigger deployment
+
+---
+
+## [v0.1.78] - 2026-06-28
+
+### Bug 修复
+
+- 修复 500 错误
+- CORS 配置修复
+- redirect_slashes 禁用
+
+---
+
+## [v0.1.77] - 2026-06-28
+
+### Bug 修复
+
+- 修复标题库新建/编辑 — 前后端字段名不匹配导致 422
+
+---
+
+### Phase 2 功能合并（v0.1.77 ~ v0.1.88）
+
+**新增功能 PR:**
+
+- PR#74: Phase 1 核心重构 — 标题库 API、配音库 API、去 Project 层清理
+- PR#75: Phase 2 查重功能前端页面
+- PR#76: Phase 2 查重功能后端 API（5 个端点）
+- PR#77: Phase 2 订阅管理前端页面
+- PR#78: Phase 2 订阅管理后端 API（5 个端点）
+- PR#79: 修复一键生成页面废弃 API 调用
+- PR#80: 回退域对象 extra_meta → metadata
+- PR#81: 删除查重 API 错误的 204 返回
+- PR#82: 查重上传接口错误信息不再泄露内部异常（安全审计）
+- PR#83: 订阅 + 查重单元测试（63 用例）
+- PR#84: 订阅管理前端对接真实 API
+- PR#85: 禁用 redirect_slashes 修复 307 重定向
+- PR#90: 标题库字段名修复
+- PR#91: 标题/配音创建 500 修复 + CORS
+- PR#94: 素材库新建自动获取默认 project_id
+- PR#97: 前端交互状态反馈全面补充
+
+---
+
+
+- Docker compose 修复 mem_limit 冲突
+
+---
+
+## [v0.1.86] - 2026-06-29
+
+### CI/CD 优化
+
+- CI 优化
+
+---
+
+## [v0.1.85] - 2026-06-29
+
+### CI/CD 优化
+
+- CI 优化
+
+---
+
+## [v0.1.84] - 2026-06-29
+
+### CI/CD 优化
+
+- CI runner label 匹配修复
+
+---
+
+## [v0.1.83] - 2026-06-29
+
+### CI/CD 优化
+
+- CI SSH debug 修正
+
+---
+
+## [v0.1.82] - 2026-06-29
+
+### CI/CD 优化
+
+- CI SSH debug 修正
+
+---
+
+## [v0.1.81] - 2026-06-29
+
+### CI/CD 优化
+
+- CI runner label 匹配修复
+
+---
+
+## [v0.1.80] - 2026-06-28
+
+### Bug 修复
+
+- 修复 redirect_slashes + 标题字段匹配
+
+---
+
+## [v0.1.79] - 2026-06-28
+
+### Deployment
+
+- Re-trigger deployment
+
+---
+
+## [v0.1.78] - 2026-06-28
+
+### Bug 修复
+
+- 修复 500 错误
+- CORS 配置修复
+- redirect_slashes 禁用
+
+---
+
+## [v0.1.77] - 2026-06-28
+
+### Bug 修复
+
+- 修复标题库新建/编辑 — 前后端字段名不匹配导致 422
+
+---
 
 ## [Unreleased]
 
-## [1.2.0] - 2026-06-19
-
-### Phase 7: 核心视频剪辑业务 - 完成 ✅
-
-**完成进度:** 100%  
-**状态:** 已完成并验证
-
 #### Added
 
 **素材管理:**

alembic/versions/007_add_editing_mode.py

@@ -4,25 +4,26 @@ Revision ID: 007
 Revises: 006
 Create Date: 2026-06-26
 """
-from alembic import op
+
 import sqlalchemy as sa
 
+from alembic import op
+
 # revision identifiers
-revision = '007'
-down_revision = '006'
+revision = "007"
+down_revision = "006"
 branch_labels = None
 depends_on = None
 
 
 def upgrade() -> None:
     op.add_column(
-        'generation_tasks',
-        sa.Column('editing_mode', sa.String(20), nullable=False, server_default='one_take')
+        "generation_tasks", sa.Column("editing_mode", sa.String(20), nullable=False, server_default="one_take")
     )
     # 添加索引以支持查询
-    op.create_index('ix_generation_tasks_editing_mode', 'generation_tasks', ['editing_mode'])
+    op.create_index("ix_generation_tasks_editing_mode", "generation_tasks", ["editing_mode"])
 
 
 def downgrade() -> None:
-    op.drop_index('ix_generation_tasks_editing_mode', table_name='generation_tasks')
-    op.drop_column('generation_tasks', 'editing_mode')
+    op.drop_index("ix_generation_tasks_editing_mode", table_name="generation_tasks")
+    op.drop_column("generation_tasks", "editing_mode")

alembic/versions/008_add_video_dedup_fields.py

@@ -4,6 +4,7 @@ Revision ID: 008
 Revises: 007
 Create Date: 2024-06-26
 """
+
 import sqlalchemy as sa
 
 from alembic import op
@@ -16,20 +17,11 @@ depends_on = None
 
 def upgrade() -> None:
     # Add video_fingerprint column as JSON text
-    op.add_column(
-        "generated_videos",
-        sa.Column("video_fingerprint", sa.Text(), nullable=True)
-    )
+    op.add_column("generated_videos", sa.Column("video_fingerprint", sa.Text(), nullable=True))
     # Add is_duplicate column
-    op.add_column(
-        "generated_videos",
-        sa.Column("is_duplicate", sa.Boolean(), nullable=False, server_default="false")
-    )
+    op.add_column("generated_videos", sa.Column("is_duplicate", sa.Boolean(), nullable=False, server_default="false"))
     # Add duplicate_of column for tracking original video
-    op.add_column(
-        "generated_videos",
-        sa.Column("duplicate_of", sa.String(32), nullable=True)
-    )
+    op.add_column("generated_videos", sa.Column("duplicate_of", sa.String(32), nullable=True))
 
 
 def downgrade() -> None:

alembic/versions/009_remove_workspace_concept.py

@@ -11,10 +11,12 @@ This migration:
 4. Removes workspace_id from all tables that had it
 5. Drops workspace-related tables: workspaces, workspace_members, workspace_invitations
 """
-from alembic import op
+
 import sqlalchemy as sa
 from sqlalchemy import text
 
+from alembic import op
+
 # revision identifiers
 revision = "009"
 down_revision = "008"
@@ -24,15 +26,15 @@ depends_on = None
 
 def upgrade() -> None:
     conn = op.get_bind()
-    
+
     # Step 1: Add subscription/quota fields to users table
     conn.execute(text("""
         ALTER TABLE users
-        ADD COLUMN IF NOT EXISTS subscription_plan VARCHAR(20) NOT NULL DEFAULT free
+        ADD COLUMN IF NOT EXISTS subscription_plan VARCHAR(20) NOT NULL DEFAULT 'free'
     """))
     conn.execute(text("""
         ALTER TABLE users
-        ADD COLUMN IF NOT EXISTS subscription_status VARCHAR(20) NOT NULL DEFAULT active
+        ADD COLUMN IF NOT EXISTS subscription_status VARCHAR(20) NOT NULL DEFAULT 'active'
     """))
     conn.execute(text("""
         ALTER TABLE users
@@ -50,7 +52,7 @@ def upgrade() -> None:
         ALTER TABLE users
         ADD COLUMN IF NOT EXISTS used_storage_gb FLOAT NOT NULL DEFAULT 0
     """))
-    
+
     # Step 2: Copy subscription data from workspaces to users
     conn.execute(text("""
         UPDATE users SET
@@ -63,7 +65,7 @@ def upgrade() -> None:
         FROM workspaces w
         WHERE w.owner_user_id = users.id
     """))
-    
+
     # Step 3: Add owner_user_id and shared_users to projects table
     conn.execute(text("""
         ALTER TABLE projects
@@ -73,7 +75,7 @@ def upgrade() -> None:
         ALTER TABLE projects
         ADD COLUMN IF NOT EXISTS shared_users JSON
     """))
-    
+
     # Step 4: Migrate workspace_id to owner_user_id (from workspace_members where role=owner)
     conn.execute(text("""
         UPDATE projects SET
@@ -82,13 +84,13 @@ def upgrade() -> None:
         WHERE wm.workspace_id = projects.workspace_id
         AND wm.role = 'owner'
     """))
-    
+
     # Set shared_users to empty array for all projects
     conn.execute(text("""
         UPDATE projects SET shared_users = '[]'::json
         WHERE shared_users IS NULL
     """))
-    
+
     # Step 5: Remove workspace_id from all tables
     tables_with_workspace_id = [
         "asset_libraries",
@@ -104,12 +106,12 @@ def upgrade() -> None:
         "tasks",
         "task_issues",
     ]
-    
+
     for table in tables_with_workspace_id:
         conn.execute(text(f"""
             ALTER TABLE {table} DROP COLUMN IF EXISTS workspace_id
         """))
-    
+
     # Step 6: Drop workspace-related tables
     conn.execute(text("""
         DROP TABLE IF EXISTS workspace_invitations
@@ -120,7 +122,7 @@ def upgrade() -> None:
     conn.execute(text("""
         DROP TABLE IF EXISTS workspaces
     """))
-    
+
     # Step 7: Drop workspace_id from projects table
     conn.execute(text("""
         ALTER TABLE projects DROP COLUMN IF EXISTS workspace_id
@@ -129,15 +131,15 @@ def upgrade() -> None:
 
 def downgrade() -> None:
     conn = op.get_bind()
-    
+
     # Add back workspace tables (simplified - in real scenario would need full recreation)
     conn.execute(text("""
         CREATE TABLE IF NOT EXISTS workspaces (
             id VARCHAR(36) PRIMARY KEY,
             name VARCHAR(100) NOT NULL,
             owner_user_id VARCHAR(36) NOT NULL,
-            subscription_plan VARCHAR(20) NOT NULL DEFAULT free,
-            subscription_status VARCHAR(20) NOT NULL DEFAULT active,
+            subscription_plan VARCHAR(20) NOT NULL DEFAULT 'free',
+            subscription_status VARCHAR(20) NOT NULL DEFAULT 'active',
             subscription_expires_at TIMESTAMP,
             max_projects FLOAT NOT NULL DEFAULT 3,
             max_storage_gb FLOAT NOT NULL DEFAULT 10,
@@ -145,7 +147,7 @@ def downgrade() -> None:
             created_at TIMESTAMP NOT NULL DEFAULT NOW()
         )
     """))
-    
+
     conn.execute(text("""
         CREATE TABLE IF NOT EXISTS workspace_members (
             id VARCHAR(36) PRIMARY KEY,
@@ -157,7 +159,7 @@ def downgrade() -> None:
             UNIQUE(workspace_id, user_id)
         )
     """))
-    
+
     conn.execute(text("""
         CREATE TABLE IF NOT EXISTS workspace_invitations (
             id VARCHAR(36) PRIMARY KEY,
@@ -166,18 +168,18 @@ def downgrade() -> None:
             invitee_email VARCHAR(255) NOT NULL,
             role VARCHAR(20) NOT NULL,
             invitation_token VARCHAR(255) NOT NULL UNIQUE,
-            status VARCHAR(20) NOT NULL DEFAULT pending,
+            status VARCHAR(20) NOT NULL DEFAULT 'pending',
             expires_at TIMESTAMP,
             accepted_at TIMESTAMP,
             created_at TIMESTAMP NOT NULL DEFAULT NOW()
         )
     """))
-    
+
     # Add back workspace_id column to projects
     conn.execute(text("""
         ALTER TABLE projects ADD COLUMN workspace_id VARCHAR(32)
     """))
-    
+
     # Add back workspace_id columns to other tables
     tables_with_workspace_id = [
         "asset_libraries",
@@ -193,11 +195,11 @@ def downgrade() -> None:
         "tasks",
         "task_issues",
     ]
-    
+
     for table in tables_with_workspace_id:
         conn.execute(text(f"""
             ALTER TABLE {table} ADD COLUMN workspace_id VARCHAR(36)
         """))
-    
+
     # Note: This downgrade is incomplete - projects.owner_user_id data would need to be
     # converted back to workspace_ids, which requires reconstructing workspace records.

alembic/versions/010_add_foreign_key_constraints.py

@@ -1,190 +0,0 @@
-"""add foreign key constraints and missing indexes
-
-Revision ID: 010
-Revises: 009
-Create Date: 2026-06-28
-
-Summary:
-- Add ForeignKey constraints to all 35 logical FK columns across 16 tables
-- ON DELETE CASCADE for parent-child relationships (project → children)
-- ON DELETE SET NULL for optional user references (created_by, assignee, etc.)
-- Add missing indexes on 10 FK columns
-- Alter columns from NOT NULL to nullable where SET NULL is needed
-"""
-
-from alembic import op
-import sqlalchemy as sa
-
-revision = "010"
-down_revision = "009"
-branch_labels = None
-depends_on = None
-
-
-def upgrade() -> None:
-    # ── projects ──────────────────────────────────────────────
-    op.create_foreign_key("fk_projects_owner_user_id", "projects", "users", ["owner_user_id"], ["id"], ondelete="CASCADE")
-
-    # ── asset_libraries ───────────────────────────────────────
-    op.create_foreign_key("fk_asset_libraries_project_id", "asset_libraries", "projects", ["project_id"], ["id"], ondelete="CASCADE")
-
-    # ── assets ────────────────────────────────────────────────
-    # uploaded_by_user_id: nullable=False → nullable=True for SET NULL
-    op.alter_column("assets", "uploaded_by_user_id", existing_type=sa.String(36), nullable=True)
-    op.create_foreign_key("fk_assets_project_id", "assets", "projects", ["project_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_assets_asset_library_id", "assets", "asset_libraries", ["asset_library_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_assets_uploaded_by_user_id", "assets", "users", ["uploaded_by_user_id"], ["id"], ondelete="SET NULL")
-    # Add missing index
-    op.create_index("ix_assets_uploaded_by_user_id", "assets", ["uploaded_by_user_id"])
-
-    # ── project_titles ────────────────────────────────────────
-    # created_by_user_id: nullable=False → nullable=True for SET NULL
-    op.alter_column("project_titles", "created_by_user_id", existing_type=sa.String(36), nullable=True)
-    op.create_foreign_key("fk_project_titles_project_id", "project_titles", "projects", ["project_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_project_titles_created_by_user_id", "project_titles", "users", ["created_by_user_id"], ["id"], ondelete="SET NULL")
-    # Add missing index
-    op.create_index("ix_project_titles_created_by_user_id", "project_titles", ["created_by_user_id"])
-
-    # ── edit_templates ────────────────────────────────────────
-    # created_by_user_id: nullable=False → nullable=True for SET NULL
-    op.alter_column("edit_templates", "created_by_user_id", existing_type=sa.String(32), nullable=True)
-    op.create_foreign_key("fk_edit_templates_project_id", "edit_templates", "projects", ["project_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_edit_templates_created_by_user_id", "edit_templates", "users", ["created_by_user_id"], ["id"], ondelete="SET NULL")
-
-    # ── edit_plans ────────────────────────────────────────────
-    # title_id: nullable=False → nullable=True for SET NULL
-    # created_by_user_id: nullable=False → nullable=True for SET NULL
-    op.alter_column("edit_plans", "title_id", existing_type=sa.String(32), nullable=True)
-    op.alter_column("edit_plans", "created_by_user_id", existing_type=sa.String(32), nullable=True)
-    op.create_foreign_key("fk_edit_plans_project_id", "edit_plans", "projects", ["project_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_edit_plans_template_id", "edit_plans", "edit_templates", ["template_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_edit_plans_asset_library_id", "edit_plans", "asset_libraries", ["asset_library_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_edit_plans_title_id", "edit_plans", "project_titles", ["title_id"], ["id"], ondelete="SET NULL")
-    op.create_foreign_key("fk_edit_plans_created_by_user_id", "edit_plans", "users", ["created_by_user_id"], ["id"], ondelete="SET NULL")
-
-    # ── edit_plan_clips ───────────────────────────────────────
-    op.create_foreign_key("fk_edit_plan_clips_edit_plan_id", "edit_plan_clips", "edit_plans", ["edit_plan_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_edit_plan_clips_asset_id", "edit_plan_clips", "assets", ["asset_id"], ["id"], ondelete="CASCADE")
-
-    # ── ingest_jobs ───────────────────────────────────────────
-    # result_asset_id: nullable=False → nullable=True for SET NULL
-    op.alter_column("ingest_jobs", "result_asset_id", existing_type=sa.String(32), nullable=True)
-    op.create_foreign_key("fk_ingest_jobs_project_id", "ingest_jobs", "projects", ["project_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_ingest_jobs_library_id", "ingest_jobs", "asset_libraries", ["library_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_ingest_jobs_result_asset_id", "ingest_jobs", "assets", ["result_asset_id"], ["id"], ondelete="SET NULL")
-
-    # ── classification_jobs ───────────────────────────────────
-    op.create_foreign_key("fk_classification_jobs_project_id", "classification_jobs", "projects", ["project_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_classification_jobs_asset_id", "classification_jobs", "assets", ["asset_id"], ["id"], ondelete="CASCADE")
-
-    # ── generation_tasks ──────────────────────────────────────
-    # edit_plan_id: nullable=False → nullable=True for SET NULL
-    # created_by_user_id: nullable=False → nullable=True for SET NULL
-    op.alter_column("generation_tasks", "edit_plan_id", existing_type=sa.String(32), nullable=True)
-    op.alter_column("generation_tasks", "created_by_user_id", existing_type=sa.String(32), nullable=True)
-    op.create_foreign_key("fk_generation_tasks_project_id", "generation_tasks", "projects", ["project_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_generation_tasks_asset_library_id", "generation_tasks", "asset_libraries", ["asset_library_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_generation_tasks_edit_plan_id", "generation_tasks", "edit_plans", ["edit_plan_id"], ["id"], ondelete="SET NULL")
-    op.create_foreign_key("fk_generation_tasks_created_by_user_id", "generation_tasks", "users", ["created_by_user_id"], ["id"], ondelete="SET NULL")
-
-    # ── generated_videos ──────────────────────────────────────
-    op.create_foreign_key("fk_generated_videos_project_id", "generated_videos", "projects", ["project_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_generated_videos_generation_task_id", "generated_videos", "generation_tasks", ["generation_task_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_generated_videos_duplicate_of", "generated_videos", "generated_videos", ["duplicate_of"], ["id"], ondelete="SET NULL")
-
-    # ── tasks ─────────────────────────────────────────────────
-    # parent_task_id: nullable=False → nullable=True for SET NULL
-    # assignee_user_id: nullable=False → nullable=True for SET NULL
-    op.alter_column("tasks", "parent_task_id", existing_type=sa.String(32), nullable=True)
-    op.alter_column("tasks", "assignee_user_id", existing_type=sa.String(32), nullable=True)
-    op.create_foreign_key("fk_tasks_project_id", "tasks", "projects", ["project_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_tasks_parent_task_id", "tasks", "tasks", ["parent_task_id"], ["id"], ondelete="SET NULL")
-    op.create_foreign_key("fk_tasks_assignee_user_id", "tasks", "users", ["assignee_user_id"], ["id"], ondelete="SET NULL")
-
-    # ── milestones ────────────────────────────────────────────
-    op.create_foreign_key("fk_milestones_project_id", "milestones", "projects", ["project_id"], ["id"], ondelete="CASCADE")
-
-    # ── task_issues ───────────────────────────────────────────
-    # created_by_user_id: nullable=False → nullable=True for SET NULL
-    op.alter_column("task_issues", "created_by_user_id", existing_type=sa.String(32), nullable=True)
-    op.create_foreign_key("fk_task_issues_task_id", "task_issues", "tasks", ["task_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_task_issues_project_id", "task_issues", "projects", ["project_id"], ["id"], ondelete="CASCADE")
-    op.create_foreign_key("fk_task_issues_created_by_user_id", "task_issues", "users", ["created_by_user_id"], ["id"], ondelete="SET NULL")
-
-
-def downgrade() -> None:
-    # ── task_issues ───────────────────────────────────────────
-    op.drop_constraint("fk_task_issues_created_by_user_id", "task_issues", type_="foreignkey")
-    op.drop_constraint("fk_task_issues_project_id", "task_issues", type_="foreignkey")
-    op.drop_constraint("fk_task_issues_task_id", "task_issues", type_="foreignkey")
-    op.alter_column("task_issues", "created_by_user_id", existing_type=sa.String(32), nullable=False)
-
-    # ── milestones ────────────────────────────────────────────
-    op.drop_constraint("fk_milestones_project_id", "milestones", type_="foreignkey")
-
-    # ── tasks ─────────────────────────────────────────────────
-    op.drop_constraint("fk_tasks_assignee_user_id", "tasks", type_="foreignkey")
-    op.drop_constraint("fk_tasks_parent_task_id", "tasks", type_="foreignkey")
-    op.drop_constraint("fk_tasks_project_id", "tasks", type_="foreignkey")
-    op.alter_column("tasks", "assignee_user_id", existing_type=sa.String(32), nullable=False)
-    op.alter_column("tasks", "parent_task_id", existing_type=sa.String(32), nullable=False)
-
-    # ── generated_videos ──────────────────────────────────────
-    op.drop_constraint("fk_generated_videos_duplicate_of", "generated_videos", type_="foreignkey")
-    op.drop_constraint("fk_generated_videos_generation_task_id", "generated_videos", type_="foreignkey")
-    op.drop_constraint("fk_generated_videos_project_id", "generated_videos", type_="foreignkey")
-
-    # ── generation_tasks ──────────────────────────────────────
-    op.drop_constraint("fk_generation_tasks_created_by_user_id", "generation_tasks", type_="foreignkey")
-    op.drop_constraint("fk_generation_tasks_edit_plan_id", "generation_tasks", type_="foreignkey")
-    op.drop_constraint("fk_generation_tasks_asset_library_id", "generation_tasks", type_="foreignkey")
-    op.drop_constraint("fk_generation_tasks_project_id", "generation_tasks", type_="foreignkey")
-    op.alter_column("generation_tasks", "created_by_user_id", existing_type=sa.String(32), nullable=False)
-    op.alter_column("generation_tasks", "edit_plan_id", existing_type=sa.String(32), nullable=False)
-
-    # ── classification_jobs ───────────────────────────────────
-    op.drop_constraint("fk_classification_jobs_asset_id", "classification_jobs", type_="foreignkey")
-    op.drop_constraint("fk_classification_jobs_project_id", "classification_jobs", type_="foreignkey")
-
-    # ── ingest_jobs ───────────────────────────────────────────
-    op.drop_constraint("fk_ingest_jobs_result_asset_id", "ingest_jobs", type_="foreignkey")
-    op.drop_constraint("fk_ingest_jobs_library_id", "ingest_jobs", type_="foreignkey")
-    op.drop_constraint("fk_ingest_jobs_project_id", "ingest_jobs", type_="foreignkey")
-    op.alter_column("ingest_jobs", "result_asset_id", existing_type=sa.String(32), nullable=False)
-
-    # ── edit_plan_clips ───────────────────────────────────────
-    op.drop_constraint("fk_edit_plan_clips_asset_id", "edit_plan_clips", type_="foreignkey")
-    op.drop_constraint("fk_edit_plan_clips_edit_plan_id", "edit_plan_clips", type_="foreignkey")
-
-    # ── edit_plans ────────────────────────────────────────────
-    op.drop_constraint("fk_edit_plans_created_by_user_id", "edit_plans", type_="foreignkey")
-    op.drop_constraint("fk_edit_plans_title_id", "edit_plans", type_="foreignkey")
-    op.drop_constraint("fk_edit_plans_asset_library_id", "edit_plans", type_="foreignkey")
-    op.drop_constraint("fk_edit_plans_template_id", "edit_plans", type_="foreignkey")
-    op.drop_constraint("fk_edit_plans_project_id", "edit_plans", type_="foreignkey")
-    op.alter_column("edit_plans", "created_by_user_id", existing_type=sa.String(32), nullable=False)
-    op.alter_column("edit_plans", "title_id", existing_type=sa.String(32), nullable=False)
-
-    # ── edit_templates ────────────────────────────────────────
-    op.drop_constraint("fk_edit_templates_created_by_user_id", "edit_templates", type_="foreignkey")
-    op.drop_constraint("fk_edit_templates_project_id", "edit_templates", type_="foreignkey")
-    op.alter_column("edit_templates", "created_by_user_id", existing_type=sa.String(32), nullable=False)
-
-    # ── project_titles ────────────────────────────────────────
-    op.drop_index("ix_project_titles_created_by_user_id", table_name="project_titles")
-    op.drop_constraint("fk_project_titles_created_by_user_id", "project_titles", type_="foreignkey")
-    op.drop_constraint("fk_project_titles_project_id", "project_titles", type_="foreignkey")
-    op.alter_column("project_titles", "created_by_user_id", existing_type=sa.String(36), nullable=False)
-
-    # ── assets ────────────────────────────────────────────────
-    op.drop_index("ix_assets_uploaded_by_user_id", table_name="assets")
-    op.drop_constraint("fk_assets_uploaded_by_user_id", "assets", type_="foreignkey")
-    op.drop_constraint("fk_assets_asset_library_id", "assets", type_="foreignkey")
-    op.drop_constraint("fk_assets_project_id", "assets", type_="foreignkey")
-    op.alter_column("assets", "uploaded_by_user_id", existing_type=sa.String(36), nullable=False)
-
-    # ── asset_libraries ───────────────────────────────────────
-    op.drop_constraint("fk_asset_libraries_project_id", "asset_libraries", type_="foreignkey")
-
-    # ── projects ──────────────────────────────────────────────
-    op.drop_constraint("fk_projects_owner_user_id", "projects", type_="foreignkey")

alembic/versions/010_phase0_extensibility.py

@@ -10,9 +10,11 @@ This migration:
 2. Creates title_libraries table (独立标题库，支持跨项目复用)
 3. Creates voice_libraries table (配音库，支持 AI 配音管理)
 """
-from alembic import op
+
 import sqlalchemy as sa
 
+from alembic import op
+
 # revision identifiers
 revision = "010"
 down_revision = "009"
@@ -25,21 +27,11 @@ def upgrade() -> None:
 
     # ── 1. Add metadata JSONB to existing tables ──
 
-    conn.execute(sa.text(
-        "ALTER TABLE projects ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}'"
-    ))
-    conn.execute(sa.text(
-        "ALTER TABLE asset_libraries ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}'"
-    ))
-    conn.execute(sa.text(
-        "ALTER TABLE assets ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}'"
-    ))
-    conn.execute(sa.text(
-        "ALTER TABLE edit_templates ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}'"
-    ))
-    conn.execute(sa.text(
-        "ALTER TABLE generation_tasks ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}'"
-    ))
+    conn.execute(sa.text("ALTER TABLE projects ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}'"))
+    conn.execute(sa.text("ALTER TABLE asset_libraries ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}'"))
+    conn.execute(sa.text("ALTER TABLE assets ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}'"))
+    conn.execute(sa.text("ALTER TABLE edit_templates ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}'"))
+    conn.execute(sa.text("ALTER TABLE generation_tasks ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}'"))
 
     # ── 2. Create title_libraries table ──
 
@@ -59,15 +51,9 @@ def upgrade() -> None:
             updated_at TIMESTAMP NOT NULL DEFAULT NOW()
         )
     """))
-    conn.execute(sa.text(
-        "CREATE INDEX IF NOT EXISTS ix_title_libraries_user_id ON title_libraries(user_id)"
-    ))
-    conn.execute(sa.text(
-        "CREATE INDEX IF NOT EXISTS ix_title_libraries_category ON title_libraries(category)"
-    ))
-    conn.execute(sa.text(
-        "CREATE INDEX IF NOT EXISTS ix_title_libraries_is_active ON title_libraries(is_active)"
-    ))
+    conn.execute(sa.text("CREATE INDEX IF NOT EXISTS ix_title_libraries_user_id ON title_libraries(user_id)"))
+    conn.execute(sa.text("CREATE INDEX IF NOT EXISTS ix_title_libraries_category ON title_libraries(category)"))
+    conn.execute(sa.text("CREATE INDEX IF NOT EXISTS ix_title_libraries_is_active ON title_libraries(is_active)"))
 
     # ── 3. Create voice_libraries table ──
 
@@ -91,15 +77,9 @@ def upgrade() -> None:
             updated_at TIMESTAMP NOT NULL DEFAULT NOW()
         )
     """))
-    conn.execute(sa.text(
-        "CREATE INDEX IF NOT EXISTS ix_voice_libraries_user_id ON voice_libraries(user_id)"
-    ))
-    conn.execute(sa.text(
-        "CREATE INDEX IF NOT EXISTS ix_voice_libraries_project_id ON voice_libraries(project_id)"
-    ))
-    conn.execute(sa.text(
-        "CREATE INDEX IF NOT EXISTS ix_voice_libraries_status ON voice_libraries(status)"
-    ))
+    conn.execute(sa.text("CREATE INDEX IF NOT EXISTS ix_voice_libraries_user_id ON voice_libraries(user_id)"))
+    conn.execute(sa.text("CREATE INDEX IF NOT EXISTS ix_voice_libraries_project_id ON voice_libraries(project_id)"))
+    conn.execute(sa.text("CREATE INDEX IF NOT EXISTS ix_voice_libraries_status ON voice_libraries(status)"))
 
 
 def downgrade() -> None:

alembic/versions/011_phase1_core_refactor.py

@@ -14,9 +14,11 @@ This migration:
    - edit_plan_clips (编辑计划片段)
 2. Removes edit_plan_id column from generation_tasks table
 """
-from alembic import op
+
 import sqlalchemy as sa
 
+from alembic import op
+
 # revision identifiers
 revision = "011"
 down_revision = "010"
@@ -39,9 +41,7 @@ def upgrade() -> None:
 
     # ── 2. Remove edit_plan_id from generation_tasks ──
 
-    conn.execute(sa.text(
-        "ALTER TABLE generation_tasks DROP COLUMN IF EXISTS edit_plan_id"
-    ))
+    conn.execute(sa.text("ALTER TABLE generation_tasks DROP COLUMN IF EXISTS edit_plan_id"))
 
 
 def downgrade() -> None:
@@ -49,9 +49,7 @@ def downgrade() -> None:
 
     # ── 1. Re-add edit_plan_id to generation_tasks ──
 
-    conn.execute(sa.text(
-        "ALTER TABLE generation_tasks ADD COLUMN IF NOT EXISTS edit_plan_id VARCHAR(32)"
-    ))
+    conn.execute(sa.text("ALTER TABLE generation_tasks ADD COLUMN IF NOT EXISTS edit_plan_id VARCHAR(32)"))
 
     # ── 2. Recreate deprecated tables (basic structure) ──
 

alembic/versions/012_add_duplication_tables.py

@@ -8,9 +8,11 @@ This migration creates two new tables:
 1. duplication_records — 查重记录主表
 2. duplication_segments — 重复片段详情表
 """
-from alembic import op
+
 import sqlalchemy as sa
 
+from alembic import op
+
 # revision identifiers
 revision = "012"
 down_revision = "011"
@@ -40,12 +42,8 @@ def upgrade() -> None:
             updated_at TIMESTAMP NOT NULL DEFAULT NOW()
         )
     """))
-    conn.execute(sa.text(
-        "CREATE INDEX IF NOT EXISTS ix_duplication_records_user_id ON duplication_records(user_id)"
-    ))
-    conn.execute(sa.text(
-        "CREATE INDEX IF NOT EXISTS ix_duplication_records_status ON duplication_records(status)"
-    ))
+    conn.execute(sa.text("CREATE INDEX IF NOT EXISTS ix_duplication_records_user_id ON duplication_records(user_id)"))
+    conn.execute(sa.text("CREATE INDEX IF NOT EXISTS ix_duplication_records_status ON duplication_records(status)"))
 
     # ── 2. Create duplication_segments table ──
 
@@ -62,9 +60,9 @@ def upgrade() -> None:
             similarity FLOAT NOT NULL
         )
     """))
-    conn.execute(sa.text(
-        "CREATE INDEX IF NOT EXISTS ix_duplication_segments_record_id ON duplication_segments(record_id)"
-    ))
+    conn.execute(
+        sa.text("CREATE INDEX IF NOT EXISTS ix_duplication_segments_record_id ON duplication_segments(record_id)")
+    )
 
 
 def downgrade() -> None:

alembic/versions/013_add_recipe_tables.py

@@ -0,0 +1,62 @@
+"""Phase 2 - 配方复用：recipes + recipe_items
+
+Revision ID: 013
+Revises: 012
+Create Date: 2026-06-29
+
+This migration creates two new tables:
+1. recipes — 配方主表
+2. recipe_items — 配方素材项表
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers
+revision = "013"
+down_revision = "012"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── 1. Create recipes table ──
+
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS recipes (
+            id VARCHAR(36) PRIMARY KEY,
+            user_id VARCHAR(36) NOT NULL,
+            name VARCHAR(200) NOT NULL,
+            description TEXT NOT NULL DEFAULT '',
+            template_id VARCHAR(36) NOT NULL DEFAULT '',
+            generation_params JSONB NOT NULL DEFAULT '{}',
+            is_active BOOLEAN NOT NULL DEFAULT TRUE,
+            metadata JSONB NOT NULL DEFAULT '{}',
+            created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+            updated_at TIMESTAMP NOT NULL DEFAULT NOW()
+        )
+    """))
+    conn.execute(sa.text("CREATE INDEX IF NOT EXISTS ix_recipes_user_id ON recipes(user_id)"))
+
+    # ── 2. Create recipe_items table ──
+
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS recipe_items (
+            id VARCHAR(36) PRIMARY KEY,
+            recipe_id VARCHAR(36) NOT NULL,
+            item_type VARCHAR(20) NOT NULL,
+            item_id VARCHAR(36) NOT NULL,
+            position INTEGER NOT NULL DEFAULT 0,
+            metadata JSONB NOT NULL DEFAULT '{}'
+        )
+    """))
+    conn.execute(sa.text("CREATE INDEX IF NOT EXISTS ix_recipe_items_recipe_id ON recipe_items(recipe_id)"))
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DROP TABLE IF EXISTS recipe_items"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS recipes"))

alembic/versions/014_add_template_tables.py

@@ -0,0 +1,83 @@
+"""Phase 3 - 剪辑计划模板：templates + template_segments + template_categories
+
+Revision ID: 014
+Revises: 013
+Create Date: 2026-06-29
+
+This migration creates three new tables:
+1. templates — 剪辑计划模板主表
+2. template_segments — 模板片段表
+3. template_categories — 模板分类表
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers
+revision = "014"
+down_revision = "013"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── 1. Create templates table ──
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS templates (
+            id VARCHAR(36) PRIMARY KEY,
+            user_id VARCHAR(36) NOT NULL,
+            name VARCHAR(200) NOT NULL,
+            mode VARCHAR(30) NOT NULL,
+            category VARCHAR(100) NOT NULL DEFAULT '',
+            tags JSONB NOT NULL DEFAULT '[]',
+            title_config JSONB NOT NULL DEFAULT '{}',
+            subtitle_config JSONB NOT NULL DEFAULT '{}',
+            bgm_config JSONB NOT NULL DEFAULT '{}',
+            estimated_duration FLOAT NOT NULL DEFAULT 0.0,
+            is_active BOOLEAN NOT NULL DEFAULT TRUE,
+            created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+            updated_at TIMESTAMP NOT NULL DEFAULT NOW()
+        )
+    """))
+    conn.execute(sa.text("CREATE INDEX IF NOT EXISTS ix_templates_user_id ON templates(user_id)"))
+    conn.execute(sa.text("CREATE INDEX IF NOT EXISTS ix_templates_mode ON templates(mode)"))
+
+    # ── 2. Create template_segments table ──
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS template_segments (
+            id VARCHAR(36) PRIMARY KEY,
+            template_id VARCHAR(36) NOT NULL,
+            segment_order INTEGER NOT NULL,
+            duration_min FLOAT NOT NULL,
+            duration_max FLOAT NOT NULL,
+            material_type VARCHAR(20),
+            created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+            updated_at TIMESTAMP NOT NULL DEFAULT NOW()
+        )
+    """))
+    conn.execute(
+        sa.text("CREATE INDEX IF NOT EXISTS ix_template_segments_template_id " "ON template_segments(template_id)")
+    )
+
+    # ── 3. Create template_categories table ──
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS template_categories (
+            id VARCHAR(36) PRIMARY KEY,
+            user_id VARCHAR(36) NOT NULL,
+            name VARCHAR(100) NOT NULL,
+            created_at TIMESTAMP NOT NULL DEFAULT NOW()
+        )
+    """))
+    conn.execute(
+        sa.text("CREATE INDEX IF NOT EXISTS ix_template_categories_user_id " "ON template_categories(user_id)")
+    )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DROP TABLE IF EXISTS template_categories"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS template_segments"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS templates"))

alembic/versions/015_add_generation_task_extensions.py

@@ -0,0 +1,34 @@
+"""add generation task extensions
+
+Revision ID: 015
+Revises: 014
+Create Date: 2026-06-29
+"""
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import mysql
+
+from alembic import op
+
+# revision identifiers
+revision = "015"
+down_revision = "014"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("generation_tasks", sa.Column("template_id", sa.String(36), nullable=False, server_default=""))
+    op.add_column("generation_tasks", sa.Column("asset_ids", mysql.JSON(), nullable=False, server_default="[]"))
+    op.add_column("generation_tasks", sa.Column("title_ids", mysql.JSON(), nullable=False, server_default="[]"))
+    op.add_column("generation_tasks", sa.Column("voice_ids", mysql.JSON(), nullable=False, server_default="[]"))
+
+    op.create_index(op.f("ix_generation_tasks_template_id"), "generation_tasks", ["template_id"])
+
+
+def downgrade() -> None:
+    op.drop_index(op.f("ix_generation_tasks_template_id"), table_name="generation_tasks")
+    op.drop_column("generation_tasks", "voice_ids")
+    op.drop_column("generation_tasks", "title_ids")
+    op.drop_column("generation_tasks", "asset_ids")
+    op.drop_column("generation_tasks", "template_id")

alembic/versions/016_phase8_edit_template_plan.py

@@ -0,0 +1,116 @@
+"""phase8 edit template plan
+
+Revision ID: 016
+Revises: 015
+Create Date: 2026-07-01
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "016"
+down_revision = "015"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # --- edit_templates: 替换为 Phase 8 新 schema ---
+    # 删除旧列
+    op.drop_column("edit_templates", "project_id")
+    op.drop_column("edit_templates", "target_duration")
+    op.drop_column("edit_templates", "clip_count")
+    op.drop_column("edit_templates", "is_active")
+    op.drop_column("edit_templates", "created_by_user_id")
+    op.drop_column("edit_templates", "metadata")
+
+    # 添加新列
+    op.add_column(
+        "edit_templates",
+        sa.Column("template_type", sa.String(50), nullable=False, server_default="default"),
+    )
+    op.add_column(
+        "edit_templates",
+        sa.Column("config", sa.JSON(), nullable=False, server_default="{}"),
+    )
+    op.add_column(
+        "edit_templates",
+        sa.Column("preview_url", sa.String(1000), nullable=False, server_default=""),
+    )
+    op.add_column(
+        "edit_templates",
+        sa.Column("sort_weight", sa.Integer(), nullable=False, server_default="0"),
+    )
+    op.add_column(
+        "edit_templates",
+        sa.Column("status", sa.String(20), nullable=False, server_default="active"),
+    )
+
+    # 添加索引
+    op.create_index("ix_edit_templates_template_type", "edit_templates", ["template_type"])
+    op.create_index("ix_edit_templates_sort_weight", "edit_templates", ["sort_weight"])
+    op.create_index("ix_edit_templates_status", "edit_templates", ["status"])
+
+    # --- edit_plans: 重建表（在 011 中被删除） ---
+    op.create_table(
+        "edit_plans",
+        sa.Column("id", sa.String(32), primary_key=True),
+        sa.Column("template_id", sa.String(32), nullable=False, index=True),
+        sa.Column("name", sa.String(200), nullable=False),
+        sa.Column("status", sa.String(20), nullable=False, server_default="draft", index=True),
+        sa.Column("total_duration", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("config", sa.JSON(), nullable=False, server_default="{}"),
+        sa.Column(
+            "created_at",
+            sa.DateTime(),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("edit_plans")
+
+    op.drop_index("ix_edit_templates_status", "edit_templates")
+    op.drop_index("ix_edit_templates_sort_weight", "edit_templates")
+    op.drop_index("ix_edit_templates_template_type", "edit_templates")
+
+    op.drop_column("edit_templates", "status")
+    op.drop_column("edit_templates", "sort_weight")
+    op.drop_column("edit_templates", "preview_url")
+    op.drop_column("edit_templates", "config")
+    op.drop_column("edit_templates", "template_type")
+
+    # 恢复旧列
+    op.add_column(
+        "edit_templates",
+        sa.Column("project_id", sa.String(32), nullable=False, server_default=""),
+    )
+    op.add_column(
+        "edit_templates",
+        sa.Column("target_duration", sa.Float(), nullable=False, server_default="30"),
+    )
+    op.add_column(
+        "edit_templates",
+        sa.Column("clip_count", sa.Integer(), nullable=False, server_default="3"),
+    )
+    op.add_column(
+        "edit_templates",
+        sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.true()),
+    )
+    op.add_column(
+        "edit_templates",
+        sa.Column("created_by_user_id", sa.String(32), nullable=False, server_default=""),
+    )
+    op.add_column(
+        "edit_templates",
+        sa.Column("metadata", sa.JSON(), nullable=False, server_default="{}"),
+    )

alembic/versions/017_phase8_clip_config_plan_clip.py

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

alembic/versions/018_add_jobs_table.py

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

alembic/versions/019_add_voice_clone_profiles_table.py

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

alembic/versions/020_add_tts_jobs_table.py

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

alembic/versions/021_add_billing_records_table.py

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

alembic/versions/022_add_source_edit_plan_id.py

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

alembic/versions/023_add_edit_plan_project_and_user.py

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

alembic/versions/024_add_user_is_admin.py

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

alembic/versions/025_add_user_wechat_fields.py

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

alembic/versions/026_add_user_profile_fields.py

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

alembic/versions/027_add_user_ban_fields.py

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

alembic/versions/028_add_user_admin_fields.py

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

alembic/versions/029_add_user_phone.py

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

alembic/versions/030_add_tags_and_asset_tags.py

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

alembic/versions/031_add_file_hash_to_assets_and_ing_jobs.py

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

alembic/versions/032_add_asset_select_mode_to_generation_tasks.py

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

alembic/versions/033_add_batch_id_to_generation_tasks.py

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

alembic/versions/034_cms_enhance_placeholder.py

@@ -0,0 +1,28 @@
+"""CMS Enhancements (placeholder - manually applied on production)
+
+Revision ID: 034_cms_enhance
+Revises: 033
+Create Date: 2026-07-09
+
+占位迁移文件：生产数据库已手动升级到此版本，
+此文件用于让 alembic 识别当前版本，避免部署时迁移失败。
+实际的表结构变更（helpcenter, tickets, partners, site_settings 等）
+已在生产环境手动执行。
+"""
+
+from alembic import op
+
+revision = "034_cms_enhance"
+down_revision = "033"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """占位 - 变更已在生产环境手动应用"""
+    pass
+
+
+def downgrade() -> None:
+    """占位 - 不执行实际回退"""
+    pass

alembic/versions/035_add_editing_mode_to_templates.py

@@ -0,0 +1,26 @@
+"""Add editing_mode to edit_templates
+
+Revision ID: 035_editing_mode
+Revises: 034_cms_enhance
+Create Date: 2026-07-09
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "035_editing_mode"
+down_revision = "034_cms_enhance"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "edit_templates",
+        sa.Column("editing_mode", sa.String(20), nullable=False, server_default="one_take"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("edit_templates", "editing_mode")

alembic/versions/036_expand_uuid_fields_to_36.py

@@ -0,0 +1,68 @@
+"""Expand UUID fields from varchar(32) to varchar(36)
+
+All UUID fields across all tables were varchar(32), but standard UUIDs with
+hyphens are 36 characters (e.g. 550e8400-e29b-41d4-a716-446655440000).
+This caused StringDataRightTruncation errors on insert.
+
+Revision ID: 036_expand_uuid_36
+Revises: 035_editing_mode
+Create Date: 2026-07-10
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "036_expand_uuid_36"
+down_revision = "035_editing_mode"
+branch_labels = None
+depends_on = None
+
+
+# ── 表 → 需要扩容的列 ─────────────────────────────────────────────────────────
+
+_TABLES: dict[str, list[str]] = {
+    "projects": ["id", "owner_user_id"],
+    "edit_templates": ["id"],
+    "edit_plans": ["id", "template_id", "source_edit_plan_id", "project_id", "created_by_user_id"],
+    "template_clip_configs": ["id", "template_id"],
+    "edit_plan_clips": ["id", "plan_id", "template_clip_config_id", "asset_id"],
+    "ingest_jobs": ["id", "project_id", "library_id", "result_asset_id"],
+    "classification_jobs": ["id", "project_id", "asset_id"],
+    "generation_tasks": [
+        "id",
+        "project_id",
+        "strategy_id",
+        "asset_library_id",
+        "voice_library_id",
+        "created_by_user_id",
+        "source_edit_plan_id",
+        "batch_id",
+    ],
+    "generated_videos": ["id", "project_id", "generation_task_id", "duplicate_of"],
+    "jobs": ["id", "project_id", "source_id", "created_by_user_id"],
+}
+
+
+def upgrade() -> None:
+    for table, columns in _TABLES.items():
+        for col in columns:
+            op.alter_column(
+                table,
+                col,
+                existing_type=sa.String(32),
+                type_=sa.String(36),
+                existing_nullable=None,
+            )
+
+
+def downgrade() -> None:
+    for table, columns in reversed(list(_TABLES.items())):
+        for col in columns:
+            op.alter_column(
+                table,
+                col,
+                existing_type=sa.String(36),
+                type_=sa.String(32),
+                existing_nullable=None,
+            )

alembic/versions/037_add_logs_to_generation_tasks.py

@@ -0,0 +1,26 @@
+"""Add logs field to generation_tasks
+
+Revision ID: 037_generation_logs
+Revises: 036_expand_uuid_36
+Create Date: 2026-07-10
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "037_generation_logs"
+down_revision = "036_expand_uuid_36"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "generation_tasks",
+        sa.Column("logs", sa.Text(), nullable=False, server_default="[]"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("generation_tasks", "logs")

alembic/versions/038_add_error_info_and_retry_to_generation_tasks.py

@@ -0,0 +1,47 @@
+"""add error_info and retry fields to generation_tasks
+
+Revision ID: 038_error_retry
+Revises: 037_generation_logs
+Create Date: 2026-07-13 22:15:00.000000
+"""
+
+import sqlalchemy as sa
+from sqlalchemy.dialects.mysql import JSON as MySQLJSON
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "038_error_retry"
+down_revision = "037_generation_logs"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # error_info: 结构化错误信息（error_type, message, stack_trace, failed_at, stage等）
+    op.add_column(
+        "generation_tasks",
+        sa.Column("error_info", sa.JSON(), nullable=True),
+    )
+    # retry_count: 重试次数
+    op.add_column(
+        "generation_tasks",
+        sa.Column("retry_count", sa.Integer(), nullable=False, server_default="0"),
+    )
+    # auto_retry_enabled: 是否开启自动重试
+    op.add_column(
+        "generation_tasks",
+        sa.Column("auto_retry_enabled", sa.Boolean(), nullable=False, server_default=sa.text("false")),
+    )
+    # auto_retry_max: 最大自动重试次数
+    op.add_column(
+        "generation_tasks",
+        sa.Column("auto_retry_max", sa.Integer(), nullable=False, server_default="0"),
+    )
+
+
+def downgrade():
+    op.drop_column("generation_tasks", "auto_retry_max")
+    op.drop_column("generation_tasks", "auto_retry_enabled")
+    op.drop_column("generation_tasks", "retry_count")
+    op.drop_column("generation_tasks", "error_info")

alembic/versions/039_add_transition_duration.py

@@ -0,0 +1,34 @@
+"""add transition_duration to edit_plan_clips
+
+Revision ID: 039_transition_duration
+Revises: 038_error_retry
+Create Date: 2026-07-14 09:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "039_transition_duration"
+down_revision = "038_error_retry"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "edit_plan_clips",
+        sa.Column(
+            "transition_duration",
+            sa.Float(),
+            nullable=False,
+            server_default="0.0",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("edit_plan_clips", "transition_duration")

alembic/versions/040_add_playback_speed_to_edit_plan_clips.py

@@ -0,0 +1,29 @@
+"""add playback_speed to edit_plan_clips
+
+Revision ID: 040_playback_speed
+Revises: 039_transition_duration
+Create Date: 2026-07-14 10:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "040_playback_speed"
+down_revision = "039_transition_duration"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "edit_plan_clips",
+        sa.Column("playback_speed", sa.Float(), nullable=False, server_default="1.0"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("edit_plan_clips", "playback_speed")

apps/api/app/__init__.py

@@ -1 +0,0 @@
-"""API application package."""

apps/api/app/api/__init__.py

@@ -1 +0,0 @@
-"""API package."""

apps/api/app/api/router.py

@@ -5,16 +5,23 @@ from app.api.routes.auth import router as auth_router
 from app.api.routes.chunked_upload import router as chunked_upload_router
 from app.api.routes.classification_jobs import router as classification_jobs_router
 from app.api.routes.duplication import router as duplication_router
-from app.api.routes.generated_videos import router as generated_videos_router
-from app.api.routes.subscription import router as subscription_router
-from app.api.routes.titles import router as titles_router
-from app.api.routes.voices import router as voices_router
+from app.api.routes.edit_plans import router as edit_plans_router
+from app.api.routes.feature_flags import router as feature_flags_router
 from app.api.routes.generation_tasks import router as generation_tasks_router
 from app.api.routes.health import router as health_check_router
 from app.api.routes.ingest_jobs import router as ingest_jobs_router
+from app.api.routes.internal_render import router as internal_render_router
 from app.api.routes.projects import router as projects_router
+from app.api.routes.subscription import router as subscription_router
+from app.api.routes.tags import router as tags_router
 from app.api.routes.task_center import router as task_center_router
+from app.api.routes.templates import router as templates_router
+from app.api.routes.titles import router as titles_router
+from app.api.routes.tts import router as tts_router
 from app.api.routes.upload import router as upload_router
+from app.api.routes.videos import router as videos_router
+from app.api.routes.voice_clones import router as voice_clones_router
+from app.api.routes.voices import router as voices_router
 from fastapi import APIRouter
 
 api_router = APIRouter(prefix="/api/v1")
@@ -30,6 +37,11 @@ api_router.include_router(
     prefix="/projects",
     tags=["Project"],
 )
+api_router.include_router(
+    tags_router,
+    prefix="/tags",
+    tags=["Tag"],
+)
 api_router.include_router(
     task_center_router,
     tags=["TaskCenter"],
@@ -73,11 +85,6 @@ api_router.include_router(
     prefix="/generation",
     tags=["Generation"],
 )
-api_router.include_router(
-    generated_videos_router,
-    prefix="/generated-videos",
-    tags=["GeneratedVideo"],
-)
 api_router.include_router(
     titles_router,
     prefix="/titles",
@@ -88,6 +95,15 @@ api_router.include_router(
     prefix="/voices",
     tags=["VoiceLibrary"],
 )
+api_router.include_router(
+    voice_clones_router,
+    prefix="/voice-clones",
+    tags=["VoiceClone"],
+)
+api_router.include_router(
+    videos_router,
+    tags=["VideoCenter"],
+)
 api_router.include_router(
     duplication_router,
     prefix="/duplication",
@@ -98,3 +114,26 @@ api_router.include_router(
     prefix="/subscription",
     tags=["Subscription"],
 )
+api_router.include_router(
+    templates_router,
+    prefix="/templates",
+    tags=["Template"],
+)
+api_router.include_router(
+    edit_plans_router,
+    prefix="/edit-plans",
+    tags=["EditPlan"],
+)
+api_router.include_router(
+    tts_router,
+    prefix="/tts",
+    tags=["TTS"],
+)
+api_router.include_router(
+    feature_flags_router,
+    tags=["Internal"],
+)
+api_router.include_router(
+    internal_render_router,
+    tags=["Internal"],
+)

apps/api/app/api/routes/_helpers.py

@@ -0,0 +1,48 @@
+"""路由层共享辅助函数 — 消除跨文件重复定义。"""
+
+from typing import Any
+
+from fastapi import HTTPException, status
+
+from packages.application import GetProjectUseCase
+from packages.ports.user_repository import UserRepository
+
+
+def check_project_access(project_id: str, user_id: str, project_repository) -> None:
+    """检查用户是否有项目访问权限。
+
+    合并自 asset_libraries.py / edit_plans.py 的同名函数。
+    - 空 project_id 直接放行（兼容 edit_plans 中 project_id 可选的场景）
+    - 错误信息使用中文，与项目其他路由保持一致
+    """
+    if not project_id or not project_id.strip():
+        return
+    project = project_repository.find_by_id(project_id)
+    if project is None:
+        raise HTTPException(status_code=404, detail="项目不存在")
+    if not project.can_access(user_id):
+        raise HTTPException(status_code=403, detail="无权访问该项目")
+
+
+def get_user_plan(user_id: str, user_repository: UserRepository) -> str:
+    """获取用户的订阅计划名称。"""
+    user = user_repository.find_by_id(user_id)
+    if user is None:
+        return "free"
+    return getattr(user, "subscription_plan", "free") or "free"
+
+
+def require_project_and_library(
+    project_id: str,
+    library_id: str,
+    project_repository: Any,
+    asset_library_repository: Any,
+) -> None:
+    """Verify project and asset library exist."""
+    project = GetProjectUseCase(project_repository).execute(project_id)
+    if project is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+
+    libraries = asset_library_repository.find_by_project(project_id)
+    if not any(item.id == library_id for item in libraries):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Asset library not found")

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

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

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

@@ -1,13 +1,18 @@
 from typing import Any
 
 from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_asset_library_repository, get_project_repository
+from app.dependencies import (
+    get_asset_library_repository,
+    get_asset_repository,
+    get_project_repository,
+)
 from app.schemas.asset_library import (
     AssetLibraryResponse,
     CreateAssetLibraryRequest,
+    EnsureDefaultLibraryRequest,
     ListAssetLibrariesResponse,
 )
-from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
 
 from packages.application import (
     CreateAssetLibraryCommand,
@@ -15,20 +20,13 @@ from packages.application import (
     GetProjectUseCase,
     ListAssetLibrariesUseCase,
 )
-from packages.domain import AssetLibraryKind
+from packages.domain import AssetLibrary, AssetLibraryKind
+
+from ._helpers import check_project_access
 
 router = APIRouter()
 
 
-def _check_project_access(project_id: str, user_id: str, project_repository) -> None:
-    """检查用户是否有项目访问权限"""
-    project = project_repository.find_by_id(project_id)
-    if project is None:
-        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
-    if not project.can_access(user_id):
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied to project")
-
-
 def _to_asset_library_response(item) -> AssetLibraryResponse:
     return AssetLibraryResponse(
         id=item.id,
@@ -43,13 +41,14 @@ def _to_asset_library_response(item) -> AssetLibraryResponse:
 @router.get("", response_model=ListAssetLibrariesResponse)
 def list_asset_libraries(
     project_id: str | None = Query(None),
+    kind: str | None = Query(None, pattern="^(video|voice|image)$"),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     asset_library_repository: Any = Depends(get_asset_library_repository),
     project_repository: Any = Depends(get_project_repository),
 ) -> ListAssetLibrariesResponse:
     user_id = authenticated_user.user.id
     use_case = ListAssetLibrariesUseCase(asset_library_repository)
-    
+
     if project_id:
         # If project_id provided, check access and filter by project
         project = GetProjectUseCase(project_repository).execute(project_id)
@@ -65,7 +64,12 @@ def list_asset_libraries(
         for proj in accessible_projects:
             all_items.extend(use_case.execute(proj.id))
         items = all_items
-    
+
+    # 按 kind 过滤（可选）
+    if kind:
+        kind_enum = AssetLibraryKind(kind)
+        items = [item for item in items if item.kind == kind_enum]
+
     return ListAssetLibrariesResponse(items=[_to_asset_library_response(item) for item in items])
 
 
@@ -90,3 +94,79 @@ def create_asset_library(
         )
     )
     return _to_asset_library_response(item)
+
+
+# 默认素材库名称映射
+_DEFAULT_LIBRARY_NAMES = {
+    "video": "视频素材库",
+    "voice": "配音素材库",
+    "image": "图片素材库",
+}
+
+
+@router.post("/ensure-default", response_model=AssetLibraryResponse)
+def ensure_default_library(
+    request: EnsureDefaultLibraryRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_library_repository: Any = Depends(get_asset_library_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> AssetLibraryResponse:
+    """确保项目下指定 kind 的默认素材库存在，已存在则直接返回，不存在则自动创建。"""
+    project = project_repository.find_by_id(request.project_id)
+    if project is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+    if not project.can_access(authenticated_user.user.id):
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied to project")
+
+    kind = AssetLibraryKind(request.kind)
+
+    # 查找该项目下同 kind 的素材库，返回第一个
+    existing = asset_library_repository.find_by_project(request.project_id)
+    for lib in existing:
+        if lib.kind == kind:
+            return _to_asset_library_response(lib)
+
+    # 不存在 → 自动创建
+    import uuid
+    from datetime import datetime, timezone
+
+    now = datetime.now(timezone.utc)
+    default_name = _DEFAULT_LIBRARY_NAMES.get(request.kind, f"{request.kind}素材库")
+    library = AssetLibrary(
+        id=str(uuid.uuid4()),
+        project_id=request.project_id,
+        name=default_name,
+        kind=kind,
+        asset_count=0,
+        total_size=0,
+        created_at=now,
+        updated_at=now,
+    )
+    created = asset_library_repository.create(library)
+    return _to_asset_library_response(created)
+
+
+@router.delete("/{library_id}", status_code=status.HTTP_204_NO_CONTENT, response_class=Response)
+def delete_asset_library(
+    library_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_library_repository: Any = Depends(get_asset_library_repository),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> None:
+    """删除素材库，同时删除库内所有素材。"""
+    # 查找素材库
+    library = asset_library_repository.find_by_id(library_id)
+    if library is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="素材库不存在")
+
+    # 权限校验：检查用户是否有项目访问权限
+    check_project_access(library.project_id, authenticated_user.user.id, project_repository)
+
+    # 删除库内所有素材（硬删除，素材库已删除，无需保留软删除状态）
+    assets_in_library = asset_repository.find_by_library(library_id)
+    for asset in assets_in_library:
+        asset_repository.delete(asset.id)
+
+    # 删除素材库本身
+    asset_library_repository.delete(library_id)

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

@@ -1,25 +1,57 @@
-from typing import Any
+import logging
+from typing import Any, Optional
 
+from app.api.routes._helpers import check_project_access
 from app.auth import AuthenticatedUser, get_current_user
+from app.core.storage import get_storage_service
 from app.dependencies import (
     get_asset_library_repository,
     get_asset_repository,
     get_project_repository,
+    get_tag_repository,
 )
-from app.schemas.asset import AssetResponse, CreateAssetRequest, ListAssetsResponse, UpdateAssetReviewRequest
-from fastapi import APIRouter, Depends, HTTPException
+from app.schemas.asset import (
+    AssetResponse,
+    BatchClassifyRequest,
+    BatchDeleteRequest,
+    BatchMarkRequest,
+    BatchOperationResponse,
+    BatchTagRequest,
+    CreateAssetRequest,
+    ListAssetsResponse,
+    UpdateAssetRequest,
+    UpdateAssetReviewRequest,
+)
+from app.schemas.tag import TagAssetsRequest
+from fastapi import APIRouter, Depends, HTTPException, Query, Response
 
 from packages.application import (
     CreateAssetCommand,
     CreateAssetUseCase,
-    ListAssetsUseCase,
 )
 from packages.domain import AssetStatus, ClassificationStatus
 
+logger = logging.getLogger(__name__)
+
 router = APIRouter()
 
 
-def _to_asset_response(item) -> AssetResponse:
+def _to_asset_response(item, storage_service=None) -> AssetResponse:
+    # 生成签名文件 URL（用于视频播放 / 文件下载）
+    file_url = None
+    if item.storage_key:
+        try:
+            svc = storage_service or get_storage_service()
+            file_url = svc.get_download_url(item.storage_key)
+        except Exception:
+            logger.warning("生成签名URL失败: storage_key=%s", item.storage_key, exc_info=True)
+            file_url = None
+
+    # 缩略图：优先用已有 thumbnail_url，否则对视频素材复用文件签名 URL
+    thumbnail_url = item.thumbnail_url
+    if not thumbnail_url and item.mime_type and item.mime_type.startswith("video") and file_url:
+        thumbnail_url = file_url
+
     return AssetResponse(
         id=item.id,
         project_id=item.project_id,
@@ -29,7 +61,8 @@ def _to_asset_response(item) -> AssetResponse:
         mime_type=item.mime_type,
         metadata=item.metadata,
         file_size=item.file_size,
-        thumbnail_url=item.thumbnail_url,
+        file_url=file_url,
+        thumbnail_url=thumbnail_url,
         duration=item.duration,
         width=item.width,
         height=item.height,
@@ -39,33 +72,208 @@ def _to_asset_response(item) -> AssetResponse:
         classification_status=item.classification_status.value,
         quality_score=item.quality_score,
         uploaded_by_user_id=item.uploaded_by_user_id,
+        tag_ids=getattr(item, "tag_ids", []),
     )
 
 
-def _check_project_access(project_id: str, user_id: str, project_repository) -> None:
-    """检查用户是否有项目访问权限"""
-    project = project_repository.find_by_id(project_id)
-    if project is None:
-        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
-    if not project.can_access(user_id):
-        raise HTTPException(status_code=403, detail="Access denied to project")
-
-
 @router.get("", response_model=ListAssetsResponse)
 def list_assets(
-    library_id: str,
+    library_id: Optional[str] = Query(None),
+    project_id: Optional[str] = Query(None),
+    kind: Optional[str] = Query(None, pattern="^(video|voice|image)$"),
+    keyword: Optional[str] = Query(None, description="按名称模糊匹配"),
+    gender: Optional[str] = Query(None, description="按 metadata.gender 筛选"),
+    style: Optional[str] = Query(None, description="按 metadata.style 筛选"),
+    tag_ids: Optional[str] = Query(None, description="按标签 ID 筛选（逗号分隔，取交集）"),
+    smart_view: Optional[str] = Query(
+        None,
+        description="智能视图筛选：recommended=推荐(质量分≥80)、cautious=慎用(60-79)、risky=高风险(<60或已驳回)、unused=未使用、used=已使用、pending_review=待复核",
+        pattern="^(recommended|cautious|risky|unused|used|pending_review)$",
+    ),
+    classification: Optional[str] = Query(
+        None,
+        description="按内容分类筛选：scenic=风景、product=产品、person=人物、animal=动物、food=美食、tech=科技、sport=运动、music=音乐、other=其他",
+    ),
+    skip: int = Query(0, ge=0),
+    limit: int = Query(100, ge=1, le=500),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     asset_repository: Any = Depends(get_asset_repository),
     asset_library_repository: Any = Depends(get_asset_library_repository),
     project_repository: Any = Depends(get_project_repository),
 ) -> ListAssetsResponse:
-    library = asset_library_repository.get(library_id)
-    if library is None:
-        raise HTTPException(status_code=404, detail=f"AssetLibrary {library_id} not found")
-    _check_project_access(library.project_id, authenticated_user.user.id, project_repository)
-    use_case = ListAssetsUseCase(asset_repository)
-    items = use_case.execute(library_id)
-    return ListAssetsResponse(items=[_to_asset_response(item) for item in items])
+    user_id = authenticated_user.user.id
+
+    # kind → file_type 映射（voice 对应 audio）
+    kind_to_file_type = {"video": "video", "voice": "audio", "image": "image"}
+
+    # 解析 tag_ids 参数（逗号分隔）
+    filter_tag_ids: list[str] | None = None
+    if tag_ids:
+        filter_tag_ids = [t.strip() for t in tag_ids.split(",") if t.strip()]
+        if not filter_tag_ids:
+            filter_tag_ids = None
+
+    # 需要内存过滤的标志（keyword/gender/style/tag_ids/smart_view/classification 无法在 DB 层过滤）
+    needs_memory_filter = bool(keyword or gender or style or filter_tag_ids or smart_view or classification)
+
+    def _apply_memory_filters(items):
+        """应用 keyword / gender / style / tag_ids / smart_view / classification 内存过滤。"""
+        result = items
+        if keyword:
+            kw = keyword.lower()
+            result = [i for i in result if kw in (i.name or "").lower()]
+        if gender:
+            result = [i for i in result if (i.metadata or {}).get("gender") == gender]
+        if style:
+            result = [i for i in result if (i.metadata or {}).get("style") == style]
+        if classification:
+            result = [i for i in result if (i.metadata or {}).get("classification") == classification]
+        if filter_tag_ids:
+            tag_set = set(filter_tag_ids)
+            result = [i for i in result if tag_set.issubset(set(getattr(i, "tag_ids", [])))]
+        if smart_view:
+
+            def __meta(a):
+                return a.metadata or {}
+
+            def __use_count(a):
+                return int(__meta(a).get("generation_use_count") or 0)
+
+            def __review_status(a):
+                return __meta(a).get("review_status", "")
+
+            if smart_view == "recommended":
+                result = [i for i in result if i.quality_score is not None and i.quality_score >= 80]
+            elif smart_view == "cautious":
+                result = [i for i in result if i.quality_score is not None and 60 <= i.quality_score < 80]
+            elif smart_view == "risky":
+                result = [
+                    i
+                    for i in result
+                    if (i.quality_score is not None and i.quality_score < 60) or __review_status(i) == "rejected"
+                ]
+            elif smart_view == "unused":
+                result = [i for i in result if __use_count(i) == 0]
+            elif smart_view == "used":
+                result = [i for i in result if __use_count(i) > 0]
+            elif smart_view == "pending_review":
+                result = [i for i in result if __review_status(i) == "pending_review"]
+        return result
+
+    # ── 优化路径：无内存过滤时，使用 DB 级分页 ──
+    if not needs_memory_filter:
+        ft = kind_to_file_type.get(kind) if kind else None
+
+        # 模式1：指定 library_id
+        if library_id:
+            library = asset_library_repository.get(library_id)
+            if library is None:
+                raise HTTPException(status_code=404, detail=f"AssetLibrary {library_id} not found")
+            check_project_access(library.project_id, user_id, project_repository)
+            if ft:
+                items = asset_repository.find_by_library_and_file_type(library_id, ft, skip=skip, limit=limit)
+                total = asset_repository.count_by_project(library.project_id) if not kind else len(items)
+            else:
+                items = asset_repository.find_by_library(library_id, skip=skip, limit=limit)
+                total = asset_repository.count_by_project(library.project_id)
+            return ListAssetsResponse(
+                items=[_to_asset_response(item) for item in items],
+                total=total,
+                skip=skip,
+                limit=limit,
+            )
+
+        # 模式2：指定 project_id
+        if project_id:
+            check_project_access(project_id, user_id, project_repository)
+            if ft:
+                # 无直接方法，加载后按 file_type 过滤（仍比全量加载好）
+                all_items = asset_repository.find_by_project(project_id)
+                items = [i for i in all_items if i.mime_type and i.mime_type.startswith(ft)]
+                total = len(items)
+                paged = items[skip : skip + limit]
+            else:
+                items = asset_repository.find_by_project(project_id, skip=skip, limit=limit)
+                total = asset_repository.count_by_project(project_id)
+                paged = items
+            return ListAssetsResponse(
+                items=[_to_asset_response(item) for item in paged],
+                total=total,
+                skip=skip,
+                limit=limit,
+            )
+
+        # 模式3：跨项目（无 library_id/project_id）
+        try:
+            projects = project_repository.find_accessible_projects(user_id)
+        except Exception:
+            logger.exception("查询用户可访问项目失败: user_id=%s", user_id)
+            return ListAssetsResponse(items=[], total=0, skip=skip, limit=limit)
+
+        project_ids = [p.id for p in projects]
+        if not project_ids:
+            return ListAssetsResponse(items=[], total=0, skip=skip, limit=limit)
+
+        total = asset_repository.count_by_project_ids(project_ids)
+        # 跨项目分页：逐项目累积直到凑够一页
+        paged_items: list = []
+        offset = skip
+        remaining = limit
+        for pid in project_ids:
+            proj_total = asset_repository.count_by_project(pid)
+            if offset >= proj_total:
+                offset -= proj_total
+                continue
+            proj_items = asset_repository.find_by_project(pid, skip=offset, limit=remaining)
+            paged_items.extend(proj_items)
+            remaining -= len(proj_items)
+            offset = 0
+            if remaining <= 0:
+                break
+
+        return ListAssetsResponse(
+            items=[_to_asset_response(item) for item in paged_items],
+            total=total,
+            skip=skip,
+            limit=limit,
+        )
+
+    # ── 内存过滤路径：有 keyword/gender/style 时，加载全量后内存过滤 ──
+    if library_id:
+        library = asset_library_repository.get(library_id)
+        if library is None:
+            raise HTTPException(status_code=404, detail=f"AssetLibrary {library_id} not found")
+        check_project_access(library.project_id, user_id, project_repository)
+        if kind:
+            all_items = asset_repository.find_by_library_and_file_type(library_id, kind_to_file_type[kind])
+        else:
+            all_items = asset_repository.find_by_library(library_id)
+    elif project_id:
+        check_project_access(project_id, user_id, project_repository)
+        all_items = asset_repository.find_by_project(project_id)
+    else:
+        try:
+            projects = project_repository.find_accessible_projects(user_id)
+        except Exception:
+            logger.exception("查询用户可访问项目失败: user_id=%s", user_id)
+            return ListAssetsResponse(items=[], total=0, skip=skip, limit=limit)
+        all_items = []
+        for proj in projects:
+            all_items.extend(asset_repository.find_by_project(proj.id))
+
+    # 应用 kind 过滤（如果有）+ keyword/gender/style
+    if kind:
+        ft = kind_to_file_type.get(kind)
+        all_items = [i for i in all_items if i.mime_type and i.mime_type.startswith(ft or "")]
+    filtered = _apply_memory_filters(all_items)
+    total = len(filtered)
+    paged = filtered[skip : skip + limit]
+    return ListAssetsResponse(
+        items=[_to_asset_response(item) for item in paged],
+        total=total,
+        skip=skip,
+        limit=limit,
+    )
 
 
 def _apply_asset_review_status(item, review_status: str):
@@ -87,12 +295,260 @@ def update_asset_review_status(
     item = asset_repository.get(asset_id)
     if item is None:
         raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
-    _check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
     _apply_asset_review_status(item, request.review_status)
     updated = asset_repository.update(item)
     return _to_asset_response(updated)
 
 
+@router.post("/batch-delete", response_model=BatchOperationResponse)
+def batch_delete_assets(
+    request: BatchDeleteRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> BatchOperationResponse:
+    """批量删除素材（软删除，标记 status=deleted），需逐项校验项目权限。"""
+    user_id = authenticated_user.user.id
+    success_ids: list[str] = []
+    failed_details: dict[str, str] = {}
+
+    for asset_id in request.asset_ids:
+        item = asset_repository.find_by_id(asset_id)
+        if item is None:
+            failed_details[asset_id] = "not_found"
+            continue
+        try:
+            check_project_access(item.project_id, user_id, project_repository)
+            success_ids.append(asset_id)
+        except HTTPException:
+            failed_details[asset_id] = "access_denied"
+
+    if success_ids:
+        asset_repository.batch_delete(success_ids)
+
+    return BatchOperationResponse(
+        success_count=len(success_ids),
+        failed_ids=list(failed_details.keys()),
+        failed_details=failed_details,
+    )
+
+
+@router.post("/batch-tag", response_model=BatchOperationResponse)
+def batch_tag_assets(
+    request: BatchTagRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+    tag_repository: Any = Depends(get_tag_repository),
+) -> BatchOperationResponse:
+    """批量打标签（添加或替换模式），需逐项校验项目权限和标签权限。"""
+    user_id = authenticated_user.user.id
+    success_ids: list[str] = []
+    failed_details: dict[str, str] = {}
+
+    # 校验标签存在且属于当前用户
+    for tag_id in request.tag_ids:
+        tag = tag_repository.get(tag_id)
+        if tag is None:
+            return BatchOperationResponse(
+                success_count=0,
+                failed_ids=list(request.asset_ids),
+                failed_details={aid: f"tag_not_found:{tag_id}" for aid in request.asset_ids},
+            )
+        if tag.user_id != user_id:
+            return BatchOperationResponse(
+                success_count=0,
+                failed_ids=list(request.asset_ids),
+                failed_details={aid: f"tag_access_denied:{tag_id}" for aid in request.asset_ids},
+            )
+
+    # 校验素材权限
+    for asset_id in request.asset_ids:
+        item = asset_repository.find_by_id(asset_id)
+        if item is None:
+            failed_details[asset_id] = "not_found"
+            continue
+        try:
+            check_project_access(item.project_id, user_id, project_repository)
+            success_ids.append(asset_id)
+        except HTTPException:
+            failed_details[asset_id] = "access_denied"
+
+    if success_ids:
+        if request.mode == "replace":
+            asset_repository.batch_replace_tags(success_ids, request.tag_ids)
+        else:
+            asset_repository.batch_add_tags(success_ids, request.tag_ids)
+
+    return BatchOperationResponse(
+        success_count=len(success_ids),
+        failed_ids=list(failed_details.keys()),
+        failed_details=failed_details,
+    )
+
+
+@router.post("/batch-classify", response_model=BatchOperationResponse)
+def batch_classify_assets(
+    request: BatchClassifyRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> BatchOperationResponse:
+    """批量修改素材内容分类（person/scenic/product等），存在metadata.category中。"""
+    user_id = authenticated_user.user.id
+    success_ids: list[str] = []
+    failed_details: dict[str, str] = {}
+
+    for asset_id in request.asset_ids:
+        item = asset_repository.find_by_id(asset_id)
+        if item is None:
+            failed_details[asset_id] = "not_found"
+            continue
+        try:
+            check_project_access(item.project_id, user_id, project_repository)
+            success_ids.append(asset_id)
+        except HTTPException:
+            failed_details[asset_id] = "access_denied"
+
+    if success_ids:
+        asset_repository.batch_update_metadata(success_ids, {"category": request.category})
+
+    return BatchOperationResponse(
+        success_count=len(success_ids),
+        failed_ids=list(failed_details.keys()),
+        failed_details=failed_details,
+    )
+
+
+@router.post("/batch-mark", response_model=BatchOperationResponse)
+def batch_mark_assets(
+    request: BatchMarkRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> BatchOperationResponse:
+    """批量设置智能视图标记（recommended/caution/high_risk），存在metadata.smart_view中。"""
+    user_id = authenticated_user.user.id
+    success_ids: list[str] = []
+    failed_details: dict[str, str] = {}
+
+    for asset_id in request.asset_ids:
+        item = asset_repository.find_by_id(asset_id)
+        if item is None:
+            failed_details[asset_id] = "not_found"
+            continue
+        try:
+            check_project_access(item.project_id, user_id, project_repository)
+            success_ids.append(asset_id)
+        except HTTPException:
+            failed_details[asset_id] = "access_denied"
+
+    if success_ids:
+        asset_repository.batch_update_metadata(success_ids, {"smart_view": request.smart_view})
+
+    return BatchOperationResponse(
+        success_count=len(success_ids),
+        failed_ids=list(failed_details.keys()),
+        failed_details=failed_details,
+    )
+
+
+@router.get("/{asset_id}", response_model=AssetResponse)
+def get_asset(
+    asset_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> AssetResponse:
+    item = asset_repository.find_by_id(asset_id)
+    if item is None:
+        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
+    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    return _to_asset_response(item)
+
+
+@router.put("/{asset_id}", response_model=AssetResponse)
+def update_asset(
+    asset_id: str,
+    request: UpdateAssetRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> AssetResponse:
+    item = asset_repository.find_by_id(asset_id)
+    if item is None:
+        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
+    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+
+    # 合并可修改字段
+    if request.name is not None:
+        item.name = request.name
+    if request.metadata is not None:
+        item.metadata = {**item.metadata, **request.metadata}
+    if request.tags is not None:
+        item.metadata = {**item.metadata, "tags": request.tags}
+
+    updated = asset_repository.update(item)
+    return _to_asset_response(updated)
+
+
+@router.delete("/{asset_id}", status_code=204, response_class=Response)
+def delete_asset(
+    asset_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> None:
+    item = asset_repository.find_by_id(asset_id)
+    if item is None:
+        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
+    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    asset_repository.delete(asset_id)
+
+
+@router.post("/{asset_id}/tags", response_model=AssetResponse)
+def tag_asset(
+    asset_id: str,
+    request: TagAssetsRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+    tag_repository: Any = Depends(get_tag_repository),
+) -> AssetResponse:
+    """给素材打标签。"""
+    item = asset_repository.find_by_id(asset_id)
+    if item is None:
+        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
+    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    for tag_id in request.tag_ids:
+        tag = tag_repository.get(tag_id)
+        if tag is None:
+            raise HTTPException(status_code=404, detail=f"Tag {tag_id} not found")
+        if tag.user_id != authenticated_user.user.id:
+            raise HTTPException(status_code=403, detail=f"无权使用标签 {tag_id}")
+        item.add_tag(tag_id)
+    updated = asset_repository.update(item)
+    return _to_asset_response(updated)
+
+
+@router.delete("/{asset_id}/tags/{tag_id}", status_code=204, response_class=Response)
+def untag_asset(
+    asset_id: str,
+    tag_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    asset_repository: Any = Depends(get_asset_repository),
+    project_repository: Any = Depends(get_project_repository),
+) -> None:
+    """取消素材的标签。"""
+    item = asset_repository.find_by_id(asset_id)
+    if item is None:
+        raise HTTPException(status_code=404, detail=f"Asset {asset_id} not found")
+    check_project_access(item.project_id, authenticated_user.user.id, project_repository)
+    item.remove_tag(tag_id)
+    asset_repository.update(item)
+
+
 @router.post("", response_model=AssetResponse)
 def create_asset(
     request: CreateAssetRequest,
@@ -106,7 +562,7 @@ def create_asset(
         raise HTTPException(status_code=404, detail=f"Project {request.project_id} not found")
     if not project.can_access(authenticated_user.user.id):
         raise HTTPException(status_code=403, detail="Access denied to project")
-    
+
     library = asset_library_repository.get(request.library_id)
     if library is None or library.project_id != request.project_id:
         raise HTTPException(status_code=404, detail=f"AssetLibrary {request.library_id} not found")

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

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

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

@@ -6,19 +6,20 @@ Supports chunked upload, resume, and automatic cleanup of expired uploads.
 import fcntl
 import json
 import logging
-import os
 import shutil
+import tempfile
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any
 from uuid import uuid4
 
+from app.api.routes._helpers import require_project_and_library
 from app.auth import AuthenticatedUser, get_current_user
-from app.config import get_settings
 from app.core.celery_app import celery_app
 from app.core.storage import OSSStorageService, get_storage_service
 from app.dependencies import (
     get_asset_library_repository,
+    get_asset_repository,
     get_ingest_job_repository,
     get_project_repository,
 )
@@ -42,15 +43,37 @@ DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024  # 5MB
 MAX_FILE_SIZE = 2 * 1024 * 1024 * 1024  # 2GB
 CHUNK_EXPIRY_HOURS = 24
 
-# Allowed file types (consistent with existing upload.py)
+# Allowed file types — must stay in sync with upload.py ALLOWED_MIME_TYPES
 ALLOWED_MIME_TYPES = {
-    "image/jpeg", "image/png", "image/gif", "image/webp",
-    "video/mp4", "video/quicktime", "video/x-msvideo", "video/webm",
-    "audio/mpeg", "audio/wav", "audio/ogg", "audio/mp3",
+    # Images
+    "image/jpeg",
+    "image/png",
+    "image/gif",
+    "image/webp",
+    "image/bmp",
+    "image/tiff",
+    "image/svg+xml",
+    # Video
+    "video/mp4",
+    "video/quicktime",
+    "video/mpeg",
+    "video/x-msvideo",
+    "video/webm",
+    "video/x-matroska",
+    "video/3gpp",
+    # Audio
+    "audio/mpeg",
+    "audio/wav",
+    "audio/ogg",
+    "audio/mp3",
+    "audio/flac",
+    "audio/aac",
+    "audio/x-m4a",
+    "audio/webm",
 }
 
 # Chunk storage root directory
-CHUNK_STORAGE_ROOT = Path("/tmp/chunked_uploads")
+CHUNK_STORAGE_ROOT = Path(tempfile.gettempdir()) / "chunked_uploads"
 
 
 def _get_chunk_dir(upload_id: str) -> Path:
@@ -67,13 +90,13 @@ def _atomic_check_and_record(upload_id: str, chunk_index: int) -> bool:
     """
     Atomically check if chunk is uploaded and record if not.
     Uses file locking to prevent race conditions.
-    
+
     Returns:
         True if chunk was newly recorded, False if already exists
     """
     meta_path = _get_upload_meta_path(upload_id)
     CHUNK_STORAGE_ROOT.mkdir(parents=True, exist_ok=True)
-    
+
     with open(meta_path, "r+", encoding="utf-8") as f:
         fcntl.flock(f.fileno(), fcntl.LOCK_EX)
         try:
@@ -90,22 +113,6 @@ def _atomic_check_and_record(upload_id: str, chunk_index: int) -> bool:
             fcntl.flock(f.fileno(), fcntl.LOCK_UN)
 
 
-def _require_project_and_library(
-    project_id: str,
-    library_id: str,
-    project_repository: Any,
-    asset_library_repository: Any,
-) -> None:
-    """Verify project and asset library exist"""
-    project = GetProjectUseCase(project_repository).execute(project_id)
-    if project is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
-
-    libraries = asset_library_repository.list_by_project(project_id)
-    if not any(item.id == library_id for item in libraries):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Asset library not found")
-
-
 def _load_upload_meta(upload_id: str) -> dict[str, Any]:
     """Load upload metadata"""
     meta_path = _get_upload_meta_path(upload_id)
@@ -128,15 +135,17 @@ def _validate_file_type(content: bytes, filename: str) -> str:
     """Validate file type"""
     try:
         import magic
+
         detected_mime = magic.from_buffer(content, mime=True)
     except ImportError:
         import mimetypes
+
         detected_mime = mimetypes.guess_type(filename)[0] or "application/octet-stream"
 
     if detected_mime not in ALLOWED_MIME_TYPES:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"Unsupported file type: {detected_mime}. Allowed types: {', '.join(sorted(ALLOWED_MIME_TYPES))}"
+            detail=f"Unsupported file type: {detected_mime}. Allowed types: {', '.join(sorted(ALLOWED_MIME_TYPES))}",
         )
     return detected_mime
 
@@ -181,7 +190,6 @@ async def init_chunked_upload(
     asset_library_repository: Any = Depends(get_asset_library_repository),
 ) -> ChunkedUploadInitResponse:
     """Initialize chunked upload"""
-    settings = get_settings()
 
     # Validate file size
     if request.file_size > MAX_FILE_SIZE:
@@ -196,7 +204,7 @@ async def init_chunked_upload(
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
 
     # Verify asset library
-    _require_project_and_library(
+    require_project_and_library(
         request.project_id,
         request.library_id,
         project_repository,
@@ -249,6 +257,154 @@ async def init_chunked_upload(
     )
 
 
+@router.get("/{upload_id}/status", response_model=ChunkedUploadStatusResponse)
+async def get_upload_status(
+    upload_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+) -> ChunkedUploadStatusResponse:
+    """Get upload status (for resume)"""
+    meta = _load_upload_meta(upload_id)
+
+    return ChunkedUploadStatusResponse(
+        upload_id=upload_id,
+        filename=meta["filename"],
+        file_size=meta["file_size"],
+        total_chunks=meta["total_chunks"],
+        uploaded_chunks=sorted(meta["uploaded_chunks"]),
+        status=meta["status"],
+        created_at=datetime.fromisoformat(meta["created_at"]),
+        expires_at=datetime.fromisoformat(meta["expires_at"]),
+    )
+
+
+@router.post("/{upload_id}/complete", response_model=ChunkedUploadCompleteResponse)
+async def complete_chunked_upload(
+    upload_id: str,
+    request: ChunkedUploadCompleteRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+    asset_library_repository: Any = Depends(get_asset_library_repository),
+    asset_repository: Any = Depends(get_asset_repository),
+    ingest_job_repository: Any = Depends(get_ingest_job_repository),
+    storage_service: OSSStorageService = Depends(get_storage_service),
+) -> ChunkedUploadCompleteResponse:
+    """Complete chunked upload, merge chunks"""
+    # Load metadata
+    meta = _load_upload_meta(upload_id)
+
+    # Verify project ID and library ID
+    if request.project_id != meta["project_id"] or request.library_id != meta["library_id"]:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Project or library ID mismatch")
+
+    # Verify all chunks are uploaded
+    expected_chunks = set(range(meta["total_chunks"]))
+    uploaded_chunks = set(meta["uploaded_chunks"])
+    missing_chunks = expected_chunks - uploaded_chunks
+
+    if missing_chunks:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Missing chunks: {sorted(missing_chunks)}. Please upload remaining chunks first.",
+        )
+
+    # Validate file type
+    chunk_dir = _get_chunk_dir(upload_id)
+    sample_chunk_path = chunk_dir / "chunk_000000"
+    if sample_chunk_path.exists():
+        with open(sample_chunk_path, "rb") as f:
+            sample_data = f.read(8192)  # Read first 8KB for type detection
+        detected_mime = _validate_file_type(sample_data, meta["filename"])
+        if detected_mime not in ALLOWED_MIME_TYPES:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Unsupported file type: {detected_mime}",
+            )
+
+    # Merge chunks to temp file
+    temp_file_path = CHUNK_STORAGE_ROOT / f"{upload_id}_complete.tmp"
+    try:
+        with open(temp_file_path, "wb") as out_file:
+            for i in range(meta["total_chunks"]):
+                chunk_path = chunk_dir / f"chunk_{i:06d}"
+                with open(chunk_path, "rb") as in_file:
+                    shutil.copyfileobj(in_file, out_file)
+
+        # Verify file size
+        actual_size = temp_file_path.stat().st_size
+        if actual_size != meta["file_size"]:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"File size mismatch. Expected {meta['file_size']}, got {actual_size}",
+            )
+
+        # Upload to OSS
+        file_id = uuid4().hex[:8]
+        safe_filename = meta["filename"]
+        storage_key = f"uploads/{file_id}/{safe_filename}"
+
+        file_url = storage_service.upload_file(
+            str(temp_file_path),
+            storage_key,
+            content_type=meta["content_type"],
+        )
+
+        # ── 素材去重检测：同素材库 + 同 file_hash 视为重复 ──
+        if request.file_hash:
+            existing = asset_repository.find_by_library_and_file_hash(
+                library_id=request.library_id,
+                file_hash=request.file_hash,
+            )
+            if existing is not None:
+                logger.info(
+                    "素材去重命中(chunked): library=%s hash=%s existing_asset=%s",
+                    request.library_id,
+                    request.file_hash,
+                    existing.id,
+                )
+                meta["status"] = "completed"
+                _save_upload_meta(upload_id, meta)
+                return ChunkedUploadCompleteResponse(
+                    storage_key=storage_key,
+                    ingest_job_id="",
+                    url=file_url,
+                    duplicated=True,
+                    asset_id=existing.id,
+                )
+
+        # Create ingest job
+        use_case = SubmitIngestJobUseCase(ingest_job_repository)
+        job = use_case.execute(
+            SubmitIngestJobCommand(
+                project_id=meta["project_id"],
+                library_id=meta["library_id"],
+                storage_key=storage_key,
+                file_hash=request.file_hash,
+            )
+        )
+        celery_app.send_task("worker.ingest_asset", args=[job.id])
+
+        # Update metadata status
+        meta["status"] = "completed"
+        _save_upload_meta(upload_id, meta)
+
+        return ChunkedUploadCompleteResponse(
+            storage_key=storage_key,
+            ingest_job_id=job.id,
+            url=file_url,
+        )
+
+    finally:
+        # Cleanup temp file and chunks
+        if temp_file_path.exists():
+            temp_file_path.unlink()
+        if chunk_dir.exists():
+            shutil.rmtree(chunk_dir)
+        # Delete metadata file
+        meta_path = _get_upload_meta_path(upload_id)
+        if meta_path.exists():
+            meta_path.unlink()
+
+
 @router.post("/{upload_id}/{chunk_index}")
 async def upload_chunk(
     upload_id: str,
@@ -320,126 +476,3 @@ async def upload_chunk(
         "uploaded_chunks": len(meta["uploaded_chunks"]),
         "total_chunks": meta["total_chunks"],
     }
-
-
-@router.get("/{upload_id}/status", response_model=ChunkedUploadStatusResponse)
-async def get_upload_status(
-    upload_id: str,
-    authenticated_user: AuthenticatedUser = Depends(get_current_user),
-) -> ChunkedUploadStatusResponse:
-    """Get upload status (for resume)"""
-    meta = _load_upload_meta(upload_id)
-
-    return ChunkedUploadStatusResponse(
-        upload_id=upload_id,
-        filename=meta["filename"],
-        file_size=meta["file_size"],
-        total_chunks=meta["total_chunks"],
-        uploaded_chunks=sorted(meta["uploaded_chunks"]),
-        status=meta["status"],
-        created_at=datetime.fromisoformat(meta["created_at"]),
-        expires_at=datetime.fromisoformat(meta["expires_at"]),
-    )
-
-
-@router.post("/{upload_id}/complete", response_model=ChunkedUploadCompleteResponse)
-async def complete_chunked_upload(
-    upload_id: str,
-    request: ChunkedUploadCompleteRequest,
-    authenticated_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-    asset_library_repository: Any = Depends(get_asset_library_repository),
-    ingest_job_repository: Any = Depends(get_ingest_job_repository),
-    storage_service: OSSStorageService = Depends(get_storage_service),
-) -> ChunkedUploadCompleteResponse:
-    """Complete chunked upload, merge chunks"""
-    # Load metadata
-    meta = _load_upload_meta(upload_id)
-
-    # Verify project ID and library ID
-    if request.project_id != meta["project_id"] or request.library_id != meta["library_id"]:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Project or library ID mismatch")
-
-    # Verify all chunks are uploaded
-    expected_chunks = set(range(meta["total_chunks"]))
-    uploaded_chunks = set(meta["uploaded_chunks"])
-    missing_chunks = expected_chunks - uploaded_chunks
-
-    if missing_chunks:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"Missing chunks: {sorted(missing_chunks)}. Please upload remaining chunks first.",
-        )
-
-    # Validate file type
-    chunk_dir = _get_chunk_dir(upload_id)
-    sample_chunk_path = chunk_dir / "chunk_000000"
-    if sample_chunk_path.exists():
-        with open(sample_chunk_path, "rb") as f:
-            sample_data = f.read(8192)  # Read first 8KB for type detection
-        detected_mime = _validate_file_type(sample_data, meta["filename"])
-        if detected_mime not in ALLOWED_MIME_TYPES:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=f"Unsupported file type: {detected_mime}",
-            )
-
-    # Merge chunks to temp file
-    temp_file_path = CHUNK_STORAGE_ROOT / f"{upload_id}_complete.tmp"
-    try:
-        with open(temp_file_path, "wb") as out_file:
-            for i in range(meta["total_chunks"]):
-                chunk_path = chunk_dir / f"chunk_{i:06d}"
-                with open(chunk_path, "rb") as in_file:
-                    shutil.copyfileobj(in_file, out_file)
-
-        # Verify file size
-        actual_size = temp_file_path.stat().st_size
-        if actual_size != meta["file_size"]:
-            raise HTTPException(
-                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-                detail=f"File size mismatch. Expected {meta['file_size']}, got {actual_size}",
-            )
-
-        # Upload to OSS
-        file_id = uuid4().hex[:8]
-        safe_filename = meta["filename"]
-        storage_key = f"uploads/{file_id}/{safe_filename}"
-
-        file_url = storage_service.upload_file(
-            str(temp_file_path),
-            storage_key,
-            content_type=meta["content_type"],
-        )
-
-        # Create ingest job
-        use_case = SubmitIngestJobUseCase(ingest_job_repository)
-        job = use_case.execute(
-            SubmitIngestJobCommand(
-                project_id=meta["project_id"],
-                library_id=meta["library_id"],
-                storage_key=storage_key,
-            )
-        )
-        celery_app.send_task("worker.ingest_asset", args=[job.id])
-
-        # Update metadata status
-        meta["status"] = "completed"
-        _save_upload_meta(upload_id, meta)
-
-        return ChunkedUploadCompleteResponse(
-            storage_key=storage_key,
-            ingest_job_id=job.id,
-            url=file_url,
-        )
-
-    finally:
-        # Cleanup temp file and chunks
-        if temp_file_path.exists():
-            temp_file_path.unlink()
-        if chunk_dir.exists():
-            shutil.rmtree(chunk_dir)
-        # Delete metadata file
-        meta_path = _get_upload_meta_path(upload_id)
-        if meta_path.exists():
-            meta_path.unlink()

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

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

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

@@ -1,4 +1,5 @@
 """查重 API 路由。"""
+
 from __future__ import annotations
 
 import logging
@@ -9,12 +10,12 @@ from app.auth import AuthenticatedUser, get_current_user
 from app.core.storage import OSSStorageService, get_storage_service
 from app.dependencies import get_duplication_repository
 from app.schemas.duplication import (
+    DuplicateSegmentResponse,
     DuplicationDetailResponse,
     DuplicationRecordResponse,
     DuplicationUploadResponse,
-    DuplicateSegmentResponse,
 )
-from fastapi import APIRouter, Depends, File, HTTPException, Response, UploadFile, status
+from fastapi import APIRouter, Depends, File, HTTPException, Query, Response, UploadFile, status
 
 from packages.application import (
     DeleteDuplicationRecordUseCase,
@@ -28,13 +29,22 @@ from packages.domain.duplication import DuplicationRecord
 
 logger = logging.getLogger(__name__)
 
-router = APIRouter()
+router = APIRouter(
+    tags=["查重"],
+)
 
 # 查重功能只接受视频文件
-ALLOWED_VIDEO_MIME_TYPES = frozenset({
-    "video/mp4", "video/mpeg", "video/quicktime", "video/x-msvideo",
-    "video/webm", "video/x-matroska", "video/3gpp",
-})
+ALLOWED_VIDEO_MIME_TYPES = frozenset(
+    {
+        "video/mp4",
+        "video/mpeg",
+        "video/quicktime",
+        "video/x-msvideo",
+        "video/webm",
+        "video/x-matroska",
+        "video/3gpp",
+    }
+)
 
 
 def _validate_video_mime_type(content_type: str | None) -> str:
@@ -44,16 +54,16 @@ def _validate_video_mime_type(content_type: str | None) -> str:
             status_code=status.HTTP_400_BAD_REQUEST,
             detail="Content-Type header is required",
         )
-    
+
     # 处理带参数的类型，如 "video/mp4; charset=utf-8"
     base_type = content_type.split(";")[0].strip().lower()
-    
+
     if base_type not in ALLOWED_VIDEO_MIME_TYPES:
         raise HTTPException(
             status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
-            detail=f"只支持视频文件。支持的类型: mp4, mpeg, mov, avi, webm, mkv, 3gp",
+            detail="只支持视频文件。支持的类型: mp4, mpeg, mov, avi, webm, mkv, 3gp",
         )
-    
+
     return base_type
 
 
@@ -117,9 +127,10 @@ async def upload_for_duplication(
 
     # P0-2: 验证文件大小（参考 OSS_DIRECT_UPLOAD_MAX_MB）
     from app.config import get_settings
+
     settings = get_settings()
     max_size_bytes = settings.OSS_DIRECT_UPLOAD_MAX_MB * 1024 * 1024
-    
+
     # 先检查 Content-Length header（如果可用）
     if file.size is not None and file.size > max_size_bytes:
         raise HTTPException(
@@ -135,7 +146,7 @@ async def upload_for_duplication(
     try:
         content = await file.read()
         file_size = len(content)
-        
+
         # 再次检查实际文件大小
         if file_size > max_size_bytes:
             raise HTTPException(
@@ -190,12 +201,19 @@ async def upload_for_duplication(
 
 @router.get("/records", response_model=list[DuplicationRecordResponse])
 def list_duplication_records(
+    offset: int = Query(0, ge=0, description="分页偏移量"),
+    limit: int = Query(50, ge=1, le=200, description="每页数量，最大 200"),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     duplication_repository: Any = Depends(get_duplication_repository),
 ) -> list[DuplicationRecordResponse]:
-    """获取当前用户的查重记录列表。"""
+    """
+    获取当前用户的查重记录列表。
+
+    支持分页：通过 offset 和 limit 参数控制。
+    返回按创建时间倒序排列的记录。
+    """
     use_case = ListDuplicationRecordsUseCase(duplication_repository)
-    records = use_case.execute(authenticated_user.user.id)
+    records = use_case.execute(user_id=authenticated_user.user.id, offset=offset, limit=limit)
     return [_to_record_response(r) for r in records]
 
 
@@ -221,7 +239,7 @@ def get_duplication_detail(
     return _to_detail_response(record)
 
 
-@router.delete("/records/{record_id}", status_code=status.HTTP_204_NO_CONTENT, response_class=Response)
+@router.delete("/records/{record_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
 def delete_duplication_record(
     record_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -239,7 +257,7 @@ def delete_duplication_record(
 
     use_case = DeleteDuplicationRecordUseCase(duplication_repository)
     use_case.execute(record_id)
-    return Response(status_code=204)
+    return
 
 
 @router.post("/records/{record_id}/retry", response_model=DuplicationUploadResponse)
@@ -248,7 +266,11 @@ def retry_duplication(
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     duplication_repository: Any = Depends(get_duplication_repository),
 ) -> DuplicationUploadResponse:
-    """重新提交查重。"""
+    """
+    重新提交查重。
+
+    仅 failed 状态的记录允许重试，其他状态返回 400。
+    """
     # 检查记录存在且属于当前用户
     detail_uc = GetDuplicationDetailUseCase(duplication_repository)
     record = detail_uc.execute(record_id)
@@ -259,7 +281,13 @@ def retry_duplication(
         )
 
     use_case = RetryDuplicationUseCase(duplication_repository)
-    updated = use_case.execute(record_id)
+    try:
+        updated = use_case.execute(record_id)
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        )
     if updated is None:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,

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

@@ -0,0 +1,462 @@
+"""剪辑计划管理 API — Phase 8 模板编排引擎.
+
+RESTful CRUD for EditPlan:
+- GET    /api/v1/edit-plans            列表（分页 + 状态/模板筛选）
+- GET    /api/v1/edit-plans/{id}       详情
+- POST   /api/v1/edit-plans            创建
+- PUT    /api/v1/edit-plans/{id}       更新（含状态机流转）
+- DELETE /api/v1/edit-plans/{id}       删除
+
+拆分模块（各自独立 router，由本文件 include_router 聚合）:
+- edit_plans_generation.py   生成相关（generate / generation-status / generations）
+- edit_plans_ai.py           AI 推荐 & 封面（ai-recommend / generate-cover）
+- edit_plans_timeline.py     时间线 & 模板生成（timeline / generate-from-template）
+
+业务逻辑委托给 EditPlanService 服务层。
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any, List, Optional
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_db_session, get_project_repository
+from app.schemas.generation_task import GenerationTaskResponse
+from app.services import EditPlanService
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
+
+from packages.domain.config_schemas import normalize_plan_config
+from packages.domain.edit_plan import EditPlan, EditPlanStatus
+
+from ._helpers import check_project_access
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# ── Pydantic Schemas ─────────────────────────────────────────────────────────
+
+
+class EditPlanCreateRequest(BaseModel):
+    """创建剪辑计划请求体"""
+
+    template_id: str = Field(..., min_length=1, max_length=32, description="关联模板 ID")
+    name: str = Field(..., min_length=1, max_length=200, description="计划名称")
+    config: dict[str, Any] = Field(default_factory=dict, description="计划配置 (JSON)")
+    total_duration: float = Field(default=0.0, ge=0.0, description="总时长 (秒)")
+    project_id: str = Field(default="", description="所属项目 ID")
+
+
+class EditPlanUpdateRequest(BaseModel):
+    """更新剪辑计划请求体"""
+
+    name: Optional[str] = Field(default=None, min_length=1, max_length=200, description="计划名称")
+    config: Optional[dict[str, Any]] = Field(default=None, description="计划配置 (JSON)")
+    total_duration: Optional[float] = Field(default=None, ge=0.0, description="总时长 (秒)")
+    status: Optional[str] = Field(
+        default=None,
+        description="目标状态 (通过状态机流转): editing / rendering / completed / failed / draft",
+    )
+
+
+class EditPlanResponse(BaseModel):
+    """剪辑计划响应体"""
+
+    id: str
+    template_id: str
+    name: str
+    status: str
+    total_duration: float
+    project_id: str = ""
+    created_by_user_id: str = ""
+    config: dict[str, Any]
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class EditPlanListResponse(BaseModel):
+    """剪辑计划列表响应体"""
+
+    items: List[EditPlanResponse]
+    total: int
+    page: int
+    page_size: int
+
+
+class ClipStatusItem(BaseModel):
+    """片段生成状态"""
+
+    clip_id: str
+    clip_type: str
+    order: int
+    status: str
+    asset_id: str
+    text_content: str
+    duration: float
+
+
+class EditPlanGenerationStatusResponse(BaseModel):
+    """剪辑计划生成进度响应体"""
+
+    plan_id: str
+    plan_status: str
+    generation_task_id: Optional[str] = None
+    clips: List[ClipStatusItem]
+
+
+class EditPlanGenerateResponse(BaseModel):
+    """剪辑计划触发生成响应体"""
+
+    plan_id: str
+    plan_status: str
+    generation_task_id: str
+    clip_count: int
+
+
+class EditPlanGenerationsResponse(BaseModel):
+    """剪辑计划关联的生成记录列表响应体"""
+
+    items: List[GenerationTaskResponse]
+    total: int
+
+
+# ── AI 推荐片段方案 Schemas（任务 3.09） ──────────────────────────────────────
+
+
+class AIRecommendRequest(BaseModel):
+    """AI 推荐片段方案请求体"""
+
+    asset_ids: List[str] = Field(default_factory=list, description="素材 ID 列表")
+    editing_mode: str = Field(default="one_take", description="剪辑模式: one_take / pip / voice_over / voice_pip")
+    target_duration: float = Field(default=30.0, ge=1.0, le=600.0, description="目标时长（秒）")
+
+
+class AIRecommendClipItem(BaseModel):
+    """AI 推荐的单个片段"""
+
+    clip_type: str = Field(..., description="片段类型: intro / showcase / title / subtitle / cta / outro")
+    order: int = Field(..., ge=0, description="片段顺序")
+    text_content: str = Field(default="", description="文字内容")
+    duration: float = Field(..., ge=0.0, description="片段时长（秒）")
+    transition_effect: str = Field(default="cut", description="转场效果")
+    transition_duration: float = Field(default=0.0, ge=0.0, description="转场时长（秒），0 表示使用默认值")
+    asset_id: str = Field(default="", description="关联素材 ID")
+    start_time: float = Field(default=0.0, ge=0.0, description="素材截取起始时间（秒）")
+    config: dict[str, Any] = Field(default_factory=dict, description="片段额外配置")
+
+
+class AIRecommendResponse(BaseModel):
+    """AI 推荐片段方案响应体"""
+
+    plan_id: str = Field(..., description="剪辑计划 ID")
+    clips: List[AIRecommendClipItem] = Field(..., description="推荐的片段列表")
+    config: dict[str, Any] = Field(..., description="推荐的 plan config（cover/title/subtitle/bgm）")
+    total_duration: float = Field(..., ge=0.0, description="推荐方案总时长（秒）")
+    confidence: float = Field(..., ge=0.0, le=1.0, description="AI 推荐置信度 (0~1)")
+
+
+# ── AI 封面生成 Schemas（任务 3.09） ─────────────────────────────────────────
+
+
+class GenerateCoverRequest(BaseModel):
+    """AI 封面生成请求体"""
+
+    asset_ids: List[str] = Field(default_factory=list, description="素材 ID 列表（确定视频来源）")
+    cover_type: str = Field(
+        default="ai_frame",
+        description="封面类型: ai_frame / manual / upload / ai_regenerate",
+    )
+    frame_time: Optional[float] = Field(
+        default=None,
+        ge=0.0,
+        description="手动选帧时间点（秒），仅 cover_type=manual 时有效",
+    )
+
+
+class GenerateCoverResponse(BaseModel):
+    """AI 封面生成响应体"""
+
+    plan_id: str = Field(..., description="剪辑计划 ID")
+    cover: dict[str, Any] = Field(..., description="封面数据（type / image_url / frame_time 等）")
+
+
+# ── 基于模板生成剪辑计划 Schemas ─────────────────────────────────────────────
+
+
+class GenerateFromTemplateRequest(BaseModel):
+    """基于模板生成剪辑计划请求体"""
+
+    template_id: str = Field(..., description="剪辑模板 ID")
+    asset_ids: List[str] = Field(default_factory=list, description="素材 ID 列表")
+    project_id: str = Field(default="", description="所属项目 ID")
+    name: str = Field(default="", description="计划名称（为空则自动取模板名）")
+
+
+class _PlanClipItem(BaseModel):
+    """片段响应体"""
+
+    id: str
+    clip_type: str
+    order: int
+    asset_id: str
+    text_content: str
+    start_time: float
+    duration: float
+    transition_effect: str
+    transition_duration: float
+    playback_speed: float = 1.0
+    status: str
+    config: Optional[dict[str, Any]] = None
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class GenerateFromTemplateResponse(BaseModel):
+    """基于模板生成剪辑计划响应体"""
+
+    plan: EditPlanResponse
+    clips: List[_PlanClipItem]
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _to_response(p: EditPlan) -> EditPlanResponse:
+    return EditPlanResponse(
+        id=p.id,
+        template_id=p.template_id,
+        name=p.name,
+        status=p.status.value if hasattr(p.status, "value") else p.status,
+        total_duration=p.total_duration,
+        project_id=p.project_id or "",
+        created_by_user_id=p.created_by_user_id or "",
+        config=p.config,
+        created_at=p.created_at,
+        updated_at=p.updated_at,
+    )
+
+
+# ── CRUD Routes ───────────────────────────────────────────────────────────────
+
+
+@router.get("", response_model=EditPlanListResponse)
+def list_plans(
+    page: int = Query(default=1, ge=1, description="页码"),
+    page_size: int = Query(default=20, ge=1, le=100, description="每页数量"),
+    template_id: Optional[str] = Query(default=None, description="按模板 ID 筛选"),
+    project_id: Optional[str] = Query(default=None, description="按项目 ID 筛选"),
+    status_filter: Optional[str] = Query(
+        default=None,
+        alias="status",
+        description="按状态筛选: draft / editing / rendering / completed / failed",
+    ),
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> EditPlanListResponse:
+    """获取剪辑计划列表（支持分页、按模板/状态/项目筛选）"""
+    svc = EditPlanService(db)
+
+    # 空串 project_id 视为未传（避免 DB 中匹配到空串记录）
+    if project_id is not None and not project_id.strip():
+        project_id = None
+
+    # 解析状态筛选
+    status_enum: Optional[EditPlanStatus] = None
+    if status_filter:
+        try:
+            status_enum = EditPlanStatus(status_filter)
+        except ValueError:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="无效的筛选条件，请选择正确的状态",
+            )
+
+    # 项目鉴权：如果指定了 project_id，校验用户是否有权访问
+    if project_id:
+        check_project_access(project_id, current_user.user.id, project_repository)
+
+    skip = (page - 1) * page_size
+    plans = svc.list_plans(
+        template_id=template_id,
+        project_id=project_id,
+        status=status_enum,
+        skip=skip,
+        limit=page_size,
+    )
+    total = svc.count_plans(
+        template_id=template_id,
+        project_id=project_id,
+        status=status_enum,
+    )
+
+    return EditPlanListResponse(
+        items=[_to_response(p) for p in plans],
+        total=total,
+        page=page,
+        page_size=page_size,
+    )
+
+
+@router.get("/{plan_id}", response_model=EditPlanResponse)
+def get_plan(
+    plan_id: str,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> EditPlanResponse:
+    """获取单个剪辑计划详情"""
+    svc = EditPlanService(db)
+    try:
+        plan = svc.get_plan_or_raise(plan_id)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=str(exc),
+        )
+    # 项目鉴权
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+    return _to_response(plan)
+
+
+@router.post("", response_model=EditPlanResponse, status_code=status.HTTP_201_CREATED)
+def create_plan(
+    body: EditPlanCreateRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> EditPlanResponse:
+    """创建剪辑计划"""
+    # 空串 project_id 统一为 ""
+    project_id = (body.project_id or "").strip()
+    # 项目鉴权
+    if project_id:
+        check_project_access(project_id, current_user.user.id, project_repository)
+    svc = EditPlanService(db)
+    # 标准化 config，填充 cover/title/subtitle/bgm 默认值
+    normalized_config = normalize_plan_config(body.config)
+    try:
+        created = svc.create_plan(
+            template_id=body.template_id,
+            name=body.name,
+            config=normalized_config,
+            total_duration=body.total_duration,
+            project_id=project_id,
+            created_by_user_id=current_user.user.id,
+        )
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(exc),
+        )
+    logger.info(
+        "创建剪辑计划: id=%s name=%s by user=%s",
+        created.id,
+        created.name,
+        current_user.user.id,
+    )
+    return _to_response(created)
+
+
+@router.put("/{plan_id}", response_model=EditPlanResponse)
+def update_plan(
+    plan_id: str,
+    body: EditPlanUpdateRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> EditPlanResponse:
+    """更新剪辑计划（支持状态机流转）"""
+    svc = EditPlanService(db)
+    # 项目鉴权
+    existing = svc.get_plan(plan_id)
+    if existing is None:
+        raise HTTPException(status_code=404, detail=f"剪辑计划不存在: {plan_id}")
+    if existing.project_id:
+        check_project_access(existing.project_id, current_user.user.id, project_repository)
+
+    # 基础字段更新
+    try:
+        if body.name is not None or body.config is not None or body.total_duration is not None:
+            # 标准化 config（如果提供了）
+            config_to_update = normalize_plan_config(body.config) if body.config is not None else None
+            svc.update_plan(
+                plan_id,
+                name=body.name,
+                config=config_to_update,
+                total_duration=body.total_duration,
+            )
+
+        # 状态机流转
+        if body.status is not None:
+            try:
+                target_status = EditPlanStatus(body.status)
+            except ValueError:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="无效的状态值，请选择正确的状态",
+                )
+            svc.transition_status(plan_id, target_status)
+    except ValueError as exc:
+        err_msg = str(exc)
+        if "不存在" in err_msg:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=err_msg,
+            )
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=err_msg,
+        )
+
+    # 返回最新状态
+    result = svc.get_plan_or_raise(plan_id)
+    logger.info("更新剪辑计划: id=%s by user=%s", plan_id, current_user.user.id)
+    return _to_response(result)
+
+
+@router.delete("/{plan_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
+def delete_plan(
+    plan_id: str,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> None:
+    """删除剪辑计划"""
+    svc = EditPlanService(db)
+    # 项目鉴权
+    existing = svc.get_plan(plan_id)
+    if existing and existing.project_id:
+        check_project_access(existing.project_id, current_user.user.id, project_repository)
+    deleted = svc.delete_plan(plan_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"剪辑计划不存在: {plan_id}",
+        )
+    logger.info(
+        "删除剪辑计划: id=%s by user=%s",
+        plan_id,
+        current_user.user.id,
+    )
+
+
+# ── Include sub-routers (拆分模块) ────────────────────────────────────────────
+
+from .edit_plans_ai import router as ai_router
+from .edit_plans_generation import router as generation_router
+from .edit_plans_timeline import router as timeline_router
+
+router.include_router(generation_router)
+router.include_router(ai_router)
+router.include_router(timeline_router)

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

@@ -0,0 +1,199 @@
+"""剪辑计划 AI 推荐 & 封面生成 API 端点。
+
+从 edit_plans.py 拆分，包含：
+- POST /{plan_id}/ai-recommend    AI 推荐片段方案
+- POST /{plan_id}/generate-cover  AI 生成封面
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.api.routes._helpers import check_project_access
+from app.api.routes.edit_plans import (
+    AIRecommendClipItem,
+    AIRecommendRequest,
+    AIRecommendResponse,
+    GenerateCoverRequest,
+    GenerateCoverResponse,
+)
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_db_session, get_project_repository
+from app.services import EditPlanService
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from packages.domain.config_schemas import normalize_plan_config
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.post(
+    "/{plan_id}/ai-recommend",
+    response_model=AIRecommendResponse,
+)
+def ai_recommend_clips(
+    plan_id: str,
+    body: AIRecommendRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> AIRecommendResponse:
+    """AI 推荐片段方案
+
+    调用 AI 服务分析素材，自动生成片段编排方案并写入剪辑计划。
+
+    流程：
+    1. 验证计划存在且状态为 draft/editing
+    2. 调用 AI 推荐服务（当前为 stub，后续接入真实 AI）
+    3. 清除计划现有片段，按推荐方案重新创建
+    4. 更新计划 config（cover/title/subtitle/bgm）和 total_duration
+    5. 返回推荐方案详情
+    """
+    svc = EditPlanService(db)
+
+    try:
+        plan = svc.get_plan_or_raise(plan_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    plan_status = plan.status.value if hasattr(plan.status, "value") else plan.status
+    if plan_status not in ("draft", "editing"):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="当前计划状态不支持AI推荐，请先创建或编辑计划后再试",
+        )
+
+    from apps.worker.worker_app.tasks.ai_tasks import run_ai_recommend
+
+    result = run_ai_recommend(
+        plan_id=plan_id,
+        template_id=plan.template_id,
+        asset_ids=body.asset_ids,
+        editing_mode=body.editing_mode,
+        target_duration=body.target_duration,
+    )
+
+    # 事务保护：清除 → 重建 → 更新 必须在同一逻辑事务中
+    try:
+        svc.delete_all_clips(plan_id)
+
+        for clip_data in result["clips"]:
+            svc.create_clip(
+                plan_id=plan_id,
+                clip_type=clip_data["clip_type"],
+                order=clip_data["order"],
+                text_content=clip_data.get("text_content", ""),
+                duration=clip_data["duration"],
+                transition_effect=clip_data.get("transition_effect", "cut"),
+                asset_id=clip_data.get("asset_id", ""),
+                start_time=clip_data.get("start_time", 0.0),
+                config=clip_data.get("config", {}),
+            )
+
+        normalized_config = normalize_plan_config(result.get("config", {}))
+        svc.update_plan(
+            plan_id,
+            config=normalized_config,
+            total_duration=result["total_duration"],
+        )
+    except Exception:
+        logger.exception("AI 推荐写入失败，plan_id=%s 数据可能不一致", plan_id)
+        try:
+            db.rollback()
+        except Exception as rollback_err:
+            logger.error(
+                "AI 推荐回滚失败，数据库会话可能处于不一致状态: plan_id=%s error=%s",
+                plan_id,
+                rollback_err,
+            )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="AI推荐结果保存失败，请稍后重试",
+        )
+
+    logger.info(
+        "AI 推荐片段方案: plan_id=%s clips=%d duration=%.1f by user=%s",
+        plan_id,
+        len(result["clips"]),
+        result["total_duration"],
+        current_user.user.id,
+    )
+
+    return AIRecommendResponse(
+        plan_id=plan_id,
+        clips=[
+            AIRecommendClipItem(
+                clip_type=c["clip_type"],
+                order=c["order"],
+                text_content=c.get("text_content", ""),
+                duration=c["duration"],
+                transition_effect=c.get("transition_effect", "cut"),
+                asset_id=c.get("asset_id", ""),
+                start_time=c.get("start_time", 0.0),
+                config=c.get("config", {}),
+            )
+            for c in result["clips"]
+        ],
+        config=normalized_config,
+        total_duration=result["total_duration"],
+        confidence=result["confidence"],
+    )
+
+
+@router.post(
+    "/{plan_id}/generate-cover",
+    response_model=GenerateCoverResponse,
+)
+def generate_cover(
+    plan_id: str,
+    body: GenerateCoverRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> GenerateCoverResponse:
+    """AI 生成封面
+
+    调用 AI 服务从视频中选帧或生成封面图，并更新计划 config.cover。
+    """
+    svc = EditPlanService(db)
+
+    try:
+        plan = svc.get_plan_or_raise(plan_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    from apps.worker.worker_app.tasks.ai_tasks import run_generate_cover
+
+    cover_data = run_generate_cover(
+        plan_id=plan_id,
+        asset_ids=body.asset_ids,
+        cover_type=body.cover_type,
+        frame_time=body.frame_time,
+    )
+
+    current_config = dict(plan.config)
+    current_config["cover"] = cover_data
+    normalized = normalize_plan_config(current_config)
+    svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
+
+    logger.info(
+        "AI 封面生成: plan_id=%s type=%s by user=%s",
+        plan_id,
+        body.cover_type,
+        current_user.user.id,
+    )
+
+    return GenerateCoverResponse(
+        plan_id=plan_id,
+        cover=cover_data,
+    )

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

@@ -0,0 +1,383 @@
+"""剪辑计划生成相关 API 端点。
+
+从 edit_plans.py 拆分，包含：
+- POST /{plan_id}/generate          触发剪辑渲染生成
+- GET  /{plan_id}/generation-status 查询生成进度
+- GET  /{plan_id}/generations       查询关联的生成记录
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.api.routes._helpers import check_project_access
+from app.api.routes.edit_plans import (
+    ClipStatusItem,
+    EditPlanGenerateResponse,
+    EditPlanGenerationsResponse,
+    EditPlanGenerationStatusResponse,
+)
+from app.auth import AuthenticatedUser, get_current_user
+from app.core.celery_app import celery_app
+from app.core.task_enqueue import GLOBAL_PENDING_LIMIT, USER_PENDING_LIMIT
+from app.dependencies import get_asset_library_repository, get_asset_repository, get_db_session, get_project_repository
+from app.services import EditPlanService
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.generation_task_repository import (
+    SQLAlchemyGenerationTaskRepository,
+)
+from packages.adapters.sqlalchemy_impl.template_clip_config_repository import (
+    SQLAlchemyTemplateClipConfigRepository,
+)
+from packages.adapters.sqlalchemy_impl.template_repository import (
+    SQLAlchemyTemplateRepository,
+)
+from packages.application.generation_tasks import (
+    CreateGenerationTaskCommand,
+    CreateGenerationTaskUseCase,
+)
+from packages.domain.edit_plan import EditPlanStatus
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _auto_fallback_draft_to_editing(svc: EditPlanService, plan_id: str, plan_check) -> None:
+    """自动兜底 1: draft → editing"""
+    if plan_check.status == EditPlanStatus.DRAFT:
+        logger.info("自动兜底: plan=%s draft→editing", plan_id)
+        svc.transition_status(plan_id, EditPlanStatus.EDITING)
+
+
+def _auto_fallback_copy_template_clips(svc: EditPlanService, plan_id: str, plan_check, db: Session) -> None:
+    """自动兜底 2: 无片段 + 有 template_id → 从模板复制片段配置"""
+    existing_clips = svc.count_clips(plan_id)
+    if existing_clips == 0 and plan_check.template_id:
+        logger.info(
+            "自动兜底: plan=%s 无片段，从模板 %s 复制片段配置",
+            plan_id,
+            plan_check.template_id,
+        )
+        clip_config_repo = SQLAlchemyTemplateClipConfigRepository(db)
+        configs = clip_config_repo.list_by_template(plan_check.template_id)
+        if configs:
+            for cfg in configs:
+                svc.create_clip(
+                    plan_id=plan_id,
+                    clip_type=cfg.clip_type.value if hasattr(cfg.clip_type, "value") else cfg.clip_type,
+                    order=cfg.order,
+                    template_clip_config_id=cfg.id,
+                    duration=cfg.default_duration,
+                    transition_effect=(
+                        cfg.transition_effect.value
+                        if hasattr(cfg.transition_effect, "value")
+                        else cfg.transition_effect
+                    ),
+                )
+            logger.info("自动兜底: plan=%s 从新模型 template_clip_configs 复制了 %d 个片段", plan_id, len(configs))
+        else:
+            tpl_repo = SQLAlchemyTemplateRepository(db)
+            segments = tpl_repo.list_segments(plan_check.template_id)
+            for seg in segments:
+                avg_duration = (seg.duration_min + seg.duration_max) / 2
+                svc.create_clip(
+                    plan_id=plan_id,
+                    clip_type="main",
+                    order=seg.segment_order,
+                    duration=avg_duration,
+                    config={
+                        "material_type": seg.material_type or "",
+                        "template_segment_id": seg.id,
+                    },
+                )
+            logger.info("自动兜底: plan=%s 从旧模型 template_segments 复制了 %d 个片段", plan_id, len(segments))
+
+
+def _auto_fallback_assign_assets(
+    svc: EditPlanService,
+    plan_id: str,
+    plan_check,
+) -> list:
+    """自动兜底 3: 为没有素材的片段分配素材。返回剩余无素材片段列表。"""
+    all_clips = svc.list_clips(plan_id)
+    clips_without_asset = [c for c in all_clips if not c.asset_id]
+    config_asset_ids = (plan_check.config or {}).get("asset_ids", [])
+
+    if clips_without_asset and config_asset_ids:
+        logger.info(
+            "自动兜底3: plan=%s 为 %d 个无素材片段分配 %d 个指定素材",
+            plan_id,
+            len(clips_without_asset),
+            len(config_asset_ids),
+        )
+        for i, clip in enumerate(clips_without_asset):
+            asset_idx = i % len(config_asset_ids)
+            svc.assign_asset(clip.id, config_asset_ids[asset_idx])
+        logger.info("自动兜底3: plan=%s 素材分配完成", plan_id)
+        clips_without_asset = []
+
+    return clips_without_asset
+
+
+def _auto_fallback_auto_material_mode(
+    svc: EditPlanService,
+    plan_id: str,
+    plan_check,
+    clips_without_asset: list,
+    asset_library_repo: Any,
+    asset_repo: Any,
+) -> None:
+    """自动兜底 4: 自动素材模式 → 从项目默认视频素材库选取"""
+    if not clips_without_asset:
+        return
+    material_mode = (plan_check.config or {}).get("material_mode", "manual")
+    if material_mode != "auto" or not plan_check.project_id:
+        return
+
+    import random
+
+    logger.info(
+        "自动兜底4: plan=%s 自动素材模式，从项目素材库选取素材 (%d 个片段需要)",
+        plan_id,
+        len(clips_without_asset),
+    )
+    libs = asset_library_repo.find_by_project(plan_check.project_id)
+    video_lib = None
+    for lib in libs:
+        lib_kind = lib.kind.value if hasattr(lib.kind, "value") else lib.kind
+        if lib_kind == "video":
+            video_lib = lib
+            break
+
+    if video_lib:
+        assets = asset_repo.find_by_library(video_lib.id)
+        ready_videos = [
+            a
+            for a in assets
+            if (a.status.value if hasattr(a.status, "value") else a.status) == "ready"
+            and a.mime_type
+            and a.mime_type.startswith("video")
+        ]
+        if ready_videos:
+            random.shuffle(ready_videos)
+            for i, clip in enumerate(clips_without_asset):
+                asset = ready_videos[i % len(ready_videos)]
+                svc.assign_asset(clip.id, asset.id)
+            logger.info(
+                "自动兜底4: plan=%s 从素材库 %s 分配了 %d 个素材给 %d 个片段",
+                plan_id,
+                video_lib.name,
+                len(ready_videos),
+                len(clips_without_asset),
+            )
+        else:
+            logger.warning("自动兜底4: plan=%s 素材库无可用视频素材", plan_id)
+    else:
+        logger.warning("自动兜底4: plan=%s 项目无视频素材库", plan_id)
+
+
+def _check_queue_limits(gen_task_repo, user_id: str) -> None:
+    """队列限流预检查"""
+    try:
+        has_count = hasattr(gen_task_repo, "count_pending_by_user") and hasattr(
+            gen_task_repo, "count_pending_total"
+        )
+        if has_count:
+            user_pending = gen_task_repo.count_pending_by_user(user_id)
+            global_pending = gen_task_repo.count_pending_total()
+            if user_pending >= USER_PENDING_LIMIT:
+                raise HTTPException(
+                    status_code=429,
+                    detail=f"您的待处理任务过多（当前 {user_pending}/{USER_PENDING_LIMIT}），请等待完成后再提交",
+                )
+            if global_pending >= GLOBAL_PENDING_LIMIT:
+                raise HTTPException(
+                    status_code=503,
+                    detail="系统繁忙，请稍后再试",
+                )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.warning("[队列限流] 剪辑计划限流检查失败，跳过: %s", e)
+
+
+@router.post("/{plan_id}/generate", response_model=EditPlanGenerateResponse)
+def generate_plan(
+    plan_id: str,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+    asset_library_repo: Any = Depends(get_asset_library_repository),
+    asset_repo: Any = Depends(get_asset_repository),
+) -> EditPlanGenerateResponse:
+    """触发剪辑计划渲染生成
+
+    前置条件：计划状态必须为 editing，且至少有一个片段。
+    流程：
+    1. 验证计划状态为 editing
+    2. 将 pending 片段标记为 ready
+    3. 创建 GenerationTask
+    4. 调度 Celery 任务 worker.render_edit_plan
+    5. 将计划状态流转为 rendering
+    """
+    svc = EditPlanService(db)
+    plan_check = svc.get_plan(plan_id)
+    if plan_check is None:
+        raise HTTPException(status_code=404, detail=f"剪辑计划不存在: {plan_id}")
+    if plan_check.project_id:
+        check_project_access(plan_check.project_id, current_user.user.id, project_repository)
+
+    # 自动兜底流程
+    _auto_fallback_draft_to_editing(svc, plan_id, plan_check)
+    _auto_fallback_copy_template_clips(svc, plan_id, plan_check, db)
+    clips_without_asset = _auto_fallback_assign_assets(svc, plan_id, plan_check)
+    _auto_fallback_auto_material_mode(svc, plan_id, plan_check, clips_without_asset, asset_library_repo, asset_repo)
+
+    # 检查是否可生成
+    try:
+        can_gen, reason = svc.can_generate(plan_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+    if not can_gen:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=reason)
+
+    # 核心生成流程
+    try:
+        clip_count = svc.mark_clips_ready(plan_id)
+
+        gen_task_repo = SQLAlchemyGenerationTaskRepository(db)
+        user_id = current_user.user.id
+        _check_queue_limits(gen_task_repo, user_id)
+
+        gen_task_use_case = CreateGenerationTaskUseCase(gen_task_repo)
+        plan = svc.get_plan_or_raise(plan_id)
+        gen_task = gen_task_use_case.execute(
+            CreateGenerationTaskCommand(
+                project_id="",
+                template_id=plan.template_id,
+                created_by_user_id=current_user.user.id,
+                source_edit_plan_id=plan_id,
+            )
+        )
+
+        svc.update_plan_config(plan_id, {"generation_task_id": gen_task.id})
+        svc.transition_status(plan_id, EditPlanStatus.RENDERING)
+        celery_app.send_task("worker.render_edit_plan", args=[plan_id])
+
+        updated_plan = svc.get_plan_or_raise(plan_id)
+
+        logger.info(
+            "触发剪辑计划生成: plan_id=%s gen_task_id=%s clips=%d by user=%s",
+            plan_id,
+            gen_task.id,
+            clip_count,
+            current_user.user.id,
+        )
+
+        return EditPlanGenerateResponse(
+            plan_id=plan_id,
+            plan_status=updated_plan.status.value if hasattr(updated_plan.status, "value") else updated_plan.status,
+            generation_task_id=gen_task.id,
+            clip_count=clip_count,
+        )
+    except HTTPException:
+        raise
+    except Exception:
+        logger.exception("触发剪辑计划生成失败: plan_id=%s", plan_id)
+        try:
+            svc.transition_status(plan_id, EditPlanStatus.FAILED)
+        except Exception:
+            logger.warning("标记计划失败状态时异常: plan_id=%s", plan_id)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="生成失败，请稍后重试",
+        )
+
+
+@router.get(
+    "/{plan_id}/generation-status",
+    response_model=EditPlanGenerationStatusResponse,
+)
+def get_generation_status(
+    plan_id: str,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> EditPlanGenerationStatusResponse:
+    """查询剪辑计划生成进度"""
+    svc = EditPlanService(db)
+    try:
+        gen_status = svc.get_generation_status(plan_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+
+    plan = gen_status["plan"]
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+    clips = gen_status["clips"]
+
+    clip_items = [
+        ClipStatusItem(
+            clip_id=c.id,
+            clip_type=c.clip_type,
+            order=c.order,
+            status=c.status.value if hasattr(c.status, "value") else c.status,
+            asset_id=c.asset_id or "",
+            text_content=c.text_content or "",
+            duration=c.duration,
+        )
+        for c in clips
+    ]
+
+    return EditPlanGenerationStatusResponse(
+        plan_id=plan_id,
+        plan_status=plan.status.value if hasattr(plan.status, "value") else plan.status,
+        generation_task_id=gen_status["generation_task_id"],
+        clips=clip_items,
+    )
+
+
+@router.get(
+    "/{plan_id}/generations",
+    response_model=EditPlanGenerationsResponse,
+)
+def list_plan_generations(
+    plan_id: str,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> EditPlanGenerationsResponse:
+    """查询剪辑计划关联的所有生成记录"""
+    svc = EditPlanService(db)
+    plan = svc.get_plan_or_raise(plan_id)
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    from app.schemas.generation_task import GenerationTaskResponse
+
+    gen_task_repo = SQLAlchemyGenerationTaskRepository(db)
+    tasks = gen_task_repo.list_by_source_edit_plan(plan_id)
+    items = [
+        GenerationTaskResponse(
+            id=t.id,
+            project_id=t.project_id,
+            asset_library_id=t.asset_library_id,
+            strategy_id=t.strategy_id,
+            voice_library_id=t.voice_library_id,
+            template_id=t.template_id,
+            asset_ids=t.asset_ids,
+            title_ids=t.title_ids,
+            voice_ids=t.voice_ids,
+            source_edit_plan_id=t.source_edit_plan_id or "",
+            status=t.status.value if hasattr(t.status, "value") else t.status,
+            progress=t.progress,
+            result_count=t.result_count,
+            error_message=t.error_message,
+        )
+        for t in tasks
+    ]
+    return EditPlanGenerationsResponse(items=items, total=len(items))

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

@@ -0,0 +1,221 @@
+"""剪辑计划时间线 & 模板生成 API 端点。
+
+从 edit_plans.py 拆分，包含：
+- GET  /{plan_id}/timeline            时间线场景数据
+- POST /generate-from-template        基于模板+素材自动生成剪辑计划
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, List
+
+from app.api.routes._helpers import check_project_access
+from app.api.routes.edit_plans import (
+    GenerateFromTemplateRequest,
+    GenerateFromTemplateResponse,
+    _PlanClipItem,
+    _to_response,
+)
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_db_session, get_project_repository
+from app.services import EditPlanService, PlanGeneratorService
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# ── Timeline Schemas ──────────────────────────────────────────────────────────
+
+
+class TimelineSceneResponse(BaseModel):
+    """时间线场景"""
+
+    scene: str = Field(..., description="场景描述")
+    time: str = Field(..., description='时间范围，如 "0:00 - 0:05"')
+    duration: float = Field(..., ge=0, description="时长（秒）")
+    color: str = Field(..., description="展示颜色")
+    clip_id: str = Field(default="", description="关联的片段 ID")
+    clip_type: str = Field(default="", description="片段类型")
+
+
+class TimelineResponse(BaseModel):
+    """时间线响应"""
+
+    plan_id: str
+    total_duration: float
+    scenes: List[TimelineSceneResponse]
+
+
+# clip_type → 颜色映射
+_CLIP_TYPE_COLORS = {
+    "intro": "#6366f1",
+    "title": "#6366f1",
+    "product": "#818cf8",
+    "showcase": "#10b981",
+    "scene": "#10b981",
+    "subtitle": "#f59e0b",
+    "text": "#f59e0b",
+    "cta": "#ef4444",
+    "outro": "#ef4444",
+    "voiceover": "#8b5cf6",
+    "transition": "#64748b",
+}
+
+_DEFAULT_COLOR = "#6366f1"
+
+
+def _format_time(seconds: float) -> str:
+    """将秒数格式化为 M:SS"""
+    m = int(seconds) // 60
+    s = int(seconds) % 60
+    return f"{m}:{s:02d}"
+
+
+def _clip_type_to_scene_label(clip_type: str, text_content: str) -> str:
+    """根据 clip_type 和 text_content 生成场景描述"""
+    type_labels = {
+        "intro": "开场",
+        "title": "标题",
+        "product": "产品展示",
+        "showcase": "场景展示",
+        "scene": "场景",
+        "subtitle": "字幕",
+        "text": "文字",
+        "cta": "结尾 CTA",
+        "outro": "结尾",
+        "voiceover": "配音",
+        "transition": "转场",
+    }
+    label = type_labels.get(clip_type, clip_type or "片段")
+    if text_content:
+        short = text_content[:20].strip()
+        if short:
+            return f"{label} - {short}"
+    return label
+
+
+# ── Routes ────────────────────────────────────────────────────────────────────
+
+
+@router.get(
+    "/{plan_id}/timeline",
+    response_model=TimelineResponse,
+)
+def get_plan_timeline(
+    plan_id: str,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> TimelineResponse:
+    """获取剪辑计划的时间线场景数据"""
+    svc = EditPlanService(db)
+    plan = svc.get_plan_or_raise(plan_id)
+    if plan.project_id:
+        check_project_access(plan.project_id, current_user.user.id, project_repository)
+
+    clips = svc.list_clips(plan_id=plan_id, skip=0, limit=200)
+    clips.sort(key=lambda c: c.order)
+
+    scenes: List[TimelineSceneResponse] = []
+    current_time = 0.0
+
+    for clip in clips:
+        start = current_time
+        end = start + clip.duration
+        color = _CLIP_TYPE_COLORS.get(clip.clip_type, _DEFAULT_COLOR)
+        scene_label = _clip_type_to_scene_label(clip.clip_type, clip.text_content)
+
+        scenes.append(
+            TimelineSceneResponse(
+                scene=scene_label,
+                time=f"{_format_time(start)} - {_format_time(end)}",
+                duration=clip.duration,
+                color=color,
+                clip_id=clip.id,
+                clip_type=clip.clip_type,
+            )
+        )
+        current_time = end
+
+    total_duration = sum(s.duration for s in scenes) or plan.total_duration
+
+    return TimelineResponse(
+        plan_id=plan_id,
+        total_duration=total_duration,
+        scenes=scenes,
+    )
+
+
+@router.post(
+    "/generate-from-template",
+    response_model=GenerateFromTemplateResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+def generate_from_template(
+    body: GenerateFromTemplateRequest,
+    db: Session = Depends(get_db_session),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> GenerateFromTemplateResponse:
+    """基于模板 + 素材自动生成剪辑计划"""
+    from app.services import EditTemplateService
+
+    if body.project_id:
+        check_project_access(body.project_id, current_user.user.id, project_repository)
+
+    template_svc = EditTemplateService(db)
+
+    try:
+        template = template_svc.get_template_or_raise(body.template_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+
+    clip_configs = template_svc.list_clip_configs(body.template_id, skip=0, limit=200)
+
+    generator = PlanGeneratorService(db)
+    result = generator.generate_from_template(
+        template=template,
+        clip_configs=clip_configs,
+        asset_ids=body.asset_ids,
+        project_id=body.project_id,
+        created_by_user_id=current_user.user.id,
+        name=body.name,
+    )
+
+    plan = result["plan"]
+    clips = result["clips"]
+
+    logger.info(
+        "基于模板生成剪辑计划: plan_id=%s template_id=%s clips=%d by user=%s",
+        plan.id,
+        body.template_id,
+        len(clips),
+        current_user.user.id,
+    )
+
+    return GenerateFromTemplateResponse(
+        plan=_to_response(plan),
+        clips=[
+            _PlanClipItem(
+                id=c.id,
+                clip_type=c.clip_type,
+                order=c.order,
+                asset_id=c.asset_id,
+                text_content=c.text_content,
+                start_time=c.start_time,
+                duration=c.duration,
+                transition_effect=c.transition_effect,
+                transition_duration=c.transition_duration,
+                status=c.status.value if hasattr(c.status, "value") else c.status,
+                config=c.config,
+                created_at=c.created_at,
+                updated_at=c.updated_at,
+            )
+            for c in clips
+        ],
+    )

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

@@ -0,0 +1,194 @@
+"""Feature Flag 内部管理接口。
+
+通过内部 API Key 鉴权，支持查看和修改 Feature Flag 配置。
+主要用于灰度发布期间的动态开关控制。
+
+API:
+  GET  /api/v1/internal/feature-flags          - 列出所有 flag
+  GET  /api/v1/internal/feature-flags/{name}   - 查看单个 flag
+  PUT  /api/v1/internal/feature-flags/{name}   - 设置 flag 配置
+  DELETE /api/v1/internal/feature-flags/{name} - 删除 flag
+
+鉴权：X-API-Key header，走内部 API Key 验证
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from app.api.routes.auth import _verify_internal_api_key
+from app.config import settings
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from pydantic import BaseModel, Field
+
+from packages.adapters.redis.feature_flag_store import (
+    FeatureFlagConfig,
+    RedisFeatureFlagStore,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/internal/feature-flags", tags=["Internal"])
+
+# 允许管理的 flag 白名单（防止误操作其他系统 flag）
+ALLOWED_FLAGS = {
+    "render_engine",
+}
+
+
+def _get_feature_flag_store() -> RedisFeatureFlagStore:
+    """获取 Feature Flag 存储实例。"""
+    return RedisFeatureFlagStore(redis_url=settings.REDIS_URL)
+
+
+class FeatureFlagUpdateRequest(BaseModel):
+    """Feature Flag 更新请求体。"""
+
+    enabled: bool = Field(..., description="是否启用")
+    percentage: int = Field(0, ge=0, le=100, description="灰度百分比 (0-100)")
+    whitelist: list[str] = Field(default_factory=list, description="白名单列表（如 user_id）")
+
+
+class FeatureFlagResponse(BaseModel):
+    """Feature Flag 响应。"""
+
+    name: str
+    enabled: bool
+    percentage: int
+    whitelist: list[str]
+
+    @classmethod
+    def from_config(cls, config: FeatureFlagConfig) -> "FeatureFlagResponse":
+        return cls(
+            name=config.name,
+            enabled=config.enabled,
+            percentage=config.percentage,
+            whitelist=sorted(config.whitelist),
+        )
+
+
+class FeatureFlagCheckResponse(BaseModel):
+    """Flag 激活检查响应。"""
+
+    name: str
+    active: bool
+    identifier: Optional[str] = None
+
+
+def _validate_flag_name(name: str) -> None:
+    """校验 flag 名称是否在允许列表中。"""
+    if name not in ALLOWED_FLAGS:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Unsupported flag: {name}. Allowed: {sorted(ALLOWED_FLAGS)}",
+        )
+
+
+@router.get("", response_model=list[FeatureFlagResponse])
+async def list_feature_flags(
+    _: bool = Depends(_verify_internal_api_key),
+    store: RedisFeatureFlagStore = Depends(_get_feature_flag_store),
+) -> list[FeatureFlagResponse]:
+    """列出所有 Feature Flag。"""
+    try:
+        flags = store.list_all()
+        # 同时返回预定义的 flag（即使未设置也显示默认值）
+        result = []
+        for name in sorted(ALLOWED_FLAGS):
+            config = flags.get(name) or FeatureFlagConfig(name=name, enabled=False)
+            result.append(FeatureFlagResponse.from_config(config))
+        # 加上已存在但不在白名单中的 flag（只读展示）
+        for name, config in flags.items():
+            if name not in ALLOWED_FLAGS:
+                result.append(FeatureFlagResponse.from_config(config))
+        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}")
+
+
+@router.get("/{name}", response_model=FeatureFlagResponse)
+async def get_feature_flag(
+    name: str,
+    _: bool = Depends(_verify_internal_api_key),
+    store: RedisFeatureFlagStore = Depends(_get_feature_flag_store),
+) -> FeatureFlagResponse:
+    """获取单个 Feature Flag 配置。"""
+    try:
+        config = store.get(name)
+        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}")
+
+
+@router.get("/{name}/check", response_model=FeatureFlagCheckResponse)
+async def check_feature_flag(
+    name: str,
+    identifier: Optional[str] = Query(None, description="标识符，如 user_id"),
+    _: bool = Depends(_verify_internal_api_key),
+    store: RedisFeatureFlagStore = Depends(_get_feature_flag_store),
+) -> FeatureFlagCheckResponse:
+    """检查某个标识符是否命中 Feature Flag。"""
+    try:
+        active = store.is_active(name, identifier=identifier)
+        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}")
+
+
+@router.put("/{name}", response_model=FeatureFlagResponse)
+async def update_feature_flag(
+    name: str,
+    request: FeatureFlagUpdateRequest,
+    _: bool = Depends(_verify_internal_api_key),
+    store: RedisFeatureFlagStore = Depends(_get_feature_flag_store),
+) -> FeatureFlagResponse:
+    """更新 Feature Flag 配置。
+
+    只允许修改 ALLOWED_FLAGS 列表中的 flag。
+    """
+    _validate_flag_name(name)
+
+    try:
+        config = FeatureFlagConfig(
+            name=name,
+            enabled=request.enabled,
+            percentage=request.percentage,
+            whitelist=set(request.whitelist),
+        )
+        store.set(config)
+        logger.info(
+            "Feature flag updated: name=%s enabled=%s percentage=%d whitelist=%d",
+            name,
+            config.enabled,
+            config.percentage,
+            len(config.whitelist),
+        )
+        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}")
+
+
+@router.delete("/{name}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
+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。
+    """
+    _validate_flag_name(name)
+
+    try:
+        deleted = store.delete(name)
+        logger.info("Feature flag deleted: name=%s deleted=%s", name, deleted)
+        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}")

apps/api/app/api/routes/generated_videos.py

@@ -1,123 +0,0 @@
-from typing import Any
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.core.storage import OSSStorageService, get_storage_service
-from app.dependencies import get_generated_video_repository, get_project_repository
-from app.schemas.generated_video import (
-    GeneratedVideoDownloadUrlResponse,
-    GeneratedVideoResponse,
-    ListGeneratedVideosResponse,
-    UpdateGeneratedVideoReviewRequest,
-)
-from fastapi import APIRouter, Depends, HTTPException, Query
-
-from packages.application import (
-    GetGeneratedVideoDownloadUrlUseCase,
-    GetGeneratedVideoUseCase,
-    ListGeneratedVideosUseCase,
-)
-
-router = APIRouter()
-
-
-def _to_generated_video_response(item, download_url: str | None = None) -> GeneratedVideoResponse:
-    return GeneratedVideoResponse(
-        id=item.id,
-        project_id=item.project_id,
-        generation_task_id=item.generation_task_id,
-        name=item.name,
-        file_url=item.file_url,
-        file_size=item.file_size,
-        duration=item.duration,
-        thumbnail_url=item.thumbnail_url,
-        width=item.width,
-        height=item.height,
-        fps=item.fps,
-        status=item.status,
-        review_status=item.review_status,
-        generation_params=item.generation_params,
-        download_url=download_url,
-    )
-
-
-@router.get("", response_model=ListGeneratedVideosResponse)
-def list_generated_videos(
-    project_id: str | None = Query(None),
-    authenticated_user: AuthenticatedUser = Depends(get_current_user),
-    generated_video_repository: Any = Depends(get_generated_video_repository),
-    project_repository: Any = Depends(get_project_repository),
-    storage_service: OSSStorageService = Depends(get_storage_service),
-) -> ListGeneratedVideosResponse:
-    user_id = authenticated_user.user.id
-    use_case = ListGeneratedVideosUseCase(generated_video_repository)
-    
-    if project_id:
-        # If project_id provided, check access and filter by project
-        project = project_repository.find_by_id(project_id)
-        if project is None:
-            raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
-        items = use_case.execute(project_id)
-    else:
-        # If no project_id, list all videos from accessible projects
-        accessible_projects = project_repository.find_accessible_projects(user_id)
-        all_items = []
-        for proj in accessible_projects:
-            all_items.extend(use_case.execute(proj.id))
-        items = all_items
-    
-    # Generate download URLs for each video
-    responses = []
-    for item in items:
-        download_url = storage_service.get_download_url(item.file_url)
-        responses.append(_to_generated_video_response(item, download_url=download_url))
-    return ListGeneratedVideosResponse(items=responses)
-
-
-@router.get("/{video_id}", response_model=GeneratedVideoResponse)
-def get_generated_video(
-    video_id: str,
-    authenticated_user: AuthenticatedUser = Depends(get_current_user),
-    generated_video_repository: Any = Depends(get_generated_video_repository),
-    storage_service: OSSStorageService = Depends(get_storage_service),
-) -> GeneratedVideoResponse:
-    use_case = GetGeneratedVideoUseCase(generated_video_repository)
-    item = use_case.execute(video_id)
-    if item is None:
-        raise HTTPException(status_code=404, detail=f"GeneratedVideo {video_id} not found")
-    download_url = storage_service.get_download_url(item.file_url)
-    return _to_generated_video_response(item, download_url=download_url)
-
-
-@router.patch("/{video_id}/review", response_model=GeneratedVideoResponse)
-def update_generated_video_review_status(
-    video_id: str,
-    request: UpdateGeneratedVideoReviewRequest,
-    authenticated_user: AuthenticatedUser = Depends(get_current_user),
-    generated_video_repository: Any = Depends(get_generated_video_repository),
-    storage_service: OSSStorageService = Depends(get_storage_service),
-) -> GeneratedVideoResponse:
-    video = generated_video_repository.get(video_id)
-    if video is None:
-        raise HTTPException(status_code=404, detail=f"GeneratedVideo {video_id} not found")
-    video.review_status = request.review_status
-    updated = generated_video_repository.update(video)
-    download_url = storage_service.get_download_url(updated.file_url)
-    return _to_generated_video_response(updated, download_url=download_url)
-
-
-@router.get("/{video_id}/download-url", response_model=GeneratedVideoDownloadUrlResponse)
-def get_generated_video_download_url(
-    video_id: str,
-    authenticated_user: AuthenticatedUser = Depends(get_current_user),
-    generated_video_repository: Any = Depends(get_generated_video_repository),
-    storage_service: OSSStorageService = Depends(get_storage_service),
-) -> GeneratedVideoDownloadUrlResponse:
-    video = generated_video_repository.get(video_id)
-    if video is None:
-        raise HTTPException(status_code=404, detail=f"GeneratedVideo {video_id} not found")
-    use_case = GetGeneratedVideoDownloadUrlUseCase(generated_video_repository)
-    file_url = use_case.execute(video_id)
-    if file_url is None:
-        raise HTTPException(status_code=404, detail=f"GeneratedVideo {video_id} not found")
-    download_url = storage_service.get_download_url(file_url)
-    return GeneratedVideoDownloadUrlResponse(video_id=video_id, download_url=download_url)

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

@@ -1,7 +1,18 @@
+import logging
+import random
+import uuid
 from typing import Any
 
+from app.api.routes._helpers import check_project_access
 from app.auth import AuthenticatedUser, get_current_user
-from app.core.celery_app import celery_app
+from app.core.storage import OSSStorageService, get_storage_service
+from app.core.task_enqueue import (
+    GLOBAL_PENDING_LIMIT,
+    USER_PENDING_LIMIT,
+    GlobalQueueFull,
+    UserPendingLimitExceeded,
+    safe_enqueue_generation_task,
+)
 from app.dependencies import (
     get_asset_library_repository,
     get_asset_repository,
@@ -14,8 +25,10 @@ from app.schemas.generated_video import (
     ListGeneratedVideosResponse,
 )
 from app.schemas.generation_task import (
+    BatchGenerationTaskResponse,
     CreateGenerationTaskRequest,
     GenerationTaskResponse,
+    ListGenerationTasksResponse,
 )
 from fastapi import APIRouter, Depends, HTTPException
 
@@ -26,18 +39,10 @@ from packages.application import (
     ListGeneratedVideosByTaskUseCase,
 )
 
+logger = logging.getLogger(__name__)
+
 router = APIRouter()
 
-
-def _check_project_access(project_id: str, user_id: str, project_repository) -> None:
-    """检查用户是否有项目访问权限"""
-    project = project_repository.find_by_id(project_id)
-    if project is None:
-        raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
-    if not project.can_access(user_id):
-        raise HTTPException(status_code=403, detail="Access denied to project")
-
-
 def _to_generation_task_response(task) -> GenerationTaskResponse:
     return GenerationTaskResponse(
         id=task.id,
@@ -45,6 +50,14 @@ def _to_generation_task_response(task) -> GenerationTaskResponse:
         asset_library_id=task.asset_library_id,
         strategy_id=task.strategy_id,
         voice_library_id=task.voice_library_id,
+        template_id=task.template_id,
+        asset_ids=task.asset_ids,
+        title_ids=task.title_ids,
+        voice_ids=task.voice_ids,
+        source_edit_plan_id=task.source_edit_plan_id or "",
+        asset_select_mode=getattr(task, "asset_select_mode", ""),
+        batch_id=getattr(task, "batch_id", ""),
+        logs=getattr(task, "logs", "[]"),
         status=task.status,
         progress=task.progress,
         result_count=task.result_count,
@@ -52,7 +65,7 @@ def _to_generation_task_response(task) -> GenerationTaskResponse:
     )
 
 
-def _to_generated_video_response(item) -> GeneratedVideoResponse:
+def _to_generated_video_response(item, download_url: str | None = None) -> GeneratedVideoResponse:
     return GeneratedVideoResponse(
         id=item.id,
         project_id=item.project_id,
@@ -65,6 +78,7 @@ def _to_generated_video_response(item) -> GeneratedVideoResponse:
         width=item.width,
         height=item.height,
         fps=item.fps,
+        download_url=download_url,
     )
 
 
@@ -79,7 +93,87 @@ def _ensure_library_has_ready_video_assets(assets) -> None:
         )
 
 
-@router.post("/tasks", response_model=GenerationTaskResponse)
+def _select_assets_from_library(
+    assets: list,
+    mode: str,
+    count: int,
+) -> list[str]:
+    """根据选取模式从素材库中选取 ready 状态的视频素材 ID。
+
+    Args:
+        assets: 素材库中所有素材（Asset 实体列表）
+        mode: 选取模式 — all=全部, random=随机, smart=按质量评分
+        count: 选取数量，0 表示全部（仅 random/smart 模式有效）
+
+    Returns:
+        选中的素材 ID 列表
+    """
+    ready_video_assets = [a for a in assets if a.status.value == "ready" and a.mime_type.startswith("video")]
+
+    if not ready_video_assets:
+        return []
+
+    if mode == "random":
+        selected = (
+            ready_video_assets if count <= 0 else random.sample(ready_video_assets, min(count, len(ready_video_assets)))
+        )
+        return [a.id for a in selected]
+
+    if mode == "smart":
+        # 按质量分降序排列（质量分高的优先），质量分相同时按时长降序
+        sorted_assets = sorted(
+            ready_video_assets,
+            key=lambda a: (
+                a.quality_score if a.quality_score is not None else 0.0,
+                a.duration if a.duration is not None else 0.0,
+            ),
+            reverse=True,
+        )
+        selected = sorted_assets if count <= 0 else sorted_assets[:count]
+        return [a.id for a in selected]
+
+    # 默认 all 模式：返回全部 ready 视频素材
+    return [a.id for a in ready_video_assets]
+
+
+def _resolve_project_and_library(
+    request: CreateGenerationTaskRequest,
+    project_repository: Any,
+    asset_library_repository: Any,
+    asset_repository: Any,
+    authenticated_user: AuthenticatedUser,
+) -> tuple[str, str]:
+    """解析 project_id 和 asset_library_id。
+
+    支持两种模式：
+    - 显式传入（向后兼容）
+    - 从 asset_ids 反查 asset_library（模板模式）
+    返回 (project_id, asset_library_id)。
+    """
+    project_id = request.project_id.strip()
+    asset_library_id = request.asset_library_id.strip()
+
+    # 模板模式：project_id 未提供时，从 asset_ids 反查所属 project
+    if not project_id and request.asset_ids:
+        first_asset_id = request.asset_ids[0]
+        asset = asset_repository.find_by_id(first_asset_id)
+        if asset is not None:
+            project_id = asset.project_id
+            if not asset_library_id:
+                asset_library_id = asset.library_id
+
+    # 向后兼容校验：project_id 已提供时验证权限
+    if project_id:
+        project = project_repository.find_by_id(project_id)
+        if project is None:
+            raise HTTPException(status_code=404, detail=f"Project {project_id} not found")
+        if not project.can_access(authenticated_user.user.id):
+            raise HTTPException(status_code=403, detail="Access denied to project")
+
+    return project_id, asset_library_id
+
+
+@router.post("/tasks", response_model=BatchGenerationTaskResponse)
 def create_generation_task(
     request: CreateGenerationTaskRequest,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -87,32 +181,143 @@ def create_generation_task(
     project_repository: Any = Depends(get_project_repository),
     asset_library_repository: Any = Depends(get_asset_library_repository),
     asset_repository: Any = Depends(get_asset_repository),
-) -> GenerationTaskResponse:
-    project = project_repository.find_by_id(request.project_id)
-    if project is None:
-        raise HTTPException(status_code=404, detail=f"Project {request.project_id} not found")
-    if not project.can_access(authenticated_user.user.id):
-        raise HTTPException(status_code=403, detail="Access denied to project")
-    
-    library = asset_library_repository.get(request.asset_library_id)
-    if library is None or library.project_id != request.project_id:
-        raise HTTPException(status_code=404, detail=f"AssetLibrary {request.asset_library_id} not found")
-    
-    assets = asset_repository.list_by_library(request.asset_library_id)
-    _ensure_library_has_ready_video_assets(assets)
+) -> BatchGenerationTaskResponse:
+    logger.info(
+        "[生成任务] 接收请求: user_id=%s, template_id=%s, asset_count=%d, mode=%s, count=%d",
+        authenticated_user.user.id,
+        request.template_id,
+        len(request.asset_ids),
+        request.asset_select_mode,
+        request.count,
+    )
+
+    try:
+        project_id, asset_library_id = _resolve_project_and_library(
+            request, project_repository, asset_library_repository, asset_repository, authenticated_user
+        )
+    except HTTPException as e:
+        logger.warning("[生成任务] 校验失败: %s", e.detail)
+        raise
+
+    # asset_library 存在性校验（仅在提供了 asset_library_id 时）
+    resolved_asset_ids: list[str] = list(request.asset_ids)
+    if asset_library_id:
+        library = asset_library_repository.get(asset_library_id)
+        if library is None or (project_id and library.project_id != project_id):
+            logger.warning("[生成任务] 素材库不存在: library_id=%s", asset_library_id)
+            raise HTTPException(status_code=404, detail=f"AssetLibrary {asset_library_id} not found")
+
+        assets = asset_repository.find_by_library(asset_library_id)
+        try:
+            _ensure_library_has_ready_video_assets(assets)
+        except HTTPException as e:
+            logger.warning("[生成任务] 素材校验失败: %s", e.detail)
+            raise
+
+        # 素材库自动匹配：当未显式指定 asset_ids 时，按模式自动选取
+        if not resolved_asset_ids:
+            resolved_asset_ids = _select_assets_from_library(
+                assets,
+                mode=request.asset_select_mode,
+                count=request.asset_select_count,
+            )
 
     use_case = CreateGenerationTaskUseCase(generation_task_repository)
-    task = use_case.execute(
-        CreateGenerationTaskCommand(
-            project_id=request.project_id,
-            asset_library_id=request.asset_library_id,
-            strategy_id=request.strategy_id,
-            voice_library_id=request.voice_library_id,
-            created_by_user_id=authenticated_user.user.id,
-        )
-    )
-    celery_app.send_task("worker.generate_video", args=[task.id])
-    return _to_generation_task_response(task)
+    count = request.count
+    created_tasks = []
+    failed_tasks = []
+    user_id = authenticated_user.user.id
+    # 同批次任务共享 batch_id，用于视频查重时批次内比对
+    batch_id = uuid.uuid4().hex if count > 1 else ""
+
+    # 预检查：批量提交前先看会不会超限，避免建一半才拒
+    try:
+        user_pending = generation_task_repository.count_pending_by_user(user_id)
+        global_pending = generation_task_repository.count_pending_total()
+        if user_pending + count > USER_PENDING_LIMIT:
+            raise UserPendingLimitExceeded(
+                user_id=user_id, pending_count=user_pending + count, limit=USER_PENDING_LIMIT
+            )
+        if global_pending + count > GLOBAL_PENDING_LIMIT:
+            raise GlobalQueueFull(pending_count=global_pending + count, limit=GLOBAL_PENDING_LIMIT)
+    except UserPendingLimitExceeded as e:
+        raise HTTPException(
+            status_code=429,
+            detail=f"您的待处理任务过多（当前 {e.pending_count - count}/{e.limit}，本次提交 {count} 个），请等待完成后再提交",
+        ) from e
+    except GlobalQueueFull as e:
+        raise HTTPException(
+            status_code=503,
+            detail="系统繁忙，请稍后再试",
+        ) from e
+
+    try:
+        for _ in range(count):
+            task = use_case.execute(
+                CreateGenerationTaskCommand(
+                    project_id=project_id,
+                    asset_library_id=asset_library_id,
+                    strategy_id=request.strategy_id,
+                    voice_library_id=request.voice_library_id,
+                    template_id=request.template_id,
+                    asset_ids=resolved_asset_ids,
+                    title_ids=request.title_ids,
+                    voice_ids=request.voice_ids,
+                    created_by_user_id=user_id,
+                    source_edit_plan_id=request.source_edit_plan_id,
+                    asset_select_mode=request.asset_select_mode,
+                    batch_id=batch_id,
+                    auto_retry_enabled=request.auto_retry_enabled,
+                    auto_retry_max=request.auto_retry_max,
+                )
+            )
+            try:
+                if safe_enqueue_generation_task(
+                    task,
+                    generation_task_repository,
+                    user_id=user_id,
+                    log_prefix="[生成任务]",
+                    log_task_status=True,
+                ):
+                    created_tasks.append(task)
+                else:
+                    failed_tasks.append(task)
+            except UserPendingLimitExceeded:
+                # 兜底：如果预检查后又并发提交了，在这里也拦住
+                failed_tasks.append(task)
+                if not created_tasks:
+                    raise HTTPException(
+                        status_code=429,
+                        detail="您的待处理任务过多，请等待完成后再提交",
+                    )
+                break
+            except GlobalQueueFull:
+                failed_tasks.append(task)
+                if not created_tasks:
+                    raise HTTPException(
+                        status_code=503,
+                        detail="系统繁忙，请稍后再试",
+                    )
+                break
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("[生成任务] 创建失败: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail="创建生成任务失败，请稍后重试或查看任务日志")
+
+    items = [_to_generation_task_response(t) for t in created_tasks + failed_tasks]
+    return BatchGenerationTaskResponse(items=items, total=len(items))
+
+
+@router.get("/tasks", response_model=ListGenerationTasksResponse)
+def list_generation_tasks(
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    generation_task_repository: Any = Depends(get_generation_task_repository),
+) -> ListGenerationTasksResponse:
+    """用户级生成任务列表（跨 project）。"""
+    tasks = generation_task_repository.list_by_user(authenticated_user.user.id)
+    items = [_to_generation_task_response(task) for task in tasks]
+    return ListGenerationTasksResponse(items=items)
 
 
 @router.get("/tasks/{task_id}", response_model=GenerationTaskResponse)
@@ -126,7 +331,8 @@ def get_generation_task(
     task = use_case.execute(task_id)
     if task is None:
         raise HTTPException(status_code=404, detail=f"GenerationTask {task_id} not found")
-    _check_project_access(task.project_id, authenticated_user.user.id, project_repository)
+    if task.project_id:
+        check_project_access(task.project_id, authenticated_user.user.id, project_repository)
     return _to_generation_task_response(task)
 
 
@@ -137,11 +343,86 @@ def list_generation_results(
     generation_task_repository: Any = Depends(get_generation_task_repository),
     generated_video_repository: Any = Depends(get_generated_video_repository),
     project_repository: Any = Depends(get_project_repository),
+    storage_service: OSSStorageService = Depends(get_storage_service),
 ) -> ListGeneratedVideosResponse:
     task = generation_task_repository.get(task_id)
     if task is None:
         raise HTTPException(status_code=404, detail=f"GenerationTask {task_id} not found")
-    _check_project_access(task.project_id, authenticated_user.user.id, project_repository)
+    if task.project_id:
+        check_project_access(task.project_id, authenticated_user.user.id, project_repository)
     use_case = ListGeneratedVideosByTaskUseCase(generated_video_repository)
     items = use_case.execute(task_id)
-    return ListGeneratedVideosResponse(items=[_to_generated_video_response(item) for item in items])
+    responses = []
+    for item in items:
+        download_url = storage_service.get_download_url(item.file_url, expires_seconds=86400)
+        responses.append(_to_generated_video_response(item, download_url=download_url))
+    return ListGeneratedVideosResponse(items=responses)
+
+
+@router.post("/tasks/{task_id}/retry", response_model=GenerationTaskResponse)
+def retry_generation_task(
+    task_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    generation_task_repository: Any = Depends(get_generation_task_repository),
+) -> GenerationTaskResponse:
+    """简化重试：通过 task_id 直接重试失败任务。"""
+    task = generation_task_repository.get(task_id)
+    if task is None:
+        raise HTTPException(status_code=404, detail="Generation task not found")
+    if task.created_by_user_id and task.created_by_user_id != authenticated_user.user.id:
+        raise HTTPException(status_code=403, detail="Access denied to this task")
+    status_val = task.status.value if hasattr(task.status, "value") else str(task.status)
+    if status_val != "failed":
+        raise HTTPException(status_code=409, detail="Only failed tasks can be retried")
+
+    user_id = authenticated_user.user.id
+    # 预检查：创建前判断，>= 上限就拒绝
+    user_pending = generation_task_repository.count_pending_by_user(user_id)
+    global_pending = generation_task_repository.count_pending_total()
+    if user_pending >= USER_PENDING_LIMIT:
+        raise HTTPException(
+            status_code=429,
+            detail=f"您的待处理任务过多（当前 {user_pending}/{USER_PENDING_LIMIT}），请等待完成后再提交",
+        )
+    if global_pending >= GLOBAL_PENDING_LIMIT:
+        raise HTTPException(
+            status_code=503,
+            detail="系统繁忙，请稍后再试",
+        )
+
+    use_case = CreateGenerationTaskUseCase(generation_task_repository)
+    retried = use_case.execute(
+        CreateGenerationTaskCommand(
+            project_id=task.project_id,
+            asset_library_id=task.asset_library_id,
+            strategy_id=task.strategy_id,
+            voice_library_id=task.voice_library_id,
+            template_id=task.template_id,
+            asset_ids=task.asset_ids,
+            title_ids=task.title_ids,
+            voice_ids=task.voice_ids,
+            created_by_user_id=user_id,
+            source_edit_plan_id=task.source_edit_plan_id or "",
+            asset_select_mode=getattr(task, "asset_select_mode", ""),
+        )
+    )
+    try:
+        if not safe_enqueue_generation_task(
+            retried,
+            generation_task_repository,
+            user_id=user_id,
+            log_prefix="[生成任务]",
+            log_task_status=True,
+        ):
+            logger.warning("[生成任务] 重试入队失败: task_id=%s", retried.id)
+    except UserPendingLimitExceeded:
+        raise HTTPException(
+            status_code=429,
+            detail="您的待处理任务过多，请等待完成后再提交",
+        ) from None
+    except GlobalQueueFull:
+        raise HTTPException(
+            status_code=503,
+            detail="系统繁忙，请稍后再试",
+        ) from None
+    return _to_generation_task_response(retried)

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

@@ -5,7 +5,6 @@ import redis
 from app.config import settings
 from fastapi import APIRouter, status
 from fastapi.responses import JSONResponse
-from pydantic import BaseModel
 
 router = APIRouter(tags=["Health"])
 
@@ -21,19 +20,8 @@ async def health_check():
 
 @router.get("/ready", status_code=status.HTTP_200_OK)
 async def readiness_check():
-    checks = {
-        "database": await _check_database(),
-        "redis": await _check_redis(),
-    }
-    all_healthy = all(check["status"] == "healthy" for check in checks.values())
-    response = {
-        "status": "ready" if all_healthy else "not_ready",
-        "timestamp": datetime.utcnow().isoformat(),
-        "checks": checks,
-    }
-    if not all_healthy:
-        return JSONResponse(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, content=response)
-    return response
+    """简单的就绪检查，仅返回状态。详细健康检查请使用 /health 端点。"""
+    return {"status": "ready"}
 
 
 @router.get("/startup", status_code=status.HTTP_200_OK)
@@ -97,6 +85,38 @@ async def _check_redis() -> dict:
         }
 
 
+def _check_oss() -> dict:
+    try:
+        from app.core.storage import get_storage_service
+
+        svc = get_storage_service()
+        if not svc.access_key_id or not svc.access_key_secret:
+            return {
+                "status": "unhealthy",
+                "type": "oss",
+                "message": "OSS credentials not configured (OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET missing)",
+            }
+        if svc.bucket is None:
+            return {
+                "status": "unhealthy",
+                "type": "oss",
+                "message": "OSS SDK (oss2) not installed or bucket client init failed",
+            }
+        # Try a lightweight OSS API call to verify connectivity & credentials
+        svc.bucket.get_bucket_info()
+        return {
+            "status": "healthy",
+            "type": "oss",
+            "message": f"OSS connected: endpoint={svc.endpoint} bucket={svc.bucket_name}",
+        }
+    except Exception as error:
+        return {
+            "status": "unhealthy",
+            "type": "oss",
+            "message": f"OSS check failed: {type(error).__name__}: {error}",
+        }
+
+
 async def _check_migrations() -> dict:
     if settings.USE_IN_MEMORY_DB:
         return {

apps/api/app/api/routes/internal_render.py

@@ -0,0 +1,120 @@
+"""渲染结果内部下载接口。
+
+通过内部 API Key 鉴权，为灰度对比工具等内部系统提供渲染结果下载能力。
+
+API:
+  GET  /api/v1/internal/render/videos/{video_id}/download-url  - 获取单个视频下载URL
+  GET  /api/v1/internal/render/tasks/{task_id}/videos          - 获取任务下所有视频及下载URL
+
+鉴权：X-API-Key header，走内部 API Key 验证
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.api.routes.auth import _verify_internal_api_key
+from app.core.storage import OSSStorageService, get_storage_service
+from app.dependencies import get_generated_video_repository
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/internal/render", tags=["Internal"])
+
+
+class InternalRenderVideoItem(BaseModel):
+    """内部渲染视频项。"""
+
+    video_id: str
+    generation_task_id: str
+    project_id: str
+    name: str
+    file_url: str
+    file_size: int | None = None
+    duration: float | None = None
+    width: int | None = None
+    height: int | None = None
+    fps: float | None = None
+    status: str
+    download_url: str
+
+
+class InternalRenderTaskVideosResponse(BaseModel):
+    """任务下所有渲染视频响应。"""
+
+    task_id: str
+    count: int
+    videos: list[InternalRenderVideoItem]
+
+
+class InternalRenderDownloadUrlResponse(BaseModel):
+    """单个视频下载URL响应。"""
+
+    video_id: str
+    download_url: str
+
+
+def _video_to_item(video: Any, download_url: str) -> InternalRenderVideoItem:
+    """将 GeneratedVideo 领域对象转为响应项。"""
+    return InternalRenderVideoItem(
+        video_id=video.id,
+        generation_task_id=video.generation_task_id,
+        project_id=video.project_id,
+        name=video.name,
+        file_url=video.file_url,
+        file_size=getattr(video, "file_size", None),
+        duration=getattr(video, "duration", None),
+        width=getattr(video, "width", None),
+        height=getattr(video, "height", None),
+        fps=getattr(video, "fps", None),
+        status=video.status,
+        download_url=download_url,
+    )
+
+
+@router.get("/videos/{video_id}/download-url", response_model=InternalRenderDownloadUrlResponse)
+def get_render_video_download_url(
+    video_id: str,
+    _: bool = Depends(_verify_internal_api_key),
+    generated_video_repository: Any = Depends(get_generated_video_repository),
+    storage_service: OSSStorageService = Depends(get_storage_service),
+) -> InternalRenderDownloadUrlResponse:
+    """获取单个渲染视频的下载URL（预签名）。"""
+    video = generated_video_repository.get(video_id)
+    if video is None:
+        raise HTTPException(status_code=404, detail=f"GeneratedVideo {video_id} not found")
+
+    download_url = storage_service.get_download_url(video.file_url, expires_seconds=86400)
+    logger.info("内部渲染下载URL生成: video_id=%s", video_id)
+    return InternalRenderDownloadUrlResponse(video_id=video_id, download_url=download_url)
+
+
+@router.get("/tasks/{task_id}/videos", response_model=InternalRenderTaskVideosResponse)
+def get_render_task_videos(
+    task_id: str,
+    status: str | None = Query(None, description="按状态筛选，如 completed/failed"),
+    _: bool = Depends(_verify_internal_api_key),
+    generated_video_repository: Any = Depends(get_generated_video_repository),
+    storage_service: OSSStorageService = Depends(get_storage_service),
+) -> InternalRenderTaskVideosResponse:
+    """获取生成任务下所有渲染视频及下载URL。"""
+    videos = generated_video_repository.list_by_generation_task(task_id)
+
+    # 状态筛选
+    if status:
+        videos = [v for v in videos if v.status == status]
+
+    items = []
+    for video in videos:
+        download_url = storage_service.get_download_url(video.file_url, expires_seconds=86400)
+        items.append(_video_to_item(video, download_url))
+
+    logger.info("内部渲染任务视频查询: task_id=%s count=%d", task_id, len(items))
+    return InternalRenderTaskVideosResponse(
+        task_id=task_id,
+        count=len(items),
+        videos=items,
+    )

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

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

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

@@ -7,11 +7,12 @@ from app.schemas.project import (
     ListProjectsResponse,
     ProjectResponse,
 )
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, Response, status
 
 from packages.application import (
     CreateProjectCommand,
     CreateProjectUseCase,
+    DeleteProjectUseCase,
     GetProjectUseCase,
     ListProjectsUseCase,
 )
@@ -22,8 +23,10 @@ router = APIRouter()
 def _to_project_response(item) -> ProjectResponse:
     return ProjectResponse(
         id=item.id,
+        owner_user_id=item.owner_user_id,
         name=item.name,
         description=item.description,
+        shared_users=item.shared_users,
     )
 
 
@@ -37,6 +40,8 @@ def get_project(
     project = use_case.execute(project_id)
     if project is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+    if not project.can_access(authenticated_user.user.id):
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied to project")
     return _to_project_response(project)
 
 
@@ -65,3 +70,22 @@ def create_project(
         owner_user_id=authenticated_user.user.id,
     )
     return _to_project_response(project)
+
+
+@router.delete("/{project_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
+def delete_project(
+    project_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    project_repository: Any = Depends(get_project_repository),
+) -> dict:
+    use_case = DeleteProjectUseCase(project_repository)
+    try:
+        deleted = use_case.execute(project_id, authenticated_user.user.id)
+    except PermissionError:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Only the project owner can delete this project",
+        )
+    if not deleted:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+    return

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

@@ -1,12 +1,11 @@
 """Subscription management API routes."""
+
 from __future__ import annotations
 
 from dataclasses import replace
 from datetime import datetime, timezone
 from typing import List
 
-from fastapi import APIRouter, Depends, HTTPException, status
-
 from app.auth import AuthenticatedUser, get_current_user
 from app.dependencies import get_user_repository
 from app.schemas.subscription import (
@@ -17,6 +16,8 @@ from app.schemas.subscription import (
     SubscriptionInfo,
     ToggleAutoRenewRequest,
 )
+from fastapi import APIRouter, Depends, HTTPException, status
+
 from packages.ports.user_repository import UserRepository
 
 router = APIRouter()
@@ -34,6 +35,7 @@ PLAN_QUOTAS = {
 
 # ============ Helper Functions ============
 
+
 def _get_plan_name(plan_id: str) -> str:
     """获取套餐显示名称"""
     plan_names = {
@@ -86,10 +88,11 @@ def _build_subscription_info(user: AuthenticatedUser) -> SubscriptionInfo:
 
 # ============ API Endpoints ============
 
+
 @router.get("/current", response_model=SubscriptionInfo)
 async def get_current_subscription(
     current_user: AuthenticatedUser = Depends(get_current_user),
-):
+) -> SubscriptionInfo:
     """获取当前订阅信息"""
     return _build_subscription_info(current_user)
 
@@ -97,10 +100,33 @@ async def get_current_subscription(
 @router.get("/billing-records", response_model=List[BillingRecord])
 async def get_billing_records(
     current_user: AuthenticatedUser = Depends(get_current_user),
-):
+) -> List[BillingRecord]:
     """获取账单记录列表"""
-    # TODO: 从数据库查询账单记录
-    return []
+    from packages.adapters.sqlalchemy_impl.billing_repository import SQLAlchemyBillingRepository
+    from packages.adapters.sqlalchemy_impl.session import SessionLocal
+
+    if SessionLocal is None:
+        return []
+
+    session = SessionLocal()
+    try:
+        repo = SQLAlchemyBillingRepository(session)
+        records = repo.find_by_user(current_user.user.id)
+        return [
+            BillingRecord(
+                id=r.id,
+                plan_name=r.plan_name,
+                amount=r.amount,
+                billing_cycle=r.billing_cycle,
+                status=r.status,
+                payment_method=r.payment_method or "未支付",
+                created_at=r.created_at.isoformat() if r.created_at else "",
+                invoice_url=r.invoice_url,
+            )
+            for r in records
+        ]
+    finally:
+        session.close()
 
 
 @router.post("/change-plan", response_model=ChangePlanResponse)
@@ -108,7 +134,7 @@ async def change_plan(
     request: ChangePlanRequest,
     current_user: AuthenticatedUser = Depends(get_current_user),
     user_repository: UserRepository = Depends(get_user_repository),
-):
+) -> ChangePlanResponse:
     """变更订阅套餐（升级/降级）"""
     # TODO: 接入支付验证（支付宝/微信支付）
     valid_plans = {"free", "standard", "pro", "enterprise"}
@@ -160,7 +186,7 @@ async def change_plan(
 async def cancel_subscription(
     current_user: AuthenticatedUser = Depends(get_current_user),
     user_repository: UserRepository = Depends(get_user_repository),
-):
+) -> SimpleResponse:
     """取消订阅"""
     user = current_user.user
     if user.subscription_plan == "free":
@@ -178,11 +204,66 @@ async def cancel_subscription(
     )
 
 
+@router.post("/payment-callback")
+async def payment_callback(
+    user_id: str,
+    plan: str,
+    billing_cycle: str,
+    amount: float,
+    payment_method: str = "alipay",
+    payment_id: str = "",
+) -> dict:
+    """支付回调 - 在事务中更新账单和订阅状态
+
+    注意：生产环境需要验证支付签名
+    """
+    import uuid
+    from datetime import timedelta
+
+    from packages.adapters.sqlalchemy_impl.billing_repository import SQLAlchemyBillingRepository
+    from packages.adapters.sqlalchemy_impl.session import SessionLocal
+
+    if SessionLocal is None:
+        raise HTTPException(status_code=500, detail="Database not available")
+
+    session = SessionLocal()
+    try:
+        repo = SQLAlchemyBillingRepository(session)
+
+        # 创建账单记录
+        record_id = uuid.uuid4().hex
+        repo.create(
+            {
+                "id": record_id,
+                "user_id": user_id,
+                "plan_name": _get_plan_name(plan),
+                "amount": amount,
+                "billing_cycle": billing_cycle,
+                "status": "pending",
+            }
+        )
+
+        # 在事务中标记支付成功并更新订阅
+        repo.mark_paid(record_id, payment_method, payment_id)
+
+        # 计算到期时间
+        days = 365 if billing_cycle == "yearly" else 30
+        expires_at = datetime.now(timezone.utc) + timedelta(days=days)
+        repo.update_subscription_on_payment(user_id, plan, expires_at)
+
+        return {"success": True, "message": "支付成功", "record_id": record_id}
+    except Exception as e:
+        session.rollback()
+        raise HTTPException(status_code=500, detail=f"支付处理失败: {str(e)}")
+    finally:
+        session.close()
+
+
 @router.post("/toggle-auto-renew", response_model=SimpleResponse)
 async def toggle_auto_renew(
     request: ToggleAutoRenewRequest,
     current_user: AuthenticatedUser = Depends(get_current_user),
-):
+) -> SimpleResponse:
     """切换自动续费"""
     # TODO: 实际需要在数据库中存储 auto_renew 字段
     status_text = "已开启自动续费" if request.enabled else "已关闭自动续费"

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

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

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

@@ -1,24 +1,43 @@
+import logging
 from typing import Any
 
 from app.auth import AuthenticatedUser, get_current_user
 from app.core.celery_app import celery_app
+from app.core.task_enqueue import (
+    GLOBAL_PENDING_LIMIT,
+    USER_PENDING_LIMIT,
+    GlobalQueueFull,
+    UserPendingLimitExceeded,
+    safe_enqueue_generation_task,
+)
 from app.dependencies import (
     get_generation_task_repository,
     get_ingest_job_repository,
     get_project_repository,
 )
-from app.schemas.task_center import ListProjectTasksResponse, ProjectTaskResponse
-from fastapi import APIRouter, Depends, HTTPException
+from app.schemas.task_center import (
+    ListProjectTasksResponse,
+    ListTasksResponse,
+    ProjectTaskResponse,
+    UserTaskResponse,
+)
+from fastapi import APIRouter, Depends, HTTPException, Query
 
 from packages.application import (
     CreateGenerationTaskCommand,
     CreateGenerationTaskUseCase,
+    RetryGenerationTaskUseCase,
     SubmitIngestJobCommand,
     SubmitIngestJobUseCase,
 )
 
+logger = logging.getLogger(__name__)
+
 router = APIRouter()
 
+DEFAULT_PAGE_SIZE = 50
+MAX_PAGE_SIZE = 200
+
 
 def _humanize_task_error(error_message: str) -> str:
     raw = (error_message or "").strip()
@@ -34,79 +53,260 @@ def _humanize_task_error(error_message: str) -> str:
     return f"任务失败：{raw}"
 
 
+def _status_value(status) -> str:
+    """安全获取状态值（兼容 StrEnum 和 plain string）。"""
+    return status.value if hasattr(status, "value") else str(status)
+
+
 def _generation_step(task) -> str:
-    if task.status.value == "pending":
+    s = _status_value(task.status)
+    if s == "pending":
         return "等待 Worker 执行"
-    if task.status.value == "running":
+    if s == "running":
         return "正在生成成片"
-    if task.status.value == "completed":
+    if s == "completed":
         return "生成完成"
-    if task.status.value == "failed":
+    if s == "failed":
         return "生成失败"
-    return task.status.value
+    if s == "cancelled":
+        return "已取消"
+    return s
 
 
 def _ingest_step(job) -> str:
-    if job.status.value == "pending":
+    s = _status_value(job.status)
+    if s == "pending":
         return "等待导入"
-    if job.status.value == "processing":
+    if s == "processing":
         return "正在分析素材"
-    if job.status.value == "completed":
+    if s == "completed":
         return "导入完成"
-    if job.status.value == "failed":
+    if s == "failed":
         return "导入失败"
-    return job.status.value
+    return s
+
+
+def _generation_task_to_user_response(task) -> UserTaskResponse:
+    return UserTaskResponse(
+        id=f"generation:{task.id}",
+        task_type="generation",
+        project_id=task.project_id,
+        template_id=task.template_id,
+        status=_status_value(task.status),
+        progress=task.progress,
+        current_step=_generation_step(task),
+        error_message=task.error_message,
+        error_info=task.error_info or {},
+        user_message=_humanize_task_error(task.error_message),
+        retryable=_status_value(task.status) == "failed",
+        retry_count=task.retry_count or 0,
+        source_id=task.id,
+        created_at=task.created_at,
+        updated_at=task.completed_at or task.started_at or task.created_at,
+    )
+
+
+def _generation_task_to_project_response(task) -> ProjectTaskResponse:
+    return ProjectTaskResponse(
+        id=f"generation:{task.id}",
+        task_type="generation",
+        project_id=task.project_id,
+        status=_status_value(task.status),
+        progress=task.progress,
+        current_step=_generation_step(task),
+        error_message=task.error_message,
+        error_info=task.error_info or {},
+        user_message=_humanize_task_error(task.error_message),
+        retryable=_status_value(task.status) == "failed",
+        retry_count=task.retry_count or 0,
+        source_id=task.id,
+        template_id=task.template_id,
+        created_at=task.created_at,
+        updated_at=task.completed_at or task.started_at or task.created_at,
+    )
+
+
+def _validate_status(status: str | None) -> str | None:
+    """校验状态值合法性。"""
+    if status is None:
+        return None
+    valid = {"pending", "running", "completed", "failed", "cancelled"}
+    if status not in valid:
+        raise HTTPException(
+            status_code=400,
+            detail=f"无效的状态筛选值: {status}，允许值: {', '.join(sorted(valid))}",
+        )
+    return status
+
+
+def _clamp_page_size(page_size: int) -> int:
+    if page_size <= 0:
+        return DEFAULT_PAGE_SIZE
+    if page_size > MAX_PAGE_SIZE:
+        return MAX_PAGE_SIZE
+    return page_size
+
+
+# ── 用户级端点（放在项目级端点之前，避免路由冲突） ──
+
+
+@router.get("/tasks", response_model=ListTasksResponse)
+def list_user_tasks(
+    status: str | None = Query(None, description="按状态筛选：pending/running/completed/failed/cancelled"),
+    task_type: str | None = Query(None, description="按任务类型筛选：generation/ingest"),
+    page: int = Query(1, ge=1, description="页码，从1开始"),
+    page_size: int = Query(DEFAULT_PAGE_SIZE, ge=1, le=MAX_PAGE_SIZE, description="每页数量"),
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    ingest_job_repository: Any = Depends(get_ingest_job_repository),
+    generation_task_repository: Any = Depends(get_generation_task_repository),
+) -> ListTasksResponse:
+    """用户级任务列表（跨 project），支持状态/类型筛选和分页。"""
+    status = _validate_status(status)
+    page_size = _clamp_page_size(page_size)
+    user_id = authenticated_user.user.id
+    offset = (page - 1) * page_size
+
+    items: list[UserTaskResponse] = []
+
+    # 生成任务
+    if task_type is None or task_type == "generation":
+        gen_result = generation_task_repository.list_by_user_filtered(
+            user_id,
+            status=status,
+            limit=page_size + 1,  # 多取一条判断是否还有下一页（简单起见这里用offset）
+            offset=offset,
+        )
+        for task in gen_result:
+            items.append(_generation_task_to_user_response(task))
+
+    # 按时间倒序
+    items.sort(key=lambda item: item.updated_at or item.created_at or "", reverse=True)
+
+    # 总数（仅generation，ingest暂不计入总数以保持简单）
+    total = generation_task_repository.count_by_user_filtered(user_id, status=status)
+
+    return ListTasksResponse(items=items[:page_size], total=total)
+
+
+@router.post("/tasks/{task_id}/retry", response_model=UserTaskResponse)
+def retry_task_by_id(
+    task_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    generation_task_repository: Any = Depends(get_generation_task_repository),
+) -> UserTaskResponse:
+    """原地重试失败的生成任务（复用同一个task_id，retry_count+1）。"""
+    task = generation_task_repository.get(task_id)
+    if task is None:
+        raise HTTPException(status_code=404, detail="Generation task not found")
+    if task.created_by_user_id and task.created_by_user_id != authenticated_user.user.id:
+        raise HTTPException(status_code=403, detail="Access denied to this task")
+    if _status_value(task.status) != "failed":
+        raise HTTPException(status_code=409, detail="Only failed tasks can be retried")
+
+    user_id = authenticated_user.user.id
+
+    # 预检查
+    user_pending = generation_task_repository.count_pending_by_user(user_id)
+    global_pending = generation_task_repository.count_pending_total()
+    if user_pending >= USER_PENDING_LIMIT:
+        raise HTTPException(
+            status_code=429,
+            detail=f"您的待处理任务过多（当前 {user_pending}/{USER_PENDING_LIMIT}），请等待完成后再提交",
+        )
+    if global_pending >= GLOBAL_PENDING_LIMIT:
+        raise HTTPException(
+            status_code=503,
+            detail="系统繁忙，请稍后再试",
+        )
+
+    # 原地重试
+    use_case = RetryGenerationTaskUseCase(generation_task_repository)
+    retried = use_case.execute(task_id)
+
+    # 重新入队
+    try:
+        if not safe_enqueue_generation_task(
+            retried, generation_task_repository, user_id=user_id, log_prefix="[任务中心]"
+        ):
+            logger.warning("[任务中心] 用户级重试入队失败: task_id=%s", retried.id)
+    except UserPendingLimitExceeded:
+        raise HTTPException(
+            status_code=429,
+            detail="您的待处理任务过多，请等待完成后再提交",
+        ) from None
+    except GlobalQueueFull:
+        raise HTTPException(
+            status_code=503,
+            detail="系统繁忙，请稍后再试",
+        ) from None
+
+    return _generation_task_to_user_response(retried)
+
+
+# ── 项目级端点 ──
 
 
 @router.get("/projects/{project_id}/tasks", response_model=ListProjectTasksResponse)
 def list_project_tasks(
     project_id: str,
+    status: str | None = Query(None, description="按状态筛选：pending/running/completed/failed/cancelled"),
+    task_type: str | None = Query(None, description="按任务类型筛选：generation/ingest"),
+    page: int = Query(1, ge=1, description="页码，从1开始"),
+    page_size: int = Query(DEFAULT_PAGE_SIZE, ge=1, le=MAX_PAGE_SIZE, description="每页数量"),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     project_repository: Any = Depends(get_project_repository),
     ingest_job_repository: Any = Depends(get_ingest_job_repository),
     generation_task_repository: Any = Depends(get_generation_task_repository),
 ) -> ListProjectTasksResponse:
+    """项目级任务列表，支持状态/类型筛选和分页。"""
     project = project_repository.find_by_id(project_id)
     if project is None:
         raise HTTPException(status_code=404, detail="Project not found")
 
+    status = _validate_status(status)
+    page_size = _clamp_page_size(page_size)
+    offset = (page - 1) * page_size
+
     items: list[ProjectTaskResponse] = []
-    for job in ingest_job_repository.list_by_project(project_id):
-        items.append(
-            ProjectTaskResponse(
-                id=f"ingest:{job.id}",
-                task_type="ingest",
-                project_id=job.project_id,
-                status=job.status.value,
-                progress=100.0 if job.status.value == "completed" else 0.0,
-                current_step=_ingest_step(job),
-                error_message=job.error_message,
-                user_message=_humanize_task_error(job.error_message),
-                retryable=job.status.value == "failed",
-                source_id=job.id,
-                created_at=job.created_at,
-                updated_at=job.updated_at,
-            )
-        )
-    for task in generation_task_repository.list_by_project(project_id):
-        items.append(
-            ProjectTaskResponse(
-                id=f"generation:{task.id}",
-                task_type="generation",
-                project_id=task.project_id,
-                status=task.status.value,
-                progress=task.progress,
-                current_step=_generation_step(task),
-                error_message=task.error_message,
-                user_message=_humanize_task_error(task.error_message),
-                retryable=task.status.value == "failed",
-                source_id=task.id,
-                created_at=task.created_at,
-                updated_at=task.completed_at or task.started_at or task.created_at,
+
+    # 导入任务
+    if task_type is None or task_type == "ingest":
+        for job in ingest_job_repository.list_by_project(project_id):
+            if status and _status_value(job.status) != status:
+                continue
+            items.append(
+                ProjectTaskResponse(
+                    id=f"ingest:{job.id}",
+                    task_type="ingest",
+                    project_id=job.project_id,
+                    status=_status_value(job.status),
+                    progress=100.0 if _status_value(job.status) == "completed" else 0.0,
+                    current_step=_ingest_step(job),
+                    error_message=job.error_message,
+                    user_message=_humanize_task_error(job.error_message),
+                    retryable=_status_value(job.status) == "failed",
+                    source_id=job.id,
+                    created_at=job.created_at,
+                    updated_at=job.updated_at,
+                )
             )
+
+    # 生成任务
+    if task_type is None or task_type == "generation":
+        gen_items = generation_task_repository.list_by_project_filtered(
+            project_id,
+            status=status,
+            limit=page_size + 1,
+            offset=offset,
         )
+        for task in gen_items:
+            items.append(_generation_task_to_project_response(task))
+
     items.sort(key=lambda item: item.updated_at or item.created_at or "", reverse=True)
-    return ListProjectTasksResponse(items=items)
+
+    total = generation_task_repository.count_by_project_filtered(project_id, status=status)
+
+    return ListProjectTasksResponse(items=items[:page_size], total=total)
 
 
 @router.post("/tasks/{task_type}/{source_id}/retry", response_model=ProjectTaskResponse)
@@ -117,40 +317,56 @@ def retry_project_task(
     ingest_job_repository: Any = Depends(get_ingest_job_repository),
     generation_task_repository: Any = Depends(get_generation_task_repository),
 ) -> ProjectTaskResponse:
+    """项目级任务重试。"""
     if task_type == "generation":
         task = generation_task_repository.get(source_id)
         if task is None:
             raise HTTPException(status_code=404, detail="Generation task not found")
-        if task.status.value != "failed":
+        if _status_value(task.status) != "failed":
             raise HTTPException(status_code=409, detail="Only failed tasks can be retried")
-        use_case = CreateGenerationTaskUseCase(generation_task_repository)
-        retried = use_case.execute(
-            CreateGenerationTaskCommand(
-                project_id=task.project_id,
-                asset_library_id=task.asset_library_id,
-                strategy_id=task.strategy_id,
-                voice_library_id=task.voice_library_id,
-                edit_plan_id=task.edit_plan_id,
-                created_by_user_id=authenticated_user.user.id,
+
+        user_id = authenticated_user.user.id
+
+        # 预检查
+        user_pending = generation_task_repository.count_pending_by_user(user_id)
+        global_pending = generation_task_repository.count_pending_total()
+        if user_pending >= USER_PENDING_LIMIT:
+            raise HTTPException(
+                status_code=429,
+                detail=f"您的待处理任务过多（当前 {user_pending}/{USER_PENDING_LIMIT}），请等待完成后再提交",
             )
-        )
-        celery_app.send_task("worker.generate_video", args=[retried.id])
-        return ProjectTaskResponse(
-            id=f"generation:{retried.id}",
-            task_type="generation",
-            project_id=retried.project_id,
-            status=retried.status.value,
-            progress=retried.progress,
-            current_step=_generation_step(retried),
-            source_id=retried.id,
-            created_at=retried.created_at,
-            updated_at=retried.created_at,
-        )
+        if global_pending >= GLOBAL_PENDING_LIMIT:
+            raise HTTPException(
+                status_code=503,
+                detail="系统繁忙，请稍后再试",
+            )
+
+        # 原地重试
+        use_case = RetryGenerationTaskUseCase(generation_task_repository)
+        retried = use_case.execute(source_id)
+
+        try:
+            if not safe_enqueue_generation_task(
+                retried, generation_task_repository, user_id=user_id, log_prefix="[任务中心]"
+            ):
+                logger.warning("[任务中心] 项目级重试入队失败: task_id=%s", retried.id)
+        except UserPendingLimitExceeded:
+            raise HTTPException(
+                status_code=429,
+                detail="您的待处理任务过多，请等待完成后再提交",
+            ) from None
+        except GlobalQueueFull:
+            raise HTTPException(
+                status_code=503,
+                detail="系统繁忙，请稍后再试",
+            ) from None
+        return _generation_task_to_project_response(retried)
+
     if task_type == "ingest":
         job = ingest_job_repository.get(source_id)
         if job is None:
             raise HTTPException(status_code=404, detail="Ingest job not found")
-        if job.status.value != "failed":
+        if _status_value(job.status) != "failed":
             raise HTTPException(status_code=409, detail="Only failed tasks can be retried")
         use_case = SubmitIngestJobUseCase(ingest_job_repository)
         retried = use_case.execute(
@@ -165,7 +381,7 @@ def retry_project_task(
             id=f"ingest:{retried.id}",
             task_type="ingest",
             project_id=retried.project_id,
-            status=retried.status.value,
+            status=_status_value(retried.status),
             progress=0,
             current_step=_ingest_step(retried),
             source_id=retried.id,

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

@@ -0,0 +1,408 @@
+"""Template CRUD + generate + category routes."""
+
+from __future__ import annotations
+
+import logging
+
+from app.auth import AuthenticatedUser, get_current_user
+from app.dependencies import get_db_session
+from app.schemas.template import (
+    CategoryResponse,
+    CopyTemplateRequest,
+    CreateCategoryRequest,
+    CreateTemplateRequest,
+    GenerateWarningResponse,
+    ListCategoriesResponse,
+    ListTagsResponse,
+    ListTemplatesResponse,
+    SegmentResponse,
+    TemplateResponse,
+    TemplateUsageResponse,
+    ToggleFavoriteResponse,
+    UpdateTemplateRequest,
+    ValidateTemplateRequest,
+    ValidateTemplateResponse,
+)
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from sqlalchemy.orm import Session
+
+logger = logging.getLogger(__name__)
+
+from packages.adapters.sqlalchemy_impl.template_repository import SQLAlchemyTemplateRepository
+from packages.application.template.commands import (
+    CopyTemplateCommand,
+    CreateCategoryCommand,
+    CreateTemplateCommand,
+    ListTemplatesFilter,
+    SegmentCommand,
+    UpdateTemplateCommand,
+    ValidateTemplateCommand,
+)
+from packages.application.template.use_cases import (
+    CopyTemplateUseCase,
+    CountTemplatesUseCase,
+    CreateCategoryUseCase,
+    CreateTemplateUseCase,
+    DeleteCategoryUseCase,
+    DeleteTemplateUseCase,
+    GetTemplateUseCase,
+    ListCategoriesUseCase,
+    ListTagsUseCase,
+    ListTemplatesUseCase,
+    NotFoundError,
+    UpdateTemplateUseCase,
+    ValidateTemplateUseCase,
+    ValidationError,
+)
+
+router = APIRouter()
+
+
+def _get_template_repository(session: Session = Depends(get_db_session)) -> SQLAlchemyTemplateRepository:
+    return SQLAlchemyTemplateRepository(session)
+
+
+def _segment_to_response(seg) -> SegmentResponse:
+    return SegmentResponse(
+        id=seg.id,
+        template_id=seg.template_id,
+        segment_order=seg.segment_order,
+        duration_min=seg.duration_min,
+        duration_max=seg.duration_max,
+        material_type=seg.material_type,
+        created_at=seg.created_at,
+        updated_at=seg.updated_at,
+    )
+
+
+def _to_response(template, usage_count: int = 0) -> TemplateResponse:
+    return TemplateResponse(
+        id=template.id,
+        user_id=template.user_id,
+        name=template.name,
+        mode=template.mode,
+        category=template.category,
+        tags=template.tags,
+        title_config=template.title_config,
+        subtitle_config=template.subtitle_config,
+        bgm_config=template.bgm_config,
+        estimated_duration=template.estimated_duration,
+        segments=[_segment_to_response(s) for s in getattr(template, "segments", [])],
+        is_active=template.is_active,
+        usage_count=usage_count,
+        created_at=template.created_at,
+        updated_at=template.updated_at,
+    )
+
+
+# ── Template CRUD ──
+
+
+@router.get("", response_model=ListTemplatesResponse)
+def list_templates(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(50, ge=1, le=200),
+    category: str | None = Query(None, description="按分类筛选"),
+    tag: str | None = Query(None, description="按标签筛选"),
+    keyword: str | None = Query(None, description="按名称关键词搜索"),
+    mode: str | None = Query(None, description="按剪辑模式筛选"),
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> ListTemplatesResponse:
+    user_id = authenticated_user.user.id
+    try:
+        tpl_filter = ListTemplatesFilter(
+            category=category,
+            tag=tag,
+            keyword=keyword,
+            mode=mode,
+        )
+        use_case = ListTemplatesUseCase(template_repository)
+        templates = use_case.execute(user_id, skip=skip, limit=limit, filter=tpl_filter)
+        count_use_case = CountTemplatesUseCase(template_repository)
+        total = count_use_case.execute(user_id, filter=tpl_filter)
+
+        # 批量查询使用次数
+        items = []
+        for t in templates:
+            usage = template_repository.get_usage_count(t.id)
+            items.append(_to_response(t, usage_count=usage))
+    except Exception:
+        logger.exception("list_templates 查询失败: user_id=%s", user_id)
+        return ListTemplatesResponse(items=[], total=0)
+    return ListTemplatesResponse(
+        items=items,
+        total=total,
+    )
+
+
+@router.get("/{template_id}", response_model=TemplateResponse)
+def get_template(
+    template_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> TemplateResponse:
+    user_id = authenticated_user.user.id
+    try:
+        use_case = GetTemplateUseCase(template_repository)
+        template = use_case.execute(template_id, user_id)
+        usage = template_repository.get_usage_count(template_id)
+    except Exception:
+        logger.exception("get_template 查询失败: template_id=%s", template_id)
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="模板查询失败")
+    if template is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
+    return _to_response(template, usage_count=usage)
+
+
+@router.post("", response_model=TemplateResponse, status_code=status.HTTP_201_CREATED)
+def create_template(
+    request: CreateTemplateRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> TemplateResponse:
+    user_id = authenticated_user.user.id
+    command = CreateTemplateCommand(
+        user_id=user_id,
+        name=request.name,
+        mode=request.mode,
+        category=request.category,
+        tags=request.tags,
+        title_config=request.title_config,
+        subtitle_config=request.subtitle_config,
+        bgm_config=request.bgm_config,
+        estimated_duration=request.estimated_duration,
+        segments=[
+            SegmentCommand(
+                segment_order=s.segment_order,
+                duration_min=s.duration_min,
+                duration_max=s.duration_max,
+                material_type=s.material_type,
+            )
+            for s in request.segments
+        ],
+    )
+    use_case = CreateTemplateUseCase(template_repository)
+    try:
+        template = use_case.execute(command)
+    except ValidationError as exc:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc))
+    return _to_response(template)
+
+
+@router.patch("/{template_id}", response_model=TemplateResponse)
+def update_template(
+    template_id: str,
+    request: UpdateTemplateRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> TemplateResponse:
+    user_id = authenticated_user.user.id
+    command = UpdateTemplateCommand(
+        template_id=template_id,
+        user_id=user_id,
+        name=request.name,
+        mode=request.mode,
+        category=request.category,
+        tags=request.tags,
+        title_config=request.title_config,
+        subtitle_config=request.subtitle_config,
+        bgm_config=request.bgm_config,
+        estimated_duration=request.estimated_duration,
+        segments=(
+            [
+                SegmentCommand(
+                    segment_order=s.segment_order,
+                    duration_min=s.duration_min,
+                    duration_max=s.duration_max,
+                    material_type=s.material_type,
+                )
+                for s in request.segments
+            ]
+            if request.segments is not None
+            else None
+        ),
+    )
+    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 ValidationError as exc:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc))
+    return _to_response(template)
+
+
+@router.delete("/{template_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
+def delete_template(
+    template_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> Response:
+    user_id = authenticated_user.user.id
+    use_case = DeleteTemplateUseCase(template_repository)
+    deleted = use_case.execute(template_id, user_id)
+    if not deleted:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
+    return
+
+
+@router.post("/{template_id}/copy", response_model=TemplateResponse, status_code=status.HTTP_201_CREATED)
+def copy_template(
+    template_id: str,
+    request: CopyTemplateRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> TemplateResponse:
+    """复制模板（含所有片段配置）"""
+    user_id = authenticated_user.user.id
+    command = CopyTemplateCommand(
+        template_id=template_id,
+        user_id=user_id,
+        new_name=request.new_name,
+    )
+    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 ValidationError as exc:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc))
+    return _to_response(template)
+
+
+@router.get("/{template_id}/usage", response_model=TemplateUsageResponse)
+def get_template_usage(
+    template_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> TemplateUsageResponse:
+    """获取模板使用次数（关联的剪辑计划数量）"""
+    user_id = authenticated_user.user.id
+    # 鉴权：确保模板存在且属于当前用户
+    use_case = GetTemplateUseCase(template_repository)
+    template = use_case.execute(template_id, user_id)
+    if template is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
+    usage = template_repository.get_usage_count(template_id)
+    return TemplateUsageResponse(template_id=template_id, usage_count=usage)
+
+
+@router.post("/{template_id}/toggle-favorite", response_model=ToggleFavoriteResponse)
+def toggle_favorite(
+    template_id: str,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> ToggleFavoriteResponse:
+    """切换模板收藏状态（当前为兼容端点，始终返回 false）"""
+    user_id = authenticated_user.user.id
+    use_case = GetTemplateUseCase(template_repository)
+    try:
+        template = use_case.execute(template_id, user_id)
+    except Exception:
+        logger.exception("toggle_favorite 查询失败: template_id=%s", template_id)
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
+    if template is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
+    return ToggleFavoriteResponse(id=template_id, is_favorite=False)
+
+
+# ── Validate template ──
+
+
+@router.post("/{template_id}/validate", response_model=ValidateTemplateResponse)
+def validate_template(
+    template_id: str,
+    request: ValidateTemplateRequest = ValidateTemplateRequest(),
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> ValidateTemplateResponse:
+    user_id = authenticated_user.user.id
+    command = ValidateTemplateCommand(
+        template_id=template_id,
+        user_id=user_id,
+        voiceover_duration=request.voiceover_duration,
+    )
+    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 ValidationError as exc:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc))
+
+    return ValidateTemplateResponse(
+        template=_to_response(result.template),
+        warnings=[GenerateWarningResponse(code=w.code, message=w.message, details=w.details) for w in result.warnings],
+    )
+
+
+# ── Category CRUD ──
+
+
+@router.get("/categories/list", response_model=ListCategoriesResponse)
+def list_categories(
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> ListCategoriesResponse:
+    user_id = authenticated_user.user.id
+    try:
+        use_case = ListCategoriesUseCase(template_repository)
+        categories = use_case.execute(user_id)
+    except Exception:
+        logger.exception("list_categories 查询失败: user_id=%s", user_id)
+        return ListCategoriesResponse(items=[])
+    return ListCategoriesResponse(
+        items=[CategoryResponse(id=c.id, user_id=c.user_id, name=c.name, created_at=c.created_at) for c in categories],
+    )
+
+
+@router.post("/categories", response_model=CategoryResponse, status_code=status.HTTP_201_CREATED)
+def create_category(
+    request: CreateCategoryRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> CategoryResponse:
+    user_id = authenticated_user.user.id
+    command = CreateCategoryCommand(user_id=user_id, name=request.name)
+    use_case = CreateCategoryUseCase(template_repository)
+    category = use_case.execute(command)
+    return CategoryResponse(
+        id=category.id,
+        user_id=category.user_id,
+        name=category.name,
+        created_at=category.created_at,
+    )
+
+
+@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),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> Response:
+    user_id = authenticated_user.user.id
+    use_case = DeleteCategoryUseCase(template_repository)
+    deleted = use_case.execute(category_id, user_id)
+    if not deleted:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Category not found")
+    return Response(status_code=204)
+
+
+# ── Tags ──
+
+
+@router.get("/tags/list", response_model=ListTagsResponse)
+def list_tags(
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    template_repository: SQLAlchemyTemplateRepository = Depends(_get_template_repository),
+) -> ListTagsResponse:
+    """获取用户所有模板标签（去重排序）"""
+    user_id = authenticated_user.user.id
+    try:
+        use_case = ListTagsUseCase(template_repository)
+        tags = use_case.execute(user_id)
+    except Exception:
+        logger.exception("list_tags 查询失败: user_id=%s", user_id)
+        return ListTagsResponse(items=[])
+    return ListTagsResponse(items=tags)

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

@@ -1,10 +1,10 @@
 """Title library CRUD routes."""
+
 from __future__ import annotations
 
 from typing import Optional
 
-from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
-
+from app.api.routes._helpers import get_user_plan
 from app.auth import AuthenticatedUser, get_current_user
 from app.dependencies import get_db_session, get_user_repository
 from app.schemas.title_library import (
@@ -13,19 +13,26 @@ from app.schemas.title_library import (
     TitleLibraryItemResponse,
     UpdateTitleLibraryRequest,
 )
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from sqlalchemy.orm import Session
+
 from packages.adapters.sqlalchemy_impl.title_library_repository import SQLAlchemyTitleLibraryRepository
-from packages.application.title_library.commands import CreateTitleLibraryCommand, UpdateTitleLibraryCommand
+from packages.application.title_library.commands import (
+    CreateTitleLibraryCommand,
+    PickTitleCommand,
+    UpdateTitleLibraryCommand,
+)
 from packages.application.title_library.use_cases import (
     CreateTitleLibraryUseCase,
     DeleteTitleLibraryUseCase,
     GetTitleLibraryUseCase,
     ListTitleLibraryUseCase,
-    UpdateTitleLibraryUseCase,
     NotFoundError,
+    PickTitleUseCase,
     QuotaExceededError,
+    UpdateTitleLibraryUseCase,
 )
 from packages.ports.user_repository import UserRepository
-from sqlalchemy.orm import Session
 
 router = APIRouter()
 
@@ -50,13 +57,6 @@ def _to_response(item) -> TitleLibraryItemResponse:
     )
 
 
-def _get_user_plan(user_id: str, user_repository: UserRepository) -> str:
-    user = user_repository.find_by_id(user_id)
-    if user is None:
-        return "free"
-    return getattr(user, "subscription_plan", "free") or "free"
-
-
 @router.get("", response_model=ListTitleLibraryResponse)
 def list_titles(
     category: Optional[str] = Query(None),
@@ -75,6 +75,41 @@ def list_titles(
     )
 
 
+@router.post("/pick", response_model=TitleLibraryItemResponse)
+def pick_title(
+    category: Optional[str] = Query(None, description="按分类筛选，不填则从全部标题中选"),
+    exclude_ids: Optional[str] = Query(
+        None,
+        description="排除的标题ID（逗号分隔），用于批量生成时避免重复",
+    ),
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    title_repository: SQLAlchemyTitleLibraryRepository = Depends(_get_title_repository),
+) -> TitleLibraryItemResponse:
+    """智能选择一个标题。
+
+    策略：优先使用次数少的，从最少的前5个中随机选一个，兼顾公平和多样性。
+    """
+    user_id = authenticated_user.user.id
+    exclude_list: list[str] = []
+    if exclude_ids:
+        exclude_list = [t.strip() for t in exclude_ids.split(",") if t.strip()]
+
+    use_case = PickTitleUseCase(title_repository)
+    item = use_case.execute(
+        PickTitleCommand(
+            user_id=user_id,
+            category=category,
+            exclude_ids=exclude_list,
+        )
+    )
+    if item is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="标题库为空，请先添加标题",
+        )
+    return _to_response(item)
+
+
 @router.get("/{title_id}", response_model=TitleLibraryItemResponse)
 def get_title(
     title_id: str,
@@ -97,7 +132,7 @@ def create_title(
     user_repository: UserRepository = Depends(get_user_repository),
 ) -> TitleLibraryItemResponse:
     user_id = authenticated_user.user.id
-    plan_name = _get_user_plan(user_id, user_repository)
+    plan_name = get_user_plan(user_id, user_repository)
     command = CreateTitleLibraryCommand(
         user_id=user_id,
         name=request.name,
@@ -142,7 +177,7 @@ def update_title(
     return _to_response(item)
 
 
-@router.delete("/{title_id}", status_code=status.HTTP_204_NO_CONTENT, response_class=Response)
+@router.delete("/{title_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
 def delete_title(
     title_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -153,4 +188,4 @@ def delete_title(
     deleted = use_case.execute(title_id, user_id)
     if not deleted:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Title not found")
-    return Response(status_code=204)
+    return

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

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

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

@@ -1,12 +1,15 @@
+import logging
 from typing import Any
 from uuid import uuid4
 
+from app.api.routes._helpers import require_project_and_library
 from app.auth import AuthenticatedUser, get_current_user
 from app.config import get_settings
 from app.core.celery_app import celery_app
 from app.core.storage import OSSStorageService, get_storage_service
 from app.dependencies import (
     get_asset_library_repository,
+    get_asset_repository,
     get_ingest_job_repository,
     get_project_repository,
 )
@@ -15,29 +18,46 @@ from app.schemas.upload import (
     DirectUploadCompleteResponse,
     DirectUploadPrepareRequest,
     DirectUploadPrepareResponse,
-    UploadAssetRequest,
     UploadAssetResponse,
 )
-from typing import Annotated
-
 from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile, status
 
-from packages.application import GetProjectUseCase, SubmitIngestJobCommand, SubmitIngestJobUseCase
+from packages.application import SubmitIngestJobCommand, SubmitIngestJobUseCase
+
+logger = logging.getLogger(__name__)
 
 router = APIRouter()
 
 # 允许上传的文件 MIME 类型
-ALLOWED_MIME_TYPES = frozenset({
-    # 视频
-    "video/mp4", "video/mpeg", "video/quicktime", "video/x-msvideo",
-    "video/webm", "video/x-matroska", "video/3gpp",
-    # 音频
-    "audio/mpeg", "audio/wav", "audio/ogg", "audio/flac", "audio/aac",
-    "audio/mp3", "audio/x-m4a", "audio/webm",
-    # 图片
-    "image/jpeg", "image/png", "image/gif", "image/webp", "image/bmp",
-    "image/svg+xml", "image/tiff",
-})
+ALLOWED_MIME_TYPES = frozenset(
+    {
+        # 视频
+        "video/mp4",
+        "video/mpeg",
+        "video/quicktime",
+        "video/x-msvideo",
+        "video/webm",
+        "video/x-matroska",
+        "video/3gpp",
+        # 音频
+        "audio/mpeg",
+        "audio/wav",
+        "audio/ogg",
+        "audio/flac",
+        "audio/aac",
+        "audio/mp3",
+        "audio/x-m4a",
+        "audio/webm",
+        # 图片
+        "image/jpeg",
+        "image/png",
+        "image/gif",
+        "image/webp",
+        "image/bmp",
+        "image/tiff",
+        "image/svg+xml",
+    }
+)
 
 
 def _validate_mime_type(content_type: str | None) -> str:
@@ -47,39 +67,25 @@ def _validate_mime_type(content_type: str | None) -> str:
             status_code=status.HTTP_400_BAD_REQUEST,
             detail="Content-Type header is required",
         )
-    
+
     # 处理带参数的类型，如 "video/mp4; charset=utf-8"
     base_type = content_type.split(";")[0].strip().lower()
-    
+
     if base_type not in ALLOWED_MIME_TYPES:
         raise HTTPException(
             status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
             detail=f"File type '{base_type}' is not supported. Allowed types: video, audio, and image files.",
         )
-    
+
     return base_type
 
 
-def _require_project_and_library(
-    project_id: str,
-    library_id: str,
-    project_repository: Any,
-    asset_library_repository: Any,
-) -> None:
-    project = GetProjectUseCase(project_repository).execute(project_id)
-    if project is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
-
-    libraries = asset_library_repository.list_by_project(project_id)
-    if not any(item.id == library_id for item in libraries):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Asset library not found")
-
-
 def _submit_ingest_job(
     project_id: str,
     library_id: str,
     storage_key: str,
     ingest_job_repository: Any,
+    file_hash: str = "",
 ) -> Any:
     use_case = SubmitIngestJobUseCase(ingest_job_repository)
     job = use_case.execute(
@@ -87,6 +93,7 @@ def _submit_ingest_job(
             project_id=project_id,
             library_id=library_id,
             storage_key=storage_key,
+            file_hash=file_hash,
         )
     )
     celery_app.send_task("worker.ingest_asset", args=[job.id])
@@ -113,7 +120,7 @@ async def prepare_direct_upload(
     # P2-5: 服务端验证 MIME 类型
     validated_content_type = _validate_mime_type(request.content_type)
 
-    _require_project_and_library(
+    require_project_and_library(
         request.project_id,
         request.library_id,
         project_repository,
@@ -131,7 +138,14 @@ async def prepare_direct_upload(
             expires_seconds=settings.OSS_DIRECT_UPLOAD_EXPIRE_SECONDS,
         )
     except RuntimeError as error:
+        logger.error("OSS not configured for direct upload prepare: %s", error)
         raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(error)) from error
+    except Exception as error:
+        logger.exception("Unexpected error in direct upload prepare: %s", error)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to prepare upload: {type(error).__name__}",
+        ) from error
 
     return DirectUploadPrepareResponse(
         upload_url=str(payload["url"]),
@@ -150,10 +164,11 @@ async def complete_direct_upload(
     ingest_job_repository: Any = Depends(get_ingest_job_repository),
     project_repository: Any = Depends(get_project_repository),
     asset_library_repository: Any = Depends(get_asset_library_repository),
+    asset_repository: Any = Depends(get_asset_repository),
     storage_service: OSSStorageService = Depends(get_storage_service),
 ) -> DirectUploadCompleteResponse:
     """确认浏览器直传完成并创建导入任务。"""
-    _require_project_and_library(
+    require_project_and_library(
         request.project_id,
         request.library_id,
         project_repository,
@@ -162,14 +177,43 @@ async def complete_direct_upload(
     normalized_key = storage_service._normalize_storage_key(request.storage_key)
     if not normalized_key.startswith("uploads/"):
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid upload key")
-    if not storage_service.file_exists(normalized_key):
+    try:
+        file_exists = storage_service.file_exists(normalized_key)
+    except Exception as error:
+        logger.exception("OSS error checking file existence for key=%s: %s", normalized_key, error)
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Storage service unavailable",
+        ) from error
+    if not file_exists:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Uploaded file not found")
 
+    # ── 素材去重检测：同素材库 + 同 file_hash 视为重复 ──
+    if request.file_hash:
+        existing = asset_repository.find_by_library_and_file_hash(
+            library_id=request.library_id,
+            file_hash=request.file_hash,
+        )
+        if existing is not None:
+            logger.info(
+                "素材去重命中: library=%s hash=%s existing_asset=%s",
+                request.library_id,
+                request.file_hash,
+                existing.id,
+            )
+            return DirectUploadCompleteResponse(
+                storage_key=normalized_key,
+                ingest_job_id="",
+                duplicated=True,
+                asset_id=existing.id,
+            )
+
     job = _submit_ingest_job(
         project_id=request.project_id,
         library_id=request.library_id,
         storage_key=normalized_key,
         ingest_job_repository=ingest_job_repository,
+        file_hash=request.file_hash,
     )
     return DirectUploadCompleteResponse(storage_key=normalized_key, ingest_job_id=job.id)
 
@@ -181,18 +225,40 @@ async def complete_direct_upload(
     description="上传素材文件（multipart/form-data），支持视频、音频、图片。触发导入流水线自动处理。",
 )
 async def upload_asset(
-    form_data: Annotated[UploadAssetRequest, Form()],
+    project_id: str = Form(..., min_length=1, description="项目 ID"),
+    library_id: str = Form(..., min_length=1, description="素材库 ID"),
     file: UploadFile = File(..., description="要上传的文件（视频、音频、图片等）"),
+    file_hash: str = Form(default="", description="文件 MD5 哈希，用于去重检测"),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     ingest_job_repository: Any = Depends(get_ingest_job_repository),
     project_repository: Any = Depends(get_project_repository),
     asset_library_repository: Any = Depends(get_asset_library_repository),
+    asset_repository: Any = Depends(get_asset_repository),
     storage_service: OSSStorageService = Depends(get_storage_service),
 ) -> UploadAssetResponse:
     """上传素材文件并触发导入流水线。"""
-    project_id = form_data.project_id
-    library_id = form_data.library_id
-    _require_project_and_library(project_id, library_id, project_repository, asset_library_repository)
+    require_project_and_library(project_id, library_id, project_repository, asset_library_repository)
+
+    # ── 素材去重检测：上传前检查同素材库 + 同 file_hash ──
+    if file_hash:
+        existing = asset_repository.find_by_library_and_file_hash(
+            library_id=library_id,
+            file_hash=file_hash,
+        )
+        if existing is not None:
+            logger.info(
+                "素材去重命中(multipart): library=%s hash=%s existing_asset=%s",
+                library_id,
+                file_hash,
+                existing.id,
+            )
+            return UploadAssetResponse(
+                storage_key=existing.storage_key,
+                ingest_job_id="",
+                url="",
+                duplicated=True,
+                asset_id=existing.id,
+            )
 
     # P2-5: 服务端验证 MIME 类型
     validated_content_type = _validate_mime_type(file.content_type)
@@ -201,17 +267,28 @@ async def upload_asset(
     safe_filename = file.filename.replace("/", "_").replace("\\", "_") if file.filename else "unknown"
     storage_key = f"uploads/{file_id}/{safe_filename}"
 
-    file_url = storage_service.upload_file(
-        file.file,
-        storage_key,
-        content_type=validated_content_type,
-    )
+    try:
+        file_url = storage_service.upload_file(
+            file.file,
+            storage_key,
+            content_type=validated_content_type,
+        )
+    except RuntimeError as error:
+        logger.error("OSS not configured for upload: %s", error)
+        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(error)) from error
+    except Exception as error:
+        logger.exception("Unexpected error uploading file to OSS: %s", error)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to upload file: {type(error).__name__}",
+        ) from error
 
     job = _submit_ingest_job(
         project_id=project_id,
         library_id=library_id,
         storage_key=storage_key,
         ingest_job_repository=ingest_job_repository,
+        file_hash=file_hash,
     )
 
     return UploadAssetResponse(

apps/api/app/api/routes/videos.py

@@ -0,0 +1,179 @@
+import logging
+import uuid
+
+from app.api.routes._helpers import check_project_access
+from app.auth import AuthenticatedUser, get_current_user
+from app.core.celery_app import celery_app
+from app.core.storage import OSSStorageService, get_storage_service
+from app.dependencies import get_generated_video_repository
+from app.schemas.video_center import (
+    BatchDownloadRequest,
+    BatchDownloadResponse,
+    ListVideosResponse,
+    UpdateVideoReviewRequest,
+    VideoItemResponse,
+)
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from packages.application import (
+    GetGeneratedVideoUseCase,
+    GetVideosByIdsUseCase,
+    ListGeneratedVideosPaginatedUseCase,
+    UpdateVideoReviewStatusUseCase,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def _to_video_response(item, storage: OSSStorageService | None = None) -> VideoItemResponse:
+    download_url = None
+    if storage and item.file_url:
+        try:
+            download_url = storage.get_download_url(item.file_url)
+        except Exception:
+            download_url = item.file_url
+    return VideoItemResponse(
+        id=item.id,
+        project_id=item.project_id,
+        generation_task_id=item.generation_task_id,
+        name=item.name,
+        file_url=item.file_url,
+        file_size=item.file_size,
+        duration=item.duration,
+        thumbnail_url=item.thumbnail_url,
+        width=item.width,
+        height=item.height,
+        fps=item.fps,
+        status=item.status,
+        review_status=item.review_status,
+        generation_params=item.generation_params,
+        download_url=download_url,
+        generated_at=item.generated_at.isoformat() if hasattr(item, "generated_at") and item.generated_at else "",
+    )
+
+
+@router.get("/videos", response_model=ListVideosResponse)
+def list_videos(
+    project_id: str | None = Query(None, description="项目ID，不传则返回所有项目"),
+    status: str | None = Query(None, description="按状态筛选"),
+    review_status: str | None = Query(None, description="按复核状态筛选"),
+    page: int = Query(1, ge=1, description="页码"),
+    page_size: int = Query(20, ge=1, le=100, description="每页数量"),
+    repo=Depends(get_generated_video_repository),
+    storage: OSSStorageService = Depends(get_storage_service),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+):
+    """成片列表，支持分页、按项目/状态/复核状态筛选。"""
+    use_case = ListGeneratedVideosPaginatedUseCase(repo)
+    items, total = use_case.execute(
+        project_id=project_id,
+        status=status,
+        review_status=review_status,
+        page=page,
+        page_size=page_size,
+    )
+    return ListVideosResponse(
+        items=[_to_video_response(item, storage) for item in items],
+        total=total,
+        page=page,
+        page_size=page_size,
+    )
+
+
+@router.get("/videos/{video_id}", response_model=VideoItemResponse)
+def get_video(
+    video_id: str,
+    repo=Depends(get_generated_video_repository),
+    storage: OSSStorageService = Depends(get_storage_service),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+):
+    """获取单个成片详情。"""
+    use_case = GetGeneratedVideoUseCase(repo)
+    item = use_case.execute(video_id)
+    if item is None:
+        raise HTTPException(status_code=404, detail="Video not found")
+    return _to_video_response(item, storage)
+
+
+@router.patch("/videos/{video_id}/review", response_model=VideoItemResponse)
+def update_video_review_status(
+    video_id: str,
+    request: UpdateVideoReviewRequest,
+    repo=Depends(get_generated_video_repository),
+    storage: OSSStorageService = Depends(get_storage_service),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+):
+    """更新成片复核状态：pending_review / approved / rejected。"""
+    use_case = UpdateVideoReviewStatusUseCase(repo)
+    item = use_case.execute(video_id, request.review_status)
+    if item is None:
+        raise HTTPException(status_code=404, detail="Video not found")
+    logger.info("Video %s review status updated to %s by user %s", video_id, request.review_status, current_user.user_id)
+    return _to_video_response(item, storage)
+
+
+@router.post("/videos/batch-download", response_model=BatchDownloadResponse)
+def batch_download_videos(
+    request: BatchDownloadRequest,
+    repo=Depends(get_generated_video_repository),
+    current_user: AuthenticatedUser = Depends(get_current_user),
+):
+    """批量下载成片，异步打包 zip。
+    
+    传入 video_ids 列表，创建一个批量下载任务，任务完成后返回 zip 下载链接。
+    """
+    if not request.video_ids:
+        raise HTTPException(status_code=400, detail="video_ids cannot be empty")
+    if len(request.video_ids) > 50:
+        raise HTTPException(status_code=400, detail="Maximum 50 videos per batch download")
+
+    # 校验视频都存在
+    use_case = GetVideosByIdsUseCase(repo)
+    videos = use_case.execute(request.video_ids)
+    if len(videos) != len(request.video_ids):
+        raise HTTPException(status_code=404, detail="Some videos not found")
+
+    # 发送 celery 任务
+    task = celery_app.send_task(
+        "worker.batch_download_videos",
+        args=[request.video_ids, current_user.user_id],
+    )
+
+    logger.info("Batch download job created: %s, videos=%d", task.id, len(request.video_ids))
+    return BatchDownloadResponse(job_id=task.id, status="pending")
+
+
+@router.get("/videos/batch-download/{job_id}", response_model=BatchDownloadResponse)
+def get_batch_download_status(
+    job_id: str,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+):
+    """查询批量下载任务状态。"""
+    from celery.result import AsyncResult
+
+    task = AsyncResult(job_id, app=celery_app)
+    
+    status_map = {
+        "PENDING": "pending",
+        "STARTED": "running",
+        "SUCCESS": "success",
+        "FAILURE": "failed",
+        "RETRY": "pending",
+        "REVOKED": "cancelled",
+    }
+    api_status = status_map.get(task.state, "pending")
+
+    download_url = None
+    if task.state == "SUCCESS" and task.result:
+        if isinstance(task.result, dict):
+            download_url = task.result.get("download_url")
+        elif isinstance(task.result, str):
+            download_url = task.result
+
+    return BatchDownloadResponse(
+        job_id=job_id,
+        status=api_status,
+        download_url=download_url,
+    )

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

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

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

@@ -1,18 +1,31 @@
-"""Voice library CRUD routes."""
+"""Voice library CRUD routes — Phase 3 增强版.
+
+支持预置音色和克隆音色的统一列表。
+"""
+
 from __future__ import annotations
 
-from typing import Optional
-
-from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from typing import Literal, Optional
 
+from app.api.routes._helpers import get_user_plan
 from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_user_repository
+from app.dependencies import get_audio_url_signer, get_db_session, get_user_repository
+from app.schemas.voice import (
+    PresetVoiceItemResponse,
+    PresetVoiceListResponse,
+    UnifiedVoiceItemResponse,
+    UnifiedVoiceListResponse,
+)
 from app.schemas.voice_library import (
     CreateVoiceLibraryRequest,
     ListVoiceLibraryResponse,
-    VoiceLibraryItemResponse,
     UpdateVoiceLibraryRequest,
+    VoiceLibraryItemResponse,
 )
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.voice_clone_profile_repository import SQLAlchemyVoiceCloneProfileRepository
 from packages.adapters.sqlalchemy_impl.voice_library_repository import SQLAlchemyVoiceLibraryRepository
 from packages.application.voice_library.commands import CreateVoiceLibraryCommand, UpdateVoiceLibraryCommand
 from packages.application.voice_library.use_cases import (
@@ -20,12 +33,12 @@ from packages.application.voice_library.use_cases import (
     DeleteVoiceLibraryUseCase,
     GetVoiceLibraryUseCase,
     ListVoiceLibraryUseCase,
-    UpdateVoiceLibraryUseCase,
     NotFoundError,
     QuotaExceededError,
+    UpdateVoiceLibraryUseCase,
 )
+from packages.domain.preset_voices import PRESET_VOICES
 from packages.ports.user_repository import UserRepository
-from sqlalchemy.orm import Session
 
 router = APIRouter()
 
@@ -34,7 +47,14 @@ def _get_voice_repository(session: Session = Depends(get_db_session)) -> SQLAlch
     return SQLAlchemyVoiceLibraryRepository(session)
 
 
-def _to_response(item) -> VoiceLibraryItemResponse:
+def _get_clone_profile_repository(session: Session = Depends(get_db_session)) -> SQLAlchemyVoiceCloneProfileRepository:
+    return SQLAlchemyVoiceCloneProfileRepository(session)
+
+
+def _to_response(item, sign_url=None) -> VoiceLibraryItemResponse:
+    audio = item.audio_url
+    if sign_url and audio:
+        audio = sign_url(audio)
     return VoiceLibraryItemResponse(
         id=item.id,
         user_id=item.user_id,
@@ -43,7 +63,7 @@ def _to_response(item) -> VoiceLibraryItemResponse:
         voice_provider=item.voice_provider,
         voice_id=item.voice_id,
         voice_name=item.voice_name,
-        audio_url=item.audio_url,
+        audio_url=audio,
         duration=item.duration,
         file_size=item.file_size,
         status=item.status,
@@ -54,27 +74,169 @@ def _to_response(item) -> VoiceLibraryItemResponse:
     )
 
 
-def _get_user_plan(user_id: str, user_repository: UserRepository) -> str:
-    user = user_repository.find_by_id(user_id)
-    if user is None:
-        return "free"
-    return getattr(user, "subscription_plan", "free") or "free"
+def _to_unified_response(item, profile_id_map: dict | None = None, sign_url=None) -> UnifiedVoiceItemResponse:
+    """将数据库音色转换为统一响应格式。
+
+    Args:
+        item: VoiceLibraryItem
+        profile_id_map: voice_id → profile_id 映射，用于填充 voice_clone_profile_id
+        sign_url: 音频URL预签名函数
+    """
+    profile_id = None
+    if profile_id_map and item.voice_id:
+        profile_id = profile_id_map.get(item.voice_id)
+    audio = item.audio_url
+    if sign_url and audio:
+        audio = sign_url(audio)
+    return UnifiedVoiceItemResponse(
+        id=item.id,
+        type="clone",
+        name=item.name,
+        description=item.text,
+        gender="unknown",
+        language="zh-CN",
+        voice_id=item.voice_id,
+        voice_provider=item.voice_provider or "cosyvoice",
+        audio_url=audio,
+        duration=item.duration,
+        file_size=item.file_size,
+        status=item.status,
+        tags=item.tags,
+        user_id=item.user_id,
+        project_id=item.project_id,
+        voice_clone_profile_id=profile_id,
+        created_at=item.created_at,
+        updated_at=item.updated_at,
+    )
 
 
-@router.get("", response_model=ListVoiceLibraryResponse)
-def list_voices(
+def _preset_to_unified_response(preset) -> UnifiedVoiceItemResponse:
+    """将预置音色转换为统一响应格式。"""
+    return UnifiedVoiceItemResponse(
+        id=preset.voice_id,
+        type="preset",
+        name=preset.name,
+        description=preset.description,
+        gender=preset.gender,
+        language=preset.language,
+        voice_id=preset.voice_id,
+        voice_provider="cosyvoice",
+        preview_url=preset.preview_url,
+        tags=preset.tags or [],
+    )
+
+
+# ==================== 统一配音列表（预置 + 克隆）====================
+
+
+@router.get("", response_model=UnifiedVoiceListResponse)
+def list_voices_unified(
+    type: Optional[Literal["preset", "clone"]] = Query(
+        None,
+        description="音色类型过滤：preset=仅预置，clone=仅克隆，不传=全部",
+    ),
     status_filter: Optional[str] = Query(None, alias="status"),
     skip: int = Query(0, ge=0),
     limit: int = Query(50, ge=1, le=200),
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     voice_repository: SQLAlchemyVoiceLibraryRepository = Depends(_get_voice_repository),
+    clone_profile_repository: SQLAlchemyVoiceCloneProfileRepository = Depends(_get_clone_profile_repository),
+    sign_url=Depends(get_audio_url_signer),
+) -> UnifiedVoiceListResponse:
+    """获取配音列表（预置音色 + 用户克隆音色）。
+
+    - 不传 type：返回预置音色 + 用户克隆音色，预置音色在前
+    - type=preset：仅返回预置音色
+    - type=clone：仅返回用户克隆音色
+    """
+    user_id = authenticated_user.user.id
+    items: list[UnifiedVoiceItemResponse] = []
+    preset_count = 0
+    clone_count = 0
+
+    has_preset = type is None or type == "preset"
+    has_clone = type is None or type == "clone"
+
+    # 获取预置音色
+    if has_preset:
+        preset_items = [_preset_to_unified_response(p) for p in PRESET_VOICES]
+        preset_count = len(preset_items)
+
+    # 获取克隆音色
+    if has_clone:
+        use_case = ListVoiceLibraryUseCase(voice_repository)
+        clone_items_raw, clone_count = use_case.execute(user_id, status=status_filter, skip=skip, limit=limit)
+        # 批量查询 voice_id → profile_id 映射，填充 voice_clone_profile_id
+        voice_ids = [i.voice_id for i in clone_items_raw if i.voice_id]
+        profile_id_map = clone_profile_repository.find_profile_ids_by_voice_ids(voice_ids) if voice_ids else {}
+        clone_items = [_to_unified_response(i, profile_id_map, sign_url) for i in clone_items_raw]
+
+    # 组装结果
+    if type == "preset":
+        items = preset_items[skip : skip + limit]
+        total = preset_count
+    elif type == "clone":
+        items = clone_items
+        total = clone_count
+    else:
+        # 全量模式：预置在前，克隆补位
+        all_items = preset_items + clone_items
+        total = preset_count + clone_count
+        items = all_items[skip : skip + limit]
+
+    return UnifiedVoiceListResponse(
+        items=items,
+        total=total,
+        preset_count=preset_count if has_preset else 0,
+        clone_count=clone_count if has_clone else 0,
+    )
+
+
+# ==================== 预置音色专用端点 ====================
+
+
+@router.get("/presets", response_model=PresetVoiceListResponse)
+def list_preset_voices() -> PresetVoiceListResponse:
+    """获取预置音色列表。
+
+    不需要认证，返回所有系统预置的 CosyVoice 音色。
+    """
+    items = [
+        PresetVoiceItemResponse(
+            voice_id=p.voice_id,
+            name=p.name,
+            description=p.description,
+            gender=p.gender,
+            language=p.language,
+            preview_url=p.preview_url,
+            tags=p.tags or [],
+        )
+        for p in PRESET_VOICES
+    ]
+    return PresetVoiceListResponse(items=items, total=len(items))
+
+
+# ==================== 原有 CRUD 端点（保持向后兼容）====================
+
+
+@router.get("/legacy", response_model=ListVoiceLibraryResponse)
+def list_voices_legacy(
+    status_filter: Optional[str] = Query(None, alias="status"),
+    skip: int = Query(0, ge=0),
+    limit: int = Query(50, ge=1, le=200),
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    voice_repository: SQLAlchemyVoiceLibraryRepository = Depends(_get_voice_repository),
+    sign_url=Depends(get_audio_url_signer),
 ) -> ListVoiceLibraryResponse:
+    """原有配音列表接口（仅返回用户克隆音色）。
+
+    保留用于向后兼容，新客户端请使用 GET /api/v1/voices。
+    """
     user_id = authenticated_user.user.id
     use_case = ListVoiceLibraryUseCase(voice_repository)
-    items = use_case.execute(user_id, status=status_filter, skip=skip, limit=limit)
-    total = voice_repository.count_by_user(user_id)
+    items, total = use_case.execute(user_id, status=status_filter, skip=skip, limit=limit)
     return ListVoiceLibraryResponse(
-        items=[_to_response(i) for i in items],
+        items=[_to_response(i, sign_url) for i in items],
         total=total,
     )
 
@@ -84,13 +246,14 @@ def get_voice(
     voice_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     voice_repository: SQLAlchemyVoiceLibraryRepository = Depends(_get_voice_repository),
+    sign_url=Depends(get_audio_url_signer),
 ) -> VoiceLibraryItemResponse:
     user_id = authenticated_user.user.id
     use_case = GetVoiceLibraryUseCase(voice_repository)
     item = use_case.execute(voice_id, user_id)
     if item is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice not found")
-    return _to_response(item)
+    return _to_response(item, sign_url)
 
 
 @router.post("", response_model=VoiceLibraryItemResponse, status_code=status.HTTP_201_CREATED)
@@ -99,9 +262,10 @@ def create_voice(
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     voice_repository: SQLAlchemyVoiceLibraryRepository = Depends(_get_voice_repository),
     user_repository: UserRepository = Depends(get_user_repository),
+    sign_url=Depends(get_audio_url_signer),
 ) -> VoiceLibraryItemResponse:
     user_id = authenticated_user.user.id
-    plan_name = _get_user_plan(user_id, user_repository)
+    plan_name = get_user_plan(user_id, user_repository)
     command = CreateVoiceLibraryCommand(
         user_id=user_id,
         name=request.name,
@@ -124,7 +288,7 @@ def create_voice(
             status_code=status.HTTP_429_TOO_MANY_REQUESTS,
             detail=f"配音库配额已满（{exc.used}/{exc.limit}），请升级套餐",
         )
-    return _to_response(item)
+    return _to_response(item, sign_url)
 
 
 @router.put("/{voice_id}", response_model=VoiceLibraryItemResponse)
@@ -133,6 +297,7 @@ def update_voice(
     request: UpdateVoiceLibraryRequest,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     voice_repository: SQLAlchemyVoiceLibraryRepository = Depends(_get_voice_repository),
+    sign_url=Depends(get_audio_url_signer),
 ) -> VoiceLibraryItemResponse:
     user_id = authenticated_user.user.id
     command = UpdateVoiceLibraryCommand(
@@ -154,10 +319,10 @@ def update_voice(
         item = use_case.execute(command)
     except NotFoundError:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice not found")
-    return _to_response(item)
+    return _to_response(item, sign_url)
 
 
-@router.delete("/{voice_id}", status_code=status.HTTP_204_NO_CONTENT, response_class=Response)
+@router.delete("/{voice_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
 def delete_voice(
     voice_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -168,4 +333,4 @@ def delete_voice(
     deleted = use_case.execute(voice_id, user_id)
     if not deleted:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice not found")
-    return Response(status_code=204)
+    return

apps/api/app/auth.py

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

apps/api/app/config.py

@@ -1,7 +1,7 @@
 import os
 from typing import Optional
 
-from pydantic import field_validator
+from pydantic import AliasChoices, Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
@@ -19,37 +19,32 @@ class Settings(BaseSettings):
     # Container bind address; external expose is controlled by Docker/Nginx.
     API_HOST: str = "0.0.0.0"  # nosec: B104
     API_PORT: int = 8000
-    API_PREFIX: str = "/api/v1"
 
-    DATABASE_URL: str = (
-        "postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas"
-    )
+    DATABASE_URL: str = "postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas"
     DATABASE_POOL_SIZE: int = 20
     DATABASE_MAX_OVERFLOW: int = 10  # 调整为合理值：pool_size(20) + max_overflow(10) = 最大30连接
     DATABASE_POOL_TIMEOUT: int = 30
-    DATABASE_POOL_RECYLE: int = 3600
+    DATABASE_POOL_RECYCLE: int = 3600
     USE_IN_MEMORY_DB: bool = False
     AUTO_CREATE_SCHEMA: bool = False
 
     REDIS_URL: str = "redis://localhost:6379/0"
-    REDIS_MAX_CONNECTION: int = 50
     ENABLE_REDIS_SESSIONS: bool = False
 
     # JWT secret key - MUST be set via environment variable, no default allowed
     JWT_SECRET_KEY: Optional[str] = None
-    # 旧的 JWT secret key（用于密钥轮换期间验证旧 token）
-    # 在密钥轮换时，先设置新密钥，旧密钥保留在此处直到所有旧 token 过期
-    JWT_SECRET_KEY_OLD: Optional[str] = None
-    # 密钥轮换天数（到达此天数后建议更换密钥）
-    SECRET_ROTATION_DAYS: int = 90
+
+    # JWT 算法与过期时间（与 .env.example 对齐）
+    JWT_ALGORITHM: str = "HS256"
+    JWT_ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+    JWT_REFRESH_TOKEN_EXPIRE_DAYS: int = 30
 
     @field_validator("JWT_SECRET_KEY", mode="before")
     @classmethod
     def validate_jwt_secret_key(cls, v):
         if v is None or v == "":
             raise ValueError(
-                "JWT_SECRET_KEY must be set via environment variable. "
-                "Do not use default value in production!"
+                "JWT_SECRET_KEY must be set via environment variable. " "Do not use default value in production!"
             )
         # Block known insecure default values
         insecure_defaults = [
@@ -61,8 +56,7 @@ class Settings(BaseSettings):
         ]
         if v.lower() in [d.lower() for d in insecure_defaults]:
             raise ValueError(
-                f"JWT_SECRET_KEY '{v}' is insecure. "
-                "Please set a strong random secret via environment variable."
+                f"JWT_SECRET_KEY '{v}' is insecure. " "Please set a strong random secret via environment variable."
             )
         return v
 
@@ -79,17 +73,41 @@ class Settings(BaseSettings):
     CELERY_RESULT_BACKEND: str = "redis://localhost:6379/1"
 
     # OSS 七牛云相关
-    OSS_ENDPOINT: str = "oss-cn-hangzhou.aliiyuncs.com"
+    OSS_ENDPOINT: str = "oss-cn-hangzhou.aliyuncs.com"
     OSS_ACCESS_KEY_ID: str = ""
     OSS_ACCESS_KEY_SECRET: str = ""
     OSS_BUCKET_NAME: str = "xiaoxia-autocut"
-    OSS_DIRECT_UPLOAD_MAX_MB: int = 800
-    OSS_DIRECT_UPLOAD_EXPRESS_SECRET: int = 900
 
-    LOG_LEVEL: str = "INFO"
-    CORS_ORIGINS_RAW: str = (
-        "http://localhost:3000,http://localhost:5173,http://localhost:8000"
+    @field_validator("OSS_ACCESS_KEY_ID", mode="before")
+    @classmethod
+    def validate_oss_access_key_id(cls, v):
+        if (v is None or v == "") and os.getenv("APP_ENV", "development") != "development":
+            raise ValueError(
+                "OSS_ACCESS_KEY_ID must be set via environment variable in non-development environments. "
+                "Check the server .env file (e.g. /var/lib/xiaoxia-saas-staging/.env)."
+            )
+        return v or ""
+
+    @field_validator("OSS_ACCESS_KEY_SECRET", mode="before")
+    @classmethod
+    def validate_oss_access_key_secret(cls, v):
+        if (v is None or v == "") and os.getenv("APP_ENV", "development") != "development":
+            raise ValueError(
+                "OSS_ACCESS_KEY_SECRET must be set via environment variable in non-development environments. "
+                "Check the server .env file (e.g. /var/lib/xiaoxia-saas-staging/.env)."
+            )
+        return v or ""
+
+    OSS_DIRECT_UPLOAD_MAX_MB: int = Field(
+        default=2000,
+        validation_alias=AliasChoices("OSS_DIRECT_UPLOAD_MAX_MB", "MAX_UPLOAD_SIZE_MB"),
     )
+    OSS_DIRECT_UPLOAD_EXPIRE_SECONDS: int = 900
+
+    CORS_ORIGINS_RAW: str = "http://localhost:3000,http://localhost:5173,http://localhost:8000"
+
+    # 渲染引擎选择：legacy=旧VideoComposeService，unified=新UnifiedRenderService
+    RENDER_ENGINE: str = "legacy"
 
     model_config = SettingsConfigDict(
         env_file=".env",
@@ -100,11 +118,7 @@ class Settings(BaseSettings):
 
     @property
     def CORS_ORIGINS(self) -> list[str]:
-        return [
-            origin.strip()
-            for origin in self.CORS_ORIGINS_RAW.split(",")
-            if origin.strip()
-        ]
+        return [origin.strip() for origin in self.CORS_ORIGINS_RAW.split(",") if origin.strip()]
 
     @property
     def database_url(self) -> str:

apps/api/app/core/__init__.py

@@ -1 +0,0 @@
-"""Core configuration package."""

apps/api/app/core/database.py

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

apps/api/app/core/storage.py

@@ -1,225 +1,14 @@
-"""阿里云 OSS 存储服务"""
+"""Backward-compatible re-export from shared storage.
 
-import base64
-import datetime as dt
-import hashlib
-import hmac
-import json
-import logging
-import os
-from urllib.parse import urlparse
+All storage logic now lives in ``packages.shared.storage``.
+This module keeps old import paths working so existing code
+does not need to change.
+"""
 
-try:
-    import oss2
-except ImportError:  # pragma: no cover - exercised in minimal local/test environments
-    oss2 = None
-from app.config import get_settings
-
-logger = logging.getLogger(__name__)
-
-
-class OSSStorageService:
-    """阿里云 OSS 存储服务"""
-
-    def __init__(self):
-        settings = get_settings()
-        self.bucket_name = settings.OSS_BUCKET_NAME
-        self.public_url = f"https://{settings.OSS_BUCKET_NAME}.{settings.OSS_ENDPOINT}"
-        self.local_url_prefix = os.getenv("GENERATED_FILES_URL_PREFIX", "/generated-files")
-        self.bucket = None
-
-        if settings.OSS_ACCESS_KEY_ID and settings.OSS_ACCESS_KEY_SECRET:
-            if oss2 is not None:
-                auth = oss2.Auth(
-                    settings.OSS_ACCESS_KEY_ID,
-                    settings.OSS_ACCESS_KEY_SECRET,
-                )
-                self.bucket = oss2.Bucket(
-                    auth,
-                    settings.OSS_ENDPOINT,
-                    settings.OSS_BUCKET_NAME,
-                )
-        self.access_key_id = settings.OSS_ACCESS_KEY_ID
-        self.access_key_secret = settings.OSS_ACCESS_KEY_SECRET
-        self.endpoint = settings.OSS_ENDPOINT
-
-    def _is_local_generated_url(self, storage_key_or_url: str) -> bool:
-        parsed = urlparse(storage_key_or_url)
-        path = parsed.path if parsed.scheme else storage_key_or_url
-        return path.startswith(f"{self.local_url_prefix}/")
-
-    def create_direct_upload_post(
-        self,
-        storage_key: str,
-        content_type: str,
-        max_size_bytes: int,
-        expires_seconds: int,
-    ) -> dict[str, object]:
-        """创建浏览器直传 OSS 的 PostObject 表单。"""
-        if not self.access_key_id or not self.access_key_secret:
-            raise RuntimeError("OSS storage is not configured")
-        normalized_key = self._normalize_storage_key(storage_key)
-        if not normalized_key.startswith("uploads/"):
-            raise ValueError("direct upload key must be under uploads/")
-
-        expiration = (dt.datetime.now(dt.timezone.utc) + dt.timedelta(seconds=expires_seconds)).strftime(
-            "%Y-%m-%dT%H:%M:%S.000Z"
-        )
-        policy = {
-            "expiration": expiration,
-            "conditions": [
-                {"bucket": self.bucket_name},
-                {"key": normalized_key},
-                ["content-length-range", 1, max_size_bytes],
-                ["starts-with", "$Content-Type", content_type.split("/", 1)[0] + "/" if "/" in content_type else ""],
-            ],
-        }
-        encoded_policy = base64.b64encode(json.dumps(policy, separators=(",", ":")).encode("utf-8")).decode("ascii")
-        signature = base64.b64encode(
-            hmac.new(self.access_key_secret.encode("utf-8"), encoded_policy.encode("utf-8"), hashlib.sha1).digest()
-        ).decode("ascii")
-
-        return {
-            "url": self.public_url,
-            "method": "POST",
-            "storage_key": normalized_key,
-            "expires_at": expiration,
-            "fields": {
-                "key": normalized_key,
-                "OSSAccessKeyId": self.access_key_id,
-                "policy": encoded_policy,
-                "Signature": signature,
-                "success_action_status": "201",
-                "Content-Type": content_type,
-            },
-        }
-
-    def upload_file(
-        self,
-        file_or_path,
-        storage_key: str,
-        content_type: str = "application/octet-stream",
-    ) -> str:
-        """
-        上传文件到 OSS
-
-        Args:
-            file_or_path: 文件对象或本地文件路径
-            storage_key: 存储键（文件路径）
-            content_type: 内容类型
-
-        Returns:
-            文件公网 URL
-        """
-        if self.bucket is None:
-            raise RuntimeError("OSS storage is not configured")
-
-        try:
-            # 如果是字符串路径，从本地文件上传
-            if isinstance(file_or_path, str):
-                self.bucket.put_object_from_file(storage_key, file_or_path, headers={"Content-Type": content_type})
-            else:
-                # 文件对象
-                file_or_path.seek(0)
-                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}")
-
-    def get_url(self, storage_key: str) -> str:
-        """获取文件公网 URL"""
-        return f"{self.public_url}/{storage_key}"
-
-    def get_download_url(self, storage_key_or_url: str, expires_seconds: int = 3600) -> str:
-        """
-        获取文件下载签名 URL（用于私有文件）
-
-        Args:
-            storage_key_or_url: 存储键或完整 URL
-            expires_seconds: 过期时间（秒）
-
-        Returns:
-            签名 URL
-        """
-        if self.bucket is None:
-            if self._is_local_generated_url(storage_key_or_url):
-                return storage_key_or_url
-            return self.get_url(self._normalize_storage_key(storage_key_or_url))
-
-        storage_key = self._normalize_storage_key(storage_key_or_url)
-        try:
-            return self.bucket.sign_url("GET", storage_key, expires_seconds)
-        except Exception:
-            return self.get_url(storage_key)
-
-    def _normalize_storage_key(self, storage_key_or_url: str) -> str:
-        """从 URL 中提取存储键"""
-        if storage_key_or_url.startswith("http://") or storage_key_or_url.startswith("https://"):
-            parsed = urlparse(storage_key_or_url)
-            # 移除开头的 /
-            return parsed.path.lstrip("/")
-        return storage_key_or_url.lstrip("/")
-
-    def download_file(self, storage_key: str, local_path: str):
-        """
-        从 OSS 下载文件到本地
-
-        Args:
-            storage_key: 存储键
-            local_path: 本地文件路径
-        """
-        if self.bucket is None:
-            raise RuntimeError("OSS storage is not configured")
-
-        try:
-            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}")
-
-    def delete_file(self, storage_key: str):
-        """
-        删除 OSS 文件
-
-        Args:
-            storage_key: 存储键
-        """
-        if self.bucket is None:
-            return
-
-        try:
-            self.bucket.delete_object(storage_key)
-        except Exception as error:
-            logger.warning(
-                "Failed to delete file from OSS",
-                extra={"storage_key": storage_key, "error": str(error)},
-            )
-
-    def file_exists(self, storage_key: str) -> bool:
-        """
-        检查文件是否存在
-
-        Args:
-            storage_key: 存储键
-
-        Returns:
-            是否存在
-        """
-        if self.bucket is None:
-            return False
-        return self.bucket.object_exists(storage_key)
-
-
-
-
-_storage_service = None
-
-
-def get_storage_service() -> OSSStorageService:
-    """获取存储服务实例（全局单例）"""
-    global _storage_service
-    if _storage_service is None:
-        _storage_service = OSSStorageService()
-    return _storage_service
+from packages.shared.storage import SharedStorageService as OSSStorageService
+from packages.shared.storage import (
+    get_shared_storage_service,
+    get_storage_service,
+)
 
+__all__ = ["OSSStorageService", "get_storage_service", "get_shared_storage_service"]

apps/api/app/core/task_enqueue.py

@@ -0,0 +1,221 @@
+import logging
+from typing import Any
+
+from app.core.celery_app import celery_app
+
+logger = logging.getLogger(__name__)
+
+# ── 限流阈值常量（全系统统一管理，不要在业务代码里硬编码） ──
+USER_PENDING_LIMIT = 3  # 单用户 pending 上限
+GLOBAL_PENDING_LIMIT = 20  # 全局 pending 上限
+
+
+class UserPendingLimitExceeded(Exception):
+    """用户 pending 任务数超限，返回 429。"""
+
+    def __init__(self, user_id: str, pending_count: int, limit: int):
+        self.user_id = user_id
+        self.pending_count = pending_count
+        self.limit = limit
+        super().__init__(f"用户 {user_id} pending 任务数 {pending_count} 超过上限 {limit}")
+
+
+class GlobalQueueFull(Exception):
+    """全局限流，返回 503。"""
+
+    def __init__(self, pending_count: int, limit: int):
+        self.pending_count = pending_count
+        self.limit = limit
+        super().__init__(f"系统 pending 任务数 {pending_count} 超过上限 {limit}")
+
+
+def check_queue_limits(
+    user_id: str,
+    generation_task_repository: Any,
+    *,
+    user_pending_limit: int = USER_PENDING_LIMIT,
+    global_pending_limit: int = GLOBAL_PENDING_LIMIT,
+) -> None:
+    """检查队列限流（预检查用，任务创建前调用），超限抛对应异常。
+
+    边界语义：>= 上限即拒绝（达到上限就不能再加新任务）。
+
+    Args:
+        user_id: 用户 ID
+        generation_task_repository: 任务仓储
+        user_pending_limit: 单用户 pending 上限，默认 USER_PENDING_LIMIT
+        global_pending_limit: 全局 pending 上限，默认 GLOBAL_PENDING_LIMIT
+
+    Raises:
+        GlobalQueueFull: 全局超限时抛出（优先级更高，先查全局）
+        UserPendingLimitExceeded: 用户超限时抛出
+    """
+    # 先查全局（系统级保护优先级更高）
+    global_pending = generation_task_repository.count_pending_total()
+    if global_pending >= global_pending_limit:
+        logger.warning(
+            "[队列限流] 全局 pending 任务数超限: %d/%d, user_id=%s",
+            global_pending,
+            global_pending_limit,
+            user_id,
+        )
+        raise GlobalQueueFull(pending_count=global_pending, limit=global_pending_limit)
+
+    # 再查用户级
+    if user_id:
+        user_pending = generation_task_repository.count_pending_by_user(user_id)
+        if user_pending >= user_pending_limit:
+            logger.warning(
+                "[队列限流] 用户 pending 任务数超限: user_id=%s, count=%d/%d",
+                user_id,
+                user_pending,
+                user_pending_limit,
+            )
+            raise UserPendingLimitExceeded(user_id=user_id, pending_count=user_pending, limit=user_pending_limit)
+
+
+def _mark_task_failed_safely(
+    task: Any,
+    generation_task_repository: Any,
+    log_prefix: str,
+    reason: str,
+) -> None:
+    """安全地把任务标记为 failed，更新失败只打日志不崩溃。"""
+    try:
+        task.mark_failed(f"任务被限流拒绝: {reason}")
+        generation_task_repository.update(task)
+    except Exception as update_err:
+        logger.error(
+            "%s 限流后更新状态也失败: task_id=%s error=%s",
+            log_prefix,
+            task.id,
+            update_err,
+            exc_info=True,
+        )
+
+
+def safe_enqueue_generation_task(
+    task: Any,
+    generation_task_repository: Any,
+    *,
+    user_id: str = "",
+    log_prefix: str = "[任务队列]",
+    log_task_status: bool = False,
+    user_pending_limit: int = USER_PENDING_LIMIT,
+    global_pending_limit: int = GLOBAL_PENDING_LIMIT,
+) -> bool:
+    """安全入队：入队前限流检查 → 发送 Celery 任务 → 入队后最终校验兜底。
+
+    边界说明：
+    入队前检查用 > 而非 >=。因为调用此函数时 task 已经是 pending 状态并计入 DB，
+    pending 总数包含了当前任务本身。pending > limit 等价于"其他任务数 >= limit"，
+    与预检查的 >= 语义一致（都是达到上限就拒绝新任务）。
+
+    入队后最终校验：发送 Celery 成功后再查一次 DB 计数，处理并发竞态场景
+    （两个请求同时通过入队前检查，后到的那个在这里被兜住）。
+
+    Args:
+        task: 生成任务对象，需有 id 属性和 mark_failed 方法（状态已为 pending）
+        generation_task_repository: 任务仓储，用于更新状态
+        user_id: 用户 ID，传了才做用户级限流检查
+        log_prefix: 日志前缀，便于区分调用来源
+        log_task_status: 成功日志中是否额外打印任务状态
+        user_pending_limit: 单用户 pending 上限，默认 USER_PENDING_LIMIT
+        global_pending_limit: 全局 pending 上限，默认 GLOBAL_PENDING_LIMIT
+
+    Returns:
+        True 表示入队成功，False 表示入队失败（已标记为 failed）
+
+    Raises:
+        GlobalQueueFull: 全局 pending 超限时抛出，任务会被标记为 failed
+        UserPendingLimitExceeded: 用户 pending 超限时抛出，任务会被标记为 failed
+    """
+    # ── 入队前检查：任务已是 pending，用 > 判断（包含当前任务） ──
+
+    # 全局限流检查（始终生效）
+    global_pending = generation_task_repository.count_pending_total()
+    if global_pending > global_pending_limit:
+        logger.warning(
+            "[队列限流] 全局 pending 任务数超限(入队前): %d/%d, user_id=%s",
+            global_pending,
+            global_pending_limit,
+            user_id or "unknown",
+        )
+        exc = GlobalQueueFull(pending_count=global_pending, limit=global_pending_limit)
+        _mark_task_failed_safely(task, generation_task_repository, log_prefix, str(exc))
+        raise exc
+
+    # 用户级限流检查（传了 user_id 才做）
+    if user_id:
+        user_pending = generation_task_repository.count_pending_by_user(user_id)
+        if user_pending > user_pending_limit:
+            logger.warning(
+                "[队列限流] 用户 pending 任务数超限(入队前): user_id=%s, count=%d/%d",
+                user_id,
+                user_pending,
+                user_pending_limit,
+            )
+            exc = UserPendingLimitExceeded(user_id=user_id, pending_count=user_pending, limit=user_pending_limit)
+            _mark_task_failed_safely(task, generation_task_repository, log_prefix, str(exc))
+            raise exc
+
+    # ── 发送 Celery 任务 ──
+    try:
+        celery_app.send_task("worker.generate_video", args=[task.id])
+    except Exception as e:
+        logger.error(
+            "%s 入队失败，标记为失败: task_id=%s error=%s",
+            log_prefix,
+            task.id,
+            e,
+            exc_info=True,
+        )
+        try:
+            task.mark_failed(f"任务入队失败: {e}")
+            generation_task_repository.update(task)
+        except Exception as update_err:
+            logger.error(
+                "%s 入队失败后更新状态也失败: task_id=%s error=%s",
+                log_prefix,
+                task.id,
+                update_err,
+                exc_info=True,
+            )
+        return False
+
+    # ── 入队后最终校验：并发竞态兜底 ──
+    # 发送成功后再查一次，防止两个请求同时通过入队前检查导致超限
+    global_after = generation_task_repository.count_pending_total()
+    user_after = generation_task_repository.count_pending_by_user(user_id) if user_id else 0
+
+    global_over = global_after > global_pending_limit
+    user_over = bool(user_id and user_after > user_pending_limit)
+
+    if global_over or user_over:
+        if global_over:
+            reason = f"全局 pending 超限(入队后): {global_after}/{global_pending_limit}"
+            exc: Exception = GlobalQueueFull(pending_count=global_after, limit=global_pending_limit)
+        else:
+            reason = f"用户 pending 超限(入队后): {user_after}/{user_pending_limit}"
+            exc = UserPendingLimitExceeded(user_id=user_id, pending_count=user_after, limit=user_pending_limit)
+
+        logger.warning(
+            "[队列限流] %s, task_id=%s, user_id=%s — 回滚状态为 failed",
+            reason,
+            task.id,
+            user_id or "unknown",
+        )
+        _mark_task_failed_safely(task, generation_task_repository, log_prefix, reason)
+        raise exc
+
+    # 入队成功日志
+    if log_task_status:
+        logger.info(
+            "%s 入队成功: task_id=%s, status=%s",
+            log_prefix,
+            task.id,
+            task.status,
+        )
+    else:
+        logger.info("%s 入队成功: task_id=%s", log_prefix, task.id)
+    return True

apps/api/app/db.py

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

apps/api/app/dependencies.py

@@ -3,17 +3,18 @@
 All repository and service factories are defined here as FastAPI dependencies,
 ensuring proper lifecycle management and testability.
 """
+
 from __future__ import annotations
 
-import redis
 from typing import Generator
 
+import redis
 from app.config import settings
 from fastapi import Depends
 from sqlalchemy.orm import Session
 
 from packages.adapters.redis import NoopSessionStore, SessionStore
-from packages.adapters.smtp import EmailConfig, NoopEmailService, get_email_service
+from packages.adapters.smtp import EmailConfig, EmailService, NoopEmailService, get_email_service
 from packages.adapters.sqlalchemy_impl.asset_library_repository import (
     SQLAlchemyAssetLibraryRepository,
 )
@@ -30,31 +31,27 @@ from packages.adapters.sqlalchemy_impl.generated_video_repository import (
 from packages.adapters.sqlalchemy_impl.generation_task_repository import (
     SQLAlchemyGenerationTaskRepository,
 )
-from packages.adapters.sqlalchemy_impl.title_library_repository import (
-    SQLAlchemyTitleLibraryRepository,
-)
-from packages.adapters.sqlalchemy_impl.voice_library_repository import (
-    SQLAlchemyVoiceLibraryRepository,
-)
 from packages.adapters.sqlalchemy_impl.ingest_job_repository import (
     SQLAlchemyIngestJobRepository,
 )
+from packages.adapters.sqlalchemy_impl.job_repository import SQLAlchemyJobRepository
 from packages.adapters.sqlalchemy_impl.project_repository import (
     SQLAlchemyProjectRepository,
 )
 from packages.adapters.sqlalchemy_impl.session import build_session_factory
+from packages.adapters.sqlalchemy_impl.tag_repository import SQLAlchemyTagRepository
+from packages.adapters.sqlalchemy_impl.title_library_repository import (
+    SQLAlchemyTitleLibraryRepository,
+)
 from packages.adapters.sqlalchemy_impl.user_repository import SQLAlchemyUserRepository
-from packages.ports.asset_repository import AssetRepository
-from packages.ports.asset_library_repository import AssetLibraryRepository
+from packages.adapters.sqlalchemy_impl.voice_clone_profile_repository import (
+    SQLAlchemyVoiceCloneProfileRepository,
+)
+from packages.adapters.sqlalchemy_impl.voice_library_repository import (
+    SQLAlchemyVoiceLibraryRepository,
+)
+from packages.ports.tag_repository import TagRepository
 from packages.ports.user_repository import UserRepository
-from packages.ports.classification_job_repository import ClassificationJobRepository
-from packages.ports.duplication_repository import DuplicationRecordRepository
-from packages.ports.generation_task_repository import GenerationTaskRepository
-from packages.ports.title_library_repository import TitleLibraryRepository
-from packages.ports.voice_library_repository import VoiceLibraryRepository
-from packages.ports.generated_video_repository import GeneratedVideoRepository
-from packages.ports.ingest_job_repository import IngestJobRepository
-from packages.ports.project_repository import ProjectRepository
 
 _engine, _SessionLocal = build_session_factory(settings.DATABASE_URL)
 
@@ -103,6 +100,13 @@ def get_generation_task_repository(
     return SQLAlchemyGenerationTaskRepository(session)
 
 
+def get_job_repository(
+    session: Session = Depends(get_db_session),
+) -> SQLAlchemyJobRepository:
+    """Provide the SQLAlchemy job repository implementation."""
+    return SQLAlchemyJobRepository(session)
+
+
 def get_generated_video_repository(
     session: Session = Depends(get_db_session),
 ) -> SQLAlchemyGeneratedVideoRepository:
@@ -124,6 +128,12 @@ def get_project_repository(
     return SQLAlchemyProjectRepository(session)
 
 
+def get_tag_repository(
+    session: Session = Depends(get_db_session),
+) -> TagRepository:
+    """Provide the SQLAlchemy tag repository implementation."""
+    return SQLAlchemyTagRepository(session)
+
 
 def get_user_repository(
     session: Session = Depends(get_db_session),
@@ -156,6 +166,7 @@ def get_auth_email_service() -> NoopEmailService | EmailService:
         enabled=True,
     )
 
+
 def get_title_library_repository(
     session: Session = Depends(get_db_session),
 ) -> SQLAlchemyTitleLibraryRepository:
@@ -168,3 +179,47 @@ def get_voice_library_repository(
 ) -> SQLAlchemyVoiceLibraryRepository:
     """Provide the SQLAlchemy voice library repository implementation."""
     return SQLAlchemyVoiceLibraryRepository(session)
+
+
+def get_voice_clone_profile_repository(
+    session: Session = Depends(get_db_session),
+) -> SQLAlchemyVoiceCloneProfileRepository:
+    """Provide the SQLAlchemy voice clone profile repository implementation."""
+    return SQLAlchemyVoiceCloneProfileRepository(session)
+
+
+def get_cosyvoice_service():
+    """Provide the CosyVoice service instance.
+
+    注入 OSS 音频URL预签名函数，确保私有bucket下的参考音频
+    能被 CosyVoice 服务器下载。
+    """
+    from app.core.storage import get_storage_service
+
+    from packages.application.cosyvoice_service import CosyVoiceService
+
+    storage = get_storage_service()
+
+    def _sign_audio_url(url: str) -> str:
+        """对音频URL做预签名，私有bucket下 CosyVoice 服务器才能下载."""
+        return storage.get_download_url(url, expires_seconds=86400)
+
+    return CosyVoiceService(audio_url_signer=_sign_audio_url)
+
+
+def get_audio_url_signer():
+    """提供音频URL预签名函数（24小时有效期）。
+
+    用于所有 API 返回给前端的音频 URL，确保私有 OSS bucket 下可正常访问。
+    空 URL、非 OSS URL 直接原样返回；签名失败时回退到原始 URL。
+    """
+    from app.core.storage import get_storage_service
+
+    storage = get_storage_service()
+
+    def sign_audio_url(url: str) -> str:
+        if not url:
+            return url
+        return storage.get_download_url(url, expires_seconds=86400)
+
+    return sign_audio_url

apps/api/app/middleware/auth.py

@@ -1,18 +1,22 @@
 """
 Authentication dependency compatibility layer.
 
-Canonical bearer-token parsing lives in app.auth. This module remains only so
-legacy imports have a safe target while workspace dependencies are rebuilt.
+Canonical bearer-token parsing lives in app.auth. This module re-exports
+common auth dependencies for backward compatibility.
 """
 
 from __future__ import annotations
 
+import logging
+
 from app.auth import AuthenticatedUser
 from app.auth import get_current_user as get_authenticated_user
 from app.dependencies import get_user_repository
-from fastapi import Depends
+from fastapi import Depends, HTTPException
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 
+logger = logging.getLogger(__name__)
+
 from packages.domain.entities import User
 from packages.ports.user_repository import UserRepository
 
@@ -33,6 +37,10 @@ async def get_current_user_optional(
         return None
     try:
         authenticated_user = await get_authenticated_user(credentials, user_repository)
-    except HTTPException:
+    except HTTPException as exc:
+        if exc.status_code >= 500:
+            # 服务端错误不应被静默吞掉，记录日志
+            logger.error("可选认证遇到服务端错误，status=%s", exc.status_code, exc_info=True)
+        # 4xx 认证失败（如 token 无效、用户不存在）属于正常流程，返回 None
         return None
     return authenticated_user.user

apps/api/app/middleware/exceptions.py

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

apps/api/app/middleware/logging.py

@@ -69,9 +69,7 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
 
         # 记录请求信息（不包含敏感参数）
         if safe_query:
-            logger.info(
-                f"Request: {request.method} {request.url.path}?{safe_query}"  # noqa: E501
-            )
+            logger.info(f"Request: {request.method} {request.url.path}?{safe_query}")  # noqa: E501
         else:
             logger.info(f"Request: {request.method} {request.url.path}")
 
@@ -83,8 +81,7 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
 
         # 记录响应信息
         logger.info(
-            f"Response: {request.method} {request.url.path} "
-            f"status={response.status_code} time={process_time:.3f}s"
+            f"Response: {request.method} {request.url.path} " f"status={response.status_code} time={process_time:.3f}s"
         )
 
         # 添加处理时间到响应头
@@ -94,15 +91,27 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
 
 
 class RateLimitMiddleware(BaseHTTPMiddleware):
-    """基于 IP 的简单限流中间件"""
+    """基于 IP 的简单限流中间件
 
-    def __init__(self, app, max_requests: int = 100, window_seconds: int = 60):
+    Args:
+        app: ASGI 应用
+        max_requests: 窗口期内最大请求数
+        window_seconds: 时间窗口（秒）
+        paths: 限流的路径列表，None 表示所有路径
+    """
+
+    def __init__(self, app, max_requests: int = 100, window_seconds: int = 60, paths: list[str] | None = None):
         super().__init__(app)
         self.max_requests = max_requests
         self.window_seconds = window_seconds
+        self.paths = set(paths) if paths else None
         self.requests = {}  # {ip: [timestamps]}
 
     async def dispatch(self, request: Request, call_next):
+        # 如果配置了路径过滤，只对指定路径限流
+        if self.paths is not None and request.url.path not in self.paths:
+            return await call_next(request)
+
         # 获取客户端 IP
         client_ip = request.client.host
 
@@ -111,9 +120,7 @@ class RateLimitMiddleware(BaseHTTPMiddleware):
         # 清理过期记录
         if client_ip in self.requests:
             self.requests[client_ip] = [
-                ts
-                for ts in self.requests[client_ip]
-                if current_time - ts < self.window_seconds
+                ts for ts in self.requests[client_ip] if current_time - ts < self.window_seconds
             ]
 
         # 计算请求次数
@@ -128,8 +135,7 @@ class RateLimitMiddleware(BaseHTTPMiddleware):
                     "error": {
                         "code": "RATE_LIMIT_EXCEEDED",
                         "message": (  # noqa: E501
-                            f"Too many requests. Limit: "
-                            f"{self.max_requests} per {self.window_seconds}s"
+                            f"Too many requests. Limit: " f"{self.max_requests} per {self.window_seconds}s"
                         ),
                     }
                 },
@@ -145,8 +151,6 @@ class RateLimitMiddleware(BaseHTTPMiddleware):
 
         # 添加限流信息到响应头
         response.headers["X-RateLimit-Limit"] = str(self.max_requests)
-        response.headers["X-RateLimit-Remaining"] = str(
-            self.max_requests - len(self.requests[client_ip])
-        )
+        response.headers["X-RateLimit-Remaining"] = str(self.max_requests - len(self.requests[client_ip]))
 
         return response

apps/api/app/middleware/monitoring.py

@@ -6,7 +6,7 @@ import logging
 import time
 from typing import Callable
 
-from fastapi import Request, Response
+from fastapi import Request
 from starlette.middleware.base import BaseHTTPMiddleware
 
 logger = logging.getLogger(__name__)

apps/api/app/middleware/prometheus_metrics.py

@@ -14,17 +14,16 @@ from typing import Callable
 
 from fastapi import Request, Response
 from prometheus_client import (
+    CONTENT_TYPE_LATEST,
+    REGISTRY,
     Counter,
     Gauge,
     Histogram,
     generate_latest,
-    CONTENT_TYPE_LATEST,
-    REGISTRY,
 )
 from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.responses import PlainTextResponse
 
-
 # Buckets for HTTP request duration (seconds)
 HTTP_DURATION_BUCKETS = (0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0)
 
@@ -122,8 +121,19 @@ class PrometheusMetricsMiddleware(BaseHTTPMiddleware):
 
 
 async def metrics_endpoint(request: Request) -> PlainTextResponse:
-    """FastAPI endpoint that returns Prometheus metrics in text format."""
+    """FastAPI endpoint that returns Prometheus metrics in text format.
+
+    需要 Bearer Token 认证，Token 通过 METRICS_AUTH_TOKEN 环境变量配置。
+    """
     import os
+
+    # Bearer Token 认证
+    auth_token = os.getenv("METRICS_AUTH_TOKEN", "")
+    if auth_token:
+        auth_header = request.headers.get("Authorization", "")
+        if not auth_header.startswith("Bearer ") or auth_header[7:] != auth_token:
+            return PlainTextResponse(content="Unauthorized", status_code=401)
+
     version = os.getenv("APP_VERSION", "unknown")
     environment = os.getenv("APP_ENV", "unknown")
     APP_INFO.labels(version=version, environment=environment).set(1)

apps/api/app/middleware/versioning.py

@@ -2,8 +2,6 @@
 API 版本管理中间件
 """
 
-from datetime import datetime
-
 from fastapi import Request
 from starlette.middleware.base import BaseHTTPMiddleware
 
@@ -63,7 +61,7 @@ class APIVersionMiddleware(BaseHTTPMiddleware):
 class VersionNotFoundMiddleware(BaseHTTPMiddleware):
     """处理已下线的 API 版本"""
 
-    SUNSET_VERSIONS = []  # 已下线的版本列表
+    SUNSET_VERSIONS: list[str] = []  # 已下线的版本列表
 
     async def dispatch(self, request: Request, call_next):
         version = self._extract_version(request.url.path)

apps/api/app/schemas/asset.py

@@ -25,6 +25,12 @@ class UpdateAssetReviewRequest(BaseModel):
     review_status: str = Field(..., pattern="^(pending_review|approved|rejected)$")
 
 
+class UpdateAssetRequest(BaseModel):
+    name: str | None = Field(default=None, min_length=1, max_length=100)
+    metadata: dict[str, object] | None = None
+    tags: list[str] | None = None
+
+
 class AssetResponse(BaseModel):
     id: str
     project_id: str
@@ -34,6 +40,7 @@ class AssetResponse(BaseModel):
     mime_type: str
     metadata: dict[str, object]
     file_size: int
+    file_url: str | None = None
     thumbnail_url: str | None = None
     duration: float | None = None
     width: int | None = None
@@ -44,7 +51,52 @@ class AssetResponse(BaseModel):
     classification_status: str
     quality_score: float | None = None
     uploaded_by_user_id: str
+    tag_ids: list[str] = Field(default_factory=list)
+
+
+MAX_BATCH_SIZE = 200
+
+
+class BatchDeleteRequest(BaseModel):
+    """批量删除请求（软删除）。"""
+
+    asset_ids: list[str] = Field(..., min_length=1, max_length=MAX_BATCH_SIZE, description="要删除的素材 ID 列表")
+
+
+class BatchOperationResponse(BaseModel):
+    """批量操作通用响应。"""
+
+    success_count: int = Field(..., ge=0, description="成功数量")
+    failed_ids: list[str] = Field(default_factory=list, description="失败的 ID 列表")
+    failed_details: dict[str, str] = Field(default_factory=dict, description="失败详情 {asset_id: reason}")
+
+
+class BatchTagRequest(BaseModel):
+    """批量打标签请求。"""
+
+    asset_ids: list[str] = Field(..., min_length=1, max_length=MAX_BATCH_SIZE, description="素材 ID 列表")
+    tag_ids: list[str] = Field(..., min_length=1, max_length=50, description="标签 ID 列表")
+    mode: str = Field(default="add", pattern="^(add|replace)$", description="add=添加合并，replace=全量替换")
+
+
+class BatchClassifyRequest(BaseModel):
+    """批量修改分类请求。"""
+
+    asset_ids: list[str] = Field(..., min_length=1, max_length=MAX_BATCH_SIZE, description="素材 ID 列表")
+    category: str = Field(..., min_length=1, max_length=50, description="内容分类，如 person/scenic/product")
+
+
+class BatchMarkRequest(BaseModel):
+    """批量设置智能视图标记请求。"""
+
+    asset_ids: list[str] = Field(..., min_length=1, max_length=MAX_BATCH_SIZE, description="素材 ID 列表")
+    smart_view: str = Field(
+        ..., pattern="^(recommended|caution|high_risk)$", description="智能视图标记：recommended/caution/high_risk"
+    )
 
 
 class ListAssetsResponse(BaseModel):
     items: list[AssetResponse]
+    total: int = Field(default=0, ge=0)
+    skip: int = Field(default=0, ge=0)
+    limit: int = Field(default=100, ge=1)

apps/api/app/schemas/asset_library.py

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

apps/api/app/schemas/chunked_upload.py

@@ -7,7 +7,9 @@ class ChunkedUploadInitRequest(BaseModel):
     filename: str = Field(..., min_length=1, max_length=255, description="Filename")
     file_size: int = Field(..., gt=0, le=2147483648, description="File size in bytes, max 2GB")
     total_chunks: int = Field(..., gt=0, description="Total number of chunks")
-    content_type: str = Field(default="application/octet-stream", min_length=1, max_length=100, description="Content type")
+    content_type: str = Field(
+        default="application/octet-stream", min_length=1, max_length=100, description="Content type"
+    )
     project_id: str = Field(..., min_length=1, description="Project ID")
     library_id: str = Field(..., min_length=1, description="Asset library ID")
 
@@ -34,9 +36,12 @@ class ChunkedUploadStatusResponse(BaseModel):
 class ChunkedUploadCompleteRequest(BaseModel):
     project_id: str = Field(..., min_length=1, description="Project ID")
     library_id: str = Field(..., min_length=1, description="Asset library ID")
+    file_hash: str = Field(default="", max_length=64, description="文件 MD5 哈希，用于去重检测")
 
 
 class ChunkedUploadCompleteResponse(BaseModel):
     storage_key: str = Field(..., description="Storage key")
     ingest_job_id: str = Field(..., description="Ingest job ID")
     url: str = Field(..., description="File URL")
+    duplicated: bool = Field(default=False, description="是否为重复素材（命中去重）")
+    asset_id: str = Field(default="", description="重复素材的 asset_id（duplicated=true 时返回）")

apps/api/app/schemas/duplication.py

@@ -1,4 +1,5 @@
 """查重 API Pydantic schemas。"""
+
 from __future__ import annotations
 
 from pydantic import BaseModel, Field

apps/api/app/schemas/generation_task.py

@@ -1,12 +1,61 @@
-from pydantic import BaseModel, Field
+import json
+
+from pydantic import BaseModel, Field, field_validator, model_validator
 
 
 class CreateGenerationTaskRequest(BaseModel):
-    project_id: str = Field(..., min_length=1)
-    asset_library_id: str = Field(..., min_length=1)
+    """创建生成任务请求。
+
+    支持两种模式（至少提供一种）：
+    - 项目模式：project_id + asset_library_id（向后兼容）
+    - 模板模式：template_id + asset_ids / title_ids / voice_ids
+    """
+
+    project_id: str = ""
+    asset_library_id: str = ""
     strategy_id: str = ""
     voice_library_id: str = ""
     created_by_user_id: str = ""
+    # ── 模板模式新增字段 ──
+    template_id: str = ""
+    asset_ids: list[str] = Field(default_factory=list)
+    title_ids: list[str] = Field(default_factory=list)
+    voice_ids: list[str] = Field(default_factory=list)
+    # ── 来源剪辑计划 ──
+    source_edit_plan_id: str = ""
+    # ── 批量生成 ──
+    count: int = Field(default=1, ge=1, le=50, description="批量生成数量，默认1，最大50")
+    # ── 素材库自动匹配 ──
+    asset_select_mode: str = Field(
+        default="all",
+        description="素材选取模式：all=全部ready视频, random=随机选取, smart=智能匹配（按质量/时长评分）",
+    )
+    asset_select_count: int = Field(
+        default=0, ge=0, le=100, description="选取数量，0表示全部（仅 random/smart 模式有效）"
+    )
+    # ── 自动重试 ──
+    auto_retry_enabled: bool = Field(
+        default=False,
+        description="是否开启失败自动重试，默认关闭",
+    )
+    auto_retry_max: int = Field(
+        default=0,
+        ge=0,
+        le=5,
+        description="最大自动重试次数，0表示不自动重试，最大5次",
+    )
+
+    @model_validator(mode="after")
+    def _check_at_least_one_mode(self) -> "CreateGenerationTaskRequest":
+        has_project = bool(self.project_id.strip())
+        has_template = bool(self.template_id.strip())
+        if not has_project and not has_template:
+            raise ValueError("project_id 或 template_id 至少需要提供一个")
+        has_library = bool(self.asset_library_id.strip())
+        has_assets = bool(self.asset_ids or self.title_ids or self.voice_ids)
+        if not has_library and not has_assets:
+            raise ValueError("asset_library_id 或 asset_ids/title_ids/voice_ids 至少需要提供一个")
+        return self
 
 
 class GenerationTaskResponse(BaseModel):
@@ -15,7 +64,46 @@ class GenerationTaskResponse(BaseModel):
     asset_library_id: str
     strategy_id: str
     voice_library_id: str
+    template_id: str = ""
+    asset_ids: list[str] = Field(default_factory=list)
+    title_ids: list[str] = Field(default_factory=list)
+    voice_ids: list[str] = Field(default_factory=list)
+    source_edit_plan_id: str = ""
+    asset_select_mode: str = ""
+    batch_id: str = ""
     status: str
     progress: float
     result_count: int
     error_message: str
+    error_info: dict = Field(default_factory=dict)
+    retry_count: int = 0
+    auto_retry_enabled: bool = False
+    auto_retry_max: int = 0
+    logs: list[dict] = Field(default_factory=list)
+
+    @field_validator("logs", mode="before")
+    @classmethod
+    def _parse_logs(cls, v: object) -> list[dict]:
+        """将 JSON 字符串解析为 list[dict]。"""
+        if isinstance(v, str):
+            try:
+                parsed = json.loads(v)
+                return parsed if isinstance(parsed, list) else []
+            except (json.JSONDecodeError, TypeError):
+                return []
+        if isinstance(v, list):
+            return v
+        return []
+
+
+class BatchGenerationTaskResponse(BaseModel):
+    """批量生成任务响应。"""
+
+    items: list[GenerationTaskResponse]
+    total: int
+
+
+class ListGenerationTasksResponse(BaseModel):
+    """用户级生成任务列表响应（跨 project）。"""
+
+    items: list[GenerationTaskResponse]

apps/api/app/schemas/subscription.py

@@ -1,15 +1,17 @@
 """Subscription schemas for API request/response models."""
+
 from __future__ import annotations
 
-from typing import List, Optional
+from typing import Optional
 
 from pydantic import BaseModel, Field
 
-
 # ============ Enums / Types ============
 
+
 class PlanType(str):
     """套餐类型"""
+
     FREE = "free"
     STANDARD = "standard"
     PRO = "pro"
@@ -18,6 +20,7 @@ class PlanType(str):
 
 class SubscriptionStatus(str):
     """订阅状态"""
+
     ACTIVE = "active"
     EXPIRED = "expired"
     CANCELLED = "cancelled"
@@ -26,6 +29,7 @@ class SubscriptionStatus(str):
 
 class BillingStatus(str):
     """账单状态"""
+
     PAID = "paid"
     PENDING = "pending"
     FAILED = "failed"
@@ -34,14 +38,17 @@ class BillingStatus(str):
 
 class BillingCycle(str):
     """计费周期"""
+
     MONTHLY = "monthly"
     YEARLY = "yearly"
 
 
 # ============ Response Schemas ============
 
+
 class SubscriptionInfo(BaseModel):
     """当前订阅信息"""
+
     id: str
     plan_id: str
     plan_name: str
@@ -56,6 +63,7 @@ class SubscriptionInfo(BaseModel):
 
 class BillingRecord(BaseModel):
     """账单记录"""
+
     id: str
     plan_name: str
     amount: float
@@ -68,6 +76,7 @@ class BillingRecord(BaseModel):
 
 class ChangePlanResponse(BaseModel):
     """升级/降级响应"""
+
     success: bool
     message: str
     new_subscription: Optional[SubscriptionInfo] = None
@@ -75,18 +84,22 @@ class ChangePlanResponse(BaseModel):
 
 class SimpleResponse(BaseModel):
     """简单响应（用于取消订阅、切换自动续费等）"""
+
     success: bool
     message: str
 
 
 # ============ Request Schemas ============
 
+
 class ChangePlanRequest(BaseModel):
     """升级/降级请求"""
+
     target_plan_id: str = Field(..., description="目标套餐ID")
     billing_cycle: str = Field(..., description="计费周期: monthly/yearly")
 
 
 class ToggleAutoRenewRequest(BaseModel):
     """切换自动续费请求"""
+
     enabled: bool = Field(..., description="是否开启自动续费")

apps/api/app/schemas/tag.py

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