From 02efe738a0290fda2d31bd019d9ae45bf6d8d7b3 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Wed, 10 Jun 2026 07:14:35 +0200
Subject: [PATCH] fix(geschichte): make the documented error-code contract real
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

GESCHICHTE_TYPE_IMMUTABLE and JOURNEY_NOTE_TOO_LONG were declared in
errors.ts, translated, and documented — but never existed in the backend.
update() now rejects a type change with 409 (omitted/same type still pass);
note length is enforced at 2000 with its own code, matching the frontend
maxlength and the i18n message (resolves the #793 discrepancy in favour of
the spec). JOURNEY_ITEM_NOT_IN_JOURNEY is deleted everywhere instead — the
deliberate 404 posture for cross-journey item ids must not leak existence
via a distinct code.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CLAUDE.md                                     |  4 +-
 .../familienarchiv/exception/ErrorCode.java   |  4 ++
 .../geschichte/GeschichteService.java         |  4 ++
 .../journeyitem/JourneyItemService.java       |  7 ++--
 .../geschichte/GeschichteServiceTest.java     | 37 +++++++++++++++++++
 .../journeyitem/JourneyItemServiceTest.java   | 28 +++++++++++---
 docs/ARCHITECTURE.md                          |  2 +-
 frontend/messages/de.json                     |  1 -
 frontend/messages/en.json                     |  1 -
 frontend/messages/es.json                     |  1 -
 frontend/src/lib/shared/errors.ts             |  3 --
 11 files changed, 74 insertions(+), 18 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 2bbc4b24..632213cc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -163,7 +163,7 @@ Input DTOs live flat in the domain package. Response types are the model entitie
 
 → See [CONTRIBUTING.md §Error handling](./CONTRIBUTING.md#error-handling)
 
-**LLM reminder:** use `DomainException.notFound/forbidden/conflict/internal()` from service methods — never throw raw exceptions. When adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) add to `ErrorCode` type in `frontend/src/lib/shared/errors.ts`, (3) add a `case` in `getErrorMessage()`, (4) add i18n keys in `messages/{de,en,es}.json`. Valid error codes include: `TOO_MANY_LOGIN_ATTEMPTS` (returned by `LoginRateLimiter` as HTTP 429 when a brute-force threshold is exceeded); `JOURNEY_ITEM_NOT_IN_JOURNEY`, `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE` (journey/geschichte domain constraints).
+**LLM reminder:** use `DomainException.notFound/forbidden/conflict/internal()` from service methods — never throw raw exceptions. When adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) add to `ErrorCode` type in `frontend/src/lib/shared/errors.ts`, (3) add a `case` in `getErrorMessage()`, (4) add i18n keys in `messages/{de,en,es}.json`. Valid error codes include: `TOO_MANY_LOGIN_ATTEMPTS` (returned by `LoginRateLimiter` as HTTP 429 when a brute-force threshold is exceeded); `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE` (journey/geschichte domain constraints).
 
 ### Security / Permissions
 
