shinkan-jinkendo/docs/architecture/UMSETZUNGSPLAN_ROADMAP.md

Umsetzungsplan und Roadmap – Refaktorierung Shinkan Jinkendo

Aktueller Stand (laufend):

• Phase 0: abgeschlossen – siehe BASELINE_SNAPSHOT.md (Bundle festgehalten, API-/k6-Vorlagen + Skripte unter scripts/load/).
• Phase 1 (Teil): Dashboard: kein zweites getCurrentProfile; Trainings-Vorschau über GET /api/dashboard/kpis (training_home); Playwright Test 8 sichert API-Budget ab.
• Phase 1 (Teil): Org-Inbox: ein gemeinsamer Ladepfad fetchOrgInboxSnapshot für Mount-useEffect und refreshOrgInbox (gleiche Requests, weniger Drift-Risiko; Verhalten unverändert).
• Phase 2: abgeschlossen (2026-05-14) — Indizes 058–062, Keyset /api/exercises + /api/training-units, /api/dashboard/kpis inkl. training_home, EXPLAIN-Vorlagen scripts/load/explain-readpaths.sql.
• Offen Phase 1: Inbox optional TTL / nur bei sichtbarem Widget.
• Phase 1: verzögertes Erstlade Org-Inbox per Idle ist umgesetzt.

Ziel: Nach MVP eine nachhaltige Architektur für Wachstum, Performance (Server + schwache Clients) und sichere Feature-Erweiterung.
Leitdokumente: ZIELBILD_ARCHITEKTUR.md, SCHULDEN_UND_REMEDIATION.md, VERBINDLICHE_REGELN_SHINKAN.md.

---

Leitplanken (vereinbart)

• Kein Breaking der Zugriffsschicht: neue und geänderte Endpoints folgen get_tenant_context / Audit wie bisher.
• Inkrementell: Jede Phase liefert nutzbaren Stand (kein Big-Bang-Stillstand).
• Neue Features während der Roadmap: S8 Checkliste und S1/S3 strikt; wo möglich gleich im neuen API-Modul-Pfad.

---

Phase 0 – Baseline (kurz, Pflicht)

Status: Erledigt (2026-05-13). Siehe docs/architecture/BASELINE_SNAPSHOT.md und scripts/load/.

Task	Output
API p95 der Top-5-Routen messen (z. B. profiles/me, exercises list, training-units list, media-assets list)	Vorlage + Messverfahren in BASELINE_SNAPSHOT.md; Werte nach erstem Lauf auf Dev/Prod eintragen
Ein Lasttestszenario (Login → Dashboard → Übungen → Planung)	Playwright npm run test:e2e + k6 scripts/load/k6-health-baseline.js (README dort)
Bundle: Grösse Einstieg + schwerste Route	In BASELINE_SNAPSHOT.md dokumentiert (Auszug vite build)

Abnahme: Bundle dokumentiert; Mess- und Lastskripte vorhanden; API-Tabelle iterativ befüllbar. Phase 2 beginnt nach diesem Freeze-Punkt.

---

Phase 1 – Quick Wins Netzwerk (hoher ROI, geringes Risiko)

Fokus: Weniger redundante Requests, bessere Mobile-UX, kaum strukturelle Risiken.

Task	Bezug Remediation	Status
Dashboard: Doppel-getCurrentProfile auflösen; kanonisches Profil klären	A3	erledigt
Dashboard: listTrainingUnits-Reduktion (ein Call statt zweier identischer)	A3	erledigt
Dashboard: listExercises-Doppelabruf / Summary-Call	A3, B1	erledigt (GET /api/dashboard/kpis)
Org-Inbox: Ladestrategie; Umsetzung Teil 1 (gemeinsamer Ladepfad, keine doppelte Logik)	A3	erledigt
Org-Inbox: TTL / verzögertes Laden (nur nach Bedarf)	A3	teils (Erstlade per requestIdleCallback, max. 1,5s)

