stammtisch-hersbruck/backend/README.md

# Kurbeler — Backend (PocketBase)

PocketBase-Instanz für Events, Läufe, Fahrer, Zeiten und Teams.

## Lokal starten

`.env` aus der Vorlage anlegen (die `.env` selbst steht in `.gitignore`):

    cp .env.example .env

und die Werte eintragen — `.env.example` beschreibt jede Variable. Dann:

    docker compose up -d --build

Admin-UI: http://127.0.0.1:8090/_/ — Login mit `SUPERUSER_EMAIL`/`SUPERUSER_PASSWORD`.

Damit das Frontend gegen diese Instanz läuft, in `../frontend/.env`
`PUBLIC_PB_URL=http://127.0.0.1:8090` setzen.

## Schema

Das Schema liegt als versionierte Migration in `pb_migrations/` und wird beim
Start automatisch angewendet. Es enthält die sechs fachlichen Collections
`users`, `teams`, `events`, `stages`, `riders`, `times`.

`1754400000_init_schema.js` ist ein Snapshot der produktiven Instanz. Er wurde
per `GET /api/collections` abgezogen und ruft `importCollections` mit
`deleteMissing = false` auf — die Migration legt an und aktualisiert, löscht
aber nichts, was nicht im Snapshot steht.

### Schema-Änderungen aus dem Admin-UI holen

`pb_migrations/` wird **nicht** in den Container gemountet — die Migrationen
kommen über `COPY` ins Image (siehe `Dockerfile`). Das ist Absicht: Ein
Bind-Mount überdeckt das Image-Verzeichnis, und auf einem Deployment-Host ohne
ausgechecktes Repo legt Docker dort ein leeres Verzeichnis an. PocketBase
findet dann keine Migration und startet mit einer Datenbank ohne Collections.

Die Kehrseite: Eine im Admin-UI erzeugte Migration liegt zunächst nur im
Container und muss von Hand herausgeholt werden:

    # Welche Dateien sind dazugekommen?
    docker compose exec pocketbase ls /pb/pb_migrations

    # Die neue Datei ins Repo kopieren und committen
    docker compose cp pocketbase:/pb/pb_migrations/<datei> ./pb_migrations/

Ohne diesen Schritt ist die Änderung beim nächsten `--build` verloren.

Ein frisch gestarteter Container hat damit dasselbe Schema wie die produktive
Instanz — aber **keine** Daten.

### Regeln: der Login-Vorspann ist Pflicht

Jede Regel, die `@request.auth.id` erwähnt, beginnt mit
`@request.auth.id != "" && (…)`. Das ist kein Stilmittel, sondern schließt ein
Loch:

**Eine leere Relation ist in PocketBase gleich dem leeren `@request.auth.id`
einer anonymen Anfrage.** `team.admins.id ?= @request.auth.id` ist damit für
jedes Team **ohne Admins** wahr — und ohne Admins ist jedes frisch angelegte
Team. Dasselbe gilt für jede optionale Relation: `created_by`, `stewards`,
`rider.user`.

Nachgewiesen an einer lokalen Instanz mit dem Schema aus diesem Repo: Ein
`POST` auf `/api/collections/riders/records` **ohne jeden Token** legte den
Fahrer an. Betroffen waren nach demselben Muster `teams` (update), `riders`,
`trails`, `trail_versions`, `trail_flags`, `trail_markers`, `trail_comments`,
`event_series` und `event_participants`.

`1754501700_rules_require_login.js` setzt den Vorspann vor jede betroffene
Regel. Er kann nichts erlauben, was vorher verboten war — er nimmt nur die
anonyme Anfrage heraus, die keine dieser Regeln je erfüllen sollte. Gelesen
werden die Regeln aus der Datenbank, eine Handänderung aus dem Admin-UI wird
also abgesichert und nicht überschrieben.

Nach dem Deploy einmal gegenprüfen — das muss scheitern:

    curl -X POST https://api.stammtisch-hersbruck.de/api/collections/riders/records \
      -H 'Content-Type: application/json' \
      -d '{"team":"<TEAM_ID>","name":"Test"}'

