werkbaum/backend/README.md

Editor Backend – Grundgerippe

CRUD-Skelett mit Spring Boot 4, Kotlin und API First (OpenAPI 3, YAML). Die vier HTTP-Befehle (GET, POST, PUT, DELETE) sind für die Ressource Document umgesetzt – bewusst noch ohne Autorisierung, aber mit vorbereiteten Erweiterungspunkten für Live-Editing, Autorisierung und clientseitige Verschlüsselung.

Voraussetzungen

• JDK 21
• Gradle 9 (einmalig gradle wrapper --gradle-version 9.1 ausführen, danach ./gradlew)

Wichtige Kommandos

Kommando	Zweck
./gradlew openApiGenerate	Generiert API-Interfaces + Modelle aus src/main/resources/openapi/api.yaml
./gradlew build	Generierung, Kompilierung, alle Tests, Coverage-Prüfung
./gradlew test	Unit- und Behavior-Tests (Cucumber)
./gradlew jacocoTestReport	Coverage-Report unter build/reports/jacoco/test/html
./gradlew bootRun	Startet das Backend auf Port 8080

API First – Ablauf

1. Vertrag ändern: src/main/resources/openapi/api.yaml
2. ./gradlew openApiGenerate → erzeugt DocumentsApi (Interface) und Modelle nach build/generated/openapi (Pakete de.werkbaum.generated.*)
3. DocumentsController implementiert das Interface mit skipDefaultInterface=true: Weicht die Implementierung vom Vertrag ab, bricht der Build – Spezifikation und Code können nicht auseinanderlaufen.

Generierter Code wird nicht eingecheckt und zählt nicht zur Code Coverage.

Teststrategie

• Behavior-Tests (Cucumber, src/test/resources/features/dokumente.feature) testen die API von außen gegen die laufende Anwendung (RANDOM_PORT): Statuscodes, Payloads, Fehlerpfade. Die Szenarien sind auf Deutsch (# language: de) und dienen als lebende Dokumentation.
• Unit-Tests (JUnit 5 + MockK) decken die Geschäftslogik im DocumentService isoliert ab (Versionierung, Zeitstempel per festem Clock, Fehlerfälle).
• Coverage: JaCoCo, Verifikation mit mind. 80 % Line Coverage (jacocoTestCoverageVerification, hängt an check).

Architektur

api/         DocumentsController (implementiert generiertes Interface),
             GlobalExceptionHandler (RFC 9457 ProblemDetail)
service/     DocumentService (Geschäftslogik, Versionierung), Clock-Bean
repository/  DocumentRepository + DocumentHistoryRepository (Interfaces)
persistence/ JPA-Entities, Spring-Data-Repositories und Adapter (H2/Liquibase)
domain/      Document (internes Modell, getrennt vom API-Modell)

Das interne Domänenmodell ist bewusst vom generierten API-Modell getrennt – so können API-Vertrag und Persistenz unabhängig voneinander weiterentwickelt werden.

Historie & Wiederherstellung

• Jede Änderung wird als Snapshot in einer vom Dokument getrennten Historie protokolliert – sie überlebt ein DELETE.
• Zwei Ebenen (D76): Meilensteine sind die nutzersichtbare Historie und bleiben; Sync-Versionen tragen die Diffs des Live-Editings, sind kurzlebig und werden verdichtet. Ohne die Trennung würde die Historie beim getakteten Schreiben zum Transaktionslog – hunderte Volltext-Snapshots eines 40-kB-Dokuments je Sitzung.
  • Meilenstein wird ein Stand bei einer strukturellen Änderung (Anlegen, Löschen, Wiederherstellen, Rückfall), beim Vollersatz per PUT und nach einer Schreibpause. Letzteres ohne Zeitgeber: Die nächste Änderung stellt fest, dass eine Pause war, und befördert die Version davor nachträglich. Der Knopfdruck aus dem Konzept ist derselbe Schalter (milestone = true), sobald PATCH /content ihn durchreicht.
  • Stellschrauben: werkbaum.live-editing.milestone-pause (30 s) und sync-retention (1 h).
• GET /api/v1/documents/{uuid}/history liefert die Meilensteine (älteste zuerst) und immer den jüngsten Stand; Identifier ist die UUID, wie bei GET (der Titel ist nicht eindeutig).
• POST /api/v1/documents/{uuid}/restore stellt ein gelöschtes Dokument unter derselben UUID wieder her (RESTORED, letzter Stand aus dem Tombstone). Mit optionalem Body {"version": n} wird eine bestimmte Version übernommen – bei einem noch lebenden Dokument ist das ein Rückfall (ROLLED_BACK), kein Wiederherstellen: Der Client hatte nie eine Sperre. Ohne Zielversion antwortet der Server bei existierendem Dokument mit 409, eine bereits verdichtete Zielversion mit 404.

Vorbereitete Erweiterungen

Autorisierung

• bearerAuth (JWT) ist in der OpenAPI-Spec als Security Scheme definiert, aber noch auf keine Operation angewendet.
• Später: spring-boot-starter-security + security: [bearerAuth] in der Spec; die Behavior-Tests erhalten dann einen Auth-Schritt („Angenommen ich bin als … angemeldet").

Live-Editing (Konzept: docs/live-editing-proposal.md, Entscheidung: D76)

• Gebaut: das Zeilen-Diff als reine Funktionen (de.werkbaum.diff – Anwenden, Berechnen, Rebasen, Prüfsumme) und die zweistufige Historie.
• Offen: PATCH /content samt Rebase und Idempotenz, der Änderungsfeed per Long Polling, Master-Passwort für GET /documents, Client-Anpassung.
• DocumentUpdateRequest.expectedVersion ist im Vertrag vorgesehen, wird aber noch nicht ausgewertet.

Clientseitige Verschlüsselung

• content ist ein opaker String, den der Server nie interpretiert. Der Wechsel auf Ciphertext erfordert keine API-Änderung; ggf. kommen später Metadaten-Felder (z. B. Schlüssel-ID, Nonce) als eigene Properties hinzu.

Persistenz

• H2 im File-Modus (./data/editor.mv.db) mit MODE=PostgreSQL – läuft im Server-Prozess, keine Datenbank-Installation nötig. Dokumente und Historie überleben einen Neustart.
• Schema per Liquibase im formatierten SQL-Format (src/main/resources/db/changelog/db.changelog-master.sql, kein XML). Neue Änderungen werden als weitere --changeset-Blöcke angehängt; Hibernate validiert nur (ddl-auto: validate).
• Umstieg auf echtes PostgreSQL: im Wesentlichen JDBC-URL/Credentials in der application.yaml tauschen und den Postgres-Treiber als Dependency ergänzen – Schema-Migrationen und Code bleiben unverändert.
• Tests laufen gegen H2 in-memory (src/test/resources/application.yaml), mit demselben Liquibase-Schema.
• Service-Methoden sind @Transactional: Dokument-Änderung und Historieneintrag werden atomar geschrieben.

Hinweise

• Versionsnummern in build.gradle.kts (Spring Boot, OpenAPI Generator, Cucumber, MockK) beim ersten Build ggf. auf den aktuellen Patch-Stand heben.