trihub-ernaehrung-backseatDevs/docs/booking.md

# Paketbuchung

## Ablauf

Die Angebotsübersicht führt zur Detailseite eines Pakets. Der Buchungsbutton
übergibt die Paket-ID und gegebenenfalls die gewählte Variante als URL-Parameter
an `booking.html`. Bestehende Links mit `#/buchen/:packageId` funktionieren weiterhin.

Booking lädt die Bestellübersicht vom Server. Sie enthält Paket und Variante,
Laufzeit, Leistungen, Abrechnung, Nettopreis, MwSt. und Gesamtbetrag. Die Preise
stammen aus `src/shared/packagesdetails.js`; Preisangaben des Browsers werden
nicht übernommen. Ohne Varianten-ID wird die erste Variante des Pakets gewählt.

Beim Absenden speichert der Server Kundendaten und den vollständigen Bestellstand
in der CSV. Anschließend sendet er eine Bestätigung als Text und HTML mit
Buchungsnummer, Datum, gebuchten Leistungen und Preisen. Änderungen am Katalog
verändern bereits gespeicherte Bestellungen nicht.

Der Zahlungsvorgang ist weiterhin simuliert. Es erfolgt keine Abbuchung und
keine verbindliche Beratungsbuchung. Darauf weisen Formular und E-Mail hin.

## Lokal starten

Voraussetzung ist Node.js 24. Abhängigkeiten mit `npm ci` installieren und die
Werte aus `.env.example` in eine lokale `.env` übernehmen. Eine vorhandene
Konfiguration dabei erhalten.

In separaten Terminals starten:

- `npm run dev:mail`: Mailpit mit SMTP auf Port 1025 und Weboberfläche auf 8025.
- `npm run dev:server`: Buchungs-API auf Port 3000.
- `npm run dev`: Frontend auf Port 5173; `/api` wird an Node weitergeleitet.

Die Angebotsübersicht liegt unter <http://localhost:5173/angebotsuebersicht.html>,
der Mailfänger unter <http://localhost:8025>. Mailpit ist im Dev Container enthalten.

`npm run build` erzeugt die Seiten in `dist/`, einschließlich der Paketdetailseite.
Für ein Deployment muss der Webserver `/api` an den Node-Server weiterleiten.
`npm run start:server` startet die API ohne automatischen Neustart.

## Konfiguration

| Variable                 | Standardwert                     | Bedeutung                                           |
| ------------------------ | -------------------------------- | --------------------------------------------------- |
| `HOST`                   | `127.0.0.1`                      | Bind-Adresse der API                                |
| `PORT`                   | `3000`                           | API-Port; bei Änderung auch den Vite-Proxy anpassen |
| `SMTP_HOST`              | `127.0.0.1`                      | SMTP-Server                                         |
| `SMTP_PORT`              | `1025` lokal, sonst `587`        | SMTP-Port                                           |
| `SMTP_SECURE`            | `false`                          | Direktes TLS aktivieren                             |
| `SMTP_USER`, `SMTP_PASS` | leer                             | SMTP-Zugangsdaten; beide gemeinsam setzen           |
| `SMTP_FROM`              | `Tri-Hub <buchung@example.test>` | Absender                                            |
| `SMTP_ALLOW_EXTERNAL`    | `false`                          | Versand über externe SMTP-Server aktivieren         |

Externe SMTP-Verbindungen erfordern TLS. Zugangsdaten gehören ausschließlich
in die Serverkonfiguration und dürfen kein `VITE_`-Präfix erhalten.

## API

Der vollständige Vertrag steht in `src/server/swagger.json`.

| Endpunkt                     | Funktion                                                                            |
| ---------------------------- | ----------------------------------------------------------------------------------- |
| `GET /api/angebote`          | Bestehende Kurzübersicht mit `id`, `name` und `summary`                             |
| `GET /api/packages`          | Kurzübersicht im Swagger-Format                                                     |
| `GET /api/packages/{id}`     | Paketdetails einschließlich Varianten und Leistungen                                |
| `POST /api/bookings/preview` | Bestellübersicht für `packageId` und optionale `variantId`; speichert keine Buchung |
| `POST /api/bookings`         | Buchung speichern und Bestätigung versenden                                         |

POST-Anfragen benötigen `Content-Type: application/json`. Beim Buchen ist
zusätzlich ein `Idempotency-Key` als UUID v4 erforderlich. Das Formular sendet
`packageId`, gegebenenfalls `variantId`, `name` und `email`.

Alternativ akzeptiert die API das Swagger-Objekt `customer` mit `firstName`,
`lastName`, `email` sowie optional `phone`, `ageGroup` und `notes`. Dabei muss
`acceptedTerms` den Wert `true` haben. Diese Angaben werden ebenfalls gespeichert.

