Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M17-automation-engine.md
T

19 KiB
Raw Blame History

module, title, phase, status, last_updated, session_source, related_lps, spec_style
module title phase status last_updated session_source related_lps spec_style
17 Automation Engine 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-3
LP-4
LP-5
LP-6
LP-9
LP-10
LP-11
requirements-pur

Modul 17 — Automation Engine

Detail-Spec gemäß LP-9. USP-Säule. Löst Zapier+n8n+Supabase ab (LP-7). KI als Bedienoberfläche (LP-5). Anti-Agentur-Positionierung (LP-6) durch Klartext-Diagnostik + Selbst-Wartbarkeit.

Themenblöcke

A. Datenmodell (Rule, Step, Execution, Credential, Template)
B. Trigger-Library (Phase 1, Geerkens-fokussiert)
C. Action-Library (Phase 1)
D. Visueller Flow-Editor (Graph-basiert)
E. KI-Erstellung per natürlicher Sprache (LP-5)
F. Dry-Run / Vorschau / Reversibilität (PM-3)
G. Schutz-Mechanismen (Loop-Guard, Rate-Limit, Anomalie-Detection — EC-1, EC-2)
H. Idempotenz + Resume-Mode (EC-3)
I. Templates (Branchen-modular)
J. Klartext-Diagnostik in Execution-Logs (LP-10)
K. Stage-Stuck-Eskalation als Built-in-Cron
L. Trigger-Volumen-Metering (für Pricing)
M. Permissions

Block A — Datenmodell

Architektur-Entscheidung

Graph-basierter Flow ab Phase 1. Knoten + Edges, parallele Branches möglich, Verzweigungen über If/Else. Mehr Komplexität, aber matched alte Codebase + mächtige Use-Cases.

Kern-Entitäten

AutomationRule           — eine Wenn-Dann-Regel pro Tenant
AutomationRuleStep       — einzelne Knoten in einer Rule
AutomationExecution      — Lauf einer Rule
AutomationStepExecution  — pro Step Status + Output
AutomationCredential     — Tenant-Credentials für Action-Knoten
AutomationTemplate       — vorgefertigte Workflows

AutomationRule

  • id, tenant_id, name, description
  • flow_data (JSON — Graph-Struktur: Nodes + Edges, kompatibel mit Flow-Library)
  • enabled (Boolean)
  • created_by_user_id, created_via (manual | template | ki_natural_language)
  • last_executed_at, executions_count_30d
  • archived_at

AutomationRuleStep

  • id, rule_id, step_kind (trigger | condition | action | flow_control)
  • node_type (z.B. deal.stage_changed, condition.field_equals, action.send_email, flow.delay)
  • config (JSON — Knoten-spezifisch)
  • parent_step_ids[] (für Multi-Parent-Merge nach parallelen Branches)
  • position (für Editor-Layout)

AutomationExecution

  • id, tenant_id, rule_id, triggered_at
  • trigger_payload (JSON)
  • status (running | success | partial_success | failed | cancelled)
  • started_at, finished_at
  • summary_text (Klartext)
  • dry_run (Boolean)
  • triggered_by_user_id (nullable)
  • idempotency_key
  • reverse_window_expires_at (24h nach Execution für Undo)

AutomationStepExecution

  • id, execution_id, step_id
  • started_at, finished_at
  • status (pending | running | success | skipped | failed)
  • input (JSON)
  • output (JSON — für Folge-Steps)
  • summary_text (Klartext)
  • error_text (Klartext bei Fehler)
  • idempotency_key

AutomationCredential

  • id, tenant_id, key, value (verschlüsselt at-rest), description
  • Apps aus M33a stellen ihre Connections automatisch zur Verfügung; AutomationCredential nur für nicht-App-Credentials

AutomationTemplate

  • id, tenant_id (NULL bei Plattform-Templates), name, description
  • flow_data (JSON)
  • category
  • is_published, branchen_template_origin

Block B — Trigger-Library (Phase 1, Geerkens-fokussiert)

Pro Trigger: Trigger-Payload-Daten stehen für Folge-Steps zur Verfügung. Multi-Pipeline-Filter bei pipeline-bezogenen Triggern: Pipeline + Stage als Multi-Select.

CRM (M1)

  • contact.created, contact.updated, contact.tag_added

Lead (M2)

  • lead.received (mit Source-Filter), lead.status_changed, lead.assigned

Sales (M3)

  • deal.created (mit Pipeline-Filter)
  • deal.stage_changed (mit Pipeline + From-/To-Stage-Filter)
  • deal.won, deal.lost (mit Pipeline-Filter)
  • deal.stuck.in_stage
  • deal.assignee_changed
  • deal.volume_changed

