fix(pdf): prevent scroll-sync effect from hijacking page navigation

The scroll-sync $effect was re-triggering on every dependency change
(including currentPage), forcing the PDF back to the annotation's page
when the user clicked next/prev. Fix: track prevActiveAnnotationId
and only scroll when the active annotation actually changes.

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
@@ -190,6 +194,7 @@ jobs:
           E2E_BASE_URL: http://localhost:3000
           E2E_USERNAME: admin
           E2E_PASSWORD: admin123
+          E2E_BACKEND_URL: http://localhost:8080
 
       - name: Upload E2E results
         if: always()

COLLABORATING.md

@@ -43,6 +43,42 @@ Repeat for each new behavior.
 - The Refactor step must not change behavior — if a test breaks, the refactor introduced a bug.
 - If a bug is reported with no test, write the failing test first, then fix it.
 
+## User Journeys & E2E Acceptance Criteria
+
+Every `feature` issue must include two sections before any implementation begins:
+
+### 1. User Journey
+
+A plain-prose description of the steps a user takes to get value from the feature. Written from the user's perspective, not the implementation's:
+
+> User opens a document, clicks "History", sees a chronological list of changes with editor name and timestamp. Clicking a row expands the old vs. new values.
+
+This makes the scope concrete and prevents scope creep — anything not in the journey is out of scope for the issue.
+
+### 2. E2E Scenarios
+
+One or more acceptance criteria written as Playwright-ready scenarios. These become the outermost Red test in the TDD cycle — no feature is considered done until all its E2E scenarios pass:
+
+```
+Scenario: View edit history of a document
+  Given I am on a document detail page
+  When I click the "History" tab
+  Then I see at least one revision entry
+  And each entry shows the editor's name and a timestamp
+```
+
+Use this format consistently. It maps directly to `test.describe` / `test` blocks in the Playwright spec.
+
+### Where this fits in the workflow
+
+```
+Issue (Journey + Scenarios) → Red E2E test → Implementation → Green
+```
+
+The scenarios in the issue are the contract. Write them before planning, treat them as failing tests from day one.
+
+---
+
 ## Issue Tracking (Gitea)
 
 All work is tracked in **Gitea** at `http://192.168.178.71:3005` (repo `marcel/familienarchiv`). Never use todo files or CLAUDE.md notes as a substitute.

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>
@@ -119,6 +133,10 @@
 			<artifactId>lombok</artifactId>
 			<optional>true</optional>
 		</dependency>
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-mail</artifactId>
+		</dependency>
 		<dependency>
 			<groupId>org.flywaydb</groupId>
 			<artifactId>flyway-core</artifactId>
@@ -144,7 +162,7 @@
 				<activeByDefault>true</activeByDefault>
 			</activation>
 			<properties>
-				<spring.profiles.active>dev</spring.profiles.active>
+				<spring.profiles.active>dev,e2e</spring.profiles.active>
 			</properties>
 		</profile>
 		<profile>
@@ -157,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/AsyncConfig.java

@@ -6,10 +6,12 @@ import java.util.concurrent.ThreadPoolExecutor;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.scheduling.annotation.EnableAsync;
+import org.springframework.scheduling.annotation.EnableScheduling;
 import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
 
 @Configuration
 @EnableAsync
