17 KiB
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:
- 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).
- 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) undR-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)
- Quer-Entscheidung (1)+(2) klären (Raffael) → typisierte Modell-Registry spezifizieren/bauen.
- R-P14E (formulas) und R-P14D (workflowEngine) auf die Registry migrieren (parallelisierbar, sobald Registry steht).
- R-P14F (onboarding) entkoppeln (klein, peripher, kann früh/parallel).
- R-P14G (codeGenerator) Disposition entscheiden (Cut vs. Rebuild — Sonderfall, s. Doc).
- 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 überfieldSchema. - 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.mdAD-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 dierowGet/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 auffieldSchema/Modell-Liste). - Empfehlung: Registry als eigenen kleinen Vor-Slice (
R-P14DSlice 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,Kontaktechte Prisma-Tabelle).Leadoptional mitnehmen, wenn billig. - V2: Modell-Registry als geteilter Baustein bauen (Adapter-Interface oben), Slice =
R-P14DSlice 0. - V3a: workflows = generischer
row*-Block über Registry, nurKontaktadressierbar (vorerst). →R-P14Dbaubar. - V3b: formulas = Cut mit β (kein Rebuild). →
R-P14Ewird Cut-Ticket. - V3c: codeGenerator = Cut mit β. →
R-P14Gwird 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).Leadoptional, 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.tokenhat keinenRow-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(dropentities-Feld) + Workflows (Phase A). - entityLinks.prisma ≠ entityBuilder.prisma: Agent prüft;
entityLinks/FileEntityLink(typisierte polymorphe Links) behalten, nurentityBuilder.prismalö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/RowsApiraus; 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/apientity-row-routes, Worker form-submission generischer Pfad. - B3
EntitiesSingletonraus:useAppData/useAdminDataentities-Feld droppen (Konsumenten des Feldes prüfen → es sind nur EB-UI-Teile, die in B1 weg sind). - B4 Schema:
entityBuilder.prismalö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.tsdisabled-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 deploygegen 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)
R-P14C(Teil 1, Branchfeat/R-P14C) — liegt fertig.R-P14C-teil2(Phase A) — auf Teil 1.R-P6B-β(Phase B, Branchfeat/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.