Projects (M4)

  • project.created (mit Pipeline-Filter)
  • project.stage_changed (mit Pipeline + Stage-Filter)
  • project.completed, project.cancelled (mit Pipeline-Filter)
  • project.stuck.in_stage
  • project.member_added, project.member_removed
  • project.acceptance_completed (mit kind-Filter)
  • schedule_entry.created, schedule_entry.changed, schedule_entry.cancelled

Forms (M5)

  • form.submitted (pro Form auswählbar)

Booking (M6)

  • booking.scheduled, booking.cancelled, booking.held

Email (M9)

  • email.received_inbox (pro Mailbox)
  • email.subject_pattern_matched (Regex)

Telephony (M12)

  • call.inbound_completed
  • call.outbound_completed
  • call.missed

Tasks (M26)

  • task.created, task.assigned, task.completed
  • task.deadline_approaching, task.overdue

Time-based (Built-in)

  • schedule.cron (CRON-Expression)
  • schedule.delay (Folge-Step nach Delay)

KWP (M19)

  • kwp.auftrag_pulled
  • kwp.schema_drift_detected

Apps Engine (M33a)

  • app.connection_status_changed
  • app.sync_failed

HR (M14)

  • hr.vacation_approved
  • hr.sick_leave_reported

Customer Portal (M15)

  • portal.kunde_uploaded_file
  • portal.kunde_replied

Block C — Action-Library (Phase 1)

CRM

  • contact.update, contact.add_tag/remove_tag, contact.assign_to_user

Lead

  • lead.assign_to_user, lead.set_status, lead.promote_to_contact

Sales (mit Pipeline-Targeting)

  • deal.create (mit Ziel-Pipeline + Start-Stage)
  • deal.update_stage (zu konkreter Stage oder semantisch won | lost | next_open)
  • deal.update_volume, deal.assign_to_user, deal.add_tag
  • deal.move_to_pipeline (Deal in andere Pipeline verschieben)

Projects (mit Pipeline-Targeting)

  • project.create (mit Ziel-Pipeline + Start-Stage)
  • project.create_from_won_deal (Won-Handoff mit konfigurierbarer Default-Mapping pro Sales-Pipeline)
  • project.update_stage
  • project.add_member
  • project.create_task
  • project.create_schedule_entry
  • project.start_acceptance
  • project.move_to_pipeline

Communication

  • email.send (mit Template + dynamischen Vars)
  • chat.send_message (in Channel)
  • notification.send_push, notification.send_in_app

Tasks

  • task.create, task.assign_to_user

KWP

  • kwp.push_auftrag

HTTP / External

  • http.request (GET/POST/PUT/DELETE)
  • webhook.send (signiert)

Flow-Control

  • delay, if_else, parallel, merge
  • loop — NICHT in Phase 1 (Loop-Guard-Komplexität)

KI (M18)

  • ai.generate_text, ai.summarize, ai.classify

Calendar (M25)

  • calendar.create_event, calendar.update_event

Files (M23)

  • file.create_from_url

Conditions (für If/Else)

  • Field-Equals / Contains / Greater-Than / Less-Than
  • Tag-Set / Tag-Not-Set
  • Time-Of-Day / Day-Of-Week
  • User-In-Group
  • Custom-JS-Expression — Phase 2 (Sicherheits-Risiko)

SHK-Template-Defaults: Sales-Pipeline → Project-Pipeline (Won-Handoff)

Sales-Pipeline Default-Project-Pipeline
Anlagen-Verkauf Anlagen-Installation
Wartungsverträge Wartungseinsatz

Block D — Visueller Flow-Editor

Editor-Anforderungen (/{tenant}/automations/:id/edit)

Zu zeigende Daten:

  • Canvas mit Graph-Struktur (Knoten + Verbindungen)
  • Sidebar mit Knoten-Catalog (filterbar nach Modul-Quelle)
  • Konfigurations-Bereich für ausgewählten Knoten
  • Mini-Map für große Flows
  • Toolbar: Zoom, Pan, Undo/Redo, Zentrieren, Auto-Layout

Benötigte UI-Elemente:

  • Graph-Canvas-Komponente (Library-Wahl über Boilerplate)
  • Knoten-Catalog-Panel mit Drag-&-Drop oder Klick-Hinzufügen
  • Knoten-Konfigurations-Panel
  • Verbindungs-Erstell-Funktion
  • Validation-Anzeige
  • Test-Run-Funktion (Dry-Run)
  • Save / Activate / Deactivate-Funktion
  • Versionierung-Anzeige (Phase 2)

