# ViewIT Plugin Entwicklung (`addon/plugins/*_plugin.py`)

Diese Datei zeigt, wie Plugins im Projekt aufgebaut sind und wie sie mit dem Router zusammenarbeiten.

## Grundlagen
- Ein Plugin ist eine Python Datei in `addon/plugins/`.
- Dateien mit `_` Prefix werden nicht geladen.
- Plugin Klasse erbt von `BasisPlugin`.
- Optional: `Plugin = <Klasse>` als klarer Einstiegspunkt.

## Pflichtmethoden
Jedes Plugin implementiert:
- `async search_titles(query: str, progress_callback: Callable[[str, Optional[int]], Any] | None = None) -> list[str>`
- `seasons_for(title: str) -> list[str]`
- `episodes_for(title: str, season: str) -> list[str]`

## Wichtige optionale Methoden
- `capabilities()`
- `genres()`
- `popular_series()`
- `latest_episodes(page: int = 1)`
- `latest_titles(page: int = 1)`
- `titles_for_genre(genre: str)`
- `titles_for_genre_page(genre: str, page: int)`
- `titles_for_genre_group_page(...)` / `genre_has_more(...)` (Paging / Alphabet-Gruppen)
- `years_available()` / `titles_for_year(year, page)`
- `countries_available()` / `titles_for_country(country, page)`
- `collections()` / `titles_for_collection(collection, page)`
- `tags()` / `titles_for_tag(tag, page)`
- `random_title()`
- `stream_link_for(...)`
- `stream_link_for_url(...)`
- `available_hosters_for(...)`
- `available_hosters_for_url(...)`
- `episode_url_for(...)`
- `series_url_for_title(...)`
- `remember_series_url(...)`
- `metadata_for(...)`

## Film Provider Standard
Wenn keine echten Staffeln existieren:
- `seasons_for(title)` gibt `['Film']`
- `episodes_for(title, 'Film')` gibt `['Stream']`

## Capabilities
Ein Plugin kann Features melden ueber `capabilities()`.
Bekannte Werte:
- `popular_series`   – beliebte Serien/Filme verfügbar
- `genres`           – Genre-Navigation
- `latest_episodes`  – neu erschienene Episoden (`latest_episodes(page)`)
- `new_titles`       – neu hinzugefügte Titel (`latest_titles(page)`)
- `alpha`            – alphabetische Navigation
- `series_catalog`   – vollständiger Serienindex
- `year_filter`      – Filter nach Erscheinungsjahr (`years_available()`, `titles_for_year()`)
- `country_filter`   – Filter nach Produktionsland (`countries_available()`, `titles_for_country()`)
- `collections`      – Sammlungen/Filmreihen (`collections()`, `titles_for_collection()`)
- `tags`             – Schlagwort-Suche (`tags()`, `titles_for_tag()`)
- `random`           – zufälliger Titel (`random_title()`)

## Suche
Aktuelle Regeln fuer Suchtreffer:
- Match auf Titel
- Wortbasiert
- Keine Teilwort Treffer im selben Wort
- Beschreibungen nicht fuer Match nutzen

Siehe als Referenz:
- `addon/plugins/_template_plugin.py` (Minimal-Template)
- `addon/plugins/serienstream_plugin.py`
- `addon/plugins/aniworld_plugin.py`
- `addon/plugins/topstreamfilm_plugin.py`
- `addon/plugins/hdfilme_plugin.py`
- `addon/plugins/kkiste_plugin.py`
- `addon/plugins/moflix_plugin.py`
- `addon/plugins/netzkino_plugin.py`
- `addon/plugins/youtube_plugin.py`

## Settings
Pro Plugin meist `*_base_url`.
Beispiele:
- `serienstream_base_url`
- `aniworld_base_url`
- `einschalten_base_url`
- `topstream_base_url`
- `filmpalast_base_url`
- `doku_streams_base_url`
- `hdfilme_base_url`
- `kkiste_base_url`
- `moflix_base_url`
- `netzkino_base_url`

## Playback Flow
1. Episode oder Film auswaehlen.
2. Optional Hosterliste anzeigen.
3. `stream_link_for` oder `stream_link_for_url` aufrufen.
4. `resolve_stream_link` aufrufen.
5. Finale URL an Kodi geben.

## Logging
Nutze Helper aus `addon/plugin_helpers.py`:
- `log_url(...)`
- `dump_response_html(...)`
- `notify_url(...)`

## Build und Checks
- ZIP: `./scripts/build_kodi_zip.sh`
- Addon Ordner: `./scripts/build_install_addon.sh`
- Manifest: `python3 scripts/generate_plugin_manifest.py`
- Snapshot Checks: `python3 qa/run_plugin_snapshots.py`

## Kurze Checkliste
- `name` gesetzt und korrekt
- `*_base_url` in Settings vorhanden
- Suche liefert nur passende Titel
- Playback Methoden vorhanden
- Fehler und Timeouts behandelt
- Cache nur da, wo er Zeit spart