test(parser): add regression and cross-feature interaction tests

Regression test confirms already-spaced dot names are not double-spaced.
Interaction test confirms // separator works with dot-compressed names.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitea/workflows/ci.yml

@@ -28,6 +28,10 @@ jobs:
         run: npm ci
         working-directory: frontend
 
+      - name: Compile Paraglide i18n
+        run: npx @inlang/paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide
+        working-directory: frontend
+
       - name: Lint
         run: npm run lint
         working-directory: frontend
@@ -67,134 +71,4 @@ jobs:
         run: |
           chmod +x mvnw
           ./mvnw clean test
-        working-directory: backend
+        working-directory: backend
-
-  # ─── E2E Tests ────────────────────────────────────────────────────────────────
-  # Needs: PostgreSQL + MinIO (via docker-compose) + Spring Boot + SvelteKit dev server.
-  # Test data is seeded by DataInitializer on first startup (admin user + e2e profile data).
-  e2e-tests:
-    name: E2E Tests
-    runs-on: ubuntu-latest
-
-    # These env vars are picked up by docker-compose (overrides .env file)
-    env:
-      DOCKER_API_VERSION: "1.43"
-      POSTGRES_USER: archive_user
-      POSTGRES_PASSWORD: ci_db_password
-      POSTGRES_DB: family_archive_db
-      MINIO_ROOT_USER: minio_admin
-      MINIO_ROOT_PASSWORD: ci_minio_password
-      MINIO_DEFAULT_BUCKETS: archive-documents
-      PORT_DB: 5433
-      PORT_MINIO_API: 9100
-      PORT_MINIO_CONSOLE: 9101
-      PORT_BACKEND: 8080
-      PORT_FRONTEND: 3000
-
-    steps:
-      - uses: actions/checkout@v4
-
-      # ── Infrastructure ──────────────────────────────────────────────────────
-      - name: Cleanup leftover containers from previous runs
-        run: docker compose -f docker-compose.yml -f docker-compose.ci.yml down --volumes --remove-orphans || true
-
-      - name: Start DB and MinIO
-        run: docker compose -f docker-compose.yml -f docker-compose.ci.yml up -d db minio create-buckets
-
-      - name: Wait for DB to be ready
-        run: |
-          timeout 30 bash -c \
-            'until docker compose -f docker-compose.yml -f docker-compose.ci.yml exec -T db pg_isready -U archive_user; do sleep 2; done'
-
-      - name: Connect job container to compose network
-        run: docker network connect familienarchiv_archive-net $(cat /etc/hostname)
-
-      # ── Backend ─────────────────────────────────────────────────────────────
-      - uses: actions/setup-java@v4
-        with:
-          java-version: '21'
-          distribution: temurin
-
-      - name: Cache Maven repository
-        uses: actions/cache@v4
-        with:
-          path: ~/.m2/repository
-          key: maven-${{ hashFiles('backend/pom.xml') }}
-          restore-keys: maven-
-
-      - name: Build backend (skip tests — covered by separate Java test job)
-        run: |
-          chmod +x mvnw
-          ./mvnw clean package -DskipTests
-        working-directory: backend
-
-      - name: Start backend
-        run: |
-          java -jar backend/target/*.jar \
-            --spring.profiles.active=e2e \
-            --SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/family_archive_db \
-            --SPRING_DATASOURCE_USERNAME=archive_user \
-            --SPRING_DATASOURCE_PASSWORD=ci_db_password \
-            --S3_ENDPOINT=http://minio:9000 \
-            --S3_ACCESS_KEY=minio_admin \
-            --S3_SECRET_KEY=ci_minio_password \
-            --S3_BUCKET_NAME=archive-documents \
-            --S3_REGION=us-east-1 \
-            --APP_ADMIN_USERNAME=admin \
-            --APP_ADMIN_PASSWORD=admin123 \
-            &
-          echo "Waiting for backend..."
-          timeout 90 bash -c \
-            'until curl -sf http://localhost:8080/actuator/health | grep -q "UP"; do sleep 3; done'
-          echo "Backend is up."
-
-      # ── Frontend ─────────────────────────────────────────────────────────────
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: Cache node_modules
-        id: node-modules-cache
-        uses: actions/cache@v4
-        with:
-          path: frontend/node_modules
-          key: node-modules-${{ hashFiles('frontend/package-lock.json') }}
-
-      - name: Install frontend dependencies
-        if: steps.node-modules-cache.outputs.cache-hit != 'true'
-        run: npm ci
-        working-directory: frontend
-
-      - name: Cache Playwright browsers
-        id: playwright-cache
-        uses: actions/cache@v4
-        with:
-          path: ~/.cache/ms-playwright
-          key: playwright-chromium-${{ hashFiles('frontend/package-lock.json') }}
-
-      - name: Install Playwright Chromium + system deps
-        if: steps.playwright-cache.outputs.cache-hit != 'true'
-        run: npx playwright install chromium --with-deps
-        working-directory: frontend
-
-      - name: Install Playwright system deps (browser binary already cached)
-        if: steps.playwright-cache.outputs.cache-hit == 'true'
-        run: npx playwright install-deps chromium
-        working-directory: frontend
-
-      # ── Tests ────────────────────────────────────────────────────────────────
-      - name: Run E2E tests
-        run: npm run test:e2e
-        working-directory: frontend
-        env:
-          E2E_BASE_URL: http://localhost:3000
-          E2E_USERNAME: admin
-          E2E_PASSWORD: admin123
-          E2E_BACKEND_URL: http://localhost:8080
-
-      - name: Upload E2E results
-        if: always()
-        uses: actions/upload-artifact@v3
-        with:
-          name: e2e-results
-          path: frontend/test-results/e2e/

backend/pom.xml

@@ -34,6 +34,10 @@
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-actuator</artifactId>
 		</dependency>
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-validation</artifactId>
+		</dependency>
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-data-jpa</artifactId>
@@ -65,6 +69,16 @@
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-jetty</artifactId>
 		</dependency>
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-testcontainers</artifactId>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>org.testcontainers</groupId>
+			<artifactId>testcontainers-postgresql</artifactId>
+			<scope>test</scope>
+		</dependency>
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-actuator-test</artifactId>
@@ -161,6 +175,50 @@
 
 	<build>
 		<plugins>
+			<plugin>
+				<groupId>org.jacoco</groupId>
+				<artifactId>jacoco-maven-plugin</artifactId>
+				<version>0.8.12</version>
+				<configuration>
+					<excludes>
+						<exclude>**/dto/**</exclude>
+						<exclude>**/config/**</exclude>
+						<exclude>**/exception/ErrorCode*</exclude>
+						<exclude>**/model/**</exclude>
+					</excludes>
+				</configuration>
+				<executions>
+					<execution>
+						<id>prepare-agent</id>
+						<goals><goal>prepare-agent</goal></goals>
+					</execution>
+					<execution>
+						<id>report</id>
+						<phase>verify</phase>
+						<goals><goal>report</goal></goals>
+					</execution>
+					<!-- Gate: baseline 89.4% overall / service 90.2% / controller 80.0% -->
+					<execution>
+						<id>check</id>
+						<phase>verify</phase>
+						<goals><goal>check</goal></goals>
+						<configuration>
+							<rules>
+								<rule>
+									<element>BUNDLE</element>
+									<limits>
+										<limit>
+											<counter>BRANCH</counter>
+											<value>COVEREDRATIO</value>
+											<minimum>0.88</minimum>
+										</limit>
+									</limits>
+								</rule>
+							</rules>
+						</configuration>
+					</execution>
+				</executions>
+			</plugin>
 			<plugin>
 				<groupId>org.springframework.boot</groupId>
 				<artifactId>spring-boot-maven-plugin</artifactId>

backend/src/main/java/org/raddatz/familienarchiv/config/DataInitializer.java

@@ -84,6 +84,14 @@ public class DataInitializer {
             TagRepository tagRepo,
             PasswordEncoder passwordEncoder) {
         return args -> {
+            // Always reset the admin password to the configured value so a failed password-reset
+            // test from a previous run can never leave the account locked out.
+            userRepository.findByUsername(adminUsername).ifPresent(admin -> {
+                admin.setPassword(passwordEncoder.encode(adminPassword));
+                userRepository.save(admin);
+                log.info("E2E seed: Admin-Passwort auf konfigurierten Wert zurückgesetzt.");
+            });
+
             // Always ensure the read-only test user exists, even when seed data was already loaded.
             if (userRepository.findByUsername("reader").isEmpty()) {
                 log.info("E2E seed: Erstelle 'reader'-Testbenutzer...");

backend/src/main/java/org/raddatz/familienarchiv/controller/AdminController.java

@@ -41,4 +41,10 @@ public class AdminController {
                 documentService.getDocumentsWithoutVersions());
         return ResponseEntity.ok(new BackfillResult(count));
     }
+
+    @PostMapping("/backfill-file-hashes")
+    public ResponseEntity<BackfillResult> backfillFileHashes() {
+        int count = documentService.backfillFileHashes();
+        return ResponseEntity.ok(new BackfillResult(count));
+    }
 }

backend/src/main/java/org/raddatz/familienarchiv/controller/AnnotationController.java

@@ -4,10 +4,12 @@ import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.raddatz.familienarchiv.dto.CreateAnnotationDTO;
 import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.Document;
 import org.raddatz.familienarchiv.model.DocumentAnnotation;
 import org.raddatz.familienarchiv.security.Permission;
 import org.raddatz.familienarchiv.security.RequirePermission;
 import org.raddatz.familienarchiv.service.AnnotationService;
+import org.raddatz.familienarchiv.service.DocumentService;
 import org.raddatz.familienarchiv.service.UserService;
 import org.springframework.http.HttpStatus;
 import org.springframework.security.core.Authentication;
@@ -23,6 +25,7 @@ import java.util.UUID;
 public class AnnotationController {
 
     private final AnnotationService annotationService;
+    private final DocumentService documentService;
     private final UserService userService;
 
     @GetMapping
@@ -32,18 +35,19 @@ public class AnnotationController {
 
     @PostMapping
     @ResponseStatus(HttpStatus.CREATED)
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public DocumentAnnotation createAnnotation(
             @PathVariable UUID documentId,
             @RequestBody CreateAnnotationDTO dto,
             Authentication authentication) {
         UUID userId = resolveUserId(authentication);
-        return annotationService.createAnnotation(documentId, dto, userId);
+        Document doc = documentService.getDocumentById(documentId);
+        return annotationService.createAnnotation(documentId, dto, userId, doc.getFileHash());
     }
 
     @DeleteMapping("/{annotationId}")
     @ResponseStatus(HttpStatus.NO_CONTENT)
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public void deleteAnnotation(
             @PathVariable UUID documentId,
             @PathVariable UUID annotationId,

backend/src/main/java/org/raddatz/familienarchiv/controller/AuthE2EController.java

@@ -10,6 +10,8 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+import io.swagger.v3.oas.annotations.Operation;
+
 import lombok.RequiredArgsConstructor;
 
 /**
@@ -24,6 +26,9 @@ public class AuthE2EController {
 
     private final PasswordResetTokenRepository tokenRepository;
 
+    // Hidden from the OpenAPI spec — this endpoint must never appear in the generated api.ts
+    // even when the e2e profile is active alongside the dev profile during spec generation.
+    @Operation(hidden = true)
     @GetMapping("/reset-token-for-test")
     public ResponseEntity<String> getResetTokenForTest(@RequestParam String email) {
         return tokenRepository.findLatestActiveTokenByEmail(email, LocalDateTime.now())

backend/src/main/java/org/raddatz/familienarchiv/controller/CommentController.java

@@ -33,25 +33,25 @@ public class CommentController {
 
     @PostMapping("/api/documents/{documentId}/comments")
     @ResponseStatus(HttpStatus.CREATED)
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public DocumentComment postDocumentComment(
             @PathVariable UUID documentId,
             @RequestBody CreateCommentDTO dto,
             Authentication authentication) {
         AppUser author = resolveUser(authentication);
-        return commentService.postComment(documentId, null, dto.getContent(), author);
+        return commentService.postComment(documentId, null, dto.getContent(), dto.getMentionedUserIds(), author);
     }
 
     @PostMapping("/api/documents/{documentId}/comments/{commentId}/replies")
     @ResponseStatus(HttpStatus.CREATED)
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public DocumentComment replyToDocumentComment(
             @PathVariable UUID documentId,
             @PathVariable UUID commentId,
             @RequestBody CreateCommentDTO dto,
             Authentication authentication) {
         AppUser author = resolveUser(authentication);
-        return commentService.replyToComment(documentId, commentId, dto.getContent(), author);
+        return commentService.replyToComment(documentId, commentId, dto.getContent(), dto.getMentionedUserIds(), author);
     }
 
     // ─── Annotation comments ──────────────────────────────────────────────────
@@ -63,32 +63,63 @@ public class CommentController {
 
     @PostMapping("/api/documents/{documentId}/annotations/{annotationId}/comments")
     @ResponseStatus(HttpStatus.CREATED)
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public DocumentComment postAnnotationComment(
             @PathVariable UUID documentId,
             @PathVariable UUID annotationId,
             @RequestBody CreateCommentDTO dto,
             Authentication authentication) {
         AppUser author = resolveUser(authentication);
-        return commentService.postComment(documentId, annotationId, dto.getContent(), author);
+        return commentService.postComment(documentId, annotationId, dto.getContent(), dto.getMentionedUserIds(), author);
     }
 
     @PostMapping("/api/documents/{documentId}/annotations/{annotationId}/comments/{commentId}/replies")
     @ResponseStatus(HttpStatus.CREATED)
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public DocumentComment replyToAnnotationComment(
             @PathVariable UUID documentId,
             @PathVariable UUID commentId,
             @RequestBody CreateCommentDTO dto,
             Authentication authentication) {
         AppUser author = resolveUser(authentication);
-        return commentService.replyToComment(documentId, commentId, dto.getContent(), author);
+        return commentService.replyToComment(documentId, commentId, dto.getContent(), dto.getMentionedUserIds(), author);
+    }
+
+    // ─── Block (transcription) comments ────────────────────────────────────────
+
+    @GetMapping("/api/documents/{documentId}/transcription-blocks/{blockId}/comments")
+    public List<DocumentComment> getBlockComments(@PathVariable UUID blockId) {
+        return commentService.getCommentsForBlock(blockId);
+    }
+
+    @PostMapping("/api/documents/{documentId}/transcription-blocks/{blockId}/comments")
+    @ResponseStatus(HttpStatus.CREATED)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
+    public DocumentComment postBlockComment(
+            @PathVariable UUID documentId,
+            @PathVariable UUID blockId,
+            @RequestBody CreateCommentDTO dto,
+            Authentication authentication) {
+        AppUser author = resolveUser(authentication);
+        return commentService.postBlockComment(documentId, blockId, dto.getContent(), dto.getMentionedUserIds(), author);
+    }
+
+    @PostMapping("/api/documents/{documentId}/transcription-blocks/{blockId}/comments/{commentId}/replies")
+    @ResponseStatus(HttpStatus.CREATED)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
+    public DocumentComment replyToBlockComment(
+            @PathVariable UUID documentId,
+            @PathVariable UUID commentId,
+            @RequestBody CreateCommentDTO dto,
+            Authentication authentication) {
+        AppUser author = resolveUser(authentication);
+        return commentService.replyToComment(documentId, commentId, dto.getContent(), dto.getMentionedUserIds(), author);
     }
 
     // ─── Edit and delete (shared) ─────────────────────────────────────────────
 
     @PatchMapping("/api/documents/{documentId}/comments/{commentId}")
-    @RequirePermission(Permission.ANNOTATE_ALL)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
     public DocumentComment editComment(
             @PathVariable UUID documentId,
             @PathVariable UUID commentId,

backend/src/main/java/org/raddatz/familienarchiv/controller/DocumentController.java

@@ -2,16 +2,25 @@ package org.raddatz.familienarchiv.controller;
 
 import java.io.IOException;
 import java.time.LocalDate;
+import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
 import java.util.UUID;
 
 
 
+import io.swagger.v3.oas.annotations.Parameter;
+import org.raddatz.familienarchiv.dto.DocumentSearchResult;
 import org.raddatz.familienarchiv.dto.DocumentUpdateDTO;
 import org.raddatz.familienarchiv.dto.DocumentVersionSummary;
+import org.raddatz.familienarchiv.dto.IncompleteDocumentDTO;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
 import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.dto.DocumentSort;
+import org.raddatz.familienarchiv.model.DocumentStatus;
 import org.raddatz.familienarchiv.model.DocumentVersion;
 import org.raddatz.familienarchiv.security.Permission;
 import org.raddatz.familienarchiv.security.RequirePermission;
@@ -23,6 +32,7 @@ import org.springframework.http.HttpHeaders;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.core.io.InputStreamResource;
+import org.springframework.web.bind.annotation.DeleteMapping;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.ModelAttribute;
 import org.springframework.web.bind.annotation.PathVariable;
@@ -31,6 +41,8 @@ import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RequestPart;
+import org.springframework.web.server.ResponseStatusException;
+import org.springframework.http.HttpStatus;
 import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
@@ -103,15 +115,97 @@ public class DocumentController {
         }
     }
 
+    // --- DELETE ---
+
+    @DeleteMapping("/{id}")
+    @RequirePermission(Permission.WRITE_ALL)
+    public ResponseEntity<Void> deleteDocument(@PathVariable UUID id) {
+        documentService.deleteDocument(id);
+        return ResponseEntity.noContent().build();
+    }
+
+    // --- QUICK UPLOAD ---
+
+    private static final Set<String> ALLOWED_CONTENT_TYPES = Set.of(
+            "application/pdf", "image/jpeg", "image/png", "image/tiff");
+
+    public record UploadError(String filename, String code) {}
+    public record QuickUploadResult(List<Document> created, List<Document> updated, List<UploadError> errors) {}
+
+    @PostMapping(value = "/quick-upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @RequirePermission(Permission.WRITE_ALL)
+    public QuickUploadResult quickUpload(
+            @RequestPart(value = "files", required = false) List<MultipartFile> files) {
+        List<Document> created = new ArrayList<>();
+        List<Document> updated = new ArrayList<>();
+        List<UploadError> errors = new ArrayList<>();
+
+        if (files == null || files.isEmpty()) {
+            return new QuickUploadResult(created, updated, errors);
+        }
+
+        for (MultipartFile file : files) {
+            if (!ALLOWED_CONTENT_TYPES.contains(file.getContentType())) {
+                errors.add(new UploadError(file.getOriginalFilename(), "UNSUPPORTED_FILE_TYPE"));
+                continue;
+            }
+            try {
+                DocumentService.StoreResult result = documentService.storeDocument(file);
+                if (result.isNew()) {
+                    created.add(result.document());
+                } else {
+                    updated.add(result.document());
+                }
+            } catch (Exception e) {
+                errors.add(new UploadError(file.getOriginalFilename(), "FILE_UPLOAD_FAILED"));
+                log.warn("Quick upload failed for file {}: {}", file.getOriginalFilename(), e.getMessage());
+            }
+        }
+
+        return new QuickUploadResult(created, updated, errors);
+    }
+
+    @GetMapping("/incomplete-count")
+    public Map<String, Long> getIncompleteCount() {
+        return Map.of("count", documentService.getIncompleteCount());
+    }
+
+    @GetMapping("/incomplete")
+    public List<IncompleteDocumentDTO> getIncomplete(
+            @Parameter(description = "Maximum number of results") @RequestParam(defaultValue = "10") int size) {
+        return documentService.findIncompleteDocuments(size);
+    }
+
+    @GetMapping("/incomplete/next")
+    public ResponseEntity<Document> getNextIncomplete(@RequestParam UUID excludeId) {
+        return documentService.findNextIncompleteDocument(excludeId)
+                .map(ResponseEntity::ok)
+                .orElse(ResponseEntity.noContent().build());
+    }
+
+    @GetMapping("/recent-activity")
+    public ResponseEntity<List<Document>> getRecentActivity(
+            @RequestParam(defaultValue = "5") int size) {
+        return ResponseEntity.ok(documentService.getRecentActivity(size));
+    }
+
     @GetMapping("/search")
-    public ResponseEntity<List<Document>> search(
+    public ResponseEntity<DocumentSearchResult> search(
             @RequestParam(required = false) String q,
             @RequestParam(required = false) LocalDate from,
             @RequestParam(required = false) LocalDate to,
             @RequestParam(required = false) UUID senderId,
             @RequestParam(required = false) UUID receiverId,
-            @RequestParam(required = false, name = "tag") List<String> tags) {
+            @RequestParam(required = false, name = "tag") List<String> tags,
-        return ResponseEntity.ok(documentService.searchDocuments(q, from, to, senderId, receiverId, tags));
+            @RequestParam(required = false) String tagQ,
+            @Parameter(description = "Filter by document status") @RequestParam(required = false) DocumentStatus status,
+            @Parameter(description = "Sort field") @RequestParam(required = false) DocumentSort sort,
+            @Parameter(description = "Sort direction: ASC or DESC") @RequestParam(required = false, defaultValue = "DESC") String dir) {
+        if (!"ASC".equalsIgnoreCase(dir) && !"DESC".equalsIgnoreCase(dir)) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "dir must be ASC or DESC");
+        }
+        List<Document> results = documentService.searchDocuments(q, from, to, senderId, receiverId, tags, tagQ, status, sort, dir);
+        return ResponseEntity.ok(DocumentSearchResult.of(results));
     }
 
     // --- VERSIONS ---
@@ -129,7 +223,7 @@ public class DocumentController {
     @GetMapping("/conversation")
     public List<Document> getConversation(
             @RequestParam UUID senderId,
-            @RequestParam UUID receiverId,
+            @RequestParam(required = false) UUID receiverId,
             @RequestParam(required = false) LocalDate from,
             @RequestParam(required = false) LocalDate to,
             @RequestParam(defaultValue = "DESC") String dir) {

backend/src/main/java/org/raddatz/familienarchiv/controller/GlobalExceptionHandler.java

@@ -2,12 +2,15 @@ package org.raddatz.familienarchiv.controller;
 
 import java.util.stream.Collectors;
 
+import jakarta.validation.ConstraintViolationException;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.MethodArgumentNotValidException;
 import org.springframework.web.bind.annotation.ExceptionHandler;
 import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
+import org.springframework.web.server.ResponseStatusException;
 
 import lombok.extern.slf4j.Slf4j;
 
@@ -30,6 +33,26 @@ public class GlobalExceptionHandler {
         return ResponseEntity.badRequest().body(new ErrorResponse(ErrorCode.VALIDATION_ERROR, message));
     }
 
+    @ExceptionHandler(ConstraintViolationException.class)
+    public ResponseEntity<ErrorResponse> handleConstraintViolation(ConstraintViolationException ex) {
+        String message = ex.getConstraintViolations().stream()
+                .map(v -> v.getPropertyPath() + ": " + v.getMessage())
+                .collect(Collectors.joining(", "));
+        return ResponseEntity.badRequest().body(new ErrorResponse(ErrorCode.VALIDATION_ERROR, message));
+    }
+
+    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
+    public ResponseEntity<ErrorResponse> handleTypeMismatch(MethodArgumentTypeMismatchException ex) {
+        String message = "Invalid value '" + ex.getValue() + "' for parameter '" + ex.getName() + "'";
+        return ResponseEntity.badRequest().body(new ErrorResponse(ErrorCode.VALIDATION_ERROR, message));
+    }
+
+    @ExceptionHandler(ResponseStatusException.class)
+    public ResponseEntity<ErrorResponse> handleResponseStatus(ResponseStatusException ex) {
+        return ResponseEntity.status(ex.getStatusCode())
+                .body(new ErrorResponse(ErrorCode.VALIDATION_ERROR, ex.getReason()));
+    }
+
     @ExceptionHandler(Exception.class)
     public ResponseEntity<ErrorResponse> handleGeneric(Exception ex) {
         log.error("Unhandled exception", ex);

backend/src/main/java/org/raddatz/familienarchiv/controller/NotificationController.java

@@ -0,0 +1,105 @@
+package org.raddatz.familienarchiv.controller;
+
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import lombok.RequiredArgsConstructor;
+import io.swagger.v3.oas.annotations.Parameter;
+import org.raddatz.familienarchiv.dto.NotificationDTO;
+import org.raddatz.familienarchiv.dto.NotificationPreferenceDTO;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.NotificationType;
+import org.raddatz.familienarchiv.security.Permission;
+import org.raddatz.familienarchiv.security.RequirePermission;
+import org.raddatz.familienarchiv.service.NotificationService;
+import org.raddatz.familienarchiv.service.SseEmitterRegistry;
+import org.raddatz.familienarchiv.service.UserService;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.data.domain.Sort;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.security.core.Authentication;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
+
+import java.util.Map;
+
+import java.util.UUID;
+
+@RestController
+@RequiredArgsConstructor
+@Validated
+public class NotificationController {
+
+    private final NotificationService notificationService;
+    private final UserService userService;
+    private final SseEmitterRegistry sseEmitterRegistry;
+
+    // These endpoints are intentionally open to any authenticated user —
+    // they return and mutate only the current user's own notifications, scoped
+    // by the resolved user identity. No additional permission check is required.
+
+    @GetMapping(value = "/api/notifications/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
+    public SseEmitter stream(Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        return sseEmitterRegistry.register(user.getId());
+    }
+
+    @GetMapping("/api/notifications")
+    public Page<NotificationDTO> getNotifications(
+            @RequestParam(defaultValue = "0") int page,
+            @RequestParam(defaultValue = "10") @Min(1) @Max(100) int size,
+            @Parameter(description = "Filter by notification type") @RequestParam(required = false) NotificationType type,
+            @Parameter(description = "Filter by read status") @RequestParam(required = false) Boolean read,
+            Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        PageRequest pageable = PageRequest.of(page, size, Sort.by("createdAt").descending());
+        return notificationService.getNotifications(user.getId(), type, read, pageable);
+    }
+
+    @GetMapping("/api/notifications/unread-count")
+    public Map<String, Long> countUnread(Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        return Map.of("count", notificationService.countUnread(user.getId()));
+    }
+
+    @PostMapping("/api/notifications/read-all")
+    @ResponseStatus(HttpStatus.NO_CONTENT)
+    public void markAllRead(Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        notificationService.markAllRead(user.getId());
+    }
+
+    @PatchMapping("/api/notifications/{id}/read")
+    public NotificationDTO markOneRead(
+            @PathVariable UUID id,
+            Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        return notificationService.markRead(id, user.getId());
+    }
+
+    @GetMapping("/api/users/me/notification-preferences")
+    @RequirePermission({Permission.READ_ALL, Permission.WRITE_ALL, Permission.ANNOTATE_ALL})
+    public NotificationPreferenceDTO getPreferences(Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        return new NotificationPreferenceDTO(user.isNotifyOnReply(), user.isNotifyOnMention());
+    }
+
+    @PutMapping("/api/users/me/notification-preferences")
+    @RequirePermission({Permission.READ_ALL, Permission.WRITE_ALL, Permission.ANNOTATE_ALL})
+    public NotificationPreferenceDTO updatePreferences(
+            @RequestBody NotificationPreferenceDTO dto,
+            Authentication authentication) {
+        AppUser user = resolveUser(authentication);
+        AppUser updated = notificationService.updatePreferences(
+                user.getId(), dto.notifyOnReply(), dto.notifyOnMention());
+        return new NotificationPreferenceDTO(updated.isNotifyOnReply(), updated.isNotifyOnMention());
+    }
+
+    // ─── private helpers ──────────────────────────────────────────────────────
+
+    private AppUser resolveUser(Authentication authentication) {
+        return userService.findByUsername(authentication.getName());
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/controller/PersonController.java

@@ -4,16 +4,25 @@ import java.util.List;
 import java.util.Map;
 import java.util.UUID;
 
+
+import org.raddatz.familienarchiv.dto.PersonNameAliasDTO;
+import org.raddatz.familienarchiv.dto.PersonSummaryDTO;
 import org.raddatz.familienarchiv.dto.PersonUpdateDTO;
 import org.raddatz.familienarchiv.model.Document;
 import org.raddatz.familienarchiv.model.Person;
+import org.raddatz.familienarchiv.model.PersonNameAlias;
+import org.raddatz.familienarchiv.security.Permission;
+import org.raddatz.familienarchiv.security.RequirePermission;
 import org.raddatz.familienarchiv.service.DocumentService;
 import org.raddatz.familienarchiv.service.PersonService;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
+import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 import org.springframework.web.server.ResponseStatusException;
 
+import jakarta.validation.Valid;
+
 import lombok.RequiredArgsConstructor;
 
 @RestController
@@ -25,7 +34,7 @@ public class PersonController {
     private final DocumentService documentService;
 
     @GetMapping
-    public ResponseEntity<List<Person>> getPersons(@RequestParam(required = false) String q) {
+    public ResponseEntity<List<PersonSummaryDTO>> getPersons(@RequestParam(required = false) String q) {
         return ResponseEntity.ok(personService.findAll(q));
     }
 
@@ -52,17 +61,20 @@ public class PersonController {
     }
 
     @PostMapping
-    public ResponseEntity<Person> createPerson(@RequestBody Map<String, String> body) {
+    @RequirePermission(Permission.WRITE_ALL)
-        String firstName = body.get("firstName");
+    public ResponseEntity<Person> createPerson(@Valid @RequestBody PersonUpdateDTO dto) {
-        String lastName = body.get("lastName");
+        if (dto.getFirstName() == null || dto.getFirstName().isBlank()
-        if (firstName == null || firstName.isBlank() || lastName == null || lastName.isBlank()) {
+                || dto.getLastName() == null || dto.getLastName().isBlank()) {
             throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Vor- und Nachname sind Pflichtfelder");
         }
-        return ResponseEntity.ok(personService.createPerson(firstName.trim(), lastName.trim(), body.get("alias")));
+        dto.setFirstName(dto.getFirstName().trim());
+        dto.setLastName(dto.getLastName().trim());
+        return ResponseEntity.ok(personService.createPerson(dto));
     }
 
     @PutMapping("/{id}")
-    public ResponseEntity<Person> updatePerson(@PathVariable UUID id, @RequestBody PersonUpdateDTO dto) {
+    @RequirePermission(Permission.WRITE_ALL)
+    public ResponseEntity<Person> updatePerson(@PathVariable UUID id, @Valid @RequestBody PersonUpdateDTO dto) {
         if (dto.getFirstName() == null || dto.getFirstName().isBlank()
                 || dto.getLastName() == null || dto.getLastName().isBlank()) {
             throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Vor- und Nachname sind Pflichtfelder");
@@ -74,6 +86,7 @@ public class PersonController {
 
     @PostMapping("/{id}/merge")
     @ResponseStatus(HttpStatus.NO_CONTENT)
+    @RequirePermission(Permission.WRITE_ALL)
     public void mergePerson(@PathVariable UUID id, @RequestBody Map<String, String> body) {
         String targetIdStr = body.get("targetPersonId");
         if (targetIdStr == null || targetIdStr.isBlank()) {
@@ -81,4 +94,24 @@ public class PersonController {
         }
         personService.mergePersons(id, UUID.fromString(targetIdStr));
     }
+
+    // ─── Alias endpoints ────────────────────────────────────────────────────
+
+    @GetMapping("/{id}/aliases")
+    public List<PersonNameAlias> getAliases(@PathVariable UUID id) {
+        return personService.getAliases(id);
+    }
+
+    @PostMapping("/{id}/aliases")
+    @RequirePermission(Permission.WRITE_ALL)
+    public PersonNameAlias addAlias(@PathVariable UUID id, @Valid @RequestBody PersonNameAliasDTO dto) {
+        return personService.addAlias(id, dto);
+    }
+
+    @DeleteMapping("/{id}/aliases/{aliasId}")
+    @ResponseStatus(HttpStatus.NO_CONTENT)
+    @RequirePermission(Permission.WRITE_ALL)
+    public void removeAlias(@PathVariable UUID id, @PathVariable UUID aliasId) {
+        personService.removeAlias(id, aliasId);
+    }
 }

backend/src/main/java/org/raddatz/familienarchiv/controller/StatsController.java

@@ -0,0 +1,25 @@
+package org.raddatz.familienarchiv.controller;
+
+import org.raddatz.familienarchiv.dto.StatsDTO;
+import org.raddatz.familienarchiv.repository.DocumentRepository;
+import org.raddatz.familienarchiv.repository.PersonRepository;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import lombok.RequiredArgsConstructor;
+
+@RestController
+@RequestMapping("/api/stats")
+@RequiredArgsConstructor
+public class StatsController {
+
+    private final PersonRepository personRepository;
+    private final DocumentRepository documentRepository;
+
+    @GetMapping
+    public ResponseEntity<StatsDTO> getStats() {
+        return ResponseEntity.ok(new StatsDTO(personRepository.count(), documentRepository.count()));
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/controller/TranscriptionBlockController.java

@@ -0,0 +1,102 @@
+package org.raddatz.familienarchiv.controller;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.raddatz.familienarchiv.dto.CreateTranscriptionBlockDTO;
+import org.raddatz.familienarchiv.dto.ReorderTranscriptionBlocksDTO;
+import org.raddatz.familienarchiv.dto.UpdateTranscriptionBlockDTO;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.TranscriptionBlock;
+import org.raddatz.familienarchiv.model.TranscriptionBlockVersion;
+import org.raddatz.familienarchiv.security.Permission;
+import org.raddatz.familienarchiv.security.RequirePermission;
+import org.raddatz.familienarchiv.service.TranscriptionService;
+import org.raddatz.familienarchiv.service.UserService;
+import org.springframework.http.HttpStatus;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+import java.util.UUID;
+
+@RestController
+@RequestMapping("/api/documents/{documentId}/transcription-blocks")
+@RequiredArgsConstructor
+@Slf4j
+public class TranscriptionBlockController {
+
+    private final TranscriptionService transcriptionService;
+    private final UserService userService;
+
+    @GetMapping
+    @RequirePermission(Permission.READ_ALL)
+    public List<TranscriptionBlock> listBlocks(@PathVariable UUID documentId) {
+        return transcriptionService.listBlocks(documentId);
+    }
+
+    @GetMapping("/{blockId}")
+    @RequirePermission(Permission.READ_ALL)
+    public TranscriptionBlock getBlock(@PathVariable UUID documentId, @PathVariable UUID blockId) {
+        return transcriptionService.getBlock(documentId, blockId);
+    }
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    @RequirePermission(Permission.WRITE_ALL)
+    public TranscriptionBlock createBlock(
+            @PathVariable UUID documentId,
+            @RequestBody CreateTranscriptionBlockDTO dto,
+            Authentication authentication) {
+        UUID userId = requireUserId(authentication);
+        return transcriptionService.createBlock(documentId, dto, userId);
+    }
+
+    @PutMapping("/{blockId}")
+    @RequirePermission(Permission.WRITE_ALL)
+    public TranscriptionBlock updateBlock(
+            @PathVariable UUID documentId,
+            @PathVariable UUID blockId,
+            @RequestBody UpdateTranscriptionBlockDTO dto,
+            Authentication authentication) {
+        UUID userId = requireUserId(authentication);
+        return transcriptionService.updateBlock(documentId, blockId, dto, userId);
+    }
+
+    @DeleteMapping("/{blockId}")
+    @ResponseStatus(HttpStatus.NO_CONTENT)
+    @RequirePermission(Permission.WRITE_ALL)
+    public void deleteBlock(
+            @PathVariable UUID documentId,
+            @PathVariable UUID blockId) {
+        transcriptionService.deleteBlock(documentId, blockId);
+    }
+
+    @PutMapping("/reorder")
+    @RequirePermission(Permission.WRITE_ALL)
+    public List<TranscriptionBlock> reorderBlocks(
+            @PathVariable UUID documentId,
+            @RequestBody ReorderTranscriptionBlocksDTO dto) {
+        transcriptionService.reorderBlocks(documentId, dto);
+        return transcriptionService.listBlocks(documentId);
+    }
+
+    @GetMapping("/{blockId}/history")
+    @RequirePermission(Permission.READ_ALL)
+    public List<TranscriptionBlockVersion> getBlockHistory(
+            @PathVariable UUID documentId,
+            @PathVariable UUID blockId) {
+        return transcriptionService.getBlockHistory(documentId, blockId);
+    }
+
+    private UUID requireUserId(Authentication authentication) {
+        if (authentication == null || !authentication.isAuthenticated()) {
+            throw DomainException.unauthorized("Authentication required");
+        }
+        AppUser user = userService.findByUsername(authentication.getName());
+        if (user == null) {
+            throw DomainException.unauthorized("User not found");
+        }
+        return user.getId();
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/controller/UserController.java

@@ -61,6 +61,7 @@ public class UserController {
     }
 
     @GetMapping("users/{id}")
+    @RequirePermission(Permission.ADMIN_USER)
     public ResponseEntity<AppUser> getUser(@PathVariable UUID id) {
         AppUser user = userService.getById(id);
         user.setPassword(null);

backend/src/main/java/org/raddatz/familienarchiv/controller/UserSearchController.java

@@ -0,0 +1,32 @@
+package org.raddatz.familienarchiv.controller;
+
+import lombok.RequiredArgsConstructor;
+import org.raddatz.familienarchiv.dto.MentionDTO;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.security.Permission;
+import org.raddatz.familienarchiv.security.RequirePermission;
+import org.raddatz.familienarchiv.service.UserSearchService;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+@RestController
+@RequiredArgsConstructor
+@RequirePermission({Permission.READ_ALL, Permission.WRITE_ALL, Permission.ANNOTATE_ALL})
+public class UserSearchController {
+
+    private final UserSearchService userSearchService;
+
+    @GetMapping("/api/users/search")
+    public List<MentionDTO> search(@RequestParam(defaultValue = "") String q) {
+        return userSearchService.search(q).stream()
+                .map(this::toMentionDTO)
+                .toList();
+    }
+
+    private MentionDTO toMentionDTO(AppUser user) {
+        return new MentionDTO(user.getId(), user.getFirstName(), user.getLastName());
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/dto/CreateCommentDTO.java

@@ -2,7 +2,12 @@ package org.raddatz.familienarchiv.dto;
 
 import lombok.Data;
 
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
 @Data
 public class CreateCommentDTO {
     private String content;
+    private List<UUID> mentionedUserIds = new ArrayList<>();
 }

backend/src/main/java/org/raddatz/familienarchiv/dto/CreateTranscriptionBlockDTO.java

@@ -0,0 +1,25 @@
+package org.raddatz.familienarchiv.dto;
+
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.Positive;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class CreateTranscriptionBlockDTO {
+    @Min(0)
+    private int pageNumber;
+    @Min(0)
+    private double x;
+    @Min(0)
+    private double y;
+    @Positive
+    private double width;
+    @Positive
+    private double height;
+    private String text;
+    private String label;
+}

backend/src/main/java/org/raddatz/familienarchiv/dto/DocumentSearchResult.java

@@ -0,0 +1,16 @@
+package org.raddatz.familienarchiv.dto;
+
+import org.raddatz.familienarchiv.model.Document;
+
+import java.util.List;
+
+public record DocumentSearchResult(List<Document> documents, long total) {
+    /**
+     * Creates a result where total equals the list size.
+     * No pagination yet — the full matched set is always returned.
+     * When pagination is added, total must come from a DB COUNT query, not list.size().
+     */
+    public static DocumentSearchResult of(List<Document> documents) {
+        return new DocumentSearchResult(documents, documents.size());
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/dto/DocumentSort.java

@@ -0,0 +1,5 @@
+package org.raddatz.familienarchiv.dto;
+
+public enum DocumentSort {
+    DATE, TITLE, SENDER, RECEIVER, UPLOAD_DATE
+}

backend/src/main/java/org/raddatz/familienarchiv/dto/DocumentUpdateDTO.java

@@ -17,4 +17,5 @@ public class DocumentUpdateDTO {
     private UUID senderId;
     private List<UUID> receiverIds;
     private String tags;
+    private Boolean metadataComplete;
 }

backend/src/main/java/org/raddatz/familienarchiv/dto/IncompleteDocumentDTO.java

@@ -0,0 +1,10 @@
+package org.raddatz.familienarchiv.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.util.UUID;
+
+public record IncompleteDocumentDTO(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String title
+) {}

backend/src/main/java/org/raddatz/familienarchiv/dto/MentionDTO.java

@@ -0,0 +1,11 @@
+package org.raddatz.familienarchiv.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.util.UUID;
+
+public record MentionDTO(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String firstName,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String lastName
+) {}

backend/src/main/java/org/raddatz/familienarchiv/dto/NotificationDTO.java

@@ -0,0 +1,19 @@
+package org.raddatz.familienarchiv.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.raddatz.familienarchiv.model.NotificationType;
+
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+public record NotificationDTO(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) NotificationType type,
+        UUID documentId,
+        UUID referenceId,
+        UUID annotationId,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) boolean read,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) LocalDateTime createdAt,
+        String actorName,
+        String documentTitle
+) {}

