Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-P14D.md
T

62 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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: "<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
- [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:"<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).