BilgymFlow — EduPage Integrácia

📖 Ako to funguje — vysvetlenie pre netech používateľa ▶

Čo je EduPage API?

EduPage je školský informačný systém, ktorý používate na zadávanie suplov, rozvrhov a pod. Existuje neoficiálna Python knižnica (edupage-api), ktorá vie:

Prihlásiť sa do EduPage ako bežný používateľ
Stiahnuť dáta (rozvrhy, suplovanie, triedy, učiteľov...)
Vrátiť tieto dáta vo forme čitateľnej pre počítač

Dôležité upozornenie: Toto NIE je oficiálne API od EduPage. Je to komunitou vytvorený nástroj, ktorý "číta" EduPage ako bežný prehliadač. Ak EduPage zmení svoju stránku, knižnica môže prestať fungovať.

3 systémy suplov — ako to teraz funguje

BilgymFlow má 3 zdroje dát pre suplovanie. Systém 3 (Python) je jeden z nich:

Systém 1 (GitHub Actions – HTML scraper) — beží každých 30 min, stiahne HTML stránku suplov z EduPage
Systém 2 (Node.js cez EduPage) — alternatívny zdroj, prihlásenie cez PHPSESSID cookie
Systém 3 (GitHub Actions – Python + edupage-api) — beží každú hodinu (+ extra ranné časy), používa edupage-api Python knižnicu

Prečo GitHub Actions a nie Azure?
Azure cloudu (kde bežia naše funkcie) EduPage server cslewis.edupage.org odmietne spojenie — Azure IP adresy sú blokované. GitHub Actions beží najprv cez Linux runner (rýchlejší). Ak ten tiež nedosiahne EduPage (napr. GitHub zmenil IP rozsahy), automaticky sa spustí záložný macOS runner — ten beží na Apple Silicon Macoch s inými IP adresami, ktoré EduPage neblokuje. Azure Function timery bežia paralelne ako ďalšia záloha.

Kedy sa Systém 3 (Python supl) spúšťa?

Primárne (GitHub Actions) — každý pracovný deň (Po–Pi):

Ranné časy: 6:30, 7:00, 7:30, 8:00 SELČ
Denné časy: 12:00, 16:00, 20:00 SELČ

Každý beh skúsi najprv Linux runner. Ak ten zlyhá (sieťová nedostupnosť), automaticky sa spustí macOS runner ako záloha.

Záloha (Azure Functions) — každý pracovný deň (Po–Pi), paralelne s GitHub Actions:

Ranné časy: 6:00, 6:30, 7:00, 7:30 SELČ (supl_timer_morning)
Denné časy: 8:00, 12:00, 16:00, 20:00 SELČ (supl_timer)

Azure beží z inej siete ako GitHub — ak Edupage zablokuje GitHub, Azure môže fungovať a naopak.

Ako funguje stiahnutie rozvrhu?

Existujú dva typy rozvrhov:

Bežný rozvrh (edupage-timetable-data.json) — sťahuje sa automaticky každý pracovný deň o 6:30–8:00 cez GitHub Actions (Python runner), ukladá sa do Azure Blob Storage a zobrazuje sa na tejto stránke v sekcii Rozvrhy.
Stály rozvrh (edupage-stable-rozvrh.json) — aktualizuje sa ručne vždy keď sa školský rozvrh zmení (nový semester, zmeny skupín). Ukladá sa do Azure Blob Storage a slúži na porovnanie s reálnym rozvrhom na stránke rozvrh.html.

1

O 6:30 SELČ sa spustí GitHub Actions workflow "Suplovanie – Python sync" (Linux runner).

2

Python skript sa prihlási do EduPage a stiahne rozvrh každého učiteľa (trvá ~3 min, 80+ učiteľov s pauzami 1,2 s medzi nimi).

3

Výsledok uloží do Azure Blob Storage (edupage-timetable-data.json).

4

