Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,541 @@
---
module: 17
title: Automation Engine
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-3, LP-4, LP-5, LP-6, LP-9, LP-10, LP-11]
spec_style: 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)