358 lines
16 KiB
Markdown
358 lines
16 KiB
Markdown
# BreznFlow
|
||
|
||
|
||
|
||
|
||
|
||
|
||
🇬🇧 [English version → README.md](README.md)
|
||
|
||
---
|
||
|
||
BreznFlow ist ein WordPress-Plugin, das n8n-Automations-Workflows als interaktive SVG-Diagramme rendert — direkt in Beiträgen und Seiten. Workflow-JSON einfügen, und das Plugin erzeugt ein zoombares, klickbares Diagramm mit Node-Detail-Panel, automatischer Maskierung sensibler Daten und farbcodierten Node-Icons.
|
||
|
||
Keine externen Abhängigkeiten. Kein CDN. Kein Tracking. Vanilla JavaScript. Ein Shortcode: `[breznflow id="X"]`.
|
||
|
||
---
|
||
|
||
## Warum dieses Plugin existiert
|
||
|
||
n8n-Workflows sind mächtig, aber visuell teilen ist überraschend schwierig. Screenshots sind statisch und veralten schnell. Den n8n-Editor einzubetten ist unpraktisch. JSON in einen Blogpost kopieren ist unlesbar.
|
||
|
||
BreznFlow löst das, indem es den rohen JSON-Export in ein interaktives Diagramm verwandelt — die gleichen Nodes, die gleichen Verbindungen, aber als sauberes SVG innerhalb von WordPress gerendert. Leser können zoomen, pannen und jeden Node anklicken, um seine Parameter zu sehen.
|
||
|
||
Entwickelt in Passau, Bayern — für [mifupa.com](https://mifupa.com), einem persönlichen Blog, auf dem regelmäßig n8n-Automationen vorgestellt werden und eine bessere Darstellung brauchten.
|
||
|
||
---
|
||
|
||
## Inhaltsverzeichnis
|
||
|
||
- [Warum dieses Plugin existiert](#warum-dieses-plugin-existiert)
|
||
- [Verzeichnisstruktur](#verzeichnisstruktur)
|
||
- [Features](#features)
|
||
- [Datenspeicherung](#datenspeicherung)
|
||
- [Sicherheit](#sicherheit)
|
||
- [Shortcode](#shortcode)
|
||
- [Installation](#installation)
|
||
- [Technischer Stack](#technischer-stack)
|
||
- [Lizenz](#lizenz)
|
||
|
||
---
|
||
|
||
## Verzeichnisstruktur
|
||
|
||
```
|
||
breznflow/
|
||
├── breznflow.php # Plugin-Header, Konstanten (BREZNFLOW_VERSION, BREZNFLOW_DIR, BREZNFLOW_URL)
|
||
├── uninstall.php # Aufräumen bei Plugin-Löschung
|
||
├── readme.txt # WordPress.org Plugin-Readme
|
||
├── assets/
|
||
│ ├── admin.css # Admin-Stylesheet (Wizard, Settings, Listtable)
|
||
│ ├── admin.js # Admin-JavaScript (Wizard-Schritte, JSON-Validierung)
|
||
│ ├── renderer.css # Frontend SVG-Renderer Styles
|
||
│ ├── renderer.js # Frontend-Renderer (SVG-Engine, Pan/Zoom, Detail-Panel)
|
||
│ ├── brezn.css # Legacy Brezn-Theme (Kompatibilität)
|
||
│ └── themes/
|
||
│ ├── dark.css # Dark-Theme (Standard)
|
||
│ ├── light.css # Light-Theme
|
||
│ ├── minimal.css # Minimal-Theme
|
||
│ ├── tech.css # Tech-Theme
|
||
│ └── brezn.css # Brezn-Theme
|
||
├── includes/
|
||
│ ├── Core.php # Singleton-Bootstrap, lädt alle Abhängigkeiten
|
||
│ ├── PostType.php # CPT breznflow_workflow + Taxonomie breznflow_category
|
||
│ ├── Shortcode.php # [breznflow] Shortcode mit 13 Attributen
|
||
│ ├── DownloadHandler.php # JSON-Download-Endpunkt (?breznflow_download={id})
|
||
│ ├── EmbedHandler.php # Standalone Embed-Seite (?breznflow_embed={id})
|
||
│ ├── Admin/
|
||
│ │ ├── AdminMenu.php # Menüstruktur + Dashboard-Render
|
||
│ │ ├── SettingsPage.php # Plugin-Einstellungen (16 Optionen, validiert)
|
||
│ │ ├── ThemesPage.php # Theme-Verwaltung (Import/Löschen eigener Themes)
|
||
│ │ ├── WizardPage.php # 3-Schritt Import-Wizard (Einfügen/Upload → Konfigurieren → Vorschau)
|
||
│ │ ├── WorkflowListTable.php # WP_List_Table für Workflow-Verwaltung
|
||
│ │ └── views/ # PHP-Templates für alle Admin-Seiten
|
||
│ ├── Features/
|
||
│ │ ├── NodeTypeRegistry.php # 86 Node-Typen mit Markenfarben und Icons
|
||
│ │ ├── NodeCategorizer.php # Kategorisiert Nodes (Trigger, Action, Logic, AI, etc.)
|
||
│ │ ├── InfoBoxBuilder.php # „3× HTTP Request, 2× Code" Node-Zusammenfassung
|
||
│ │ ├── ViewCounter.php # View-Zähler pro Workflow
|
||
│ │ ├── RelatedWorkflows.php # Ähnliche Workflows nach gemeinsamen Node-Typen
|
||
│ │ ├── ThemeRegistry.php # 5 Built-in-Themes + Custom-Theme-Support
|
||
│ │ └── ThemeImporter.php # Import/Export von .breznflow.json Theme-Dateien
|
||
│ └── Security/
|
||
│ ├── MaskingRules.php # Secret-Erkennung (URL-Parameter, Header, Entropie)
|
||
│ ├── WorkflowValidator.php # JSON-Schema-Validierung für n8n-Exporte
|
||
│ └── WorkflowSanitizer.php # Zwei-Pass-Sanitierung: Strings + Secret-Maskierung
|
||
└── languages/
|
||
├── breznflow.pot # Übersetzungsvorlage
|
||
├── breznflow-de_DE.po # Deutsche Übersetzung
|
||
└── breznflow-de_DE.mo # Kompilierte deutsche Übersetzung
|
||
```
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
### Interaktiver SVG-Renderer
|
||
|
||
Das Herzstück von BreznFlow. Jeder n8n-Node wird zu einem klickbaren SVG-Element mit farbcodierten Icons, Verbindungslinien und Labels. Der Renderer unterstützt:
|
||
|
||
- **Pan & Zoom** — Mausrad zoomt zur Cursorposition, Klick-Drag zum Verschieben
|
||
- **Node-Klick** — öffnet das Detail-Panel unterhalb des Diagramms mit allen Node-Parametern
|
||
- **Auto-Fit** — Workflows über einem konfigurierbaren Node-Schwellenwert (Standard: 30) zoomen automatisch zum Trigger-Node beim Laden
|
||
- **Minimap** — optionales Minimap-Overlay zur Navigation in großen Workflows
|
||
- **Vollbild** — Portal-basierter Vollbildmodus
|
||
|
||
Alles wird clientseitig in Vanilla JavaScript gerendert — kein Canvas, kein WebGL, keine externen Bibliotheken.
|
||
|
||
---
|
||
|
||
### 3-Schritt Import-Wizard
|
||
|
||
1. **Einfügen oder hochladen** — JSON direkt einfügen, `.json`-Datei hochladen oder von URL abrufen
|
||
2. **Konfigurieren** — Darstellungsmodus, Theme, Zoom, Titel, Kategorien einstellen
|
||
3. **Vorschau** — Live-SVG-Vorschau mit Maskierungs-Zusammenfassung vor dem Veröffentlichen
|
||
|
||
Der Wizard validiert JSON gegen das n8n-Schema, sanitiert alle Strings und maskiert erkannte Geheimnisse. Das Maskierungs-Protokoll zeigt genau, was entfernt wurde und warum.
|
||
|
||
**Import von URL:** Ruft Workflow-JSON von beliebigen öffentlichen URLs per `wp_remote_get()` ab. Anfragen an private/interne Netzwerkadressen (localhost, LAN-Bereiche, Cloud-Metadaten-Endpunkte) werden blockiert.
|
||
|
||
---
|
||
|
||
### Node Type Registry
|
||
|
||
86 vordefinierte Node-Typen mit markengetreuen Farben und 2-Buchstaben-Icons:
|
||
|
||
| Kategorie | Beispiele |
|
||
|---|---|
|
||
| Trigger | Schedule, Webhook, Manual, Form |
|
||
| Kernlogik | HTTP Request, Code, IF, Switch, Merge, Filter |
|
||
| Datentransformation | HTML, XML, Markdown, Crypto |
|
||
| Datenbanken | MySQL, PostgreSQL, Redis, MongoDB, SQLite, Supabase |
|
||
| Kommunikation | Slack, Telegram, Discord, Gmail, WhatsApp |
|
||
| Google | Sheets, Drive, Calendar, Docs, YouTube |
|
||
| Dev-Tools | GitHub, GitLab, Jira, Confluence, Linear, Notion |
|
||
| KI | OpenAI, Claude, Gemini, Ollama, Hugging Face, Mistral, LangChain |
|
||
| Speicher | FTP, SSH, Airtable, Baserow |
|
||
| CRM/Marketing | HubSpot, Salesforce, Mailchimp, Brevo |
|
||
|
||
Unbekannte Node-Typen bekommen einen deterministischen Fallback: 2-Buchstaben-Initialen und eine Farbe aus einem djb2-Hash — der gleiche unbekannte Typ sieht immer gleich aus.
|
||
|
||
---
|
||
|
||
### Theme-System
|
||
|
||
5 Built-in-Themes: **Dark** (Standard), **Light**, **Minimal**, **Tech**, **Brezn**.
|
||
|
||
Eigene Themes können als `.breznflow.json`-Dateien mit 41 CSS-Farbtokens importiert werden. Custom-Themes werden in `wp_options` gespeichert und als Inline-CSS-Variablen gerendert.
|
||
|
||
Themes sind global, pro Workflow oder pro Shortcode wählbar via `theme="dark"`.
|
||
|
||
---
|
||
|
||
### Action Bar
|
||
|
||
Unterhalb des Diagramms (nicht im Compact-Modus) bietet die Action Bar:
|
||
|
||
| Aktion | Steuerung | Funktion |
|
||
|---|---|---|
|
||
| **Share** | Globale Einstellung | Zeigt Artikel-Link + Anker-Link für Hash-Navigation |
|
||
| **Embed** | Global + pro Post | Zeigt iframe-Embed-Code für Standalone-Einbettung |
|
||
| **Get JSON** | Globale Einstellung | Zeigt formatiertes JSON mit Größe in KB |
|
||
| **Download** | Global + pro Post | Lädt sanitiertes JSON als Datei herunter |
|
||
|
||
Jede Aktion ist global in den Einstellungen steuerbar und per Shortcode überschreibbar.
|
||
|
||
---
|
||
|
||
### Maskierung sensibler Daten
|
||
|
||
BreznFlow speichert nie das rohe Workflow-JSON. Vor dem Speichern läuft eine Zwei-Pass-Sanitierung:
|
||
|
||
**Pass 1 — String-Sanitierung:** Alle Strings durchlaufen `sanitize_text_field()`. Ausnahme: `jsCode`-Felder bleiben erhalten, werden aber mit `esc_html()` ausgegeben (nie ausgeführt).
|
||
|
||
**Pass 2 — Secret-Erkennung:**
|
||
|
||
- **URL-Parameter:** `api_key`, `token`, `secret`, `password`, `access_token`, `auth`, `client_secret` in Query-Strings → `[REDACTED]`
|
||
- **Header-Werte:** Authorization, Bearer, X-API-Key und ähnliche Header-Namen in `{name, value}`-Paaren → Wert maskiert
|
||
- **Hochentropie-Bedingungen:** Werte in IF/Switch-Conditions, die UUID-Muster, Groß-/Kleinschreibung+Ziffern oder lange Strings ohne Leerzeichen matchen → per Entropie-Heuristik maskiert
|
||
|
||
Ein **Maskierungs-Protokoll** zeichnet jedes maskierte Element mit Grund, Key und Hinweis auf — sichtbar in der Wizard-Vorschau (Schritt 3).
|
||
|
||
---
|
||
|
||
### Darstellungsmodi
|
||
|
||
| Modus | Was angezeigt wird |
|
||
|---|---|
|
||
| `visual` | Vollständiges Diagramm mit Toolbar, Detail-Panel, Action Bar |
|
||
| `info` | Nur Node-Zähler (InfoBox) — kein Diagramm |
|
||
| `compact` | Diagramm ohne Toolbar und Action Bar |
|
||
|
||
Konfigurierbar global, pro Workflow oder pro Shortcode.
|
||
|
||
---
|
||
|
||
### Embed-Handler
|
||
|
||
Liefert eine Standalone-HTML-Seite unter `?breznflow_embed={id}` für iframe-Einbettung. Die Seite enthält nur den SVG-Renderer — kein WordPress-Theme, keine Admin-Bar.
|
||
|
||
**Dual-Gate-Sicherheit:** Sowohl die globale `allow_embed`-Einstellung als auch das Per-Post-Meta `_breznflow_show_embed` müssen aktiviert sein.
|
||
|
||
URL-Parameter: `?theme={id}` und `?minimap=0|1`.
|
||
|
||
HTTP-Header enthalten `X-Robots-Tag: noindex, nofollow` und entfernen `X-Frame-Options` für Embedding.
|
||
|
||
---
|
||
|
||
### Weitere Features
|
||
|
||
- **View-Zähler** — zählt, wie oft jeder Workflow angezeigt wird
|
||
- **Ähnliche Workflows** — zeigt verwandte Workflows nach gemeinsamen Node-Typen
|
||
- **InfoBox** — kompakte Zusammenfassung wie „3× HTTP Request, 2× Code, 1× OpenAI"
|
||
- **KI-Erkennung** — erkennt und markiert automatisch Workflows mit KI-Nodes
|
||
- **Schema.org HowTo** — optionale JSON-LD-Strukturdatenausgabe
|
||
- **Anker-Navigation** — `<span id="breznflow-{id}">` für Hash-basiertes Deep-Linking mit 60px Scroll-Offset
|
||
|
||
---
|
||
|
||
## Datenspeicherung
|
||
|
||
### WordPress Options (wp_options)
|
||
|
||
| Option-Key | Inhalt |
|
||
|---|---|
|
||
| `breznflow_settings` | Alle Plugin-Einstellungen (16 Keys, serialisiertes Array) |
|
||
| `breznflow_custom_themes` | Custom-Theme-Definitionen (serialisiertes Array) |
|
||
|
||
### Post Meta (wp_postmeta)
|
||
|
||
| Meta-Key | Inhalt |
|
||
|---|---|
|
||
| `_breznflow_raw_json` | Sanitiertes Workflow-JSON (nie das Roh-Original) |
|
||
| `_breznflow_original_name` | Originaler Workflow-Name aus n8n |
|
||
| `_breznflow_node_count` | Gesamtzahl der Nodes |
|
||
| `_breznflow_node_summary` | Kategorisierte Node-Anzahl (JSON) |
|
||
| `_breznflow_has_ai_nodes` | Ob der Workflow KI-Nodes enthält |
|
||
| `_breznflow_ai_node_types` | Liste der KI-Node-Typen (JSON) |
|
||
| `_breznflow_mask_log` | Maskierte Werte beim Import (JSON) |
|
||
| `_breznflow_default_zoom` | Zoom-Level pro Workflow (10–200) |
|
||
| `_breznflow_show_title` | Titel anzeigen |
|
||
| `_breznflow_show_infobox` | InfoBox anzeigen |
|
||
| `_breznflow_show_download` | Download erlauben |
|
||
| `_breznflow_show_embed` | Einbettung erlauben |
|
||
| `_breznflow_show_minimap` | Minimap anzeigen |
|
||
| `_breznflow_default_mode` | Darstellungsmodus |
|
||
| `_breznflow_default_theme` | Theme-ID |
|
||
|
||
### Uninstall-Cleanup
|
||
|
||
`uninstall.php` löscht bei Plugin-Deinstallation:
|
||
- Alle `breznflow_workflow`-Posts und deren Meta
|
||
- Option `breznflow_settings`
|
||
- Alle `breznflow_category`-Taxonomie-Terms
|
||
- Alle Transients mit Präfix `breznflow_`
|
||
|
||
---
|
||
|
||
## Sicherheit
|
||
|
||
### Eingabevalidierung
|
||
|
||
- Workflow-JSON wird vor dem Import gegen das n8n-Schema validiert
|
||
- Alle `$_POST` / `$_GET`-Werte über `wp_unslash()` + spezifische Sanitizer verarbeitet
|
||
- Alle Ausgaben escaped mit `esc_html`, `esc_attr`, `esc_url`
|
||
- SQL-Queries ausschließlich via `$wpdb->prepare()`
|
||
|
||
### CSRF-Schutz
|
||
|
||
Jede Admin-Aktion validiert eine WordPress-Nonce. Capability-Checks erfordern `manage_options` für Einstellungen und `edit_posts` für Workflow-Verwaltung.
|
||
|
||
### Download- & Embed-Sicherheit
|
||
|
||
Beide Endpunkte validieren:
|
||
1. Post existiert, ist Typ `breznflow_workflow` und Status `publish`
|
||
2. Die entsprechende Per-Post-Meta-Berechtigung ist aktiviert
|
||
3. Die globale Einstellung ist aktiviert
|
||
4. Das gespeicherte JSON ist valide
|
||
|
||
Response-Header enthalten `X-Content-Type-Options: nosniff`. Downloads nutzen `Cache-Control: no-store`.
|
||
|
||
### Import von URL
|
||
|
||
Das „Von URL abrufen"-Feature im Wizard blockiert Anfragen an private/interne Netzwerkadressen (localhost, `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, Cloud-Metadaten-Endpunkte) zur Verhinderung von SSRF-Angriffen.
|
||
|
||
---
|
||
|
||
## Shortcode
|
||
|
||
```
|
||
[breznflow id="42"]
|
||
[breznflow id="42" mode="compact" theme="light" zoom="80"]
|
||
[breznflow id="42" show_share="0" show_embed="1" show_minimap="0"]
|
||
```
|
||
|
||
| Attribut | Standard | Beschreibung |
|
||
|---|---|---|
|
||
| `id` | — | Workflow-Post-ID (erforderlich) |
|
||
| `mode` | `visual` | `visual`, `info` oder `compact` |
|
||
| `theme` | `dark` | Theme-ID |
|
||
| `zoom` | `100` | Initiales Zoom-Level (10–200) |
|
||
| `show_title` | `true` | Workflow-Titel anzeigen |
|
||
| `show_infobox` | `true` | Node-Zusammenfassung anzeigen |
|
||
| `show_minimap` | `true` | Minimap-Overlay anzeigen |
|
||
| `show_download` | `false` | Download-Button anzeigen |
|
||
| `show_share` | `true` | Share-Aktion anzeigen |
|
||
| `show_embed` | `false` | Embed-Aktion anzeigen |
|
||
| `show_get_json` | `false` | „Get JSON"-Aktion anzeigen |
|
||
| `max_code_lines` | `50` | Max. Zeilen in Code-Node-Anzeige |
|
||
|
||
**Auflösungs-Hierarchie:** Shortcode-Attribut → Post-Meta → Plugin-Einstellungen.
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
**Via GitHub Release (empfohlen):**
|
||
1. `breznflow.zip` vom [neuesten Release](https://github.com/noschmarrn/breznflow/releases/latest) herunterladen
|
||
2. In WordPress unter *Plugins → Installieren → Plugin hochladen* einspielen
|
||
|
||
**Manuell (clone):**
|
||
```bash
|
||
cd /path/to/wordpress/wp-content/plugins/
|
||
git clone https://github.com/noschmarrn/breznflow.git
|
||
wp plugin activate breznflow
|
||
```
|
||
|
||
**Nach der Aktivierung:**
|
||
1. *BreznFlow → Workflow hinzufügen*
|
||
2. n8n Workflow-JSON einfügen (oder `.json`-Datei hochladen)
|
||
3. Darstellungseinstellungen konfigurieren und Vorschau prüfen
|
||
4. Veröffentlichen — `[breznflow id="X"]` in beliebigen Beitrag oder Seite einfügen
|
||
|
||
Kein Build-Step. Alle Assets sind direkte JS/CSS-Dateien.
|
||
|
||
---
|
||
|
||
## Technischer Stack
|
||
|
||
| Komponente | Technologie |
|
||
|---|---|
|
||
| Backend | PHP 8.0+, WordPress Plugin API |
|
||
| Namespace | `BreznFlow\` |
|
||
| Architektur | Singleton-Core, Feature-Klassen mit `register()` |
|
||
| Rendering | Vanilla JavaScript SVG-Generierung (kein Canvas, keine Bibliotheken) |
|
||
| Datenbank | WordPress Options API + Post Meta |
|
||
| Caching | WordPress Transients (Related Workflows) |
|
||
| Frontend | Vanilla JS, kein Build-Step, kein externes CDN |
|
||
| I18n | `.pot`-File, Text-Domain `breznflow` |
|
||
| Coding Standard | WordPress PHPCS |
|
||
| Lizenz | GPL-2.0-or-later |
|
||
|
||
---
|
||
|
||
## Lizenz
|
||
|
||
GPL-2.0-or-later — [https://www.gnu.org/licenses/gpl-2.0.html](https://www.gnu.org/licenses/gpl-2.0.html)
|
||
|
||
Copyright (c) 2025–2026 [mifupa.com](https://mifupa.com)
|