chmln-app-dev/formeleon

0 Fork 0

Files

T

br 5fff17531d

Formeleon Deployment Pipeline / Deploy to Dev Environment (push) Successful in 1m1s

Details

Formeleon Deployment Pipeline / Deploy to Production Environment (push) Skipped

Details

i18 drin

mail drin
fehlende routen drin
prod-reife erreicht.
TODOS:

Deine aktuellen offenen TODOs
1. Rate-Limiting (Spam-Schutz VOR dem reCAPTCHA)
Das reCAPTCHA hält zwar Bots ab, aber wenn jemand böswillig ein Script schreibt, das 1.000 POST-Requests pro Sekunde an /api/v1/submissions sendet, muss dein Backend jedes Mal Google kontaktieren und die Datenbank befragen. Das frisst Server-Ressourcen.

Todo: Einbinden von Flask-Limiter und Absichern der API-Route (z.B. max. 10 Submissions pro Minute pro IP-Adresse oder Tenant).
2. Billing & Feature-Enforcement (Limits pro Tenant durchsetzen)
Die Mandanten-Architektur und das config-Feld im JSON existieren bereits. Aber wir erzwingen diese Limits aktuell nicht im Backend.

Todo: Im Dashboard (templates/admin/tenants/view.html) UI-Controls einbauen, um Feature-Flags für einen Tenant festzulegen:
max_forms (z.B. 1 für Free-User, 10 für Pro-User).
allow_instant_mail (Dürfen E-Mails an den Tenant gesendet werden?).
allow_autoresponder (Darf der Autoresponder für Endkunden genutzt werden?).
Todo: Diese Limits hart im Backend (beim Erstellen von Forms und beim Mailversand) kontrollieren. (Der Mailer prüft das zwar schon halbwegs, das UI zum Pflegen fehlt aber noch komplett).
3. E-Mail Templates aufwerten (HTML statt Plain-Text)
Bisher versendet der Service E-Mails als reinen Text (plain). Für eine professionelle SaaS-Lösung sollten diese Mails ansprechend aussehen.

Todo: Im services/mailer.py den MIMEMultipart so erweitern, dass er saubere HTML-Mails aus einem Jinja2-Template (templates/emails/...) generiert, inklusive Branding/Logo deines Services.
4. Frontend-Snippet "Graceful Degradation"
Das embed.js arbeitet aktuell sehr gut. Aber was ist, wenn das Formeleon-Backend mal für 5 Minuten down ist?

Todo: Einen sauberen Timeout im fetch einbauen und dem Endkunden auf der Webseite eine schöne, fallback HTML-Meldung anzeigen ("Entschuldigung, das Formular ist momentan nicht erreichbar"), anstatt dass sich das Script lautlos in der Console mit einem CORS/Network-Error verabschiedet.
5. CI/CD Pipeline (Deployment)
Wenn der Code fertig ist, willst du ihn sicher nicht immer händisch per git pull auf deinen Produktionsserver schieben und dort docker compose up tippen.

Todo: Eine simple Pipeline (Github Actions / Gitea Actions) anlegen, die den Code testet und automatisch auf dem Zielserver ausrollt.

2026-09-29 05:16:01 +02:00

6.0 KiB

Raw Blame History

name, description

name	description
Formeleon Rules	Projekt-Richtlinien für Formeleon

Formeleon - Projekt Leitfaden (CONTINUE.md)

Willkommen im Formeleon Projekt! Diese Datei dient als Leitfaden und Regelwerk für Entwickler und KI-Assistenten (wie Continue.dev), die an dieser Codebasis arbeiten.

1. Projektübersicht

Formeleon ist ein mandantenfähiges Formular-Service-System (Multi-tenant Form Generator & Backend API). Es dient dazu, Formular-Submissions von externen Mandanten-Webseiten entgegenzunehmen, diese vor Bot-Spam zu schützen (via Google reCAPTCHA v3), die Daten isoliert nach Mandanten zu speichern und ein Admin-Dashboard zur Verwaltung bereitzustellen.

Kern-Technologien:

Backend: Python 3, Flask
Datenbank: PostgreSQL/SQLite via Flask-SQLAlchemy, Migrationen via Flask-Migrate
Authentifizierung: Zitadel via OIDC (OAuth2)
Frontend (Admin): Mithril.js, Bootstrap (CSS)
Frontend (Public): Leichtgewichtiges JS-Embed-Snippet
Infrastruktur: Docker / Docker Compose

Architektur-Ansatz: Das Backend ist entkoppelt und nutzt das Flask Blueprint-Muster.

api: Public Form API für das Entgegennehmen von Daten.
admin: Dashboard zur Verwaltung.
auth: OIDC/Zitadel Handler.

2. Erste Schritte (Getting Started)

Voraussetzungen

Docker & Docker Compose (für die einfachste lokale Umgebung)
Python 3.x (für lokale Entwicklung ohne Docker)
Eine .env Datei (Basis: docs/dev-guide.md für Mocking/Dev-Variablen)

Lokale Entwicklung & Ausführung

