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

9.6 KiB
Raw Blame History

R-P12c · Production Trigger-Bus + typisierter Forward-Executor

Typ Dev (Code)
Owner Raffael
Phase P12 — Automation-Engine Nachzug
Cycle/Fenster v2-W1 · 2026-07-15 → 2026-07-18
Status umgesetzt · 7/7 DoD (mit dokumentierten v1-Grenzen)

Abhängigkeiten & Parallelität

  • Blocked by: R-P12a ✅
  • Blocks: R-P12b (produktive Outputs für Reverse), VR-P32d (KWP-Inbound-Event)
  • Nicht Teil von R-P20b: Der Bootstrap legt nur inaktive Metadaten-Platzhalter an.
  • Dependency-Stand 2026-07-15: R-P20b liefert exakt drei unveröffentlichte, nicht ausführbare Platzhalter inklusive stabiler Template-Keys. Trigger-Bus, Rule-Matching, Queue und Executor bleiben vollständig Scope dieses Tickets.

Was wir bauen

Den fehlenden produktiven Laufweg Domain-Event → Outbox → Rule-Matching → Queue → typisierter Executor. Der Legacy-Entity-Builder-/WorkflowEngine-Pfad wird nicht erweitert.

Definition of Done

  • Domain-Events werden transaktional als typisierte Automation-Trigger in die Outbox geschrieben — Emitter-Set v1: kontakt.created/updated (CRM-Service, neu), email.inbound_received (Mail-Sync-Hook, neu), bestehende lead.*/project.*/deal.won/form.submitted; Mapping in AUTOMATION_DOMAIN_EVENT_TRIGGER_MAP
  • Tenant-/Permission-gefiltertes Rule-Matching erzeugt idempotente Executions (packages/db/src/automation-forward.server.ts, Companion-Consumer neben portal-automation auf outbox.workflow)
  • Worker claimt und verarbeitet DAG-Steps concurrency-safe mit Retry, Delay und Resume (packages/db/src/automation-executor.server.ts + Worker-Queue outbox.automation-executor; Retry/Delay durabel über Outbox-scheduledAt)
  • Typed Action-Adapter für Condition, Task, Notification und externe Transaktionsmail; keine Direkt-Mail-Provider-Aufrufe (email.send_transactional publiziert mail.transactional.send in die Mail-Outbox; zusätzlich crm.update_kontakt/crm.create_note/http.request)
  • Step-Outputs sind schema-validiert und für den 24h-Reverse aus R-P12b verwertbar (validateAutomationStepOutput, Shapes spiegeln executeAutomationReverse)
  • Loop-/Rate-/SSRF-/Idempotenz-Guards greifen fail-closed (SSRF via validateOutboundHttpUrl + fetchOutboundHttpWithRedirects)
  • RLS-, Duplicate-Event-/Mail-, Parallelitäts-, Recovery- und Observability-Tests grün (automation-forward.server.test.ts 12, automation-executor.server.test.ts 14, automation-forward.test.ts 2, automation.run.test.ts 4)

Dokumentierte v1-Grenzen (bewusst, kein stiller Scope-Ausbau):

  • loop.for_each wird vom Executor fail-closed abgelehnt (Klartext automation.execution.loopForEachUnsupported) — Per-Item-Fan-out braucht dynamische Step-Instanzen, die das DAG-Modell nicht trägt (Folge-Entscheid).
  • webhook.received ist im Bus gemappt, hat aber keine öffentliche Inbound-Route (URL/Secret-Design offen, vgl. R-P12b-delta-abweichungen.md K-T3).
  • time.schedule / projects.deadline_soon brauchen einen Scheduler-Emitter (kein DoD-Punkt dieses Tickets).
  • condition.if_else ohne beschriftete Ja/Nein-Kanten (S01d-Rest-Delta): bei false wird der abhängige Zweig übersprungen (Filter-Semantik, deckt die vereinfachte Ein-Zeilen-Bedingung der K-L1-Karte).
  • Team-Optionen in task.create/task.assign/notification.send haben kein Group-Backing (Design-Platzhalter): Zuweisung fällt auf Rule-Owner bzw. bricht fail-closed ab.

