实现增量扫描

2026-04-11 14:38:23 +08:00
parent 3f82e29c6c
commit 79d47c81e7
10 changed files with 351 additions and 91 deletions
--- a/internal/model/model.go
+++ b/internal/model/model.go
@@ -13,15 +13,17 @@ type Library struct {

 // MediaFile represents a single audio file on disk.
 type MediaFile struct {
-	ID         int       `json:"id"`
-	Path       string    `json:"path"`
-	LibraryID  int       `json:"library_id"`
-	FileSize   int64     `json:"file_size"`
-	Format     string    `json:"format"`
-	BitRate    int       `json:"bit_rate"`
-	SampleRate int       `json:"sample_rate"`
-	CreatedAt  time.Time `json:"created_at"`
-	UpdatedAt  time.Time `json:"updated_at"`
+	ID          int       `json:"id"`
+	Path        string    `json:"path"`
+	LibraryID   int       `json:"library_id"`
+	FileSize    int64     `json:"file_size"`
+	FileMtimeNs int64     `json:"file_mtime_ns"`
+	Format      string    `json:"format"`
+	BitRate     int       `json:"bit_rate"`
+	SampleRate  int       `json:"sample_rate"`
+	LastSeenAt  time.Time `json:"last_seen_at"`
+	CreatedAt   time.Time `json:"created_at"`
+	UpdatedAt   time.Time `json:"updated_at"`
 }

 // Artist represents a music artist.
--- a/internal/repository/library.go
+++ b/internal/repository/library.go
@@ -76,14 +76,34 @@ func (r *LibraryRepository) Delete(id int) error {
 	}
 	defer tx.Rollback()

-	// Delete the library — CASCADE removes media_files and songs automatically
 	_, err = tx.Exec("DELETE FROM libraries WHERE id = ?", id)
 	if err != nil {
 		return err
 	}

-	// Clean up orphan albums (no songs reference them)
-	_, err = tx.Exec(`
+	if err := cleanupOrphansTx(tx); err != nil {
+		return err
+	}
+
+	return tx.Commit()
+}
+
+func (r *LibraryRepository) CleanupOrphans() error {
+	tx, err := r.db.Begin()
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback()
+
+	if err := cleanupOrphansTx(tx); err != nil {
+		return err
+	}
+
+	return tx.Commit()
+}
+
+func cleanupOrphansTx(tx *sql.Tx) error {
+	_, err := tx.Exec(`
 		DELETE FROM albums WHERE id NOT IN (
 			SELECT DISTINCT album_id FROM songs WHERE album_id IS NOT NULL
 		)
@@ -92,7 +112,6 @@ func (r *LibraryRepository) Delete(id int) error {
 		return err
 	}

-	// Clean up orphan artists (no songs and no albums reference them)
 	_, err = tx.Exec(`
 		DELETE FROM artists WHERE id NOT IN (
 			SELECT DISTINCT artist_id FROM songs WHERE artist_id IS NOT NULL
@@ -104,5 +123,5 @@ func (r *LibraryRepository) Delete(id int) error {
 		return err
 	}

-	return tx.Commit()
+	return nil
 }
--- a/internal/repository/media_repo.go
+++ b/internal/repository/media_repo.go
@@ -3,12 +3,16 @@ package repository
 import (
 	"butterfliu/internal/model"
 	"database/sql"
+	"time"
 )

 type ExistingMediaFile struct {
 	Path        string
 	MediaFileID int
 	HasSong     bool
+	FileSize    int64
+	FileMtimeNs int64
+	LastSeenAt  time.Time
 }

 type MediaRepository struct {
@@ -21,8 +25,19 @@ func NewMediaRepository(db *sql.DB) *MediaRepository {

 func (r *MediaRepository) Get(id int) (model.MediaFile, error) {
 	var m model.MediaFile
-	err := r.db.QueryRow("SELECT id, path, library_id FROM media_files WHERE id = ?", id).Scan(
+	err := r.db.QueryRow(`
+		SELECT id, path, library_id,
+		       COALESCE(file_size, 0), COALESCE(file_mtime_ns, 0), COALESCE(format, ''),
+		       COALESCE(bit_rate, 0), COALESCE(sample_rate, 0),
+		       COALESCE(last_seen_at, '1970-01-01T00:00:00Z'),
+		       COALESCE(created_at, '1970-01-01T00:00:00Z'),
+		       COALESCE(updated_at, '1970-01-01T00:00:00Z')
+		FROM media_files WHERE id = ?
+	`, id).Scan(
 		&m.ID, &m.Path, &m.LibraryID,
+		&m.FileSize, &m.FileMtimeNs, &m.Format,
+		&m.BitRate, &m.SampleRate, &m.LastSeenAt,
+		&m.CreatedAt, &m.UpdatedAt,
 	)
 	if err != nil {
 		return model.MediaFile{}, err
@@ -33,8 +48,9 @@ func (r *MediaRepository) Get(id int) (model.MediaFile, error) {
 func (r *MediaRepository) GetByPath(path string) (model.MediaFile, error) {
 	row := r.db.QueryRow(`
 		SELECT id, path, library_id,
-		       COALESCE(file_size, 0), COALESCE(format, ''),
+		       COALESCE(file_size, 0), COALESCE(file_mtime_ns, 0), COALESCE(format, ''),
 		       COALESCE(bit_rate, 0), COALESCE(sample_rate, 0),
+		       COALESCE(last_seen_at, '1970-01-01T00:00:00Z'),
 		       COALESCE(created_at, '1970-01-01T00:00:00Z'),
 		       COALESCE(updated_at, '1970-01-01T00:00:00Z')
 		FROM media_files WHERE path = ?
@@ -42,8 +58,8 @@ func (r *MediaRepository) GetByPath(path string) (model.MediaFile, error) {
 	var mediaFile model.MediaFile
 	if err := row.Scan(
 		&mediaFile.ID, &mediaFile.Path, &mediaFile.LibraryID,
-		&mediaFile.FileSize, &mediaFile.Format,
-		&mediaFile.BitRate, &mediaFile.SampleRate,
+		&mediaFile.FileSize, &mediaFile.FileMtimeNs, &mediaFile.Format,
+		&mediaFile.BitRate, &mediaFile.SampleRate, &mediaFile.LastSeenAt,
 		&mediaFile.CreatedAt, &mediaFile.UpdatedAt,
 	); err != nil {
 		return model.MediaFile{}, err
@@ -51,8 +67,18 @@ func (r *MediaRepository) GetByPath(path string) (model.MediaFile, error) {
 	return mediaFile, nil
 }

-func (r *MediaRepository) Create(path string, libraryID int) (model.MediaFile, error) {
-	result, err := r.db.Exec("INSERT INTO media_files (path, library_id) VALUES (?, ?)", path, libraryID)
+func (r *MediaRepository) Create(mediaFile model.MediaFile) (model.MediaFile, error) {
+	result, err := r.db.Exec(
+		`INSERT INTO media_files (path, library_id, file_size, file_mtime_ns, format, bit_rate, sample_rate, last_seen_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+		mediaFile.Path,
+		mediaFile.LibraryID,
+		mediaFile.FileSize,
+		mediaFile.FileMtimeNs,
+		mediaFile.Format,
+		mediaFile.BitRate,
+		mediaFile.SampleRate,
+		mediaFile.LastSeenAt,
+	)
 	if err != nil {
 		return model.MediaFile{}, err
 	}
@@ -62,16 +88,15 @@ func (r *MediaRepository) Create(path string, libraryID int) (model.MediaFile, e
 		return model.MediaFile{}, err
 	}

-	return model.MediaFile{
-		ID:        int(id),
-		Path:      path,
-		LibraryID: libraryID,
-	}, nil
+	mediaFile.ID = int(id)
+	return mediaFile, nil
 }

 func (r *MediaRepository) ListExistingByLibrary(libraryID int) ([]ExistingMediaFile, error) {
 	rows, err := r.db.Query(`
-		SELECT mf.path, mf.id, CASE WHEN s.id IS NULL THEN 0 ELSE 1 END AS has_song
+		SELECT mf.path, mf.id, CASE WHEN s.id IS NULL THEN 0 ELSE 1 END AS has_song,
+		       COALESCE(mf.file_size, 0), COALESCE(mf.file_mtime_ns, 0),
+		       COALESCE(mf.last_seen_at, '1970-01-01T00:00:00Z')
 		FROM media_files mf
 		LEFT JOIN songs s ON s.media_file_id = mf.id
 		WHERE mf.library_id = ?
@@ -85,7 +110,7 @@ func (r *MediaRepository) ListExistingByLibrary(libraryID int) ([]ExistingMediaF
 	for rows.Next() {
 		var item ExistingMediaFile
 		var hasSong int
-		if err := rows.Scan(&item.Path, &item.MediaFileID, &hasSong); err != nil {
+		if err := rows.Scan(&item.Path, &item.MediaFileID, &hasSong, &item.FileSize, &item.FileMtimeNs, &item.LastSeenAt); err != nil {
 			return nil, err
 		}
 		item.HasSong = hasSong == 1
@@ -94,6 +119,34 @@ func (r *MediaRepository) ListExistingByLibrary(libraryID int) ([]ExistingMediaF
 	return existing, nil
 }

+func (r *MediaRepository) UpdateMetadata(mediaFile model.MediaFile) error {
+	_, err := r.db.Exec(
+		`UPDATE media_files SET file_size = ?, file_mtime_ns = ?, format = ?, bit_rate = ?, sample_rate = ?, last_seen_at = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?`,
+		mediaFile.FileSize,
+		mediaFile.FileMtimeNs,
+		mediaFile.Format,
+		mediaFile.BitRate,
+		mediaFile.SampleRate,
+		mediaFile.LastSeenAt,
+		mediaFile.ID,
+	)
+	return err
+}
+
+func (r *MediaRepository) TouchLastSeen(mediaFileID int, seenAt time.Time) error {
+	_, err := r.db.Exec(
+		`UPDATE media_files SET last_seen_at = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?`,
+		seenAt,
+		mediaFileID,
+	)
+	return err
+}
+
+func (r *MediaRepository) Delete(id int) error {
+	_, err := r.db.Exec("DELETE FROM media_files WHERE id = ?", id)
+	return err
+}
+
 func (r *MediaRepository) GetSongsByLibraryWithDetails(libraryID int) ([]model.SongDetail, error) {
 	rows, err := r.db.Query(`
 		SELECT s.id, s.title, a.name as artist_name, al.title as album_title, s.duration, mf.path
--- a/internal/repository/song_repo.go
+++ b/internal/repository/song_repo.go
@@ -130,3 +130,11 @@ func (r *SongRepository) Create(title string, artistID, albumID, duration, media
 		MediaFileID: mediaFileID,
 	}, nil
 }
+
+func (r *SongRepository) UpdateByMediaFileID(title string, artistID, albumID, duration, mediaFileID int) error {
+	_, err := r.db.Exec(
+		"UPDATE songs SET title = ?, artist_id = ?, album_id = ?, duration = ? WHERE media_file_id = ?",
+		title, artistID, albumID, duration, mediaFileID,
+	)
+	return err
+}
--- a/internal/scanner/scanner.go
+++ b/internal/scanner/scanner.go
@@ -11,34 +11,51 @@ import (
 	"strings"
 )

+type DiscoveredAudioFile struct {
+	Path        string
+	FileSize    int64
+	FileMtimeNs int64
+}
+
 type ScannedSong struct {
-	Title    string
-	Artist   string
-	Album    string
-	Duration int
-	Path     string
+	Title      string
+	Artist     string
+	Album      string
+	Duration   int
+	Path       string
+	Format     string
+	BitRate    int
+	SampleRate int
 }

 // ffprobeFormat holds the JSON output from ffprobe format section
 type ffprobeFormat struct {
-	Tags     map[string]string `json:"tags"`
-	Duration string            `json:"duration"`
+	Tags       map[string]string `json:"tags"`
+	Duration   string            `json:"duration"`
+	BitRate    string            `json:"bit_rate"`
+	FormatName string            `json:"format_name"`
+}
+
+type ffprobeStream struct {
+	CodecType  string `json:"codec_type"`
+	SampleRate string `json:"sample_rate"`
 }

 // ffprobeOutput holds the full ffprobe JSON output
 type ffprobeOutput struct {
-	Format ffprobeFormat `json:"format"`
+	Format  ffprobeFormat  `json:"format"`
+	Streams []ffprobeStream `json:"streams"`
 }

 func ScanDirectory(dirPath string) ([]ScannedSong, error) {
-	paths, err := ListAudioFiles(dirPath)
+	files, err := ListAudioFiles(dirPath)
 	if err != nil {
 		return nil, err
 	}

-	songs := make([]ScannedSong, 0, len(paths))
-	for _, path := range paths {
-		song, err := ProbeAudioFile(path)
+	songs := make([]ScannedSong, 0, len(files))
+	for _, file := range files {
+		song, err := ProbeAudioFile(file.Path)
 		if err != nil {
 			continue
 		}
@@ -48,8 +65,8 @@ func ScanDirectory(dirPath string) ([]ScannedSong, error) {
 	return songs, nil
 }

-func ListAudioFiles(dirPath string) ([]string, error) {
-	paths := []string{}
+func ListAudioFiles(dirPath string) ([]DiscoveredAudioFile, error) {
+	files := []DiscoveredAudioFile{}

 	err := filepath.Walk(dirPath, func(path string, info os.FileInfo, err error) error {
 		if err != nil {
@@ -64,11 +81,15 @@ func ListAudioFiles(dirPath string) ([]string, error) {
 			return nil
 		}

-		paths = append(paths, path)
+		files = append(files, DiscoveredAudioFile{
+			Path:        path,
+			FileSize:    info.Size(),
+			FileMtimeNs: info.ModTime().UnixNano(),
+		})
 		return nil
 	})

-	return paths, err
+	return files, err
 }

 func ProbeAudioFile(filePath string) (ScannedSong, error) {
@@ -80,7 +101,7 @@ func ProbeAudioFile(filePath string) (ScannedSong, error) {
 }

 func processAudioFile(filePath string) (ScannedSong, error) {
-	cmd := exec.Command("ffprobe", "-v", "quiet", "-print_format", "json", "-show_format", filePath)
+	cmd := exec.Command("ffprobe", "-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", filePath)
 	output, err := cmd.Output()
 	if err != nil {
 		return ScannedSong{}, fmt.Errorf("ffprobe failed for %s: %v", filePath, err)
@@ -118,12 +139,38 @@ func processAudioFile(filePath string) (ScannedSong, error) {
 		}
 	}

+	bitRate := 0
+	if probeOutput.Format.BitRate != "" {
+		if value, err := strconv.Atoi(probeOutput.Format.BitRate); err == nil {
+			bitRate = value
+		}
+	}
+
+	sampleRate := 0
+	for _, stream := range probeOutput.Streams {
+		if stream.CodecType != "audio" || stream.SampleRate == "" {
+			continue
+		}
+		if value, err := strconv.Atoi(stream.SampleRate); err == nil {
+			sampleRate = value
+			break
+		}
+	}
+
+	format := probeOutput.Format.FormatName
+	if format == "" {
+		format = strings.TrimPrefix(strings.ToLower(filepath.Ext(filePath)), ".")
+	}
+
 	return ScannedSong{
-		Title:    title,
-		Artist:   artist,
-		Album:    album,
-		Duration: duration,
-		Path:     filePath,
+		Title:      title,
+		Artist:     artist,
+		Album:      album,
+		Duration:   duration,
+		Path:       filePath,
+		Format:     format,
+		BitRate:    bitRate,
+		SampleRate: sampleRate,
 	}, nil
 }

--- a/internal/service/library.go
+++ b/internal/service/library.go
@@ -9,6 +9,7 @@ import (
 	"log"
 	"path/filepath"
 	"strings"
+	"time"
 )

 // ScanReport holds the result of a library scan.
@@ -16,6 +17,8 @@ type ScanReport struct {
 	TotalFiles  int      `json:"total_files"`
 	Processed   int      `json:"processed"`
 	Added       int      `json:"added"`
+	Updated     int      `json:"updated"`
+	Deleted     int      `json:"deleted"`
 	Skipped     int      `json:"skipped"`
 	FailedFiles []string `json:"failed_files"`
 }
@@ -175,7 +178,7 @@ func (s *LibraryService) Scan(id int, onProgress ScanProgressFunc) (*ScanReport,
 		return nil, fmt.Errorf("library %d not found: %w", id, err)
 	}

-	paths, err := scanner.ListAudioFiles(lib.Path)
+	files, err := scanner.ListAudioFiles(lib.Path)
 	if err != nil {
 		return nil, fmt.Errorf("scan directory %s: %w", lib.Path, err)
 	}
@@ -190,29 +193,43 @@ func (s *LibraryService) Scan(id int, onProgress ScanProgressFunc) (*ScanReport,
 		existingByPath[existing.Path] = existing
 	}

-	report := &ScanReport{TotalFiles: len(paths)}
+	seenAt := time.Now()
+	seenPaths := make(map[string]struct{}, len(files))
+	report := &ScanReport{TotalFiles: len(files)}
 	notifyProgress(report, onProgress)

-	for _, path := range paths {
-		existing, found := existingByPath[path]
-		if found && existing.HasSong {
-			report.Skipped++
+	for _, file := range files {
+		seenPaths[file.Path] = struct{}{}
+		existing, found := existingByPath[file.Path]
+
+		if found && existing.HasSong && existing.FileSize == file.FileSize && existing.FileMtimeNs == file.FileMtimeNs {
+			if err := s.mediaRepo.TouchLastSeen(existing.MediaFileID, seenAt); err != nil {
+				log.Printf("Failed to refresh last_seen_at for %s: %v", filepath.Base(file.Path), err)
+				report.FailedFiles = append(report.FailedFiles, file.Path)
+			} else {
+				report.Skipped++
+			}
 			report.Processed++
 			notifyProgress(report, onProgress)
 			continue
 		}

-		song, err := scanner.ProbeAudioFile(path)
+		song, err := scanner.ProbeAudioFile(file.Path)
 		if err != nil {
-			log.Printf("Failed to probe %s: %v", filepath.Base(path), err)
-			report.FailedFiles = append(report.FailedFiles, path)
+			log.Printf("Failed to probe %s: %v", filepath.Base(file.Path), err)
+			if found {
+				if touchErr := s.mediaRepo.TouchLastSeen(existing.MediaFileID, seenAt); touchErr != nil {
+					log.Printf("Failed to refresh last_seen_at for %s after probe failure: %v", filepath.Base(file.Path), touchErr)
+				}
+			}
+			report.FailedFiles = append(report.FailedFiles, file.Path)
 			report.Processed++
 			notifyProgress(report, onProgress)
 			continue
 		}

-		if err := s.addScannedSong(song, lib.ID, report, found, existing.MediaFileID); err != nil {
-			log.Printf("Failed to add %s: %v", filepath.Base(song.Path), err)
+		if err := s.upsertScannedSong(song, file, lib.ID, report, seenAt, found, existing); err != nil {
+			log.Printf("Failed to upsert %s: %v", filepath.Base(song.Path), err)
 			report.FailedFiles = append(report.FailedFiles, song.Path)
 		}

@@ -220,6 +237,13 @@ func (s *LibraryService) Scan(id int, onProgress ScanProgressFunc) (*ScanReport,
 		notifyProgress(report, onProgress)
 	}

+	deleted, err := s.deleteMissingMediaFiles(existingFiles, seenPaths)
+	if err != nil {
+		return nil, fmt.Errorf("delete missing media files: %w", err)
+	}
+	report.Deleted = deleted
+	notifyProgress(report, onProgress)
+
 	log.Printf("Scan complete for library %d: %+v", id, report)
 	return report, nil
 }
@@ -233,30 +257,15 @@ func notifyProgress(report *ScanReport, onProgress ScanProgressFunc) {
 		TotalFiles: report.TotalFiles,
 		Processed:  report.Processed,
 		Added:      report.Added,
+		Updated:    report.Updated,
+		Deleted:    report.Deleted,
 		Skipped:    report.Skipped,
 	}
 	copyReport.FailedFiles = append([]string(nil), report.FailedFiles...)
 	onProgress(copyReport)
 }

-// addScannedSong upserts a scanned song and its related artist, album, and media file.
-func (s *LibraryService) addScannedSong(song scanner.ScannedSong, libraryID int, report *ScanReport, hasExistingMedia bool, mediaFileID int) error {
-	mediaFile := model.MediaFile{ID: mediaFileID, Path: song.Path, LibraryID: libraryID}
-	if !hasExistingMedia {
-		var err error
-		mediaFile, err = s.getOrCreateMediaFile(song.Path, libraryID)
-		if err != nil {
-			return fmt.Errorf("media file: %w", err)
-		}
-	}
-
-	if hasSong, err := s.songRepo.HasByMediaFileID(mediaFile.ID); err != nil {
-		return fmt.Errorf("song lookup: %w", err)
-	} else if hasSong {
-		report.Skipped++
-		return nil
-	}
-
+func (s *LibraryService) upsertScannedSong(song scanner.ScannedSong, file scanner.DiscoveredAudioFile, libraryID int, report *ScanReport, seenAt time.Time, hasExistingMedia bool, existing repository.ExistingMediaFile) error {
 	artist, err := s.getOrCreateArtist(song.Artist)
 	if err != nil {
 		return fmt.Errorf("artist: %w", err)
@@ -267,20 +276,67 @@ func (s *LibraryService) addScannedSong(song scanner.ScannedSong, libraryID int,
 		return fmt.Errorf("album: %w", err)
 	}

+	mediaFile := model.MediaFile{
+		ID:          existing.MediaFileID,
+		Path:        song.Path,
+		LibraryID:   libraryID,
+		FileSize:    file.FileSize,
+		FileMtimeNs: file.FileMtimeNs,
+		Format:      song.Format,
+		BitRate:     song.BitRate,
+		SampleRate:  song.SampleRate,
+		LastSeenAt:  seenAt,
+	}
+
+	if !hasExistingMedia {
+		mediaFile, err = s.mediaRepo.Create(mediaFile)
+		if err != nil {
+			return fmt.Errorf("media file: %w", err)
+		}
+	} else if err := s.mediaRepo.UpdateMetadata(mediaFile); err != nil {
+		return fmt.Errorf("media file: %w", err)
+	}
+
+	if hasExistingMedia && existing.HasSong {
+		if err := s.songRepo.UpdateByMediaFileID(song.Title, artist.ID, album.ID, song.Duration, mediaFile.ID); err != nil {
+			return fmt.Errorf("song: %w", err)
+		}
+		report.Updated++
+		return nil
+	}
+
 	if _, err := s.songRepo.Create(song.Title, artist.ID, album.ID, song.Duration, mediaFile.ID); err != nil {
 		return fmt.Errorf("song: %w", err)
 	}

-	report.Added++
+	if hasExistingMedia {
+		report.Updated++
+	} else {
+		report.Added++
+	}
 	return nil
 }

-func (s *LibraryService) getOrCreateMediaFile(path string, libraryID int) (model.MediaFile, error) {
-	mf, err := s.mediaRepo.GetByPath(path)
-	if err == nil {
-		return mf, nil
+func (s *LibraryService) deleteMissingMediaFiles(existingFiles []repository.ExistingMediaFile, seenPaths map[string]struct{}) (int, error) {
+	deleted := 0
+	for _, existing := range existingFiles {
+		if _, ok := seenPaths[existing.Path]; ok {
+			continue
+		}
+		if err := s.mediaRepo.Delete(existing.MediaFileID); err != nil {
+			return deleted, err
+		}
+		deleted++
 	}
-	return s.mediaRepo.Create(path, libraryID)
+
+	if deleted == 0 {
+		return 0, nil
+	}
+
+	if err := s.libRepo.CleanupOrphans(); err != nil {
+		return deleted, err
+	}
+	return deleted, nil
 }

 func (s *LibraryService) getOrCreateArtist(name string) (model.Artist, error) {
--- a/migrations/004_add_incremental_scan_fields.go
+++ b/migrations/004_add_incremental_scan_fields.go
@@ -0,0 +1,73 @@
+package migrations
+
+import (
+	"database/sql"
+)
+
+func init() {
+	RegisterMigration(
+		4,
+		"Add incremental scan fields",
+		migrateAddIncrementalScanFieldsUp,
+		migrateAddIncrementalScanFieldsDown,
+	)
+}
+
+func migrateAddIncrementalScanFieldsUp(tx *sql.Tx) error {
+	_, err := tx.Exec(`
+		ALTER TABLE media_files ADD COLUMN file_mtime_ns INTEGER DEFAULT 0
+	`)
+	if err != nil {
+		return err
+	}
+
+	_, err = tx.Exec(`
+		ALTER TABLE media_files ADD COLUMN last_seen_at TIMESTAMP
+	`)
+	if err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func migrateAddIncrementalScanFieldsDown(tx *sql.Tx) error {
+	_, err := tx.Exec(`
+		CREATE TABLE media_files_old (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			path TEXT NOT NULL,
+			library_id INTEGER NOT NULL,
+			file_size INTEGER DEFAULT 0,
+			format TEXT DEFAULT '',
+			bit_rate INTEGER DEFAULT 0,
+			sample_rate INTEGER DEFAULT 0,
+			created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+			updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+			FOREIGN KEY (library_id) REFERENCES libraries(id) ON DELETE CASCADE
+		)
+	`)
+	if err != nil {
+		return err
+	}
+
+	_, err = tx.Exec(`
+		INSERT INTO media_files_old (id, path, library_id, file_size, format, bit_rate, sample_rate, created_at, updated_at)
+		SELECT id, path, library_id, file_size, format, bit_rate, sample_rate, created_at, updated_at
+		FROM media_files
+	`)
+	if err != nil {
+		return err
+	}
+
+	_, err = tx.Exec("DROP TABLE media_files")
+	if err != nil {
+		return err
+	}
+
+	_, err = tx.Exec("ALTER TABLE media_files_old RENAME TO media_files")
+	if err != nil {
+		return err
+	}
+
+	return nil
+}
--- a/web/src/components/LibraryCard.vue
+++ b/web/src/components/LibraryCard.vue
@@ -13,7 +13,7 @@
        {{ scanStatus.report.processed }} / {{ scanStatus.report.total_files || 0 }}
      </span>
      <span v-else-if="scanStatus.report" class="scan-status-text">
-        新增 {{ scanStatus.report.added }} · 跳过 {{ scanStatus.report.skipped }} · 失败 {{ scanStatus.report.failed_files?.length || 0 }}
+        新增 {{ scanStatus.report.added || 0 }} · 变更 {{ scanStatus.report.updated || 0 }} · 删除 {{ scanStatus.report.deleted || 0 }} · 跳过 {{ scanStatus.report.skipped || 0 }} · 失败 {{ scanStatus.report.failed_files?.length || 0 }}
      </span>
      <span v-else-if="scanStatus.error" class="scan-status-text">{{ scanStatus.error }}</span>
    </div>
--- a/web/src/components/tests/LibraryCard.spec.js
+++ b/web/src/components/tests/LibraryCard.spec.js
@@ -60,7 +60,7 @@ describe('LibraryCard.vue', () => {
    const wrapper = setup({
      scanStatus: {
        running: true,
-        report: { processed: 1, total_files: 2, added: 0, skipped: 0, failed_files: [] },
+        report: { processed: 1, total_files: 2, added: 0, updated: 0, deleted: 0, skipped: 0, failed_files: [] },
      },
    })

@@ -82,12 +82,14 @@ describe('LibraryCard.vue', () => {
    const wrapper = setup({
      scanStatus: {
        running: false,
-        report: { added: 3, skipped: 2, failed_files: ['/bad.mp3'] },
+        report: { added: 3, updated: 1, deleted: 2, skipped: 2, failed_files: ['/bad.mp3'] },
      },
    })

    expect(wrapper.text()).toContain('最近一次扫描')
    expect(wrapper.text()).toContain('新增 3')
+    expect(wrapper.text()).toContain('变更 1')
+    expect(wrapper.text()).toContain('删除 2')
    expect(wrapper.text()).toContain('跳过 2')
    expect(wrapper.text()).toContain('失败 1')
    wrapper.unmount()
--- a/web/src/stores/tests/butterfliu.spec.js
+++ b/web/src/stores/tests/butterfliu.spec.js
@@ -59,15 +59,15 @@ describe('butterfliu store', () => {
      const responses = [
        {
          ok: true,
-          json: () => Promise.resolve({ running: true, library_id: 1, report: { processed: 0, total_files: 2, added: 0, skipped: 0, failed_files: [] } }),
+          json: () => Promise.resolve({ running: true, library_id: 1, report: { processed: 0, total_files: 2, added: 0, updated: 0, deleted: 0, skipped: 0, failed_files: [] } }),
        },
        {
          ok: true,
-          json: () => Promise.resolve({ running: true, library_id: 1, report: { processed: 1, total_files: 2, added: 1, skipped: 0, failed_files: [] } }),
+          json: () => Promise.resolve({ running: true, library_id: 1, report: { processed: 1, total_files: 2, added: 1, updated: 0, deleted: 0, skipped: 0, failed_files: [] } }),
        },
        {
          ok: true,
-          json: () => Promise.resolve({ running: false, library_id: 1, report: { processed: 2, total_files: 2, added: 1, skipped: 1, failed_files: [] } }),
+          json: () => Promise.resolve({ running: false, library_id: 1, report: { processed: 2, total_files: 2, added: 1, updated: 1, deleted: 0, skipped: 0, failed_files: [] } }),
        },
      ]
      const fetchMock = mockFetch(() => Promise.resolve(responses.shift()))
@@ -79,7 +79,7 @@ describe('butterfliu store', () => {
      await vi.advanceTimersByTimeAsync(1000)
      const result = await promise

-      expect(result).toEqual({ running: false, library_id: 1, report: { processed: 2, total_files: 2, added: 1, skipped: 1, failed_files: [] } })
+      expect(result).toEqual({ running: false, library_id: 1, report: { processed: 2, total_files: 2, added: 1, updated: 1, deleted: 0, skipped: 0, failed_files: [] } })
      expect(fetchMock).toHaveBeenNthCalledWith(1, '/api/libraries/1/scan', {
        method: 'POST',
      })