From e21d01e10b71067340ea90b58a99b1701042a45c Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Mon, 13 Apr 2026 10:00:02 +0200
Subject: [PATCH] feat(ocr): add OcrStreamEvent sealed interface with
 Start/Page/Error/Done records

Defines the event types for NDJSON streaming OCR. Uses Java 21 sealed
interface with record subtypes for exhaustive pattern matching in the
consumer.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../service/OcrStreamEvent.java               | 14 +++++
 .../service/OcrStreamEventTest.java           | 51 +++++++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 backend/src/main/java/org/raddatz/familienarchiv/service/OcrStreamEvent.java
 create mode 100644 backend/src/test/java/org/raddatz/familienarchiv/service/OcrStreamEventTest.java

diff --git a/backend/src/main/java/org/raddatz/familienarchiv/service/OcrStreamEvent.java b/backend/src/main/java/org/raddatz/familienarchiv/service/OcrStreamEvent.java
new file mode 100644
index 00000000..aec0e4f1
--- /dev/null
+++ b/backend/src/main/java/org/raddatz/familienarchiv/service/OcrStreamEvent.java
@@ -0,0 +1,14 @@
+package org.raddatz.familienarchiv.service;
+
+import java.util.List;
+
+public sealed interface OcrStreamEvent {
+
+    record Start(int totalPages) implements OcrStreamEvent {}
+
+    record Page(int pageNumber, List<OcrBlockResult> blocks) implements OcrStreamEvent {}
+
+    record Error(int pageNumber, String message) implements OcrStreamEvent {}
+
+    record Done(int totalBlocks, int skippedPages) implements OcrStreamEvent {}
+}
diff --git a/backend/src/test/java/org/raddatz/familienarchiv/service/OcrStreamEventTest.java b/backend/src/test/java/org/raddatz/familienarchiv/service/OcrStreamEventTest.java
new file mode 100644
index 00000000..70dc7866
--- /dev/null
+++ b/backend/src/test/java/org/raddatz/familienarchiv/service/OcrStreamEventTest.java
@@ -0,0 +1,51 @@
+package org.raddatz.familienarchiv.service;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class OcrStreamEventTest {
+
+    @Test
+    void startRecordHoldsTotalPages() {
+        var start = new OcrStreamEvent.Start(5);
+        assertThat(start.totalPages()).isEqualTo(5);
+        assertThat(start).isInstanceOf(OcrStreamEvent.class);
+    }
+
+    @Test
+    void pageRecordHoldsBlocksAndPageNumber() {
+        var block = new OcrBlockResult(0, 0.1, 0.2, 0.8, 0.1, null, "Test");
+        var page = new OcrStreamEvent.Page(0, List.of(block));
+        assertThat(page.pageNumber()).isEqualTo(0);
+        assertThat(page.blocks()).hasSize(1);
+    }
+
+    @Test
+    void errorRecordHoldsPageAndMessage() {
+        var error = new OcrStreamEvent.Error(2, "failed");
+        assertThat(error.pageNumber()).isEqualTo(2);
+        assertThat(error.message()).isEqualTo("failed");
+    }
+
+    @Test
+    void doneRecordHoldsTotalBlocksAndSkippedPages() {
+        var done = new OcrStreamEvent.Done(12, 2);
+        assertThat(done.totalBlocks()).isEqualTo(12);
+        assertThat(done.skippedPages()).isEqualTo(2);
+    }
+
+    @Test
+    void patternMatchingWorksOnSealedInterface() {
+        OcrStreamEvent event = new OcrStreamEvent.Start(3);
+        String result = switch (event) {
+            case OcrStreamEvent.Start s -> "start:" + s.totalPages();
+            case OcrStreamEvent.Page p -> "page:" + p.pageNumber();
+            case OcrStreamEvent.Error e -> "error:" + e.pageNumber();
+            case OcrStreamEvent.Done d -> "done:" + d.totalBlocks();
+        };
+        assertThat(result).isEqualTo("start:3");
+    }
+}