Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-P12a.md
T

11 KiB

R-P12a · P12 Automation-Engine + Trigger/Action-Registry + Guards

Typ Dev (Code)
Owner Raffael
Phase P12 — Automation-Engine (USP-Säule 1)
Cycle/Fenster W4 — USP, Härtung & Launch · 2026-07-06 → 2026-07-07 · Gate W4
Status Subframe-UI-Nachzug teilweise integriert

🎨 subframe-ui: teilweise integriert (seit 2026-07-09) — Management- und Execution-Flächen aus D-P12/Subframe sind für /automations, /automations/:id/executions und /automations/:id/executions/:exec_id hinter der bestehenden VM/Loader-Grenze integriert; Loop-/Rate-Warnmodal und vollständige visuelle Endabnahme bleiben Nachzug.

🟢 Kein Pivot-Sonderfall (P12 ist USP, nicht Teil der projekt-zentrischen Kern-Kette) — aber Trigger/Actions arbeiten auf dem Projekt-Kern. 🟡 v1-/AD-32-Grenze: kwp.push_project ist nur ein nicht ausführbarer Extension-Slot ohne KWP-Adapter/Executor-Handler; ein Ausführungsversuch scheitert fail-closed. Er ist keine freigegebene Writeback-Capability. Kein freigegebener KWP-Provider-Handler oder KWP-spezifischer Konfigvertrag vor VEXT-6 plus erneuter ausdrücklicher Produktfreigabe.

Abhängigkeiten & Parallelität

  • Blocked by: R-P11b (Dashboard fertig — Automation baut auf vollem Modul-Set auf)
  • Blocks: R-P12b (Flow-Editor verbraucht Engine + Registry) , R-P13 (KI-Actions docken an) → R-P13 entfällt (AD-26: KI→MCP)
  • Sequenz (Raffaels Kern-Kette): sequenziell (R-P11b → R-P12a → R-P12b) → R-P13 — R-P12b ist Ketten-Ende (AD-26).
  • Läuft parallel zu: Akeshans Module W4. Schema-Trennung nach AD-21.

Was wir bauen

Den Engine-Unterbau der ersten USP-Säule: eine vollständige Trigger-Library (CRM, Lead, Sales, Projekte, Email, Forms, Booking, Kalender, Zeit, Webhooks) und eine erweiterbare Action-Library (CRM, Notification, HTTP, Task, If/Else, Delay, Loop; KWP bleibt ein nicht ausführbarer Extension-Slot ohne Provider-Handler), plus die Schutz-Mechanismen (Loop-Guard, Rate-Limit, Idempotenz, Metering, Resume). Flows sind als JSON-Graph persistiert. Der visuelle Editor folgt in P12b.

Benötigte Screens (Backend bedient — Design liefert D-FLOW + D-P12)

Screen [Route] Kern-Inhalt
Automation-Liste [/automations] Name, Trigger, Status (aktiv/pausiert/Entwurf), Läufe (30d), letzte Ausführung, „nur meine"-Filter
Execution-Liste [/automations/:id/executions] Letzte N Läufe, Filter (Status/Datum/Trigger-Typ), Klick → Detail
Execution-Detail [/automations/:id/executions/:exec_id] summary_text, Trigger-Payload user-lesbar, Step-by-Step-Verlauf mit Klartext je Schritt (Status/Input/Output/Dauer), Dry-Run-Marker, 24h-Rückgängig-Button mit Restzeit, Manuell-Retry, Resume-ab-Schritt
Loop-/Rate-Schutz-Warnmodal Schleifen-Erkennung mit Abhängigkeits-Graph-Visualisierung + „Beheben"; Anomalie-Pause-Hinweis Klartext (z.B. „2.000-mal in 5 Min, typisch 5-10/Tag — pausiert")

(Trigger-/Action-Library = Daten im Knoten-Katalog, kein eigener Screen. Flow-Editor selbst → R-P12b.)

