fix(generate): 修复 usePlanConfigLoader 隐式any类型

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

@@ -1,16 +1,18 @@
+/**
+ * 字幕样式配置面板 — Drawer 形式
+ * 字幕开关（手动 / ASR 自动识别）、字体大小、颜色、描边/阴影、位置、ASR 语言
+ */
 import React from "react"
 import { Drawer, Slider, ColorPicker, Select } from "antd"
 import type { Color } from "antd/es/color-picker"
 import type { SubtitleStyleConfig } from "@/pages/editing-planner/types/subtitle"
 import {
+  POSITION_OPTIONS,
   FONT_OPTIONS,
   ANIMATION_OPTIONS,
   ASR_LANGUAGE_OPTIONS,
 } from "@/pages/editing-planner/constants/subtitleStyle"
 import SubtitlePreview from "./subtitle-style/SubtitlePreview"
-import { SubtitleModeSwitch } from "./subtitle-style/SubtitleModeSwitch"
-import { SubtitlePositionSelector } from "./subtitle-style/SubtitlePositionSelector"
-import { SubtitleEffectButtons } from "./subtitle-style/SubtitleEffectButtons"
 
 interface SubtitleStylePanelProps {
   open: boolean
@@ -38,6 +40,7 @@ const SubtitleStylePanel: React.FC<SubtitleStylePanelProps> = ({
       onClose={onClose}
       className="subtitle-style-drawer"
     >
+      {/* ── 字幕开关 ── */}
       <div className="sub-field">
         <div className="sub-toggle-row">
           <span className="sub-label">启用字幕</span>
@@ -52,11 +55,26 @@ const SubtitleStylePanel: React.FC<SubtitleStylePanelProps> = ({
 
       {config.enabled && (
         <>
+          {/* ── 模式切换 ── */}
           <div className="sub-field">
             <label className="sub-label">字幕来源</label>
-            <SubtitleModeSwitch mode={config.mode} onModeChange={(mode) => update({ mode })} />
+            <div className="sub-mode-switch">
+              <button
+                className={`sub-mode-btn${config.mode === "manual" ? " active" : ""}`}
+                onClick={() => update({ mode: "manual" })}
+              >
+                ✏️ 手动输入
+              </button>
+              <button
+                className={`sub-mode-btn${config.mode === "asr" ? " active" : ""}`}
+                onClick={() => update({ mode: "asr" })}
+              >
+                🤖 ASR 识别
+              </button>
+            </div>
           </div>
 
+          {/* ── ASR 语言（仅 ASR 模式） ── */}
           {config.mode === "asr" && (
             <div className="sub-field">
               <label className="sub-label">识别语言</label>
@@ -70,6 +88,7 @@ const SubtitleStylePanel: React.FC<SubtitleStylePanelProps> = ({
             </div>
           )}
 
+          {/* ── 字体大小 ── */}
           <div className="sub-field">
             <label className="sub-label">
               字体大小 <span className="sub-value">{config.fontSize}px</span>
@@ -82,6 +101,7 @@ const SubtitleStylePanel: React.FC<SubtitleStylePanelProps> = ({
             />
           </div>
 
+          {/* ── 字体颜色 ── */}
           <div className="sub-field">
             <label className="sub-label">字体颜色</label>
             <div className="sub-color-row">
@@ -93,6 +113,7 @@ const SubtitleStylePanel: React.FC<SubtitleStylePanelProps> = ({
             </div>
           </div>
 
+          {/* ── 字体 ── */}
           <div className="sub-field">
             <label className="sub-label">字体</label>
             <Select
@@ -104,24 +125,46 @@ const SubtitleStylePanel: React.FC<SubtitleStylePanelProps> = ({
             />
           </div>
 
+          {/* ── 字幕位置 ── */}
           <div className="sub-field">
             <label className="sub-label">位置</label>
-            <SubtitlePositionSelector
-              position={config.position}
-              onPositionChange={(position) => update({ position })}
-            />
+            <div className="sub-position-group">
+              {POSITION_OPTIONS.map((opt) => (
+                <button
+                  key={opt.value}
+                  className={`sub-position-btn${config.position === opt.value ? " active" : ""}`}
+                  onClick={() =>
+                    update({
+                      position: opt.value as SubtitleStyleConfig["position"],
+                    })
+                  }
+                >
+                  {opt.label}
+                </button>
+              ))}
+            </div>
           </div>
 
+          {/* ── 描边 / 阴影 ── */}
           <div className="sub-field">
             <label className="sub-label">效果</label>
-            <SubtitleEffectButtons
-              stroke={config.stroke}
-              shadow={config.shadow}
-              onStrokeChange={(stroke) => update({ stroke })}
-              onShadowChange={(shadow) => update({ shadow })}
-            />
+            <div className="sub-effect-btns">
+              <button
+                className={`sub-effect-btn${config.stroke ? " active" : ""}`}
+                onClick={() => update({ stroke: !config.stroke })}
+              >
+                S 描边
+              </button>
+              <button
+                className={`sub-effect-btn${config.shadow ? " active" : ""}`}
+                onClick={() => update({ shadow: !config.shadow })}
+              >
+                ☁ 阴影
+              </button>
+            </div>
           </div>
 
+          {/* ── 动画 ── */}
           <div className="sub-field">
             <label className="sub-label">动画效果</label>
             <Select
@@ -136,6 +179,7 @@ const SubtitleStylePanel: React.FC<SubtitleStylePanelProps> = ({
             />
           </div>
 
+          {/* ── 预览 ── */}
           <SubtitlePreview config={config} />
         </>
       )}

apps/web/src/pages/editing-planner/components/subtitle-style/SubtitleEffectButtons.tsx

@@ -1,32 +0,0 @@
-import React from "react"
-
-interface SubtitleEffectButtonsProps {
-  stroke: boolean
-  shadow: boolean
-  onStrokeChange: (enabled: boolean) => void
-  onShadowChange: (enabled: boolean) => void
-}
-
-export const SubtitleEffectButtons: React.FC<SubtitleEffectButtonsProps> = ({
-  stroke,
-  shadow,
-  onStrokeChange,
-  onShadowChange,
-}) => {
-  return (
-    <div className="sub-effect-btns">
-      <button
-        className={`sub-effect-btn${stroke ? " active" : ""}`}
-        onClick={() => onStrokeChange(!stroke)}
-      >
-        S 描边
-      </button>
-      <button
-        className={`sub-effect-btn${shadow ? " active" : ""}`}
-        onClick={() => onShadowChange(!shadow)}
-      >
-        ☁ 阴影
-      </button>
-    </div>
-  )
-}

apps/web/src/pages/editing-planner/components/subtitle-style/SubtitleModeSwitch.tsx

@@ -1,25 +0,0 @@
-import React from "react"
-
-interface SubtitleModeSwitchProps {
-  mode: "manual" | "asr"
-  onModeChange: (mode: "manual" | "asr") => void
-}
-
-export const SubtitleModeSwitch: React.FC<SubtitleModeSwitchProps> = ({ mode, onModeChange }) => {
-  return (
-    <div className="sub-mode-switch">
-      <button
-        className={`sub-mode-btn${mode === "manual" ? " active" : ""}`}
-        onClick={() => onModeChange("manual")}
-      >
-        ✏️ 手动输入
-      </button>
-      <button
-        className={`sub-mode-btn${mode === "asr" ? " active" : ""}`}
-        onClick={() => onModeChange("asr")}
-      >
-        🤖 ASR 识别
-      </button>
-    </div>
-  )
-}

apps/web/src/pages/editing-planner/components/subtitle-style/SubtitlePositionSelector.tsx

@@ -1,27 +0,0 @@
-import React from "react"
-import type { SubtitleStyleConfig } from "@/pages/editing-planner/types/subtitle"
-import { POSITION_OPTIONS } from "@/pages/editing-planner/constants/subtitleStyle"
-
-interface SubtitlePositionSelectorProps {
-  position: SubtitleStyleConfig["position"]
-  onPositionChange: (position: SubtitleStyleConfig["position"]) => void
-}
-
-export const SubtitlePositionSelector: React.FC<SubtitlePositionSelectorProps> = ({
-  position,
-  onPositionChange,
-}) => {
-  return (
-    <div className="sub-position-group">
-      {POSITION_OPTIONS.map((opt) => (
-        <button
-          key={opt.value}
-          className={`sub-position-btn${position === opt.value ? " active" : ""}`}
-          onClick={() => onPositionChange(opt.value as SubtitleStyleConfig["position"])}
-        >
-          {opt.label}
-        </button>
-      ))}
-    </div>
-  )
-}

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

@@ -1,309 +0,0 @@
-/**
- * GeneratePage 表单状态管理
- * 集中管理 7 步向导的所有共享状态、API 加载、URL 参数解析
- */
-import { useState, useEffect, useMemo } from "react"
-import { useQuery } from "@tanstack/react-query"
-import { useSearchParams } from "react-router-dom"
-import type { GeneratedVideo, TitleConfig } from "@/api/template-editor"
-import type { EditingTemplate } from "@/api/editing-planner"
-import { getEditPlan } from "@/api/template-editor"
-import type { CoverConfig } from "../../editing-planner/types"
-import { getEditingTemplates } from "@/api/editing-planner"
-import type { PresetVoiceItem } from "@/api/voices"
-import { fetchPresetVoices } from "@/api/voices"
-import { DEFAULT_COVER_SETTINGS } from "../constants"
-import type { TitleSettings } from "../types"
-
-const DEFAULT_TITLE_SETTINGS: TitleSettings = {
-  aiAutoSelect: false,
-  title: "",
-  position: "bottom",
-  font: "思源黑体",
-  size: 28,
-  bold: true,
-  italic: false,
-  stroke: true,
-  shadow: false,
-  color: "#ffffff",
-}
-
-export interface GenerateFormState {
-  /* 步骤 */
-  currentStep: number
-  setCurrentStep: (step: number | ((prev: number) => number)) => void
-
-  /* 模板 */
-  selectedTemplate: string
-  setSelectedTemplate: (id: string) => void
-  userTemplates: EditingTemplate[]
-
-  /* 素材 */
-  selectedMaterials: string[]
-  setSelectedMaterials: (ids: string[]) => void
-  materialMode: "manual" | "auto"
-  setMaterialMode: (mode: "manual" | "auto") => void
-  smartSelectedIds: string[]
-  setSmartSelectedIds: (ids: string[]) => void
-
-  /* 标题 */
-  titleSettings: TitleSettings
-  setTitleSettings: (settings: TitleSettings | ((prev: TitleSettings) => TitleSettings)) => void
-
-  /* 封面 */
-  coverSettings: CoverConfig
-  setCoverSettings: (settings: CoverConfig | ((prev: CoverConfig) => CoverConfig)) => void
-
-  /* 配音 */
-  selectedVoice: string
-  setSelectedVoice: (id: string) => void
-  voiceMode: "preset" | "custom" | "clone"
-  setVoiceMode: (mode: "preset" | "custom" | "clone") => void
-  selectedClonedVoice: string
-  setSelectedClonedVoice: (id: string) => void
-  presetVoices: PresetVoiceItem[]
-
-  /* 克隆弹窗 */
-  cloneModalOpen: boolean
-  setCloneModalOpen: (open: boolean) => void
-
-  /* 生成数量 */
-  generateCount: number
-  setGenerateCount: (n: number) => void
-
-  /* 高级设置 */
-  videoRatio: string
-  duration: number
-  style: string
-  autoSubtitles: boolean
-  bgm: boolean
-
-  /* URL 参数 */
-  editPlanId: string | null
-  planConfigStr: string | null
-
-  /* 预览弹窗 */
-  previewVideo: GeneratedVideo | null
-  setPreviewVideo: (v: GeneratedVideo | null) => void
-  previewModalOpen: boolean
-  setPreviewModalOpen: (open: boolean) => void
-}
-
-export const useGenerateFormState = (): GenerateFormState => {
-  const [searchParams] = useSearchParams()
-  const editPlanId = searchParams.get("edit_plan_id")
-  const planConfigStr = searchParams.get("plan_config")
-
-  /* ── 步骤状态 ── */
-  const [currentStep, setCurrentStep] = useState(1)
-
-  /* ── 模板（从 API 加载） ── */
-  const [selectedTemplate, setSelectedTemplate] = useState("")
-  const { data: userTemplates = [] } = useQuery({
-    queryKey: ["generate-templates"],
-    queryFn: () => getEditingTemplates(),
-    staleTime: 60_000,
-  })
-  /* 模板加载完成后自动选中第一个 */
-  useEffect(() => {
-    if (userTemplates.length > 0 && !selectedTemplate) {
-      setSelectedTemplate(userTemplates[0].id)
-    }
-  }, [userTemplates, selectedTemplate])
-
-  /* ── 素材 ── */
-  const [selectedMaterials, setSelectedMaterials] = useState<string[]>([])
-  const [materialMode, setMaterialMode] = useState<"manual" | "auto">("manual")
-  const [smartSelectedIds, setSmartSelectedIds] = useState<string[]>([])
-
-  /* ── 标题设置 ── */
-  const [titleSettings, setTitleSettings] = useState<TitleSettings>(DEFAULT_TITLE_SETTINGS)
-
-  /* ── 封面设置 ── */
-  const [coverSettings, setCoverSettings] = useState<CoverConfig>(DEFAULT_COVER_SETTINGS)
-
-  /* 当选中模板开启了「AI自动匹配标题」，自动填入模板预设标题 / 封面 */
-  useEffect(() => {
-    const tpl = userTemplates.find((t) => t.id === selectedTemplate)
-    if (tpl?.title_config) {
-      setTitleSettings((prev) => ({
-        ...prev,
-        aiAutoSelect: tpl.title_config!.ai_auto_select,
-        title: tpl.title_config!.content || prev.title,
-        position: tpl.title_config!.position || prev.position,
-        font: tpl.title_config!.font_preset || prev.font,
-        size: tpl.title_config!.font_size || prev.size,
-        color: tpl.title_config!.font_color || prev.color,
-      }))
-    }
-    if (tpl?.cover_config) {
-      setCoverSettings((prev) => ({
-        ...prev,
-        enabled: tpl.cover_config!.enabled ?? prev.enabled,
-        mode: (tpl.cover_config!.mode as CoverConfig["mode"]) || prev.mode,
-        frame_time: tpl.cover_config!.frame_time ?? prev.frame_time,
-        upload_url: tpl.cover_config!.upload_url || prev.upload_url,
-        ai_suggested_time: tpl.cover_config!.ai_suggested_time ?? prev.ai_suggested_time,
-        thumbnail_url: tpl.cover_config!.thumbnail_url || prev.thumbnail_url,
-      }))
-    }
-  }, [selectedTemplate, userTemplates])
-
-  /* ── 配音 ── */
-  const [selectedVoice, setSelectedVoice] = useState("")
-  const [voiceMode, setVoiceMode] = useState<"preset" | "custom" | "clone">("preset")
-  const [selectedClonedVoice, setSelectedClonedVoice] = useState("")
-
-  /* ── 预置音色 API ── */
-  const { data: presetVoicesData } = useQuery({
-    queryKey: ["preset-voices"],
-    queryFn: fetchPresetVoices,
-  })
-  const presetVoices: PresetVoiceItem[] = useMemo(
-    () => presetVoicesData?.items ?? [],
-    [presetVoicesData],
-  )
-
-  /* ── 克隆声音弹窗 ── */
-  const [cloneModalOpen, setCloneModalOpen] = useState(false)
-
-  /* ── 生成数量 ── */
-  const [generateCount, setGenerateCount] = useState(1)
-
-  /* ── 高级设置（隐藏但保留） ── */
-  const [videoRatio] = useState("16:9")
-  const [duration] = useState(30)
-  const [style] = useState("business")
-  const [autoSubtitles] = useState(true)
-  const [bgm] = useState(true)
-
-  /* ── 预览弹窗 ── */
-  const [previewVideo, setPreviewVideo] = useState<GeneratedVideo | null>(null)
-  const [previewModalOpen, setPreviewModalOpen] = useState(false)
-
-  /** 解析 plan_config 并自动填充表单 */
-  useEffect(() => {
-    if (!planConfigStr) return
-    try {
-      const config = JSON.parse(planConfigStr) as {
-        title_config?: {
-          content?: string
-          ai_auto_select?: boolean
-          position?: string
-          font_preset?: string
-          font_size?: number
-          font_color?: string
-        }
-        subtitle_config?: { enabled?: boolean }
-        bgm_config?: { enabled?: boolean; music_id?: string }
-        mode?: string
-        total_duration?: number
-        segments?: Array<{ media_asset_id?: string; material_type?: string }>
-      }
-
-      if (config.title_config) {
-        const tc = config.title_config as TitleConfig
-        setTitleSettings((prev) => ({
-          ...prev,
-          title: tc.content || "",
-          aiAutoSelect: tc.ai_auto_select || false,
-          position: tc.position || prev.position,
-          font: tc.font_preset || prev.font,
-          size: tc.font_size || prev.size,
-          color: tc.font_color || prev.color,
-        }))
-      }
-      if (config.segments && config.segments.length > 0) {
-        const assetIds = config.segments
-          .map((s) => s.media_asset_id)
-          .filter((id): id is string => !!id)
-        if (assetIds.length > 0) {
-          setSelectedMaterials(assetIds)
-        }
-      }
-    } catch (err) {
-      console.warn("解析 plan_config 失败:", err)
-    }
-  }, [planConfigStr])
-
-  /** 如果没有 plan_config，尝试通过 edit_plan_id 从后端拉取配置 */
-  useEffect(() => {
-    if (!editPlanId || planConfigStr) return
-    const loadPlanConfig = async () => {
-      try {
-        const plan = await getEditPlan(editPlanId)
-        if (plan.name) setTitleSettings((prev) => ({ ...prev, title: plan.name }))
-        const cfg = plan.config
-        if (cfg?.title_config) {
-          setTitleSettings((prev) => ({
-            ...prev,
-            aiAutoSelect: cfg.title_config!.ai_auto_select,
-            title: cfg.title_config!.content || prev.title,
-            position: cfg.title_config!.position || prev.position,
-            font: cfg.title_config!.font_preset || prev.font,
-            size: cfg.title_config!.font_size || prev.size,
-            color: cfg.title_config!.font_color || prev.color,
-          }))
-        }
-        if (cfg?.cover_config) {
-          const cc = cfg.cover_config as CoverConfig
-          setCoverSettings((prev) => ({
-            ...prev,
-            enabled: cc.enabled ?? prev.enabled,
-            mode: cc.mode || prev.mode,
-            frame_time: cc.frame_time ?? prev.frame_time,
-            upload_url: cc.upload_url || prev.upload_url,
-            ai_suggested_time: cc.ai_suggested_time ?? prev.ai_suggested_time,
-            thumbnail_url: cc.thumbnail_url || prev.thumbnail_url,
-          }))
-        }
-        if (cfg?.asset_ids) {
-          setSelectedMaterials(cfg.asset_ids.filter((v): v is string => typeof v === "string"))
-        }
-      } catch (err) {
-        console.warn("加载模板草稿配置失败:", err)
-      }
-    }
-    loadPlanConfig()
-  }, [editPlanId, planConfigStr])
-
-  return {
-    currentStep,
-    setCurrentStep,
-    selectedTemplate,
-    setSelectedTemplate,
-    userTemplates,
-    selectedMaterials,
-    setSelectedMaterials,
-    materialMode,
-    setMaterialMode,
-    smartSelectedIds,
-    setSmartSelectedIds,
-    titleSettings,
-    setTitleSettings,
-    coverSettings,
-    setCoverSettings,
-    selectedVoice,
-    setSelectedVoice,
-    voiceMode,
-    setVoiceMode,
-    selectedClonedVoice,
-    setSelectedClonedVoice,
-    presetVoices,
-    cloneModalOpen,
-    setCloneModalOpen,
-    generateCount,
-    setGenerateCount,
-    videoRatio,
-    duration,
-    style,
-    autoSubtitles,
-    bgm,
-    editPlanId,
-    planConfigStr,
-    previewVideo,
-    setPreviewVideo,
-    previewModalOpen,
-    setPreviewModalOpen,
-  }
-}

apps/web/src/pages/generate/hooks/useGenerateFormState/index.ts

@@ -0,0 +1,198 @@
+/**
+ * GeneratePage 表单状态管理
+ * 集中管理 7 步向导的所有共享状态、API 加载、URL 参数解析
+ */
+import { useState } from "react"
+import { useSearchParams } from "react-router-dom"
+import type { GeneratedVideo } from "@/api/template-editor"
+import type { EditingTemplate } from "@/api/editing-planner"
+import type { CoverConfig } from "../../../editing-planner/types"
+import type { PresetVoiceItem } from "@/api/voices"
+import { DEFAULT_COVER_SETTINGS } from "../../constants"
+import type { TitleSettings } from "../../types"
+import { useTemplateSelection } from "./useTemplateSelection"
+import { useTitleCoverSync } from "./useTitleCoverSync"
+import { useVoiceState } from "./useVoiceState"
+import { usePlanConfigLoader } from "./usePlanConfigLoader"
+
+const DEFAULT_TITLE_SETTINGS: TitleSettings = {
+  aiAutoSelect: false,
+  title: "",
+  position: "bottom",
+  font: "思源黑体",
+  size: 28,
+  bold: true,
+  italic: false,
+  stroke: true,
+  shadow: false,
+  color: "#ffffff",
+}
+
+export interface GenerateFormState {
+  /* 步骤 */
+  currentStep: number
+  setCurrentStep: (step: number | ((prev: number) => number)) => void
+
+  /* 模板 */
+  selectedTemplate: string
+  setSelectedTemplate: (id: string) => void
+  userTemplates: EditingTemplate[]
+
+  /* 素材 */
+  selectedMaterials: string[]
+  setSelectedMaterials: (ids: string[]) => void
+  materialMode: "manual" | "auto"
+  setMaterialMode: (mode: "manual" | "auto") => void
+  smartSelectedIds: string[]
+  setSmartSelectedIds: (ids: string[]) => void
+
+  /* 标题 */
+  titleSettings: TitleSettings
+  setTitleSettings: (settings: TitleSettings | ((prev: TitleSettings) => TitleSettings)) => void
+
+  /* 封面 */
+  coverSettings: CoverConfig
+  setCoverSettings: (settings: CoverConfig | ((prev: CoverConfig) => CoverConfig)) => void
+
+  /* 配音 */
+  selectedVoice: string
+  setSelectedVoice: (id: string) => void
+  voiceMode: "preset" | "custom" | "clone"
+  setVoiceMode: (mode: "preset" | "custom" | "clone") => void
+  selectedClonedVoice: string
+  setSelectedClonedVoice: (id: string) => void
+  presetVoices: PresetVoiceItem[]
+
+  /* 克隆弹窗 */
+  cloneModalOpen: boolean
+  setCloneModalOpen: (open: boolean) => void
+
+  /* 生成数量 */
+  generateCount: number
+  setGenerateCount: (n: number) => void
+
+  /* 高级设置 */
+  videoRatio: string
+  duration: number
+  style: string
+  autoSubtitles: boolean
+  bgm: boolean
+
+  /* URL 参数 */
+  editPlanId: string | null
+  planConfigStr: string | null
+
+  /* 预览弹窗 */
+  previewVideo: GeneratedVideo | null
+  setPreviewVideo: (v: GeneratedVideo | null) => void
+  previewModalOpen: boolean
+  setPreviewModalOpen: (open: boolean) => void
+}
+
+export const useGenerateFormState = (): GenerateFormState => {
+  const [searchParams] = useSearchParams()
+  const editPlanId = searchParams.get("edit_plan_id")
+  const planConfigStr = searchParams.get("plan_config")
+
+  /* ── 步骤状态 ── */
+  const [currentStep, setCurrentStep] = useState(1)
+
+  /* ── 模板选择 ── */
+  const { selectedTemplate, setSelectedTemplate, userTemplates } = useTemplateSelection()
+
+  /* ── 素材 ── */
+  const [selectedMaterials, setSelectedMaterials] = useState<string[]>([])
+  const [materialMode, setMaterialMode] = useState<"manual" | "auto">("manual")
+  const [smartSelectedIds, setSmartSelectedIds] = useState<string[]>([])
+
+  /* ── 标题设置 ── */
+  const [titleSettings, setTitleSettings] = useState<TitleSettings>(DEFAULT_TITLE_SETTINGS)
+
+  /* ── 封面设置 ── */
+  const [coverSettings, setCoverSettings] = useState<CoverConfig>(DEFAULT_COVER_SETTINGS)
+
+  /* ── 模板切换时同步标题/封面 ── */
+  useTitleCoverSync({
+    selectedTemplate,
+    userTemplates,
+    setTitleSettings,
+    setCoverSettings,
+  })
+
+  /* ── 配音状态 ── */
+  const {
+    selectedVoice,
+    setSelectedVoice,
+    voiceMode,
+    setVoiceMode,
+    selectedClonedVoice,
+    setSelectedClonedVoice,
+    presetVoices,
+  } = useVoiceState()
+
+  /* ── 克隆声音弹窗 ── */
+  const [cloneModalOpen, setCloneModalOpen] = useState(false)
+
+  /* ── 生成数量 ── */
+  const [generateCount, setGenerateCount] = useState(1)
+
+  /* ── 高级设置（隐藏但保留） ── */
+  const [videoRatio] = useState("16:9")
+  const [duration] = useState(30)
+  const [style] = useState("business")
+  const [autoSubtitles] = useState(true)
+  const [bgm] = useState(true)
+
+  /* ── 预览弹窗 ── */
+  const [previewVideo, setPreviewVideo] = useState<GeneratedVideo | null>(null)
+  const [previewModalOpen, setPreviewModalOpen] = useState(false)
+
+  /* ── 从 URL / 编辑计划加载配置 ── */
+  usePlanConfigLoader({
+    editPlanId,
+    planConfigStr,
+    setTitleSettings,
+    setCoverSettings,
+    setSelectedMaterials,
+  })
+
+  return {
+    currentStep,
+    setCurrentStep,
+    selectedTemplate,
+    setSelectedTemplate,
+    userTemplates,
+    selectedMaterials,
+    setSelectedMaterials,
+    materialMode,
+    setMaterialMode,
+    smartSelectedIds,
+    setSmartSelectedIds,
+    titleSettings,
+    setTitleSettings,
+    coverSettings,
+    setCoverSettings,
+    selectedVoice,
+    setSelectedVoice,
+    voiceMode,
+    setVoiceMode,
+    selectedClonedVoice,
+    setSelectedClonedVoice,
+    presetVoices,
+    cloneModalOpen,
+    setCloneModalOpen,
+    generateCount,
+    setGenerateCount,
+    videoRatio,
+    duration,
+    style,
+    autoSubtitles,
+    bgm,
+    editPlanId,
+    planConfigStr,
+    previewVideo,
+    setPreviewVideo,
+    previewModalOpen,
+    setPreviewModalOpen,
+  }
+}

apps/web/src/pages/generate/hooks/useGenerateFormState/usePlanConfigLoader.ts

@@ -0,0 +1,110 @@
+import { useEffect } from "react"
+import type { CoverConfig } from "../../../editing-planner/types"
+import type { TitleSettings } from "../../types"
+import type { TitleConfig } from "@/api/template-editor"
+import { getEditPlan } from "@/api/template-editor"
+
+interface UsePlanConfigLoaderOptions {
+  editPlanId: string | null
+  planConfigStr: string | null
+  setTitleSettings: (settings: TitleSettings | ((prev: TitleSettings) => TitleSettings)) => void
+  setCoverSettings: (settings: CoverConfig | ((prev: CoverConfig) => CoverConfig)) => void
+  setSelectedMaterials: (ids: string[]) => void
+}
+
+/**
+ * 从 URL 参数或编辑计划 ID 加载表单配置
+ */
+export function usePlanConfigLoader({
+  editPlanId,
+  planConfigStr,
+  setTitleSettings,
+  setCoverSettings,
+  setSelectedMaterials,
+}: UsePlanConfigLoaderOptions) {
+  /** 解析 plan_config 并自动填充表单 */
+  useEffect(() => {
+    if (!planConfigStr) return
+    try {
+      const config = JSON.parse(planConfigStr) as {
+        title_config?: {
+          content?: string
+          ai_auto_select?: boolean
+          position?: string
+          font_preset?: string
+          font_size?: number
+          font_color?: string
+        }
+        subtitle_config?: { enabled?: boolean }
+        bgm_config?: { enabled?: boolean; music_id?: string }
+        mode?: string
+        total_duration?: number
+        segments?: Array<{ media_asset_id?: string; material_type?: string }>
+      }
+
+      if (config.title_config) {
+        const tc = config.title_config as TitleConfig
+        setTitleSettings((prev: TitleSettings) => ({
+          ...prev,
+          title: tc.content || "",
+          aiAutoSelect: tc.ai_auto_select || false,
+          position: tc.position || prev.position,
+          font: tc.font_preset || prev.font,
+          size: tc.font_size || prev.size,
+          color: tc.font_color || prev.color,
+        }))
+      }
+      if (config.segments && config.segments.length > 0) {
+        const assetIds = config.segments
+          .map((s) => s.media_asset_id)
+          .filter((id): id is string => !!id)
+        if (assetIds.length > 0) {
+          setSelectedMaterials(assetIds)
+        }
+      }
+    } catch (err) {
+      console.warn("解析 plan_config 失败:", err)
+    }
+  }, [planConfigStr, setTitleSettings, setSelectedMaterials])
+
+  /** 如果没有 plan_config，尝试通过 edit_plan_id 从后端拉取配置 */
+  useEffect(() => {
+    if (!editPlanId || planConfigStr) return
+    const loadPlanConfig = async () => {
+      try {
+        const plan = await getEditPlan(editPlanId)
+        if (plan.name) setTitleSettings((prev: TitleSettings) => ({ ...prev, title: plan.name }))
+        const cfg = plan.config
+        if (cfg?.title_config) {
+          setTitleSettings((prev: TitleSettings) => ({
+            ...prev,
+            aiAutoSelect: cfg.title_config!.ai_auto_select,
+            title: cfg.title_config!.content || prev.title,
+            position: cfg.title_config!.position || prev.position,
+            font: cfg.title_config!.font_preset || prev.font,
+            size: cfg.title_config!.font_size || prev.size,
+            color: cfg.title_config!.font_color || prev.color,
+          }))
+        }
+        if (cfg?.cover_config) {
+          const cc = cfg.cover_config as CoverConfig
+          setCoverSettings((prev: CoverConfig) => ({
+            ...prev,
+            enabled: cc.enabled ?? prev.enabled,
+            mode: cc.mode || prev.mode,
+            frame_time: cc.frame_time ?? prev.frame_time,
+            upload_url: cc.upload_url || prev.upload_url,
+            ai_suggested_time: cc.ai_suggested_time ?? prev.ai_suggested_time,
+            thumbnail_url: cc.thumbnail_url || prev.thumbnail_url,
+          }))
+        }
+        if (cfg?.asset_ids) {
+          setSelectedMaterials(cfg.asset_ids.filter((v): v is string => typeof v === "string"))
+        }
+      } catch (err) {
+        console.warn("加载模板草稿配置失败:", err)
+      }
+    }
+    loadPlanConfig()
+  }, [editPlanId, planConfigStr, setTitleSettings, setCoverSettings, setSelectedMaterials])
+}

apps/web/src/pages/generate/hooks/useGenerateFormState/useTemplateSelection.ts

@@ -0,0 +1,22 @@
+import { useState, useEffect } from "react"
+import { useQuery } from "@tanstack/react-query"
+import { getEditingTemplates } from "@/api/editing-planner"
+import type { EditingTemplate } from "@/api/editing-planner"
+
+export function useTemplateSelection() {
+  const [selectedTemplate, setSelectedTemplate] = useState("")
+  const { data: userTemplates = [] } = useQuery<EditingTemplate[]>({
+    queryKey: ["generate-templates"],
+    queryFn: () => getEditingTemplates(),
+    staleTime: 60_000,
+  })
+
+  /* 模板加载完成后自动选中第一个 */
+  useEffect(() => {
+    if (userTemplates.length > 0 && !selectedTemplate) {
+      setSelectedTemplate(userTemplates[0].id)
+    }
+  }, [userTemplates, selectedTemplate])
+
+  return { selectedTemplate, setSelectedTemplate, userTemplates }
+}

apps/web/src/pages/generate/hooks/useGenerateFormState/useTitleCoverSync.ts

@@ -0,0 +1,47 @@
+import { useEffect } from "react"
+import type { TitleSettings } from "../../types"
+import type { CoverConfig } from "../../../editing-planner/types"
+import type { EditingTemplate } from "@/api/editing-planner"
+
+interface UseTitleCoverSyncOptions {
+  selectedTemplate: string
+  userTemplates: EditingTemplate[]
+  setTitleSettings: (settings: TitleSettings | ((prev: TitleSettings) => TitleSettings)) => void
+  setCoverSettings: (settings: CoverConfig | ((prev: CoverConfig) => CoverConfig)) => void
+}
+
+/**
+ * 当选中模板变化时，自动同步标题和封面配置
+ */
+export function useTitleCoverSync({
+  selectedTemplate,
+  userTemplates,
+  setTitleSettings,
+  setCoverSettings,
+}: UseTitleCoverSyncOptions) {
+  useEffect(() => {
+    const tpl = userTemplates.find((t) => t.id === selectedTemplate)
+    if (tpl?.title_config) {
+      setTitleSettings((prev: TitleSettings) => ({
+        ...prev,
+        aiAutoSelect: tpl.title_config!.ai_auto_select,
+        title: tpl.title_config!.content || prev.title,
+        position: tpl.title_config!.position || prev.position,
+        font: tpl.title_config!.font_preset || prev.font,
+        size: tpl.title_config!.font_size || prev.size,
+        color: tpl.title_config!.font_color || prev.color,
+      }))
+    }
+    if (tpl?.cover_config) {
+      setCoverSettings((prev: CoverConfig) => ({
+        ...prev,
+        enabled: tpl.cover_config!.enabled ?? prev.enabled,
+        mode: (tpl.cover_config!.mode as CoverConfig["mode"]) || prev.mode,
+        frame_time: tpl.cover_config!.frame_time ?? prev.frame_time,
+        upload_url: tpl.cover_config!.upload_url || prev.upload_url,
+        ai_suggested_time: tpl.cover_config!.ai_suggested_time ?? prev.ai_suggested_time,
+        thumbnail_url: tpl.cover_config!.thumbnail_url || prev.thumbnail_url,
+      }))
+    }
+  }, [selectedTemplate, userTemplates, setTitleSettings, setCoverSettings])
+}

apps/web/src/pages/generate/hooks/useGenerateFormState/useVoiceState.ts

@@ -0,0 +1,30 @@
+import { useState, useMemo } from "react"
+import { useQuery } from "@tanstack/react-query"
+import type { PresetVoiceItem } from "@/api/voices"
+import { fetchPresetVoices } from "@/api/voices"
+
+export function useVoiceState() {
+  const [selectedVoice, setSelectedVoice] = useState("")
+  const [voiceMode, setVoiceMode] = useState<"preset" | "custom" | "clone">("preset")
+  const [selectedClonedVoice, setSelectedClonedVoice] = useState("")
+
+  /* 预置音色 API */
+  const { data: presetVoicesData } = useQuery({
+    queryKey: ["preset-voices"],
+    queryFn: fetchPresetVoices,
+  })
+  const presetVoices: PresetVoiceItem[] = useMemo(
+    () => presetVoicesData?.items ?? [],
+    [presetVoicesData],
+  )
+
+  return {
+    selectedVoice,
+    setSelectedVoice,
+    voiceMode,
+    setVoiceMode,
+    selectedClonedVoice,
+    setSelectedClonedVoice,
+    presetVoices,
+  }
+}

apps/web/src/pages/voice-materials/components/voice-material-row/useRowProgress.ts

@@ -1,4 +1,4 @@
-import { useRef, useCallback, useEffect } from "react"
+import { useRef, useCallback } from "react"
 
 interface UseRowProgressOptions {
   duration: number
@@ -7,22 +7,6 @@ interface UseRowProgressOptions {
 
 export function useRowProgress({ duration, onSeek }: UseRowProgressOptions) {
   const progressRef = useRef<HTMLDivElement>(null)
-  const listenersRef = useRef<{ move: ((e: MouseEvent) => void) | null; up: (() => void) | null }>({
-    move: null,
-    up: null,
-  })
-
-  const cleanupListeners = useCallback(() => {
-    const { move, up } = listenersRef.current
-    if (move) {
-      document.removeEventListener("mousemove", move)
-      listenersRef.current.move = null
-    }
-    if (up) {
-      document.removeEventListener("mouseup", up)
-      listenersRef.current.up = null
-    }
-  }, [])
 
   const handleMouseDown = useCallback(
     (e: React.MouseEvent<HTMLDivElement>) => {
@@ -32,7 +16,6 @@ export function useRowProgress({ duration, onSeek }: UseRowProgressOptions) {
       const doSeek = (ev: MouseEvent) => {
         if (!progressRef.current) return
         const rect = progressRef.current.getBoundingClientRect()
-        if (rect.width <= 0) return
         const percent = Math.max(0, Math.min(1, (ev.clientX - rect.left) / rect.width))
         onSeek(percent * duration)
       }
@@ -41,26 +24,15 @@ export function useRowProgress({ duration, onSeek }: UseRowProgressOptions) {
 
       const handleMove = (ev: MouseEvent) => doSeek(ev)
       const handleUp = () => {
-        cleanupListeners()
+        document.removeEventListener("mousemove", handleMove)
+        document.removeEventListener("mouseup", handleUp)
       }
 
-      // 先清理旧的，再添加新的
-      cleanupListeners()
-      listenersRef.current.move = handleMove
-      listenersRef.current.up = handleUp
-
       document.addEventListener("mousemove", handleMove)
       document.addEventListener("mouseup", handleUp)
     },
-    [duration, onSeek, cleanupListeners],
+    [duration, onSeek],
   )
 
-  // 组件卸载时清理事件监听器
-  useEffect(() => {
-    return () => {
-      cleanupListeners()
-    }
-  }, [cleanupListeners])
-
   return { progressRef, handleMouseDown }
 }

apps/web/src/test/pages/editing-planner/smoke.test.tsx

@@ -65,9 +65,6 @@ import "@/pages/editing-planner/components/filter/FilterPresetGrid"
 import "@/pages/editing-planner/components/filter/FilterManualAdjust"
 import "@/pages/editing-planner/components/intro-outro/IntroOutroBlock"
 import "@/pages/editing-planner/components/subtitle-style/SubtitlePreview"
-import "@/pages/editing-planner/components/subtitle-style/SubtitleModeSwitch"
-import "@/pages/editing-planner/components/subtitle-style/SubtitlePositionSelector"
-import "@/pages/editing-planner/components/subtitle-style/SubtitleEffectButtons"
 import "@/pages/editing-planner/components/tts/VoiceSelector"
 import "@/pages/editing-planner/components/tts/TtsSlider"
 import "@/pages/editing-planner/components/watermark/WatermarkTypeTabs"

apps/web/src/test/pages/generate/smoke.test.tsx

@@ -38,6 +38,11 @@ describe("GeneratePage module smoke test", () => {
 })
 import "@/pages/generate/hooks/useGenerateVideo"
 import "@/pages/generate/hooks/generate-video/useGenerationPolling"
+import "@/pages/generate/hooks/useGenerateFormState"
+import "@/pages/generate/hooks/useGenerateFormState/useTemplateSelection"
+import "@/pages/generate/hooks/useGenerateFormState/useTitleCoverSync"
+import "@/pages/generate/hooks/useGenerateFormState/useVoiceState"
+import "@/pages/generate/hooks/useGenerateFormState/usePlanConfigLoader"
 import "@/pages/generate/hooks/generate-video/types"
 import "@/pages/generate/hooks/generate-video/phase"
 import "@/pages/generate/hooks/generate-video/voiceConfig"

apps/web/src/test/pages/voice-materials/smoke.test.tsx

@@ -20,8 +20,6 @@ import "@/pages/voice-materials/components/voice-material-card/CardActions"
 import "@/pages/voice-materials/components/voice-material-card/BatchCheckbox"
 import "@/pages/voice-materials/components/voice-material-card/types"
 import "@/pages/voice-materials/components/VoiceMaterialRow"
-import "@/pages/voice-materials/components/voice-material-row/useRowProgress"
-import "@/pages/voice-materials/components/voice-material-row/TagDisplay"
 import "@/pages/voice-materials/components/Toolbar"
 import "@/pages/voice-materials/components/TagFilterBar"
 import "@/pages/voice-materials/components/BatchBar"

packages/application/cosyvoice_service.py

@@ -569,9 +569,7 @@ class CosyVoiceService:
             清洗后的 prefix
         """
         # 只保留字母和数字
-        import re
-
-        cleaned = re.sub(r"[^a-zA-Z0-9]", "", name)
+        cleaned = "".join(c for c in name if c.isalnum())
         # 最多10字符
         cleaned = cleaned[:10]
         # 如果清洗后为空，用默认值

tests/unit/domain/test_template_clip_converter.py

@@ -1,496 +0,0 @@
-"""模板片段转换器单测.
-
-纯函数模块，覆盖：枚举安全解析、config过滤、
-clip→template转换、snapshot双向转换、名称校验。
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from packages.domain.template_clip_config import (
-    ClipType,
-    TemplateClipConfig,
-    TransitionEffect,
-)
-from packages.domain.template_clip_converter import (
-    clip_config_to_snapshot,
-    clip_configs_to_snapshots,
-    clip_to_template_clip_config,
-    clips_to_template_clip_configs,
-    filter_clip_config,
-    filter_plan_config_to_template,
-    safe_parse_clip_type,
-    safe_parse_transition_effect,
-    snapshot_to_template_clip_config,
-    snapshots_to_template_clip_configs,
-    validate_template_name,
-)
-
-
-class TestSafeParseTransitionEffect:
-    def test_enum_passthrough(self):
-        result = safe_parse_transition_effect(TransitionEffect.FADE)
-        assert result == TransitionEffect.FADE
-        assert isinstance(result, TransitionEffect)
-
-    def test_valid_string(self):
-        result = safe_parse_transition_effect("fade")
-        assert result == TransitionEffect.FADE
-
-    def test_cut_string(self):
-        result = safe_parse_transition_effect("cut")
-        assert result == TransitionEffect.CUT
-
-    def test_invalid_string_returns_default(self):
-        result = safe_parse_transition_effect("invalid_effect")
-        assert result == TransitionEffect.CUT  # 默认
-
-    def test_invalid_string_custom_default(self):
-        result = safe_parse_transition_effect("bad", default=TransitionEffect.DISSOLVE)
-        assert result == TransitionEffect.DISSOLVE
-
-    def test_none_returns_default(self):
-        result = safe_parse_transition_effect(None)
-        assert result == TransitionEffect.CUT
-
-    def test_int_value_returns_default(self):
-        result = safe_parse_transition_effect(123)
-        assert result == TransitionEffect.CUT
-
-    def test_empty_string_returns_default(self):
-        result = safe_parse_transition_effect("")
-        assert result == TransitionEffect.CUT
-
-
-class TestSafeParseClipType:
-    def test_enum_passthrough(self):
-        result = safe_parse_clip_type(ClipType.SUBTITLE)
-        assert result == ClipType.SUBTITLE
-        assert isinstance(result, ClipType)
-
-    def test_valid_string_main(self):
-        result = safe_parse_clip_type("main")
-        assert result == ClipType.MAIN
-
-    def test_valid_string_text(self):
-        result = safe_parse_clip_type("subtitle")
-        assert result == ClipType.SUBTITLE
-
-    def test_invalid_string_returns_default(self):
-        result = safe_parse_clip_type("unknown_type")
-        assert result == ClipType.MAIN
-
-    def test_invalid_string_custom_default(self):
-        result = safe_parse_clip_type("bad", default=ClipType.TITLE)
-        assert result == ClipType.TITLE
-
-    def test_none_returns_default(self):
-        result = safe_parse_clip_type(None)
-        assert result == ClipType.MAIN
-
-    def test_dict_returns_default(self):
-        result = safe_parse_clip_type({"key": "val"})
-        assert result == ClipType.MAIN
-
-
-class TestFilterClipConfig:
-    def test_none_config(self):
-        result = filter_clip_config(None)
-        assert result == {}
-
-    def test_empty_dict(self):
-        result = filter_clip_config({})
-        assert result == {}
-
-    def test_basic_config_passthrough(self):
-        cfg = {"font_size": 24, "color": "red"}
-        result = filter_clip_config(cfg)
-        assert result == {"font_size": 24, "color": "red"}
-
-    def test_filters_asset_info(self):
-        cfg = {"font_size": 24, "asset_info": {"id": "123"}}
-        result = filter_clip_config(cfg)
-        assert "asset_info" not in result
-        assert result["font_size"] == 24
-
-    def test_filters_source_asset_id(self):
-        cfg = {"source_asset_id": "asset_1", "text_key": "hi"}
-        result = filter_clip_config(cfg)
-        assert "source_asset_id" not in result
-        assert result["text_key"] == "hi"
-
-    def test_playback_speed_added_when_not_one(self):
-        result = filter_clip_config({}, playback_speed=1.5)
-        assert result["playback_speed"] == 1.5
-
-    def test_playback_speed_one_not_added(self):
-        result = filter_clip_config({}, playback_speed=1.0)
-        assert "playback_speed" not in result
-
-    def test_playback_speed_none_not_added(self):
-        result = filter_clip_config({}, playback_speed=None)
-        assert "playback_speed" not in result
-
-    def test_playback_speed_config_takes_priority(self):
-        """clip_config中的playback_speed会覆盖参数传入的（因为update在后面）."""
-        cfg = {"playback_speed": 0.5, "other": "val"}
-        result = filter_clip_config(cfg, playback_speed=2.0)
-        assert result["playback_speed"] == 0.5  # config里的覆盖参数的
-        assert result["other"] == "val"
-
-    def test_custom_skip_keys(self):
-        cfg = {"keep_me": 1, "drop_me": 2, "also_drop": 3}
-        skip = frozenset({"drop_me", "also_drop"})
-        result = filter_clip_config(cfg, skip_keys=skip)
-        assert result == {"keep_me": 1}
-
-    def test_does_not_mutate_input(self):
-        cfg = {"a": 1, "asset_info": "x"}
-        original = dict(cfg)
-        filter_clip_config(cfg)
-        assert cfg == original  # 原dict不变
-
-
-class TestFilterPlanConfigToTemplate:
-    def test_none_config(self):
-        result = filter_plan_config_to_template(None)
-        assert result == {}
-
-    def test_empty_dict(self):
-        result = filter_plan_config_to_template({})
-        assert result == {}
-
-    def test_keeps_template_fields(self):
-        cfg = {"title": "My Template", "aspect_ratio": "9:16"}
-        result = filter_plan_config_to_template(cfg)
-        assert result == cfg
-
-    def test_filters_runtime_fields(self):
-        cfg = {
-            "title": "T",
-            "is_template_draft": True,
-            "asset_ids": ["a1"],
-            "source_edit_plan_id": "ep1",
-            "generation_task_id": "gt1",
-        }
-        result = filter_plan_config_to_template(cfg)
-        assert "is_template_draft" not in result
-        assert "asset_ids" not in result
-        assert "source_edit_plan_id" not in result
-        assert "generation_task_id" not in result
-        assert result["title"] == "T"
-
-    def test_custom_skip_keys(self):
-        cfg = {"keep": 1, "skip_a": 2, "skip_b": 3}
-        skip = frozenset({"skip_a", "skip_b"})
-        result = filter_plan_config_to_template(cfg, skip_keys=skip)
-        assert result == {"keep": 1}
-
-
-class TestClipToTemplateClipConfig:
-    @dataclass
-    class FakeClip:
-        clip_type: str = "main"
-        order: int = 0
-        duration: float = 5.0
-        text_content: str = ""
-        transition_effect: str = "cut"
-        playback_speed: float | None = None
-        config: dict | None = None
-
-    def test_basic_conversion(self):
-        clip = self.FakeClip(
-            clip_type="subtitle",
-            order=2,
-            duration=3.5,
-            text_content="Hello",
-            transition_effect="fade",
-        )
-        result = clip_to_template_clip_config("tpl_1", clip)
-        assert isinstance(result, TemplateClipConfig)
-        assert result.template_id == "tpl_1"
-        assert result.clip_type == ClipType.SUBTITLE
-        assert result.order == 2
-        assert result.min_duration == 3.5
-        assert result.max_duration == 3.5
-        assert result.text_template == "Hello"
-        assert result.transition_effect == TransitionEffect.FADE
-
-    def test_duration_fixed_min_max_equal(self):
-        """转换后 min_duration == max_duration == clip.duration."""
-        clip = self.FakeClip(duration=7.2)
-        result = clip_to_template_clip_config("t1", clip)
-        assert result.min_duration == 7.2
-        assert result.max_duration == 7.2
-
-    def test_zero_duration(self):
-        clip = self.FakeClip(duration=0.0)
-        result = clip_to_template_clip_config("t1", clip)
-        assert result.min_duration == 0.0
-        assert result.max_duration == 0.0
-
-    def test_none_duration_defaults_to_zero(self):
-        clip = self.FakeClip()
-        clip.duration = None  # type: ignore
-        result = clip_to_template_clip_config("t1", clip)
-        assert result.min_duration == 0.0
-        assert result.max_duration == 0.0
-
-    def test_empty_text_content_becomes_empty_string(self):
-        clip = self.FakeClip(text_content="")
-        result = clip_to_template_clip_config("t1", clip)
-        assert result.text_template == ""
-
-    def test_none_text_content_becomes_empty_string(self):
-        clip = self.FakeClip()
-        clip.text_content = None  # type: ignore
-        result = clip_to_template_clip_config("t1", clip)
-        assert result.text_template == ""
-
-    def test_playback_speed_in_config(self):
-        clip = self.FakeClip(playback_speed=1.5, config={"font": "bold"})
-        result = clip_to_template_clip_config("t1", clip)
-        assert result.config["playback_speed"] == 1.5
-        assert result.config["font"] == "bold"
-
-    def test_playback_speed_one_not_in_config(self):
-        clip = self.FakeClip(playback_speed=1.0)
-        result = clip_to_template_clip_config("t1", clip)
-        assert "playback_speed" not in result.config
-
-    def test_config_asset_info_filtered(self):
-        clip = self.FakeClip(config={"text_key": "hi", "asset_info": {"id": "a"}})
-        result = clip_to_template_clip_config("t1", clip)
-        assert "asset_info" not in result.config
-        assert result.config["text_key"] == "hi"
-
-    def test_invalid_clip_type_falls_back(self):
-        clip = self.FakeClip(clip_type="invalid_type")
-        result = clip_to_template_clip_config("t1", clip)
-        assert result.clip_type == ClipType.MAIN
-
-    def test_missing_attributes(self):
-        """对象没有某些属性时使用默认值."""
-
-        class MinimalClip:
-            pass
-
-        result = clip_to_template_clip_config("t1", MinimalClip())
-        assert result.clip_type == ClipType.MAIN
-        assert result.order == 0
-        assert result.min_duration == 0.0
-        assert result.text_template == ""
-        assert result.transition_effect == TransitionEffect.CUT
-
-
-class TestClipsToTemplateClipConfigs:
-    def test_empty_list(self):
-        result = clips_to_template_clip_configs("t1", [])
-        assert result == []
-
-    def test_multiple_clips(self):
-        clip_a = TestClipToTemplateClipConfig.FakeClip(clip_type="subtitle", order=0, duration=3.0, text_content="A")
-        clip_b = TestClipToTemplateClipConfig.FakeClip(clip_type="title", order=1, duration=5.0, text_content="")
-        result = clips_to_template_clip_configs("t1", [clip_a, clip_b])
-        assert len(result) == 2
-        assert result[0].clip_type == ClipType.SUBTITLE
-        assert result[0].order == 0
-        assert result[1].clip_type == ClipType.TITLE
-        assert result[1].order == 1
-        assert all(isinstance(r, TemplateClipConfig) for r in result)
-
-
-class TestClipConfigToSnapshot:
-    def test_basic_snapshot(self):
-        cfg = TemplateClipConfig.create(
-            template_id="t1",
-            clip_type=ClipType.SUBTITLE,
-            order=2,
-            min_duration=3.0,
-            max_duration=5.0,
-            text_template="Hello",
-            transition_effect=TransitionEffect.FADE,
-            config={"font_size": 20},
-        )
-        snap = clip_config_to_snapshot(cfg)
-        assert snap["clip_type"] == "subtitle"
-        assert snap["order"] == 2
-        assert snap["min_duration"] == 3.0
-        assert snap["max_duration"] == 5.0
-        assert snap["text_template"] == "Hello"
-        assert snap["transition_effect"] == "fade"
-        assert snap["config"] == {"font_size": 20}
-
-    def test_enum_values_are_strings(self):
-        cfg = TemplateClipConfig.create(template_id="t1", clip_type=ClipType.MAIN, order=0)
-        snap = clip_config_to_snapshot(cfg)
-        assert snap["clip_type"] == "main"
-        assert isinstance(snap["clip_type"], str)
-        assert snap["transition_effect"] == "cut"
-        assert isinstance(snap["transition_effect"], str)
-
-    def test_config_is_copy_not_reference(self):
-        config = {"key": "val"}
-        cfg = TemplateClipConfig.create(template_id="t1", clip_type=ClipType.MAIN, order=0, config=config)
-        snap = clip_config_to_snapshot(cfg)
-        snap["config"]["key"] = "changed"
-        assert config["key"] == "val"  # 原config不变
-
-    def test_empty_config(self):
-        cfg = TemplateClipConfig.create(template_id="t1", clip_type=ClipType.MAIN, order=0, config={})
-        snap = clip_config_to_snapshot(cfg)
-        assert snap["config"] == {}
-
-    def test_none_text_becomes_empty(self):
-        cfg = TemplateClipConfig.create(template_id="t1", clip_type=ClipType.MAIN, order=0)
-        cfg.text_template = None  # type: ignore
-        snap = clip_config_to_snapshot(cfg)
-        assert snap["text_template"] == ""
-
-
-class TestClipConfigsToSnapshots:
-    def test_empty_list(self):
-        assert clip_configs_to_snapshots([]) == []
-
-    def test_multiple_configs(self):
-        cfg1 = TemplateClipConfig.create(
-            template_id="t1",
-            clip_type=ClipType.SUBTITLE,
-            order=0,
-            min_duration=2.0,
-            max_duration=2.0,
-        )
-        cfg2 = TemplateClipConfig.create(
-            template_id="t1",
-            clip_type=ClipType.TITLE,
-            order=1,
-            min_duration=3.0,
-            max_duration=3.0,
-        )
-        snaps = clip_configs_to_snapshots([cfg1, cfg2])
-        assert len(snaps) == 2
-        assert snaps[0]["clip_type"] == "subtitle"
-        assert snaps[1]["clip_type"] == "title"
-
-
-class TestSnapshotToTemplateClipConfig:
-    def test_basic_conversion(self):
-        snap = {
-            "clip_type": "subtitle",
-            "order": 3,
-            "min_duration": 2.5,
-            "max_duration": 4.5,
-            "text_template": "World",
-            "transition_effect": "dissolve",
-            "config": {"color": "blue"},
-        }
-        result = snapshot_to_template_clip_config("tpl_2", snap)
-        assert isinstance(result, TemplateClipConfig)
-        assert result.template_id == "tpl_2"
-        assert result.clip_type == ClipType.SUBTITLE
-        assert result.order == 3
-        assert result.min_duration == 2.5
-        assert result.max_duration == 4.5
-        assert result.text_template == "World"
-        assert result.transition_effect == TransitionEffect.DISSOLVE
-        assert result.config == {"color": "blue"}
-
-    def test_empty_snapshot_uses_defaults(self):
-        result = snapshot_to_template_clip_config("t1", {})
-        assert result.clip_type == ClipType.MAIN
-        assert result.order == 0
-        assert result.min_duration == 0.0
-        assert result.max_duration == 0.0
-        assert result.text_template == ""
-        assert result.transition_effect == TransitionEffect.CUT
-        assert result.config == {}
-
-    def test_invalid_clip_type_defaults(self):
-        snap = {"clip_type": "unknown"}
-        result = snapshot_to_template_clip_config("t1", snap)
-        assert result.clip_type == ClipType.MAIN
-
-    def test_invalid_transition_defaults(self):
-        snap = {"transition_effect": "bad_effect"}
-        result = snapshot_to_template_clip_config("t1", snap)
-        assert result.transition_effect == TransitionEffect.CUT
-
-    def test_none_config_becomes_empty(self):
-        snap = {"config": None}
-        result = snapshot_to_template_clip_config("t1", snap)
-        assert result.config == {}
-
-
-class TestSnapshotsToTemplateClipConfigs:
-    def test_empty_list(self):
-        result = snapshots_to_template_clip_configs("t1", [])
-        assert result == []
-
-    def test_multiple_snapshots(self):
-        snaps = [
-            {"clip_type": "subtitle", "order": 0, "text_template": "A"},
-            {"clip_type": "title", "order": 1},
-        ]
-        result = snapshots_to_template_clip_configs("t1", snaps)
-        assert len(result) == 2
-        assert result[0].clip_type == ClipType.SUBTITLE
-        assert result[0].text_template == "A"
-        assert result[1].clip_type == ClipType.TITLE
-
-
-class TestRoundTrip:
-    """clip → config → snapshot → config 双向转换一致性."""
-
-    def test_snapshot_config_round_trip(self):
-        original = TemplateClipConfig.create(
-            template_id="t1",
-            clip_type=ClipType.SUBTITLE,
-            order=5,
-            min_duration=3.0,
-            max_duration=6.0,
-            text_template="Round trip",
-            transition_effect=TransitionEffect.FADE,
-            config={"key": "value"},
-        )
-        snap = clip_config_to_snapshot(original)
-        restored = snapshot_to_template_clip_config("t1", snap)
-        assert restored.clip_type == original.clip_type
-        assert restored.order == original.order
-        assert restored.min_duration == original.min_duration
-        assert restored.max_duration == original.max_duration
-        assert restored.text_template == original.text_template
-        assert restored.transition_effect == original.transition_effect
-        assert restored.config == original.config
-
-
-class TestValidateTemplateName:
-    def test_valid_name(self):
-        assert validate_template_name("我的模板") == "我的模板"
-
-    def test_strips_whitespace(self):
-        assert validate_template_name("  Hello  ") == "Hello"
-
-    def test_empty_string_raises(self):
-        try:
-            validate_template_name("")
-        except ValueError as e:
-            assert "不能为空" in str(e)
-        else:
-            raise AssertionError("expected ValueError")
-
-    def test_whitespace_only_raises(self):
-        try:
-            validate_template_name("   ")
-        except ValueError as e:
-            assert "不能为空" in str(e)
-        else:
-            raise AssertionError("expected ValueError")
-
-    def test_none_raises(self):
-        try:
-            validate_template_name(None)
-        except ValueError as e:
-            assert "不能为空" in str(e)
-        else:
-            raise AssertionError("expected ValueError")

tests/unit/domain/test_verification_code.py

@@ -1,280 +0,0 @@
-"""VerificationCode 单元测试."""
-
-from __future__ import annotations
-
-from datetime import datetime, timedelta, timezone
-from unittest.mock import patch
-
-import pytest
-from domain.verification_code import VerificationCode
-
-
-class TestVerificationCodeCreate:
-    """create() 工厂方法测试."""
-
-    def test_create_basic(self):
-        vc = VerificationCode.create("test@example.com", "email_login")
-        assert vc.id is not None
-        assert len(vc.id) == 32
-        assert vc.recipient == "test@example.com"
-        assert vc.code_type == "email_login"
-        assert len(vc.code) == 6
-        assert vc.code.isdigit()
-        assert vc.used_at is None
-        assert vc.attempts == 0
-        assert vc.created_at is not None
-        assert vc.expires_at > vc.created_at
-
-    def test_create_recipient_stripped(self):
-        vc = VerificationCode.create("  test@example.com  ", "email_login")
-        assert vc.recipient == "test@example.com"
-
-    def test_create_custom_code(self):
-        vc = VerificationCode.create("test@example.com", "email_login", custom_code="123456")
-        assert vc.code == "123456"
-
-    def test_create_custom_ttl(self):
-        fixed_now = datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc)
-        with patch("domain.verification_code.datetime") as mock_dt:
-            mock_dt.now.return_value = fixed_now
-            mock_dt.side_effect = lambda *a, **kw: datetime(*a, **kw)
-            vc = VerificationCode.create("test@example.com", "email_login", ttl_seconds=60)
-        assert vc.expires_at == fixed_now + timedelta(seconds=60)
-
-    def test_create_default_ttl_300(self):
-        fixed_now = datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc)
-        with patch("domain.verification_code.datetime") as mock_dt:
-            mock_dt.now.return_value = fixed_now
-            mock_dt.side_effect = lambda *a, **kw: datetime(*a, **kw)
-            vc = VerificationCode.create("test@example.com", "email_login")
-        assert vc.expires_at == fixed_now + timedelta(seconds=300)
-
-    def test_create_unique_ids(self):
-        vc1 = VerificationCode.create("a@b.com", "email_login")
-        vc2 = VerificationCode.create("a@b.com", "email_login")
-        assert vc1.id != vc2.id
-
-    def test_create_unique_codes(self):
-        codes = set()
-        for _ in range(20):
-            vc = VerificationCode.create("a@b.com", "email_login")
-            codes.add(vc.code)
-        # 20个随机6位码几乎肯定不都一样
-        assert len(codes) > 1
-
-    def test_create_phone_recipient(self):
-        vc = VerificationCode.create("13800138000", "phone_login")
-        assert vc.recipient == "13800138000"
-        assert vc.code_type == "phone_login"
-
-    def test_create_all_code_types(self):
-        for ct in ["email_bind", "phone_bind", "email_login", "phone_login", "reset_password"]:
-            vc = VerificationCode.create("test@example.com", ct)
-            assert vc.code_type == ct
-
-
-class TestVerificationCodeIsExpired:
-    """is_expired 属性测试."""
-
-    def test_not_expired_future(self):
-        future = datetime.now(timezone.utc) + timedelta(hours=1)
-        vc = VerificationCode(
-            id="1",
-            recipient="a@b.com",
-            code="123456",
-            code_type="email_login",
-            expires_at=future,
-        )
-        assert vc.is_expired is False
-
-    def test_expired_past(self):
-        past = datetime.now(timezone.utc) - timedelta(hours=1)
-        vc = VerificationCode(
-            id="1",
-            recipient="a@b.com",
-            code="123456",
-            code_type="email_login",
-            expires_at=past,
-        )
-        assert vc.is_expired is True
-
-    def test_expired_boundary_exact(self):
-        # 用mock固定时间，expires_at等于当前时间不算过期
-        fixed_now = datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc)
-        with patch("domain.verification_code.datetime") as mock_dt:
-            mock_dt.now.return_value = fixed_now
-            mock_dt.side_effect = lambda *a, **kw: datetime(*a, **kw)
-            vc = VerificationCode(
-                id="1",
-                recipient="a@b.com",
-                code="123456",
-                code_type="email_login",
-                expires_at=fixed_now,
-            )
-            assert vc.is_expired is False
-
-
-class TestVerificationCodeIsUsed:
-    """is_used 属性测试."""
-
-    def test_not_used_default(self):
-        vc = VerificationCode.create("a@b.com", "email_login")
-        assert vc.is_used is False
-
-    def test_is_used_after_mark(self):
-        vc = VerificationCode.create("a@b.com", "email_login")
-        vc.mark_used()
-        assert vc.is_used is True
-
-
-class TestVerificationCodeIsValid:
-    """is_valid 属性测试."""
-
-    def test_valid_fresh(self):
-        future = datetime.now(timezone.utc) + timedelta(hours=1)
-        vc = VerificationCode(
-            id="1",
-            recipient="a@b.com",
-            code="123456",
-            code_type="email_login",
-            expires_at=future,
-        )
-        assert vc.is_valid is True
-
-    def test_invalid_expired(self):
-        past = datetime.now(timezone.utc) - timedelta(hours=1)
-        vc = VerificationCode(
-            id="1",
-            recipient="a@b.com",
-            code="123456",
-            code_type="email_login",
-            expires_at=past,
-        )
-        assert vc.is_valid is False
-
-    def test_invalid_used(self):
-        future = datetime.now(timezone.utc) + timedelta(hours=1)
-        vc = VerificationCode(
-            id="1",
-            recipient="a@b.com",
-            code="123456",
-            code_type="email_login",
-            expires_at=future,
-        )
-        vc.mark_used()
-        assert vc.is_valid is False
-
-    def test_invalid_expired_and_used(self):
-        past = datetime.now(timezone.utc) - timedelta(hours=1)
-        vc = VerificationCode(
-            id="1",
-            recipient="a@b.com",
-            code="123456",
-            code_type="email_login",
-            expires_at=past,
-        )
-        vc.mark_used()
-        assert vc.is_valid is False
-
-
-class TestVerificationCodeMarkUsed:
-    """mark_used 方法测试."""
-
-    def test_mark_used_sets_timestamp(self):
-        vc = VerificationCode.create("a@b.com", "email_login")
-        assert vc.used_at is None
-        before = datetime.now(timezone.utc)
-        vc.mark_used()
-        after = datetime.now(timezone.utc)
-        assert vc.used_at is not None
-        assert before <= vc.used_at <= after
-
-    def test_mark_used_twice_overwrites(self):
-        vc = VerificationCode.create("a@b.com", "email_login")
-        vc.mark_used()
-        first = vc.used_at
-        # 时间足够短，一般不会不同，但确保可以重复调用
-        vc.mark_used()
-        assert vc.used_at is not None
-
-
-class TestVerificationCodeIncrementAttempts:
-    """increment_attempts 方法测试."""
-
-    def test_default_zero(self):
-        vc = VerificationCode.create("a@b.com", "email_login")
-        assert vc.attempts == 0
-
-    def test_increment_once(self):
-        vc = VerificationCode.create("a@b.com", "email_login")
-        vc.increment_attempts()
-        assert vc.attempts == 1
-
-    def test_increment_multiple(self):
-        vc = VerificationCode.create("a@b.com", "email_login")
-        for _i in range(5):
-            vc.increment_attempts()
-        assert vc.attempts == 5
-
-
-class TestVerificationCodeBasics:
-    """基础构造和 slots 测试."""
-
-    def test_direct_construction(self):
-        now = datetime.now(timezone.utc)
-        vc = VerificationCode(
-            id="abc123",
-            recipient="test@test.com",
-            code="000000",
-            code_type="email_bind",
-            expires_at=now + timedelta(minutes=5),
-            used_at=None,
-            attempts=0,
-            created_at=now,
-        )
-        assert vc.id == "abc123"
-        assert vc.recipient == "test@test.com"
-        assert vc.code == "000000"
-
-    def test_slots_no_extra_attrs(self):
-        vc = VerificationCode.create("a@b.com", "email_login")
-        with pytest.raises((AttributeError, TypeError)):
-            vc.new_field = "value"  # type: ignore[attr-defined]
-
-    def test_equality_same_id(self):
-        now = datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc)
-        vc1 = VerificationCode(
-            id="same",
-            recipient="a@b.com",
-            code="111",
-            code_type="email_login",
-            expires_at=now,
-            created_at=now,
-        )
-        vc2 = VerificationCode(
-            id="same",
-            recipient="a@b.com",
-            code="111",
-            code_type="email_login",
-            expires_at=now,
-            created_at=now,
-        )
-        assert vc1 == vc2
-
-    def test_equality_different_id(self):
-        now = datetime.now(timezone.utc)
-        vc1 = VerificationCode(
-            id="id1",
-            recipient="a@b.com",
-            code="111",
-            code_type="email_login",
-            expires_at=now,
-        )
-        vc2 = VerificationCode(
-            id="id2",
-            recipient="a@b.com",
-            code="111",
-            code_type="email_login",
-            expires_at=now,
-        )
-        assert vc1 != vc2