# FEATURES.md, WebRadio Feature-Übersicht

> Vollständige Übersicht aller Features der WebRadio-Plattform.
> Stand: 2026-04-05

---

## 🌐 FRONTEND (öffentlich erreichbar)

### Startseite (`/`)
- Hero-Bereich mit Radio-Name, Slogan und Live-Button
- Eingebetteter Live-Player (HTML5 Audio, persistent im Footer)
- Sendeplan-Vorschau: die nächsten Sendungen des Tages
- News-Vorschau: die letzten 3 Artikel
- Live-Badge: zeigt an wenn gerade eine Sendung läuft
- Zweisprachig (DE / EN) mit Sprachumschalter

### Sendeplan (`/sendeplan.php`)
- Vollständiger Wochenplan (Montag bis Sonntag)
- Tages-Navigation (direkt zum gewünschten Tag springen)
- Live-Countdown: zeigt wie lange bis zur nächsten Sendung
- Hervorhebung der aktuell laufenden Sendung
- DJ-Name und Sendungsfarbe pro Eintrag
- Featured-Sendungen werden besonders hervorgehoben
- **Mobile Swipe-Navigation**, zwischen Tagen wischen, Swipe-Hinweis (fadeout nach erstem Wischen)

### DJ-Profile (`/djs.php`)
- Übersicht aller aktiven DJs mit Profilfoto
- Bio auf Deutsch und Englisch
- Verlinkung zu Social Media (Facebook, Instagram, Twitter/X)
- Website-Link pro DJ
- Responsive Karten-Layout

### News (`/news.php` + `/news-detail.php`)
- Newsübersicht mit Vorschaubild, Kategorie und Datum
- Einzelartikel mit vollem HTML-Content (Formatierungen, Bilder etc.)
- Kategorien (z.B. Programm, Technik, Team, Event)
- Zweisprachige Artikel (DE / EN)
- Kurzbeschreibung (Excerpt) in der Übersicht

### Song-Wünsche (`/wunsch.php`)
- Formular: Name, Interpret, Songtitel, optionale Nachricht
- Öffnen/Schließen steuerbar durch DJs im Admin
- **Song-Voting**, Herzen-Button pro Wunsch, IP-basierter Schutz vor Mehrfach-Votes
- Top-Wünsche Anzeige (meistgewünschte Songs mit Gesamtvotes)
- **Playlist-History**, Sidebar zeigt die letzten 8 gespielten Songs mit Uhrzeit
- CSRF-geschützt, Spam-Schutz durch Validierung

### Bewerbungen (`/bewerbung.php`)
- Bewerbungsformular für neue DJs / Moderatoren
- Felder: Name, E-Mail, Erfahrung, Wunschsendeplatz, Nachricht
- Notiz-Feld für interne Bearbeitung (Admin-seitig)
- Bewerbungen erscheinen im Admin-Dashboard

### Podcasts (`/podcasts.php`)
- Übersicht aller veröffentlichten Podcast-Episoden
- Direkt einbettbarer Audio-Player pro Episode
- Beschreibung, Datum, Kategorie pro Episode
- Zweisprachig (DE / EN)

### Chat (`/chat.php`)
- Vollwertiger Echtzeit-Chat (AJAX-Polling alle 2s)
- **4 Räume**: Allgemein, Musik & Wünsche, Off-Topic, DJ-Lounge
- **Gast-Modus**: Gast-Gate Overlay, Nickname-Eingabe vor Chat-Zugang, Token via localStorage
- **Login-Modus**: DJ-Name wird automatisch aus Profil geladen, DMs, Moderations-Tools
- **Emoji-Picker**: 😊-Button öffnet Panel mit 5 Kategorien / ~100 Emojis, Einfügen an Cursor-Position
- **GIF-Funktion**: GIF-Button, Tenor API (Trending + Suche), Grid-Vorschau, Klick = sofort senden
- **Reaktionen**: 7 Emoji-Reaktionen pro Nachricht (Toggle, Zähler, Wer hat reagiert)
- **Reply**: Antwort auf eine Nachricht mit Vorschau-Zitat
- **Direktnachrichten**: Eingeloggte User können sich gegenseitig DMs schicken (inkl. Unread-Badge)
- **Moderations-Tools**: Nachrichten löschen (Soft-Delete), User bannen (IP + Token + UserID, Ablaufzeit)
- **Online-User-Liste**: rechte Sidebar, 90s Timeout, Heartbeat alle 30s
- **Layout**: max 900px zentriert, Nachrichten anchored to bottom
- **Admin-Verwaltung**: `/admin/chat.php` (Übersicht, Bans aufheben, Räume leeren)
- **Raum-Verwaltung**: `/admin/chat-rooms.php` (CRUD, Icon, Slug, Login-Pflicht, Sort)

