From 24b2dc04607d33c55a1c50506e3017772509346c Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Thu, 23 Apr 2026 20:39:04 +0200
Subject: [PATCH] refactor(thumbnails): pack key + aspect + pageCount into
 ThumbnailResult

persistThumbnailMetadata was a four-arg method signature that mixed
three conceptually related values. Wrapping them in a private
ThumbnailResult record drops the signature to (Document, result),
mirrors the existing SourcePreview record one step earlier in the
pipeline, and keeps generate() reading as a narrative of small
named outputs rather than positional arguments.

Refs #305
Fixes @felixbrandt suggestion 2 from PR review

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../service/ThumbnailService.java             | 20 +++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/backend/src/main/java/org/raddatz/familienarchiv/service/ThumbnailService.java b/backend/src/main/java/org/raddatz/familienarchiv/service/ThumbnailService.java
index 620a36c8..f654b922 100644
--- a/backend/src/main/java/org/raddatz/familienarchiv/service/ThumbnailService.java
+++ b/backend/src/main/java/org/raddatz/familienarchiv/service/ThumbnailService.java
@@ -99,8 +99,9 @@ public class ThumbnailService {
         String thumbnailKey = thumbnailKeyFor(doc.getId());
         if (!uploadToStorage(thumbnailKey, jpeg, doc.getId())) return Outcome.FAILED;
 
-        ThumbnailAspect aspect = aspectOf(preview.image());
-        return persistThumbnailMetadata(doc, thumbnailKey, aspect, preview.pageCount());
+        ThumbnailResult result = new ThumbnailResult(
+                thumbnailKey, aspectOf(preview.image()), preview.pageCount());
+        return persistThumbnailMetadata(doc, result);
     }
 
     private static ThumbnailAspect aspectOf(BufferedImage source) {
@@ -112,6 +113,10 @@ public class ThumbnailService {
     // 1 for image uploads; for PDFs it comes straight from PDDocument.
     private record SourcePreview(BufferedImage image, int pageCount) {}
 
+    // Everything the generate pipeline has already committed to storage and
+    // now wants stamped onto the Document entity in a single save call.
+    private record ThumbnailResult(String key, ThumbnailAspect aspect, int pageCount) {}
+
     private static String thumbnailKeyFor(UUID documentId) {
         return THUMBNAIL_KEY_PREFIX + documentId + THUMBNAIL_KEY_SUFFIX;
     }
@@ -156,13 +161,12 @@ public class ThumbnailService {
         }
     }
 
-    private Outcome persistThumbnailMetadata(Document doc, String thumbnailKey,
-                                             ThumbnailAspect aspect, int pageCount) {
+    private Outcome persistThumbnailMetadata(Document doc, ThumbnailResult result) {
         try {
-            doc.setThumbnailKey(thumbnailKey);
+            doc.setThumbnailKey(result.key());
             doc.setThumbnailGeneratedAt(LocalDateTime.now());
-            doc.setThumbnailAspect(aspect);
-            doc.setPageCount(pageCount);
+            doc.setThumbnailAspect(result.aspect());
+            doc.setPageCount(result.pageCount());
             documentRepository.save(doc);
             return Outcome.SUCCESS;
         } catch (Exception e) {
@@ -172,7 +176,7 @@ public class ThumbnailService {
             // overwrite it cleanly. Logging distinctly so an operator tracking
             // backfill totals can spot the database-side issue.
             log.warn("Thumbnail persist failed for doc={} (orphaned in storage as {}): {}",
-                    doc.getId(), thumbnailKey, e.getMessage());
+                    doc.getId(), result.key(), e.getMessage());
             return Outcome.FAILED;
         }
     }