fix: 修复 useTemplateSave CoverConfig 导入路径

- Extract template list + filtering to useTemplateList.ts
- Extract template detail loading to useTemplateDetail.ts
- Extract plan/draft loading to usePlanLoading.ts
- Extract save modal + payload to useTemplateSave.ts
- Main hook reduced from 466 to 210 lines (-55%)
- Keep import path @/pages/editing-planner/hooks/useTemplateManagement unchanged

apps/web/src/api/assets.ts

@@ -0,0 +1,443 @@
+/**
+ * 素材相关 API
+ * Phase 1 重构：去掉 project_id，素材直接归属用户
+ */
+import apiClient from "./client"
+import { getOrCreateDefaultProject } from "./projects"
+
+/** 素材元数据 */
+export interface AssetMetadata {
+  /** 时长（秒） */
+  duration?: number
+  /** 宽度（像素） */
+  width?: number
+  /** 高度（像素） */
+  height?: number
+  /** 比特率（bps） */
+  bitrate?: number
+  /** 编码格式 */
+  codec?: string
+  /** 帧率 */
+  fps?: number
+  /** 采样率（Hz） */
+  sample_rate?: number
+  /** 声道数 */
+  channels?: number
+  /** 其他扩展字段 */
+  [key: string]: unknown
+}
+
+/** 素材分类状态 */
+export type AssetClassificationStatus = "pending" | "processing" | "completed" | "failed"
+
+/** 素材条目 */
+export interface AssetItem {
+  id: string
+  library_id: string
+  name: string
+  storage_key: string
+  mime_type: string
+  metadata: AssetMetadata
+  file_size?: number
+  file_url?: string
+  thumbnail_url?: string
+  /** 时长（秒），视频/音频素材由后端从 metadata 提取到顶层 */
+  duration?: number
+  status?: string
+  classification_status?: AssetClassificationStatus | null
+  quality_score?: number | null
+  tag_ids?: string[]
+  created_at?: string
+}
+
+/** 素材库 */
+export interface AssetLibraryItem {
+  id: string
+  name: string
+  kind: "video" | "voice" | "image"
+  asset_count?: number
+  total_size?: number
+  created_at?: string
+}
+
+/** 入库任务 */
+export interface IngestJob {
+  id: string
+  library_id: string
+  storage_key: string
+  status: "pending" | "processing" | "completed" | "failed"
+  error_message: string
+  result_asset_id: string
+}
+
+/** 分类任务 */
+export interface ClassificationJob {
+  id: string
+  asset_id: string
+  status: "pending" | "processing" | "completed" | "failed"
+  classification: string
+  confidence: number
+  error_message: string
+}
+
+/** 素材诊断信息 */
+export interface AssetDiagnosis {
+  readiness_score: number
+  readiness_label: string
+  total_assets: number
+  ready_assets: number
+  video_assets: number
+  image_assets: number
+  voice_assets: number
+  total_duration_seconds: number
+  estimated_video_count: number
+  used_assets: number
+  unused_assets: number
+  pending_review_assets: number
+  smart_views: Array<{
+    key: string
+    label: string
+    count: number
+    description: string
+  }>
+  gaps: Array<{
+    key: string
+    severity: "critical" | "warning" | "info"
+    message: string
+    recommendation: string
+  }>
+}
+
+// ─── 素材诊断 ──────────────────────────────────────────────
+
+/** 获取素材诊断信息（可选 asset_id 查单素材，否则全局诊断） */
+export const getAssetDiagnosis = async (assetId?: string): Promise<AssetDiagnosis> => {
+  const params: Record<string, string> = {}
+  if (assetId) params.asset_id = assetId
+  const response = await apiClient.get("/asset-diagnosis", { params })
+  return response.data
+}
+
+// ─── 素材库 ────────────────────────────────────────────────
+
+/** 获取当前用户的所有素材库 */
+export const getAssetLibraries = async (): Promise<AssetLibraryItem[]> => {
+  const response = await apiClient.get("/asset-libraries")
+  return response.data.items || []
+}
+
+/** 创建素材库（自动获取或创建默认项目以提供 project_id） */
+export const createAssetLibrary = async (data: {
+  name: string
+  kind: "video" | "voice" | "image"
+}): Promise<AssetLibraryItem> => {
+  // 后端要求 project_id，前端自动管理默认项目
+  const project = await getOrCreateDefaultProject()
+  const response = await apiClient.post("/asset-libraries", {
+    project_id: project.id,
+    ...data,
+  })
+  return response.data
+}
+
+/** 确保项目下指定 kind 的默认素材库存在（不存在则自动创建） */
+export const ensureDefaultLibrary = async (data: {
+  project_id: string
+  kind: "video" | "voice" | "image"
+}): Promise<AssetLibraryItem> => {
+  const response = await apiClient.post("/asset-libraries/ensure-default", data)
+  return response.data
+}
+
+/** 删除素材库 */
+export const deleteAssetLibrary = async (libraryId: string): Promise<void> => {
+  await apiClient.delete(`/asset-libraries/${libraryId}`)
+}
+
+// ─── 素材 ──────────────────────────────────────────────────
+
+/** 获取素材库下的所有素材 */
+export const getAssets = async (
+  libraryId: string,
+  options?: { status?: string; page?: number; page_size?: number },
+): Promise<{ items: AssetItem[]; total: number }> => {
+  const params: Record<string, string | number> = { library_id: libraryId }
+  // 默认拉取所有非删除状态的素材（ready/ingesting/processing/uploading/error/failed）
+  // 让用户能看到"处理中"的素材，不会以为上传失败了
+  if (options?.status) {
+    params.status = options.status
+  }
+  if (options?.page) params.page = options.page
+  if (options?.page_size) params.page_size = options.page_size
+  const response = await apiClient.get("/assets", { params })
+  const data = response.data || {}
+  const items: AssetItem[] = data.items || []
+  const total: number = typeof data.total === "number" ? data.total : items.length
+  return { items, total }
+}
+
+/** 按类型获取素材（如 voice/video/image），支持可选筛选 */
+export const getAssetsByKind = async (
+  kind: string,
+  filters?: {
+    keyword?: string
+    gender?: string
+    style?: string
+    tag_ids?: string[]
+    limit?: number
+    page?: number
+    page_size?: number
+  },
+): Promise<AssetItem[]> => {
+  const params: Record<string, string | number> = { kind }
+  if (filters?.keyword) params.keyword = filters.keyword
+  if (filters?.gender) params.gender = filters.gender
+  if (filters?.style) params.style = filters.style
+  if (filters?.tag_ids?.length) params.tag_ids = filters.tag_ids.join(",")
+  if (filters?.limit) params.limit = filters.limit
+  if (filters?.page) params.page = filters.page
+  if (filters?.page_size) params.page_size = filters.page_size
+  const response = await apiClient.get("/assets", { params })
+  return response.data.items || []
+}
+
+/** 创建素材（上传文件后调用，附带 metadata） */
+export const createAsset = async (data: {
+  library_id: string
+  name: string
+  storage_key: string
+  mime_type: string
+  metadata?: AssetMetadata
+}): Promise<AssetItem> => {
+  const response = await apiClient.post("/assets", data)
+  return response.data
+}
+
+/** 更新素材（名称、metadata 等） */
+export const updateAsset = async (
+  assetId: string,
+  data: { name?: string; metadata?: AssetMetadata },
+): Promise<AssetItem> => {
+  const response = await apiClient.put(`/assets/${assetId}`, data)
+  return response.data
+}
+
+/** 更新素材审核状态 */
+export const updateAssetReviewStatus = async (
+  assetId: string,
+  reviewStatus: "pending_review" | "approved" | "rejected",
+): Promise<AssetItem> => {
+  const response = await apiClient.patch(`/assets/${assetId}/review`, {
+    review_status: reviewStatus,
+  })
+  return response.data
+}
+
+/** 删除素材 */
+export const deleteAsset = async (assetId: string): Promise<void> => {
+  await apiClient.delete(`/assets/${assetId}`)
+}
+
+// ─── 上传 ──────────────────────────────────────────────────
+
+/** 表单上传素材（小文件） */
+export const uploadAsset = async (
+  formData: FormData,
+): Promise<{ storage_key: string; ingest_job_id: string; url: string }> => {
+  const response = await apiClient.post("/upload", formData, {
+    headers: { "Content-Type": "multipart/form-data" },
+    timeout: 30 * 60 * 1000,
+  })
+  return response.data
+}
+
+/** 预签名直传准备 */
+export const prepareDirectUpload = async (data: {
+  project_id: string
+  library_id: string
+  filename: string
+  content_type: string
+  file_size: number
+}): Promise<{
+  upload_url: string
+  method: string
+  storage_key: string
+  expires_at: string
+  fields: Record<string, string>
+  max_size_bytes: number
+}> => {
+  const response = await apiClient.post("/upload/direct/prepare", data)
+  return response.data
+}
+
+/** 直传完成确认 */
+export const completeDirectUpload = async (data: {
+  project_id: string
+  library_id: string
+  storage_key: string
+}): Promise<{ storage_key: string; ingest_job_id: string }> => {
+  const response = await apiClient.post("/upload/direct/complete", data)
+  return response.data
+}
+
+/** 直传上传（大文件推荐），支持可选进度回调 */
+export const uploadAssetDirect = async (data: {
+  file: File
+  library_id: string
+  onProgress?: (percent: number) => void
+}): Promise<{ storage_key: string; ingest_job_id: string }> => {
+  // 后端要求 project_id，前端自动获取默认项目
+  const project = await getOrCreateDefaultProject()
+
+  const prepared = await prepareDirectUpload({
+    project_id: project.id,
+    library_id: data.library_id,
+    filename: data.file.name,
+    content_type: data.file.type || "application/octet-stream",
+    file_size: data.file.size,
+  })
+
+  const directForm = new FormData()
+  Object.entries(prepared.fields).forEach(([key, value]) => directForm.append(key, value))
+  directForm.append("file", data.file)
+
+  // 使用 XMLHttpRequest 以获取上传进度 + 超时控制 + 详细错误诊断
+  await new Promise<void>((resolve, reject) => {
+    const xhr = new XMLHttpRequest()
+    xhr.open(prepared.method, prepared.upload_url)
+
+    // 超时 10 分钟
+    xhr.timeout = 10 * 60 * 1000
+
+    xhr.upload.onprogress = (e) => {
+      if (e.lengthComputable && data.onProgress) {
+        data.onProgress(Math.round((e.loaded / e.total) * 100))
+      }
+    }
+    xhr.onload = () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        resolve()
+      } else {
+        // 解析 OSS 返回的 XML 错误信息
+        let ossError = ""
+        try {
+          const codeMatch = xhr.responseText.match(/<Code>([^<]+)<\/Code>/)
+          const msgMatch = xhr.responseText.match(/<Message>([^<]+)<\/Message>/)
+          if (codeMatch || msgMatch) {
+            ossError = ` [OSS: ${codeMatch?.[1] || "unknown"} - ${msgMatch?.[1] || "unknown"}]`
+          }
+        } catch {
+          // 无法解析响应体
+        }
+        const detail = `OSS 直传失败: HTTP ${xhr.status} ${xhr.statusText}${ossError}`
+        console.error("[OSS Upload] 直传失败:", {
+          url: prepared.upload_url,
+          storage_key: prepared.storage_key,
+          status: xhr.status,
+          statusText: xhr.statusText,
+        })
+        reject(new Error(detail))
+      }
+    }
+    xhr.onerror = () => {
+      console.error("[OSS Upload] 网络错误:", {
+        url: prepared.upload_url,
+        storage_key: prepared.storage_key,
+      })
+      reject(new Error("OSS 上传网络错误，请检查网络连接"))
+    }
+    xhr.ontimeout = () => {
+      console.error("[OSS Upload] 上传超时:", {
+        url: prepared.upload_url,
+        storage_key: prepared.storage_key,
+      })
+      reject(new Error("OSS 上传超时（10分钟），请检查网络或尝试更小的文件"))
+    }
+    xhr.send(directForm)
+  })
+
+  return completeDirectUpload({
+    project_id: project.id,
+    library_id: data.library_id,
+    storage_key: prepared.storage_key,
+  })
+}
+
+// ─── 入库 / 分类任务 ───────────────────────────────────────
+
+/** 查询入库任务状态 */
+export const getIngestJob = async (jobId: string): Promise<IngestJob> => {
+  const response = await apiClient.get(`/ingest-jobs/${jobId}`)
+  return response.data
+}
+
+/** 提交素材分类任务 */
+export const submitClassificationJob = async (data: {
+  asset_id: string
+}): Promise<ClassificationJob> => {
+  const response = await apiClient.post("/classification-jobs", data)
+  return response.data
+}
+
+/** 查询分类任务状态 */
+export const getClassificationJob = async (jobId: string): Promise<ClassificationJob> => {
+  const response = await apiClient.get(`/classification-jobs/${jobId}`)
+  return response.data
+}
+
+// ─── 批量操作 ───────────────────────────────────────────────
+
+/** 批量操作结果 */
+export interface BatchOperationResult {
+  succeeded: string[]
+  failed: string[]
+  total: number
+  success_count: number
+  failure_count: number
+}
+
+/** 统一批量操作结果归一化，防御后端字段缺失或格式不一致 */
+const normalizeBatchResult = (raw: Record<string, unknown>): BatchOperationResult => {
+  const succeeded = Array.isArray(raw.succeeded) ? (raw.succeeded as string[]) : []
+  const failed = Array.isArray(raw.failed) ? (raw.failed as string[]) : []
+  const success_count = typeof raw.success_count === "number" ? raw.success_count : succeeded.length
+  const failure_count = typeof raw.failure_count === "number" ? raw.failure_count : failed.length
+  const total = typeof raw.total === "number" ? raw.total : success_count + failure_count
+  return { succeeded, failed, total, success_count, failure_count }
+}
+
+/** 批量删除素材 */
+export const batchDeleteAssets = async (assetIds: string[]): Promise<BatchOperationResult> => {
+  const response = await apiClient.post("/assets/batch-delete", {
+    asset_ids: assetIds,
+  })
+  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
+}
+
+/** 批量打标签 */
+export const batchTagAssets = async (data: {
+  asset_ids: string[]
+  tags: string[]
+  mode: "add" | "replace"
+}): Promise<BatchOperationResult> => {
+  const response = await apiClient.post("/assets/batch-tag", data)
+  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
+}
+
+/** 批量改分类 */
+export const batchClassifyAssets = async (data: {
+  asset_ids: string[]
+  category: string
+}): Promise<BatchOperationResult> => {
+  const response = await apiClient.post("/assets/batch-classify", data)
+  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
+}
+
+/** 批量智能标记 */
+export const batchMarkAssets = async (data: {
+  asset_ids: string[]
+  smart_view: "recommended" | "caution" | "high_risk"
+}): Promise<BatchOperationResult> => {
+  const response = await apiClient.post("/assets/batch-mark", data)
+  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
+}

