timerise-ai/booking-kiosk

Selbstbedienungs-Buchungskiosk

Ein Kiosk ist eine Buchungswebsite mit umgekehrtem Vertrauensmodell: Der Client ist per Design nicht authentifiziert und physisch gemeinsam genutzt, daher liegt das gesamte Vertrauen auf dem Server (Preise, Kapazität, Idempotenz) und der gesamte Zustand ist flüchtig (In-Memory, automatischer Reset, nie persistent). Alles in dieser Skill folgt aus diesen beiden Tatsachen.

Wann verwenden

• Erstellung eines Walk-up-Buchungsterminals für slotbasierte Kapazität (Stationen × Zeitfenster) mit optionaler Ausrüstung und Verbrauchsmaterialien.
• Hinzufügen eines Kiosk-Modus zu einer App, die bereits Online-Buchungen unterstützt.
• Überprüfung eines bestehenden Kiosks anhand der unten stehenden harten Regeln; provenance.md dokumentiert den Grund für jede Regel.

Wann NICHT verwenden

• On-Premises-Offline-Fallback-Server – dies ist die Schwester-Skill island-mode-server; diese Skill definiert nur den Client-seitigen Failover-Vertrag des Kiosks.
• Digitale Beschilderung/Anzeigebildschirme – andere Fähigkeit (Wiedergabe, keine Eingabe), andere Skill.
• Mitarbeiter-POS oder Admin-Buchungswerkzeuge – Mitarbeiter sind authentifiziert und vertrauenswürdig; das Vertrauensmodell dieser Skill ist für sie falsch.
• Eine normale Buchungswebsite – nutzen Sie die Backend-Schnittstelle, wenn nützlich, aber die Kiosk-Mechanik (Tastatur, Timer, Berührungsoptimierung) ist dort überflüssig.

Architektur

 KioskProvider (reiner Reducer: Schritte, Auswahlen, Warenkorb, sessionId)
   │ Props: Dictionary-Abschnitte        Hooks: Preisgestaltung · Ausrüstung · Verfügbarkeit
 Bildschirme: service→date→time→participants→equipment→summary→confirmation
   │                         └─ Nebenablauf: booking-lookup → booking-edit
   ▼ ein Fetch-Wrapper (device key + offline base-URL failover)
 /api/kiosk/booking/{create,lookup,add-items,edit}     ← alle Vertrauensentscheidungen
   ▼ KioskBackend-Schnittstelle: Server-Preisgestaltung · Promo · Bestandssperren (TTL 15 Min.)
     transaktionale Kapazitätsprüfung · Kassen-/Online-Zahlung · Webhook
 Echtzeit: location.lastBookingChangeAt → stilles Nachladen → REFRESH_SLOT

Kritische Fakten

1. Benutzertaps navigieren; Hintergrundaktualisierungen tun dies nie. SET_SLOT vs. REFRESH_SLOT ist der Unterschied zwischen Live-Verfügbarkeit und dem Versetzen eines Kunden mitten im Kauf vom Zusammenfassungsbildschirm.
2. Der Server berechnet alles. Nichts Geldbezogenes wird eingehend übertragen; der Client-Gesamtbetrag ist eine Voransicht.
3. Kassenzahlung ist der Resilienzpfad – Buchung bestätigt mit PENDING_COUNTER_PAYMENT, keine Zahlungsintegration im Ablauf; Online-Zahlung an einem Kiosk bedeutet einen QR, den der Kunde scannt, niemals den Kiosk weg navigieren.
4. Jede Texteingabe öffnet die Bildschirmtastatur und setzt inputMode="none". Eines ohne das andere ist ein unbenutzbarer Bildschirm.
5. Bestandssperren sind TTL-reserviert (15 Min.) und werden bei jedem Fehlerpfad freigegeben – der Sweep-Job ist das Sicherheitsnetz, nicht der Mechanismus.
6. Die Client-sessionId ist der Idempotenzschlüssel. Doppeltippen, Wiederholen, verlorene Antwort: höchstens eine Buchung.

Harte Regeln

Kiosk-Sitzungszustand niemals persistent speichern. Der nächste Kunde darf nicht den Namen des vorherigen sehen. In-Memory + 120 s Inaktivitäts-Reset + 30 s Bestätigungs-Reset, auf Hardware verifiziert.

