Merge branch 'develop' into refactor/template-editor-api

将 template-editor.ts 单文件拆分为目录结构，按业务模块组织：

- types.ts — 所有类型定义（EditPlan/Clip/MediaAsset 等）
- constants.ts — 常量（TRANSITION_OPTIONS/QUALITY_OPTIONS 等）
- editPlans.ts — 模板草稿 CRUD + 生成 + 复制 + 取消
- clips.ts — 片段 CRUD + 批量操作（重排序/批量删除/从素材创建）
- aiFeatures.ts — AI 推荐 + AI 封面生成
- mediaAssets.ts — 素材库 API + AssetItem→MediaAsset 映射
- index.ts — 统一入口，re-export 所有类型/常量/函数

入口文件从 744 行精简到 88 行（仅 re-export），
各模块职责单一，便于维护和 tree-shaking。
导入路径 @/api/template-editor 保持向后兼容。

apps/web/src/api/template-editor.ts

@@ -1,744 +0,0 @@
-/**
- * 模板草稿 API — 对接后端 Template Editor Schema
- * 字段名严格匹配后端 API 响应
- */
-import apiClient from "./client"
-import type { AssetItem } from "./assets"
-import type {
-  WatermarkConfig,
-  IntroOutroConfig,
-  PipConfig,
-  FilterConfig,
-  ChromaKeyConfig,
-  StickerConfig,
-  CoverConfig,
-} from "@/pages/editing-planner/types"
-
-/* ============================================================
- * 后端 API 类型（严格匹配后端 Schema）
- * ============================================================ */
-
-/** 模板草稿状态枚举 */
-export type EditPlanStatus =
-  "draft" | "editing" | "rendering" | "completed" | "failed" | "cancelled"
-
-/** 标题配置（对齐后端 title_config） */
-export interface TitleConfig {
-  ai_auto_select: boolean
-  content: string
-  font_preset: string
-  font_color: string
-  font_size: number
-  position: string
-}
-
-/** 字幕配置 */
-export interface SubtitleConfig {
-  enabled: boolean
-  position: string
-  font: string
-  color: string
-  size: number
-  animation: string
-}
-
-/** BGM 配置 */
-export interface BgmConfig {
-  enabled: boolean
-  music_id: string
-}
-
-/** 片段 TTS 配置 */
-export interface SegmentTtsConfig {
-  mode: string
-  text: string
-  voice_id: string
-  speed: number
-  pitch: number
-  volume: number
-  subtitle_sync: boolean
-}
-
-/** 片段裁剪配置 */
-export interface SegmentTrimConfig {
-  start_time: number
-  end_time: number
-}
-
-/** 片段转场配置 */
-export interface SegmentTransitionConfig {
-  type: string
-  duration: number
-}
-
-/** 模板草稿中的单个片段（config 内部 segments 项） */
-export interface EditPlanSegment {
-  segment_order: number
-  duration_min: number
-  duration_max: number
-  material_type: string
-  transition?: SegmentTransitionConfig
-  playback_speed?: number
-  tts_config?: SegmentTtsConfig
-  trim_config?: SegmentTrimConfig
-}
-
-/** 模板草稿 config 完整类型（对齐后端 config JSON 结构） */
-export interface EditPlanConfig {
-  title_config?: TitleConfig
-  subtitle_config?: SubtitleConfig
-  bgm_config?: BgmConfig
-  estimated_duration?: number
-  segments?: EditPlanSegment[]
-  watermark_config?: WatermarkConfig
-  intro_outro_config?: IntroOutroConfig
-  pip_config?: PipConfig
-  filter_config?: FilterConfig
-  green_screen_config?: ChromaKeyConfig
-  sticker_config?: StickerConfig
-  cover_config?: CoverConfig
-  /** 前端扩展：关联的素材 ID 列表 */
-  asset_ids?: string[]
-  /** 配音 ID */
-  voice_id?: string
-  /** 克隆音色档案 ID */
-  voice_clone_profile_id?: string
-  /** 自定义配音音频 URL */
-  custom_audio_url?: string
-  /** 自定义配音文本 */
-  custom_text?: string
-  /** 视频比例 */
-  ratio?: string
-  /** 视频风格 */
-  style?: string
-  /** 目标时长（秒） */
-  duration?: number
-  /** 是否自动生成字幕 */
-  auto_subtitles?: boolean
-  /** 是否启用 BGM */
-  bgm?: boolean
-  /** 生成数量 */
-  generate_count?: number
-  /** 素材模式 */
-  material_mode?: string
-}
-
-/** 模板草稿（后端响应） */
-export interface EditPlan {
-  id: string
-  template_id: string
-  name: string
-  status: EditPlanStatus
-  total_duration: number
-  /** 生成视频数量（后端 EditPlanResponse.result_count） */
-  result_count: number
-  config: EditPlanConfig
-  created_at: string
-  updated_at: string
-}
-
-/** 创建模板草稿请求（后端要求 template_id + name 必填） */
-export interface CreateEditPlanRequest {
-  template_id: string
-  name: string
-  config?: EditPlanConfig
-  total_duration?: number
-  /** 来源模板草稿 ID（从模板编辑器跳转到智能剪辑时关联） */
-  source_edit_plan_id?: string
-}
-
-/** 更新模板草稿请求 */
-export interface UpdateEditPlanRequest {
-  name?: string
-  config?: EditPlanConfig
-  total_duration?: number
-  status?: EditPlanStatus
-}
-
-/** 生成响应 */
-export interface GenerateResponse {
-  plan_id: string
-  plan_status: EditPlanStatus
-  generation_task_id: string
-  clip_count: number
-}
-
-/** 模板草稿关联的生成记录（实际是 GenerationTask 对象） */
-export interface EditPlanGeneration {
-  id: string // 即 generation_task_id
-  source_edit_plan_id: string
-  template_id: string
-  asset_ids: string[]
-  status: EditPlanStatus
-  progress: number
-  result_count: number
-  error_message: string
-  error_info: Record<string, unknown>
-  logs: Array<Record<string, unknown>>
-  retry_count: number
-  created_at?: string
-  updated_at?: string
-}
-
-/** 片段生成状态 */
-export interface ClipStatusItem {
-  clip_id: string
-  clip_type: string
-  order: number
-  status: string
-  asset_id?: string
-  text_content?: string
-  duration?: number
-  error_message?: string
-}
-
-/** 生成状态轮询响应 */
-export interface GenerationStatusResponse {
-  plan_id: string
-  plan_status: EditPlanStatus
-  generation_task_id?: string
-  error_message?: string
-  clips: ClipStatusItem[]
-  error?: string
-  message?: string
-}
-
-/** 生成视频详情（对应后端 GeneratedVideoResponse） */
-export interface GeneratedVideo {
-  id: string
-  project_id?: string
-  generation_task_id?: string
-  name: string
-  file_url: string
-  file_size?: number
-  duration?: number
-  thumbnail_url?: string
-  width?: number
-  height?: number
-  fps?: number
-  status: string
-  review_status?: string
-  download_url?: string
-  created_at?: string
-  updated_at?: string
-}
-
-/* ============================================================
- * AI 推荐 & 封面生成（任务 3.09）
- * ============================================================ */
-
-/** AI 推荐请求 */
-export interface AIRecommendRequest {
-  asset_ids: string[]
-  editing_mode?: string
-  target_duration?: number
-}
-
-/** AI 推荐单个片段 */
-export interface AIRecommendClipItem {
-  clip_type: string
-  order: number
-  text_content: string
-  duration: number
-  transition_effect: string
-  asset_id: string
-  start_time: number
-  config: EditPlanConfig
-}
-
-/** AI 推荐响应 */
-export interface AIRecommendResponse {
-  plan_id: string
-  clips: AIRecommendClipItem[]
-  config: EditPlanConfig
-  total_duration: number
-  confidence: number
-}
-
-/** AI 封面生成请求 */
-export interface GenerateCoverRequest {
-  asset_ids: string[]
-  cover_type?: "ai_frame" | "manual" | "upload" | "ai_regenerate"
-  frame_time?: number
-}
-
-/** AI 封面生成响应 */
-export interface GenerateCoverResponse {
-  plan_id: string
-  cover: CoverResult
-}
-
-/** 封面生成结果 */
-export interface CoverResult {
-  scheme?: string
-  asset_id?: string
-  frame_time?: number
-  thumbnail_url?: string
-}
-
-/* ============================================================
- * 前端 UI 类型（EditingPlanner 组件依赖，保留兼容）
- * ============================================================ */
-
-/** 转场效果（14 种预设） */
-export interface TransitionEffect {
-  type:
-    | "none"
-    | "cut"
-    | "fade"
-    | "dissolve"
-    | "zoom"
-    | "slide_left"
-    | "slide_right"
-    | "slide_up"
-    | "slide_down"
-    | "wipe_left"
-    | "wipe_right"
-    | "wipe_up"
-    | "wipe_down"
-    | "circlecrop"
-    | "rectcrop"
-  duration: number // 转场时长（秒）
-  /** 播放速度倍率 */
-  playback_speed?: number
-}
-
-/** 素材库资产（UI 层类型，映射自后端 AssetResponse） */
-export interface MediaAsset {
-  id: string
-  name: string
-  type: "video" | "image" | "audio"
-  /** 缩略图 URL */
-  thumbnail_url?: string
-  /** 时长（秒），仅 video/audio */
-  duration?: number
-  /** 文件大小（字节） */
-  size?: number
-  /** 标签 */
-  tags: string[]
-  created_at: string
-  /** 质量分 0-100 */
-  quality_score?: number
-  /** 分类状态 */
-  classification_status?: "pending" | "processing" | "completed" | "failed"
-}
-
-/* ============================================================
- * API 函数 — 严格对接后端
- * ============================================================ */
-
-/** 模板草稿列表查询参数 */
-export interface EditPlanListParams {
-  page?: number
-  page_size?: number
-  template_id?: string
-  status?: string
-}
-
-/** 模板草稿列表分页响应 */
-export interface EditPlanListResponse {
-  items: EditPlan[]
-  total: number
-  page: number
-  page_size: number
-}
-
-/** 获取模板草稿列表（支持分页和筛选） */
-export async function getEditPlans(params?: EditPlanListParams): Promise<EditPlanListResponse> {
-  const response = await apiClient.get<EditPlanListResponse>("/templates/drafts", {
-    params,
-  })
-  return response.data
-}
-
-/** 获取单个模板草稿 */
-export async function getEditPlan(templateId: string): Promise<EditPlan> {
-  const response = await apiClient.get(`/templates/${templateId}/editor`)
-  return response.data
-}
-
-/** 创建模板草稿 */
-export async function createEditPlan(data: CreateEditPlanRequest): Promise<EditPlan> {
-  const response = await apiClient.post("/templates/drafts", data)
-  return response.data
-}
-
-/** 更新模板草稿 */
-export async function updateEditPlan(
-  templateId: string,
-  data: UpdateEditPlanRequest,
-): Promise<EditPlan> {
-  const response = await apiClient.put(`/templates/${templateId}/editor`, data)
-  return response.data
-}
-
-/** 删除模板草稿 */
-export async function deleteEditPlan(templateId: string): Promise<void> {
-  await apiClient.delete(`/templates/${templateId}/editor`)
-}
-
-/** 触发生成 */
-export async function generateEditPlan(templateId: string): Promise<GenerateResponse> {
-  const response = await apiClient.post(`/templates/${templateId}/editor/generate`)
-  return response.data
-}
-
-/** 获取生成状态（轮询用） */
-export async function getGenerationStatus(templateId: string): Promise<GenerationStatusResponse> {
-  const response = await apiClient.get(`/templates/${templateId}/editor/generation-status`)
-  return response.data
-}
-
-/** AI 推荐片段方案 */
-export async function aiRecommendClips(
-  templateId: string,
-  data: AIRecommendRequest,
-): Promise<AIRecommendResponse> {
-  const response = await apiClient.post(`/templates/${templateId}/editor/ai-recommend`, data)
-  return response.data
-}
-
-/** AI 生成封面 */
-export async function generateCover(
-  templateId: string,
-  data: GenerateCoverRequest,
-): Promise<GenerateCoverResponse> {
-  const response = await apiClient.post(`/templates/${templateId}/editor/generate-cover`, data)
-  return response.data
-}
-
-/** 获取模板草稿关联的生成记录 */
-export async function getEditPlanGenerations(templateId: string): Promise<EditPlanGeneration[]> {
-  const response = await apiClient.get(`/templates/${templateId}/editor/generations`)
-  return response.data.items || []
-}
-
-/** 获取生成任务的视频结果列表 */
-export async function getGenerationTaskResults(taskId: string): Promise<GeneratedVideo[]> {
-  const response = await apiClient.get(`/generation/tasks/${taskId}/results`)
-  return response.data.items || response.data || []
-}
-
-/** 取消生成任务 */
-export async function cancelGeneration(templateId: string): Promise<void> {
-  await apiClient.post(`/templates/${templateId}/editor/cancel`)
-}
-
-/* ============================================================
- * 片段 CRUD（后端 EditPlanClip 独立表）
- * ============================================================ */
-
-/** 片段状态 */
-export type EditPlanClipStatus = "pending" | "processing" | "ready" | "failed"
-
-/** 剪辑片段（后端响应） */
-export interface EditPlanClip {
-  id: string
-  plan_id: string
-  clip_type: string // main / intro / outro / overlay / background / b_roll 等
-  order: number
-  asset_id: string
-  text_content: string
-  start_time: number
-  duration: number
-  transition_effect: string
-  transition_duration: number
-  playback_speed: number
-  status: EditPlanClipStatus
-  config: Record<string, unknown>
-  created_at?: string
-  updated_at?: string
-}
-
-/** 创建片段请求 */
-export interface CreateEditPlanClipRequest {
-  clip_type: string
-  order: number
-  asset_id?: string
-  text_content?: string
-  start_time?: number
-  duration?: number
-  transition_effect?: string
-  transition_duration?: number
-  playback_speed?: number
-  config?: Record<string, unknown>
-}
-
-/** 更新片段请求 */
-export interface UpdateEditPlanClipRequest {
-  clip_type?: string
-  order?: number
-  asset_id?: string
-  text_content?: string
-  start_time?: number
-  duration?: number
-  transition_effect?: string
-  transition_duration?: number
-  playback_speed?: number
-  config?: Record<string, unknown>
-}
-
-/** 片段列表响应 */
-export interface EditPlanClipListResponse {
-  items: EditPlanClip[]
-  total: number
-}
-
-/** 片段列表查询参数 */
-export interface EditPlanClipListParams {
-  status?: string
-  skip?: number
-  limit?: number
-}
-
-/** 获取片段列表 */
-export async function getEditPlanClips(
-  templateId: string,
-  params?: EditPlanClipListParams,
-): Promise<EditPlanClipListResponse> {
-  const response = await apiClient.get<EditPlanClipListResponse>(
-    `/templates/${templateId}/editor/clips`,
-    {
-      params,
-    },
-  )
-  return response.data
-}
-
-/** 获取单个片段详情 */
-export async function getEditPlanClip(templateId: string, clipId: string): Promise<EditPlanClip> {
-  const response = await apiClient.get<EditPlanClip>(
-    `/templates/${templateId}/editor/clips/${clipId}`,
-  )
-  return response.data
-}
-
-/** 创建片段 */
-export async function createEditPlanClip(
-  templateId: string,
-  data: CreateEditPlanClipRequest,
-): Promise<EditPlanClip> {
-  const response = await apiClient.post<EditPlanClip>(`/templates/${templateId}/editor/clips`, data)
-  return response.data
-}
-
-/** 更新片段 */
-export async function updateEditPlanClip(
-  templateId: string,
-  clipId: string,
-  data: UpdateEditPlanClipRequest,
-): Promise<EditPlanClip> {
-  const response = await apiClient.put<EditPlanClip>(
-    `/templates/${templateId}/editor/clips/${clipId}`,
-    data,
-  )
-  return response.data
-}
-
-/** 删除片段 */
-export async function deleteEditPlanClip(templateId: string, clipId: string): Promise<void> {
-  await apiClient.delete(`/templates/${templateId}/editor/clips/${clipId}`)
-}
-
-/* ============================================================
- * 片段批量操作
- * ============================================================ */
-
-/** 重排序条目 */
-export interface ClipReorderItem {
-  clip_id: string
-  new_order: number
-}
-
-/** 重排序响应 */
-export interface ClipReorderResponse {
-  success: boolean
-  updated_count: number
-  message: string
-}
-
-/** 批量删除响应 */
-export interface ClipBatchDeleteResponse {
-  success: boolean
-  deleted_count: number
-  message: string
-}
-
-/** 从素材批量创建响应 */
-export interface ClipsFromAssetsResponse {
-  success: boolean
-  created_count: number
-  message: string
-  clip_ids: string[]
-}
-
-/** 片段重排序（拖拽排序后一次性提交） */
-export async function reorderEditPlanClips(
-  templateId: string,
-  items: ClipReorderItem[],
-): Promise<ClipReorderResponse> {
-  const response = await apiClient.post<ClipReorderResponse>(
-    `/templates/${templateId}/editor/clips/reorder`,
-    { items },
-  )
-  return response.data
-}
-
-/** 批量删除片段 */
-export async function batchDeleteEditPlanClips(
-  templateId: string,
-  clipIds: string[],
-): Promise<ClipBatchDeleteResponse> {
-  const response = await apiClient.post<ClipBatchDeleteResponse>(
-    `/templates/${templateId}/editor/clips/batch-delete`,
-    { clip_ids: clipIds },
-  )
-  return response.data
-}
-
-/** 从素材批量创建片段（追加到时间线末尾） */
-export async function createClipsFromAssets(
-  templateId: string,
-  assetIds: string[],
-  clipType = "main",
-): Promise<ClipsFromAssetsResponse> {
-  const response = await apiClient.post<ClipsFromAssetsResponse>(
-    `/templates/${templateId}/editor/clips/from-assets`,
-    { asset_ids: assetIds, clip_type: clipType },
-  )
-  return response.data
-}
-
-/* ============================================================
- * 复制计划
- * ============================================================ */
-
-/** 复制计划请求 */
-export interface CopyEditPlanRequest {
-  name?: string
-  project_id?: string
-}
-
-/** 复制模板草稿（含所有片段配置） */
-export async function copyEditPlan(
-  templateId: string,
-  data?: CopyEditPlanRequest,
-): Promise<EditPlan> {
-  const response = await apiClient.post<EditPlan>(
-    `/templates/${templateId}/editor/copy`,
-    data || {},
-  )
-  return response.data
-}
-
-/**
- * 获取素材库列表 — 调用 GET /api/v1/assets?library_id=xxx
- * 将后端 AssetResponse 映射为前端 MediaAsset 类型
- */
-export async function getMediaAssets(libraryId?: string): Promise<MediaAsset[]> {
-  const response = await apiClient.get("/assets", {
-    params: libraryId ? { library_id: libraryId } : undefined,
-  })
-  const items: AssetItem[] = response.data.items || []
-  return items.map(mapAssetToMediaAsset)
-}
-
-/** 获取单个素材 */
-export async function getMediaAsset(id: string): Promise<MediaAsset> {
-  const response = await apiClient.get(`/assets/${id}`)
-  return mapAssetToMediaAsset(response.data)
-}
-
-/* ============================================================
- * 映射函数：AssetResponse → MediaAsset
- * ============================================================ */
-
-function inferMediaType(mimeType: string): "video" | "image" | "audio" {
-  if (mimeType.startsWith("video/")) return "video"
-  if (mimeType.startsWith("image/")) return "image"
-  return "audio"
-}
-
-function mapAssetToMediaAsset(asset: AssetItem): MediaAsset {
-  // 优先取顶层 duration，其次从 metadata 回退
-  const metaDuration =
-    typeof asset.metadata?.duration === "number" ? asset.metadata.duration : undefined
-  return {
-    id: asset.id,
-    name: asset.name,
-    type: inferMediaType(asset.mime_type || ""),
-    thumbnail_url: asset.thumbnail_url,
-    duration: asset.duration ?? metaDuration,
-    size: asset.file_size ?? undefined,
-    tags: [],
-    created_at: asset.created_at ?? "",
-    quality_score: asset.quality_score ?? undefined,
-    classification_status: asset.classification_status ?? undefined,
-  }
-}
-
-/* ============================================================
- * 常量
- * ============================================================ */
-
-/** 转场效果选项（14 种预设） */
-export const TRANSITION_OPTIONS: {
-  value: TransitionEffect["type"]
-  label: string
-  icon: string
-}[] = [
-  { value: "none", label: "无转场", icon: "⊘" },
-  { value: "cut", label: "硬切", icon: "✂" },
-  { value: "fade", label: "淡入淡出", icon: "◐" },
-  { value: "dissolve", label: "溶解", icon: "◈" },
-  { value: "zoom", label: "缩放", icon: "⊕" },
-  { value: "slide_left", label: "左滑", icon: "←" },
-  { value: "slide_right", label: "右滑", icon: "→" },
-  { value: "slide_up", label: "上滑", icon: "↑" },
-  { value: "slide_down", label: "下滑", icon: "↓" },
-  { value: "wipe_left", label: "左擦除", icon: "▸|" },
-  { value: "wipe_right", label: "右擦除", icon: "|◂" },
-  { value: "wipe_up", label: "上擦除", icon: "▴̄" },
-  { value: "wipe_down", label: "下擦除", icon: "▾̄" },
-  { value: "circlecrop", label: "圆形裁切", icon: "●" },
-  { value: "rectcrop", label: "矩形裁切", icon: "■" },
-]
-
-/** 素材类型标签 */
-export const MATERIAL_TYPE_LABELS: Record<string, string> = {
-  video: "视频",
-  image: "图片",
-  audio: "音频",
-  voiceover: "配音",
-}
-
-/** 素材类型图标 */
-export const MATERIAL_TYPE_ICONS: Record<string, string> = {
-  video: "🎬",
-  image: "🖼️",
-  audio: "🎵",
-  voiceover: "🎙️",
-}
-
-/** 计划状态标签 */
-export const PLAN_STATUS_LABELS: Record<EditPlanStatus, string> = {
-  draft: "草稿",
-  editing: "编辑中",
-  rendering: "渲染中",
-  completed: "已完成",
-  failed: "失败",
-  cancelled: "已取消",
-}
-
-/** 质量分筛选选项 */
-export const QUALITY_OPTIONS: {
-  value: string
-  label: string
-  min?: number
-  max?: number
-}[] = [
-  { value: "all", label: "全部质量" },
-  { value: "high", label: "高质量 (80-100)", min: 80, max: 100 },
-  { value: "medium", label: "中质量 (50-79)", min: 50, max: 79 },
-  { value: "low", label: "低质量 (0-49)", min: 0, max: 49 },
-]

