feat(db/m7-cover-sources): SQL queries for provider settings + recheck

- Extends GetAlbumCoverageRollup's with_art FILTER to include 'theaudiodb' so F's coverage gauge surfaces TheAudioDB-found rows as with_art rather than silently undercounting. - Modifies ListAlbumsMissingCover to take the current sources_version as a parameter; eligibility now includes stale-'none' rows. - Adds SetAlbumCoverWithVersion (atomic write of path + source + version stamp) and the parallel SetArtistArtWithVersion + ClearArtistArtNone + ListArtistsMissingArt for the artist-art enricher. - New coverart_settings.sql with ListProviderSettings, UpsertProviderSettings (boot reconciliation, preserves operator values on conflict), UpdateProviderSettings (admin PATCH; tri- state api_key handling), GetCurrentSourcesVersion, BumpSourcesVersion (RETURNING the new value).
2026-05-06 12:28:18 -04:00
parent a86897b35e
commit 526a78b302
12 changed files with 550 additions and 88 deletions
@@ -11,6 +11,21 @@ import (
 	"github.com/jackc/pgx/v5/pgtype"
 )

+const clearArtistArtNone = `-- name: ClearArtistArtNone :exec
+UPDATE artists
+   SET artist_art_source = NULL,
+       updated_at        = now()
+ WHERE id = $1
+   AND artist_art_source = 'none'
+`
+
+// M7 cover-sources: parallel of ClearAlbumCoverNone. Used by the
+// eligibility loop to flip stale 'none' rows back to NULL.
+func (q *Queries) ClearArtistArtNone(ctx context.Context, id pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, clearArtistArtNone, id)
+	return err
+}
+
 const countArtists = `-- name: CountArtists :one
 SELECT COUNT(*) FROM artists
 `
@@ -52,25 +67,46 @@ func (q *Queries) DeleteArtistIfEmpty(ctx context.Context, id pgtype.UUID) (pgty
 }

 const getArtistByID = `-- name: GetArtistByID :one
-SELECT id, name, sort_name, mbid, created_at, updated_at FROM artists WHERE id = $1
+SELECT a.id, a.name, a.sort_name, a.mbid,
+       a.artist_thumb_path, a.artist_fanart_path,
+       a.artist_art_source, a.artist_art_sources_version
+  FROM artists a
+ WHERE a.id = $1
 `

