Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -0,0 +1,98 @@
# 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)
- [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.)
- [~] `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).
- [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 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.