fix: Changelog aus der Zielfassung, blockierende Dateien beiseite

Zwei Fehler beim ersten Probelauf des Update-Skripts.

Der Changelog blieb leer. Das Skript las CHANGELOG.md aus der Arbeitskopie
- also aus dem LAUFENDEN Stand, der die neuen Abschnitte naturgemaess noch
nicht kennt. Jetzt kommt er ueber git show aus der Zielfassung.

Das Umschalten scheiterte an einer unversionierten Datei. Genau das
passiert beim Sprung auf die Fassung, die dieses Skript eingefuehrt hat:
Man holt es sich von Hand, und in der Zielfassung gehoert es dann dazu -
git weigert sich, eine unversionierte Datei zu ueberschreiben. Solche
Dateien werden jetzt nicht weggeworfen, sondern nach .vor-update-<zeit>
beiseite geschoben, danach laeuft das Umschalten durch.

Etappe: 8
Phase: Haertung

.env.example

@@ -16,9 +16,41 @@ DATABASE_URL="postgresql://cockpit:bitte-aendern@localhost:5432/betreuungs_cockp
 AUTH_SECRET=
 # Oeffentliche Basis-URL der Anwendung (ohne abschliessenden Slash).
 AUTH_URL=http://localhost:3000
-# Hinter einem Reverse Proxy (Caddy) auf true setzen.
+# Hinter einem Reverse Proxy auf true setzen.
 AUTH_TRUST_HOST=true
 
+# --- Erreichbarkeit: HIER MUSST DU DICH ENTSCHEIDEN -------------------------
+#
+# Auf welcher Adresse soll die Anwendung erreichbar sein? Das haengt davon
+# ab, WO dein Reverse Proxy laeuft. Waehl genau eine Zeile aus:
+#
+#   Proxy auf DEMSELBEN Server
+#       APP_BIND=127.0.0.1
+#       Von aussen kommt niemand heran, nur der Proxy nebenan. Sicherste
+#       Variante - aber ein Proxy auf einem anderen Rechner erreicht die
+#       Anwendung damit NICHT.
+#
+#   Proxy auf einem ANDEREN Server, privates Netz oder WireGuard vorhanden
+#       APP_BIND=10.0.0.5        <- die Adresse DIESES Servers in dem Netz
+#       Erste Wahl, wenn der Proxy woanders steht.
+#
+#   Proxy auf einem ANDEREN Server, kein privates Netz
+#       APP_BIND=0.0.0.0
+#       Nur zusammen mit einer Firewallregel, die den Port ausschliesslich
+#       fuer die IP des Proxy-Servers oeffnet:
+#           ufw allow from <IP-des-Proxys> to any port 3000 proto tcp
+#           ufw deny 3000/tcp
+#
+# Zwischen Proxy und Anwendung laeuft unverschluesseltes HTTP - die
+# Anwendung beendet kein TLS. Dieser Weg darf nie durchs offene Netz gehen.
+# Einzelheiten: docs/INSTALLATION.md, Schritt 7.
+APP_BIND=127.0.0.1
+APP_PORT=3000
+
+# Die Konsole des mitgelieferten Objektspeichers. Nur noetig, wenn auf dem
+# Server schon etwas auf 9001 laeuft.
+MINIO_KONSOLE_PORT=9001
+
 # --- Anwendungsseitige Feldverschluesselung ---------------------------------
 # AES-256-GCM. 32 Bytes, base64. OHNE DIESEN SCHLUESSEL SIND DIE VERSCHLUESSELTEN
 # FELDER UNWIEDERBRINGLICH VERLOREN - unbedingt getrennt vom Backup sichern!

CHANGELOG.md

@@ -26,6 +26,210 @@ Wiederherstellung*.
 
 _Noch nichts._
 
