Mannschaftskasse

Interne Web-App für die Strafen- und Mannschaftskasse unseres Fußballteams. Zwei Kassenwarte verwalten mit einem gemeinsamen Passwort Strafen, Kisten-Strafen, Zahlungen und den Kassenbestand. Läuft auf Smartphone, Tablet und PC, komplett auf Deutsch.

Inhalt

1. Einrichtung nur über Vercel (empfohlen)
2. Funktionen
3. Regeln, wie die App rechnet
4. Technik und Architektur
5. Sicherheit
6. Umgebungsvariablen
7. Datenbankmigrationen
8. Passwort ändern
9. Sicherung und Wiederherstellung
10. Lokale Entwicklung und Tests
11. Fehlerbehebung
12. Bekannte Grenzen

Einrichtung nur über Vercel (empfohlen)

Ihr braucht dafür nur einen Browser, kein Terminal und kein Node.js. Alles passiert in Vercel; die Datenbank (Supabase) wird direkt aus Vercel heraus angelegt.

Was beim Deployen automatisch passiert: Beim Build auf Vercel (Produktion) richtet die App die Datenbank selbst ein bzw. aktualisiert sie: Tabellen, Sicherheitsregeln (RLS), Löschschutz, die 21 Spieler und der Strafenkatalog. Es werden keine Zahlungen, Strafen oder Kassenstände erfunden. Der Vorgang ist wiederholbar und verändert vorhandene Daten nicht.

Schritt 1: Projekt in Vercel

Euer Repo ist bereits mit Vercel verbunden (Adresse kasse-jade.vercel.app). Falls nicht: bei vercel.com Add New → Project, das Repo Wang20923/Kasse importieren und Deploy klicken. Das erste Deployment klappt auch ohne Datenbank; die App zeigt dann auf der Login-Seite an, was noch fehlt.

Schritt 2: Datenbank verbinden

1. Im Vercel-Projekt oben auf Storage gehen.
2. Create Database (bzw. „Browse Marketplace“) wählen, dann Supabase.
3. Region Frankfurt (eu-central-1) wählen, Namen vergeben, anlegen.
4. Die Datenbank mit dem Projekt Kasse verbinden (mindestens für die Umgebung Production).

Vercel trägt die Verbindungsdaten (POSTGRES_URL, POSTGRES_URL_NON_POOLING und weitere) automatisch als Umgebungsvariablen ein. Ihr müsst nichts kopieren.

Ihr habt schon ein eigenes Supabase-Projekt? Dann statt der Integration unter Settings → Environment Variables die Variable DATABASE_URL mit der „Transaction pooler“-Verbindung aus Supabase (Button Connect) anlegen.

Schritt 3: Gemeinsames Passwort festlegen

1. Im Vercel-Projekt Settings → Environment Variables.
2. Neue Variable: Name KASSE_PASSWORD, Wert = euer gemeinsames Passwort (mindestens 12 Zeichen, am besten ein kurzer Satz).
3. Umgebung: Production (bei Bedarf auch Preview). Die Option Sensitive aktivieren, dann kann den Wert später niemand mehr im Dashboard auslesen.
4. Speichern.

Das Passwort steht damit weder im Code noch in der Datenbank. Der Server leitet daraus beim Start einen scrypt-Schlüssel ab und prüft jeden Login dagegen.

Schritt 4: Neu deployen

Deployments → beim obersten Eintrag auf ⋯ → Redeploy. Neue Umgebungsvariablen werden nur bei einem neuen Deployment übernommen.

Im Build-Log seht ihr dann z. B.:

[Datenbank] Verbunden mit aws-0-eu-central-1.pooler.supabase.com:5432
[Datenbank] ✔ angewendet: 0001_schema.sql
[Datenbank] ✔ angewendet: 0002_seed.sql

Schritt 5: Loslegen

1. https://kasse-jade.vercel.app öffnen (bzw. eure eigene Domain), mit dem Passwort anmelden, optional den eigenen Namen angeben.
2. Einstellungen: Anfangsbestand der Kasse eintragen (aktueller Bargeld- oder Kontostand). Die Zahlungsfrist (14 Tage) ist vorbelegt.
3. Spieler: Liste prüfen. In der vorgegebenen Liste kommen Moritz und Willem jeweils nur einmal vor. Gibt es im Team zwei, den zweiten über „Spieler hinzufügen“ mit Kennzeichnung (z. B. Nachname) anlegen und beim ersten ebenfalls eine Kennzeichnung ergänzen.
4. Auf dem Handy „Zum Startbildschirm hinzufügen“, dann startet die App wie eine normale App.

