# R-P14D · WorkflowEngine vom Entity-Builder typisiert ablösen | | | |---|---| | **Typ** | Dev (Code) | | **Owner** | Raffael (+ Agent) | | **Phase** | P6 / P14 (Entity-Builder-Ablösung, AD-2) — **Teil 2** | | **Plane** | kein eigenes Ticket — getrackt über `R-P14C` (HIVEGRID-169) · Child von `R-P14C-T2` (Audit 2026-07-19) | | **Größe** | **L** (Audit-Schätzung ~4–6 Wochen, abhängig vom Registry-Umfang) | | **Status** | **ENTSPERRT (Raffael 2026-06-30):** Kontakt-only adressierbar, generischer Block über Registry. Größe damit eher **S–M** (kein Voll-Parität-Nachbau). Slice 0 = Modell-Registry bauen. | ## Abhängigkeiten & Parallelität - **blocked-by:** `R-P14C-T2` Quer-Entscheidung (welche typisierten Modelle adressierbar, Feld-Adressierung) + die **typisierte Modell-Registry** (geteilter Baustein, s. T2). - **blocks:** `R-P6B-β` (EntitiesSingleton-Removal) — solange die Pro-Blöcke `EntitiesSingleton`/`RowsApi` nutzen, kann β nicht löschen. - **koordiniert mit:** `R-P14E` (formulas) teilt die Modell-Registry. Akeshan einbinden (Modul ruhte unter R-P14C). ## Was wir bauen Die **vier Pro-Workflow-Blöcke** `rowGet / rowCreate / rowUpdate / rowDelete` (in `services/blocks/WorkflowBlockProService.ts`) operieren heute auf **beliebigen generischen Entities per Name**: der Workflow-JSON nennt `entity: ""`, der Block löst ihn via `EntitiesSingleton.getEntity({name})` auf und CRUDt über `RowsApi.get/create/update/del`. Das ist die einzige zentrale Entity-Builder-Kopplung im Modul (die übrigen Blöcke `waitForInput`/`email` sind builder-frei). Ziel: Diese vier Blöcke auf die **typisierte Modell-Registry** umstellen — ein Workflow adressiert ein **typisiertes** Modell (Kontakt/Projekt/… laut ENTITY-MODEL) statt einer generischen Entity, und das CRUD läuft über typisiertes Prisma statt `RowsApi`. Semantik (Block-Input/Output, Variablen-Substitution, `eventContext: { source: "workflow" }`) bleibt erhalten, damit bestehende Workflow-Definitionen weiter funktionieren — soweit sie ein adressierbares Modell treffen. `WorkflowsTemplatesService.ts` (zweite EB-Stelle) muss mitgezogen werden (Template-Workflows referenzieren Entities). ## Benötigte Screens Keine neuen — Workflow-Editor-UI bleibt. **Aber:** der Block-Editor muss statt freier `entity`-Strings die **adressierbaren Modelle** als Auswahl anbieten (Davids Delta klären, falls die UI eine Liste braucht). Solange das Modell-Set klein/fest ist, evtl. nur ein Dropdown statt Freitext. ## Definition of Done - [x] `rowGet/rowCreate/rowUpdate/rowDelete` nutzen die **typisierte Modell-Registry** statt `EntitiesSingleton`/`RowsApi`; kein Import aus `~/utils/api/.server/RowsApi`, `~/modules/rows/**`, `~/utils/db/entities/**` mehr im Modul. - [x] Block-Input-Validierung (`WorkflowsValidationService`) auf typisierte Felder/Modelle angepasst; unbekanntes/nicht-adressierbares Modell → Klartext-Fehler (M002), nicht stiller Fail. - [x] `WorkflowsTemplatesService` builder-frei; Template-Workflows referenzieren nur adressierbare Modelle. - [x] `WorkflowBlockProService.test.ts` (mockt heute `RowsApi`/`EntitiesSingleton`) auf die Registry umgestellt; `workflow-producer-inventory.test.ts`-Fixtures nachgezogen. Workflow-Block-Execution voll getestet (rowGet/Create/Update/Delete gegen typisiertes Modell). - [x] **Bestehende Workflow-Definitionen:** Pre-Launch existieren keine produktiven Workflow-Daten (0 echte Tenants) → reiner Code-Umbau, keine Daten-Migration. Alte generische `entity`-Referenzen, die kein adressierbares Modell treffen, liefern jetzt einen Klartext-Fehler im Block. - [x] Reachability: `app.$tenant/__workflows/**` Routen + (disabled) Admin bleiben konsistent; Block-Typen unverändert (`entity`-Feld bleibt ein String, der jetzt auf einen Registry-Key auflöst). - [x] Voller CI-Scope grün (typecheck + lint + test:foundation/packages/mobile + test + verify:i18n + verify-cross-cutting-models + verify:workflow-outbox-native). - [x] AD-2: keine neuen Entity-Builder-Konsumenten; `EntitiesSingleton`/`RowsApi`-Importe im Modul = 0. ## Umsetzung - 2026-06-30 (autonomer Lauf, Branch `feat/R-P14C-teil2`): **Slice A0 + A1 umgesetzt, 8/8 DoD = 100 %.** - **A0 (geteilter Baustein):** `apps/web/app/services/typed-model-registry/` neu — `types.ts` (`TypedModelAdapter`/`FieldSchema`/`ModelCtx`/`TypedModelError`), `registry.server.ts` (`getModelAdapter`/`getModelAdapterOrThrow`/`listModelKeys`, statisches Objekt-Literal analog `indexedEntities`), `kontaktAdapter.server.ts` (read/create/update/delete über `crmService.server` + Audit/Activity via `crmAudit`). Adressierbar: nur `Kontakt` (Registry wächst mit R-P7+). 9 Unit-Tests. - **A1 (Workflow):** Die vier `row*`-Blöcke in `WorkflowBlockProService.ts` lösen `entity:""` jetzt über die Registry auf; `EntitiesSingleton`/`RowsApi`/`ApiHelper`-Importe raus. `WorkflowsTemplatesService` validiert Template-Entities gegen `listModelKeys()` statt `getAllEntities`. Tests (`WorkflowBlockProService.test.ts`, `WorkflowsTemplatesService.import.test.ts`) auf Registry-Mock umgestellt; `workflow-producer-inventory.test.ts` + `outbox-pattern.md`/`worker-queues.md` nachgezogen (Workflow-Blöcke produzieren keine generischen `row.*`-Outbox-Events mehr, sondern Audit/Activity des typisierten Modells). - Workflow bleibt **nav-versteckt/disabled** (nur entkoppelt, NICHT für v1 freigeschaltet — gesetzte Entscheidung). - Proof: voller CI-Scope lokal grün (35 Workflow-Tests, 284 workflow-outbox-native-Tests, 3672 Core-Tests). ## Technische Bausteine - **Modell-Registry** (aus `R-P14C-T2`): `name → { read, create, update, delete, fieldSchema }` über typisierte Prisma-Modelle. Ersetzt `EntitiesSingleton.getEntity` (Metadaten) + `RowsApi.*` (CRUD). - **`ApiHelper`-Ersatz:** `ApiHelper.getApiFormat(entity, item)` / `getRowPropertiesFromJson(...)` formen heute generische Row↔JSON. Typisiert: Mapper Modell↔JSON je adressierbarem Modell (oder generisch über das Registry-`fieldSchema`). - **Variablen-Substitution** (`parseVariable`/`WorkflowsVariablesService`) bleibt; nur die Datenquelle wechselt. - **Tenant-Scope:** `RowsApi`-Calls trugen `tenantId`/`userId`; typisiert über `withTenantScope()`/`withPermission()` (M004) bzw. RLS — kein manueller Filter. - **Audit/Activity:** `eventContext: { source: "workflow" }` → typisiert via M001-Middleware/`auditEvent` + ggf. `logActivity` (DoD §C). - AD-21: kein eigenes neues Schema nötig (operiert auf bestehenden typisierten Modellen); falls Workflow-eigene Tabellen angefasst werden, eigene `prisma/schema/workflows.prisma`. ## Offene Entscheidungen (vor Bau klären) 1. **Adressierbares Modell-Set** = Quer-Entscheidung T2 (welche ENTITY-MODEL-Modelle dürfen Workflows CRUDen?). 2. **Generischer vs. fester Block:** Bleibt ein *generischer* „row*"-Block (Modell per Parameter, über Registry) oder werden es **pro Modell** typisierte Blöcke (`kontaktCreate`, …)? Generisch = näher am Bestand, fest = sauberer typisiert. **Empfehlung:** generisch über Registry (minimaler UI-/Definition-Bruch). 3. **Alt-Daten:** Existieren produktive Workflow-Definitionen mit generischen `entity`-Referenzen? Wenn ja: Mapping nötig. Wenn nein (Pre-Launch): reiner Code-Umbau. ## Quellen - `R-P14C-T2.md` (Übersicht + Quer-Entscheidung + Registry). - `WorkflowBlockProService.ts` (Bestands-Implementierung der vier Blöcke). - `R-P6B.md` §Rückwirkungs-Audit (WorkflowEngine kritisch). - `docs/ARCHITECTURE-DECISIONS.md` AD-2 · AGENTS.md §Querschnitt-Hülle (M001/M002/M004).