apps/web/src/api/template-editor/aiFeatures.ts

@@ -0,0 +1,28 @@
+/**
+ * AI 推荐 + 封面生成 API
+ */
+import apiClient from "../client"
+import type {
+  AIRecommendRequest,
+  AIRecommendResponse,
+  GenerateCoverRequest,
+  GenerateCoverResponse,
+} from "./types"
+
+/** AI 推荐片段方案 */
+export async function aiRecommendClips(
+  templateId: string,
+  data: AIRecommendRequest,
+): Promise<AIRecommendResponse> {
+  const response = await apiClient.post(`/templates/${templateId}/editor/ai-recommend`, data)
+  return response.data
+}
+
+/** AI 生成封面 */
+export async function generateCover(
+  templateId: string,
+  data: GenerateCoverRequest,
+): Promise<GenerateCoverResponse> {
+  const response = await apiClient.post(`/templates/${templateId}/editor/generate-cover`, data)
+  return response.data
+}

apps/web/src/api/template-editor/clips.ts

@@ -0,0 +1,99 @@
+/**
+ * 片段 CRUD + 批量操作 API
+ */
+import apiClient from "../client"
+import type {
+  EditPlanClip,
+  EditPlanClipListParams,
+  EditPlanClipListResponse,
+  CreateEditPlanClipRequest,
+  UpdateEditPlanClipRequest,
+  ClipReorderItem,
+  ClipReorderResponse,
+  ClipBatchDeleteResponse,
+  ClipsFromAssetsResponse,
+} from "./types"
+
+/** 获取片段列表 */
+export async function getEditPlanClips(
+  templateId: string,
+  params?: EditPlanClipListParams,
+): Promise<EditPlanClipListResponse> {
+  const response = await apiClient.get<EditPlanClipListResponse>(
+    `/templates/${templateId}/editor/clips`,
+    { params },
+  )
+  return response.data
+}
+
+/** 获取单个片段详情 */
+export async function getEditPlanClip(templateId: string, clipId: string): Promise<EditPlanClip> {
+  const response = await apiClient.get<EditPlanClip>(
+    `/templates/${templateId}/editor/clips/${clipId}`,
+  )
+  return response.data
+}
+
+/** 创建片段 */
+export async function createEditPlanClip(
+  templateId: string,
+  data: CreateEditPlanClipRequest,
+): Promise<EditPlanClip> {
+  const response = await apiClient.post<EditPlanClip>(`/templates/${templateId}/editor/clips`, data)
+  return response.data
+}
+
+/** 更新片段 */
+export async function updateEditPlanClip(
+  templateId: string,
+  clipId: string,
+  data: UpdateEditPlanClipRequest,
+): Promise<EditPlanClip> {
+  const response = await apiClient.put<EditPlanClip>(
+    `/templates/${templateId}/editor/clips/${clipId}`,
+    data,
+  )
+  return response.data
+}
+
+/** 删除片段 */
+export async function deleteEditPlanClip(templateId: string, clipId: string): Promise<void> {
+  await apiClient.delete(`/templates/${templateId}/editor/clips/${clipId}`)
+}
+
+/** 片段重排序（拖拽排序后一次性提交） */
+export async function reorderEditPlanClips(
+  templateId: string,
+  items: ClipReorderItem[],
+): Promise<ClipReorderResponse> {
+  const response = await apiClient.post<ClipReorderResponse>(
+    `/templates/${templateId}/editor/clips/reorder`,
+    { items },
+  )
+  return response.data
+}
+
+/** 批量删除片段 */
+export async function batchDeleteEditPlanClips(
+  templateId: string,
+  clipIds: string[],
+): Promise<ClipBatchDeleteResponse> {
+  const response = await apiClient.post<ClipBatchDeleteResponse>(
+    `/templates/${templateId}/editor/clips/batch-delete`,
+    { clip_ids: clipIds },
+  )
+  return response.data
+}
+
+/** 从素材批量创建片段（追加到时间线末尾） */
+export async function createClipsFromAssets(
+  templateId: string,
+  assetIds: string[],
+  clipType = "main",
+): Promise<ClipsFromAssetsResponse> {
+  const response = await apiClient.post<ClipsFromAssetsResponse>(
+    `/templates/${templateId}/editor/clips/from-assets`,
+    { asset_ids: assetIds, clip_type: clipType },
+  )
+  return response.data
+}