apps/web/src/api/assets/assets.ts

@@ -1,87 +0,0 @@
-/**
- * 素材 CRUD API
- */
-import apiClient from "../client"
-import type { AssetItem, AssetMetadata } from "./types"
-
-/** 获取素材库下的所有素材 */
-export const getAssets = async (
-  libraryId: string,
-  options?: {
-    status?: string
-    page?: number
-    page_size?: number
-  },
-): Promise<{ items: AssetItem[]; total: number }> => {
-  const params: Record<string, string | number> = { library_id: libraryId }
-  if (options?.status) params.status = options.status
-  if (options?.page) params.page = options.page
-  if (options?.page_size) params.page_size = options.page_size
-  const response = await apiClient.get("/assets", { params })
-  const data = response.data || {}
-  const items: AssetItem[] = data.items || []
-  const total: number = typeof data.total === "number" ? data.total : items.length
-  return { items, total }
-}
-
-/** 按类型获取素材（如 voice/video/image），支持可选筛选 */
-export const getAssetsByKind = async (
-  kind: string,
-  filters?: {
-    keyword?: string
-    gender?: string
-    style?: string
-    tag_ids?: string[]
-    limit?: number
-    page?: number
-    page_size?: number
-  },
-): Promise<AssetItem[]> => {
-  const params: Record<string, string | number> = { kind }
-  if (filters?.keyword) params.keyword = filters.keyword
-  if (filters?.gender) params.gender = filters.gender
-  if (filters?.style) params.style = filters.style
-  if (filters?.tag_ids?.length) params.tag_ids = filters.tag_ids.join(",")
-  if (filters?.limit) params.limit = filters.limit
-  if (filters?.page) params.page = filters.page
-  if (filters?.page_size) params.page_size = filters.page_size
-  const response = await apiClient.get("/assets", { params })
-  return response.data.items || []
-}
-
-/** 创建素材（上传文件后调用，附带 metadata） */
-export const createAsset = async (data: {
-  library_id: string
-  name: string
-  storage_key: string
-  mime_type: string
-  metadata?: AssetMetadata
-}): Promise<AssetItem> => {
-  const response = await apiClient.post("/assets", data)
-  return response.data
-}
-
-/** 更新素材（名称、metadata 等） */
-export const updateAsset = async (
-  assetId: string,
-  data: { name?: string; metadata?: AssetMetadata },
-): Promise<AssetItem> => {
-  const response = await apiClient.put(`/assets/${assetId}`, data)
-  return response.data
-}
-
-/** 更新素材审核状态 */
-export const updateAssetReviewStatus = async (
-  assetId: string,
-  reviewStatus: "pending_review" | "approved" | "rejected",
-): Promise<AssetItem> => {
-  const response = await apiClient.patch(`/assets/${assetId}/review`, {
-    review_status: reviewStatus,
-  })
-  return response.data
-}
-
-/** 删除素材 */
-export const deleteAsset = async (assetId: string): Promise<void> => {
-  await apiClient.delete(`/assets/${assetId}`)
-}