+@EnableScheduling
 public class AsyncConfig {
     @Bean
     public Executor taskExecutor() {

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

@@ -43,13 +43,13 @@ public class DataInitializer {
     @Bean
     public CommandLineRunner initAdminUser(PasswordEncoder passwordEncoder) {
         return args -> {
-            if (userRepository.count() == 0) {
-                log.info("Keine User gefunden. Erstelle Default-Admin...");
+            if (userRepository.findByUsername(adminUsername).isEmpty()) {
+                log.info("Kein Admin-User '{}' gefunden. Erstelle Default-Admin...", adminUsername);
 
                 // 1. Admin Gruppe erstellen
                 UserGroup adminGroup = UserGroup.builder()
                         .name("Administrators")
-                        .permissions(Set.of("ADMIN", "READ_ALL", "WRITE_ALL", "ADMIN_USER", "ADMIN_TAG", "ADMIN_PERMISSION"))
+                        .permissions(Set.of("ADMIN", "READ_ALL", "WRITE_ALL", "ANNOTATE_ALL", "ADMIN_USER", "ADMIN_TAG", "ADMIN_PERMISSION"))
                         .build();
                 groupRepository.save(adminGroup);
 
@@ -81,10 +81,35 @@ public class DataInitializer {
     @Profile("e2e")
     public CommandLineRunner initE2EData(PersonRepository personRepo,
             DocumentRepository docRepo,
-            TagRepository tagRepo) {
+            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...");
+                UserGroup leserGroup = groupRepository.findByName("Leser").orElseGet(() ->
+                        groupRepository.save(UserGroup.builder()
+                                .name("Leser")
+                                .permissions(Set.of("READ_ALL"))
+                                .build()));
+                userRepository.save(AppUser.builder()
+                        .username("reader")
+                        .password(passwordEncoder.encode("reader123"))
+                        .groups(Set.of(leserGroup))
+                        .build());
+                log.info("E2E seed: 'reader'-Testbenutzer erstellt.");
+            }
+
             if (personRepo.count() > 0) {
-                log.info("E2E seed: Daten bereits vorhanden, überspringe.");
+                log.info("E2E seed: Personendaten bereits vorhanden, überspringe Dokument-Seed.");
                 return;
             }
 
@@ -165,8 +190,8 @@ public class DataInitializer {
                     .receivers(Set.of(otto))
                     .build());
 
-            log.info("E2E seed: {} Personen, {} Tags, {} Dokumente erstellt.",
-                    personRepo.count(), tagRepo.count(), docRepo.count());
+            log.info("E2E seed: {} Personen, {} Tags, {} Dokumente, {} Benutzer erstellt.",
+                    personRepo.count(), tagRepo.count(), docRepo.count(), userRepository.count());
         };
     }
 }

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

@@ -48,6 +48,10 @@ public class SecurityConfig {
                 .authorizeHttpRequests(auth -> {
                     // Health endpoint must be open so CI/Docker health checks work without credentials
                     auth.requestMatchers("/actuator/health").permitAll();
+                    // Password reset endpoints are unauthenticated by nature
+                    auth.requestMatchers("/api/auth/forgot-password", "/api/auth/reset-password").permitAll();
+                    // E2E test helper (only active under "e2e" profile)
+                    auth.requestMatchers("/api/auth/reset-token-for-test").permitAll();
                     // In dev, allow unauthenticated access to the OpenAPI spec and Swagger UI
                     if (environment.matchesProfiles("dev")) {
                         auth.requestMatchers(

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

@@ -1,7 +1,10 @@
 package org.raddatz.familienarchiv.controller;
 
+import org.raddatz.familienarchiv.dto.BackfillResult;
 import org.raddatz.familienarchiv.security.Permission;
 import org.raddatz.familienarchiv.security.RequirePermission;
+import org.raddatz.familienarchiv.service.DocumentService;
+import org.raddatz.familienarchiv.service.DocumentVersionService;
 import org.raddatz.familienarchiv.service.MassImportService;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -18,6 +21,8 @@ import lombok.RequiredArgsConstructor;
 public class AdminController {
 
     private final MassImportService massImportService;
+    private final DocumentService documentService;
+    private final DocumentVersionService documentVersionService;
 
     @PostMapping("/trigger-import")
     public ResponseEntity<MassImportService.ImportStatus> triggerMassImport() {
@@ -29,4 +34,17 @@ public class AdminController {
     public ResponseEntity<MassImportService.ImportStatus> importStatus() {
         return ResponseEntity.ok(massImportService.getStatus());
     }
+
+    @PostMapping("/backfill-versions")
+    public ResponseEntity<BackfillResult> backfillVersions() {
+        int count = documentVersionService.backfillMissingVersions(
+                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

@@ -0,0 +1,71 @@
+package org.raddatz.familienarchiv.controller;
+
+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;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+import java.util.UUID;
+
+@RestController
+@RequestMapping("/api/documents/{documentId}/annotations")
+@RequiredArgsConstructor
+@Slf4j
+public class AnnotationController {
+
+    private final AnnotationService annotationService;
+    private final DocumentService documentService;
+    private final UserService userService;
+
+    @GetMapping
+    public List<DocumentAnnotation> listAnnotations(@PathVariable UUID documentId) {
+        return annotationService.listAnnotations(documentId);
+    }
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
+    public DocumentAnnotation createAnnotation(
+            @PathVariable UUID documentId,
+            @RequestBody CreateAnnotationDTO dto,
+            Authentication authentication) {
+        UUID userId = resolveUserId(authentication);
+        Document doc = documentService.getDocumentById(documentId);
+        return annotationService.createAnnotation(documentId, dto, userId, doc.getFileHash());
+    }
+
+    @DeleteMapping("/{annotationId}")
+    @ResponseStatus(HttpStatus.NO_CONTENT)
+    @RequirePermission({Permission.ANNOTATE_ALL, Permission.WRITE_ALL})
+    public void deleteAnnotation(
+            @PathVariable UUID documentId,
+            @PathVariable UUID annotationId,
+            Authentication authentication) {
+        UUID userId = resolveUserId(authentication);
+        annotationService.deleteAnnotation(documentId, annotationId, userId);
+    }
+
+    // ─── private helpers ──────────────────────────────────────────────────────
+
+    private UUID resolveUserId(Authentication authentication) {
+        if (authentication == null || !authentication.isAuthenticated()) return null;
+        try {
+            AppUser user = userService.findByUsername(authentication.getName());
+            return user != null ? user.getId() : null;
+        } catch (Exception e) {
+            log.warn("Could not resolve user for annotation: {}", e.getMessage());
+            return null;
+        }
+    }
+}

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

@@ -0,0 +1,37 @@
+package org.raddatz.familienarchiv.controller;
+
+import org.raddatz.familienarchiv.dto.ForgotPasswordRequest;
+import org.raddatz.familienarchiv.dto.ResetPasswordRequest;
+import org.raddatz.familienarchiv.service.PasswordResetService;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import lombok.RequiredArgsConstructor;
+
+@RestController
+@RequestMapping("/api/auth")
+@RequiredArgsConstructor
+public class AuthController {
+
+    private final PasswordResetService passwordResetService;
+
+    @Value("${app.base-url:http://localhost:3000}")
+    private String appBaseUrl;
+
+    @PostMapping("/forgot-password")
+    public ResponseEntity<Void> forgotPassword(@RequestBody ForgotPasswordRequest request) {
+        passwordResetService.requestReset(request.getEmail(), appBaseUrl);
+        // Always return 204 — never disclose whether the email exists
+        return ResponseEntity.noContent().build();
+    }
+
+    @PostMapping("/reset-password")
+    public ResponseEntity<Void> resetPassword(@RequestBody ResetPasswordRequest request) {
+        passwordResetService.resetPassword(request);
+        return ResponseEntity.noContent().build();
+    }
+}

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

@@ -0,0 +1,38 @@
+package org.raddatz.familienarchiv.controller;
+
+import java.time.LocalDateTime;
+
+import org.raddatz.familienarchiv.repository.PasswordResetTokenRepository;
+import org.springframework.context.annotation.Profile;
+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.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.Operation;
+
+import lombok.RequiredArgsConstructor;
+
+/**
+ * Test-only endpoint to retrieve a password reset token by email.
+ * Only active under the "e2e" Spring profile.
+ */
+@RestController
+@RequestMapping("/api/auth")
+@Profile("e2e")
+@RequiredArgsConstructor
+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())
+                .map(ResponseEntity::ok)
+                .orElse(ResponseEntity.notFound().build());
+    }
+}

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

@@ -0,0 +1,153 @@
+package org.raddatz.familienarchiv.controller;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.raddatz.familienarchiv.dto.CreateCommentDTO;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.DocumentComment;
+import org.raddatz.familienarchiv.security.Permission;
+import org.raddatz.familienarchiv.security.RequirePermission;
+import org.raddatz.familienarchiv.service.CommentService;
+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
+@RequiredArgsConstructor
+@Slf4j
+public class CommentController {
+
+    private final CommentService commentService;
+    private final UserService userService;
+
+    // ─── General document comments ────────────────────────────────────────────
+
+    @GetMapping("/api/documents/{documentId}/comments")
+    public List<DocumentComment> getDocumentComments(@PathVariable UUID documentId) {
+        return commentService.getCommentsForDocument(documentId);
+    }
+
+    @PostMapping("/api/documents/{documentId}/comments")
+    @ResponseStatus(HttpStatus.CREATED)
+    @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(), dto.getMentionedUserIds(), author);
+    }
+
+    @PostMapping("/api/documents/{documentId}/comments/{commentId}/replies")
+    @ResponseStatus(HttpStatus.CREATED)
+    @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(), dto.getMentionedUserIds(), author);
+    }
+
+    // ─── Annotation comments ──────────────────────────────────────────────────
+
+    @GetMapping("/api/documents/{documentId}/annotations/{annotationId}/comments")
+    public List<DocumentComment> getAnnotationComments(@PathVariable UUID annotationId) {
+        return commentService.getCommentsForAnnotation(annotationId);
+    }
+
+    @PostMapping("/api/documents/{documentId}/annotations/{annotationId}/comments")
+    @ResponseStatus(HttpStatus.CREATED)
+    @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(), dto.getMentionedUserIds(), author);
+    }
+
+    @PostMapping("/api/documents/{documentId}/annotations/{annotationId}/comments/{commentId}/replies")
+    @ResponseStatus(HttpStatus.CREATED)
+    @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(), 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, Permission.WRITE_ALL})
+    public DocumentComment editComment(
+            @PathVariable UUID documentId,
+            @PathVariable UUID commentId,
+            @RequestBody CreateCommentDTO dto,
+            Authentication authentication) {
+        AppUser currentUser = resolveUser(authentication);
+        return commentService.editComment(documentId, commentId, dto.getContent(), currentUser);
+    }
+
+    @DeleteMapping("/api/documents/{documentId}/comments/{commentId}")
+    @ResponseStatus(HttpStatus.NO_CONTENT)
+    public void deleteComment(
+            @PathVariable UUID documentId,
+            @PathVariable UUID commentId,
+            Authentication authentication) {
+        AppUser currentUser = resolveUser(authentication);
+        commentService.deleteComment(documentId, commentId, currentUser);
+    }
+
+    // ─── private helpers ──────────────────────────────────────────────────────
+
+    private AppUser resolveUser(Authentication authentication) {
+        if (authentication == null || !authentication.isAuthenticated()) return null;
+        try {
+            return userService.findByUsername(authentication.getName());
+        } catch (Exception e) {
+            log.warn("Could not resolve user for comment: {}", e.getMessage());
+            return null;
+        }
+    }
+}

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

@@ -2,22 +2,35 @@ 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.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.model.DocumentStatus;
+import org.raddatz.familienarchiv.model.DocumentVersion;
 import org.raddatz.familienarchiv.security.Permission;
 import org.raddatz.familienarchiv.security.RequirePermission;
 import org.raddatz.familienarchiv.service.DocumentService;
+import org.raddatz.familienarchiv.service.DocumentVersionService;
 import org.raddatz.familienarchiv.service.FileService;
 import org.springframework.data.domain.Sort;
 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;
@@ -39,6 +52,7 @@ import lombok.extern.slf4j.Slf4j;
 public class DocumentController {
 
     private final DocumentService documentService;
+    private final DocumentVersionService documentVersionService;
     private final FileService fileService;
 
     // --- DOWNLOAD ---
@@ -97,6 +111,80 @@ 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(
             @RequestParam(required = false) String q,
@@ -104,14 +192,27 @@ public class DocumentController {
             @RequestParam(required = false) LocalDate to,
             @RequestParam(required = false) UUID senderId,
             @RequestParam(required = false) UUID receiverId,
-            @RequestParam(required = false, name = "tag") List<String> tags) {
-        return ResponseEntity.ok(documentService.searchDocuments(q, from, to, senderId, receiverId, tags));
+            @RequestParam(required = false, name = "tag") List<String> tags,
+            @Parameter(description = "Filter by document status") @RequestParam(required = false) DocumentStatus status) {
+        return ResponseEntity.ok(documentService.searchDocuments(q, from, to, senderId, receiverId, tags, status));
+    }
+
+    // --- VERSIONS ---
+
+    @GetMapping("/{id}/versions")
+    public List<DocumentVersionSummary> getVersions(@PathVariable UUID id) {
+        return documentVersionService.getSummaries(id);
+    }
+
+    @GetMapping("/{id}/versions/{versionId}")
+    public DocumentVersion getVersion(@PathVariable UUID id, @PathVariable UUID versionId) {
+        return documentVersionService.getVersion(id, versionId);
     }
 
     @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,23 @@ import java.util.List;
 import java.util.Map;
 import java.util.UUID;
 
+
+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.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 +32,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 +59,20 @@ public class PersonController {
     }
 
     @PostMapping
-    public ResponseEntity<Person> createPerson(@RequestBody Map<String, String> body) {
-        String firstName = body.get("firstName");
-        String lastName = body.get("lastName");
-        if (firstName == null || firstName.isBlank() || lastName == null || lastName.isBlank()) {
+    @RequirePermission(Permission.WRITE_ALL)
+    public ResponseEntity<Person> createPerson(@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");
         }
-        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 +84,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()) {

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

@@ -4,6 +4,7 @@ import java.util.List;
 import java.util.Map;
 import java.util.UUID;
 
+import org.raddatz.familienarchiv.dto.AdminUpdateUserRequest;
 import org.raddatz.familienarchiv.dto.ChangePasswordDTO;
 import org.raddatz.familienarchiv.dto.CreateUserRequest;
 import org.raddatz.familienarchiv.dto.UpdateProfileDTO;
@@ -60,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);
@@ -79,6 +81,15 @@ public class UserController {
         return ResponseEntity.ok(userService.createUserOrUpdate(request));
     }
 
+    @PutMapping("/users/{id}")
+    @RequirePermission(Permission.ADMIN_USER)
+    public ResponseEntity<AppUser> adminUpdateUser(@PathVariable UUID id,
+                                                    @RequestBody AdminUpdateUserRequest dto) {
+        AppUser updated = userService.adminUpdateUser(id, dto);
+        updated.setPassword(null);
+        return ResponseEntity.ok(updated);
+    }
+
     @DeleteMapping("/users/{id}")
     @RequirePermission(Permission.ADMIN_USER)
     public ResponseEntity<Void> deleteUser(@PathVariable UUID id) {

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/AdminUpdateUserRequest.java

@@ -0,0 +1,18 @@
+package org.raddatz.familienarchiv.dto;
+
+import lombok.Data;
+
+import java.time.LocalDate;
+import java.util.List;
+import java.util.UUID;
+
+@Data
+public class AdminUpdateUserRequest {
+    private String firstName;
+    private String lastName;
+    private LocalDate birthDate;
+    private String email;
+    private String contact;
+    private String newPassword;
+    private List<UUID> groupIds;
+}

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

@@ -0,0 +1,7 @@
+package org.raddatz.familienarchiv.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+public record BackfillResult(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) int count
+) {}

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

@@ -0,0 +1,17 @@
+package org.raddatz.familienarchiv.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class CreateAnnotationDTO {
+    private int pageNumber;
+    private double x;
+    private double y;
+    private double width;
+    private double height;
+    private String color;
+}

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

@@ -0,0 +1,13 @@
+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/CreateUserRequest.java

@@ -3,6 +3,7 @@ package org.raddatz.familienarchiv.dto;
 
 import lombok.Data;
 
+import java.time.LocalDate;
 import java.util.List;
 import java.util.UUID;
 
@@ -11,5 +12,9 @@ public class CreateUserRequest {
     private String username;
     private String email;
     private String initialPassword;
-    private List<UUID> groupIds; // In welche Gruppen soll der User?
+    private List<UUID> groupIds;
+    private String firstName;
+    private String lastName;
+    private LocalDate birthDate;
+    private String contact;
 }

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/DocumentVersionSummary.java

@@ -0,0 +1,14 @@
+package org.raddatz.familienarchiv.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.UUID;
+
+public record DocumentVersionSummary(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) LocalDateTime savedAt,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String editorName,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) List<String> changedFields
+) {}

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

@@ -0,0 +1,8 @@
+package org.raddatz.familienarchiv.dto;
+
+import lombok.Data;
+
+@Data
+public class ForgotPasswordRequest {
+    private String email;
+}

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/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/ResetPasswordRequest.java

@@ -0,0 +1,9 @@
+package org.raddatz.familienarchiv.dto;
+
+import lombok.Data;
+
+@Data
+public class ResetPasswordRequest {
+    private String token;
+    private String newPassword;
+}

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,10 @@ package org.raddatz.familienarchiv.exception;
  */
 public enum ErrorCode {
 
+    // --- Persons ---
+    /** A person with the given ID does not exist. 404 */
+    PERSON_NOT_FOUND,
+
     // --- Documents ---
     /** A document with the given ID does not exist. 404 */
     DOCUMENT_NOT_FOUND,
@@ -17,6 +21,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 */
@@ -35,6 +41,28 @@ public enum ErrorCode {
     UNAUTHORIZED,
     /** The authenticated user lacks the required permission. 403 */
     FORBIDDEN,
+    /** The password-reset token is missing, expired, or already used. 400 */
+    INVALID_RESET_TOKEN,
+
+    // --- Annotations ---
+    /** The annotation with the given ID does not exist. 404 */
+    ANNOTATION_NOT_FOUND,
+    /** 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 */

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

@@ -0,0 +1,62 @@
+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 = "document_annotations")
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class DocumentAnnotation {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID id;
+
+    @Column(name = "document_id", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID documentId;
+
+    @Column(name = "page_number", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private int pageNumber;
+
+    @Column(nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private double x;
+
+    @Column(nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private double y;
+
+    @Column(nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private double width;
+
+    @Column(nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private double height;
+
+    @Column(nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private String color;
+
+    @Column(name = "file_hash", length = 64)
+    private String fileHash;
+
+    @Column(name = "created_by")
+    private UUID createdBy;
+
+    @Column(name = "created_at", nullable = false, updatable = false)
+    @CreationTimestamp
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private LocalDateTime createdAt;
+}

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

@@ -0,0 +1,85 @@
+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;
+import java.util.List;
+import java.util.UUID;
+
+@Entity
+@Table(name = "document_comments")
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class DocumentComment {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID id;
+
+    @Column(name = "document_id", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID documentId;
+
+    @Column(name = "annotation_id")
+    private UUID annotationId;
+
+    @Column(name = "block_id")
+    private UUID blockId;
+
+    @Column(name = "parent_id")
+    private UUID parentId;
+
+    @Column(name = "author_id")
+    private UUID authorId;
+
+    @Column(name = "author_name", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private String authorName;
+
+    @Column(nullable = false, columnDefinition = "TEXT")
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private String content;
+
+    @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;
+
+    // Populated by the service — not stored in the database
+    @Transient
+    @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/DocumentVersion.java

@@ -0,0 +1,50 @@
+package org.raddatz.familienarchiv.model;
+
+import jakarta.persistence.*;
+import lombok.*;
+import org.hibernate.annotations.JdbcTypeCode;
+import org.hibernate.type.SqlTypes;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+@Entity
+@Table(name = "document_versions")
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class DocumentVersion {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID id;
+
+    @Column(name = "document_id", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private UUID documentId;
+
+    @Column(name = "saved_at", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private LocalDateTime savedAt;
+
+    @Column(name = "editor_id")
+    private UUID editorId;
+
+    @Column(name = "editor_name", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private String editorName;
+
+    @JdbcTypeCode(SqlTypes.JSON)
+    @Column(columnDefinition = "jsonb", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private String snapshot;
+
+    @JdbcTypeCode(SqlTypes.JSON)
+    @Column(name = "changed_fields", columnDefinition = "jsonb", nullable = false)
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    private String changedFields;
+}

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/PasswordResetToken.java

@@ -0,0 +1,45 @@
+package org.raddatz.familienarchiv.model;
+
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Entity
+@Table(name = "password_reset_tokens")
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class PasswordResetToken {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    private UUID id;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "user_id", nullable = false)
+    private AppUser user;
+
+    @Column(nullable = false, unique = true, length = 64)
+    private String token;
+
+    @Column(name = "expires_at", nullable = false)
+    private LocalDateTime expiresAt;
+
+    @Column(nullable = false)
+    @Builder.Default
+    private boolean used = false;
+}

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

@@ -0,0 +1,19 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.raddatz.familienarchiv.model.DocumentAnnotation;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+
+public interface AnnotationRepository extends JpaRepository<DocumentAnnotation, UUID> {
+
+    List<DocumentAnnotation> findByDocumentId(UUID documentId);
+
+    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

@@ -0,0 +1,18 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.raddatz.familienarchiv.model.DocumentComment;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.List;
+import java.util.UUID;
+
+public interface CommentRepository extends JpaRepository<DocumentComment, UUID> {
+
+    List<DocumentComment> findByDocumentIdAndAnnotationIdIsNullAndParentIdIsNull(UUID documentId);
+
+    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);
@@ -34,14 +41,28 @@ public interface DocumentRepository extends JpaRepository<Document, UUID>, JpaSp
 
     List<Document> findByTags_Id(UUID tagId);
 
+    @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,
@@ -50,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,6 +7,7 @@ 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.Tag;
 import org.springframework.data.jpa.domain.Specification;
 import org.springframework.util.StringUtils;
@@ -55,6 +56,11 @@ public class DocumentSpecifications {
         };
     }
     
+    // 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)
     public static Specification<Document> hasTags(List<String> tags) {
         return (root, query, cb) -> {

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

@@ -0,0 +1,17 @@
+package org.raddatz.familienarchiv.repository;
+
+import org.raddatz.familienarchiv.model.DocumentVersion;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.stereotype.Repository;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+
+@Repository
+public interface DocumentVersionRepository extends JpaRepository<DocumentVersion, UUID> {
+
+    List<DocumentVersion> findByDocumentIdOrderBySavedAtAsc(UUID documentId);
+
+    Optional<DocumentVersion> findByIdAndDocumentId(UUID id, UUID documentId);
+}

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/PasswordResetTokenRepository.java

@@ -0,0 +1,22 @@
+package org.raddatz.familienarchiv.repository;
+
+import java.time.LocalDateTime;
+import java.util.Optional;
+import java.util.UUID;
+
+import org.raddatz.familienarchiv.model.PasswordResetToken;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+
+public interface PasswordResetTokenRepository extends JpaRepository<PasswordResetToken, UUID> {
+
+    Optional<PasswordResetToken> findByToken(String token);
+
+    @Query("SELECT t.token FROM PasswordResetToken t WHERE t.user.email = :email AND t.used = false AND t.expiresAt > :now ORDER BY t.expiresAt DESC LIMIT 1")
+    Optional<String> findLatestActiveTokenByEmail(String email, LocalDateTime now);
+
+    @Modifying
+    @Query("DELETE FROM PasswordResetToken t WHERE t.expiresAt < :now OR t.used = true")
+    void deleteExpiredAndUsed(LocalDateTime now);
+}

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;
@@ -28,6 +29,36 @@ 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
+            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,'%'))
+            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/Permission.java

@@ -3,6 +3,7 @@ package org.raddatz.familienarchiv.security;
 public enum Permission {
     READ_ALL,
     WRITE_ALL,
+    ANNOTATE_ALL,
     ADMIN,
     ADMIN_USER,
     ADMIN_TAG,

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()
-                .anyMatch(a -> a.getAuthority().equals(requiredPerm.name()));
+        boolean hasAny = auth.getAuthorities().stream()
+                .anyMatch(a -> {
+                    for (Permission p : requiredPerms) {
+                        if (a.getAuthority().equals(p.name())) return true;
+                    }
+                    return false;
+                });
 
-        if (!hasPermission) {
-            throw DomainException.forbidden("Missing required permission: " + requiredPerm.name());
+        if (!hasAny) {
+            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

@@ -0,0 +1,83 @@
+package org.raddatz.familienarchiv.service;
+
+import lombok.RequiredArgsConstructor;
+import org.raddatz.familienarchiv.dto.CreateAnnotationDTO;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.model.DocumentAnnotation;
+import org.raddatz.familienarchiv.repository.AnnotationRepository;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+import java.util.UUID;
+
+@Service
+@RequiredArgsConstructor
+public class AnnotationService {
+
+    private final AnnotationRepository annotationRepository;
+
+    public List<DocumentAnnotation> listAnnotations(UUID documentId) {
+        return annotationRepository.findByDocumentId(documentId);
+    }
+
+    @Transactional
+    public DocumentAnnotation createAnnotation(UUID documentId, CreateAnnotationDTO dto, UUID userId, String fileHash) {
+        List<DocumentAnnotation> existing =
+                annotationRepository.findByDocumentIdAndPageNumber(documentId, dto.getPageNumber());
+
+        boolean overlaps = existing.stream().anyMatch(a -> overlaps(a, dto));
+        if (overlaps) {
+            throw DomainException.conflict(
+                    ErrorCode.ANNOTATION_OVERLAP, "Annotation overlaps an existing one on this page");
+        }
+
+        DocumentAnnotation annotation = DocumentAnnotation.builder()
+                .documentId(documentId)
+                .pageNumber(dto.getPageNumber())
+                .x(dto.getX())
+                .y(dto.getY())
+                .width(dto.getWidth())
+                .height(dto.getHeight())
+                .color(dto.getColor())
+                .fileHash(fileHash)
+                .createdBy(userId)
+                .build();
+
+        return annotationRepository.save(annotation);
+    }
+
+    @Transactional
+    public void deleteAnnotation(UUID documentId, UUID annotationId, UUID userId) {
+        DocumentAnnotation annotation = annotationRepository
+                .findByIdAndDocumentId(annotationId, documentId)
+                .orElseThrow(() -> DomainException.notFound(
+                        ErrorCode.ANNOTATION_NOT_FOUND, "Annotation not found: " + annotationId));
+
+        if (userId == null || !userId.equals(annotation.getCreatedBy())) {
+            throw DomainException.forbidden("Only the annotation author can delete it");
+        }
+
+        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) {
+        double ex2 = existing.getX() + existing.getWidth();
+        double ey2 = existing.getY() + existing.getHeight();
+        double dx2 = dto.getX() + dto.getWidth();
+        double dy2 = dto.getY() + dto.getHeight();
+        return existing.getX() < dx2 && ex2 > dto.getX()
+                && existing.getY() < dy2 && ey2 > dto.getY();
+    }
+}

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

@@ -0,0 +1,182 @@
+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;
+import org.raddatz.familienarchiv.model.DocumentComment;
+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
+@RequiredArgsConstructor
+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 withRepliesAndMentions(roots);
+    }
+
+    public List<DocumentComment> getCommentsForAnnotation(UUID annotationId) {
+        List<DocumentComment> roots = commentRepository.findByAnnotationIdAndParentIdIsNull(annotationId);
+        return withRepliesAndMentions(roots);
+    }
+
+    public List<DocumentComment> getCommentsForBlock(UUID blockId) {
+        List<DocumentComment> roots = commentRepository.findByBlockIdAndParentIdIsNull(blockId);
+        return withRepliesAndMentions(roots);
+    }
+
+    @Transactional
+    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)
+                .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 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));
+
+        UUID rootId = target.getParentId() != null ? target.getParentId() : target.getId();
+        DocumentComment root = commentRepository.findById(rootId)
+                .orElseThrow(() -> DomainException.notFound(
+                        ErrorCode.COMMENT_NOT_FOUND, "Comment not found: " + rootId));
+
+        DocumentComment reply = DocumentComment.builder()
+                .documentId(documentId)
+                .annotationId(root.getAnnotationId())
+                .parentId(root.getId())
+                .content(content)
+                .authorId(author.getId())
+                .authorName(resolveAuthorName(author))
+                .build();
+        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
+    public DocumentComment editComment(UUID documentId, UUID commentId, String content, AppUser currentUser) {
+        DocumentComment comment = findComment(documentId, commentId);
+        if (!currentUser.getId().equals(comment.getAuthorId())) {
+            throw DomainException.forbidden("Only the comment author can edit it");
+        }
+        comment.setContent(content);
+        return commentRepository.save(comment);
+    }
+
+    @Transactional
+    public void deleteComment(UUID documentId, UUID commentId, AppUser currentUser) {
+        DocumentComment comment = findComment(documentId, commentId);
+        boolean isAuthor = currentUser.getId().equals(comment.getAuthorId());
+        boolean isAdmin = currentUser.hasPermission("ADMIN");
+        if (!isAuthor && !isAdmin) {
+            throw DomainException.forbidden("Only the comment author or an admin can delete it");
+        }
+        commentRepository.delete(comment);
+    }
+
+    public List<DocumentComment> findReplies(UUID parentId) {
+        return commentRepository.findByParentId(parentId);
+    }
+
+    // ─── private helpers ──────────────────────────────────────────────────────
+
+    private List<DocumentComment> withRepliesAndMentions(List<DocumentComment> roots) {
+        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()))
+                .orElseThrow(() -> DomainException.notFound(
+                        ErrorCode.COMMENT_NOT_FOUND, "Comment not found: " + commentId));
+    }
+
+    private String resolveAuthorName(AppUser author) {
+        String first = author.getFirstName();
+        String last = author.getLastName();
+        if ((first == null || first.isBlank()) && (last == null || last.isBlank())) {
+            return author.getUsername();
+        }
+        return ((first != null ? first : "") + " " + (last != null ? last : "")).strip();
+    }
+}

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

@@ -4,11 +4,13 @@ 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.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 +20,16 @@ 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.HashMap;
 import java.util.HashSet;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
 import java.util.UUID;
@@ -37,42 +44,65 @@ public class DocumentService {
     private final PersonService personService;
     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 NEIN: Erstellt neuen Eintrag (wartet auf Metadaten).
+     * - Wenn JA: Aktualisiert Status und verknüpft Datei — isNew = false.
+     * - 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
-        Optional<Document> existingDoc = documentRepository.findByOriginalFilename(originalFilename);
+        // 1. Check for existing record (findFirst to survive duplicate filenames in the DB)
+        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
@@ -81,15 +111,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);
@@ -119,13 +165,16 @@ public class DocumentService {
 
         // Datei
         if (file != null && !file.isEmpty()) {
-            String s3Key = fileService.uploadFile(file, file.getOriginalFilename());
-            doc.setFilePath(s3Key);
+            FileService.UploadResult upload = fileService.uploadFile(file, file.getOriginalFilename());
+            doc.setFilePath(upload.s3Key());
+            doc.setFileHash(upload.fileHash());
             doc.setContentType(file.getContentType());
             doc.setStatus(DocumentStatus.UPLOADED);
         }
 
-        return documentRepository.save(doc);
+        Document finalDoc = documentRepository.save(doc);
+        documentVersionService.recordVersion(finalDoc);
+        return finalDoc;
     }
 
     @Transactional
@@ -165,20 +214,24 @@ 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)
-
-            // Neue Datei hochladen
-            String s3Key = fileService.uploadFile(newFile, newFile.getOriginalFilename());
-
-            doc.setFilePath(s3Key);
+            FileService.UploadResult upload = fileService.uploadFile(newFile, newFile.getOriginalFilename());
+            doc.setFilePath(upload.s3Key());
+            doc.setFileHash(upload.fileHash());
             doc.setOriginalFilename(newFile.getOriginalFilename());
             doc.setContentType(newFile.getContentType());
             doc.setStatus(DocumentStatus.UPLOADED);
         }
 
-        return documentRepository.save(doc);
+        Document saved = documentRepository.save(doc);
+        documentVersionService.recordVersion(saved);
+        return saved;
     }
 
     public Document updateDocumentTags(UUID docId, List<String> tagNames) {
@@ -219,16 +272,24 @@ 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, DocumentStatus status) {
         Specification<Document> spec = Specification.where(hasText(text))
                 .and(isBetween(from, to))
                 .and(hasSender(sender))
                 .and(hasReceiver(receiver))
-                .and(hasTags(tags));
+                .and(hasTags(tags))
+                .and(hasStatus(status));
 
-        // Immer sortiert nach Datum
-        return documentRepository.findAll(spec, Sort.by(Sort.Direction.ASC, "documentDate"));
+        // Neueste zuerst (nach Erstellungsdatum)
+        return documentRepository.findAll(spec, Sort.by(Sort.Direction.DESC, "createdAt"));
     }
 
     // 2. SPEZIALITÄT: Der Schriftwechsel
@@ -252,6 +313,10 @@ public class DocumentService {
                 .orElseThrow(() -> DomainException.notFound(ErrorCode.DOCUMENT_NOT_FOUND, "Document not found: " + id));
     }
 
+    public List<Document> getDocumentsWithoutVersions() {
+        return documentRepository.findDocumentsWithoutVersions();
+    }
+
     public List<Document> getDocumentsBySender(UUID senderId) {
         return documentRepository.findBySenderId(senderId);
     }
@@ -263,9 +328,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 -> {
@@ -274,4 +367,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/DocumentVersionService.java

@@ -0,0 +1,229 @@
+package org.raddatz.familienarchiv.service;
+
+import tools.jackson.core.type.TypeReference;
+import tools.jackson.databind.ObjectMapper;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.raddatz.familienarchiv.dto.DocumentVersionSummary;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.model.DocumentVersion;
+import org.raddatz.familienarchiv.model.Person;
+import org.raddatz.familienarchiv.model.Tag;
+import org.raddatz.familienarchiv.repository.DocumentVersionRepository;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+import java.util.UUID;
+import java.util.stream.Collectors;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class DocumentVersionService {
+
+    private final DocumentVersionRepository versionRepository;
+    private final UserService userService;
+    private final ObjectMapper objectMapper;
+
+    @Transactional
+    public void recordVersion(Document doc) {
+        AppUser editor = resolveCurrentUser();
+        String editorName = buildEditorName(editor);
+        UUID editorId = editor != null ? editor.getId() : null;
+
+        String snapshot = serializeSnapshot(doc);
+        List<DocumentVersion> previous = versionRepository.findByDocumentIdOrderBySavedAtAsc(doc.getId());
+        String changedFields = computeChangedFields(doc, previous);
+
+        versionRepository.save(DocumentVersion.builder()
+                .documentId(doc.getId())
+                .savedAt(LocalDateTime.now())
+                .editorId(editorId)
+                .editorName(editorName)
+                .snapshot(snapshot)
+                .changedFields(changedFields)
+                .build());
+    }
+
+    @Transactional
+    public int backfillMissingVersions(List<Document> docs) {
+        int count = 0;
+        for (Document doc : docs) {
+            List<DocumentVersion> existing = versionRepository.findByDocumentIdOrderBySavedAtAsc(doc.getId());
+            if (!existing.isEmpty()) continue;
+            LocalDateTime savedAt = doc.getCreatedAt() != null ? doc.getCreatedAt() : LocalDateTime.now();
+            versionRepository.save(DocumentVersion.builder()
+                    .documentId(doc.getId())
+                    .savedAt(savedAt)
+                    .editorId(null)
+                    .editorName("Datenimport")
+                    .snapshot(serializeSnapshot(doc))
+                    .changedFields("[]")
+                    .build());
+            count++;
+        }
+        return count;
+    }
+
+    public List<DocumentVersionSummary> getSummaries(UUID documentId) {
+        return versionRepository.findByDocumentIdOrderBySavedAtAsc(documentId).stream()
+                .map(v -> new DocumentVersionSummary(
+                        v.getId(),
+                        v.getSavedAt(),
+                        v.getEditorName(),
+                        parseChangedFields(v.getChangedFields())))
+                .toList();
+    }
+
+    public DocumentVersion getVersion(UUID documentId, UUID versionId) {
+        return versionRepository.findByIdAndDocumentId(versionId, documentId)
+                .orElseThrow(() -> DomainException.notFound(ErrorCode.DOCUMENT_NOT_FOUND,
+                        "Version not found: " + versionId));
+    }
+
+    // ─── private helpers ──────────────────────────────────────────────────────
+
+    private AppUser resolveCurrentUser() {
+        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
+        if (auth == null || !auth.isAuthenticated()) {
+            return null;
+        }
+        try {
+            return userService.findByUsername(auth.getName());
+        } catch (Exception e) {
+            log.warn("Could not resolve editor for version snapshot: {}", e.getMessage());
+            return null;
+        }
+    }
+
+    private String buildEditorName(AppUser user) {
+        if (user == null) return "Unknown";
+        String first = user.getFirstName();
+        String last = user.getLastName();
+        if (first != null && !first.isBlank() && last != null && !last.isBlank()) {
+            return first + " " + last;
+        }
+        return user.getUsername();
+    }
+
+    private String serializeSnapshot(Document doc) {
+        try {
+            return objectMapper.writeValueAsString(doc);
+        } catch (Exception e) {
+            log.error("Failed to serialize document snapshot for {}", doc.getId(), e);
+            return "{}";
+        }
+    }
+
+    private String computeChangedFields(Document current, List<DocumentVersion> previousVersions) {
+        if (previousVersions.isEmpty()) {
+            return "[]";
+        }
+        DocumentVersion last = previousVersions.get(previousVersions.size() - 1);
+        try {
+            Map<String, Object> previousMap = objectMapper.readValue(
+                    last.getSnapshot(), new TypeReference<>() {});
+            List<String> changed = new ArrayList<>();
+
+            checkScalar(changed, "title", current.getTitle(), previousMap);
+            checkScalar(changed, "documentDate",
+                    current.getDocumentDate() != null ? current.getDocumentDate().toString() : null,
+                    previousMap);
+            checkScalar(changed, "location", current.getLocation(), previousMap);
+            checkScalar(changed, "documentLocation", current.getDocumentLocation(), previousMap);
+            checkScalar(changed, "transcription", current.getTranscription(), previousMap);
+            checkScalar(changed, "summary", current.getSummary(), previousMap);
+            checkSender(changed, current, previousMap);
+            checkReceivers(changed, current, previousMap);
+            checkTags(changed, current, previousMap);
+
+            return objectMapper.writeValueAsString(changed);
+        } catch (Exception e) {
+            log.warn("Could not compute changedFields for document {}", current.getId(), e);
+            return "[]";
+        }
+    }
+
+    private void checkScalar(List<String> changed, String field, String currentValue,
+                              Map<String, Object> previousMap) {
+        Object prev = previousMap.get(field);
+        String prevStr = prev != null ? prev.toString() : null;
+        if (!Objects.equals(currentValue, prevStr)) {
+            changed.add(field);
+        }
+    }
+
+    @SuppressWarnings("unchecked")
+    private void checkSender(List<String> changed, Document current, Map<String, Object> previousMap) {
+        String currentId = current.getSender() != null
+                ? current.getSender().getId().toString() : null;
+        Object prevSender = previousMap.get("sender");
+        String prevId = null;
+        if (prevSender instanceof Map<?, ?> senderMap) {
+            Object id = senderMap.get("id");
+            prevId = id != null ? id.toString() : null;
+        }
+        if (!Objects.equals(currentId, prevId)) {
+            changed.add("sender");
+        }
+    }
+
+    @SuppressWarnings("unchecked")
+    private void checkReceivers(List<String> changed, Document current, Map<String, Object> previousMap) {
+        Set<String> currentIds = current.getReceivers() != null
+                ? current.getReceivers().stream().map(p -> p.getId().toString()).collect(Collectors.toSet())
+                : Set.of();
+        Object prevReceivers = previousMap.get("receivers");
+        Set<String> prevIds = Set.of();
+        if (prevReceivers instanceof List<?> list) {
+            prevIds = list.stream()
+                    .filter(r -> r instanceof Map<?, ?>)
+                    .map(r -> ((Map<?, ?>) r).get("id"))
+                    .filter(Objects::nonNull)
+                    .map(Object::toString)
+                    .collect(Collectors.toSet());
+        }
+        if (!currentIds.equals(prevIds)) {
+            changed.add("receivers");
+        }
+    }
+
+    @SuppressWarnings("unchecked")
+    private void checkTags(List<String> changed, Document current, Map<String, Object> previousMap) {
+        Set<String> currentNames = current.getTags() != null
+                ? current.getTags().stream().map(Tag::getName).collect(Collectors.toSet())
+                : Set.of();
+        Object prevTags = previousMap.get("tags");
+        Set<String> prevNames = Set.of();
+        if (prevTags instanceof List<?> list) {
+            prevNames = list.stream()
+                    .filter(t -> t instanceof Map<?, ?>)
+                    .map(t -> ((Map<?, ?>) t).get("name"))
+                    .filter(Objects::nonNull)
+                    .map(Object::toString)
+                    .collect(Collectors.toSet());
+        }
+        if (!currentNames.equals(prevNames)) {
+            changed.add("tags");
+        }
+    }
+
+    private List<String> parseChangedFields(String json) {
+        try {
+            return objectMapper.readValue(json, new TypeReference<>() {});
+        } catch (Exception e) {
+            return List.of();
+        }
+    }
+}

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 {
-        // Generate secure unique path: "documents/UUID_filename"
+    public UploadResult uploadFile(MultipartFile file, String originalFilename) throws IOException {
+        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,
-                    RequestBody.fromInputStream(file.getInputStream(), file.getSize()));
+            s3Client.putObject(putObjectRequest, RequestBody.fromBytes(bytes));
 
-            log.info("Uploaded file to S3: {}", s3Key);
-            return s3Key;
+            log.info("Uploaded file to S3: {} (hash={})", s3Key, fileHash);
+            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 {
-        GetObjectRequest getObjectRequest = GetObjectRequest.builder()
-                .bucket(bucketName)
-                .key(s3Key)
-                .build();
+        try {
+            GetObjectRequest getObjectRequest = GetObjectRequest.builder()
+                    .bucket(bucketName)
+                    .key(s3Key)
+                    .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();
-        if (contentType == null || contentType.isBlank()) {
-            contentType = "application/octet-stream";
+            String contentType = s3Object.response().contentType();
+            if (contentType == null || contentType.isBlank()) {
+                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/PasswordResetService.java

@@ -0,0 +1,132 @@
+package org.raddatz.familienarchiv.service;
+
+import java.security.SecureRandom;
+import java.time.LocalDateTime;
+import java.util.HexFormat;
+import java.util.Optional;
+
+import org.raddatz.familienarchiv.dto.ResetPasswordRequest;
+import org.raddatz.familienarchiv.exception.DomainException;
+import org.raddatz.familienarchiv.exception.ErrorCode;
+import org.raddatz.familienarchiv.model.AppUser;
+import org.raddatz.familienarchiv.model.PasswordResetToken;
+import org.raddatz.familienarchiv.repository.AppUserRepository;
+import org.raddatz.familienarchiv.repository.PasswordResetTokenRepository;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.mail.MailException;
+import org.springframework.mail.SimpleMailMessage;
+import org.springframework.mail.javamail.JavaMailSender;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class PasswordResetService {
+
+    private final AppUserRepository userRepository;
+    private final PasswordResetTokenRepository tokenRepository;
+    private final PasswordEncoder passwordEncoder;
+
+    @Autowired(required = false)
+    private JavaMailSender mailSender;
+
+    @Value("${app.mail.from:noreply@familienarchiv.local}")
+    private String mailFrom;
+
+    private static final SecureRandom SECURE_RANDOM = new SecureRandom();
+    private static final int TOKEN_EXPIRY_HOURS = 1;
+
+    /**
+     * Creates a reset token for the given email address and sends it via email.
+     * If the email is not found, silently does nothing (prevents user enumeration).
+     * If no mail sender is configured, logs a warning.
+     */
+    public void requestReset(String email, String appBaseUrl) {
+        Optional<AppUser> userOpt = userRepository.findByEmail(email);
+        if (userOpt.isEmpty()) {
+            log.debug("Password reset requested for unknown email: {}", email);
+            return;
+        }
+
+        AppUser user = userOpt.get();
+        String token = generateToken();
+
+        tokenRepository.save(PasswordResetToken.builder()
+                .user(user)
+                .token(token)
+                .expiresAt(LocalDateTime.now().plusHours(TOKEN_EXPIRY_HOURS))
+                .build());
+
+        sendResetEmail(user.getEmail(), token, appBaseUrl);
+    }
+
+    /**
+     * Validates the token and updates the user's password.
+     */
+    @Transactional
+    public void resetPassword(ResetPasswordRequest request) {
+        PasswordResetToken resetToken = tokenRepository.findByToken(request.getToken())
+                .orElseThrow(() -> DomainException.badRequest(
+                        ErrorCode.INVALID_RESET_TOKEN, "Invalid or unknown reset token"));
+
+        if (resetToken.isUsed() || resetToken.getExpiresAt().isBefore(LocalDateTime.now())) {
+            throw DomainException.badRequest(ErrorCode.INVALID_RESET_TOKEN, "Token expired or already used");
+        }
+
+        AppUser user = resetToken.getUser();
+        user.setPassword(passwordEncoder.encode(request.getNewPassword()));
+        userRepository.save(user);
+
+        resetToken.setUsed(true);
+        tokenRepository.save(resetToken);
+    }
+
+    /** Nightly cleanup of expired and used tokens. */
+    @Scheduled(cron = "0 0 3 * * *")
+    @Transactional
+    public void cleanupExpiredTokens() {
+        tokenRepository.deleteExpiredAndUsed(LocalDateTime.now());
+        log.info("Cleaned up expired password reset tokens");
+    }
+
+    private String generateToken() {
+        byte[] bytes = new byte[32];
+        SECURE_RANDOM.nextBytes(bytes);
+        return HexFormat.of().formatHex(bytes);
+    }
+
+    private void sendResetEmail(String to, String token, String appBaseUrl) {
+        if (mailSender == null) {
+            log.warn("Mail sender not configured — skipping password reset email to {}", to);
+            return;
+        }
+
+        String resetUrl = appBaseUrl + "/reset-password?token=" + token;
+        SimpleMailMessage message = new SimpleMailMessage();
+        message.setFrom(mailFrom);
+        message.setTo(to);
+        message.setSubject("Passwort zurücksetzen — Familienarchiv");
+        message.setText(
+                "Hallo,\n\n"
+                + "Sie haben eine Passwort-Zurücksetzung beantragt.\n\n"
+                + "Klicken Sie auf den folgenden Link, um Ihr Passwort zurückzusetzen:\n"
+                + resetUrl + "\n\n"
+                + "Der Link ist " + TOKEN_EXPIRY_HOURS + " Stunde(n) gültig.\n\n"
+                + "Falls Sie diese Anfrage nicht gestellt haben, ignorieren Sie diese E-Mail.\n\n"
+                + "Ihr Familienarchiv-Team");
+
+        try {
+            mailSender.send(message);
+            log.info("Password reset email sent to {}", to);
+        } catch (MailException e) {
+            log.error("Failed to send password reset email to {}: {}", to, e.getMessage());
+        }
+    }
+}

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

@@ -1,9 +1,13 @@
 package org.raddatz.familienarchiv.service;
 
 import java.util.List;
+import java.util.Optional;
 import java.util.UUID;
 
+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.repository.PersonRepository;
 import org.springframework.http.HttpStatus;
@@ -19,16 +23,19 @@ public class PersonService {
 
     private final PersonRepository personRepository;
 
-    public List<Person> findAll(String q) {
-        if (q != null && !q.isBlank()) {
-            return personRepository.searchByName(q);
+    public List<PersonSummaryDTO> findAll(String q) {
+        if (q == null) {
+            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 +49,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 +77,36 @@ public class PersonService {
     }
 
     @Transactional
-    public Person updatePerson(UUID id, PersonUpdateDTO dto) {
-        if (dto.getBirthYear() != null && dto.getDeathYear() != null && dto.getBirthYear() > dto.getDeathYear()) {
+    public Person createPerson(PersonUpdateDTO dto) {
+        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 +122,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);

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

@@ -3,6 +3,7 @@ package org.raddatz.familienarchiv.service;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
+import org.raddatz.familienarchiv.dto.AdminUpdateUserRequest;
 import org.raddatz.familienarchiv.dto.ChangePasswordDTO;
 import org.raddatz.familienarchiv.dto.CreateUserRequest;
 import org.raddatz.familienarchiv.dto.UpdateProfileDTO;
@@ -17,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;
@@ -54,6 +56,10 @@ public class UserService {
                     .email(request.getEmail())
                     .password(passwordEncoder.encode(request.getInitialPassword()))
                     .groups(groups)
+                    .firstName(request.getFirstName())
+                    .lastName(request.getLastName())
+                    .birthDate(request.getBirthDate())
+                    .contact(request.getContact())
                     .enabled(true)
                     .build();
         }
@@ -73,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);
@@ -96,6 +114,39 @@ public class UserService {
         return userRepository.save(user);
     }
 
+    @Transactional
+    public AppUser adminUpdateUser(UUID id, AdminUpdateUserRequest dto) {
+        AppUser user = getById(id);
+
+        if (dto.getEmail() != null && !dto.getEmail().isBlank()) {
+            userRepository.findByEmail(dto.getEmail()).ifPresent(existing -> {
+                if (!existing.getId().equals(id)) {
+                    throw DomainException.conflict(ErrorCode.EMAIL_ALREADY_IN_USE,
+                            "E-Mail wird bereits von einem anderen Konto verwendet");
+                }
+            });
+            user.setEmail(dto.getEmail().trim());
+        } else if (dto.getEmail() != null && dto.getEmail().isBlank()) {
+            user.setEmail(null);
+        }
+
+        user.setFirstName(dto.getFirstName());
+        user.setLastName(dto.getLastName());
+        user.setBirthDate(dto.getBirthDate());
+        user.setContact(dto.getContact() == null || dto.getContact().isBlank() ? null : dto.getContact().trim());
+
+        if (dto.getNewPassword() != null && !dto.getNewPassword().isBlank()) {
+            user.setPassword(passwordEncoder.encode(dto.getNewPassword()));
+        }
+
+        if (dto.getGroupIds() != null) {
+            Set<UserGroup> groups = new HashSet<>(groupRepository.findAllById(dto.getGroupIds()));
+            user.setGroups(groups);
+        }
+
+        return userRepository.save(user);
+    }
+
     @Transactional
     public void changePassword(UUID userId, ChangePasswordDTO 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:
@@ -24,6 +25,23 @@ spring:
       max-file-size: 50MB
       max-request-size: 50MB
 
+  mail:
+    host: ${MAIL_HOST:}
+    port: ${MAIL_PORT:587}
+    username: ${MAIL_USERNAME:}
+    password: ${MAIL_PASSWORD:}
+    properties:
+      mail:
+        smtp:
+          auth: true
+          starttls:
+            enable: true
+
+management:
+  health:
+    mail:
+      enabled: false
+
 springdoc:
   api-docs:
     enabled: false
@@ -38,6 +56,11 @@ app:
     bucket: ${S3_BUCKET_NAME}
     region: ${S3_REGION}
 
+  base-url: ${APP_BASE_URL:http://localhost:3000}
+
+  mail:
+    from: ${APP_MAIL_FROM:noreply@familienarchiv.local}
+
   admin:
     username: ${APP_ADMIN_USERNAME:admin}
     password: ${APP_ADMIN_PASSWORD:admin123}

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

@@ -0,0 +1,14 @@
+CREATE TABLE document_annotations (
+    id          UUID             PRIMARY KEY DEFAULT gen_random_uuid(),
+    document_id UUID             NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    page_number INTEGER          NOT NULL,
+    x           DOUBLE PRECISION NOT NULL,
+    y           DOUBLE PRECISION NOT NULL,
+    width       DOUBLE PRECISION NOT NULL,
+    height      DOUBLE PRECISION NOT NULL,
+    color       VARCHAR(20)      NOT NULL,
+    created_by  UUID             REFERENCES users(id) ON DELETE SET NULL,
+    created_at  TIMESTAMP        NOT NULL DEFAULT now()
+);
+
+CREATE INDEX ON document_annotations (document_id, page_number);

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

@@ -0,0 +1,7 @@
+-- Grant ANNOTATE_ALL to every group that already has ADMIN.
+-- New installs get it via DataInitializer; this covers existing deployments.
+INSERT INTO group_permissions (group_id, permission)
+SELECT g.id, 'ANNOTATE_ALL'
+FROM user_groups g
+WHERE g.id IN (SELECT group_id FROM group_permissions WHERE permission = 'ADMIN')
+  AND g.id NOT IN (SELECT group_id FROM group_permissions WHERE permission = 'ANNOTATE_ALL');

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

@@ -0,0 +1,15 @@
+CREATE TABLE document_comments (
+    id              UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+    document_id     UUID         NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    annotation_id   UUID         REFERENCES document_annotations(id) ON DELETE CASCADE,
+    parent_id       UUID         REFERENCES document_comments(id) ON DELETE CASCADE,
+    author_id       UUID         REFERENCES users(id) ON DELETE SET NULL,
+    author_name     VARCHAR(200) NOT NULL,
+    content         TEXT         NOT NULL,
+    created_at      TIMESTAMP    NOT NULL DEFAULT now(),
+    updated_at      TIMESTAMP    NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_dc_document   ON document_comments(document_id);
+CREATE INDEX idx_dc_annotation ON document_comments(annotation_id);
+CREATE INDEX idx_dc_parent     ON document_comments(parent_id);

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/V8__add_password_reset_tokens.sql

@@ -0,0 +1,10 @@
+CREATE TABLE password_reset_tokens (
+    id          UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id     UUID         NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    token       VARCHAR(64)  NOT NULL UNIQUE,
+    expires_at  TIMESTAMP    NOT NULL,
+    used        BOOLEAN      NOT NULL DEFAULT FALSE,
+    created_at  TIMESTAMP    NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_prt_token ON password_reset_tokens(token);

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

@@ -0,0 +1,11 @@
+CREATE TABLE document_versions (
+    id            UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+    document_id   UUID         NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    saved_at      TIMESTAMP    NOT NULL DEFAULT now(),
+    editor_id     UUID         REFERENCES users(id) ON DELETE SET NULL,
+    editor_name   VARCHAR(200) NOT NULL,
+    snapshot      JSONB        NOT NULL,
+    changed_fields JSONB       NOT NULL DEFAULT '[]'
+);
+
+CREATE INDEX ON document_versions (document_id, saved_at DESC);

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

@@ -0,0 +1,86 @@
+package org.raddatz.familienarchiv.controller;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.config.SecurityConfig;
+import org.raddatz.familienarchiv.model.Document;
+import org.raddatz.familienarchiv.security.PermissionAspect;
+import org.raddatz.familienarchiv.service.CustomUserDetailsService;
+import org.raddatz.familienarchiv.service.DocumentService;
+import org.raddatz.familienarchiv.service.DocumentVersionService;
+import org.raddatz.familienarchiv.service.MassImportService;
+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 static org.mockito.ArgumentMatchers.anyList;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@WebMvcTest(AdminController.class)
+@Import({SecurityConfig.class, PermissionAspect.class, AopAutoConfiguration.class})
+class AdminControllerTest {
+
+    @Autowired MockMvc mockMvc;
+
+    @MockitoBean MassImportService massImportService;
+    @MockitoBean DocumentService documentService;
+    @MockitoBean DocumentVersionService documentVersionService;
+    @MockitoBean CustomUserDetailsService customUserDetailsService;
+
+    @Test
+    void backfillVersions_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(post("/api/admin/backfill-versions"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(roles = "USER")
+    void backfillVersions_returns403_whenNotAdmin() throws Exception {
+        mockMvc.perform(post("/api/admin/backfill-versions"))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "ADMIN")
+    void backfillVersions_returns200_withCount_whenAdmin() throws Exception {
+        when(documentService.getDocumentsWithoutVersions()).thenReturn(List.of(Document.builder().build()));
+        when(documentVersionService.backfillMissingVersions(anyList())).thenReturn(1);
+
+        mockMvc.perform(post("/api/admin/backfill-versions"))
+                .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

@@ -0,0 +1,205 @@
+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.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;
+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.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.delete;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@WebMvcTest(AnnotationController.class)
+@Import({SecurityConfig.class, PermissionAspect.class, AopAutoConfiguration.class})
+class AnnotationControllerTest {
+
+    @Autowired MockMvc mockMvc;
+
+    @MockitoBean AnnotationService annotationService;
+    @MockitoBean DocumentService documentService;
+    @MockitoBean UserService userService;
+    @MockitoBean CustomUserDetailsService customUserDetailsService;
+
+    private static final String ANNOTATION_JSON =
+            "{\"pageNumber\":1,\"x\":0.1,\"y\":0.1,\"width\":0.2,\"height\":0.2,\"color\":\"#ff0000\"}";
+
+    // ─── GET /api/documents/{documentId}/annotations ──────────────────────────
+
+    @Test
+    void listAnnotations_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/documents/" + UUID.randomUUID() + "/annotations"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void listAnnotations_returns200_whenAuthenticated() throws Exception {
+        when(annotationService.listAnnotations(any())).thenReturn(List.of());
+
+        mockMvc.perform(get("/api/documents/" + UUID.randomUUID() + "/annotations"))
+                .andExpect(status().isOk());
+    }
+
+    // ─── POST /api/documents/{documentId}/annotations ─────────────────────────
+
+    @Test
+    void createAnnotation_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(post("/api/documents/" + UUID.randomUUID() + "/annotations")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(ANNOTATION_JSON))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void createAnnotation_returns403_whenMissingAnnotatePermission() throws Exception {
+        mockMvc.perform(post("/api/documents/" + UUID.randomUUID() + "/annotations")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(ANNOTATION_JSON))
+                .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 {
+        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())
+                .andExpect(jsonPath("$.pageNumber").value(1));
+    }
+
+    @Test
+    @WithMockUser(authorities = "ANNOTATE_ALL")
+    void createAnnotation_returns409_whenOverlap() throws Exception {
+        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")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(ANNOTATION_JSON))
+                .andExpect(status().isConflict());
+    }
+
+    // ─── DELETE /api/documents/{documentId}/annotations/{annotationId} ─────────
+
+    @Test
+    void deleteAnnotation_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(delete("/api/documents/" + UUID.randomUUID() + "/annotations/" + UUID.randomUUID()))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void deleteAnnotation_returns403_whenMissingAnnotatePermission() throws Exception {
+        mockMvc.perform(delete("/api/documents/" + UUID.randomUUID() + "/annotations/" + UUID.randomUUID()))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "ANNOTATE_ALL")
+    void deleteAnnotation_returns204_whenHasAnnotatePermission() throws Exception {
+        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

@@ -0,0 +1,308 @@
+package org.raddatz.familienarchiv.controller;
+
+import org.junit.jupiter.api.Test;
+import org.raddatz.familienarchiv.config.SecurityConfig;
+import org.raddatz.familienarchiv.model.DocumentComment;
+import org.raddatz.familienarchiv.security.PermissionAspect;
+import org.raddatz.familienarchiv.service.CommentService;
+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.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.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.delete;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.patch;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@WebMvcTest(CommentController.class)
+@Import({SecurityConfig.class, PermissionAspect.class, AopAutoConfiguration.class})
+class CommentControllerTest {
+
+    @Autowired MockMvc mockMvc;
+
+    @MockitoBean CommentService commentService;
+    @MockitoBean UserService userService;
+    @MockitoBean CustomUserDetailsService customUserDetailsService;
+
+    private static final String COMMENT_JSON = "{\"content\":\"Test comment\"}";
+    private static final UUID DOC_ID = UUID.randomUUID();
+    private static final UUID ANN_ID = UUID.randomUUID();
+    private static final UUID COMMENT_ID = UUID.randomUUID();
+
+    // ─── GET /api/documents/{documentId}/comments ─────────────────────────────
+
+    @Test
+    void getDocumentComments_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/documents/" + DOC_ID + "/comments"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getDocumentComments_returns200_whenAuthenticated() throws Exception {
+        when(commentService.getCommentsForDocument(any())).thenReturn(List.of());
+        mockMvc.perform(get("/api/documents/" + DOC_ID + "/comments"))
+                .andExpect(status().isOk());
+    }
+
+    // ─── POST /api/documents/{documentId}/comments ────────────────────────────
+
+    @Test
+    void postDocumentComment_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void postDocumentComment_returns403_whenMissingPermission() throws Exception {
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "ANNOTATE_ALL")
+    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(), any())).thenReturn(saved);
+
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isCreated())
+                .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
+    void replyToComment_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/comments/" + COMMENT_ID + "/replies")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(authorities = "ANNOTATE_ALL")
+    void replyToComment_returns201_whenHasPermission() 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))
+                .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))
+                .andExpect(status().isCreated());
+    }
+
+    // ─── PATCH /api/documents/{documentId}/comments/{commentId} ──────────────
+
+    @Test
+    void editComment_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(patch("/api/documents/" + DOC_ID + "/comments/" + COMMENT_ID)
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser(authorities = "ANNOTATE_ALL")
+    void editComment_returns200_whenHasPermission() 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());
+    }
+
+    // ─── DELETE /api/documents/{documentId}/comments/{commentId} ─────────────
+
+    @Test
+    void deleteComment_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(delete("/api/documents/" + DOC_ID + "/comments/" + COMMENT_ID))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void deleteComment_returns204_whenAuthenticated() throws Exception {
+        mockMvc.perform(delete("/api/documents/" + DOC_ID + "/comments/" + COMMENT_ID))
+                .andExpect(status().isNoContent());
+    }
+
+    // ─── GET /api/documents/{documentId}/annotations/{annId}/comments ─────────
+
+    @Test
+    void getAnnotationComments_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/documents/" + DOC_ID + "/annotations/" + ANN_ID + "/comments"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getAnnotationComments_returns200_whenAuthenticated() throws Exception {
+        when(commentService.getCommentsForAnnotation(any())).thenReturn(List.of());
+        mockMvc.perform(get("/api/documents/" + DOC_ID + "/annotations/" + ANN_ID + "/comments"))
+                .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
+    @WithMockUser
+    void postAnnotationComment_returns403_whenMissingPermission() throws Exception {
+        mockMvc.perform(post("/api/documents/" + DOC_ID + "/annotations/" + ANN_ID + "/comments")
+                        .contentType(MediaType.APPLICATION_JSON).content(COMMENT_JSON))
+                .andExpect(status().isForbidden());
+    }
+
+    @Test
+    @WithMockUser(authorities = "ANNOTATE_ALL")
+    void postAnnotationComment_returns201_whenHasPermission() 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))
+                .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))
+                .andExpect(status().isCreated());
+    }
+
+    // ─── POST /api/documents/{documentId}/annotations/{annId}/comments/{commentId}/replies ─
+
+    @Test
+    @WithMockUser(authorities = "ANNOTATE_ALL")
+    void replyToAnnotationComment_returns201_whenHasPermission() 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());
+    }
+
+    @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

@@ -1,10 +1,15 @@
 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;
 import org.raddatz.familienarchiv.service.DocumentService;
+import org.raddatz.familienarchiv.service.DocumentVersionService;
 import org.raddatz.familienarchiv.service.FileService;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
@@ -15,13 +20,20 @@ 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.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;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
 @WebMvcTest(DocumentController.class)
@@ -31,6 +43,7 @@ class DocumentControllerTest {
     @Autowired MockMvc mockMvc;
 
     @MockitoBean DocumentService documentService;
+    @MockitoBean DocumentVersionService documentVersionService;
     @MockitoBean FileService fileService;
     @MockitoBean CustomUserDetailsService customUserDetailsService;
 
@@ -45,13 +58,32 @@ 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()))
                 .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(), eq(DocumentStatus.REVIEWED)))
+                .thenReturn(Collections.emptyList());
+
+        mockMvc.perform(get("/api/documents/search").param("status", "REVIEWED"))
+                .andExpect(status().isOk());
+
+        verify(documentService).searchDocuments(any(), any(), any(), any(), any(), any(), eq(DocumentStatus.REVIEWED));
+    }
+
+    @Test
+    @WithMockUser
+    void search_withInvalidStatus_returns400() throws Exception {
+        mockMvc.perform(get("/api/documents/search").param("status", "INVALID"))
+                .andExpect(status().isBadRequest());
+    }
+
     // ─── POST /api/documents ─────────────────────────────────────────────────
 
     @Test
@@ -113,4 +145,340 @@ class DocumentControllerTest {
                         .with(req -> { req.setMethod("PUT"); return req; }))
                 .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
+    void getVersions_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/documents/" + UUID.randomUUID() + "/versions"))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getVersions_returns200_whenAuthenticated() throws Exception {
+        UUID docId = UUID.randomUUID();
+        DocumentVersionSummary summary = new DocumentVersionSummary(
+                UUID.randomUUID(), LocalDateTime.now(), "Emma Müller", List.of("title"));
+        when(documentVersionService.getSummaries(docId)).thenReturn(List.of(summary));
+
+        mockMvc.perform(get("/api/documents/" + docId + "/versions"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$[0].editorName").value("Emma Müller"));
+    }
+
+    // ─── GET /api/documents/{id}/versions/{versionId} ────────────────────────
+
+    @Test
+    void getVersion_returns401_whenUnauthenticated() throws Exception {
+        mockMvc.perform(get("/api/documents/" + UUID.randomUUID() + "/versions/" + UUID.randomUUID()))
+                .andExpect(status().isUnauthorized());
+    }
+
+    @Test
+    @WithMockUser
+    void getVersion_returns200_whenAuthenticated() throws Exception {
+        UUID docId = UUID.randomUUID();
+        UUID versionId = UUID.randomUUID();
+        DocumentVersion version = DocumentVersion.builder()
+                .id(versionId).documentId(docId).savedAt(LocalDateTime.now())
+                .editorName("Otto").snapshot("{\"title\":\"Brief\"}").changedFields("[]").build();
+        when(documentVersionService.getVersion(docId, versionId)).thenReturn(version);
+
+        mockMvc.perform(get("/api/documents/" + docId + "/versions/" + versionId))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.editorName").value("Otto"));
+    }
 }

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,7 @@ 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.security.PermissionAspect;
 import org.raddatz.familienarchiv.service.CustomUserDetailsService;
 import org.raddatz.familienarchiv.service.DocumentService;
@@ -11,15 +12,22 @@ 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.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 +40,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 +165,232 @@ 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());
+    }
 }

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/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"));
+    }
+}