fix: prevent docker images grep from failing build with set -e

The last line of the build script uses grep to display built images,
but with set -e, grep returning no matches causes the entire script
to fail. This is a classic set -e footgun.

The grep pattern was also broken: docker images shows REPOSITORY and
TAG as separate columns (no ':' between them), so 'xiaoxia-saas.*:'
never matched. Changed to two-stage grep and added || true safety net.

The build and push were actually succeeding - only the final display
line was causing the failure.

.env.production.example

@@ -5,7 +5,6 @@ APP_ENV=production
 ENVIRONMENT=production
 DEBUG=false
 USE_IN_MEMORY_DB=false
-LOG_LEVEL=WARNING
 
 # ==================== 数据库（必须修改）====================
 DATABASE_URL=postgresql://prod_user:CHANGE_THIS_PASSWORD@db-prod:5432/xiaoxia_prod

.gitea/workflows/ci-cd.yml

@@ -19,6 +19,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   validate:
     name: Validate Code Quality And Tests
@@ -165,6 +169,10 @@ jobs:
 
     env:
       USE_IN_MEMORY_DB: "true"
+      OSS_ACCESS_KEY_ID: placeholder
+      OSS_ACCESS_KEY_SECRET: placeholder
+      OSS_BUCKET_NAME: xiaoxia-autocut
+      OSS_ENDPOINT: oss-cn-hangzhou.aliyuncs.com
 
     steps:
       - name: Checkout code
@@ -213,6 +221,32 @@ jobs:
                       tar.extract(member, '.')
           PY
 
+      - name: Install ffmpeg
+        shell: sh
+        run: |
+          set +e
+          if command -v ffmpeg > /dev/null 2>&1; then
+            echo "ffmpeg already installed: $(ffmpeg -version | head -1)"
+            exit 0
+          fi
+          if command -v apt-get > /dev/null 2>&1; then
+            apt-get update -qq && apt-get install -y -qq ffmpeg
+          elif command -v yum > /dev/null 2>&1; then
+            yum install -y -q epel-release 2>/dev/null
+            yum install -y -q ffmpeg 2>/dev/null
+            if [ $? -ne 0 ] && command -v dnf > /dev/null 2>&1; then
+              dnf install -y -q --nogpgcheck https://download1.rpmfusion.org/free/el/rpmfusion-free-release-$(rpm -E %rhel).noarch.rpm 2>/dev/null
+              dnf install -y -q ffmpeg 2>/dev/null
+            fi
+          elif command -v dnf > /dev/null 2>&1; then
+            dnf install -y -q ffmpeg 2>/dev/null
+          fi
+          if command -v ffmpeg > /dev/null 2>&1; then
+            echo "ffmpeg installed successfully: $(ffmpeg -version | head -1)"
+          else
+            echo "Warning: ffmpeg installation failed or not available, some tests may be skipped"
+          fi
+
       - name: Install dependencies
         shell: sh
         run: |
@@ -256,6 +290,10 @@ jobs:
     env:
       DATABASE_URL: postgresql+psycopg://postgres:postgres@127.0.0.1:5432/xiaoxia_saas
       USE_IN_MEMORY_DB: "false"
+      OSS_ACCESS_KEY_ID: placeholder
+      OSS_ACCESS_KEY_SECRET: placeholder
+      OSS_BUCKET_NAME: xiaoxia-autocut
+      OSS_ENDPOINT: oss-cn-hangzhou.aliyuncs.com
 
     steps:
       - name: Checkout code
@@ -321,6 +359,32 @@ jobs:
           python3 -m pip install -q -r requirements-dev.txt
           pytest --version
 
+      - name: Install ffmpeg
+        shell: sh
+        run: |
+          set +e
+          if command -v ffmpeg > /dev/null 2>&1; then
+            echo "ffmpeg already installed: $(ffmpeg -version | head -1)"
+            exit 0
+          fi
+          if command -v apt-get > /dev/null 2>&1; then
+            apt-get update -qq && apt-get install -y -qq ffmpeg
+          elif command -v yum > /dev/null 2>&1; then
+            yum install -y -q epel-release 2>/dev/null
+            yum install -y -q ffmpeg 2>/dev/null
+            if [ $? -ne 0 ] && command -v dnf > /dev/null 2>&1; then
+              dnf install -y -q --nogpgcheck https://download1.rpmfusion.org/free/el/rpmfusion-free-release-$(rpm -E %rhel).noarch.rpm 2>/dev/null
+              dnf install -y -q ffmpeg 2>/dev/null
+            fi
+          elif command -v dnf > /dev/null 2>&1; then
+            dnf install -y -q ffmpeg 2>/dev/null
+          fi
+          if command -v ffmpeg > /dev/null 2>&1; then
+            echo "ffmpeg installed successfully: $(ffmpeg -version | head -1)"
+          else
+            echo "Warning: ffmpeg installation failed or not available, some tests may be skipped"
+          fi
+
       - name: Start Redis
         shell: sh
         run: |
@@ -390,7 +454,7 @@ jobs:
         shell: sh
         run: |
           set -eu
-          pip install -q pytest-rerunfailures
+          python3 -m pip install -q pytest-rerunfailures
           PYTHONPATH="$PWD/apps/api:$PWD" python3 -m coverage run --append \
             --source=apps/api/app,packages \
             --omit="*/migrations/*,*/tests/*,*/test_*.py,*/site-packages/*" \

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

@@ -12,7 +12,7 @@ from app.schemas.asset_library import (
     EnsureDefaultLibraryRequest,
     ListAssetLibrariesResponse,
 )
-from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
 
 from packages.application import (
     CreateAssetLibraryCommand,
@@ -146,7 +146,7 @@ def ensure_default_library(
     return _to_asset_library_response(created)
 
 
-@router.delete("/{library_id}", status_code=status.HTTP_204_NO_CONTENT)
+@router.delete("/{library_id}", status_code=status.HTTP_204_NO_CONTENT, response_class=Response)
 def delete_asset_library(
     library_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),

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

@@ -1,6 +1,7 @@
 import logging
 from typing import Any, Optional
 
+from app.api.routes._helpers import check_project_access
 from app.auth import AuthenticatedUser, get_current_user
 from app.core.storage import get_storage_service
 from app.dependencies import (
@@ -19,7 +20,7 @@ from app.schemas.asset import (
     UpdateAssetReviewRequest,
 )
 from app.schemas.tag import TagAssetsRequest
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Depends, HTTPException, Query, Response
 
 from packages.application import (
     CreateAssetCommand,
@@ -27,8 +28,6 @@ from packages.application import (
 )
 from packages.domain import AssetStatus, ClassificationStatus
 
-from app.api.routes._helpers import check_project_access
-
 logger = logging.getLogger(__name__)
 
 router = APIRouter()
@@ -74,7 +73,6 @@ def _to_asset_response(item, storage_service=None) -> AssetResponse:
     )
 
 
-
 @router.get("", response_model=ListAssetsResponse)
 def list_assets(
     library_id: Optional[str] = Query(None),
@@ -330,7 +328,7 @@ def update_asset(
     return _to_asset_response(updated)
 
 
-@router.delete("/{asset_id}", status_code=204)
+@router.delete("/{asset_id}", status_code=204, response_class=Response)
 def delete_asset(
     asset_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -369,7 +367,7 @@ def tag_asset(
     return _to_asset_response(updated)
 
 
-@router.delete("/{asset_id}/tags/{tag_id}", status_code=204)
+@router.delete("/{asset_id}/tags/{tag_id}", status_code=204, response_class=Response)
 def untag_asset(
     asset_id: str,
     tag_id: str,

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

@@ -105,7 +105,7 @@ async def register(
     request: RegisterRequest,
     user_repository: UserRepository = Depends(get_user_repository),
     email_service=Depends(get_auth_email_service),
-):
+) -> RegisterResponse:
     use_case = RegisterUserUseCase(
         user_repository=user_repository,
         base_url=settings.APP_BASE_URL,
@@ -136,7 +136,7 @@ async def login(
     request: LoginRequest,
     user_repository: UserRepository = Depends(get_user_repository),
     session_store=Depends(get_auth_session_store),
-):
+) -> LoginResponse:
     use_case = LoginUseCase(
         user_repository=user_repository,
         session_store=session_store,
@@ -162,7 +162,7 @@ async def refresh(
     request: RefreshRequest,
     user_repository: UserRepository = Depends(get_user_repository),
     session_store=Depends(get_auth_session_store),
-):
+) -> LoginResponse:
     use_case = RefreshTokenUseCase(
         user_repository=user_repository,
         session_store=session_store,
@@ -194,7 +194,7 @@ def _verify_email_token(token: str, user_repository: UserRepository) -> MessageR
 async def verify_email(
     token: str,
     user_repository: UserRepository = Depends(get_user_repository),
-):
+) -> MessageResponse:
     return _verify_email_token(token, user_repository)
 
 
@@ -202,7 +202,7 @@ async def verify_email(
 async def verify_email_post(
     request: VerifyEmailRequestModel,
     user_repository: UserRepository = Depends(get_user_repository),
-):
+) -> MessageResponse:
     return _verify_email_token(request.token, user_repository)
 
 
@@ -211,7 +211,7 @@ async def forgot_password(
     request: PasswordResetRequestModel,
     user_repository: UserRepository = Depends(get_user_repository),
     email_service=Depends(get_auth_email_service),
-):
+) -> MessageResponse:
     success, error = RequestPasswordResetUseCase(
         user_repository=user_repository,
         base_url=settings.APP_BASE_URL,
@@ -227,7 +227,7 @@ async def forgot_password(
 async def reset_password(
     request: ResetPasswordModel,
     user_repository: UserRepository = Depends(get_user_repository),
-):
+) -> MessageResponse:
     success, error = ResetPasswordUseCase(user_repository=user_repository).execute(
         ResetPasswordRequest(token=request.token, new_password=request.new_password)
     )
@@ -241,7 +241,7 @@ async def reset_password(
 async def logout(
     credentials: HTTPAuthorizationCredentials | None = Depends(bearer_scheme),
     current_user: AuthenticatedUser = Depends(get_current_user),
-):
+) -> MessageResponse:
     """登出 - 将当前 token 加入黑名单"""
 
     if credentials:
@@ -257,7 +257,7 @@ async def logout(
 @router.get("/me", response_model=CurrentUserResponse)
 async def get_current_user_info(
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
-):
+) -> CurrentUserResponse:
     user = authenticated_user.user
     return CurrentUserResponse(
         user_id=user.id,
@@ -323,7 +323,7 @@ def _get_internal_api_keys() -> list[str]:
             if content:
                 return [k.strip() for k in content.split(",") if k.strip()]
     except Exception:
-        logger.debug("Failed to read internal API keys from file", exc_info=True)
+        logger.warning("无法读取内部 API 密钥文件，仅依赖环境变量配置", exc_info=True)
 
     return []
 
@@ -354,7 +354,7 @@ async def wechat_sync(
     request: WechatSyncRequest,
     user_repository: UserRepository = Depends(get_user_repository),
     _: bool = Depends(_verify_internal_api_key),
-):
+) -> WechatSyncResponse:
     """
     微信同步登录/注册（系统级内部接口）
 

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

@@ -13,6 +13,7 @@ from pathlib import Path
 from typing import Any
 from uuid import uuid4
 
+from app.api.routes._helpers import require_project_and_library
 from app.auth import AuthenticatedUser, get_current_user
 from app.core.celery_app import celery_app
 from app.core.storage import OSSStorageService, get_storage_service
@@ -34,8 +35,6 @@ from fastapi.params import File
 
 from packages.application import GetProjectUseCase, SubmitIngestJobCommand, SubmitIngestJobUseCase
 
-from app.api.routes._helpers import require_project_and_library
-
 router = APIRouter()
 logger = logging.getLogger(__name__)
 

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

@@ -239,7 +239,7 @@ def get_duplication_detail(
     return _to_detail_response(record)
 
 
-@router.delete("/records/{record_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
+@router.delete("/records/{record_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
 def delete_duplication_record(
     record_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -257,7 +257,7 @@ def delete_duplication_record(
 
     use_case = DeleteDuplicationRecordUseCase(duplication_repository)
     use_case.execute(record_id)
-    return Response(status_code=204)
+    return
 
 
 @router.post("/records/{record_id}/retry", response_model=DuplicationUploadResponse)

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

@@ -6,12 +6,11 @@ RESTful CRUD for EditPlan:
 - POST   /api/v1/edit-plans            创建
 - PUT    /api/v1/edit-plans/{id}       更新（含状态机流转）
 - DELETE /api/v1/edit-plans/{id}       删除
-- POST   /api/v1/edit-plans/{id}/generate          触发剪辑渲染生成（任务 2.05）
-- GET    /api/v1/edit-plans/{id}/generation-status  查询生成进度（任务 2.05）
-- POST   /api/v1/edit-plans/{id}/ai-recommend       AI 推荐片段方案（任务 3.09）
-- POST   /api/v1/edit-plans/{id}/generate-cover     AI 生成封面（任务 3.09）
-- GET    /api/v1/edit-plans/{id}/timeline           时间线场景数据
-- POST   /api/v1/edit-plans/generate-from-template  基于模板+素材自动生成剪辑计划
+
+拆分模块（各自独立 router，由本文件 include_router 聚合）:
+- edit_plans_generation.py   生成相关（generate / generation-status / generations）
+- edit_plans_ai.py           AI 推荐 & 封面（ai-recommend / generate-cover）
+- edit_plans_timeline.py     时间线 & 模板生成（timeline / generate-from-template）
 
 业务逻辑委托给 EditPlanService 服务层。
 """
@@ -23,33 +22,18 @@ from datetime import datetime
 from typing import Any, List, Optional
 
 from app.auth import AuthenticatedUser, get_current_user
-from app.core.celery_app import celery_app
-from app.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.dependencies import get_db_session, get_project_repository
 from app.schemas.generation_task import GenerationTaskResponse
-from app.services import EditPlanService, PlanGeneratorService
-from fastapi import APIRouter, Depends, HTTPException, Query, status
+from app.services import EditPlanService
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session
 
-from packages.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 ._helpers import check_project_access
 from packages.domain.config_schemas import normalize_plan_config
 from packages.domain.edit_plan import EditPlan, EditPlanStatus
 
+from ._helpers import check_project_access
+
 logger = logging.getLogger(__name__)
 
 router = APIRouter()
@@ -258,7 +242,7 @@ def _to_response(p: EditPlan) -> EditPlanResponse:
     )
 
 
-# ── Routes ────────────────────────────────────────────────────────────────────
+# ── CRUD Routes ───────────────────────────────────────────────────────────────
 
 
 @router.get("", response_model=EditPlanListResponse)
@@ -438,7 +422,7 @@ def update_plan(
     return _to_response(result)
 
 
-@router.delete("/{plan_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
+@router.delete("/{plan_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
 def delete_plan(
     plan_id: str,
     db: Session = Depends(get_db_session),
@@ -464,753 +448,12 @@ def delete_plan(
     )
 
 
-# ── 生成相关端点（任务 2.05） ─────────────────────────────────────────────────
+# ── Include sub-routers (拆分模块) ────────────────────────────────────────────
 
+from .edit_plans_ai import router as ai_router
+from .edit_plans_generation import router as generation_router
+from .edit_plans_timeline import router as timeline_router
 
-@router.post("/{plan_id}/generate", response_model=EditPlanGenerateResponse)
-def generate_plan(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-    asset_library_repo: Any = Depends(get_asset_library_repository),
-    asset_repo: Any = Depends(get_asset_repository),
-) -> EditPlanGenerateResponse:
-    """触发剪辑计划渲染生成
-
-    前置条件：计划状态必须为 editing，且至少有一个片段。
-    流程：
-    1. 验证计划状态为 editing
-    2. 将 pending 片段标记为 ready
-    3. 创建 GenerationTask
-    4. 调度 Celery 任务 worker.render_edit_plan
-    5. 将计划状态流转为 rendering
-    """
-    svc = EditPlanService(db)
-    # 项目鉴权
-    plan_check = svc.get_plan(plan_id)
-    if plan_check is None:
-        raise HTTPException(status_code=404, detail=f"剪辑计划不存在: {plan_id}")
-    if plan_check.project_id:
-        check_project_access(plan_check.project_id, current_user.user.id, project_repository)
-
-    # ── 自动兜底 1: draft → editing ──────────────────────────────────────
-    if plan_check.status == EditPlanStatus.DRAFT:
-        logger.info("自动兜底: plan=%s draft→editing", plan_id)
-        svc.transition_status(plan_id, EditPlanStatus.EDITING)
-
-    # ── 自动兜底 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,
-        )
-        # 优先从新模型 template_clip_configs 读取，若无则回退到旧模型 template_segments
-        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:
-            # 回退到旧模型 template_segments
-            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))
-
-    # ── 自动兜底 3: 为没有素材的片段分配素材 ──────────────────────────
-    # 如果 plan.config.asset_ids 有素材，但 clips 没有 asset_id，自动按顺序分配
-    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", [])
-    material_mode = (plan_check.config or {}).get("material_mode", "manual")
-
-    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 = []  # 已分配完
-
-    # ── 自动兜底 4: 自动素材模式 → 从项目默认视频素材库选取 ────────────
-    if clips_without_asset and material_mode == "auto" and plan_check.project_id:
-        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 状态的视频素材
-            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)
-
-    # 检查是否可生成
-    try:
-        can_gen, reason = svc.can_generate(plan_id)
-    except ValueError as exc:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=str(exc),
-        )
-    if not can_gen:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=reason,
-        )
-
-    # 核心生成流程：捕获异常返回明确错误信息，避免裸 500
-    try:
-        # 将 pending 片段标记为 ready
-        clip_count = svc.mark_clips_ready(plan_id)
-
-        # 创建 GenerationTask
-        gen_task_repo = SQLAlchemyGenerationTaskRepository(db)
-
-        # 队列限流预检查（repository 不支持计数时跳过）
-        user_id = current_user.user.id
-        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)
-
-        gen_task_use_case = CreateGenerationTaskUseCase(gen_task_repo)
-        plan = svc.get_plan_or_raise(plan_id)
-        gen_task = gen_task_use_case.execute(
-            CreateGenerationTaskCommand(
-                project_id="",
-                template_id=plan.template_id,
-                created_by_user_id=current_user.user.id,
-                source_edit_plan_id=plan_id,
-            )
-        )
-
-        # 将 generation_task_id 存入 plan config
-        svc.update_plan_config(plan_id, {"generation_task_id": gen_task.id})
-
-        # 流转状态为 rendering
-        svc.transition_status(plan_id, EditPlanStatus.RENDERING)
-
-        # 调度 Celery 任务
-        celery_app.send_task("worker.render_edit_plan", args=[plan_id])
-
-        # 获取最新状态
-        updated_plan = svc.get_plan_or_raise(plan_id)
-
-        logger.info(
-            "触发剪辑计划生成: plan_id=%s gen_task_id=%s clips=%d by user=%s",
-            plan_id,
-            gen_task.id,
-            clip_count,
-            current_user.user.id,
-        )
-
-        return EditPlanGenerateResponse(
-            plan_id=plan_id,
-            plan_status=updated_plan.status.value if hasattr(updated_plan.status, "value") else updated_plan.status,
-            generation_task_id=gen_task.id,
-            clip_count=clip_count,
-        )
-    except HTTPException:
-        # 已处理的 HTTP 异常直接透传
-        raise
-    except Exception:
-        logger.exception("触发剪辑计划生成失败: plan_id=%s", plan_id)
-        # 尝试将计划标记为失败（RENDERING → FAILED 是合法的状态流转）
-        try:
-            svc.transition_status(plan_id, EditPlanStatus.FAILED)
-        except Exception:
-            logger.warning("标记计划失败状态时异常: plan_id=%s", plan_id)
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="生成失败，请稍后重试",
-        )
-
-
-@router.get(
-    "/{plan_id}/generation-status",
-    response_model=EditPlanGenerationStatusResponse,
-)
-def get_generation_status(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> EditPlanGenerationStatusResponse:
-    """查询剪辑计划生成进度
-
-    返回计划状态、关联的 GenerationTask ID、以及每个片段的状态。
-    """
-    svc = EditPlanService(db)
-    try:
-        gen_status = svc.get_generation_status(plan_id)
-    except ValueError as exc:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=str(exc),
-        )
-
-    plan = gen_status["plan"]
-    # 项目鉴权
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-    clips = gen_status["clips"]
-
-    clip_items = [
-        ClipStatusItem(
-            clip_id=c.id,
-            clip_type=c.clip_type,
-            order=c.order,
-            status=c.status.value if hasattr(c.status, "value") else c.status,
-            asset_id=c.asset_id or "",
-            text_content=c.text_content or "",
-            duration=c.duration,
-        )
-        for c in clips
-    ]
-
-    return EditPlanGenerationStatusResponse(
-        plan_id=plan_id,
-        plan_status=plan.status.value if hasattr(plan.status, "value") else plan.status,
-        generation_task_id=gen_status["generation_task_id"],
-        clips=clip_items,
-    )
-
-
-@router.get(
-    "/{plan_id}/generations",
-    response_model=EditPlanGenerationsResponse,
-)
-def list_plan_generations(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> EditPlanGenerationsResponse:
-    """查询剪辑计划关联的所有生成记录
-
-    返回该剪辑计划触发的所有 GenerationTask，按创建时间倒序。
-    """
-    svc = EditPlanService(db)
-    # 验证计划存在 + 项目鉴权
-    plan = svc.get_plan_or_raise(plan_id)
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    gen_task_repo = SQLAlchemyGenerationTaskRepository(db)
-    tasks = gen_task_repo.list_by_source_edit_plan(plan_id)
-    items = [
-        GenerationTaskResponse(
-            id=t.id,
-            project_id=t.project_id,
-            asset_library_id=t.asset_library_id,
-            strategy_id=t.strategy_id,
-            voice_library_id=t.voice_library_id,
-            template_id=t.template_id,
-            asset_ids=t.asset_ids,
-            title_ids=t.title_ids,
-            voice_ids=t.voice_ids,
-            source_edit_plan_id=t.source_edit_plan_id or "",
-            status=t.status.value if hasattr(t.status, "value") else t.status,
-            progress=t.progress,
-            result_count=t.result_count,
-            error_message=t.error_message,
-        )
-        for t in tasks
-    ]
-    return EditPlanGenerationsResponse(items=items, total=len(items))
-
-
-# ── AI 推荐 & 封面生成端点（任务 3.09） ────────────────────────────────────────
-
-
-@router.post(
-    "/{plan_id}/ai-recommend",
-    response_model=AIRecommendResponse,
-)
-def ai_recommend_clips(
-    plan_id: str,
-    body: AIRecommendRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> AIRecommendResponse:
-    """AI 推荐片段方案
-
-    调用 AI 服务分析素材，自动生成片段编排方案并写入剪辑计划。
-
-    流程：
-    1. 验证计划存在且状态为 draft/editing
-    2. 调用 AI 推荐服务（当前为 stub，后续接入真实 AI）
-    3. 清除计划现有片段，按推荐方案重新创建
-    4. 更新计划 config（cover/title/subtitle/bgm）和 total_duration
-    5. 返回推荐方案详情
-
-    前端对接：
-    - 请求体只需传 asset_ids（必填），editing_mode 和 target_duration 可选
-    - 返回的 clips 可直接渲染到时间线
-    - 返回的 config 包含推荐的封面/标题/字幕/BGM 配置
-    """
-    svc = EditPlanService(db)
-
-    # 验证计划存在
-    try:
-        plan = svc.get_plan_or_raise(plan_id)
-    except ValueError as exc:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=str(exc),
-        )
-
-    # 项目鉴权
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 验证状态：只允许 draft 或 editing
-    plan_status = plan.status.value if hasattr(plan.status, "value") else plan.status
-    if plan_status not in ("draft", "editing"):
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="当前计划状态不支持AI推荐，请先创建或编辑计划后再试",
-        )
-
-    # 调用 AI 推荐服务（同步调用 stub，后续改为 Celery 异步）
-    from apps.worker.worker_app.tasks.ai_tasks import run_ai_recommend
-
-    result = run_ai_recommend(
-        plan_id=plan_id,
-        template_id=plan.template_id,
-        asset_ids=body.asset_ids,
-        editing_mode=body.editing_mode,
-        target_duration=body.target_duration,
-    )
-
-    # ── 事务保护：清除 → 重建 → 更新 必须在同一逻辑事务中 ──
-    # TODO: 当前各 repo 方法内部 commit()，无法真正回滚。
-    #       后续重构 repo 为 flush() 模式后，此处改为统一 commit。
-    try:
-        # 清除现有片段
-        svc.delete_all_clips(plan_id)
-
-        # 按推荐方案创建新片段
-        for clip_data in result["clips"]:
-            svc.create_clip(
-                plan_id=plan_id,
-                clip_type=clip_data["clip_type"],
-                order=clip_data["order"],
-                text_content=clip_data.get("text_content", ""),
-                duration=clip_data["duration"],
-                transition_effect=clip_data.get("transition_effect", "cut"),
-                asset_id=clip_data.get("asset_id", ""),
-                start_time=clip_data.get("start_time", 0.0),
-                config=clip_data.get("config", {}),
-            )
-
-        # 更新计划 config 和 total_duration
-        normalized_config = normalize_plan_config(result.get("config", {}))
-        svc.update_plan(
-            plan_id,
-            config=normalized_config,
-            total_duration=result["total_duration"],
-        )
-    except Exception:
-        logger.exception("AI 推荐写入失败，plan_id=%s 数据可能不一致", plan_id)
-        # 尝试回滚未提交的变更
-        try:
-            db.rollback()
-        except Exception:
-            pass
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="AI推荐结果保存失败，请稍后重试",
-        )
-
-    logger.info(
-        "AI 推荐片段方案: plan_id=%s clips=%d duration=%.1f by user=%s",
-        plan_id,
-        len(result["clips"]),
-        result["total_duration"],
-        current_user.user.id,
-    )
-
-    return AIRecommendResponse(
-        plan_id=plan_id,
-        clips=[
-            AIRecommendClipItem(
-                clip_type=c["clip_type"],
-                order=c["order"],
-                text_content=c.get("text_content", ""),
-                duration=c["duration"],
-                transition_effect=c.get("transition_effect", "cut"),
-                asset_id=c.get("asset_id", ""),
-                start_time=c.get("start_time", 0.0),
-                config=c.get("config", {}),
-            )
-            for c in result["clips"]
-        ],
-        config=normalized_config,
-        total_duration=result["total_duration"],
-        confidence=result["confidence"],
-    )
-
-
-@router.post(
-    "/{plan_id}/generate-cover",
-    response_model=GenerateCoverResponse,
-)
-def generate_cover(
-    plan_id: str,
-    body: GenerateCoverRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> GenerateCoverResponse:
-    """AI 生成封面
-
-    调用 AI 服务从视频中选帧或生成封面图，并更新计划 config.cover。
-
-    流程：
-    1. 验证计划存在
-    2. 调用 AI 封面生成服务（当前为 stub，后续接入真实 AI）
-    3. 更新 plan.config["cover"] 为生成的封面数据
-    4. 返回封面数据
-
-    前端对接：
-    - cover_type=ai_frame: AI 智能选帧（默认）
-    - cover_type=manual: 手动选帧，需传 frame_time
-    - cover_type=upload: 用户上传，接口返回空 image_url，前端自行上传后更新
-    - cover_type=ai_regenerate: AI 重新生成
-    """
-    svc = EditPlanService(db)
-
-    # 验证计划存在
-    try:
-        plan = svc.get_plan_or_raise(plan_id)
-    except ValueError as exc:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=str(exc),
-        )
-
-    # 项目鉴权
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    # 调用 AI 封面生成服务
-    from apps.worker.worker_app.tasks.ai_tasks import run_generate_cover
-
-    cover_data = run_generate_cover(
-        plan_id=plan_id,
-        asset_ids=body.asset_ids,
-        cover_type=body.cover_type,
-        frame_time=body.frame_time,
-    )
-
-    # 更新 plan.config["cover"]
-    current_config = dict(plan.config)
-    current_config["cover"] = cover_data
-    normalized = normalize_plan_config(current_config)
-    svc.update_plan_config(plan_id, {"cover": normalized["cover"]})
-
-    logger.info(
-        "AI 封面生成: plan_id=%s type=%s by user=%s",
-        plan_id,
-        body.cover_type,
-        current_user.user.id,
-    )
-
-    return GenerateCoverResponse(
-        plan_id=plan_id,
-        cover=cover_data,
-    )
-
-
-# ── Timeline / Scene 端点（P2-6） ─────────────────────────────────────────────
-
-
-class TimelineSceneResponse(BaseModel):
-    """时间线场景"""
-
-    scene: str = Field(..., description="场景描述")
-    time: str = Field(..., description='时间范围，如 "0:00 - 0:05"')
-    duration: float = Field(..., ge=0, description="时长（秒）")
-    color: str = Field(..., description="展示颜色")
-    clip_id: str = Field(default="", description="关联的片段 ID")
-    clip_type: str = Field(default="", description="片段类型")
-
-
-class TimelineResponse(BaseModel):
-    """时间线响应"""
-
-    plan_id: str
-    total_duration: float
-    scenes: List[TimelineSceneResponse]
-
-
-# clip_type → 颜色映射
-_CLIP_TYPE_COLORS = {
-    "intro": "#6366f1",
-    "title": "#6366f1",
-    "product": "#818cf8",
-    "showcase": "#10b981",
-    "scene": "#10b981",
-    "subtitle": "#f59e0b",
-    "text": "#f59e0b",
-    "cta": "#ef4444",
-    "outro": "#ef4444",
-    "voiceover": "#8b5cf6",
-    "transition": "#64748b",
-}
-
-_DEFAULT_COLOR = "#6366f1"
-
-
-def _format_time(seconds: float) -> str:
-    """将秒数格式化为 M:SS"""
-    m = int(seconds) // 60
-    s = int(seconds) % 60
-    return f"{m}:{s:02d}"
-
-
-def _clip_type_to_scene_label(clip_type: str, text_content: str) -> str:
-    """根据 clip_type 和 text_content 生成场景描述"""
-    type_labels = {
-        "intro": "开场",
-        "title": "标题",
-        "product": "产品展示",
-        "showcase": "场景展示",
-        "scene": "场景",
-        "subtitle": "字幕",
-        "text": "文字",
-        "cta": "结尾 CTA",
-        "outro": "结尾",
-        "voiceover": "配音",
-        "transition": "转场",
-    }
-    label = type_labels.get(clip_type, clip_type or "片段")
-    if text_content:
-        # 截取前 20 个字符作为副标题
-        short = text_content[:20].strip()
-        if short:
-            return f"{label} - {short}"
-    return label
-
-
-@router.get(
-    "/{plan_id}/timeline",
-    response_model=TimelineResponse,
-)
-def get_plan_timeline(
-    plan_id: str,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> TimelineResponse:
-    """获取剪辑计划的时间线场景数据
-
-    返回按计划片段排序的时间线场景列表，供前端 GeneratePage 渲染使用。
-    """
-    svc = EditPlanService(db)
-    plan = svc.get_plan_or_raise(plan_id)
-    # 项目鉴权
-    if plan.project_id:
-        check_project_access(plan.project_id, current_user.user.id, project_repository)
-
-    clips = svc.list_clips(plan_id=plan_id, skip=0, limit=200)
-    # 按 order 排序
-    clips.sort(key=lambda c: c.order)
-
-    scenes: List[TimelineSceneResponse] = []
-    current_time = 0.0
-
-    for clip in clips:
-        start = current_time
-        end = start + clip.duration
-        color = _CLIP_TYPE_COLORS.get(clip.clip_type, _DEFAULT_COLOR)
-        scene_label = _clip_type_to_scene_label(clip.clip_type, clip.text_content)
-
-        scenes.append(
-            TimelineSceneResponse(
-                scene=scene_label,
-                time=f"{_format_time(start)} - {_format_time(end)}",
-                duration=clip.duration,
-                color=color,
-                clip_id=clip.id,
-                clip_type=clip.clip_type,
-            )
-        )
-        current_time = end
-
-    total_duration = sum(s.duration for s in scenes) or plan.total_duration
-
-    return TimelineResponse(
-        plan_id=plan_id,
-        total_duration=total_duration,
-        scenes=scenes,
-    )
-
-
-# ── 基于模板生成剪辑计划 ─────────────────────────────────────────────────────
-
-
-@router.post(
-    "/generate-from-template",
-    response_model=GenerateFromTemplateResponse,
-    status_code=status.HTTP_201_CREATED,
-)
-def generate_from_template(
-    body: GenerateFromTemplateRequest,
-    db: Session = Depends(get_db_session),
-    current_user: AuthenticatedUser = Depends(get_current_user),
-    project_repository: Any = Depends(get_project_repository),
-) -> GenerateFromTemplateResponse:
-    """基于模板 + 素材自动生成剪辑计划
-
-    流程:
-    1. 获取模板及其片段配置
-    2. 调用 PlanGeneratorService 生成 EditPlan + EditPlanClips
-    3. 返回完整的计划和片段列表
-    """
-    from app.services import EditTemplateService
-
-    # 项目鉴权
-    if body.project_id:
-        check_project_access(body.project_id, current_user.user.id, project_repository)
-
-    template_svc = EditTemplateService(db)
-
-    # 获取模板
-    try:
-        template = template_svc.get_template_or_raise(body.template_id)
-    except ValueError as exc:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=str(exc),
-        )
-
-    # 获取模板片段配置
-    clip_configs = template_svc.list_clip_configs(body.template_id, skip=0, limit=200)
-
-    # 调用 PlanGeneratorService 生成计划
-    generator = PlanGeneratorService(db)
-    result = generator.generate_from_template(
-        template=template,
-        clip_configs=clip_configs,
-        asset_ids=body.asset_ids,
-        project_id=body.project_id,
-        created_by_user_id=current_user.user.id,
-        name=body.name,
-    )
-
-    plan = result["plan"]
-    clips = result["clips"]
-
-    logger.info(
-        "基于模板生成剪辑计划: plan_id=%s template_id=%s clips=%d by user=%s",
-        plan.id,
-        body.template_id,
-        len(clips),
-        current_user.user.id,
-    )
-
-    return GenerateFromTemplateResponse(
-        plan=_to_response(plan),
-        clips=[
-            _PlanClipItem(
-                id=c.id,
-                clip_type=c.clip_type,
-                order=c.order,
-                asset_id=c.asset_id,
-                text_content=c.text_content,
-                start_time=c.start_time,
-                duration=c.duration,
-                transition_effect=c.transition_effect,
-                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
-        ],
-    )
+router.include_router(generation_router)
+router.include_router(ai_router)
+router.include_router(timeline_router)

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

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

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

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

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

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

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

@@ -19,11 +19,10 @@ from typing import Optional
 
 from app.api.routes.auth import _verify_internal_api_key
 from app.config import settings
-from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
 from pydantic import BaseModel, Field
 
 from packages.adapters.redis.feature_flag_store import (
-    FEATURE_FLAG_REDIS_PREFIX,
     FeatureFlagConfig,
     RedisFeatureFlagStore,
 )
@@ -90,7 +89,7 @@ def _validate_flag_name(name: str) -> None:
 async def list_feature_flags(
     _: bool = Depends(_verify_internal_api_key),
     store: RedisFeatureFlagStore = Depends(_get_feature_flag_store),
-):
+) -> list[FeatureFlagResponse]:
     """列出所有 Feature Flag。"""
     try:
         flags = store.list_all()
@@ -114,7 +113,7 @@ async def get_feature_flag(
     name: str,
     _: bool = Depends(_verify_internal_api_key),
     store: RedisFeatureFlagStore = Depends(_get_feature_flag_store),
-):
+) -> FeatureFlagResponse:
     """获取单个 Feature Flag 配置。"""
     try:
         config = store.get(name)
