formeleon/docs/feinkonzept.md

Formeleon - Feinkonzept & Spezifikation

• Autor: Björn Runden br@runden.net
• Status: Freigegeben / In Umsetzung
• Version: 1.0
• Datum: August 2026

---

1. Übersicht & Systemkontext

Formeleon ist ein mandantenfähiges Formular-Service-System (Multi-tenant Form Generator & Backend API). Das System nimmt Formular-Submissions von externen Mandanten-Webseiten entgegen, schützt diese vor Bot-Spam, speichert die Daten isoliert nach Mandanten ab und stellt ein Admin-Dashboard zur Verwaltung bereit.

---

2. Authentifizierung & Identity Management (Zitadel OIDC)

• Identity Provider: Zitadel via OIDC (OAuth2) unter Nutzung von authlib.integrations.flask_client.OAuth.
• Scope & Mapping: Zitadel wird ausschließlich für die Authentifizierung und Übermittlung von User-Attributen (z. B. E-Mail, Name, Sub-ID) genutzt. Es findet kein Rollen-Mapping aus Token-Claims statt.
• Lokale Rechteverwaltung (RBAC): Die Zuweisung von Rollen (admin, tenant_admin, user, viewer) erfolgt strikt innerhalb der lokalen PostgreSQL/SQLite-Datenbank über die E-Mail-Adresse des Benutzers.
• Development Bypass: Bei aktivierter Option DEV_MODE=true umgeht eine Middleware den OIDC-Redirect und injiziert eine Mock-Session für die lokale Entwicklung.

---

3. Bot-Schutz & Spam-Handling (Google reCAPTCHA v3)

Parameter	Spezifikation
Technologie	Google reCAPTCHA v3 (unsichtbare Score-basierte Validierung)
Schwellenwert (Threshold)	Standard: 0.5 (konfigurierbar via RECAPTCHA_MIN_SCORE in .env)
Fehlerfall (Bot Risk)	Rückgabe von HTTP Status 400 Bad Request an den Client mit lesbarer Fehlermeldung.
Datenhaltung bei Spam	Submissions mit Score < 0.5 werden als flagged_as_spam in der Datenbank gespeichert (nicht direkt gelöscht).
Benachrichtigungen	Automatischer E-Mail-Hinweis an Admin/Mandant bei erkannter Spam-Submission (sofern Mandant auflösbar).
Dev Mode Simulation	Mock-Service gibt standardmäßig Score 0.9 zurück (einstellbar via MOCK_RECAPTCHA_SCORE).

---

4. Frontend Integration (Form-Embed Snippet)

4.1 Embed Workflow

1. Einbindung beim Mandanten:

   <script src="https://formeleon.domain/embed.js" data-form-id="123" data-public-key="pk_live_xyz"></script>
   <div id="formeleon-form"></div>
   

2. Handshake & Validation: Das Snippet führt beim Laden eine Asynchron-Anforderung via Fetch API durch (GET /api/v1/forms/<form_id>). Das Backend prüft den Origin-Header gegen die allowed_origins des Mandanten.
3. Rendering (Lightweight DOM Insertion): Direktes HTML-Injecting (via innerHTML/DOM-Parser) in das Ziel-DOM. Bewusst kein Shadow-DOM, um das Customizing via CSS des Mandanten zu erleichtern.
4. Submission Handling: Das Snippet fängt das onsubmit-Event ab, fordert im Hintergrund ein reCAPTCHA v3 Token an und sendet die Formulardaten per POST/JSON an das Backend.

---

5. Datenmodell & Multi-Tenancy

• Tenant Isolation: Logische Mandantentrennung auf Datenbankebene über tenant_id an den Entitäten FormConfig, Submission und User.
• Public Keys & Hashes: Öffentliche Schlüssel für das Embedding haben das Format pk_live_<hash> und enthalten intern einen SHA-basierten Verweis auf die tenant_id.
• Flexible Payloads: Die Submissions speichern dynamische Eingabefelder in einem JSON-Payload-Feld der Datenbank ab, um feingranulare Schema-Änderungen ohne Schema-Migrationen zu ermöglichen.

---

6. Anweisungen für KI-Coding-Agenten

Bei der Generierung und Bearbeitung von Code in diesem Repository sind folgende Punkte strikt zu beachten:

1. Modularität: Jede neue Route muss im entsprechenden Blueprint (routes/auth.py, routes/api.py, routes/admin.py) registriert werden.
2. ORM-Pflicht: Datenbankzugriffe ausschließlich über Flask-SQLAlchemy durchführen. Schema-Änderungen über Flask-Migrate anlegen.
3. Header & PyDoc: Alle neu erstellten Dateien müssen den Kopf gemäß docs/coding-standards.md tragen. PyDoc-Docstrings sind für Funktionen Pflicht.
4. Git-Branching: Entwicklung erfolgt ausschließlich auf dem Branch main. Merges auf stable sind der CI/CD-Pipeline vorbehalten.