# Žánrový prohlížeč — plan of record

Stav: **G1–G4 postavené 2026-10-27. G7 (kvalita výpisu + služby v ČR + cache) postaveno 2026-10-29, G8 (kvalita všude) postaveno 2026-10-29; obojí čeká na test Standy.** Necommitováno, nenasazeno. Všechna rozhodnutí se Standou jsou v `900-decisions.md`.
Agent čte `AGENTS.md`, tento soubor, pak kapitolu své fáze. Otevřené detaily (výchozí hodnoty, přesný seznam
zemí, ladění filtru) **rozhoduje implementující agent sám** na základě headless testů a zapíše je do
`900-decisions.md`. Standy se ptá až při předání (číslovaný testovací checklist).

## Cíl
Uživatel v Pro tebe listuje žánry a v nich **všechny** filmy/seriály, filtruje rokem a zemí původu,
řazeno od nejnovějších do absolutní minulosti, bez ztráty známých titulů. Nahrazuje staré nevyhovující
žánrové složky (ty zůstanou skryté, nemazat).

## Zdroje — fáze
| # | Fáze | Stav | Kapitola |
|---|------|------|----------|
| G1 | TMDB: data, filtry, stránkování, cache, řádky | hotovo | `010-tmdb-engine.md` |
| G2 | Skin: sekce Žánry v Pro tebe + podstránka žánru, widget manager | hotovo | `020-skin.md` |
| G3 | Nastavení, progres, výchozí hodnoty z headless testů | hotovo | `030-settings-progress.md` |
| G4 | Ověření + předání | čeká na Standu | `040-verification.md` |
| G7 | Kvalita výpisu (filtr Původ), služby v ČR (scoring, loga, řádek), texty, jednotná cache | **postaveno, čeká na test** | `070` pravidla, `080` cache, `090` postup + testy; měření `060`, `data/` |
| G8 | Kvalita TMDB napříč doplňkem a skinem: modul `wcs/quality`, nastavení Kvalita návrhů | **postaveno, čeká na test** | `900` kolo 7, G8 |
| G5 | ČSFD scraper (žánry, výpis dle data, země) + cache | později | `050-future-csfd.md` |
| G6 | Sloučení TMDB + ČSFD | později | `050-future-csfd.md` |

G1–G3 se staví v pořadí, každá fáze s offline testy; G4 končí testem Standy.

## Co uživatel vidí
**Pro tebe → řádek Žánry**
- Textové karty (bez obrázků), stejný vzhled jako žánrové karty na stránce Filmy.
- Řídí se hero přepínačem Pro tebe (Vše / Filmy / Seriály; Vše = sloučené žánry).
- Nahoře „moje“ žánry podle scoringu z profilu Pro tebe (knihovna, zhlédnuté, 👍), potom ostatní.
- TV-only žánry (Kids, News, Reality, Soap, Talk) defaultně skryté.

**Klik na žánr → podstránka žánru** (layout jako detail filmu, nové rozložení)
- Hero: název žánru.
- Hero tlačítka (konzistentní s `docs/plan/skin-milionar/220-hero-buttons.md`):
  Typ (Filmy / Seriály / Oboje), Rok (Vše + jednotlivé roky), Země (Vše + nejvíce produkující země),
  Řazení (Datum default / Hodnocení / Popularita), Výběr (Vše / Doporučené default / Top — viz 010).
  Default: Vše roky, Vše země, Datum sestupně.
- Řádky (widgety, plně ve widget manageru 1123 — zapnout, pořadí, nastavení):
  1. **Výpis** — skutečný výpis všech položek dle filtrů; **jediný stránkovaný**;
     stránkování ručně na konci/začátku řádku (karta Další / Předchozí stránka, ikony Kodi, „Strana X“).
  2. Doporučeno pro tebe — engine Pro tebe, ověřeno na Webshare.
  3. Populární teď.
  4. Nejlépe hodnocené.
  5. Skryté klenoty.
  6. Nejlepší z desetiletí — jeden widget na dekádu (2020s … 1950s, Starší), ve widget manageru.

## Závazná pravidla
- **Nikdy čekání bez informace:** načítání Pro tebe, podstránky žánru, stránky výpisu i ověřování Webshare
  vždy ukazuje oficiální Kodi progres (`xbmcgui.DialogProgressBG`, jako `wcs/skin/installer.py:344`)
  s jasným postupem (co se načítá, kolik hotovo). Platí i pro stávající načítání Pro tebe.
- Konzistence: design, karty, hero tlačítka, managery jako zbytek skinu; zarovnané hrany, stejné mezery.
- Všechno nastavitelné, rozumné defaulty z testů; nastavení nepřepisovat v kódu, jen defaulty.
- Překlady cs/sk/en (i nepřeložené TV žánry TMDB).
- Zachovat stávající chování mimo dotčené části. Ikony jen Kodi, žádné vlastní kreslené.
- Klíče z userdata nikdy nevypisovat.

## Postup práce (pořadí)
1. Přečíst kontext níže, stávající žánry (`wcs/router.py:684-697` akce `tmdb_browse_genres`,
   `tmdb_browse_series_genres`, `tmdb_combo_genres`; `wcs/metadata/TMDbClient.py:136,361`; `wcs/ui/UI.py:785`).
2. G1 `wcs/genres/` + unit testy → 3. headless měření defaultů (030) → 4. nastavení + progres (030)
   → 5. G2 skin + endpointy → 6. ověření v Kodi (040) → 7. checklist Standovi.
