stefan
439551951b
- Implemented new reusable components including Label, Input, InputOTP, HoverCard, Popover, Pagination, NavigationMenu, Menubar, ScrollArea, Resizable, RadioGroup, and Progress under `docs/06_Frontend/FIGMA/src/app/components/ui/`. - Enhanced structural organization to improve scalability and maintainability. - Updated `settings.gradle.kts` to include the new module `frontend:features:nennung-feature`. Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
545 lines
16 KiB
Markdown
545 lines
16 KiB
Markdown
# Turnierverwaltungs-Anwendung - Nennungs-Maske
|
||
|
||
## 📋 Projektübersicht
|
||
|
||
Professionelle Desktop-Anwendung für die Verwaltung von Pferdesport-Turnieren mit Fokus auf die **Nennungs-Maske** als
|
||
Herzstück der Anwendung.
|
||
|
||
Die Anwendung ermöglicht die effiziente Erfassung von Turnier-Nennungen durch ein intelligentes Pferd-Reiter-Suchsystem
|
||
mit Cross-Reference-Funktionalität und IMS-Kennzeichnung (Im System).
|
||
|
||
---
|
||
|
||
## 🎨 Design-System
|
||
|
||
- **Design Framework**: Material Design 3 (MUI v5+)
|
||
- **Primärfarbe**: Indigo (#3F51B5)
|
||
- **UI-Philosophie**: Kompakt, informationsdicht, tastaturoptimiert
|
||
- **Zielplattform**: Desktop (keine Mobile-Optimierung erforderlich)
|
||
|
||
---
|
||
|
||
## 🛠 Technologie-Stack
|
||
|
||
### Core
|
||
|
||
- **React** 18+ mit TypeScript
|
||
- **Material-UI (MUI)** v5+ für UI-Komponenten
|
||
- **Emotion** für CSS-in-JS Styling
|
||
|
||
### Dependencies
|
||
|
||
```json
|
||
{
|
||
"@mui/material": "^5.x",
|
||
"@emotion/react": "^11.x",
|
||
"@emotion/styled": "^11.x",
|
||
"@mui/icons-material": "^5.x",
|
||
"react": "^18.x",
|
||
"react-dom": "^18.x",
|
||
"typescript": "^5.x"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📐 Layout-Struktur
|
||
|
||
### 2-Spalten 3-Zeilen Grid (60% / 40% horizontal)
|
||
|
||
```
|
||
┌─────────────────────────────────┬──────────────────────┐
|
||
│ Pferd/Reiter Suche (60%) │ Verkauf/Buchungen │ 50%
|
||
│ - Pferd Suche + Details │ (40%) │
|
||
│ - Reiter Suche + Details │ │
|
||
├─────────────────────────────────┴──────────────────────┤
|
||
│ Navigation (Startliste | Ergebnisse | Abrechnung) │ 5%
|
||
├─────────────────────────────────┬──────────────────────┤
|
||
│ Nennungsübersicht (60%) │ Bewerbsübersicht │ 45%
|
||
│ - Reiter | Pferd | Bewerbe │ (40%) │
|
||
│ - Tabbed Interface │ - Doppelklick nennt │
|
||
└─────────────────────────────────┴──────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 🏗 Komponenten-Architektur
|
||
|
||
### Komponenten-Hierarchie
|
||
|
||
```
|
||
App.tsx
|
||
└── NennungsMaske.tsx (Hauptlayout)
|
||
├── PferdReiterEingabe.tsx (Such-System)
|
||
├── VerkaufBuchungen.tsx (Verkauf/Buchungen)
|
||
├── NennungenTabelle.tsx (Nennungsübersicht)
|
||
└── Bewerbsliste.tsx (Bewerbsübersicht)
|
||
```
|
||
|
||
### Datei-Übersicht
|
||
|
||
| Datei | Beschreibung | Zeilen |
|
||
|--------------------------|---------------------------------------|--------|
|
||
| `App.tsx` | Root Component mit MUI Theme Provider | ~30 |
|
||
| `theme.tsx` | Material Design 3 Theme (Indigo) | ~50 |
|
||
| `NennungsMaske.tsx` | Hauptlayout mit Grid-Struktur | ~120 |
|
||
| `PferdReiterEingabe.tsx` | Intelligentes Such-System | ~400 |
|
||
| `VerkaufBuchungen.tsx` | Verkauf & Buchungen Tabs | ~250 |
|
||
| `NennungenTabelle.tsx` | Nennungsübersicht mit Tabs | ~180 |
|
||
| `Bewerbsliste.tsx` | Bewerbsübersicht | ~180 |
|
||
|
||
---
|
||
|
||
## 🔍 Core Features
|
||
|
||
### 1. **Intelligentes Such-System**
|
||
|
||
#### Pferd-Suche
|
||
|
||
- **Eingabe**: Kopfnummer oder Name
|
||
- **Echtzeit-Filterung**: Während der Eingabe alle Treffer anzeigen
|
||
- **Nach Auswahl**: Top 4 Ergebnisse behalten (scrollbar)
|
||
- **Cross-Reference**: Zeigt automatisch Reiter des ausgewählten Pferdes
|
||
- **IMS-Kennzeichnung**: Bereits genannte Pferde mit "IMS" Badge
|
||
|
||
#### Reiter-Suche
|
||
|
||
- **Eingabe**: Vorname und/oder Nachname
|
||
- **Echtzeit-Filterung**: Während der Eingabe alle Treffer anzeigen
|
||
- **Nach Auswahl**: Top 4 Ergebnisse behalten (scrollbar)
|
||
- **Cross-Reference**: Zeigt automatisch Pferde des ausgewählten Reiters
|
||
- **IMS-Kennzeichnung**: Bereits genannte Reiter mit "IMS" Badge
|
||
- **Geburtsjahr**: Bei Namensgleichheit zur Unterscheidung (*1998, *2002)
|
||
|
||
#### Tastaturnavigation
|
||
|
||
- **↑/↓**: Navigation durch Suchergebnisse
|
||
- **Enter**: Auswahl bestätigen
|
||
- **Tab**: Zum nächsten Feld
|
||
- **Doppelklick**: Alternative zur Enter-Taste
|
||
|
||
### 2. **IMS-System (Im System)**
|
||
|
||
**Definition**: Pferd-Reiter-Kombinationen, die bereits für dieses Turnier genannt haben.
|
||
|
||
**Verhalten**:
|
||
|
||
```typescript
|
||
// Mock-Daten Beispiel
|
||
const turnieNennungen = [
|
||
{ reiterId: 2, pferdId: 5, bewerbNr: 3 }, // Thomas Bauer mit Domino in Bewerb 3
|
||
{ reiterId: 1, pferdId: 1, bewerbNr: 2 }, // Anna Schneider mit Obora's Donna
|
||
];
|
||
```
|
||
|
||
**Vorteile**:
|
||
|
||
- ✅ Schneller Zugriff auf häufig verwendete Kombinationen
|
||
- ✅ Vermeidung von Duplikaten
|
||
- ✅ Verkauf (z.B. "Heu") kann schnell auf bestehende Pferde gebucht werden
|
||
|
||
### 3. **Cross-Reference-Funktionalität**
|
||
|
||
#### Szenario A: Reiter → Pferde
|
||
|
||
```
|
||
1. Reiter "Ba" eingeben
|
||
2. Suchergebnis: "Thomas BAUER" (IMS)
|
||
3. Automatisch im Pferd-Feld: "Domino" (IMS)
|
||
4. Pferd auswählen → Verkauf buchen ODER
|
||
5. Anderes Pferd suchen → Neue Nennung
|
||
```
|
||
|
||
#### Szenario B: Pferd → Reiter
|
||
|
||
```
|
||
1. Pferd "Domino" suchen
|
||
2. Pferd auswählen
|
||
3. Automatisch im Reiter-Feld: "Thomas Bauer" (IMS)
|
||
4. Reiter bestätigen ODER
|
||
5. Anderen Reiter suchen → Pferd hat 2 Reiter
|
||
```
|
||
|
||
### 4. **Workflow: Nennung erstellen**
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ 1. Pferd suchen (oder via Reiter-Cross-Reference) │
|
||
│ → Pfeiltasten navigieren │
|
||
│ → Enter oder Doppelklick bestätigen │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ 2. Reiter suchen (oder via Pferd-Cross-Reference) │
|
||
│ → Pfeiltasten navigieren │
|
||
│ → Enter oder Doppelklick bestätigen │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ 3. Pferd + Reiter Details werden angezeigt │
|
||
│ → Validierung (Lizenz, Konto-Saldo) │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ 4. Bewerb aus Bewerbsübersicht wählen │
|
||
│ → Doppelklick auf Bewerb │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ 5. Nennung erscheint in Nennungsübersicht │
|
||
│ → Filterbar nach Reiter/Pferd/Bewerb │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 5. **Verkauf & Buchungen**
|
||
|
||
#### Verkauf-Tab
|
||
|
||
- **Artikel-Liste**: Nenngeld, Stallmiete, Heu, Stroh, etc.
|
||
- **Menge anpassen**: +/- Buttons oder direkte Eingabe
|
||
- **Auto-Berechnung**: Betrag = Menge × Einzelpreis
|
||
- **Hervorhebung**: Wichtige Artikel (Nenngeld, Stallmiete) gelb hinterlegt
|
||
- **Buchung**: Nur auf ausgewähltes Pferd möglich
|
||
|
||
#### Buchungen-Tab
|
||
|
||
- **Übersicht**: Alle getätigten Buchungen
|
||
- **Stornierung**: Einzelne Buchungen rückgängig machen
|
||
|
||
### 6. **Nennungsübersicht**
|
||
|
||
#### 3 Tabs
|
||
|
||
- **Reiter**: Alle Nennungen gefiltert nach ausgewähltem Reiter
|
||
- **Pferd**: Alle Nennungen gefiltert nach ausgewähltem Pferd
|
||
- **Bewerbe**: Alle Nennungen chronologisch
|
||
|
||
#### Funktionen
|
||
|
||
- **Positionieren**: Startreihenfolge manuell festlegen
|
||
- **Stornieren**: Nennung entfernen
|
||
- **Farbcodierung**:
|
||
- Grün: Startwunsch "Vorne"
|
||
- Blau: Startwunsch "Hinten"
|
||
|
||
### 7. **Bewerbsübersicht**
|
||
|
||
- **Alle Bewerbe**: Tag, Platz, Nr, Name, Beginn, Anzahl Nennungen
|
||
- **Doppelklick**: Nennung erstellen (nur wenn Pferd + Reiter ausgewählt)
|
||
- **Filter**: Bewerbe nach Kriterien filtern
|
||
- **Aktualisierung**: Echtzeit-Update der Nennungsanzahl
|
||
|
||
---
|
||
|
||
## 🎯 Bedienkonzept
|
||
|
||
### Kompakte Desktop-UI
|
||
|
||
- **Font-Größe**: 10-11px (kompakt, informationsdicht)
|
||
- **Button-Größe**: `size="small"` mit reduziertem Padding
|
||
- **Tabellen**: Dense-Modus mit minimalen Zeilenhöhen
|
||
- **Icons**: 14-16px (klein aber erkennbar)
|
||
|
||
### Tastatur-First
|
||
|
||
- **Tab-Navigation**: Durch alle Eingabefelder
|
||
- **Pfeiltasten**: Navigation in Listen
|
||
- **Enter**: Bestätigung
|
||
- **Escape**: Abbrechen (TODO)
|
||
- **Shortcuts**: (TODO: Strg+N für Neu, Strg+S für Speichern)
|
||
|
||
---
|
||
|
||
## 📊 Datenmodell (Mock)
|
||
|
||
### Pferd
|
||
|
||
```typescript
|
||
interface Pferd {
|
||
id: number;
|
||
kopfnr: string; // z.B. "A123", "4568"
|
||
name: string; // z.B. "Obora's Donna"
|
||
rasse: string; // z.B. "Hannoveraner"
|
||
farbe: string; // z.B. "Brauner"
|
||
besitzer: string; // z.B. "Franz Huber"
|
||
stall: string; // z.B. "Box 12"
|
||
}
|
||
```
|
||
|
||
### Reiter
|
||
|
||
```typescript
|
||
interface Reiter {
|
||
id: number;
|
||
kopfnr: string; // z.B. "201"
|
||
vorname: string; // z.B. "Thomas"
|
||
nachname: string; // z.B. "Bauer"
|
||
verein: string; // z.B. "RC Graz"
|
||
lizenz: string; // z.B. "LNR-2024-4587"
|
||
lizenzGueltig: boolean;
|
||
kontoSaldo: number; // z.B. -125.50 (negativ = Schulden)
|
||
geburtsjahr: number; // z.B. 1998 (für Namensgleichheit)
|
||
}
|
||
```
|
||
|
||
### Nennung
|
||
|
||
```typescript
|
||
interface Nennung {
|
||
id: number;
|
||
pferdId: number;
|
||
reiterId: number;
|
||
bewerbNr: string; // z.B. "1", "2a"
|
||
bewerbName: string; // z.B. "Dressur Kl. L"
|
||
tag: string; // z.B. "SA", "SO"
|
||
platz: string; // z.B. "A1", "C2"
|
||
startwunsch?: string; // z.B. "Vorne", "Hinten"
|
||
}
|
||
```
|
||
|
||
### Bewerb
|
||
|
||
```typescript
|
||
interface Bewerb {
|
||
nr: string; // z.B. "1", "2a"
|
||
name: string; // z.B. "Dressur Kl. L"
|
||
tag: string; // z.B. "SA"
|
||
platz: string; // z.B. "A1"
|
||
beginn: string; // z.B. "08:00"
|
||
nenn: number; // Anzahl Nennungen
|
||
}
|
||
```
|
||
|
||
### Turnie-Nennung (IMS)
|
||
|
||
```typescript
|
||
interface TurnieNennung {
|
||
reiterId: number;
|
||
pferdId: number;
|
||
bewerbNr: number;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 Installation & Setup
|
||
|
||
### Schritt 1: Projekt initialisieren
|
||
|
||
```bash
|
||
# React + TypeScript Projekt erstellen
|
||
npx create-react-app turnierverwaltung --template typescript
|
||
|
||
cd turnierverwaltung
|
||
```
|
||
|
||
### Schritt 2: Dependencies installieren
|
||
|
||
```bash
|
||
# MUI und Dependencies
|
||
npm install @mui/material @emotion/react @emotion/styled @mui/icons-material
|
||
|
||
# TypeScript Types (falls benötigt)
|
||
npm install --save-dev @types/react @types/react-dom
|
||
```
|
||
|
||
### Schritt 3: Projektstruktur erstellen
|
||
|
||
```
|
||
src/
|
||
├── app/
|
||
│ ├── App.tsx
|
||
│ ├── theme.tsx
|
||
│ └── components/
|
||
│ ├── NennungsMaske.tsx
|
||
│ ├── PferdReiterEingabe.tsx
|
||
│ ├── VerkaufBuchungen.tsx
|
||
│ ├── NennungenTabelle.tsx
|
||
│ └── Bewerbsliste.tsx
|
||
├── styles/
|
||
│ └── theme.css
|
||
└── index.tsx
|
||
```
|
||
|
||
### Schritt 4: Dateien manuell übertragen
|
||
|
||
**WICHTIG**: Da kein Download verfügbar ist, müssen Sie die Dateien manuell aus Figma Make kopieren:
|
||
|
||
1. **Öffnen Sie jede Komponente** in Figma Make
|
||
2. **Kopieren Sie den Code** (Strg+A, Strg+C)
|
||
3. **Erstellen Sie die Datei** in Ihrer IDE
|
||
4. **Fügen Sie den Code ein** (Strg+V)
|
||
|
||
**Reihenfolge**:
|
||
|
||
1. `theme.tsx` (Theme zuerst!)
|
||
2. `App.tsx`
|
||
3. `NennungsMaske.tsx`
|
||
4. `PferdReiterEingabe.tsx`
|
||
5. `VerkaufBuchungen.tsx`
|
||
6. `NennungenTabelle.tsx`
|
||
7. `Bewerbsliste.tsx`
|
||
|
||
### Schritt 5: Starten
|
||
|
||
```bash
|
||
npm start
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 Nächste Schritte / TODO
|
||
|
||
### Phase 1: Backend-Integration
|
||
|
||
- [ ] REST API Endpoints definieren
|
||
- [ ] Pferde aus Datenbank laden
|
||
- [ ] Reiter aus Datenbank laden
|
||
- [ ] Nennungen persistieren
|
||
- [ ] Echtzeit-Updates (WebSocket?)
|
||
|
||
### Phase 2: Erweiterte Features
|
||
|
||
- [ ] **Neu-Button**: Dialog für neue Pferde/Reiter
|
||
- [ ] **Bearbeiten-Button**: Inline-Editing von Details
|
||
- [ ] **Stornieren**: Nennung mit Bestätigung löschen
|
||
- [ ] **Positionieren**: Drag & Drop für Startreihenfolge
|
||
- [ ] **Filter**: Erweiterte Filteroptionen
|
||
- [ ] **Drucken**: Startlisten, Nennungslisten
|
||
- [ ] **Export**: PDF, Excel
|
||
|
||
### Phase 3: Validierung & Business Logic
|
||
|
||
- [ ] Lizenz-Prüfung (abgelaufene Lizenzen warnen)
|
||
- [ ] Konto-Saldo Warnung (negative Salden)
|
||
- [ ] Doppel-Nennungen verhindern
|
||
- [ ] Zeitkonflikte erkennen
|
||
- [ ] Kapazitätsgrenzen (max. Nennungen pro Bewerb)
|
||
|
||
### Phase 4: Weitere Masken
|
||
|
||
- [ ] **Startliste**: Reihenfolge, Startzeiten
|
||
- [ ] **Ergebnisse**: Platzierungen erfassen
|
||
- [ ] **Abrechnung**: Kosten, Zahlungen, Quittungen
|
||
|
||
### Phase 5: UX-Verbesserungen
|
||
|
||
- [ ] **Keyboard Shortcuts**: Strg+N, Strg+S, etc.
|
||
- [ ] **Undo/Redo**: Historie für Änderungen
|
||
- [ ] **Suche optimieren**: Fuzzy Search, Synonyme
|
||
- [ ] **Loading States**: Spinner, Skeleton Screens
|
||
- [ ] **Error Handling**: Benutzerfreundliche Fehlermeldungen
|
||
|
||
### Phase 6: Performance
|
||
|
||
- [ ] **Virtualisierung**: Große Listen (1000+ Einträge)
|
||
- [ ] **Lazy Loading**: Komponenten on-demand laden
|
||
- [ ] **Caching**: Häufig verwendete Daten
|
||
|
||
---
|
||
|
||
## 💡 Design-Entscheidungen
|
||
|
||
### Warum Material Design 3?
|
||
|
||
- **Konsistentes Design-System**: Bewährte Patterns
|
||
- **Accessibility**: WCAG-konform out-of-the-box
|
||
- **Rich Component Library**: Weniger Custom-Code
|
||
- **Professional Look**: Moderne, cleane Optik
|
||
|
||
### Warum Indigo als Primärfarbe?
|
||
|
||
- **Professionell**: Vertrauenswürdig, seriös
|
||
- **Kontrast**: Gute Lesbarkeit auf hellem Hintergrund
|
||
- **Differenzierung**: Nicht das "Standard-Blau"
|
||
|
||
### Warum 2-Spalten Layout?
|
||
|
||
- **Workflow-orientiert**: Eingabe links, Übersicht rechts
|
||
- **Platzsparend**: Maximale Information auf einem Screen
|
||
- **Desktop-optimiert**: Nutzt breite Bildschirme effizient
|
||
|
||
### Warum IMS-System?
|
||
|
||
- **Performance**: Reduziert Suchzeit drastisch
|
||
- **UX**: Häufige Kombinationen sofort verfügbar
|
||
- **Fehlerminimierung**: Bereits validierte Kombinationen
|
||
|
||
---
|
||
|
||
## 🤝 Team-Übergabe Checkliste
|
||
|
||
### Für Frontend-Entwickler
|
||
|
||
- [ ] README durchlesen (diese Datei!)
|
||
- [ ] Komponenten-Struktur verstehen
|
||
- [ ] Mock-Daten analysieren
|
||
- [ ] Workflow nachvollziehen (IMS, Cross-Reference)
|
||
- [ ] UI/UX Konzept verinnerlichen
|
||
|
||
### Für Backend-Entwickler
|
||
|
||
- [ ] Datenmodell definieren (siehe "Datenmodell")
|
||
- [ ] API Endpoints spezifizieren
|
||
- [ ] Validierungs-Regeln implementieren
|
||
- [ ] Performance-Anforderungen klären
|
||
|
||
### Für Product Owner
|
||
|
||
- [ ] Feature-Priorisierung (siehe "Nächste Schritte")
|
||
- [ ] User Stories schreiben
|
||
- [ ] Acceptance Criteria definieren
|
||
|
||
### Für Designer
|
||
|
||
- [ ] Theme anpassen (Farben, Schriften)
|
||
- [ ] Icons konsistent gestalten
|
||
- [ ] Print-Layouts definieren
|
||
|
||
---
|
||
|
||
## 📞 Support & Fragen
|
||
|
||
### Häufige Fragen
|
||
|
||
**Q: Warum verschwindet das Suchfeld nicht nach der Auswahl?**
|
||
A: Bewusste Design-Entscheidung! Die Top 4 Ergebnisse bleiben sichtbar, damit man schnell zwischen ähnlichen
|
||
Pferden/Reitern wechseln kann (z.B. mehrere "Obora's..." Pferde).
|
||
|
||
**Q: Was bedeutet IMS?**
|
||
A: "Im System" = Pferd-Reiter-Kombination hat bereits eine Nennung für dieses Turnier.
|
||
|
||
**Q: Warum Cross-Reference?**
|
||
A: Effizienz! Wenn ich einen Reiter suche, sehe ich sofort seine Pferde. Spart Zeit bei Verkäufen oder weiteren
|
||
Nennungen.
|
||
|
||
**Q: Kann ein Pferd mehrere Reiter haben?**
|
||
A: Ja! Ein Pferd kann von verschiedenen Reitern in verschiedenen Bewerben geritten werden.
|
||
|
||
**Q: Warum ist die Schrift so klein?**
|
||
A: Desktop-Anwendung für Profis. Kompakte Darstellung = mehr Information auf einem Blick = weniger Scrollen.
|
||
|
||
---
|
||
|
||
## 📄 Lizenz
|
||
|
||
(Bitte durch Ihr Team festlegen)
|
||
|
||
---
|
||
|
||
## ✍️ Autoren & Mitwirkende
|
||
|
||
- **Projekt-Owner**: [Ihr Name]
|
||
- **Prototyp**: Erstellt mit Figma Make
|
||
- **Datum**: März 2026
|
||
|
||
---
|
||
|
||
## 📝 Änderungshistorie
|
||
|
||
| Version | Datum | Änderung |
|
||
|---------|------------|------------------------------------------|
|
||
| 0.1.0 | 2026-03-21 | Initialer Prototyp mit Nennungs-Maske |
|
||
| | | - IMS-System implementiert |
|
||
| | | - Cross-Reference-Suche |
|
||
| | | - 2-Spalten 3-Zeilen Layout (50%-5%-45%) |
|
||
| | | - Material Design 3 (Indigo) |
|
||
|
||
---
|
||
|
||
**Ende der Dokumentation**
|
||
|
||
Bei Fragen oder Unklarheiten: Bitte diese README erweitern und im Team diskutieren!
|