Lars
dd0fae4bf5
Some checks failed
Deploy Development / deploy (push) Successful in 49s
Test Suite / pytest-backend (push) Failing after 43s
Test Suite / lint-backend (push) Successful in 0s
Test Suite / build-frontend (push) Successful in 15s
Test Suite / k6 /health Baseline (push) Successful in 44s
Test Suite / playwright-tests (push) Successful in 1m15s
- Introduced a roadmap-first approach for the planning AI, allowing for a structured progression graph that aligns with the overall project roadmap. - Added new functionality to strip off-topic steps from exercise paths, improving the relevance of generated exercise suggestions. - Implemented a detailed goal text generation for AI proposals, enhancing the context provided for new exercises. - Updated the ExerciseProgressionPathBuilder component to support new features, including roadmap previews and improved focus area handling. - Incremented application version to 0.8.205 and updated database schema version to 20260606086 to reflect these changes.
160 lines
8.9 KiB
Markdown
160 lines
8.9 KiB
Markdown
# Umsetzungsplan und Roadmap – Refaktorierung Shinkan Jinkendo
|
||
|
||
**Aktueller Stand (laufend):**
|
||
|
||
- **Phase 0:** abgeschlossen – siehe **[BASELINE_SNAPSHOT.md](./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](./ZIELBILD_ARCHITEKTUR.md), [SCHULDEN_UND_REMEDIATION.md](./SCHULDEN_UND_REMEDIATION.md), [VERBINDLICHE_REGELN_SHINKAN.md](./VERBINDLICHE_REGELN_SHINKAN.md).
|
||
|
||
**Planungs-KI (parallel):** [PLANNING_KI_ROADMAP.md](./PLANNING_KI_ROADMAP.md) — Phase **F** Roadmap-first Progressionsgraph (ab 0.8.204), unabhängig von Architektur-Phase 4 API-Split.
|
||
|
||
---
|
||
|
||
## 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](./BASELINE_SNAPSHOT.md)**). Nach Deploy: p95 der Top-Routen erneut messen und mit Baseline vergleichen ([M2](#meilensteine-empfohlen)).
|
||
|
||
**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](../../scripts/load/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
|
||
|
||
- Jedes Feature: [VERBINDLICHE_REGELN_SHINKAN.md](./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.
|