apps/web/src/api/assets/batch.ts

@@ -1,51 +0,0 @@
-/**
- * 素材批量操作 API
- */
-import apiClient from "../client"
-import type { BatchOperationResult } from "./types"
-
-/** 统一批量操作结果归一化，防御后端字段缺失或格式不一致 */
-export const normalizeBatchResult = (raw: Record<string, unknown>): BatchOperationResult => {
-  const succeeded = Array.isArray(raw.succeeded) ? (raw.succeeded as string[]) : []
-  const failed = Array.isArray(raw.failed) ? (raw.failed as string[]) : []
-  const success_count = typeof raw.success_count === "number" ? raw.success_count : succeeded.length
-  const failure_count = typeof raw.failure_count === "number" ? raw.failure_count : failed.length
-  const total = typeof raw.total === "number" ? raw.total : success_count + failure_count
-  return { succeeded, failed, total, success_count, failure_count }
-}
-
-/** 批量删除素材 */
-export const batchDeleteAssets = async (assetIds: string[]): Promise<BatchOperationResult> => {
-  const response = await apiClient.post("/assets/batch-delete", {
-    asset_ids: assetIds,
-  })
-  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
-}
-
-/** 批量打标签 */
-export const batchTagAssets = async (data: {
-  asset_ids: string[]
-  tags: string[]
-  mode: "add" | "replace"
-}): Promise<BatchOperationResult> => {
-  const response = await apiClient.post("/assets/batch-tag", data)
-  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
-}
-
-/** 批量改分类 */
-export const batchClassifyAssets = async (data: {
-  asset_ids: string[]
-  category: string
-}): Promise<BatchOperationResult> => {
-  const response = await apiClient.post("/assets/batch-classify", data)
-  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
-}
-
-/** 批量智能标记 */
-export const batchMarkAssets = async (data: {
-  asset_ids: string[]
-  smart_view: "recommended" | "caution" | "high_risk"
-}): Promise<BatchOperationResult> => {
-  const response = await apiClient.post("/assets/batch-mark", data)
-  return normalizeBatchResult((response.data || {}) as Record<string, unknown>)
-}

apps/web/src/api/assets/diagnosis.ts

@@ -1,13 +0,0 @@
-/**
- * 素材诊断 API
- */
-import apiClient from "../client"
-import type { AssetDiagnosis } from "./types"
-
-/** 获取素材诊断信息（可选 asset_id 查单素材，否则全局诊断） */
-export const getAssetDiagnosis = async (assetId?: string): Promise<AssetDiagnosis> => {
-  const params: Record<string, string> = {}
-  if (assetId) params.asset_id = assetId
-  const response = await apiClient.get("/asset-diagnosis", { params })
-  return response.data
-}

apps/web/src/api/assets/index.ts

@@ -1,55 +0,0 @@
-/**
- * 素材相关 API — 按模块拆分后的统一入口
- * 保持与原 assets.ts 相同的导出结构，向后兼容
- */
-
-// 类型
-export type {
-  AssetMetadata,
-  AssetClassificationStatus,
-  AssetItem,
-  AssetLibraryItem,
-  IngestJob,
-  ClassificationJob,
-  AssetDiagnosis,
-  BatchOperationResult,
-  UploadResult,
-  DirectUploadPrepareResult,
-  DirectUploadCompleteResult,
-} from "./types"
-
-// 素材诊断
-export { getAssetDiagnosis } from "./diagnosis"
-
-// 素材库
-export {
-  getAssetLibraries,
-  createAssetLibrary,
-  ensureDefaultLibrary,
-  deleteAssetLibrary,
-} from "./libraries"
-
-// 素材 CRUD
-export {
-  getAssets,
-  getAssetsByKind,
-  createAsset,
-  updateAsset,
-  updateAssetReviewStatus,
-  deleteAsset,
-} from "./assets"
-
-// 上传
-export { uploadAsset, prepareDirectUpload, completeDirectUpload, uploadAssetDirect } from "./upload"
-
-// 任务
-export { getIngestJob, submitClassificationJob, getClassificationJob } from "./jobs"
-
-// 批量操作
-export {
-  normalizeBatchResult,
-  batchDeleteAssets,
-  batchTagAssets,
-  batchClassifyAssets,
-  batchMarkAssets,
-} from "./batch"

apps/web/src/api/assets/jobs.ts

@@ -1,25 +0,0 @@
-/**
- * 入库任务 & 分类任务 API
- */
-import apiClient from "../client"
-import type { IngestJob, ClassificationJob } from "./types"
-
-/** 查询入库任务状态 */
-export const getIngestJob = async (jobId: string): Promise<IngestJob> => {
-  const response = await apiClient.get(`/ingest-jobs/${jobId}`)
-  return response.data
-}
-
-/** 提交素材分类任务 */
-export const submitClassificationJob = async (data: {
-  asset_id: string
-}): Promise<ClassificationJob> => {
-  const response = await apiClient.post("/classification-jobs", data)
-  return response.data
-}
-
-/** 查询分类任务状态 */
-export const getClassificationJob = async (jobId: string): Promise<ClassificationJob> => {
-  const response = await apiClient.get(`/classification-jobs/${jobId}`)
-  return response.data
-}

apps/web/src/api/assets/libraries.ts

@@ -1,39 +0,0 @@
-/**
- * 素材库 API
- */
-import apiClient from "../client"
-import { getOrCreateDefaultProject } from "../projects"
-import type { AssetLibraryItem } from "./types"
-
-/** 获取当前用户的所有素材库 */
-export const getAssetLibraries = async (): Promise<AssetLibraryItem[]> => {
-  const response = await apiClient.get("/asset-libraries")
-  return response.data.items || []
-}
-
-/** 创建素材库（自动获取或创建默认项目以提供 project_id） */
-export const createAssetLibrary = async (data: {
-  name: string
-  kind: "video" | "voice" | "image"
-}): Promise<AssetLibraryItem> => {
-  const project = await getOrCreateDefaultProject()
-  const response = await apiClient.post("/asset-libraries", {
-    project_id: project.id,
-    ...data,
-  })
-  return response.data
-}
-
-/** 确保项目下指定 kind 的默认素材库存在 */
-export const ensureDefaultLibrary = async (data: {
-  project_id: string
-  kind: "video" | "voice" | "image"
-}): Promise<AssetLibraryItem> => {
-  const response = await apiClient.post("/asset-libraries/ensure-default", data)
-  return response.data
-}
-
-/** 删除素材库 */
-export const deleteAssetLibrary = async (libraryId: string): Promise<void> => {
-  await apiClient.delete(`/asset-libraries/${libraryId}`)
-}

apps/web/src/api/assets/types.ts