Schritt 6: Daten aus der alten Strafenkasse übernehmen

1. Die alte Strafenkasse öffnen und oben auf Export klicken. Dabei wird eine Datei strafenkasse-export-….json gespeichert. (Ein PDF oder Screenshot der alten Seite reicht nicht: Darin stehen keine Daten, nur die Oberfläche bzw. der Programmcode.)
2. In der neuen App Einstellungen → Daten aus der alten Strafenkasse übernehmen → Export-Datei auswählen.
3. Spieler-Zuordnung prüfen: Namen werden automatisch zugeordnet (Groß-/Kleinschreibung egal). Unbekannte Namen werden neu angelegt, gibt es einen Namen doppelt (z. B. zwei Moritz), muss man selbst wählen.
4. Fälligkeit für offene Strafen wählen (Standard: neue Frist ab Importtag).
5. Kasse: Ist das Geld der bereits bezahlten Strafen schon in eurem Anfangsbestand enthalten, das Häkchen setzen; dann wird eine Gegenbuchung angelegt, damit nichts doppelt zählt.
6. Vorschau prüfen und Import starten.

So wird übernommen:

Alte Strafenkasse	Neue App
Geld-Eintrag, offen	Geldstrafe mit Betrag, Datum und Kommentar
Geld-Eintrag, bezahlt	Geldstrafe plus Zahlungseingang zum damaligen Bezahldatum
Bier-Eintrag (Kiste)	Kisten-Strafe; bei 2 Kisten zwei Einträge, bezahlte als „erledigt“
Papierkorb	wird nicht übernommen
Strafarten der alten App	werden nicht in den Katalog übernommen, der Name bleibt aber bei jeder Strafe erhalten

Der Import läuft in einer Transaktion (ganz oder gar nicht), wird im Verlauf protokolliert und kann gefahrlos wiederholt werden: Bereits übernommene Einträge werden erkannt und nicht doppelt angelegt.

Optional

• Eigene Domain: Vercel → Settings → Domains, z. B. kasse.euer-verein.de hinzufügen und den angezeigten DNS-Eintrag beim Domain-Anbieter setzen. HTTPS kommt automatisch.
• Repo privat stellen: Das GitHub-Repo ist derzeit öffentlich. Geheimnisse liegen keine darin, aber z. B. die Spielernamen stehen in db/migrations/0002_seed.sql. Auf GitHub unter Settings → General → Danger Zone → Change visibility auf „Private“ stellen; Vercel funktioniert damit genauso.
• Produktions-Branch: Vercel baut die Produktivversion aus dem Standard-Branch des Repos (aktuell claude/vibrant-heisenberg-2dblke). Wer lieber main hat, benennt den Branch auf GitHub um und stellt in Vercel unter Settings → Git → Production Branch denselben Namen ein. Vorschau-Deployments aus anderen Branches verändern die Datenbank nicht.

Funktionen

Bereich	Was geht
Dashboard	Kassenbestand, offene Schulden, offene und überfällige Strafen, Einnahmen Monat und Jahr, offene Kisten, Rangliste der höchsten Schulden, letzte Buchungen, großer Button „Strafe eintragen“
Spieler	21 Spieler vorangelegt, Namen und Kennzeichnung bearbeitbar, hinzufügen, deaktivieren (Daten bleiben), Profil mit Schulden, Zusatzgebühren, Zahlungen, Kisten und kompletter Historie
Strafe eintragen	Schnellerfassung fürs Handy: Datum und Anlass bleiben stehen, mehrere Spieler auf einmal, automatische Berechnung, Zusammenfassung vor dem Speichern, Warnung bei möglichen Doppelbuchungen, mehrere Strafen nacheinander ohne Neustart
Offene Schulden	Filter (offen, überfällig, bald fällig, bezahlt), Suche, Sortierung nach Name, Restschuld und Fälligkeit, Summenzeile, direkter Sprung ins Profil, Button „Schulden kopieren“ für WhatsApp (eine Zeile pro Spieler, z. B. Paul – 5,00 €, alphabetisch, aktuelle Restschuld inkl. manueller Zusatzgebühren und Teilzahlungen, ohne Kisten)
Kasse und Zahlungen	Tatsächlicher Kassenbestand, Zahlungen erfassen (automatisch verteilt oder gezielt pro Strafe, Teilzahlungen), Vorschau der Verteilung, Kassenkorrekturen, Einnahmen pro Monat und pro Spieler, Storno mit Begründung
Kisten-Strafen	Eigene Übersicht, offen/erledigt/storniert, als erledigt markieren mit Datum und Notiz
Strafenkatalog	Strafen hinzufügen, bearbeiten, aktivieren, deaktivieren, Geld oder Kiste, Berechnungsart, Auswärts-Faktor, Bindung an Training oder Spiel, Doppelbuchungsschutz
Verlauf	Lückenloses, unveränderbares Protokoll mit Zeitpunkt und Admin-Name, filterbar
Einstellungen	Zahlungsfrist, „Bald fällig“-Schwelle, Anfangsbestand, Verspätungsregel, angemeldete Geräte, Backup und Wiederherstellung, Import aus der alten Strafenkasse