### Kontakt (`/kontakt.php`)
- Kontaktformular mit CSRF-Schutz
- DSGVO-Checkbox mit Link zur Datenschutzerklärung
- Sendet Nachricht an konfigurierte Kontakt-E-Mail

### Rechtliches
- Impressum (`/impressum.php`), §5 TMG konform
- Datenschutzerklärung (`/datenschutz.php`), DSGVO-Grundlage

### Live-Player (global, im Footer)
- Persistent auf allen Seiten sichtbar
- HTML5 Audio-Player
- Automatische Verbindung zum Icecast-Stream (`/stream`)
- Zeigt aktuell laufenden Song (via API-Polling alle 15s)
- Bei AutoDJ: Songname + Künstler aus Icecast-Metadaten
- Bei Live-DJ: "DJ-Name, live" im Player
- Badge wechselt zwischen **LIVE** (rot) und **AutoDJ** (blau)
- Mini-Equalizer-Animation im "Gerade on Air" Badge (4 Bars, animiert wenn Stream läuft)
- Play/Pause, Lautstärke, Mute

---

## 🔧 ADMIN-PANEL (`/admin/`)

### Login & Sicherheit
- Sicheres Login mit E-Mail + Passwort
- CSRF-Schutz auf allen Formularen
- Session-basierte Authentifizierung
- Rollen- und rechtegesteuerter Zugang (kein Admin sieht mehr als erlaubt)
- Automatischer Redirect bei fehlendem Recht

### Dashboard (`/admin/index.php`)
- Übersichtskacheln: Anzahl DJs, Sendungen, News, offene Song-Wünsche
- Bewerbungen-Widget: neue Bewerbungen sofort sichtbar
- **Hörerzahl-Chart**, Chart.js Liniendiagramm (Ø + Max Hörer der letzten 24h, stündlich)
- Schnellzugriff auf häufige Aktionen
- Letzte Aktivitäten

### DJ-Verwaltung (`/admin/djs.php` + `djs-edit.php`)
- DJs anlegen, bearbeiten, aktivieren/deaktivieren
- Profilfoto hochladen (JPG, PNG, WebP, GIF, max. 5 MB)
- Bio in Deutsch und Englisch
- Social-Media-Links (Facebook, Instagram, Twitter/X, Website)
- Sortierreihenfolge anpassbar
- **Persönliche Stream-Zugangsdaten** pro DJ:
  - Eigener Mount-Pfad (z.B. `/live/dj-max`)
  - Eigenes Stream-Passwort (automatisch generiert)
  - Passwort anzeigen/verbergen + In-Zwischenablage kopieren
  - Credentials neu generieren (1-Klick)
  - Icecast-Konfig-Snippet direkt angezeigt
- Verknüpfung mit Login-Account (DJ kann eigenes Profil bearbeiten)
- Upload-Verzeichnis Gesundheitscheck (zeigt Schreibrechte-Status)

### Sendeplan (`/admin/schedule.php` + `schedule-edit.php`)
- Sendungen anlegen, bearbeiten, löschen
- Wochentag, Start- und Endzeit, DJ-Zuweisung
- Titel und Beschreibung zweisprachig (DE / EN)
- Farb-Picker pro Sendung
- Featured-Markierung für Highlight-Sendungen
- Aktivieren / Deaktivieren einzelner Einträge

### News-Verwaltung (`/admin/news.php` + `news-edit.php`)
- Artikel anlegen, bearbeiten, veröffentlichen
- Vollständiger HTML-Editor für Artikelinhalt
- Vorschaubild hochladen
- Zweisprachige Titel, Inhalt und Kurzbeschreibung
- Kategorien, Autor, Veröffentlichungsdatum
- Entwurf / Veröffentlicht Status

### Song-Wünsche (`/admin/requests.php`)
- Alle eingegangenen Wünsche mit Filter (offen / gespielt / abgelehnt)
- Status ändern (Ausstehend → Gespielt / Abgelehnt)
- Wünsche-Formular global öffnen oder schließen
- Sortierung nach Datum

### Podcasts (`/admin/podcasts.php` + `podcasts-edit.php`)
- Podcast-Episoden verwalten
- Audio-Datei hochladen oder externe URL angeben
- Beschreibung zweisprachig
- Veröffentlichungsstatus steuern

