# Phase 8: Dashboard Widgets Vollimplementierung - Research

**Researched:** 2026-07-01
**Domain:** React Widget-Komponenten, NestJS-Modulerweiterung, Prisma-Schema, SSRF-Schutz
**Confidence:** HIGH (eigene Codebase direkt gelesen; Referenzimplementierungen vollständig verfügbar)

---

<user_constraints>
## User Constraints (from CONTEXT.md)

### Locked Decisions

**D-01 (DASH-11):** Kein universeller Einheitswert. Jedes Widget bekommt Constraints, die es bei Mindestgröße erkennbar und nutzbar halten. Claude legt konkrete Werte fest.

**D-02 (Favorites Backend):** Neue Prisma-Tabelle `FavoriteLink` mit Feldern: `id`, `userId`, `tenantId`, `widgetId`, `title`, `url`, `iconUrl`, `position`. Eigene Tabelle — sauber abfragbar und sortierbar.

**D-03 (Favorites Ansicht):** Standard-Ansicht: Liste (Icon + Titel untereinander). Grid-Ansicht (Kacheln) umschaltbar. Bei Grid-Ansicht saubere Formatierung.

**D-04 (Favorites CRUD):** Hinzufügen/Bearbeiten/Löschen direkt im Widget im Dashboard-Edit-Modus ('+'-Button + Inline-Formular). Kein separater Einstellungen-Tab.

**D-05 (Icon-Discovery):** Server-seitig beim Anlegen. NestJS fetcht Seite, parst `<link rel="apple-touch-icon">`, `<link rel="icon">`, `<link rel="shortcut icon">`, OG-Image. Fallback: `/favicon.ico`. SSRF-Schutz gegen private IPs/localhost. `iconUrl` in `FavoriteLink`. Client rendert `<img src={iconUrl}>` mit Buchstaben-Fallback.

**D-06 (Link-Widget):** Separater WidgetType `link`. Zeigt genau einen Link. Ansicht umschaltbar: Liste oder Kachel. Teilt FavoriteLink-Tabelle mit FavoritesWidget (widgetId als Zuordnung).

**D-07 (Stopwatch-Persistenz):** Startzeit (Unix-Timestamp/ISO-String) + Zustand (running/paused/elapsed) in `WidgetInstance.config`. Kein separater API-Endpunkt — `PATCH /dashboard/widgets/:id/config`.

**D-08 (Stopwatch-Funktionen):** Start, Stop/Pause, Reset. Rundenzeiten optional — Claude entscheidet.

**D-09 (Calculator):** Grundrechenarten (+, −, ×, ÷), Tastatureingabe. Kein Persist. Logik aus personal-dashboard portieren, CSS-Module durch Tailwind ersetzen.

### Claude's Discretion
- Konkrete minW/minH/defaultW/defaultH-Werte für neue Widgets
- Lap-Timer in Stoppuhr: im ersten Schritt oder später
- Reihenfolge der Kacheln im Favoriten-Grid
- Keyboard-Shortcuts im Calculator-Widget (aus personal-dashboard übernehmen)
- SSRF-Timeout und max-redirect-Werte (aus personal-dashboard: 4000ms / 2 redirects)

### Deferred Ideas (OUT OF SCOPE)
- Stoppuhr-Anzeige im Browser-Seitentitel + Taskleiste
- DomainCheck-Widget
- Lap-Timer (falls nicht in Phase 8 umgesetzt: separater Task späterer Phase)
</user_constraints>

---

<phase_requirements>
## Phase Requirements

| ID | Description | Research Support |
|----|-------------|------------------|
| DASH-08 | Taschenrechner-Widget (Grundrechenarten, Tastatureingabe) | Calculator-Logik aus personal-dashboard vollständig portierbar; keine neuen Pakete; Tailwind-Styling nach Tessera-Muster |
| DASH-09 | Favoriten-Widget mit Backend-Persistenz (Links mit Titel, URL, Icon) | FavoriteLink-Prisma-Modell definiert; NestJS FavoritesModule mit Controller/Service/DTOs; Icon-Discovery aus personal-dashboard portierbar |
| DASH-10 | Stoppuhr-Widget (Start/Stop/Reset, Rundenzeiten) | Zustand in WidgetInstance.config; bestehende updateWidgetConfig()-Funktion direkt verwendbar; kein neuer API-Endpunkt |
| DASH-11 | Alle Widgets haben einheitliche Grid-Constraints (gleiche Feldstruktur, sinnvolle Werte) | WIDGET_CONSTRAINTS-Record in widget-registry.tsx erweitern; D-01 klärt: gleiche Feldstruktur, individuelle Werte |
</phase_requirements>

---

## Summary

Phase 8 implementiert vier neue Dashboard-Widgets (Calculator, Favorites, Link, Stopwatch) und normalisiert die Grid-Constraints aller Widgets. Die Codebase ist vollständig gelesen und die Referenzimplementierungen aus dem personal-dashboard sind verfügbar.

**Keine neuen npm-Pakete erforderlich.** Alle benötigten Funktionen sind in der bestehenden Stack vorhanden: React 19 + Tailwind für die Frontend-Widgets, NestJS 11 + Prisma 6 + class-validator für das Backend, Node.js 24-Built-ins (`dns/promises`, `net`, globales `fetch`) für die SSRF-geschützte Icon-Discovery. Dies eliminiert Installations- und Kompatibilitätsrisiken.

