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

17 KiB
Raw Blame History

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)

  • Teil-2-Audit durchgeführt (aktiv/dead, EB-Kopplungstiefe, Größenklassen) — siehe Tabelle oben.
  • Child-Specs entworfen: R-P14D, R-P14E, R-P14F, R-P14G.
  • Geteilte Vorbedingung (typisierte Modell-Registry) + zentrale Quer-Entscheidung benannt.
  • Quer-Entscheidung (1)+(2) von Raffael getroffen (2026-06-30): adressierbar = Kontakt über wachsende Registry; Feld-Adressierung über fieldSchema.
  • 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:

// 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

  • 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.
  • V2: Modell-Registry als geteilter Baustein bauen (Adapter-Interface oben), Slice = R-P14D Slice 0.
  • V3a: workflows = generischer row*-Block über Registry, nur Kontakt adressierbar (vorerst). → R-P14D baubar.
  • V3b: formulas = Cut mit β (kein Rebuild). → R-P14E wird Cut-Ticket.
  • V3c: codeGenerator = Cut mit β. → R-P14G wird Cut-Ticket.
  • 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.