eforms.cloud v0.0.61

1. Architektur & Tech-Stack

Die Anwendung folgt einer klassischen Client-Server-Architektur. Das Nuxt-3-Frontend kommuniziert per REST-API mit dem Laravel-Backend. In Produktion sitzt ein Nginx-Reverse-Proxy davor, der SSL-Terminierung und Routing übernimmt.

2. Voraussetzungen

• Docker & Docker Compose (v2+)
• Git
• Optional: php, composer, node (falls lokal ohne Docker gearbeitet wird)

3. Entwicklungsumgebung starten

Repository klonen und starten

git clone https://github.com/calhelp/eforms-cloud.git
cd eforms-cloud
docker compose -f docker compose.dev.yml up --build

Das startet drei Container:

Datenbank-Migrationen ausführen

docker compose -f docker compose.dev.yml exec api php artisan migrate

Container stoppen

docker compose -f docker compose.dev.yml down

Zum vollständigen Zurücksetzen inkl. Datenbank-Volume:

docker compose -f docker compose.dev.yml down -v

4. Backend-Zugang & Admin-User

Admin-User per Seeder anlegen

Der AdminSeeder erstellt automatisch einen Standard-Admin-Account:

docker compose -f docker compose.dev.yml exec api php artisan db:seed --class=AdminSeeder

Admin-Login im Frontend

Öffne http://localhost:3000/admin/login und melde dich mit den obigen Zugangsdaten an.

Eigenen Admin-User per Tinker anlegen

docker compose -f docker compose.dev.yml exec api php artisan tinker

# In Tinker:
User::create([
    'name' => 'Dein Name',
    'email' => 'deine@email.de',
    'password' => Hash::make('deinSicheresPasswort')
]);

Direkt in den Backend-Container

docker compose -f docker compose.dev.yml exec api bash

# Nützliche Artisan-Befehle:
php artisan migrate         # Migrationen ausführen
php artisan migrate:fresh   # DB zurücksetzen & neu migrieren
php artisan tinker           # Laravel REPL
php artisan route:list       # Alle API-Routen anzeigen

5. API-Referenz

Basis-URL (Entwicklung): http://localhost:8000/api

Öffentliche Endpunkte (kein Token nötig)

Geschützte Endpunkte (Bearer-Token erforderlich)

Zwei-Faktor-Authentifizierung (Bearer-Token erforderlich)

Admin-Endpunkte (Admin-Rolle erforderlich)

Developer-Endpunkte (Developer-Rolle erforderlich)

BI-API Endpunkte (Bearer-Token mit bi:read Berechtigung)

Detaillierte Dokumentation: BI-API Dokumentation

6. Authentifizierung (Sanctum)

Die API nutzt Laravel Sanctum mit Token-basierter Authentifizierung.

Login (Token erhalten)

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@eforms.cloud", "password": "password"}'

Antwort:

{
  "token": "1|abc123...",
  "user": { "id": 1, "name": "Admin", "email": "admin@eforms.cloud" }
}

Geschützte Route aufrufen

curl http://localhost:8000/api/meldungen \
  -H "Authorization: Bearer 1|abc123..."

Logout

curl -X POST http://localhost:8000/api/auth/logout \
  -H "Authorization: Bearer 1|abc123..."

7. Zwei-Faktor-Authentifizierung (2FA)

Das System unterstuetzt TOTP-basierte Zwei-Faktor-Authentifizierung fuer alle Admin-Benutzer. Die Implementierung nutzt pragmarx/google2fa und bacon/bacon-qr-code.

Ablauf

1. Aktivierung: POST /api/auth/two-factor/enable – Generiert Secret, QR-Code (SVG) und 8 Recovery Codes (Format: XXXX-XXXX)
2. Bestaetigung: POST /api/auth/two-factor/confirm – Verifiziert TOTP-Code aus Authenticator-App
3. Login mit 2FA: Login gibt two_factor: true zurueck → Client sendet Code an POST /api/auth/two-factor-challenge
4. Recovery: Falls kein Zugriff auf Authenticator, kann ein Recovery Code statt TOTP-Code verwendet werden

Beispiel: 2FA aktivieren

curl -X POST http://localhost:8000/api/auth/two-factor/enable \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Content-Type: application/json" \
  -d '{"password": "mein-passwort"}'

Antwort:

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code_svg": "<svg ...>",
  "recovery_codes": ["ABCD-EFGH", "IJKL-MNOP", ...]
}

Deaktivierung