Operationen:

  • Knoten hinzufügen / konfigurieren / löschen / duplizieren
  • Verbindungen erstellen / löschen
  • Knoten verschieben / Auto-Layout
  • Test-Run mit Sample-Payload
  • Save (versionierter Snapshot)
  • Activate / Deactivate
  • Rule duplizieren

Klartext im Knoten-Label:

  • Trigger: „Wenn Deal in Pipeline ‚Anlagen-Verkauf' → Stage ‚Verhandlung'"
  • Condition: „Wenn Volumen > 10.000 EUR"
  • Action: „Push an Noah G. + Vertriebsleiter"
  • Delay: „Warte 24 Stunden"

Validation-Hinweise:

  • Knoten ohne Verbindung: „Knoten ‚Email senden' ist nicht verbunden — wird nie ausgeführt"
  • Cycle erkannt: „Diese Verbindung würde eine Schleife bilden — bitte anders verkabeln"
  • Knoten unvollständig: „Bei ‚Email senden' fehlt der Empfänger"

Block E — KI-Erstellung per natürlicher Sprache (LP-5)

User sagt z.B.: „Wenn jemand das Kontaktformular ausfüllt und das Volumen über 10.000 EUR ist, schicke mir und dem Vertriebsleiter eine Push-Benachrichtigung und lege den Lead in der Premium-Pipeline an."

KI-Pipeline (intern)

  1. Intent-Klassifikation: neue Automation oder Edit?
  2. Entity-Extraction: Trigger, Filter, Actions
  3. Schema-Validation: existieren referenzierte Pipelines, User, Forms? (EC-4)
  4. Rückfrage bei Mehrdeutigkeit: „Du meinst Klaus Müller (Vertriebsleiter Süd) oder Klaus Schmidt (Bauleiter Nord)?" (EC-4)
  5. Flow-Generierung: Graph-Struktur als JSON
  6. Vorschau-Rendering: Flow im Editor + Klartext-Beschreibung
  7. Risiko-Hinweise: „Achtung: ‚Volumen über 10.000' kann auch bei Wartungsverträgen mit hohem Vertragswert greifen — nur Anlagen-Verkauf-Pipeline einschränken?" (EC-4)

Edit-Mode

Bestehende Automation: „Füge eine Wartezeit von 1 Tag zwischen der Email und der Push-Benachrichtigung ein" → KI baut Diff-Vorschlag.

Sicherheits-Layer

  • Action-Boundary (EC-5): KI führt nicht direkt aus, bereitet Flow vor — Bestätigung Pflicht
  • Schema-Validation vor Vorschau (EC-4)
  • Klartext-Risiko-Hinweise (EC-4)
  • Promptfoo-Eval-Suite als CI-Pflicht (EC-5)

UI-Anforderungen

  • Eingabe-Funktion (Text oder Voice via Whisper-EU M18)
  • Live-Streaming-Antwort
  • Vorschau-Rendering im Flow-Editor
  • Bestätigungs-/Anpassungs-Funktion
  • Beispiel-Prompts als Vorschläge (Onboarding)

Block F — Dry-Run / Vorschau / Reversibilität (PM-3)

Dry-Run-Mode

  • Engine simuliert Rule mit Sample-Payload
  • Keine echten Side-Effects
  • Klartext-Anzeige pro Step:
    • „Diese Automation würde jetzt 1.400 Personen treffen. Hier die ersten 5: ..."
    • „Email würde versandt an: noah@geerkens.de mit Subject ‚Premium-Lead'"
  • Bestätigung Pflicht: „Trotzdem aktivieren?"

Vor-Aktivierungs-Pflicht

  • Rule mit > 100 Datensätzen pro Schritt → Dry-Run-Bestätigung Pflicht
  • Schwellenwert konfigurierbar pro Tenant (Default 100)

Reversibilität (24h-Reverse-Window)

  • Jede Execution hat reverse_window_expires_at = triggered_at + 24h
  • Innerhalb 24h reversible Wirkungen rückgängig:
    • Mails: nicht zurückziehbar, aber Empfänger-Liste anzeigbar mit Klartext
    • Angelegte Entitäten: hard-löschen mit Audit
    • Status-Änderungen: zurücksetzen
    • Tag-Änderungen: rückgängig
  • Klartext: „Du hast noch 23h 12min, um diese Ausführung zurückzunehmen."
  • Multi-Step-Confirm + Audit-Trail-Eintrag pro Reverse

Block G — Schutz-Mechanismen (EC-1, EC-2)

