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

15 KiB
Raw Blame History

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 geplant — Scope-Klärung offen (siehe §Blocker)

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)

  • EmailMarketing/CrmService-Legacy (R-P14C Teil 1) + WorkflowEngine (R-P14D) typisiert abgelöst; formulas + codeGenerator = Cut mit β (kein Rebuild); onboarding (R-P14F) entkoppelt.
  • 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.
  • 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.
  • 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.)
  • [~] entityBuilder.prisma gelöscht + prisma db push (AD-21: kein Migrations-File am Branch); TENANT_SCOPED_MODELS (8 EB-Modelle raus) + PLATFORM_CATALOG_GLOBALS (Entity/EntityGroup/Formula/RowComment raus) + Cross-Schema-Relationen (accounts/core/permissions) nachgezogen. Offen: forward-only DROP-Migration beim Merge (s. §Umsetzung).
  • 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-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 CI-Scope lokal grün: typecheck (web/worker/api/db), lint, test:foundation/packages/mobile, Core-Test (3500 grün), verify:i18n, verify:cross-cutting-models (104/104 tenantId-Modelle, 8 EB-Modelle raus), verify:workflow-outbox-native (282), verify:onboarding-flow, verify:sidebar-routes, verify:feature-manifest-baseline, verify:removed-modules, verify:source-health, verify:ci-baseline. (Advisory verify:route-inventory ist NICHT im CI-Gate und 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 (AD-21): Am Branch nur prisma db push (kein Migrations-File). Die forward-only DROP-Migration entsteht beim Merge nach main — sie muss alle entityBuilder.prisma-Tabellen droppen (DO $IF EXISTS$-Guards) und die mit-entfernten Spalten/Relationen: Log.rowId/Log.commentId (+ FKs Log.row/Log.comment), Permission.entityId (+ FK), ApiKey↔ApiKeyEntity, sowie die Rück-Relationen auf User/Tenant/Role/Group. Inverse-SQL als Kommentar (DoD 28), reproduzierbar gegen leere DB (CI migrate deploy).
  • Offene CR-Flags (M176-Doc fehlt noch → hier vermerkt):
    1. Collab generischer row-Resource-Type entfernt (api.collab.token): Echtzeit-Collab für generische Rows weg; kb-article bleibt. Falls Collab auf typisierten Datensätzen gewünscht → typisierter resource-type-Zweig (neues Ticket).
    2. Formular-Eingang entity-row-Ziel entfernt (Worker): generic (nur speichern) + crm-contact bleiben als Ziele. packages/form-widget SubmissionTargetType listet entity-row noch (Worker lehnt es ab) → Follow-up: aus dem Enum entfernen.
    3. REGRESSION (Pre-Launch unkritisch): Formular-Ziel crm-contact im Worker nicht mehr verdrahtet (MISSING_CRM_ADAPTER). Der bisherige CRM-Creator war EB-basiert; es gibt keinen typisierten Kontakt-Creator in einem worker-erreichbaren Paket. Handler-Zweig existiert, ist aber unverdrahtet → crm-contact-Submissions schlügen zur Laufzeit fehl, bis ein typisierter Kontakt-Creator (packages/db oder shared) ergänzt wird.
    4. Workflow rowGet-Block = No-op (workflow-trigger-native-executor): liefert {row:null}; rowGet bleibt unterstützter Block-Typ (Guard-Test grün), row-getriggerte Workflows bekommen aber null bis ein typisierter Ersatz verdrahtet ist.