Files
2026-07-08 16:15:37 +02:00

159 lines
17 KiB
Markdown
Raw Permalink 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-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** | neu · Teil 2 von `R-P14C` (#169) |
| **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.