apps/web/src/api/template-editor/constants.ts

@@ -0,0 +1,66 @@
+/**
+ * 模板编辑器常量
+ */
+import type { TransitionEffect, EditPlanStatus } from "./types"
+
+/** 转场效果选项（14 种预设） */
+export const TRANSITION_OPTIONS: {
+  value: TransitionEffect["type"]
+  label: string
+  icon: string
+}[] = [
+  { value: "none", label: "无转场", icon: "⊘" },
+  { value: "cut", label: "硬切", icon: "✂" },
+  { value: "fade", label: "淡入淡出", icon: "◐" },
+  { value: "dissolve", label: "溶解", icon: "◈" },
+  { value: "zoom", label: "缩放", icon: "⊕" },
+  { value: "slide_left", label: "左滑", icon: "←" },
+  { value: "slide_right", label: "右滑", icon: "→" },
+  { value: "slide_up", label: "上滑", icon: "↑" },
+  { value: "slide_down", label: "下滑", icon: "↓" },
+  { value: "wipe_left", label: "左擦除", icon: "▸|" },
+  { value: "wipe_right", label: "右擦除", icon: "|◂" },
+  { value: "wipe_up", label: "上擦除", icon: "▴̄" },
+  { value: "wipe_down", label: "下擦除", icon: "▾̄" },
+  { value: "circlecrop", label: "圆形裁切", icon: "●" },
+  { value: "rectcrop", label: "矩形裁切", icon: "■" },
+]
+
+/** 素材类型标签 */
+export const MATERIAL_TYPE_LABELS: Record<string, string> = {
+  video: "视频",
+  image: "图片",
+  audio: "音频",
+  voiceover: "配音",
+}
+
+/** 素材类型图标 */
+export const MATERIAL_TYPE_ICONS: Record<string, string> = {
+  video: "🎬",
+  image: "🖼️",
+  audio: "🎵",
+  voiceover: "🎙️",
+}
+
+/** 计划状态标签 */
+export const PLAN_STATUS_LABELS: Record<EditPlanStatus, string> = {
+  draft: "草稿",
+  editing: "编辑中",
+  rendering: "渲染中",
+  completed: "已完成",
+  failed: "失败",
+  cancelled: "已取消",
+}
+
+/** 质量分筛选选项 */
+export const QUALITY_OPTIONS: {
+  value: string
+  label: string
+  min?: number
+  max?: number
+}[] = [
+  { value: "all", label: "全部质量" },
+  { value: "high", label: "高质量 (80-100)", min: 80, max: 100 },
+  { value: "medium", label: "中质量 (50-79)", min: 50, max: 79 },
+  { value: "low", label: "低质量 (0-49)", min: 0, max: 49 },
+]

