15 KiB
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:
- 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). CrmService(R-P6-Legacy) — hängt direkt anutils/db/entities+entityBuilder. Entfällt erst mit (1).- workflows / formulas —
EntitiesSingleton,Entity/Property/FormulaLog(Workflow-Blocks + Formula-Evaluation an Entity/Property gebunden). Eigene Migration nötig. EntitiesSingleton— von ~49 Dateien appweit genutzt (Entity-Metadaten/Cache:useAppData/useAdminData). Muss durch typisierte Registries je Modul ersetzt werden.- Datenverlust:
entityBuilder.prismaenthältRow(= alle generischen Entity-Daten der Tenants) +Property/EntityView/RowPermission/TenantSettingsRow(alle tenant-scoped, inTENANT_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):
- EmailMarketing weg von Entity-Builder-
contact-Rows → typisiertesKontakt-Modell (hält die R-P6-CrmService-Legacy am Leben). - WorkflowEngine weg von
EntitiesSingleton→ typisierte Registry. - apps/api + apps/worker: generische Entity-Row-Handler (
findLegacyEntityByName("contact")etc.) typisieren. - Dann β (Raffael):
EntitiesSingletonkomplett 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, dannutils/db/entities+modules/rows+ Admin/Auto-Routen + Schema. Mit dokumentierter Forward-Migration (Inverse-SQL) + Tenant-Daten-Entscheidung.
Definition of Done (Voll-Scope, β eingeschlossen)
- EmailMarketing/CrmService-Legacy (R-P14C Teil 1) + WorkflowEngine (R-P14D) typisiert abgelöst; formulas + codeGenerator = Cut mit β (kein Rebuild); onboarding (R-P14F) entkoppelt.
EntitiesSingletonentfernt: die 8 Builder-Kern-Konsumenten starben mitmodules/rows; die bleibenden (useAppData/useAdminData/useAppOrAdminData) verloren dasentities/entityGroups-Feld; WorkflowEngine läuft über die typisierte Modell-Registry.modules/rows,utils/db/entities,admin/entities(inkl. der Layout-Routeadmin/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.tsentfernt; Worker-Formular-entity-row-Pfad entfernt; Such-Indizesrows/entitiesentfernt; CRM-Such-Reindexer auf die typisierteKontakt-Tabelle umgestellt.- Row-Collab:
api.collab.tokengenerischerrow-Resource-Type entfernt (kb-article-Collab bleibt, alles andere fail-closed); Collab-Editor/hocuspocus bleiben. (CR: s.u.) entityBuilder.prismagelöscht + forward-only DROP-Migrationprisma/migrations/20260630120000_drop_entity_builder/migration.sqlmit 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.- Tenant-Daten-Strategie dokumentiert: keine echten Tenants (Prod 0 echte Tenants) → Tabellen droppen, kein Export/keine Daten-Migration (Entscheidung Raffael 2026-06-30).
- 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-Definitiondocs/ARCHITECTURE-DECISIONS.mdAD-2 (Entity-Builder raus), AD-20 (projekt-zentrisch)- Codebase-Analyse 2026-06-29 (Konsumenten-Matrix, oben)
Umsetzung
- 2026-06-29: Branch
feat/R-P6Bangelegt, 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-CrmServiceentfernt (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-betaauffeat/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.prismaweg (grep 0 in Quell-Code, nur noch Doku-Kommentare inservices/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. (Advisoryverify:route-inventorywar 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-Inventareroute-access-inventory.*+csrf-inventory+ generiertertenant-isolation-reportnachgezogen; EB-Contract-Tests entfernt (permission-matrix.testgelöscht,openapi.test/app.test/csrf-inventory.test/openapi-guard.testbereinigt). (b) Coverage der kritischen apps/api-Module wiederhergestellt (neuerauth/scope.test.ts+ Fixture-Branch — die gelöschten EB-Tests deckten auch behaltene Funktionen ab; auth 99.7 %, isolation 100 %). (c) Production-Seedpermissions-seed.server:entityId:nullauspermission.createManyraus (mitPermission.entityIdweg; 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_builderist 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:
rgauf 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 überprisma.kontakt.create/ Form-Actions verdrahtet; nativer Workflow-rowGetliest jetzt tenant-scoped aus der typisiertenKontakt-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.tsgrün;pnpm --filter @hivegrid/web typecheck,pnpm --filter @hivegrid/api typecheck,pnpm --filter @hivegrid/worker typecheckgrün.