Die größte Komplexität liegt beim Favorites-Widget: Es braucht ein neues NestJS-Modul (`FavoritesModule`), ein neues Prisma-Modell (`FavoriteLink`), serverseitiges Icon-Discovery mit SSRF-Schutz und eine zweistufige Widget-Ansicht (Liste/Grid). Der Code für alle diese Teile existiert bereits im personal-dashboard und muss nur portiert werden.

**Primary recommendation:** Sequenziell vorgehen: zuerst FavoriteLink-Schema + Prisma-Migration, dann FavoritesModule, dann die vier Widget-Komponenten (Calculator zuerst — keine Abhängigkeiten), dann widget-registry/catalog/i18n-Updates als letzter Schritt.

---

## Architectural Responsibility Map

| Capability | Primary Tier | Secondary Tier | Rationale |
|------------|-------------|----------------|-----------|
| Calculator-Logik | Browser / Client | — | Rein clientseitig; kein Persist; State in React useState |
| Stoppuhr-Logik | Browser / Client | API / Backend | Timer läuft im Browser; Startzeit wird via PATCH an Backend persistiert |
| Favoriten-CRUD UI | Browser / Client | API / Backend | UI im Widget; Daten von NestJS API |
| Icon-Discovery | API / Backend | — | Serverseitig (SSRF-Schutz); Client darf keine externen URLs direkt fetchen |
| FavoriteLink-Persistenz | Database / Storage | — | PostgreSQL via Prisma; userId+tenantId-Scope |
| Widget-Registry / Constraints | Frontend Server (SSR) | Browser / Client | widget-registry.tsx wird beim Bundling eingebunden; Typen + Constraints wirken build-time |
| i18n-Strings | Frontend Server (SSR) | — | next-intl Server Component native; Keys in messages/de.json + messages/en.json |

---

## Standard Stack

### Core (bereits installiert — keine neuen Pakete)

| Library | Version | Purpose | Relevanz für Phase 8 |
|---------|---------|---------|----------------------|
| React | 19.x | UI-Komponenten | Alle vier Widget-Komponenten |
| Next.js | 15.3.x | Framework | App Router, 'use client' Widgets |
| Tailwind CSS | 4.x | Styling | CSS-Module aus personal-dashboard durch Tailwind ersetzen |
| next-intl | 4.13.x | i18n | useTranslations() für alle Widget-Strings |
| NestJS | 11.x | API-Framework | Neues FavoritesModule |
| Prisma | 6.x | ORM | Neues FavoriteLink-Modell; db push |
| class-validator | 0.15.x | DTO-Validierung | DTOs für FavoriteLink-CRUD |

**Hinweis zur Prisma-Version:** Das Projekt nutzt Prisma 6.x (package.json: `^6.0.0`), nicht 7.x wie in der CLAUDE.md-Empfehlung. [VERIFIED: apps/api/package.json]

### Node.js Built-ins für Icon-Discovery (kein npm install nötig)

| Modul | Zweck | Node.js-Version |
|-------|-------|-----------------|
| `dns/promises` (lookup) | Hostname → IP-Auflösung für SSRF-Check | Node 18+ (Node 24 installiert) |
| `net` (isIP) | IPv4/IPv6-Erkennung | Built-in |
| `fetch` (global) | HTTP-Fetch für HTML-Parsing | Node 18+ native |

[VERIFIED: node --version = v24.16.0]

### Keine neuen Pakete — Package Legitimacy Audit entfällt

Alle benötigten Funktionen sind in bestehenden Paketen oder Node.js-Built-ins verfügbar.

---

## Package Legitimacy Audit

**Keine neuen externen Pakete für diese Phase.** [VERIFIED: Analyse aller Anforderungen — reine Portierung + bestehender Stack]

| Package | Registry | Verdict | Disposition |
|---------|----------|---------|-------------|
| (keine neuen Pakete) | — | — | — |

---

## Architecture Patterns

### System Architecture Diagram

```
Browser (React)
  ├── CalculatorWidget            → useState (in-memory, kein API-Call)
  ├── StopwatchWidget             → useState + updateWidgetConfig()
  │                                  PATCH /dashboard/widgets/:id/config
  ├── FavoritesWidget (liste/grid)→ fetch() → GET /favorites?widgetId=X
  │   + Inline-Formular (editMode)   POST/PATCH/DELETE /favorites/:id
  └── LinkWidget (1 Eintrag)      → fetch() → GET /favorites?widgetId=X (limit 1)

NestJS API
  ├── DashboardController (bestehend)
  │     PATCH /dashboard/widgets/:id/config → StopwatchWidget-Persist
  └── FavoritesController (neu)
        GET    /favorites?widgetId=         → FavoritesService.list()
        POST   /favorites                   → FavoritesService.create() + IconDiscoveryService
        PATCH  /favorites/:id               → FavoritesService.update()
        DELETE /favorites/:id              → FavoritesService.remove()
              ↓
        IconDiscoveryService (portiert aus personal-dashboard)
              ↓ DNS-Lookup → IP-SSRF-Check → fetch(url, {redirect:'manual'}) → HTML-Parse
              ↓ Fallback: /favicon.ico

PostgreSQL (Prisma)
  ├── WidgetInstance.config (JSON) ← StopwatchWidget state
  └── FavoriteLink                 ← FavoritesWidget + LinkWidget Daten
```

### Recommended Project Structure (neue Dateien)

