Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/docs/automation/WORKFLOW-ENGINE-TOOL-MATRIX.md
T

11 KiB

Workflow-Engine: Laufzeit- und Tool-Matrix

Stand: 2026-08-01

Scope: lokal testbare Phase-1-Automationen; KWP-Schreibzugriffe sind ausdrücklich ausgenommen.

Diese Matrix trennt drei Zustände, die im Editor nicht miteinander verwechselt werden dürfen:

  • Aktiv: Der Baustein besitzt einen echten Executor und darf in aktivierbaren Regeln verwendet werden.
  • Vorbereitet: Der Baustein ist im Katalog sichtbar, aber extension_slot und damit fail-closed nicht aktivierbar.
  • Ausgenommen: Kein Phase-1-Tool; wird nicht still über einen Platzhalter-Executor simuliert.

Ergebnis der Verifikation

Ebene Ergebnis Beleg
Katalog/Editor/Executor/Reverse/Trigger/Worker 316 Tests grün, 9 opt-in DB-Tests übersprungen 21 fokussierte Vitest-Suiten
Neuer Core-Executor gegen echte DB 4/4 grün frische PostgreSQL-DB, RLS-Rollen über scripts/provision-rls-roles.mjs, 30/30 Migrationen
Bestehende Workflow-Outbox-Brücke gegen echte DB 5/5 grün dieselbe frische DB, seriell nach dem Core-Executor
Aktive Core-Katalogeinträge gegen Dispatcher vollständig Registry-Test gleicht aktive Core-Nodes mit AUTOMATION_CORE_EXECUTOR_NODE_TYPES ab
Aktive Portal-Katalogeinträge gegen Dispatcher vollständig Registry-/Worker-Tests gleichen sie mit PORTAL_AUTOMATION_ACTION_PERMISSIONS ab
Trigger gegen Producer/Scheduler vollständig AUTOMATION_TRIGGERS_WITHOUT_EMITTER ist leer und vertraglich getestet

Die DB-Tests beweisen Migration, RLS-Kontext, Persistenz, Claims, Step-Outputs, Delay/Resume und Outbox-Verarbeitung. Eine interaktive Browser-Abnahme war in dieser Agent-Oberfläche nicht verfügbar; Picker und Konfiguration sind deshalb durch Component-/Service-Tests, nicht durch behauptete Browser-Klicks belegt.

Aktive Bausteine

Core-Executor

Bausteine Echte Wirkung Reverse/Output
crm.update_kontakt typisierte Kontaktfelder ändern Snapshot; rückgängig
crm.add_tag, crm.remove_tag Kontakt-Tag anlegen/entfernen vorheriger Zustand; rückgängig
crm.assign_kontakt Kontakt einem Tenant-User zuweisen vorherige Zuweisung; rückgängig
crm.create_note Kontakt-Aktivität/Notiz anlegen append-only; bewusst nicht rückgängig
lead.assign, lead.set_status Lead-Zuweisung bzw. Status ändern und Folge-Trigger publizieren vorheriger Zustand; rückgängig
task.create, task.assign Aufgabe anlegen bzw. vorhandene Aufgabe zuweisen Task-ID/Snapshot; rückgängig
notification.send persistente In-App-Benachrichtigung erzeugen Empfänger dokumentiert; nicht zurückziehbar
email.send_transactional mail.transactional.send durabel in die Mail-Outbox schreiben Empfänger dokumentiert; nicht zurückziehbar
chat.post_message echte Teamchat-Nachricht über den Chat-Service senden Message-ID; nicht zurückziehbar
http.request SSRF- und Redirect-geschützten HTTP-Aufruf ausführen Status/Response-Metadaten; nicht rückgängig
condition.if_else genau den True- oder False-Zweig freigeben Entscheidung persistiert
delay.wait Lauf durabel bis zum Zielzeitpunkt pausieren und wieder aufnehmen Waiting-/Resume-Zustand
flow.parallel, flow.merge parallele Zweige freigeben und anschließend synchronisieren DAG-Zustand

