style: format client.test.ts with prettier

Bug 1 — 数据源统一：
- scheduleProactiveRefresh() 中 accessToken 和 refreshToken 统一从 Zustand store 读取
- 修复前：accessToken 从 localStorage 读，refreshToken 从 Zustand 读（不一致）
- 修复后：两者都从 useAuthStore.getState() 读取（单一数据源）

Bug 2 — 非空断言修复：
- 移除 client.ts 和 tokenRefresh.ts 中的 user! 强制非空断言
- executeTokenRefresh() 在刷新前检查 user 是否为空，为空则跳过刷新
- client.ts 401 处理中，executeTokenRefresh() 返回 null 时直接登出

并发竞态修复：
- 新增 executeTokenRefresh() 共享函数，带 activeRefreshPromise 锁
- 主动刷新（setTimeout）和被动刷新（401 拦截器）共用同一把锁
- 多个组件同时触发刷新时，只发一次请求，后续调用复用 Promise

测试更新：
- client.test.ts 适配新逻辑，mock executeTokenRefresh 替代直接 mock refreshAccessToken
- 43 个测试全部通过

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

@@ -1,84 +0,0 @@
-name: API Base Image Build
-
-on:
-  push:
-    branches:
-      - develop
-      - main
-    paths:
-      - 'requirements-base.txt'
-      - 'requirements.txt'
-      - 'infra/docker/api-base.Dockerfile'
-  workflow_dispatch:
-
-jobs:
-  build-api-base:
-    name: Build API Base Image
-    runs-on: runtime-builder
-    timeout-minutes: 45
-    steps:
-    - name: Checkout code
-      shell: sh
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      run: |
-        curl -sH "Authorization: token $GITHUB_TOKEN" \
-          "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}" \
-          | bash
-
-    - name: Docker login to Registry
-      shell: sh
-      env:
-        ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
-        ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}
-        GITEA_REGISTRY_USER: xiaoxia
-        GITEA_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
-      run: |
-        set -eu
-        for i in 1 2 3; do
-          echo "=== Docker login 尝试 $i/3 ==="
-          if printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin \
-              && docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"; then
-            echo "✅ Docker login successful"
-            break
-          fi
-          echo "❌ Docker login 失败（尝试 $i/3），5s 后重试..."
-          sleep 5
-        done
-
-    - name: Build and push API base image
-      shell: sh
-      run: |
-        set -eu
-        ACR_IMAGE="xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji/saas-api-base:latest"
-        GITEA_IMAGE="git.xiaoxiajianji.com/xiaoxia-saas/saas-api-base:latest"
-
-        echo "=== Building API base image ==="
-
-        # 使用普通 docker build（单平台不需要 buildx）
-        docker build \
-          -f infra/docker/api-base.Dockerfile \
-          -t "${ACR_IMAGE}" \
-          .
-
-        echo ""
-        echo "✅ Image built successfully"
-
-        # 推送到 ACR
-        echo "=== Pushing to ACR ==="
-        docker push "${ACR_IMAGE}"
-        echo "✅ Pushed to ACR"
-
-        # 打标签并推送到 Gitea Packages 作为备份
-        echo "=== Pushing to Gitea Packages ==="
-        docker tag "${ACR_IMAGE}" "${GITEA_IMAGE}"
-        docker push "${GITEA_IMAGE}" || echo "⚠️ Gitea Packages push failed (non-fatal)"
-        echo "✅ Gitea backup push completed"
-
-    - name: Cleanup
-      if: always()
-      shell: sh
-      run: |
-        ACR_IMAGE="xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji/saas-api-base:latest"
-        docker rmi "${ACR_IMAGE}" 2>/dev/null || true
-        echo "Cleanup done"

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

@@ -24,18 +24,18 @@ jobs:
         - name: builder
           dockerfile: infra/docker/worker-base-builder.Dockerfile
           image_name: worker-base-builder
+          cache_name: worker-base-builder-cache
         - name: runtime
           dockerfile: infra/docker/worker-base-runtime.Dockerfile
           image_name: worker-base-runtime
+          cache_name: worker-base-runtime-cache
     steps:
     - name: Checkout code
       shell: sh
       env:
         GITHUB_TOKEN: ${{ github.token }}
       run: |
-        curl -sH "Authorization: token $GITHUB_TOKEN" \
-          "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}" \
-          | bash
+        curl -sH "Authorization: token $GITHUB_TOKEN"           "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/raw/scripts/ci/step_checkout.sh?ref=${GITHUB_SHA}"           | bash
 
     - name: Docker login to Registry
       shell: sh
@@ -48,8 +48,7 @@ jobs:
         set -eu
         for i in 1 2 3; do
           echo "=== Docker login 尝试 $i/3 ==="
-          if printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin \
-              && docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"; then
+          if printf '%s' "${ACR_PASSWORD}" | docker login xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com -u "${ACR_USERNAME}" --password-stdin              && docker login git.xiaoxiajianji.com -u "${GITEA_REGISTRY_USER}" -p "${GITEA_REGISTRY_TOKEN}"; then
             echo "✅ Docker login successful"
             break
           fi
@@ -57,39 +56,48 @@ jobs:
           sleep 5
         done
 
+    - name: Setup buildx builder
+      shell: sh
+      run: |
+        set -eu
+        BUILDER_NAME="ci-builder-${GITHUB_RUN_ID}-${{ matrix.name }}"
+        if ! docker buildx inspect "$BUILDER_NAME" > /dev/null 2>&1; then
+          docker buildx create --use --name "$BUILDER_NAME" --driver docker-container
+          echo "Created $BUILDER_NAME"
+        else
+          docker buildx use "$BUILDER_NAME"
+          echo "Using existing $BUILDER_NAME"
+        fi
+        docker buildx inspect --bootstrap
+
     - name: Build and push base image
       shell: sh
       run: |
         set -eu
         REGISTRY="xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji"
         IMAGE_TAG="${REGISTRY}/${{ matrix.image_name }}:latest"
-
+        SAFE_REF_NAME=$(echo "${GITHUB_REF_NAME}" | tr '/' '-')
+        CACHE_REF="${REGISTRY}/${{ matrix.cache_name }}:${SAFE_REF_NAME}"
+        
         echo "=== Building ${{ matrix.name }} base image ==="
-        echo "Dockerfile: ${{ matrix.dockerfile }}"
         echo "Image: ${IMAGE_TAG}"
-
-        # 使用普通 docker build（单平台不需要 buildx）
-        docker build \
-          -f "${{ matrix.dockerfile }}" \
-          -t "${IMAGE_TAG}" \
-          .
-
-        docker push "${IMAGE_TAG}"
-
-        # 同时推送到 Gitea Packages 作为备份
+        echo "Cache: ${CACHE_REF}"
+        
+        # 用通用构建脚本
+        bash scripts/ci/docker_build_push.sh           ${{ matrix.dockerfile }}           "${IMAGE_TAG}"           "${CACHE_REF}"
+        
+        # 同时推送到 Gitea Packages 作为备份（可选）
         GITEA_IMAGE="git.xiaoxiajianji.com/xiaoxia-saas/${{ matrix.image_name }}:latest"
         docker tag "${IMAGE_TAG}" "${GITEA_IMAGE}"
         docker push "${GITEA_IMAGE}" || echo "Gitea Packages push failed (non-fatal)"
-
+        
         echo ""
         echo "✅ ${{ matrix.name }} base image built and pushed"
 
-    - name: Cleanup local images
+    - name: Cleanup buildx builder
       if: always()
       shell: sh
       run: |
-        REGISTRY="xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji"
-        docker rmi "${REGISTRY}/${{ matrix.image_name }}:latest" 2>/dev/null || true
-        docker rmi "git.xiaoxiajianji.com/xiaoxia-saas/${{ matrix.image_name }}:latest" 2>/dev/null || true
-        docker image prune -f 2>/dev/null || true
-        echo "Image cleanup done"
+        docker buildx rm "ci-builder-${GITHUB_RUN_ID}-${{ matrix.name }}" 2>/dev/null || true
+        docker buildx prune -f 2>/dev/null || true
+        echo "Builder cleanup done"

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

@@ -1,5 +1,5 @@
 import logging