curl -X DELETE http://localhost:8000/api/auth/two-factor \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Content-Type: application/json" \
  -d '{"password": "mein-passwort"}'

8. CAPTCHA-System

Das System bietet einen mathematischen CAPTCHA-Schutz mit SVG-Rendering und visueller Rausch-Ueberlagerung.

Schwierigkeitsstufen

Kontext-Steuerung

CAPTCHA kann separat fuer verschiedene Kontexte aktiviert werden:

• forms – Meldungsformulare (Standard: aktiviert)
• login – Admin-Login (Standard: deaktiviert)

Zusaetzlicher Schutz

• Honeypot-Feld: Unsichtbares Feld, das von Bots ausgefuellt wird → Submission wird abgelehnt
• Rate Limiting: Konfigurierbare Anfragen pro Stunde (Standard: 10)
• Einmalverwendung: Jeder CAPTCHA-Token ist nach Verifizierung ungueltig
• Ablauf: Tokens laufen nach 5 Minuten ab

Beispiel: CAPTCHA generieren

curl http://localhost:8000/api/captcha

Antwort:

{
  "token": "abc123...",
  "image_svg": "<svg ...>",
  "accessible_text": "Was ergibt 3 plus 7?"
}

9. Rollensystem & Berechtigungen

Das System verwendet vier Rollen mit hierarchischen Berechtigungen:

Hierarchie-Regel: Admins koennen keine Developer bearbeiten oder loeschen. Benutzer koennen sich nicht selbst loeschen.

10. Dynamisches Formularsystem

Formulare werden ueber ein Template-Block-System definiert, das ohne Code-Aenderungen neue Formular-Layouts ermoeglicht.

Architektur

• FormTemplate: Definiert ein Formular (Slug, Titel, Beschreibung, aktiv/inaktiv, Detailmodus)
• FormBlock: Wiederverwendbare Feldgruppe (Fieldset) mit Slug, Legende, Felddefinitionen
• FormTemplateBlock: Verknuepfung mit Sortierreihenfolge und Feld-Overrides (Sichtbarkeit, Pflichtfelder)

Unterstuetzte Feldtypen (18)

Feld-Eigenschaften

• dbField – Datenbank-Schluessel fuer JSONB-Speicherung
• required, min, max, step – Validierung
• options – Auswahlliste fuer Select-/Checkbox-Felder
• showAsChart – Feld wird als Chart im Dashboard angezeigt
• showAsTopCard – Feld wird als Top-Wert-Karte im Dashboard angezeigt
• anonymize – Feld wird bei Einreichung anonymisiert
• detailedOnly – Feld nur im ausfuehrlichen Modus sichtbar
• dependsOn – Abhaengigkeiten (z.B. Landkreis abhaengig von Bundesland)

Import / Export

Templates koennen als JSON-Bundle exportiert und importiert werden. Beim Import werden bestehende Bloecke wiederverwendet oder automatisch erstellt. So lassen sich Formulare zwischen verschiedenen eforms.cloud-Instanzen portieren.

11. Anonymisierung

Der AnonymisierungsService entfernt automatisch personenbezogene Daten aus Freitextfeldern bei der Einreichung einer Meldung. Welche Felder anonymisiert werden, wird dynamisch aus den FormBlock-Definitionen ermittelt.

Dynamische Felderkennung

Der Service liest zur Laufzeit alle Felder, die in den zugehoerigen FormBlocks mit anonymize: true markiert sind. Zusaetzlich werden alle otherDbField-Eintraege (Sonstiges-Freitextfelder) automatisch einbezogen. Neue Felder koennen im Block-Editor (/admin/blockeditor) per Checkbox "Anonymisieren" aktiviert werden — ohne Code-Aenderung.

Erkannte Muster

Zusätzlich werden technische Metadaten (ip, user_agent, session_id, debug_info) aus der Anfrage entfernt.

12. Mehrsprachigkeit (i18n)

eforms.cloud unterstuetzt vollstaendige Zweisprachigkeit (Deutsch und Englisch) auf allen Ebenen:

Frontend

• @nuxtjs/i18n: Integration fuer automatische Spracherkennung und Locale-Routing
• LanguageSwitch.vue: Sprachumschalter im Frontend fuer Benutzer
• LocaleTabs.vue: Locale-Tabs im Block-Editor und Template-Editor (DE/EN)
• useApiLocale.ts: Composable fuer locale-aware API-Aufrufe
• useTranslations.ts: Composable fuer die Uebersetzungsverwaltung

