# R-P6B · Entity-Builder-Vollausbau (generischer Rest raus, AD-2) | | | |---|---| | **Typ** | Dev (Code) | | **Owner** | Raffael | | **Phase** | P6 — CRM-Kern (Folge von R-P6) | | **Plane** | #166 · blocked-by `R-P6` (✅ erledigt 2026-06-29) | | **Status** | **Done** — 7/7 DoD = 100 % done | ## Was wir bauen Die **vollständige Entfernung des generischen Entity-Builders** aus HiveGrid (AD-2). R-P6 (Variante A) hat den CRM-Teil bereits typisiert und den CRM-Entity-Builder-**Pfad** abgelöst. R-P6B (Variante B) entfernt den **generischen Rest**: `apps/web/app/modules/rows/**`, `apps/web/app/utils/db/entities/**`, die Entity-Builder-Settings/Admin-Routes, die autogenerierten `$entity.__autogenerated`-Routen, Row-Collab (Hocuspocus/`api.collab.token`) und schließlich das `prisma/schema/entityBuilder.prisma`-Schema. > **🔴 VERBINDLICH (2026-06-29, Raffael):** Diese Ablösung ist **Pflicht, kein „optional"** (AD-2, jetzt auch in AGENTS.md verankert). Zwei Teile: **(a) Ab sofort KEINE neuen Entity-Builder-Konsumenten** — jedes neue Modul/Feature nutzt typisierte Prisma-Tabellen (PR-Block). **(b) Die bereits gebauten Konsumenten werden rückwirkend typisiert abgelöst** — organisch, sobald das jeweilige Modul ohnehin angefasst wird (Liste in §Rückwirkungs-Audit). Raffael + Agent nehmen das Akeshan ab; Ownership-Detail offen (§Migrationskette & Ownership). ## Umfang (Inventar — aus Codebase-Analyse 2026-06-29) | Bereich | Pfad | ~Dateien | Aktion | |---|---|---|---| | Schema | `prisma/schema/entityBuilder.prisma` | 1 (21 Modelle) | löschen + Forward-Migration | | UI-Builder | `apps/web/app/modules/rows/**` | ~50 | löschen | | DB-Query-Layer | `apps/web/app/utils/db/entities/**` | ~19 | löschen | | Admin-Builder-UI | `apps/web/app/routes/admin/entities/**` | ~72 | löschen | | Tenant-Settings | `apps/web/app/routes/app.$tenant/settings/entities/**` | ~7 | löschen | | Auto-CRUD-Routen | `app.$tenant/$entity.__autogenerated/**` + `g.$group/...` | ~40 | löschen | | API-Layer | `utils/api/.server/{Entities,Rows,Properties,RowRelationships,RowPermissions}Api.ts` | 5 | löschen | | Components | `apps/web/app/components/entities/**` | ~20 | löschen | | Row-Collab | `apps/hocuspocus/**` + `routes/api.collab.token.ts` | ~13 | klären (Y.js-Collab) | | **Summe** | | **~240+** | | ## 🔴 Blocker & Abhängigkeiten (Scope-Klärung erforderlich) Der generische Entity-Builder wird **nicht nur von CRM** genutzt. Vor der Entfernung des strukturellen Kerns (`modules/rows`, `utils/db/entities`, `EntitiesSingleton`, `entityBuilder.prisma`) müssen folgende Konsumenten auf typisierte Modelle migriert werden: 1. **EmailMarketing** (ursprünglich Akeshans Track AK-P14) — nutzt `CrmService` (R-P6-Legacy: `getContact`/`getContactsInRowIds`) + `RowWithDetails`/`EntityWithDetails`. Kampagnen referenzieren contact-Row-IDs. **Harter Blocker.** Ownership der Migration in Klärung (siehe §Migrationskette & Ownership). 2. **`CrmService` (R-P6-Legacy)** — hängt direkt an `utils/db/entities` + `entityBuilder`. Entfällt erst mit (1). 3. **workflows / formulas** — `EntitiesSingleton`, `Entity`/`Property`/`FormulaLog` (Workflow-Blocks + Formula-Evaluation an Entity/Property gebunden). **Eigene Migration nötig.** 4. **`EntitiesSingleton`** — von **~49 Dateien** appweit genutzt (Entity-Metadaten/Cache: `useAppData`/`useAdminData`). Muss durch typisierte Registries je Modul ersetzt werden. 5. **Datenverlust:** `entityBuilder.prisma` enthält `Row` (= **alle** generischen Entity-Daten der Tenants) + `Property`/`EntityView`/`RowPermission`/`TenantSettingsRow` (alle tenant-scoped, in `TENANT_SCOPED_MODELS`). Schema-Löschung = **irreversibler Tenant-Datenverlust** → braucht Produkt-/Migrations-Entscheidung (welche Tenants betroffen? Vorab-Export? v2-only-Garantie?). **Konsequenz:** Solange (1)–(4) leben, kann **kein** Kern-Teil entfernt werden — auch die Admin-/Auto-Routes nicht, weil sie die noch laufenden Entities verwalten/rendern. R-P6B ist damit **derzeit nicht autonom baubar**; es ist die Spitze der Migrationskette unten. ## Migrationskette & Ownership (Stand 2026-06-29) „Die Kette" = die voneinander abhängigen Migrations-Schritte, die VOR der Kern-Entfernung (β) erledigt sein müssen. Geordnet (jeder Schritt setzt den vorigen voraus): 1. **EmailMarketing** weg von Entity-Builder-`contact`-Rows → typisiertes `Kontakt`-Modell (hält die R-P6-`CrmService`-Legacy am Leben). 2. **WorkflowEngine** weg von `EntitiesSingleton` → typisierte Registry. 3. **apps/api + apps/worker**: generische Entity-Row-Handler (`findLegacyEntityByName("contact")` etc.) typisieren. 4. **Dann β (Raffael):** `EntitiesSingleton` komplett raus → `modules/rows`/`utils/db/entities`/Admin-/Auto-Routen löschen → `entityBuilder.prisma` + Forward-Migration (+ Tenant-Daten-Entscheidung). **Ownership: GEKLÄRT (2026-06-29).** Akeshan baut **AK-P14a (#42) + AK-P14b (#43)** planmäßig auf dem bestehenden Builder fertig und **stoppt dann kurz**; **Raffael (+ Agent) übernimmt das EmailMarketing-Modul** und fährt die Migration gebündelt via **`R-P14C`** — EmailMarketing typisieren **plus** die übrigen rückwirkenden Konsumenten (WorkflowEngine, formulas, …) „im Vorhinein" mitnehmen. `R-P14C` ist **blocked-by #42/#43**. Erst danach wird **R-P6B-β** (EntitiesSingleton-Removal + Schema-Löschung) entsperrt. Akeshan wird bei Änderungen an seinen Modulen eingebunden. Solange R-P14C läuft, ruht/abgestimmt: `modules/emailMarketing`, `modules/workflowEngine`, `modules/formulas`. ## Rückwirkungs-Audit (2026-06-29) — was ist gebaut + nutzt den Builder **Ergebnis: 7 bereits gebaute Module nutzen den Entity-Builder aktiv → rückwirkend typisiert abzulösen.** Noch nicht gebaute Module werden gleich typisiert gebaut (kein Rückwirkungsbedarf). | Modul | Builder-Nutzung | Dringlichkeit | Ticket/Herkunft | |---|---|---|---| | EmailMarketing (`modules/emailMarketing`) | `CrmService.getContact`/`getContactsInRowIds` (contact-Row-IDs in Kampagnen) | **DRINGEND** (Daten wachsen, Akeshan aktiv) | AK-P14a #42 / AK-P14b #43 | | WorkflowEngine (`modules/workflowEngine`) | `EntitiesSingleton.getEntity()` (Block-Metadaten, 4 Stellen) | kritisch | Boilerplate-Bestand | | formulas (`modules/formulas`) | `EntityWithDetails`/`PropertyWithDetails`/`RowWithDetails` | kritisch | Boilerplate-Bestand | | codeGenerator (`modules/.../codeGenerator`) | `EntityWithDetails` (Template-Gen) | prüfen ob noch aktiv/nötig | Boilerplate-Bestand | | onboarding (`OnboardingService`) | `getAllEntities()` | low-prio | Boilerplate-Bestand | | `CrmService`-Legacy (`modules/crm`) | `getEntityByName`/`getRowById`/`getRowsInIds` | blockiert (hängt an EmailMarketing) | R-P6 (done) | | Entity-Builder selbst (`modules/rows`, `components/entities/**`, Auto-Routes, `*Api.server`-Layer) | — | wird gelöscht | R-P6B-β | **Nicht rückwirkend (noch nicht gebaut → von Anfang typisiert):** AK-P14b-Versand, AK-P15a/b, AK-P16c/d, AK-DEMO1, AK-P17/P19 (eigene typisierte Module, nutzen Builder ohnehin nicht). **Kritischer Pfad:** EmailMarketing + WorkflowEngine + formulas müssen typisiert sein, bevor `EntitiesSingleton` / `modules/rows` / Schema fallen können. EmailMarketing zuerst (löst die `CrmService`-Legacy ab). ## Empfohlener Scope-Split - **R-P6B-α (jetzt, nach Verifikation):** nur Teile entfernen, die nach R-P6 **nachweislich verwaist** sind (grep-belegt 0 Konsumenten). Realistisch klein, da der Builder breit genutzt wird. - **R-P6B-β (nach AK-P14 + workflows/formulas-Migration):** `EntitiesSingleton` → typisierte Registries, dann `utils/db/entities` + `modules/rows` + Admin/Auto-Routen + Schema. Mit dokumentierter Forward-Migration (Inverse-SQL) + Tenant-Daten-Entscheidung. ## Definition of Done (Voll-Scope, β eingeschlossen) - [x] EmailMarketing/CrmService-Legacy (R-P14C Teil 1) + WorkflowEngine (R-P14D) typisiert abgelöst; formulas + codeGenerator = **Cut mit β** (kein Rebuild); onboarding (R-P14F) entkoppelt. - [x] `EntitiesSingleton` entfernt: die 8 Builder-Kern-Konsumenten starben mit `modules/rows`; die bleibenden (`useAppData`/`useAdminData`/`useAppOrAdminData`) verloren das `entities`/`entityGroups`-Feld; WorkflowEngine läuft über die typisierte Modell-Registry. - [x] `modules/rows`, `utils/db/entities`, `admin/entities` (inkl. der Layout-Route `admin/entities.tsx`), `settings/entities`, `$entity.__autogenerated`, `g.$group`, Entity-API-Layer (`utils/api/.server/{Entities,Rows,Properties,Row*}Api`), `components/entities`, `modules/formulas`, `modules/codeGenerator` + die EB-Helper entfernt; `apps/api` `/v1/entities` + `/v1/relationships` + `packages/db/src/{entities,rows,relationships,settings}.server.ts` entfernt; Worker-Formular-`entity-row`-Pfad entfernt; Such-Indizes `rows`/`entities` entfernt; CRM-Such-Reindexer auf die typisierte `Kontakt`-Tabelle umgestellt. - [x] Row-Collab: `api.collab.token` generischer `row`-Resource-Type entfernt (kb-article-Collab bleibt, alles andere fail-closed); Collab-Editor/hocuspocus bleiben. (CR: s.u.) - [x] `entityBuilder.prisma` gelöscht + forward-only DROP-Migration `prisma/migrations/20260630120000_drop_entity_builder/migration.sql` mit Inverse-SQL-Kommentar vorhanden; `TENANT_SCOPED_MODELS` (8 EB-Modelle raus) + `PLATFORM_CATALOG_GLOBALS` (Entity/EntityGroup/Formula/RowComment raus) + Cross-Schema-Relationen (accounts/core/permissions) nachgezogen. - [x] Tenant-Daten-Strategie dokumentiert: **keine echten Tenants** (Prod 0 echte Tenants) → Tabellen droppen, **kein Export/keine Daten-Migration** (Entscheidung Raffael 2026-06-30). - [x] typecheck (web/worker/api/db) + lint + i18n + voller CI-Test-Scope grün; alle EB-bezogenen Tests angepasst/entfernt. ## Quellen - `R-P6.md` §Scope-Entscheidung (Abgrenzung A/B) — die R-P6B-Definition - `docs/ARCHITECTURE-DECISIONS.md` AD-2 (Entity-Builder raus), AD-20 (projekt-zentrisch) - Codebase-Analyse 2026-06-29 (Konsumenten-Matrix, oben) ## Umsetzung - 2026-06-29: Branch `feat/R-P6B` angelegt, Ticket-Doc + Konsumenten-/Blocker-Analyse erstellt. Diese Doc als eigenständiger **Doc-PR #14**. - 2026-06-29: Scope-Entscheidung (Raffael): **R-P6B-α jetzt** (nur nachweislich verwaiste Teile), struktureller Rest (β) nach AK-P14. **α umgesetzt** (Branch `feat/R-P6B-alpha`, **PR #15**): die konsumentenlosen Entity-Builder-Reader aus dem R-P6-Legacy-`CrmService` entfernt (550→185 Zeilen, grep-belegt 0 externe Konsumenten, kein Datenverlust). Voller CI-Test-Scope grün. EmailMarketing-Reader (validate/getContact/getContactsInRowIds) bleiben. - **β bleibt blockiert** (AK-P14/workflows/formulas + Tenant-Daten-Entscheidung) — kein destruktives Löschen des Kerns ohne Vorab-Migrationen + Go. - **2026-06-30: β ENTSPERRT.** Teil 1 (EmailMarketing, R-P14C) fertig; Teil 2 (workflows/onboarding) entschieden + formulas/codeGenerator = Cut mit β. **Tenant-Daten-Entscheidung gefallen:** keine echten Tenants (Prod hat 0 echte Tenants) → β = Tabellen droppen, forward-only Migration, **kein Export**. Ausführungsreifer Gesamtplan + alle gesetzten Entscheidungen: **`R-P14C-T2.md` §Ebene-1 Mega-Plan**. β läuft als 3. gestapelter PR (`feat/R-P6B-beta` auf `feat/R-P14C-teil2`). - **2026-06-30: β UMGESETZT** (autonomer Lauf, Branch `feat/R-P6B-beta`). Der generische Entity-Builder ist **vollständig entfernt**. Proof: ~370+ Dateien gelöscht; `EntitiesSingleton`/`RowsApi`/`entityBuilder.prisma` weg (grep 0 in Quell-Code, nur noch Doku-Kommentare in `services/typed-model-registry/`); `entityLinks.prisma` (typisierte polymorphe Links) bewusst behalten. **Voller damaliger CI-Scope lokal grün:** typecheck (web/worker/api/db), lint, Tests, i18n, Cross-Cutting-Modelle, Workflow-Outbox, Onboarding, Sidebar, Removed-Modules, Source-Health und CI-Baseline. *(Advisory `verify:route-inventory` war schon vor β über Budget — β hat tenant-Routen von ~125 auf 83 reduziert, weiterer Abbau = Folge-Arbeit.)* - **2026-06-30: Remote-CI grün gezogen** (3 Fix-Commits auf `feat/R-P6B-beta`, nachdem die Gitea-Actions-CI Folgefehler der EB-Entfernung zeigte, die der lokale Scope nicht abdeckte). Behoben: (a) **OpenAPI-Spec + generierter API-Client** (`apps/api/src/openapi.ts`, `packages/api-client-ts/*`) ohne die 5 `/v1/entities`+`/v1/relationships`-Pfade; **Security-Inventare** `route-access-inventory.*` + `csrf-inventory` + generierter `tenant-isolation-report` nachgezogen; EB-Contract-Tests entfernt (`permission-matrix.test` gelöscht, `openapi.test`/`app.test`/`csrf-inventory.test`/`openapi-guard.test` bereinigt). (b) **Coverage** der kritischen apps/api-Module wiederhergestellt (neuer `auth/scope.test.ts` + Fixture-Branch — die gelöschten EB-Tests deckten auch behaltene Funktionen ab; auth 99.7 %, isolation 100 %). (c) **Production-Seed** `permissions-seed.server`: `entityId:null` aus `permission.createMany` raus (mit `Permission.entityId` weg; loser Client-Typ ließ es durch den Typecheck, brach erst zur Laufzeit im Docker-Smoke). (d) **Docker-Runtime-Smokes** prüfen nicht mehr hart auf den Entity-Pfad. Zwei CI-Ausfälle waren reine Flakes/Transient (Plugin-Sandbox-Test auf T1; paralleler Docker-Build) → per Re-Run grün. Endstand: **T1, R-P14C-teil2, R-P6B-beta alle grün** in Gitea-Actions. - **Migration abgeschlossen:** Die forward-only DROP-Migration `20260630120000_drop_entity_builder` ist im Repo und enthält Guards + Inverse-SQL-Kommentar. Sie droppt die Entity-Builder-Tabellen und die entfernten FK-Spalten (`Log.rowId`, `Log.commentId`, `Permission.entityId`, `OutboundEmail.contactRowId`) reproduzierbar. - **2026-07-09 Abschluss-Check:** R-P6B auf 7/7 DoD = 100 % done nachgezogen. Proof: `rg` auf alte Builder-Symbole (`entity-row`, `RowsApi`, `EntitiesSingleton`, `/v1/entities`, `/v1/relationships`, `modules/rows`, `utils/db/entities`, `settings/entities`, `admin/entities`, `$entity.__autogenerated`) im Source-Scope leer; `crm-contact`-Formularpfad ist im Worker-Bootstrap typisiert über `prisma.kontakt.create` / Form-Actions verdrahtet; nativer Workflow-`rowGet` liest jetzt tenant-scoped aus der typisierten `Kontakt`-Tabelle statt `{ row: null }`; alte Entity-Builder-Docs-Links aus der Docs-Sidebar entfernt. Verifikation: `pnpm exec vitest run apps/worker/src/jobs/workflow-trigger-native-executor.test.ts -t "rowGet"` grün; `pnpm exec vitest run apps/worker/src/jobs/form-submission-route.test.ts apps/worker/src/jobs/form-submission-route-bootstrap.test.ts apps/worker/src/jobs/workflow-trigger-native-executor.test.ts -t "rowGet|CRM contact|crm-contact|FORM_SUBMISSION_ROUTE_QUEUE|bootstrap"` grün; `pnpm exec vitest run packages/form-widget/src/routing.extra.test.ts apps/web/app/routes.test.ts apps/worker/src/jobs/workflow-trigger-native-executor.test.ts -t "unknown-target|removed fake|rowGet"` grün; `pnpm exec vitest run apps/api/src/app.test.ts apps/api/src/openapi.test.ts apps/api/src/plugin-hook-publisher.test.ts apps/api/src/middleware/body-limit.test.ts apps/api/src/idempotency/store.test.ts` grün; `pnpm --filter @hivegrid/web typecheck`, `pnpm --filter @hivegrid/api typecheck`, `pnpm --filter @hivegrid/worker typecheck` grün.