77 lines
11 KiB
Markdown
77 lines
11 KiB
Markdown
# 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
|
|
- [x] **Vollständige Trigger-Library** über alle Module (CRM, Lead, Sales, Projekte, Email, Forms, Booking, Kalender, Zeit, Webhook) im Knoten-Katalog gruppiert
|
|
- [x] **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
|
|
- [x] **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.).
|
|
- [x] Klartext-Diagnostik in allen Execution-Logs (Step-Status, Dauer, Input/Output)
|
|
- [x] Datenmodell persistiert: **`AutomationRule`/`AutomationRuleStep`/`AutomationExecution`/`AutomationStepExecution`** (+ Credential/Template)
|
|
- [x] Plattform- + Tenant-Templates mit Katalog und „aus Rule erstellen" (Backend)
|
|
- [x] 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-`.prisma`s 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)
|
|
- [x] Subframe-UI-Nachzug für Automation-Liste und Execution-Flächen integriert
|
|
- [x] App-Shell-Grenze nachgezogen: keine generierte Subframe-Sidebar innerhalb der HiveGrid-App-Shell
|
|
- [x] 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
|
|
- [x] Plane-Ticket `R-P12a` mit Subframe-UI-Nachzug aktualisiert
|