Wer eine neue Regel schreibt, setzt den Vorspann mit. Sonst reißt dasselbe
Loch an der nächsten Stelle wieder auf.

### `1754501300` scheitert auf einer frischen Datenbank

Bekannt und **nicht behoben**: Bei `docker compose up --build` mit leerem
`pb_data` legt der Snapshot `1754400000` die Collection `riders` bereits ohne
das Feld `event` an. `1754501300_event_participants.js` sucht danach mit
`findRecordsByFilter('riders', 'event != "")` und bricht mit
`unknown field "event"` ab — PocketBase startet dann gar nicht.

Auf der produktiven Instanz tritt das nicht auf, dort gibt es das Feld noch.
Angefasst wurde die Migration deshalb nicht; wer lokal von Null startet,
braucht diese eine Zeile:

    const existing = riders.fields.getByName('event')
        ? app.findRecordsByFilter('riders', 'event != ""', '', 0, 0)
        : []

## Hooks (`pb_hooks/`)

Serverseitiges JavaScript, das PocketBase beim Start lädt (`--hooksDir`). Wie
`pb_migrations/` kommt das Verzeichnis per `COPY` ins Image — eine Änderung
wirkt also erst nach `docker compose up -d --build`.

| Datei | Zweck |
|---|---|
| `clock.pb.js` | Uhrenabgleich für die Zeitnahme |
| `team_invites.pb.js` | `GET /api/team-invites/{token}`, `POST …/accept`, `POST …/join` |
| `team_invites_lib.js` | Gemeinsame Helfer der drei Einladungs-Routen |
| `directory.pb.js` | `GET /api/directory/users` — Benutzerverzeichnis des Superadmins |
| `directory_lib.js` | Helfer dazu |
| `mail_lib.js` | Absender, Vorlagen, Versand — alles, was Mails verschickt, geht hier durch |
| `notifications.pb.js` | Auslöser der Benachrichtigungen und der tägliche Versand |
| `notifications_lib.js` | Voreinstellungen, Empfängerkreis, Warteschlange |
| `views/invite.html` | Vorlage der Einladungsmail |
| `views/digest.html` | Vorlage der Tageszusammenfassung |

Vorlagen werden mit `$template.loadFiles(...).render(data)` gefüllt — Go's
`html/template`. Die Platzhalter stehen deshalb in `{{ }}` und werden dabei
escaped; Trailnamen und Kommentartexte kommen aus der Datenbank und dürfen
kein Markup einschleusen.

## Mails

SMTP wird im Admin-UI eingerichtet (Settings → Mail settings). Zwei
Umgebungsvariablen kommen dazu, beide in `.env.example` beschrieben:

| Variable | Wofür |
|---|---|
| `APP_URL` | Adresse des **Frontends**. Aus ihr entstehen die Links in Mails. |
| `APP_NAME` | Optional. Name in Betreff und Text; ohne sie steht dort „Kurbeler". |

`APP_URL` ist ausdrücklich nicht `settings().meta.appURL` — die zeigt auf
PocketBase selbst, und ein Einladungslink dorthin führte auf die API statt auf
die Seite, die das Konto anlegt. Sie ist auch nicht der `Origin` des
Aufrufers: Der steht unter dessen Kontrolle, und ein Link in einer Mail, den
ein Fremder auf seinen eigenen Server zeigen lassen kann, ist eine
Phishing-Vorlage mit unserem Absender darauf. Fehlt die Variable, verweigern
die Mail-Routen den Dienst.

### Einladung statt Passwort

`POST /api/team-invites/send` ist der Ersatz für „Konto anlegen" im Kader.
Dort tippte die Teamleitung Adresse **und Passwort** ein und musste dieses
Passwort anschließend irgendwie zum Fahrer bringen — über einen Kanal, den
niemand geplant hat. Sie kannte es außerdem.

Jetzt legt die Route eine persönliche Einladung an (`team_invites` mit
`email` und `rider`) und verschickt sie. Das Passwort entsteht erst beim
Empfänger auf `/invite/{token}`. Die Adresse ist dabei gebunden: Das Feld auf
der Seite ist gesperrt, und weil ein gesperrtes Feld nur eine Bitte ist, prüft
`/accept` sie noch einmal.