Regeln, wie die App rechnet

Alle Geldbeträge werden als ganze Cent gespeichert und gerechnet, nie als Gleitkommazahl. Alle Kalenderdaten beziehen sich auf Europe/Berlin.

Strafen

• Zu spät kommen: 1 € pro angefangene 2 Minuten. Formel: aufgerundet(Minuten / 2) × 1 €. 1 oder 2 Min. = 1 €, 3 oder 4 Min. = 2 €, 5 Min. = 3 €, 10 Min. = 5 €. 0 Minuten erzeugen keine Strafe. Betrag und Intervall sind in den Einstellungen bzw. im Katalog änderbar.
• Unabgemeldet fehlen: zwei getrennte Strafen, Training 25 €, Spiel 50 €. Die Training-Variante lässt sich nur mit Anlass „Training“ speichern, die Spiel-Variante nur mit „Heimspiel“ oder „Auswärtsspiel“.
• Unnötige gelbe Karte: 5 € pro Karte, die Anzahl wird mitgegeben (3 Karten = 15 €). Auch Einwurf, Ankle Breaker, Tor verfehlt und Fangzaun sind „pro Vorfall“.
• Nicht duschen: eine einzige Vorlage mit 2 €. Wird beim Erfassen „Auswärtsspiel“ gewählt, wird der Betrag verdoppelt (4 €). Es gibt bewusst keine zweite Vorlage „Nicht duschen auswärts“, damit nicht versehentlich Grund- und Auswärtsstrafe zusammen gebucht werden.
• Vergessene Gegenstände: „Schienbeinschoner vergessen“ und „Fußballschuhe vergessen“ sind spezifisch, „Große Dinge“ und „Kleinere Dinge“ allgemein. Trifft am selben Tag beim selben Spieler eine allgemeine auf eine spezifische (oder eine andere allgemeine) Strafe, zeigt die App eine Warnung: Die spezifische hat Vorrang. Speichern geht nur nach ausdrücklicher Bestätigung, dass es ein eigener Verstoß ist. Dieselbe Strafe zweimal am selben Tag wird ebenfalls als mögliches Duplikat gemeldet.
• Kisten-Strafen (Rote Karte, Eigentor, Geburtstag, In der Zeitung) haben keinen Geldwert, werden getrennt gespeichert (Datum, Anlass, Kommentar, Status offen/erledigt) und beeinflussen weder Schulden noch Kasse.

Jede gespeicherte Strafe friert Bezeichnung, Einzelbetrag, Anzahl, Minuten, Faktor, und Fälligkeit ein. Spätere Änderungen am Katalog oder an den Einstellungen ändern bestehende Strafen nicht.

Zahlungsfrist

1. Fällig ist eine Geldstrafe 14 Tage nach dem Strafdatum (Standard, pro Strafe änderbar). Strafe am 01.10. ist fällig am 15.10.
2. Eine Zahlung am Fälligkeitstag ist noch rechtzeitig. Ab dem Folgetag gilt die Strafe als überfällig.
3. Überfällig ist nur ein Status. Es kommt nie automatisch eine Gebühr dazu, egal wie lange die Strafe offen ist.
4. Restschuld = Strafbetrag − bisherige Zahlungen (src/lib/domain/balance.ts, getestet in tests/unit/balance.test.ts).

Zusatzgebühren (nur manuell)

