# MyTischtennis Automatischer Datenabruf

## Übersicht

Dieses System ermöglicht den automatischen Abruf von Spielergebnissen und Statistiken von myTischtennis.de.

## Scheduler

### 6:00 Uhr - Rating Updates
- **Service:** `autoUpdateRatingsService.js`
- **Funktion:** Aktualisiert TTR/QTTR-Werte für Spieler
- **Status:** ✅ Aktiv. Nutzt `memberService.updateRatingsFromMyTischtennisByUserId(...)` pro Verein ueber einen freigeschalteten Benutzer mit gespeichertem myTischtennis-Login.

### 6:30 Uhr - Spielergebnisse
- **Service:** `autoFetchMatchResultsService.js`
- **Funktion:** Ruft Team-Spielplaene, Liga-Spielplaene, Spielerbilanzen und Ligatabellen fuer konfigurierte Teams ab
- **Status:** ✅ Aktiv. Importiert neue Spiele, aktualisiert Ergebnis- und Termin-Aenderungen und synchronisiert Ligatabellen.

## Benötigte Konfiguration

### 1. MyTischtennis-Account
- Account muss in den MyTischtennis-Settings verknüpft sein
- Checkbox "Automatische Updates" aktivieren
- Passwort speichern (erforderlich für automatische Re-Authentifizierung)

### 2. League-Konfiguration

Für jede Liga müssen folgende Felder ausgefüllt werden:

```sql
UPDATE league SET
  my_tischtennis_group_id = '504417',  -- Group ID von myTischtennis
  association = 'HeTTV',               -- Verband (z.B. HeTTV, DTTB)
  groupname = '1.Kreisklasse'          -- Gruppenname für URL
WHERE id = 1;
```

**Beispiel-URL:**
```
https://www.mytischtennis.de/click-tt/HeTTV/25--26/ligen/1.Kreisklasse/gruppe/504417/...
                                       ^^^^^         ^^^^^^^^^^^^^^        ^^^^^^
                                    association      groupname          group_id
```

### 3. Team-Konfiguration

Für jedes Team muss die myTischtennis Team-ID gesetzt werden:

```sql
UPDATE club_team SET
  my_tischtennis_team_id = '2995094'  -- Team ID von myTischtennis
WHERE id = 1;
```

**Beispiel-URL:**
```
.../mannschaft/2995094/Harheimer_TC_(J11)/spielerbilanzen/gesamt
               ^^^^^^^
              team_id
```

### 4. Spieler-Zuordnung (Optional)

Spieler werden automatisch anhand des Namens zugeordnet. Für genauere Zuordnung kann die myTischtennis Player-ID gesetzt werden:

```sql
UPDATE member SET
  my_tischtennis_player_id = 'NU2705037'  -- Player ID von myTischtennis
WHERE id = 1;
```

## Migrationen

Folgende Migrationen müssen ausgeführt werden:

```bash
# 1. MyTischtennis Auto-Update-Felder
mysql -u root -p trainingstagebuch < backend/migrations/add_auto_update_ratings_to_my_tischtennis.sql

# 2. MyTischtennis Update-History-Tabelle
mysql -u root -p trainingstagebuch < backend/migrations/create_my_tischtennis_update_history.sql

# 3. League MyTischtennis-Felder
mysql -u root -p trainingstagebuch < backend/migrations/add_mytischtennis_fields_to_league.sql

# 4. Team MyTischtennis-ID
mysql -u root -p trainingstagebuch < backend/migrations/add_mytischtennis_team_id_to_club_team.sql

# 5. Member MyTischtennis Player-ID
mysql -u root -p trainingstagebuch < backend/migrations/add_mytischtennis_player_id_to_member.sql

# 6. Match Result-Felder
mysql -u root -p trainingstagebuch < backend/migrations/add_match_result_fields.sql
```

## Abgerufene Daten

Von der myTischtennis API werden folgende Daten abgerufen:

### Einzelstatistiken
- Player ID, Vorname, Nachname
- Gewonnene/Verlorene Punkte
- Anzahl Spiele
- Detaillierte Statistiken nach Gegner-Position

### Doppelstatistiken
- Player IDs, Namen der beiden Spieler
- Gewonnene/Verlorene Punkte
- Anzahl Spiele
- Zuordnung der beteiligten Mitglieder ueber Player-ID oder Namensabgleich