backend/src/main/java/org/raddatz/familienarchiv/dto/NotificationPreferenceDTO.java

@@ -0,0 +1,3 @@
+package org.raddatz.familienarchiv.dto;
+
+public record NotificationPreferenceDTO(boolean notifyOnReply, boolean notifyOnMention) {}

backend/src/main/java/org/raddatz/familienarchiv/dto/PersonNameAliasDTO.java

@@ -0,0 +1,12 @@
+package org.raddatz.familienarchiv.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+import org.raddatz.familienarchiv.model.PersonNameAliasType;
+
+public record PersonNameAliasDTO(
+        @NotBlank @Size(max = 255) String lastName,
+        @Size(max = 255) String firstName,
+        @NotNull PersonNameAliasType type
+) {}

backend/src/main/java/org/raddatz/familienarchiv/dto/PersonSummaryDTO.java

@@ -0,0 +1,19 @@
+package org.raddatz.familienarchiv.dto;
+
+import java.util.UUID;
+
+/**
+ * Projection returned by the /api/persons list endpoint.
+ * Includes document count to avoid N+1 queries in the UI.
+ * Uses interface projection for compatibility with native queries.
+ */
+public interface PersonSummaryDTO {
+    UUID getId();
+    String getFirstName();
+    String getLastName();
+    String getAlias();
+    Integer getBirthYear();
+    Integer getDeathYear();
+    String getNotes();
+    long getDocumentCount();
+}

backend/src/main/java/org/raddatz/familienarchiv/dto/PersonUpdateDTO.java

@@ -1,12 +1,17 @@
 package org.raddatz.familienarchiv.dto;
 
