7.3 KiB
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 | neu · Child von R-P14C-T2 |
| 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-T2Quer-Entscheidung (welche typisierten Modelle adressierbar, Feld-Adressierung) + die typisierte Modell-Registry (geteilter Baustein, s. T2). - blocks:
R-P6B-β(EntitiesSingleton-Removal) — solange die Pro-BlöckeEntitiesSingleton/RowsApinutzen, 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 WorkflowBlockProService.ts) operieren heute auf beliebigen generischen Entities per Name: der Workflow-JSON nennt entity: "<name>", 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
rowGet/rowCreate/rowUpdate/rowDeletenutzen die typisierte Modell-Registry stattEntitiesSingleton/RowsApi; kein Import aus~/utils/api/.server/RowsApi,~/modules/rows/**,~/utils/db/entities/**mehr im Modul.- Block-Input-Validierung (
WorkflowsValidationService) auf typisierte Felder/Modelle angepasst; unbekanntes/nicht-adressierbares Modell → Klartext-Fehler (M002), nicht stiller Fail. WorkflowsTemplatesServicebuilder-frei; Template-Workflows referenzieren nur adressierbare Modelle.WorkflowBlockProService.test.ts(mockt heuteRowsApi/EntitiesSingleton) auf die Registry umgestellt;workflow-producer-inventory.test.ts-Fixtures nachgezogen. Workflow-Block-Execution voll getestet (rowGet/Create/Update/Delete gegen typisiertes Modell).- 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. - 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). - Voller CI-Scope grün (typecheck + lint + test:foundation/packages/mobile + test + verify:i18n + verify-cross-cutting-models + verify:workflow-outbox-native).
- 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 analogindexedEntities),kontaktAdapter.server.ts(read/create/update/delete übercrmService.server+ Audit/Activity viacrmAudit). Adressierbar: nurKontakt(Registry wächst mit R-P7+). 9 Unit-Tests. - A1 (Workflow): Die vier
row*-Blöcke inWorkflowBlockProService.tslösenentity:"<key>"jetzt über die Registry auf;EntitiesSingleton/RowsApi/ApiHelper-Importe raus.WorkflowsTemplatesServicevalidiert Template-Entities gegenlistModelKeys()stattgetAllEntities. Tests (WorkflowBlockProService.test.ts,WorkflowsTemplatesService.import.test.ts) auf Registry-Mock umgestellt;workflow-producer-inventory.test.ts+outbox-pattern.md/worker-queues.mdnachgezogen (Workflow-Blöcke produzieren keine generischenrow.*-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).
- A0 (geteilter Baustein):
Technische Bausteine
- Modell-Registry (aus
R-P14C-T2):name → { read, create, update, delete, fieldSchema }über typisierte Prisma-Modelle. ErsetztEntitiesSingleton.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 trugentenantId/userId; typisiert überwithTenantScope()/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)
- Adressierbares Modell-Set = Quer-Entscheidung T2 (welche ENTITY-MODEL-Modelle dürfen Workflows CRUDen?).
- 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). - 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.mdAD-2 · AGENTS.md §Querschnitt-Hülle (M001/M002/M004).