107 lines
23 KiB
Markdown
107 lines
23 KiB
Markdown
# Boilerplate-Abgleich — M17 Automation Engine
|
||
|
||
| Feld | Wert |
|
||
| --- | --- |
|
||
| Modul-ID | M17 |
|
||
| Name | Automation Engine (USP-Säule) |
|
||
| Milestones | M075 (Schema + Auslöser-Registry), M076 (Aktion-Registry + Steuerung), M077 (Bedingungen), M078 (Visueller Editor), M079 (Test-Lauf/Schwellenwert-Vorschau), M080 (24h-Undo/Reversibilität), M081 (Schleifen-/Webhook-/Anomalie-Schutz + Resume), M082 (Klartext-Logs + Re-Run + Trigger-Volumen-Metering) |
|
||
| Pflichtenheft-Block | Block 4 (USP-Säulen), Modul 17, Abschnitte 17.1–17.9 + Anhang H.1.1 (Metering) |
|
||
| Spec | `_bmad-output/specs/M17-automation-engine.md` (USP-Säule, „größte und wichtigste") |
|
||
| **Reuse-Level** | **high** |
|
||
|
||
## Reuse-Zusammenfassung
|
||
|
||
Die Boilerplate enthält eine **vollständige, produktionsreife, graph-basierte Workflow-Engine** — exakt die in der Spec geforderte Architektur (Knoten + Edges, parallele Branches, If/Switch). Sie umfasst:
|
||
|
||
- **Datenmodell** (`prisma/schema/workflows.prisma`, 10 Modelle): `Workflow`, `WorkflowBlock`, `WorkflowBlockToBlock` (Edges), `WorkflowBlockConditionGroup`/`WorkflowBlockCondition` (AND/OR), `WorkflowExecution`, `WorkflowBlockExecution`, `WorkflowInputExample`, `WorkflowVariable`, `WorkflowCredential` — tenant-scoped + `appliesToAllTenants` (Plattform-Templates), Execution-Tracking pro Block, alle nötigen Performance-Indizes vorhanden.
|
||
- **Visueller Editor** (`apps/web/app/modules/workflowEngine/`, ~120 Dateien): `@xyflow/react`-Canvas mit Mini-Map/Zoom/Pan, `dagre`-Auto-Layout, Knoten-Catalog, pro-Knoten-Config-Panel, Custom-Edges, Pre-Save-Validierung mit Klartext-Fehlern, Block-Errors-Anzeige, Execution-Visualisierung, Streaming-Progress.
|
||
- **Engine + Worker** (`apps/worker/src/jobs/workflow-*.ts`, ~16 Dateien): Outbox-getriebener `event`-Trigger-Fanout, Block-Executor-Factory (native + HTTP), Stalled-Execution-Reconciler-Cron, Preflight-Check, Resume-from-block (`fromBlockId`), Continuation/`waitForInput`, BullMQ-Backoff.
|
||
- **Bedingungs-Engine** (`WorkflowsConditionsService.ts` + `WorkflowConditionUtils.ts`): Operatoren `=`, `!=`, `>`, `<`, `>=`, `<=`, `startsWith`, `endsWith`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`, AND/OR-Gruppen, `{{$vars}}`/`{{$params}}`-Variablen-Auflösung.
|
||
- **Querschnitt**: AES-Credential-Verschlüsselung (`CryptoApi.decrypt`) + Credential-Redaction in Logs, AJV-JSON-Schema-Validierung für Trigger-Payloads, Plugin-Hooks (`workflow.executed`/`workflow.failed`), Idempotenz (`@toolctrl/foundation` + Outbox-Receiver-Idempotency), Default-Templates-Registry (code-basiert, i18n).
|
||
|
||
Damit ist das **gesamte Architektur-Skelett** von M075–M082 abgedeckt: Graph-Datenmodell, Editor-Library, Execution-Engine, Conditions, Resume-Mode, Trigger-Fanout, Templates-Registry. Was **fehlt**, sind durchweg **HiveGrid-fachliche Inhalte und USP-Mechaniken**: die ~60 domänen-spezifischen Trigger/Actions (Deal/Project/Lead/CRM/Booking/Telefonie/KWP/Portal …), das 24h-Undo/Reverse-Window, Anomalie-Detection + Loop-Guard mit Klartext, KI-Erstellung per Sprache, Dry-Run-mit-Empfänger-Sample + >100-Schwelle, Trigger-Volumen-Metering, sowie die HiveGrid-Permission-Bundles.
|
||
|
||
**Wichtiger Architektur-Vorbehalt:** Der gesamte Editor- und Service-Code liegt in `apps/web/app/modules/workflowEngine/` als RR7-Route-Module mit `.db.server.ts`/`.api.server.ts`-Dateien — das **kollidiert mit der HiveGrid-Layer-Disziplin** (AGENTS §A: View-Models in `packages/view-models`, UI in `packages/ui-hivegrid`, Subframe via Adapter, keine `useLoaderData` in UI-Components). Plus User-Memory-Blocker: **`.server.ts`-Re-Export ist verboten — nur Component-Extraktion**. Der Code ist daher als **Vorlage** zu behandeln (Logik 1:1 übernehmen, Layer-Struktur umbauen), nicht als 1:1-Import. Datenmodell, Engine/Worker und reine Helper/Services sind dagegen sehr nah an 1:1.
|
||
|
||
## Übernehmbar aus Boilerplate
|
||
|
||
| Boilerplate-Pfad | Was | Wie nutzbar |
|
||
| --- | --- | --- |
|
||
| `prisma/schema/workflows.prisma` | Komplettes graph-basiertes Datenmodell: `Workflow`, `WorkflowBlock`, `WorkflowBlockToBlock` (Edges + `condition`), `WorkflowBlockConditionGroup`/`Condition`, `WorkflowExecution`, `WorkflowBlockExecution`, `WorkflowInputExample`, `WorkflowVariable`, `WorkflowCredential`; tenant-scoped + `appliesToAllTenants`, Status/Duration/Error/`waitingBlockId` pro Execution, Indizes | **als-vorlage** — Struktur deckt `AutomationRule`/`RuleStep`/`Execution`/`StepExecution`/`Credential`/`Template` der Spec (Block A). Ergänzen: `created_via` (manual/template/ki_natural_language), `last_executed_at`, `executions_count_30d`, `archived_at`, `dry_run`, `idempotency_key`, `reverse_window_expires_at`, `summary_text`, `parent_step_ids[]`/`position`, sowie ein dediziertes `AutomationTemplate`-Modell (Boilerplate-Templates sind code-only, kein DB-Modell) |
|
||
| `apps/web/app/modules/workflowEngine/components/workflows/WorkflowBuilder.tsx` + `LazyWorkflowBuilder.tsx`, `WorkflowBlockEditor.tsx`, `WorkflowEditorSidebar.tsx`, `WorkflowExecutionsSidebar.tsx`, `components/nodes/*`, `components/edges/CustomEdge.tsx` | Vollständiger `@xyflow/react`-Editor: Canvas, Knoten-Catalog-Sidebar, pro-Knoten-Config, Custom-Edges, Trigger-/If-/Switch-Nodes, Lazy-Load | **als-vorlage** — Editor-Grundgerüst + Drag/Connect/Config-Muster 1:1 übernehmbar (deckt M078, Block D). MUSS in `packages/ui-hivegrid` + Adapter-Layer umziehen (AGENTS §A, M015); UI darf kein `useLoaderData` nutzen |
|
||
| `apps/web/app/modules/workflowEngine/helpers/WorkflowLayoutUtils.ts` | `dagre`-basiertes Auto-Layout (`getLayoutedElements`, rankdir) | **1:1** — deckt „Auto-Layout"-Toolbar (Block D) |
|
||
| `apps/web/app/modules/workflowEngine/helpers/WorkflowUtils.ts` | `buildExecutionOrder` mit `visited`-Set (DFS-Traversal über `true/false/default/case/loopNext/loopEnd`-Branches), Block-Graph-Helfer | **anpassen** — Traversal-Basis; für Loop-Guard/Cycle-Pre-Save-Validation (Block G) als Cycle-Detektor erweitern (vorhandenes `visited` ist Traversal-Schutz, KEINE explizite Cycle-Warnung) |
|
||
| `apps/web/app/modules/workflowEngine/services/WorkflowPreflightService.ts` + `helpers/WorkflowReferenceUtils.ts` | Pre-Save/Pre-Run-Validierung: fehlende Variablen/Credentials, fehlende Pflicht-Inputs pro Block, native-Capability-Errors, alles als i18n-Klartext; `throwIfFailed` mit `status:400` + `preflight`-Detail | **als-vorlage** — deckt 17.5.6 „Validator listet alle Probleme" (Block D) sehr gut; ergänzen: „Knoten nicht verbunden / wird nie ausgeführt" + Cycle-Warnung (Klartext aus Spec Block D) |
|
||
| `apps/web/app/modules/workflowEngine/services/WorkflowsValidationService.ts` | AJV-JSON-Schema-Compile + `validate`/`parseJsonSchema` für Trigger-Payload-Validierung | **1:1** — Schema-Validation für Trigger-Payloads/manuelle Trigger |
|
||
| `apps/web/app/modules/workflowEngine/services/WorkflowsConditionsService.ts` + `helpers/WorkflowConditionUtils.ts` + `dtos/WorkflowConditionDtos.ts` | Bedingungs-Auswertung: 12 Operatoren, AND/OR-Gruppen, `parseVariable`-Auflösung, i18n-Labels, Operator-Validierung | **anpassen** — deckt M077/Block C Conditions (Field-Equals/Contains/Greater/Less, Tag-Set via contains). Ergänzen: `Time-Of-Day`/`Day-Of-Week`, `User-In-Group`, type-safe Feld-Picker, der Trigger-Felder kennt (Spec 17.4 / M077-Hinweis) |
|
||
| `apps/web/app/modules/workflowEngine/services/WorkflowsExecutionsService.ts` | Execution-Orchestrierung: Live-Check, Preflight, Execution-Record, Trigger-Block-Suche, **Resume ab `fromBlockId`**, Continuation-Sourcing, Outbox-Publish (`workflow.execution.requested`), Plugin-Hook-Emission, Credential-Redaction | **als-vorlage** — Kern der Engine; Resume-Mode (Block H) bereits angelegt. `.server`-Logik in HiveGrid-Service-Layer (`app/domain/**` / loader-pfad) extrahieren |
|
||
| `apps/web/app/modules/workflowEngine/services/blocks/WorkflowBlockService.ts` + `WorkflowBlockProService.ts` + `dtos/WorkflowBlockTypes.ts` | Block-Type-Registry + Executor: `trigger(manual/event)`, `if`/`switch` (flow), `httpRequest`, `log`, `alertUser`, `doNothing`, `waitForInput`, `gpt` (ai), `rowGet/Create/Update/Delete` (entities) — als deklarative `WorkflowBlockTypeDto[]` mit Inputs/Outputs/Conditions | **als-vorlage** — die Registry-Architektur (deklarative Node-Typen + Executor) ist genau das M075/M076-Muster. Inhalte sind aber generisch (`row*`/`httpRequest`/`gpt`) — die ~60 HiveGrid-Trigger/Actions (deal/project/lead/contact/booking/call/kwp/portal/…) müssen NEU als Plug-Registry-Einträge ergänzt werden |
|
||
| `apps/web/app/modules/workflowEngine/utils/DefaultWorkflowTemplates.ts` + `WorkflowsTemplatesService.ts` + `workflowTemplateI18n.ts` | Code-basierte Template-Registry mit i18n-Keys, Import-in-Tenant, `adminOnly`/`appliesToAllTenants` | **als-vorlage** — deckt Template-Mechanik (Block I, M082-Templates). Inhalte sind Demo (`sampleHttpRequests`); die SHK-Templates („Lead-Begrüßung", „Won-Handoff", „Stuck-Deal-Eskalation", „Mängel-Tasks-Generator" …) neu schreiben |
|
||
| `apps/worker/src/jobs/workflow-trigger.ts` + `workflow-trigger-store.ts` + `workflow-trigger-executor-factory.ts` + `workflow-trigger-native-executor.ts` + `workflow-trigger-http-executor.ts` + `workflow-trigger-bootstrap.ts` | Outbox-getriebener Event→Workflow-Fanout: `findLiveEventWorkflows` (matcht `event`-Trigger gegen `eventName` + Condition-Filter), Idempotenz via Outbox-Receiver, Executor-Factory (native/HTTP), Rejected-Execution-Recording | **anpassen** — exakt die „Auslöser-Registry als Plug-Architektur"-Mechanik (M075-Hinweis). HiveGrid-Module müssen ihre Domain-Events in den Outbox-Bus emittieren (`workflow.*`-Prefix); Event-Liste erweitern |
|
||
| `apps/worker/src/jobs/workflow-execution-stalled-reconciler.ts` + `-cron.ts` | Cron: findet hängende Executions (>30 min, `waiting`/`waitingBlock`), gleicht gegen Failed-Outbox/Queue-Failed-Jobs ab, repariert/re-published | **1:1** — Resilienz-Baustein für Resume-Mode (Block H, M081); zusätzlich als Muster für den Stage-Stuck-Daily-Cron (Block K) nutzbar |
|
||
| `packages/queue/src/producers.ts` (`retryJobOptionsByQueueAndJobName`, `buildRetryJobOptions`) + `types.ts` (Default `attempts:3`, exponential backoff) | BullMQ-Retry/Backoff-Konfiguration pro Queue/Job, exponential | **anpassen** — Basis für die Auto-Retry-Strategie 1m/5m/15m/1h/6h/24h (Block H, M081); konkrete Backoff-Stufen + „nach 6 Retries failed + Admin-Mail" ergänzen |
|
||
| `packages/foundation/src/idempotency.ts` (`withIdempotency`, `IdempotencyClient`) + `prisma/schema/core.prisma` (`IdempotencyKey @@unique([scope,key])`) | Idempotenz-Helper + DB-Modell | **1:1** — `idempotency_key` pro Action-Step (Block H / AV#8); deckt „skip mit Status skipped, wenn schon erledigt" |
|
||
| `apps/worker/src/outbox/event-router.ts` (`DEFAULT_OUTBOX_ROUTING`, inkl. `{ prefix: "workflow.", queue: "outbox.workflow" }`) + `outbox/dispatcher.ts` | Outbox→Queue-Routing (longest-prefix-wins), Dead-Letter | **1:1** — der `workflow.`-Pfad ist bereits verdrahtet; HiveGrid-Domain-Events nur emittieren |
|
||
| `apps/web/app/modules/workflowEngine/services/WorkflowVariablesAndCredentialsService.ts` + `WorkflowsVariablesService.ts` (`CryptoApi.decrypt`, `redactWorkflowCredentials`, `REDACTED_WORKFLOW_CREDENTIAL`) | AES-verschlüsselte Tenant-Credentials at-rest + Credential-Redaction in Outputs/Logs | **1:1** — deckt `AutomationCredential` (Block A) + Klartext-Logs-Sicherheit (Block J). App-Credentials aus M33a separat anbinden |
|
||
| `apps/web/app/modules/workflowEngine/components/workflows/stream/WorkflowStreamProgress.tsx` + Routes `workflows.$id.run.stream.*` + `apps/web/app/modules/workflowEngine/routes/.../run.manual.*` | SSE-Streaming der laufenden Execution + manueller Run-Trigger | **als-vorlage** — Live-Streaming-Antwort (Block E) + Test-Run-UX (Block F/M079); Layer-Umbau nötig |
|
||
| `apps/web/app/modules/workflowEngine/utils/workflowExecutionErrorText.ts` + `components/workflows/misc/WorkflowBlockErrors.tsx` + `WorkflowResultBadge.tsx` | Klartext-Fehler-Mapping + Block-Error-/Status-Badges | **anpassen** — Basis für Klartext-Diagnostik (Block J/LP-10); Spec-Klartext-Beispiele (17.9.3) ergänzen |
|
||
| `packages/ai` (`@toolctrl/ai`): `src/index.ts`, `prompts/index.ts` (versionierte Prompt-Registry), `tools/index.ts` (scoped Tool-Registry), `streaming/index.ts`, `guards/index.ts` (`assertAICostBudget`, `createFixedWindowAIRateLimiter`, `createReviewRequiredResult`, PII-Redaction), `fallback.ts` (Multi-Provider EU: Mistral/Scaleway/Aleph-Alpha), `cost/*` | KI-Provider-Layer + Guards + Streaming + Cost-Tracking | **anpassen** — Fundament für KI-Erstellung-per-Sprache (Block E/LP-5). `createReviewRequiredResult` deckt Action-Boundary (EC-5); Rate-Limiter/Cost-Guards für KI-Aufrufe. NEU: Intent-Klassifikation + Entity-Extraction + Flow-Graph-Generierung-Prompts |
|
||
| `packages/ai/src/promptfoo-provider.ts` + `packages/ai/test/evals/` + Repo-Root `promptfoo.config.yaml` | Promptfoo-Eval-Harness (Baseline-Test) als CI-Gate | **als-vorlage** — deckt AV#14 / EC-5 „Promptfoo-Eval-Suite als CI-Pflicht" für die KI-Flow-Generierung (Block E); eigene Eval-Cases neu |
|
||
| `packages/plugin-runtime/src/hooks/registry.ts` (Hooks `workflow.created/updated/deleted/executed/failed`) | zod-validierte Workflow-Lifecycle-Hooks | **1:1** — Audit-Trail-/Activity-Hooks für Rule-Änderungen (AV#6) + Notification-Trigger |
|
||
| `prisma/schema/core.prisma` (`AuditEvent` Hash-Kette, `Event`/`EventWebhookAttempt`) + `packages/db` (`publishOutboxEvent`, `runDbTransaction`, `audit-hash.ts`, DSGVO-FK-Map) | Audit-Trail, transaktionale Outbox, signierte Webhooks | **1:1** — Querschnitt für AV#6 (Rule-Change-Audit), `webhook.send (signiert)` (Block C), Reverse-Audit-Eintrag (Block F) |
|
||
| `prisma/schema/notifications.prisma` + `apps/web/app/modules/notifications/.../NotificationService.ts` | In-App/Email/Push-Delivery + Preferences + DeviceToken | **1:1** — `notification.send_push`/`send_in_app` Actions (Block C) + Anomalie-/Loop-Guard-Notifications (Block G) via `notify()` (M011) |
|
||
| `prisma/schema/featureFlags.prisma` + `evaluateFlagForContext` | Feature-Flag-Engine | **1:1** — DoD-Pflicht „Feature-Flag-fähig" (M006) für das gesamte Modul |
|
||
| `packages/view-models` (`VMState`, `ActionCallbacks`, `I18nLabel`, `assertI18nLabel`) | View-Model-Statusmodell + i18n-Key-Zwang | **1:1** — Konvention M013; Loader baut VM, UI empfängt nur VM+Actions (DoD Layer-Disziplin) |
|
||
| `package.json` Root-Dep `@xyflow/react ^12.10.0` + `dagre` | Graph-Editor-Library bereits installiert | **1:1** — beantwortet die offene Spec-Frage „Flow-Editor-Library-Wahl"; **xyflow ist gesetzt** |
|
||
|
||
## Vorhandene Daten-Modelle (konkret)
|
||
|
||
`prisma/schema/workflows.prisma` — Mapping zur Spec (Block A):
|
||
|
||
| Spec-Entität | Boilerplate-Modell | Lücke |
|
||
| --- | --- | --- |
|
||
| `AutomationRule` | `Workflow` (`name`, `description`, `status`, `tenantId?`, `createdByUserId`, `appliesToAllTenants`) | fehlt: `flow_data`-JSON (BP nutzt normalisierte `WorkflowBlock`-Tabellen statt eines JSON-Blobs — beides valide; Spec nennt JSON, BP-Ansatz ist sauberer), `created_via`, `last_executed_at`, `executions_count_30d`, `archived_at` |
|
||
| `AutomationRuleStep` | `WorkflowBlock` (`type`, `description`, `isTrigger`, `input`, `conditionsGroups`) + `WorkflowBlockToBlock` (Edges) | fehlt: explizites `step_kind`-Enum, `parent_step_ids[]` (BP modelliert Edges als eigene Tabelle — funktional äquivalent für Multi-Parent), `position` für Editor-Layout |
|
||
| `AutomationExecution` | `WorkflowExecution` (`type`, `status`, `input`, `output`, `duration`, `endedAt`, `error`, `waitingBlockId`, `createdByUserId`) | fehlt: `summary_text`, `dry_run`, `idempotency_key`, `reverse_window_expires_at`, `trigger_payload` (steckt in `input`) |
|
||
| `AutomationStepExecution` | `WorkflowBlockExecution` (`status`, `startedAt`, `endedAt`, `input`, `output`, `duration`, `error`) | fehlt: `summary_text`, `error_text` (Klartext getrennt vom techn. `error`), `idempotency_key` pro Step |
|
||
| `AutomationCredential` | `WorkflowCredential` (`name`, `value`, `@@unique([tenantId,name])`, AES-verschlüsselt) | weitgehend vollständig; `description`-Feld + App-Credential-Bridge zu M33a ergänzen |
|
||
| `AutomationTemplate` | (kein DB-Modell) — Templates sind code-basiert in `DefaultWorkflowTemplates.ts` | **komplett neu**: DB-Modell für Tenant-eigene Templates (`is_published`, `category`, `branchen_template_origin`) |
|
||
|
||
Zusätzlich nutzbar: `WorkflowVariable` (tenant-scoped Vars), `WorkflowInputExample` (Sample-Payloads für Dry-Run-Quelle, Block F offener Punkt), `IdempotencyKey` (core.prisma).
|
||
|
||
## Lücken / komplett neu zu bauen
|
||
|
||
1. **Domänen-Trigger-Library (~45 Trigger, Block B / M075):** Boilerplate kennt nur generische Trigger (`manual`, `event` mit `row.created/updated/deleted` + Account/Member/Subscription/Email-Events). Alle HiveGrid-Trigger fehlen: `deal.*` (created/stage_changed/won/lost/stuck/assignee_changed/volume_changed), `project.*`, `lead.*`, `contact.*`, `booking.*`, `call.*` (Telefonie), `task.*`, `form.submitted`, `email.received_inbox`/`subject_pattern_matched`, `kwp.*`, `app.*`, `hr.*`, `portal.*`, `schedule.cron`/`delay`. → Als Plug-Registry-Einträge + Domain-Event-Emission in den jeweiligen Modulen.
|
||
2. **Domänen-Action-Library (~40 Actions, Block C / M076):** BP hat nur `httpRequest`, `log`, `alertUser`, `gpt`, `rowGet/Create/Update/Delete`. Fehlen alle CRM/Lead/Sales/Project/Communication/Task/KWP/Calendar/File-Actions inkl. **Pipeline-Targeting** (`deal.create` mit Ziel-Pipeline+Start-Stage), `project.create_from_won_deal` (Won-Handoff mit Default-Mapping), `email.send` (Template+Vars), `notification.send_push/in_app`, `webhook.send (signiert)`, `ai.summarize/classify`. Flow-Control `if`/`switch` vorhanden; `delay`/`parallel`/`merge` ergänzen; **`loop` bewusst NICHT** (Anti-Liste). KI-Actions auf `packages/ai` mappen.
|
||
3. **24h-Undo / Reverse-Window (Block F / M080):** Komplett neu. Kein Reverse-Mechanismus in BP. Benötigt: `reverse_window_expires_at`, Snapshot der reversiblen Wirkungen pro Run, Reverse-Handler (Hard-Delete angelegter Entitäten / Status-Reset / Tag-Rückgängig / Empfänger-Liste bei Mails), BullMQ-delayed Cleanup-Job nach 24h, Multi-Step-Confirm + Audit-Eintrag pro Reverse.
|
||
4. **Anomalie-Detection + Loop-Guard mit Klartext (Block G / M081):** Komplett neu. Hard-Limit 1.000/h pro Trigger (tenant-konfigurierbar), 10×-Rate-Anomalie→Pause+Notification, Loop-Guard max. 5 Auto-Trigger/Datensatz/60s, Pre-Save-Cycle-Detection mit Klartext-Visualisierung. (BP `createFixedWindowAIRateLimiter` ist NUR für AI-Calls pro userId — nicht für Trigger-Volumen.)
|
||
5. **KI-Erstellung per natürlicher Sprache (Block E / wird in M086 referenziert):** Engine-Bausteine (`packages/ai`, Prompt-/Tool-Registry, Streaming, Promptfoo, `createReviewRequiredResult`) vorhanden, aber die **KI-Pipeline selbst neu**: Intent-Klassifikation, Entity-Extraction (Trigger/Filter/Actions), Schema-Validation gegen existierende Pipelines/User/Forms (EC-4), Rückfrage-bei-Mehrdeutigkeit, Flow-Graph-Generierung als JSON, Risiko-Hinweise, Edit-Mode-Diff, Voice via Whisper-EU (M18). Hinweis Spec: M078 listet M086 (KI-Sprache) als „benötigt von" — KI-Erstellung ist eigener Milestone-Strang.
|
||
6. **Dry-Run mit Empfänger-Sample + >100-Schwelle (Block F / M079):** BP hat Test-Run/manual-Run + SSE-Streaming, aber **keinen** Side-Effect-freien Dry-Run mit „würde X Personen treffen, erste 5: …", keine konfigurierbare Schwellenwert-Bestätigung (Default 100), kein Mock-Adapter-Layer für Actions.
|
||
7. **Trigger-Volumen-Metering (Block L / M082):** Komplett neu. Counter `AutomationExecution` pro Tenant/Monat, Soft-Limit-Warnung bei 80%, Hard-Limit→Queue+Klartext, Visualisierung in `/{tenant}/admin/usage/`. (BP hat `MetricLog`/AI-Cost-Aggregate als Muster, aber kein Trigger-Volumen.)
|
||
8. **Stage-Stuck-Eskalation als Daily-Cron (Block K):** Neu — Cron checkt `stage.auto_archive_after_days`, emittiert `deal.stuck.in_stage`/`project.stuck.in_stage`. Reconciler-Cron-Muster (`workflow-execution-stalled-reconciler-cron.ts`) als Vorlage.
|
||
9. **HiveGrid-Permissions + Bundles (Block M):** Neu — `automation.read/test/write/activate/delete/reverse/use_ki/admin` + Bundles `basic/builder/publisher/admin` + SHK-Default-Rollen. BP-Workflow-Routes nutzen generische Auth-Boundary (`workflowAccess.server.ts`), nicht diese Permissions. Über M004 `withPermission()` verdrahten.
|
||
10. **Klartext-Step-Diagnostik nach Spec (Block J / M082):** BP hat Execution-Detail-Views + Error-Text-Mapping, aber die konkreten Spec-Klartext-Texte (17.9.3: „Email an X gesendet, Dauer 0.8s", Halb-Erfolg, Skipped-mit-Grund) + „Detail-Logs für Plattform-Admin (`tech_details`)" + Re-Run-aus-Log neu formulieren.
|
||
11. **Layer-Umbau (querschnittlich, PR-Block-relevant):** Der gesamte `apps/web/app/modules/workflowEngine/`-Editor-/Service-Stack muss in die HiveGrid-Drei-Schichten überführt werden: View-Models → `packages/view-models/src/automation/*.vm.ts`, UI → `packages/ui-hivegrid/src/...` (kein `useLoaderData`, kein Prisma-Import), Subframe-Output via Adapter. **`.server.ts`-Re-Export verboten (User-Memory) → Component-Extraktion.** Sidebar-Eintrag „Automation-Studio" in Gruppe `automation-ki` (INTEGRATION-CONTRACTS §1), Routen unter `/{tenant}/automations/...` (Spec-Pfade) statt BP-`__workflows/workflow-engine`.
|
||
|
||
## Empfohlenes Vorgehen
|
||
|
||
**Phase 1 — Fundament aus Boilerplate übernehmen (M075):**
|
||
1. `prisma/schema/workflows.prisma` als Basis nach HiveGrid übernehmen, um Spec-Felder erweitern (`created_via`, `archived_at`, `dry_run`, `idempotency_key`, `reverse_window_expires_at`, `summary_text`/`error_text`, `position`) + neues `AutomationTemplate`-DB-Modell. Forward-Only-Migration.
|
||
2. Outbox→Workflow-Fanout-Worker (`workflow-trigger*.ts`) + `event-router.ts` (`workflow.`-Prefix ist schon verdrahtet) 1:1 übernehmen.
|
||
3. Block-Type-Registry-Architektur (`WorkflowBlockTypes.ts` + `WorkflowBlockService.ts`) als Plug-Registry übernehmen; HiveGrid-Domain-Trigger als erste Einträge ergänzen + Domain-Events in CRM/Lead/Sales/Project emittieren.
|
||
|
||
**Phase 2 — Actions + Conditions (M076/M077):**
|
||
4. Action-Registry mit Idempotency-Key (`foundation/idempotency.ts`) ausbauen; Domänen-Actions inkl. Pipeline-Targeting + Won-Handoff neu; Flow-Control `delay/parallel/merge` ergänzen (kein `loop`).
|
||
5. `WorkflowsConditionsService`/`WorkflowConditionUtils` übernehmen, um `Time-Of-Day`/`Day-Of-Week`/`User-In-Group` + type-safe Feld-Picker erweitern.
|
||
|
||
**Phase 3 — Editor (M078):**
|
||
6. `WorkflowBuilder`-Editor (xyflow + dagre) als Vorlage in `packages/ui-hivegrid` + Adapter überführen (Layer-Disziplin, Component-Extraktion statt `.server`-Re-Export). `WorkflowPreflightService` übernehmen + Cycle-/„nicht-verbunden"-Klartext-Validierung ergänzen. Pflicht-Aktivierung als separater Schritt.
|
||
|
||
**Phase 4 — USP-Mechaniken neu (M079–M082):**
|
||
7. M079: Dry-Run-Mode mit Mock-Action-Adapter + Empfänger-Sample + >100-Schwelle (BP Test-Run/Streaming als UX-Vorlage).
|
||
8. M080: 24h-Undo/Reverse-Window komplett neu (Snapshot + Reverse-Handler + delayed Cleanup-Job + Audit).
|
||
9. M081: Anomalie-Detection + Loop-Guard + Resume/Backoff — Resume ist in `WorkflowsExecutionsService` (`fromBlockId`) + Stalled-Reconciler vorhanden; Rate-Limit/Anomalie/Loop-Guard neu; Backoff-Stufen 1m/5m/15m/1h/6h/24h via `queue/producers.ts` konfigurieren.
|
||
10. M082: Klartext-Logs (BP Error-Text-Mapping + Execution-Detail als Vorlage) + Re-Run + Trigger-Volumen-Metering (neu, `MetricLog`/AI-Cost-Aggregate als Muster).
|
||
|
||
**Querschnitt parallel:** Permissions/Bundles (M004), Feature-Flag (M006), Audit-Hooks (`plugin-runtime` workflow-Hooks + `AuditEvent`), `notify()` (M011), Sidebar/Routes (INTEGRATION-CONTRACTS), Promptfoo-Eval-Gate für die spätere KI-Erstellung (`packages/ai/test/evals` als Vorlage). Templates-Registry (`DefaultWorkflowTemplates.ts`-Muster) mit SHK-Templates befüllen.
|