Nexus/plan.md

Plan: Navigation Route Smoke Test (Ticket #50)

Stand: 2026-04-03

Anforderungsanalyse

Untersuchungsergebnis: Die in #50 gemeldeten 404s sind kein echter Code-Defekt.

• analytics/skills → HTTP 200 (in Docker-Logs bestätigt)
• reports/chargeability → HTTP 200 (in Docker-Logs bestätigt)
• analytics/insights → Seite existiert, wurde schlicht noch nicht kompiliert (Next.js dev kompiliert Routen on-demand beim ersten Besuch)
• Alle 35 Nav-Hrefs wurden gegen existierende page.tsx-Dateien geprüft: keine toten Links

Was gebaut wird: Ein Playwright-Smoke-Test, der bei jedem Lauf alle sichtbaren Sidebar-Destinations (navSections + adminNavEntries) für einen eingeloggten Admin-User überprüft. Verhindert, dass künftige Regressions (nav-Link zu nicht-existierender Route) erst von Usern entdeckt werden.

Betroffenes Paket: apps/web (nur Testinfrastruktur, kein Produktionscode)

---

Betroffene Pakete & Dateien

Paket	Dateien	Art der Änderung
apps/web	e2e/dev-system/nav-smoke.spec.ts	create
apps/web	e2e/navigation.spec.ts	edit — 9 bisher ungetestete Routen hinzufügen

---

Task-Liste

• Task 1: e2e/dev-system/nav-smoke.spec.ts erstellen

  Neues Spec in der dev-system-Suite (läuft gegen Live-Dev-Server auf Port 3100). Nutzt gespeicherten Auth-State (storageState: .auth/admin.json) — kein manueller Login nötig, vermeidet Rate-Limiter. Admin-User hat Zugriff auf alle Routen.

  Alle Hrefs als eigenständige Konstante definieren — NICHT AppShell importieren (würde Next.js-Infrastruktur in die Test-Runtime einziehen).

  Pro Route: page.goto(href, { waitUntil: "commit" }) + zwei Assertions:

  1. response.status() !== 404
  2. "This page could not be found" ist nicht sichtbar (max 15 s warten)

  Timeout für die Seite auf 60_000 ms setzen wegen JIT-Compile-Verzögerung bei noch nicht kompilierten Routen (z.B. analytics/insights beim ersten Besuch).

  Hrefs (Stand AppShell.tsx 2026-04-03):

  • Planning: /dashboard, /timeline, /allocations, /staffing, /notifications
  • Estimating: /estimates, /admin/rate-cards, /admin/effort-rules, /admin/experience-multipliers
  • Resources: /resources, /projects, /roles
  • Analytics: /analytics/skills, /reports/chargeability, /reports/builder, /analytics/computation-graph, /analytics/insights
  • Time Off: /vacations/my, /vacations
  • Account: /account/security
  • Admin: /admin/blueprints, /admin/clients, /admin/countries, /admin/org-units, /admin/utilization-categories, /admin/management-levels, /admin/imports, /admin/calculation-rules, /admin/vacations, /admin/users, /admin/system-roles, /admin/settings, /admin/notifications, /admin/webhooks, /admin/activity-log

  → Datei: apps/web/e2e/dev-system/nav-smoke.spec.ts

• Task 2: e2e/navigation.spec.ts erweitern

  Die bestehende navigation.spec.ts im Standard-Test-Suite prüft nur 5 Routen via Sidebar-Click. Einen separaten Test-Block "all nav routes resolve (no 404)" hinzufügen, der die restlichen regulären Routen (ohne Admin-Routen, da Role-Gate im isolierten Test-Server-Seed unbekannt) per page.goto prüft.

  Neue Routen zusätzlich zum bestehenden 5er-Set: /estimates, /roles, /analytics/skills, /reports/chargeability, /reports/builder, /analytics/computation-graph, /analytics/insights, /vacations/my, /vacations, /account/security

  Der bestehende Click-Test bleibt unverändert.

  → Datei: apps/web/e2e/navigation.spec.ts

---

Abhängigkeiten

• Task 1 und Task 2 sind vollständig unabhängig — können parallel implementiert werden.
• Task 1 setzt gespeicherte Auth-State-Dateien voraus (e2e/dev-system/.auth/admin.json). Diese existieren bereits (von vorherigen Runs). Falls nicht: playwright test --config playwright.dev.config.ts ohne Spec-Filter — global-setup läuft zuerst.

---

Akzeptanzkriterien

• pnpm --filter @nexus/web exec playwright test --config playwright.dev.config.ts e2e/dev-system/nav-smoke.spec.ts → alle 35 Tests grün gegen Live-Dev-Server auf Port 3100
• pnpm --filter @nexus/web exec playwright test e2e/navigation.spec.ts → grün im Standard-Test-Suite
• pnpm test:unit → unverändert grün (kein Produktionscode geändert)
• pnpm --filter @nexus/web exec tsc --noEmit → keine neuen Errors
• Gitea #50 mit Analyseergebnis kommentieren und schließen

---

Risiken & offene Fragen

1. Slow first-compile: analytics/insights wurde im Dev-Server noch nie kompiliert. Der erste Goto kann 10–15 s dauern (JIT + Batch-Query). Test-Timeout auf 60_000 ms setzen.

2. /vacations/my für Admin ohne Resource: Admin-User admin@planarchy.dev hat möglicherweise kein verlinktes Resource-Record. Die Seite rendert dann ein Amber-Warning-Banner — kein 404. Smoke-Test besteht trotzdem, da nur HTTP-Status und "page not found"-Text geprüft werden.

3. Role-Gates in Standard-Suite (Task 2): Der Test-Server-Seed-User admin@nexus.dev muss systemRole ADMIN haben damit Role-gated Routen erreichbar sind. Prüfen via test-server.mjs bevor Implementierung.

4. Credentials nicht mischen: navigation.spec.ts (Standard-Suite) → admin@nexus.dev. nav-smoke.spec.ts (dev-system) → admin@planarchy.dev via storageState. Nie kreuzen.