feat: add STRM tree dry-run preview

internal/handler/strm.go

@@ -118,6 +118,7 @@ type generateSTRMTreeReq struct {
 	BaseURL      string   `json:"base_url"`
 	Overwrite    bool     `json:"overwrite"`
 	Cleanup      bool     `json:"cleanup"`
+	DryRun       bool     `json:"dry_run"`
 }
 
 func generateSTRMHandler(svc *service.Container) gin.HandlerFunc {
@@ -189,6 +190,7 @@ func generateSTRMFromTreeHandler(svc *service.Container) gin.HandlerFunc {
 			BaseURL:      baseURL,
 			Overwrite:    req.Overwrite,
 			Cleanup:      req.Cleanup,
+			DryRun:       req.DryRun,
 		})
 		if err != nil {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})

internal/service/strm_generate.go

@@ -31,6 +31,7 @@ type GenerateSTRMResult struct {
 	Updated   int                `json:"updated"`
 	Skipped   int                `json:"skipped"`
 	Cleaned   int                `json:"cleaned"`
+	Previewed int                `json:"previewed,omitempty"`
 	Errors    []string           `json:"errors,omitempty"`
 	Items     []GenerateSTRMItem `json:"items,omitempty"`
 }
@@ -269,6 +270,8 @@ func (r *GenerateSTRMResult) addItem(item GenerateSTRMItem) {
 		r.Updated++
 	case "skipped":
 		r.Skipped++
+	case "preview":
+		r.Previewed++
 	case "error":
 		r.Errors = append(r.Errors, fmt.Sprintf("%s: %s", item.Title, item.Reason))
 	}
@@ -285,6 +288,7 @@ func (r *GenerateSTRMResult) merge(part *GenerateSTRMResult) {
 	r.Updated += part.Updated
 	r.Skipped += part.Skipped
 	r.Cleaned += part.Cleaned
+	r.Previewed += part.Previewed
 	r.Errors = append(r.Errors, part.Errors...)
 	r.Items = append(r.Items, part.Items...)
 }

internal/service/strm_tree_import.go

