67 lines
9.6 KiB
Markdown
67 lines
9.6 KiB
Markdown
# 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.
|