Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-P14D.md
T
2026-07-08 16:15:37 +02:00

7.3 KiB
Raw Blame History

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-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 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/rowDelete nutzen die typisierte Modell-Registry statt EntitiesSingleton/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.
  • WorkflowsTemplatesService builder-frei; Template-Workflows referenzieren nur adressierbare Modelle.
  • 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).
  • 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 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:"<key>" 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).