chore: add transactions

Author: chrootlogin

README.md

@@ -28,6 +28,8 @@ Warum ORM? -> Warum JPA/Hibernate? -> Warum Flyway-Migrationen? -> Wie arbeitet
 
 Das Starterprojekt bleibt dabei bewusst unvollständig. Die Studierenden müssen zentrale Datenbanklogik wie Pflichtfelder, Constraints und Repository-Entscheide selbst entwickeln und begründen. Bereits gelaufene Flyway-Migrationen werden nicht nachträglich angepasst; Verbesserungen entstehen als neue Migrationen.
 
+Ab Block 3 ergänzt `db-2-app` ein Checkpoint-System für Quereinstieg, Nacharbeit und Lösungseinsicht. Der normale Unterricht startet weiterhin beim Starter. Bei Bedarf erzeugt `./course-state create block-3-start ...` eine separate Arbeitskopie mit dem passenden Einstiegspunkt; `block-3-complete` enthält die sichtbare Lösung mit Transaktionsworkflow, Events und Optimistic Locking.
+
 ## Leitfallstudie
 
 Alle Materialien arbeiten mit einem **Ticket-System für internen Support**. Die Fallstudie ist klein genug für Unterrichtslektionen und reich genug für typische Datenbankentwicklungsfragen:

docs/5_transactions_applications/0_intro.md

@@ -1,5 +1,268 @@
 # Transaktionen und Datenkonsistenz in Anwendungen
 
-Dieser Block wird Transaktionsgrenzen aus Anwendungssicht behandeln. Themen sind `@Transactional`, Commit, Rollback, fachliche Invarianten, externe Seiteneffekte und Optimistic Locking.
+Ein Ticket wird in einer Anwendung selten als einzelne Tabellenzeile behandelt. Wenn ein neues Ticket entsteht, braucht es oft zusätzlich einen ersten Kommentar, einen Ereigniseintrag und später einen Statuswechsel. Aus Sicht der Benutzerin ist das ein einziger fachlicher Vorgang. Aus Sicht der Datenbank sind es mehrere `INSERT`- und `UPDATE`-Anweisungen.
 
