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/library_integration_test.go

@@ -0,0 +1,81 @@
+//go:build integration
+
+package backend
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"music-server/internal/db/repository"
+	"music-server/internal/testutil/pgtest"
+
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestLibraryAndStatisticsWithPostgres checks the UUID and statistics queries against a real database.
+func TestLibraryAndStatisticsWithPostgres(t *testing.T) {
+	ctx := context.Background()
+	q := repository.New(pgtest.NewMigratedDatabase(t).Pool)
+	musicDir := copyTestMusic(t)
+	require.NoError(t, os.Mkdir(filepath.Join(musicDir, "Empty Soundtrack"), 0o755))
+	writeFile(t, filepath.Join(musicDir, "Empty Soundtrack", "cover.jpg"), "image")
+
+	s := NewSyncService(q, musicDir, nil)
+	require.True(t, s.Start(false))
+	s.Wait()
+	require.Empty(t, s.Result().CatchedErrors)
+
+	library := NewLibraryService(q)
+	soundtracks, err := library.Soundtracks(ctx)
+	require.NoError(t, err)
+	require.Len(t, soundtracks, 4)
+
+	bird, err := library.Soundtrack(ctx, soundtracks[0].Uuid)
+	require.NoError(t, err)
+	assert.Equal(t, "A Bird Story", bird.Name)
+	require.Len(t, bird.Songs, 6)
+	song := bird.Songs[0]
+	assert.Equal(t, bird.Uuid, song.SoundtrackUuid)
+
+	info, err := library.Song(ctx, song.Uuid)
+	require.NoError(t, err)
+	assert.Equal(t, "A Bird Story", info.SoundtrackName)
+	path, err := library.SongPath(ctx, song.Uuid)
+	require.NoError(t, err)
+	assert.FileExists(t, path)
+	_, err = library.Song(ctx, uuid.New())
+	assert.ErrorIs(t, err, ErrNotFound)
+
+	// Play counts by UUID.
+	require.NoError(t, q.AddSongPlayedByUUID(ctx, song.Uuid))
+	require.NoError(t, q.AddSoundtrackPlayedByUUID(ctx, bird.Uuid))
+	info, err = library.Song(ctx, song.Uuid)
+	require.NoError(t, err)
+	assert.Equal(t, int32(1), info.TimesPlayed)
+
+	stats := NewStatisticsService(q)
+	most, err := stats.MostPlayedSoundtracks(ctx, 10)
+	require.NoError(t, err)
+	require.NotEmpty(t, most)
+	assert.Equal(t, bird.Uuid, most[0].SoundtrackUuid)
+	assert.Len(t, most[0].Songs, 6)
+	assert.NotEqual(t, uuid.Nil, most[0].Songs[0].SongUuid)
+
+	songs, err := stats.MostPlayedSongs(ctx, 1)
+	require.NoError(t, err)
+	assert.Equal(t, song.Uuid, songs[0].SongUuid)
+	assert.Equal(t, bird.Uuid, songs[0].SoundtrackUuid)
+
+	never, err := stats.NeverPlayedSoundtracks(ctx)
+	require.NoError(t, err)
+	for _, st := range never {
+		assert.NotEqual(t, uuid.Nil, st.SoundtrackUuid)
+		if st.SoundtrackName == "Empty Soundtrack" {
+			assert.Empty(t, st.Songs, "a soundtrack without songs has an empty song list")
+		}
+	}
+}