apps/web/src/api/template-editor/editPlans.ts

@@ -0,0 +1,91 @@
+/**
+ * 模板草稿 CRUD + 生成相关 API
+ */
+import apiClient from "../client"
+import type {
+  EditPlan,
+  EditPlanListParams,
+  EditPlanListResponse,
+  CreateEditPlanRequest,
+  UpdateEditPlanRequest,
+  GenerateResponse,
+  GenerationStatusResponse,
+  EditPlanGeneration,
+  GeneratedVideo,
+  CopyEditPlanRequest,
+} from "./types"
+
+/** 获取模板草稿列表（支持分页和筛选） */
+export async function getEditPlans(params?: EditPlanListParams): Promise<EditPlanListResponse> {
+  const response = await apiClient.get<EditPlanListResponse>("/templates/drafts", {
+    params,
+  })
+  return response.data
+}
+
+/** 获取单个模板草稿 */
+export async function getEditPlan(templateId: string): Promise<EditPlan> {
+  const response = await apiClient.get(`/templates/${templateId}/editor`)
+  return response.data
+}
+
+/** 创建模板草稿 */
+export async function createEditPlan(data: CreateEditPlanRequest): Promise<EditPlan> {
+  const response = await apiClient.post("/templates/drafts", data)
+  return response.data
+}
+
+/** 更新模板草稿 */
+export async function updateEditPlan(
+  templateId: string,
+  data: UpdateEditPlanRequest,
+): Promise<EditPlan> {
+  const response = await apiClient.put(`/templates/${templateId}/editor`, data)
+  return response.data
+}
+
+/** 删除模板草稿 */
+export async function deleteEditPlan(templateId: string): Promise<void> {
+  await apiClient.delete(`/templates/${templateId}/editor`)
+}
+
+/** 触发生成 */
+export async function generateEditPlan(templateId: string): Promise<GenerateResponse> {
+  const response = await apiClient.post(`/templates/${templateId}/editor/generate`)
+  return response.data
+}
+
+/** 获取生成状态（轮询用） */
+export async function getGenerationStatus(templateId: string): Promise<GenerationStatusResponse> {
+  const response = await apiClient.get(`/templates/${templateId}/editor/generation-status`)
+  return response.data
+}
+
+/** 获取模板草稿关联的生成记录 */
+export async function getEditPlanGenerations(templateId: string): Promise<EditPlanGeneration[]> {
+  const response = await apiClient.get(`/templates/${templateId}/editor/generations`)
+  return response.data.items || []
+}
+
+/** 获取生成任务的视频结果列表 */
+export async function getGenerationTaskResults(taskId: string): Promise<GeneratedVideo[]> {
+  const response = await apiClient.get(`/generation/tasks/${taskId}/results`)
+  return response.data.items || response.data || []
+}
+
+/** 取消生成任务 */
+export async function cancelGeneration(templateId: string): Promise<void> {
+  await apiClient.post(`/templates/${templateId}/editor/cancel`)
+}
+
+/** 复制模板草稿（含所有片段配置） */
+export async function copyEditPlan(
+  templateId: string,
+  data?: CopyEditPlanRequest,
+): Promise<EditPlan> {
+  const response = await apiClient.post<EditPlan>(
+    `/templates/${templateId}/editor/copy`,
+    data || {},
+  )
+  return response.data
+}

