feat: implement database reset and demo population scripts with tests

README.md

@@ -1,4 +1,4 @@
-# KIBU – Schritte 1 bis 3
+# KIBU – Kinder-Betreuung Online
 
 Lokale Web-App für die Kinderbetreuung mit Next.js, TypeScript und einer echten PostgreSQL-Datenbank. Keine externen Dienste, Fonts oder Bild-Uploads. Kinderkarten verwenden Initialen.
 
@@ -99,16 +99,60 @@ docker compose up -d --wait
 
 Das benannte Volume `kibu_kibu_postgres` erhält die Daten bei Neustarts. **Nicht** `docker compose down -v` verwenden, wenn Daten erhalten bleiben sollen. Regelmäßige verschlüsselte Backups sind vor realem Einsatz erforderlich.
 
+## Testinstanz leeren oder neu befuellen
+
+**Achtung: unwiderruflich, nur fuer lokale Testdatenbanken!** Vorher die App
+beenden. Beide Befehle loeschen alle Kinder, Wochen-/Tagesplaene, Anwesenheit,
+Abholberechtigungen, Alleingehregeln, den gesamten Audit-Verlauf,
+Aufnahmerunden, Anmeldungen, Limits, Betreuungskonten und Sitzungen.
+Eigene Slots werden durch die vier aktiven Standardslots ersetzt.
+Schema, angewendete Migrationen und die lokale `.env` bleiben erhalten.
+Der Audit-Loeschschutz wird nur innerhalb der Reset-Transaktion kurz aufgehoben;
+bei einem Fehler wird die gesamte Leerung zurueckgerollt.
+
+```powershell
+# Nur leeren, noch ohne neuen Zugang oder Demokinder:
+npm run db:clear -- --confirm-reset
+
+# Leeren, neuen Zugang erstellen und 12 fiktive Kinder mit Verlauf anlegen:
+npm run db:reset -- --confirm-reset
+```
+
+Ohne `--confirm-reset` wird nichts geloescht. Remote-Datenbankadressen und
+PostgreSQL-Verwaltungsdatenbanken werden abgelehnt. Die Adresse allein ersetzt
+keine Pruefung des Ziels: auch eine lokale Portweiterleitung darf nicht auf
+Produktivdaten zeigen.
+
+`db:reset` fuehrt nach dem Leeren die vorhandenen Befehle `db:setup` und
+`db:seed` aus. Ein neues zufaelliges Passwort erscheint im Terminal; wenn in
+`.env` `BOOTSTRAP_EMAIL`/`BOOTSTRAP_PASSWORD` gesetzt sind, werden diese benutzt.
+Alte Passwoerter und Sitzungen funktionieren danach nicht mehr. Die Demodaten
+umfassen Kinder, Wochenplaene, Tagesabweichungen, Kontakte, Alleingehregeln und
+zwei Wochen Anwesenheitsverlauf; Aufnahmerunden bleiben leer.
+
+Nach `db:clear` bei Bedarf `npm run db:setup` und `npm run db:seed` einzeln
+ausfuehren. `db:seed` allein ist weiterhin nicht destruktiv und ueberschreibt
+keine vorhandenen Kinder. Schlaegt die Neueinrichtung nach erfolgreichem Leeren
+fehl, bleibt die Instanz leer bzw. teilweise eingerichtet; Ursache beheben und
+`db:setup`/`db:seed` erneut ausfuehren. Anschliessend die App wieder starten.
+
 ## Prüfen
 
 ```powershell
 npm test
 npm run test:db
+npm run test:reset
 npm run build
 ```
 
 `test:db` benötigt eine eingerichtete Datenbank. Eigene Kinder-/Audit-Testdatensätze werden innerhalb von Transaktionen geprüft und vollständig zurückgerollt. Der Paralleltest verwendet eine eigene kurzlebige Aufnahmerunde und entfernt diese samt Anmeldungen im Anschluss. Bestehende Demodaten bleiben erhalten. Geprüft werden unter anderem Korrekturen, Versionskonflikte, Vorher-/Nachher-Protokollierung, unveränderliches Audit-Log, Berechtigungen, Slots, Anmeldungen, konkurrierende Auslosungen und einmalige Übernahme. Unit-Tests prüfen exakte Fenstergrenzen und die gleichberechtigten Auswahlpfade kleiner Ziehungen. `npm run typecheck` prüft TypeScript ohne Build.
 
+`test:reset` erstellt eine eigene zufaellig benannte lokale Testdatenbank und
+entfernt ausschliesslich diese wieder. Der Datenbankzugang benoetigt dafuer
+`CREATEDB` (beim lokalen Compose-Zugang vorhanden). Der Test prueft Schutzabfragen,
+vollstaendige Leerung, Standardslots, erneute Demo-Befuellung, neue Zugangsdaten
+und den nach dem Reset wieder aktiven Audit-Loeschschutz.
+
 ## Betriebsgrenze
 
 Diese Version ist für den lokalen Testbetrieb gedacht, nicht zur unveränderten Veröffentlichung im Internet. Entwicklungs- und Produktionsserver binden standardmäßig nur an `127.0.0.1`. Für einen echten Einsatz mit Kinderdaten sind unter anderem HTTPS, datenschutzgerechte Betriebs-/Löschkonzepte einschließlich Audit-Daten, Backup/Restore und individuelle Betreuungszugänge erforderlich. Bei HTTPS `SESSION_SECURE=true` setzen. Der erste Zugang ist kein öffentliches Standardpasswort.