Die allgemeinen **Einladungslinks bleiben unverändert** — sie gelten jedem,
der sie hat, und lassen `email` und `rider` leer.

### Benachrichtigungen: eine Mail am Tag

Kein Auslöser verschickt eine Mail. Alle legen einen Eintrag in
`notifications`, und `cronAdd('notifications_digest', '0 6 * * *', …)` macht
daraus einmal täglich je Konto eine Zusammenfassung.

Das ist der ganze Punkt: Ein Trailkommentar, dem drei Antworten folgen, löste
sonst vier Mails aus. Ein Verein, der sich die nicht leisten kann, schaltet
nach drei Tagen alles ab.

Nebenwirkung, die zählt: Ein Fehler im Mailversand kann nie das Speichern
eines Events verhindern — der Auslöser schreibt nur in eine Tabelle.
Scheitert der Versand an ein Konto, bleiben dessen Einträge unversendet stehen
und sind am nächsten Morgen wieder dabei.

Was ohne Einstellungen gilt, steht als `DEFAULTS` in `notifications_lib.js`
und noch einmal in `frontend/src/lib/stores/notificationPrefs.svelte.ts`.
**Beide Listen müssen zusammenpassen** — stünde dort etwas anderes, zeigte die
Oberfläche einen Schalter an, der nichts mit dem zu tun hat, was verschickt
wird. Die Linie: An heißt „betrifft mich", aus heißt „ist viel".

