Lars
4b2848c7c3
All checks were successful
Deploy Development / deploy (push) Successful in 41s
Test Suite / pytest-backend (push) Successful in 35s
Test Suite / lint-backend (push) Successful in 0s
Test Suite / build-frontend (push) Successful in 11s
Test Suite / playwright-tests (push) Successful in 57s
- 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>
134 lines
5.2 KiB
Markdown
134 lines
5.2 KiB
Markdown
# Architekturschuld – Erfassung und Behebungsschritte
|
||
|
||
Dieses Dokument listet **bewusst** die aus MVP und Code-Review bekannten strukturellen Themen auf und ordnet **konkrete Massnahmen** zu. Reihenfolge ist an die Roadmap gekoppelt; hier die inhaltliche Detailierung.
|
||
|
||
---
|
||
|
||
## A. Frontend
|
||
|
||
### A1 – „God Pages“ (Training, Übungsformular, Vereine)
|
||
|
||
**Schuld:** Sehr grosse Dateien (tausende Zeilen) mit viel State, vielen Effekten und eingebetteten Modals.
|
||
|
||
**Risiko:** Hohe Re-Render-Kosten, schwerer zu testen, hoher RAM auf schwachen Geräten, neue Features vergrössern die Datei weiter.
|
||
|
||
**Behebungsschritte:**
|
||
|
||
1. **Inventar:** pro Page kurze Gliederung (Abschnitte) und Ziel-Komponenten benennen.
|
||
2. **Extrahieren:** Zuerst isolierbare Blöcke (Listen, Modals, Sidebar, Form-Sektionen) in Unterkomponenten; Props/Oberfläche dokumentieren.
|
||
3. **Hooks:** wiederkehrende Logik (`useEffect`-Ketten, Filter-State) in `useXxx`-Hooks pro Domäne.
|
||
4. **Optional `features/training/` o. ä.:** wenn 3+ zusammengehörige Komponenten entstehen.
|
||
|
||
**Erfolgskriterium:** Page-Datei unter dem in `VERBINDLICHE_REGELN_SHINKAN.md` genannten Soft-Limit oder dokumentierte Ausnahme.
|
||
|
||
---
|
||
|
||
### A2 – Monolithischer API-Client (`utils/api.js`)
|
||
|
||
**Schuld:** Eine Datei bündelt alle Endpoints; erschwert Tree-Shaking, Navigation und domänenweise Ownership.
|
||
|
||
**Behebungsschritte:**
|
||
|
||
1. Verzeichnisstruktur festlegen, z. B. `frontend/src/api/` mit `client.js` (Token, `request`), `exercises.js`, `planning.js`, …
|
||
2. Bestehende `api.js` schrittweise zur **Facade** (`export * from …`) degradieren oder re-exportieren.
|
||
3. Neue Features **nur** in domänenspezifischen Dateien implementieren.
|
||
|
||
**Erfolgskriterium:** Kein Wachstum des Monolithen über bestehende Endpoint-Anzahl hinaus; mittelfristig dominieren kleine Module.
|
||
|
||
---
|
||
|
||
### A3 – Redundante und „chatty“ Client-Requests
|
||
|
||
**Schuld (Beispiele):** Dashboard lädt Profil erneut trotz Auth; mehrere nahezu gleiche `listTrainingUnits`-Aufrufe; doppelte `listExercises` für KPIs.
|
||
|
||
**Risiko:** Mehr Last auf API/DB, schlechtere UX auf langsamen Geräten.
|
||
|
||
**Behebungsschritte:**
|
||
|
||
1. **Profil:** eine kanonische Quelle (Auth-Profil reicht für Anzeige; fehlende Felder gezielt nachladen oder Auth-Check erweitern – fachlich klären).
|
||
2. **Dashboard:** einen **Summary-Endpoint** spezifizieren und implementieren (siehe Backend B1) oder Client auf einen aggregierten Aufruf reduzieren.
|
||
3. **Org-Inbox / globale Fetches:** Ladestrategie definieren (on-demand vs. TTL vs. sichtbarkeitsabhängig) und `OrgInboxContext` entsprechend umbauen.
|
||
|
||
**Stand Umsetzung:** Gemeinsame Funktion `fetchOrgInboxSnapshot` für Mount und `refreshOrgInbox` (ein Codepfad, gleiche API-Calls). Optionales verzögertes Laden / TTL weiterhin offen.
|
||
|
||
**Erfolgskriterium:** Dashboard-Initialisierung ohne redundanten `getCurrentProfile`; ohne drei parallele fast gleiche Trainingslisten (oder dokumentierte Ausnahme).
|
||
|
||
---
|
||
|
||
### A4 – Schwere Abhängigkeiten
|
||
|
||
**Schuld:** PDF/Markdown/Canvas-Pfade ziehen grosse Chunks.
|
||
|
||
**Behebungsschritte:** Strikte `import()` an Nutzeraktion; keine statischen Top-Level-Imports schwerer Libs in gemeinsamen Einstiegspfaden.
|
||
|
||
**Erfolgskriterium:** Lighthouse / Bundle-Analyse zeigt schwere Libs nur auf betroffenen Routen.
|
||
|
||
---
|
||
|
||
## B. Backend
|
||
|
||
### B1 – Aggregations- und Summary-APIs
|
||
|
||
**Schuld:** Bildschirme holen mehrere Listen und aggregieren im Client.
|
||
|
||
**Behebungsschritte:**
|
||
|
||
1. Endpoint(s) z. B. `GET /api/dashboard/summary` oder domänenspezifisch mit gleicher Sichtbarkeitslogik wie Einzel-Listen.
|
||
2. Tests oder manuelle Checkliste gegen **Tenant-Leaks** (nur eigene/sehbare Daten).
|
||
3. Versionierung in `version.py` bei neuem Router-Block oder signifikantem Modul-Update.
|
||
|
||
**Erfolgskriterium:** Fertigest Dashboard mit einer serverseitigen Zusammenfassung (oder festgelegte Client-Reduktion mit Messung).
|
||
|
||
---
|
||
|
||
### B2 – Listenqueries (z. B. Übungsliste)
|
||
|
||
**Schuld:** Korrelierte Subqueries pro Zeile können bei Wachstum teuer werden.
|
||
|
||
**Behebungsschritte:**
|
||
|
||
1. `EXPLAIN (ANALYZE, BUFFERS)` auf Produktions-näher Konfiguration mit realistischem `limit`.
|
||
2. Indizes für Filter und Sortierung ergänzen.
|
||
3. Refactoring: JOINs/LATERAL statt N-facher Subquery, wo messbar besser.
|
||
|
||
**Erfolgskriterium:** Dokumentierte p95-Zielwerte erreicht oder Trend verbessert (siehe Roadmap).
|
||
|
||
---
|
||
|
||
### B3 – Pagination
|
||
|
||
**Schuld:** Tiefe `OFFSET`-Werte skalieren schlecht.
|
||
|
||
**Behebungsschritte:** Keyset-Pagination für grosse Listen in späteren Phasen einführen; API-Vertrag dokumentieren.
|
||
|
||
---
|
||
|
||
## C. Querschnitt
|
||
|
||
### C1 – Messbarkeit
|
||
|
||
**Schuld:** Optimierung ohne Baseline.
|
||
|
||
**Behebungsschritte:** Einmalig Baseline (API p95, Bundle-Grössen Haupt-Route, ein Lasttest-Szenario) festhalten; wiederholen nach grossen Phasen.
|
||
|
||
---
|
||
|
||
### C2 – Dokumentation und Audit
|
||
|
||
**Schuld:** Wissen nur in Chats.
|
||
|
||
**Behebungsschritte:** `HANDOVER.md` und `ACCESS_LAYER_ENDPOINT_AUDIT.md` bei jedem grösseren API-Block aktualisieren; Roadmap-Phase abhaken.
|
||
|
||
---
|
||
|
||
## Mapping: Schuld → Regel
|
||
|
||
| Schuld | Primär-Regel (Shinkan) |
|
||
|--------|-------------------------|
|
||
| God Pages | S1, S2 |
|
||
| API-Monolith | S3 |
|
||
| Globale Fetches | S4 |
|
||
| Chatty API | S5 |
|
||
| Caching-Ideen | S6 |
|
||
| Grössere Features ohne Messung | S7, S8 |
|