优化扫描

2026-04-11 13:57:48 +08:00
parent 169b2c1858
commit 3f82e29c6c
11 changed files with 392 additions and 76 deletions
--- a/internal/controller/library.go
+++ b/internal/controller/library.go
@@ -7,15 +7,25 @@ import (
 	"net/http"
 	"strconv"
 	"sync"
+	"time"

 	"github.com/go-chi/chi/v5"
 )

+type ScanStatus struct {
+	Running    bool                `json:"running"`
+	LibraryID  int                 `json:"library_id"`
+	Report     *service.ScanReport `json:"report,omitempty"`
+	Error      string              `json:"error,omitempty"`
+	StartedAt  *time.Time          `json:"started_at,omitempty"`
+	FinishedAt *time.Time          `json:"finished_at,omitempty"`
+}
+
 type LibraryController struct {
 	libraryService *service.LibraryService
 	coverService   *service.CoverService
 	scanMutex      sync.Mutex
-	isScanning     bool
+	scanStatus     ScanStatus
 }

 func NewLibraryController(libraryService *service.LibraryService, coverSvc *service.CoverService) *LibraryController {
@@ -112,49 +122,91 @@ func (c *LibraryController) UpdatePath(w http.ResponseWriter, r *http.Request) {
 }

 func (c *LibraryController) Scan(w http.ResponseWriter, r *http.Request) {
-	c.scanMutex.Lock()
-	if c.isScanning {
-		c.scanMutex.Unlock()
-		jsonError(w, "Another scan is already in progress", http.StatusConflict)
-		return
-	}
-	c.isScanning = true
-	c.scanMutex.Unlock()
-
 	idParam := chi.URLParam(r, "id")
 	id, err := strconv.Atoi(idParam)
 	if err != nil {
-		c.scanMutex.Lock()
-		c.isScanning = false
-		c.scanMutex.Unlock()
 		jsonError(w, err.Error(), http.StatusBadRequest)
 		return
 	}

-	go func() {
-		defer func() {
-			c.scanMutex.Lock()
-			c.isScanning = false
-			c.scanMutex.Unlock()
-		}()
+	c.scanMutex.Lock()
+	if c.scanStatus.Running {
+		c.scanMutex.Unlock()
+		jsonError(w, "Another scan is already in progress", http.StatusConflict)
+		return
+	}

-		report, err := c.libraryService.Scan(id)
+	startedAt := time.Now()
+	c.scanStatus = ScanStatus{
+		Running:   true,
+		LibraryID: id,
+		Report:    &service.ScanReport{},
+		StartedAt: &startedAt,
+	}
+	startedStatus := c.cloneScanStatusLocked()
+	c.scanMutex.Unlock()
+
+	go func() {
+		report, err := c.libraryService.Scan(id, func(progress service.ScanReport) {
+			c.scanMutex.Lock()
+			if c.scanStatus.LibraryID == id {
+				progressCopy := progress
+				c.scanStatus.Report = &progressCopy
+			}
+			c.scanMutex.Unlock()
+		})
+
+		c.scanMutex.Lock()
+		defer c.scanMutex.Unlock()
+
+		finishedAt := time.Now()
+		c.scanStatus.Running = false
+		c.scanStatus.FinishedAt = &finishedAt
+		if report != nil {
+			reportCopy := *report
+			c.scanStatus.Report = &reportCopy
+		}
 		if err != nil {
+			c.scanStatus.Error = err.Error()
 			log.Printf("Scan failed for library %d: %v", id, err)
 			return
 		}

+		c.scanStatus.Error = ""
 		log.Printf("Scan completed for library %d: %+v", id, report)
 	}()

-	jsonMsg(w, "Library scan started.")
+	jsonResponse(w, startedStatus, http.StatusAccepted)
 }

 func (c *LibraryController) GetScanStatus(w http.ResponseWriter, r *http.Request) {
+	idParam := chi.URLParam(r, "id")
+	id, err := strconv.Atoi(idParam)
+	if err != nil {
+		jsonError(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
 	c.scanMutex.Lock()
-	scanning := c.isScanning
+	status := c.cloneScanStatusLocked()
 	c.scanMutex.Unlock()
-	jsonResponse(w, map[string]bool{"scanning": scanning}, http.StatusOK)
+
+	if status.LibraryID != id {
+		jsonResponse(w, ScanStatus{LibraryID: id, Report: &service.ScanReport{}}, http.StatusOK)
+		return
+	}
+
+	jsonResponse(w, status, http.StatusOK)
+}
+
+func (c *LibraryController) cloneScanStatusLocked() ScanStatus {
+	status := c.scanStatus
+	if c.scanStatus.Report != nil {
+		reportCopy := *c.scanStatus.Report
+		reportCopy.FailedFiles = append([]string(nil), c.scanStatus.Report.FailedFiles...)
+		status.Report = &reportCopy
+	}
+	return status
 }

 func (c *LibraryController) Delete(w http.ResponseWriter, r *http.Request) {
--- a/internal/repository/media_repo.go
+++ b/internal/repository/media_repo.go
@@ -5,6 +5,12 @@ import (
 	"database/sql"
 )

+type ExistingMediaFile struct {
+	Path        string
+	MediaFileID int
+	HasSong     bool
+}
+
 type MediaRepository struct {
 	db *sql.DB
 }
@@ -63,6 +69,31 @@ func (r *MediaRepository) Create(path string, libraryID int) (model.MediaFile, e
 	}, 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
+		FROM media_files mf
+		LEFT JOIN songs s ON s.media_file_id = mf.id
+		WHERE mf.library_id = ?
+	`, libraryID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	existing := []ExistingMediaFile{}
+	for rows.Next() {
+		var item ExistingMediaFile
+		var hasSong int
+		if err := rows.Scan(&item.Path, &item.MediaFileID, &hasSong); err != nil {
+			return nil, err
+		}
+		item.HasSong = hasSong == 1
+		existing = append(existing, item)
+	}
+	return existing, nil
+}
+
 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
@@ -95,6 +95,18 @@ func (r *SongRepository) Get(id int) (model.Song, error) {
 	return song, nil
 }

+func (r *SongRepository) HasByMediaFileID(mediaFileID int) (bool, error) {
+	var exists int
+	err := r.db.QueryRow("SELECT 1 FROM songs WHERE media_file_id = ? LIMIT 1", mediaFileID).Scan(&exists)
+	if err == sql.ErrNoRows {
+		return false, nil
+	}
+	if err != nil {
+		return false, err
+	}
+	return true, nil
+}
+
 func (r *SongRepository) Create(title string, artistID, albumID, duration, mediaFileID int) (model.Song, error) {
 	result, err := r.db.Exec(
 		"INSERT INTO songs (title, artist_id, album_id, duration, media_file_id) VALUES (?, ?, ?, ?, ?)",
--- a/internal/scanner/scanner.go
+++ b/internal/scanner/scanner.go
@@ -31,12 +31,26 @@ type ffprobeOutput struct {
 }

 func ScanDirectory(dirPath string) ([]ScannedSong, error) {
-	songs := []ScannedSong{}
-
-	if _, err := exec.LookPath("ffprobe"); err != nil {
-		return songs, fmt.Errorf("ffprobe not found in PATH: %v", err)
+	paths, err := ListAudioFiles(dirPath)
+	if err != nil {
+		return nil, err
 	}

+	songs := make([]ScannedSong, 0, len(paths))
+	for _, path := range paths {
+		song, err := ProbeAudioFile(path)
+		if err != nil {
+			continue
+		}
+		songs = append(songs, song)
+	}
+
+	return songs, nil
+}
+
+func ListAudioFiles(dirPath string) ([]string, error) {
+	paths := []string{}
+
 	err := filepath.Walk(dirPath, func(path string, info os.FileInfo, err error) error {
 		if err != nil {
 			return err
@@ -50,16 +64,19 @@ func ScanDirectory(dirPath string) ([]ScannedSong, error) {
 			return nil
 		}

-		if song, err := processAudioFile(path); err != nil {
-			// Log error but continue scanning other files
-			return nil
-		} else {
-			songs = append(songs, song)
-		}
+		paths = append(paths, path)
 		return nil
 	})

-	return songs, err
+	return paths, err
+}
+
+func ProbeAudioFile(filePath string) (ScannedSong, error) {
+	if _, err := exec.LookPath("ffprobe"); err != nil {
+		return ScannedSong{}, fmt.Errorf("ffprobe not found in PATH: %v", err)
+	}
+
+	return processAudioFile(filePath)
 }

 func processAudioFile(filePath string) (ScannedSong, error) {
--- a/internal/service/library.go
+++ b/internal/service/library.go
@@ -13,12 +13,15 @@ import (

 // ScanReport holds the result of a library scan.
 type ScanReport struct {
-	TotalFiles  int
-	Added       int
-	Skipped     int
-	FailedFiles []string
+	TotalFiles  int      `json:"total_files"`
+	Processed   int      `json:"processed"`
+	Added       int      `json:"added"`
+	Skipped     int      `json:"skipped"`
+	FailedFiles []string `json:"failed_files"`
 }

+type ScanProgressFunc func(ScanReport)
+
 type LibraryService struct {
 	libRepo    *repository.LibraryRepository
 	artistRepo *repository.ArtistRepository
@@ -166,35 +169,92 @@ func (s *LibraryService) GetAlbum(id int) (model.AlbumDetail, error) {
 	}, nil
 }

-func (s *LibraryService) Scan(id int) (*ScanReport, error) {
+func (s *LibraryService) Scan(id int, onProgress ScanProgressFunc) (*ScanReport, error) {
 	lib, err := s.libRepo.GetByID(id)
 	if err != nil {
 		return nil, fmt.Errorf("library %d not found: %w", id, err)
 	}

-	scannedSongs, err := scanner.ScanDirectory(lib.Path)
+	paths, err := scanner.ListAudioFiles(lib.Path)
 	if err != nil {
 		return nil, fmt.Errorf("scan directory %s: %w", lib.Path, err)
 	}

-	report := &ScanReport{TotalFiles: len(scannedSongs)}
+	existingFiles, err := s.mediaRepo.ListExistingByLibrary(lib.ID)
+	if err != nil {
+		return nil, fmt.Errorf("load existing media files: %w", err)
+	}

-	for _, song := range scannedSongs {
-		if err := s.addScannedSong(song, lib.ID, report); err != nil {
+	existingByPath := make(map[string]repository.ExistingMediaFile, len(existingFiles))
+	for _, existing := range existingFiles {
+		existingByPath[existing.Path] = existing
+	}
+
+	report := &ScanReport{TotalFiles: len(paths)}
+	notifyProgress(report, onProgress)
+
+	for _, path := range paths {
+		existing, found := existingByPath[path]
+		if found && existing.HasSong {
+			report.Skipped++
+			report.Processed++
+			notifyProgress(report, onProgress)
+			continue
+		}
+
+		song, err := scanner.ProbeAudioFile(path)
+		if err != nil {
+			log.Printf("Failed to probe %s: %v", filepath.Base(path), err)
+			report.FailedFiles = append(report.FailedFiles, 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)
 			report.FailedFiles = append(report.FailedFiles, song.Path)
 		}
+
+		report.Processed++
+		notifyProgress(report, onProgress)
 	}

 	log.Printf("Scan complete for library %d: %+v", id, report)
 	return report, nil
 }

+func notifyProgress(report *ScanReport, onProgress ScanProgressFunc) {
+	if onProgress == nil {
+		return
+	}
+
+	copyReport := ScanReport{
+		TotalFiles: report.TotalFiles,
+		Processed:  report.Processed,
+		Added:      report.Added,
+		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) error {
-	mediaFile, err := s.getOrCreateMediaFile(song.Path, libraryID)
-	if err != nil {
-		return fmt.Errorf("media file: %w", err)
+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
 	}

 	artist, err := s.getOrCreateArtist(song.Artist)
--- a/main.go
+++ b/main.go
@@ -45,8 +45,8 @@ func main() {
 		r.Put("/{id}/name", libraryController.UpdateName)
 		r.Put("/{id}/path", libraryController.UpdatePath)
 		r.Post("/{id}/scan", libraryController.Scan)
+		r.Get("/{id}/scan-status", libraryController.GetScanStatus)
 		r.Get("/{id}/songs", libraryController.GetSongs)
-		r.Get("/scan-status", libraryController.GetScanStatus)
 	})

 	r.Route("/api/songs", func(r chi.Router) {
--- a/web/src/components/LibraryCard.vue
+++ b/web/src/components/LibraryCard.vue
@@ -4,6 +4,20 @@
      <FolderOpen :size="32" />
    </div>
    <h4 class="card-name">{{ props.name }}</h4>
+
+    <div v-if="scanStatus" class="scan-status" :class="{ running: scanStatus.running, failed: !!scanStatus.error }">
+      <span class="scan-status-title">
+        {{ scanStatus.running ? '扫描中' : scanStatus.error ? '扫描失败' : '最近一次扫描' }}
+      </span>
+      <span v-if="scanStatus.running && scanStatus.report" class="scan-status-text">
+        {{ 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 }}
+      </span>
+      <span v-else-if="scanStatus.error" class="scan-status-text">{{ scanStatus.error }}</span>
+    </div>
+
    <DropDown>
      <template v-slot:trigger>
        <button class="card-menu-btn" aria-label="更多操作"><EllipsisVertical :size="16" /></button>
@@ -12,9 +26,9 @@
        <ListMusic class="dropdown-icon" :size="16" />
        <span class="dropdown-text">查看歌曲</span>
      </button>
-      <button class="dropdown-item" @click="scanCard">
-        <RotateCw class="dropdown-icon" :size="16" />
-        <span class="dropdown-text">扫描</span>
+      <button class="dropdown-item" :disabled="scanStatus?.running" @click="scanCard">
+        <RotateCw class="dropdown-icon" :class="{ spinning: scanStatus?.running }" :size="16" />
+        <span class="dropdown-text">{{ scanStatus?.running ? '扫描中' : '扫描' }}</span>
      </button>
      <button class="dropdown-item danger" type="button" @click="deleteCard">
        <Trash2 class="dropdown-icon" :size="16" />
@@ -31,10 +45,12 @@ import DropDown from './DropDown.vue'
 const props = defineProps({
  name: String,
  id: Number,
+  scanStatus: Object,
 })
 const emit = defineEmits(['delete', 'scan', 'viewSongs'])

 const scanCard = () => {
+  if (props.scanStatus?.running) return
  emit('scan', props.id)
 }
 const deleteCard = () => {
@@ -90,7 +106,34 @@ const viewSongs = () => {
  max-width: 100%;
 }

-/* 菜单按钮 */
+.scan-status {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 2px;
+  min-height: 40px;
+  text-align: center;
+}
+
+.scan-status-title {
+  font-size: var(--font-size-0);
+  color: var(--text-secondary);
+  font-weight: 600;
+}
+
+.scan-status-text {
+  font-size: var(--font-size-0);
+  color: var(--text-muted);
+}
+
+.scan-status.running .scan-status-title {
+  color: var(--brand);
+}
+
+.scan-status.failed .scan-status-title {
+  color: var(--red-7);
+}
+
 .card-menu-btn {
  position: absolute;
  top: var(--size-2);
@@ -116,4 +159,22 @@ const viewSongs = () => {
  background-color: var(--gray-3);
  color: var(--text-primary);
 }
+
+.dropdown-item:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.spinning {
+  animation: spin 1s linear infinite;
+}
+
+@keyframes spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
 </style>
--- a/web/src/components/tests/LibraryCard.spec.js
+++ b/web/src/components/tests/LibraryCard.spec.js
@@ -43,12 +43,10 @@ describe('LibraryCard.vue', () => {
  it('should emit scan event with id when scan button clicked', async () => {
    const wrapper = setup()

-    // Open dropdown first
    await wrapper.find('.card-menu-btn').trigger('click')
    await flushPromises()

    const buttons = getMenuButtons()
-    // Second button is "扫描"
    expect(buttons.length).toBeGreaterThanOrEqual(2)
    buttons[1].click()
    await flushPromises()
@@ -58,6 +56,43 @@ describe('LibraryCard.vue', () => {
    wrapper.unmount()
  })

+  it('should disable scan action while scanning', async () => {
+    const wrapper = setup({
+      scanStatus: {
+        running: true,
+        report: { processed: 1, total_files: 2, added: 0, skipped: 0, failed_files: [] },
+      },
+    })
+
+    expect(wrapper.text()).toContain('扫描中')
+
+    await wrapper.find('.card-menu-btn').trigger('click')
+    await flushPromises()
+
+    const buttons = getMenuButtons()
+    expect(buttons[1].disabled).toBe(true)
+    buttons[1].click()
+    await flushPromises()
+
+    expect(wrapper.emitted('scan')).toBeFalsy()
+    wrapper.unmount()
+  })
+
+  it('should render latest scan summary when available', () => {
+    const wrapper = setup({
+      scanStatus: {
+        running: false,
+        report: { added: 3, skipped: 2, failed_files: ['/bad.mp3'] },
+      },
+    })
+
+    expect(wrapper.text()).toContain('最近一次扫描')
+    expect(wrapper.text()).toContain('新增 3')
+    expect(wrapper.text()).toContain('跳过 2')
+    expect(wrapper.text()).toContain('失败 1')
+    wrapper.unmount()
+  })
+
  it('should emit delete event with id when delete button clicked', async () => {
    const wrapper = setup()

@@ -65,7 +100,6 @@ describe('LibraryCard.vue', () => {
    await flushPromises()

    const buttons = getMenuButtons()
-    // Third button (type=reset) is "删除"
    expect(buttons.length).toBeGreaterThanOrEqual(3)
    buttons[2].click()
    await flushPromises()
@@ -82,7 +116,6 @@ describe('LibraryCard.vue', () => {
    await flushPromises()

    const buttons = getMenuButtons()
-    // First button is "查看歌曲"
    expect(buttons.length).toBeGreaterThanOrEqual(1)
    buttons[0].click()
    await flushPromises()
--- a/web/src/stores/tests/butterfliu.spec.js
+++ b/web/src/stores/tests/butterfliu.spec.js
@@ -4,9 +4,11 @@ import { useButterfliuStore } from '../butterfliu'
 describe('butterfliu store', () => {
  beforeEach(() => {
    vi.restoreAllMocks()
+    vi.useFakeTimers()
  })

  afterEach(() => {
+    vi.useRealTimers()
    vi.unstubAllGlobals()
  })

@@ -53,20 +55,37 @@ describe('butterfliu store', () => {
  })

  describe('scanLibrary', () => {
-    it('should POST to scan endpoint and return result', async () => {
-      const mockResult = { added: 5, updated: 2 }
-      const fetchMock = mockFetch(() => Promise.resolve({
-        ok: true,
-        json: () => Promise.resolve(mockResult),
-      }))
+    it('should POST to scan endpoint and poll status until finished', async () => {
+      const responses = [
+        {
+          ok: true,
+          json: () => Promise.resolve({ running: true, library_id: 1, report: { processed: 0, total_files: 2, added: 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: [] } }),
+        },
+        {
+          ok: true,
+          json: () => Promise.resolve({ running: false, library_id: 1, report: { processed: 2, total_files: 2, added: 1, skipped: 1, failed_files: [] } }),
+        },
+      ]
+      const fetchMock = mockFetch(() => Promise.resolve(responses.shift()))

      const store = useButterfliuStore()
-      const result = await store.scanLibrary(1)
+      const promise = store.scanLibrary(1)

-      expect(result).toEqual(mockResult)
-      expect(fetchMock).toHaveBeenCalledWith('/api/libraries/1/scan', {
+      await vi.advanceTimersByTimeAsync(1000)
+      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(fetchMock).toHaveBeenNthCalledWith(1, '/api/libraries/1/scan', {
        method: 'POST',
      })
+      expect(fetchMock).toHaveBeenNthCalledWith(2, '/api/libraries/1/scan-status')
+      expect(fetchMock).toHaveBeenNthCalledWith(3, '/api/libraries/1/scan-status')
+      expect(store.scanStatusByLibraryId[1].running).toBe(false)
    })

    it('should set error on failure', async () => {
--- a/web/src/stores/butterfliu.js
+++ b/web/src/stores/butterfliu.js
@@ -1,9 +1,23 @@
 import { ref } from 'vue'
 import { defineStore } from 'pinia'

+const POLL_INTERVAL_MS = 1000
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
 export const useButterfliuStore = defineStore('butterfliu', () => {
  const libraries = ref([])
  const error = ref(null)
+  const scanStatusByLibraryId = ref({})
+
+  function setScanStatus(id, status) {
+    scanStatusByLibraryId.value = {
+      ...scanStatusByLibraryId.value,
+      [id]: status,
+    }
+  }

  async function fetchLibraries() {
    try {
@@ -17,6 +31,14 @@ export const useButterfliuStore = defineStore('butterfliu', () => {
    }
  }

+  async function fetchScanStatus(id) {
+    const resp = await fetch(`/api/libraries/${id}/scan-status`)
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}`)
+    const status = await resp.json()
+    setScanStatus(id, status)
+    return status
+  }
+
  async function scanLibrary(id) {
    try {
      error.value = null
@@ -24,8 +46,17 @@ export const useButterfliuStore = defineStore('butterfliu', () => {
        method: 'POST',
      })
      if (!resp.ok) throw new Error(`HTTP ${resp.status}`)
-      const result = await resp.json()
-      return result
+
+      const startedStatus = await resp.json()
+      setScanStatus(id, startedStatus)
+
+      let status = startedStatus
+      while (status.running) {
+        await sleep(POLL_INTERVAL_MS)
+        status = await fetchScanStatus(id)
+      }
+
+      return status
    } catch (e) {
      error.value = e.message
      console.error('Failed to scan library:', e)
@@ -76,7 +107,6 @@ export const useButterfliuStore = defineStore('butterfliu', () => {
    return resp.json()
  }

-  // TODO: 用于未来艺术家/专辑页面
  async function fetchArtists() {
    const resp = await fetch('/api/artists')
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`)
@@ -92,7 +122,9 @@ export const useButterfliuStore = defineStore('butterfliu', () => {
  return {
    libraries,
    error,
+    scanStatusByLibraryId,
    fetchLibraries,
+    fetchScanStatus,
    scanLibrary,
    addLibrary,
    deleteLibrary,
--- a/web/src/views/SettingsView.vue
+++ b/web/src/views/SettingsView.vue
@@ -18,20 +18,19 @@

    <AddLibraryDialog v-model="show" @confirm="toAddLibrary" />

-    <!-- 空状态 -->
    <div v-if="libraries.length === 0" class="empty-state">
      <FolderOpen :size="48" class="empty-icon" />
      <h3>还没有音乐库</h3>
      <p>点击上方「添加音乐库」按钮开始使用</p>
    </div>

-    <!-- 音乐库网格 -->
    <div v-else class="library-grid">
      <LibraryCard
        v-for="l in libraries"
        :key="l.id"
        :name="l.name"
        :id="l.id"
+        :scan-status="scanStatusMap[l.id]"
        @scan="toScanLibrary(l.id)"
        @delete="toDeleteLibrary(l.id)"
        @viewSongs="toViewSongs(l.id)"
@@ -51,14 +50,18 @@ import { useButterfliuStore } from '@/stores/butterfliu'
 const router = useRouter()
 const butterfliu = useButterfliuStore()
 const libraries = computed(() => butterfliu.libraries)
+const scanStatusMap = computed(() => butterfliu.scanStatusByLibraryId)
 const show = ref(false)

 function toAddLibrary(name, path) {
  butterfliu.addLibrary(name, path).then(() => butterfliu.fetchLibraries())
 }

-function toScanLibrary(id) {
-  butterfliu.scanLibrary(id)
+async function toScanLibrary(id) {
+  const status = await butterfliu.scanLibrary(id)
+  if (status && !status.error) {
+    await butterfliu.fetchLibraries()
+  }
 }

 function toDeleteLibrary(id) {
@@ -80,7 +83,6 @@ onMounted(() => {
  margin: 0 auto;
 }

-/* === 页面头部 === */
 .page-header {
  margin-bottom: var(--size-6);
  padding-bottom: var(--size-4);
@@ -97,14 +99,12 @@ onMounted(() => {
  font-size: var(--font-size-1);
 }

-/* === 操作按钮 === */
 .actions {
  display: flex;
  gap: var(--size-2);
  margin-bottom: var(--size-6);
 }

-/* === 空状态 === */
 .empty-state {
  display: flex;
  flex-direction: column;
@@ -129,7 +129,6 @@ onMounted(() => {
  color: var(--text-muted);
 }

-/* === 音乐库网格 === */
 .library-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));