```
apps/
├── api/
│   ├── prisma/
│   │   └── schema.prisma             UPDATE: FavoriteLink-Modell hinzufügen
│   └── src/
│       ├── app.module.ts             UPDATE: FavoritesModule importieren
│       └── favorites/                NEU
│           ├── favorites.module.ts
│           ├── favorites.controller.ts
│           ├── favorites.service.ts
│           ├── icon-discovery.service.ts  (portiert aus personal-dashboard)
│           └── dto/
│               ├── create-favorite.dto.ts
│               └── update-favorite.dto.ts
└── web/
    ├── src/
    │   ├── components/dashboard/
    │   │   ├── widget-registry.tsx   UPDATE: 4 neue Typen + Constraints + wireXWidget()
    │   │   ├── widget-catalog-modal.tsx  UPDATE: WIDGET_TYPES Array
    │   │   └── widgets/
    │   │       ├── calculator-widget.tsx  NEU
    │   │       ├── calculator-widget.test.tsx  NEU
    │   │       ├── favorites-widget.tsx   NEU
    │   │       ├── favorites-widget.test.tsx  NEU
    │   │       ├── link-widget.tsx         NEU
    │   │       ├── link-widget.test.tsx    NEU
    │   │       ├── stopwatch-widget.tsx    NEU
    │   │       └── stopwatch-widget.test.tsx  NEU
    │   ├── lib/
    │   │   └── favorites-api.ts      NEU (analog zu dashboard-api.ts)
    │   └── messages/
    │       ├── de.json               UPDATE: neue Widget-Keys
    │       └── en.json               UPDATE: neue Widget-Keys
    └── src/app/api/favorites/        OPTIONAL: Next.js API-Route als Proxy (falls nötig)
```

### Pattern 1: Neues Widget registrieren (wireXWidget-Pattern)

Jedes neue Widget muss in `widget-registry.tsx` exakt nach diesem Muster registriert werden:

```typescript
// Source: apps/web/src/components/dashboard/widget-registry.tsx (bestehend)

// 1. WidgetType-Union erweitern
export type WidgetType = 'clock' | 'search' | 'calendar' | 'note'
  | 'calculator' | 'favorites' | 'link' | 'stopwatch';

// 2. WIDGET_CONSTRAINTS eintragen
export const WIDGET_CONSTRAINTS: Record<WidgetType, { minW: number; minH: number; defaultW: number; defaultH: number }> = {
  // bestehend:
  clock:    { minW: 2, minH: 2, defaultW: 2, defaultH: 2 },
  search:   { minW: 3, minH: 2, defaultW: 6, defaultH: 2 },
  calendar: { minW: 3, minH: 3, defaultW: 4, defaultH: 6 },
  note:     { minW: 2, minH: 3, defaultW: 3, defaultH: 4 },
  // neu (Claude-Discretion D-01):
  calculator: { minW: 2, minH: 4, defaultW: 3, defaultH: 5 },
  favorites:  { minW: 2, minH: 3, defaultW: 3, defaultH: 5 },
  link:       { minW: 2, minH: 2, defaultW: 2, defaultH: 2 },
  stopwatch:  { minW: 2, minH: 2, defaultW: 3, defaultH: 3 },
};

// 3. PlaceholderWidget im WIDGET_REGISTRY eintragen
// 4. wireXWidget()-Funktion hinzufügen (analog zu wireClockWidget)
let calculatorWired = false;
export function wireCalculatorWidget(component: ComponentType<WidgetProps>) {
  if (!calculatorWired) {
    WIDGET_REGISTRY.calculator.component = component;
    calculatorWired = true;
  }
}
// ... analog für favorites, link, stopwatch
```

[VERIFIED: apps/web/src/components/dashboard/widget-registry.tsx]

### Pattern 2: Widget-Komponente (Tessera-Standard)

```typescript
// Source: apps/web/src/components/dashboard/widgets/clock-widget.tsx (bestehend)
'use client';

import type { WidgetProps } from '../widget-registry';
import { useTranslations } from 'next-intl';

export function CalculatorWidget({ instanceId, config, isEditMode }: WidgetProps) {
  // Alle Styles via Tailwind (keine CSS-Module)
  // useTranslations('widgets') für alle UI-Strings
  // updateWidgetConfig(instanceId, {...}) für Persistenz (Stopwatch)
  return (
    <div className="flex h-full flex-col ...">
      {/* Tailwind-Styling */}
    </div>
  );
}
```

[VERIFIED: apps/web/src/components/dashboard/widgets/clock-widget.tsx, note-widget.tsx]

### Pattern 3: FavoriteLink Prisma-Schema

```prisma
// Zu ergänzen in apps/api/prisma/schema.prisma
model FavoriteLink {
  id        String   @id @default(uuid())
  userId    String
  tenantId  String
  widgetId  String   // WidgetInstance.id — Zuordnung zum konkreten Widget
  title     String
  url       String
  iconUrl   String?
  position  Int      @default(0)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@index([userId])
  @@index([tenantId])
  @@index([widgetId])
}
```

[ASSUMED: Feldstruktur aus D-02 und personal-dashboard FavoriteLink-Typ ableitet; Prisma-Syntax verifiziert an bestehendem Schema]

### Pattern 4: NestJS FavoritesModule

```typescript
// apps/api/src/favorites/favorites.module.ts
import { Module } from '@nestjs/common';
import { FavoritesController } from './favorites.controller';
import { FavoritesService } from './favorites.service';
import { IconDiscoveryService } from './icon-discovery.service';

@Module({
  controllers: [FavoritesController],
  providers: [FavoritesService, IconDiscoveryService],
})
export class FavoritesModule {}

// In app.module.ts: FavoritesModule zu imports: [...] hinzufügen
// PrismaService ist global via PrismaModule — kein Re-Import nötig
```

