# R-P14C-T2 · Entity-Builder-native Module typisiert ablösen (Teil 2) — Übersicht | | | |---|---| | **Typ** | Dev (Code) — **Meta/Übersicht** (verteilt auf Child-Tickets) | | **Owner** | Raffael (+ Agent) | | **Phase** | P6 / P14 (Entity-Builder-Ablösung, AD-2) | | **Plane** | neu · Teil 2 von `R-P14C` (#169) | | **Status** | **ENTSCHIEDEN (Raffael 2026-06-30, §Abnahme):** `R-P14D` (+`R-P14F`) baubar · `R-P14E`+`R-P14G` = Cut mit β | > **Diese Datei ist die Übersicht.** Die eigentlichen Bau-Tickets sind die Child-Docs `R-P14D` (WorkflowEngine), `R-P14E` (formulas), `R-P14F` (onboarding), `R-P14G` (codeGenerator). Hier steht das gemeinsame Problem, die geteilte Vorbedingung und die zentrale offene Entscheidung, die alle vier blockiert. ## Kontext (warum dieses Ticket existiert) `R-P14C` (Teil 1, **fertig** auf Branch `feat/R-P14C`) hat **EmailMarketing** typisiert und den `CrmService`-Legacy-Reader entfernt (Variante A — Editor entfernt, nicht migriert). Damit ist der **erste** Schritt der R-P6B-Migrationskette durch. **Teil 2** nimmt die übrigen, in R-P6B §Rückwirkungs-Audit gelisteten gebauten Entity-Builder-Konsumenten dran, damit anschließend **R-P6B-β** (`EntitiesSingleton`-Removal + `modules/rows`/`utils/db/entities` + `entityBuilder.prisma` löschen) entsperrt werden kann. ## Befund aus dem Teil-2-Audit (2026-06-30) Anders als EmailMarketing (peripherer Konsument) sind diese vier Module **im Kern Entity-Builder-Maschinerie** — sie konsumieren den Builder nicht nur, sie operieren auf dem *generischen Entity-Begriff*: | Modul | Was es im Kern tut | EB-Berührung (nicht-Test) | Routen-Status | Größe | |---|---|---|---|---| | **workflowEngine** | Pro-Blöcke `rowGet/rowCreate/rowUpdate/rowDelete` CRUDen **beliebige generische Entities** per Name (`EntitiesSingleton.getEntity` + `RowsApi`) | 2 Dateien (`WorkflowBlockProService`, `WorkflowsTemplatesService`) | Public-Slug disabled, `admin/__workflows/**` disabled, `app.$tenant/__workflows/**` registriert (nav-versteckt) | **L** | | **formulas** | Formel-Evaluation **über Entity/Property/Row** (`RowHelper.getPropertyValue`, `getAllEntities`) | 3 Dateien (`FormulaService`, `FormulaRowService`, `FormulaVariableValueDto`) | lebt in `admin/entities/**` + `settings/entities/**` (= EB-UI, die β löscht) | **M** | | **codeGenerator** | **generiert Code AUS Entity-Definitionen** (Prisma/DTO/Routes-Templates) — Meta-Werkzeug | 27 von 29 (Template-Input `EntityWithDetails`) | nur `admin/entities/code-generator/**` (EB-Admin) | **M** (aber Sonderfall, s.u.) | | **onboarding** | `getAllEntities` (Onboarding-Config) + `RowsApi.count` (Filter-Vorschau) | 2 Dateien (`OnboardingService`, `OnboardingFiltersService`) | Slug disabled; `admin/onboarding/**` + public `/onboarding/$id` | **S–M** | **Belege:** `WorkflowBlockProService.ts:7,62,99,138,182` · `FormulaService.ts:8-10,173,187` · `OnboardingService.ts:3,225` · `OnboardingFiltersService.ts` (`RowsApi.count`) · `CodeGeneratorService.ts:1` (`EntityWithDetails`). Routen-Disabled: `routes.ts` `defaultDisabledPluginRouteFilePatterns` (`admin/__workflows/**`), `PublicRouteSegments.ts` `disabledPluginRouteSlugs` (`workflow-engine`, `onboarding`). ## 🔴 Quer-Entscheidung (blockiert ALLE vier Child-Tickets) „Typisiert neu bauen" (Richtungsentscheid Raffael, 2026-06-30) heißt für diese Module **nicht** „ein paar Imports tauschen". Es fehlt das **typisierte Ziel**, auf dem die Engines laufen sollen. Ein Workflow-`rowCreate`-Block braucht ein konkretes Ziel-Modell; eine Formel braucht typisierte Felder. Zwei Entscheidungen, die in den Specs als offen markiert sind und vor dem Bau fallen müssen: 1. **Welche typisierten Modelle sind „adressierbar"?** (Workflows + Formeln müssen wissen, auf welchen Modellen sie operieren dürfen — Kontakt, Projekt, Auftrag, … aus dem ENTITY-MODEL). Daraus folgt der gemeinsame Baustein **typisierte Modell-Registry** (§Geteilte Vorbedingung). 2. **Feld-Adressierung typisiert** — wie referenziert ein Workflow/eine Formel ein Feld eines Modells, wenn es keine generischen `Property`-Zeilen mehr gibt? (statisches Feld-Schema je Modell vs. Code-generierte Metadaten). > Solange (1)+(2) offen sind, ist kein Child-Ticket autonom baubar — sonst würde der Agent Produkt-/Architektur-Richtung **erfinden** (AGENTS.md §Ticket-Treue: PR-Block). Die Specs liefern Optionen + Empfehlung; die Auswahl ist Raffaels Call. ## Geteilte Vorbedingung: typisierte Modell-Registry (neuer Baustein) `EntitiesSingleton.getEntity({name})` liefert generische Entity-Metadaten (Properties als Zeilen). Der typisierte Ersatz ist eine **Modell-Registry**: `name → { read(id), create(data), update(id,data), delete(id), fieldSchema }` über die **typisierten** Prisma-Modelle (R-P6-`Kontakt` etc.). Diese Registry ist: - die **gemeinsame** Grundlage für `R-P14D` (Workflows) **und** `R-P14E` (Formeln), - der erste Baustein der späteren `EntitiesSingleton`-Ablösung in **R-P6B-β** (49 appweite Konsumenten) — sollte also so entworfen werden, dass β darauf aufbaut, - **neu zu spezifizieren** (Umfang der Registry = Quer-Entscheidung 1). Empfehlung: Registry als eigenes kleines Ticket **vor** R-P14D/E ziehen (Vorbedingung), damit beide darauf aufsetzen. (Als `R-P14D` Slice 0 oder eigenes `R-P6B-REG` — Owner-Entscheid.) ## Reihenfolge (Migrationskette, Teil 2) 1. **Quer-Entscheidung (1)+(2)** klären (Raffael) → typisierte Modell-Registry spezifizieren/bauen. 2. **R-P14E (formulas)** und **R-P14D (workflowEngine)** auf die Registry migrieren (parallelisierbar, sobald Registry steht). 3. **R-P14F (onboarding)** entkoppeln (klein, peripher, kann früh/parallel). 4. **R-P14G (codeGenerator)** Disposition entscheiden (Cut vs. Rebuild — Sonderfall, s. Doc). 5. Erst wenn Teil 1 (R-P14C) **und** Teil 2 (D/E/F/G) durch sind → **R-P6B-β** entsperrt. ## Definition of Done (dieses Übersichts-Tickets) - [x] Teil-2-Audit durchgeführt (aktiv/dead, EB-Kopplungstiefe, Größenklassen) — siehe Tabelle oben. - [x] Child-Specs entworfen: `R-P14D`, `R-P14E`, `R-P14F`, `R-P14G`. - [x] Geteilte Vorbedingung (typisierte Modell-Registry) + zentrale Quer-Entscheidung benannt. - [x] **Quer-Entscheidung (1)+(2) von Raffael getroffen** (2026-06-30): adressierbar = `Kontakt` über wachsende Registry; Feld-Adressierung über `fieldSchema`. - [x] Child-Tickets umgesetzt (autonomer Lauf 2026-06-30): `R-P14D` (Workflows → Registry) + `R-P14F` (onboarding entkoppelt) gebaut; `R-P14E` (formulas) + `R-P14G` (codeGenerator) = **Cut mit β**. → **R-P6B-β entsperrt UND umgesetzt** (`feat/R-P6B-beta`, voller CI-Scope grün). ## Quellen - `R-P6B.md` §Migrationskette & Ownership + §Rückwirkungs-Audit (Konsumenten-Matrix). - `R-P14C.md` §Umsetzung (Teil 1 fertig, Variante A). - `docs/ARCHITECTURE-DECISIONS.md` AD-2 (Entity-Builder raus, „Migration durch Neubau"), AD-20 (projekt-zentrisch), AD-21 (Prisma-Schema/Migration). - `.planning/ENTITY-MODEL.md` (welche typisierten Modelle adressierbar sind — Quer-Entscheidung 1). - Teil-2-Audit 2026-06-30 (Codebase-Kartierung, oben). ## 🟢 Konkreter Vorschlag zur Abnahme (2026-06-30, Option B) Ausgearbeitet aus dem ENTITY-MODEL + Codebase-Stand. **Raffael: abnicken oder korrigieren** — danach ist der Bau entsperrt. ### Befund, der alles vereinfacht - Die **WorkflowEngine ist bereits typisiert** (`prisma/schema/workflows.prisma`: `Workflow`/`WorkflowBlock`/`WorkflowExecution`/…). Die **einzige** Entity-Builder-Kopplung sind die `rowGet/Create/Update/Delete`-Blöcke, die auf *generische* Entities zeigen. - Typisiert **gebaut** ist heute nur **`Kontakt`** (R-P6, `crm.prisma`) + **`Lead`** (`marketingLeads.prisma`). `Projekt`/`Rechnung`/`Termin`/`Aufgabe`/… kommen erst mit R-P7/R-P8+. - **Formeln** stehen **nicht** als eigene v1-Entität im ENTITY-MODEL (Domäne 7 = Automation/AutomationRule; keine „Formula"). → Sie sind reine Entity-Builder-Funktion (berechnete Properties). ### Vorschlag 1 — Adressierbares Modell-Set = „was typisiert gebaut ist", über eine wachsende Registry Nicht alle theoretischen Modelle auf einmal. Die **Modell-Registry** startet mit dem, was typisiert existiert, und wächst, wenn R-P7/R-P8+ neue Modelle bauen: - **Jetzt adressierbar:** `Kontakt` (+ `Lead`). - **Später (registrieren, sobald gebaut):** `Projekt`, `Rechnung`, `Termin`, `Aufgabe`, `Checkliste` … (Kern-Kette). - Konsequenz: **R-P14D wird viel kleiner** als die Audit-Schätzung (4–6 Wo) — kein generischer Voll-Parität-Nachbau, sondern „row-Blöcke an die Registry hängen, Registry mit Kontakt seeden". Realistisch **S–M** statt L. ### Vorschlag 2 — Die typisierte Modell-Registry (geteilter Baustein) Ein kleiner Adapter-Registry-Layer (analog zu Such-Index-/Sidebar-Registries), der `EntitiesSingleton.getEntity(name)` + `RowsApi.*` ersetzt: ```ts // packages/… oder apps/web/app/services/typed-model-registry/ interface TypedModelAdapter { key: string; // "kontakt" — stabiler Adress-Schlüssel label: string; // i18n-Key read(id: string, ctx: ModelCtx): Promise; create(data: unknown, ctx: ModelCtx): Promise; update(id: string, data: unknown, ctx: ModelCtx): Promise; delete(id: string, ctx: ModelCtx): Promise; fieldSchema: FieldSchema; // { name, type, required, … } je Feld — ersetzt PropertyWithDetails } type ModelCtx = { tenantId: string | null; userId?: string }; // registry.get("kontakt") → Adapter ; alle Ops über withTenantScope()/withPermission() (M004) + Audit (M001) ``` - **Kontakt** registriert seinen Adapter aus `crm.prisma`/`utils/integrations/crm`. Neue Modelle registrieren beim Bau (R-P7+). - Diese Registry ist **auch die Grundlage für R-P6B-β** (die ~49 appweiten `EntitiesSingleton`-Konsumenten für Entity-Metadaten migrieren später auf `fieldSchema`/Modell-Liste). - **Empfehlung:** Registry als eigenen kleinen Vor-Slice (`R-P14D` Slice 0) bauen. ### Vorschlag 3 — Empfehlung pro Modul | Modul | Empfehlung | Warum | |---|---|---| | **workflowEngine** (`R-P14D`) | **Generischer `row*`-Block über die Registry** (Modell per Parameter), adressierbares Set = registrierte Modelle (Kontakt jetzt) | Engine schon typisiert; nur 4 Blöcke umhängen; minimaler Definition-/UI-Bruch; wächst mit den Modellen | | **formulas** (`R-P14E`) | **CUT mit β** (kein typisierter Neubau) | Keine v1-Entität im ENTITY-MODEL; reine Entity-Builder-Funktion (berechnete Properties); stirbt sauber mit dem Builder | | **codeGenerator** (`R-P14G`) | **CUT mit β** | Meta-Werkzeug, generiert Code aus Entity-Defs; ohne Builder kein Input/Nutzen | | **onboarding** (`R-P14F`) | **EB-Touchpoints entfernen** (nicht typisieren) | onboarding hat eigenes typ. Schema; `getAllEntities`/`RowsApi.count` sind Boilerplate-Reste, in v1 ohne Funktion | **Netto wenn so abgenickt:** Nur **ein** echtes Bau-Ticket bleibt aktiv (`R-P14D` workflows, jetzt S–M dank Registry + kleinem Modell-Set) + die triviale onboarding-Entkopplung (`R-P14F`). `R-P14E` (formulas) + `R-P14G` (codeGenerator) werden **kein eigener Bau**, sondern wandern in `R-P6B-β`s Lösch-Scope. Das schrumpft Teil 2 drastisch. ### Abnahme (Raffael, 2026-06-30) — ✅ ENTSCHIEDEN - [x] **V1:** Adressierbares Set startet mit **`Kontakt`** (wächst per Registry mit R-P7+). Bedingung „Kontakt nutzt den Entity-Builder nicht mehr" **bestätigt** (`utils/integrations/crm` = 0 EB-Importe, `Kontakt` echte Prisma-Tabelle). `Lead` optional mitnehmen, wenn billig. - [x] **V2:** Modell-Registry als geteilter Baustein bauen (Adapter-Interface oben), Slice = `R-P14D` Slice 0. - [x] **V3a:** workflows = generischer `row*`-Block über Registry, nur `Kontakt` adressierbar (vorerst). → **`R-P14D` baubar.** - [x] **V3b:** formulas = **Cut mit β** (kein Rebuild). → `R-P14E` wird Cut-Ticket. - [x] **V3c:** codeGenerator = **Cut mit β**. → `R-P14G` wird Cut-Ticket. - [x] **V3d:** onboarding = **entity-basierte Filter-Bedingungen entfernen** (`entity.hasCreated`/`hasNotCreated` + `entities`-Metadata), Rest von onboarding bleibt. Diese Bedingungen sind ohne Entity-Builder bedeutungslos. → `R-P14F` (klein). *(Falls „Nutzer hat Kontakt angelegt" später als Onboarding-Bedingung gewünscht ist: neuer typisierter Filter, eigenes Mini-Ticket.)* ## 🟩 Ebene-1 Mega-Plan — entschieden 2026-06-30 (für einen autonomen Lauf) Vollständiger, rückfragefreier Plan: Entity-Builder bis zum Ende ablösen = **Teil 2 + R-P6B-β** in *einem* autonomen Lauf. ### Gesetzte Entscheidungen (keine Rückfragen mehr nötig) - **Daten:** keine echten Tenants (Prod existiert, aber 0 echte Tenants) → β = Tabellen **droppen**, forward-only Migration, **kein Export/keine Daten-Migration**. Größter R-P6B-Blocker entfällt. - **Lauf-Umfang:** Teil 2 **und** β in einem Lauf (Raffael: ja). - **Workflow-Engine:** nur **entkoppeln**; Status bleibt wie jetzt (nav-versteckt/`disabledPluginRouteSlugs`), **NICHT** für v1 freischalten. - **Adressierbar:** nur **`Kontakt`** (Registry wächst später). `Lead` optional, wenn billig. - **formulas + codeGenerator:** **Cut mit β** (kein Rebuild). - **onboarding:** nur die entity-basierten Filter-Bedingungen entfernen (`entity.hasCreated`/`hasNotCreated` + `entities`-Metadata), Rest bleibt. - **Collab/hocuspocus:** **behalten** — ist der „novel"-Rich-Text-Editor + typisierte `CollabDoc`, NICHT Entity-Builder (Agent verifiziert: `api.collab.token` hat keinen `Row`-Bezug; sonst flaggen). - **Generische Entity-Row-Public-API** (`apps/api/.../entity-row-routes.ts`): **mit β löschen** (Public-API ist eh v2). - **Formular-Eingang** (Worker `form-submission-route`, falls er generische Entity-Rows schreibt): **generischen Schreibpfad mit β entfernen, KEIN typisiertes Ziel erfinden.** Wenn dadurch der Formular-Eingang ohne Ziel dasteht → sauber deaktivieren + **CR/TODO für Raffael flaggen** („typisiertes Formular-Capture-Ziel, z.B. Lead, offen"). Pre-Launch unkritisch. - **EntitiesSingleton:** nur 12 Konsumenten (nicht 49); 8 im Builder-Kern (sterben mit β), außerhalb nur `useAppData`/`useAdminData` (drop `entities`-Feld) + Workflows (Phase A). - **entityLinks.prisma ≠ entityBuilder.prisma:** Agent prüft; `entityLinks`/`FileEntityLink` (typisierte polymorphe Links) **behalten**, nur `entityBuilder.prisma` löschen. ### Ablauf (Slices, jeder grün, Subagenten für Audits) **Phase A — Teil 2 (Branch `feat/R-P14C-teil2`):** - **A0** Modell-Registry bauen (Adapter-Interface oben) + Kontakt-Adapter registrieren. - **A1** `R-P14D`: Workflow-`row*`-Blöcke (`WorkflowBlockProService`, `WorkflowsTemplatesService`) auf Registry (Kontakt-only); `EntitiesSingleton`/`RowsApi` raus; Tests umstellen. - **A2** `R-P14F`: onboarding entity-Filter-Bedingungen + `entities`-Metadata entfernen. **Phase B — R-P6B-β (neuer Branch `feat/R-P6B-beta` auf `feat/R-P14C-teil2`):** - **B0** Audit (Subagent): exakte Lösch-/Nachzug-Liste (Inventar in `R-P6B.md` §Umfang). - **B1** EB-UI/Routen löschen: `modules/rows`, `components/entities`, `admin/entities/**`, `settings/entities/**`, `$entity.__autogenerated`/`g.$group`, `routes/admin/__workflows` (disabled), `formulas`, `codeGenerator`. - **B2** API-Layer löschen: `utils/api/.server/{Entities,Rows,Properties,RowRelationships,RowPermissions}Api`, `utils/db/entities/**`, `apps/api` entity-row-routes, Worker form-submission generischer Pfad. - **B3** `EntitiesSingleton` raus: `useAppData`/`useAdminData` `entities`-Feld droppen (Konsumenten des Feldes prüfen → es sind nur EB-UI-Teile, die in B1 weg sind). - **B4** Schema: `entityBuilder.prisma` löschen → `prisma db push` (AD-21, kein Migration-File am Branch) + `generate`; `TENANT_SCOPED_MODELS` (entityBuilder-Modelle raus) + RLS nachziehen. - **B5** Cross-Refs/Registries: `routes.ts` disabled-Patterns, `disabledPluginRouteSlugs`, Sidebar, Such-Index (`packages/search`), Permissions (`admin.formulas.*` etc.), Manifeste (`plugin-candidates.json`, `rows-entities-runtime.json`), Decision-Report-Verifier (`scripts/verify-*`), `routes.test.ts`, `admin-route-targets.test.ts` — alle nachziehen. - **B6** Voller CI-Scope grün + `prisma migrate deploy` gegen leere DB reproduzierbar (Migration entsteht beim Merge, forward-only + Inverse-SQL-Kommentar, `DO $$ … IF EXISTS … $$`-Guards). ### PR-/Merge-Strategie (3 gestapelte PRs, in Reihenfolge mergebar) 1. `R-P14C` (Teil 1, Branch `feat/R-P14C`) — liegt fertig. 2. `R-P14C-teil2` (Phase A) — auf Teil 1. 3. `R-P6B-β` (Phase B, Branch `feat/R-P6B-beta`) — auf Teil 2. Jeder Branch eigenständig grün; CI so vorbereitet, dass die drei PRs **jederzeit in dieser Reihenfolge** mergebar sind. ## Umsetzung - 2026-06-30: Teil-2-Audit + Spec-Entwürfe erstellt (Branch `feat/R-P14C-teil2`). **Kein Migrations-Code** — der typisierte Ziel-Layer ist Produkt-/Architektur-Entscheidung (Quer-Entscheidung), die vor dem Bau fallen muss. Diese Doc + die vier Child-Docs sind der ausführungsreife Ausgangspunkt. - 2026-06-30: **Konkreter Vorschlag (Option B) ergänzt** (§oben) — wachsende Modell-Registry, adressierbares Set startet mit Kontakt, formulas+codeGenerator → Cut mit β. Wartet auf Raffaels Abnahme (V1–V3d), dann ist `R-P14D` (+`R-P14F`) baubar.