Die Antwort enthält die Buchungsnummer, den Erstellungszeitpunkt, das gebuchte
Paket unter `bookedPackage` und den Versandstatus. Eine neue Buchung mit
SMTP-Annahme erhält HTTP 201, eine Wiederholung HTTP 200. Bei ausstehendem,
fehlgeschlagenem oder unklarem Versand wird HTTP 202 zurückgegeben.

Ungültige Angaben, Pakete und Varianten ergeben HTTP 400; ein unbekanntes Paket
am Detail-Endpunkt HTTP 404. Derselbe Anfrageschlüssel mit anderen Daten ergibt
HTTP 409. JSON-Anfragen sind auf 8 KiB begrenzt. Fehlerantworten enthalten
`error.code`, `error.message` und gegebenenfalls `error.fields`.

## Speicherung und Wiederholungen

Die Buchungen liegen in `src/server/data/bookings.csv`. Neue Buchungsnummern
werden fortlaufend als `TH-000001`, `TH-000002` usw. vergeben. Der höchste
vorhandene Wert bestimmt die nächste Nummer. Die CSV muss deshalb vollständig
erhalten bleiben; ältere UUID-Buchungsnummern werden weiterhin unterstützt.

`bookedPackage` speichert den Bestellstand als JSON, `customer` die optionalen
strukturierten Kundendaten und `acceptedTerms` die zugehörige Zustimmung.
CSV-Dateien mit dem früheren Spaltensatz bleiben lesbar und werden beim nächsten
Speichern erweitert. Für alte Buchungen ohne Bestellstand liefert die API
`bookedPackage: null`.

Lesen, Schreiben und Versand werden innerhalb einer Warteschlange abgearbeitet.
Die Datei wird über eine temporäre Datei atomar ersetzt. Unterstützt wird ein
Backend-Prozess auf einem lokalen Dateisystem. Mehrere Serverinstanzen benötigen
einen gemeinsam abgesicherten Speicher. CSV-Zellen werden gegen die Auswertung
als Tabellenformeln geschützt; Dateien erhalten den Zugriffsmodus 0600.

Wiederholte Anfragen mit demselben Schlüssel und denselben Daten liefern die
vorhandene Buchung. Es wird keine zweite Bestellung angelegt. Die Auswahl einer
anderen Variante mit demselben Schlüssel wird abgelehnt.

Das Formular merkt sich Anfrage und Bestellübersicht je Paket und Variante im
`sessionStorage`. Nach einem Verbindungsfehler bleiben die Angaben gesperrt,
damit dieselbe Anfrage erneut geprüft werden kann. Ein neuer Tab oder gelöschter
Sitzungsspeicher liegt außerhalb dieser Absicherung.

## Versandstatus

| Status     | Bedeutung                                                                                        |
| ---------- | ------------------------------------------------------------------------------------------------ |
| `pending`  | Buchung gespeichert; Versand noch nicht gestartet. Dieselbe Anfrage kann den Versand fortsetzen. |
| `sending`  | Versandabsicht gespeichert. Nach einem Prozessabbruch liefert die API `unknown`.                 |
| `accepted` | SMTP hat die Nachricht angenommen; die Zustellung ist noch nicht bestätigt.                      |
| `failed`   | Versand fehlgeschlagen oder ausdrücklich abgelehnt.                                              |
| `unknown`  | SMTP-Annahme oder anschließende Statusspeicherung blieb unklar.                                  |

Bei `failed` und `unknown` wird nicht automatisch erneut versendet. Vor einem
manuellen Neuversand muss der Mailserver anhand der Buchungsnummer geprüft werden.
CSV und SMTP bilden keine gemeinsame Transaktion.

## Tests

`npm test` prüft Validierung, Preisberechnung, Varianten, CSV-Kompatibilität,
Wiederholungen und Versandfehler. `npm run test:browser` prüft den Weg von der
Angebotsübersicht über die Paketdetails bis zur Bestätigung, einschließlich
Premium-Jahresvariante, Tastaturbedienung und schmalem Bildschirm.

Die Tests verwenden die regulären Paketdaten, temporäre CSV-Dateien und einen
simulierten Mailversand. Playwright benötigt Chromium; die Installation erfolgt
mit `npx playwright install --with-deps chromium`. Die Ports 3000 und 5173 müssen
für die automatisch gestarteten Testserver frei sein.

Vor einem Commit außerdem `npm run format:check`, `npm run build` und
`git diff --check` ausführen. Für eine manuelle Mailprüfung eine Buchung mit einer
Adresse unter `example.test` anlegen und die Bestätigung in Mailpit kontrollieren.