@@ -1,138 +0,0 @@
-/**
- * 素材相关类型定义
- */
-
-/** 素材元数据 */
-export interface AssetMetadata {
-  /** 时长（秒） */
-  duration?: number
-  /** 宽度（像素） */
-  width?: number
-  /** 高度（像素） */
-  height?: number
-  /** 比特率（bps） */
-  bitrate?: number
-  /** 编码格式 */
-  codec?: string
-  /** 帧率 */
-  fps?: number
-  /** 采样率（Hz） */
-  sample_rate?: number
-  /** 声道数 */
-  channels?: number
-  /** 其他扩展字段 */
-  [key: string]: unknown
-}
-
-/** 素材分类状态 */
-export type AssetClassificationStatus = "pending" | "processing" | "completed" | "failed"
-
-/** 素材条目 */
-export interface AssetItem {
-  id: string
-  library_id: string
-  name: string
-  storage_key: string
-  mime_type: string
-  metadata: AssetMetadata
-  file_size?: number
-  file_url?: string
-  thumbnail_url?: string
-  /** 时长（秒），视频/音频素材由后端从 metadata 提取到顶层 */
-  duration?: number
-  status?: string
-  classification_status?: AssetClassificationStatus | null
-  quality_score?: number | null
-  tag_ids?: string[]
-  created_at?: string
-}
-
-/** 素材库 */
-export interface AssetLibraryItem {
-  id: string
-  name: string
-  kind: "video" | "voice" | "image"
-  asset_count?: number
-  total_size?: number
-  created_at?: string
-}
-
-/** 入库任务 */
-export interface IngestJob {
-  id: string
-  library_id: string
-  storage_key: string
-  status: "pending" | "processing" | "completed" | "failed"
-  error_message: string
-  result_asset_id: string
-}
-
-/** 分类任务 */
-export interface ClassificationJob {
-  id: string
-  asset_id: string
-  status: "pending" | "processing" | "completed" | "failed"
-  classification: string
-  confidence: number
-  error_message: string
-}
-
-/** 素材诊断信息 */
-export interface AssetDiagnosis {
-  readiness_score: number
-  readiness_label: string
-  total_assets: number
-  ready_assets: number
-  video_assets: number
-  image_assets: number
-  voice_assets: number
-  total_duration_seconds: number
-  estimated_video_count: number
-  used_assets: number
-  unused_assets: number
-  pending_review_assets: number
-  smart_views: Array<{
-    key: string
-    label: string
-    count: number
-    description: string
-  }>
-  gaps: Array<{
-    key: string
-    severity: "critical" | "warning" | "info"
-    message: string
-    recommendation: string
-  }>
-}
-
-/** 批量操作结果 */
-export interface BatchOperationResult {
-  succeeded: string[]
-  failed: string[]
-  total: number
-  success_count: number
-  failure_count: number
-}
-
-/** 上传返回 */
-export interface UploadResult {
-  storage_key: string
-  ingest_job_id: string
-  url: string
-}
-
-/** 预签名直传准备返回 */
-export interface DirectUploadPrepareResult {
-  upload_url: string
-  method: string
-  storage_key: string
-  expires_at: string
-  fields: Record<string, string>
-  max_size_bytes: number
-}
-
-/** 直传完成确认返回 */
-export interface DirectUploadCompleteResult {
-  storage_key: string
-  ingest_job_id: string
-}

apps/web/src/api/assets/upload.ts

@@ -1,119 +0,0 @@
-/**
- * 上传相关 API（表单上传 + OSS 直传）
- */
-import apiClient from "../client"
-import { getOrCreateDefaultProject } from "../projects"
-import type { UploadResult, DirectUploadPrepareResult, DirectUploadCompleteResult } from "./types"
-
-/** 表单上传素材（小文件） */
-export const uploadAsset = async (formData: FormData): Promise<UploadResult> => {
-  const response = await apiClient.post("/upload", formData, {
-    headers: { "Content-Type": "multipart/form-data" },
-    timeout: 30 * 60 * 1000,
-  })
-  return response.data
-}
-
-/** 预签名直传准备 */
-export const prepareDirectUpload = async (data: {
-  project_id: string
-  library_id: string
-  filename: string
-  content_type: string
-  file_size: number
-}): Promise<DirectUploadPrepareResult> => {
-  const response = await apiClient.post("/upload/direct/prepare", data)
-  return response.data
-}
-
-/** 直传完成确认 */
-export const completeDirectUpload = async (data: {
-  project_id: string
-  library_id: string
-  storage_key: string
-}): Promise<DirectUploadCompleteResult> => {
-  const response = await apiClient.post("/upload/direct/complete", data)
-  return response.data
-}
-
-/** 直传上传（大文件推荐），支持可选进度回调 */
-export const uploadAssetDirect = async (data: {
-  file: File
-  library_id: string
-  onProgress?: (percent: number) => void
-}): Promise<DirectUploadCompleteResult> => {
-  const project = await getOrCreateDefaultProject()
-
-  const prepared = await prepareDirectUpload({
-    project_id: project.id,
-    library_id: data.library_id,
-    filename: data.file.name,
-    content_type: data.file.type || "application/octet-stream",
-    file_size: data.file.size,
-  })
-
-  const directForm = new FormData()
-  Object.entries(prepared.fields).forEach(([key, value]) => directForm.append(key, value))
-  directForm.append("file", data.file)
-
-  // 使用 XMLHttpRequest 以获取上传进度 + 超时控制 + 详细错误诊断
-  await new Promise<void>((resolve, reject) => {
-    const xhr = new XMLHttpRequest()
-    xhr.open(prepared.method, prepared.upload_url)
-
-    // 超时 10 分钟
-    xhr.timeout = 10 * 60 * 1000
-
-    xhr.upload.onprogress = (e) => {
-      if (e.lengthComputable && data.onProgress) {
-        data.onProgress(Math.round((e.loaded / e.total) * 100))
-      }
-    }
-    xhr.onload = () => {
-      if (xhr.status >= 200 && xhr.status < 300) {
-        resolve()
-      } else {
-        // 解析 OSS 返回的 XML 错误信息
-        let ossError = ""
-        try {
-          const codeMatch = xhr.responseText.match(/<Code>([^<]+)<\/Code>/)
-          const msgMatch = xhr.responseText.match(/<Message>([^<]+)<\/Message>/)
-          if (codeMatch || msgMatch) {
-            ossError = ` [OSS: ${codeMatch?.[1] || "unknown"} - ${msgMatch?.[1] || "unknown"}]`
-          }
-        } catch {
-          // 无法解析响应体
-        }
-        const detail = `OSS 直传失败: HTTP ${xhr.status} ${xhr.statusText}${ossError}`
-        console.error("[OSS Upload] 直传失败:", {
-          url: prepared.upload_url,
-          storage_key: prepared.storage_key,
-          status: xhr.status,
-          statusText: xhr.statusText,
-        })
-        reject(new Error(detail))
-      }
-    }
-    xhr.onerror = () => {
-      console.error("[OSS Upload] 网络错误:", {
-        url: prepared.upload_url,
-        storage_key: prepared.storage_key,
-      })
-      reject(new Error("OSS 上传网络错误，请检查网络连接"))
-    }
-    xhr.ontimeout = () => {
-      console.error("[OSS Upload] 上传超时:", {
-        url: prepared.upload_url,
-        storage_key: prepared.storage_key,
-      })
-      reject(new Error("OSS 上传超时（10分钟），请检查网络或尝试更小的文件"))
-    }
-    xhr.send(directForm)
-  })
-
-  return completeDirectUpload({
-    project_id: project.id,
-    library_id: data.library_id,
-    storage_key: prepared.storage_key,
-  })
-}

apps/web/src/pages/editing-planner/hooks/template-management/usePlanLoading.ts

