159 lines
17 KiB
Markdown
159 lines
17 KiB
Markdown
# R-P14C-T2 · Entity-Builder-native Module typisiert ablösen (Teil 2) — Übersicht
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Typ** | Dev (Code) — **Meta/Übersicht** (verteilt auf Child-Tickets) |
|
||
| **Owner** | Raffael (+ Agent) |
|
||
| **Phase** | P6 / P14 (Entity-Builder-Ablösung, AD-2) |
|
||
| **Plane** | kein eigenes Ticket — getrackt über `R-P14C` (HIVEGRID-169) · Teil 2 von `R-P14C` (Audit 2026-07-19) |
|
||
| **Status** | **ENTSCHIEDEN (Raffael 2026-06-30, §Abnahme):** `R-P14D` (+`R-P14F`) baubar · `R-P14E`+`R-P14G` = Cut mit β |
|
||
|
||
> **Diese Datei ist die Übersicht.** Die eigentlichen Bau-Tickets sind die Child-Docs `R-P14D` (WorkflowEngine), `R-P14E` (formulas), `R-P14F` (onboarding), `R-P14G` (codeGenerator). Hier steht das gemeinsame Problem, die geteilte Vorbedingung und die zentrale offene Entscheidung, die alle vier blockiert.
|
||
|
||
## Kontext (warum dieses Ticket existiert)
|
||
`R-P14C` (Teil 1, **fertig** auf Branch `feat/R-P14C`) hat **EmailMarketing** typisiert und den `CrmService`-Legacy-Reader entfernt (Variante A — Editor entfernt, nicht migriert). Damit ist der **erste** Schritt der R-P6B-Migrationskette durch. **Teil 2** nimmt die übrigen, in R-P6B §Rückwirkungs-Audit gelisteten gebauten Entity-Builder-Konsumenten dran, damit anschließend **R-P6B-β** (`EntitiesSingleton`-Removal + `modules/rows`/`utils/db/entities` + `entityBuilder.prisma` löschen) entsperrt werden kann.
|
||
|
||
## Befund aus dem Teil-2-Audit (2026-06-30)
|
||
Anders als EmailMarketing (peripherer Konsument) sind diese vier Module **im Kern Entity-Builder-Maschinerie** — sie konsumieren den Builder nicht nur, sie operieren auf dem *generischen Entity-Begriff*:
|
||
|
||
| Modul | Was es im Kern tut | EB-Berührung (nicht-Test) | Routen-Status | Größe |
|
||
|---|---|---|---|---|
|
||
| **workflowEngine** | Pro-Blöcke `rowGet/rowCreate/rowUpdate/rowDelete` CRUDen **beliebige generische Entities** per Name (`EntitiesSingleton.getEntity` + `RowsApi`) | 2 Dateien (`WorkflowBlockProService`, `WorkflowsTemplatesService`) | Public-Slug disabled, `admin/__workflows/**` disabled, `app.$tenant/__workflows/**` registriert (nav-versteckt) | **L** |
|
||
| **formulas** | Formel-Evaluation **über Entity/Property/Row** (`RowHelper.getPropertyValue`, `getAllEntities`) | 3 Dateien (`FormulaService`, `FormulaRowService`, `FormulaVariableValueDto`) | lebt in `admin/entities/**` + `settings/entities/**` (= EB-UI, die β löscht) | **M** |
|
||
| **codeGenerator** | **generiert Code AUS Entity-Definitionen** (Prisma/DTO/Routes-Templates) — Meta-Werkzeug | 27 von 29 (Template-Input `EntityWithDetails`) | nur `admin/entities/code-generator/**` (EB-Admin) | **M** (aber Sonderfall, s.u.) |
|
||
| **onboarding** | `getAllEntities` (Onboarding-Config) + `RowsApi.count` (Filter-Vorschau) | 2 Dateien (`OnboardingService`, `OnboardingFiltersService`) | Slug disabled; `admin/onboarding/**` + public `/onboarding/$id` | **S–M** |
|
||
|
||
**Belege:** `WorkflowBlockProService.ts:7,62,99,138,182` · `FormulaService.ts:8-10,173,187` · `OnboardingService.ts:3,225` · `OnboardingFiltersService.ts` (`RowsApi.count`) · `CodeGeneratorService.ts:1` (`EntityWithDetails`). Routen-Disabled: `routes.ts` `defaultDisabledPluginRouteFilePatterns` (`admin/__workflows/**`), `PublicRouteSegments.ts` `disabledPluginRouteSlugs` (`workflow-engine`, `onboarding`).
|
||
|
||
## 🔴 Quer-Entscheidung (blockiert ALLE vier Child-Tickets)
|
||
„Typisiert neu bauen" (Richtungsentscheid Raffael, 2026-06-30) heißt für diese Module **nicht** „ein paar Imports tauschen". Es fehlt das **typisierte Ziel**, auf dem die Engines laufen sollen. Ein Workflow-`rowCreate`-Block braucht ein konkretes Ziel-Modell; eine Formel braucht typisierte Felder. Zwei Entscheidungen, die in den Specs als offen markiert sind und vor dem Bau fallen müssen:
|
||
|
||
1. **Welche typisierten Modelle sind „adressierbar"?** (Workflows + Formeln müssen wissen, auf welchen Modellen sie operieren dürfen — Kontakt, Projekt, Auftrag, … aus dem ENTITY-MODEL). Daraus folgt der gemeinsame Baustein **typisierte Modell-Registry** (§Geteilte Vorbedingung).
|
||
2. **Feld-Adressierung typisiert** — wie referenziert ein Workflow/eine Formel ein Feld eines Modells, wenn es keine generischen `Property`-Zeilen mehr gibt? (statisches Feld-Schema je Modell vs. Code-generierte Metadaten).
|
||
|
||
> Solange (1)+(2) offen sind, ist kein Child-Ticket autonom baubar — sonst würde der Agent Produkt-/Architektur-Richtung **erfinden** (AGENTS.md §Ticket-Treue: PR-Block). Die Specs liefern Optionen + Empfehlung; die Auswahl ist Raffaels Call.
|
||
|
||
## Geteilte Vorbedingung: typisierte Modell-Registry (neuer Baustein)
|
||
`EntitiesSingleton.getEntity({name})` liefert generische Entity-Metadaten (Properties als Zeilen). Der typisierte Ersatz ist eine **Modell-Registry**: `name → { read(id), create(data), update(id,data), delete(id), fieldSchema }` über die **typisierten** Prisma-Modelle (R-P6-`Kontakt` etc.). Diese Registry ist:
|
||
- die **gemeinsame** Grundlage für `R-P14D` (Workflows) **und** `R-P14E` (Formeln),
|
||
- der erste Baustein der späteren `EntitiesSingleton`-Ablösung in **R-P6B-β** (49 appweite Konsumenten) — sollte also so entworfen werden, dass β darauf aufbaut,
|
||
- **neu zu spezifizieren** (Umfang der Registry = Quer-Entscheidung 1).
|
||
|
||
Empfehlung: Registry als eigenes kleines Ticket **vor** R-P14D/E ziehen (Vorbedingung), damit beide darauf aufsetzen. (Als `R-P14D` Slice 0 oder eigenes `R-P6B-REG` — Owner-Entscheid.)
|
||
|
||
## Reihenfolge (Migrationskette, Teil 2)
|
||
1. **Quer-Entscheidung (1)+(2)** klären (Raffael) → typisierte Modell-Registry spezifizieren/bauen.
|
||
2. **R-P14E (formulas)** und **R-P14D (workflowEngine)** auf die Registry migrieren (parallelisierbar, sobald Registry steht).
|
||
3. **R-P14F (onboarding)** entkoppeln (klein, peripher, kann früh/parallel).
|
||
4. **R-P14G (codeGenerator)** Disposition entscheiden (Cut vs. Rebuild — Sonderfall, s. Doc).
|
||
5. Erst wenn Teil 1 (R-P14C) **und** Teil 2 (D/E/F/G) durch sind → **R-P6B-β** entsperrt.
|
||
|
||
## Definition of Done (dieses Übersichts-Tickets)
|
||
- [x] Teil-2-Audit durchgeführt (aktiv/dead, EB-Kopplungstiefe, Größenklassen) — siehe Tabelle oben.
|
||
- [x] Child-Specs entworfen: `R-P14D`, `R-P14E`, `R-P14F`, `R-P14G`.
|
||
- [x] Geteilte Vorbedingung (typisierte Modell-Registry) + zentrale Quer-Entscheidung benannt.
|
||
- [x] **Quer-Entscheidung (1)+(2) von Raffael getroffen** (2026-06-30): adressierbar = `Kontakt` über wachsende Registry; Feld-Adressierung über `fieldSchema`.
|
||
- [x] Child-Tickets umgesetzt (autonomer Lauf 2026-06-30): `R-P14D` (Workflows → Registry) + `R-P14F` (onboarding entkoppelt) gebaut; `R-P14E` (formulas) + `R-P14G` (codeGenerator) = **Cut mit β**. → **R-P6B-β entsperrt UND umgesetzt** (`feat/R-P6B-beta`, voller CI-Scope grün).
|
||
|
||
## Quellen
|
||
- `R-P6B.md` §Migrationskette & Ownership + §Rückwirkungs-Audit (Konsumenten-Matrix).
|
||
- `R-P14C.md` §Umsetzung (Teil 1 fertig, Variante A).
|
||
- `docs/ARCHITECTURE-DECISIONS.md` AD-2 (Entity-Builder raus, „Migration durch Neubau"), AD-20 (projekt-zentrisch), AD-21 (Prisma-Schema/Migration).
|
||
- `.planning/ENTITY-MODEL.md` (welche typisierten Modelle adressierbar sind — Quer-Entscheidung 1).
|
||
- Teil-2-Audit 2026-06-30 (Codebase-Kartierung, oben).
|
||
|
||
## 🟢 Konkreter Vorschlag zur Abnahme (2026-06-30, Option B)
|
||
Ausgearbeitet aus dem ENTITY-MODEL + Codebase-Stand. **Raffael: abnicken oder korrigieren** — danach ist der Bau entsperrt.
|
||
|
||
### Befund, der alles vereinfacht
|
||
- Die **WorkflowEngine ist bereits typisiert** (`prisma/schema/workflows.prisma`: `Workflow`/`WorkflowBlock`/`WorkflowExecution`/…). Die **einzige** Entity-Builder-Kopplung sind die `rowGet/Create/Update/Delete`-Blöcke, die auf *generische* Entities zeigen.
|
||
- Typisiert **gebaut** ist heute nur **`Kontakt`** (R-P6, `crm.prisma`) + **`Lead`** (`marketingLeads.prisma`). `Projekt`/`Rechnung`/`Termin`/`Aufgabe`/… kommen erst mit R-P7/R-P8+.
|
||
- **Formeln** stehen **nicht** als eigene v1-Entität im ENTITY-MODEL (Domäne 7 = Automation/AutomationRule; keine „Formula"). → Sie sind reine Entity-Builder-Funktion (berechnete Properties).
|
||
|
||
### Vorschlag 1 — Adressierbares Modell-Set = „was typisiert gebaut ist", über eine wachsende Registry
|
||
Nicht alle theoretischen Modelle auf einmal. Die **Modell-Registry** startet mit dem, was typisiert existiert, und wächst, wenn R-P7/R-P8+ neue Modelle bauen:
|
||
- **Jetzt adressierbar:** `Kontakt` (+ `Lead`).
|
||
- **Später (registrieren, sobald gebaut):** `Projekt`, `Rechnung`, `Termin`, `Aufgabe`, `Checkliste` … (Kern-Kette).
|
||
- Konsequenz: **R-P14D wird viel kleiner** als die Audit-Schätzung (4–6 Wo) — kein generischer Voll-Parität-Nachbau, sondern „row-Blöcke an die Registry hängen, Registry mit Kontakt seeden". Realistisch **S–M** statt L.
|
||
|
||
### Vorschlag 2 — Die typisierte Modell-Registry (geteilter Baustein)
|
||
Ein kleiner Adapter-Registry-Layer (analog zu Such-Index-/Sidebar-Registries), der `EntitiesSingleton.getEntity(name)` + `RowsApi.*` ersetzt:
|
||
|
||
```ts
|
||
// packages/… oder apps/web/app/services/typed-model-registry/
|
||
interface TypedModelAdapter<T> {
|
||
key: string; // "kontakt" — stabiler Adress-Schlüssel
|
||
label: string; // i18n-Key
|
||
read(id: string, ctx: ModelCtx): Promise<T | null>;
|
||
create(data: unknown, ctx: ModelCtx): Promise<T>;
|
||
update(id: string, data: unknown, ctx: ModelCtx): Promise<T>;
|
||
delete(id: string, ctx: ModelCtx): Promise<void>;
|
||
fieldSchema: FieldSchema; // { name, type, required, … } je Feld — ersetzt PropertyWithDetails
|
||
}
|
||
type ModelCtx = { tenantId: string | null; userId?: string };
|
||
// registry.get("kontakt") → Adapter ; alle Ops über withTenantScope()/withPermission() (M004) + Audit (M001)
|
||
```
|
||
|
||
- **Kontakt** registriert seinen Adapter aus `crm.prisma`/`utils/integrations/crm`. Neue Modelle registrieren beim Bau (R-P7+).
|
||
- Diese Registry ist **auch die Grundlage für R-P6B-β** (die ~49 appweiten `EntitiesSingleton`-Konsumenten für Entity-Metadaten migrieren später auf `fieldSchema`/Modell-Liste).
|
||
- **Empfehlung:** Registry als eigenen kleinen Vor-Slice (`R-P14D` Slice 0) bauen.
|
||
|
||
### Vorschlag 3 — Empfehlung pro Modul
|
||
| Modul | Empfehlung | Warum |
|
||
|---|---|---|
|
||
| **workflowEngine** (`R-P14D`) | **Generischer `row*`-Block über die Registry** (Modell per Parameter), adressierbares Set = registrierte Modelle (Kontakt jetzt) | Engine schon typisiert; nur 4 Blöcke umhängen; minimaler Definition-/UI-Bruch; wächst mit den Modellen |
|
||
| **formulas** (`R-P14E`) | **CUT mit β** (kein typisierter Neubau) | Keine v1-Entität im ENTITY-MODEL; reine Entity-Builder-Funktion (berechnete Properties); stirbt sauber mit dem Builder |
|
||
| **codeGenerator** (`R-P14G`) | **CUT mit β** | Meta-Werkzeug, generiert Code aus Entity-Defs; ohne Builder kein Input/Nutzen |
|
||
| **onboarding** (`R-P14F`) | **EB-Touchpoints entfernen** (nicht typisieren) | onboarding hat eigenes typ. Schema; `getAllEntities`/`RowsApi.count` sind Boilerplate-Reste, in v1 ohne Funktion |
|
||
|
||
**Netto wenn so abgenickt:** Nur **ein** echtes Bau-Ticket bleibt aktiv (`R-P14D` workflows, jetzt S–M dank Registry + kleinem Modell-Set) + die triviale onboarding-Entkopplung (`R-P14F`). `R-P14E` (formulas) + `R-P14G` (codeGenerator) werden **kein eigener Bau**, sondern wandern in `R-P6B-β`s Lösch-Scope. Das schrumpft Teil 2 drastisch.
|
||
|
||
### Abnahme (Raffael, 2026-06-30) — ✅ ENTSCHIEDEN
|
||
- [x] **V1:** Adressierbares Set startet mit **`Kontakt`** (wächst per Registry mit R-P7+). Bedingung „Kontakt nutzt den Entity-Builder nicht mehr" **bestätigt** (`utils/integrations/crm` = 0 EB-Importe, `Kontakt` echte Prisma-Tabelle). `Lead` optional mitnehmen, wenn billig.
|
||
- [x] **V2:** Modell-Registry als geteilter Baustein bauen (Adapter-Interface oben), Slice = `R-P14D` Slice 0.
|
||
- [x] **V3a:** workflows = generischer `row*`-Block über Registry, nur `Kontakt` adressierbar (vorerst). → **`R-P14D` baubar.**
|
||
- [x] **V3b:** formulas = **Cut mit β** (kein Rebuild). → `R-P14E` wird Cut-Ticket.
|
||
- [x] **V3c:** codeGenerator = **Cut mit β**. → `R-P14G` wird Cut-Ticket.
|
||
- [x] **V3d:** onboarding = **entity-basierte Filter-Bedingungen entfernen** (`entity.hasCreated`/`hasNotCreated` + `entities`-Metadata), Rest von onboarding bleibt. Diese Bedingungen sind ohne Entity-Builder bedeutungslos. → `R-P14F` (klein). *(Falls „Nutzer hat Kontakt angelegt" später als Onboarding-Bedingung gewünscht ist: neuer typisierter Filter, eigenes Mini-Ticket.)*
|
||
|
||
## 🟩 Ebene-1 Mega-Plan — entschieden 2026-06-30 (für einen autonomen Lauf)
|
||
Vollständiger, rückfragefreier Plan: Entity-Builder bis zum Ende ablösen = **Teil 2 + R-P6B-β** in *einem* autonomen Lauf.
|
||
|
||
### Gesetzte Entscheidungen (keine Rückfragen mehr nötig)
|
||
- **Daten:** keine echten Tenants (Prod existiert, aber 0 echte Tenants) → β = Tabellen **droppen**, forward-only Migration, **kein Export/keine Daten-Migration**. Größter R-P6B-Blocker entfällt.
|
||
- **Lauf-Umfang:** Teil 2 **und** β in einem Lauf (Raffael: ja).
|
||
- **Workflow-Engine:** nur **entkoppeln**; Status bleibt wie jetzt (nav-versteckt/`disabledPluginRouteSlugs`), **NICHT** für v1 freischalten.
|
||
- **Adressierbar:** nur **`Kontakt`** (Registry wächst später). `Lead` optional, wenn billig.
|
||
- **formulas + codeGenerator:** **Cut mit β** (kein Rebuild).
|
||
- **onboarding:** nur die entity-basierten Filter-Bedingungen entfernen (`entity.hasCreated`/`hasNotCreated` + `entities`-Metadata), Rest bleibt.
|
||
- **Collab/hocuspocus:** **behalten** — ist der „novel"-Rich-Text-Editor + typisierte `CollabDoc`, NICHT Entity-Builder (Agent verifiziert: `api.collab.token` hat keinen `Row`-Bezug; sonst flaggen).
|
||
- **Generische Entity-Row-Public-API** (`apps/api/.../entity-row-routes.ts`): **mit β löschen** (Public-API ist eh v2).
|
||
- **Formular-Eingang** (Worker `form-submission-route`, falls er generische Entity-Rows schreibt): **generischen Schreibpfad mit β entfernen, KEIN typisiertes Ziel erfinden.** Wenn dadurch der Formular-Eingang ohne Ziel dasteht → sauber deaktivieren + **CR/TODO für Raffael flaggen** („typisiertes Formular-Capture-Ziel, z.B. Lead, offen"). Pre-Launch unkritisch.
|
||
- **EntitiesSingleton:** nur 12 Konsumenten (nicht 49); 8 im Builder-Kern (sterben mit β), außerhalb nur `useAppData`/`useAdminData` (drop `entities`-Feld) + Workflows (Phase A).
|
||
- **entityLinks.prisma ≠ entityBuilder.prisma:** Agent prüft; `entityLinks`/`FileEntityLink` (typisierte polymorphe Links) **behalten**, nur `entityBuilder.prisma` löschen.
|
||
|
||
### Ablauf (Slices, jeder grün, Subagenten für Audits)
|
||
**Phase A — Teil 2 (Branch `feat/R-P14C-teil2`):**
|
||
- **A0** Modell-Registry bauen (Adapter-Interface oben) + Kontakt-Adapter registrieren.
|
||
- **A1** `R-P14D`: Workflow-`row*`-Blöcke (`WorkflowBlockProService`, `WorkflowsTemplatesService`) auf Registry (Kontakt-only); `EntitiesSingleton`/`RowsApi` raus; Tests umstellen.
|
||
- **A2** `R-P14F`: onboarding entity-Filter-Bedingungen + `entities`-Metadata entfernen.
|
||
|
||
**Phase B — R-P6B-β (neuer Branch `feat/R-P6B-beta` auf `feat/R-P14C-teil2`):**
|
||
- **B0** Audit (Subagent): exakte Lösch-/Nachzug-Liste (Inventar in `R-P6B.md` §Umfang).
|
||
- **B1** EB-UI/Routen löschen: `modules/rows`, `components/entities`, `admin/entities/**`, `settings/entities/**`, `$entity.__autogenerated`/`g.$group`, `routes/admin/__workflows` (disabled), `formulas`, `codeGenerator`.
|
||
- **B2** API-Layer löschen: `utils/api/.server/{Entities,Rows,Properties,RowRelationships,RowPermissions}Api`, `utils/db/entities/**`, `apps/api` entity-row-routes, Worker form-submission generischer Pfad.
|
||
- **B3** `EntitiesSingleton` raus: `useAppData`/`useAdminData` `entities`-Feld droppen (Konsumenten des Feldes prüfen → es sind nur EB-UI-Teile, die in B1 weg sind).
|
||
- **B4** Schema: `entityBuilder.prisma` löschen → `prisma db push` (AD-21, kein Migration-File am Branch) + `generate`; `TENANT_SCOPED_MODELS` (entityBuilder-Modelle raus) + RLS nachziehen.
|
||
- **B5** Cross-Refs/Registries: `routes.ts` disabled-Patterns, `disabledPluginRouteSlugs`, Sidebar, Such-Index (`packages/search`), Permissions (`admin.formulas.*` etc.), Manifeste (`plugin-candidates.json`, `rows-entities-runtime.json`), Decision-Report-Verifier (`scripts/verify-*`), `routes.test.ts`, `admin-route-targets.test.ts` — alle nachziehen.
|
||
- **B6** Voller CI-Scope grün + `prisma migrate deploy` gegen leere DB reproduzierbar (Migration entsteht beim Merge, forward-only + Inverse-SQL-Kommentar, `DO $$ … IF EXISTS … $$`-Guards).
|
||
|
||
### PR-/Merge-Strategie (3 gestapelte PRs, in Reihenfolge mergebar)
|
||
1. `R-P14C` (Teil 1, Branch `feat/R-P14C`) — liegt fertig.
|
||
2. `R-P14C-teil2` (Phase A) — auf Teil 1.
|
||
3. `R-P6B-β` (Phase B, Branch `feat/R-P6B-beta`) — auf Teil 2.
|
||
Jeder Branch eigenständig grün; CI so vorbereitet, dass die drei PRs **jederzeit in dieser Reihenfolge** mergebar sind.
|
||
|
||
## Umsetzung
|
||
- 2026-06-30: Teil-2-Audit + Spec-Entwürfe erstellt (Branch `feat/R-P14C-teil2`). **Kein Migrations-Code** — der typisierte Ziel-Layer ist Produkt-/Architektur-Entscheidung (Quer-Entscheidung), die vor dem Bau fallen muss. Diese Doc + die vier Child-Docs sind der ausführungsreife Ausgangspunkt.
|
||
- 2026-06-30: **Konkreter Vorschlag (Option B) ergänzt** (§oben) — wachsende Modell-Registry, adressierbares Set startet mit Kontakt, formulas+codeGenerator → Cut mit β. Wartet auf Raffaels Abnahme (V1–V3d), dann ist `R-P14D` (+`R-P14F`) baubar.
|