Technische Bausteine

  • Bestehende AutomationRule*-/AutomationExecution*-Modelle und Cloud-Outbox/BullMQ.
  • Neue Action email.send_transactional über den vorhandenen mail.transactional.send-Pfad.
  • Keine neuen Entity-Builder-Konsumenten.

Quellen

  • .planning/ticket-docs/R-P12a.md, R-P12b.md, R-P20b.md
  • docs/ARCHITECTURE-DECISIONS.md → AD-2, AD-21

Umsetzungs-Notiz

  • 2026-07-19 (Akeshan, Audit-Restwork auf fix/r-p12-audit-restwork): Kompletten produktiven Laufweg gebaut: Domain-Event → outbox.workflow → Companion-Consumer (Rule-Matching, Owner-Permission automation.run|manage|admin, Idempotenz, Loop-/Volumen-Guards, alles in EINER Tenant-RLS-Transaktion inkl. automation.execution.requested-Dispatch) → outbox.automation-executor → typisierter Executor (Step-Claims via bedingtem updateMany, Retry mit Backoff über planAutomationRetry + Outbox-scheduledAt, delay.wait als durabler waiting-Status, Resume-ab-Schritt; Resume-Skips erfüllen Nachfolger, Branch-Skips nicht). Action-Adapter mit echten Effekten und reverse-kompatiblen, validierten Outputs; email.send_transactional neu in Registry + K-Node-Dialog (K-A2). Guard-Funktionen nach @hivegrid/db/automation-guards extrahiert (Web re-exportiert). Zusätzlich verdrahtet: run-now (Lauf-Liste), Erneut-ausführen und Ab-Schritt-fortsetzen (Lauf-Detail).
  • Proof: Commits 46518ad3a (DoD 1) · 58624cb5a (DoD 2–6) · bd6267022 (DoD 4/K-A2 + i18n) · 403b75112 (DoD 7, 26 Tests) · 8cc51786e (manueller Laufpfad + 4 Tests). Lokal grün: pnpm --filter @hivegrid/{db,worker,web} typecheck, verify:i18n Exit 0, verify:cross-cutting-models PASS, verify:sidebar-routes 33/33, verify:ui-visual 130 passed, Hot-Swap-Drill inkl. r-p12b-editor, fokussierte Suiten (automation web 29, db-forward 12, db-executor 14, worker handlers/bootstrap/router 154+36+23) grün.
  • RLS: Alle neuen Pfade laufen in withTenantRLS-Transaktionen (Worker-Helfer apps/worker/src/db/tenantRls.ts); Tests bilden die Policy nach (Fremd-Tenant-Query wirft).