Zusatzgebühren entstehen ausschließlich, wenn ein angemeldeter Administrator sie einträgt:

1. Auf Offene Schulden oder im Spielerprofil auf „Zusatzgebühr“ tippen.
2. Spieler wählen, Betrag eingeben (bis 1.000 €), optional einen Grund.
3. „Weiter“ zeigt eine Zusammenfassung mit der offenen Geldschuld vorher und nachher. Gespeichert wird erst mit „Zusatzgebühr bestätigen“. Abbrechen oder Zurück speichert nichts.
4. Wurde für denselben Spieler am selben Tag schon eine gleich hohe Zusatzgebühr eingetragen, muss zusätzlich bestätigt werden, dass es eine eigene Gebühr ist. Ein Doppelklick speichert nie doppelt.

Eine Zusatzgebühr ist ein eigener Posten mit dem Kennzeichen „manuell“: Sie erhöht die offene Geldschuld, erscheint in der Schuldenübersicht (Spalte Zusatzgebühren), im Text von „Schulden kopieren“, in der Kasse unter „Offene Geldforderungen“ und „Zusatzgebühren“ und kann wie eine Strafe ganz oder in Teilen bezahlt, bearbeitet oder mit Begründung storniert werden. Wer sie wann für wen mit welchem Grund eingetragen hat, steht im Spielerprofil und im Verlauf (Filter „Zusatzgebühren“).

Umstellung von automatischen auf manuelle Zusatzgebühren

Frühere Versionen haben nach Fristablauf automatisch 0,50 € pro Woche berechnet. Diese Gebühren waren nie eigene Buchungen, sondern wurden aus einem Gebührensatz pro Strafe abgeleitet. Die Migration 0003_manual_surcharges.sql setzt diesen Satz bei allen Strafen und in den Einstellungen auf 0 und protokolliert die Umstellung im Verlauf (Eintrag „System“). Danach gilt:

• Strafbeträge, Fälligkeiten, Spieler, Zahlungen und Zahlungszuordnungen bleiben unverändert, der Kassenbestand auch.
• Offene Schulden bestehen nur noch aus Strafbetrag minus Zahlungen (plus manuell eingetragene Zusatzgebühren).
• Wer früher eine automatische Gebühr schon bezahlt hat, hat jetzt bei dieser Strafe mehr bezahlt als den Strafbetrag. Die Zahlung bleibt so, wie sie ist, die Strafe zeigt den Betrag als Überzahlung, und die Kasse weist die Summe gesondert aus. Eine Rückzahlung oder Verrechnung passiert nicht automatisch. Wer das möchte, bucht eine Kassenkorrektur.
• Die alten Spalten bleiben aus Kompatibilitätsgründen bestehen, ein Datenbank-Trigger hält sie dauerhaft auf 0. Auch das Wiederherstellen einer alten Sicherung bringt keine automatischen Gebühren zurück.

Auf Vercel läuft die Migration beim nächsten Produktions-Deploy automatisch.

Zahlungen verteilen

• Automatisch: Der Betrag tilgt zuerst die Strafe mit der frühesten Fälligkeit (bei Gleichstand früheres Strafdatum, dann frühere Erfassung), jeweils bis zu deren Restschuld am Zahlungstag. Manuelle Zusatzgebühren werden dabei wie Strafen behandelt. Der Rest geht an die nächste Strafe. So werden überfällige Strafen zuerst beglichen.
• Bestimmte Strafen: Beträge pro Strafe frei festlegen, Teilzahlungen möglich.
• Vor dem Speichern zeigt die App für jede Strafe „offen vorher / Zahlung / offen danach“, erst nach „Zahlungseingang bestätigen“ wird gebucht.
• Mehr als die offene Restschuld kann nicht gebucht werden. Zusätzliches Geld (Spende o. ä.) bitte als Kassenkorrektur erfassen.
• Schutz vor Doppelbuchungen: Jedes Formular hat eine eindeutige Anfrage-ID, ein doppelt abgeschicktes Formular (Doppelklick, Netzwerk-Wiederholung) bucht nichts doppelt. Eine weitere Zahlung desselben Spielers über denselben Betrag am selben Tag muss ausdrücklich bestätigt werden. Buchungen pro Spieler laufen gesperrt in einer Transaktion, sodass beide Admins gleichzeitig arbeiten können, ohne eine Strafe zu überzahlen. Hat der andere Admin zwischen Vorschau und Speichern gebucht, meldet die App das und zeigt die neue Verteilung.

