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 allen Freitextfeldern bei der Einreichung einer Meldung.

Anonymisierte Felder (18 Stück)

Alle _sonstiges-Freitextfelder sowie: beschreibung_vorfall, beschreibung_verletzung, auswirkung, konflikt_hintergrund, zusatz_intervention, wahrnehmung, umstaende.

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, GeoController
│   │   ├── Http/Middleware/         # AdminMiddleware, DeveloperMiddleware, ValidateCaptcha
│   │   ├── Models/                 # User, Submission, FormTemplate, FormBlock,
│   │   │                           # FormTemplateBlock, AppSetting
│   │   └── Services/               # AnonymisierungsService, CaptchaService,
│   │                               # BiFieldRegistry, GeoService, TestDataSeederService
│   ├── database/
│   │   ├── migrations/             # Datenbank-Schema
│   │   └── seeders/                # AdminSeeder
│   ├── tests/                      # PHPUnit-Tests
│   ├── routes/api.php              # API-Routen
│   ├── Dockerfile                  # Produktion
│   └── Dockerfile.dev              # Entwicklung
├── frontend/                       # Nuxt 3 Frontend
│   ├── pages/                      # 17 Seiten (Meldung, Admin, Login, …)
│   ├── components/                 # 25 Vue-Komponenten
│   ├── composables/                # 8 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 (17)

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 (10)

• 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)

17. 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

18. 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)