Die Anwendung kann typischerweise über Docker Compose gestartet werden:

docker-compose up --build

Weitere Details zur Einrichtung der Umgebung und Dev-Mocks (z.B. Mock-reCAPTCHA-Scores oder Dev-Bypass für OIDC) finden sich in docs/dev-guide.md.

3. Projektstruktur

Der Code ist modular (Blueprint-Muster) strukturiert. Es gibt keine monolithische app.py für die Routen-Logik.

app.py: Anwendungs-Initialisierung & Blueprint-Registrierung.
models.py: SQLAlchemy Datenmodelle.
routes/: Flask Blueprints.
- api.py (@api_bp): Public Submissions & Handshake.
- admin.py (@admin_bp): Admin Panel & Config.
- auth.py (@auth_bp): OIDC / Zitadel Handler.
services/: Ausgelagerte Geschäftslogik.
- recaptcha.py: reCAPTCHA Validation & Mocking.
- exporter.py: Stream-Export Logik (CSV/JSON/YAML).
- mailer.py: E-Mail Versand.
static/: Frontend Assets (JS Snippets, Mithril.js Admin UI, CSS).
docs/: Umfangreiche Projektdokumentation.
AGENTS.md: Wichtige Instruktionen für KI-Assistenten.
ARCHITEKTUR.md: Detaillierte Systemarchitektur.

4. Entwicklungs-Workflow & Code-Standards

DIESE REGELN SIND VERBINDLICH FÜR ALLE ENTWICKLER UND KI-AGENTEN!

Sprache:
- Code (Variablen, Funktionen, Modulnamen, Code-Kommentare): Englisch.
- Dokumentation (Markdown, umfangreiche Architektur-Dokus): Deutsch.
Dateiköpfe: Jede neu erstellte oder modifizierte Quelltext-Datei (.py, .j2, .html, .js, .css) MUSS den standardisierten Dateikopf tragen.
- Autor: Björn Runden <br@runden.net>
- Siehe genaue Formate in docs/coding-standards.md.
Dokumentationspflicht (PyDoc & Jinja2):
- Jede Klasse, Funktion und Methode in Python muss PyDoc-Docstrings erhalten.
- Logikführende Jinja2-Templates (Schleifen, Makros, etc.) müssen kommentiert werden.
Datenbank & ORM:
- Zugriff NIEMALS direkt über Roh-SQL.
- AUSSCHLIESSLICH über Flask-SQLAlchemy arbeiten.
- Schema-Änderungen über Flask-Migrate (flask db migrate) abbilden.
Git & Branching:
- Entwicklung erfolgt ausschließlich auf dem Branch main.
- Merges auf stable sind der CI/CD-Pipeline vorbehalten.
Modularität:
- Neue Routen müssen im entsprechenden Blueprint (routes/auth.py, routes/api.py, routes/admin.py) registriert werden.

5. Schlüsselkonzepte & Datenmodell

Multi-Tenancy (Mandantenfähigkeit): Logische Trennung auf Datenbankebene über tenant_id (FormConfig, Submission, User).
Public Keys: Format pk_live_<hash>. Enthalten intern einen SHA-basierten Verweis auf die tenant_id.
Flexible Payloads: Formulardaten werden in einem JSON-Payload-Feld (Submission.Payload) gespeichert, um Schema-Migrationen bei Formularänderungen zu vermeiden.
RBAC (Role-Based Access Control): Lokale Rechteverwaltung in der DB (admin, tenant_admin, user, viewer) verknüpft über die E-Mail-Adresse. Zitadel (OIDC) liefert nur Identität (Kein Rollen-Mapping aus Token-Claims!).
Bot-Schutz: Google reCAPTCHA v3. Schwellenwert konfigurierbar. Unter Schwellenwert wird die Submission als flagged_as_spam gespeichert und ein HTTP 400 zurückgegeben.

6. Frontend Einbindung (Das Embed Snippet)

Mandanten binden das Formular wie folgt ein:

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

Das Snippet (static/js/...) nutzt die Fetch API für einen Handshake (prüft Origin), injiziert das HTML direkt ins DOM und fängt das Submit-Event ab, um ein reCAPTCHA Token zu holen und die Daten an /api/v1/... zu senden.

7. Referenzen & Weiterführende Dokumentation

Bevor du spezifische Module bearbeitest, lies bitte die entsprechenden Detail-Dokumente:

KI-Agenten Steuerzentrale: AGENTS.md
System-Architektur & DB: ARCHITEKTUR.md
Feinkonzept & Spezifikation: docs/feinkonzept.md
Header & PyDoc Standards: docs/coding-standards.md
Dev-Environment & Mocks: docs/dev-guide.md
CI/CD & Deployment: docs/deployment.md
Git-Workflow: docs/git-workflow.md

(Hinweis: Für konkrete Troubleshooting-Fälle, lies bitte die jeweiligen Markdown-Dateien im docs/ Verzeichnis, z.B. bezüglich der Entwicklungsumgebung in der dev-guide.md)

6.0 KiB Raw Blame History