feat: implement automated data scraping and history generation pipeline for PVL reservoir levels

docs/pvl_data_sources.md

@@ -0,0 +1,44 @@
+# Analýza dostupných dat z Povodí Vltavy (PVL.cz)
+
+Tento dokument sumarizuje všechna data, která jsme schopni strojově získat z webových stránek Povodí Vltavy pro jednotlivé vodní nádrže (např. z adresy `Mereni.aspx?oid=1&id=VLL1`).
+
+Data jsou na zdrojovém backendu rozdělena do několika logických celků (tabulek), které můžeme libovolně vytěžovat.
+
+## 1. Technické parametry nádrže (Základní údaje)
+Tato data jsou statická a definují fyzické a inženýrské limity přehrady.
+
+* **Tok (River):** Na jaké řece se nádrž nachází (např. Vltava).
+* **Koruna hráze:** Absolutní nadmořská výška nejvyššího bodu hráze [m n.m.].
+* **Kóta přelivu:** Výška přelivových hran [m n.m.].
+* **Maximální retenční hladina:** Krizová úroveň nadržení při povodních [m n.m.].
+* **Hladina zásobního prostoru:** Maximální běžná hladina, pro kterou je určen zásobní objem [m n.m.].
+* **Hladina stálého nadržení:** Minimální hladina nutná pro zachování ekologických a technických funkcí [m n.m.] (lze využít pro přesný výpočet procentuální naplněnosti).
+* **Výškový systém:** Zpravidla "Balt p.v." (Baltský po vyrovnání).
+
+## 2. Aktuální hodnoty (Real-time data)
+Tato tabulka obsahuje nejčerstvější data z měřicích stanic s přesným časovým razítkem. Ne všechny hodnoty musí být vždy u všech přehrad dostupné.
+
+* **Časové razítko:** Přesný čas posledního měření (např. *05.06.2026 22:10*).
+* **Hladina vody v nádrži:** Aktuální výška [m n.m.].
+* **Objem:** Skutečný aktuální zadržovaný objem vody [mil. m³].
+* **Přítok (Inflow):** Odhadovaný/měřený přítok do přehrady [m³/s].
+* **Odtok (Outflow):** Skutečný odtok z přehrady [m³/s].
+* **Srážky (24h):** Úhrn srážek za posledních 24 hodin [mm] *(k dispozici pouze u vybraných stanic)*.
+* **Teplota vzduchu:** Aktuální teplota vzduchu [°C] *(k dispozici pouze u vybraných stanic)*.
+
+## 3. Historická časová řada (Tabulka měření)
+Tyto tabulky obsahují historický vývoj po jednotlivých hodinách za posledních několik dnů, což využíváme pro vykreslování grafů.
+
+* **Datum a čas:** Hodinové intervaly (např. *05.06.2026 22:00*).
+* **Hladina:** Měřená výška hladiny [m n.m.].
+* **Odtok:** Odtok přes hráz [m³/s].
+* *(Poznámka: Přítok a Objem se do historické tabulky u většiny přehrad ze strany PVL neukládají, zveřejňují pouze hladinu a odtok).*
+* **QN:** Indikátor kvality dat (ověřená/neověřená).
+
+---
+
+### Možnosti budoucího rozšíření HLADINATORu
+Na základě výše zmíněných dostupných bodů můžeme do aplikace snadno přidat:
+1. **Srážky a teplotu** - Pokud je pro danou přehradu údaj dostupný, můžeme přidat widget pro zobrazení úhrnu srážek za 24h a aktuální teploty vzduchu.
+2. **Přesnější výpočet %** - Pomocí limitů "Maximální retenční hladina" a "Hladina stálého nadržení" můžeme přesně indikovat blížící se povodňový stav.
+3. **Výstražný systém (Alerts)** - Vizuální varování (např. změna barvy panelu na červenou), pokud se aktuální hladina nebezpečně blíží kótě přelivu.