### Bewerbungen (`/admin/applications.php`)
- Alle eingegangenen DJ-Bewerbungen einsehen
- Status-Verwaltung (neu / in Bearbeitung / angenommen / abgelehnt)
- Interne Notizen pro Bewerbung

### Chat-Administration (`/admin/chat.php`)
- Statistiken: Nachrichten gesamt, heute, online jetzt, aktive Bans
- Letzte 50 Nachrichten mit Direkt-Löschen
- Aktive Bans verwalten und aufheben
- Räume leeren (alle Nachrichten eines Raums per Knopfdruck löschen)

### Chat-Räume (`/admin/chat-rooms.php`)
- CRUD für Räume: Name, Slug, Icon (Emoji), Beschreibung, Sort-Order
- Login-Pflicht pro Raum konfigurierbar
- Standard-Raum setzen, Räume deaktivieren
- Direkter Kontakt per E-Mail-Link

### Benutzer-Verwaltung (`/admin/users.php` + `users-edit.php`)
- Benutzer anlegen, bearbeiten, deaktivieren
- Rollen zuweisen (aus DB, beliebig erweiterbar)
- DJ-Profil mit Login-Account verknüpfen
- Automatische Willkommens-E-Mail bei neuem Account
- E-Mail dient als Login-Name
- Passwort-Änderung mit Stärke-Check

### Rollen & Rechte (`/admin/roles.php`)
- Vollständig DB-gesteuertes Rechte-System
- Rollen anlegen, bearbeiten, löschen (außer Kern-Rollen)
- 23 einzelne Permissions frei zuweisbar
- Rechte gruppiert nach Bereich (Dashboard, DJs, News, System etc.)
- Änderungen sofort aktiv (User muss sich neu einloggen)
- Standard-Rollen: `superadmin`, `admin`, `dj` (nicht löschbar)

### Einstellungen (`/admin/settings.php`)
- Radio-Name, Slogan (DE / EN)
- Stream-URL, Icecast-Host, Port, Mount
- Stream-Quellpasswort (mit Anzeigen/Verbergen-Button)
- Kontakt-E-Mail
- Footer-Text (DE / EN)
- Social-Media-Links (Facebook, Instagram, Twitter, Discord)
- Song-Wünsche global öffnen / schließen

### DJ-Bereich (`/admin/dj-area.php`)
- Nur für eingeloggte DJs mit verknüpftem Profil
- **Persönliche Stream-Zugangsdaten** (Mount + Passwort, kopierbar)
- **"Jetzt live gehen"**, markiert DJ als aktuell live, Benachrichtigung an alle
- **Browser-Push-Notification**, DJ bekommt Desktop-Notification wenn Sendung bestätigt wurde
- **"Sendung beenden"**, beendet Live-Status
- **"Übergabe vorbereiten"**, Modal mit DJ-Auswahl, sendet Benachrichtigung an Ziel-DJ
- Song-Wünsche-Toggle (Formular öffnen / schließen)
- Wer ist gerade live? Übersicht
- Hörer-Statistik-Widget
- Streaming-Software Tipps (BUTT, Mixxx, Traktor, Rocket Broadcaster)
- Link zum eigenen DJ-Profil

### Benachrichtigungen (`/admin/notifications.php`)
- System-Benachrichtigungen für alle Admins/DJs
- Live-Gehen, Sendungsübergabe, neue Bewerbungen
- Gelesen / Ungelesen Status

### API-Dokumentation (`/admin/api-docs.php`)
- Übersicht aller verfügbaren API-Endpunkte
- Parameter und Beispiel-Antworten

---

## 📡 API-ENDPUNKTE (`/api/`)

| Endpunkt | Beschreibung |
|----------|-------------|
| `/api/now-playing.php` | Aktuell laufender Song (JSON), Icecast-Polling |
| `/api/status.php` | Stream-Status, `is_autodj`, Songname, Listener-Anzahl, Live-DJ Name + Foto, aktuelle Sendung |
| `/api/request.php` | Song-Wunsch einreichen (POST) |
| `/api/vote.php` | Song-Wunsch voten (POST, IP-Schutz, CSRF) |
| `/api/track-played.php` | Gespielten Track von Liquidsoap empfangen (POST, Token-Schutz) |
| `/api/contact.php` | Kontaktformular absenden (POST) |
| `/api/icecast-auth.php` | Icecast URL-Authentifizierung für Live-DJs |