`notifications` ist über die API nicht beschreibbar (create/update/delete auf
`null`, in PocketBase „nur Superuser"). Gefüllt wird sie ausschließlich aus
den Hooks, die an den Regeln vorbeilaufen — sonst schriebe sich jeder selbst
Meldungen, oder anderen.

### Warum das Verzeichnis eine Route braucht

Konten entstehen mit `emailVisibility: false` (`teams.svelte.ts`,
`createMember`). PocketBase gibt die E-Mail-Adresse damit nur ihrem Inhaber
heraus — in jedem `users`-Datensatz, den jemand anderes liest, ist das Feld
leer. Ein Verzeichnis ohne Adressen wäre aber eine Liste von Namen, in der
niemand ein Konto wiedererkennt.

Das Flag umzulegen wäre eine Zeile und zugleich ein Loch: `users.listRule`
gilt appweit (`@request.auth.id != ""`), jede angemeldete Person läse danach
jede Adresse — quer über alle Teams. Der Hook liest sie stattdessen
serverseitig und gibt sie nur dem heraus, der sie sehen darf.

`superadmin` wird dabei frisch aus der Datenbank gelesen und nicht aus dem
mitgeschickten Auth-Record: Der Token hält den Stand von der Anmeldung fest,
eine entzogene Rolle wirkte sonst bis zu seinem Ablauf nicht.

## Wer darf ein Konto löschen?

Zwei, und sonst niemand — `users.deleteRule` (siehe
`1757340000_users_superadmin_delete.js`):

| Wer | Wo |
|---|---|
| Der Inhaber selbst | Einstellungen → Profil |
| Superadmin | Einstellungen → Benutzer |

Die Teamleitung ausdrücklich **nicht**. Sie verwaltet Fahrer und
Mitgliedschaften; im Kader gibt es dafür genau einen Eingriff an einer fremden
Person, „Zugang zum Team entziehen" (`teams.removeMember`). Der nimmt das Konto
aus `teams.users`/`teams.admins` — Fahrer, Teilnahmen und Zeiten bleiben
stehen. Sie sind die Geschichte des Teams und nicht die des Logins.

Ein Konto, das ein Team besitzt, lässt sich nicht löschen: `teams.owner` ist
eine Pflichtrelation ohne cascadeDelete, PocketBase müsste sie beim Löschen
leeren und bräche dabei den Datensatz. Beide Oberflächen prüfen das vorher und
sagen, welches Team im Weg steht — sonst stünde dort ein Datenbankfehler.

Warum überhaupt ein Hook? Wer über einen Link beitritt, ist noch nicht
angemeldet und muss drei Dinge auf einmal tun, die keine Collection-Regel
einzeln erlauben darf: ein Konto anlegen, sich in `teams.users` eintragen und
einen Fahrer anlegen. Ein Hook arbeitet an den Regeln vorbei und kann genau
diese Kombination erlauben — gegen einen gültigen Token und sonst nicht.

**Zwei Fallstricke, an denen die erste Fassung scheiterte:**

1. Jeder Route-Handler läuft in einer **eigenen** JS-Laufzeit. Funktionen, die
   in derselben Datei neben `routerAdd` stehen, sind im Handler *nicht*
   sichtbar (`ReferenceError`). Gemeinsamer Code gehört deshalb in ein Modul,
   das der Handler sich per ``require(`${__hooks}/…`)`` selbst holt.
2. Was `record.get()` bei einer Mehrfach-Relation liefert, ist ein Go-Slice
   und kein JS-Array — `indexOf` und Konsorten sind darauf nicht verlässlich.
   Anhängen geht über den Modifier `record.set('users+', id)`, Prüfen über
   einen Filter.

## Datenpersistenz

Sämtliche Laufzeitdaten liegen in der SQLite-DB unter `/pb/pb_data`: Datensätze,
Uploads, die SMTP-Einstellungen und der Superuser. Ohne gemountetes Volume auf
diesem Pfad sind sie nach jedem Redeploy verloren.

Das Volume-Mapping `./pb_data:/pb/pb_data` steht in der `docker-compose.yaml`,
damit die Persistenz-Konfiguration versioniert im Repo liegt.

**Trügerisches Signal:** Die Collections kommen aus der Migration und sind nach
einem Redeploy auch dann da, wenn gar kein Volume existiert. Sie taugen **nicht**
als Nachweis funktionierender Persistenz — das zeigt nur ein Datensatz, der in
keiner Migration steht.

Mount prüfen:

    docker inspect <container> --format '{{json .Mounts}}' | jq

Erscheint dort kein Eintrag mit `"Destination": "/pb/pb_data"`, fehlt die Persistenz.

`pb_data/` steht in `.gitignore` und gehört dort auch hin.

## Superuser-Verhalten

`entrypoint.sh` ruft `superuser create` auf — bewusst **nicht** `upsert`.
Existiert der Account bereits, scheitert `create` mit „Value must be unique" und
das Passwort bleibt unangetastet. Eine im Admin-UI vorgenommene
Passwortänderung überlebt damit jeden Redeploy.

| Situation | Verhalten |
|---|---|
| Erster Start, Variablen gesetzt | Superuser wird angelegt |
| Neustart, Account existiert | „Superuser existiert bereits — Passwort bleibt unverändert" |
| Passwort im UI geändert, dann Neustart | UI-Passwort gilt weiter, Env wird ignoriert |
| Variablen nicht gesetzt | Übersprungen, PocketBase gibt Installer-Link im Log aus |
| Passwort zu kurz (< 8 Zeichen) | Container bricht mit Exitcode 1 ab |

Passwort später ändern: **im Admin-UI**, nicht über die Env — eine Änderung der
Env-Variable hat keine Wirkung mehr, sobald der Account existiert.

## PocketBase aktualisieren

Die Version ist über das Build-Arg `PB_VERSION` gepinnt (Dockerfile und
`docker-compose.yaml`). Wert hochsetzen, committen, neu bauen.

Ein `latest` gibt es bewusst nicht: Der GitHub-Asset heißt
`pocketbase_<version>_linux_amd64.zip`, enthält die Version also im Dateinamen.
Der Pin ist auch gewollt — sonst zieht jeder Rebuild unangekündigt eine neue
Version, inklusive möglicher DB-Schema-Migrationen.

Vor einem Update: Changelog prüfen
(https://github.com/pocketbase/pocketbase/releases) und `pb_data` sichern —
PocketBase migriert die DB beim Start automatisch, ein Downgrade ist danach
nicht mehr ohne Weiteres möglich.