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

96 lines
15 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-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.