CapaKraken/docs/old-markdowns/review-report-2026-03-15-computation-graph.md

Review-Report — 2026-03-15 (3D Computation Graph)

Ergebnis: ✅ Bestanden

Alle Quality Gates bestanden. Keine kritischen Probleme. Zwei Minor-Empfehlungen.

Quality Gates

Gate	Status	Details
Engine Tests	✅	283/283 (19 files)
Staffing Tests	✅	37/37 (3 files)
API Tests	✅	209/209 (21 files)
Application Tests	✅	67/67 (15 files)
TypeScript (web)	✅	0 errors (excl. BlueprintFieldEditor TS2589)
TypeScript (api)	✅	0 errors

Code-Review-Checkliste

Architektur

• Keine zirkulaeren Abhaengigkeiten — api → engine/shared/db (erlaubt)
• engine und staffing unveraendert, keine DB-Imports
• Neuer Router computationGraph in index.ts registriert
• Keine SSE-Events noetig (read-only Feature, keine Mutations)

TypeScript & Typsicherheit

• any-Types nur an react-force-graph-3d-Grenzen mit eslint-disable Kommentar (6 Stellen)
• Prisma-Enums gecastet: pa.status as unknown as string + as Parameters<typeof computeBudgetStatus>[2]
• JSONB-Feld gecastet: commercialTerms as { contingencyPercent?: number; ... } | null
• scheduleRules as SpainScheduleRule | null korrekt
• exactOptionalPropertyTypes beachtet: ...(formula ? { formula } : {}) Pattern

Datenbank & Prisma

• Keine Schema-Aenderungen — rein lesende Queries
• Geldbetraege in Integer-Cents: lcrCents, dailyCostCents, budgetCents etc.
• Kein Seed noetig (kein neues Modell)

UI & Komponenten

• "use client" Direktive gesetzt
• Three.js via dynamic(() => import(...), { ssr: false }) — kein SSR-Problem
• Neue Seite in AppShell-Navigation ergaenzt ("Computation Graph" unter Analytics)
• Opake Hintergruende: bg-zinc-50, bg-zinc-900/95 (95% ist akzeptabel fuer Tooltip)

Sicherheit

• Beide Procedures nutzen controllerProcedure (ADMIN + MANAGER + CONTROLLER)
• Keine Raw-Queries — nur Prisma findMany/findUniqueOrThrow
• Keine sensiblen Daten im Response — nur berechnete Werte und Formeln

Gefundene Probleme

Kritisch

Keine.

Minor

1. Duplizierte Types — GraphNode, GraphLink, Domain sind sowohl in packages/api/.../computation-graph.ts als auch apps/web/.../domain-colors.ts definiert. Funktioniert (tRPC inferiert die Typen), aber bei Aenderungen muss man beide Stellen anpassen. Empfehlung: Types nach @capakraken/shared verschieben wenn sie stabil sind.

2. project.list Query — Der Client castet das Ergebnis via (projectData as any)?.projects ?? (projectData as any). Das deutet auf Unsicherheit ueber das Return-Format hin. Sollte nach dem Merge geprueft werden, ob .projects oder direkt das Array zurueckkommt.

Empfehlungen

1. Bundle Size Monitoring — three und react-force-graph-3d fuegen ~700KB (gzipped) hinzu. Dank dynamic import + { ssr: false } trifft das nur die Computation Graph Seite. Trotzdem: bei der naechsten Bundle-Analyse verifizieren.

2. E2E-Test — Aktuell kein Test fuer die neue Seite. Ein Playwright-Smoke-Test (navigate to /analytics/computation-graph, expect canvas element) waere sinnvoll.

3. Link Formula Labels — Plan sah Three.js Text-Sprites auf Kanten vor (E3). Die Formeln sind in den Link-Daten vorhanden (formula Feld), werden aber aktuell nur bei Hover (indirekt ueber Node-Tooltip) sichtbar. Kann als Follow-up ergaenzt werden.

Learnings-Vorschlag fuer LEARNINGS.md

### react-force-graph-3d in Next.js 15

- Muss als `dynamic(() => import("react-force-graph-3d"), { ssr: false })` geladen werden
- React 19 Kompatibilitaet: funktioniert, aber TypeScript-Generics sind loose — `as any` Cast + eslint-disable noetig bei Callbacks (`onNodeClick`, `nodeThreeObject`, `linkColor`)
- Node-Rendering via Canvas-basierte Three.js Sprites (nicht HTML-Overlays) — performanter bei 50+ Knoten
- `warmupTicks={50}` + `cooldownTicks={0}` verhindert die Kraft-Simulation und nutzt stattdessen die fixen `fx/fy/fz` Positionen