Definition of Done

  • Vollständige Trigger-Library über alle Module (CRM, Lead, Sales, Projekte, Email, Forms, Booking, Kalender, Zeit, Webhook) im Knoten-Katalog gruppiert
  • Erweiterbare Action-Library (CRM, Notification, HTTP, Task, If/Else, Delay, Loop) + Registry — der KWP-Platzhalter besitzt keinen KWP-Adapter/Executor-Handler und scheitert fail-closed; eine ausführbare KWP-Action bleibt bis VEXT-6 + erneuter Produktfreigabe ausgeschlossen; keine KI-Actions nach AD-26
  • Schutz: Loop-Guard (Abhängigkeits-Graph-Warnung), Rate-Limit + Anomalie-Pause, Idempotenz-Key, Trigger-Volumen-Metering pro Tenant, Resume-ab-Schritt mit Auto-Retry — Audit-Präzisierung 2026-07-19: Resume/Retry existierte bis dahin nur als Datenmodell ohne Ausführung (planAutomationRetry/resumeFromStepId ohne Konsument); die Ausführung liefert dependency-aware der R-P12c-Forward-Executor (umgesetzt 19.07., packages/db/src/automation-executor.server.ts). Punkt bleibt abgehakt, Erfüllungsweg ist dokumentiert (Freigabe im Audit 19.07.).
  • Klartext-Diagnostik in allen Execution-Logs (Step-Status, Dauer, Input/Output)
  • Datenmodell persistiert: AutomationRule/AutomationRuleStep/AutomationExecution/AutomationStepExecution (+ Credential/Template)
  • Plattform- + Tenant-Templates mit Katalog und „aus Rule erstellen" (Backend)
  • Konnektor tenantHasModule('automation') (Engine/Routes/Actions gated)

Umsetzungs-Notiz

  • 2026-07-02: Serverseitiger R-P12a-Unterbau umgesetzt: prisma/schema/automation.prisma + RLS, Automation-Knoten-/Template-Registry, Loop-/Volume-/Retry-/Idempotency-Guards, verschlüsselte Credentials, Template-Seeding, Rule-aus-Template, Tenant-Template-aus-Rule, Execution-Start mit Metering/Step-Logs, Entitlements/Permissions, Sidebar/Route-Wiring und Basis-Routen fuer Liste/Execution-Liste/Execution-Detail.

  • Proof: pnpm typecheck; pnpm exec prisma validate; pnpm vitest run apps/web/app/services/automation/automation.registry.test.ts packages/entitlements/src/features.test.ts packages/entitlements/src/plans.test.ts packages/entitlements/src/blueprints.test.ts packages/cli/src/commands/tenant/models.test.ts scripts/verify-route-inventory.test.mjs apps/web/app/application/sidebar/AppSidebar.test.tsx apps/web/app/application/ui/uiInventory.test.ts apps/web/app/components/core/roles/roleDisplay.test.ts.

  • Plane: Kommentar mit Proof hinterlegt; Ticket auf Blocked / On Hold gesetzt.

  • DoD-Stand: 7/7 technische DoD = 100 % serverseitig. Extern blockiert bleibt die visuelle Endabnahme bzw. Screen-Anpassung durch Davids D-FLOW/D-P12; Ticket bleibt deshalb On Hold, nicht Done.

  • 2026-07-09: Subframe-UI-Nachzug teilweise integriert: apps/web/app/components/screens/automation/AutomationPages.tsx rendert Automation-Liste, Execution-Liste, Execution-Detail und Template-Katalog mit ~/ui/Subframe-Komponenten nach Davids P12-Subframe-Stand. Die bestehenden Loader/VMs aus automation.server.ts bleiben unverändert. Proof: pnpm --filter @hivegrid/web typecheck grün. Offen bleibt der Loop-/Rate-Schutz-Warnmodal-Feinschnitt sowie die vollständige Endabnahme gegen D-P12.

  • 2026-07-10: UI-Bugfix: Rekursive Subframe-App-Shell entfernt. AutomationPages.tsx rendert jetzt nur noch app-chrome-freien Content und importiert nicht mehr ~/ui/layouts/DefaultPageLayout, damit die echte HiveGrid-Sidebar nicht doppelt erscheint. Proof: Regressionstest apps/web/app/components/screens/subframe-layout-boundary.test.ts.

  • 2026-07-10 (Akeshan, Querverweis — UI-Nachzug auf Subframe-Soll): Die vier Übersichts-Screens sind auf den vollen Subframe-Stand „(MCP) HiveGrid Workflow Engine / Automationen P12" gehoben und in Einzeldateien unter apps/web/app/components/screens/automation/ aufgeteilt (Liste/Lauf-Liste/Lauf-Detail/Vorlagen + Dialoge M01 Probelauf, M02 Schleifen-/Rate-Warnung, M03 Start-Auswahl). Engine/Registry/Schema sind unangetastet; ergänzt wurden nur Web-Layer-Bausteine: List-VM (failed24h, TriggerMeter-Anomalie, Owner-Name, currentUserId), Executions-Stats (Erfolgsquote 30d, Ø Dauer), Step-Snapshots (input/output) im Detail-VM, Template-Ketten im Katalog-VM sowie Route-Ops create/duplicate/archive/activate/pause/create-template auf der Liste und dry-run auf der Lauf-Liste (CSRF + automation.manage bzw. run; activate validiert wie im Editor inkl. Loop-Guard). errorText von Lauf und Schritten wird jetzt gerendert. Titel/Meta für Breadcrumbs ergänzt. Demo-Seed: dritte Regel „Kundendaten aktualisieren" (auto-pausiert) + aktiver AutomationTriggerMeter-Eintrag als M02-/Banner-Demo. Proof: typecheck 0 Fehler, pnpm lint exit 0, boundary-/automation-/format-Tests grün, Seed zweimal idempotent gegen frische DB. Weiter offen (braucht R-P12b-Engine): run-now, Erneut-ausführen und Ab-Schritt-fortsetzen; Cross-Automation-Abhängigkeits-Graph im M02 (Backend erkennt nur Intra-Flow-Zyklen + Rate-Anomalie).

  • 2026-07-11 (Dependency-Nachzug aus R-P12b): Execution-Detail unterstützt jetzt Reverse-EXECUTE für belastbar persistierte Outputs der Actions task.create, task.assign und crm.update_kontakt; tenant-/permission-gegatet, innerhalb des 24h-Fensters, mit exakter Confirm-Phrase und Activity-Audit. Fehlende oder unbekannte Outputs brechen fail-closed ab. Der Forward-Executor und seine Step-Output-Verträge wurden nicht verändert; weitere Action-Abdeckung bleibt deshalb in R-P12b offen. Proof: automation.reverse.test.ts 3/3 grün, Tenant-Routen-Typecheck grün. R-P12a-Stand: 7/7 technische DoD = 100 % done; keine DoD-Regression.

  • 2026-07-19 (Akeshan, Audit-Restwork): Drei-Quellen-Audit ergab real 6/7 (Plane stand auf Done): Punkt 3e (Resume/Retry-Ausführung) war Plan-Code ohne Aufrufer, ein generischer Executor fehlte komplett (nur der portal.*-Slice lief). Mit R-P12c (gleicher Branch) ist der Erfüllungsweg jetzt real: generischer Trigger-Bus, Forward-Executor mit Retry/Delay/Resume, und die Screen-Anforderungen „Manuell-Retry"/„Resume-ab-Schritt" im Execution-Detail sowie run-now auf der Lauf-Liste sind verdrahtet (Commits 58624cb5a, 8cc51786e). RLS-Regressions-Check: alle Automation-Pfade laufen kontextgebunden, keine Verstöße. Stand: 7/7 DoD, Erfüllung von 3e über R-P12c dokumentiert (dependency-aware, AGENTS.md §Ticket-Änderungen).