@@ -0,0 +1,157 @@
+import { useEffect, type Dispatch, type SetStateAction } from "react"
+import { message } from "antd"
+import { getEditPlan, getEditPlanClips } from "@/api/template-editor"
+import type { ClipData, ClipType, TtsConfig, TtsMode, TrimConfig } from "../../types"
+import type { SubtitleStyleConfig } from "../../types/subtitle"
+import type { TitleConfig } from "@/api/template-editor"
+import type { BgmMixConfig } from "@/api/bgm"
+import type { TransitionEffect } from "@/api/template-editor"
+import type { CoverConfig } from "../../types"
+
+interface UsePlanLoadingOptions {
+  loadedPlanId: string | null
+  resetClips: (clips: ClipData[]) => void
+  setLoadedTemplateId: (id: string | null) => void
+  setDraftName: (name: string) => void
+  setTitleConfig: Dispatch<SetStateAction<TitleConfig>>
+  setSubtitleSettings: Dispatch<SetStateAction<SubtitleStyleConfig>>
+  setBgmSettings: Dispatch<SetStateAction<BgmMixConfig>>
+  setCoverConfig: Dispatch<SetStateAction<CoverConfig>>
+}
+
+/**
+ * 加载已有计划草稿数据到编辑器
+ * 从列表页"编辑"按钮进入时，URL 带 planId，需要还原计划配置
+ */
+export function usePlanLoading({
+  loadedPlanId,
+  resetClips,
+  setLoadedTemplateId,
+  setDraftName,
+  setTitleConfig,
+  setSubtitleSettings,
+  setBgmSettings,
+  setCoverConfig,
+}: UsePlanLoadingOptions) {
+  useEffect(() => {
+    if (!loadedPlanId) return
+
+    Promise.all([
+      getEditPlan(loadedPlanId),
+      getEditPlanClips(loadedPlanId, { limit: 500 }).catch(() => ({
+        items: [],
+        total: 0,
+      })),
+    ])
+      .then(([plan, clipsRes]) => {
+        setLoadedTemplateId(plan.template_id)
+        setDraftName(plan.name)
+
+        const cfg = plan.config
+        if (cfg.title_config) {
+          setTitleConfig({
+            ai_auto_select: cfg.title_config!.ai_auto_select,
+            content: cfg.title_config!.content,
+            position: cfg.title_config!.position,
+            font_preset: cfg.title_config!.font_preset,
+            font_size: cfg.title_config!.font_size,
+            font_color: cfg.title_config!.font_color || "#ffffff",
+          })
+        }
+        if (cfg.subtitle_config) {
+          setSubtitleSettings((prev) => ({
+            ...prev,
+            enabled: cfg.subtitle_config!.enabled,
+            position: (cfg.subtitle_config!.position ||
+              "bottom") as SubtitleStyleConfig["position"],
+            font: cfg.subtitle_config!.font,
+            fontSize: cfg.subtitle_config!.size,
+            fontColor: cfg.subtitle_config!.color || "#ffffff",
+            animation: cfg.subtitle_config!.animation,
+          }))
+        }
+        if (cfg.bgm_config) {
+          setBgmSettings((prev) => ({
+            ...prev,
+            enabled: cfg.bgm_config!.enabled,
+            music_id: cfg.bgm_config!.music_id || "",
+          }))
+        }
+        if (cfg.cover_config) {
+          setCoverConfig((prev: CoverConfig) => ({
+            ...prev,
+            enabled: cfg.cover_config!.enabled ?? prev.enabled,
+            mode: (cfg.cover_config!.mode as CoverConfig["mode"]) || prev.mode,
+            frame_time: cfg.cover_config!.frame_time ?? prev.frame_time,
+            upload_url: cfg.cover_config!.upload_url || prev.upload_url,
+            thumbnail_url: cfg.cover_config!.thumbnail_url || prev.thumbnail_url,
+            ai_suggested_time: cfg.cover_config!.ai_suggested_time ?? prev.ai_suggested_time,
+          }))
+        }
+
+        /* 还原片段：优先从后端 clips 表，其次从 config.segments 兜底 */
+        const backendClips = clipsRes?.items || []
+        if (backendClips.length > 0) {
+          const sorted = [...backendClips].sort((a, b) => a.order - b.order)
+          const mapped: ClipData[] = sorted.map((clip) => ({
+            id: clip.id,
+            template_segment_id: (clip.config?.template_segment_id as string) || "",
+            type: (clip.clip_type === "voiceover" ? "voice" : "pip") as ClipType,
+            duration: clip.duration || 3,
+            startOffset: 0,
+            script_text: clip.text_content || "",
+            order: clip.order,
+            media_asset_id: clip.asset_id || undefined,
+            transition:
+              clip.transition_effect && clip.transition_effect !== "none"
+                ? {
+                    type: clip.transition_effect as TransitionEffect["type"],
+                    duration: clip.transition_duration || 0.3,
+                  }
+                : undefined,
+            speed: clip.playback_speed
+              ? { rate: clip.playback_speed, pitchCorrection: true }
+              : undefined,
+            tts_config: (clip.config?.tts_config as TtsConfig) || undefined,
+            trim_config: (clip.config?.trim_config as TrimConfig) || undefined,
+          }))
+          setTimeout(() => resetClips(mapped), 100)
+        } else if (cfg.segments && cfg.segments.length > 0) {
+          /* 兜底：从 config.segments 还原（老数据兼容） */
+          const mapped: ClipData[] = cfg.segments.map((seg, idx) => ({
+            id: `seg-${idx}`,
+            template_segment_id: `seg-${idx}`,
+            type: (seg.material_type === "voiceover" ? "voice" : "pip") as ClipType,
+            duration: (seg.duration_min + seg.duration_max) / 2,
+            startOffset: 0,
+            script_text: "",
+            order: seg.segment_order,
+            transition: seg.transition
+              ? {
+                  type: seg.transition.type as TransitionEffect["type"],
+                  duration: seg.transition.duration,
+                }
+              : undefined,
+            speed: seg.playback_speed
+              ? { rate: seg.playback_speed, pitchCorrection: true }
+              : undefined,
+            tts_config: seg.tts_config
+              ? { ...seg.tts_config, mode: seg.tts_config.mode as TtsMode }
+              : undefined,
+            trim_config: seg.trim_config || undefined,
+          }))
+          setTimeout(() => resetClips(mapped), 100)
+        }
+      })
+      .catch(() => message.error("加载模板草稿失败"))
+  }, [
+    loadedPlanId,
+    resetClips,
+    setLoadedTemplateId,
+    setDraftName,
+    setTitleConfig,
+    setSubtitleSettings,
+    setBgmSettings,
+    setCoverConfig,
+  ])
+}

apps/web/src/pages/editing-planner/hooks/template-management/useTemplateDetail.ts

@@ -0,0 +1,91 @@
+import { useEffect, type Dispatch, type SetStateAction } from "react"
+import { message } from "antd"
+import { getEditingTemplate, type TemplateMode } from "@/api/editing-planner"
+import type { TitleConfig } from "@/api/template-editor"
+import type { ClipData, ClipType } from "../../types"
+import type { SubtitleStyleConfig } from "../../types/subtitle"
+import type { BgmMixConfig } from "@/api/bgm"
+
+interface UseTemplateDetailOptions {
+  loadedTemplateId: string | null
+  resetClips: (clips: ClipData[]) => void
+  setCurrentMode: (mode: TemplateMode) => void
+  setTitleConfig: Dispatch<SetStateAction<TitleConfig>>
+  setSubtitleSettings: Dispatch<SetStateAction<SubtitleStyleConfig>>
+  setBgmSettings: Dispatch<SetStateAction<BgmMixConfig>>
+  setDraftName: (name: string) => void
+  setDraftCategory: (cat: string) => void
+  setDraftTags: (tags: string) => void
+}
+
+/**
+ * 加载模板详情并初始化片段列表 + 配置
+ */
+export function useTemplateDetail({
+  loadedTemplateId,
+  resetClips,
+  setCurrentMode,
+  setTitleConfig,
+  setSubtitleSettings,
+  setBgmSettings,
+  setDraftName,
+  setDraftCategory,
+  setDraftTags,
+}: UseTemplateDetailOptions) {
+  useEffect(() => {
+    if (!loadedTemplateId) return
+    getEditingTemplate(loadedTemplateId)
+      .then((tpl) => {
+        if (!tpl) return
+        setCurrentMode(tpl.mode)
+
+        const mapped: ClipData[] = tpl.segments.map((seg, idx) => ({
+          id: seg.id || `seg-${idx}`,
+          template_segment_id: seg.id || `seg-${idx}`,
+          type: (seg.material_type === "voiceover" ? "voice" : "pip") as ClipType,
+          duration: (seg.duration_min + seg.duration_max) / 2,
+          startOffset: 0,
+          script_text: "",
+          order: seg.segment_order,
+        }))
+        resetClips(mapped)
+
+        setTitleConfig({
+          ai_auto_select: tpl.title_config.ai_auto_select,
+          content: tpl.title_config.content,
+          position: tpl.title_config.position,
+          font_preset: tpl.title_config.font_preset,
+          font_size: tpl.title_config.font_size,
+          font_color: tpl.title_config.font_color || "#ffffff",
+        })
+        setSubtitleSettings((prev) => ({
+          ...prev,
+          enabled: tpl.subtitle_config.enabled,
+          position: (tpl.subtitle_config.position || "bottom") as SubtitleStyleConfig["position"],
+          font: tpl.subtitle_config.font,
+          fontSize: tpl.subtitle_config.size,
+          fontColor: tpl.subtitle_config.color || "#ffffff",
+          animation: tpl.subtitle_config.animation,
+        }))
+        setBgmSettings((prev) => ({
+          ...prev,
+          enabled: tpl.bgm_config.enabled,
+          music_id: tpl.bgm_config.music_id || "",
+        }))
+        setDraftName(tpl.name)
+        setDraftCategory(tpl.category)
+        setDraftTags(tpl.tags.join(", "))
+      })
+      .catch(() => message.error("加载模板详情失败"))
+  }, [
+    loadedTemplateId,
+    resetClips,
+    setCurrentMode,
+    setTitleConfig,
+    setSubtitleSettings,
+    setBgmSettings,
+    setDraftName,
+    setDraftCategory,
+    setDraftTags,
+  ])
+}

apps/web/src/pages/editing-planner/hooks/template-management/useTemplateList.ts