apps/web/src/api/template-editor/index.ts

@@ -0,0 +1,88 @@
+/**
+ * 模板编辑器 API — 按模块拆分后的统一入口
+ * 保持与原 template-editor.ts 相同的导出结构，向后兼容
+ */
+
+// 类型
+export type {
+  EditPlanStatus,
+  TitleConfig,
+  SubtitleConfig,
+  BgmConfig,
+  SegmentTtsConfig,
+  SegmentTrimConfig,
+  SegmentTransitionConfig,
+  EditPlanSegment,
+  EditPlanConfig,
+  EditPlan,
+  CreateEditPlanRequest,
+  UpdateEditPlanRequest,
+  EditPlanListParams,
+  EditPlanListResponse,
+  GenerateResponse,
+  EditPlanGeneration,
+  ClipStatusItem,
+  GenerationStatusResponse,
+  GeneratedVideo,
+  AIRecommendRequest,
+  AIRecommendClipItem,
+  AIRecommendResponse,
+  GenerateCoverRequest,
+  GenerateCoverResponse,
+  CoverResult,
+  EditPlanClipStatus,
+  EditPlanClip,
+  CreateEditPlanClipRequest,
+  UpdateEditPlanClipRequest,
+  EditPlanClipListResponse,
+  EditPlanClipListParams,
+  ClipReorderItem,
+  ClipReorderResponse,
+  ClipBatchDeleteResponse,
+  ClipsFromAssetsResponse,
+  CopyEditPlanRequest,
+  TransitionEffect,
+  MediaAsset,
+} from "./types"
+
+// 常量
+export {
+  TRANSITION_OPTIONS,
+  MATERIAL_TYPE_LABELS,
+  MATERIAL_TYPE_ICONS,
+  PLAN_STATUS_LABELS,
+  QUALITY_OPTIONS,
+} from "./constants"
+
+// 模板草稿 CRUD + 生成
+export {
+  getEditPlans,
+  getEditPlan,
+  createEditPlan,
+  updateEditPlan,
+  deleteEditPlan,
+  generateEditPlan,
+  getGenerationStatus,
+  getEditPlanGenerations,
+  getGenerationTaskResults,
+  cancelGeneration,
+  copyEditPlan,
+} from "./editPlans"
+
+// 片段 CRUD + 批量操作
+export {
+  getEditPlanClips,
+  getEditPlanClip,
+  createEditPlanClip,
+  updateEditPlanClip,
+  deleteEditPlanClip,
+  reorderEditPlanClips,
+  batchDeleteEditPlanClips,
+  createClipsFromAssets,
+} from "./clips"
+
+// AI 推荐 + 封面生成
+export { aiRecommendClips, generateCover } from "./aiFeatures"
+
+// 素材库
+export { getMediaAssets, getMediaAsset } from "./mediaAssets"