Rate-Limit (EC-1)

  • Hard-Limit pro Trigger: Default 1.000 Auslösungen/h, Tenant-konfigurierbar
  • Anomalie-Detection: 10x normale Rate → Pause + Klartext-Notification: „Die Automation ‚Lead-Begrüßung' wurde 2.000-mal in 5 Min ausgelöst — typisch sind 5-10 pro Tag. Wir haben sie pausiert. Bitte prüfen."

Loop-Guard (EC-2)

  • Hardes Limit: max. 5 Auto-Trigger pro Datensatz pro 60 Sek
  • Klartext-Stopp bei Loop-Erkennung: „Automation A löst B aus, B löst A aus — Schleife erkannt, beide pausiert. [Visualisierung] [Beheben]"
  • Pre-Save-Validation beim Erstellen: System prüft Abhängigkeits-Graph, warnt vor Schleifen

Block H — Idempotenz + Resume-Mode (EC-3)

Idempotenz pro Action

  • Jeder Action-Step hat idempotency_key
  • Action prüft vor Ausführung — wenn schon erledigt, skip mit Status skipped

Resume-Mode

  • Retry beginnt am fehlgeschlagenen Step, nicht von vorne
  • Klartext: „Automation X war zu 60% durch (3/5 Schritte erfolgreich). Schritt 4 (KWP-Sync) fehlgeschlagen. Auto-Retry in 5 Min. [Manuell wiederholen] [Ab Schritt 4 weitermachen] [Abbrechen]"

Auto-Retry-Strategie

  • Exponential Backoff: 1 Min, 5 Min, 15 Min, 1 Std, 6 Std, 24 Std
  • Nach 6 Retries → failed mit Klartext-Email an Tenant-Admin
  • Manueller Retry möglich

Block I — Templates

Plattform-Templates (Code-Registry, branchen-modular)

SHK-Standard-Templates (Vorschlag):

  • „Lead-Begrüßung" — neuer Lead → Auto-Email mit Wartungstermin-Vorschlag
  • „Won-Handoff zur Installation" — Deal Won → Auto-Project + Push an PL
  • „Wartungstermin-Reminder" — 1 Woche vor Termin Reminder (Phase 2 für WhatsApp)
  • „Stuck-Deal-Eskalation" — Deal > 14 Tage in „Angebot" → Push an Vertriebsleiter
  • „Anrufe-Rückruf" — verpasster Anruf → Task für Vertriebler mit 24h-Deadline
  • „Acceptance-Komplett-Workflow" — acceptance_completed mit kind=full → Email + Customer-Portal-Update + KWP-Rechnungs-Trigger
  • „Mängel-Tasks-Generator" — acceptance_completed mit kind=with_defects → Tasks für jeden Mangel mit 7-Tage-Deadline

Tenant-Templates (User-definiert)

  • Tenant kann eigene Templates anlegen
  • Phase 2: Sharing über Marketplace (M33c)

Template-Catalog (/{tenant}/automations/templates)

  • Liste aller Templates (Plattform + Tenant), gruppiert nach Kategorie
  • Pro Template: Beschreibung + Beispiel-Use-Case + Anzahl Tenants die es nutzen

Operationen:

  • Template auswählen → Rule-Instanz aus Template
  • Eigenes Template anlegen aus existierender Rule
  • Template editieren / archivieren

Block J — Klartext-Diagnostik in Execution-Logs (LP-10)

Execution-Detail-View (/{tenant}/automations/:id/executions/:exec_id)

Zu zeigende Daten:

  • summary_text (Top-Level)
  • triggered_at, finished_at, Dauer
  • Trigger-Payload (User-readable)
  • Step-by-Step-Verlauf mit Status, Klartext, Input/Output, Dauer
  • dry_run-Marker
  • reverse_window-Status

Benötigte UI-Elemente:

  • Step-by-Step-Liste oder Timeline
  • Pro Step: Detail-Panel mit Input/Output
  • Filter nach Status
  • Funktion „Wirkungen rückgängig machen" (innerhalb 24h)
  • Funktion „Manuell retry"
  • Funktion „Detail-Logs für Plattform-Admin" (zeigt tech_details)

Execution-Liste (/{tenant}/automations/:id/executions)

  • Letzte N Executions
  • Filter nach Status, Datum, Trigger-Typ
  • Klick öffnet Detail

