From b12ff9c808e7c2c509e64015e6ab3e5a78b1a7a6 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Thu, 23 Apr 2026 14:08:49 +0200
Subject: [PATCH] feat(documents): V53 add thumbnail_aspect + page_count
 columns

Adds two nullable metadata columns to documents, populated by
ThumbnailService when it generates the JPEG preview. Both remain null
until the existing admin backfill endpoint reruns the service.

Refs #305

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 ...3__add_thumbnail_aspect_and_page_count.sql |  8 ++++
 .../repository/MigrationIntegrationTest.java  | 45 +++++++++++++++++++
 2 files changed, 53 insertions(+)
 create mode 100644 backend/src/main/resources/db/migration/V53__add_thumbnail_aspect_and_page_count.sql

diff --git a/backend/src/main/resources/db/migration/V53__add_thumbnail_aspect_and_page_count.sql b/backend/src/main/resources/db/migration/V53__add_thumbnail_aspect_and_page_count.sql
new file mode 100644
index 00000000..53d39dc2
--- /dev/null
+++ b/backend/src/main/resources/db/migration/V53__add_thumbnail_aspect_and_page_count.sql
@@ -0,0 +1,8 @@
+-- Adds two nullable metadata columns populated by ThumbnailService when it
+-- generates the JPEG preview: thumbnail_aspect (PORTRAIT | LANDSCAPE, from the
+-- source image w/h ratio with threshold 1.1) and page_count (from PDDocument
+-- for PDFs, 1 for image uploads). Both are null until the existing admin
+-- backfill endpoint (/api/admin/generate-thumbnails) reruns the service.
+ALTER TABLE documents
+    ADD COLUMN thumbnail_aspect VARCHAR(16),
+    ADD COLUMN page_count INTEGER;
diff --git a/backend/src/test/java/org/raddatz/familienarchiv/repository/MigrationIntegrationTest.java b/backend/src/test/java/org/raddatz/familienarchiv/repository/MigrationIntegrationTest.java
index b482a0be..e751b85d 100644
--- a/backend/src/test/java/org/raddatz/familienarchiv/repository/MigrationIntegrationTest.java
+++ b/backend/src/test/java/org/raddatz/familienarchiv/repository/MigrationIntegrationTest.java
@@ -302,6 +302,51 @@ class MigrationIntegrationTest {
         ).isInstanceOf(DataIntegrityViolationException.class);
     }
 
+    // ─── V53: add thumbnail_aspect + page_count columns to documents ─────────
+
+    @Test
+    void v53_thumbnailAspectColumn_existsAndIsNullable() {
+        UUID docId = createDocument();
+
+        // Column must exist and accept NULL (freshly-created doc has no thumbnail yet)
+        String aspect = jdbc.queryForObject(
+                "SELECT thumbnail_aspect FROM documents WHERE id = ?", String.class, docId);
+        assertThat(aspect).isNull();
+    }
+
+    @Test
+    void v53_pageCountColumn_existsAndIsNullable() {
+        UUID docId = createDocument();
+
+        Integer pageCount = jdbc.queryForObject(
+                "SELECT page_count FROM documents WHERE id = ?", Integer.class, docId);
+        assertThat(pageCount).isNull();
+    }
+
+    @Test
+    void v53_thumbnailAspectColumn_acceptsPortraitAndLandscape() {
+        UUID docId = createDocument();
+
+        int portraitRows = jdbc.update(
+                "UPDATE documents SET thumbnail_aspect = 'PORTRAIT' WHERE id = ?", docId);
+        assertThat(portraitRows).isEqualTo(1);
+
+        int landscapeRows = jdbc.update(
+                "UPDATE documents SET thumbnail_aspect = 'LANDSCAPE' WHERE id = ?", docId);
+        assertThat(landscapeRows).isEqualTo(1);
+    }
+
+    @Test
+    void v53_pageCountColumn_storesInteger() {
+        UUID docId = createDocument();
+
+        jdbc.update("UPDATE documents SET page_count = 4 WHERE id = ?", docId);
+
+        Integer stored = jdbc.queryForObject(
+                "SELECT page_count FROM documents WHERE id = ?", Integer.class, docId);
+        assertThat(stored).isEqualTo(4);
+    }
+
     // ─── V51: backfill annotation_id on block comments and notifications ─────
 
     @Test