apps/web/src/api/template-editor/mediaAssets.ts

@@ -0,0 +1,44 @@
+/**
+ * 素材库 API（对接 /assets 接口，映射为 MediaAsset 类型）
+ */
+import apiClient from "../client"
+import type { AssetItem } from "../assets"
+import type { MediaAsset } from "./types"
+
+const inferMediaType = (mimeType: string): "video" | "image" | "audio" => {
+  if (mimeType.startsWith("video/")) return "video"
+  if (mimeType.startsWith("image/")) return "image"
+  return "audio"
+}
+
+const mapAssetToMediaAsset = (asset: AssetItem): MediaAsset => {
+  const metaDuration =
+    typeof asset.metadata?.duration === "number" ? asset.metadata.duration : undefined
+  return {
+    id: asset.id,
+    name: asset.name,
+    type: inferMediaType(asset.mime_type || ""),
+    thumbnail_url: asset.thumbnail_url,
+    duration: asset.duration ?? metaDuration,
+    size: asset.file_size ?? undefined,
+    tags: [],
+    created_at: asset.created_at ?? "",
+    quality_score: asset.quality_score ?? undefined,
+    classification_status: asset.classification_status ?? undefined,
+  }
+}
+
+/** 获取素材库列表 */
+export async function getMediaAssets(libraryId?: string): Promise<MediaAsset[]> {
+  const response = await apiClient.get("/assets", {
+    params: libraryId ? { library_id: libraryId } : undefined,
+  })
+  const items: AssetItem[] = response.data.items || []
+  return items.map(mapAssetToMediaAsset)
+}
+
+/** 获取单个素材 */
+export async function getMediaAsset(id: string): Promise<MediaAsset> {
+  const response = await apiClient.get(`/assets/${id}`)
+  return mapAssetToMediaAsset(response.data)
+}

apps/web/src/api/template-editor/types.ts