[VERIFIED: apps/api/src/app.module.ts — PrismaModule in imports, global; MEDIUM confidence via context7-Digest]

### Pattern 5: Stoppuhr-Persistenz in WidgetInstance.config

```typescript
// Gespeichertes Config-Objekt in WidgetInstance.config (Json):
type StopwatchConfig = {
  state: 'running' | 'paused' | 'stopped';
  startedAt: string | null;  // ISO-8601-String wenn running
  elapsed: number;           // akkumulierte Zeit in ms (wenn paused/stopped)
};

// Beim Laden aus config:
const elapsed = config.state === 'running' && config.startedAt
  ? (Date.now() - new Date(config.startedAt as string).getTime()) + (config.elapsed as number ?? 0)
  : (config.elapsed as number ?? 0);

// Beim Start:
await updateWidgetConfig(instanceId, {
  state: 'running',
  startedAt: new Date().toISOString(),
  elapsed: currentElapsed,
});
```

[VERIFIED: updateWidgetConfig() in apps/web/src/lib/dashboard-api.ts — Merge-Semantik im Service bestätigt]

### Pattern 6: Calculator-Tastaturhandler

```typescript
// Portiert aus personal-dashboard/src/components/CalculatorWidget.tsx
// CSS-Module → Tailwind; CalculatorWidget() → export function CalculatorWidget({ instanceId, config, isEditMode }: WidgetProps)

function handleKeyboard(event: React.KeyboardEvent<HTMLDivElement>) {
  const key = event.key;
  const code = event.code;
  let handled = true;

  if (/^[0-9]$/.test(key)) { inputDigit(key); }
  else if (key === ',' || key === '.' || code === 'NumpadDecimal') { inputDecimal(); }
  else if (key === '+' || code === 'NumpadAdd') { chooseOperator('add'); }
  else if (key === '-' || code === 'NumpadSubtract') { chooseOperator('subtract'); }
  else if (key === '*' || code === 'NumpadMultiply') { chooseOperator('multiply'); }
  else if (key === '/' || code === 'NumpadDivide') { chooseOperator('divide'); }
  else if (key === 'Enter' || key === '=' || code === 'NumpadEnter') { applyEquals(); }
  else if (key === 'Backspace') { backspace(); }
  else if (key === 'Escape') { clearAll(); }
  else if (key === 'Delete') { clearEntry(); }
  else if (key === '%') { applyUnary('percent'); }
  else if (key === 'F9') { toggleSign(); }
  else { handled = false; }

  if (handled) {
    event.preventDefault();
    event.stopPropagation(); // Verhindert react-grid-layout Interferenz
  }
}

// Auf Container-div:
<div tabIndex={0} onKeyDown={handleKeyboard} role="application" aria-label="Taschenrechner">
```

[VERIFIED: /home/vicolab/Schreibtisch/personal-dashboard/src/components/CalculatorWidget.tsx — 434 Zeilen, vollständige Logik]

### Anti-Patterns to Avoid

- **CSS-Module verwenden:** Tessera nutzt ausschließlich Tailwind. Das personal-dashboard verwendet `CalculatorWidget.module.css` — diese Klassen müssen in Tailwind-Klassen übersetzt werden. Niemals `styles.xyz` im Tessera-Projekt.
- **Global `dns` importieren ohne `dns/promises`:** Der synchrone `dns`-Modul hat keine Promise-API. Immer `import { lookup } from 'dns/promises'` verwenden.
- **Icon-URL direkt vom Client fetchen:** Die SSRF-Schutz-Logik muss serverseitig in NestJS laufen. Der Client darf niemals direkt externe URLs für Icon-Discovery fetchen.
- **`fetch()` ohne `redirect: 'manual'`:** Automatisches Redirect-Folgen umgeht den SSRF-Check für Redirect-Ziele. Immer manuell weiterleiten und jedes Redirect-Ziel prüfen.
- **FavoriteLink ohne userId-Scope zurückgeben:** Ownership-Check (`WHERE userId = :userId`) ist Pflicht in jedem FavoritesService-Query.
- **WidgetType in CreateWidgetDto nicht aktualisieren:** `@IsIn(['clock', 'search', 'calendar', 'note'])` muss die 4 neuen Typen enthalten — sonst wirft die API 400 beim Widget-Erstellen.
- **WIDGET_TYPES-Array im Catalog-Modal nicht aktualisieren:** `widget-catalog-modal.tsx` hat ein hardcodiertes `WIDGET_TYPES`-Array — es muss ebenfalls erweitert werden.

---

## Don't Hand-Roll

| Problem | Nicht selbst bauen | Verwenden | Warum |
|---------|-------------------|-----------|-------|
| Arithmetik-Logik | Eigene Rechenfunktionen | `parseDisplay`, `formatNumber`, `calculate` aus personal-dashboard | Bewährt, edge-case-behandelt (NaN, -0, 1e15-Grenze, Dezimalkomma) |
| Icon-Discovery | Eigenen HTML-Parser | `extractIconFromHtml` + `fetchHtml` aus personal-dashboard | SSRF-Schutz, Redirect-Handling, Timeout, 200k-HTML-Limit |
| SSRF-IP-Check | Eigene Regex | `isPrivateIpv4` + `isPrivateIpv6` + `isBlockedHostname` aus personal-dashboard | RFC1918 komplett, CGNAT, IPv6-Sonderfälle |
| Widget-Config-Update | Neuen API-Endpunkt | `updateWidgetConfig()` in `dashboard-api.ts` | Bereits implementiert, PATCH /dashboard/widgets/:id/config |
| Favorites-Sortierung | Drag-Library | Native HTML5 Drag & Drop (wie in personal-dashboard) | Ausreichend für Liste; kein neues Paket nötig |

