# Berechtigungssystem - Dokumentation

## Übersicht

Das Trainingstagebuch verfügt nun über ein vollständiges rollenbasiertes Berechtigungssystem (RBAC - Role-Based Access Control). Der Club-Ersteller hat automatisch Admin-Rechte und kann anderen Mitgliedern Rollen und spezifische Berechtigungen zuweisen.

## Rollen

### 1. Administrator (admin)
- **Vollzugriff** auf alle Funktionen
- Kann Berechtigungen anderer Benutzer verwalten
- Der Club-Ersteller ist automatisch Administrator und kann nicht degradiert werden

### 2. Trainer (trainer)
- Kann Trainingseinheiten planen und verwalten
- Kann Mitglieder anlegen und bearbeiten
- Kann Spielpläne einsehen und bearbeiten
- Kann Turniere organisieren
- **Kann nicht**: Einstellungen ändern, Berechtigungen verwalten

### 3. Mannschaftsführer (team_manager)
- Kann Teams und Spielpläne verwalten
- Kann Spieler für Matches einteilen
- Kann Spielergebnisse eintragen
- **Kann nicht**: Trainingseinheiten planen, Mitglieder verwalten

### 4. Mitglied (member)
- Nur Lesezugriff auf alle Bereiche
- Kann eigene Daten einsehen
- **Kann nicht**: Daten ändern oder löschen

## Berechtigungsbereiche

- **diary**: Trainingstagebuch
- **members**: Mitgliederverwaltung
- **teams**: Team-Management
- **schedule**: Spielpläne
- **tournaments**: Turniere
- **statistics**: Statistiken
- **settings**: Einstellungen
- **permissions**: Berechtigungsverwaltung
- **mytischtennis**: MyTischtennis-Integration (für alle zugänglich)

## Backend-Integration

### Migration ausführen

```sql
mysql -u username -p database_name < backend/migrations/add_permissions_to_user_club.sql
```

### Authorization Middleware verwenden

```javascript
import { authorize, requireAdmin, requireOwner } from '../middleware/authorizationMiddleware.js';

// Beispiel: Nur Lesezugriff erforderlich
router.get('/diary/:clubId', authenticate, authorize('diary', 'read'), getDiary);

// Beispiel: Schreibzugriff erforderlich
router.post('/diary/:clubId', authenticate, authorize('diary', 'write'), createDiary);

// Beispiel: Admin-Rechte erforderlich
router.put('/settings/:clubId', authenticate, requireAdmin(), updateSettings);

// Beispiel: Nur Owner
router.delete('/club/:clubId', authenticate, requireOwner(), deleteClub);
```

### Permission Service verwenden

```javascript
import permissionService from '../services/permissionService.js';

// Berechtigungen prüfen
const hasPermission = await permissionService.hasPermission(userId, clubId, 'diary', 'write');

// Rolle setzen
await permissionService.setUserRole(userId, clubId, 'trainer', adminUserId);

// Custom Permissions setzen
await permissionService.setCustomPermissions(
  userId, 
  clubId, 
  { diary: { write: false }, members: { write: true } },
  adminUserId
);
```

## Frontend-Integration

### Composable verwenden

```vue
<script setup>
import { usePermissions } from '@/composables/usePermissions.js';

const { can, canWrite, canDelete, isAdmin, isOwner, userRole } = usePermissions();

// Beispiel
if (can('diary', 'write')) {
  // Zeige Bearbeitungsbutton
}
</script>
```

### Direktiven verwenden

```vue
<template>
  <!-- Nur anzeigen, wenn Schreibrechte für diary vorhanden -->
  <button v-can:diary.write>Bearbeiten</button>
  
  <!-- Nur anzeigen, wenn Löschrechte für members vorhanden -->
  <button v-can:members.delete>Löschen</button>
  
  <!-- Alternative Syntax -->
  <div v-can="'diary.write'">Inhalt nur für Berechtigte</div>
  
  <!-- Nur für Admins -->
  <div v-admin>Admin-Bereich</div>
  
  <!-- Nur für Owner -->
  <div v-owner>Owner-Bereich</div>
</template>
```

### Store verwenden

```javascript
import { useStore } from 'vuex';

const store = useStore();

// Berechtigungen abrufen
const permissions = store.getters.currentPermissions;
const hasPermission = store.getters.hasPermission('diary', 'write');
const isOwner = store.getters.isClubOwner;
const userRole = store.getters.userRole;

// Berechtigungen laden (wird automatisch beim Club-Wechsel gemacht)
await store.dispatch('loadPermissions', clubId);
```

## Admin-UI

Die Berechtigungsverwaltung ist unter `/permissions` verfügbar und nur für Administratoren sichtbar.

**Funktionen:**
- Übersicht aller Clubmitglieder mit ihren Rollen
- Rollen zuweisen/ändern
- Custom Permissions für einzelne Benutzer definieren
- Erklärung der verfügbaren Rollen

## MyTischtennis-Integration

Die MyTischtennis-Einstellungen und -Funktionen sind für **alle Club-Mitglieder** zugänglich, unabhängig von ihrer Rolle. Dies ermöglicht es jedem, die Anbindung einzurichten und Daten abzurufen.

## Sicherheitshinweise

1. **Der Club-Ersteller** (Owner) kann nicht degradiert oder gelöscht werden
2. **Owner-Rechte** können nicht übertragen werden
3. **Backend-Validierung** wird immer durchgeführt, auch wenn das Frontend Elemente ausblendet
4. **Alle API-Routen** sind durch Middleware geschützt
5. **Permissions werden gecacht** im localStorage für bessere Performance

## Beispiel-Szenarien

### Szenario 1: Trainer hinzufügen
1. Admin öffnet `/permissions`
2. Wählt Benutzer aus
3. Ändert Rolle zu "Trainer"
4. Benutzer kann jetzt Trainingseinheiten planen

### Szenario 2: Custom Permissions
1. Admin öffnet `/permissions`
2. Wählt Benutzer aus
3. Klickt auf "Anpassen"
4. Setzt individuelle Berechtigungen (z.B. nur Diary-Schreibrecht)
5. Speichert

### Szenario 3: Neues Mitglied
1. Mitglied registriert sich und fordert Zugang an
2. Admin genehmigt Anfrage (Standardrolle: "member")
3. Mitglied hat Lesezugriff
4. Bei Bedarf kann Admin die Rolle später ändern

## Troubleshooting

**Problem**: Berechtigungen werden nicht aktualisiert
- **Lösung**: Seite neu laden oder Club neu auswählen

**Problem**: "Keine Berechtigung" trotz korrekter Rolle
- **Lösung**: Prüfen, ob Custom Permissions die Rolle überschreiben

**Problem**: Owner kann keine Änderungen vornehmen
- **Lösung**: Owner sollte automatisch alle Rechte haben. Prüfen Sie die `isOwner`-Flag in der Datenbank

## API-Endpunkte

```
GET    /api/permissions/:clubId                          - Eigene Berechtigungen abrufen
GET    /api/permissions/:clubId/members                  - Alle Mitglieder mit Berechtigungen (Admin)
PUT    /api/permissions/:clubId/user/:userId/role        - Rolle ändern (Admin)
PUT    /api/permissions/:clubId/user/:userId/permissions - Custom Permissions setzen (Admin)
GET    /api/permissions/roles/available                  - Verfügbare Rollen abrufen
GET    /api/permissions/structure/all                    - Berechtigungsstruktur abrufen
```