# 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
- [x] Keine zirkulaeren Abhaengigkeiten — `api → engine/shared/db` (erlaubt)
- [x] `engine` und `staffing` unveraendert, keine DB-Imports
- [x] Neuer Router `computationGraph` in `index.ts` registriert
- [x] Keine SSE-Events noetig (read-only Feature, keine Mutations)

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

### Datenbank & Prisma
- [x] Keine Schema-Aenderungen — rein lesende Queries
- [x] Geldbetraege in Integer-Cents: `lcrCents`, `dailyCostCents`, `budgetCents` etc.
- [x] Kein Seed noetig (kein neues Modell)

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

### Sicherheit
- [x] Beide Procedures nutzen `controllerProcedure` (ADMIN + MANAGER + CONTROLLER)
- [x] Keine Raw-Queries — nur Prisma `findMany`/`findUniqueOrThrow`
- [x] 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

```markdown
### 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
```