@@ -0,0 +1,440 @@
+/**
+ * 模板编辑器 API 类型定义
+ * 字段名严格匹配后端 API 响应
+ */
+import type {
+  WatermarkConfig,
+  IntroOutroConfig,
+  PipConfig,
+  FilterConfig,
+  ChromaKeyConfig,
+  StickerConfig,
+  CoverConfig,
+} from "@/pages/editing-planner/types"
+
+/* ── 模板草稿状态 ── */
+
+export type EditPlanStatus =
+  "draft" | "editing" | "rendering" | "completed" | "failed" | "cancelled"
+
+/* ── 配置相关类型 ── */
+
+/** 标题配置（对齐后端 title_config） */
+export interface TitleConfig {
+  ai_auto_select: boolean
+  content: string
+  font_preset: string
+  font_color: string
+  font_size: number
+  position: string
+}
+
+/** 字幕配置 */
+export interface SubtitleConfig {
+  enabled: boolean
+  position: string
+  font: string
+  color: string
+  size: number
+  animation: string
+}
+
+/** BGM 配置 */
+export interface BgmConfig {
+  enabled: boolean
+  music_id: string
+}
+
+/** 片段 TTS 配置 */
+export interface SegmentTtsConfig {
+  mode: string
+  text: string
+  voice_id: string
+  speed: number
+  pitch: number
+  volume: number
+  subtitle_sync: boolean
+}
+
+/** 片段裁剪配置 */
+export interface SegmentTrimConfig {
+  start_time: number
+  end_time: number
+}
+
+/** 片段转场配置 */
+export interface SegmentTransitionConfig {
+  type: string
+  duration: number
+}
+
+/** 模板草稿中的单个片段 */
+export interface EditPlanSegment {
+  segment_order: number
+  duration_min: number
+  duration_max: number
+  material_type: string
+  transition?: SegmentTransitionConfig
+  playback_speed?: number
+  tts_config?: SegmentTtsConfig
+  trim_config?: SegmentTrimConfig
+}
+
+/** 模板草稿 config 完整类型 */
+export interface EditPlanConfig {
+  title_config?: TitleConfig
+  subtitle_config?: SubtitleConfig
+  bgm_config?: BgmConfig
+  estimated_duration?: number
+  segments?: EditPlanSegment[]
+  watermark_config?: WatermarkConfig
+  intro_outro_config?: IntroOutroConfig
+  pip_config?: PipConfig
+  filter_config?: FilterConfig
+  green_screen_config?: ChromaKeyConfig
+  sticker_config?: StickerConfig
+  cover_config?: CoverConfig
+  /** 前端扩展：关联的素材 ID 列表 */
+  asset_ids?: string[]
+  /** 配音 ID */
+  voice_id?: string
+  /** 克隆音色档案 ID */
+  voice_clone_profile_id?: string
+  /** 自定义配音音频 URL */
+  custom_audio_url?: string
+  /** 自定义配音文本 */
+  custom_text?: string
+  /** 视频比例 */
+  ratio?: string
+  /** 视频风格 */
+  style?: string
+  /** 目标时长（秒） */
+  duration?: number
+  /** 是否自动生成字幕 */
+  auto_subtitles?: boolean
+  /** 是否启用 BGM */
+  bgm?: boolean
+  /** 生成数量 */
+  generate_count?: number
+  /** 素材模式 */
+  material_mode?: string
+}
+
+/* ── 模板草稿主体 ── */
+
+/** 模板草稿（后端响应） */
+export interface EditPlan {
+  id: string
+  template_id: string
+  name: string
+  status: EditPlanStatus
+  total_duration: number
+  /** 生成视频数量 */
+  result_count: number
+  config: EditPlanConfig
+  created_at: string
+  updated_at: string
+}
+
+/** 创建模板草稿请求 */
+export interface CreateEditPlanRequest {
+  template_id: string
+  name: string
+  config?: EditPlanConfig
+  total_duration?: number
+  /** 来源模板草稿 ID */
+  source_edit_plan_id?: string
+}
+
+/** 更新模板草稿请求 */
+export interface UpdateEditPlanRequest {
+  name?: string
+  config?: EditPlanConfig
+  total_duration?: number
+  status?: EditPlanStatus
+}
+
+/** 模板草稿列表查询参数 */
+export interface EditPlanListParams {
+  page?: number
+  page_size?: number
+  template_id?: string
+  status?: string
+}
+
+/** 模板草稿列表分页响应 */
+export interface EditPlanListResponse {
+  items: EditPlan[]
+  total: number
+  page: number
+  page_size: number
+}
+
+/* ── 生成相关 ── */
+
+/** 生成响应 */
+export interface GenerateResponse {
+  plan_id: string
+  plan_status: EditPlanStatus
+  generation_task_id: string
+  clip_count: number
+}
+
+/** 模板草稿关联的生成记录 */
+export interface EditPlanGeneration {
+  id: string
+  source_edit_plan_id: string
+  template_id: string
+  asset_ids: string[]
+  status: EditPlanStatus
+  progress: number
+  result_count: number
+  error_message: string
+  error_info: Record<string, unknown>
+  logs: Array<Record<string, unknown>>
+  retry_count: number
+  created_at?: string
+  updated_at?: string
+}
+
+/** 片段生成状态 */
+export interface ClipStatusItem {
+  clip_id: string
+  clip_type: string
+  order: number
+  status: string
+  asset_id?: string
+  text_content?: string
+  duration?: number
+  error_message?: string
+}
+
+/** 生成状态轮询响应 */
+export interface GenerationStatusResponse {
+  plan_id: string
+  plan_status: EditPlanStatus
+  generation_task_id?: string
+  error_message?: string
+  clips: ClipStatusItem[]
+  error?: string
+  message?: string
+}
+
+/** 生成视频详情 */
+export interface GeneratedVideo {
+  id: string
+  project_id?: string
+  generation_task_id?: string
+  name: string
+  file_url: string
+  file_size?: number
+  duration?: number
+  thumbnail_url?: string
+  width?: number
+  height?: number
+  fps?: number
+  status: string
+  review_status?: string
+  download_url?: string
+  created_at?: string
+  updated_at?: string
+}
+
+/* ── AI 推荐 & 封面生成 ── */
+
+/** AI 推荐请求 */
+export interface AIRecommendRequest {
+  asset_ids: string[]
+  editing_mode?: string
+  target_duration?: number
+}
+
+/** AI 推荐单个片段 */
+export interface AIRecommendClipItem {
+  clip_type: string
+  order: number
+  text_content: string
+  duration: number
+  transition_effect: string
+  asset_id: string
+  start_time: number
+  config: EditPlanConfig
+}
+
+/** AI 推荐响应 */
+export interface AIRecommendResponse {
+  plan_id: string
+  clips: AIRecommendClipItem[]
+  config: EditPlanConfig
+  total_duration: number
+  confidence: number
+}
+
+/** AI 封面生成请求 */
+export interface GenerateCoverRequest {
+  asset_ids: string[]
+  cover_type?: "ai_frame" | "manual" | "upload" | "ai_regenerate"
+  frame_time?: number
+}
+
+/** AI 封面生成响应 */
+export interface GenerateCoverResponse {
+  plan_id: string
+  cover: CoverResult
+}
+
+/** 封面生成结果 */
+export interface CoverResult {
+  scheme?: string
+  asset_id?: string
+  frame_time?: number
+  thumbnail_url?: string
+}
+
+/* ── 片段 CRUD 相关 ── */
+
+/** 片段状态 */
+export type EditPlanClipStatus = "pending" | "processing" | "ready" | "failed"
+
+/** 剪辑片段（后端响应） */
+export interface EditPlanClip {
+  id: string
+  plan_id: string
+  clip_type: string
+  order: number
+  asset_id: string
+  text_content: string
+  start_time: number
+  duration: number
+  transition_effect: string
+  transition_duration: number
+  playback_speed: number
+  status: EditPlanClipStatus
+  config: Record<string, unknown>
+  created_at?: string
+  updated_at?: string
+}
+
+/** 创建片段请求 */
+export interface CreateEditPlanClipRequest {
+  clip_type: string
+  order: number
+  asset_id?: string
+  text_content?: string
+  start_time?: number
+  duration?: number
+  transition_effect?: string
+  transition_duration?: number
+  playback_speed?: number
+  config?: Record<string, unknown>
+}
+
+/** 更新片段请求 */
+export interface UpdateEditPlanClipRequest {
+  clip_type?: string
+  order?: number
+  asset_id?: string
+  text_content?: string
+  start_time?: number
+  duration?: number
+  transition_effect?: string
+  transition_duration?: number
+  playback_speed?: number
+  config?: Record<string, unknown>
+}
+
+/** 片段列表响应 */
+export interface EditPlanClipListResponse {
+  items: EditPlanClip[]
+  total: number
+}
+
+/** 片段列表查询参数 */
+export interface EditPlanClipListParams {
+  status?: string
+  skip?: number
+  limit?: number
+}
+
+/* ── 片段批量操作 ── */
+
+/** 重排序条目 */
+export interface ClipReorderItem {
+  clip_id: string
+  new_order: number
+}
+
+/** 重排序响应 */
+export interface ClipReorderResponse {
+  success: boolean
+  updated_count: number
+  message: string
+}
+
+/** 批量删除响应 */
+export interface ClipBatchDeleteResponse {
+  success: boolean
+  deleted_count: number
+  message: string
+}
+
+/** 从素材批量创建响应 */
+export interface ClipsFromAssetsResponse {
+  success: boolean
+  created_count: number
+  message: string
+  clip_ids: string[]
+}
+
+/* ── 复制计划 ── */
+
+/** 复制计划请求 */
+export interface CopyEditPlanRequest {
+  name?: string
+  project_id?: string
+}
+
+/* ── 前端 UI 类型 ── */
+
+/** 转场效果（14 种预设） */
+export interface TransitionEffect {
+  type:
+    | "none"
+    | "cut"
+    | "fade"
+    | "dissolve"
+    | "zoom"
+    | "slide_left"
+    | "slide_right"
+    | "slide_up"
+    | "slide_down"
+    | "wipe_left"
+    | "wipe_right"
+    | "wipe_up"
+    | "wipe_down"
+    | "circlecrop"
+    | "rectcrop"
+  duration: number
+  /** 播放速度倍率 */
+  playback_speed?: number
+}
+
+/** 素材库资产（UI 层类型） */
+export interface MediaAsset {
+  id: string
+  name: string
+  type: "video" | "image" | "audio"
+  /** 缩略图 URL */
+  thumbnail_url?: string
+  /** 时长（秒），仅 video/audio */
+  duration?: number
+  /** 文件大小（字节） */
+  size?: number
+  /** 标签 */
+  tags: string[]
+  created_at: string
+  /** 质量分 0-100 */
+  quality_score?: number
+  /** 分类状态 */
+  classification_status?: "pending" | "processing" | "completed" | "failed"
+}

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

