# Quest Arena – výzvy, soutěže a odznaky

Tato kapitola popisuje motivační modul **Quest Arena**, který v hlavním menu najdete pod položkou **Quest Arena**.

> **Poznámka k názvům:** V menu je zkrácený název **Quest Arena**. Po otevření stránky pracujete s plným názvem **Quest Arena – výzvy, soutěže, odznaky**. Archiv historických odznaků je na samostatné stránce **Archiv odznaků** (`/odznaky/archiv`).

## K čemu Quest Arena slouží

Quest Arena je motivační vrstva nad běžnými školními daty. Nezaměňujte ji s klasickými žebříčky na stránce **Žebříčky a statistiky** — ty popisuje [05-zebricky-statistiky.md](05-zebricky-statistiky.md).

Modul řeší:

- **výzvy** — cíle pro žáky, třídy nebo školy,
- **soutěže** — ligy, poháry a výsledkové režimy (republikové, krajské, třídní…),
- **odznaky** — odměny za splněné podmínky,
- **výsledkový servis** — bonusové žebříčky, tabule, vyhodnocení a tisky,
- **katalog** — předpřipravené šablony výzev, soutěží a odznaků.

## Kde modul najdete

1. Přihlaste se do správné školy.
2. Zkontrolujte aktivní školní rok v horní liště.
3. V hlavním menu otevřete **Quest Arena**.