Kassenbestand

Kassenbestand = Anfangsbestand + bestätigte (nicht stornierte) Zahlungen + Kassenkorrekturen

Offene Schulden zählen nicht als Einnahmen. Kisten-Strafen sind keine Geldbuchungen. Ausgaben (z. B. Getränke) werden als negative Kassenkorrektur mit Begründung erfasst.

Gleichnamige Spieler

Jeder Spieler hat eine eigene ID, alle Buchungen hängen an der ID, nicht am Namen. Zwei Spieler mit gleichem Namen sind erlaubt, brauchen aber eine unterschiedliche Kennzeichnung (z. B. Nachname, Rückennummer). Die App zeigt dann z. B. „Moritz (Torwart)“. Ohne Kennzeichnung lässt sich ein zweiter „Moritz“ nicht anlegen (das prüft auch die Datenbank).

Korrekturen statt Löschen

Strafen, Zahlungen, Kisten und Korrekturen werden nie gelöscht, sondern mit Begründung storniert. Die Datenbank verhindert Löschen per Trigger. Zahlungen und Korrekturen können nach dem Speichern nicht verändert werden (nur storniert und neu erfasst). Strafen können bearbeitet werden (Datum, Fälligkeit, Betrag, Kommentar), jede Änderung wird mit Vorher/Nachher und Grund protokolliert. Das Protokoll selbst ist unveränderbar.

Technik und Architektur

• Next.js 16 (App Router, Server Components, Server Actions), TypeScript, Tailwind CSS 4
• PostgreSQL bei Supabase, Zugriff ausschließlich serverseitig über pg (node-postgres) mit parametrisierten Abfragen
• Hosting bei Vercel (Region Frankfurt, siehe vercel.json)
• Tests mit Vitest; Integrationstests laufen gegen eine eingebettete PostgreSQL-Instanz (PGlite), dafür ist kein Datenbankserver nötig

db/migrations/          SQL-Migrationen (Schema, RLS, Trigger, Startdaten)
scripts/                migrate, hash-password, backup/restore
src/lib/domain/         Reine Rechenlogik: Geld, Datum, Strafen, Restschuld, Verteilung, Kasse
src/lib/validation.ts   Gemeinsame Eingabeprüfung (Client und Server)
src/server/auth/        Passwort-Hash, Sessions, Rate-Limit, Login
src/server/services/    Buchungslogik mit Transaktionen und Protokoll
src/app/actions/        Server-Aktionen (prüfen immer die Session)
src/app/(app)/          Seiten der App
src/components/         UI-Bausteine und Fach-Komponenten
src/proxy.ts            Erste Schutzschicht (Next.js Proxy, früher „Middleware“)
tests/                  Unit- und Integrationstests

Sicherheit

• Login: ein gemeinsames Passwort, serverseitig geprüft. Es liegt ausschließlich als geheime Umgebungsvariable KASSE_PASSWORD bei Vercel (verschlüsselt, als „Sensitive“ nicht mehr auslesbar), nie im Code und nie in der Datenbank. Der Server vergleicht über einen scrypt-abgeleiteten Schlüssel in konstanter Zeit. Wer das Passwort gar nicht bei Vercel hinterlegen will, kann stattdessen nur dessen scrypt-Hash als KASSE_PASSWORD_HASH setzen (npm run hash-password); der Hash hat Vorrang. Optional gibt jeder beim Login seinen Namen an, der im Verlauf erscheint.
• Sessions: zufälliges 256-Bit-Token im Cookie __Host-kasse_session (HttpOnly, Secure, SameSite=Lax, 30 Tage). In der Datenbank liegt nur der SHA-256-Hash des Tokens. Sessions lassen sich in den Einstellungen für andere Geräte beenden. Ändert ihr das Passwort, werden alle bestehenden Sessions automatisch ungültig.
• Brute-Force-Schutz: max. 5 Fehlversuche pro IP in 15 Minuten, zusätzlich max. 50 Fehlversuche insgesamt in 15 Minuten. Gezählt wird in der Datenbank, damit es auch über mehrere Serverless-Instanzen greift.
• Zugriffsschutz in drei Schichten: Proxy (ohne Cookie nur Login, API und POST → 401), jede Seite und jede Server-Aktion prüft die Session gegen die Datenbank, die API-Route ebenfalls. Server-Aktionen werden in Next.js zusätzlich per Origin-Prüfung gegen CSRF geschützt.
• Datenbank: Row Level Security ist auf allen Tabellen aktiv, ohne Policies für die öffentlichen Supabase-Rollen anon und authenticated; deren Rechte werden zusätzlich entzogen. Über die Supabase-API (anon key) ist also nichts lesbar oder schreibbar. Die App selbst verbindet sich serverseitig mit den Datenbank-Zugangsdaten, die nur in Vercel hinterlegt sind. Die von der Supabase-Integration zusätzlich angelegten Schlüssel (z. B. NEXT_PUBLIC_SUPABASE_*) verwendet die App nicht.
• HTTPS: Vercel liefert ausschließlich über HTTPS aus; die App leitet HTTP zusätzlich um und setzt HSTS.
• Header: X-Frame-Options: DENY, frame-ancestors 'none', nosniff, Referrer-Policy, Permissions-Policy, X-Robots-Tag: noindex.
• Keine Geheimnisse im Repository: .env* ist in .gitignore, nur .env.example ohne Werte ist eingecheckt.