-func (q *Queries) GetArtistByID(ctx context.Context, id pgtype.UUID) (Artist, error) {
+type GetArtistByIDRow struct {
+	ID                      pgtype.UUID
+	Name                    string
+	SortName                string
+	Mbid                    *string
+	ArtistThumbPath         *string
+	ArtistFanartPath        *string
+	ArtistArtSource         *string
+	ArtistArtSourcesVersion int32
+}
+
+// M7 cover-sources: enricher reads the artist's mbid + current art
+// columns to drive eligibility check. (Modified from SELECT * to
+// explicitly include the new artist_art_* columns added in migration
+// 0018.)
+func (q *Queries) GetArtistByID(ctx context.Context, id pgtype.UUID) (GetArtistByIDRow, error) {
 	row := q.db.QueryRow(ctx, getArtistByID, id)
-	var i Artist
+	var i GetArtistByIDRow
 	err := row.Scan(
 		&i.ID,
 		&i.Name,
 		&i.SortName,
 		&i.Mbid,
-		&i.CreatedAt,
-		&i.UpdatedAt,
+		&i.ArtistThumbPath,
+		&i.ArtistFanartPath,
+		&i.ArtistArtSource,
+		&i.ArtistArtSourcesVersion,
 	)
 	return i, err
 }

 const getArtistByName = `-- name: GetArtistByName :one
-SELECT id, name, sort_name, mbid, created_at, updated_at FROM artists WHERE name = $1 LIMIT 1
+SELECT id, name, sort_name, mbid, created_at, updated_at, artist_thumb_path, artist_fanart_path, artist_art_source, artist_art_sources_version FROM artists WHERE name = $1 LIMIT 1
 `

 func (q *Queries) GetArtistByName(ctx context.Context, name string) (Artist, error) {
@@ -83,12 +119,16 @@ func (q *Queries) GetArtistByName(ctx context.Context, name string) (Artist, err
 		&i.Mbid,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.ArtistThumbPath,
+		&i.ArtistFanartPath,
+		&i.ArtistArtSource,
+		&i.ArtistArtSourcesVersion,
 	)
 	return i, err
 }

 const getArtistsByIDs = `-- name: GetArtistsByIDs :many
-SELECT id, name, sort_name, mbid, created_at, updated_at FROM artists WHERE id = ANY($1::uuid[])
+SELECT id, name, sort_name, mbid, created_at, updated_at, artist_thumb_path, artist_fanart_path, artist_art_source, artist_art_sources_version FROM artists WHERE id = ANY($1::uuid[])
 `

 // Batched lookup used by M5c suggestion attribution to resolve top-3
@@ -109,6 +149,10 @@ func (q *Queries) GetArtistsByIDs(ctx context.Context, dollar_1 []pgtype.UUID) (
 			&i.Mbid,
 			&i.CreatedAt,
 			&i.UpdatedAt,
+			&i.ArtistThumbPath,
+			&i.ArtistFanartPath,
+			&i.ArtistArtSource,
+			&i.ArtistArtSourcesVersion,
 		); err != nil {
 			return nil, err
 		}
@@ -121,7 +165,7 @@ func (q *Queries) GetArtistsByIDs(ctx context.Context, dollar_1 []pgtype.UUID) (
 }

 const listArtists = `-- name: ListArtists :many
-SELECT id, name, sort_name, mbid, created_at, updated_at FROM artists ORDER BY sort_name
+SELECT id, name, sort_name, mbid, created_at, updated_at, artist_thumb_path, artist_fanart_path, artist_art_source, artist_art_sources_version FROM artists ORDER BY sort_name
 `

 func (q *Queries) ListArtists(ctx context.Context) ([]Artist, error) {
@@ -140,6 +184,10 @@ func (q *Queries) ListArtists(ctx context.Context) ([]Artist, error) {
 			&i.Mbid,
 			&i.CreatedAt,
 			&i.UpdatedAt,
+			&i.ArtistThumbPath,
+			&i.ArtistFanartPath,
+			&i.ArtistArtSource,
+			&i.ArtistArtSourcesVersion,
 		); err != nil {
 			return nil, err
 		}
@@ -152,7 +200,7 @@ func (q *Queries) ListArtists(ctx context.Context) ([]Artist, error) {
 }

 const listArtistsAlpha = `-- name: ListArtistsAlpha :many
-SELECT id, name, sort_name, mbid, created_at, updated_at FROM artists ORDER BY sort_name, name, id LIMIT $1 OFFSET $2
+SELECT id, name, sort_name, mbid, created_at, updated_at, artist_thumb_path, artist_fanart_path, artist_art_source, artist_art_sources_version FROM artists ORDER BY sort_name, name, id LIMIT $1 OFFSET $2
 `

 type ListArtistsAlphaParams struct {
@@ -176,6 +224,10 @@ func (q *Queries) ListArtistsAlpha(ctx context.Context, arg ListArtistsAlphaPara
 			&i.Mbid,
 			&i.CreatedAt,
 			&i.UpdatedAt,
+			&i.ArtistThumbPath,
+			&i.ArtistFanartPath,
+			&i.ArtistArtSource,
+			&i.ArtistArtSourcesVersion,
 		); err != nil {
 			return nil, err
 		}
@@ -188,7 +240,7 @@ func (q *Queries) ListArtistsAlpha(ctx context.Context, arg ListArtistsAlphaPara
 }

 const listArtistsAlphaWithCovers = `-- name: ListArtistsAlphaWithCovers :many
-SELECT artists.id, artists.name, artists.sort_name, artists.mbid, artists.created_at, artists.updated_at,
+SELECT artists.id, artists.name, artists.sort_name, artists.mbid, artists.created_at, artists.updated_at, artists.artist_thumb_path, artists.artist_fanart_path, artists.artist_art_source, artists.artist_art_sources_version,
       cov.id AS cover_album_id,
       cnt.album_count::bigint AS album_count
 FROM artists
@@ -237,6 +289,10 @@ func (q *Queries) ListArtistsAlphaWithCovers(ctx context.Context, arg ListArtist
 			&i.Artist.Mbid,
 			&i.Artist.CreatedAt,
 			&i.Artist.UpdatedAt,
+			&i.Artist.ArtistThumbPath,
+			&i.Artist.ArtistFanartPath,
+			&i.Artist.ArtistArtSource,
+			&i.Artist.ArtistArtSourcesVersion,
 			&i.CoverAlbumID,
 			&i.AlbumCount,
 		); err != nil {
@@ -250,8 +306,46 @@ func (q *Queries) ListArtistsAlphaWithCovers(ctx context.Context, arg ListArtist
 	return items, nil
 }

+const listArtistsMissingArt = `-- name: ListArtistsMissingArt :many
+SELECT a.id
+  FROM artists a
+ WHERE a.artist_art_source IS NULL
+    OR (a.artist_art_source = 'none' AND a.artist_art_sources_version != $1)
+ ORDER BY a.created_at
+ LIMIT $2
+`
+
+type ListArtistsMissingArtParams struct {
+	ArtistArtSourcesVersion int32
+	Limit                   int32
+}
+
+// M7 cover-sources: returns artist rows the artist-art enricher should
+// attempt. Eligible: artist_art_source IS NULL OR (= 'none' AND stale
+// artist_art_sources_version). MBID-less artists are returned but the
+// enricher skips them at the row.mbid == nil guard inside the chain.
+func (q *Queries) ListArtistsMissingArt(ctx context.Context, arg ListArtistsMissingArtParams) ([]pgtype.UUID, error) {
+	rows, err := q.db.Query(ctx, listArtistsMissingArt, arg.ArtistArtSourcesVersion, arg.Limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []pgtype.UUID
+	for rows.Next() {
+		var id pgtype.UUID
+		if err := rows.Scan(&id); err != nil {
+			return nil, err
+		}
+		items = append(items, id)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const listArtistsNewest = `-- name: ListArtistsNewest :many
-SELECT id, name, sort_name, mbid, created_at, updated_at FROM artists ORDER BY created_at DESC, id DESC LIMIT $1 OFFSET $2
+SELECT id, name, sort_name, mbid, created_at, updated_at, artist_thumb_path, artist_fanart_path, artist_art_source, artist_art_sources_version FROM artists ORDER BY created_at DESC, id DESC LIMIT $1 OFFSET $2
 `

 type ListArtistsNewestParams struct {
@@ -276,6 +370,10 @@ func (q *Queries) ListArtistsNewest(ctx context.Context, arg ListArtistsNewestPa
 			&i.Mbid,
 			&i.CreatedAt,
 			&i.UpdatedAt,
+			&i.ArtistThumbPath,
+			&i.ArtistFanartPath,
+			&i.ArtistArtSource,
+			&i.ArtistArtSourcesVersion,
 		); err != nil {
 			return nil, err
 		}
@@ -288,7 +386,7 @@ func (q *Queries) ListArtistsNewest(ctx context.Context, arg ListArtistsNewestPa
 }

 const searchArtists = `-- name: SearchArtists :many
-SELECT id, name, sort_name, mbid, created_at, updated_at FROM artists
+SELECT id, name, sort_name, mbid, created_at, updated_at, artist_thumb_path, artist_fanart_path, artist_art_source, artist_art_sources_version FROM artists
 WHERE name ILIKE '%' || $1 || '%'
 ORDER BY sort_name
 LIMIT $2 OFFSET $3
@@ -316,6 +414,10 @@ func (q *Queries) SearchArtists(ctx context.Context, arg SearchArtistsParams) ([
 			&i.Mbid,
 			&i.CreatedAt,
 			&i.UpdatedAt,
+			&i.ArtistThumbPath,
+			&i.ArtistFanartPath,
+			&i.ArtistArtSource,
+			&i.ArtistArtSourcesVersion,
 		); err != nil {
 			return nil, err
 		}
@@ -327,6 +429,40 @@ func (q *Queries) SearchArtists(ctx context.Context, arg SearchArtistsParams) ([
 	return items, nil
 }

+const setArtistArtWithVersion = `-- name: SetArtistArtWithVersion :exec
+UPDATE artists
+   SET artist_thumb_path           = $2,
+       artist_fanart_path          = $3,
+       artist_art_source           = $4,
+       artist_art_sources_version  = $5,
+       updated_at                  = now()
+ WHERE id = $1
+`
+
+type SetArtistArtWithVersionParams struct {
+	ID                      pgtype.UUID
+	ArtistThumbPath         *string
+	ArtistFanartPath        *string
+	ArtistArtSource         *string
+	ArtistArtSourcesVersion int32
+}
+
+// M7 cover-sources: records a successful or settled artist-art
+// enrichment with the current sources_version stamp. thumb_path /
+// fanart_path are NULL on a 'none' result, or independently NULL if
+// the provider returned only one of the two image types (e.g.
+// TheAudioDB had a thumb but no fanart for this artist).
+func (q *Queries) SetArtistArtWithVersion(ctx context.Context, arg SetArtistArtWithVersionParams) error {
+	_, err := q.db.Exec(ctx, setArtistArtWithVersion,
+		arg.ID,
+		arg.ArtistThumbPath,
+		arg.ArtistFanartPath,
+		arg.ArtistArtSource,
+		arg.ArtistArtSourcesVersion,
+	)
+	return err
+}
+
 const setArtistMbidIfNull = `-- name: SetArtistMbidIfNull :exec
 UPDATE artists
   SET mbid = $2,
@@ -355,7 +491,7 @@ DO UPDATE SET
    name = EXCLUDED.name,
    sort_name = EXCLUDED.sort_name,
    updated_at = now()
-RETURNING id, name, sort_name, mbid, created_at, updated_at
+RETURNING id, name, sort_name, mbid, created_at, updated_at, artist_thumb_path, artist_fanart_path, artist_art_source, artist_art_sources_version
 `

 type UpsertArtistParams struct {
@@ -376,6 +512,10 @@ func (q *Queries) UpsertArtist(ctx context.Context, arg UpsertArtistParams) (Art
 		&i.Mbid,
 		&i.CreatedAt,
 		&i.UpdatedAt,
+		&i.ArtistThumbPath,
+		&i.ArtistFanartPath,
+		&i.ArtistArtSource,
+		&i.ArtistArtSourcesVersion,
 	)
 	return i, err
 }