Merge branch 'develop' into ci/cache-optimization-plus

Co-authored-by: xiaoxia <dev@xiaoxiajianji.com>
Co-committed-by: xiaoxia <dev@xiaoxiajianji.com>

.ci-trigger

@@ -1 +1,2 @@
-trigger: 1784009947
+CI trigger file - safe to delete
+updated!

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

@@ -0,0 +1,81 @@
+name: CI Health Daily Report
+
+on:
+  schedule:
+    - cron: '0 1 * * *'  # UTC 01:00 = 北京时间 09:00
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  ci-health-report:
+    name: CI健康度每日巡检
+    runs-on: saas
+    timeout-minutes: 10
+
+    steps:
+    - name: Checkout code
+      shell: sh
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: |
+        set -eu
+        python3 - <<'PY'
+        import io, os, tarfile, time, urllib.request, urllib.error
+        url = f"{os.environ['GITHUB_API_URL']}/repos/{os.environ['GITHUB_REPOSITORY']}/archive/{os.environ['GITHUB_SHA']}.tar.gz"
+        request = urllib.request.Request(url, headers={"Authorization": f"token {os.environ['GITHUB_TOKEN']}"})
+        last_err = None
+        for attempt in range(5):
+            try:
+                with urllib.request.urlopen(request, timeout=120) as response:
+                    archive = response.read()
+                break
+            except urllib.error.HTTPError as e:
+                last_err = e
+                if e.code >= 500 and attempt < 4:
+                    wait = 2 ** attempt
+                    print(f"Checkout HTTP {e.code}, retrying in {wait}s (attempt {attempt+1}/5)...")
+                    time.sleep(wait)
+                    continue
+                raise
+            except Exception as e:
+                last_err = e
+                if attempt < 4:
+                    wait = 2 ** attempt
+                    print(f"Checkout error: {e}, retrying in {wait}s (attempt {attempt+1}/5)...")
+                    time.sleep(wait)
+                    continue
+                raise
+        else:
+            raise last_err
+        with tarfile.open(fileobj=io.BytesIO(archive), mode='r:gz') as tar:
+            root_prefix = tar.getmembers()[0].name.split('/', 1)[0] + '/'
+            for member in tar.getmembers():
+                name = member.name
+                if name == root_prefix[:-1]:
+                    continue
+                if name.startswith(root_prefix):
+                    member.name = name[len(root_prefix):]
+                if member.name:
+                    tar.extract(member, '.')
+        PY
+
+    - name: Run CI health check and report
+      shell: sh
+      env:
+        GITEA_TOKEN: ${{ github.token }}
+        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
+      run: |
+        set +e
+        echo "=== CI健康度每日巡检 ==="
+        echo "时间: $(date '+%Y-%m-%d %H:%M:%S')"
+        echo ""
+
+        python3 scripts/ci/ci_health_report.py --limit 30
+        EXIT_CODE=$?
+
+        echo ""
+        echo "巡检完成 (exit code: $EXIT_CODE)"
+        # 永远成功，不影响CI状态（通知失败不应该标红）
+        exit 0

.gitea/workflows/ci-pipeline.yml

@@ -335,9 +335,6 @@ jobs:
     - name: Run Prettier check
       shell: sh
       run: bash scripts/ci/step_frontend_run.sh "npx --no-install prettier --check \"src/**/*.{ts,tsx,md}\""
-    - name: Run Vitest tests
-      shell: sh
-      run: bash scripts/ci/step_frontend_run.sh "npx --no-install vitest run src/test"
     - name: Job duration summary
       if: always()
       shell: sh
@@ -419,6 +416,125 @@ jobs:
         [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
         python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
 
+
+  build-pr:
+    name: PR Build ${{ matrix.service_display }} Image
+    runs-on: runtime-builder
+    timeout-minutes: ${{ matrix.timeout }}
+    if: github.event_name == 'pull_request'
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - service: api
+          service_display: API
+          dockerfile: infra/docker/api.Dockerfile
+          image_name: xiaoxia-saas-api
+          cache_name: api-cache
+          timeout: 30
+        - service: worker
+          service_display: Worker
+          dockerfile: infra/docker/worker.Dockerfile
+          image_name: xiaoxia-saas-worker
+          cache_name: worker-cache
+          timeout: 40
+        - service: web
+          service_display: Web
+          dockerfile: infra/docker/web.Dockerfile
+          image_name: xiaoxia-saas-web
+          cache_name: web-cache
+          timeout: 30
+    steps:
+    - name: Checkout code
+      shell: sh
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: |
+        curl -sH "Authorization: token $GITHUB_TOKEN"           "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}"           | bash
+    - name: Record job start time
+      shell: sh
+      run: bash scripts/ci/step_timer_start.sh
+    - name: Docker login to Registry (for cache read)
+      shell: sh
+      env:
+        ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
+        ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
+        GITEA_REGISTRY_USER: xiaoxia
+        GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+      run: |
+        set -eu
+        for i in 1 2 3; do
+          echo "Docker login attempt $i/3"
+          if printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin              && docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"; then
+            echo "Docker login successful"
+            break
+          fi
+          echo "Docker login failed ($i/3), retrying in 5s..."
+          sleep 5
+        done
+    - name: Build PR image (verify only, no push)
+      shell: sh
+      run: |
+        set -eu
+        REGISTRY="xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji"
+        IMAGE_TAG="${REGISTRY}/${{ matrix.image_name }}:pr-${GITHUB_SHA}"
+        CACHE_REF="${REGISTRY}/${{ matrix.cache_name }}:develop"
+
+        EXTRA_BUILD_ARGS="APP_VERSION=\"${GITHUB_SHA}\""
+        if [ "${{ matrix.service }}" = "web" ]; then
+          EXTRA_BUILD_ARGS="$EXTRA_BUILD_ARGS NGINX_CONF=infra/docker/nginx-staging.conf"
+        fi
+
+        NO_CACHE_FLAG=""
+        for i in 1 2 3; do
+          echo "PR Build attempt $i/3"
+          if bash scripts/ci/docker_build_only.sh $NO_CACHE_FLAG ${{ matrix.dockerfile }} "${IMAGE_TAG}" "${CACHE_REF}" $EXTRA_BUILD_ARGS; then
+            echo "PR Build successful"
+            break
+          fi
+          echo "PR Build failed (attempt $i/3)"
+          [ $i -eq 3 ] && exit 1
+          sleep 10
+          if [ $i -eq 2 ]; then
+            NO_CACHE_FLAG="--no-cache"
+            echo "Next retry with --no-cache"
+          fi
+        done
+        echo
+        echo "${{ matrix.service_display }} PR build verified: ${IMAGE_TAG}"
+    - name: Cleanup buildx builder
+      if: always()
+      shell: sh
+      run: |
+        BUILDER_NAME="ci-pr-builder-${GITHUB_RUN_ID:-local}"
+        docker buildx rm "$BUILDER_NAME" 2>/dev/null || true
+        docker buildx prune -f 2>/dev/null || true
+        echo "Builder cleanup done"
+    - name: Job duration summary
+      if: always()
+      shell: sh
+      run: bash scripts/ci/step_timer_end.sh
+    - name: Notify on failure
+      continue-on-error: true
+      if: failure()
+      shell: sh
+      env:
+        CI_NOTIFY_WEBHOOK: ${{ secrets.CI_NOTIFY_WEBHOOK }}
+      run: |
+        set +e
+        NOTIFY_MODE=failure JOB_NAME="PR Build ${{ matrix.service_display }} Image" python3 scripts/ci_notify.py
+    - name: Report CI trace
+      if: always()
+      shell: sh
+      env:
+        AGENTLOOP_LICENSE_KEY: ${{ secrets.AGENTLOOP_LICENSE_KEY }}
+      run: |
+        STATUS="ok"
+        [ ${{ job.status }} = "success" ] || STATUS="error"
+        START_TIME=""
+        [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
+        python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+
   build-staging:
     name: Build Staging ${{ matrix.service_display }} Image
     runs-on: runtime-builder
@@ -465,9 +581,16 @@ jobs:
         GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
       run: |
         set -eu
-        printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin
-        docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"
-        echo "Docker login successful"
+        # Docker login 带重试（网络波动时自动重试）
+        for i in 1 2 3; do
+          echo "=== Docker login 尝试 $i/3 ==="
+          if printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin              && docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"; then
+            echo "✅ Docker login successful"
+            break
+          fi
+          echo "❌ Docker login 失败（尝试 $i/3），5s 后重试..."
+          sleep 5
+        done
     - name: Setup cache strategy
       shell: sh
       run: |
@@ -526,6 +649,15 @@ jobs:
 
         echo
         echo "${{ matrix.service_display }} image pushed: ${IMAGE_TAG}"
+    - name: Cleanup buildx builder
+      if: always()
+      shell: sh
+      run: |
+        docker buildx rm ci-builder-${GITHUB_RUN_ID}-${GITHUB_JOB}-${{ matrix.cache_name }} 2>/dev/null || true
+        docker buildx rm ci-builder 2>/dev/null || true
+        docker buildx prune -f 2>/dev/null || true
+        echo "Builder cleanup done"
+
     - name: Job duration summary
       if: always()
       shell: sh
@@ -589,9 +721,16 @@ jobs:
         GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
       run: |
         set -eu
-        printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin
-        docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"
-        echo "Docker login successful"
+        # Docker login 带重试（网络波动时自动重试）
+        for i in 1 2 3; do
+          echo "=== Docker login 尝试 $i/3 ==="
+          if printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin              && docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"; then
+            echo "✅ Docker login successful"
+            break
+          fi
+          echo "❌ Docker login 失败（尝试 $i/3），5s 后重试..."
+          sleep 5
+        done
     - name: Install SSH client
       if: success()
       shell: sh
@@ -858,9 +997,16 @@ jobs:
         GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
       run: |
         set -eu
-        printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin
-        docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"
-        echo "Docker login successful"
+        # Docker login 带重试（网络波动时自动重试）
+        for i in 1 2 3; do
+          echo "=== Docker login 尝试 $i/3 ==="
+          if printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin              && docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"; then
+            echo "✅ Docker login successful"
+            break
+          fi
+          echo "❌ Docker login 失败（尝试 $i/3），5s 后重试..."
+          sleep 5
+        done
     - name: Setup cache strategy
       shell: sh
       run: |

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

@@ -21,6 +21,10 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v3
+        # 网络波动自动重试2次
+        retry:
+          max_attempts: 2
+          retry_on: error
       
       - name: Check CI trigger status for all open PRs
         env:

.gitea/workflows/code-review.yml

@@ -25,9 +25,21 @@ jobs:
         uses: actions/checkout@v3
         with:
           fetch-depth: 0
+        # 网络波动自动重试2次
+        retry:
+          max_attempts: 2
+          retry_on: error
 
       - name: Install dependencies
         run: |
+          # 确保 python3-pip 可用（兼容不同基础镜像）
+          if ! python3 -m pip --version >/dev/null 2>&1; then
+            apt-get update -qq && apt-get install -y -qq python3-pip python3-venv >/dev/null 2>&1
+          fi
+          # 部分镜像 ensurepip 方式兜底
+          if ! python3 -m pip --version >/dev/null 2>&1; then
+            python3 -m ensurepip --upgrade 2>/dev/null || curl -sS https://bootstrap.pypa.io/get-pip.py | python3
+          fi
           python3 -m pip install --upgrade pip
           python3 -m pip install requests
 
@@ -64,3 +76,4 @@ jobs:
           START_TIME=""
           [ -f /tmp/ci_job_start_time ] && START_TIME=$(cat /tmp/ci_job_start_time)
           python3 scripts/ci/ci_trace_report.py --service xiaoxia-saas-ci --status $STATUS --start-time "$START_TIME" || true
+

.gitea/workflows/pr-automation.yml

@@ -235,6 +235,9 @@ jobs:
             CONTEXTS=(
               "CI/CD Pipeline / Validate Code Quality And Tests (pull_request)"
               "CI/CD Pipeline / Frontend Lint (pull_request)"
+              "CI/CD Pipeline / PR Build API Image (pull_request)"
+              "CI/CD Pipeline / PR Build Worker Image (pull_request)"
+              "CI/CD Pipeline / PR Build Web Image (pull_request)"
             )
             echo "检查required门禁（与分支保护一致）"
           fi

alembic/versions/048_cleanup_result_count.py

@@ -0,0 +1,37 @@
+"""Phase 3 - 清理 EditPlan 表冗余字段
+
+Revision ID: 048
+Revises: 047
+Create Date: 2026-07-21
+
+Changes:
+1. 删除 edit_plans.result_count 字段（剪辑计划独立功能遗留，模板草稿不用，
+   生成结果数由 generation_tasks.result_count 承载）
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "048_cleanup_result_count"
+down_revision = "047_template_versioning"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # 删除 result_count 字段（剪辑计划独立功能遗留字段）
+    op.drop_column("edit_plans", "result_count")
+
+
+def downgrade() -> None:
+    # 回滚：恢复 result_count 字段，默认值 0
+    op.add_column(
+        "edit_plans",
+        sa.Column(
+            "result_count",
+            sa.Integer,
+            nullable=False,
+            server_default="0",
+        ),
+    )

alembic/versions/049_wechat_login_phone.py

@@ -0,0 +1,97 @@
+"""#558 - 微信登录：手机号绑定字段 + 验证码表
+
+Revision ID: 049
+Revises: 048
+Create Date: 2026-07-21
+
+Changes:
+1. users 表新增 phone_verified / binding_completed_at 字段（phone 字段已在 029 中添加）
+2. users 表 phone 字段添加唯一索引（幂等）
+3. 新建 verification_codes 表（统一管理邮箱+手机验证码）
+"""
+
+import sqlalchemy as sa
+
+from alembic import context, op
+
+revision = "049_wechat_login_phone"
+down_revision = "048_cleanup_result_count"
+branch_labels = None
+depends_on = None
+
+
+def _column_exists(table: str, column: str) -> bool:
+    """检查列是否已存在。离线模式下返回 False。"""
+    if context.is_offline_mode():
+        return False
+    conn = op.get_bind()
+    result = conn.execute(
+        sa.text("SELECT 1 FROM information_schema.columns " "WHERE table_name = :table AND column_name = :column"),
+        {"table": table, "column": column},
+    )
+    return result.first() is not None
+
+
+def _index_exists(index_name: str) -> bool:
+    """检查索引是否已存在。离线模式下返回 False。"""
+    if context.is_offline_mode():
+        return False
+    conn = op.get_bind()
+    result = conn.execute(
+        sa.text("SELECT 1 FROM pg_indexes WHERE indexname = :index_name"),
+        {"index_name": index_name},
+    )
+    return result.first() is not None
+
+
+def upgrade() -> None:
+    # 1. users 表新增手机号验证状态字段（幂等）
+    if not _column_exists("users", "phone_verified"):
+        op.add_column(
+            "users",
+            sa.Column(
+                "phone_verified",
+                sa.Boolean,
+                nullable=False,
+                server_default=sa.text("false"),
+            ),
+        )
+
+    if not _column_exists("users", "binding_completed_at"):
+        op.add_column(
+            "users",
+            sa.Column("binding_completed_at", sa.DateTime, nullable=True),
+        )
+
+    # 2. phone 字段唯一索引（幂等 - 029 加了字段但没加索引）
+    if not _index_exists("ix_users_phone"):
+        op.create_index("ix_users_phone", "users", ["phone"], unique=True)
+
+    # 3. verification_codes 表
+    op.create_table(
+        "verification_codes",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("recipient", sa.String(255), nullable=False, index=True),
+        sa.Column("code", sa.String(10), nullable=False),
+        sa.Column("code_type", sa.String(32), nullable=False, index=True),
+        sa.Column("expires_at", sa.DateTime, nullable=False),
+        sa.Column("used_at", sa.DateTime, nullable=True),
+        sa.Column("attempts", sa.Integer, nullable=False, server_default="0"),
+        sa.Column("created_at", sa.DateTime, nullable=False),
+        sa.Index(
+            "ix_verification_recipient_type",
+            "recipient",
+            "code_type",
+            "created_at",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("verification_codes")
+    if _index_exists("ix_users_phone"):
+        op.drop_index("ix_users_phone", table_name="users")
+    if _column_exists("users", "binding_completed_at"):
+        op.drop_column("users", "binding_completed_at")
+    if _column_exists("users", "phone_verified"):
+        op.drop_column("users", "phone_verified")

apps/api/app/api/router.py

@@ -5,7 +5,6 @@ from app.api.routes.auth import router as auth_router
 from app.api.routes.chunked_upload import router as chunked_upload_router
 from app.api.routes.classification_jobs import router as classification_jobs_router
 from app.api.routes.duplication import router as duplication_router
-from app.api.routes.edit_plans import router as edit_plans_router
 from app.api.routes.feature_flags import router as feature_flags_router
 from app.api.routes.generation_tasks import router as generation_tasks_router
 from app.api.routes.health import router as health_check_router
@@ -125,11 +124,6 @@ api_router.include_router(
     prefix="/templates/{template_id}/editor",
     tags=["TemplateEditor"],
 )
-api_router.include_router(
-    edit_plans_router,
-    prefix="/edit-plans",
-    tags=["EditPlan"],
-)
 api_router.include_router(
     tts_router,
     prefix="/tts",

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

@@ -139,26 +139,3 @@ def format_utc_datetime(dt: datetime | None) -> str:
     if dt.tzinfo is None:
         return dt.isoformat() + "Z"
     return dt.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
-
-
-# ── Deprecated API 标记 ──────────────────────────────────────────────────────
-
-
-import logging as _logging
-
-from fastapi import Request as _Request
-
-_deprecated_logger = _logging.getLogger(__name__)
-
-
-def deprecated_edit_plans_api(request: _Request) -> None:
-    """标记 /edit-plans/* 系列 API 为废弃，打 warning 日志。
-
-    Phase 2 模板编辑器收敛后，所有剪辑计划 API 迁移到 /templates/{id}/editor/*。
-    旧路径保留 2 个版本周期兼容，之后会下线。
-    """
-    _deprecated_logger.warning(
-        "Deprecated API called: %s %s. Use /templates/{template_id}/editor/* instead.",
-        request.method,
-        request.url.path,
-    )

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

@@ -81,6 +81,9 @@ class CurrentUserResponse(BaseModel):
     username: str
     display_name: str
     email_verified: bool
+    phone: str = ""
+    phone_verified: bool = False
+    binding_complete: bool = False
 
 
 class PasswordResetRequestModel(BaseModel):
@@ -259,12 +262,16 @@ async def get_current_user_info(
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
 ) -> CurrentUserResponse:
     user = authenticated_user.user
+    binding_complete = user.phone_verified and user.email_verified and user.email and "@wechat.local" not in user.email
     return CurrentUserResponse(
         user_id=user.id,
         email=user.email,
         username=user.username,
         display_name=user.display_name,
         email_verified=user.email_verified,
+        phone=user.phone or "",
+        phone_verified=user.phone_verified,
+        binding_complete=binding_complete,
     )
 
 
@@ -380,3 +387,202 @@ async def wechat_sync(
         raise HTTPException(status_code=400, detail=error)
 
     return WechatSyncResponse(**response.to_dict())
+
+
+# ==================== 微信网页登录（OAuth） ====================
+
+
+class WechatAuthUrlResponse(BaseModel):
+    auth_url: str
+    state: str
+
+
+class WechatCallbackRequest(BaseModel):
+    code: str
+    state: str = ""
+
+
+class WechatLoginResponse(BaseModel):
+    access_token: str
+    refresh_token: str
+    user_id: str
+    display_name: str
+    avatar_url: str = ""
+    is_new_user: bool
+    binding_complete: bool
+    expires_in: int
+
+
+@router.get("/wechat/url", response_model=WechatAuthUrlResponse)
+async def get_wechat_auth_url() -> WechatAuthUrlResponse:
+    """获取微信扫码登录授权链接"""
+    from packages.application.auth.wechat_oauth_service import get_wechat_oauth_service
+
+    oauth_service = get_wechat_oauth_service()
+    auth_url, state = oauth_service.generate_auth_url()
+    return WechatAuthUrlResponse(auth_url=auth_url, state=state)
+
+
+@router.post("/wechat/callback", response_model=WechatLoginResponse)
+async def wechat_callback(
+    request: WechatCallbackRequest,
+    user_repository: UserRepository = Depends(get_user_repository),
+) -> WechatLoginResponse:
+    """微信登录回调处理"""
+    from packages.application.auth.wechat_oauth_service import get_wechat_oauth_service
+    from packages.application.auth.wechat_sync_use_case import WechatSyncRequest as SyncRequest
+    from packages.application.auth.wechat_sync_use_case import WechatSyncUseCase
+
+    # 1. 用 code 换微信用户信息
+    oauth_service = get_wechat_oauth_service()
+    wechat_user, err = oauth_service.handle_callback(request.code, request.state)
+    if err:
+        raise HTTPException(status_code=400, detail=err)
+
+    # 2. 同步登录/注册（复用 wechat-sync 逻辑）
+    use_case = WechatSyncUseCase(user_repository=user_repository)
+    sync_request = SyncRequest(
+        openid=wechat_user.openid,
+        unionid=wechat_user.unionid,
+        nickname=wechat_user.nickname,
+        avatar_url=wechat_user.avatar_url,
+        source="web",
+    )
+    response, err = use_case.execute(sync_request)
+    if err:
+        raise HTTPException(status_code=400, detail=err)
+
+    # 3. 判断绑定状态
+    user = user_repository.find_by_id(response.user_id)
+    binding_complete = False
+    if user:
+        binding_complete = (
+            user.phone_verified and user.email_verified and user.email and "@wechat.local" not in user.email
+        )
+
+    return WechatLoginResponse(
+        access_token=response.access_token,
+        refresh_token=response.refresh_token,
+        user_id=response.user_id,
+        display_name=response.nickname,
+        avatar_url=response.avatar_url or wechat_user.avatar_url,
+        is_new_user=response.is_new_user,
+        binding_complete=binding_complete,
+        expires_in=response.expires_in,
+    )
+
+
+# ==================== 验证码 & 绑定 ====================
+
+
+class SendVerificationCodeRequest(BaseModel):
+    target: str  # phone / email
+    value: str
+    purpose: str  # bind / login / reset_password
+
+
+class SendVerificationCodeResponse(BaseModel):
+    expires_in: int
+    resend_after: int
+
+
+class BindContactRequest(BaseModel):
+    phone: str = ""
+    phone_code: str = ""
+    email: str = ""
+    email_code: str = ""
+
+
+class BindContactResponse(BaseModel):
+    success: bool
+    user: dict
+
+
+@router.post("/send-verification-code", response_model=SendVerificationCodeResponse)
+async def send_verification_code(
+    request: SendVerificationCodeRequest,
+) -> SendVerificationCodeResponse:
+    """发送验证码（手机或邮箱）"""
+    from app.dependencies import get_db_session
+
+    from packages.adapters.sms.sms_service import get_sms_service
+    from packages.adapters.smtp import get_email_service
+    from packages.adapters.sqlalchemy_impl.verification_code_repository import (
+        SQLAlchemyVerificationCodeRepository,
+    )
+    from packages.application.auth.bind_contact_use_case import SendVerificationCodeRequest as UseCaseRequest
+    from packages.application.auth.bind_contact_use_case import (
+        SendVerificationCodeUseCase,
+    )
+    from packages.application.auth.verification_code_service import VerificationCodeService
+
+    db = next(get_db_session())
+    repo = SQLAlchemyVerificationCodeRepository(db)
+    vc_service = VerificationCodeService(repo=repo)
+    sms_service = get_sms_service()
+    email_service = get_email_service()
+
+    use_case = SendVerificationCodeUseCase(
+        verification_code_service=vc_service,
+        sms_service=sms_service,
+        email_service=email_service,
+    )
+    uc_request = UseCaseRequest(
+        target=request.target,
+        value=request.value,
+        purpose=request.purpose,
+    )
+    response, err = use_case.execute(uc_request)
+    if err:
+        raise HTTPException(status_code=400, detail=err)
+
+    return SendVerificationCodeResponse(
+        expires_in=response.expires_in,
+        resend_after=response.resend_after,
+    )
+
+
+@router.post("/bind-contact", response_model=BindContactResponse)
+async def bind_contact(
+    request: BindContactRequest,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    user_repository: UserRepository = Depends(get_user_repository),
+) -> BindContactResponse:
+    """绑定手机号和/或邮箱（需登录态）"""
+    from app.dependencies import get_db_session
+
+    from packages.adapters.sqlalchemy_impl.verification_code_repository import (
+        SQLAlchemyVerificationCodeRepository,
+    )
+    from packages.application.auth.bind_contact_use_case import BindContactRequest as UseCaseRequest
+    from packages.application.auth.bind_contact_use_case import (
+        BindContactUseCase,
+    )
+    from packages.application.auth.verification_code_service import VerificationCodeService
+
+    db = next(get_db_session())
+    vc_repo = SQLAlchemyVerificationCodeRepository(db)
+    vc_service = VerificationCodeService(repo=vc_repo)
+
+    use_case = BindContactUseCase(
+        user_repository=user_repository,
+        verification_code_service=vc_service,
+    )
+    uc_request = UseCaseRequest(
+        user_id=current_user.user.id,
+        phone=request.phone,
+        phone_code=request.phone_code,
+        email=request.email,
+        email_code=request.email_code,
+    )
+    response, err = use_case.execute(uc_request)
+    if err:
+        raise HTTPException(status_code=400, detail=err)
+
+    return BindContactResponse(success=True, user=response.to_dict()["user"])
+
+
+# ==================== 当前用户信息扩展 ====================
+
+# 扩展 CurrentUserResponse 增加绑定状态字段（在原响应基础上补充）
+# 通过给 get_current_user_info 返回值补充字段实现

apps/api/app/api/routes/edit_plans_adjustments.py

@@ -1,313 +0,0 @@
-"""片段调整 API.
-
-- PUT    /clips/{clip_id}/speed         调速
-- PUT    /clips/{clip_id}/volume        音量调节
-- PUT    /clips/{clip_id}/trim          裁剪（trim in/out）
-- PUT    /clips/{clip_id}/adjustments   统一调整（speed+volume+trim）
-- POST   /{plan_id}/clips/batch-speed   批量调速
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, Optional
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
-from app.services import EditPlanService
-from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, Field
-from sqlalchemy.orm import Session
-
-from ._helpers import check_project_access, deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-
-class SpeedAdjustRequest(BaseModel):
-    """调速请求"""
-
-    speed: float = Field(..., ge=0.25, le=4.0, description="播放速度 0.25~4.0")
-
-
-class VolumeAdjustRequest(BaseModel):
-    """音量调节请求"""
-
-    volume: float = Field(..., ge=0.0, le=2.0, description="音量倍率 0~2.0（1.0=原音量）")
-
-
-class TrimAdjustRequest(BaseModel):
-    """裁剪请求"""
-
-    trim_start: float = Field(0.0, ge=0.0, description="开头裁剪秒数")
-    trim_end: float = Field(0.0, ge=0.0, description="结尾裁剪秒数")
-
-
-class ClipAdjustmentsRequest(BaseModel):
-    """统一调整请求"""
-
-    speed: Optional[float] = Field(default=None, ge=0.25, le=4.0)
-    volume: Optional[float] = Field(default=None, ge=0.0, le=2.0)
-    trim_start: Optional[float] = Field(default=None, ge=0.0)
-    trim_end: Optional[float] = Field(default=None, ge=0.0)
-
-
-class BatchSpeedRequest(BaseModel):
-    """批量调速请求"""
-
-    speed: float = Field(..., ge=0.25, le=4.0, description="播放速度")
-
-
-class ClipAdjustResponse(BaseModel):
-    """片段调整响应"""
-
-    clip_id: str
-    speed: float
-    volume: float
-    trim_start: float
-    trim_end: float
-    duration: float
-
-
-class BatchSpeedResponse(BaseModel):
-    """批量调速响应"""
-
-    updated_count: int
-    plan_id: str
-
-
-# ── Helpers ──────────────────────────────────────────────────────────────────
-
-
-def _get_clip_config(clip) -> dict:
-    config = getattr(clip, "config", {}) or {}
-    if not isinstance(config, dict):
-        config = {}
-    return config
-
-
-def _get_volume(clip) -> float:
-    config = _get_clip_config(clip)
-    return float(config.get("volume", 1.0))
-
-
-def _get_trim(clip) -> tuple[float, float]:
-    config = _get_clip_config(clip)
-    trim_start = float(config.get("trim_start", 0.0))
-    trim_end = float(config.get("trim_end", 0.0))
-    return trim_start, trim_end
-
-
-def _build_response(clip) -> ClipAdjustResponse:
-    trim_start, trim_end = _get_trim(clip)
-    return ClipAdjustResponse(
-        clip_id=clip.id,
-        speed=clip.playback_speed,
-        volume=_get_volume(clip),
-        trim_start=trim_start,
-        trim_end=trim_end,
-        duration=clip.duration,
-    )
-
-
-def _validate_trim(trim_start: float, trim_end: float, total_duration: float) -> None:
-    """验证裁剪时长不超过总时长"""
-    if trim_start + trim_end >= total_duration:
-        raise ValueError(f"裁剪总时长（{trim_start + trim_end:.2f}s）不能大于等于片段总时长（{total_duration:.2f}s）")
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-def _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository):
-    svc = EditPlanService(db)
-    clip = svc.get_clip(clip_id)
-    if not clip:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"片段不存在: {clip_id}",
-        )
-    plan = svc.get_plan(clip.plan_id)
-    if plan and plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-    return svc, plan, clip
-
-
-@router.put("/clips/{clip_id}/speed", response_model=ClipAdjustResponse, deprecated=True)
-def adjust_speed(
-    clip_id: str,
-    body: SpeedAdjustRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipAdjustResponse:
-    """调整片段播放速度"""
-    svc, _, clip = _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository)
-
-    updated = svc.update_clip(clip_id, playback_speed=body.speed)
-
-    logger.info(
-        "调整片段速度: clip_id=%s speed=%.2f by user=%s",
-        clip_id,
-        body.speed,
-        current_user.user.id,
-    )
-    return _build_response(updated)
-
-
-@router.put("/clips/{clip_id}/volume", response_model=ClipAdjustResponse, deprecated=True)
-def adjust_volume(
-    clip_id: str,
-    body: VolumeAdjustRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipAdjustResponse:
-    """调整片段音量"""
-    svc, _, clip = _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository)
-
-    # 更新 config.volume
-    config = dict(_get_clip_config(clip))
-    config["volume"] = body.volume
-    updated = svc.update_clip(clip_id, config=config)
-
-    logger.info(
-        "调整片段音量: clip_id=%s volume=%.2f by user=%s",
-        clip_id,
-        body.volume,
-        current_user.user.id,
-    )
-    return _build_response(updated)
-
-
-@router.put("/clips/{clip_id}/trim", response_model=ClipAdjustResponse, deprecated=True)
-def adjust_trim(
-    clip_id: str,
-    body: TrimAdjustRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipAdjustResponse:
-    """裁剪片段（trim in/out）"""
-    svc, _, clip = _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository)
-
-    # 验证裁剪时长
-    try:
-        _validate_trim(body.trim_start, body.trim_end, clip.duration)
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-
-    # 更新 config
-    config = dict(_get_clip_config(clip))
-    config["trim_start"] = body.trim_start
-    config["trim_end"] = body.trim_end
-    updated = svc.update_clip(clip_id, config=config)
-
-    logger.info(
-        "裁剪片段: clip_id=%s trim_start=%.2f trim_end=%.2f by user=%s",
-        clip_id,
-        body.trim_start,
-        body.trim_end,
-        current_user.user.id,
-    )
-    return _build_response(updated)
-
-
-@router.put("/clips/{clip_id}/adjustments", response_model=ClipAdjustResponse, deprecated=True)
-def adjust_all(
-    clip_id: str,
-    body: ClipAdjustmentsRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipAdjustResponse:
-    """统一调整片段的 speed / volume / trim"""
-    svc, _, clip = _get_svc_and_plan_and_clip(db, clip_id, current_user, project_repository)
-
-    update_kwargs = {}
-    config_updates = {}
-
-    if body.speed is not None:
-        update_kwargs["playback_speed"] = body.speed
-
-    if body.volume is not None:
-        config_updates["volume"] = body.volume
-
-    if body.trim_start is not None:
-        config_updates["trim_start"] = body.trim_start
-
-    if body.trim_end is not None:
-        config_updates["trim_end"] = body.trim_end
-
-    # 验证 trim
-    current_trim_start, current_trim_end = _get_trim(clip)
-    new_trim_start = body.trim_start if body.trim_start is not None else current_trim_start
-    new_trim_end = body.trim_end if body.trim_end is not None else current_trim_end
-
-    if body.trim_start is not None or body.trim_end is not None:
-        try:
-            _validate_trim(new_trim_start, new_trim_end, clip.duration)
-        except ValueError as e:
-            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-
-    if config_updates:
-        config = dict(_get_clip_config(clip))
-        config.update(config_updates)
-        update_kwargs["config"] = config
-
-    if not update_kwargs:
-        return _build_response(clip)
-
-    updated = svc.update_clip(clip_id, **update_kwargs)
-
-    logger.info(
-        "统一调整片段: clip_id=%s speed=%s volume=%s by user=%s",
-        clip_id,
-        body.speed,
-        body.volume,
-        current_user.user.id,
-    )
-    return _build_response(updated)
-
-
-@router.post("/{plan_id}/clips/batch-speed", response_model=BatchSpeedResponse, deprecated=True)
-def batch_adjust_speed(
-    plan_id: str,
-    body: BatchSpeedRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> BatchSpeedResponse:
-    """批量调整计划内所有片段的播放速度"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    clips = svc.list_clips(plan_id, limit=500, skip=0)
-    count = 0
-    for clip in clips:
-        svc.update_clip(clip.id, playback_speed=body.speed)
-        count += 1
-
-    logger.info(
-        "批量调速: plan_id=%s count=%d speed=%.2f by user=%s",
-        plan_id,
-        count,
-        body.speed,
-        current_user.user.id,
-    )
-    return BatchSpeedResponse(updated_count=count, plan_id=plan_id)

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

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

apps/api/app/api/routes/edit_plans_clips.py

@@ -1,423 +0,0 @@
-"""剪辑计划片段（Clip）CRUD 路由。"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, List, Optional
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
-from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
-from sqlalchemy.orm import Session
-
-from packages.domain.edit_plan_clip import EditPlanClipStatus
-
-from ._helpers import deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-from pydantic import BaseModel, Field
-
-
-class EditPlanClipResponse(BaseModel):
-    """剪辑片段响应体"""
-
-    id: str
-    plan_id: str
-    clip_type: str
-    order: int
-    asset_id: str = ""
-    text_content: str = ""
-    start_time: float = 0.0
-    duration: float = 0.0
-    transition_effect: str = "cut"
-    transition_duration: float = 0.0
-    playback_speed: float = 1.0
-    status: str
-    config: dict[str, Any] = Field(default_factory=dict)
-    created_at: Optional[str] = None
-    updated_at: Optional[str] = None
-
-
-class EditPlanClipListResponse(BaseModel):
-    """剪辑片段列表响应体"""
-
-    items: List[EditPlanClipResponse]
-    total: int
-
-
-class EditPlanClipCreateRequest(BaseModel):
-    """创建剪辑片段请求体"""
-
-    clip_type: str = Field(
-        ..., min_length=1, max_length=50, description="片段类型: main/intro/outro/overlay/background/b_roll 等"
-    )
-    order: int = Field(..., ge=0, description="排序序号")
-    asset_id: str = Field(default="", max_length=64, description="关联素材 ID")
-    text_content: str = Field(default="", max_length=5000, description="文本内容（字幕/配音等）")
-    start_time: float = Field(default=0.0, ge=0.0, description="起始时间 (秒)")
-    duration: float = Field(default=0.0, ge=0.0, description="时长 (秒)")
-    transition_effect: str = Field(default="cut", max_length=50, description="转场效果")
-    transition_duration: float = Field(default=0.0, ge=0.0, description="转场时长 (秒)")
-    playback_speed: float = Field(default=1.0, gt=0.0, le=10.0, description="播放速度倍率")
-    config: dict[str, Any] = Field(default_factory=dict, description="扩展配置 (JSON)")
-
-
-class EditPlanClipUpdateRequest(BaseModel):
-    """更新剪辑片段请求体"""
-
-    clip_type: Optional[str] = Field(default=None, min_length=1, max_length=50, description="片段类型")
-    order: Optional[int] = Field(default=None, ge=0, description="排序序号")
-    asset_id: Optional[str] = Field(default=None, max_length=64, description="关联素材 ID")
-    text_content: Optional[str] = Field(default=None, max_length=5000, description="文本内容")
-    start_time: Optional[float] = Field(default=None, ge=0.0, description="起始时间 (秒)")
-    duration: Optional[float] = Field(default=None, ge=0.0, description="时长 (秒)")
-    transition_effect: Optional[str] = Field(default=None, max_length=50, description="转场效果")
-    transition_duration: Optional[float] = Field(default=None, ge=0.0, description="转场时长 (秒)")
-    playback_speed: Optional[float] = Field(default=None, gt=0.0, le=10.0, description="播放速度倍率")
-    config: Optional[dict[str, Any]] = Field(default=None, description="扩展配置 (JSON)")
-
-
-# ── Helpers ──────────────────────────────────────────────────────────────────
-
-
-def _check_plan_access(plan_id: str, user_id: str, project_repository: Any, db: Session) -> Any:
-    """验证用户是否有权限访问该剪辑计划（通过项目关联）。
-    返回 plan 对象供后续使用，避免重复查询。
-    """
-    from app.services.edit_plan_service import EditPlanService
-
-    from ._helpers import check_project_access
-
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if plan is None:
-        raise HTTPException(status_code=404, detail=f"剪辑计划不存在: {plan_id}")
-    if plan.project_id:
-        check_project_access(plan.project_id, user_id, project_repository)
-    return plan
-
-
-def _clip_to_response(clip) -> EditPlanClipResponse:
-    """将领域对象转换为响应体"""
-    return EditPlanClipResponse(
-        id=clip.id,
-        plan_id=clip.plan_id,
-        clip_type=clip.clip_type,
-        order=clip.order,
-        asset_id=clip.asset_id or "",
-        text_content=clip.text_content or "",
-        start_time=clip.start_time,
-        duration=clip.duration,
-        transition_effect=clip.transition_effect or "cut",
-        transition_duration=clip.transition_duration or 0.0,
-        playback_speed=clip.playback_speed or 1.0,
-        status=clip.status.value if hasattr(clip.status, "value") else str(clip.status),
-        config=clip.config or {},
-        created_at=clip.created_at.isoformat() if clip.created_at else None,
-        updated_at=clip.updated_at.isoformat() if clip.updated_at else None,
-    )
-
-
-def _get_svc(db: Session):
-    """获取 EditPlanService 实例"""
-    from app.services.edit_plan_service import EditPlanService
-
-    return EditPlanService(db)
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-@router.get("", response_model=EditPlanClipListResponse, deprecated=True)
-def list_clips(
-    plan_id: str,
-    status_filter: Optional[str] = Query(None, alias="status", description="按状态过滤"),
-    skip: int = Query(0, ge=0, description="分页偏移"),
-    limit: int = Query(100, ge=1, le=500, description="每页数量"),
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> EditPlanClipListResponse:
-    """获取剪辑计划的片段列表"""
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-    status_enum = EditPlanClipStatus(status_filter) if status_filter else None
-    clips = svc.list_clips(plan_id, status=status_enum, skip=skip, limit=limit)
-    total = svc.count_clips(plan_id, status=status_enum)
-
-    return EditPlanClipListResponse(
-        items=[_clip_to_response(c) for c in clips],
-        total=total,
-    )
-
-
-@router.post("", response_model=EditPlanClipResponse, status_code=status.HTTP_201_CREATED, deprecated=True)
-def create_clip(
-    plan_id: str,
-    body: EditPlanClipCreateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> EditPlanClipResponse:
-    """创建剪辑片段"""
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-    try:
-        clip = svc.create_clip(
-            plan_id=plan_id,
-            clip_type=body.clip_type,
-            order=body.order,
-            asset_id=body.asset_id,
-            text_content=body.text_content,
-            start_time=body.start_time,
-            duration=body.duration,
-            transition_effect=body.transition_effect,
-            transition_duration=body.transition_duration,
-            playback_speed=body.playback_speed,
-            config=body.config,
-        )
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-
-    logger.info("创建剪辑片段: plan_id=%s clip_id=%s by user=%s", plan_id, clip.id, current_user.user.id)
-    return _clip_to_response(clip)
-
-
-@router.get("/{clip_id}", response_model=EditPlanClipResponse, deprecated=True)
-def get_clip(
-    plan_id: str,
-    clip_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> EditPlanClipResponse:
-    """获取剪辑片段详情"""
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-    clip = svc.get_clip(clip_id)
-    if clip is None:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-    if clip.plan_id != plan_id:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-
-    return _clip_to_response(clip)
-
-
-@router.put("/{clip_id}", response_model=EditPlanClipResponse, deprecated=True)
-def update_clip(
-    plan_id: str,
-    clip_id: str,
-    body: EditPlanClipUpdateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> EditPlanClipResponse:
-    """更新剪辑片段"""
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-    # 验证 clip 属于该 plan
-    clip = svc.get_clip(clip_id)
-    if clip is None:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-    if clip.plan_id != plan_id:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-
-    try:
-        updated = svc.update_clip(
-            clip_id,
-            clip_type=body.clip_type,
-            order=body.order,
-            asset_id=body.asset_id,
-            text_content=body.text_content,
-            start_time=body.start_time,
-            duration=body.duration,
-            transition_effect=body.transition_effect,
-            transition_duration=body.transition_duration,
-            playback_speed=body.playback_speed,
-            config=body.config,
-        )
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-
-    logger.info("更新剪辑片段: plan_id=%s clip_id=%s by user=%s", plan_id, clip_id, current_user.user.id)
-    return _clip_to_response(updated)
-
-
-@router.delete(
-    "/{clip_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response, deprecated=True
-)
-def delete_clip(
-    plan_id: str,
-    clip_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> None:
-    """删除剪辑片段"""
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-    # 验证 clip 属于该 plan
-    clip = svc.get_clip(clip_id)
-    if clip is None:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-    if clip.plan_id != plan_id:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-
-    deleted = svc.delete_clip(clip_id)
-    if not deleted:
-        raise HTTPException(status_code=404, detail=f"片段不存在: {clip_id}")
-
-    logger.info("删除剪辑片段: plan_id=%s clip_id=%s by user=%s", plan_id, clip_id, current_user.user.id)
-    return None
-
-
-# ── 片段分割与合并 ──────────────────────────────────────────────────────────
-
-
-class SplitClipRequest(BaseModel):
-    """分割片段请求体"""
-
-    split_time: float = Field(..., gt=0, description="分割点（秒，相对于片段起始）")
-
-
-class MergeClipsRequest(BaseModel):
-    """合并片段请求体"""
-
-    clip_ids: list[str] = Field(..., min_length=2, description="要合并的片段 ID 列表")
-
-
-@router.post(
-    "/{clip_id}/split",
-    response_model=dict[str, Any],
-    summary="分割片段",
-    status_code=status.HTTP_200_OK,
-    deprecated=True,
-)
-def split_clip(
-    plan_id: str,
-    clip_id: str,
-    body: SplitClipRequest,
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    db: Session = Depends(get_db_session),
-    project_repository: Any = Depends(get_project_repository),
-) -> dict[str, Any]:
-    """将一个片段从指定时间点分割为两个片段。
-
-    分割后原片段变为左半部分，新增右半部分片段，后续片段顺序自动后移。
-    若片段有关联素材，会自动设置 trim_start/trim_end 标记裁剪范围。
-    """
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-    clip = svc.get_clip(clip_id)
-    if clip is None or clip.plan_id != plan_id:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"片段不存在: {clip_id}",
-        )
-
-    try:
-        result = svc.split_clip(clip_id, body.split_time)
-    except ValueError as e:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=str(e),
-        ) from e
-
-    left = result["left_clip"]
-    right = result["right_clip"]
-    logger.info("分割片段: plan_id=%s clip_id=%s by user=%s", plan_id, clip_id, current_user.user.id)
-
-    return {
-        "left_clip": {
-            "id": left.id,
-            "plan_id": left.plan_id,
-            "clip_type": left.clip_type,
-            "order": left.order,
-            "duration": left.duration,
-            "start_time": left.start_time,
-        },
-        "right_clip": {
-            "id": right.id,
-            "plan_id": right.plan_id,
-            "clip_type": right.clip_type,
-            "order": right.order,
-            "duration": right.duration,
-            "start_time": right.start_time,
-        },
-    }
-
-
-@router.post(
-    "/merge",
-    response_model=dict[str, Any],
-    summary="合并多个连续片段",
-    status_code=status.HTTP_200_OK,
-    deprecated=True,
-)
-def merge_clips(
-    plan_id: str,
-    body: MergeClipsRequest,
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    db: Session = Depends(get_db_session),
-    project_repository: Any = Depends(get_project_repository),
-) -> dict[str, Any]:
-    """将多个连续的同类型片段合并为一个片段。
-
-    合并要求：
-    - 至少 2 个片段
-    - 属于同一剪辑计划
-    - order 连续
-    - 类型相同
-
-    合并后保留第一个片段，其余删除，后续片段顺序自动前移。
-    """
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-
-    # 校验所有片段都属于该 plan
-    for cid in body.clip_ids:
-        clip = svc.get_clip(cid)
-        if clip is None or clip.plan_id != plan_id:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"片段不存在: {cid}",
-            )
-
-    try:
-        merged = svc.merge_clips(body.clip_ids)
-    except ValueError as e:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=str(e),
-        ) from e
-
-    logger.info(
-        "合并片段: plan_id=%s clip_count=%d by user=%s",
-        plan_id,
-        len(body.clip_ids),
-        current_user.user.id,
-    )
-
-    return {
-        "id": merged.id,
-        "plan_id": merged.plan_id,
-        "clip_type": merged.clip_type,
-        "order": merged.order,
-        "duration": merged.duration,
-        "text_content": merged.text_content,
-    }

apps/api/app/api/routes/edit_plans_clips_batch.py

@@ -1,245 +0,0 @@
-"""剪辑计划片段批量操作 API。"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, List
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
-from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, Field
-from sqlalchemy.orm import Session
-
-from ._helpers import deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-
-class ClipReorderItem(BaseModel):
-    """重排序条目"""
-
-    clip_id: str
-    new_order: int = Field(..., ge=0, description="新的排序序号")
-
-
-class ClipReorderRequest(BaseModel):
-    """片段重排序请求"""
-
-    items: List[ClipReorderItem] = Field(..., min_length=1, max_length=500, description="重排序条目列表")
-
-
-class ClipReorderResponse(BaseModel):
-    """片段重排序响应"""
-
-    success: bool
-    updated_count: int
-    message: str = ""
-
-
-class ClipBatchDeleteRequest(BaseModel):
-    """批量删除片段请求"""
-
-    clip_ids: List[str] = Field(..., min_length=1, max_length=500, description="要删除的片段ID列表")
-
-
-class ClipBatchDeleteResponse(BaseModel):
-    """批量删除片段响应"""
-
-    success: bool
-    deleted_count: int
-    message: str = ""
-
-
-class ClipsFromAssetsRequest(BaseModel):
-    """从素材批量创建片段请求"""
-
-    asset_ids: List[str] = Field(..., min_length=1, max_length=200, description="素材 ID 列表，按顺序追加到时间线末尾")
-    clip_type: str = Field(default="main", description="片段类型，默认 main")
-
-
-class ClipsFromAssetsResponse(BaseModel):
-    """从素材批量创建片段响应"""
-
-    success: bool
-    created_count: int
-    message: str = ""
-    clip_ids: List[str] = Field(default_factory=list, description="创建的片段ID列表")
-
-
-# ── Helpers ──────────────────────────────────────────────────────────────────
-
-
-def _check_plan_access(plan_id: str, user_id: str, project_repository: Any, db: Session) -> Any:
-    """验证用户是否有权限访问该剪辑计划，返回 plan 对象。"""
-    from app.services.edit_plan_service import EditPlanService
-
-    from ._helpers import check_project_access
-
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if plan is None:
-        raise HTTPException(status_code=404, detail=f"剪辑计划不存在: {plan_id}")
-    if plan.project_id:
-        check_project_access(plan.project_id, user_id, project_repository)
-    return plan
-
-
-def _get_svc(db: Session):
-    """获取 EditPlanService 实例"""
-    from app.services.edit_plan_service import EditPlanService
-
-    return EditPlanService(db)
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-@router.post("/reorder", response_model=ClipReorderResponse, deprecated=True)
-def reorder_clips(
-    plan_id: str,
-    body: ClipReorderRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipReorderResponse:
-    """批量重排序片段
-
-    前端拖拽调整顺序后，一次性提交所有变更的 order。
-    自动触发编辑状态回退（从 completed/failed 切回 editing）。
-    """
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-
-    # 验证所有 clip 都属于该 plan
-    clip_ids = [item.clip_id for item in body.items]
-    existing_clips = svc.list_clips(plan_id, skip=0, limit=10000)
-    existing_ids = {c.id for c in existing_clips}
-
-    invalid_ids = [cid for cid in clip_ids if cid not in existing_ids]
-    if invalid_ids:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"以下片段不属于该计划: {', '.join(invalid_ids[:5])}",
-        )
-
-    # 执行重排序
-    updated_count = 0
-    for item in body.items:
-        try:
-            svc.update_clip(item.clip_id, order=item.new_order)
-            updated_count += 1
-        except ValueError as e:
-            logger.warning("重排序片段失败: clip_id=%s error=%s", item.clip_id, e)
-
-    logger.info(
-        "批量重排序片段: plan_id=%s count=%d by user=%s",
-        plan_id,
-        updated_count,
-        current_user.user.id,
-    )
-
-    return ClipReorderResponse(
-        success=True,
-        updated_count=updated_count,
-        message=f"成功更新 {updated_count} 个片段的顺序",
-    )
-
-
-@router.post("/batch-delete", response_model=ClipBatchDeleteResponse, deprecated=True)
-def batch_delete_clips(
-    plan_id: str,
-    body: ClipBatchDeleteRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipBatchDeleteResponse:
-    """批量删除片段
-
-    自动触发编辑状态回退（从 completed/failed 切回 editing）。
-    """
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-
-    # 验证所有 clip 都属于该 plan
-    existing_clips = svc.list_clips(plan_id, skip=0, limit=10000)
-    existing_ids = {c.id for c in existing_clips}
-
-    valid_ids = [cid for cid in body.clip_ids if cid in existing_ids]
-    skipped = len(body.clip_ids) - len(valid_ids)
-
-    # 执行删除
-    deleted_count = 0
-    for clip_id in valid_ids:
-        if svc.delete_clip(clip_id):
-            deleted_count += 1
-
-    message = f"成功删除 {deleted_count} 个片段"
-    if skipped > 0:
-        message += f"，跳过 {skipped} 个不存在的片段"
-
-    logger.info(
-        "批量删除片段: plan_id=%s deleted=%d skipped=%d by user=%s",
-        plan_id,
-        deleted_count,
-        skipped,
-        current_user.user.id,
-    )
-
-    return ClipBatchDeleteResponse(
-        success=True,
-        deleted_count=deleted_count,
-        message=message,
-    )
-
-
-@router.post("/from-assets", response_model=ClipsFromAssetsResponse, deprecated=True)
-def create_clips_from_assets(
-    plan_id: str,
-    body: ClipsFromAssetsRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipsFromAssetsResponse:
-    """从素材批量创建片段（追加到时间线末尾）
-
-    一次性将多个素材作为片段添加到剪辑计划，自动读取素材时长。
-    自动触发编辑状态回退（completed/failed → editing）。
-    """
-    _check_plan_access(plan_id, current_user.user.id, project_repository, db)
-
-    svc = _get_svc(db)
-
-    try:
-        clips = svc.create_clips_from_assets(
-            plan_id=plan_id,
-            asset_ids=body.asset_ids,
-            clip_type=body.clip_type,
-        )
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-
-    clip_ids = [c.id for c in clips]
-
-    logger.info(
-        "从素材批量创建片段: plan_id=%s count=%d by user=%s",
-        plan_id,
-        len(clips),
-        current_user.user.id,
-    )
-
-    return ClipsFromAssetsResponse(
-        success=True,
-        created_count=len(clips),
-        message=f"成功创建 {len(clips)} 个片段",
-        clip_ids=clip_ids,
-    )

apps/api/app/api/routes/edit_plans_cover.py

@@ -1,317 +0,0 @@
-"""封面管理 API.
-
-- GET    /{plan_id}/cover              获取封面配置
-- PUT    /{plan_id}/cover              更新封面配置
-- POST   /{plan_id}/cover/extract      从指定片段抽帧生成封面
-- POST   /{plan_id}/cover/smart        智能选帧生成封面
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, Optional
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.core.storage import get_storage_service
-from app.dependencies import (
-    get_asset_repository,
-    get_db_session,
-    get_project_repository,
-)
-from app.services import EditPlanService
-from app.services.cover_service import CoverService
-from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, Field
-from sqlalchemy.orm import Session
-
-from packages.domain.config_schemas import normalize_plan_config
-
-from ._helpers import check_project_access, deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-
-class CoverConfigResponse(BaseModel):
-    """封面配置响应"""
-
-    type: str = Field(..., description="封面类型: ai_frame / manual / upload")
-    image_url: str = Field(default="", description="封面图片 URL")
-    frame_time: Optional[float] = Field(default=None, description="抽帧时间点（秒）")
-
-
-class CoverUpdateRequest(BaseModel):
-    """更新封面配置请求"""
-
-    type: Optional[str] = Field(default=None, description="封面类型")
-    image_url: Optional[str] = Field(default=None, description="封面图片 URL")
-    frame_time: Optional[float] = Field(default=None, ge=0.0, description="抽帧时间点（秒）")
-
-
-class CoverExtractRequest(BaseModel):
-    """从片段抽帧生成封面请求"""
-
-    clip_id: str = Field(..., description="片段 ID")
-    frame_time: float = Field(1.0, ge=0.0, description="抽帧时间点（秒）")
-
-
-class CoverSmartRequest(BaseModel):
-    """智能选帧请求"""
-
-    clip_id: Optional[str] = Field(default=None, description="指定片段 ID（不传则用第一个视频片段）")
-
-
-class CoverGenerateResponse(BaseModel):
-    """封面生成响应"""
-
-    type: str = Field(..., description="封面类型")
-    image_url: str = Field(..., description="封面图片 URL")
-    frame_time: Optional[float] = Field(default=None, description="抽帧时间点（秒）")
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-@router.get("/{plan_id}/cover", response_model=CoverConfigResponse, deprecated=True)
-def get_cover(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> CoverConfigResponse:
-    """获取封面配置"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    cover = CoverService.get_cover_config(plan.config or {})
-    return CoverConfigResponse(**cover)
-
-
-@router.put("/{plan_id}/cover", response_model=CoverConfigResponse, deprecated=True)
-def update_cover(
-    plan_id: str,
-    body: CoverUpdateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> CoverConfigResponse:
-    """更新封面配置
-
-    用于：设置上传的封面图片 URL、切换封面类型、调整时间点等。
-    """
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 合并更新
-    current_cover = CoverService.get_cover_config(plan.config or {})
-    updates = body.model_dump(exclude_none=True)
-    new_cover = {**current_cover, **updates}
-
-    # 验证 type 值
-    valid_types = {"ai_frame", "manual", "upload", "ai_regenerate"}
-    if "type" in updates and updates["type"] not in valid_types:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"无效的封面类型: {updates['type']}，有效值: {valid_types}",
-        )
-
-    # 更新到 plan.config
-    current_config = dict(plan.config or {})
-    current_config["cover"] = new_cover
-    normalized = normalize_plan_config(current_config)
-    updated_plan = svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
-
-    result = CoverService.get_cover_config(updated_plan.config or {})
-    logger.info("更新封面配置: plan_id=%s type=%s by user=%s", plan_id, result["type"], current_user.user.id)
-    return CoverConfigResponse(**result)
-
-
-@router.post("/{plan_id}/cover/extract", response_model=CoverGenerateResponse, deprecated=True)
-def extract_cover(
-    plan_id: str,
-    body: CoverExtractRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-    storage_service: Any = Depends(get_storage_service),
-    asset_repository: Any = Depends(get_asset_repository),
-) -> CoverGenerateResponse:
-    """从指定片段的指定时间点抽帧生成封面"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 获取片段对应的素材
-    clip = svc.get_clip(body.clip_id)
-    if not clip:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"片段不存在: {body.clip_id}",
-        )
-
-    if clip.plan_id != plan_id:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="片段不属于该剪辑计划",
-        )
-
-    if not clip.asset_id:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="片段没有关联素材，无法抽帧",
-        )
-
-    # 抽帧生成封面
-    cover_svc = CoverService(storage_service, asset_repository)
-    try:
-        cover_data = cover_svc.extract_cover_from_clip(
-            plan_id=plan_id,
-            asset_id=clip.asset_id,
-            frame_time=body.frame_time,
-        )
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-    except RuntimeError as e:
-        logger.error("封面抽帧失败: plan_id=%s clip_id=%s error=%s", plan_id, body.clip_id, e)
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"封面抽帧失败: {e}",
-        ) from e
-
-    # 更新到 plan.config.cover
-    current_config = dict(plan.config or {})
-    current_config["cover"] = cover_data
-    normalized = normalize_plan_config(current_config)
-    svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
-
-    logger.info(
-        "封面抽帧完成: plan_id=%s clip_id=%s time=%.2fs by user=%s",
-        plan_id,
-        body.clip_id,
-        body.frame_time,
-        current_user.user.id,
-    )
-    return CoverGenerateResponse(**cover_data)
-
-
-@router.post("/{plan_id}/cover/smart", response_model=CoverGenerateResponse, deprecated=True)
-def smart_cover(
-    plan_id: str,
-    body: CoverSmartRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-    storage_service: Any = Depends(get_storage_service),
-    asset_repository: Any = Depends(get_asset_repository),
-) -> CoverGenerateResponse:
-    """智能选帧生成封面
-
-    从指定片段（或第一个视频片段）中智能选取一帧作为封面。
-    当前实现：取片段第3秒帧（后续可优化为多帧选最清晰）。
-    """
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 确定使用哪个片段
-    clip_id = body.clip_id
-    asset_id = ""
-
-    if clip_id:
-        clip = svc.get_clip(clip_id)
-        if not clip:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"片段不存在: {clip_id}",
-            )
-        if clip.plan_id != plan_id:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="片段不属于该剪辑计划",
-            )
-        if not clip.asset_id:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="片段没有关联素材",
-            )
-        asset_id = clip.asset_id
-    else:
-        # 找第一个有素材的视频片段
-        clips = svc.list_clips(plan_id, limit=50, skip=0)
-        for c in clips:
-            if c.asset_id and c.clip_type == "video":
-                asset_id = c.asset_id
-                clip_id = c.id
-                break
-
-        if not asset_id:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="没有找到可用的视频片段",
-            )
-
-    # 智能选帧
-    cover_svc = CoverService(storage_service, asset_repository)
-    try:
-        cover_data = cover_svc.generate_smart_cover(
-            plan_id=plan_id,
-            asset_id=asset_id,
-        )
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-    except RuntimeError as e:
-        logger.error("智能封面生成失败: plan_id=%s error=%s", plan_id, e)
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"智能封面生成失败: {e}",
-        ) from e
-
-    # 更新到 plan.config.cover
-    current_config = dict(plan.config or {})
-    current_config["cover"] = cover_data
-    normalized = normalize_plan_config(current_config)
-    svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
-
-    logger.info(
-        "智能封面生成完成: plan_id=%s clip_id=%s by user=%s",
-        plan_id,
-        clip_id,
-        current_user.user.id,
-    )
-    return CoverGenerateResponse(**cover_data)

apps/api/app/api/routes/edit_plans_export.py

@@ -1,276 +0,0 @@
-"""导出设置 API.
-
-- GET    /{plan_id}/export              获取导出配置
-- PUT    /{plan_id}/export              更新导出配置
-- GET    /export-presets                 导出预设列表
-"""
-
-from __future__ import annotations
-
-import logging
-import re
-from typing import Any, List, Optional
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
-from app.services import EditPlanService
-from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, Field, validator
-from sqlalchemy.orm import Session
-
-from packages.domain.config_schemas import normalize_plan_config
-
-from ._helpers import check_project_access, deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── 导出预设 ──────────────────────────────────────────────────────────────────
-
-EXPORT_PRESETS = [
-    {
-        "id": "export_1080p_30",
-        "name": "1080P 高清",
-        "resolution": "1080x1920",
-        "fps": 30,
-        "video_bitrate": 8000,
-        "audio_bitrate": 128,
-        "format": "mp4",
-        "quality_preset": "balanced",
-        "description": "竖屏高清，适合短视频平台",
-        "size_hint": "约 10MB/分钟",
-    },
-    {
-        "id": "export_1080p_60",
-        "name": "1080P 高帧率",
-        "resolution": "1080x1920",
-        "fps": 60,
-        "video_bitrate": 12000,
-        "audio_bitrate": 128,
-        "format": "mp4",
-        "quality_preset": "high",
-        "description": "60帧高帧率，流畅运动画面",
-        "size_hint": "约 18MB/分钟",
-    },
-    {
-        "id": "export_720p_30",
-        "name": "720P 流畅",
-        "resolution": "720x1280",
-        "fps": 30,
-        "video_bitrate": 4000,
-        "audio_bitrate": 128,
-        "format": "mp4",
-        "quality_preset": "fast",
-        "description": "快速导出，文件较小",
-        "size_hint": "约 5MB/分钟",
-    },
-    {
-        "id": "export_4k_30",
-        "name": "4K 超清",
-        "resolution": "2160x3840",
-        "fps": 30,
-        "video_bitrate": 20000,
-        "audio_bitrate": 192,
-        "format": "mp4",
-        "quality_preset": "best",
-        "description": "4K超清画质，专业品质",
-        "size_hint": "约 30MB/分钟",
-    },
-    {
-        "id": "export_1080p_30_mov",
-        "name": "1080P ProRes",
-        "resolution": "1080x1920",
-        "fps": 30,
-        "video_bitrate": 15000,
-        "audio_bitrate": 256,
-        "format": "mov",
-        "quality_preset": "high",
-        "description": "MOV格式，适合后期剪辑",
-        "size_hint": "约 25MB/分钟",
-    },
-]
-
-VALID_QUALITY_PRESETS = {"ultra_fast", "fast", "balanced", "high", "best"}
-VALID_FORMATS = {"mp4", "mov"}
-
-RESOLUTION_PATTERN = re.compile(r"^\d+x\d+$")
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-
-class ExportConfigResponse(BaseModel):
-    """导出配置响应"""
-
-    resolution: str
-    fps: int
-    video_bitrate: int
-    audio_bitrate: int
-    format: str
-    quality_preset: str
-    watermark_enabled: bool
-    watermark_text: str
-
-
-class ExportUpdateRequest(BaseModel):
-    """更新导出配置请求"""
-
-    resolution: Optional[str] = None
-    fps: Optional[int] = Field(default=None, ge=15, le=60)
-    video_bitrate: Optional[int] = Field(default=None, ge=1000, le=20000)
-    audio_bitrate: Optional[int] = Field(default=None, ge=64, le=320)
-    format: Optional[str] = None
-    quality_preset: Optional[str] = None
-    watermark_enabled: Optional[bool] = None
-    watermark_text: Optional[str] = None
-
-    @validator("resolution")
-    def validate_resolution(cls, v):
-        if v is None:
-            return v
-        if not RESOLUTION_PATTERN.match(v):
-            raise ValueError("分辨率格式错误，应为 宽x高，如 1080x1920")
-        w, h = v.split("x")
-        if int(w) < 100 or int(h) < 100:
-            raise ValueError("分辨率数值过小")
-        if int(w) > 4096 or int(h) > 4096:
-            raise ValueError("分辨率数值过大，最大 4096x4096")
-        return v
-
-    @validator("format")
-    def validate_format(cls, v):
-        if v is None:
-            return v
-        if v not in VALID_FORMATS:
-            raise ValueError(f"无效格式: {v}，支持: {VALID_FORMATS}")
-        return v
-
-    @validator("quality_preset")
-    def validate_quality_preset(cls, v):
-        if v is None:
-            return v
-        if v not in VALID_QUALITY_PRESETS:
-            raise ValueError(f"无效质量预设: {v}，支持: {VALID_QUALITY_PRESETS}")
-        return v
-
-
-class ExportPresetItem(BaseModel):
-    """导出预设条目"""
-
-    id: str
-    name: str
-    resolution: str
-    fps: int
-    video_bitrate: int
-    audio_bitrate: int
-    format: str
-    quality_preset: str
-    description: str
-    size_hint: str
-
-
-class ExportPresetListResponse(BaseModel):
-    """导出预设列表响应"""
-
-    items: List[ExportPresetItem]
-    total: int
-
-
-# ── Helpers ──────────────────────────────────────────────────────────────────
-
-
-def _get_export_config(plan_config: dict) -> dict:
-    e = plan_config.get("export", {})
-    if not isinstance(e, dict):
-        e = {}
-    return {
-        "resolution": e.get("resolution", "1080x1920"),
-        "fps": e.get("fps", 30),
-        "video_bitrate": e.get("video_bitrate", 8000),
-        "audio_bitrate": e.get("audio_bitrate", 128),
-        "format": e.get("format", "mp4"),
-        "quality_preset": e.get("quality_preset", "balanced"),
-        "watermark_enabled": e.get("watermark_enabled", False),
-        "watermark_text": e.get("watermark_text", ""),
-    }
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-@router.get("/export-presets", response_model=ExportPresetListResponse, deprecated=True)
-def list_export_presets(
-    current_user: AuthenticatedUser = Depends(get_current_user),
-) -> ExportPresetListResponse:
-    """获取导出预设列表"""
-    items = [ExportPresetItem(**p) for p in EXPORT_PRESETS]
-    return ExportPresetListResponse(items=items, total=len(items))
-
-
-@router.get("/{plan_id}/export", response_model=ExportConfigResponse, deprecated=True)
-def get_export_config(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ExportConfigResponse:
-    """获取导出配置"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    config = _get_export_config(plan.config or {})
-    return ExportConfigResponse(**config)
-
-
-@router.put("/{plan_id}/export", response_model=ExportConfigResponse, deprecated=True)
-def update_export_config(
-    plan_id: str,
-    body: ExportUpdateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ExportConfigResponse:
-    """更新导出配置"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 合并更新
-    current = _get_export_config(plan.config or {})
-    updates = body.model_dump(exclude_none=True)
-    new_export = {**current, **updates}
-
-    # 更新到 plan.config
-    current_config = dict(plan.config or {})
-    current_config["export"] = new_export
-    normalized = normalize_plan_config(current_config)
-    updated_plan = svc.update_plan_config(plan_id, {"export": normalized["export"]})
-
-    result = _get_export_config(updated_plan.config or {})
-    logger.info(
-        "更新导出配置: plan_id=%s resolution=%s fps=%d by user=%s",
-        plan_id,
-        result["resolution"],
-        result["fps"],
-        current_user.user.id,
-    )
-    return ExportConfigResponse(**result)

apps/api/app/api/routes/edit_plans_filter.py

@@ -1,199 +0,0 @@
-"""滤镜调色 API.
-
-- GET    /filter-presets            滤镜预设列表
-- GET    /{plan_id}/filter          获取全局滤镜配置
-- PUT    /{plan_id}/filter          更新全局滤镜配置
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, List, Optional
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
-from app.services import EditPlanService
-from fastapi import APIRouter, Depends, HTTPException, Query, status
-from pydantic import BaseModel, Field
-from sqlalchemy.orm import Session
-
-from packages.domain.config_schemas import normalize_plan_config
-from packages.domain.filter_presets import (
-    FilterPreset,
-    get_filter_preset,
-    list_filter_presets,
-)
-
-from ._helpers import check_project_access, deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-
-class FilterPresetResponse(BaseModel):
-    """滤镜预设响应"""
-
-    id: str
-    name: str
-    category: str
-    description: str
-    tags: List[str] = Field(default_factory=list)
-
-
-class FilterConfigResponse(BaseModel):
-    """滤镜配置响应"""
-
-    enabled: bool
-    preset_id: str
-    intensity: int
-    brightness: float
-    contrast: float
-    saturation: float
-    warmth: float
-
-
-class FilterUpdateRequest(BaseModel):
-    """更新滤镜配置请求"""
-
-    enabled: Optional[bool] = None
-    preset_id: Optional[str] = None
-    intensity: Optional[int] = Field(default=None, ge=0, le=100)
-    brightness: Optional[float] = Field(default=None, ge=-1.0, le=1.0)
-    contrast: Optional[float] = Field(default=None, ge=0.0, le=2.0)
-    saturation: Optional[float] = Field(default=None, ge=0.0, le=3.0)
-    warmth: Optional[float] = Field(default=None, ge=-1.0, le=1.0)
-
-
-class FilterPresetListResponse(BaseModel):
-    """滤镜预设列表响应"""
-
-    items: List[FilterPresetResponse]
-    total: int
-
-
-# ── Helpers ──────────────────────────────────────────────────────────────────
-
-
-def _preset_to_response(p: FilterPreset) -> FilterPresetResponse:
-    return FilterPresetResponse(
-        id=p.id,
-        name=p.name,
-        category=p.category,
-        description=p.description,
-        tags=list(p.tags),
-    )
-
-
-def _get_filter_config(plan_config: dict) -> dict:
-    """从 plan.config 中提取滤镜配置"""
-    f = plan_config.get("filter", {})
-    if not isinstance(f, dict):
-        f = {}
-    return {
-        "enabled": f.get("enabled", False),
-        "preset_id": f.get("preset_id", "filter_none"),
-        "intensity": f.get("intensity", 100),
-        "brightness": f.get("brightness", 0.0),
-        "contrast": f.get("contrast", 1.0),
-        "saturation": f.get("saturation", 1.0),
-        "warmth": f.get("warmth", 0.0),
-    }
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-@router.get("/filter-presets", response_model=FilterPresetListResponse, deprecated=True)
-def list_presets(
-    category: Optional[str] = Query(default=None, description="按分类筛选"),
-    keyword: Optional[str] = Query(default=None, description="关键词搜索"),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-) -> FilterPresetListResponse:
-    """获取滤镜预设列表"""
-    presets = list_filter_presets(category=category, keyword=keyword)
-    items = [_preset_to_response(p) for p in presets]
-    return FilterPresetListResponse(items=items, total=len(items))
-
-
-@router.get("/{plan_id}/filter", response_model=FilterConfigResponse, deprecated=True)
-def get_filter(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> FilterConfigResponse:
-    """获取剪辑计划的全局滤镜配置"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    config = _get_filter_config(plan.config or {})
-    return FilterConfigResponse(**config)
-
-
-@router.put("/{plan_id}/filter", response_model=FilterConfigResponse, deprecated=True)
-def update_filter(
-    plan_id: str,
-    body: FilterUpdateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> FilterConfigResponse:
-    """更新全局滤镜配置"""
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 验证 preset_id
-    updates = body.model_dump(exclude_none=True)
-    if "preset_id" in updates:
-        preset = get_filter_preset(updates["preset_id"])
-        if preset is None:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=f"无效的滤镜预设: {updates['preset_id']}",
-            )
-
-    # 合并更新
-    current = _get_filter_config(plan.config or {})
-    new_filter = {**current, **updates}
-
-    # 如果设为原图 preset，自动关闭
-    if new_filter["preset_id"] == "filter_none":
-        new_filter["enabled"] = False
-
-    # 更新到 plan.config
-    current_config = dict(plan.config or {})
-    current_config["filter"] = new_filter
-    normalized = normalize_plan_config(current_config)
-    updated_plan = svc.update_plan_config(plan_id, {"filter": normalized["filter"]})
-
-    result = _get_filter_config(updated_plan.config or {})
-    logger.info(
-        "更新滤镜配置: plan_id=%s preset=%s intensity=%d by user=%s",
-        plan_id,
-        result["preset_id"],
-        result["intensity"],
-        current_user.user.id,
-    )
-    return FilterConfigResponse(**result)

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

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

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

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

apps/api/app/api/routes/edit_plans_transitions.py

@@ -1,274 +0,0 @@
-"""转场特效 API.
-
-- GET    /transition-presets              转场预设列表
-- PUT    /clips/{clip_id}/transition      设置单个片段转场
-- POST   /{plan_id}/transitions/batch     批量设置转场（所有片段）
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any, List, Optional
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_db_session, get_project_repository
-from app.services import EditPlanService
-from fastapi import APIRouter, Depends, HTTPException, Query, status
-from pydantic import BaseModel, Field
-from sqlalchemy.orm import Session
-
-from packages.domain.transition_presets import (
-    TransitionPreset,
-    get_transition_preset,
-    list_transition_presets,
-)
-
-from ._helpers import check_project_access, deprecated_edit_plans_api
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(
-    dependencies=[Depends(deprecated_edit_plans_api)],
-)
-
-
-# ── Schemas ──────────────────────────────────────────────────────────────────
-
-
-class TransitionPresetResponse(BaseModel):
-    """转场预设响应"""
-
-    id: str
-    name: str
-    category: str
-    description: str
-    tags: List[str] = Field(default_factory=list)
-    default_duration: float
-    min_duration: float
-    max_duration: float
-
-
-class TransitionUpdateRequest(BaseModel):
-    """更新转场请求"""
-
-    effect: str = Field(..., description="转场效果 ID")
-    duration: Optional[float] = Field(default=None, ge=0.0, description="转场时长（秒）")
-
-
-class BatchTransitionRequest(BaseModel):
-    """批量设置转场请求"""
-
-    effect: str = Field(..., description="转场效果 ID")
-    duration: Optional[float] = Field(default=None, ge=0.0, description="转场时长（秒）")
-    apply_to: str = Field(
-        default="all",
-        description="应用范围: all=所有片段, except_first=除第一个外, except_last=除最后一个, middle=中间片段",
-    )
-
-
-class ClipTransitionResponse(BaseModel):
-    """片段转场信息响应"""
-
-    clip_id: str
-    effect: str
-    duration: float
-
-
-class BatchTransitionResponse(BaseModel):
-    """批量转场响应"""
-
-    updated_count: int
-    plan_id: str
-
-
-class TransitionPresetListResponse(BaseModel):
-    """转场预设列表响应"""
-
-    items: List[TransitionPresetResponse]
-    total: int
-
-
-# ── Helpers ──────────────────────────────────────────────────────────────────
-
-
-def _preset_to_response(p: TransitionPreset) -> TransitionPresetResponse:
-    return TransitionPresetResponse(
-        id=p.id,
-        name=p.name,
-        category=p.category,
-        description=p.description,
-        tags=list(p.tags),
-        default_duration=p.default_duration,
-        min_duration=p.min_duration,
-        max_duration=p.max_duration,
-    )
-
-
-def _validate_transition(effect: str, duration: Optional[float] = None) -> tuple[str, float]:
-    """验证转场效果和时长，返回 (effect, duration)"""
-    preset = get_transition_preset(effect)
-    if preset is None:
-        raise ValueError(f"无效的转场效果: {effect}")
-
-    # 硬切特殊处理，时长强制为0
-    if effect == "transition_none" or preset.transition == "none":
-        return "cut", 0.0
-
-    final_duration = duration if duration is not None else preset.default_duration
-    if final_duration < preset.min_duration:
-        final_duration = preset.min_duration
-    if final_duration > preset.max_duration:
-        final_duration = preset.max_duration
-
-    return preset.transition, round(final_duration, 3)
-
-
-# ── Routes ───────────────────────────────────────────────────────────────────
-
-
-@router.get("/transition-presets", response_model=TransitionPresetListResponse, deprecated=True)
-def list_presets(
-    category: Optional[str] = Query(default=None, description="按分类筛选"),
-    keyword: Optional[str] = Query(default=None, description="关键词搜索"),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-) -> TransitionPresetListResponse:
-    """获取转场预设列表"""
-    presets = list_transition_presets(category=category, keyword=keyword)
-    items = [_preset_to_response(p) for p in presets]
-    return TransitionPresetListResponse(items=items, total=len(items))
-
-
-@router.put("/clips/{clip_id}/transition", response_model=ClipTransitionResponse, deprecated=True)
-def update_clip_transition(
-    clip_id: str,
-    body: TransitionUpdateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> ClipTransitionResponse:
-    """设置单个片段的转场效果"""
-    svc = EditPlanService(db)
-    clip = svc.get_clip(clip_id)
-    if not clip:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"片段不存在: {clip_id}",
-        )
-
-    plan = svc.get_plan(clip.plan_id)
-    if plan and plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 验证转场参数
-    try:
-        effect, duration = _validate_transition(body.effect, body.duration)
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-
-    # 更新片段
-    updated_clip = svc.update_clip(
-        clip_id,
-        transition_effect=effect,
-        transition_duration=duration,
-    )
-
-    logger.info(
-        "更新片段转场: clip_id=%s effect=%s duration=%.3f by user=%s",
-        clip_id,
-        effect,
-        duration,
-        current_user.user.id,
-    )
-    return ClipTransitionResponse(
-        clip_id=clip_id,
-        effect=updated_clip.transition_effect,
-        duration=updated_clip.transition_duration,
-    )
-
-
-@router.post("/{plan_id}/transitions/batch", response_model=BatchTransitionResponse, deprecated=True)
-def batch_update_transitions(
-    plan_id: str,
-    body: BatchTransitionRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> BatchTransitionResponse:
-    """批量设置计划内所有片段的转场效果
-
-    apply_to 说明：
-    - all: 所有片段
-    - except_first: 除第一个片段外（第一个片段不需要前转场）
-    - except_last: 除最后一个片段外
-    - middle: 只设置中间片段（除首尾）
-    """
-    svc = EditPlanService(db)
-    plan = svc.get_plan(plan_id)
-    if not plan:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"剪辑计划不存在: {plan_id}",
-        )
-
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 验证转场参数
-    try:
-        effect, duration = _validate_transition(body.effect, body.duration)
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
-
-    # 获取所有片段
-    clips = svc.list_clips(plan_id, limit=500, skip=0)
-    if not clips:
-        return BatchTransitionResponse(updated_count=0, plan_id=plan_id)
-
-    # 确定应用范围
-    total = len(clips)
-    if total <= 1:
-        # 只有一个片段时，只有 all 模式才应用
-        if body.apply_to != "all":
-            return BatchTransitionResponse(updated_count=0, plan_id=plan_id)
-
-    # 按 order 排序
-    clips_sorted = sorted(clips, key=lambda c: c.order)
-    indices_to_update = []
-
-    if body.apply_to == "all":
-        indices_to_update = list(range(total))
-    elif body.apply_to == "except_first":
-        indices_to_update = list(range(1, total))
-    elif body.apply_to == "except_last":
-        indices_to_update = list(range(total - 1))
-    elif body.apply_to == "middle":
-        if total <= 2:
-            indices_to_update = []
-        else:
-            indices_to_update = list(range(1, total - 1))
-    else:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"无效的 apply_to: {body.apply_to}",
-        )
-
-    # 批量更新
-    count = 0
-    for idx in indices_to_update:
-        clip = clips_sorted[idx]
-        svc.update_clip(
-            clip.id,
-            transition_effect=effect,
-            transition_duration=duration,
-        )
-        count += 1
-
-    logger.info(
-        "批量更新转场: plan_id=%s count=%d effect=%s apply_to=%s by user=%s",
-        plan_id,
-        count,
-        effect,
-        body.apply_to,
-        current_user.user.id,
-    )
-    return BatchTransitionResponse(updated_count=count, plan_id=plan_id)

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

@@ -23,60 +23,462 @@
 from __future__ import annotations
 
 import logging
+import re as _re
 from typing import Any, List, Optional
 
-from app.api.routes.edit_plans import (
-    AIRecommendRequest,
-    AIRecommendResponse,
-    BGMConfigUpdateRequest,
-    ClipStatusItem,
-    EditPlanGenerateResponse,
-    EditPlanGenerationsResponse,
-    EditPlanGenerationStatusResponse,
-    GenerateCoverRequest,
-    GenerateCoverResponse,
-)
-from app.api.routes.edit_plans_adjustments import (
-    BatchSpeedRequest,
-    BatchSpeedResponse,
-    ClipAdjustmentsRequest,
-    ClipAdjustResponse,
-    SpeedAdjustRequest,
-    TrimAdjustRequest,
-    VolumeAdjustRequest,
-)
-from app.api.routes.edit_plans_clips_batch import (
-    ClipBatchDeleteRequest,
-    ClipBatchDeleteResponse,
-    ClipReorderRequest,
-    ClipReorderResponse,
-    ClipsFromAssetsRequest,
-    ClipsFromAssetsResponse,
-)
-from app.api.routes.edit_plans_cover import (
-    CoverConfigResponse,
-    CoverExtractRequest,
-    CoverGenerateResponse,
-    CoverSmartRequest,
-    CoverUpdateRequest,
-)
-from app.api.routes.edit_plans_export import (
-    ExportConfigResponse,
-    ExportPresetListResponse,
-    ExportUpdateRequest,
-)
-from app.api.routes.edit_plans_filter import (
-    FilterConfigResponse,
-    FilterPresetListResponse,
-    FilterUpdateRequest,
-)
-from app.api.routes.edit_plans_transitions import (
-    BatchTransitionRequest,
-    BatchTransitionResponse,
-    ClipTransitionResponse,
-    TransitionPresetListResponse,
-    TransitionUpdateRequest,
-)
+from app.schemas.generation_task import GenerationTaskResponse
+from pydantic import BaseModel, Field, validator
+
+# ── Pydantic Schemas (migrated from edit_plans*) ────────────────────────────
+
+
+# ── From edit_plans.py ──────────────────────────────────────────────────────
+
+
+class ClipStatusItem(BaseModel):
+    """片段生成状态"""
+
+    clip_id: str
+    clip_type: str
+    order: int
+    status: str
+    asset_id: str
+    text_content: str
+    duration: float
+
+
+class EditPlanGenerationStatusResponse(BaseModel):
+    """剪辑计划生成进度响应体"""
+
+    plan_id: str
+    plan_status: str
+    generation_task_id: Optional[str] = None
+    generation_task_status: Optional[str] = None
+    progress: float = 0.0
+    video_url: str = ""
+    error_message: str = ""
+    clips: List[ClipStatusItem]
+
+
+class EditPlanGenerateResponse(BaseModel):
+    """剪辑计划触发生成响应体"""
+
+    plan_id: str
+    plan_status: str
+    generation_task_id: str
+    clip_count: int
+
+
+class EditPlanGenerationsResponse(BaseModel):
+    """剪辑计划关联的生成记录列表响应体"""
+
+    items: List[GenerationTaskResponse]
+    total: int
+
+
+class AIRecommendRequest(BaseModel):
+    """AI 推荐片段方案请求体"""
+
+    asset_ids: List[str] = Field(default_factory=list, description="素材 ID 列表")
+    editing_mode: str = Field(default="one_take", description="剪辑模式: one_take / pip / voice_over / voice_pip")
+    target_duration: float = Field(default=30.0, ge=1.0, le=600.0, description="目标时长（秒）")
+
+
+class AIRecommendClipItem(BaseModel):
+    """AI 推荐的单个片段"""
+
+    clip_type: str = Field(..., description="片段类型: intro / showcase / title / subtitle / cta / outro")
+    order: int = Field(..., ge=0, description="片段顺序")
+    text_content: str = Field(default="", description="文字内容")
+    duration: float = Field(..., ge=0.0, description="片段时长（秒）")
+    transition_effect: str = Field(default="cut", description="转场效果")
+    transition_duration: float = Field(default=0.0, ge=0.0, description="转场时长（秒），0 表示使用默认值")
+    asset_id: str = Field(default="", description="关联素材 ID")
+    start_time: float = Field(default=0.0, ge=0.0, description="素材截取起始时间（秒）")
+    config: dict[str, Any] = Field(default_factory=dict, description="片段额外配置")
+
+
+class AIRecommendResponse(BaseModel):
+    """AI 推荐片段方案响应体"""
+
+    plan_id: str = Field(..., description="剪辑计划 ID")
+    clips: List[AIRecommendClipItem] = Field(..., description="推荐的片段列表")
+    config: dict[str, Any] = Field(..., description="推荐的 plan config（cover/title/subtitle/bgm）")
+    total_duration: float = Field(..., ge=0.0, description="推荐方案总时长（秒）")
+    confidence: float = Field(..., ge=0.0, le=1.0, description="AI 推荐置信度 (0~1)")
+
+
+class GenerateCoverRequest(BaseModel):
+    """AI 封面生成请求体"""
+
+    asset_ids: List[str] = Field(default_factory=list, description="素材 ID 列表（确定视频来源）")
+    cover_type: str = Field(
+        default="ai_frame",
+        description="封面类型: ai_frame / manual / upload / ai_regenerate",
+    )
+    frame_time: Optional[float] = Field(
+        default=None,
+        ge=0.0,
+        description="手动选帧时间点（秒），仅 cover_type=manual 时有效",
+    )
+
+
+class GenerateCoverResponse(BaseModel):
+    """AI 封面生成响应体"""
+
+    plan_id: str = Field(..., description="剪辑计划 ID")
+    cover: dict[str, Any] = Field(..., description="封面数据（type / image_url / frame_time 等）")
+
+
+class BGMConfigUpdateRequest(BaseModel):
+    """更新BGM配置请求体"""
+
+    enabled: Optional[bool] = Field(default=None, description="是否启用 BGM")
+    source: Optional[str] = Field(default=None, description="BGM 来源: library/upload/ai_recommend")
+    asset_id: Optional[str] = Field(default=None, max_length=64, description="BGM 素材 ID")
+    preset_id: Optional[str] = Field(default=None, max_length=64, description="预设 BGM ID")
+    audio_url: Optional[str] = Field(default=None, max_length=500, description="BGM 音频 URL")
+    volume: Optional[float] = Field(default=None, ge=0.0, le=1.0, description="音量 (0.0 ~ 1.0)")
+    fade_in: Optional[float] = Field(default=None, ge=0.0, le=30.0, description="淡入时长（秒）")
+    fade_out: Optional[float] = Field(default=None, ge=0.0, le=30.0, description="淡出时长（秒）")
+    loop_enabled: Optional[bool] = Field(default=None, description="是否循环播放")
+    sidechain_enabled: Optional[bool] = Field(default=None, description="是否启用人声闪避")
+    sidechain_ratio: Optional[float] = Field(default=None, ge=0.0, le=1.0, description="闪避音量降低比例")
+
+
+# ── From edit_plans_adjustments.py ──────────────────────────────────────────
+
+
+class SpeedAdjustRequest(BaseModel):
+    """调速请求"""
+
+    speed: float = Field(..., ge=0.25, le=4.0, description="播放速度 0.25~4.0")
+
+
+class VolumeAdjustRequest(BaseModel):
+    """音量调节请求"""
+
+    volume: float = Field(..., ge=0.0, le=2.0, description="音量倍率 0~2.0（1.0=原音量）")
+
+
+class TrimAdjustRequest(BaseModel):
+    """裁剪请求"""
+
+    trim_start: float = Field(0.0, ge=0.0, description="开头裁剪秒数")
+    trim_end: float = Field(0.0, ge=0.0, description="结尾裁剪秒数")
+
+
+class ClipAdjustmentsRequest(BaseModel):
+    """统一调整请求"""
+
+    speed: Optional[float] = Field(default=None, ge=0.25, le=4.0)
+    volume: Optional[float] = Field(default=None, ge=0.0, le=2.0)
+    trim_start: Optional[float] = Field(default=None, ge=0.0)
+    trim_end: Optional[float] = Field(default=None, ge=0.0)
+
+
+class BatchSpeedRequest(BaseModel):
+    """批量调速请求"""
+
+    speed: float = Field(..., ge=0.25, le=4.0, description="播放速度")
+
+
+class ClipAdjustResponse(BaseModel):
+    """片段调整响应"""
+
+    clip_id: str
+    speed: float
+    volume: float
+    trim_start: float
+    trim_end: float
+    duration: float
+
+
+class BatchSpeedResponse(BaseModel):
+    """批量调速响应"""
+
+    updated_count: int
+    plan_id: str
+
+
+# ── From edit_plans_clips_batch.py ──────────────────────────────────────────
+
+
+class ClipReorderItem(BaseModel):
+    """重排序条目"""
+
+    clip_id: str
+    new_order: int = Field(..., ge=0, description="新的排序序号")
+
+
+class ClipReorderRequest(BaseModel):
+    """片段重排序请求"""
+
+    items: List[ClipReorderItem] = Field(..., min_length=1, max_length=500, description="重排序条目列表")
+
+
+class ClipReorderResponse(BaseModel):
+    """片段重排序响应"""
+
+    success: bool
+    updated_count: int
+    message: str = ""
+
+
+class ClipBatchDeleteRequest(BaseModel):
+    """批量删除片段请求"""
+
+    clip_ids: List[str] = Field(..., min_length=1, max_length=500, description="要删除的片段ID列表")
+
+
+class ClipBatchDeleteResponse(BaseModel):
+    """批量删除片段响应"""
+
+    success: bool
+    deleted_count: int
+    message: str = ""
+
+
+class ClipsFromAssetsRequest(BaseModel):
+    """从素材批量创建片段请求"""
+
+    asset_ids: List[str] = Field(..., min_length=1, max_length=200, description="素材 ID 列表，按顺序追加到时间线末尾")
+    clip_type: str = Field(default="main", description="片段类型，默认 main")
+
+
+class ClipsFromAssetsResponse(BaseModel):
+    """从素材批量创建片段响应"""
+
+    success: bool
+    created_count: int
+    message: str = ""
+    clip_ids: List[str] = Field(default_factory=list, description="创建的片段ID列表")
+
+
+# ── From edit_plans_cover.py ────────────────────────────────────────────────
+
+
+class CoverConfigResponse(BaseModel):
+    """封面配置响应"""
+
+    type: str = Field(..., description="封面类型: ai_frame / manual / upload")
+    image_url: str = Field(default="", description="封面图片 URL")
+    frame_time: Optional[float] = Field(default=None, description="抽帧时间点（秒）")
+
+
+class CoverUpdateRequest(BaseModel):
+    """更新封面配置请求"""
+
+    type: Optional[str] = Field(default=None, description="封面类型")
+    image_url: Optional[str] = Field(default=None, description="封面图片 URL")
+    frame_time: Optional[float] = Field(default=None, ge=0.0, description="抽帧时间点（秒）")
+
+
+class CoverExtractRequest(BaseModel):
+    """从片段抽帧生成封面请求"""
+
+    clip_id: str = Field(..., description="片段 ID")
+    frame_time: float = Field(1.0, ge=0.0, description="抽帧时间点（秒）")
+
+
+class CoverSmartRequest(BaseModel):
+    """智能选帧请求"""
+
+    clip_id: Optional[str] = Field(default=None, description="指定片段 ID（不传则用第一个视频片段）")
+
+
+class CoverGenerateResponse(BaseModel):
+    """封面生成响应"""
+
+    type: str = Field(..., description="封面类型")
+    image_url: str = Field(..., description="封面图片 URL")
+    frame_time: Optional[float] = Field(default=None, description="抽帧时间点（秒）")
+
+
+# ── From edit_plans_export.py ───────────────────────────────────────────────
+
+_EXPORT_RESOLUTION_PATTERN = _re.compile(r"^\d+x\d+$")
+_EXPORT_VALID_QUALITY_PRESETS = {"ultra_fast", "fast", "balanced", "high", "best"}
+_EXPORT_VALID_FORMATS = {"mp4", "mov"}
+
+
+class ExportConfigResponse(BaseModel):
+    """导出配置响应"""
+
+    resolution: str
+    fps: int
+    video_bitrate: int
+    audio_bitrate: int
+    format: str
+    quality_preset: str
+    watermark_enabled: bool
+    watermark_text: str
+
+
+class ExportUpdateRequest(BaseModel):
+    """更新导出配置请求"""
+
+    resolution: Optional[str] = None
+    fps: Optional[int] = Field(default=None, ge=15, le=60)
+    video_bitrate: Optional[int] = Field(default=None, ge=1000, le=20000)
+    audio_bitrate: Optional[int] = Field(default=None, ge=64, le=320)
+    format: Optional[str] = None
+    quality_preset: Optional[str] = None
+    watermark_enabled: Optional[bool] = None
+    watermark_text: Optional[str] = None
+
+    @validator("resolution")
+    def validate_resolution(cls, v):
+        if v is None:
+            return v
+        if not _EXPORT_RESOLUTION_PATTERN.match(v):
+            raise ValueError("分辨率格式错误，应为 宽x高，如 1080x1920")
+        w, h = v.split("x")
+        if int(w) < 100 or int(h) < 100:
+            raise ValueError("分辨率数值过小")
+        if int(w) > 4096 or int(h) > 4096:
+            raise ValueError("分辨率数值过大，最大 4096x4096")
+        return v
+
+    @validator("format")
+    def validate_format(cls, v):
+        if v is None:
+            return v
+        if v not in _EXPORT_VALID_FORMATS:
+            raise ValueError(f"无效格式: {v}，支持: {_EXPORT_VALID_FORMATS}")
+        return v
+
+    @validator("quality_preset")
+    def validate_quality_preset(cls, v):
+        if v is None:
+            return v
+        if v not in _EXPORT_VALID_QUALITY_PRESETS:
+            raise ValueError(f"无效质量预设: {v}，支持: {_EXPORT_VALID_QUALITY_PRESETS}")
+        return v
+
+
+class ExportPresetItem(BaseModel):
+    """导出预设条目"""
+
+    id: str
+    name: str
+    resolution: str
+    fps: int
+    video_bitrate: int
+    audio_bitrate: int
+    format: str
+    quality_preset: str
+    description: str
+    size_hint: str
+
+
+class ExportPresetListResponse(BaseModel):
+    """导出预设列表响应"""
+
+    items: List[ExportPresetItem]
+    total: int
+
+
+# ── From edit_plans_filter.py ───────────────────────────────────────────────
+
+
+class FilterPresetResponse(BaseModel):
+    """滤镜预设响应"""
+
+    id: str
+    name: str
+    category: str
+    description: str
+    tags: List[str] = Field(default_factory=list)
+
+
+class FilterConfigResponse(BaseModel):
+    """滤镜配置响应"""
+
+    enabled: bool
+    preset_id: str
+    intensity: int
+    brightness: float
+    contrast: float
+    saturation: float
+    warmth: float
+
+
+class FilterUpdateRequest(BaseModel):
+    """更新滤镜配置请求"""
+
+    enabled: Optional[bool] = None
+    preset_id: Optional[str] = None
+    intensity: Optional[int] = Field(default=None, ge=0, le=100)
+    brightness: Optional[float] = Field(default=None, ge=-1.0, le=1.0)
+    contrast: Optional[float] = Field(default=None, ge=0.0, le=2.0)
+    saturation: Optional[float] = Field(default=None, ge=0.0, le=3.0)
+    warmth: Optional[float] = Field(default=None, ge=-1.0, le=1.0)
+
+
+class FilterPresetListResponse(BaseModel):
+    """滤镜预设列表响应"""
+
+    items: List[FilterPresetResponse]
+    total: int
+
+
+# ── From edit_plans_transitions.py ──────────────────────────────────────────
+
+
+class TransitionPresetResponse(BaseModel):
+    """转场预设响应"""
+
+    id: str
+    name: str
+    category: str
+    description: str
+    tags: List[str] = Field(default_factory=list)
+    default_duration: float
+    min_duration: float
+    max_duration: float
+
+
+class TransitionUpdateRequest(BaseModel):
+    """更新转场请求"""
+
+    effect: str = Field(..., description="转场效果 ID")
+    duration: Optional[float] = Field(default=None, ge=0.0, description="转场时长（秒）")
+
+
+class BatchTransitionRequest(BaseModel):
+    """批量设置转场请求"""
+
+    effect: str = Field(..., description="转场效果 ID")
+    duration: Optional[float] = Field(default=None, ge=0.0, description="转场时长（秒）")
+    apply_to: str = Field(
+        default="all",
+        description="应用范围: all=所有片段, except_first=除第一个外, except_last=除最后一个, middle=中间片段",
+    )
+
+
+class ClipTransitionResponse(BaseModel):
+    """片段转场信息响应"""
+
+    clip_id: str
+    effect: str
+    duration: float
+
+
+class BatchTransitionResponse(BaseModel):
+    """批量转场响应"""
+
+    updated_count: int
+    plan_id: str
+
+
+class TransitionPresetListResponse(BaseModel):
+    """转场预设列表响应"""
+
+    items: List[TransitionPresetResponse]
+    total: int
+
+
 from app.auth import AuthenticatedUser, get_current_user
 from app.core.celery_app import celery_app
 from app.core.storage import OSSStorageService, get_storage_service
@@ -89,7 +491,6 @@ from app.dependencies import (
 from app.services.edit_plan_service import EditPlanService
 from app.services.edit_template_service import EditTemplateService
 from fastapi import APIRouter, Depends, HTTPException, Query, status
-from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session
 
 from packages.adapters.sqlalchemy_impl.generation_task_repository import (
@@ -238,19 +639,84 @@ def get_draft_plan_id(
     template_id: str,
     services: tuple[EditTemplateService, EditPlanService] = Depends(get_editor_services),
     current_user: AuthenticatedUser = Depends(get_current_user),
+    db: Session = Depends(get_db_session),
 ) -> str:
     """
     路径依赖：根据 template_id 获取或创建草稿，返回 plan_id。
 
     这是模板编辑器路由的核心依赖——所有编辑器端点都先经过这里，
     确保 template_id → plan_id 的映射始终存在。
+
+    兼容策略：优先从新模板系统（edit_templates 表）查找，
+    若不存在则回退到旧模板系统（templates 表），确保用户自建模板可用。
     """
-    tpl_svc, _ = services
-    draft = tpl_svc.get_or_create_draft(
-        template_id,
-        user_id=str(current_user.user_id),
+    tpl_svc, plan_svc = services
+    user_id = str(current_user.user.id)
+
+    # 1. 草稿已存在 → 直接返回
+    draft = tpl_svc.get_template_draft(template_id)
+    if draft is not None:
+        return draft.id
+
+    # 2. 新系统有模板 → 用新服务创建草稿
+    if tpl_svc.get_template(template_id) is not None:
+        draft = tpl_svc.create_template_draft(template_id, user_id=user_id)
+        return draft.id
+
+    # 3. 回退到旧模板系统（templates 表）
+    old_repo = SQLAlchemyTemplateRepository(db)
+    old_template = old_repo.get(template_id, user_id=user_id)
+    if old_template is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="模板不存在")
+
+    # 4. 基于旧模板创建草稿计划
+    from app.services.plan_generator_service import PlanGeneratorService
+
+    from packages.domain.edit_template import EditTemplate, EditTemplateStatus
+    from packages.domain.template_clip_config import ClipType, TemplateClipConfig
+
+    # 构造伪 EditTemplate 对象（只填 generate_from_template 需要的字段）
+    pseudo_template = EditTemplate(
+        id=old_template.id,
+        name=old_template.name,
+        editing_mode=old_template.mode,
+        status=EditTemplateStatus.ACTIVE,
     )
-    return draft.id
+
+    # 将旧模板 segments 转换为 clip_configs
+    clip_configs: list[TemplateClipConfig] = []
+    for seg in old_template.segments or []:
+        clip_configs.append(
+            TemplateClipConfig(
+                id=f"seg_{seg.id}",
+                template_id=old_template.id,
+                clip_type=ClipType.MAIN,
+                order=seg.segment_order,
+                min_duration=seg.duration_min,
+                max_duration=seg.duration_max,
+            )
+        )
+
+    generator = PlanGeneratorService(db)
+    result = generator.generate_from_template(
+        template=pseudo_template,
+        clip_configs=clip_configs,
+        asset_ids=[],
+        created_by_user_id=user_id,
+        name=f"{old_template.name} - 草稿",
+    )
+    plan = result["plan"]
+
+    # 标记为模板草稿（后续可复用 tpl_svc.get_template_draft 的查找逻辑）
+    plan_svc.update_plan_config(plan.id, {"is_template_draft": True})
+
+    logger.info(
+        "旧模板自动创建草稿: template_id=%s draft_plan_id=%s user_id=%s",
+        template_id,
+        plan.id,
+        user_id,
+    )
+    return plan.id
 
 
 # ── 草稿核心端点 ────────────────────────────────────────────────────────────
@@ -683,7 +1149,7 @@ def update_editor_bgm(
         template_id,
         plan_id,
         current_bgm.get("enabled", False),
-        current_user.user_id,
+        current_user.user.id,
     )
 
     return {
@@ -931,7 +1397,7 @@ def generate_editor_draft(
         clip_count = plan_svc.mark_clips_ready(plan_id)
 
         gen_task_repo = SQLAlchemyGenerationTaskRepository(db)
-        user_id = current_user.user_id
+        user_id = current_user.user.id
         _check_queue_limits(gen_task_repo, user_id)
 
         gen_task_use_case = CreateGenerationTaskUseCase(gen_task_repo)
@@ -941,7 +1407,7 @@ def generate_editor_draft(
             CreateGenerationTaskCommand(
                 project_id=plan.project_id or "",
                 template_id=plan.template_id,
-                created_by_user_id=current_user.user_id,
+                created_by_user_id=current_user.user.id,
                 source_edit_plan_id=plan_id,
                 asset_ids=list(config_asset_ids) if config_asset_ids else [],
             ),
@@ -959,7 +1425,7 @@ def generate_editor_draft(
             plan_id,
             gen_task.id,
             clip_count,
-            current_user.user_id,
+            current_user.user.id,
         )
 
         return EditPlanGenerateResponse(
@@ -1490,7 +1956,7 @@ def editor_ai_recommend(
         plan_id,
         len(result["clips"]),
         result["total_duration"],
-        current_user.user_id,
+        current_user.user.id,
     )
 
     return AIRecommendResponse(
@@ -1545,7 +2011,7 @@ def editor_generate_cover(
         template_id,
         plan_id,
         body.cover_type,
-        current_user.user_id,
+        current_user.user.id,
     )
 
     return GenerateCoverResponse(plan_id=plan_id, cover=cover_data)
@@ -1961,7 +2427,7 @@ def extract_editor_cover(
         template_id,
         plan_id,
         body.clip_id,
-        current_user.user_id,
+        current_user.user.id,
     )
 
     return CoverGenerateResponse(
@@ -2003,7 +2469,7 @@ def smart_editor_cover(
         template_id,
         plan_id,
         body.strategy,
-        current_user.user_id,
+        current_user.user.id,
     )
 
     return CoverGenerateResponse(
@@ -2084,7 +2550,7 @@ def create_clips_from_assets_editor(
         template_id,
         plan_id,
         len(clips),
-        current_user.user_id,
+        current_user.user.id,
     )
 
     return ClipsFromAssetsResponse(

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

@@ -113,7 +113,7 @@ def update_video_review_status(
     if item is None:
         raise HTTPException(status_code=404, detail="Video not found")
     logger.info(
-        "Video %s review status updated to %s by user %s", video_id, request.review_status, current_user.user_id
+        "Video %s review status updated to %s by user %s", video_id, request.review_status, current_user.user.id
     )
     return _to_video_response(item, storage)
 
@@ -197,7 +197,7 @@ def batch_download_videos(
     # 发送 celery 任务
     task = celery_app.send_task(
         "worker.batch_download_videos",
-        args=[request.video_ids, current_user.user_id],
+        args=[request.video_ids, current_user.user.id],
     )
 
     logger.info("Batch download job created: %s, videos=%d", task.id, len(request.video_ids))

apps/api/app/services/edit_plan_service.py

@@ -39,70 +39,6 @@ class EditPlanService:
 
     # ── 剪辑计划 CRUD ──────────────────────────────────────────────────────
 
-    def list_plans(
-        self,
-        *,
-        template_id: Optional[str] = None,
-        project_id: Optional[str] = None,
-        status: Optional[EditPlanStatus] = None,
-        skip: int = 0,
-        limit: int = 50,
-    ) -> List[EditPlan]:
-        """列出剪辑计划
-
-        Args:
-            template_id: 按模板 ID 筛选
-            project_id: 按项目 ID 筛选
-            status: 按状态筛选
-            skip: 分页偏移
-            limit: 每页数量
-        """
-        if project_id:
-            return self._plan_repo.list_by_project(
-                project_id,
-                status=status,
-                skip=skip,
-                limit=limit,
-            )
-        if template_id:
-            return self._plan_repo.list_by_template(
-                template_id,
-                status=status,
-                skip=skip,
-                limit=limit,
-            )
-        return self._plan_repo.list_all(status=status, skip=skip, limit=limit)
-
-    def count_plans(
-        self,
-        *,
-        template_id: Optional[str] = None,
-        project_id: Optional[str] = None,
-        status: Optional[EditPlanStatus] = None,
-    ) -> int:
-        """统计计划数量
-
-        Note:
-            当指定 template_id/project_id 时，通过全量查询计算 total（repo 限制）。
-        """
-        if project_id:
-            all_matching = self._plan_repo.list_by_project(
-                project_id,
-                status=status,
-                skip=0,
-                limit=10000,
-            )
-            return len(all_matching)
-        if template_id:
-            all_matching = self._plan_repo.list_by_template(
-                template_id,
-                status=status,
-                skip=0,
-                limit=10000,
-            )
-            return len(all_matching)
-        return self._plan_repo.count(status=status)
-
     def get_plan(self, plan_id: str) -> Optional[EditPlan]:
         """获取计划详情"""
         return self._plan_repo.get(plan_id)
@@ -124,7 +60,7 @@ class EditPlanService:
         project_id: str = "",
         created_by_user_id: str = "",
     ) -> EditPlan:
-        """创建剪辑计划
+        """创建剪辑计划（基础 CRUD，供内部测试与脚本使用）
 
         Raises:
             ValueError: 参数校验失败
@@ -190,23 +126,6 @@ class EditPlanService:
         logger.info("更新剪辑计划: id=%s", plan_id)
         return result
 
-    def delete_plan(self, plan_id: str) -> bool:
-        """删除剪辑计划及其所有片段
-
-        Returns:
-            bool: 是否删除成功
-        """
-        existing = self._plan_repo.get(plan_id)
-        if existing is None:
-            return False
-
-        # 先删除所有片段
-        self._clip_repo.delete_by_plan(plan_id)
-        # 再删除计划
-        self._plan_repo.delete(plan_id)
-        logger.info("删除剪辑计划: id=%s", plan_id)
-        return True
-
     # ── 状态机流转 ──────────────────────────────────────────────────────────
 
     def transition_status(self, plan_id: str, target_status: EditPlanStatus) -> EditPlan:
@@ -447,63 +366,6 @@ class EditPlanService:
         logger.info("删除所有片段: plan_id=%s count=%d", plan_id, count)
         return count
 
-    def create_clips_from_assets(
-        self,
-        plan_id: str,
-        asset_ids: list[str],
-        *,
-        clip_type: str = "main",
-    ) -> list[EditPlanClip]:
-        """从素材批量创建片段（追加到时间线末尾）。
-
-        Args:
-            plan_id: 计划 ID
-            asset_ids: 素材 ID 列表（按顺序追加）
-            clip_type: 片段类型
-
-        Returns:
-            list[EditPlanClip]: 创建的片段列表
-        """
-        if not asset_ids:
-            return []
-
-        # 确保计划存在 + 自动回退状态
-        self.get_plan_or_raise(plan_id)
-        self._auto_resume_editing(plan_id)
-
-        # 查询素材信息（取 duration）
-        from packages.adapters.sqlalchemy_impl.models import AssetModel
-
-        session = self._clip_repo.session  # type: ignore[attr-defined]
-        assets = session.query(AssetModel).filter(AssetModel.id.in_(asset_ids)).all()
-        asset_map = {a.id: a for a in assets}
-
-        # 从现有片段数量开始追加
-        existing_count = self._clip_repo.count(plan_id=plan_id)
-
-        # 批量创建片段
-        created: list[EditPlanClip] = []
-        for i, asset_id in enumerate(asset_ids):
-            asset = asset_map.get(asset_id)
-            duration = asset.duration if asset and asset.duration else 0.0
-
-            clip = self.create_clip(
-                plan_id=plan_id,
-                clip_type=clip_type,
-                order=existing_count + i,
-                asset_id=asset_id,
-                duration=duration,
-            )
-            created.append(clip)
-
-        logger.info(
-            "从素材批量创建片段: plan_id=%s count=%d",
-            plan_id,
-            len(created),
-        )
-        return created
-
-    # ── 渲染生成流程 ────────────────────────────────────────────────────────
     # ── 片段分割与合并 ──────────────────────────────────────────────────────
 
     def split_clip(self, clip_id: str, split_time: float) -> Dict[str, Any]:
@@ -674,249 +536,7 @@ class EditPlanService:
 
         return merged_clip
 
-    # ── 字幕管理 ──────────────────────────────────────────────────────────
-
-    def list_subtitles(self, clip_id: str) -> List[Dict[str, Any]]:
-        """获取片段的所有字幕
-
-        Returns:
-            List[dict]: 字幕列表，按 start 时间排序
-        """
-        clip = self.get_clip_or_raise(clip_id)
-        config = clip.config or {}
-        subtitles = config.get("subtitles", [])
-        # 按开始时间排序
-        subtitles.sort(key=lambda s: s.get("start", 0))
-        return subtitles
-
-    def get_subtitle(self, clip_id: str, subtitle_id: str) -> Optional[Dict[str, Any]]:
-        """获取单条字幕"""
-        subtitles = self.list_subtitles(clip_id)
-        for s in subtitles:
-            if s.get("id") == subtitle_id:
-                return s
-        return None
-
-    def add_subtitle(
-        self,
-        clip_id: str,
-        start: float,
-        end: float,
-        text: str,
-        *,
-        style: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """添加一条字幕
-
-        Args:
-            clip_id: 片段 ID
-            start: 开始时间（秒，相对于片段）
-            end: 结束时间（秒）
-            text: 字幕文本
-            style: 样式配置（字体、大小、颜色、位置等）
-
-        Returns:
-            dict: 新增的字幕条目
-
-        Raises:
-            ValueError: 时间非法或文本为空
-        """
-        clip = self.get_clip_or_raise(clip_id)
-
-        if start < 0 or end <= start:
-            raise ValueError(f"字幕时间非法: start={start}, end={end}")
-        if not text.strip():
-            raise ValueError("字幕文本不能为空")
-        if end > clip.duration + 0.001:
-            raise ValueError(f"字幕结束时间不能超过片段时长: end={end:.3f}, duration={clip.duration:.3f}")
-
-        self._auto_resume_editing(clip.plan_id)
-
-        from uuid import uuid4
-
-        config = dict(clip.config) if clip.config else {}
-        subtitles = list(config.get("subtitles", []))
-
-        subtitle = {
-            "id": uuid4().hex,
-            "start": round(start, 3),
-            "end": round(end, 3),
-            "text": text.strip(),
-            "style": style or {},
-        }
-        subtitles.append(subtitle)
-        subtitles.sort(key=lambda s: s.get("start", 0))
-
-        config["subtitles"] = subtitles
-        clip.config = config
-        self._clip_repo.update(clip)
-
-        logger.info(
-            "添加字幕: clip_id=%s subtitle_id=%s start=%.3fs end=%.3fs",
-            clip_id,
-            subtitle["id"],
-            start,
-            end,
-        )
-
-        return subtitle
-
-    def update_subtitle(
-        self,
-        clip_id: str,
-        subtitle_id: str,
-        *,
-        start: Optional[float] = None,
-        end: Optional[float] = None,
-        text: Optional[str] = None,
-        style: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """更新一条字幕
-
-        Returns:
-            dict: 更新后的字幕条目
-
-        Raises:
-            ValueError: 字幕不存在或参数非法
-        """
-        clip = self.get_clip_or_raise(clip_id)
-        config = dict(clip.config) if clip.config else {}
-        subtitles = list(config.get("subtitles", []))
-
-        found = False
-        for i, s in enumerate(subtitles):
-            if s.get("id") == subtitle_id:
-                # 更新字段
-                updated_s = dict(s)
-                if start is not None:
-                    updated_s["start"] = round(start, 3)
-                if end is not None:
-                    updated_s["end"] = round(end, 3)
-                if text is not None:
-                    if not text.strip():
-                        raise ValueError("字幕文本不能为空")
-                    updated_s["text"] = text.strip()
-                if style is not None:
-                    updated_s["style"] = style
-
-                # 校验时间
-                if updated_s["start"] < 0 or updated_s["end"] <= updated_s["start"]:
-                    raise ValueError(f"字幕时间非法: start={updated_s['start']}, end={updated_s['end']}")
-                if updated_s["end"] > clip.duration + 0.001:
-                    raise ValueError("字幕结束时间不能超过片段时长")
-
-                subtitles[i] = updated_s
-                found = True
-                break
-
-        if not found:
-            raise ValueError(f"字幕不存在: {subtitle_id}")
-
-        self._auto_resume_editing(clip.plan_id)
-
-        subtitles.sort(key=lambda s: s.get("start", 0))
-        config["subtitles"] = subtitles
-        clip.config = config
-        self._clip_repo.update(clip)
-
-        logger.info("更新字幕: clip_id=%s subtitle_id=%s", clip_id, subtitle_id)
-
-        return subtitles[next(i for i, s in enumerate(subtitles) if s["id"] == subtitle_id)]
-
-    def delete_subtitle(self, clip_id: str, subtitle_id: str) -> bool:
-        """删除一条字幕
-
-        Returns:
-            bool: 是否删除成功
-        """
-        clip = self.get_clip_or_raise(clip_id)
-        config = dict(clip.config) if clip.config else {}
-        subtitles = list(config.get("subtitles", []))
-
-        new_subtitles = [s for s in subtitles if s.get("id") != subtitle_id]
-        if len(new_subtitles) == len(subtitles):
-            return False
-
-        self._auto_resume_editing(clip.plan_id)
-
-        config["subtitles"] = new_subtitles
-        clip.config = config
-        self._clip_repo.update(clip)
-
-        logger.info("删除字幕: clip_id=%s subtitle_id=%s", clip_id, subtitle_id)
-        return True
-
-    def batch_update_subtitles(
-        self,
-        clip_id: str,
-        subtitles: List[Dict[str, Any]],
-    ) -> List[Dict[str, Any]]:
-        """批量更新字幕（全量替换，用于批量编辑或导入）
-
-        Args:
-            clip_id: 片段 ID
-            subtitles: 字幕列表，每条需包含 start/end/text，已有 id 则保留
-
-        Returns:
-            List[dict]: 更新后的字幕列表
-        """
-        clip = self.get_clip_or_raise(clip_id)
-
-        from uuid import uuid4
-
-        validated = []
-        for s in subtitles:
-            start = float(s.get("start", 0))
-            end = float(s.get("end", 0))
-            text = str(s.get("text", ""))
-
-            if start < 0 or end <= start:
-                raise ValueError(f"字幕时间非法: start={start}, end={end}")
-            if not text.strip():
-                continue  # 跳过空字幕
-            if end > clip.duration + 0.001:
-                raise ValueError(f"字幕结束时间不能超过片段时长: end={end}")
-
-            subtitle_id = s.get("id") or uuid4().hex
-            validated.append(
-                {
-                    "id": subtitle_id,
-                    "start": round(start, 3),
-                    "end": round(end, 3),
-                    "text": text.strip(),
-                    "style": s.get("style", {}),
-                }
-            )
-
-        validated.sort(key=lambda s: s["start"])
-
-        self._auto_resume_editing(clip.plan_id)
-
-        config = dict(clip.config) if clip.config else {}
-        config["subtitles"] = validated
-        clip.config = config
-        self._clip_repo.update(clip)
-
-        logger.info(
-            "批量更新字幕: clip_id=%s count=%d",
-            clip_id,
-            len(validated),
-        )
-
-        return validated
-
-    def get_plan_with_clips(self, plan_id: str) -> Dict[str, Any]:
-        """获取计划及其所有片段
-
-        Returns:
-            dict: {"plan": EditPlan, "clips": List[EditPlanClip]}
-        """
-        plan = self.get_plan_or_raise(plan_id)
-        clips = self._clip_repo.list_by_plan(plan_id)
-        return {
-            "plan": plan,
-            "clips": clips,
-        }
+    # ── 渲染生成流程 ────────────────────────────────────────────────────────
 
     def get_generation_status(self, plan_id: str) -> Dict[str, Any]:
         """获取渲染进度状态
@@ -1026,85 +646,3 @@ class EditPlanService:
             updated_at=plan.updated_at,
         )
         return self._plan_repo.update(updated)
-
-    # ── 复制计划 ────────────────────────────────────────────────────────────
-
-    def copy_plan(
-        self,
-        plan_id: str,
-        *,
-        new_name: Optional[str] = None,
-        project_id: Optional[str] = None,
-    ) -> EditPlan:
-        """复制一个剪辑计划（含所有片段配置）。
-
-        新计划状态为 editing，不含生成任务和结果记录。
-
-        Args:
-            plan_id: 源计划 ID
-            new_name: 新计划名称，不传则为「原名 - 副本」
-            project_id: 新计划的项目 ID，不传则复用源计划
-
-        Returns:
-            EditPlan: 新创建的计划
-
-        Raises:
-            ValueError: 源计划不存在
-        """
-        source = self.get_plan_or_raise(plan_id)
-        source_clips = self._clip_repo.list_by_plan(plan_id)
-
-        # 新计划名称
-        name = new_name or f"{source.name} - 副本"
-        new_project_id = project_id if project_id is not None else source.project_id
-
-        # 复制 plan 配置（去除渲染结果相关字段）
-        new_config = dict(source.config)
-        new_config.pop("rendered_url", None)
-        new_config.pop("rendered_storage_key", None)
-        new_config.pop("generation_task_id", None)
-
-        # 创建新计划
-        new_plan = EditPlan.create(
-            template_id=source.template_id,
-            name=name,
-            config=new_config,
-            total_duration=source.total_duration,
-            project_id=new_project_id,
-            created_by_user_id=source.created_by_user_id,
-            source_edit_plan_id=plan_id,
-        )
-        # 强制切到 editing 状态
-        if new_plan.status != EditPlanStatus.EDITING:
-            try:
-                new_plan.start_editing()
-            except ValueError:
-                pass
-
-        created_plan = self._plan_repo.create(new_plan)
-        logger.info(
-            "复制剪辑计划: source=%s target=%s name=%s clips=%d",
-            plan_id,
-            created_plan.id,
-            name,
-            len(source_clips),
-        )
-
-        # 复制所有片段
-        for clip in source_clips:
-            new_clip = self.create_clip(
-                plan_id=created_plan.id,
-                clip_type=clip.clip_type,
-                order=clip.order,
-                asset_id=clip.asset_id or "",
-                text_content=clip.text_content or "",
-                start_time=clip.start_time,
-                duration=clip.duration,
-                transition_effect=clip.transition_effect or "cut",
-                transition_duration=clip.transition_duration or 0.0,
-                playback_speed=clip.playback_speed or 1.0,
-                config=dict(clip.config) if clip.config else None,
-            )
-            logger.debug("复制片段: source=%s target=%s order=%d", clip.id, new_clip.id, clip.order)
-
-        return self.get_plan_or_raise(created_plan.id)

apps/api/app/services/edit_template_service.py

@@ -754,8 +754,8 @@ class EditTemplateService:
             template.bump_version()  # 版本号 +1
             updated_template = self._template_repo.update(template)
 
-            # 批量删除旧的片段配置（走 repository，保证测试 stub 和真实行为一致）
-            self._clip_config_repo.delete_by_template(template_id)
+            # 批量删除旧的片段配置（外层事务统一提交）
+            self._clip_config_repo.delete_by_template(template_id, commit=False)
 
             # 创建新的片段配置
             created_configs: list[TemplateClipConfig] = []

apps/web/e2e/core-generation.spec.ts

@@ -52,7 +52,7 @@ type AssetListResponse = {
 test.describe("Core generation flow", () => {
   test.describe.configure({ timeout: 180_000 })
 
-  test("walks through 5-step wizard and starts generation", async ({ page, request }) => {
+  test("walks through 7-step wizard and starts generation", async ({ page, request }) => {
     test.setTimeout(180_000)
 
     await routeBrowserApiToTestApi(page)
@@ -177,7 +177,7 @@ test.describe("Core generation flow", () => {
 
     // Navigate to generate page
     await page.goto("/app/generate")
-    await expect(page.getByRole("heading", { name: "一键生成" })).toBeVisible({
+    await expect(page.getByRole("heading", { name: "智能剪辑" })).toBeVisible({
       timeout: 20_000,
     })
 
@@ -196,38 +196,56 @@ test.describe("Core generation flow", () => {
     await materialLabel.locator("input[type='checkbox']").check()
     await page.getByRole("button", { name: "下一步" }).click()
 
-    // Step 3: title
+    // Step 3: preview (纯展示页，AI 智能匹配预览)
+    await expect(page.getByRole("heading", { name: /生成预览/ })).toBeVisible()
+    await page.getByRole("button", { name: "下一步" }).click()
+
+    // Step 4: title
     await expect(page.getByRole("heading", { name: /选择标题/ })).toBeVisible()
     const titleText = `E2E Test ${suffix}`
     await page.getByPlaceholder("输入自定义标题…").fill(titleText)
     await page.getByRole("button", { name: "下一步" }).click()
 
-    // Step 4: voice
+    // Step 5: voice
     await expect(page.getByRole("heading", { name: /选择配音/ })).toBeVisible()
     const firstVoiceCard = page.locator(".xx-voice-choice-item").first()
     await firstVoiceCard.click()
     await page.getByRole("button", { name: "下一步" }).click()
 
-    // Step 5: confirm and generate
+    // Step 6: cover (默认 AI 智能选帧模式，直接下一步)
+    await expect(page.getByRole("heading", { name: /选择封面/ })).toBeVisible()
+    await page.getByRole("button", { name: "下一步" }).click()
+
+    // Step 7: confirm and generate
     await expect(page.getByRole("heading", { name: /确认生成/ })).toBeVisible()
 
-    // Wait for plan creation API to be called
-    const createPlanPromise = page.waitForResponse(
-      (response) =>
-        response.url().includes("/edit-plans") &&
-        response.request().method() === "POST" &&
-        !response.url().includes("/generate"),
+    // Wait for generation API to be called
+    // 新架构：GET 草稿自动创建 → PUT 更新内容 → POST /generate 触发生成
+    // 等 generate 接口返回，确认生成流程启动
+    const generatePromise = page.waitForResponse(
+      (response) => {
+        const url = response.url()
+        const path = new URL(url).pathname
+        return response.request().method() === "POST" && path.endsWith("/editor/generate")
+      },
       { timeout: 30_000 },
     )
 
     // Click generate button
     await page.locator(".xx-btn-primary").filter({ hasText: "确认生成" }).first().click()
 
-    // Verify plan was created successfully
-    const planResp = await createPlanPromise
-    expect(planResp.ok()).toBeTruthy()
-    const planData = (await planResp.json()) as { id: string }
-    expect(planData.id).toBeTruthy()
+    // Verify generation was triggered successfully
+    const genResp = await generatePromise
+    if (!genResp.ok()) {
+      const body = await genResp.text()
+      console.error(
+        `[E2E DEBUG] 触发生成接口失败: status=${genResp.status()} url=${genResp.url()} body=${body.slice(0, 500)}`,
+      )
+    }
+    expect(genResp.ok()).toBeTruthy()
+    const genData = (await genResp.json()) as { plan_id: string; generation_task_id: string }
+    expect(genData.plan_id).toBeTruthy()
+    expect(genData.generation_task_id).toBeTruthy()
 
     // Generation may fail in test env (no worker), that's OK
     // Just verify the flow started - check page shows generation-related UI

apps/web/src/api/auth.ts

@@ -121,3 +121,67 @@ export const verifyEmail = async (token: string): Promise<{ message: string }> =
   const response = await apiClient.post("/auth/verify-email", { token })
   return response.data
 }
+
+/* ========== 微信登录 ========== */
+
+export interface WechatAuthUrlResponse {
+  auth_url: string
+  state: string
+}
+
+export interface WechatCallbackResponse {
+  access_token: string
+  refresh_token?: string | null
+  user_id: string
+  display_name: string
+  avatar_url: string
+  is_new_user: boolean
+  binding_complete: boolean
+  expires_in: number
+}
+
+export interface SendVerificationCodeRequest {
+  target: "email" | "phone"
+  value: string
+  purpose: "bind" | "login" | "reset_password"
+}
+
+export interface BindContactRequest {
+  target: "email" | "phone"
+  value: string
+  code: string
+}
+
+export interface BindContactResponse {
+  message: string
+  user: User
+}
+
+// 获取微信授权链接
+export const getWechatAuthUrl = async (): Promise<WechatAuthUrlResponse> => {
+  const response = await apiClient.get("/auth/wechat/url")
+  return response.data
+}
+
+// 微信回调登录
+export const wechatCallback = async (
+  code: string,
+  state: string,
+): Promise<WechatCallbackResponse> => {
+  const response = await apiClient.post("/auth/wechat/callback", { code, state })
+  return response.data
+}
+
+// 发送验证码
+export const sendVerificationCode = async (
+  data: SendVerificationCodeRequest,
+): Promise<{ message: string }> => {
+  const response = await apiClient.post("/auth/send-verification-code", data)
+  return response.data
+}
+
+// 绑定联系方式
+export const bindContact = async (data: BindContactRequest): Promise<BindContactResponse> => {
+  const response = await apiClient.post("/auth/bind-contact", data)
+  return response.data
+}

apps/web/src/api/templateEditor.ts

@@ -199,6 +199,8 @@ export interface GenerationStatusResponse {
   generation_task_id?: string
   error_message?: string
   clips: ClipStatusItem[]
+  error?: string
+  message?: string
 }
 
 /** 生成视频详情（对应后端 GeneratedVideoResponse） */
@@ -343,71 +345,71 @@ export interface EditPlanListResponse {
 
 /** 获取模板草稿列表（支持分页和筛选） */
 export async function getEditPlans(params?: EditPlanListParams): Promise<EditPlanListResponse> {
-  const response = await apiClient.get<EditPlanListResponse>("/edit-plans", {
+  const response = await apiClient.get<EditPlanListResponse>("/templates/drafts", {
     params,
   })
   return response.data
 }
 
 /** 获取单个模板草稿 */
-export async function getEditPlan(planId: string): Promise<EditPlan> {
-  const response = await apiClient.get(`/edit-plans/${planId}`)
+export async function getEditPlan(templateId: string): Promise<EditPlan> {
+  const response = await apiClient.get(`/templates/${templateId}/editor`)
   return response.data
 }
 
 /** 创建模板草稿 */
 export async function createEditPlan(data: CreateEditPlanRequest): Promise<EditPlan> {
-  const response = await apiClient.post("/edit-plans", data)
+  const response = await apiClient.post("/templates/drafts", data)
   return response.data
 }
 
 /** 更新模板草稿 */
 export async function updateEditPlan(
-  planId: string,
+  templateId: string,
   data: UpdateEditPlanRequest,
 ): Promise<EditPlan> {
-  const response = await apiClient.put(`/edit-plans/${planId}`, data)
+  const response = await apiClient.put(`/templates/${templateId}/editor`, data)
   return response.data
 }
 
 /** 删除模板草稿 */
-export async function deleteEditPlan(planId: string): Promise<void> {
-  await apiClient.delete(`/edit-plans/${planId}`)
+export async function deleteEditPlan(templateId: string): Promise<void> {
+  await apiClient.delete(`/templates/${templateId}/editor`)
 }
 
 /** 触发生成 */
-export async function generateEditPlan(planId: string): Promise<GenerateResponse> {
-  const response = await apiClient.post(`/edit-plans/${planId}/generate`)
+export async function generateEditPlan(templateId: string): Promise<GenerateResponse> {
+  const response = await apiClient.post(`/templates/${templateId}/editor/generate`)
   return response.data
 }
 
 /** 获取生成状态（轮询用） */
-export async function getGenerationStatus(planId: string): Promise<GenerationStatusResponse> {
-  const response = await apiClient.get(`/edit-plans/${planId}/generation-status`)
+export async function getGenerationStatus(templateId: string): Promise<GenerationStatusResponse> {
+  const response = await apiClient.get(`/templates/${templateId}/editor/generation-status`)
   return response.data
 }
 
 /** AI 推荐片段方案 */
 export async function aiRecommendClips(
-  planId: string,
+  templateId: string,
   data: AIRecommendRequest,
 ): Promise<AIRecommendResponse> {
-  const response = await apiClient.post(`/edit-plans/${planId}/ai-recommend`, data)
+  const response = await apiClient.post(`/templates/${templateId}/editor/ai-recommend`, data)
   return response.data
 }
 
 /** AI 生成封面 */
 export async function generateCover(
-  planId: string,
+  templateId: string,
   data: GenerateCoverRequest,
 ): Promise<GenerateCoverResponse> {
-  const response = await apiClient.post(`/edit-plans/${planId}/generate-cover`, data)
+  const response = await apiClient.post(`/templates/${templateId}/editor/generate-cover`, data)
   return response.data
 }
 
 /** 获取模板草稿关联的生成记录 */
-export async function getEditPlanGenerations(planId: string): Promise<EditPlanGeneration[]> {
-  const response = await apiClient.get(`/edit-plans/${planId}/generations`)
+export async function getEditPlanGenerations(templateId: string): Promise<EditPlanGeneration[]> {
+  const response = await apiClient.get(`/templates/${templateId}/editor/generations`)
   return response.data.items || []
 }
 
@@ -418,8 +420,8 @@ export async function getGenerationTaskResults(taskId: string): Promise<Generate
 }
 
 /** 取消生成任务 */
-export async function cancelGeneration(planId: string): Promise<void> {
-  await apiClient.post(`/edit-plans/${planId}/cancel`)
+export async function cancelGeneration(templateId: string): Promise<void> {
+  await apiClient.post(`/templates/${templateId}/editor/cancel`)
 }
 
 /* ============================================================
@@ -491,43 +493,51 @@ export interface EditPlanClipListParams {
 
 /** 获取片段列表 */
 export async function getEditPlanClips(
-  planId: string,
+  templateId: string,
   params?: EditPlanClipListParams,
 ): Promise<EditPlanClipListResponse> {
-  const response = await apiClient.get<EditPlanClipListResponse>(`/edit-plans/${planId}/clips`, {
-    params,
-  })
+  const response = await apiClient.get<EditPlanClipListResponse>(
+    `/templates/${templateId}/editor/clips`,
+    {
+      params,
+    },
+  )
   return response.data
 }
 
 /** 获取单个片段详情 */
-export async function getEditPlanClip(planId: string, clipId: string): Promise<EditPlanClip> {
-  const response = await apiClient.get<EditPlanClip>(`/edit-plans/${planId}/clips/${clipId}`)
+export async function getEditPlanClip(templateId: string, clipId: string): Promise<EditPlanClip> {
+  const response = await apiClient.get<EditPlanClip>(
+    `/templates/${templateId}/editor/clips/${clipId}`,
+  )
   return response.data
 }
 
 /** 创建片段 */
 export async function createEditPlanClip(
-  planId: string,
+  templateId: string,
   data: CreateEditPlanClipRequest,
 ): Promise<EditPlanClip> {
-  const response = await apiClient.post<EditPlanClip>(`/edit-plans/${planId}/clips`, data)
+  const response = await apiClient.post<EditPlanClip>(`/templates/${templateId}/editor/clips`, data)
   return response.data
 }
 
 /** 更新片段 */
 export async function updateEditPlanClip(
-  planId: string,
+  templateId: string,
   clipId: string,
   data: UpdateEditPlanClipRequest,
 ): Promise<EditPlanClip> {
-  const response = await apiClient.put<EditPlanClip>(`/edit-plans/${planId}/clips/${clipId}`, data)
+  const response = await apiClient.put<EditPlanClip>(
+    `/templates/${templateId}/editor/clips/${clipId}`,
+    data,
+  )
   return response.data
 }
 
 /** 删除片段 */
-export async function deleteEditPlanClip(planId: string, clipId: string): Promise<void> {
-  await apiClient.delete(`/edit-plans/${planId}/clips/${clipId}`)
+export async function deleteEditPlanClip(templateId: string, clipId: string): Promise<void> {
+  await apiClient.delete(`/templates/${templateId}/editor/clips/${clipId}`)
 }
 
 /* ============================================================
@@ -564,11 +574,11 @@ export interface ClipsFromAssetsResponse {
 
 /** 片段重排序（拖拽排序后一次性提交） */
 export async function reorderEditPlanClips(
-  planId: string,
+  templateId: string,
   items: ClipReorderItem[],
 ): Promise<ClipReorderResponse> {
   const response = await apiClient.post<ClipReorderResponse>(
-    `/edit-plans/${planId}/clips/reorder`,
+    `/templates/${templateId}/editor/clips/reorder`,
     { items },
   )
   return response.data
@@ -576,11 +586,11 @@ export async function reorderEditPlanClips(
 
 /** 批量删除片段 */
 export async function batchDeleteEditPlanClips(
-  planId: string,
+  templateId: string,
   clipIds: string[],
 ): Promise<ClipBatchDeleteResponse> {
   const response = await apiClient.post<ClipBatchDeleteResponse>(
-    `/edit-plans/${planId}/clips/batch-delete`,
+    `/templates/${templateId}/editor/clips/batch-delete`,
     { clip_ids: clipIds },
   )
   return response.data
@@ -588,12 +598,12 @@ export async function batchDeleteEditPlanClips(
 
 /** 从素材批量创建片段（追加到时间线末尾） */
 export async function createClipsFromAssets(
-  planId: string,
+  templateId: string,
   assetIds: string[],
   clipType = "main",
 ): Promise<ClipsFromAssetsResponse> {
   const response = await apiClient.post<ClipsFromAssetsResponse>(
-    `/edit-plans/${planId}/clips/from-assets`,
+    `/templates/${templateId}/editor/clips/from-assets`,
     { asset_ids: assetIds, clip_type: clipType },
   )
   return response.data
@@ -610,8 +620,14 @@ export interface CopyEditPlanRequest {
 }
 
 /** 复制模板草稿（含所有片段配置） */
-export async function copyEditPlan(planId: string, data?: CopyEditPlanRequest): Promise<EditPlan> {
-  const response = await apiClient.post<EditPlan>(`/edit-plans/${planId}/copy`, data || {})
+export async function copyEditPlan(
+  templateId: string,
+  data?: CopyEditPlanRequest,
+): Promise<EditPlan> {
+  const response = await apiClient.post<EditPlan>(
+    `/templates/${templateId}/editor/copy`,
+    data || {},
+  )
   return response.data
 }
 

apps/web/src/api/templates.ts

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

apps/web/src/components/AssetSelector/AssetSelector.tsx

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

apps/web/src/components/auth/BindContactModal.tsx

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

apps/web/src/hooks/useAuth.ts

@@ -20,24 +20,56 @@ export const useLogin = () => {
     const data = await mutation.mutateAsync(credentials)
     const refreshToken = data.refresh_token ?? null
 
-    // 先保存 token
-    localStorage.setItem("access_token", data.access_token)
-    if (refreshToken) {
-      localStorage.setItem("refresh_token", refreshToken)
-    } else {
-      localStorage.removeItem("refresh_token")
-    }
-
     // 获取用户信息
     const user = await authApi.getCurrentUser()
     setAuth(user, data.access_token, refreshToken)
-    navigate("/")
+
+    // 跳转到登录前页面或首页
+    const redirect = localStorage.getItem("login_redirect") || "/"
+    localStorage.removeItem("login_redirect")
+    navigate(redirect, { replace: true })
     return data
   }
 
   return { ...mutation, mutateAsync: login }
 }
 
+// 微信登录 Hook（用于回调后处理登录状态）
+export const useWechatCallback = () => {
+  const navigate = useNavigate()
+  const setAuth = useAuthStore((state) => state.setAuth)
+  const setUser = useAuthStore((state) => state.setUser)
+
+  const mutation = useMutation({
+    mutationFn: ({ code, state }: { code: string; state: string }) =>
+      authApi.wechatCallback(code, state),
+  })
+
+  const handleCallback = async (code: string, state: string) => {
+    // 校验 state
+    const savedState = localStorage.getItem("wechat_state")
+    if (!savedState || savedState !== state) {
+      throw new Error("安全校验失败")
+    }
+    localStorage.removeItem("wechat_state")
+
+    const result = await mutation.mutateAsync({ code, state })
+    const user = await authApi.getCurrentUser()
+    setAuth(user, result.access_token, result.refresh_token)
+
+    return { ...result, user }
+  }
+
+  // 绑定成功后跳转
+  const finishLogin = () => {
+    const redirect = localStorage.getItem("login_redirect") || "/"
+    localStorage.removeItem("login_redirect")
+    navigate(redirect, { replace: true })
+  }
+
+  return { ...mutation, handleCallback, finishLogin, setUser }
+}
+
 // 注册 Hook
 export const useRegister = () => {
   const navigate = useNavigate()

apps/web/src/pages/auth/Login.tsx

@@ -1,10 +1,11 @@
 /**
  * 登录页面 - V21 完全对标
  */
-import React from "react"
+import React, { useState } from "react"
 import { Form, Input, Checkbox, message } from "antd"
 import { Link, useNavigate } from "react-router-dom"
 import { useLogin } from "@/hooks/useAuth"
+import { getWechatAuthUrl } from "@/api/auth"
 import Button from "@/components/ui/Button"
 import "./Login.css"
 
@@ -18,6 +19,7 @@ const Login: React.FC = () => {
   const navigate = useNavigate()
   const loginMutation = useLogin()
   const [form] = Form.useForm()
+  const [wechatLoading, setWechatLoading] = useState(false)
 
   const onFinish = async (values: LoginFormValues) => {
     try {
@@ -33,6 +35,29 @@ const Login: React.FC = () => {
     }
   }
 
+  const handleWechatLogin = async () => {
+    try {
+      setWechatLoading(true)
+      const result = await getWechatAuthUrl()
+      // 保存 state 到 localStorage 用于回调时验证
+      localStorage.setItem("wechat_state", result.state)
+      // 记录登录前的来源页，登录成功后跳回
+      const from = window.location.pathname + window.location.search
+      if (from !== "/login" && from !== "/register") {
+        localStorage.setItem("login_redirect", from)
+      } else {
+        localStorage.removeItem("login_redirect")
+      }
+      // 跳转到微信授权页
+      window.location.href = result.auth_url
+    } catch (error) {
+      if (!(error as { __msgShown?: boolean })?.__msgShown)
+        message.error("微信登录暂不可用，请稍后重试")
+    } finally {
+      setWechatLoading(false)
+    }
+  }
+
   return (
     <div className="xx-auth-page">
       <div className="xx-auth-card">
@@ -100,10 +125,11 @@ const Login: React.FC = () => {
           <button
             type="button"
             className="xx-btn-wechat"
-            onClick={() => message.info("微信登录功能开发中")}
+            onClick={handleWechatLogin}
+            disabled={wechatLoading}
           >
             <span className="xx-wechat-icon">💬</span>
-            微信登录
+            {wechatLoading ? "加载中..." : "微信登录"}
           </button>
         </div>
 

apps/web/src/pages/auth/WechatCallback.tsx

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

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

@@ -20,8 +20,8 @@ import {
   getTemplateCategories,
   MODE_LABELS,
 } from "@/api/editingPlanner"
-import type { MediaAsset, TransitionEffect, TitleConfig } from "@/api/editPlans"
-import { getMediaAssets, getEditPlan, getEditPlanClips } from "@/api/editPlans"
+import type { MediaAsset, TransitionEffect, TitleConfig } from "@/api/templateEditor"
+import { getMediaAssets, getEditPlan, getEditPlanClips } from "@/api/templateEditor"
 import { useUndoRedo } from "./hooks/useUndoRedo"
 import type {
   ClipData,

apps/web/src/pages/editing-planner/components/ClipPropertiesPanel.tsx

@@ -6,7 +6,7 @@ import React, { useRef, useState, useCallback } from "react"
 import { useNavigate } from "react-router-dom"
 import type { TemplateMode } from "@/api/editingPlanner"
 import type { ClipData, ClipType } from "../types"
-import { TRANSITION_OPTIONS } from "@/api/editPlans"
+import { TRANSITION_OPTIONS } from "@/api/templateEditor"
 import type { AssetItem } from "@/api/assets"
 
 interface SubtitleSettings {

apps/web/src/pages/editing-planner/components/GenerationHistoryModal.tsx

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

apps/web/src/pages/editing-planner/components/IntroOutroPanel.tsx

@@ -7,7 +7,7 @@ import React, { useCallback } from "react"
 import { Drawer } from "antd"
 import type { IntroOutroConfig, IntroOutroItem, IntroOutroKind, TransitionType } from "../types"
 import { DEFAULT_INTRO_OUTRO } from "../types"
-import { TRANSITION_OPTIONS } from "@/api/editPlans"
+import { TRANSITION_OPTIONS } from "@/api/templateEditor"
 
 /* ──────────── 常量 ──────────── */
 

apps/web/src/pages/editing-planner/components/MediaPanel.tsx

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

apps/web/src/pages/editing-planner/components/PreviewPlayer.tsx

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

apps/web/src/pages/editing-planner/components/TimelinePanel.tsx

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

apps/web/src/pages/editing-planner/components/TransitionSelector.tsx

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

apps/web/src/pages/editing-planner/hooks/useEditPlanClips.ts

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

apps/web/src/pages/generate/GeneratePage.tsx

@@ -25,16 +25,16 @@ import {
 import type { AssetItem } from "@/api/assets"
 import { getAssets, getAssetLibraries } from "@/api/assets"
 import {
-  createEditPlan,
   generateEditPlan,
   updateEditPlan,
   getGenerationTaskResults,
-} from "@/api/editPlans"
-import type { GeneratedVideo, EditPlanConfig, TitleConfig } from "@/api/editPlans"
+  getGenerationStatus,
+  getEditPlan,
+} from "@/api/templateEditor"
+import type { GeneratedVideo, EditPlanConfig, TitleConfig } from "@/api/templateEditor"
 import type { CoverConfig } from "../editing-planner/types"
 import { getEditingTemplates } from "@/api/editingPlanner"
 import { getTitles } from "@/api/titles"
-import apiClient from "@/api/client"
 import { fetchPresetVoices } from "@/api/voices"
 import type { PresetVoiceItem } from "@/api/voices"
 import { formatDuration } from "@/api/voiceClone"
@@ -44,7 +44,6 @@ import { synthesizeSpeech, getTTSJobStatus, saveTtsToLibrary } from "@/api/tts"
 import { getTags, createTag } from "@/api/tags"
 import { useCloneProgress } from "@/hooks/useCloneProgress"
 import { useSearchParams, useNavigate } from "react-router-dom"
-import { getEditPlan } from "@/api/editPlans"
 import "./generate.css"
 
 const { Text } = Typography
@@ -588,7 +587,7 @@ const GeneratePage: React.FC = () => {
 
   const handleRefreshMatch = useCallback(async () => {
     if (materials.items.length <= 5) {
-      message.info("素材库素材较少，无法换一批")
+      message.info("视频库素材较少，无法换一批")
       return
     }
     setSmartMatching(true)
@@ -994,8 +993,11 @@ const GeneratePage: React.FC = () => {
         if (customVoiceText.trim()) voiceConfig.custom_text = customVoiceText.trim()
       }
 
-      const plan = await createEditPlan({
-        template_id: selectedTemplate,
+      // 获取或创建草稿（新架构：GET /templates/{templateId}/editor 自动创建）
+      await getEditPlan(selectedTemplate)
+
+      // 更新草稿内容 + 切换到 editing 状态
+      await updateEditPlan(selectedTemplate, {
         name: titleSettings.title.trim(),
         config: {
           asset_ids: materialMode === "auto" ? smartSelectedIds : selectedMaterials,
@@ -1018,18 +1020,14 @@ const GeneratePage: React.FC = () => {
           material_mode: materialMode,
         },
         total_duration: duration,
-        source_edit_plan_id: editPlanId || undefined,
+        status: "editing",
       })
 
-      // 后端要求计划处于 editing 状态才能触发渲染，自动转换状态
-      await updateEditPlan(plan.id, { status: "editing" })
-
-      await generateEditPlan(plan.id)
+      await generateEditPlan(selectedTemplate)
 
       const poll = async () => {
         try {
-          const status = await apiClient.get(`/edit-plans/${plan.id}/generation-status`)
-          const data = status.data
+          const data = await getGenerationStatus(selectedTemplate)
 
           if (data.plan_status === "completed") {
             setProgress(100)
@@ -1059,7 +1057,7 @@ const GeneratePage: React.FC = () => {
               dataAny.error_message ||
               dataAny.error ||
               dataAny.message ||
-              (data.clips || []).find((c: any) => c.status === "failed")?.error_message ||
+              (data.clips || []).find((c) => c.status === "failed")?.error_message ||
               "视频生成失败，请联系管理员或重试"
             // 安全提取字符串：递归处理嵌套对象（后端可能返回 {code, message: {code, message}} 等嵌套结构）
             const safeExtract = (val: unknown): string => {
@@ -1076,7 +1074,7 @@ const GeneratePage: React.FC = () => {
               return String(val ?? "")
             }
             const errorMsg = safeExtract(rawMsg)
-            console.error("[生成失败] planId:", plan.id, "响应:", data)
+            console.error("[生成失败] templateId:", selectedTemplate, "响应:", data)
             setGenerateError(errorMsg)
             message.error(errorMsg)
             return
@@ -1092,7 +1090,7 @@ const GeneratePage: React.FC = () => {
           >
         } catch (pollErr) {
           // 轮询接口本身出错（网络/鉴权等），记录并继续轮询一次
-          console.error("[轮询出错] planId:", plan.id, pollErr)
+          console.error("[轮询出错] templateId:", selectedTemplate, pollErr)
           progressTimer.current = setTimeout(poll, 3000) as unknown as ReturnType<
             typeof setInterval
           >
@@ -1199,7 +1197,6 @@ const GeneratePage: React.FC = () => {
     duration,
     autoSubtitles,
     bgm,
-    editPlanId,
     selectedTemplate,
     generateCount,
     materialMode,

apps/web/src/pages/voice-materials/VoiceMaterialLibrary.tsx

@@ -1953,7 +1953,7 @@ const VoiceMaterialLibrary: React.FC = () => {
                 icon={<PlusOutlined />}
                 onClick={handleTtsSave}
               >
-                保存到素材库
+                保存到配音库
               </Button>
             </div>
           )}

apps/web/src/router/index.tsx

@@ -9,6 +9,7 @@ import Login from "@/pages/auth/Login"
 import Register from "@/pages/auth/Register"
 import ForgotPassword from "@/pages/auth/ForgotPassword"
 import ResetPassword from "@/pages/auth/ResetPassword"
+import WechatCallback from "@/pages/auth/WechatCallback"
 import HomePage from "@/pages/home/HomePage"
 import { useAuthStore } from "@/store/authStore"
 
@@ -60,6 +61,10 @@ export const router = createBrowserRouter([
     path: "/reset-password",
     element: <ResetPassword />,
   },
+  {
+    path: "/auth/wechat/callback",
+    element: <WechatCallback />,
+  },
   {
     path: "/app",
     element: (

apps/web/src/test/api/editPlans.test.ts

@@ -23,7 +23,7 @@ import {
   copyEditPlan,
   getMediaAssets,
   getMediaAsset,
-} from "@/api/editPlans"
+} from "@/api/templateEditor"
 
 const mockGet = vi.fn()
 const mockPost = vi.fn()

apps/web/src/test/components/AssetSelector/AssetSelector.test.tsx

@@ -2,7 +2,7 @@ import React from "react"
 import { describe, it, expect, vi } from "vitest"
 import { render, screen } from "@testing-library/react"
 import AssetSelector from "@/components/AssetSelector/AssetSelector"
-import type { MediaAsset } from "@/api/editPlans"
+import type { MediaAsset } from "@/api/templateEditor"
 
 vi.mock("@/components/ui", () => ({
   Input: ({ placeholder }: any) => <input placeholder={placeholder} />,

apps/web/src/test/hooks/useAuth.test.tsx

@@ -7,8 +7,18 @@ import { renderHook, act } from "@testing-library/react"
 import { MemoryRouter } from "react-router-dom"
 
 const mockNavigate = vi.fn()
-const mockSetAuth = vi.fn()
-const mockClearAuth = vi.fn()
+const mockSetAuth = vi.fn((_user: any, accessToken: string, refreshToken?: string | null) => {
+  localStorage.setItem("access_token", accessToken)
+  if (refreshToken) {
+    localStorage.setItem("refresh_token", refreshToken)
+  } else {
+    localStorage.removeItem("refresh_token")
+  }
+})
+const mockClearAuth = vi.fn(() => {
+  localStorage.removeItem("access_token")
+  localStorage.removeItem("refresh_token")
+})
 const mockMutateAsync = vi.fn()
 const mockQueryClear = vi.fn()
 
@@ -99,7 +109,7 @@ describe("useAuth hooks", () => {
       expect(localStorage.getItem("access_token")).toBe("access-123")
       expect(localStorage.getItem("refresh_token")).toBe("refresh-456")
       expect(mockSetAuth).toHaveBeenCalled()
-      expect(mockNavigate).toHaveBeenCalledWith("/")
+      expect(mockNavigate).toHaveBeenCalledWith("/", { replace: true })
     })
 
     it("没有 refresh_token 时从 localStorage 移除", async () => {

apps/web/src/test/pages/EditingPlanner.test.tsx

@@ -146,7 +146,7 @@ vi.mock("@/api/editingPlanner", () => ({
   MODE_LABELS: { pip: "画中画", intro_outro: "片头片尾", watermark: "水印" },
 }))
 
-vi.mock("@/api/editPlans", () => ({
+vi.mock("@/api/templateEditor", () => ({
   getMediaAssets: vi.fn().mockResolvedValue({ items: [] }),
   getEditPlanGenerations: vi.fn().mockResolvedValue({ items: [] }),
   generateCover: vi.fn().mockResolvedValue({}),

apps/web/src/test/pages/GeneratePage.test.tsx

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

apps/web/src/test/pages/editing-planner/hooks/useEditPlanClips.test.ts

@@ -32,7 +32,7 @@ vi.mock("antd", () => ({
   },
 }))
 
-vi.mock("@/api/editPlans", () => ({
+vi.mock("@/api/templateEditor", () => ({
   getEditPlanClips: vi.fn().mockResolvedValue({ items: [], total: 0 }),
   createEditPlanClip: vi.fn().mockResolvedValue({}),
   updateEditPlanClip: vi.fn().mockResolvedValue({}),

apps/worker/worker_app/tasks/edit_plan_generation.py

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

infra/docker/api.Dockerfile

@@ -1,33 +1,69 @@
 # ============================================================
-# API Dockerfile - 专门用于 FastAPI 应用
-# 优化：依赖分层缓存 + 多阶段构建基础层
+# API Dockerfile - FastAPI 应用
+# 优化：多阶段构建 + pip cache mount + 依赖分层缓存
 # ============================================================
 
-# 基础镜像：Python 3.12
-FROM git.xiaoxiajianji.com/xiaoxia/base/python:3.12-slim
+# ==================== Builder 阶段 ====================
+FROM git.xiaoxiajianji.com/xiaoxia/base/python:3.12-slim AS builder
+
+# 使用阿里云镜像加速
+RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null || \
+    sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true
+
+# 安装编译依赖（仅 builder 需要）
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# 创建虚拟环境
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+WORKDIR /tmp
+
+# ---- 依赖分层：基础依赖（变化少，缓存命中率高）----
+COPY requirements-base.txt /tmp/requirements-base.txt
+
+RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
+    pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
+    -r /tmp/requirements-base.txt \
+    && rm /tmp/requirements-base.txt
+
+# ---- 依赖分层：业务依赖（变化频繁）----
+COPY requirements.txt /tmp/requirements.txt
+
+RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
+    pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
+    -r /tmp/requirements.txt \
+    && rm /tmp/requirements.txt
+
+# ---- Python 依赖瘦身 ----
+RUN find /opt/venv -name "*.so" -type f -exec strip --strip-all {} \; 2>/dev/null || true
+RUN find /opt/venv -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null; \
+    find /opt/venv -name "*.pyc" -delete 2>/dev/null || true
+
+# ==================== Runtime 阶段 ====================
+FROM git.xiaoxiajianji.com/xiaoxia/base/python:3.12-slim AS runtime
 
 # 构建参数：版本号（CI 传入 commit hash）
 ARG APP_VERSION=dev
 
 # 使用阿里云镜像加速
-RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null ||     sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true
+RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null || \
+    sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true
 
-# 安装系统依赖
-RUN apt-get update && apt-get install -y --no-install-recommends     libpq-dev     && rm -rf /var/lib/apt/lists/*
+# 只装运行时需要的库（libpq5 是 psycopg2 运行时依赖）
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpq5 \
+    && rm -rf /var/lib/apt/lists/*
+
+# 从 builder 复制虚拟环境
+COPY --from=builder /opt/venv /opt/venv
 
 # 设置工作目录
 WORKDIR /app
 
-# ---- 依赖分层：基础依赖（变化少，缓存命中率高）----
-COPY requirements-base.txt /tmp/requirements-base.txt
-
-RUN python -m venv /opt/venv     && /opt/venv/bin/pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com -r /tmp/requirements-base.txt     && rm /tmp/requirements-base.txt
-
-# ---- 依赖分层：业务依赖（变化频繁）----
-COPY requirements.txt /tmp/requirements.txt
-
-RUN /opt/venv/bin/pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com -r /tmp/requirements.txt     && rm /tmp/requirements.txt
-
 # 复制应用代码
 COPY apps/api/ /app/apps/api/
 COPY packages/ /app/packages/
@@ -43,7 +79,8 @@ ENV PYTHONUNBUFFERED=1
 ENV APP_VERSION=$APP_VERSION
 
 # 健康检查
-HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3     CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=5)"
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=5)"
 
 # API 入口点
 WORKDIR /app/apps/api

infra/docker/worker.Dockerfile

@@ -1,9 +1,10 @@
 # ============================================================
-# Worker Dockerfile - 优化版（多阶段构建 + 镜像瘦身）
+# Worker Dockerfile - 优化版（多阶段构建 + 镜像瘦身 + cache mount加速）
 # 优化项：
 #   1. 多阶段构建：builder 阶段安装编译依赖，runtime 阶段只保留运行时
-#   2. ffmpeg 静态编译替换：从 apt 安装(457MB) 改为静态二进制(~80MB)
+#   2. ffmpeg 通过 apt 安装（阿里云镜像加速，几秒完成，稳定可靠）
 #   3. Python 依赖瘦身：strip .so 调试符号 + 清理测试文件 + 清理缓存
+#   4. pip cache mount：加速依赖下载（跨构建共享pip wheel缓存）
 # ============================================================
 
 # ==================== Builder 阶段 ====================
@@ -19,19 +20,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     g++ \
     python3-dev \
     binutils \
-    wget \
-    xz-utils \
     && rm -rf /var/lib/apt/lists/*
 
-# ---- 下载静态编译 ffmpeg ----
-# 使用 johnvansickle.com 的静态编译版本（业界标准）
-RUN cd /tmp \
-    && wget -q https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz \
-    && tar xf ffmpeg-release-amd64-static.tar.xz \
-    && cp ffmpeg-*-amd64-static/ffmpeg /usr/local/bin/ffmpeg \
-    && cp ffmpeg-*-amd64-static/ffprobe /usr/local/bin/ffprobe \
-    && chmod +x /usr/local/bin/ffmpeg /usr/local/bin/ffprobe \
-    && rm -rf ffmpeg-*
 
 # ---- 安装 Python 依赖 ----
 WORKDIR /tmp
@@ -42,19 +32,22 @@ ENV PATH="/opt/venv/bin:$PATH"
 
 # 基础依赖
 COPY requirements-base.txt /tmp/requirements-base.txt
-RUN pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
+RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
+    pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
     -r /tmp/requirements-base.txt \
     && rm /tmp/requirements-base.txt
 
 # Worker 专属大包
 COPY requirements-worker.txt /tmp/requirements-worker.txt
-RUN pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
+RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
+    pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
     -r /tmp/requirements-worker.txt \
     && rm /tmp/requirements-worker.txt
 
 # 业务依赖
 COPY requirements.txt /tmp/requirements.txt
-RUN pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
+RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
+    pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
     -r /tmp/requirements.txt \
     && rm /tmp/requirements.txt
 
@@ -86,13 +79,10 @@ RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debia
 
 # 安装最小运行时依赖（opencv-python-headless 需要 libglib2.0-0）
 RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
     libglib2.0-0 \
     && rm -rf /var/lib/apt/lists/*
 
-# 从 builder 复制 ffmpeg 静态二进制
-COPY --from=builder /usr/local/bin/ffmpeg /usr/local/bin/ffmpeg
-COPY --from=builder /usr/local/bin/ffprobe /usr/local/bin/ffprobe
-
 # 从 builder 复制 Python 虚拟环境
 COPY --from=builder /opt/venv /opt/venv
 

packages/adapters/in_memory/user_repository.py

@@ -17,6 +17,9 @@ class InMemoryUserRepository(UserRepository):
         self._username_index: Dict[str, str] = {}  # username -> user_id
         self._verification_token_index: Dict[str, str] = {}  # token -> user_id
         self._reset_token_index: Dict[str, str] = {}  # token -> user_id
+        self._wechat_openid_index: Dict[str, str] = {}  # openid -> user_id
+        self._wechat_unionid_index: Dict[str, str] = {}  # unionid -> user_id
+        self._phone_index: Dict[str, str] = {}  # phone -> user_id
 
     def save(self, user: User) -> None:
         """保存用户"""
@@ -28,6 +31,12 @@ class InMemoryUserRepository(UserRepository):
             self._verification_token_index[user.email_verification_token] = user.id
         if user.password_reset_token:
             self._reset_token_index[user.password_reset_token] = user.id
+        if user.wechat_openid:
+            self._wechat_openid_index[user.wechat_openid] = user.id
+        if user.wechat_unionid:
+            self._wechat_unionid_index[user.wechat_unionid] = user.id
+        if user.phone:
+            self._phone_index[user.phone] = user.id
 
     def find_by_id(self, user_id: str) -> Optional[User]:
         """根据 ID 查找用户"""
@@ -61,6 +70,31 @@ class InMemoryUserRepository(UserRepository):
             return self._users.get(user_id)
         return None
 
+    def find_by_wechat_openid(self, openid: str) -> Optional[User]:
+        """根据微信 openid 查找用户"""
+        user_id = self._wechat_openid_index.get(openid)
+        if user_id:
+            return self._users.get(user_id)
+        return None
+
+    def find_by_wechat_unionid(self, unionid: str) -> Optional[User]:
+        """根据微信 unionid 查找用户"""
+        if not unionid:
+            return None
+        user_id = self._wechat_unionid_index.get(unionid)
+        if user_id:
+            return self._users.get(user_id)
+        return None
+
+    def find_by_phone(self, phone: str) -> Optional[User]:
+        """根据手机号查找用户"""
+        if not phone:
+            return None
+        user_id = self._phone_index.get(phone)
+        if user_id:
+            return self._users.get(user_id)
+        return None
+
     def delete(self, user_id: str) -> bool:
         """删除用户"""
         user = self._users.get(user_id)

packages/adapters/sms/sms_service.py

@@ -0,0 +1,85 @@
+"""
+短信服务实现（Noop + 阿里云）
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+class NoopSmsService:
+    """空实现短信服务 - 开发/测试环境用，只打日志不真发"""
+
+    def send_verification_code(self, phone: str, code: str) -> bool:
+        logger.info("[NoopSMS] 发送验证码到 %s: %s", phone, code)
+        return True
+
+    def send_template_sms(self, phone: str, template_id: str, params: dict) -> bool:
+        logger.info("[NoopSMS] 发送模板短信到 %s, template=%s, params=%s", phone, template_id, params)
+        return True
+
+
+class AliyunSmsService:
+    """阿里云短信服务"""
+
+    def __init__(
+        self,
+        access_key_id: str | None = None,
+        access_key_secret: str | None = None,
+        sign_name: str | None = None,
+        verify_template_id: str | None = None,
+    ):
+        self.access_key_id = access_key_id or os.environ.get("ALIYUN_SMS_ACCESS_KEY_ID", "")
+        self.access_key_secret = access_key_secret or os.environ.get("ALIYUN_SMS_ACCESS_KEY_SECRET", "")
+        self.sign_name = sign_name or os.environ.get("ALIYUN_SMS_SIGN_NAME", "小应剪辑")
+        self.verify_template_id = verify_template_id or os.environ.get("ALIYUN_SMS_VERIFY_TEMPLATE_ID", "SMS_123456789")
+
+    def send_verification_code(self, phone: str, code: str) -> bool:
+        return self.send_template_sms(phone, self.verify_template_id, {"code": code})
+
+    def send_template_sms(self, phone: str, template_id: str, params: dict) -> bool:
+        try:
+            import json
+
+            from alibabacloud_dysmsapi20170525 import models as dysmsapi_models
+            from alibabacloud_dysmsapi20170525.client import Client as DysmsapiClient
+            from alibabacloud_tea_openapi import models as open_api_models
+
+            config = open_api_models.Config(
+                access_key_id=self.access_key_id,
+                access_key_secret=self.access_key_secret,
+            )
+            config.endpoint = "dysmsapi.aliyuncs.com"
+            client = DysmsapiClient(config)
+
+            request = dysmsapi_models.SendSmsRequest(
+                phone_numbers=phone,
+                sign_name=self.sign_name,
+                template_code=template_id,
+                template_param=json.dumps(params),
+            )
+            response = client.send_sms(request)
+            body = response.body
+            if body.code == "OK":
+                logger.info("阿里云短信发送成功: phone=%s, template=%s", phone, template_id)
+                return True
+            else:
+                logger.error("阿里云短信发送失败: code=%s, message=%s", body.code, body.message)
+                return False
+        except ImportError:
+            logger.error("阿里云短信 SDK 未安装，请 pip install alibabacloud-dysmsapi20170525")
+            return False
+        except Exception as e:
+            logger.error("阿里云短信发送异常: %s", e, exc_info=True)
+            return False
+
+
+def get_sms_service() -> "NoopSmsService | AliyunSmsService":
+    """获取短信服务实例"""
+    provider = os.environ.get("SMS_PROVIDER", "noop").lower()
+    if provider == "aliyun":
+        return AliyunSmsService()
+    return NoopSmsService()

packages/adapters/sqlalchemy_impl/edit_plan_repository.py

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

packages/adapters/sqlalchemy_impl/models.py

@@ -31,9 +31,13 @@ class UserModel(Base):
     used_storage_gb = Column(Integer, nullable=False, default=0)
     # 管理员标识
     is_admin = Column(Boolean, nullable=False, default=False)
-    # 微信登录（小程序端）
+    # 微信登录
     wechat_openid = Column(String(128), nullable=True, unique=True, index=True)
     wechat_unionid = Column(String(128), nullable=True, unique=True, index=True)
+    # 手机号绑定
+    phone = Column(String(32), nullable=True, unique=True, index=True)
+    phone_verified = Column(Boolean, nullable=False, default=False)
+    binding_completed_at = Column(DateTime, nullable=True)
     created_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))
 
 
@@ -172,7 +176,6 @@ class EditPlanModel(Base):
     name = Column(String(200), nullable=False)
     status = Column(String(20), nullable=False, default="draft", index=True)
     total_duration = Column(Float, nullable=False, default=0.0)
-    result_count = Column(Integer, nullable=False, default=0)
     config = Column(JSON, nullable=False, default=dict)
     source_edit_plan_id = Column(String(36), nullable=True, index=True)
     project_id = Column(String(36), nullable=False, default="", index=True)
@@ -556,3 +559,18 @@ class BillingRecordModel(Base):
     invoice_url = Column(String(500), nullable=True)
     created_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))
     paid_at = Column(DateTime, nullable=True)
+
+
+class VerificationCodeModel(Base):
+    """验证码（邮箱/手机统一管理）"""
+
+    __tablename__ = "verification_codes"
+
+    id = Column(String(36), primary_key=True)
+    recipient = Column(String(255), nullable=False, index=True)  # 邮箱或手机号
+    code = Column(String(10), nullable=False)
+    code_type = Column(String(32), nullable=False, index=True)  # email_bind / phone_bind / ...
+    expires_at = Column(DateTime, nullable=False)
+    used_at = Column(DateTime, nullable=True)
+    attempts = Column(Integer, nullable=False, default=0)
+    created_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))

packages/adapters/sqlalchemy_impl/template_clip_config_repository.py

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

packages/adapters/sqlalchemy_impl/user_repository.py

@@ -35,6 +35,9 @@ class SQLAlchemyUserRepository(UserRepository):
         model.is_admin = user.is_admin
         model.wechat_openid = user.wechat_openid
         model.wechat_unionid = user.wechat_unionid
+        model.phone = user.phone
+        model.phone_verified = user.phone_verified
+        model.binding_completed_at = user.binding_completed_at
         model.created_at = user.created_at
 
         self.session.commit()
@@ -61,6 +64,12 @@ class SQLAlchemyUserRepository(UserRepository):
         model = self.session.query(UserModel).filter(UserModel.wechat_unionid == unionid.strip()).first()
         return self._to_entity(model)
 
+    def find_by_phone(self, phone: str) -> User | None:
+        if not phone or not phone.strip():
+            return None
+        model = self.session.query(UserModel).filter(UserModel.phone == phone.strip()).first()
+        return self._to_entity(model)
+
     def find_by_verification_token(self, token: str) -> User | None:
         model = self.session.query(UserModel).filter(UserModel.email_verification_token == token).first()
         return self._to_entity(model)
@@ -101,5 +110,8 @@ class SQLAlchemyUserRepository(UserRepository):
             is_admin=model.is_admin or False,
             wechat_openid=model.wechat_openid,
             wechat_unionid=model.wechat_unionid,
+            phone=model.phone,
+            phone_verified=model.phone_verified or False,
+            binding_completed_at=model.binding_completed_at,
             created_at=model.created_at,
         )

packages/adapters/sqlalchemy_impl/verification_code_repository.py

@@ -0,0 +1,79 @@
+"""
+验证码仓储 SQLAlchemy 实现
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from sqlalchemy.orm import Session
+
+from packages.adapters.sqlalchemy_impl.models import VerificationCodeModel
+from packages.domain.verification_code import VerificationCode
+from packages.ports.verification_code_repository import VerificationCodeRepository
+
+
+class SQLAlchemyVerificationCodeRepository(VerificationCodeRepository):
+    def __init__(self, session: Session):
+        self.session = session
+
+    def save(self, code: VerificationCode) -> None:
+        model = self.session.get(VerificationCodeModel, code.id)
+        if model is None:
+            model = VerificationCodeModel(id=code.id)
+            self.session.add(model)
+
+        model.recipient = code.recipient
+        model.code = code.code
+        model.code_type = code.code_type
+        model.expires_at = code.expires_at
+        model.used_at = code.used_at
+        model.attempts = code.attempts
+        model.created_at = code.created_at
+
+        self.session.commit()
+        self.session.refresh(model)
+
+    def find_latest(self, recipient: str, code_type: str) -> Optional[VerificationCode]:
+        model = (
+            self.session.query(VerificationCodeModel)
+            .filter(
+                VerificationCodeModel.recipient == recipient.strip(),
+                VerificationCodeModel.code_type == code_type,
+            )
+            .order_by(VerificationCodeModel.created_at.desc())
+            .first()
+        )
+        return self._to_entity(model)
+
+    def find_by_id(self, code_id: str) -> Optional[VerificationCode]:
+        return self._to_entity(self.session.get(VerificationCodeModel, code_id))
+
+    def count_today(self, recipient: str, code_type: str) -> int:
+        now = datetime.now(timezone.utc)
+        start_of_day = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        return (
+            self.session.query(VerificationCodeModel)
+            .filter(
+                VerificationCodeModel.recipient == recipient.strip(),
+                VerificationCodeModel.code_type == code_type,
+                VerificationCodeModel.created_at >= start_of_day,
+            )
+            .count()
+        )
+
+    @staticmethod
+    def _to_entity(model: VerificationCodeModel | None) -> VerificationCode | None:
+        if model is None:
+            return None
+        return VerificationCode(
+            id=model.id,
+            recipient=model.recipient,
+            code=model.code,
+            code_type=model.code_type,
+            expires_at=model.expires_at,
+            used_at=model.used_at,
+            attempts=model.attempts,
+            created_at=model.created_at,
+        )

packages/application/auth/bind_contact_use_case.py

@@ -0,0 +1,231 @@
+"""
+微信登录 + 绑定手机号邮箱 Use Case
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Optional
+
+from packages.application.auth.verification_code_service import (
+    CODE_TYPE_EMAIL_BIND,
+    CODE_TYPE_PHONE_BIND,
+    normalize_phone,
+    validate_email,
+    validate_phone,
+)
+from packages.domain.entities import User
+
+logger = logging.getLogger(__name__)
+
+
+class BindContactRequest:
+    """绑定联系方式请求"""
+
+    def __init__(
+        self,
+        user_id: str,
+        phone: str = "",
+        phone_code: str = "",
+        email: str = "",
+        email_code: str = "",
+    ):
+        self.user_id = user_id
+        self.phone = normalize_phone(phone) if phone else ""
+        self.phone_code = phone_code.strip() if phone_code else ""
+        self.email = email.strip().lower() if email else ""
+        self.email_code = email_code.strip() if email_code else ""
+
+
+class BindContactResponse:
+    """绑定响应"""
+
+    def __init__(self, user: User):
+        self.user = user
+
+    def to_dict(self) -> dict:
+        return {
+            "user": {
+                "id": self.user.id,
+                "email": self.user.email,
+                "phone": self.user.phone,
+                "phone_verified": self.user.phone_verified,
+                "display_name": self.user.display_name,
+                "binding_complete": self.user.binding_completed_at is not None,
+            }
+        }
+
+
+class BindContactUseCase:
+    """绑定手机+邮箱用例"""
+
+    def __init__(
+        self,
+        user_repository,
+        verification_code_service,
+        email_service=None,
+    ):
+        self.user_repo = user_repository
+        self.verification_service = verification_code_service
+        self.email_service = email_service
+
+    def execute(self, request: BindContactRequest) -> tuple[Optional[BindContactResponse], Optional[str]]:
+        try:
+            # 1. 校验参数
+            if not request.phone and not request.email:
+                return None, "至少填写手机号或邮箱"
+
+            # 2. 查找用户
+            user = self.user_repo.find_by_id(request.user_id)
+            if not user:
+                return None, "用户不存在"
+
+            # 3. 手机号绑定
+            if request.phone:
+                ok, err = validate_phone(request.phone)
+                if not ok:
+                    return None, err
+
+                if not request.phone_code:
+                    return None, "请输入手机验证码"
+
+                # 校验手机号未被其他账号绑定
+                existing = self.user_repo.find_by_phone(request.phone)
+                if existing and existing.id != user.id:
+                    return None, "该手机号已被其他账号绑定"
+
+                # 校验验证码
+                ok, err = self.verification_service.verify(
+                    recipient=request.phone,
+                    code_type=CODE_TYPE_PHONE_BIND,
+                    code_value=request.phone_code,
+                )
+                if not ok:
+                    return None, f"手机验证码错误：{err}"
+
+                user.phone = request.phone
+                user.phone_verified = True
+
+            # 4. 邮箱绑定
+            if request.email:
+                ok, err = validate_email(request.email)
+                if not ok:
+                    return None, err
+
+                if not request.email_code:
+                    return None, "请输入邮箱验证码"
+
+                # 校验邮箱未被其他账号绑定
+                existing = self.user_repo.find_by_email(request.email)
+                if existing and existing.id != user.id:
+                    return None, "该邮箱已被其他账号绑定"
+
+                # 校验验证码
+                ok, err = self.verification_service.verify(
+                    recipient=request.email,
+                    code_type=CODE_TYPE_EMAIL_BIND,
+                    code_value=request.email_code,
+                )
+                if not ok:
+                    return None, f"邮箱验证码错误：{err}"
+
+                user.email = request.email
+                user.email_verified = True
+
+            # 5. 判断是否完成绑定
+            if user.phone_verified and user.email_verified and "@wechat.local" not in user.email:
+                user.binding_completed_at = datetime.now(timezone.utc)
+
+            # 6. 保存
+            self.user_repo.save(user)
+
+            return BindContactResponse(user=user), None
+
+        except Exception as e:
+            logger.error("绑定联系方式失败: %s", e, exc_info=True)
+            return None, f"绑定失败: {str(e)}"
+
+
+class SendVerificationCodeRequest:
+    """发送验证码请求"""
+
+    def __init__(self, target: str, value: str, purpose: str):
+        self.target = target  # phone / email
+        self.value = value.strip()
+        self.purpose = purpose  # bind / login / reset_password
+
+
+class SendVerificationCodeResponse:
+    """发送验证码响应"""
+
+    def __init__(self, expires_in: int, resend_after: int):
+        self.expires_in = expires_in
+        self.resend_after = resend_after
+
+    def to_dict(self) -> dict:
+        return {
+            "expires_in": self.expires_in,
+            "resend_after": self.resend_after,
+        }
+
+
+class SendVerificationCodeUseCase:
+    """发送验证码用例"""
+
+    def __init__(
+        self,
+        verification_code_service,
+        sms_service=None,
+        email_service=None,
+    ):
+        self.verification_service = verification_code_service
+        self.sms_service = sms_service
+        self.email_service = email_service
+
+    def execute(
+        self, request: SendVerificationCodeRequest
+    ) -> tuple[Optional[SendVerificationCodeResponse], Optional[str]]:
+        try:
+            # 1. 确定 code_type
+            if request.target == "phone":
+                ok, err = validate_phone(request.value)
+                if not ok:
+                    return None, err
+                code_type = f"{request.target}_{request.purpose}"
+                recipient = normalize_phone(request.value)
+            elif request.target == "email":
+                ok, err = validate_email(request.value)
+                if not ok:
+                    return None, err
+                code_type = f"{request.target}_{request.purpose}"
+                recipient = request.value.lower()
+            else:
+                return None, f"不支持的目标类型: {request.target}"
+
+            # 2. 生成验证码
+            code_obj, err = self.verification_service.generate(recipient, code_type)
+            if err:
+                return None, err
+
+            # 3. 发送
+            if request.target == "phone" and self.sms_service:
+                self.sms_service.send_verification_code(recipient, code_obj.code)
+            elif request.target == "email" and self.email_service:
+                subject = "验证码 - 小应剪辑"
+                body = f"您的验证码是：{code_obj.code}，5分钟内有效。"
+                self.email_service.send_email(recipient, subject, body)
+
+            # 4. 返回
+            ttl = (code_obj.expires_at - code_obj.created_at).total_seconds()
+            return (
+                SendVerificationCodeResponse(
+                    expires_in=int(ttl),
+                    resend_after=60,
+                ),
+                None,
+            )
+
+        except Exception as e:
+            logger.error("发送验证码失败: %s", e, exc_info=True)
+            return None, f"发送失败: {str(e)}"

packages/application/auth/verification_code_service.py

@@ -0,0 +1,206 @@
+"""
+验证码服务
+- 生成验证码
+- 校验验证码
+- 频控（60s 冷却 + 每日上限）
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from datetime import datetime, timezone
+from typing import Optional
+
+from packages.domain.verification_code import VerificationCode
+from packages.ports.verification_code_repository import VerificationCodeRepository
+
+logger = logging.getLogger(__name__)
+
+# 频控参数
+RESEND_COOLDOWN_SECONDS = 60  # 重发冷却时间
+DAILY_LIMIT = 10  # 每日发送上限
+MAX_ATTEMPTS = 5  # 单验证码最大尝试次数
+DEFAULT_TTL_SECONDS = 300  # 默认有效期 5 分钟
+
+# 验证码类型
+CODE_TYPE_EMAIL_BIND = "email_bind"
+CODE_TYPE_PHONE_BIND = "phone_bind"
+CODE_TYPE_EMAIL_LOGIN = "email_login"
+CODE_TYPE_PHONE_LOGIN = "phone_login"
+CODE_TYPE_RESET_PASSWORD = "reset_password"
+
+VALID_CODE_TYPES = {
+    CODE_TYPE_EMAIL_BIND,
+    CODE_TYPE_PHONE_BIND,
+    CODE_TYPE_EMAIL_LOGIN,
+    CODE_TYPE_PHONE_LOGIN,
+    CODE_TYPE_RESET_PASSWORD,
+}
+
+
+class VerificationCodeService:
+    """验证码服务"""
+
+    def __init__(
+        self,
+        repo: VerificationCodeRepository,
+        resend_cooldown: int = RESEND_COOLDOWN_SECONDS,
+        daily_limit: int = DAILY_LIMIT,
+        max_attempts: int = MAX_ATTEMPTS,
+        default_ttl: int = DEFAULT_TTL_SECONDS,
+    ):
+        self.repo = repo
+        self.resend_cooldown = resend_cooldown
+        self.daily_limit = daily_limit
+        self.max_attempts = max_attempts
+        self.default_ttl = default_ttl
+
+    def generate(
+        self,
+        recipient: str,
+        code_type: str,
+        ttl_seconds: int | None = None,
+        custom_code: str | None = None,
+    ) -> tuple[Optional[VerificationCode], Optional[str]]:
+        """
+        生成验证码
+
+        Returns:
+            (验证码实体, 错误信息)
+        """
+        recipient = recipient.strip()
+
+        # 参数校验
+        if not recipient:
+            return None, "接收方不能为空"
+        if code_type not in VALID_CODE_TYPES:
+            return None, f"无效的验证码类型: {code_type}"
+
+        # 频控检查
+        can_send, wait_seconds = self._check_rate_limit(recipient, code_type)
+        if not can_send:
+            if wait_seconds > 0:
+                return None, f"发送太频繁，请 {wait_seconds} 秒后再试"
+            return None, "今日发送次数已达上限"
+
+        # 生成并保存
+        code = VerificationCode.create(
+            recipient=recipient,
+            code_type=code_type,
+            ttl_seconds=ttl_seconds or self.default_ttl,
+            custom_code=custom_code,
+        )
+        self.repo.save(code)
+
+        return code, None
+
+    def verify(
+        self,
+        recipient: str,
+        code_type: str,
+        code_value: str,
+        consume: bool = True,
+    ) -> tuple[bool, Optional[str]]:
+        """
+        校验验证码
+
+        Args:
+            recipient: 接收方（邮箱/手机号）
+            code_type: 验证码类型
+            code_value: 用户输入的验证码
+            consume: 校验成功后是否标记为已使用
+
+        Returns:
+            (是否通过, 错误信息)
+        """
+        recipient = recipient.strip()
+        code_value = code_value.strip()
+
+        if not recipient or not code_value:
+            return False, "参数不完整"
+
+        # 查找最新的验证码
+        latest = self.repo.find_latest(recipient, code_type)
+        if not latest:
+            return False, "验证码不存在或已过期"
+
+        # 增加尝试次数
+        latest.increment_attempts()
+        self.repo.save(latest)
+
+        # 检查是否已使用
+        if latest.is_used:
+            return False, "验证码已使用，请重新获取"
+
+        # 检查是否过期
+        if latest.is_expired:
+            return False, "验证码已过期，请重新获取"
+
+        # 检查尝试次数
+        if latest.attempts > self.max_attempts:
+            return False, "验证次数过多，请重新获取验证码"
+
+        # 校验验证码
+        if latest.code != code_value:
+            return False, "验证码错误"
+
+        # 校验通过，标记为已使用
+        if consume:
+            latest.mark_used()
+            self.repo.save(latest)
+
+        return True, None
+
+    def _check_rate_limit(self, recipient: str, code_type: str) -> tuple[bool, int]:
+        """
+        频控检查
+
+        Returns:
+            (是否允许发送, 需等待秒数)
+        """
+        # 检查冷却时间
+        latest = self.repo.find_latest(recipient, code_type)
+        if latest:
+            elapsed = (datetime.now(timezone.utc) - latest.created_at).total_seconds()
+            if elapsed < self.resend_cooldown:
+                wait = int(self.resend_cooldown - elapsed)
+                return False, wait
+
+        # 检查每日上限
+        today_count = self.repo.count_today(recipient, code_type)
+        if today_count >= self.daily_limit:
+            return False, 0
+
+        return True, 0
+
+
+def validate_phone(phone: str) -> tuple[bool, str]:
+    """校验手机号格式（中国大陆手机号）"""
+    phone = phone.strip()
+    if not phone:
+        return False, "手机号不能为空"
+    # 支持 +86 前缀或纯 11 位
+    pattern = r"^(\+86)?1[3-9]\d{9}$"
+    if not re.match(pattern, phone):
+        return False, "手机号格式不正确"
+    return True, ""
+
+
+def normalize_phone(phone: str) -> str:
+    """标准化手机号（去掉 +86 前缀，统一存储格式）"""
+    phone = phone.strip()
+    if phone.startswith("+86"):
+        phone = phone[3:]
+    return phone
+
+
+def validate_email(email: str) -> tuple[bool, str]:
+    """校验邮箱格式"""
+    email = email.strip()
+    if not email:
+        return False, "邮箱不能为空"
+    pattern = r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"
+    if not re.match(pattern, email):
+        return False, "邮箱格式不正确"
+    return True, ""

packages/application/auth/wechat_oauth_service.py

@@ -0,0 +1,206 @@
+"""
+微信 OAuth 服务
+- 生成授权链接（网页扫码登录）
+- 处理回调，用 code 换 access_token + 用户信息
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+import urllib.parse
+from dataclasses import dataclass
+from threading import Lock
+from typing import Optional
+from uuid import uuid4
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+STATE_TTL_SECONDS = 600  # state 有效期 10 分钟
+
+
+class MemoryStateStore:
+    """内存 state 存储（简单实现，单节点可用）
+
+    多实例部署时建议替换为 Redis 实现。
+    """
+
+    def __init__(self, ttl_seconds: int = STATE_TTL_SECONDS):
+        self._ttl = ttl_seconds
+        self._states: dict[str, float] = {}  # state -> expire_at
+        self._lock = Lock()
+
+    def put(self, state: str) -> None:
+        with self._lock:
+            self._clean_expired()
+            self._states[state] = time.time() + self._ttl
+
+    def verify_and_consume(self, state: str) -> bool:
+        with self._lock:
+            self._clean_expired()
+            if state in self._states:
+                del self._states[state]
+                return True
+            return False
+
+    def _clean_expired(self) -> None:
+        now = time.time()
+        expired = [s for s, exp in self._states.items() if exp < now]
+        for s in expired:
+            del self._states[s]
+
+
+@dataclass
+class WechatUserInfo:
+    """微信用户信息"""
+
+    openid: str
+    unionid: str = ""
+    nickname: str = ""
+    avatar_url: str = ""
+
+
+class WechatOAuthService:
+    """微信开放平台 OAuth 服务（网页扫码登录）"""
+
+    def __init__(
+        self,
+        app_id: str | None = None,
+        app_secret: str | None = None,
+        redirect_uri: str | None = None,
+        state_store=None,
+    ):
+        self.app_id = app_id or os.environ.get("WECHAT_OPEN_APP_ID", "")
+        self.app_secret = app_secret or os.environ.get("WECHAT_OPEN_APP_SECRET", "")
+        self.redirect_uri = redirect_uri or os.environ.get("WECHAT_OPEN_REDIRECT_URI", "")
+        # state 存储（CSRF 防护），默认内存实现
+        self._state_store = state_store or MemoryStateStore()
+
+    def is_configured(self) -> bool:
+        """检查微信配置是否完整"""
+        return bool(self.app_id and self.app_secret and self.redirect_uri)
+
+    def generate_auth_url(self, scope: str = "snsapi_login") -> tuple[str, str]:
+        """
+        生成微信授权链接
+
+        Returns:
+            (授权URL, state)
+        """
+        state = uuid4().hex
+        # 保存 state 用于回调校验（防 CSRF）
+        self._state_store.put(state)
+
+        if not self.is_configured():
+            # 未配置时返回 mock URL，方便前端联调
+            mock_params = urllib.parse.urlencode(
+                {
+                    "app_id": "mock",
+                    "redirect_uri": self.redirect_uri,
+                    "scope": scope,
+                    "state": state,
+                }
+            )
+            return f"/mock/wechat/auth?{mock_params}", state
+
+        params = {
+            "appid": self.app_id,
+            "redirect_uri": self.redirect_uri,
+            "response_type": "code",
+            "scope": scope,
+            "state": state,
+        }
+        url = "https://open.weixin.qq.com/connect/qrconnect?" + urllib.parse.urlencode(params) + "#wechat_redirect"
+        return url, state
+
+    def handle_callback(self, code: str, state: str) -> tuple[Optional[WechatUserInfo], Optional[str]]:
+        """
+        处理微信回调
+
+        Args:
+            code: 微信授权码
+            state: 防 CSRF 状态
+
+        Returns:
+            (微信用户信息, 错误信息)
+        """
+        if not code:
+            return None, "缺少授权码"
+
+        # 校验 state（防 CSRF）—— 一次性使用
+        if not state or not self._state_store.verify_and_consume(state):
+            logger.warning("微信回调 state 校验失败: state=%s", state)
+            return None, "无效的 state 参数，请求可能已过期或被篡改"
+
+        if not self.is_configured():
+            # 开发模式：返回 mock 用户信息
+            logger.info("微信未配置，使用 mock 用户信息")
+            return (
+                WechatUserInfo(
+                    openid=f"mock_{code[:20]}",
+                    unionid=f"mock_union_{code[:16]}",
+                    nickname="微信测试用户",
+                    avatar_url="",
+                ),
+                None,
+            )
+
+        try:
+            # 1. 用 code 换 access_token
+            token_url = "https://api.weixin.qq.com/sns/oauth2/access_token"
+            token_params = {
+                "appid": self.app_id,
+                "secret": self.app_secret,
+                "code": code,
+                "grant_type": "authorization_code",
+            }
+            token_resp = requests.get(token_url, params=token_params, timeout=10)
+            token_data = token_resp.json()
+
+            if "errcode" in token_data and token_data["errcode"] != 0:
+                logger.error("微信获取 access_token 失败: %s", token_data)
+                return None, f"微信授权失败: {token_data.get('errmsg', '未知错误')}"
+
+            access_token = token_data["access_token"]
+            openid = token_data["openid"]
+            unionid = token_data.get("unionid", "")
+
+            # 2. 获取用户信息
+            user_url = "https://api.weixin.qq.com/sns/userinfo"
+            user_params = {
+                "access_token": access_token,
+                "openid": openid,
+                "lang": "zh_CN",
+            }
+            user_resp = requests.get(user_url, params=user_params, timeout=10)
+            user_data = user_resp.json()
+
+            if "errcode" in user_data and user_data["errcode"] != 0:
+                logger.error("微信获取用户信息失败: %s", user_data)
+                return None, f"获取用户信息失败: {user_data.get('errmsg', '未知错误')}"
+
+            return (
+                WechatUserInfo(
+                    openid=openid,
+                    unionid=unionid,
+                    nickname=user_data.get("nickname", ""),
+                    avatar_url=user_data.get("headimgurl", ""),
+                ),
+                None,
+            )
+
+        except requests.RequestException as e:
+            logger.error("微信 OAuth 请求异常: %s", e, exc_info=True)
+            return None, "微信服务暂不可用，请稍后再试"
+        except Exception as e:
+            logger.error("微信回调处理异常: %s", e, exc_info=True)
+            return None, "微信登录处理失败"
+
+
+def get_wechat_oauth_service() -> WechatOAuthService:
+    """获取微信 OAuth 服务单例"""
+    # TODO: 可替换为 Redis state store
+    return WechatOAuthService()

packages/domain/auth/sms_service.py

@@ -0,0 +1,19 @@
+"""
+短信服务接口
+"""
+
+from abc import ABC, abstractmethod
+
+
+class SmsService(ABC):
+    """短信服务接口"""
+
+    @abstractmethod
+    def send_verification_code(self, phone: str, code: str) -> bool:
+        """发送验证码短信"""
+        pass
+
+    @abstractmethod
+    def send_template_sms(self, phone: str, template_id: str, params: dict) -> bool:
+        """发送模板短信"""
+        pass

packages/domain/edit_plan.py

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

packages/domain/entities.py

@@ -59,6 +59,11 @@ class User:
     wechat_openid: str | None = None
     wechat_unionid: str | None = None
 
+    # 手机号绑定
+    phone: str | None = None
+    phone_verified: bool = False
+    binding_completed_at: datetime | None = None
+
     created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
 
 

packages/domain/verification_code.py

@@ -0,0 +1,66 @@
+"""
+验证码领域实体
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from uuid import uuid4
+
+
+@dataclass(slots=True)
+class VerificationCode:
+    """验证码（邮箱/手机统一）"""
+
+    id: str
+    recipient: str  # 邮箱或手机号
+    code: str
+    code_type: str  # email_bind / phone_bind / email_login / phone_login / reset_password
+    expires_at: datetime
+    used_at: datetime | None = None
+    attempts: int = 0
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @classmethod
+    def create(
+        cls,
+        recipient: str,
+        code_type: str,
+        ttl_seconds: int = 300,
+        custom_code: str | None = None,
+    ) -> "VerificationCode":
+        """创建验证码"""
+        import random
+
+        code = custom_code or "".join(random.choices("0123456789", k=6))
+        now = datetime.now(timezone.utc)
+        return cls(
+            id=uuid4().hex,
+            recipient=recipient.strip(),
+            code=code,
+            code_type=code_type,
+            expires_at=now + timedelta(seconds=ttl_seconds),
+            created_at=now,
+        )
+
+    @property
+    def is_expired(self) -> bool:
+        """是否已过期"""
+        return datetime.now(timezone.utc) > self.expires_at
+
+    @property
+    def is_used(self) -> bool:
+        """是否已使用"""
+        return self.used_at is not None
+
+    @property
+    def is_valid(self) -> bool:
+        """是否有效（未过期且未使用）"""
+        return not self.is_expired and not self.is_used
+
+    def mark_used(self) -> None:
+        """标记为已使用"""
+        self.used_at = datetime.now(timezone.utc)
+
+    def increment_attempts(self) -> None:
+        """增加尝试次数"""
+        self.attempts += 1

packages/ports/user_repository.py

@@ -51,6 +51,11 @@ class UserRepository(ABC):
         """根据微信 unionid 查找用户"""
         pass
 
+    @abstractmethod
+    def find_by_phone(self, phone: str) -> Optional[User]:
+        """根据手机号查找用户"""
+        pass
+
     @abstractmethod
     def delete(self, user_id: str) -> bool:
         """删除用户"""

packages/ports/verification_code_repository.py

@@ -0,0 +1,32 @@
+"""
+验证码仓储接口
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from packages.domain.verification_code import VerificationCode
+
+
+class VerificationCodeRepository(ABC):
+    """验证码仓储接口"""
+
+    @abstractmethod
+    def save(self, code: VerificationCode) -> None:
+        """保存验证码"""
+        pass
+
+    @abstractmethod
+    def find_latest(self, recipient: str, code_type: str) -> Optional[VerificationCode]:
+        """查找最新的有效验证码"""
+        pass
+
+    @abstractmethod
+    def find_by_id(self, code_id: str) -> Optional[VerificationCode]:
+        """根据 ID 查找验证码"""
+        pass
+
+    @abstractmethod
+    def count_today(self, recipient: str, code_type: str) -> int:
+        """统计当日发送次数（频控用）"""
+        pass

scripts/agent-commit.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# Agent代码提交前自动格式化+质量检查脚本
+# 用法: scripts/agent-commit.sh <commit_message> [files...]
+# 效果: 自动跑black+isort+ruff check，通过后才commit+push
+set -e
+
+if [ $# -lt 1 ]; then
+  echo "用法: $0 <commit_message> [file1 file2 ...]"
+  echo "示例: $0 \"feat: add new api\" apps/api/src/"
+  exit 1
+fi
+
+COMMIT_MSG="$1"
+shift
+
+TARGETS="${@:-.}"
+
+cd "$(dirname "$0")/.."
+REPO_ROOT=$(pwd)
+echo "仓库根目录: $REPO_ROOT"
+echo "提交信息: $COMMIT_MSG"
+echo "目标路径: $TARGETS"
+echo ""
+
+# 后端代码格式化（Python文件）
+PYTHON_FILES=$(find $TARGETS -name "*.py" -type f 2>/dev/null | head -100 || true)
+if [ -n "$PYTHON_FILES" ]; then
+  echo "=== Step 1/4: 后端代码格式化 (black) ==="
+  if command -v black &> /dev/null; then
+    black $TARGETS 2>&1 | tail -3
+    echo "✅ black 完成"
+  else
+    echo "⚠️  未安装black，跳过"
+  fi
+  echo ""
+
+  echo "=== Step 2/4: import排序 (isort) ==="
+  if command -v isort &> /dev/null; then
+    isort $TARGETS 2>&1 | tail -3
+    echo "✅ isort 完成"
+  else
+    echo "⚠️  未安装isort，跳过"
+  fi
+  echo ""
+
+  echo "=== Step 3/4: 代码质量检查 (ruff check) ==="
+  if command -v ruff &> /dev/null; then
+    RUFF_OUTPUT=$(ruff check $TARGETS 2>&1) || true
+    RUFF_ERRORS=$(echo "$RUFF_OUTPUT" | grep -c "^" || echo 0)
+    if [ "$RUFF_ERRORS" -le 2 ] || echo "$RUFF_OUTPUT" | grep -q "All checks passed"; then
+      echo "✅ ruff 检查通过（错误数: $RUFF_ERRORS）"
+    else
+      echo "❌ ruff 发现以下问题:"
+      echo "$RUFF_OUTPUT" | head -30
+      echo ""
+      echo "请修复后重新提交，或手动忽略特定问题"
+      exit 1
+    fi
+  else
+    echo "⚠️  未安装ruff，跳过"
+  fi
+  echo ""
+else
+  echo "ℹ️  未检测到Python文件，跳过后端格式化"
+  echo ""
+fi
+
+# 前端代码格式化（TS/TSX文件）
+TS_FILES=$(find $TARGETS -name "*.ts" -o -name "*.tsx" -type f 2>/dev/null | head -100 || true)
+if [ -n "$TS_FILES" ] && [ -f "apps/web/package.json" ]; then
+  echo "=== Step 4/4: 前端代码格式化 (prettier) ==="
+  if command -v npx &> /dev/null; then
+    cd apps/web && npx prettier --write "src/**/*.{ts,tsx}" 2>&1 | tail -3 || true
+    cd "$REPO_ROOT"
+    echo "✅ prettier 完成"
+  else
+    echo "⚠️  未安装npx，跳过前端格式化"
+  fi
+  echo ""
+fi
+
+# Git操作
+echo "=== 提交代码 ==="
+git add -A
+git diff --cached --stat
+echo ""
+git commit -m "$COMMIT_MSG"
+echo ""
+echo "✅ 本地提交完成"
+
+# 可选：自动推送
+if [ "$AGENT_AUTO_PUSH" = "true" ]; then
+  echo "正在推送到远程..."
+  git push
+  echo "✅ 推送完成"
+else
+  echo "ℹ️  本地已提交，如需推送执行: git push"
+  echo "   设置 AGENT_AUTO_PUSH=true 可自动推送"
+fi

scripts/ci/auto_fix_formatting.py

@@ -62,7 +62,7 @@ def ensure_git_repo(api_url, repo, token, pr_number):
     # 强制checkout到源分支（覆盖tarball内容）
     # tarball是merge后的commit，源分支才是我们要修改并推送的目标
     print("切换到源分支...")
-    run(f"git checkout -B --force {head_branch} FETCH_HEAD")
+    run(f"git checkout -f -B {head_branch} FETCH_HEAD")
 
     result = run("git status --porcelain")
     if result.stdout.strip():

scripts/ci/check_migration_chain.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""
+检查 Alembic migration 编号连续性。
+
+扫描 alembic/versions/ 下所有 migration 文件，提取 revision 和 down_revision，
+验证整条链是否完整——每个 down_revision（除了 baseline 的 None）都必须对应一个存在的 revision。
+
+支持两种格式:
+    revision: str = "001"          # 旧格式（带类型注解）
+    revision = "038_error_retry"   # 新格式（带描述后缀）
+
+匹配策略：提取 revision 名称的数字前缀（如 "001"、"038"）作为唯一标识进行匹配，
+兼容纯数字编号和"数字_描述"两种命名风格。
+
+用法:
+    python3 scripts/ci/check_migration_chain.py [alembic_versions_dir]
+
+默认目录: alembic/versions/
+
+退出码:
+    0 - 链完整
+    1 - 有断链或其他错误
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+# 匹配 revision / down_revision，支持带类型注解和不带类型注解两种格式
+# revision: str = "xxx" 或 revision = "xxx"
+REV_PATTERN = re.compile(
+    r'^\s*revision\s*(?::\s*str\s*)?=\s*["\']([^"\']+)["\']',
+    re.MULTILINE,
+)
+DOWN_PATTERN = re.compile(
+    r'^\s*down_revision\s*(?::\s*(?:Union\[str,\s*None\]|str\s*\|\s*None|None|str)\s*)?=\s*(["\']([^"\']+)["\']|None)',
+    re.MULTILINE,
+)
+
+# 提取 revision 名称的数字前缀，如 "001" 或 "038_error_retry" → "038"
+NUM_PREFIX_PATTERN = re.compile(r"^(\d+)")
+
+
+def num_prefix(name: str) -> str:
+    """提取 revision 名称的数字前缀。"""
+    m = NUM_PREFIX_PATTERN.match(name)
+    return m.group(1) if m else name
+
+
+def extract_migration_info(filepath: Path) -> tuple[str, str | None]:
+    """从 migration 文件中提取 revision 和 down_revision（返回完整名称）。"""
+    content = filepath.read_text(encoding="utf-8")
+
+    rev_match = REV_PATTERN.search(content)
+    down_match = DOWN_PATTERN.search(content)
+
+    if not rev_match:
+        raise ValueError(f"{filepath.name}: 未找到 revision 定义")
+
+    revision = rev_match.group(1)
+
+    if not down_match:
+        raise ValueError(f"{filepath.name}: 未找到 down_revision 定义")
+
+    # down_match group(2) 是引号内的值，如果是 None 则 group(2) 为 None
+    down_revision = down_match.group(2)
+
+    return revision, down_revision
+
+
+def check_chain(versions_dir: Path) -> list[str]:
+    """检查 migration 链是否完整，返回错误列表。"""
+    errors: list[str] = []
+
+    if not versions_dir.is_dir():
+        return [f"目录不存在: {versions_dir}"]
+
+    py_files = sorted(versions_dir.glob("*.py"))
+    if not py_files:
+        return [f"目录下没有 migration 文件: {versions_dir}"]
+
+    # 收集所有 revision（用数字前缀做唯一标识）
+    revisions_by_num: dict[str, str] = {}  # 数字前缀 -> 完整 revision 名
+    revision_files: dict[str, str] = {}  # 数字前缀 -> 文件名
+    down_revisions: list[tuple[str, str | None]] = []  # (文件名, down_revision 数字前缀或None)
+
+    for f in py_files:
+        if f.name.startswith("__"):
+            continue
+        try:
+            rev, down = extract_migration_info(f)
+        except ValueError as e:
+            errors.append(str(e))
+            continue
+
+        rev_num = num_prefix(rev)
+
+        if rev_num in revisions_by_num:
+            errors.append(
+                f"编号重复: 编号 {rev_num} 同时出现在 "
+                f"{f.name} (revision={rev}) 和 {revision_files[rev_num]} (revision={revisions_by_num[rev_num]})"
+            )
+        else:
+            revisions_by_num[rev_num] = rev
+            revision_files[rev_num] = f.name
+
+        down_num = num_prefix(down) if down else None
+        down_revisions.append((f.name, down_num))
+
+    if errors:
+        return errors
+
+    # 检查每个 down_revision 是否存在
+    baselines = 0
+    for filename, down_num in down_revisions:
+        if down_num is None:
+            baselines += 1
+            continue
+
+        if down_num not in revisions_by_num:
+            errors.append(
+                f"断链: {filename} 的 down_revision 指向编号 '{down_num}'，但没有任何 migration 的 revision 是这个编号"
+            )
+
+    if baselines == 0:
+        errors.append("没有找到 baseline migration（down_revision = None 的文件）")
+    elif baselines > 1:
+        errors.append(f"发现 {baselines} 个 baseline migration，通常只能有 1 个")
+
+    # 额外检查：数字编号是否连续（只对能提取出数字的）
+    if revisions_by_num and not errors:
+        nums = sorted(int(n) for n in revisions_by_num if n.isdigit())
+        if nums:
+            expected = list(range(nums[0], nums[-1] + 1))
+            missing = [n for n in expected if n not in nums]
+            if missing:
+                missing_str = ", ".join(f"{n:03d}" for n in missing)
+                errors.append(f"编号不连续: 缺少编号 {missing_str}")
+
+    return errors
+
+
+def main() -> int:
+    if len(sys.argv) > 1:
+        versions_dir = Path(sys.argv[1])
+    else:
+        versions_dir = Path("alembic/versions")
+
+    print(f"检查 migration 编号连续性: {versions_dir}")
+    print()
+
+    errors = check_chain(versions_dir)
+
+    py_files = [f for f in versions_dir.glob("*.py") if not f.name.startswith("__")]
+
+    if errors:
+        print(f"❌ Migration 链有问题（共 {len(py_files)} 个文件，{len(errors)} 个错误）:")
+        for e in errors:
+            print(f"  - {e}")
+        print()
+        print("请修复后再提交。常见原因：")
+        print("  1. 新 migration 的 down_revision 编号写错了")
+        print("  2. 多个 PR 同时加 migration，编号冲突")
+        print("  3. 合并代码时漏了某个 migration 文件")
+        return 1
+
+    print(f"✅ Migration 链完整，共 {len(py_files)} 个版本")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/ci/ci_health_check.py

@@ -0,0 +1,298 @@
+#!/usr/bin/env python3
+"""
+CI 健康度快速检查脚本
+- 统计最近 N 条 run 的成功率（按 workflow 分类）
+- 列出失败的 run 和失败的 job/step
+- 区分基础设施问题 vs 业务代码问题
+- 输出简洁的健康度报告
+
+用法:
+  python3 scripts/ci/ci_health_check.py [--limit 20] [--workflow ci-pipeline.yml] [--json]
+
+环境变量:
+  GITEA_TOKEN   API token（必需）
+  GITEA_API_URL Gitea API 地址，默认 https://git.xiaoxiajianji.com/api/v1
+  GITEA_REPO    仓库，默认 xiaoxia/xiaoxia-saas
+"""
+
+import argparse
+import json
+import os
+import sys
+import urllib.request
+from datetime import datetime, timedelta, timezone
+
+# ---- 基础设施问题关键词（命中即判定为基础设施问题）----
+INFRA_KEYWORDS = [
+    # 网络/连接
+    "Couldn't connect to server",
+    "Connection refused",
+    "Connection reset",
+    "Connection timed out",
+    "Failed to connect to",
+    "network is unreachable",
+    "TLS handshake timeout",
+    "SSL certificate problem",
+    # 容器/Runner
+    "No such container",
+    "container already exists",
+    "docker: not found",
+    "no space left on device",
+    "out of memory",
+    "OOMKilled",
+    "pull access denied",
+    "manifest unknown",
+    "Error response from daemon",
+    "runner",
+    "runner is not online",
+    "no matching runners",
+    # Checkout/Git
+    "Could not resolve host",
+    "fatal: unable to access",
+    "The remote end hung up unexpectedly",
+    "early EOF",
+    "index-pack failed",
+    "git fetch",
+    "checkout failed",
+    "ETXTBSY",
+    "text file busy",
+    # 镜像/环境
+    "No module named pip",
+    "pip: not found",
+    "command not found: python",
+    "python3: not found",
+    "node: not found",
+    "npm: not found",
+    "exec format error",
+    "standard_init_linux.go",
+    # 系统/资源
+    "Input/output error",
+    "device or resource busy",
+    "No space left on device",
+    "Disk full",
+    # 鉴权/配置
+    "401 Unauthorized",
+    "403 Forbidden",
+    "404 Not Found",
+    "identity_sign: private key",
+    "Permission denied",
+]
+
+
+def api_get(path: str) -> dict:
+    base = os.environ.get("GITEA_API_URL", "https://git.xiaoxiajianji.com/api/v1")
+    repo = os.environ.get("GITEA_REPO", "xiaoxia/xiaoxia-saas")
+    token = os.environ.get("GITEA_TOKEN", "")
+    url = f"{base}/repos/{repo}/{path}"
+    req = urllib.request.Request(url, headers={"Authorization": f"token {token}"})
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return json.loads(resp.read().decode())
+
+
+def get_run_jobs(run_id: int) -> list:
+    return api_get(f"actions/runs/{run_id}/jobs").get("jobs", [])
+
+
+def get_job_log(job_id: int) -> str:
+    try:
+        return api_get(f"actions/jobs/{job_id}/logs")
+    except Exception:
+        return ""
+
+
+def classify_failure(job: dict) -> str:
+    """判断失败原因类型: infra / business / unknown"""
+    name = job.get("name", "")
+    # 仅根据 job 名称做初步分类（更精确需读日志，但代价高）
+    infra_jobs = ["Checkout", "Build", "Deploy", "Cleanup"]
+    business_jobs = [
+        "Unit Tests",
+        "Integration Tests",
+        "Frontend Lint",
+        "Frontend Unit Tests",
+        "Staging E2E",
+        "E2E",
+        "Validate Code Quality",
+    ]
+    name_lower = name.lower()
+    if (
+        any(k.lower() in name_lower for k in infra_jobs)
+        and "Test" not in name
+        and "Lint" not in name
+        and "Validate" not in name
+    ):
+        return "infra"
+    if any(k.lower() in name_lower for k in business_jobs):
+        return "business"
+    return "unknown"
+
+
+def analyze_with_log(job_id: int) -> str:
+    """通过日志关键词精确分类"""
+    log = get_job_log(job_id)
+    log_lower = log.lower()
+    for kw in INFRA_KEYWORDS:
+        if kw.lower() in log_lower:
+            return "infra"
+    return "business"
+
+
+def fmt_time(t: str) -> str:
+    if not t or t.startswith("1970"):
+        return "-"
+    try:
+        dt = datetime.fromisoformat(t.replace("Z", "+00:00"))
+        bj = dt.astimezone(timezone(timedelta(hours=8)))
+        return bj.strftime("%m-%d %H:%M")
+    except Exception:
+        return t[:16]
+
+
+def main():
+    parser = argparse.ArgumentParser(description="CI 健康度快速检查")
+    parser.add_argument("--limit", type=int, default=20, help="最近多少条 run")
+    parser.add_argument("--workflow", type=str, default="", help="只看某个 workflow")
+    parser.add_argument("--json", action="store_true", help="JSON 输出")
+    parser.add_argument("--deep", action="store_true", help="深度检查（读日志，较慢）")
+    args = parser.parse_args()
+
+    if not os.environ.get("GITEA_TOKEN"):
+        print("错误: 请设置 GITEA_TOKEN 环境变量", file=sys.stderr)
+        sys.exit(1)
+
+    # 1. 获取最近 run
+    runs = api_get(f"actions/runs?limit={args.limit}").get("workflow_runs", [])
+    if args.workflow:
+        runs = [r for r in runs if args.workflow in r.get("path", "")]
+
+    if not runs:
+        print("没有找到匹配的 run")
+        return
+
+    # 按 workflow 分组统计
+    wf_stats = {}
+    failed_runs = []
+
+    for r in runs:
+        path = r.get("path", "unknown")
+        # 提取 workflow 文件名，兼容各种 path 格式
+        if ".yml" in path or ".yaml" in path:
+            # ci-pipeline.yml@refs/heads/develop -> ci-pipeline.yml
+            wf = path.split("@")[0].split("/")[-1]
+        else:
+            wf = path.split("/")[-1] if "/" in path else path
+        if wf not in wf_stats:
+            wf_stats[wf] = {"total": 0, "success": 0, "failure": 0, "cancelled": 0, "others": 0}
+        wf_stats[wf]["total"] += 1
+        status = r.get("status", "")
+        conc = r.get("conclusion", "")
+        if status != "completed":
+            wf_stats[wf]["others"] += 1
+            continue
+        if conc == "success":
+            wf_stats[wf]["success"] += 1
+        elif conc == "failure":
+            wf_stats[wf]["failure"] += 1
+            failed_runs.append(r)
+        elif conc == "cancelled":
+            wf_stats[wf]["cancelled"] += 1
+        else:
+            wf_stats[wf]["others"] += 1
+
+    # 2. 失败 run 详情
+    failed_details = []
+    for r in failed_runs[:10]:  # 最多看10个失败的
+        jobs = get_run_jobs(r["id"])
+        failed_jobs = [j for j in jobs if j.get("conclusion") == "failure"]
+        job_infos = []
+        for j in failed_jobs:
+            cat = classify_failure(j)
+            if args.deep and cat == "unknown":
+                cat = analyze_with_log(j["id"])
+            # 找失败的 step
+            failed_steps = []
+            for step in j.get("steps", []):
+                if step.get("conclusion") == "failure":
+                    failed_steps.append(step.get("name", "?"))
+            job_infos.append(
+                {
+                    "name": j.get("name", ""),
+                    "category": cat,
+                    "failed_steps": failed_steps,
+                    "runner": j.get("runner_name", ""),
+                }
+            )
+        failed_details.append(
+            {
+                "id": r["id"],
+                "title": r.get("display_title", ""),
+                "branch": r.get("head_branch", ""),
+                "time": fmt_time(r.get("updated_at", "")),
+                "jobs": job_infos,
+            }
+        )
+
+    # 3. 输出
+    if args.json:
+        result = {"workflows": wf_stats, "failed_runs": failed_details}
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return
+
+    # 文本报告
+    print("=" * 60)
+    print("  CI 健康度报告")
+    print("=" * 60)
+    print(f"统计范围: 最近 {len(runs)} 条 run")
+    print(f"时间: {datetime.now(timezone(timedelta(hours=8))).strftime('%Y-%m-%d %H:%M:%S')}")
+    print()
+
+    print("📊 各 Workflow 成功率:")
+    print("-" * 60)
+    for wf, s in sorted(wf_stats.items()):
+        total = s["total"]
+        succ = s["success"]
+        rate = (succ / total * 100) if total > 0 else 0
+        bar = "█" * int(rate / 5) + "░" * (20 - int(rate / 5))
+        icon = "🟢" if rate >= 90 else ("🟡" if rate >= 70 else "🔴")
+        print(f"  {icon} {wf:35s} {rate:5.1f}%  {bar}  ({succ}/{total})")
+        if s["failure"]:
+            print(f"      失败: {s['failure']}  取消: {s['cancelled']}  进行中: {s['others']}")
+
+    if failed_details:
+        print()
+        print("❌ 失败详情:")
+        print("-" * 60)
+        for d in failed_details:
+            print(f"  #{d['id']} [{d['time']}] {d['title'][:45]}")
+            print(f"      分支: {d['branch']}")
+            for j in d["jobs"]:
+                cat_icon = "🏗️" if j["category"] == "infra" else ("🐛" if j["category"] == "business" else "❓")
+                steps = ", ".join(j["failed_steps"][:3]) if j["failed_steps"] else "未知"
+                print(f"      {cat_icon} {j['name'][:30]:30s} 失败步骤: {steps}")
+                if j["runner"]:
+                    print(f"          runner: {j['runner']}")
+    else:
+        print()
+        print("✅ 最近没有失败的 run")
+
+    # 总结
+    total_all = sum(s["total"] for s in wf_stats.values())
+    succ_all = sum(s["success"] for s in wf_stats.values())
+    fail_all = sum(s["failure"] for s in wf_stats.values())
+    infra_fail = sum(1 for d in failed_details for j in d["jobs"] if j["category"] == "infra")
+    biz_fail = sum(1 for d in failed_details for j in d["jobs"] if j["category"] == "business")
+    rate_all = (succ_all / total_all * 100) if total_all > 0 else 0
+    print()
+    print("=" * 60)
+    print(f"  总结: 总成功率 {rate_all:.1f}% ({succ_all}/{total_all})")
+    if fail_all > 0:
+        print(f"  失败job分类: 基础设施 {infra_fail} 个 | 业务代码 {biz_fail} 个")
+        if infra_fail > biz_fail:
+            print("  ⚠️ 主要是基础设施问题，建议优先排查 CI 环境")
+        else:
+            print("  💡 主要是业务代码问题，建议关注业务侧修复")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

scripts/ci/ci_health_report.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""
+CI健康度每日巡检报告脚本
+- 调用ci_health_check.py获取数据
+- 有失败时生成飞书卡片通知并发送
+- 无失败时静默退出（不打扰）
+- 用于每日定时巡检
+
+用法:
+  python3 scripts/ci/ci_health_report.py [--limit 30] [--dry-run]
+
+环境变量:
+  GITEA_TOKEN         API token（必需）
+  CI_NOTIFY_WEBHOOK   飞书webhook地址（必需，用于发报告）
+  GITEA_API_URL       Gitea API 地址
+  GITEA_REPO          仓库
+"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import urllib.request
+from datetime import datetime, timedelta, timezone
+
+
+def run_health_check(limit: int) -> dict:
+    """调用ci_health_check.py获取JSON结果"""
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    cmd = [
+        sys.executable,
+        os.path.join(script_dir, "ci_health_check.py"),
+        "--json",
+        "--limit",
+        str(limit),
+    ]
+    env = os.environ.copy()
+    # 确保GITEA_TOKEN传递
+    if not env.get("GITEA_TOKEN") and env.get("GITHUB_TOKEN"):
+        env["GITEA_TOKEN"] = env["GITHUB_TOKEN"]
+
+    result = subprocess.run(cmd, capture_output=True, text=True, env=env)
+    if result.returncode != 0:
+        print(f"health check failed: {result.stderr}")
+        return {"workflows": {}, "failed_runs": []}
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError:
+        print(f"failed to parse health check output: {result.stdout[:200]}")
+        return {"workflows": {}, "failed_runs": []}
+
+
+def build_feishu_card(data: dict) -> dict:
+    """构建飞书卡片消息"""
+    wf_stats = data.get("workflows", {})
+    failed_runs = data.get("failed_runs", [])
+
+    # 统计数据
+    total_all = sum(s["total"] for s in wf_stats.values())
+    succ_all = sum(s["success"] for s in wf_stats.values())
+    fail_all = sum(s["failure"] for s in wf_stats.values())
+    rate_all = (succ_all / total_all * 100) if total_all > 0 else 0
+
+    # 失败分类
+    infra_fail = 0
+    biz_fail = 0
+    unknown_fail = 0
+    for run in failed_runs:
+        for job in run.get("jobs", []):
+            cat = job.get("category", "unknown")
+            if cat == "infra":
+                infra_fail += 1
+            elif cat == "business":
+                biz_fail += 1
+            else:
+                unknown_fail += 1
+
+    now = datetime.now(timezone(timedelta(hours=8))).strftime("%Y-%m-%d %H:%M")
+
+    # 各workflow成功率行
+    wf_lines = []
+    for wf, s in sorted(wf_stats.items()):
+        total = s["total"]
+        succ = s["success"]
+        fail = s["failure"]
+        rate = (succ / total * 100) if total > 0 else 0
+        icon = "🟢" if rate >= 90 else ("🟡" if rate >= 70 else "🔴")
+        wf_name = (
+            wf.replace("ci-pipeline.yml", "CI Pipeline")
+            .replace("code-review.yml", "Code Review")
+            .replace("daily-check.yml", "Daily Check")
+            .replace("preview-deploy.yml", "Preview Deploy")
+        )
+        wf_lines.append(f"{icon} **{wf_name}**: {rate:.0f}% ({succ}/{total}，失败{fail})")
+
+    # 失败详情（最多显示5条）
+    fail_detail_lines = []
+    for i, run in enumerate(failed_runs[:5]):
+        run_id = run["id"]
+        title = run.get("title", "")[:35]
+        branch = run.get("branch", "")
+        jobs_str = ", ".join(j["name"][:15] for j in run.get("jobs", [])[:3])
+        fail_detail_lines.append(f"• **#{run_id}** {title}\n   分支: {branch} | 失败: {jobs_str}")
+
+    if len(failed_runs) > 5:
+        fail_detail_lines.append(f"... 还有 {len(failed_runs) - 5} 条失败记录")
+
+    # 整体状态
+    if fail_all == 0:
+        status_text = "✅ 全部通过"
+        status_color = "green"
+    elif infra_fail > biz_fail:
+        status_text = "⚠️ 基础设施问题为主"
+        status_color = "yellow"
+    else:
+        status_text = "🔴 存在业务失败"
+        status_color = "red"
+
+    card = {
+        "config": {"wide_screen_mode": True},
+        "header": {
+            "title": {"tag": "plain_text", "content": f"CI告警 - 每日健康度巡检 ({now})"},
+            "template": status_color,
+        },
+        "elements": [
+            {
+                "tag": "div",
+                "text": {
+                    "tag": "lark_md",
+                    "content": f"**统计范围**: 最近 {total_all} 条 run\n**整体状态**: {status_text}\n**总成功率**: {rate_all:.1f}% ({succ_all}/{total_all})",
+                },
+            },
+            {"tag": "hr"},
+            {
+                "tag": "div",
+                "text": {
+                    "tag": "lark_md",
+                    "content": "**📊 各Workflow成功率**\n" + "\n".join(wf_lines) if wf_lines else "暂无数据",
+                },
+            },
+        ],
+    }
+
+    # 失败分类统计
+    if fail_all > 0:
+        card["elements"].append({"tag": "hr"})
+        card["elements"].append(
+            {
+                "tag": "div",
+                "text": {
+                    "tag": "lark_md",
+                    "content": f"**失败原因分类**\n🏗️ 基础设施: {infra_fail} 个\n🐛 业务代码: {biz_fail} 个\n❓ 待确认: {unknown_fail} 个",
+                },
+            }
+        )
+
+    # 失败详情
+    if fail_detail_lines:
+        card["elements"].append({"tag": "hr"})
+        card["elements"].append(
+            {
+                "tag": "div",
+                "text": {
+                    "tag": "lark_md",
+                    "content": "**❌ 失败详情**\n" + "\n\n".join(fail_detail_lines),
+                },
+            }
+        )
+
+    # 查看更多
+    card["elements"].append({"tag": "hr"})
+    base_url = os.environ.get("GITEA_BASE_URL", "https://git.xiaoxiajianji.com")
+    repo = os.environ.get("GITEA_REPO", "xiaoxia/xiaoxia-saas")
+    card["elements"].append(
+        {
+            "tag": "action",
+            "actions": [
+                {
+                    "tag": "button",
+                    "text": {"tag": "plain_text", "content": "查看CI面板"},
+                    "type": "primary",
+                    "url": f"{base_url}/{repo}/actions",
+                }
+            ],
+        }
+    )
+
+    return {"msg_type": "interactive", "card": card}
+
+
+def send_feishu(webhook: str, payload: dict) -> bool:
+    """发送飞书webhook"""
+    data = json.dumps(payload).encode()
+    req = urllib.request.Request(
+        webhook,
+        data=data,
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            result = json.loads(resp.read().decode())
+            return result.get("code", -1) == 0 or result.get("StatusCode", -1) == 0
+    except Exception as e:
+        print(f"send feishu failed: {e}")
+        return False
+
+
+def main():
+    parser = argparse.ArgumentParser(description="CI健康度每日巡检报告")
+    parser.add_argument("--limit", type=int, default=30, help="统计最近N条run")
+    parser.add_argument("--dry-run", action="store_true", help="只打印不发送")
+    parser.add_argument("--always-notify", action="store_true", help="即使全部通过也发送通知")
+    args = parser.parse_args()
+
+    webhook = os.environ.get("CI_NOTIFY_WEBHOOK", "")
+    if not webhook and not args.dry_run:
+        print("未配置 CI_NOTIFY_WEBHOOK，跳过通知")
+        # 还是执行健康检查输出到日志，方便排查
+        data = run_health_check(args.limit)
+        print(f"health check done: {len(data.get('failed_runs', []))} failed")
+        return 0
+
+    # 执行健康检查
+    data = run_health_check(args.limit)
+    failed_count = len(data.get("failed_runs", []))
+
+    # 无失败且不强制通知 → 静默退出
+    if failed_count == 0 and not args.always_notify:
+        print("✅ 全部通过，静默退出")
+        return 0
+
+    # 构建并发送卡片
+    card = build_feishu_card(data)
+
+    if args.dry_run:
+        print(json.dumps(card, ensure_ascii=False, indent=2))
+        return 0
+
+    success = send_feishu(webhook, card)
+    if success:
+        print(f"📤 已发送健康度报告，失败 {failed_count} 条")
+    else:
+        print("❌ 发送飞书通知失败")
+
+    # 通知失败不阻断流程
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/ci/docker_build_only.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# PR构建专用：只构建不推送，只读缓存不写，用于PR阶段验证Dockerfile
+set -eu
+
+NO_CACHE_FLAG=""
+if [ "$1" = "--no-cache" ]; then
+  NO_CACHE_FLAG="--no-cache"
+  shift
+fi
+
+DOCKERFILE="$1"
+IMAGE_TAG="$2"
+CACHE_REF="$3"
+shift 3
+BUILD_ARGS=""
+for arg in "$@"; do
+  BUILD_ARGS="$BUILD_ARGS --build-arg $arg"
+done
+
+BUILDER_NAME="ci-pr-builder-${GITHUB_RUN_ID:-local}"
+if ! docker buildx inspect "$BUILDER_NAME" > /dev/null 2>&1; then
+  docker buildx create --use --name "$BUILDER_NAME" --driver docker-container
+else
+  docker buildx use "$BUILDER_NAME"
+fi
+docker buildx inspect --bootstrap
+
+CACHE_NAME=$(echo "$CACHE_REF" | tr "/" "_" | tr ":" "-")
+LOCAL_CACHE_DIR="/tmp/buildx-cache/${CACHE_NAME}"
+mkdir -p "$LOCAL_CACHE_DIR"
+
+echo "=== PR Build: build only, no push, read-only cache ==="
+echo "Dockerfile: ${DOCKERFILE}"
+echo "Image tag: ${IMAGE_TAG}"
+echo ""
+
+build_with_retry() {
+  local attempt=1
+  local max_attempts=2
+  while [ $attempt -le $max_attempts ]; do
+    local build_output
+    local exit_code
+    set +e
+    build_output=$(docker buildx build \
+      $NO_CACHE_FLAG \
+      $BUILD_ARGS \
+      --cache-from "type=local,src=${LOCAL_CACHE_DIR}" \
+      --cache-from "type=registry,ref=${CACHE_REF}" \
+      -f "${DOCKERFILE}" \
+      -t "${IMAGE_TAG}" \
+      --load \
+      . 2>&1)
+    exit_code=$?
+    set -e
+    if [ $exit_code -eq 0 ]; then
+      echo "$build_output"
+      return 0
+    fi
+    if echo "$build_output" | grep -qE "parent snapshot.*not found|snapshot.*does not exist|cache.*corrupt|failed to compute cache key"; then
+      echo "$build_output"
+      echo "Local cache corrupted, cleaning and retrying ($attempt/$max_attempts)..."
+      rm -rf "${LOCAL_CACHE_DIR}"
+      mkdir -p "${LOCAL_CACHE_DIR}"
+      docker buildx prune -f -a >/dev/null 2>&1 || true
+      attempt=$((attempt + 1))
+    else
+      echo "$build_output"
+      return $exit_code
+    fi
+  done
+  echo "Local cache failed, building with registry cache only..."
+  docker buildx build \
+    $NO_CACHE_FLAG \
+    $BUILD_ARGS \
+    --cache-from "type=registry,ref=${CACHE_REF}" \
+    -f "${DOCKERFILE}" \
+    -t "${IMAGE_TAG}" \
+    --load \
+    .
+}
+
+build_with_retry
+echo ""
+echo "PR build OK (not pushed): ${IMAGE_TAG}"

scripts/ci/docker_build_push.sh

@@ -1,6 +1,5 @@
 #!/bin/bash
-# 通用Docker镜像构建+推送脚本（local cache为主 + registry cache兜底）
-# M-2优化：解决registry缓存导入慢(247s)和推送不稳定问题
+# 通用Docker镜像构建+推送脚本（local cache为主 + registry cache共享）
 # 用法: docker_build_push.sh [--no-cache] <Dockerfile> <image_tag> <cache_ref> [build_arg...]
 set -eu
 
@@ -35,7 +34,7 @@ LOCAL_CACHE_DIR="/tmp/buildx-cache/${CACHE_NAME}"
 
 mkdir -p "$LOCAL_CACHE_DIR"
 
-# 缓存源：local优先（带自动修复），registry兜底
+# 缓存源：local优先（带自动修复），registry兜底读写
 # 本地缓存损坏时自动清理后重试，避免snapshot not found导致构建全挂
 build_with_cache_retry() {
   local attempt=1
@@ -48,8 +47,9 @@ build_with_cache_retry() {
       $NO_CACHE_FLAG \
       $BUILD_ARGS \
       --cache-from "type=local,src=${LOCAL_CACHE_DIR}" \
-      --cache-from "type=registry,ref=${CACHE_REF},ignore-error=true" \
+      --cache-from "type=registry,ref=${CACHE_REF}" \
       --cache-to "type=local,dest=${LOCAL_CACHE_DIR},mode=max" \
+      --cache-to "type=registry,ref=${CACHE_REF},mode=max,ignore-error=true" \
       -f "${DOCKERFILE}" \
       -t "${IMAGE_TAG}" \
       --push \
@@ -81,15 +81,16 @@ build_with_cache_retry() {
   docker buildx build \
     $NO_CACHE_FLAG \
     $BUILD_ARGS \
-    --cache-from "type=registry,ref=${CACHE_REF},ignore-error=true" \
+    --cache-from "type=registry,ref=${CACHE_REF}" \
     --cache-to "type=local,dest=${LOCAL_CACHE_DIR},mode=max" \
+    --cache-to "type=registry,ref=${CACHE_REF},mode=max,ignore-error=true" \
     -f "${DOCKERFILE}" \
     -t "${IMAGE_TAG}" \
     --push \
     .
 }
 
-echo "=== Step 1: Build & push image (local cache + registry read, with auto-repair) ==="
+echo "=== Step 1: Build & push image (local cache + registry cache, with auto-repair) ==="
 echo "Local cache: ${LOCAL_CACHE_DIR}"
 echo "Registry cache: ${CACHE_REF}"
 echo ""
@@ -99,6 +100,7 @@ build_with_cache_retry
 echo ""
 echo "Image pushed: ${IMAGE_TAG}"
 echo "Local cache updated"
+echo "Registry cache updated (if supported)"
 
 echo ""
 echo "Build completed: ${IMAGE_TAG}"

scripts/ci/step_frontend_install.sh

@@ -1,24 +1,25 @@
 #!/bin/sh
 # CI 公共步骤：前端依赖安装（在 docker node 容器中运行）
-# 用法：step_frontend_install.sh [模式]
-#   模式: full (默认) - 完整安装所有依赖
-#        vitest       - 同full（保持接口兼容）
+# 优化：增加国内npm镜像源，加重试间隔
 set -eu
 
 MODE="${1:-full}"
 
 echo "=== 前端依赖安装开始 (模式: $MODE) ==="
 
-# npm ci 带重试（网络不稳定时自动重试）
+# npm国内镜像源（加速下载，减少网络失败）
+NPM_REGISTRY="https://registry.npmmirror.com"
+
 for i in 1 2 3; do
+  echo "npm ci 尝试 $i/3 (镜像: $NPM_REGISTRY)"
   docker run --rm \
     -v "$PWD:/workspace" \
     -w /workspace/apps/web \
     docker.m.daocloud.io/library/node:20 \
-    sh -lc "npm ci --no-audit --no-fund" && break
+    sh -lc "npm config set registry $NPM_REGISTRY && npm ci --no-audit --no-fund" && break
   echo "npm ci 失败，重试 $i/3..."
   [ $i -eq 3 ] && exit 1
-  sleep 5
+  sleep 10
 done
 
 echo "=== 前端依赖安装完成 ==="

tests/unit/test_classification_domain.py

@@ -0,0 +1,139 @@
+"""classification 模块单元测试."""
+
+import pytest
+from domain.classification import (
+    AssetClassification,
+    AssetLibraryKind,
+    ClassificationJob,
+    ClassificationJobStatus,
+    IngestJobStatus,
+)
+
+
+class TestAssetLibraryKind:
+    """AssetLibraryKind 枚举测试."""
+
+    def test_values(self):
+        assert AssetLibraryKind.VIDEO == "video"
+        assert AssetLibraryKind.VOICE == "voice"
+
+
+class TestIngestJobStatus:
+    """IngestJobStatus 枚举测试."""
+
+    def test_values(self):
+        assert IngestJobStatus.PENDING == "pending"
+        assert IngestJobStatus.PROCESSING == "processing"
+        assert IngestJobStatus.COMPLETED == "completed"
+        assert IngestJobStatus.FAILED == "failed"
+
+
+class TestClassificationJobStatus:
+    """ClassificationJobStatus 枚举测试."""
+
+    def test_values(self):
+        assert ClassificationJobStatus.PENDING == "pending"
+        assert ClassificationJobStatus.PROCESSING == "processing"
+        assert ClassificationJobStatus.COMPLETED == "completed"
+        assert ClassificationJobStatus.FAILED == "failed"
+
+
+class TestAssetClassification:
+    """AssetClassification 枚举测试."""
+
+    def test_values(self):
+        assert AssetClassification.SCENIC == "scenic"
+        assert AssetClassification.PRODUCT == "product"
+        assert AssetClassification.PERSON == "person"
+        assert AssetClassification.ANIMAL == "animal"
+        assert AssetClassification.FOOD == "food"
+        assert AssetClassification.TECH == "tech"
+        assert AssetClassification.SPORT == "sport"
+        assert AssetClassification.MUSIC == "music"
+        assert AssetClassification.OTHER == "other"
+
+
+class TestClassificationJobCreate:
+    """ClassificationJob.create 工厂方法测试."""
+
+    def test_create_with_valid_params(self):
+        job = ClassificationJob.create(project_id="proj_001", asset_id="asset_001")
+        assert job.id
+        assert len(job.id) == 32
+        assert job.project_id == "proj_001"
+        assert job.asset_id == "asset_001"
+        assert job.status == ClassificationJobStatus.PENDING
+        assert job.classification == ""
+        assert job.confidence == 0.0
+        assert job.error_message == ""
+        assert job.created_at is not None
+        assert job.updated_at is not None
+
+    def test_create_strips_strings(self):
+        job = ClassificationJob.create(
+            project_id="  proj_002  ",
+            asset_id="  asset_002  ",
+        )
+        assert job.project_id == "proj_002"
+        assert job.asset_id == "asset_002"
+
+    def test_create_empty_project_id_raises(self):
+        with pytest.raises(ValueError, match="project_id"):
+            ClassificationJob.create(project_id="", asset_id="a")
+
+    def test_create_whitespace_project_id_raises(self):
+        with pytest.raises(ValueError, match="project_id"):
+            ClassificationJob.create(project_id="   ", asset_id="a")
+
+    def test_create_empty_asset_id_raises(self):
+        with pytest.raises(ValueError, match="asset_id"):
+            ClassificationJob.create(project_id="p", asset_id="")
+
+    def test_create_whitespace_asset_id_raises(self):
+        with pytest.raises(ValueError, match="asset_id"):
+            ClassificationJob.create(project_id="p", asset_id="   ")
+
+    def test_create_ids_are_unique(self):
+        j1 = ClassificationJob.create(project_id="p", asset_id="a")
+        j2 = ClassificationJob.create(project_id="p", asset_id="b")
+        assert j1.id != j2.id
+
+    def test_create_timestamps_are_utc(self):
+        job = ClassificationJob.create(project_id="p", asset_id="a")
+        assert job.created_at.tzinfo is not None
+        assert job.updated_at.tzinfo is not None
+
+
+class TestClassificationJobState:
+    """ClassificationJob 状态操作测试"""
+
+    def test_set_processing(self):
+        job = ClassificationJob.create(project_id="proj-1", asset_id="asset-1")
+        job.status = ClassificationJobStatus.PROCESSING
+        assert job.status == ClassificationJobStatus.PROCESSING
+
+    def test_set_completed_with_result(self):
+        job = ClassificationJob.create(project_id="proj-1", asset_id="asset-1")
+        job.status = ClassificationJobStatus.COMPLETED
+        job.classification = AssetClassification.SCENIC
+        job.confidence = 0.95
+        assert job.status == ClassificationJobStatus.COMPLETED
+        assert job.classification == "scenic"
+        assert job.confidence == pytest.approx(0.95)
+
+    def test_set_failed_with_error(self):
+        job = ClassificationJob.create(project_id="proj-1", asset_id="asset-1")
+        job.status = ClassificationJobStatus.FAILED
+        job.error_message = "model timeout"
+        assert job.status == ClassificationJobStatus.FAILED
+        assert job.error_message == "model timeout"
+
+    def test_confidence_range_zero(self):
+        job = ClassificationJob.create(project_id="proj-1", asset_id="asset-1")
+        job.confidence = 0.0
+        assert job.confidence == 0.0
+
+    def test_confidence_range_one(self):
+        job = ClassificationJob.create(project_id="proj-1", asset_id="asset-1")
+        job.confidence = 1.0
+        assert job.confidence == 1.0

tests/unit/test_config_schemas_and_ai_endpoints.py

@@ -4,11 +4,6 @@
 - config_schemas: normalize_plan_config / normalize_template_config 默认值填充、部分覆盖、非标准字段保留
 - config_schemas: Pydantic 枚举校验（CoverType / TextPosition / BGMSource）
 - ai_tasks: run_ai_recommend / run_generate_cover stub 返回结构
-- edit_plans API: POST /{plan_id}/ai-recommend 正常/404/400
-- edit_plans API: POST /{plan_id}/generate-cover 正常/404
-- edit_plans API: create_plan config 标准化
-- edit_plans API: update_plan config 标准化
-- edit_templates API: create_template / update_template config 标准化
 """
 
 from __future__ import annotations
@@ -17,7 +12,6 @@ import os
 import sys
 from pathlib import Path
 from typing import Any
-from unittest.mock import MagicMock
 
 os.environ.setdefault("JWT_SECRET_KEY", "unit-test-secret-key-for-testing")
 os.environ.setdefault("DATABASE_URL", "sqlite:///test.db")
@@ -271,270 +265,3 @@ class TestAIRunTasks:
             cover_type="upload",
         )
         assert result["type"] == "upload"
-
-
-# ---------------------------------------------------------------------------
-# API 端点测试 — AI 推荐 & 封面生成
-# ---------------------------------------------------------------------------
-
-
-class StubEditPlanRepository:
-    """内存中的 EditPlan 仓储 stub（支持 clips）"""
-
-    def __init__(self):
-        self._plans: dict[str, Any] = {}
-        self._clips: dict[str, list] = {}  # plan_id → [clip]
-        self._counter = 0
-
-    def _next_id(self) -> str:
-        self._counter += 1
-        return f"plan-{self._counter:03d}"
-
-    def get(self, plan_id: str):
-        return self._plans.get(plan_id)
-
-    def create(self, plan):
-        self._plans[plan.id] = plan
-        return plan
-
-    def update(self, plan):
-        if plan.id not in self._plans:
-            raise ValueError(f"EditPlan {plan.id} not found")
-        self._plans[plan.id] = plan
-        return plan
-
-    def delete(self, plan_id: str):
-        if plan_id not in self._plans:
-            return False
-        del self._plans[plan_id]
-        return True
-
-    def list_all(self, *, status=None, skip=0, limit=50):
-        items = list(self._plans.values())
-        if status:
-            items = [p for p in items if p.status == status]
-        return items[skip : skip + limit]
-
-    def count(self, *, template_id=None, status=None):
-        return len(list(self._plans.values()))
-
-    def delete_by_plan(self, plan_id: str):
-        self._clips.pop(plan_id, None)
-
-
-def _make_auth_user():
-    from app.auth import AuthenticatedUser
-
-    from packages.domain.entities import User
-
-    user = User(id="user-001", email="test@example.com", display_name="测试用户")
-    return AuthenticatedUser(user=user)
-
-
-def _create_ai_test_app():
-    """创建带 stub 注入的测试 FastAPI 应用（支持 AI 端点）"""
-    import app.services.edit_plan_service as service_module
-    from app.api.routes import edit_plans as edit_plans_module
-    from app.api.routes.edit_plans import router
-
-    stub_repo = StubEditPlanRepository()
-
-    # Mock service methods that interact with DB
-    original_plan_repo = service_module.SQLAlchemyEditPlanRepository
-    original_clip_repo = service_module.SQLAlchemyEditPlanClipRepository
-    original_gen_repo = service_module.SQLAlchemyGenerationTaskRepository
-
-    service_module.SQLAlchemyEditPlanRepository = lambda db: stub_repo
-    service_module.SQLAlchemyEditPlanClipRepository = lambda db: stub_repo
-    service_module.SQLAlchemyGenerationTaskRepository = lambda db: stub_repo
-
-    app = FastAPI()
-    app.include_router(router, prefix="/api/v1/edit-plans")
-    app.dependency_overrides[edit_plans_module.get_current_user] = _make_auth_user
-    app.dependency_overrides[edit_plans_module.get_db_session] = lambda: MagicMock()
-
-    def cleanup():
-        service_module.SQLAlchemyEditPlanRepository = original_plan_repo
-        service_module.SQLAlchemyEditPlanClipRepository = original_clip_repo
-        service_module.SQLAlchemyGenerationTaskRepository = original_gen_repo
-
-    return app, stub_repo, cleanup
-
-
-from fastapi import FastAPI
-from fastapi.testclient import TestClient
-
-from packages.domain.edit_plan import EditPlan
-
-
-@pytest.fixture
-def ai_client():
-    app, stub_repo, cleanup = _create_ai_test_app()
-    yield TestClient(app), stub_repo
-    cleanup()
-
-
-class TestAIRecommendEndpoint:
-    def test_ai_recommend_success(self, ai_client):
-        c, repo = ai_client
-        plan = EditPlan.create("tpl-001", "测试计划")
-        repo.create(plan)
-
-        resp = c.post(
-            f"/api/v1/edit-plans/{plan.id}/ai-recommend",
-            json={"asset_ids": ["asset-1", "asset-2"]},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["plan_id"] == plan.id
-        assert "clips" in data
-        assert len(data["clips"]) >= 2
-        assert "config" in data
-        assert data["total_duration"] > 0
-        assert "confidence" in data
-
-    def test_ai_recommend_not_found(self, ai_client):
-        c, repo = ai_client
-        resp = c.post(
-            "/api/v1/edit-plans/nonexistent/ai-recommend",
-            json={"asset_ids": ["asset-1"]},
-        )
-        assert resp.status_code == 404
-
-    def test_ai_recommend_rejects_rendering_status(self, ai_client):
-        c, repo = ai_client
-        plan = EditPlan.create("tpl-001", "渲染中计划")
-        plan.start_editing()
-        plan.start_rendering()
-        repo.create(plan)
-
-        resp = c.post(
-            f"/api/v1/edit-plans/{plan.id}/ai-recommend",
-            json={"asset_ids": ["asset-1"]},
-        )
-        assert resp.status_code == 400
-        assert "当前计划状态" in resp.json()["detail"] or "编辑计划" in resp.json()["detail"]
-
-    def test_ai_recommend_with_custom_params(self, ai_client):
-        c, repo = ai_client
-        plan = EditPlan.create("tpl-001", "自定义参数计划")
-        repo.create(plan)
-
-        resp = c.post(
-            f"/api/v1/edit-plans/{plan.id}/ai-recommend",
-            json={
-                "asset_ids": ["asset-1"],
-                "editing_mode": "pip",
-                "target_duration": 15.0,
-            },
-        )
-        assert resp.status_code == 200
-
-    def test_ai_recommend_invalid_duration(self, ai_client):
-        c, repo = ai_client
-        plan = EditPlan.create("tpl-001", "测试计划")
-        repo.create(plan)
-
-        resp = c.post(
-            f"/api/v1/edit-plans/{plan.id}/ai-recommend",
-            json={"asset_ids": ["asset-1"], "target_duration": -5.0},
-        )
-        assert resp.status_code == 422
-
-
-class TestGenerateCoverEndpoint:
-    def test_generate_cover_ai_frame(self, ai_client):
-        c, repo = ai_client
-        plan = EditPlan.create("tpl-001", "封面测试计划")
-        repo.create(plan)
-
-        resp = c.post(
-            f"/api/v1/edit-plans/{plan.id}/generate-cover",
-            json={"asset_ids": ["asset-1"], "cover_type": "ai_frame"},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["plan_id"] == plan.id
-        assert "cover" in data
-        assert data["cover"]["type"] == "ai_frame"
-
-    def test_generate_cover_manual(self, ai_client):
-        c, repo = ai_client
-        plan = EditPlan.create("tpl-001", "手动封面计划")
-        repo.create(plan)
-
-        resp = c.post(
-            f"/api/v1/edit-plans/{plan.id}/generate-cover",
-            json={"asset_ids": ["asset-1"], "cover_type": "manual", "frame_time": 3.5},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["cover"]["type"] == "manual"
-        assert data["cover"]["frame_time"] == 3.5
-
-    def test_generate_cover_not_found(self, ai_client):
-        c, repo = ai_client
-        resp = c.post(
-            "/api/v1/edit-plans/nonexistent/generate-cover",
-            json={"asset_ids": []},
-        )
-        assert resp.status_code == 404
-
-    def test_generate_cover_default_type(self, ai_client):
-        c, repo = ai_client
-        plan = EditPlan.create("tpl-001", "默认封面计划")
-        repo.create(plan)
-
-        # 不传 cover_type，默认 ai_frame
-        resp = c.post(
-            f"/api/v1/edit-plans/{plan.id}/generate-cover",
-            json={"asset_ids": ["asset-1"]},
-        )
-        assert resp.status_code == 200
-        assert resp.json()["cover"]["type"] == "ai_frame"
-
-
-# ---------------------------------------------------------------------------
-# Config 标准化集成测试（create/update plan & template）
-# ---------------------------------------------------------------------------
-
-
-class TestConfigNormalizationInAPI:
-    """验证 create/update 端点自动标准化 config"""
-
-    def test_create_plan_normalizes_config(self, ai_client):
-        c, repo = ai_client
-        resp = c.post(
-            "/api/v1/edit-plans",
-            json={
-                "template_id": "tpl-001",
-                "name": "标准化测试",
-                "config": {"title": {"text": "自定义标题"}},
-            },
-        )
-        assert resp.status_code == 201
-        config = resp.json()["config"]
-        # 传入的 title.text 被保留
-        assert config["title"]["text"] == "自定义标题"
-        # 未传入的 title 字段填充默认值
-        assert config["title"]["font"] == "思源黑体"
-        # cover/bgm/subtitle 全部填充默认值
-        assert config["cover"]["type"] == "ai_frame"
-        assert config["bgm"]["volume"] == 0.3
-        assert config["subtitle"]["position"] == "bottom"
-
-    def test_update_plan_normalizes_config(self, ai_client):
-        c, repo = ai_client
-        plan = EditPlan.create("tpl-001", "更新标准化测试")
-        repo.create(plan)
-
-        resp = c.put(
-            f"/api/v1/edit-plans/{plan.id}",
-            json={"config": {"bgm": {"volume": 0.9}}},
-        )
-        assert resp.status_code == 200
-        config = resp.json()["config"]
-        assert config["bgm"]["volume"] == 0.9
-        assert config["bgm"]["source"] == "library"
-        assert config["cover"]["type"] == "ai_frame"
-        assert config["title"]["enabled"] is True

tests/unit/test_cover_service.py

@@ -0,0 +1,400 @@
+"""
+封面管理服务单元测试
+"""
+
+import subprocess
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+import pytest
+
+from apps.api.app.services.cover_service import (
+    COVER_STORAGE_PREFIX,
+    DEFAULT_COVER_HEIGHT,
+    DEFAULT_COVER_QUALITY,
+    DEFAULT_COVER_WIDTH,
+    CoverService,
+)
+
+
+class TestGetCoverConfig:
+    """get_cover_config 静态方法测试"""
+
+    def test_get_cover_config_default(self):
+        """测试默认封面配置"""
+        config = {}
+        result = CoverService.get_cover_config(config)
+        assert result["type"] == "ai_frame"
+        assert result["image_url"] == ""
+        assert result["frame_time"] is None
+
+    def test_get_cover_config_with_custom_values(self):
+        """测试自定义封面配置"""
+        config = {
+            "cover": {
+                "type": "manual",
+                "image_url": "https://example.com/cover.jpg",
+                "frame_time": 5.5,
+            }
+        }
+        result = CoverService.get_cover_config(config)
+        assert result["type"] == "manual"
+        assert result["image_url"] == "https://example.com/cover.jpg"
+        assert result["frame_time"] == 5.5
+
+    def test_get_cover_config_cover_not_dict(self):
+        """测试 cover 不是 dict 时返回默认值"""
+        config = {"cover": "not-a-dict"}
+        result = CoverService.get_cover_config(config)
+        assert result["type"] == "ai_frame"
+        assert result["image_url"] == ""
+        assert result["frame_time"] is None
+
+    def test_get_cover_config_partial_fields(self):
+        """测试部分字段存在时，其余字段用默认值"""
+        config = {"cover": {"type": "custom"}}
+        result = CoverService.get_cover_config(config)
+        assert result["type"] == "custom"
+        assert result["image_url"] == ""
+        assert result["frame_time"] is None
+
+    def test_get_cover_config_empty_cover_dict(self):
+        """测试空的 cover dict"""
+        config = {"cover": {}}
+        result = CoverService.get_cover_config(config)
+        assert result["type"] == "ai_frame"
+        assert result["image_url"] == ""
+
+
+class TestExtractCoverFromClip:
+    """extract_cover_from_clip 测试"""
+
+    @pytest.fixture
+    def mock_storage(self):
+        storage = Mock()
+        storage.download_file = Mock()
+        storage.upload_file = Mock()
+        storage.get_url = Mock(return_value="https://oss.example.com/covers/plan1/cover_1000.jpg")
+        return storage
+
+    @pytest.fixture
+    def mock_asset_repo(self):
+        repo = Mock()
+        repo.get = Mock(return_value=None)
+        return repo
+
+    @pytest.fixture
+    def video_asset(self):
+        asset = Mock()
+        asset.storage_key = "videos/test-video.mp4"
+        asset.mime_type = "video/mp4"
+        return asset
+
+    @pytest.fixture
+    def service(self, mock_storage, mock_asset_repo):
+        return CoverService(storage_service=mock_storage, asset_repository=mock_asset_repo)
+
+    def test_extract_cover_asset_not_found(self, service, mock_asset_repo):
+        """测试素材不存在时报错"""
+        mock_asset_repo.get.return_value = None
+
+        with pytest.raises(ValueError, match="素材不存在"):
+            service.extract_cover_from_clip(plan_id="plan-1", asset_id="nonexistent")
+
+    def test_extract_cover_asset_no_storage_key(self, service, mock_asset_repo):
+        """测试素材没有文件时报错"""
+        asset = Mock()
+        asset.storage_key = ""
+        asset.mime_type = "video/mp4"
+        mock_asset_repo.get.return_value = asset
+
+        with pytest.raises(ValueError, match="素材没有文件"):
+            service.extract_cover_from_clip(plan_id="plan-1", asset_id="asset-no-file")
+
+    def test_extract_cover_asset_not_video(self, service, mock_asset_repo):
+        """测试非视频素材报错"""
+        asset = Mock()
+        asset.storage_key = "images/photo.jpg"
+        asset.mime_type = "image/jpeg"
+        mock_asset_repo.get.return_value = asset
+
+        with pytest.raises(ValueError, match="素材不是视频类型"):
+            service.extract_cover_from_clip(plan_id="plan-1", asset_id="asset-img")
+
+    def test_extract_cover_download_failure(self, service, mock_asset_repo, mock_storage, video_asset):
+        """测试下载素材失败"""
+        mock_asset_repo.get.return_value = video_asset
+        mock_storage.download_file.side_effect = Exception("网络错误")
+
+        with pytest.raises(RuntimeError, match="下载素材失败"):
+            service.extract_cover_from_clip(plan_id="plan-1", asset_id="asset-1")
+
+    def test_extract_cover_upload_failure(self, service, mock_asset_repo, mock_storage, video_asset):
+        """测试上传封面失败"""
+        mock_asset_repo.get.return_value = video_asset
+
+        def fake_download(storage_key, local_path):
+            # 创建一个假的视频文件
+            Path(local_path).parent.mkdir(parents=True, exist_ok=True)
+            with open(local_path, "wb") as f:
+                f.write(b"fake video data")
+
+        mock_storage.download_file.side_effect = fake_download
+        mock_storage.upload_file.side_effect = Exception("上传失败")
+
+        # mock _extract_frame 避免真的调 ffmpeg
+        with patch.object(CoverService, "_extract_frame") as mock_extract:
+
+            def fake_extract(video_path, output_path, **kwargs):
+                # 创建假的封面文件
+                with open(output_path, "wb") as f:
+                    f.write(b"\xff\xd8\xff\xe0fake jpeg data")
+
+            mock_extract.side_effect = fake_extract
+
+            with pytest.raises(RuntimeError, match="上传封面失败"):
+                service.extract_cover_from_clip(plan_id="plan-1", asset_id="asset-1")
+
+    def test_extract_cover_get_url_falls_back_to_key(self, service, mock_asset_repo, mock_storage, video_asset):
+        """测试获取 URL 失败时降级为 storage_key"""
+        mock_asset_repo.get.return_value = video_asset
+
+        def fake_download(storage_key, local_path):
+            Path(local_path).parent.mkdir(parents=True, exist_ok=True)
+            with open(local_path, "wb") as f:
+                f.write(b"fake video data")
+
+        mock_storage.download_file.side_effect = fake_download
+        mock_storage.get_url.side_effect = Exception("URL服务不可用")
+
+        with patch.object(CoverService, "_extract_frame") as mock_extract:
+
+            def fake_extract(video_path, output_path, **kwargs):
+                with open(output_path, "wb") as f:
+                    f.write(b"\xff\xd8\xff\xe0fake jpeg")
+
+            mock_extract.side_effect = fake_extract
+
+            result = service.extract_cover_from_clip(plan_id="plan-abc", asset_id="asset-xyz", frame_time=2.5)
+
+        assert result["type"] == "manual"
+        assert result["frame_time"] == 2.5
+        # URL 失败时返回 storage_key
+        assert COVER_STORAGE_PREFIX in result["image_url"]
+        assert "plan-abc" in result["image_url"]
+
+    def test_extract_cover_success(self, service, mock_asset_repo, mock_storage, video_asset):
+        """测试抽帧成功完整流程"""
+        mock_asset_repo.get.return_value = video_asset
+
+        def fake_download(storage_key, local_path):
+            Path(local_path).parent.mkdir(parents=True, exist_ok=True)
+            with open(local_path, "wb") as f:
+                f.write(b"fake video data for testing")
+
+        mock_storage.download_file.side_effect = fake_download
+
+        with patch.object(CoverService, "_extract_frame") as mock_extract:
+
+            def fake_extract(video_path, output_path, **kwargs):
+                with open(output_path, "wb") as f:
+                    f.write(b"\xff\xd8\xff\xe0fake jpeg image data")
+
+            mock_extract.side_effect = fake_extract
+
+            result = service.extract_cover_from_clip(
+                plan_id="plan-123",
+                asset_id="asset-456",
+                frame_time=3.0,
+                width=720,
+                height=1280,
+                quality=3,
+            )
+
+        assert result["type"] == "manual"
+        assert result["image_url"] == "https://oss.example.com/covers/plan1/cover_1000.jpg"
+        assert result["frame_time"] == 3.0
+
+        # 验证上传被调用
+        mock_storage.upload_file.assert_called_once()
+        upload_args = mock_storage.upload_file.call_args[1]
+        assert upload_args["content_type"] == "image/jpeg"
+        assert "plan-123" in upload_args["storage_key"]
+        assert "3000" in upload_args["storage_key"]  # frame_time * 1000
+
+        # 验证 _extract_frame 被调用且参数正确
+        mock_extract.assert_called_once()
+        extract_kwargs = mock_extract.call_args[1]
+        assert extract_kwargs["time_sec"] == 3.0
+        assert extract_kwargs["width"] == 720
+        assert extract_kwargs["height"] == 1280
+        assert extract_kwargs["quality"] == 3
+
+
+class TestGenerateSmartCover:
+    """generate_smart_cover 测试"""
+
+    @pytest.fixture
+    def service(self):
+        return CoverService(storage_service=Mock(), asset_repository=Mock())
+
+    def test_generate_smart_cover_calls_extract_with_default_time(self, service):
+        """测试智能封面调用 extract_cover_from_clip 并设置 type 为 ai_frame"""
+        fake_result = {"type": "manual", "image_url": "test.jpg", "frame_time": 3.0}
+
+        with patch.object(service, "extract_cover_from_clip", return_value=fake_result) as mock_extract:
+            result = service.generate_smart_cover(plan_id="plan-1", asset_id="asset-1")
+
+            mock_extract.assert_called_once()
+            call_kwargs = mock_extract.call_args[1]
+            assert call_kwargs["plan_id"] == "plan-1"
+            assert call_kwargs["asset_id"] == "asset-1"
+            assert call_kwargs["frame_time"] == 3.0  # 默认第3秒
+
+        assert result["type"] == "ai_frame"
+        assert result["image_url"] == "test.jpg"
+
+    def test_generate_smart_cover_passes_dimensions(self, service):
+        """测试智能封面传递尺寸和质量参数"""
+        fake_result = {"type": "manual", "image_url": "test.jpg", "frame_time": 3.0}
+
+        with patch.object(service, "extract_cover_from_clip", return_value=fake_result) as mock_extract:
+            service.generate_smart_cover(
+                plan_id="plan-1",
+                asset_id="asset-1",
+                width=1080,
+                height=1920,
+                quality=5,
+            )
+
+            call_kwargs = mock_extract.call_args[1]
+            assert call_kwargs["width"] == 1080
+            assert call_kwargs["height"] == 1920
+            assert call_kwargs["quality"] == 5
+
+
+class TestExtractFrame:
+    """_extract_frame 静态方法测试（mock subprocess）"""
+
+    @pytest.fixture
+    def video_path(self, tmp_path):
+        path = tmp_path / "test_video.mp4"
+        path.write_bytes(b"fake video")
+        return path
+
+    @pytest.fixture
+    def output_path(self, tmp_path):
+        return tmp_path / "cover.jpg"
+
+    def test_extract_frame_success(self, video_path, output_path):
+        """测试 FFmpeg 抽帧成功"""
+        fake_result = Mock()
+        fake_result.returncode = 0
+
+        with patch("subprocess.run", return_value=fake_result) as mock_run:
+            CoverService._extract_frame(
+                video_path=video_path,
+                output_path=output_path,
+                time_sec=2.5,
+                width=1080,
+                height=1920,
+                quality=5,
+            )
+
+            assert mock_run.call_count == 1
+            cmd = mock_run.call_args[0][0]
+            assert cmd[0] == "ffmpeg"
+            assert "-ss" in cmd
+            assert "2.500" in cmd
+            assert "-vframes" in cmd
+            # 验证 scale+crop 滤镜存在
+            vf_index = cmd.index("-vf") + 1
+            assert "scale=" in cmd[vf_index]
+            assert "crop=" in cmd[vf_index]
+
+    def test_extract_frame_fallback_to_simple_command(self, video_path, output_path):
+        """测试主命令失败时回退到简化命令"""
+        fail_result = Mock()
+        fail_result.returncode = 1
+        fail_result.stderr = "Filter graph error"
+
+        success_result = Mock()
+        success_result.returncode = 0
+
+        call_count = 0
+
+        def fake_run(*args, **kwargs):
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                return fail_result
+            return success_result
+
+        with patch("subprocess.run", side_effect=fake_run) as mock_run:
+            CoverService._extract_frame(
+                video_path=video_path,
+                output_path=output_path,
+                time_sec=1.0,
+                width=1080,
+                height=1920,
+                quality=5,
+            )
+
+            assert mock_run.call_count == 2
+            # 第二次是简化命令（没有 -vf 参数）
+            second_cmd = mock_run.call_args_list[1][0][0]
+            assert "-vf" not in second_cmd
+
+    def test_extract_frame_both_commands_fail(self, video_path, output_path):
+        """测试两个命令都失败时报错"""
+        fail_result = Mock()
+        fail_result.returncode = 1
+        fail_result.stderr = "Invalid data found when processing input"
+
+        with patch("subprocess.run", return_value=fail_result):
+            with pytest.raises(RuntimeError, match="FFmpeg 抽帧失败"):
+                CoverService._extract_frame(
+                    video_path=video_path,
+                    output_path=output_path,
+                    time_sec=1.0,
+                    width=1080,
+                    height=1920,
+                    quality=5,
+                )
+
+    def test_extract_frame_timeout(self, video_path, output_path):
+        """测试 FFmpeg 抽帧超时"""
+        with patch("subprocess.run", side_effect=subprocess.TimeoutExpired(cmd="ffmpeg", timeout=60)):
+            with pytest.raises(RuntimeError, match="FFmpeg 抽帧超时"):
+                CoverService._extract_frame(
+                    video_path=video_path,
+                    output_path=output_path,
+                    time_sec=1.0,
+                    width=1080,
+                    height=1920,
+                    quality=5,
+                )
+
+    def test_extract_frame_ffmpeg_not_found(self, video_path, output_path):
+        """测试 FFmpeg 不可用"""
+        with patch("subprocess.run", side_effect=FileNotFoundError("ffmpeg not found")):
+            with pytest.raises(RuntimeError, match="FFmpeg 不可用"):
+                CoverService._extract_frame(
+                    video_path=video_path,
+                    output_path=output_path,
+                    time_sec=1.0,
+                    width=1080,
+                    height=1920,
+                    quality=5,
+                )
+
+
+class TestDefaults:
+    """默认常量测试"""
+
+    def test_default_dimensions(self):
+        """测试默认尺寸常量"""
+        assert DEFAULT_COVER_WIDTH == 1080
+        assert DEFAULT_COVER_HEIGHT == 1920
+        assert DEFAULT_COVER_QUALITY == 5
+        assert COVER_STORAGE_PREFIX == "covers"

tests/unit/test_duplication_domain.py

@@ -1,274 +1,351 @@
-"""查重域模型单元测试。
-
-覆盖：
-- DuplicationRecord.create() 工厂方法及验证
-- DuplicationRecord 状态转换（mark_processing / mark_completed / mark_failed）
-- DuplicationRecord.can_retry() / reset_for_retry()
-- DuplicateSegment.create() 工厂方法及验证
 """
-
-from __future__ import annotations
+Duplication 查重记录领域模型单元测试
+"""
 
 import pytest
 
 from packages.domain.duplication import DuplicateSegment, DuplicationRecord
 
 
-class TestDuplicationRecordCreate:
-    """DuplicationRecord.create() 工厂方法测试。"""
+class TestDuplicateSegmentCreate:
+    """DuplicateSegment.create 测试"""
 
     def test_create_success(self):
-        record = DuplicationRecord.create(
-            user_id="user-1",
-            filename="test.mp4",
-            file_size=1024,
-            storage_key="oss/key/test.mp4",
-            duration_seconds=30.0,
+        seg = DuplicateSegment.create(
+            source_start=10.0,
+            source_end=20.0,
+            matched_video_id="vid_123",
+            matched_video_name="测试视频",
+            matched_start=5.0,
+            matched_end=15.0,
+            similarity=85.5,
         )
-        assert record.user_id == "user-1"
+        assert seg.id is not None
+        assert len(seg.id) == 32
+        assert seg.source_start == 10.0
+        assert seg.source_end == 20.0
+        assert seg.matched_video_id == "vid_123"
+        assert seg.matched_video_name == "测试视频"
+        assert seg.matched_start == 5.0
+        assert seg.matched_end == 15.0
+        assert seg.similarity == 85.5
+
+    def test_invalid_source_negative_start(self):
+        with pytest.raises(ValueError, match="invalid source segment range"):
+            DuplicateSegment.create(
+                source_start=-1.0,
+                source_end=10.0,
+                matched_video_id="v1",
+                matched_video_name="n1",
+                matched_start=0,
+                matched_end=10,
+                similarity=50,
+            )
+
+    def test_invalid_source_end_before_start(self):
+        with pytest.raises(ValueError, match="invalid source segment range"):
+            DuplicateSegment.create(
+                source_start=20.0,
+                source_end=10.0,
+                matched_video_id="v1",
+                matched_video_name="n1",
+                matched_start=0,
+                matched_end=10,
+                similarity=50,
+            )
+
+    def test_invalid_source_end_equals_start(self):
+        with pytest.raises(ValueError, match="invalid source segment range"):
+            DuplicateSegment.create(
+                source_start=10.0,
+                source_end=10.0,
+                matched_video_id="v1",
+                matched_video_name="n1",
+                matched_start=0,
+                matched_end=10,
+                similarity=50,
+            )
+
+    def test_invalid_matched_negative_start(self):
+        with pytest.raises(ValueError, match="invalid matched segment range"):
+            DuplicateSegment.create(
+                source_start=0,
+                source_end=10,
+                matched_video_id="v1",
+                matched_video_name="n1",
+                matched_start=-5,
+                matched_end=10,
+                similarity=50,
+            )
+
+    def test_invalid_matched_end_before_start(self):
+        with pytest.raises(ValueError, match="invalid matched segment range"):
+            DuplicateSegment.create(
+                source_start=0,
+                source_end=10,
+                matched_video_id="v1",
+                matched_video_name="n1",
+                matched_start=15,
+                matched_end=10,
+                similarity=50,
+            )
+
+    def test_invalid_similarity_negative(self):
+        with pytest.raises(ValueError, match="similarity must be between 0 and 100"):
+            DuplicateSegment.create(
+                source_start=0,
+                source_end=10,
+                matched_video_id="v1",
+                matched_video_name="n1",
+                matched_start=0,
+                matched_end=10,
+                similarity=-1,
+            )
+
+    def test_invalid_similarity_over_100(self):
+        with pytest.raises(ValueError, match="similarity must be between 0 and 100"):
+            DuplicateSegment.create(
+                source_start=0,
+                source_end=10,
+                matched_video_id="v1",
+                matched_video_name="n1",
+                matched_start=0,
+                matched_end=10,
+                similarity=101,
+            )
+
+    def test_similarity_boundary_zero(self):
+        seg = DuplicateSegment.create(
+            source_start=0,
+            source_end=10,
+            matched_video_id="v1",
+            matched_video_name="n1",
+            matched_start=0,
+            matched_end=10,
+            similarity=0,
+        )
+        assert seg.similarity == 0
+
+    def test_similarity_boundary_100(self):
+        seg = DuplicateSegment.create(
+            source_start=0,
+            source_end=10,
+            matched_video_id="v1",
+            matched_video_name="n1",
+            matched_start=0,
+            matched_end=10,
+            similarity=100,
+        )
+        assert seg.similarity == 100
+
+
+class TestDuplicationRecordCreate:
+    """DuplicationRecord.create 测试"""
+
+    def test_create_minimal(self):
+        record = DuplicationRecord.create(
+            user_id="user123",
+            filename="test.mp4",
+            file_size=1024000,
+            storage_key="oss://bucket/test.mp4",
+        )
+        assert record.id is not None
+        assert len(record.id) == 32
+        assert record.user_id == "user123"
         assert record.filename == "test.mp4"
-        assert record.file_size == 1024
-        assert record.storage_key == "oss/key/test.mp4"
-        assert record.duration_seconds == 30.0
+        assert record.file_size == 1024000
+        assert record.storage_key == "oss://bucket/test.mp4"
+        assert record.status == "pending"
+        assert record.duplicate_rate is None
+        assert record.duplicate_count == 0
+        assert record.segments == []
+        assert record.duration_seconds == 0.0
+        assert record.created_at is not None
+        assert record.updated_at is not None
+
+    def test_create_with_duration(self):
+        record = DuplicationRecord.create(
+            user_id="u1",
+            filename="video.mp4",
+            file_size=5000,
+            storage_key="key",
+            duration_seconds=120.5,
+        )
+        assert record.duration_seconds == 120.5
+
+    def test_create_strips_whitespace(self):
+        record = DuplicationRecord.create(
+            user_id="  user456  ",
+            filename="  my video.mp4  ",
+            file_size=100,
+            storage_key="key",
+        )
+        assert record.user_id == "user456"
+        assert record.filename == "my video.mp4"
+
+    def test_empty_user_id_raises(self):
+        with pytest.raises(ValueError, match="user_id cannot be empty"):
+            DuplicationRecord.create(
+                user_id="   ",
+                filename="test.mp4",
+                file_size=100,
+                storage_key="key",
+            )
+
+    def test_empty_filename_raises(self):
+        with pytest.raises(ValueError, match="filename cannot be empty"):
+            DuplicationRecord.create(
+                user_id="u1",
+                filename="  ",
+                file_size=100,
+                storage_key="key",
+            )
+
+    def test_zero_file_size_raises(self):
+        with pytest.raises(ValueError, match="file_size must be positive"):
+            DuplicationRecord.create(
+                user_id="u1",
+                filename="test.mp4",
+                file_size=0,
+                storage_key="key",
+            )
+
+    def test_negative_file_size_raises(self):
+        with pytest.raises(ValueError, match="file_size must be positive"):
+            DuplicationRecord.create(
+                user_id="u1",
+                filename="test.mp4",
+                file_size=-100,
+                storage_key="key",
+            )
+
+
+class TestDuplicationRecordLifecycle:
+    """生命周期状态转换测试"""
+
+    def test_mark_processing(self):
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        old_updated = record.updated_at
+        record.mark_processing()
+        assert record.status == "processing"
+        assert record.updated_at >= old_updated
+
+    def test_mark_completed(self):
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        record.mark_processing()
+        segments = [
+            DuplicateSegment.create(
+                source_start=0,
+                source_end=10,
+                matched_video_id="v1",
+                matched_video_name="n1",
+                matched_start=0,
+                matched_end=10,
+                similarity=90,
+            )
+        ]
+        record.mark_completed(
+            duplicate_rate=25.5,
+            duplicate_count=1,
+            segments=segments,
+        )
+        assert record.status == "completed"
+        assert record.duplicate_rate == 25.5
+        assert record.duplicate_count == 1
+        assert len(record.segments) == 1
+        assert record.error_message == ""
+
+    def test_mark_completed_zero_rate(self):
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        record.mark_completed(duplicate_rate=0.0, duplicate_count=0, segments=[])
+        assert record.status == "completed"
+        assert record.duplicate_rate == 0.0
+        assert record.duplicate_count == 0
+        assert record.segments == []
+
+    def test_mark_completed_100_rate(self):
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        record.mark_completed(duplicate_rate=100.0, duplicate_count=5, segments=[])
+        assert record.duplicate_rate == 100.0
+
+    def test_mark_completed_invalid_rate_negative(self):
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        with pytest.raises(ValueError, match="duplicate_rate must be between 0 and 100"):
+            record.mark_completed(duplicate_rate=-1, duplicate_count=0, segments=[])
+
+    def test_mark_completed_invalid_rate_over_100(self):
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        with pytest.raises(ValueError, match="duplicate_rate must be between 0 and 100"):
+            record.mark_completed(duplicate_rate=101, duplicate_count=0, segments=[])
+
+    def test_mark_failed(self):
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        record.mark_processing()
+        record.mark_failed("网络超时")
+        assert record.status == "failed"
+        assert record.error_message == "网络超时"
+        assert record.duplicate_rate is None
+
+    def test_mark_failed_from_pending(self):
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        record.mark_failed("文件损坏")
+        assert record.status == "failed"
+        assert record.error_message == "文件损坏"
+
+
+class TestDuplicationRecordRetry:
+    """重试逻辑测试"""
+
+    def test_can_retry_failed(self):
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        record.mark_failed("error")
+        assert record.can_retry() is True
+
+    def test_cannot_retry_pending(self):
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        assert record.can_retry() is False
+
+    def test_cannot_retry_processing(self):
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        record.mark_processing()
+        assert record.can_retry() is False
+
+    def test_cannot_retry_completed(self):
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        record.mark_completed(duplicate_rate=10, duplicate_count=1, segments=[])
+        assert record.can_retry() is False
+
+    def test_reset_for_retry(self):
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        record.mark_processing()
+        segments = [
+            DuplicateSegment.create(
+                source_start=0,
+                source_end=5,
+                matched_video_id="v1",
+                matched_video_name="n1",
+                matched_start=0,
+                matched_end=5,
+                similarity=80,
+            )
+        ]
+        record.mark_completed(duplicate_rate=30, duplicate_count=1, segments=segments)
+        record.status = "failed"
+        record.error_message = "something wrong"
+        record.video_fingerprint = {"hash": "abc"}
+
+        record.reset_for_retry()
         assert record.status == "pending"
         assert record.duplicate_rate is None
         assert record.duplicate_count == 0
         assert record.error_message == ""
         assert record.segments == []
         assert record.video_fingerprint is None
-        assert record.id  # 自动生成 ID
+        assert record.updated_at is not None
 
-    def test_create_with_default_duration(self):
-        record = DuplicationRecord.create(
-            user_id="user-1",
-            filename="test.mp4",
-            file_size=1024,
-            storage_key="oss/key",
-        )
-        assert record.duration_seconds == 0.0
-
-    def test_create_empty_user_id_raises(self):
-        with pytest.raises(ValueError, match="user_id"):
-            DuplicationRecord.create(
-                user_id="",
-                filename="test.mp4",
-                file_size=1024,
-                storage_key="oss/key",
-            )
-
-    def test_create_whitespace_user_id_raises(self):
-        with pytest.raises(ValueError, match="user_id"):
-            DuplicationRecord.create(
-                user_id="   ",
-                filename="test.mp4",
-                file_size=1024,
-                storage_key="oss/key",
-            )
-
-    def test_create_empty_filename_raises(self):
-        with pytest.raises(ValueError, match="filename"):
-            DuplicationRecord.create(
-                user_id="user-1",
-                filename="",
-                file_size=1024,
-                storage_key="oss/key",
-            )
-
-    def test_create_zero_file_size_raises(self):
-        with pytest.raises(ValueError, match="file_size"):
-            DuplicationRecord.create(
-                user_id="user-1",
-                filename="test.mp4",
-                file_size=0,
-                storage_key="oss/key",
-            )
-
-    def test_create_negative_file_size_raises(self):
-        with pytest.raises(ValueError, match="file_size"):
-            DuplicationRecord.create(
-                user_id="user-1",
-                filename="test.mp4",
-                file_size=-100,
-                storage_key="oss/key",
-            )
-
-
-class TestDuplicationRecordStateTransitions:
-    """状态转换测试。"""
-
-    @pytest.fixture
-    def record(self):
-        return DuplicationRecord.create(
-            user_id="user-1",
-            filename="test.mp4",
-            file_size=1024,
-            storage_key="oss/key",
-        )
-
-    def test_mark_processing(self, record):
-        record.mark_processing()
-        assert record.status == "processing"
-
-    def test_mark_completed_success(self, record):
-        record.mark_processing()
-        segments = [
-            DuplicateSegment.create(
-                source_start=0.0,
-                source_end=5.0,
-                matched_video_id="vid-1",
-                matched_video_name="existing.mp4",
-                matched_start=0.0,
-                matched_end=5.0,
-                similarity=92.5,
-            )
-        ]
-        record.mark_completed(duplicate_rate=15.0, duplicate_count=1, segments=segments)
-        assert record.status == "completed"
-        assert record.duplicate_rate == 15.0
-        assert record.duplicate_count == 1
-        assert len(record.segments) == 1
-
-    def test_mark_completed_invalid_rate_raises(self, record):
-        record.mark_processing()
-        with pytest.raises(ValueError, match="duplicate_rate"):
-            record.mark_completed(duplicate_rate=101.0, duplicate_count=0, segments=[])
-
-    def test_mark_completed_negative_rate_raises(self, record):
-        record.mark_processing()
-        with pytest.raises(ValueError, match="duplicate_rate"):
-            record.mark_completed(duplicate_rate=-1.0, duplicate_count=0, segments=[])
-
-    def test_mark_failed(self, record):
-        record.mark_processing()
-        record.mark_failed("处理超时")
-        assert record.status == "failed"
-        assert record.error_message == "处理超时"
-
-
-class TestDuplicationRecordRetry:
-    """can_retry() 和 reset_for_retry() 测试。"""
-
-    @pytest.fixture
-    def record(self):
-        return DuplicationRecord.create(
-            user_id="user-1",
-            filename="test.mp4",
-            file_size=1024,
-            storage_key="oss/key",
-        )
-
-    def test_mark_failed_sets_status_and_error(self, record):
-        record.mark_processing()
-        record.mark_failed("处理失败")
-        assert record.status == "failed"
-        assert record.error_message == "处理失败"
-
-    def test_mark_failed_updates_timestamp(self, record):
-        old_updated = record.updated_at
-        record.mark_processing()
-        record.mark_failed("错误")
-        assert record.updated_at >= old_updated
-
-    def test_failed_record_preserves_result_fields(self, record):
-        """mark_failed 不改变 duplicate_rate 等结果字段（由 use case 层重置）。"""
-        record.mark_processing()
-        record.mark_completed(duplicate_rate=10.0, duplicate_count=1, segments=[])
-        record.mark_failed("重试失败")
-        assert record.status == "failed"
-        assert record.error_message == "重试失败"
-        assert record.duplicate_rate == 10.0
-
-
-class TestDuplicateSegmentCreate:
-    """DuplicateSegment.create() 工厂方法测试。"""
-
-    def test_create_success(self):
-        seg = DuplicateSegment.create(
-            source_start=1.0,
-            source_end=5.0,
-            matched_video_id="vid-1",
-            matched_video_name="existing.mp4",
-            matched_start=2.0,
-            matched_end=6.0,
-            similarity=85.5,
-        )
-        assert seg.source_start == 1.0
-        assert seg.source_end == 5.0
-        assert seg.matched_video_id == "vid-1"
-        assert seg.matched_video_name == "existing.mp4"
-        assert seg.matched_start == 2.0
-        assert seg.matched_end == 6.0
-        assert seg.similarity == 85.5
-        assert seg.id  # 自动生成 ID
-
-    def test_create_negative_source_start_raises(self):
-        with pytest.raises(ValueError, match="invalid source segment range"):
-            DuplicateSegment.create(
-                source_start=-1.0,
-                source_end=5.0,
-                matched_video_id="vid-1",
-                matched_video_name="v.mp4",
-                matched_start=0.0,
-                matched_end=5.0,
-                similarity=80.0,
-            )
-
-    def test_create_source_end_le_start_raises(self):
-        with pytest.raises(ValueError, match="invalid source segment range"):
-            DuplicateSegment.create(
-                source_start=5.0,
-                source_end=5.0,
-                matched_video_id="vid-1",
-                matched_video_name="v.mp4",
-                matched_start=0.0,
-                matched_end=5.0,
-                similarity=80.0,
-            )
-
-    def test_create_negative_matched_start_raises(self):
-        with pytest.raises(ValueError, match="invalid matched segment range"):
-            DuplicateSegment.create(
-                source_start=0.0,
-                source_end=5.0,
-                matched_video_id="vid-1",
-                matched_video_name="v.mp4",
-                matched_start=-1.0,
-                matched_end=5.0,
-                similarity=80.0,
-            )
-
-    def test_create_matched_end_le_start_raises(self):
-        with pytest.raises(ValueError, match="invalid matched segment range"):
-            DuplicateSegment.create(
-                source_start=0.0,
-                source_end=5.0,
-                matched_video_id="vid-1",
-                matched_video_name="v.mp4",
-                matched_start=2.0,
-                matched_end=1.0,
-                similarity=80.0,
-            )
-
-    def test_create_similarity_out_of_range_raises(self):
-        with pytest.raises(ValueError, match="similarity"):
-            DuplicateSegment.create(
-                source_start=0.0,
-                source_end=5.0,
-                matched_video_id="vid-1",
-                matched_video_name="v.mp4",
-                matched_start=0.0,
-                matched_end=5.0,
-                similarity=101.0,
-            )
-
-    def test_create_negative_similarity_raises(self):
-        with pytest.raises(ValueError, match="similarity"):
-            DuplicateSegment.create(
-                source_start=0.0,
-                source_end=5.0,
-                matched_video_id="vid-1",
-                matched_video_name="v.mp4",
-                matched_start=0.0,
-                matched_end=5.0,
-                similarity=-1.0,
-            )
+    def test_reset_for_retry_from_pending(self):
+        """即使从 pending 也能重置（调用方负责判断 can_retry）"""
+        record = DuplicationRecord.create(user_id="u1", filename="t.mp4", file_size=100, storage_key="k")
+        record.reset_for_retry()
+        assert record.status == "pending"
+        assert record.duplicate_count == 0

tests/unit/test_edit_plan_adjustments_api.py

@@ -1,491 +0,0 @@
-"""
-片段调整 API 单元测试
-
-覆盖：
-- PUT /clips/{clip_id}/speed - 调速
-- PUT /clips/{clip_id}/volume - 音量调节
-- PUT /clips/{clip_id}/trim - 裁剪
-- PUT /clips/{clip_id}/adjustments - 统一调整
-- POST /{plan_id}/clips/batch-speed - 批量调速
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from datetime import datetime
-from pathlib import Path
-from typing import Optional
-from unittest.mock import MagicMock
-
-os.environ.setdefault("JWT_SECRET_KEY", "unit-test-secret-key-for-testing")
-os.environ.setdefault("DATABASE_URL", "sqlite:///test.db")
-
-import pytest
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
-
-from fastapi import FastAPI
-from fastapi.testclient import TestClient
-
-from packages.domain.config_schemas import normalize_plan_config
-from packages.domain.edit_plan import EditPlan, EditPlanStatus
-from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
-
-# ---------------------------------------------------------------------------
-# Stub Repository
-# ---------------------------------------------------------------------------
-
-
-class StubEditPlanRepository:
-    def __init__(self, plans: dict[str, EditPlan] | None = None):
-        self._plans = plans or {}
-
-    def get(self, plan_id: str) -> Optional[EditPlan]:
-        return self._plans.get(plan_id)
-
-    def create(self, plan: EditPlan) -> EditPlan:
-        self._plans[plan.id] = plan
-        return plan
-
-    def update(self, plan: EditPlan) -> EditPlan:
-        self._plans[plan.id] = plan
-        return plan
-
-    def list_all(self, *, status=None, skip=0, limit=50):
-        return list(self._plans.values())[skip : skip + limit]
-
-    def list_by_template(self, template_id, *, status=None, skip=0, limit=50):
-        return [p for p in self._plans.values() if p.template_id == template_id][skip : skip + limit]
-
-    def delete(self, plan_id: str) -> bool:
-        return self._plans.pop(plan_id, None) is not None
-
-    def count(self, *, status=None, template_id=None):
-        return len(self._plans)
-
-
-class StubEditPlanClipRepository:
-    def __init__(self, clips: dict[str, EditPlanClip] | None = None):
-        self._clips = clips or {}
-
-    def list_by_plan(self, plan_id, *, status=None, skip=0, limit=100):
-        items = [c for c in self._clips.values() if c.plan_id == plan_id]
-        items.sort(key=lambda c: c.order)
-        return items[skip : skip + limit]
-
-    def count(self, plan_id, *, status=None):
-        return len([c for c in self._clips.values() if c.plan_id == plan_id])
-
-    def get(self, clip_id: str) -> Optional[EditPlanClip]:
-        return self._clips.get(clip_id)
-
-    def create(self, clip: EditPlanClip) -> EditPlanClip:
-        self._clips[clip.id] = clip
-        return clip
-
-    def update(self, clip: EditPlanClip) -> EditPlanClip:
-        self._clips[clip.id] = clip
-        return clip
-
-    def delete(self, clip_id: str) -> bool:
-        return self._clips.pop(clip_id, None) is not None
-
-    def delete_by_plan(self, plan_id: str) -> int:
-        before = len(self._clips)
-        self._clips = {k: v for k, v in self._clips.items() if v.plan_id != plan_id}
-        return before - len(self._clips)
-
-
-# ---------------------------------------------------------------------------
-# Test Fixtures
-# ---------------------------------------------------------------------------
-
-
-def _make_sample_plan(plan_id="plan-001"):
-    return EditPlan(
-        id=plan_id,
-        template_id="tpl-001",
-        name="测试计划",
-        status=EditPlanStatus.EDITING,
-        total_duration=30.0,
-        config=normalize_plan_config({}),
-        project_id="",
-        created_by_user_id="user-001",
-        created_at=datetime(2026, 7, 16, 10, 0, 0),
-        updated_at=datetime(2026, 7, 16, 10, 0, 0),
-    )
-
-
-def _make_clip(clip_id, plan_id="plan-001", order=0, duration=10.0, speed=1.0):
-    return EditPlanClip(
-        id=clip_id,
-        plan_id=plan_id,
-        clip_type="video",
-        order=order,
-        asset_id="asset-001",
-        text_content="",
-        start_time=0.0,
-        duration=duration,
-        transition_effect="cut",
-        transition_duration=0.0,
-        playback_speed=speed,
-        status=EditPlanClipStatus.READY,
-        config={},
-        created_at=datetime(2026, 7, 16, 10, 0, 0),
-        updated_at=datetime(2026, 7, 16, 10, 0, 0),
-    )
-
-
-def _create_test_app():
-    import app.services.edit_plan_service as service_module
-    from app.api.routes.edit_plans import router
-
-    plan = _make_sample_plan()
-    clips = {
-        "clip-001": _make_clip("clip-001", order=0, duration=10.0),
-        "clip-002": _make_clip("clip-002", order=1, duration=15.0),
-        "clip-003": _make_clip("clip-003", order=2, duration=20.0),
-    }
-    stub_plan_repo = StubEditPlanRepository({plan.id: plan})
-    stub_clip_repo = StubEditPlanClipRepository(clips)
-
-    original_plan_repo = service_module.SQLAlchemyEditPlanRepository
-    original_clip_repo = service_module.SQLAlchemyEditPlanClipRepository
-    original_gen_repo = service_module.SQLAlchemyGenerationTaskRepository
-    service_module.SQLAlchemyEditPlanRepository = lambda db: stub_plan_repo
-    service_module.SQLAlchemyEditPlanClipRepository = lambda db: stub_clip_repo
-    service_module.SQLAlchemyGenerationTaskRepository = lambda db: MagicMock()
-
-    app = FastAPI()
-    app.include_router(router, prefix="/api/v1/edit-plans")
-
-    def _mock_auth():
-        mock = MagicMock()
-        mock.user.id = "user-001"
-        return mock
-
-    import app.api.routes._helpers as helpers_module
-
-    original_check = helpers_module.check_project_access
-    helpers_module.check_project_access = lambda *a, **kw: None
-
-    from app.api.routes import edit_plans as main_module
-
-    app.dependency_overrides[main_module.get_current_user] = _mock_auth
-    app.dependency_overrides[main_module.get_db_session] = lambda: MagicMock()
-    app.dependency_overrides[main_module.get_project_repository] = lambda: MagicMock()
-
-    import app.api.routes.edit_plans_adjustments as adj_module
-
-    app.dependency_overrides[adj_module.get_current_user] = _mock_auth
-    app.dependency_overrides[adj_module.get_db_session] = lambda: MagicMock()
-    app.dependency_overrides[adj_module.get_project_repository] = lambda: MagicMock()
-
-    def cleanup():
-        service_module.SQLAlchemyEditPlanRepository = original_plan_repo
-        service_module.SQLAlchemyEditPlanClipRepository = original_clip_repo
-        service_module.SQLAlchemyGenerationTaskRepository = original_gen_repo
-        helpers_module.check_project_access = original_check
-
-    return app, stub_plan_repo, stub_clip_repo, cleanup
-
-
-@pytest.fixture
-def adj_client():
-    app, plan_repo, clip_repo, cleanup = _create_test_app()
-    yield TestClient(app), plan_repo, clip_repo
-    cleanup()
-
-
-# ---------------------------------------------------------------------------
-# 调速测试
-# ---------------------------------------------------------------------------
-
-
-class TestAdjustSpeed:
-    def test_speed_up(self, adj_client):
-        c, _, clip_repo = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/speed",
-            json={"speed": 2.0},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["speed"] == 2.0
-        assert data["clip_id"] == "clip-001"
-
-        clip = clip_repo.get("clip-001")
-        assert clip.playback_speed == 2.0
-
-    def test_slow_down(self, adj_client):
-        c, _, clip_repo = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/speed",
-            json={"speed": 0.5},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["speed"] == 0.5
-
-    def test_speed_clip_not_found(self, adj_client):
-        c, _, _ = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-nonexist/speed",
-            json={"speed": 1.5},
-        )
-        assert resp.status_code == 404
-
-    def test_speed_out_of_range_low(self, adj_client):
-        c, _, _ = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/speed",
-            json={"speed": 0.1},
-        )
-        assert resp.status_code == 422
-
-    def test_speed_out_of_range_high(self, adj_client):
-        c, _, _ = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/speed",
-            json={"speed": 5.0},
-        )
-        assert resp.status_code == 422
-
-    def test_speed_default_value(self, adj_client):
-        c, _, clip_repo = adj_client
-        # 验证默认 speed
-        clip = clip_repo.get("clip-001")
-        assert clip.playback_speed == 1.0
-
-
-# ---------------------------------------------------------------------------
-# 音量调节测试
-# ---------------------------------------------------------------------------
-
-
-class TestAdjustVolume:
-    def test_set_volume(self, adj_client):
-        c, _, clip_repo = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/volume",
-            json={"volume": 0.5},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["volume"] == 0.5
-
-        clip = clip_repo.get("clip-001")
-        assert clip.config["volume"] == 0.5
-
-    def test_mute(self, adj_client):
-        c, _, clip_repo = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/volume",
-            json={"volume": 0.0},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["volume"] == 0.0
-
-    def test_boost_volume(self, adj_client):
-        c, _, clip_repo = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/volume",
-            json={"volume": 1.5},
-        )
-        assert resp.status_code == 200
-        assert resp.json()["volume"] == 1.5
-
-    def test_volume_out_of_range(self, adj_client):
-        c, _, _ = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/volume",
-            json={"volume": 3.0},
-        )
-        assert resp.status_code == 422
-
-    def test_volume_clip_not_found(self, adj_client):
-        c, _, _ = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-nonexist/volume",
-            json={"volume": 1.0},
-        )
-        assert resp.status_code == 404
-
-    def test_default_volume(self, adj_client):
-        c, _, _ = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/speed",
-            json={"speed": 1.0},
-        )
-        data = resp.json()
-        # 默认音量应该是 1.0
-        assert data["volume"] == 1.0
-
-
-# ---------------------------------------------------------------------------
-# 裁剪测试
-# ---------------------------------------------------------------------------
-
-
-class TestAdjustTrim:
-    def test_trim_start(self, adj_client):
-        c, _, clip_repo = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/trim",
-            json={"trim_start": 2.0, "trim_end": 0.0},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["trim_start"] == 2.0
-        assert data["trim_end"] == 0.0
-
-        clip = clip_repo.get("clip-001")
-        assert clip.config["trim_start"] == 2.0
-
-    def test_trim_both_ends(self, adj_client):
-        c, _, clip_repo = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/trim",
-            json={"trim_start": 1.5, "trim_end": 2.5},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["trim_start"] == 1.5
-        assert data["trim_end"] == 2.5
-
-    def test_trim_exceeds_duration(self, adj_client):
-        c, _, _ = adj_client
-        # 片段时长 10 秒，裁剪 8+3 = 11 > 10
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/trim",
-            json={"trim_start": 8.0, "trim_end": 3.0},
-        )
-        assert resp.status_code == 400
-        assert "不能大于等于片段总时长" in resp.json()["detail"]
-
-    def test_trim_clip_not_found(self, adj_client):
-        c, _, _ = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-nonexist/trim",
-            json={"trim_start": 1.0},
-        )
-        assert resp.status_code == 404
-
-    def test_default_trim_zero(self, adj_client):
-        c, _, _ = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/speed",
-            json={"speed": 1.0},
-        )
-        data = resp.json()
-        assert data["trim_start"] == 0.0
-        assert data["trim_end"] == 0.0
-
-
-# ---------------------------------------------------------------------------
-# 统一调整测试
-# ---------------------------------------------------------------------------
-
-
-class TestAdjustAll:
-    def test_adjust_speed_and_volume(self, adj_client):
-        c, _, clip_repo = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/adjustments",
-            json={"speed": 1.5, "volume": 0.8},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["speed"] == 1.5
-        assert data["volume"] == 0.8
-
-        clip = clip_repo.get("clip-001")
-        assert clip.playback_speed == 1.5
-        assert clip.config["volume"] == 0.8
-
-    def test_adjust_all_four(self, adj_client):
-        c, _, clip_repo = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/adjustments",
-            json={"speed": 2.0, "volume": 0.5, "trim_start": 1.0, "trim_end": 1.0},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["speed"] == 2.0
-        assert data["volume"] == 0.5
-        assert data["trim_start"] == 1.0
-        assert data["trim_end"] == 1.0
-
-        clip = clip_repo.get("clip-001")
-        assert clip.playback_speed == 2.0
-        assert clip.config["volume"] == 0.5
-        assert clip.config["trim_start"] == 1.0
-        assert clip.config["trim_end"] == 1.0
-
-    def test_adjust_empty_body(self, adj_client):
-        c, _, _ = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/adjustments",
-            json={},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        # 保持默认值
-        assert data["speed"] == 1.0
-        assert data["volume"] == 1.0
-
-    def test_adjust_trim_exceeds(self, adj_client):
-        c, _, _ = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/adjustments",
-            json={"trim_start": 9.0, "trim_end": 2.0},
-        )
-        assert resp.status_code == 400
-
-    def test_adjust_clip_not_found(self, adj_client):
-        c, _, _ = adj_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-nonexist/adjustments",
-            json={"speed": 1.5},
-        )
-        assert resp.status_code == 404
-
-
-# ---------------------------------------------------------------------------
-# 批量调速测试
-# ---------------------------------------------------------------------------
-
-
-class TestBatchSpeed:
-    def test_batch_speed_all(self, adj_client):
-        c, _, clip_repo = adj_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/clips/batch-speed",
-            json={"speed": 1.5},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["updated_count"] == 3
-        assert data["plan_id"] == "plan-001"
-
-        for cid in ["clip-001", "clip-002", "clip-003"]:
-            clip = clip_repo.get(cid)
-            assert clip.playback_speed == 1.5
-
-    def test_batch_speed_plan_not_found(self, adj_client):
-        c, _, _ = adj_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-nonexist/clips/batch-speed",
-            json={"speed": 2.0},
-        )
-        assert resp.status_code == 404
-
-    def test_batch_speed_invalid(self, adj_client):
-        c, _, _ = adj_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/clips/batch-speed",
-            json={"speed": 10.0},
-        )
-        assert resp.status_code == 422

tests/unit/test_edit_plan_clip_domain.py

@@ -0,0 +1,262 @@
+"""edit_plan_clip 领域模型单元测试."""
+
+from datetime import datetime, timezone
+
+import pytest
+from domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
+
+
+class TestEditPlanClipStatus:
+    """EditPlanClipStatus 枚举测试."""
+
+    def test_values(self):
+        assert EditPlanClipStatus.PENDING == "pending"
+        assert EditPlanClipStatus.READY == "ready"
+        assert EditPlanClipStatus.RENDERED == "rendered"
+        assert EditPlanClipStatus.FAILED == "failed"
+
+
+class TestEditPlanClipCreate:
+    """EditPlanClip.create 工厂方法测试."""
+
+    def test_create_with_required_fields(self):
+        clip = EditPlanClip.create(plan_id="plan_001", clip_type="video", order=1)
+        assert clip.id  # 自动生成的 UUID
+        assert len(clip.id) == 32  # hex 格式
+        assert clip.plan_id == "plan_001"
+        assert clip.clip_type == "video"
+        assert clip.order == 1
+        assert clip.status == EditPlanClipStatus.PENDING
+        assert clip.start_time == 0.0
+        assert clip.duration == 0.0
+        assert clip.transition_effect == "cut"
+        assert clip.playback_speed == 1.0
+        assert clip.config == {}
+
+    def test_create_with_all_fields(self):
+        clip = EditPlanClip.create(
+            plan_id="plan_002",
+            clip_type="audio",
+            order=2,
+            template_clip_config_id="tpl_001",
+            asset_id="asset_001",
+            text_content="测试文案",
+            start_time=5.0,
+            duration=10.0,
+            transition_effect="fade",
+            transition_duration=0.5,
+            playback_speed=1.5,
+            config={"key": "value"},
+        )
+        assert clip.plan_id == "plan_002"
+        assert clip.clip_type == "audio"
+        assert clip.order == 2
+        assert clip.template_clip_config_id == "tpl_001"
+        assert clip.asset_id == "asset_001"
+        assert clip.text_content == "测试文案"
+        assert clip.start_time == 5.0
+        assert clip.duration == 10.0
+        assert clip.transition_effect == "fade"
+        assert clip.transition_duration == 0.5
+        assert clip.playback_speed == 1.5
+        assert clip.config == {"key": "value"}
+
+    def test_create_strips_strings(self):
+        clip = EditPlanClip.create(
+            plan_id="  plan_003  ",
+            clip_type="  video  ",
+            order=1,
+            asset_id="  asset_001  ",
+            template_clip_config_id="  tpl_001  ",
+            text_content="  测试  ",
+            transition_effect="  fade  ",
+        )
+        assert clip.plan_id == "plan_003"
+        assert clip.clip_type == "video"
+        assert clip.asset_id == "asset_001"
+        assert clip.template_clip_config_id == "tpl_001"
+        assert clip.text_content == "测试"
+        assert clip.transition_effect == "fade"
+
+    def test_create_empty_plan_id_raises(self):
+        with pytest.raises(ValueError, match="plan_id"):
+            EditPlanClip.create(plan_id="", clip_type="video", order=1)
+
+    def test_create_whitespace_plan_id_raises(self):
+        with pytest.raises(ValueError, match="plan_id"):
+            EditPlanClip.create(plan_id="   ", clip_type="video", order=1)
+
+    def test_create_empty_clip_type_raises(self):
+        with pytest.raises(ValueError, match="clip_type"):
+            EditPlanClip.create(plan_id="plan_001", clip_type="", order=1)
+
+    def test_create_negative_start_time_raises(self):
+        with pytest.raises(ValueError, match="start_time"):
+            EditPlanClip.create(plan_id="p", clip_type="v", order=1, start_time=-1.0)
+
+    def test_create_negative_duration_raises(self):
+        with pytest.raises(ValueError, match="duration"):
+            EditPlanClip.create(plan_id="p", clip_type="v", order=1, duration=-5.0)
+
+    def test_create_zero_speed_clamps_to_1(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, playback_speed=0.0)
+        assert clip.playback_speed == 1.0
+
+    def test_create_negative_speed_clamps_to_1(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, playback_speed=-1.0)
+        assert clip.playback_speed == 1.0
+
+    def test_create_low_speed_clamps_to_min(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, playback_speed=0.1)
+        assert clip.playback_speed == 0.25
+
+    def test_create_high_speed_clamps_to_max(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, playback_speed=5.0)
+        assert clip.playback_speed == 4.0
+
+    def test_create_speed_at_boundary_values(self):
+        # 边界值应该保持不变
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, playback_speed=0.25)
+        assert clip.playback_speed == 0.25
+
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, playback_speed=4.0)
+        assert clip.playback_speed == 4.0
+
+    def test_create_negative_transition_duration_clamps_to_0(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, transition_duration=-1.0)
+        assert clip.transition_duration == 0.0
+
+    def test_create_empty_transition_effect_defaults_to_cut(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, transition_effect="")
+        assert clip.transition_effect == "cut"
+
+    def test_create_empty_asset_id_stays_empty(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, asset_id="")
+        assert clip.asset_id == ""
+
+    def test_create_none_config_defaults_to_empty_dict(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, config=None)
+        assert clip.config == {}
+
+    def test_create_ids_are_unique(self):
+        c1 = EditPlanClip.create(plan_id="p", clip_type="v", order=1)
+        c2 = EditPlanClip.create(plan_id="p", clip_type="v", order=2)
+        assert c1.id != c2.id
+
+    def test_create_timestamps_are_utc(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1)
+        assert clip.created_at.tzinfo is not None
+        assert clip.updated_at.tzinfo is not None
+
+
+class TestEditPlanClipStateMachine:
+    """状态机流转测试."""
+
+    @pytest.fixture
+    def pending_clip(self):
+        return EditPlanClip.create(plan_id="plan_001", clip_type="video", order=1)
+
+    def test_initial_status_is_pending(self, pending_clip):
+        assert pending_clip.status == EditPlanClipStatus.PENDING
+
+    def test_pending_to_ready(self, pending_clip):
+        pending_clip.mark_ready()
+        assert pending_clip.status == EditPlanClipStatus.READY
+
+    def test_pending_cannot_mark_rendered(self, pending_clip):
+        with pytest.raises(ValueError, match="只有 ready"):
+            pending_clip.mark_rendered()
+
+    def test_pending_cannot_mark_failed(self, pending_clip):
+        with pytest.raises(ValueError, match="只有 ready"):
+            pending_clip.mark_failed()
+
+    def test_ready_to_rendered(self, pending_clip):
+        pending_clip.mark_ready()
+        pending_clip.mark_rendered()
+        assert pending_clip.status == EditPlanClipStatus.RENDERED
+
+    def test_ready_to_failed(self, pending_clip):
+        pending_clip.mark_ready()
+        pending_clip.mark_failed()
+        assert pending_clip.status == EditPlanClipStatus.FAILED
+
+    def test_rendered_cannot_mark_ready_again(self, pending_clip):
+        pending_clip.mark_ready()
+        pending_clip.mark_rendered()
+        with pytest.raises(ValueError):
+            pending_clip.mark_ready()
+
+    def test_failed_cannot_mark_ready_again(self, pending_clip):
+        pending_clip.mark_ready()
+        pending_clip.mark_failed()
+        with pytest.raises(ValueError):
+            pending_clip.mark_ready()
+
+    def test_state_transition_updates_updated_at(self, pending_clip):
+        old_updated = pending_clip.updated_at
+        # 确保时间不同
+        import time
+
+        time.sleep(0.001)
+        pending_clip.mark_ready()
+        assert pending_clip.updated_at > old_updated
+
+
+class TestEditPlanClipAssignAsset:
+    """assign_asset 方法测试."""
+
+    def test_assign_asset(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1)
+        assert not clip.has_asset
+        clip.assign_asset("asset_001")
+        assert clip.asset_id == "asset_001"
+        assert clip.has_asset
+
+    def test_assign_asset_strips_whitespace(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1)
+        clip.assign_asset("  asset_001  ")
+        assert clip.asset_id == "asset_001"
+
+    def test_assign_empty_asset_raises(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1)
+        with pytest.raises(ValueError, match="asset_id"):
+            clip.assign_asset("")
+
+    def test_assign_whitespace_asset_raises(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1)
+        with pytest.raises(ValueError, match="asset_id"):
+            clip.assign_asset("   ")
+
+    def test_assign_updates_updated_at(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1)
+        old_updated = clip.updated_at
+        import time
+
+        time.sleep(0.001)
+        clip.assign_asset("asset_001")
+        assert clip.updated_at > old_updated
+
+
+class TestEditPlanClipProperties:
+    """属性方法测试."""
+
+    def test_end_time(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, start_time=5.0, duration=10.0)
+        assert clip.end_time == 15.0
+
+    def test_end_time_zero_duration(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, start_time=3.0, duration=0.0)
+        assert clip.end_time == 3.0
+
+    def test_has_asset_true(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, asset_id="a001")
+        assert clip.has_asset is True
+
+    def test_has_asset_false(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1)
+        assert clip.has_asset is False
+
+    def test_has_asset_empty_string(self):
+        clip = EditPlanClip.create(plan_id="p", clip_type="v", order=1, asset_id="")
+        assert clip.has_asset is False

tests/unit/test_edit_plan_cover_api.py

@@ -1,559 +0,0 @@
-"""
-封面管理 API 单元测试
-
-覆盖：
-- GET /{plan_id}/cover - 获取封面配置
-- PUT /{plan_id}/cover - 更新封面配置
-- POST /{plan_id}/cover/extract - 从片段抽帧
-- POST /{plan_id}/cover/smart - 智能选帧
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from datetime import datetime
-from pathlib import Path
-from typing import Optional
-from unittest.mock import MagicMock, patch
-
-os.environ.setdefault("JWT_SECRET_KEY", "unit-test-secret-key-for-testing")
-os.environ.setdefault("DATABASE_URL", "sqlite:///test.db")
-
-import pytest
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
-
-from fastapi import FastAPI
-from fastapi.testclient import TestClient
-
-from packages.domain.config_schemas import normalize_plan_config
-from packages.domain.edit_plan import EditPlan, EditPlanStatus
-from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
-
-# ---------------------------------------------------------------------------
-# Stub Repository
-# ---------------------------------------------------------------------------
-
-
-class StubEditPlanRepository:
-    def __init__(self, plans: dict[str, EditPlan] | None = None):
-        self._plans = plans or {}
-        self._counter = 100
-
-    def _next_id(self) -> str:
-        self._counter += 1
-        return f"plan-{self._counter:03d}"
-
-    def list_all(self, *, status=None, skip=0, limit=50):
-        items = list(self._plans.values())
-        if status is not None:
-            items = [p for p in items if p.status == status]
-        items.sort(key=lambda p: p.created_at, reverse=True)
-        return items[skip : skip + limit]
-
-    def list_by_template(self, template_id, *, status=None, skip=0, limit=50):
-        items = [p for p in self._plans.values() if p.template_id == template_id]
-        if status is not None:
-            items = [p for p in items if p.status == status]
-        items.sort(key=lambda p: p.created_at, reverse=True)
-        return items[skip : skip + limit]
-
-    def get(self, plan_id: str) -> Optional[EditPlan]:
-        return self._plans.get(plan_id)
-
-    def create(self, plan: EditPlan) -> EditPlan:
-        if not plan.id:
-            plan.id = self._next_id()
-        self._plans[plan.id] = plan
-        return plan
-
-    def update(self, plan: EditPlan) -> EditPlan:
-        self._plans[plan.id] = plan
-        return plan
-
-    def delete(self, plan_id: str) -> bool:
-        if plan_id in self._plans:
-            del self._plans[plan_id]
-            return True
-        return False
-
-    def count(self, *, status=None, template_id=None):
-        items = list(self._plans.values())
-        if status is not None:
-            items = [p for p in items if p.status == status]
-        if template_id is not None:
-            items = [p for p in items if p.template_id == template_id]
-        return len(items)
-
-
-class StubEditPlanClipRepository:
-    def __init__(self, clips: dict[str, EditPlanClip] | None = None):
-        self._clips = clips or {}
-        self._counter = 200
-
-    def _next_id(self) -> str:
-        self._counter += 1
-        return f"clip-{self._counter:03d}"
-
-    def list_by_plan(self, plan_id, *, status=None, skip=0, limit=100):
-        items = [c for c in self._clips.values() if c.plan_id == plan_id]
-        if status is not None:
-            items = [c for c in items if c.status == status]
-        items.sort(key=lambda c: c.order)
-        return items[skip : skip + limit]
-
-    def count(self, plan_id, *, status=None):
-        items = [c for c in self._clips.values() if c.plan_id == plan_id]
-        if status is not None:
-            items = [c for c in items if c.status == status]
-        return len(items)
-
-    def get(self, clip_id: str) -> Optional[EditPlanClip]:
-        return self._clips.get(clip_id)
-
-    def create(self, clip: EditPlanClip) -> EditPlanClip:
-        if not clip.id:
-            clip.id = self._next_id()
-        self._clips[clip.id] = clip
-        return clip
-
-    def update(self, clip: EditPlanClip) -> EditPlanClip:
-        self._clips[clip.id] = clip
-        return clip
-
-    def delete(self, clip_id: str) -> bool:
-        if clip_id in self._clips:
-            del self._clips[clip_id]
-            return True
-        return False
-
-    def delete_by_plan(self, plan_id: str) -> int:
-        to_delete = [cid for cid, c in self._clips.items() if c.plan_id == plan_id]
-        for cid in to_delete:
-            del self._clips[cid]
-        return len(to_delete)
-
-
-class StubAssetRepository:
-    def __init__(self, assets: dict | None = None):
-        self._assets = assets or {}
-
-    def get(self, asset_id: str):
-        return self._assets.get(asset_id)
-
-
-class StubStorageService:
-    def __init__(self):
-        self.uploaded = {}
-        self.downloaded = {}
-
-    def upload_file(self, file_or_path, storage_key, content_type="application/octet-stream"):
-        self.uploaded[storage_key] = file_or_path
-        return f"https://oss.example.com/{storage_key}"
-
-    def get_url(self, storage_key: str) -> str:
-        return f"https://oss.example.com/{storage_key}"
-
-    def download_file(self, storage_key: str, local_path: str):
-        self.downloaded[storage_key] = local_path
-        # 创建一个假文件（空文件也可以，因为抽帧会被 mock 掉）
-        Path(local_path).parent.mkdir(parents=True, exist_ok=True)
-        with open(local_path, "wb") as f:
-            f.write(b"fake video data for testing")
-
-
-# ---------------------------------------------------------------------------
-# Test Fixtures
-# ---------------------------------------------------------------------------
-
-
-def _make_sample_plan(plan_id="plan-001", config=None):
-    if config is None:
-        config = normalize_plan_config({})
-    return EditPlan(
-        id=plan_id,
-        template_id="tpl-001",
-        name="测试计划",
-        status=EditPlanStatus.EDITING,
-        total_duration=30.0,
-        config=config,
-        project_id="",
-        created_by_user_id="user-001",
-        created_at=datetime(2026, 7, 16, 10, 0, 0),
-        updated_at=datetime(2026, 7, 16, 10, 0, 0),
-    )
-
-
-def _make_sample_clip(clip_id="clip-001", plan_id="plan-001", asset_id="asset-001", clip_type="video"):
-    return EditPlanClip(
-        id=clip_id,
-        plan_id=plan_id,
-        clip_type=clip_type,
-        order=0,
-        asset_id=asset_id,
-        text_content="",
-        start_time=0.0,
-        duration=10.0,
-        transition_effect="none",
-        transition_duration=0.0,
-        playback_speed=1.0,
-        status=EditPlanClipStatus.READY,
-        config={},
-        created_at=datetime(2026, 7, 16, 10, 0, 0),
-        updated_at=datetime(2026, 7, 16, 10, 0, 0),
-    )
-
-
-def _create_test_app():
-    import app.api.routes.edit_plans_cover as cover_module
-    import app.services.edit_plan_service as service_module
-    from app.api.routes.edit_plans import router
-
-    # 创建 stub
-    plan = _make_sample_plan()
-    clip = _make_sample_clip()
-    stub_plan_repo = StubEditPlanRepository({plan.id: plan})
-    stub_clip_repo = StubEditPlanClipRepository({clip.id: clip})
-
-    # 替换服务模块中的 Repository 类
-    original_plan_repo = service_module.SQLAlchemyEditPlanRepository
-    original_clip_repo = service_module.SQLAlchemyEditPlanClipRepository
-    original_gen_repo = service_module.SQLAlchemyGenerationTaskRepository
-    service_module.SQLAlchemyEditPlanRepository = lambda db: stub_plan_repo
-    service_module.SQLAlchemyEditPlanClipRepository = lambda db: stub_clip_repo
-    service_module.SQLAlchemyGenerationTaskRepository = lambda db: MagicMock()
-
-    app = FastAPI()
-    app.include_router(router, prefix="/api/v1/edit-plans")
-
-    # Mock 认证
-    def _mock_auth():
-        mock = MagicMock()
-        mock.user.id = "user-001"
-        return mock
-
-    # Mock 项目访问检查
-    import app.api.routes._helpers as helpers_module
-
-    original_check = helpers_module.check_project_access
-    helpers_module.check_project_access = lambda *a, **kw: None
-
-    # 覆盖依赖
-    app.dependency_overrides[cover_module.get_current_user] = _mock_auth
-    app.dependency_overrides[cover_module.get_db_session] = lambda: MagicMock()
-    app.dependency_overrides[cover_module.get_project_repository] = lambda: MagicMock()
-
-    # Mock storage 和 asset repo
-    stub_storage = StubStorageService()
-    stub_asset_repo = StubAssetRepository(
-        {
-            "asset-001": MagicMock(
-                storage_key="videos/test.mp4",
-                mime_type="video/mp4",
-            ),
-            "asset-img": MagicMock(
-                storage_key="images/test.jpg",
-                mime_type="image/jpeg",
-            ),
-        }
-    )
-
-    app.dependency_overrides[cover_module.get_storage_service] = lambda: stub_storage
-    app.dependency_overrides[cover_module.get_asset_repository] = lambda: stub_asset_repo
-
-    # 也需要覆盖 edit_plans 主模块的 auth（用于其他路由）
-    from app.api.routes import edit_plans as main_module
-
-    app.dependency_overrides[main_module.get_current_user] = _mock_auth
-    app.dependency_overrides[main_module.get_db_session] = lambda: MagicMock()
-    app.dependency_overrides[main_module.get_project_repository] = lambda: MagicMock()
-
-    def cleanup():
-        service_module.SQLAlchemyEditPlanRepository = original_plan_repo
-        service_module.SQLAlchemyEditPlanClipRepository = original_clip_repo
-        service_module.SQLAlchemyGenerationTaskRepository = original_gen_repo
-        helpers_module.check_project_access = original_check
-
-    return app, stub_plan_repo, stub_clip_repo, stub_storage, cleanup
-
-
-@pytest.fixture
-def cover_client():
-    app, plan_repo, clip_repo, storage, cleanup = _create_test_app()
-    yield TestClient(app), plan_repo, clip_repo, storage
-    cleanup()
-
-
-# ---------------------------------------------------------------------------
-# GET /{plan_id}/cover 测试
-# ---------------------------------------------------------------------------
-
-
-class TestGetCover:
-    def test_get_default_cover(self, cover_client):
-        c, _, _, _ = cover_client
-        resp = c.get("/api/v1/edit-plans/plan-001/cover")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["type"] == "ai_frame"
-        assert data["image_url"] == ""
-        assert data["frame_time"] is None
-
-    def test_get_cover_not_found(self, cover_client):
-        c, _, _, _ = cover_client
-        resp = c.get("/api/v1/edit-plans/plan-nonexist/cover")
-        assert resp.status_code == 404
-
-    def test_get_cover_with_custom_config(self, cover_client):
-        c, plan_repo, _, _ = cover_client
-        # 更新 plan 的 cover 配置
-        plan = plan_repo.get("plan-001")
-        new_config = dict(plan.config)
-        new_config["cover"] = {"type": "manual", "image_url": "https://example.com/cover.jpg", "frame_time": 5.5}
-        plan.config = new_config
-        plan_repo.update(plan)
-
-        resp = c.get("/api/v1/edit-plans/plan-001/cover")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["type"] == "manual"
-        assert data["image_url"] == "https://example.com/cover.jpg"
-        assert data["frame_time"] == 5.5
-
-
-# ---------------------------------------------------------------------------
-# PUT /{plan_id}/cover 测试
-# ---------------------------------------------------------------------------
-
-
-class TestUpdateCover:
-    def test_update_cover_type_and_url(self, cover_client):
-        c, plan_repo, _, _ = cover_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/cover",
-            json={"type": "upload", "image_url": "https://example.com/uploaded.jpg"},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["type"] == "upload"
-        assert data["image_url"] == "https://example.com/uploaded.jpg"
-
-        # 验证存储
-        plan = plan_repo.get("plan-001")
-        assert plan.config["cover"]["type"] == "upload"
-        assert plan.config["cover"]["image_url"] == "https://example.com/uploaded.jpg"
-
-    def test_update_cover_frame_time(self, cover_client):
-        c, plan_repo, _, _ = cover_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/cover",
-            json={"type": "manual", "frame_time": 3.14},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["type"] == "manual"
-        assert data["frame_time"] == 3.14
-
-        plan = plan_repo.get("plan-001")
-        assert plan.config["cover"]["frame_time"] == 3.14
-
-    def test_update_cover_invalid_type(self, cover_client):
-        c, _, _, _ = cover_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/cover",
-            json={"type": "invalid_type"},
-        )
-        assert resp.status_code == 400
-
-    def test_update_cover_not_found(self, cover_client):
-        c, _, _, _ = cover_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-nonexist/cover",
-            json={"type": "upload", "image_url": "test.jpg"},
-        )
-        assert resp.status_code == 404
-
-    def test_update_cover_partial(self, cover_client):
-        """只更新 image_url，type 保持不变"""
-        c, plan_repo, _, _ = cover_client
-        # 先设置一个类型
-        c.put("/api/v1/edit-plans/plan-001/cover", json={"type": "manual", "frame_time": 2.0})
-
-        # 只更新 image_url
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/cover",
-            json={"image_url": "https://example.com/new.jpg"},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["type"] == "manual"  # 保持不变
-        assert data["image_url"] == "https://example.com/new.jpg"
-        assert data["frame_time"] == 2.0  # 保持不变
-
-
-# ---------------------------------------------------------------------------
-# POST /{plan_id}/cover/extract 测试
-# ---------------------------------------------------------------------------
-
-
-class TestExtractCover:
-    def test_extract_success(self, cover_client):
-        c, plan_repo, _, _ = cover_client
-        with patch("app.services.cover_service.CoverService._extract_frame") as mock_extract:
-            # mock ffmpeg 抽帧，直接创建输出文件
-            def fake_extract(video_path, output_path, **kwargs):
-                output_path.parent.mkdir(parents=True, exist_ok=True)
-                output_path.write_bytes(b"fake jpeg data")
-
-            mock_extract.side_effect = fake_extract
-
-            resp = c.post(
-                "/api/v1/edit-plans/plan-001/cover/extract",
-                json={"clip_id": "clip-001", "frame_time": 2.5},
-            )
-
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["type"] == "manual"
-        assert data["frame_time"] == 2.5
-        assert data["image_url"].startswith("https://oss.example.com/covers/")
-
-        # 验证 plan.config 已更新
-        plan = plan_repo.get("plan-001")
-        assert plan.config["cover"]["type"] == "manual"
-        assert plan.config["cover"]["frame_time"] == 2.5
-
-    def test_extract_clip_not_found(self, cover_client):
-        c, _, _, _ = cover_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/cover/extract",
-            json={"clip_id": "clip-nonexist", "frame_time": 1.0},
-        )
-        assert resp.status_code == 404
-
-    def test_extract_plan_not_found(self, cover_client):
-        c, _, _, _ = cover_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-nonexist/cover/extract",
-            json={"clip_id": "clip-001", "frame_time": 1.0},
-        )
-        assert resp.status_code == 404
-
-    def test_extract_clip_no_asset(self, cover_client):
-        c, _, clip_repo, _ = cover_client
-        # 创建一个没有 asset 的片段
-        empty_clip = _make_sample_clip(clip_id="clip-empty", asset_id="")
-        clip_repo.create(empty_clip)
-
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/cover/extract",
-            json={"clip_id": "clip-empty", "frame_time": 1.0},
-        )
-        assert resp.status_code == 400
-        assert "没有关联素材" in resp.json()["detail"]
-
-    def test_extract_clip_not_in_plan(self, cover_client):
-        c, _, clip_repo, _ = cover_client
-        # 创建属于另一个 plan 的片段
-        other_clip = _make_sample_clip(clip_id="clip-other", plan_id="plan-other")
-        clip_repo.create(other_clip)
-
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/cover/extract",
-            json={"clip_id": "clip-other", "frame_time": 1.0},
-        )
-        assert resp.status_code == 400
-        assert "不属于该剪辑计划" in resp.json()["detail"]
-
-    def test_extract_negative_frame_time(self, cover_client):
-        c, _, _, _ = cover_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/cover/extract",
-            json={"clip_id": "clip-001", "frame_time": -1.0},
-        )
-        assert resp.status_code == 422  # pydantic 校验失败
-
-
-# ---------------------------------------------------------------------------
-# POST /{plan_id}/cover/smart 测试
-# ---------------------------------------------------------------------------
-
-
-class TestSmartCover:
-    def test_smart_cover_with_clip_id(self, cover_client):
-        c, plan_repo, _, _ = cover_client
-        with patch("app.services.cover_service.CoverService._extract_frame") as mock_extract:
-
-            def fake_extract(video_path, output_path, **kwargs):
-                output_path.parent.mkdir(parents=True, exist_ok=True)
-                output_path.write_bytes(b"fake jpeg data")
-
-            mock_extract.side_effect = fake_extract
-
-            resp = c.post(
-                "/api/v1/edit-plans/plan-001/cover/smart",
-                json={"clip_id": "clip-001"},
-            )
-
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["type"] == "ai_frame"
-        assert data["image_url"].startswith("https://oss.example.com/covers/")
-
-        plan = plan_repo.get("plan-001")
-        assert plan.config["cover"]["type"] == "ai_frame"
-
-    def test_smart_cover_auto_pick_first_video(self, cover_client):
-        c, plan_repo, clip_repo, _ = cover_client
-        # 添加多个片段，第一个视频应该被选中
-        clip2 = _make_sample_clip(clip_id="clip-002", clip_type="audio", asset_id="asset-audio")
-        clip2.order = 1
-        clip_repo.create(clip2)
-
-        with patch("app.services.cover_service.CoverService._extract_frame") as mock_extract:
-
-            def fake_extract(video_path, output_path, **kwargs):
-                output_path.parent.mkdir(parents=True, exist_ok=True)
-                output_path.write_bytes(b"fake jpeg data")
-
-            mock_extract.side_effect = fake_extract
-
-            resp = c.post(
-                "/api/v1/edit-plans/plan-001/cover/smart",
-                json={},
-            )
-
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["type"] == "ai_frame"
-
-    def test_smart_cover_clip_not_found(self, cover_client):
-        c, _, _, _ = cover_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/cover/smart",
-            json={"clip_id": "clip-nonexist"},
-        )
-        assert resp.status_code == 404
-
-    def test_smart_cover_no_video_clips(self, cover_client):
-        c, _, clip_repo, _ = cover_client
-        # 删除原有片段，添加纯音频片段
-        clip_repo.delete("clip-001")
-        audio_clip = _make_sample_clip(clip_id="clip-audio", clip_type="audio", asset_id="asset-001")
-        clip_repo.create(audio_clip)
-
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/cover/smart",
-            json={},
-        )
-        assert resp.status_code == 400
-        assert "没有找到可用的视频片段" in resp.json()["detail"]
-
-    def test_smart_cover_plan_not_found(self, cover_client):
-        c, _, _, _ = cover_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-nonexist/cover/smart",
-            json={},
-        )
-        assert resp.status_code == 404

tests/unit/test_edit_plan_domain.py

@@ -0,0 +1,237 @@
+"""剪辑计划领域模型单元测试."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import pytest
+
+from packages.domain.edit_plan import EditPlan, EditPlanStatus
+
+
+class TestEditPlanStatus:
+    """EditPlanStatus 枚举测试."""
+
+    def test_status_values(self):
+        assert EditPlanStatus.DRAFT.value == "draft"
+        assert EditPlanStatus.EDITING.value == "editing"
+        assert EditPlanStatus.RENDERING.value == "rendering"
+        assert EditPlanStatus.COMPLETED.value == "completed"
+        assert EditPlanStatus.FAILED.value == "failed"
+
+    def test_status_is_str(self):
+        assert isinstance(EditPlanStatus.DRAFT, str)
+        assert EditPlanStatus.DRAFT == "draft"
+
+
+class TestEditPlanCreate:
+    """创建剪辑计划测试."""
+
+    def test_create_basic(self):
+        plan = EditPlan.create(template_id="tpl_001", name="测试计划")
+        assert plan.id
+        assert len(plan.id) == 32  # uuid4 hex
+        assert plan.template_id == "tpl_001"
+        assert plan.name == "测试计划"
+        assert plan.status == EditPlanStatus.DRAFT
+        assert plan.total_duration == 0.0
+        assert plan.config == {}
+        assert plan.source_edit_plan_id == ""
+        assert plan.project_id == ""
+        assert plan.created_by_user_id == ""
+
+    def test_create_with_all_fields(self):
+        plan = EditPlan.create(
+            template_id="tpl_001",
+            name="完整测试计划",
+            config={"key": "value"},
+            total_duration=60.5,
+            source_edit_plan_id="src_001",
+            project_id="proj_001",
+            created_by_user_id="user_001",
+        )
+        assert plan.name == "完整测试计划"
+        assert plan.total_duration == 60.5
+        assert plan.config == {"key": "value"}
+        assert plan.source_edit_plan_id == "src_001"
+        assert plan.project_id == "proj_001"
+        assert plan.created_by_user_id == "user_001"
+
+    def test_create_empty_name_raises(self):
+        with pytest.raises(ValueError, match="名称不能为空"):
+            EditPlan.create(template_id="tpl_001", name="")
+
+    def test_create_whitespace_name_raises(self):
+        with pytest.raises(ValueError, match="名称不能为空"):
+            EditPlan.create(template_id="tpl_001", name="   ")
+
+    def test_create_empty_template_id_raises(self):
+        with pytest.raises(ValueError, match="template_id 不能为空"):
+            EditPlan.create(template_id="", name="测试")
+
+    def test_create_whitespace_template_id_raises(self):
+        with pytest.raises(ValueError, match="template_id 不能为空"):
+            EditPlan.create(template_id="   ", name="测试")
+
+    def test_create_name_stripped(self):
+        plan = EditPlan.create(template_id="tpl_001", name="  我的计划  ")
+        assert plan.name == "我的计划"
+
+    def test_create_template_id_stripped(self):
+        plan = EditPlan.create(template_id="  tpl_001  ", name="测试")
+        assert plan.template_id == "tpl_001"
+
+    def test_create_timestamps_set(self):
+        before = datetime.now(timezone.utc)
+        plan = EditPlan.create(template_id="tpl_001", name="测试")
+        after = datetime.now(timezone.utc)
+        assert before <= plan.created_at <= after
+        assert before <= plan.updated_at <= after
+
+    def test_create_config_none_defaults_to_empty(self):
+        plan = EditPlan.create(template_id="tpl_001", name="测试", config=None)
+        assert plan.config == {}
+
+
+class TestEditPlanStateMachine:
+    """状态机流转测试."""
+
+    def _make_plan(self, status: EditPlanStatus) -> EditPlan:
+        return EditPlan(
+            id="test_id",
+            template_id="tpl_001",
+            name="测试计划",
+            status=status,
+        )
+
+    def test_draft_to_editing(self):
+        plan = self._make_plan(EditPlanStatus.DRAFT)
+        plan.start_editing()
+        assert plan.status == EditPlanStatus.EDITING
+        assert plan.updated_at > plan.created_at
+
+    def test_editing_to_rendering(self):
+        plan = self._make_plan(EditPlanStatus.EDITING)
+        plan.start_rendering()
+        assert plan.status == EditPlanStatus.RENDERING
+
+    def test_rendering_to_completed(self):
+        plan = self._make_plan(EditPlanStatus.RENDERING)
+        plan.mark_completed()
+        assert plan.status == EditPlanStatus.COMPLETED
+
+    def test_rendering_to_failed(self):
+        plan = self._make_plan(EditPlanStatus.RENDERING)
+        plan.mark_failed()
+        assert plan.status == EditPlanStatus.FAILED
+
+    def test_completed_to_editing_resume(self):
+        plan = self._make_plan(EditPlanStatus.COMPLETED)
+        plan.resume_editing()
+        assert plan.status == EditPlanStatus.EDITING
+
+    def test_failed_to_editing_resume(self):
+        plan = self._make_plan(EditPlanStatus.FAILED)
+        plan.resume_editing()
+        assert plan.status == EditPlanStatus.EDITING
+
+    def test_failed_to_draft_reset(self):
+        plan = self._make_plan(EditPlanStatus.FAILED)
+        plan.reset_to_draft()
+        assert plan.status == EditPlanStatus.DRAFT
+
+    def test_invalid_start_editing_from_editing(self):
+        plan = self._make_plan(EditPlanStatus.EDITING)
+        with pytest.raises(ValueError, match="只有 draft 状态"):
+            plan.start_editing()
+
+    def test_invalid_start_editing_from_rendering(self):
+        plan = self._make_plan(EditPlanStatus.RENDERING)
+        with pytest.raises(ValueError):
+            plan.start_editing()
+
+    def test_invalid_start_rendering_from_draft(self):
+        plan = self._make_plan(EditPlanStatus.DRAFT)
+        with pytest.raises(ValueError, match="只有 editing 状态"):
+            plan.start_rendering()
+
+    def test_invalid_start_rendering_from_completed(self):
+        plan = self._make_plan(EditPlanStatus.COMPLETED)
+        with pytest.raises(ValueError):
+            plan.start_rendering()
+
+    def test_invalid_mark_completed_from_draft(self):
+        plan = self._make_plan(EditPlanStatus.DRAFT)
+        with pytest.raises(ValueError, match="只有 rendering 状态"):
+            plan.mark_completed()
+
+    def test_invalid_mark_failed_from_editing(self):
+        plan = self._make_plan(EditPlanStatus.EDITING)
+        with pytest.raises(ValueError):
+            plan.mark_failed()
+
+    def test_invalid_resume_editing_from_draft(self):
+        plan = self._make_plan(EditPlanStatus.DRAFT)
+        with pytest.raises(ValueError, match="只有 completed/failed 状态"):
+            plan.resume_editing()
+
+    def test_invalid_resume_editing_from_rendering(self):
+        plan = self._make_plan(EditPlanStatus.RENDERING)
+        with pytest.raises(ValueError):
+            plan.resume_editing()
+
+    def test_invalid_reset_to_draft_from_draft(self):
+        plan = self._make_plan(EditPlanStatus.DRAFT)
+        with pytest.raises(ValueError, match="只有 failed 状态"):
+            plan.reset_to_draft()
+
+    def test_invalid_reset_to_draft_from_completed(self):
+        plan = self._make_plan(EditPlanStatus.COMPLETED)
+        with pytest.raises(ValueError):
+            plan.reset_to_draft()
+
+    def test_state_transition_updates_updated_at(self):
+        plan = self._make_plan(EditPlanStatus.DRAFT)
+        old_updated = plan.updated_at
+        plan.start_editing()
+        assert plan.updated_at >= old_updated
+
+
+class TestEditPlanDataclass:
+    """数据类属性测试."""
+
+    def test_slots_prevents_dynamic_attributes(self):
+        plan = EditPlan(id="1", template_id="t1", name="test")
+        with pytest.raises(AttributeError):
+            plan.new_field = "value"
+
+    def test_full_flow_draft_editing_rendering_completed(self):
+        """完整流程：草稿 → 编辑 → 渲染 → 完成."""
+        plan = EditPlan.create(template_id="tpl_001", name="完整流程")
+        assert plan.status == EditPlanStatus.DRAFT
+
+        plan.start_editing()
+        assert plan.status == EditPlanStatus.EDITING
+
+        plan.start_rendering()
+        assert plan.status == EditPlanStatus.RENDERING
+
+        plan.mark_completed()
+        assert plan.status == EditPlanStatus.COMPLETED
+
+    def test_full_flow_draft_editing_rendering_failed_reset(self):
+        """完整流程：草稿 → 编辑 → 渲染 → 失败 → 重置 → 编辑 → 渲染 → 完成."""
+        plan = EditPlan.create(template_id="tpl_001", name="失败重试流程")
+
+        plan.start_editing()
+        plan.start_rendering()
+        plan.mark_failed()
+        assert plan.status == EditPlanStatus.FAILED
+
+        plan.reset_to_draft()
+        assert plan.status == EditPlanStatus.DRAFT
+
+        plan.start_editing()
+        plan.start_rendering()
+        plan.mark_completed()
+        assert plan.status == EditPlanStatus.COMPLETED

tests/unit/test_edit_plan_export_api.py

@@ -1,350 +0,0 @@
-"""
-导出设置 API 单元测试
-
-覆盖：
-- GET /export-presets - 导出预设列表
-- GET /{plan_id}/export - 获取导出配置
-- PUT /{plan_id}/export - 更新导出配置
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from datetime import datetime
-from pathlib import Path
-from typing import Optional
-from unittest.mock import MagicMock
-
-os.environ.setdefault("JWT_SECRET_KEY", "unit-test-secret-key-for-testing")
-os.environ.setdefault("DATABASE_URL", "sqlite:///test.db")
-
-import pytest
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
-
-from fastapi import FastAPI
-from fastapi.testclient import TestClient
-
-from packages.domain.config_schemas import normalize_plan_config
-from packages.domain.edit_plan import EditPlan, EditPlanStatus
-
-# ---------------------------------------------------------------------------
-# Stub Repository
-# ---------------------------------------------------------------------------
-
-
-class StubEditPlanRepository:
-    def __init__(self, plans: dict[str, EditPlan] | None = None):
-        self._plans = plans or {}
-
-    def get(self, plan_id: str) -> Optional[EditPlan]:
-        return self._plans.get(plan_id)
-
-    def create(self, plan: EditPlan) -> EditPlan:
-        self._plans[plan.id] = plan
-        return plan
-
-    def update(self, plan: EditPlan) -> EditPlan:
-        self._plans[plan.id] = plan
-        return plan
-
-    def list_all(self, *, status=None, skip=0, limit=50):
-        return list(self._plans.values())[skip : skip + limit]
-
-    def list_by_template(self, template_id, *, status=None, skip=0, limit=50):
-        return [p for p in self._plans.values() if p.template_id == template_id][skip : skip + limit]
-
-    def delete(self, plan_id: str) -> bool:
-        return self._plans.pop(plan_id, None) is not None
-
-    def count(self, *, status=None, template_id=None):
-        return len(self._plans)
-
-
-class StubEditPlanClipRepository:
-    def list_by_plan(self, plan_id, *, status=None, skip=0, limit=100):
-        return []
-
-    def count(self, plan_id, *, status=None):
-        return 0
-
-    def get(self, clip_id: str):
-        return None
-
-    def create(self, clip):
-        return clip
-
-    def update(self, clip):
-        return clip
-
-    def delete(self, clip_id: str) -> bool:
-        return False
-
-    def delete_by_plan(self, plan_id: str) -> int:
-        return 0
-
-
-# ---------------------------------------------------------------------------
-# Test Fixtures
-# ---------------------------------------------------------------------------
-
-
-def _make_sample_plan(plan_id="plan-001"):
-    return EditPlan(
-        id=plan_id,
-        template_id="tpl-001",
-        name="测试计划",
-        status=EditPlanStatus.EDITING,
-        total_duration=30.0,
-        config=normalize_plan_config({}),
-        project_id="",
-        created_by_user_id="user-001",
-        created_at=datetime(2026, 7, 16, 10, 0, 0),
-        updated_at=datetime(2026, 7, 16, 10, 0, 0),
-    )
-
-
-def _create_test_app():
-    import app.services.edit_plan_service as service_module
-    from app.api.routes.edit_plans import router
-
-    plan = _make_sample_plan()
-    stub_plan_repo = StubEditPlanRepository({plan.id: plan})
-    stub_clip_repo = StubEditPlanClipRepository()
-
-    original_plan_repo = service_module.SQLAlchemyEditPlanRepository
-    original_clip_repo = service_module.SQLAlchemyEditPlanClipRepository
-    original_gen_repo = service_module.SQLAlchemyGenerationTaskRepository
-    service_module.SQLAlchemyEditPlanRepository = lambda db: stub_plan_repo
-    service_module.SQLAlchemyEditPlanClipRepository = lambda db: stub_clip_repo
-    service_module.SQLAlchemyGenerationTaskRepository = lambda db: MagicMock()
-
-    app = FastAPI()
-    app.include_router(router, prefix="/api/v1/edit-plans")
-
-    def _mock_auth():
-        mock = MagicMock()
-        mock.user.id = "user-001"
-        return mock
-
-    import app.api.routes._helpers as helpers_module
-
-    original_check = helpers_module.check_project_access
-    helpers_module.check_project_access = lambda *a, **kw: None
-
-    from app.api.routes import edit_plans as main_module
-
-    app.dependency_overrides[main_module.get_current_user] = _mock_auth
-    app.dependency_overrides[main_module.get_db_session] = lambda: MagicMock()
-    app.dependency_overrides[main_module.get_project_repository] = lambda: MagicMock()
-
-    import app.api.routes.edit_plans_export as export_module
-
-    app.dependency_overrides[export_module.get_current_user] = _mock_auth
-    app.dependency_overrides[export_module.get_db_session] = lambda: MagicMock()
-    app.dependency_overrides[export_module.get_project_repository] = lambda: MagicMock()
-
-    def cleanup():
-        service_module.SQLAlchemyEditPlanRepository = original_plan_repo
-        service_module.SQLAlchemyEditPlanClipRepository = original_clip_repo
-        service_module.SQLAlchemyGenerationTaskRepository = original_gen_repo
-        helpers_module.check_project_access = original_check
-
-    return app, stub_plan_repo, cleanup
-
-
-@pytest.fixture
-def export_client():
-    app, plan_repo, cleanup = _create_test_app()
-    yield TestClient(app), plan_repo
-    cleanup()
-
-
-# ---------------------------------------------------------------------------
-# Export Presets 测试
-# ---------------------------------------------------------------------------
-
-
-class TestExportPresets:
-    def test_list_all_presets(self, export_client):
-        c, _ = export_client
-        resp = c.get("/api/v1/edit-plans/export-presets")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] >= 5
-        assert len(data["items"]) == data["total"]
-        first = data["items"][0]
-        assert "id" in first
-        assert "name" in first
-        assert "resolution" in first
-        assert "fps" in first
-        assert "video_bitrate" in first
-        assert "format" in first
-        assert "description" in first
-        assert "size_hint" in first
-
-    def test_preset_has_valid_resolution(self, export_client):
-        c, _ = export_client
-        resp = c.get("/api/v1/edit-plans/export-presets")
-        data = resp.json()
-        for item in data["items"]:
-            assert "x" in item["resolution"]
-            assert item["fps"] >= 15
-            assert item["fps"] <= 60
-            assert item["format"] in ("mp4", "mov")
-
-
-# ---------------------------------------------------------------------------
-# GET /{plan_id}/export 测试
-# ---------------------------------------------------------------------------
-
-
-class TestGetExportConfig:
-    def test_default_export_config(self, export_client):
-        c, _ = export_client
-        resp = c.get("/api/v1/edit-plans/plan-001/export")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["resolution"] == "1080x1920"
-        assert data["fps"] == 30
-        assert data["video_bitrate"] == 8000
-        assert data["audio_bitrate"] == 128
-        assert data["format"] == "mp4"
-        assert data["quality_preset"] == "balanced"
-        assert data["watermark_enabled"] is False
-        assert data["watermark_text"] == ""
-
-    def test_export_not_found(self, export_client):
-        c, _ = export_client
-        resp = c.get("/api/v1/edit-plans/plan-nonexist/export")
-        assert resp.status_code == 404
-
-
-# ---------------------------------------------------------------------------
-# PUT /{plan_id}/export 测试
-# ---------------------------------------------------------------------------
-
-
-class TestUpdateExportConfig:
-    def test_update_resolution_and_fps(self, export_client):
-        c, plan_repo = export_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/export",
-            json={"resolution": "720x1280", "fps": 60},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["resolution"] == "720x1280"
-        assert data["fps"] == 60
-
-        plan = plan_repo.get("plan-001")
-        assert plan.config["export"]["resolution"] == "720x1280"
-        assert plan.config["export"]["fps"] == 60
-
-    def test_update_bitrate(self, export_client):
-        c, plan_repo = export_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/export",
-            json={"video_bitrate": 12000, "audio_bitrate": 192},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["video_bitrate"] == 12000
-        assert data["audio_bitrate"] == 192
-
-    def test_update_format(self, export_client):
-        c, _ = export_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/export",
-            json={"format": "mov"},
-        )
-        assert resp.status_code == 200
-        assert resp.json()["format"] == "mov"
-
-    def test_invalid_format(self, export_client):
-        c, _ = export_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/export",
-            json={"format": "avi"},
-        )
-        assert resp.status_code == 422
-
-    def test_update_quality_preset(self, export_client):
-        c, _ = export_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/export",
-            json={"quality_preset": "best"},
-        )
-        assert resp.status_code == 200
-        assert resp.json()["quality_preset"] == "best"
-
-    def test_invalid_quality_preset(self, export_client):
-        c, _ = export_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/export",
-            json={"quality_preset": "ultimate"},
-        )
-        assert resp.status_code == 422
-
-    def test_update_watermark(self, export_client):
-        c, plan_repo = export_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/export",
-            json={"watermark_enabled": True, "watermark_text": "我的视频"},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["watermark_enabled"] is True
-        assert data["watermark_text"] == "我的视频"
-
-        plan = plan_repo.get("plan-001")
-        assert plan.config["export"]["watermark_enabled"] is True
-        assert plan.config["export"]["watermark_text"] == "我的视频"
-
-    def test_invalid_resolution_format(self, export_client):
-        c, _ = export_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/export",
-            json={"resolution": "1080*1920"},
-        )
-        assert resp.status_code == 422
-
-    def test_resolution_too_large(self, export_client):
-        c, _ = export_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/export",
-            json={"resolution": "8000x8000"},
-        )
-        assert resp.status_code == 422
-
-    def test_fps_out_of_range(self, export_client):
-        c, _ = export_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/export",
-            json={"fps": 120},
-        )
-        assert resp.status_code == 422
-
-    def test_export_not_found(self, export_client):
-        c, _ = export_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-nonexist/export",
-            json={"fps": 30},
-        )
-        assert resp.status_code == 404
-
-    def test_partial_update_preserves_other_fields(self, export_client):
-        c, _ = export_client
-        # 先修改一个
-        c.put("/api/v1/edit-plans/plan-001/export", json={"resolution": "720x1280"})
-        # 再修改另一个
-        resp = c.put("/api/v1/edit-plans/plan-001/export", json={"fps": 60})
-        data = resp.json()
-        # 分辨率应该保持
-        assert data["resolution"] == "720x1280"
-        # fps 更新了
-        assert data["fps"] == 60
-        # 其他默认值不变
-        assert data["format"] == "mp4"
-        assert data["video_bitrate"] == 8000

tests/unit/test_edit_plan_filter_api.py

@@ -1,476 +0,0 @@
-"""
-滤镜调色 API 单元测试
-
-覆盖：
-- GET /filter-presets - 滤镜预设列表
-- GET /{plan_id}/filter - 获取滤镜配置
-- PUT /{plan_id}/filter - 更新滤镜配置
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from datetime import datetime
-from pathlib import Path
-from typing import Optional
-from unittest.mock import MagicMock
-
-os.environ.setdefault("JWT_SECRET_KEY", "unit-test-secret-key-for-testing")
-os.environ.setdefault("DATABASE_URL", "sqlite:///test.db")
-
-import pytest
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
-
-from fastapi import FastAPI
-from fastapi.testclient import TestClient
-
-from packages.domain.config_schemas import normalize_plan_config
-from packages.domain.edit_plan import EditPlan, EditPlanStatus
-from packages.domain.filter_presets import FILTER_PRESET_LIBRARY, build_ffmpeg_filter
-
-# ---------------------------------------------------------------------------
-# Stub Repository
-# ---------------------------------------------------------------------------
-
-
-class StubEditPlanRepository:
-    def __init__(self, plans: dict[str, EditPlan] | None = None):
-        self._plans = plans or {}
-
-    def list_all(self, *, status=None, skip=0, limit=50):
-        items = list(self._plans.values())
-        if status is not None:
-            items = [p for p in items if p.status == status]
-        items.sort(key=lambda p: p.created_at, reverse=True)
-        return items[skip : skip + limit]
-
-    def list_by_template(self, template_id, *, status=None, skip=0, limit=50):
-        items = [p for p in self._plans.values() if p.template_id == template_id]
-        if status is not None:
-            items = [p for p in items if p.status == status]
-        items.sort(key=lambda p: p.created_at, reverse=True)
-        return items[skip : skip + limit]
-
-    def get(self, plan_id: str) -> Optional[EditPlan]:
-        return self._plans.get(plan_id)
-
-    def create(self, plan: EditPlan) -> EditPlan:
-        self._plans[plan.id] = plan
-        return plan
-
-    def update(self, plan: EditPlan) -> EditPlan:
-        self._plans[plan.id] = plan
-        return plan
-
-    def delete(self, plan_id: str) -> bool:
-        if plan_id in self._plans:
-            del self._plans[plan_id]
-            return True
-        return False
-
-    def count(self, *, status=None, template_id=None):
-        items = list(self._plans.values())
-        if status is not None:
-            items = [p for p in items if p.status == status]
-        if template_id is not None:
-            items = [p for p in items if p.template_id == template_id]
-        return len(items)
-
-
-class StubEditPlanClipRepository:
-    def list_by_plan(self, plan_id, *, status=None, skip=0, limit=100):
-        return []
-
-    def count(self, plan_id, *, status=None):
-        return 0
-
-    def get(self, clip_id: str):
-        return None
-
-    def create(self, clip):
-        return clip
-
-    def update(self, clip):
-        return clip
-
-    def delete(self, clip_id: str) -> bool:
-        return False
-
-    def delete_by_plan(self, plan_id: str) -> int:
-        return 0
-
-
-# ---------------------------------------------------------------------------
-# Test Fixtures
-# ---------------------------------------------------------------------------
-
-
-def _make_sample_plan(plan_id="plan-001", config=None):
-    if config is None:
-        config = normalize_plan_config({})
-    return EditPlan(
-        id=plan_id,
-        template_id="tpl-001",
-        name="测试计划",
-        status=EditPlanStatus.EDITING,
-        total_duration=30.0,
-        config=config,
-        project_id="",
-        created_by_user_id="user-001",
-        created_at=datetime(2026, 7, 16, 10, 0, 0),
-        updated_at=datetime(2026, 7, 16, 10, 0, 0),
-    )
-
-
-def _create_test_app():
-    import app.api.routes.edit_plans_filter as filter_module
-    import app.services.edit_plan_service as service_module
-    from app.api.routes.edit_plans import router
-
-    plan = _make_sample_plan()
-    stub_plan_repo = StubEditPlanRepository({plan.id: plan})
-    stub_clip_repo = StubEditPlanClipRepository()
-
-    original_plan_repo = service_module.SQLAlchemyEditPlanRepository
-    original_clip_repo = service_module.SQLAlchemyEditPlanClipRepository
-    original_gen_repo = service_module.SQLAlchemyGenerationTaskRepository
-    service_module.SQLAlchemyEditPlanRepository = lambda db: stub_plan_repo
-    service_module.SQLAlchemyEditPlanClipRepository = lambda db: stub_clip_repo
-    service_module.SQLAlchemyGenerationTaskRepository = lambda db: MagicMock()
-
-    app = FastAPI()
-    app.include_router(router, prefix="/api/v1/edit-plans")
-
-    # Mock 认证
-    def _mock_auth():
-        mock = MagicMock()
-        mock.user.id = "user-001"
-        return mock
-
-    # Mock 项目访问检查
-    import app.api.routes._helpers as helpers_module
-
-    original_check = helpers_module.check_project_access
-    helpers_module.check_project_access = lambda *a, **kw: None
-
-    # 主路由的依赖覆盖
-    from app.api.routes import edit_plans as main_module
-
-    app.dependency_overrides[main_module.get_current_user] = _mock_auth
-    app.dependency_overrides[main_module.get_db_session] = lambda: MagicMock()
-    app.dependency_overrides[main_module.get_project_repository] = lambda: MagicMock()
-
-    # 滤镜路由的依赖覆盖
-    app.dependency_overrides[filter_module.get_current_user] = _mock_auth
-    app.dependency_overrides[filter_module.get_db_session] = lambda: MagicMock()
-    app.dependency_overrides[filter_module.get_project_repository] = lambda: MagicMock()
-
-    def cleanup():
-        service_module.SQLAlchemyEditPlanRepository = original_plan_repo
-        service_module.SQLAlchemyEditPlanClipRepository = original_clip_repo
-        service_module.SQLAlchemyGenerationTaskRepository = original_gen_repo
-        helpers_module.check_project_access = original_check
-
-    return app, stub_plan_repo, cleanup
-
-
-@pytest.fixture
-def filter_client():
-    app, plan_repo, cleanup = _create_test_app()
-    yield TestClient(app), plan_repo
-    cleanup()
-
-
-# ---------------------------------------------------------------------------
-# Filter Presets 测试
-# ---------------------------------------------------------------------------
-
-
-class TestFilterPresets:
-    def test_list_all_presets(self, filter_client):
-        c, _ = filter_client
-        resp = c.get("/api/v1/edit-plans/filter-presets")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] == len(FILTER_PRESET_LIBRARY)
-        assert data["total"] > 10
-        assert len(data["items"]) == data["total"]
-        # 验证字段
-        first = data["items"][0]
-        assert "id" in first
-        assert "name" in first
-        assert "category" in first
-        assert "description" in first
-        assert "tags" in first
-
-    def test_filter_by_category_basic(self, filter_client):
-        c, _ = filter_client
-        resp = c.get("/api/v1/edit-plans/filter-presets?category=basic")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] > 0
-        for item in data["items"]:
-            assert item["category"] == "basic"
-
-    def test_filter_by_category_bw(self, filter_client):
-        c, _ = filter_client
-        resp = c.get("/api/v1/edit-plans/filter-presets?category=bw")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] >= 3
-        for item in data["items"]:
-            assert item["category"] == "bw"
-
-    def test_filter_by_keyword(self, filter_client):
-        c, _ = filter_client
-        resp = c.get("/api/v1/edit-plans/filter-presets?keyword=电影")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] > 0
-        # 至少包含电影感滤镜
-        names = [item["name"] for item in data["items"]]
-        assert any("电影" in n for n in names)
-
-    def test_filter_by_keyword_japanese(self, filter_client):
-        c, _ = filter_client
-        resp = c.get("/api/v1/edit-plans/filter-presets?keyword=日系")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] >= 1
-        assert data["items"][0]["name"] == "日系"
-
-    def test_filter_empty_result(self, filter_client):
-        c, _ = filter_client
-        resp = c.get("/api/v1/edit-plans/filter-presets?keyword=不存在的滤镜")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] == 0
-        assert data["items"] == []
-
-    def test_filter_invalid_category(self, filter_client):
-        c, _ = filter_client
-        resp = c.get("/api/v1/edit-plans/filter-presets?category=nonexistent")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] == 0
-
-
-# ---------------------------------------------------------------------------
-# GET /{plan_id}/filter 测试
-# ---------------------------------------------------------------------------
-
-
-class TestGetFilter:
-    def test_get_default_filter(self, filter_client):
-        c, _ = filter_client
-        resp = c.get("/api/v1/edit-plans/plan-001/filter")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["enabled"] is False
-        assert data["preset_id"] == "filter_none"
-        assert data["intensity"] == 100
-        assert data["brightness"] == 0.0
-        assert data["contrast"] == 1.0
-        assert data["saturation"] == 1.0
-        assert data["warmth"] == 0.0
-
-    def test_get_filter_not_found(self, filter_client):
-        c, _ = filter_client
-        resp = c.get("/api/v1/edit-plans/plan-nonexist/filter")
-        assert resp.status_code == 404
-
-    def test_get_filter_with_custom_config(self, filter_client):
-        c, plan_repo = filter_client
-        plan = plan_repo.get("plan-001")
-        new_config = dict(plan.config)
-        new_config["filter"] = {
-            "enabled": True,
-            "preset_id": "filter_cinematic",
-            "intensity": 80,
-            "brightness": 0.1,
-            "contrast": 1.2,
-            "saturation": 0.9,
-            "warmth": 0.3,
-        }
-        plan.config = new_config
-        plan_repo.update(plan)
-
-        resp = c.get("/api/v1/edit-plans/plan-001/filter")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["enabled"] is True
-        assert data["preset_id"] == "filter_cinematic"
-        assert data["intensity"] == 80
-        assert data["brightness"] == 0.1
-
-
-# ---------------------------------------------------------------------------
-# PUT /{plan_id}/filter 测试
-# ---------------------------------------------------------------------------
-
-
-class TestUpdateFilter:
-    def test_enable_filter(self, filter_client):
-        c, plan_repo = filter_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/filter",
-            json={"enabled": True, "preset_id": "filter_cinematic"},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["enabled"] is True
-        assert data["preset_id"] == "filter_cinematic"
-
-        plan = plan_repo.get("plan-001")
-        assert plan.config["filter"]["enabled"] is True
-        assert plan.config["filter"]["preset_id"] == "filter_cinematic"
-
-    def test_adjust_intensity(self, filter_client):
-        c, plan_repo = filter_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/filter",
-            json={"enabled": True, "preset_id": "filter_cinematic", "intensity": 50},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["intensity"] == 50
-
-        plan = plan_repo.get("plan-001")
-        assert plan.config["filter"]["intensity"] == 50
-
-    def test_invalid_intensity_returns_422(self, filter_client):
-        c, _ = filter_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/filter",
-            json={"intensity": 150},
-        )
-        assert resp.status_code == 422
-
-    def test_invalid_preset_returns_400(self, filter_client):
-        c, _ = filter_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/filter",
-            json={"preset_id": "nonexistent_filter"},
-        )
-        assert resp.status_code == 400
-        assert "无效的滤镜预设" in resp.json()["detail"]
-
-    def test_filter_not_found(self, filter_client):
-        c, _ = filter_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-nonexist/filter",
-            json={"enabled": True},
-        )
-        assert resp.status_code == 404
-
-    def test_set_none_preset_disables_filter(self, filter_client):
-        c, plan_repo = filter_client
-        # 先启用一个滤镜
-        c.put(
-            "/api/v1/edit-plans/plan-001/filter",
-            json={"enabled": True, "preset_id": "filter_cinematic"},
-        )
-
-        # 再设为原图
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/filter",
-            json={"preset_id": "filter_none"},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["preset_id"] == "filter_none"
-        assert data["enabled"] is False  # 原图自动关闭
-
-    def test_partial_update(self, filter_client):
-        c, plan_repo = filter_client
-        # 先设置完整配置
-        c.put(
-            "/api/v1/edit-plans/plan-001/filter",
-            json={
-                "enabled": True,
-                "preset_id": "filter_warm",
-                "intensity": 70,
-                "brightness": 0.05,
-            },
-        )
-
-        # 只修改强度，其他保持不变
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/filter",
-            json={"intensity": 90},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["intensity"] == 90
-        assert data["preset_id"] == "filter_warm"  # 保持不变
-        assert data["enabled"] is True  # 保持不变
-        assert data["brightness"] == 0.05  # 保持不变
-
-    def test_custom_adjustments(self, filter_client):
-        c, _ = filter_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/filter",
-            json={
-                "enabled": True,
-                "preset_id": "filter_cinematic",
-                "brightness": 0.1,
-                "contrast": 1.3,
-                "saturation": 1.2,
-                "warmth": 0.2,
-            },
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["brightness"] == 0.1
-        assert data["contrast"] == 1.3
-        assert data["saturation"] == 1.2
-        assert data["warmth"] == 0.2
-
-    def test_invalid_brightness_returns_422(self, filter_client):
-        c, _ = filter_client
-        resp = c.put(
-            "/api/v1/edit-plans/plan-001/filter",
-            json={"brightness": 2.0},
-        )
-        assert resp.status_code == 422
-
-
-# ---------------------------------------------------------------------------
-# FFmpeg 滤镜生成测试
-# ---------------------------------------------------------------------------
-
-
-class TestBuildFFmpegFilter:
-    def test_no_filter(self):
-        assert build_ffmpeg_filter("filter_none", 100) == ""
-
-    def test_zero_intensity(self):
-        assert build_ffmpeg_filter("filter_cinematic", 0) == ""
-
-    def test_invalid_preset(self):
-        assert build_ffmpeg_filter("nonexistent", 100) == ""
-
-    def test_cinematic_full(self):
-        result = build_ffmpeg_filter("filter_cinematic", 100)
-        assert result.startswith("eq=")
-        assert "contrast=" in result
-        assert "saturation=" in result
-        assert "gamma_r=" in result
-
-    def test_cinematic_half(self):
-        full = build_ffmpeg_filter("filter_cinematic", 100)
-        half = build_ffmpeg_filter("filter_cinematic", 50)
-        assert full != half
-        # 50% 强度的参数应该更接近原值
-        assert "eq=" in half
-
-    def test_bw_filter(self):
-        result = build_ffmpeg_filter("filter_bw", 100)
-        assert "saturation=0" in result
-
-    def test_warm_filter(self):
-        result = build_ffmpeg_filter("filter_warm", 100)
-        assert "gamma_r=" in result
-        assert "gamma_b=" in result

tests/unit/test_edit_plan_generation_api.py

@@ -1,754 +0,0 @@
-"""剪辑计划生成 API 单元测试 — Phase 8 任务 2.05.
-
-覆盖 2 个新端点：
-  POST /api/v1/edit-plans/{id}/generate          — 触发剪辑渲染生成
-  GET  /api/v1/edit-plans/{id}/generation-status  — 查询生成进度
-
-使用 FastAPI TestClient + Stub Repository + dependency_overrides.
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from dataclasses import dataclass, field
-from typing import Any, Optional
-from unittest.mock import MagicMock, patch
-
-os.environ.setdefault("JWT_SECRET_KEY", "unit-test-secret-key-for-testing")
-os.environ.setdefault("DATABASE_URL", "sqlite:///test.db")
-
-import pytest
-from fastapi import FastAPI
-from fastapi.testclient import TestClient
-
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "apps", "api"))
-
-from packages.domain.edit_plan import EditPlan, EditPlanStatus
-from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
-
-# ── Stub Repositories ─────────────────────────────────────────────────────────
-
-
-class StubEditPlanRepository:
-    """内存中模拟 EditPlan 仓储"""
-
-    def __init__(self) -> None:
-        self._store: dict[str, EditPlan] = {}
-
-    def list_all(
-        self,
-        *,
-        status: Optional[EditPlanStatus] = None,
-        skip: int = 0,
-        limit: int = 50,
-    ) -> list[EditPlan]:
-        items = list(self._store.values())
-        if status:
-            items = [p for p in items if p.status == status]
-        items.sort(key=lambda p: p.created_at, reverse=True)
-        return items[skip : skip + limit]
-
-    def list_by_template(
-        self,
-        template_id: str,
-        *,
-        status: Optional[EditPlanStatus] = None,
-        skip: int = 0,
-        limit: int = 50,
-    ) -> list[EditPlan]:
-        items = [p for p in self._store.values() if p.template_id == template_id]
-        if status:
-            items = [p for p in items if p.status == status]
-        items.sort(key=lambda p: p.created_at, reverse=True)
-        return items[skip : skip + limit]
-
-    def get(self, plan_id: str) -> Optional[EditPlan]:
-        return self._store.get(plan_id)
-
-    def create(self, plan: EditPlan) -> EditPlan:
-        self._store[plan.id] = plan
-        return plan
-
-    def update(self, plan: EditPlan) -> EditPlan:
-        if plan.id not in self._store:
-            raise ValueError(f"EditPlan {plan.id} not found")
-        self._store[plan.id] = plan
-        return plan
-
-    def delete(self, plan_id: str) -> bool:
-        if plan_id in self._store:
-            del self._store[plan_id]
-            return True
-        return False
-
-    def count(self, *, status: Optional[EditPlanStatus] = None) -> int:
-        items = list(self._store.values())
-        if status:
-            items = [p for p in items if p.status == status]
-        return len(items)
-
-
-class StubEditPlanClipRepository:
-    """内存中模拟 EditPlanClip 仓储"""
-
-    def __init__(self) -> None:
-        self._store: dict[str, EditPlanClip] = {}
-
-    def list_by_plan(
-        self,
-        plan_id: str,
-        *,
-        status: Optional[EditPlanClipStatus] = None,
-        skip: int = 0,
-        limit: int = 100,
-    ) -> list[EditPlanClip]:
-        items = [c for c in self._store.values() if c.plan_id == plan_id]
-        if status:
-            items = [c for c in items if c.status == status]
-        items.sort(key=lambda c: c.order)
-        return items[skip : skip + limit]
-
-    def get(self, clip_id: str) -> Optional[EditPlanClip]:
-        return self._store.get(clip_id)
-
-    def create(self, clip: EditPlanClip) -> EditPlanClip:
-        self._store[clip.id] = clip
-        return clip
-
-    def update(self, clip: EditPlanClip) -> EditPlanClip:
-        if clip.id not in self._store:
-            raise ValueError(f"EditPlanClip {clip.id} not found")
-        self._store[clip.id] = clip
-        return clip
-
-    def delete(self, clip_id: str) -> bool:
-        if clip_id in self._store:
-            del self._store[clip_id]
-            return True
-        return False
-
-    def delete_by_plan(self, plan_id: str) -> int:
-        to_delete = [c.id for c in self._store.values() if c.plan_id == plan_id]
-        for cid in to_delete:
-            del self._store[cid]
-        return len(to_delete)
-
-    def count(
-        self,
-        plan_id: Optional[str] = None,
-        *,
-        status: Optional[EditPlanClipStatus] = None,
-    ) -> int:
-        items = list(self._store.values())
-        if plan_id:
-            items = [c for c in items if c.plan_id == plan_id]
-        if status:
-            items = [c for c in items if c.status == status]
-        return len(items)
-
-
-class StubGenerationTaskRepository:
-    """内存中模拟 GenerationTask 仓储"""
-
-    def __init__(self) -> None:
-        self._store: dict[str, Any] = {}
-
-    def create(self, task: Any) -> Any:
-        self._store[task.id] = task
-        return task
-
-    def get(self, task_id: str) -> Optional[Any]:
-        return self._store.get(task_id)
-
-    def update(self, task: Any) -> Any:
-        if task.id not in self._store:
-            raise ValueError(f"GenerationTask {task.id} not found")
-        self._store[task.id] = task
-        return task
-
-    def list_by_project(self, project_id: str) -> list[Any]:
-        return [t for t in self._store.values() if t.project_id == project_id]
-
-    def list_by_user(self, user_id: str) -> list[Any]:
-        return [t for t in self._store.values() if t.created_by_user_id == user_id]
-
-    def count_by_user(self, user_id: str) -> int:
-        return len([t for t in self._store.values() if t.created_by_user_id == user_id])
-
-    def count_pending_by_user(self, user_id: str) -> int:
-        return len(
-            [
-                t
-                for t in self._store.values()
-                if t.created_by_user_id == user_id and getattr(t, "status", "") == "pending"
-            ]
-        )
-
-    def count_pending_total(self) -> int:
-        return len([t for t in self._store.values() if getattr(t, "status", "") == "pending"])
-
-    def list_recent_by_user(self, user_id: str, limit: int = 5) -> list[Any]:
-        items = [t for t in self._store.values() if t.created_by_user_id == user_id]
-        items.sort(key=lambda t: t.created_at, reverse=True)
-        return items[:limit]
-
-    def list_by_user_filtered(
-        self,
-        user_id: str,
-        *,
-        status: str | None = None,
-        limit: int | None = None,
-        offset: int = 0,
-    ) -> list:
-        """按用户+状态筛选任务列表（stub实现）。"""
-        items = [t for t in self._store.values() if t.created_by_user_id == user_id]
-        if status:
-            items = [t for t in items if str(t.status) == status]
-        # 按创建时间倒序
-        items.sort(key=lambda t: t.created_at or "", reverse=True)
-        if offset:
-            items = items[offset:]
-        if limit is not None:
-            items = items[:limit]
-        return items
-
-    def count_by_user_filtered(
-        self,
-        user_id: str,
-        *,
-        status: str | None = None,
-    ) -> int:
-        """按用户+状态筛选计数（stub实现）。"""
-        items = [t for t in self._store.values() if t.created_by_user_id == user_id]
-        if status:
-            items = [t for t in items if str(t.status) == status]
-        return len(items)
-
-    def list_by_project_filtered(
-        self,
-        project_id: str,
-        *,
-        status: str | None = None,
-        limit: int | None = None,
-        offset: int = 0,
-    ) -> list:
-        """按项目+状态筛选任务列表（stub实现）。"""
-        items = [t for t in self._store.values() if t.project_id == project_id]
-        if status:
-            items = [t for t in items if str(t.status) == status]
-        # 按创建时间倒序
-        items.sort(key=lambda t: t.created_at or "", reverse=True)
-        if offset:
-            items = items[offset:]
-        if limit is not None:
-            items = items[:limit]
-        return items
-
-    def count_by_project_filtered(
-        self,
-        project_id: str,
-        *,
-        status: str | None = None,
-    ) -> int:
-        """按项目+状态筛选计数（stub实现）。"""
-        items = [t for t in self._store.values() if t.project_id == project_id]
-        if status:
-            items = [t for t in items if str(t.status) == status]
-        return len(items)
-
-
-# ── Fixtures ──────────────────────────────────────────────────────────────────
-
-
-@dataclass
-class FakeUser:
-    id: str = "user-001"
-    email: str = "test@example.com"
-
-
-@dataclass
-class FakeAuthenticatedUser:
-    user: FakeUser = field(default_factory=FakeUser)
-    session_id: str | None = None
-    token_type: str | None = None
-
-
-@pytest.fixture
-def plan_repo() -> StubEditPlanRepository:
-    return StubEditPlanRepository()
-
-
-@pytest.fixture
-def clip_repo() -> StubEditPlanClipRepository:
-    return StubEditPlanClipRepository()
-
-
-@pytest.fixture
-def gen_task_repo() -> StubGenerationTaskRepository:
-    return StubGenerationTaskRepository()
-
-
-@pytest.fixture
-def app(
-    plan_repo: StubEditPlanRepository,
-    clip_repo: StubEditPlanClipRepository,
-    gen_task_repo: StubGenerationTaskRepository,
-) -> FastAPI:
-    """构建测试 FastAPI 应用，注入 Stub Repository"""
-    import app.services.edit_plan_service as service_module
-    from app.api.routes.edit_plans import router
-    from app.auth import get_current_user
-    from app.dependencies import get_db_session
-
-    # 替换 Repository 类
-    original_plan_repo = service_module.SQLAlchemyEditPlanRepository
-    original_clip_repo = service_module.SQLAlchemyEditPlanClipRepository
-    original_gen_repo = service_module.SQLAlchemyGenerationTaskRepository
-
-    service_module.SQLAlchemyEditPlanRepository = lambda session: plan_repo
-    service_module.SQLAlchemyEditPlanClipRepository = lambda session: clip_repo
-    service_module.SQLAlchemyGenerationTaskRepository = lambda session: gen_task_repo
-
-    test_app = FastAPI()
-    test_app.include_router(router, prefix="/api/v1/edit-plans")
-
-    def override_get_db_session():
-        yield MagicMock()
-
-    def override_get_current_user():
-        return FakeAuthenticatedUser()
-
-    test_app.dependency_overrides[get_db_session] = override_get_db_session
-    test_app.dependency_overrides[get_current_user] = override_get_current_user
-
-    yield test_app
-
-    # 恢复
-    service_module.SQLAlchemyEditPlanRepository = original_plan_repo
-    service_module.SQLAlchemyEditPlanClipRepository = original_clip_repo
-    service_module.SQLAlchemyGenerationTaskRepository = original_gen_repo
-    test_app.dependency_overrides.clear()
-
-
-@pytest.fixture
-def client(app: FastAPI) -> TestClient:
-    return TestClient(app)
-
-
-def _make_plan(
-    name: str = "测试计划",
-    template_id: str = "tmpl-001",
-    status: EditPlanStatus = EditPlanStatus.DRAFT,
-    **kwargs: Any,
-) -> EditPlan:
-    plan = EditPlan.create(template_id=template_id, name=name, **kwargs)
-    plan.status = status
-    return plan
-
-
-def _make_clip(
-    plan_id: str,
-    clip_type: str = "MAIN",
-    order: int = 1,
-    asset_id: str = "assets/video.mp4",
-    status: EditPlanClipStatus = EditPlanClipStatus.PENDING,
-    **kwargs: Any,
-) -> EditPlanClip:
-    clip = EditPlanClip.create(
-        plan_id=plan_id,
-        clip_type=clip_type,
-        order=order,
-        asset_id=asset_id,
-        **kwargs,
-    )
-    clip.status = status
-    return clip
-
-
-# ── POST /api/v1/edit-plans/{id}/generate ─────────────────────────────────────
-
-
-class TestGeneratePlan:
-    def test_generate_success(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-        clip_repo: StubEditPlanClipRepository,
-    ) -> None:
-        """editing 状态 + pending 片段 → 触发成功"""
-        plan = _make_plan(status=EditPlanStatus.EDITING)
-        plan_repo.create(plan)
-        clip = _make_clip(plan.id, order=1)
-        clip_repo.create(clip)
-
-        with patch("app.api.routes.edit_plans_generation.celery_app") as mock_celery:
-            mock_celery.send_task = MagicMock()
-            resp = client.post(f"/api/v1/edit-plans/{plan.id}/generate")
-
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["plan_id"] == plan.id
-        assert data["plan_status"] == "rendering"
-        assert data["clip_count"] == 1
-        assert "generation_task_id" in data
-
-        # 验证计划状态已更新
-        updated = plan_repo.get(plan.id)
-        assert updated.status == EditPlanStatus.RENDERING
-
-        # 验证片段状态已更新为 ready
-        updated_clip = clip_repo.get(clip.id)
-        assert updated_clip.status == EditPlanClipStatus.READY
-
-    def test_generate_not_found(self, client: TestClient) -> None:
-        """计划不存在 → 404"""
-        resp = client.post("/api/v1/edit-plans/nonexistent/generate")
-        assert resp.status_code == 404
-        assert "不存在" in resp.json()["detail"]
-
-    def test_generate_draft_auto_transition_to_editing(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-    ) -> None:
-        """draft 状态自动转 editing（自动兜底），然后因 0 片段报错"""
-        plan = _make_plan(status=EditPlanStatus.DRAFT)
-        plan_repo.create(plan)
-        resp = client.post(f"/api/v1/edit-plans/{plan.id}/generate")
-        # draft 自动转 editing，但没有片段所以还是 400
-        assert resp.status_code == 400
-        assert "请先添加片段后再生成视频" in resp.json()["detail"]
-        # 验证状态已自动转为 editing
-        updated_plan = plan_repo.get(plan.id)
-        assert updated_plan is not None
-        assert updated_plan.status == EditPlanStatus.EDITING
-
-    def test_generate_wrong_status_rendering(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-    ) -> None:
-        """rendering 状态 → 400"""
-        plan = _make_plan(status=EditPlanStatus.RENDERING)
-        plan_repo.create(plan)
-        resp = client.post(f"/api/v1/edit-plans/{plan.id}/generate")
-        assert resp.status_code == 400
-
-    def test_generate_wrong_status_completed(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-    ) -> None:
-        """completed 状态 → 400"""
-        plan = _make_plan(status=EditPlanStatus.COMPLETED)
-        plan_repo.create(plan)
-        resp = client.post(f"/api/v1/edit-plans/{plan.id}/generate")
-        assert resp.status_code == 400
-
-    def test_generate_no_clips(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-    ) -> None:
-        """editing 状态但没有片段 → 400"""
-        plan = _make_plan(status=EditPlanStatus.EDITING)
-        plan_repo.create(plan)
-        resp = client.post(f"/api/v1/edit-plans/{plan.id}/generate")
-        assert resp.status_code == 400
-        assert "片段" in resp.json()["detail"]
-
-    def test_generate_with_ready_clips(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-        clip_repo: StubEditPlanClipRepository,
-    ) -> None:
-        """已有 ready 状态的片段也可以触发生成"""
-        plan = _make_plan(status=EditPlanStatus.EDITING)
-        plan_repo.create(plan)
-        clip = _make_clip(plan.id, order=1, status=EditPlanClipStatus.READY)
-        clip_repo.create(clip)
-
-        with patch("app.api.routes.edit_plans_generation.celery_app") as mock_celery:
-            mock_celery.send_task = MagicMock()
-            resp = client.post(f"/api/v1/edit-plans/{plan.id}/generate")
-
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["plan_status"] == "rendering"
-
-    def test_generate_multiple_clips(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-        clip_repo: StubEditPlanClipRepository,
-    ) -> None:
-        """多个片段全部从 pending 转为 ready"""
-        plan = _make_plan(status=EditPlanStatus.EDITING)
-        plan_repo.create(plan)
-        for i in range(3):
-            clip = _make_clip(plan.id, order=i + 1)
-            clip_repo.create(clip)
-
-        with patch("app.api.routes.edit_plans_generation.celery_app") as mock_celery:
-            mock_celery.send_task = MagicMock()
-            resp = client.post(f"/api/v1/edit-plans/{plan.id}/generate")
-
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["clip_count"] == 3
-
-        # 验证所有片段都变为 ready
-        clips = clip_repo.list_by_plan(plan.id)
-        assert all(c.status == EditPlanClipStatus.READY for c in clips)
-
-
-# ── GET /api/v1/edit-plans/{id}/generation-status ─────────────────────────────
-
-
-class TestGetGenerationStatus:
-    def test_status_not_found(self, client: TestClient) -> None:
-        """计划不存在 → 404"""
-        resp = client.get("/api/v1/edit-plans/nonexistent/generation-status")
-        assert resp.status_code == 404
-
-    def test_status_draft_plan(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-        clip_repo: StubEditPlanClipRepository,
-    ) -> None:
-        """draft 状态计划的生成状态"""
-        plan = _make_plan(status=EditPlanStatus.DRAFT)
-        plan_repo.create(plan)
-        clip = _make_clip(plan.id, order=1)
-        clip_repo.create(clip)
-
-        resp = client.get(f"/api/v1/edit-plans/{plan.id}/generation-status")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["plan_id"] == plan.id
-        assert data["plan_status"] == "draft"
-        assert data["generation_task_id"] is None
-        assert len(data["clips"]) == 1
-        assert data["clips"][0]["status"] == "pending"
-
-    def test_status_rendering_plan(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-        clip_repo: StubEditPlanClipRepository,
-    ) -> None:
-        """rendering 状态计划的生成状态"""
-        plan = _make_plan(status=EditPlanStatus.RENDERING)
-        plan.config["generation_task_id"] = "gen-task-001"
-        plan_repo.create(plan)
-
-        clip1 = _make_clip(plan.id, order=1, status=EditPlanClipStatus.RENDERED)
-        clip2 = _make_clip(plan.id, order=2, status=EditPlanClipStatus.READY)
-        clip_repo.create(clip1)
-        clip_repo.create(clip2)
-
-        resp = client.get(f"/api/v1/edit-plans/{plan.id}/generation-status")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["plan_status"] == "rendering"
-        assert data["generation_task_id"] == "gen-task-001"
-        assert len(data["clips"]) == 2
-        statuses = {c["status"] for c in data["clips"]}
-        assert "rendered" in statuses
-        assert "ready" in statuses
-
-    def test_status_completed_plan(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-        clip_repo: StubEditPlanClipRepository,
-    ) -> None:
-        """completed 状态计划的生成状态"""
-        plan = _make_plan(status=EditPlanStatus.COMPLETED)
-        plan.config["generation_task_id"] = "gen-task-002"
-        plan.config["rendered_url"] = "https://oss.example.com/rendered/output.mp4"
-        plan_repo.create(plan)
-
-        clip = _make_clip(plan.id, order=1, status=EditPlanClipStatus.RENDERED)
-        clip_repo.create(clip)
-
-        resp = client.get(f"/api/v1/edit-plans/{plan.id}/generation-status")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["plan_status"] == "completed"
-        assert data["generation_task_id"] == "gen-task-002"
-        assert len(data["clips"]) == 1
-        assert data["clips"][0]["status"] == "rendered"
-
-    def test_status_clip_fields(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-        clip_repo: StubEditPlanClipRepository,
-    ) -> None:
-        """验证片段状态返回的字段完整性"""
-        plan = _make_plan(status=EditPlanStatus.EDITING)
-        plan_repo.create(plan)
-        clip = _make_clip(
-            plan.id,
-            clip_type="INTRO",
-            order=1,
-            asset_id="assets/intro.mp4",
-            duration=5.0,
-        )
-        clip.text_content = "欢迎观看"
-        clip_repo.create(clip)
-
-        resp = client.get(f"/api/v1/edit-plans/{plan.id}/generation-status")
-        assert resp.status_code == 200
-        data = resp.json()
-        clip_data = data["clips"][0]
-        assert clip_data["clip_id"] == clip.id
-        assert clip_data["clip_type"] == "INTRO"
-        assert clip_data["order"] == 1
-        assert clip_data["asset_id"] == "assets/intro.mp4"
-        assert clip_data["text_content"] == "欢迎观看"
-        assert clip_data["duration"] == 5.0
-
-    def test_status_no_clips(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-    ) -> None:
-        """没有片段的计划也能查询状态"""
-        plan = _make_plan(status=EditPlanStatus.DRAFT)
-        plan_repo.create(plan)
-
-        resp = client.get(f"/api/v1/edit-plans/{plan.id}/generation-status")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["clips"] == []
-
-
-# ── Response Schema 验证 ──────────────────────────────────────────────────────
-
-
-class TestResponseSchema:
-    def test_generate_response_structure(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-        clip_repo: StubEditPlanClipRepository,
-    ) -> None:
-        """验证 generate 端点响应结构"""
-        plan = _make_plan(status=EditPlanStatus.EDITING)
-        plan_repo.create(plan)
-        clip = _make_clip(plan.id, order=1)
-        clip_repo.create(clip)
-
-        with patch("app.api.routes.edit_plans_generation.celery_app") as mock_celery:
-            mock_celery.send_task = MagicMock()
-            resp = client.post(f"/api/v1/edit-plans/{plan.id}/generate")
-
-        assert resp.status_code == 200
-        data = resp.json()
-        expected_keys = {"plan_id", "plan_status", "generation_task_id", "clip_count"}
-        assert set(data.keys()) == expected_keys
-
-    def test_generation_status_response_structure(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-    ) -> None:
-        """验证 generation-status 端点响应结构"""
-        plan = _make_plan(status=EditPlanStatus.DRAFT)
-        plan_repo.create(plan)
-
-        resp = client.get(f"/api/v1/edit-plans/{plan.id}/generation-status")
-        assert resp.status_code == 200
-        data = resp.json()
-        expected_keys = {
-            "plan_id",
-            "plan_status",
-            "generation_task_id",
-            "generation_task_status",
-            "progress",
-            "video_url",
-            "error_message",
-            "clips",
-        }
-        assert set(data.keys()) == expected_keys
-
-
-# ── P0-1: 生成接口错误处理 ────────────────────────────────────────────────────
-
-
-class TestGeneratePlanErrorHandling:
-    """P0-1: generate 端点异常时返回明确错误信息，不裸 500"""
-
-    def test_generate_internal_error_returns_clear_message(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-        clip_repo: StubEditPlanClipRepository,
-    ) -> None:
-        """核心流程抛异常 → 500 + 用户友好的错误信息（不暴露技术细节）"""
-        plan = _make_plan(status=EditPlanStatus.EDITING)
-        plan_repo.create(plan)
-        clip = _make_clip(plan.id, order=1)
-        clip_repo.create(clip)
-
-        with patch("app.api.routes.edit_plans_generation.celery_app") as mock_celery:
-            # 模拟 Celery 调度失败
-            mock_celery.send_task.side_effect = RuntimeError("Redis 连接超时")
-            resp = client.post(f"/api/v1/edit-plans/{plan.id}/generate")
-
-        assert resp.status_code == 500
-        data = resp.json()
-        # 验证返回了用户友好的错误信息，不暴露技术细节
-        assert "生成失败" in data["detail"]
-        assert "RuntimeError" not in data["detail"]
-        assert "Redis" not in data["detail"]
-
-    def test_generate_error_rolls_back_plan_status(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-        clip_repo: StubEditPlanClipRepository,
-    ) -> None:
-        """异常时将计划标记为 failed（RENDERING → FAILED 是合法流转）"""
-        plan = _make_plan(status=EditPlanStatus.EDITING)
-        plan_repo.create(plan)
-        clip = _make_clip(plan.id, order=1)
-        clip_repo.create(clip)
-
-        with patch("app.api.routes.edit_plans_generation.celery_app") as mock_celery:
-            mock_celery.send_task.side_effect = RuntimeError("调度失败")
-            resp = client.post(f"/api/v1/edit-plans/{plan.id}/generate")
-
-        assert resp.status_code == 500
-        # 计划状态应变为 failed
-        updated = plan_repo.get(plan.id)
-        assert updated.status == EditPlanStatus.FAILED
-
-    def test_generate_error_detail_is_user_friendly(
-        self,
-        client: TestClient,
-        plan_repo: StubEditPlanRepository,
-        clip_repo: StubEditPlanClipRepository,
-    ) -> None:
-        """错误信息对用户友好，不暴露技术细节（异常类型、内部错误信息）"""
-        plan = _make_plan(status=EditPlanStatus.EDITING)
-        plan_repo.create(plan)
-        clip = _make_clip(plan.id, order=1)
-        clip_repo.create(clip)
-
-        with patch("app.api.routes.edit_plans_generation.celery_app") as mock_celery:
-            mock_celery.send_task.side_effect = ConnectionError("Broker 不可达")
-            resp = client.post(f"/api/v1/edit-plans/{plan.id}/generate")
-
-        assert resp.status_code == 500
-        detail = resp.json()["detail"]
-        # 验证不暴露技术细节
-        assert "ConnectionError" not in detail
-        assert "Broker 不可达" not in detail
-        # 验证返回了用户友好的提示
-        assert "生成失败" in detail

tests/unit/test_edit_plan_service.py

@@ -320,77 +320,10 @@ class TestEditPlanServiceCRUD:
         with pytest.raises(ValueError, match="剪辑计划不存在"):
             svc.get_plan_or_raise("nonexistent")
 
-    def test_list_plans(self):
-        svc = _make_service()
-        svc.create_plan("tpl-001", "计划1")
-        svc.create_plan("tpl-001", "计划2")
-        result = svc.list_plans()
-        assert len(result) == 2
-
-    def test_list_plans_by_template(self):
-        svc = _make_service()
-        svc.create_plan("tpl-001", "计划1")
-        svc.create_plan("tpl-002", "计划2")
-        result = svc.list_plans(template_id="tpl-001")
-        assert len(result) == 1
-        assert result[0].name == "计划1"
-
-    def test_list_plans_by_status(self):
-        svc = _make_service()
-        p1 = svc.create_plan("tpl-001", "计划1")
-        svc.create_plan("tpl-001", "计划2")
-        svc.transition_status(p1.id, EditPlanStatus.EDITING)
-        result = svc.list_plans(status=EditPlanStatus.EDITING)
-        assert len(result) == 1
-
-    def test_count_plans(self):
-        svc = _make_service()
-        svc.create_plan("tpl-001", "计划1")
-        svc.create_plan("tpl-001", "计划2")
-        assert svc.count_plans() == 2
-
-    def test_update_plan_name(self):
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "原名")
-        updated = svc.update_plan(p.id, name="新名")
-        assert updated.name == "新名"
-
     def test_update_plan_not_found_raises(self):
         svc = _make_service()
         with pytest.raises(ValueError, match="剪辑计划不存在"):
             svc.update_plan("nonexistent", name="新名")
-
-    def test_delete_plan(self):
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "要删除")
-        assert svc.delete_plan(p.id) is True
-        assert svc.get_plan(p.id) is None
-
-    def test_delete_plan_not_found(self):
-        svc = _make_service()
-        assert svc.delete_plan("nonexistent") is False
-
-    def test_delete_plan_also_deletes_clips(self):
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "带片段")
-        svc.create_clip(p.id, "intro", 0)
-        svc.create_clip(p.id, "main", 1)
-        assert svc.count_clips(p.id) == 2
-        svc.delete_plan(p.id)
-        # 片段应被一并删除
-        assert svc.count_clips(p.id) == 0
-
-
-# ===========================================================================
-# 状态机流转测试
-# ===========================================================================
-
-
-class TestStatusTransitions:
-    """状态机流转测试"""
-
-    def test_transition_draft_to_editing(self):
-        svc = _make_service()
         p = svc.create_plan("tpl-001", "测试")
         result = svc.transition_status(p.id, EditPlanStatus.EDITING)
         assert result.status == EditPlanStatus.EDITING
@@ -600,22 +533,6 @@ class TestGenerationWorkflow:
         clips = svc.list_clips(p.id)
         for c in clips:
             assert c.status == EditPlanClipStatus.READY
-
-    def test_get_plan_with_clips(self):
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试")
-        svc.create_clip(p.id, "intro", 0)
-        svc.create_clip(p.id, "main", 1)
-        result = svc.get_plan_with_clips(p.id)
-        assert result["plan"].id == p.id
-        assert len(result["clips"]) == 2
-
-    def test_get_plan_with_clips_not_found(self):
-        svc = _make_service()
-        with pytest.raises(ValueError, match="剪辑计划不存在"):
-            svc.get_plan_with_clips("nonexistent")
-
-    def test_get_generation_status(self):
         svc = _make_service()
         p = svc.create_plan("tpl-001", "测试")
         svc.create_clip(p.id, "intro", 0)
@@ -849,234 +766,6 @@ class TestClipSplit:
         assert right.asset_id == "asset-001"
 
 
-class TestSubtitleManagement:
-    """字幕管理测试"""
-
-    def test_add_subtitle_basic(self):
-        """基础：添加一条字幕"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        subtitle = svc.add_subtitle(clip.id, start=1.0, end=3.0, text="大家好")
-
-        assert subtitle["text"] == "大家好"
-        assert subtitle["start"] == 1.0
-        assert subtitle["end"] == 3.0
-        assert "id" in subtitle
-        assert len(subtitle["id"]) > 0
-
-    def test_add_subtitle_with_style(self):
-        """添加带样式的字幕"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        style = {"font_size": 24, "color": "#ffffff", "position": "bottom"}
-        subtitle = svc.add_subtitle(clip.id, start=0.0, end=2.0, text="测试", style=style)
-
-        assert subtitle["style"]["font_size"] == 24
-        assert subtitle["style"]["color"] == "#ffffff"
-
-    def test_list_subtitles_sorted_by_time(self):
-        """字幕列表按时间排序"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        svc.add_subtitle(clip.id, start=5.0, end=6.0, text="第二")
-        svc.add_subtitle(clip.id, start=1.0, end=2.0, text="第一")
-        svc.add_subtitle(clip.id, start=8.0, end=9.0, text="第三")
-
-        subtitles = svc.list_subtitles(clip.id)
-        assert len(subtitles) == 3
-        assert subtitles[0]["text"] == "第一"
-        assert subtitles[1]["text"] == "第二"
-        assert subtitles[2]["text"] == "第三"
-
-    def test_add_subtitle_invalid_time_raises(self):
-        """非法时间报错"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        # 开始时间为负
-        with pytest.raises(ValueError, match="时间非法"):
-            svc.add_subtitle(clip.id, start=-1.0, end=2.0, text="test")
-
-        # 结束时间 <= 开始时间
-        with pytest.raises(ValueError, match="时间非法"):
-            svc.add_subtitle(clip.id, start=5.0, end=3.0, text="test")
-
-        # 超过片段时长
-        with pytest.raises(ValueError, match="不能超过片段时长"):
-            svc.add_subtitle(clip.id, start=8.0, end=15.0, text="test")
-
-    def test_add_subtitle_empty_text_raises(self):
-        """空文本报错"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        with pytest.raises(ValueError, match="不能为空"):
-            svc.add_subtitle(clip.id, start=1.0, end=2.0, text="   ")
-
-    def test_get_subtitle(self):
-        """获取单条字幕"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        sub = svc.add_subtitle(clip.id, start=1.0, end=2.0, text="测试")
-        found = svc.get_subtitle(clip.id, sub["id"])
-
-        assert found is not None
-        assert found["text"] == "测试"
-
-        # 不存在的返回 None
-        assert svc.get_subtitle(clip.id, "nonexistent") is None
-
-    def test_update_subtitle_text(self):
-        """更新字幕文本"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        sub = svc.add_subtitle(clip.id, start=1.0, end=2.0, text="原文")
-        updated = svc.update_subtitle(clip.id, sub["id"], text="修改后")
-
-        assert updated["text"] == "修改后"
-        assert updated["start"] == 1.0  # 时间不变
-
-    def test_update_subtitle_time(self):
-        """更新字幕时间"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        sub = svc.add_subtitle(clip.id, start=1.0, end=2.0, text="测试")
-        updated = svc.update_subtitle(clip.id, sub["id"], start=3.0, end=5.0)
-
-        assert updated["start"] == 3.0
-        assert updated["end"] == 5.0
-
-    def test_update_subtitle_not_found_raises(self):
-        """更新不存在的字幕报错"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        with pytest.raises(ValueError, match="字幕不存在"):
-            svc.update_subtitle(clip.id, "fake-id", text="test")
-
-    def test_delete_subtitle(self):
-        """删除字幕"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        sub = svc.add_subtitle(clip.id, start=1.0, end=2.0, text="要删的")
-        assert svc.count_clips(p.id) == 1  # 片段还在
-
-        deleted = svc.delete_subtitle(clip.id, sub["id"])
-        assert deleted is True
-
-        subtitles = svc.list_subtitles(clip.id)
-        assert len(subtitles) == 0
-
-    def test_delete_subtitle_not_found(self):
-        """删除不存在的字幕返回 False"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        deleted = svc.delete_subtitle(clip.id, "nonexistent")
-        assert deleted is False
-
-    def test_batch_update_subtitles(self):
-        """批量更新字幕（全量替换）"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=20.0)
-
-        # 先加一条
-        svc.add_subtitle(clip.id, start=1.0, end=2.0, text="旧字幕")
-
-        # 全量替换为 3 条
-        new_subs = [
-            {"start": 0.0, "end": 3.0, "text": "第一条"},
-            {"start": 4.0, "end": 7.0, "text": "第二条"},
-            {"start": 8.0, "end": 12.0, "text": "第三条"},
-        ]
-        result = svc.batch_update_subtitles(clip.id, new_subs)
-
-        assert len(result) == 3
-        assert result[0]["text"] == "第一条"
-        # 都有 id
-        assert all("id" in s for s in result)
-        # 旧字幕没了
-        subtitles = svc.list_subtitles(clip.id)
-        assert len(subtitles) == 3
-
-    def test_batch_update_preserves_existing_ids(self):
-        """批量更新时已有 id 的字幕保留原 id"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        sub = svc.add_subtitle(clip.id, start=1.0, end=2.0, text="原字幕")
-        original_id = sub["id"]
-
-        # 带 id 批量更新，修改文本
-        updated_list = svc.batch_update_subtitles(
-            clip.id,
-            [{"id": original_id, "start": 1.0, "end": 3.0, "text": "修改了"}],
-        )
-
-        assert len(updated_list) == 1
-        assert updated_list[0]["id"] == original_id
-        assert updated_list[0]["text"] == "修改了"
-
-    def test_batch_update_skips_empty_text(self):
-        """批量更新时空文本自动跳过"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        subs = [
-            {"start": 0.0, "end": 1.0, "text": "有效"},
-            {"start": 2.0, "end": 3.0, "text": "  "},  # 空白，跳过
-            {"start": 4.0, "end": 5.0, "text": "也有效"},
-        ]
-        result = svc.batch_update_subtitles(clip.id, subs)
-
-        assert len(result) == 2
-
-    def test_empty_clip_returns_empty_list(self):
-        """没有字幕的片段返回空列表"""
-        svc = _make_service()
-        p = svc.create_plan("tpl-001", "测试计划")
-        svc.transition_status(p.id, EditPlanStatus.EDITING)
-        clip = svc.create_clip(p.id, "main", 0, duration=10.0)
-
-        subtitles = svc.list_subtitles(clip.id)
-        assert subtitles == []
-
-
 class TestClipMerge:
     """片段合并测试"""
 

tests/unit/test_edit_plan_transitions_api.py

@@ -1,494 +0,0 @@
-"""
-转场特效 API 单元测试
-
-覆盖：
-- GET /transition-presets - 转场预设列表
-- PUT /clips/{clip_id}/transition - 设置单个片段转场
-- POST /{plan_id}/transitions/batch - 批量设置转场
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from datetime import datetime
-from pathlib import Path
-from typing import Optional
-from unittest.mock import MagicMock
-
-os.environ.setdefault("JWT_SECRET_KEY", "unit-test-secret-key-for-testing")
-os.environ.setdefault("DATABASE_URL", "sqlite:///test.db")
-
-import pytest
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
-
-from fastapi import FastAPI
-from fastapi.testclient import TestClient
-
-from packages.domain.config_schemas import normalize_plan_config
-from packages.domain.edit_plan import EditPlan, EditPlanStatus
-from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
-from packages.domain.transition_presets import TRANSITION_PRESET_LIBRARY
-
-# ---------------------------------------------------------------------------
-# Stub Repository
-# ---------------------------------------------------------------------------
-
-
-class StubEditPlanRepository:
-    def __init__(self, plans: dict[str, EditPlan] | None = None):
-        self._plans = plans or {}
-
-    def list_all(self, *, status=None, skip=0, limit=50):
-        items = list(self._plans.values())
-        if status is not None:
-            items = [p for p in items if p.status == status]
-        items.sort(key=lambda p: p.created_at, reverse=True)
-        return items[skip : skip + limit]
-
-    def list_by_template(self, template_id, *, status=None, skip=0, limit=50):
-        items = [p for p in self._plans.values() if p.template_id == template_id]
-        if status is not None:
-            items = [p for p in items if p.status == status]
-        items.sort(key=lambda p: p.created_at, reverse=True)
-        return items[skip : skip + limit]
-
-    def get(self, plan_id: str) -> Optional[EditPlan]:
-        return self._plans.get(plan_id)
-
-    def create(self, plan: EditPlan) -> EditPlan:
-        self._plans[plan.id] = plan
-        return plan
-
-    def update(self, plan: EditPlan) -> EditPlan:
-        self._plans[plan.id] = plan
-        return plan
-
-    def delete(self, plan_id: str) -> bool:
-        if plan_id in self._plans:
-            del self._plans[plan_id]
-            return True
-        return False
-
-    def count(self, *, status=None, template_id=None):
-        items = list(self._plans.values())
-        if status is not None:
-            items = [p for p in items if p.status == status]
-        if template_id is not None:
-            items = [p for p in items if p.template_id == template_id]
-        return len(items)
-
-
-class StubEditPlanClipRepository:
-    def __init__(self, clips: dict[str, EditPlanClip] | None = None):
-        self._clips = clips or {}
-        self._counter = 0
-
-    def _next_id(self) -> str:
-        self._counter += 1
-        return f"clip-new{self._counter}"
-
-    def list_by_plan(self, plan_id, *, status=None, skip=0, limit=100):
-        items = [c for c in self._clips.values() if c.plan_id == plan_id]
-        if status is not None:
-            items = [c for c in items if c.status == status]
-        items.sort(key=lambda c: c.order)
-        return items[skip : skip + limit]
-
-    def count(self, plan_id, *, status=None):
-        items = [c for c in self._clips.values() if c.plan_id == plan_id]
-        if status is not None:
-            items = [c for c in items if c.status == status]
-        return len(items)
-
-    def get(self, clip_id: str) -> Optional[EditPlanClip]:
-        return self._clips.get(clip_id)
-
-    def create(self, clip: EditPlanClip) -> EditPlanClip:
-        if not clip.id:
-            clip.id = self._next_id()
-        self._clips[clip.id] = clip
-        return clip
-
-    def update(self, clip: EditPlanClip) -> EditPlanClip:
-        self._clips[clip.id] = clip
-        return clip
-
-    def delete(self, clip_id: str) -> bool:
-        if clip_id in self._clips:
-            del self._clips[clip_id]
-            return True
-        return False
-
-    def delete_by_plan(self, plan_id: str) -> int:
-        to_delete = [cid for cid, c in self._clips.items() if c.plan_id == plan_id]
-        for cid in to_delete:
-            del self._clips[cid]
-        return len(to_delete)
-
-
-# ---------------------------------------------------------------------------
-# Test Fixtures
-# ---------------------------------------------------------------------------
-
-
-def _make_sample_plan(plan_id="plan-001"):
-    return EditPlan(
-        id=plan_id,
-        template_id="tpl-001",
-        name="测试计划",
-        status=EditPlanStatus.EDITING,
-        total_duration=30.0,
-        config=normalize_plan_config({}),
-        project_id="",
-        created_by_user_id="user-001",
-        created_at=datetime(2026, 7, 16, 10, 0, 0),
-        updated_at=datetime(2026, 7, 16, 10, 0, 0),
-    )
-
-
-def _make_clip(clip_id, plan_id="plan-001", order=0, transition_effect="cut", transition_duration=0.0):
-    return EditPlanClip(
-        id=clip_id,
-        plan_id=plan_id,
-        clip_type="video",
-        order=order,
-        asset_id="asset-001",
-        text_content="",
-        start_time=0.0,
-        duration=10.0,
-        transition_effect=transition_effect,
-        transition_duration=transition_duration,
-        playback_speed=1.0,
-        status=EditPlanClipStatus.READY,
-        config={},
-        created_at=datetime(2026, 7, 16, 10, 0, 0),
-        updated_at=datetime(2026, 7, 16, 10, 0, 0),
-    )
-
-
-def _create_test_app():
-    import app.api.routes.edit_plans_transitions as transitions_module
-    import app.services.edit_plan_service as service_module
-    from app.api.routes.edit_plans import router
-
-    plan = _make_sample_plan()
-    clips = {
-        "clip-001": _make_clip("clip-001", order=0),
-        "clip-002": _make_clip("clip-002", order=1),
-        "clip-003": _make_clip("clip-003", order=2),
-        "clip-004": _make_clip("clip-004", order=3),
-    }
-    stub_plan_repo = StubEditPlanRepository({plan.id: plan})
-    stub_clip_repo = StubEditPlanClipRepository(clips)
-
-    original_plan_repo = service_module.SQLAlchemyEditPlanRepository
-    original_clip_repo = service_module.SQLAlchemyEditPlanClipRepository
-    original_gen_repo = service_module.SQLAlchemyGenerationTaskRepository
-    service_module.SQLAlchemyEditPlanRepository = lambda db: stub_plan_repo
-    service_module.SQLAlchemyEditPlanClipRepository = lambda db: stub_clip_repo
-    service_module.SQLAlchemyGenerationTaskRepository = lambda db: MagicMock()
-
-    app = FastAPI()
-    app.include_router(router, prefix="/api/v1/edit-plans")
-
-    # Mock 认证
-    def _mock_auth():
-        mock = MagicMock()
-        mock.user.id = "user-001"
-        return mock
-
-    # Mock 项目访问检查
-    import app.api.routes._helpers as helpers_module
-
-    original_check = helpers_module.check_project_access
-    helpers_module.check_project_access = lambda *a, **kw: None
-
-    # 覆盖依赖
-    from app.api.routes import edit_plans as main_module
-
-    app.dependency_overrides[main_module.get_current_user] = _mock_auth
-    app.dependency_overrides[main_module.get_db_session] = lambda: MagicMock()
-    app.dependency_overrides[main_module.get_project_repository] = lambda: MagicMock()
-
-    app.dependency_overrides[transitions_module.get_current_user] = _mock_auth
-    app.dependency_overrides[transitions_module.get_db_session] = lambda: MagicMock()
-    app.dependency_overrides[transitions_module.get_project_repository] = lambda: MagicMock()
-
-    def cleanup():
-        service_module.SQLAlchemyEditPlanRepository = original_plan_repo
-        service_module.SQLAlchemyEditPlanClipRepository = original_clip_repo
-        service_module.SQLAlchemyGenerationTaskRepository = original_gen_repo
-        helpers_module.check_project_access = original_check
-
-    return app, stub_plan_repo, stub_clip_repo, cleanup
-
-
-@pytest.fixture
-def transition_client():
-    app, plan_repo, clip_repo, cleanup = _create_test_app()
-    yield TestClient(app), plan_repo, clip_repo
-    cleanup()
-
-
-# ---------------------------------------------------------------------------
-# Transition Presets 测试
-# ---------------------------------------------------------------------------
-
-
-class TestTransitionPresets:
-    def test_list_all_presets(self, transition_client):
-        c, _, _ = transition_client
-        resp = c.get("/api/v1/edit-plans/transition-presets")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] == len(TRANSITION_PRESET_LIBRARY)
-        assert data["total"] > 10
-        first = data["items"][0]
-        assert "id" in first
-        assert "name" in first
-        assert "category" in first
-        assert "default_duration" in first
-        assert "min_duration" in first
-        assert "max_duration" in first
-
-    def test_filter_by_category_fade(self, transition_client):
-        c, _, _ = transition_client
-        resp = c.get("/api/v1/edit-plans/transition-presets?category=fade")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] >= 3
-        for item in data["items"]:
-            assert item["category"] == "fade"
-
-    def test_filter_by_category_slide(self, transition_client):
-        c, _, _ = transition_client
-        resp = c.get("/api/v1/edit-plans/transition-presets?category=slide")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] >= 4
-        for item in data["items"]:
-            assert item["category"] == "slide"
-
-    def test_filter_by_keyword(self, transition_client):
-        c, _, _ = transition_client
-        resp = c.get("/api/v1/edit-plans/transition-presets?keyword=模糊")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] > 0
-        names = [item["name"] for item in data["items"]]
-        assert any("模糊" in n for n in names)
-
-    def test_filter_empty_result(self, transition_client):
-        c, _, _ = transition_client
-        resp = c.get("/api/v1/edit-plans/transition-presets?keyword=不存在的转场")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] == 0
-
-    def test_contains_none_transition(self, transition_client):
-        c, _, _ = transition_client
-        resp = c.get("/api/v1/edit-plans/transition-presets?category=basic")
-        assert resp.status_code == 200
-        data = resp.json()
-        ids = [item["id"] for item in data["items"]]
-        assert "transition_none" in ids
-
-
-# ---------------------------------------------------------------------------
-# PUT /clips/{clip_id}/transition 测试
-# ---------------------------------------------------------------------------
-
-
-class TestUpdateClipTransition:
-    def test_set_fade_transition(self, transition_client):
-        c, _, clip_repo = transition_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/transition",
-            json={"effect": "transition_fade", "duration": 0.8},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["clip_id"] == "clip-001"
-        assert data["effect"] == "fade"
-        assert data["duration"] == 0.8
-
-        clip = clip_repo.get("clip-001")
-        assert clip.transition_effect == "fade"
-        assert clip.transition_duration == 0.8
-
-    def test_set_none_transition(self, transition_client):
-        c, _, clip_repo = transition_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/transition",
-            json={"effect": "transition_none"},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["effect"] == "cut"
-        assert data["duration"] == 0.0
-
-    def test_use_default_duration(self, transition_client):
-        c, _, _ = transition_client
-        # 不传 duration，使用预设默认值
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/transition",
-            json={"effect": "transition_fade"},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["effect"] == "fade"
-        assert data["duration"] > 0  # 使用默认值
-
-    def test_invalid_effect(self, transition_client):
-        c, _, _ = transition_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/transition",
-            json={"effect": "invalid_effect"},
-        )
-        assert resp.status_code == 400
-        assert "无效的转场效果" in resp.json()["detail"]
-
-    def test_clip_not_found(self, transition_client):
-        c, _, _ = transition_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-nonexist/transition",
-            json={"effect": "transition_fade"},
-        )
-        assert resp.status_code == 404
-
-    def test_negative_duration_422(self, transition_client):
-        c, _, _ = transition_client
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/transition",
-            json={"effect": "transition_fade", "duration": -0.5},
-        )
-        assert resp.status_code == 422
-
-    def test_duration_clamped_to_max(self, transition_client):
-        c, _, clip_repo = transition_client
-        # 传一个超过最大值的时长，应该被钳制
-        resp = c.put(
-            "/api/v1/edit-plans/clips/clip-001/transition",
-            json={"effect": "transition_fade", "duration": 10.0},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        # fade 最大 2.0s
-        assert data["duration"] <= 2.0
-
-
-# ---------------------------------------------------------------------------
-# POST /{plan_id}/transitions/batch 测试
-# ---------------------------------------------------------------------------
-
-
-class TestBatchUpdateTransitions:
-    def test_batch_all(self, transition_client):
-        c, _, clip_repo = transition_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/transitions/batch",
-            json={"effect": "transition_fade", "duration": 0.5, "apply_to": "all"},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["updated_count"] == 4  # 4个片段
-
-        for cid in ["clip-001", "clip-002", "clip-003", "clip-004"]:
-            clip = clip_repo.get(cid)
-            assert clip.transition_effect == "fade"
-            assert clip.transition_duration == 0.5
-
-    def test_batch_except_first(self, transition_client):
-        c, _, clip_repo = transition_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/transitions/batch",
-            json={"effect": "transition_fade", "apply_to": "except_first"},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["updated_count"] == 3
-
-        # 第一个不变
-        assert clip_repo.get("clip-001").transition_effect == "cut"
-        # 其余三个被更新
-        for cid in ["clip-002", "clip-003", "clip-004"]:
-            assert clip_repo.get(cid).transition_effect == "fade"
-
-    def test_batch_except_last(self, transition_client):
-        c, _, clip_repo = transition_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/transitions/batch",
-            json={"effect": "transition_slideleft", "apply_to": "except_last"},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["updated_count"] == 3
-
-        # 最后一个不变
-        assert clip_repo.get("clip-004").transition_effect == "cut"
-        # 前三个被更新
-        for cid in ["clip-001", "clip-002", "clip-003"]:
-            assert clip_repo.get(cid).transition_effect == "slideleft"
-
-    def test_batch_middle(self, transition_client):
-        c, _, clip_repo = transition_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/transitions/batch",
-            json={"effect": "transition_dissolve", "apply_to": "middle"},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["updated_count"] == 2  # 4个片段，中间2个
-
-        # 首尾不变
-        assert clip_repo.get("clip-001").transition_effect == "cut"
-        assert clip_repo.get("clip-004").transition_effect == "cut"
-        # 中间被更新
-        assert clip_repo.get("clip-002").transition_effect == "dissolve"
-        assert clip_repo.get("clip-003").transition_effect == "dissolve"
-
-    def test_batch_invalid_effect(self, transition_client):
-        c, _, _ = transition_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/transitions/batch",
-            json={"effect": "invalid"},
-        )
-        assert resp.status_code == 400
-
-    def test_batch_plan_not_found(self, transition_client):
-        c, _, _ = transition_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-nonexist/transitions/batch",
-            json={"effect": "transition_fade"},
-        )
-        assert resp.status_code == 404
-
-    def test_batch_invalid_apply_to(self, transition_client):
-        c, _, _ = transition_client
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/transitions/batch",
-            json={"effect": "transition_fade", "apply_to": "invalid"},
-        )
-        assert resp.status_code == 400
-
-    def test_batch_none_transition(self, transition_client):
-        c, _, clip_repo = transition_client
-        # 先设一个转场
-        c.post(
-            "/api/v1/edit-plans/plan-001/transitions/batch",
-            json={"effect": "transition_fade", "apply_to": "all"},
-        )
-        # 再全部设为无
-        resp = c.post(
-            "/api/v1/edit-plans/plan-001/transitions/batch",
-            json={"effect": "transition_none", "apply_to": "all"},
-        )
-        assert resp.status_code == 200
-        assert resp.json()["updated_count"] == 4
-
-        for cid in ["clip-001", "clip-002", "clip-003", "clip-004"]:
-            clip = clip_repo.get(cid)
-            assert clip.transition_effect == "cut"
-            assert clip.transition_duration == 0.0

tests/unit/test_edit_plans_api.py

@@ -1,906 +0,0 @@
-"""
-edit_plans.py 剪辑计划 API 端点单元测试
-
-覆盖（25+ 测试用例）：
-- 创建：正常创建、空名称 400、空 template_id 422
-- 列表：默认分页、按状态筛选、按模板筛选、无效状态 400
-- 详情：正常获取、不存在 404
-- 更新：基础字段更新、状态机合法流转、状态机非法流转 400、不存在 404、无效状态值 400
-- 删除：正常删除、不存在 404
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from pathlib import Path
-from typing import Optional
-from unittest.mock import MagicMock, patch
-
-os.environ.setdefault("JWT_SECRET_KEY", "unit-test-secret-key-for-testing")
-os.environ.setdefault("DATABASE_URL", "sqlite:///test.db")
-
-import pytest
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
-
-from fastapi import FastAPI
-from fastapi.testclient import TestClient
-
-from packages.domain.config_schemas import normalize_plan_config
-from packages.domain.edit_plan import EditPlan, EditPlanStatus
-
-# ---------------------------------------------------------------------------
-# Stub Repository
-# ---------------------------------------------------------------------------
-
-
-class StubEditPlanRepository:
-    """内存中的 EditPlan 仓储 stub"""
-
-    def __init__(self, plans: dict[str, EditPlan] | None = None):
-        self._plans = plans or {}
-        self._counter = 0
-
-    def _next_id(self) -> str:
-        self._counter += 1
-        return f"plan-{self._counter:03d}"
-
-    def list_all(
-        self,
-        *,
-        status: Optional[EditPlanStatus] = None,
-        skip: int = 0,
-        limit: int = 50,
-    ) -> list[EditPlan]:
-        items = list(self._plans.values())
-        if status is not None:
-            items = [p for p in items if p.status == status]
-        items.sort(key=lambda p: p.created_at, reverse=True)
-        return items[skip : skip + limit]
-
-    def list_by_template(
-        self,
-        template_id: str,
-        *,
-        status: Optional[EditPlanStatus] = None,
-        skip: int = 0,
-        limit: int = 50,
-    ) -> list[EditPlan]:
-        items = [p for p in self._plans.values() if p.template_id == template_id]
-        if status is not None:
-            items = [p for p in items if p.status == status]
-        items.sort(key=lambda p: p.created_at, reverse=True)
-        return items[skip : skip + limit]
-
-    def get(self, plan_id: str) -> Optional[EditPlan]:
-        return self._plans.get(plan_id)
-
-    def create(self, plan: EditPlan) -> EditPlan:
-        self._plans[plan.id] = plan
-        return plan
-
-    def update(self, plan: EditPlan) -> EditPlan:
-        if plan.id not in self._plans:
-            raise ValueError(f"EditPlan {plan.id} not found")
-        self._plans[plan.id] = plan
-        return plan
-
-    def delete(self, plan_id: str) -> bool:
-        if plan_id not in self._plans:
-            return False
-        del self._plans[plan_id]
-        return True
-
-    def delete_by_plan(self, plan_id: str) -> None:
-        """按 plan_id 删除关联片段（stub 实现：无操作）。"""
-        pass
-
-    def count(
-        self,
-        *,
-        template_id: Optional[str] = None,
-        status: Optional[EditPlanStatus] = None,
-    ) -> int:
-        items = list(self._plans.values())
-        if template_id:
-            items = [p for p in items if p.template_id == template_id]
-        if status is not None:
-            items = [p for p in items if p.status == status]
-        return len(items)
-
-
-# ---------------------------------------------------------------------------
-# Fixtures
-# ---------------------------------------------------------------------------
-
-
-def _make_auth_user():
-    """构造 AuthenticatedUser mock"""
-    from app.auth import AuthenticatedUser
-
-    from packages.domain.entities import User
-
-    user = User(
-        id="user-001",
-        email="test@example.com",
-        display_name="测试用户",
-    )
-    return AuthenticatedUser(user=user)
-
-
-def _create_test_app():
-    """创建带 stub 注入的测试 FastAPI 应用"""
-    import app.services.edit_plan_service as service_module
-    from app.api.routes import edit_plans as edit_plans_module
-    from app.api.routes.edit_plans import router
-
-    stub_repo = StubEditPlanRepository()
-
-    # 替换服务模块中的 Repository 类
-    original_plan_repo_class = service_module.SQLAlchemyEditPlanRepository
-    original_clip_repo_class = service_module.SQLAlchemyEditPlanClipRepository
-    original_generation_task_repo_class = service_module.SQLAlchemyGenerationTaskRepository
-    service_module.SQLAlchemyEditPlanRepository = lambda db: stub_repo
-    service_module.SQLAlchemyEditPlanClipRepository = lambda db: stub_repo
-    service_module.SQLAlchemyGenerationTaskRepository = lambda db: stub_repo
-
-    app = FastAPI()
-    app.include_router(router, prefix="/api/v1/edit-plans")
-
-    # 覆盖认证依赖
-    app.dependency_overrides[edit_plans_module.get_current_user] = _make_auth_user
-    app.dependency_overrides[edit_plans_module.get_db_session] = lambda: MagicMock()
-
-    def cleanup():
-        service_module.SQLAlchemyEditPlanRepository = original_plan_repo_class
-        service_module.SQLAlchemyEditPlanClipRepository = original_clip_repo_class
-        service_module.SQLAlchemyGenerationTaskRepository = original_generation_task_repo_class
-
-    return app, stub_repo, cleanup
-
-
-@pytest.fixture
-def client():
-    app, stub_repo, cleanup = _create_test_app()
-    yield TestClient(app), stub_repo
-    cleanup()
-
-
-# ---------------------------------------------------------------------------
-# 创建测试
-# ---------------------------------------------------------------------------
-
-
-class TestCreatePlan:
-    """创建剪辑计划测试。
-
-    注意：创建计划时会从模板生成 clips，这里 mock 掉模板服务和生成器，
-    专注验证 API 层参数传递和响应格式。
-    """
-
-    def _make_test_plan(self, plan_id="plan-001", template_id="tpl-001", name="测试计划"):
-        """构造一个测试用 EditPlan"""
-        return EditPlan.create(
-            template_id=template_id,
-            name=name,
-            config=normalize_plan_config({}),
-            total_duration=15.0,
-        )
-
-    @patch("app.api.routes.edit_plans.EditTemplateService")
-    @patch("app.services.PlanGeneratorService")
-    def test_create_success(self, mock_generator_cls, mock_template_svc_cls, client):
-        c, repo = client
-
-        # Setup mock 模板服务
-        mock_template_svc = MagicMock()
-        mock_template_svc.get_template_or_raise.return_value = MagicMock(
-            id="tpl-001",
-            name="测试模板",
-            config={},
-        )
-        mock_template_svc.list_clip_configs.return_value = []
-        mock_template_svc_cls.return_value = mock_template_svc
-
-        # Setup mock 生成器
-        mock_gen = MagicMock()
-        test_plan = self._make_test_plan(name="我的剪辑计划")
-        test_plan.status = EditPlanStatus.EDITING
-        # 把 plan 存到 stub repo，这样后续 update_plan 能找到
-        repo.create(test_plan)
-        mock_gen.generate_from_template.return_value = {
-            "plan": test_plan,
-            "clips": [],
-        }
-        mock_generator_cls.return_value = mock_gen
-
-        resp = c.post(
-            "/api/v1/edit-plans",
-            json={
-                "template_id": "tpl-001",
-                "name": "我的剪辑计划",
-                "config": {"bgm": {"enabled": True}},
-                "total_duration": 60.0,
-            },
-        )
-        assert resp.status_code == 201
-        data = resp.json()
-        assert data["name"] == "我的剪辑计划"
-        assert data["template_id"] == "tpl-001"
-        assert "id" in data
-        assert "created_at" in data
-
-        # 验证调用了生成器
-        mock_gen.generate_from_template.assert_called_once()
-        call_kwargs = mock_gen.generate_from_template.call_args[1]
-        assert call_kwargs["template"].id == "tpl-001"
-        assert call_kwargs["name"] == "我的剪辑计划"
-        assert call_kwargs["created_by_user_id"] == "user-001"
-
-    @patch("app.api.routes.edit_plans.EditTemplateService")
-    @patch("app.services.PlanGeneratorService")
-    def test_create_with_asset_ids(self, mock_generator_cls, mock_template_svc_cls, client):
-        """创建计划时传入 asset_ids，应传递给生成器并写入 plan.config"""
-        c, repo = client
-
-        mock_template_svc = MagicMock()
-        mock_template_svc.get_template_or_raise.return_value = MagicMock(
-            id="tpl-001",
-            name="测试模板",
-            config={},
-        )
-        mock_template_svc.list_clip_configs.return_value = []
-        mock_template_svc_cls.return_value = mock_template_svc
-
-        mock_gen = MagicMock()
-        test_plan = self._make_test_plan(name="带素材计划")
-        test_plan.status = EditPlanStatus.EDITING
-        repo.create(test_plan)
-        mock_gen.generate_from_template.return_value = {
-            "plan": test_plan,
-            "clips": [],
-        }
-        mock_generator_cls.return_value = mock_gen
-
-        asset_ids = ["asset-001", "asset-002", "asset-003"]
-        resp = c.post(
-            "/api/v1/edit-plans",
-            json={
-                "template_id": "tpl-001",
-                "name": "带素材计划",
-                "asset_ids": asset_ids,
-            },
-        )
-        assert resp.status_code == 201
-
-        # 验证 asset_ids 传递给了生成器
-        mock_gen.generate_from_template.assert_called_once()
-        call_kwargs = mock_gen.generate_from_template.call_args[1]
-        assert call_kwargs["asset_ids"] == asset_ids
-
-    @patch("app.api.routes.edit_plans.EditTemplateService")
-    @patch("app.services.PlanGeneratorService")
-    def test_create_minimal(self, mock_generator_cls, mock_template_svc_cls, client):
-        c, repo = client
-
-        mock_template_svc = MagicMock()
-        mock_template_svc.get_template_or_raise.return_value = MagicMock(
-            id="tpl-001",
-            name="测试模板",
-            config={},
-        )
-        mock_template_svc.list_clip_configs.return_value = []
-        mock_template_svc_cls.return_value = mock_template_svc
-
-        mock_gen = MagicMock()
-        test_plan = self._make_test_plan()
-        test_plan.status = EditPlanStatus.EDITING
-        # 把 plan 存到 stub repo
-        repo.create(test_plan)
-        mock_gen.generate_from_template.return_value = {
-            "plan": test_plan,
-            "clips": [],
-        }
-        mock_generator_cls.return_value = mock_gen
-
-        resp = c.post(
-            "/api/v1/edit-plans",
-            json={"template_id": "tpl-001", "name": "最小计划"},
-        )
-        assert resp.status_code == 201
-        data = resp.json()
-        assert "id" in data
-
-        # 验证生成器被调用
-        mock_gen.generate_from_template.assert_called_once()
-
-    @patch("app.api.routes.edit_plans.EditTemplateService")
-    def test_create_template_not_found_falls_back_empty(self, mock_template_svc_cls, client):
-        """模板不存在时降级为空计划（向后兼容）"""
-        c, repo = client
-
-        mock_template_svc = MagicMock()
-        mock_template_svc.get_template_or_raise.side_effect = ValueError("模板不存在")
-        mock_template_svc_cls.return_value = mock_template_svc
-
-        resp = c.post(
-            "/api/v1/edit-plans",
-            json={"template_id": "nonexistent", "name": "测试"},
-        )
-        assert resp.status_code == 201
-        data = resp.json()
-        assert data["name"] == "测试"
-        assert data["template_id"] == "nonexistent"
-        # 空计划没有片段
-        assert "clips" not in data or len(data.get("clips", [])) == 0
-
-    def test_create_empty_name_returns_422(self, client):
-        c, repo = client
-        resp = c.post(
-            "/api/v1/edit-plans",
-            json={"template_id": "tpl-001", "name": ""},
-        )
-        assert resp.status_code == 422
-
-    def test_create_missing_template_id_returns_422(self, client):
-        c, repo = client
-        resp = c.post(
-            "/api/v1/edit-plans",
-            json={"name": "没有模板的计划"},
-        )
-        assert resp.status_code == 422
-
-    def test_create_negative_duration_returns_422(self, client):
-        c, repo = client
-        resp = c.post(
-            "/api/v1/edit-plans",
-            json={"template_id": "tpl-001", "name": "test", "total_duration": -1.0},
-        )
-        assert resp.status_code == 422
-
-
-# ---------------------------------------------------------------------------
-# 列表测试
-# ---------------------------------------------------------------------------
-
-
-class TestListPlans:
-    def _seed_plans(self, repo, count=3, template_id="tpl-001"):
-        for i in range(count):
-            plan = EditPlan.create(
-                template_id=template_id,
-                name=f"计划{i+1}",
-                config={"index": i},
-            )
-            repo.create(plan)
-        return plan
-
-    def test_list_empty(self, client):
-        c, repo = client
-        resp = c.get("/api/v1/edit-plans")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["items"] == []
-        assert data["total"] == 0
-        assert data["page"] == 1
-        assert data["page_size"] == 20
-
-    def test_list_with_items(self, client):
-        c, repo = client
-        self._seed_plans(repo, count=3)
-        resp = c.get("/api/v1/edit-plans")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert len(data["items"]) == 3
-        assert data["total"] == 3
-
-    def test_list_pagination(self, client):
-        c, repo = client
-        self._seed_plans(repo, count=5)
-        resp = c.get("/api/v1/edit-plans?page=1&page_size=2")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert len(data["items"]) == 2
-        assert data["total"] == 5
-        assert data["page"] == 1
-
-        resp2 = c.get("/api/v1/edit-plans?page=3&page_size=2")
-        data2 = resp2.json()
-        assert len(data2["items"]) == 1
-
-    def test_list_filter_by_status(self, client):
-        c, repo = client
-        p1 = EditPlan.create("tpl-001", "计划A")
-        repo.create(p1)
-        p2 = EditPlan.create("tpl-001", "计划B")
-        repo.create(p2)
-        p2.start_editing()
-        repo.update(p2)
-
-        resp = c.get("/api/v1/edit-plans?status=draft")
-        data = resp.json()
-        assert data["total"] == 1
-        assert data["items"][0]["name"] == "计划A"
-
-        resp2 = c.get("/api/v1/edit-plans?status=editing")
-        data2 = resp2.json()
-        assert data2["total"] == 1
-        assert data2["items"][0]["name"] == "计划B"
-
-    def test_list_filter_by_template_id(self, client):
-        c, repo = client
-        p1 = EditPlan.create("tpl-001", "模板1计划")
-        repo.create(p1)
-        p2 = EditPlan.create("tpl-002", "模板2计划")
-        repo.create(p2)
-
-        resp = c.get("/api/v1/edit-plans?template_id=tpl-001")
-        data = resp.json()
-        assert data["total"] == 1
-        assert data["items"][0]["name"] == "模板1计划"
-
-    def test_list_filter_by_template_and_status(self, client):
-        c, repo = client
-        p1 = EditPlan.create("tpl-001", "模板1草稿")
-        repo.create(p1)
-        p2 = EditPlan.create("tpl-001", "模板1编辑中")
-        repo.create(p2)
-        p2.start_editing()
-        repo.update(p2)
-        p3 = EditPlan.create("tpl-002", "模板2草稿")
-        repo.create(p3)
-
-        resp = c.get("/api/v1/edit-plans?template_id=tpl-001&status=draft")
-        data = resp.json()
-        assert data["total"] == 1
-        assert data["items"][0]["name"] == "模板1草稿"
-
-    def test_list_invalid_status_returns_400(self, client):
-        c, repo = client
-        resp = c.get("/api/v1/edit-plans?status=invalid_status")
-        assert resp.status_code == 400
-        assert "无效" in resp.json()["detail"]
-
-
-# ---------------------------------------------------------------------------
-# 详情测试
-# ---------------------------------------------------------------------------
-
-
-class TestGetPlan:
-    def test_get_success(self, client):
-        c, repo = client
-        plan = EditPlan.create("tpl-001", "测试计划", config={"key": "val"})
-        repo.create(plan)
-
-        resp = c.get(f"/api/v1/edit-plans/{plan.id}")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["id"] == plan.id
-        assert data["name"] == "测试计划"
-        assert data["config"] == {"key": "val"}
-
-    def test_get_not_found_returns_404(self, client):
-        c, repo = client
-        resp = c.get("/api/v1/edit-plans/nonexistent-id")
-        assert resp.status_code == 404
-        assert "剪辑计划不存在" in resp.json()["detail"]
-
-    def test_get_plan_rendered_url_is_signed(self, client):
-        """plan详情接口返回的rendered_url应该是签名URL，不是裸OSS URL"""
-        c, repo = client
-        raw_url = "https://bucket.oss-cn-hangzhou.aliyuncs.com/rendered/plan-001/output.mp4"
-        signed_url = raw_url + "?OSSAccessKeyId=xxx&Expires=123456&Signature=yyy"
-        plan = EditPlan.create("tpl-001", "测试计划", config={"rendered_url": raw_url, "other": "val"})
-        plan.status = EditPlanStatus.COMPLETED
-        repo.create(plan)
-
-        mock_storage = MagicMock()
-        mock_storage.get_download_url.return_value = signed_url
-        with patch("app.api.routes.edit_plans.get_storage_service", return_value=mock_storage):
-            resp = c.get(f"/api/v1/edit-plans/{plan.id}")
-
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["config"]["rendered_url"] == signed_url
-        assert data["config"]["other"] == "val"
-        mock_storage.get_download_url.assert_called_once_with(raw_url, expires_seconds=86400)
-
-    def test_list_plans_rendered_url_is_signed(self, client):
-        """plan列表接口返回的rendered_url也应该是签名URL"""
-        c, repo = client
-        raw_url = "https://bucket.oss-cn-hangzhou.aliyuncs.com/rendered/plan-list/output.mp4"
-        signed_url = raw_url + "?OSSAccessKeyId=xxx&Expires=123456&Signature=yyy"
-        plan = EditPlan.create("tpl-001", "测试计划", config={"rendered_url": raw_url})
-        plan.status = EditPlanStatus.COMPLETED
-        repo.create(plan)
-
-        mock_storage = MagicMock()
-        mock_storage.get_download_url.return_value = signed_url
-        with patch("app.api.routes.edit_plans.get_storage_service", return_value=mock_storage):
-            resp = c.get("/api/v1/edit-plans")
-
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["items"][0]["config"]["rendered_url"] == signed_url
-
-    def test_get_plan_no_rendered_url_skips_signing(self, client):
-        """没有rendered_url的计划不调用签名服务"""
-        c, repo = client
-        plan = EditPlan.create("tpl-001", "测试计划", config={"key": "val"})
-        repo.create(plan)
-
-        mock_storage = MagicMock()
-        with patch("app.api.routes.edit_plans.get_storage_service", return_value=mock_storage):
-            resp = c.get(f"/api/v1/edit-plans/{plan.id}")
-
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["config"] == {"key": "val"}
-        mock_storage.get_download_url.assert_not_called()
-
-
-# ---------------------------------------------------------------------------
-# 更新测试
-# ---------------------------------------------------------------------------
-
-
-class TestUpdatePlan:
-    def _seed_plan(self, repo, name="原计划", template_id="tpl-001"):
-        plan = EditPlan.create(template_id, name)
-        repo.create(plan)
-        return plan
-
-    def test_update_name(self, client):
-        c, repo = client
-        plan = self._seed_plan(repo)
-
-        resp = c.put(f"/api/v1/edit-plans/{plan.id}", json={"name": "新名称"})
-        assert resp.status_code == 200
-        assert resp.json()["name"] == "新名称"
-
-    def test_update_config(self, client):
-        c, repo = client
-        plan = self._seed_plan(repo)
-
-        resp = c.put(
-            f"/api/v1/edit-plans/{plan.id}",
-            json={"config": {"bgm": "sad", "transition": "fade"}},
-        )
-        assert resp.status_code == 200
-        assert resp.json()["config"] == normalize_plan_config({"bgm": "sad", "transition": "fade"})
-
-    def test_update_total_duration(self, client):
-        c, repo = client
-        plan = self._seed_plan(repo)
-
-        resp = c.put(f"/api/v1/edit-plans/{plan.id}", json={"total_duration": 120.5})
-        assert resp.status_code == 200
-        assert resp.json()["total_duration"] == 120.5
-
-    def test_update_status_draft_to_editing(self, client):
-        c, repo = client
-        plan = self._seed_plan(repo)
-        assert plan.status == EditPlanStatus.DRAFT
-
-        resp = c.put(f"/api/v1/edit-plans/{plan.id}", json={"status": "editing"})
-        assert resp.status_code == 200
-        assert resp.json()["status"] == "editing"
-
-    def test_update_status_full_happy_path(self, client):
-        c, repo = client
-        plan = self._seed_plan(repo)
-
-        # draft → editing
-        resp = c.put(f"/api/v1/edit-plans/{plan.id}", json={"status": "editing"})
-        assert resp.json()["status"] == "editing"
-
-        # editing → rendering
-        resp = c.put(f"/api/v1/edit-plans/{plan.id}", json={"status": "rendering"})
-        assert resp.json()["status"] == "rendering"
-
-        # rendering → completed
-        resp = c.put(f"/api/v1/edit-plans/{plan.id}", json={"status": "completed"})
-        assert resp.json()["status"] == "completed"
-
-    def test_update_status_failure_and_reset(self, client):
-        c, repo = client
-        plan = self._seed_plan(repo)
-
-        # draft → editing → rendering → failed
-        c.put(f"/api/v1/edit-plans/{plan.id}", json={"status": "editing"})
-        c.put(f"/api/v1/edit-plans/{plan.id}", json={"status": "rendering"})
-        resp = c.put(f"/api/v1/edit-plans/{plan.id}", json={"status": "failed"})
-        assert resp.json()["status"] == "failed"
-
-        # failed → draft (reset)
-        resp = c.put(f"/api/v1/edit-plans/{plan.id}", json={"status": "draft"})
-        assert resp.json()["status"] == "draft"
-
-    def test_update_invalid_transition_returns_400(self, client):
-        c, repo = client
-        plan = self._seed_plan(repo)
-
-        # draft → rendering 不合法
-        resp = c.put(f"/api/v1/edit-plans/{plan.id}", json={"status": "rendering"})
-        assert resp.status_code == 400
-
-    def test_update_draft_to_completed_returns_400(self, client):
-        c, repo = client
-        plan = self._seed_plan(repo)
-
-        # draft → completed 不合法
-        resp = c.put(f"/api/v1/edit-plans/{plan.id}", json={"status": "completed"})
-        assert resp.status_code == 400
-
-    def test_update_invalid_status_value_returns_400(self, client):
-        c, repo = client
-        plan = self._seed_plan(repo)
-
-        resp = c.put(f"/api/v1/edit-plans/{plan.id}", json={"status": "bogus"})
-        assert resp.status_code == 400
-        assert "无效" in resp.json()["detail"]
-
-    def test_update_same_status_is_noop(self, client):
-        c, repo = client
-        plan = self._seed_plan(repo)
-
-        resp = c.put(f"/api/v1/edit-plans/{plan.id}", json={"status": "draft"})
-        assert resp.status_code == 200
-        assert resp.json()["status"] == "draft"
-
-    def test_update_not_found_returns_404(self, client):
-        c, repo = client
-        resp = c.put("/api/v1/edit-plans/nonexistent", json={"name": "x"})
-        assert resp.status_code == 404
-
-    def test_update_combined_fields_and_status(self, client):
-        c, repo = client
-        plan = self._seed_plan(repo)
-
-        resp = c.put(
-            f"/api/v1/edit-plans/{plan.id}",
-            json={"name": "新名称", "status": "editing", "total_duration": 90.0},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["name"] == "新名称"
-        assert data["status"] == "editing"
-        assert data["total_duration"] == 90.0
-
-
-# ---------------------------------------------------------------------------
-# 删除测试
-# ---------------------------------------------------------------------------
-
-
-class TestDeletePlan:
-    def test_delete_success(self, client):
-        c, repo = client
-        plan = EditPlan.create("tpl-001", "待删除")
-        repo.create(plan)
-
-        resp = c.delete(f"/api/v1/edit-plans/{plan.id}")
-        assert resp.status_code == 204
-        assert repo.get(plan.id) is None
-
-    def test_delete_not_found_returns_404(self, client):
-        c, repo = client
-        resp = c.delete("/api/v1/edit-plans/nonexistent")
-        assert resp.status_code == 404
-        assert "剪辑计划不存在" in resp.json()["detail"]
-
-
-# ---------------------------------------------------------------------------
-# BGM 配置测试
-# ---------------------------------------------------------------------------
-
-
-class TestBGMConfig:
-    """BGM 配置 API 测试"""
-
-    def test_get_bgm_default_empty(self, client):
-        """新计划 BGM 默认为空"""
-        c, repo = client
-        plan = EditPlan.create("tpl-001", "测试")
-        repo.create(plan)
-
-        resp = c.get(f"/api/v1/edit-plans/{plan.id}/bgm")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["plan_id"] == plan.id
-        assert data["bgm"] == {}
-
-    def test_update_bgm_volume(self, client):
-        """更新 BGM 音量"""
-        c, repo = client
-        plan = EditPlan.create("tpl-001", "测试")
-        repo.create(plan)
-
-        resp = c.put(
-            f"/api/v1/edit-plans/{plan.id}/bgm",
-            json={"volume": 0.5, "fade_in": 2.0, "fade_out": 3.0},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["bgm"]["volume"] == 0.5
-        assert data["bgm"]["fade_in"] == 2.0
-        assert data["bgm"]["fade_out"] == 3.0
-
-    def test_enable_bgm_with_preset(self, client):
-        """启用 BGM 并指定 preset_id"""
-        c, repo = client
-        plan = EditPlan.create("tpl-001", "测试")
-        repo.create(plan)
-
-        resp = c.put(
-            f"/api/v1/edit-plans/{plan.id}/bgm",
-            json={
-                "enabled": True,
-                "source": "library",
-                "preset_id": "bgm_upbeat_001",
-                "volume": 0.3,
-            },
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["bgm"]["enabled"] is True
-        assert data["bgm"]["preset_id"] == "bgm_upbeat_001"
-
-    def test_enable_bgm_without_source_returns_400(self, client):
-        """启用 BGM 但不指定来源，返回 400"""
-        c, repo = client
-        plan = EditPlan.create("tpl-001", "测试")
-        repo.create(plan)
-
-        resp = c.put(
-            f"/api/v1/edit-plans/{plan.id}/bgm",
-            json={"enabled": True, "volume": 0.3},
-        )
-        assert resp.status_code == 400
-        assert "素材来源" in resp.json()["detail"]
-
-    def test_enable_bgm_with_asset_id(self, client):
-        """启用 BGM 并指定 asset_id"""
-        c, repo = client
-        plan = EditPlan.create("tpl-001", "测试")
-        repo.create(plan)
-
-        resp = c.put(
-            f"/api/v1/edit-plans/{plan.id}/bgm",
-            json={
-                "enabled": True,
-                "source": "upload",
-                "asset_id": "asset-audio-001",
-                "loop_enabled": True,
-            },
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["bgm"]["enabled"] is True
-        assert data["bgm"]["asset_id"] == "asset-audio-001"
-        assert data["bgm"]["loop_enabled"] is True
-
-    def test_update_bgm_not_found(self, client):
-        """不存在的计划返回 404"""
-        c, _ = client
-        resp = c.put(
-            "/api/v1/edit-plans/nonexistent/bgm",
-            json={"volume": 0.5},
-        )
-        assert resp.status_code == 404
-
-    def test_get_bgm_not_found(self, client):
-        """不存在的计划返回 404"""
-        c, _ = client
-        resp = c.get("/api/v1/edit-plans/nonexistent/bgm")
-        assert resp.status_code == 404
-
-    def test_partial_update_preserves_existing(self, client):
-        """部分更新保留原有配置"""
-        c, repo = client
-        plan = EditPlan.create("tpl-001", "测试")
-        plan.config = {"bgm": {"volume": 0.5, "fade_in": 1.0}}
-        repo.create(plan)
-
-        # 只改音量
-        resp = c.put(
-            f"/api/v1/edit-plans/{plan.id}/bgm",
-            json={"volume": 0.8},
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["bgm"]["volume"] == 0.8
-        assert data["bgm"]["fade_in"] == 1.0  # 保留
-
-    def test_sidechain_config(self, client):
-        """人声闪避配置更新"""
-        c, repo = client
-        plan = EditPlan.create("tpl-001", "测试")
-        repo.create(plan)
-
-        resp = c.put(
-            f"/api/v1/edit-plans/{plan.id}/bgm",
-            json={
-                "enabled": True,
-                "preset_id": "bgm_relax_001",
-                "sidechain_enabled": True,
-                "sidechain_ratio": 0.4,
-            },
-        )
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["bgm"]["sidechain_enabled"] is True
-        assert data["bgm"]["sidechain_ratio"] == 0.4
-
-
-# ---------------------------------------------------------------------------
-# BGM 预设库测试
-# ---------------------------------------------------------------------------
-
-
-class TestBGMPresets:
-    """BGM 预设列表 API 测试"""
-
-    def test_list_all_presets(self, client):
-        """获取所有预设 BGM"""
-        c, _ = client
-        resp = c.get("/api/v1/edit-plans/bgm/presets")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert "items" in data
-        assert "total" in data
-        assert "styles" in data
-        assert data["total"] >= 10  # 至少有 10 首预设
-        assert len(data["items"]) == data["total"]
-
-    def test_filter_by_style(self, client):
-        """按风格筛选"""
-        c, _ = client
-        resp = c.get("/api/v1/edit-plans/bgm/presets?style=upbeat")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] >= 3
-        for item in data["items"]:
-            assert item["style"] == "upbeat"
-
-    def test_search_by_keyword(self, client):
-        """关键词搜索"""
-        c, _ = client
-        resp = c.get("/api/v1/edit-plans/bgm/presets?keyword=钢琴")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert data["total"] >= 1
-        for item in data["items"]:
-            has_piano = (
-                "钢琴" in item["name"] or "钢琴" in item["description"] or any("钢琴" in tag for tag in item["tags"])
-            )
-            assert has_piano
-
-    def test_pagination(self, client):
-        """分页功能"""
-        c, _ = client
-        resp = c.get("/api/v1/edit-plans/bgm/presets?skip=0&limit=3")
-        assert resp.status_code == 200
-        data = resp.json()
-        assert len(data["items"]) == 3
-        assert data["skip"] == 0
-        assert data["limit"] == 3
-
-    def test_preset_structure(self, client):
-        """预设条目字段完整"""
-        c, _ = client
-        resp = c.get("/api/v1/edit-plans/bgm/presets?limit=1")
-        assert resp.status_code == 200
-        item = resp.json()["items"][0]
-
-        assert "id" in item
-        assert "name" in item
-        assert "style" in item
-        assert "style_label" in item
-        assert "duration" in item
-        assert "artist" in item
-        assert "description" in item
-        assert "tags" in item
-        assert isinstance(item["tags"], list)

tests/unit/test_edit_template_domain.py

@@ -0,0 +1,154 @@
+"""
+EditTemplate 剪辑模板领域模型单元测试
+"""
+
+import pytest
+
+from packages.domain.edit_template import EditTemplate, EditTemplateStatus
+from packages.domain.editing_mode import EditingMode
+
+
+class TestEditTemplateStatus:
+    """EditTemplateStatus 枚举测试"""
+
+    def test_status_values(self):
+        assert EditTemplateStatus.ACTIVE == "active"
+        assert EditTemplateStatus.INACTIVE == "inactive"
+
+
+class TestEditTemplateCreate:
+    """create 工厂方法测试"""
+
+    def test_create_minimal(self):
+        template = EditTemplate.create(name="测试模板")
+        assert template.id is not None
+        assert len(template.id) == 32
+        assert template.name == "测试模板"
+        assert template.description == ""
+        assert template.template_type == "default"
+        assert template.editing_mode == EditingMode.ONE_TAKE.value
+        assert template.config == {}
+        assert template.preview_url == ""
+        assert template.sort_weight == 0
+        assert template.status == EditTemplateStatus.ACTIVE
+        assert template.version == 1
+        assert template.created_at is not None
+        assert template.updated_at is not None
+
+    def test_create_with_all_fields(self):
+        template = EditTemplate.create(
+            name="口播模板",
+            description="适合口播类视频",
+            template_type="talking_head",
+            editing_mode=EditingMode.VOICE_OVER.value,
+            config={"aspect_ratio": "9:16", "duration": 60},
+            preview_url="https://example.com/preview.mp4",
+            sort_weight=100,
+            status=EditTemplateStatus.INACTIVE,
+            version=3,
+        )
+        assert template.name == "口播模板"
+        assert template.description == "适合口播类视频"
+        assert template.template_type == "talking_head"
+        assert template.editing_mode == EditingMode.VOICE_OVER.value
+        assert template.config == {"aspect_ratio": "9:16", "duration": 60}
+        assert template.preview_url == "https://example.com/preview.mp4"
+        assert template.sort_weight == 100
+        assert template.status == EditTemplateStatus.INACTIVE
+        assert template.version == 3
+
+    def test_create_strips_whitespace(self):
+        template = EditTemplate.create(
+            name="  我的模板  ",
+            description="  描述  ",
+            template_type="  ",
+            editing_mode="  ",
+            preview_url="  url  ",
+        )
+        assert template.name == "我的模板"
+        assert template.description == "描述"
+        assert template.template_type == "default"  # 空字符串回退到default
+        assert template.editing_mode == EditingMode.ONE_TAKE.value  # 空回退
+        assert template.preview_url == "url"
+
+    def test_create_empty_name_raises(self):
+        with pytest.raises(ValueError, match="模板名称不能为空"):
+            EditTemplate.create(name="   ")
+
+    def test_create_invalid_editing_mode_raises(self):
+        with pytest.raises(ValueError, match="无效的 editing_mode"):
+            EditTemplate.create(name="测试", editing_mode="invalid_mode")
+
+    def test_create_config_none(self):
+        template = EditTemplate.create(name="test", config=None)
+        assert template.config == {}
+        # 两个模板不共享同一个 dict
+        t2 = EditTemplate.create(name="test2")
+        assert template.config is not t2.config
+
+    def test_create_all_editing_modes(self):
+        """所有合法 editing_mode 都能创建"""
+        for mode in EditingMode:
+            template = EditTemplate.create(name=f"test_{mode.value}", editing_mode=mode.value)
+            assert template.editing_mode == mode.value
+
+
+class TestEditTemplateActivateDeactivate:
+    """激活/停用测试"""
+
+    def test_activate_from_inactive(self):
+        template = EditTemplate.create(name="test", status=EditTemplateStatus.INACTIVE)
+        old_updated = template.updated_at
+        template.activate()
+        assert template.status == EditTemplateStatus.ACTIVE
+        assert template.updated_at >= old_updated
+
+    def test_activate_from_active(self):
+        template = EditTemplate.create(name="test")
+        template.activate()
+        assert template.status == EditTemplateStatus.ACTIVE
+
+    def test_deactivate_from_active(self):
+        template = EditTemplate.create(name="test")
+        template.deactivate()
+        assert template.status == EditTemplateStatus.INACTIVE
+
+    def test_deactivate_from_inactive(self):
+        template = EditTemplate.create(name="test", status=EditTemplateStatus.INACTIVE)
+        template.deactivate()
+        assert template.status == EditTemplateStatus.INACTIVE
+
+
+class TestEditTemplateIsActive:
+    """is_active 属性测试"""
+
+    def test_is_active_true(self):
+        template = EditTemplate.create(name="test")
+        assert template.is_active is True
+
+    def test_is_active_false(self):
+        template = EditTemplate.create(name="test", status=EditTemplateStatus.INACTIVE)
+        assert template.is_active is False
+
+
+class TestEditTemplateBumpVersion:
+    """版本号递增测试"""
+
+    def test_bump_version_increments(self):
+        template = EditTemplate.create(name="test", version=1)
+        old_updated = template.updated_at
+        template.bump_version()
+        assert template.version == 2
+        assert template.updated_at >= old_updated
+
+    def test_bump_version_multiple(self):
+        template = EditTemplate.create(name="test", version=5)
+        template.bump_version()
+        template.bump_version()
+        assert template.version == 7
+
+    def test_bump_version_updates_timestamp(self):
+        template = EditTemplate.create(name="test")
+        old_updated = template.updated_at
+        template.bump_version()
+        assert template.updated_at > old_updated or template.updated_at == old_updated

tests/unit/test_edit_template_service.py

@@ -167,7 +167,7 @@ class StubTemplateClipConfigRepository:
     def delete(self, config_id: str) -> bool:
         return self._configs.pop(config_id, None) is not None
 
-    def delete_by_template(self, template_id: str) -> int:
+    def delete_by_template(self, template_id: str, *, commit: bool = True) -> int:
         ids = [cid for cid, c in self._configs.items() if c.template_id == template_id]
         for cid in ids:
             del self._configs[cid]

tests/unit/test_editing_mode_domain.py

@@ -0,0 +1,40 @@
+"""
+EditingMode 剪辑模式枚举单元测试
+"""
+
+from packages.domain.editing_mode import EditingMode
+
+
+class TestEditingMode:
+    """EditingMode 枚举测试"""
+
+    def test_all_modes_exist(self):
+        assert EditingMode.ONE_TAKE == "one_take"
+        assert EditingMode.PIP == "pip"
+        assert EditingMode.VOICE_OVER == "voice_over"
+        assert EditingMode.VOICE_PIP == "voice_pip"
+
+    def test_total_count(self):
+        assert len(EditingMode) == 4
+
+    def test_is_string_type(self):
+        for mode in EditingMode:
+            assert isinstance(mode.value, str)
+            assert isinstance(mode, str)
+
+    def test_mode_descriptions(self):
+        """验证模式值有意义"""
+        assert "one" in EditingMode.ONE_TAKE
+        assert "pip" in EditingMode.PIP
+        assert "voice" in EditingMode.VOICE_OVER
+        assert "voice" in EditingMode.VOICE_PIP
+
+    def test_usage_in_comparison(self):
+        mode = EditingMode.ONE_TAKE
+        assert mode == "one_take"
+        assert mode != "pip"
+
+    def test_iterable(self):
+        modes = list(EditingMode)
+        assert len(modes) == 4
+        assert EditingMode.ONE_TAKE in modes

tests/unit/test_feature_flags_infra.py

@@ -0,0 +1,347 @@
+"""
+Feature Flags 基础设施层单元测试
+"""
+
+import pytest
+
+from packages.infrastructure.feature_flags import (
+    FeatureFlag,
+    FeatureFlags,
+    FeatureScope,
+    feature_flags,
+)
+
+
+class TestFeatureFlag:
+    """FeatureFlag 单个开关测试"""
+
+    def test_default_values(self):
+        """测试默认值"""
+        flag = FeatureFlag(name="test_flag")
+        assert flag.name == "test_flag"
+        assert flag.description == ""
+        assert flag.global_enabled is True
+        assert flag.plan_overrides == {}
+        assert flag.user_overrides == {}
+
+    def test_is_enabled_global_true(self):
+        """测试全局启用"""
+        flag = FeatureFlag(name="test", global_enabled=True)
+        assert flag.is_enabled() is True
+
+    def test_is_enabled_global_false(self):
+        """测试全局禁用"""
+        flag = FeatureFlag(name="test", global_enabled=False)
+        assert flag.is_enabled() is False
+
+    def test_is_enabled_plan_override(self):
+        """测试套餐级别覆盖"""
+        flag = FeatureFlag(
+            name="test",
+            global_enabled=True,
+            plan_overrides={"free": False, "premium": True},
+        )
+        # free 套餐被覆盖为 False
+        assert flag.is_enabled(user_plan="free") is False
+        # premium 套餐覆盖为 True
+        assert flag.is_enabled(user_plan="premium") is True
+        # 没有覆盖的套餐用全局值
+        assert flag.is_enabled(user_plan="basic") is True
+
+    def test_is_enabled_user_override_priority(self):
+        """测试用户白名单优先级最高"""
+        flag = FeatureFlag(
+            name="test",
+            global_enabled=False,
+            plan_overrides={"premium": True},
+            user_overrides={"user-1": True, "user-2": False},
+        )
+        # 用户白名单 True → 全局禁用也能启用
+        assert flag.is_enabled(user_plan="free", user_id="user-1") is True
+        # 用户白名单 False → premium 套餐也禁用
+        assert flag.is_enabled(user_plan="premium", user_id="user-2") is False
+        # 没有用户白名单 → 走套餐级别
+        assert flag.is_enabled(user_plan="premium", user_id="user-3") is True
+
+    def test_is_enabled_no_params(self):
+        """测试不传任何参数时使用全局值"""
+        flag = FeatureFlag(name="test", global_enabled=True)
+        assert flag.is_enabled() is True
+
+    def test_is_enabled_empty_strings_treated_as_none(self):
+        """测试空字符串 user_id/user_plan 不触发覆盖"""
+        flag = FeatureFlag(
+            name="test",
+            global_enabled=True,
+            plan_overrides={"free": False},
+            user_overrides={"": True},  # 空字符串key
+        )
+        # 空字符串 user_id 被当作 falsy，不走用户白名单分支
+        assert flag.is_enabled(user_id="", user_plan="") is True
+
+    def test_plan_override_does_not_affect_other_plans(self):
+        """测试套餐覆盖不影响其他套餐"""
+        flag = FeatureFlag(
+            name="test",
+            global_enabled=True,
+            plan_overrides={"free": False},
+        )
+        assert flag.is_enabled(user_plan="free") is False
+        assert flag.is_enabled(user_plan="basic") is True
+        assert flag.is_enabled(user_plan="premium") is True
+
+    def test_user_override_can_enable_for_disabled_plan(self):
+        """测试用户白名单可以为被禁用的套餐用户单独启用"""
+        flag = FeatureFlag(
+            name="test",
+            global_enabled=False,
+            plan_overrides={"premium": True},
+            user_overrides={"special-user": True},
+        )
+        # free 套餐用户 + 白名单 → 启用
+        assert flag.is_enabled(user_plan="free", user_id="special-user") is True
+
+    def test_user_override_can_disable_for_enabled_plan(self):
+        """测试用户白名单可以为启用套餐的用户单独禁用"""
+        flag = FeatureFlag(
+            name="test",
+            global_enabled=True,
+            user_overrides={"bad-user": False},
+        )
+        assert flag.is_enabled(user_id="bad-user") is False
+
+
+class TestFeatureScope:
+    """FeatureScope 常量测试"""
+
+    def test_scope_constants(self):
+        """测试所有常量存在"""
+        assert FeatureScope.AI_VOICE_GENERATION == "ai_voice_generation"
+        assert FeatureScope.DEDUPLICATION_REPORT == "deduplication_report"
+        assert FeatureScope.BATCH_EXPORT == "batch_export"
+        assert FeatureScope.MULTI_PLATFORM_OUTPUT == "multi_platform_output"
+        assert FeatureScope.RECIPE_REUSE == "recipe_reuse"
+
+
+class TestFeatureFlags:
+    """FeatureFlags 管理器测试"""
+
+    @pytest.fixture
+    def flags(self):
+        """创建新的 FeatureFlags 实例（不影响全局单例）"""
+        return FeatureFlags()
+
+    # ===== 初始化 =====
+
+    def test_default_flags_exist(self, flags):
+        """测试默认 flags 已注册"""
+        all_flags = flags.list_flags()
+        assert FeatureScope.AI_VOICE_GENERATION in all_flags
+        assert FeatureScope.DEDUPLICATION_REPORT in all_flags
+        assert FeatureScope.BATCH_EXPORT in all_flags
+        assert FeatureScope.MULTI_PLATFORM_OUTPUT in all_flags
+        assert FeatureScope.RECIPE_REUSE in all_flags
+
+    def test_default_ai_voice_generation(self, flags):
+        """测试 AI 配音功能默认配置"""
+        # free 套餐不可用
+        assert flags.is_enabled("ai_voice_generation", user_plan="free") is False
+        # basic 套餐可用
+        assert flags.is_enabled("ai_voice_generation", user_plan="basic") is True
+        # premium 套餐可用
+        assert flags.is_enabled("ai_voice_generation", user_plan="premium") is True
+
+    def test_default_deduplication_report(self, flags):
+        """测试去重报告默认配置（仅 premium）"""
+        assert flags.is_enabled("deduplication_report", user_plan="free") is False
+        assert flags.is_enabled("deduplication_report", user_plan="basic") is False
+        assert flags.is_enabled("deduplication_report", user_plan="premium") is True
+
+    def test_default_multi_platform_output(self, flags):
+        """测试多平台输出默认配置（仅 premium）"""
+        assert flags.is_enabled("multi_platform_output", user_plan="free") is False
+        assert flags.is_enabled("multi_platform_output", user_plan="basic") is False
+        assert flags.is_enabled("multi_platform_output", user_plan="premium") is True
+
+    def test_default_batch_export(self, flags):
+        """测试批量导出默认配置"""
+        assert flags.is_enabled("batch_export", user_plan="free") is False
+        assert flags.is_enabled("batch_export", user_plan="basic") is True
+        assert flags.is_enabled("batch_export", user_plan="premium") is True
+
+    def test_default_recipe_reuse(self, flags):
+        """测试配方复用默认配置"""
+        assert flags.is_enabled("recipe_reuse", user_plan="free") is False
+        assert flags.is_enabled("recipe_reuse", user_plan="basic") is True
+        assert flags.is_enabled("recipe_reuse", user_plan="premium") is True
+
+    # ===== 注册新 flag =====
+
+    def test_register_new_flag(self, flags):
+        """测试注册新的 feature flag"""
+        new_flag = FeatureFlag(name="new_feature", description="新功能", global_enabled=False)
+        flags.register(new_flag)
+
+        assert flags.get("new_feature") is not None
+        assert flags.get("new_feature").description == "新功能"
+        assert flags.is_enabled("new_feature") is False
+
+    def test_register_overwrites_existing(self, flags):
+        """测试注册同名 flag 会覆盖"""
+        flag1 = FeatureFlag(name="test", global_enabled=True, description="v1")
+        flags.register(flag1)
+        assert flags.get("test").description == "v1"
+
+        flag2 = FeatureFlag(name="test", global_enabled=False, description="v2")
+        flags.register(flag2)
+        assert flags.get("test").description == "v2"
+        assert flags.is_enabled("test") is False
+
+    # ===== get 方法 =====
+
+    def test_get_existing_flag(self, flags):
+        """测试获取存在的 flag"""
+        flag = flags.get("ai_voice_generation")
+        assert flag is not None
+        assert flag.name == "ai_voice_generation"
+
+    def test_get_nonexistent_flag(self, flags):
+        """测试获取不存在的 flag 返回 None"""
+        assert flags.get("nonexistent") is None
+
+    # ===== is_enabled 方法 =====
+
+    def test_is_enabled_nonexistent_flag_returns_false(self, flags):
+        """测试不存在的 flag 返回 False"""
+        assert flags.is_enabled("nonexistent_flag") is False
+
+    def test_is_enabled_without_plan_or_user(self, flags):
+        """测试不传套餐和用户ID"""
+        assert flags.is_enabled("ai_voice_generation") is True
+
+    # ===== set_global =====
+
+    def test_set_global_enable(self, flags):
+        """测试设置全局启用"""
+        flags.set_global("ai_voice_generation", enabled=False)
+        assert flags.is_enabled("ai_voice_generation", user_plan="premium") is False
+
+    def test_set_global_disable(self, flags):
+        """测试设置全局禁用"""
+        flags.set_global("deduplication_report", enabled=False)
+        assert flags.is_enabled("deduplication_report", user_plan="premium") is False
+
+    def test_set_global_nonexistent_raises(self, flags):
+        """测试设置不存在的 flag 抛出异常"""
+        with pytest.raises(KeyError, match="not found"):
+            flags.set_global("nonexistent", enabled=True)
+
+    # ===== set_plan_override =====
+
+    def test_set_plan_override(self, flags):
+        """测试设置套餐覆盖"""
+        # 先确认 basic 套餐默认是去重报告禁用
+        assert flags.is_enabled("deduplication_report", user_plan="basic") is False
+
+        flags.set_plan_override("deduplication_report", "basic", True)
+        assert flags.is_enabled("deduplication_report", user_plan="basic") is True
+
+    def test_set_plan_override_nonexistent_raises(self, flags):
+        """测试设置不存在 flag 的套餐覆盖抛出异常"""
+        with pytest.raises(KeyError, match="not found"):
+            flags.set_plan_override("nonexistent", "free", True)
+
+    # ===== set_user_override =====
+
+    def test_set_user_override_enable(self, flags):
+        """测试设置用户白名单启用"""
+        assert flags.is_enabled("deduplication_report", user_plan="free", user_id="user-1") is False
+
+        flags.set_user_override("deduplication_report", "user-1", True)
+        assert flags.is_enabled("deduplication_report", user_plan="free", user_id="user-1") is True
+
+    def test_set_user_override_disable(self, flags):
+        """测试设置用户白名单禁用"""
+        assert flags.is_enabled("batch_export", user_plan="premium", user_id="user-2") is True
+
+        flags.set_user_override("batch_export", "user-2", False)
+        assert flags.is_enabled("batch_export", user_plan="premium", user_id="user-2") is False
+
+    def test_set_user_override_nonexistent_raises(self, flags):
+        """测试设置不存在 flag 的用户覆盖抛出异常"""
+        with pytest.raises(KeyError, match="not found"):
+            flags.set_user_override("nonexistent", "user-1", True)
+
+    # ===== list_flags =====
+
+    def test_list_flags_returns_copy(self, flags):
+        """测试 list_flags 返回副本"""
+        all_flags = flags.list_flags()
+        all_flags["fake"] = FeatureFlag(name="fake")
+
+        # 原注册表不应被修改
+        assert "fake" not in flags.list_flags()
+
+    def test_list_flags_count(self, flags):
+        """测试默认 flag 数量"""
+        all_flags = flags.list_flags()
+        assert len(all_flags) == 5  # 5 个默认 flag
+
+    # ===== get_enabled_for_plan =====
+
+    def test_get_enabled_for_free_plan(self, flags):
+        """测试 free 套餐启用的功能"""
+        enabled = flags.get_enabled_for_plan("free")
+        # free 套餐应该只有 0 个默认启用的功能？不对，让我看看...
+        # 所有5个默认功能 free 套餐都是 False 吗？
+        # AI_VOICE_GENERATION: free=False
+        # DEDUPLICATION_REPORT: free=False, basic=False
+        # BATCH_EXPORT: free=False
+        # MULTI_PLATFORM_OUTPUT: free=False, basic=False
+        # RECIPE_REUSE: free=False
+        # 所以 free 套餐一个都没有？
+        assert len(enabled) == 0
+
+    def test_get_enabled_for_premium_plan(self, flags):
+        """测试 premium 套餐启用的功能"""
+        enabled = flags.get_enabled_for_plan("premium")
+        # premium 套餐所有功能都应该启用
+        assert len(enabled) == 5
+        assert "ai_voice_generation" in enabled
+        assert "deduplication_report" in enabled
+        assert "batch_export" in enabled
+        assert "multi_platform_output" in enabled
+        assert "recipe_reuse" in enabled
+
+    def test_get_enabled_for_basic_plan(self, flags):
+        """测试 basic 套餐启用的功能"""
+        enabled = flags.get_enabled_for_plan("basic")
+        # basic: ai_voice=True, dedup=False, batch=True, multi=False, recipe=True
+        assert "ai_voice_generation" in enabled
+        assert "deduplication_report" not in enabled
+        assert "batch_export" in enabled
+        assert "multi_platform_output" not in enabled
+        assert "recipe_reuse" in enabled
+        assert len(enabled) == 3
+
+
+class TestGlobalSingleton:
+    """全局单例测试"""
+
+    def test_global_singleton_exists(self):
+        """测试全局单例存在"""
+        assert feature_flags is not None
+        assert isinstance(feature_flags, FeatureFlags)
+
+    def test_global_singleton_has_defaults(self):
+        """测试全局单例有默认配置"""
+        assert feature_flags.get("ai_voice_generation") is not None
+        assert feature_flags.get("deduplication_report") is not None
+
+    def test_global_singleton_independent_from_new_instance(self):
+        """测试全局单例与新实例相互独立"""
+        new_flags = FeatureFlags()
+        new_flags.set_global("ai_voice_generation", False)
+
+        # 全局单例不应受影响
+        assert feature_flags.is_enabled("ai_voice_generation") is True

tests/unit/test_filter_presets_domain.py

@@ -0,0 +1,230 @@
+"""filter_presets 模块单元测试."""
+
+from dataclasses import FrozenInstanceError
+
+import pytest
+from domain.filter_presets import (
+    FILTER_PRESET_LIBRARY,
+    FilterPreset,
+    build_ffmpeg_filter,
+    get_filter_preset,
+    list_filter_presets,
+)
+
+
+class TestFilterPreset:
+    """FilterPreset 数据类测试."""
+
+    def test_create_required_fields(self):
+        f = FilterPreset(id="test_001", name="测试滤镜", category="basic")
+        assert f.id == "test_001"
+        assert f.name == "测试滤镜"
+        assert f.category == "basic"
+        # 默认值
+        assert f.description == ""
+        assert f.tags == []
+        assert f.brightness == 0.0
+        assert f.contrast == 1.0
+        assert f.saturation == 1.0
+        assert f.gamma == 1.0
+        assert f.gamma_r == 1.0
+        assert f.gamma_g == 1.0
+        assert f.gamma_b == 1.0
+        assert f.hue == 0.0
+        assert f.lut_url == ""
+
+    def test_create_all_fields(self):
+        f = FilterPreset(
+            id="test_002",
+            name="完整滤镜",
+            category="cinematic",
+            description="测试描述",
+            tags=["标签1", "标签2"],
+            brightness=0.1,
+            contrast=1.2,
+            saturation=0.8,
+            gamma=1.1,
+            gamma_r=1.05,
+            gamma_g=0.95,
+            gamma_b=1.15,
+            hue=10.0,
+            lut_url="https://example.com/lut.png",
+        )
+        assert f.category == "cinematic"
+        assert f.brightness == 0.1
+        assert f.contrast == 1.2
+        assert f.saturation == 0.8
+        assert f.gamma == 1.1
+        assert f.gamma_r == 1.05
+        assert f.gamma_g == 0.95
+        assert f.gamma_b == 1.15
+        assert f.hue == 10.0
+        assert f.lut_url == "https://example.com/lut.png"
+
+    def test_frozen_immutable(self):
+        f = FilterPreset(id="test", name="测试", category="basic")
+        with pytest.raises(FrozenInstanceError):
+            f.name = "修改"  # type: ignore[misc]
+
+    def test_tags_default_new_list(self):
+        f1 = FilterPreset(id="1", name="a", category="basic")
+        f2 = FilterPreset(id="2", name="b", category="basic")
+        assert f1.tags is not f2.tags
+        assert f1.tags == []
+
+
+class TestFilterPresetLibrary:
+    """FILTER_PRESET_LIBRARY 预设库测试."""
+
+    def test_not_empty(self):
+        assert len(FILTER_PRESET_LIBRARY) > 0
+
+    def test_all_unique_ids(self):
+        ids = [f.id for f in FILTER_PRESET_LIBRARY]
+        assert len(ids) == len(set(ids))
+
+    def test_all_are_filter_preset_instances(self):
+        for f in FILTER_PRESET_LIBRARY:
+            assert isinstance(f, FilterPreset)
+
+    def test_contains_basic_category(self):
+        cats = {f.category for f in FILTER_PRESET_LIBRARY}
+        assert "basic" in cats
+
+    def test_none_filter_is_identity(self):
+        """filter_none 应该所有参数都是默认值（不改变画面）"""
+        f = get_filter_preset("filter_none")
+        assert f is not None
+        assert f.brightness == 0.0
+        assert f.contrast == 1.0
+        assert f.saturation == 1.0
+        assert f.gamma == 1.0
+
+
+class TestGetFilterPreset:
+    """get_filter_preset 函数测试."""
+
+    def test_existing_id(self):
+        f = get_filter_preset("filter_brighten")
+        assert f is not None
+        assert f.id == "filter_brighten"
+        assert f.name == "明亮"
+
+    def test_nonexistent_id(self):
+        assert get_filter_preset("nonexistent") is None
+
+    def test_empty_string(self):
+        assert get_filter_preset("") is None
+
+
+class TestListFilterPresets:
+    """list_filter_presets 函数测试."""
+
+    def test_no_filters_returns_all(self):
+        result = list_filter_presets()
+        assert len(result) == len(FILTER_PRESET_LIBRARY)
+
+    def test_filter_by_category_basic(self):
+        result = list_filter_presets(category="basic")
+        assert len(result) >= 4
+        for f in result:
+            assert f.category == "basic"
+
+    def test_filter_by_unknown_category_returns_empty(self):
+        result = list_filter_presets(category="nonexistent")
+        assert result == []
+
+    def test_filter_by_keyword_name(self):
+        result = list_filter_presets(keyword="明亮")
+        assert len(result) >= 1
+        assert any(f.name == "明亮" for f in result)
+
+    def test_filter_by_keyword_tag(self):
+        result = list_filter_presets(keyword="提亮")
+        assert len(result) >= 1
+
+    def test_filter_by_keyword_description(self):
+        result = list_filter_presets(keyword="偏暗")
+        assert len(result) >= 1
+
+    def test_filter_keyword_case_insensitive(self):
+        r1 = list_filter_presets(keyword="FILTER")
+        r2 = list_filter_presets(keyword="filter")
+        assert len(r1) == len(r2)
+
+    def test_filter_keyword_no_match(self):
+        result = list_filter_presets(keyword="xyz_nonexistent_12345")
+        assert result == []
+
+    def test_combined_category_and_keyword(self):
+        result = list_filter_presets(category="basic", keyword="明亮")
+        assert len(result) >= 1
+        for f in result:
+            assert f.category == "basic"
+
+    def test_combined_no_match(self):
+        result = list_filter_presets(category="basic", keyword="电影感")
+        # 基础分类里没有电影感关键词
+        pass  # 不做强断言，看实际数据
+
+
+class TestBuildFFmpegFilter:
+    """build_ffmpeg_filter 函数测试."""
+
+    def test_none_preset_returns_empty(self):
+        result = build_ffmpeg_filter("nonexistent")
+        assert result == ""
+
+    def test_zero_intensity_returns_empty(self):
+        result = build_ffmpeg_filter("filter_brighten", intensity=0)
+        assert result == ""
+
+    def test_negative_intensity_returns_empty(self):
+        result = build_ffmpeg_filter("filter_brighten", intensity=-10)
+        assert result == ""
+
+    def test_full_intensity_brighten(self):
+        result = build_ffmpeg_filter("filter_brighten", intensity=100)
+        assert result.startswith("eq=")
+        assert "brightness=0.120" in result
+        assert "contrast=1.050" in result
+        assert "saturation=1.050" in result
+        assert "gamma=1.100" in result
+
+    def test_half_intensity(self):
+        """强度 50% 时参数应该是全量的一半（向原值插值）"""
+        full = build_ffmpeg_filter("filter_brighten", intensity=100)
+        half = build_ffmpeg_filter("filter_brighten", intensity=50)
+
+        # 50% 强度的 brightness 应该是 0.060 (0.120 * 0.5)
+        assert "brightness=0.060" in half
+        # full 和 half 都应该有 eq= 前缀
+        assert full.startswith("eq=")
+        assert half.startswith("eq=")
+
+    def test_intensity_over_100_clamps_to_100(self):
+        result1 = build_ffmpeg_filter("filter_brighten", intensity=100)
+        result2 = build_ffmpeg_filter("filter_brighten", intensity=150)
+        assert result1 == result2
+
+    def test_filter_none_returns_empty(self):
+        """原图滤镜所有参数都是默认值，应该返回空字符串"""
+        result = build_ffmpeg_filter("filter_none")
+        assert result == ""
+
+    def test_warm_filter_has_gamma_channels(self):
+        """暖色滤镜应该调整 RGB 通道伽马"""
+        result = build_ffmpeg_filter("filter_warm", intensity=100)
+        assert "gamma_r=" in result
+        # 暖色红通道伽马 > 1.0
+        assert "gamma_r=1.100" in result
+
+    def test_result_format_is_eq_params(self):
+        """结果格式应该是 eq=param1=val:param2=val..."""
+        result = build_ffmpeg_filter("filter_brighten", intensity=100)
+        assert result.startswith("eq=")
+        # 参数之间用冒号分隔
+        parts = result[3:].split(":")
+        assert len(parts) >= 4  # 至少 brightness/contrast/saturation/gamma
+        for part in parts:
+            assert "=" in part  # 每个部分都是 key=value 格式

tests/unit/test_generated_video_domain.py

@@ -0,0 +1,196 @@
+"""generated_video 领域模型单元测试."""
+
+import pytest
+from domain.generated_video import GeneratedVideo
+
+
+class TestGeneratedVideoCreate:
+    """GeneratedVideo.create 工厂方法测试."""
+
+    def test_create_with_required_fields(self):
+        video = GeneratedVideo.create(
+            project_id="proj_001",
+            generation_task_id="task_001",
+            name="测试视频",
+            file_url="https://example.com/out.mp4",
+        )
+        assert video.id
+        assert len(video.id) == 32
+        assert video.project_id == "proj_001"
+        assert video.generation_task_id == "task_001"
+        assert video.name == "测试视频"
+        assert video.file_url == "https://example.com/out.mp4"
+        # 默认值
+        assert video.user_id == ""
+        assert video.file_size == 0
+        assert video.duration == 0.0
+        assert video.width == 0
+        assert video.height == 0
+        assert video.fps == 0.0
+        assert video.thumbnail_url is None
+        assert video.status == "completed"
+        assert video.review_status == "pending_review"
+        assert video.generation_params == {}
+        assert video.video_fingerprint is None
+        assert video.is_duplicate is False
+        assert video.duplicate_of is None
+        assert video.generated_at is not None
+        assert video.created_at is not None
+
+    def test_create_with_all_fields(self):
+        video = GeneratedVideo.create(
+            project_id="proj_002",
+            generation_task_id="task_002",
+            name="完整视频",
+            file_url="https://example.com/full.mp4",
+            user_id="user_001",
+            file_size=1024000,
+            duration=30.5,
+            width=1920,
+            height=1080,
+            fps=30.0,
+            thumbnail_url="https://example.com/thumb.jpg",
+            generation_params={"quality": "high"},
+        )
+        assert video.user_id == "user_001"
+        assert video.file_size == 1024000
+        assert video.duration == 30.5
+        assert video.width == 1920
+        assert video.height == 1080
+        assert video.fps == 30.0
+        assert video.thumbnail_url == "https://example.com/thumb.jpg"
+        assert video.generation_params == {"quality": "high"}
+
+    def test_create_strips_strings(self):
+        video = GeneratedVideo.create(
+            project_id="  proj_003  ",
+            generation_task_id="  task_003  ",
+            name="  测试视频  ",
+            file_url="  https://example.com/out.mp4  ",
+            user_id="  user_003  ",
+        )
+        assert video.project_id == "proj_003"
+        assert video.generation_task_id == "task_003"
+        assert video.name == "测试视频"
+        assert video.file_url == "https://example.com/out.mp4"
+        assert video.user_id == "user_003"
+
+    def test_create_empty_project_id_raises(self):
+        with pytest.raises(ValueError, match="project_id"):
+            GeneratedVideo.create(
+                project_id="",
+                generation_task_id="t",
+                name="n",
+                file_url="u",
+            )
+
+    def test_create_whitespace_project_id_raises(self):
+        with pytest.raises(ValueError, match="project_id"):
+            GeneratedVideo.create(
+                project_id="   ",
+                generation_task_id="t",
+                name="n",
+                file_url="u",
+            )
+
+    def test_create_empty_generation_task_id_raises(self):
+        with pytest.raises(ValueError, match="generation_task_id"):
+            GeneratedVideo.create(
+                project_id="p",
+                generation_task_id="",
+                name="n",
+                file_url="u",
+            )
+
+    def test_create_empty_name_raises(self):
+        with pytest.raises(ValueError, match="name"):
+            GeneratedVideo.create(
+                project_id="p",
+                generation_task_id="t",
+                name="",
+                file_url="u",
+            )
+
+    def test_create_empty_file_url_raises(self):
+        with pytest.raises(ValueError, match="file_url"):
+            GeneratedVideo.create(
+                project_id="p",
+                generation_task_id="t",
+                name="n",
+                file_url="",
+            )
+
+    def test_create_none_generation_params_defaults_to_empty_dict(self):
+        video = GeneratedVideo.create(
+            project_id="p",
+            generation_task_id="t",
+            name="n",
+            file_url="u",
+            generation_params=None,
+        )
+        assert video.generation_params == {}
+
+    def test_create_ids_are_unique(self):
+        v1 = GeneratedVideo.create(project_id="p", generation_task_id="t1", name="n1", file_url="u1")
+        v2 = GeneratedVideo.create(project_id="p", generation_task_id="t2", name="n2", file_url="u2")
+        assert v1.id != v2.id
+
+    def test_create_timestamps_are_utc(self):
+        video = GeneratedVideo.create(project_id="p", generation_task_id="t", name="n", file_url="u")
+        assert video.created_at.tzinfo is not None
+        assert video.generated_at.tzinfo is not None
+
+
+class TestGeneratedVideoProperties:
+    """GeneratedVideo 属性测试"""
+
+    def test_default_status_completed(self):
+        gv = GeneratedVideo.create(
+            project_id="proj-1",
+            generation_task_id="task-1",
+            name="测试视频",
+            file_url="https://example.com/video.mp4",
+        )
+        assert gv.status == "completed"
+
+    def test_default_review_status(self):
+        gv = GeneratedVideo.create(
+            project_id="proj-1",
+            generation_task_id="task-1",
+            name="测试视频",
+            file_url="https://example.com/video.mp4",
+        )
+        assert gv.review_status == "pending_review"
+
+    def test_set_status(self):
+        gv = GeneratedVideo.create(
+            project_id="proj-1",
+            generation_task_id="task-1",
+            name="测试视频",
+            file_url="https://example.com/video.mp4",
+        )
+        gv.status = "failed"
+        assert gv.status == "failed"
+
+    def test_mark_as_duplicate(self):
+        gv = GeneratedVideo.create(
+            project_id="proj-1",
+            generation_task_id="task-1",
+            name="测试视频",
+            file_url="https://example.com/video.mp4",
+        )
+        gv.is_duplicate = True
+        gv.duplicate_of = "video-original"
+        assert gv.is_duplicate is True
+        assert gv.duplicate_of == "video-original"
+
+    def test_set_fingerprint(self):
+        gv = GeneratedVideo.create(
+            project_id="proj-1",
+            generation_task_id="task-1",
+            name="测试视频",
+            file_url="https://example.com/video.mp4",
+        )
+        fingerprint = {"phash": "abc123", "md5": "def456"}
+        gv.video_fingerprint = fingerprint
+        assert gv.video_fingerprint == fingerprint