Lars
4b2848c7c3
- Introduced a new section for the Performance-Baseline in CLAUDE.md and updated HANDOVER.md to include references to the new BASELINE_SNAPSHOT.md. - Enhanced architecture documentation in README.md to clarify the purpose of the baseline snapshot and its relevance to the refactor roadmap. - Refactored OrgInboxContext to implement a unified loading logic for join requests and content reports, improving code maintainability and performance. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
6.2 KiB
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; einelistTrainingUnits-Abfrage für „Nächste Termine“ + Notiz-Pool; Playwright Test 8 indev-smoke-test.spec.jssichert API-Budget ab. - Phase 1 (Teil): Org-Inbox: ein gemeinsamer Ladepfad
fetchOrgInboxSnapshotfür Mount-useEffectundrefreshOrgInbox(gleiche Requests, weniger Drift-Risiko; Verhalten unverändert). - Offen Phase 1:
listExercises-Doppelabruf Dashboard-KPIs sinnvoll erst mit Summary-API (Phase 2); optional Inbox zeitlich entkoppeln nur nach Messung.
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 | Phase 2 (Backend-Summary) |
| 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 |
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.