Po každém kroku aktualizovat sekci Průběh.

## Kontext pro agenta
- Skilly: `kodi-skin`, `kodi-ui`, `kodi-harness`, `kodi-debug`, `test-tmdb`.
- Plány: `docs/plan/pro-tebe/*` (engine, dostupnost Webshare, skin, feedback), `docs/plan/skin-milionar/200-detail.md`,
  `220-hero-buttons.md`, `170-context-manager.md`, `240-modern.md`.
- Widget manager = okno 1123 (`resources/skin.milionar/xml/Custom_1123_MilionarRows.xml`).
- Pro tebe kód: `wcs/foryou/` (engine, score, features, availability, widgets, service).
- Stávající filtr zemí v doplňku **neexistuje** (ověřeno grepem) — vytvořit nový, sjednocený.
- Paměť projektu: jen požadované UI změny, ikony Kodi, cílené testy (ne celý baseline), testovat v Kodi sám
  přes dočasný harness a pak vrátit, sdílené Kodi s druhou session (před klávesami ověřit idle),
  přesný číslovaný checklist při předání, skin kopie přes `sync_dev.sh`.

## Pasti
- TMDB strop 500 stran → kurzor po datech, ne čísla stran.
- `include_adult=false` vždy; bez budoucích titulů (`.lte` = dnes).
- Film v discover nemá `origin_country` (TV ano) — filtrovat serverem, badge země jen z detailu/cache.
- TV žánry TMDB nejsou v cs přeložené.
- S klientským filtrem není znám celkový počet stran → label „Strana X“ (případně odhad, agent rozhodne).
- Duplicity: vedlejší řádky podstránky se mezi sebou neopakují (jako Pro tebe); Výpis je úplný.
- cs-CZ názvy/popisy, fallback en-US, když chybí.
- Zdrojová vrstva oddělená (`source = tmdb`), aby šlo připojit ČSFD a sloučení bez přepisu UI (050).

## Kde to je (2026-10-27)
| Část | Soubory |
|------|---------|
| Žánry, scoring | `wcs/genres/catalog.py`; snapshot Pro tebe `genre_sources` (`wcs/foryou/engine.py`) |
| Kvalita (Původ, posouzení, globální nastavení) | `wcs/quality/rules.py`, `settings.py`, `lists.py` (čistá logika) |
| Kurzor, volby | `wcs/genres/cursor.py`, `options.py` (čistá logika, bez Kodi) |
| Zdroj TMDB | `wcs/genres/tmdb.py` (rozhraní pro budoucí ČSFD) |
| Postranní řádky | `wcs/genres/rows.py` |
| Podstránka (načtení, filtry, stránky, Zpět, progres) | `wcs/genres/page.py`, `progress.py`, `settings.py`, akce `genre_*` v `wcs/skin/local.py` |
| Řádky (cache-only) | `wcs/genres/widgets.py` (`fy_genres`, `gn_*` přes `rows.run`) |
| Skin | `scripts/skin_harness/gen_genre.py` → `Includes_MilionarGenre.xml`; karta plakátu (ikona, badge) v `gen_cinema.py`; `Home.xml`, `Includes.xml`, `SkinSettings.xml` (Widgety: Stránka žánru) |
| Widget manager | sekce `genre` a řádek `fy_genres` v `wcs/skin/slots.py` (volby řádku = `mil.<sec>.<n>.opts`) |
| Nastavení doplňku | TMDb → Žánry (`genre_ttl_*`, `genre_requests_per_page`) |
| Testy | `scripts/library_harness/test_genres.py` (20), harness `scripts/genre_harness/genre_harness.py` |

## Průběh
- 2026-10-29: G7 postaveno a ověřeno (unit `test_services` 14, `test_genres`, harness quality, live Kodi: stránka
  žánru, štítky, řádek Teď na službách, detail). Necommitováno, nenasazeno.
- 2026-10-29: vada výpisu (smetí, čtverečky, prázdné hero) potvrzena headless i v Kodi; 5 kol diskuze se Standou,
  testy TMDB (`scripts/genre_harness/tmdb_probe.py` → `data/tmdb-probe.json`); G7 naplánováno (070–090).
- 2026-10-27: plán hotový.
- 2026-10-27: G1–G4 postavené. Offline: `test_genres` 20/20, dotčené sady (cinema, detail, modern, foryou, slots,
  clicks, refresh) zelené kromě 4 selhání, která patří k už dřív rozpracovanému stromu (výchozí řádky Filmů,
  počty slotů v refresh, navigace v onload). Headless měření a rozhodnutí: `900-decisions.md` (body 1–24, kurzor až do nejstaršího titulu bez duplicit a děr).
  Kodi 21.3 (modern skin, 2560×1440): řádek Žánry v Pro tebe, otevření z karty a Zpět na stejnou kartu, hero +
  6 tlačítek, 6 řádků, Další/Předchozí stránka s fokusem na první titul, Rok 1985, Typ Filmy (menu nad tlačítky),
  detail filmu z podstránky a Zpět, progres načítání, widget manager sekce `genre` s volbami Výběru.
  Neověřeno živě: karta „Nic nenalezeno“ (jen unit test), klasický vzhled (stejné šablony), Země (stejný kód jako Rok).
  Standův slot 7 Pro tebe vrácen na „vypnuto“; sekce `genre` dostala výchozí řádky (seed při prvním otevření).