Abnahme: Kein funktionales Leck; Netzwerk-Tab zeigt messbar weniger parallele gleiche Muster beim ersten Dashboard-Load.

---

Phase 2 – Backend Lesepfade (Skalierung „viele Nutzer“)

Status: Abgeschlossen (2026-05-14).

Voraussetzung: Phase 0 abgeschlossen (BASELINE_SNAPSHOT.md). Nach Deploy: p95 der Top-Routen erneut messen und mit Baseline vergleichen (M2).

Fokus: DB und API stabil unter parallelen Lesern.

Task	Bezug	Status
EXPLAIN + Index-Tuning für list_exercises und nächste schwere Listen	B2	erledigt (Indizes 058–060, 062; Vorlagen explain-readpaths.sql; Messung Team)
Summary-API finalisieren/erweitern falls in P1 nur Teilbereich	B1	erledigt (GET /api/dashboard/kpis + training_home)
Keyset-Pagination für Listen mit Sort-Key	B3	erledigt (/api/exercises, /api/training-units)

Lieferung: Migrationen 058–062; Keyset-Parameter wie dokumentiert in OpenAPI/Router; Dashboard nutzt ein KPI-Request für Kennzahlen und Trainings-Vorschau.

Abnahme: p95 der optimierten Routen nach Messung dokumentiert verbessert ggü. Phase 0 oder Obergrenze notiert (siehe Baseline-Tabelle).

---

Phase 3 – Frontend-Struktur (Wartbarkeit + Client-Performance)

Fokus: God-Pages abbauen, Virtualisierung wo nötig.

Task	Bezug
Eine Page komplett zerteilen als Referenz (z. B. TrainingPlanningPage oder ExerciseFormPage) – Rest priorisiert nach Nutzung	A1
Virtualisierung für die längste produktive Liste	A1, S2
Schwere Imports auf import() umziehen (gezielt)	A4

Abnahme: Referenz-Page unter Soft-Limit; Regel S1 für neue Änderungen durchsetzbar.

---

Phase 4 – API-Client Modularisierung

Fokus: Wartbarkeit für viele neue Features.

Task	Bezug
frontend/src/api/ anlegen, request/client zentral	A2
Facade: bestehende Importe von utils/api nicht sofort alle brechen; Migration in Wellen	A2
Neue Endpoints nur noch in Domänen-Dateien	S3

Abnahme: Anteil neuer Module > X% der neuen Zeilen (Team-Ziel); Monolith wächst nicht weiter.

---

Phase 5 – Vertiefung DB & Pagination

Fokus: Wachstum Datenbestand.

Task	Bezug
Keyset für weitere Listen	B3
Weitere Query-Refactorings nach Monitoring	B2

Abnahme: Dokumentierte Paginierungs-API; keine Regression in der Zugriffsschicht.

---

Meilensteine (empfohlen)

Meilenstein	Inhalt
M1	Phase 0 + 1 abgeschlossen, HANDOVER aktualisiert
M2	Phase 2 abgeschlossen, Lasttest / p95 nachziehen
M3	Phase 3 Referenz-Page + Virtualisierung live
M4	Phase 4 migrationsbereit für alle neuen Features
M5	Phase 5 für Top-Listen abgeschlossen

---

Parallel: neue Features

• Jedes Feature: VERBINDLICHE_REGELN_SHINKAN.md S8.
• Berührung schwerer Pfade: kurzer Performance-Nachweis (S7).

---

Risiken und Mitigation

Risiko	Mitigation
Summary-Endpoint falsch gefiltert	Code-Review + Abgleich mit Einzel-Endpoint-Logik; Tests mit mehreren Rollen
Refaktor bricht PWA/Offline	Smoke-Test nach grossen Frontend-Phasen
Keyset bricht alte Clients	Versionierte Query-Parameter oder Übergangsfenster

---

Pflege

Nach jeder Phase: README dieses Bündels prüfen; Roadmap Checkboxen/Status; HANDOVER nächste Phase nennen.