br
5fff17531d
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.
160 lines
5.1 KiB
Markdown
160 lines
5.1 KiB
Markdown
# Formeleon 🦎
|
||
|
||
> Mandantenfähiger, hochflexibler Formular-Generator mit nahtloser Website-Integration und integriertem Bot-Schutz.
|
||
|
||
*Read this in English: [README.EN.md](./README.EN.md)*
|
||
|
||
---
|
||
|
||
## 📋 Überblick
|
||
|
||
Formeleon ist ein zentral gehosteter Service (ChamäleonCloud), der es Webseitenbetreibern (Mandanten) ermöglicht, dynamische Formulare ohne Backend-Aufwand per HTML/JavaScript-Snippet in bestehende Webseiten einzubetten.
|
||
|
||
### Kern-Features
|
||
* **Nahtlose Integration:** Einbettung via JS-Snippet ("Chamäleon-Effekt").
|
||
* **Maximale Feldvariabilität:** Dynamische JSON-Payloads via SQLite/SQLAlchemy.
|
||
* **Integrierte Sicherheit:** OIDC-Integration (Zitadel), Public-Key Handshake, Origin/Referer-Validierung & reCAPTCHA v3 Support.
|
||
* **UX & Bot-Protection:** Integriertes Ampel-System (Laderad/Clearance) für Absende-Buttons.
|
||
* **Reporting & Export:** Daten-Exports (CSV/JSON/YAML) per Stream oder automatisierte E-Mail-Dumps.
|
||
|
||
---
|
||
|
||
## 🛠️ Tech-Stack
|
||
|
||
* **Backend:** Python 3.13, Flask (Blueprint-Architektur), Flask-SQLAlchemy, Flask-Migrate (Alembic)
|
||
* **Frontend (Admin-Panel):** Bootstrap 5, Mithril.js / HTML5
|
||
* **Authentication:** OIDC via Zitadel (Admin-Panel)
|
||
* **Deployment:** Docker, Gunicorn, Gitea Actions (Runner)
|
||
|
||
---
|
||
|
||
## 🚀 Schnellstart (Lokal / Docker-less)
|
||
|
||
Das Projekt kann auf Windows/Linux komplett ohne Docker in einer Virtual Environment entwickelt werden:
|
||
|
||
1. **Repository klonen & Umgebung einrichten:**
|
||
```bash
|
||
python -m venv venv
|
||
|
||
# Auf Linux/Mac:
|
||
source venv/bin/activate
|
||
# Auf Windows:
|
||
venv\Scripts\activate
|
||
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
2. **Umgebungsvariablen (optional):**
|
||
*(Formeleon startet standardmäßig im Dev-Mode mit einer lokalen SQLite-DB `formeleon.db`)*
|
||
|
||
3. **Datenbank initialisieren & starten:**
|
||
```bash
|
||
# Migration-Repository initialisieren (nur einmalig!)
|
||
flask db init
|
||
|
||
# Datenbank-Schema erstellen
|
||
flask db upgrade
|
||
|
||
# Optionales Seeding mit Testdaten
|
||
flask seed-db
|
||
|
||
# Anwendung starten (auf Port 5000 mit Hot-Reload)
|
||
flask run --port=5000 --debug
|
||
```
|
||
|
||
---
|
||
|
||
## 🐳 Schnellstart (Docker)
|
||
|
||
Für das vollständige Linux- / Staging-Gefühl kannst du Docker nutzen. Durch Volume-Mounts bleibt der Code synchron, und du kannst im Editor (Windows/Mac) programmieren.
|
||
|
||
```bash
|
||
# 1. Image bauen und Container starten
|
||
docker compose up --build
|
||
|
||
# 2. Anwendung beenden
|
||
# (Strg+C oder:)
|
||
docker compose down
|
||
|
||
# 3. Datenbank und Volumes komplett zurücksetzen
|
||
docker compose down -v && docker-compose up --build
|
||
```
|
||
|
||
### Docker CLI-Kommandos ausführen
|
||
Du kannst `flask` Kommandos direkt gegen den laufenden Container feuern:
|
||
|
||
```bash
|
||
# Datenbank Migrationen anlegen
|
||
docker compose run --rm app flask db migrate -m "neue migration"
|
||
|
||
# Datenbank-Schema updaten
|
||
docker compose run --rm app flask db upgrade
|
||
|
||
# Datenbank mit Testdaten füllen
|
||
docker compose run --rm app flask seed-db
|
||
|
||
# Shell im Container öffnen
|
||
docker compose run --rm app bash
|
||
```
|
||
|
||
### Zugriff auf die Anwendung
|
||
- **Admin Dashboard:** http://localhost:5000/admin/
|
||
- **API Endpunkt:** http://localhost:5000/api/v1/
|
||
- **Health Check:** http://localhost:5000/
|
||
|
||
---
|
||
|
||
## 🌍 Mehrsprachigkeit (i18n) via Flask-Babel
|
||
|
||
Das Admin-Dashboard von Formeleon unterstützt Mehrsprachigkeit (aktuell Deutsch und Englisch). Wir nutzen dafür den Standard `Flask-Babel` (gettext).
|
||
|
||
### 1. Texte im Code markieren
|
||
Damit das System erkennt, dass ein Text übersetzt werden soll, muss er im Python- oder HTML-Code mit der Funktion `_()` umschlossen werden.
|
||
|
||
**In HTML (Jinja2 Templates):**
|
||
```html
|
||
<!-- Vorher -->
|
||
<h1>Welcome to the Dashboard</h1>
|
||
|
||
<!-- Nachher -->
|
||
<h1>{{ _('Welcome to the Dashboard') }}</h1>
|
||
```
|
||
|
||
**In Python-Dateien:**
|
||
```python
|
||
from flask_babel import _
|
||
|
||
# Vorher
|
||
flash('Form saved successfully!', 'success')
|
||
|
||
# Nachher
|
||
flash(_('Form saved successfully!'), 'success')
|
||
```
|
||
|
||
### 2. Der Übersetzungs-Workflow (CLI)
|
||
Wenn neue Texte im Code markiert wurden, müssen diese extrahiert und die Sprachdateien aktualisiert werden.
|
||
Führe dazu folgende Befehle bei aktivierter virtueller Umgebung (`source venv/bin/activate`) aus:
|
||
|
||
```bash
|
||
# 1. Sammelt alle markierten Strings aus dem Code und erstellt die Vorlage (messages.pot)
|
||
pybabel extract -F babel.cfg -k _l -o messages.pot routes services templates utils
|
||
|
||
# 2. Gleicht die neue Vorlage mit den bestehenden Übersetzungen (im Ordner 'translations') ab, ohne alte zu überschreiben
|
||
pybabel update -i messages.pot -d translations
|
||
|
||
# -> JETZT öffnest du z.B. translations/de/LC_MESSAGES/messages.po in einem Texteditor und trägst deine Übersetzungen bei msgstr "" ein! <-
|
||
|
||
# 3. Kompiliert die .po Textdateien in pfeilschnelle .mo Maschinendateien für den Webserver
|
||
pybabel compile -d translations
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 Dokumentation
|
||
|
||
* [`AGENTS.md`](./AGENTS.md) – Regelwerk und Anweisungen für KI-Coding-Agenten.
|
||
* [`ARCHITEKTUR.md`](./ARCHITEKTUR.md) – Detaillierte Systemarchitektur und Datenmodelle.
|
||
* [`docs/coding-standards.md`](./docs/coding-standards.md) – Header- und PyDoc-Dokumentationsstandards.
|
||
* [`docs/deployment.md`](./docs/deployment.md) – CI/CD-Pipeline und Docker-Deployment-Guide.
|
||
* [`docs/dev-guide.md`](./docs/dev-guide.md) – Entwickler-Handbuch, Mocking & Seeding.
|