---

## 🎵 STREAMING & AUTO-DJ

### Icecast2 (Streaming-Server)
- Live-Stream auf Mount `/stream` (Port 8000)
- **URL-Authentifizierung**: Icecast prüft DJ-Passwörter gegen die Datenbank
- Kein Neustart bei neuen DJs, Passwörter automatisch gültig
- Globales Source-Passwort als Admin-Fallback

### Liquidsoap (Auto-DJ)
- Läuft als Systemd-Service (`liquidsoap-radio`)
- Spielt MP3s aus `/assets/audio/` in zufälliger Reihenfolge
- Playlist wird automatisch stündlich neu geladen (neue Songs sofort erkannt)
- Fallback auf Stille wenn keine Musikdateien vorhanden
- **7 GEMA-freie Tracks** vorinstalliert (Creative Commons, Clivio Botticelli AI Music)
- **on_metadata Hook**, POST an `/api/track-played.php` bei jedem Songwechsel (Playlist-History)
- Hook-Konfiguration: `liquidsoap-hook.liq` (Referenzdatei im Projekt)

### Automatisches Fallback-System
- **DJ live** → Hörer bekommen den Live-Stream
- **Kein DJ** → Icecast schaltet automatisch auf Auto-DJ um
- **DJ kommt zurück** → Icecast schaltet sofort auf Live zurück
- Alles vollautomatisch, kein manueller Eingriff nötig

### Now Playing, Live-Statusanzeige
- `GET /api/status.php` liefert: `online`, `is_autodj`, `title`, `listeners`, `live_dj`, `show`
- **AutoDJ aktiv** → Songname + Künstler aus Icecast-Metadaten angezeigt
- **DJ live** → DJ-Name + Profilfoto aus der Datenbank angezeigt
- Frontend pollt alle 15 Sekunden automatisch
- Hero-Card auf der Startseite wechselt dynamisch zwischen AutoDJ-Modus und Live-DJ-Modus
- Sticky Player (Footer) zeigt aktuellen Song bzw. "DJ Maximus, live"
- Footer "On Air" Bereich aktualisiert sich in Echtzeit
- **Live-DJ Erkennung**: DJ drückt "Jetzt live gehen" in `/admin/dj-area.php` → `djs.is_live=1` → sofort auf Webseite sichtbar
- **Sendungsende**: DJ drückt "Sendung beenden" → zurück auf AutoDJ-Anzeige
- **Übergabe**: DJ übergibt an nächsten DJ per Modal → nächster drückt "Jetzt live gehen" → Webseite wechselt automatisch

---

## 📊 STATISTIKEN & CRON

### Cronjobs (automatisch auf Server)
| Task | Intervall | Beschreibung |
|------|-----------|-------------|
| Hörer-Statistik | alle 5 Min | Speichert aktuelle Listener-Anzahl in `listener_stats` |
| Datenbank-Backup | täglich 03:00 | SQL-Dump nach `/backups/db/` |

---

## 🔐 SICHERHEIT

- **CSRF-Schutz** auf allen POST-Formularen
- **Prepared Statements** für alle Datenbankabfragen (kein SQL-Injection möglich)
- **XSS-Schutz** durch `htmlspecialchars()` überall
- **Passwort-Hashing** mit `password_hash()` (bcrypt)
- **Rechte-System** DB-gesteuert, jede Admin-Seite abgesichert
- **Upload-Schutz**: `.htaccess` in Upload-Verzeichnissen blockiert PHP-Ausführung
- **Icecast Auth**: nur aktive DJs mit gültigem DB-Passwort dürfen streamen
- **Error-Reporting** deaktiviert (keine PHP-Fehler für Besucher sichtbar)
- **Custom Error-Pages**: 404, 403, 500 im Seiten-Design

---

## 🌍 MEHRSPRACHIGKEIT

- Vollständig zweisprachig: **Deutsch** und **Englisch**
- Sprachumschalter im Frontend (DE / EN)
- Sprachdateien: `lang/de.php` + `lang/en.php`
- Alle UI-Texte, News-Inhalte, DJ-Bios, Sendungsbeschreibungen zweisprachig
- Session-basiert (bleibt beim Browsen erhalten)
- **JS-Strings** werden via `window.radioLang` aus PHP in footer.php injiziert (kein hardcoded Deutsch mehr)
- **Standardsprache** in Admin-Einstellungen konfigurierbar (DB-Setting `default_language`)

---