-from typing import Any, List, Optional
+from typing import Any, Optional
 
 from app.api.routes._helpers import check_project_access, format_utc_datetime
 from app.auth import AuthenticatedUser, get_current_user
@@ -14,7 +14,6 @@ from app.schemas.asset import (
     AssetResponse,
     BatchClassifyRequest,
     BatchDeleteRequest,
-    BatchGetRequest,
     BatchMarkRequest,
     BatchOperationResponse,
     BatchTagRequest,
@@ -371,18 +370,6 @@ def update_asset_review_status(
     return _to_asset_response(updated)
 
 
-@router.post("/batch", response_model=List[AssetResponse])
-def batch_get_assets(
-    request: BatchGetRequest,
-    authenticated_user: AuthenticatedUser = Depends(get_current_user),
-    asset_repository: Any = Depends(get_asset_repository),
-) -> list[AssetResponse]:
-    """批量获取素材详情（根据 ID 列表）。"""
-    items = asset_repository.find_by_ids(request.ids)
-    storage_service = get_storage_service()
-    return [_to_asset_response(item, storage_service) for item in items]
-
-
 @router.post("/batch-delete", response_model=BatchOperationResponse)
 def batch_delete_assets(
     request: BatchDeleteRequest,

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

@@ -1,6 +1,6 @@
 from datetime import datetime, timezone
 
-import psycopg
+import psycopg2
 import redis
 from app.config import settings
 from fastapi import APIRouter, status
@@ -49,7 +49,7 @@ async def _check_database() -> dict:
             "message": "Using in-memory database",
         }
     try:
-        conn = psycopg.connect(settings.DATABASE_URL, connect_timeout=3)
+        conn = psycopg2.connect(settings.DATABASE_URL, connect_timeout=3)
         with conn.cursor() as cur:
             cur.execute("SELECT 1")
             cur.fetchone()
@@ -124,7 +124,7 @@ async def _check_migrations() -> dict:
             "message": "Using in-memory database, no migrations needed",
         }
     try:
-        conn = psycopg.connect(settings.DATABASE_URL, connect_timeout=3)
+        conn = psycopg2.connect(settings.DATABASE_URL, connect_timeout=3)
         with conn.cursor() as cur:
             cur.execute("""
                 SELECT COUNT(*) FROM information_schema.tables

apps/api/app/schemas/asset.py

@@ -58,12 +58,6 @@ class AssetResponse(BaseModel):
 MAX_BATCH_SIZE = 200
 
 
-class BatchGetRequest(BaseModel):
-    """批量获取素材详情请求。"""
-
-    ids: list[str] = Field(..., min_length=1, max_length=MAX_BATCH_SIZE, description="素材 ID 列表")
-
-
 class BatchDeleteRequest(BaseModel):
     """批量删除请求（软删除）。"""
 

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

@@ -214,8 +214,12 @@ test.describe("Core generation flow", () => {
     await titleInput.fill(titleText)
     await page.getByRole("button", { name: "下一步" }).click()
 
-    // Step 5: preview — 前端实时预览架构改造，无需后端生成预览
-    await expect(page.getByRole("heading", { name: /预览设置/ })).toBeVisible({ timeout: 15000 })
+    // Step 5: preview — 需要先生成预览视频，才能进入下一步
+    await expect(page.getByRole("heading", { name: /生成预览/ })).toBeVisible({ timeout: 15000 })
+    // 点击"生成预览"按钮触发预览生成
+    await page.locator(".xx-preview-generate-btn").click()
+    // 等待预览生成完成（后端渲染，可能需要较长时间）
+    await expect(page.getByText("预览生成成功")).toBeVisible({ timeout: 300_000 })
     await page.getByRole("button", { name: "下一步" }).click()
 
     // Step 6: cover (默认 AI 智能选帧模式，直接下一步)

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

@@ -13,9 +13,7 @@ import React, { useMemo } from "react"
 import { Modal, message } from "antd"
 import { useNavigate } from "react-router-dom"
 import type { VoiceClone } from "@/api/voice-clone"
-import { useQuery } from "@tanstack/react-query"
 import { useCloneProgress } from "@/hooks/useCloneProgress"
-import { getAssetsByKind } from "@/api/assets"
 import CloneModal from "@/components/voice/CloneModal"
 import GenerateHeader from "./components/GenerateHeader"
 import GenerateStepsBar from "./components/GenerateStepsBar"
@@ -107,18 +105,6 @@ const GeneratePage: React.FC = () => {
     [userTemplates, selectedTemplate],
   )
 
-  /* ── 配音音频 URL ── */
-  const { data: voiceMaterials = [] } = useQuery({
-    queryKey: ["assets", "voice"],
-    queryFn: () => getAssetsByKind("voice", { limit: 50 }),
-  })
-
-  const voiceAudioUrl = useMemo(() => {
-    if (!selectedVoice) return undefined
-    const asset = voiceMaterials.find((v) => v.id === selectedVoice)
-    return asset?.file_url || undefined
-  }, [selectedVoice, voiceMaterials])
-
   /* ── 步骤导航 ── */
   const { goNext, goPrev } = useStepNavigation({
     currentStep,
@@ -250,7 +236,6 @@ const GeneratePage: React.FC = () => {
               assetsReady={previewAssetsReady}
               assetsLoading={previewAssetsLoading}
               titleSettings={titleSettings}
-              voiceAudioUrl={voiceAudioUrl}
             />
           )}
           {currentStep >= 6 && (

apps/web/src/pages/generate/components/FrontendPreviewPlayer.tsx

@@ -2,9 +2,6 @@
  * 前端预览播放器
  * 用原生 <video> 标签按时间线播放素材片段
  * 替代后端 FFmpeg 渲染预览，实现真正的实时预览
- *
- * 注意：本组件不创建 .xx-preview-video 容器（由父组件 PreviewVideoPanel 提供）
- * 避免嵌套 .xx-preview-video 导致 CSS 冲突
  */
 import React, { useMemo, useCallback, useState, useRef, useEffect } from "react"
 import { PlayCircleOutlined, PauseCircleOutlined, SoundOutlined } from "@ant-design/icons"
@@ -21,8 +18,6 @@ interface FrontendPreviewPlayerProps {
   videoRatio: string
   /** 是否准备好播放（素材已加载） */
   ready: boolean
-  /** 配音音频 URL */
-  voiceAudioUrl?: string
 }
 
 /** 格式化时间 mm:ss */
@@ -46,7 +41,9 @@ function buildPlaybackSegments(
   const segments: PlaybackSegment[] = []
 
   assets.forEach((asset, i) => {
+    // 获取素材时长（从 metadata 或顶层字段）
     const assetDuration = asset.duration || asset.metadata?.duration || 30
+    // 模板片段的时长约束
     const tplSeg = templateSegments[i] || templateSegments[templateSegments.length - 1]
     const segDuration = tplSeg
       ? Math.min(tplSeg.duration_max, Math.max(tplSeg.duration_min, assetDuration))
@@ -55,15 +52,9 @@ function buildPlaybackSegments(
     const startTime = 0
     const endTime = Math.min(startTime + segDuration, assetDuration)
 
-    const videoUrl = asset.file_url || asset.storage_key
-
-    console.log(
-      `[buildPlaybackSegments] 片段 ${i}: assetId=${asset.id}, videoUrl=${videoUrl?.substring(0, 80)}, file_url=${!!asset.file_url}`,
-    )
-
     segments.push({
       assetId: asset.id,
-      videoUrl,
+      videoUrl: asset.file_url || asset.storage_key,
       startTime,
       endTime,
       order: i,
@@ -76,10 +67,10 @@ function buildPlaybackSegments(
 const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
   assets,
   template,
-  videoRatio: _videoRatio,
+  videoRatio,
   ready,
-  voiceAudioUrl,
 }) => {
+  // 构建播放片段
   const segments = useMemo(() => buildPlaybackSegments(assets, template), [assets, template])
 
   const {
@@ -87,83 +78,13 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
     currentTime,
     totalDuration,
     currentSegmentIndex,
+    isEnded,
     canPlay,
     togglePlayPause,
     seekTo,
     videoRef,
   } = useSegmentScheduler(segments)
 
-  // ── 配音音频同步 ──
-  const audioRef = useRef<HTMLAudioElement | null>(null)
-  const prevIsPlayingRef = useRef(false)
-
-  // 创建/更新 Audio 元素
-  useEffect(() => {
-    if (!voiceAudioUrl) {
-      // 没有配音，清理已有 audio
-      if (audioRef.current) {
-        audioRef.current.pause()
-        audioRef.current.src = ""
-        audioRef.current = null
-      }
-      return
-    }
-
-    if (!audioRef.current) {
-      audioRef.current = new Audio()
-      audioRef.current.preload = "auto"
-    }
-    if (audioRef.current.src !== voiceAudioUrl) {
-      audioRef.current.src = voiceAudioUrl
-    }
-  }, [voiceAudioUrl])
-
-  // 同步播放状态
-  useEffect(() => {
-    const audio = audioRef.current
-    if (!audio || !audio.src) return
-
-    if (isPlaying && !prevIsPlayingRef.current) {
-      // 刚进入播放
-      audio.currentTime = currentTime
-      audio.play().catch(() => {})
-    } else if (!isPlaying && prevIsPlayingRef.current) {
-      // 刚暂停
-      audio.pause()
-    }
-    prevIsPlayingRef.current = isPlaying
-  }, [isPlaying, currentTime])
-
-  // seek 时同步音频
-  const handleSeekTo = useCallback(
-    (time: number) => {
-      seekTo(time)
-      const audio = audioRef.current
-      if (audio && audio.src) {
-        audio.currentTime = time
-      }
-    },
-    [seekTo],
-  )
-
-  // 播放结束时暂停音频
-  useEffect(() => {
-    if (!isPlaying) {
-      const audio = audioRef.current
-      if (audio) audio.pause()
-    }
-  }, [isPlaying])
-
-  // 清理
-  useEffect(() => {
-    return () => {
-      if (audioRef.current) {
-        audioRef.current.pause()
-        audioRef.current.src = ""
-      }
-    }
-  }, [])
-
   // 进度条拖拽
   const [isDragging, setIsDragging] = useState(false)
   const progressRef = useRef<HTMLDivElement>(null)
@@ -173,9 +94,9 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
       if (!progressRef.current || totalDuration <= 0) return
       const rect = progressRef.current.getBoundingClientRect()
       const ratio = Math.max(0, Math.min(1, (e.clientX - rect.left) / rect.width))
-      handleSeekTo(ratio * totalDuration)
+      seekTo(ratio * totalDuration)
     },
-    [totalDuration, handleSeekTo],
+    [totalDuration, seekTo],
   )
 
   const handleMouseDown = useCallback(
@@ -192,7 +113,7 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
       if (!progressRef.current || totalDuration <= 0) return
       const rect = progressRef.current.getBoundingClientRect()
       const ratio = Math.max(0, Math.min(1, (e.clientX - rect.left) / rect.width))
-      handleSeekTo(ratio * totalDuration)
+      seekTo(ratio * totalDuration)
     }
     const handleMouseUp = () => setIsDragging(false)
     window.addEventListener("mousemove", handleMouseMove)
@@ -201,25 +122,15 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
       window.removeEventListener("mousemove", handleMouseMove)
       window.removeEventListener("mouseup", handleMouseUp)
     }
-  }, [isDragging, totalDuration, handleSeekTo])
+  }, [isDragging, totalDuration, seekTo])
 
+  const videoAspectStyle = { aspectRatio: (videoRatio || "16:9").replace(":", "/") }
   const progressPercent = totalDuration > 0 ? (currentTime / totalDuration) * 100 : 0
 
   // 未就绪状态
   if (!ready || !assets.length) {
     return (
-      <div
-        className="xx-preview-empty"
-        style={{
-          position: "absolute",
-          inset: 0,
-          display: "flex",
-          flexDirection: "column",
-          alignItems: "center",
-          justifyContent: "center",
-          zIndex: 1,
-        }}
-      >
+      <div className="xx-preview-empty">
         <SoundOutlined style={{ fontSize: 48, color: "var(--text-tertiary)", marginBottom: 12 }} />
         <p className="xx-preview-empty-title">准备预览素材...</p>
         <p className="xx-preview-empty-desc">加载素材后即可预览播放</p>
@@ -230,18 +141,7 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
   // 无播放片段
   if (!canPlay) {
     return (
-      <div
-        className="xx-preview-empty"
-        style={{
-          position: "absolute",
-          inset: 0,
-          display: "flex",
-          flexDirection: "column",
-          alignItems: "center",
-          justifyContent: "center",
-          zIndex: 1,
-        }}
-      >
+      <div className="xx-preview-empty">
         <PlayCircleOutlined
           style={{ fontSize: 48, color: "var(--text-tertiary)", marginBottom: 12 }}
         />
@@ -252,85 +152,76 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
   }
 
   return (
-    <>
-      {/* ✅ 不再创建 .xx-preview-video 容器，直接渲染 video + 覆盖层 */}
-      {/* video 元素 — 由父组件 .xx-preview-video 容器提供定位和尺寸 */}
-      <video
-        muted
-        ref={videoRef}
-        preload="auto"
-        style={{
-          position: "absolute",
-          inset: 0,
-          width: "100%",
-          height: "100%",
-          objectFit: "contain",
-          background: "#000",
-          zIndex: 1,
-        }}
-        playsInline
-      />
+    <div className="xx-frontend-preview-player">
+      {/* 视频区域 */}
+      <div className="xx-preview-video" style={{ ...videoAspectStyle, position: "relative" }}>
+        <video
+          ref={videoRef}
+          preload="auto"
+          style={{
+            width: "100%",
+            height: "100%",
+            objectFit: "contain",
+            background: "#000",
+          }}
+          playsInline
+        />
 
-      {/* 播放按钮覆盖层 */}
-      {!isPlaying && (
-        <button
-          className="xx-preview-play-btn"
-          onClick={togglePlayPause}
+        {/* 播放/暂停按钮覆盖 */}
+        {!isPlaying && (
+          <button
+            className="xx-preview-play-btn"
+            onClick={togglePlayPause}
+            style={{
+              position: "absolute",
+              top: "50%",
+              left: "50%",
+              transform: "translate(-50%, -50%)",
+              background: "rgba(0,0,0,0.5)",
+              border: "none",
+              borderRadius: "50%",
+              width: 56,
+              height: 56,
+              cursor: "pointer",
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              color: "#fff",
+              fontSize: 28,
+              zIndex: 10,
+              transition: "opacity 0.2s",
+            }}
+          >
+            {isEnded ? <PlayCircleOutlined /> : <PlayCircleOutlined />}
+          </button>
+        )}
+
+        {/* 当前片段指示器 */}
+        <div
           style={{
             position: "absolute",
-            top: "50%",
-            left: "50%",
-            transform: "translate(-50%, -50%)",
-            background: "rgba(0,0,0,0.5)",
-            border: "none",
-            borderRadius: "50%",
-            width: 56,
-            height: 56,
-            cursor: "pointer",
-            display: "flex",
-            alignItems: "center",
-            justifyContent: "center",
+            top: 8,
+            left: 8,
+            background: "rgba(0,0,0,0.6)",
             color: "#fff",
-            fontSize: 28,
+            fontSize: 11,
+            padding: "2px 8px",
+            borderRadius: 4,
             zIndex: 10,
-            transition: "opacity 0.2s",
           }}
         >
-          <PlayCircleOutlined />
-        </button>
-      )}
-
-      {/* 片段指示器 */}
-      <div
-        style={{
-          position: "absolute",
-          top: 8,
-          left: 8,
-          background: "rgba(0,0,0,0.6)",
-          color: "#fff",
-          fontSize: 11,
-          padding: "2px 8px",
-          borderRadius: 4,
-          zIndex: 10,
-        }}
-      >
-        片段 {currentSegmentIndex + 1}/{segments.length}
+          片段 {currentSegmentIndex + 1}/{segments.length}
+        </div>
       </div>
 
-      {/* 控制条 — 绝对定位在底部 */}
+      {/* 控制条 */}
       <div
         className="xx-preview-controls"
         style={{
-          position: "absolute",
-          bottom: 0,
-          left: 0,
-          right: 0,
           display: "flex",
           alignItems: "center",
           gap: 8,
-          padding: "8px 12px",
-          background: "linear-gradient(transparent, rgba(0,0,0,0.6))",
-          zIndex: 10,
+          padding: "8px 0",
         }}
       >
         {/* 播放/暂停 */}
@@ -339,7 +230,7 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
           style={{
             background: "none",
             border: "none",
-            color: "#fff",
+            color: "var(--text-primary, #fff)",
             fontSize: 18,
             cursor: "pointer",
             padding: 4,
@@ -354,7 +245,7 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
         <span
           style={{
             fontSize: 12,
-            color: "rgba(255,255,255,0.8)",
+            color: "var(--text-secondary, #999)",
             minWidth: 80,
             fontVariantNumeric: "tabular-nums",
           }}
@@ -384,6 +275,7 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
               transition: isDragging ? "none" : "width 0.1s linear",
             }}
           />
+          {/* 进度指示点 */}
           <div
             style={{
               position: "absolute",
@@ -401,7 +293,7 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
           />
         </div>
       </div>
-    </>
+    </div>
   )
 }
 

apps/web/src/pages/generate/components/PreviewVideoPanel.tsx

@@ -6,10 +6,6 @@
  * 架构改造：完全去除后端 FFmpeg 预览依赖
  * - 使用 FrontendPreviewPlayer 直接播放素材片段
  * - TitleOverlay CSS 层实时响应标题样式变化
- *
- * 布局：本组件提供 .xx-preview-video 容器（position: relative + overflow: hidden）
- * FrontendPreviewPlayer 的内容通过 absolute 定位填充容器
- * TitleOverlay 通过 absolute 定位 + z-index: 30 覆盖在最上层
  */
 import React, { useMemo } from "react"
 import { LoadingOutlined } from "@ant-design/icons"
@@ -31,8 +27,6 @@ interface PreviewVideoPanelProps {
   assetsLoading: boolean
   /** 标题设置 — 用于 CSS 实时预览层 */
   titleSettings?: TitleSettings
-  /** 配音音频 URL */
-  voiceAudioUrl?: string
 }
 
 /* ── ASS 坐标系参数（与后端 ass_subtitle_builder.py 一致） ── */
@@ -109,8 +103,6 @@ function buildTitleStyle(settings: TitleSettings): React.CSSProperties {
 
 /**
  * CSS 标题预览覆盖层
- * 始终渲染：有标题显示标题，无标题显示占位文本"标题预览"
- * z-index: 20（在视频 z-index:1 和控制条 z-index:10 之上）
  */
 const TitleOverlay: React.FC<{ titleSettings: TitleSettings }> = ({ titleSettings }) => {
   const positionStyle = useMemo(
@@ -132,17 +124,16 @@ const TitleOverlay: React.FC<{ titleSettings: TitleSettings }> = ({ titleSetting
     ],
   )
 
-  // 标题为空时显示占位文本
-  const displayTitle = titleSettings.title?.trim() || "标题预览"
+  if (!titleSettings.title?.trim()) return null
 
   return (
     <div
+      className="xx-preview-title-overlay"
       style={{
         position: "absolute",
         inset: 0,
         zIndex: 20,
         pointerEvents: "none",
-        overflow: "hidden",
       }}
     >
       <div
@@ -152,7 +143,7 @@ const TitleOverlay: React.FC<{ titleSettings: TitleSettings }> = ({ titleSetting
           position: "absolute",
         }}
       >
-        {displayTitle}
+        {titleSettings.title}
       </div>
     </div>
   )
@@ -167,7 +158,6 @@ export const PreviewVideoPanel: React.FC<PreviewVideoPanelProps> = ({
   assetsReady,
   assetsLoading,
   titleSettings,
-  voiceAudioUrl,
 }) => {
   const videoAspectStyle = { aspectRatio: (videoRatio || "16:9").replace(":", "/") }
 
@@ -178,42 +168,33 @@ export const PreviewVideoPanel: React.FC<PreviewVideoPanelProps> = ({
         {assetsReady && assets.length > 0 && <span className="xx-preview-badge">实时预览</span>}
       </div>
 
-      {/* ✅ 预览容器 — 唯一的 .xx-preview-video 容器
-          内部所有内容（视频、控制条、标题叠加层）通过 absolute 定位填充 */}
-      <div className="xx-preview-video" style={{ ...videoAspectStyle, position: "relative" }}>
-        {/* 加载中状态 */}
-        {assetsLoading && (
-          <div
-            className="xx-preview-loading-center"
-            style={{
-              position: "absolute",
-              inset: 0,
-              display: "flex",
-              flexDirection: "column",
-              alignItems: "center",
-              justifyContent: "center",
-              zIndex: 5,
-            }}
-          >
-            <LoadingOutlined style={{ fontSize: 36, color: "#fff" }} spin />
-            <p style={{ marginTop: 12, color: "rgba(255,255,255,0.8)", fontSize: 14 }}>
-              加载素材中...
-            </p>
+      {/* 加载中 */}
+      {assetsLoading && (
+        <div className="xx-preview-loading-panel">
+          <div className="xx-preview-video" style={videoAspectStyle}>
+            <div className="xx-preview-loading-center">
+              <LoadingOutlined style={{ fontSize: 36, color: "#fff" }} spin />
+              <p style={{ marginTop: 12, color: "rgba(255,255,255,0.8)", fontSize: 14 }}>
+                加载素材中...
+              </p>
+            </div>
           </div>
-        )}
+        </div>
+      )}
 
-        {/* 前端播放器（视频 + 控制条 + 播放按钮）*/}
-        <FrontendPreviewPlayer
-          assets={assets}
-          template={template}
-          videoRatio={videoRatio}
-          ready={assetsReady}
-          voiceAudioUrl={voiceAudioUrl}
-        />
-
-        {/* CSS 标题实时预览层 — z-index: 20，始终渲染在内容层之上 */}
-        {titleSettings && <TitleOverlay titleSettings={titleSettings} />}
-      </div>
+      {/* 前端预览播放器 + CSS 标题叠加 */}
+      {!assetsLoading && (
+        <div className="xx-preview-video" style={{ ...videoAspectStyle, position: "relative" }}>
+          <FrontendPreviewPlayer
+            assets={assets}
+            template={template}
+            videoRatio={videoRatio}
+            ready={assetsReady}
+          />
+          {/* CSS 标题实时预览层 — 与 FFmpeg ASS 渲染坐标对齐 */}
+          {titleSettings && <TitleOverlay titleSettings={titleSettings} />}
+        </div>
+      )}
 
       {/* 素材信息 */}
       {assetsReady && assets.length > 0 && (

apps/web/src/pages/generate/generate.css

@@ -895,12 +895,13 @@
   max-height: 400px;
   border-radius: var(--radius-md);
   background: linear-gradient(135deg, var(--color-gray-900), var(--color-primary-900));
+  display: grid;
+  place-items: center;
   color: var(--text-inverse);
   font-size: 36px;
   position: relative;
   overflow: hidden;
   margin-bottom: 16px;
-  isolation: isolate;
 }
 
 .xx-preview-video::before {
@@ -909,7 +910,6 @@
   inset: 0;
   background: radial-gradient(circle at 72% 28%, rgba(255, 255, 255, 0.2), transparent 40%);
   pointer-events: none;
-  z-index: 0;
 }
 
 .xx-preview-video video {

apps/web/src/pages/generate/hooks/usePreviewAssets.ts

@@ -1,22 +1,33 @@
 /**
  * 预览素材加载 Hook
- * 根据选中的素材 ID 列表，逐个获取素材详情（含 file_url、duration 等）
+ * 根据选中的素材 ID 列表，批量获取素材详情（含 file_url、duration 等）
  * 供前端预览播放器使用
- *
- * 注意：后端没有批量接口（/assets/batch 返回 405），
- * 因此直接使用 Promise.allSettled 并发请求单个 GET /assets/{id}
  */
 import { useState, useEffect, useCallback, useRef } from "react"
 import type { AssetItem } from "@/api/assets"
 import type { AxiosResponse } from "axios"
 
+/** 批量获取素材详情的 API 路径 */
+const ASSETS_BATCH_URL = "/assets/batch"
+
 /**
- * 通过 ID 列表逐个获取素材（并发）
- * 使用 Promise.allSettled 确保单个失败不影响整体
+ * 通过 ID 列表批量获取素材
+ * 优先使用批量接口，失败则回退为逐个获取
  */
 async function fetchAssetsByIds(ids: string[]): Promise<AssetItem[]> {
   if (!ids.length) return []
 
+  try {
+    // 尝试批量接口
+    const { default: apiClient } = await import("@/api/client")
+    const response = await apiClient.post(ASSETS_BATCH_URL, { ids })
+    const items: AssetItem[] = response.data?.items || response.data || []
+    if (items.length > 0) return items
+  } catch {
+    // 批量接口不存在，回退为逐个获取
+  }
+
+  // 回退：逐个获取
   try {
     const { default: apiClient } = await import("@/api/client")
     const results = await Promise.allSettled(
@@ -53,11 +64,8 @@ export function usePreviewAssets(assetIds: string[], enabled: boolean): UsePrevi
   const [ready, setReady] = useState(false)
   const requestIdRef = useRef(0)
 
-  // 稳定化 assetIds：只有内容真正变化时才更新引用
-  const stableAssetIds = useStableArray(assetIds)
-
   const load = useCallback(async () => {
-    if (!stableAssetIds.length || !enabled) {
+    if (!assetIds.length || !enabled) {
       setAssets([])
       setReady(false)
       return
@@ -68,7 +76,7 @@ export function usePreviewAssets(assetIds: string[], enabled: boolean): UsePrevi
     setReady(false)
 
     try {
-      const result = await fetchAssetsByIds(stableAssetIds)
+      const result = await fetchAssetsByIds(assetIds)
       // 防止竞态：只保留最新请求的结果
       if (requestIdRef.current === thisRequestId) {
         setAssets(result)
@@ -84,7 +92,7 @@ export function usePreviewAssets(assetIds: string[], enabled: boolean): UsePrevi
         setLoading(false)
       }
     }
-  }, [stableAssetIds, enabled])
+  }, [assetIds, enabled])
 
   useEffect(() => {
     load()
@@ -93,22 +101,4 @@ export function usePreviewAssets(assetIds: string[], enabled: boolean): UsePrevi
   return { assets, loading, ready, reload: load }
 }
 
-/**
- * useStableArray — 数组内容稳定化 Hook
- * 只有数组内容真正变化时才返回新的引用，避免父组件 re-render 导致的无效更新
- */
-function useStableArray<T>(array: T[]): T[] {
-  const ref = useRef<T[]>(array)
-
-  // 比较数组内容是否真正变化
-  const hasChanged =
-    array.length !== ref.current.length || array.some((item, index) => item !== ref.current[index])
-
-  if (hasChanged) {
-    ref.current = array
-  }
-
-  return ref.current
-}
-
 export default usePreviewAssets

apps/web/src/pages/generate/hooks/useSegmentScheduler.ts

@@ -91,10 +91,6 @@ export function useSegmentScheduler(segments: PlaybackSegment[]): SegmentSchedul
   const rafRef = useRef<number>(0)
   const isSeekingRef = useRef(false)
 
-  // ✅ 关键修复：用 ref 标记是否已加载过片段（替代检查 video.src）
-  // video.src = "" 在浏览器中会被解析为页面 URL，导致 "video.src === ''" 永远为 false
-  const srcLoadedRef = useRef(false)
-
   // 预加载用的隐藏 video 元素
   const preloadVideoRef = useRef<HTMLVideoElement | null>(null)
 
@@ -113,115 +109,34 @@ export function useSegmentScheduler(segments: PlaybackSegment[]): SegmentSchedul
     ? currentTime - (timelineStarts[currentSegmentIndex] || 0) + currentSegment.startTime
     : 0
 
-  /** 切换到指定片段，返回 Promise 在视频可播放后 resolve */
+  /** 切换到指定片段 */
   const switchToSegment = useCallback(
-    (index: number, seekToLocalTime?: number): Promise<void> => {
-      return new Promise((resolve) => {
-        const video = videoRef.current
-        if (!video || index >= segments.length) {
-          resolve()
-          return
+    (index: number, seekToLocalTime?: number) => {
+      const video = videoRef.current
+      if (!video || index >= segments.length) return
+
+      const seg = segments[index]
+      video.src = seg.videoUrl
+
+      const localTime = seekToLocalTime ?? seg.startTime
+      // 等待 src 设置后再设置 currentTime
+      const onLoaded = () => {
+        video.currentTime = localTime
+        video.removeEventListener("loadedmetadata", onLoaded)
+      }
+      video.addEventListener("loadedmetadata", onLoaded)
+
+      setCurrentSegmentIndex(index)
+
+      // 预加载下一段
+      if (index + 1 < segments.length) {
+        const nextSeg = segments[index + 1]
+        if (!preloadVideoRef.current) {
+          preloadVideoRef.current = document.createElement("video")
+          preloadVideoRef.current.preload = "auto"
         }
-
-        const seg = segments[index]
-        const videoUrl = seg.videoUrl
-
-        if (!videoUrl || videoUrl === "") {
-          console.error(
-            `[useSegmentScheduler] 片段 ${index} 的 videoUrl 为空！assetId: ${seg.assetId}`,
-          )
-          resolve()
-          return
-        }
-
-        // 检查是否是完整的 HTTP URL
-        if (!videoUrl.startsWith("http://") && !videoUrl.startsWith("https://")) {
-          console.warn(`[useSegmentScheduler] 片段 ${index} 的 videoUrl 不是完整 URL: ${videoUrl}`)
-        }
-
-        const localTime = seekToLocalTime ?? seg.startTime
-
-        // ✅ 关键修复：清除旧事件监听，防止重复绑定
-        const cleanup = () => {
-          video.removeEventListener("loadedmetadata", onLoaded)
-          video.removeEventListener("error", onError)
-          video.removeEventListener("canplay", onCanPlay)
-          clearTimeout(timeoutId)
-        }
-
-        const onLoaded = () => {
-          video.currentTime = localTime
-          srcLoadedRef.current = true
-          cleanup()
-          console.log(
-            `[useSegmentScheduler] 片段 ${index} loadedmetadata, src=${videoUrl.substring(0, 80)}`,
-          )
-          resolve()
-        }
-
-        const onCanPlay = () => {
-          video.currentTime = localTime
-          srcLoadedRef.current = true
-          cleanup()
-          console.log(
-            `[useSegmentScheduler] 片段 ${index} canplay, src=${videoUrl.substring(0, 80)}`,
-          )
-          resolve()
-        }
-
-        const onError = () => {
-          console.error(
-            `[useSegmentScheduler] 视频加载失败: ${videoUrl}`,
-            video.error?.message || `code=${video.error?.code}`,
-          )
-          srcLoadedRef.current = true // 标记为已尝试，避免死循环
-          cleanup()
-          resolve()
-        }
-
-        // ✅ 关键修复：10秒超时防止 Promise 永远不 resolve
-        const timeoutId = setTimeout(() => {
-          console.warn(
-            `[useSegmentScheduler] 片段 ${index} 加载超时 (10s), readyState=${video.readyState}`,
-          )
-          cleanup()
-          resolve()
-        }, 10000)
-
-        // 先绑定事件，再设置 src（避免错过已触发的loadedmetadata）
-        video.addEventListener("loadedmetadata", onLoaded)
-        video.addEventListener("canplay", onCanPlay)
-        video.addEventListener("error", onError)
-
-        // 设置 src 并显式调用 load()
-        video.src = videoUrl
-        video.load()
-
-        // ✅ 关键修复：如果 readyState >= 1（已有 metadata），说明加载已完成
-        // 直接设置 currentTime 并 resolve，不等待事件
-        if (video.readyState >= 1) {
-          video.currentTime = localTime
-          srcLoadedRef.current = true
-          cleanup()
-          console.log(
-            `[useSegmentScheduler] 片段 ${index} 已缓存(readyState=${video.readyState}), 直接播放`,
-          )
-          resolve()
-          return
-        }
-
-        setCurrentSegmentIndex(index)
-
-        // 预加载下一段
-        if (index + 1 < segments.length) {
-          const nextSeg = segments[index + 1]
-          if (!preloadVideoRef.current) {
-            preloadVideoRef.current = document.createElement("video")
-            preloadVideoRef.current.preload = "auto"
-          }
-          preloadVideoRef.current.src = nextSeg.videoUrl
-        }
-      })
+        preloadVideoRef.current.src = nextSeg.videoUrl
+      }
     },
     [segments],
   )
@@ -237,35 +152,17 @@ export function useSegmentScheduler(segments: PlaybackSegment[]): SegmentSchedul
     const seg = segments[currentSegmentIndex]
     if (!seg) return
 
-    // 提前 2 秒预加载下一段
-    if (currentSegmentIndex + 1 < segments.length) {
-      const nextSeg = segments[currentSegmentIndex + 1]
-      if (!preloadVideoRef.current) {
-        preloadVideoRef.current = document.createElement("video")
-        preloadVideoRef.current.preload = "auto"
-      }
-      if (preloadVideoRef.current.src !== nextSeg.videoUrl) {
-        preloadVideoRef.current.src = nextSeg.videoUrl
-        preloadVideoRef.current.load()
-      }
-    }
-
     // 检查是否到达出点（容差 0.15s）
     if (video.currentTime >= seg.endTime - 0.15) {
       const nextIndex = currentSegmentIndex + 1
       if (nextIndex < segments.length) {
-        switchToSegment(nextIndex).then(() => {
-          const v = videoRef.current
-          if (v) {
-            v.play().catch((e) =>
-              console.warn("[useSegmentScheduler] auto-play next segment failed:", e),
-            )
-          }
-        })
+        // 切到下一段
+        switchToSegment(nextIndex)
         const accumulatedTime =
           (timelineStarts[currentSegmentIndex] || 0) + (seg.endTime - seg.startTime)
         setCurrentTime(accumulatedTime)
       } else {
+        // 播放结束
         video.pause()
         setIsPlaying(false)
         setIsEnded(true)
@@ -273,6 +170,7 @@ export function useSegmentScheduler(segments: PlaybackSegment[]): SegmentSchedul
         return
       }
     } else {
+      // 更新全局时间
       const globalTime =
         (timelineStarts[currentSegmentIndex] || 0) + (video.currentTime - seg.startTime)
       setCurrentTime(Math.max(0, Math.min(globalTime, totalDuration)))
@@ -284,41 +182,22 @@ export function useSegmentScheduler(segments: PlaybackSegment[]): SegmentSchedul
   /** 播放 */
   const play = useCallback(async () => {
     const video = videoRef.current
-    if (!video || !canPlay) {
-      console.log("[useSegmentScheduler] play: video=", !!video, "canPlay=", canPlay)
-      return
-    }
+    if (!video || !canPlay) return
 
     setIsEnded(false)
 
-    // ✅ 关键修复：用 ref 标记代替 video.src 检查
-    if (!srcLoadedRef.current) {
-      console.log("[useSegmentScheduler] 首次播放，加载片段 0...")
-      await switchToSegment(0)
+    // 如果还没设置 src（首次播放），先加载第一段
+    if (!video.src || video.src === "") {
+      switchToSegment(0)
     }
 
     try {
-      const playPromise = video.play()
-      if (playPromise !== undefined) {
-        await playPromise
-      }
-      console.log("[useSegmentScheduler] 播放开始, src=", video.src?.substring(0, 80))
+      await video.play()
       setIsPlaying(true)
       rafRef.current = requestAnimationFrame(tick)
-    } catch (err) {
-      console.warn("[useSegmentScheduler] 播放失败:", err, "src=", video.src?.substring(0, 80))
-      // 如果播放失败，尝试重新加载片段
-      if (!srcLoadedRef.current) {
-        srcLoadedRef.current = false
-        await switchToSegment(0)
-        try {
-          await video.play()
-          setIsPlaying(true)
-          rafRef.current = requestAnimationFrame(tick)
-        } catch (retryErr) {
-          console.error("[useSegmentScheduler] 重试播放仍然失败:", retryErr)
-        }
-      }
+    } catch {
+      // 自动播放可能被浏览器阻止，忽略
+      console.warn("[useSegmentScheduler] auto-play blocked by browser")
     }
   }, [canPlay, switchToSegment, tick])
 
@@ -338,16 +217,18 @@ export function useSegmentScheduler(segments: PlaybackSegment[]): SegmentSchedul
       if (isEnded) {
         // 播放结束后再次播放，从头开始
         setIsEnded(false)
-        srcLoadedRef.current = false // ✅ 重置标记，强制重新加载
-        switchToSegment(0, segments[0]?.startTime).then(() => {
-          const video = videoRef.current
-          if (video) {
-            video.play().catch((e) => console.warn("[useSegmentScheduler] restart play failed:", e))
+        switchToSegment(0, segments[0]?.startTime)
+        const video = videoRef.current
+        if (video) {
+          const onSeeked = () => {
+            video.play().catch(() => {})
             setIsPlaying(true)
             setCurrentTime(0)
             rafRef.current = requestAnimationFrame(tick)
+            video.removeEventListener("seeked", onSeeked)
           }
-        })
+          video.addEventListener("seeked", onSeeked)
+        }
       } else {
         play()
       }
@@ -356,7 +237,7 @@ export function useSegmentScheduler(segments: PlaybackSegment[]): SegmentSchedul
 
   /** 跳转到指定全局时间 */
   const seekTo = useCallback(
-    async (time: number) => {
+    (time: number) => {
       const video = videoRef.current
       if (!video || !canPlay) return
 
@@ -365,8 +246,11 @@ export function useSegmentScheduler(segments: PlaybackSegment[]): SegmentSchedul
 
       isSeekingRef.current = true
 
+      // 如果片段变了，需要切换 src
       if (index !== currentSegmentIndex) {
-        await switchToSegment(index, localTime)
+        switchToSegment(index, localTime)
+        // switchToSegment 会设置 src 并在 loadedmetadata 后设置 currentTime
+        // 所以这里不需要再设置
       } else {
         video.currentTime = localTime
       }
@@ -375,6 +259,7 @@ export function useSegmentScheduler(segments: PlaybackSegment[]): SegmentSchedul
       setCurrentSegmentIndex(index)
       setIsEnded(false)
 
+      // 延迟恢复 tick 检测
       setTimeout(() => {
         isSeekingRef.current = false
       }, 200)
@@ -400,12 +285,10 @@ export function useSegmentScheduler(segments: PlaybackSegment[]): SegmentSchedul
     setCurrentTime(0)
     setCurrentSegmentIndex(0)
     setIsEnded(false)
-    srcLoadedRef.current = false // ✅ 重置标记
     const video = videoRef.current
     if (video) {
       video.pause()
-      video.removeAttribute("src")
-      video.load()
+      video.src = ""
     }
   }, [segments])
 

infra/docker/api-base.Dockerfile

@@ -1,43 +0,0 @@
-# ============================================================
-# API 基础镜像（预构建）
-# 预装系统依赖 + Python 依赖，业务构建从此镜像开始
-# 当 requirements-base.txt 或 requirements.txt 变更时重新构建
-# 目标：将 API Image 构建时间从 15-20 分钟降至 3-5 分钟
-# ============================================================
-
-FROM git.xiaoxiajianji.com/xiaoxia/base/python:3.12-slim
-
-# 使用阿里云镜像加速
-RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null || \
-    sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true
-
-# 预装系统依赖（gcc 编译 psycopg/pg 扩展，libpq-dev 编译期，libpq5 运行期，ffmpeg 封面取帧）
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    gcc \
-    libpq-dev \
-    libpq5 \
-    ffmpeg \
-    && rm -rf /var/lib/apt/lists/*
-
-# 创建虚拟环境
-RUN python -m venv /opt/venv
-ENV PATH="/opt/venv/bin:$PATH"
-
-WORKDIR /tmp
-
-# 预装 Python 基础依赖
-COPY requirements-base.txt requirements.txt ./
-RUN pip install --no-cache-dir \
-    -i https://mirrors.aliyun.com/pypi/simple/ \
-    --trusted-host mirrors.aliyun.com \
-    -r requirements-base.txt -r requirements.txt
-
-# 虚拟环境瘦身
-RUN find /opt/venv -name "*.so" -type f -exec strip --strip-all {} \; 2>/dev/null || true
-RUN find /opt/venv -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null; \
-    find /opt/venv -name "*.pyc" -delete 2>/dev/null || true
-
-# 清理临时文件
-RUN rm -f /tmp/requirements-base.txt /tmp/requirements.txt
-
-ENV PYTHONPATH=/app

infra/docker/api.Dockerfile

@@ -1,28 +1,81 @@
 # ============================================================
 # API Dockerfile - FastAPI 应用
-# 优化：从预构建基础镜像开始，仅叠加业务代码
-# 基础镜像包含所有系统依赖和 Python 依赖，构建时间 < 5 分钟
+# 优化：多阶段构建 + pip cache mount + 依赖分层缓存
 # ============================================================
 
-FROM xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji/saas-api-base:latest
+# ==================== Builder 阶段 ====================
+FROM git.xiaoxiajianji.com/xiaoxia/base/python:3.12-slim AS builder
+
+# 使用阿里云镜像加速
+RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null || \
+    sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true
+
+# 安装编译依赖（仅 builder 需要）
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# 创建虚拟环境
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+WORKDIR /tmp
+
+# ---- 依赖分层：基础依赖（变化少，缓存命中率高）----
+COPY requirements-base.txt /tmp/requirements-base.txt
+
+RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
+    pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
+    -r /tmp/requirements-base.txt \
+    && rm /tmp/requirements-base.txt
+
+# ---- 依赖分层：业务依赖（变化频繁）----
+COPY requirements.txt /tmp/requirements.txt
+
+RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
+    pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com \
+    -r /tmp/requirements.txt \
+    && rm /tmp/requirements.txt
+
+# ---- Python 依赖瘦身 ----
+RUN find /opt/venv -name "*.so" -type f -exec strip --strip-all {} \; 2>/dev/null || true
+RUN find /opt/venv -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null; \
+    find /opt/venv -name "*.pyc" -delete 2>/dev/null || true
+
+# ==================== Runtime 阶段 ====================
+FROM git.xiaoxiajianji.com/xiaoxia/base/python:3.12-slim AS runtime
 
 # 构建参数：版本号（CI 传入 commit hash）
 ARG APP_VERSION=dev
 
+# 使用阿里云镜像加速
+RUN sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources 2>/dev/null || \
+    sed -i 's|deb.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list 2>/dev/null || true
+
+# 只装运行时需要的库（libpq5 是 psycopg2 运行时依赖，ffmpeg 用于封面兜底取帧）
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpq5 \
+    ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+# 从 builder 复制虚拟环境
+COPY --from=builder /opt/venv /opt/venv
+
 # 设置工作目录
 WORKDIR /app
 
-# 复制应用代码（按变化频率从低到高排序，最大化层缓存命中）
-COPY alembic.ini ./alembic.ini
-COPY migrations/ ./migrations/
-COPY alembic/ ./alembic/
-COPY scripts/ ./scripts/
-COPY packages/ ./packages/
-COPY apps/api/ ./apps/api/
+# 复制应用代码
+COPY apps/api/ /app/apps/api/
+COPY packages/ /app/packages/
+COPY alembic.ini /app/alembic.ini
+COPY migrations/ /app/migrations/
+COPY alembic/ /app/alembic/
+COPY scripts/ /app/scripts/
 
 # 设置环境变量
 ENV PATH="/opt/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
-ENV PYTHONPATH=/app:/app/apps/api
+ENV PYTHONPATH=/app
 ENV PYTHONUNBUFFERED=1
 ENV APP_VERSION=$APP_VERSION
 
@@ -31,4 +84,5 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
     CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=5)"
 
 # API 入口点
-CMD ["uvicorn", "apps.api.main:app", "--host", "0.0.0.0", "--port", "8000"]
+WORKDIR /app/apps/api
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

requirements-base.txt

@@ -2,6 +2,7 @@
 # 修改此文件会触发完整重新构建，请谨慎修改
 
 # 数据库（基础层）
+psycopg2-binary==2.9.9
 psycopg[binary]==3.2.2
 sqlalchemy==2.0.35
 alembic==1.13.3

scripts/ci/docker_build_push.sh

@@ -3,9 +3,6 @@
 # 用法: docker_build_push.sh [--no-cache] <Dockerfile> <image_tag> <cache_ref> [build_arg...]
 set -eu
 
-# 单次 build 超时时间（秒），防止 docker buildx build 无限挂起
-BUILD_TIMEOUT=1500
-
 NO_CACHE_FLAG=""
 if [ "$1" = "--no-cache" ]; then
   NO_CACHE_FLAG="--no-cache"
@@ -46,7 +43,7 @@ build_with_cache_retry() {
     local build_output
     local exit_code
     set +e
-    build_output=$(timeout ${BUILD_TIMEOUT} docker buildx build \
+    build_output=$(docker buildx build \
       $NO_CACHE_FLAG \
       $BUILD_ARGS \
       --cache-from "type=local,src=${LOCAL_CACHE_DIR}" \
@@ -63,12 +60,6 @@ build_with_cache_retry() {
       echo "$build_output"
       return 0
     fi
-    # 超时退出（exit code 124）
-    if [ $exit_code -eq 124 ]; then
-      echo "❌ Docker build TIMEOUT after ${BUILD_TIMEOUT}s - build hung and was killed"
-      echo "$build_output" | tail -20
-      return $exit_code
-    fi
     # 检测到缓存损坏类错误，清掉本地缓存重试
     if echo "$build_output" | grep -qE "parent snapshot.*not found|snapshot.*does not exist|cache.*corrupt|failed to compute cache key"; then
       echo "$build_output"
@@ -77,7 +68,7 @@ build_with_cache_retry() {
       rm -rf "${LOCAL_CACHE_DIR}"
       mkdir -p "${LOCAL_CACHE_DIR}"
       # 清理buildx builder的内部snapshot状态
-      docker buildx prune -f -a > /dev/null 2>&1 || true
+      docker buildx prune -f -a >/dev/null 2>&1 || true
       attempt=$((attempt + 1))
     else
       # 非缓存类错误，直接输出并返回
@@ -87,7 +78,7 @@ build_with_cache_retry() {
   done
   # 重试完还是失败，不用本地缓存最后试一次（只从registry读）
   echo "⚠️  All cached attempts failed, building without local cache..."
-  timeout ${BUILD_TIMEOUT} docker buildx build \
+  docker buildx build \
     $NO_CACHE_FLAG \
     $BUILD_ARGS \
     --cache-from "type=registry,ref=${CACHE_REF}" \
@@ -102,7 +93,6 @@ build_with_cache_retry() {
 echo "=== Step 1: Build & push image (local cache + registry cache, with auto-repair) ==="
 echo "Local cache: ${LOCAL_CACHE_DIR}"
 echo "Registry cache: ${CACHE_REF}"
-echo "Build timeout: ${BUILD_TIMEOUT}s"
 echo ""
 
 build_with_cache_retry

scripts/ci/rebuild-api-base-image.sh

@@ -1,40 +0,0 @@
-#!/bin/bash
-# ============================================================
-# 重建 API 基础镜像脚本
-# 用途：当 requirements-base.txt 或 requirements.txt 变更时手动触发
-# 前提：需要在已登录 ACR 的构建服务器上执行
-# ============================================================
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-
-REGISTRY="xiaoxia-registry.cn-hangzhou.cr.aliyuncs.com/xiaoxiakeji"
-IMAGE_NAME="saas-api-base"
-TAG="latest"
-FULL_TAG="${REGISTRY}/${IMAGE_NAME}:${TAG}"
-
-echo "========================================="
-echo "🔨 Rebuilding API base image"
-echo "   Registry: ${REGISTRY}"
-echo "   Image:    ${FULL_TAG}"
-echo "   Context:  ${REPO_ROOT}"
-echo "========================================="
-
-cd "$REPO_ROOT"
-
-# 构建并推送
-docker buildx build \
-    --platform linux/amd64 \
-    --tag "${FULL_TAG}" \
-    --push \
-    -f infra/docker/api-base.Dockerfile \
-    .
-
-echo ""
-echo "✅ API base image pushed: ${FULL_TAG}"
-
-# 显示镜像大小
-docker pull "${FULL_TAG}" > /dev/null 2>&1
-docker images "${FULL_TAG}" --format "table {{.Repository}}:{{.Tag}}\t{{.Size}}"

tests/unit/test_health_routes.py

@@ -1,186 +0,0 @@
-"""Unit tests for apps/api/app/api/routes/health.py
-
-覆盖 _check_database() 和 _check_migrations() 中 psycopg3 连接逻辑。
-确保增量覆盖率 ≥ 60%（目标覆盖 lines 52, 127）。
-"""
-
-from unittest.mock import AsyncMock, MagicMock, patch
-
-import pytest
-
-
-@pytest.mark.asyncio
-class TestCheckDatabase:
-    """Tests for _check_database() health check function."""
-
-    @patch("apps.api.app.api.routes.health.settings")
-    @patch("apps.api.app.api.routes.health.psycopg.connect")
-    async def test_check_database_success(self, mock_connect, mock_settings):
-        """PostgreSQL 连接成功时返回 healthy。"""
-        mock_settings.USE_IN_MEMORY_DB = False
-        mock_settings.DATABASE_URL = "postgresql+psycopg://test:test@localhost/test"
-
-        # Mock connection and cursor
-        mock_conn = MagicMock()
-        mock_cursor = MagicMock()
-        mock_cursor.__enter__ = MagicMock(return_value=mock_cursor)
-        mock_cursor.__exit__ = MagicMock(return_value=False)
-        mock_cursor.fetchone.return_value = (1,)
-        mock_conn.cursor.return_value = mock_cursor
-        mock_connect.return_value = mock_conn
-
-        from apps.api.app.api.routes.health import _check_database
-
-        result = await _check_database()
-
-        assert result["status"] == "healthy"
-        assert result["type"] == "postgresql"
-        assert result["message"] == "Database connection successful"
-        mock_connect.assert_called_once_with(
-            "postgresql+psycopg://test:test@localhost/test", connect_timeout=3
-        )
-        mock_cursor.execute.assert_called_once_with("SELECT 1")
-        mock_conn.close.assert_called_once()
-
-    @patch("apps.api.app.api.routes.health.settings")
-    @patch("apps.api.app.api.routes.health.psycopg.connect")
-    async def test_check_database_connection_failure(self, mock_connect, mock_settings):
-        """PostgreSQL 连接失败时返回 unhealthy。"""
-        mock_settings.USE_IN_MEMORY_DB = False
-        mock_settings.DATABASE_URL = "postgresql+psycopg://test:test@localhost/test"
-        mock_connect.side_effect = Exception("connection refused")
-
-        from apps.api.app.api.routes.health import _check_database
-
-        result = await _check_database()
-
-        assert result["status"] == "unhealthy"
-        assert result["type"] == "postgresql"
-        assert "connection refused" in result["message"]
-
-    @patch("apps.api.app.api.routes.health.settings")
-    async def test_check_database_in_memory(self, mock_settings):
-        """使用内存数据库时跳过 PostgreSQL 检查。"""
-        mock_settings.USE_IN_MEMORY_DB = True
-
-        from apps.api.app.api.routes.health import _check_database
-
-        result = await _check_database()
-
-        assert result["status"] == "healthy"
-        assert result["type"] == "in_memory"
-
-
-@pytest.mark.asyncio
-class TestCheckMigrations:
-    """Tests for _check_migrations() health check function."""
-
-    @patch("apps.api.app.api.routes.health.settings")
-    @patch("apps.api.app.api.routes.health.psycopg.connect")
-    async def test_check_migrations_success(self, mock_connect, mock_settings):
-        """所有迁移表存在时返回 healthy。"""
-        mock_settings.USE_IN_MEMORY_DB = False
-        mock_settings.DATABASE_URL = "postgresql+psycopg://test:test@localhost/test"
-
-        mock_conn = MagicMock()
-        mock_cursor = MagicMock()
-        mock_cursor.__enter__ = MagicMock(return_value=mock_cursor)
-        mock_cursor.__exit__ = MagicMock(return_value=False)
-        mock_cursor.fetchone.return_value = (5,)  # 5 tables found
-        mock_conn.cursor.return_value = mock_cursor
-        mock_connect.return_value = mock_conn
-
-        from apps.api.app.api.routes.health import _check_migrations
-
-        result = await _check_migrations()
-
-        assert result["status"] == "healthy"
-        assert result["message"] == "Database migrations applied"
-        mock_connect.assert_called_once_with(
-            "postgresql+psycopg://test:test@localhost/test", connect_timeout=3
-        )
-        mock_conn.close.assert_called_once()
-
-    @patch("apps.api.app.api.routes.health.settings")
-    @patch("apps.api.app.api.routes.health.psycopg.connect")
-    async def test_check_migrations_missing_tables(self, mock_connect, mock_settings):
-        """迁移表不完整时返回 unhealthy。"""
-        mock_settings.USE_IN_MEMORY_DB = False
-        mock_settings.DATABASE_URL = "postgresql+psycopg://test:test@localhost/test"
-
-        mock_conn = MagicMock()
-        mock_cursor = MagicMock()
-        mock_cursor.__enter__ = MagicMock(return_value=mock_cursor)
-        mock_cursor.__exit__ = MagicMock(return_value=False)
-        mock_cursor.fetchone.return_value = (2,)  # Only 2 of 5 tables
-        mock_conn.cursor.return_value = mock_cursor
-        mock_connect.return_value = mock_conn
-
-        from apps.api.app.api.routes.health import _check_migrations
-
-        result = await _check_migrations()
-
-        assert result["status"] == "unhealthy"
-        assert "Missing tables" in result["message"]
-        assert "2/5" in result["message"]
-
-    @patch("apps.api.app.api.routes.health.settings")
-    @patch("apps.api.app.api.routes.health.psycopg.connect")
-    async def test_check_migrations_connection_failure(self, mock_connect, mock_settings):
-        """数据库连接失败时返回 unhealthy。"""
-        mock_settings.USE_IN_MEMORY_DB = False
-        mock_settings.DATABASE_URL = "postgresql+psycopg://test:test@localhost/test"
-        mock_connect.side_effect = Exception("connection refused")
-
-        from apps.api.app.api.routes.health import _check_migrations
-
-        result = await _check_migrations()
-
-        assert result["status"] == "unhealthy"
-        assert "Migration check failed" in result["message"]
-
-    @patch("apps.api.app.api.routes.health.settings")
-    async def test_check_migrations_in_memory(self, mock_settings):
-        """使用内存数据库时跳过迁移检查。"""
-        mock_settings.USE_IN_MEMORY_DB = True
-
-        from apps.api.app.api.routes.health import _check_migrations
-
-        result = await _check_migrations()
-
-        assert result["status"] == "healthy"
-        assert "no migrations needed" in result["message"]
-
-
-@pytest.mark.asyncio
-class TestStartupCheck:
-    """Tests for startup_check() endpoint."""
-
-    @patch("apps.api.app.api.routes.health._check_migrations")
-    @patch("apps.api.app.api.routes.health._check_database")
-    async def test_startup_all_healthy(self, mock_db, mock_mig):
-        """所有检查通过时返回 started。"""
-        mock_db.return_value = {"status": "healthy"}
-        mock_mig.return_value = {"status": "healthy"}
-
-        from apps.api.app.api.routes.health import startup_check
-
-        result = await startup_check()
-
-        assert result["status"] == "started"
-
-    @patch("apps.api.app.api.routes.health._check_migrations")
-    @patch("apps.api.app.api.routes.health._check_database")
-    async def test_startup_db_unhealthy(self, mock_db, mock_mig):
-        """数据库不健康时返回 starting + 503。"""
-        mock_db.return_value = {"status": "unhealthy", "message": "fail"}
-        mock_mig.return_value = {"status": "healthy"}
-
-        from apps.api.app.api.routes.health import startup_check
-
-        result = await startup_check()
-
-        assert result.status_code == 503
-        import json
-        body = json.loads(result.body)
-        assert body["status"] == "starting"