Backend

• Translation-Model: Speichert Uebersetzungen in der translations-Tabelle
• TranslationController: CRUD-Operationen, Import und Export von Uebersetzungen
• Formular-Bloecke und Templates unterstuetzen mehrsprachige Labels und Beschreibungen
• Layout-Einstellungen (Header, Footer, Sektionen) sind pro Locale konfigurierbar

API-Endpunkte (Admin-Rolle erforderlich)

13. Wartungsmodus

Das System verfügt über einen konfigurierbaren Wartungsmodus, der über die app_settings-Tabelle gesteuert wird.

Status abfragen (öffentlich)

curl http://localhost:8000/api/maintenance/status

Antwort:

{
  "enabled": true,
  "message": "Dieses Projekt dient als Demonstrationsversion...",
  "contact": ""
}

Wartungsmodus umschalten (Admin)

curl -X POST http://localhost:8000/api/admin/maintenance \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "message": "Wartungsarbeiten bis 18 Uhr", "contact": "admin@example.de"}'

14. Datenbank

Entwicklungs-Zugangsdaten

Direkte Verbindung per psql

docker compose -f docker compose.dev.yml exec db psql -U eopel eforms_db

Wichtige Tabellen

• users – Benutzer (E-Mail, Passwort-Hash, Rolle, 2FA-Secret/-Recovery-Codes)
• submissions – Formular-Einreichungen (JSONB-Daten, Template-Slug)
• form_templates – Formular-Templates (Slug, Titel, aktiv, Detailmodus)
• form_blocks – Formular-Bloecke (Slug, Legende, Felddefinitionen als JSON)
• form_template_blocks – Verknuepfung Template-Block (Sortierung, Feld-Overrides)
• personal_access_tokens – Sanctum-Tokens (API-Zugang)
• app_settings – Schluessel-Wert-Konfiguration (Wartung, CAPTCHA, Layout)

15. Projektstruktur

eforms.cloud/
├── backend/                        # Laravel 13 API
│   ├── app/
│   │   ├── Http/Controllers/Api/   # Auth, Meldung, Dashboard, Settings, User,
│   │   │                           # FormTemplate, FormBlock, BiStats, TwoFactor,
│   │   │                           # Captcha, ApiToken, Geo, AuditLog,
│   │   │                           # EmailNotification, Health, StripeWebhook,
│   │   │                           # Organization, OrganizationInvitation, Plan,
│   │   │                           # ScheduledReport, SsoAuth, SsoProvider,
│   │   │                           # Translation, UpdateController
│   │   ├── Http/Middleware/         # Admin, Developer, ValidateCaptcha, CheckPlanFeature,
│   │   │                           # DemoMode, EnsureTenant, SetLocale
│   │   ├── Models/                 # User, Submission, FormTemplate, FormBlock,
│   │   │                           # FormTemplateBlock, AppSetting, AuditLog,
│   │   │                           # EmailNotification, InstancePlan, Organization,
│   │   │                           # OrganizationInvitation, ScheduledReport,
│   │   │                           # ScheduledReportRun, SsoProvider, Translation, UpdateLog
│   │   └── Services/               # AnonymisierungsService, CaptchaService,
│   │                               # BiFieldRegistry, GeoService, TestDataSeederService,
│   │                               # AuditService, StripeService, PlanService,
│   │                               # SsoService, TenantContext, UpdateService
│   ├── database/
│   │   ├── migrations/             # Datenbank-Schema
│   │   └── seeders/                # AdminSeeder, FormBlockSeeder, FormTemplateSeeder,
│   │                               # EnglishTranslationSeeder, DatabaseSeeder
│   ├── tests/                      # PHPUnit-Tests
│   ├── routes/api.php              # API-Routen
│   ├── Dockerfile                  # Produktion
│   └── Dockerfile.dev              # Entwicklung
├── frontend/                       # Nuxt 3 Frontend
│   ├── pages/                      # 19 Seiten (Meldung, Admin, Login, …)
│   ├── components/                 # 19 Vue-Komponenten
│   ├── composables/                # 15 Composables (useApi, useAuth, useCaptcha, …)
│   ├── tests/                      # Vitest-Tests
│   ├── Dockerfile                  # Produktion
│   └── Dockerfile.dev              # Entwicklung
├── nginx/                          # Reverse-Proxy-Konfiguration
├── docs/                           # GitHub Pages Dokumentation
├── .github/workflows/
│   ├── deploy.yml                  # Build, Test & Deploy
│   ├── pages.yml                   # GitHub Pages Deploy
│   └── version-bump.yml            # Semantische Versionierung
├── docker-compose.yml              # Produktion
└── docker-compose.dev.yml          # Entwicklung