+## [1.0.5] – 2026-08-22
+
+### Hinzugefügt
+
+- **`scripts/update.sh`** — aktualisiert die Anwendung mit einem Befehl.
+
+  ```bash
+  ./scripts/update.sh              # auf die neueste Fassung
+  ./scripts/update.sh --pruefen    # nur nachsehen, nichts ändern
+  ./scripts/update.sh v1.2.0       # auf eine bestimmte Fassung
+  ```
+
+  Es nimmt die Schritte ab, die man von Hand vergisst: Sicherung
+  anstoßen und bei Misserfolg **abbrechen**, den Changelog zwischen altem
+  und neuem Stand anzeigen, umschalten, neu bauen, warten bis die
+  Anwendung antwortet, **die beiden SQL-Skripte ausführen** und zum
+  Schluss prüfen, ob wirklich die neue Fassung läuft.
+
+  Zwei Eigenschaften, die dabei zählen:
+
+  **Bis zur Rückfrage wird nichts verändert.** Bricht etwas vorher ab —
+  Server nicht erreichbar, falsche Versionsangabe — findest du alles so
+  vor wie zuvor. Kein Halbzustand.
+
+  **Eigene Änderungen an versionierten Dateien blockieren nicht.** Im
+  Betrieb passt man die `docker-compose.yml` an, bis etwas läuft; genau
+  diese Anpassungen sind später oft schon eingearbeitet. Das Skript legt
+  sie vor dem Umschalten mit `git stash` beiseite und sagt, wie man sie
+  zurückholt. Mit `--verwerfen` werden sie stattdessen weggeworfen. Die
+  `.env` bleibt immer unangetastet — sie ist nicht versioniert.
+
+  Schlägt der Bau fehl, nennt das Skript den Weg zurück auf den
+  vorherigen Stand.
+
+### Behoben
+
+- **Der Port der MinIO-Konsole ließ sich nicht ändern.** Er stand fest auf
+  `9001`; lief dort schon etwas, startete der ganze Stapel nicht
+  (`port is already allocated`). Jetzt über `MINIO_KONSOLE_PORT` in der
+  `.env` einstellbar — dieselbe Möglichkeit, die `APP_PORT` schon hatte.
+
+## [1.0.4] – 2026-08-22
+
+### Behoben
+
+- **Die Ersteinrichtung ließ sich nicht abschließen.** Schritt 3 meldete
+  „Bitte prüfe die markierten Felder" — markierte aber keines. Man kam an
+  dieser Stelle nicht weiter.
+
+  Ursache: Das kurze Formular der Ersteinrichtung schickt neun Felder, das
+  vollständige unter *Stammdaten* alle. Beide gehen durch dasselbe Schema,
+  und die optionalen Felder waren zwar `nullable`, aber nicht `optional` —
+  ein Feld, das gar nicht abgeschickt wurde, ist `undefined`, nicht
+  `null`. Beanstandet wurden also zwei Dutzend Felder, die auf dem
+  Bildschirm nie standen.
+
+- **Eine Meldung ohne zugehöriges Feld kann nicht mehr unsichtbar
+  bleiben.** Beanstandet die Prüfung ein Feld, das das Formular gar nicht
+  gesendet hat, sagt die Anwendung das jetzt ausdrücklich und schreibt es
+  ins Serverlog — statt es als Eingabefehler auszugeben, den niemand
+  finden kann. Das ist ein Fehler im Programm, und er soll auch so
+  aussehen.
+
+- **Eine betreute Person ließ sich nicht endgültig löschen.** Beim Löschen
+  setzt Postgres den Verweis im Audit-Log auf NULL (`ON DELETE SET NULL`),
+  und genau dieses UPDATE hat der Unveränderlichkeits-Trigger abgewiesen.
+  Betroffen war damit auch das Leeren des Papierkorbs nach 30 Tagen und
+  das Entfernen des Demofalls.
+
+  Der Trigger erlaubt jetzt genau eine Ausnahme: das Nullen der beiden
+  Fremdschlüssel `betreuteId` und `userId`. Jede andere Änderung bleibt
+  verboten, auch das Setzen eines Fremdschlüssels auf einen **anderen**
+  Wert. Der Nachweis bleibt vollständig — Zeitpunkt, Aktion, Bezeichnung,
+  die verschlüsselte Änderung und die Momentaufnahmen von Name und
+  E-Mail sind unberührt. Es verschwindet nur der Verweis auf einen
+  Datensatz, den es nicht mehr gibt.
+
+  **Beim Update nötig:** das SQL-Skript erneut ausführen, sonst bleibt der
+  alte Trigger stehen.
+
+  ```bash
+  docker compose exec app node node_modules/prisma/build/index.js db execute     --schema prisma/schema.prisma --file prisma/sql/audit-schutz.sql
+  ```
+
+### Geprüft
+
+- Sieben neue Tests (`tests/stammdaten.test.ts`) prüfen genau die
+  Formularinhalte der Ersteinrichtung, dazu das vollständige Formular mit
+  leeren Feldern und die weiterhin verlangten Pflichtangaben.
+- Der Ablauf ist zusätzlich im Browser durchgespielt worden: Anmeldung,
+  zweiter Faktor, Schritt 3, Landung auf dem Dashboard — und die daraus
+  abgeleiteten Pflichtfristen samt Ausschlussfrist für die
+  Aufwandspauschale.
+- Der geänderte Trigger ist gegen eine laufende Datenbank geprüft:
+  Löschen gelingt, Fälschen und Löschen von Einträgen scheitert weiterhin.
+
+## [1.0.3] – 2026-08-22
+
+Keine Änderung am Programm — nur an der Konfigurationsvorlage und der
+Anleitung. Ein Neubau des Abbilds ist nicht nötig.
+
+### Behoben
+
+- **`.env.example` band die Anwendung stillschweigend an `127.0.0.1`.**
+  Der Wert stand dort als fertig ausgefüllte Zeile zwischen lauter anderen
+  fertigen Zeilen. Wer die Datei kopiert hat und seinen Reverse Proxy auf
+  einem **anderen** Server betreibt, kam nicht an die Anwendung heran —
+  und der Fehler sah aus, als läge es am Proxy.
+
+  Jetzt steht dort eine Entscheidung mit drei benannten Fällen statt eines
+  Vorgabewerts. Der sichere Standard bleibt `127.0.0.1`; er wird nur nicht
+  mehr als „schon erledigt" präsentiert.
+
+  Für bestehende Installationen genügt eine Zeile in der `.env`:
+
+  ```bash
+  APP_BIND=10.0.0.5      # Adresse, über die der Proxy diesen Server erreicht
+  docker compose up -d
+  ```
+
+### Geändert
+
+- **`docs/INSTALLATION.md`** nennt `APP_BIND` jetzt schon in Schritt 3, wo
+  die `.env` ausgefüllt wird — nicht erst in Schritt 7, wo der Proxy
+  drankommt. Dazu ein eigener Abschnitt in der Fehlersuche: „Der Proxy
+  erreicht die Anwendung nicht", mit den zwei `curl`-Proben, die den
+  Unterschied zwischen falscher Bindeadresse und Firewall zeigen.
+
+## [1.0.2] – 2026-08-22
+
+### Behoben
+
+- **Die Einrichtung des zweiten Faktors brach mit einem Serverfehler ab**
+  („Application error: a server-side exception has occurred"). Im
+  Serverlog stand `Umgebungsvariable ENC_KEY_V2 fehlt` — obwohl niemand
+  einen zweiten Schlüssel wollte.
+
+  Ursache: `docker-compose.yml` reicht `ENC_KEY_V2` immer an den Behälter
+  durch, mit **leerem Wert**, wenn in der `.env` keiner steht. Die
+  Anwendung erkannte Schlüssel aber am Variablennamen statt am Inhalt,
+  fand also ein leeres `ENC_KEY_V2` und brach ab. Leere
+  Schlüsselvariablen werden jetzt übersprungen.
+
+  Betroffen war jede Stelle, die verschlüsselte Felder schreibt oder
+  liest — also praktisch alles außer der reinen Anmeldung. Die Anmeldung
+  ging durch, weil sie ohne Verschlüsselung auskommt; der Fehler trat
+  deshalb erst auf der nächsten Seite auf.
+
+- **Die Meldung beim Schlüsselwechsel** nennt jetzt, welche Versionen
+  tatsächlich vorhanden sind, und die richtige Reihenfolge: erst den
+  neuen Schlüssel eintragen, dann `ENC_KEY_AKTIV` umstellen.
+
+### Hinzugefügt
+
+- **`scripts/anmeldung-pruefen.mjs`** — beantwortet die Frage, warum eine
+  Anmeldung nicht klappt. Das Formular sagt bewusst nicht, woran es lag,
+  sonst ließe sich daran ablesen, welche Adressen es gibt. Auf dem Server
+  darf man es wissen: Jeder Versuch wird mit Grund protokolliert, und das
+  Skript liest ihn vor — dazu den Zustand des Zugangs, den Stand der
+  Login-Sperre und die eingestellte `AUTH_URL`.
+
+  ```bash
+  docker compose exec app node scripts/anmeldung-pruefen.mjs deine@adresse.de
+  ```
+
+  Es ändert nichts, es liest nur.
+
+### Geprüft
+
+- Sieben neue Tests (`tests/umgebung.test.ts`) decken die
+  Schlüsselauswertung ab, darunter genau die Konstellation aus dem
+  Fehlerbericht: gesetztes `ENC_KEY_V1`, leeres `ENC_KEY_V2`.
+
+## [1.0.1] – 2026-08-22
+
+### Behoben
+
+- **Betriebsskripte fehlten im Docker-Abbild.** Das Verzeichnis `scripts/`
+  wurde beim Bauen nie in die Laufzeitstufe übernommen. `docker compose
+  exec app node scripts/totp-geheimnis.mjs …` endete deshalb mit
+  `Cannot find module`. Betroffen waren alle Skripte, die im laufenden
+  Behälter gedacht sind — auch `wartungsschluessel.mjs` und
+  `schluessel-erzeugen.mjs`.
+
+  Nach dem Update funktioniert der Befehl wie dokumentiert. Wer nicht
+  gleich aktualisieren will, kommt einmalig auch so an das Skript:
+
+  ```bash
+  docker compose cp scripts/totp-geheimnis.mjs app:/app/totp-geheimnis.mjs
+  docker compose exec app node totp-geheimnis.mjs deine@adresse.de
+  ```
+
+### Hinzugefügt
+
+- **`scripts/totp-geheimnis.mjs`** — liest das TOTP-Geheimnis eines Zugangs
+  aus, um denselben Zugang auf einem zweiten Gerät einzurichten (Handy und
+  Tablet, oder ein Ersatzgerät). Die Anwendung zeigt das Geheimnis sonst
+  nur einmal an, beim Einrichten; bisher blieb nur, den zweiten Faktor
+  zurückzusetzen und alle Wiederherstellungscodes neu zu erzeugen.
+
+  Das Skript läuft nur auf dem Server und nur mit Zugriff auf die Datenbank
+  **und** auf `ENC_KEY_V1`. Wer beides hat, kann ohnehin alles lesen — es
+  ist also keine Hintertür, sondern erspart eine unnötige Neueinrichtung.
+
 ## [1.0.0] – 2026-08-22
 
 Erste vollständige Fassung. Alle acht Etappen umgesetzt, alle
@@ -188,5 +392,10 @@ Was davon wann angegangen wird, steht in [`docs/ROADMAP.md`](docs/ROADMAP.md).
 
 ---
 
-[Unveröffentlicht]: https://git.wilde-server.de/florian.wilde/betreuungs-cockpit/compare/v1.0.0...HEAD
+[Unveröffentlicht]: https://git.wilde-server.de/florian.wilde/betreuungs-cockpit/compare/v1.0.5...HEAD
+[1.0.5]: https://git.wilde-server.de/florian.wilde/betreuungs-cockpit/compare/v1.0.4...v1.0.5
+[1.0.4]: https://git.wilde-server.de/florian.wilde/betreuungs-cockpit/compare/v1.0.3...v1.0.4
+[1.0.3]: https://git.wilde-server.de/florian.wilde/betreuungs-cockpit/compare/v1.0.2...v1.0.3
+[1.0.2]: https://git.wilde-server.de/florian.wilde/betreuungs-cockpit/compare/v1.0.1...v1.0.2
+[1.0.1]: https://git.wilde-server.de/florian.wilde/betreuungs-cockpit/compare/v1.0.0...v1.0.1
 [1.0.0]: https://git.wilde-server.de/florian.wilde/betreuungs-cockpit/releases/tag/v1.0.0

Dockerfile

@@ -95,6 +95,17 @@ COPY --from=bau --chown=cockpit:cockpit /app/node_modules/.prisma ./node_modules
 COPY --from=bau --chown=cockpit:cockpit /app/node_modules/@prisma ./node_modules/@prisma
 COPY --from=bau --chown=cockpit:cockpit /app/node_modules/prisma ./node_modules/prisma
 
+# Betriebsskripte, die im laufenden Behaelter gebraucht werden:
+#   totp-geheimnis.mjs      zweites Geraet fuer den Zweitfaktor einrichten
+#   wartungsschluessel.mjs  Schluessel fuer /api/wartung ausrechnen
+#   schluessel-erzeugen.mjs neue Schluessel fuer die Rotation
+#
+# Das ganze Verzeichnis, nicht einzelne Dateien: sonst faellt beim
+# naechsten Betriebsskript wieder auf, dass es fehlt - und zwar erst dann,
+# wenn man es braucht. Die Entwicklungsskripte darin laufen hier mangels
+# Werkzeugen nicht, kosten aber auch nur ein paar Kilobyte.
+COPY --from=bau --chown=cockpit:cockpit /app/scripts ./scripts
+
 # Ablage fuer den Dateitreiber, falls kein Objektspeicher benutzt wird.
 RUN mkdir -p /app/daten/dokumente && chown -R cockpit:cockpit /app/daten
 

README.md

@@ -15,6 +15,7 @@ eines Angehörigen: Fristen, Vorgänge, Belege, Vermögen, Sozialhilfe, Berichte
 ## Inhalt
 
 - [Was die Anwendung kann](#was-die-anwendung-kann)
+- [Die drei Dokumente, die du wirklich brauchst](#die-drei-dokumente-die-du-wirklich-brauchst)
 - [Schnellstart zum Ausprobieren](#schnellstart-zum-ausprobieren)
 - [Produktivbetrieb mit Docker Compose](#produktivbetrieb-mit-docker-compose)
 - [Reverse Proxy](#reverse-proxy)
@@ -46,6 +47,23 @@ eines Angehörigen: Fristen, Vorgänge, Belege, Vermögen, Sozialhilfe, Berichte
 
 ---
 
+## Die drei Dokumente, die du wirklich brauchst
+
+| Wofür | Wo |
+|---|---|
+| **Die Anwendung aufsetzen** — auf einem Server, der Docker und einen Proxy schon hat, mit Kontrolle nach jedem Schritt | [`docs/INSTALLATION.md`](docs/INSTALLATION.md) |
+| **Täglich damit arbeiten** — die zwölf Handgriffe, der Jahresrhythmus, was tun wenn etwas schiefgeht | [`docs/ANLEITUNG.md`](docs/ANLEITUNG.md), in der Anwendung unter `/anleitung` |
+| **Wissen, was sich ändert** — was neu ist, was du vor einem Update beachten musst | [`CHANGELOG.md`](CHANGELOG.md) |
+
+Dazu: [`docs/ROADMAP.md`](docs/ROADMAP.md) für das, was als Nächstes
+kommt, und [`docs/BAUPROTOKOLL.md`](docs/BAUPROTOKOLL.md) für die Frage,
+wie das hier entstanden ist.
+
+Der Rest dieser Datei ist die Kurzfassung für alle, die schon wissen, was
+sie tun.
+
+---
+
 ## Schnellstart zum Ausprobieren
 
 Voraussetzungen: **Node.js ≥ 20.11**, **Docker** und **Git**.
@@ -113,6 +131,10 @@ laufender Antrag beim Bezirk Oberfranken mit acht Nachforderungen.
 
 ## Produktivbetrieb mit Docker Compose
 
+> **Zum ersten Mal?** Nimm die [Schritt-für-Schritt-Anleitung](docs/INSTALLATION.md).
+> Sie fängt beim leeren Server an, hat nach jedem Abschnitt eine Kontrolle
+> und endet mit einer Abnahmeliste. Was hier steht, ist die Kurzfassung.
+
 Das Compose-Setup bringt drei Dienste mit: die Anwendung, PostgreSQL und
 MinIO als S3-kompatiblen Objektspeicher, dazu einen Sicherungsdienst.
 
@@ -155,72 +177,62 @@ existiert.
 ### Aktualisieren
 
 ```bash
-git pull
-docker compose up -d --build
+./scripts/update.sh
 ```
 
-Die Migrationen laufen beim Start des Anwendungsbehälters mit. **Vorher ein
-Backup anstoßen** (siehe unten) — eine Migration lässt sich nicht zurückrollen.
+Das Skript sichert zuerst, zeigt den Changelog zwischen altem und neuem
+Stand, fragt nach, schaltet um, baut neu und führt danach die beiden
+SQL-Skripte aus. Schlägt die Sicherung fehl, wird nicht aktualisiert.
+
+`--pruefen` sieht nur nach, ohne etwas zu ändern. Eigene Änderungen an
+versionierten Dateien werden vor dem Umschalten beiseite gelegt
+(`git stash`), die `.env` bleibt unangetastet.
+
+Einzelheiten und der Weg von Hand: [`docs/INSTALLATION.md`](docs/INSTALLATION.md).
 
 ---
 
 ## Reverse Proxy
 
-Die Anwendung erwartet, dass der Proxy TLS beendet und die echte Client-IP
-weiterreicht. Sie liest `X-Forwarded-For` bzw. `X-Real-IP` für das
-Rate-Limiting am Login und für das Audit-Log (dort nur als Hash).
+Die Anwendung **beendet selbst kein TLS** und bringt keinen Proxy mit. Sie
+horcht standardmäßig auf `127.0.0.1:3000`.
 
-**Caddy**
+**Läuft der Proxy auf demselben Server**, ist damit alles gesagt: Er zeigt
+auf `127.0.0.1:3000`, fertig.
 
-```caddyfile
-cockpit.example.de {
-    encode zstd gzip
-    reverse_proxy 127.0.0.1:3000
+**Läuft er auf einem anderen Server**, setz in der `.env` die Adresse, über
+die er herankommt — am besten die eines privaten Netzes oder eines
+WireGuard-Tunnels:
 
-    # Uploads: Fotos von Behördenschreiben können groß sein.
-    request_body {
-        max_size 30MB
-    }
-}
+```bash
+APP_BIND=10.0.0.5
+APP_PORT=3000
 ```
 
-**nginx**
+`0.0.0.0` nur, wenn eine Firewall den Port ausschließlich für die IP des
+Proxy-Servers öffnet. Zwischen Proxy und Anwendung läuft unverschlüsseltes
+HTTP — dieser Weg darf nie durchs offene Netz gehen.
 
-```nginx
-server {
-    listen 443 ssl http2;
-    server_name cockpit.example.de;
+### Was der Proxy leisten muss
 
-    ssl_certificate     /etc/letsencrypt/live/cockpit.example.de/fullchain.pem;
-    ssl_certificate_key /etc/letsencrypt/live/cockpit.example.de/privkey.pem;
+| Anforderung | Was ohne sie passiert |
+|---|---|
+| TLS beenden | Der Browser lehnt Cookies mit `Secure`-Kennzeichen ab, die Anmeldung schlägt stumm fehl |
+| `Host` durchreichen | Auth.js vergleicht ihn mit `AUTH_URL` und weist die Anmeldung ab |
+| `X-Forwarded-Proto: https` | Die Anwendung baut Adressen mit `http` |
+| `X-Forwarded-For` | Die Login-Sperre zählt alle Zugriffe als denselben Anschluss |
+| Uploads ≥ 30 MB | Fotos mehrseitiger Bescheide werden abgeschnitten |
+| Zeitgrenze ≥ 10 Minuten | Belegmappe, Rechnungslegung und Vollexport brechen ab |
+| Antwort nicht puffern | Der Vollexport kommt als Strom |
 
-    client_max_body_size 30M;
+**Keine eigenen Sicherheitskopfzeilen setzen.** CSP, `X-Frame-Options`,
+`nosniff` und HSTS kommen aus der Anwendung. Die CSP enthält eine Nonce,
+die pro Anfrage neu ist — eine feste CSP aus dem Proxy blockiert die
+eigenen Skripte.
 
-    location / {
-        proxy_pass         http://127.0.0.1:3000;
-        proxy_http_version 1.1;
-        proxy_set_header   Host              $host;
-        proxy_set_header   X-Real-IP         $remote_addr;
-        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
-        proxy_set_header   X-Forwarded-Proto $scheme;
-        proxy_set_header   Upgrade           $http_upgrade;
-        proxy_set_header   Connection        "upgrade";
-    }
-}
-```
-
-**Traefik** (Labels am `app`-Dienst)
-
-```yaml
-labels:
-  - traefik.enable=true
-  - traefik.http.routers.cockpit.rule=Host(`cockpit.example.de`)
-  - traefik.http.routers.cockpit.tls.certresolver=letsencrypt
-  - traefik.http.services.cockpit.loadbalancer.server.port=3000
-```
-
-In allen Fällen muss `AUTH_URL` in der `.env` auf die öffentliche Adresse
-zeigen (`https://cockpit.example.de`), sonst schlägt die Anmeldung fehl.
+**Fertige Konfigurationen** für Caddy, nginx und Traefik, mit Zeitgrenzen
+und den Gegenproben, stehen in
+[`docs/INSTALLATION.md`](docs/INSTALLATION.md), Schritt 7.
 
 ---
 
@@ -479,6 +491,7 @@ npm test                 # Vitest: Fachlogik
 npm run test:e2e         # Playwright: kritische Abläufe
 npm run db:studio        # Prisma Studio
 npm run protokoll        # Bauprotokoll aus der Git-Historie
+npm run version -- patch # Version anheben, Changelog vorbereiten
 ```
 
 Konventionen — verbindlich für alle Beiträge:

docker-compose.yml

@@ -4,10 +4,13 @@
 #
 #   docker compose up -d --build
 #
-# Kein Reverse Proxy in dieser Datei: der ist auf dem Server bereits
-# vorhanden. Die Anwendung horcht nur auf 127.0.0.1:3000 - von aussen
-# erreichbar wird sie ausschliesslich ueber den vorhandenen Proxy, der
-# auch TLS beendet. Siehe README, Abschnitt "Reverse Proxy".
+# Kein Reverse Proxy in dieser Datei: der ist bereits vorhanden. Die
+# Anwendung beendet selbst kein TLS und horcht standardmaessig nur auf
+# 127.0.0.1:3000.
+#
+# Liegt der Proxy auf einem anderen Server, setze APP_BIND in der .env auf
+# die Adresse, ueber die er herankommt - siehe docs/INSTALLATION.md,
+# Schritt 7.
 #
 # Die Datenbank hat bewusst KEINE Portfreigabe. Sie ist nur ueber das
 # interne Docker-Netz erreichbar. Wer mit psql heran muss, geht ueber
@@ -63,7 +66,10 @@ services:
     ports:
       # Nur an die Loopback-Adresse gebunden. Die Konsole erreichst du
       # ueber einen SSH-Tunnel oder ueber deinen vorhandenen Proxy.
-      - '127.0.0.1:9001:9001'
+      #
+      # Laeuft auf dem Server schon etwas auf 9001, weich in der .env aus:
+      #     MINIO_KONSOLE_PORT=9011
+      - '${MINIO_KONSOLE_BIND:-127.0.0.1}:${MINIO_KONSOLE_PORT:-9001}:9001'
     networks: [intern]
 
   app:
@@ -88,7 +94,9 @@ services:
       AUTH_URL: ${AUTH_URL:?AUTH_URL fehlt in der .env}
       AUTH_TRUST_HOST: 'true'
       ENC_KEY_V1: ${ENC_KEY_V1:?ENC_KEY_V1 fehlt in der .env - ohne ihn sind die verschluesselten Felder nicht lesbar}
-      ENC_KEY_V2: ${ENC_KEY_V2:-}
+      # Bleibt leer, solange nicht rotiert wird. Die Anwendung ueberspringt
+      # leere Schluesselvariablen - siehe src/lib/env.ts.
+      # ENC_KEY_V2: ${ENC_KEY_V2:-}
       ENC_KEY_AKTIV: ${ENC_KEY_AKTIV:-1}
       INDEX_KEY: ${INDEX_KEY:?INDEX_KEY fehlt in der .env}
       SESSION_MAX_AGE: ${SESSION_MAX_AGE:-1800}
@@ -111,9 +119,19 @@ services:
       SMTP_FROM: ${SMTP_FROM:-}
       TZ: Europe/Berlin
     ports:
-      # Nur Loopback. Der vorhandene Reverse Proxy auf dem Host reicht
-      # von aussen hierher durch und beendet TLS.
-      - '127.0.0.1:${APP_PORT:-3000}:3000'
+      # Standard ist die Loopback-Adresse: dann erreicht die Anwendung nur
+      # ein Proxy, der auf demselben Rechner laeuft.
+      #
+      # Liegt der Reverse Proxy auf einem ANDEREN Server, muss hier die
+      # Adresse stehen, ueber die er herankommt - am besten die eines
+      # privaten Netzes oder eines WireGuard-Tunnels:
+      #
+      #     APP_BIND=10.0.0.5
+      #
+      # 0.0.0.0 nur setzen, wenn eine Firewall den Port ausschliesslich
+      # fuer die IP des Proxy-Servers oeffnet. Die Anwendung beendet kein
+      # TLS und gehoert nie unverschluesselt ins offene Netz.
+      - '${APP_BIND:-127.0.0.1}:${APP_PORT:-3000}:3000'
     networks: [intern]
     healthcheck:
       test: ['CMD', 'node', '-e', "fetch('http://127.0.0.1:3000/api/gesundheit').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]

docs/ANLEITUNG.md

@@ -0,0 +1,451 @@
+# Bedienungsanleitung
+
+Für dich als ehrenamtlichen Betreuer. Kein Handbuch zum Durchlesen —
+sondern eine Sammlung der Handgriffe, die du tatsächlich brauchst, in der
+Reihenfolge, in der sie im Alltag vorkommen.
+
+> Diese Anwendung ist ein **Arbeits- und Dokumentationswerkzeug**. Sie
+> rechnet Fristen aus und sortiert Unterlagen. Sie erteilt **keine
+> Rechtsberatung** und kennt deinen Einzelfall nicht. Wo ein Paragraph
+> steht, steht daneben der Hinweis, dass er die Rückfrage bei Gericht,
+> Bezirk oder Anwalt nicht ersetzt. Nimm den ernst.
+
+---
+
+## Der Grundgedanke in drei Sätzen
+
+Du trägst einmal ein, was passiert ist — ein Schreiben, ein Besuch, eine
+Überweisung. Die Anwendung merkt sich, wann daraus etwas folgt, und
+erinnert dich rechtzeitig. Am Ende des Betreuungsjahres erzeugt sie aus
+demselben Bestand die Berichte, die Gericht und Bezirk von dir wollen.
+
+Das heißt umgekehrt: **Was du nicht einträgst, steht später nicht im
+Bericht.** Der Aufwand liegt vorn, der Gewinn hinten.
+
+---
+
+## Der erste Tag
+
+Beim allerersten Aufruf führt dich ein Assistent durch drei Schritte.
+
+**Schritt 1 — Dein Zugang.** Name, E-Mail, Passwort. Nimm vier zufällige
+Wörter statt eines kurzen Kunstworts: *Kastanie-Waschbär-Turm-Grün* ist
+leichter zu merken und deutlich schwerer zu knacken. Noch besser ist ein
+Passwortmanager.
+
+**Schritt 2 — Der zweite Faktor.** Installiere eine Authenticator-App —
+**Aegis** (Android) oder **2FAS** (iOS) sind quelloffen und brauchen kein
+Konto. Scanne den Code, tippe die sechs Ziffern ein.
+
+Danach bekommst du **acht Wiederherstellungscodes**. Die sind der einzige
+Weg zurück, wenn dein Handy verloren geht. Druck sie aus und leg sie zu
+deinen Betreuungsunterlagen — **nicht** auf dasselbe Gerät wie die App.
+Sie werden dir nie wieder angezeigt.
+
+**Schritt 3 — Die betreute Person.** Nur das Nötigste. Ein Feld ist dabei
+wichtiger als alle anderen:
+
+> **Das Bestellungsdatum.** Es steht in deiner Bestellungsurkunde. Daraus
+> berechnet die Anwendung dein Betreuungsjahr — und damit, wann
+> Anfangsbericht, Vermögensverzeichnis, Jahresbericht und die
+> Aufwandspauschale fällig sind. Ist es falsch, ist alles falsch.
+
+Alles Weitere trägst du später unter **Stammdaten → Bearbeiten** in Ruhe
+nach. Das lohnt sich: Was dort steht, taucht in jedem Bericht und in jedem
+Anschreiben wieder auf.
+
+**Zum Schluss:** Geh auf **Fristen** und klicke einmal auf
+*Pflichtfristen ableiten*. Danach stehen deine gesetzlichen Termine drin.
+
+---
+
+## Der Morgen: die Seite „Heute"
+
+Diese eine Seite beantwortet die Frage, was ansteht. Von oben nach unten:
+
+| Kachel | Was sie dir sagt |
+|---|---|
+| **Fristen** | Was überfällig ist (rot), was diese Woche fällig wird (orange), was diesen Monat (gelb) |
+| **Wartet auf andere** | Vorgänge, bei denen die Gegenstelle am Zug ist — mit Tagen seit dem letzten Kontakt |
+| **Nachforderungen des Trägers** | Was der Bezirk noch von dir will, mit Fortschrittsbalken |
+| **Ungeprüfter Posteingang** | Neu hochgeladene Schreiben, die noch niemand zugeordnet hat |
+| **Unverbuchte Belege** | Rechnungen ohne Buchung und Buchungen ohne Beleg |
+| **Wo stehen wir?** | Vermögen zum letzten Stichtag, Heimkosten gegen Deckung, Tage bis zum Jahresbericht |
+
+Jede Kachel endet in einer Handlung. Wenn irgendwo nichts steht, ist dort
+auch nichts zu tun.
+
+**Ist eine Kachel leer, obwohl du Daten erwartest?** Dann fehlt meist ein
+Eintrag: keine Fristen ohne Bestellungsdatum, keine Deckungslücke ohne
+erfassten Heimkostenmonat.
+
+---
+
+## Die zwölf häufigsten Handgriffe
+
+### 1. Ein Behördenschreiben aufnehmen
+
+**Dokumente → Aufnehmen**, oder unterwegs über den runden Knopf unten
+rechts → *Beleg fotografieren*.
+
+1. Foto machen oder PDF wählen — mehrere auf einmal sind ausdrücklich
+   erwünscht.
+2. Warten, bis die Datei angenommen ist. Geprüft wird der **Inhalt**, nicht
+   die Endung: eine Datei, die sich nur als PDF ausgibt, wird abgelehnt.
+3. Titel eintragen (oder leer lassen — die Erkennung schlägt einen vor).
+4. **Eingangsdatum** setzen. Das ist wichtiger, als es aussieht: Bei
+   Bescheiden läuft die Widerspruchsfrist ab dem Zugang, nicht ab dem
+   Datum auf dem Brief.
+5. Vorgang auswählen.
+6. *In die Akte übernehmen*.
+
+Danach liest der Server den Text (Texterkennung auf Deutsch) und schlägt
+dir **Absender, Datum, Aktenzeichen, Dokumentart und eine im Text genannte
+Frist** vor. Die Textstelle steht daneben — prüf sie, bevor du übernimmst.
+Nichts davon wird automatisch angelegt.
+
+**Trag ein, wo das Papier liegt.** Es gibt ein Feld für Ordner und
+Register. Wenn der Rechtspfleger das Original sehen will, findest du es
+dann in zehn Sekunden.
+
+### 2. Aus einem Schreiben eine Frist machen
+
+Öffne das Dokument. Steht unter den Vorschlägen eine erkannte Frist,
+genügt ein Klick auf *Als Frist übernehmen*. Sonst: **Fristen → Neu**,
+Datum eintragen, Vorgang zuordnen.
+
+Setz bei behördlichen Fristen die Vorwarnung großzügig. Der Standard ist
+60/30/7/1 Tage vorher.
+
+### 3. Einen Besuch festhalten — in zwanzig Sekunden
+
+Runder Knopf unten rechts → *Notiz / Kontakt festhalten*.
+
+Datum ist auf heute vorbelegt, die Art wählst du aus einer Knopfreihe, die
+Dauer per Schnellwahl. Ein Freitextfeld, fertig.
+
+Zwei Felder lohnen die zusätzlichen Sekunden:
+
+- **„Persönlicher Kontakt zur betreuten Person"** — dieses Häkchen zählt
+  direkt in den Jahresbericht. Es ist bewusst **nicht** vorbelegt: ein
+  versehentlich gesetztes Häkchen wäre eine falsche Angabe gegenüber dem
+  Gericht.
+- **Geäußerte Wünsche** — seit der Reform 2023 ist der Wille der betreuten
+  Person die Leitschnur deines Handelns (§ 1821 BGB). Was du hier
+  festhältst, landet im Jahresbericht und trägt deine Entscheidungen.
+
+Das ist der Handgriff, der sich am meisten auszahlt. Ein Jahresbericht aus
+vierzig kurzen Notizen schreibt sich fast von selbst; einer aus der
+Erinnerung ist eine Qual.
+
+### 4. Eine Buchung erfassen
+
+**Vermögen & Kasse → Buchungen → Neu**, oder über den runden Knopf.
+
+Wichtig ist die Trennung: **Betrifft die Buchung die betreute Person oder
+ist es deine eigene Auslage?** Läuft eine Buchung auf ein als privat
+markiertes Konto und ist trotzdem als „betrifft die Betreute"
+gekennzeichnet, warnt die Anwendung. Das ist der Fehler, der einem in der
+Rechnungslegung um die Ohren fliegt.
+
+**Belege.** Eine Buchung ohne Beleg wird in der Liste markiert. Das ist
+kein Verbot — manchmal gibt es keinen. Dann trag eine Begründung ein, dann
+ist die Zeile sauber und du weißt später noch, warum.
+
+### 5. Einen Vorgang anlegen
+
+**Vorgänge → Neuer Vorgang.** Nimm eine Vorlage, wenn eine passt:
+
+Heimeinzug · Antrag Hilfe zur Pflege · Wohnungsauflösung · Hausverkauf ·
+Darlehen § 91 SGB XII · Versicherungsverwertung · Pflegegrad-Höherstufung ·
+Steuererklärung · Widerspruch gegen Bescheid
+
+Jede bringt eine durchdachte Aufgabenliste in der richtigen Reihenfolge
+mit. Bei den genehmigungspflichtigen erzwingt sie die Reihenfolge
+**Mitteilung → Genehmigung → Rechtsgeschäft**.
+
+Ein Feld solltest du immer pflegen: **Nächster Schritt.** Es steht auf dem
+Dashboard und beantwortet dir in vier Wochen die Frage, was du dir dabei
+gedacht hast.
+
+### 6. Ein genehmigungspflichtiges Geschäft
+
+Hausverkauf, Wohnungskündigung, Kreditaufnahme, Verwertung einer
+Lebensversicherung — dafür brauchst du das Betreuungsgericht.
+
+Markiere den Vorgang als genehmigungspflichtig und wähle die
+Rechtsgrundlage. Die Anwendung zeigt dann eine feste Stufenfolge:
+
+**Mitteilung ans Gericht → Antrag gestellt → Anhörung → Beschluss →
+Rechtskraft → Vollzug**
+
+> Die Stufe **Vollzug lässt sich erst setzen, wenn ein Beschlussdokument
+> hinterlegt ist.** Das ist Absicht: Nach § 1858 BGB muss die Genehmigung
+> **vor** dem Rechtsgeschäft vorliegen. Ein Vertrag, den du vorher
+> unterschreibst, ist schwebend unwirksam.
+
+Sprich vorher mit dem Rechtspfleger. Die Anwendung ersetzt das Gespräch
+nicht, sie erinnert dich nur daran.
+
+### 7. Eine Nachforderung des Bezirks abarbeiten
+
+**Sozialhilfe → Akte öffnen.** Jede angeforderte Unterlage steht als
+eigene Zeile mit Status und Frist. Der Fortschrittsbalken zeigt „x von y
+Unterlagen geliefert".
+
+Beim Anlegen des Antrags kannst du die **Checkliste der Standardunterlagen**
+übernehmen — Rentenbescheide, Kontoauszüge, Versicherungsunterlagen,
+notarielle Übertragungsverträge, Pflegegradbescheid, Heimvertrag,
+Grundbuchauszug. Zu jeder steht dabei, **warum** der Träger sie will. Das
+erspart Rückfragen.
+
+Gibt es eine Unterlage nicht, setz den Status auf *nicht vorhanden* und
+schreib eine Begründung dazu. Die geht später mit ins Unterlagenpaket —
+besser als kommentarloses Schweigen.
+
+Wenn alles beisammen ist: **Berichte → Unterlagenpaket**. Das macht aus
+den markierten Dokumenten **eine** PDF mit Anschreiben, laufender Nummer
+und Inhaltsverzeichnis.
+
+### 8. Einen Bescheid prüfen
+
+**Sozialhilfe → Akte → Bescheide → Neu.**
+
+Trag das **Zugangsdatum** ein, nicht das Datum auf dem Bescheid. Die
+Widerspruchsfrist läuft ab Bekanntgabe.
+
+Die Anwendung rechnet die Frist aus — mit Wochenende, bayerischen
+Feiertagen und dem Sonderfall, dass bei fehlender oder falscher
+Rechtsbehelfsbelehrung ein Jahr statt eines Monats gilt (§ 66 SGG). Der
+Rechenweg wird ausgegeben, damit du ihn nachvollziehen kannst. Aus dem
+Ergebnis entsteht automatisch die Frist *Widerspruch möglich bis*.
+
+**Rechne im Zweifel nach oder frag beim Bezirk.** Eine verstrichene
+Widerspruchsfrist bekommst du nicht zurück.
+
+### 9. Einen Rückkaufswert anfordern
+
+**Verträge → Vertrag öffnen → Rückkaufswert anfordern.** Es entsteht ein
+Anschreiben zum Kopieren, und die Anwendung legt eine **Wiedervorlage in
+vier Wochen** an. Versicherer antworten selten von selbst.
+
+### 10. Einen Vertrag kündigen
+
+**Verträge → Vertrag öffnen → Kündigen.**
+
+Der Rechner nennt dir den **spätesten Absendetag**, nicht den Fristablauf —
+eine Kündigung wirkt mit dem Zugang, nicht mit dem Abschicken. Drei Tage
+Postlauf sind eingerechnet.
+
+Der Assistent fragt dich nach der Genehmigung. Er beantwortet die Frage
+nicht, und das soll er auch nicht: Ob die Verwertung einer
+Lebensversicherung genehmigungspflichtig ist, entscheidet der
+Rechtspfleger. Der **Versandnachweis** (Einschreiben, Faxprotokoll) ist
+Pflichtfeld — ohne ihn geht die Kündigung nicht durch.
+
+### 11. Einen Wertstand nachtragen
+
+**Vermögen & Kasse → Vermögen → Posten öffnen → Wert eintragen.**
+
+Stichtag, Betrag und **Wertquelle** — letztere ist Pflicht. „Eigene
+Schätzung" ist eine zulässige Antwort, „keine Angabe" nicht: Im
+Vermögensverzeichnis steht die Quelle mit dabei, und das Gericht darf
+wissen, woher die Zahl kommt.
+
+Alte Werte werden **nie überschrieben**. Jede Vermögensübersicht bleibt
+später reproduzierbar.
+
+### 12. Etwas versehentlich Gelöschtes zurückholen
+
+**Einstellungen → Papierkorb.** Gelöschtes bleibt 30 Tage liegen und lässt
+sich mit einem Klick zurückholen. Erst danach ist es wirklich weg.
+
+Endgültiges Löschen verlangt eine erneute Anmeldung.
+
+---
+
+## Das Betreuungsjahr
+
+Dein Jahr läuft **ab dem Tag der Bestellung**, nicht ab dem 1. Januar. Wer
+am 14. Februar bestellt wurde, hat sein erstes Betreuungsjahr bis zum
+13. Februar des Folgejahres.
+
+| Wann | Was | Grundlage |
+|---|---|---|
+| 3 Monate nach Bestellung | Vermögensverzeichnis und Anfangsbericht | §§ 1835, 1863 BGB |
+| Zum Ende jedes Betreuungsjahres | Jahresbericht und Vermögensübersicht | §§ 1859, 1863 BGB |
+| Bis 6 Monate danach | **Aufwandspauschale beantragen** | § 1878 BGB |
+| Jährlich bis 31.12. | Bayerisches Landespflegegeld | BayLPflGG |
+| Jährlich | Zuzahlungsbefreiung der Krankenkasse | § 62 SGB V |
+| Jährlich | Rückkaufswerte aller Versicherungen aktualisieren | — |
+
+> **Die Aufwandspauschale ist eine Ausschlussfrist.** Läuft sie ab, ist
+> der Anspruch ersatzlos weg — keine Nachsicht, keine Wiedereinsetzung.
+> Die Anwendung warnt deshalb schon 90 Tage vorher und markiert sie rot.
+
+---
+
+## Die Berichte
+
+Alle unter **Berichte**, die beiden Finanzberichte unter **Vermögen &
+Kasse → Berichte**. Jeder trägt Kopf mit Aktenzeichen, Fußzeile mit
+Seitenzahl und ein Unterschriftenfeld.
+
+**Vermögensverzeichnis (§ 1835 BGB).** Stichtag wählen, Knopf drücken.
+Aktiva nach Gruppen, Passiva, laufende Einnahmen und Ausgaben,
+Belegverweise. Hat ein Posten zum Stichtag keinen Wert, erscheint er als
+**Lücke** — nicht als 0,00 €. Das ist ehrlicher und fällt dir auf.
+
+**Vermögensübersicht / Rechnungslegung (§§ 1859, 1865 BGB).**
+Betreuungsjahr wählen. Anfangsbestand, geordnete Einnahmen und Ausgaben,
+Endbestand, Belegliste.
+
+Zwei Varianten: die knappe Übersicht für **befreite Betreuer** (§ 1859 BGB
+— als Angehöriger bist du das in der Regel) und die vollständige
+Rechnungslegung.
+
+> Geht die Rechenprobe nicht auf, wird die **Differenz im Bericht
+> ausgewiesen** und jeder fehlende Saldostand benannt. Das ist Absicht.
+> Eine still geglättete Rechnungslegung ist gegenüber dem Gericht wertlos —
+> und meistens fehlt einfach ein Kontoauszug.
+
+**Jahresbericht (§ 1863 BGB).** Die Anwendung erzeugt einen **Entwurf** aus
+deinen Kontaktprotokollen, Gesundheitsereignissen und Vorgängen, gegliedert
+nach dem, was das Gericht sehen will. Du überarbeitest ihn im Browser
+(wird automatisch zwischengespeichert) und gibst ihn dann als PDF oder DOCX
+aus.
+
+> Es ist ein Entwurf, kein fertiger Bericht. Lies ihn durch, bevor du ihn
+> abgibst. Was dort steht, verantwortest du.
+
+**Belegmappe.** Alle Dokumente eines Vorgangs oder Zeitraums als eine
+chronologisch sortierte, paginierte PDF mit Deckblatt und
+Inhaltsverzeichnis. Genau das, was Gericht und Bezirk haben wollen.
+
+**Vollexport.** Ein ZIP mit allen Originaldateien, allen Daten als
+lesbarem JSON, den Berichten und Prüfsummen. Damit kannst du diese
+Anwendung jederzeit verlassen. Verlangt eine erneute Anmeldung.
+
+---
+
+## Am Handy
+
+Die Anwendung ist am Telefon vollwertig bedienbar — sie ist dafür gebaut,
+nicht dafür angepasst.
+
+- Menü über das Symbol links oben, schließt mit Wischen oder Escape.
+- Der **runde Knopf unten rechts** ist immer erreichbar: Beleg
+  fotografieren, Notiz festhalten, Frist anlegen, Buchung erfassen.
+- Tabellen scrollen in ihrem eigenen Rahmen, nie die ganze Seite.
+- Zoomen ist erlaubt und abgeschaltet wird es nie.
+
+Der typische Fall: Du sitzt im Heim, fotografierst die Heimrechnung,
+ordnest sie dem Vorgang zu, hältst den Besuch fest — drei Minuten, und
+abends musst du nichts nacharbeiten.
+
+---
+
+## Wenn etwas schiefgeht
+
+**Ich will den Zugang auf ein zweites Gerät legen.**
+Das Geheimnis wird nur einmal angezeigt, beim Einrichten. Wer es später
+noch einmal braucht — Handy und Tablet, oder ein Ersatzgerät im Schrank —
+liest es auf dem Server aus:
+
+```bash
+docker compose exec app node scripts/totp-geheimnis.mjs deine@adresse.de
+```
+
+Läuft der Behälter noch mit einer Fassung vor 1.0.1, fehlt das Skript im
+Abbild (`Cannot find module`). Dann entweder aktualisieren, oder einmalig:
+
+```bash
+docker compose cp scripts/totp-geheimnis.mjs app:/app/totp-geheimnis.mjs
+docker compose exec app node totp-geheimnis.mjs deine@adresse.de
+```
+
+Das ist keine Hintertür: Es läuft nur mit Zugriff auf die Datenbank **und**
+auf `ENC_KEY_V1`. Wer beides hat, kommt ohnehin an alles. Die Ausgabe
+gehört trotzdem in kein Protokoll und in keine E-Mail.
+
+**Ich habe mein Handy mit der Authenticator-App verloren.**
+Melde dich mit einem deiner Wiederherstellungscodes an — statt der sechs
+Ziffern gibst du den Code im Format `XXXX-XXXX-XXXX` ein. Jeder
+funktioniert einmal. Danach unter **Konto → Zweiter Faktor** neu
+einrichten und **neue Codes erzeugen**.
+
+**Ich habe auch die Wiederherstellungscodes verloren.**
+Dann kommt nur noch jemand mit Zugriff auf den Server weiter, indem er den
+zweiten Faktor in der Datenbank zurücksetzt. Genau deshalb: Codes
+ausdrucken.
+
+**Der Code wird nicht angenommen.**
+Fast immer geht die Uhr des Telefons falsch. TOTP-Codes hängen an der
+Uhrzeit. Stell die automatische Zeitsynchronisierung ein.
+
+**„Zu viele Fehlversuche."**
+Nach fünf Fehlversuchen wird für eine Viertelstunde gesperrt. Warte ab —
+das gilt auch dann, wenn du selbst es warst.
+
+**Ich habe mein Passwort geändert und bin überall abgemeldet.**
+So gewollt. Ein Passwortwechsel beendet alle Sitzungen, auch auf Geräten,
+an denen du gerade nicht sitzt.
+
+**Eine Frist stimmt nicht.**
+Prüf zuerst das Bestellungsdatum unter **Stammdaten**. Änderst du es,
+werden die Pflichtfristen neu berechnet. Erledigte Fristen bleiben dabei
+unangetastet.
+
+**Ein Bericht zeigt eine Differenz.**
+Meistens fehlt ein Saldostand. Der Bericht sagt dir, welcher. Trag ihn
+unter **Vermögen & Kasse → Konten** nach und erzeuge neu.
+
+**Die Texterkennung findet nichts.**
+Sie braucht Tesseract auf dem Server. Fehlt es, funktioniert der Upload
+trotzdem — nur ohne Volltextsuche. Titel und Absender kannst du von Hand
+eintragen.
+
+---
+
+## Was diese Anwendung nicht tut
+
+Damit du dich nicht darauf verlässt:
+
+- **Sie berät dich nicht.** Sie rechnet Fristen und schlägt Einordnungen
+  vor. Ob dein Fall eine Ausnahme ist, weiß sie nicht.
+- **Sie entscheidet nicht, was Schonvermögen ist.** Sie gibt dir
+  Argumentationshilfen zu § 90 SGB XII zum Übernehmen. Entscheiden tun der
+  Träger und notfalls das Sozialgericht.
+- **Sie schätzt keine Bewilligungschancen.**
+- **Sie holt keine Kontoauszüge ab.** Kontobewegungen kommen per
+  CSV-Import oder von Hand.
+- **Sie verschickt nichts.** Anschreiben entstehen als Text zum Kopieren,
+  Berichte als PDF. Absenden musst du selbst — und den Versandnachweis
+  hochladen.
+- **Sie ersetzt deine Papierablage nicht.** Originale bleiben Originale.
+  Deshalb gibt es das Feld für den Ablageort.
+
+---
+
+## Zwei Gewohnheiten, die sich lohnen
+
+**Jeden Kontakt festhalten, sofort.** Auch das kurze Telefonat. Zwanzig
+Sekunden jetzt sparen dir im Januar einen halben Tag.
+
+**Einmal im Jahr die Wiederherstellung üben.** Ein Backup, das nie
+zurückgespielt wurde, ist kein Backup. Die Anleitung steht in der README
+unter *Sicherung und Wiederherstellung*. Zwanzig Minuten, einmal im Jahr.
+
+---
+
+## Wo du weiterkommst
+
+- **Hinweise** in der Anwendung — 37 Karten zu den häufigen Fallstricken,
+  jede mit Rechtsgrundlage und Link zum Gesetzestext.
+- **Protokoll** — jede Änderung, lückenlos und unveränderlich. Dein
+  Nachweis gegenüber Gericht und möglichen Miterben.
+- Dein **Rechtspfleger** beim Betreuungsgericht. Er ist zuständig und
+  antwortet. Bei allem, was genehmigungspflichtig sein könnte: vorher
+  fragen, nicht nachher.
+- Die örtliche **Betreuungsbehörde** und die Betreuungsvereine beraten
+  ehrenamtliche Betreuer kostenlos.

docs/ROADMAP.md

@@ -0,0 +1,261 @@
+# Roadmap
+
+Was als Nächstes drankommt, und warum in dieser Reihenfolge.
+
+**Maßstab ist der Alltag, nicht die Vollständigkeit.** Ein Punkt steht
+weit oben, wenn er entweder etwas Falsches richtigstellt oder jeden Monat
+Zeit spart. Er steht weit unten, wenn er nur schön wäre.
+
+Diese Datei ist eine Absichtserklärung, kein Vertrag. Was sich im Betrieb
+als wichtiger herausstellt, rutscht nach oben.
+
+Stand: 22.08.2026 · Aktuelle Fassung: **1.0.0** ([CHANGELOG](../CHANGELOG.md))
+
+---
+
+## Woher die Punkte kommen
+
+Beim Bauen sind **44 Schema-Wünsche** aufgelaufen — Stellen, an denen das
+Datenmodell etwas nicht abbildet, was die Fachlogik gebraucht hätte. Sie
+liegen einzeln und begründet in [`schema-wuensche/`](schema-wuensche/),
+nach Modul getrennt. Diese Roadmap sortiert sie nach Dringlichkeit und
+bündelt sie zu Releases, die sich in einem Rutsch migrieren lassen.
+
+Dazu kommen die bekannten Einschränkungen aus dem Changelog und das, was
+sich im Betrieb noch zeigen wird.
+
+---
+
+## 1.1 — Was heute noch falsch sein kann
+
+**Ziel:** Kein Wert in der Anwendung soll unter ungünstigen Umständen
+falsch sein, ohne dass man es merkt. Das ist die einzige Art von Fehler,
+die man einem Betreuungsgericht nicht erklären kann.
+
+### Kostenkonto der Immobilie richtigstellen
+
+`Buchung` hat kein `immobilieId`. Das Kostenkonto wertet deshalb über
+Buchungskategorien aus — bei **einem** Grundstück richtig, bei einem
+zweiten still falsch. Die Oberfläche sagt das derzeit an der Auswertung
+dazu; das ist ein Pflaster, keine Lösung.
+
+*Aufwand: klein. Migration: ein Feld, ein Index.*
+
+### Umbuchungen kennen ihr Gegenkonto
+
+Eine Umbuchung zwischen zwei Konten erscheint heute als zwei unverbundene
+Buchungen. In der Rechnungslegung sieht das aus wie eine Ausgabe und eine
+Einnahme — und wer nachrechnet, fragt zu Recht nach.
+
+*Aufwand: klein. Migration: ein selbstbezüglicher Fremdschlüssel.*
+
+### Dublettenschutz beim Import ohne Konto
+
+Der Schutz vor Doppelbuchungen greift über `(kontoId, importReferenz)`.
+Ist kein Konto zugeordnet, greift er nicht — ein zweimal eingelesener
+Auszug erzeugt dann doppelte Buchungen.
+
+*Aufwand: klein. Migration: partieller eindeutiger Index.*
+
+### Rückkaufswert am Vertrag
+
+Der Wert hängt heute am Vermögensposten. In der Vertragsübersicht steht
+deshalb kein Betrag — ausgerechnet dort, wo man ihn beim Telefonat mit dem
+Versicherer braucht.
+
+*Aufwand: klein.*
+
+### Genau eine Zielspalte je Dokumentverknüpfung
+
+`DokumentVerknuepfung` hat zwölf mögliche Zielspalten; dass genau eine
+gesetzt ist, erzwingt bisher nur die Anwendung. Ein CHECK-Constraint macht
+daraus eine Zusage, die auch bei direktem Datenbankzugriff hält.
+
+*Aufwand: klein. Migration: ein Constraint.*
+
+### Papierkorb für Saldo- und Wertstände
+
+Beide Modelle haben kein `geloeschtAm`. Ein versehentlich eingetragener
+Kontostand lässt sich nur endgültig löschen — was der Zusage widerspricht,
+dass Löschen 30 Tage rückgängig zu machen ist.
+
+*Aufwand: klein.*
+
+### Aufgaben aus Vorlagen entfernen können
+
+Passt eine Aufgabe aus einer Vorgangs-Vorlage im Einzelfall nicht, bleibt
+sie dauerhaft offen stehen und verfälscht jede Fortschrittsanzeige.
+
+*Aufwand: klein.*
+
+---
+
+## 1.2 — Weniger tippen
+
+**Ziel:** Die Handgriffe, die sich jeden Monat wiederholen, kürzer machen.
+
+### Nachforderungen mit stabilem Schlüssel
+
+Der Dublettenschutz beim Übernehmen der Standardcheckliste läuft über die
+Bezeichnung. Wer eine Zeile umbenennt, bekommt sie beim nächsten Mal
+doppelt.
+
+### Bescheid und Frist verbinden
+
+Aus einem Bescheid entsteht die Widerspruchsfrist heute über einen
+Textschlüssel statt über einen Fremdschlüssel. Ändert sich das
+Zugangsdatum, wandert die Frist nicht mit.
+
+### Statuswechsel eines Vorgangs als eigene Tabelle
+
+Der Zeitstrahl liest Statuswechsel aus dem entschlüsselten Audit-Log. Das
+funktioniert, ist aber langsam und hängt an einem Format, das eigentlich
+nur Nachweis sein soll.
+
+### Wer hat was erfasst
+
+Fristen, Saldo- und Wertstände tragen kein Feld für den erfassenden
+Benutzer. Bei einer Betreuung zu zweit ist das die erste Frage.
+
+### Ansprechpartner am Vorgang
+
+Die Sachstandsanfrage kann namentlich anreden, bekommt den Ansprechpartner
+mangels Feld aber nicht übergeben.
+
+### Inventarliste als eigenes Modell
+
+Wertgegenstände hängen heute an Freitext und Fotos. Für die
+Wohnungsauflösung wäre eine Liste mit Bezeichnung, Raum, geschätztem Wert
+und Verbleib das richtige Werkzeug.
+
+### Pflegegrad-Historie
+
+Der Pflegegrad steht als einzelnes Feld in den Stammdaten. Frühere Grade
+mit ihren Zeiträumen gehören in eine Historie — sie werden im
+Jahresbericht und bei einer Höherstufung gebraucht.
+
+---
+
+## 1.3 — Belastbarkeit
+
+**Ziel:** Die Stellen absichern, die bisher nur unter Laborbedingungen
+geprüft sind.
+
+### Texterkennung gegen echtes Tesseract
+
+Bisher ist nur der Weg „nicht verfügbar, Upload funktioniert trotzdem"
+getestet. Ein Test im Container gegen echte Schreiben — auch schlechte
+Handyfotos, auch mehrseitige Bescheide — fehlt.
+
+### CAMT.053 gegen einen echten Bankauszug
+
+Der Leser ist gegen selbst gebaute Beispiele geprüft. Ein echter Auszug
+der Sparkasse ist der eigentliche Test.
+
+### Suche und Belegmappe gegen Postgres
+
+Beide sind nur in Einzelteilen geprüft, nicht end-to-end gegen die
+Datenbank mit einigen hundert Dokumenten.
+
+### Wiederherstellung als Test
+
+Die Anleitung dafür steht in der README. Ein Skript, das sie einmal im
+Monat automatisch durchspielt — Sicherung zurückspielen, Diagnosen im
+Klartext prüfen, Testdatenbank verwerfen — wäre der Beweis statt der
+Absichtserklärung.
+
+### Barrierefreiheits-Durchgang mit einem Screenreader
+
+Semantik, Fokusreihenfolge und Kontraste sind beim Bauen beachtet und in
+Teilen getestet. Ein Durchgang mit NVDA oder VoiceOver ist etwas anderes
+als eine Testzusicherung.
+
+### `@react-pdf/renderer` ohne Krücke
+
+`src/lib/pdf/standardschrift.ts` gleicht aus, dass die Unterabhängigkeiten
+für Standardschriften kein Schriftobjekt mehr liefern. Ein `overrides`-
+Eintrag in der `package.json` oder eine neuere Fassung macht die Datei
+überflüssig — sie baut sich dann selbst ab.
+
+---
+
+## 2.0 — Mehr als eine Betreuung
+
+**Ziel:** Was sich nur mit einem Bruch lösen lässt. Deshalb eine eigene
+Hauptversion — und deshalb nicht vorher.
+
+### Zweite betreute Person im Alltag erprobt
+
+Das Datenmodell trägt es von Anfang an: Alles hängt an einer `betreuteId`,
+der Zugriff wird gegen sie geprüft, die Auswahl steht in der Seitenleiste.
+**Gelaufen ist es bisher nur mit einer.** Was fehlt, ist Erfahrung — und
+vermutlich ein Dashboard, das über beide hinwegsieht.
+
+### Heimkostenmodell entwirren
+
+Der einrichtungseinheitliche Eigenanteil auf der Heimrechnung ist bereits
+um die Leistung der Pflegekasse gekürzt. Das Modul rechnet deshalb
+ausdrücklich nach der Lesart `EIGENANTEIL_NETTO` und warnt, wenn die
+Pflegekassenleistung zusätzlich erfasst wird.
+
+Sauberer wäre, die beiden Lesarten im Modell zu trennen, statt sie im Kopf
+auseinanderzuhalten. Das ändert bestehende Datensätze — also 2.0.
+
+### Mehrere Fassungen je Bericht
+
+Heute verdrängt die DOCX-Ausgabe die abgegebene PDF-Fassung. Was einmal
+beim Gericht lag, sollte unverändert nachweisbar bleiben.
+
+### Verschlüsselte Ablage auch bei S3
+
+Beim Dateitreiber liegen Dokumente zusätzlich AES-256-GCM-verschlüsselt.
+Bei S3 geht das nicht, weil signierte URLs am Server vorbei ausgeliefert
+werden. Der Ausweg wäre, Dateien durch die Anwendung zu reichen — das
+kostet Durchsatz und ist eine bewusste Abwägung, keine Selbstverständlichkeit.
+
+---
+
+## Später, ohne Datum
+
+Sinnvoll, aber nicht dringend:
+
+- **Kalendarische Wiedervorlage per E-Mail als Wochenübersicht** statt
+  einzelner Erinnerungen.
+- **Vorlagen für eigene Anschreiben**, über die mitgelieferten hinaus.
+- **Import eines Grundbuchauszugs** als strukturierte Daten statt als PDF.
+- **Mehrere Betreuungsgerichte** je betreuter Person (bei Umzug).
+- **Zwei-Personen-Prinzip** für besonders sensible Aktionen — technisch
+  vorbereitet durch die erneute Anmeldung, fachlich noch nicht gebraucht.
+- **Statistik über mehrere Betreuungsjahre** für den eigenen Überblick.
+
+---
+
+## Bewusst nicht geplant
+
+Damit klar ist, worauf niemand warten muss:
+
+| Was | Warum nicht |
+|---|---|
+| **Automatische Rechtsberatung** | Die Anwendung kennt den Einzelfall nicht. Sie rechnet und dokumentiert; entscheiden tun Gericht, Träger und im Zweifel das Sozialgericht. |
+| **Prognosen zu Bewilligungschancen** | Eine Zahl, die niemand belegen kann, wird trotzdem geglaubt. Das ist schlimmer als keine Zahl. |
+| **Direkte Bankanbindung** | Ein dauerhafter Kontozugriff ist ein Risiko, das der Bequemlichkeit nicht wert ist. CSV und CAMT reichen. |
+| **Mehrmandantenfähigkeit für fremde Betreuungen** | Sobald mehrere Betreuer mit fremden Fällen auf derselben Installation arbeiten, ändert sich die datenschutzrechtliche Lage grundlegend. Mehrere Betreute **einer** Person bleiben möglich. |
+| **Native App für Handy und Tablet** | Die Web-Anwendung ist am Telefon vollwertig bedienbar. Eine zweite Oberfläche wäre eine zweite Oberfläche, die veraltet. |
+| **Cloud-Angebot für andere Betreuer** | Dann wäre ich Auftragsverarbeiter für fremde Gesundheitsdaten. Eine andere Aufgabe als die, für die das hier gebaut wurde. |
+| **KI-Auswertung der Akte** | Gesundheitsdaten einer nicht entscheidungsfähigen Person verlassen diesen Server nicht. Die Texterkennung läuft lokal, und dabei bleibt es. |
+
+---
+
+## Wie hier priorisiert wird
+
+Drei Fragen, in dieser Reihenfolge:
+
+1. **Kann daraus ein falscher Wert in einem Bericht ans Gericht werden?**
+   Dann sofort — auch wenn es unbequem ist.
+2. **Kostet es jeden Monat Zeit?** Dann bald.
+3. **Wäre es schön?** Dann irgendwann, und ehrlich gesagt vielleicht nie.
+
+Fällt ein Punkt in Kategorie 1 und wird trotzdem nicht sofort behoben,
+steht der Grund dabei — und die Oberfläche sagt an der betroffenen Stelle,
+worauf man achten muss. Ein stillschweigend falscher Wert ist das
+Schlimmste, was diese Anwendung produzieren kann.

next.config.mjs

@@ -6,6 +6,16 @@ const nextConfig = {
   poweredByHeader: false,
   // Argon2 ist eine native Bibliothek und darf nicht gebundelt werden.
   serverExternalPackages: ['@node-rs/argon2'],
+
+  // Zwei Seiten lesen zur Laufzeit eine Markdown-Datei aus docs/:
+  // die Datenschutzhinweise und die Bedienungsanleitung. Der Pfad wird
+  // erst zur Laufzeit gebaut, die Dateiverfolgung von Next.js kann ihn
+  // also nicht erkennen - ohne diesen Eintrag fehlten beide Dateien im
+  // Standalone-Build, und im Behaelter waeren die Seiten leer.
+  outputFileTracingIncludes: {
+    '/datenschutz': ['./docs/datenschutzhinweise.md'],
+    '/anleitung': ['./docs/ANLEITUNG.md'],
+  },
   eslint: {
     ignoreDuringBuilds: false,
   },

package.json

@@ -1,6 +1,6 @@
 {
   "name": "betreuungs-cockpit",
-  "version": "1.0.0",
+  "version": "1.0.5",
   "private": true,
   "description": "Arbeits- und Dokumentationswerkzeug fuer die ehrenamtliche rechtliche Betreuung",
   "engines": {

prisma/sql/audit-schutz.sql

@@ -25,6 +25,42 @@ BEGIN
     RETURN OLD;
   END IF;
 
+  /*
+   * Eine einzige Ausnahme beim UPDATE: das Nullen der beiden
+   * Fremdschluessel.
+   *
+   * Wird eine betreute Person oder ein Benutzer endgueltig geloescht
+   * (Papierkorb nach 30 Tagen), setzt Postgres wegen ON DELETE SET NULL
+   * die Spalten betreuteId bzw. userId auf NULL. Ohne diese Ausnahme
+   * scheitert das Loeschen - und der Papierkorb liesse sich nie leeren.
+   *
+   * Der Nachweis bleibt dabei vollstaendig: Zeitpunkt, Aktion, Entitaet,
+   * Bezeichnung und die verschluesselte Aenderung sind unberuehrt, ebenso
+   * die Momentaufnahmen userEmail und userName. Es verschwindet nur der
+   * Verweis auf einen Datensatz, den es nicht mehr gibt.
+   *
+   * Jede andere Aenderung wird abgewiesen - auch das Zurueckschreiben
+   * eines Fremdschluessels auf einen anderen Wert.
+   */
+  IF TG_OP = 'UPDATE'
+     AND NEW.id                        =                OLD.id
+     AND NEW.zeitpunkt                 =                OLD.zeitpunkt
+     AND NEW.aktion                    =                OLD.aktion
+     AND NEW.entitaet                  =                OLD.entitaet
+     AND NEW."entitaetId"              IS NOT DISTINCT FROM OLD."entitaetId"
+     AND NEW.bezeichnung               IS NOT DISTINCT FROM OLD.bezeichnung
+     AND NEW."userEmail"               IS NOT DISTINCT FROM OLD."userEmail"
+     AND NEW."userName"                IS NOT DISTINCT FROM OLD."userName"
+     AND NEW."aenderungVerschluesselt" IS NOT DISTINCT FROM OLD."aenderungVerschluesselt"
+     AND NEW."ipHash"                  IS NOT DISTINCT FROM OLD."ipHash"
+     AND NEW."userAgent"               IS NOT DISTINCT FROM OLD."userAgent"
+     -- Die beiden Fremdschluessel duerfen sich aendern, aber NUR nach NULL.
+     AND (NEW."betreuteId" IS NULL OR NEW."betreuteId" IS NOT DISTINCT FROM OLD."betreuteId")
+     AND (NEW."userId"     IS NULL OR NEW."userId"     IS NOT DISTINCT FROM OLD."userId")
+  THEN
+    RETURN NEW;
+  END IF;
+
   RAISE EXCEPTION
     'Das Audit-Log ist unveraenderlich. % auf audit_log ist nicht zulaessig.',
     TG_OP

scripts/anmeldung-pruefen.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * Warum klappt die Anmeldung nicht?
+ *
+ *   node --env-file=.env scripts/anmeldung-pruefen.mjs <e-mail>
+ *   docker compose exec app node scripts/anmeldung-pruefen.mjs <e-mail>
+ *
+ * Die Anwendung sagt am Anmeldeformular bewusst nicht, woran es lag - sonst
+ * liesse sich daran ablesen, welche Adressen es gibt. Auf dem Server darf
+ * man es wissen: Jeder Versuch wird mit Grund protokolliert, und dieses
+ * Skript liest ihn vor.
+ *
+ * Es aendert nichts. Es liest nur.
+ */
+import { PrismaClient } from '@prisma/client'
+
+const email = (process.argv[2] ?? '').trim().toLowerCase()
+
+if (!email) {
+  console.error('Aufruf: node scripts/anmeldung-pruefen.mjs <e-mail>')
+  process.exit(1)
+}
+
+const db = new PrismaClient()
+
+function zeit(d) {
+  return d ? new Date(d).toLocaleString('de-DE') : '—'
+}
+
+/** Klartext zu den Gruenden, die src/auth.ts protokolliert. */
+const GRUND = {
+  unbekannt: 'Diese E-Mail-Adresse gibt es nicht (Tippfehler? andere Adresse?)',
+  'passwort-falsch': 'Das Passwort stimmt nicht',
+  'code-falsch': 'Der Code aus der Authenticator-App stimmt nicht',
+  gesperrt: 'Abgewiesen, weil zu diesem Zeitpunkt bereits gesperrt war',
+  'konto-inaktiv': 'Der Zugang ist deaktiviert oder im Papierkorb',
+}
+
+try {
+  const benutzer = await db.user.findUnique({ where: { email } })
+
+  console.log('\n══ Zugang ' + '═'.repeat(50))
+
+  if (!benutzer) {
+    console.log(`  Es gibt KEINEN Zugang mit der Adresse ${email}.`)
+    const alle = await db.user.findMany({
+      select: { email: true, aktiv: true, geloeschtAm: true },
+      orderBy: { erstelltAm: 'asc' },
+    })
+    console.log(
+      alle.length
+        ? '\n  Vorhandene Adressen:\n' +
+            alle.map((u) => `    ${u.email}${u.geloeschtAm ? '  (im Papierkorb)' : u.aktiv ? '' : '  (deaktiviert)'}`).join('\n')
+        : '\n  Es gibt ueberhaupt keinen Zugang. Leg ihn im Browser unter /ersteinrichtung an.',
+    )
+  } else {
+    const zweiterFaktor = benutzer.totpAktiviertAm
+      ? `eingerichtet am ${zeit(benutzer.totpAktiviertAm)}`
+      : benutzer.totpSecretVerschluesselt
+        ? 'vorbereitet, aber NICHT bestaetigt - beim Anmelden wird noch kein Code verlangt'
+        : 'noch nicht eingerichtet - beim Anmelden wird noch kein Code verlangt'
+
+    console.log(`  Name:              ${benutzer.name}`)
+    console.log(`  Rolle:             ${benutzer.rolle}`)
+    console.log(`  Aktiv:             ${benutzer.aktiv ? 'ja' : 'NEIN - Anmeldung nicht moeglich'}`)
+    console.log(`  Papierkorb:        ${benutzer.geloeschtAm ? 'JA seit ' + zeit(benutzer.geloeschtAm) : 'nein'}`)
+    console.log(`  Zweiter Faktor:    ${zweiterFaktor}`)
+    console.log(`  Wiederherstellung: ${benutzer.wiederherstellungscodes.length} Codes uebrig`)
+    console.log(`  Passwort gesetzt:  ${zeit(benutzer.passwortGeaendertAm)}`)
+    console.log(`  Letzte Anmeldung:  ${zeit(benutzer.letzteAnmeldung)}`)
+
+    const zugaenge = await db.betreuungsZugang.count({ where: { userId: benutzer.id } })
+    const betreute = await db.betreute.count({ where: { geloeschtAm: null } })
+    console.log(`  Betreute Personen: ${zugaenge} zugeordnet, ${betreute} insgesamt angelegt`)
+
+    if (zugaenge === 0 && betreute === 0) {
+      console.log(
+        '\n  Hinweis: Nach dem Anmelden landest du zuerst bei der\n' +
+          '  Ersteinrichtung - erst zweiter Faktor, dann betreute Person.',
+      )
+    }
+  }
+
+  // --- Versuche der letzten Tage -------------------------------------------
+  const versuche = await db.loginVersuch.findMany({
+    where: { email },
+    orderBy: { zeitpunkt: 'desc' },
+    take: 15,
+  })
+
+  console.log('\n══ Letzte Anmeldeversuche ' + '═'.repeat(35))
+
+  if (versuche.length === 0) {
+    console.log(
+      '  Keine. Es ist also NIE ein Versuch beim Server angekommen.\n\n' +
+        '  Das heisst: Das Formular hat gar nicht abgeschickt, oder es lief\n' +
+        '  auf eine andere Adresse. Pruef AUTH_URL - siehe unten.',
+    )
+  } else {
+    for (const v of versuche) {
+      const kennzeichen = v.erfolg ? 'OK    ' : 'FEHLER'
+      const grund = v.erfolg ? 'angemeldet' : (GRUND[v.grund] ?? v.grund ?? 'unbekannter Grund')
+      console.log(`  ${zeit(v.zeitpunkt).padEnd(20)} ${kennzeichen}  ${grund}`)
+    }
+  }
+
+  // --- Sperre ---------------------------------------------------------------
+  const fenster = Number.parseInt(process.env.LOGIN_FENSTER_SEKUNDEN ?? '900', 10)
+  const grenze = Number.parseInt(process.env.LOGIN_MAX_VERSUCHE ?? '5', 10)
+  const seit = new Date(Date.now() - fenster * 1000)
+
+  const offen = await db.loginVersuch.count({
+    where: { email, erfolg: false, zeitpunkt: { gte: seit } },
+  })
+
+  console.log('\n══ Sperre ' + '═'.repeat(51))
+  console.log(`  ${offen} von ${grenze} Fehlversuchen im laufenden Fenster (${fenster / 60} Minuten)`)
+
+  if (offen >= grenze) {
+    console.log(
+      '\n  GESPERRT. Warte das Fenster ab, oder setz die Zaehler zurueck:\n' +
+        '    docker compose exec db psql -U cockpit betreuungs_cockpit \\\n' +
+        '      -c "DELETE FROM login_versuch WHERE erfolg = false;"',
+    )
+  }
+
+  // --- Umgebung -------------------------------------------------------------
+  console.log('\n══ Umgebung ' + '═'.repeat(49))
+  console.log(`  AUTH_URL:  ${process.env.AUTH_URL ?? 'NICHT GESETZT'}`)
+  console.log(
+    '\n  Diese Adresse muss EXAKT die sein, die du im Browser aufrufst -\n' +
+      '  gleiches Schema (https), gleicher Hostname, kein Schraegstrich am\n' +
+      '  Ende. Weicht sie ab, wird das Sitzungs-Cookie fuer die falsche\n' +
+      '  Herkunft gesetzt: Die Anmeldung landet ohne Fehlermeldung wieder\n' +
+      '  auf dem Formular, und oben steht kein einziger Fehlversuch.\n',
+  )
+} catch (fehler) {
+  // Ein Prisma-Stacktrace hilft hier niemandem weiter.
+  const meldung = fehler instanceof Error ? fehler.message : String(fehler)
+
+  if (/Can't reach database server|ECONNREFUSED/i.test(meldung)) {
+    // Das Passwort in der Verbindungszeichenkette gehoert nicht auf den Schirm.
+    const url = (process.env.DATABASE_URL ?? 'NICHT GESETZT').replace(/:[^:@/]+@/, ':***@')
+    console.error(
+      [
+        '',
+        'Die Datenbank ist nicht erreichbar.',
+        '',
+        `  DATABASE_URL: ${url}`,
+        '',
+        '  Im Docker-Betrieb gehoert dieses Skript IN den Behaelter:',
+        '    docker compose exec app node scripts/anmeldung-pruefen.mjs <e-mail>',
+        '',
+        '  Laeuft die Datenbank ueberhaupt?',
+        '    docker compose ps',
+        '',
+      ].join('\n'),
+    )
+  } else {
+    console.error(`\nFehler: ${meldung}\n`)
+  }
+  process.exitCode = 1
+} finally {
+  await db.$disconnect()
+}

scripts/totp-geheimnis.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * Das TOTP-Geheimnis eines Zugangs auslesen.
+ *
+ *   node --env-file=.env scripts/totp-geheimnis.mjs <e-mail>
+ *
+ * Wofuer das gut ist: Die Anwendung zeigt das Geheimnis genau einmal an,
+ * beim Einrichten. Wer den Zugang auf ein zweites Geraet legen will -
+ * Handy und Tablet, oder ein Ersatzgeraet im Schrank - braucht es noch
+ * einmal. Ohne dieses Skript bliebe nur, den zweiten Faktor zurueckzusetzen
+ * und alle Wiederherstellungscodes neu zu erzeugen.
+ *
+ * Was es NICHT ist: eine Hintertuer. Es laeuft nur auf dem Server, nur mit
+ * Zugriff auf die Datenbank UND auf ENC_KEY_V1 aus der Umgebung. Wer beides
+ * hat, kann ohnehin alles lesen. Genau deshalb liegt der Schluessel nicht
+ * in der Datenbank.
+ *
+ * Im Docker-Betrieb:
+ *
+ *   docker compose exec app node scripts/totp-geheimnis.mjs fw@example.de
+ *
+ * Die Ausgabe gehoert nicht in ein Protokoll und nicht in eine E-Mail.
+ */
+import { PrismaClient } from '@prisma/client'
+import { createDecipheriv } from 'node:crypto'
+
+const email = (process.argv[2] ?? '').trim().toLowerCase()
+
+if (!email) {
+  console.error('Aufruf: node --env-file=.env scripts/totp-geheimnis.mjs <e-mail>')
+  process.exit(1)
+}
+
+/**
+ * Entschluesselt einen Umschlag aus src/lib/crypto/feld.ts.
+ * Format: bc1.<version>.<iv>.<tag>.<geheimtext>, alles base64url.
+ */
+function entschluesseln(umschlag, kontext) {
+  const teile = umschlag.split('.')
+  if (teile.length !== 5 || teile[0] !== 'bc1') {
+    throw new Error('Der gespeicherte Wert hat nicht das erwartete Format.')
+  }
+
+  const version = Number.parseInt(teile[1], 10)
+  const roh = process.env[`ENC_KEY_V${version}`]
+  if (!roh) {
+    throw new Error(
+      `ENC_KEY_V${version} ist nicht gesetzt. Ohne diesen Schluessel laesst ` +
+        `sich der Wert nicht lesen - auch nicht aus einem Backup.`,
+    )
+  }
+
+  const decipher = createDecipheriv(
+    'aes-256-gcm',
+    Buffer.from(roh, 'base64'),
+    Buffer.from(teile[2], 'base64url'),
+    { authTagLength: 16 },
+  )
+  // Der Feldname wird mitauthentifiziert - er muss exakt stimmen.
+  decipher.setAAD(Buffer.from(`bc1:${version}:${kontext}`, 'utf8'))
+  decipher.setAuthTag(Buffer.from(teile[3], 'base64url'))
+
+  return Buffer.concat([
+    decipher.update(Buffer.from(teile[4], 'base64url')),
+    decipher.final(),
+  ]).toString('utf8')
+}
+
+/** Base32 in Vierergruppen - so tippt es sich von Hand deutlich sicherer. */
+function gruppiert(text) {
+  return text.replace(/(.{4})/g, '$1 ').trim()
+}
+
+const db = new PrismaClient()
+
+try {
+  const benutzer = await db.user.findUnique({
+    where: { email },
+    select: {
+      email: true,
+      name: true,
+      totpSecretVerschluesselt: true,
+      totpAktiviertAm: true,
+      wiederherstellungscodes: true,
+    },
+  })
+
+  if (!benutzer) {
+    console.error(`Kein Zugang mit der Adresse ${email}.`)
+    process.exit(1)
+  }
+
+  if (!benutzer.totpSecretVerschluesselt) {
+    console.error(
+      `Fuer ${email} ist noch kein zweiter Faktor eingerichtet. ` +
+        `Das passiert beim ersten Anmelden.`,
+    )
+    process.exit(1)
+  }
+
+  const secret = entschluesseln(benutzer.totpSecretVerschluesselt, 'totpSecretVerschluesselt')
+  const uri =
+    `otpauth://totp/Betreuungs-Cockpit:${encodeURIComponent(benutzer.email)}` +
+    `?secret=${secret}&issuer=Betreuungs-Cockpit&algorithm=SHA1&digits=6&period=30`
+
+  console.log(`
+Zugang:      ${benutzer.name} <${benutzer.email}>
+Aktiv seit:  ${benutzer.totpAktiviertAm?.toLocaleString('de-DE') ?? 'noch nicht bestaetigt'}
+Codes uebrig: ${benutzer.wiederherstellungscodes.length}
+
+Geheimnis zum Abtippen:
+  ${gruppiert(secret)}
+
+Zum Einscannen (in einen QR-Code-Erzeuger auf DIESEM Rechner geben,
+niemals in einen Dienst im Netz):
+  ${uri}
+
+Diese Ausgabe gehoert nicht in ein Protokoll und nicht in eine E-Mail.
+`)
+} finally {
+  await db.$disconnect()
+}

scripts/update.sh

@@ -0,0 +1,385 @@
+#!/usr/bin/env bash
+#
+# Betreuungs-Cockpit aktualisieren.
+#
+#   ./scripts/update.sh              auf die neueste veroeffentlichte Fassung
+#   ./scripts/update.sh v1.2.0       auf eine bestimmte Fassung
+#   ./scripts/update.sh --ja         ohne Rueckfrage (fuer cron)
+#   ./scripts/update.sh --pruefen    nur nachsehen, nichts aendern
+#   ./scripts/update.sh --verwerfen  eigene Aenderungen an versionierten
+#                                    Dateien wegwerfen statt beiseitelegen
+#
+# Was das Skript tut, in dieser Reihenfolge:
+#
+#   1. Voraussetzungen pruefen (Verzeichnis, git, docker, .env)
+#   2. Fassungen holen und vergleichen
+#   3. Zeigen, was sich aendert (Changelog-Abschnitte dazwischen)
+#   4. Nachfragen
+#   5. SICHERUNG anstossen - und abbrechen, wenn sie nicht klappt
+#   6. Eigene Aenderungen beiseitelegen, umschalten, neu bauen, starten
+#   7. Die beiden SQL-Skripte ausfuehren (sie sind idempotent)
+#   8. Pruefen, ob die neue Fassung wirklich laeuft
+#
+# Die Reihenfolge ist Absicht: Bis einschliesslich Schritt 4 wird nichts
+# veraendert. Wer vorher abbricht - oder wobei etwas schiefgeht -, findet
+# alles so vor wie zuvor. Erst danach wird angefasst.
+#
+# Schritt 5 ist der wichtigste: Eine Datenbank-Migration laesst sich nicht
+# zurueckrollen. Ohne Sicherung wird hier nichts aktualisiert.
+#
+# Schritt 7 ebenfalls: Die SQL-Skripte laufen NICHT mit den Migrationen
+# mit. Wer sie vergisst, hat einen veralteten Trigger und merkt es erst,
+# wenn etwas nicht geht.
+#
+# Die .env wird nie angefasst - sie ist nicht versioniert.
+
+# Die geschweiften Klammern sorgen dafuer, dass bash die ganze Datei liest,
+# bevor sie irgendetwas ausfuehrt. Ohne sie koennte der git-checkout weiter
+# unten das Skript unter den eigenen Fuessen austauschen.
+{
+set -euo pipefail
+
+# --- Ausgabe -----------------------------------------------------------------
+
+if [ -t 1 ]; then
+  ROT=$'\033[31m'; GRUEN=$'\033[32m'; GELB=$'\033[33m'; FETT=$'\033[1m'; AUS=$'\033[0m'
+else
+  ROT=''; GRUEN=''; GELB=''; FETT=''; AUS=''
+fi
+
+schritt()  { printf '\n%s==> %s%s\n' "$FETT" "$1" "$AUS"; }
+gut()      { printf '    %s%s%s\n' "$GRUEN" "$1" "$AUS"; }
+warnung()  { printf '    %s%s%s\n' "$GELB" "$1" "$AUS"; }
+abbruch()  { printf '\n%sAbbruch: %s%s\n\n' "$ROT" "$1" "$AUS" >&2; exit 1; }
+
+# --- Aufrufparameter ---------------------------------------------------------
+
+ZIEL=""
+OHNE_RUECKFRAGE=0
+NUR_PRUEFEN=0
+OHNE_SICHERUNG=0
+VERWERFEN=0
+ENTSCHEIDUNG=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --ja|-j)          OHNE_RUECKFRAGE=1 ;;
+    --pruefen|-p)     NUR_PRUEFEN=1 ;;
+    --ohne-sicherung) OHNE_SICHERUNG=1 ;;
+    --verwerfen)      VERWERFEN=1 ;;
+    --hilfe|-h)
+      sed -n '2,34p' "$0" | sed 's/^#\s\?//'
+      exit 0 ;;
+    -*)               abbruch "Unbekannte Angabe: $arg (--hilfe zeigt die Moeglichkeiten)" ;;
+    *)                ZIEL="$arg" ;;
+  esac
+done
+
+# --- 1. Voraussetzungen ------------------------------------------------------
+
+schritt "Voraussetzungen"
+
+cd "$(dirname "$0")/.." || abbruch "Das Projektverzeichnis ist nicht erreichbar."
+PROJEKT="$(pwd)"
+
+[ -f docker-compose.yml ] || abbruch "Hier liegt keine docker-compose.yml: $PROJEKT"
+[ -f .env ]               || abbruch "Es gibt keine .env. Ohne sie startet die Anwendung nicht."
+command -v git >/dev/null || abbruch "git ist nicht installiert."
+docker compose version >/dev/null 2>&1 || abbruch "docker compose (v2) ist nicht verfuegbar."
+
+gut "Verzeichnis: $PROJEKT"
+
+# Nur nachsehen - angefasst wird die Arbeitskopie erst kurz vor dem
+# Umschalten, wenn Sicherung und Rueckfrage durch sind. Ein Abbruch
+# dazwischen darf keinen Halbzustand hinterlassen.
+SCHMUTZIG=""
+if [ -n "$(git status --porcelain --untracked-files=no)" ]; then
+  SCHMUTZIG="ja"
+  warnung "Es gibt eigene Aenderungen an versionierten Dateien."
+  git status --short --untracked-files=no | sed 's/^/      /'
+  printf '      Sie werden vor dem Umschalten beiseite gelegt.\n'
+else
+  gut "Arbeitskopie ist sauber"
+fi
+
+# --- 2. Was ist da, was kommt ------------------------------------------------
+
+schritt "Fassungen"
+
+if ! git fetch --tags --quiet origin; then
+  abbruch "Konnte die Fassungen nicht vom Server holen.
+         Erreichst du ihn? Stimmen die Zugangsdaten?
+         Es wurde nichts geaendert."
+fi
+
+JETZT="$(git describe --tags --exact-match 2>/dev/null || git rev-parse --short HEAD)"
+NEUESTE="$(git tag --list 'v*' --sort=-v:refname | head -1)"
+
+[ -n "$NEUESTE" ] || abbruch "Es gibt keine veroeffentlichte Fassung (kein Tag)."
+
+if [ -z "$ZIEL" ]; then
+  ZIEL="$NEUESTE"
+fi
+
+git rev-parse --verify --quiet "$ZIEL^{commit}" >/dev/null \
+  || abbruch "Die Fassung '$ZIEL' gibt es nicht. Vorhanden:
+$(git tag --list 'v*' --sort=-v:refname | head -5 | sed 's/^/           /')"
+
+printf '    Jetzt:   %s\n' "$JETZT"
+printf '    Ziel:    %s%s%s\n' "$FETT" "$ZIEL" "$AUS"
+
+if [ "$(git rev-parse HEAD)" = "$(git rev-parse "$ZIEL^{commit}")" ]; then
+  gut "Bereits auf dem gewuenschten Stand - nichts zu tun."
+  exit 0
+fi
+
+# --- 3. Was aendert sich -----------------------------------------------------
+
+schritt "Was sich aendert"
+
+# Der Changelog muss aus der ZIELfassung kommen: Der laufende Stand kennt
+# die neuen Abschnitte ja noch gar nicht.
+CHANGELOG="$(git show "$ZIEL:CHANGELOG.md" 2>/dev/null || true)"
+
+if [ -n "$CHANGELOG" ]; then
+  # Alle Abschnitte zwischen dem laufenden und dem gewuenschten Stand.
+  JETZT_NR="${JETZT#v}"
+  printf '%s
+' "$CHANGELOG" | awk -v jetzt="$JETZT_NR" '
+    /^## \[/ {
+      nummer = $0
+      sub(/^## \[/, "", nummer); sub(/\].*/, "", nummer)
+      if (nummer == jetzt) exit
+      drucken = (nummer != "Unveröffentlicht")
+    }
+    drucken { print "    " $0 }
+  ' | head -60
+else
+  warnung "Kein CHANGELOG.md in $ZIEL gefunden."
+fi
+
+printf '\n'
+git log --oneline --no-decorate "HEAD..$ZIEL" | head -15 | sed 's/^/    /'
+
+if [ "$NUR_PRUEFEN" = "1" ]; then
+  printf '\n'
+  gut "Nur geprueft - es wurde nichts geaendert."
+  [ -n "$SCHMUTZIG" ] && warnung "Beim echten Lauf wuerden deine Aenderungen beiseite gelegt."
+  exit 0
+fi
+
+# --- 4. Nachfragen -----------------------------------------------------------
+
+if [ "$OHNE_RUECKFRAGE" != "1" ]; then
+  printf '\n%sJetzt aktualisieren auf %s? [j/N] %s' "$FETT" "$ZIEL" "$AUS"
+  read -r antwort </dev/tty || antwort=""
+  case "$antwort" in
+    [jJ]|[jJ][aA]) ;;
+    *) printf '\n'; warnung "Abgebrochen, nichts geaendert."; exit 0 ;;
+  esac
+fi
+
+# --- 5. Sicherung ------------------------------------------------------------
+
+if [ "$OHNE_SICHERUNG" = "1" ]; then
+  schritt "Sicherung wird uebersprungen"
+  warnung "Auf eigene Gefahr - eine Migration laesst sich nicht zurueckrollen."
+else
+  schritt "Sicherung"
+
+  if docker compose ps --status running --services 2>/dev/null | grep -qx sicherung; then
+    if docker compose exec -T sicherung /bin/sh /sicherung.sh; then
+      gut "Sicherung angelegt und selbst geprueft."
+    else
+      abbruch "Die Sicherung ist fehlgeschlagen. Es wird nichts aktualisiert.
+         Mit --ohne-sicherung laesst sich das uebergehen - aber ueberleg
+         dir das zweimal."
+    fi
+  else
+    warnung "Der Dienst 'sicherung' laeuft nicht - es wurde nichts gesichert."
+    if [ "$OHNE_RUECKFRAGE" != "1" ]; then
+      printf '\n    %sTrotzdem weitermachen? [j/N] %s' "$FETT" "$AUS"
+      read -r weiter </dev/tty || weiter=""
+      case "$weiter" in [jJ]|[jJ][aA]) ;; *) abbruch "Abgebrochen." ;; esac
+    fi
+  fi
+fi
+
+# --- 6. Umschalten und bauen -------------------------------------------------
+
+# Aenderungen an versionierten Dateien blockieren das Umschalten.
+#
+# Im Betrieb ist das der Normalfall: Man passt die docker-compose.yml an,
+# bis etwas laeuft. Genau diese Anpassungen sind spaeter oft schon
+# eingearbeitet - das Skript soll sie also nicht zum Hindernis machen.
+#
+# Verworfen wird trotzdem nichts stillschweigend. Standard ist "beiseite
+# legen": git stash macht es rueckholbar. Wer sie wirklich weghaben will,
+# nimmt --verwerfen.
+#
+# Die .env ist nie betroffen - sie ist nicht versioniert.
+schritt "Eigene Aenderungen"
+
+if [ -n "$(git status --porcelain --untracked-files=no)" ]; then
+  printf '\n    Diese versionierten Dateien sind veraendert:\n\n'
+  git status --short --untracked-files=no | sed 's/^/      /'
+  printf '\n'
+
+  if [ "$VERWERFEN" = "1" ]; then
+    ENTSCHEIDUNG="verwerfen"
+  elif [ "$OHNE_RUECKFRAGE" = "1" ]; then
+    # Ohne jemanden zum Fragen: die sichere Variante.
+    ENTSCHEIDUNG="beiseite"
+  else
+    printf '    %s[b]%s eiseite legen (git stash, spaeter rueckholbar)\n' "$FETT" "$AUS"
+    printf '    %s[v]%s erwerfen (endgueltig weg)\n' "$FETT" "$AUS"
+    printf '    %s[a]%s bbrechen\n\n' "$FETT" "$AUS"
+    printf '    Was soll damit geschehen? [b/v/a] '
+    read -r wahl </dev/tty || wahl=""
+    case "$wahl" in
+      [bB]|'') ENTSCHEIDUNG="beiseite" ;;
+      [vV])    ENTSCHEIDUNG="verwerfen" ;;
+      *)       abbruch "Abgebrochen, nichts geaendert." ;;
+    esac
+  fi
+
+  if [ "$ENTSCHEIDUNG" = "verwerfen" ]; then
+    git checkout -- .
+    warnung "Aenderungen verworfen."
+  else
+    STASH_NAME="vor Update $(date +%Y-%m-%d_%H%M)"
+    git stash push --quiet --message "$STASH_NAME" -- . \
+      || abbruch "Konnte die Aenderungen nicht beiseite legen."
+    gut "Beiseite gelegt als: $STASH_NAME"
+    printf '      Ansehen:    git stash list\n'
+    printf '      Zurueck:    git stash pop\n'
+    printf '      Wegwerfen:  git stash drop\n'
+  fi
+else
+  gut "Arbeitskopie ist sauber"
+fi
+
+schritt "Umschalten auf $ZIEL"
+
+# Eine unversionierte Datei kann im Weg stehen, wenn die Zielfassung sie
+# fuehrt. Das passiert beim Update auf die Fassung, die dieses Skript
+# eingefuehrt hat: Man hat es sich von Hand geholt, jetzt gehoert es dazu.
+# Solche Dateien werden nicht weggeworfen, sondern beiseite geschoben.
+if ! git checkout --quiet "$ZIEL" 2>/dev/null; then
+  IM_WEG="$(git checkout "$ZIEL" 2>&1     | sed -n '/would be overwritten/,/^Aborting/p'     | grep -E '^\s' | tr -d '	 ' | grep -v '^$' || true)"
+
+  if [ -n "$IM_WEG" ]; then
+    ZEIT="$(date +%Y%m%d-%H%M%S)"
+    printf '    Diese unversionierten Dateien stehen im Weg:
+'
+    for datei in $IM_WEG; do
+      [ -e "$datei" ] || continue
+      mv "$datei" "${datei}.vor-update-${ZEIT}"
+      printf '      %s -> %s.vor-update-%s
+' "$datei" "$datei" "$ZEIT"
+    done
+    git checkout --quiet "$ZIEL" || abbruch "Das Umschalten auf $ZIEL ist fehlgeschlagen.
+         Deine Aenderungen liegen im Stash: git stash list"
+  else
+    abbruch "Das Umschalten auf $ZIEL ist fehlgeschlagen.
+$([ -n "$SCHMUTZIG" ] && printf '         Deine Aenderungen liegen im Stash: git stash list')"
+  fi
+fi
+
+gut "$(git describe --tags --always)"
+
+schritt "Bauen und starten"
+printf '    Das dauert beim ersten Mal einige Minuten.\n\n'
+
+if ! GIT_COMMIT="$(git rev-parse --short HEAD)" \
+     BUILD_ZEIT="$(date -Iseconds)" \
+     docker compose up -d --build; then
+  printf '\n'
+  abbruch "Bauen oder Starten ist fehlgeschlagen.
+         Die Quellen stehen jetzt auf $ZIEL, die Anwendung laeuft aber
+         noch mit dem alten Abbild - oder gar nicht.
+
+         Zurueck auf den vorherigen Stand:
+           git checkout $JETZT && docker compose up -d --build
+$([ -n "$SCHMUTZIG" ] && printf '\n         Deine Aenderungen liegen im Stash: git stash list')"
+fi
+
+# --- 7. Warten, bis die Anwendung antwortet ----------------------------------
+
+schritt "Warten auf die Anwendung"
+
+# Adresse und Port stehen in der .env - Standard ist die Loopback-Adresse.
+ADRESSE="$(grep -E '^APP_BIND=' .env | tail -1 | cut -d= -f2- | tr -d '"' || true)"
+PORT="$(grep -E '^APP_PORT=' .env | tail -1 | cut -d= -f2- | tr -d '"' || true)"
+[ -n "$ADRESSE" ] || ADRESSE="127.0.0.1"
+[ -n "$PORT" ] || PORT="3000"
+# Auf 0.0.0.0 kann man nicht zugreifen - dann ueber die Loopback-Adresse.
+[ "$ADRESSE" = "0.0.0.0" ] && ADRESSE="127.0.0.1"
+
+GESUND="http://${ADRESSE}:${PORT}/api/gesundheit"
+ANTWORT=""
+
+for _ in $(seq 1 60); do
+  ANTWORT="$(curl -fsS --max-time 5 "$GESUND" 2>/dev/null || true)"
+  case "$ANTWORT" in *'"bereit"'*) break ;; esac
+  printf '.'
+  sleep 3
+done
+printf '\n'
+
+case "$ANTWORT" in
+  *'"bereit"'*) gut "Die Anwendung antwortet." ;;
+  *)
+    printf '\n'
+    docker compose logs app --tail 40 | sed 's/^/    /'
+    abbruch "Die Anwendung antwortet nicht unter $GESUND.
+         Die letzten Zeilen aus dem Log stehen oben.
+         Zurueck geht es mit:  git checkout $JETZT && docker compose up -d --build"
+    ;;
+esac
+
+# --- 8. SQL-Skripte ----------------------------------------------------------
+
+schritt "Volltextsuche und Audit-Schutz"
+printf '    Diese beiden laufen nicht mit den Migrationen mit.\n'
+printf '    Sie sind idempotent - mehrfaches Ausfuehren schadet nicht.\n\n'
+
+PRISMA="node node_modules/prisma/build/index.js"
+
+for skript in volltextsuche audit-schutz; do
+  if docker compose exec -T app $PRISMA db execute \
+       --schema prisma/schema.prisma --file "prisma/sql/${skript}.sql" >/dev/null 2>&1; then
+    gut "${skript}.sql ausgefuehrt"
+  else
+    warnung "${skript}.sql ist fehlgeschlagen - bitte von Hand nachholen:"
+    printf '      docker compose exec app %s db execute \\\n' "$PRISMA"
+    printf '        --schema prisma/schema.prisma --file prisma/sql/%s.sql\n' "$skript"
+  fi
+done
+
+# --- 9. Nachschau ------------------------------------------------------------
+
+schritt "Ergebnis"
+
+LAEUFT="$(printf '%s' "$ANTWORT" | sed -n 's/.*"version":"\([^"]*\)".*/\1/p')"
+ERWARTET="${ZIEL#v}"
+
+printf '    Erwartet: %s\n' "$ERWARTET"
+printf '    Laeuft:   %s\n' "${LAEUFT:-unbekannt}"
+
+if [ "$LAEUFT" = "$ERWARTET" ]; then
+  printf '\n'
+  gut "Fertig. Version $ERWARTET laeuft."
+else
+  printf '\n'
+  warnung "Die laufende Fassung stimmt nicht mit der erwarteten ueberein."
+  warnung "Vermutlich hat der Bau den alten Behaelter stehen lassen:"
+  printf '      docker compose up -d --build --force-recreate app\n'
+fi
+
+printf '\n    Zustand:  docker compose ps\n'
+printf '    Log:      docker compose logs app --tail 50\n'
+printf '    Zurueck:  git checkout %s && docker compose up -d --build\n\n' "$JETZT"
+
+exit 0
+}

src/app/(app)/anleitung/page.tsx

@@ -0,0 +1,55 @@
+import type { Metadata } from 'next'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { BookOpen } from 'lucide-react'
+import { Alert, AlertDescription } from '@/components/ui/alert'
+import { SeitenKopf } from '@/components/seiten-kopf'
+import { MarkdownSeite } from '@/components/markdown-seite'
+import { DruckKnopf } from '@/components/druck-knopf'
+import { erfordereBenutzer } from '@/lib/auth/sitzung'
+
+export const metadata: Metadata = { title: 'Anleitung' }
+export const dynamic = 'force-dynamic'
+
+/**
+ * Die Bedienungsanleitung, gelesen aus docs/ANLEITUNG.md.
+ *
+ * Dieselbe Datei, die auch im Repository liegt und sich ausdrucken laesst -
+ * zwei Fassungen desselben Textes waeren zwei Fassungen, die auseinander-
+ * laufen. Wer im Heim steht und nicht weiterweiss, hat sie damit auf dem
+ * Telefon dabei.
+ */
+export default async function AnleitungSeite() {
+  await erfordereBenutzer()
+
+  const pfad = path.join(process.cwd(), 'docs', 'ANLEITUNG.md')
+  let inhalt: string
+
+  try {
+    inhalt = await readFile(pfad, 'utf8')
+  } catch {
+    inhalt = ''
+  }
+
+  return (
+    <div className="max-w-3xl space-y-6">
+      <SeitenKopf
+        titel="Bedienungsanleitung"
+        beschreibung="Die Handgriffe, die du tatsächlich brauchst — in der Reihenfolge, in der sie im Alltag vorkommen."
+        aktionen={<DruckKnopf beschriftung="Anleitung drucken" />}
+      />
+
+      {inhalt === '' ? (
+        <Alert variant="warnung">
+          <BookOpen aria-hidden="true" />
+          <AlertDescription>
+            Die Anleitung konnte nicht geladen werden. Sie liegt im Projekt unter{' '}
+            <code>docs/ANLEITUNG.md</code>.
+          </AlertDescription>
+        </Alert>
+      ) : (
+        <MarkdownSeite inhalt={inhalt} />
+      )}
+    </div>
+  )
+}

src/app/datenschutz/page.tsx

@@ -2,6 +2,7 @@ import type { Metadata } from 'next'
 import Link from 'next/link'
 import { readFile } from 'node:fs/promises'
 import path from 'node:path'
+import { MarkdownSeite } from '@/components/markdown-seite'
 
 export const metadata: Metadata = { title: 'Datenschutz' }
 
@@ -11,83 +12,7 @@ export const metadata: Metadata = { title: 'Datenschutz' }
  * Der Text kommt aus docs/datenschutzhinweise.md - dieselbe Datei, die man
  * auch ausdrucken und der betreuten Person aushaendigen kann. Zwei Quellen
  * fuer denselben Text waeren zwei Quellen fuer Fehler.
- *
- * Die Umsetzung ist bewusst schlicht: keine Markdown-Bibliothek, nur die
- * wenigen Auszeichnungen, die im Dokument wirklich vorkommen.
  */
-function alsAbsaetze(markdown: string) {
-  const zeilen = markdown.split(/\r?\n/)
-  const bloecke: React.ReactNode[] = []
-  let absatz: string[] = []
-
-  const absatzSchliessen = (schluessel: number) => {
-    if (absatz.length === 0) return
-    bloecke.push(
-      <p key={`p-${schluessel}`} className="leading-relaxed">
-        {absatz.join(' ')}
-      </p>,
-    )
-    absatz = []
-  }
-
-  zeilen.forEach((zeile, i) => {
-    const roh = zeile.trim()
-
-    // Der Hinweisblock fuer den Ausfuellenden gehoert nicht auf die Seite.
-    if (roh.startsWith('>')) return
-
-    if (roh === '' || roh === '---') {
-      absatzSchliessen(i)
-      return
-    }
-    if (roh.startsWith('## ')) {
-      absatzSchliessen(i)
-      bloecke.push(
-        <h2 key={i} className="mt-8 text-xl font-semibold">
-          {roh.slice(3)}
-        </h2>,
-      )
-      return
-    }
-    if (roh.startsWith('# ')) {
-      absatzSchliessen(i)
-      bloecke.push(
-        <h1 key={i} className="text-2xl font-semibold">
-          {roh.slice(2)}
-        </h1>,
-      )
-      return
-    }
-    if (roh.startsWith('- ')) {
-      absatzSchliessen(i)
-      bloecke.push(
-        <li key={i} className="ml-5 list-disc leading-relaxed">
-          {roh.slice(2)}
-        </li>,
-      )
-      return
-    }
-    // Tabellenzeilen werden als einfache Aufzaehlung dargestellt.
-    if (roh.startsWith('|')) {
-      absatzSchliessen(i)
-      const spalten = roh.split('|').map((s) => s.trim()).filter(Boolean)
-      if (spalten.every((s) => /^-+$/.test(s))) return
-      bloecke.push(
-        <div key={i} className="flex flex-col gap-0.5 border-l-2 py-1 pl-3 sm:flex-row sm:gap-3">
-          <span className="min-w-56 font-medium">{spalten[0]}</span>
-          <span className="text-muted-foreground">{spalten.slice(1).join(' · ')}</span>
-        </div>,
-      )
-      return
-    }
-
-    absatz.push(roh)
-  })
-
-  absatzSchliessen(zeilen.length)
-  return bloecke
-}
-
 export default async function DatenschutzSeite() {
   const pfad = path.join(process.cwd(), 'docs', 'datenschutzhinweise.md')
   let inhalt: string
@@ -95,14 +20,24 @@ export default async function DatenschutzSeite() {
   try {
     inhalt = await readFile(pfad, 'utf8')
   } catch {
-    inhalt =
-      '# Datenschutzhinweise\n\nDer Text konnte nicht geladen werden. ' +
-      'Er liegt in docs/datenschutzhinweise.md.'
+    inhalt = ''
   }
 
   return (
     <div className="mx-auto max-w-3xl px-4 py-10 sm:px-6">
-      <article className="space-y-3 [&_strong]:font-semibold">{alsAbsaetze(inhalt)}</article>
+      <h1 className="text-2xl font-semibold">Datenschutzhinweise</h1>
+      <p className="mt-1 text-sm text-muted-foreground">nach Art. 13 und 14 DSGVO</p>
+
+      <div className="mt-8">
+        {inhalt === '' ? (
+          <p className="text-muted-foreground">
+            Der Text konnte nicht geladen werden. Er liegt im Projekt unter{' '}
+            <code className="rounded bg-muted px-1.5 py-0.5">docs/datenschutzhinweise.md</code>.
+          </p>
+        ) : (
+          <MarkdownSeite inhalt={inhalt} />
+        )}
+      </div>
 
       <p className="mt-10 border-t pt-6 text-sm text-muted-foreground">
         <Link href="/anmelden" className="underline hover:no-underline">

src/components/benutzer-menue.tsx

@@ -3,7 +3,16 @@
 import * as React from 'react'
 import Link from 'next/link'
 import { signOut } from 'next-auth/react'
-import { LogOut, Monitor, Moon, Settings, ShieldCheck, Sun, User as UserIcon } from 'lucide-react'
+import {
+  BookOpen,
+  LogOut,
+  Monitor,
+  Moon,
+  Settings,
+  ShieldCheck,
+  Sun,
+  User as UserIcon,
+} from 'lucide-react'
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -96,6 +105,12 @@ export function BenutzerMenue({
             Einstellungen
           </Link>
         </DropdownMenuItem>
+        <DropdownMenuItem asChild>
+          <Link href="/anleitung">
+            <BookOpen className="size-4" />
+            Anleitung
+          </Link>
+        </DropdownMenuItem>
 
         <DropdownMenuSeparator />
         <DropdownMenuLabel className="text-xs font-normal text-muted-foreground">

src/components/druck-knopf.tsx

@@ -0,0 +1,20 @@
+'use client'
+
+import { Printer } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+
+/**
+ * Druckt die aktuelle Seite.
+ *
+ * Muss eine Client-Komponente sein - window.print() gibt es auf dem
+ * Server nicht. Der Knopf selbst traegt "no-print", damit er auf dem
+ * Ausdruck nicht auftaucht.
+ */
+export function DruckKnopf({ beschriftung = 'Drucken' }: { beschriftung?: string }) {
+  return (
+    <Button variant="outline" className="no-print" onClick={() => window.print()}>
+      <Printer aria-hidden="true" />
+      {beschriftung}
+    </Button>
+  )
+}

src/components/markdown-seite.tsx

@@ -0,0 +1,324 @@
+import * as React from 'react'
+
+/**
+ * Anzeige einer Markdown-Datei aus dem docs-Verzeichnis.
+ *
+ * Bewusst ohne Markdown-Bibliothek: Die Anwendung zeigt genau zwei solche
+ * Dokumente an - die Datenschutzhinweise und die Anleitung. Beide schreibe
+ * ich selbst, ich weiss also, welche Auszeichnungen darin vorkommen. Eine
+ * Bibliothek waere hier vor allem zusaetzliche Abhaengigkeit und
+ * zusaetzliche Angriffsflaeche.
+ *
+ * Unterstuetzt: Ueberschriften, Absaetze, Aufzaehlungen (auch nummeriert),
+ * Tabellen, Zitatbloecke, Codebloecke, Trennlinien sowie **fett**,
+ * `Code` und [Links](ziel) im Fliesstext.
+ *
+ * Nicht unterstuetzt und auch nicht noetig: eingebettetes HTML, Bilder,
+ * Fussnoten. Rohes HTML wird NICHT durchgereicht - der Text wird immer als
+ * Text ausgegeben, nie als Markup.
+ */
+
+type Block =
+  | { art: 'ueberschrift'; ebene: 2 | 3 | 4; text: string }
+  | { art: 'absatz'; text: string }
+  | { art: 'liste'; nummeriert: boolean; punkte: string[] }
+  | { art: 'tabelle'; kopf: string[]; zeilen: string[][] }
+  | { art: 'zitat'; zeilen: string[] }
+  | { art: 'code'; zeilen: string[] }
+  | { art: 'trenner' }
+
+/** Zerlegt den Fliesstext in fett, Code und Links. */
+function inline(text: string, schluessel: string): React.ReactNode[] {
+  const teile: React.ReactNode[] = []
+  // Reihenfolge zaehlt: Code zuerst, damit Sternchen darin nicht greifen.
+  const muster = /(`[^`]+`)|(\*\*[^*]+\*\*)|(\[[^\]]+\]\([^)]+\))/g
+
+  let letzte = 0
+  let treffer: RegExpExecArray | null
+  let nummer = 0
+
+  while ((treffer = muster.exec(text)) !== null) {
+    if (treffer.index > letzte) {
+      teile.push(text.slice(letzte, treffer.index))
+    }
+
+    const stueck = treffer[0]
+    const id = `${schluessel}-${nummer++}`
+
+    if (stueck.startsWith('`')) {
+      teile.push(
+        <code key={id} className="rounded bg-muted px-1.5 py-0.5 font-mono text-[0.9em]">
+          {stueck.slice(1, -1)}
+        </code>,
+      )
+    } else if (stueck.startsWith('**')) {
+      teile.push(
+        <strong key={id} className="font-semibold">
+          {stueck.slice(2, -2)}
+        </strong>,
+      )
+    } else {
+      const beschriftung = stueck.slice(1, stueck.indexOf(']'))
+      const ziel = stueck.slice(stueck.indexOf('](') + 2, -1)
+      const extern = /^https?:\/\//.test(ziel)
+      teile.push(
+        <a
+          key={id}
+          href={ziel}
+          className="text-primary underline underline-offset-2 hover:no-underline"
+          {...(extern ? { target: '_blank', rel: 'noreferrer noopener' } : {})}
+        >
+          {beschriftung}
+        </a>,
+      )
+    }
+
+    letzte = treffer.index + stueck.length
+  }
+
+  if (letzte < text.length) teile.push(text.slice(letzte))
+  return teile
+}
+
+function zerlegen(markdown: string, ohneTitel: boolean): Block[] {
+  const zeilen = markdown.split(/\r?\n/)
+  const bloecke: Block[] = []
+  let absatz: string[] = []
+
+  const absatzSchliessen = () => {
+    if (absatz.length === 0) return
+    bloecke.push({ art: 'absatz', text: absatz.join(' ') })
+    absatz = []
+  }
+
+  for (let i = 0; i < zeilen.length; i++) {
+    const roh = zeilen[i] ?? ''
+    const zeile = roh.trimEnd()
+    const gekuerzt = zeile.trim()
+
+    // --- Codeblock ---------------------------------------------------------
+    if (gekuerzt.startsWith('```')) {
+      absatzSchliessen()
+      const inhalt: string[] = []
+      i += 1
+      while (i < zeilen.length && !(zeilen[i] ?? '').trim().startsWith('```')) {
+        inhalt.push(zeilen[i] ?? '')
+        i += 1
+      }
+      bloecke.push({ art: 'code', zeilen: inhalt })
+      continue
+    }
+
+    if (gekuerzt === '') {
+      absatzSchliessen()
+      continue
+    }
+
+    if (/^-{3,}$/.test(gekuerzt) || /^\*{3,}$/.test(gekuerzt)) {
+      absatzSchliessen()
+      bloecke.push({ art: 'trenner' })
+      continue
+    }
+
+    // --- Ueberschriften ----------------------------------------------------
+    const ueberschrift = gekuerzt.match(/^(#{1,4})\s+(.*)$/)
+    if (ueberschrift) {
+      absatzSchliessen()
+      const ebene = ueberschrift[1]!.length
+      // Die H1 ist der Dokumenttitel - den setzt die Seite selbst.
+      if (ebene === 1 && ohneTitel) continue
+      bloecke.push({
+        art: 'ueberschrift',
+        ebene: (Math.min(Math.max(ebene, 2), 4) as 2 | 3 | 4),
+        text: ueberschrift[2]!,
+      })
+      continue
+    }
+
+    // --- Zitatblock --------------------------------------------------------
+    if (gekuerzt.startsWith('>')) {
+      absatzSchliessen()
+      const inhalt: string[] = []
+      while (i < zeilen.length && (zeilen[i] ?? '').trim().startsWith('>')) {
+        inhalt.push((zeilen[i] ?? '').trim().replace(/^>\s?/, ''))
+        i += 1
+      }
+      i -= 1
+      bloecke.push({ art: 'zitat', zeilen: [inhalt.join(' ')] })
+      continue
+    }
+
+    // --- Tabelle -----------------------------------------------------------
+    if (gekuerzt.startsWith('|')) {
+      absatzSchliessen()
+      const spalten = (z: string) =>
+        z
+          .trim()
+          .replace(/^\|/, '')
+          .replace(/\|$/, '')
+          .split('|')
+          .map((s) => s.trim())
+
+      const kopf = spalten(gekuerzt)
+      i += 1 // Trennzeile ueberspringen
+      const zeilenInhalt: string[][] = []
+      while (i + 1 < zeilen.length && (zeilen[i + 1] ?? '').trim().startsWith('|')) {
+        i += 1
+        zeilenInhalt.push(spalten(zeilen[i] ?? ''))
+      }
+      bloecke.push({ art: 'tabelle', kopf, zeilen: zeilenInhalt })
+      continue
+    }
+
+    // --- Aufzaehlung -------------------------------------------------------
+    const punkt = gekuerzt.match(/^(?:[-*]|\d+\.)\s+(.*)$/)
+    if (punkt) {
+      absatzSchliessen()
+      const nummeriert = /^\d+\./.test(gekuerzt)
+      const punkte: string[] = [punkt[1]!]
+
+      while (i + 1 < zeilen.length) {
+        const naechste = (zeilen[i + 1] ?? '').trim()
+        const weiterer = naechste.match(/^(?:[-*]|\d+\.)\s+(.*)$/)
+        if (weiterer && /^\d+\./.test(naechste) === nummeriert) {
+          punkte.push(weiterer[1]!)
+          i += 1
+          continue
+        }
+        // Eingerueckte Fortsetzung gehoert zum letzten Punkt.
+        if (naechste !== '' && /^\s{2,}\S/.test(zeilen[i + 1] ?? '')) {
+          punkte[punkte.length - 1] += ` ${naechste}`
+          i += 1
+          continue
+        }
+        break
+      }
+
+      bloecke.push({ art: 'liste', nummeriert, punkte })
+      continue
+    }
+
+    absatz.push(gekuerzt)
+  }
+
+  absatzSchliessen()
+  return bloecke
+}
+
+export function MarkdownSeite({
+  inhalt,
+  ohneTitel = true,
+  className,
+}: {
+  inhalt: string
+  /** Die erste H1 weglassen - die Seite setzt ihre Ueberschrift selbst. */
+  ohneTitel?: boolean
+  className?: string
+}) {
+  const bloecke = zerlegen(inhalt, ohneTitel)
+
+  return (
+    <article className={className}>
+      {bloecke.map((block, i) => {
+        switch (block.art) {
+          case 'ueberschrift': {
+            const Tag = `h${block.ebene}` as 'h2' | 'h3' | 'h4'
+            const groesse =
+              block.ebene === 2
+                ? 'mt-10 text-xl font-semibold'
+                : block.ebene === 3
+                  ? 'mt-7 text-lg font-semibold'
+                  : 'mt-5 text-base font-semibold'
+            return (
+              <Tag key={i} className={`${groesse} scroll-mt-20 first:mt-0`}>
+                {block.text}
+              </Tag>
+            )
+          }
+
+          case 'absatz':
+            return (
+              <p key={i} className="mt-3 leading-relaxed">
+                {inline(block.text, String(i))}
+              </p>
+            )
+
+          case 'liste': {
+            const Tag = block.nummeriert ? 'ol' : 'ul'
+            return (
+              <Tag
+                key={i}
+                className={`mt-3 space-y-1.5 pl-6 ${
+                  block.nummeriert ? 'list-decimal' : 'list-disc'
+                }`}
+              >
+                {block.punkte.map((punkt, j) => (
+                  <li key={j} className="leading-relaxed">
+                    {inline(punkt, `${i}-${j}`)}
+                  </li>
+                ))}
+              </Tag>
+            )
+          }
+
+          case 'tabelle':
+            return (
+              // Tabellen scrollen im eigenen Rahmen - am Handy darf nie die
+              // ganze Seite seitlich wandern.
+              <div key={i} className="mt-4 w-full overflow-x-auto rounded-lg border">
+                <table className="w-full text-sm">
+                  <thead>
+                    <tr className="border-b bg-muted/50">
+                      {block.kopf.map((spalte, j) => (
+                        <th key={j} className="px-3 py-2 text-left font-semibold">
+                          {inline(spalte, `${i}-k-${j}`)}
+                        </th>
+                      ))}
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {block.zeilen.map((zeile, j) => (
+                      <tr key={j} className="border-b last:border-0">
+                        {zeile.map((zelle, k) => (
+                          <td key={k} className="px-3 py-2 align-top">
+                            {inline(zelle, `${i}-${j}-${k}`)}
+                          </td>
+                        ))}
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            )
+
+          case 'zitat':
+            return (
+              <blockquote
+                key={i}
+                className="mt-4 rounded-r-md border-l-4 border-primary/40 bg-muted/40 py-3 pl-4 pr-3"
+              >
+                {block.zeilen.map((zeile, j) => (
+                  <p key={j} className="leading-relaxed">
+                    {inline(zeile, `${i}-${j}`)}
+                  </p>
+                ))}
+              </blockquote>
+            )
+
+          case 'code':
+            return (
+              <pre
+                key={i}
+                className="mt-4 overflow-x-auto rounded-lg border bg-muted/60 p-3 text-sm"
+              >
+                <code className="font-mono">{block.zeilen.join('\n')}</code>
+              </pre>
+            )
+
+          case 'trenner':
+            return <hr key={i} className="my-8" />
+        }
+      })}
+    </article>
+  )
+}

src/lib/env.ts

@@ -58,14 +58,25 @@ function einmal<T>(fn: () => T): () => T {
 
 const holeVerschluesselungsschluessel = einmal((): Map<number, Buffer> => {
   const schluessel = new Map<number, Buffer>()
+
   // ENC_KEY_V1, ENC_KEY_V2, ... - alte Versionen bleiben zum Entschluesseln
   // stehen, verschluesselt wird immer mit der aktiven Version.
-  for (const [name] of Object.entries(process.env)) {
+  for (const [name, wert] of Object.entries(process.env)) {
     const treffer = name.match(/^ENC_KEY_V(\d+)$/)
-    if (treffer) {
+    if (!treffer) continue
+
+    // Eine LEERE Variable ist kein Schluessel.
+    //
+    // docker compose reicht ENC_KEY_V2 immer durch - mit leerem Wert, wenn
+    // in der .env keiner steht. Wuerde hier allein der Name zaehlen, waere
+    // jede Installation ohne zweiten Schluessel kaputt, und zwar mit der
+    // irrefuehrenden Meldung "ENC_KEY_V2 fehlt" - obwohl niemand einen
+    // zweiten Schluessel wollte.
+    if (!wert || wert.trim() === '') continue
+
     schluessel.set(Number.parseInt(treffer[1]!, 10), schluessel32(name))
   }
-  }
+
   if (schluessel.size === 0) {
     throw new Error(
       'Kein Verschluesselungsschluessel gefunden. Es muss mindestens ENC_KEY_V1 ' +
@@ -78,8 +89,11 @@ const holeVerschluesselungsschluessel = einmal((): Map<number, Buffer> => {
 const holeAktiveVersion = einmal((): number => {
   const version = zahl('ENC_KEY_AKTIV', 1)
   if (!holeVerschluesselungsschluessel().has(version)) {
+    const vorhanden = [...holeVerschluesselungsschluessel().keys()].sort().join(', ')
     throw new Error(
-      `ENC_KEY_AKTIV=${version}, aber ENC_KEY_V${version} ist nicht gesetzt.`,
+      `ENC_KEY_AKTIV=${version}, aber ENC_KEY_V${version} ist nicht gesetzt oder leer. ` +
+        `Vorhanden sind die Versionen: ${vorhanden}. Beim Rotieren zuerst den ` +
+        `neuen Schluessel eintragen, danach ENC_KEY_AKTIV umstellen.`,
     )
   }
   return version

src/lib/validierung/betreute.ts

@@ -8,21 +8,36 @@ import { z } from 'zod'
  * ist, nicht was falsch war.
  */
 
-/** Leere Zeichenketten aus einem Formular sollen zu null werden, nicht zu "". */
+/**
+ * Optionales Textfeld.
+ *
+ * Drei Eingaben muessen zu null werden:
+ *   ""         das Feld war da, blieb aber leer
+ *   null       ausdruecklich geleert
+ *   undefined  das Feld war im Formular ueberhaupt nicht dabei
+ *
+ * Der letzte Fall ist der wichtige: Das kurze Formular der Ersteinrichtung
+ * schickt nur eine Handvoll Felder, das vollstaendige unter Stammdaten
+ * alle. Beide gehen durch dasselbe Schema. Ohne .optional() wuerde die
+ * Ersteinrichtung an zwei Dutzend Feldern scheitern, die gar nicht auf dem
+ * Bildschirm stehen - und die Meldung liesse sich keinem Feld zuordnen.
+ */
 const optionalerText = (max = 200) =>
   z
     .string()
     .trim()
     .max(max, `Bitte höchstens ${max} Zeichen.`)
-    .transform((wert) => (wert === '' ? null : wert))
+    .optional()
     .nullable()
+    .transform((wert) => (wert === undefined || wert === '' ? null : wert))
 
-/** HTML-Datumsfelder liefern "" oder "2026-01-15". */
+/** HTML-Datumsfelder liefern "" oder "2026-01-15" - oder gar nichts. */
 const optionalesDatum = z
   .string()
   .trim()
-  .transform((wert) => (wert === '' ? null : wert))
+  .optional()
   .nullable()
+  .transform((wert) => (wert === undefined || wert === '' ? null : wert))
   .refine((wert) => wert === null || /^\d{4}-\d{2}-\d{2}$/.test(wert), {
     message: 'Bitte ein Datum im Format TT.MM.JJJJ wählen.',
   })

src/lib/version.ts

@@ -17,7 +17,7 @@
  */
 
 /** Muss zur "version" in der package.json passen. */
-export const VERSION = '1.0.0'
+export const VERSION = '1.0.5'
 
 /**
  * Kurzer Git-Stand, beim Bauen hineingereicht:

src/server/actions/betreute.ts

@@ -53,6 +53,49 @@ function felderAusFehler(fehler: z.ZodError): Record<string, string> {
   return ergebnis
 }
 
+/**
+ * Baut die Antwort auf einen Pruefungsfehler.
+ *
+ * Der wichtige Teil ist die Unterscheidung: Beanstandet die Pruefung ein
+ * Feld, das gar nicht abgeschickt wurde, dann passt das Formular nicht zum
+ * Schema - und die Meldung liesse sich auf dem Bildschirm keinem Feld
+ * zuordnen. Der Nutzer saehe "Bitte pruefe die markierten Felder", ohne
+ * dass irgendetwas markiert waere, und kaeme nie weiter.
+ *
+ * Das ist ein Fehler im Programm, keiner in der Eingabe. Er wird deshalb
+ * benannt und ins Serverlog geschrieben, statt ihn dem Nutzer als
+ * Eingabefehler unterzuschieben.
+ */
+function antwortAufFehler(fehler: z.ZodError, formular: FormData): BetreuteZustand {
+  const felder = felderAusFehler(fehler)
+  const gesendet = new Set(formular.keys())
+  const nichtZuordenbar = Object.entries(felder).filter(([feld]) => !gesendet.has(feld))
+
+  if (nichtZuordenbar.length > 0) {
+    const liste = nichtZuordenbar.map(([feld, meldung]) => `${feld}: ${meldung}`).join('; ')
+    console.error(
+      `[stammdaten] Das Formular passt nicht zum Schema. Beanstandet wurden ` +
+        `Felder, die es gar nicht abgeschickt hat: ${liste}`,
+    )
+    return {
+      fehler:
+        'Das Formular passt nicht zur Prüfung — betroffen sind Felder, die ' +
+        'hier gar nicht stehen: ' +
+        nichtZuordenbar.map(([feld]) => feld).join(', ') +
+        '. Das ist ein Fehler in der Anwendung, nicht in deiner Eingabe. ' +
+        'Einzelheiten stehen im Serverlog.',
+      felder,
+      werte: werteMerken(formular),
+    }
+  }
+
+  return {
+    fehler: 'Bitte prüfe die markierten Felder.',
+    felder,
+    werte: werteMerken(formular),
+  }
+}
+
 function werteMerken(formular: FormData): Record<string, string> {
   const werte: Record<string, string> = {}
   for (const [name, wert] of formular.entries()) {
@@ -77,13 +120,7 @@ export async function betreuteAnlegen(
   }
 
   const gelesen = BetreuteSchema.safeParse(formularLesen(formular))
-  if (!gelesen.success) {
-    return {
-      fehler: 'Bitte prüfe die markierten Felder.',
-      felder: felderAusFehler(gelesen.error),
-      werte: werteMerken(formular),
-    }
-  }
+  if (!gelesen.success) return antwortAufFehler(gelesen.error, formular)
 
   const { offen, verschluesselt } = aufteilen(gelesen.data)
 
@@ -134,13 +171,7 @@ export async function betreuteAendern(
   const { benutzer, betreute } = await erfordereZugang(betreuteId, 'STAMMDATEN', 'schreiben')
 
   const gelesen = BetreuteSchema.safeParse(formularLesen(formular))
-  if (!gelesen.success) {
-    return {
-      fehler: 'Bitte prüfe die markierten Felder.',
-      felder: felderAusFehler(gelesen.error),
-      werte: werteMerken(formular),
-    }
-  }
+  if (!gelesen.success) return antwortAufFehler(gelesen.error, formular)
 
   const { offen, verschluesselt } = aufteilen(gelesen.data)
 

tests/stammdaten.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from 'vitest'
+import { BetreuteSchema, formularLesen } from '@/lib/validierung/betreute'
+
+/**
+ * Eingabepruefung der Stammdaten.
+ *
+ * Anlass für diese Datei war ein Fehler im Betrieb: Die Ersteinrichtung
+ * ließ sich nicht abschließen. Das Formular meldete „Bitte prüfe die
+ * markierten Felder", markierte aber keines — weil die Meldungen zu
+ * Feldern gehörten, die dort gar nicht stehen.
+ *
+ * Ursache: Das kurze Formular der Ersteinrichtung schickt neun Felder,
+ * das vollständige unter Stammdaten alle. Beide gehen durch dasselbe
+ * Schema, und die optionalen Felder waren zwar `nullable`, aber nicht
+ * `optional` — ein fehlendes Feld ist `undefined`, nicht `null`.
+ */
+
+/** Die Felder, die das kurze Formular der Ersteinrichtung tatsächlich schickt. */
+function ersteinrichtungsFormular(): FormData {
+  const f = new FormData()
+  f.set('vorname', 'Franziska')
+  f.set('nachname', 'Wilde')
+  f.set('geburtsdatum', '1963-09-23')
+  f.set('betreuungsgericht', 'Lichtenfels')
+  f.set('aktenzeichenGericht', 'XVII 355/25')
+  f.set('bestellungAm', '2025-11-07')
+  f.append('aufgabenkreise', 'VERMOEGENSSORGE')
+  f.append('aufgabenkreise', 'GESUNDHEITSSORGE')
+  f.set('befreiterBetreuer', 'on')
+  f.set('ehrenamtlich', 'on')
+  return f
+}
+
+describe('Ersteinrichtung', () => {
+  it('nimmt das kurze Formular an, obwohl es die meisten Felder nicht schickt', () => {
+    const gelesen = BetreuteSchema.safeParse(formularLesen(ersteinrichtungsFormular()))
+
+    if (!gelesen.success) {
+      const felder = Object.keys(gelesen.error.flatten().fieldErrors).join(', ')
+      throw new Error(`Abgelehnt wegen: ${felder}`)
+    }
+
+    expect(gelesen.data.vorname).toBe('Franziska')
+    expect(gelesen.data.nachname).toBe('Wilde')
+    expect(gelesen.data.geburtsdatum.toISOString()).toBe('1963-09-23T00:00:00.000Z')
+    expect(gelesen.data.bestellungAm?.toISOString()).toBe('2025-11-07T00:00:00.000Z')
+    expect(gelesen.data.aufgabenkreise).toEqual(['VERMOEGENSSORGE', 'GESUNDHEITSSORGE'])
+    expect(gelesen.data.befreiterBetreuer).toBe(true)
+    expect(gelesen.data.ehrenamtlich).toBe(true)
+  })
+
+  it('macht aus nicht gesendeten Feldern null, nicht undefined', () => {
+    const gelesen = BetreuteSchema.parse(formularLesen(ersteinrichtungsFormular()))
+
+    // Diese Felder standen nie auf dem Bildschirm. Sie muessen als null in
+    // der Datenbank landen, sonst schreibt Prisma sie gar nicht.
+    expect(gelesen.heimName).toBeNull()
+    expect(gelesen.diagnosen).toBeNull()
+    expect(gelesen.geburtsname).toBeNull()
+    expect(gelesen.heimEinzugAm).toBeNull()
+    expect(gelesen.bestellungBis).toBeNull()
+    expect(gelesen.aktenzeichenBezirk).toBeNull()
+    expect(gelesen.pflegegrad).toBeNull()
+    expect(gelesen.schwerbehinderungGdB).toBeNull()
+  })
+
+  it('haelt auch das vollstaendige Formular aus', () => {
+    const f = ersteinrichtungsFormular()
+    // So kommt es aus dem Bearbeitungsformular: alle Felder da, viele leer.
+    for (const feld of [
+      'anrede', 'geburtsname', 'geburtsort',
+      'heimName', 'heimStrasse', 'heimPlz', 'heimOrt', 'heimZimmer', 'heimTelefon',
+      'fruehereStrasse', 'frueherePlz', 'fruehererOrt',
+      'krankenkasse', 'krankenversichertennummer', 'pflegekasse',
+      'schwerbehinderungMerkzeichen', 'diagnosen', 'ermittelterWille',
+      'aufgabenkreiseFreitext', 'aktenzeichenBezirk', 'aktenzeichenSozialamt',
+      'rentenversicherungsnummer', 'steuerId', 'notizen',
+    ]) {
+      f.set(feld, '')
+    }
+    for (const feld of ['heimEinzugAm', 'pflegegradSeit', 'pflegegradBescheidVom', 'bestellungBis']) {
+      f.set(feld, '')
+    }
+    f.set('pflegegrad', '')
+    f.set('schwerbehinderungGdB', '')
+
+    const gelesen = BetreuteSchema.safeParse(formularLesen(f))
+    expect(gelesen.success, 'Leere Felder duerfen nicht abgelehnt werden').toBe(true)
+  })
+
+  it('nimmt ausgefuellte Angaben unveraendert an', () => {
+    const f = ersteinrichtungsFormular()
+    f.set('heimName', '  Seniorenzentrum St. Katharina  ')
+    f.set('pflegegrad', '3')
+    f.set('diagnosen', 'COPD GOLD III')
+
+    const gelesen = BetreuteSchema.parse(formularLesen(f))
+    // Fuehrende und nachlaufende Leerzeichen fliegen raus.
+    expect(gelesen.heimName).toBe('Seniorenzentrum St. Katharina')
+    expect(gelesen.pflegegrad).toBe(3)
+    expect(gelesen.diagnosen).toBe('COPD GOLD III')
+  })
+
+  it('besteht weiterhin auf Vorname, Nachname und Geburtsdatum', () => {
+    const f = new FormData()
+    f.set('vorname', '')
+    f.set('nachname', '')
+    f.set('geburtsdatum', '')
+
+    const gelesen = BetreuteSchema.safeParse(formularLesen(f))
+    expect(gelesen.success).toBe(false)
+
+    if (!gelesen.success) {
+      const felder = gelesen.error.flatten().fieldErrors
+      expect(Object.keys(felder).sort()).toEqual(['geburtsdatum', 'nachname', 'vorname'])
+    }
+  })
+
+  it('weist ein Geburtsdatum in der Zukunft ab', () => {
+    const f = ersteinrichtungsFormular()
+    f.set('geburtsdatum', '2099-01-01')
+
+    const gelesen = BetreuteSchema.safeParse(formularLesen(f))
+    expect(gelesen.success).toBe(false)
+    if (!gelesen.success) {
+      expect(gelesen.error.flatten().fieldErrors.geburtsdatum?.[0]).toMatch(/Zukunft/)
+    }
+  })
+
+  it('weist ein unfertiges Datum ab, statt es stillschweigend zu verwerfen', () => {
+    const f = ersteinrichtungsFormular()
+    f.set('bestellungAm', '2025-11')
+
+    const gelesen = BetreuteSchema.safeParse(formularLesen(f))
+    expect(gelesen.success).toBe(false)
+  })
+})

tests/umgebung.test.ts

@@ -0,0 +1,105 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+/**
+ * Auswertung der Umgebungsvariablen.
+ *
+ * Der Anlass für diese Datei war ein Fehler im Betrieb: docker compose
+ * reicht `ENC_KEY_V2` immer durch — mit leerem Wert, wenn in der .env
+ * keiner steht. Die Schlüsselsammlung erkannte Schlüssel aber am
+ * Variablennamen statt am Inhalt, fand also ein leeres `ENC_KEY_V2` und
+ * brach ab. Die Meldung lautete „ENC_KEY_V2 fehlt", obwohl niemand einen
+ * zweiten Schlüssel wollte.
+ *
+ * Jede Prüfung hier lädt `@/lib/env` frisch, weil die Werte beim ersten
+ * Zugriff gemerkt werden.
+ */
+
+const ECHT = Buffer.alloc(32, 7).toString('base64')
+const ECHT_ZWEI = Buffer.alloc(32, 9).toString('base64')
+
+let vorher: NodeJS.ProcessEnv
+
+async function frischesEnv() {
+  // Leert die Modulregistrierung, damit der naechste Import das Modul neu
+  // auswertet - die Schluessel werden sonst nur beim ersten Mal gelesen.
+  vi.resetModules()
+  const { env } = await import('@/lib/env')
+  return env
+}
+
+beforeEach(() => {
+  vorher = { ...process.env }
+  for (const name of Object.keys(process.env)) {
+    if (/^ENC_KEY_V\d+$/.test(name)) delete process.env[name]
+  }
+  delete process.env.ENC_KEY_AKTIV
+})
+
+afterEach(() => {
+  process.env = vorher
+})
+
+describe('Verschlüsselungsschlüssel aus der Umgebung', () => {
+  it('nimmt einen einzelnen Schlüssel an', async () => {
+    process.env.ENC_KEY_V1 = ECHT
+
+    const env = await frischesEnv()
+    expect([...env.verschluesselungsschluessel.keys()]).toEqual([1])
+    expect(env.aktiveSchluesselversion).toBe(1)
+  })
+
+  it('überspringt eine leere Schlüsselvariable', async () => {
+    // Genau das setzt docker compose, wenn in der .env kein zweiter
+    // Schlüssel steht: ENC_KEY_V2: ${ENC_KEY_V2:-}
+    process.env.ENC_KEY_V1 = ECHT
+    process.env.ENC_KEY_V2 = ''
+
+    const env = await frischesEnv()
+    expect([...env.verschluesselungsschluessel.keys()]).toEqual([1])
+    expect(env.aktiveSchluesselversion).toBe(1)
+  })
+
+  it('überspringt eine Variable, in der nur Leerzeichen stehen', async () => {
+    process.env.ENC_KEY_V1 = ECHT
+    process.env.ENC_KEY_V2 = '   '
+
+    const env = await frischesEnv()
+    expect([...env.verschluesselungsschluessel.keys()]).toEqual([1])
+  })
+
+  it('nimmt beide Schlüssel an, wenn wirklich rotiert wird', async () => {
+    process.env.ENC_KEY_V1 = ECHT
+    process.env.ENC_KEY_V2 = ECHT_ZWEI
+    process.env.ENC_KEY_AKTIV = '2'
+
+    const env = await frischesEnv()
+    expect([...env.verschluesselungsschluessel.keys()].sort()).toEqual([1, 2])
+    expect(env.aktiveSchluesselversion).toBe(2)
+  })
+
+  it('sagt beim Rotieren deutlich, wenn der neue Schlüssel fehlt', async () => {
+    process.env.ENC_KEY_V1 = ECHT
+    process.env.ENC_KEY_V2 = ''
+    process.env.ENC_KEY_AKTIV = '2'
+
+    const env = await frischesEnv()
+    expect(() => env.aktiveSchluesselversion).toThrow(/ENC_KEY_AKTIV=2/)
+    // Die Meldung nennt, was da ist, und die richtige Reihenfolge.
+    expect(() => env.aktiveSchluesselversion).toThrow(/Vorhanden sind die Versionen: 1/)
+    expect(() => env.aktiveSchluesselversion).toThrow(/zuerst den neuen Schluessel/)
+  })
+
+  it('beschwert sich, wenn gar kein Schlüssel gesetzt ist', async () => {
+    process.env.ENC_KEY_V2 = ''
+
+    const env = await frischesEnv()
+    expect(() => env.verschluesselungsschluessel).toThrow(/mindestens ENC_KEY_V1/)
+  })
+
+  it('weist einen Schlüssel falscher Länge ab', async () => {
+    process.env.ENC_KEY_V1 = Buffer.alloc(16, 1).toString('base64')
+
+    const env = await frischesEnv()
+    expect(() => env.verschluesselungsschluessel).toThrow(/32 Bytes/)
+  })
+})