docs(08-03): complete Favorites widget plan summary
This commit is contained in:
@@ -0,0 +1,172 @@
|
||||
---
|
||||
phase: 08-dashboard-widgets-vollimplementierung
|
||||
plan: "03"
|
||||
subsystem: dashboard-widgets
|
||||
tags: [favorites, widget, tdd, dashboard, persistence, ssrf, i18n, icons]
|
||||
status: complete
|
||||
|
||||
dependency_graph:
|
||||
requires:
|
||||
- 08-01 (wireFavoritesWidget, WIDGET_CONSTRAINTS.favorites, i18n keys)
|
||||
- 08-02 (no direct dep, wave-3 parallel)
|
||||
provides:
|
||||
- FavoritesWidget component (add/edit/delete, list/grid, letter fallback)
|
||||
- FavoriteLink Prisma model (userId/tenantId/widgetId scoped)
|
||||
- FavoritesModule NestJS (CRUD + SSRF icon discovery)
|
||||
- favorites-api.ts client (fetchFavorites/createFavorite/updateFavorite/deleteFavorite)
|
||||
- wireFavoritesWidget() now connected in page.tsx
|
||||
affects:
|
||||
- apps/api/prisma/schema.prisma
|
||||
- apps/api/src/app.module.ts
|
||||
- apps/web/src/app/(portal)/page.tsx
|
||||
|
||||
tech_stack:
|
||||
added: []
|
||||
patterns:
|
||||
- TDD Red/Green cycle (FavoritesWidget behavioral contract)
|
||||
- SSRF protection ported from personal-dashboard/favorite-icons.ts
|
||||
- redirect: 'manual' with per-hop DNS check (T-08-05)
|
||||
- userId + widgetId scoping for all DB queries (T-08-06 / Pitfall 3)
|
||||
- useEffect dep array excludes t() to prevent re-fetch on each render
|
||||
- letter fallback span always in DOM (img layered on top via absolute positioning)
|
||||
|
||||
key_files:
|
||||
created:
|
||||
- apps/api/src/favorites/favorites.module.ts
|
||||
- apps/api/src/favorites/favorites.controller.ts
|
||||
- apps/api/src/favorites/favorites.service.ts
|
||||
- apps/api/src/favorites/icon-discovery.service.ts
|
||||
- apps/api/src/favorites/dto/create-favorite.dto.ts
|
||||
- apps/api/src/favorites/dto/update-favorite.dto.ts
|
||||
- apps/web/src/lib/favorites-api.ts
|
||||
- apps/web/src/components/dashboard/widgets/favorites-widget.tsx
|
||||
- apps/web/src/components/dashboard/widgets/favorites-widget.test.tsx
|
||||
modified:
|
||||
- apps/api/prisma/schema.prisma (FavoriteLink model added)
|
||||
- apps/api/src/app.module.ts (FavoritesModule registered)
|
||||
- apps/web/src/app/(portal)/page.tsx (wireFavoritesWidget added)
|
||||
|
||||
decisions:
|
||||
- "useEffect deps: [instanceId] only — t() mock creates new fn ref on each render, causing re-fetch loops in tests; excluded intentionally"
|
||||
- "dangerouslySetInnerHTML comment-only occurrences (2) are explanation comments, not actual usage — XSS threat T-08-07 mitigated"
|
||||
- "Letter fallback span always rendered (absolute positioned), img layered on top and hidden via onError — avoids flash-of-no-icon"
|
||||
- "Sync act() + waitFor() pattern in tests — async act() hangs when component uses void async handlers; waitFor polls until promise chain settles"
|
||||
|
||||
metrics:
|
||||
duration: "~25 minutes"
|
||||
completed: "2026-07-01"
|
||||
tasks_completed: 3
|
||||
tests_added: 7
|
||||
files_created: 9
|
||||
files_modified: 3
|
||||
---
|
||||
|
||||
# Phase 08 Plan 03: Favorites Widget Summary
|
||||
|
||||
Favorites-Widget Vollimplementierung (DASH-09) via TDD Red/Green-Zyklus: persistente Favoritenliste mit server-seitiger Icon-Discovery (SSRF-Schutz), Inline-CRUD im Edit-Modus, Liste/Kacheln-Ansicht und Buchstaben-Fallback.
|
||||
|
||||
## What Was Built
|
||||
|
||||
- **FavoriteLink Prisma Model**: Felder userId, tenantId, widgetId, title, url, iconUrl (nullable), position. Indizes auf userId, tenantId, widgetId (Pitfall 3 — jede Widget-Instanz hat ihre eigene Favoritenliste).
|
||||
|
||||
- **IconDiscoveryService** (`icon-discovery.service.ts`): Port aus `personal-dashboard/src/lib/favorite-icons.ts`. SSRF-Schutz: DNS-Aufloesung jeder URL und jedes Redirect-Ziels, private IPv4/IPv6-Ranges blockiert, blocked hostnames (localhost/.local/0.0.0.0), `redirect: 'manual'` mit manueller Redirect-Verfolgung bis MAX_REDIRECTS=2, 4000ms AbortController-Timeout, 200k-Zeichen HTML-Cap (T-08-05, T-08-09). User-Agent geaendert auf `tessera/1.0`.
|
||||
|
||||
- **FavoritesModule** (NestJS): FavoritesController (GET/POST/PATCH/DELETE /favorites), FavoritesService (list/create/update/remove — alle Queries scoped by userId, T-08-06), IconDiscoveryService als Provider. In AppModule registriert.
|
||||
|
||||
- **favorites-api.ts**: FavoriteLink-Typ + fetchFavorites(widgetId)/createFavorite(payload)/updateFavorite(id, payload)/deleteFavorite(id). Alle Requests mit `credentials: 'include'` und API_URL/favorites.
|
||||
|
||||
- **FavoritesWidget** (`favorites-widget.tsx`): 'use client', useTranslations. Laedt Favoriten beim Mount via fetchFavorites(instanceId). Sortierung nach position asc + title asc. Listenansicht (default) und Kachelansicht (umschaltbar im Edit-Modus, persists via updateWidgetConfig). Inline-CRUD im Edit-Modus: '+'-Formular, Bearbeiten-Inline-Form, Loeschen-Button. Icons: `<img>` mit onError-Hide + `<span data-testid="letter-fallback-{id}">` als Buchstaben-Fallback. Links: target="_blank" rel="noreferrer" (T-08-08). Kein dangerouslySetInnerHTML (T-08-07).
|
||||
|
||||
- **page.tsx Wiring**: `wireFavoritesWidget(FavoritesWidget)` hinzugefuegt.
|
||||
|
||||
## Tasks
|
||||
|
||||
| Task | Description | Status | Commit |
|
||||
|------|-------------|--------|--------|
|
||||
| 1 | RED: Failing tests fuer FavoritesWidget CRUD + view toggle + letter fallback | Complete | a3bb3f2 |
|
||||
| 2 | FavoriteLink schema + FavoritesModule (CRUD + SSRF icon discovery) | Complete | 758d246 |
|
||||
| 3 | GREEN: FavoritesWidget frontend + API client + page.tsx wiring | Complete | cc6f5ae |
|
||||
|
||||
## Test Results
|
||||
|
||||
- **favorites-widget.test.tsx**: 7 Tests — fetchFavorites mit instanceId aufgerufen, empty state, add-Formular, inline edit, delete mit DOM-Entfernung, list/grid toggle, Buchstaben-Fallback
|
||||
- **Full Web Suite**: 81/81 Tests bestehen (17 Test-Dateien)
|
||||
- **Web TypeScript**: sauber (0 Fehler)
|
||||
- **API TypeScript**: sauber (0 Fehler, prisma generate erfolgreich)
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Worktree Fast-Forward (auto-fix, Rule 3)
|
||||
|
||||
**Found during:** Pre-task setup
|
||||
|
||||
**Issue:** Das Worktree-Branch `worktree-agent-a80275c51086517d1` war bei `88db54f` (vor phase-08-Commits), nicht am erwarteten Basis-Commit `4645a5f` (Main nach Wave 2). Phase-08 wave-1 und wave-2 Artefakte (wireFavoritesWidget, WIDGET_CONSTRAINTS, i18n-Keys) fehlten.
|
||||
|
||||
**Fix:** `git merge main --ff-only` — Fast-Forward auf `4645a5f`. Keine Konflikte. Node-Modules-Symlinks danach erstellt.
|
||||
|
||||
**Impact:** Keiner. Alle Plan-01 und Plan-02-Artefakte standen danach vollstaendig zur Verfuegung.
|
||||
|
||||
### useEffect Dependency Array: t() ausgeschlossen (auto-fix, Rule 1)
|
||||
|
||||
**Found during:** Task 3 GREEN — test 'edit' scheiterte bei waitFor (saveButton nicht sichtbar)
|
||||
|
||||
**Issue:** `t()` aus `useTranslations()` war in `useEffect([instanceId, t])`-Abhaengigkeiten. Der Mock erzeugt bei jedem Render eine neue Funktionsreferenz -> useEffect feuert bei jedem State-Update neu -> `setLoading(true)` loescht die geladenen Favoriten.
|
||||
|
||||
**Fix:** Dependency-Array auf `[instanceId]` reduziert; error-Fallback nutzt stabilen String-Key statt `t()`. Kommentar erklaert Entscheidung.
|
||||
|
||||
**Files modified:** `favorites-widget.tsx` (useEffect)
|
||||
|
||||
**Commit:** cc6f5ae
|
||||
|
||||
### Testmuster: Sync act() + waitFor() statt async act() (auto-fix, Rule 1)
|
||||
|
||||
**Found during:** Task 3 GREEN — add/edit/delete Tests timeout nach 5000ms
|
||||
|
||||
**Issue:** `await act(async () => { fireEvent.click(btn); })` bei Komponenten die `void asyncHandler(e)` nutzen: act() wartet nicht auf asynchrone Fortsetzungen in `void`-discarded Promises.
|
||||
|
||||
**Fix:** Interaktions-Events mit sync `act(() => { fireEvent...; })` aufgerufen; assertions in `await waitFor(() => ...)` verschoben. waitFor pollt bis die async-Kette (API-Mock -> setState) abgeschlossen ist.
|
||||
|
||||
**Files modified:** `favorites-widget.test.tsx`
|
||||
|
||||
**Commit:** cc6f5ae
|
||||
|
||||
### dangerouslySetInnerHTML grep-count = 2 (kein Problem)
|
||||
|
||||
Beide Vorkommen sind in **Kommentaren** (Zeile 24 und 354) die erklaeren WARUM dangerouslySetInnerHTML nicht verwendet wird. Kein tatsaechlicher JSX-Attribut-Einsatz. T-08-07 korrekt mitigiert.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
Keine Stubs. FavoritesWidget ist vollstaendig implementiert und mit Backend verbunden.
|
||||
|
||||
## Threat Surface Scan
|
||||
|
||||
Alle Threats aus dem Plan-Threat-Register wurden mitigiert:
|
||||
|
||||
| Threat ID | Status |
|
||||
|-----------|--------|
|
||||
| T-08-05 (SSRF via IconDiscoveryService) | Mitigiert — vollstaendiger SSRF-Guard portiert: DNS-Check, private IPs, redirect:manual, 4000ms Timeout, 200k HTML-Cap |
|
||||
| T-08-06 (Spoofing via FavoritesService) | Mitigiert — jede Query scoped by userId + widgetId; NotFoundException bei Ownership-Mismatch |
|
||||
| T-08-07 (XSS via icon render) | Mitigiert — iconUrl nur via `<img src>`; kein dangerouslySetInnerHTML |
|
||||
| T-08-08 (open redirect) | Mitigiert — Links mit target="_blank" rel="noreferrer"; kein server-seitiger Redirect |
|
||||
| T-08-09 (DoS via HTML fetch) | Mitigiert — MAX_HTML_CHARS 200000 Truncation + 4000ms AbortController |
|
||||
|
||||
Keine neuen Sicherheitsoberflaechen eingefuehrt, die nicht im Threat-Modell erwaehnt waren.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
| Item | Status |
|
||||
|------|--------|
|
||||
| favorites-widget.tsx | FOUND |
|
||||
| favorites-widget.test.tsx | FOUND |
|
||||
| favorites-api.ts | FOUND |
|
||||
| favorites.module.ts | FOUND |
|
||||
| icon-discovery.service.ts | FOUND |
|
||||
| FavoriteLink in schema.prisma | FOUND |
|
||||
| FavoritesModule in app.module.ts | FOUND |
|
||||
| page.tsx: wireFavoritesWidget(FavoritesWidget) | FOUND |
|
||||
| Commit a3bb3f2 (RED) | FOUND |
|
||||
| Commit 758d246 (backend) | FOUND |
|
||||
| Commit cc6f5ae (GREEN) | FOUND |
|
||||
| Full suite 81/81 | PASSED |
|
||||
| Web TypeScript: 0 errors | PASSED |
|
||||
| API TypeScript: 0 errors | PASSED |
|
||||
Reference in New Issue
Block a user