Cez túto stránku môžete skontrolovať rozvrhy a nastaviť prepojenie učiteľov. Stály rozvrh aktualizujte manuálne cez skript fetch_stable_local.py (spustiť lokálne na Mac).

Ako otestovať GitHub Action manuálne?

Otvorte GitHub repozitár bilgymflow
Kliknite na záložku Actions
Vyberte workflow "Suplovanie – Python sync (EduPage API)"
Kliknite "Run workflow" vpravo hore → "Run workflow"
Po ~30 sekundách uvidíte výsledok (zelená = OK, červená = chyba)

Podmienka: musíte mať nastavené 4 GitHub Secrets (pozri sekciu Nastavenie nižšie).

Čo keď API prestane fungovať?

Ak EduPage zmení svoju stránku alebo knižnica prestane fungovať, posledné uložené dáta zostanú v systéme. Učitelia uvidia posledne stiahnutý rozvrh s upozornením o dátume aktualizácie. Suplovanie funguje nezávisle (systémy 1 a 2 pokračujú normálne).

📅 Harmonogram — kedy čo beží ▶

SELČ = Stredoeurópsky letný čas (UTC+2, apríl–október). V zime (CET, UTC+1) sú časy o 1 hodinu skôr.

Čas (SELČ)	Zdroj	Čo sa sťahuje	Poznámka
6:30–8:00	GitHub	Rozvrhy — všetci učitelia (~80), celý týždeň	Trvá ~3 min. Linux runner (rýchlejší). Azure timetable_timer nefunguje — Azure IP blokovanie zo strany EduPage.
6:30	GitHub	Suplovanie na dnes + rozvrh (ak Azure zlyhalo)	Linux runner; ak nedosiahne EduPage → macOS fallback (len o 7:00). Rozvrh len ak blob nie je aktuálny.
7:00, 7:30, 8:00	GitHub	Suplovanie na dnes + rozvrh (ak ešte stále zlyhalo)	Linux runner; macOS fallback len o 7:00. Po 8:00 sa rozvrh nekontroluje.
12:00	GitHub	Suplovanie na dnes (poludňajší update)	Linux runner + macOS fallback. EduPage môže pridávať zmeny počas dňa.
16:00	GitHub	Suplovanie na dnes (popoludňajší update)	Linux runner + macOS fallback.
20:00	GitHub	Suplovanie (večerný sync)	Linux runner + macOS fallback. EduPage môže mať zajtra zverejnené suplovanie.
6:00, 6:30, 7:00, 7:30	Azure	Suplovanie — ranná záloha (supl_timer_morning)	Paralelne s GitHub. Ak GHA nedosiahne EduPage, Azure pokryje ranné časy.
8:00, 12:00, 16:00, 20:00	Azure	Suplovanie — denná záloha (supl_timer)	Záloha pre prípad výpadku GitHub Actions. Beží z iných IP.

Čo sa stane ak Azure rozvrh o 6:00 zlyhá?
GitHub Actions o 6:30, 7:00, 7:30 a 8:00 automaticky skontrolujú, či je blob aktuálny. Ak nie → spustia plný rozvrh sync (trvá ~3 min). Ak aj GHA zlyhá, dostaneš email od GitHub (automatické notifikácie z Actions).

Ako vidieť, či to zlyhalo?
Na tejto stránke v sekcii "Rozvrh" uvidíš run_log s červenou chybou. Ak je blob starší ako 24h, zobrazí sa upozornenie.

Cena GitHub Actions: Pre súkromné repo máš 2 000 minút/mesiac zadarmo. Náš plán: 7 behov/deň × 30 dní × ~1 min/beh (Linux) = ~210 min/mesiac Linux. macOS runner (ak Linux zlyhá): 10× cena Linux minút, ale beží len výnimočne. Timetable fallback (ak beží): ~3 min/beh, max 5× mesačne = ~15 min extra. Celkom v normálnom stave: ~225 min → zadarmo v rámci free tieru.

⚙️ Nastavenie — požadované premenné prostredia ▶ Načítavam...

