Doku und Tooling: README, .env-Vorlage, Launch-Konfiguration

2026-07-17 18:18:45 +02:00
parent b1e41026b6
commit fbd4659346
4 changed files with 132 additions and 22 deletions
@@ -1,36 +1,117 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Speisekarte – Betriebskantine

-## Getting Started
+Digitale Speisekarte für eine Firmenkantine (ca. 250 Mitarbeiter) mit
+öffentlicher Wochenansicht, Kantinen-Bereich zur Pflege der Gerichte und
+Admin-Bereich für Benutzerverwaltung und Branding.

-First, run the development server:
+**Stack:** Next.js 16 (App Router, TypeScript, Tailwind CSS) · Supabase
+(PostgreSQL, Auth inkl. Passkeys, Storage, Row Level Security)

-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+## Funktionen
+
+| Bereich | Funktionen |
+| --- | --- |
+| Öffentlich (ohne Login) | Wochenplan Mo–Fr mit den Bereichen Brotzeit (09:00–10:00), Mittagessen, Mittagessen vegetarisch und Suppe (je 11:30–13:30); Navigation vorherige/nächste Woche; Logo zentriert über der Karte; Allergene & Zusatzstoffe unterhalb der Karte |
+| Kantinen-Team (`/intern`) | Gerichte anlegen/bearbeiten/löschen; Gerichte Tagen/Bereichen zuweisen (mehrere pro Zelle) und wieder entfernen; globale Allergen-/Zusatzstofflisten pflegen; eigene Passkeys verwalten |
+| Admin (`/admin`) | Kantinenmitarbeiter anlegen/bearbeiten/löschen (inkl. Passwort-Reset und Rollenvergabe); Farbgebung der Speisekarte anpassen; Logo hochladen/entfernen |
+
+Anmeldung mit E-Mail + Passwort oder alternativ per **Passkey**
+(Registrierung im Bereich „Passkeys“ nach dem ersten Login).
+
+## Projektstruktur
+
+```
+app/                    Next.js-Routen
+  page.tsx              Öffentliche Speisekarte
+  login/                Login (Passwort + Passkey)
+  intern/               Kantinen-Bereich (Rolle: staff oder admin)
+  admin/                Verwaltung (Rolle: admin)
+  api/admin/users/      Benutzerverwaltung (serverseitig, Service-Role-Key)
+components/             Client-Komponenten (WeekEditor, DishManager, …)
+lib/supabase/           Supabase-Clients (Browser / Server / Admin)
+lib/                    Typen, Datums-/Formatierungshelfer
+proxy.ts                Session-Refresh + Schutz von /intern und /admin
+supabase/migrations/    Schema & Seed-Daten (Referenz/Doku)
+supabase/local/         Skripte + Dumps für die lokale PostgreSQL-Kopie
+scripts/                Hilfsskripte (DB-Migration, lokaler Sync)
 ```

-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+## Entwicklung

-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+```bash
+npm install
+npm run dev            # http://localhost:3000
+```

-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+Voraussetzung: `.env.local` mit den Werten aus `.env.example`
+(liegt lokal bereits vor und ist per `.gitignore` vom Repo ausgeschlossen).

-## Learn More
+## Umgebungsvariablen (Live-Betrieb)

-To learn more about Next.js, take a look at the following resources:
+Beim Webserver/Hoster müssen genau diese drei Variablen hinterlegt werden
+(Werte: Supabase-Dashboard → Project Settings → API Keys):

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+| Variable | Bedeutung | Geheim? |
+| --- | --- | --- |
+| `NEXT_PUBLIC_SUPABASE_URL` | URL des Supabase-Projekts, z. B. `https://hvzikwjoyhoakedlywhj.supabase.co` | nein |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Öffentlicher anon-Key (RLS schützt die Daten) | nein |
+| `SUPABASE_SERVICE_ROLE_KEY` | Service-Role-Key für die Benutzerverwaltung | **ja – niemals im Browser/Repo!** |

-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+Build & Start auf dem Server:

-## Deploy on Vercel
+```bash
+npm ci
+npm run build
+npm run start          # Port 3000 (hinter Reverse-Proxy betreiben)
+```

-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+### Passkeys für die Produktions-Domain freischalten

-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+Passkeys sind an die Domain gebunden. Aktuell ist `localhost` konfiguriert.
+Vor dem Livegang in der Supabase-Konfiguration (Management API oder
+Dashboard → Authentication → Settings) anpassen:
+
+- `webauthn_rp_id` = `speisekarte.example.de` (die echte Domain, ohne Protokoll)
+- `webauthn_rp_origins` = `https://speisekarte.example.de`
+- `passkey_enabled` = `true` (bereits aktiv)
+
+## Datenbank
+
+### Supabase (führende Datenbank)
+
+- Projekt-Ref: `hvzikwjoyhoakedlywhj` (Region `eu-central-1`, Frankfurt)
+- Schema und Seed-Daten: `supabase/migrations/0001_init.sql` und `0002_seed.sql`
+- Ausführen weiterer SQL-Dateien:
+  `SUPABASE_ACCESS_TOKEN=<token> node scripts/db-apply.mjs <datei.sql>`
+
+Sicherheitsmodell (Row Level Security):
+
+- `anon` darf ausschließlich lesen (Speisekarte, Bereiche, Allergene,
+  Zusatzstoffe, Einstellungen).
+- `staff`/`admin` (Rolle im `profiles`-Eintrag) pflegen Gerichte,
+  Wochenplan und Kennzeichnungen.
+- Nur `admin` ändert Einstellungen (Farben/Logo) und verwaltet Benutzer;
+  das Anlegen/Löschen von Benutzern läuft serverseitig über den
+  Service-Role-Key (`app/api/admin/users`).
+- Storage-Bucket `branding` (Logo): öffentlich lesbar, Schreibzugriff nur Admin.
+
+### Lokale PostgreSQL-Kopie
+
+Auf dem Entwicklungsrechner läuft PostgreSQL 17 mit der Datenbank
+`speisekarte` (Kopie von Schema + Daten aus Supabase, inkl. Minimal-Stubs
+für `auth`/`storage`). Neu aufbauen bzw. aktualisieren:
+
+```powershell
+$env:SUPABASE_DB_PASSWORD = "<Supabase-DB-Passwort>"
+$env:LOCAL_PG_PASSWORD    = "<lokales postgres-Passwort>"
+powershell -File scripts\sync-local-db.ps1
+```
+
+Hinweis: Die lokale Kopie dient als Ablage/Backup und für Auswertungen.
+Logins (Passwort-Hashes, Passkeys) verbleiben ausschließlich in Supabase.
+
+## Zugangsdaten
+
+Die Anmeldedaten (Admin, Demo-Mitarbeiter, Datenbank-Passwörter) stehen in
+`ZUGANGSDATEN.md` – diese Datei ist bewusst **nicht** im Repository
+(`.gitignore`). Nach dem ersten Login bitte die Startpasswörter ändern.