@@ -130,7 +129,7 @@ async def check_feature_flag(
     identifier: Optional[str] = Query(None, description="标识符，如 user_id"),
     _: bool = Depends(_verify_internal_api_key),
     store: RedisFeatureFlagStore = Depends(_get_feature_flag_store),
-):
+) -> FeatureFlagCheckResponse:
     """检查某个标识符是否命中 Feature Flag。"""
     try:
         active = store.is_active(name, identifier=identifier)
@@ -146,7 +145,7 @@ async def update_feature_flag(
     request: FeatureFlagUpdateRequest,
     _: bool = Depends(_verify_internal_api_key),
     store: RedisFeatureFlagStore = Depends(_get_feature_flag_store),
-):
+) -> FeatureFlagResponse:
     """更新 Feature Flag 配置。
 
     只允许修改 ALLOWED_FLAGS 列表中的 flag。
@@ -174,12 +173,12 @@ async def update_feature_flag(
         raise HTTPException(status_code=500, detail=f"Failed to update flag: {exc}")
 
 
-@router.delete("/{name}", status_code=status.HTTP_204_NO_CONTENT)
+@router.delete("/{name}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
 async def delete_feature_flag(
     name: str,
     _: bool = Depends(_verify_internal_api_key),
     store: RedisFeatureFlagStore = Depends(_get_feature_flag_store),
-):
+) :
     """删除 Feature Flag。
 
     只允许删除 ALLOWED_FLAGS 列表中的 flag。
