backend/src/main/java/org/raddatz/familienarchiv/document/DocumentRepository.java

@@ -50,9 +50,11 @@ public interface DocumentRepository extends JpaRepository<Document, UUID>, JpaSp
     // Prüft effizient, ob ein Dateiname schon existiert (gibt true/false zurück)
     boolean existsByOriginalFilename(String originalFilename);
 
+    // lazy – @BatchSize(50) fallback active; see ADR-022
     @EntityGraph("Document.full")
     List<Document> findBySenderId(UUID senderId);
 
+    // lazy – @BatchSize(50) fallback active; see ADR-022
     @EntityGraph("Document.full")
     List<Document> findByReceiversId(UUID receiverId);
 

backend/src/main/java/org/raddatz/familienarchiv/person/Person.java

@@ -11,6 +11,7 @@ import java.util.ArrayList;
 import java.util.List;
 import java.util.UUID;
 
+// prevents infinite recursion in JSON serialization; see ADR-022 for lazy-fetch context
 @JsonIgnoreProperties({"hibernateLazyInitializer", "handler"})
 @Entity
 @Table(name = "persons")

backend/src/main/java/org/raddatz/familienarchiv/tag/Tag.java

@@ -7,6 +7,7 @@ import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.persistence.*;
 import lombok.*;
 
+// prevents infinite recursion in JSON serialization; see ADR-022 for lazy-fetch context
 @JsonIgnoreProperties({"hibernateLazyInitializer", "handler"})
 @Entity
 @Data

backend/src/test/java/org/raddatz/familienarchiv/document/DocumentLazyLoadingTest.java

@@ -28,6 +28,17 @@ import static org.assertj.core.api.Assertions.assertThatCode;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.when;
 
+/**
+ * Verifies that lazy-loaded associations on {@link Document} are accessible after a service
+ * method returns — i.e. no {@link org.hibernate.LazyInitializationException} is thrown outside
+ * the Hibernate session that loaded the entity.
+ *
+ * <p><b>Known limitation:</b> calling {@code getDocumentById} (or any other service method) from
+ * within an already-open transaction is not covered here. When an outer transaction is active,
+ * the service's own {@code @Transactional} merges into it and Hibernate keeps the same session
+ * open, so the lazy-init guard behaves differently than in a non-transactional caller. This is a
+ * known constraint of the test setup, not a bug in the production code.
+ */
 @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
 @ActiveProfiles("test")
 @Import(PostgresContainerConfig.class)
@@ -100,6 +111,7 @@ class DocumentLazyLoadingTest {
         }).doesNotThrowAnyException();
         results.forEach(d -> assertThat(d.getSender()).isNotNull());
         results.forEach(d -> assertThat(d.getSender().getLastName()).isNotNull());
+        results.forEach(d -> assertThat(d.getTags()).isNotEmpty());
     }
 
     @Test