refactor: split modules and harden scraping workflows

internal/service/scraper_test.go

@@ -8,7 +8,6 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
-	"time"
 
 	"github.com/glebarez/sqlite"
 	"go.uber.org/zap"
@@ -19,327 +18,6 @@ import (
 	"github.com/ShukeBta/MediaStationGo/internal/repository"
 )
 
-func TestCleanQuery(t *testing.T) {
-	cases := []struct {
-		in        string
-		wantTitle string
-		wantYear  int
-	}{
-		{"Inception.2010.1080p.BluRay.x264.mkv", "inception", 2010},
-		{"The_Matrix_(1999).1080p.WEB-DL.H265.mp4", "the matrix", 1999},
-		{"interstellar.2014.4k.hdr.dts.atmos.mkv", "interstellar", 2014},
-		{"My Movie 2022 [HDR] (1080p) [TGx].mp4", "my movie", 2022},
-		{"NoYearOrTags.mkv", "noyearortags", 0},
-		{"亏成首富从游戏开始 The Richest in Game - S01E11 - 4K.mp4", "亏成首富从游戏开始 the richest in game", 0},
-		{"紫川.2024.S02E24.第24集.2160p.WEB-DL.H.265-ColorTV.mkv", "紫川", 2024},
-		{"紫川 (2024) {tmdb-247590}", "紫川", 2024},
-	}
-	for _, tc := range cases {
-		t.Run(tc.in, func(t *testing.T) {
-			gotTitle, gotYear := CleanQuery(tc.in)
-			if gotTitle != tc.wantTitle || gotYear != tc.wantYear {
-				t.Errorf("CleanQuery(%q) = (%q, %d), want (%q, %d)",
-					tc.in, gotTitle, gotYear, tc.wantTitle, tc.wantYear)
-			}
-		})
-	}
-}
-
-func TestExternalIDHintsFromText(t *testing.T) {
-	hints := externalIDHintsFromText("国漫/折腰 (2025) {tmdb 296753}/Season 1/折腰.S01E01.mkv")
-	if hints.TMDbID != 296753 {
-		t.Fatalf("tmdb hint = %d, want 296753", hints.TMDbID)
-	}
-	hints = externalIDHintsFromText("Movie (2026) {tmdb-1630433} [douban=3622222] {bgm 456789} {tvdb:12345}")
-	if hints.TMDbID != 1630433 || hints.DoubanID != "3622222" || hints.BangumiID != 456789 || hints.TheTVDBID != "12345" {
-		t.Fatalf("external hints not parsed: %+v", hints)
-	}
-}
-
-func TestPathHintMetadataDoesNotMarkMediaMatched(t *testing.T) {
-	meta, hints := pathHintMetadata("cloud://openlist/国漫/折腰 (2025) {tmdb 296753}/Season 1/折腰.S01E01.mkv", true)
-	if meta == nil || hints.TMDbID != 296753 || meta.TMDbID != 296753 || meta.Title != "折腰" || meta.Year != 2025 {
-		t.Fatalf("path hint metadata = %+v hints=%+v", meta, hints)
-	}
-	media := &model.Media{Title: "折腰", ScrapeStatus: "pending"}
-	applyLocalMetadata(media, meta)
-	if media.ScrapeStatus != "pending" {
-		t.Fatalf("path hints alone must not mark media matched, got %q", media.ScrapeStatus)
-	}
-}
-
-func TestEnrichOneCloudPathHintOverridesStaleTMDbID(t *testing.T) {
-	var requested []string
-	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		requested = append(requested, r.URL.Path)
-		w.Header().Set("Content-Type", "application/json")
-		switch r.URL.Path {
-		case "/tv/296753":
-			_ = json.NewEncoder(w).Encode(map[string]any{
-				"id":             296753,
-				"name":           "折腰",
-				"overview":       "正确的剧集条目",
-				"poster_path":    "/zheyao.jpg",
-				"first_air_date": "2025-05-13",
-				"origin_country": []string{"CN"},
-			})
-		default:
-			http.NotFound(w, r)
-		}
-	}))
-	defer upstream.Close()
-
-	db, err := gorm.Open(sqlite.Open("file::memory:?cache=shared"), &gorm.Config{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := db.AutoMigrate(&model.Library{}, &model.Series{}, &model.Media{}); err != nil {
-		t.Fatal(err)
-	}
-	repos := repository.New(db)
-	cfg := &config.Config{}
-	cfg.Secrets.TMDbAPIKey = "test-key"
-	cfg.Secrets.TMDbAPIProxy = upstream.URL
-	cfg.Secrets.TMDbImageProxy = upstream.URL + "/images"
-	log := zap.NewNop()
-	scraper := NewScraperService(cfg, log, repos, NewTMDbProvider(cfg, log, nil), nil, nil, nil, NewHub(log))
-
-	lib := model.Library{Name: "OpenList · 国产剧", Path: "cloud://openlist/国产剧", Type: "tv", Enabled: true}
-	if err := repos.DB.Create(&lib).Error; err != nil {
-		t.Fatal(err)
-	}
-	media := model.Media{
-		LibraryID:    lib.ID,
-		Title:        "折腰",
-		Path:         "cloud://openlist/国产剧/折腰 (2025) {tmdb-296753}/Season 1/折腰.S01E01.mkv",
-		SeasonNum:    1,
-		EpisodeNum:   1,
-		TMDbID:       220269,
-		ScrapeStatus: "pending",
-	}
-	if err := repos.DB.Create(&media).Error; err != nil {
-		t.Fatal(err)
-	}
-
-	if err := scraper.EnrichOne(t.Context(), &media); err != nil {
-		t.Fatal(err)
-	}
-	var got model.Media
-	if err := repos.DB.First(&got, "id = ?", media.ID).Error; err != nil {
-		t.Fatal(err)
-	}
-	if got.ScrapeStatus != "matched" || got.TMDbID != 296753 || got.Title != "折腰" || got.PosterURL == "" {
-		t.Fatalf("path hint was not authoritative: status=%q tmdb=%d title=%q poster=%q", got.ScrapeStatus, got.TMDbID, got.Title, got.PosterURL)
-	}
-	for _, path := range requested {
-		if path == "/tv/220269" || path == "/movie/220269" {
-			t.Fatalf("scraper queried stale tmdb id; requests=%v", requested)
-		}
-	}
-}
-
-func TestManualRequestMatchFallsBackToCandidatePayload(t *testing.T) {
-	scraper := &ScraperService{}
-	match, err := scraper.manualRequestMatch(t.Context(), ManualScrapeRequest{
-		Source:   "douban",
-		Title:    "手动选择的电影",
-		DoubanID: "1234567",
-		Year:     2026,
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if match.Title != "手动选择的电影" || match.DoubanID != "1234567" || match.Year != 2026 {
-		t.Fatalf("fallback match = %#v", match)
-	}
-}
-
-func TestManualSearchReturnsTMDbCandidatePage(t *testing.T) {
-	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "application/json")
-		if r.URL.Path != "/search/movie" {
-			http.NotFound(w, r)
-			return
-		}
-		_ = json.NewEncoder(w).Encode(map[string]any{
-			"results": []map[string]any{
-				{
-					"id":            101,
-					"title":         "错误的同名电影",
-					"poster_path":   "/wrong.jpg",
-					"release_date":  "2021-01-01",
-					"vote_average":  5.1,
-					"genre_ids":     []int{18},
-					"backdrop_path": "/wrong-backdrop.jpg",
-				},
-				{
-					"id":            202,
-					"title":         "正确的同名电影",
-					"poster_path":   "/right.jpg",
-					"release_date":  "2021-08-01",
-					"vote_average":  8.2,
-					"genre_ids":     []int{28},
-					"backdrop_path": "/right-backdrop.jpg",
-				},
-			},
-		})
-	}))
-	defer upstream.Close()
-
-	db, err := gorm.Open(sqlite.Open("file::memory:?cache=shared"), &gorm.Config{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := db.AutoMigrate(&model.Library{}, &model.Series{}, &model.Media{}); err != nil {
-		t.Fatal(err)
-	}
-	repos := repository.New(db)
-	cfg := &config.Config{}
-	cfg.Secrets.TMDbAPIKey = "test-key"
-	cfg.Secrets.TMDbAPIProxy = upstream.URL
-	log := zap.NewNop()
-	scraper := NewScraperService(cfg, log, repos, NewTMDbProvider(cfg, log, nil), nil, nil, nil, NewHub(log))
-
-	lib := model.Library{Name: "电影", Path: "/media/movie", Type: "movie", Enabled: true}
-	if err := repos.DB.Create(&lib).Error; err != nil {
-		t.Fatal(err)
-	}
-	media := model.Media{LibraryID: lib.ID, Title: "同名电影", Path: "/media/movie/同名电影.mkv"}
-	if err := repos.DB.Create(&media).Error; err != nil {
-		t.Fatal(err)
-	}
-
-	results, err := scraper.ManualSearch(t.Context(), &media, "同名电影", "tmdb", "movie")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(results) != 2 || results[0].TMDbID != 101 || results[1].TMDbID != 202 {
-		t.Fatalf("manual TMDb candidates = %#v", results)
-	}
-}
-
-func TestManualSearchIncludesAdultProvider(t *testing.T) {
-	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		switch r.URL.Path {
-		case "/search":
-			w.Header().Set("Content-Type", "text/html; charset=utf-8")
-			_, _ = w.Write([]byte(`<a class="box" href="/v/ssis001"><strong>SSIS-001 手动候选</strong></a>`))
-		case "/v/ssis001":
-			w.Header().Set("Content-Type", "text/html; charset=utf-8")
-			_, _ = w.Write([]byte(`<h2 class="title"><strong>SSIS-001 手动成人标题</strong></h2><img class="video-cover" src="/cover.jpg">`))
-		default:
-			http.NotFound(w, r)
-		}
-	}))
-	defer upstream.Close()
-
-	db, err := gorm.Open(sqlite.Open("file::memory:?cache=shared"), &gorm.Config{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := db.AutoMigrate(&model.Library{}, &model.Series{}, &model.Media{}, &model.APIConfig{}); err != nil {
-		t.Fatal(err)
-	}
-	repos := repository.New(db)
-	apiConfig := NewAPIConfigService(zap.NewNop(), repos, NewCryptoService("", zap.NewNop()))
-	baseURL := upstream.URL
-	if _, err := apiConfig.Update(t.Context(), "adult", APIConfigPatch{BaseURL: &baseURL}); err != nil {
-		t.Fatal(err)
-	}
-	log := zap.NewNop()
-	scraper := NewScraperService(&config.Config{}, log, repos, nil, nil, nil, nil, NewHub(log), NewAdultProvider(log, apiConfig))
-
-	lib := model.Library{Name: "成人", Path: "/media/adult", Type: "movie", Enabled: true}
-	if err := repos.DB.Create(&lib).Error; err != nil {
-		t.Fatal(err)
-	}
-	media := model.Media{LibraryID: lib.ID, Title: "SSIS-001", OriginalName: "SSIS-001", Path: "/media/adult/SSIS-001.mkv"}
-	if err := repos.DB.Create(&media).Error; err != nil {
-		t.Fatal(err)
-	}
-
-	results, err := scraper.ManualSearch(t.Context(), &media, "SSIS-001", "adult", "adult")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(results) != 1 || results[0].Source != "adult" || results[0].MediaType != "adult" || !results[0].NSFW || results[0].OriginalName != "SSIS-001" {
-		t.Fatalf("manual adult candidates = %#v", results)
-	}
-}
-
-func TestApplyManualMatchSavesSelectedCloudMatchWhenDetailsSlow(t *testing.T) {
-	oldTimeout := tmdbDetailsTimeout
-	tmdbDetailsTimeout = 20 * time.Millisecond
-	defer func() { tmdbDetailsTimeout = oldTimeout }()
-
-	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/movie/77" {
-			http.NotFound(w, r)
-			return
-		}
-		select {
-		case <-r.Context().Done():
-			return
-		case <-time.After(time.Second):
-			_ = json.NewEncoder(w).Encode(map[string]any{
-				"id":    77,
-				"title": "Slow Details",
-			})
-		}
-	}))
-	defer upstream.Close()
-
-	db, err := gorm.Open(sqlite.Open("file::memory:?cache=shared"), &gorm.Config{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := db.AutoMigrate(&model.Library{}, &model.Series{}, &model.Media{}); err != nil {
-		t.Fatal(err)
-	}
-	repos := repository.New(db)
-	cfg := &config.Config{}
-	cfg.Secrets.TMDbAPIKey = "test-key"
-	cfg.Secrets.TMDbAPIProxy = upstream.URL
-	log := zap.NewNop()
-	scraper := NewScraperService(cfg, log, repos, NewTMDbProvider(cfg, log, nil), nil, nil, nil, NewHub(log))
-
-	lib := model.Library{Name: "OpenList · Movies", Path: "cloud://openlist/Movies", Type: "movie", Enabled: true}
-	if err := repos.DB.Create(&lib).Error; err != nil {
-		t.Fatal(err)
-	}
-	media := model.Media{
-		LibraryID:    lib.ID,
-		Title:        "bad cloud title",
-		Path:         "cloud://openlist/Movies/Bad.Title.2026.mkv",
-		ScrapeStatus: "pending",
-	}
-	if err := repos.DB.Create(&media).Error; err != nil {
-		t.Fatal(err)
-	}
-
-	start := time.Now()
-	if _, err := scraper.ApplyManualMatch(t.Context(), media.ID, ManualScrapeRequest{
-		Source:    "manual",
-		MediaType: "movie",
-		Title:     "Correct Cloud Movie",
-		TMDbID:    77,
-		Year:      2026,
-	}); err != nil {
-		t.Fatal(err)
-	}
-	if elapsed := time.Since(start); elapsed > 500*time.Millisecond {
-		t.Fatalf("manual apply waited for optional details: %s", elapsed)
-	}
-
-	var got model.Media
-	if err := repos.DB.First(&got, "id = ?", media.ID).Error; err != nil {
-		t.Fatal(err)
-	}
-	if got.Title != "Correct Cloud Movie" || got.ScrapeStatus != "matched" || got.TMDbID != 77 {
-		t.Fatalf("manual cloud match was not saved: title=%q status=%q tmdb=%d", got.Title, got.ScrapeStatus, got.TMDbID)
-	}
-}
-
 func TestEnrichOneUsesExistingTMDbIDForCloudMedia(t *testing.T) {
 	scraper, repos, closeServer := newTestScraper(t)
 	defer closeServer()
@@ -373,56 +51,6 @@ func TestEnrichOneUsesExistingTMDbIDForCloudMedia(t *testing.T) {
 	}
 }
 
-func TestScrapeQueryCandidatesPreferSeriesFolderAndCJKTitle(t *testing.T) {
-	lib := &model.Library{
-		Path: `F:\downloads\国产剧`,
-		Type: "movie",
-	}
-	media := &model.Media{
-		Title:      "亏成首富从游戏开始 the ri est in game",
-		Path:       `F:\downloads\国产剧\亏成首富从游戏开始 The Richest in Game\Season 01\亏成首富从游戏开始 The Richest in Game - S01E11 - 4K.mp4`,
-		SeasonNum:  1,
-		EpisodeNum: 11,
-	}
-
-	got := scrapeQueryCandidates(media, lib)
-	if len(got) == 0 {
-		t.Fatal("scrapeQueryCandidates returned no candidates")
-	}
-	if got[0] != "亏成首富从游戏开始" {
-		t.Fatalf("first query candidate = %q, want Chinese series title", got[0])
-	}
-	for _, candidate := range got {
-		if strings.Contains(candidate, "ri est") {
-			t.Fatalf("query candidate kept substring-stripped title: %#v", got)
-		}
-	}
-}
-
-func TestScrapeQueryCandidatesSkipCategoryFolderAsSeriesTitle(t *testing.T) {
-	lib := &model.Library{
-		Path: `/downloads`,
-		Type: "tv",
-	}
-	media := &model.Media{
-		Title:      "Ashes To Crown",
-		Path:       `/downloads/国产剧/Ashes.to.Crown.S01E06.1080p.WEB-DL.mkv`,
-		SeasonNum:  1,
-		EpisodeNum: 6,
-	}
-
-	got := scrapeQueryCandidates(media, lib)
-	if len(got) == 0 {
-		t.Fatal("scrapeQueryCandidates returned no candidates")
-	}
-	if got[0] == "国产剧" {
-		t.Fatalf("first query candidate = %q, category folders must not be used as title candidates: %#v", got[0], got)
-	}
-	if !strings.EqualFold(got[0], "Ashes To Crown") {
-		t.Fatalf("first query candidate = %q, want release title; all candidates=%#v", got[0], got)
-	}
-}
-
 func TestEnrichOneWritesTMDbIDColumn(t *testing.T) {
 	scraper, repos, closeServer := newTestScraper(t)
 	defer closeServer()
@@ -460,6 +88,39 @@ func TestEnrichOneWritesTMDbIDColumn(t *testing.T) {
 	}
 }
 
+func TestEnrichOneTreatsEpisodicMediaInMovieLibraryAsTV(t *testing.T) {
+	scraper, repos, closeServer := newTestScraper(t)
+	defer closeServer()
+
+	lib := model.Library{Name: "混合库", Path: t.TempDir(), Type: "movie", Enabled: true}
+	if err := repos.DB.Create(&lib).Error; err != nil {
+		t.Fatal(err)
+	}
+	media := model.Media{
+		LibraryID:    lib.ID,
+		Title:        "间谍过家家 S02E01",
+		Path:         filepath.Join(lib.Path, "间谍过家家", "Season 02", "间谍过家家 - S02E01.mkv"),
+		SeasonNum:    2,
+		EpisodeNum:   1,
+		ScrapeStatus: "pending",
+	}
+	if err := repos.DB.Create(&media).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	if err := scraper.EnrichOne(t.Context(), &media); err != nil {
+		t.Fatal(err)
+	}
+
+	var got model.Media
+	if err := repos.DB.First(&got, "id = ?", media.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if got.ScrapeStatus != "matched" || got.TMDbID != 12345 {
+		t.Fatalf("episodic media in movie library should use tv scrape: status=%q tmdb=%d", got.ScrapeStatus, got.TMDbID)
+	}
+}
+
 func TestEnrichOneWritesTMDbEpisodeMetadata(t *testing.T) {
 	scraper, repos, closeServer := newTestScraper(t)
 	defer closeServer()
@@ -469,12 +130,16 @@ func TestEnrichOneWritesTMDbEpisodeMetadata(t *testing.T) {
 		t.Fatal(err)
 	}
 	mediaPath := filepath.Join(lib.Path, "间谍过家家 - S02E01.mkv")
+	existingPoster := "https://image.tmdb.org/t/p/w500/existing-poster.jpg"
+	existingBackdrop := "https://image.tmdb.org/t/p/w1280/existing-backdrop.jpg"
 	media := model.Media{
 		LibraryID:    lib.ID,
 		Title:        "间谍过家家",
 		Path:         mediaPath,
 		SeasonNum:    2,
 		EpisodeNum:   1,
+		PosterURL:    existingPoster,
+		BackdropURL:  existingBackdrop,
 		ScrapeStatus: "pending",
 	}
 	if err := repos.DB.Create(&media).Error; err != nil {
@@ -499,6 +164,9 @@ func TestEnrichOneWritesTMDbEpisodeMetadata(t *testing.T) {
 	if got.Rating < 9.09 || got.Rating > 9.11 {
 		t.Fatalf("episode rating = %v, want 9.1", got.Rating)
 	}
+	if got.EpisodeTitle != "任务代号: 猫" {
+		t.Fatalf("episode_title should store per-episode name, got %q", got.EpisodeTitle)
+	}
 	// original_name 必须保持「整剧原名」,绝不能被单集名(任务代号: 猫)覆盖,
 	// 否则同剧每集 original_name 不同会导致合集被拆成多集无法合并。
 	if got.OriginalName != "SPY×FAMILY" {
@@ -506,6 +174,108 @@ func TestEnrichOneWritesTMDbEpisodeMetadata(t *testing.T) {
 	}
 }
 
+func TestEnrichOneSkipsTMDbEpisodeStillWhenDisabled(t *testing.T) {
+	scraper, repos, closeServer := newTestScraper(t)
+	defer closeServer()
+
+	lib := model.Library{Name: "番剧", Path: t.TempDir(), Type: "tv", Enabled: true}
+	if err := repos.DB.Create(&lib).Error; err != nil {
+		t.Fatal(err)
+	}
+	mediaPath := filepath.Join(lib.Path, "间谍过家家 - S02E01.mkv")
+	existingPoster := "https://image.tmdb.org/t/p/w500/existing-poster.jpg"
+	existingBackdrop := "https://image.tmdb.org/t/p/w1280/existing-backdrop.jpg"
+	media := model.Media{
+		LibraryID:    lib.ID,
+		Title:        "间谍过家家",
+		Path:         mediaPath,
+		SeasonNum:    2,
+		EpisodeNum:   1,
+		PosterURL:    existingPoster,
+		BackdropURL:  existingBackdrop,
+		ScrapeStatus: "pending",
+	}
+	if err := repos.DB.Create(&media).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	episodeArtwork := false
+	if err := scraper.EnrichOneWithOptions(t.Context(), &media, ScrapeOptions{EpisodeArtwork: &episodeArtwork}); err != nil {
+		t.Fatal(err)
+	}
+
+	var got model.Media
+	if err := repos.DB.First(&got, "id = ?", media.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if got.Overview != "单集剧情" || got.DurationSec != 24*60 {
+		t.Fatalf("episode metadata should still be saved: overview=%q duration=%d", got.Overview, got.DurationSec)
+	}
+	if got.Rating < 9.09 || got.Rating > 9.11 {
+		t.Fatalf("episode rating = %v, want 9.1", got.Rating)
+	}
+	if strings.HasSuffix(got.BackdropURL, "/images/w500/still.jpg") {
+		t.Fatalf("episode still should not be saved when disabled: backdrop=%q", got.BackdropURL)
+	}
+	if !strings.HasSuffix(got.PosterURL, "/images/w500/poster.jpg") {
+		t.Fatalf("series poster should still be saved when episode artwork is disabled: got %q", got.PosterURL)
+	}
+	if !strings.HasSuffix(got.BackdropURL, "/images/w1280/backdrop.jpg") {
+		t.Fatalf("series backdrop should still be saved when episode artwork is disabled: got %q", got.BackdropURL)
+	}
+	if got.PosterURL == existingPoster || got.BackdropURL == existingBackdrop {
+		t.Fatalf("main artwork should be refreshed while episode still is skipped: poster=%q backdrop=%q", got.PosterURL, got.BackdropURL)
+	}
+}
+
+func TestApplyManualMatchSkipsTMDbEpisodeStillWhenDisabled(t *testing.T) {
+	scraper, repos, closeServer := newTestScraper(t)
+	defer closeServer()
+
+	lib := model.Library{Name: "番剧", Path: t.TempDir(), Type: "tv", Enabled: true}
+	if err := repos.DB.Create(&lib).Error; err != nil {
+		t.Fatal(err)
+	}
+	media := model.Media{
+		LibraryID:    lib.ID,
+		Title:        "待匹配",
+		Path:         filepath.Join(lib.Path, "间谍过家家 - S02E01.mkv"),
+		SeasonNum:    2,
+		EpisodeNum:   1,
+		ScrapeStatus: "pending",
+	}
+	if err := repos.DB.Create(&media).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	episodeArtwork := false
+	got, err := scraper.ApplyManualMatch(t.Context(), media.ID, ManualScrapeRequest{
+		Source:         "tmdb",
+		MediaType:      "tv",
+		Title:          "间谍过家家",
+		TMDbID:         12345,
+		EpisodeArtwork: &episodeArtwork,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got == nil {
+		t.Fatal("manual match returned nil media")
+	}
+	if got.Overview != "单集剧情" || got.DurationSec != 24*60 {
+		t.Fatalf("episode metadata should still be saved: overview=%q duration=%d", got.Overview, got.DurationSec)
+	}
+	if strings.HasSuffix(got.BackdropURL, "/images/w500/still.jpg") {
+		t.Fatalf("manual episode still should not be saved when disabled: backdrop=%q", got.BackdropURL)
+	}
+	if !strings.HasSuffix(got.PosterURL, "/images/w500/poster.jpg") {
+		t.Fatalf("series poster should still be saved when manual episode artwork is disabled: got %q", got.PosterURL)
+	}
+	if !strings.HasSuffix(got.BackdropURL, "/images/w1280/backdrop.jpg") {
+		t.Fatalf("series backdrop should still be saved when manual episode artwork is disabled: got %q", got.BackdropURL)
+	}
+}
+
 func TestEnrichOneRejectsWrongYearMatchFromSeriesFolder(t *testing.T) {
 	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
@@ -634,6 +404,9 @@ func TestEnrichOnePrefersLocalMetadataWithoutProvider(t *testing.T) {
 	if got.SeasonNum != 2 || got.EpisodeNum != 12 || got.Overview != "本地剧情" {
 		t.Fatalf("unexpected local episode data: s=%d e=%d overview=%q", got.SeasonNum, got.EpisodeNum, got.Overview)
 	}
+	if got.EpisodeTitle != "企鹅公园" {
+		t.Fatalf("episode_title = %q, want local episode title", got.EpisodeTitle)
+	}
 }
 
 func TestManualEnrichLibraryRetriesNoMatchAndCountsRealMatches(t *testing.T) {
@@ -664,35 +437,129 @@ func TestManualEnrichLibraryRetriesNoMatchAndCountsRealMatches(t *testing.T) {
 	}
 }
 
-func TestScrapeDelayUsesSettings(t *testing.T) {
+func TestManualEnrichLibraryCanRefreshAlreadyMatchedRows(t *testing.T) {
 	scraper, repos, closeServer := newTestScraper(t)
 	defer closeServer()
-	if err := repos.DB.AutoMigrate(&model.Setting{}); err != nil {
+
+	lib := model.Library{Name: "番剧", Path: t.TempDir(), Type: "tv", Enabled: true}
+	if err := repos.DB.Create(&lib).Error; err != nil {
+		t.Fatal(err)
+	}
+	media := model.Media{
+		LibraryID:    lib.ID,
+		Title:        "间谍过家家",
+		Path:         filepath.Join(lib.Path, "间谍过家家 - S02E02.mkv"),
+		SeasonNum:    2,
+		EpisodeNum:   2,
+		ScrapeStatus: "matched",
+	}
+	if err := repos.DB.Create(&media).Error; err != nil {
 		t.Fatal(err)
 	}
 
-	if got := scraper.scrapeDelay(t.Context()); got < 250*time.Millisecond || got > 500*time.Millisecond {
-		t.Fatalf("default scrapeDelay = %s, want 250-500ms", got)
+	defaultResult, err := scraper.EnrichLibraryDetailedWithOptions(t.Context(), lib.ID, ScrapeOptions{RetryNoMatch: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if defaultResult.Processed != 0 || defaultResult.Candidates != 0 {
+		t.Fatalf("default manual scrape result=%+v, want matched rows skipped without IncludeMatched", defaultResult)
 	}
 
-	if err := repos.Setting.Set(t.Context(), "scrape.delay_min_ms", "0"); err != nil {
+	refreshResult, err := scraper.EnrichLibraryDetailedWithOptions(t.Context(), lib.ID, ScrapeOptions{
+		RetryNoMatch:   true,
+		IncludeMatched: true,
+	})
+	if err != nil {
 		t.Fatal(err)
 	}
-	if err := repos.Setting.Set(t.Context(), "scrape.delay_max_ms", "0"); err != nil {
+	if refreshResult.Processed != 1 || refreshResult.Matched != 1 || refreshResult.Candidates != 1 {
+		t.Fatalf("refresh result=%+v, want already matched row reprocessed", refreshResult)
+	}
+}
+
+func TestScrapeCandidateRowsPrioritizeLibraryArtworkBeforeEpisodes(t *testing.T) {
+	scraper, repos, closeServer := newTestScraper(t)
+	defer closeServer()
+
+	lib := model.Library{Name: "番剧", Path: t.TempDir(), Type: "tv", Enabled: true}
+	if err := repos.DB.Create(&lib).Error; err != nil {
 		t.Fatal(err)
 	}
-	if got := scraper.scrapeDelay(t.Context()); got != 0 {
-		t.Fatalf("disabled scrapeDelay = %s, want 0", got)
+	rows := []model.Media{
+		{
+			Base:         model.Base{ID: "001-episode"},
+			LibraryID:    lib.ID,
+			Title:        "间谍过家家 第 1 集",
+			Path:         filepath.Join(lib.Path, "间谍过家家 - S02E01.mkv"),
+			SeasonNum:    2,
+			EpisodeNum:   1,
+			ScrapeStatus: "pending",
+		},
+		{
+			Base:         model.Base{ID: "999-series"},
+			LibraryID:    lib.ID,
+			Title:        "间谍过家家",
+			Path:         filepath.Join(lib.Path, "间谍过家家.mkv"),
+			ScrapeStatus: "pending",
+		},
+	}
+	if err := repos.DB.Create(&rows).Error; err != nil {
+		t.Fatal(err)
 	}
 
-	if err := repos.Setting.Set(t.Context(), "scrape.delay_min_ms", "800"); err != nil {
+	got, err := scraper.scrapeCandidateRows(t.Context(), lib.ID, ScrapeOptions{})
+	if err != nil {
 		t.Fatal(err)
 	}
-	if err := repos.Setting.Set(t.Context(), "scrape.delay_max_ms", "200"); err != nil {
+	if len(got) != 2 {
+		t.Fatalf("candidate rows = %d, want 2", len(got))
+	}
+	if got[0].ID != "999-series" || got[1].ID != "001-episode" {
+		t.Fatalf("scrape order = [%s, %s], want series-level row before episode row", got[0].ID, got[1].ID)
+	}
+}
+
+func TestEnrichLibraryIncludesMergedCloudLibraryMedia(t *testing.T) {
+	scraper, repos, closeServer := newTestScraper(t)
+	defer closeServer()
+
+	local := model.Library{Name: "番剧", Path: t.TempDir(), Type: "tv", Enabled: true}
+	cloud := model.Library{
+		Name:    "OpenList · 番剧",
+		Path:    BuildCloudLibraryPath("openlist", "/番剧", "/番剧"),
+		Type:    "tv",
+		Enabled: true,
+	}
+	if err := repos.DB.Create(&local).Error; err != nil {
 		t.Fatal(err)
 	}
-	if got := scraper.scrapeDelay(t.Context()); got != 800*time.Millisecond {
-		t.Fatalf("normalized scrapeDelay = %s, want 800ms", got)
+	if err := repos.DB.Create(&cloud).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := repos.DB.Create(&model.Media{
+		LibraryID:    cloud.ID,
+		Title:        "间谍过家家",
+		Path:         "cloud://openlist/番剧/间谍过家家 - S02E02.mkv",
+		SeasonNum:    2,
+		EpisodeNum:   2,
+		ScrapeStatus: "pending",
+	}).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	result, err := scraper.EnrichLibraryDetailed(t.Context(), local.ID, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Matched != 1 || result.Processed != 1 || result.Candidates != 1 || result.Failed != 0 {
+		t.Fatalf("result=%+v, want merged cloud media to be scraped once", result)
+	}
+	var got model.Media
+	if err := repos.DB.First(&got, "library_id = ?", cloud.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if got.ScrapeStatus != "matched" || got.TMDbID != 12345 {
+		t.Fatalf("merged cloud media was not enriched: status=%q tmdb=%d", got.ScrapeStatus, got.TMDbID)
 	}
 }