19 KiB
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 |
|
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,descriptionflow_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_30darchived_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_attrigger_payload(JSON)status(running | success | partial_success | failed | cancelled)started_at,finished_atsummary_text(Klartext)dry_run(Boolean)triggered_by_user_id(nullable)idempotency_keyreverse_window_expires_at(24h nach Execution für Undo)
AutomationStepExecution
id,execution_id,step_idstarted_at,finished_atstatus(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,descriptionflow_data(JSON)categoryis_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_stagedeal.assignee_changeddeal.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_stageproject.member_added,project.member_removedproject.acceptance_completed(mitkind-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_completedcall.outbound_completedcall.missed
Tasks (M26)
task.created,task.assigned,task.completedtask.deadline_approaching,task.overdue
Time-based (Built-in)
schedule.cron(CRON-Expression)schedule.delay(Folge-Step nach Delay)
KWP (M19)
kwp.auftrag_pulledkwp.schema_drift_detected
Apps Engine (M33a)
app.connection_status_changedapp.sync_failed
HR (M14)
hr.vacation_approvedhr.sick_leave_reported
Customer Portal (M15)
portal.kunde_uploaded_fileportal.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 semantischwon | lost | next_open)deal.update_volume,deal.assign_to_user,deal.add_tagdeal.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_stageproject.add_memberproject.create_taskproject.create_schedule_entryproject.start_acceptanceproject.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,mergeloop— 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)
- Intent-Klassifikation: neue Automation oder Edit?
- Entity-Extraction: Trigger, Filter, Actions
- Schema-Validation: existieren referenzierte Pipelines, User, Forms? (EC-4)
- Rückfrage bei Mehrdeutigkeit: „Du meinst Klaus Müller (Vertriebsleiter Süd) oder Klaus Schmidt (Bauleiter Nord)?" (EC-4)
- Flow-Generierung: Graph-Struktur als JSON
- Vorschau-Rendering: Flow im Editor + Klartext-Beschreibung
- 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 →
failedmit 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_completedmitkind=full→ Email + Customer-Portal-Update + KWP-Rechnungs-Trigger - „Mängel-Tasks-Generator" —
acceptance_completedmitkind=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-Markerreverse_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_stagemit 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)