16. Frontend-Seiten & Komponenten

Seiten (19)

Wichtige Komponenten

• Layout: AppHeader, AppFooter, LanguageSwitch
• Dashboard: StatsCards, DynamicChart, PieChart, ChartMeldungenProMonat, DashboardViewSelector, LetzteMeldungen
• Formular (dynamisch): FormRenderer, DynamicField, CaptchaWidget
• Block-Editor: FieldPreview, FieldTypeLabel, LocaleTabs
• Sonstige: ConfirmModal, HtmlEditor, SimpleHtmlEditor, ValidationErrors

Composables (15)

• useApi – API-Kommunikation mit Bearer-Token
• useApiLocale – Locale-aware API-Aufrufe (sendet aktuelle Sprache mit)
• useAuth – Authentifizierungsstatus, Login, Logout, 2FA-Verifizierung
• useCaptcha – CAPTCHA-Generierung, Validierung und Honeypot-Verwaltung
• useTemplates – FormTemplate-CRUD, Import/Export, Duplizieren
• useBlocks – FormBlock-CRUD mit Suche und Paginierung
• useTranslations – Uebersetzungsverwaltung (CRUD, Import/Export)
• useLayoutSettings – Layout-Konfiguration (Header, Footer, Logos, Content)
• useLandkreise – Landkreis-Daten für Formulare
• useFeiertage – Deutsche Feiertage (fest, beweglich, landesspezifisch)
• useEmailNotifications – E-Mail-Benachrichtigungs-CRUD
• useOrganization – Organisationsverwaltung
• useSso – SSO-Provider-Verwaltung
• useTranslationKeys – Uebersetzungsschluessel-Verwaltung
• useUpdates – Update-Verwaltung

17. Code-Qualitaet & Checks

Die Code-Qualitaet wird durch ein mehrstufiges System aus lokalen Git-Hooks, Makefile-Befehlen und CI-Pipeline sichergestellt. Jede Aenderung durchlaeuft automatisch mehrere Pruefungen, bevor sie auf main gelangt.

Uebersicht der Checks

Git-Hooks

Die Git-Hooks werden mit bash scripts/setup-hooks.sh (bzw. make setup) aktiviert. Sie liegen unter .githooks/ und werden automatisch bei jedem Commit bzw. Push ausgefuehrt.

Pre-Commit Hook

Schnelle Checks, die bei jedem git commit laufen (unter 5 Sekunden):

• Laravel Pint – PHP-Code-Style pruefen und automatisch korrigieren
• PHP Syntax – Syntaxfehler in geaenderten PHP-Dateien erkennen
• ESLint – JavaScript/TypeScript-Lint fuer geaenderte Dateien
• Prettier – Formatierung geaenderter Frontend-Dateien

Pre-Push Hook

Umfassendere Checks, die vor jedem git push laufen (30–120 Sekunden):

• PHPUnit – Alle Backend-Tests ausfuehren
• PHPStan – Statische PHP-Analyse (Level 5, mit Larastan-Extension)
• Vitest – Alle Frontend-Tests ausfuehren
• TypeScript Typecheck – nuxi typecheck (vue-tsc) ausfuehren

Falls ein Check fehlschlaegt, wird der Push abgelehnt. In Ausnahmefaellen: git push --no-verify (nicht empfohlen).

PHPStan (Statische Analyse)

PHPStan analysiert den PHP-Code statisch auf Typfehler, undefinierte Variablen und falsche Methodenaufrufe. Die Konfiguration:

• Config: backend/phpstan.neon
• Level: 5 (erkennt Typfehler, falsche Argumente, fehlende Return-Types)
• Extension: Larastan (Laravel-spezifische Regeln fuer Eloquent, Facades etc.)
• Baseline: backend/phpstan-baseline.neon – erfasst bestehende Fehler, sodass neue Fehler sofort auffallen

# PHPStan ausfuehren
cd backend && vendor/bin/phpstan analyse

# Baseline aktualisieren (nach dem Fixen von Fehlern)
cd backend && vendor/bin/phpstan analyse --generate-baseline

Makefile-Befehle

Alle Checks koennen auch manuell ueber das Makefile ausgefuehrt werden:

Claude-Integration