## 🎨 DESIGN & UX

- **Dark Wave Theme**, dunkles, modernes Radio-Design
- Bootstrap 5.3.3 als CSS-Framework
- Vollständig **responsive** (Mobile, Tablet, Desktop)
- Konsistente Farbgebung über CSS-Variablen
- Admin-Panel mit eigenem Dark-Theme
- Hover-Effekte, Transitions, Loading-States
- Custom Error-Pages (404, 403, 500) im Seiten-Design

---

## 🖥️ TECH-STACK

| Komponente | Version / Details |
|------------|-------------------|
| Server-OS | Ubuntu 24.04 LTS |
| Webserver | Apache 2.4.58 |
| PHP | 8.5.4 (prozedural, PDO) |
| Datenbank | MySQL 8.0.45 |
| Streaming | Icecast2 2.4.4 |
| Auto-DJ | Liquidsoap 2.2.4 |
| CSS-Framework | Bootstrap 5.3.3 (CDN) |
| Icons | Bootstrap Icons (CDN) |
| Hosting | VPS (23.88.48.74) |

---

## 📁 VERZEICHNISSTRUKTUR (Übersicht)

```
/var/www/radio/
├── index.php, djs.php, sendeplan.php, news.php ...  (Frontend)
├── admin/                  Admin-Panel
├── api/                    API-Endpunkte
├── assets/
│   ├── css/style.css       Frontend-Design
│   ├── js/main.js          Player + AJAX
│   ├── img/djs/            DJ-Profilfotos
│   ├── img/news/           News-Bilder
│   └── audio/              Auto-DJ Musikdateien (MP3)
├── includes/               Header, Footer, Auth, Functions
├── config/                 DB-Verbindung, Konfiguration
├── lang/                   Sprachdateien DE + EN
├── cron/                   Cronjob-Scripts
├── backups/db/             Automatische DB-Backups
└── errors/                 Custom Error-Pages
```

---

## 🚧 OFFEN / GEPLANT

- [ ] Impressum + Datenschutz mit echten Daten befüllen (vor Go-Live!)
- [ ] HTTPS / SSL (sobald Domain verfügbar)
- [ ] Liquidsoap on_metadata Hook auf dem Server aktivieren (Anleitung: `liquidsoap-hook.liq`)
- [ ] `liquidsoap_token` in DB-Settings ggf. auf individuellen Wert ändern
- [x] **Live-Chat**, Vollwertiger Chat mit Räumen, DMs, Reaktionen, GIFs, Emoji-Picker, Moderation
- [ ] Weitere Rollen: Sendeleitung, Castingleitung (über `/admin/roles.php`)
- [ ] Weitere GEMA-freie Musik für Auto-DJ hochladen (`/assets/audio/`)

## ✅ ERLEDIGT

- [x] Hörerzahl-Chart im Admin-Dashboard (Chart.js, letzte 24h, stündlich) (2026-04-04)
- [x] Song-Wunsch Voting (Herzen-Button, IP-Schutz, API `api/vote.php`) (2026-04-04)
- [x] Playlist-History auf wunsch.php (letzte 8 Songs, via `playlist_history` Tabelle) (2026-04-04)
- [x] Liquidsoap Track-Endpoint (`api/track-played.php`, Token-Schutz) (2026-04-04)
- [x] Cookie-Banner DSGVO (localStorage-basiert, Opt-In) (2026-04-04)
- [x] Sitemap.xml dynamisch (`sitemap.php`, inkl. News + DJ-Profile + hreflang) (2026-04-04)
- [x] Mobile Swipe-Navigation im Sendeplan (2026-04-04)
- [x] Browser Push Notification beim "Jetzt live gehen" (Notification API) (2026-04-04)
- [x] Zweisprachiges JS via `window.radioLang` + `lang/de.php` + `lang/en.php` (2026-04-04)
- [x] Standardsprache in Admin-Einstellungen konfigurierbar (2026-04-04)
- [x] MP3-Dateien für Auto-DJ, 7 GEMA-freie CC-Tracks vorinstalliert (2026-04-04)
- [x] "Now Playing" Song-Anzeige im Frontend, AutoDJ + Live-DJ Erkennung (2026-04-04)
- [x] Live-DJ Anzeige mit Name + Foto über "Jetzt live gehen" Button (2026-04-04)
- [x] Mini-Equalizer Animation im Hero-Badge (2026-04-04)
- [x] AutoDJ / LIVE Badge-Unterscheidung im Sticky Player (2026-04-04)