@@ -271,7 +271,7 @@ Back button pattern — use the shared `<BackButton>` component from `$lib/share
 
 → See [CONTRIBUTING.md §Error handling](./CONTRIBUTING.md#error-handling)
 
-**LLM reminder:** when adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) add to `ErrorCode` type in `frontend/src/lib/shared/errors.ts`, (3) add a `case` in `getErrorMessage()`, (4) add i18n keys in `messages/{de,en,es}.json`. Valid error codes include: `TOO_MANY_LOGIN_ATTEMPTS` (returned by `LoginRateLimiter` as HTTP 429 when a brute-force threshold is exceeded); `JOURNEY_ITEM_NOT_IN_JOURNEY`, `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE` (journey/geschichte domain constraints).
+**LLM reminder:** when adding a new `ErrorCode`: (1) add to `ErrorCode.java`, (2) add to `ErrorCode` type in `frontend/src/lib/shared/errors.ts`, (3) add a `case` in `getErrorMessage()`, (4) add i18n keys in `messages/{de,en,es}.json`. Valid error codes include: `TOO_MANY_LOGIN_ATTEMPTS` (returned by `LoginRateLimiter` as HTTP 429 when a brute-force threshold is exceeded); `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE` (journey/geschichte domain constraints).
 
 ---
 
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/exception/ErrorCode.java b/backend/src/main/java/org/raddatz/familienarchiv/exception/ErrorCode.java
index e38f8b0b..ba8eac3b 100644
--- a/backend/src/main/java/org/raddatz/familienarchiv/exception/ErrorCode.java
+++ b/backend/src/main/java/org/raddatz/familienarchiv/exception/ErrorCode.java
@@ -132,6 +132,10 @@ public enum ErrorCode {
     JOURNEY_DOCUMENT_ALREADY_ADDED,
     /** The Geschichte is not of type JOURNEY — journey-item operations are not allowed on it. 400 */
     GESCHICHTE_TYPE_MISMATCH,
+    /** The type of an existing Geschichte cannot be changed via PATCH. 409 */
+    GESCHICHTE_TYPE_IMMUTABLE,
+    /** A journey-item note exceeds the maximum length (2000 characters). 400 */
+    JOURNEY_NOTE_TOO_LONG,
 
     // --- Tags ---
     /** A tag with the given ID does not exist. 404 */
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/geschichte/GeschichteService.java b/backend/src/main/java/org/raddatz/familienarchiv/geschichte/GeschichteService.java
index a683b3cc..fb1164ea 100644
--- a/backend/src/main/java/org/raddatz/familienarchiv/geschichte/GeschichteService.java
+++ b/backend/src/main/java/org/raddatz/familienarchiv/geschichte/GeschichteService.java
@@ -155,6 +155,10 @@ public class GeschichteService {
         Geschichte g = geschichteRepository.findById(id)
                 .orElseThrow(() -> DomainException.notFound(
                         ErrorCode.GESCHICHTE_NOT_FOUND, "Geschichte not found: " + id));
+        if (dto.getType() != null && dto.getType() != g.getType()) {
+            throw DomainException.conflict(ErrorCode.GESCHICHTE_TYPE_IMMUTABLE,
+                    "The type of a Geschichte cannot be changed after creation");
+        }
         if (dto.getTitle() != null) {
             requireTitle(dto.getTitle());
             g.setTitle(dto.getTitle().trim());
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemService.java b/backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemService.java
index 2a9b5484..5fe40e7e 100644
--- a/backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemService.java
+++ b/backend/src/main/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemService.java
@@ -30,7 +30,8 @@ public class JourneyItemService {
 
     static final int MAX_ITEMS = 100;
     static final int POSITION_STEP = 10;
-    static final int MAX_NOTE_LENGTH = 5000;
+    // 2000 per the editor spec — frontend maxlength and the i18n error message agree (#793).
+    static final int MAX_NOTE_LENGTH = 2000;
 
     private final JourneyItemRepository journeyItemRepository;
     private final GeschichteQueryService geschichteQueryService;
@@ -63,7 +64,7 @@ public class JourneyItemService {
         }
 
         if (note != null && note.length() > MAX_NOTE_LENGTH) {
-            throw DomainException.badRequest(ErrorCode.VALIDATION_ERROR,
+            throw DomainException.badRequest(ErrorCode.JOURNEY_NOTE_TOO_LONG,
                     "Note exceeds maximum length of " + MAX_NOTE_LENGTH + " characters");
         }
 
@@ -110,7 +111,7 @@ public class JourneyItemService {
         String note = normalizeNote(noteField.orElse(null));
 
         if (note != null && note.length() > MAX_NOTE_LENGTH) {
-            throw DomainException.badRequest(ErrorCode.VALIDATION_ERROR,
+            throw DomainException.badRequest(ErrorCode.JOURNEY_NOTE_TOO_LONG,
                     "Note exceeds maximum length of " + MAX_NOTE_LENGTH + " characters");
         }
 
diff --git a/backend/src/test/java/org/raddatz/familienarchiv/geschichte/GeschichteServiceTest.java b/backend/src/test/java/org/raddatz/familienarchiv/geschichte/GeschichteServiceTest.java
index a8364645..a51408a4 100644
--- a/backend/src/test/java/org/raddatz/familienarchiv/geschichte/GeschichteServiceTest.java
+++ b/backend/src/test/java/org/raddatz/familienarchiv/geschichte/GeschichteServiceTest.java
@@ -476,6 +476,43 @@ class GeschichteServiceTest {
         assertThat(saved.body()).doesNotContain("<script>").contains("<p>ok</p>");
     }
 
+    @Test
+    void update_rejects_type_change_with_409_GESCHICHTE_TYPE_IMMUTABLE() {
+        authenticateAs(writer, Permission.BLOG_WRITE);
+        UUID id = UUID.randomUUID();
+        Geschichte existing = draft(id);
+        existing.setType(GeschichteType.STORY);
+        when(geschichteRepository.findById(id)).thenReturn(Optional.of(existing));
+
+        GeschichteUpdateDTO dto = new GeschichteUpdateDTO();
+        dto.setType(GeschichteType.JOURNEY);
+
+        assertThatThrownBy(() -> geschichteService.update(id, dto))
+                .isInstanceOf(DomainException.class)
+                .extracting("code")
+                .isEqualTo(ErrorCode.GESCHICHTE_TYPE_IMMUTABLE);
+    }
+
+    @Test
+    void update_accepts_dto_carrying_the_unchanged_type() {
+        authenticateAs(writer, Permission.BLOG_WRITE);
+        UUID id = UUID.randomUUID();
+        Geschichte existing = draft(id);
+        existing.setType(GeschichteType.STORY);
+        when(geschichteRepository.findById(id)).thenReturn(Optional.of(existing));
+        when(geschichteRepository.save(any(Geschichte.class)))
+                .thenAnswer(inv -> inv.getArgument(0));
+
+        GeschichteUpdateDTO dto = new GeschichteUpdateDTO();
+        dto.setType(GeschichteType.STORY);
+        dto.setTitle("Unverändert getypt");
+
+        GeschichteView saved = geschichteService.update(id, dto);
+
+        assertThat(saved.type()).isEqualTo(GeschichteType.STORY);
+        assertThat(saved.title()).isEqualTo("Unverändert getypt");
+    }
+
     @Test
     void update_throws_NOT_FOUND_when_geschichte_unknown() {
         authenticateAs(writer, Permission.BLOG_WRITE);
diff --git a/backend/src/test/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemServiceTest.java b/backend/src/test/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemServiceTest.java
index 93808775..63b7be32 100644
--- a/backend/src/test/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemServiceTest.java
+++ b/backend/src/test/java/org/raddatz/familienarchiv/geschichte/journeyitem/JourneyItemServiceTest.java
@@ -203,18 +203,34 @@ class JourneyItemServiceTest {
     }
 
     @Test
-    void append_returns400_when_note_exceeds_5000_chars() {
+    void append_rejects_note_longer_than_2000_chars_with_JOURNEY_NOTE_TOO_LONG() {
+        // 2000 is the spec'd limit (frontend maxlength + i18n message agree) — see #793.
         Geschichte journey = journey(geschichteId);
         when(geschichteQueryService.findById(geschichteId)).thenReturn(Optional.of(journey));
         when(journeyItemRepository.countByGeschichteId(geschichteId)).thenReturn(0L);
 
         JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
-        dto.setNote("x".repeat(5001));
+        dto.setNote("x".repeat(2001));
 
         assertThatThrownBy(() -> journeyItemService.append(geschichteId, dto))
                 .isInstanceOf(DomainException.class)
                 .satisfies(e -> assertThat(((DomainException) e).getCode())
-                        .isEqualTo(ErrorCode.VALIDATION_ERROR));
+                        .isEqualTo(ErrorCode.JOURNEY_NOTE_TOO_LONG));
+    }
+
+    @Test
+    void append_accepts_note_of_exactly_2000_chars() {
+        Geschichte journey = journey(geschichteId);
+        when(geschichteQueryService.findById(geschichteId)).thenReturn(Optional.of(journey));
+        when(journeyItemRepository.countByGeschichteId(geschichteId)).thenReturn(0L);
+        when(journeyItemRepository.findMaxPositionByGeschichteId(geschichteId)).thenReturn(Optional.empty());
+        JourneyItem saved = savedItem(itemId, journey, 10, null, "x".repeat(2000));
+        when(journeyItemRepository.save(any())).thenReturn(saved);
+
+        JourneyItemCreateDTO dto = new JourneyItemCreateDTO();
+        dto.setNote("x".repeat(2000));
+
+        assertThat(journeyItemService.append(geschichteId, dto).note()).hasSize(2000);
     }
 
     @Test
@@ -420,18 +436,18 @@ class JourneyItemServiceTest {
     }
 
     @Test
-    void patch_returns400_when_note_exceeds_5000_chars() {
+    void patch_rejects_note_longer_than_2000_chars_with_JOURNEY_NOTE_TOO_LONG() {
         Geschichte journey = journey(geschichteId);
         JourneyItem item = savedItem(itemId, journey, 10, null, "Old");
         when(journeyItemRepository.findByIdAndGeschichteId(itemId, geschichteId)).thenReturn(Optional.of(item));
 
         JourneyItemUpdateDTO dto = new JourneyItemUpdateDTO();
-        dto.setNote(Optional.of("x".repeat(5001)));
+        dto.setNote(Optional.of("x".repeat(2001)));
 
         assertThatThrownBy(() -> journeyItemService.updateNote(geschichteId, itemId, dto))
                 .isInstanceOf(DomainException.class)
                 .satisfies(e -> assertThat(((DomainException) e).getCode())
-                        .isEqualTo(ErrorCode.VALIDATION_ERROR));
+                        .isEqualTo(ErrorCode.JOURNEY_NOTE_TOO_LONG));
     }
 
     @Test
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index eea5477a..59acfab2 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -61,7 +61,7 @@ Members of the cross-cutting layer have no entity of their own, no user-facing C
 | `audit` | Append-only event store (`audit_log`) for all domain mutations. Feeds the activity feed and Family Pulse dashboard. | Consumed by 5+ domains; no user-facing CRUD of its own |
 | `config` | Infrastructure bean definitions: `MinioConfig`, `AsyncConfig`, `WebConfig` | Framework infra; no business logic |
 | `dashboard` | Stats aggregation for the admin dashboard and Family Pulse widget | Aggregates from 3+ domains; no owned entities |
-| `exception` | `DomainException`, `ErrorCode` enum, `GlobalExceptionHandler` | Framework infra; consumed by every controller and service. Adding a new `ErrorCode` requires matching updates in `frontend/src/lib/shared/errors.ts` and all three `messages/*.json` locale files. Current security-related codes: `CSRF_TOKEN_MISSING` (403 on mutating request without valid `X-XSRF-TOKEN` header), `TOO_MANY_LOGIN_ATTEMPTS` (429 when login rate limit exceeded). Journey/geschichte domain codes: `JOURNEY_ITEM_NOT_IN_JOURNEY`, `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE`. |
+| `exception` | `DomainException`, `ErrorCode` enum, `GlobalExceptionHandler` | Framework infra; consumed by every controller and service. Adding a new `ErrorCode` requires matching updates in `frontend/src/lib/shared/errors.ts` and all three `messages/*.json` locale files. Current security-related codes: `CSRF_TOKEN_MISSING` (403 on mutating request without valid `X-XSRF-TOKEN` header), `TOO_MANY_LOGIN_ATTEMPTS` (429 when login rate limit exceeded). Journey/geschichte domain codes: `JOURNEY_NOTE_TOO_LONG`, `JOURNEY_DOCUMENT_ALREADY_ADDED`, `GESCHICHTE_TYPE_IMMUTABLE`. |
 | `filestorage` | `FileService` — MinIO/S3 upload, download, presigned-URL generation | Generic service; consumed by `document` and `ocr` |
 | `importing` | `CanonicalImportOrchestrator` — async canonical import running four idempotent loaders (`TagTreeImporter` → `PersonRegisterImporter` → `PersonTreeImporter` → `DocumentImporter`) over the normalizer's committed canonical artifacts (`canonical-*.xlsx` + `canonical-persons-tree.json`) | Orchestrates across `person`, `tag`, `document` |
 | `security` | `SecurityConfig`, `Permission` enum, `@RequirePermission` annotation, `PermissionAspect` (AOP) | Framework infra; enforced globally across all controllers |
diff --git a/frontend/messages/de.json b/frontend/messages/de.json
index 7969df2a..e3f4a455 100644
--- a/frontend/messages/de.json
+++ b/frontend/messages/de.json
@@ -1203,7 +1203,6 @@
 	"journey_edit_title_journey": "Lesereise bearbeiten",
 	"journey_publish_disabled_title": "Titel und mindestens ein Eintrag erforderlich",
 	"journey_save_hint_published": "Änderungen werden sofort für alle Leser sichtbar.",
-	"error_journey_item_not_in_journey": "Dieser Eintrag gehört nicht zu dieser Lesereise.",
 	"error_journey_note_too_long": "Die Notiz ist zu lang (maximal 2000 Zeichen).",
 	"error_journey_document_already_added": "Dieser Brief ist bereits in der Lesereise enthalten.",
 	"error_geschichte_type_immutable": "Der Typ einer Geschichte kann nach der Erstellung nicht mehr geändert werden."
diff --git a/frontend/messages/en.json b/frontend/messages/en.json
index b45711e6..7e55ccb2 100644
--- a/frontend/messages/en.json
+++ b/frontend/messages/en.json
@@ -1203,7 +1203,6 @@
 	"journey_edit_title_journey": "Edit reading journey",
 	"journey_publish_disabled_title": "Title and at least one entry required",
 	"journey_save_hint_published": "Changes will be immediately visible to all readers.",
-	"error_journey_item_not_in_journey": "This entry does not belong to this reading journey.",
 	"error_journey_note_too_long": "The note is too long (maximum 2000 characters).",
 	"error_journey_document_already_added": "This letter is already included in the reading journey.",
 	"error_geschichte_type_immutable": "The type of a story cannot be changed after creation."
diff --git a/frontend/messages/es.json b/frontend/messages/es.json
index 9821ad93..7c835331 100644
--- a/frontend/messages/es.json
+++ b/frontend/messages/es.json
@@ -1203,7 +1203,6 @@
 	"journey_edit_title_journey": "Editar viaje de lectura",
 	"journey_publish_disabled_title": "Se requiere título y al menos una entrada",
 	"journey_save_hint_published": "Los cambios serán visibles inmediatamente para todos los lectores.",
-	"error_journey_item_not_in_journey": "Esta entrada no pertenece a este viaje de lectura.",
 	"error_journey_note_too_long": "La nota es demasiado larga (máximo 2000 caracteres).",
 	"error_journey_document_already_added": "Esta carta ya está incluida en el viaje de lectura.",
 	"error_geschichte_type_immutable": "El tipo de una historia no se puede cambiar después de su creación."
diff --git a/frontend/src/lib/shared/errors.ts b/frontend/src/lib/shared/errors.ts
index 203e35fc..3df6a49e 100644
--- a/frontend/src/lib/shared/errors.ts
+++ b/frontend/src/lib/shared/errors.ts
@@ -47,7 +47,6 @@ export type ErrorCode =
 	| 'DUPLICATE_RELATIONSHIP'
 	| 'GESCHICHTE_NOT_FOUND'
 	| 'JOURNEY_ITEM_NOT_FOUND'
-	| 'JOURNEY_ITEM_NOT_IN_JOURNEY'
 	| 'JOURNEY_ITEM_POSITION_CONFLICT'
 	| 'JOURNEY_AT_CAPACITY'
 	| 'JOURNEY_NOTE_TOO_LONG'
@@ -174,8 +173,6 @@ export function getErrorMessage(code: ErrorCode | string | undefined): string {
 			return m.error_geschichte_not_found();
 		case 'JOURNEY_ITEM_NOT_FOUND':
 			return m.error_journey_item_not_found();
-		case 'JOURNEY_ITEM_NOT_IN_JOURNEY':
-			return m.error_journey_item_not_in_journey();
 		case 'JOURNEY_ITEM_POSITION_CONFLICT':
 			return m.error_journey_item_position_conflict();
 		case 'JOURNEY_AT_CAPACITY':