Pre správne fungovanie je potrebné nastaviť nasledovné premenné. Zelená = nakonfigurované, červená = chýbajú.

EDUPAGE_USERNAMEEduPage prihlasovací email (Python Function App — pre rozvrh)

SUPL_BLOB_SAS_URLSAS URL pre supl blob — Azure SWA nastavenia

TIMETABLE_BLOB_SAS_URLSAS URL pre rozvrh blob — Azure SWA nastavenia

STABLE_BLOB_SAS_URLSAS URL pre stály rozvrh blob (edupage-stable-rozvrh.json) — Azure SWA nastavenia

TIMETABLE_HTTP_TRIGGER_URLURL Python HTTP funkcie pre ručný sync — Azure SWA nastavenia

GitHub Secrets (pre Systém 3 supl sync cez GitHub Actions):
Nastavte v GitHub repozitáry: Settings → Secrets and variables → Actions → New repository secret

EDUPAGE_USERNAME — napr. jan.ban@cslewis.edupage.org
EDUPAGE_PASSWORD — heslo do EduPage
EDUPAGE_SUBDOMAIN — napr. cslewis (bez .edupage.org)
AZURE_STORAGE_CONNECTION_STRING — z Azure Portal → Storage Accounts → bilgymsupl → Access keys → skopírujte Connection string (nie samotný kľúč)

Ako nastaviť TIMETABLE_BLOB_SAS_URL:
1. Otvor Azure Portal → Storage Accounts → bilgymsupl → Containers → edupage-cache
2. Nájdi súbor edupage-timetable-data.json (po prvom behu ho tam bude Python funkcia)
3. Klikni na tri bodky → Generate SAS → nastav oprávnenia: Read, platnosť 1–2 roky → Create
4. Skopíruj Blob SAS URL a ulož do Azure Static Web App → Configuration → Application settings ako TIMETABLE_BLOB_SAS_URL

Ako nastaviť TIMETABLE_HTTP_TRIGGER_URL:
1. Otvor Azure Portal → Function Apps → bilgym-supl-py → Functions → timetable_http
2. Klikni na Get Function URL → Function key → Copy
3. Ulož celú URL (vrátane ?code=...) do Azure SWA nastavení ako TIMETABLE_HTTP_TRIGGER_URL

🟢 Stav systému — posledné behy EduPage API Načítavam... ▶

Načítavam stav...

🔄 Suplovanie — debug log a dáta (Systém 3 / Python) ▶ Načítavam...

Načítavam supl blob...

🖥 Spustiť stiahnutie suplovanie — lokálne (z tvojho Macu)

Zisťujem…

Vyžaduje spustený local_server.py na tvojom Macu. Trvá ~30 sek. Výsledok uvidíš v termináli.

🔍 Live suplovanie debug (rovnaký výstup ako na dashboarde)

👁 Náhľad suplov — čo vidia jednotliví učitelia →

Ukáže presne, čo každý učiteľ vidí na svojom dashboarde (suplovanie widget).

📅 Rozvrhy — stiahnuté z EduPage (overovanie) ▶ Načítavam...

Poznámka: Stiahnutie trvá ~2–3 minúty (80+ učiteľov). Po kliknutí počkajte a potom stránku refreshujte — dáta sa aktualizujú v blob úložisku.

Načítavam rozvrhy z blobu...

🔗 Mapovanie identít — EduPage ↔ BilgymFlow učitelia ▶ Načítavam...

Čo je mapovanie identít?

EduPage má svojich interných ID pre učiteľov (napr. číslo 1234). BilgymFlow má vlastné ID učiteľov. Aby sme vedeli zobraziť "rozvrh učiteľa Nováka z EduPage" na karte učiteľa Nováka v BilgymFlow, musíme vedieť, že "EduPage ID 1234 = BilgymFlow učiteľ abc-xyz".

Toto mapovanie sa robí raz ručne na tejto stránke. Potom funguje automaticky.

Načítavam mapovanie...