chore: better checkpoints

Author: chrootlogin

docs/5_transactions_applications/0_intro.md

@@ -4,15 +4,7 @@ Ein Ticket wird in einer Anwendung selten als einzelne Tabellenzeile behandelt.
 
 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.
+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, nutzt du den Checkpoint `block-3-start`. Das Checkpoint-System wird im separaten Abschnitt **Checkpoints** erklärt.
 
 :::{important} Lernziele
 Nach diesem Block kannst du:
@@ -28,7 +20,7 @@ Nach diesem Block kannst du:
 
 ## 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.
+Transaktionen kennst du 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:
 
@@ -218,41 +210,6 @@ sequenceDiagram
 
 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:

docs/checkpoints.md

@@ -0,0 +1,90 @@
+# Checkpoints
+
+Das Kursprojekt `db-2-app` ist der normale Startpunkt für die Arbeit im Unterricht. Du beginnst im Starter, entwickelst Schritt für Schritt weiter und löst die Aufgaben im Verlauf der Blöcke. Checkpoints helfen, wenn du später einsteigst, etwas nacharbeiten möchtest oder eine Lösung kontrolliert anschauen musst.
+
+Ein Checkpoint erzeugt eine normale Arbeitskopie des Projekts in einem frei wählbaren Zielordner. Diese Kopie kannst du öffnen, testen, verändern oder löschen, ohne den Starter zu überschreiben.
+
+## Überblick
+
+Ein Checkpoint beschreibt einen definierten Stand von `db-2-app`. Der erzeugte Zielordner ist ein vollständiges Maven-Projekt mit eigener Projektkopie.
+
+Du verwendest Checkpoints in drei Situationen:
+
+- Du steigst mitten in einen Block ein.
+- Du möchtest einen früheren Stand nacharbeiten.
+- Du möchtest eine Lösung separat anschauen.
+
+Der Starter bleibt dabei unverändert. Für die normale Arbeit im Unterricht brauchst du keinen Checkpoint.
+
+## Grundbefehle
+
+Alle Befehle werden im Ordner `db-2-app` ausgeführt.
+
+Verfügbare Zustände anzeigen:
+
+```bash
+./course-state list
+```
+
+Einen Zustand in einen Zielordner erzeugen:
+
+```bash
+./course-state create <state> <ziel>
+```
+
+Einen einzelnen Zustand materialisieren und testen:
+
+```bash
+./course-state test <state>
+```
+
+Alle definierten Zustände prüfen:
+
+```bash
+./course-state validate --skip-slow
+```
+
+Ohne `--skip-slow` werden auch langsamere Testcontainers-Tests ausgeführt, sofern Docker oder Podman verfügbar ist.
+
+## Aktuelle Zustände
+
+| Zustand | Verwendung |
+| --- | --- |
+| `block-2-start` | Normaler Starter für Block 2 |
+| `block-2-complete` | Lösung der V2-Migration für Ticket-Regeln |
+| `block-3-start` | Einstieg in Block 3 auf Basis des abgeschlossenen Block 2 |
+| `block-3-complete` | Lösung mit Transaktionsworkflow, Kommentaren, Events und Versionierung |
+
+Die Liste wird erweitert, sobald weitere Blöcke vollständige App-Zustände brauchen.
+
+## Praxisbeispiele
+
+Für den normalen Unterricht arbeitest du direkt im Starter weiter. Wenn du aber in Block 3 quer einsteigst, erzeugst du eine eigene Arbeitskopie:
+
+```bash
+./course-state create block-3-start ../work/db-2-app-block-3
+```
+
+Wenn du die Lösung zu Block 3 anschauen möchtest, erzeugst du eine separate Lösungskopie:
+
+```bash
+./course-state create block-3-complete ../work/db-2-app-block-3-loesung
+```
+
+Die Zielordner sind Beispiele. Entscheidend ist, dass der Zielordner ausserhalb von `db-2-app` liegt. Dadurch bleibt der Starter unverändert.
+
+## Zustände prüfen
+
+Wenn du kontrollieren möchtest, ob ein Zustand korrekt erzeugt wird, kannst du ihn testen:
+
+```bash
+./course-state test block-3-start
+```
+
+Alle definierten Zustände prüfst du mit:
+
+```bash
+./course-state validate --skip-slow
+```
+
+Diese Prüfung erzeugt temporäre Arbeitskopien und führt die für den jeweiligen Zustand vorgesehenen Tests aus.

docs/myst.yml

@@ -30,6 +30,8 @@ project:
       file: 7_query_design/0_intro.md
     - title: Performance und typische ORM-Probleme
       file: 8_performance_orm/0_intro.md
+    - title: Checkpoints
+      file: checkpoints.md
   license: CC-BY-SA-4.0
   open_access: true
 site:
@@ -39,6 +41,8 @@ site:
       url: https://database-development.erhardt.consulting/extras/#/slides
     - title: Übungsaufgaben
       url: https://database-development.erhardt.consulting/extras/#/exercises
+    - title: Checkpoints
+      url: /checkpoints
   options:
     logo_text: Database Development
     hide_outline: true