@@ -189,7 +188,7 @@ async def delete_feature_flag(
     try:
         deleted = store.delete(name)
         logger.info("Feature flag deleted: name=%s deleted=%s", name, deleted)
-        return None
+        pass
     except Exception as exc:
         logger.error("Failed to delete feature flag %s: %s", name, exc)
         raise HTTPException(status_code=500, detail=f"Failed to delete flag: {exc}")

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

@@ -3,6 +3,7 @@ import random
 import uuid
 from typing import Any
 
+from app.api.routes._helpers import check_project_access
 from app.auth import AuthenticatedUser, get_current_user
 from app.core.storage import OSSStorageService, get_storage_service
 from app.core.task_enqueue import (
@@ -10,7 +11,6 @@ from app.core.task_enqueue import (
     USER_PENDING_LIMIT,
     GlobalQueueFull,
     UserPendingLimitExceeded,
-    check_queue_limits,
     safe_enqueue_generation_task,
 )
 from app.dependencies import (
@@ -32,8 +32,6 @@ from app.schemas.generation_task import (
 )
 from fastapi import APIRouter, Depends, HTTPException
 
-from app.api.routes._helpers import check_project_access
-
 from packages.application import (
     CreateGenerationTaskCommand,
     CreateGenerationTaskUseCase,

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

@@ -7,7 +7,7 @@ from app.schemas.project import (
     ListProjectsResponse,
     ProjectResponse,
 )
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, Response, status
 
 from packages.application import (
     CreateProjectCommand,
@@ -72,12 +72,12 @@ def create_project(
     return _to_project_response(project)
 
 
-@router.delete("/{project_id}")
+@router.delete("/{project_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
 def delete_project(
     project_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
     project_repository: Any = Depends(get_project_repository),
-):
+) -> dict:
     use_case = DeleteProjectUseCase(project_repository)
     try:
         deleted = use_case.execute(project_id, authenticated_user.user.id)
@@ -88,4 +88,4 @@ def delete_project(
         )
     if not deleted:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
-    return {"message": "Project deleted successfully"}
+    return

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

@@ -92,7 +92,7 @@ def _build_subscription_info(user: AuthenticatedUser) -> SubscriptionInfo:
 @router.get("/current", response_model=SubscriptionInfo)
 async def get_current_subscription(
     current_user: AuthenticatedUser = Depends(get_current_user),
-):
+) -> SubscriptionInfo:
     """获取当前订阅信息"""
     return _build_subscription_info(current_user)
 
@@ -100,7 +100,7 @@ async def get_current_subscription(
 @router.get("/billing-records", response_model=List[BillingRecord])
 async def get_billing_records(
     current_user: AuthenticatedUser = Depends(get_current_user),
-):
+) -> List[BillingRecord]:
     """获取账单记录列表"""
     from packages.adapters.sqlalchemy_impl.billing_repository import SQLAlchemyBillingRepository
     from packages.adapters.sqlalchemy_impl.session import SessionLocal
@@ -134,7 +134,7 @@ async def change_plan(
     request: ChangePlanRequest,
     current_user: AuthenticatedUser = Depends(get_current_user),
     user_repository: UserRepository = Depends(get_user_repository),
-):
+) -> ChangePlanResponse:
     """变更订阅套餐（升级/降级）"""
     # TODO: 接入支付验证（支付宝/微信支付）
     valid_plans = {"free", "standard", "pro", "enterprise"}
@@ -186,7 +186,7 @@ async def change_plan(
 async def cancel_subscription(
     current_user: AuthenticatedUser = Depends(get_current_user),
     user_repository: UserRepository = Depends(get_user_repository),
-):
+) -> SimpleResponse:
     """取消订阅"""
     user = current_user.user
     if user.subscription_plan == "free":
@@ -212,7 +212,7 @@ async def payment_callback(
     amount: float,
     payment_method: str = "alipay",
     payment_id: str = "",
-):
+) -> dict:
     """支付回调 - 在事务中更新账单和订阅状态
 
     注意：生产环境需要验证支付签名
@@ -263,7 +263,7 @@ async def payment_callback(
 async def toggle_auto_renew(
     request: ToggleAutoRenewRequest,
     current_user: AuthenticatedUser = Depends(get_current_user),
-):
+) -> SimpleResponse:
     """切换自动续费"""
     # TODO: 实际需要在数据库中存储 auto_renew 字段
     status_text = "已开启自动续费" if request.enabled else "已关闭自动续费"

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

@@ -10,7 +10,7 @@ from app.schemas.tag import (
     ListTagsResponse,
     TagResponse,
 )
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Response
 
 from packages.domain import Tag
 
@@ -52,7 +52,7 @@ def create_tag(
     return TagResponse(id=created.id, name=created.name, created_at=created.created_at)
 
 
-@router.delete("/{tag_id}", status_code=204)
+@router.delete("/{tag_id}", status_code=204, response_class=Response)
 def delete_tag(
     tag_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),

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

@@ -206,7 +206,7 @@ def update_template(
     return _to_response(template)
 
 
-@router.delete("/{template_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
+@router.delete("/{template_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
 def delete_template(
     template_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -217,7 +217,7 @@ def delete_template(
     deleted = use_case.execute(template_id, user_id)
     if not deleted:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Template not found")
-    return Response(status_code=204)
+    return
 
 
 @router.post("/{template_id}/toggle-favorite", response_model=ToggleFavoriteResponse)
@@ -307,7 +307,7 @@ def create_category(
     )
 
 
-@router.delete("/categories/{category_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
+@router.delete("/categories/{category_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
 def delete_category(
     category_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -318,4 +318,4 @@ def delete_category(
     deleted = use_case.execute(category_id, user_id)
     if not deleted:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Category not found")
-    return Response(status_code=204)
+    return

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

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from typing import Optional
 
+from app.api.routes._helpers import get_user_plan
 from app.auth import AuthenticatedUser, get_current_user
 from app.dependencies import get_db_session, get_user_repository
 from app.schemas.title_library import (
@@ -28,8 +29,6 @@ from packages.application.title_library.use_cases import (
 )
 from packages.ports.user_repository import UserRepository
 
-from app.api.routes._helpers import get_user_plan
-
 router = APIRouter()
 
 
@@ -138,7 +137,7 @@ def update_title(
     return _to_response(item)
 
 
-@router.delete("/{title_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
+@router.delete("/{title_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
 def delete_title(
     title_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -149,4 +148,4 @@ def delete_title(
     deleted = use_case.execute(title_id, user_id)
     if not deleted:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Title not found")
-    return Response(status_code=204)
+    return

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

@@ -241,7 +241,7 @@ def get_tts_job_status(
     )
 
 
-@router.delete("/jobs/{job_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
+@router.delete("/jobs/{job_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
 def delete_tts_job(
     job_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -253,7 +253,7 @@ def delete_tts_job(
     deleted = use_case.execute(job_id, user_id)
     if not deleted:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="TTS job not found")
-    return Response(status_code=204)
+    return
 
 
 @router.post(
@@ -372,10 +372,10 @@ async def tts_websocket_stream(
         streaming_service = TTSStreamingService(cosyvoice_service)
         await streaming_service.synthesize_and_stream(websocket, params)
     except WebSocketDisconnect:
-        logger.info("WebSocket 客户端断开连接")
+        logger.info("WebSocket 客户端主动断开连接")
     except Exception as e:
         logger.error(f"WebSocket 流式合成异常: {e}", exc_info=True)
         try:
             await websocket.send_json({"type": "error", "message": f"服务异常: {e}"})
-        except Exception:
-            pass
+        except Exception as send_err:
+            logger.warning("WebSocket 错误消息发送失败（连接可能已断开）: %s", send_err)

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

@@ -2,6 +2,7 @@ import logging
 from typing import Any
 from uuid import uuid4
 
+from app.api.routes._helpers import require_project_and_library
 from app.auth import AuthenticatedUser, get_current_user
 from app.config import get_settings
 from app.core.celery_app import celery_app
@@ -23,8 +24,6 @@ from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile, s
 
 from packages.application import SubmitIngestJobCommand, SubmitIngestJobUseCase
 
-from app.api.routes._helpers import require_project_and_library
-
 logger = logging.getLogger(__name__)
 
 router = APIRouter()

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

@@ -172,6 +172,7 @@ def get_voice_clone_status(
     "/{clone_id}",
     status_code=status.HTTP_204_NO_CONTENT,
     response_model=None,
+    response_class=Response,
 )
 def delete_voice_clone(
     clone_id: str,
@@ -184,7 +185,7 @@ def delete_voice_clone(
     deleted = use_case.execute(clone_id, user_id)
     if not deleted:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice clone not found")
-    return Response(status_code=204)
+    return
 
 
 @router.post("/{clone_id}/retry", response_model=VoiceCloneProfileResponse)

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

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 from typing import Literal, Optional
 
+from app.api.routes._helpers import get_user_plan
 from app.auth import AuthenticatedUser, get_current_user
 from app.dependencies import get_audio_url_signer, get_db_session, get_user_repository
 from app.schemas.voice import (
@@ -39,8 +40,6 @@ from packages.application.voice_library.use_cases import (
 from packages.domain.preset_voices import PRESET_VOICES
 from packages.ports.user_repository import UserRepository
 
-from app.api.routes._helpers import get_user_plan
-
 router = APIRouter()
 
 
@@ -323,7 +322,7 @@ def update_voice(
     return _to_response(item, sign_url)
 
 
-@router.delete("/{voice_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
+@router.delete("/{voice_id}", status_code=status.HTTP_204_NO_CONTENT, response_model=None, response_class=Response)
 def delete_voice(
     voice_id: str,
     authenticated_user: AuthenticatedUser = Depends(get_current_user),
@@ -334,4 +333,4 @@ def delete_voice(
     deleted = use_case.execute(voice_id, user_id)
     if not deleted:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Voice not found")
-    return Response(status_code=204)
+    return

apps/api/app/config.py

@@ -19,7 +19,6 @@ class Settings(BaseSettings):
     # Container bind address; external expose is controlled by Docker/Nginx.
     API_HOST: str = "0.0.0.0"  # nosec: B104
     API_PORT: int = 8000
-    API_PREFIX: str = "/api/v1"
 
     DATABASE_URL: str = "postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas"
     DATABASE_POOL_SIZE: int = 20
@@ -30,16 +29,10 @@ class Settings(BaseSettings):
     AUTO_CREATE_SCHEMA: bool = False
 
     REDIS_URL: str = "redis://localhost:6379/0"
-    REDIS_MAX_CONNECTION: int = 50
     ENABLE_REDIS_SESSIONS: bool = False
 
     # JWT secret key - MUST be set via environment variable, no default allowed
     JWT_SECRET_KEY: Optional[str] = None
-    # 旧的 JWT secret key（用于密钥轮换期间验证旧 token）
-    # 在密钥轮换时，先设置新密钥，旧密钥保留在此处直到所有旧 token 过期
-    JWT_SECRET_KEY_OLD: Optional[str] = None
-    # 密钥轮换天数（到达此天数后建议更换密钥）
-    SECRET_ROTATION_DAYS: int = 90
 
     # JWT 算法与过期时间（与 .env.example 对齐）
     JWT_ALGORITHM: str = "HS256"
@@ -111,7 +104,6 @@ class Settings(BaseSettings):
     )
     OSS_DIRECT_UPLOAD_EXPIRE_SECONDS: int = 900
 
-    LOG_LEVEL: str = "INFO"
     CORS_ORIGINS_RAW: str = "http://localhost:3000,http://localhost:5173,http://localhost:8000"
 
     # 渲染引擎选择：legacy=旧VideoComposeService，unified=新UnifiedRenderService

apps/api/app/core/storage.py

@@ -1,283 +1,14 @@
-"""阿里云 OSS 存储服务"""
+"""Backward-compatible re-export from shared storage.
 
-import base64
-import datetime as dt
-import hashlib
-import hmac
-import json
-import logging
-import os
-from urllib.parse import urlparse
+All storage logic now lives in ``packages.shared.storage``.
+This module keeps old import paths working so existing code
+does not need to change.
+"""
 
-try:
-    import oss2
-except ImportError:  # pragma: no cover - exercised in minimal local/test environments
-    oss2 = None
-from app.config import get_settings
+from packages.shared.storage import SharedStorageService as OSSStorageService
+from packages.shared.storage import (
+    get_shared_storage_service,
+    get_storage_service,
+)
 
-logger = logging.getLogger(__name__)
-
-
-class OSSStorageService:
-    """阿里云 OSS 存储服务"""
-
-    def __init__(self):
-        settings = get_settings()
-        self.bucket_name = settings.OSS_BUCKET_NAME
-        self.public_url = f"https://{settings.OSS_BUCKET_NAME}.{settings.OSS_ENDPOINT}"
-        self.local_url_prefix = os.getenv("GENERATED_FILES_URL_PREFIX", "/generated-files")
-        self.bucket = None
-
-        has_key_id = bool(settings.OSS_ACCESS_KEY_ID)
-        has_key_secret = bool(settings.OSS_ACCESS_KEY_SECRET)
-
-        if has_key_id and has_key_secret:
-            if oss2 is not None:
-                try:
-                    # P0-2 修复：oss2.Bucket 的 endpoint 必须带 https:// 前缀，
-                    # 否则 sign_url 默认生成 HTTP URL。
-                    bucket_endpoint = settings.OSS_ENDPOINT
-                    if not bucket_endpoint.startswith(("http://", "https://")):
-                        bucket_endpoint = f"https://{bucket_endpoint}"
-                    auth = oss2.Auth(
-                        settings.OSS_ACCESS_KEY_ID,
-                        settings.OSS_ACCESS_KEY_SECRET,
-                    )
-                    self.bucket = oss2.Bucket(
-                        auth,
-                        bucket_endpoint,
-                        settings.OSS_BUCKET_NAME,
-                    )
-                    logger.info(
-                        "OSS initialized: endpoint=%s bucket=%s",
-                        settings.OSS_ENDPOINT,
-                        settings.OSS_BUCKET_NAME,
-                    )
-                except Exception as error:
-                    logger.error("Failed to initialize OSS bucket client: %s", error)
-            else:
-                logger.error("oss2 SDK is not installed — OSS operations will fail")
-        else:
-            missing = []
-            if not has_key_id:
-                missing.append("OSS_ACCESS_KEY_ID")
-            if not has_key_secret:
-                missing.append("OSS_ACCESS_KEY_SECRET")
-            logger.error("OSS credentials not configured — missing: %s", ", ".join(missing))
-
-        self.access_key_id = settings.OSS_ACCESS_KEY_ID
-        self.access_key_secret = settings.OSS_ACCESS_KEY_SECRET
-        self.endpoint = settings.OSS_ENDPOINT
-
-    def diagnose(self) -> None:
-        """启动诊断：输出 OSS 配置状态，帮助排查预签名 URL 问题。"""
-        key_id_display = (
-            f"{self.access_key_id[:4]}...{self.access_key_id[-4:]}" if len(self.access_key_id) > 8 else "(empty)"
-        )
-        logger.info(
-            "[OSS诊断] endpoint=%s bucket_name=%s access_key_id=%s",
-            self.endpoint,
-            self.bucket_name,
-            key_id_display,
-        )
-        if self.bucket is None:
-            logger.error(
-                "[OSS诊断] ❌ bucket=None — 预签名URL不可用！"
-                "原因: OSS_ACCESS_KEY_ID/OSS_ACCESS_KEY_SECRET 未配置或 oss2 未安装。"
-                "请检查服务器 .env 文件（如 /var/lib/xiaoxia-saas-staging/.env）"
-            )
-        else:
-            logger.info("[OSS诊断] ✅ bucket 已配置，预签名URL可用")
-
-    def _is_local_generated_url(self, storage_key_or_url: str) -> bool:
-        parsed = urlparse(storage_key_or_url)
-        path = parsed.path if parsed.scheme else storage_key_or_url
-        return path.startswith(f"{self.local_url_prefix}/")
-
-    def create_direct_upload_post(
-        self,
-        storage_key: str,
-        content_type: str,
-        max_size_bytes: int,
-        expires_seconds: int,
-    ) -> dict[str, object]:
-        """创建浏览器直传 OSS 的 PostObject 表单。"""
-        if not self.access_key_id or not self.access_key_secret:
-            raise RuntimeError("OSS storage is not configured")
-        normalized_key = self._normalize_storage_key(storage_key)
-        if not normalized_key.startswith("uploads/"):
-            raise ValueError("direct upload key must be under uploads/")
-
-        expiration = (dt.datetime.now(dt.timezone.utc) + dt.timedelta(seconds=expires_seconds)).strftime(
-            "%Y-%m-%dT%H:%M:%S.000Z"
-        )
-        policy = {
-            "expiration": expiration,
-            "conditions": [
-                {"bucket": self.bucket_name},
-                {"key": normalized_key},
-                ["content-length-range", 1, max_size_bytes],
-                ["starts-with", "$Content-Type", content_type.split("/", 1)[0] + "/" if "/" in content_type else ""],
-            ],
-        }
-        encoded_policy = base64.b64encode(json.dumps(policy, separators=(",", ":")).encode("utf-8")).decode("ascii")
-        signature = base64.b64encode(
-            hmac.new(self.access_key_secret.encode("utf-8"), encoded_policy.encode("utf-8"), hashlib.sha1).digest()
-        ).decode("ascii")
-
-        return {
-            "url": self.public_url,
-            "method": "POST",
-            "storage_key": normalized_key,
-            "expires_at": expiration,
-            "fields": {
-                "key": normalized_key,
-                "OSSAccessKeyId": self.access_key_id,
-                "policy": encoded_policy,
-                "Signature": signature,
-                "success_action_status": "201",
-                "Content-Type": content_type,
-            },
-        }
-
-    def upload_file(
-        self,
-        file_or_path,
-        storage_key: str,
-        content_type: str = "application/octet-stream",
-    ) -> str:
-        """
-        上传文件到 OSS
-
-        Args:
-            file_or_path: 文件对象或本地文件路径
-            storage_key: 存储键（文件路径）
-            content_type: 内容类型
-
-        Returns:
-            文件公网 URL
-        """
-        if self.bucket is None:
-            raise RuntimeError("OSS storage is not configured")
-
-        try:
-            # 如果是字符串路径，从本地文件上传
-            if isinstance(file_or_path, str):
-                self.bucket.put_object_from_file(storage_key, file_or_path, headers={"Content-Type": content_type})
-            else:
-                # 文件对象
-                file_or_path.seek(0)
-                self.bucket.put_object(storage_key, file_or_path, headers={"Content-Type": content_type})
-
-            return f"{self.public_url}/{storage_key}"
-        except Exception as e:
-            raise Exception(f"Failed to upload file to OSS: {e}")
-
-    def get_url(self, storage_key: str) -> str:
-        """获取文件公网 URL"""
-        return f"{self.public_url}/{storage_key}"
-
-    def get_download_url(self, storage_key_or_url: str, expires_seconds: int = 3600) -> str:
-        """
-        获取文件下载签名 URL（用于私有文件）
-
-        Args:
-            storage_key_or_url: 存储键或完整 URL
-            expires_seconds: 过期时间（秒）
-
-        Returns:
-            签名 URL
-        """
-        if self.bucket is None:
-            if self._is_local_generated_url(storage_key_or_url):
-                return storage_key_or_url
-            logger.warning(
-                "get_download_url: OSS bucket not configured, returning raw URL. " "storage_key_or_url=%s",
-                storage_key_or_url[:200],
-            )
-            return self.get_url(self._normalize_storage_key(storage_key_or_url))
-
-        storage_key = self._normalize_storage_key(storage_key_or_url)
-        try:
-            signed = self.bucket.sign_url("GET", storage_key, expires_seconds)
-            logger.info(
-                "get_download_url: signed URL generated. storage_key=%s url_prefix=%s",
-                storage_key[:80],
-                signed[:60],
-            )
-            return signed
-        except Exception:
-            logger.exception(
-                "get_download_url: sign_url failed, falling back to raw URL. " "storage_key=%s",
-                storage_key[:200],
-            )
-            return self.get_url(storage_key)
-
-    def _normalize_storage_key(self, storage_key_or_url: str) -> str:
-        """从 URL 中提取存储键"""
-        if storage_key_or_url.startswith("http://") or storage_key_or_url.startswith("https://"):
-            parsed = urlparse(storage_key_or_url)
-            # 移除开头的 /
-            return parsed.path.lstrip("/")
-        return storage_key_or_url.lstrip("/")
-
-    def download_file(self, storage_key: str, local_path: str):
-        """
-        从 OSS 下载文件到本地
-
-        Args:
-            storage_key: 存储键
-            local_path: 本地文件路径
-        """
-        if self.bucket is None:
-            raise RuntimeError("OSS storage is not configured")
-
-        try:
-            os.makedirs(os.path.dirname(local_path), exist_ok=True)
-            self.bucket.get_object_to_file(storage_key, local_path)
-        except Exception as e:
-            raise Exception(f"Failed to download file from OSS: {e}")
-
-    def delete_file(self, storage_key: str):
-        """
-        删除 OSS 文件
-
-        Args:
-            storage_key: 存储键
-        """
-        if self.bucket is None:
-            return
-
-        try:
-            self.bucket.delete_object(storage_key)
-        except Exception as error:
-            logger.warning(
-                "Failed to delete file from OSS",
-                extra={"storage_key": storage_key, "error": str(error)},
-            )
-
-    def file_exists(self, storage_key: str) -> bool:
-        """
-        检查文件是否存在
-
-        Args:
-            storage_key: 存储键
-
-        Returns:
-            是否存在
-        """
-        if self.bucket is None:
-            return False
-        return self.bucket.object_exists(storage_key)
-
-
-_storage_service = None
-
-
-def get_storage_service() -> OSSStorageService:
-    """获取存储服务实例（全局单例）"""
-    global _storage_service
-    if _storage_service is None:
-        _storage_service = OSSStorageService()
-        _storage_service.diagnose()
-    return _storage_service
+__all__ = ["OSSStorageService", "get_storage_service", "get_shared_storage_service"]

apps/api/app/middleware/auth.py

@@ -7,12 +7,16 @@ common auth dependencies for backward compatibility.
 
 from __future__ import annotations
 
+import logging
+
 from app.auth import AuthenticatedUser
 from app.auth import get_current_user as get_authenticated_user
 from app.dependencies import get_user_repository
 from fastapi import Depends, HTTPException
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 
+logger = logging.getLogger(__name__)
+
 from packages.domain.entities import User
 from packages.ports.user_repository import UserRepository
 
@@ -33,6 +37,10 @@ async def get_current_user_optional(
         return None
     try:
         authenticated_user = await get_authenticated_user(credentials, user_repository)
-    except HTTPException:
+    except HTTPException as exc:
+        if exc.status_code >= 500:
+            # 服务端错误不应被静默吞掉，记录日志
+            logger.error("可选认证遇到服务端错误，status=%s", exc.status_code, exc_info=True)
+        # 4xx 认证失败（如 token 无效、用户不存在）属于正常流程，返回 None
         return None
     return authenticated_user.user

apps/api/app/services/job_service.py

@@ -13,7 +13,6 @@ from __future__ import annotations
 import logging
 from typing import Any
 
-
 from packages.application.jobs import (
     CancelJobUseCase,
     CompleteJobCommand,

apps/web/playwright.config.ts

@@ -26,6 +26,9 @@ export default defineConfig({
           use: {
             ...devices["Desktop Chrome"],
             channel: process.env.E2E_BROWSER_CHANNEL || "msedge",
+            launchOptions: {
+              args: ["--disable-gpu", "--disable-software-rasterizer"],
+            },
           },
         },
         {
@@ -51,6 +54,9 @@ export default defineConfig({
           use: {
             ...devices["Desktop Chrome"],
             channel: process.env.E2E_BROWSER_CHANNEL || "msedge",
+            launchOptions: {
+              args: ["--disable-gpu", "--disable-software-rasterizer"],
+            },
           },
         },
       ],

apps/web/src/api/accounts.ts

@@ -1,161 +0,0 @@
-/**
- * 账号管理 Mock API
- *
- * 模拟多平台账号绑定/解绑操作
- * 支持平台：抖音、快手、小红书、微信视频号
- */
-
-/* ── 类型定义 ───────────────────────────────────────────── */
-
-/** 平台 ID */
-export type PlatformId = "douyin" | "kuaishou" | "xiaohongshu" | "wechat";
-
-/** 账号状态 */
-export type AccountStatus = "active" | "expired" | "limited";
-
-/** 已绑定的账号 */
-export interface Account {
-  id: string;
-  platform_id: PlatformId;
-  name: string;
-  avatar?: string;
-  status: AccountStatus;
-  bound_at: string;
-}
-
-/** 平台信息 */
-export interface Platform {
-  id: PlatformId;
-  name: string;
-  subName: string;
-  icon: string;
-  gradient: string;
-}
-
-/** 绑定账号请求 */
-export interface BindAccountRequest {
-  platform_id: PlatformId;
-  name: string;
-}
-
-/* ── 平台配置 ───────────────────────────────────────────── */
-
-export const PLATFORMS: Platform[] = [
-  {
-    id: "douyin",
-    name: "抖音",
-    subName: "短视频发布平台",
-    icon: "📱",
-    gradient: "linear-gradient(135deg, #fe2c55, #25f4ee)",
-  },
-  {
-    id: "kuaishou",
-    name: "快手",
-    subName: "短视频发布平台",
-    icon: "🎬",
-    gradient: "linear-gradient(135deg, #ff4906, #ffba00)",
-  },
-  {
-    id: "xiaohongshu",
-    name: "小红书",
-    subName: "种草笔记发布平台",
-    icon: "📕",
-    gradient: "linear-gradient(135deg, #ff2442, #ff6b6b)",
-  },
-  {
-    id: "wechat",
-    name: "微信视频号",
-    subName: "视频号发布平台",
-    icon: "💬",
-    gradient: "linear-gradient(135deg, #07c160, #4cd964)",
-  },
-];
-
-/* ── Mock 数据 ───────────────────────────────────────────── */
-
-let MOCK_ACCOUNTS: Account[] = [
-  {
-    id: "acc-001",
-    platform_id: "douyin",
-    name: "小虾官方号",
-    avatar: "🦐",
-    status: "active",
-    bound_at: "2025-12-01T10:00:00Z",
-  },
-  {
-    id: "acc-002",
-    platform_id: "douyin",
-    name: "小虾日常",
-    avatar: "🐟",
-    status: "active",
-    bound_at: "2025-12-15T14:30:00Z",
-  },
-  {
-    id: "acc-003",
-    platform_id: "kuaishou",
-    name: "小虾剪辑",
-    avatar: "🎬",
-    status: "active",
-    bound_at: "2026-01-05T09:00:00Z",
-  },
-  {
-    id: "acc-004",
-    platform_id: "xiaohongshu",
-    name: "小虾种草",
-    avatar: "📕",
-    status: "limited",
-    bound_at: "2026-02-20T16:00:00Z",
-  },
-];
-
-/* ── 模拟延迟 ───────────────────────────────────────────── */
-
-const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
-
-/* ── API 函数 ───────────────────────────────────────────── */
-
-/** 获取指定平台的账号列表 */
-export async function getAccountsByPlatform(
-  platformId: PlatformId,
-): Promise<Account[]> {
-  await delay(300);
-  return MOCK_ACCOUNTS.filter((a) => a.platform_id === platformId);
-}
-
-/** 获取所有平台的账号总数 */
-export async function getAllAccounts(): Promise<Account[]> {
-  await delay(200);
-  return [...MOCK_ACCOUNTS];
-}
-
-/** 绑定新账号 */
-export async function bindAccount(data: BindAccountRequest): Promise<Account> {
-  await delay(500);
-  const newAccount: Account = {
-    id: `acc-${Date.now()}`,
-    platform_id: data.platform_id,
-    name: data.name,
-    avatar: undefined,
-    status: "active",
-    bound_at: new Date().toISOString(),
-  };
-  MOCK_ACCOUNTS = [...MOCK_ACCOUNTS, newAccount];
-  return newAccount;
-}
-
-/** 解绑账号 */
-export async function unbindAccount(accountId: string): Promise<void> {
-  await delay(400);
-  MOCK_ACCOUNTS = MOCK_ACCOUNTS.filter((a) => a.id !== accountId);
-}
-
-/* ── 状态配置 ───────────────────────────────────────────── */
-
-export const ACCOUNT_STATUS_CONFIG: Record<
-  AccountStatus,
-  { label: string; className: string }
-> = {
-  active: { label: "正常", className: "acc-status--active" },
-  expired: { label: "已过期", className: "acc-status--expired" },
-  limited: { label: "受限", className: "acc-status--limited" },
-};

apps/web/src/components/ui/Form.tsx

@@ -1,37 +0,0 @@
-/**
- * V21 Form 表单
- * 封装 Ant Design Form，应用 V21 设计系统样式
- */
-import React from "react";
-import { Form as AntForm } from "antd";
-import type { FormProps as AntFormProps } from "antd";
-import classNames from "classnames";
-import "./ui.css";
-
-export interface FormProps extends AntFormProps {
-  /** 紧凑模式（减小表单项间距） */
-  compact?: boolean;
-}
-
-const Form = ({ className, compact, children, ...rest }: FormProps) => {
-  const v21Class = classNames(
-    "xx-form",
-    compact && "xx-form-compact",
-    className,
-  );
-  return (
-    <AntForm
-      className={v21Class}
-      {...(rest as Omit<FormProps, "className" | "compact" | "children">)}
-    >
-      {children as React.ReactNode}
-    </AntForm>
-  );
-};
-
-/** 导出 Form 的子组件（保持 antd API 一致） */
-export const FormItem = AntForm.Item;
-export const FormList = AntForm.List;
-export const FormProvider = AntForm.Provider;
-
-export default Form;

apps/web/src/components/ui/Pagination.tsx

@@ -1,25 +0,0 @@
-/**
- * V21 Pagination 分页
- * 封装 Ant Design Pagination，应用 V21 设计系统样式
- */
-import React from "react";
-import { Pagination as AntPagination } from "antd";
-import type { PaginationProps as AntPaginationProps } from "antd";
-import classNames from "classnames";
-import "./ui.css";
-
-export interface PaginationProps extends AntPaginationProps {
-  /** 使用 V21 样式 */
-  v21?: boolean;
-}
-
-const Pagination: React.FC<PaginationProps> = ({
-  className,
-  v21 = true,
-  ...rest
-}) => {
-  const v21Class = classNames(v21 && "xx-pagination", className);
-  return <AntPagination className={v21Class} {...rest} />;
-};
-
-export default Pagination;

apps/web/src/components/ui/Table.tsx

@@ -1,29 +0,0 @@
-/**
- * V21 Table 表格
- * 封装 Ant Design Table，应用 V21 设计系统样式
- */
-import React from "react";
-import { Table as AntTable } from "antd";
-import type { TableProps as AntTableProps } from "antd";
-import classNames from "classnames";
-import "./ui.css";
-
-export interface TableProps<
-  RecordType = unknown,
-> extends AntTableProps<RecordType> {
-  /** 使用 V21 样式 */
-  v21?: boolean;
-}
-
-function Table<RecordType extends object = Record<string, unknown>>({
-  className,
-  v21 = true,
-  ...rest
-}: TableProps<RecordType>) {
-  const v21Class = classNames(v21 && "xx-table", className);
-  return <AntTable<RecordType> className={v21Class} {...rest} />;
-}
-
-export default Table as <RecordType extends object = Record<string, unknown>>(
-  props: TableProps<RecordType> & React.RefAttributes<HTMLDivElement>,
-) => React.ReactElement;

apps/web/src/components/ui/index.ts

@@ -15,9 +15,6 @@ export type { SelectProps } from "./Select";
 export { default as Modal } from "./Modal";
 export type { ModalProps } from "./Modal";
 
-export { default as Table } from "./Table";
-export type { TableProps } from "./Table";
-
 export { default as Card } from "./Card";
 export type { CardProps } from "./Card";
 
@@ -26,9 +23,3 @@ export type { TagProps, TagVariant } from "./Tag";
 
 export { Tooltip, Popover } from "./Tooltip";
 export type { TooltipProps, PopoverProps } from "./Tooltip";
-
-export { default as Form, FormItem, FormList, FormProvider } from "./Form";
-export type { FormProps } from "./Form";
-
-export { default as Pagination } from "./Pagination";
-export type { PaginationProps } from "./Pagination";

apps/web/src/components/ui/ui.css

@@ -258,51 +258,6 @@
   font-size: 24px !important;
 }
 
-/* ============================================================
-   Table 表格
-   ============================================================ */
-.xx-table .ant-table {
-  background: var(--bg-primary) !important;
-  color: var(--text-primary) !important;
-  border-radius: var(--radius-md) !important;
-  overflow: hidden;
-}
-
-.xx-table .ant-table-thead > tr > th {
-  background: var(--bg-secondary) !important;
-  color: var(--text-secondary) !important;
-  font-weight: var(--font-weight-semibold) !important;
-  border-bottom: 1px solid var(--border-color) !important;
-  font-size: var(--font-size-sm) !important;
-  text-transform: uppercase;
-  letter-spacing: var(--letter-spacing-wide);
-}
-
-.xx-table .ant-table-tbody > tr > td {
-  border-bottom: 1px solid var(--border-light) !important;
-  color: var(--text-primary) !important;
-  transition: var(--transition-fast) !important;
-}
-
-.xx-table .ant-table-tbody > tr:hover > td {
-  background: var(--primary-soft) !important;
-}
-
-.xx-table .ant-table-tbody > tr:last-child > td {
-  border-bottom: none !important;
-}
-
-/* 排序图标 */
-.xx-table .ant-table-column-sorter-up.active,
-.xx-table .ant-table-column-sorter-down.active {
-  color: var(--primary-color) !important;
-}
-
-/* 分页 */
-.xx-table .ant-pagination {
-  padding: var(--space-md) 0 !important;
-}
-
 /* ============================================================
    Card 卡片
    ============================================================ */
@@ -429,68 +384,6 @@
   border-bottom: 1px solid var(--border-light) !important;
 }
 
-/* ============================================================
-   Form 表单
-   ============================================================ */
-.xx-form .ant-form-item-label > label {
-  color: var(--text-primary) !important;
-  font-weight: var(--font-weight-medium) !important;
-  font-size: var(--font-size-base) !important;
-}
-
-.xx-form .ant-form-item-explain-error {
-  color: var(--error-color) !important;
-  font-size: var(--font-size-sm) !important;
-}
-
-.xx-form .ant-form-item {
-  margin-bottom: var(--space-lg) !important;
-}
-
-/* 表单项间距紧凑 */
-.xx-form-compact .ant-form-item {
-  margin-bottom: var(--space-md) !important;
-}
-
-/* ============================================================
-   Pagination 分页
-   ============================================================ */
-.xx-pagination .ant-pagination-item {
-  border-radius: var(--radius-xs) !important;
-  border-color: var(--border-color) !important;
-  transition: var(--transition-fast) !important;
-}
-
-.xx-pagination .ant-pagination-item a {
-  color: var(--text-primary) !important;
-}
-
-.xx-pagination .ant-pagination-item:hover {
-  border-color: var(--primary-color) !important;
-}
-
-.xx-pagination .ant-pagination-item:hover a {
-  color: var(--primary-color) !important;
-}
-
-.xx-pagination .ant-pagination-item-active {
-  background: var(--gradient-primary) !important;
-  border-color: transparent !important;
-}
-
-.xx-pagination .ant-pagination-item-active a {
-  color: var(--text-inverse) !important;
-}
-
-.xx-pagination .ant-pagination-prev .ant-pagination-item-link,
-.xx-pagination .ant-pagination-next .ant-pagination-item-link {
-  border-radius: var(--radius-xs) !important;
-  color: var(--text-secondary) !important;
-}
-
-.xx-pagination .ant-pagination-disabled .ant-pagination-item-link {
-  color: var(--text-disabled) !important;
-}
 
 /* ============================================================
    响应式
@@ -517,9 +410,6 @@
     padding: var(--space-md) !important;
   }
 
-  .xx-form .ant-form-item {
-    margin-bottom: var(--space-md) !important;
-  }
 }
 
 @media (max-width: 480px) {

apps/web/src/pages/accounts/Accounts.tsx

@@ -2,194 +2,62 @@
  * 账号管理页面 — V21 Design System
  *
  * 展示多平台账号绑定状态（抖音/快手/小红书/微信视频号）
- * 支持绑定/解绑操作
+ * 后端账号管理 API 尚未就绪，当前展示占位状态
  *
  * 零 antd 直接导入，全部使用 CSS 变量
  */
-import React, { useState, useCallback } from "react";
-import { useQueries, useMutation, useQueryClient } from "@tanstack/react-query";
+import React from "react";
 import { Button } from "@/components/ui";
 import PageHead from "@/components/layout/PageHead";
-import {
-  PLATFORMS,
-  getAccountsByPlatform,
-  unbindAccount,
-  bindAccount,
-  ACCOUNT_STATUS_CONFIG,
-  type Platform,
-  type Account,
-  type PlatformId,
-} from "@/api/accounts";
 import "./accounts.css";
 
-/* ── Toast 系统 ─────────────────────────────────────────── */
+/* ── 类型定义 ───────────────────────────────────────────── */
 
-interface Toast {
-  id: number;
-  message: string;
-  type: "success" | "error";
+export type PlatformId = "douyin" | "kuaishou" | "xiaohongshu" | "wechat";
+
+export interface Platform {
+  id: PlatformId;
+  name: string;
+  subName: string;
+  icon: string;
+  gradient: string;
 }
 
-let toastIdCounter = 0;
-
-/* ── 平台卡片组件 ───────────────────────────────────────── */
-
-interface PlatformCardProps {
-  platform: Platform;
-  accounts: Account[];
-  isLoading: boolean;
-  onBind: (platformId: PlatformId) => void;
-  onUnbind: (accountId: string, accountName: string) => void;
-}
-
-const PlatformCard: React.FC<PlatformCardProps> = ({
-  platform,
-  accounts,
-  isLoading,
-  onBind,
-  onUnbind,
-}) => {
-  return (
-    <div className="acc-card">
-      {/* 平台头部 */}
-      <div className="acc-card-header">
-        <div
-          className="acc-card-icon"
-          style={{ background: platform.gradient }}
-        >
-          {platform.icon}
-        </div>
-        <div>
-          <h3 className="acc-card-title">{platform.name}</h3>
-          <p className="acc-card-subtitle">{platform.subName}</p>
-        </div>
-      </div>
-
-      {/* 账号列表 */}
-      <div className="acc-account-list">
-        {isLoading ? (
-          <div className="acc-empty">
-            <p className="acc-empty-text">加载中…</p>
-          </div>
-        ) : accounts.length > 0 ? (
-          accounts.map((account) => {
-            const statusCfg = ACCOUNT_STATUS_CONFIG[account.status];
-            return (
-              <div key={account.id} className="acc-account-row">
-                <div
-                  className="acc-account-avatar"
-                  style={{ background: platform.gradient }}
-                >
-                  {account.avatar || platform.icon}
-                </div>
-                <div className="acc-account-info">
-                  <div className="acc-account-name">{account.name}</div>
-                  <span className={`acc-status-pill ${statusCfg.className}`}>
-                    {statusCfg.label}
-                  </span>
-                </div>
-                <Button
-                  buttonType="ghost"
-                  buttonSize="sm"
-                  onClick={() => onUnbind(account.id, account.name)}
-                >
-                  解绑
-                </Button>
-              </div>
-            );
-          })
-        ) : (
-          <div className="acc-empty">
-            <div className="acc-empty-icon">🔓</div>
-            <p className="acc-empty-text">暂未绑定账号</p>
-          </div>
-        )}
-      </div>
-
-      {/* 绑定按钮 */}
-      <Button buttonType="ghost" onClick={() => onBind(platform.id)}>
-        + 绑定新账号
-      </Button>
-    </div>
-  );
-};
+/** 支持的平台列表 */
+const PLATFORMS: Platform[] = [
+  {
+    id: "douyin",
+    name: "抖音",
+    subName: "短视频发布",
+    icon: "🎵",
+    gradient: "linear-gradient(135deg, #000 0%, #333 100%)",
+  },
+  {
+    id: "kuaishou",
+    name: "快手",
+    subName: "短视频发布",
+    icon: "📹",
+    gradient: "linear-gradient(135deg, #ff6600 0%, #ff9933 100%)",
+  },
+  {
+    id: "xiaohongshu",
+    name: "小红书",
+    subName: "种草笔记 + 视频",
+    icon: "📕",
+    gradient: "linear-gradient(135deg, #fe2c55 0%, #ff6680 100%)",
+  },
+  {
+    id: "wechat",
+    name: "微信视频号",
+    subName: "视频号发布",
+    icon: "💬",
+    gradient: "linear-gradient(135deg, #07c160 0%, #38d97a 100%)",
+  },
+];
 
 /* ── 主页面 ─────────────────────────────────────────────── */
 
 const Accounts: React.FC = () => {
-  const queryClient = useQueryClient();
-  const [toasts, setToasts] = useState<Toast[]>([]);
-
-  /** 显示 toast */
-  const showToast = useCallback((message: string, type: Toast["type"]) => {
-    const id = ++toastIdCounter;
-    setToasts((prev) => [...prev, { id, message, type }]);
-    setTimeout(() => {
-      setToasts((prev) => prev.filter((t) => t.id !== id));
-    }, 3000);
-  }, []);
-
-  /** 查询所有平台的账号 */
-  const _queriesResults = useQueries({
-    queries: PLATFORMS.map((platform) => ({
-      queryKey: ["accounts", platform.id] as const,
-      queryFn: () => getAccountsByPlatform(platform.id),
-    })),
-  });
-  const accountQueries = PLATFORMS.map((platform, i) => ({
-    platform,
-    ..._queriesResults[i],
-  }));
-
-  /** 解绑 mutation */
-  const unbindMutation = useMutation({
-    mutationFn: unbindAccount,
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["accounts"] });
-      showToast("已解绑账号", "success");
-    },
-    onError: () => {
-      showToast("解绑失败", "error");
-    },
-  });
-
-  /** 绑定 mutation */
-  const bindMutation = useMutation({
-    mutationFn: bindAccount,
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["accounts"] });
-      showToast("账号绑定成功", "success");
-    },
-    onError: () => {
-      showToast("绑定失败", "error");
-    },
-  });
-
-  /** 绑定新账号 */
-  const handleBind = (platformId: PlatformId) => {
-    const platform = PLATFORMS.find((p) => p.id === platformId);
-    if (!platform) return;
-
-    const name = window.prompt(`请输入要绑定的${platform.name}账号名称：`);
-    if (name && name.trim()) {
-      bindMutation.mutate({ platform_id: platformId, name: name.trim() });
-    }
-  };
-
-  /** 解绑账号 */
-  const handleUnbind = (accountId: string, accountName: string) => {
-    if (window.confirm(`确定解绑账号「${accountName}」吗？`)) {
-      unbindMutation.mutate(accountId);
-    }
-  };
-
-  /** 统计已绑定账号数 */
-  const totalBound = accountQueries.reduce(
-    (sum, q) => sum + (q.data?.length ?? 0),
-    0,
-  );
-  const totalPlatforms = PLATFORMS.length;
-
   return (
     <div className="acc-page">
       <PageHead
@@ -197,17 +65,34 @@ const Accounts: React.FC = () => {
         description="绑定您的社交平台账号，用于视频一键发布到各平台"
       />
 
-      {/* 平台卡片网格 */}
+      {/* 平台卡片网格 — 占位状态 */}
       <div className="acc-grid">
-        {accountQueries.map(({ platform, data, isLoading }) => (
-          <PlatformCard
-            key={platform.id}
-            platform={platform}
-            accounts={data ?? []}
-            isLoading={isLoading}
-            onBind={handleBind}
-            onUnbind={handleUnbind}
-          />
+        {PLATFORMS.map((platform) => (
+          <div key={platform.id} className="acc-card">
+            <div className="acc-card-header">
+              <div
+                className="acc-card-icon"
+                style={{ background: platform.gradient }}
+              >
+                {platform.icon}
+              </div>
+              <div>
+                <h3 className="acc-card-title">{platform.name}</h3>
+                <p className="acc-card-subtitle">{platform.subName}</p>
+              </div>
+            </div>
+
+            <div className="acc-account-list">
+              <div className="acc-empty">
+                <div className="acc-empty-icon">🔒</div>
+                <p className="acc-empty-text">功能即将上线</p>
+              </div>
+            </div>
+
+            <Button buttonType="ghost" disabled>
+              即将支持绑定
+            </Button>
+          </div>
         ))}
       </div>
 
@@ -215,22 +100,10 @@ const Accounts: React.FC = () => {
       <div className="acc-stats-bar">
         <span className="acc-stats-icon">📊</span>
         <span className="acc-stats-text">
-          已绑定 <span className="acc-stats-highlight">{totalBound}</span>{" "}
-          个账号 / 支持{" "}
-          <span className="acc-stats-highlight">{totalPlatforms}</span> 个平台
+          支持 <span className="acc-stats-highlight">{PLATFORMS.length}</span>{" "}
+          个平台，功能即将上线
         </span>
       </div>
-
-      {/* Toast 提示 */}
-      {toasts.length > 0 && (
-        <div className="vc-toast-container">
-          {toasts.map((t) => (
-            <div key={t.id} className={`vc-toast vc-toast--${t.type}`}>
-              {t.type === "success" ? "✅" : "❌"} {t.message}
-            </div>
-          ))}
-        </div>
-      )}
     </div>
   );
 };

apps/web/src/pages/accounts/accounts.css

@@ -82,77 +82,6 @@
   gap: 10px;
 }
 
-/* ── 账号行 ─────────────────────────────────────────────── */
-
-.acc-account-row {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-  padding: 12px;
-  background: var(--bg-secondary);
-  border-radius: var(--radius-md);
-  transition: var(--transition-fast);
-}
-
-.acc-account-row:hover {
-  background: var(--primary-soft);
-}
-
-.acc-account-avatar {
-  width: 36px;
-  height: 36px;
-  border-radius: 50%;
-  display: grid;
-  place-items: center;
-  color: var(--text-inverse);
-  font-weight: var(--font-weight-bold);
-  font-size: var(--font-size-sm);
-  flex-shrink: 0;
-}
-
-.acc-account-info {
-  flex: 1;
-  min-width: 0;
-}
-
-.acc-account-name {
-  font-size: var(--font-size-base);
-  font-weight: var(--font-weight-semibold);
-  color: var(--text-primary);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-}
-
-/* ── 状态标签 ───────────────────────────────────────────── */
-
-.acc-status-pill {
-  display: inline-flex;
-  align-items: center;
-  gap: 4px;
-  padding: 2px 8px;
-  border-radius: var(--radius-full);
-  font-size: var(--font-size-xs);
-  font-weight: var(--font-weight-semibold);
-  line-height: 1.6;
-  margin-top: 2px;
-}
-
-.acc-status--active {
-  background: var(--success-soft);
-  color: var(--secondary-color);
-}
-
-.acc-status--expired {
-  background: var(--error-soft);
-  color: var(--error-color);
-}
-
-.acc-status--limited {
-  background: var(--warning-soft);
-  color: var(--accent-color);
-}
-
 /* ── 空状态 ─────────────────────────────────────────────── */
 
 .acc-empty {
@@ -235,17 +164,6 @@
     font-size: var(--font-size-base);
   }
 
-  .acc-account-row {
-    padding: 10px;
-    gap: 8px;
-  }
-
-  .acc-account-avatar {
-    width: 32px;
-    height: 32px;
-    font-size: var(--font-size-xs);
-  }
-
   .acc-stats-bar {
     padding: var(--space-sm) var(--space-md);
     font-size: var(--font-size-sm);

apps/web/src/pages/admin/Admin.css

@@ -1,442 +1,20 @@
-/* V21 Admin 页面样式 */
+/* Admin 页面样式（Phase 3 精简）
+ *
+ * 原始 477 行 → 精简至仅保留实际使用的 class。
+ * 已迁移至 global.css / ui.css 的样式不再重复定义：
+ *   .xx-page-head       → global.css
+ *   .xx-primary-btn     → global.css
+ *   .xx-tag / .xx-card  → ui.css / global.css
+ *
+ * 以下 class 仅被 AdminComingSoon.tsx 使用。
+ */
 
-/* 页面容器 */
-.dashboard-page,
-.analytics-page,
-.user-management-page,
-.log-viewer-page,
-.system-monitor-page,
 .admin-coming-soon-page {
   padding: 32px;
   max-width: 1400px;
   margin: 0 auto;
 }
 
-/* 页面头部 */
-.xx-page-head {
-  background: rgba(255, 255, 255, 0.94);
-  border: 1px solid rgba(226, 232, 240, 0.95);
-  border-radius: var(--radius-xl);
-  box-shadow: 0 24px 70px rgba(15, 23, 42, 0.09);
-  padding: 32px 40px;
-  margin-bottom: 32px;
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-}
-
-.xx-page-head-content {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-}
-
-.xx-page-head h2 {
-  font-size: 28px;
-  font-weight: 900;
-  color: var(--slate, #0f172a);
-  margin: 0;
-  letter-spacing: -0.02em;
-}
-
-.xx-page-head p {
-  font-size: 15px;
-  color: var(--muted, #64748b);
-  margin: 0;
-}
-
-.xx-page-head-actions {
-  display: flex;
-  gap: 12px;
-  align-items: center;
-}
-
-/* 简化页面头部（无操作按钮） */
-.xx-page-head-simple {
-  background: rgba(255, 255, 255, 0.94);
-  border: 1px solid rgba(226, 232, 240, 0.95);
-  border-radius: var(--radius-xl);
-  box-shadow: 0 24px 70px rgba(15, 23, 42, 0.09);
-  padding: 32px 40px;
-  margin-bottom: 32px;
-}
-
-.xx-page-head-simple h2 {
-  font-size: 28px;
-  font-weight: 900;
-  color: var(--slate, #0f172a);
-  margin: 0 0 8px;
-  letter-spacing: -0.02em;
-}
-
-.xx-page-head-simple p {
-  font-size: 15px;
-  color: var(--muted, #64748b);
-  margin: 0;
-}
-
-/* 统计卡片网格 - 4列 */
-.xx-grid-4 {
-  display: grid;
-  grid-template-columns: repeat(4, 1fr);
-  gap: 24px;
-  margin-bottom: 32px;
-}
-
-@media (max-width: 1200px) {
-  .xx-grid-4 {
-    grid-template-columns: repeat(2, 1fr);
-  }
-}
-
-@media (max-width: 768px) {
-  .xx-grid-4 {
-    grid-template-columns: 1fr;
-  }
-}
-
-/* 统计卡片 */
-.xx-stat-card {
-  background: rgba(255, 255, 255, 0.94);
-  border: 1px solid rgba(226, 232, 240, 0.95);
-  border-radius: var(--radius-lg);
-  box-shadow: 0 10px 30px rgba(15, 23, 42, 0.06);
-  padding: 24px;
-  transition: all 0.3s;
-}
-
-.xx-stat-card:hover {
-  transform: translateY(-2px);
-  box-shadow: 0 16px 40px rgba(15, 23, 42, 0.08);
-}
-
-.xx-stat-card-header {
-  display: flex;
-  justify-content: space-between;
-  align-items: flex-start;
-  margin-bottom: 16px;
-}
-
-.xx-stat-card-icon {
-  width: 48px;
-  height: 48px;
-  border-radius: var(--radius-md);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-size: 22px;
-}
-
-.xx-stat-card-icon.primary {
-  background: linear-gradient(135deg, #6366f1, #4f46e5);
-  color: white;
-}
-
-.xx-stat-card-icon.success {
-  background: linear-gradient(135deg, #34d399, #10b981);
-  color: white;
-}
-
-.xx-stat-card-icon.warning {
-  background: linear-gradient(135deg, #fbbf24, #f59e0b);
-  color: white;
-}
-
-.xx-stat-card-icon.purple {
-  background: linear-gradient(135deg, #a78bfa, #8b5cf6);
-  color: white;
-}
-
-.xx-stat-card-icon.info {
-  background: linear-gradient(135deg, #60a5fa, #3b82f6);
-  color: white;
-}
-
-.xx-stat-card-icon.orange {
-  background: linear-gradient(135deg, #fb923c, #f97316);
-  color: white;
-}
-
-.xx-stat-card-label {
-  font-size: 14px;
-  color: var(--muted, #64748b);
-  font-weight: 500;
-  margin-bottom: 8px;
-}
-
-.xx-stat-card-value {
-  font-size: 32px;
-  font-weight: 900;
-  color: var(--slate, #0f172a);
-  line-height: 1.2;
-  letter-spacing: -0.02em;
-}
-
-.xx-stat-card-value.primary {
-  color: var(--indigo, #4f46e5);
-}
-
-.xx-stat-card-value.success {
-  color: var(--green, #10b981);
-}
-
-.xx-stat-card-value.warning {
-  color: var(--amber, #f59e0b);
-}
-
-.xx-stat-card-value.purple {
-  color: #8b5cf6;
-}
-
-.xx-stat-card-growth {
-  font-size: 13px;
-  color: var(--green, #10b981);
-  font-weight: 600;
-  margin-top: 8px;
-  display: flex;
-  align-items: center;
-  gap: 4px;
-}
-
-/* 数据表格 */
-.xx-table-wrapper {
-  background: rgba(255, 255, 255, 0.94);
-  border: 1px solid rgba(226, 232, 240, 0.95);
-  border-radius: var(--radius-lg);
-  box-shadow: 0 10px 30px rgba(15, 23, 42, 0.06);
-  overflow: hidden;
-}
-
-.xx-table-wrapper .ant-table {
-  background: transparent;
-}
-
-.xx-table-wrapper .ant-table-thead > tr > th {
-  background: rgba(248, 250, 252, 0.8);
-  font-weight: 800;
-  font-size: 13px;
-  color: var(--slate, #0f172a);
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-  padding: 16px 20px;
-}
-
-.xx-table-wrapper .ant-table-tbody > tr > td {
-  padding: 16px 20px;
-  font-size: 14px;
-}
-
-.xx-table-wrapper .ant-table-tbody > tr:hover > td {
-  background: rgba(79, 70, 229, 0.03);
-}
-
-/* V21 按钮 */
-.xx-primary-btn {
-  background: linear-gradient(135deg, #6366f1, #4f46e5) !important;
-  color: white !important;
-  border: none !important;
-  border-radius: var(--radius-md) !important;
-  font-weight: 700 !important;
-  box-shadow: 0 8px 20px rgba(79, 70, 229, 0.25) !important;
-  transition: all 0.2s !important;
-}
-
-.xx-primary-btn:hover {
-  box-shadow: 0 12px 28px rgba(79, 70, 229, 0.3) !important;
-  transform: translateY(-1px);
-}
-
-.xx-ghost-btn {
-  background: white !important;
-  border: 1px solid rgba(226, 232, 240, 0.95) !important;
-  color: var(--slate, #0f172a) !important;
-  border-radius: var(--radius-md) !important;
-  font-weight: 600 !important;
-  transition: all 0.2s !important;
-}
-
-.xx-ghost-btn:hover {
-  border-color: var(--indigo, #4f46e5) !important;
-  color: var(--indigo, #4f46e5) !important;
-}
-
-/* V21 输入框 */
-.xx-search-input {
-  border-radius: var(--radius-md) !important;
-  border: 1px solid rgba(226, 232, 240, 0.95) !important;
-  padding: 8px 16px !important;
-}
-
-.xx-search-input:hover,
-.xx-search-input:focus {
-  border-color: var(--indigo, #4f46e5) !important;
-  box-shadow: 0 0 0 3px rgba(79, 70, 229, 0.1) !important;
-}
-
-/* V21 Tag */
-.xx-tag {
-  border-radius: var(--radius-xs) !important;
-  font-weight: 600 !important;
-  font-size: 12px !important;
-  padding: 4px 10px !important;
-}
-
-.xx-tag.info {
-  background: rgba(59, 130, 246, 0.1) !important;
-  color: #3b82f6 !important;
-  border: 1px solid rgba(59, 130, 246, 0.2) !important;
-}
-
-.xx-tag.success {
-  background: rgba(16, 185, 129, 0.1) !important;
-  color: #10b981 !important;
-  border: 1px solid rgba(16, 185, 129, 0.2) !important;
-}
-
-.xx-tag.warning {
-  background: rgba(245, 158, 11, 0.1) !important;
-  color: #f59e0b !important;
-  border: 1px solid rgba(245, 158, 11, 0.2) !important;
-}
-
-.xx-tag.error {
-  background: rgba(239, 68, 68, 0.1) !important;
-  color: #ef4444 !important;
-  border: 1px solid rgba(239, 68, 68, 0.2) !important;
-}
-
-.xx-tag.debug {
-  background: rgba(100, 116, 139, 0.1) !important;
-  color: #64748b !important;
-  border: 1px solid rgba(100, 116, 139, 0.2) !important;
-}
-
-/* V21 Progress */
-.xx-progress-primary .ant-progress-circle .ant-progress-text {
-  color: var(--indigo, #4f46e5) !important;
-  font-weight: 700 !important;
-}
-
-.xx-progress-success .ant-progress-circle .ant-progress-text {
-  color: var(--green, #10b981) !important;
-  font-weight: 700 !important;
-}
-
-.xx-progress-warning .ant-progress-circle .ant-progress-text {
-  color: var(--amber, #f59e0b) !important;
-  font-weight: 700 !important;
-}
-
-/* 图表容器 */
-.xx-chart-container {
-  background: rgba(255, 255, 255, 0.94);
-  border: 1px solid rgba(226, 232, 240, 0.95);
-  border-radius: var(--radius-lg);
-  box-shadow: 0 10px 30px rgba(15, 23, 42, 0.06);
-  padding: 24px;
-}
-
-.xx-chart-container .ant-card-head {
-  border-bottom: 1px solid rgba(226, 232, 240, 0.8);
-  padding: 20px 24px;
-}
-
-.xx-chart-container .ant-card-head-title {
-  font-weight: 800;
-  font-size: 17px;
-  color: var(--slate, #0f172a);
-}
-
-/* 筛选器区域 */
-.xx-filter-bar {
-  background: rgba(255, 255, 255, 0.94);
-  border: 1px solid rgba(226, 232, 240, 0.95);
-  border-radius: var(--radius-lg);
-  box-shadow: 0 10px 30px rgba(15, 23, 42, 0.06);
-  padding: 20px 24px;
-  margin-bottom: 24px;
-  display: flex;
-  flex-wrap: wrap;
-  gap: 16px;
-  align-items: center;
-}
-
-/* 资源监控卡片 */
-.xx-resource-card {
-  background: rgba(255, 255, 255, 0.94);
-  border: 1px solid rgba(226, 232, 240, 0.95);
-  border-radius: var(--radius-lg);
-  box-shadow: 0 10px 30px rgba(15, 23, 42, 0.06);
-  padding: 24px;
-  text-align: center;
-}
-
-.xx-resource-card-icon {
-  width: 64px;
-  height: 64px;
-  border-radius: var(--radius-md);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  margin: 0 auto 16px;
-  font-size: 28px;
-}
-
-.xx-resource-card-label {
-  font-size: 14px;
-  color: var(--muted, #64748b);
-  font-weight: 600;
-  margin-bottom: 16px;
-}
-
-/* 日期选择器 */
-.xx-date-picker {
-  border-radius: var(--radius-md) !important;
-}
-
-/* Drawer */
-.xx-drawer .ant-drawer-header {
-  border-bottom: 1px solid rgba(226, 232, 240, 0.8);
-  padding: 20px 24px;
-}
-
-.xx-drawer .ant-drawer-title {
-  font-weight: 800;
-  font-size: 18px;
-  color: var(--slate, #0f172a);
-}
-
-/* 日志详情 */
-.xx-log-detail {
-  padding: 4px 0;
-}
-
-.xx-log-detail-label {
-  font-size: 13px;
-  font-weight: 700;
-  color: var(--slate, #0f172a);
-  margin-bottom: 4px;
-}
-
-.xx-log-detail-value {
-  font-size: 14px;
-  color: var(--muted, #64748b);
-  background: rgba(248, 250, 252, 0.8);
-  padding: 12px;
-  border-radius: var(--radius-sm);
-  margin-bottom: 16px;
-}
-
-.xx-log-detail-code {
-  font-family: "JetBrains Mono", "Fira Code", monospace;
-  background: rgba(248, 250, 252, 0.8);
-  padding: 12px;
-  border-radius: var(--radius-sm);
-  white-space: pre-wrap;
-  word-break: break-all;
-}
-
-/* Result 页面居中 */
 .xx-result-center {
   display: flex;
   justify-content: center;
@@ -447,31 +25,3 @@
 .xx-result-center .ant-result {
   padding: 48px;
 }
-
-/* 刷新时间显示 */
-.xx-refresh-time {
-  font-size: 13px;
-  color: var(--muted, #64748b);
-  margin-right: 12px;
-}
-
-/* 图表配色覆盖 */
-.recharts-text {
-  fill: #64748b !important;
-  font-size: 12px !important;
-}
-
-.recharts-cartesian-grid-horizontal line,
-.recharts-cartesian-grid-vertical line {
-  stroke: rgba(226, 232, 240, 0.8) !important;
-}
-
-/* 图表 Legend */
-.recharts-legend-wrapper {
-  padding-top: 16px !important;
-}
-
-.recharts-legend-item-text {
-  color: #64748b !important;
-  font-size: 13px !important;
-}

apps/web/src/pages/dashboard/Dashboard.tsx

@@ -1,454 +1,97 @@
 /**
  * 控制台页面 — V21 设计系统
  * KPI 卡片网格 + 快速入口 + 最近任务卡片列表 + 使用统计图表 + 公告
- * 使用 mock 数据，CSS 变量，V21 组件
+ * CSS 变量，V21 组件
  */
 import React from "react";
 import { useNavigate } from "react-router-dom";
-import { Button, Tag } from "@/components/ui";
-import {
-  VideoCameraOutlined,
-  AppstoreOutlined,
-  ThunderboltOutlined,
-  DatabaseOutlined,
-  FileTextOutlined,
-} from "@ant-design/icons";
+import { Button } from "@/components/ui";
+import { DatabaseOutlined } from "@ant-design/icons";
 import "./dashboard.css";
 
-/* ============================================================
- * Mock 数据
- * ============================================================ */
-interface KpiItem {
-  key: string;
-  icon: string;
-  iconGradient: string;
-  value: string;
-  label: string;
-  trend: string;
-  trendDirection: "up" | "down" | "neutral";
-  accent: string;
-}
+/* ── 主组件 ─────────────────────────────────────────────── */
 
-// TODO: kpiData 当前使用硬编码 mock 数据，待后端提供 Dashboard 统计 API 后替换
-const kpiData: KpiItem[] = [
-  {
-    key: "projects",
-    icon: "video",
-    iconGradient: "linear-gradient(135deg, #6366f1, #4f46e5)",
-    value: "12",
-    label: "项目总数",
-    trend: "↑ 2 本月新增",
-    trendDirection: "up",
-    accent: "#6366f1",
-  },
-  {
-    key: "assets",
-    icon: "appstore",
-    iconGradient: "linear-gradient(135deg, #0ea5e9, #0284c7)",
-    value: "486",
-    label: "素材总数",
-    trend: "↑ 38 本月上传",
-    trendDirection: "up",
-    accent: "#0ea5e9",
-  },
-  {
-    key: "generations",
-    icon: "thunderbolt",
-    iconGradient: "linear-gradient(135deg, #10b981, #059669)",
-    value: "156",
-    label: "本月生成数",
-    trend: "↑ 23% 较上月",
-    trendDirection: "up",
-    accent: "#10b981",
-  },
-  {
-    key: "storage",
-    icon: "database",
-    iconGradient: "linear-gradient(135deg, #f59e0b, #d97706)",
-    value: "2.4GB",
-    label: "存储空间",
-    trend: "已用 24%",
-    trendDirection: "neutral",
-    accent: "#f59e0b",
-  },
-];
-
-interface QuickEntry {
-  id: string;
-  icon: string;
-  iconGradient: string;
-  title: string;
-  description: string;
-  path: string;
-}
-
-// TODO: quickEntries 描述中含硬编码计数（如 486个素材），待后端 API 后动态化
-const quickEntries: QuickEntry[] = [
-  {
-    id: "titles",
-    icon: "filetext",
-    iconGradient: "linear-gradient(135deg, #6366f1, #4f46e5)",
-    title: "标题库",
-    description: "24条标题 · 5个分类",
-    path: "/app/titles",
-  },
-  {
-    id: "assets",
-    icon: "appstore",
-    iconGradient: "linear-gradient(135deg, #0ea5e9, #0284c7)",
-    title: "素材库",
-    description: "486个素材 · 3个素材库",
-    path: "/app/assets",
-  },
-  {
-    id: "generate",
-    icon: "thunderbolt",
-    iconGradient: "linear-gradient(135deg, #10b981, #059669)",
-    title: "一键生成",
-    description: "开始创作新视频",
-    path: "/app/generate",
-  },
-  {
-    id: "products",
-    icon: "video",
-    iconGradient: "linear-gradient(135deg, #f59e0b, #d97706)",
-    title: "成片库",
-    description: "89个成片 · 3个待复核",
-    path: "/app/products",
-  },
-];
-
-type TaskStatus = "completed" | "processing" | "pending" | "failed";
-
-interface RecentTask {
-  id: string;
-  name: string;
-  type: string;
-  template: string;
-  status: TaskStatus;
-  date: string;
-  duration?: string;
-}
-
-const statusLabel: Record<TaskStatus, string> = {
-  completed: "已完成",
-  processing: "进行中",
-  pending: "排队中",
-  failed: "失败",
-};
-
-// TODO: recentTasks 当前使用硬编码 mock 数据，待后端提供最近任务 API 后替换
-const recentTasks: RecentTask[] = [
-  {
-    id: "t-1",
-    name: "产品介绍视频_春季促销",
-    type: "视频生成",
-    template: "商品展示模板",
-    status: "completed",
-    date: "2026-07-01 09:30",
-    duration: "2分18秒",
-  },
-  {
-    id: "t-2",
-    name: "品牌宣传片_终版",
-    type: "视频生成",
-    template: "品牌宣传模板",
-    status: "processing",
-    date: "2026-07-01 10:15",
-  },
-  {
-    id: "t-3",
-    name: "用户评价合集",
-    type: "视频生成",
-    template: "评价展示模板",
-    status: "completed",
-    date: "2026-06-30 16:42",
-    duration: "1分45秒",
-  },
-  {
-    id: "t-4",
-    name: "新品发布预告",
-    type: "视频生成",
-    template: "新品预告模板",
-    status: "pending",
-    date: "2026-06-30 14:20",
-  },
-  {
-    id: "t-5",
-    name: "活动回顾_618大促",
-    type: "视频生成",
-    template: "活动回顾模板",
-    status: "failed",
-    date: "2026-06-29 11:05",
-  },
-];
-
-interface ChartItem {
-  label: string;
-  value: number;
-}
-
-const weeklyData: ChartItem[] = [
-  { label: "周一", value: 18 },
-  { label: "周二", value: 25 },
-  { label: "周三", value: 32 },
-  { label: "周四", value: 28 },
-  { label: "周五", value: 42 },
-  { label: "周六", value: 15 },
-  { label: "周日", value: 8 },
-];
-
-interface Announcement {
-  id: string;
-  tag: "update" | "notice" | "activity";
-  tagLabel: string;
-  title: string;
-  date: string;
-}
-
-const announcements: Announcement[] = [
-  {
-    id: "a-1",
-    tag: "update",
-    tagLabel: "更新",
-    title: "系统已升级至 v2.0，新增批量生成功能",
-    date: "2026-07-01",
-  },
-  {
-    id: "a-2",
-    tag: "activity",
-    tagLabel: "活动",
-    title: "7月创作挑战赛已开启，参与赢积分奖励",
-    date: "2026-06-28",
-  },
-  {
-    id: "a-3",
-    tag: "notice",
-    tagLabel: "公告",
-    title: "7月3日凌晨 2:00-4:00 系统维护通知",
-    date: "2026-06-25",
-  },
-];
-
-/* ============================================================
- * 工具函数
- * ============================================================ */
-const getGreeting = () => {
-  const hour = new Date().getHours();
-  if (hour < 6) return "夜深了";
-  if (hour < 12) return "早上好";
-  if (hour < 14) return "中午好";
-  if (hour < 18) return "下午好";
-  return "晚上好";
-};
-
-const formatDate = () => {
-  const d = new Date();
-  const weekDays = ["日", "一", "二", "三", "四", "五", "六"];
-  return `${d.getFullYear()}年${d.getMonth() + 1}月${d.getDate()}日 星期${weekDays[d.getDay()]}`;
-};
-
-/** 图标名称 → Ant Design 组件映射 */
-const iconMap: Record<string, React.ReactNode> = {
-  video: <VideoCameraOutlined />,
-  appstore: <AppstoreOutlined />,
-  thunderbolt: <ThunderboltOutlined />,
-  database: <DatabaseOutlined />,
-  filetext: <FileTextOutlined />,
-};
-
-/* ============================================================
- * 组件
- * ============================================================ */
 const Dashboard: React.FC = () => {
   const navigate = useNavigate();
 
-  const maxChart = Math.max(...weeklyData.map((d) => d.value));
-
   return (
     <div className="xx-dashboard-page">
-      {/* ── 欢迎头部 ─────────────────────────────────────────── */}
-      <div className="xx-dashboard-welcome">
-        <h2>{getGreeting()}，创作者</h2>
-        <p>{formatDate()} — 欢迎回到小小剪辑控制台</p>
-      </div>
-
-      {/* ── KPI 卡片网格 ─────────────────────────────────────── */}
+      {/* KPI 卡片网格 */}
       <div className="xx-kpi-grid">
-        {kpiData.map((item) => (
-          <div
-            key={item.key}
-            className="xx-kpi-card"
-            style={{ "--kpi-accent": item.accent } as React.CSSProperties}
-          >
-            <div
-              className="xx-kpi-icon"
-              style={{ background: item.iconGradient }}
-            >
-              {iconMap[item.icon] ?? item.icon}
-            </div>
-            <div className="xx-kpi-value">{item.value}</div>
-            <div className="xx-kpi-label">{item.label}</div>
-            <span
-              className={`xx-kpi-trend xx-kpi-trend--${item.trendDirection}`}
-            >
-              {item.trend}
-            </span>
-          </div>
-        ))}
-      </div>
-
-      {/* ── 主内容区：左侧任务+图表 / 右侧公告 ──────────────── */}
-      <div className="xx-dashboard-main">
-        {/* 左列 */}
-        <div className="xx-dashboard-left-col">
-          {/* 最近任务 */}
-          <div className="xx-dashboard-section">
-            <div className="xx-dashboard-section-header">
-              <h3>最近任务</h3>
-              <button onClick={() => navigate("/app/history")}>查看全部</button>
-            </div>
-            <div className="xx-task-list">
-              {recentTasks.map((task) => (
-                <div key={task.id} className="xx-task-item">
-                  <div className="xx-task-info">
-                    <h4>{task.name}</h4>
-                    <span>
-                      {task.type} · 模板：{task.template}
-                    </span>
-                  </div>
-                  <Tag
-                    variant={
-                      task.status === "completed"
-                        ? "success"
-                        : task.status === "processing"
-                          ? "info"
-                          : task.status === "failed"
-                            ? "error"
-                            : "warning"
-                    }
-                  >
-                    {statusLabel[task.status]}
-                  </Tag>
-                  <div className="xx-task-time">
-                    <span>{task.date}</span>
-                    {task.status === "completed"
-                      ? `耗时 ${task.duration}`
-                      : task.status === "processing"
-                        ? "生成中..."
-                        : task.status === "failed"
-                          ? "请重试"
-                          : "等待中"}
-                  </div>
-                  <div className="xx-task-action">
-                    <Button
-                      buttonType="ghost"
-                      buttonSize="sm"
-                      onClick={() => navigate("/app/history")}
-                    >
-                      查看
-                    </Button>
-                  </div>
-                </div>
-              ))}
-            </div>
-          </div>
-
-          {/* 使用统计图表 */}
-          <div className="xx-dashboard-section">
-            <div className="xx-dashboard-section-header">
-              <h3>本周生成趋势</h3>
-              <span className="xx-chart-total">
-                共 {weeklyData.reduce((s, d) => s + d.value, 0)} 次
-              </span>
-            </div>
-            <div className="xx-chart-container">
-              <div className="xx-chart-bars">
-                {weeklyData.map((d, i) => (
-                  <div key={i} className="xx-chart-bar-wrapper">
-                    <div
-                      className="xx-chart-bar"
-                      style={{
-                        height: `${(d.value / maxChart) * 100}%`,
-                      }}
-                    >
-                      <span className="xx-chart-bar-value">{d.value}</span>
-                    </div>
-                  </div>
-                ))}
-              </div>
-              <div className="xx-chart-labels">
-                {weeklyData.map((d, i) => (
-                  <div key={i} className="xx-chart-label">
-                    {d.label}
-                  </div>
-                ))}
-              </div>
-            </div>
-          </div>
-        </div>
-
-        {/* 右列 — 公告 + 存储用量 */}
-        <div className="xx-dashboard-section xx-dashboard-section--start">
-          <div className="xx-dashboard-section-header">
-            <h3>系统公告</h3>
-          </div>
-          <div className="xx-announcement-list">
-            {announcements.map((a) => (
-              <div key={a.id} className="xx-announcement-item">
-                <span
-                  className={`xx-announcement-tag xx-announcement-tag--${a.tag}`}
-                >
-                  {a.tagLabel}
-                </span>
-                <div className="xx-announcement-content">
-                  <h4>{a.title}</h4>
-                  <time>{a.date}</time>
-                </div>
-              </div>
-            ))}
-          </div>
-
-          {/* 存储用量 */}
-          <div className="xx-storage-section">
-            <div className="xx-storage-section-title">存储用量</div>
-            <div className="xx-storage-bar">
-              <div className="xx-storage-bar-track">
-                <div className="xx-storage-bar-fill" style={{ width: "24%" }} />
-              </div>
-              <div className="xx-storage-bar-label">
-                <span>2.4 GB 已用</span>
-                <span>10 GB 总量</span>
-              </div>
-            </div>
-          </div>
+        <div className="xx-dashboard-empty">
+          <p>暂无统计数据</p>
         </div>
       </div>
 
-      {/* ── 快速入口 ─────────────────────────────────────────── */}
+      {/* 快速入口 */}
       <div className="xx-quick-entry-section">
         <div className="xx-quick-entry-header">
           <h3 className="xx-quick-entry-title">快速入口</h3>
         </div>
         <div className="xx-quick-grid">
-          {quickEntries.map((entry) => (
-            <div
-              key={entry.id}
-              className="xx-quick-card"
-              onClick={() => navigate(entry.path)}
-            >
-              <div
-                className="xx-quick-card-icon"
-                style={{ background: entry.iconGradient }}
-              >
-                {iconMap[entry.icon] ?? entry.icon}
-              </div>
-              <h3>{entry.title}</h3>
-              <p>{entry.description}</p>
-            </div>
-          ))}
+          <div className="xx-dashboard-empty">
+            <p>暂无快速入口</p>
+          </div>
         </div>
       </div>
+
+      {/* 最近任务 */}
+      <section className="xx-dashboard-section">
+        <div className="xx-dashboard-section-header">
+          <h3>最近任务</h3>
+          <Button
+            buttonType="ghost"
+            buttonSize="sm"
+            onClick={() => navigate("/app/history")}
+          >
+            查看全部
+          </Button>
+        </div>
+        <div className="xx-task-list">
+          <div className="xx-dashboard-empty">
+            <p>暂无最近任务</p>
+          </div>
+        </div>
+      </section>
+
+      {/* 使用统计 */}
+      <section
+        className="xx-dashboard-section"
+        style={{ marginTop: "var(--space-md)" }}
+      >
+        <div className="xx-dashboard-section-header">
+          <h3>使用统计</h3>
+        </div>
+        <div className="xx-chart-container">
+          <div className="xx-chart-bars">
+            <div className="xx-dashboard-empty" style={{ width: "100%" }}>
+              <DatabaseOutlined style={{ fontSize: 24, marginBottom: 8 }} />
+              <p>暂无统计数据</p>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      {/* 公告 */}
+      <section
+        className="xx-dashboard-section"
+        style={{ marginTop: "var(--space-md)" }}
+      >
+        <div className="xx-dashboard-section-header">
+          <h3>公告</h3>
+        </div>
+        <div className="xx-announcement-list">
+          <div className="xx-announcement-item">
+            <span className="xx-announcement-tag xx-announcement-tag--notice">
+              官方
+            </span>
+            <div className="xx-announcement-content">
+              <h4>欢迎使用小应 SaaS 平台</h4>
+              <time>当前为演示版本，部分功能正在开发中。</time>
+            </div>
+          </div>
+        </div>
+      </section>
     </div>
   );
 };

apps/web/src/pages/dashboard/dashboard.css

@@ -1,6 +1,6 @@
 /**
  * 控制台页面 - V21 设计系统样式
- * KPI 卡片网格 + 快速入口 + 最近任务卡片列表 + 使用统计图表 + 公告
+ * KPI 卡片网格 + 快速入口 + 最近任务 + 使用统计图表 + 公告
  * 统一使用 CSS 变量，支持深色/浅色主题
  */
 @import "../../styles/global.css";
@@ -13,26 +13,6 @@
   padding: var(--space-xl);
 }
 
-/* ============================================================
-   欢迎头部
-   ============================================================ */
-.xx-dashboard-welcome {
-  margin-bottom: var(--space-lg);
-}
-
-.xx-dashboard-welcome h2 {
-  margin: 0 0 var(--space-xs);
-  font-size: var(--font-size-xl);
-  font-weight: var(--font-weight-bold);
-  color: var(--text-primary);
-}
-
-.xx-dashboard-welcome p {
-  margin: 0;
-  font-size: var(--font-size-sm);
-  color: var(--text-secondary);
-}
-
 /* ============================================================
    KPI 卡片网格
    ============================================================ */
@@ -43,76 +23,6 @@
   margin-bottom: var(--space-lg);
 }
 
-.xx-kpi-card {
-  background: linear-gradient(180deg, var(--bg-primary), var(--bg-secondary));
-  border: 1px solid var(--border-color);
-  border-radius: var(--radius-lg);
-  padding: 20px;
-  transition: 0.18s ease;
-  position: relative;
-  overflow: hidden;
-}
-
-.xx-kpi-card:hover {
-  transform: translateY(-2px);
-  box-shadow: var(--shadow-sm);
-}
-
-.xx-kpi-icon {
-  width: 40px;
-  height: 40px;
-  border-radius: var(--radius-md);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-size: var(--font-size-lg);
-  margin-bottom: var(--space-sm);
-}
-
-.xx-kpi-value {
-  font-size: 30px;
-  font-weight: 800;
-  color: var(--text-primary);
-  line-height: 1.2;
-  margin-bottom: var(--space-xs);
-}
-
-.xx-kpi-label {
-  font-size: var(--font-size-sm);
-  color: var(--text-secondary);
-  margin-bottom: var(--space-sm);
-}
-
-.xx-kpi-trend {
-  font-size: 12px;
-  margin-top: 8px;
-  display: inline-flex;
-  align-items: center;
-  gap: 4px;
-}
-
-.xx-kpi-trend--up {
-  color: var(--success-color);
-}
-
-.xx-kpi-trend--down {
-  color: var(--error-color);
-}
-
-.xx-kpi-trend--neutral {
-  color: var(--text-tertiary);
-}
-
-/* ============================================================
-   主内容区两栏布局
-   ============================================================ */
-.xx-dashboard-main {
-  display: grid;
-  grid-template-columns: 1fr 320px;
-  gap: var(--space-md);
-  margin-bottom: var(--space-lg);
-}
-
 /* ============================================================
    区块卡片
    ============================================================ */
@@ -161,7 +71,25 @@
 }
 
 /* ============================================================
-   最近任务卡片列表
+   空状态
+   ============================================================ */
+.xx-dashboard-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: var(--space-xl) var(--space-md);
+  text-align: center;
+  color: var(--text-tertiary);
+}
+
+.xx-dashboard-empty p {
+  margin: 0;
+  font-size: var(--font-size-sm);
+}
+
+/* ============================================================
+   最近任务列表
    ============================================================ */
 .xx-task-list {
   display: flex;
@@ -169,86 +97,6 @@
   gap: var(--space-sm);
 }
 
-.xx-task-item {
-  background: var(--bg-primary);
-  border: 1px solid var(--border-color);
-  border-radius: var(--radius-md);
-  padding: var(--space-sm) var(--space-md);
-  display: grid;
-  grid-template-columns: 1fr auto auto auto;
-  gap: var(--space-md);
-  align-items: center;
-  transition: var(--transition-all);
-}
-
-.xx-task-item:hover {
-  border-color: var(--primary-color);
-  box-shadow: var(--shadow-sm);
-}
-
-.xx-task-info h4 {
-  margin: 0 0 var(--space-xs);
-  font-size: var(--font-size-sm);
-  font-weight: 600;
-  color: var(--text-primary);
-}
-
-.xx-task-info span {
-  font-size: var(--font-size-xs);
-  color: var(--text-secondary);
-}
-
-.xx-task-status {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--space-xs);
-  padding: 3px 10px;
-  border-radius: var(--radius-sm);
-  font-size: var(--font-size-xs);
-  font-weight: 500;
-  white-space: nowrap;
-}
-
-.xx-task-status--completed {
-  color: var(--success-color);
-  background: var(--success-soft);
-  border: 1px solid var(--success-border);
-}
-
-.xx-task-status--processing {
-  color: var(--info-color);
-  background: var(--primary-soft);
-  border: 1px solid var(--color-primary-200);
-}
-
-.xx-task-status--pending {
-  color: var(--text-secondary);
-  background: var(--bg-secondary);
-  border: 1px solid var(--border-color);
-}
-
-.xx-task-status--failed {
-  color: var(--error-color);
-  background: var(--error-soft);
-  border: 1px solid var(--error-border);
-}
-
-.xx-task-time {
-  text-align: right;
-  font-size: var(--font-size-xs);
-  color: var(--text-secondary);
-  min-width: 100px;
-}
-
-.xx-task-time span {
-  display: block;
-  margin-bottom: var(--space-xxs);
-}
-
-.xx-task-action {
-  font-size: var(--font-size-xs);
-}
-
 /* ============================================================
    使用统计图表（纯 CSS 柱状图）
    ============================================================ */
@@ -264,69 +112,27 @@
   padding-top: var(--space-sm);
 }
 
-.xx-chart-bar-wrapper {
-  flex: 1;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  height: 100%;
-  justify-content: flex-end;
-}
-
-.xx-chart-bar {
-  width: 100%;
-  max-width: 36px;
-  border-radius: var(--radius-sm) var(--radius-sm) 0 0;
-  background: var(--gradient-primary);
-  transition: height 0.6s cubic-bezier(0.34, 1.56, 0.64, 1);
-  position: relative;
-  min-height: 4px;
-  cursor: pointer;
-}
-
-.xx-chart-bar:hover {
-  opacity: 0.85;
-}
-
-.xx-chart-bar:active {
-  opacity: 0.7;
-  transform: scaleY(0.97);
-  transform-origin: bottom;
-}
-
-.xx-chart-bar-value {
-  position: absolute;
-  top: -20px;
-  left: 50%;
-  transform: translateX(-50%);
-  font-size: var(--font-size-xs);
-  font-weight: 600;
-  color: var(--text-primary);
-  white-space: nowrap;
-  opacity: 0;
-  transition: var(--transition-opacity);
-}
-
-.xx-chart-bar:hover .xx-chart-bar-value {
-  opacity: 1;
-}
-
-.xx-chart-labels {
-  display: flex;
-  gap: var(--space-sm);
-  margin-top: var(--space-sm);
-}
-
-.xx-chart-label {
-  flex: 1;
-  text-align: center;
-  font-size: var(--font-size-xs);
-  color: var(--text-secondary);
-}
-
 /* ============================================================
-   快速入口卡片网格
+   快速入口
    ============================================================ */
+.xx-quick-entry-section {
+  margin-bottom: var(--space-md);
+}
+
+.xx-quick-entry-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: var(--space-md);
+}
+
+.xx-quick-entry-title {
+  margin: 0;
+  font-size: var(--font-size-base);
+  font-weight: var(--font-weight-semibold);
+  color: var(--text-primary);
+}
+
 .xx-quick-grid {
   display: grid;
   grid-template-columns: repeat(4, 1fr);
@@ -334,53 +140,6 @@
   margin-bottom: var(--space-lg);
 }
 
-.xx-quick-card {
-  background: var(--bg-primary);
-  border: 1px solid var(--border-color);
-  border-radius: var(--radius-lg);
-  padding: var(--space-lg);
-  cursor: pointer;
-  transition: var(--transition-all);
-  text-align: center;
-}
-
-.xx-quick-card:hover {
-  border-color: var(--primary-color);
-  box-shadow: var(--shadow-md);
-  transform: translateY(-2px);
-}
-
-.xx-quick-card:active {
-  transform: translateY(0) scale(0.98);
-  box-shadow: var(--shadow-sm);
-  transition-duration: 0.1s;
-}
-
-.xx-quick-card-icon {
-  width: 52px;
-  height: 52px;
-  border-radius: var(--radius-md);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-size: var(--font-size-xl);
-  margin: 0 auto var(--space-md);
-  color: var(--text-inverse);
-}
-
-.xx-quick-card h3 {
-  margin: 0 0 var(--space-sm);
-  font-size: var(--font-size-md);
-  font-weight: var(--font-weight-semibold);
-  color: var(--text-primary);
-}
-
-.xx-quick-card p {
-  margin: 0;
-  color: var(--text-secondary);
-  font-size: var(--font-size-sm);
-}
-
 /* ============================================================
    公告区域
    ============================================================ */
@@ -451,90 +210,10 @@
   color: var(--text-secondary);
 }
 
-/* ============================================================
-   存储用量条
-   ============================================================ */
-.xx-storage-bar {
-  margin-top: var(--space-sm);
-}
-
-.xx-storage-bar-track {
-  height: var(--space-sm);
-  background: var(--bg-secondary);
-  border-radius: var(--space-xs);
-  overflow: hidden;
-}
-
-.xx-storage-bar-fill {
-  height: 100%;
-  border-radius: var(--space-xs);
-  background: var(--gradient-primary);
-  transition: width 0.6s ease;
-}
-
-.xx-storage-bar-label {
-  display: flex;
-  justify-content: space-between;
-  font-size: var(--font-size-xs);
-  color: var(--text-secondary);
-  margin-top: var(--space-xs);
-}
-
-/* ============================================================
-   迁移自内联样式的工具类
-   ============================================================ */
-.xx-dashboard-left-col {
-  display: flex;
-  flex-direction: column;
-  gap: var(--space-md);
-}
-
-.xx-chart-total {
-  font-size: var(--font-size-xs);
-  color: var(--text-secondary);
-}
-
-.xx-dashboard-section--start {
-  align-self: start;
-}
-
-.xx-storage-section {
-  margin-top: var(--space-md);
-}
-
-.xx-storage-section-title {
-  font-size: 13px;
-  font-weight: 500;
-  color: var(--text-primary);
-  margin-bottom: 4px;
-}
-
-.xx-quick-entry-section {
-  margin-bottom: var(--space-md);
-}
-
-.xx-quick-entry-header {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  margin-bottom: var(--space-md);
-}
-
-.xx-quick-entry-title {
-  margin: 0;
-  font-size: var(--font-size-base);
-  font-weight: var(--font-weight-semibold);
-  color: var(--text-primary);
-}
-
 /* ============================================================
    响应式
    ============================================================ */
 @media (max-width: 1200px) {
-  .xx-dashboard-main {
-    grid-template-columns: 1fr;
-  }
-
   .xx-kpi-grid {
     grid-template-columns: repeat(2, 1fr);
   }
@@ -557,15 +236,6 @@
     grid-template-columns: 1fr;
   }
 
-  .xx-task-item {
-    grid-template-columns: 1fr;
-    gap: var(--space-sm);
-  }
-
-  .xx-task-time {
-    text-align: left;
-  }
-
   .xx-chart-bars {
     height: 120px;
   }

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

@@ -69,22 +69,6 @@ const VOICE_GENDER_ICON: Record<string, string> = {
   neutral: "✨",
 };
 
-/* ── 时间线 Mock ──
- * TODO: 后端暂无时间线场景数据 API，当前使用硬编码预览数据。
- *       待后端提供 timeline/scene 接口后替换为真实 API 调用。
- */
-interface TimelineScene {
-  scene: string;
-  time: string;
-  duration: number;
-}
-
-const MOCK_TIMELINE: TimelineScene[] = [
-  { scene: "主讲口播 · 开场钩子", time: "0-8s", duration: 8 },
-  { scene: "产品特写 · B-roll", time: "8-20s", duration: 12 },
-  { scene: "用户反馈 · 结尾", time: "20-30s", duration: 10 },
-];
-
 /* ── 步骤定义 ── */
 const STEPS = [
   { key: 1, label: "选择模板" },
@@ -1758,15 +1742,19 @@ const GeneratePage: React.FC = () => {
           <div className="xx-preview-title">剪辑计划预览</div>
 
           {/* 时间线列表 */}
-          <div className="xx-preview-timeline">
-            {MOCK_TIMELINE.map((item, idx) => (
-              <div key={idx} className="xx-timeline-item">
-                <div className="num">{idx + 1}</div>
-                <span className="scene-name">{item.scene}</span>
-                <span>{item.time}</span>
+          {generated ? (
+            <div className="xx-preview-timeline">
+              <div className="xx-timeline-item">
+                <span className="scene-name">生成完成，可下载或分享视频</span>
               </div>
-            ))}
-          </div>
+            </div>
+          ) : (
+            <div className="xx-preview-timeline">
+              <div className="xx-timeline-item">
+                <span className="scene-name">确认标题后自动生成剪辑计划</span>
+              </div>
+            </div>
+          )}
 
           {/* 生成操作按钮 */}
           <div className="xx-generate-actions">

apps/web/src/pages/titles/TitleLibrary.tsx

@@ -36,36 +36,24 @@ type TitleType = "hot" | "normal" | "creative";
 type Industry = "general" | "food" | "tech" | "beauty" | "education" | "travel";
 type Frequency = "all" | "high" | "medium" | "low";
 
-interface CategoryItem {
-  id: string;
-  name: string;
-  count: number;
-}
-
 interface TitleData {
   id: string;
   content: string;
   type: TitleType;
   industry: Industry;
+  category: string;
   usageCount: number;
   isFavorited: boolean;
   createdAt: string;
 }
 
-/* ============================================================
- * Mock 数据
- * ============================================================ */
-// TODO: 分类数据当前为前端硬编码 mock，待后端提供标题分类 API 后替换
-const MOCK_CATEGORIES: CategoryItem[] = [
-  { id: "cat-all", name: "全部标题", count: 0 },
-];
-
 /** 后端 TitleItem → 前端 TitleData 映射 */
 const toTitleData = (item: TitleItem): TitleData => ({
   id: item.id,
   content: item.content,
   type: (item.category as TitleType) || "normal",
   industry: "general",
+  category: item.category || "未分类",
   usageCount: 0,
   isFavorited: false,
   createdAt: item.created_at?.slice(0, 10) || "",
@@ -246,9 +234,8 @@ const TitleCard: React.FC<{
 const TitleLibrary: React.FC = () => {
   const queryClient = useQueryClient();
 
-  /* 分类数据 */
-  const [categories, setCategories] = useState<CategoryItem[]>(MOCK_CATEGORIES);
-  const [activeCatId, setActiveCatId] = useState<string>(MOCK_CATEGORIES[0].id);
+  /* 分类数据 — 从真实标题数据动态派生 */
+  const [activeCatId, setActiveCatId] = useState<string>("cat-all");
 
   /* 标题数据 — 真实 API */
   const { data: apiTitles = [] } = useQuery({
@@ -261,6 +248,23 @@ const TitleLibrary: React.FC = () => {
     [apiTitles],
   );
 
+  /* 从真实标题数据动态派生分类（无需后端分类 API） */
+  const categories = useMemo(() => {
+    const cats = new Map<string, number>();
+    apiTitles.forEach((t) => {
+      const cat = t.category || "未分类";
+      cats.set(cat, (cats.get(cat) || 0) + 1);
+    });
+    return [
+      { id: "cat-all", name: "全部标题", count: apiTitles.length },
+      ...Array.from(cats.entries()).map(([name, count]) => ({
+        id: `cat-${name}`,
+        name,
+        count,
+      })),
+    ];
+  }, [apiTitles]);
+
   /* CRUD mutations */
   const createMutation = useMutation({
     mutationFn: (content: string) => createTitle({ content }),
@@ -297,10 +301,6 @@ const TitleLibrary: React.FC = () => {
   const [editingId, setEditingId] = useState<string | null>(null);
   const [editText, setEditText] = useState("");
 
-  /* 新建分类 */
-  const [createCatModalOpen, setCreateCatModalOpen] = useState(false);
-  const [newCatName, setNewCatName] = useState("");
-
   /* 新建标题 */
   const [createTitleModalOpen, setCreateTitleModalOpen] = useState(false);
   const [newTitleContent, setNewTitleContent] = useState("");
@@ -318,19 +318,11 @@ const TitleLibrary: React.FC = () => {
   const filteredTitles = useMemo(() => {
     let list = titles;
 
-    /* 按分类过滤（"全部标题" 不过滤） */
+    /* 按分类过滤（"全部标题" 不过滤）— 直接匹配后端 category 字段 */
     if (activeCatId !== "cat-all") {
       const catName = activeCategory?.name || "";
-      const catToIndustry: Record<string, Industry> = {
-        美食探店: "food",
-        科技数码: "tech",
-        生活日常: "general",
-        美妆穿搭: "beauty",
-        教育学习: "education",
-      };
-      const mappedIndustry = catToIndustry[catName];
-      if (mappedIndustry) {
-        list = list.filter((t) => t.industry === mappedIndustry);
+      if (catName) {
+        list = list.filter((t) => t.category === catName);
       }
     }
 
@@ -424,33 +416,6 @@ const TitleLibrary: React.FC = () => {
     [deleteMutation],
   );
 
-  /* 新建分类 */
-  const handleCreateCategory = () => {
-    if (!newCatName.trim()) {
-      message.warning("请输入分类名称");
-      return;
-    }
-    const cat: CategoryItem = {
-      id: `cat-${Date.now()}`,
-      name: newCatName.trim(),
-      count: 0,
-    };
-    setCategories((prev) => [...prev, cat]);
-    setActiveCatId(cat.id);
-    setCreateCatModalOpen(false);
-    setNewCatName("");
-    message.success(`分类 "${cat.name}" 创建成功`);
-  };
-
-  /* 删除分类 */
-  const handleDeleteCategory = (id: string) => {
-    setCategories((prev) => prev.filter((c) => c.id !== id));
-    if (activeCatId === id) {
-      setActiveCatId("cat-all");
-    }
-    message.success("分类已删除");
-  };
-
   /* 新建标题 */
   const handleCreateTitle = () => {
     if (!newTitleContent.trim()) {
@@ -537,38 +502,11 @@ const TitleLibrary: React.FC = () => {
                   </h4>
                   <span>{cat.count} 条</span>
                 </div>
-                {cat.id !== "cat-all" && (
-                  <Popconfirm
-                    title={`确定删除分类 "${cat.name}"？`}
-                    onConfirm={(e) => {
-                      e?.stopPropagation();
-                      handleDeleteCategory(cat.id);
-                    }}
-                    onCancel={(e) => e?.stopPropagation()}
-                    okText="删除"
-                    cancelText="取消"
-                  >
-                    <button
-                      className="xx-title-category-delete"
-                      onClick={(e) => e.stopPropagation()}
-                      title="删除分类"
-                    >
-                      <DeleteOutlined />
-                    </button>
-                  </Popconfirm>
-                )}
               </div>
             </div>
           ))}
 
-          {/* 新建分类 */}
-          <div
-            className="xx-title-category-add"
-            onClick={() => setCreateCatModalOpen(true)}
-          >
-            <PlusOutlined />
-            新建分类
-          </div>
+          {/* TODO: 新建分类功能待后端分类 API 就绪后启用 */}
         </div>
 
         {/* ─── 右侧：内容区 ─── */}
@@ -674,35 +612,6 @@ const TitleLibrary: React.FC = () => {
         </div>
       </div>
 
-      {/* ─── 新建分类弹窗 ─── */}
-      <AntModal
-        title="新建分类"
-        open={createCatModalOpen}
-        onCancel={() => setCreateCatModalOpen(false)}
-        onOk={handleCreateCategory}
-        okText="创建"
-        cancelText="取消"
-        destroyOnClose
-      >
-        <div style={{ padding: "8px 0" }}>
-          <div
-            style={{
-              marginBottom: 6,
-              fontSize: "var(--font-size-sm)",
-              color: "var(--text-secondary)",
-            }}
-          >
-            分类名称
-          </div>
-          <Input
-            placeholder="请输入分类名称"
-            value={newCatName}
-            onChange={(e) => setNewCatName(e.target.value)}
-            maxLength={30}
-          />
-        </div>
-      </AntModal>
-
       {/* ─── 新建标题弹窗 ─── */}
       <AntModal
         title="新建标题"

apps/worker/video_processing/dedup.py

@@ -1,10 +1,8 @@
 """Video deduplication module - compute fingerprints and detect duplicates."""
 
 import hashlib
-import json
 import logging
 import os
-import subprocess
 import tempfile
 from dataclasses import dataclass
 from typing import Optional
@@ -327,7 +325,6 @@ def check_duplicate_task(self: Task, generated_video_id: str) -> dict:
             raise ValueError(f"Generated video {generated_video_id} not found")
 
         local_path = os.path.join(temp_dir, f"{generated_video_id}.mp4")
-        storage_key = video.file_url.split("/")[-1]
         storage_service.download_file(
             f"projects/{video.project_id}/generated/{generated_video_id}/{generated_video_id}.mp4", local_path
         )

apps/worker/video_processing/ffmpeg_utils.py

@@ -81,7 +81,7 @@ def run_ffmpeg(
             timeout=timeout,
         )
         return (result.stdout or "", result.stderr or "")
-    except subprocess.TimeoutExpired as e:
+    except subprocess.TimeoutExpired:
         logger.error(
             "FFmpeg 命令超时 (%ds): command=%s",
             timeout or -1,

apps/worker/video_processing/oss_helpers.py

@@ -11,7 +11,6 @@ import logging
 import os
 import threading
 from pathlib import Path
-from typing import Optional
 from urllib.parse import urlparse
 
 import oss2

apps/worker/video_processing/processor.py

@@ -2,14 +2,16 @@
 视频处理核心类
 """
 
+import logging
 import os
 import tempfile
 from dataclasses import dataclass
-from pathlib import Path
 from typing import List
 
 import ffmpeg
 
+logger = logging.getLogger(__name__)
+
 
 @dataclass
 class VideoResult:
@@ -131,8 +133,8 @@ class VideoProcessor:
             if concat_file is not None:
                 try:
                     concat_file.close()
-                except Exception:
-                    pass  # 忽略关闭时的错误
+                except OSError as close_err:
+                    logger.warning("临时文件关闭失败: %s", close_err)
 
     def generate_thumbnail(
         self,

apps/worker/video_processing/render_adapter.py

@@ -17,15 +17,15 @@ import logging
 import tempfile
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Callable
+from typing import Callable
 
 from sqlalchemy.orm import Session
 from video_processing.oss_helpers import download_asset, upload_to_oss
-from video_processing.unified_render_service import RenderResult, UnifiedRenderService
+from video_processing.unified_render_service import UnifiedRenderService
 
 from packages.adapters.sqlalchemy_impl.edit_plan_clip_repository import SQLAlchemyEditPlanClipRepository
 from packages.adapters.sqlalchemy_impl.edit_plan_repository import SQLAlchemyEditPlanRepository
-from packages.domain.edit_plan import EditPlan, EditPlanStatus
+from packages.domain.edit_plan import EditPlanStatus
 from packages.domain.edit_plan_clip import EditPlanClip, EditPlanClipStatus
 
 logger = logging.getLogger(__name__)
@@ -210,8 +210,8 @@ class RenderAdapter:
 
                 try:
                     shutil.rmtree(temp_dir, ignore_errors=True)
-                except Exception:
-                    pass
+                except Exception as cleanup_err:
+                    logger.warning("临时目录清理失败: path=%s error=%s", temp_dir, cleanup_err)
 
     def validate_plan(self, plan_id: str) -> tuple[bool, list[str], list[str], int, int]:
         """校验计划是否可渲染（兼容 VideoComposeService.validate_compose 接口）。

apps/worker/video_processing/render_audio.py

@@ -0,0 +1,364 @@
+"""音频混音模块 — 从 unified_render_service.py 拆分.
+
+职责：
+- 主图层音频 concat 拼接
+- 独立音频轨 amix 混音
+- 音视频合并（mux）
+
+所有函数接收 RenderContext 获取共享依赖（work_dir、plan_id 等），
+避免直接依赖 UnifiedRenderService 类。
+"""
+
+from __future__ import annotations
+
+import logging
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# 延迟导入避免循环依赖：unified_render_service 定义 ResolvedClip / RenderLayer，
+# 本模块提供音频函数供 unified_render_service 调用。
+# 使用 from __future__ import annotations + TYPE_CHECKING 解决类型引用。
+from typing import TYPE_CHECKING
+
+from video_processing.ffmpeg_utils import FFMPEG_BIN, probe_has_audio, run_ffmpeg
+
+if TYPE_CHECKING:
+    from video_processing.unified_render_service import RenderLayer, ResolvedClip
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RenderContext:
+    """渲染上下文 — 提供音频混音所需的共享依赖."""
+
+    work_dir: Path
+    plan_id: str
+    # 音频探测缓存（避免同一 clip 被多次 ffprobe）
+    _audio_cache: dict[str, bool] = field(default_factory=dict)
+
+
+# ── 工具函数 ──────────────────────────────────────────────────────────────────
+
+
+def clip_effective_duration(clip: ResolvedClip) -> float:
+    """计算 clip 的有效时长.
+
+    与 UnifiedRenderService._clip_effective_duration 逻辑一致。
+    """
+    if clip.duration > 0:
+        return min(clip.duration, clip.actual_duration) if clip.actual_duration > 0 else clip.duration
+    return clip.actual_duration if clip.actual_duration > 0 else 0.0
+
+
+def clip_has_audio(ctx: RenderContext, clip: ResolvedClip) -> bool:
+    """探测 clip 是否有音频流（带缓存）.
+
+    避免同一个 clip 被多次 ffprobe 探测。
+    """
+    key = str(clip.local_path)
+    if key not in ctx._audio_cache:
+        ctx._audio_cache[key] = probe_has_audio(clip.local_path)
+    return ctx._audio_cache[key]
+
+
+# ── 音频混音 ──────────────────────────────────────────────────────────────────
+
+
+def mix_audio(
+    ctx: RenderContext,
+    layers: list[RenderLayer],
+    video_duration: float,
+) -> Path | None:
+    """音频后处理混音.
+
+    处理逻辑：
+    1. 主音频源按优先级查找：main > broll（background 不参与主音频，通常是图片无音轨）
+    2. 主图层音频按顺序 concat 拼接
+    3. 独立音频轨（audio role）用 amix 混入
+    4. 输出时长截断到 video_duration
+    5. 无音频流的 clip 会被自动跳过，避免 FFmpeg 引用 [i:a] 失败
+
+    Args:
+        ctx: 渲染上下文
+        layers: 图层列表
+        video_duration: 视频总时长（用于截断音频）
+
+    Returns:
+        混音后的音频文件路径，无音频时返回 None
+    """
+    # 按优先级精确查找主音频图层：main > broll
+    # background 不参与主音频（通常是静态图片，无音轨）
+    layer_map = {layer.role: layer for layer in layers}
+    main_layer = None
+    for role in ("main", "broll"):
+        if role in layer_map and layer_map[role].clips:
+            main_layer = layer_map[role]
+            break
+
+    main_clips: list[ResolvedClip] = main_layer.clips if main_layer else []
+
+    # 没有主视频图层时兜底：检查 overlay/corner_voice 层是否有带音频的素材
+    if not main_clips:
+        for role in ("overlay", "corner_voice"):
+            if role in layer_map and layer_map[role].clips:
+                main_clips = layer_map[role].clips
+                break
+
+    # 收集独立音频轨
+    audio_clips: list[ResolvedClip] = []
+    if "audio" in layer_map:
+        audio_clips = layer_map["audio"].clips
+
+    # ── 防御：过滤掉无音频流的 clip ──
+    main_clips = [c for c in main_clips if clip_has_audio(ctx, c)]
+    audio_clips = [c for c in audio_clips if clip_has_audio(ctx, c)]
+
+    if not main_clips and not audio_clips:
+        return None
+
+    # 构建音频处理命令
+    output_path = ctx.work_dir / f"audio_{ctx.plan_id}.aac"
+
+    # 简单场景：只有主图层 + 无独立音频 → 直接从视频提取音频并拼接
+    if main_clips and not audio_clips:
+        concat_main_audio(ctx, main_clips, output_path, video_duration)
+        return output_path
+
+    # 有独立音频轨 → amix 混音
+    mix_with_independent_audio(ctx, main_clips, audio_clips, output_path, video_duration)
+    return output_path
+
+
+def concat_main_audio(
+    ctx: RenderContext,
+    clips: list[ResolvedClip],
+    output_path: Path,
+    video_duration: float,
+) -> None:
+    """主图层音频 concat 拼接（对齐链路A行为）.
+
+    每个 clip 提取音频 → trim → 按顺序 concat。
+    """
+    if len(clips) == 1:
+        # 单 clip，直接提取音频，截断到 min(clip有效时长, 视频总时长)
+        clip = clips[0]
+        effective_duration = clip_effective_duration(clip)
+        # 最终时长：取 clip 有效时长和视频总时长的较小值
+        # （视频总时长由主图层决定，但单 clip 场景下两者应该一致，仍做保护）
+        final_duration = effective_duration
+        if video_duration > 0 and (final_duration <= 0 or final_duration > video_duration):
+            final_duration = video_duration
+
+        command = [
+            FFMPEG_BIN,
+            "-y",
+            "-i",
+            str(clip.local_path),
+            "-vn",
+            "-acodec",
+            "aac",
+            "-b:a",
+            "128k",
+        ]
+        if final_duration > 0:
+            command.extend(["-t", f"{final_duration:.3f}"])
+        command.append(str(output_path))
+        run_ffmpeg(command)
+        return
+
+    # 多 clip，用 filter_complex concat
+    input_args: list[str] = []
+    filter_parts: list[str] = []
+
+    for i, clip in enumerate(clips):
+        input_args.extend(["-i", str(clip.local_path)])
+        effective_duration = clip_effective_duration(clip)
+        if effective_duration > 0:
+            filter_parts.append(f"[{i}:a]atrim=0:{effective_duration:.3f},asetpts=PTS-STARTPTS[a{i}]")
+        else:
+            filter_parts.append(f"[{i}:a]asetpts=PTS-STARTPTS[a{i}]")
+
+    audio_labels = "".join(f"[a{i}]" for i in range(len(clips)))
+    filter_parts.append(f"{audio_labels}concat=n={len(clips)}:v=0:a=1[outa]")
+
+    # 截断到视频总时长
+    if video_duration > 0:
+        filter_parts.append(f"[outa]atrim=0:{video_duration:.3f}[final_audio]")
+        final_label = "final_audio"
+    else:
+        final_label = "outa"
+
+    filter_complex = ";".join(filter_parts)
+
+    command = [
+        FFMPEG_BIN,
+        "-y",
+        *input_args,
+        "-filter_complex",
+        filter_complex,
+        "-map",
+        f"[{final_label}]",
+        "-acodec",
+        "aac",
+        "-b:a",
+        "128k",
+        str(output_path),
+    ]
+    run_ffmpeg(command)
+
+
+def mix_with_independent_audio(
+    ctx: RenderContext,
+    main_clips: list[ResolvedClip],
+    audio_clips: list[ResolvedClip],
+    output_path: Path,
+    video_duration: float,
+) -> None:
+    """主音频 + 独立音频轨 amix 混音.
+
+    Args:
+        ctx: 渲染上下文
+        main_clips: 主视频 clips（提取音频后 concat）
+        audio_clips: 独立音频轨 clips
+        output_path: 输出路径
+        video_duration: 视频总时长
+    """
+    input_args: list[str] = []
+    filter_parts: list[str] = []
+    mix_labels: list[str] = []
+
+    input_idx = 0
+
+    # 1. 主图层音频 concat
+    if main_clips:
+        for clip in main_clips:
+            input_args.extend(["-i", str(clip.local_path)])
+            effective_duration = clip_effective_duration(clip)
+            if effective_duration > 0:
+                filter_parts.append(
+                    f"[{input_idx}:a]atrim=0:{effective_duration:.3f},asetpts=PTS-STARTPTS[ma{input_idx}]"
+                )
+            else:
+                filter_parts.append(f"[{input_idx}:a]asetpts=PTS-STARTPTS[ma{input_idx}]")
+            input_idx += 1
+
+        if len(main_clips) == 1:
+            mix_labels.append("ma0")
+        else:
+            main_labels = "".join(f"[ma{i}]" for i in range(len(main_clips)))
+            filter_parts.append(f"{main_labels}concat=n={len(main_clips)}:v=0:a=1[main_audio]")
+            mix_labels.append("main_audio")
+
+    # 2. 独立音频轨
+    for j, clip in enumerate(audio_clips):
+        input_args.extend(["-i", str(clip.local_path)])
+        effective_duration = clip_effective_duration(clip)
+        volume = clip.config.get("volume", 1.0) if clip.config else 1.0
+        label = f"ia{j}"
+        filters = []
+        if effective_duration > 0:
+            filters.append(f"atrim=0:{effective_duration:.3f}")
+        filters.append("asetpts=PTS-STARTPTS")
+        if volume != 1.0:
+            filters.append(f"volume={volume}")
+        filter_parts.append(f"[{input_idx}:a]{','.join(filters)}[{label}]")
+        mix_labels.append(label)
+        input_idx += 1
+
+    # 3. amix 混音
+    mix_inputs = "".join(f"[{label}]" for label in mix_labels)
+    n_inputs = len(mix_labels)
+    # normalized=0 保持音量，duration=shortest 取最短
+    filter_parts.append(f"{mix_inputs}amix=inputs={n_inputs}:duration=longest:normalize=0[mixed_audio]")
+
+    # 4. 截断到视频时长
+    if video_duration > 0:
+        filter_parts.append(f"[mixed_audio]atrim=0:{video_duration:.3f}[final_audio]")
+        final_label = "final_audio"
+    else:
+        final_label = "mixed_audio"
+
+    filter_complex = ";".join(filter_parts)
+
+    command = [
+        FFMPEG_BIN,
+        "-y",
+        *input_args,
+        "-filter_complex",
+        filter_complex,
+        "-map",
+        f"[{final_label}]",
+        "-acodec",
+        "aac",
+        "-b:a",
+        "128k",
+        str(output_path),
+    ]
+
+    logger.info(
+        "音频混音: plan_id=%s main_clips=%d audio_clips=%d",
+        ctx.plan_id,
+        len(main_clips),
+        len(audio_clips),
+    )
+    try:
+        run_ffmpeg(command)
+    except subprocess.CalledProcessError as e:
+        logger.error(
+            "音频混音失败: plan_id=%s exit_code=%d\nfilter_complex:\n%s",
+            ctx.plan_id,
+            e.returncode,
+            filter_complex[:3000],
+        )
+        raise
+
+
+def merge_audio_video(
+    ctx: RenderContext,
+    video_path: Path,
+    audio_path: Path,
+    output_path: Path,
+) -> None:
+    """将音频合并到视频中（视频流拷贝，音频直接复用）.
+
+    Args:
+        ctx: 渲染上下文
+        video_path: 无声视频路径
+        audio_path: 音频文件路径
+        output_path: 输出文件路径
+    """
+    command = [
+        FFMPEG_BIN,
+        "-y",
+        "-i",
+        str(video_path),
+        "-i",
+        str(audio_path),
+        "-c:v",
+        "copy",
+        "-c:a",
+        "aac",
+        "-b:a",
+        "128k",
+        "-map",
+        "0:v:0",
+        "-map",
+        "1:a:0",
+        "-shortest",
+        "-movflags",
+        "+faststart",
+        str(output_path),
+    ]
+
+    logger.info("合并音视频: plan_id=%s", ctx.plan_id)
+    try:
+        run_ffmpeg(command)
+    except subprocess.CalledProcessError as e:
+        logger.error(
+            "合并音视频失败: plan_id=%s exit_code=%d",
+            ctx.plan_id,
+            e.returncode,
+        )
+        raise

apps/worker/video_processing/render_subtitles.py

@@ -0,0 +1,255 @@
+"""ASS 字幕生成模块 — 从 unified_render_service.py 拆分.
+
+职责：
+- 将 title / subtitle 配置转换为 ASS 字幕文件
+- 提供样式计算（颜色、对齐、描边/阴影）
+- 供 UnifiedRenderService._maybe_generate_ass 调用
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+# ── 常量 ──────────────────────────────────────────────────────────────────────
+
+# Title/Subtitle 默认边距（像素）
+TITLE_MARGIN_TOP = 60
+TITLE_MARGIN_BOTTOM = 60
+TITLE_MARGIN_SIDE = 40
+
+
+# ── ASS 字幕工具 ─────────────────────────────────────────────────────────────
+
+
+def _hex_to_ass_color(hex_color: str) -> str:
+    """将 HEX 颜色（#RRGGBB）转换为 ASS &HBBGGRR 格式。"""
+    hex_color = hex_color.lstrip("#")
+    if len(hex_color) != 6:
+        return "&H000000"
+    r, g, b = hex_color[0:2], hex_color[2:4], hex_color[4:6]
+    return f"&H{b.upper()}{g.upper()}{r.upper()}"
+
+
+def _position_to_ass_alignment(position: str) -> int:
+    """将文字位置映射为 ASS \\an 对齐编号。
+
+    ASS 对齐编号（数字小键盘布局）：
+      7 8 9
+      4 5 6
+      1 2 3
+    """
+    mapping = {
+        "top": 8,  # 顶部居中
+        "center": 5,  # 居中
+        "bottom": 2,  # 底部居中
+    }
+    return mapping.get(position, 8)
+
+
+def _build_ass_style(
+    style_name: str,
+    *,
+    font_name: str = "思源黑体",
+    font_size: int = 48,
+    primary_color: str = "&H00FFFFFF",
+    outline_color: str = "&H00000000",
+    outline_width: float = 1.0,
+    shadow_blur: float = 0.0,
+    shadow_offset: tuple[int, int] = (0, 0),
+    bold: bool = False,
+    italic: bool = False,
+    alignment: int = 8,
+    margin_v: int = 60,
+    margin_l: int = 40,
+    margin_r: int = 40,
+) -> str:
+    """构建 ASS Style 行。
+
+    Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour,
+            Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle,
+            BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
+    """
+    bold_val = -1 if bold else 0
+    italic_val = -1 if italic else 0
+
+    # BackColour 用于阴影（BorderStyle=1 时 outline + shadow）
+    back_color = primary_color  # 阴影颜色默认同文字色（带透明度由阴影模糊控制）
+
+    # Shadow 值：ASS 中 Shadow 字段是阴影偏移距离（像素），
+    # 我们用 shadow_offset[1] 作为纵向偏移，模糊由 BorderStyle=3 实现
+    # 简化：BorderStyle=1（outline + drop shadow），Shadow 字段表示阴影深度
+    shadow_depth = shadow_offset[1] if shadow_blur > 0 else 0
+
+    return (
+        f"Style: {style_name},{font_name},{font_size},{primary_color},"
+        f"&H000000FF,{outline_color},{back_color},"
+        f"{bold_val},{italic_val},0,0,100,100,0,0,"
+        f"1,{outline_width},{shadow_depth},{alignment},"
+        f"{margin_l},{margin_r},{margin_v},1"
+    )
+
+
+def _escape_ass_text(text: str) -> str:
+    r"""转义 ASS 文本中的特殊字符。
+
+    ASS 中换行用 \N（硬换行）或 \n（软换行），
+    大括号 {} 用于覆盖样式，需要转义。
+    """
+    # 将实际换行转为 ASS 硬换行
+    text = text.replace("\r\n", "\\N").replace("\n", "\\N").replace("\r", "\\N")
+    # 转义大括号（ASS 用它做样式覆盖标签）
+    text = text.replace("{", "(").replace("}", ")")
+    return text
+
+
+def _format_ass_time(seconds: float) -> str:
+    """将秒数格式化为 ASS 时间格式 H:MM:SS.cc。"""
+    hours = int(seconds // 3600)
+    minutes = int((seconds % 3600) // 60)
+    secs = seconds % 60
+    return f"{hours}:{minutes:02d}:{secs:05.2f}"
+
+
+def generate_ass_subtitles(
+    output_path: Path,
+    *,
+    video_width: int,
+    video_height: int,
+    video_duration: float,
+    title_text: str = "",
+    title_config: dict[str, Any] | None = None,
+    subtitle_text: str = "",
+    subtitle_config: dict[str, Any] | None = None,
+) -> Path:
+    """生成 ASS 字幕文件。
+
+    支持 Title（标题）和 Subtitle（字幕）两种字幕类型，
+    各自可独立配置样式、位置和内容。
+
+    Args:
+        output_path: 输出 ASS 文件路径
+        video_width: 视频宽度（用于 ASS PlayResX）
+        video_height: 视频高度（用于 ASS PlayResY）
+        video_duration: 视频总时长（秒），字幕显示整个时长
+        title_text: 标题文本
+        title_config: 标题样式配置（TitleConfig dict）
+        subtitle_text: 字幕文本
+        subtitle_config: 字幕样式配置（SubtitleConfig dict）
+
+    Returns:
+        生成的 ASS 文件路径
+    """
+    title_config = title_config or {}
+    subtitle_config = subtitle_config or {}
+
+    title_enabled = title_config.get("enabled", True) and bool(title_text.strip())
+    subtitle_enabled = subtitle_config.get("enabled", True) and bool(subtitle_text.strip())
+
+    if not title_enabled and not subtitle_enabled:
+        # 没有字幕，生成空文件（仍返回路径，调用方自行判断是否使用）
+        output_path.write_text("", encoding="utf-8")
+        return output_path
+
+    styles: list[str] = []
+    events: list[str] = []
+
+    # ── Title 样式与事件 ──────────────────────────────────────────────────
+    if title_enabled:
+        title_color = _hex_to_ass_color(title_config.get("color", "#ffffff"))
+        title_stroke = title_config.get("stroke", {}) or {}
+        title_shadow = title_config.get("shadow", {}) or {}
+        stroke_color = _hex_to_ass_color(title_stroke.get("color", "#000000"))
+        stroke_width = float(title_stroke.get("width", 1)) if title_stroke.get("enabled", False) else 0.0
+        shadow_blur = float(title_shadow.get("blur", 4)) if title_shadow.get("enabled", False) else 0.0
+        shadow_offset = (
+            title_shadow.get("offset_x", 2) if title_shadow.get("enabled", False) else 0,
+            title_shadow.get("offset_y", 2) if title_shadow.get("enabled", False) else 0,
+        )
+
+        title_alignment = _position_to_ass_alignment(title_config.get("position", "top"))
+
+        styles.append(
+            _build_ass_style(
+                "TitleStyle",
+                font_name=title_config.get("font", "思源黑体"),
+                font_size=int(title_config.get("size", 48)),
+                primary_color=title_color,
+                outline_color=stroke_color,
+                outline_width=stroke_width,
+                shadow_blur=shadow_blur,
+                shadow_offset=shadow_offset,
+                bold=bool(title_config.get("bold", True)),
+                italic=bool(title_config.get("italic", False)),
+                alignment=title_alignment,
+                margin_v=TITLE_MARGIN_TOP,
+                margin_l=TITLE_MARGIN_SIDE,
+                margin_r=TITLE_MARGIN_SIDE,
+            )
+        )
+
+        # 转义 ASS 特殊字符
+        safe_title_text = _escape_ass_text(title_text)
+
+        events.append(
+            "Dialogue: 0,0:00:00.00," f"{_format_ass_time(video_duration)}," "TitleStyle,,0,0,0,," f"{safe_title_text}"
+        )
+
+    # ── Subtitle 样式与事件 ───────────────────────────────────────────────
+    if subtitle_enabled:
+        sub_color = _hex_to_ass_color(subtitle_config.get("color", "#ffffff"))
+        sub_alignment = _position_to_ass_alignment(subtitle_config.get("position", "bottom"))
+
+        styles.append(
+            _build_ass_style(
+                "SubtitleStyle",
+                font_name=subtitle_config.get("font", "思源黑体"),
+                font_size=int(subtitle_config.get("size", 24)),
+                primary_color=sub_color,
+                outline_color="&H00000000",
+                outline_width=1.0,
+                shadow_blur=0.0,
+                shadow_offset=(0, 0),
+                bold=False,
+                italic=False,
+                alignment=sub_alignment,
+                margin_v=TITLE_MARGIN_BOTTOM,
+                margin_l=TITLE_MARGIN_SIDE,
+                margin_r=TITLE_MARGIN_SIDE,
+            )
+        )
+
+        safe_subtitle_text = _escape_ass_text(subtitle_text)
+
+        events.append(
+            "Dialogue: 0,0:00:00.00,"
+            f"{_format_ass_time(video_duration)},"
+            "SubtitleStyle,,0,0,0,,"
+            f"{safe_subtitle_text}"
+        )
+
+    # ── 组装 ASS 文件 ─────────────────────────────────────────────────────
+    ass_content = f"""[Script Info]
+ScriptType: v4.00+
+PlayResX: {video_width}
+PlayResY: {video_height}
+ScaledBorderAndShadow: yes
+WrapStyle: 2
+Encoding: UTF-8
+
+[V4+ Styles]
+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding  # noqa: E501
+{chr(10).join(styles)}
+
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+{chr(10).join(events)}
+"""
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(ass_content, encoding="utf-8")
+    return output_path

apps/worker/video_processing/unified_render_service.py

@@ -39,18 +39,12 @@ from video_processing.ffmpeg_utils import (
     probe_video_info,
     run_ffmpeg,
 )
+from video_processing.render_audio import RenderContext, merge_audio_video, mix_audio
+from video_processing.render_subtitles import generate_ass_subtitles
 
 logger = logging.getLogger(__name__)
 
 
-# ── 常量 ──────────────────────────────────────────────────────────────────────
-
-# Title/Subtitle 默认边距（像素）
-TITLE_MARGIN_TOP = 60
-TITLE_MARGIN_BOTTOM = 60
-TITLE_MARGIN_SIDE = 40
-
-
 # ── 数据结构 ──────────────────────────────────────────────────────────────────
 
 
@@ -97,238 +91,6 @@ class RenderResult:
 # ── clip_type → layer role 映射 ──────────────────────────────────────────────
 
 
-# ── ASS 字幕工具 ─────────────────────────────────────────────────────────────
-
-
-def _hex_to_ass_color(hex_color: str) -> str:
-    """将 HEX 颜色（#RRGGBB）转换为 ASS &HBBGGRR 格式。"""
-    hex_color = hex_color.lstrip("#")
-    if len(hex_color) != 6:
-        return "&H000000"
-    r, g, b = hex_color[0:2], hex_color[2:4], hex_color[4:6]
-    return f"&H{b.upper()}{g.upper()}{r.upper()}"
-
-
-def _position_to_ass_alignment(position: str) -> int:
-    """将文字位置映射为 ASS \an 对齐编号。
-
-    ASS 对齐编号（数字小键盘布局）：
-      7 8 9
-      4 5 6
-      1 2 3
-    """
-    mapping = {
-        "top": 8,  # 顶部居中
-        "center": 5,  # 居中
-        "bottom": 2,  # 底部居中
-    }
-    return mapping.get(position, 8)
-
-
-def _build_ass_style(
-    style_name: str,
-    *,
-    font_name: str = "思源黑体",
-    font_size: int = 48,
-    primary_color: str = "&H00FFFFFF",
-    outline_color: str = "&H00000000",
-    outline_width: float = 1.0,
-    shadow_blur: float = 0.0,
-    shadow_offset: tuple[int, int] = (0, 0),
-    bold: bool = False,
-    italic: bool = False,
-    alignment: int = 8,
-    margin_v: int = 60,
-    margin_l: int = 40,
-    margin_r: int = 40,
-) -> str:
-    """构建 ASS Style 行。
-
-    Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour,
-            Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle,
-            BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
-    """
-    bold_val = -1 if bold else 0
-    italic_val = -1 if italic else 0
-
-    # BackColour 用于阴影（BorderStyle=1 时 outline + shadow）
-    back_color = primary_color  # 阴影颜色默认同文字色（带透明度由阴影模糊控制）
-
-    # Shadow 值：ASS 中 Shadow 字段是阴影偏移距离（像素），
-    # 我们用 shadow_offset[1] 作为纵向偏移，模糊由 BorderStyle=3 实现
-    # 简化：BorderStyle=1（outline + drop shadow），Shadow 字段表示阴影深度
-    shadow_depth = shadow_offset[1] if shadow_blur > 0 else 0
-
-    return (
-        f"Style: {style_name},{font_name},{font_size},{primary_color},"
-        f"&H000000FF,{outline_color},{back_color},"
-        f"{bold_val},{italic_val},0,0,100,100,0,0,"
-        f"1,{outline_width},{shadow_depth},{alignment},"
-        f"{margin_l},{margin_r},{margin_v},1"
-    )
-
-
-def generate_ass_subtitles(
-    output_path: Path,
-    *,
-    video_width: int,
-    video_height: int,
-    video_duration: float,
-    title_text: str = "",
-    title_config: dict[str, Any] | None = None,
-    subtitle_text: str = "",
-    subtitle_config: dict[str, Any] | None = None,
-) -> Path:
-    """生成 ASS 字幕文件。
-
-    支持 Title（标题）和 Subtitle（字幕）两种字幕类型，
-    各自可独立配置样式、位置和内容。
-
-    Args:
-        output_path: 输出 ASS 文件路径
-        video_width: 视频宽度（用于 ASS PlayResX）
-        video_height: 视频高度（用于 ASS PlayResY）
-        video_duration: 视频总时长（秒），字幕显示整个时长
-        title_text: 标题文本
-        title_config: 标题样式配置（TitleConfig dict）
-        subtitle_text: 字幕文本
-        subtitle_config: 字幕样式配置（SubtitleConfig dict）
-
-    Returns:
-        生成的 ASS 文件路径
-    """
-    title_config = title_config or {}
-    subtitle_config = subtitle_config or {}
-
-    title_enabled = title_config.get("enabled", True) and bool(title_text.strip())
-    subtitle_enabled = subtitle_config.get("enabled", True) and bool(subtitle_text.strip())
-
-    if not title_enabled and not subtitle_enabled:
-        # 没有字幕，生成空文件（仍返回路径，调用方自行判断是否使用）
-        output_path.write_text("", encoding="utf-8")
-        return output_path
-
-    styles: list[str] = []
-    events: list[str] = []
-
-    # ── Title 样式与事件 ──────────────────────────────────────────────────
-    if title_enabled:
-        title_color = _hex_to_ass_color(title_config.get("color", "#ffffff"))
-        title_stroke = title_config.get("stroke", {}) or {}
-        title_shadow = title_config.get("shadow", {}) or {}
-        stroke_color = _hex_to_ass_color(title_stroke.get("color", "#000000"))
-        stroke_width = float(title_stroke.get("width", 1)) if title_stroke.get("enabled", False) else 0.0
-        shadow_blur = float(title_shadow.get("blur", 4)) if title_shadow.get("enabled", False) else 0.0
-        shadow_offset = (
-            title_shadow.get("offset_x", 2) if title_shadow.get("enabled", False) else 0,
-            title_shadow.get("offset_y", 2) if title_shadow.get("enabled", False) else 0,
-        )
-
-        title_alignment = _position_to_ass_alignment(title_config.get("position", "top"))
-
-        styles.append(
-            _build_ass_style(
-                "TitleStyle",
-                font_name=title_config.get("font", "思源黑体"),
-                font_size=int(title_config.get("size", 48)),
-                primary_color=title_color,
-                outline_color=stroke_color,
-                outline_width=stroke_width,
-                shadow_blur=shadow_blur,
-                shadow_offset=shadow_offset,
-                bold=bool(title_config.get("bold", True)),
-                italic=bool(title_config.get("italic", False)),
-                alignment=title_alignment,
-                margin_v=TITLE_MARGIN_TOP,
-                margin_l=TITLE_MARGIN_SIDE,
-                margin_r=TITLE_MARGIN_SIDE,
-            )
-        )
-
-        # 转义 ASS 特殊字符
-        safe_title_text = _escape_ass_text(title_text)
-
-        events.append(
-            "Dialogue: 0,0:00:00.00," f"{_format_ass_time(video_duration)}," "TitleStyle,,0,0,0,," f"{safe_title_text}"
-        )
-
-    # ── Subtitle 样式与事件 ───────────────────────────────────────────────
-    if subtitle_enabled:
-        sub_color = _hex_to_ass_color(subtitle_config.get("color", "#ffffff"))
-        sub_alignment = _position_to_ass_alignment(subtitle_config.get("position", "bottom"))
-
-        styles.append(
-            _build_ass_style(
-                "SubtitleStyle",
-                font_name=subtitle_config.get("font", "思源黑体"),
-                font_size=int(subtitle_config.get("size", 24)),
-                primary_color=sub_color,
-                outline_color="&H00000000",
-                outline_width=1.0,
-                shadow_blur=0.0,
-                shadow_offset=(0, 0),
-                bold=False,
-                italic=False,
-                alignment=sub_alignment,
-                margin_v=TITLE_MARGIN_BOTTOM,
-                margin_l=TITLE_MARGIN_SIDE,
-                margin_r=TITLE_MARGIN_SIDE,
-            )
-        )
-
-        safe_subtitle_text = _escape_ass_text(subtitle_text)
-
-        events.append(
-            "Dialogue: 0,0:00:00.00,"
-            f"{_format_ass_time(video_duration)},"
-            "SubtitleStyle,,0,0,0,,"
-            f"{safe_subtitle_text}"
-        )
-
-    # ── 组装 ASS 文件 ─────────────────────────────────────────────────────
-    ass_content = f"""[Script Info]
-ScriptType: v4.00+
-PlayResX: {video_width}
-PlayResY: {video_height}
-ScaledBorderAndShadow: yes
-WrapStyle: 2
-Encoding: UTF-8
-
-[V4+ Styles]
-Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding  # noqa: E501
-{chr(10).join(styles)}
-
-[Events]
-Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
-{chr(10).join(events)}
-"""
-
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-    output_path.write_text(ass_content, encoding="utf-8")
-    return output_path
-
-
-def _escape_ass_text(text: str) -> str:
-    r"""转义 ASS 文本中的特殊字符。
-
-    ASS 中换行用 \N（硬换行）或 \n（软换行），
-    大括号 {} 用于覆盖样式，需要转义。
-    """
-    # 将实际换行转为 ASS 硬换行
-    text = text.replace("\r\n", "\\N").replace("\n", "\\N").replace("\r", "\\N")
-    # 转义大括号（ASS 用它做样式覆盖标签）
-    text = text.replace("{", "(").replace("}", ")")
-    return text
-
-
-def _format_ass_time(seconds: float) -> str:
-    """将秒数格式化为 ASS 时间格式 H:MM:SS.cc。"""
-    hours = int(seconds // 3600)
-    minutes = int((seconds % 3600) // 60)
-    secs = seconds % 60
-    return f"{hours}:{minutes:02d}:{secs:05.2f}"
-
-
 def _resolve_layer_role(clip_type: str, config: dict[str, Any]) -> str:
     """根据 clip_type 和 config.role 确定图层角色。
 
@@ -476,7 +238,10 @@ class UnifiedRenderService:
             else:
                 # 回退到带滤镜的直通渲染
                 pass_through_has_audio = self._render_pass_through(
-                    layers, output_path, ass_path=ass_path, video_duration=video_duration
+                    layers,
+                    output_path,
+                    ass_path=ass_path,
+                    video_duration=video_duration,
                 )
         else:
             filter_complex, input_args = self._build_filter_complex(layers, ass_path=ass_path)
@@ -501,7 +266,8 @@ class UnifiedRenderService:
             # 直通场景已在一次调用中完成视频+音频
             has_audio = pass_through_has_audio
         else:
-            audio_path = self._mix_audio(layers, video_duration)
+            ctx = RenderContext(work_dir=self.work_dir, plan_id=self.plan.id)
+            audio_path = mix_audio(ctx, layers, video_duration)
             t_audio_end = time.time()
             audio_mix_ms = int((t_audio_end - t_audio_start) * 1000)
             has_audio = audio_path is not None
@@ -512,7 +278,7 @@ class UnifiedRenderService:
                     audio_mix_ms,
                 )
                 # 7. 合并音视频
-                self._merge_audio_video(video_only_path, audio_path, output_path)
+                merge_audio_video(ctx, video_only_path, audio_path, output_path)
             else:
                 # 无音频，直接用无声视频
                 import shutil
@@ -798,8 +564,12 @@ class UnifiedRenderService:
             if output_path.exists():
                 try:
                     output_path.unlink()
-                except OSError:
-                    pass
+                except OSError as unlink_err:
+                    logger.warning(
+                        "[unified-render] 损坏输出文件清理失败: path=%s error=%s",
+                        output_path,
+                        unlink_err,
+                    )
             return False
 
     def _render_pass_through(
@@ -1208,303 +978,9 @@ class UnifiedRenderService:
             info["height"],
         )
 
-    # ── 音频后处理 ────────────────────────────────────────────────────────
-
-    def _mix_audio(self, layers: list[RenderLayer], video_duration: float) -> Path | None:
-        """音频后处理混音.
-
-        处理逻辑：
-        1. 主音频源按优先级查找：main > broll（background 不参与主音频，通常是图片无音轨）
-        2. 主图层音频按顺序 concat 拼接
-        3. 独立音频轨（audio role）用 amix 混入
-        4. 输出时长截断到 video_duration
-        5. 无音频流的 clip 会被自动跳过，避免 FFmpeg 引用 [i:a] 失败
-
-        Args:
-            layers: 图层列表
-            video_duration: 视频总时长（用于截断音频）
-
-        Returns:
-            混音后的音频文件路径，无音频时返回 None
-        """
-        # 按优先级精确查找主音频图层：main > broll
-        # background 不参与主音频（通常是静态图片，无音轨）
-        layer_map = {layer.role: layer for layer in layers}
-        main_layer = None
-        for role in ("main", "broll"):
-            if role in layer_map and layer_map[role].clips:
-                main_layer = layer_map[role]
-                break
-
-        main_clips: list[ResolvedClip] = main_layer.clips if main_layer else []
-
-        # 没有主视频图层时兜底：检查 overlay/corner_voice 层是否有带音频的素材
-        if not main_clips:
-            for role in ("overlay", "corner_voice"):
-                if role in layer_map and layer_map[role].clips:
-                    main_clips = layer_map[role].clips
-                    break
-
-        # 收集独立音频轨
-        audio_clips: list[ResolvedClip] = []
-        if "audio" in layer_map:
-            audio_clips = layer_map["audio"].clips
-
-        # ── 防御：过滤掉无音频流的 clip ──
-        # 源视频可能没有音频流（如静音视频、纯图片转的视频），直接引用 [i:a] 会导致 FFmpeg 失败
-        main_clips = [c for c in main_clips if self._clip_has_audio(c)]
-        audio_clips = [c for c in audio_clips if self._clip_has_audio(c)]
-
-        if not main_clips and not audio_clips:
-            return None
-
-        # 构建音频处理命令
-        output_path = self.work_dir / f"audio_{self.plan.id}.aac"
-
-        # 简单场景：只有主图层 + 无独立音频 → 直接从视频提取音频并拼接
-        if main_clips and not audio_clips:
-            self._concat_main_audio(main_clips, output_path, video_duration)
-            return output_path
-
-        # 有独立音频轨 → amix 混音
-        self._mix_with_independent_audio(main_clips, audio_clips, output_path, video_duration)
-        return output_path
-
-    def _concat_main_audio(self, clips: list[ResolvedClip], output_path: Path, video_duration: float) -> None:
-        """主图层音频 concat 拼接（对齐链路A行为）.
-
-        每个 clip 提取音频 → trim → 按顺序 concat。
-        """
-        if len(clips) == 1:
-            # 单 clip，直接提取音频，截断到 min(clip有效时长, 视频总时长)
-            clip = clips[0]
-            effective_duration = self._clip_effective_duration(clip)
-            # 最终时长：取 clip 有效时长和视频总时长的较小值
-            # （视频总时长由主图层决定，但单 clip 场景下两者应该一致，仍做保护）
-            final_duration = effective_duration
-            if video_duration > 0 and (final_duration <= 0 or final_duration > video_duration):
-                final_duration = video_duration
-
-            command = [
-                FFMPEG_BIN,
-                "-y",
-                "-i",
-                str(clip.local_path),
-                "-vn",
-                "-acodec",
-                "aac",
-                "-b:a",
-                "128k",
-            ]
-            if final_duration > 0:
-                command.extend(["-t", f"{final_duration:.3f}"])
-            command.append(str(output_path))
-            run_ffmpeg(command)
-            return
-
-        # 多 clip，用 filter_complex concat
-        input_args: list[str] = []
-        filter_parts: list[str] = []
-
-        for i, clip in enumerate(clips):
-            input_args.extend(["-i", str(clip.local_path)])
-            effective_duration = self._clip_effective_duration(clip)
-            if effective_duration > 0:
-                filter_parts.append(f"[{i}:a]atrim=0:{effective_duration:.3f},asetpts=PTS-STARTPTS[a{i}]")
-            else:
-                filter_parts.append(f"[{i}:a]asetpts=PTS-STARTPTS[a{i}]")
-
-        audio_labels = "".join(f"[a{i}]" for i in range(len(clips)))
-        filter_parts.append(f"{audio_labels}concat=n={len(clips)}:v=0:a=1[outa]")
-
-        # 截断到视频总时长
-        if video_duration > 0:
-            filter_parts.append(f"[outa]atrim=0:{video_duration:.3f}[final_audio]")
-            final_label = "final_audio"
-        else:
-            final_label = "outa"
-
-        filter_complex = ";".join(filter_parts)
-
-        command = [
-            FFMPEG_BIN,
-            "-y",
-            *input_args,
-            "-filter_complex",
-            filter_complex,
-            "-map",
-            f"[{final_label}]",
-            "-acodec",
-            "aac",
-            "-b:a",
-            "128k",
-            str(output_path),
-        ]
-        run_ffmpeg(command)
-
-    def _mix_with_independent_audio(
-        self,
-        main_clips: list[ResolvedClip],
-        audio_clips: list[ResolvedClip],
-        output_path: Path,
-        video_duration: float,
-    ) -> None:
-        """主音频 + 独立音频轨 amix 混音.
-
-        Args:
-            main_clips: 主视频 clips（提取音频后 concat）
-            audio_clips: 独立音频轨 clips
-            output_path: 输出路径
-            video_duration: 视频总时长
-        """
-        input_args: list[str] = []
-        filter_parts: list[str] = []
-        mix_labels: list[str] = []
-
-        input_idx = 0
-
-        # 1. 主图层音频 concat
-        if main_clips:
-            for clip in main_clips:
-                input_args.extend(["-i", str(clip.local_path)])
-                effective_duration = self._clip_effective_duration(clip)
-                if effective_duration > 0:
-                    filter_parts.append(
-                        f"[{input_idx}:a]atrim=0:{effective_duration:.3f},asetpts=PTS-STARTPTS[ma{input_idx}]"
-                    )
-                else:
-                    filter_parts.append(f"[{input_idx}:a]asetpts=PTS-STARTPTS[ma{input_idx}]")
-                input_idx += 1
-
-            if len(main_clips) == 1:
-                mix_labels.append("ma0")
-            else:
-                main_labels = "".join(f"[ma{i}]" for i in range(len(main_clips)))
-                filter_parts.append(f"{main_labels}concat=n={len(main_clips)}:v=0:a=1[main_audio]")
-                mix_labels.append("main_audio")
-
-        # 2. 独立音频轨
-        for j, clip in enumerate(audio_clips):
-            input_args.extend(["-i", str(clip.local_path)])
-            effective_duration = self._clip_effective_duration(clip)
-            volume = clip.config.get("volume", 1.0) if clip.config else 1.0
-            label = f"ia{j}"
-            filters = []
-            if effective_duration > 0:
-                filters.append(f"atrim=0:{effective_duration:.3f}")
-            filters.append("asetpts=PTS-STARTPTS")
-            if volume != 1.0:
-                filters.append(f"volume={volume}")
-            filter_parts.append(f"[{input_idx}:a]{','.join(filters)}[{label}]")
-            mix_labels.append(label)
-            input_idx += 1
-
-        # 3. amix 混音
-        mix_inputs = "".join(f"[{label}]" for label in mix_labels)
-        n_inputs = len(mix_labels)
-        # normalized=0 保持音量，duration=shortest 取最短
-        filter_parts.append(f"{mix_inputs}amix=inputs={n_inputs}:duration=longest:normalize=0[mixed_audio]")
-
-        # 4. 截断到视频时长
-        if video_duration > 0:
-            filter_parts.append(f"[mixed_audio]atrim=0:{video_duration:.3f}[final_audio]")
-            final_label = "final_audio"
-        else:
-            final_label = "mixed_audio"
-
-        filter_complex = ";".join(filter_parts)
-
-        command = [
-            FFMPEG_BIN,
-            "-y",
-            *input_args,
-            "-filter_complex",
-            filter_complex,
-            "-map",
-            f"[{final_label}]",
-            "-acodec",
-            "aac",
-            "-b:a",
-            "128k",
-            str(output_path),
-        ]
-
-        logger.info(
-            "音频混音: plan_id=%s main_clips=%d audio_clips=%d",
-            self.plan.id,
-            len(main_clips),
-            len(audio_clips),
-        )
-        try:
-            run_ffmpeg(command)
-        except subprocess.CalledProcessError as e:
-            logger.error(
-                "音频混音失败: plan_id=%s exit_code=%d\nfilter_complex:\n%s",
-                self.plan.id,
-                e.returncode,
-                filter_complex[:3000],
-            )
-            raise
-
-    def _merge_audio_video(self, video_path: Path, audio_path: Path, output_path: Path) -> None:
-        """将音频合并到视频中（视频流拷贝，音频直接复用）.
-
-        Args:
-            video_path: 无声视频路径
-            audio_path: 音频文件路径
-            output_path: 输出文件路径
-        """
-        command = [
-            FFMPEG_BIN,
-            "-y",
-            "-i",
-            str(video_path),
-            "-i",
-            str(audio_path),
-            "-c:v",
-            "copy",
-            "-c:a",
-            "aac",
-            "-b:a",
-            "128k",
-            "-map",
-            "0:v:0",
-            "-map",
-            "1:a:0",
-            "-shortest",
-            "-movflags",
-            "+faststart",
-            str(output_path),
-        ]
-
-        logger.info("合并音视频: plan_id=%s", self.plan.id)
-        try:
-            run_ffmpeg(command)
-        except subprocess.CalledProcessError as e:
-            logger.error(
-                "合并音视频失败: plan_id=%s exit_code=%d",
-                self.plan.id,
-                e.returncode,
-            )
-            raise
-
     @staticmethod
     def _clip_effective_duration(clip: ResolvedClip) -> float:
         """计算 clip 的有效时长."""
         if clip.duration > 0:
             return min(clip.duration, clip.actual_duration) if clip.actual_duration > 0 else clip.duration
         return clip.actual_duration if clip.actual_duration > 0 else 0.0
-
-    def _clip_has_audio(self, clip: ResolvedClip) -> bool:
-        """探测 clip 是否有音频流（带缓存）.
-
-        避免同一个 clip 被多次 ffprobe 探测。
-        """
-        if not hasattr(self, "_audio_cache"):
-            self._audio_cache: dict[str, bool] = {}
-        key = str(clip.local_path)
-        if key not in self._audio_cache:
-            from .ffmpeg_utils import probe_has_audio
-
-            self._audio_cache[key] = probe_has_audio(clip.local_path)
-        return self._audio_cache[key]

apps/worker/worker_app/tasks/asset_analyzer.py

@@ -10,12 +10,10 @@ from __future__ import annotations
 
 import json
 import logging
-import math
 import os
 import subprocess
 import tempfile
 from dataclasses import dataclass, field
-from typing import Any
 
 import numpy as np
 from PIL import Image

apps/worker/worker_app/tasks/classification.py

@@ -1,4 +1,3 @@
-from celery import Task
 from celery.utils.log import get_task_logger
 from worker_app.celery_app import celery_app
 
@@ -9,7 +8,6 @@ from packages.adapters.sqlalchemy_impl.classification_job_repository import (
     SQLAlchemyClassificationJobRepository,
 )
 from packages.domain import (
-    ClassificationJob,
     ClassificationJobStatus,
     ClassificationStatus,
 )

apps/worker/worker_app/tasks/compose_video.py

@@ -5,12 +5,9 @@
 
 from __future__ import annotations
 
-import logging
 import os
-import shutil
 import subprocess
 import tempfile
-from datetime import datetime, timezone
 from pathlib import Path
 
 from celery.utils.log import get_task_logger

apps/worker/worker_app/tasks/edit_plan_generation.py

@@ -21,7 +21,6 @@ import logging
 import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Optional
 
 from worker_app.celery_app import celery_app
 from worker_app.db import SessionLocal

apps/worker/worker_app/tasks/generation.py

@@ -13,15 +13,13 @@
 
 from __future__ import annotations
 
-import json
 import logging
 import os
 import tempfile
 import time
 from dataclasses import dataclass, field
-from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 from worker_app.celery_app import celery_app
 from worker_app.db import SessionLocal
@@ -69,7 +67,11 @@ def _update_task_status(task_id: str, status_action: str, **kwargs) -> bool:
 
             action(**kwargs)
             repo.update(task)
-            logger.info("GenerationTask 状态更新成功: task_id=%s action=%s", task_id, status_action)
+            logger.info(
+                "GenerationTask 状态更新成功: task_id=%s action=%s",
+                task_id,
+                status_action,
+            )
             return True
         finally:
             session.close()
@@ -174,7 +176,6 @@ def _build_plan_and_clips_from_task(
         path_duration[p] = probe_duration(p)
 
     clips: list[_VirtualClip] = []
-    n = len(downloaded_paths)
 
     if mode == "pip":
         # 1 main + N-1 overlay
@@ -461,7 +462,10 @@ def _download_library_assets(
                 if not storage_key:
                     failed_assets.append(f"{asset.name}({asset.id})")
                     logger.warning(
-                        "[task_id=%s] 素材缺少 file_url, 跳过: asset_id=%s name=%s", task_id, asset.id, asset.name
+                        "[task_id=%s] 素材缺少 file_url, 跳过: asset_id=%s name=%s",
+                        task_id,
+                        asset.id,
+                        asset.name,
                     )
                     if gen_task:
                         gen_task.append_log(
@@ -507,7 +511,12 @@ def _download_library_assets(
                         )
                 else:
                     failed_assets.append(f"{asset.name}({asset.id})")
-                    logger.warning("[task_id=%s] Failed to download asset: %s (id=%s)", task_id, asset.name, asset.id)
+                    logger.warning(
+                        "[task_id=%s] Failed to download asset: %s (id=%s)",
+                        task_id,
+                        asset.name,
+                        asset.id,
+                    )
                     if gen_task:
                         gen_task.append_log(
                             "下载素材",
@@ -716,6 +725,238 @@ def _render_with_legacy_engine(
     return duration, file_size
 
 
+# ── generate_video 阶段子函数 ─────────────────────────────────────────────────
+
+
+def _load_task_info(task_id: str) -> dict | None:
+    """从数据库加载 GenerationTask 元数据。
+
+    Returns:
+        包含任务元数据的字典，任务不存在时返回 None。
+    """
+    from packages.adapters.sqlalchemy_impl.generation_task_repository import (
+        SQLAlchemyGenerationTaskRepository,
+    )
+
+    session = SessionLocal()
+    try:
+        task_repo = SQLAlchemyGenerationTaskRepository(session)
+        gen_task = task_repo.get(task_id)
+        if gen_task is None:
+            return None
+
+        return {
+            "project_id": gen_task.project_id,
+            "asset_library_id": gen_task.asset_library_id,
+            "voice_library_id": gen_task.voice_library_id or "",
+            "template_id": getattr(gen_task, "template_id", "") or "",
+            "mode": gen_task.strategy_id or "one_take",
+            "task_asset_ids": list(gen_task.asset_ids or []),
+            "batch_id": getattr(gen_task, "batch_id", "") or "",
+            "user_id": getattr(gen_task, "created_by_user_id", "") or "",
+        }
+    finally:
+        session.close()
+
+
+def _download_all_assets(
+    temp_path: Path,
+    asset_library_id: str,
+    project_id: str,
+    task_asset_ids: list[str],
+    voice_library_id: str,
+    task_id: str,
+) -> tuple[list[Path], str | None]:
+    """下载视频素材和配音素材。
+
+    Returns:
+        (downloaded_videos, audio_path)
+
+    Note: gen_task 不传入下载函数（session 已关闭），
+    主函数在下载前后已有汇总日志。
+    """
+    logger.info("[task_id=%s] [下载素材] 开始下载视频素材", task_id)
+    download_start = time.monotonic()
+    downloaded_videos = _download_library_assets(
+        temp_path,
+        asset_library_id=asset_library_id,
+        project_id=project_id,
+        asset_ids=task_asset_ids or None,
+        task_id=task_id,
+    )
+    download_elapsed = time.monotonic() - download_start
+    logger.info(
+        "[task_id=%s] [下载素材] 完成: 成功=%d个, 耗时=%.1fs",
+        task_id,
+        len(downloaded_videos),
+        download_elapsed,
+    )
+
+    audio_path: str | None = None
+    if voice_library_id:
+        local_audio = temp_path / "voice.mp3"
+        if _download_voice_asset(voice_library_id, local_audio):
+            audio_path = str(local_audio)
+            logger.info("[task_id=%s] [下载配音] 配音下载成功", task_id)
+
+    return downloaded_videos, audio_path
+
+
+def _render_video(
+    task_id: str,
+    downloaded_videos: list[Path],
+    voice_path: str | None,
+    editing_mode,
+    project_id: str,
+    template_id: str,
+    user_id: str,
+    temp_path: Path,
+    output_name: str,
+) -> tuple[Path, float]:
+    """渲染视频（含配音混音）。
+
+    Returns:
+        (output_path, render_duration)
+    """
+    if not downloaded_videos:
+        raise RuntimeError(f"素材下载结果为空: task_id={task_id}")
+
+    # 构建虚拟 plan + clips
+    virtual_plan, virtual_clips, asset_path_map = _build_plan_and_clips_from_task(
+        task_id=task_id,
+        downloaded_paths=downloaded_videos,
+        mode=editing_mode.value,
+    )
+
+    total_duration = sum(c.duration for c in virtual_clips)
+    logger.info(
+        "[task_id=%s] [剪辑计划] 片段数=%d, 总时长=%.1fs",
+        task_id,
+        len(virtual_clips),
+        total_duration,
+    )
+
+    # 选择渲染引擎
+    engine = _resolve_render_engine(user_id) if user_id else ENGINE_UNIFIED
+    logger.info("[task_id=%s] [渲染] 引擎选择: %s (user_id=%s)", task_id, engine, user_id)
+
+    render_start = time.monotonic()
+    render_output_path = temp_path / f"rendered-{task_id}.mp4"
+
+    if engine == ENGINE_LEGACY:
+        render_duration, _ = _render_with_legacy_engine(
+            task_id=task_id,
+            virtual_clips=virtual_clips,
+            asset_path_map=asset_path_map,
+            work_dir=temp_path,
+            output_path=render_output_path,
+        )
+    else:
+        logger.info("[task_id=%s] [渲染] unified 引擎 FFmpeg 渲染开始", task_id)
+        render_service = UnifiedRenderService(
+            plan=virtual_plan,
+            clips=virtual_clips,
+            asset_path_map=asset_path_map,
+            work_dir=temp_path,
+            output_width=OUTPUT_WIDTH,
+            output_height=OUTPUT_HEIGHT,
+            output_fps=int(OUTPUT_FPS),
+        )
+        render_result = render_service.render()
+        render_output_path = render_result.output_path
+        render_duration = render_result.duration
+
+    render_elapsed = time.monotonic() - render_start
+    logger.info(
+        "[task_id=%s] [渲染] %s 引擎完成: 耗时=%.1fs, 时长=%.2fs",
+        task_id,
+        engine,
+        render_elapsed,
+        render_duration,
+    )
+
+    # 配音混音
+    if voice_path:
+        final_path = temp_path / f"final-{task_id}.mp4"
+        try:
+            _mux_audio_track(render_output_path, voice_path, final_path)
+            output_path = final_path
+        except Exception as mux_err:
+            logger.warning("[task_id=%s] [混音] 音频混合失败，使用无音频版本: %s", task_id, mux_err)
+            output_path = render_output_path
+    else:
+        output_path = render_output_path
+
+    return output_path, render_duration
+
+
+def _upload_and_record(
+    task_id: str,
+    output_path: Path,
+    project_id: str,
+    batch_id: str,
+    editing_mode,
+) -> tuple[str, float, int, int]:
+    """上传 OSS、创建视频记录并查重。
+
+    Returns:
+        (file_url, duration, file_size, video_count)
+    """
+    storage_key = f"generated/projects/{project_id}/tasks/{task_id}/{output_path.name}"
+    file_size = output_path.stat().st_size
+
+    # 上传 OSS
+    logger.info("[task_id=%s] [OSS上传] 开始上传: size=%d", task_id, file_size)
+    upload_start = time.monotonic()
+    file_url = upload_to_oss(output_path, storage_key)
+    upload_elapsed = time.monotonic() - upload_start
+    if not file_url:
+        raise RuntimeError(f"OSS 上传失败: task_id={task_id}, storage_key={storage_key}")
+
+    # 校验 URL 可达性（P0-2: 私有 bucket 用预签名 + object_exists 降级）
+    verify_url = get_signed_download_url(file_url, expires_seconds=300) or file_url
+    if not _verify_url_accessible(verify_url):
+        from video_processing.oss_helpers import normalize_storage_key, oss_bucket
+
+        bucket = oss_bucket()
+        key = normalize_storage_key(file_url)
+        if not (bucket and bucket.object_exists(key)):
+            raise RuntimeError(
+                f"OSS 上传后 URL 不可访问且 object_exists 失败: file_url={file_url}, " f"storage_key={storage_key}"
+            )
+        logger.info(
+            "URL 校验失败但 object_exists 确认文件存在，视为上传成功: storage_key=%s",
+            key,
+        )
+
+    logger.info(
+        "[task_id=%s] [OSS上传] 成功: 耗时=%.1fs, file_url=%s",
+        task_id,
+        upload_elapsed,
+        file_url,
+    )
+
+    # 创建 GeneratedVideo 记录 + 查重
+    duration = probe_duration(output_path)
+    dedup_session = SessionLocal()
+    try:
+        video_count = create_video_record_and_dedup(
+            generation_task_id=task_id,
+            project_id=project_id,
+            batch_id=batch_id,
+            file_url=file_url,
+            file_size=file_size,
+            duration=duration,
+            video_path=str(output_path),
+            mode=editing_mode.value,
+            session=dedup_session,
+        )
+    finally:
+        dedup_session.close()
+
+    return file_url, duration, file_size, video_count or 1
+
+
 # ── Celery Task ──────────────────────────────────────────────────────────────
 
 
@@ -738,294 +979,126 @@ def generate_video(self, task_id: str) -> dict:
     Returns:
         生成结果字典
     """
+    from packages.adapters.sqlalchemy_impl.generation_task_repository import (
+        SQLAlchemyGenerationTaskRepository,
+    )
     from packages.domain import EditingMode
 
     logger.info("[task_id=%s] [接收任务] 开始生成视频任务", task_id)
 
-    # 从数据库加载任务信息
-    session = SessionLocal()
+    # ── 1. 加载任务信息 ──────────────────────────────────────────────────────
+    task_info = _load_task_info(task_id)
+    if task_info is None:
+        logger.error("[task_id=%s] [接收任务] 任务不存在", task_id)
+        return {"status": "failed", "error": f"generation task {task_id} not found"}
+
+    project_id = task_info["project_id"]
+    asset_library_id = task_info["asset_library_id"]
+    voice_library_id = task_info["voice_library_id"]
+    template_id = task_info["template_id"]
+    task_asset_ids = task_info["task_asset_ids"]
+    batch_id = task_info["batch_id"]
+    user_id = task_info["user_id"]
+
+    # 加载 gen_task（用于全程进度日志；_flush_logs 使用独立 session 持久化）
+    _session = SessionLocal()
     try:
-        from packages.adapters.sqlalchemy_impl.generation_task_repository import (
-            SQLAlchemyGenerationTaskRepository,
-        )
+        _repo = SQLAlchemyGenerationTaskRepository(_session)
+        gen_task = _repo.get(task_id)
+    finally:
+        _session.close()
 
-        task_repo = SQLAlchemyGenerationTaskRepository(session)
-        gen_task = task_repo.get(task_id)
-        if gen_task is None:
-            logger.error("[task_id=%s] [接收任务] 任务不存在", task_id)
-            return {"status": "failed", "error": f"generation task {task_id} not found"}
-        project_id = gen_task.project_id
-        asset_library_id = gen_task.asset_library_id
-        voice_library_id = gen_task.voice_library_id or ""
-        template_id = getattr(gen_task, "template_id", "") or ""
-        mode = gen_task.strategy_id or "one_take"
-        task_asset_ids = list(gen_task.asset_ids or [])
-        batch_id = getattr(gen_task, "batch_id", "") or ""
-
-        # 记录接收任务日志
+    # 记录接收任务日志
+    if gen_task:
         gen_task.append_log(
             "接收任务",
-            f"模式={mode}, 模板={template_id}, 素材数={len(task_asset_ids)}",
-            mode=mode,
+            f"模式={task_info['mode']}, 模板={template_id}, 素材数={len(task_asset_ids)}",
+            mode=task_info["mode"],
             template_id=template_id,
             asset_count=len(task_asset_ids),
         )
         _flush_logs(task_id, gen_task)
-    finally:
-        session.close()
 
     # 标记任务为 running
     _update_task_status(task_id, "mark_processing")
 
     try:
-        editing_mode = EditingMode(mode)
+        editing_mode = EditingMode(mode) if (mode := task_info["mode"]) else EditingMode.ONE_TAKE
     except ValueError:
         editing_mode = EditingMode.ONE_TAKE
 
     output_name = f"generated-{task_id}.mp4"
-    storage_key = f"generated/projects/{project_id}/tasks/{task_id}/{output_name}"
 
     try:
-        # P1: template_id 存在性校验
         if template_id:
             _validate_template_exists(template_id)
 
-        # P1: asset_ids 归属校验 — 已合并到 _download_library_assets 同一 session（P3-2）
-
         with tempfile.TemporaryDirectory(prefix="xiaoxia-generation-") as temp_dir:
             temp_path = Path(temp_dir)
-            output_path = temp_path / output_name
 
-            # 1. 从素材库/项目下载视频素材
-            logger.info("[task_id=%s] [下载素材] 开始下载视频素材", task_id)
-            download_start = time.monotonic()
-            downloaded_videos = _download_library_assets(
+            # ── 2. 下载素材 ──────────────────────────────────────────────────
+            downloaded_videos, audio_path = _download_all_assets(
                 temp_path,
                 asset_library_id=asset_library_id,
                 project_id=project_id,
-                asset_ids=task_asset_ids or None,
+                task_asset_ids=task_asset_ids,
+                voice_library_id=voice_library_id,
                 task_id=task_id,
-                gen_task=gen_task,
             )
-            download_elapsed = time.monotonic() - download_start
-            logger.info(
-                "[task_id=%s] [下载素材] 完成: 成功=%d个, 耗时=%.1fs",
-                task_id,
-                len(downloaded_videos),
-                download_elapsed,
-            )
-
-            # 重新加载 gen_task 以追加日志（session 已关闭）
-            _session = SessionLocal()
-            try:
-                _repo = SQLAlchemyGenerationTaskRepository(_session)
-                gen_task = _repo.get(task_id)
-            finally:
-                _session.close()
 
             if gen_task:
                 gen_task.append_log(
                     "下载素材",
                     f"成功下载 {len(downloaded_videos)} 个视频素材",
                     count=len(downloaded_videos),
-                    duration=round(download_elapsed, 2),
                 )
                 _flush_logs(task_id, gen_task)
 
-            # 2. 下载配音（如有）
-            audio_path: str | None = None
-            if voice_library_id:
-                local_audio = temp_path / "voice.mp3"
-                if _download_voice_asset(voice_library_id, local_audio):
-                    audio_path = str(local_audio)
-                    logger.info("[task_id=%s] [下载配音] 配音下载成功", task_id)
-
-            # 3. 渲染
-            if not downloaded_videos:
-                # 素材下载为空（不应到达此处，_download_library_assets 已做校验）
-                raise RuntimeError(
-                    f"素材下载结果为空: task_id={task_id}, "
-                    f"asset_library_id={asset_library_id}, project_id={project_id}, "
-                    f"asset_ids={task_asset_ids}"
-                )
-
-            # 构建虚拟 plan + clips + asset_path_map
-            virtual_plan, virtual_clips, asset_path_map = _build_plan_and_clips_from_task(
+            # ── 3. 渲染 + 混音 ───────────────────────────────────────────────
+            output_path, render_duration = _render_video(
                 task_id=task_id,
-                downloaded_paths=downloaded_videos,
-                mode=editing_mode.value,
-            )
-
-            total_duration = sum(c.duration for c in virtual_clips)
-            logger.info(
-                "[task_id=%s] [剪辑计划] 片段数=%d, 总时长=%.1fs",
-                task_id,
-                len(virtual_clips),
-                total_duration,
+                downloaded_videos=downloaded_videos,
+                voice_path=audio_path,
+                editing_mode=editing_mode,
+                project_id=project_id,
+                template_id=template_id,
+                user_id=user_id,
+                temp_path=temp_path,
+                output_name=output_name,
             )
 
             if gen_task:
-                gen_task.append_log(
-                    "剪辑计划",
-                    f"片段数={len(virtual_clips)}, 总时长={total_duration:.1f}s",
-                    segment_count=len(virtual_clips),
-                    total_duration=round(total_duration, 2),
-                )
+                gen_task.append_log("渲染", f"渲染完成, 时长={render_duration:.1f}s")
                 _flush_logs(task_id, gen_task)
 
-            # 3. 根据 Feature Flag 选择渲染引擎
-            user_id = getattr(gen_task, "created_by_user_id", "") if gen_task else ""
-            engine = _resolve_render_engine(user_id) if user_id else ENGINE_UNIFIED
-            logger.info("[task_id=%s] [渲染] 引擎选择: %s (user_id=%s)", task_id, engine, user_id)
-
-            render_start = time.monotonic()
-            render_output_path = temp_path / f"rendered-{task_id}.mp4"
-
-            if engine == ENGINE_LEGACY:
-                # 旧引擎：filter_complex + concat（保持原帧率，无 fps 归一化）
-                render_duration, render_file_size = _render_with_legacy_engine(
-                    task_id=task_id,
-                    virtual_clips=virtual_clips,
-                    asset_path_map=asset_path_map,
-                    work_dir=temp_path,
-                    output_path=render_output_path,
-                )
-                render_elapsed = time.monotonic() - render_start
-                logger.info(
-                    "[task_id=%s] [渲染] legacy 引擎完成: 耗时=%.1fs, 时长=%.2fs",
-                    task_id,
-                    render_elapsed,
-                    render_duration,
-                )
-            else:
-                # 新引擎：UnifiedRenderService 图层架构
-                logger.info("[task_id=%s] [渲染] unified 引擎 FFmpeg 渲染开始", task_id)
-                render_service = UnifiedRenderService(
-                    plan=virtual_plan,
-                    clips=virtual_clips,
-                    asset_path_map=asset_path_map,
-                    work_dir=temp_path,
-                    output_width=OUTPUT_WIDTH,
-                    output_height=OUTPUT_HEIGHT,
-                    output_fps=int(OUTPUT_FPS),
-                )
-                render_result = render_service.render()
-                render_output_path = render_result.output_path
-                render_duration = render_result.duration
-                render_file_size = render_result.file_size
-                render_elapsed = time.monotonic() - render_start
-                logger.info(
-                    "[task_id=%s] [渲染] unified 引擎完成: 耗时=%.1fs",
-                    task_id,
-                    render_elapsed,
-                )
-
-            if gen_task:
-                gen_task.append_log(
-                    "渲染",
-                    f"引擎={engine}, 耗时={render_elapsed:.1f}s",
-                    duration=round(render_elapsed, 2),
-                    engine=engine,
-                )
-                _flush_logs(task_id, gen_task)
-
-            # 4. 如有配音，后处理混音
-            if audio_path:
-                final_path = temp_path / f"final-{task_id}.mp4"
-                try:
-                    _mux_audio_track(render_output_path, audio_path, final_path)
-                    # 混音成功，使用混音后的文件
-                    output_path = final_path
-                except Exception as mux_err:
-                    logger.warning("[task_id=%s] [混音] 音频混合失败，使用无音频版本: %s", task_id, mux_err)
-                    output_path = render_output_path
-            else:
-                output_path = render_output_path
-
-            file_size = output_path.stat().st_size
-            duration = probe_duration(output_path)
-
-            # 5. 上传到 OSS — 失败必须抛异常，不能静默忽略
-            logger.info("[task_id=%s] [OSS上传] 开始上传: size=%d", task_id, file_size)
-            upload_start = time.monotonic()
-            file_url = upload_to_oss(output_path, storage_key)
-            upload_elapsed = time.monotonic() - upload_start
-            if not file_url:
-                # OSS 未配置或上传失败
-                if gen_task:
-                    gen_task.append_log("OSS上传", "上传失败", level="ERROR")
-                    _flush_logs(task_id, gen_task)
-                raise RuntimeError(
-                    f"OSS 上传失败: task_id={task_id}, storage_key={storage_key}, " f"output_path={output_path}"
-                )
-
-            # P0-2 修复：私有 bucket 下裸 URL 永远 403，改用预签名 URL 校验
-            # 先用预签名 URL 校验，失败则降级为检查文件是否存在（object_exists）
-            verify_url = get_signed_download_url(file_url, expires_seconds=300) or file_url
-            if not _verify_url_accessible(verify_url):
-                # 预签名 URL 也访问失败时，退一步用 object_exists 确认上传成功
-                from video_processing.oss_helpers import normalize_storage_key, oss_bucket
-
-                bucket = oss_bucket()
-                key = normalize_storage_key(file_url)
-                if bucket and bucket.object_exists(key):
-                    logger.info("URL 校验失败但 object_exists 确认文件存在，视为上传成功: storage_key=%s", key)
-                    if gen_task:
-                        gen_task.append_log("OSS上传", "URL校验降级: object_exists确认存在", level="WARN")
-                else:
-                    if gen_task:
-                        gen_task.append_log("OSS上传", "上传后URL不可访问", level="ERROR", file_url=file_url)
-                        _flush_logs(task_id, gen_task)
-                    raise RuntimeError(
-                        f"OSS 上传后 URL 不可访问且 object_exists 失败: file_url={file_url}, "
-                        f"storage_key={storage_key}"
-                    )
-
-            logger.info(
-                "[task_id=%s] [OSS上传] 成功: 耗时=%.1fs, file_url=%s",
-                task_id,
-                upload_elapsed,
-                file_url,
+            # ── 4. 上传 OSS + 查重记录 ───────────────────────────────────────
+            file_url, duration, file_size, video_count = _upload_and_record(
+                task_id=task_id,
+                output_path=output_path,
+                project_id=project_id,
+                batch_id=batch_id,
+                editing_mode=editing_mode,
             )
 
             if gen_task:
                 gen_task.append_log(
                     "OSS上传",
-                    f"上传成功, 大小={file_size}, 耗时={upload_elapsed:.1f}s",
+                    f"上传成功, 大小={file_size}",
                     file_size=file_size,
-                    duration=round(upload_elapsed, 2),
                     file_url=file_url,
                 )
                 _flush_logs(task_id, gen_task)
 
-            # 6. 创建 GeneratedVideo 记录 + 查重
-            dedup_session = SessionLocal()
-            try:
-                video_count = create_video_record_and_dedup(
-                    generation_task_id=task_id,
-                    project_id=project_id,
-                    batch_id=batch_id,
-                    file_url=file_url,
-                    file_size=file_size,
-                    duration=duration,
-                    video_path=str(output_path),
-                    mode=editing_mode.value,
-                    session=dedup_session,
-                )
-            finally:
-                dedup_session.close()
+            # ── 5. 标记完成 ──────────────────────────────────────────────────
+            _update_task_status(task_id, "mark_completed", result_count=video_count)
 
-            # 7. 标记任务为 completed
-            _update_task_status(task_id, "mark_completed", result_count=video_count or 1)
-
-            # 记录完成日志
             if gen_task:
                 gen_task.append_log(
                     "任务完成",
                     f"视频生成完成: 时长={duration:.2f}s, 大小={file_size}",
                     duration=round(duration, 2),
                     file_size=file_size,
-                    video_count=video_count or 1,
+                    video_count=video_count,
                 )
                 _flush_logs(task_id, gen_task)
 

apps/worker/worker_app/tasks/ingest.py

@@ -1,9 +1,6 @@
 import subprocess
 from datetime import datetime, timezone
-from typing import Optional
 
-from celery import Celery
-from celery.app.task import Task
 from celery.utils.log import get_task_logger
 from worker_app.celery_app import celery_app
 from worker_app.core.asset_types import infer_mime_type_from_storage_key

apps/worker/worker_app/tasks/voice_extraction.py

@@ -1,14 +1,11 @@
 """Voice extraction tasks - extract voice tracks and background music from videos."""
 
-import json
 import logging
 import os
 import subprocess
 import tempfile
-from typing import Optional
 
 from celery import Task
-from sqlalchemy.orm import Session
 from worker_app.celery_app import celery_app
 from worker_app.db import SessionLocal
 

packages/application/tts_job/streaming_service.py

@@ -243,8 +243,8 @@ class TTSStreamingService:
         return total
 
     async def _send_json(self, websocket: Any, data: dict) -> None:
-        """安全发送 JSON 帧。"""
+        """发送 JSON 帧，失败时记录日志。"""
         try:
             await websocket.send_json(data)
-        except Exception:
-            pass
+        except Exception as e:
+            logger.warning("WebSocket JSON 发送失败: type=%s error=%s", data.get("type", "?"), e)

packages/shared/storage.py

@@ -30,21 +30,67 @@ class SharedStorageService:
         self.local_url_prefix = os.getenv("GENERATED_FILES_URL_PREFIX", "/generated-files")
         self.bucket = None
 
-        if settings.oss_access_key_id and settings.oss_access_key_secret:
+        has_key_id = bool(settings.oss_access_key_id)
+        has_key_secret = bool(settings.oss_access_key_secret)
+
+        if has_key_id and has_key_secret:
             if oss2 is not None:
-                auth = oss2.Auth(
-                    settings.oss_access_key_id,
-                    settings.oss_access_key_secret,
-                )
-                self.bucket = oss2.Bucket(
-                    auth,
-                    settings.oss_endpoint,
-                    settings.oss_bucket_name,
-                )
+                try:
+                    # P0-2 修复：oss2.Bucket 的 endpoint 必须带 https:// 前缀，
+                    # 否则 sign_url 默认生成 HTTP URL。
+                    bucket_endpoint = settings.oss_endpoint
+                    if not bucket_endpoint.startswith(("http://", "https://")):
+                        bucket_endpoint = f"https://{bucket_endpoint}"
+                    auth = oss2.Auth(
+                        settings.oss_access_key_id,
+                        settings.oss_access_key_secret,
+                    )
+                    self.bucket = oss2.Bucket(
+                        auth,
+                        bucket_endpoint,
+                        settings.oss_bucket_name,
+                    )
+                    logger.info(
+                        "OSS initialized: endpoint=%s bucket=%s",
+                        settings.oss_endpoint,
+                        settings.oss_bucket_name,
+                    )
+                except Exception as error:
+                    logger.error("Failed to initialize OSS bucket client: %s", error)
+            else:
+                logger.error("oss2 SDK is not installed — OSS operations will fail")
+        else:
+            missing = []
+            if not has_key_id:
+                missing.append("OSS_ACCESS_KEY_ID")
+            if not has_key_secret:
+                missing.append("OSS_ACCESS_KEY_SECRET")
+            logger.error("OSS credentials not configured — missing: %s", ", ".join(missing))
+
         self.access_key_id = settings.oss_access_key_id
         self.access_key_secret = settings.oss_access_key_secret
         self.endpoint = settings.oss_endpoint
 
+    def diagnose(self) -> None:
+        """启动诊断：输出 OSS 配置状态，帮助排查预签名 URL 问题。"""
+        key_id_display = (
+            f"{self.access_key_id[:4]}...{self.access_key_id[-4:]}" if len(self.access_key_id) > 8 else "(empty)"
+        )
+        logger.info(
+            "[OSS诊断] endpoint=%s bucket_name=%s access_key_id=%s",
+            self.endpoint,
+            self.bucket_name,
+            key_id_display,
+        )
+        if self.bucket is None:
+            logger.error(
+                "[OSS诊断] ❌ bucket=None — 预签名URL不可用！"
+                "原因: OSS_ACCESS_KEY_ID/OSS_ACCESS_KEY_SECRET 未配置或 oss2 未安装。"
+                "请检查服务器 .env 文件（如 /var/lib/xiaoxia-saas-staging/.env）"
+            )
+        else:
+            logger.info("[OSS诊断] ✅ bucket 已配置，预签名URL可用")
+
     def _is_local_generated_url(self, storage_key_or_url: str) -> bool:
         parsed = urlparse(storage_key_or_url)
         path = parsed.path if parsed.scheme else storage_key_or_url
@@ -90,12 +136,26 @@ class SharedStorageService:
         if self.bucket is None:
             if self._is_local_generated_url(storage_key_or_url):
                 return storage_key_or_url
+            logger.warning(
+                "get_download_url: OSS bucket not configured, returning raw URL. storage_key_or_url=%s",
+                storage_key_or_url[:200],
+            )
             return self.get_url(self._normalize_storage_key(storage_key_or_url))
 
         storage_key = self._normalize_storage_key(storage_key_or_url)
         try:
-            return self.bucket.sign_url("GET", storage_key, expires_seconds)
+            signed = self.bucket.sign_url("GET", storage_key, expires_seconds)
+            logger.info(
+                "get_download_url: signed URL generated. storage_key=%s url_prefix=%s",
+                storage_key[:80],
+                signed[:60],
+            )
+            return signed
         except Exception:
+            logger.exception(
+                "get_download_url: sign_url failed, falling back to raw URL. storage_key=%s",
+                storage_key[:200],
+            )
             return self.get_url(storage_key)
 
     def _normalize_storage_key(self, storage_key_or_url: str) -> str:
@@ -175,6 +235,7 @@ def get_shared_storage_service() -> SharedStorageService:
     global _storage_service
     if _storage_service is None:
         _storage_service = SharedStorageService()
+        _storage_service.diagnose()
     return _storage_service
 
 

requirements-base.txt

@@ -24,9 +24,6 @@ celery==5.4.0
 
 # 对象存储
 oss2==2.18.4
-cryptography==46.0.5
-# 覆盖系统预装的旧版pyOpenSSL，与cryptography 46.0.5兼容
-pyOpenSSL==26.2.0
 
 # HTTP 客户端
 httpx==0.27.2

requirements.txt

@@ -6,9 +6,6 @@ pydantic-settings==2.6.0
 email-validator==2.2.0
 python-multipart==0.0.32
 
-# 邮件
-aiosmtplib==3.0.2
-
 # 测试
 pytest==8.3.3
 pytest-asyncio==0.24.0

scripts/build_release_images.sh

@@ -63,8 +63,7 @@ BRANCH_NAME="${GITHUB_REF_NAME:-${CI_COMMIT_BRANCH:-unknown}}"
 if [ "$USE_CACHE" -eq 1 ]; then
   docker buildx build \
     --build-arg APP_VERSION="$VERSION" \
-    --cache-from "type=registry,ref=${CACHE_REGISTRY}/api-cache:${CACHE_TAG},ignore-error=true" \
-    --cache-to "type=registry,ref=${CACHE_REGISTRY}/api-cache:${CACHE_TAG},mode=max" \
+    --cache-from "type=registry,ref=${CACHE_REGISTRY}/api-cache:${CACHE_TAG_PRIMARY},ignore-error=true" \
     -f infra/docker/api.Dockerfile \
     -t "$API_IMAGE" -t "$API_LATEST" \
     --load \
@@ -123,8 +122,7 @@ echo "=== Building Worker image ==="
 if [ "$USE_CACHE" -eq 1 ]; then
   docker buildx build \
     --build-arg APP_VERSION="$VERSION" \
-    --cache-from "type=registry,ref=${CACHE_REGISTRY}/worker-cache:${CACHE_TAG},ignore-error=true" \
-    --cache-to "type=registry,ref=${CACHE_REGISTRY}/worker-cache:${CACHE_TAG},mode=max" \
+    --cache-from "type=registry,ref=${CACHE_REGISTRY}/worker-cache:${CACHE_TAG_PRIMARY},ignore-error=true" \
     -f infra/docker/worker.Dockerfile \
     -t "$WORKER_IMAGE" -t "$WORKER_LATEST" \
     --load \
@@ -152,8 +150,7 @@ test -f apps/web/dist/index.html
 
 if [ "$USE_CACHE" -eq 1 ]; then
   docker buildx build \
-    --cache-from "type=registry,ref=${CACHE_REGISTRY}/web-cache:${CACHE_TAG},ignore-error=true" \
-    --cache-to "type=registry,ref=${CACHE_REGISTRY}/web-cache:${CACHE_TAG},mode=max" \
+    --cache-from "type=registry,ref=${CACHE_REGISTRY}/web-cache:${CACHE_TAG_PRIMARY},ignore-error=true" \
     -f infra/docker/web-artifact.Dockerfile \
     --build-arg "NGINX_CONF=$NGINX_CONF_FILE" \
     -t "$WEB_IMAGE" \
@@ -182,4 +179,4 @@ else
 fi
 
 echo "=== Build complete ==="
-docker images | grep "xiaoxia-saas.*:$VERSION"
+docker images | grep "xiaoxia-saas" | grep "$VERSION" || true

scripts/check_migration_safety.py

@@ -48,10 +48,19 @@ HIGH_RISK_PATTERNS = [
 
 # 中风险模式：可能导致数据丢失或兼容性问题
 MEDIUM_RISK_PATTERNS = [
-    (r"op\.alter_column\([^)]*nullable\s*=\s*False", "新增 NOT NULL 约束 - 旧数据可能为空导致迁移失败"),
+    (
+        r"op\.alter_column\([^)]*nullable\s*=\s*False",
+        "新增 NOT NULL 约束 - 旧数据可能为空导致迁移失败",
+    ),
     (r"op\.alter_column\([^)]*type_\s*=", "列类型变更 - 可能导致数据截断或转换失败"),
-    (r"\bop\.rename_table\(", "op.rename_table() - 重命名表，可能导致依赖该表的代码报错"),
-    (r"\bop\.rename_column\(", "op.rename_column() - 重命名列，可能导致依赖该列的代码报错"),
+    (
+        r"\bop\.rename_table\(",
+        "op.rename_table() - 重命名表，可能导致依赖该表的代码报错",
+    ),
+    (
+        r"\bop\.rename_column\(",
+        "op.rename_column() - 重命名列，可能导致依赖该列的代码报错",
+    ),
     (r"\bop\.drop_index\(", "op.drop_index() - 删除索引，可能影响查询性能"),
     (r"\bop\.drop_constraint\(", "op.drop_constraint() - 删除约束，可能影响数据完整性"),
 ]
@@ -95,7 +104,16 @@ def get_new_migrations_via_diff(diff_target: str) -> List[Path]:
     """
     try:
         result = subprocess.run(
-            ["git", "diff", "--name-only", "--diff-filter=A", diff_target, "HEAD", "--", "alembic/versions/"],
+            [
+                "git",
+                "diff",
+                "--name-only",
+                "--diff-filter=A",
+                diff_target,
+                "HEAD",
+                "--",
+                "alembic/versions/",
+            ],
             cwd=str(REPO_ROOT),
             capture_output=True,
             text=True,
@@ -247,4 +265,3 @@ def main() -> int:
 
 if __name__ == "__main__":
     sys.exit(main())
-

scripts/init_production_env.sh

@@ -73,7 +73,6 @@ OSS_ACCESS_KEY_ID=$OSS_ACCESS_KEY_ID
 OSS_ACCESS_KEY_SECRET=$OSS_ACCESS_KEY_SECRET
 OSS_BUCKET_NAME=$OSS_BUCKET_NAME
 
-LOG_LEVEL=INFO
 CORS_ORIGINS_RAW=https://xiaoxiajianji.com,https://api.xiaoxiajianji.com
 EOF
 

tests/conftest.py

@@ -17,18 +17,13 @@ os.environ.setdefault("USE_IN_MEMORY_DB", "True")
 # CI 环境没有 Redis，所有 Celery 异步任务都 mock 掉，避免连接超时报错
 # 集成测试只测 API 层逻辑（参数校验、权限、DB 操作），异步任务由 worker 单测覆盖
 
-from unittest.mock import MagicMock, patch
+from unittest.mock import MagicMock
 
 
 def _mock_celery_task():
     """全局 mock Celery 任务的 delay/apply_async/send_task 方法。"""
     from celery import Celery, Task
 
-    # 保存原始方法
-    _orig_delay = Task.delay
-    _orig_apply_async = Task.apply_async
-    _orig_send_task = Celery.send_task
-
     def _mock_delay(self, *args, **kwargs):
         mock_result = MagicMock()
         mock_result.id = "mock-task-id"

tests/integration/conftest.py

@@ -113,7 +113,6 @@ class PerfAssert:
             raise ValueError(f"未知的阈值级别: {threshold_level}，可选: {list(PERF_THRESHOLDS.keys())}")
 
         threshold_ms = PERF_THRESHOLDS[threshold_level]
-        num_samples = samples or self.sample_count
         result = PerfResult(name=name or threshold_level, threshold_ms=threshold_ms)
 
         # 预热（第一次请求可能有冷启动开销）

tests/integration/fixtures/duplication_routes_fixed.py

@@ -1,282 +0,0 @@
-"""查重 API 路由。"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any
-from uuid import uuid4
-
-from app.auth import AuthenticatedUser, get_current_user
-from app.core.storage import OSSStorageService, get_storage_service
-from app.dependencies import get_duplication_repository
-from app.schemas.duplication import (
-    DuplicateSegmentResponse,
-    DuplicationDetailResponse,
-    DuplicationRecordResponse,
-    DuplicationUploadResponse,
-)
-from fastapi import APIRouter, Depends, File, HTTPException, Response, UploadFile, status
-
-from packages.application import (
-    DeleteDuplicationRecordUseCase,
-    GetDuplicationDetailUseCase,
-    ListDuplicationRecordsUseCase,
-    RetryDuplicationUseCase,
-    UploadForDuplicationCommand,
-    UploadForDuplicationUseCase,
-)
-from packages.domain.duplication import DuplicationRecord
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter()
-
-# 查重功能只接受视频文件
-ALLOWED_VIDEO_MIME_TYPES = frozenset(
-    {
-        "video/mp4",
-        "video/mpeg",
-        "video/quicktime",
-        "video/x-msvideo",
-        "video/webm",
-        "video/x-matroska",
-        "video/3gpp",
-    }
-)
-
-
-def _validate_video_mime_type(content_type: str | None) -> str:
-    """验证视频文件的 MIME 类型，如果无效则抛出异常。"""
-    if not content_type:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="Content-Type header is required",
-        )
-
-    # 处理带参数的类型，如 "video/mp4; charset=utf-8"
-    base_type = content_type.split(";")[0].strip().lower()
-
-    if base_type not in ALLOWED_VIDEO_MIME_TYPES:
-        raise HTTPException(
-            status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
-            detail="只支持视频文件。支持的类型: mp4, mpeg, mov, avi, webm, mkv, 3gp",
-        )
-
-    return base_type
-
-
-def _to_record_response(record: DuplicationRecord) -> DuplicationRecordResponse:
-    return DuplicationRecordResponse(
-        id=record.id,
-        filename=record.filename,
-        file_size=record.file_size,
-        duration_seconds=record.duration_seconds,
-        status=record.status,
-        duplicate_rate=record.duplicate_rate,
-        duplicate_count=record.duplicate_count,
-        created_at=record.created_at.isoformat(),
-        updated_at=record.updated_at.isoformat(),
-    )
-
-
-def _to_detail_response(record: DuplicationRecord) -> DuplicationDetailResponse:
-    return DuplicationDetailResponse(
-        id=record.id,
-        filename=record.filename,
-        file_size=record.file_size,
-        duration_seconds=record.duration_seconds,
-        status=record.status,
-        duplicate_rate=record.duplicate_rate,
-        duplicate_count=record.duplicate_count,
-        created_at=record.created_at.isoformat(),
-        updated_at=record.updated_at.isoformat(),
-        segments=[
-            DuplicateSegmentResponse(
-                id=seg.id,
-                source_start=seg.source_start,
-                source_end=seg.source_end,
-                matched_video_id=seg.matched_video_id,
-                matched_video_name=seg.matched_video_name,
-                matched_start=seg.matched_start,
-                matched_end=seg.matched_end,
-                similarity=seg.similarity,
-            )
-            for seg in record.segments
-        ],
-    )
-
-
-@router.post("/upload", response_model=DuplicationUploadResponse)
-async def upload_for_duplication(
-    file: UploadFile = File(..., description="要查重的视频文件"),
-    authenticated_user: AuthenticatedUser = Depends(get_current_user),
-    duplication_repository: Any = Depends(get_duplication_repository),
-    storage_service: OSSStorageService = Depends(get_storage_service),
-) -> DuplicationUploadResponse:
-    """上传视频进行查重。"""
-    if file.filename is None:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="文件名不能为空",
-        )
-
-    # P0-1: 验证 MIME 类型（只接受视频文件）
-    validated_content_type = _validate_video_mime_type(file.content_type)
-
-    # P0-2: 验证文件大小（参考 OSS_DIRECT_UPLOAD_MAX_MB）
-    from app.config import get_settings
-
-    settings = get_settings()
-    max_size_bytes = settings.OSS_DIRECT_UPLOAD_MAX_MB * 1024 * 1024
-
-    # 先检查 Content-Length header（如果可用）
-    if file.size is not None and file.size > max_size_bytes:
-        raise HTTPException(
-            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
-            detail=f"文件超过上传限制 ({settings.OSS_DIRECT_UPLOAD_MAX_MB}MB)",
-        )
-
-    # 读取文件内容并上传到 OSS
-    file_id = uuid4().hex[:8]
-    safe_filename = file.filename.replace("/", "_").replace("\\", "_")
-    storage_key = f"duplication/{file_id}/{safe_filename}"
-
-    try:
-        content = await file.read()
-        file_size = len(content)
-
-        # 再次检查实际文件大小
-        if file_size > max_size_bytes:
-            raise HTTPException(
-                status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
-                detail=f"文件超过上传限制 ({settings.OSS_DIRECT_UPLOAD_MAX_MB}MB)",
-            )
-    except HTTPException:
-        raise
-    except Exception as exc:
-        logger.error("读取查重文件失败: %s", exc, exc_info=True)
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="文件读取失败，请稍后重试",
-        ) from exc
-
-    try:
-        storage_service.upload_file(
-            content,
-            storage_key,
-            content_type=validated_content_type,
-        )
-    except Exception as exc:
-        logger.error("查重文件上传 OSS 失败: %s", exc, exc_info=True)
-        raise HTTPException(
-            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-            detail="文件上传失败，请稍后重试",
-        ) from exc
-
-    use_case = UploadForDuplicationUseCase(duplication_repository)
-    record = use_case.execute(
-        UploadForDuplicationCommand(
-            user_id=authenticated_user.user.id,
-            filename=file.filename,
-            file_size=file_size,
-            storage_key=storage_key,
-        )
-    )
-
-    logger.info(
-        "Duplication upload: record=%s file=%s user=%s",
-        record.id,
-        file.filename,
-        authenticated_user.user.id,
-    )
-
-    return DuplicationUploadResponse(
-        id=record.id,
-        status=record.status,
-        message=f'文件 "{file.filename}" 已上传，正在查重中...',
-    )
-
-
-@router.get("/records", response_model=list[DuplicationRecordResponse])
-def list_duplication_records(
-    authenticated_user: AuthenticatedUser = Depends(get_current_user),
-    duplication_repository: Any = Depends(get_duplication_repository),
-) -> list[DuplicationRecordResponse]:
-    """获取当前用户的查重记录列表。"""
-    use_case = ListDuplicationRecordsUseCase(duplication_repository)
-    records = use_case.execute(authenticated_user.user.id)
-    return [_to_record_response(r) for r in records]
-
-
-@router.get("/records/{record_id}", response_model=DuplicationDetailResponse)
-def get_duplication_detail(
-    record_id: str,
-    authenticated_user: AuthenticatedUser = Depends(get_current_user),
-    duplication_repository: Any = Depends(get_duplication_repository),
-) -> DuplicationDetailResponse:
-    """获取查重记录详情（含重复片段）。"""
-    use_case = GetDuplicationDetailUseCase(duplication_repository)
-    record = use_case.execute(record_id)
-    if record is None:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"查重记录 {record_id} 不存在",
-        )
-    if record.user_id != authenticated_user.user.id:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"查重记录 {record_id} 不存在",
-        )
-    return _to_detail_response(record)
-
-
-@router.delete("/records/{record_id}", status_code=status.HTTP_204_NO_CONTENT, response_class=Response)
-def delete_duplication_record(
-    record_id: str,
-    authenticated_user: AuthenticatedUser = Depends(get_current_user),
-    duplication_repository: Any = Depends(get_duplication_repository),
-) -> Response:
-    """删除查重记录。"""
-    # 检查记录是否存在且属于当前用户
-    detail_uc = GetDuplicationDetailUseCase(duplication_repository)
-    record = detail_uc.execute(record_id)
-    if record is None or record.user_id != authenticated_user.user.id:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"查重记录 {record_id} 不存在",
-        )
-
-    use_case = DeleteDuplicationRecordUseCase(duplication_repository)
-    use_case.execute(record_id)
-    return Response(status_code=204)
-
-
-@router.post("/records/{record_id}/retry", response_model=DuplicationUploadResponse)
-def retry_duplication(
-    record_id: str,
-    authenticated_user: AuthenticatedUser = Depends(get_current_user),
-    duplication_repository: Any = Depends(get_duplication_repository),
-) -> DuplicationUploadResponse:
-    """重新提交查重。"""
-    # 检查记录存在且属于当前用户
-    detail_uc = GetDuplicationDetailUseCase(duplication_repository)
-    record = detail_uc.execute(record_id)
-    if record is None or record.user_id != authenticated_user.user.id:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"查重记录 {record_id} 不存在",
-        )
-
-    use_case = RetryDuplicationUseCase(duplication_repository)
-    updated = use_case.execute(record_id)
-    if updated is None:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"查重记录 {record_id} 不存在",
-        )
-
-    return DuplicationUploadResponse(
-        id=updated.id,
-        status=updated.status,
-        message="已重新提交查重",
-    )

tests/integration/test_api_performance.py

@@ -18,7 +18,6 @@ from __future__ import annotations
 
 import os
 import uuid
-from typing import Optional
 
 import pytest
 from fastapi.testclient import TestClient

tests/integration/test_auth.py

@@ -308,7 +308,7 @@ class TestPasswordReset:
         )
 
         response = client.post(
-            "/api/v1/auth/password/forgot",
+            "/api/v1/auth/forgot-password",
             json={"email": test_email},
         )
 
@@ -318,7 +318,7 @@ class TestPasswordReset:
     def test_request_password_reset_nonexistent_user(self):
         """测试请求不存在的用户密码重置"""
         response = client.post(
-            "/api/v1/auth/password/forgot",
+            "/api/v1/auth/forgot-password",
             json={"email": "nonexistent@example.com"},
         )
 

tests/integration/test_duplication_api.py

@@ -14,7 +14,6 @@ from __future__ import annotations
 
 import os
 import sys
-from dataclasses import replace
 from datetime import datetime, timezone
 from typing import Any
 from unittest.mock import MagicMock
@@ -33,7 +32,7 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "apps", "
 from app.api.routes.duplication import router
 from app.auth import AuthenticatedUser, get_current_user
 from app.core.storage import get_storage_service
-from app.dependencies import get_db_session, get_duplication_repository
+from app.dependencies import get_duplication_repository
 
 from packages.domain.duplication import DuplicateSegment, DuplicationRecord
 

tests/integration/test_duplication_upload_error_handling.py

@@ -32,11 +32,9 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "apps", "
 
 from app.api.routes.duplication import _validate_video_mime_type, router
 from app.auth import AuthenticatedUser, get_current_user
-from app.core.storage import OSSStorageService, get_storage_service
+from app.core.storage import get_storage_service
 from app.dependencies import get_duplication_repository
 
-from packages.domain.duplication import DuplicationRecord
-
 # ── 导入真实模块（不创建 fake module） ────────────────────────────────────────
 from packages.domain.entities import User
 

tests/integration/test_error_scenarios.py

@@ -14,7 +14,6 @@
 
 from __future__ import annotations
 
-import json
 import os
 import sys
 import uuid
@@ -240,7 +239,7 @@ class TestForbidden403:
     """测试 403 禁止访问场景。"""
 
     def test_access_other_user_project(self, auth_headers, other_auth_headers):
-        """访问他人项目应返回 403/404（权限检查未实现时返回 200 为已知问题）。"""
+        """访问他人项目应返回 403。"""
         # 用户 A 创建项目
         created = client.post(
             "/api/v1/projects",
@@ -255,11 +254,10 @@ class TestForbidden403:
             f"/api/v1/projects/{project_id}",
             headers=other_auth_headers,
         )
-        # TODO: 项目权限检查未实现，当前返回 200；实现后应改为 [403, 404]
-        assert response.status_code in [200, 403, 404], f"访问他人项目状态码异常: {response.status_code}"
+        assert response.status_code == 403, f"访问他人项目应返回 403，实际: {response.status_code}"
 
     def test_delete_other_user_project(self, auth_headers, other_auth_headers):
-        """删除他人项目应返回 403/404（权限检查未实现时返回 200/204 为已知问题）。"""
+        """删除他人项目应返回 403。"""
         created = client.post(
             "/api/v1/projects",
             json={"name": "Do Not Delete"},
@@ -272,8 +270,7 @@ class TestForbidden403:
             f"/api/v1/projects/{project_id}",
             headers=other_auth_headers,
         )
-        # TODO: 项目权限检查未实现，当前可能返回 200/204；DELETE 端点未实现时返回 405；实现后应改为 [403, 404]
-        assert response.status_code in [200, 204, 403, 404, 405], f"删除他人项目状态码异常: {response.status_code}"
+        assert response.status_code == 403, f"删除他人项目应返回 403，实际: {response.status_code}"
 
 
 # ---------------------------------------------------------------------------

tests/integration/test_full_pipeline.py

@@ -9,16 +9,12 @@ import shutil
 import subprocess
 import tempfile
 from pathlib import Path
-from unittest.mock import MagicMock, patch
 
 import pytest
 from video_processing.unified_render_service import (
-    RenderResult,
     UnifiedRenderService,
 )
 from worker_app.tasks.generation import (
-    OUTPUT_HEIGHT,
-    OUTPUT_WIDTH,
     _build_plan_and_clips_from_task,
     _create_fallback_clip,
     _mux_audio_track,

tests/integration/test_generation_api.py

@@ -515,7 +515,6 @@ class TestRetryGenerationTask:
             task_id = resp.json()["items"][0]["id"]
 
         # 直接修改 repository 中的任务状态为 failed
-        from app.dependencies import get_generation_task_repository
 
         # 由于是 stub，我们需要通过另一种方式设置状态
         # 让我们直接通过 retry 测试来验证

tests/integration/test_ingest_pipeline.py

@@ -3,7 +3,7 @@ from packages.adapters.in_memory import (
     InMemoryIngestJobRepository,
 )
 from packages.application import SubmitIngestJobCommand, SubmitIngestJobUseCase
-from packages.domain import Asset, IngestJob, IngestJobStatus
+from packages.domain import Asset, IngestJobStatus
 
 
 def simulate_ingest_asset(

tests/integration/test_project_management.py

@@ -1,263 +0,0 @@
-"""项目管理功能集成测试"""
-
-import pytest
-
-# 项目管理功能尚未实现，相关模块不存在，跳过整个文件
-pytest.skip(
-    "项目管理功能尚未实现（project_management_repositories / "
-    "project_management_use_cases / TaskPriority / TaskStatus 均不存在）",
-    allow_module_level=True,
-)
-
-from packages.adapters.in_memory.project_management_repositories import (
-    InMemoryMilestoneRepository,
-    InMemoryTaskIssueRepository,
-    InMemoryTaskRepository,
-)
-from packages.application.project_management_use_cases import (
-    CreateMilestoneUseCase,
-    CreateTaskIssueUseCase,
-    CreateTaskUseCase,
-    ListProjectTasksUseCase,
-    ListTaskIssuesUseCase,
-    ResolveTaskIssueUseCase,
-    UpdateTaskProgressUseCase,
-    UpdateTaskStatusUseCase,
-)
-from packages.domain import TaskPriority, TaskStatus
-
-
-def test_create_task():
-    """测试创建任务"""
-    repo = InMemoryTaskRepository()
-    use_case = CreateTaskUseCase(repo)
-
-    task = use_case.execute(
-        project_id="proj_1",
-        name="开发登录功能",
-        description="实现用户登录功能",
-        priority=TaskPriority.HIGH,
-    )
-
-    assert task.id is not None
-    assert task.name == "开发登录功能"
-    assert task.status == TaskStatus.PENDING
-    assert task.priority == TaskPriority.HIGH
-    assert task.progress == 0.0
-
-
-def test_list_tasks():
-    """测试获取任务列表"""
-    repo = InMemoryTaskRepository()
-    create_use_case = CreateTaskUseCase(repo)
-
-    # 创建两个任务
-    create_use_case.execute(
-        project_id="proj_1",
-        name="任务1",
-    )
-    create_use_case.execute(
-        project_id="proj_1",
-        name="任务2",
-    )
-
-    # 查询任务列表
-    list_use_case = ListProjectTasksUseCase(repo)
-    tasks = list_use_case.execute("proj_1")
-
-    assert len(tasks) == 2
-    assert tasks[0].name == "任务1"
-    assert tasks[1].name == "任务2"
-
-
-def test_update_task_status():
-    """测试更新任务状态"""
-    repo = InMemoryTaskRepository()
-    create_use_case = CreateTaskUseCase(repo)
-    update_use_case = UpdateTaskStatusUseCase(repo)
-
-    # 创建任务
-    task = create_use_case.execute(
-        project_id="proj_1",
-        name="测试任务",
-    )
-
-    # 更新状态为进行中
-    updated_task = update_use_case.execute(task.id, TaskStatus.IN_PROGRESS)
-
-    assert updated_task.status == TaskStatus.IN_PROGRESS
-    assert updated_task.actual_start_date is not None
-
-
-def test_update_task_progress():
-    """测试更新任务进度"""
-    repo = InMemoryTaskRepository()
-    create_use_case = CreateTaskUseCase(repo)
-    progress_use_case = UpdateTaskProgressUseCase(repo)
-
-    # 创建任务
-    task = create_use_case.execute(
-        project_id="proj_1",
-        name="测试任务",
-    )
-
-    # 更新进度到 50%
-    updated_task = progress_use_case.execute(task.id, 50.0)
-
-    assert updated_task.progress == 50.0
-    assert updated_task.status == TaskStatus.IN_PROGRESS
-
-    # 更新进度到 100%
-    completed_task = progress_use_case.execute(task.id, 100.0)
-
-    assert completed_task.progress == 100.0
-    assert completed_task.status == TaskStatus.COMPLETED
-    assert completed_task.actual_end_date is not None
-
-
-def test_create_milestone():
-    """测试创建里程碑"""
-    repo = InMemoryMilestoneRepository()
-    use_case = CreateMilestoneUseCase(repo)
-
-    milestone = use_case.execute(
-        project_id="proj_1",
-        name="V1.0 发布",
-        description="第一个正式版本",
-    )
-
-    assert milestone.id is not None
-    assert milestone.name == "V1.0 发布"
-    assert milestone.completed is False
-
-
-def test_create_and_resolve_issue():
-    """测试创建和解决任务问题"""
-    repo = InMemoryTaskIssueRepository()
-    create_use_case = CreateTaskIssueUseCase(repo)
-    resolve_use_case = ResolveTaskIssueUseCase(repo)
-    list_use_case = ListTaskIssuesUseCase(repo)
-
-    # 创建问题
-    issue = create_use_case.execute(
-        task_id="task_1",
-        project_id="proj_1",
-        title="接口报错",
-        description="调用登录接口返回 500",
-    )
-
-    assert issue.id is not None
-    assert issue.title == "接口报错"
-    assert issue.resolved is False
-
-    # 解决问题
-    resolved_issue = resolve_use_case.execute(issue.id)
-
-    assert resolved_issue.resolved is True
-    assert resolved_issue.resolved_at is not None
-
-    # 查询任务问题列表
-    issues = list_use_case.execute("task_1")
-    assert len(issues) == 1
-    assert issues[0].resolved is True
-
-
-def test_task_hierarchy():
-    """测试任务层级关系"""
-    repo = InMemoryTaskRepository()
-    create_use_case = CreateTaskUseCase(repo)
-
-    # 创建父任务
-    parent_task = create_use_case.execute(
-        project_id="proj_1",
-        name="开发用户模块",
-    )
-
-    # 创建子任务
-    child_task_1 = create_use_case.execute(
-        project_id="proj_1",
-        name="登录功能",
-        parent_task_id=parent_task.id,
-    )
-
-    child_task_2 = create_use_case.execute(
-        project_id="proj_1",
-        name="注册功能",
-        parent_task_id=parent_task.id,
-    )
-
-    # 查询子任务
-    children = repo.list_by_parent(parent_task.id)
-
-    assert len(children) == 2
-    assert children[0].parent_task_id == parent_task.id
-    assert children[1].parent_task_id == parent_task.id
-
-
-def test_get_task_detail():
-    """测试获取任务详情"""
-    from packages.application.get_task_detail_use_case import GetTaskDetailUseCase
-
-    repo = InMemoryTaskRepository()
-    create_use_case = CreateTaskUseCase(repo)
-    get_use_case = GetTaskDetailUseCase(repo)
-
-    # 创建任务
-    task = create_use_case.execute(
-        project_id="proj_1",
-        name="测试任务",
-        description="这是一个测试任务",
-    )
-
-    # 获取详情
-    retrieved_task = get_use_case.execute(task.id)
-
-    assert retrieved_task.id == task.id
-    assert retrieved_task.name == "测试任务"
-    assert retrieved_task.description == "这是一个测试任务"
-
-    # 测试不存在的任务
-    try:
-        get_use_case.execute("nonexistent_id")
-        assert False, "应该抛出异常"
-    except ValueError as e:
-        assert "not found" in str(e)
-
-
-def test_update_task():
-    """测试任务基本信息更新"""
-    from packages.application.update_task_use_case import UpdateTaskUseCase
-
-    repo = InMemoryTaskRepository()
-    create_use_case = CreateTaskUseCase(repo)
-    update_use_case = UpdateTaskUseCase(repo)
-
-    # 创建任务
-    task = create_use_case.execute(
-        project_id="proj_1",
-        name="原始任务",
-        description="原始描述",
-        priority="low",
-    )
-
-    # 更新任务
-    updated_task = update_use_case.execute(
-        task_id=task.id,
-        name="更新后的任务",
-        description="更新后的描述",
-        priority="high",
-    )
-
-    assert updated_task.name == "更新后的任务"
-    assert updated_task.description == "更新后的描述"
-    assert updated_task.priority == "high"
-
-    # 部分更新
-    partial_updated = update_use_case.execute(
-        task_id=task.id,
-        name="又更新了",
-    )
-
-    assert partial_updated.name == "又更新了"
-    assert partial_updated.description == "更新后的描述"  # 保持不变
-    assert partial_updated.priority == "high"  # 保持不变

tests/integration/test_subscription_api.py

@@ -16,7 +16,6 @@ from __future__ import annotations
 import importlib.util
 import os
 import sys
-from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Optional
 
@@ -30,12 +29,10 @@ from fastapi.testclient import TestClient
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "apps", "api"))
 
-from app.auth import AuthenticatedUser, get_current_user
-from app.dependencies import get_user_repository
+from app.auth import AuthenticatedUser
 
 # ── 导入真实模块（不创建 fake module） ────────────────────────────────────────
 from packages.domain.entities import User
-from packages.ports.user_repository import UserRepository
 
 # ── 导入被测路由模块（从 fixtures 加载简化版路由） ─────────────────────────────
 _fixture_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "fixtures", "subscription_routes.py")

tests/integration/test_task_center_api.py

@@ -629,7 +629,6 @@ class TestTaskCenterCrossEndpoint:
         # 2. 重试失败任务
         retry_resp = tc.post("/tasks/gen-fail-cross/retry")
         assert retry_resp.status_code == 200
-        new_task_id = retry_resp.json()["source_id"]
 
         # 3. 再次列出，应有2个任务（旧的failed + 新的pending）
         list_resp2 = tc.get("/tasks")

tests/integration/test_tts_api.py

@@ -18,7 +18,6 @@ from __future__ import annotations
 import os
 import sys
 from datetime import datetime, timezone
-from unittest.mock import MagicMock
 
 # ── 环境变量 & sys.path（必须在导入 app.* 之前设置） ──────────────────────────
 os.environ.setdefault("JWT_SECRET_KEY", "unit-test-secret-key-for-testing")

tests/integration/test_voice_clone_api.py

@@ -18,7 +18,6 @@ from __future__ import annotations
 import os
 import sys
 from datetime import datetime, timezone
-from unittest.mock import MagicMock
 
 # ── 环境变量 & sys.path（必须在导入 app.* 之前设置） ──────────────────────────
 os.environ.setdefault("JWT_SECRET_KEY", "unit-test-secret-key-for-testing")

tests/render_compare/audio_diff.py

@@ -181,7 +181,7 @@ def compute_audio_diff(
             timeout=120,
         )
         stderr = result.stderr or ""
-    except subprocess.CalledProcessError as e:
+    except subprocess.CalledProcessError:
         # 如果音频格式不兼容，返回失败
         return AudioDiffResult(
             audio_a=str(audio_a),

tests/render_compare/runner.py

@@ -30,7 +30,7 @@ import json
 import os
 import sys
 import time
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 from typing import Any
@@ -403,9 +403,6 @@ def generate_html_report(summary: dict[str, Any], output_path: Path):
     scenarios = summary["scenarios"]
 
     # 按通过/失败分组
-    passed_list = [s for s in scenarios if s["passed"]]
-    failed_list = [s for s in scenarios if not s["passed"]]
-
     # 构建场景卡片
     scenario_cards = ""
     for s in scenarios:

tests/unit/test_asset_diagnosis.py

@@ -1,7 +1,6 @@
 import os
 import sys
 from pathlib import Path
-from uuid import uuid4
 
 # 设置必要环境变量（必须在导入 app 模块之前）
 os.environ.setdefault("JWT_SECRET_KEY", "unit-test-secret-key-for-testing")
@@ -9,7 +8,6 @@ os.environ.setdefault("DATABASE_URL", "sqlite:///test.db")
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
 
-import pytest
 from app.api.routes.asset_diagnosis import _build_diagnosis
 from fastapi import FastAPI
 from fastapi.testclient import TestClient

tests/unit/test_asset_library_delete.py

@@ -13,7 +13,6 @@ from __future__ import annotations
 import os
 import sys
 from pathlib import Path
-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")
@@ -220,7 +219,7 @@ class TestDeleteAssetLibrary:
 
         response = client.delete("/api/v1/asset-libraries/lib-1")
         assert response.status_code == 403
-        assert "Access denied" in response.json()["detail"]
+        assert "无权访问该项目" in response.json()["detail"]
 
         # 库未被删除
         assert lib_repo.find_by_id("lib-1") is not None

tests/unit/test_asset_tagging.py

@@ -86,7 +86,7 @@ def test_find_by_tag_ids(asset_repo, tag_repo):
     a2.add_tag(tag1.id)
     asset_repo.update(a2)
 
-    a3 = _create_asset(asset_repo, name="c.mp4")
+    _create_asset(asset_repo, name="c.mp4")
     # 无标签
 
     # 按 tag1 筛选 → a1, a2

tests/unit/test_audio_url_presign.py

@@ -8,8 +8,6 @@ from __future__ import annotations
 
 from unittest.mock import MagicMock, patch
 
-import pytest
-
 
 class TestAudioUrlSigner:
     """测试音频URL签名函数的行为。"""
@@ -79,8 +77,8 @@ class TestAudioUrlSigner:
         mock_svc = MagicMock(spec=OSSStorageService)
         mock_svc.get_download_url.return_value = "https://signed/a.mp3?sig=123"
 
-        # 替换全局单例
-        with patch("app.core.storage._storage_service", mock_svc):
+        # 替换全局单例（现在位于 packages.shared.storage）
+        with patch("packages.shared.storage._storage_service", mock_svc):
             from app.dependencies import get_audio_url_signer
 
             signer = get_audio_url_signer()

tests/unit/test_auto_clip_service.py

@@ -10,10 +10,9 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
 from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any
-from unittest.mock import MagicMock
 
 import pytest
-from app.services.auto_clip_service import AutoClipService, ClipAssignDetail
+from app.services.auto_clip_service import AutoClipService
 
 # ── Stub 实体 ─────────────────────────────────────────────────────────────────
 

tests/unit/test_chunked_upload_routes.py

@@ -20,7 +20,6 @@ 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
 
 # 确保 app 模块可导入
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))

tests/unit/test_config_oss.py

@@ -12,12 +12,9 @@ from __future__ import annotations
 
 import importlib.util
 import os
-import sys
 from pathlib import Path
 from unittest.mock import patch
 
-import pytest
-
 
 def _load_settings_class():
     """
@@ -40,7 +37,7 @@ def _fresh_settings(**env_overrides: dict[str, str]):
         "JWT_SECRET_KEY": "unit-test-secret-key-12345",
         **env_overrides,
     }
-    with patch.dict(os.environ, env, clear=False):
+    with patch.dict(os.environ, env, clear=True):
         Settings = _load_settings_class()
         return Settings()
 

tests/unit/test_config_schemas_and_ai_endpoints.py

@@ -15,9 +15,8 @@ from __future__ import annotations
 
 import os
 import sys
-from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 from unittest.mock import MagicMock
 
 os.environ.setdefault("JWT_SECRET_KEY", "unit-test-secret-key-for-testing")
@@ -41,7 +40,7 @@ class TestNormalizePlanConfig:
         assert result == DEFAULT_EDIT_PLAN_CONFIG.copy()
 
     def test_empty_dict_returns_full_defaults(self):
-        from packages.domain.config_schemas import DEFAULT_EDIT_PLAN_CONFIG, normalize_plan_config
+        from packages.domain.config_schemas import normalize_plan_config
 
         result = normalize_plan_config({})
         assert result["cover"]["type"] == "ai_frame"
@@ -363,7 +362,7 @@ def _create_ai_test_app():
 from fastapi import FastAPI
 from fastapi.testclient import TestClient
 
-from packages.domain.edit_plan import EditPlan, EditPlanStatus
+from packages.domain.edit_plan import EditPlan
 
 
 @pytest.fixture

tests/unit/test_cosyvoice_service.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import json
-from unittest.mock import MagicMock, patch
+from unittest.mock import MagicMock
 
 import httpx
 import pytest

tests/unit/test_dedup_engine.py

@@ -37,13 +37,10 @@ if "worker_app.celery_app" in sys.modules and isinstance(sys.modules["worker_app
 if "worker_app.db" in sys.modules and isinstance(sys.modules["worker_app.db"], MagicMock):
     sys.modules["worker_app.db"].SessionLocal = MagicMock()
 
-# Mock celery.Task base class — 仅在 celery 不可用时注入 mock，避免污染真实包
-try:
-    import celery as _real_celery  # noqa: F401
-except ImportError:
-    _mock_if_absent("celery", MagicMock())
-    if "celery" in sys.modules and isinstance(sys.modules["celery"], MagicMock):
-        sys.modules["celery"].Task = object
+# Mock celery.Task base class
+_mock_if_absent("celery", MagicMock())
+if "celery" in sys.modules and isinstance(sys.modules["celery"], MagicMock):
+    sys.modules["celery"].Task = object
 
 # Mock packages.shared.storage
 _mock_if_absent("packages.shared")

tests/unit/test_duplication_use_cases.py

@@ -22,7 +22,7 @@ from packages.application.duplication import (
     UploadForDuplicationCommand,
     UploadForDuplicationUseCase,
 )
-from packages.domain.duplication import DuplicateSegment, DuplicationRecord
+from packages.domain.duplication import DuplicationRecord
 
 
 def _make_record(status="pending", **kwargs):

tests/unit/test_edit_plan_generation_api.py

@@ -12,7 +12,6 @@ from __future__ import annotations
 import os
 import sys
 from dataclasses import dataclass, field
-from datetime import datetime, timezone
 from typing import Any, Optional
 from unittest.mock import MagicMock, patch
 
@@ -319,7 +318,7 @@ class TestGeneratePlan:
         clip = _make_clip(plan.id, order=1)
         clip_repo.create(clip)
 
-        with patch("app.api.routes.edit_plans.celery_app") as mock_celery:
+        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")
 
@@ -407,7 +406,7 @@ class TestGeneratePlan:
         clip = _make_clip(plan.id, order=1, status=EditPlanClipStatus.READY)
         clip_repo.create(clip)
 
-        with patch("app.api.routes.edit_plans.celery_app") as mock_celery:
+        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")
 
@@ -428,7 +427,7 @@ class TestGeneratePlan:
             clip = _make_clip(plan.id, order=i + 1)
             clip_repo.create(clip)
 
-        with patch("app.api.routes.edit_plans.celery_app") as mock_celery:
+        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")
 
@@ -581,7 +580,7 @@ class TestResponseSchema:
         clip = _make_clip(plan.id, order=1)
         clip_repo.create(clip)
 
-        with patch("app.api.routes.edit_plans.celery_app") as mock_celery:
+        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")
 
@@ -624,7 +623,7 @@ class TestGeneratePlanErrorHandling:
         clip = _make_clip(plan.id, order=1)
         clip_repo.create(clip)
 
-        with patch("app.api.routes.edit_plans.celery_app") as mock_celery:
+        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")
@@ -648,7 +647,7 @@ class TestGeneratePlanErrorHandling:
         clip = _make_clip(plan.id, order=1)
         clip_repo.create(clip)
 
-        with patch("app.api.routes.edit_plans.celery_app") as mock_celery:
+        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")
 
@@ -669,7 +668,7 @@ class TestGeneratePlanErrorHandling:
         clip = _make_clip(plan.id, order=1)
         clip_repo.create(clip)
 
-        with patch("app.api.routes.edit_plans.celery_app") as mock_celery:
+        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")
 

tests/unit/test_edit_plan_worker_failure.py

@@ -13,7 +13,6 @@ from __future__ import annotations
 import os
 import sys
 from dataclasses import dataclass, field
-from datetime import datetime, timezone
 from types import ModuleType
 from typing import Any, Optional
 from unittest.mock import MagicMock, patch
@@ -176,7 +175,6 @@ class TestRenderEditPlanFailureUpdatesGenTask:
         gen_task = StubGenerationTask(id="gen-task-001", status=_StubStatus("running"))
 
         plan_repo = StubPlanRepo(plan)
-        clip_repo = StubClipRepo([])
         gen_task_repo = StubGenTaskRepo(gen_task)
 
         # 让 clip_repo 抛异常以触发 except 路径

tests/unit/test_edit_plans_api.py

@@ -13,7 +13,6 @@ from __future__ import annotations
 
 import os
 import sys
-from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 from unittest.mock import MagicMock

tests/unit/test_edit_template_service.py

@@ -16,8 +16,8 @@ import os
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, List, Optional
-from unittest.mock import MagicMock, patch
+from typing import List, 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")
@@ -27,7 +27,7 @@ import pytest
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
 
 from packages.domain.edit_template import EditTemplate, EditTemplateStatus
-from packages.domain.template_clip_config import ClipType, TemplateClipConfig, TransitionEffect
+from packages.domain.template_clip_config import ClipType, TemplateClipConfig
 
 # ---------------------------------------------------------------------------
 # Stub Repositories
@@ -273,7 +273,7 @@ class TestEditTemplateServiceCRUD:
 
     def test_list_templates_active_only(self):
         svc = _make_service()
-        t1 = svc.create_template(name="活跃")
+        svc.create_template(name="活跃")
         t2 = svc.create_template(name="停用")
         svc.deactivate_template(t2.id)
         result = svc.list_templates(active_only=True)

tests/unit/test_email_service.py

@@ -2,7 +2,7 @@
 邮件服务测试
 """
 
-from unittest.mock import MagicMock, Mock, patch
+from unittest.mock import MagicMock, patch
 
 import pytest
 

tests/unit/test_feature_flag.py

@@ -5,10 +5,7 @@
 
 from __future__ import annotations
 
-import time
-from unittest.mock import MagicMock, patch
-
-import pytest
+from unittest.mock import MagicMock
 
 from packages.adapters.redis.feature_flag_store import (
     FeatureFlagConfig,
@@ -337,7 +334,6 @@ class TestRedisStoreDegradation:
 
     def test_get_returns_default_when_redis_unavailable(self):
         """Redis 连接失败时返回默认关闭配置，不抛异常。"""
-        import importlib
 
         from packages.adapters.redis import feature_flag_store as ff_module
 
@@ -358,7 +354,6 @@ class TestRedisStoreDegradation:
 
     def test_list_all_returns_empty_on_redis_error(self):
         """Redis 错误时 list_all 返回空字典。"""
-        import importlib
 
         from packages.adapters.redis import feature_flag_store as ff_module
 

tests/unit/test_form_upload_routes.py

@@ -21,7 +21,6 @@ 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
 
 # 确保 app 模块可导入
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))

tests/unit/test_generation_feature_flag.py

@@ -11,18 +11,14 @@ from __future__ import annotations
 
 import os
 import sys
-from datetime import datetime, timezone
 from types import ModuleType
-from typing import Any
-from unittest.mock import MagicMock, patch
+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")
 
 from pathlib import Path
 
-import pytest
-
 # ── Mock worker 模块以避免数据库连接 ──────────────────────────────────────────
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "apps", "worker"))
@@ -226,8 +222,6 @@ def test_legacy_engine_two_clips_concat_duration():
     import subprocess
     import tempfile
 
-    from video_processing.ffmpeg_utils import probe_duration
-
     from apps.worker.worker_app.tasks.generation import _render_with_legacy_engine
 
     with tempfile.TemporaryDirectory() as tmpdir:

tests/unit/test_generation_logging.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 import json
 import sys
 from pathlib import Path
-from unittest.mock import MagicMock, patch
+from unittest.mock import patch
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "api"))
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "apps" / "worker"))