-Die inhaltliche Ausarbeitung folgt später.
+Genau an dieser Stelle werden Transaktionen im Anwendungscode wichtig. Eine Transaktion beantwortet nicht nur die Frage, ob PostgreSQL `COMMIT` oder `ROLLBACK` ausführt. Sie beantwortet vor allem die fachliche Frage: Welche Änderungen gehören so eng zusammen, dass sie nur gemeinsam dauerhaft gespeichert werden dürfen?
+
+In Block 2 hast du `db-2-app` als Starterprojekt kennengelernt. Die Anwendung konnte Tickets lesen und erstellen. Für Block 3 bleibt der normale Lernpfad gleich: Du startest beim Starter und entwickelst weiter. Falls du mitten im Modul einsteigst oder eine Lösung anschauen musst, kannst du einen Checkpoint erzeugen:
+
+```bash
+cd db-2-app
+./course-state create block-3-start ../work/db-2-app-block-3
+./course-state create block-3-complete ../work/db-2-app-block-3-loesung
+```
+
+Der Checkpoint ist eine normale Arbeitskopie. Er ersetzt nicht den Unterrichtsweg, sondern macht definierte Zustände reproduzierbar.
+
+:::{important} Lernziele
+Nach diesem Block kannst du:
+
+- eine fachliche Transaktionsgrenze im Service-Layer begründen.
+- `@Transactional` als Werkzeug für deklarative Transaktionen in Spring einordnen.
+- erklären, wann eine Service-Methode committet oder zurückgerollt wird.
+- Ticket, Kommentar und Event als gemeinsamen Datenbankvorgang modellieren.
+- Datenbanktransaktionen von externen Seiteneffekten wie E-Mail oder HTTP Calls abgrenzen.
+- Optimistic Locking als Grundidee für gleichzeitige Bearbeitung erklären.
+- einen fehlerhaften Transaktionsablauf im Code Review erkennen.
+:::
+
+## Warum Transaktionen in der Anwendung?
+
+PostgreSQL kennt Transaktionen seit DB-1: Änderungen werden entweder dauerhaft gemacht oder verworfen. In DB-2 interessiert uns, wo diese Entscheidung im Anwendungscode liegt.
+
+Betrachte einen einfachen Ticket-Workflow:
+
+1. Ein Ticket wird erstellt.
+2. Ein erster Kommentar wird gespeichert.
+3. Ein Event `ticket_created` wird in den Verlauf geschrieben.
+
+Wenn Schritt 2 oder 3 fehlschlägt, darf nicht einfach nur das Ticket übrig bleiben. Sonst zeigt die Anwendung ein Ticket ohne Verlauf oder ohne Startkommentar. Das ist technisch möglich, aber fachlich unvollständig.
+
+```{mermaid}
+flowchart LR
+    Request["POST /api/tickets"]
+    Ticket["tickets<br/>neue Zeile"]
+    Comment["ticket_comments<br/>optional erster Kommentar"]
+    Event["ticket_events<br/>ticket_created"]
+    Commit["COMMIT"]
+    Rollback["ROLLBACK bei Fehler"]
+
+    Request --> Ticket --> Comment --> Event --> Commit
+    Ticket -. Fehler .-> Rollback
+    Comment -. Fehler .-> Rollback
+    Event -. Fehler .-> Rollback
+```
+
+Eine gute Transaktionsgrenze schützt den fachlichen Zusammenhang. Sie ist deshalb meistens nicht die Repository-Methode und nicht der Controller, sondern die Service-Methode, die den Ablauf koordiniert.
+
+## `@Transactional` im Service-Layer
+
+Spring unterstützt deklarative Transaktionen mit `@Transactional`. Die Annotation wird typischerweise durch einen Spring-Proxy ausgewertet: Beim Eintritt in die Methode wird eine Transaktion geöffnet oder wiederverwendet, am Ende wird bei normalem Rücksprung committet und bei passenden Exceptions zurückgerollt {cite}`spring_framework_transaction_reference`.
+
+Im Kursprojekt liegt die Grenze bewusst im Service:
+
+```java
+@Transactional
+TicketResponse createTicket(CreateTicketRequest request) {
+    TicketEntity savedTicket = persistTicketWorkflow(request);
+    return ticketMapper.toResponse(savedTicket);
+}
+```
+
+Die Schichten haben dabei unterschiedliche Rollen:
+
+| Schicht | Rolle im Transaktionskontext |
+| --- | --- |
+| Controller | HTTP-Daten entgegennehmen, validieren und an den Service delegieren |
+| Service | fachlichen Ablauf und Transaktionsgrenze festlegen |
+| Repository | einzelne Datenbankoperationen kapseln |
+| PostgreSQL | Constraints, Fremdschlüssel und dauerhafte Speicherung erzwingen |
+
+Der Service ist der passende Ort, weil er weiss, welche Schritte fachlich zusammengehören. Das Repository weiss nur, wie eine Entity gespeichert wird. Der Controller sollte nicht entscheiden, welche Datenbankänderungen atomar sein müssen.
+
+```{mermaid}
+sequenceDiagram
+    autonumber
+    participant C as TicketController
+    participant S as TicketService
+    participant T as tickets
+    participant K as ticket_comments
+    participant E as ticket_events
+
+    C->>S: createTicket(request)
+    Note over S: @Transactional beginnt
+    S->>T: Ticket speichern
+    S->>K: Kommentar speichern
+    S->>E: Event speichern
+    Note over S: Methode endet ohne Fehler
+    S-->>C: TicketResponse
+    Note over S,E: COMMIT
+```
+
+## Commit und Rollback lesen
+
+In Spring gilt als Grundregel: Eine `RuntimeException` oder ein `Error` löst bei `@Transactional` standardmässig ein Rollback aus. Checked Exceptions werden nicht automatisch gleich behandelt, wenn nichts anderes konfiguriert ist {cite}`spring_framework_transaction_reference`.
+
+Für den Unterricht reicht diese Faustregel:
+
+- Wenn die Methode normal endet, wird committet.
+- Wenn eine unbehandelte Runtime Exception aus der Methode herausläuft, wird zurückgerollt.
+- Wenn ein Fehler abgefangen und verschluckt wird, sieht Spring am Methodenende keinen Rollback-Grund.
+
+Das ist der Grund, warum Fehlerbehandlung nicht nur Stilfrage ist. Eine Service-Methode, die einen Fehler abfängt, loggt und trotzdem normal zurückkehrt, kann einen unvollständigen Vorgang committen.
+
+```java
+@Transactional
+void falsch() {
+    ticketRepository.save(ticket);
+    try {
+        eventRepository.save(event);
+    } catch (RuntimeException ex) {
+        // Problem: Methode laeuft danach normal weiter.
+    }
+}
+```
+
+Besser ist, den Fehler entweder bewusst weiterzugeben oder eine fachliche Alternative zu implementieren, die keinen halben Zustand hinterlässt.
+
+## Fachliche Invarianten
+
+Eine Invariante ist eine Regel, die nach jedem erfolgreichen Vorgang gelten muss. Im Ticket-System können solche Regeln sein:
+
+- Ein neu erstelltes Ticket hat einen gültigen Status.
+- Ein Ticket mit Startkommentar hat einen Kommentar-Eintrag, der auf das Ticket zeigt.
+- Jeder Statuswechsel erzeugt ein Event.
+- Ein geschlossenes Ticket wird in diesem einfachen Modell nicht wieder geöffnet.
+
+Manche Regeln gehören in PostgreSQL:
+
+```sql
+ALTER TABLE app_starter.tickets
+    ADD CONSTRAINT tickets_status_check
+    CHECK (status IN ('open', 'waiting', 'closed'));
+```
+
+Andere Regeln brauchen Service-Logik:
+
+```java
+private void assertStatusTransition(String oldStatus, String newStatus) {
+    if ("closed".equals(oldStatus)) {
+        throw new ResponseStatusException(
+            HttpStatus.BAD_REQUEST,
+            "Geschlossene Tickets werden nicht wieder geoeffnet"
+        );
+    }
+}
+```
+
+Beides ergänzt sich. PostgreSQL schützt zentrale Datenregeln unabhängig vom Schreibpfad. Der Service schützt fachliche Abläufe, die mehr Kontext brauchen als eine einzelne Spalte.
+
+## Externe Seiteneffekte
+
+Eine Datenbanktransaktion kann Datenbankänderungen zurückrollen. Sie kann aber keine bereits gesendete E-Mail zurückholen, keinen HTTP Call ungeschehen machen und keine Message aus einer externen Queue entfernen.
+
+Riskant ist deshalb ein Ablauf wie:
+
+```text
+Transaktion beginnt
+    Ticket speichern
+    E-Mail senden
+    Event speichern schlaegt fehl
+Rollback
+```
+
+Nach dem Rollback existiert das Ticket nicht, aber die E-Mail wurde schon verschickt. Das ist kein Fehler von PostgreSQL. Es ist eine falsch gewählte Grenze zwischen Datenbanktransaktion und Systemprozess.
+
+Für Block 3 genügt die Grundentscheidung:
+
+- Datenbankänderungen, die fachlich zusammengehören, liegen in einer kurzen Transaktion.
+- Externe Effekte werden bewusst danach ausgelöst oder in einem eigenen Muster behandelt.
+- Im Code Review wird geprüft, ob externe Effekte mitten in der Transaktion stehen.
+
+Wir vertiefen hier keine Event-Architektur. Entscheidend ist, dass du die Grenze erkennst.
+
+## Optimistic Locking
+
+Nebenläufigkeit wird sichtbar, wenn zwei Personen dasselbe Ticket bearbeiten. Beide lesen den Status `open`. Person A setzt auf `waiting`, Person B setzt fast gleichzeitig auf `closed`. Ohne Schutz kann die spätere Speicherung die frühere Änderung überschreiben.
+
+Optimistic Locking löst dieses Problem mit einer Versionsspalte. Die Entity erhält ein Feld mit `@Version`; Hibernate/JPA nutzt dieses Feld, um beim Speichern zu prüfen, ob der gelesene Stand noch aktuell ist {cite}`hibernate_orm_user_guide`.
+
+```java
+@Version
+@Column(name = "version")
+private Long version;
+```
+
+Die Datenbankmigration ergänzt die passende Spalte:
+
+```sql
+ALTER TABLE app_starter.tickets
+    ADD COLUMN version BIGINT NOT NULL DEFAULT 0;
+```
+
+Die Idee ist bewusst einfach:
+
+```{mermaid}
+sequenceDiagram
+    autonumber
+    participant A as Supporter A
+    participant B as Supporter B
+    participant DB as PostgreSQL
+
+    A->>DB: Ticket lesen, version = 0
+    B->>DB: Ticket lesen, version = 0
+    A->>DB: Status waiting speichern, version 0 -> 1
+    B->>DB: Status closed mit version 0 speichern
+    DB-->>B: Konflikt, Stand ist veraltet
+```
+
+Optimistic Locking verhindert nicht, dass zwei Personen gleichzeitig arbeiten. Es verhindert, dass eine Anwendung unbemerkt auf veraltetem Stand speichert. Die fachliche Reaktion bleibt Aufgabe der Anwendung: neu laden, Konflikt melden oder Benutzerin entscheiden lassen.
+
+## Checkpoint-System für diesen Block
+
+Das Checkpoint-System ist bewusst nicht Git-basiert. Es verwendet normale Dateien in Overlays:
+
+```text
+db-2-app/course/
+├── states.yml
+└── overlays/
+    ├── block-2-complete/
+    └── block-3-complete/
+```
+
+Die Zustände bauen aufeinander auf:
+
+| Zustand | Verwendung |
+| --- | --- |
+| `block-2-start` | Normaler Starter für Block 2 |
+| `block-2-complete` | Lösung der V2-Migration |
+| `block-3-start` | Einstieg in Block 3 |
+| `block-3-complete` | Lösung mit Transaktionsworkflow |
+
+Für den normalen Unterricht beginnst du im Starter. Für Quereinstieg oder Lösungseinsicht erzeugst du eine Kopie:
+
+```bash
+./course-state create block-3-start ../work/db-2-app-block-3
+```
+
+Dozierende können alle definierten Zustände prüfen:
+
+```bash
+./course-state validate --skip-slow
+```
+
+Ohne `--skip-slow` werden auch Testcontainers-Tests ausgeführt, sofern Docker oder Podman verfügbar ist.
+
+## Review-Fragen für Block 3
+
+Beim Lesen eines Transaktionsablaufs helfen diese Fragen:
+
+- Welcher fachliche Vorgang wird geschützt?
+- Beginnt und endet die Transaktion an der richtigen Stelle?
+- Welche Tabellenänderungen müssen gemeinsam committen?
+- Welche Exception würde ein Rollback auslösen?
+- Werden Fehler versehentlich abgefangen?
+- Gibt es externe Seiteneffekte innerhalb der Transaktion?
+- Braucht der Vorgang Schutz gegen gleichzeitige Bearbeitung?
+
+Eine gute Antwort nennt nicht nur `@Transactional`. Sie begründet, warum genau diese Grenze den fachlichen Zustand schützt.

docs/references.bib

@@ -31,6 +31,15 @@ @misc{spring_data_jpa_reference
   note = {Accessed on: 2026-04-23}
 }
 
+@misc{spring_framework_transaction_reference,
+  author = {{VMware, Inc.}},
+  title = {Using @Transactional},
+  journal = {Spring Framework Reference Documentation},
+  year = {2026},
+  url = {https://docs.spring.io/spring-framework/reference/7.0/data-access/transaction/declarative/annotations.html},
+  note = {Accessed on: 2026-06-04}
+}
+
 @misc{hibernate_orm_user_guide,
   author = {{Hibernate Team}},
   title = {Hibernate ORM User Guide},