R-P12c: 7/7 DoD = 100 % done (v1-Grenzen oben dokumentiert).

  • 2026-07-26 (Akeshan, Bugfix-Runde nach lokalem End-to-End-Test, Branch fix/automations-bugfixes): Der Laufweg selbst wurde live bestätigt (Kontakt anlegen → kontakt.created → Match → Executor → Aufgabe, ~1,1 s; run-now, Rückgängig, Lauf-Liste/-Detail grün). Gefixt wurden drei Folgen der oben dokumentierten v1-Grenzen, die im UI als Bug ankamen:

    • Roher englischer Guard-Text im UI: evaluateTriggerVolume lieferte einen englischen Prosa-Satz, den Web- und Worker-Pfad als AutomationExecution.summaryText bzw. AutomationTriggerMeter.anomalyText persistierten. In der Lauf-Liste stand dadurch sichtbar „1 automation triggers in 5 minutes for crm.kontakt_created; guard within limit." Der Guard liefert jetzt zusätzlich summaryKey (automation.execution.triggerVolumePaused bzw. .queued); der Anomalie-Banner speichert nur noch AUTOMATION_TRIGGER_VOLUME_ANOMALY_KEY und interpoliert Anzahl/Fenster/Auslöser aus der Meter-Zeile (neue VM-Felder anomalyCount/anomalyWindowMinutes). Der englische summaryText bleibt für Logs erhalten. Gleiche Behandlung für den Portal-Chain-Guard (automation.guards.portalChainPaused).
    • Bausteine ohne Executor: Der Picker bot die 6 portal.*-Aktionen auch unter Kern-Auslösern an; ein Lauf endete dann mit unsupportedNode (live reproduziert). Neu: automationExecutionFamily() in der Registry, der Picker zeigt nur noch die zum Auslöser passende Familie, und die Editor-Validierung blockt executor_family_mismatch sowie node_without_executor (loop.for_each, Extension-Slots) vor dem Aktivieren.
    • Auslöser ohne Emitter: AUTOMATION_TRIGGERS_WITHOUT_EMITTER (booking ×2, calendar, email.campaign_bounced, projects.deadline_soon, time.schedule, webhook.received) erzeugt jetzt eine Editor-Warnung „Die Regel würde nie starten" — nicht blockierend, weil solche Regeln vorbereitet werden dürfen. Betrifft u.a. die aktive Demo-Regel „Termin-Erinnerung vorbereiten". Die Emitter/der Scheduler selbst bleiben offen (kein Scope dieser Runde).
    • Proof: pnpm typecheck · pnpm lint · pnpm test 1108 Dateien / 7716 Tests grün · verify:i18n Exit 0 · verify:ui-visual 130 passed · Hot-Swap-Drill grün; neue Tests in automation.editor.test.ts, automation-forward.server.test.ts und automationUi.test.tsx.
  • 2026-08-01 (Raffael) — Vollständiger lokaler Engine-Audit und Action-Ausbau: Alle katalogisierten Trigger besitzen jetzt einen echten Producer bzw. Scheduler; webhook.received, Booking/Calendar, Campaign-Bounce, Portal-Status-Mail, Zeitplan und Deadline sind damit nicht mehr tote Editor-Einträge. Der Core-Executor führt zusätzlich echte Branches, Parallel/Merge, Loop-Fan-out, CRM-Tags/Zuweisung, Lead-Zuweisung/-Status, Teamchat und durchgereichte Step-Outputs aus. Portal-Ketten reichen Outputs zwischen Schritten weiter. Aktivierung und Dry-Run validieren Pflichtkonfiguration fail-closed; Registry-Tests verhindern aktive Core-/Portal-Nodes ohne Handler. Die noch nicht ausführbaren Phase-1-Aktionen sind als sichtbare extension_slot-Bausteine vorbereitet und in docs/automation/WORKFLOW-ENGINE-TOOL-MATRIX.md mit ihrem fehlenden produktiven Tool dokumentiert. loop.for_each ist runtime-seitig fertig, bleibt bis zu einer eigenen Produktfreigabe gesperrt; KWP-Writes blieben vereinbarungsgemäß unangetastet.

  • Proof 2026-08-01: 21 fokussierte Suiten mit 316 grünen Tests und 9 bewusst opt-in DB-Skips. Danach frische PostgreSQL-Instanz mit kanonisch provisionierten Nicht-Superuser-RLS-Rollen und 30/30 Migrationen: automation-executor.integration.test.ts 4/4 sowie workflow-trigger-e2e.test.ts 5/5, seriell grün. Betroffene DB-/Worker-/Web-Zielchecks, ESLint und Locale-Kohärenz liefen je atomarem Slice grün; kein unnötiger Full-Repo-Typecheck auf dem frischen Main-Worktree.

  • Stand 2026-08-01: R-P12c 7/7 DoD = 100 % done. Der Audit erweitert den belegten Laufzeitumfang; die vorbereiteten Tools in der Matrix sind explizite Folgearbeit und werden nicht als bereits ausführbar ausgegeben.