+import jakarta.validation.constraints.Size;
 import lombok.Data;
 
 @Data
 public class PersonUpdateDTO {
+    @Size(max = 100)
     private String firstName;
+    @Size(max = 100)
     private String lastName;
+    @Size(max = 200)
     private String alias;
+    @Size(max = 5000)
     private String notes;
     private Integer birthYear;
     private Integer deathYear;

backend/src/main/java/org/raddatz/familienarchiv/dto/ReorderTranscriptionBlocksDTO.java

@@ -0,0 +1,15 @@
+package org.raddatz.familienarchiv.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+import java.util.UUID;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class ReorderTranscriptionBlocksDTO {
+    private List<UUID> blockIds;
+}

backend/src/main/java/org/raddatz/familienarchiv/dto/StatsDTO.java

@@ -0,0 +1,7 @@
+package org.raddatz.familienarchiv.dto;
+
+/**
+ * Aggregate counts for the dashboard/persons stats bar.
+ */
+public record StatsDTO(long totalPersons, long totalDocuments) {
+}

backend/src/main/java/org/raddatz/familienarchiv/dto/UpdateTranscriptionBlockDTO.java

@@ -0,0 +1,13 @@
+package org.raddatz.familienarchiv.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class UpdateTranscriptionBlockDTO {
+    private String text;
+    private String label;
+}

backend/src/main/java/org/raddatz/familienarchiv/exception/ErrorCode.java

@@ -8,6 +8,12 @@ package org.raddatz.familienarchiv.exception;
  */
 public enum ErrorCode {
 
+    // --- Persons ---
+    /** A person with the given ID does not exist. 404 */
+    PERSON_NOT_FOUND,
+    /** A person name alias with the given ID does not exist. 404 */
+    ALIAS_NOT_FOUND,
+
     // --- Documents ---
     /** A document with the given ID does not exist. 404 */
     DOCUMENT_NOT_FOUND,
@@ -17,6 +23,8 @@ public enum ErrorCode {
     FILE_NOT_FOUND,
     /** An error occurred while uploading a file to object storage. 500 */
     FILE_UPLOAD_FAILED,
+    /** The uploaded file's content type is not supported (PDF/JPEG/PNG/TIFF only). 400 */
+    UNSUPPORTED_FILE_TYPE,
 
     // --- Users ---
     /** A user with the given ID or username does not exist. 404 */
@@ -44,10 +52,20 @@ public enum ErrorCode {
     /** The new annotation overlaps an existing one on the same page. 409 */
     ANNOTATION_OVERLAP,
 
+    // --- Transcription Blocks ---
+    /** The transcription block with the given ID does not exist. 404 */
+    TRANSCRIPTION_BLOCK_NOT_FOUND,
+    /** Optimistic locking conflict — block was modified by another user. 409 */
+    TRANSCRIPTION_BLOCK_CONFLICT,
+
     // --- Comments ---
     /** The comment with the given ID does not exist. 404 */
     COMMENT_NOT_FOUND,
 
+    // --- Notifications ---
+    /** The notification with the given ID does not exist. 404 */
+    NOTIFICATION_NOT_FOUND,
+
     // --- Generic ---
     /** Request validation failed (missing or malformed fields). 400 */
     VALIDATION_ERROR,

backend/src/main/java/org/raddatz/familienarchiv/model/AppUser.java

@@ -51,6 +51,16 @@ public class AppUser {
     @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
     private boolean enabled = true; // Um User zu sperren ohne sie zu löschen
 
+    @Column(nullable = false)
+    @Builder.Default
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private boolean notifyOnReply = false;
+
+    @Column(nullable = false)
+    @Builder.Default
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private boolean notifyOnMention = false;
+
     // Ein User kann in mehreren Gruppen sein
     @ManyToMany(fetch = FetchType.EAGER)
     @JoinTable(name = "users_groups", joinColumns = @JoinColumn(name = "user_id"), inverseJoinColumns = @JoinColumn(name = "group_id"))

backend/src/main/java/org/raddatz/familienarchiv/model/Document.java

@@ -39,6 +39,10 @@ public class Document {
     @Column(name = "content_type")
     private String contentType;
 
+    // SHA-256 hash of the uploaded file — used to link annotations to a file version
+    @Column(name = "file_hash", length = 64)
+    private String fileHash;
+
     // Originaler Dateiname beim Upload (z.B. "Brief_Oma_1940.pdf")
     @Column(name = "original_filename", nullable = false)
     @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
@@ -82,6 +86,11 @@ public class Document {
     @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
     private LocalDateTime updatedAt;
 
+    @Column(name = "metadata_complete", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    @Builder.Default
+    private boolean metadataComplete = false;
+
     @ManyToMany(fetch = FetchType.EAGER)
     @JoinTable(name = "document_receivers", joinColumns = @JoinColumn(name = "document_id"), inverseJoinColumns = @JoinColumn(name = "person_id"))
     @Builder.Default

backend/src/main/java/org/raddatz/familienarchiv/model/DocumentAnnotation.java

@@ -49,6 +49,9 @@ public class DocumentAnnotation {
     @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
     private String color;
 
+    @Column(name = "file_hash", length = 64)
+    private String fileHash;
+
     @Column(name = "created_by")
     private UUID createdBy;
 

backend/src/main/java/org/raddatz/familienarchiv/model/DocumentComment.java

@@ -1,10 +1,12 @@
 package org.raddatz.familienarchiv.model;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.persistence.*;
 import lombok.*;
 import org.hibernate.annotations.CreationTimestamp;
 import org.hibernate.annotations.UpdateTimestamp;
+import org.raddatz.familienarchiv.dto.MentionDTO;
 
 import java.time.LocalDateTime;
 import java.util.ArrayList;
@@ -31,6 +33,9 @@ public class DocumentComment {
     @Column(name = "annotation_id")
     private UUID annotationId;
 
+    @Column(name = "block_id")
+    private UUID blockId;
+
     @Column(name = "parent_id")
     private UUID parentId;
 
@@ -60,4 +65,21 @@ public class DocumentComment {
     @Builder.Default
     @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
     private List<DocumentComment> replies = new ArrayList<>();
+
+    // JPA join table for structured mention references — not serialized directly
+    @ManyToMany(fetch = FetchType.EAGER)
+    @JoinTable(
+            name = "comment_mentions",
+            joinColumns = @JoinColumn(name = "comment_id"),
+            inverseJoinColumns = @JoinColumn(name = "user_id")
+    )
+    @JsonIgnore
+    @Builder.Default
+    private List<AppUser> mentions = new ArrayList<>();
+
+    // Populated by CommentService before serialization — not persisted.
+    @Transient
+    @Builder.Default
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private List<MentionDTO> mentionDTOs = new ArrayList<>();
 }

backend/src/main/java/org/raddatz/familienarchiv/model/DocumentSort.java

@@ -0,0 +1,5 @@
+package org.raddatz.familienarchiv.model;
+
+public enum DocumentSort {
+    DATE, TITLE, SENDER, RECEIVER, UPLOAD_DATE
+}

backend/src/main/java/org/raddatz/familienarchiv/model/Notification.java

@@ -0,0 +1,55 @@
+package org.raddatz.familienarchiv.model;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.persistence.*;
+import lombok.*;
+import org.hibernate.annotations.CreationTimestamp;
+
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+@Entity
+@Table(name = "notifications")
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class Notification {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID id;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "recipient_id", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private AppUser recipient;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private NotificationType type;
+
+    @Column(name = "document_id")
+    private UUID documentId;
+
+    @Column(name = "reference_id")
+    private UUID referenceId;
+
+    @Column(name = "annotation_id")
+    private UUID annotationId;
+
+    @Column(nullable = false)
+    @Builder.Default
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private boolean read = false;
+
+    @CreationTimestamp
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private LocalDateTime createdAt;
+
+    @Column(name = "actor_name")
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private String actorName;
+}

backend/src/main/java/org/raddatz/familienarchiv/model/NotificationType.java

@@ -0,0 +1,6 @@
+package org.raddatz.familienarchiv.model;
+
+public enum NotificationType {
+    REPLY,
+    MENTION
+}

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

@@ -1,9 +1,12 @@
 package org.raddatz.familienarchiv.model;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.persistence.*;
 import lombok.*;
 
+import java.util.ArrayList;
+import java.util.List;
 import java.util.UUID;
 @Entity
 @Table(name = "persons")
@@ -35,4 +38,12 @@ public class Person {
 
     private Integer birthYear;
     private Integer deathYear;
+
+    // Entity-graph navigation for JPA JOIN queries (e.g. DocumentSpecifications.hasText).
+    // Uses entity relationship rather than cross-domain repository access, avoiding a
+    // separate DB roundtrip while respecting domain boundaries.
+    @OneToMany(mappedBy = "person", cascade = CascadeType.ALL, orphanRemoval = true)
+    @JsonIgnore
+    @Builder.Default
+    private List<PersonNameAlias> nameAliases = new ArrayList<>();
 }

backend/src/main/java/org/raddatz/familienarchiv/model/PersonNameAlias.java

@@ -0,0 +1,50 @@
+package org.raddatz.familienarchiv.model;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.persistence.*;
+import lombok.*;
+import org.hibernate.annotations.CreationTimestamp;
+
+import java.time.Instant;
+import java.util.UUID;
+
+@Entity
+@Table(name = "person_name_aliases")
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class PersonNameAlias {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID id;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "person_id", nullable = false)
+    @JsonIgnore
+    private Person person;
+
+    @Column(name = "last_name", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private String lastName;
+
+    @Column(name = "first_name")
+    private String firstName;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private PersonNameAliasType type;
+
+    @Column(name = "sort_order", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private Integer sortOrder;
+
+    @CreationTimestamp
+    @Column(name = "created_at", updatable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private Instant createdAt;
+}

backend/src/main/java/org/raddatz/familienarchiv/model/PersonNameAliasType.java

@@ -0,0 +1,8 @@
+package org.raddatz.familienarchiv.model;
+
+public enum PersonNameAliasType {
+    BIRTH,
+    WIDOWED,
+    DIVORCED,
+    OTHER
+}

backend/src/main/java/org/raddatz/familienarchiv/model/TranscriptionBlock.java

@@ -0,0 +1,64 @@
+package org.raddatz.familienarchiv.model;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.persistence.*;
+import lombok.*;
+import org.hibernate.annotations.CreationTimestamp;
+import org.hibernate.annotations.UpdateTimestamp;
+
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+@Entity
+@Table(name = "transcription_blocks")
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class TranscriptionBlock {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID id;
+
+    @Column(name = "annotation_id", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID annotationId;
+
+    @Column(name = "document_id", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID documentId;
+
+    @Column(nullable = false, columnDefinition = "TEXT")
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private String text;
+
+    @Column(length = 200)
+    private String label;
+
+    @Column(name = "sort_order", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private int sortOrder;
+
+    @Version
+    @Column(nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private int version;
+
+    @Column(name = "created_by")
+    private UUID createdBy;
+
+    @Column(name = "updated_by")
+    private UUID updatedBy;
+
+    @Column(name = "created_at", nullable = false, updatable = false)
+    @CreationTimestamp
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private LocalDateTime createdAt;
+
+    @Column(name = "updated_at", nullable = false)
+    @UpdateTimestamp
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private LocalDateTime updatedAt;
+}

backend/src/main/java/org/raddatz/familienarchiv/model/TranscriptionBlockVersion.java

@@ -0,0 +1,39 @@
+package org.raddatz.familienarchiv.model;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.persistence.*;
+import lombok.*;
+import org.hibernate.annotations.CreationTimestamp;
+
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+@Entity
+@Table(name = "transcription_block_versions")
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class TranscriptionBlockVersion {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID id;
+
+    @Column(name = "block_id", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID blockId;
+
+    @Column(nullable = false, columnDefinition = "TEXT")
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private String text;
+
+    @Column(name = "changed_by")
+    private UUID changedBy;
+
+    @Column(name = "changed_at", nullable = false, updatable = false)
+    @CreationTimestamp
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private LocalDateTime changedAt;
+}

backend/src/main/java/org/raddatz/familienarchiv/repository/AnnotationRepository.java

@@ -14,4 +14,6 @@ public interface AnnotationRepository extends JpaRepository<DocumentAnnotation,
     List<DocumentAnnotation> findByDocumentIdAndPageNumber(UUID documentId, int pageNumber);
 
     Optional<DocumentAnnotation> findByIdAndDocumentId(UUID id, UUID documentId);
+
+    List<DocumentAnnotation> findByDocumentIdAndFileHashIsNull(UUID documentId);
 }

backend/src/main/java/org/raddatz/familienarchiv/repository/AppUserRepository.java

@@ -1,10 +1,13 @@
 package org.raddatz.familienarchiv.repository;
 
-
 import org.raddatz.familienarchiv.model.AppUser;
+import org.springframework.data.domain.Pageable;
 import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
 import org.springframework.stereotype.Repository;
 
+import java.util.List;
 import java.util.Optional;
 import java.util.UUID;
 
@@ -12,4 +15,9 @@ import java.util.UUID;
 public interface AppUserRepository extends JpaRepository<AppUser, UUID> {
     Optional<AppUser> findByUsername(String username);
     Optional<AppUser> findByEmail(String email);
+
+    @Query("SELECT u FROM AppUser u WHERE " +
+            "LOWER(COALESCE(u.firstName, '') || ' ' || COALESCE(u.lastName, '')) LIKE LOWER(CONCAT('%', :q, '%')) " +
+            "OR LOWER(u.username) LIKE LOWER(CONCAT('%', :q, '%'))")
+    List<AppUser> searchByNameOrUsername(@Param("q") String q, Pageable pageable);
 }

backend/src/main/java/org/raddatz/familienarchiv/repository/CommentRepository.java

@@ -13,4 +13,6 @@ public interface CommentRepository extends JpaRepository<DocumentComment, UUID>
     List<DocumentComment> findByAnnotationIdAndParentIdIsNull(UUID annotationId);
 
     List<DocumentComment> findByParentId(UUID parentId);
+
+    List<DocumentComment> findByBlockIdAndParentIdIsNull(UUID blockId);
 }

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

@@ -2,6 +2,8 @@ package org.raddatz.familienarchiv.repository;
 
 import org.raddatz.familienarchiv.model.Document;
 import org.raddatz.familienarchiv.model.DocumentStatus;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
@@ -10,7 +12,9 @@ import org.springframework.data.repository.query.Param;
 import org.springframework.stereotype.Repository;
 
 import java.time.LocalDate;
+import java.util.Collection;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 import java.util.UUID;
 
@@ -21,6 +25,9 @@ public interface DocumentRepository extends JpaRepository<Document, UUID>, JpaSp
     // Wichtig für den Abgleich beim Excel-Import & Datei-Upload
     Optional<Document> findByOriginalFilename(String originalFilename);
 
+    // Wie oben, gibt aber nur das erste Ergebnis zurück — sicher wenn doppelte Dateinamen existieren
+    Optional<Document> findFirstByOriginalFilename(String originalFilename);
+
     // Findet alle Dokumente mit einem bestimmten Status
     // z.B. um alle offenen "PLACEHOLDER" zu finden
     List<Document> findByStatus(DocumentStatus status);
@@ -37,14 +44,25 @@ public interface DocumentRepository extends JpaRepository<Document, UUID>, JpaSp
     @Query("SELECT d FROM Document d WHERE d.id NOT IN (SELECT DISTINCT dv.documentId FROM DocumentVersion dv)")
     List<Document> findDocumentsWithoutVersions();
 
+    List<Document> findByFileHashIsNullAndFilePathIsNotNull();
+
+    @Query("SELECT d.id, d.title FROM Document d WHERE d.id IN :ids")
+    List<Object[]> findIdAndTitleByIdIn(@Param("ids") Collection<UUID> ids);
+
+    long countByMetadataCompleteFalse();
+
+    List<Document> findByMetadataCompleteFalse(Sort sort);
+
+    Page<Document> findByMetadataCompleteFalse(Pageable pageable);
+
+    Optional<Document> findFirstByMetadataCompleteFalseAndIdNot(UUID id, Sort sort);
+
     @Query("SELECT DISTINCT d FROM Document d " +
             "JOIN d.receivers r " +
             "WHERE " +
-            // Logik: (Sender A an Empfänger B) ODER (Sender B an Empfänger A)
             "((d.sender.id = :person1 AND r.id = :person2) " +
             " OR " +
             " (d.sender.id = :person2 AND r.id = :person1)) " +
-            // UND das Datum stimmt
             "AND d.documentDate BETWEEN :from AND :to")
     List<Document> findConversation(
             @Param("person1") UUID person1,
@@ -53,4 +71,14 @@ public interface DocumentRepository extends JpaRepository<Document, UUID>, JpaSp
             @Param("to") LocalDate to,
             Sort sort);
 
+    @Query("SELECT DISTINCT d FROM Document d " +
+            "LEFT JOIN d.receivers r " +
+            "WHERE (d.sender.id = :personId OR r.id = :personId) " +
+            "AND d.documentDate BETWEEN :from AND :to")
+    List<Document> findSinglePersonCorrespondence(
+            @Param("personId") UUID personId,
+            @Param("from") LocalDate from,
+            @Param("to") LocalDate to,
+            Sort sort);
+
 }

backend/src/main/java/org/raddatz/familienarchiv/repository/DocumentSpecifications.java

@@ -7,24 +7,79 @@ import java.util.List;
 import java.util.UUID;
 
 import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentStatus;
+import org.raddatz.familienarchiv.model.Person;
+import org.raddatz.familienarchiv.model.PersonNameAlias;
 import org.raddatz.familienarchiv.model.Tag;
 import org.springframework.data.jpa.domain.Specification;
 import org.springframework.util.StringUtils;
 
 public class DocumentSpecifications {
 
-    // Filtert nach Text (in Titel, Dateiname oder Transkription)
+    // Filtert nach Text (in Titel, Dateiname, Transkription, Ort, Absender- und Empfängername, Tags)
     public static Specification<Document> hasText(String text) {
         return (root, query, cb) -> {
             if (!StringUtils.hasText(text))
                 return null;
             String likePattern = "%" + text.toLowerCase() + "%";
 
+            // LEFT JOIN on sender (ManyToOne — no duplicate rows)
+            Join<Document, Person> senderJoin = root.join("sender", JoinType.LEFT);
+
+            // LEFT JOIN sender → aliases (entity-graph navigation avoids a separate DB
+            // roundtrip while respecting domain boundaries — the alias table is part of
+            // the Person aggregate, navigated via @OneToMany, not via a cross-domain
+            // repository call from DocumentService)
+            Join<Person, PersonNameAlias> senderAliasJoin = senderJoin.join("nameAliases", JoinType.LEFT);
+
+            // EXISTS subquery for receiver name — avoids duplicate rows for multi-receiver docs
+            Subquery<Long> receiverSub = query.subquery(Long.class);
+            Root<Document> receiverRoot = receiverSub.from(Document.class);
+            Join<Document, Person> receiverJoin = receiverRoot.join("receivers");
+            receiverSub.select(cb.literal(1L))
+                    .where(
+                            cb.equal(receiverRoot.get("id"), root.get("id")),
+                            cb.or(
+                                    cb.like(cb.lower(receiverJoin.get("lastName")), likePattern),
+                                    cb.like(cb.lower(receiverJoin.get("firstName")), likePattern)
+                            )
+                    );
+
+            // EXISTS subquery for receiver alias name
+            Subquery<Long> receiverAliasSub = query.subquery(Long.class);
+            Root<Document> receiverAliasRoot = receiverAliasSub.from(Document.class);
+            Join<Document, Person> recAliasPersonJoin = receiverAliasRoot.join("receivers");
+            Join<Person, PersonNameAlias> recAliasJoin = recAliasPersonJoin.join("nameAliases");
+            receiverAliasSub.select(cb.literal(1L))
+                    .where(
+                            cb.equal(receiverAliasRoot.get("id"), root.get("id")),
+                            cb.like(cb.lower(recAliasJoin.get("lastName")), likePattern)
+                    );
+
+            // EXISTS subquery for tag name — avoids duplicate rows for multi-tag docs
+            Subquery<Long> tagSub = query.subquery(Long.class);
+            Root<Document> tagRoot = tagSub.from(Document.class);
+            Join<Document, Tag> tagJoin = tagRoot.join("tags");
+            tagSub.select(cb.literal(1L))
+                    .where(
+                            cb.equal(tagRoot.get("id"), root.get("id")),
+                            cb.like(cb.lower(tagJoin.get("name")), likePattern)
+                    );
+
+            query.distinct(true);
+
             return cb.or(
                     cb.like(cb.lower(root.get("title")), likePattern),
                     cb.like(cb.lower(root.get("originalFilename")), likePattern),
                     cb.like(cb.lower(root.get("transcription")), likePattern),
-                    cb.like(cb.lower(root.get("location")), likePattern));
+                    cb.like(cb.lower(root.get("location")), likePattern),
+                    cb.like(cb.lower(senderJoin.get("lastName")), likePattern),
+                    cb.like(cb.lower(senderJoin.get("firstName")), likePattern),
+                    cb.like(cb.lower(senderAliasJoin.get("lastName")), likePattern),
+                    cb.exists(receiverSub),
+                    cb.exists(receiverAliasSub),
+                    cb.exists(tagSub)
+            );
         };
     }
 
@@ -54,8 +109,13 @@ public class DocumentSpecifications {
             return cb.lessThanOrEqualTo(root.get("documentDate"), end);
         };
     }
-    
+
-    // Filtert nach Schlagworten (UND-Verknüpfung)
+    // Filtert nach Status
+    public static Specification<Document> hasStatus(DocumentStatus status) {
+        return (root, query, cb) -> status == null ? null : cb.equal(root.get("status"), status);
+    }
+
+    // Filtert nach Schlagworten (UND-Verknüpfung, exakter Match)
     public static Specification<Document> hasTags(List<String> tags) {
         return (root, query, cb) -> {
             if (tags == null || tags.isEmpty())
@@ -66,15 +126,13 @@ public class DocumentSpecifications {
             for (String tagName : tags) {
                 if (!StringUtils.hasText(tagName)) continue;
 
-                // Subquery erstellen: "Gibt es für dieses Dokument (root.id) einen Tag mit dem Namen X?"
-                // Dies stellt sicher, dass ALLE Tags vorhanden sein müssen (AND Logik).
                 Subquery<Long> subquery = query.subquery(Long.class);
                 Root<Document> subRoot = subquery.from(Document.class);
                 Join<Document, Tag> subTags = subRoot.join("tags");
 
                 subquery.select(subRoot.get("id"))
                         .where(
-                                cb.equal(subRoot.get("id"), root.get("id")), // Korrelation zum Haupt-Query
+                                cb.equal(subRoot.get("id"), root.get("id")),
                                 cb.equal(cb.lower(subTags.get("name")), tagName.trim().toLowerCase())
                         );
 
@@ -84,5 +142,26 @@ public class DocumentSpecifications {
             return cb.and(predicates.toArray(new Predicate[0]));
         };
     }
-    
+
-}
+    // Filtert nach partiellem Tag-Namen (ILIKE) — für Live-Tag-Suche
+    public static Specification<Document> hasTagPartial(String tagQ) {
+        return (root, query, cb) -> {
+            if (!StringUtils.hasText(tagQ))
+                return null;
+            String likePattern = "%" + tagQ.toLowerCase() + "%";
+
+            Subquery<Long> subquery = query.subquery(Long.class);
+            Root<Document> subRoot = subquery.from(Document.class);
+            Join<Document, Tag> tagJoin = subRoot.join("tags");
+
+            subquery.select(cb.literal(1L))
+                    .where(
+                            cb.equal(subRoot.get("id"), root.get("id")),
+                            cb.like(cb.lower(tagJoin.get("name")), likePattern)
+                    );
+
+            return cb.exists(subquery);
+        };
+    }
+
+}

backend/src/main/java/org/raddatz/familienarchiv/repository/NotificationRepository.java

@@ -0,0 +1,32 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.raddatz.familienarchiv.model.Notification;
+import org.raddatz.familienarchiv.model.NotificationType;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.UUID;
+
+public interface NotificationRepository extends JpaRepository<Notification, UUID> {
+
+    Page<Notification> findByRecipientIdOrderByCreatedAtDesc(UUID recipientId, Pageable pageable);
+
+    Page<Notification> findByRecipientIdAndTypeOrderByCreatedAtDesc(
+            UUID recipientId, NotificationType type, Pageable pageable);
+
+    Page<Notification> findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(
+            UUID recipientId, NotificationType type, Pageable pageable);
+
+    Page<Notification> findByRecipientIdAndReadFalseOrderByCreatedAtDesc(
+            UUID recipientId, Pageable pageable);
+
+    long countByRecipientIdAndReadFalse(UUID recipientId);
+
+    @Modifying
+    @Query("UPDATE Notification n SET n.read = true WHERE n.recipient.id = :userId")
+    void markAllReadByRecipientId(@Param("userId") UUID userId);
+}

backend/src/main/java/org/raddatz/familienarchiv/repository/PersonNameAliasRepository.java

@@ -0,0 +1,16 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.raddatz.familienarchiv.model.PersonNameAlias;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+
+import java.util.List;
+import java.util.UUID;
+
+public interface PersonNameAliasRepository extends JpaRepository<PersonNameAlias, UUID> {
+
+    List<PersonNameAlias> findByPersonIdOrderBySortOrderAscCreatedAtAsc(UUID personId);
+
+    @Query("SELECT COALESCE(MAX(a.sortOrder), -1) FROM PersonNameAlias a WHERE a.person.id = :personId")
+    int findMaxSortOrder(UUID personId);
+}

backend/src/main/java/org/raddatz/familienarchiv/repository/PersonRepository.java

@@ -4,6 +4,7 @@ import java.util.List;
 import java.util.Optional;
 import java.util.UUID;
 
+import org.raddatz.familienarchiv.dto.PersonSummaryDTO;
 import org.raddatz.familienarchiv.model.Person;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.data.jpa.repository.Modifying;
@@ -14,11 +15,11 @@ import org.springframework.stereotype.Repository;
 @Repository
 public interface PersonRepository extends JpaRepository<Person, UUID> {
 
-    // Suche nach String in Vor- ODER Nachnamen, sortiert nach Nachname
+    @Query("SELECT DISTINCT p FROM Person p LEFT JOIN p.nameAliases a WHERE " +
-    @Query("SELECT p FROM Person p WHERE " +
            "LOWER(CONCAT(p.firstName,' ',p.lastName)) LIKE LOWER(CONCAT('%', :query, '%')) OR " +
            "LOWER(CONCAT(p.lastName, ' ', p.firstName)) LIKE LOWER(CONCAT('%', :query, '%')) OR " +
-           "LOWER(p.alias) LIKE LOWER(CONCAT('%', :query, '%')) " +
+           "LOWER(p.alias) LIKE LOWER(CONCAT('%', :query, '%')) OR " +
+           "LOWER(a.lastName) LIKE LOWER(CONCAT('%', :query, '%')) " +
            "ORDER BY p.lastName ASC, p.firstName ASC")
     List<Person> searchByName(@Param("query") String query);
 
@@ -28,6 +29,39 @@ public interface PersonRepository extends JpaRepository<Person, UUID> {
     // Lookup by full alias string, used during ODS mass import
     Optional<Person> findByAliasIgnoreCase(String alias);
 
+    // Exact first+last name match, used for filename-based sender lookup
+    Optional<Person> findByFirstNameIgnoreCaseAndLastNameIgnoreCase(String firstName, String lastName);
+
+    // --- PersonSummaryDTO with document count ---
+
+    @Query(value = """
+            SELECT p.id, p.first_name AS firstName, p.last_name AS lastName,
+                   p.alias, p.birth_year AS birthYear, p.death_year AS deathYear, p.notes,
+                   (SELECT COUNT(*) FROM documents d WHERE d.sender_id = p.id)
+                   + (SELECT COUNT(*) FROM document_receivers dr WHERE dr.person_id = p.id) AS documentCount
+            FROM persons p
+            ORDER BY p.last_name ASC, p.first_name ASC
+            """,
+            nativeQuery = true)
+    List<PersonSummaryDTO> findAllWithDocumentCount();
+
+    @Query(value = """
+            SELECT p.id, p.first_name AS firstName, p.last_name AS lastName,
+                   p.alias, p.birth_year AS birthYear, p.death_year AS deathYear, p.notes,
+                   (SELECT COUNT(*) FROM documents d WHERE d.sender_id = p.id)
+                   + (SELECT COUNT(*) FROM document_receivers dr WHERE dr.person_id = p.id) AS documentCount
+            FROM persons p
+            LEFT JOIN person_name_aliases a ON a.person_id = p.id
+            WHERE LOWER(CONCAT(p.first_name,' ',p.last_name)) LIKE LOWER(CONCAT('%',:query,'%'))
+               OR LOWER(CONCAT(p.last_name,' ',p.first_name)) LIKE LOWER(CONCAT('%',:query,'%'))
+               OR LOWER(p.alias) LIKE LOWER(CONCAT('%',:query,'%'))
+               OR LOWER(a.last_name) LIKE LOWER(CONCAT('%',:query,'%'))
+            GROUP BY p.id, p.first_name, p.last_name, p.alias, p.birth_year, p.death_year, p.notes
+            ORDER BY p.last_name ASC, p.first_name ASC
+            """,
+            nativeQuery = true)
+    List<PersonSummaryDTO> searchWithDocumentCount(@Param("query") String query);
+
     // --- Correspondent queries ---
 
     @Query(value = """

backend/src/main/java/org/raddatz/familienarchiv/repository/TranscriptionBlockRepository.java

@@ -0,0 +1,17 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.raddatz.familienarchiv.model.TranscriptionBlock;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+
+public interface TranscriptionBlockRepository extends JpaRepository<TranscriptionBlock, UUID> {
+
+    List<TranscriptionBlock> findByDocumentIdOrderBySortOrderAsc(UUID documentId);
+
+    Optional<TranscriptionBlock> findByIdAndDocumentId(UUID id, UUID documentId);
+
+    int countByDocumentId(UUID documentId);
+}

backend/src/main/java/org/raddatz/familienarchiv/repository/TranscriptionBlockVersionRepository.java

@@ -0,0 +1,12 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.raddatz.familienarchiv.model.TranscriptionBlockVersion;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.List;
+import java.util.UUID;
+
+public interface TranscriptionBlockVersionRepository extends JpaRepository<TranscriptionBlockVersion, UUID> {
+
+    List<TranscriptionBlockVersion> findByBlockIdOrderByChangedAtDesc(UUID blockId);
+}

backend/src/main/java/org/raddatz/familienarchiv/security/PermissionAspect.java

@@ -23,7 +23,7 @@ public class PermissionAspect {
         RequirePermission permission = getAnnotation(joinPoint);
 
         if (permission != null) {
-            validateUserAccess(permission.value());
+            validateUserAccess(permission.value()); // value() is now Permission[]
         }
 
         return joinPoint.proceed();
@@ -43,18 +43,23 @@ public class PermissionAspect {
         return joinPoint.getTarget().getClass().getAnnotation(RequirePermission.class);
     }
 
-    private void validateUserAccess(Permission requiredPerm) {
+    private void validateUserAccess(Permission[] requiredPerms) {
         Authentication auth = SecurityContextHolder.getContext().getAuthentication();
 
         if (auth == null || !auth.isAuthenticated()) {
             throw DomainException.unauthorized("Not authenticated");
         }
 
-        boolean hasPermission = auth.getAuthorities().stream()
+        boolean hasAny = auth.getAuthorities().stream()
-                .anyMatch(a -> a.getAuthority().equals(requiredPerm.name()));
+                .anyMatch(a -> {
+                    for (Permission p : requiredPerms) {
+                        if (a.getAuthority().equals(p.name())) return true;
+                    }
+                    return false;
+                });
 
-        if (!hasPermission) {
+        if (!hasAny) {
-            throw DomainException.forbidden("Missing required permission: " + requiredPerm.name());
+            throw DomainException.forbidden("Missing required permission");
         }
     }
 }

backend/src/main/java/org/raddatz/familienarchiv/security/RequirePermission.java

@@ -8,5 +8,5 @@ import java.lang.annotation.Target;
 @Target({ElementType.METHOD, ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface RequirePermission {
-    Permission value(); // e.g. "ADMIN" or "WRITE_ALL"
+    Permission[] value(); // one or more — user needs any of the listed permissions
 }

backend/src/main/java/org/raddatz/familienarchiv/service/AnnotationService.java

@@ -23,7 +23,7 @@ public class AnnotationService {
     }
 
     @Transactional
-    public DocumentAnnotation createAnnotation(UUID documentId, CreateAnnotationDTO dto, UUID userId) {
+    public DocumentAnnotation createAnnotation(UUID documentId, CreateAnnotationDTO dto, UUID userId, String fileHash) {
         List<DocumentAnnotation> existing =
                 annotationRepository.findByDocumentIdAndPageNumber(documentId, dto.getPageNumber());
 
@@ -41,6 +41,7 @@ public class AnnotationService {
                 .width(dto.getWidth())
                 .height(dto.getHeight())
                 .color(dto.getColor())
+                .fileHash(fileHash)
                 .createdBy(userId)
                 .build();
 
@@ -61,6 +62,14 @@ public class AnnotationService {
         annotationRepository.delete(annotation);
     }
 
+    @Transactional
+    public void backfillAnnotationFileHashForDocument(UUID documentId, String fileHash) {
+        annotationRepository.findByDocumentIdAndFileHashIsNull(documentId).forEach(a -> {
+            a.setFileHash(fileHash);
+            annotationRepository.save(a);
+        });
+    }
+
     // ─── private helpers ──────────────────────────────────────────────────────
 
     private boolean overlaps(DocumentAnnotation existing, CreateAnnotationDTO dto) {

backend/src/main/java/org/raddatz/familienarchiv/service/CommentService.java

@@ -1,6 +1,7 @@
 package org.raddatz.familienarchiv.service;
 
 import lombok.RequiredArgsConstructor;
+import org.raddatz.familienarchiv.dto.MentionDTO;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
 import org.raddatz.familienarchiv.model.AppUser;
@@ -9,7 +10,9 @@ import org.raddatz.familienarchiv.repository.CommentRepository;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
+import java.util.LinkedHashSet;
 import java.util.List;
+import java.util.Set;
 import java.util.UUID;
 
 @Service
@@ -17,20 +20,45 @@ import java.util.UUID;
 public class CommentService {
 
     private final CommentRepository commentRepository;
+    private final UserService userService;
+    private final NotificationService notificationService;
 
     public List<DocumentComment> getCommentsForDocument(UUID documentId) {
         List<DocumentComment> roots =
                 commentRepository.findByDocumentIdAndAnnotationIdIsNullAndParentIdIsNull(documentId);
-        return withReplies(roots);
+        return withRepliesAndMentions(roots);
     }
 
     public List<DocumentComment> getCommentsForAnnotation(UUID annotationId) {
         List<DocumentComment> roots = commentRepository.findByAnnotationIdAndParentIdIsNull(annotationId);
-        return withReplies(roots);
+        return withRepliesAndMentions(roots);
+    }
+
+    public List<DocumentComment> getCommentsForBlock(UUID blockId) {
+        List<DocumentComment> roots = commentRepository.findByBlockIdAndParentIdIsNull(blockId);
+        return withRepliesAndMentions(roots);
     }
 
     @Transactional
-    public DocumentComment postComment(UUID documentId, UUID annotationId, String content, AppUser author) {
+    public DocumentComment postBlockComment(UUID documentId, UUID blockId, String content,
+                                            List<UUID> mentionedUserIds, AppUser author) {
+        DocumentComment comment = DocumentComment.builder()
+                .documentId(documentId)
+                .blockId(blockId)
+                .content(content)
+                .authorId(author.getId())
+                .authorName(resolveAuthorName(author))
+                .build();
+        saveMentions(comment, mentionedUserIds);
+        DocumentComment saved = commentRepository.save(comment);
+        withMentionDTOs(saved);
+        notificationService.notifyMentions(mentionedUserIds, saved);
+        return saved;
+    }
+
+    @Transactional
+    public DocumentComment postComment(UUID documentId, UUID annotationId, String content,
+                                       List<UUID> mentionedUserIds, AppUser author) {
         DocumentComment comment = DocumentComment.builder()
                 .documentId(documentId)
                 .annotationId(annotationId)
@@ -38,11 +66,16 @@ public class CommentService {
                 .authorId(author.getId())
                 .authorName(resolveAuthorName(author))
                 .build();
-        return commentRepository.save(comment);
+        saveMentions(comment, mentionedUserIds);
+        DocumentComment saved = commentRepository.save(comment);
+        withMentionDTOs(saved);
+        notificationService.notifyMentions(mentionedUserIds, saved);
+        return saved;
     }
 
     @Transactional
-    public DocumentComment replyToComment(UUID documentId, UUID commentId, String content, AppUser author) {
+    public DocumentComment replyToComment(UUID documentId, UUID commentId, String content,
+                                          List<UUID> mentionedUserIds, AppUser author) {
         DocumentComment target = commentRepository.findById(commentId)
                 .orElseThrow(() -> DomainException.notFound(
                         ErrorCode.COMMENT_NOT_FOUND, "Comment not found: " + commentId));
@@ -60,7 +93,15 @@ public class CommentService {
                 .authorId(author.getId())
                 .authorName(resolveAuthorName(author))
                 .build();
-        return commentRepository.save(reply);
+        saveMentions(reply, mentionedUserIds);
+        DocumentComment saved = commentRepository.save(reply);
+        withMentionDTOs(saved);
+
+        Set<UUID> participantIds = collectParticipantIds(root);
+        participantIds.remove(author.getId());
+        notificationService.notifyReply(saved, participantIds);
+        notificationService.notifyMentions(mentionedUserIds, saved);
+        return saved;
     }
 
     @Transactional
@@ -84,13 +125,45 @@ public class CommentService {
         commentRepository.delete(comment);
     }
 
+    public List<DocumentComment> findReplies(UUID parentId) {
+        return commentRepository.findByParentId(parentId);
+    }
+
     // ─── private helpers ──────────────────────────────────────────────────────
 
-    private List<DocumentComment> withReplies(List<DocumentComment> roots) {
+    private List<DocumentComment> withRepliesAndMentions(List<DocumentComment> roots) {
-        roots.forEach(root -> root.setReplies(commentRepository.findByParentId(root.getId())));
+        roots.forEach(root -> {
+            List<DocumentComment> replies = commentRepository.findByParentId(root.getId());
+            replies.forEach(this::withMentionDTOs);
+            root.setReplies(replies);
+            withMentionDTOs(root);
+        });
         return roots;
     }
 
+    private void saveMentions(DocumentComment comment, List<UUID> mentionedUserIds) {
+        if (mentionedUserIds == null || mentionedUserIds.isEmpty()) return;
+        List<AppUser> users = userService.findAllById(mentionedUserIds);
+        comment.setMentions(users);
+    }
+
+    private void withMentionDTOs(DocumentComment comment) {
+        List<MentionDTO> dtos = comment.getMentions().stream()
+                .map(u -> new MentionDTO(u.getId(), u.getFirstName(), u.getLastName()))
+                .toList();
+        comment.setMentionDTOs(dtos);
+    }
+
+    private Set<UUID> collectParticipantIds(DocumentComment root) {
+        Set<UUID> ids = new LinkedHashSet<>();
+        if (root.getAuthorId() != null) ids.add(root.getAuthorId());
+        commentRepository.findByParentId(root.getId())
+                .forEach(reply -> {
+                    if (reply.getAuthorId() != null) ids.add(reply.getAuthorId());
+                });
+        return ids;
+    }
+
     private DocumentComment findComment(UUID documentId, UUID commentId) {
         return commentRepository.findById(commentId)
                 .filter(c -> documentId.equals(c.getDocumentId()))

backend/src/main/java/org/raddatz/familienarchiv/service/DocumentService.java

@@ -4,11 +4,14 @@ import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
 import org.raddatz.familienarchiv.dto.DocumentUpdateDTO;
+import org.raddatz.familienarchiv.dto.IncompleteDocumentDTO;
 import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.dto.DocumentSort;
 import org.raddatz.familienarchiv.model.DocumentStatus;
 import org.raddatz.familienarchiv.model.Person;
 import org.raddatz.familienarchiv.model.Tag;
 import org.raddatz.familienarchiv.repository.DocumentRepository;
+import org.springframework.data.domain.PageRequest;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.jpa.domain.Specification;
 import org.raddatz.familienarchiv.exception.DomainException;
@@ -18,11 +21,18 @@ import org.springframework.transaction.annotation.Transactional;
 import org.springframework.web.multipart.MultipartFile;
 
 import java.io.IOException;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
 import java.time.LocalDate;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collection;
+import java.util.Comparator;
+import java.util.HashMap;
 import java.util.HashSet;
 import java.util.List;
+import java.util.Map;
+import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
 import java.util.UUID;
@@ -38,42 +48,64 @@ public class DocumentService {
     private final FileService fileService;
     private final TagService tagService;
     private final DocumentVersionService documentVersionService;
+    private final AnnotationService annotationService;
+
+    public record StoreResult(Document document, boolean isNew) {}
+
+    public Map<UUID, String> findTitlesByIds(Collection<UUID> ids) {
+        if (ids.isEmpty()) return Map.of();
+        Map<UUID, String> titles = new HashMap<>();
+        for (Object[] row : documentRepository.findIdAndTitleByIdIn(ids)) {
+            titles.put((UUID) row[0], (String) row[1]);
+        }
+        return titles;
+    }
 
     /**
      * Lädt eine Datei hoch.
      * - Prüft, ob ein Eintrag (aus Excel) schon existiert.
-     * - Wenn JA: Aktualisiert Status und verknüpft Datei.
+     * - Wenn JA: Aktualisiert Status und verknüpft Datei — isNew = false.
-     * - Wenn NEIN: Erstellt neuen Eintrag (wartet auf Metadaten).
+     * - Wenn NEIN: Erstellt neuen Eintrag — isNew = true.
      */
     @Transactional
-    public Document storeDocument(MultipartFile file) throws IOException {
+    public StoreResult storeDocument(MultipartFile file) throws IOException {
         String originalFilename = file.getOriginalFilename();
 
-        // 1. Check for existing record
+        // 1. Check for existing record (findFirst to survive duplicate filenames in the DB)
-        Optional<Document> existingDoc = documentRepository.findByOriginalFilename(originalFilename);
+        Optional<Document> existingDoc = documentRepository.findFirstByOriginalFilename(originalFilename);
+        boolean isNew = existingDoc.isEmpty();
         Document document;
 
         if (existingDoc.isPresent()) {
             document = existingDoc.get();
         } else {
+            // New uploads from the drop zone always start as incomplete
+            ParsedFilename parsed = parseFilenameData(originalFilename);
+            Person sender = (parsed != null)
+                    ? personService.findByName(parsed.firstName(), parsed.lastName()).orElse(null)
+                    : null;
             document = Document.builder()
                     .originalFilename(originalFilename)
-                    .title(originalFilename)
+                    .title(parsed != null ? parsed.title() : stripExtension(originalFilename))
+                    .documentDate(parsed != null ? parsed.date() : null)
+                    .sender(sender)
                     .status(DocumentStatus.UPLOADED)
+                    .metadataComplete(false)
                     .build();
         }
 
         // 2. Delegate Storage to FileService
-        String s3Key = fileService.uploadFile(file, originalFilename);
+        FileService.UploadResult upload = fileService.uploadFile(file, originalFilename);
 
         // 3. Update Database
-        document.setFilePath(s3Key);
+        document.setFilePath(upload.s3Key());
+        document.setFileHash(upload.fileHash());
         document.setContentType(file.getContentType());
         if (document.getStatus() == DocumentStatus.PLACEHOLDER) {
             document.setStatus(DocumentStatus.UPLOADED);
         }
 
-        return documentRepository.save(document);
+        return new StoreResult(documentRepository.save(document), isNew);
     }
 
     @Transactional
@@ -82,15 +114,31 @@ public class DocumentService {
                 ? file.getOriginalFilename()
                 : (dto.getTitle() != null ? dto.getTitle() : "Unbenanntes Dokument");
 
+        // If the caller explicitly sets metadataComplete, use it.
+        // Otherwise apply heuristic: complete if at least one key field is present.
+        boolean metadataComplete;
+        if (dto.getMetadataComplete() != null) {
+            metadataComplete = dto.getMetadataComplete();
+        } else {
+            metadataComplete = dto.getDocumentDate() != null
+                    || dto.getSenderId() != null
+                    || (dto.getReceiverIds() != null && !dto.getReceiverIds().isEmpty());
+        }
+
+        String titleToUse = (dto.getTitle() != null && !dto.getTitle().isBlank())
+                ? dto.getTitle()
+                : titleFromFilename(filename);
+
         Document doc = Document.builder()
                 .originalFilename(filename)
-                .title(dto.getTitle())
+                .title(titleToUse)
                 .documentDate(dto.getDocumentDate())
                 .location(dto.getLocation())
                 .documentLocation(dto.getDocumentLocation())
                 .transcription(dto.getTranscription())
                 .summary(dto.getSummary())
                 .status(DocumentStatus.PLACEHOLDER)
+                .metadataComplete(metadataComplete)
                 .build();
 
         doc = documentRepository.save(doc);
@@ -120,8 +168,9 @@ public class DocumentService {
 
         // Datei
         if (file != null && !file.isEmpty()) {
-            String s3Key = fileService.uploadFile(file, file.getOriginalFilename());
+            FileService.UploadResult upload = fileService.uploadFile(file, file.getOriginalFilename());
-            doc.setFilePath(s3Key);
+            doc.setFilePath(upload.s3Key());
+            doc.setFileHash(upload.fileHash());
             doc.setContentType(file.getContentType());
             doc.setStatus(DocumentStatus.UPLOADED);
         }
@@ -168,14 +217,16 @@ public class DocumentService {
             doc.getReceivers().clear(); // Alle entfernen
         }
 
+        // 3b. metadataComplete — only update when explicitly set in the DTO
+        if (dto.getMetadataComplete() != null) {
+            doc.setMetadataComplete(dto.getMetadataComplete());
+        }
+
         // 4. Datei austauschen (nur wenn eine neue ausgewählt wurde)
         if (newFile != null && !newFile.isEmpty()) {
-            // Alte Datei könnte man hier theoretisch löschen (optional)
+            FileService.UploadResult upload = fileService.uploadFile(newFile, newFile.getOriginalFilename());
-
+            doc.setFilePath(upload.s3Key());
-            // Neue Datei hochladen
+            doc.setFileHash(upload.fileHash());
-            String s3Key = fileService.uploadFile(newFile, newFile.getOriginalFilename());
-
-            doc.setFilePath(s3Key);
             doc.setOriginalFilename(newFile.getOriginalFilename());
             doc.setContentType(newFile.getContentType());
             doc.setStatus(DocumentStatus.UPLOADED);
@@ -224,16 +275,86 @@ public class DocumentService {
         return documentRepository.save(doc);
     }
 
+    // 0. Zuletzt aktive Dokumente (sortiert nach updatedAt DESC)
+    public List<Document> getRecentActivity(int size) {
+        return documentRepository.findAll(
+                PageRequest.of(0, size, Sort.by(Sort.Direction.DESC, "updatedAt"))
+        ).getContent();
+    }
+
     // 1. Allgemeine Suche (für das Suchfeld im Frontend)
-    public List<Document> searchDocuments(String text, LocalDate from, LocalDate to, UUID sender, UUID receiver, List<String> tags) {
+    public List<Document> searchDocuments(String text, LocalDate from, LocalDate to, UUID sender, UUID receiver, List<String> tags, String tagQ, DocumentStatus status, DocumentSort sort, String dir) {
         Specification<Document> spec = Specification.where(hasText(text))
                 .and(isBetween(from, to))
                 .and(hasSender(sender))
                 .and(hasReceiver(receiver))
-                .and(hasTags(tags));
+                .and(hasTags(tags))
+                .and(hasTagPartial(tagQ))
+                .and(hasStatus(status));
 
-        // Immer sortiert nach Datum
+        // SENDER and RECEIVER are sorted in-memory because JPA's Sort.by("sender.lastName")
-        return documentRepository.findAll(spec, Sort.by(Sort.Direction.ASC, "documentDate"));
+        // generates an INNER JOIN that silently drops documents with null sender/receivers.
+        // TODO: replace with a native @Query using ORDER BY ... NULLS LAST when pagination is added.
+        if (sort == DocumentSort.RECEIVER) {
+            List<Document> results = documentRepository.findAll(spec);
+            return sortByFirstReceiver(results, dir);
+        }
+        if (sort == DocumentSort.SENDER) {
+            List<Document> results = documentRepository.findAll(spec);
+            return sortBySender(results, dir);
+        }
+        Sort springSort = resolveSort(sort, dir);
+        return documentRepository.findAll(spec, springSort);
+    }
+
+    private Sort resolveSort(DocumentSort sort, String dir) {
+        Sort.Direction direction = "ASC".equalsIgnoreCase(dir) ? Sort.Direction.ASC : Sort.Direction.DESC;
+        if (sort == null || sort == DocumentSort.DATE) {
+            return Sort.by(direction, "documentDate");
+        }
+        // SENDER and RECEIVER are sorted in-memory before this method is called
+        return switch (sort) {
+            case TITLE -> Sort.by(direction, "title");
+            case UPLOAD_DATE -> Sort.by(direction, "createdAt");
+            default -> Sort.by(direction, "documentDate");
+        };
+    }
+
+    private List<Document> sortBySender(List<Document> documents, String dir) {
+        boolean ascending = "ASC".equalsIgnoreCase(dir);
+        Comparator<String> nullSafeComparator = (a, b) -> {
+            if (a.isEmpty() && b.isEmpty()) return 0;
+            if (a.isEmpty()) return ascending ? 1 : -1;
+            if (b.isEmpty()) return ascending ? -1 : 1;
+            return ascending ? a.compareTo(b) : b.compareTo(a);
+        };
+        return documents.stream()
+                .sorted(Comparator.comparing(doc -> {
+                    Person s = doc.getSender();
+                    if (s == null || s.getLastName() == null) return "";
+                    return s.getLastName() + " " + Objects.toString(s.getFirstName(), "");
+                }, nullSafeComparator))
+                .toList();
+    }
+
+    private List<Document> sortByFirstReceiver(List<Document> documents, String dir) {
+        boolean ascending = "ASC".equalsIgnoreCase(dir);
+        Comparator<String> nullSafeComparator = (a, b) -> {
+            if (a.isEmpty() && b.isEmpty()) return 0;
+            if (a.isEmpty()) return 1;
+            if (b.isEmpty()) return -1;
+            return ascending ? a.compareTo(b) : b.compareTo(a);
+        };
+        return documents.stream()
+                .sorted(Comparator.comparing(this::firstReceiverSortKey, nullSafeComparator))
+                .toList();
+    }
+
+    private String firstReceiverSortKey(Document doc) {
+        return doc.getReceivers().stream()
+                .min(Comparator.comparing(Person::getLastName).thenComparing(Person::getFirstName))
+                .map(p -> p.getLastName() + " " + p.getFirstName())
+                .orElse("");
     }
 
     // 2. SPEZIALITÄT: Der Schriftwechsel
@@ -272,9 +393,37 @@ public class DocumentService {
     public List<Document> getConversationFiltered(UUID senderId, UUID receiverId, LocalDate from, LocalDate to, Sort sort) {
         LocalDate dateFrom = (from != null) ? from : LocalDate.parse("0000-01-01");
         LocalDate dateTo = (to != null) ? to : LocalDate.now();
+        if (receiverId == null) {
+            return documentRepository.findSinglePersonCorrespondence(senderId, dateFrom, dateTo, sort);
+        }
         return documentRepository.findConversation(senderId, receiverId, dateFrom, dateTo, sort);
     }
 
+    public long getIncompleteCount() {
+        return documentRepository.countByMetadataCompleteFalse();
+    }
+
+    public List<IncompleteDocumentDTO> findIncompleteDocuments(int size) {
+        PageRequest pageable = PageRequest.of(0, size, Sort.by(Sort.Direction.DESC, "createdAt"));
+        return documentRepository.findByMetadataCompleteFalse(pageable)
+                .stream()
+                .map(doc -> new IncompleteDocumentDTO(doc.getId(), doc.getTitle()))
+                .toList();
+    }
+
+    public Optional<Document> findNextIncompleteDocument(UUID currentId) {
+        return documentRepository.findFirstByMetadataCompleteFalseAndIdNot(
+                currentId, Sort.by(Sort.Direction.DESC, "createdAt"));
+    }
+
+    @Transactional
+    public void deleteDocument(UUID id) {
+        if (!documentRepository.existsById(id)) {
+            throw DomainException.notFound(ErrorCode.DOCUMENT_NOT_FOUND, "Document not found: " + id);
+        }
+        documentRepository.deleteById(id);
+    }
+
     @Transactional
     public void deleteTagCascading(UUID tagId) {
         documentRepository.findByTags_Id(tagId).forEach(doc -> {
@@ -283,4 +432,120 @@ public class DocumentService {
         });
         tagService.delete(tagId);
     }
+
+    @Transactional
+    public int backfillFileHashes() {
+        List<Document> docs = documentRepository.findByFileHashIsNullAndFilePathIsNotNull();
+        int count = 0;
+        for (Document doc : docs) {
+            try {
+                byte[] bytes = fileService.downloadFileBytes(doc.getFilePath());
+                String hash = sha256Hex(bytes);
+                doc.setFileHash(hash);
+                documentRepository.save(doc);
+                annotationService.backfillAnnotationFileHashForDocument(doc.getId(), hash);
+                count++;
+            } catch (Exception e) {
+                log.warn("Failed to backfill hash for document {}: {}", doc.getId(), e.getMessage());
+            }
+        }
+        return count;
+    }
+
+    // ─── private helpers ──────────────────────────────────────────────────────
+
+    private static String stripExtension(String filename) {
+        if (filename == null) return null;
+        int dot = filename.lastIndexOf('.');
+        return dot > 0 ? filename.substring(0, dot) : filename;
+    }
+
+    private record ParsedFilename(LocalDate date, String firstName, String lastName) {
+        String title() {
+            String dateDisplay = String.format("%02d.%02d.%d",
+                    date.getDayOfMonth(), date.getMonthValue(), date.getYear());
+            return firstName + " " + lastName + " (" + dateDisplay + ")";
+        }
+    }
+
+    /**
+     * Parses a structured filename into its date and name components.
+     *
+     * Algorithm: split stem on "_", identify the date token (first or last segment),
+     * treat the outermost remaining segment as firstName, rest as lastName parts.
+     * Compound last names (e.g. "de_Gruyter") are supported naturally.
+     * Returns null for unrecognised filenames.
+     *
+     * Examples:
+     *   18881025_de_Gruyter_Walter.pdf  → date=1888-10-25, firstName=Walter, lastName=de Gruyter
+     *   1965-03-12_Mueller_Hans.pdf     → date=1965-03-12, firstName=Hans,   lastName=Mueller
+     *   Mueller_Hans_19650312.pdf       → date=1965-03-12, firstName=Hans,   lastName=Mueller
+     */
+    private static ParsedFilename parseFilenameData(String filename) {
+        if (filename == null) return null;
+        int dot = filename.lastIndexOf('.');
+        if (dot < 0) return null;
+        String stem = filename.substring(0, dot);
+
+        String[] parts = stem.split("_", -1);
+        if (parts.length < 3) return null;
+
+        String dateIso;
+        String[] nameParts;
+
+        String dateFromFirst = tryParseDate(parts[0]);
+        if (dateFromFirst != null) {
+            dateIso = dateFromFirst;
+            nameParts = Arrays.copyOfRange(parts, 1, parts.length);
+        } else {
+            String dateFromLast = tryParseDate(parts[parts.length - 1]);
+            if (dateFromLast == null) return null;
+            dateIso = dateFromLast;
+            nameParts = Arrays.copyOfRange(parts, 0, parts.length - 1);
+        }
+
+        if (nameParts.length < 2) return null;
+        for (String p : nameParts) {
+            if (!p.matches("\\p{L}+")) return null;
+        }
+
+        String firstName = nameParts[nameParts.length - 1];
+        String lastName = String.join(" ", Arrays.copyOfRange(nameParts, 0, nameParts.length - 1));
+        return new ParsedFilename(LocalDate.parse(dateIso), firstName, lastName);
+    }
+
+    // Used by tests and as a public utility; delegates to parseFilenameData.
+    static String titleFromFilename(String filename) {
+        if (filename == null) return null;
+        ParsedFilename parsed = parseFilenameData(filename);
+        return parsed != null ? parsed.title() : stripExtension(filename);
+    }
+
+    private static String tryParseDate(String s) {
+        if (s.matches("\\d{4}-\\d{2}-\\d{2}")) {
+            int m = Integer.parseInt(s.substring(5, 7));
+            int d = Integer.parseInt(s.substring(8, 10));
+            if (m >= 1 && m <= 12 && d >= 1 && d <= 31) return s;
+        } else if (s.matches("\\d{8}")) {
+            int m = Integer.parseInt(s.substring(4, 6));
+            int d = Integer.parseInt(s.substring(6, 8));
+            if (m >= 1 && m <= 12 && d >= 1 && d <= 31)
+                return s.substring(0, 4) + "-" + s.substring(4, 6) + "-" + s.substring(6, 8);
+        }
+        return null;
+    }
+
+    private static String sha256Hex(byte[] bytes) {
+        try {
+            MessageDigest digest = MessageDigest.getInstance("SHA-256");
+            byte[] hash = digest.digest(bytes);
+            StringBuilder sb = new StringBuilder(64);
+            for (byte b : hash) {
+                sb.append(String.format("%02x", b));
+            }
+            return sb.toString();
+        } catch (NoSuchAlgorithmException e) {
+            throw new IllegalStateException("SHA-256 not available", e);
+        }
+    }
 }

backend/src/main/java/org/raddatz/familienarchiv/service/FileService.java

@@ -13,6 +13,9 @@ import org.springframework.web.multipart.MultipartFile;
 import org.springframework.core.io.InputStreamResource;
 
 import java.io.IOException;
+import java.io.InputStream;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
 import java.util.UUID;
 
 @Service
@@ -29,10 +32,14 @@ public class FileService {
     }
 
     /**
-     * Uploads a file to S3/MinIO and returns the generated object key.
+     * Uploads a file to S3/MinIO.
+     * Returns an {@link UploadResult} containing the S3 key and the SHA-256
+     * hash of the file content.  The hash is used to link annotations to the
+     * specific file version they were created against.
      */
-    public String uploadFile(MultipartFile file, String originalFilename) throws IOException {
+    public UploadResult uploadFile(MultipartFile file, String originalFilename) throws IOException {
-        // Generate secure unique path: "documents/UUID_filename"
+        byte[] bytes = file.getBytes();
+        String fileHash = sha256Hex(bytes);
         String s3Key = "documents/" + UUID.randomUUID() + "_" + originalFilename;
 
         try {
@@ -42,11 +49,10 @@ public class FileService {
                     .contentType(file.getContentType())
                     .build();
 
-            s3Client.putObject(putObjectRequest,
+            s3Client.putObject(putObjectRequest, RequestBody.fromBytes(bytes));
-                    RequestBody.fromInputStream(file.getInputStream(), file.getSize()));
 
-            log.info("Uploaded file to S3: {}", s3Key);
+            log.info("Uploaded file to S3: {} (hash={})", s3Key, fileHash);
-            return s3Key;
+            return new UploadResult(s3Key, fileHash);
         } catch (S3Exception e) {
             log.error("S3 Upload Error", e);
             throw new IOException("Failed to upload file to storage", e);
@@ -58,32 +64,72 @@ public class FileService {
      * Returns a wrapper containing the stream and content type.
      */
     public S3FileDownload downloadFile(String s3Key) {
-    try {
+        try {
-        GetObjectRequest getObjectRequest = GetObjectRequest.builder()
+            GetObjectRequest getObjectRequest = GetObjectRequest.builder()
-                .bucket(bucketName)
+                    .bucket(bucketName)
-                .key(s3Key)
+                    .key(s3Key)
-                .build();
+                    .build();
 
-        ResponseInputStream<GetObjectResponse> s3Object = s3Client.getObject(getObjectRequest);
+            ResponseInputStream<GetObjectResponse> s3Object = s3Client.getObject(getObjectRequest);
 
-        // Use whatever content type S3 has stored (set at upload time)
+            String contentType = s3Object.response().contentType();
-        String contentType = s3Object.response().contentType();
+            if (contentType == null || contentType.isBlank()) {
-        if (contentType == null || contentType.isBlank()) {
+                contentType = "application/octet-stream";
-            contentType = "application/octet-stream";
+            }
+
+            return new S3FileDownload(new InputStreamResource(s3Object), contentType);
+
+        } catch (NoSuchKeyException e) {
+            throw new StorageFileNotFoundException("File not found in storage: " + s3Key);
+        } catch (S3Exception e) {
+            throw new RuntimeException("Storage Error: " + e.getMessage());
         }
-
-        return new S3FileDownload(new InputStreamResource(s3Object), contentType);
-
-    } catch (NoSuchKeyException e) {
-        throw new StorageFileNotFoundException("File not found in storage: " + s3Key);
-    } catch (S3Exception e) {
-        throw new RuntimeException("Storage Error: " + e.getMessage());
     }
-}
+
-    // Helper Record to carry the stream and metadata back to the controller
+    /**
+     * Downloads a file from S3/MinIO and returns its raw bytes.
+     * Used for hash backfill — callers are responsible for not calling this on large files unnecessarily.
+     */
+    public byte[] downloadFileBytes(String s3Key) throws IOException {
+        try {
+            GetObjectRequest getObjectRequest = GetObjectRequest.builder()
+                    .bucket(bucketName)
+                    .key(s3Key)
+                    .build();
+            try (InputStream in = s3Client.getObject(getObjectRequest)) {
+                return in.readAllBytes();
+            }
+        } catch (NoSuchKeyException e) {
+            throw new StorageFileNotFoundException("File not found in storage: " + s3Key);
+        } catch (S3Exception e) {
+            throw new IOException("Failed to download file from storage: " + e.getMessage(), e);
+        }
+    }
+
+    // ─── private helpers ──────────────────────────────────────────────────────
+
+    private static String sha256Hex(byte[] bytes) {
+        try {
+            MessageDigest digest = MessageDigest.getInstance("SHA-256");
+            byte[] hash = digest.digest(bytes);
+            StringBuilder sb = new StringBuilder(64);
+            for (byte b : hash) {
+                sb.append(String.format("%02x", b));
+            }
+            return sb.toString();
+        } catch (NoSuchAlgorithmException e) {
+            throw new IllegalStateException("SHA-256 not available", e);
+        }
+    }
+
+    // ─── result types ─────────────────────────────────────────────────────────
+
+    /** Carries the S3 object key and the content hash back to the caller. */
+    public record UploadResult(String s3Key, String fileHash) {}
+
+    /** Carries the download stream and content type. */
     public record S3FileDownload(InputStreamResource resource, String contentType) {}
 
-    // Custom Exception
     public static class StorageFileNotFoundException extends RuntimeException {
         public StorageFileNotFoundException(String message) { super(message); }
     }

backend/src/main/java/org/raddatz/familienarchiv/service/MassImportService.java

@@ -312,6 +312,9 @@ public class MassImportService {
                 .originalFilename(originalFilename)
                 .build());
 
+        // Heuristic: mark as complete if at least one key field is present in the spreadsheet row
+        boolean metadataComplete = date != null || !senderRaw.isBlank() || !receiversRaw.isBlank();
+
         doc.setTitle(buildTitle(index, date, location));
         doc.setFilePath(s3Key);
         doc.setContentType(contentType);
@@ -325,6 +328,7 @@ public class MassImportService {
         doc.setSender(sender);
         doc.getReceivers().addAll(receivers);
         if (tag != null) doc.getTags().add(tag);
+        doc.setMetadataComplete(metadataComplete);
 
         documentRepository.save(doc);
         log.info("Importiert{}: {}", file.isEmpty() ? " (nur Metadaten)" : "", originalFilename);

backend/src/main/java/org/raddatz/familienarchiv/service/NotificationService.java

@@ -0,0 +1,210 @@
+package org.raddatz.familienarchiv.service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.raddatz.familienarchiv.dto.NotificationDTO;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.DocumentComment;
+import org.raddatz.familienarchiv.model.Notification;
+import org.raddatz.familienarchiv.model.NotificationType;
+import org.raddatz.familienarchiv.repository.NotificationRepository;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.mail.MailException;
+import org.springframework.mail.SimpleMailMessage;
+import org.springframework.mail.javamail.JavaMailSender;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Propagation;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+import java.util.UUID;
+import java.util.stream.Collectors;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class NotificationService {
+
+    private final NotificationRepository notificationRepository;
+    private final UserService userService;
+    private final DocumentService documentService;
+    private final Optional<JavaMailSender> mailSender;
+    private final SseEmitterRegistry sseEmitterRegistry;
+
+    @Value("${app.mail.from:noreply@familienarchiv.local}")
+    private String mailFrom;
+
+    @Value("${app.base-url:http://localhost:3000}")
+    private String baseUrl;
+
+    /**
+     * Creates REPLY notifications for all participants in the thread, excluding the replier.
+     * Runs in a separate transaction so a notification failure cannot roll back the parent comment.
+     */
+    @Transactional(propagation = Propagation.REQUIRES_NEW)
+    public void notifyReply(DocumentComment reply, Set<UUID> participantIds) {
+        if (participantIds.isEmpty()) return;
+
+        List<AppUser> recipients = userService.findAllById(participantIds);
+        for (AppUser recipient : recipients) {
+            Notification notification = Notification.builder()
+                    .recipient(recipient)
+                    .type(NotificationType.REPLY)
+                    .documentId(reply.getDocumentId())
+                    .referenceId(reply.getId())
+                    .annotationId(reply.getAnnotationId())
+                    .actorName(reply.getAuthorName())
+                    .build();
+            saveAndPush(notification);
+
+            if (recipient.isNotifyOnReply()) {
+                sendNotificationEmail(recipient, reply, NotificationType.REPLY);
+            }
+        }
+    }
+
+    /**
+     * Creates MENTION notifications for each mentioned user.
+     * Runs in a separate transaction so a notification failure cannot roll back the parent comment.
+     */
+    @Transactional(propagation = Propagation.REQUIRES_NEW)
+    public void notifyMentions(List<UUID> mentionedUserIds, DocumentComment comment) {
+        if (mentionedUserIds == null || mentionedUserIds.isEmpty()) return;
+
+        List<AppUser> recipients = userService.findAllById(mentionedUserIds);
+        for (AppUser recipient : recipients) {
+            Notification notification = Notification.builder()
+                    .recipient(recipient)
+                    .type(NotificationType.MENTION)
+                    .documentId(comment.getDocumentId())
+                    .referenceId(comment.getId())
+                    .annotationId(comment.getAnnotationId())
+                    .actorName(comment.getAuthorName())
+                    .build();
+            saveAndPush(notification);
+
+            if (recipient.isNotifyOnMention()) {
+                sendNotificationEmail(recipient, comment, NotificationType.MENTION);
+            }
+        }
+    }
+
+    public Page<NotificationDTO> getNotifications(UUID userId, NotificationType type, Boolean read, Pageable pageable) {
+        Page<Notification> page;
+        if (type != null && Boolean.FALSE.equals(read)) {
+            page = notificationRepository.findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(userId, type, pageable);
+        } else if (type != null) {
+            page = notificationRepository.findByRecipientIdAndTypeOrderByCreatedAtDesc(userId, type, pageable);
+        } else if (Boolean.FALSE.equals(read)) {
+            page = notificationRepository.findByRecipientIdAndReadFalseOrderByCreatedAtDesc(userId, pageable);
+        } else {
+            page = notificationRepository.findByRecipientIdOrderByCreatedAtDesc(userId, pageable);
+        }
+        return mapWithDocumentTitles(page);
+    }
+
+    private Page<NotificationDTO> mapWithDocumentTitles(Page<Notification> page) {
+        Set<UUID> documentIds = page.getContent().stream()
+                .map(Notification::getDocumentId)
+                .filter(id -> id != null)
+                .collect(Collectors.toSet());
+        Map<UUID, String> titles = documentService.findTitlesByIds(documentIds);
+        return page.map(n -> toDTO(n, titles));
+    }
+
+    public long countUnread(UUID userId) {
+        return notificationRepository.countByRecipientIdAndReadFalse(userId);
+    }
+
+    @Transactional
+    public void markAllRead(UUID userId) {
+        notificationRepository.markAllReadByRecipientId(userId);
+    }
+
+    @Transactional
+    public NotificationDTO markRead(UUID notificationId, UUID userId) {
+        Notification notification = notificationRepository.findById(notificationId)
+                .orElseThrow(() -> DomainException.notFound(
+                        ErrorCode.NOTIFICATION_NOT_FOUND, "Notification not found: " + notificationId));
+        if (!notification.getRecipient().getId().equals(userId)) {
+            throw DomainException.forbidden("Notification belongs to a different user");
+        }
+        notification.setRead(true);
+        return toDTO(notificationRepository.save(notification), Map.of());
+    }
+
+    @Transactional
+    public AppUser updatePreferences(UUID userId, boolean notifyOnReply, boolean notifyOnMention) {
+        return userService.updateNotificationPreferences(userId, notifyOnReply, notifyOnMention);
+    }
+
+    // ─── private helpers ──────────────────────────────────────────────────────
+
+    private void saveAndPush(Notification notification) {
+        Notification saved = notificationRepository.save(notification);
+        sseEmitterRegistry.send(saved.getRecipient().getId(), toDTO(saved, Map.of()));
+    }
+
+    private NotificationDTO toDTO(Notification n, Map<UUID, String> titles) {
+        return new NotificationDTO(
+                n.getId(),
+                n.getType(),
+                n.getDocumentId(),
+                n.getReferenceId(),
+                n.getAnnotationId(),
+                n.isRead(),
+                n.getCreatedAt(),
+                n.getActorName(),
+                n.getDocumentId() != null ? titles.get(n.getDocumentId()) : null
+        );
+    }
+
+    private void buildCommentPath(DocumentComment comment, StringBuilder sb) {
+        sb.append("?commentId=").append(comment.getId());
+        if (comment.getAnnotationId() != null) {
+            sb.append("&annotationId=").append(comment.getAnnotationId());
+        }
+    }
+
+    private void sendNotificationEmail(AppUser recipient, DocumentComment comment, NotificationType type) {
+        if (mailSender.isEmpty()) {
+            log.warn("Mail sender not configured — skipping notification email to {}", recipient.getEmail());
+            return;
+        }
+        if (recipient.getEmail() == null || recipient.getEmail().isBlank()) return;
+
+        StringBuilder path = new StringBuilder("/documents/").append(comment.getDocumentId());
+        buildCommentPath(comment, path);
+        String link = baseUrl + path;
+
+        String subject = type == NotificationType.REPLY
+                ? "Neue Antwort auf deinen Kommentar — Familienarchiv"
+                : "Du wurdest in einem Kommentar erwähnt — Familienarchiv";
+
+        String body = type == NotificationType.REPLY
+                ? "Hallo,\n\njemand hat auf einen Kommentar geantwortet, an dem du beteiligt warst.\n\n"
+                + "Zum Kommentar:\n" + link + "\n\nDein Familienarchiv-Team"
+                : "Hallo,\n\njemand hat dich in einem Kommentar erwähnt.\n\n"
+                + "Zum Kommentar:\n" + link + "\n\nDein Familienarchiv-Team";
+
+        SimpleMailMessage message = new SimpleMailMessage();
+        message.setFrom(mailFrom);
+        message.setTo(recipient.getEmail());
+        message.setSubject(subject);
+        message.setText(body);
+
+        try {
+            mailSender.get().send(message);
+        } catch (MailException e) {
+            log.error("Failed to send notification email to {}: {}", recipient.getEmail(), e.getMessage());
+        }
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/service/PersonNameParser.java

@@ -1,6 +1,7 @@
 package org.raddatz.familienarchiv.service;
 
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
@@ -20,6 +21,7 @@ public class PersonNameParser {
     private static final Pattern GEB_PATTERN = Pattern.compile("\\s+geb\\.\\s+\\S+");
     private static final Pattern PAREN_LAST_NAME = Pattern.compile("\\(([^)]+)\\)\\s*$");
     private static final Pattern MULTI_SEPARATOR = Pattern.compile("\\s+(?:und|u)\\s+");
+    private static final Pattern SLASH_SEPARATOR = Pattern.compile("//");
 
     public record SplitName(String firstName, String lastName) {}
 
@@ -38,6 +40,16 @@ public class PersonNameParser {
     public static List<String> parseReceivers(String raw) {
         if (raw == null || raw.isBlank()) return List.of();
 
+        // 0. Pre-split on "//" — each segment is an independent name entry
+        String[] slashParts = SLASH_SEPARATOR.split(raw, -1);
+        if (slashParts.length > 1) {
+            return Arrays.stream(slashParts)
+                    .map(String::trim)
+                    .filter(s -> !s.isBlank())
+                    .flatMap(segment -> parseReceivers(segment).stream())
+                    .toList();
+        }
+
         // 1. Strip "geb. Xxx" maiden-name annotations
         String cleaned = GEB_PATTERN.matcher(raw).replaceAll("").trim();
 
@@ -111,6 +123,11 @@ public class PersonNameParser {
 
         String cleaned = GEB_PATTERN.matcher(rawName).replaceAll("").trim();
 
+        // Normalize dot-compressed names: "Dr.Fr.Zarncke" -> "Dr. Fr. Zarncke"
+        if (!cleaned.contains(" ") && cleaned.contains(".")) {
+            cleaned = cleaned.replace(".", ". ").trim();
+        }
+
         String lastName = findKnownLastName(cleaned);
         if (lastName != null) {
             String firstName = cleaned.substring(0, cleaned.length() - lastName.length()).trim();

backend/src/main/java/org/raddatz/familienarchiv/service/PersonService.java

@@ -1,10 +1,17 @@
 package org.raddatz.familienarchiv.service;
 
 import java.util.List;
+import java.util.Optional;
 import java.util.UUID;
 
+import org.raddatz.familienarchiv.dto.PersonNameAliasDTO;
+import org.raddatz.familienarchiv.dto.PersonSummaryDTO;
 import org.raddatz.familienarchiv.dto.PersonUpdateDTO;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
 import org.raddatz.familienarchiv.model.Person;
+import org.raddatz.familienarchiv.model.PersonNameAlias;
+import org.raddatz.familienarchiv.repository.PersonNameAliasRepository;
 import org.raddatz.familienarchiv.repository.PersonRepository;
 import org.springframework.http.HttpStatus;
 import org.springframework.stereotype.Service;
@@ -18,17 +25,21 @@ import lombok.RequiredArgsConstructor;
 public class PersonService {
 
     private final PersonRepository personRepository;
+    private final PersonNameAliasRepository aliasRepository;
 
-    public List<Person> findAll(String q) {
+    public List<PersonSummaryDTO> findAll(String q) {
-        if (q != null && !q.isBlank()) {
+        if (q == null) {
-            return personRepository.searchByName(q);
+            return personRepository.findAllWithDocumentCount();
         }
-        return personRepository.findAllByOrderByLastNameAscFirstNameAsc();
+        if (q.isBlank()) {
+            return List.of();
+        }
+        return personRepository.searchWithDocumentCount(q.trim());
     }
 
     public Person getById(UUID id) {
         return personRepository.findById(id)
-                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "Person nicht gefunden"));
+                .orElseThrow(() -> DomainException.notFound(ErrorCode.PERSON_NOT_FOUND, "Person not found: " + id));
     }
 
     public List<Person> findCorrespondents(UUID personId, String q) {
@@ -42,6 +53,10 @@ public class PersonService {
         return personRepository.findAllById(ids);
     }
 
+    public Optional<Person> findByName(String firstName, String lastName) {
+        return personRepository.findByFirstNameIgnoreCaseAndLastNameIgnoreCase(firstName, lastName);
+    }
+
     @Transactional
     public Person findOrCreateByAlias(String rawName) {
         String alias = rawName.trim();
@@ -66,12 +81,36 @@ public class PersonService {
     }
 
     @Transactional
-    public Person updatePerson(UUID id, PersonUpdateDTO dto) {
+    public Person createPerson(PersonUpdateDTO dto) {
-        if (dto.getBirthYear() != null && dto.getDeathYear() != null && dto.getBirthYear() > dto.getDeathYear()) {
+        validateYears(dto.getBirthYear(), dto.getDeathYear());
+        Person person = Person.builder()
+                .firstName(dto.getFirstName())
+                .lastName(dto.getLastName())
+                .alias(dto.getAlias() == null || dto.getAlias().isBlank() ? null : dto.getAlias().trim())
+                .notes(dto.getNotes() == null || dto.getNotes().isBlank() ? null : dto.getNotes().trim())
+                .birthYear(dto.getBirthYear())
+                .deathYear(dto.getDeathYear())
+                .build();
+        return personRepository.save(person);
+    }
+
+    private void validateYears(Integer birthYear, Integer deathYear) {
+        if (birthYear != null && birthYear <= 0) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Geburtsjahr muss eine positive Zahl sein");
+        }
+        if (deathYear != null && deathYear <= 0) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Todesjahr muss eine positive Zahl sein");
+        }
+        if (birthYear != null && deathYear != null && birthYear > deathYear) {
             throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Geburtsjahr darf nicht nach dem Todesjahr liegen");
         }
+    }
+
+    @Transactional
+    public Person updatePerson(UUID id, PersonUpdateDTO dto) {
+        validateYears(dto.getBirthYear(), dto.getDeathYear());
         Person person = personRepository.findById(id)
-                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "Person nicht gefunden"));
+                .orElseThrow(() -> DomainException.notFound(ErrorCode.PERSON_NOT_FOUND, "Person not found: " + id));
         person.setFirstName(dto.getFirstName());
         person.setLastName(dto.getLastName());
         person.setAlias(dto.getAlias() == null || dto.getAlias().isBlank() ? null : dto.getAlias().trim());
@@ -87,9 +126,9 @@ public class PersonService {
             throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Quelle und Ziel dürfen nicht identisch sein");
         }
         personRepository.findById(sourceId)
-                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "Quell-Person nicht gefunden"));
+                .orElseThrow(() -> DomainException.notFound(ErrorCode.PERSON_NOT_FOUND, "Source person not found: " + sourceId));
         personRepository.findById(targetId)
-                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "Ziel-Person nicht gefunden"));
+                .orElseThrow(() -> DomainException.notFound(ErrorCode.PERSON_NOT_FOUND, "Target person not found: " + targetId));
 
         // Reassign sender references
         personRepository.reassignSender(sourceId, targetId);
@@ -102,4 +141,35 @@ public class PersonService {
 
         personRepository.deleteById(sourceId);
     }
+
+    // ─── Alias management ───────────────────────────────────────────────────
+
+    public List<PersonNameAlias> getAliases(UUID personId) {
+        getById(personId);
+        return aliasRepository.findByPersonIdOrderBySortOrderAscCreatedAtAsc(personId);
+    }
+
+    @Transactional
+    public PersonNameAlias addAlias(UUID personId, PersonNameAliasDTO dto) {
+        Person person = getById(personId);
+        int nextSortOrder = aliasRepository.findMaxSortOrder(personId) + 1;
+        PersonNameAlias alias = PersonNameAlias.builder()
+                .person(person)
+                .lastName(dto.lastName())
+                .firstName(dto.firstName())
+                .type(dto.type())
+                .sortOrder(nextSortOrder)
+                .build();
+        return aliasRepository.save(alias);
+    }
+
+    @Transactional
+    public void removeAlias(UUID personId, UUID aliasId) {
+        PersonNameAlias alias = aliasRepository.findById(aliasId)
+                .orElseThrow(() -> DomainException.notFound(ErrorCode.ALIAS_NOT_FOUND, "Alias not found: " + aliasId));
+        if (!alias.getPerson().getId().equals(personId)) {
+            throw DomainException.forbidden("Alias does not belong to this person");
+        }
+        aliasRepository.delete(alias);
+    }
 }

backend/src/main/java/org/raddatz/familienarchiv/service/SseEmitterRegistry.java

@@ -0,0 +1,36 @@
+package org.raddatz.familienarchiv.service;
+
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
+
+import java.io.IOException;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+
+@Component
+@Slf4j
+public class SseEmitterRegistry {
+
+    private final ConcurrentHashMap<UUID, SseEmitter> emitters = new ConcurrentHashMap<>();
+
+    public SseEmitter register(UUID userId) {
+        SseEmitter emitter = new SseEmitter(0L); // 0 = no timeout; EventSource reconnects automatically
+        emitters.put(userId, emitter);
+        emitter.onCompletion(() -> emitters.remove(userId, emitter));
+        emitter.onTimeout(()    -> emitters.remove(userId, emitter));
+        emitter.onError(e  ->    emitters.remove(userId, emitter));
+        return emitter;
+    }
+
+    public void send(UUID userId, Object data) {
+        SseEmitter emitter = emitters.get(userId);
+        if (emitter == null) return;
+        try {
+            emitter.send(SseEmitter.event().name("notification").data(data));
+        } catch (IOException e) {
+            log.debug("SSE send failed for user {} — removing emitter", userId);
+            emitters.remove(userId, emitter);
+        }
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/service/TranscriptionService.java

@@ -0,0 +1,140 @@
+package org.raddatz.familienarchiv.service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.raddatz.familienarchiv.dto.CreateAnnotationDTO;
+import org.raddatz.familienarchiv.dto.CreateTranscriptionBlockDTO;
+import org.raddatz.familienarchiv.dto.ReorderTranscriptionBlocksDTO;
+import org.raddatz.familienarchiv.dto.UpdateTranscriptionBlockDTO;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentAnnotation;
+import org.raddatz.familienarchiv.model.TranscriptionBlock;
+import org.raddatz.familienarchiv.model.TranscriptionBlockVersion;
+import org.raddatz.familienarchiv.repository.AnnotationRepository;
+import org.raddatz.familienarchiv.repository.TranscriptionBlockRepository;
+import org.raddatz.familienarchiv.repository.TranscriptionBlockVersionRepository;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+import java.util.UUID;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class TranscriptionService {
+
+    private static final String TRANSCRIPTION_COLOR = "#00C7B1";
+    private static final int MAX_TEXT_LENGTH = 10_000;
+
+    private final TranscriptionBlockRepository blockRepository;
+    private final TranscriptionBlockVersionRepository versionRepository;
+    private final AnnotationRepository annotationRepository;
+    private final AnnotationService annotationService;
+    private final DocumentService documentService;
+
+    public List<TranscriptionBlock> listBlocks(UUID documentId) {
+        return blockRepository.findByDocumentIdOrderBySortOrderAsc(documentId);
+    }
+
+    public TranscriptionBlock getBlock(UUID documentId, UUID blockId) {
+        return blockRepository.findByIdAndDocumentId(blockId, documentId)
+                .orElseThrow(() -> DomainException.notFound(
+                        ErrorCode.TRANSCRIPTION_BLOCK_NOT_FOUND,
+                        "Transcription block not found: " + blockId));
+    }
+
+    @Transactional
+    public TranscriptionBlock createBlock(UUID documentId, CreateTranscriptionBlockDTO dto, UUID userId) {
+        Document doc = documentService.getDocumentById(documentId);
+
+        CreateAnnotationDTO annotationDTO = new CreateAnnotationDTO(
+                dto.getPageNumber(), dto.getX(), dto.getY(),
+                dto.getWidth(), dto.getHeight(), TRANSCRIPTION_COLOR);
+        DocumentAnnotation annotation = annotationService.createAnnotation(
+                documentId, annotationDTO, userId, doc.getFileHash());
+
+        int nextOrder = blockRepository.countByDocumentId(documentId);
+        String text = sanitizeText(dto.getText());
+
+        TranscriptionBlock block = TranscriptionBlock.builder()
+                .annotationId(annotation.getId())
+                .documentId(documentId)
+                .text(text)
+                .label(dto.getLabel())
+                .sortOrder(nextOrder)
+                .createdBy(userId)
+                .updatedBy(userId)
+                .build();
+
+        TranscriptionBlock saved = blockRepository.save(block);
+        saveVersion(saved, userId);
+        log.info("Created transcription block {} for document {}", saved.getId(), documentId);
+        return saved;
+    }
+
+    @Transactional
+    public TranscriptionBlock updateBlock(UUID documentId, UUID blockId,
+                                          UpdateTranscriptionBlockDTO dto, UUID userId) {
+        TranscriptionBlock block = getBlock(documentId, blockId);
+
+        String text = sanitizeText(dto.getText());
+        block.setText(text);
+        if (dto.getLabel() != null) {
+            block.setLabel(dto.getLabel());
+        }
+        block.setUpdatedBy(userId);
+
+        TranscriptionBlock saved = blockRepository.save(block);
+        saveVersion(saved, userId);
+        return saved;
+    }
+
+    @Transactional
+    public void deleteBlock(UUID documentId, UUID blockId) {
+        TranscriptionBlock block = getBlock(documentId, blockId);
+        UUID annotationId = block.getAnnotationId();
+
+        // Block is the aggregate root — delete block first (cascades to versions + comments),
+        // then delete the dependent annotation directly (no ownership check needed)
+        blockRepository.delete(block);
+        blockRepository.flush();
+        annotationRepository.deleteById(annotationId);
+        log.info("Deleted transcription block {} and annotation {} for document {}",
+                blockId, annotationId, documentId);
+    }
+
+    @Transactional
+    public void reorderBlocks(UUID documentId, ReorderTranscriptionBlocksDTO dto) {
+        List<UUID> blockIds = dto.getBlockIds();
+        for (int i = 0; i < blockIds.size(); i++) {
+            TranscriptionBlock block = getBlock(documentId, blockIds.get(i));
+            block.setSortOrder(i);
+            blockRepository.save(block);
+        }
+    }
+
+    public List<TranscriptionBlockVersion> getBlockHistory(UUID documentId, UUID blockId) {
+        getBlock(documentId, blockId);
+        return versionRepository.findByBlockIdOrderByChangedAtDesc(blockId);
+    }
+
+    private void saveVersion(TranscriptionBlock block, UUID userId) {
+        TranscriptionBlockVersion version = TranscriptionBlockVersion.builder()
+                .blockId(block.getId())
+                .text(block.getText())
+                .changedBy(userId)
+                .build();
+        versionRepository.save(version);
+    }
+
+    String sanitizeText(String text) {
+        if (text == null) return "";
+        if (text.length() > MAX_TEXT_LENGTH) {
+            text = text.substring(0, MAX_TEXT_LENGTH);
+        }
+        return text;
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/service/UserSearchService.java

@@ -0,0 +1,23 @@
+package org.raddatz.familienarchiv.service;
+
+import lombok.RequiredArgsConstructor;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.repository.AppUserRepository;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.stereotype.Service;
+
+import java.util.List;
+
+@Service
+@RequiredArgsConstructor
+public class UserSearchService {
+
+    private static final int MAX_RESULTS = 10;
+
+    private final AppUserRepository userRepository;
+
+    public List<AppUser> search(String query) {
+        if (query == null || query.isBlank()) return List.of();
+        return userRepository.searchByNameOrUsername(query.trim(), PageRequest.of(0, MAX_RESULTS));
+    }
+}

backend/src/main/java/org/raddatz/familienarchiv/service/UserService.java

@@ -18,6 +18,7 @@ import org.springframework.security.crypto.password.PasswordEncoder;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
+import java.util.Collection;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Optional;
@@ -78,6 +79,18 @@ public class UserService {
                 .orElseThrow(() -> DomainException.notFound(ErrorCode.USER_NOT_FOUND, "No user found for id: " + id));
     }
 
+    public List<AppUser> findAllById(Collection<UUID> ids) {
+        return userRepository.findAllById(ids);
+    }
+
+    @Transactional
+    public AppUser updateNotificationPreferences(UUID userId, boolean notifyOnReply, boolean notifyOnMention) {
+        AppUser user = getById(userId);
+        user.setNotifyOnReply(notifyOnReply);
+        user.setNotifyOnMention(notifyOnMention);
+        return userRepository.save(user);
+    }
+
     @Transactional
     public AppUser updateProfile(UUID userId, UpdateProfileDTO dto) {
         AppUser user = getById(userId);

backend/src/main/resources/application.yaml

@@ -12,6 +12,7 @@ spring:
     enabled: false  # Managed explicitly via FlywayConfig bean
 
   jpa:
+    open-in-view: false  # Prevents holding DB connections for the full HTTP request lifecycle
     hibernate:
       ddl-auto: none
     properties:

backend/src/main/resources/db/migration/V13__add_file_hash.sql

@@ -0,0 +1,7 @@
+-- Add content-based file hash to documents for annotation versioning
+ALTER TABLE documents
+    ADD COLUMN file_hash VARCHAR(64);
+
+-- Each annotation remembers which file version it was created against
+ALTER TABLE document_annotations
+    ADD COLUMN file_hash VARCHAR(64);

backend/src/main/resources/db/migration/V14__add_cascade_delete_to_document_join_tables.sql

@@ -0,0 +1,12 @@
+-- Add ON DELETE CASCADE to document_tags and document_receivers so that
+-- deleting a document automatically removes its tag and receiver associations.
+
+ALTER TABLE public.document_tags
+    DROP CONSTRAINT fkc99c5qjulwx9gru07yrhicgd2,
+    ADD CONSTRAINT fkc99c5qjulwx9gru07yrhicgd2
+        FOREIGN KEY (document_id) REFERENCES public.documents(id) ON DELETE CASCADE;
+
+ALTER TABLE public.document_receivers
+    DROP CONSTRAINT fks7t60twjgfmpeqcuc3g0fvjpm,
+    ADD CONSTRAINT fks7t60twjgfmpeqcuc3g0fvjpm
+        FOREIGN KEY (document_id) REFERENCES public.documents(id) ON DELETE CASCADE;

backend/src/main/resources/db/migration/V15__add_metadata_complete_to_documents.sql

@@ -0,0 +1,6 @@
+-- Add metadata_complete flag to documents.
+-- Existing rows default to true (already reviewed before this feature existed).
+-- New documents created via Java will receive false from the entity default.
+
+ALTER TABLE documents
+    ADD COLUMN metadata_complete BOOLEAN NOT NULL DEFAULT TRUE;

backend/src/main/resources/db/migration/V16__notifications_and_preferences.sql

@@ -0,0 +1,18 @@
+-- Notification preferences on the user record — no separate entity needed
+ALTER TABLE users ADD COLUMN notify_on_reply   BOOLEAN NOT NULL DEFAULT false;
+ALTER TABLE users ADD COLUMN notify_on_mention BOOLEAN NOT NULL DEFAULT false;
+
+-- In-app notifications
+CREATE TABLE notifications (
+    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    recipient_id  UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    type          VARCHAR(32) NOT NULL,  -- 'REPLY' | 'MENTION'
+    document_id   UUID,
+    reference_id  UUID,                  -- commentId that triggered this notification
+    annotation_id UUID,
+    read          BOOLEAN NOT NULL DEFAULT false,
+    created_at    TIMESTAMP NOT NULL DEFAULT now(),
+    actor_name    VARCHAR(255)
+);
+
+CREATE INDEX idx_notifications_recipient ON notifications(recipient_id, read, created_at DESC);

backend/src/main/resources/db/migration/V17__comment_mentions.sql

@@ -0,0 +1,5 @@
+CREATE TABLE comment_mentions (
+    comment_id UUID NOT NULL REFERENCES document_comments(id) ON DELETE CASCADE,
+    user_id    UUID NOT NULL REFERENCES users(id)             ON DELETE CASCADE,
+    PRIMARY KEY (comment_id, user_id)
+);

backend/src/main/resources/db/migration/V18__add_transcription_blocks.sql

@@ -0,0 +1,16 @@
+CREATE TABLE transcription_blocks (
+    id            UUID             PRIMARY KEY DEFAULT gen_random_uuid(),
+    annotation_id UUID             NOT NULL REFERENCES document_annotations(id) ON DELETE RESTRICT,
+    document_id   UUID             NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    text          TEXT             NOT NULL DEFAULT '' CHECK (length(text) <= 10000),
+    label         VARCHAR(200),
+    sort_order    INTEGER          NOT NULL DEFAULT 0,
+    version       INTEGER          NOT NULL DEFAULT 0,
+    created_by    UUID             REFERENCES users(id) ON DELETE SET NULL,
+    updated_by    UUID             REFERENCES users(id) ON DELETE SET NULL,
+    created_at    TIMESTAMP        NOT NULL DEFAULT now(),
+    updated_at    TIMESTAMP        NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_tb_document_sort ON transcription_blocks(document_id, sort_order);
+CREATE INDEX idx_tb_annotation    ON transcription_blocks(annotation_id);

backend/src/main/resources/db/migration/V19__add_transcription_block_versions.sql

@@ -0,0 +1,9 @@
+CREATE TABLE transcription_block_versions (
+    id         UUID      PRIMARY KEY DEFAULT gen_random_uuid(),
+    block_id   UUID      NOT NULL REFERENCES transcription_blocks(id) ON DELETE CASCADE,
+    text       TEXT      NOT NULL,
+    changed_by UUID      REFERENCES users(id) ON DELETE SET NULL,
+    changed_at TIMESTAMP NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_tbv_block ON transcription_block_versions(block_id, changed_at DESC);

backend/src/main/resources/db/migration/V20__add_block_id_to_comments.sql

@@ -0,0 +1,4 @@
+ALTER TABLE document_comments
+    ADD COLUMN block_id UUID REFERENCES transcription_blocks(id) ON DELETE CASCADE;
+
+CREATE INDEX idx_dc_block ON document_comments(block_id);

backend/src/main/resources/db/migration/V21__add_person_name_aliases.sql

@@ -0,0 +1,22 @@
+-- Enable pg_trgm for substring search via GIN indexes
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+
+-- Historical name aliases for persons (marriage, widowhood, etc.)
+CREATE TABLE person_name_aliases (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    person_id   UUID NOT NULL REFERENCES persons(id) ON DELETE CASCADE,
+    last_name   VARCHAR(255) NOT NULL,
+    first_name  VARCHAR(255),
+    type        VARCHAR(50) NOT NULL,
+    sort_order  INTEGER NOT NULL DEFAULT 0,
+    created_at  TIMESTAMPTZ DEFAULT now()
+);
+
+-- Indexes on alias table
+CREATE INDEX idx_aliases_person_id ON person_name_aliases(person_id);
+CREATE INDEX idx_aliases_last_name_trgm ON person_name_aliases USING GIN (lower(last_name) gin_trgm_ops);
+
+-- Retroactive GIN trigram indexes on existing persons table for substring search
+CREATE INDEX idx_persons_first_name_trgm ON persons USING GIN (lower(first_name) gin_trgm_ops);
+CREATE INDEX idx_persons_last_name_trgm ON persons USING GIN (lower(last_name) gin_trgm_ops);
+CREATE INDEX idx_persons_alias_trgm ON persons USING GIN (lower(alias) gin_trgm_ops);

backend/src/test/java/org/raddatz/familienarchiv/ApplicationContextTest.java

@@ -0,0 +1,25 @@
+package org.raddatz.familienarchiv;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
+import org.springframework.context.annotation.Import;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.testcontainers.containers.PostgreSQLContainer;
+import software.amazon.awssdk.services.s3.S3Client;
+
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
+@ActiveProfiles("test")
+@Import(PostgresContainerConfig.class)
+class ApplicationContextTest {
+
+    @MockitoBean
+    S3Client s3Client;
+
+    @Test
+    void contextLoads() {
+        // verifies that the Spring context starts successfully with all beans wired,
+        // Flyway migrations applied, and no configuration errors
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/PostgresContainerConfig.java

@@ -0,0 +1,16 @@
+package org.raddatz.familienarchiv;
+
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
+import org.springframework.context.annotation.Bean;
+import org.testcontainers.containers.PostgreSQLContainer;
+
+@TestConfiguration(proxyBeanMethods = false)
+public class PostgresContainerConfig {
+
+    @Bean
+    @ServiceConnection
+    PostgreSQLContainer<?> postgresContainer() {
+        return new PostgreSQLContainer<>("postgres:16-alpine");
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/controller/AdminControllerTest.java

@@ -58,4 +58,29 @@ class AdminControllerTest {
                 .andExpect(status().isOk())
                 .andExpect(jsonPath("$.count").value(1));
     }
+
+    // ─── POST /api/admin/backfill-file-hashes ──────────────────────────────────
+
+    @Test
+    void backfillFileHashes_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(post("/api/admin/backfill-file-hashes"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(roles = "USER")
+    void backfillFileHashes_returns403_whenNotAdmin() throws Exception {
+        mockMvc.perform(post("/api/admin/backfill-file-hashes"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "ADMIN")
+    void backfillFileHashes_returns200_withCount_whenAdmin() throws Exception {
+        when(documentService.backfillFileHashes()).thenReturn(3);
+
+        mockMvc.perform(post("/api/admin/backfill-file-hashes"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.count").value(3));
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/controller/AnnotationControllerTest.java

@@ -4,10 +4,12 @@ import org.junit.jupiter.api.Test;
 import org.raddatz.familienarchiv.config.SecurityConfig;
 import org.raddatz.familienarchiv.exception.DomainException;
 import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.model.Document;
 import org.raddatz.familienarchiv.model.DocumentAnnotation;
 import org.raddatz.familienarchiv.security.PermissionAspect;
 import org.raddatz.familienarchiv.service.AnnotationService;
 import org.raddatz.familienarchiv.service.CustomUserDetailsService;
+import org.raddatz.familienarchiv.service.DocumentService;
 import org.raddatz.familienarchiv.service.UserService;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration;
@@ -36,6 +38,7 @@ class AnnotationControllerTest {
     @Autowired MockMvc mockMvc;
 
     @MockitoBean AnnotationService annotationService;
+    @MockitoBean DocumentService documentService;
     @MockitoBean UserService userService;
     @MockitoBean CustomUserDetailsService customUserDetailsService;
 
@@ -78,6 +81,29 @@ class AnnotationControllerTest {
                 .andExpect(status().isForbidden());
     }
 
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void createAnnotation_returns201_whenHasWriteAllPermission() throws Exception {
+        UUID docId = UUID.randomUUID();
+        DocumentAnnotation saved = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.1).y(0.1).width(0.2).height(0.2).color("#ff0000").build();
+        when(documentService.getDocumentById(any())).thenReturn(Document.builder().build());
+        when(annotationService.createAnnotation(any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + docId + "/annotations")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(ANNOTATION_JSON))
+                .andExpect(status().isCreated());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void deleteAnnotation_returns204_whenHasWriteAllPermission() throws Exception {
+        mockMvc.perform(delete("/api/documents/" + UUID.randomUUID() + "/annotations/" + UUID.randomUUID()))
+                .andExpect(status().isNoContent());
+    }
+
     @Test
     @WithMockUser(authorities = "ANNOTATE_ALL")
     void createAnnotation_returns201_whenHasAnnotatePermission() throws Exception {
@@ -85,7 +111,8 @@ class AnnotationControllerTest {
         DocumentAnnotation saved = DocumentAnnotation.builder()
                 .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
                 .x(0.1).y(0.1).width(0.2).height(0.2).color("#ff0000").build();
-        when(annotationService.createAnnotation(any(), any(), any())).thenReturn(saved);
+        when(documentService.getDocumentById(any())).thenReturn(Document.builder().build());
+        when(annotationService.createAnnotation(any(), any(), any(), any())).thenReturn(saved);
 
         mockMvc.perform(post("/api/documents/" + docId + "/annotations")
                         .contentType(MediaType.APPLICATION_JSON)
@@ -97,7 +124,8 @@ class AnnotationControllerTest {
     @Test
     @WithMockUser(authorities = "ANNOTATE_ALL")
     void createAnnotation_returns409_whenOverlap() throws Exception {
-        when(annotationService.createAnnotation(any(), any(), any()))
+        when(documentService.getDocumentById(any())).thenReturn(Document.builder().build());
+        when(annotationService.createAnnotation(any(), any(), any(), any()))
                 .thenThrow(DomainException.conflict(ErrorCode.ANNOTATION_OVERLAP, "Overlap"));
 
         mockMvc.perform(post("/api/documents/" + UUID.randomUUID() + "/annotations")
@@ -127,4 +155,51 @@ class AnnotationControllerTest {
         mockMvc.perform(delete("/api/documents/" + UUID.randomUUID() + "/annotations/" + UUID.randomUUID()))
                 .andExpect(status().isNoContent());
     }
+
+    // ─── resolveUserId — unauthenticated / null user / exception branches ─────
+
+    @Test
+    void createAnnotation_returns401_whenUnauthenticated_resolveUserIdReturnsNull() throws Exception {
+        // authentication == null → resolveUserId returns null
+        mockMvc.perform(post("/api/documents/" + UUID.randomUUID() + "/annotations")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(ANNOTATION_JSON))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(authorities = "ANNOTATE_ALL")
+    void createAnnotation_resolvesNullUserId_whenUserServiceThrows() throws Exception {
+        // findByUsername throws → catch block → resolveUserId returns null
+        UUID docId = UUID.randomUUID();
+        when(userService.findByUsername(any())).thenThrow(new RuntimeException("DB error"));
+        DocumentAnnotation saved = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.1).y(0.1).width(0.2).height(0.2).color("#ff0000").build();
+        when(documentService.getDocumentById(any())).thenReturn(Document.builder().build());
+        when(annotationService.createAnnotation(any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + docId + "/annotations")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(ANNOTATION_JSON))
+                .andExpect(status().isCreated());
+    }
+
+    @Test
+    @WithMockUser(authorities = "ANNOTATE_ALL")
+    void createAnnotation_resolvesNullUserId_whenUserServiceReturnsNull() throws Exception {
+        // findByUsername returns null → user != null = false → resolveUserId returns null
+        UUID docId = UUID.randomUUID();
+        when(userService.findByUsername(any())).thenReturn(null);
+        DocumentAnnotation saved = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.1).y(0.1).width(0.2).height(0.2).color("#ff0000").build();
+        when(documentService.getDocumentById(any())).thenReturn(Document.builder().build());
+        when(annotationService.createAnnotation(any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + docId + "/annotations")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(ANNOTATION_JSON))
+                .andExpect(status().isCreated());
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/controller/CommentControllerTest.java

@@ -81,7 +81,7 @@ class CommentControllerTest {
     void postDocumentComment_returns201_whenHasPermission() throws Exception {
         DocumentComment saved = DocumentComment.builder()
                 .id(COMMENT_ID).documentId(DOC_ID).authorName("Hans").content("Test comment").build();
-        when(commentService.postComment(any(), any(), any(), any())).thenReturn(saved);
+        when(commentService.postComment(any(), any(), any(), any(), any())).thenReturn(saved);
 
         mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments")
                         .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
@@ -89,6 +89,18 @@ class CommentControllerTest {
                 .andExpect(jsonPath("$.content").value("Test comment"));
     }
 
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void postDocumentComment_returns201_whenHasWriteAllPermission() throws Exception {
+        DocumentComment saved = DocumentComment.builder()
+                .id(COMMENT_ID).documentId(DOC_ID).authorName("Hans").content("Test comment").build();
+        when(commentService.postComment(any(), any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isCreated());
+    }
+
     // ─── POST /api/documents/{documentId}/comments/{commentId}/replies ────────
 
     @Test
@@ -104,7 +116,20 @@ class CommentControllerTest {
         DocumentComment saved = DocumentComment.builder()
                 .id(UUID.randomUUID()).documentId(DOC_ID).parentId(COMMENT_ID)
                 .authorName("Anna").content("Test comment").build();
-        when(commentService.replyToComment(any(), any(), any(), any())).thenReturn(saved);
+        when(commentService.replyToComment(any(), any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments/" + COMMENT_ID + "/replies")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isCreated());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void replyToComment_returns201_whenHasWriteAllPermission() throws Exception {
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(DOC_ID).parentId(COMMENT_ID)
+                .authorName("Anna").content("Test comment").build();
+        when(commentService.replyToComment(any(), any(), any(), any(), any())).thenReturn(saved);
 
         mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments/" + COMMENT_ID + "/replies")
                         .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
@@ -163,6 +188,18 @@ class CommentControllerTest {
                 .andExpect(status().isOk());
     }
 
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void editComment_returns200_whenHasWriteAllPermission() throws Exception {
+        DocumentComment updated = DocumentComment.builder()
+                .id(COMMENT_ID).documentId(DOC_ID).authorName("Hans").content("Test comment").build();
+        when(commentService.editComment(any(), any(), any(), any())).thenReturn(updated);
+
+        mockMvc.perform(patch("/api/documents/" + DOC_ID + "/comments/" + COMMENT_ID)
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isOk());
+    }
+
     // ─── POST /api/documents/{documentId}/annotations/{annId}/comments ────────
 
     @Test
@@ -179,7 +216,20 @@ class CommentControllerTest {
         DocumentComment saved = DocumentComment.builder()
                 .id(UUID.randomUUID()).documentId(DOC_ID).annotationId(ANN_ID)
                 .authorName("Hans").content("Test comment").build();
-        when(commentService.postComment(any(), any(), any(), any())).thenReturn(saved);
+        when(commentService.postComment(any(), any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/annotations/" + ANN_ID + "/comments")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isCreated());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void postAnnotationComment_returns201_whenHasWriteAllPermission() throws Exception {
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(DOC_ID).annotationId(ANN_ID)
+                .authorName("Hans").content("Test comment").build();
+        when(commentService.postComment(any(), any(), any(), any(), any())).thenReturn(saved);
 
         mockMvc.perform(post("/api/documents/" + DOC_ID + "/annotations/" + ANN_ID + "/comments")
                         .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
@@ -194,10 +244,65 @@ class CommentControllerTest {
         DocumentComment saved = DocumentComment.builder()
                 .id(UUID.randomUUID()).documentId(DOC_ID).annotationId(ANN_ID)
                 .parentId(COMMENT_ID).authorName("Anna").content("Test comment").build();
-        when(commentService.replyToComment(any(), any(), any(), any())).thenReturn(saved);
+        when(commentService.replyToComment(any(), any(), any(), any(), any())).thenReturn(saved);
 
         mockMvc.perform(post("/api/documents/" + DOC_ID + "/annotations/" + ANN_ID + "/comments/" + COMMENT_ID + "/replies")
                         .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
                 .andExpect(status().isCreated());
     }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void replyToAnnotationComment_returns201_whenHasWriteAllPermission() throws Exception {
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(DOC_ID).annotationId(ANN_ID)
+                .parentId(COMMENT_ID).authorName("Anna").content("Test comment").build();
+        when(commentService.replyToComment(any(), any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/annotations/" + ANN_ID + "/comments/" + COMMENT_ID + "/replies")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isCreated());
+    }
+
+    // ─── resolveUser — exception branch ──────────────────────────────────────
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void postDocumentComment_stillSucceeds_whenUserServiceThrows() throws Exception {
+        // findByUsername throws → catch block in resolveUser → author null, saves anyway
+        when(userService.findByUsername(any())).thenThrow(new RuntimeException("DB error"));
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(DOC_ID).content("Test comment").build();
+        when(commentService.postComment(any(), any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isCreated());
+    }
+
+    // ─── Block comment endpoints ─────────────────────────────────────────────
+
+    @Test
+    @WithMockUser
+    void getBlockComments_returns200() throws Exception {
+        UUID blockId = UUID.randomUUID();
+        when(commentService.getCommentsForBlock(blockId)).thenReturn(List.of());
+
+        mockMvc.perform(get("/api/documents/" + DOC_ID + "/transcription-blocks/" + blockId + "/comments"))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void postBlockComment_returns201() throws Exception {
+        UUID blockId = UUID.randomUUID();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(DOC_ID).blockId(blockId).content("Nice").build();
+        when(commentService.postBlockComment(any(), any(), any(), any(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/transcription-blocks/" + blockId + "/comments")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isCreated())
+                .andExpect(jsonPath("$.blockId").value(blockId.toString()));
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/controller/DocumentControllerTest.java

@@ -2,7 +2,9 @@ package org.raddatz.familienarchiv.controller;
 
 import org.junit.jupiter.api.Test;
 import org.raddatz.familienarchiv.dto.DocumentVersionSummary;
+import org.raddatz.familienarchiv.dto.IncompleteDocumentDTO;
 import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentStatus;
 import org.raddatz.familienarchiv.model.DocumentVersion;
 import org.raddatz.familienarchiv.security.PermissionAspect;
 import org.raddatz.familienarchiv.service.CustomUserDetailsService;
@@ -21,9 +23,13 @@ import org.springframework.test.web.servlet.MockMvc;
 import java.time.LocalDateTime;
 import java.util.Collections;
 import java.util.List;
+import java.util.Optional;
 import java.util.UUID;
 
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.multipart;
@@ -52,13 +58,58 @@ class DocumentControllerTest {
     @Test
     @WithMockUser
     void search_returns200_whenAuthenticated() throws Exception {
-        when(documentService.searchDocuments(any(), any(), any(), any(), any(), any()))
+        when(documentService.searchDocuments(any(), any(), any(), any(), any(), any(), any(), any(), any(), any()))
                 .thenReturn(Collections.emptyList());
 
         mockMvc.perform(get("/api/documents/search"))
                 .andExpect(status().isOk());
     }
 
+    @Test
+    @WithMockUser
+    void search_withStatusParam_passesItToService() throws Exception {
+        when(documentService.searchDocuments(any(), any(), any(), any(), any(), any(), any(), eq(DocumentStatus.REVIEWED), any(), any()))
+                .thenReturn(Collections.emptyList());
+
+        mockMvc.perform(get("/api/documents/search").param("status", "REVIEWED"))
+                .andExpect(status().isOk());
+
+        verify(documentService).searchDocuments(any(), any(), any(), any(), any(), any(), any(), eq(DocumentStatus.REVIEWED), any(), any());
+    }
+
+    @Test
+    @WithMockUser
+    void search_withInvalidStatus_returns400() throws Exception {
+        mockMvc.perform(get("/api/documents/search").param("status", "INVALID"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser
+    void search_withInvalidDir_returns400() throws Exception {
+        mockMvc.perform(get("/api/documents/search").param("dir", "INVALID"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser
+    void search_withInvalidSort_returns400() throws Exception {
+        mockMvc.perform(get("/api/documents/search").param("sort", "GARBAGE"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser
+    void search_responseContainsTotalCount() throws Exception {
+        when(documentService.searchDocuments(any(), any(), any(), any(), any(), any(), any(), any(), any(), any()))
+                .thenReturn(Collections.emptyList());
+
+        mockMvc.perform(get("/api/documents/search"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.total").value(0))
+                .andExpect(jsonPath("$.documents").isArray());
+    }
+
     // ─── POST /api/documents ─────────────────────────────────────────────────
 
     @Test
@@ -121,6 +172,298 @@ class DocumentControllerTest {
                 .andExpect(status().isOk());
     }
 
+    // ─── DELETE /api/documents/{id} ──────────────────────────────────────────
+
+    @Test
+    void deleteDocument_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(org.springframework.test.web.servlet.request.MockMvcRequestBuilders
+                        .delete("/api/documents/" + UUID.randomUUID()))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void deleteDocument_returns403_whenMissingWritePermission() throws Exception {
+        mockMvc.perform(org.springframework.test.web.servlet.request.MockMvcRequestBuilders
+                        .delete("/api/documents/" + UUID.randomUUID()))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void deleteDocument_returns204_whenHasWritePermission() throws Exception {
+        UUID id = UUID.randomUUID();
+        mockMvc.perform(org.springframework.test.web.servlet.request.MockMvcRequestBuilders
+                        .delete("/api/documents/" + id))
+                .andExpect(status().isNoContent());
+    }
+
+    // ─── POST /api/documents/quick-upload ────────────────────────────────────
+
+    @Test
+    void quickUpload_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(multipart("/api/documents/quick-upload"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void quickUpload_returns403_whenMissingWritePermission() throws Exception {
+        mockMvc.perform(multipart("/api/documents/quick-upload"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void quickUpload_returns200_withValidPdfFile() throws Exception {
+        Document doc = Document.builder()
+                .id(UUID.randomUUID()).title("scan001").originalFilename("scan001.pdf").build();
+        when(documentService.storeDocument(any()))
+                .thenReturn(new DocumentService.StoreResult(doc, true));
+
+        org.springframework.mock.web.MockMultipartFile file =
+                new org.springframework.mock.web.MockMultipartFile("files", "scan001.pdf", "application/pdf", new byte[]{1});
+
+        mockMvc.perform(multipart("/api/documents/quick-upload").file(file))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.created[0].title").value("scan001"))
+                .andExpect(jsonPath("$.updated").isEmpty())
+                .andExpect(jsonPath("$.errors").isEmpty());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void quickUpload_placesDocumentInUpdated_whenFilenameAlreadyExists() throws Exception {
+        Document existing = Document.builder()
+                .id(UUID.randomUUID()).title("Alter Brief").originalFilename("scan001.pdf").build();
+        when(documentService.storeDocument(any()))
+                .thenReturn(new DocumentService.StoreResult(existing, false));
+
+        org.springframework.mock.web.MockMultipartFile file =
+                new org.springframework.mock.web.MockMultipartFile("files", "scan001.pdf", "application/pdf", new byte[]{1});
+
+        mockMvc.perform(multipart("/api/documents/quick-upload").file(file))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.created").isEmpty())
+                .andExpect(jsonPath("$.updated[0].title").value("Alter Brief"))
+                .andExpect(jsonPath("$.errors").isEmpty());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void quickUpload_skipsUnsupportedFileType_andReturnsError() throws Exception {
+        org.springframework.mock.web.MockMultipartFile file =
+                new org.springframework.mock.web.MockMultipartFile("files", "report.docx",
+                        "application/vnd.openxmlformats-officedocument.wordprocessingml.document", new byte[]{1});
+
+        mockMvc.perform(multipart("/api/documents/quick-upload").file(file))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.created").isEmpty())
+                .andExpect(jsonPath("$.errors[0].filename").value("report.docx"))
+                .andExpect(jsonPath("$.errors[0].code").value("UNSUPPORTED_FILE_TYPE"));
+    }
+
+    // ─── GET /api/documents/{id}/file ────────────────────────────────────────
+
+    @Test
+    @WithMockUser
+    void getDocumentFile_returns404_whenDocHasNoFilePath() throws Exception {
+        UUID id = UUID.randomUUID();
+        Document doc = Document.builder().id(id).title("Brief").build(); // filePath == null
+        when(documentService.getDocumentById(id)).thenReturn(doc);
+
+        mockMvc.perform(get("/api/documents/" + id + "/file"))
+                .andExpect(status().isNotFound());
+    }
+
+    @Test
+    @WithMockUser
+    void getDocumentFile_returns200_withContentTypeFromDoc() throws Exception {
+        UUID id = UUID.randomUUID();
+        Document doc = Document.builder().id(id).title("Brief")
+                .filePath("docs/brief.pdf").contentType("application/pdf")
+                .originalFilename("brief.pdf").build();
+        when(documentService.getDocumentById(id)).thenReturn(doc);
+        java.io.InputStream stream = new java.io.ByteArrayInputStream(new byte[]{1, 2, 3});
+        when(fileService.downloadFile("docs/brief.pdf"))
+                .thenReturn(new FileService.S3FileDownload(
+                        new org.springframework.core.io.InputStreamResource(stream), "application/octet-stream"));
+
+        mockMvc.perform(get("/api/documents/" + id + "/file"))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser
+    void getDocumentFile_returns200_withContentTypeFromStorage_whenDocContentTypeIsBlank() throws Exception {
+        UUID id = UUID.randomUUID();
+        Document doc = Document.builder().id(id).title("Brief")
+                .filePath("docs/brief.pdf").contentType("  ") // blank → falls back to storage type
+                .originalFilename("brief.pdf").build();
+        when(documentService.getDocumentById(id)).thenReturn(doc);
+        java.io.InputStream stream = new java.io.ByteArrayInputStream(new byte[]{1, 2, 3});
+        when(fileService.downloadFile("docs/brief.pdf"))
+                .thenReturn(new FileService.S3FileDownload(
+                        new org.springframework.core.io.InputStreamResource(stream), "application/pdf"));
+
+        mockMvc.perform(get("/api/documents/" + id + "/file"))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser
+    void getDocumentFile_returns404_whenStorageFileNotFound() throws Exception {
+        UUID id = UUID.randomUUID();
+        Document doc = Document.builder().id(id).title("Brief")
+                .filePath("docs/missing.pdf").contentType("application/pdf")
+                .originalFilename("missing.pdf").build();
+        when(documentService.getDocumentById(id)).thenReturn(doc);
+        when(fileService.downloadFile("docs/missing.pdf"))
+                .thenThrow(new FileService.StorageFileNotFoundException("not found"));
+
+        mockMvc.perform(get("/api/documents/" + id + "/file"))
+                .andExpect(status().isNotFound());
+    }
+
+    // ─── POST /api/documents/quick-upload — null/empty files ─────────────────
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void quickUpload_returnsEmptyResult_whenNoFilesPartProvided() throws Exception {
+        mockMvc.perform(multipart("/api/documents/quick-upload"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.created").isEmpty())
+                .andExpect(jsonPath("$.updated").isEmpty())
+                .andExpect(jsonPath("$.errors").isEmpty());
+    }
+
+    // ─── GET /api/documents/incomplete-count ─────────────────────────────────
+
+    @Test
+    void getIncompleteCount_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/documents/incomplete-count"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getIncompleteCount_returns200_withCount() throws Exception {
+        when(documentService.getIncompleteCount()).thenReturn(3L);
+
+        mockMvc.perform(get("/api/documents/incomplete-count"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.count").value(3));
+    }
+
+    // ─── GET /api/documents/incomplete ───────────────────────────────────────
+
+    @Test
+    void getIncomplete_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/documents/incomplete"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getIncomplete_returns200_withDTOList() throws Exception {
+        UUID id = UUID.randomUUID();
+        IncompleteDocumentDTO dto = new IncompleteDocumentDTO(id, "Unvollständig");
+        when(documentService.findIncompleteDocuments(anyInt())).thenReturn(List.of(dto));
+
+        mockMvc.perform(get("/api/documents/incomplete"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].id").value(id.toString()))
+                .andExpect(jsonPath("$[0].title").value("Unvollständig"));
+    }
+
+    @Test
+    @WithMockUser
+    void getIncomplete_withSizeParam_passesItToService() throws Exception {
+        when(documentService.findIncompleteDocuments(5)).thenReturn(List.of());
+
+        mockMvc.perform(get("/api/documents/incomplete").param("size", "5"))
+                .andExpect(status().isOk());
+
+        verify(documentService).findIncompleteDocuments(5);
+    }
+
+    @Test
+    @WithMockUser
+    void getIncomplete_usesDefaultSizeWhenNotSpecified() throws Exception {
+        when(documentService.findIncompleteDocuments(anyInt())).thenReturn(List.of());
+
+        mockMvc.perform(get("/api/documents/incomplete"))
+                .andExpect(status().isOk());
+
+        verify(documentService).findIncompleteDocuments(10);
+    }
+
+    // ─── GET /api/documents/incomplete/next ──────────────────────────────────
+
+    @Test
+    void getNextIncomplete_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/documents/incomplete/next")
+                        .param("excludeId", UUID.randomUUID().toString()))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getNextIncomplete_returns200_whenNextExists() throws Exception {
+        UUID excludeId = UUID.randomUUID();
+        Document next = Document.builder()
+                .id(UUID.randomUUID()).title("Nächster").originalFilename("next.pdf").build();
+        when(documentService.findNextIncompleteDocument(excludeId)).thenReturn(Optional.of(next));
+
+        mockMvc.perform(get("/api/documents/incomplete/next")
+                        .param("excludeId", excludeId.toString()))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.title").value("Nächster"));
+    }
+
+    @Test
+    @WithMockUser
+    void getNextIncomplete_returns204_whenNoneRemain() throws Exception {
+        UUID excludeId = UUID.randomUUID();
+        when(documentService.findNextIncompleteDocument(excludeId)).thenReturn(Optional.empty());
+
+        mockMvc.perform(get("/api/documents/incomplete/next")
+                        .param("excludeId", excludeId.toString()))
+                .andExpect(status().isNoContent());
+    }
+
+    // ─── GET /api/documents/recent-activity ──────────────────────────────────
+
+    @Test
+    void getRecentActivity_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/documents/recent-activity"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getRecentActivity_returnsOkWithDocuments() throws Exception {
+        Document doc1 = Document.builder().id(UUID.randomUUID()).title("Alpha").originalFilename("a.pdf").build();
+        Document doc2 = Document.builder().id(UUID.randomUUID()).title("Beta").originalFilename("b.pdf").build();
+        when(documentService.getRecentActivity(5)).thenReturn(List.of(doc1, doc2));
+
+        mockMvc.perform(get("/api/documents/recent-activity").param("size", "5"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].title").value("Alpha"))
+                .andExpect(jsonPath("$[1].title").value("Beta"));
+    }
+
+    @Test
+    @WithMockUser
+    void getRecentActivity_appliesDefaultSizeOfFive_whenSizeParamOmitted() throws Exception {
+        when(documentService.getRecentActivity(5)).thenReturn(List.of());
+
+        mockMvc.perform(get("/api/documents/recent-activity"))
+                .andExpect(status().isOk());
+
+        verify(documentService).getRecentActivity(5);
+    }
+
     // ─── GET /api/documents/{id}/versions ────────────────────────────────────
 
     @Test

backend/src/test/java/org/raddatz/familienarchiv/controller/NotificationControllerTest.java

@@ -0,0 +1,343 @@
+package org.raddatz.familienarchiv.controller;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.config.SecurityConfig;
+import org.raddatz.familienarchiv.dto.NotificationDTO;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.NotificationType;
+import org.raddatz.familienarchiv.security.PermissionAspect;
+import org.raddatz.familienarchiv.service.CustomUserDetailsService;
+import org.raddatz.familienarchiv.service.NotificationService;
+import org.raddatz.familienarchiv.service.SseEmitterRegistry;
+import org.raddatz.familienarchiv.service.UserService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration;
+import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.data.domain.PageImpl;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.http.MediaType;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.UUID;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+import static org.springframework.http.MediaType.TEXT_EVENT_STREAM_VALUE;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+
+@WebMvcTest(NotificationController.class)
+@Import({SecurityConfig.class, PermissionAspect.class, AopAutoConfiguration.class})
+class NotificationControllerTest {
+
+    @Autowired MockMvc mockMvc;
+
+    @MockitoBean NotificationService notificationService;
+    @MockitoBean UserService userService;
+    @MockitoBean SseEmitterRegistry sseEmitterRegistry;
+    @MockitoBean CustomUserDetailsService customUserDetailsService;
+
+    private static final UUID USER_ID = UUID.randomUUID();
+
+    // ─── GET /api/notifications ───────────────────────────────────────────────
+
+    @Test
+    void getNotifications_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/notifications"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser")
+    void getNotifications_returns200_whenAuthenticatedWithNoPermissions() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(notificationService.getNotifications(eq(USER_ID), any(), any(), any()))
+                .thenReturn(new PageImpl<>(List.of()));
+
+        mockMvc.perform(get("/api/notifications"))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void getNotifications_returns200WithList_whenAuthenticated() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        NotificationDTO dto = new NotificationDTO(
+                UUID.randomUUID(), NotificationType.REPLY, UUID.randomUUID(),
+                UUID.randomUUID(), null, false, LocalDateTime.now(), "Anna Smith", "Testdokument");
+
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(notificationService.getNotifications(eq(USER_ID), any(), any(), any()))
+                .thenReturn(new PageImpl<>(List.of(dto), PageRequest.of(0, 10), 1));
+
+        mockMvc.perform(get("/api/notifications"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.content").isArray());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void getNotifications_returnsOnlyCurrentUsersNotifications() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(notificationService.getNotifications(eq(USER_ID), any(), any(), any()))
+                .thenReturn(new PageImpl<>(List.of()));
+
+        mockMvc.perform(get("/api/notifications"))
+                .andExpect(status().isOk());
+
+        verify(notificationService).getNotifications(eq(USER_ID), any(), any(), any());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void getNotifications_withTypeAndReadFalse_passesFiltersToService() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(notificationService.getNotifications(eq(USER_ID), eq(NotificationType.MENTION), eq(false), any()))
+                .thenReturn(new PageImpl<>(List.of()));
+
+        mockMvc.perform(get("/api/notifications")
+                        .param("type", "MENTION")
+                        .param("read", "false"))
+                .andExpect(status().isOk());
+
+        verify(notificationService).getNotifications(eq(USER_ID), eq(NotificationType.MENTION), eq(false), any());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void getNotifications_withInvalidType_returns400() throws Exception {
+        mockMvc.perform(get("/api/notifications").param("type", "INVALID_TYPE"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void getNotifications_returns400_whenSizeExceedsMaximum() throws Exception {
+        mockMvc.perform(get("/api/notifications").param("size", "200"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void getNotifications_returns400_whenSizeIsZero() throws Exception {
+        mockMvc.perform(get("/api/notifications").param("size", "0"))
+                .andExpect(status().isBadRequest());
+    }
+
+    // ─── POST /api/notifications/read-all ────────────────────────────────────
+
+    @Test
+    void markAllRead_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(post("/api/notifications/read-all"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void markAllRead_returns204_whenAuthenticated() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+
+        mockMvc.perform(post("/api/notifications/read-all"))
+                .andExpect(status().isNoContent());
+
+        verify(notificationService).markAllRead(USER_ID);
+    }
+
+    // ─── PATCH /api/notifications/{id}/read ──────────────────────────────────
+
+    @Test
+    void markOneRead_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(patch("/api/notifications/" + UUID.randomUUID() + "/read"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void markOneRead_returns403_whenNotificationBelongsToDifferentUser() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        UUID notifId = UUID.randomUUID();
+
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        org.mockito.Mockito.doThrow(
+                org.raddatz.familienarchiv.exception.DomainException.forbidden("not yours"))
+                .when(notificationService).markRead(notifId, USER_ID);
+
+        mockMvc.perform(patch("/api/notifications/" + notifId + "/read"))
+                .andExpect(status().isForbidden());
+    }
+
+    // ─── GET /api/users/me/notification-preferences ──────────────────────────
+
+    @Test
+    void getPreferences_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/users/me/notification-preferences"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser")
+    void getPreferences_returns403_whenUserHasNoPermission() throws Exception {
+        mockMvc.perform(get("/api/users/me/notification-preferences"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void getPreferences_returns200_whenUserHasReadAll() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(true).notifyOnMention(false).build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+
+        mockMvc.perform(get("/api/users/me/notification-preferences"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.notifyOnReply").value(true))
+                .andExpect(jsonPath("$.notifyOnMention").value(false));
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"WRITE_ALL"})
+    void getPreferences_returns200_whenUserHasWriteAll() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(false).notifyOnMention(true).build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+
+        mockMvc.perform(get("/api/users/me/notification-preferences"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.notifyOnMention").value(true));
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"ANNOTATE_ALL"})
+    void getPreferences_returns200_whenUserHasAnnotateAll() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(false).notifyOnMention(false).build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+
+        mockMvc.perform(get("/api/users/me/notification-preferences"))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"WRITE_ALL"})
+    void getNotifications_returns200_whenUserHasOnlyWriteAll() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(notificationService.getNotifications(eq(USER_ID), any(), any(), any()))
+                .thenReturn(new PageImpl<>(List.of()));
+
+        mockMvc.perform(get("/api/notifications"))
+                .andExpect(status().isOk());
+    }
+
+    // ─── PUT /api/users/me/notification-preferences ──────────────────────────
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void updatePreferences_persistsBothBooleans() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(false).notifyOnMention(false).build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+
+        AppUser updated = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(true).notifyOnMention(true).build();
+        when(notificationService.updatePreferences(USER_ID, true, true)).thenReturn(updated);
+
+        mockMvc.perform(put("/api/users/me/notification-preferences")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"notifyOnReply\":true,\"notifyOnMention\":true}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.notifyOnReply").value(true))
+                .andExpect(jsonPath("$.notifyOnMention").value(true));
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"WRITE_ALL"})
+    void updatePreferences_returns200_whenUserHasWriteAll() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(false).notifyOnMention(false).build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+
+        AppUser updated = AppUser.builder().id(USER_ID).username("testuser")
+                .notifyOnReply(true).notifyOnMention(false).build();
+        when(notificationService.updatePreferences(USER_ID, true, false)).thenReturn(updated);
+
+        mockMvc.perform(put("/api/users/me/notification-preferences")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"notifyOnReply\":true,\"notifyOnMention\":false}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.notifyOnReply").value(true));
+    }
+
+    // ─── GET /api/notifications/unread-count ─────────────────────────────────
+
+    @Test
+    void countUnread_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/notifications/unread-count"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void countUnread_returns200WithCount_whenAuthenticated() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(notificationService.countUnread(USER_ID)).thenReturn(3L);
+
+        mockMvc.perform(get("/api/notifications/unread-count"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.count").value(3));
+    }
+
+    // ─── PATCH /api/notifications/{id}/read — additional cases ───────────────
+
+    // ─── GET /api/notifications/stream ───────────────────────────────────────
+
+    @Test
+    void stream_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/notifications/stream")
+                        .accept(TEXT_EVENT_STREAM_VALUE))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void stream_returns200_whenAuthenticated() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        when(sseEmitterRegistry.register(USER_ID)).thenReturn(new org.springframework.web.servlet.mvc.method.annotation.SseEmitter());
+
+        mockMvc.perform(get("/api/notifications/stream")
+                        .accept(TEXT_EVENT_STREAM_VALUE))
+                .andExpect(status().isOk());
+    }
+
+    // ─── PATCH /api/notifications/{id}/read — additional cases ───────────────
+
+    @Test
+    @WithMockUser(username = "testuser", authorities = {"READ_ALL"})
+    void markOneRead_returns404_whenNotificationDoesNotExist() throws Exception {
+        AppUser user = AppUser.builder().id(USER_ID).username("testuser").build();
+        UUID notifId = UUID.randomUUID();
+
+        when(userService.findByUsername("testuser")).thenReturn(user);
+        doThrow(DomainException.notFound(ErrorCode.NOTIFICATION_NOT_FOUND, "Notification not found: " + notifId))
+                .when(notificationService).markRead(notifId, USER_ID);
+
+        mockMvc.perform(patch("/api/notifications/" + notifId + "/read"))
+                .andExpect(status().isNotFound());
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/controller/PersonControllerTest.java

@@ -2,6 +2,9 @@ package org.raddatz.familienarchiv.controller;
 
 import org.junit.jupiter.api.Test;
 import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.Person;
+import org.raddatz.familienarchiv.model.PersonNameAlias;
+import org.raddatz.familienarchiv.model.PersonNameAliasType;
 import org.raddatz.familienarchiv.security.PermissionAspect;
 import org.raddatz.familienarchiv.service.CustomUserDetailsService;
 import org.raddatz.familienarchiv.service.DocumentService;
@@ -11,15 +14,23 @@ import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
 import org.raddatz.familienarchiv.config.SecurityConfig;
 import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration;
 import org.springframework.context.annotation.Import;
+import org.springframework.http.MediaType;
 import org.springframework.security.test.context.support.WithMockUser;
 import org.springframework.test.context.bean.override.mockito.MockitoBean;
 import org.springframework.test.web.servlet.MockMvc;
 
 import java.util.Collections;
+import java.util.List;
 import java.util.UUID;
 
+import org.raddatz.familienarchiv.dto.PersonSummaryDTO;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
-import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
 @WebMvcTest(PersonController.class)
@@ -32,6 +43,114 @@ class PersonControllerTest {
     @MockitoBean DocumentService documentService;
     @MockitoBean CustomUserDetailsService customUserDetailsService;
 
+    // ─── GET /api/persons ─────────────────────────────────────────────────────
+
+    @Test
+    void getPersons_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/persons"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getPersons_returns200_withEmptyList() throws Exception {
+        when(personService.findAll(null)).thenReturn(Collections.emptyList());
+        mockMvc.perform(get("/api/persons"))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser
+    void getPersons_delegatesQueryParam_toService() throws Exception {
+        PersonSummaryDTO dto = mockPersonSummary("Hans", "Müller");
+        when(personService.findAll("Hans")).thenReturn(List.of(dto));
+
+        mockMvc.perform(get("/api/persons").param("q", "Hans"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].firstName").value("Hans"));
+    }
+
+    private PersonSummaryDTO mockPersonSummary(String firstName, String lastName) {
+        return new PersonSummaryDTO() {
+            public java.util.UUID getId() { return UUID.randomUUID(); }
+            public String getFirstName() { return firstName; }
+            public String getLastName() { return lastName; }
+            public String getAlias() { return null; }
+            public Integer getBirthYear() { return null; }
+            public Integer getDeathYear() { return null; }
+            public String getNotes() { return null; }
+            public long getDocumentCount() { return 0; }
+        };
+    }
+
+    // ─── GET /api/persons/{id} ────────────────────────────────────────────────
+
+    @Test
+    void getPerson_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/persons/{id}", UUID.randomUUID()))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getPerson_returns200_whenFound() throws Exception {
+        UUID id = UUID.randomUUID();
+        Person person = Person.builder().id(id).firstName("Anna").lastName("Schmidt").build();
+        when(personService.getById(id)).thenReturn(person);
+
+        mockMvc.perform(get("/api/persons/{id}", id))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.firstName").value("Anna"));
+    }
+
+    // ─── GET /api/persons/{id}/correspondents ─────────────────────────────────
+
+    @Test
+    void getCorrespondents_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/persons/{id}/correspondents", UUID.randomUUID()))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getCorrespondents_returns200_withoutFilter() throws Exception {
+        UUID personId = UUID.randomUUID();
+        when(personService.findCorrespondents(personId, null)).thenReturn(Collections.emptyList());
+
+        mockMvc.perform(get("/api/persons/{id}/correspondents", personId))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser
+    void getCorrespondents_returns200_withFilter() throws Exception {
+        UUID personId = UUID.randomUUID();
+        Person correspondent = Person.builder().id(UUID.randomUUID()).firstName("Walter").lastName("Gruyter").build();
+        when(personService.findCorrespondents(personId, "Walter")).thenReturn(List.of(correspondent));
+
+        mockMvc.perform(get("/api/persons/{id}/correspondents", personId).param("q", "Walter"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].firstName").value("Walter"));
+    }
+
+    // ─── GET /api/persons/{id}/documents ──────────────────────────────────────
+
+    @Test
+    void getPersonDocuments_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/persons/{id}/documents", UUID.randomUUID()))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getPersonDocuments_returns200_whenAuthenticated() throws Exception {
+        UUID personId = UUID.randomUUID();
+        when(documentService.getDocumentsBySender(personId)).thenReturn(Collections.emptyList());
+
+        mockMvc.perform(get("/api/persons/{id}/documents", personId))
+                .andExpect(status().isOk());
+    }
+
     // ─── GET /api/persons/{id}/received-documents ─────────────────────────────
 
     @Test
@@ -49,4 +168,312 @@ class PersonControllerTest {
         mockMvc.perform(get("/api/persons/{id}/received-documents", personId))
                 .andExpect(status().isOk());
     }
+
+    // ─── POST /api/persons ────────────────────────────────────────────────────
+
+    @Test
+    void createPerson_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void createPerson_returns400_whenFirstNameIsMissing() throws Exception {
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"lastName\":\"Müller\"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void createPerson_returns400_whenFirstNameIsBlank() throws Exception {
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"  \",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void createPerson_returns400_whenLastNameIsMissing() throws Exception {
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void createPerson_returns400_whenLastNameIsBlank() throws Exception {
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"  \"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void createPerson_returns200_whenValid() throws Exception {
+        Person saved = Person.builder().id(UUID.randomUUID()).firstName("Hans").lastName("Müller").build();
+        when(personService.createPerson(any(org.raddatz.familienarchiv.dto.PersonUpdateDTO.class))).thenReturn(saved);
+
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.firstName").value("Hans"));
+    }
+
+    // ─── PUT /api/persons/{id} ────────────────────────────────────────────────
+
+    @Test
+    void updatePerson_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(put("/api/persons/{id}", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void updatePerson_returns400_whenFirstNameIsBlank() throws Exception {
+        mockMvc.perform(put("/api/persons/{id}", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"\",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void updatePerson_returns400_whenLastNameIsNull() throws Exception {
+        mockMvc.perform(put("/api/persons/{id}", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void updatePerson_returns200_whenValid() throws Exception {
+        UUID id = UUID.randomUUID();
+        Person updated = Person.builder().id(id).firstName("Hans").lastName("Müller").build();
+        when(personService.updatePerson(eq(id), any())).thenReturn(updated);
+
+        mockMvc.perform(put("/api/persons/{id}", id)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.lastName").value("Müller"));
+    }
+
+    // ─── POST /api/persons/{id}/merge ─────────────────────────────────────────
+
+    @Test
+    void mergePerson_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(post("/api/persons/{id}/merge", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"targetPersonId\":\"" + UUID.randomUUID() + "\"}"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void mergePerson_returns400_whenTargetPersonIdIsMissing() throws Exception {
+        mockMvc.perform(post("/api/persons/{id}/merge", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void mergePerson_returns400_whenTargetPersonIdIsBlank() throws Exception {
+        mockMvc.perform(post("/api/persons/{id}/merge", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"targetPersonId\":\"  \"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void mergePerson_returns204_whenValid() throws Exception {
+        UUID sourceId = UUID.randomUUID();
+        UUID targetId = UUID.randomUUID();
+
+        mockMvc.perform(post("/api/persons/{id}/merge", sourceId)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"targetPersonId\":\"" + targetId + "\"}"))
+                .andExpect(status().isNoContent());
+    }
+
+    // ─── PUT /api/persons/{id} — lastName blank branch ────────────────────────
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void updatePerson_returns400_whenLastNameIsBlank() throws Exception {
+        // firstName valid, lastName blank → second || operand = true → 400
+        UUID id = UUID.randomUUID();
+        mockMvc.perform(put("/api/persons/{id}", id)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"   \"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    // ─── Phase 2.2: POST /api/persons with full PersonUpdateDTO ───────────────
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void createPerson_returns200_withAllSixFields() throws Exception {
+        UUID id = UUID.randomUUID();
+        Person saved = Person.builder().id(id).firstName("Maria").lastName("Raddatz")
+                .alias("Oma Maria").birthYear(1901).deathYear(1975).notes("Some notes").build();
+        when(personService.createPerson(any(org.raddatz.familienarchiv.dto.PersonUpdateDTO.class))).thenReturn(saved);
+
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Maria\",\"lastName\":\"Raddatz\"," +
+                                "\"alias\":\"Oma Maria\",\"birthYear\":1901,\"deathYear\":1975," +
+                                "\"notes\":\"Some notes\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.firstName").value("Maria"))
+                .andExpect(jsonPath("$.alias").value("Oma Maria"))
+                .andExpect(jsonPath("$.birthYear").value(1901));
+    }
+
+    // ─── Phase 1.2: @Size constraints ─────────────────────────────────────────
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void updatePerson_returns400_whenNotesExceed5000Chars() throws Exception {
+        String oversizedNotes = "x".repeat(5001);
+        UUID id = UUID.randomUUID();
+        mockMvc.perform(put("/api/persons/{id}", id)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"Müller\",\"notes\":\"" + oversizedNotes + "\"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void updatePerson_returns400_whenFirstNameExceeds100Chars() throws Exception {
+        String oversizedFirstName = "x".repeat(101);
+        UUID id = UUID.randomUUID();
+        mockMvc.perform(put("/api/persons/{id}", id)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"" + oversizedFirstName + "\",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    // ─── Phase 1.1: @RequirePermission(WRITE_ALL) on write endpoints ──────────
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void createPerson_returns403_whenUserHasOnlyReadPermission() throws Exception {
+        mockMvc.perform(post("/api/persons")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void updatePerson_returns403_whenUserHasOnlyReadPermission() throws Exception {
+        mockMvc.perform(put("/api/persons/{id}", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"firstName\":\"Hans\",\"lastName\":\"Müller\"}"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void mergePerson_returns403_whenUserHasOnlyReadPermission() throws Exception {
+        mockMvc.perform(post("/api/persons/{id}/merge", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"targetPersonId\":\"" + UUID.randomUUID() + "\"}"))
+                .andExpect(status().isForbidden());
+    }
+
+    // ─── GET /api/persons/{id}/aliases ────────────────────────────────────────
+
+    @Test
+    @WithMockUser
+    void getAliases_returns200_withList() throws Exception {
+        UUID personId = UUID.randomUUID();
+        PersonNameAlias alias = PersonNameAlias.builder()
+                .id(UUID.randomUUID()).lastName("de Gruyter").type(PersonNameAliasType.BIRTH).sortOrder(0).build();
+        when(personService.getAliases(personId)).thenReturn(List.of(alias));
+
+        mockMvc.perform(get("/api/persons/{id}/aliases", personId))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].lastName").value("de Gruyter"));
+    }
+
+    // ─── POST /api/persons/{id}/aliases ──────────────────────────────────────
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void addAlias_returns200_whenValid() throws Exception {
+        UUID personId = UUID.randomUUID();
+        PersonNameAlias saved = PersonNameAlias.builder()
+                .id(UUID.randomUUID()).lastName("de Gruyter").type(PersonNameAliasType.BIRTH).sortOrder(0).build();
+        when(personService.addAlias(eq(personId), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/persons/{id}/aliases", personId)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"lastName\":\"de Gruyter\",\"type\":\"BIRTH\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.lastName").value("de Gruyter"));
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void addAlias_returns403_withoutWritePermission() throws Exception {
+        mockMvc.perform(post("/api/persons/{id}/aliases", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"lastName\":\"de Gruyter\",\"type\":\"BIRTH\"}"))
+                .andExpect(status().isForbidden());
+    }
+
+    // ─── DELETE /api/persons/{id}/aliases/{aliasId} ──────────────────────────
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void removeAlias_returns204_whenValid() throws Exception {
+        UUID personId = UUID.randomUUID();
+        UUID aliasId = UUID.randomUUID();
+
+        mockMvc.perform(delete("/api/persons/{id}/aliases/{aliasId}", personId, aliasId))
+                .andExpect(status().isNoContent());
+
+        verify(personService).removeAlias(personId, aliasId);
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void removeAlias_returns403_withoutWritePermission() throws Exception {
+        mockMvc.perform(delete("/api/persons/{id}/aliases/{aliasId}", UUID.randomUUID(), UUID.randomUUID()))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void addAlias_returns400_whenLastNameIsBlank() throws Exception {
+        mockMvc.perform(post("/api/persons/{id}/aliases", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"lastName\":\"\",\"type\":\"BIRTH\"}"))
+                .andExpect(status().isBadRequest());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void addAlias_returns400_whenTypeIsNull() throws Exception {
+        mockMvc.perform(post("/api/persons/{id}/aliases", UUID.randomUUID())
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"lastName\":\"de Gruyter\"}"))
+                .andExpect(status().isBadRequest());
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/controller/StatsControllerTest.java

@@ -0,0 +1,61 @@
+package org.raddatz.familienarchiv.controller;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.config.SecurityConfig;
+import org.raddatz.familienarchiv.repository.DocumentRepository;
+import org.raddatz.familienarchiv.repository.PersonRepository;
+import org.raddatz.familienarchiv.security.PermissionAspect;
+import org.raddatz.familienarchiv.service.CustomUserDetailsService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration;
+import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.MockMvc;
+
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@WebMvcTest(StatsController.class)
+@Import({SecurityConfig.class, PermissionAspect.class, AopAutoConfiguration.class})
+class StatsControllerTest {
+
+    @Autowired MockMvc mockMvc;
+
+    @MockitoBean PersonRepository personRepository;
+    @MockitoBean DocumentRepository documentRepository;
+    @MockitoBean CustomUserDetailsService customUserDetailsService;
+
+    @Test
+    void getStats_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/stats"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getStats_returns200_withCorrectCounts() throws Exception {
+        when(personRepository.count()).thenReturn(4L);
+        when(documentRepository.count()).thenReturn(12L);
+
+        mockMvc.perform(get("/api/stats"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.totalPersons").value(4))
+                .andExpect(jsonPath("$.totalDocuments").value(12));
+    }
+
+    @Test
+    @WithMockUser
+    void getStats_returns200_withZeroCounts() throws Exception {
+        when(personRepository.count()).thenReturn(0L);
+        when(documentRepository.count()).thenReturn(0L);
+
+        mockMvc.perform(get("/api/stats"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.totalPersons").value(0))
+                .andExpect(jsonPath("$.totalDocuments").value(0));
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/controller/TranscriptionBlockControllerTest.java

@@ -0,0 +1,359 @@
+package org.raddatz.familienarchiv.controller;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.config.SecurityConfig;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.TranscriptionBlock;
+import org.raddatz.familienarchiv.model.TranscriptionBlockVersion;
+import org.raddatz.familienarchiv.security.PermissionAspect;
+import org.raddatz.familienarchiv.service.CustomUserDetailsService;
+import org.raddatz.familienarchiv.service.TranscriptionService;
+import org.raddatz.familienarchiv.service.UserService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration;
+import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.http.MediaType;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.List;
+import java.util.UUID;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+
+@WebMvcTest(TranscriptionBlockController.class)
+@Import({SecurityConfig.class, PermissionAspect.class, AopAutoConfiguration.class})
+class TranscriptionBlockControllerTest {
+
+    @Autowired MockMvc mockMvc;
+
+    @MockitoBean TranscriptionService transcriptionService;
+    @MockitoBean UserService userService;
+    @MockitoBean CustomUserDetailsService customUserDetailsService;
+
+    private static final UUID DOC_ID  = UUID.randomUUID();
+    private static final UUID BLOCK_ID = UUID.randomUUID();
+    private static final String URL_BASE    = "/api/documents/" + DOC_ID + "/transcription-blocks";
+    private static final String URL_BLOCK   = URL_BASE + "/" + BLOCK_ID;
+    private static final String URL_REORDER = URL_BASE + "/reorder";
+    private static final String URL_HISTORY = URL_BLOCK + "/history";
+
+    private static final String CREATE_JSON =
+            "{\"pageNumber\":1,\"x\":0.1,\"y\":0.2,\"width\":0.3,\"height\":0.4,\"text\":\"Liebe Mutter,\"}";
+    private static final String UPDATE_JSON =
+            "{\"text\":\"Neue Fassung\",\"label\":\"Anrede\"}";
+    private static final String REORDER_JSON =
+            "{\"blockIds\":[\"" + UUID.randomUUID() + "\",\"" + UUID.randomUUID() + "\"]}";
+
+    private AppUser mockUser() {
+        return AppUser.builder().id(UUID.randomUUID()).username("user").build();
+    }
+
+    private TranscriptionBlock sampleBlock() {
+        return TranscriptionBlock.builder()
+                .id(BLOCK_ID).documentId(DOC_ID)
+                .annotationId(UUID.randomUUID())
+                .text("Liebe Mutter,").sortOrder(0).build();
+    }
+
+    // ─── GET /api/documents/{id}/transcription-blocks ────────────────────────
+
+    @Test
+    void listBlocks_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get(URL_BASE))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void listBlocks_returns403_whenMissingReadAllPermission() throws Exception {
+        mockMvc.perform(get(URL_BASE))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void listBlocks_returns200_withBlocks_whenAuthorised() throws Exception {
+        TranscriptionBlock b = sampleBlock();
+        when(transcriptionService.listBlocks(DOC_ID)).thenReturn(List.of(b));
+
+        mockMvc.perform(get(URL_BASE))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].text").value("Liebe Mutter,"));
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void listBlocks_returns200_withEmptyArray_whenNoBlocksExist() throws Exception {
+        when(transcriptionService.listBlocks(any())).thenReturn(List.of());
+
+        mockMvc.perform(get(URL_BASE))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$").isArray())
+                .andExpect(jsonPath("$").isEmpty());
+    }
+
+    // ─── GET /api/documents/{id}/transcription-blocks/{blockId} ─────────────
+
+    @Test
+    void getBlock_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get(URL_BLOCK))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getBlock_returns403_whenMissingReadAllPermission() throws Exception {
+        mockMvc.perform(get(URL_BLOCK))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void getBlock_returns200_withBlockData_whenFound() throws Exception {
+        when(transcriptionService.getBlock(DOC_ID, BLOCK_ID)).thenReturn(sampleBlock());
+
+        mockMvc.perform(get(URL_BLOCK))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.id").value(BLOCK_ID.toString()))
+                .andExpect(jsonPath("$.text").value("Liebe Mutter,"))
+                .andExpect(jsonPath("$.sortOrder").value(0));
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void getBlock_returns404_whenBlockDoesNotExist() throws Exception {
+        when(transcriptionService.getBlock(any(), any()))
+                .thenThrow(DomainException.notFound(ErrorCode.TRANSCRIPTION_BLOCK_NOT_FOUND, "not found"));
+
+        mockMvc.perform(get(URL_BLOCK))
+                .andExpect(status().isNotFound())
+                .andExpect(jsonPath("$.code").value("TRANSCRIPTION_BLOCK_NOT_FOUND"));
+    }
+
+    // ─── POST /api/documents/{id}/transcription-blocks ───────────────────────
+
+    @Test
+    void createBlock_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(post(URL_BASE)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(CREATE_JSON))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void createBlock_returns403_whenMissingWriteAllPermission() throws Exception {
+        mockMvc.perform(post(URL_BASE)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(CREATE_JSON))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void createBlock_returns201_withSavedBlock_whenAuthorised() throws Exception {
+        when(userService.findByUsername(any())).thenReturn(mockUser());
+        when(transcriptionService.createBlock(eq(DOC_ID), any(), any())).thenReturn(sampleBlock());
+
+        mockMvc.perform(post(URL_BASE)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(CREATE_JSON))
+                .andExpect(status().isCreated())
+                .andExpect(jsonPath("$.text").value("Liebe Mutter,"))
+                .andExpect(jsonPath("$.documentId").value(DOC_ID.toString()));
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void createBlock_returns401_whenUserNotFoundInDatabase() throws Exception {
+        when(userService.findByUsername(any())).thenReturn(null);
+
+        mockMvc.perform(post(URL_BASE)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(CREATE_JSON))
+                .andExpect(status().isUnauthorized());
+    }
+
+    // ─── PUT /api/documents/{id}/transcription-blocks/{blockId} ─────────────
+
+    @Test
+    void updateBlock_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(put(URL_BLOCK)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(UPDATE_JSON))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void updateBlock_returns403_whenMissingWriteAllPermission() throws Exception {
+        mockMvc.perform(put(URL_BLOCK)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(UPDATE_JSON))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void updateBlock_returns200_withUpdatedBlock_whenAuthorised() throws Exception {
+        TranscriptionBlock updated = sampleBlock();
+        updated.setText("Neue Fassung");
+        updated.setLabel("Anrede");
+
+        when(userService.findByUsername(any())).thenReturn(mockUser());
+        when(transcriptionService.updateBlock(eq(DOC_ID), eq(BLOCK_ID), any(), any()))
+                .thenReturn(updated);
+
+        mockMvc.perform(put(URL_BLOCK)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(UPDATE_JSON))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.text").value("Neue Fassung"))
+                .andExpect(jsonPath("$.label").value("Anrede"));
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void updateBlock_returns404_whenBlockDoesNotExist() throws Exception {
+        when(userService.findByUsername(any())).thenReturn(mockUser());
+        when(transcriptionService.updateBlock(any(), any(), any(), any()))
+                .thenThrow(DomainException.notFound(ErrorCode.TRANSCRIPTION_BLOCK_NOT_FOUND, "not found"));
+
+        mockMvc.perform(put(URL_BLOCK)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(UPDATE_JSON))
+                .andExpect(status().isNotFound());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void updateBlock_returns401_whenUserNotFoundInDatabase() throws Exception {
+        when(userService.findByUsername(any())).thenReturn(null);
+
+        mockMvc.perform(put(URL_BLOCK)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(UPDATE_JSON))
+                .andExpect(status().isUnauthorized());
+    }
+
+    // ─── DELETE /api/documents/{id}/transcription-blocks/{blockId} ───────────
+
+    @Test
+    void deleteBlock_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(delete(URL_BLOCK))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void deleteBlock_returns403_whenMissingWriteAllPermission() throws Exception {
+        mockMvc.perform(delete(URL_BLOCK))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void deleteBlock_returns204_whenAuthorised() throws Exception {
+        mockMvc.perform(delete(URL_BLOCK))
+                .andExpect(status().isNoContent());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void deleteBlock_returns404_whenBlockDoesNotExist() throws Exception {
+        org.mockito.Mockito.doThrow(
+                DomainException.notFound(ErrorCode.TRANSCRIPTION_BLOCK_NOT_FOUND, "not found"))
+                .when(transcriptionService).deleteBlock(any(), any());
+
+        mockMvc.perform(delete(URL_BLOCK))
+                .andExpect(status().isNotFound());
+    }
+
+    // ─── PUT /api/documents/{id}/transcription-blocks/reorder ────────────────
+
+    @Test
+    void reorderBlocks_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(put(URL_REORDER)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(REORDER_JSON))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void reorderBlocks_returns403_whenMissingWriteAllPermission() throws Exception {
+        mockMvc.perform(put(URL_REORDER)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(REORDER_JSON))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "WRITE_ALL")
+    void reorderBlocks_returns200_withReorderedBlocks_whenAuthorised() throws Exception {
+        when(transcriptionService.listBlocks(DOC_ID)).thenReturn(List.of(sampleBlock()));
+
+        mockMvc.perform(put(URL_REORDER)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(REORDER_JSON))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$").isArray());
+    }
+
+    // ─── GET /api/documents/{id}/transcription-blocks/{blockId}/history ──────
+
+    @Test
+    void getBlockHistory_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get(URL_HISTORY))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getBlockHistory_returns403_whenMissingReadAllPermission() throws Exception {
+        mockMvc.perform(get(URL_HISTORY))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void getBlockHistory_returns200_withVersionList_whenAuthorised() throws Exception {
+        TranscriptionBlockVersion v = TranscriptionBlockVersion.builder()
+                .id(UUID.randomUUID()).blockId(BLOCK_ID).text("v1").build();
+        when(transcriptionService.getBlockHistory(DOC_ID, BLOCK_ID)).thenReturn(List.of(v));
+
+        mockMvc.perform(get(URL_HISTORY))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].text").value("v1"))
+                .andExpect(jsonPath("$[0].blockId").value(BLOCK_ID.toString()));
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void getBlockHistory_returns404_whenBlockDoesNotExist() throws Exception {
+        when(transcriptionService.getBlockHistory(any(), any()))
+                .thenThrow(DomainException.notFound(ErrorCode.TRANSCRIPTION_BLOCK_NOT_FOUND, "not found"));
+
+        mockMvc.perform(get(URL_HISTORY))
+                .andExpect(status().isNotFound());
+    }
+
+    @Test
+    @WithMockUser(authorities = "READ_ALL")
+    void getBlockHistory_returns200_withEmptyList_whenNoVersionsExist() throws Exception {
+        when(transcriptionService.getBlockHistory(any(), any())).thenReturn(List.of());
+
+        mockMvc.perform(get(URL_HISTORY))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$").isEmpty());
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/controller/UserControllerTest.java

@@ -0,0 +1,78 @@
+package org.raddatz.familienarchiv.controller;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.config.SecurityConfig;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.security.PermissionAspect;
+import org.raddatz.familienarchiv.service.CustomUserDetailsService;
+import org.raddatz.familienarchiv.service.UserService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration;
+import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.UUID;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@WebMvcTest(UserController.class)
+@Import({SecurityConfig.class, PermissionAspect.class, AopAutoConfiguration.class})
+class UserControllerTest {
+
+    @Autowired MockMvc mockMvc;
+
+    @MockitoBean UserService userService;
+    @MockitoBean CustomUserDetailsService customUserDetailsService;
+
+    // ─── GET /api/users/me ────────────────────────────────────────────────────
+
+    @Test
+    void getCurrentUser_returns401_whenUnauthenticated() throws Exception {
+        // authentication == null → returns 401 (covers null/!isAuthenticated branch)
+        mockMvc.perform(get("/api/users/me"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(username = "anna")
+    void getCurrentUser_returns200_whenAuthenticated() throws Exception {
+        AppUser user = AppUser.builder().id(UUID.randomUUID()).username("anna").build();
+        when(userService.findByUsername("anna")).thenReturn(user);
+
+        mockMvc.perform(get("/api/users/me"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.username").value("anna"));
+    }
+
+    // ─── GET /api/users/{id} ──────────────────────────────────────────────────
+
+    @Test
+    @WithMockUser(username = "reader")
+    void getUser_returns403_whenCallerLacksAdminUserPermission() throws Exception {
+        UUID id = UUID.randomUUID();
+        AppUser target = AppUser.builder().id(id).username("target").build();
+        when(userService.getById(id)).thenReturn(target);
+
+        mockMvc.perform(get("/api/users/" + id))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(username = "admin", authorities = {"ADMIN_USER"})
+    void getUser_returns200_whenCallerHasAdminUserPermission() throws Exception {
+        UUID id = UUID.randomUUID();
+        AppUser user = AppUser.builder().id(id).username("target").build();
+        when(userService.getById(id)).thenReturn(user);
+
+        mockMvc.perform(get("/api/users/" + id))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.username").value("target"));
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/controller/UserSearchControllerTest.java

@@ -0,0 +1,94 @@
+package org.raddatz.familienarchiv.controller;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.config.SecurityConfig;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.security.PermissionAspect;
+import org.raddatz.familienarchiv.service.CustomUserDetailsService;
+import org.raddatz.familienarchiv.service.UserSearchService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.aop.AopAutoConfiguration;
+import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.List;
+import java.util.UUID;
+import java.util.stream.IntStream;
+
+import static org.hamcrest.Matchers.lessThanOrEqualTo;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@WebMvcTest(UserSearchController.class)
+@Import({SecurityConfig.class, PermissionAspect.class, AopAutoConfiguration.class})
+class UserSearchControllerTest {
+
+    @Autowired MockMvc mockMvc;
+
+    @MockitoBean UserSearchService userSearchService;
+    @MockitoBean CustomUserDetailsService customUserDetailsService;
+
+    @Test
+    void search_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/users/search").param("q", "Hans"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void search_returns403_whenUserLacksPermission() throws Exception {
+        mockMvc.perform(get("/api/users/search").param("q", "Hans"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = {"ANNOTATE_ALL"})
+    void search_returns200_whenUserHasAnnotateAll() throws Exception {
+        when(userSearchService.search("Hans")).thenReturn(List.of());
+
+        mockMvc.perform(get("/api/users/search").param("q", "Hans"))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    @WithMockUser(authorities = {"READ_ALL"})
+    void search_returns200_whenAuthenticated() throws Exception {
+        AppUser user = AppUser.builder().id(UUID.randomUUID())
+                .firstName("Hans").lastName("Mueller").username("hans").build();
+        when(userSearchService.search("Hans")).thenReturn(List.of(user));
+
+        mockMvc.perform(get("/api/users/search").param("q", "Hans"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].firstName").value("Hans"));
+    }
+
+    @Test
+    @WithMockUser(authorities = {"READ_ALL"})
+    void search_returnsEmptyList_whenQueryIsEmpty() throws Exception {
+        when(userSearchService.search("")).thenReturn(List.of());
+
+        mockMvc.perform(get("/api/users/search").param("q", ""))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$").isEmpty());
+    }
+
+    @Test
+    @WithMockUser(authorities = {"READ_ALL"})
+    void search_returnsAtMostTenResults() throws Exception {
+        List<AppUser> elevenUsers = IntStream.range(0, 11)
+                .mapToObj(i -> AppUser.builder().id(UUID.randomUUID())
+                        .firstName("User").lastName(String.valueOf(i)).username("u" + i).build())
+                .toList();
+        when(userSearchService.search(anyString())).thenReturn(elevenUsers.subList(0, 10));
+
+        mockMvc.perform(get("/api/users/search").param("q", "a"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.length()").value(lessThanOrEqualTo(10)));
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/repository/DocumentRepositoryTest.java

@@ -0,0 +1,256 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.config.FlywayConfig;
+import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentStatus;
+import org.raddatz.familienarchiv.model.Person;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
+import org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest;
+import org.springframework.context.annotation.Import;
+
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.data.domain.Sort;
+
+import java.time.LocalDate;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import({PostgresContainerConfig.class, FlywayConfig.class})
+class DocumentRepositoryTest {
+
+    @Autowired
+    private DocumentRepository documentRepository;
+
+    @Autowired
+    private PersonRepository personRepository;
+
+    // ─── save and findById ────────────────────────────────────────────────────
+
+    @Test
+    void save_persistsDocument_andFindByIdReturnsSameDocument() {
+        Document document = Document.builder()
+                .title("Testbrief")
+                .originalFilename("testbrief.pdf")
+                .status(DocumentStatus.PLACEHOLDER)
+                .build();
+
+        Document saved = documentRepository.save(document);
+        Optional<Document> found = documentRepository.findById(saved.getId());
+
+        assertThat(found).isPresent();
+        assertThat(found.get().getTitle()).isEqualTo("Testbrief");
+        assertThat(found.get().getStatus()).isEqualTo(DocumentStatus.PLACEHOLDER);
+    }
+
+    // ─── findByStatus ─────────────────────────────────────────────────────────
+
+    @Test
+    void findByStatus_returnsOnlyDocumentsWithMatchingStatus() {
+        documentRepository.save(Document.builder()
+                .title("Placeholder Doc")
+                .originalFilename("placeholder.pdf")
+                .status(DocumentStatus.PLACEHOLDER)
+                .build());
+        documentRepository.save(Document.builder()
+                .title("Uploaded Doc")
+                .originalFilename("uploaded.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .build());
+
+        List<Document> placeholders = documentRepository.findByStatus(DocumentStatus.PLACEHOLDER);
+
+        assertThat(placeholders).extracting(Document::getStatus)
+                .containsOnly(DocumentStatus.PLACEHOLDER);
+    }
+
+    // ─── findByOriginalFilename ───────────────────────────────────────────────
+
+    @Test
+    void findByOriginalFilename_returnsDocument_whenFilenameMatches() {
+        documentRepository.save(Document.builder()
+                .title("Omas Brief")
+                .originalFilename("omas_brief.pdf")
+                .status(DocumentStatus.PLACEHOLDER)
+                .build());
+
+        Optional<Document> found = documentRepository.findByOriginalFilename("omas_brief.pdf");
+
+        assertThat(found).isPresent();
+        assertThat(found.get().getTitle()).isEqualTo("Omas Brief");
+    }
+
+    @Test
+    void findByOriginalFilename_returnsEmpty_whenFilenameDoesNotExist() {
+        Optional<Document> found = documentRepository.findByOriginalFilename("does_not_exist.pdf");
+
+        assertThat(found).isEmpty();
+    }
+
+    // ─── existsByOriginalFilename ─────────────────────────────────────────────
+
+    @Test
+    void existsByOriginalFilename_returnsTrue_whenDocumentExists() {
+        documentRepository.save(Document.builder()
+                .title("Brief")
+                .originalFilename("brief.pdf")
+                .status(DocumentStatus.PLACEHOLDER)
+                .build());
+
+        assertThat(documentRepository.existsByOriginalFilename("brief.pdf")).isTrue();
+    }
+
+    @Test
+    void existsByOriginalFilename_returnsFalse_whenDocumentDoesNotExist() {
+        assertThat(documentRepository.existsByOriginalFilename("nonexistent.pdf")).isFalse();
+    }
+
+    // ─── findBySenderId ───────────────────────────────────────────────────────
+
+    @Test
+    void findBySenderId_returnsDocuments_whereSenderIdMatches() {
+        Person sender = personRepository.save(Person.builder()
+                .firstName("Hans")
+                .lastName("Müller")
+                .build());
+        documentRepository.save(Document.builder()
+                .title("Brief von Hans")
+                .originalFilename("brief_hans.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(sender)
+                .build());
+
+        List<Document> docs = documentRepository.findBySenderId(sender.getId());
+
+        assertThat(docs).hasSize(1);
+        assertThat(docs.get(0).getSender().getId()).isEqualTo(sender.getId());
+    }
+
+    // ─── countByMetadataCompleteFalse ─────────────────────────────────────────
+
+    @Test
+    void countByMetadataCompleteFalse_returnsNumberOfIncompleteDocuments() {
+        documentRepository.save(Document.builder()
+                .title("Incomplete")
+                .originalFilename("incomplete.pdf")
+                .status(DocumentStatus.PLACEHOLDER)
+                .metadataComplete(false)
+                .build());
+        documentRepository.save(Document.builder()
+                .title("Complete")
+                .originalFilename("complete.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .metadataComplete(true)
+                .build());
+
+        assertThat(documentRepository.countByMetadataCompleteFalse()).isEqualTo(1);
+    }
+
+    // ─── findAll (PageRequest) — recent activity ──────────────────────────────
+
+    @Test
+    void findAll_withPageRequest_returnsOnlySizeRows_notFullTable() {
+        for (int i = 0; i < 10; i++) {
+            documentRepository.save(Document.builder()
+                    .title("Doc " + i).originalFilename("doc" + i + ".pdf")
+                    .status(DocumentStatus.PLACEHOLDER).build());
+        }
+
+        Page<Document> result = documentRepository.findAll(
+                PageRequest.of(0, 3, Sort.by(Sort.Direction.DESC, "updatedAt")));
+
+        assertThat(result.getContent()).hasSize(3);
+        assertThat(result.getTotalElements()).isEqualTo(10);
+    }
+
+    // ─── findByMetadataCompleteFalse (Pageable) ───────────────────────────────
+
+    @Test
+    void findByMetadataCompleteFalse_withPageable_returnsOnlyIncompleteAndRespectsSizeCap() {
+        for (int i = 0; i < 5; i++) {
+            documentRepository.save(Document.builder()
+                    .title("Incomplete " + i).originalFilename("inc" + i + ".pdf")
+                    .status(DocumentStatus.UPLOADED).metadataComplete(false).build());
+        }
+        documentRepository.save(Document.builder()
+                .title("Complete").originalFilename("complete.pdf")
+                .status(DocumentStatus.REVIEWED).metadataComplete(true).build());
+
+        Page<Document> result = documentRepository.findByMetadataCompleteFalse(
+                PageRequest.of(0, 3, Sort.by(Sort.Direction.DESC, "createdAt")));
+
+        assertThat(result.getContent()).hasSize(3);
+        assertThat(result.getTotalElements()).isEqualTo(5);
+        assertThat(result.getContent()).allMatch(d -> !d.isMetadataComplete());
+    }
+
+    // ─── findSinglePersonCorrespondence — DISTINCT / multi-receiver safety ────
+
+    @Test
+    void findSinglePersonCorrespondence_returnsExactlyOneResult_whenDocumentHasThreeReceiversAndOneMatchesPersonId() {
+        Person sender = personRepository.save(Person.builder()
+                .firstName("Hans").lastName("Müller").build());
+        Person receiver1 = personRepository.save(Person.builder()
+                .firstName("Anna").lastName("Schmidt").build());
+        Person receiver2 = personRepository.save(Person.builder()
+                .firstName("Bertha").lastName("Wagner").build());
+        Person receiver3 = personRepository.save(Person.builder()
+                .firstName("Clara").lastName("Koch").build());
+
+        // Document addressed to all three receivers
+        Document doc = documentRepository.save(Document.builder()
+                .title("Rundschreiben")
+                .originalFilename("rundschreiben.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(sender)
+                .receivers(new HashSet<>(Set.of(receiver1, receiver2, receiver3)))
+                .documentDate(LocalDate.of(1950, 6, 1))
+                .build());
+
+        Sort sort = Sort.by(Sort.Direction.DESC, "documentDate");
+        LocalDate from = LocalDate.of(1900, 1, 1);
+        LocalDate to = LocalDate.of(2000, 1, 1);
+
+        // Query for receiver1 — the DISTINCT must collapse the 3 JOIN rows into 1 result
+        List<Document> results = documentRepository.findSinglePersonCorrespondence(
+                receiver1.getId(), from, to, sort);
+
+        assertThat(results).hasSize(1);
+        assertThat(results.get(0).getId()).isEqualTo(doc.getId());
+    }
+
+    @Test
+    void findSinglePersonCorrespondence_includesDocumentsWherePerson_isSender() {
+        Person sender = personRepository.save(Person.builder()
+                .firstName("Hans").lastName("Müller").build());
+        Person receiver = personRepository.save(Person.builder()
+                .firstName("Anna").lastName("Schmidt").build());
+
+        documentRepository.save(Document.builder()
+                .title("Brief als Absender")
+                .originalFilename("brief_absender.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(sender)
+                .receivers(new HashSet<>(Set.of(receiver)))
+                .documentDate(LocalDate.of(1950, 6, 1))
+                .build());
+
+        Sort sort = Sort.by(Sort.Direction.DESC, "documentDate");
+        LocalDate from = LocalDate.of(1900, 1, 1);
+        LocalDate to = LocalDate.of(2000, 1, 1);
+
+        List<Document> results = documentRepository.findSinglePersonCorrespondence(
+                sender.getId(), from, to, sort);
+
+        assertThat(results).hasSize(1);
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/repository/DocumentSpecificationsTest.java

@@ -0,0 +1,354 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.config.FlywayConfig;
+import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentStatus;
+import org.raddatz.familienarchiv.model.Person;
+import org.raddatz.familienarchiv.model.PersonNameAlias;
+import org.raddatz.familienarchiv.model.PersonNameAliasType;
+import org.raddatz.familienarchiv.model.Tag;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
+import org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.data.jpa.domain.Specification;
+
+import java.time.LocalDate;
+import java.util.List;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.raddatz.familienarchiv.repository.DocumentSpecifications.*;
+
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import({PostgresContainerConfig.class, FlywayConfig.class})
+class DocumentSpecificationsTest {
+
+    @Autowired DocumentRepository documentRepository;
+    @Autowired PersonRepository personRepository;
+    @Autowired PersonNameAliasRepository aliasRepository;
+    @Autowired TagRepository tagRepository;
+
+    private Person sender;
+    private Person receiver;
+    private Document briefEarly;
+    private Document briefLate;
+    private Document photoDoc;
+
+    @BeforeEach
+    void setUp() {
+        documentRepository.deleteAll();
+        personRepository.deleteAll();
+        tagRepository.deleteAll();
+
+        sender   = personRepository.save(Person.builder().firstName("Walter").lastName("Müller").build());
+        receiver = personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+
+        Tag tagFamilie = tagRepository.save(Tag.builder().name("Familie").build());
+        Tag tagUrlaub  = tagRepository.save(Tag.builder().name("Urlaub").build());
+
+        briefEarly = documentRepository.save(Document.builder()
+                .title("Alter Brief")
+                .originalFilename("brief_early.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .documentDate(LocalDate.of(1940, 5, 1))
+                .transcription("Liebe Anna, ich schreibe dir aus dem Krieg")
+                .location("Berlin")
+                .sender(sender)
+                .receivers(Set.of(receiver))
+                .tags(Set.of(tagFamilie))
+                .build());
+
+        briefLate = documentRepository.save(Document.builder()
+                .title("Neuerer Brief")
+                .originalFilename("brief_late.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .documentDate(LocalDate.of(1960, 8, 15))
+                .sender(sender)
+                .tags(Set.of(tagUrlaub))
+                .build());
+
+        photoDoc = documentRepository.save(Document.builder()
+                .title("Familienfoto")
+                .originalFilename("familienfoto.jpg")
+                .status(DocumentStatus.PLACEHOLDER)
+                .build());
+    }
+
+    // ─── hasText ──────────────────────────────────────────────────────────────
+
+    @Test
+    void hasText_returnsAllDocuments_whenTextIsNull() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText(null)));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasText_returnsAllDocuments_whenTextIsBlank() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("   ")));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasText_filtersOnTitle() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("familienfoto")));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Familienfoto");
+    }
+
+    @Test
+    void hasText_filtersOnOriginalFilename() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("brief_late")));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Neuerer Brief");
+    }
+
+    @Test
+    void hasText_filtersOnTranscription() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("schreibe dir")));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasText_filtersOnLocation() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("berlin")));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasText_isCaseInsensitive() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("BRIEF")));
+        assertThat(result).extracting(Document::getTitle).containsExactlyInAnyOrder("Alter Brief", "Neuerer Brief");
+    }
+
+    @Test
+    void hasText_returnsEmpty_whenNoMatch() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("xyznotexist")));
+        assertThat(result).isEmpty();
+    }
+
+    // ─── hasSender ────────────────────────────────────────────────────────────
+
+    @Test
+    void hasSender_returnsAllDocuments_whenPersonIdIsNull() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasSender(null)));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasSender_filtersDocumentsBySender() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasSender(sender.getId())));
+        assertThat(result).extracting(Document::getTitle)
+                .containsExactlyInAnyOrder("Alter Brief", "Neuerer Brief");
+    }
+
+    @Test
+    void hasSender_returnsEmpty_whenSenderHasNoDocuments() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasSender(receiver.getId())));
+        assertThat(result).isEmpty();
+    }
+
+    // ─── hasReceiver ──────────────────────────────────────────────────────────
+
+    @Test
+    void hasReceiver_returnsAllDocuments_whenPersonIdIsNull() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasReceiver(null)));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasReceiver_filtersDocumentsByReceiver() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasReceiver(receiver.getId())));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasReceiver_returnsEmpty_whenReceiverHasNoDocuments() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasReceiver(sender.getId())));
+        assertThat(result).isEmpty();
+    }
+
+    // ─── isBetween ────────────────────────────────────────────────────────────
+
+    @Test
+    void isBetween_returnsAllDocuments_whenBothDatesAreNull() {
+        List<Document> result = documentRepository.findAll(Specification.where(isBetween(null, null)));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void isBetween_filtersByBothDates() {
+        List<Document> result = documentRepository.findAll(
+                Specification.where(isBetween(LocalDate.of(1939, 1, 1), LocalDate.of(1945, 12, 31))));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void isBetween_filtersByStartDateOnly() {
+        List<Document> result = documentRepository.findAll(
+                Specification.where(isBetween(LocalDate.of(1950, 1, 1), null)));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Neuerer Brief");
+    }
+
+    @Test
+    void isBetween_filtersByEndDateOnly() {
+        List<Document> result = documentRepository.findAll(
+                Specification.where(isBetween(null, LocalDate.of(1945, 12, 31))));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void isBetween_returnsEmpty_whenNoDatesInRange() {
+        List<Document> result = documentRepository.findAll(
+                Specification.where(isBetween(LocalDate.of(1970, 1, 1), LocalDate.of(1980, 12, 31))));
+        assertThat(result).isEmpty();
+    }
+
+    // ─── hasTags ──────────────────────────────────────────────────────────────
+
+    @Test
+    void hasTags_returnsAllDocuments_whenTagListIsNull() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTags(null)));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasTags_returnsAllDocuments_whenTagListIsEmpty() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTags(List.of())));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasTags_filtersDocumentsByTag() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTags(List.of("Familie"))));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasTags_isCaseInsensitive() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTags(List.of("familie"))));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasTags_requiresAllTagsToBePresent_andLogic() {
+        // briefEarly has "Familie" but not "Urlaub" — should be excluded
+        List<Document> result = documentRepository.findAll(
+                Specification.where(hasTags(List.of("Familie", "Urlaub"))));
+        assertThat(result).isEmpty();
+    }
+
+    @Test
+    void hasTags_skipsEmptyTagNames() {
+        // An empty string in the tag list should be ignored
+        List<Document> result = documentRepository.findAll(Specification.where(hasTags(List.of("  ", "Familie"))));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasTags_returnsEmpty_whenTagDoesNotExist() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTags(List.of("Unbekannt"))));
+        assertThat(result).isEmpty();
+    }
+
+    @Test
+    void hasText_findsByPartialSenderLastName() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("üller")));
+        assertThat(result).extracting(Document::getTitle)
+                .containsExactlyInAnyOrder("Alter Brief", "Neuerer Brief");
+    }
+
+    @Test
+    void hasText_findsByPartialReceiverLastName() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("schmid")));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasText_findsByPartialTagName() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("amili")));
+        assertThat(result).extracting(Document::getTitle)
+                .containsExactlyInAnyOrder("Alter Brief", "Familienfoto");
+    }
+
+    @Test
+    void hasText_doesNotProduceDuplicatesForDocumentWithMultipleReceivers() {
+        Person receiver2 = personRepository.save(Person.builder().firstName("Karl").lastName("Schmidt").build());
+        briefEarly.setReceivers(new java.util.HashSet<>(Set.of(receiver, receiver2)));
+        documentRepository.save(briefEarly);
+
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("schmid")));
+        assertThat(result).hasSize(1);
+    }
+
+    // ─── hasTagPartial ────────────────────────────────────────────────────────
+
+    @Test
+    void hasTagPartial_returnsAllDocuments_whenTextIsNull() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTagPartial(null)));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasTagPartial_findsByPartialTagName() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTagPartial("amili")));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Alter Brief");
+    }
+
+    @Test
+    void hasTagPartial_isCaseInsensitive() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTagPartial("URLAUB")));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Neuerer Brief");
+    }
+
+    @Test
+    void hasTagPartial_returnsEmpty_whenNoTagMatches() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasTagPartial("xyz")));
+        assertThat(result).isEmpty();
+    }
+
+    // ─── hasStatus ────────────────────────────────────────────────────────────
+
+    @Test
+    void hasStatus_returnsAllDocuments_whenStatusIsNull() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasStatus(null)));
+        assertThat(result).hasSize(3);
+    }
+
+    @Test
+    void hasStatus_returnsOnlyMatchingDocuments_whenStatusIsSet() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasStatus(DocumentStatus.PLACEHOLDER)));
+        assertThat(result).extracting(Document::getTitle).containsExactly("Familienfoto");
+    }
+
+    @Test
+    void hasStatus_returnsEmpty_whenNoDocumentMatchesStatus() {
+        List<Document> result = documentRepository.findAll(Specification.where(hasStatus(DocumentStatus.REVIEWED)));
+        assertThat(result).isEmpty();
+    }
+
+    // ─── hasText with aliases ────────────────────────────────────────────────
+
+    @Test
+    void hasText_findsDocumentBySenderAliasLastName() {
+        aliasRepository.save(PersonNameAlias.builder()
+                .person(sender).lastName("von Mueller").type(PersonNameAliasType.BIRTH).sortOrder(0).build());
+
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("von Mueller")));
+
+        assertThat(result).isNotEmpty();
+        assertThat(result).extracting(Document::getTitle).contains("Alter Brief");
+    }
+
+    @Test
+    void hasText_findsDocumentByReceiverAliasLastName() {
+        aliasRepository.save(PersonNameAlias.builder()
+                .person(receiver).lastName("de Gruyter").type(PersonNameAliasType.BIRTH).sortOrder(0).build());
+
+        List<Document> result = documentRepository.findAll(Specification.where(hasText("de Gruyter")));
+
+        assertThat(result).isNotEmpty();
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/repository/NotificationRepositoryTest.java

@@ -0,0 +1,119 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.config.FlywayConfig;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.Notification;
+import org.raddatz.familienarchiv.model.NotificationType;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
+import org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import({PostgresContainerConfig.class, FlywayConfig.class})
+class NotificationRepositoryTest {
+
+    @Autowired NotificationRepository notificationRepository;
+    @Autowired AppUserRepository appUserRepository;
+
+    private AppUser userA;
+    private AppUser userB;
+
+    @BeforeEach
+    void setUp() {
+        notificationRepository.deleteAll();
+        appUserRepository.deleteAll();
+        userA = appUserRepository.save(AppUser.builder().username("userA").password("pw").build());
+        userB = appUserRepository.save(AppUser.builder().username("userB").password("pw").build());
+    }
+
+    // ─── findByRecipientIdAndTypeAndReadFalse ─────────────────────────────────
+
+    @Test
+    void returnsOnlyUnreadMentions_forTargetUser() {
+        notificationRepository.save(mention(userA, false)); // ✓ match
+        notificationRepository.save(mention(userA, true));  // read — excluded
+        notificationRepository.save(reply(userA, false));   // REPLY — excluded
+        notificationRepository.save(mention(userB, false)); // different user — excluded
+
+        Page<Notification> result = notificationRepository
+                .findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(
+                        userA.getId(), NotificationType.MENTION, Pageable.ofSize(10));
+
+        assertThat(result.getContent()).hasSize(1);
+        assertThat(result.getContent().get(0).getRecipient().getId()).isEqualTo(userA.getId());
+        assertThat(result.getContent().get(0).getType()).isEqualTo(NotificationType.MENTION);
+        assertThat(result.getContent().get(0).isRead()).isFalse();
+    }
+
+    @Test
+    void returnsEmpty_whenAllMentionsAreRead() {
+        notificationRepository.save(mention(userA, true));
+
+        Page<Notification> result = notificationRepository
+                .findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(
+                        userA.getId(), NotificationType.MENTION, Pageable.ofSize(10));
+
+        assertThat(result.getContent()).isEmpty();
+    }
+
+    @Test
+    void respectsSizeLimit() {
+        for (int i = 0; i < 5; i++) {
+            notificationRepository.save(mention(userA, false));
+        }
+
+        Page<Notification> result = notificationRepository
+                .findByRecipientIdAndTypeAndReadFalseOrderByCreatedAtDesc(
+                        userA.getId(), NotificationType.MENTION, Pageable.ofSize(3));
+
+        assertThat(result.getContent()).hasSize(3);
+        assertThat(result.getTotalElements()).isEqualTo(5);
+    }
+
+    // ─── findByRecipientIdAndType (without read filter) ──────────────────────
+
+    @Test
+    void findByType_returnsBothReadAndUnreadMentions() {
+        notificationRepository.save(mention(userA, false)); // unread
+        notificationRepository.save(mention(userA, true));  // read — should also be included
+        notificationRepository.save(reply(userA, false));   // REPLY — excluded
+        notificationRepository.save(mention(userB, false)); // different user — excluded
+
+        Page<Notification> result = notificationRepository
+                .findByRecipientIdAndTypeOrderByCreatedAtDesc(
+                        userA.getId(), NotificationType.MENTION, Pageable.ofSize(10));
+
+        assertThat(result.getContent()).hasSize(2);
+        assertThat(result.getContent()).allMatch(n -> n.getType() == NotificationType.MENTION);
+        assertThat(result.getContent()).allMatch(n -> n.getRecipient().getId().equals(userA.getId()));
+    }
+
+    // ─── helpers ─────────────────────────────────────────────────────────────
+
+    private Notification mention(AppUser recipient, boolean read) {
+        return Notification.builder()
+                .recipient(recipient)
+                .type(NotificationType.MENTION)
+                .actorName("Tester")
+                .read(read)
+                .build();
+    }
+
+    private Notification reply(AppUser recipient, boolean read) {
+        return Notification.builder()
+                .recipient(recipient)
+                .type(NotificationType.REPLY)
+                .actorName("Tester")
+                .read(read)
+                .build();
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/repository/PersonRepositoryTest.java

@@ -0,0 +1,443 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.config.FlywayConfig;
+import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentStatus;
+import org.raddatz.familienarchiv.model.Person;
+import org.raddatz.familienarchiv.model.PersonNameAlias;
+import org.raddatz.familienarchiv.model.PersonNameAliasType;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
+import org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest;
+import org.springframework.context.annotation.Import;
+
+import org.raddatz.familienarchiv.dto.PersonSummaryDTO;
+
+import jakarta.persistence.EntityManager;
+import jakarta.persistence.PersistenceContext;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import({PostgresContainerConfig.class, FlywayConfig.class})
+class PersonRepositoryTest {
+
+    @Autowired
+    private PersonRepository personRepository;
+
+    @Autowired
+    private PersonNameAliasRepository aliasRepository;
+
+    @Autowired
+    private DocumentRepository documentRepository;
+
+    @PersistenceContext
+    private EntityManager entityManager;
+
+    // ─── save and findById ────────────────────────────────────────────────────
+
+    @Test
+    void save_persistsPerson_andFindByIdReturnsSamePerson() {
+        Person person = Person.builder()
+                .firstName("Anna")
+                .lastName("Schmidt")
+                .build();
+
+        Person saved = personRepository.save(person);
+        Optional<Person> found = personRepository.findById(saved.getId());
+
+        assertThat(found).isPresent();
+        assertThat(found.get().getFirstName()).isEqualTo("Anna");
+        assertThat(found.get().getLastName()).isEqualTo("Schmidt");
+    }
+
+    // ─── searchByName ─────────────────────────────────────────────────────────
+
+    @Test
+    void searchByName_findsByFirstName() {
+        personRepository.save(Person.builder().firstName("Hans").lastName("Müller").build());
+        personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+
+        List<Person> results = personRepository.searchByName("Hans");
+
+        assertThat(results).hasSize(1);
+        assertThat(results.get(0).getFirstName()).isEqualTo("Hans");
+    }
+
+    @Test
+    void searchByName_findsByLastName() {
+        personRepository.save(Person.builder().firstName("Hans").lastName("Müller").build());
+        personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+
+        List<Person> results = personRepository.searchByName("Schmidt");
+
+        assertThat(results).hasSize(1);
+        assertThat(results.get(0).getLastName()).isEqualTo("Schmidt");
+    }
+
+    @Test
+    void searchByName_isCaseInsensitive() {
+        personRepository.save(Person.builder().firstName("Hans").lastName("Müller").build());
+
+        List<Person> results = personRepository.searchByName("hans");
+
+        assertThat(results).hasSize(1);
+    }
+
+    @Test
+    void searchByName_findsByAlias() {
+        personRepository.save(Person.builder()
+                .firstName("Hans").lastName("Müller").alias("Opa Hans").build());
+
+        List<Person> results = personRepository.searchByName("Opa Hans");
+
+        assertThat(results).hasSize(1);
+    }
+
+    // ─── findAllByOrderByLastNameAscFirstNameAsc ──────────────────────────────
+
+    @Test
+    void findAllByOrderByLastNameAscFirstNameAsc_returnsSortedByLastNameThenFirstName() {
+        personRepository.save(Person.builder().firstName("Bernd").lastName("Ziegler").build());
+        personRepository.save(Person.builder().firstName("Anna").lastName("Müller").build());
+        personRepository.save(Person.builder().firstName("Clara").lastName("Müller").build());
+
+        List<Person> sorted = personRepository.findAllByOrderByLastNameAscFirstNameAsc();
+
+        assertThat(sorted).extracting(Person::getLastName)
+                .startsWith("Müller", "Müller");
+        assertThat(sorted.stream()
+                .filter(p -> p.getLastName().equals("Müller"))
+                .map(Person::getFirstName)
+                .toList())
+                .containsExactly("Anna", "Clara");
+    }
+
+    // ─── findByAliasIgnoreCase ────────────────────────────────────────────────
+
+    @Test
+    void findByAliasIgnoreCase_returnsMatchingPerson() {
+        personRepository.save(Person.builder()
+                .firstName("Karl").lastName("Brandt").alias("Opa Karl").build());
+
+        Optional<Person> found = personRepository.findByAliasIgnoreCase("opa karl");
+
+        assertThat(found).isPresent();
+        assertThat(found.get().getFirstName()).isEqualTo("Karl");
+    }
+
+    @Test
+    void findByAliasIgnoreCase_returnsEmpty_whenAliasDoesNotMatch() {
+        Optional<Person> found = personRepository.findByAliasIgnoreCase("nobody");
+
+        assertThat(found).isEmpty();
+    }
+
+    // ─── findByFirstNameIgnoreCaseAndLastNameIgnoreCase ───────────────────────
+
+    @Test
+    void findByFirstNameIgnoreCaseAndLastNameIgnoreCase_returnsMatch() {
+        personRepository.save(Person.builder().firstName("Maria").lastName("Raddatz").build());
+
+        Optional<Person> found = personRepository.findByFirstNameIgnoreCaseAndLastNameIgnoreCase(
+                "maria", "raddatz");
+
+        assertThat(found).isPresent();
+        assertThat(found.get().getFirstName()).isEqualTo("Maria");
+    }
+
+    // ─── findCorrespondents ───────────────────────────────────────────────────
+
+    @Test
+    void findCorrespondents_returnsPersonsWhoSharedDocumentsWith() {
+        Person walter = personRepository.save(Person.builder().firstName("Walter").lastName("Müller").build());
+        Person anna   = personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+        Person clara  = personRepository.save(Person.builder().firstName("Clara").lastName("Cram").build());
+
+        // Walter sends to Anna (1 document)
+        documentRepository.save(Document.builder()
+                .title("Brief 1").originalFilename("brief1.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(anna)).build());
+
+        // Walter sends to Clara (2 documents — Clara should rank higher)
+        documentRepository.save(Document.builder()
+                .title("Brief 2").originalFilename("brief2.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(clara)).build());
+        documentRepository.save(Document.builder()
+                .title("Brief 3").originalFilename("brief3.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(clara)).build());
+
+        List<Person> correspondents = personRepository.findCorrespondents(walter.getId());
+
+        assertThat(correspondents).extracting(Person::getFirstName)
+                .containsExactly("Clara", "Anna"); // Clara ranks first (2 documents)
+    }
+
+    @Test
+    void findCorrespondents_returnsEmpty_whenPersonHasNoDocuments() {
+        Person solo = personRepository.save(Person.builder().firstName("Solo").lastName("Mensch").build());
+
+        List<Person> correspondents = personRepository.findCorrespondents(solo.getId());
+
+        assertThat(correspondents).isEmpty();
+    }
+
+    // ─── findCorrespondentsWithFilter ─────────────────────────────────────────
+
+    @Test
+    void findCorrespondentsWithFilter_returnsOnlyMatchingCorrespondents() {
+        Person walter = personRepository.save(Person.builder().firstName("Walter").lastName("Müller").build());
+        Person anna   = personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+        Person bernd  = personRepository.save(Person.builder().firstName("Bernd").lastName("Braun").build());
+
+        documentRepository.save(Document.builder()
+                .title("Brief an Anna").originalFilename("anna.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(anna)).build());
+        documentRepository.save(Document.builder()
+                .title("Brief an Bernd").originalFilename("bernd.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(bernd)).build());
+
+        List<Person> filtered = personRepository.findCorrespondentsWithFilter(walter.getId(), "Anna");
+
+        assertThat(filtered).extracting(Person::getFirstName).containsExactly("Anna");
+    }
+
+    @Test
+    void findCorrespondentsWithFilter_isCaseInsensitive() {
+        Person walter = personRepository.save(Person.builder().firstName("Walter").lastName("Müller").build());
+        Person anna   = personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+
+        documentRepository.save(Document.builder()
+                .title("Brief").originalFilename("brief.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(anna)).build());
+
+        List<Person> filtered = personRepository.findCorrespondentsWithFilter(walter.getId(), "schmidt");
+
+        assertThat(filtered).hasSize(1);
+        assertThat(filtered.get(0).getLastName()).isEqualTo("Schmidt");
+    }
+
+    // ─── reassignSender ───────────────────────────────────────────────────────
+
+    @Test
+    void reassignSender_updatesDocumentsSenderFromSourceToTarget() {
+        Person source = personRepository.save(Person.builder().firstName("Alt").lastName("Person").build());
+        Person target = personRepository.save(Person.builder().firstName("Neu").lastName("Person").build());
+
+        documentRepository.save(Document.builder()
+                .title("Brief").originalFilename("brief.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(source).build());
+
+        personRepository.reassignSender(source.getId(), target.getId());
+        entityManager.flush();
+        entityManager.clear();
+
+        List<Document> docs = documentRepository.findBySenderId(target.getId());
+        assertThat(docs).hasSize(1);
+        assertThat(documentRepository.findBySenderId(source.getId())).isEmpty();
+    }
+
+    // ─── insertMissingReceiverReference ──────────────────────────────────────
+
+    @Test
+    void insertMissingReceiverReference_addsTargetWhereSourceWasReceiver() {
+        Person source = personRepository.save(Person.builder().firstName("Alt").lastName("Person").build());
+        Person target = personRepository.save(Person.builder().firstName("Neu").lastName("Person").build());
+        Person sender = personRepository.save(Person.builder().firstName("Send").lastName("Er").build());
+
+        Document doc = documentRepository.save(Document.builder()
+                .title("Brief").originalFilename("brief.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(sender).receivers(Set.of(source)).build());
+
+        personRepository.insertMissingReceiverReference(source.getId(), target.getId());
+        entityManager.flush();
+        entityManager.clear();
+
+        Document reloaded = documentRepository.findById(doc.getId()).orElseThrow();
+        assertThat(reloaded.getReceivers())
+                .extracting(Person::getId)
+                .contains(target.getId());
+    }
+
+    @Test
+    void insertMissingReceiverReference_doesNotCreateDuplicate_whenTargetAlreadyReceiver() {
+        Person source = personRepository.save(Person.builder().firstName("Alt").lastName("Person").build());
+        Person target = personRepository.save(Person.builder().firstName("Neu").lastName("Person").build());
+        Person sender = personRepository.save(Person.builder().firstName("Send").lastName("Er").build());
+
+        // target is already a receiver together with source
+        Document doc = documentRepository.save(Document.builder()
+                .title("Brief").originalFilename("brief.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(sender).receivers(Set.of(source, target)).build());
+
+        personRepository.insertMissingReceiverReference(source.getId(), target.getId());
+        entityManager.flush();
+        entityManager.clear();
+
+        Document reloaded = documentRepository.findById(doc.getId()).orElseThrow();
+        long targetCount = reloaded.getReceivers().stream()
+                .filter(p -> p.getId().equals(target.getId())).count();
+        assertThat(targetCount).isEqualTo(1); // no duplicate
+    }
+
+    // ─── Phase 3.2: findAllWithDocumentCount ──────────────────────────────────
+
+    @Test
+    void findAllWithDocumentCount_includesDocumentCountAsSenderAndReceiver() {
+        Person walter = personRepository.save(Person.builder().firstName("Walter").lastName("Müller").build());
+        Person anna   = personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+
+        // Walter sends 2 docs to Anna (Anna receives 2)
+        documentRepository.save(Document.builder()
+                .title("Brief 1").originalFilename("b1.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(anna)).build());
+        documentRepository.save(Document.builder()
+                .title("Brief 2").originalFilename("b2.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(walter).receivers(Set.of(anna)).build());
+        // Anna also sends 1 doc to Walter
+        documentRepository.save(Document.builder()
+                .title("Brief 3").originalFilename("b3.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(anna).receivers(Set.of(walter)).build());
+
+        List<PersonSummaryDTO> result = personRepository.findAllWithDocumentCount();
+
+        PersonSummaryDTO walterSummary = result.stream()
+                .filter(p -> p.getId().equals(walter.getId())).findFirst().orElseThrow();
+        PersonSummaryDTO annaSummary = result.stream()
+                .filter(p -> p.getId().equals(anna.getId())).findFirst().orElseThrow();
+
+        assertThat(walterSummary.getDocumentCount()).isEqualTo(3); // sent 2, received 1
+        assertThat(annaSummary.getDocumentCount()).isEqualTo(3);   // sent 1, received 2
+    }
+
+    @Test
+    void findAllWithDocumentCount_returnsZero_whenPersonHasNoDocuments() {
+        Person solo = personRepository.save(Person.builder().firstName("Solo").lastName("Mensch").build());
+
+        List<PersonSummaryDTO> result = personRepository.findAllWithDocumentCount();
+
+        PersonSummaryDTO soloSummary = result.stream()
+                .filter(p -> p.getId().equals(solo.getId())).findFirst().orElseThrow();
+        assertThat(soloSummary.getDocumentCount()).isEqualTo(0);
+    }
+
+    @Test
+    void searchWithDocumentCount_filtersAndIncludesCount() {
+        Person hans = personRepository.save(Person.builder().firstName("Hans").lastName("Müller").build());
+        Person anna = personRepository.save(Person.builder().firstName("Anna").lastName("Schmidt").build());
+
+        documentRepository.save(Document.builder()
+                .title("Brief").originalFilename("brief.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(hans).receivers(Set.of(anna)).build());
+
+        List<PersonSummaryDTO> result = personRepository.searchWithDocumentCount("Hans");
+
+        assertThat(result).hasSize(1);
+        assertThat(result.get(0).getFirstName()).isEqualTo("Hans");
+        assertThat(result.get(0).getDocumentCount()).isEqualTo(1);
+    }
+
+    @Test
+    void searchWithDocumentCount_isCaseInsensitive() {
+        personRepository.save(Person.builder().firstName("Hans").lastName("Müller").build());
+
+        List<PersonSummaryDTO> result = personRepository.searchWithDocumentCount("hans");
+
+        assertThat(result).hasSize(1);
+    }
+
+    // ─── deleteReceiverReferences ─────────────────────────────────────────────
+
+    @Test
+    void deleteReceiverReferences_removesPersonFromAllDocumentReceivers() {
+        Person toDelete = personRepository.save(Person.builder().firstName("Weg").lastName("Person").build());
+        Person sender   = personRepository.save(Person.builder().firstName("Send").lastName("Er").build());
+
+        Document doc1 = documentRepository.save(Document.builder()
+                .title("Brief 1").originalFilename("b1.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(sender).receivers(Set.of(toDelete)).build());
+        Document doc2 = documentRepository.save(Document.builder()
+                .title("Brief 2").originalFilename("b2.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .sender(sender).receivers(Set.of(toDelete)).build());
+
+        personRepository.deleteReceiverReferences(toDelete.getId());
+        entityManager.flush();
+        entityManager.clear();
+
+        assertThat(documentRepository.findById(doc1.getId()).orElseThrow().getReceivers()).isEmpty();
+        assertThat(documentRepository.findById(doc2.getId()).orElseThrow().getReceivers()).isEmpty();
+    }
+
+    // ─── searchByName with aliases ───────────────────────────────────────────
+
+    @Test
+    void searchByName_findsByAliasLastName() {
+        Person clara = personRepository.save(Person.builder().firstName("Clara").lastName("Cram").build());
+        aliasRepository.save(PersonNameAlias.builder()
+                .person(clara).lastName("de Gruyter").type(PersonNameAliasType.BIRTH).sortOrder(0).build());
+
+        List<Person> results = personRepository.searchByName("de Gruyter");
+
+        assertThat(results).hasSize(1);
+        assertThat(results.get(0).getLastName()).isEqualTo("Cram");
+    }
+
+    @Test
+    void searchByName_stillFindsByCurrentLastName_afterAliasAdded() {
+        Person clara = personRepository.save(Person.builder().firstName("Clara").lastName("Cram").build());
+        aliasRepository.save(PersonNameAlias.builder()
+                .person(clara).lastName("de Gruyter").type(PersonNameAliasType.BIRTH).sortOrder(0).build());
+
+        List<Person> results = personRepository.searchByName("Cram");
+
+        assertThat(results).hasSize(1);
+    }
+
+    @Test
+    void searchByName_doesNotReturnDuplicates_whenMultipleAliasesMatch() {
+        Person clara = personRepository.save(Person.builder().firstName("Clara").lastName("Cram").build());
+        aliasRepository.save(PersonNameAlias.builder()
+                .person(clara).lastName("de Gruyter").type(PersonNameAliasType.BIRTH).sortOrder(0).build());
+        aliasRepository.save(PersonNameAlias.builder()
+                .person(clara).lastName("Gruyter-Cram").type(PersonNameAliasType.OTHER).sortOrder(1).build());
+
+        List<Person> results = personRepository.searchByName("Gruyter");
+
+        assertThat(results).hasSize(1);
+    }
+
+    // ─── searchWithDocumentCount with aliases ────────────────────────────────
+
+    @Test
+    void searchWithDocumentCount_findsByAliasLastName() {
+        Person clara = personRepository.save(Person.builder().firstName("Clara").lastName("Cram").build());
+        aliasRepository.save(PersonNameAlias.builder()
+                .person(clara).lastName("de Gruyter").type(PersonNameAliasType.BIRTH).sortOrder(0).build());
+
+        List<PersonSummaryDTO> results = personRepository.searchWithDocumentCount("de Gruyter");
+
+        assertThat(results).hasSize(1);
+        assertThat(results.get(0).getLastName()).isEqualTo("Cram");
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/repository/TranscriptionBlockRepositoryTest.java

@@ -0,0 +1,193 @@
+package org.raddatz.familienarchiv.repository;
+
+import jakarta.persistence.EntityManager;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.PostgresContainerConfig;
+import org.raddatz.familienarchiv.config.FlywayConfig;
+import org.raddatz.familienarchiv.model.*;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
+import org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import({PostgresContainerConfig.class, FlywayConfig.class})
+class TranscriptionBlockRepositoryTest {
+
+    @Autowired TranscriptionBlockRepository blockRepository;
+    @Autowired TranscriptionBlockVersionRepository versionRepository;
+    @Autowired DocumentRepository documentRepository;
+    @Autowired AnnotationRepository annotationRepository;
+    @Autowired EntityManager em;
+
+    private UUID documentId;
+    private UUID annotationId;
+
+    @BeforeEach
+    void setUp() {
+        Document doc = documentRepository.save(Document.builder()
+                .title("Testbrief")
+                .originalFilename("brief.pdf")
+                .status(DocumentStatus.UPLOADED)
+                .build());
+        documentId = doc.getId();
+
+        DocumentAnnotation annotation = annotationRepository.save(DocumentAnnotation.builder()
+                .documentId(documentId)
+                .pageNumber(1)
+                .x(0.1).y(0.2).width(0.3).height(0.4)
+                .color("#00C7B1")
+                .build());
+        annotationId = annotation.getId();
+    }
+
+    // ─── findByDocumentIdOrderBySortOrderAsc ─────────────────────────────────
+
+    @Test
+    void findByDocumentIdOrderBySortOrderAsc_returnsBlocksInSortOrder() {
+        blockRepository.save(block("Block B", 1));
+        blockRepository.save(block("Block A", 0));
+        blockRepository.save(block("Block C", 2));
+
+        List<TranscriptionBlock> result = blockRepository.findByDocumentIdOrderBySortOrderAsc(documentId);
+
+        assertThat(result).hasSize(3);
+        assertThat(result.get(0).getText()).isEqualTo("Block A");
+        assertThat(result.get(1).getText()).isEqualTo("Block B");
+        assertThat(result.get(2).getText()).isEqualTo("Block C");
+    }
+
+    @Test
+    void findByDocumentIdOrderBySortOrderAsc_returnsEmptyList_whenNoBlocksForDocument() {
+        UUID otherId = UUID.randomUUID();
+        List<TranscriptionBlock> result = blockRepository.findByDocumentIdOrderBySortOrderAsc(otherId);
+        assertThat(result).isEmpty();
+    }
+
+    @Test
+    void findByDocumentIdOrderBySortOrderAsc_doesNotReturnBlocksFromOtherDocument() {
+        blockRepository.save(block("My block", 0));
+
+        Document other = documentRepository.save(Document.builder()
+                .title("Anderer Brief").originalFilename("other.pdf").status(DocumentStatus.PLACEHOLDER).build());
+
+        List<TranscriptionBlock> result = blockRepository.findByDocumentIdOrderBySortOrderAsc(other.getId());
+        assertThat(result).isEmpty();
+    }
+
+    // ─── findByIdAndDocumentId ────────────────────────────────────────────────
+
+    @Test
+    void findByIdAndDocumentId_returnsBlock_whenBothMatch() {
+        TranscriptionBlock saved = blockRepository.save(block("Liebe Tante,", 0));
+
+        Optional<TranscriptionBlock> found = blockRepository.findByIdAndDocumentId(saved.getId(), documentId);
+
+        assertThat(found).isPresent();
+        assertThat(found.get().getText()).isEqualTo("Liebe Tante,");
+    }
+
+    @Test
+    void findByIdAndDocumentId_returnsEmpty_whenDocumentIdDoesNotMatch() {
+        TranscriptionBlock saved = blockRepository.save(block("Liebe Tante,", 0));
+
+        Optional<TranscriptionBlock> found = blockRepository.findByIdAndDocumentId(saved.getId(), UUID.randomUUID());
+
+        assertThat(found).isEmpty();
+    }
+
+    @Test
+    void findByIdAndDocumentId_returnsEmpty_whenBlockIdDoesNotExist() {
+        Optional<TranscriptionBlock> found = blockRepository.findByIdAndDocumentId(UUID.randomUUID(), documentId);
+        assertThat(found).isEmpty();
+    }
+
+    // ─── countByDocumentId ────────────────────────────────────────────────────
+
+    @Test
+    void countByDocumentId_returnsZero_whenNoBlocksExist() {
+        assertThat(blockRepository.countByDocumentId(documentId)).isZero();
+    }
+
+    @Test
+    void countByDocumentId_returnsCorrectCount_afterMultipleSaves() {
+        blockRepository.save(block("Block 1", 0));
+        blockRepository.save(block("Block 2", 1));
+        blockRepository.save(block("Block 3", 2));
+
+        assertThat(blockRepository.countByDocumentId(documentId)).isEqualTo(3);
+    }
+
+    @Test
+    void countByDocumentId_doesNotCountBlocksFromOtherDocument() {
+        blockRepository.save(block("Block 1", 0));
+
+        UUID otherId = UUID.randomUUID();
+        assertThat(blockRepository.countByDocumentId(otherId)).isZero();
+    }
+
+    // ─── version (optimistic lock) ────────────────────────────────────────────
+
+    @Test
+    void version_startsAtZero_andIncrementsOnEachSave() {
+        TranscriptionBlock saved = blockRepository.saveAndFlush(block("initial", 0));
+        assertThat(saved.getVersion()).isZero();
+
+        saved.setText("updated");
+        TranscriptionBlock updated = blockRepository.saveAndFlush(saved);
+        assertThat(updated.getVersion()).isEqualTo(1);
+    }
+
+    // ─── cascade: deleting a block cascades to its versions ──────────────────
+
+    @Test
+    @Transactional
+    void delete_cascadesToVersions() {
+        TranscriptionBlock block = blockRepository.saveAndFlush(block("text", 0));
+        versionRepository.saveAndFlush(TranscriptionBlockVersion.builder()
+                .blockId(block.getId()).text("text").build());
+
+        assertThat(versionRepository.findByBlockIdOrderByChangedAtDesc(block.getId())).hasSize(1);
+
+        blockRepository.delete(block);
+        blockRepository.flush();
+        em.clear();
+
+        assertThat(versionRepository.findByBlockIdOrderByChangedAtDesc(block.getId())).isEmpty();
+    }
+
+    // ─── cascade: deleting a document cascades to its blocks ─────────────────
+
+    @Test
+    @Transactional
+    void deleteDocument_cascadesToBlocks() {
+        blockRepository.saveAndFlush(block("text", 0));
+        assertThat(blockRepository.findByDocumentIdOrderBySortOrderAsc(documentId)).hasSize(1);
+
+        documentRepository.deleteById(documentId);
+        documentRepository.flush();
+        em.clear();
+
+        assertThat(blockRepository.findByDocumentIdOrderBySortOrderAsc(documentId)).isEmpty();
+    }
+
+    // ─── helper ──────────────────────────────────────────────────────────────
+
+    private TranscriptionBlock block(String text, int sortOrder) {
+        return TranscriptionBlock.builder()
+                .annotationId(annotationId)
+                .documentId(documentId)
+                .text(text)
+                .sortOrder(sortOrder)
+                .build();
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/service/AnnotationServiceTest.java

@@ -44,7 +44,7 @@ class AnnotationServiceTest {
         when(annotationRepository.findByDocumentIdAndPageNumber(docId, 1))
                 .thenReturn(List.of(existing));
 
-        assertThatThrownBy(() -> annotationService.createAnnotation(docId, dto, userId))
+        assertThatThrownBy(() -> annotationService.createAnnotation(docId, dto, userId, null))
                 .isInstanceOf(DomainException.class)
                 .satisfies(e -> assertThat(((DomainException) e).getStatus()).isEqualTo(CONFLICT));
 
@@ -63,7 +63,7 @@ class AnnotationServiceTest {
                 .x(0.0).y(0.0).width(0.05).height(0.05).color("#ff0000").createdBy(userId).build();
         when(annotationRepository.save(any())).thenReturn(saved);
 
-        DocumentAnnotation result = annotationService.createAnnotation(docId, dto, userId);
+        DocumentAnnotation result = annotationService.createAnnotation(docId, dto, userId, null);
 
         assertThat(result).isEqualTo(saved);
         verify(annotationRepository).save(any());
@@ -117,6 +117,35 @@ class AnnotationServiceTest {
         verify(annotationRepository).delete(annotation);
     }
 
+    @Test
+    void createAnnotation_setsFileHash_whenProvided() {
+        UUID docId = UUID.randomUUID();
+        UUID userId = UUID.randomUUID();
+        CreateAnnotationDTO dto = new CreateAnnotationDTO(1, 0.0, 0.0, 0.05, 0.05, "#ff0000");
+        String fileHash = "abc123";
+
+        when(annotationRepository.findByDocumentIdAndPageNumber(docId, 1)).thenReturn(List.of());
+        when(annotationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        DocumentAnnotation result = annotationService.createAnnotation(docId, dto, userId, fileHash);
+
+        assertThat(result.getFileHash()).isEqualTo(fileHash);
+    }
+
+    @Test
+    void createAnnotation_setsNullFileHash_whenNoneProvided() {
+        UUID docId = UUID.randomUUID();
+        UUID userId = UUID.randomUUID();
+        CreateAnnotationDTO dto = new CreateAnnotationDTO(1, 0.0, 0.0, 0.05, 0.05, "#ff0000");
+
+        when(annotationRepository.findByDocumentIdAndPageNumber(docId, 1)).thenReturn(List.of());
+        when(annotationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        DocumentAnnotation result = annotationService.createAnnotation(docId, dto, userId, null);
+
+        assertThat(result.getFileHash()).isNull();
+    }
+
     // ─── listAnnotations ──────────────────────────────────────────────────────
 
     @Test
@@ -128,4 +157,126 @@ class AnnotationServiceTest {
 
         assertThat(annotationService.listAnnotations(docId)).containsExactly(a);
     }
+
+    // ─── backfillAnnotationFileHashForDocument ────────────────────────────────
+
+    @Test
+    void backfillAnnotationFileHashForDocument_setsHashOnAnnotationsWithNullHash() {
+        UUID docId = UUID.randomUUID();
+        String hash = "abc123";
+        DocumentAnnotation a = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).build();
+        when(annotationRepository.findByDocumentIdAndFileHashIsNull(docId)).thenReturn(List.of(a));
+
+        annotationService.backfillAnnotationFileHashForDocument(docId, hash);
+
+        assertThat(a.getFileHash()).isEqualTo(hash);
+        verify(annotationRepository).save(a);
+    }
+
+    @Test
+    void backfillAnnotationFileHashForDocument_doesNothingWhenNoAnnotations() {
+        UUID docId = UUID.randomUUID();
+        when(annotationRepository.findByDocumentIdAndFileHashIsNull(docId)).thenReturn(List.of());
+
+        annotationService.backfillAnnotationFileHashForDocument(docId, "hash");
+
+        verify(annotationRepository, never()).save(any());
+    }
+
+    // ─── deleteAnnotation — null userId ───────────────────────────────────────
+
+    @Test
+    void deleteAnnotation_throwsForbidden_whenUserIdIsNull() {
+        UUID docId = UUID.randomUUID();
+        UUID annotId = UUID.randomUUID();
+        UUID ownerId = UUID.randomUUID();
+
+        DocumentAnnotation annotation = DocumentAnnotation.builder()
+                .id(annotId).documentId(docId).createdBy(ownerId).build();
+        when(annotationRepository.findByIdAndDocumentId(annotId, docId))
+                .thenReturn(Optional.of(annotation));
+
+        assertThatThrownBy(() -> annotationService.deleteAnnotation(docId, annotId, null))
+                .isInstanceOf(DomainException.class)
+                .satisfies(e -> assertThat(((DomainException) e).getStatus()).isEqualTo(FORBIDDEN));
+    }
+
+    // ─── overlaps — partial overlap cases ────────────────────────────────────
+
+    @Test
+    void createAnnotation_noConflict_whenAnnotationIsToTheLeft() {
+        // existing: x=0.5, w=0.3 (x2=0.8); dto: x=0.0, w=0.4 (dx2=0.4)
+        // existing.getX() < dx2 → 0.5 < 0.4 → FALSE → no overlap (first && fails)
+        UUID docId = UUID.randomUUID();
+        DocumentAnnotation existing = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.5).y(0.0).width(0.3).height(0.5).color("#ff0000").build();
+        CreateAnnotationDTO dto = new CreateAnnotationDTO(1, 0.0, 0.0, 0.4, 0.5, "#0000ff");
+        when(annotationRepository.findByDocumentIdAndPageNumber(docId, 1)).thenReturn(List.of(existing));
+        when(annotationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        annotationService.createAnnotation(docId, dto, UUID.randomUUID(), null);
+
+        verify(annotationRepository).save(any());
+    }
+
+    @Test
+    void createAnnotation_noConflict_whenAnnotationIsToTheRight() {
+        // existing: x=0.0, w=0.1 (ex2=0.1); dto: x=0.2, w=0.3 (dx2=0.5)
+        // existing.getX() < dx2 → 0.0 < 0.5 → TRUE
+        // ex2 > dto.getX() → 0.1 > 0.2 → FALSE → no overlap (second && fails)
+        UUID docId = UUID.randomUUID();
+        DocumentAnnotation existing = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.0).y(0.0).width(0.1).height(0.5).color("#ff0000").build();
+        CreateAnnotationDTO dto = new CreateAnnotationDTO(1, 0.2, 0.0, 0.3, 0.5, "#0000ff");
+        when(annotationRepository.findByDocumentIdAndPageNumber(docId, 1)).thenReturn(List.of(existing));
+        when(annotationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        annotationService.createAnnotation(docId, dto, UUID.randomUUID(), null);
+
+        verify(annotationRepository).save(any());
+    }
+
+    @Test
+    void createAnnotation_noConflict_whenAnnotationIsBelow() {
+        // x ranges overlap, but y ranges don't
+        // existing: x=0.0, w=0.5, y=0.5, h=0.2 (ey2=0.7)
+        // dto: x=0.1, w=0.3 (dx2=0.4), y=0.0, h=0.4 (dy2=0.4)
+        // existing.getX() < dx2 → 0.0 < 0.4 → TRUE
+        // ex2 > dto.getX() → 0.5 > 0.1 → TRUE
+        // existing.getY() < dy2 → 0.5 < 0.4 → FALSE → no overlap (third && fails)
+        UUID docId = UUID.randomUUID();
+        DocumentAnnotation existing = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.0).y(0.5).width(0.5).height(0.2).color("#ff0000").build();
+        CreateAnnotationDTO dto = new CreateAnnotationDTO(1, 0.1, 0.0, 0.3, 0.4, "#0000ff");
+        when(annotationRepository.findByDocumentIdAndPageNumber(docId, 1)).thenReturn(List.of(existing));
+        when(annotationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        annotationService.createAnnotation(docId, dto, UUID.randomUUID(), null);
+
+        verify(annotationRepository).save(any());
+    }
+
+    @Test
+    void createAnnotation_noConflict_whenAnnotationIsAbove() {
+        // x ranges overlap, y ranges don't — existing is ABOVE the new annotation
+        // existing: x=0.0, w=0.5, y=0.0, h=0.1 (ey2=0.1)
+        // dto: x=0.1, w=0.3 (dx2=0.4), y=0.2, h=0.3 (dy2=0.5)
+        // A: 0.0 < 0.4 → TRUE, B: 0.5 > 0.1 → TRUE, C: 0.0 < 0.5 → TRUE
+        // D: ey2 > dto.getY() → 0.1 > 0.2 → FALSE → no overlap (fourth && fails)
+        UUID docId = UUID.randomUUID();
+        DocumentAnnotation existing = DocumentAnnotation.builder()
+                .id(UUID.randomUUID()).documentId(docId).pageNumber(1)
+                .x(0.0).y(0.0).width(0.5).height(0.1).color("#ff0000").build();
+        CreateAnnotationDTO dto = new CreateAnnotationDTO(1, 0.1, 0.2, 0.3, 0.3, "#0000ff");
+        when(annotationRepository.findByDocumentIdAndPageNumber(docId, 1)).thenReturn(List.of(existing));
+        when(annotationRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        annotationService.createAnnotation(docId, dto, UUID.randomUUID(), null);
+
+        verify(annotationRepository).save(any());
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/service/CommentServiceTest.java

@@ -20,6 +20,9 @@ import java.util.UUID;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyList;
+import static org.mockito.ArgumentMatchers.anySet;
+import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
@@ -30,6 +33,8 @@ import static org.springframework.http.HttpStatus.NOT_FOUND;
 class CommentServiceTest {
 
     @Mock CommentRepository commentRepository;
+    @Mock UserService userService;
+    @Mock NotificationService notificationService;
     @InjectMocks CommentService commentService;
 
     // ─── postComment ──────────────────────────────────────────────────────────
@@ -43,7 +48,7 @@ class CommentServiceTest {
                 .id(UUID.randomUUID()).documentId(docId).authorName("Hans Müller").content("Test").build();
         when(commentRepository.save(any())).thenReturn(saved);
 
-        DocumentComment result = commentService.postComment(docId, null, "Test", author);
+        DocumentComment result = commentService.postComment(docId, null, "Test", List.of(), author);
 
         assertThat(result.getAuthorName()).isEqualTo("Hans Müller");
     }
@@ -56,11 +61,28 @@ class CommentServiceTest {
                 .id(UUID.randomUUID()).documentId(docId).authorName("hans42").content("Test").build();
         when(commentRepository.save(any())).thenReturn(saved);
 
-        DocumentComment result = commentService.postComment(docId, null, "Test", author);
+        DocumentComment result = commentService.postComment(docId, null, "Test", List.of(), author);
 
         assertThat(result.getAuthorName()).isEqualTo("hans42");
     }
 
+    @Test
+    void postComment_triggersNotifyMentions_whenMentionedUserIdsProvided() {
+        UUID docId = UUID.randomUUID();
+        UUID mentionedId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("hans").firstName("Hans").lastName("M").build();
+        AppUser mentioned = AppUser.builder().id(mentionedId).username("anna").firstName("Anna").lastName("S").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).authorName("Hans M").content("Hey @Anna S").build();
+
+        when(userService.findAllById(List.of(mentionedId))).thenReturn(List.of(mentioned));
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.postComment(docId, null, "Hey @Anna S", List.of(mentionedId), author);
+
+        verify(notificationService).notifyMentions(eq(List.of(mentionedId)), eq(saved));
+    }
+
     // ─── replyToComment ───────────────────────────────────────────────────────
 
     @Test
@@ -70,7 +92,7 @@ class CommentServiceTest {
         AppUser author = AppUser.builder().id(UUID.randomUUID()).username("anna").build();
         when(commentRepository.findById(commentId)).thenReturn(Optional.empty());
 
-        assertThatThrownBy(() -> commentService.replyToComment(docId, commentId, "Reply", author))
+        assertThatThrownBy(() -> commentService.replyToComment(docId, commentId, "Reply", List.of(), author))
                 .isInstanceOf(DomainException.class)
                 .satisfies(e -> assertThat(((DomainException) e).getStatus()).isEqualTo(NOT_FOUND));
 
@@ -91,11 +113,12 @@ class CommentServiceTest {
 
         when(commentRepository.findById(replyId)).thenReturn(Optional.of(existingReply));
         when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of(existingReply));
         DocumentComment saved = DocumentComment.builder()
                 .id(UUID.randomUUID()).documentId(docId).parentId(rootId).content("Reply2").authorName("anna").build();
         when(commentRepository.save(any())).thenReturn(saved);
 
-        DocumentComment result = commentService.replyToComment(docId, replyId, "Reply2", author);
+        DocumentComment result = commentService.replyToComment(docId, replyId, "Reply2", List.of(), author);
 
         assertThat(result.getParentId()).isEqualTo(rootId);
     }
@@ -110,15 +133,59 @@ class CommentServiceTest {
                 .id(rootId).documentId(docId).parentId(null).content("Root").authorName("Hans").build();
 
         when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of());
         DocumentComment saved = DocumentComment.builder()
                 .id(UUID.randomUUID()).documentId(docId).parentId(rootId).content("Reply").authorName("anna").build();
         when(commentRepository.save(any())).thenReturn(saved);
 
-        DocumentComment result = commentService.replyToComment(docId, rootId, "Reply", author);
+        DocumentComment result = commentService.replyToComment(docId, rootId, "Reply", List.of(), author);
 
         assertThat(result.getParentId()).isEqualTo(rootId);
     }
 
+    @Test
+    void replyToComment_triggersNotifyReply_afterSave() {
+        UUID docId = UUID.randomUUID();
+        UUID rootId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("anna").build();
+
+        DocumentComment root = DocumentComment.builder()
+                .id(rootId).documentId(docId).parentId(null).content("Root").authorName("Hans").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId).content("Reply").authorName("anna").build();
+
+        when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of());
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.replyToComment(docId, rootId, "Reply", List.of(), author);
+
+        verify(notificationService).notifyReply(eq(saved), anySet());
+    }
+
+    @Test
+    void replyToComment_triggersNotifyMentions_whenMentionedUserIdsProvided() {
+        UUID docId = UUID.randomUUID();
+        UUID rootId = UUID.randomUUID();
+        UUID mentionedId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("anna").build();
+        AppUser mentioned = AppUser.builder().id(mentionedId).username("bob").firstName("Bob").lastName("J").build();
+
+        DocumentComment root = DocumentComment.builder()
+                .id(rootId).documentId(docId).parentId(null).content("Root").authorName("Hans").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId).content("Hey @Bob J").authorName("anna").build();
+
+        when(userService.findAllById(List.of(mentionedId))).thenReturn(List.of(mentioned));
+        when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of());
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.replyToComment(docId, rootId, "Hey @Bob J", List.of(mentionedId), author);
+
+        verify(notificationService).notifyMentions(eq(List.of(mentionedId)), eq(saved));
+    }
+
     // ─── editComment ──────────────────────────────────────────────────────────
 
     @Test
@@ -233,6 +300,181 @@ class CommentServiceTest {
         assertThat(result.get(0).getReplies()).containsExactly(reply);
     }
 
+    // ─── replyToComment — reply with null authorId in thread ─────────────────
+
+    @Test
+    void replyToComment_handlesNullAuthorId_inExistingReply() {
+        UUID docId = UUID.randomUUID();
+        UUID rootId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("anna").firstName("Anna").lastName("S").build();
+
+        DocumentComment root = DocumentComment.builder()
+                .id(rootId).documentId(docId).parentId(null).authorId(UUID.randomUUID()).content("Root").authorName("Root").build();
+        // Existing reply with null authorId
+        DocumentComment nullAuthorReply = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId).authorId(null).content("Anon reply").authorName("anon").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId).content("New reply").authorName("Anna S").build();
+
+        when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of(nullAuthorReply));
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.replyToComment(docId, rootId, "New reply", List.of(), author);
+
+        // Must not throw NullPointerException; only non-null authorIds collected
+        verify(notificationService).notifyReply(eq(saved), anySet());
+    }
+
+    // ─── resolveAuthorName edge cases ─────────────────────────────────────────
+
+    @Test
+    void postComment_fallsBackToUsername_whenFirstNameBlankAndLastNameNull() {
+        UUID docId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("user42")
+                .firstName("   ").lastName(null).build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).authorName("user42").content("Hi").build();
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        DocumentComment result = commentService.postComment(docId, null, "Hi", List.of(), author);
+
+        assertThat(result.getAuthorName()).isEqualTo("user42");
+    }
+
+    @Test
+    void postComment_fallsBackToUsername_whenFirstNameNullAndLastNameBlank() {
+        UUID docId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("user42")
+                .firstName(null).lastName("  ").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).authorName("user42").content("Hi").build();
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        DocumentComment result = commentService.postComment(docId, null, "Hi", List.of(), author);
+
+        assertThat(result.getAuthorName()).isEqualTo("user42");
+    }
+
+    @Test
+    void postComment_includesOnlyFirstName_whenLastNameIsNull() {
+        UUID docId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("user42")
+                .firstName("Hans").lastName(null).build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).authorName("Hans").content("Hi").build();
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.postComment(docId, null, "Hi", List.of(), author);
+
+        // first != null && !blank → true; last == null → entire condition false → returns stripped first
+        verify(commentRepository).save(any());
+    }
+
+    @Test
+    void postComment_includesOnlyLastName_whenFirstNameIsNull() {
+        UUID docId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("user42")
+                .firstName(null).lastName("Müller").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).authorName("Müller").content("Hi").build();
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.postComment(docId, null, "Hi", List.of(), author);
+
+        // No exception — name resolution with null first name strips cleanly
+        verify(commentRepository).save(any());
+    }
+
+    // ─── saveMentions — null/empty guard ─────────────────────────────────────
+
+    @Test
+    void postComment_doesNotCallUserService_whenMentionedUserIdsIsNull() {
+        UUID docId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("hans")
+                .firstName("Hans").lastName("M").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).authorName("Hans M").content("Hi").build();
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.postComment(docId, null, "Hi", null, author);
+
+        verify(userService, never()).findAllById(anyList());
+    }
+
+    // ─── collectParticipantIds — non-null authorId in reply ──────────────────
+
+    @Test
+    void replyToComment_includesNonNullAuthorId_fromExistingReply() {
+        UUID docId = UUID.randomUUID();
+        UUID rootId = UUID.randomUUID();
+        UUID existingReplyAuthorId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("anna").build();
+
+        DocumentComment root = DocumentComment.builder()
+                .id(rootId).documentId(docId).parentId(null).authorId(UUID.randomUUID())
+                .content("Root").authorName("root").build();
+        // Existing reply WITH a non-null authorId — covers true branch of reply.getAuthorId() != null
+        DocumentComment existingReply = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId)
+                .authorId(existingReplyAuthorId).content("Existing").authorName("someone").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId)
+                .content("New reply").authorName("anna").build();
+
+        when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of(existingReply));
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        commentService.replyToComment(docId, rootId, "New reply", List.of(), author);
+
+        verify(notificationService).notifyReply(eq(saved), anySet());
+    }
+
+    // ─── collectParticipantIds — null authorId ────────────────────────────────
+
+    @Test
+    void replyToComment_excludesNullAuthorIds_fromParticipantSet() {
+        UUID docId = UUID.randomUUID();
+        UUID rootId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("anna").build();
+
+        // Root with null authorId
+        DocumentComment root = DocumentComment.builder()
+                .id(rootId).documentId(docId).parentId(null).authorId(null).content("Root").authorName("anon").build();
+        DocumentComment saved = DocumentComment.builder()
+                .id(UUID.randomUUID()).documentId(docId).parentId(rootId).content("Reply").authorName("anna").build();
+
+        when(commentRepository.findById(rootId)).thenReturn(Optional.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of());
+        when(commentRepository.save(any())).thenReturn(saved);
+
+        // Must not throw NullPointerException
+        commentService.replyToComment(docId, rootId, "Reply", List.of(), author);
+
+        verify(notificationService).notifyReply(eq(saved), anySet());
+    }
+
+    // ─── getCommentsForAnnotation ─────────────────────────────────────────────
+
+    @Test
+    void getCommentsForAnnotation_returnsRootsForAnnotation() {
+        UUID annotationId = UUID.randomUUID();
+        UUID rootId = UUID.randomUUID();
+
+        DocumentComment root = DocumentComment.builder()
+                .id(rootId).annotationId(annotationId).authorName("Hans").content("Root").build();
+
+        when(commentRepository.findByAnnotationIdAndParentIdIsNull(annotationId))
+                .thenReturn(List.of(root));
+        when(commentRepository.findByParentId(rootId)).thenReturn(List.of());
+
+        List<DocumentComment> result = commentService.getCommentsForAnnotation(annotationId);
+
+        assertThat(result).hasSize(1);
+        assertThat(result.get(0).getAnnotationId()).isEqualTo(annotationId);
+    }
+
     // ─── helpers ──────────────────────────────────────────────────────────────
 
     private AppUser buildAdmin() {
@@ -246,4 +488,40 @@ class CommentServiceTest {
                         .build()))
                 .build();
     }
+
+    // ─── Block-level comments ────────────────────────────────────────────────
+
+    @Test
+    void getCommentsForBlock_returnsRootCommentsFilteredByBlockId() {
+        UUID blockId = UUID.randomUUID();
+        DocumentComment root = DocumentComment.builder()
+                .id(UUID.randomUUID()).blockId(blockId).content("Nice work").authorName("Felix")
+                .createdAt(LocalDateTime.now()).updatedAt(LocalDateTime.now()).build();
+        when(commentRepository.findByBlockIdAndParentIdIsNull(blockId)).thenReturn(List.of(root));
+        when(commentRepository.findByParentId(root.getId())).thenReturn(List.of());
+
+        List<DocumentComment> result = commentService.getCommentsForBlock(blockId);
+
+        assertThat(result).hasSize(1);
+        assertThat(result.getFirst().getContent()).isEqualTo("Nice work");
+    }
+
+    @Test
+    void postBlockComment_setsBlockIdOnComment() {
+        UUID documentId = UUID.randomUUID();
+        UUID blockId = UUID.randomUUID();
+        AppUser author = AppUser.builder().id(UUID.randomUUID()).username("felix").firstName("Felix").lastName("Brandt").build();
+        when(commentRepository.save(any())).thenAnswer(inv -> {
+            DocumentComment c = inv.getArgument(0);
+            c.setId(UUID.randomUUID());
+            return c;
+        });
+
+        DocumentComment result = commentService.postBlockComment(
+                documentId, blockId, "Looks like Breslau", List.of(), author);
+
+        assertThat(result.getBlockId()).isEqualTo(blockId);
+        assertThat(result.getDocumentId()).isEqualTo(documentId);
+        assertThat(result.getContent()).isEqualTo("Looks like Breslau");
+    }
 }

backend/src/test/java/org/raddatz/familienarchiv/service/CustomUserDetailsServiceTest.java

@@ -0,0 +1,120 @@
+package org.raddatz.familienarchiv.service;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.UserGroup;
+import org.raddatz.familienarchiv.repository.AppUserRepository;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.security.core.userdetails.UserDetails;
+import org.springframework.security.core.userdetails.UsernameNotFoundException;
+
+import java.util.Optional;
+import java.util.Set;
+import java.util.UUID;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class CustomUserDetailsServiceTest {
+
+    @Mock AppUserRepository userRepository;
+    @InjectMocks CustomUserDetailsService service;
+
+    // ─── loadUserByUsername — not found ──────────────────────────────────────
+
+    @Test
+    void loadUserByUsername_throwsUsernameNotFoundException_whenUserNotFound() {
+        when(userRepository.findByUsername("ghost")).thenReturn(Optional.empty());
+
+        assertThatThrownBy(() -> service.loadUserByUsername("ghost"))
+                .isInstanceOf(UsernameNotFoundException.class)
+                .hasMessageContaining("ghost");
+    }
+
+    // ─── loadUserByUsername — happy path ─────────────────────────────────────
+
+    @Test
+    void loadUserByUsername_returnsUserDetails_withMappedAuthorities() {
+        UserGroup group = UserGroup.builder().id(UUID.randomUUID()).name("Admins")
+                .permissions(Set.of("READ_ALL", "WRITE_ALL")).build();
+        AppUser user = AppUser.builder().id(UUID.randomUUID())
+                .username("admin").password("hashed").enabled(true)
+                .groups(Set.of(group)).build();
+        when(userRepository.findByUsername("admin")).thenReturn(Optional.of(user));
+
+        UserDetails details = service.loadUserByUsername("admin");
+
+        assertThat(details.getUsername()).isEqualTo("admin");
+        assertThat(details.getAuthorities()).extracting("authority")
+                .contains("READ_ALL", "WRITE_ALL");
+    }
+
+    @Test
+    void loadUserByUsername_returnsEmptyAuthorities_whenUserHasNoGroups() {
+        AppUser user = AppUser.builder().id(UUID.randomUUID())
+                .username("viewer").password("hashed").enabled(true)
+                .groups(Set.of()).build();
+        when(userRepository.findByUsername("viewer")).thenReturn(Optional.of(user));
+
+        UserDetails details = service.loadUserByUsername("viewer");
+
+        assertThat(details.getAuthorities()).isEmpty();
+    }
+
+    // ─── loadUserByUsername — unknown permission ──────────────────────────────
+
+    @Test
+    void loadUserByUsername_grantsUnknownPermission_butLogsWarning() {
+        // Unknown permissions should still be granted (logged as warning, not silently dropped)
+        UserGroup group = UserGroup.builder().id(UUID.randomUUID()).name("CustomGroup")
+                .permissions(Set.of("UNKNOWN_CUSTOM_PERM")).build();
+        AppUser user = AppUser.builder().id(UUID.randomUUID())
+                .username("custom").password("hashed").enabled(true)
+                .groups(Set.of(group)).build();
+        when(userRepository.findByUsername("custom")).thenReturn(Optional.of(user));
+
+        UserDetails details = service.loadUserByUsername("custom");
+
+        assertThat(details.getAuthorities()).extracting("authority")
+                .contains("UNKNOWN_CUSTOM_PERM");
+    }
+
+    // ─── loadUserByUsername — disabled user ───────────────────────────────────
+
+    @Test
+    void loadUserByUsername_returnsDisabledUser_whenUserIsDisabled() {
+        AppUser user = AppUser.builder().id(UUID.randomUUID())
+                .username("disabled").password("hashed").enabled(false)
+                .groups(Set.of()).build();
+        when(userRepository.findByUsername("disabled")).thenReturn(Optional.of(user));
+
+        UserDetails details = service.loadUserByUsername("disabled");
+
+        assertThat(details.isEnabled()).isFalse();
+    }
+
+    // ─── loadUserByUsername — multi-group permission merge ────────────────────
+
+    @Test
+    void loadUserByUsername_mergesPermissionsFromMultipleGroups() {
+        UserGroup g1 = UserGroup.builder().id(UUID.randomUUID()).name("Readers")
+                .permissions(Set.of("READ_ALL")).build();
+        UserGroup g2 = UserGroup.builder().id(UUID.randomUUID()).name("Writers")
+                .permissions(Set.of("WRITE_ALL")).build();
+        AppUser user = AppUser.builder().id(UUID.randomUUID())
+                .username("multi").password("hashed").enabled(true)
+                .groups(Set.of(g1, g2)).build();
+        when(userRepository.findByUsername("multi")).thenReturn(Optional.of(user));
+
+        UserDetails details = service.loadUserByUsername("multi");
+
+        assertThat(details.getAuthorities()).extracting("authority")
+                .containsExactlyInAnyOrder("READ_ALL", "WRITE_ALL");
+    }
+}

backend/src/test/java/org/raddatz/familienarchiv/service/DocumentVersionServiceTest.java

@@ -374,6 +374,366 @@ class DocumentVersionServiceTest {
         assertThat(count).isEqualTo(2);
     }
 
+    // ─── recordVersion — no auth / user not found ─────────────────────────────
+
+    @Test
+    void recordVersion_usesUnknown_whenSecurityContextHasNoAuthentication() {
+        // No call to authenticateAs — context is cleared
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(any())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(minimalDocument());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getEditorName()).isEqualTo("Unknown");
+        assertThat(captor.getValue().getEditorId()).isNull();
+    }
+
+    @Test
+    void recordVersion_usesUnknown_whenAuthenticationIsNotAuthenticated() {
+        // Auth present but isAuthenticated() = false — use TestingAuthenticationToken
+        org.springframework.security.authentication.TestingAuthenticationToken notAuth =
+                new org.springframework.security.authentication.TestingAuthenticationToken("user", null);
+        notAuth.setAuthenticated(false);
+        SecurityContextHolder.getContext().setAuthentication(notAuth);
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(any())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(minimalDocument());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getEditorName()).isEqualTo("Unknown");
+    }
+
+    @Test
+    void recordVersion_usesUnknown_whenUserServiceThrows() {
+        authenticateAs("missinguser");
+        when(userService.findByUsername("missinguser")).thenThrow(new RuntimeException("not found"));
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(any())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(minimalDocument());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getEditorName()).isEqualTo("Unknown");
+    }
+
+    // ─── recordVersion — buildEditorName edge cases ───────────────────────────
+
+    @Test
+    void recordVersion_usesUsername_whenFirstNameIsNotBlankButLastNameIsNull() {
+        authenticateAs("user42");
+        when(userService.findByUsername("user42")).thenReturn(
+                AppUser.builder().id(UUID.randomUUID()).username("user42")
+                        .firstName("Hans").lastName(null).build());
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(any())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(minimalDocument());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getEditorName()).isEqualTo("user42");
+    }
+
+    @Test
+    void recordVersion_usesUsername_whenFirstNameIsBlankButLastNameIsPresent() {
+        authenticateAs("user42");
+        when(userService.findByUsername("user42")).thenReturn(
+                AppUser.builder().id(UUID.randomUUID()).username("user42")
+                        .firstName("  ").lastName("Müller").build());
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(any())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(minimalDocument());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getEditorName()).isEqualTo("user42");
+    }
+
+    @Test
+    void recordVersion_usesUsername_whenLastNameIsBlankButFirstNameIsPresent() {
+        authenticateAs("user42");
+        when(userService.findByUsername("user42")).thenReturn(
+                AppUser.builder().id(UUID.randomUUID()).username("user42")
+                        .firstName("Hans").lastName("  ").build());
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(any())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(minimalDocument());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getEditorName()).isEqualTo("user42");
+    }
+
+    // ─── recordVersion — computeChangedFields with corrupt snapshot ──────────
+
+    @Test
+    void recordVersion_returnsEmptyChangedFields_whenPreviousSnapshotIsInvalidJson() {
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        UUID docId = UUID.randomUUID();
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot("INVALID JSON")
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.recordVersion(Document.builder().id(docId).title("T").build());
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).isEqualTo("[]");
+    }
+
+    // ─── recordVersion — checkSender/checkReceivers/checkTags with no previous ─
+
+    @Test
+    void recordVersion_tracksSenderAdded_whenPreviousHadNoSender() throws Exception {
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        ObjectMapper mapper = new ObjectMapper();
+        UUID docId = UUID.randomUUID();
+        Document oldDoc = Document.builder().id(docId).title("T").build(); // no sender
+        String oldSnapshot = mapper.writeValueAsString(oldDoc);
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Person newSender = Person.builder().id(UUID.randomUUID()).firstName("A").lastName("B").build();
+        Document updated = Document.builder().id(docId).title("T").sender(newSender).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("sender");
+    }
+
+    @Test
+    void recordVersion_tracksReceiversAdded_whenPreviousHadNone() throws Exception {
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        ObjectMapper mapper = new ObjectMapper();
+        UUID docId = UUID.randomUUID();
+        Document oldDoc = Document.builder().id(docId).title("T").build(); // no receivers
+        String oldSnapshot = mapper.writeValueAsString(oldDoc);
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Person r = Person.builder().id(UUID.randomUUID()).firstName("C").lastName("D").build();
+        Document updated = Document.builder().id(docId).title("T").receivers(Set.of(r)).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("receivers");
+    }
+
+    @Test
+    void recordVersion_tracksTagsAdded_whenPreviousHadNone() throws Exception {
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        ObjectMapper mapper = new ObjectMapper();
+        UUID docId = UUID.randomUUID();
+        Document oldDoc = Document.builder().id(docId).title("T").build(); // no tags
+        String oldSnapshot = mapper.writeValueAsString(oldDoc);
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Tag tag = Tag.builder().id(UUID.randomUUID()).name("Familie").build();
+        Document updated = Document.builder().id(docId).title("T").tags(Set.of(tag)).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("tags");
+    }
+
+    // ─── checkSender — sender map with null id ───────────────────────────────
+
+    @Test
+    void recordVersion_senderChangedToPresent_whenPreviousSenderHasNullId() throws Exception {
+        // Covers: prevSender instanceof Map = true, but id == null → prevId = null
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        UUID docId = UUID.randomUUID();
+        // Manually craft a JSON where sender object exists but id is null
+        String oldSnapshot = "{\"id\":\"" + docId + "\",\"title\":\"T\","
+                + "\"sender\":{\"id\":null,\"firstName\":\"A\",\"lastName\":\"B\"},"
+                + "\"receivers\":[],\"tags\":[]}";
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Person newSender = Person.builder().id(UUID.randomUUID()).firstName("B").lastName("C").build();
+        Document updated = Document.builder().id(docId).title("T").sender(newSender).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("sender");
+    }
+
+    // ─── checkSender — sender unchanged → not in changedFields ───────────────
+
+    @Test
+    void recordVersion_doesNotTrackSender_whenSenderUnchanged() throws Exception {
+        // Covers: !Objects.equals(currentId, prevId) = false → don't add "sender"
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        ObjectMapper mapper = new ObjectMapper();
+        UUID docId = UUID.randomUUID();
+        UUID senderId = UUID.randomUUID();
+        Person sender = Person.builder().id(senderId).firstName("A").lastName("B").build();
+        Document oldDoc = Document.builder().id(docId).title("T").sender(sender).build();
+        String oldSnapshot = mapper.writeValueAsString(oldDoc);
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        // Same sender — should NOT be in changedFields
+        Document updated = Document.builder().id(docId).title("T").sender(sender).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).doesNotContain("sender");
+    }
+
+    // ─── computeChangedFields — documentDate ternary true branch ─────────────
+
+    @Test
+    void recordVersion_tracksDocumentDate_whenCurrentDocHasNonNullDate() throws Exception {
+        // current.getDocumentDate() != null = true → ternary true branch in computeChangedFields
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        ObjectMapper mapper = new ObjectMapper();
+        UUID docId = UUID.randomUUID();
+        Document oldDoc = Document.builder().id(docId).title("T").build(); // no date in previous
+        String oldSnapshot = mapper.writeValueAsString(oldDoc);
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        // Current doc has a non-null documentDate → ternary evaluates its true branch
+        Document updated = Document.builder().id(docId).title("T")
+                .documentDate(LocalDate.of(1965, 3, 12)).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("documentDate");
+    }
+
+    // ─── checkReceivers / checkTags — when previous snapshot has null values ───
+
+    @Test
+    void recordVersion_tracksReceivers_whenPreviousSnapshotHasNullReceivers() throws Exception {
+        // prevReceivers NOT instanceof List<?> → prevIds = Set.of() → if currentIds differ → added
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        UUID docId = UUID.randomUUID();
+        // Craft snapshot where "receivers" is JSON null → deserialized as null, NOT a List
+        String oldSnapshot = "{\"id\":\"" + docId + "\",\"title\":\"T\",\"receivers\":null,\"tags\":[]}";
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Person r = Person.builder().id(UUID.randomUUID()).firstName("A").lastName("B").build();
+        Document updated = Document.builder().id(docId).title("T").receivers(Set.of(r)).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("receivers");
+    }
+
+    @Test
+    void recordVersion_tracksTags_whenPreviousSnapshotHasNullTags() throws Exception {
+        // prevTags NOT instanceof List<?> → prevNames = Set.of() → if currentNames differ → added
+        authenticateAs("user1");
+        when(userService.findByUsername("user1")).thenReturn(stubUser("user1"));
+
+        UUID docId = UUID.randomUUID();
+        // Craft snapshot where "tags" is JSON null → deserialized as null, NOT a List
+        String oldSnapshot = "{\"id\":\"" + docId + "\",\"title\":\"T\",\"receivers\":[],\"tags\":null}";
+
+        DocumentVersion previous = DocumentVersion.builder()
+                .id(UUID.randomUUID()).documentId(docId).snapshot(oldSnapshot)
+                .changedFields("[]").savedAt(LocalDateTime.now().minusMinutes(5))
+                .editorName("user1").build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(docId)).thenReturn(List.of(previous));
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        Tag tag = Tag.builder().id(UUID.randomUUID()).name("Familie").build();
+        Document updated = Document.builder().id(docId).title("T").tags(Set.of(tag)).build();
+        versionService.recordVersion(updated);
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getChangedFields()).contains("tags");
+    }
+
+    // ─── backfill — uses LocalDateTime.now() when createdAt is null ──────────
+
+    @Test
+    void backfill_usesNow_whenDocumentCreatedAtIsNull() {
+        Document doc = Document.builder().id(UUID.randomUUID()).title("T").createdAt(null).build();
+        when(versionRepository.findByDocumentIdOrderBySavedAtAsc(doc.getId())).thenReturn(List.of());
+        when(versionRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        versionService.backfillMissingVersions(List.of(doc));
+
+        ArgumentCaptor<DocumentVersion> captor = ArgumentCaptor.forClass(DocumentVersion.class);
+        verify(versionRepository).save(captor.capture());
+        assertThat(captor.getValue().getSavedAt()).isNotNull();
+    }
+
     // ─── helpers ──────────────────────────────────────────────────────────────
 
     private void authenticateAs(String username) {

backend/src/test/java/org/raddatz/familienarchiv/service/FileServiceTest.java

@@ -0,0 +1,200 @@
+package org.raddatz.familienarchiv.service;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.springframework.mock.web.MockMultipartFile;
+import software.amazon.awssdk.core.ResponseInputStream;
+import software.amazon.awssdk.core.sync.RequestBody;
+import software.amazon.awssdk.http.AbortableInputStream;
+import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.model.GetObjectRequest;
+import software.amazon.awssdk.services.s3.model.GetObjectResponse;
+import software.amazon.awssdk.services.s3.model.NoSuchKeyException;
+import software.amazon.awssdk.services.s3.model.PutObjectRequest;
+import software.amazon.awssdk.services.s3.model.S3Exception;
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.*;
+
+class FileServiceTest {
+
+    private S3Client s3Client;
+    private FileService fileService;
+
+    @BeforeEach
+    void setUp() {
+        s3Client = mock(S3Client.class);
+        fileService = new FileService(s3Client, "test-bucket");
+    }
+
+    @Test
+    void uploadFile_returnsS3Key() throws IOException {
+        MockMultipartFile file = new MockMultipartFile(
+                "file", "test.pdf", "application/pdf", new byte[]{1, 2, 3});
+
+        FileService.UploadResult result = fileService.uploadFile(file, "test.pdf");
+
+        assertThat(result.s3Key()).startsWith("documents/");
+        assertThat(result.s3Key()).endsWith("_test.pdf");
+        verify(s3Client).putObject(any(PutObjectRequest.class), any(RequestBody.class));
+    }
+
+    @Test
+    void uploadFile_returnsCorrectSha256FileHash() throws IOException, NoSuchAlgorithmException {
+        byte[] content = "hello pdf content".getBytes();
+        MockMultipartFile file = new MockMultipartFile(
+                "file", "doc.pdf", "application/pdf", content);
+
+        FileService.UploadResult result = fileService.uploadFile(file, "doc.pdf");
+
+        // Compute expected hash independently
+        MessageDigest digest = MessageDigest.getInstance("SHA-256");
+        byte[] hashBytes = digest.digest(content);
+        StringBuilder expected = new StringBuilder();
+        for (byte b : hashBytes) {
+            expected.append(String.format("%02x", b));
+        }
+
+        assertThat(result.fileHash()).isEqualTo(expected.toString());
+    }
+
+    @Test
+    void uploadFile_differentContents_produceDifferentHashes() throws IOException {
+        MockMultipartFile file1 = new MockMultipartFile(
+                "f", "a.pdf", "application/pdf", new byte[]{1, 2, 3});
+        MockMultipartFile file2 = new MockMultipartFile(
+                "f", "b.pdf", "application/pdf", new byte[]{4, 5, 6});
+
+        FileService.UploadResult r1 = fileService.uploadFile(file1, "a.pdf");
+        FileService.UploadResult r2 = fileService.uploadFile(file2, "b.pdf");
+
+        assertThat(r1.fileHash()).isNotEqualTo(r2.fileHash());
+    }
+
+    @Test
+    void uploadFile_sameContents_produceSameHash() throws IOException {
+        byte[] content = new byte[]{10, 20, 30};
+        MockMultipartFile file1 = new MockMultipartFile("f", "x.pdf", "application/pdf", content);
+        MockMultipartFile file2 = new MockMultipartFile("f", "y.pdf", "application/pdf", content);
+
+        FileService.UploadResult r1 = fileService.uploadFile(file1, "x.pdf");
+        FileService.UploadResult r2 = fileService.uploadFile(file2, "y.pdf");
+
+        assertThat(r1.fileHash()).isEqualTo(r2.fileHash());
+    }
+
+    @Test
+    void uploadFile_throwsIOException_whenS3Throws() {
+        MockMultipartFile file = new MockMultipartFile("f", "fail.pdf", "application/pdf", new byte[]{1});
+        S3Exception s3ex = (S3Exception) S3Exception.builder().message("bucket error").statusCode(500).build();
+        when(s3Client.putObject(any(PutObjectRequest.class), any(RequestBody.class))).thenThrow(s3ex);
+
+        assertThatThrownBy(() -> fileService.uploadFile(file, "fail.pdf"))
+                .isInstanceOf(IOException.class)
+                .hasMessageContaining("Failed to upload");
+    }
+
+    // ─── downloadFile ─────────────────────────────────────────────────────────
+
+    @Test
+    void downloadFile_returnsResourceWithContentType() {
+        byte[] content = "pdf content".getBytes();
+        GetObjectResponse response = GetObjectResponse.builder().contentType("application/pdf").build();
+        ResponseInputStream<GetObjectResponse> stream = new ResponseInputStream<>(
+                response, AbortableInputStream.create(new ByteArrayInputStream(content)));
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenReturn(stream);
+
+        FileService.S3FileDownload result = fileService.downloadFile("documents/test.pdf");
+
+        assertThat(result.contentType()).isEqualTo("application/pdf");
+        assertThat(result.resource()).isNotNull();
+    }
+
+    @Test
+    void downloadFile_fallsBackToOctetStream_whenContentTypeIsBlank() {
+        byte[] content = "data".getBytes();
+        GetObjectResponse response = GetObjectResponse.builder().contentType("   ").build();
+        ResponseInputStream<GetObjectResponse> stream = new ResponseInputStream<>(
+                response, AbortableInputStream.create(new ByteArrayInputStream(content)));
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenReturn(stream);
+
+        FileService.S3FileDownload result = fileService.downloadFile("documents/file");
+
+        assertThat(result.contentType()).isEqualTo("application/octet-stream");
+    }
+
+    @Test
+    void downloadFile_fallsBackToOctetStream_whenContentTypeIsNull() {
+        byte[] content = "data".getBytes();
+        GetObjectResponse response = GetObjectResponse.builder().build(); // no contentType
+        ResponseInputStream<GetObjectResponse> stream = new ResponseInputStream<>(
+                response, AbortableInputStream.create(new ByteArrayInputStream(content)));
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenReturn(stream);
+
+        FileService.S3FileDownload result = fileService.downloadFile("documents/file");
+
+        assertThat(result.contentType()).isEqualTo("application/octet-stream");
+    }
+
+    @Test
+    void downloadFile_throwsStorageFileNotFoundException_whenNoSuchKey() {
+        NoSuchKeyException ex = NoSuchKeyException.builder().message("not found").statusCode(404).build();
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenThrow(ex);
+
+        assertThatThrownBy(() -> fileService.downloadFile("missing/key.pdf"))
+                .isInstanceOf(FileService.StorageFileNotFoundException.class)
+                .hasMessageContaining("missing/key.pdf");
+    }
+
+    @Test
+    void downloadFile_throwsRuntimeException_whenS3Exception() {
+        S3Exception ex = (S3Exception) S3Exception.builder().message("storage error").statusCode(503).build();
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenThrow(ex);
+
+        assertThatThrownBy(() -> fileService.downloadFile("documents/file.pdf"))
+                .isInstanceOf(RuntimeException.class)
+                .hasMessageContaining("Storage Error");
+    }
+
+    // ─── downloadFileBytes ────────────────────────────────────────────────────
+
+    @Test
+    void downloadFileBytes_returnsRawBytes() throws IOException {
+        byte[] content = "raw bytes".getBytes();
+        GetObjectResponse response = GetObjectResponse.builder().build();
+        ResponseInputStream<GetObjectResponse> stream = new ResponseInputStream<>(
+                response, AbortableInputStream.create(new ByteArrayInputStream(content)));
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenReturn(stream);
+
+        byte[] result = fileService.downloadFileBytes("documents/file.pdf");
+
+        assertThat(result).isEqualTo(content);
+    }
+
+    @Test
+    void downloadFileBytes_throwsStorageFileNotFoundException_whenNoSuchKey() {
+        NoSuchKeyException ex = NoSuchKeyException.builder().message("not found").statusCode(404).build();
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenThrow(ex);
+
+        assertThatThrownBy(() -> fileService.downloadFileBytes("missing/key.pdf"))
+                .isInstanceOf(FileService.StorageFileNotFoundException.class);
+    }
+
+    @Test
+    void downloadFileBytes_throwsIOException_whenS3Exception() {
+        S3Exception ex = (S3Exception) S3Exception.builder().message("storage error").statusCode(503).build();
+        when(s3Client.getObject(any(GetObjectRequest.class))).thenThrow(ex);
+
+        assertThatThrownBy(() -> fileService.downloadFileBytes("documents/file.pdf"))
+                .isInstanceOf(IOException.class)
+                .hasMessageContaining("Failed to download");
+    }
+}