loop.for_each ist im Executor vollständig implementiert und mit allen Datenquellen sowie echter DB getestet. Der Baustein bleibt bis zu einer eigenen Produktfreigabe als extension_slot gesperrt; die Runtime-Reife allein erweitert den aktiven Ticket-Scope nicht.

Portal-Executor

Die getrennte Portal-Familie führt portal.invite_user, portal.grant_access, portal.revoke_access, portal.release_document, portal.send_status_mail und portal.disable_user aus. Der Editor verhindert Misch-Flows aus Portal- und Core-Bausteinen; beide Worker lehnen eine falsche Familie zusätzlich fail-closed ab.

Trigger

Alle 27 aktiven Trigger im Katalog besitzen heute einen Producer, eine öffentliche Inbound-Brücke oder einen Scheduler. Dazu gehören CRM, Lead, Projekt/Sales, Formular, E-Mail/Bounce, Booking, Kalender, Zeitplan, Deadline, Webhook und Portal. Event-Verträge, Tenant-Zuordnung, Duplikatunterdrückung und Rule-Matching werden vor dem Executor validiert.

Vorbereitete Bausteine und benötigte Tools

Ein vorbereiteter Baustein darf erst auf active wechseln, wenn sein Tool alle folgenden Verträge erfüllt: Tenant-RLS, Berechtigungsprüfung, stabile Idempotenz, Domain-Invarianten, Audit/Activity, notwendige Search-/Notification-Side-Effects, typisiertes Output-Schema, Reverse-Klassifizierung und Tests gegen echte PostgreSQL-Persistenz.

Priorität Vorbereitete Bausteine Wiederverwendbarer Bestand Noch zu bauendes Tool / Entscheidung
1 lead.convert_to_project createProjectFromQualifiedLead in projectService.server.ts; bereits idempotent, projekt-zentrisch, mit Triggern, Suche, Chat-Sync und Aggregaten Worker-sicheres ProjectCommandGateway.convertQualifiedLead aus der Web-Schicht extrahieren; Actor-/Permission-Kontext definieren. Kontakt wird nur explizit, über Lead-Link oder E-Mail-Match verknüpft, nicht blind neu erzeugt.
1 sales.create_project, projects.create_project, sales.change_stage, projects.change_stage, sales.change_volume, sales.assign_project, sales.move_pipeline, projects.move_pipeline createProject, moveProjectStage, updateProjectStammdaten, moveProjectToPipeline besitzen die fachlichen Guards und Side-Effects Worker-sicheres ProjectCommandGateway mit Idempotenz und automation-spezifischen Outputs/Reverse-Plänen. Die vorhandenen Services dürfen nicht im Worker dupliziert oder per Direktimport aus apps/web verwendet werden.
1 sales.add_project_tag typisierte Projektbasis vorhanden; kein kanonischer Projekt-Tag-Writer gefunden ProjectTagCommand mit tenant-geprüfter Tag-Registry, Add-Dedupe, Activity/Search und Reverse.
1 projects.add_member addProjectMember prüft Tenant-User/-Gruppe und synchronisiert den Projektchat Worker-Fassade plus idempotenter Membership-Key und Output für Remove-Reverse.
1 projects.create_task createIdempotentTaskFromSource und Projekt-Link-Felder existieren ProjectTaskCommand für eine idempotente, mit dem Projekt verknüpfte Aufgabe samt User-/Gruppenauflösung.
1 projects.create_appointment createProjectAppointment schreibt den typisierten ProjektTermin und Activity ProjectAppointmentCommand mit Idempotenz, Projekt-/Kalender-Event-Vertrag und Reverse-Output.
1 projects.start_acceptance submitAcceptanceProtocol schließt eine Abnahme ab; kein fachlich passender Start-/Draft-Befehl vorhanden AcceptanceDraftCommand.start definieren. Nicht den Submit-Service mit erfundenen Signaturen missbrauchen.
Entscheidung projects.create_from_won_sales AD-20: Sales/Deal/Auftrag sind Typen bzw. Zustände desselben Projekt-Kerns; kein Won-Handoff Nicht als Create-Writer bauen. Block entfernen oder in eine echte Typ-/Stage-Transition umbenennen und dafür einen dokumentierten Product-/Entity-Model-Entscheid treffen.
2 notification.send_push Web-Push-Provider und Retry-Job existieren für Telephony; Foundation-Kanäle kennen nur IN_APP/EMAIL Generischer PWA-Push-Kanal: Subscription-Registrierung pro Tenant-User, PUSH-Preference/Delivery, Worker-Routing zum vorhandenen Provider, Invalid-Subscription-Cleanup.
2 webhook.send_signed Public-API-Webhooks besitzen HMAC-Header, Delivery-Persistenz und SSRF-Schutz Credential-basiertes SignedWebhookCommand für frei konfigurierte Ziele. Secrets bleiben verschlüsselt und nie im Rule-JSON; benötigt Retry-/Delivery-Output und stabile Idempotenz.
2 calendar.create_event, calendar.update_event Provider-neutraler CalendarAdapter und Google-Implementierung können schreiben; Connection/Token-Refresh existiert CalendarWriteService: schreibbare Verbindung/Kalender wählen, Tokens erneuern, lokale CalendarEvent-Zuordnung persistieren, ETag-Konflikte behandeln, idempotent schreiben. Provider-I/O darf nicht in einer langen DB-Transaktion liegen.
2 files.create_from_url S3-/File-Service und fail-closed ClamAV-Pipeline existieren; Billing hat nur einen spezialisierten SSRF-geschützten Download RemoteFileIngestService: SSRF- und Redirect-geschützter Download, harte Größen-/Content-Type-Grenzen, ClamAV vor Freigabe, Storage/File-Zeile, Entity-Link, Idempotenz und Cleanup.
Ausgenommen kwp.push_project Slot bleibt vorhanden KWP-Writes sind für diesen Auftrag ausdrücklich ausgenommen. Kein Fake-Handler.