U položek menu s novým obsahem se může zobrazit badge **Novinky** — po otevření modulu se označí jako přečtené (viz [02-prvni-kroky.md](02-prvni-kroky.md#novinky-a-news-feed)).

## Přehled obrazovky

### Dashboard (horní karusel)

Po otevření stránky uvidíte souhrnné karty v karuselu. Kliknutím na kartu otevřete detailní modal. Typické metriky:

| Karta | Co ukazuje |
|-------|------------|
| Vypsané výzvy / soutěže / odznaky | Počet aktivních kampaní |
| Mistr výzev / soutěží / odznaků | Žák s nejvyšším počtem bodů nebo odznaků |
| Quest Master | Žák s nejvíce výhrami |
| Quest TOP třída | Třída s nejvyšším průměrem quest výher na žáka |
| Point Hunter | Nejvíce bonusových bodů |
| TOP třída výzev / soutěží / odznaků | Nejúspěšnější třída v dané kategorii |

Karusel listujte šipkami nebo tečkami pod kartami. Poslední přepočet metrik je uveden v info boxu ℹ️ u nadpisu stránky.

### Hlavní přepínač (tři skupiny)

Pod dashboardem je dvoustupňová navigace:

1. **Výzvy** | **Soutěže** | **Odznaky** — hlavní skupina
2. Podskupina podle vybrané skupiny (viz tabulka níže)

| Skupina | Záložky | Účel |
|---------|---------|------|
| **Výzvy** | Výsledkový servis, Aktivní výzvy, Katalog výzev* | Přehled, správa a výsledky výzev |
| **Soutěže** | Výsledkový servis, Aktivní soutěže, Katalog soutěží* | Ligy, poháry, pořadí |
| **Odznaky** | Výsledkový servis, Aktivní odznaky, Katalog odznaků | Odměny a jejich přehled |

\* Katalog vidí jen role s oprávněním spravovat kampaně (`can_manage_manual_challenges`).

## Výsledkový servis

**Výsledkový servis** je samostatná část uvnitř každé skupiny. Slouží pro sledování pořadí, bonusových bodů, tabulí a tisků — ne pro zakládání nových kampaní.

### Výzvy — výsledkový servis

Typické podsekce:

- **Bonusový žebříček** — body z výzev,
- **Tabule** — přehledová tabule výsledků,
- **Moje výzvy** — výzvy přihlášeného uživatele / žáka,
- **Třídní výzvy** — výzvy v kontextu třídy,
- **Meziškolní výzvy** — širší scope napříč školami.

Filtry žáka, třídy, školy a školního roku nastavujete přímo v dané sekci.

### Soutěže — výsledkový servis

Soutěže v katalogu lze vypsat jako **ligu** nebo **pohár**. Výsledkový servis soutěží zahrnuje:

- **Bonusový žebříček soutěží**,
- **Výsledky** — pořadí a podium,
- **Moje soutěže**, **Soutěže třídy**, **Školní soutěže**, **Meziškolní soutěže**.

Důležité pravidlo: běžné výkonové žebříčky soutěží započítávají jen **regular disciplíny** (standardní sportovní disciplíny školy). Bonusové, penalizační nebo interní disciplíny se do soutěžního bodování nepočítají.

**Grand Prix** (Závěrečná Grand Prix) počítá jen body ze **soutěží**, ne z výzev.

Typy soutěžního scope v katalogu:

| Scope | Význam |
|-------|--------|
| **Republikové** | Celostátní / školní srovnání |
| **Krajské** | Filtrovatelné podle kraje |
| **Třídní** | Srovnání v rámci třídy (např. Třída zlepšovatelů) |
| **Progress** | Meziroční zlepšení výkonů |

U krajských soutěží lze ve výsledkovém modálu filtrovat **Kraj**. Odměny jsou standardně pro **první 3 místa**.

### Odznaky — výsledkový servis

Podsekce podle scope:

- **Moje odznaky** — odznaky přihlášeného žáka,
- **Žákovské odznaky** — přehled podle žáků,
- **Třídní přehled** — odznaky v třídě,
- **Školní odznaky** — celoškolský přehled.

U tabulek používejte ikony **📊** (grafy), **ℹ️** (vysvětlení) a **🖨️** (tisk).

## Aktivní výzvy, soutěže a odznaky

Záložka **Aktivní výzvy / soutěže / odznaky** ukazuje právě vypsané kampaně. U každé karty typicky uvidíte:

- název a popis,
- stav (aktivní / ukončená),
- počet účastníků a průběh plnění,
- akce podle role (úprava, archivace, vyhodnocení, zápis účastníků).

Učitel nebo admin s oprávněním může:

- ručně vypsat novou výzvu, soutěž nebo odznak,
- upravit / duplikovat / archivovat existující položku,
- vyhodnotit výzvu a udělit odměny,
- zapisovat účastníky do katalogových položek.

## Zápis účastníků (enrollment)

Účastníky řešíte z karty **Aktivní výzvy / soutěže** nebo z katalogové karty tlačítkem **Zapsat účastníky**. Otevře se modal se stejnou logikou pro výzvy i soutěže.

### Postup pro učitele / admina

1. Otevřete **Quest Arena** → skupina **Výzvy** nebo **Soutěže** → **Aktivní…** (nebo **Katalog**).
2. U karty klikněte **Zapsat účastníky**.
3. Volitelně nastavte **Termín od / Termín do** (účast v daném intervalu).
4. Filtry: škola (superadmin), třída, hledání — typicky 4 filtrační pole.
5. Přesuňte žáky ze seznamu dostupných do vybraných (dual-list).
6. Uložte.

**Zpětný zápis:** u ukončené / uzavřené kampaně může být zápis účastníků stále dostupný (tooltip „Zpětný zápis…“) — slouží k dočištění evidence po termínu.

### Žákovský self-join

Pokud je výzva otevřená pro samozápis, žák na kartě aktivní výzvy vidí:

- **Zapojit se do výzvy**, nebo
- **Odhlásit se z výzvy** (pokud už je zapsaný).

Žák nevidí katalogovou správu ani hromadný enrollment modal.

## Režimy vyhodnocení (stručně)

| Režim | Co to znamená pro učitele |
|-------|---------------------------|
| **Automatické** | Backend spočítá metriku z výkonů / rekordů / teacher benchmarků a doplní splnění |
| **Ruční skóre** | Např. Sportovní kvíz — zadáte body per účastník; odměna = dosažené skóre nad prahem |
| **Teacher benchmark** („Poraž učitele“) | Nejprve nastavte školní benchmarky disciplín v evaluačním modalu, pak auto porovnání |
| **Měsíční ruleta** | Disciplína se losuje na měsíc školního roku; vyhodnocení jen v této disciplíně |

Automatické vyhodnocení používejte tam, kde je výsledek objektivně v datech. Ruční jen tam, kde backend metriku nemá (např. offline kvíz).

## Měsíční ruleta

Katalogová výzva **Měsíční ruleta** (`student_monthly_roulette`):

1. VyPište ji z **Katalogu výzev** (nebo ověřte, že už je aktivní).
2. Systém drží **jeden los disciplíny na školu + školní rok + měsíc**.
3. V evaluačním modalu vyberte měsíc — zobrazí se vylosovaná disciplína.
4. Plnění se počítá z výkonů v této disciplíně za daný měsíc (ne „libovolná disciplína“).

Legacy alias `student_weekly_roulette` zůstává jen v backendu pro stará vypsání; v UI pracujte s **Měsíční ruletou**.

## Katalog

Katalog obsahuje předpřipravené šablony. Oprávněné role mohou:

- **vypsat** jednotlivou položku z katalogu,
- **vypsat všechny** položky najednou,
- **odepsat všechny** aktivní katalogové položky (hromadná deaktivace).

V katalogu soutěží se nové položky vytvářejí jako **liga** nebo **pohár**. Po vypsání z katalogu se položka objeví v **Aktivních soutěžích** a ve **Výsledkovém servisu**.

## Archiv odznaků

Historicky získané odznaky najdete na stránce **Archiv odznaků**. Užitečné pro:

- kontrolu, co už bylo přiděleno,
- filtrování podle scope, disciplíny nebo typu,
- export archivního přehledu.

## Quest Arena žebříčky (stránka Žebříčky)

Na stránce **Žebříčky a statistiky** jsou navíc dvě sekce navázané na Quest Arenu:

- **Výzvy a soutěže** — souhrnné žebříčky quest kontextu,
- **Žebříček odznaků** — pořadí podle získaných odznaků.

Detail popisuje [05-zebricky-statistiky.md](05-zebricky-statistiky.md#quest-arena-žebříčky). Správu kampaní a vyhodnocení řešte v Quest Areně, ne v klasických žebříčcích.

## Role a oprávnění

| Role | Typický přístup |
|------|-----------------|
| **Žák** (`zak` / `reader`) | Moje výzvy, odznaky, výsledky; bez správy katalogu |
| **Učitel** (`editor`) | Přehled tříd, vyhodnocení, zápis účastníků dle oprávnění |
| **Admin školy** (`admin`) | Správa kampaní, katalog, širší školní kontext |
| **Superadmin** | Agregovaná data napříč školami; škola v horní liště omezuje celou stránku |

Ruční vypsání výzvy, soutěže nebo odznaku, práce s katalogem a automatické vyhodnocení vyžadují odpovídající oprávnění. Detail rolí: [roles.md](roles.md).

## Doporučený workflow pro učitele

1. Otevřete **Quest Arena**.
2. Zkontrolujte dashboard — kolik je aktivních kampaní.
3. Přepněte na **Výzvy**, **Soutěže** nebo **Odznaky** podle cíle.
4. V **Aktivních** položkách ověřte účastníky a stav plnění.
5. Ve **Výsledkovém servisu** zkontrolujte pořadí a případně vytiskněte tabuli.
6. Pro odměny a historii otevřete **Odznaky** nebo **Archiv odznaků**.

Prakticky nejčastěji po zadání výkonů nebo při průběžné motivaci žáků.

## Rozdíl: Quest Arena vs. klasické žebříčky

| Oblast | Kde | Co řeší |
|--------|-----|---------|
| Klasické žebříčky | Žebříčky a statistiky | Bodové pořadí, rekordy, statistiky výkonů |
| Quest Arena | Menu Quest Arena | Kampaně, katalog, odměny, výsledkový servis |
| QA žebříčky | Žebříčky → Výzvy a soutěže / Žebříček odznaků | Souhrnná pořadí quest kontextu |

## Nejčastější situace

### Nevidím žádné výzvy nebo soutěže

- zkontrolujte školní rok,
- zkontrolujte filtry v dané sekci,
- ověřte, že ve škole existují vypsané kampaně (nebo je vyvolejte z katalogu),
- ověřte oprávnění role.

### Odznak se nezobrazuje

- ověřte splnění podmínek (někdy proběhne automatický přepočet se zpožděním),
- zkontrolujte filtr typu odznaku nebo disciplíny,
- starší odměny hledejte v **Archivu odznaků**.

### Potřebuji výsledkové pořadí soutěže

Použijte **Výsledkový servis** v Quest Areně (skupina Soutěže), ne klasický bodový žebříček. U lig a pohárů hledejte podium a bonusový žebříček soutěží.

### Vidím dvě stejné karty v aktivním přehledu

U beztermínových katalogových položek může existovat živé vypsání ve více školních rocích. Aktivní přehled zobrazuje jen jednu kartu na katalogový klíč — pokud vidíte duplicitu, zkontrolujte filtr školního roku.

### Jak zapsat účastníky / žák se chce zapojit sám

- Učitel/admin: tlačítko **Zapsat účastníky** na kartě → filtry + dual-list (viz sekce [Zápis účastníků](#zápis-účastníků-enrollment)).
- Žák: **Zapojit se do výzvy** / **Odhlásit se z výzvy** na kartě, pokud je self-join povolený.
- Po termínu: zpětný zápis může být stále dostupný u uzavřených kampaní.

### Měsíční ruleta — špatná disciplína

Los je vázaný na školu, školní rok a měsíc. V evaluačním modalu zvolte správný měsíc; disciplína se nemění ručně „ad hoc“ mimo los.

### Stránka se načítá po částech

Quest Arena načítá některé sekce lazy (fragmenty přes AJAX). Po přepnutí záložky může krátce trvat, než se obsah doplní — to je očekávané chování.

## Viz také

- [02-prvni-kroky.md](02-prvni-kroky.md) — navigace, nastavení, novinky
- [05-zebricky-statistiky.md](05-zebricky-statistiky.md) — klasické žebříčky a QA sekce
- [teacher-guide.md](teacher-guide.md) — denní workflow učitele
- [reports.md](reports.md) — exporty a tisky