@@ -0,0 +1,82 @@
+import { useState, useCallback, useEffect, useMemo } from "react"
+import { message } from "antd"
+import {
+  getEditingTemplates,
+  getTemplateCategories,
+  type EditingTemplate,
+  type TemplateCategory,
+} from "@/api/editing-planner"
+import { getMediaAssets, type MediaAsset } from "@/api/template-editor"
+import { FILTER_CATEGORIES } from "../../constants"
+
+/**
+ * 模板列表 + 分类 + 筛选搜索
+ */
+export function useTemplateList(
+  setMediaAssets: (assets: MediaAsset[]) => void,
+  initialTemplateId: string | null,
+) {
+  const [templates, setTemplates] = useState<EditingTemplate[]>([])
+  const [categories, setCategories] = useState<TemplateCategory[]>([])
+  const [loadingTemplates, setLoadingTemplates] = useState(false)
+  const [currentFilter, setCurrentFilter] = useState("全部")
+  const [searchQuery, setSearchQuery] = useState("")
+  const [loadedTemplateId, setLoadedTemplateId] = useState<string | null>(initialTemplateId)
+
+  /**
+   * 并行加载模板列表、分类、素材库
+   * 三个接口无依赖关系，用 Promise.all 并发
+   */
+  const loadTemplates = useCallback(async () => {
+    setLoadingTemplates(true)
+    try {
+      const [tpls, cats, assets] = await Promise.all([
+        getEditingTemplates(),
+        getTemplateCategories(),
+        getMediaAssets(),
+      ])
+      setTemplates(tpls)
+      setCategories(cats)
+      setMediaAssets(assets)
+    } catch {
+      message.error("加载模板失败")
+    } finally {
+      setLoadingTemplates(false)
+    }
+  }, [setMediaAssets])
+
+  useEffect(() => {
+    loadTemplates()
+  }, [loadTemplates])
+
+  const filteredTemplates = useMemo(
+    () =>
+      templates.filter((t) => {
+        if (currentFilter !== "全部" && t.category !== currentFilter) return false
+        if (searchQuery && !t.name.toLowerCase().includes(searchQuery.toLowerCase())) return false
+        return true
+      }),
+    [templates, currentFilter, searchQuery],
+  )
+
+  const currentTemplate = useMemo(
+    () => templates.find((t) => t.id === loadedTemplateId) || null,
+    [templates, loadedTemplateId],
+  )
+
+  return {
+    templates,
+    categories,
+    loadingTemplates,
+    loadedTemplateId,
+    setLoadedTemplateId,
+    currentFilter,
+    setCurrentFilter,
+    searchQuery,
+    setSearchQuery,
+    filteredTemplates,
+    currentTemplate,
+    loadTemplates,
+    FILTER_CATEGORIES,
+  }
+}

apps/web/src/pages/editing-planner/hooks/template-management/useTemplateSave.ts

@@ -0,0 +1,184 @@
+import { useState, useCallback } from "react"
+import { message } from "antd"
+import {
+  createEditingTemplate,
+  updateEditingTemplate,
+  type SaveTemplatePayload,
+  type TemplateMode,
+} from "@/api/editing-planner"
+import type {
+  ClipData,
+  WatermarkConfig,
+  IntroOutroConfig,
+  PipConfig,
+  FilterConfig,
+  ChromaKeyConfig,
+  StickerConfig,
+} from "../../types"
+import type { SubtitleStyleConfig } from "../../types/subtitle"
+import type { TitleConfig } from "@/api/template-editor"
+import type { CoverConfig } from "../../types"
+import type { BgmMixConfig } from "@/api/bgm"
+
+interface UseTemplateSaveOptions {
+  currentMode: TemplateMode
+  clips: ClipData[]
+  totalDuration: number
+  titleConfig: TitleConfig
+  subtitleSettings: SubtitleStyleConfig
+  bgmSettings: BgmMixConfig
+  watermarkSettings: WatermarkConfig
+  introOutroSettings: IntroOutroConfig
+  pipSettings: PipConfig
+  filterSettings: FilterConfig
+  chromaKeySettings: ChromaKeyConfig
+  stickerSettings: StickerConfig
+  coverConfig: CoverConfig
+  loadedTemplateId: string | null
+  loadTemplates: () => Promise<void>
+}
+
+/**
+ * 模板保存（创建/更新）
+ */
+export function useTemplateSave(options: UseTemplateSaveOptions) {
+  const {
+    currentMode,
+    clips,
+    totalDuration,
+    titleConfig,
+    subtitleSettings,
+    bgmSettings,
+    watermarkSettings,
+    introOutroSettings,
+    pipSettings,
+    filterSettings,
+    chromaKeySettings,
+    stickerSettings,
+    coverConfig,
+    loadedTemplateId,
+    loadTemplates,
+  } = options
+
+  const [saveModalOpen, setSaveModalOpen] = useState(false)
+  const [draftName, setDraftName] = useState("")
+  const [draftCategory, setDraftCategory] = useState("")
+  const [draftTags, setDraftTags] = useState("")
+  const [saveLoading, setSaveLoading] = useState(false)
+
+  const handleOpenSaveModal = useCallback(() => {
+    setSaveModalOpen(true)
+  }, [])
+
+  const handleSave = useCallback(async () => {
+    if (!draftName.trim()) {
+      message.warning("请输入模板名称")
+      return
+    }
+    setSaveLoading(true)
+    try {
+      const payload: SaveTemplatePayload = {
+        name: draftName,
+        mode: currentMode,
+        category: draftCategory,
+        tags: draftTags
+          .split(",")
+          .map((t) => t.trim())
+          .filter(Boolean),
+        title_config: titleConfig,
+        subtitle_config: {
+          enabled: subtitleSettings.enabled,
+          position: subtitleSettings.position,
+          font: subtitleSettings.font,
+          color: subtitleSettings.fontColor,
+          size: subtitleSettings.fontSize,
+          animation: subtitleSettings.animation,
+        },
+        bgm_config: {
+          enabled: bgmSettings.enabled,
+          music_id: bgmSettings.music_id,
+        },
+        estimated_duration: totalDuration,
+        segments: clips.map((c, i) => ({
+          segment_order: i,
+          duration_min: Math.max(1, c.duration - 2),
+          duration_max: c.duration + 2,
+          material_type: c.type === "voice" ? "voiceover" : "video",
+          transition: c.transition
+            ? { type: c.transition.type, duration: c.transition.duration }
+            : undefined,
+          playback_speed: c.speed ? c.speed.rate : undefined,
+          tts_config: c.tts_config
+            ? {
+                mode: c.tts_config.mode,
+                text: c.tts_config.text,
+                voice_id: c.tts_config.voice_id,
+                speed: c.tts_config.speed,
+                pitch: c.tts_config.pitch,
+                volume: c.tts_config.volume,
+                subtitle_sync: c.tts_config.subtitle_sync,
+              }
+            : undefined,
+          trim_config: c.trim_config
+            ? {
+                start_time: c.trim_config.start_time,
+                end_time: c.trim_config.end_time,
+              }
+            : undefined,
+        })),
+        watermark_config: { ...watermarkSettings },
+        intro_outro_config: { ...introOutroSettings },
+        pip_config: { ...pipSettings },
+        filter_config: { ...filterSettings },
+        green_screen_config: { ...chromaKeySettings },
+        sticker_config: { ...stickerSettings },
+        cover_config: { ...coverConfig },
+      }
+      if (loadedTemplateId) {
+        await updateEditingTemplate(loadedTemplateId, payload)
+      } else {
+        await createEditingTemplate(payload)
+      }
+      message.success(loadedTemplateId ? "模板保存成功" : "模板创建成功")
+      setSaveModalOpen(false)
+      loadTemplates()
+    } catch {
+      message.error("保存失败")
+    } finally {
+      setSaveLoading(false)
+    }
+  }, [
+    draftName,
+    draftCategory,
+    draftTags,
+    currentMode,
+    clips,
+    totalDuration,
+    titleConfig,
+    subtitleSettings,
+    bgmSettings,
+    watermarkSettings,
+    introOutroSettings,
+    pipSettings,
+    filterSettings,
+    chromaKeySettings,
+    stickerSettings,
+    coverConfig,
+    loadedTemplateId,
+    loadTemplates,
+  ])
+
+  return {
+    saveModalOpen,
+    setSaveModalOpen,
+    draftName,
+    setDraftName,
+    draftCategory,
+    setDraftCategory,
+    draftTags,
+    setDraftTags,
+    saveLoading,
+    handleOpenSaveModal,
+    handleSave,
+  }
+}

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

