Prefer UUIDs in the API (Phase 3 of the UUID migration)

- New /api/v1 endpoints: GET /soundtracks, /soundtracks/{uuid},
  /songs/{uuid} and /songs/{uuid}/file (streams the song, Range support,
  locked during sync)
- UUIDs added to every response with soundtracks or songs: queue info and
  list (SoundtrackUuid, SongUuid) and statistics (soundtrack_uuid,
  song_uuid). Existing fields stay for backward compatibility
- Play counts and broken-song removal use song UUIDs instead of
  soundtrack ID + song name, so songs with the same name are counted
  separately
- Statistics return an empty song list for soundtracks without songs
  instead of a single empty entry
- The legacy .id file cleanup stays until Phase 4 (#31)

Closes #29

internal/testutil/fakedb/fakedb.go

@@ -52,12 +52,15 @@ func (s *Store) AddSoundtrack(st repository.Soundtrack) repository.Soundtrack {
 	return st
 }
 
-// AddTestSong inserts a song and returns it with its UUID set.
+// AddTestSong inserts a song and returns it with its UUID and soundtrack UUID set.
 func (s *Store) AddTestSong(song repository.Song) repository.Song {
 	defer s.lock()()
 	if song.Uuid == uuid.Nil {
 		song.Uuid = uuid.New()
 	}
+	if i := s.soundtrackIndex(song.SoundtrackID); song.SoundtrackUuid == uuid.Nil && i >= 0 {
+		song.SoundtrackUuid = s.Soundtracks[i].Uuid
+	}
 	s.Songs = append(s.Songs, song)
 	return song
 }
@@ -162,9 +165,29 @@ func (s *Store) RemoveSoundtrackDeletionDate(_ context.Context, id int32) error
 	return s.updateSoundtrack(id, func(st *repository.Soundtrack) { st.Deleted = nil })
 }
 
-func (s *Store) AddSoundtrackPlayed(_ context.Context, id int32) error {
+func (s *Store) AddSoundtrackPlayedByUUID(_ context.Context, id uuid.UUID) error {
+	defer s.lock()()
 	now := time.Now()
-	return s.updateSoundtrack(id, func(st *repository.Soundtrack) { st.TimesPlayed++; st.LastPlayed = &now })
+	for i := range s.Soundtracks {
+		if s.Soundtracks[i].Uuid == id {
+			s.Soundtracks[i].TimesPlayed++
+			s.Soundtracks[i].LastPlayed = &now
+		}
+	}
+	return s.Err
+}
+
+func (s *Store) GetSoundtrackByUUID(_ context.Context, id uuid.UUID) (repository.Soundtrack, error) {
+	defer s.lock()()
+	if s.Err != nil {
+		return repository.Soundtrack{}, s.Err
+	}
+	for _, st := range s.Soundtracks {
+		if st.Uuid == id && st.Deleted == nil {
+			return st, nil
+		}
+	}
+	return repository.Soundtrack{}, pgx.ErrNoRows
 }
 
 func (s *Store) MarkSoundtracksDeletedExcept(_ context.Context, ids []int32) error {
@@ -231,22 +254,46 @@ func (s *Store) UpdateSongByUUID(_ context.Context, arg repository.UpdateSongByU
 	return s.Err
 }
 
-func (s *Store) AddSongPlayed(_ context.Context, arg repository.AddSongPlayedParams) error {
+func (s *Store) AddSongPlayedByUUID(_ context.Context, id uuid.UUID) error {
 	defer s.lock()()
 	for i := range s.Songs {
-		if s.Songs[i].SoundtrackID == arg.SoundtrackID && s.Songs[i].SongName == arg.SongName {
+		if s.Songs[i].Uuid == id {
 			s.Songs[i].TimesPlayed++
 		}
 	}
 	return s.Err
 }
 
-func (s *Store) RemoveBrokenSong(_ context.Context, arg repository.RemoveBrokenSongParams) error {
+func (s *Store) GetSongsBySoundtrackUUID(_ context.Context, id uuid.UUID) ([]repository.Song, error) {
 	defer s.lock()()
-	s.Songs = slices.DeleteFunc(s.Songs, func(song repository.Song) bool {
-		return song.SoundtrackID == arg.SoundtrackID && song.Path == arg.Path
-	})
-	return s.Err
+	if s.Err != nil {
+		return nil, s.Err
+	}
+	var songs []repository.Song
+	for _, song := range s.Songs {
+		if song.SoundtrackUuid == id {
+			songs = append(songs, song)
+		}
+	}
+	slices.SortFunc(songs, func(a, b repository.Song) int { return cmp.Compare(a.SongName, b.SongName) })
+	return songs, nil
+}
+
+func (s *Store) GetActiveSongByUUID(_ context.Context, id uuid.UUID) (repository.GetActiveSongByUUIDRow, error) {
+	defer s.lock()()
+	if s.Err != nil {
+		return repository.GetActiveSongByUUIDRow{}, s.Err
+	}
+	for _, song := range s.Songs {
+		if song.Uuid != id {
+			continue
+		}
+		if i := s.soundtrackIndex(song.SoundtrackID); i >= 0 && s.Soundtracks[i].Deleted == nil {
+			st := s.Soundtracks[i]
+			return repository.GetActiveSongByUUIDRow{Song: song, SoundtrackName: st.SoundtrackName, SoundtrackPath: st.Path}, nil
+		}
+	}
+	return repository.GetActiveSongByUUIDRow{}, pgx.ErrNoRows
 }
 
 func (s *Store) RemoveBrokenSongs(_ context.Context, uuids []uuid.UUID) error {