Verbleibende gemeinsame Produktionswerkzeuge

Diese Punkte betreffen bereits aktive Bausteine. Die Hauptwirkung ist lokal verifiziert, für vollständige Parität mit manuellen UI-Aktionen fehlen aber noch gemeinsame Domain-Werkzeuge:

  1. Domain-Side-Effect-Fassade für Worker-Aktionen: Kontakt-, Lead- und Task-Mutationen müssen Search-Projektion, Activity und weitere fachliche Side-Effects über dieselben Commands wie die Web-App auslösen. Direkte Prisma-Writes funktionieren, können heute aber z. B. einen Suchindex bis zum nächsten Rebuild veralten lassen.
  2. Tenant-Principal-Resolver: task.create, task.assign und notification.send unterstützen derzeit nur die tatsächlich implementierten Owner/Creator-Pfade. Für Mitarbeiter, Teams und Gruppen braucht es einen gemeinsamen permission-geprüften Resolver statt Design-Platzhaltern.
  3. Versionierter E-Mail-Template-Resolver: Dynamische Platzhalter funktionieren, aber email.send_transactional nimmt noch Betreff/Text direkt aus der Regel. Für den vollständigen Phase-1-Vertrag fehlen Template-ID, Version, erlaubte Platzhalter und Preview/Validation.
  4. HTTP-Credential-/Header-Resolver: http.request ist funktional und SSRF-geschützt, unterstützt aber noch keine sicher gespeicherten dynamischen Header. Auth-Secrets dürfen nicht in der Flow-Konfiguration liegen.

Aktivierungs-Gate für neue Tools

Vor dem Umschalten eines Slots auf active müssen mindestens folgende Nachweise im selben atomaren Change liegen:

  1. Handler im passenden Executor und maschinenlesbarer Eintrag im Executor-Vertrag.
  2. Config- und Output-Schema inklusive Klartextfehlern.
  3. Idempotenz- und Retry-Test, Permission-/RLS-Test sowie echter PostgreSQL-Integrationstest.
  4. Reverse-Handler oder explizite, im Lauf sichtbare Kennzeichnung als nicht rückziehbar.
  5. Editor-Descriptor, i18n und Component-Test; keine Aktivierung eines nur sichtbaren Placeholders.