docs: massive restructuring of documentation, development guides and agent playbooks

2026-06-15 12:54:38 +02:00
parent e4988b4397
commit ce63303b2c
686 changed files with 45423 additions and 319 deletions
@@ -0,0 +1,206 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+last_update: 2026-03-26
+---
+
+# Navigation & Routing Diagramm — Meldestelle Desktop
+
+🏗️ **[Lead Architect]** | 26. März 2026
+
+Dieses Dokument visualisiert alle Screens und Navigationsübergänge der Compose Desktop App.
+Generiert aus: `frontend/shells/meldestelle-desktop/src/jvmMain/kotlin/at/mocode/desktop/`
+
+---
+
+MVP-Hinweis (2026-04-02):
+- Die Desktop‑App startet im MVP ohne erzwungenen Login/Ping direkt in die Haupt‑Shell (Veranstaltungs‑Verwaltung).
+- Der Login‑Knoten und Auth‑Guard im Diagramm bleiben aus Planungsgründen sichtbar, sind jedoch im MVP deaktiviert.
+
+---
+
+## 1. Übersicht: NavRail-Einstiegspunkte
+
+Die linke Navigationsleiste (NavRail) bietet folgende Direkteinstiege:
+
+| Icon | Label             | Ziel-Screen        | Status                      |
+|------|-------------------|--------------------|-----------------------------|
+| 📅   | Veranstaltungen   | `Veranstaltungen`  | ✅ Implementiert             |
+| 🏇   | Reiter            | `Reiter`           | ⬜ Placeholder               |
+| 🐴   | Pferde            | `Pferde`           | ⬜ Placeholder               |
+| 👤   | Funktionäre       | `Funktionaere`     | ⬜ Placeholder               |
+| 🏆   | Meisterschaften   | `Meisterschaften`  | ⬜ Placeholder               |
+| 🥇   | Cups              | `Cups`             | ⬜ Placeholder               |
+| 📥   | Stammdaten-Import | `StammdatenImport` | 🟡 UI fertig, Polling offen |
+
+---
+
+## 2. Vollständiges Navigationsfluss-Diagramm
+
+```mermaid
+flowchart TD
+    %% ─── App-Start & Auth ───────────────────────────────────────────
+    START([App Start]) --> LOGIN
+
+    LOGIN["🔐 Login\n/auth/login"]
+    LOGIN -->|"onSuccess (returnTo)"| VERANSTALTUNGEN
+
+    AUTH_GUARD{{"🛡️ Auth Guard\n(nicht eingeloggt?)"}}
+    AUTH_GUARD -->|"nicht authentifiziert"| LOGIN
+
+    %% ─── NavRail Top-Level ──────────────────────────────────────────
+    NAVRAIL(["🗂️ NavRail"])
+    NAVRAIL --> VERANSTALTUNGEN
+    NAVRAIL --> REITER
+    NAVRAIL --> PFERDE
+    NAVRAIL --> FUNKTIONAERE
+    NAVRAIL --> MEISTERSCHAFTEN
+    NAVRAIL --> CUPS
+    NAVRAIL --> STAMMDATEN_IMPORT
+
+    %% ─── Veranstaltungen-Flow ───────────────────────────────────────
+    VERANSTALTUNGEN["📅 Veranstaltungen\n(AdminUebersichtScreen)\n/veranstaltungen"]
+    VERANSTALTUNGEN -->|"+ Neue Veranstaltung"| VERANSTALTER_AUSWAHL
+    VERANSTALTUNGEN -->|"Veranstaltung öffnen (id)"| VERANSTALTUNG_DETAIL
+
+    VERANSTALTER_AUSWAHL["🏢 Veranstalter auswählen\n/veranstalter/auswahl"]
+    VERANSTALTER_AUSWAHL -->|"Zurück"| VERANSTALTUNGEN
+    VERANSTALTER_AUSWAHL -->|"Weiter (veranstalterId)"| VERANSTALTER_DETAIL
+
+    VERANSTALTER_DETAIL["🏢 Veranstalter Detail\n/veranstalter/{id}"]
+    VERANSTALTER_DETAIL -->|"Zurück"| VERANSTALTER_AUSWAHL
+    VERANSTALTER_DETAIL -->|"Veranstaltung öffnen (vId)"| VERANSTALTUNG_UEBERSICHT
+    VERANSTALTER_DETAIL -->|"Neue Veranstaltung gespeichert"| VERANSTALTER_DETAIL
+
+    VERANSTALTUNG_UEBERSICHT["📋 Veranstaltung Übersicht\n/veranstalter/{verId}/veranstaltung/{vId}"]
+    VERANSTALTUNG_UEBERSICHT -->|"Zurück"| VERANSTALTER_DETAIL
+    VERANSTALTUNG_UEBERSICHT -->|"Turnier öffnen (tId)"| TURNIER_DETAIL
+    VERANSTALTUNG_UEBERSICHT -->|"+ Neues Turnier"| TURNIER_NEU
+
+    VERANSTALTUNG_DETAIL["📄 Veranstaltung Detail\n/veranstaltung/{id}"]
+    VERANSTALTUNG_DETAIL -->|"Zurück"| VERANSTALTUNGEN
+    VERANSTALTUNG_DETAIL -->|"+ Neues Turnier"| TURNIER_NEU
+    VERANSTALTUNG_DETAIL -->|"Turnier öffnen (tId)"| TURNIER_DETAIL
+
+    VERANSTALTUNG_NEU["➕ Neue Veranstaltung\n/veranstaltung/neu"]
+    VERANSTALTUNG_NEU -->|"Zurück"| VERANSTALTUNGEN
+    VERANSTALTUNG_NEU -->|"Speichern"| VERANSTALTUNGEN
+
+    TURNIER_DETAIL["🏟️ Turnier Detail\n/veranstaltung/{vId}/turnier/{tId}\n(inkl. Nennungs-Tab ⭐)"]
+    TURNIER_DETAIL -->|"Zurück"| VERANSTALTUNG_DETAIL
+
+    TURNIER_NEU["➕ Neues Turnier\n/veranstaltung/{vId}/turnier/neu"]
+    TURNIER_NEU -->|"Zurück"| VERANSTALTUNG_DETAIL
+    TURNIER_NEU -->|"Speichern"| VERANSTALTUNG_DETAIL
+
+    %% ─── Stammdaten-Import ──────────────────────────────────────────
+    STAMMDATEN_IMPORT["📥 Stammdaten Import\n/stammdaten/import\n(ZNS ZIP-Import)"]
+
+    %% ─── Placeholder Screens ────────────────────────────────────────
+    REITER["🏇 Reiter\n/reiter\n⬜ Placeholder"]
+    PFERDE["🐴 Pferde\n/pferde\n⬜ Placeholder"]
+    FUNKTIONAERE["👤 Funktionäre\n/funktionaere\n⬜ Placeholder"]
+    MEISTERSCHAFTEN["🏆 Meisterschaften\n/meisterschaften\n⬜ Placeholder"]
+    CUPS["🥇 Cups\n/cups\n⬜ Placeholder"]
+
+    %% ─── Logout ─────────────────────────────────────────────────────
+    LOGOUT(["🚪 Logout"])
+    LOGOUT -->|"Token löschen"| LOGIN
+
+    %% ─── Styling ────────────────────────────────────────────────────
+    style LOGIN fill:#f0a500,color:#000
+    style AUTH_GUARD fill:#e74c3c,color:#fff
+    style VERANSTALTUNGEN fill:#2ecc71,color:#000
+    style TURNIER_DETAIL fill:#3498db,color:#fff
+    style STAMMDATEN_IMPORT fill:#9b59b6,color:#fff
+    style REITER fill:#bdc3c7,color:#555
+    style PFERDE fill:#bdc3c7,color:#555
+    style FUNKTIONAERE fill:#bdc3c7,color:#555
+    style MEISTERSCHAFTEN fill:#bdc3c7,color:#555
+    style CUPS fill:#bdc3c7,color:#555
+```
+
+---
+
+## 3. Screens nach Status
+
+### ✅ Vollständig implementiert
+
+| Screen                      | Route                                       | Komponente                              |
+|-----------------------------|---------------------------------------------|-----------------------------------------|
+| Login                       | `/auth/login`                               | `LoginScreen`                           |
+| Veranstaltungen (Übersicht) | `/veranstaltungen`                          | `AdminUebersichtScreen`                 |
+| Veranstalter Auswahl        | `/veranstalter/auswahl`                     | `VeranstalterAuswahlScreen`             |
+| Veranstalter Detail         | `/veranstalter/{id}`                        | `VeranstalterDetailScreen`              |
+| Veranstaltung Übersicht     | `/veranstalter/{verId}/veranstaltung/{vId}` | `VeranstaltungUebersichtScreen`         |
+| Veranstaltung Detail        | `/veranstaltung/{id}`                       | `VeranstaltungDetailScreen`             |
+| Veranstaltung Neu           | `/veranstaltung/neu`                        | `VeranstaltungNeuScreen`                |
+| Turnier Detail              | `/veranstaltung/{vId}/turnier/{tId}`        | `TurnierDetailScreen` + `NennungsMaske` |
+| Turnier Neu                 | `/veranstaltung/{vId}/turnier/neu`          | `TurnierNeuScreen`                      |
+
+### 🟡 Teilweise implementiert
+
+| Screen            | Route                | Offen                                          |
+|-------------------|----------------------|------------------------------------------------|
+| Stammdaten Import | `/stammdaten/import` | Status-Polling zum Backend fehlt (ZNS Phase 3) |
+
+### ⬜ Placeholder (NavRail sichtbar, Screen leer)
+
+| Screen          | Route              |
+|-----------------|--------------------|
+| Reiter          | `/reiter`          |
+| Pferde          | `/pferde`          |
+| Funktionäre     | `/funktionaere`    |
+| Meisterschaften | `/meisterschaften` |
+| Cups            | `/cups`            |
+
+### 🗑️ Definiert aber nicht in Desktop-Navigation eingebunden
+
+| Screen           | Route                | Hinweis                         |
+|------------------|----------------------|---------------------------------|
+| Landing          | `/`                  | Web-App Relikt                  |
+| Home             | `/home`              | Web-App Relikt                  |
+| Dashboard        | `/dashboard`         | Web-App Relikt                  |
+| Ping             | `/ping`              | Dev/Health-Check                |
+| Profile          | `/profile`           | Web-App Relikt                  |
+| OrganizerProfile | `/organizer/profile` | Web-App Relikt                  |
+| AuthCallback     | `/auth/callback`     | Web-App Relikt (OAuth Redirect) |
+| Nennung          | `/nennung`           | Web-App Relikt                  |
+| CreateTournament | `/tournament/create` | Web-App Relikt                  |
+
+---
+
+## 4. Wichtige Hinweise
+
+### Auth Guard
+
+Jeder Screen (außer `Login`) ist durch den Auth Guard geschützt:
+
+```
+if (!authState.isAuthenticated && currentScreen !is AppScreen.Login) {
+    nav.navigateToScreen(AppScreen.Login(returnTo = AppScreen.Veranstaltungen))
+}
+```
+
+### Web-App Relikte im AppScreen
+
+Es existieren 9 Screens (`Landing`, `Home`, `Dashboard`, `Ping`, `Profile`, `OrganizerProfile`,
+`AuthCallback`, `Nennung`, `CreateTournament`), die aus der alten Web-App stammen und in der
+Desktop-App nicht gerendert werden. → **Offene Entscheidung:** Bereinigen oder für zukünftige
+Web-App-Phase behalten? Siehe ADR-Bedarf.
+
+### Nennungs-Tab ⭐
+
+Der `TurnierDetailScreen` enthält den wichtigsten fachlichen Screen: die `NennungsMaske`
+(Bewerbe-Tab). Dies ist das Herzstück des `registration-context`.
+
+---
+
+## 5. Referenzen
+
+- Quellcode: `frontend/shells/meldestelle-desktop/src/jvmMain/kotlin/at/mocode/desktop/DesktopApp.kt`
+- Quellcode: `frontend/shells/meldestelle-desktop/src/jvmMain/kotlin/at/mocode/desktop/screens/DesktopMainLayout.kt`
+- Quellcode: `frontend/core/src/commonMain/kotlin/at/mocode/frontend/core/navigation/AppScreen.kt`
+- ZNS-Importer Roadmap: `docs/01_Architecture/Roadmap_ZNS_Importer.md`
+- Figma Design-Baseline: Vision_03 (ADR Session Log 2026-03-24)