### Team-Informationen
- Teamname, Liga, Saison
- Gesamtpunkte (gewonnen/verloren)
- Doppel- und Einzelpunkte

## Implementierungsdetails

### Datenfluss

1. **Scheduler** (6:30 Uhr):
   - `schedulerService.js` triggert `autoFetchMatchResultsService.executeAutomaticFetch()`

2. **Account-Verarbeitung**:
   - Lädt alle MyTischtennis-Accounts mit `autoUpdateRatings = true`
   - Prüft Session-Gültigkeit
   - Re-Authentifizierung bei abgelaufener Session

3. **Team-Abfrage**:
   - Lädt alle Teams mit konfigurierten myTischtennis-IDs
   - Baut API-URL dynamisch zusammen
   - Führt authentifizierten GET-Request durch

4. **Datenverarbeitung**:
   - Parst JSON-Response
   - Matched Spieler anhand von ID oder Name
   - Speichert myTischtennis Player-ID bei Mitgliedern
   - verarbeitet auch Doppelpartner-Zuordnungen
   - speichert/aktualisiert Spiele und Ligatabellen

### Player-Matching-Algorithmus

```javascript
1. Suche nach myTischtennis Player-ID (exakte Übereinstimmung)
2. Falls nicht gefunden: Suche nach Name (case-insensitive)
3. Falls gefunden: Speichere myTischtennis Player-ID für zukünftige Abfragen
```

**Hinweis:** Da Namen verschlüsselt gespeichert werden, müssen für den Namens-Abgleich alle Members geladen und entschlüsselt werden. Dies ist bei großen Datenbanken ineffizient.

## TODO / Offene Punkte

### Noch offen:

1. **Spielergebnis-Details**:
   - Einzelne Matches mit Satzständen speichern
   - Tabelle für Match-Historie erstellen

2. **History-Tabelle für Spielergebnis-Abrufe** (optional):
   - Ähnlich zu `my_tischtennis_update_history`
   - Speichert Erfolg/Fehler der Abrufe

3. **Benachrichtigungen** (optional):
   - Email/Push bei neuen Ergebnissen
   - Highlights für besondere Siege

4. **Performance-Optimierung**:
   - Caching für Player-Matches
   - Incremental Updates (nur neue Daten)

## Manueller Test

```javascript
// Im Node-Backend-Code oder über API-Endpoint:
import schedulerService from './services/schedulerService.js';

// Rating Updates manuell triggern
await schedulerService.triggerRatingUpdates();

// Spielergebnisse manuell abrufen
await schedulerService.triggerMatchResultsFetch();
```

### Manuelle HTTP-Trigger

```text
POST /api/scheduler/rating_updates
POST /api/scheduler/match_results
GET  /api/scheduler/status
```

## API-Dokumentation

### MyTischtennis Spielerbilanzen-Endpoint

**URL-Format:**
```
https://www.mytischtennis.de/click-tt/{association}/{season}/ligen/{groupname}/gruppe/{groupId}/mannschaft/{teamId}/{teamname}/spielerbilanzen/gesamt?_data=routes%2Fclick-tt%2B%2F%24association%2B%2F%24season%2B%2F%24type%2B%2F%28%24groupname%29.gruppe.%24urlid_.mannschaft.%24teamid.%24teamname%2B%2Fspielerbilanzen.%24filter
```

**Parameter:**
- `{association}`: Verband (z.B. "HeTTV")
- `{season}`: Saison im Format "25--26"
- `{groupname}`: Gruppenname URL-encoded (z.B. "1.Kreisklasse")
- `{groupId}`: Gruppen-ID (numerisch, z.B. "504417")
- `{teamId}`: Team-ID (numerisch, z.B. "2995094")
- `{teamname}`: Teamname URL-encoded mit Underscores (z.B. "Harheimer_TC_(J11)")

**Response:** JSON mit `data.balancesheet` Array

## Sicherheit

- ✅ Automatische Session-Verwaltung
- ✅ Re-Authentifizierung bei abgelaufenen Sessions
- ✅ Passwörter verschlüsselt gespeichert
- ✅ Fehlerbehandlung und Logging
- ✅ Graceful Degradation (einzelne Team-Fehler stoppen nicht den gesamten Prozess)