---

## Common Pitfalls

### Pitfall 1: Tastaturevents + react-grid-layout Konflikt
**What goes wrong:** Der Calculator fängt `/`-Taste ab (Divide) — react-grid-layout oder der Browser könnte ebenfalls darauf reagieren. Ohne `stopPropagation()` "bockt" die Seite oder navigiert.
**Root cause:** react-grid-layout ist ein DOM-Eventlistener; Keydown-Events bubblen nach oben.
**How to avoid:** `event.stopPropagation()` in allen handled-Fällen im `handleKeyboard`-Handler. Der Container braucht `tabIndex={0}` für Fokus.
**Warning signs:** Division-Taste öffnet browser-interne Suche; Seite scrollt beim Drücken von Pfeiltasten.

### Pitfall 2: Stoppuhr-Drift nach Seiten-Reload
**What goes wrong:** Wenn die Stoppuhr läuft und die Seite neu geladen wird, muss der gespeicherte `startedAt`-Timestamp korrekt interpretiert werden. Bei falscher Zeitzonenbehandlung läuft die Uhr falsch.
**Root cause:** `new Date(startedAt)` interpretiert ISO-8601 korrekt in UTC. `Date.now()` gibt ebenfalls UTC-Millisekunden. Die Differenz ist korrekt — solange `startedAt` als ISO-String (`new Date().toISOString()`) gespeichert wird.
**How to avoid:** Immer `new Date().toISOString()` für startedAt; `Date.now() - new Date(startedAt).getTime()` für Elapsed.
**Warning signs:** Stoppuhr springt nach Reload auf falschen Wert.

### Pitfall 3: FavoriteLink ohne widgetId-Scope
**What goes wrong:** Wenn `GET /favorites` keine `widgetId`-Filterung hat, sieht ein FavoritesWidget die Favoriten eines anderen FavoritesWidgets desselben Nutzers.
**Root cause:** Ein User kann mehrere FavoritesWidget-Instanzen auf dem Dashboard haben.
**How to avoid:** `WHERE widgetId = :widgetId` in jedem FavoritesService-Query. `widgetId` aus Query-Parameter validieren (class-validator `@IsUUID()`).
**Warning signs:** Alle Widgets zeigen dieselben Favoriten.

### Pitfall 4: Prisma-Client nach Schema-Change veraltet
**What goes wrong:** Nach `prisma db push` muss der Prisma-Client neu generiert werden (`prisma generate`). Ohne dies kennt TypeScript das neue `FavoriteLink`-Modell nicht.
**Root cause:** `prisma db push` pusht Schema zur DB, aber generiert den Client nicht automatisch (im Gegensatz zu `prisma migrate dev`).
**How to avoid:** Nach `prisma db push` immer `npx prisma generate` ausführen (oder beides via `prisma db push && prisma generate`).
**Warning signs:** TypeScript-Fehler `Property 'favoriteLink' does not exist on type 'PrismaClient'`.

### Pitfall 5: SSRF-Bypass via DNS-Rebinding
**What goes wrong:** Ein Angreifer registriert eine Domain, die zuerst auf eine öffentliche IP zeigt (SSRF-Check besteht), dann auf `192.168.x.x` rebindet.
**Root cause:** DNS-TTL-Ablauf zwischen Check und Fetch.
**How to avoid:** Die bestehende SSRF-Logik aus personal-dashboard macht den DNS-Lookup und den HTTP-Fetch in derselben Event-Loop-Iteration mit einem kurzen Timeout. Das reduziert das Fenster erheblich. Keine vollständige Immunität, aber ausreichend für diesen Use Case.
**Warning signs:** Kein direktes Warning-Zeichen — Review des SSRF-Codes beim Portieren.

### Pitfall 6: widget-catalog-modal.tsx WIDGET_TYPES Array vergessen
**What goes wrong:** Neue Widgets erscheinen nicht im Katalog, obwohl sie in der Registry registriert sind.
**Root cause:** `WIDGET_TYPES` in `widget-catalog-modal.tsx` ist ein hardcodiertes Array — kein dynamisches `Object.keys(WIDGET_REGISTRY)`.
**How to avoid:** Bei jedem neuen Widget auch `WIDGET_TYPES` in `widget-catalog-modal.tsx` erweitern.

### Pitfall 7: CreateWidgetDto @IsIn() nicht aktualisiert
**What goes wrong:** POST /dashboard/widgets mit `widgetType: 'calculator'` gibt 400 zurück.
**Root cause:** `@IsIn(['clock', 'search', 'calendar', 'note'])` in `create-widget.dto.ts` kennt die neuen Typen nicht.
**How to avoid:** `@IsIn([...alle WidgetTypes...])` aktualisieren, sobald neue Typen in `WidgetType`-Union aufgenommen werden.

---

## Grid-Constraints Entscheidung (Claude's Discretion — D-01)

Begründung der Werte basierend auf Widget-Inhalt:

