From 0d8ba90b136b361998b60e5a59718c57c4bafd8b Mon Sep 17 00:00:00 2001
From: Deluan <deluan@navidrome.org>
Date: Fri, 17 Jul 2026 18:43:47 -0400
Subject: [PATCH] feat(album): add uploaded_image column and path helper

---
 consts/consts.go                                   |  1 +
 .../20260717224137_add_album_uploaded_image.sql    |  5 +++++
 model/album.go                                     |  6 ++++++
 model/album_test.go                                | 14 ++++++++++++++
 4 files changed, 26 insertions(+)
 create mode 100644 db/migrations/20260717224137_add_album_uploaded_image.sql

diff --git a/consts/consts.go b/consts/consts.go
index f453ac125..b788be9e9 100644
--- a/consts/consts.go
+++ b/consts/consts.go
@@ -124,6 +124,7 @@ const (
 // Entity types
 const (
 	EntityArtist   = "artist"
+	EntityAlbum    = "album"
 	EntityPlaylist = "playlist"
 	EntityRadio    = "radio"
 )
diff --git a/db/migrations/20260717224137_add_album_uploaded_image.sql b/db/migrations/20260717224137_add_album_uploaded_image.sql
new file mode 100644
index 000000000..9dcda817a
--- /dev/null
+++ b/db/migrations/20260717224137_add_album_uploaded_image.sql
@@ -0,0 +1,5 @@
+-- +goose Up
+ALTER TABLE album ADD COLUMN uploaded_image varchar NOT NULL DEFAULT '';
+
+-- +goose Down
+ALTER TABLE album DROP COLUMN uploaded_image;
diff --git a/model/album.go b/model/album.go
index ade7f6ee0..6f53e4c66 100644
--- a/model/album.go
+++ b/model/album.go
@@ -8,6 +8,7 @@ import (
 	"time"
 
 	"github.com/navidrome/navidrome/conf"
+	"github.com/navidrome/navidrome/consts"
 
 	"github.com/gohugoio/hashstructure"
 )
@@ -49,6 +50,7 @@ type Album struct {
 	MbzReleaseGroupID    string   `structs:"mbz_release_group_id" json:"mbzReleaseGroupId,omitempty"`
 	FolderIDs            []string `structs:"folder_ids" json:"-" hash:"set"` // All folders that contain media_files for this album
 	ExplicitStatus       string   `structs:"explicit_status" json:"explicitStatus"`
+	UploadedImage        string   `structs:"-" json:"uploadedImage,omitempty" hash:"ignore"`
 
 	// External metadata fields
 	Description           string     `structs:"description" json:"description,omitempty" hash:"ignore"`
@@ -73,6 +75,10 @@ func (a Album) CoverArtID() ArtworkID {
 	return artworkIDFromAlbum(a)
 }
 
+func (a Album) UploadedImagePath() string {
+	return UploadedImagePath(consts.EntityAlbum, a.UploadedImage)
+}
+
 func (a Album) FullName() string {
 	if conf.Server.Subsonic.AppendAlbumVersion && len(a.Tags[TagAlbumVersion]) > 0 {
 		return fmt.Sprintf("%s (%s)", a.Name, a.Tags[TagAlbumVersion][0])
diff --git a/model/album_test.go b/model/album_test.go
index 0f4c912cd..3413d3859 100644
--- a/model/album_test.go
+++ b/model/album_test.go
@@ -2,6 +2,7 @@ package model_test
 
 import (
 	"encoding/json"
+	"path/filepath"
 
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
@@ -25,6 +26,19 @@ var _ = Describe("Album", func() {
 		Entry("returns just name when tag is absent", true, Tags{}, "Album"),
 		Entry("returns just name when tag is an empty slice", true, Tags{TagAlbumVersion: []string{}}, "Album"),
 	)
+
+	Describe("UploadedImagePath", func() {
+		BeforeEach(func() {
+			conf.Server.DataFolder = conf.NewDir("/data")
+		})
+		It("returns empty when no image was uploaded", func() {
+			Expect(Album{ID: "al-1"}.UploadedImagePath()).To(BeEmpty())
+		})
+		It("returns the path under the data folder when set", func() {
+			a := Album{ID: "al-1", UploadedImage: "al-1_cover.jpg"}
+			Expect(a.UploadedImagePath()).To(Equal(filepath.Join("/data", "artwork", "album", "al-1_cover.jpg")))
+		})
+	})
 })
 
 var _ = Describe("Albums", func() {