@@ -1,157 +0,0 @@
-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

@@ -1,91 +0,0 @@
-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

@@ -1,82 +0,0 @@
-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

@@ -1,184 +0,0 @@
-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,8 +1,27 @@
-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 { 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 type {
   ClipData,
+  ClipType,
+  TtsConfig,
+  TtsMode,
+  TrimConfig,
   WatermarkConfig,
   IntroOutroConfig,
   PipConfig,
@@ -13,11 +32,6 @@ 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
@@ -30,6 +44,7 @@ interface UseTemplateManagementParams {
   setSubtitleSettings: Dispatch<SetStateAction<SubtitleStyleConfig>>
   setBgmSettings: Dispatch<SetStateAction<BgmMixConfig>>
   setCoverConfig: Dispatch<SetStateAction<CoverConfig>>
+  // 保存时需要的配置
   clips: ClipData[]
   totalDuration: number
   titleConfig: TitleConfig
@@ -46,7 +61,7 @@ interface UseTemplateManagementParams {
 
 /**
  * 模板管理 Hook
- * 模板列表/分类/加载/保存/模式切换/筛选搜索
+ * 模板列表/分类/加载/保存/模式切换/筛选搜索 + 3 个 useEffect
  */
 export const useTemplateManagement = (params: UseTemplateManagementParams) => {
   const {
@@ -74,101 +89,346 @@ 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 {
-    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 filteredTemplates = templates.filter((t) => {
+    if (currentFilter !== "全部" && t.category !== currentFilter) return false
+    if (searchQuery && !t.name.toLowerCase().includes(searchQuery.toLowerCase())) return false
+    return true
   })
 
-  /* ── 模板详情加载 ── */
-  useTemplateDetail({
-    loadedTemplateId,
-    resetClips,
-    setCurrentMode,
-    setTitleConfig,
-    setSubtitleSettings,
-    setBgmSettings,
-    setDraftName,
-    setDraftCategory,
-    setDraftTags,
-  })
+  const currentTemplate = templates.find((t) => t.id === loadedTemplateId) || null
 
-  /* ── 计划草稿加载 ── */
-  usePlanLoading({
+  /* ──────────── 加载 ──────────── */
+
+  /**
+   * 并行加载模板列表、分类、素材库
+   * 首次挂载时调用，三个接口无依赖关系，用 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("加载模板草稿失败"))
+  }, [
     loadedPlanId,
     resetClips,
-    setLoadedTemplateId,
-    setDraftName,
     setTitleConfig,
     setSubtitleSettings,
     setBgmSettings,
     setCoverConfig,
-  })
+  ])
 
-  /* ── 事件 ── */
-  const handleLoadTemplate = useCallback(
-    (templateId: string) => {
-      setLoadedTemplateId(templateId)
-      setSelectedClipId(null)
-    },
-    [setLoadedTemplateId, setSelectedClipId],
-  )
+  /* ──────────── 事件 ──────────── */
 
-  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 })))
+  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 },
       }
-    },
-    [setClips],
-  )
+      if (loadedTemplateId) {
+        await updateEditingTemplate(loadedTemplateId, payload)
+      } else {
+        await createEditingTemplate(payload)
+      }
+      message.success(loadedTemplateId ? "模板保存成功" : "模板创建成功")
+      setSaveModalOpen(false)
+      loadTemplates()
+    } catch {
+      message.error("保存失败")
+    } finally {
+      setSaveLoading(false)
+    }
+  }
 
   return {
     // state