| Widget | minW | minH | defaultW | defaultH | Begründung |
|--------|------|------|----------|----------|------------|
| clock (bestehend) | 2 | 2 | 2 | 2 | Einfache Zeitanzeige |
| search (bestehend) | 3 | 2 | 6 | 2 | Breite Suchleiste |
| calendar (bestehend) | 3 | 3 | 4 | 6 | Terminliste braucht Höhe |
| note (bestehend) | 2 | 3 | 3 | 4 | Textfeld braucht Mindesthöhe |
| **calculator (neu)** | **2** | **4** | **3** | **5** | 4×5 Tastenfeld + Display + Memory-Reihe; bei minH:4 sind alle Tasten bedienbar |
| **favorites (neu)** | **2** | **3** | **3** | **5** | Mindestens 2-3 Links sichtbar; defaultH:5 für komfortable Liste |
| **link (neu)** | **2** | **2** | **2** | **2** | Einzelner Link: Icon + Titel, eine Zeile reicht |
| **stopwatch (neu)** | **2** | **2** | **3** | **3** | Display + 3 Buttons; defaultW:3 für bessere Lesbarkeit |

---

## Stoppuhr: Lap-Timer Entscheidung (Claude's Discretion — D-08)

**Entscheidung: Lap-Timer in Phase 8 implementieren** — die Komplexität ist überschaubar (zusätzliches Array `laps: number[]` im Config, Button "Runde"). Wenn im ersten Plan zu aufwändig, wird es als optionaler Task am Ende des Plans eingeplant.

Config-Extension für Laps:
```typescript
type StopwatchConfig = {
  state: 'running' | 'paused' | 'stopped';
  startedAt: string | null;
  elapsed: number;
  laps: number[];  // Lap-Zeiten in ms, neueste zuerst
};
```

---

## Stopwatch Icon-Discovery: SSRF-Konfiguration (Claude's Discretion — D-05)

Werte aus personal-dashboard direkt übernehmen:
- `HTML_FETCH_TIMEOUT_MS = 4000` — ausreichend für normale Webseiten
- `MAX_REDIRECTS = 2` — verhindert Redirect-Loops
- `MAX_HTML_CHARS = 200_000` — ca. 200 KB HTML reichen für Icon-Tags im `<head>`
- User-Agent: `tessera/1.0` (statt `personal-dashboard/0.1.0`)

---

## Code Examples

### Icon-Discovery-Service (NestJS, portiert)

```typescript
// apps/api/src/favorites/icon-discovery.service.ts
// Portiert aus personal-dashboard/src/lib/favorite-icons.ts
// Änderungen: 'personal-dashboard/0.1.0' → 'tessera/1.0' im User-Agent
import { Injectable } from '@nestjs/common';
import { lookup } from 'dns/promises';
import { isIP } from 'net';

@Injectable()
export class IconDiscoveryService {
  async discoverFavoriteIconUrl(pageUrl: string): Promise<string> {
    // ... (vollständige Logik aus personal-dashboard portieren)
    // SSRF-Check → HTML-Fetch → Icon-Parse → Fallback /favicon.ico
  }
}
```

### FavoritesController (NestJS-Pattern)

```typescript
// apps/api/src/favorites/favorites.controller.ts
@Controller('favorites')
export class FavoritesController {
  constructor(private readonly favoritesService: FavoritesService) {}

  private extractContext(req: Request) {
    // Gleiche extractContext()-Logik wie DashboardController
  }

  @Get()
  async list(@Req() req: Request, @Query('widgetId') widgetId: string) {
    const { userId } = this.extractContext(req);
    return this.favoritesService.list(userId, widgetId);
  }

  @Post()
  async create(@Req() req: Request, @Body() dto: CreateFavoriteDto) { ... }

  @Patch(':id')
  async update(@Param('id') id: string, @Req() req: Request, @Body() dto: UpdateFavoriteDto) { ... }

  @Delete(':id')
  async remove(@Param('id') id: string, @Req() req: Request) { ... }
}
```

[VERIFIED: Muster aus apps/api/src/dashboard/dashboard.controller.ts]

### Favorites-API-Client (Frontend)

```typescript
// apps/web/src/lib/favorites-api.ts (analog zu dashboard-api.ts)
const API_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3001';

export async function fetchFavorites(widgetId: string) {
  const res = await fetch(`${API_URL}/favorites?widgetId=${encodeURIComponent(widgetId)}`, {
    credentials: 'include',
  });
  if (!res.ok) throw new Error('Failed to fetch favorites');
  return res.json() as Promise<FavoriteLink[]>;
}
// ... create, update, remove analog
```

[VERIFIED: Muster aus apps/web/src/lib/dashboard-api.ts]

### i18n-Keys für neue Widgets

```json
// In messages/de.json, Abschnitt "widgets", zu ergänzen:
"calculator": {
  "name": "Taschenrechner",
  "description": "Grundrechenarten mit Tastatureingabe"
},
"favorites": {
  "name": "Favoriten",
  "description": "Schnellzugriff auf Links",
  "loading": "Favoriten werden geladen...",
  "empty": "Noch keine Favoriten.",
  "addTitle": "Titel",
  "addUrl": "URL",
  "addButton": "Hinzufügen",
  "listView": "Liste",
  "gridView": "Kacheln",
  "editButton": "Favorit bearbeiten",
  "deleteButton": "Favorit loeschen",
  "saveButton": "Speichern",
  "cancelButton": "Abbrechen",
  "error": "Fehler beim Laden der Favoriten"
},
"link": {
  "name": "Link",
  "description": "Einzelner Schnellzugriff-Link"
},
"stopwatch": {
  "name": "Stoppuhr",
  "description": "Zeitmessung mit Rundenzeiten",
  "start": "Start",
  "stop": "Stop",
  "reset": "Reset",
  "lap": "Runde"
}
```

