Lars/shinkan-jinkendo
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 3 Wiki Activity
a19ed02300
shinkan-jinkendo/docs/architecture/UMSETZUNGSPLAN_ROADMAP.md
Lars 76cc81a385
All checks were successful
Deploy Development / deploy (push) Successful in 42s
Details
Test Suite / pytest-backend (push) Successful in 37s
Details
Test Suite / lint-backend (push) Successful in 0s
Details
Test Suite / build-frontend (push) Successful in 20s
Details
Test Suite / k6 /health Baseline (push) Successful in 33s
Details
Test Suite / playwright-tests (push) Successful in 1m8s
Details
Update project documentation and enhance training features for parallel streams 
- Updated CLAUDE.md and PROJECT_STATUS.md to reflect the latest app version (0.8.140) and database schema (20260515063) as of 2026-05-14.
- Enhanced DOMAIN_MODEL.md and PARALLEL_TRAINING_STREAMS_CONCEPT.md to clarify the implementation of phases and parallel streams in training units.
- Improved HANDOVER.md with detailed descriptions of the coaching and breakout functionalities, including rejoin logic and session management.
- Updated FACHLICHE_NUTZERFUNKTIONEN.md to include new features related to training planning and execution, emphasizing the integration of phases and parallel streams.
- Revised FEATURES_DELIVERED_2026-Q2.md to document the latest changes and improvements in the training framework and media management.
2026-05-15 22:11:05 +02:00

8.7 KiB
Raw Blame History

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 3 (abgeschlossen 2026-05-14): Übungsliste modularisiert; Trainingsplanung/Übungsformular: Page-Dateien unter Soft-Limit — Implementierung in TrainingPlanningPageRoot.jsx, ExerciseFormPageRoot.jsx, ExercisesListPageRoot.jsx; pages/*.jsx nur Re-Export. Playwright Tests 9–10.
  • Phase 4 (fortlaufend 2026-05-14): API Welle 1 client.js; Welle 2 planning.js; Welle 3 exercises.js; utils/api.js bleibt Facade (export *, api-Objekt ...exercises, ...planning).
  • Trainingsplan Breakout / Coach (2026-05-14): Phasen + parallele Streams (063, Frontend 0.8.137–0.8.140), Coach-Rejoin und Nachbereitung — siehe docs/HANDOVER.md, technical/PARALLEL_TRAINING_STREAMS_SPEC.md.

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

Teil umgesetzt (2026-05-13): ExercisesListPage — Karten ExerciseListCard.jsx; Filter/Massenänderung ExerciseListFilterModal.jsx / ExerciseListBulkModal.jsx; Tab „Progressionsgraphen“ lazy; Picker virtualisiert; Gitter data-testid + content-visibility; Playwright Tests 9–10.

Abgeschlossen (2026-05-14): Routen bleiben unter frontend/src/pages/; schwere Implementierung in components/planning/TrainingPlanningPageRoot.jsx, components/exercises/ExerciseFormPageRoot.jsx, components/exercises/ExercisesListPageRoot.jsx — pages/* nur Re-Export (Soft-Limit ~500 Zeilen laut VERBINDLICHE_REGELN_SHINKAN.md).

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

Phase 4 – API-Client Modularisierung

Status: fortlaufend (2026-05-14) — Welle 1: client.js; Welle 2: planning.js; Welle 3: exercises.js; utils/api.js bleibt vollständige Facade.

Fokus: Wartbarkeit für viele neue Features.

Task Bezug Status
frontend/src/api/client.js — zentraler HTTP-Client A2 erledigt (Welle 1)
frontend/src/api/planning.js — Trainingsplanung (Einheiten, Vorlagen, Module, Rahmen, Dashboard-KPIs) A2 erledigt (Welle 2)
frontend/src/api/exercises.js — Übungen, Medien/Archiv, Varianten, Progressionsgraphen, KI A2 erledigt (Welle 3)
Weitere Domänen-Module unter frontend/src/api/ + Entlastung von utils/api.js A2 offen
Neue Endpoints primär in Domänen-Dateien S3 offen

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 abgeschlossen: Page-Dateien Soft-Limit (Re-Export); Virtualisierung Übungsliste
M4 Phase 4 migrationsbereit für alle neuen Features
M5 Phase 5 für Top-Listen abgeschlossen

Parallel: neue Features

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.