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 2 startet erst danach (Vergleich nach Umsetzung gegen Baseline).
• Phase 1 (Teil): Dashboard: kein zweites getCurrentProfile; eine listTrainingUnits-Abfrage für „Nächste Termine“ + Notiz-Pool; Playwright Test 8 in dev-smoke-test.spec.js 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 1 / 2 (Teil): Dashboard-KPIs: GET /api/dashboard/kpis (ein Roundtrip); Playwright-Test 8 angepasst.
• Phase 2 (Teil): Listen-Indizes 058 (exercises Sortierung/created_by) und 059 (training_units Kalenderliste ohne Blueprint).
• Offen Phase 1: Inbox zeitlich entkoppeln nur nach Messung (optional).

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	optional, nach Messung

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

---

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

Voraussetzung: Phase 0 abgeschlossen (BASELINE_SNAPSHOT.md). Nach Umsetzung Phase 2 p95 / Bundle mit Baseline vergleichen.

Fokus: DB und API stabil unter parallelen Lesern.

Task	Bezug
EXPLAIN + Index-Tuning für list_exercises und nächste schwere Listen	B2
Summary-API finalisieren/erweitern falls in P1 nur Teilbereich	B1
Optional: erste Keyset-Pagination für eine Liste mit bekanntem Sort-Key	B3

Teil erledigt (2026-05-14): Migration 058 (exercises: globale updated_at-Sortierung / created_by+updated_at), 059 (training_units: Kalenderliste ohne Blueprint), 060 (exercises: Partial-Indizes official/club inkl. Archiv-Filter; Junction is_primary für List-Subqueries). Rest: EXPLAIN unter Produktionsvolumen, Fähigkeits-Level-Filter nur bei Bedarf (ggf. Ausdrucks-Index).

Abnahme: p95 der optimierten Routen verbessert ggü. Phase 0 oder dokumentierte Obergrenze eingehalten.

---

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 wiederholt
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.