[ASSUMED: Key-Namen nach Tessera-Konvention (bestehende Keys als Vorlage); en.json analog]

---

## State of the Art

| Alter Ansatz | Aktueller Ansatz | Geaendert | Impact |
|--------------|------------------|-----------|--------|
| CSS-Module (personal-dashboard) | Tailwind (Tessera) | Phase 5 | Alle Widget-Klassen → Tailwind-Utility-Klassen |
| fetch() mit redirect:'follow' | redirect:'manual' + manuelles Folgen | SSRF-Erkenntnis | Kein SSRF-Bypass via Redirects |
| Prisma migrate dev | prisma db push | Projekt-Konvention | Schneller für iterative Entwicklung ohne Migration-History |

---

## Assumptions Log

| # | Claim | Section | Risk if Wrong |
|---|-------|---------|---------------|
| A1 | FavoriteLink-Prisma-Feldnamen (id, userId, tenantId, widgetId, title, url, iconUrl, position) entsprechen D-02 aus CONTEXT | Schema-Pattern | Geringes Risiko: D-02 nennt exakt diese Felder |
| A2 | `prisma db push` ist die bevorzugte Methode (kein `migrate dev`) | Pattern 4 | Risiko: Falls Migrations-History erwünscht ist. Bestehendes Projekt nutzt db push (Jun 29, 2026 beobachtet) |
| A3 | i18n-Key-Namen folgen dem bestehenden Muster (z.B. `calculator.name`, `favorites.loading`) | i18n-Sektion | Gering: Falsche Key-Namen führen zu fehlenden Strings, leicht korrigierbar |
| A4 | FavoritesController unter `/favorites` (nicht `/dashboard/favorites`) | Architecture | Wenn der User `/dashboard/favorites` erwartet, müssen Routen angepasst werden |
| A5 | Lap-Timer wird in Phase 8 umgesetzt (Claude's Discretion D-08) | Stopwatch-Entscheidung | Kann als optionaler Task eingeplant werden |

---

## Open Questions (RESOLVED)

1. **FavoritesController-Route: `/favorites` oder `/dashboard/favorites`?**
   - Was bekannt: DashboardController ist unter `/dashboard`; SearchProviders ebenfalls.
   - Was unklar: Ob Favorites konzeptuell zum Dashboard-Modul gehören oder ein eigenes Top-Level-Modul sind.
   - RESOLVED: `/favorites` (eigenes Modul, eigener Controller) — saubere Trennung. In Plan 08-03 umgesetzt.

2. **Braucht Next.js eine API-Route als Proxy für `/favorites`?**
   - Was bekannt: `dashboard-api.ts` ruft NestJS direkt via `NEXT_PUBLIC_API_URL` auf (mit `credentials: 'include'`). Das funktioniert für alle bestehenden Widgets.
   - Was unklar: Ob CORS-Konfiguration für `/favorites` bereits durch bestehende NestJS-CORS-Config abgedeckt ist.
   - RESOLVED: Kein Next.js API-Proxy nötig — gleiche Fetch-Pattern wie `dashboard-api.ts` verwenden. CORS durch bestehende NestJS-Config abgedeckt. In Plan 08-03 (favorites-api.ts) umgesetzt.

---

## Environment Availability

| Dependency | Required By | Available | Version | Fallback |
|------------|------------|-----------|---------|----------|
| Node.js `dns/promises` | IconDiscoveryService SSRF | ✓ | Node 24.16.0 | — |
| Node.js `net` (isIP) | IconDiscoveryService SSRF | ✓ | Built-in | — |
| Global `fetch` | IconDiscoveryService HTTP | ✓ | Node 24.16.0 | — |
| PostgreSQL | FavoriteLink-Tabelle | ✓ | 16.x (Docker) | — |
| Prisma Client | FavoritesService | ✓ | 6.x | — |

[VERIFIED: node --version = v24.16.0 auf Entwicklungsrechner]

---

## Validation Architecture

### Test Framework

| Property | Value |
|----------|-------|
| Framework | Vitest 4.1.9 + @testing-library/react 16.3.2 |
| Config file | `apps/web/vitest.config.ts` |
| Quick run command | `pnpm --filter @tessera/web test` |
| Full suite command | `pnpm --filter @tessera/web test --run` |

[VERIFIED: apps/web/vitest.config.ts, apps/web/package.json scripts]

### Phase Requirements → Test Map

| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| DASH-08 | Calculator zeigt Rechenergebnis | unit | `pnpm --filter @tessera/web test calculator-widget` | ❌ Wave 0 |
| DASH-08 | Tastatureingabe löst Ziffern/Operatoren aus | unit | `pnpm --filter @tessera/web test calculator-widget` | ❌ Wave 0 |
| DASH-09 | Favorites-Widget lädt Links aus API | unit (fetch mock) | `pnpm --filter @tessera/web test favorites-widget` | ❌ Wave 0 |
| DASH-09 | Favorit hinzufügen/bearbeiten/löschen | unit (fetch mock) | `pnpm --filter @tessera/web test favorites-widget` | ❌ Wave 0 |
| DASH-10 | Stoppuhr: Start/Stop/Reset | unit | `pnpm --filter @tessera/web test stopwatch-widget` | ❌ Wave 0 |
| DASH-10 | Stoppuhr rekonstruiert nach Reload | unit (fake timers) | `pnpm --filter @tessera/web test stopwatch-widget` | ❌ Wave 0 |
| DASH-11 | Alle Widgets haben 4 Constraint-Felder | unit | `pnpm --filter @tessera/web test widget-registry` | ❌ Wave 0 |

### Sampling Rate
- **Per task commit:** `pnpm --filter @tessera/web test --run <widget-name>`
- **Per wave merge:** `pnpm --filter @tessera/web test --run`
- **Phase gate:** Vollständige Suite grün vor `/gsd-verify-work`

### Wave 0 Gaps
- [ ] `apps/web/src/components/dashboard/widgets/calculator-widget.test.tsx` — DASH-08
- [ ] `apps/web/src/components/dashboard/widgets/favorites-widget.test.tsx` — DASH-09
- [ ] `apps/web/src/components/dashboard/widgets/link-widget.test.tsx` — DASH-09 (Link)
- [ ] `apps/web/src/components/dashboard/widgets/stopwatch-widget.test.tsx` — DASH-10

---

## Security Domain

> security_enforcement: true (aus config.json); ASVS Level 1

### Applicable ASVS Categories

| ASVS Category | Applies | Standard Control |
|---------------|---------|-----------------|
| V2 Authentication | nein | Bestehende JwtAuthGuard global |
| V3 Session Management | nein | Keine neuen Sessions |
| V4 Access Control | ja | FavoritesService: WHERE userId = :userId für alle Queries |
| V5 Input Validation | ja | class-validator DTOs (IsString, IsUrl, IsUUID); URL-Validierung in IconDiscovery |
| V6 Cryptography | nein | Keine Kryptographie |

### Known Threat Patterns

| Pattern | STRIDE | Standard Mitigation |
|---------|--------|---------------------|
| SSRF via Icon-Discovery | Elevation of Privilege | `isPrivateIpAddress` + `isBlockedHostname` + DNS-Lookup-Check aus personal-dashboard |
| Unauthorized Favorites Access | Spoofing | WHERE userId = :userId in jedem DB-Query; NotFoundException wenn nicht gefunden |
| XSS via iconUrl | Tampering | `<img src={iconUrl}>` ist sicher; kein `dangerouslySetInnerHTML`; iconUrl kommt vom Server |
| Open Redirect via URL-Feld | Spoofing | Links öffnen mit `target="_blank" rel="noreferrer"`; kein Server-Side-Redirect |
| Oversized HTML Fetch | DoS | MAX_HTML_CHARS = 200_000 (Text-Truncation); Timeout 4000ms |

---

## Sources

### Primary (HIGH confidence — direkte Codebase-Verifikation)
- `apps/web/src/components/dashboard/widget-registry.tsx` — WidgetType, WIDGET_CONSTRAINTS, wireXWidget-Pattern
- `apps/web/src/components/dashboard/widgets/clock-widget.tsx` — Referenz-Widget-Muster
- `apps/web/src/components/dashboard/widgets/note-widget.tsx` — updateWidgetConfig-Muster, Test-Mocking
- `apps/web/src/components/dashboard/widget-catalog-modal.tsx` — WIDGET_TYPES-Array-Hardcodierung
- `apps/api/src/dashboard/dashboard.controller.ts` — Controller-Pattern, extractContext
- `apps/api/src/dashboard/dashboard.service.ts` — Service-Pattern, Ownership-Check
- `apps/api/src/dashboard/dto/create-widget.dto.ts` — @IsIn()-Pattern
- `apps/api/src/app.module.ts` — AppModule-Imports-Array
- `apps/api/prisma/schema.prisma` — Bestehendes Schema, Index-Pattern
- `apps/web/src/lib/dashboard-api.ts` — updateWidgetConfig, Fetch-Pattern
- `apps/web/vitest.config.ts` — Test-Framework-Konfiguration

### Referenz-Implementierungen (HIGH confidence — direkt gelesen)
- `/home/vicolab/Schreibtisch/personal-dashboard/src/components/CalculatorWidget.tsx` — 434 Zeilen vollständige Calculator-Logik
- `/home/vicolab/Schreibtisch/personal-dashboard/src/lib/favorite-icons.ts` — 281 Zeilen SSRF-geschützte Icon-Discovery
- `/home/vicolab/Schreibtisch/personal-dashboard/src/components/FavoritesWidget.tsx` — 482 Zeilen Favorites-UI-Logik

### Secondary (MEDIUM confidence — Research-Digest)
- NestJS-Modul-Pattern (context7-Digest) — FavoritesModule-Registrierung
- Prisma db push Pattern (context7-Digest) — Schema-Sync ohne Migration

---

## Metadata

**Confidence breakdown:**
- Standard Stack: HIGH — direkte package.json-Verifikation, keine neuen Pakete
- Architecture: HIGH — vollständige Codebase-Lektüre, klare Integrationspunkte
- Widget-Constraints: MEDIUM — Claude-Discretion basierend auf Widget-Inhalt, erste Schätzung
- Pitfalls: HIGH — aus Codebase-Analyse und Referenz-Implementierungen abgeleitet
- Icon-Discovery: HIGH — vollständige Referenzimplementierung gelesen

**Research date:** 2026-07-01
**Valid until:** 2026-07-31 (stabiler Stack; keine Breaking Changes erwartet)