# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Naming: pflegepilot_v3's product is now branded "MeinPflegeFuchs" (renamed 2026-07-24)

The `pflegepilot_v3` product was renamed from "Pflegepilot" to **"MeinPflegeFuchs"** (domain: meinpflegefuchs.de, ordered via Strato) — there turned out to be several unrelated existing apps/services already using "Pflegepilot" or very close variants, discovered when checking candidate replacement names for trademark/confusion risk (a lesson worth repeating: the German Pflege-app naming space is extremely crowded — a `"Pflege" + descriptive word` pattern is very likely to already be taken by a real competing service; "MeinPflegeFuchs" was chosen specifically because it's a mascot-style name rather than a literal descriptor).

- **Every user-visible string, generated-document footer, email subject, page title/metadata, and the two legal texts under `rechtstexte/` were updated** to "MeinPflegeFuchs" — see the `changelog_seed.py` entry (version 1.1.0) for the user-facing announcement of the rename.
- **The `pflegepilot_v3` directory name, package/module names, DB names, and NAS deployment path (`/Dockers/pflege`) were deliberately left unchanged** — renaming those would touch git history, every absolute path referenced throughout this file and past deployment scripts, and the NAS's manually-maintained (non-git) copy, for zero user-facing benefit. Don't be confused that the folder still says "pflegepilot" while the product itself is called MeinPflegeFuchs — that's intentional, not a leftover.
- Only scope was `pflegepilot_v3` — `pflegepilot_alpha_v2` (the old, separately-running Flask app) still legitimately calls itself Pflegepilot and was not touched.
- Historical references to "Pflegepilot" — e.g. the changelog's 1.0.0 entry, or anything below in this file describing what was true *at the time it was written* — are accurate records of the past and were deliberately left as-is rather than rewritten; only forward-looking/current-state documentation and all actual product code got renamed. When adding new documentation to this file, use "MeinPflegeFuchs", not "Pflegepilot".
- `einstellungen.firmenname` (sidebar branding / PDF-footer company name) is a separate, operator-configured field for the *legal entity* name (currently "Daniel Barac Onlinedienste" in production) — unrelated to the product brand name and intentionally not touched by this rename.

## Git-Workflow: Pull Requests über Gitea statt Direkt-Push auf `master` (ab 2026-08-10)

Ab sofort läuft alle Arbeit an diesem Repo über den Remote `origin` (`ssh://git@192.168.1.222:2222/admin/pflegefuchs.git`, self-hosted Gitea auf dem NAS, Web-UI unter `http://192.168.1.222:3666`) — Betreiber-Wunsch, um bei mehreren gleichzeitigen Änderungen die Übersicht zu behalten, statt jede Änderung nur in diesem CLAUDE.md-Dokument und einzelnen `git log`-Commits nachzuvollziehen.

- **Kein Direkt-Push auf `master` mehr durch Claude.** Jede abgeschlossene, in sich sinnvolle Änderung (ein Feature, ein Bugfix, ein Tester-Feedback-Punkt aus `Feedbackfromtester.md`) bekommt einen eigenen Branch, wird dorthin committet/gepusht und als Pull Request gegen `master` geöffnet — **ein PR pro Feature/Feedback-Punkt**, nicht ein Sammel-PR pro Konversation/Session.
- **Branch-Namensschema**: `feature/<kurzbeschreibung>` für neue Funktionen, `fix/<kurzbeschreibung>` für Bugfixes, jeweils kurze englische oder deutsche Kebab-Case-Beschreibung (z. B. `feature/notfallkarte-zeitstempel`, `fix/pdf-upload-passwortgeschuetzt`).
- **PR wird nicht automatisch gemerged** — der Betreiber merged jeden PR manuell nach eigener Durchsicht über die Gitea-Weboberfläche. Das ist die eigentliche Absicht dieses Workflows (Review-Gate + Übersicht), nicht nur eine Formalität — Claude darf einen von sich selbst geöffneten PR nicht selbst mergen, auch nicht auf Nachfrage "mach doch gleich fertig", ohne das explizit noch einmal zu bestätigen.
- **Werkzeug**: `tea` (offizielle Gitea-CLI, bereits unter `admin`-Login auf diesem Rechner eingerichtet, `tea login list` zeigt den Eintrag) — PRs werden per `tea pr create` geöffnet, nicht per Klick im Web-UI. `gh` (GitHub CLI) ist ebenfalls installiert, aber **nicht** für dieses Repo relevant, da hier kein GitHub im Spiel ist.
- **PR-Titel/-Beschreibung**: Titel entspricht dem, was sonst die Commit-Message-Subject-Zeile gewesen wäre (deutsch, gleicher Stil wie die bisherigen Commit-Messages/Changelog-Einträge); Beschreibung fasst die Änderung stichpunktartig zusammen, mit Verweis auf den zugehörigen Tester-Feedback-Punkt (T-Nummer) falls zutreffend und auf den neuen `changelog_seed.py`-Versionseintrag, falls einer dazugehört.
- **Gilt für alle Änderungen an diesem Repo**, nicht nur `pflegepilot_v3` — auch Änderungen an `pflegepilot_alpha_v2` oder an diesem `CLAUDE.md` selbst laufen künftig über einen PR, keine Ausnahme für "nur Dokumentation" oder "nur ein Einzeiler".
- Dieser Workflow-Abschnitt selbst wurde als erster PR unter dem neuen Schema eingeführt (zusammen mit dem bereits fertigen Notfallkarte-Zeitstempel-Feature, siehe unten) — als lebendes Beispiel, nicht nur als Ankündigung.

## Notfall-Card-Bereich im Bearbeiten-Formular hervorgehoben (pflegepilot_v3 only, 2026-08-08)

Betreiber-Feedback: die Notfall-Card-Felder (Blutgruppe, Allergien, Medikamente, Notfallkontakt) im "Patient bearbeiten"-Formular waren nur durch eine kleine graue Zwischenüberschrift von den übrigen Abschnitten (Persönliche Daten, Adresse, Krankenversicherung, Pflegesituation) abgesetzt — optisch identisch zu jedem anderen Abschnittstitel im selben durchlaufenden weißen Formular, dadurch leicht zu übersehen.

- Der komplette Notfall-Card-Block ist jetzt eine eigene, farblich abgesetzte Box (`getAccent("red")`, dieselbe Akzentfarbe wie die "Notfall-Card"-Sektion in der Patientenakte selbst — bewusste Konsistenz, nicht neu erfunden) mit eigenem Rand, Verlaufshintergrund und einem erklärenden Untertitel ("Optional – nur sichtbar für Personen mit dem Notfall-Link/QR-Code … unabhängig vom Rest dieses Formulars").
- Kein neues Farbschema eingeführt, nur der bereits bestehende `AccentClasses`-Mechanismus aus `lib/theme.ts` wiederverwendet.
- Verifiziert per echtem Browser-Screenshot gegen `https://meinpflegefuchs.de/patienten/7/bearbeiten`.

## Fortschrittsanzeige beim PDF-Upload/OCR (pflegepilot_v3 only, 2026-08-08)

Betreiber-Feedback: weder der normale Datei-Upload noch der Kamera-Scan zeigten irgendein sichtbares Zeichen, dass im Hintergrund gearbeitet wird (Upload + Texterkennung), solange die Anfrage lief — ein Laie könnte deshalb versehentlich mehrfach dieselbe Datei hochladen, weil nicht ersichtlich ist, dass überhaupt etwas passiert.

- **`hochladen.isPending`** (React Query, bislang ungenutzt für UI-Feedback) steuert jetzt: Datei-Input wird deaktiviert (`disabled`, verhindert die Doppel-Upload-Sorge strukturell, nicht nur kosmetisch), ein Hinweistext ("Wird hochgeladen und nach durchsuchbarem Text durchsucht – bitte kurz warten, nicht erneut hochladen…") sowie ein unbestimmter Fortschrittsbalken erscheinen. Gleiches Muster für den Kamera-Scan (`DokumentScan.tsx`, `hochladenLaeuft`-Prop) ergänzt — dort fehlte bislang auch der "+ weitere Seite"-Button ein `disabled` während des Uploads.
- **Bewusst kein echter Prozentwert**: ein tatsächlicher Upload-Fortschritt (Bytes gesendet) wäre technisch möglich (`XMLHttpRequest` statt `fetch`), aber irreführend — bei einer PDF ist der Byte-Upload in Sekundenbruchteilen fertig, während die serverseitige OCR-Verarbeitung (die eigentliche Wartezeit) noch mehrere Sekunden bis über eine Minute dauern kann (bei einem 15-seitigen Testdokument ohne Textebene ca. 25s). Ein Balken, der bei 100% "fertig" aussieht, während im Hintergrund noch OCR läuft, hätte das ursprüngliche Problem eher verschlimmert als gelöst. Stattdessen ein unbestimmter ("indeterminate") Balken mit durchlaufendem Segment (`@keyframes fortschritt-durchlauf` in `globals.css`) — ehrlich darüber, dass keine Prozentangabe messbar ist, aber klar sichtbar, dass gearbeitet wird.
- **Farbe grau+grün statt grau-in-grau** (Nachbesserung noch in derselben Sitzung nach Betreiber-Feedback: auf dem gelben "Dokumente"-Kartenhintergrund war ein reines Grau-in-Grau kaum erkennbar): grauer Balken-Grund (`bg-slate-300`), grünes durchlaufendes Segment (`bg-emerald-500`).
- **Verifiziert per echtem Browser-Test** gegen `https://meinpflegefuchs.de` (Claude-in-Chrome-Skill, echter eingeloggter Nutzer-Account): ein 15-seitiges synthetisches Test-PDF ohne Textebene (erzwingt den OCR-Fallback auf jeder Seite) hochgeladen — deaktivierte Datei-Eingabe und der grün-graue Balken blieben sichtbar über die gesamte, spürbar lange Verarbeitungszeit (~25s), Eingabe wurde danach automatisch wieder freigegeben.
- **Zwischenfall während der Verifikation**: beim manuellen Aufräumen der Test-Uploads über die UI wurde durch einen Koordinaten-Klick auf eine zwischenzeitlich verschobene Listenposition versehentlich eine echte, bereits vorhandene Nutzerdatei (`Gemini_Generated_Image_....png`) gelöscht statt einer eigenen Testdatei — nicht wiederherstellbar, da harte Löschung ohne Papierkorb. Dem Nutzer sofort transparent gemeldet. **Lehre für künftige UI-Tests dieser Art**: bei listenbasierten Lösch-Aktionen in einer sich dynamisch verändernden Liste (Umsortierung durch parallele Uploads) ausschließlich über `find`/Element-Referenzen klicken, niemals über zwischengespeicherte Pixel-Koordinaten aus einem älteren Screenshot — und bei Unsicherheit über den tatsächlichen Zustand direkt die Datenbank abfragen statt der Bildschirmanzeige zu vertrauen.
- Changelog-Eintrag `1.18.3`.

## Sidebar sticky statt im Dokumentenfluss (pflegepilot_v3 only, 2026-08-08)

Betreiber-Feedback: auf langen Seiten musste man bis ganz nach unten scrollen, um "Abmelden" oder den eigenen Kontonamen in der Sidebar zu sehen. Ursache: das `<aside>` in `(app)/layout.tsx` war auf Desktop-Breite (`lg:`) nur `lg:static` — ein normales Element im Dokumentenfluss, kein `position:fixed`/`sticky`. Da es als Flex-Geschwister neben der Hauptinhaltsspalte steht (`<div className="flex min-h-screen">`), streckt das Standard-Flexbox-Verhalten (`align-items:stretch`) die Sidebar auf die Höhe des Hauptinhalts — bei einer langen Seite (z. B. eine umfangreiche Patientenakte) wurde die Sidebar dadurch künstlich sehr hoch, und da `nav` darin `flex-1` ist, rutschten der Konto-/Abmelden-Block und die Rechtstext-Links ganz ans Ende dieser künstlich gestreckten Höhe — nur durch Scrollen der **gesamten Seite** erreichbar, nicht nur der Sidebar selbst.

- **Fix**: `lg:static` → `lg:sticky lg:top-0 lg:h-screen` — die Sidebar bekommt jetzt auf Desktop-Breite eine feste, an den Viewport gebundene Höhe und bleibt beim Scrollen des Hauptinhalts an ihrer Position stehen, unabhängig davon, wie lang die jeweilige Seite ist. Der bereits bestehende `overflow-y-auto` auf dem `nav`-Element bleibt die Absicherung für den (aktuell nicht erreichten) Fall, dass allein die Navigationspunkte je die Viewport-Höhe überschreiten.
- Mobile/Tablet-Verhalten (`fixed inset-y-0` unterhalb von `lg:`) war bereits vorher schon viewport-fixiert und ist von dieser Änderung nicht betroffen.
- **Verifiziert per echtem Browser-Test** (Claude-in-Chrome-Skill) direkt gegen `https://meinpflegefuchs.de/admin` (eingeloggte Session des Betreibers) — Screenshot vor und nach starkem Scrollen im Hauptinhalt bestätigt: Sidebar-Kopf, Navigation und der "Daniel"/"Abmelden"-Block bleiben pixelgenau an derselben Position, während der Hauptinhalt darunter durchscrollt. **Lokale Browser-Verifikation war hierfür nicht möglich** — die lokale `.env` hat `NEXT_PUBLIC_API_URL` bekanntermaßen auf die echte NAS-LAN-IP statt `localhost` gesetzt (siehe Memory-Eintrag zu dieser Falle), wodurch der lokal gebaute Frontend-Container beim Testen im Browser API-Calls an die NAS statt an sich selbst schickt und auf "Lädt…" hängen bleibt — kein neuer Bug, sondern dieselbe bereits dokumentierte Umgebungs-Falle, nur diesmal zum ersten Mal in einer echten Browser-Session statt nur per curl bemerkt.
- Changelog-Eintrag `1.18.1`.

## T30-Nachtrag: Volltextsuche auch für hochgeladene PDFs + Admin-Nachverarbeitung (pflegepilot_v3 only, 2026-08-08)

Betreiber-Feedback zum ursprünglichen T30 (siehe unten): die durchsuchbaren PDFs/Volltextsuche deckten bislang nur per Kamera gescannte Dokumente ab — ganz normal hochgeladene PDFs (z. B. ein per E-Mail erhaltener oder am PC erstellter Bescheid) blieben unauffindbar, obwohl das bereits bestehende Suchfeld in der Patientenakte ("Dokumente durchsuchen…") laut Beschreibung genau das können sollte. Zwei Erweiterungen, per `AskUserQuestion` vorab geklärt (rückwirkende Nachverarbeitung ja/nein — Betreiber wählte "auch rückwirkend").

- **Kein neues Suchfeld nötig**: die bereits bestehende clientseitige Such-Eingabe in der Patientenakte (`patienten/[id]/page.tsx`, seit T30) filtert bereits auf `bezeichnung` **und** `ocr_text` — sie fand bei hochgeladenen PDFs nur deshalb nichts, weil `ocr_text` dort bislang immer `null` blieb. Mit dieser Erweiterung funktioniert dasselbe Suchfeld jetzt auch für PDFs, ohne dass am Frontend etwas Neues gebaut werden musste — nur der Platzhaltertext wurde ergänzt ("…und hochgeladener PDFs").
- **`app/dokument_scan.py: pdf_text_extrahieren()`**: neue, zweistufige Funktion je PDF-Seite. Liest zuerst per PyMuPDF (`fitz`) eine ggf. bereits vorhandene Textebene aus (`page.get_text()`) — verlustfrei und um Größenordnungen schneller als OCR, der häufigste Fall bei digital erzeugten PDFs. Nur wenn eine Seite praktisch keinen Text liefert (< 20 Zeichen, `MIN_TEXTLAENGE_JE_SEITE`, typischerweise eine eingescannte Seite ohne eigene Textebene), wird **nur diese Seite** zusätzlich per `page.get_pixmap()` gerendert und per Tesseract-OCR verarbeitet — ein gemischtes PDF (z. B. eine Textseite plus eine eingescannte Beilage) bekommt so je Seite die passende Methode. Gleiche Kulanz-Haltung wie beim bestehenden Kamera-Scan-OCR: ein Fehler auf einzelnen Seiten überspringt nur diese Seite, ein komplett unlesbares PDF liefert `None` statt den Upload/die Nachverarbeitung scheitern zu lassen.
- **Neue Abhängigkeit `PyMuPDF`** (`requirements.txt`, importiert als `import pymupdf as fitz` — der ältere `import fitz`-Name ist in aktuellen PyMuPDF-Versionen deprecated). Bewusste Abweichung von der ursprünglichen T30-Entscheidung "pypdf statt PyMuPDF/fitz" (siehe dortiger Kommentar) — die galt für reines Seiten-Zusammenfügen beim Kamera-Scan, wofür pypdf ausreicht; hier wird dagegen tatsächlich eine PDF-Seite als Bild gerendert (OCR-Fallback), das kann pypdf nicht. PyMuPDF ist dafür die schlankere Wahl gegenüber z. B. `pdf2image`+poppler-utils (kein zusätzliches System-Paket im Dockerfile nötig, reine Wheel-Installation).
- **`routers/dokumente.py: hochladen()`** (der normale Einzeldatei-Upload-Endpunkt, nicht der Kamera-Scan-Endpunkt) ruft `pdf_text_extrahieren()` jetzt automatisch auf, wenn die Dateiendung `.pdf` ist, und speichert das Ergebnis in `Dokument.ocr_text` — dieselbe Spalte wie beim Kamera-Scan, kein neues Schema-Feld nötig. Gilt nur für neue Uploads ab diesem Deploy.
- **Rückwirkende Nachverarbeitung**: neuer Endpunkt `POST /api/admin/dokumente/pdf-ocr-nachtrag` (admin-only, bewusst **ohne** Begründungspflicht/Audit-Log-Eintrag — reine additive Anreicherung bereits zugänglicher Daten, kein Datenexport/-eingriff mit Beweiswert, gleiche Einordnung wie die Test-Mail-Funktion) verarbeitet alle bereits bestehenden `Dokument`-Zeilen mit `dateiname LIKE '%.pdf'` und `ocr_text IS NULL` über **alle Konten hinweg** in einem Rutsch (Dokumentenmenge dieser App bleibt insgesamt klein) und liefert eine Zusammenfassung (`gefunden`/`aktualisiert`/`ohne_erkennbaren_text`/`fehlgeschlagen`/`datei_fehlt`) zurück. Frontend: neue Karte "PDF-Volltext nachtragen" im Admin-Dashboard (Akzentfarbe `lime`, bis dahin ungenutzt) mit einem einzelnen Button, kein Formular nötig.
- **End-to-end gegen die echte lokale Docker-Postgres-Instanz verifiziert**: drei Testfälle direkt gegen `pdf_text_extrahieren()` (ein synthetisches Text-PDF → korrekt per `get_text()` erkannt ohne OCR, ein synthetisches Bild-only-PDF → korrekt per OCR-Fallback erkannt, ein kaputtes PDF → sauber `None` statt Crash), danach der komplette HTTP-Weg: echter Upload eines Text-PDFs über `POST /api/patienten/{pid}/dokumente` liefert `ocr_text` sofort in der Response, `GET .../dokumente?suche=Aktenzeichen` (ein Wort, das nur im OCR-Text steht, nicht in der Bezeichnung) findet das Dokument korrekt, ein Kontroll-Upload einer `.txt`-Datei bestätigt `ocr_text=null` (keine Regression für Nicht-PDF-Typen). Der Nachtrags-Endpunkt wurde mit einem künstlich auf `NULL` zurückgesetzten `ocr_text` getestet (korrekt 1 gefunden/1 aktualisiert) sowie auf Idempotenz geprüft (zweiter Aufruf: 0 gefunden). `docker compose build web` fehlerfrei (Next.js-Routenmanifest zeigt `/admin` weiterhin als erwartete Route). Testdaten (2 Test-Dokumente, 1 Test-Admin-Konto) danach wieder vollständig entfernt.
- Changelog-Eintrag `1.18.0` ergänzt, vorab gegen den lokalen `GET /api/changelog`-Stand abgeglichen (neuester Eintrag war `1.17.0`), keine Kollision.

### Bug nach dem Deploy gefunden und behoben: bestimmte PDFs ließen sich gar nicht mehr hochladen (2026-08-08)

Betreiber-Meldung noch am selben Tag: unter "Dokumente → Datei hochladen" ließ sich mit einem Test-Account keine PDF hochladen (Bilder funktionierten weiterhin). Root Cause: `pdf_text_extrahieren()` wrappte nur `fitz.open()` selbst gegen Fehler ab, nicht aber `seite.get_text()` — bei PDFs, die zwar ohne Fehler geöffnet werden können, deren Seiteninhalt aber ohne Passwort nicht lesbar ist (`needs_pass=1`, z. B. ein mit Owner-Passwort geschütztes PDF, wie es manche Kassen-/Behörden-PDF-Systeme erzeugen), warf `get_text()` beim ersten Seitenzugriff einen `ValueError: document closed or encrypted`. Da dieser Aufruf in `routers/dokumente.py: hochladen()` **nach** dem Schreiben der Datei auf die Platte, aber **vor** dem Anlegen der `Dokument`-DB-Zeile passierte, brach der komplette Request mit einem 500er ab, bevor die DB-Zeile erstellt wurde — die Datei lag zwar auf der Platte, tauchte aber nirgends in der App auf.

- **Reproduziert**: ein mit `PDF_ENCRYPT_AES_256` und einem echten User-Passwort erzeugtes Test-PDF (nicht entschlüsselt geöffnet) löste exakt den beschriebenen `ValueError` aus — bestätigt vor dem Fix als echter Crash, nach dem Fix als sauberes `None`.
- **Fix, zweifach abgesichert** (gleiches Muster wie der bereits bestehende OCR-Fallback in derselben Funktion): `seite.get_text()` bekam ein eigenes `try/except`, zusätzlich fängt ein äußeres `except` um die gesamte Seiten-Schleife auch andere, nicht seitenspezifische Fehler ab (liefert dann den bis dahin erkannten Text statt komplett zu scheitern). Als zweite Sicherheitsebene wurde der Aufruf in `routers/dokumente.py: hochladen()` selbst ebenfalls in ein `try/except` gepackt — der Upload darf unter keinen Umständen an der Texterkennung scheitern, auch nicht durch einen künftigen, heute noch unbekannten Fehlerfall in `pdf_text_extrahieren()`.
- **Keine verwaisten Dateien gefunden**: ein Abgleich aller Dateien auf der Platte gegen die `Dokument`-Tabelle (NAS) ergab keine Datei ohne zugehörige DB-Zeile — der genaue vom Betreiber getestete Fall bleibt daher nicht zweifelsfrei rekonstruiert (das reproduzierte Passwort-Szenario ist der plausibelste Kandidat für dieselbe Fehlerklasse, aber nicht mit Sicherheit exakt derselbe Auslöser).
- Verifiziert per echtem HTTP-Upload des Passwort-PDFs gegen die lokale Docker-Instanz (201 statt 500, `ocr_text=null`) sowie eines normalen Text-PDFs als Regressionstest (weiterhin korrekt erkannter Text). Changelog-Eintrag `1.18.2`.

## Notfall-Card: "Zuletzt aktualisiert am"-Zeitstempel (pflegepilot_v3 only, 2026-08-08)

Betreiber-Feedback: weder intern (Patientenakte) noch extern (öffentliche Notfall-Card-Seite) war erkennbar, wann die angezeigten Notfalldaten zuletzt eingegeben/geändert wurden.

- **Neue Spalte `Patient.notfallkarte_daten_aktualisiert_am`** (Migration `e2f5c8a1b4d7`) — bewusst ein eigenes Feld statt `Patient.geaendert_am` wiederzuverwenden, das bei **jeder** Patientenänderung (Adresse, Telefonnummer, …) mitläuft und damit fälschlich häufiger "aktualisiert" wirken würde, als es für die Notfalldaten selbst zutrifft.
- **Zwei Stellen setzen den Zeitstempel**, beide nur bei einer echten inhaltlichen Änderung:
  1. `PUT /api/patienten/{pid}` (`routers/patienten.py`): vergleicht bei jedem Speichern die 5 Notfall-Felder (`blutgruppe`, `allergien`, `notfallkarte_medikamente`, `notfallkontakt_name`, `notfallkontakt_telefon`) explizit gegen die bisherigen Werte (`NOTFALLKARTE_FELDER`-Set) — bewusst nicht "war das Feld im Request enthalten", da das Bearbeiten-Formular bei jedem Speichern alle Felder mitschickt, auch unveränderte. Nur bei mindestens einer echten Wertänderung wird der Zeitstempel neu gesetzt.
  2. `POST /api/patienten/{pid}/patientenverfuegung` (`routers/briefe.py`): eine neu eingereichte Patientenverfügung zählt ebenfalls als "Notfalldaten aktualisiert" (sie wird auf der Notfall-Card mit angezeigt/verlinkt) — nur beim echten Neuanlage-Pfad, nicht wenn `_juengster_duplikat()` einen bereits bestehenden Antrag zurückgibt.
- **Anzeige an beiden Stellen**: intern im "Notfall-Card"-Collapsible der Patientenakte (nur wenn die Karte aktiv ist, direkt unter dem Titel) sowie extern auf der öffentlichen `/notfallkarte/[token]`-Seite (unter Vorname/Nachname/Geburtsdatum) — beide mit identischem `formatZeitpunkt()`-Format ("TT.MM.JJJJ, HH:MM Uhr"), bewusst dieselbe kleine Hilfsfunktion an beiden Stellen dupliziert statt in ein gemeinsames Modul ausgelagert (unterschiedliche Nachbarschaft: Server- vs. Client-Component).
- **Verifiziert** end-to-end gegen die lokale Docker-Instanz (Feldänderung setzt den Zeitstempel, ein reines Ändern eines NICHT-Notfall-Felds bei unveränderten Notfall-Werten setzt ihn nachweislich NICHT neu, öffentlicher Endpunkt liefert denselben Wert, neue Patientenverfügung bumpt ihn erneut) sowie live auf der NAS gegen den echten Test-Account (Allergien-Feld testweise geändert und zurückgesetzt, Zeitstempel beide Male korrekt aktualisiert, intern sichtbar bestätigt per Screenshot). Der öffentliche Seiten-Teil wurde bewusst **nicht** am echten, bereits aktiven Token des Testpatienten verifiziert, um dessen laufenden QR-Code/Link nicht durch eine nötige Neu-Generierung ungültig zu machen — Logik ist identisch zur bereits lokal bestätigten.
- Changelog-Eintrag `1.18.5`.

## Apple-/Google-Wallet-Passes für die Notfall-Card: bewusst weiterhin zurückgestellt (Stand 2026-08-08)

Anschlussfrage des Betreibers nach T37 ("ist die Notfallkarte schon wallet-ready?"), zusammen mit den technischen Rahmenbedingungen besprochen, aber (noch) nicht umgesetzt:

- **Technischer Unterschied zwischen den beiden Plattformen, falls das je angegangen wird**: Ein Apple-`.pkpass` lässt sich komplett offline/serverseitig erzeugen und direkt von der eigenen API ausliefern — bei Verzicht auf `webServiceURL`-Live-Updates müsste **keinerlei** Daten (auch nicht der Token) an Apple übertragen werden, nur ein einmalig zu beschaffendes Signier-Zertifikat (Apple-Developer-Program, 99 $/Jahr) ist nötig. Google Wallet ist dagegen architekturell ein Cloud-Dienst — ein Pass-Objekt muss zwingend über Googles API oder ein selbst signiertes JWT bei Google erzeugt werden, das lässt sich nicht umgehen. Der einzig sinnvolle Kompromiss dafür: der Wallet-Pass enthält nur den bereits bestehenden QR-Code/Token + einen neutralen Titel ("Notfallkarte"), nie die eigentlichen Gesundheitsdaten (Blutgruppe, Allergien, Medikamente, Notfallkontakt bleiben ausschließlich serverseitig, wie es die App bei T37 ohnehin schon so gebaut hat) — Google sähe damit zwar den Token, aber nie die echten Daten.
- **Betreiber-Entscheidung**: Thema bewusst auf einen späteren Zeitpunkt verschoben, um aktuell (noch keine zahlenden Nutzer) die laufenden Kosten (v. a. der Apple-Developer-Account) zu sparen. Kein technisches Hindernis, reine Kostenentscheidung — bei Bedarf jederzeit nachholbar, das bestehende Token-Design (kein Ablauf, kein Einmalgebrauch, siehe T37 unten) ist bereits absichtlich wallet-kompatibel angelegt.

## T37: Notfall-Card (öffentlicher, unauthentifizierter QR-Code-Notfallzugriff) (pflegepilot_v3 only, 2026-08-06)

Letzter offener Punkt aus dem Tester-Feedback-Backlog (`Feedbackfromtester.md`) — laut Backlog "der aufwendigste und sicherheitskritischste Einzelpunkt der gesamten Liste", explizit als "Plan nötig" markiert. Wunsch: ein QR-Code/Link, über den z. B. ein Notarzt im Ernstfall ausgewählte Daten einer gepflegten Person ohne Login einsehen kann. Vier Weichenstellungen vorab per `AskUserQuestion` geklärt, danach Plan-Mode-Durchlauf (`~/.claude/plans/lucky-sparking-rain.md`) vor der Umsetzung — gleiches Vorgehen wie bei T35/T36.

- **Geklärte Entscheidungen**: (1) Stufenplan — erst eine öffentliche Web-Ansicht, echte Apple-/Google-Wallet-Passes explizit als spätere Ausbaustufe zurückgestellt (kostenpflichtiger Apple-Developer-Account + Zertifikats-Setup, Google-Cloud-Projekt). (2) Datenumfang: Patientenverfügung **plus** feste Notfall-Basisdaten (Blutgruppe, Allergien, aktuelle Medikamente, Notfallkontakt) — kein frei konfigurierbarer Feld-Picker über alle Patientendaten. (3) Widerruf: ein jederzeit neu generierbarer Token pro Patient, kein separater Pause-Schalter. (4) Zugriffs-Log: IP-Adresse **und** Zeitstempel bei jedem Abruf, für den Kontoinhaber einsehbar.
- **Erste unauthentifizierte Datenexposition dieser App**: bislang führten alle bestehenden Magic-Links (T25) immer zu einer eingeloggten Session, nie zu einer öffentlichen Anzeige — hier wird zum ersten Mal Art.-9-DSGVO-Gesundheitsdaten ohne Login zugänglich gemacht, mit entsprechend strengen Vorkehrungen (siehe unten).
- **Datenmodell**: neue `Patient`-Felder `blutgruppe`/`allergien`/`notfallkarte_medikamente`/`notfallkontakt_name`/`notfallkontakt_telefon` (nur über das Bearbeiten-Formular pflegbar, bewusst nicht Teil von `PatientCreate`/dem Interview-Wizard) sowie `notfallkarte_token_hash` (NULL = inaktiv, nur SHA-256-Hash gespeichert, gleiches Prinzip wie `Nutzer.reset_token_hash`) und `notfallkarte_aktiviert_am`. Neue Kind-Tabelle `NotfallkartenZugriff` (IP + Zeitstempel je Abruf). Migration `d9f2b6e4a8c1`.
- **`app/notfallkarte.py`**: Token-Erzeugung/-Hash (bewusst **kein** Ablauf, **kein** Einmalgebrauch — anders als der T25-Magic-Link-Token, da dieser Token dauerhaft auf einer gedruckten Karte/im Wallet funktionieren soll) sowie `hole_aktuelle_patientenverfuegung()` (existierte vorher nirgends als Abfrage).
- **`app/routers/notfallkarte.py`**: authentifizierter Teil (`aktivieren`/`neu-generieren`/`deaktivieren`/`zugriffe`, hinter `require_active_access` + `get_owned_patient`, Klartext-Token wird **ausschließlich** im Moment der (Neu-)Aktivierung einmalig zurückgegeben) plus ein komplett neuer öffentlicher `router_public` (gleiches Zwei-Router-Muster wie `antraege.router_public`): `GET /api/notfallkarte/{token}` (striktes eigenes Response-Schema `NotfallkarteOeffentlichOut`, damit nie versehentlich ein zusätzliches Patientenfeld mit ausgeliefert wird) und `GET /api/notfallkarte/{token}/patientenverfuegung.pdf` (eigener token-gesicherter Zweitpfad statt des normalen `get_owned_patient`-geschützten PDF-Downloads, der für einen anonymen Aufrufer unerreichbar wäre). Beide öffentlichen Routen mit demselben Rate-Limiting-Muster wie Login/Registrierung; unbekannter/deaktivierter Token liefert immer dasselbe generische 404.
- **Frontend**: Bearbeiten-Formular bekam die Notfall-Card-Datenfelder (Blutgruppe als festes `<select>` mit den 8 Standard-Notationen, kein Freitext — Ernstfall-Seite, keine Tippfehler-Daten). Patientenakte bekam einen neuen "Notfall-Card"-Collapsible (Aktivieren mit `confirm()`-Warnhinweis vor dem ersten Freischalten, QR-Code via neuer `qrcode`-npm-Abhängigkeit, Neu-generieren/Deaktivieren, Zugriffs-Log-Liste). Neue, komplett eigenständige Top-Level-Route `frontend/src/app/notfallkarte/[token]/page.tsx` — bewusst **außerhalb** von `(app)` und `(marketing)`, damit weder die Login-Sperre noch die Marketing-Chrome (Anmelde-/Registrierungs-Links) eine im Ernstfall genutzte Seite stören; async Server Component mit demselben serverseitigen `API_INTERNAL_URL`-Fetch-Muster wie die Landingpage, eigenes `noindex,nofollow` in den Metadaten. `robots.ts` disallowed `/notfallkarte` explizit, da die URL den geheimen Token enthält.
- **Rechtstexte**: neue Datenschutzerklärung-Ziffer 8 "NOTFALLKARTE" (Folgeziffern 9–19 hochgezählt, alle internen Querverweise mit angepasst), Nutzungsbedingungen bekamen einen Feature-Bullet in Ziffer 2.1 sowie einen neuen Haftungsausschluss 11.6 (Umkreissuche-Disclaimer zu 11.7 verschoben). Wie bei der Umkreissuche-Ziffer: das sind nur die Betreiber-Quelltexte im Repo, der Betreiber muss die live angezeigte Datenschutzerklärung (`rechtstext_datenschutz`-Einstellung) selbst im Admin-UI nachziehen — noch nicht geschehen.
- **End-to-end gegen die lokale Docker-Postgres-Instanz verifiziert** (Aktivieren → Hash statt Klartext in der DB, öffentlicher Zugriff ohne jedes Cookie liefert nur die 5 Notfallfelder + Patientenverfügungs-Link, kein anderes Patientenfeld; Zugriffs-Log; Neu-Generieren invalidiert den alten Token sofort; Deaktivieren sperrt zuverlässig; echte Patientenverfügung wurde erzeugt und über den PDF-Zweitpfad korrekt ausgeliefert), danach auf der NAS deployed und dort ebenfalls per Migration-Log + Health-Checks bestätigt.

### Zwei Bugs nach dem ersten Deploy gefunden und behoben (2026-08-06)

Beide erst durch tatsächliche Nutzung der Funktion durch den Betreiber entdeckt, nicht durch Code-Review vorhersehbar:

1. **Zugriffs-Log zeigte die interne Docker-Netzwerk-IP des `web`-Containers statt der echten Besucher-IP** (`192.168.144.x`, per `docker network inspect` als exakt die IP von `pflege-web-1` auf dem `pflege_default`-Netz bestätigt). Ursache: die öffentliche Seite ist bewusst eine Server Component, die die Daten serverseitig über `API_INTERNAL_URL` lädt (Performance/Robustheit, gleiches Muster wie die Landingpage) — genau dieser Server-zu-Server-Aufruf lief aber am Nginx Proxy Manager vorbei und ist zugleich der Aufruf, der beim Backend den Zugriff protokolliert. Das Backend sah dadurch bei **jedem** Zugriff, unabhängig vom tatsächlichen Besucher, immer nur den `web`-Container als Aufrufer. **Fix**: `notfallkarte/[token]/page.tsx` liest jetzt per `headers()` (aus `next/headers`) den `x-forwarded-for`-Header des eingehenden Seitenaufrufs aus (erste Hop-Logik, gleich wie `client_ip()` im Backend) und reicht ihn explizit als `X-Forwarded-For`-Header an den internen API-Aufruf weiter — `client_ip()` im Backend liest diesen Header ohnehin bereits, keine Backend-Änderung nötig. **Lehre für künftige Features**: sobald eine Server Component serverseitig einen Backend-Endpunkt aufruft, der die Besucher-IP protokolliert/rate-limitet, muss die IP explizit durchgereicht werden — ein naiver `fetch()` von `web` zu `api` läuft immer am Reverse-Proxy vorbei und liefert sonst nur die interne Container-Adresse.
2. **"Patientenverfügung öffnen"-Link zeigte auf `localhost:8100`**, von einem echten Gerät aus natürlich nicht erreichbar. Ursache: `process.env.NEXT_PUBLIC_API_URL || "http://localhost:8100"` — auf der NAS ist `NEXT_PUBLIC_API_URL` **bewusst ein leerer String** (damit der Browser `/api/*` relativ zur selben Domain aufruft, siehe Reverse-Proxy-Abschnitt weiter unten), aber ein leerer String ist in JavaScript falsy, wodurch `||` fälschlich auf den Fallback zurückfiel statt den absichtlich leeren Wert stehen zu lassen. **Fix**: die Stelle wiederverwendet jetzt die bereits bestehende, korrekt mit `??` (nullish coalescing statt logischem Oder) gebaute `API_URL`-Konstante aus `lib/api.ts`, statt die Fallback-Logik ein zweites Mal (diesmal fehlerhaft) zu duplizieren. **Lehre**: bei `NEXT_PUBLIC_*`-Variablen, die absichtlich leer sein können (same-origin-Routing-Konvention dieses Projekts), immer `??` verwenden, nie `||` — und wo immer möglich die bestehende `API_URL`-Konstante importieren statt die Fallback-Zeile erneut hinzuschreiben.
3. Beide Fixes lokal verifiziert (inkl. eines eigenen Testartefakts dabei: die lokale Dev-`.env` hat `NEXT_PUBLIC_API_URL`/`WEB_ORIGIN` auf die reale NAS-LAN-IP `192.168.1.222` gesetzt statt auf `localhost` — ein Test gegen `192.168.1.222:8100` trifft von der lokalen Dev-Maschine aus also die **echte NAS-API**, nicht den lokalen Container; für lokale Verifikation immer `localhost:8100`/`localhost:3100` verwenden, nicht die in Aktivierungs-Antworten zurückgegebene URL blind übernehmen) und danach auf der NAS deployed.
- **Bewusst nicht angetastet**: die bereits vom Betreiber selbst aktivierte, echte Notfall-Card von "Grete Musterfrau" (Demo-Konto auf der NAS, Patient-ID 1) wurde nicht neu generiert, um den bereits gespeicherten Link/QR-Code nicht ungültig zu machen — der Fix wirkt auch auf den bestehenden Token, ohne dass etwas neu aktiviert werden muss. Bei ihr liegen vier Patientenverfügung-Anträge (IDs 32–35) aus eigenen Testdurchläufen des Betreibers, bewusst nicht aufgeräumt (nicht ungefragt Daten löschen).

## T34-Anschluss/T35/T36: Pflegegrad vermutet/bestätigt, ressourcenorientiertes Interview, 4-Wochen-Pflegetagebuch (pflegepilot_v3 only, 2026-08-05)

Drei inhaltlich verzahnte, als "hoch, Plan nötig" eingestufte Punkte aus dem Tester-Feedback-Backlog, vorab per `AskUserQuestion` mit dem Betreiber geklärt und in einem Plan (`~/.claude/plans/lucky-sparking-rain.md`) festgehalten, bevor mit der Umsetzung begonnen wurde — gleiches Vorgehen wie beim ursprünglichen T25-Side-Plan.

- **Pflegegrad "vermutet" vs. "bestätigt"** (Antwort auf T34, das zur Diskussion stellte, ob die Pflegegrad-Schätzung überhaupt noch angezeigt werden sollte): die Schätzung wird **nicht entfernt**, aber nirgendwo mehr als Fakt dargestellt. Neue Felder `Patient.pflegegrad_bestaetigt`/`pflegegrad_bestaetigt_am` (Migration `c1e5a9d3f7b2`). Die dafür nötige "Rückmeldung vom Medizinischen Dienst" **existierte bereits** aus T25 (`Antrag.zugeteilter_pflegegrad`/`bewilligter_betrag`, "Status bearbeiten"-Form) — sie war nur nicht mit `Patient.pflegegrad` verknüpft. `PUT /api/antraege/{aid}` (`routers/antraege.py: aktualisieren()`) synct jetzt bei `status="genehmigt"` mit gesetztem `zugeteilter_pflegegrad` für die drei Pflegegrad-Antragstypen (`erstantrag`/`hoeherst`/`widerspruch`) automatisch nach `Patient.pflegegrad` und setzt `pflegegrad_bestaetigt=True`. Eine Guard-Bedingung (nur schreiben, wenn sich der Wert tatsächlich ändert oder das Konto noch nicht bestätigt ist) verhindert, dass ein späteres PUT auf denselben bereits genehmigten Antrag (z. B. nur Aktenzeichen nachtragen) `pflegegrad_bestaetigt_am` erneut auf "heute" zurücksetzt — per echtem Regressionstest gegen die lokale Docker-Postgres-Instanz bestätigt. Eine manuelle Korrektur über die bestehenden Chip-Buttons (`PATCH /{pid}/pflegegrad`) setzt `pflegegrad_bestaetigt` bewusst wieder auf `False` — nur der Weg über die Antrag-Rückmeldung gilt als bestätigt. `AntragUpdate.zugeteilter_pflegegrad` bekam dabei zusätzlich eine `ge=0, le=5`-Validierung (fehlte vorher, war aber unkritisch, solange der Wert nirgends automatisch weiterverarbeitet wurde) — ohne sie hätte ein außerhalb des Bereichs liegender Wert beim Schreiben in die per CheckConstraint begrenzte `Patient.pflegegrad`-Spalte einen 500er statt einer sauberen 400-Validierung ausgelöst, per Test bestätigt (422 statt 500). Anzeige überall ergänzt, wo `pflegegrad` auftaucht (Dashboard-Badge, Patientenliste, Patientenakte, Wizard-Step5-Label "Vermuteter Pflegegrad" statt "Tatsächlicher / vermuteter Pflegegrad"). Bewusst **nicht** angefasst: `build_musterbrief_text()`/Widerspruch-Text referenzieren die Wizard-Schätzung nirgends (Widerspruchs `ist_grad`/`soll_grad` kommen aus dem echten Bescheid) — es gab dort nichts fälschlich als Fakt Dargestelltes zu korrigieren.
- **T36 (ressourcenorientierter Umbau)**: die 5 Pflegegrad-Situationsfragen (`static_data/pflegegrad_regeln.py: FRAGEN`, Interview-Wizard Schritt 4) sind jetzt Checklisten "was kann die Person noch selbstständig" (3 capability-first Teilschritte je Frage) statt einer Einzelauswahl aus 4 zunehmend defizitorientierten Optionen. Punktwert je Frage = `3 − Anzahl angekreuzter Teilschritte` — reproduziert exakt den bisherigen 0-3-Wertebereich und die Summenbandbreite 0-15, `schaetzen()` blieb **komplett unverändert**. Per Regressionstest mit den historisch dokumentierten Schwellenwerten (0-1/2-4/5-7/8-10/11-13/14-15 → PG-Bereiche 0-1/1-2/2-3/3-4/4/5) gegen die echte API bestätigt: identische Ergebnisse wie vor dem Umbau. Betrifft **nur** Schritt 4 — die 8 `LEISTUNGS_FRAGEN` aus Schritt 6 sind Logistik-Fragen (Betreuungsform, welche Zusatzleistungen), keine Fähigkeits-Fragen, blieben unangetastet. Frontend: neue Komponente `TeilschritteAuswahl` in `patienten/neu/page.tsx`, nutzt weiterhin denselben `SET_ANTWORT`-Reducer-Contract wie zuvor.
- **T35 (4-Wochen-Pflegetagebuch)**: Betreiber wählte "weiches Angebot, kein Blocker" (keine Wizard-Gating-Logik) und "separates zweites PDF pro Antrag" (statt Freitext im Hauptbrief). Neues Feld `Patient.tagebuch_start_am` (optional, über das bereits bestehende generische `PatientUpdate`/`PUT /api/patienten/{pid}` gesetzt, kein neuer Endpunkt) — Button "4-Wochen-Tagebuch starten" im bestehenden Pflegetagebuch-Collapsible der Patientenakte, danach Fortschrittsanzeige "Tag X von 28" + Anzahl unterschiedlicher Tage mit mindestens einem Eintrag im Fenster. Neues Feld `Antrag.tagebuch_pdf_pfad` (String, analog zu `pdf_pfad` — bewusst ein einzelnes Feld statt einer Anhänge-Tabelle, da es genau einen bekannten Zweit-PDF-Typ gibt). Musterbrief-Generator bekam eine "Pflegetagebuch als Anhang beifügen"-Checkbox (nur bei `typ ∈ {erstantrag, hoeherst}` sichtbar) — `MusterbriefRequest.tagebuch_anhang`, serverseitig **zusätzlich** auf denselben Typ-Filter geprüft (nicht nur im Frontend versteckt), damit ein manipulierter Request bei z. B. `grundsicherung` nicht fälschlich ein Tagebuch-PDF anhängt — per Test mit direktem API-Aufruf bestätigt (`tagebuch_pdf_pfad` bleibt `null`). Zeitfenster: `patient.tagebuch_start_am` falls gesetzt, sonst Fallback `heute − 28 Tage` (nicht `antrag.antragsdatum` — das Feld wird bei Musterbrief-Erstellung anders als beim Widerspruch nicht gesetzt). Neues Template `pdf_templates/tagebuch_anhang.html` (tabellarisch, nur nicht-leere Kategorien je Eintrag) — Inhalt per `pypdf.extract_text()` gegen einen echten Testlauf verifiziert (Patientenname, Zeitraum, beide Testeinträge korrekt enthalten). Download über denselben autorisierungsgeprüften Endpunkt (`GET .../antraege/{aid}/pdf?datei=tagebuch` statt eines neuen Endpunkts). `DELETE /api/antraege/{aid}` (T29) wurde um denselben Datei-Löschblock für `tagebuch_pdf_pfad` ergänzt wie für `pdf_pfad` — sonst wären verwaiste PDFs auf der Platte liegen geblieben (gleiche Bug-Klasse wie der ursprüngliche T29-Fund); per Test bestätigt, dass nach dem Löschen eines Antrags mit beiden PDFs keine der beiden Dateien mehr im Uploads-Verzeichnis liegt.
- **Vollständig end-to-end gegen die echte lokale Docker-Postgres-Instanz verifiziert** (nicht nur synthetisch): Migration lief sauber durch, alle drei Teile per echten HTTP-Aufrufen gegen die laufende API getestet (Sync-Logik inkl. Guard-Regression, Schätzungs-Regressionstabelle, Tagebuch-Fenster-Filterung, Zweit-PDF-Erzeugung/-Inhalt/-Download/-Löschung, Typ-Guard-Umgehungsversuch), `next build` sowie `tsc --noEmit` fehlerfrei. Testdaten (Testpatient, Testkonto) danach wieder entfernt; ein lokales `verifyadmin`-Konto blieb bewusst bestehen (Admin-Selbstlöschung ist blockiert, unkritisch für eine lokale Dev-Instanz). Changelog-Eintrag `1.17.0` ergänzt, Versions-Kollisionsrisiko vorab per `GET /api/changelog`-Abgleich ausgeschlossen (siehe Lehre im Changelog-Abschnitt unten).

## Repository layout

This is not a single project but a working directory with one active app plus reference/planning material:

- **`pflegepilot_alpha_v2/pflegepilot/`** — the current production codebase (Flask + SQLite web app). Still the live app; keep maintaining it (bugfixes, security, small features) independently of the rewrite below.
- **`pflegepilot_v3/`** — the in-progress full rewrite (FastAPI + PostgreSQL + Next.js), built as a complete parallel rebuild alongside the still-running `pflegepilot_alpha_v2` app, not a migration of it — no code is shared and no data is migrated (fresh DB, demo data, an admin account created interactively together with the operator). Backend: `pflegepilot_v3/backend/app/` (routers, SQLAlchemy models, Alembic migrations under `migrations/`). Frontend: `pflegepilot_v3/frontend/src/app/` (Next.js App Router, route groups `(marketing)` public/SSR and `(app)` client-side behind a login overlay). Own `docker-compose.yml` with independent ports (db 5532, api 8100, web 3100) so it never conflicts with the old app's Docker setup. The full 8-phase architecture plan (schema translation, cross-cutting patterns, phase-by-phase scope) lives at `C:\Users\Daniel\.claude\plans\cheerful-shimmying-pnueli.md` — read it before continuing this work. Phase 0 (project skeleton, auth end-to-end), Phase 1 (patient CRUD, tenant isolation, dashboard), Phase 2 (6-step non-AI interview wizard, rule-based Pflegegrad estimation ported to `pflegegrad_regeln.py`, Krankenkassen autocomplete), Phase 3 (Leistungskatalog, Leistungsrechner, Anträge, Widerspruch- and Musterbrief-generation), Phase 4 (admin dashboard: account lock/unlock/soft-delete-with-archival/subscription-grant, audit log, DSGVO export), Phase 5 (global subscription gate, § 14 UStG invoicing, changelog system), and Phase 6 (Pflegetagebuch, Dokumente with the same authorization-checked-download pattern as briefe, Aufgaben CRUD, Kalender aggregation) are done as of 2026-07-19 — full feature parity with the old app is reached. Of Phase 7 (responsive pass, hardening, deployment), the frontend production-build switch is done as of 2026-07-29 (see "Frontend-Produktions-Build" below) — a responsive/mobile pass across the UI is what remains. Note the architecture shift in Phase 3: unlike the old app's client-side `html2pdf.js`, PDFs here are rendered server-side with WeasyPrint (`app/pdf.py` + Jinja2 templates under `app/pdf_templates/`) and served only through an authorization-checked download route rather than an openly mounted `static/` folder — see the plan file for the full rationale. The admin router in Phase 4 (`app/routers/admin.py`) demonstrates the Phase 0 architectural decision concretely: it's declared as `APIRouter(dependencies=[Depends(require_admin)])` so every route is protected by construction, not by a maintained list. **Real bug found and fixed in Phase 5**: Gunicorn's multiple worker processes each run the FastAPI `lifespan` startup handler independently, so the changelog dev-seed sync (`app/changelog.py: sync_changelog()`) executed concurrently on first boot and inserted a duplicate row — no unique constraint existed on `changelog_eintraege.version` to prevent it. Fixed with a DB-level `UNIQUE` constraint plus `INSERT ... ON CONFLICT DO NOTHING` (Postgres dialect insert) instead of a Python-side "check existing, then insert missing" pattern, which is not safe under concurrent execution. Worth remembering for any future startup-time sync/seed logic in this app: assume it runs from more than one process at once.
- **`pflegepilot_alpha/`** — superseded v1. Source files have been deleted; only a stale `__pycache__` remains. Do not develop here.
- **`pflegepilot_erp.html`** — a standalone static HTML mockup/prototype, not wired to the Flask app. Not part of the running system.
- **`Anleitung.md`, `Leistungen.md`, `Leistungen2.md`, `Pflegegrad.md`, `Musterbrief.md`** — German-language domain reference notes (care-benefits catalog research, sample letters, project rationale) used as source material for `katalog.py` and the letter generators. Not code.
- **`refactoring.md`** — the current architecture-change brief from the product owner (see "Planned architecture pivot" below). Read this before any structural work.

A git repository is initialized at the root (`Pflegepilot/.git`). `.gitignore` excludes the SQLite DB, patient-generated files (`static/briefe`, `static/dokumente`, `static/fotos`), `__pycache__`, and `graphify-out/` — never commit real patient data.

## Commands

Run from `pflegepilot_alpha_v2/pflegepilot/`:

```bash
pip install flask
python start.py        # initializes/migrates the SQLite DB, then serves on http://localhost:5050
```

`start.py` runs with `debug=False`; running `app.py` directly instead uses `debug=True` on the same port. There is no test suite, linter, or build step in this project.

Default login after first start: `admin` / `admin` (created automatically by `init_db()` when the `nutzer` table is empty).

## Docker deployment

The app also runs containerized, as-is (Flask + SQLite, no rewrite) — `Dockerfile`, `docker-compose.yml`, `.dockerignore`, `requirements.txt`, and `.env` all live in `pflegepilot_alpha_v2/pflegepilot/`, alongside the app itself. This is an additional deployment path, not a replacement for local dev — `python start.py` still works unchanged.

```bash
cd pflegepilot_alpha_v2/pflegepilot
docker compose build
docker compose up -d        # serves on http://localhost:${APP_PORT:-5050}
docker compose logs -f app
docker compose down          # add -v to also wipe the db/static volumes
```

- **Single app service, no separate DB container**: SQLite is an embedded, file-based engine, not a networked service — there is nothing to containerize separately without swapping to Postgres, which would be a rewrite and is explicitly out of scope for this task (that's the separate, not-yet-planned `open.md` item 4). "Isolation between app and data" is instead achieved with two **named Docker volumes** — `pflegepilot_db` (mounted at `/app/db`) and `pflegepilot_static` (mounted at `/app/static`) — so patient data outlives any `docker compose build`/`up` cycle of the app container and can be backed up or moved independently of the image.
- **Runs on Gunicorn, not the Flask dev server**: the container `CMD` first runs `init_db()` once as a plain `python -c` step (idempotent — see the schema-evolution pattern above, safe to re-run on every container start), then execs `gunicorn` bound to `0.0.0.0:5050` inside the container. Worker count is `GUNICORN_WORKERS` (env var, default 2).
- **Secrets and config live in `.env`** (real file, not `.env.example` — solo project, no template needed), gitignored, and referenced by `docker-compose.yml` via `env_file`. Currently holds: `SECRET_KEY` (random 64-hex-char value, generated once with `python -c "import secrets; print(secrets.token_hex(32))"` — `app.secret_key` in `app.py` reads `os.environ.get("SECRET_KEY", "pflegepilot-alpha-2025")`, so local `python start.py` still works with zero setup via the hardcoded fallback, while Docker always overrides it with a real secret), `APP_PORT` (host-side port mapping, default 5050), `GUNICORN_WORKERS`. Never commit `.env` or paste its contents anywhere.
- **No domain/URL baked in anywhere, intentionally**: the container only knows about its internal port (`5050`, fixed) and the host port it's mapped to (`APP_PORT`, configurable). Whatever hostname eventually points at that port — a DynDNS domain forwarded to the testbench, or anything else later — needs zero code or `.env` changes here; the app doesn't care what hostname it's reached through. The one thing to revisit *when* a real domain + reverse proxy with TLS is added in front of this later: session cookies aren't currently marked `Secure` (fine for a plain-HTTP testbench today), so add `SESSION_COOKIE_SECURE=True` and proxy-header trust (`ProxyFix`) at that point, not before.
- **Bug found and fixed while adding this**: the `nutzer` table isn't in `schema.sql` (it was added later, purely via the `init_db()` migration list) — it used to be created near the *end* of that list, after several `ALTER TABLE nutzer ADD COLUMN ...` entries earlier in the same list. On any database that already had a `nutzer` table this was invisible (the ALTERs just worked normally), but on a genuinely fresh database — e.g. the first boot against a brand-new Docker volume — the ALTERs ran before the table existed, failed, and were silently swallowed by the migration loop's `except: pass`, leaving `nutzer` permanently missing `abo_bis`/`abo_typ`/`ist_demo` and crashing the demo-account bootstrap insert. Fixed by moving `CREATE TABLE IF NOT EXISTS nutzer` to the very top of the migration list with the full current column set included directly, so table creation always precedes anything that depends on it, regardless of whether the DB is fresh or pre-existing. Verified by tearing down the Docker volumes (`docker compose down -v`) and rebuilding from nothing — the app now boots clean.

## Architecture

**Single-file Flask backend, vanilla-JS SPA frontend, zero build tooling.**

- `app.py` — the entire backend: all `/api/*` routes, SQLite access, auth, file upload handling. There's no blueprint/module split — everything lives in this one file. There is no server-side email sending — see "Email: mailto hand-off, not SMTP" below.
- `templates/index.html` — the entire frontend. One Jinja template that is actually a client-rendered SPA: vanilla JS, string-templated HTML, no framework, no bundler. Key conventions in the `<script>` block:
  - `go(name, extra)` is the client-side router; it maps a page name to a `pg*()` render function (`pgDash`, `pgPatienten`, `pgKatalog`, `pgBackend`, …).
  - `S(id, html)` sets innerHTML by id; `R(html, title, actions)` sets the main content/title/toolbar in one call.
  - `api(path, opts)` is the shared `fetch` wrapper for JSON API calls (raw `fetch` is used directly for multipart file uploads).
  - PDF documents (Musterbrief, Widerspruch, Pflegetagebuch, Patientenakte) are rendered **client-side** via `html2pdf.js`, then the resulting blob is base64-uploaded to a server endpoint (e.g. `POST /api/patienten/<pid>/briefe`, `POST /api/patienten/<pid>/dokumente`) for permanent storage under `static/`.
- `katalog.py` — static data module: `KATALOG`, a list of ~82 care-benefit entries (Pflegekasse/Krankenkasse services under SGB XI), each tagged with `zielgruppe` (target group: `alterspflege`/`beduerftige`/`behinderte`) and a `pflegegrad_min`/`pflegegrad_max` range, plus legal basis (`rechtsgrundlage`), amounts, and optional `abhaengigkeiten` (cross-references to related/conflicting benefits). Filtering helpers (`get_by_zielgruppe`, `get_by_pflegegrad`, `search`, …) are used both by `/api/katalog` and to compute a patient's `empfohlene_leistungen`.
- `krankenkassen.py` — static directory of ~86 health/care insurers (GKV/PKV in Germany, SV in Austria, KVG in Switzerland) with postal addresses, used to auto-fill recipient addresses in generated letters. Has a `land` field (`DE`/`AT`/`CH`) with helpers `get_by_land`, `search(q, land=None)`.
- `db/schema.sql` — base SQLite schema (`patienten`, `antraege`, `leistungen`, `aufgaben`, `pflegetagebuch`, `einstellungen`, `dokumente`) plus demo seed rows.
- **Schema evolution pattern**: `init_db()` in `app.py` runs `schema.sql` once, then re-applies a hardcoded list of `ALTER TABLE` / `CREATE TABLE IF NOT EXISTS` statements on every startup, each wrapped in its own try/except so an already-applied migration is silently skipped. When adding a column or table, add a new entry to that list rather than editing `schema.sql` (existing DBs won't be recreated) — and keep entries idempotent/backward-compatible since this list re-runs on every process start.
- **Auth**: session-cookie based. `_get_current_user()` / `_check_admin()` read `session["nutzer_id"]`; `login_required` / `admin_required` decorators guard individual routes, while `global_auth_check()` (a Flask `before_request` hook) blanket-blocks any `/api/*` path not in the small public allowlist (`/api/auth/login`, `/api/auth/me`, `/api/einstellungen/public`). Two roles exist: `admin` and `nutzer`. Passwords are hashed with `werkzeug.security` (PBKDF2).
- **Patient isolation**: `patienten.nutzer_id` (FK to `nutzer.id`) records who owns each patient — set automatically to the creating user on `POST /api/patienten`. Two helpers in `app.py` enforce it everywhere: `_get_owned_patient(pid)` (single-patient routes — returns the row if the current user is the owner or an admin, else `None` → caller returns 404) and `_scope_sql(column="id")` (list/aggregate routes — returns a SQL fragment + params to append to a `WHERE` clause; empty for admins, `AND {column} IN (SELECT id FROM patienten WHERE nutzer_id=?)` otherwise). `admin` role is exempt and always sees every patient. Every route touching `patienten` or a child table (`antraege`, `leistungen`, `aufgaben`, `pflegetagebuch`, `dokumente`) must go through one of these two helpers — when adding a new patient-scoped route, follow the existing pattern rather than querying the table directly. `aufgaben.patient_id` is nullable in the schema, but the API now requires a `patient_id` from non-admin callers on creation (admins may still create patient-less tasks) so the isolation model stays consistent between write and read paths.
- **File storage**: everything is local under `static/` — `static/fotos/<patient_id>.<ext>` (profile photos), `static/briefe/<patient_id>/…` (generated letter PDFs), `static/dokumente/<patient_id>/…` (uploaded documents), `static/logo/` (company branding). No object storage/CDN involved.
- **Settings**: a generic key-value `einstellungen` table (accessed via `get_setting()`) holds company branding/address and the three `rechtstext_*` legal texts (see "Admin focus, self-registration & legal pages" below) — surfaced through `/api/admin/einstellungen`. The earlier "KI – Claude API" token field/card was removed (unused, never wired to any actual AI feature) — don't resurrect it without a real integration behind it.

## Planned architecture pivot (see `refactoring.md`)

The product owner specified a pivot away from the original **central multi-patient service** (any logged-in user could see all patients) toward three changes:

1. **Per-account patient isolation** — ✅ implemented. Data model: 1 `nutzer` = 1 account, `patienten.nutzer_id` FK, `admin` role exempt (sees everything). See "Patient isolation" above for the enforcement mechanism. Verified end-to-end (two non-admin accounts cannot see or directly access each other's patients; admin sees all).
2. **No-AI interview flow** — ✅ implemented. `pgNeu()` in `templates/index.html` is now a 6-step guided wizard (`neuWiz` state object, `neuRender()`/`neuNext()`/`neuBack()`/`neuCollect()`) that fully replaced the old single-form dialog: persönliche Daten → Kontakt & Adresse → Krankenversicherung → Pflegesituation → Einschätzung & Pflegeperson → Übersicht. Step 4 asks 5 plain-language situational questions (`NEU_FRAGEN`) plus a Zielgruppe question (`NEU_ZG_OPTIONEN`); `neuSchaetzung()` sums the answers into a **rule-based, non-AI** Pflegegrad range shown with a prominent disclaimer that it's not an official determination (only the Medizinischer Dienst's Begutachtung is). Server enforces a hard cap of 3 patients per non-admin account in `api_neuer_patient` (admin exempt).
3. **Admin dashboard** — ✅ implemented. New `admindash` page (`pgAdminDash()` in `templates/index.html`, nav item under `.sb-admin`), backed by `app.py` routes under `/api/admin/nutzer/<uid>/{sperren,entsperren,loeschen}`, `/api/admin/audit-log`, `/api/admin/patienten/<pid>/dsgvo-export`. Key design points, all confirmed with the user beforehand:
   - **"Löschen" is a soft-delete**, not `DELETE FROM nutzer`: it sets `aktiv=0` and archives every active patient the account owns via `_archiviere_patient()` (same 10/30-year retention-deadline logic as the existing per-patient archive feature) — because care records carry a statutory retention duty (§ 630f BGB) that a hard delete would violate. The pre-existing hard-delete route (`DELETE /api/nutzer/<uid>`) still exists but now refuses (400) if the account still owns any patients, forcing admins through the archive-first path.
   - **`nutzer.aktiv` is checked on every request** (`_get_current_user()`), so locking an account invalidates an already-open session immediately — no separate session-store/invalidation mechanism was needed.
   - **Every action requires a `begruendung`** (400 without one) and is written to the new `admin_audit_log` table (`_log_admin_aktion()`) — immutable, insert-only, same audit-trail pattern as `notizen_verlauf`. This is the operator's evidentiary record for disputes.
   - **DSGVO export** (`POST /api/admin/patienten/<pid>/dsgvo-export`) requires a `begruendung` (used as Rechtsgrundlage/Aktenzeichen), is admin-only, and streams back a ZIP (built in-memory with `zipfile`/`io.BytesIO`, no temp files) containing `daten.json` (patient + antraege + leistungen + aufgaben + pflegetagebuch + dokumente + notizen_verlauf, plus an `export_info` block) and the actual files from `static/briefe/<pid>/`, `static/dokumente/<pid>/`, and the patient's photo. Every export is itself audit-logged.
   - Self-targeting is blocked for sperren/loeschen (an admin can't lock/soft-delete their own account) to avoid a lockout with no recovery path.
   - `GET /api/nutzer` now also returns `patienten_anzahl` per account (used by the dashboard table; backward-compatible addition).

All three refactoring.md pivot pieces are now implemented. Verified end-to-end (API tests for every guard/happy-path + audit-log content, and a Playwright screenshot pass of the dashboard UI and the confirmation modal).

## Responsive design & visual style

The frontend was originally desktop-only (zero `@media` queries, fixed 228px sidebar, fixed-column form grids) and went through two visual passes per user feedback: a first "warm minimal" pass was rejected as still too clinical, then a full **glassmorphism + Bento grid** redesign (current state) — both entirely in `templates/index.html`.

- **Glass design system**: `:root` defines a dedicated token set — `--glass`/`--glass-strong` (translucent white fills), `--glass-border`, `--glass-blur`, `--glass-shadow`/`--glass-shadow-lg`, plus four `--bento-*` gradient tokens (mint/lavender/peach/rose) for tile accents. `body` has a fixed multi-blob `radial-gradient` background (`background-attachment:fixed`) that the translucent, `backdrop-filter:blur(...)` cards/sidebar/topbar/modal/login-box float over. Regular form inputs stay solid (`var(--surface)`, opaque white) — only container-level chrome (`.card`, `.modal`, `.sb`, `.topbar`, `.lo-box`) is glassy, intentionally, for text legibility. Always pair `backdrop-filter` with `-webkit-backdrop-filter` (Safari).
- **Dashboard is a real Bento grid**, not just a relabeled stat row: `.bento` is a 4-column CSS grid with **explicit** `grid-column`/`grid-row` line placement per tile class (`.bento-stat`, `.bento-hero`, `.bento-aufg`, `.bento-quick`) — deliberately not relying on grid auto-placement, which does not reliably fill remaining same-row cells the way you'd expect when items of different spans are mixed. If you add/resize tiles, keep using explicit line numbers (or verify auto-placement with the debug technique below) rather than assuming `span N` will pack tiles the way you expect.
- **Responsive tables → cards**: any live-UI (non-PDF-export) table that needs to stay usable at phone width gets `class="tw rtable"` on its wrapper and `data-label="…"` on every `<td>`. Below 700px, `.rtable` CSS turns each `<tr>` into its own glass card (label stacked above value per cell, via `td[data-label]::before{content:attr(data-label)}`) instead of squeezing table columns. Applied to: Dashboard's recent-patients table, `renderPT` (Patientenliste), `pgAufgaben`, `renderAdminDash`'s Konten table **and** its Audit-Log (originally a fixed-min-width flex list — converted to an `.rtable` specifically because flex rows with `min-width` don't degrade gracefully, unlike this pattern), and the Patientenakte Anträge table. Follow this pattern for any new data table — don't ship a raw `<table>` (or a fixed-width flex row list) without it.
- **Accordion on the card view**: within `.rtable`, exactly one row is expanded at a time — the rest collapse to a single header line (`td.rt-head`, marked explicitly per table since it's usually the first `data-label` cell) and stack tightly, so scanning many rows needs far less scrolling. `rtInit()` (shared helper, defined near `escH`) wires this up: on load the first row gets `.rt-open`; clicking any row's header toggles it open and closes the others (clicks on nested `button,a,select,input,textarea,.tl` are ignored so action buttons/links inside a row still work independently of the accordion). **Every function that renders an `.rtable` must call `rtInit()` after the DOM is in place** (see `pgDash`, `renderPT`, `pgAufgaben`, `renderAdminDash`, `loadPat`) — a new table using this pattern that forgets the call will render but never expand/collapse. Cells without `data-label` (action-button columns) are never hidden by the accordion, so those buttons stay reachable even on a collapsed row. The `.rt-chev` chevron icon is `display:none` by default and only shown inside the `max-width:700px` breakpoint — without that base rule it leaks into the plain desktop/tablet `<table>` as a stray icon. **Expand/collapse animates** via `max-height`/`opacity`/`padding` transitions on each `td[data-label]` (a fixed `max-height:130px` ceiling, not `height:auto`, since `display` and `height:auto` aren't transition-able) — don't revert this to a `display:none`/`block` toggle, that's what made it feel instant/abrupt before.
- **Date-wheel picker, not native `<input type="date">`**, for any date field where users need to scroll far from today: `openDatePicker(hiddenId, dispId, {fallback, titel, icon, yearMin, yearMax})` opens an `OM()` modal with three CSS-scroll-snap columns (Tag/Monat/Jahr, `.dwheel`/`.dwheel-col`/`.dwheel-item`, `DW_ITEM_H=38`); the centered item per column is read on confirm (`dwConfirm()`), clamped for invalid day/month combos, and written back as an ISO string. The pattern is: a visible `.dw-trigger` div (click opens the picker, shows the formatted date via `dwTriggerLabel(hiddenId, dispId, icon)`) plus a paired `<input type="hidden">` that holds the real `YYYY-MM-DD` value everything else in the codebase already expects — so `neuCollect()`/`fillWP()`/`fillM()`/`updM()` etc. needed no changes beyond calling `dwTriggerLabel()` after programmatically setting the hidden input (e.g. when a patient is selected and auto-fills the form). `openGebDatumPicker(hiddenId, dispId)` is a thin wrapper around `openDatePicker` for birth dates specifically: `icon:'ti-cake'`, `fallback` = *today − 75 years* (a far better scroll starting point than today, given this app's typical patient age) — used on `fgeb` (interview wizard), `wgeb` (Widerspruch-Generator), `mpgeb` (Musterbrief). `openDatePicker` is called directly (no wrapper, default fallback = today, `icon:'ti-calendar'`) for near-term dates where "today" is already the right starting point, e.g. `adt` (Antragsdatum). Dates that are *always* within the last/next few months and don't need this at all (Bescheiddatum, Fällig-am, Tagebuch/Dokument-Datum, etc.) can stay a plain `<input type="date">` — only convert a field once someone actually needs to scroll years back from it. If you wire the picker to a field with existing live-update behavior (Musterbrief's `updM()` was previously triggered via `oninput`), you must call that update function explicitly from `dwConfirm()` — switching to `type="hidden"` removes the inline `oninput` handler, and events dispatched on a hidden input don't automatically reach anything unless something explicitly listens for them.
- **Interview wizard step 4 asks one question at a time**, not a long scrolling list: `neuWiz.q4sub` (0 = Zielgruppe, 1-5 = each `NEU_FRAGEN` entry) tracks position within the step; `NEU_Q4_TOTAL` is the count. A thin segmented progress bar (`.subdots`/`.subdot`, distinct from the big numbered `.wiz-steps` circles for the outer 6 steps) shows position within step 4 specifically. Answering a question (`neuAntwort`/`neuSetZG`) auto-advances `q4sub` to the next one — except on the last question, which waits for an explicit "Weiter" tap so the user gets a moment before jumping to the estimate in step 5. `neuNext()`/`neuBack()` both special-case `step===4`: they move `q4sub` within the step before ever touching the outer `step` counter, and entering step 4 from step 5 via "Zurück" lands on the *last* sub-question (`q4sub=NEU_Q4_TOTAL-1`), matching normal back-navigation expectations. If you add a 7th situational question, nothing else needs to change — `NEU_Q4_TOTAL` and the subdots derive from `NEU_FRAGEN.length` automatically.
- **Mobile/tablet nav**: below 900px the `.sb` sidebar becomes a fixed off-canvas panel (`transform:translateX(-100%)`, slides in via `.sb.open`), toggled by a hamburger button (`#sb-toggle`, only visible in that breakpoint) and a `#sb-backdrop` overlay that closes it on tap. `toggleSidebar()`/`closeSidebar()` manage this; every nav-item click auto-closes it. Form grids (`.fg.c2/.c3`), stat grids (`.g4`), and the bento grid collapse to fewer columns at 900px/700px/560px. Modals go full-screen below 560px. Form inputs are forced to `font-size:16px` on phones to stop iOS Safari's auto-zoom-on-focus.
- **Dashboard quick-actions become a sticky bottom bar on phones**: below 560px, `.bento-quick` (the "Schnellzugriff" tile) switches from a normal bento grid cell to `position:fixed;bottom:0`, a horizontal icon-only tab bar (`.bq-hd` heading hidden, `.bq-list` buttons go icon-over-2-line-label via `-webkit-line-clamp:2`), so the primary actions never require scrolling to reach. `.bento{padding-bottom:80px}` in that same breakpoint reserves the space the fixed bar would otherwise cover — this is scoped to `.bento` specifically (not a global `#content` padding) since `.bento-quick`/`.bento` only ever exist on the Dashboard page.
- **Verification gotcha #1 — internal scroll**: `.content` scrolls internally (`overflow-y:auto` inside a `height:100vh` shell), so Playwright's `page.screenshot({fullPage:true})` does **not** capture content below the fold — only the viewport. Scroll `.content` itself (`document.querySelector('.content').scrollTop = ...`) before screenshotting to see the rest.
- **Verification gotcha #2 — stale template cache**: `start.py` runs with `debug=False`, so Flask's `TEMPLATES_AUTO_RELOAD` is off and Jinja caches the compiled `index.html` **in memory for the life of the process**, from the first request after startup. Editing the template while a `python start.py` process is still running from before your edit is invisible to the browser no matter how many times you reload — you'll see stale HTML/JS and it's easy to misdiagnose as a CSS/JS bug. **Always restart the server after editing `templates/index.html`** before taking verification screenshots or you'll debug a ghost.

## Subscription / payment scaffolding

The product owner wants the app to cost **4.99 €/month per account**, provider likely **PayPal** (not yet integrated — no account/API keys exist yet). Since there's no live payment method, the paywall is built but wired to a **global off switch** so it can't lock anyone out before PayPal actually works:

- `einstellungen` key `abo_pflicht` (`"1"`/`"0"`, default off) — read via `_abo_pflicht_aktiv()`. Toggle lives in the Backend-Einstellungen "Abo & Zahlung" card. **Leave this off until PayPal is actually wired up.**
- `nutzer.abo_bis` (date, NULL = never granted) / `nutzer.abo_typ` (`'kostenlos_admin'` | future `'paypal'`) track access per account. `_hat_aktiven_zugang(u)` is the single source of truth: always true for admins, always true for the demo account (`ist_demo`, see "Demo account" below — it must never hit the paywall regardless of `abo_pflicht`), always true while `abo_pflicht` is off, otherwise `abo_bis >= today`.
- `global_auth_check()` enforces this on every `/api/*` call except a small allowlist (`/api/abo/status`, `/api/abo/aktivieren`, `/api/auth/logout`) — returns **402 Payment Required** (`code: "abo_erforderlich"`) when blocked, so a blocked user can still see their status and (eventually) pay.
- `POST /api/abo/aktivieren` is an intentional **stub** (501, "noch nicht verfügbar") — real PayPal Checkout/Subscriptions integration replaces this later; do not fake a success response here.
- Admin can grant free access via `POST /api/admin/nutzer/<uid>/abo-freischalten` (`{monate, begruendung}`, 1–12 months, extends from the later of today/existing `abo_bis`, admin-only, audit-logged like the other admin-dashboard actions) — this is the "1 Monat kostenlos freischalten" capability the operator asked for, surfaced as a "Freischalten" button per row in the Admin-Dashboard.
- Frontend: `curAbo`/`aboBlockiert` globals are set in `initApp()` from `GET /api/abo/status`. `go(name)` redirects any navigation to the `meinabo` page while `aboBlockiert` is true, so a blocked account always lands on its own status/pay screen instead of a broken page. `pgMeinAbo()` is that page (status, price, stub PayPal button) and doubles as the always-available "check my subscription" view when unblocked.
- When actually integrating PayPal: replace `/api/abo/aktivieren`'s stub body with real Checkout/Subscription creation, add a webhook endpoint to update `abo_bis`/`abo_typ` on payment events, and only then flip `abo_pflicht` to `"1"`.

**This whole section describes `pflegepilot_alpha_v2` only** (`_abo_pflicht_aktiv()`, `_hat_aktiven_zugang()`, `global_auth_check()`, `initApp()` are its Flask/vanilla-JS naming). `pflegepilot_v3` — now the production system the customer actually uses — diverged from this flat-price model on 2026-07-24 per direct customer pricing feedback:

- **Tiered pricing, not a flat rate**: `abo_preis_basis` (14.99 €, covers the account plus one managed patient) + `abo_preis_zusatzpatient` (4.99 €/month per additional patient) replace the old single `abo_preis` einstellungen key. `app/einstellungen.py: berechne_abo_preis(db, patienten_anzahl)` is the one place this is computed — used by `/api/abo/status` (the logged-in user's own price), the admin Nutzerliste (`abo_preis_aktuell` per account, also drives the invoice-amount default in the Admin-Dashboard's "Rechnung" button instead of a hardcoded value), and `/api/einstellungen/public` (landing page). Change the two `abo_preis_*` einstellungen keys to reprice; never hardcode a price string in a new call site.
- **No more hard patient cap**: `app/routers/patienten.py` previously refused a `POST /api/patienten` past `MAX_PATIENTEN_PRO_KONTO = 3` (non-admin only). Removed on 2026-07-24, same reasoning as the price change — once additional patients are a paid add-on rather than free, there's no reason to also cap them; the price itself is what scales, so `berechne_abo_preis` is the only enforcement point left. Don't reintroduce a numeric cap without checking whether it should instead just be a higher per-tier price.
- **Self-service cancellation**: `nutzer.abo_gekuendigt` (bool, migration `fba430fd99be`) — `POST /api/abo/kuendigen` / `POST /api/abo/reaktivieren`, both `require_login`, surfaced on the `meinabo` page. Cancelling does **not** revoke access immediately — access still runs to `abo_bis` (statutory "kündbar zum Ende der Abrechnungsperiode"), it only marks the account as "do not auto-renew" for whenever real recurring billing exists. Admin's `abo-freischalten` (granting free months) resets `abo_gekuendigt` back to `False`, since granting a fresh paid period is itself a renewal that supersedes a stale cancellation flag.
- Reducing patient count naturally lowers the price at the next computation — there's no separate "cancel one additional patient" flow; deleting/archiving a patient is enough, since `berechne_abo_preis` reads the current patient count live.

## Ummeldung-Generator (pflegepilot_v3 only)

Added 2026-07-24 per customer feedback: when a patient moves, both the Krankenkasse and the Rentenversicherung need to be notified separately, and there was no letter generator for this (only Erstantrag/Höherstufung/Widerspruch existed). `POST /api/patienten/{pid}/adressaenderung` (`app/routers/briefe.py`) does three things in one call: updates the patient's `strasse`/`plz`/`ort` to the new address, and — independently toggleable per recipient (`krankenkasse_benachrichtigen`/`rentenversicherung_benachrichtigen`, both default `True`) — generates a PDF notification letter to the Krankenkasse and/or to a Rentenversicherungsträger, each stored as its own `Antrag` row (`typ='adressaenderung'`, added to the `ck_antrag_typ` CheckConstraint in migration `5ff4e0a87733`) via the same authorization-checked-download pattern as every other letter.

- `app/static_data/rentenversicherung.py` is a new static directory (DRV Bund + the 15 regional Träger, addresses sourced from `deutsche-rentenversicherung.de`'s official "Anschriften-Übersicht"), mirroring `krankenkassen.py`'s shape/`get_by_name`/`search` API. **Deutsche Rentenversicherung Bund is the default recipient** in the frontend — correct for the large majority of insured people since regional-Träger correspondence is generally forwarded internally; a free-text override (via `RentenversicherungAutocomplete`) still works for the small number of cases where the specific regional Träger is known and preferred, falling back to the same `"[Anschrift bitte ergänzen]"` placeholder pattern as an unrecognized Krankenkasse name if typed manually and not found in the list.
- `Patient.rentenversicherungsnummer` (new column, same migration) is the Rentenversicherung analogue of the existing `versichertennummer` — optional, collected in the "Neuer Patient"-Wizard's Krankenversicherung step and reusable by any future feature needing it, not just this letter.
- `app/briefe_text.py: build_adressaenderung_text()` is shared by both recipient letters (only the `kennzeichen_label`/`kennzeichen_wert` — Versichertennummer vs. Versicherungsnummer — and the recipient block differ), rather than duplicating two near-identical templates.
- The patient's *previous* address is captured before the DB update and shown in the letter as "Bisherige Anschrift" (or a placeholder if the patient never had a stored address) — don't reorder the update-then-read, capture old values first.
- This was, until 2026-07-24, the only way to edit a patient's address after creation — see "Patient bearbeiten" below, added the same day, which now supersedes that "first place" status.

## Patient bearbeiten (pflegepilot_v3 only)

Added 2026-07-24: until then there was no way to fix a typo made at patient creation — only Pflegegrad (`PATCH .../pflegegrad`) and Notizen (`POST .../notizen`, audit-trailed via `notizen_verlauf`) had dedicated update routes/UI; every other field (name, address, contact, insurance) was write-once via the "Neuer Patient" wizard. `PUT /api/patienten/{pid}` (`PatientUpdate` schema, generic `setattr` loop in `routers/patienten.py`) already supported updating all of these — it just had no frontend form. `app/(app)/patienten/[id]/bearbeiten/page.tsx` is that form: a single-page (not multi-step, unlike the creation wizard) edit form prefilled from the current patient, "Bearbeiten" link added next to "Löschen" on the patient detail page. Deliberately excludes `notizen` (keeps going through its own audited flow) and `patient_status`/`pflegegrad`/`foto_pfad` (each has its own dedicated update path already).

## Passwort-vergessen per SMTP (pflegepilot_v3 only, 2026-07-24) — deliberate exception to "no SMTP"

The operator noticed self-registered accounts had no email address at all, so a "Passwort vergessen" flow had no way to verify identity. Fixed by adding `nutzer.email` (unique, mandatory on new self-registrations, optional/backfillable on admin-created accounts) plus a standard token-based reset flow.

**This was, until 2026-07-28, the only place in `pflegepilot_v3` where the server sends email of its own accord.** (The "Email: mailto hand-off, not SMTP" section further below describes `pflegepilot_alpha_v2`'s design, not v3's — v3's own Musterbrief/Widerspruch/Ummeldung/Vollmacht generators don't send email at all, mailto or otherwise, they only offer a PDF download.) Two more proactive-email use cases were added on 2026-07-28 with operator sign-off; see "Proaktiver Server-Mailversand erweitert" below for the current, complete list and the reasoning for each. Don't add a *fourth* proactive-email use case without the same kind of explicit check-in — this isn't meant to become the default pattern for every notification idea.

- `app/email_util.py: send_email()` is the one place SMTP is touched. Configured via `SMTP_HOST`/`SMTP_PORT`/`SMTP_USER`/`SMTP_PASSWORD`/`SMTP_FROM`/`SMTP_USE_SSL`/`SMTP_USE_TLS` env vars (`app/config.py`), all optional. **As long as `SMTP_HOST` is unset, it only logs a warning and returns — never raises.** This was deliberate, not a stopgap to remove later: `POST /api/auth/passwort-vergessen` must always return the same generic response regardless of whether the email exists or whether sending succeeds (anti-enumeration), so `send_email()` swallowing its own failures is exactly the right shape for that caller, not a bug.
- `docker-compose.yml`'s `api.environment` block only passes through explicitly listed keys — adding a new `Settings` field in `config.py` is not enough by itself, the corresponding `${VAR}` line must also be added to `environment:` (this bit locally the first time: the `.env` value was set correctly but never reached the container until `docker-compose.yml` itself was updated). `SMTP_USE_SSL`/`smtp_use_ssl` was added alongside `smtp_use_tls` (STARTTLS) because Strato (the operator's SMTP provider) offers both port 465 (implicit SSL, `smtplib.SMTP_SSL`) and 587 (STARTTLS on a plaintext-then-upgraded connection) — these are different connection modes, not interchangeable, and the operator's provider notes specified SSL/465. **Live and verified 2026-07-24** against the operator's real Strato mailbox (`support@db-onlinedienste.de`, port 465/SSL) — both a direct `send_email()` call and the actual `/api/auth/passwort-vergessen` endpoint were tested end-to-end with no errors logged.
- **The real SMTP password lives in `pflegepilot_v3/secrets/SMTP-Secrets.txt`** (gitignored — this folder was untracked-but-NOT-ignored when the operator first created it, meaning a stray `git add -A` would have committed a plaintext password; added to `.gitignore` in the same pass this feature shipped). Never read this file's contents into a chat response, a commit, or any other persisted location — when working with it, treat the value as write-only: read it, pipe it directly into `.env` via file transfer (not inline shell arguments — special characters in the actual password broke naive shell-quoting attempts elsewhere in this project's history), never echo or log it.
- Reset tokens: `secrets.token_urlsafe(32)`, only the SHA-256 hash is stored (`nutzer.reset_token_hash`/`reset_token_laeuft_ab`), 1-hour validity, single-use (cleared on successful reset). Same rate-limiting pattern as `login`/`registrieren` (`is_rate_limited`, keyed by IP).
- The reset-link landing page (`/passwort-zuruecksetzen?token=...`) had to go in `(marketing)/`, not `(app)/` — the `(app)` layout shows a blocking `AuthOverlay` for anyone not logged in, which would swallow the page before the reset form ever rendered. `(marketing)/` has no such gate, which is exactly why Impressum/Datenschutz/AGB already live there.
- **Existing accounts created before this change have no email** and can't use password-reset until one is set — either the account holder re-registers, or an admin sets `email` via `PUT /api/nutzer/{uid}` (schema-ready; no dedicated admin edit-account modal exists yet in pflegepilot_v3's admin dashboard to do this through the UI — only the quick-create form and sperren/entsperren/löschen/Freischalten/Rechnung actions exist there today). Building that modal is a natural next step but wasn't part of this task.

## Berechtigungsbestätigung je Patient (pflegepilot_v3 only, 2026-07-24)

Operationalizes what the ToS (Ziffer 5) and Datenschutzerklärung (Ziffer 7) already say in prose — that the Nutzer, not Pflegepilot, is responsible for having a legal basis (Einwilligung, Pflege-/Fürsorgebeziehung, or rechtliche Vertretung) to enter another person's data — as an actual captured declaration, same pattern as the Widerrufsrecht consent at registration (§ 356 BGB) added earlier the same day.

- **Per patient, not once per account** (deliberate choice, confirmed with the operator): each care recipient is a distinct person who may have a distinct authorization basis (e.g. Vorsorgevollmacht for one parent but not the other), so the checkbox appears on Step 6 ("Übersicht") of the "Neuer Patient" wizard every time, not just for the first patient created.
- Enforced server-side (`POST /api/patienten` rejects with 400 if `berechtigung_bestaetigt` isn't `true`), not just a disabled button — same reasoning as the registration consent: a client-only gate is trivially bypassed by calling the API directly.
- `patient.berechtigung_bestaetigt_am` (migration `f552607a045e`) stores the timestamp as the evidentiary record, mirroring `nutzer.widerrufsverzicht_bestaetigt_am`. Not exposed via `PatientOut` (kept DB-only, same restraint as the Nutzer field) — query directly if ever needed.
- `PatientCreate.berechtigung_bestaetigt` is excluded from the `model_dump()` spread into the `Patient(...)` constructor in `routers/patienten.py` (it isn't a column — only `_am` is) — don't add fields to `PatientCreate` that aren't 1:1 `Patient` columns without checking this exclusion still holds.

## Incident 2026-07-24: German-comma price value crashed the entire admin dashboard

`app/einstellungen.py: abo_preise()` used to do a bare `decimal.Decimal(get_setting(...))`. The admin saved the "Aufpreis je zusätzlichem Patienten" field in Backend-Einstellungen with a German-formatted value (`"4,99"` — comma, not dot) — completely natural input for a German user, but `decimal.Decimal("4,99")` raises `InvalidOperation`. Since `abo_preise()` is called from `GET /api/nutzer` (admin's Nutzerliste, to compute `abo_preis_aktuell` per account), this took down the **entire** admin account list with a 500 — reported by the operator as "the accounts are gone," when in fact no data was lost at all, only the listing endpoint crashed.

Fixed in two ways, not just one: `_preis_decimal()` normalizes `,` → `.` before parsing, *and* falls back to the compiled-in default on any other `InvalidOperation` rather than propagating the exception — a plain textarea/text-input settings field will eventually get a bad value again (typo, copy-paste artifact, whatever), and a single bad price string must never be able to crash every endpoint that happens to call `abo_preise()` (currently: admin Nutzerliste, `/api/abo/status`, `/api/einstellungen/public`, invoice generation). The admin Einstellungen form (`app/(app)/admin/einstellungen/page.tsx`) also got a small inline hint under both price fields ("bitte mit Punkt, nicht Komma") — cheap prevention, but the defensive parsing is the real fix; don't remove it even if the hint seems to make it redundant.

**General lesson for this settings store**: any numeric `einstellungen` value that gets `decimal.Decimal()`/`int()`/etc.-parsed at read time is one bad save away from taking down every caller, since `get_setting()` returns whatever string is stored with no validation at write time. If you add another numeric settings key, parse it as defensively as `_preis_decimal()` does — don't assume the stored string is well-formed just because the admin UI is "just" a plain text input.

## Legal-page links inside the logged-in app shell (pflegepilot_v3 only, 2026-07-24)

Gap found by the operator: `pflegepilot_alpha_v2` already has a `.sb-legal` sidebar link row for Impressum/Datenschutz/AGB (see that section above), but `pflegepilot_v3`'s `(app)/layout.tsx` never got the equivalent — once logged in, there was no way to reach any of the three legal pages at all (they only existed via the `(marketing)/` footer, which a logged-in user viewing `/dashboard` etc. never sees). Fixed with a small link row at the bottom of the sidebar `<aside>` (below the user/logout block), `target="_blank"` so it doesn't navigate the user away from whatever they were doing in the app. Lives in the same `<aside>` used for both the desktop-static and mobile-drawer sidebar, so no separate mobile handling was needed.

## Widerrufsrecht-Einwilligung bei Registrierung (pflegepilot_v3 only, 2026-07-24)

Added while drafting the real Datenschutzerklärung/Nutzungsbedingungen (`pflegepilot_v3/rechtstexte/`, operator-authored legal text, not application code, but referenced here since it drove this feature): since the service begins performance immediately on registration (account access, letter generation) rather than after the statutory 14-day Widerrufsfrist, § 356 Abs. 5 BGB requires the consumer's *express* consent to that early start plus explicit confirmation that they know they lose the right of withdrawal once the service is fully performed — a generic "I accept the ToS" checkbox does not satisfy this.

- Two separate mandatory checkboxes on the registration form (`components/AuthOverlay.tsx: RegisterForm`), each with its own exact legal wording (matching `Nutzungsbedingungen.txt` verbatim — if the ToS wording changes, update both places together): consent to early performance, and acknowledgment of losing the withdrawal right. Submit is disabled client-side until both are checked, and links to `/agb` open in a new tab (`target="_blank"`) so the registration form isn't lost.
- **Enforced server-side, not just client-side**: `POST /api/auth/registrieren` (`routers/auth.py`) rejects with 400 unless both `zustimmung_sofortbeginn` and `zustimmung_widerrufsverzicht` are `true` — a client-side-only checkbox gate would be trivial to bypass by calling the API directly, which would leave no valid consent record.
- `nutzer.widerrufsverzicht_bestaetigt_am` (migration `212cec88ae07`) stores *when* this consent was given, as the evidentiary record the ToS text promises ("Der Zeitpunkt dieser Bestätigung wird zu Nachweiszwecken gespeichert") — if a customer ever disputes having lost their withdrawal right, this timestamp is the proof. Not currently surfaced in the admin UI (query the DB directly if ever needed); add a display there if that becomes a recurring need.

## Krankenkassen-Stammdaten: completed against the official GKV list (2026-07-24)

A customer report of one missing insurer (`BKK Gildemeister-Seidensticker`) turned out to be a symptom of a bigger gap: `static_data/krankenkassen.py` was a curated subset (~87 entries) ported 1:1 from the old app, never checked against the actual complete set of German statutory insurers. Fixed properly rather than one entry at a time — cross-referenced against the official GKV-Spitzenverband list (93 gesetzliche Krankenkassen, Stand 2026) via a `transparent-beraten.de` summary PDF, then researched an individual verified address (from each insurer's own Impressum, preferring their stated Postfach/postal address over the street address where one exists) for every missing GKV entry. Now **94 German GKV entries** (essentially complete — the file also carries the full existing PKV/AT-SV/CH-KVG sections unchanged).

- **Three pre-existing data errors found and fixed in the same pass** (not just gaps): `"AOK Berlin-Brandenburg"` was a duplicate of `"AOK Nordost – Die Gesundheitskasse"` under an outdated name, and — worse — the *other* AOK Nordost entry itself had the wrong address (a regional Geschäftsstelle in Rostock instead of the actual Hauptsitz, Wilhelmstraße 1, 10963 Berlin); merged into one correct entry. `"IKK Nord"` was renamed to `"IKK – Die Innovationskasse"` back on 2021-02-01 — the file still had the old name and, it turned out, the wrong city too. `"actimonda BKK"` merged into `"BIG direkt gesund"` (already in the list) on 2021-01-01 and no longer exists as a separate insurer — removed rather than left as a dead end that would silently address mail to a defunct entity. **Lesson for future maintenance of this file**: a Krankenkasse name/address found once and never re-verified can go stale via mergers/renames — if a customer reports a wrong address (not just a missing one), check for exactly this pattern before assuming it's just outdated data entry.
- `briefe_text.py: _kk_adresse()` was fixed to skip the street line entirely when `strasse` is empty, rather than emitting a blank first line — needed because several insurers (e.g. `Mercedes-Benz BKK`, `BKK Salzgitter`) use a dedicated large-recipient postal code with no street at all (same pattern already handled for Rentenversicherung's `_rv_adresse()`, e.g. DRV Bund).
- Many entries prefer a **Postfach address over the street address** where the insurer's own Impressum lists one as the designated correspondence address (mirroring the DRV Bund precedent) — don't "simplify" these back to a street address without checking the source first.
- This list still won't stay perfectly current forever — Krankenkassen merge and rename periodically (as the IKK/actimonda cases above show happened within the last few years). No automated staleness check exists; re-verifying against the GKV-Spitzenverband list is a manual, occasional task.

## Budget-Tracker & Krisen-Checklisten (pflegepilot_v3 only, 2026-07-28)

Zwei Tester-Feedback-Punkte, beide unabhängig voneinander:

- **Budget-Tracker** (`leistungen.budget_jahr` + neue Tabelle `leistung_ausgaben`, Endpoints in `routers/leistungen.py`, UI-Komponente `components/BudgetTracker.tsx` je Leistung in der Patientenakte): Jahresbudget + Ausgabenerfassung pro Leistung, zeigt den Restbetrag mit einem festen Verfallshinweis "30.06. des Folgejahres" (passend zum bestehenden Entlastungsbetrag-Übertrag im Katalog). Bewusst **kein** Mehrjahres-Rollover-Ledger (z. B. getrennte Buchführung "verfallener Rest aus Vorjahr" vs. "aktuelles Jahresbudget") — das wäre für eine "kurze visuelle Übersicht" (Wortlaut des Tester-Feedbacks) überkonstruiert; bei Bedarf später ausbaufähig.
- **Krisen-Checklisten** (`static_data/krisenguides.py`, Endpoint `GET /api/krisenguides`, Seite `/guides`): vier Schritt-für-Schritt-Anleitungen (plötzliche Hospitalisierung, Sturz/Notfall, Tod des Angehörigen, Ausfall der Pflegeperson) — Liste mit dem Betreiber abgestimmt, da der Tester nur ein Beispiel nannte und um Ausarbeitung bat. Reiner Content, kein Rechtstext — ersetzt nie den Notruf 112.

## Proaktiver Server-Mailversand erweitert (pflegepilot_v3 only, 2026-07-28)

Tester-Feedback bat um zwei neue proaktive Benachrichtigungen (Leistungskatalog-Änderung, tägliche Tagebuch-Erinnerung), beide strukturell ohne jede Nutzeraktion, an die sich ein Versand anhängen ließe. Wichtig zur Einordnung: `pflegepilot_v3`s Musterbrief/Widerspruch/Ummeldung/Vollmacht-Generatoren haben **kein** Mailversand-Feature jeglicher Art (weder mailto noch SMTP) — sie erzeugen serverseitig ein PDF und bieten nur "PDF öffnen" zum Download an (die `mailto:`-Weiterleitung aus dem Abschnitt "Email: mailto hand-off, not SMTP" unten ist eine Beschreibung von `pflegepilot_alpha_v2`, nicht von v3 - dort erkennbar an `templates/index.html`/`sendMailModal()`, alten vanilla-JS-Bezeichnern). Die beiden neuen Punkte hier sind also nicht "eine dritte Ausnahme neben mailto", sondern schlicht die ersten beiden Fälle in v3, in denen serverseitig überhaupt eine Mail verschickt wird, außer dem Passwort-Reset. Vom Betreiber ausdrücklich freigegeben, nicht eigenmächtig entschieden. Die vollständige, aktuelle Liste proaktiver Mailversand-Faelle in v3:

1. **Passwort-Reset** (siehe "Passwort-vergessen per SMTP" oben) — die ursprüngliche, einzige Ausnahme.
2. **Leistungskatalog-Änderungsbenachrichtigung** (`app/katalog_watch.py`) — vergleicht bei jedem App-Start den aktuellen `KATALOG`-Stand (`static_data/katalog.py`) gegen einen in `katalog_snapshots` gespeicherten Schnappschuss (Betrag/Voraussetzung/Rechtsgrundlage je `katalog_id`). Weicht ein Eintrag ab, werden alle Nutzer benachrichtigt, die diese Leistung einem Patienten zugewiesen haben (`leistungen.katalog_id`) — sowohl der Nutzer selbst als auch der Patient, falls dieser eine eigene E-Mail hat. Erster Lauf nach Deploy legt nur den Baseline-Schnappschuss an, ohne zu benachrichtigen (sonst würde der komplette Katalog beim allerersten Start als "geändert" gemeldet).
3. **Tägliche Tagebuch-Check-in-Erinnerung** (`app/reminder_scheduler.py`) — je Nutzer ein/ausschaltbar mit frei wählbarer Uhrzeit (`nutzer.reminder_aktiv`/`reminder_uhrzeit`, Einstellungsseite unter `/einstellungen`). Da diese App bewusst **keine** Scheduler-/Cron-Infrastruktur hat (der Demo-Reset läuft absichtlich über einen Lazy-Check bei jedem Request statt über einen eigenständigen Hintergrundprozess, siehe "Demo account" unten), war das die erste Stelle, an der eine echte, uhrzeitgenaue Wiederkehr gebraucht wurde. Gelöst mit einem simplen Python-Bordmittel-Hintergrundthread (kein neuer Dependency wie APScheduler/Celery) statt echtem Cron.

**Beide neuen Mechanismen teilen dasselbe Multi-Worker-Problem und denselben Lösungsansatz**: Gunicorn startet mehrere Worker-Prozesse, die denselben Startup-/Thread-Code alle gleichzeitig ausführen würden — ohne Schutz gäbe es doppelte Benachrichtigungsmails (dieselbe Klasse von Bug wie der dokumentierte Changelog-Duplikat-Vorfall, nur diesmal mit einem Seiteneffekt statt einem reinen Insert, wo `ON CONFLICT DO NOTHING` nicht ausreicht). Beide nutzen deshalb einen **Postgres-Advisory-Lock** (`pg_try_advisory_lock`, je ein fest gewählter, eindeutiger Integer-Schlüssel): bei `katalog_watch.py` nur für die Dauer eines einzelnen Abgleichs beim Start, bei `reminder_scheduler.py` über die **gesamte Lebensdauer** des Hintergrund-Threads (Lock hängt an einer dauerhaft offenen Connection). Nur der Worker, der den Lock zuerst bekommt, macht die Arbeit; alle anderen überspringen sie für diesen Prozess-Start vollständig — ausreichend, da genau ein Worker im gesamten Container die Aufgabe übernehmen muss, nicht jeder einzelne.

`app/email_util.py: send_email()` bleibt die einzige Stelle, an der SMTP angefasst wird, für alle drei Fälle gemeinsam genutzt.

## Umkreissuche für lokale Pflege-Dienstleister (pflegepilot_v3 only, 2026-07-28, T10–T13)

Tester-Feedback wollte eine Umkreissuche nach PLZ für Pflegedienste, Sanitätshäuser, diverse Wohnformen (Pflegeheim, betreutes Wohnen, Tagespflege, Demenz-Wohngruppe, soziales Café) und Therapie/Reha-Einrichtungen (Logopädie, Physiotherapie, Reha-Zentrum). Anders als bei Krankenkassen/Rentenversicherung (ein paar Dutzend bis ~100 Einträge, handkuratierbar) gibt es hier mehrere Tausend Anbieter bundesweit — eine statische Liste war nie eine Option.

- **Datenquellen-Entscheidung, bewusst vom Betreiber getroffen (nicht von Claude)**: OpenStreetMap statt Google Places API — kostenlos, kein API-Key/Account/Zahlungsmethode nötig, dafür lückenhaftere/uneinheitlicher gepflegte Daten als ein kommerzieller Dienst. Zwei separate OSM-Dienste sind beteiligt: **Nominatim** (PLZ → Koordinaten) und **Overpass API** (`overpass-api.de`, getaggte Einrichtungen im Umkreis). Beide sind offene Community-Infrastruktur ohne Key — dafür ist der öffentliche Overpass-Mirror gelegentlich träge/kurzzeitig überlastet, siehe Betriebshinweis unten.
- **`app/umkreissuche.py`** ist die zentrale Logik: `KATEGORIEN`-Registry (Kategorie-Key → Label + Liste von Overpass-Tag-Filtern), `_geocode_plz()`, `_overpass_suche()` (baut die Overpass-QL-Query, ein Retry-Versuch mit 2s Pause gegen transiente Timeouts des öffentlichen Mirrors), `suche()` (Ergebnis-Parsing, Haversine-Distanzberechnung, Sortierung nächste zuerst, gekappt auf 30 Treffer). **Bewusst als Registry statt if/elif-Kette** — T10 legte nur `pflegedienst` an, T11–T13 haben ausschließlich neue `KATEGORIEN`-Einträge ergänzt, ohne Suchlogik/Router/Frontend anzufassen (Frontend-Kategorieauswahl ist datengetrieben über `GET /api/umkreissuche/kategorien`, brauchte für T11–T13 keine einzige Zeile Änderung).
- **OSM-Tags je Kategorie recherchiert gegen OSM-Wiki (`DE:Tag:...`-Seiten) und taginfo.openstreetmap.org, nicht geraten**: `amenity=social_facility`+`social_facility=ambulatory_care` (Pflegedienst), `shop=medical_supply` (Sanitätshaus), `social_facility=nursing_home`/`assisted_living`/`day_care`/`group_home`+`for=dementia` (Wohnformen — jeweils zusätzlich das ältere, laut Wiki noch nicht vollständig migrierte `amenity=nursing_home`/`retirement_home`-Tag mitabgefragt, damit nicht-migrierte Bestandsdaten nicht verloren gehen), `healthcare=speech_therapist`/`physiotherapist`/`rehabilitation` (Therapie/Reha).
- **Zwei bekannte, bewusste Lücken statt vorgetäuschter Vollständigkeit**: "Soziales Café" hat kein verlässliches OSM-Tag — behelfsweise über `amenity=community_centre` abgebildet, Label sagt explizit "(geringe Datenlage)". "Reha-Sport" wurde als eigene Kategorie **ausgelassen** — es gibt dafür überhaupt kein brauchbares OSM-Tag (Kurse finden meist in normalen Sportvereinen/Fitnessstudios ohne eigenen kartierbaren Ort statt); eine Kategorie mit strukturell unzuverlässiger Trefferquote anzubieten wäre schlechter, als sie wegzulassen.
- **`pflegedienst_24h` (24h-Pflegedienst/Betreuung rund um die Uhr, ergänzt 2026-07-29 nach weiterem Tester-Feedback)**: gegen das OSM-Wiki recherchiert — es gibt **kein eigenes Tag** dafür; korrekt wäre `ambulatory_care` + `opening_hours=24/7`, aber `opening_hours` wird bei Pflegediensten in der Praxis so gut wie nie gepflegt, eine reine Tag-Suche darauf liefert praktisch keine Treffer. Stattdessen ein **Namens-Musterfilter** auf denselben `ambulatory_care`-Treffern (`["name"~"24.?h|24.?stunden",i]`) — 24h-Anbieter/-Vermittler tragen "24h"/"24-Stunden" in aller Regel im eigenen Firmennamen (Branchenusus). Gleiche Kompromiss-Logik wie bei "Soziales Café", Label ebenfalls explizit mit "(geringe Datenlage)" markiert. Live gegen die echte Overpass-API verifiziert (nach anfänglichen 429/504 durch den ohnehin knappen Rate-Limit des öffentlichen Mirrors, 2 gleichzeitige Slots pro IP, siehe Betriebshinweis unten): die Suche lief für PLZ 10115/30 km fehlerfrei durch (0 Treffer) — bestätigt sowohl die korrekte Query-Syntax als auch die erwartete geringe Datenlage, kein Zeichen eines Fehlers im Code selbst.
- **Betriebshinweis**: Der öffentliche Overpass-Mirror antwortet bei schnell aufeinanderfolgenden Anfragen (z.B. Kategorie-Wechsel im Sekundentakt) gelegentlich mit einem Timeout, obwohl er grundsätzlich erreichbar ist — beim Testen dieser Funktion mehrfach beobachtet und durch einfaches erneutes Anfragen (bzw. den eingebauten Retry) bestätigt transient. Kein Zeichen für einen echten Ausfall; wird sauber als 502 mit deutscher Fehlermeldung an den Nutzer durchgereicht, nicht als 500-Crash.
- Router `app/routers/umkreissuche.py`: `GET /api/umkreissuche/kategorien` (Liste fürs Frontend-Select), `GET /api/umkreissuche?plz=&kategorie=&radius_km=` (5-stellige PLZ, Radius aus `{5,10,15,25,50}`, beides serverseitig validiert). Frontend: `lib/umkreissuche.ts` + `(app)/umkreissuche/page.tsx`, Nav-Eintrag unter "Verwaltung".
- **Favoriten sind bewusst je Nutzerkonto, nicht je Patient** (explizite Vorgabe des Betreibers) — ein gefundener Pflegedienst/Sanitätshaus/etc. ist typischerweise für alle vom Konto verwalteten Patienten gleichermaßen relevant, nicht auf einen einzelnen beschränkt. Modell `UmkreissucheFavorit` (`umkreissuche_favoriten`-Tabelle, Migration `a7c4e9f1b2d3`), `UniqueConstraint(nutzer_id, osm_type, osm_id)` verhindert Duplikate und macht `POST /api/umkreissuche/favoriten` idempotent (erneutes Merken desselben OSM-Objekts gibt den bestehenden Favoriten zurück statt einen Fehler zu werfen). Name/Adresse/Kontakt werden beim Merken kopiert (nicht live nachgeladen), damit ein Favorit auch anzeigbar bleibt, wenn Overpass gerade down ist oder der Eintrag in OSM verschwindet — das ist auch der Grund, warum jeder Umkreissuche-Treffer jetzt `osm_type`+`osm_id` mitliefert (eindeutiger, stabiler Schlüssel für "ist das schon gemerkt?"-Abgleich im Frontend). `GET/POST/DELETE /api/umkreissuche/favoriten[/​{id}]`, alle `require_login`-geschützt und implizit auf den eigenen Nutzer beschränkt (kein `patient_id`-Bezug irgendwo in diesem Datenfluss).
- **Rechtstexte aktualisiert (2026-07-28)**: `rechtstexte/Datenschutzerklaerung.txt` bekam eine neue Ziffer 11 ("Umkreissuche für Pflegedienste, Sanitätshäuser und weitere Einrichtungen"), die den Nominatim-/Overpass-Datenfluss offenlegt (nur PLZ+Kategorie+Radius werden übermittelt, serverseitig — die Nutzer-IP erreicht diese Dienste nie; kein AVV nach Art. 28 DSGVO möglich, da es sich um freie Gemeinschaftsinfrastruktur ohne Vertragspartner handelt, daher als eigenständige Drittübermittlung nach Art. 6 Abs. 1 lit. b/f DSGVO eingeordnet), alle Folgeziffern wurden entsprechend hochgezählt (12–18). `Nutzungsbedingungen.txt` bekam einen Feature-Bullet in Ziffer 2.1 plus einen Haftungsausschluss in Ziffer 11.6 für die Richtigkeit der von OSM stammenden Anbieterdaten. **Wichtig**: diese `.txt`-Dateien sind nur die Betreiber-Quelltexte — die tatsächlich angezeigten Rechtstexte liegen als `einstellungen`-Keys (`rechtstext_datenschutz`/`rechtstext_agb`) in der DB und werden manuell über die Backend-Einstellungen im Admin-UI gepflegt (siehe "Admin focus, self-registration & legal pages"); es gibt keinen automatischen Datei→DB-Sync wie beim Changelog. Der Betreiber muss die aktualisierten Texte nach diesem Änderungsdurchlauf selbst ins Admin-UI übertragen, damit sie live wirksam werden.

## Benachrichtigung bei Änderung eines Umkreissuche-Favoriten (pflegepilot_v3 only, 2026-07-29, T15)

Letzter Punkt aus dem ursprünglichen Tester-Feedback-Backlog: wenn sich Kontaktdaten eines gemerkten Umkreissuche-Treffers (Pflegedienst, Sanitätshaus, Wohnform, Therapie-/Reha-Einrichtung — siehe "Umkreissuche für lokale Pflege-Dienstleister" oben) in OSM ändern, wird der Kontoinhaber per E-Mail informiert.

- `app/umkreis_favoriten_watch.py`, dritte Ausnahme vom "mailto statt SMTP"-Prinzip (nach Passwort-Reset und T14/Katalog-Änderung) — es gibt keine Nutzeraktion, an die sich der Versand hängen ließe.
- **Läuft als echter wiederkehrender Hintergrundjob** (wie `reminder_scheduler.py`), nicht nur einmalig pro App-Start wie `katalog_watch.py` — ein OSM-Eintrag kann sich jederzeit ändern, nicht nur bei einem Deploy dieser App. **Bewusst nur einmal täglich**: der öffentliche Overpass-Mirror hat ein sehr knappes Rate-Limit — **real erlebt während der Entwicklung dieses Features: nur 2 gleichzeitige Slots pro IP** (`curl https://overpass-api.de/api/status`) —, eine häufigere Abfrage aller Favoriten aller Konten wäre unverhältnismäßig für eine kostenlose Gemeinschaftsinfrastruktur.
- **Sammel-Abfrage statt einer Anfrage je Favorit**: alle Favoriten desselben `osm_type` (node/way/relation) werden in möglichst wenigen Overpass-Anfragen per ID-Filter abgeholt (`node(id:1,2,3);`, siehe OSM-Wiki "Overpass QL – By element ID"), in Chunks von 100 IDs mit 2s Pause dazwischen — bei z. B. 50 gemerkten Favoriten sonst 50 statt 1-3 Anfragen pro Durchlauf.
- Gleiches Multi-Worker-Problem/-Lösung wie bei allen anderen Hintergrund-Schedulern dieser App: Postgres-Advisory-Lock (`519274863`) über die gesamte Thread-Lebensdauer.
- **Verglichene Felder**: Name, Straße, PLZ, Ort, Telefon, E-Mail, Webseite. Bei Abweichung wird der gespeicherte Favorit-Snapshot auf den neuen Stand aktualisiert (sonst würde dieselbe Änderung an jedem folgenden Tag erneut gemeldet) und eine E-Mail an den Kontoinhaber verschickt — mehrere geänderte Favoriten desselben Kontos werden zu einer einzigen Mail pro Durchlauf gebündelt statt mehrerer Einzelmails.
- **Bewusste Einschränkung**: ist ein Favorit in OSM komplett nicht mehr auffindbar (gelöscht), wird das nur geloggt, nicht dem Nutzer gemeldet — ein "verschwunden statt geändert"-Notify-Flow bräuchte eine zusätzliche Schutzmaßnahme gegen tägliche Wiederholungsmeldungen (z. B. ein neues Schema-Feld oder automatisches Löschen des Favoriten), was für den ursprünglichen Tester-Wunsch ("Kontaktdaten geändert") überkonstruiert wäre.
- **End-to-end gegen einen echten, produktiv gemerkten Favoriten verifiziert** (nicht nur synthetisch): Overpass-ID-Abfrage lief mit HTTP 200 durch, die live aus OSM gelesenen Werte stimmten mit dem gespeicherten Stand überein — kein Fehlalarm, keine E-Mail ausgelöst, Datensatz unverändert.

## Umkreissuche: Kategorie "24h-Pflegedienst" (pflegepilot_v3 only, 2026-07-29)

Zusätzliches Tester-Feedback nach Abschluss von T8/T10-T13: `pflegedienst_24h` als neue Kategorie in derselben `KATEGORIEN`-Registry (`app/umkreissuche.py`) — siehe dortigen Eintrag unter "Umkreissuche für lokale Pflege-Dienstleister" für die Details (kein eigenes OSM-Tag, Namens-Musterfilter statt Tag-Filter, "(geringe Datenlage)" im Label). Da die Frontend-Kategorieauswahl datengetrieben über `GET /api/umkreissuche/kategorien` läuft, war dafür keine einzige Frontend-Codezeile nötig — reine Backend-Registry-Ergänzung, gleiches Muster wie T11-T13.

## Landingpage-Überarbeitung + SEO (pflegepilot_v3 only, 2026-07-29)

Betreiber-Wunsch: die Startseite einladender gestalten, die Feature-Breite der App sichtbar machen ("was er für sein bisschen Geld alles bekommt"), dabei keine Backend-/Technik-Details offenlegen, für SEO optimieren und wo sinnvoll Admin-editierbar machen.

- **`(marketing)/page.tsx` von einer Client-Component (`"use client"`, React-Query-Hook) zu einer async Server Component umgebaut** — das war die Voraussetzung für echtes SEO: eine `"use client"`-Seite kann kein `generateMetadata()` exportieren (Next.js verlangt dafür eine Server Component), und ein clientseitig nachgeladener Seiteninhalt ist für Suchmaschinen-Crawler weniger zuverlässig als serverseitig bereits im initialen HTML vorhandener Text. Die Seite brauchte ohnehin keine Interaktivität (nur `<Link>`, keine Events/State) — der Umbau war deshalb reine Entfernung von `"use client"` plus Umstellung von `usePublicEinstellungen()` (Client-Hook) auf einen eigenen serverseitigen `fetch()`-Helper (`ladeOeffentlicheEinstellungen()`), den sowohl `generateMetadata()` als auch die Seite selbst aufrufen — Next.js dedupliziert identische `fetch()`-Aufrufe automatisch innerhalb desselben Requests, kein doppelter Roundtrip.
- **Neue Umgebungsvariable `API_INTERNAL_URL` (nicht `NEXT_PUBLIC_API_URL`) für diesen serverseitigen Fetch** — wichtiger Unterschied, der beim Bauen erst durch Nachschauen in der echten NAS-`.env` auffiel: `NEXT_PUBLIC_API_URL` ist dort bewusst **leer** (der externe Zugriff läuft über Pfad-Routing im Reverse-Proxy, der Browser ruft `/api/*` relativ zur selben Domain auf, siehe "Externer Zugriff über Nginx Proxy Manager" in der NAS-Deployment-Memory) — ein serverseitiger `fetch()` auf einen relativen Pfad hätte keine Basis-URL und würde fehlschlagen. Und selbst ein gesetzter Wert wäre falsch gewesen: `localhost:8100` ist nur der **host-seitig gemappte** Port, aus einem anderen Container (hier: `web`) heraus nicht erreichbar. Der korrekte Weg für Container-zu-Container-Kommunikation ist der interne Docker-Compose-Servicename (`API_INTERNAL_URL=http://api:5050` in `docker-compose.yml`, Default über `${API_INTERNAL_URL:-http://api:5050}` auch ohne `.env`-Eintrag) — gilt identisch für lokale Entwicklung und die NAS, da beide dieselbe `docker-compose.yml` mit denselben Servicenamen nutzen. Per direktem `node -e "fetch(...)"` im laufenden `web`-Container sowie durch einen echten DB-Testwert (`landing_seo_title`, hinterher wieder entfernt) end-to-end verifiziert. Der Fetch nutzt `cache: "no-store"` statt einer Revalidate-Frist — beim Testen blieb ein per DB-Testwert geänderter Seiteninhalt trotz `next: { revalidate: 300 }` und mehrfacher Anfragen im Abstand von Sekunden bis Minuten auf dem alten Stand (vermutlich eine Turbopack-Dev-Mode-Eigenheit), sodass ein Admin nach dem Speichern in den Backend-Einstellungen nicht zuverlässig sofort das Ergebnis gesehen hätte — bei so geringem Traffic auf einer einzelnen Landingpage ist der Verzicht auf Caching hier vernachlässigbar.
- **Feature-Liste erheblich erweitert** (von 6 auf 10 Kacheln) — deckt jetzt alle inzwischen gebauten Funktionen ab (Vollmacht/Patientenverfügung, Ummeldung, Umkreissuche mit Favoriten, Dokumenten-/eGK-Scan, Budget-Tracker, Krisen-Checklisten), nicht nur den Stand von Phase 3. Bewusst **keine** Technik-/Backend-Begriffe im Text (kein "OpenStreetMap", "Tesseract", "PostgreSQL" etc.) — nur nutzerorientierte Nutzenbeschreibung.
- **SEO-Metadaten**: `generateMetadata()` liefert Titel/Beschreibung/OpenGraph/Twitter-Card/kanonische URL, mit Fallback auf fest hinterlegte Standardtexte, falls die Einstellungen (noch) leer sind oder die API einmal nicht erreichbar ist (`try/catch`, gibt dann `{}` zurück statt die Seite abstürzen zu lassen). Zusätzlich ein `SoftwareApplication`-JSON-LD-Block (schema.org) mit Preis aus den echten `abo_preis_*`-Einstellungen, nicht hartkodiert.
- **`src/app/robots.ts` und `src/app/sitemap.ts` neu** (existierten vorher gar nicht) — `robots.ts` erlaubt explizit nur die öffentlichen Marketing-Seiten (`/`, `/impressum`, `/datenschutz`, `/agb`) und disallowed explizit jede bekannte `(app)`-Route; bewusst zwei explizite Listen statt eines einzigen `disallow:"/"` mit Allow-Ausnahmen, damit eine künftig neu hinzukommende `(app)`-Route nicht versehentlich indexiert wird, nur weil sie vergessen wurde, in eine Disallow-Liste einzutragen. Neue Env-Var `NEXT_PUBLIC_SITE_URL` (Default `https://meinpflegefuchs.de`) für kanonische URLs/OpenGraph/Sitemap-Domain.
- **Modularität ins Admin-Dashboard eingebaut, wie gewünscht — aber bewusst nur für Hero-Text und SEO-Meta, nicht für die Feature-Kacheln selbst**: vier neue `einstellungen`-Keys (`landing_hero_titel`, `landing_hero_text`, `landing_seo_title`, `landing_seo_description`), als neue Karte "Landingpage & SEO" in den Backend-Einstellungen (`admin/einstellungen/page.tsx`) editierbar — genau das bereits bestehende generische Key-Value-Muster (`einstellungen_lesen`/`einstellungen_speichern` in `routers/admin.py` nehmen ohnehin jeden beliebigen Key an, keine Backend-Änderung dort nötig), plus Aufnahme der vier neuen Keys in die `_PUBLIC_KEYS`-Allowlist von `/api/einstellungen/public`. Die zehn Feature-Kacheln selbst bleiben bewusst im Code fest verdrahtet (kein dynamischer Kachel-Editor/CRUD im Admin-UI) — sie sind 1:1 an echte App-Funktionen gebunden, ein frei editierbarer Marketingtext könnte sonst leicht von der tatsächlichen Funktion abweichen; der Aufwand für ein vollwertiges Kachel-CRUD (Icon-Auswahl, Reihenfolge, …) stünde zudem in keinem Verhältnis zu Marketingtext, der selten geändert wird.
- **Betriebs-Lehre aus dem Deploy dieser Änderung**: die bisherige Annahme "`docker compose up -d --force-recreate web` reicht immer" (siehe NAS-Deployment-Notizen) stimmte diesmal nicht — ein per DB-Testwert erwartbar geänderter Seiteninhalt blieb nach einem normalen Force-Recreate zunächst auf dem alten Stand hängen (vermutlich ein von Turbopack/Next.js gehaltener Fetch-Cache, der einen reinen Force-Recreate übersteht, kombiniert mit Docker Composes Standardverhalten, anonyme Volumes beim Neuerstellen vom alten Container zu übernehmen statt sie neu anzulegen). Tatsächlich wirksam war erst `docker compose build web` gefolgt von `docker compose up -d --force-recreate --renew-anon-volumes web`. **Vorsicht**: `--renew-anon-volumes` ohne vorherigen Rebuild reißt `node_modules` weg (liegt selbst in einem anonymen Volume, das nur beim Image-Build aus dem Image befüllt wird) — immer erst bauen, dann mit `--renew-anon-volumes` neu erstellen, nie isoliert. Für reine Code-Änderungen ohne diese Cache-Problematik reicht weiterhin das einfachere `--force-recreate` allein.

## Kalender-Export für Aufgaben (pflegepilot_v3 only, 2026-07-28)

Nicht aus dem Tester-Feedback, sondern eine Anschlussfrage des Betreibers zu T15/Kalenderthemen: pro fälliger Aufgabe zwei kleine Buttons ("Zum Kalender hinzufügen") auf der Aufgaben-Seite, mit den bekannten Apple-/Google-Icons (`IconBrandApple`/`IconBrandGoogle`, `@tabler/icons-react` — keine mehrfarbigen Marken-SVGs eingebettet, monochrome Icons reichen für die Wiedererkennung).

- **Ein iCal-Format deckt beide Anbieter ab** — Google Calendar kann `.ics`-Dateien direkt importieren, es brauchte also keine separate "Google-Integration": `GET /api/aufgaben/{aid}/ics` (`app/routers/aufgaben.py`) liefert ein minimales `VCALENDAR`/`VEVENT` (ganztägig am `faellig_am`-Datum, `DTEND` = Folgetag nach iCal-Konvention für Ganztags-Events), normal sessionauthentifiziert (kein Token/Abo-Mechanismus nötig, da es ein direkter Klick-Download ist, keine wiederkehrend abgerufene Abo-URL) — Ownership-Check via neuem `_owned_aufgabe_or_404()`-Helper (aus dem bereits existierenden Inline-Check in `erledigt()` extrahiert). Sonderzeichen (Komma/Semikolon/Backslash/Zeilenumbruch) werden über `_ics_escape()` nach RFC 5545 escaped; Zeilen-Folding (>75 Oktette) bewusst weggelassen, da für die kurzen Titel/Beschreibungen dieser App nicht praxisrelevant.
- **Der Google-Button braucht gar keinen Backend-Aufruf**: Googles öffentliches, unauthentifiziertes "Quick Add"-URL-Schema (`calendar.google.com/calendar/render?action=TEMPLATE&text=&dates=&details=`) wird rein clientseitig aus den bereits geladenen Aufgaben-Daten gebaut (`lib/aufgaben.ts: googleCalendarUrl()`), kein OAuth/API-Key/Google-Cloud-Projekt nötig.
- **Bewusst kein Abo-Feed** (kontinuierlich synchronisierender externer Kalenderabo-Link) — das wäre die teurere, im Gespräch verworfene Alternative gewesen (bräuchte einen eigenen, regenerierbaren Token pro Nutzerkonto, da Kalender-Clients Abo-URLs ohne Session-Cookie periodisch selbst abrufen). Aktuelle Lösung ist bewusst ein einmaliger Pro-Aufgabe-Export, kein laufend aktualisiertes Abo.

## PLZ→Ort-Autofill bei Nutzer- und Patienten-Anlage (pflegepilot_v3 only, 2026-07-28)

Sobald eine 5-stellige Postleitzahl eingegeben ist, wird das Ort-Feld automatisch übernommen — auf der Selbstregistrierung (Rechnungsanschrift, `AuthOverlay.tsx`), im "Neuer Patient"-Assistenten (`patienten/neu/page.tsx`, Step 2) und im Patient-Bearbeiten-Formular (`patienten/[id]/bearbeiten/page.tsx`).

**Ort ist ein von der PLZ abgeleitetes Feld, kein einmaliger Vorschlag** (Betreiber-Vorgabe): vollständige, bekannte PLZ → Ort wird übernommen, auch wenn vorher ein anderer Wert dort stand; unvollständige oder gelöschte PLZ → Ort wird automatisch geleert. Damit bleibt bei einem Vertipper nie ein zur PLZ nicht mehr passender Ort stehen, den man sonst manuell erst löschen müsste — Korrektur der PLZ genügt, der Ort folgt automatisch mit. Das Ort-Feld bleibt trotzdem ein normales, editierbares Textfeld (kein Dropdown/readonly) — für die seltenen Fälle, in denen die PLZ nicht in der Datenbank steht oder der Vorschlag falsch ist, kann der Nutzer weiterhin manuell eintragen; dieser manuelle Wert bleibt nur so lange bestehen, bis die PLZ das nächste Mal geändert wird.

- **Datenbasis statt Live-Geocoding**: anders als bei der Umkreissuche (dort bewusst Nominatim/Overpass live, da Umkreissuche echte Koordinaten braucht) ist PLZ→Ort eine stabile, sich praktisch nie ändernde Zuordnung — dafür passt eine gebündelte, lokale Datei besser als ein externer Live-Call bei jedem Tastenanschlag: schneller, kein Rate-Limit-Risiko, keine Abhängigkeit von einem Drittserver für einen so grundlegenden Formular-Baustein. `app/static_data/plz_orte.json` (~9.000 Einträge) + dünner Loader `plz_orte.py`, Quelle: GeoNames.org Postal-Code-Export für Deutschland (`download.geonames.org/export/zip/DE.zip`, CC BY 4.0).
- **Grosskunden-PLZ-Problem**: der GeoNames-Rohexport (~10.800 Zeilen) enthält neben normalen Wohnort-PLZ auch ca. 1.800-2.000 deutsche Grosskunden-PLZ (dedizierte Einzelfirma-Postleitzahlen, z. B. „10875" ausschliesslich für Mercedes-Benz-Gesellschaften in Stuttgart) — bei diesen steht im Ortsnamen-Feld ein Firmen-/Behördenname statt eines echten Orts. Über eine Firmennamen-Erkennung (Rechtsformen wie GmbH/AG/KG, Behördenbegriffe wie Finanzamt/Ministerium/Bezirksregierung, Kassen/Verbände/Kammern etc.) grösstenteils herausgefiltert — nicht perfekt (vereinzelte reine Regierungssitz-PLZ ohne echten Orts-Kandidaten, z. B. „01095" → Sächsische Staatskanzlei, können noch falsch zugeordnet sein), aber für eine Autofill-Komfortfunktion ausreichend, da der Vorschlag jederzeit überschreibbar ist.
- **Mehrdeutige PLZ** (ca. 2.000 Fälle, meist ländliche PLZ, die mehrere Nachbargemeinden/Ortsteile abdecken, z. B. Dresdner Stadtteile) lösen sich auf den **kürzesten** Kandidatennamen auf (meist der schlichte Orts-/Stadtname ohne Ortsteil-Zusatz) — bewusst kein Mehrfachauswahl-Dropdown, da für eine einfache Autofill-Funktion nicht gerechtfertigt.
- `GET /api/plz/{plz}` (`app/routers/plz.py`) ist **bewusst ohne Login-Pflicht** — die Selbstregistrierung braucht die Autofill-Funktion, bevor überhaupt ein Konto existiert; keine sensiblen Daten involviert (reine öffentliche Postleitzahl-Referenzdaten), gleiches Risikoprofil wie `/api/einstellungen/public`.
- Frontend: `lib/plz.ts: usePlzSync(plz, setOrt, aktiv=true)`. Der `aktiv`-Parameter existiert ausschliesslich fuer das Bearbeiten-Formular: dort ist beim Laden bereits eine vorhandene, potenziell korrekte Adresse im Formular (die nicht zwingend aus dieser PLZ-Datenbank stammt) — ohne Schutz wuerde das blosse Oeffnen der Seite den bestehenden Ort sofort mit dem Datenbank-Vorschlag ueberschreiben, noch bevor der Nutzer irgendetwas angefasst hat. Deshalb bekommt `usePlzSync` dort zusaetzlich einen `plzBeruehrt`-State (gleiches Muster wie das bereits bestehende `versichertennummerBeruehrt`), der erst per PLZ-Feld-`onChange` auf `true` gesetzt wird - die Sync-Logik (uebernehmen/leeren) greift dann erst ab der ersten echten Nutzereingabe. Die beiden Anlage-Formulare (Registrierung, "Neuer Patient") haben keine vorhandene Adresse zu schuetzen und lassen `aktiv` einfach auf dem Default `true`.
- Datei ist eine einmalige Momentaufnahme (Stand 2026-07-28) — Postleitzahlen ändern sich in Deutschland selten, aber nicht nie (Neubaugebiete, Gemeindefusionen); keine automatische Aktualisierung eingerichtet, bei Bedarf manuell gegen einen neuen GeoNames-Export re-generieren.

## Patientenverfügung-Generator (pflegepilot_v3 only, 2026-07-28)

Fünfter Dokument-Generator neben Widerspruch/Musterbrief/Ummeldung/Vollmacht — auf ausdrücklichen Wunsch als **mehrstufiges Interview** statt eines einzelnen Formulars, weil vor der PDF-Erzeugung inhaltlich einiges abgeklärt werden muss (in welchen Situationen soll die Verfügung gelten, welche medizinischen Maßnahmen in diesen Situationen gewünscht/abgelehnt werden, Organspende, Bezug zu einer bereits hinterlegten Vollmacht etc.).

- **Formulierungen sind wortgetreu aus der offiziellen Broschüre "Patientenverfügung" des Bundesministeriums der Justiz übernommen** (bmj.de, Abschnitt 2 "Textbausteine Patientenverfügung", Stand Januar 2023 laut dem PDF selbst) — siehe `app/static_data/patientenverfuegung_textbausteine.py` für die vollständige Begründung, warum das zulässig ist: die Arbeitsgruppe "Patientenautonomie am Lebensende" hat diese Textbausteine ausdrücklich als Formulierungshilfen zur **wörtlichen Übernahme** durch Bürgerinnen und Bürger veröffentlicht — genau das ist der Verwendungszweck hier, kein Zitat im Sinne des Urheberrechts. Nicht selbst formuliert, sondern per PyMuPDF (`fitz`) aus dem offiziellen PDF extrahiert und 1:1 geprüft, um keine eigene, rechtlich unbelastbare Formulierung unterzuschieben.
- **Struktur folgt der von der Broschüre selbst empfohlenen Gliederung** (Abschnitt 1.11 "Empfohlener Aufbau"): Eingangsformel → Situationen (2.2) → Festlegungen zu ärztlichen Maßnahmen (2.3, alle 8 Kategorien: Lebenserhaltung, Wiederbelebung A+B, Schmerzbehandlung, künstliche Ernährung, Beatmung, Dialyse, Antibiotika, Blut) → Ort/Beistand (2.4) → Schweigepflichtentbindung (2.5) → Verbindlichkeit/Auslegung (2.6) → Vorsorgevollmacht-/Betreuungsverfügung-Bezug (2.7) → Organspende (2.9) → Schlussformel (2.10) → Schlussbemerkungen (2.11, immer enthalten) → Beratung (2.12) → optionales Freifeld für spätere ärztliche Bestätigung der Einwilligungsfähigkeit (2.13).
- **Fortlaufende statt fester Abschnittsnummerierung** (`build_patientenverfuegung_text()` in `app/briefe_text.py`, Variable `abschnitt`): mehrere Abschnitte sind optional (nur bei entsprechenden Angaben, z.B. kein Ort/Beistand-Abschnitt wenn nichts dazu angegeben wurde) — mit fest einprogrammierten Ziffern hätte eine leere Angabe zu Nummerierungslücken geführt (z.B. "2. ... 5. ..." ohne 3./4.), was in einem rechtlich bedeutsamen Dokument wie eine Fehlstelle wirken würde. Gefunden und gefixt noch während der Verifikation dieser Session, nicht erst durch Nutzer-Feedback.
- **Kein Fensterkuvert-Layout, kein Unterzeichner-Wechsel bei hinterlegter Vollmacht** — anders als die anderen vier Generatoren ist dies kein Brief an einen Empfänger, sondern eine eigenständige persönliche Erklärung. Neues, eigenes PDF-Template `app/pdf_templates/patientenverfuegung.html` (kein Absender-/Empfänger-Fenster, dafür Titel-Layout). Eine Patientenverfügung drückt begrifflich zwingend den eigenen Willen der betroffenen Person aus und kann nicht durch eine bevollmächtigte Person an ihrer Stelle unterschrieben werden — die `_unterzeichner()`/Vollmacht-Wechsel-Logik aus `routers/briefe.py` wird hier bewusst nicht verwendet, es unterschreibt immer nur der Patient selbst.
- **Layout-Fix während der Verifikation**: die optionale ärztliche Bestätigung (2.13) wurde zunächst in den Fließtext eingebettet und erschien dadurch *vor* der eigentlichen Patienten-Unterschrift im PDF — inhaltlich falsche Reihenfolge (die eigene Unterschrift gehört direkt nach der Erklärung, der ärztliche Anhang ist ein nachgelagerter, optionaler Zusatz). Gefixt, indem der Baustein aus `build_patientenverfuegung_text()` entfernt und stattdessen als eigener, bedingter Block *nach* dem `unterschriften`-Div direkt im Template gerendert wird (`aerztliche_bestaetigung`-Flag an `render_pdf()`).
- `Antrag.typ` erweitert um `'patientenverfuegung'` (Migration `b8d3e5f7a1c9`), nutzt denselben autorisierungsgeprüften Download-Endpunkt wie alle anderen Briefe (`GET /api/patienten/{pid}/antraege/{aid}/pdf`) — keine neue Speicher-/Download-Infrastruktur nötig.
- `GET /api/patientenverfuegung/textbausteine` liefert alle Options-Daten fürs Interview (Situationen, Maßnahmen-Kategorien mit Formulierungen, Vertrauensperson-/Organspende-Optionen) — normal `require_login`-geschützt (anders als der öffentliche PLZ-Endpunkt, da dies nur innerhalb der eingeloggten App gebraucht wird).
- **Kein Anspruch auf Vollständigkeit oder Rechtsberatung**: Fußzeile im generierten PDF weist explizit auf die Quelle (BMJ-Broschüre) hin und stellt klar, dass dies keine rechtliche oder ärztliche Beratung ersetzt — eine Patientenverfügung ist nur wirksam, wenn sie tatsächlich der freie Wille der volljährigen, einwilligungsfähigen Person ist (§ 1901a BGB); das kann Software nicht prüfen. Im Ergebnis-Bildschirm nach Erstellung wird zusätzlich auf das Zentrale Vorsorgeregister (vorsorgeregister.de, Bundesnotarkammer) als Möglichkeit hingewiesen, die Verfügung im Ernstfall auffindbar zu machen — die App selbst registriert dort nichts automatisch.

## Interview-Wizard Schritt 4: neutralere Fragen + Sprung für "Bedürftige" (pflegepilot_v3 only, 2026-07-30)

Bei gemeinsamer Durchsicht mit dem Betreiber aufgefallen: die 5 Pflegegrad-Situationsfragen (`static_data/pflegegrad_regeln.py: FRAGEN`) waren für alle drei Zielgruppen (Alterspflege/Bedürftige/Behinderte) exakt identisch — bestätigt durch Code-Prüfung: weder `GET /api/pflegegrad/fragen` noch `POST /api/pflegegrad/schaetzen` erhalten die Zielgruppe überhaupt als Parameter. Fachlich teils gerechtfertigt (das echte NBA-Begutachtungsverfahren nach § 15 SGB XI ist bewusst ursachenunabhängig), aber zwei konkrete Schwachstellen behoben:

- **Altersgebundene Klammerbeispiele neutralisiert**: "Nutzt Hilfsmittel (Stock, Rollator)…" → "…(z. B. Gehhilfe, Rollstuhl)…"; die Kognitionsfrage nannte explizit "(z. B. bei Demenz)" — jetzt allgemeiner "Gibt es Gedächtnisprobleme, Orientierungsschwierigkeiten oder auffälliges Verhalten?", ohne die Diagnose vorwegzunehmen (passt so auch für z. B. eine angeborene Behinderung).
- **Zielgruppe "Bedürftige / soziale Notlage" überspringt die 5 Situationsfragen komplett**: hier geht es typischerweise um Grundsicherung (§ 41 SGB XII), nicht um eine SGB-XI-Pflegegrad-Einschätzung. Der Wizard-Reducer (`patienten/neu/page.tsx`) springt bei dieser Zielgruppe direkt von der Zielgruppen-Auswahl (Schritt 4, Unterfrage 0) zu Schritt 5 — Ergebnis: `state.antworten` bleibt leer, die `schaetzung`-Mutation feuert nie (Bedingung `Object.keys(state.antworten).length > 0`), `pflegegrad` bleibt beim Default `0`. Schritt 5 zeigt dafür einen eigenen erklärenden Hinweis statt eines nie auflösenden "Schätzung wird berechnet…"; Pflegegrad-Buttons/Pflegeperson/Notizen bleiben nutzbar (falls doch ein Pflegegrad vorliegt).
- **Leistungen-Filter (Schritt 6) brauchte dafür keine Backend-Änderung**: `pflegegrad` bleibt automatisch bei `0`, und `GET /api/katalog`s bestehender Filter (`pflegegrad_min <= pflegegrad <= pflegegrad_max`) schließt dadurch bereits alle Leistungen aus, die einen echten Pflegegrad voraussetzen (z. B. Pflegegeld `pflegegrad_min=2`) — nur Einträge mit `pflegegrad_min=0` (der Großteil der Katalog-Einträge, 75 von 98) plus passender Zielgruppe bleiben übrig. Verifiziert durch Durchsicht der tatsächlichen `pflegegrad_min`-Werte im Katalog, keine Vermutung.

## Einheitliche Button-Stile statt unterstrichener Text-Links (pflegepilot_v3 only, 2026-07-30)

Betreiber-Feedback: Aktions-Auslöser ("+"-Funktionen, Bearbeiten, Löschen, PDF) sahen "noch nach Entwicklung aus" — durchgehendes Muster im gesamten Frontend war `className="text-{farbe}-600 underline"` auf reinem Text statt echter Button-Chrome (Hintergrund/Rand), zusätzlich auf Mobilgeräten schwer treffsicher.

- **Neue geteilte Stile in `lib/theme.ts`: `buttonStyles`** — acht benannte Varianten (`secondary`, `primary`, `danger`, `success`, `small`, `smallDanger`, `smallSuccess`, `smallPrimary`, `add`), alle mit `py-1.5`+ für ausreichend große Tippflächen. `add` ist eine Pill-Form speziell für "+"-Aktionen (z. B. "+ Widerspruch", "+ Neuer Patient", "+ eigene Leistung erfassen").
- **Betroffene Stellen**: Patientenakte (Bearbeiten/Löschen im Header, Leistungen Aktivieren/Deaktivieren/Löschen, Anträge-PDF-Link, + Widerspruch/Musterbrief/Ummeldung/Vollmacht, Tagebuch-/Dokumente-Löschen), `BudgetTracker.tsx` (Budget-Toggle, Ausgabe-Löschen, + Erfassen), Dashboard (PDF-Link in der Anträge-Vorschau, + Neuer Patient), Admin-Dashboard (Sperren/Entsperren/Löschen/Freischalten/Rechnung, Backup Herunterladen/Löschen), Changelog-Admin (Bearbeiten/Löschen, + Neuer Eintrag), Aufgaben (Erledigt), Interview-Wizard Schritt 6 (Fragen überspringen/zurück/erneut beantworten), `NaechsteSchritte.tsx` (Antrag-stellen-/Unterlagen-hochladen-CTAs).
- **Bewusst unverändert gelassen**: reine Navigations-/Inhalts-Links ohne CRUD-Charakter — Login-Bildschirm-Umschalter ("Passwort vergessen?", "Jetzt registrieren"), `tel:`/`mailto:`/Webseite-Kontaktzeilen in der Umkreissuche, Dokument-/Dateiname als Link zum Öffnen, Dashboard "Alle ansehen", sowie "Abbrechen" in den Kamera-Scan-Flows (`EgkScan`/`DokumentScan`) — dort ist ein dezenter Text-Link die etablierte, passende Konvention für eine sekundäre Abbrechen-Aktion neben einem primären Button, kein "sieht nach Entwicklung aus"-Symptom.
- `AntragCheckliste.tsx`s "Hochladen"-Beschriftung blieb unverändert, da sie bereits Teil einer voll button-gestylten Zeile ist (ganze `<li>` ist ein farbig hinterlegter Button), nicht isolierter Text.

## Interview-Wizard Schritt 6: geführter Frage-Dialog statt reiner Checkbox-Liste (pflegepilot_v3 only, 2026-07-30)

Tester-Feedback: die Leistungsauswahl in Schritt 6 wirkte für Laien "erschlagend" — unklar, ob eine Leistung überhaupt gebraucht wird oder wie viele man ankreuzen darf. Zwei Lösungsansätze wurden dem Betreiber vorgelegt (A: nur die bestehende Liste optisch/inhaltlich aufwerten; B: ein geführter Ja/Nein-Fragenteil davor, der Einträge automatisch vorwählt) — **Option B wurde explizit gewählt**, trotz höherem Aufwand.

- **Bewusst nur auf die 22 Einträge der Kategorie "Pflegekasse (SGB XI)" begrenzt**, nicht auf den gesamten Katalog (98 Einträge, 27 Kategorien) — das sind die häufigsten, direkt am Pflegegrad hängenden Leistungen; die übrigen ~76 Einträge (Krankenkasse, Landesleistungen, Steuerliches, Wohnen & Bauen etc.) sind zu heterogen für einen sinnvollen Ja/Nein-Fragenkatalog und bleiben nur in der bestehenden Liste sichtbar, die unterhalb des Frage-Dialogs unverändert weiter angezeigt und editierbar bleibt (nichts wird "unsichtbar" vorausgewählt).
- **8 Fragen**, gleiches Frage-pro-Bildschirm-Muster wie Schritt 4 (`LEISTUNGS_FRAGEN`-Konstante in `patienten/neu/page.tsx`, direkt vor `StepLeistungen`): Frage 1 ("Wie wird die Person hauptsächlich gepflegt?") ist eine Einfachauswahl mit 4 Optionen (nur Angehörige / nur Pflegedienst / gemischt / Pflegeheim), die restlichen 7 sind Ja/Nein. Jede Option trägt die zugehörigen Katalog-IDs, die bei Auswahl automatisch in `state.ausgewaehlteLeistungen` übernommen werden.
- **Neue Reducer-Aktion `SET_LEISTUNGEN` (`add`/`remove`-Arrays)** statt der bisherigen `TOGGLE_LEISTUNG` für diesen Zweck — nötig, damit beim (erneuten) Beantworten einer Frage zuerst alle IDs der zuvor gewählten Option dieser Frage entfernt werden, bevor die neuen hinzukommen (sonst blieben bei einer Antwortänderung alte Vorauswahlen hängen).
- **Abhängige Leistungen werden direkt mit ausgewählt, ohne eigene Frage**: `pk_leistungszuschlag` (automatischer Zuschlag im Heim) ist Teil der "Pflegeheim"-Option; `pk_beratungsbesuch` (Pflicht-Beratungsbesuch bei Pflegegeld-Bezug, § 37 Abs. 3 SGB XI) ist Teil der "nur Angehörige"- und "gemischt"-Optionen — beide sind laut Katalog `abhaengigkeiten` vom jeweiligen Haupteintrag, brauchen aber keine eigene Nutzerfrage.
- **4 Fragen werden übersprungen, sobald "Pflegeheim" gewählt wurde** (`ueberspringenWennHeim`-Flag: Tages-/Nachtpflege, Verhinderungs-/Kurzzeitpflege, Pflegehilfsmittel, Wohnumfeldverbesserung) — bei vollstationärer Pflege sind diese häuslichen Leistungen typischerweise nicht relevant.
- **"Fragen überspringen"** springt jederzeit direkt zur Liste, **"Fragen erneut beantworten"** (erscheint nach Abschluss) setzt den Dialog zurück auf Frage 1 — bereits gesetzte Häkchen in der Liste bleiben davon unberührt, bis eine Frage tatsächlich erneut beantwortet wird.
- **Bekannte, akzeptierte Einschränkung**: ändert man nach Beantwortung späterer Fragen die Antwort auf Frage 1 rückwirkend auf "Pflegeheim", werden zuvor über die übersprungenen Fragen gesetzte Häkchen nicht automatisch wieder entfernt (die Liste bleibt aber sichtbar/editierbar, der Nutzer kann manuell abwählen) — für den seltenen Rückwärtskorrektur-Fall bewusst nicht mit einem Undo-Kaskaden-Mechanismus überbaut.
- **Nischen-Leistungen ohne eigene Frage** (Wohngruppen-Zuschlag, Pflegeunterstützungsgeld, DiPA, `pk_stationaer_behindert`) bleiben nur über die normale Liste erreichbar, gleiches Prinzip wie bereits bei Reha-Sport in der Umkreissuche (keine erzwungene Frage für seltene Fälle).
- Betrifft alle drei Zielgruppen gleichermaßen; bei "Bedürftige" (Pflegegrad bleibt 0) filtert der bestehende Katalog-Filter die meisten Pflegekasse-Einträge ohnehin heraus (nur `pflegegrad_min=0`-Einträge bleiben sichtbar) — der Frage-Dialog wird trotzdem angezeigt, bleibt für diese Gruppe aber weitgehend wirkungslos, da die meisten Ziel-IDs gar nicht in der gefilterten Liste auftauchen.

## T30: Durchsuchbare Dokumenten-Scans + Volltextsuche (pflegepilot_v3 only, 2026-08-02)

Letzter offener "niedrig"-Punkt aus dem T26–T37-Nachtrag. Original-Feedback war nur eine Rückfrage des Testers ("Dokumenten Scan mittels OCR optimieren? Bedarf vorhanden??") — der Umfang wurde über zwei `AskUserQuestion`-Runden geklärt (was genau "optimieren" heißt, dann wie die "in unsere Generatoren übernehmen"-Anforderung konkret aussehen soll) und ist am Ende deutlich größer als "niedrig": durchsuchbare PDFs, serverseitig persistierter OCR-Text, Volltextsuche im UI, Text-Anzeige-und-Kopieren-Funktion.

- **`app/dokument_scan.py: bilder_zu_durchsuchbarem_pdf()`** ersetzt `bilder_zu_pdf()` im Scan-Upload-Pfad (die alte Funktion bleibt als Fallback bestehen). Nutzt **Tesseracts eigenen PDF-Renderer** (`pytesseract.image_to_pdf_or_hocr(bild, extension="pdf")`) statt eine Textebene manuell über das Bild zu legen — Tesseract liefert Bild+unsichtbare Textebene bereits korrekt positioniert in einer einzigen PDF-Seite. Mehrseitige Scans werden mit **`pypdf`** (neue, bewusst leichtgewichtige Abhängigkeit — reines Seiten-Zusammenfügen, kein Rendering nötig, daher nicht das schwerere PyMuPDF/fitz) zu einem gemeinsamen PDF zusammengefügt. Liefert zusätzlich den erkannten Volltext für `Dokument.ocr_text` zurück.
- **Gleiche Kulanz-Haltung wie die bestehende Kantenerkennung**: jeder OCR-Fehler (korrupte Bilddaten, Tesseract-Ausnahme) fällt auf das alte reine Bild-PDF ohne Textebene zurück, statt den Upload zu blockieren — verifiziert durch einen simulierten Fehlschlag (gemockter `pytesseract`-Aufruf), sauberer Fallback ohne Crash bestätigt.
- **`Dokument.ocr_text`** (Migration `a3d6f9c2e5b8`, `Text`-Spalte, nullable) — nur bei per Kamera gescannten Dokumenten gesetzt, nicht bei regulären Datei-Uploads (bewusst auf den tatsächlich referenzierten "Dokumenten-Scan" beschränkt, nicht auf den generischen Upload-Pfad ausgeweitet).
- **Volltextsuche**: `GET /api/patienten/{pid}/dokumente?suche=...` filtert per einfachem `ILIKE` sowohl auf `bezeichnung` als auch auf `ocr_text` — bewusst kein Postgres-`tsvector` (Dokumentenmenge je Patient bleibt klein, ein Substring-Treffer reicht für "Inhalte leichter finden"). **Im Frontend aber nicht darüber verdrahtet** — die Patientenakte nutzt stattdessen **client-seitige Filterung** der bereits geladenen, ungefilterten Dokumentenliste: `NaechsteSchritte` (T24) braucht die vollständige, ungefilterte Liste für seine "Unterlagen hochgeladen"-Fortschrittsprüfung, ein serverseitig gefilterter State hätte diese Prüfung während einer aktiven Suche verfälscht. Der Backend-Suchparameter bleibt trotzdem als eigenständige, getestete Fähigkeit bestehen (z. B. für künftige größere Dokumentenmengen oder andere Oberflächen).
- **"Text anzeigen"**: neuer Button pro Dokument (nur sichtbar, wenn `ocr_text` gesetzt ist) öffnet ein Modal mit einer `readOnly`-Textarea des erkannten Texts — Klick fokussiert und markiert automatisch den gesamten Text (`onFocus`-Handler), sodass ein einziger Klick + Strg/⌘+C zum Kopieren reicht. Bewusst **kein** automatisiertes Feld-Erkennungs-/Ein-Klick-Übernahme-System (das war die im Klärungsgespräch explizit abgelehnte, aufwendigere Alternative) — der Nutzer markiert/kopiert selbst, was er braucht, funktioniert dafür zuverlässig bei jedem beliebigen Dokumentlayout.
- **End-to-end verifiziert** (synthetisches Testbild mit bekanntem Text, da keine echten Scans verfügbar sind — gleiche Einschränkung wie beim ursprünglichen Dokumenten-Scan und dem eGK-Scan): OCR-Text korrekt erkannt, PDF-Textebene über `pypdf`s `extract_text()` als tatsächlich vorhanden bestätigt (nicht nur angenommen), Fallback-Pfad bei simuliertem OCR-Fehler geprüft, echter Upload über den tatsächlichen HTTP-Endpunkt mit korrekt gespeichertem `ocr_text`, Volltextsuche mit drei Fällen (Treffer über OCR-Inhalt, Treffer über Bezeichnung, kein Treffer) bestätigt. `next build` fehlerfrei, auf der NAS deployed (neues `pypdf` erforderte einen `docker compose build api`, nicht nur Neustart).

## DateInput-Bugfix: führende Null verhinderte Eingabe von Tag/Monat 10–31 (pflegepilot_v3 only, 2026-08-02)

Direkt nach dem T26-Umbau gemeldeter Bug: sobald Monat und Jahr bereits vollständig ausgefüllt waren, machte schon die erste eingetippte Ziffer im Tag-Feld (z. B. "1") ein vollständiges, gültiges Datum — dieses wurde sofort an den Parent gemeldet, dessen aktualisierter `value`-Prop floss zurück in die Komponente, und der dortige Sync-Effekt (für externe Wertänderungen wie eGK-Scans gedacht) füllte die einzelne Ziffer sofort zweistellig auf ("01"), noch bevor die zweite Ziffer getippt werden konnte — dadurch war der 10.–31. Tag/Monat praktisch nicht eintippbar.

- **Fix**: ein `useRef<string | null>` (`letzterEigenerWert`) merkt sich den zuletzt selbst gemeldeten ISO-Wert. Der Sync-Effekt gleicht `value` jetzt gegen diesen Ref ab und überspringt die Neuformatierung, wenn der eingehende Wert exakt die eigene, gerade erst gemeldete Eingabe ist (reines Echo) — nur ein `value`, der tatsächlich von außen kommt (z. B. eGK-Scan-Ergebnis), löst noch eine Neusynchronisation der Anzeige aus.
- Betrifft alle 6 Einbindungsstellen von `DateInput` gleichermaßen, da der Fix zentral in der Komponente sitzt.
- Verifiziert per manueller Zustands-Simulation der React-Update-Reihenfolge (kein Browser in dieser Umgebung verfügbar) — Tippfolge "1" dann "2" im Tag-Feld bei bereits gesetztem Monat/Jahr ergibt jetzt durchgängig "12" statt zwischenzeitlich auf "01" zurückgesetzt zu werden.

## Incident: E-Mail-Absendername noch "Pflegepilot" statt "MeinPflegeFuchs" (pflegepilot_v3 only, 2026-08-02)

Betreiber-Meldung: der Absendername in versendeten E-Mails zeigte noch "Pflegepilot" statt "MeinPflegeFuchs". Ursache war **kein Code-Bug** — `app/config.py`s `smtp_from`-Default war bereits korrekt auf `"MeinPflegeFuchs <no-reply@meinpflegefuchs.de>"` gesetzt (Teil der ursprünglichen Umbenennung, siehe CLAUDE.md-Abschnitt "Naming"). Die tatsächlich wirksame `SMTP_FROM`-Umgebungsvariable in **beiden** `.env`-Dateien (lokal und NAS, `docker-compose.yml` reicht sie durch) trug aber noch den alten Wert `"Pflegepilot <support@db-onlinedienste.de>"` — vermutlich beim ursprünglichen SMTP-Setup (siehe "Passwort-vergessen per SMTP") vor der Umbenennung eingetragen und beim Rename-Durchlauf übersehen, da `.env`-Werte nicht Teil der Code-/Grep-Suche über den Projektbaum waren.

- **Fix**: nur der Anzeigename in `SMTP_FROM` geändert (`Pflegepilot` → `MeinPflegeFuchs`), die tatsächliche Absenderadresse `support@db-onlinedienste.de` (echte, aktiv genutzte Mailbox) unverändert gelassen — kein Code-Deploy nötig, nur `docker compose up -d --force-recreate api` in beiden Umgebungen (ein reiner `restart` hätte die geänderte `.env` nicht neu eingelesen, da Docker Compose Umgebungsvariablen nur beim Container-Erstellen neu auswertet).
- **Verifiziert**: `settings.smtp_from` nach Neustart korrekt in beiden Umgebungen geprüft, zusätzlich eine echte Testmail über die Admin-Test-Mail-Funktion (`POST /api/admin/email-test`) verschickt und im `email_log` als `gesendet` bestätigt.
- **Lehre für künftige Rename-/Branding-Durchläufe**: `.env`-Dateien (lokal wie NAS) sind bei einem Namens-/Branding-Wechsel explizit mitzuprüfen, nicht nur der Code — sie sind gitignored und tauchen deshalb in keiner Grep-Suche über den versionierten Projektbaum auf.

## T26-Korrektur: Datumsfelder als Zahlenfelder statt Kalender-Dialog (pflegepilot_v3 only, 2026-08-02)

**Fehleinschätzung aus der vorherigen Runde korrigiert.** T26 war ursprünglich als "bereits gelöst" markiert worden, weil ein bestehender `DateWheelPicker` (drei Scroll-Wheel-Spalten in einem Popup-Dialog) angezeigt in `TT.MM.JJJJ`-Format vorhanden war — die Annahme war, dass ein Wheel-Picker das Anliegen "kein Standard-Tastatur-Popup, klares Datumsformat" bereits erfüllt. **Betreiber-Korrektur:** genau der Wheel-Picker-Dialog selbst war nicht gewünscht — stattdessen ein echtes Zahlen-Eingabefeld TT.MM.JJJJ ohne jeden Kalender-/Dialog-Umweg, mit Validierung auf kalendarisch mögliche Werte (Beispiel des Betreibers: 31.02.2000 muss abgelehnt werden).

- **`components/DateInput.tsx`** ersetzt `DateWheelPicker.tsx` komplett (Datei gelöscht, nicht nur deaktiviert) — drei nebeneinanderliegende `<input inputMode="numeric">`-Felder (Tag/Monat/Jahr) mit Punkt-Trennzeichen dazwischen, automatischer Fokus-Sprung zum nächsten Feld bei vollen 2 (bzw. 4) Ziffern, roter Rand + Fehlertext "Ungültiges Datum" sobald alle drei Felder gefüllt aber die Kombination kalendarisch unmöglich ist. Validierung über `new Date(jahr, monat, 0).getDate()` (liefert die tatsächliche Tageszahl des Monats inkl. korrekter Schaltjahr-Berechnung durch die native JS-Date-Arithmetik) statt einer hartkodierten Tage-pro-Monat-Tabelle — automatisch korrekt für Schaltjahre, ohne das explizit nachzubilden.
- **API-Erweiterung, keine neuen Anpassungen bei den Aufrufern nötig**: `onChange` liefert jetzt `string | null` statt nur `string` (vorher lieferte der Wheel-Picker erst beim expliziten "Übernehmen"-Klick einen vollständigen Wert; ein Freitextfeld hat dagegen während des Tippens zwangsläufig unvollständige/ungültige Zwischenzustände, die als `null` durchgereicht werden) — alle 6 bestehenden Aufrufer hatten ihren Datums-State bereits als `string | null` typisiert, keine Änderung an den Callern nötig außer Komponentenname/Import. `value`-Prop-Änderungen von außen (z. B. eGK-Scan/OCR füllt das Feld programmatisch) werden weiterhin per `useEffect` übernommen, aber nur bei einem tatsächlich gesetzten Wert — ein `null` von außen löscht keine laufende, noch unvollständige Nutzereingabe.
- **6 Einbindungsstellen aktualisiert**: Geburtsdatum ("Neuer Patient", "Bearbeiten"), Bescheiddatum (Widerspruch-Generator, Status-bearbeiten-Formular in der Patientenakte), Gültig-ab-Datum (Ummeldungs-Generator), Fällig-am (Aufgabe-anlegen-Modal). Redundante externe `<label>`-Wrapper an drei Stellen entfernt, da `DateInput` sein `label`-Prop jetzt selbst sichtbar über den Feldern rendert (vorher wurde `label` nur als Popup-Dialogtitel verwendet — an mehreren Stellen gab es dadurch vorher gar keine sichtbare Beschriftung im Hauptformular, nur im geöffneten Dialog).
- **Validierungslogik isoliert unit-getestet** (Node-Skript außerhalb des Frameworks, da kein Test-Runner im Projekt eingerichtet ist): alle Kernfälle bestätigt, inkl. des vom Betreiber genannten Beispiels 31.02.2000 (ungültig), 29.02.2000 (gültig, Schaltjahr), 29.02.2001 (ungültig, kein Schaltjahr), Tage-pro-Monat-Grenzen (30. April gültig, 31. April ungültig).
- `next build` fehlerfrei (die von der strengen `react-hooks/set-state-in-effect`-Regel gemeldeten Fehler für den externen-Wert-Sync-Effekt sind dieselbe bereits im Projekt an mehreren Stellen tolerierte Klasse von Lint-Meldung, die den Produktions-Build nachweislich nicht blockiert — kein Blocker, aber nicht eigens umgangen).

## Tester-Feedback-Nachtrag T27/T28/T29/T33 (pflegepilot_v3 only, 2026-08-02)

Vier weitere Punkte aus dem T26–T37-Nachtrag in `Feedbackfromtester.md`. Vor der Umsetzung drei genuine Design-Entscheidungen per `AskUserQuestion` geklärt: neuer Rubrik-Name (T27), Eigenentwurf vs. Themenvorgabe für den neuen Guide (T28), UX-Lösungsansatz für Auto-Advance (T33).

- **T27 (Rubrik-Umbenennung + Formulierungsfixes):** "Krisen-Checkliste" → **"Wegweiser für schwierige Momente"** (Betreiber-Wahl aus drei vorgeschlagenen Optionen), geändert in `(app)/layout.tsx` (Sidebar-Label), `guides/page.tsx` (H1) und `(marketing)/page.tsx` (Feature-Kachel auf der Landingpage, für Konsistenz mit angepasst, obwohl nicht explizit gefordert). Zwei Formulierungsfixes in `static_data/krisenguides.py`: der Hospitalisierung-Guide heißt jetzt "Plötzlich ins Krankenhaus" statt des Fachbegriffs; die unsinnige "Haustiere, Pflanzen ... pausieren"-Zeile wurde aufgeteilt in eine Versorgungs-Organisation für Tiere/Pflanzen (die man nicht einfach "pausieren" kann) und separat absagbare Termine.
- **T28 (neuer Guide "Umzug ins Pflegeheim"):** Betreiber wählte "selbst entwerfen lassen" statt Themenvorgabe. Fünfter Eintrag in `KRISENGUIDES` (`id="umzug_pflegeheim"`), 8 Schritte nach demselben Muster wie die bestehenden vier: Heimvergleich, § 43 SGB XI-Antrag (mit Verweis auf den bestehenden Musterbrief-Generator), Kostenübernahme/Eigenanteil, Adressänderung (Verweis auf den bestehenden Ummeldungs-Generator — bewusste Cross-Promotion eigener Features statt allgemeiner Ratschläge), Vertragskündigungen, Umzugslogistik, Nachsendeauftrag, emotionale Seite. `guides/page.tsx`s `AKZENTE`-Array um eine fünfte Farbe (`amber`) erweitert.
- **T29 (doppelte Anträge/Briefe — Root-Cause + Löschen):** Root-Cause-Prüfung zuerst: alle 5 Brief-Generatoren (Widerspruch/Musterbrief/Ummeldung/Vollmacht/Patientenverfügung) hatten bereits `disabled={mutation.isPending}` auf dem Submit-Button — ein reiner Doppelklick-Bug ist damit ausgeschlossen. Plausiblere Ursache: eine verlorene Serverantwort während der (spürbar langsamen) WeasyPrint-PDF-Erzeugung — die Anfrage wird serverseitig trotzdem fertig verarbeitet, der Client bekommt aber keine Bestätigung und der Nutzer klickt erneut. Gefixt mit `_juengster_duplikat()` (`routers/briefe.py`): vor jeder PDF-Erzeugung wird geprüft, ob für denselben Patienten/Typ bereits ein **inhaltsgleicher** (`brief_text`-identischer) Antrag innerhalb der letzten 20 Sekunden existiert — falls ja, wird dieser zurückgegeben statt PDF+DB-Zeile ein zweites Mal zu erzeugen (spart auch die teure PDF-Neu-Generierung). Bewusst kein Idempotenz-Key über alle 5 Formulare hinweg (unverhältnismäßiger Umbau für dieses Symptom) — der Zeitfenster-Abgleich reicht, da die Formulare ohnehin serverseitig deterministischen Text erzeugen. End-to-end verifiziert: zwei identische Aufrufe hintereinander liefern dieselbe Antrag-ID zurück (nur 1 DB-Zeile), ein Aufruf mit anderem `typ` erzeugt korrekt eine neue Zeile (kein Über-Deduplizieren). Zusätzlich fehlte komplett ein Lösch-Endpunkt für `Antrag`-Datensätze — `DELETE /api/antraege/{aid}` (`routers/antraege.py`, gleiche `require_paid_access`-Eigentumsprüfung wie das bestehende `PUT`) neu ergänzt, löscht auch die zugehörige PDF-Datei von der Platte. Frontend: "Löschen"-Button (kein Bestätigungsdialog, gleiches Muster wie die bereits bestehenden Leistungen-/Tagebuch-/Dokumente-Lösch-Buttons) in der Anträge-Liste der Patientenakte.
- **T33 (Interview Schritt 6: Bestätigung vor Auto-Weiterleitung):** Betreiber wählte "Bestätigen-Button statt Auto-Advance" (gleiches Prinzip wie bereits die letzte Unterfrage in Schritt 4). `waehleOption()` in `patienten/neu/page.tsx` markiert eine Antwort jetzt nur noch (visuell hervorgehoben, `border-indigo-500 bg-indigo-100`), ein neuer, bis zur Auswahl disabled "Weiter"-Button (`weiter()`) löst den Sprung zur nächsten Frage aus. Nebeneffekt (kein zusätzlicher Code nötig): beim Zurückgehen zu einer bereits beantworteten Frage wird die vorherige Auswahl jetzt automatisch korrekt hervorgehoben, da dieselbe `gewaehlt`-State-Map fürs Highlighting wiederverwendet wird. Bewusst **nur** Schritt 6 geändert, nicht die analoge Schritt-4-Logik (Pflegegrad-Situationsfragen) — der Tester-Feedback-Text bezog sich explizit auf "Step 6 Fragenkatalog".

Alle vier Punkte end-to-end gegen die echte lokale Docker-Postgres-Instanz verifiziert (Guides-Endpunkt liefert 5 Einträge mit korrektem Wortlaut, Duplikat-Schutz und Löschen wie oben beschrieben getestet, danach alle Testdaten entfernt), `next build` fehlerfrei, auf der NAS deployed.

## Tester-Feedback-Nachtrag T26/T31/T32 (pflegepilot_v3 only, 2026-08-01)

Drei Punkte aus dem am 2026-08-01 in `Feedbackfromtester.md` ergänzten Nachtrag (T26–T37, siehe dortige Gruppen K–O), auf Betreiber-Wunsch als erste drei bearbeitet:

- **T26 (Geburtsdatum-Eingabeformat) — kein Code geändert, bereits gelöst:** Der Tester-Wunsch "DD.MM.JJJJ-Schreibweise, auf Mobilgeräten Nummernblock statt regulärer Tastatur" ist für alle drei Geburtsdatum-Stellen (`patienten/neu/page.tsx`, `patienten/[id]/bearbeiten/page.tsx`) bereits durch die bestehende `components/DateWheelPicker.tsx` erfüllt — geprüft, nicht angenommen: die Komponente zeigt das gewählte Datum über `toLocaleDateString("de-DE", {day:"2-digit", month:"2-digit", year:"numeric"})` exakt im gewünschten `TT.MM.JJJJ`-Format an, und öffnet beim Bearbeiten drei Scroll-Wheel-Spalten statt eines Texteingabefelds — es gibt dort also gar keine Tastatur (weder alphanumerisch noch Nummernblock), die geöffnet werden könnte. Die übrigen, nicht in Wheel-Picker umgewandelten Datumsfelder der App (Antragsdatum-Bearbeiten, Budget-Tracker-Ausgabedatum, Changelog-Admin) sind bewusst reguläre `<input type="date">` für nahe/kurzfristige Daten — native `<input type="date">` öffnet auf Mobilgeräten ohnehin bereits einen systemeigenen Datums-Picker, keinen freien Text-/Zeichen-Tastaturblock, erfüllt das Anliegen also strukturell ebenfalls schon. **Bleibt trotzdem in der Backlog-Datei mit "ggf. bereits gelöst" vermerkt**, bis das beim nächsten Tester-Kontakt aktiv bestätigt wird — die Rückmeldung könnte sich zeitlich vor dem Wheel-Picker-Rollout ereignet haben.
- **T31 (offizieller MDK-Text auf der Ergebnisseite) — blockiert, braucht echten Text:** Das Original-Feedback ("Seite 4: offizieller Text des MDK noch hinzufügen ... <--- Rsp Marcel") verweist auf einen noch ausstehenden Wortlaut von einer dritten Person ("Marcel"), der bislang nirgends im Repository vorliegt (geprüft: kein vorhandener MDK-Volltext in `pflegepilot_v3` oder `pflegepilot_alpha_v2`, nur der bereits bestehende Kurz-Disclaimer "Das ist keine offizielle Feststellung – nur der Medizinische Dienst kann per Begutachtung einen verbindlichen Pflegegrad bescheinigen" in `patienten/neu/page.tsx`). Bewusst **kein** Text erfunden/angenommen — ein als "offizieller MDK-Text" ausgegebener, tatsächlich von Claude erfundener Text wäre ein greifbares Falschdarstellungsrisiko in einer App, die genau in diesem Punkt (Pflegegrad-Einschätzung) ohnehin schon Vertrauens-/Genauigkeitsfragen hat (siehe T34). Noch offen, braucht den echten Wortlaut vom Betreiber.
- **T32 (Musterbrief: "Pflege wird durchgeführt von") — umgesetzt, kein neues Formularfeld:** `Patient.pflegeperson` existierte bereits als freies Textfeld (erfasst in Schritt 5 "Einschätzung & Pflegeperson" des "Neuer Patient"-Assistenten, editierbar im Bearbeiten-Formular) — die Frontend-Musterbrief-Seite (`musterbrief/page.tsx`) hatte dafür aber gar kein eigenes Feld, und `build_musterbrief_text()`/`MusterbriefRequest` gaben den Wert bislang nirgends aus. Statt eines neuen Frontend-Felds/Request-Parameters liest `musterbrief_erstellen()` (`routers/briefe.py`) den Wert direkt vom ohnehin schon geladenen `patient`-Objekt (`patient.pflegeperson`) und übergibt ihn an `build_musterbrief_text(..., pflege_durch=...)` — eine neue, optionale Zeile "Pflege durch: ..." erscheint im generierten Erstantrag-Text nur, wenn das Feld tatsächlich gesetzt ist (keine leere Zeile bei fehlendem Wert). Gilt für alle Musterbrief-Typen (nicht nur Erstantrag), da `pflegeperson` unabhängig vom Antragstyp dieselbe Information ist. End-to-end gegen einen echten Testpatienten mit gesetztem `pflegeperson`-Feld verifiziert (Zeile erscheint korrekt formatiert/ausgerichtet; ohne Wert bleibt sie korrekt weg), Testdaten danach entfernt.

## Echtes Logo + Favicon eingebunden (pflegepilot_v3 only, 2026-08-01)

Betreiber hat ein Fuchs-Logo (`logo.png`, Linien-Grafik, dunkles Slate-Blau auf transparentem Grund, 599×503) und ein mehrauflösiges Favicon (`Fav.ico`, 9 Größen 16px–256px) bereitgestellt — bis dahin lief die gesamte App (Web + E-Mails) ausschließlich mit einer Text-Wortmarke "MeinPflegeFuchs" (siehe `email_templates.py`s ursprüngliche Begründung "kein Bild-Logo vorhanden").

- **Zwei Logo-Varianten**: `frontend/public/logo.png` (Original, dunkles Blau — für alle **hellen** Hintergründe: Web-Header, Login-Box) und `frontend/public/logo-white.png` (per PIL generiert, alle nicht-transparenten Pixel auf Weiß gesetzt, Alpha-Kanal unverändert — für **dunkle** Hintergründe, aktuell nur der E-Mail-Header). Ohne die weiße Variante wäre das dunkle Liniengrafik-Logo auf dem dunklen `#1e293b`-Mail-Header (praktisch) unsichtbar gewesen — vor dem Einbau via PIL-Komposit auf `#1e293b` geprüft.
- **Favicon**: `Fav.ico` ersetzt direkt `frontend/src/app/favicon.ico` — Next.js' Datei-Konvention übernimmt das automatisch, keine Code-Änderung nötig.
- **Web-Einbindung** (jeweils `<img src="/logo.png">`, bewusst kein `next/image` — im gesamten Frontend bislang nirgends verwendet, hätte fürs erste Mal extra Optimierer-/Sharp-Abhängigkeit in den `standalone`-Produktions-Build gebracht, für ein paar kleine statische Logo-Einblendungen unverhältnismäßig): App-Sidebar-Header (Desktop `<aside>` + Mobile-Topbar) in `(app)/layout.tsx`, Marketing-Header in `(marketing)/layout.tsx`, Login/Registrierungs-Box in `AuthOverlay.tsx`.
- **SEO/Social-Preview**: `(marketing)/page.tsx`s `generateMetadata()` bekam `openGraph.images`/`twitter.images` auf `/logo.png`, das JSON-LD-`SoftwareApplication`-Objekt ein `image`-Feld — vorher hatte keiner dieser drei Orte ein Bild hinterlegt.
- **E-Mail-Header** (`app/email_templates.py: render_email()`): der dunkle Header-Balken zeigt jetzt `<img src="{LOGO_URL}">` (weiße Variante) neben dem Text "MeinPflegeFuchs" statt nur reinem Text. `LOGO_URL` ist `f"{settings.web_origins[0]}/logo-white.png"`, Modul-Konstante (erfordert neu `from app.config import settings` in `email_templates.py`) — als ganz normal per HTTPS gehostete Bild-URL eingebunden, **nicht** als Base64-Data-URI: viele Clients (u. a. Gmail) blockieren/entfernen eingebettete Base64-Bilder als Spam-Heuristik, eine echte Bild-URL ist der branchenübliche, zuverlässigere Weg. `alt="MeinPflegeFuchs"` liefert bei blockierten Bildern denselben Text-Fallback, den vorher die reine Text-Wortmarke bot — der Text-Schriftzug bleibt zusätzlich neben dem Bild stehen, keine reine Bild-Lösung.
- **Visuelle Abnahme über Artifact-Vorschau** (kein Browser in dieser Umgebung verfügbar, gleiches Vorgehen wie beim E-Mail-HTML-Redesign): eine gerenderte Testmail (Katalog-Änderung) wurde mit dem Logo als Base64-Data-URI (nur für die Vorschau, nicht im echten Versand — der echte Versand nutzt die gehostete URL) als Artifact veröffentlicht.

## Test-Mail-Funktion im Admin-Dashboard (pflegepilot_v3 only, 2026-08-01)

Betreiber-Wunsch nach der E-Mail-Bündelung/-Redesign-Runde: "gib mir eine mail-test funktion im admin bereich um test mails zu versenden" — die 7 proaktiven Mailtypen (siehe "Proaktiver Server-Mailversand erweitert") ließen sich bis dahin nur pruefen, indem die jeweilige echte Versandbedingung im System nachgestellt wurde (faellige Aufgabe anlegen, Katalog-Snapshot zuruecksetzen, Widerspruchsfrist in die Vergangenheit legen, …) — unpraktisch fuer eine schnelle Design-/Text-Kontrolle.

- **`app/email_test.py`** ist eine neue, bewusst separate Registry mit einem Builder pro Mailtyp (`_tagebuch_reminder()`, `_aufgabe_faellig()`, …, `TEST_MAIL_TYPEN: dict[str, tuple[label, builder]]`, `baue_test_mail(typ)`). Jeder Builder ruft **dieselben** `email_templates`-Bausteine und **dieselbe** Formulierung wie die echte Versandstelle auf (`reminder_scheduler.py`, `katalog_watch.py`, `umkreis_favoriten_watch.py`, `routers/auth.py`), aber mit fest hinterlegten Platzhalterdaten ("Max" als Vorname, "Grete Musterfrau" als Beispiel-Patientin — Namenskonvention wie beim Demo-Account) statt echter DB-Objekte, da fuer eine Testmail keine reale Aufgabe/kein realer Antrag/Favorit existieren muss. Magic-Links (Antragsstatus, Widerspruch-Eskalation) bekommen ein Fake-Token `testvorschau` statt eines echten `antrag_token`-Eintrags — funktional inaktiv, aber strukturell identisch zur echten Mail. **Bewusste Kehrseite**: da die Builder die echte Formulierung duplizieren statt sie direkt wiederzuverwenden, muss ein Wortlaut-Update an einer echten Versandstelle manuell hier nachgezogen werden, sonst laeuft die Testmail-Vorschau inhaltlich auseinander — ein groesserer Refactor (z. B. echte DB-Objekte + Builder aus optionalen Parametern speisen) waere fuer eine reine Admin-Testfunktion unverhaeltnismaessig gewesen.
- **`GET /api/admin/email-test/typen`** liefert die Registry fuers Frontend-Dropdown, **`POST /api/admin/email-test`** (`{empfaenger, typ}`) validiert die Adresse (gleiches Regex-Muster wie die Registrierung), verschickt ueber das normale `send_email()` und protokolliert mit **`typ="test_<original_typ>"`** im `email_log` — bewusst ein eigener Typ-Praefix, damit Testversendungen die echten Volumen-/Erfolgsquote-Statistiken der "E-Mail-Versand"-Karte nicht verfaelschen. Betreff bekommt zusaetzlich ein **"[Testmail]"-Praefix**, damit im Posteingang sofort klar ist, dass es kein echter Versand war.
- **Kein `begruendung`-Pflichtfeld / kein Admin-Audit-Log-Eintrag** fuer diese Aktion — anders als Sperren/Loeschen/DSGVO-Export/Backup-Erstellen (die "vollstaendiger Datenexport/-eingriff"-Kategorie in diesem Codebase) ist das Verschicken einer harmlosen Test-Mail an eine selbst gewaehlte Adresse kein Vorgang, der eine Begruendung braucht — der bereits bestehende `email_log`-Eintrag (jetzt mit `test_`-Praefix erkennbar) reicht als Nachvollziehbarkeits-Spur.
- Frontend: `lib/admin.ts: useEmailTestTypen()`/`useEmailTestSenden()`, neue Collapsible-Karte "Test-Mail versenden" in `admin/page.tsx` direkt unter der bestehenden "E-Mail-Versand"-Karte (Akzentfarbe `cyan`, bis dahin ungenutzt) — Dropdown fuer den Mailtyp, Empfaenger-Feld (vorbelegt mit der eigenen Admin-E-Mail aus `useAuth()`, frei ueberschreibbar), Senden-Button mit Erfolgs-/Fehlermeldung.
- **End-to-end gegen die echte lokale SMTP-Konfiguration verifiziert** (nicht nur synthetisch): alle 7 Builder fehlerfrei durchlaufen lassen, dann ein echter Versand ueber die HTTP-API an eine echte Adresse ausgeloest — `email_log`-Status `gesendet`, Betreff korrekt mit "[Testmail]"-Praefix. Zusaetzlich negative Faelle geprueft (ungueltige E-Mail-Adresse → 400, unbekannter Typ → 400, kein `email_log`-Eintrag bei beiden). Test-Admin-Account und Test-`email_log`-Zeile danach wieder entfernt.

## "Nächste Schritte" auf der Patientenakte (pflegepilot_v3 only, 2026-07-30, T24)

Tester-Feedback: nach der Pflegegrad-Schätzung im Wizard und nach "Patient speichern" fehlte ein konkreter Leitfaden — "ich als Kunde habe von der Thematik kein Verständnis". Nach Klärungsgespräch (Betreiber wollte die anspruchsvollste der drei skizzierten Optionen): eine **dynamische Fortschritts-Checkliste**, keine statische Hinweisbox.

- **Neue Komponente `components/NaechsteSchritte.tsx`**, oben auf der Patientenakte. Drei Schritte: "Antrag gestellt" → "Unterlagen hochgeladen" → "Bescheid erhalten". **Bewusst kein neuer Datenbank-Zustand** — der Fortschritt wird ausschließlich aus den bereits geladenen `Antrag`-/`Dokument`-Daten des Patienten abgeleitet (kein manuelles Abhaken, keine Fehlerquelle durch veraltete Haken). Verschwindet automatisch, sobald alle drei Schritte erreicht sind.
- **Schritt 1 ist nach Zielgruppe personalisiert** (Alterspflege → Erstantrag Pflegegrad, Bedürftige → Grundsicherung, Behinderte → Eingliederungshilfe) und verlinkt direkt zum passenden Musterbrief-Antragstyp. Dafür bekam `/musterbrief` erstmals Query-Parameter-Vorbelegung (`?patientId=&typ=`) — vorher war der Patient/Typ dort nur manuell über die Dropdowns wählbar. Da `/musterbrief` als statische Seite gebaut wird (`next build` markiert sie `○`), musste die Seite dafür in eine `Suspense`-Grenze gewrappt werden (`useSearchParams()` ohne Suspense bricht sonst den Produktions-Build) — gleiches Muster wie bereits bei `patienten/[id]/page.tsx`.
- **Nachbesserung nach direktem Nutzer-Feedback** ("Farbtöne sehr ähnlich, schwer zu erkennen"): ursprüngliche Fassung nutzte durchgehend denselben Sky-Blauton (Hintergrund/Rand/Überschrift/Links) UND ⬜/✅-Emoji als Status-Symbole — Letztere haben auf hellem Hintergrund kaum Eigenkontrast, Ersteres kollidierte zudem farblich mit dem "Leistungen"-Bereich weiter unten auf derselben Seite (nutzt ebenfalls Sky-Akzent). Ersetzt durch echte Tabler-Icons (`IconCircleCheck` grün für erledigt, `IconCircleDashed` indigo für offen) und einen weißen Karten-Hintergrund mit Indigo-Rand statt eines flächigen Blau-Hintergrunds; erledigte Schritte zusätzlich durchgestrichen/grau, offene Schritte fett+farbig — deutlich klarerer Kontrast zwischen "erledigt" und "als Nächstes zu tun".
- **Zweite Nachbesserung** ("Unterlagen hochladen, welche denn? Was muss ich tun?"): die bereits bestehende `AntragCheckliste`-Komponente (T1, zeigt je Antragstyp die üblicherweise benötigten Unterlagen mit Direkt-Upload) wird jetzt **inline in Schritt 2 eingebettet**, für den tatsächlich gestellten Antragstyp des Patienten — statt eines generischen "Unterlagen hochladen"-Links. "Unterlagen hochgeladen" gilt jetzt erst als erledigt, wenn alle für diesen Antragstyp laut Checkliste benötigten Dokumenttypen tatsächlich vorhanden sind (nicht mehr nur "irgendein Dokument existiert").
- **Dabei ein echter, vorbestehender Bug gefunden und behoben**: `musterbrief_erstellen()` (`routers/briefe.py`) speicherte den `Antrag.typ` für die drei im Musterbrief-Generator schon länger wählbaren Subtypen "Eingliederungshilfe"/"Grundsicherung"/"Blindenhilfe" **immer stillschweigend als `"erstantrag"`** — der `ck_antrag_typ`-CheckConstraint erlaubte diese drei Werte schlicht nicht, der Router hat das lautlos auf `"erstantrag"` zurückgefallen lassen, statt einen Fehler zu werfen. Der PDF-Inhalt selbst war korrekt (nutzt `payload.typ` direkt), nur der gespeicherte `Antrag`-Datensatz trug den falschen Typ — sichtbar u. a. im Dashboard unter "Offene Anträge" (falsches Label) und jetzt für T24 relevant geworden, da die "Nächste Schritte"-Checkliste sonst für zwei von drei Zielgruppen die falsche Unterlagen-Liste gezeigt hätte. Migration `d7f1a3c5e8b2` erweitert den CheckConstraint um alle drei Werte, der Router speichert jetzt `payload.typ` direkt, `ANTRAG_TYP_LABEL` im Dashboard um die drei fehlenden Labels ergänzt.

## Dashboard: Patienten-Kacheln + klickbare offene Anträge (pflegepilot_v3 only, 2026-07-29)

Betreiber-Feedback: das Dashboard soll als Einstiegspunkt mehr Information bieten. Zwei Änderungen an `GET /api/dashboard` (`app/routers/dashboard.py`) und `(app)/dashboard/page.tsx`:

- **"Zuletzt bearbeitete Patienten" (reine Namensliste) ersetzt durch "Patienten im Überblick"**: kleine anklickbare Kachel pro Patient (Name, Pflegegrad-Badge, Status, plus Badges "X Anträge offen"/"Y Aufgaben offen" — nur wenn >0, sonst kein Badge). Datenquelle: `DashboardOut.patienten_uebersicht` statt `letzte_patienten` (Feld entfernt, keine anderen Verwender im Frontend).
- **"Offene Anträge"-Kachel ist jetzt klickbar** (Tester-/Betreiber-Feedback: die reine Zahl war nicht klickbar) und springt per Anchor-Link (`#offene-antraege`) zu einer neuen Sektion "Offene Anträge nach Patient" darunter — je Patient eine Zeile mit dem am längsten wartenden offenen Antrag als Vorschau plus Gesamtzahl ("+N weitere"), anklickbar zur Patientenakte.
- **Bewusst gedeckelt** (`MAX_PATIENTEN_KACHELN=6`, `MAX_OFFENE_ANTRAEGE_GRUPPEN=5` in `dashboard.py`), damit das Dashboard nicht überladen wirkt — explizite Vorgabe aus dem Feedback ("soll aber nicht zu voll werden"). Wer mehr Patienten/offene Anträge hat, findet den Rest über `/patienten` bzw. die einzelne Patientenakte.
- Aggregation läuft in Python (nicht als SQL-GROUP-BY), da die Datenmengen pro Konto klein sind und so sowohl die Kacheln als auch die Gruppierung aus denselben zwei bereits geladenen Listen (offene Anträge, offene Aufgaben) gespeist werden können, ohne zusätzliche Datenbank-Rundfahrten.
- Kleiner Nebenfund beim Anfassen von `models.py`: die `CheckConstraint`-Zeichenkette für `Antrag.typ` war seit der Patientenverfügung-Migration nicht mehr aktuell (fehlte dort, `vollmacht` war schon nachgezogen). Folgenlos, da diese App Schema ausschließlich über Alembic-Migrationen provisioniert (kein `Base.metadata.create_all()` im Code) — trotzdem korrigiert, damit der Code nicht in die Irre führt.

## Dokumenten-Scan (pflegepilot_v3 only, 2026-07-29)

Betreiber-Feedback: die Zielgruppe ist zu ca. 80% Tablet-/Handy-Nutzer/innen, die oft keinen eigenen Scanner besitzen bzw. keinen PC mehr für Dateiverwaltung nutzen. Neben dem bestehenden Datei-Upload (`hochladen`) gibt es jetzt eine zweite Option im "Dokumente"-Bereich der Patientenakte: **Kamera-Direktaufnahme mit serverseitiger Kantenerkennung/Perspektivkorrektur**, mehrere Seiten zu einem PDF zusammengefasst.

- **Bewusst serverseitig (Python/OpenCV), nicht clientseitig (JavaScript/WASM)** — eine clientseitige Lösung (z. B. OpenCV.js) müsste jedem Handy vor der ersten Nutzung ~8-9 MB WASM zumuten; serverseitig lädt das Handy nur das rohe Foto hoch, die Rechenarbeit läuft auf dem Server. Direkte Konsequenz aus der genannten Zielgruppe.
- `app/dokument_scan.py`: klassisches OpenCV-Rezept (Kontur des Dokuments finden → auf 4 Eckpunkte reduzieren → Perspektive entzerren). **Zwei Stufen der Kulanz**, bevor der Upload jemals blockiert wird: (1) findet sich eine ausreichend große Kontur, die sich aber nicht sauber auf 4 Eckpunkte reduzieren lässt, wird ersatzweise deren umschließendes gedrehtes Rechteck (`cv2.minAreaRect`) verwendet; (2) findet sich überhaupt keine ausreichend große Kontur (schlechtes Licht, unklarer Hintergrund), wird das Originalfoto unverändert weiterverwendet — explizite Betreiber-Entscheidung (Alternative wäre manuelles Nachjustieren der 4 Ecken gewesen, bewusst nicht für den ersten Wurf).
  - **2026-07-29 nachgebessert**, nachdem der Betreiber die Kantenerkennung mit echten Fotos als mangelhaft zurückgemeldet hat: Median-basiertes Auto-Canny statt fixer Schwellenwerte 50/150 (robuster über unterschiedliche Belichtung hinweg), bilateraler statt Gauß'scher Weichzeichner (glättet Papierstruktur, ohne die Kante zu verwischen), `MORPH_CLOSE` schließt kleine Lücken in der erkannten Kante (häufig durch Schatten verursacht), mehrere Epsilon-Werte für `approxPolyDP` statt nur einem festen Wert, Arbeitsauflösung von 500px auf 700px erhöht (zu grob für komplexere Hintergründe). Mit einem realistischeren synthetischen Test (Bildrauschen + schwacher Kontrast, den die alte Version nicht erkannt hätte) verifiziert — die eigentliche Bewährungsprobe sind aber weiterhin echte Handyfotos unter echten Lichtverhältnissen, dafür fehlt weiterhin eine größere Testreihe. Die Erkennungsschwelle (`MIN_KONTUR_ANTEIL = 0.2`) bleibt der erste Regler, an dem bei anhaltenden Problemen gedreht werden sollte.
  - Die Bezeichnung eines Scans lautet jetzt `{Scan-Datum} ({Seitenzahl} Seiten)` (z. B. „29.07.2026 (2 Seiten)“) statt generisch „Scan (2 Seiten)“ — Betreiber-Feedback: bei mehreren Scans desselben Dokumenttyps (z. B. mehrere „Kopie eines Bescheids“) waren die Einträge in der Liste sonst nicht unterscheidbar.
- **Mehrseitig**: mehrere per Kamera aufgenommene Fotos werden zu einem gemeinsamen PDF zusammengefasst (`bilder_zu_pdf()`, Pillow `save_all=True`) — eine Scan-Session kann mehrere Seiten eines Dokuments sein (z. B. ein mehrseitiger Bescheid). Bewusste Betreiber-Entscheidung, da einzelne Seiten für echte Behörden-/Arztdokumente unrealistisch gewesen wären.
- **Kein HEIC-Support** — weder OpenCV noch Pillow können HEIC ohne Zusatzbibliothek dekodieren. Unkritisch für den eigentlichen Kamera-Direktaufnahme-Flow (iOS liefert bei "Foto aufnehmen" über ein Web-`<input capture>` immer JPEG, unabhängig von der Kamera-Einstellung des Geräts) — nur relevant, falls jemand statt der Live-Aufnahme ein bestehendes HEIC-Foto aus der Mediathek wählt; würde dann mit einer klaren 400-Fehlermeldung abgelehnt, nicht stillschweigend falsch verarbeitet.
- Neuer Endpunkt `POST /api/patienten/{pid}/dokumente/scan` (mehrere Dateien unter demselben Formularfeld `dateien`) ergänzt, nicht ersetzt den bestehenden `POST /api/patienten/{pid}/dokumente` (Einzeldatei-Upload beliebigen Formats bleibt für PDFs/Word-Dokumente etc. bestehen) — beide erzeugen dieselbe `Dokument`-Zeile mit `typ`/`bezeichnung`, dieselbe autorisierte Download-Route.
- Frontend: `components/DokumentScan.tsx` — Kamera-Button sammelt Seiten client-seitig (Thumbnail-Vorschau, einzeln entfernbar) und lädt erst beim expliziten "Fertig, hochladen" alle gesammelten Fotos in einer Anfrage hoch, statt bei jedem Foto einzeln einen Request zu senden.
- Neue Abhängigkeit `opencv-python-headless` (keine GUI-Bibliotheken wie libGL nötig, die der Container ohnehin nie nutzt) — braucht ein `docker compose build api` (nicht nur `restart`) beim Deploy, da neue Python-Pakete zur Image-Bauzeit installiert werden.

## System-Backup im Admin-Dashboard (pflegepilot_v3 only, 2026-07-29)

Aus einem Sicherheitsgespräch mit dem Betreiber: Datenbank-Einträge sind für ihn als Admin direkt einsehbar (kein Feld-Verschlüsselungs-Feature) — das ist der Standardfall und für sich genommen kein DSGVO-Problem (Art. 32 DSGVO ist risikobasiert, Zugriff ist bereits auf den Betreiber selbst beschränkt und in der Datenschutzerklärung Ziffer 7 offengelegt). Das eigentlich relevante Risiko-Szenario ist ein Totalverlust des NAS — dagegen hilft nur ein 1:1-Backup außerhalb des Geräts, kein Verschlüsselungsfeature.

- **Ein Backup ist ein `.tar.gz`-Archiv** mit `database.sql` (kompletter `pg_dump`, Klartext-SQL statt Custom-Format für universellere Wiederherstellbarkeit ohne Versions-Zwang bei `pg_restore`) plus `uploads/` (1:1-Kopie des kompletten Upload-Verzeichnisses aller Konten — Scans, Briefe/PDFs, Fotos). Bewusst **kein** Betroffenenrechte-Export wie das bestehende DSGVO-Export-Feature (das ist auf einen Patienten beschränkt) — dies ist ein System-Backup über alle Konten hinweg, ausschließlich für den Betreiber.
- **Eigenes Docker-Volume** (`pflegepilot_v3_backups`, gemountet unter `/app/app/backups`) statt eines Unterordners von `uploads_dir` — bewusste Trennung, damit ein Backup-Archiv nie als "Patientendokument" durchgehen kann.
- **Manueller Button + automatisch täglich**, beides im Admin-Dashboard (Betreiber-Entscheidung nach Rückfrage): `app/backup_scheduler.py` folgt exakt dem Muster von `reminder_scheduler.py` (Postgres-Advisory-Lock über die gesamte Thread-Lebensdauer, eigene Lock-ID `412857930`, stündlicher Check). Es gibt bewusst **keine eigene "letztes Backup war am..."-Spalte** — die Quelle der Wahrheit ist schlicht der Zeitstempel des jüngsten vorhandenen Backup-Dateinamens (`backup.liste_backups()`); ist der nicht von heute, wird eines erstellt.
- **Rollierende Aufbewahrung der letzten 5** (Betreiber-Entscheidung "3-5"), sowohl nach dem automatischen als auch nach dem manuellen Erstellen aufgeräumt (`alte_backups_aufraeumen()`) — verhindert unbegrenzt viele Vollkopien aller Patientendaten auf der Platte.
- **Erstellen und Herunterladen werden im Admin-Audit-Log protokolliert** (gleiche Begründung wie beim DSGVO-Export: ein vollständiger Datenexport über alle Konten ist ein Vorgang, der nachvollziehbar bleiben sollte) — Erstellen braucht wie bei allen anderen Admin-Aktionen eine Begründung (`BegruendungModal`), Herunterladen wird automatisch mit fester Begründung "Download durch Admin" geloggt, ohne den Download durch ein zusätzliches Eingabefeld zu bremsen. Löschen eines Backups wird bewusst **nicht** geloggt (reine Aufräumaktion, kein Datenexport).
- **Dateinamen-Validierung gegen ein festes Muster** (`backup_YYYYMMDD_HHMMSS.tar.gz`) im Download-/Lösch-Endpunkt — Schutz vor Path Traversal über einen vom Client frei wählbaren Dateinamen.
- **Neue Abhängigkeit im Image**: `postgresql-client` (Dockerfile) für die `pg_dump`-Binary — braucht ein `docker compose build api`, nicht nur `restart`, plus `mkdir -p .../backups` im selben `RUN`-Schritt wie `uploads` (sonst würde das neue Docker-Volume beim ersten Mount mit falschem Owner initialisiert, da der `chown -R appuser` davor läuft).
- **pg_dump-17/psql-16-Versionsunterschied — ursprünglich als "harmloser Schönheitsfehler" eingeschätzt, dann durch echten Test als echter Blocker entlarvt**: Das Debian-Repository des `python:3.12-slim`-Basisimages liefert `postgresql-client` in Version 17, der DB-Server läuft auf Version 16 (`postgres:16`-Image). Ein mit pg_dump 17 erzeugter Dump enthält eine `SET transaction_timeout = 0;`-Zeile, die es in Postgres 16 noch nicht gibt. Solange nur der Dump selbst mit einem normalen (nicht-transaktionalen) `psql`-Lauf angeschaut wurde, blieb das folgenlos (Zeile erzeugt nur eine Warnung, der Rest des Dumps spielt sich korrekt ein) — das war die ursprüngliche Einschätzung unten im Restore-Abschnitt. **Das stimmte nur so lange, wie kein `--single-transaction --set ON_ERROR_STOP=1` im Spiel war.** Der eigentliche Restore-Feature (siehe unten) nutzt genau das für Atomarität — und unter dieser Kombination bricht die eine `SET`-Zeile die komplette Transaktion sofort ab, sodass **gar nichts** wiederhergestellt wird, nicht nur eine kosmetische Meldung erscheint. Das wurde erst durch einen echten, vom Betreiber ausdrücklich autorisierten Restore-Testlauf auf der NAS-Testinstanz entdeckt (nicht durch Code-Review vorhersehbar) — siehe `_dump_kompatibel_machen()` im Restore-Abschnitt für den tatsächlichen Fix. **Lehre für diese Codebasis**: ein als "kosmetisch" abgetaner Versionsunterschied kann durch eine spätere, unabhängige Änderung (hier: `--single-transaction` für ein ganz anderes Feature) nachträglich zu einem echten Blocker werden — bei jeder neuen Verwendung von `pg_dump`/`psql`-Ausgaben erneut prüfen, ob die bisherige Einschätzung noch zutrifft, statt sie unverändert zu übernehmen.

## Restore aus System-Backup (pflegepilot_v3 only, 2026-07-29)

Ergänzung zum Backup-Feature (siehe oben): "wie kriege ich die ZIP-Backup-Datei nach einem Totalausfall wieder ins System" — per Single-Upload im Admin-Dashboard, das Script übernimmt den Rest. `app/backup.py: restore_backup(archiv_pfad)`, Endpoint `POST /api/admin/backups/restore` (`archiv`: Datei-Upload, `begruendung`: Pflichtfeld wie bei jeder Admin-Aktion).

- **Reihenfolge bewusst so, dass nichts Destruktives passiert, bevor die Datei nicht minimal als gültig bestätigt ist**: 1) Archiv in ein Temp-Verzeichnis entpacken (`tarfile.extractall(..., filter="data")` — Pfad-Traversal-Schutz), `database.sql` muss existieren, sonst Abbruch ohne jede Änderung am laufenden System. 2) **Erst danach** eine Sicherheitskopie des aktuellen Zustands anlegen (Betreiber-Entscheidung: schützt vor einem Restore mit versehentlich falscher/veralteter Datei — der Dateiname der Sicherheitskopie wird in der API-Antwort und im Audit-Log-Eintrag mitgeliefert). 3) Datenbank per `psql --single-transaction --set ON_ERROR_STOP=1` einspielen — entweder komplett oder gar nicht. 4) `alembic upgrade head` erneut ausführen, falls seit dem Backup-Stand neue Migrationen zum aktuell laufenden Code hinzukamen. 5) Uploads-Verzeichnis durch den Inhalt aus dem Archiv ersetzen. 6) `engine.dispose()`, damit nachfolgende Requests garantiert frische DB-Verbindungen aufbauen.
- **Zwei echte Bugs, beide erst durch einen echten Restore-Testlauf auf der NAS-Testinstanz gefunden** (nicht durch Code-Review oder isolierte Unit-Tests vorhersehbar — beide betreffen die Interaktion mit der echten Docker-/Postgres-Umgebung):
  1. **`transaction_timeout`-Blocker** (siehe oben im Backup-Abschnitt für die volle Herleitung): `_INKOMPATIBLE_SET_MUSTER`/`_dump_kompatibel_machen()` in `backup.py` entfernt die `SET transaction_timeout = ...;`-Zeile aus dem extrahierten Dump, bevor er an `psql` geht — gezielter Fix statt der (für einen einzigen Zeilen-Bug unverhältnismäßigen) Alternative, ein zweites PGDG-Apt-Repository für exakte Versions-Parität einzurichten.
  2. **Uploads-Verzeichnis ist ein Docker-Volume-Mountpunkt**: der ursprüngliche Code rief `shutil.rmtree(settings.uploads_dir)` gefolgt von `shutil.copytree(...)` auf — schlug mit `OSError: [Errno 16] Device or resource busy` fehl, weil ein Mountpunkt selbst (anders als sein Inhalt) nicht gelöscht/neu angelegt werden kann. Gefixt, indem nur der **Inhalt** des Verzeichnisses geleert wird (`os.listdir()` + einzeln `rmtree`/`remove` je Eintrag), der Mountpunkt selbst aber bestehen bleibt, dann die neuen Dateien per `shutil.move()` hineingeschoben werden.
- **Vollständig end-to-end gegen die echte NAS-Testinstanz verifiziert** (mit expliziter Betreiber-Freigabe für einen echten — nicht nur simulierten — Restore-Test, nachdem Claude Codes eingebauter Sicherheits-Klassifizierer den ersten direkten Versuch dieses destruktiven Befehls blockiert hatte und stattdessen nachgefragt wurde): ein Test-Marker-Wert in `einstellungen` sowie die Patientenanzahl/der Alembic-Migrationsstand wurden vor und nach dem Restore verglichen, zusätzlich die tatsächlichen Datei-Inhalte des wiederhergestellten `uploads/`-Verzeichnisses stichprobenartig geprüft — alle korrekt. Nach erfolgreichem Test wurden die dabei automatisch erzeugten Sicherheitskopien sowie der Test-Marker-Eintrag wieder von der NAS entfernt.
- **Ein Restore aus einem *älteren* Backup lässt den Datenbank-Zustand während des Wiederherstellens serverseitig ungeschützt** (kein Wartungsmodus/Sperre für parallele Requests) — bewusst kein zusätzlicher Aufwand dafür, da diese Funktion für den seltenen "Totalausfall"-Fall gedacht ist, nicht für den laufenden Betrieb; ein Restore sollte praktisch immer in einem Wartungsfenster ausgeführt werden.

## eGK-Scan / OCR-Kartenerfassung (pflegepilot_v3 only, 2026-07-29, T8)

Letzter offener Punkt aus dem Tester-Feedback (siehe `Feedbackfromtester.md`): Krankenkassenkarte abfotografieren statt Versichertennummer/Krankenkasse/Name manuell abzutippen. Vier Produktentscheidungen vorab mit dem Betreiber abgestimmt (`AskUserQuestion`):

- **Tesseract OCR statt Cloud-Vision-API**: kostenlos, läuft offline im Container, kein Account/API-Key/Zahlungsmethode nötig (gleiche Grundsatzentscheidung wie OSM statt Google Places bei der Umkreissuche), Kartenfoto verlässt nie den eigenen Server. Kehrseite: spürbar geringere Erkennungsgenauigkeit als eine Cloud-Lösung, insbesondere bei schlechtem Licht/Winkel — bewusst in Kauf genommen.
- **Nur GKV (elektronische Gesundheitskarte)**, keine PKV-Karten: die eGK hat ein von gematik/GKV-Spitzenverband standardisiertes Layout (Versicherten-ID immer 1 Buchstabe + 9 Ziffern, feste Feldbezeichnungen "Name"/"Vorname"), das eine regelbasierte Erkennung überhaupt erst realistisch macht — PKV-Karten haben kein einheitliches Layout.
- **Alle fünf möglichen Felder werden übernommen** (Vorname, Nachname, Geburtsdatum, Versichertennummer, Krankenkasse), nicht nur die beiden Versicherungsfelder — Betreiber-Vorgabe: der Scan-Button sitzt deshalb in Schritt 1 des "Neuer Patient"-Assistenten (persönliche Daten), nicht erst in Schritt 3 (Krankenversicherung), damit ein einziger Scan beide Schritte vorausfüllt. Alle Felder bleiben normal manuell überschreibbar, eine verpasste/falsche Erkennung blockiert nie die Nutzung.
- **Verfügbar sowohl im "Neuer Patient"-Assistenten als auch im Patient-Bearbeiten-Formular** (z. B. bei Kassenwechsel eines bestehenden Patienten).

**Technisch**:
- `app/egk_ocr.py`: Tesseract (`pytesseract`, deutsches Sprachpaket) liest den Kartentext, danach regelbasierte Feld-Extraktion per Regex (Versicherten-ID: `[A-Z]\d{9}`; Geburtsdatum: `TT.MM.JJJJ`) und Label-Zeilenerkennung ("Name"/"Vorname" gefolgt vom Wert in derselben oder der nächsten Zeile). Die Kartenkontur-Erkennung/Entzerrung vor der OCR wird **1:1 von `dokument_scan.erkenne_und_entzerre()` wiederverwendet** statt eine zweite Kantenerkennung zu schreiben — eine eGK ist geometrisch nur ein kleineres Rechteck als ein A4-Dokument, dieselbe Heuristik passt.
- **Krankenkassen-Erkennung per Fuzzy-Matching** (`difflib.SequenceMatcher`) gegen die bestehende `krankenkassen.py`-Stammdatenliste, da der Kassenname auf der Karte oft als Logo statt als OCR-lesbarer Text gedruckt ist. **Ein echter Fehltreffer wurde beim Verifikationstest mit einem synthetischen Testbild gefunden und behoben, bevor das Feature als fertig galt**: eine kurze, komplett unpassende Zeile (Testname "Mustermann") wurde mit einem zu niedrigen Cutoff fälschlich als "Barmer" erkannt. Gefixt mit zwei Sicherungen: (1) ein Längenunterschied von mehr als 4 Zeichen zwischen OCR-Zeile und Kandidatenname wird gar nicht erst verglichen (SequenceMatcher-Werte werden bei sehr unterschiedlich langen Strings unzuverlässig), (2) ein fester Mindest-Punktzahl-Schwellenwert (`_KASSE_MIN_PUNKTZAHL = 0.72`) statt "bester Kandidat, egal wie schwach" — lieber kein Treffer als ein falscher.
- `POST /api/egk/scan` (`app/routers/egk.py`), 1-2 Fotos (Vorder-/Rückseite), `require_login`-geschützt, **bewusst nicht patientengebunden** (kein `pid` im Pfad) — wird sowohl vor der Patientenanlage (wo noch keine Patienten-ID existiert) als auch beim Bearbeiten genutzt. **Keine Persistierung**: weder das Kartenfoto noch das Erkennungsergebnis werden serverseitig gespeichert, die Response füllt ausschließlich clientseitig Formularfelder vor.
- Frontend: `components/EgkScan.tsx` (Kamera-Capture nach demselben `capture="environment"`-Muster wie `DokumentScan.tsx`, max. 2 Fotos), eingebaut in `patienten/neu/page.tsx` (Step1) und `patienten/[id]/bearbeiten/page.tsx`.
- Neue Abhängigkeiten: `tesseract-ocr` + `tesseract-ocr-deu` (Dockerfile, apt), `pytesseract` (requirements.txt) — braucht ein `docker compose build api`, nicht nur `restart`.
- **Ohne echte Testfotos verifiziert** (wie ursprünglich beim Dokumenten-Scan) — nur ein synthetisches Testbild mit bekanntem, sauberem Text stand zur Verfügung. Die Feld-Heuristiken (insb. Name/Vorname-Zeilenerkennung, die auf dem exakten Aufdruck-Wortlaut der eGK beruht) sollten nach den ersten echten Nutzungen erneut geprüft werden — gleiche Lehre wie beim Dokumenten-Scan ("Kantenerkennung ist mangelhaft" → Nachbesserung erst nach echten Fotos möglich).

## Email: mailto hand-off, not SMTP

There is **no server-side email sending anywhere in the app** — no SMTP client, no credentials, no relay. This was a deliberate removal (not a missing feature) done ahead of Docker containerization, because post-Docker the operator (Daniel) is the sole admin with no per-role differentiation to lean on — any email solution had to work identically for every account, not just an admin-configured one. `mailto:` is the "universal command": every OS/browser resolves it to the user's own default mail client (iOS → Mail, Android → Gmail/Outlook/whatever is set as default, desktop → whatever is set as default), with zero server involvement and zero secrets to manage in the container.

- Previously removed: `smtplib`/`email.mime.*` imports, `_smtp_cfg()`, `_smtp_send()`, `POST /api/email/senden`, `POST /api/email/test`, the "E-Mail (SMTP)" Backend-Einstellungen card, and the `email_smtp_*` settings keys. None of this exists anymore — don't resurrect it as a "fallback"; the user explicitly chose full removal over keeping SMTP as a backup path.
- Frontend flow (`sendMailModal(typ)` / `sendMail(typ)` in `templates/index.html`, shared by both Musterbrief and Widerspruch-Generator via the `typ` parameter): the modal collects Empfänger/Betreff/Anschreiben, then on send the existing client-side `html2pdf.js` PDF generation runs exactly as it already did for the plain "PDF herunterladen" button (`dlW()`/`dlM()`) — the blob is downloaded to the user's device **and** persisted to the patient's Akte via `POST /api/patienten/<pid>/briefe` — then `location.href='mailto:'+to+'?subject=...&body=...'` opens the user's mail client with recipient/subject/body pre-filled.
- **Hard limitation, not a bug**: `mailto:` cannot carry attachments — this is a browser/OS security restriction, not something this app can work around. The email body includes a bracketed reminder ("Bitte die heruntergeladene Datei „…" anhängen, dann diese Zeile löschen") and the modal's info box explains the same thing before sending, so the manual-attach step is expected UX, not a silent gap.
- If you add a third document type that needs "send by email", follow the same pattern: reuse the existing PDF-blob-download code for that document, then call the same `mailto:` construction — don't reintroduce a server-side send path.

## Update-Benachrichtigung / Changelog

A per-account "what's new" system tells a user, once per account, what changed since they last looked — needed now that the app ships as versioned Docker images rather than one continuously-running dev process (see "Docker deployment" above).

**Incident 2026-07-28**: `changelog_seed.py` on the NAS had two historical entries (`"1.2.0" – "Checkliste, Leistungsauswahl, Vollmacht und mehr"` dated 2026-07-27, and `"Version 1.0.1" – "Klein-Anpassungen"`) that were never present in the git-tracked copy of this file — the same class of NAS/git divergence documented for `pdf_templates/brief.html` (see the NAS-deployment memory). A new local entry was written using version `"1.2.0"` without first diffing against the NAS, which would have silently never synced (since `sync_changelog()` only inserts *missing* versions, an already-used version string is a silent no-op, not an overwrite or an error) — caught before deploying by comparing the live `GET /api/changelog` output against the local file. Fixed by restoring both missing historical entries into git (so the file is a complete record again) and renumbering the new entry to `"1.3.0"`. **Lesson**: before adding a new changelog entry, always fetch the current `GET /api/changelog` (or check the DB) rather than assuming the local `changelog_seed.py` is the complete history — the DB is the runtime source of truth and can contain entries the git file never had, exactly like the `brief.html` case.

**Policy: every feature/change from here on gets a changelog entry** (either a new `changelog.py` entry, or an admin-added one via the UI described below), not just a commit message and a `CLAUDE.md` note — the two aren't a substitute for each other. `CLAUDE.md` is for future-Claude/developers; the changelog is for end users. If you ship a user-visible change, add the entry as part of that same piece of work, not as an afterthought.

- **Two-layer source of truth**: `changelog.py` is the developer-authored seed (same static-module pattern as `katalog.py`/`krankenkassen.py`) — a `CHANGELOG` list of `{version, datum, titel, punkte}` entries, always kept **newest-first**. The actual runtime source of truth is the DB table `changelog_eintraege` (`id, version, datum, titel, punkte` — `punkte` stored as a JSON-encoded string list). On every `init_db()` run, any `changelog.py` entry whose `version` isn't yet in the DB gets inserted (`for eintrag in CHANGELOG: ... INSERT ... if not already present`) — a one-way sync, not a mirror: editing an already-synced entry via the admin UI (below) does **not** get overwritten back from `changelog.py` on the next restart, since the sync only inserts missing versions, never updates existing ones. **To ship a release note tied to a real code change: add one new entry to the top of `CHANGELOG` in `changelog.py` and nothing else** — it'll sync into the DB on next startup. For a quick announcement or correction that doesn't need a deploy, use the admin UI instead (below).
- `_changelog_alle()` in `app.py` reads all DB entries ordered `datum DESC, id DESC` (newest first). `_app_version()` is `_changelog_alle()[0]["version"]` (or `"0.0.0"` if the table is somehow empty) — there is deliberately no separate version constant anywhere to remember to bump; whatever's newest in the DB *is* the current version.
- `nutzer.letzte_gesehene_version` (TEXT, nullable) tracks the last version each account has acknowledged. `_changelog_ungesehen(letzte_gesehene_version)` walks `_changelog_alle()` from the top and collects entries until it hits the stored version (or returns everything if the value is `None`/not found — "show more rather than risk hiding something").
- **New vs. existing accounts are handled differently on purpose**: every `INSERT INTO nutzer` (default admin bootstrap, demo bootstrap, and `POST /api/nutzer` for admin-created accounts) sets `letzte_gesehene_version = _app_version()` immediately, so a brand-new account starts "caught up" and is never shown historical entries it never lived through. Existing accounts, by contrast, get the column via the usual `ALTER TABLE ADD COLUMN` migration (see schema-evolution pattern above), which leaves it `NULL` — so on the release where this shipped, and on any future upgrade of a running deployment, already-existing accounts correctly see whatever's newer than what they've acknowledged. Don't backfill existing rows to "already seen" — that would silently suppress the exact notice this feature exists to show.
- `GET /api/auth/me` carries `app_version` and `changelog_ungesehen` (the actual unseen entries, not just a flag) on every call, so the frontend needs no extra round-trip to decide whether to show anything. `POST /api/changelog/gelesen` marks the current version as seen for the logged-in user. `GET /api/changelog` returns the full history with `id`s included (needed by the admin edit/delete UI, see below) and is intentionally *not* on the public allowlist — it's only reachable once logged in, same as the rest of the app shell.
- Frontend: `initApp()` shows a modal (`showChangelogModal()`, built on the existing `OM()` modal helper) with any unseen entries right after login/app-load, unless `aboBlockiert` is true (a payment-blocked account gets sent to `meinabo` instead — no point distracting it with release notes it can't act on yet; it'll see the notice on its next unblocked login). A sidebar nav item **"Was ist neu?"** (`pgChangelog()`, under the `Konto` section next to `Mein Abo`) shows the full history at any time and carries a small red `#cl-badge` dot (matching the existing `#abadge`/`#kbadge`/`#tb-reminder-badge` pattern) while there's anything unseen; visiting the page itself also calls `/api/changelog/gelesen`, so opening the history counts as acknowledging it too, not just clicking "Gelesen" in the modal.
- **Admin can manage entries directly in the app** — `POST/PUT/DELETE /api/admin/changelog[/​<id>]` (all `@admin_required`), surfaced as "+ Neuer Eintrag" plus per-entry edit/delete icons on the `pgChangelog()` page itself when `curUser.rolle==='admin'` (`clFormModal()`/`clSpeichern()`/`clLoeschen()` in `templates/index.html`) — no separate admin-only page, the same "Was ist neu?" view just gets extra controls. `punkte` is entered as one bullet per textarea line client-side, split into a list before sending. All rendered text (`titel`, `punkte`, `version`) goes through `escH()` now that this content can come from a UI form, not just a trusted static file — don't drop that when touching this code. Note: the existing `editNutzerModal(n)` elsewhere in this file passes a whole object via `onclick="fn("+JSON.stringify(n)+")"` inlined into an HTML attribute, which is fragile (breaks if any field contains a `"`); the changelog admin UI deliberately avoids that pattern and instead keeps a `clEntriesCache` array in JS and passes only the numeric `id` into `onclick`, looking the entry back up client-side — prefer this approach for any new "edit via inline button" UI.

## Demo account

A permanent `demo`/`demo` account (`nutzer.ist_demo=1`) exists for showing the app to prospects, created automatically in `init_db()` if missing. It's a completely ordinary `nutzer`-role account — no special-casing in the isolation model — with two exceptions layered on top:

- **Immune to the subscription paywall**: `_hat_aktiven_zugang()` returns `True` for `ist_demo` accounts unconditionally, *before* the `abo_pflicht` check. Don't remove this — a demo visitor must never see "Zahlung erforderlich" regardless of the operator's billing settings. (This was caught by testing, not designed in from the start — worth re-checking if `_hat_aktiven_zugang()` is ever refactored.)
- **Email is a non-issue for the demo account**: since email sending was migrated to the client-side `mailto:` hand-off (see "Email: mailto hand-off, not SMTP" below), there is no server-side outbound relay left to abuse — a demo visitor's "send" click only opens *their own* local mail client via a `mailto:` link, never the operator's infrastructure. The earlier 403 block on `/api/email/senden`/`/api/email/test` for `ist_demo` accounts was removed along with those routes; no replacement guard was needed.

**Auto-reset every 6 hours**, lazily rather than via a background thread/cron (this app has no task scheduler and stays that way — a lazy check fits the existing "one Flask process, no queue" architecture and can't miss a tick across restarts): `_demo_reset_faellig()` compares the `einstellungen` key `demo_reset_at` against `now`; `_demo_reset()` deletes every patient owned by the demo account (cascades to antraege/leistungen/aufgaben/pflegetagebuch/dokumente via the existing `ON DELETE CASCADE` FKs — SQLite enforces this because `get_db()` sets `PRAGMA foreign_keys = ON`), then reseeds one fictional pre-filled patient (`_demo_seed()`: "Grete Musterfrau", Pflegegrad 3, one Antrag, two Leistungen, two Aufgaben, one Pflegetagebuch-Eintrag) and bumps `demo_reset_at`. The check/reset call happens in two places — `api_auth_login()` (fresh state at the start of every demo session) and `global_auth_check()` (catches a session that's still open when the 6h boundary passes mid-visit) — both call the same `_demo_reset_faellig()`/`_demo_reset()` pair, so there's one source of truth for "is a reset due."

The demo account can create up to 2 more patients itself (same 3-per-account cap as any `nutzer` account) via the normal interview flow — nothing special needed there, it's just an ordinary account under the hood.

Frontend: `#demo-badge` in the topbar (toggled in `initApp()` from `me.ist_demo`) makes it visually obvious when a session is in demo mode. Login screen has a dedicated "Demo ausprobieren" button (`doDemoLogin()`) that fills the credentials and reuses `doLogin()` — no separate login code path.

## Admin focus, self-registration & legal pages

Four related pieces shipped together, all from `open.md` items surfaced by real usage after the Docker test run:

- **Admin's sidebar is decluttered**: any `.sb-sec`/`.ni` element carrying `data-role="nutzer"` (Patienten, Leistungskatalog, Formulare & Recht, Aufgaben & Fristen, Mein Abo) is hidden for `rolle==='admin'` in `initApp()` — admin has no patients of their own, so those sections are noise. Admin lands on `admindash` (not `dashboard`) right after login (`doLogin()`) and on page reload (the bottom `initApp().then(...)` call) — Nutzerverwaltung is the admin's actual job here, not care-record data entry.
- **Admin-Dashboard is now the one-stop nutzer-management view**: `renderAdminDash()`'s Konten table gained `Registriert` (`erstellt_am`) and `Letzter Login` (+ IP) columns, plus a **Bearbeiten** button (`adminNutzerBearbeitenModal()`) that edits name/rolle/aktiv/passwort *and* the Rechnungsanschrift in one modal — previously only the simpler Backend "Nutzerverwaltung" card (still there, still fine for quick account creation) could edit a profile at all, and it had no billing-address or login-history visibility. `letzter_login`/`letzte_ip` (`nutzer` columns) are stamped on every successful login and self-registration in `api_auth_login()`/`api_auth_registrieren()` — `X-Forwarded-For` is honored ahead of `request.remote_addr` for when a reverse proxy sits in front (relevant once the DynDNS/testbench setup is live), taking the first hop only.
- **Self-registration** (`POST /api/auth/registrieren`, public — added to the `global_auth_check()` allowlist): a "Noch kein Konto? Jetzt registrieren" link on the login screen (`showRegisterForm()`/`hideRegisterForm()` toggle the same `.lo-box`, no separate page) collects Benutzername/Passwort/Name plus a **mandatory** Rechnungsanschrift (`rg_name`/`rg_strasse`/`rg_plz`/`rg_ort` on `nutzer`) and auto-logs the new account in on success (`doRegister()`). New accounts are marked `selbst_registriert=1` — admin-created accounts (`POST /api/nutzer`, still admin-only) stay `0` and are deliberately unaffected by everything below, so nothing changes for how admin onboards trusted/manual accounts.
- **Freemium write-lock for unpaid self-registrations**: `_hat_bezahlten_zugang(u)` (real `abo_bis` check, admin/demo always true) is deliberately separate from `_hat_aktiven_zugang()`/`abo_pflicht` — a self-registered account without a paid/granted subscription can browse and read *everything*, but `global_auth_check()` blocks `POST`/`PUT` to the letter-generation (`.../briefe`), Leistungen-assignment (`.../leistungen/katalog`, `.../deaktivieren`) and Aufgaben-creation (`/api/aufgaben`) endpoints with a 402 regardless of the global `abo_pflicht` toggle. This only applies when `selbst_registriert=1`, so it can go live immediately (no PayPal needed yet) without touching existing admin-created accounts. `GET /api/auth/me` exposes `schreibzugriff_gesperrt` so the frontend can short-circuit before doing client-side work (PDF generation, etc.) rather than relying on the 402 alone — `_schreibgesperrt()` in `templates/index.html` is the shared guard, called at the top of `dlM()`/`dlW()`/`sendMail()`/`assignL()`/`saveAufg()`; it toasts and redirects to `meinabo`. Lifting the lock is just admin granting `abo-freischalten` (existing mechanism) or, eventually, real payment — no separate "unlock" code path needed.
- **Admin can generate a legally compliant PDF invoice** per account (`rechnungModal()` → `rechnungErstellen()` in `templates/index.html`) — client-side PDF via the same `html2pdf.js` pattern as Musterbrief/Widerspruch (Courier-style text block, `addPageNums()`), but the invoice **number itself is server-issued**: `POST /api/admin/rechnungsnummer/naechste` (admin-only) atomically increments an `einstellungen`-backed counter (`rechnungsnummer_counter` + `rechnungsnummer_jahr`, format `{Jahr}-{Nummer:04d}`, resets to 1 on a new calendar year) so two invoices can never collide on the same number — required by § 14 Abs. 4 Nr. 4 UStG ("fortlaufende, einmalige Nummer"), which a purely client-side/date-based guess couldn't guarantee. The rest of § 14 UStG's Pflichtangaben are covered by a dedicated **"Rechnungsstellung"** card in Backend-Einstellungen (`rechnung_absender_name/_strasse/_plz/_ort`, `rechnung_steuernummer`, `rechnung_ustid`, `rechnung_kleinunternehmer`, `rechnung_ust_satz`) — deliberately **separate from the "Betrieb" card**, since the invoice seller address/tax data can legitimately differ from (or need to be more complete than) the branding address, and isn't needed by the public `/api/einstellungen/public` endpoint the way Impressum/Datenschutz are, so it's fetched fresh from the admin-only `/api/admin/einstellungen` inside `rechnungModal()` instead of the cached `_einstellungen` global. `rechnungErstellen()` refuses to generate a PDF (with a toast, not a silent blank field) if the seller address or a Steuernummer/USt-IdNr is missing. Depending on `rechnung_kleinunternehmer`, the invoice either shows a Netto/USt-Satz/USt-Betrag/Brutto breakdown (`betragBrutto / (1 + ustSatz/100)` for Netto) or the § 19 UStG small-business exemption note instead of a tax line — never both. No server-side persistence/archival of the invoice PDF itself (unlike patient documents) — these aren't care records under the §630f BGB retention duty, so a simple download suffices for "on customer request"; only the invoice *number* counter is persisted, since that's the part that must never repeat or gap.
- **Legal pages**: three `rechtstext_impressum`/`rechtstext_datenschutz`/`rechtstext_agb` keys in `einstellungen`, edited as plain textareas in the Backend-Einstellungen card that replaced "KI – Claude API" (same slot, same `saveEinst()` pattern). They're deliberately included in the **public** `/api/einstellungen/public` payload (no login required) since Impressum/Datenschutz shouldn't hide behind a login wall, and `pgRechtstext(typ)` (routed via `go('impressum'|'datenschutz'|'agb')`) reads them straight from the already-cached `_einstellungen` object. A small `.sb-legal` link row was added to the sidebar bottom, and `go()` exempts these three page names from the `aboBlockiert` redirect-to-`meinabo` logic — a payment-blocked account must still be able to read the legal pages.
- **The "Betrieb" card was deliberately kept**, not removed, despite the original `open.md` wording ("das kann weg") — `firmenname`/`firmen_logo`/`firmen_strasse`/etc. are actively used for sidebar branding and the "Erstellt mit {firmenname}" footer on generated PDFs (Musterbrief, Widerspruch, Pflegetagebuch, Patientenakte); deleting the only UI to edit them would have been a silent regression unrelated to the actual ask. If this was in fact meant to go, that's a call for the product owner, not something to infer from "veraltet."

## Known constraints worth knowing before touching auth/security-sensitive code

- `app.secret_key` in `app.py` is a hardcoded string, not loaded from an environment variable.
- The default admin account (`admin`/`admin`) is created automatically and nothing forces a password change.
- These are pre-existing conditions in the current alpha, relevant context if working on the auth/admin-dashboard parts of the refactor above.

## iOS Safari: Autofill-Attribute nachgerüstet (pflegepilot_v3 only, 2026-07-29)

Tester-/Kunden-Feedback: auf iOS Safari funktionierte Autofill "nicht sauber" und einzelne Wizard-Schritte blieben teils bei "Lädt…" hängen. Bei der Untersuchung wurde festgestellt, dass praktisch **jedes Formularfeld der eingeloggten App komplett ohne `name`- und `autoComplete`-Attribute** war — nur Login/Registrierung/Passwort-Reset hatten das korrekt gesetzt. Das ist ein bekanntes React+Safari-Muster: ohne diese Attribute trägt iOS Safaris Autofill den Wert teils direkt ins DOM ein, ohne das Event auszulösen, auf das Reacts kontrollierte Inputs lauschen — das Feld sieht sichtbar ausgefüllt aus, der React-State bleibt aber leer (Validierung schlägt fehl / leere Werte werden abgeschickt).

- **Nachgerüstet in**: "Neuer Patient"-Assistent, Patient-Bearbeiten-Formular, Musterbrief/Widerspruch/Ummeldung/Vollmacht/Patientenverfügung-Generatoren, Aufgabe-anlegen-Modal, Login/Registrierung/Passwort-Reset (dort schon vorhanden, jetzt zusätzlich mit stabilen `name`-Attributen), Admin-Nutzer-anlegen, Umkreissuche-PLZ-Feld, Katalog-/Patienten-Suchfelder, `KrankenkasseAutocomplete`/`RentenversicherungAutocomplete`.
- **Wichtige Unterscheidung, kein pauschales `autoComplete="name"` überall**: Felder, die den **Kontoinhaber selbst** betreffen (Rechnungsanschrift bei der Registrierung, "Bevollmächtigte/r (Sie)" bei der Vollmacht, Admin-Nutzer-Passwort als `new-password`), bekamen echte semantische Autofill-Tokens (`given-name`/`family-name`/`street-address`/`postal-code`/`address-level2`/`tel`/`email`/`new-password`) — dort ist Browser-Autofill mit den eigenen gespeicherten Daten korrekt und erwünscht. Felder, die eine **andere Person** betreffen (die gepflegte Person im "Neuer Patient"-Assistenten, die "Versicherte Person" im Musterbrief, Vertrauenspersonen in der Patientenverfügung), bekamen bewusst `autoComplete="off"` statt eines passenden Tokens — sonst würde iOS Safaris Kontakt-Autofill das Formular leicht mit den **eigenen** Kontaktdaten des Nutzers befüllen, was falsch wäre und ebenfalls unter "Autofill funktioniert nicht sauber" fallen würde.
- **Noch nicht angefasst** (bewusst niedrige Priorität, kein Kundenkontakt oder keine personenbezogenen Felder): Changelog-Admin-Editor, `BudgetTracker`-Beträge, Zeitfelder in den Erinnerungs-Einstellungen.
- Ohne echtes iOS-Gerät verifiziert (Betreiber hat keins zur Verfügung) — Absicherung ausschließlich über Code-Review gegen ein bekanntes, gut dokumentiertes Browser/React-Zusammenspiel, TypeScript- und ESLint-Prüfung. Sollte das Problem nach diesem Fix fortbestehen, ist der zweite Verdacht (siehe nächster Abschnitt) der wahrscheinlichere Haupttäter.

## Frontend-Produktions-Build statt next dev (pflegepilot_v3 only, 2026-07-29, Phase 7)

Zweiter, vermutlich gewichtigerer Verdacht zum selben iOS-Safari-Feedback ("Lädt…" bleibt stehen): die Produktion lief bis dahin über **`next dev`** (Next.js-Entwicklungsserver, Turbopack) statt eines echten Produktions-Builds — im Frontend-`Dockerfile` stand das explizit als offener "Phase 7"-Punkt. Der Dev-Server braucht eine Hot-Module-Reload-Websocket-Verbindung im Hintergrund; es gab in diesem Repo bereits eine dokumentierte frühere Begegnung mit fast demselben Symptom (`next.config.ts`-Kommentar zu `allowedDevOrigins`: *"…hängt die HMR-Verbindung, was im Turbopack-Dev-Modus die Hydration blockiert (Seite bleibt bei der server-gerenderten 'Lädt…'-HTML stehen)"*). iOS Safari geht mit WebSockets über Hintergrund-Tabs/Reverse-Proxy-Verbindungen nachweislich anders um als Chrome — unabhängig vom genauen Mechanismus ist ein Dev-Server in Produktion ohnehin nie für echten Nutzerverkehr gedacht.

- **`next.config.ts`**: `output: "standalone"` ergänzt — Next erzeugt dadurch ein eigenständiges, minimales Server-Bundle (`server.js` + nur benötigte `node_modules`), Grundlage für ein schlankes Produktions-Image.
- **`frontend/Dockerfile`**: komplett auf einen mehrstufigen Build umgestellt (`builder`-Stage: `npm ci` + `npm run build`; `runner`-Stage: nur `.next/standalone` + separat kopiertes `.next/static` + `public/`, non-root `appuser`). `CMD` ist jetzt `node server.js` statt `npm run dev`.
- **`NEXT_PUBLIC_*`-Variablen werden beim Build eingebacken, nicht erst zur Laufzeit gelesen** — anders als normale Server-Env-Variablen (z. B. `API_INTERNAL_URL`, die weiterhin ganz normal zur Laufzeit gelesen wird). `docker-compose.yml`s `web`-Service reicht `NEXT_PUBLIC_API_URL`/`NEXT_PUBLIC_SITE_URL` deshalb jetzt als **Build-Args** (`build.args`) durch, nicht nur als `environment:` — ein reines Setzen zur Laufzeit hätte keine Wirkung mehr auf den bereits fertig gebauten Client-Code gehabt.
- **Kein Bind-Mount/keine anonymen Volumes mehr für `web`** (anders als beim bisherigen `next dev`-Setup und anders als beim `api`-Service, der das Bind-Mount-Muster für schnelle Iteration behält) — das Image enthält das fertig gebaute Bundle. **Wichtigste Konsequenz für künftige Arbeit**: eine Code-Änderung am Frontend braucht ab jetzt immer `docker compose build web` **vor** `docker compose up -d --force-recreate web` (reines `restart`/`up -d` ohne vorherigen Build zeigt nur den alten Stand) — das bisherige Muster "Datei per scp kopieren, dann nur neustarten" funktioniert für `web` nicht mehr. Für `api` bleibt das alte Muster unverändert gültig (dort weiterhin Bind-Mount + `next dev`-Analogon existiert nicht, Uvicorn/Gunicorn liest Code-Änderungen ohnehin erst nach Neustart, kein Rebuild nötig).
- **Betreiber-Entscheidung**: ein Modus für lokale Entwicklung UND NAS/Produktion (keine separate `docker-compose.dev.yml`/`docker-compose.prod.yml`) — bewusst in Kauf genommen, dass lokales Iterieren jetzt ebenfalls einen Rebuild pro Änderung braucht, statt zwei Compose-Konfigurationen parallel zu pflegen.
- **Vor dem eigentlichen Umschalten auf der NAS verifiziert, ohne den laufenden Dev-Container zu unterbrechen**: neues Image separat gebaut (`docker compose build web` ändert nur das Image, nicht den laufenden Container), testweise unter einem anderen Port (`docker run ... -p 3199:3000`) parallel gestartet, dort Startseite/Dashboard/robots.txt sowie alle referenzierten `_next/static`-JS-Chunks auf HTTP 200 geprüft, SEO-Metadaten/JSON-LD/Feature-Kacheln der Landingpage inhaltlich verglichen — erst danach den echten `web`-Service umgeschaltet und zusätzlich über die echte Domain via Reverse-Proxy (`curl --resolve meinpflegefuchs.de:443:127.0.0.1 https://meinpflegefuchs.de/…`, korrektes SNI nötig, sonst TLS-Handshake-Fehler) bestätigt.
- **Ohne echtes iOS-Gerät verifiziert** (Betreiber hat keins zur Verfügung) — die Kernannahme (kein Dev-Server/HMR mehr im Produktionspfad) ist aber unabhängig vom tatsächlichen Safari-Verhalten schon für sich genommen die richtige Grundlage für einen produktiven Deploy.

## Antragsstatus-Tracking + automatischer Widerspruchs-Vorschlag (pflegepilot_v3 only, 2026-07-31, T25)

Letzter Punkt aus dem Tester-Feedback-Backlog (`Feedbackfromtester.md`, Side-Plan `~/.claude/plans/antragsstatus-tracking.md`). Wunsch: das System soll "regelmäßig abfragen", ob ein gestellter Antrag bewilligt/abgelehnt wurde. **Realitätscheck (mit Betreiber vorab geklärt)**: Kranken-/Pflegekassen bieten keine Status-API — "regelmäßig abfragen" bedeutet technisch, dass das System periodisch den **Nutzer selbst** per E-Mail fragt, nicht dass echte externe Automatisierung stattfindet.

- **Drei neue Antrag-Felder** (Migration `a1c4e7f9b3d6`): `bewilligter_betrag`, `aktenzeichen` (vorher nur transient in `WiderspruchRequest`, nie persistiert), `naechste_statuserinnerung_am` (Fälligkeitsdatum der nächsten "ist der Bescheid da?"-Mail) sowie `widerspruch_eskalation_gesendet` (Dedupe-Flag). Neue Tabelle `antrag_aktions_token` für Magic-Link-Einmal-Token (SHA-256-Hash-Muster wie `Nutzer.reset_token_hash`, siehe `app/antrag_token.py`).
- **Erinnerungsintervall je Antragstyp** (`static_data/antrag_fristen.py: ANTRAG_ERINNERUNGS_TAGE`): 35 Tage für `erstantrag`/`hoeherst` (orientiert an der 25-Arbeitstage-Frist § 18 Abs. 3 SGB XI + Puffer), 56 Tage für `widerspruch`, 42 Tage für `eingliederung`/`grundsicherung`/`blindenhilfe`. Wiederholt sich alle 21 Tage, solange keine Antwort eingetragen wird, bricht nach 180 Tagen ganz ab (kein endloses Nerven). `adressaenderung`/`vollmacht`/`patientenverfuegung` sind bewusst nicht im Tracking, da dort kein Bescheid erwartet wird.
- **Magic-Link-E-Mail statt reiner Statusabfrage in der App**: `reminder_scheduler.py` (selber Hintergrund-Thread/Advisory-Lock wie Tagebuch-/Aufgaben-Reminder, kein neuer Scheduler nötig) verschickt eine Mail mit drei Links ("Ja, bewilligt" / "Ja, abgelehnt" / "Noch keine Antwort"), je ein Klick landet auf `(marketing)/antrag-status` (bewusst in der `(marketing)`-Gruppe, nicht `(app)`, aus demselben Grund wie die Passwort-Reset-Seite — `AuthOverlay` würde sonst blockieren, bevor der Token überhaupt eingelöst ist), löst dort `POST /api/antraege/aktion-token/einloesen` aus (öffentlicher `router_public` ohne `require_login`, exakt wie `passwort-zuruecksetzen`) und setzt dabei eine **echte Session** (`request.session["nutzer_id"] = ...`), sodass der Rest der App danach ganz normal hinter dem bestehenden Login-Schutz weiterläuft. Ein Token deckt alle drei Ergebnis-Links ab (Ergebnis kommt als eigener Query-Parameter) und ist strikt Einmalgebrauch — nach einem Klick sind die anderen beiden Links derselben Mail ungültig.
- **Bei Ablehnung eines Pflegegrad-Antrags** (`erstantrag`/`hoeherst`) landet der Nutzer auf einer neuen "Keine Sorge"-Seite (`(app)/antraege/[id]/keine-sorge`): sachlich-ermutigender Text (bewusst **ohne erfundene Erfolgsquote** — nicht verifizierbar, rechtlich heikel; stattdessen häufige, tatsächliche Ablehnungsgründe aus der bereits bestehenden `WGRUENDE`-Bibliothek in einfacher Sprache), Fristanzeige (§ 84 SGG, 1 Monat, farbcodiert nach Resttagen) und ein **eingebetteter Mini-Widerspruch-Generator** (Patient/Bescheiddaten vorbefüllt, Nutzer wählt weiterhin selbst die zutreffenden Gründe — das kann die App nicht automatisch wissen). Für die anderen drei Antragstypen (`eingliederung`/`grundsicherung`/`blindenhilfe`) gibt es noch keine passenden Widerspruchsgründe in `WGRUENDE` — dort verlinkt die Seite nur auf das bestehende allgemeine `/widerspruch`-Formular. Ein "Vollständiges Formular öffnen"-Link übergibt alle bereits erfassten Werte als Query-Parameter an `/widerspruch` (das dafür wie `/musterbrief` einen Suspense-Wrapper für `useSearchParams()` bekam) — kein doppeltes Ausfüllen.
- **Fristeskalation**: zusätzlich zur einmaligen Erklärung auf der Keine-Sorge-Seite verschickt `reminder_scheduler.py._sende_widerspruch_eskalation()` ca. 7 Tage vor Ablauf der Widerspruchsfrist eine dringlichere Mail, falls noch kein Widerspruch erstellt wurde. Die Prüfung "wurde schon Widerspruch eingelegt" läuft rein über eine Patient+Zeitpunkt-Korrelation (`Antrag.typ='widerspruch'` mit `erstellt_am` nach dem ursprünglichen Antrag) — kein neues FK-Feld zwischen einem Antrag und seinem Widerspruch.
- **Sowohl App-generierte als auch extern gestellte Anträge werden getrackt**: der bereits bestehende generische `POST /api/antraege`-Endpunkt deckte das Nachtragen extern gestellter Anträge schon ab, es fehlte nur eine Frontend-Fläche — neuer Button "+ Antrag manuell erfassen" in der Patientenakte. Ebenso neu: eine "Status bearbeiten"-Inline-Form pro Antragszeile (Status, Bescheiddatum, Aktenzeichen, bei genehmigt/abgelehnt zusätzlich zugeteilter Pflegegrad, bei genehmigt zusätzlich bewilligter Betrag) über den bereits bestehenden generischen `PUT /api/antraege/{id}`.
- **End-to-end gegen die echte lokale Docker-Postgres-Instanz verifiziert** (nicht nur Unit-Ebene): Migration lief sauber durch, Antrag-Erstellung setzt `naechste_statuserinnerung_am` korrekt, `_sende_antragsstatus_erinnerungen()`/`_sende_widerspruch_eskalation()` einmal direkt aufgerufen (E-Mail-Versand schlug am echten SMTP-Ziel erwartungsgemäß fehl, wurde aber sauber abgefangen, ohne den Durchlauf abzubrechen), Token-Einlösung inkl. Session-Login und Einmalgebrauch (Zweitversuch mit selbem Token schlägt korrekt fehl) geprüft, Eskalations-Dedupe und die "schon Widerspruch eingelegt"-Heuristik beide bestätigt. `next build` lief fehlerfrei durch (`/widerspruch` weiterhin statisch, `/antraege/[id]/keine-sorge` korrekt dynamisch), alle neuen Routen lieferten HTTP 200 in einem containerisierten Produktions-Build. **Kein Klick-Test im echten Browser** (keine Anzeige/Playwright in dieser Umgebung verfügbar) — die UI-Logik selbst (bedingtes Rendering, Formulare) ist damit ungeprüft auf visuelle Überraschungen, nur der Datenfluss ist backend-seitig vollständig bestätigt.

## Admin-Dashboard: E-Mail-Log, Scheduler-Status, Speicherplatz-Übersicht (pflegepilot_v3 only, 2026-07-31)

Betreiber-Feedback: keine Übersicht über den E-Mail-Versand (wie viele Mails, welcher Typ, Erfolg/Fehler) — relevant für Skalierungsentscheidungen. Claude hat zwei verwandte Punkte ergänzend vorgeschlagen (Scheduler-Status, Speicherplatz), da beide dieselbe "wie skaliere ich das"-Fragestellung betreffen; der Betreiber hat alles zusammen freigegeben ("bau mir das alles ein"), plus eine vierte, separat gewünschte Ergänzung (Nutzerliste um E-Mail/Rechnungsadresse).

- **`email_log`-Tabelle** (Migration `b2d5e8f0c3a7`, Modell `EmailLogEintrag`): `send_email()` (`app/email_util.py`) ist die einzige Stelle mit SMTP-Zugriff im gesamten Backend (7 Call-Sites: Passwort-Reset, Tagebuch-/Aufgaben-Reminder, Antragsstatus-Erinnerung + Widerspruchs-Eskalation aus T25, Katalog-Änderung, Umkreis-Favoriten-Änderung) — die Funktion bekam dafür eine neue Pflicht-Parameter-Reihenfolge (`db: Session` als erstes Argument, `typ: str` keyword-only) und protokolliert jeden Aufruf mit Status `gesendet`/`fehlgeschlagen`/`uebersprungen` (Letzteres: kein `SMTP_HOST` konfiguriert). Die Log-Zeile wird nur per `db.add()` vorgemerkt, nicht selbst committet — das bleibt Aufgabe des jeweiligen Aufrufers, kein zusätzlicher Roundtrip gegenüber vorher. `GET /api/admin/email-log?tage=30` liefert die letzten 200 Einzel-Einträge plus serverseitig aggregierte Zählung nach Typ/Status.
- **Scheduler-Status ohne neue Tabelle**: alle 4 Hintergrund-Scheduler (`reminder_scheduler.py`, `backup_scheduler.py`, `umkreis_favoriten_watch.py` je Schleifendurchlauf; `katalog_watch.py` einmalig beim Start) schreiben ihren Zeitstempel über die neue Hilfsfunktion `einstellungen.py: stempel_scheduler_lauf(name)` in die bereits bestehende generische `einstellungen`-Key-Value-Tabelle (`scheduler_letzter_lauf_<name>`) — passt zum etablierten Muster (wird schon für `demo_reset_at`/`rechnungsnummer_counter` genutzt), keine neue Migration dafür nötig. `GET /api/admin/scheduler-status` berechnet serverseitig `status` (`ok`/`verzoegert`/`nie_gelaufen`) je Scheduler; `katalog_watch.py` ist als `einmalig=True` markiert, da es nur einmal pro App-Start läuft und deshalb nie sinnvoll als "verzögert" gegen ein Wiederholungsintervall geprüft werden kann (jeder vorhandene Zeitstempel bedeutet dort "beim letzten Start erfolgreich gelaufen").
- **Speicherplatz-Übersicht** (`GET /api/admin/speicherplatz`, keine Persistenz, live berechnet): Uploads-Größe rekursiv per `os.walk` über `settings.uploads_dir`, aufgeschlüsselt nach Unterordner (`briefe`/`dokumente`/`fotos`); Backup-Größe aus dem bereits bestehenden `backup.py: liste_backups()` summiert (keine doppelte Logik); Datenbankgröße über `SELECT pg_database_size(current_database())`.
- **Nutzerliste um E-Mail + Rechnungsadresse** (`admin/page.tsx`, rein Frontend): Backend lieferte `email`/`rg_name`/`rg_strasse`/`rg_plz`/`rg_ort` in `GET /api/nutzer` bereits vollständig mit — es fehlten nur die Tabellenspalten. Bewusst nur sichtbar gemacht, nicht editierbar (eine `aktualisieren`-Mutation für ein Bearbeiten-Modal existierte zwar schon ungenutzt in `lib/admin.ts`, war aber nicht Teil dieser Anfrage).
- **End-to-end gegen die echte lokale Docker-Postgres-Instanz verifiziert**: Migration lief sauber durch, alle 3 neuen Endpunkte per curl geprüft, ein echter `send_email()`-Fehlschlag (SMTP-Ziel lehnte ab) erzeugte korrekt einen `email_log`-Eintrag mit Typ/Status/Fehlermeldung, alle 4 Scheduler stempelten ihren ersten Lauf direkt nach Container-Start korrekt. **Ein scheinbares Mojibake-Problem bei Umlauten** (`Ä` erschien in der Terminal-Ausgabe verstümmelt) stellte sich bei genauerer Prüfung der rohen Response-Bytes als reines Terminal-/Encoding-Anzeigeproblem dieser Windows-Entwicklungsumgebung heraus, nicht als echter Bug — die API liefert korrektes UTF-8. `next build` lief fehlerfrei durch, `/admin` blieb weiterhin eine statische Route. **Achtung bei künftigem Debugging dieser lokalen `.env`**: sie enthält das echte, produktiv genutzte SMTP-Passwort im Klartext (dieselbe lokale `.env` wird für Realismus mit Produktionsdaten befüllt) — beim Prüfen von SMTP-Settings gezielt einzelne Keys grep'en, nicht die ganze Datei ausgeben.
- **Nachbesserung noch am selben Tag** (Betreiber-Feedback: die Konten-Tabelle wirkte durch die zwei neuen Spalten (E-Mail, Rechnungsadresse) "zerfetzt"): die generische `ResponsiveTable`/`Column`-Tabelle wurde für die Konten-Liste durch eine eigene Karten-Liste mit fester 3-Zeilen-Gliederung ersetzt (Zeile 1: Konto/Status/E-Mail, immer sichtbar; Zeile 2: Rechnungsadresse/Preis/Zugang/Registriert; Zeile 3: Patienten/Aktionen — beide nur bei aufgeklapptem Konto). Jedes Konto ist einzeln auf-/zuklappbar (`offeneKonten`-Set, unabhängig voneinander, nicht wie das alte `.rtable`-Akkordeon-Muster aus `pflegepilot_alpha_v2` mit genau einem offenen Element), Default ist eingeklappt. Dazu eine Klartext-Suche (`kontoSuche`, filtert clientseitig über Benutzername/Name/E-Mail/Rechnungsname) — kein Backend-Change nötig, da `GET /api/nutzer` ohnehin alle Konten auf einmal liefert. `ResponsiveTable` selbst bleibt unverändert bestehen, wird an anderer Stelle (`aufgaben/page.tsx`, `patienten/page.tsx`) weiterhin genutzt.

## Admin-Bereich: neue Statistik-Seite (pflegepilot_v3 only, 2026-08-01)

Betreiber-Wunsch nach einer eigenen Statistik-Seite im Admin-Bereich, im Anschluss an das E-Mail-Log-Feature. Umfang über zwei `AskUserQuestion`-Runden geklärt: 7 Kategorien wurden gebaut (Konten-Wachstum, Patienten & Pflegegrad-Verteilung, Anträge & Erfolgsquote inkl. Widerspruch-Rate, Umsatz aktuell, Aktivierungsquote, Time-to-Value, Retention-Näherung); API-Response-Times und Fehlerquoten wurden bewusst **nicht** gebaut (keinerlei Request-Timing-/Error-Logging existiert bisher irgendwo in der App — das wäre ein komplett neues Instrumentierungs-Feature vom Umfang des E-Mail-Logs, für eine Solo-Betreiber-App nicht im Verhältnis).

- **Neues Modul `backend/app/statistiken.py`** (`berechne_statistiken(db)`), neuer Endpunkt `GET /api/admin/statistiken` (`routers/admin.py`) — ein einziger aggregierter Response, gleiches Muster wie das E-Mail-Log. **Keine Migration nötig**, rein lesende Aggregation gegen vorhandene Tabellen.
- **Konsistente Filterregel**: alle wachstums-/geschäftsbezogenen Kennzahlen filtern auf `rolle='nutzer' AND ist_demo=False` ("echte Kunden") — nur die Konten-Übersicht zeigt zusätzlich Admin-/Demo-Konten als eigene Segmente. Verifiziert: der von `app.seed` angelegte Demo-Patient taucht korrekt in keiner einzigen wachstumsbezogenen Kennzahl auf.
- **Wiederverwendete Bausteine statt neu erfunden**: `einstellungen.py: berechne_abo_preis()` für den Umsatz, `static_data/antrag_fristen.py: ANTRAG_ERINNERUNGS_TAGE` für die "trackbaren" Antragstypen (identisch zu T25), die Widerspruch-Korrelations-Heuristik aus `reminder_scheduler.py: _sende_widerspruch_eskalation()` (gleicher Patient, `typ='widerspruch'`, `erstellt_am` nach dem Ausgangsantrag) für die Widerspruch-Rate.
- **Umsatz-Bucket-Logik**: `abo_typ == 'kostenlos_admin'` → Bucket "kostenlos" (nicht in der MRR-Summe), alles andere mit aktivem `abo_bis` → Bucket "zahlend" — ehrliche Zahl unabhängig davon, ob echte Zahlungen über PayPal schon fließen oder aktuell nur Freischaltungen existieren.
- **Kein Chart-Package im Frontend** (`package.json` hatte bis dahin nur `@tabler/icons-react` + `@tanstack/react-query`) — stattdessen eine schlanke, abhängigkeitsfreie Inline-SVG-Komponente `components/BarChart.tsx`, gebaut nach der `dataviz`-Skill-Methode (Mark-Specs: Balken ≤24px, 4px abgerundete Kappe/quadratische Grundlinie, 2px Lücke, Werte direkt an der Balkenspitze statt einer Hover-Tooltip-Statemachine — bei ≤12 Balken pro Diagramm laut Skill-Referenz sanktioniert). **Farbzuordnung nutzt bewusst die bereits etablierten Tailwind-Hex-Werte dieser App statt der Skill-Referenzpalette** (die Methode ist laut Skill design-system-agnostisch — "substitute this file's values"): `lib/chartColors.ts` mit `sequential` (ein Blauton, reine Größenvergleiche), `ordinalPflegegrad()` (ein Indigo-Ton, Helligkeit steigt mit dem Pflegegrad 0→5), `statusFarbe()` (exakt dieselbe emerald=gut/red=kritisch/amber=Warnung-Konvention, die `admin/page.tsx` schon für Status-Badges nutzt). Kein automatisierter Lauf von `validate_palette.js` gegen diese Tailwind-Hexwerte — bewusste, dokumentierte Vereinfachung für eine kleine interne Ein-Personen-Admin-Seite.
- **Neue Route** `admin/statistiken/page.tsx`, Nav-Eintrag in `(app)/layout.tsx`s `ADMIN_SECTIONS` — der bestehende `/admin*`-Zugriffsschutz deckt sie automatisch mit ab, keine separate Schutzlogik nötig.
- **End-to-end mit handangelegten Testdaten verifiziert** (3 Kundenkonten mit unterschiedlichen Registrierungsdaten/Login-Zeitpunkten/Abo-Zuständen, 1 Patient, 3 Anträge inkl. eines Widerspruchs) — alle 13 Kennzahlen des Response gegen die von Hand berechneten Erwartungswerte exakt geprüft (u. a. Monats-Buckets, MRR-Bucket-Trennung zahlend/kostenlos, Time-to-Value-Median, Retention-Quote je Kohorte), nicht nur oberflächlich auf HTTP 200 getestet. `next build` bestätigt `/admin/statistiken` als statische Route.
- **Nachbesserung direkt im Anschluss** (Betreiber-Feedback: Balkendiagramme kollidierten mit den umgebenden Karten): Ursache war, dass ein SVG-Wurzelelement standardmäßig NICHT am `viewBox`-Rand clippt (`overflow:visible`) — bei gekippten/langen Achsenbeschriftungen (z. B. "Eingliederungshilfe", "In Prüfung") war das reservierte Platzband in `components/BarChart.tsx` zu knapp geschätzt, der Text malte dadurch sichtbar über die eigene Box hinaus in Nachbarkarten hinein. Gefixt durch tatsächliche (nicht geschätzte) Geometrie-Berechnung des Platzbedarfs aus dem Rotationswinkel (`Math.cos`/`Math.sin` auf die Label-Pixelbreite), plus Kürzung langer Labels auf 7 Zeichen mit „…" (voller Text bleibt im `<title>`-Hover erhalten) und einem steileren Rotationswinkel (50° statt 35°, reduziert die horizontale Ausdehnung des gekippten Labels und damit die Kollisionsgefahr mit dem Nachbarbalken). Bewusst großzügig geschätzte Zeichenbreite (6.2px bei font-size 10) statt einer knappen Schätzung — lieber etwas mehr Abstand reservieren als eine erneute Kollision riskieren.

## Hard-Delete für Nutzerkonten im Admin-Dashboard (pflegepilot_v3 only, 2026-08-01)

Betreiber-Feedback: der bereits existierende Hard-Delete-Endpunkt (`DELETE /api/nutzer/{uid}` in `routers/admin.py`, verweigert wie in `pflegepilot_alpha_v2` mit 400, solange das Konto noch Patienten besitzt, blockt Selbstlöschung) hatte keine Frontend-Anbindung — nur der Soft-Delete-Button ("Löschen", archiviert Patienten statt sie zu löschen) war in der Kontenliste erreichbar.

- **Beim Anfassen ein Konsistenz-Gap gefunden und mitbehoben**: anders als jede andere destruktive Admin-Aktion in dieser App (Sperren/Entsperren/Soft-Delete/Abo-Freischalten – alle verlangen eine Begründung und werden über `log_admin_aktion()` unveränderlich protokolliert) verlangte der Hard-Delete-Endpunkt bislang weder eine Begründung noch erzeugte er einen Audit-Log-Eintrag. Nachgezogen: `payload: BegruendungRequest` Pflichtfeld, `log_admin_aktion(db, admin, "konto_hart_geloescht", "nutzer", uid, benutzername, grund)` vor dem `db.delete()` (Name/Begründung werden VOR dem Löschen erfasst — der Audit-Log-Eintrag selbst hat bewusst keinen FK auf `nutzer.id`, siehe `audit.py`, und überlebt die Löschung).
- **Frontend**: neuer Button "Hart löschen" in der Konten-Kartenliste (`admin/page.tsx`), bewusst nur sichtbar, wenn `patienten_anzahl === 0` (vermeidet einen Klick, der serverseitig ohnehin abgelehnt würde). Nutzt dieselbe `BegruendungModal`-Komponente wie die anderen Aktionen, die dafür zwei neue optionale Props bekam: `warnung` (roter ⚠️-Warntext oberhalb des Formulars, hier: "endgültig aus der Datenbank – keine Archivierung, keine Wiederherstellung") und `fehler` (zeigt den Mutation-Fehler direkt im Modal — ein Gap, der beim Einbauen auffiel: keine der bestehenden Aktionen (Sperren/Entsperren/Soft-Delete/Abo) zeigte ihren Fehlerfall bisher sichtbar an; jetzt über eine gemeinsame `aktionFehler()`-Hilfsfunktion für alle Aktionstypen einheitlich gelöst, nicht nur für Hard-Delete).
- **End-to-end verifiziert** (nicht nur HTTP 200 oberflächlich): Konto mit noch zugeordnetem Patienten → korrekt 400 mit der erwarteten Meldung; Konto ohne Patienten → 200, Konto tatsächlich aus der DB verschwunden, korrekter `admin_audit_log`-Eintrag (`aktion="konto_hart_geloescht"`); Versuch, das eigene Konto zu löschen → korrekt 400 blockiert.

## Leistungskatalog-Aktualisierung auf Stand 01/2026 (pflegepilot_v3 only, 2026-08-01)

Betreiber hat drei offizielle BMG-Quelldokumente bereitgestellt (`BMG_Ratgeber_Demenz_bf.md`, Stand 03/2026, plus `pflege2026.json`/`Pflegebeduerftig.json`/`pflegeleistungen_2026_strukturierte_daten.json`, alle Stand 01/2026, im Projekt-Wurzelverzeichnis abgelegt — nicht Teil des Codes, reine Abgleichs-Quelle) zum Abgleich von `static_data/katalog.py` (dort stand noch "Stand: 2025").

- **Betroffen ausschließlich die Kategorie "Pflegekasse (SGB XI)"** (22 Einträge, Zeilen 1–350) — die übrigen Kategorien (Sozialhilfe, Wohnen & Bauen, Landesleistungen) werden von den bereitgestellten BMG-Dokumenten nicht abgedeckt, blieben unverändert. Der Demenz-Ratgeber lieferte inhaltlich keine neuen/abweichenden Zahlen gegenüber den drei JSON-Dateien (gegengeprüft), aber ein neueres Datum (03/2026 vs. 01/2026) — beide Stände sind intern konsistent.
- **Aktualisierte Beträge**: Pflegegeld (§ 37), Pflegesachleistung (§ 36), Tages-/Nachtpflege (§ 41), vollstationäre Pflege (§ 43, **jetzt auch Pflegegrad 1 mit 131 €** — vorher fehlte Grad 1 im Katalog komplett, `pflegegrad_min` von 2 auf 1 korrigiert), Wohngruppen-Zuschlag (§ 38a, 214 €→224 €), Behinderteneinrichtungen-Ergänzungsleistung (§ 43a, 266 €→278 €).
- **Verhinderungspflege/Kurzzeitpflege neu formuliert**: beide sind seit 07/2025 real in den bereits bestehenden `pk_jahresbetrag`-Eintrag (gemeinsamer Jahresbetrag, 3.539 €) zusammengeführt — die beiden ursprünglichen Einzel-Einträge trugen aber noch ihre alten, eigenständigen Jahresbudgets (1.612 €/1.774 €) im `betrag`-Feld. Jetzt korrekt als "Teil des gemeinsamen Jahresbetrags" mit den echten Unter-Grenzen (nahe Angehörige: 2-Faches des monatlichen Pflegegelds, Aufstockung bei Kostennachweis möglich) formuliert, `pk_jahresbetrag` selbst von "neu ab 07.2025" auf "seit 07/2025" (jetzt geltendes Recht, nicht mehr Ankündigung) umformuliert. Tag `neu2025` entfernt (keine anderen Code-Referenzen darauf, geprüft).
- **Inhaltliche Präzisierungen ergänzt** (nicht nur Zahlen, auch Nuancen aus den Quelldokumenten, die vorher fehlten): technische Pflegehilfsmittel haben tatsächlich einen 10 %-Eigenanteil (max. 25 € ab 18 Jahren), nicht "100 % Kostenübernahme" wie zuvor formuliert; DiPA sind eigentlich zwei getrennte Beträge (bis 40 €/Monat App + bis 30 €/Monat Unterstützungsleistung, nicht "bis 50 €" wie zuvor); Rentenversicherungsbeiträge und Arbeitslosenversicherungsbeiträge für Pflegende bekamen konkrete Beträge statt der bisherigen vagen "Abhängig von..."/"Beitragsübernahme"-Formulierung; die vierteljährliche Beratungsbesuch-Frequenz bei Pflegegrad 4–5 ist tatsächlich optional, nicht verpflichtend wie zuvor dargestellt.
- **Bewusst nicht angefasst**: `static_data/pflegegrad_regeln.py` (die 5-Fragen-Schätzheuristik des Interview-Assistenten) — die Quelldokumente liefern keine Punkt-Schwellenwerte, nur die Gewichtung der 6 offiziellen Begutachtungsmodule in Prozent, und unsere Heuristik war ohnehin nie als exakte Nachbildung des amtlichen Begutachtungsinstruments gedacht (siehe Modul-Docstring: "bewusst grob").
- **`pflegepilot_alpha_v2/pflegepilot/katalog.py` hat exakt dieselben veralteten 2025er-Werte** (geprüft, gleiche Struktur) — auf ausdrücklichen Betreiber-Wunsch NICHT mit-aktualisiert, nur `pflegepilot_v3` betroffen.
- **Wichtige Nebenwirkung beim Deploy, vorab verifiziert**: `katalog_watch.py` (T14, siehe oben "Proaktiver Server-Mailversand erweitert") vergleicht `KATALOG` beim App-Start gegen die `katalog_snapshots`-Tabelle und **verschickt automatisch eine E-Mail an jeden Nutzer (und ggf. dessen Patienten), der eine der geänderten Leistungen einem Patienten zugewiesen hat**. Das wurde lokal gezielt nachgestellt (Snapshot-Zeilen auf die alten Werte zurückgesetzt, `_sync_und_benachrichtigen()` erneut angestoßen) — die Änderungserkennung griff korrekt für beide getesteten Einträge (`pk_pflegegeld`, `pk_stationaer`), inkl. korrektem `email_log`-Eintrag (`typ="katalog_aenderung"`). **Das bedeutet: nach dem Deploy auf die NAS gehen beim ersten Start echte Benachrichtigungsmails an betroffene Bestandskunden raus** — kein Bug, sondern genau der beabsichtigte Zweck dieses Features, aber ein bewusster Zeitpunkt für den Deploy sollte gewählt werden.

## E-Mail-Bündelung + HTML-Design für alle proaktiven Mails (pflegepilot_v3 only, 2026-08-01)

Direktes Betreiber-Feedback nach dem Katalog-Update-Deploy: 9 Einzelmails für eine Änderungsrunde waren eine "Flut", und die Mails waren reiner Text ohne Wiedererkennungswert. Auf Rückfrage hat sich der Betreiber für die aufwendigere Variante entschieden: HTML-Design für **alle 7** proaktiven Mailtypen, nicht nur die Katalog-Mail.

- **Ursache der Flut gefunden und behoben**: `katalog_watch.py: _sync_und_benachrichtigen()` rief für jeden geänderten `KATALOG`-Eintrag sofort `_benachrichtige_betroffene()` auf, die unabhängig ihre eigene Empfängerliste aufbaute und verschickte — bei N geänderten, beim selben Nutzer hinterlegten Leistungen also N separate Mails an dieselbe Person. Umgebaut: erst werden **alle** Änderungen eines Durchlaufs gesammelt, danach genau **eine** Mail je Empfänger mit einer `aenderungs_box()` pro geänderter Leistung gebaut (neue Funktionen `_benachrichtige_betroffene_gesammelt()`/`_sende_gesammelte_aenderungsmail()`). Betreff passt sich an (`„{Name}“` bei genau einer Änderung, `"N Änderungen im Leistungskatalog"` bei mehreren). Lokal verifiziert: 3 gleichzeitig geänderte, bei einem Testkonto hinterlegte Leistungen erzeugten nachweislich nur **einen** SMTP-Versandversuch und **einen** `email_log`-Eintrag (vorher wären es 3 gewesen).
- **Neues Modul `app/email_templates.py`**: gemeinsame HTML-Hülle (`render_email()`) + Bausteine (`absatz()`, `liste()`, `aenderungs_box()` für Vorher/Nachher-Vergleiche, `magic_link_reihe()` für mehrere Button-Links nebeneinander). Tabellenbasiertes Layout mit durchgängig Inline-Styles (kein `<style>`-Block als Basis) für Kompatibilität mit Outlook Desktop, das externes/`<style>`-CSS größtenteils ignoriert. Farben an das bestehende App-Design angelehnt (`#1e293b` = dasselbe Slate-800 wie `buttonStyles.primary` im Frontend). Kein Bild-Logo (keins im Projekt vorhanden) — bewusst eine Text-Wortmarke "MeinPflegeFuchs", robuster gegen Bild-Blockierung in Mail-Clients. Kein Dark-Mode-Handling (E-Mail-Client-Unterstützung dafür ist unzuverlässig) — durchgehend helles Design mit hohem Kontrast. **Sicherheitsregel**: jeder Baustein escaped intern per `html.escape()` (`esc()`-Hilfsfunktion) — Pflicht, da u. a. Nutzernamen, Aufgaben-Titel und Patientennamen echte Nutzereingaben sind, die sonst HTML in die Mail injizieren könnten.
- **`email_util.py: send_email()`** bekam einen neuen optionalen `html`-Parameter — gesetzt, wird `MIMEMultipart("alternative")` mit Text- **und** HTML-Teil verschickt (Text bleibt Pflicht-Fallback für Text-only-Clients/Spamfilter), sonst wie bisher reines `MIMEText`.
- **Alle 7 Call-Sites umgestellt** (`routers/auth.py`, `reminder_scheduler.py` ×4, `katalog_watch.py`, `umkreis_favoriten_watch.py`) — jeweils der bestehende Plain-Text-Body unverändert als Fallback, dazu ein HTML-Block aus den `email_templates`-Bausteinen. Die Antragsstatus-Erinnerung (3 Magic-Links) nutzt `magic_link_reihe()` für drei nebeneinanderliegende Buttons statt eines einzelnen CTA.
- **Visuelle Abnahme über Artifact-Vorschauen statt Screenshot** (kein Browser in dieser Umgebung verfügbar): drei repräsentative HTML-Bodies (Katalog-Änderung mit mehreren `aenderungs_box()`, Antragsstatus mit 3 Buttons, Passwort-Reset als einfachster Fall) wurden direkt im laufenden Container gerendert und als private Artifacts veröffentlicht, damit der Betreiber sie tatsächlich sehen und freigeben kann, bevor deployt wird — Claude selbst kann HTML-Mails in dieser Umgebung nicht visuell prüfen, nur strukturell.
- **Bewusst nicht gebaut**: Bulletproof-Button-VML-Hack für Outlook Desktop (Buttons bleiben dort optisch etwas schlichter, aber funktional), echtes Dark-Mode-Handling.
- **Nachbesserung nach Sichtung der Vorschauen**: Betreiber-Feedback "es fehlt die korrekte Anrede aus dem Vornamen, die Mail ist etwas plump, hier fehlt das freundliche Auftreten von uns". Zwei Probleme behoben: (1) `Nutzer` hat anders als `Patient` kein eigenes `vorname`-Feld, nur ein freies `name`-Textfeld — neue Hilfsfunktion `email_templates.vorname_aus(name, fallback)` extrahiert das erste Wort daraus (Fallback: `benutzername`), einheitlich an allen 7 Stellen verwendet; die Katalog-Änderungsmail und die Umkreis-Favoriten-Mail hatten zuvor **gar keine** Anrede ("Hallo," ohne Namen). (2) Die Begrüßung war als Satzanfang in den ersten Fließtext-Absatz eingequetscht ("Hallo Max, kurzer Check-in für heute: ...") — jetzt eine eigene Begrüßungszeile (`email_templates.gruss()`, "Hallo {Vorname}! 👋") vor dem eigentlichen Inhalt, plus wärmer formulierte Texte (z. B. "Nicht vergessen: die Aufgabe ... ist morgen fällig" statt "folgende Aufgabe ist morgen fällig"). Bei der Katalog-Änderungsmail ist der Empfänger nicht immer der Nutzer selbst (kann auch der Patient mit eigener hinterlegter E-Mail sein) — die Anrede wird deshalb korrekt je Empfänger-Adresse zugeordnet (`empfaenger_vorname`-Dict in `katalog_watch.py`), nicht pauschal der Nutzername verwendet.