Dem Client niemals Preise, Kapazität oder Gültigkeit von Aktionen anvertrauen. Der Server berechnet jeden Betrag und antwortet auf eine ungültige Aktion mit PROMO_INVALID; ein Kunde an einem Kiosk hat keine Möglichkeit, den Betrag zu überprüfen.

Ein Fetch-Wrapper für jede Kiosk-Anfrage. Der Wrapper trägt den Geräte-Header, das Fehler-Envelope und die Failover-Basis-URL, sodass Authentifizierung, Fehler und Offline-Failover auf jede Anfrage gleichzeitig angewendet werden.

Wenn der Geräteschlüssel konfiguriert ist, ist ein fehlender Header ein 401. Nur-Ablehnung-bei-falschem-Schlüssel ist gleichbedeutend mit keiner Authentifizierung.

Bestandssperren bei jedem Fehlerpfad nach dem Erwerb freigeben. Ein 409, der die Reservierung hält, friert den Bestand für die gesamte TTL ein.

Schnellstart

1. Lesen Sie state-machine.md; implementieren Sie den Reducer und Provider, führen Sie dessen Testsuite aus.
2. Erstellen Sie Bildschirme gemäß dem Vertrag in screens.md mit dem Designsystem des Hosts – Tastatur, Timer, Berührungsoptimierung.
3. Implementieren Sie die Routen aus api-contract.md über die booking-backend.md-Schnittstelle.
4. Verdrahten Sie Aktualität + Offline gemäß realtime-offline.md.
5. Bereitstellen und Rauchtest gemäß operations.md.

Anpassungsvertrag

Schnittstelle	Diese Skill liefert	Der Host liefert
Domain-Entitäten	service/station/equipment/consumable + Umbenennungstabelle	sein Vokabular (court, kart, bay…)
Mandantenbereich	locationId in der Kiosk-URL, servergeprüft	sein Standort-/Site-Modell
Geräteauthentifizierung	x-kiosk-api-key-Vertrag	Schlüsselverwaltung; optionale gerätebezogene Tokens
Datenzugriff	KioskBackend-Schnittstelle; Firestore-Referenz + SQL-Entwurf	sein ORM/SDK
Zahlungen	Kassenstatus + checkout-session/webhook-Vertrag	Stripe oder Äquivalent
Echtzeit	SubscribeFreshness-Schnittstelle	Firestore/Supabase/SSE/Polling
Offline	NetworkStatus-Vertrag	LAN-Server (island-mode-server) oder keiner
UI-Primitive	Struktur, Zustände, Interaktionsregeln	Buttons, Dialog, Spinner, Aussehen
Styling	Layoutabsicht, Touch-Ziele, ein --primary-Token	sein Designsystem
Zeichenketten	Wörterbuchschlüsselbaum, alle Schlüssel erforderlich	seine i18n-Dateien, alle Locales
Validierung	Abhängigkeitsfreie Guards	seine Schema-Bibliothek, falls vorhanden

Referenzverzeichnis

Szenario	Auslöseschlüsselwörter	Referenz
Zustand, Schritte, Reducer, Sitzung, Tests	step, reducer, GO_BACK, REFRESH_SLOT, sessionId, reset	state-machine.md
Bildschirme, Tastatur, Timer, Berührung, i18n-Schlüssel	Bildschirmtastatur, Inaktivität, Countdown, QR, Touch-Ziel, Wörterbuch	screens.md
Routen, Authentifizierung, Validierung, Idempotenz, Fehler	x-kiosk-api-key, 401, 409, Idempotenz, PROMO_INVALID, Suche, PII	api-contract.md
Kapazität, Bestand, Zahlungen, Webhook, Crons	Transaktion, Bestandssperre, TTL, PENDING_COUNTER_PAYMENT, Webhook, Rückerstattung	booking-backend.md
Live-Aktualisierung, Caching, Offline-Failover	lastBookingChangeAt, onSnapshot, s-maxage, Offline-Banner, LAN, Gesundheitsabfrage	realtime-offline.md
Bereitstellung, Gating, Bedienoberfläche	Edge --kiosk, zugewiesener Zugriff, Heartbeat, Feature-Gate, Rauchtest	operations.md
Warum die Vorlagen von der früheren Implementierung abweichen	Prüfung, Hauptbuch, bewusst beibehalten, hinzugefügt	provenance.md