Bei der Entwicklung mit Claude Code (.claude/settings.json) werden Pint, ESLint und Prettier automatisch vor jedem Commit ausgefuehrt und Aenderungen gestaged.

18. CI/CD-Pipeline

Die CI/CD-Pipeline ist in drei GitHub Actions Workflows aufgeteilt:

Build, Test & Deploy (deploy.yml)

Wird bei jedem Push und Pull Request auf main ausgeführt:

Bei erfolgreichem Merge auf main wird automatisch auf den Produktionsserver deployed.

GitHub Pages (pages.yml)

Automatisches Deployment der docs/-Inhalte bei Änderungen auf main.

Versionierung (version-bump.yml)

Automatische semantische Versionierung nach PR-Merge basierend auf Labels:

• breaking → Major-Version
• feature / enhancement → Minor-Version
• Alle anderen → Patch-Version

19. Screenshot-Automatisierung

Automatisierte Screenshots der Anwendung werden mit Playwright erstellt und in docs/assets/screenshots/ abgelegt, wo sie direkt in der Dokumentation referenziert werden können.

Funktionsweise

Das System liegt im Verzeichnis screenshots/ und ist als eigenständiges Node.js-Projekt aufgebaut. Playwright steuert einen Chromium-Browser, meldet sich an der Anwendung an, navigiert zu den relevanten Seiten und erstellt PNG-Screenshots.

• Pro Tool (eforms, calserver, edocs, quizrace) gibt es ein eigenes Playwright-Projekt mit Login-Setup und Screenshot-Scripts
• Auth-State wird einmal pro Run gespeichert und für alle Scripts wiederverwendet
• Volatile Elemente (Timestamps, Versionsnummern) werden per CSS ausgeblendet, damit keine unnötigen Git-Diffs entstehen

Verzeichnisstruktur

screenshots/
  playwright.config.ts          # Projekte, Viewports, Auth
  package.json                  # Playwright als Dependency
  .env.example                  # Credential-Template (nur für lokale Nutzung)
  lib/helpers.ts                # Shared Utilities
  scripts/
    eforms/
      login.setup.ts            # Auth-Flow
      dashboard.spec.ts         # Screenshot-Scripts
      formulare.spec.ts
      admin.spec.ts
    calserver/                  # Placeholder
    edocs/                      # Placeholder
    quizrace/                   # Placeholder
docs/assets/screenshots/        # Zielordner (wird committet)
  eforms/
  calserver/
  edocs/
  quizrace/

GitHub Actions Workflow

Der Workflow .github/workflows/screenshots.yml wird automatisch jeden Montag um 6:00 UTC ausgeführt oder kann manuell gestartet werden.

Geänderte Screenshots werden automatisch committet und gepusht.

Erforderliche GitHub Secrets

Die Credentials müssen im Repository unter Settings → Secrets and variables → Actions konfiguriert werden:

Hinweis: Nur die Secrets der Tools konfigurieren, die tatsächlich verwendet werden. Fehlende Credentials führen dazu, dass das jeweilige Login-Setup mit einer Fehlermeldung abbricht — andere Tools sind davon nicht betroffen.

Screenshots in der Dokumentation verwenden

Die erzeugten Bilder liegen unter docs/assets/screenshots/<tool>/ und können direkt referenziert werden:

<img src="assets/screenshots/eforms/dashboard-uebersicht.png" alt="Dashboard">

Neues Screenshot-Script hinzufügen

Eine neue .spec.ts-Datei im passenden Tool-Ordner anlegen. Jeder test()-Block erzeugt einen Screenshot:

import { test } from '@playwright/test';
import { prepareCleanState, hideVolatileElements, waitForIdle } from '../../lib/helpers';

test('neue-seite', async ({ page }) => {
  await page.goto('/admin/neue-seite');
  await prepareCleanState(page);
  await hideVolatileElements(page);
  await waitForIdle(page);

  await page.screenshot({
    path: 'docs/assets/screenshots/eforms/neue-seite.png',
  });
});

20. Deployment (Produktion)

Das Produktions-Deployment nutzt docker compose.yml mit Nginx, SSL via Let's Encrypt und automatischer Zertifikatserneuerung.

Schritte

1. .env-Datei im Root erstellen (basierend auf .env.example)
2. Sichere Werte für APP_KEY, DB_PASSWORD und Domain setzen
3. docker compose up -d --build ausführen
4. Der docker-entrypoint.sh führt automatisch Migrationen aus

Wichtige Umgebungsvariablen (.env)

