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

67 lines
9.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
- [x] 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`
- [x] Tenant-/Permission-gefiltertes Rule-Matching erzeugt idempotente Executions (`packages/db/src/automation-forward.server.ts`, Companion-Consumer neben portal-automation auf `outbox.workflow`)
- [x] 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`)
- [x] 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)
- [x] Step-Outputs sind schema-validiert und für den 24h-Reverse aus `R-P12b` verwertbar (`validateAutomationStepOutput`, Shapes spiegeln `executeAutomationReverse`)
- [x] Loop-/Rate-/SSRF-/Idempotenz-Guards greifen fail-closed (SSRF via `validateOutboundHttpUrl` + `fetchOutboundHttpWithRedirects`)
- [x] 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`](../../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.