chmln-app-dev/formeleon
5
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
formeleon/.continue/rules/CONTINUE.md
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 Permalink 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!

  1. Sprache:
    • Code (Variablen, Funktionen, Modulnamen, Code-Kommentare): Englisch.
    • Dokumentation (Markdown, umfangreiche Architektur-Dokus): Deutsch.
  2. 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.
  3. 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.
  4. Datenbank & ORM:
    • Zugriff NIEMALS direkt über Roh-SQL.
    • AUSSCHLIESSLICH über Flask-SQLAlchemy arbeiten.
    • Schema-Änderungen über Flask-Migrate (flask db migrate) abbilden.
  5. Git & Branching:
    • Entwicklung erfolgt ausschließlich auf dem Branch main.
    • Merges auf stable sind der CI/CD-Pipeline vorbehalten.
  6. 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)

Reference in new issue View Git Blame Copy Permalink