Technische Bausteine

  • Entities (eigene prisma/schema/automation.prisma): AutomationRule (name, flow_data JSON, enabled, created_via), AutomationRuleStep (step_kind trigger|condition|action|flow_control, node_type, config, parent_step_ids[] — Graph-Knoten), AutomationExecution (trigger_payload, status, dry_run, idempotency_key, reverse_window_expires_at), AutomationStepExecution (input/output, summary_text), AutomationCredential ([verschlüsselt]), AutomationTemplate (flow_data, category, is_published — SHK-Vorlagen). Andere Modul-.prismas nur über Trigger/Action-Adapter (AD-21).
  • RLS auf Rule/Execution/Template (AD-1); [Soft-Delete] auf Rule; AutomationCredential AES-verschlüsselt.
  • Trigger-Bus: Modul-Events (z.B. lead.qualified, deal.won) → Trigger-Matching → Execution; Idempotenz-Key verhindert Doppel-Läufe.
  • Loop-Guard/Rate-Limit/Metering server-seitig; Anomalie-Pause bei Spike (Klartext-Notification).
  • Konnektor tenantHasModule('automation') gated.
  • is_demo_data-Flag auf SHK-Templates/Demo-Rules.

Quellen (granular)

  • ENTITY-MODEL.md → Domäne 7: Automation & KI (AutomationRule/RuleStep/Execution/StepExecution/Credential/Template)
  • REQUIREMENTS.md → REQ-automation-datenmodell, REQ-automation-trigger-library, REQ-automation-action-library, REQ-automation-schutz (Phase 12)
  • ROADMAP.md → Phase 12
  • designer-briefs/P12-automation-engine.md (Flow-Editor BESPOKE — schwerste UI; v1-Grenze KWP-Push)

Dev-Nachzug (nach Davids D-FLOW/D-P12-Delta)

  • Subframe-UI-Nachzug für Automation-Liste und Execution-Flächen integriert
  • App-Shell-Grenze nachgezogen: keine generierte Subframe-Sidebar innerhalb der HiveGrid-App-Shell
  • Loop-/Rate-Schutz-Warnmodal gegen D-P12 nachgezogen (M02, 2026-07-10; Cross-Automation-Graph bleibt Engine-Nachzug)
  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket R-P12a mit Subframe-UI-Nachzug aktualisiert