Umgebungsvariablen

Variable	Pflicht	Beschreibung
POSTGRES_URL	ja*	Wird von der Supabase-Integration in Vercel automatisch gesetzt (gepoolte Verbindung, für die App)
POSTGRES_URL_NON_POOLING	nein	Ebenfalls automatisch gesetzt; wird bevorzugt für Migrationen genutzt. Ist sie vom Build aus nicht erreichbar, nimmt die App automatisch die gepoolte Verbindung
DATABASE_URL	ja*	Alternative zu POSTGRES_URL für ein eigenes Supabase-Projekt (Transaction pooler, Port 6543). Hat Vorrang
MIGRATION_DATABASE_URL	nein	Eigene Verbindung nur für Migrationen und Backups (Session pooler, Port 5432)
KASSE_PASSWORD	ja**	Das gemeinsame Passwort, mind. 12 Zeichen, in Vercel als „Sensitive“
KASSE_PASSWORD_HASH	ja**	Alternative: nur der scrypt-Hash des Passworts (npm run hash-password). Hat Vorrang
DATABASE_SSL_CA	nein	Inhalt des Supabase-CA-Zertifikats für vollständige TLS-Prüfung (sonst verschlüsselt ohne Zertifikatsprüfung)
DATABASE_POOL_MAX	nein	Max. Datenbankverbindungen pro Serverinstanz, Standard 3
KASSE_MIGRATE_PREVIEW	nein	Auf 1 setzen, wenn auch Preview-Deployments Migrationen ausführen sollen (nur mit eigener Test-Datenbank sinnvoll)

* eine der beiden. ** eine der beiden.

Datenbankmigrationen

• Migrationen liegen in db/migrations/ und werden alphabetisch angewendet (0001_..., 0002_...).
• Auf Vercel automatisch: npm run build führt zuerst scripts/deploy-migrate.ts aus. Das läuft nur bei Produktions-Deployments auf Vercel. Schlägt die Migration fehl, wird das Deployment abgebrochen, damit nie eine App mit falschem Datenbankschema live geht; die bisherige Version bleibt dann online.
• Lokal oder manuell: npm run db:migrate.
• Angewendete Migrationen stehen in der Tabelle schema_migrations, jede Migration läuft in einer eigenen Transaktion.
• Neue Migration: neue Datei mit höherer Nummer anlegen, nie eine bereits angewendete Datei ändern. Jede neue Tabelle braucht enable row level security (ein Test prüft das) und die revoke-Anweisungen für anon und authenticated.

Passwort ändern

1. Vercel → Settings → Environment Variables → KASSE_PASSWORD bearbeiten (bei „Sensitive“: löschen und neu anlegen).
2. Deployments → Redeploy.
3. Alle bisherigen Sessions sind damit automatisch ungültig, beide Admins melden sich mit dem neuen Passwort an.

Sicherung und Wiederherstellung

Regelmäßig sichern! Verlasst euch im kostenlosen Supabase-Tarif nicht auf automatische Backups.