@@ -19,6 +19,7 @@ type GenerateSTRMTreeOptions struct {
 	BaseURL      string   `json:"base_url,omitempty"`
 	Overwrite    bool     `json:"overwrite"`
 	Cleanup      bool     `json:"cleanup"`
+	DryRun       bool     `json:"dry_run"`
 }
 
 type strmTreeSource struct {
@@ -36,8 +37,10 @@ func (s *STRMService) GenerateFromTree(ctx context.Context, opts GenerateSTRMTre
 	if outputDir == "" || outputDir == "." {
 		return nil, errors.New("output_dir required")
 	}
-	if err := os.MkdirAll(outputDir, 0o755); err != nil { // #nosec G301 -- STRM output directories must be readable by media players.
+	if !opts.DryRun {
-		return nil, err
+		if err := os.MkdirAll(outputDir, 0o755); err != nil { // #nosec G301 -- STRM output directories must be readable by media players.
+			return nil, err
+		}
 	}
 	result := &GenerateSTRMResult{LibraryID: provider, OutputDir: outputDir}
 	expectedFiles := make(map[string]struct{})
@@ -53,7 +56,7 @@ func (s *STRMService) GenerateFromTree(ctx context.Context, opts GenerateSTRMTre
 		}
 		result.addItem(item)
 	}
-	if opts.Cleanup && len(expectedFiles) > 0 {
+	if opts.Cleanup && !opts.DryRun && len(expectedFiles) > 0 {
 		cleanupDir := outputDir
 		if prefix, err := strmTreeOutputPrefixPath(opts.OutputPrefix); err == nil && prefix != "" {
 			cleanupDir = filepath.Join(outputDir, prefix)
@@ -94,6 +97,11 @@ func generateTreeSTRMItem(outputDir string, source strmTreeSource, opts Generate
 	if _, err := os.Stat(filePath); err == nil {
 		action = "updated"
 	}
+	if opts.DryRun {
+		item.Action = "preview"
+		item.Reason = action
+		return item
+	}
 	if err := os.MkdirAll(filepath.Dir(filePath), 0o755); err != nil { // #nosec G301 -- STRM output directories must be readable by media players.
 		item.Action = "error"
 		item.Reason = err.Error()

internal/service/strm_tree_import_test.go

@@ -81,3 +81,59 @@ func TestGenerateSTRMFromTreeSupportsCommonVideoExtensions(t *testing.T) {
 		t.Fatalf("iso source should stay ignored by tree generator, stat err=%v", err)
 	}
 }
+
+func TestGenerateSTRMFromTreeDryRunDoesNotWriteOrCleanup(t *testing.T) {
+	outDir := filepath.Join(t.TempDir(), "strm")
+	stale := filepath.Join(outDir, "Movies", "Old.Movie.strm")
+	if err := os.MkdirAll(filepath.Dir(stale), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(stale, []byte("old\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	svc := NewSTRMService(zap.NewNop(), nil, nil)
+
+	res, err := svc.GenerateFromTree(t.Context(), GenerateSTRMTreeOptions{
+		Provider:  "openlist",
+		Paths:     []string{"/Movies/New.Movie.2026.mkv"},
+		OutputDir: outDir,
+		Cleanup:   true,
+		DryRun:    true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Previewed != 1 || res.Generated != 0 || res.Updated != 0 || res.Cleaned != 0 || len(res.Errors) != 0 {
+		t.Fatalf("result = %#v, want one preview and no writes", res)
+	}
+	if len(res.Items) != 1 || res.Items[0].Action != "preview" || res.Items[0].Reason != "generated" {
+		t.Fatalf("preview item = %#v, want generated preview", res.Items)
+	}
+	if _, err := os.Stat(filepath.Join(outDir, "Movies", "New.Movie.2026.strm")); !os.IsNotExist(err) {
+		t.Fatalf("dry run should not write new strm, stat err=%v", err)
+	}
+	if got := readSTRM(t, stale); got != "old" {
+		t.Fatalf("dry run cleanup touched stale file: %q", got)
+	}
+}
+
+func TestGenerateSTRMFromTreeDryRunDoesNotCreateOutputDir(t *testing.T) {
+	outDir := filepath.Join(t.TempDir(), "missing-strm")
+	svc := NewSTRMService(zap.NewNop(), nil, nil)
+
+	res, err := svc.GenerateFromTree(t.Context(), GenerateSTRMTreeOptions{
+		Provider:  "openlist",
+		Paths:     []string{"/Movies/New.Movie.2026.mkv"},
+		OutputDir: outDir,
+		DryRun:    true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Previewed != 1 {
+		t.Fatalf("previewed = %d, want 1", res.Previewed)
+	}
+	if _, err := os.Stat(outDir); !os.IsNotExist(err) {
+		t.Fatalf("dry run should not create output dir, stat err=%v", err)
+	}
+}

web/src/api/strm.ts

@@ -17,6 +17,7 @@ export type GenerateSTRMResult = {
   updated: number
   skipped: number
   cleaned: number
+  previewed?: number
   errors?: string[]
   items?: Array<{
     media_id: string
@@ -38,6 +39,7 @@ export type GenerateSTRMTreeInput = {
   base_url?: string
   overwrite?: boolean
   cleanup?: boolean
+  dry_run?: boolean
 }
 
 export const strmAPI = {

web/src/pages/StrmGenerateSectionParts.tsx

@@ -271,6 +271,7 @@ export function StrmGenerateResultPanel({ result }: { result: GenerateSTRMResult
         输出目录：{result.output_dir}
       </div>
       <div className="mt-1">
+        {result.previewed ? `预检 ${result.previewed} · ` : ''}
         新增 {result.generated} · 更新 {result.updated} · 跳过 {result.skipped} · 清理 {result.cleaned || 0}
       </div>
       {result.errors && result.errors.length > 0 && (

web/src/pages/StrmTreeGenerateSection.tsx

@@ -32,6 +32,7 @@ export function StrmTreeGenerateSection({
   cleanup,
   generating,
   onGenerate,
+  onPreview,
   onImportTreeFile,
   outputDir,
   outputPrefix,
@@ -39,6 +40,7 @@ export function StrmTreeGenerateSection({
   pathsText,
   provider,
   result,
+  runningMode,
   setBaseURL,
   setCleanup,
   setOutputDir,
@@ -167,13 +169,22 @@ export function StrmTreeGenerateSection({
           <input type="checkbox" checked={cleanup} onChange={(e) => setCleanup(e.target.checked)} />
           清理不在当前目录树中的旧 STRM
         </label>
+        <button
+          type="button"
+          disabled={generating || (!treeText.trim() && !pathsText.trim()) || !outputDir.trim()}
+          className="inline-flex min-h-10 items-center justify-center gap-2 rounded-2xl border border-primary-400/40 px-3 py-2 text-sm font-medium text-brand-500 transition hover:bg-primary-400/10 disabled:cursor-not-allowed disabled:opacity-50 md:col-span-2"
+          onClick={onPreview}
+        >
+          {runningMode === 'preview' ? <Loader2 size={16} className="animate-spin" /> : <FolderTree size={16} />}
+          {runningMode === 'preview' ? '预检中...' : '预检目录树'}
+        </button>
         <button
           type="submit"
           disabled={generating || (!treeText.trim() && !pathsText.trim()) || !outputDir.trim()}
-          className="neon-button md:col-span-4"
+          className="neon-button md:col-span-2"
         >
-          {generating ? <Loader2 size={16} className="animate-spin" /> : <FolderTree size={16} />}
+          {runningMode === 'generate' ? <Loader2 size={16} className="animate-spin" /> : <FolderTree size={16} />}
-          {generating ? '生成中...' : '按目录树生成'}
+          {runningMode === 'generate' ? '生成中...' : '按目录树生成'}
         </button>
       </form>
       <StrmGenerateResultPanel result={result} />

web/src/pages/useStrmTreeGenerateForm.ts

@@ -16,7 +16,7 @@ export function useStrmTreeGenerateForm() {
   const [pathsText, setPathsText] = useState('')
   const [overwrite, setOverwrite] = useState(false)
   const [cleanup, setCleanup] = useState(false)
-  const [generating, setGenerating] = useState(false)
+  const [runningMode, setRunningMode] = useState<'generate' | 'preview' | null>(null)
   const [result, setResult] = useState<GenerateSTRMResult | null>(null)
 
   const onImportTreeFile = async (event: ChangeEvent<HTMLInputElement>) => {
@@ -38,8 +38,7 @@ export function useStrmTreeGenerateForm() {
     }
   }
 
-  const onGenerate = async (event: FormEvent) => {
+  const runGenerate = async (dryRun: boolean) => {
-    event.preventDefault()
     const trimmedBaseURL = baseURL.trim()
     const paths = parsePathList(pathsText)
     if (!treeText.trim() && paths.length === 0) {
@@ -50,7 +49,7 @@ export function useStrmTreeGenerateForm() {
       toast.error('域名必须以 http:// 或 https:// 开头')
       return
     }
-    setGenerating(true)
+    setRunningMode(dryRun ? 'preview' : 'generate')
     try {
       const next = await strmAPI.generateFromTree({
         provider,
@@ -62,28 +61,44 @@ export function useStrmTreeGenerateForm() {
         paths: paths.length > 0 ? paths : undefined,
         overwrite,
         cleanup,
+        dry_run: dryRun,
       })
       setResult(next)
-      toast.success(`生成完成：新增 ${next.generated} · 更新 ${next.updated} · 跳过 ${next.skipped}`)
+      if (dryRun) {
+        toast.success(`预检完成：将处理 ${next.previewed ?? 0} 个视频 · 跳过 ${next.skipped}`)
+      } else {
+        toast.success(`生成完成：新增 ${next.generated} · 更新 ${next.updated} · 跳过 ${next.skipped}`)
+      }
     } catch (err: unknown) {
-      toast.error(apiErrorMessage(err, '目录树生成失败'))
+      toast.error(apiErrorMessage(err, dryRun ? '目录树预检失败' : '目录树生成失败'))
     } finally {
-      setGenerating(false)
+      setRunningMode(null)
     }
   }
 
+  const onGenerate = async (event: FormEvent) => {
+    event.preventDefault()
+    await runGenerate(false)
+  }
+
+  const onPreview = async () => {
+    await runGenerate(true)
+  }
+
   return {
     baseURL,
     cleanup,
-    generating,
+    generating: runningMode !== null,
     onImportTreeFile,
     onGenerate,
+    onPreview,
     outputDir,
     outputPrefix,
     overwrite,
     pathsText,
     provider,
     result,
+    runningMode,
     setBaseURL,
     setCleanup,
     setOutputDir,