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/server/handlers_test.go

@@ -13,6 +13,7 @@ import (
 	"music-server/internal/config"
 	"music-server/internal/db/repository"
 
+	"github.com/google/uuid"
 	"github.com/jackc/pgx/v5/pgtype"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -237,6 +238,11 @@ func TestTokenRateLimit(t *testing.T) {
 	assert.Contains(t, rec.Body.String(), "Rate limit exceeded")
 }
 
+var (
+	statsSoundtrackUUID = uuid.New()
+	statsSongUUID       = uuid.New()
+)
+
 // statsStore returns canned statistics.
 type statsStore struct {
 	repository.Querier
@@ -246,8 +252,9 @@ type statsStore struct {
 func (s statsStore) GetMostPlayedSoundtracksWithSongs(_ context.Context, limit int32) ([]repository.GetMostPlayedSoundtracksWithSongsRow, error) {
 	return []repository.GetMostPlayedSoundtracksWithSongsRow{{
 		SoundtrackID:   int32(limit),
+		SoundtrackUuid: statsSoundtrackUUID,
 		SoundtrackName: "Game A",
-		Songs:          []byte(`[{"song_name":"Song","times_played":3}]`),
+		Songs:          []byte(`[{"song_uuid":"` + statsSongUUID.String() + `","song_name":"Song","times_played":3}]`),
 	}}, s.err
 }
 
@@ -265,6 +272,8 @@ func TestStatisticsEndpoints(t *testing.T) {
 	require.Len(t, soundtracks, 1)
 	assert.Equal(t, int32(10), soundtracks[0].SoundtrackID, "default limit")
 	assert.Equal(t, "Song", soundtracks[0].Songs[0].SongName)
+	assert.Equal(t, statsSoundtrackUUID, soundtracks[0].SoundtrackUuid)
+	assert.Equal(t, statsSongUUID, soundtracks[0].Songs[0].SongUuid)
 
 	require.NoError(t, json.Unmarshal(e.do(http.MethodGet, "/api/v1/statistics/soundtracks/most-played?limit=500").Body.Bytes(), &soundtracks))
 	assert.Equal(t, int32(100), soundtracks[0].SoundtrackID, "limit is capped")