@@ -1,27 +1,8 @@
-import { useState, useCallback, useEffect, type Dispatch, type SetStateAction } from "react"
-import { FILTER_CATEGORIES } from "../constants"
-import { message } from "antd"
-import type {
-  EditingTemplate,
-  TemplateCategory,
-  TemplateMode,
-  SaveTemplatePayload,
-} from "@/api/editing-planner"
-import {
-  getEditingTemplates,
-  getEditingTemplate,
-  createEditingTemplate,
-  updateEditingTemplate,
-  getTemplateCategories,
-} from "@/api/editing-planner"
-import type { MediaAsset, TitleConfig, TransitionEffect } from "@/api/template-editor"
-import { getMediaAssets, getEditPlan, getEditPlanClips } from "@/api/template-editor"
+import { useState, useCallback, type Dispatch, type SetStateAction } from "react"
+import type { TemplateMode } from "@/api/editing-planner"
+import type { MediaAsset, TitleConfig } from "@/api/template-editor"
 import type {
   ClipData,
-  ClipType,
-  TtsConfig,
-  TtsMode,
-  TrimConfig,
   WatermarkConfig,
   IntroOutroConfig,
   PipConfig,
@@ -32,6 +13,11 @@ import type {
 } from "../types"
 import type { SubtitleStyleConfig } from "../types/subtitle"
 import type { BgmMixConfig } from "@/api/bgm"
+import { useTemplateList } from "./template-management/useTemplateList"
+import { useTemplateDetail } from "./template-management/useTemplateDetail"
+import { usePlanLoading } from "./template-management/usePlanLoading"
+import { useTemplateSave } from "./template-management/useTemplateSave"
+import { FILTER_CATEGORIES } from "../constants"
 
 interface UseTemplateManagementParams {
   urlTemplateId: string
@@ -44,7 +30,6 @@ interface UseTemplateManagementParams {
   setSubtitleSettings: Dispatch<SetStateAction<SubtitleStyleConfig>>
   setBgmSettings: Dispatch<SetStateAction<BgmMixConfig>>
   setCoverConfig: Dispatch<SetStateAction<CoverConfig>>
-  // 保存时需要的配置
   clips: ClipData[]
   totalDuration: number
   titleConfig: TitleConfig
@@ -61,7 +46,7 @@ interface UseTemplateManagementParams {
 
 /**
  * 模板管理 Hook
- * 模板列表/分类/加载/保存/模式切换/筛选搜索 + 3 个 useEffect
+ * 模板列表/分类/加载/保存/模式切换/筛选搜索
  */
 export const useTemplateManagement = (params: UseTemplateManagementParams) => {
   const {
@@ -89,346 +74,101 @@ export const useTemplateManagement = (params: UseTemplateManagementParams) => {
     coverConfig,
   } = params
 
-  /* ── 模板列表 ── */
-  const [templates, setTemplates] = useState<EditingTemplate[]>([])
-  const [categories, setCategories] = useState<TemplateCategory[]>([])
-  const [loadingTemplates, setLoadingTemplates] = useState(false)
-  const [loadedTemplateId, setLoadedTemplateId] = useState<string | null>(urlTemplateId || null)
   const [currentMode, setCurrentMode] = useState<TemplateMode>("pip")
-
-  /* ── 左栏筛选 ── */
-  const [currentFilter, setCurrentFilter] = useState("全部")
-  const [searchQuery, setSearchQuery] = useState("")
-
-  /* ── 保存弹窗 ── */
-  const [saveModalOpen, setSaveModalOpen] = useState(false)
-  const [draftName, setDraftName] = useState("")
-  const [draftCategory, setDraftCategory] = useState("")
-  const [draftTags, setDraftTags] = useState("")
-  const [saveLoading, setSaveLoading] = useState(false)
-
-  /* ── 计划 ID（从 URL 传入，不变） ── */
   const [loadedPlanId] = useState<string | null>(urlPlanId || null)
 
-  /* ── 计算 ── */
-  const filteredTemplates = templates.filter((t) => {
-    if (currentFilter !== "全部" && t.category !== currentFilter) return false
-    if (searchQuery && !t.name.toLowerCase().includes(searchQuery.toLowerCase())) return false
-    return true
+  /* ── 模板列表 ── */
+  const {
+    templates,
+    categories,
+    loadingTemplates,
+    loadedTemplateId,
+    setLoadedTemplateId,
+    currentFilter,
+    setCurrentFilter,
+    searchQuery,
+    setSearchQuery,
+    filteredTemplates,
+    currentTemplate,
+    loadTemplates,
+  } = useTemplateList(setMediaAssets, urlTemplateId || null)
+
+  /* ── 保存 ── */
+  const {
+    saveModalOpen,
+    setSaveModalOpen,
+    draftName,
+    setDraftName,
+    draftCategory,
+    setDraftCategory,
+    draftTags,
+    setDraftTags,
+    saveLoading,
+    handleOpenSaveModal,
+    handleSave,
+  } = useTemplateSave({
+    currentMode,
+    clips,
+    totalDuration,
+    titleConfig,
+    subtitleSettings,
+    bgmSettings,
+    watermarkSettings,
+    introOutroSettings,
+    pipSettings,
+    filterSettings,
+    chromaKeySettings,
+    stickerSettings,
+    coverConfig,
+    loadedTemplateId,
+    loadTemplates,
   })
 
-  const currentTemplate = templates.find((t) => t.id === loadedTemplateId) || null
+  /* ── 模板详情加载 ── */
+  useTemplateDetail({
+    loadedTemplateId,
+    resetClips,
+    setCurrentMode,
+    setTitleConfig,
+    setSubtitleSettings,
+    setBgmSettings,
+    setDraftName,
+    setDraftCategory,
+    setDraftTags,
+  })
 
-  /* ──────────── 加载 ──────────── */
-
-  /**
-   * 并行加载模板列表、分类、素材库
-   * 首次挂载时调用，三个接口无依赖关系，用 Promise.all 并发
-   */
-  const loadTemplates = useCallback(async () => {
-    setLoadingTemplates(true)
-    try {
-      const [tpls, cats, assets] = await Promise.all([
-        getEditingTemplates(),
-        getTemplateCategories(),
-        getMediaAssets(),
-      ])
-      setTemplates(tpls)
-      setCategories(cats)
-      setMediaAssets(assets)
-    } catch {
-      message.error("加载模板失败")
-    } finally {
-      setLoadingTemplates(false)
-    }
-  }, [setMediaAssets])
-
-  useEffect(() => {
-    loadTemplates()
-  }, [loadTemplates])
-
-  /**
-   * 加载模板详情并初始化片段列表
-   * 将后端 segments 映射为前端 ClipData，取 duration_min/max 均值作为默认时长
-   * 同时还原标题/字幕/BGM 配置
-   */
-  useEffect(() => {
-    if (!loadedTemplateId) return
-    getEditingTemplate(loadedTemplateId)
-      .then((tpl) => {
-        if (!tpl) return
-        setCurrentMode(tpl.mode)
-        const mapped: ClipData[] = tpl.segments.map((seg, idx) => ({
-          id: seg.id || `seg-${idx}`,
-          template_segment_id: seg.id || `seg-${idx}`,
-          type: (seg.material_type === "voiceover" ? "voice" : "pip") as ClipType,
-          duration: (seg.duration_min + seg.duration_max) / 2,
-          startOffset: 0,
-          script_text: "",
-          order: seg.segment_order,
-        }))
-        resetClips(mapped)
-
-        setTitleConfig({
-          ai_auto_select: tpl.title_config.ai_auto_select,
-          content: tpl.title_config.content,
-          position: tpl.title_config.position,
-          font_preset: tpl.title_config.font_preset,
-          font_size: tpl.title_config.font_size,
-          font_color: tpl.title_config.font_color || "#ffffff",
-        })
-        setSubtitleSettings((prev) => ({
-          ...prev,
-          enabled: tpl.subtitle_config.enabled,
-          position: (tpl.subtitle_config.position || "bottom") as SubtitleStyleConfig["position"],
-          font: tpl.subtitle_config.font,
-          fontSize: tpl.subtitle_config.size,
-          fontColor: tpl.subtitle_config.color || "#ffffff",
-          animation: tpl.subtitle_config.animation,
-        }))
-        setBgmSettings((prev) => ({
-          ...prev,
-          enabled: tpl.bgm_config.enabled,
-          music_id: tpl.bgm_config.music_id || "",
-        }))
-        setDraftName(tpl.name)
-        setDraftCategory(tpl.category)
-        setDraftTags(tpl.tags.join(", "))
-      })
-      .catch(() => message.error("加载模板详情失败"))
-  }, [loadedTemplateId, resetClips, setTitleConfig, setSubtitleSettings, setBgmSettings])
-
-  /**
-   * 加载已有模板草稿数据到编辑器
-   * 从列表页"编辑"按钮进入时，URL 带 planId，需要还原计划配置
-   */
-  useEffect(() => {
-    if (!loadedPlanId) return
-
-    // 并行加载计划基本信息 + 片段列表
-    Promise.all([
-      getEditPlan(loadedPlanId),
-      getEditPlanClips(loadedPlanId, { limit: 500 }).catch(() => ({
-        items: [],
-        total: 0,
-      })),
-    ])
-      .then(([plan, clipsRes]) => {
-        // 设置关联的模板（触发模板加载 effect）
-        setLoadedTemplateId(plan.template_id)
-
-        // 还原基本信息
-        setDraftName(plan.name)
-
-        // 还原 config 中的编辑器状态
-        const cfg = plan.config
-        if (cfg.title_config) {
-          setTitleConfig({
-            ai_auto_select: cfg.title_config!.ai_auto_select,
-            content: cfg.title_config!.content,
-            position: cfg.title_config!.position,
-            font_preset: cfg.title_config!.font_preset,
-            font_size: cfg.title_config!.font_size,
-            font_color: cfg.title_config!.font_color || "#ffffff",
-          })
-        }
-        if (cfg.subtitle_config) {
-          setSubtitleSettings((prev) => ({
-            ...prev,
-            enabled: cfg.subtitle_config!.enabled,
-            position: (cfg.subtitle_config!.position ||
-              "bottom") as SubtitleStyleConfig["position"],
-            font: cfg.subtitle_config!.font,
-            fontSize: cfg.subtitle_config!.size,
-            fontColor: cfg.subtitle_config!.color || "#ffffff",
-            animation: cfg.subtitle_config!.animation,
-          }))
-        }
-        if (cfg.bgm_config) {
-          setBgmSettings((prev) => ({
-            ...prev,
-            enabled: cfg.bgm_config!.enabled,
-            music_id: cfg.bgm_config!.music_id || "",
-          }))
-        }
-        // 还原封面配置
-        if (cfg.cover_config) {
-          setCoverConfig((prev) => ({
-            ...prev,
-            enabled: cfg.cover_config!.enabled ?? prev.enabled,
-            mode: (cfg.cover_config!.mode as CoverConfig["mode"]) || prev.mode,
-            frame_time: cfg.cover_config!.frame_time ?? prev.frame_time,
-            upload_url: cfg.cover_config!.upload_url || prev.upload_url,
-            thumbnail_url: cfg.cover_config!.thumbnail_url || prev.thumbnail_url,
-            ai_suggested_time: cfg.cover_config!.ai_suggested_time ?? prev.ai_suggested_time,
-          }))
-        }
-
-        // 还原片段：优先从后端 clips 表，其次从 config.segments 兜底
-        const backendClips = clipsRes?.items || []
-        if (backendClips.length > 0) {
-          // 从后端 clips 表还原
-          const sorted = [...backendClips].sort((a, b) => a.order - b.order)
-          const mapped: ClipData[] = sorted.map((clip) => ({
-            id: clip.id,
-            template_segment_id: (clip.config?.template_segment_id as string) || "",
-            type: (clip.clip_type === "voiceover" ? "voice" : "pip") as ClipType,
-            duration: clip.duration || 3,
-            startOffset: 0,
-            script_text: clip.text_content || "",
-            order: clip.order,
-            media_asset_id: clip.asset_id || undefined,
-            transition:
-              clip.transition_effect && clip.transition_effect !== "none"
-                ? {
-                    type: clip.transition_effect as TransitionEffect["type"],
-                    duration: clip.transition_duration || 0.3,
-                  }
-                : undefined,
-            speed: clip.playback_speed
-              ? { rate: clip.playback_speed, pitchCorrection: true }
-              : undefined,
-            tts_config: (clip.config?.tts_config as TtsConfig) || undefined,
-            trim_config: (clip.config?.trim_config as TrimConfig) || undefined,
-          }))
-          setTimeout(() => resetClips(mapped), 100)
-        } else if (cfg.segments && cfg.segments.length > 0) {
-          // 兜底：从 config.segments 还原（老数据兼容）
-          const mapped: ClipData[] = cfg.segments.map((seg, idx) => ({
-            id: `seg-${idx}`,
-            template_segment_id: `seg-${idx}`,
-            type: (seg.material_type === "voiceover" ? "voice" : "pip") as ClipType,
-            duration: (seg.duration_min + seg.duration_max) / 2,
-            startOffset: 0,
-            script_text: "",
-            order: seg.segment_order,
-            transition: seg.transition
-              ? {
-                  type: seg.transition.type as TransitionEffect["type"],
-                  duration: seg.transition.duration,
-                }
-              : undefined,
-            speed: seg.playback_speed
-              ? { rate: seg.playback_speed, pitchCorrection: true }
-              : undefined,
-            tts_config: seg.tts_config
-              ? { ...seg.tts_config, mode: seg.tts_config.mode as TtsMode }
-              : undefined,
-            trim_config: seg.trim_config || undefined,
-          }))
-          setTimeout(() => resetClips(mapped), 100)
-        }
-      })
-      .catch(() => message.error("加载模板草稿失败"))
-  }, [
+  /* ── 计划草稿加载 ── */
+  usePlanLoading({
     loadedPlanId,
     resetClips,
+    setLoadedTemplateId,
+    setDraftName,
     setTitleConfig,
     setSubtitleSettings,
     setBgmSettings,
     setCoverConfig,
-  ])
+  })
 
-  /* ──────────── 事件 ──────────── */
+  /* ── 事件 ── */
+  const handleLoadTemplate = useCallback(
+    (templateId: string) => {
+      setLoadedTemplateId(templateId)
+      setSelectedClipId(null)
+    },
+    [setLoadedTemplateId, setSelectedClipId],
+  )
 
-  const handleLoadTemplate = (templateId: string) => {
-    setLoadedTemplateId(templateId)
-    setSelectedClipId(null)
-  }
-
-  const handleModeChange = (mode: TemplateMode) => {
-    setCurrentMode(mode)
-    // 切换纯单类型模式时，自动转换所有已有片段的类型
-    if (mode === "voice_over") {
-      setClips((prev) => prev.map((c) => ({ ...c, type: "voice" as const })))
-    } else if (mode === "pip") {
-      setClips((prev) => prev.map((c) => ({ ...c, type: "pip" as const })))
-    }
-    // 混合模式(voice_pip)和一镜到底(one_take)不自动转换，保留原有类型
-  }
-
-  const handleOpenSaveModal = () => {
-    setSaveModalOpen(true)
-  }
-
-  const handleSave = async () => {
-    if (!draftName.trim()) {
-      message.warning("请输入模板名称")
-      return
-    }
-    setSaveLoading(true)
-    try {
-      const payload: SaveTemplatePayload = {
-        name: draftName,
-        mode: currentMode,
-        category: draftCategory,
-        tags: draftTags
-          .split(",")
-          .map((t) => t.trim())
-          .filter(Boolean),
-        title_config: titleConfig,
-        subtitle_config: {
-          enabled: subtitleSettings.enabled,
-          position: subtitleSettings.position,
-          font: subtitleSettings.font,
-          color: subtitleSettings.fontColor,
-          size: subtitleSettings.fontSize,
-          animation: subtitleSettings.animation,
-        },
-        bgm_config: {
-          enabled: bgmSettings.enabled,
-          music_id: bgmSettings.music_id,
-        },
-        estimated_duration: totalDuration,
-        segments: clips.map((c, i) => ({
-          segment_order: i,
-          duration_min: Math.max(1, c.duration - 2),
-          duration_max: c.duration + 2,
-          material_type: c.type === "voice" ? "voiceover" : "video",
-          transition: c.transition
-            ? { type: c.transition.type, duration: c.transition.duration }
-            : undefined,
-          playback_speed: c.speed ? c.speed.rate : undefined,
-          tts_config: c.tts_config
-            ? {
-                mode: c.tts_config.mode,
-                text: c.tts_config.text,
-                voice_id: c.tts_config.voice_id,
-                speed: c.tts_config.speed,
-                pitch: c.tts_config.pitch,
-                volume: c.tts_config.volume,
-                subtitle_sync: c.tts_config.subtitle_sync,
-              }
-            : undefined,
-          trim_config: c.trim_config
-            ? {
-                start_time: c.trim_config.start_time,
-                end_time: c.trim_config.end_time,
-              }
-            : undefined,
-        })),
-        watermark_config: { ...watermarkSettings },
-        intro_outro_config: { ...introOutroSettings },
-        pip_config: { ...pipSettings },
-        filter_config: { ...filterSettings },
-        green_screen_config: { ...chromaKeySettings },
-        sticker_config: { ...stickerSettings },
-        cover_config: { ...coverConfig },
+  const handleModeChange = useCallback(
+    (mode: TemplateMode) => {
+      setCurrentMode(mode)
+      if (mode === "voice_over") {
+        setClips((prev) => prev.map((c) => ({ ...c, type: "voice" as const })))
+      } else if (mode === "pip") {
+        setClips((prev) => prev.map((c) => ({ ...c, type: "pip" as const })))
       }
-      if (loadedTemplateId) {
-        await updateEditingTemplate(loadedTemplateId, payload)
-      } else {
-        await createEditingTemplate(payload)
-      }
-      message.success(loadedTemplateId ? "模板保存成功" : "模板创建成功")
-      setSaveModalOpen(false)
-      loadTemplates()
-    } catch {
-      message.error("保存失败")
-    } finally {
-      setSaveLoading(false)
-    }
-  }
+    },
+    [setClips],
+  )
 
   return {
     // state