Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
+95
@@ -0,0 +1,95 @@
|
||||
<!-- markdownlint-disable MD013 -->
|
||||
|
||||
# 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.
|
||||
Reference in new issue
Block a user