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/backend/music.go

@@ -13,6 +13,7 @@ import (
 	"music-server/internal/db/repository"
 	"music-server/internal/logging"
 
+	"github.com/google/uuid"
 	"github.com/jackc/pgx/v5"
 	"go.uber.org/zap"
 )
@@ -21,12 +22,14 @@ import (
 const maxPickAttempts = 100
 
 type SongInfo struct {
-	Soundtrack       string `json:"Soundtrack"`
-	SoundtrackPlayed int32  `json:"SoundtrackPlayed"`
-	Song             string `json:"Song"`
-	SongPlayed       int32  `json:"SongPlayed"`
-	CurrentlyPlaying bool   `json:"CurrentlyPlaying"`
-	SongNo           int    `json:"SongNo"`
+	SoundtrackUuid   uuid.UUID `json:"SoundtrackUuid"`
+	Soundtrack       string    `json:"Soundtrack"`
+	SoundtrackPlayed int32     `json:"SoundtrackPlayed"`
+	SongUuid         uuid.UUID `json:"SongUuid"`
+	Song             string    `json:"Song"`
+	SongPlayed       int32     `json:"SongPlayed"`
+	CurrentlyPlaying bool      `json:"CurrentlyPlaying"`
+	SongNo           int       `json:"SongNo"`
 }
 
 // MusicService picks songs and keeps track of the shared play queue.
@@ -111,10 +114,10 @@ func (m *MusicService) SetPlayed(ctx context.Context, songNumber int) error {
 }
 
 func (m *MusicService) markPlayed(ctx context.Context, song repository.Song) error {
-	if err := m.q.AddSoundtrackPlayed(ctx, song.SoundtrackID); err != nil {
+	if err := m.q.AddSoundtrackPlayedByUUID(ctx, song.SoundtrackUuid); err != nil {
 		return err
 	}
-	return m.q.AddSongPlayed(ctx, repository.AddSongPlayedParams{SoundtrackID: song.SoundtrackID, SongName: song.SongName})
+	return m.q.AddSongPlayedByUUID(ctx, song.Uuid)
 }
 
 func (m *MusicService) validIndex(i int) bool {
@@ -182,8 +185,10 @@ func (m *MusicService) SongInfo(ctx context.Context) SongInfo {
 	song := m.queue[m.currentSong]
 	soundtrack := m.soundtrackFor(ctx, song)
 	return SongInfo{
+		SoundtrackUuid:   soundtrack.Uuid,
 		Soundtrack:       soundtrack.SoundtrackName,
 		SoundtrackPlayed: soundtrack.TimesPlayed,
+		SongUuid:         song.Uuid,
 		Song:             song.SongName,
 		SongPlayed:       song.TimesPlayed,
 		CurrentlyPlaying: true,
@@ -197,8 +202,10 @@ func (m *MusicService) PlayedSongs(ctx context.Context) []SongInfo {
 	for i, song := range m.queue {
 		soundtrack := m.soundtrackFor(ctx, song)
 		songList = append(songList, SongInfo{
+			SoundtrackUuid:   soundtrack.Uuid,
 			Soundtrack:       soundtrack.SoundtrackName,
 			SoundtrackPlayed: soundtrack.TimesPlayed,
+			SongUuid:         song.Uuid,
 			Song:             song.SongName,
 			SongPlayed:       song.TimesPlayed,
 			CurrentlyPlaying: i == m.currentSong,
@@ -331,7 +338,7 @@ func (m *MusicService) removeBrokenSong(ctx context.Context, song repository.Son
 	logging.GetLogger().Warn("Song not found, removing from database",
 		zap.String("song", song.SongName),
 		zap.String("path", song.Path))
-	return m.q.RemoveBrokenSong(ctx, repository.RemoveBrokenSongParams{SoundtrackID: song.SoundtrackID, Path: song.Path})
+	return m.q.RemoveBrokenSongs(ctx, []uuid.UUID{song.Uuid})
 }
 
 // songIsPlayable reports whether the song file exists and its stored path is consistent.
@@ -352,7 +359,7 @@ func (m *MusicService) soundtrackFor(ctx context.Context, song repository.Song)
 		return repository.Soundtrack{}
 	}
 	for _, soundtrack := range soundtracks {
-		if soundtrack.ID == song.SoundtrackID {
+		if soundtrack.Uuid == song.SoundtrackUuid {
 			return soundtrack
 		}
 	}