Klartext-Beispiele

  • Erfolgreich: „Lead-Begrüßung wurde ausgeführt. Email an max.mueller@example.com gesendet. Dauer: 0.8s."
  • Halb-Erfolg: „Won-Handoff: Project erstellt ✓, Push gesendet ✓, KWP-Sync fehlgeschlagen ✗ — Verbindung zu KWP nicht erreichbar. Auto-Retry in 5 Min."
  • Fehler: „Fehler beim Schritt ‚Email senden': Empfänger-Email nicht zustellbar. [Empfänger prüfen]"
  • Skipped: „Schritt ‚Email senden' wurde übersprungen, weil ‚Bedingung Volumen > 10.000' nicht erfüllt war (tatsächlich: 2.500)."

Block K — Stage-Stuck-Eskalation (Built-in-Cron)

  • Daily-Cron checkt offene Deals/Projects auf Stage-Stuck (länger als stage.auto_archive_after_days)
  • Bei Stuck: Trigger-Event deal.stuck.in_stage / project.stuck.in_stage mit Metadata
  • Tenant kann eigene Automations darauf hängen
  • Default-Template „Stuck-Deal-Eskalation" nutzt das

Konfigurierbar pro Stage:

  • auto_archive_after_days
  • Tenant-Admin passt Schwellenwerte an

Block L — Trigger-Volumen-Metering

  • Pro Tenant pro Monat: Anzahl AutomationExecution-Einträge
  • Visualisierung in /{tenant}/admin/usage/
  • Soft-Limit-Warnung bei 80% des Plan-Limits
  • Hard-Limit bei Überschreitung: neue Executions werden gequeued + Klartext: „Trigger-Volumen für diesen Monat überschritten. Automations laufen ab nächstem Monat wieder. Erweiterung im Plan möglich (extern auf hivegrid.de/pricing)."
  • Konkrete Limits pro Plan kommen mit Pricing-Definition (geparkt)

Block M — Permissions

Permission Erlaubt
automation.read Liste sehen, Logs sehen
automation.test Dry-Run / Test-Run
automation.write Rules anlegen + bearbeiten
automation.activate Rules aktivieren / deaktivieren
automation.delete Rules löschen
automation.reverse Wirkungen rückgängig machen (innerhalb 24h)
automation.use_ki KI-Erstellung per Sprache
automation.admin Volle Verwaltung + Templates + Trigger-Volumen-Override

Bundle-Mapping

Bundle Atomare Permissions
automation.basic read
automation.builder obigen + test + write + use_ki
automation.publisher obigen + activate + reverse
automation.admin alle obigen + delete + admin

Default-Rollen-Zuweisung (SHK-Template)

Rolle Permission
GF automation.admin
Vertriebsleiter automation.publisher
Vertriebler automation.basic
PL automation.builder (bauen, aber Aktivierung durch GF)
Büro automation.basic
Marketing automation.publisher
Monteur (keine)

Klartext-Fehler

  • Aktivierung ohne activate: „Du kannst Automations bauen, aber das Aktivieren erfordert Freigabe durch einen Admin. [Freigabe anfordern]"
  • Reverse nach 24h: „Diese Ausführung kann nicht mehr zurückgenommen werden — das 24h-Fenster ist abgelaufen."
  • KI-Nutzung ohne Permission: „Die KI-gestützte Erstellung ist im Cloud-Plus-Plan verfügbar."

Architektur-Vorschriften (Querschnitt)

  • LP-5: KI als Bedienoberfläche der Engine (Block E)
  • LP-6: Anti-Agentur — Selbst-Wartbarkeit über Klartext + KI-Erstellung
  • LP-10, AV #1: Klartext-Diagnostik zentral (Block J)
  • LP-11, AV #2: Adapter-Pattern (Knoten konsumieren Apps aus M33a)
  • AV #5: Permissions-aware-Default
  • AV #6: Audit-Trail für Rule-Änderungen
  • AV #8: Idempotenz pro Action (Block H)
  • AV #10: Dry-Run + Reversibilität (Block F)
  • AV #14: Promptfoo-Eval-Suite für KI-Erstellung
  • AV #16: Rate-Limiting + Anomalie-Detection (Block G)
  • AV #17: Loop-Guard mit Klartext (Block G)

Detail-Spec-Status: DRAFT

Modul 17 komplett spec'd — größte und wichtigste USP-Säule.

Offene Detail-Punkte:

  • Konkrete Flow-Editor-Library-Wahl (Boilerplate-Entscheidung: React Flow / Reaflow / X6 / Custom)
  • Konkrete Pre-Save-Loop-Validation-Algorithmus
  • Konkrete Anomalie-Detection-Schwellwerte pro Trigger-Typ
  • Sample-Payload-Quelle für Dry-Run (echter Datensatz vs. synthetisch)
  • KI-Prompt-Templates pro Use-Case (Implementierungs-Detail)
  • Konkrete Trigger-Volumen-Limits pro Plan (kommt mit Pricing)