21. Kalender-Integration (Google & Microsoft)

eforms.cloud unterstuetzt die Synchronisation von Terminen mit externen Kalendern (Google Calendar, Microsoft 365/Outlook und CalDAV). Die Integration erfolgt ueber OAuth 2.0 — Admins verbinden ihren Kalender mit einem Klick, ohne selbst OAuth-Credentials konfigurieren zu muessen.

Voraussetzungen fuer den Systembetreiber

Der Betreiber der eforms.cloud-Instanz muss einmalig eine OAuth-App bei Google und/oder Microsoft registrieren und die Credentials in der .env-Datei hinterlegen. Danach funktioniert die Kalender-Verbindung fuer alle Admins und Mandanten automatisch.

Hinweis: Die Redirect-URI wird automatisch aus APP_URL abgeleitet (z.B. https://ihre-instanz.eforms.cloud/admin/calendars/google-callback). Eine manuelle Konfiguration ist nicht noetig.

Google Calendar OAuth-App einrichten

1. Oeffnen Sie die Google Cloud Console (console.cloud.google.com)
2. Erstellen Sie ein neues Projekt oder waehlen Sie ein bestehendes aus
3. Navigieren Sie zu APIs & Dienste > Bibliothek und aktivieren Sie die Google Calendar API
4. Navigieren Sie zu APIs & Dienste > Anmeldedaten und erstellen Sie eine OAuth 2.0-Client-ID (Typ: Webanwendung)
5. Fuegen Sie als Autorisierte Weiterleitungs-URI hinzu: https://[IHRE-DOMAIN]/admin/calendars/google-callback
6. Kopieren Sie Client-ID und Client-Secret in die .env-Datei
7. Konfigurieren Sie den OAuth-Zustimmungsbildschirm unter APIs & Dienste > OAuth-Zustimmungsbildschirm:
   • App-Name und Support-E-Mail angeben
   • Unter Testnutzer die E-Mail-Adressen hinzufuegen, die sich verbinden sollen (im Testmodus)
8. Fuer den produktiven Einsatz: Klicken Sie auf App veroeffentlichen, damit alle Nutzer sich verbinden koennen. Im Testmodus koennen nur die eingetragenen Testnutzer zugreifen.

Microsoft 365 / Outlook OAuth-App einrichten

1. Oeffnen Sie das Azure Portal (portal.azure.com) und navigieren Sie zu App-Registrierungen
2. Erstellen Sie eine neue App-Registrierung (Name frei waehlbar, z.B. "eforms.cloud Kalender")
3. Waehlen Sie unter Unterstuetzte Kontotypen die Option Konten in einem beliebigen Organisationsverzeichnis und persoenliche Microsoft-Konten
4. Fuegen Sie unter Authentifizierung > Plattformkonfigurationen > Web die Redirect-URI hinzu: https://[IHRE-DOMAIN]/admin/calendars/microsoft-callback
5. Erstellen Sie unter Zertifikate & Geheimnisse ein neues Client Secret
6. Kopieren Sie folgende Werte in die .env-Datei:
   • Anwendungs-ID (Client-ID) — von der Uebersichtsseite
   • Client Secret — soeben erstellt
   • Verzeichnis-ID (Tenant-ID) — oder common fuer mandantenuebergreifenden Zugriff

Kalender-Verbindung herstellen (Admin)

Sobald der Systembetreiber die OAuth-Credentials konfiguriert hat, koennen Admins ihre Kalender verbinden:

1. Navigieren Sie zu Admin > Kalender-Verbindungen (/admin/calendars)
2. Klicken Sie auf Verbindung hinzufuegen
3. Vergeben Sie einen Namen (z.B. "Praxis-Kalender")
4. Waehlen Sie den Anbieter (Google Calendar, Microsoft 365 oder CalDAV)
5. Klicken Sie auf Verbinden — Sie werden zur Autorisierungsseite des Anbieters weitergeleitet
6. Nach erfolgreicher Autorisierung werden Sie zurueckgeleitet und koennen einen Kalender auswaehlen

DSGVO-Konformitaet

Die Kalender-Synchronisation ist DSGVO-konform: Es werden keine personenbezogenen Daten in den externen Kalender geschrieben. Stattdessen wird lediglich ein neutraler Eintrag "Terminbuchung" als Platzhalter eingetragen. Fuer die Verfuegbarkeitspruefung wird die FreeBusy-API verwendet, die keine Eventdetails preisgibt.