• Sichern: In der App unter Einstellungen → Datensicherung → Backup herunterladen. Ihr bekommt eine JSON-Datei mit allen Spielern, Strafen, Kisten, Zahlungen, Korrekturen, Einstellungen und dem Protokoll (ohne Sessions). Am besten nach jedem Monat oder vor größeren Änderungen.
• Wiederherstellen: In der App unter Einstellungen → Sicherung wiederherstellen die Datei auswählen, die Zusammenfassung prüfen, zur Bestätigung WIEDERHERSTELLEN eintippen. Das ersetzt alle aktuellen Daten durch den Stand der Sicherung; man bleibt angemeldet, und die Wiederherstellung wird im Verlauf protokolliert. Geht etwas schief, wird nichts verändert (eine Transaktion).
• Umzug auf eine neue Datenbank: neue Supabase-Datenbank in Vercel verbinden, neu deployen (legt das leere Schema an), anmelden und die Sicherung wie oben wiederherstellen.
• Per Kommandozeile (optional): npm run db:backup bzw. npm run db:backup -- restore <datei> --confirm, oder klassisch pg_dump.

Lokale Entwicklung und Tests

Nur nötig, wenn ihr am Code arbeiten wollt. Voraussetzung: Node.js 22.

git clone https://github.com/Wang20923/Kasse.git && cd Kasse
npm install
cp .env.example .env.local   # DATABASE_URL und KASSE_PASSWORD eintragen
npm run db:migrate
npm run dev                  # http://localhost:3000

npm run dev         # Entwicklungsserver
npm test            # Unit- und Integrationstests (ohne externe Datenbank)
npm run lint        # ESLint
npm run typecheck   # TypeScript
npm run build       # Produktions-Build
npm run check       # alles zusammen

Abgedeckt sind unter anderem: Verspätung 0 bis 11 Minuten, unabgemeldetes Fehlen bei Training und Spiel, mehrere gelbe Karten, Verdopplung beim Auswärtsspiel, Fristablauf und alle Grenzfälle um das Fälligkeitsdatum, keine automatischen Gebühren nach Fristablauf, manuelle Zusatzgebühren mit Bestätigung, Duplikatschutz und Protokoll, Umstellung bestehender Daten ohne Änderung von Strafen und Zahlungen, Teil- und Vollzahlung, parallele Buchungen, Doppelbuchungsschutz, Storno, Trennung von offenen Schulden und Einnahmen, Kassenbestand, Kisten ohne Geldwirkung, getrennte Verwaltung gleichnamiger Spieler (Moritz, Willem), Katalog- und Einstellungsänderungen ohne Rückwirkung, RLS auf allen Tabellen, Löschschutz, Login, Rate-Limit, Session-Ablauf und Zugriffsschutz für nicht angemeldete Nutzer.

GitHub Actions führt Lint, Typecheck, Tests und Build bei jedem Push aus (.github/workflows/ci.yml).

Fehlerbehebung

Problem	Lösung
Login-Seite zeigt „Einrichtung noch nicht abgeschlossen“	Die angezeigten Schritte abarbeiten (Datenbank verbinden, KASSE_PASSWORD setzen) und danach Redeploy
„Datenbank einrichten“ wird angezeigt	Die Datenbank ist verbunden, aber leer: Redeploy des Produktions-Deployments, dabei werden die Tabellen angelegt
„Datenbank nicht erreichbar“	Im Supabase-Dashboard prüfen, ob das Projekt pausiert ist (kostenlose Projekte pausieren nach längerer Inaktivität), dann fortsetzen
Deployment bricht mit „[Datenbank] Migration fehlgeschlagen“ ab	Verbindung prüfen (Supabase-Projekt aktiv? Integration mit „Production“ verbunden?), dann erneut deployen. Die vorherige Version bleibt solange online
Passwort geändert, aber das alte gilt noch	Nach dem Ändern der Variable ist ein Redeploy nötig
„Zu viele Fehlversuche“	15 Minuten warten; die Sperre gilt pro Gerät/IP

Bekannte Grenzen

• Beide nutzen dasselbe Passwort. Der Name im Verlauf ist eine Selbstangabe beim Login und kein Beweis, wer gebucht hat. Wer echte Nachvollziehbarkeit pro Person braucht, sollte auf zwei Konten umstellen.
• Kostenlose Supabase-Projekte werden nach längerer Inaktivität pausiert und müssen dann im Supabase-Dashboard wieder gestartet werden.
• Es gibt keine automatischen Erinnerungen per E-Mail oder WhatsApp an Spieler.
• Zahlungen können nicht im Voraus (als Guthaben) gebucht werden, sondern nur auf offene Strafen.