Lars
7043addd15
- Added references to the architecture target image, refactor roadmap, and binding Shinkan rules in CLAUDE.md and HANDOVER.md for better project clarity. - Updated the Dashboard component to improve user authentication handling and optimize data loading, enhancing overall performance and user experience. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
4.9 KiB
Umsetzungsplan und Roadmap – Refaktorierung Shinkan Jinkendo
Aktueller Stand (laufend): Phase 1 begonnen – Dashboard: kein zweites getCurrentProfile, eine listTrainingUnits-Abfrage für „Nächste Termine“ und Notiz-Pool statt zweier identischer Calls.
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)
Dauer: 0,5–1 Sprint (je nach Teamgrösse).
| Task | Output |
|---|---|
API p95 der Top-5-Routen messen (z. B. profiles/me, exercises list, training-units list, media-assets list) |
Notiz in docs/architecture/ oder Verweis in HANDOVER |
| Ein Lasttestszenario (Login → Dashboard → Übungen → Planung) | Skript/Notiz + Ergebnis |
| Bundle: Grösse Einstieg + schwerste Route | Screenshot oder vite build-Logablage |
Abnahme: Zahlen dokumentiert; wiederholbar.
Phase 1 – Quick Wins Netzwerk (hoher ROI, geringes Risiko)
Fokus: Weniger redundante Requests, bessere Mobile-UX, kaum strukturelle Risiken.
| Task | Bezug Remediation |
|---|---|
Dashboard: Doppel-getCurrentProfile auflösen; kanonisches Profil klären |
A3 |
Dashboard: listTrainingUnits/listExercises-Reduktion oder erster Summary-Call |
A3, B1 |
| Org-Inbox: Ladestrategie festlegen (Technik-Kurzkonzept 1 Seite); Umsetzung mindestens Teil 1 (z. B. lazy oder TTL) | A3 |
Abnahme: Kein funktionales Leck; Netzwerk-Tab zeigt messbar weniger parallele gleiche Muster beim ersten Dashboard-Load.
Phase 2 – Backend Lesepfade (Skalierung „viele Nutzer“)
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.