@golemio/chmu 1.1.1-dev.2644315801 → 1.1.1-dev.2644362300

package/docs/implementation_documentation.md

@@ -2,62 +2,120 @@
 
 ## Záměr
 
-Modul slouží ke stažení chmu dat z ftp agregovaných po hodině do csv souborů.
+Modul slouží ke stažení ČHMÚ meteorologických dat ze dvou zdrojů:
+
+- **FTP pipeline** - hodinová CSV data z interního FTP (`data_source = 'ftp'`)
+- **Opendata pipeline** - desetiminutová JSON data z veřejného ČHMÚ opendata API (`data_source = 'opendata'`)
+
+Data z obou zdrojů se ukládají do stejné tabulky `chmu.measurements` pomocí UPSERT (PK: `measured_at`, `station_id`, `data_source`).
 
 ## Vstupní data
 
 ### Data aktivně stahujeme
 
-Popis dat, jak je pomocí cronu a integration-engine stahujeme. Pokud jsou data stahována z více zdrojů, každý zdroj je popsán zvlášť.
-
-#### *ChmuDatasource*
+#### *ChmuDatasource* (FTP)
 
 - zdroj dat
-  - golemio ftp
+  - golemio FTP
 - formát dat
-  - csv soubor
-  - [validační schéma: ](https://gitlab.com/operator-ict/golemio/code/modules/chmu/-/blob/development/src/schema-definitions/datasources/ChmuSchemaProvider.ts)
+  - CSV soubor, oddělovač `;`, kódování UTF-8
+  - [validační schéma](https://gitlab.com/operator-ict/golemio/code/modules/chmu/-/blob/development/src/schema-definitions/datasources/ChmuSchemaProvider.ts)
   - [příklad vstupních dat](https://gitlab.com/operator-ict/golemio/code/modules/chmu/-/blob/development/test/data/6443_2023020215.txt)
 - frekvence stahování
   - jednou za hodinu
-- název rabbitmq fronty
+- název RabbitMQ fronty
   - `chmu.downloadMeasurementsTask`
 
-## Zpracování dat / transformace
+#### *OpendataDatasource* (opendata)
 
-Popis transformace a případného obohacení dat. Zaměřeno hlavně na workery a jejich metody.
+- zdroj dat
+  - ČHMÚ opendata
+  - URL: `https://opendata.chmi.cz/meteorology/climate/now/data/10m-{WSI}-{YYYYMMDD}.json`
+  - soubor pokrývá celý den; každou hodinu přibývají nové záznamy za uplynulou hodinu
+- formát dat
+  - JSON, long-format záznamy: `[STATION, ELEMENT, DT, VAL, FLAG, QUALITY]`
+  - FLAG: kód podmínky pro zvláštní meteorologické situace (např. `"V"`, `"A"`); typicky `""`
+  - QUALITY: `0.0` = dobrá, `1.0` = podezřelá, `2.0` = nízká kvalita, `3.0` = odhadnutá, `4.0` = chybějící, `5.0` = neznámá
+  - VAL: číselná hodnota, nebo `""` při chybějícím měření (QUALITY = 4.0)
+  - DT ve formátu ISO 8601 UTC (`2026-06-25T10:00:00Z`)
+- frekvence stahování
+  - jednou denně (soubor pokrývá celý předchozí den)
+- název RabbitMQ fronty
+  - `chmu.downloadOpendataMeasurementsTask`
+- poznámka
+  - Zpracovány jsou pouze stanice s vyplněným sloupcem `wsi` v `chmu.stations`; ostatní jsou přeskočeny.
 
-### *ChmuWorker*
+## Zpracování dat / transformace
 
-Stručný popis workeru.
+### *ChmuWorker*
 
-#### *DownloadMeasurementsTask*
+#### *DownloadMeasurementsTask* (FTP)
 
-- vstupní rabbitmq fronta
-  - název `chmu.downloadMeasurementsTask`
-  - parametry `from` and `to` volitelné parametry v iso formátu
+- vstupní RabbitMQ fronta
+  - `chmu.downloadMeasurementsTask`
+  - parametry `from` a `to` - volitelné ISO 8601 timestampy; bez parametrů stáhne aktuální hodinu; s rozsahem generuje subtasky po hodinách
 - datové zdroje
-  - `ChmuDatasource`
+  - `ChmuDatasource` - stáhne hodinový CSV soubor z FTP
 - transformace
-  - odkaz na transformaci dat, případně stručný popis tranformace
-  - [transformace dat](https://gitlab.com/operator-ict/golemio/code/modules/chmu/-/blob/development/src/integration-engine/transformations/MeasurementsTransformation.ts)
+  - [MeasurementsTransformation](https://gitlab.com/operator-ict/golemio/code/modules/chmu/-/blob/development/src/integration-engine/transformations/MeasurementsTransformation.ts)
+  - mapování CSV polí na DB sloupce, převod desetinné čárky, `data_source = 'ftp'`
 - data modely
   - [MeasurementModel](https://gitlab.com/operator-ict/golemio/code/modules/chmu/-/blob/development/src/schema-definitions/definitions/models/MeasurementModel.ts)
 
+#### *DownloadOpendataMeasurementsTask* (opendata)
+
+- vstupní RabbitMQ fronta
+  - `chmu.downloadOpendataMeasurementsTask`
+  - parametr `date` - volitelný ISO 8601 datum; bez parametru stáhne aktuální den
+- tok zpracování
+  1. `StationsRepository` - načte stanice s vyplněným WSI z `chmu.stations`
+  2. `OpendataDatasource` - pro každou stanici stáhne denní 10m JSON soubor
+  3. Přiřazení `station_id` dle WSI -> `station_id` mappingu
+  4. `OpendataMeasurementsTransformation` - pivot long->wide; skupinování dle `(station_id, DT)`; `data_source = 'opendata'`
+  5. `MeasurementsRepository` - UPSERT do `chmu.measurements`
+- mapování ELEMENT -> DB sloupec
+
+  | ELEMENT | DB sloupec | Poznámka |
+  |---------|-----------|---------|
+  | T | air_temp | |
+  | H | air_hum | |
+  | P | air_pressure | |
+  | F | wind_speed | |
+  | D | wind_dir | |
+  | SRA10M | precip | |
+  | SSV10M | sunlight | ÷ 360 (s -> desetinné hodiny) |
+  | TMA | air_temp_max | |
+  | TMI | air_temp_min | |
+  | TPM | air_temp_ground | |
+  | Fprum | wind_speed_avg | |
+  | Dprum | wind_dir_avg | |
+  | Fmax | wind_gust | |
+  | Dmax | wind_gust_dir | |
+  | Casmax | wind_gust_time | |
+  | SCEa | snow_depth | |
+  | SVHa | snow_water | |
+  | RGLB10 | radiation_glob | |
+  | REUV10 / REUV25 | radiation_uv | |
+  | T05–T100 | soil_temp_5cm–soil_temp_100cm | |
 
+- data modely
+  - [MeasurementModel](https://gitlab.com/operator-ict/golemio/code/modules/chmu/-/blob/development/src/schema-definitions/definitions/models/MeasurementModel.ts)
 
 ## Uložení dat
 
-Popis ukládání dat.
-
 ### Obecné
 
 - typ databáze
-  - PSQL
-- datábázové schéma
+  - PostgreSQL
+- databázové schéma
   - schéma: `chmu`
   ![chmu er diagram](assets/chmu.erd.png)
 - retence dat
   - data jsou zachována
 - AsyncApi dokumentace
   - [AsyncApi](./asyncapi.yaml)
+
+### Poznámky k datové kvalitě
+
+- Sloupce `soil_hum_0_10`, `soil_hum_10_50`, `soil_hum_50_100` zůstávají v DB, ale opendata zdroj půdní vlhkost neobsahuje - všechny záznamy s `data_source = 'opendata'` mají tyto sloupce `NULL`.
+- Timezone: DT z opendata přichází jako UTC a je převedeno do Europe/Prague pro výpočet zobrazovacích polí (`time`, `year`, `month`, `day`).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@golemio/chmu",
-    "version": "1.1.1-dev.2644315801",
+    "version": "1.1.1-dev.2644362300",
     "description": "Golemio CHMU module",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",