# Implementační dokumentace modulu _energetics_

## Záměr

Modul slouží k ukládání dat o spotřebě energií v budovách a jednotlivých bytech a prostorách pro jejich nájemnce.

### ENAPO

V roce 2025 byl k modulu přidán projekt ENAPO (energetický nástroj Prahy a organizací).
![alt text](Energetika-Stránka-5-Stránka-3.drawio.png)
https://gitlab.com/operator-ict/golemio/projekty/energetika/p0262.prevzeti-energeticke-databaze/-/issues/66

## Vstupní data

### Data nám jsou posílána

-   Přes Permission Proxy na Input Gateway data si bereme z webu https://portal.ptas.cz/portal, web scraping zajišťují dataři golemia, link gitlabu
    https://gitlab.com/operator-ict/golemio/extras/importers/-/blob/development/imports/energetics/scrape_ptas.py?ref_type=heads

        -   POST (/ptas/{id}) s id odběrného místa jako parametrem => RabbitMQ send Message `savePtasMeasurements` ([Data example](../test/input-gateway/data/ptas-hot-water-data-input.csv))

#### _POST /pre_

-   PRE posílá data na Input Gateway v JSON formátu (POST na /pre).
    -   Očekávaný [formát dat](../src/schema-definitions/datasources/enapo/EnapoPreInputSchema.ts)
    -   Dál to postupuje na IE přes rabbit do [EnapoPrediTask](../src/integration-engine/enapo/workers/task/EnapoPrediTask.ts).

#### _POST /pre/csv_

-   Endpoint pro příjem historických dat PRE v CSV formátu (POST na /pre/csv).
    -   Očekávaný [formát dat](../src/schema-definitions/datasources/interfaces/IPreCsvInput.ts)
    -   V IG se CSV převede na stejný formát, jako /pre používá endpoint a dál na IE postupuje stejně.
        Tj. přes rabbit do [ProcessPreEanMeasurementsTask](../src/integration-engine/commodity-providers/workers/tasks/ProcessPreEanMeasurementsTask.ts).

### Data aktivně stahujeme

**Dostupní poskytovatelé**:

-   OICT Energetika
-   Unimonitor CEM API
    -   Vrtbovský palác
    -   Veolia měření P10 - vodoměry a elektroměry
-   PPAS (Pražská plynárenská) InternetAVE API
    -   Měření plynu pro P10 (Uživatelé AveM a AveV)
    -   Měření plynu pro zbytek Prahy pro odběratele různých kategorií A,C a MO
    -   Jedná se o odběratele různých kategorií odběru („A“ „C“ „MO“), konkrétně: účet Hl. m. Praha = „C“; Hlavní m. Praha = „MO“ a HlavníměstoPraha64581_1 = „A“
-   Azure Blob Storage
    -   Mapovací JSON pro měření přímo od poskytovatelů komodit
-   Porsenna e-Manazer API
    -   Měřidla a roční spotřeby pro P7

#### _OICT Energetika_

-   zdroj dat
    -   url: https://api.oictenergetika.cz (config.datasources.OICTEnergetikaApiUrl)
    -   parametry dotazu: config.datasources.OICTEnergetikaApiHeaders
    -   API dokumentace: https://api.oictenergetika.cz/swagger/index.html
-   formát dat
    -   protokol: http
    -   datový typ: json
    -   validační schéma: [datasources](../src/schema-definitions/datasources)
    -   příklad vstupnich dat: [fixtures](../test/integration-engine/oict-energetika/transformations/fixture)
-   frekvence stahování
    -   cron definice:
        -   cron.dataplatform.energeticsoict.fetchData (data za posledních 14 dní s parametrem `{ "targetDays": 14 }`)
            -   rabin `0 30 * * * *`
            -   prod `0 30 * * * *`
-   názvy rabbitmq front
    -   dataplatform.energeticsoict.fetchData
    -   dataplatform.energeticsoict.fetchConsumption

#### _Unimonitor CEM API - Vrtbovský palác_

-   zdroj dat
    -   url: https://cemapi.unimonitor.eu/api (config.datasources.UnimonitorCemApiEnergetics.url)
    -   parametry dotazu: config.datasources.UnimonitorCemApiEnergetics
    -   API dokumentace: https://cemapi.unimonitor.eu/doc/en/index.jsp
-   formát dat
    -   protokol: http
    -   datový typ: json
    -   validační schéma: [EnergeticsVpalac](../src/schema-definitions/providers/EnergeticsVpalac.ts)
    -   příklad vstupnich dat: [fixtures](../test/integration-engine/data)
-   frekvence stahování
    -   cron definice:
        -   cron.dataplatform.energetics.fetchVpalacXHoursData (data za poslední hodinu s parametrem `{ "targetHours": 1 }`)
            -   rabin `0 0 * * * *`
            -   prod `0 0 * * * *`
        -   cron.dataplatform.energetics.fetchVpalacXDaysData (data za posledních 14 dní s parametrem `{ "targetDays": 14 }`)
            -   rabin `0 0 8 * * *`
            -   prod `0 0 8 * * *`
-   názvy rabbitmq front
    -   dataplatform.energetics.fetchVpalacXHoursData
    -   dataplatform.energetics.fetchVpalacXDaysData

#### _Unimonitor CEM API - Veolia měření P10_

-   zdroj dat
    -   url: https://cemapi.unimonitor.eu/api (module.UnimonitorCemApiEnergetics.url)
    -   parametry dotazu: module.energetics.commodityProviders.cem_api_veolia_water (vodoměry), module.energetics.commodityProviders.cem_api_veolia_electro (elektroměry)
    -   API dokumentace: https://cemapi.unimonitor.eu/doc/index.html?lang=cs
-   formát dat
    -   protokol: http
    -   datový typ: json
    -   validační schéma: [Devices](../src/schema-definitions/datasources/commodity-providers/CemApiDevicesJsonSchema.ts), [Counters](../src/schema-definitions/datasources/commodity-providers/CemApiCountersJsonSchema.ts), [Measurements](../src/schema-definitions/datasources/commodity-providers/CemApiMeasurementsJsonSchema.ts)
    -   příklad vstupnich dat: viz [test](../test/integration-engine/commodity-providers/FetchVeoliaMeasurementsTask.test.ts)
-   frekvence stahování
    -   cron definice:
        -   cron.dataplatform.energeticscommodity.fetchMeasurementsFromProviders (data za poslední dny)
            -   rabin `0 41 * * * *` (s parametrem `{ "targetDays": 14 }`)
            -   prod `0 41 * * * *` (s parametrem `{ "targetDays": 31 }`)
-   názvy rabbitmq front
    -   dataplatform.energeticscommodity.fetchMeasurementsFromProviders
    -   dataplatform.energeticscommodity.fetchVeoliaMeasurements

#### _PPAS (Pražská plynárenská) InternetAVE API_

-   zdroj dat
    -   url: https://iave.ppas.cz/website/api (module.energetics.commodityProviders.ppas_ave_api.baseUrl)
    -   API dokumentace: https://www.ave-system.com/Content/download/AveRestApiDocumentation.pdf
-   formát dat
    -   protokol: http
    -   datový typ: json
    -   validační schéma: [Places](../src/schema-definitions/datasources/commodity-providers/AveApiPlacesJsonSchema.ts), [DeviceData](../src/schema-definitions/datasources/commodity-providers/AveApiDeviceDataJsonSchema.ts)
    -   příklad vstupnich dat: viz [test](../test/integration-engine/commodity-providers/FetchPpasMeasurementsTask.test.ts)
-   frekvence stahování
    -   cron definice:
        -   cron.dataplatform.energeticscommodity.fetchMeasurementsFromProviders (data za poslední dny)
            -   rabin `0 41 * * * *` (s parametrem `{ "targetDays": 14 }`)
            -   prod `0 41 * * * *` (s parametrem `{ "targetDays": 31 }`)
-   názvy rabbitmq front
    -   dataplatform.energeticscommodity.fetchMeasurementsFromProviders
    -   dataplatform.energeticscommodity.fetchPpasMeasurements

#### _PRE (Pražská energetika)_

-   zdroj dat
    -   ftp: ftp://ftp.wa-test.oict.cz:16421 (module.energetics.pre_electro_ftp)
-   formát dat
    -   protokol: ftp
    -   datový typ: csv
    -   validační schéma: [Data](../src/schema-definitions/datasources/PreElectricConsumptionJson.ts)
-   frekvence stahování
    -   cron definice:
        -   cron.dataplatform.energeticscommodity.fetchMeasurementsFromProviders (data za poslední dny)
            -   rabin `0 41 * * * *` (s parametrem `{ "targetDays": 14 }`)
            -   prod `0 41 * * * *` (s parametrem `{ "targetDays": 31 }`)
-   názvy rabbitmq front
    -   dataplatform.energeticscommodity.fetchPreElectroMeasurementsTask

#### _Azure Blob Storage - mapovací JSON pro měření_

-   zdroj dat
    -   url: https://golemgolemio.blob.core.windows.net (module.energetics.commodityProviders.staticData.baseUrl)
    -   parametry dotazu: path `/golem-energetics/meterssettings.json` (module.energetics.commodityProviders.staticData.metersettings.path)
    -   API dokumentace: žádná
-   formát dat
    -   protokol: http
    -   datový typ: json
    -   validační schéma: [MeterSettings](../src/schema-definitions/datasources/StaticMeterSettingsJsonSchema.ts)
    -   příklad vstupnich dat: viz [test](../test/integration-engine/commodity-providers/FetchMeasurementOptionsStaticDataTask.test.ts)
-   frekvence stahování
    -   cron definice:
        -   dataplatform.energeticscommodity.fetchMeasurementOptionsStaticData (data za poslední dny)
            -   rabin `0 53 6 * * *` (s parametrem `{}`)
            -   prod `0 53 6 * * *` (s parametrem `{}`)
-   názvy rabbitmq front
    -   dataplatform.energeticscommodity.fetchMeasurementOptionsStaticData

#### _ENO (Evidenční nástroj organizací) - SOAP/WSDL API_

-   zdroj dat
    -   WSDL URL pro jednotlivé endpointy (klíč `{endpoint}` = `wsdlLookup` | `wsdlBuilding` | `wsdlStructure` | `wsdlGeometry`):
        -   `module.energetics.eno.{endpoint}.url` — URL WSDL souboru nebo zip archivu
        -   `module.energetics.eno.{endpoint}.zipped` — `"true"` pokud je WSDL zabaleno v zip archivu (výchozí: nepřítomno = `false`)
        -   `module.energetics.eno.{endpoint}.mainFile` — název hlavního `.wsdl` souboru uvnitř zipu (povinné pokud `zipped=true`)
        -   `module.energetics.eno.extractDir` — sdílená složka pro rozbalení zip archivů (povinné pokud jakýkoli endpoint používá `zipped=true`)
    -   přepsání SOAP endpointu: pokud je `zipped=true`, SOAP klient volá endpoint odvozený z `url` odstraněním query parametrů (`url.split("?")[0]`). V IBM wsdl definicích jsou neplatné adresy pro test i pro prod.
    -   autentizace: konfigurovatelná přes `module.energetics.eno.{source}.type` (`basic` | `token`)
        -   `basic` — HTTP Basic Auth: `module.energetics.eno.{source}.user`, `module.energetics.eno.{source}.password`
        -   `token` — IBM API Gateway token v hlavičce `X-IBM-Client-Id`: `module.energetics.eno.{source}.clientId`
    -   API dokumentace: WSDL schéma
-   formát dat
    -   protokol: SOAP/XML
    -   datový typ: XML → JSON
    -   validační schémata:
        -   Číselníky:
            -   [EnoStructureTypeInput](../src/schema-definitions/datasources/eno/EnoStructureTypeInputJsonSchema.ts) - druhy staveb
            -   [EnoOrganizationInput](../src/schema-definitions/datasources/eno/EnoOrganizationInputJsonSchema.ts) - organizace
            -   [EnoManagerInput](../src/schema-definitions/datasources/eno/EnoManagerInputJsonSchema.ts) - správci
            -   [EnoEJInput](../src/schema-definitions/datasources/eno/EnoEJInputJsonSchema.ts) - evidenční jednotky
        -   Budovy:
            -   [EnoGIDListInput](../src/schema-definitions/datasources/eno/EnoGIDListInputJsonSchema.ts) - seznam GID
            -   [EnoBuildingInfoInput](../src/schema-definitions/datasources/eno/EnoBuldingInfoJsonSchema.ts) - detail budovy
    -   příklad vstupních dat: [test data](../test/integration-engine/data/eno/)
-   frekvence stahování
    -   podle potřeby přes RabbitMQ tasky
-   datové operace
    -   Číselníky (Lookups):
        -   `getDruhStavba` - získání druhů staveb
        -   `getOrganizace` - získání organizací
        -   `getSpravce` - získání správců
        -   `getEvidencniJednotky` - získání evidenčních jednotek
    -   Budovy:
        -   `getBudovyVMajetku` - získání seznamu GID budov v majetku organizace
        -   `getDetailBudovy` - získání detailu budov podle seznamu GID
        -   `getVyrazeneBudovy` - získání seznamu GID vyřazených budov
    -   Stavby:
        -   `getStavbyVMajetku` - získání seznamu GID staveb v majetku organizace
        -   `getDetailStavby` - získání detailu staveb podle seznamu GID
        -   `getVyrazeneStavby` - získání seznamu GID vyřazených staveb
    -   Geometrie:
        -   `getGeometrie` - získání geometrie (polygonů) pro seznam GID budov/staveb

#### _Porsenna (e-Manazer) REST API_

-   zdroj dat
    -   url: https://api.e-manazer.cz/gauges (module.energetics.enapo.porsenna.url)
    -   autentizace: Bearer token (module.energetics.enapo.porsenna.token)
    -   source identifikátor: `porsenna_p7`
-   formát dat
    -   protokol: http (REST)
    -   datový typ: json (Hydra kolekce se stránkováním)
    -   validační schémata: [PorsennaJsonSchema](../src/schema-definitions/datasources/enapo/porsenna/PorsennaJsonSchema.ts)
-   datasource
    -   [PorsennaDataSource](../src/integration-engine/enapo/datasources/porsenna/PorsennaDataSource.ts)
        -   `generateAsyncPages()` - stránkované získání všech měřidel
        -   `getGaugeConsumption(id, from, to)` - roční spotřeba pro jedno měřidlo

## Zpracování dat / transformace

Všechny tabulky se nachází ve schématu `energetics`

### _CommodityWorker_

Worker se stará o stahování dat (odečty, měřidla a počítadla) přímo od poskytovatelů komodit

#### _task: FetchMeasurementOptionsStaticDataTask_

Metoda sbírá mapovací JSON pro měření - odlehčený `metersettings.json` (bez secretů) z původní implementace energetické DB https://gitlab.com/operator-ict/oddeleni-vyvoje/energetika/spotreby-energii-mestskych-budov/stahovani-dat-meridel/-/blob/main/src/OIct.EnergyConsumptionGrabber/meterssettings.json. Za obsah a správu souboru odpovídá Stanislav Krňák

-   vstupní rabbitmq fronta
    -   název: dataplatform.energeticscommodity.fetchMeasurementOptionsStaticData
    -   TTL: 59 minut
    -   parametry: žádné
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   Azure Blob Storage (golemgolemio.blob.core.windows.net/golem-energetics/meterssettings.json)
-   transformace
    -   žádné
-   data modely
    -   [StaticMeterSettingsModel](../src/schema-definitions/models/StaticMeterSettingsModel.ts) tabulka `commodity_static_meter_settings`

#### _task: FetchMeasurementsFromProvidersTask_

Metoda pouze rozesílá zprávy do ostatních front (fetchVeoliaMeasurements). Slouží k získání dat o spotřebě energií od poskytovatelů komodit za posledních X dní

-   vstupní rabbitmq fronta
    -   název: dataplatform.energeticscommodity.fetchMeasurementsFromProviders
    -   TTL: 1 hodina
    -   parametry: `{ targetDays }`
    -   validační schéma: [DataEntrypointSchema](../src/integration-engine/commodity-providers/workers/schema/DataEntrypointSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   dataplatform.energeticscommodity.fetchVeoliaMeasurements (vodoměry s parametry `{ providerType: cem_api_veolia_water, dateFrom, dateTo }`)
    -   dataplatform.energeticscommodity.fetchVeoliaMeasurements (elektroměry s parametry `{ providerType: cem_api_veolia_electro, dateFrom, dateTo }`)
-   datové zdroje
    -   žádné
-   transformace
    -   žádné
-   data modely
    -   žádné

#### _task: FetchVeoliaMeasurementsTask_

Metoda sbírá data o spotřebách od poskytovatele komodit - Veolia P10 (vodoměry a elektroměry)

-   vstupní rabbitmq fronta
    -   název: dataplatform.energeticscommodity.fetchVeoliaMeasurements
    -   TTL: 1 hodina
    -   parametry: `{ providerType, dateFrom, dateTo }`
    -   validační schéma: [VeoliaMeasurementsSchema](../src/integration-engine/commodity-providers/workers/schema/VeoliaMeasurementsSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   Unimonitor CEM API
-   transformace
    -   [CemMeasurementTransformation](../src/integration-engine/commodity-providers/transformations/CemMeasurementTransformation.ts)
-   data modely
    -   [StaticMeterSettingsModel](../src/schema-definitions/models/StaticMeterSettingsModel.ts) tabulka `commodity_static_meter_settings`
    -   [MeasurementModel](../src/schema-definitions/models/MeasurementsModel.ts) tabulka `consumption_energy_measurements`

#### _task: FetchPpasMeasurementsTask_

Metoda sbírá data o spotřebách od poskytovatele komodit - PPAS (Pražská plynárenská) P10

-   vstupní rabbitmq fronta
    -   název: dataplatform.energeticscommodity.fetchPpasMeasurements
    -   TTL: 1 hodina
    -   parametry: `{ providerType, dateFrom, dateTo }`
    -   validační schéma: [PpasMeasurementsSchema](../src/integration-engine/commodity-providers/workers/schema/PpasMeasurementsSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   PPAS (Pražská plynárenská) InternetAVE API
-   transformace
    -   [AveMeasurementTransformation](../src/integration-engine/commodity-providers/transformations/AveMeasurementTransformation.ts)
-   data modely
    -   [StaticMeterSettingsModel](../src/schema-definitions/models/StaticMeterSettingsModel.ts) tabulka `commodity_static_meter_settings`
    -   [MeasurementModel](../src/schema-definitions/models/MeasurementsModel.ts) tabulka `consumption_energy_measurements`

#### _task: FetchPreElectroMeasurementsTask_

Metoda sbírá data o spotřebách od poskytovatele komodit - PRE (Pražská energetika)

-   vstupní rabbitmq fronta
    -   název: dataplatform.energeticscommodity.fetchPreElectroMeasurementsTask
    -   TTL: 1 hodina
    -   parametry: `{ dateFrom, dateTo }`
    -   validační schéma: [MeasurementsSchema](../src/integration-engine/commodity-providers/workers/schema/MeasurementsSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   PRE (Pražská energetika) FTP
-   transformace
    -   [PreElectroTransformation](../src/integration-engine/commodity-providers/transformations/PreElectroTransformation.ts)
-   data modely
    -   [StaticMeterSettingsModel](../src/schema-definitions/models/StaticMeterSettingsModel.ts) tabulka `commodity_static_meter_settings`
    -   [MeasurementModel](../src/schema-definitions/models/MeasurementsModel.ts) tabulka `consumption_energy_measurements`

#### _task: ProcessPreEanMeasurementsTask_

Přijímá data o spotřebách od PRE z IG (viz. nahoře)

-   vstupní rabbitmq fronta
    -   název: dataplatform.energeticscommodity.processPreEanMeasurements
    -   TTL: 1 hodina
    -   parametry: [IPreEanMeasurement](../src/integration-engine/commodity-providers/workers/interfaces/IPreEanMeasurement.ts)
    -   validuje se na IG
-   závislé fronty nejsou
-   datový zdroj je PRE IG endpoint (viz. nahoře)
-   transformace
    -   [PreMeasurementTransformation](../src/integration-engine/commodity-providers/transformations/PreMeasurementTransformation.ts)
    -   Vstupní hodnoty se stejným datem měření se sčítají. Duplicitní timestamp vzniká při přechodu na zimní čas.
-   data modely
    -   odsud si bere statická data: [StaticMeterSettingsModel](../src/schema-definitions/models/StaticMeterSettingsModel.ts) tabulka `commodity_static_meter_settings`
    -   sem ukládá: [MeasurementModel](../src/schema-definitions/models/MeasurementsModel.ts) tabulka `consumption_energy_measurements`

#### _task: FetchPtasWebScrapedMeasurementsTask_

Pomocí tohoto tasku zpracováváme a ukládáme data z input gateway z fronty savePtasMeasurements. Podle původního scraperu z C# bereme pouze teplo horké vody.
Aby nedocházelo ke konfliktům měřidel, filtrují se měřidla dle seznamu uloženém ve statických datech.

-   vstupní rabbitmq fronta
    -   název: dataplatform.energeticscommodity.savePtasMeasurements
    -   TTL: 1 hodina
    -   input: parsované csv příklad ([Data example](../test/input-gateway/data/ptas-hot-water-data-input.csv))
    -   validační schéma: [PtasWebScrapingJsonSchema](../src/schema-definitions/datasources/PtasWebScrapingJsonSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   PTAS Pražská Teplárenská
-   transformace
    -   [PtasWebMeasurementTransformation](../src/integration-engine/commodity-providers/transformations/PtasWebMeasurementTransformation.ts.ts)
-   data modely
    -   [StaticMeterSettingsModel](../src/schema-definitions/models/StaticMeterSettingsModel.ts) tabulka `commodity_static_meter_settings`
    -   [MeasurementModel](../src/schema-definitions/models/MeasurementsModel.ts) tabulka `consumption_energy_measurements`

### _OictEnergetikaWorker_

Worker se stará o stahování dat (spotřeba, seznamy budov a meřidel) z datového zdroje OICT Energetika

#### _task: FetchDataTask_

Metoda pouze rozesílá zprávy do ostatních front (fetchConsumption)

-   vstupní rabbitmq fronta
    -   název: dataplatform.energeticsoict.fetchData
    -   TTL: 29 minut
    -   parametry: `{ targetDays }`
    -   validační schéma: [FetchDataSchema](../src/integration-engine/oict-energetika/schema/FetchDataSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   dataplatform.energeticsoict.fetchConsumption
-   datové zdroje
    -   žádné
-   transformace
    -   žádné
-   data modely
    -   žádné

#### _task: FetchConsumptionTask_

Metoda sbírá data o spotřebách od různých poskytovalů API (consumption) a ze systémů Dot Controls (visapp)

-   vstupní rabbitmq fronta
    -   název: dataplatform.energeticsoict.fetchConsumption
    -   TTL: 10 hodin
    -   parametry: `{ dateFrom, dateTo }`
    -   validační schéma: [FetchDataSchema](../src/integration-engine/oict-energetika/schema/FetchDataSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   OICT Energetika (data/consumption, data/visapp)
-   transformace
    -   [ConsumptionTransformation](../src/integration-engine/oict-energetika/transformations/ConsumptionTransformation.ts)
-   data modely
    -   ConsumptionModel `consumption_energy_consumption`

#### _task: FetchAccessConfigurationTask_

Task aktualizuje lookup tabulku pro limitaci přístupu k output API.

-   vstupní rabbitmq fronta
    -   název: dataplatform.energeticsoict.fetchAccessConfiguration
    -   TTL: 10 minutes
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   blob storage
        -   rabín: https://rabingolemio.blob.core.windows.net/rabin-energetics/access_configuration.json
        -   golem: https://golemgolemio.blob.core.windows.net/golem-energetics/access_configuration.json
-   transformace
    -   není
-   data modely
    -   AccessLimitationModel `access_limitation`

### _EnergeticsVpalacWorker_

Worker se stará o stahování dat (odečty, měřidla a počítadla) z datového zdroje Unimonitor CEM API - Vrtbovský palác

#### _fetchXHoursData()_

Metoda sbírá aktuální data

-   vstupní rabbitmq fronta
    -   název: dataplatform.energetics.fetchVpalacXHoursData
    -   TTL: 1 hodina
    -   parametry: `{ targetHours }`
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   CEM API
-   transformace
    -   [transformations](../src/integration-engine/vpalac/transformations)
-   data modely
    -   VpalacMeasurementModel `vpalac_measurement`
    -   VpalacMeasuringEquipmentModel `vpalac_measuring_equipment`
    -   VpalacMeterTypeModel `vpalac_meter_type`
    -   VpalacTypeMeasuringEquipmentModel `vpalac_type_measuring_equipment`
    -   VpalacUnitsModel `vpalac_units`

#### _fetchXDaysData()_

Metoda sbírá historická data

-   vstupní rabbitmq fronta
    -   název: dataplatform.energetics.fetchVpalacXDaysData
    -   TTL: 1 den
    -   parametry: `{ targetDays }`
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   CEM API
-   transformace
    -   [transformations](../src/integration-engine/vpalace/transformations)
-   data modely
    -   VpalacMeasurementModel `vpalac_measurement`
    -   VpalacMeasuringEquipmentModel `vpalac_measuring_equipment`
    -   VpalacMeterTypeModel `vpalac_meter_type`
    -   VpalacTypeMeasuringEquipmentModel `vpalac_type_measuring_equipment`
    -   VpalacUnitsModel `vpalac_units`

### _EnapoWorker_

Worker se stará o stahování dat (odečty, měřidla a počítadla) z datového zdroje PPAS pro projekt ENAPO.

#### _task: EnapoPpasTask_

Metoda sbírá data o spotřebách od poskytovatele komodit - PPAS (Pražská plynárenská).

-   vstupní rabbitmq fronta
    -   název: dataplatform.enapoenergetics.fetchPpasMeasurements
    -   TTL: 1 hodina
    -   parametry: `{ providerType, dateFrom?, dateTo?, targetDays? }`
    -   validační schéma: [PpasMeasurementsSchema](../src/integration-engine/enapo/workers/schema/EnapoPpasMeasurementsParamsValidationSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   PPAS (Pražská plynárenská) InternetAVE API
-   transformace
    -   [PPasMeasurementTransformation](../src/integration-engine/enapo/transformations/PPasMeasurementTransformation.ts)
-   data modely
    -   [EnapoMeasurementsModel](../src/schema-definitions/models/EnapoMeasurementsModel.ts) tabulka `enapo_measurements`

#### _task: EnapoPrediTask_

Task zpracovává zasílaná data o spotřebě elektřiny. Data jsou nám zasílána

-   vstupní rabbitmq fronta
    -   název: dataplatform.enapoenergetics.processPrediData
    -   TTL: 1 hodina
    -   validační schéma: [EnapoPreInputSchema](../src/schema-definitions/datasources/enapo/EnapoPreInputSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   PRE distribution zasílá data na input gateway
-   transformace
    -   [PreDailyMeasurementsTransformation](../src/integration-engine/enapo/transformations/pre/PreDailyMeasurementsTransformation.ts)
    -   [PreMeasurementsTransformation](../src/integration-engine/enapo/transformations/pre/PreMeasurementsTransformation.ts)
    -   [PreMetadataTransfromation](../src/integration-engine/enapo/transformations/pre/PreMetadataTransfromation.ts.ts)
    -   v případě, že se u measurementů vyskytnou dvě hodnoty ve stejném čase, tak se hodnoty sečtou viz [sumDuplicates](../src/integration-engine/commodity-providers/helper/PreMeasurementFilter.ts)
    -   device_serial_number is extracted from raw_data `meter_replaced` value
        -   default time for meter change is set to static value `10:00` Europe/Prague time
        -   If change occurs e.g. `"meter_replaced": "2025-06-19|54292510|55505332|2025-06-30|55505332|96933662"` measurements before 19.6.2025 will have serial number `54292510`      measurements after `2025-06-19 10:00` will have serial number `55505332` and measurements after `2025-06-30 10:00` will have serial number `96933662`
        -   [DeviceSerialNumberExtractor](../src/integration-engine/enapo/transformations/pre/helpers/DeviceSerialNumberExtractor.ts)
-   data modely
    -   [EnapoMeasurementsModel](../src/schema-definitions/models/enapo/EnapoMeasurementsModel.ts) tabulka `enapo_measurements`
    -   [EnapoMetadataModel](../src/schema-definitions/models/enapo/EnapoMetadataModel.ts) tabulka `enapo_metadata`
    -   [PreIncomingDataLogModel](../src/schema-definitions/models/enapo/PreIncomingDataLogModel.ts) tabulka `enapo_log_pre`

#### _task: EnoLookupTask_

Task stahuje číselníková (lookup) data ze systému ENO (Evidenční nástroj organizací) včetně druhů staveb, organizací, správců a evidenčních jednotek.

-   vstupní rabbitmq fronta
    -   název: dataplatform.enapoenergetics.processEnoLookup
    -   TTL: 1 hodina
    -   parametry: `{ type }` - typ číselníku (`getDruhStavba` | `getOrganizace` | `getSpravce` | `getEvidencniJednotky`)
    -   validační schéma: [EnoLookupTaskInputSchema](../src/integration-engine/enapo/workers/schema/EnoLookupTaskInputSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   ENO SOAP/WSDL API (Lookups endpoint)
    -   [EnoDatasource](../src/integration-engine/enapo/datasources/eno/EnoDatasource.ts)
    -   [EnoDatasourceFactory](../src/integration-engine/enapo/datasources/eno/EnoDatasourceFactory.ts)
-   transformace
    -   [EnoStructureTypeTransformation](../src/integration-engine/enapo/transformations/eno/EnoStructureTypeTransformation.ts) - transformace druhů staveb
    -   [EnoOrganizationTransformation](../src/integration-engine/enapo/transformations/eno/EnoOrganizationTransformation.ts) - transformace organizací
    -   [EnoManagerTransformation](../src/integration-engine/enapo/transformations/eno/EnoManagerTransformation.ts) - transformace správců
    -   [EnoEJTransformation](../src/integration-engine/enapo/transformations/eno/EnoEJTransformation.ts) - transformace evidenčních jednotek
-   data modely
    -   [StructureTypeModel](../src/schema-definitions/models/eno/StructureTypeModel.ts) tabulka `eno_struktura_typ_lookup`
    -   [OrganizationLookupModel](../src/schema-definitions/models/eno/OrganizationLookupModel.ts) tabulka `eno_organizace_lookup`
    -   [ManagerLookupModel](../src/schema-definitions/models/eno/ManagerLookupModel.ts) tabulka `eno_spravce_lookup`
    -   [EJLookupModel](../src/schema-definitions/models/eno/EJLookupModel.ts) tabulka `eno_ej_lookup`
-   unit testy
    -   [EnoLookupTask.test.ts](../test/integration-engine/enapo/task/EnoLookupTask.test.ts)

#### _task: EnoBuildingTask_

Task stahuje data o budovách ze systému ENO včetně detailních informací o budovách, adresách, umístění a majetkových vztazích. Podporuje plnou i inkrementální synchronizaci (pomocí parametru `daysBack`).

-   vstupní rabbitmq fronta
    -   název: dataplatform.enapoenergetics.processEnoBuildings
    -   TTL: 1 hodina
    -   parametry: `{ type, source, daysBack? }`
        -   `type` - typ synchronizace (`current` | `removed`)
        -   `source` - zdroj dat (např. `mhmp`)
        -   `daysBack` - volitelný parametr pro inkrementální synchronizaci (počet dní zpětně)
    -   validační schéma: [EnoBuildingTaskInputSchema](../src/integration-engine/enapo/workers/schema/EnoBuildingTaskInputSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   ENO SOAP/WSDL API (Buildings endpoint)
    -   [EnoDatasource](../src/integration-engine/enapo/datasources/eno/EnoDatasource.ts)
    -   [EnoDatasourceFactory](../src/integration-engine/enapo/datasources/eno/EnoDatasourceFactory.ts)
-   transformace
    -   [EnoBuildingTransformation](../src/integration-engine/enapo/transformations/eno/EnoBuildingTransformation.ts) - transformace dat budov
        -   Transformuje budovu, majetek, adresy a umístění
        -   Zpracovává pole adres a umístění s přidělením pořadí (poradi)
-   data modely
    -   [BuildingModel](../src/schema-definitions/models/eno/BuildingModel.ts) tabulka `eno_budova`
    -   [PropertyModel](../src/schema-definitions/models/eno/PropertyModel.ts) tabulka `eno_majetek`
    -   [AddressModel](../src/schema-definitions/models/eno/AddressModel.ts) tabulka `eno_adresa`
    -   [LocationModel](../src/schema-definitions/models/eno/LocationModel.ts) tabulka `eno_umisteni`
    -   [RemovedGIDModel](../src/schema-definitions/models/eno/RemovedGIDModel.ts) tabulka `eno_vyrazene_gid`
-   funkce
    -   **Plná synchronizace**: Stáhne všechny budovy v majetku organizace (bez parametru `daysBack`)
    -   **Inkrementální synchronizace**: Stáhne pouze budovy změněné za posledních X dní (s parametrem `daysBack`)
    -   **Vyřazené budovy**: Pro typ `removed` ukládá GID vyřazených budov do speciální tabulky. Datový zdroj povinně vyžaduje datum od kdy. Ve výchozím stavu je nastaveno od `2025-01-01T00:00:00+01:00` lze to upravit v konfiguraci změnou `module.energetics.eno.removedBuldingsStartDate`.
    -   **Transakční zpracování**: Všechny operace zápisu probíhají v databázové transakci pro zajištění konzistence
-   unit testy
    -   [EnoBuildingTask.test.ts](../test/integration-engine/enapo/task/EnoBuildingTask.test.ts)

#### _task: EnoStructureTask_

Task stahuje data o stavbách ze systému ENO včetně detailních informací o stavbách, adresách, umístění a majetkových vztazích. Podporuje plnou i inkrementální synchronizaci (pomocí parametru `daysBack`). Po úspěšném stažení staveb automaticky spouští stahování geometrií.

-   vstupní rabbitmq fronta
    -   název: dataplatform.enapoenergetics.processEnoStructures
    -   TTL: 1 hodina
    -   parametry: `{ type, source, daysBack? }`
        -   `type` - typ synchronizace (`current` | `removed`)
        -   `source` - zdroj dat (např. `mhmp`)
        -   `daysBack` - volitelný parametr pro inkrementální synchronizaci (počet dní zpětně)
    -   validační schéma: [EnoBuildingTaskInputSchema](../src/integration-engine/enapo/workers/schema/EnoBuildingTaskInputSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   dataplatform.enapoenergetics.processEnoGeometry - po úspěšném stažení staveb
-   datové zdroje
    -   ENO SOAP/WSDL API (Structure endpoint)
    -   [EnoDatasource](../src/integration-engine/enapo/datasources/eno/EnoDatasource.ts)
    -   [EnoDatasourceFactory](../src/integration-engine/enapo/datasources/eno/EnoDatasourceFactory.ts)
-   transformace
    -   [EnoStructureTransformation](../src/integration-engine/enapo/transformations/eno/EnoStructureTransformation.ts) - transformace dat staveb
        -   Transformuje stavbu, majetek, adresy a umístění
        -   Zpracovává pole adres a umístění s přidělením pořadí (poradi)
-   data modely
    -   [StructureModel](../src/schema-definitions/models/eno/StructureModel.ts) tabulka `eno_stavba`
    -   [PropertyModel](../src/schema-definitions/models/eno/PropertyModel.ts) tabulka `eno_majetek`
    -   [AddressModel](../src/schema-definitions/models/eno/AddressModel.ts) tabulka `eno_adresa`
    -   [LocationModel](../src/schema-definitions/models/eno/LocationModel.ts) tabulka `eno_umisteni`
    -   [RemovedGIDModel](../src/schema-definitions/models/eno/RemovedGIDModel.ts) tabulka `eno_vyrazene_gid`
-   funkce
    -   **Plná synchronizace**: Stáhne všechny stavby v majetku organizace (bez parametru `daysBack`)
    -   **Inkrementální synchronizace**: Stáhne pouze stavby změněné za posledních X dní (s parametrem `daysBack`)
    -   **Vyřazené stavby**: Pro typ `removed` ukládá GID vyřazených staveb do speciální tabulky
    -   **Transakční zpracování**: Všechny operace zápisu probíhají v databázové transakci pro zajištění konzistence
    -   **Automatické stažení geometrií**: Po úspěšném zpracování staveb odesílá zprávu do fronty pro stažení geometrií
-   unit testy
    -   [EnoStructureTask.test.ts](../test/integration-engine/enapo/task/EnoStructureTask.test.ts)

#### _task: EnoGeometryTask_

Task stahuje geometrie (polygony) pro budovy a stavby ze systému ENO. Je automaticky spouštěn po dokončení synchronizace budov nebo staveb.

-   vstupní rabbitmq fronta
    -   název: dataplatform.enapoenergetics.processEnoGeometry
    -   TTL: 1 hodina
    -   parametry: `{ source, listGid }`
        -   `source` - zdroj dat (např. `mhmp`)
        -   `listGid` - seznam GID pro které se má stáhnout geometrie
    -   validační schéma: [EnoGeometryTaskInputSchema](../src/integration-engine/enapo/workers/schema/EnoGeometryTaskInputSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   ENO SOAP/WSDL API (Geometry endpoint)
    -   [EnoDatasource](../src/integration-engine/enapo/datasources/eno/EnoDatasource.ts)
    -   [EnoDatasourceFactory](../src/integration-engine/enapo/datasources/eno/EnoDatasourceFactory.ts)
-   transformace
    -   [EnoGeometryTransformation](../src/integration-engine/enapo/transformations/eno/EnoGeometryTransformation.ts) - transformace geometrických dat
        -   Zpracovává polygony ve formátu WKT (Well-Known Text)
        -   Přiděluje pořadí (poradi) pro více geometrií se stejným GID
        -   Podporuje EPSG kód pro souřadnicový systém
-   data modely
    -   [GeometryModel](../src/schema-definitions/models/eno/GeometryModel.ts) tabulka `eno_geometrie`
-   funkce
    -   **Stažení geometrií**: Stáhne geometrie pro zadaný seznam GID
    -   **Podpora více geometrií**: Jeden GID může mít více geometrií (např. budova s více polygony), každá dostane unikátní pořadí
    -   **EPSG kód**: Podporuje různé souřadnicové systémy (výchozí S-JTSK = 5514)
-   unit testy
    -   [EnoGeometryTask.test.ts](../test/integration-engine/enapo/task/EnoGeometryTask.test.ts)

#### _PPAS Distribution API_

-   zdroj dat
    -   url: https://distribution-api.ppas.cz (module.energetics.enapo.ppas.distribution.url)
    -   OAuth2 URL: https://distribution-oauth.ppas.cz/oauth/token (module.energetics.enapo.ppas.distribution.oauthUrl)
    -   autentizace: OAuth2 Client Credentials Flow
        -   clientId: module.energetics.enapo.ppas.distribution.clientId
        -   clientSecret: module.energetics.enapo.ppas.distribution.clientSecret
        -   accessToken header: module.energetics.enapo.ppas.distribution.accessToken
    -   API dokumentace: interní dokumentace PPAS
    -   Kdyz jsou hodnoty v consumptionKwh negativni tak se jedna o storno označeno jako CORRECTION pokud ne označeno jako STANDARD, pokud prijdou dve nulove hodnoty za sebou, nazváno zero rows, tak je první brána jako STANDARD a druhá CORRECTION
-   formát dat
    -   protokol: https (REST API)
    -   datový typ: json
    -   validační schémata:
        -   [PpasDistributionInvoiceListInput](../src/schema-definitions/datasources/enapo/ppas/distribution/IPpasDistributionInvoiceListInput.ts) - seznam faktur
        -   [PpasDistributionInvoiceDetailInput](../src/schema-definitions/datasources/enapo/ppas/distribution/IPpasDistributionInvoiceDetailInput.ts) - detail faktury včetně zařízení a cen
        -   [PpasDistributionSchema](../src/schema-definitions/datasources/enapo/ppas/distribution/PpasDistributionSchema.ts) - JSON Schema validace
    -   příklad vstupních dat:
        -   [ppas_distribution_invoice_list_input.json](../test/integration-engine/data/enapo/ppas_distribution_invoice_list_input.json)
        -   [ppas_distribution_invoice_detail_input.json](../test/integration-engine/data/enapo/ppas_distribution_invoice_detail_input.json)
-   datasource
    -   [PpasDistributionDatasource](../src/integration-engine/enapo/datasources/ppas/distribution/PpasDistributionDatasource.ts)
        -   `getInvoiceList(from, to, ic?)` - získání seznamu faktur za období
        -   `getInvoiceDetail(intNum)` - získání detailu faktury včetně zařízení, odečtů a cen
    -   Automatická správa OAuth2 tokenu (refresh před expirací)
    -   Validace odpovědí pomocí JSON Schema
-   unit testy
    -   [PpasDistributionDatasource.test.ts](../test/integration-engine/enapo/datasource/PpasDistributionDatasource.test.ts)

#### _task: EnapoPpasDistributionTask_

Task stahuje fakturační data distribuce od PPAS včetně informací o fakturách, zařízeních, odečtech a cenách. Data jsou následně transformována a uložena do tří souvisejících tabulek.

-   vstupní rabbitmq fronta
    -   název: dataplatform.enapoenergetics.fetchPpasDistribution
    -   TTL: 1 hodina
    -   parametry: `{ from?, to? }`
        -   `from` - datum od (formát YYYY-MM-DD), volitelné - výchozí: dnes - 3 dny
        -   `to` - datum do (formát YYYY-MM-DD), volitelné - výchozí: dnes
    -   validační schéma: [EnapoPpasDistributionParamsSchema](../src/integration-engine/enapo/workers/schema/EnapoPpasDistributionParamsSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   PPAS Distribution API
    -   [PpasDistributionDatasource](../src/integration-engine/enapo/datasources/ppas/distribution/PpasDistributionDatasource.ts)
-   transformace
    -   [PpasDistributionTransformation](../src/integration-engine/enapo/transformations/ppas/PpasDistributionTransformation.ts) - transformace dat faktur
        -   Transformuje fakturační hlavičku s informacemi o zákazníkovi, adresách a fakturovaných částkách
        -   Zpracovává zařízení (devices) s jejich odečty včetně spotřeby elektřiny a plynu
        -   Zpracovává cenové položky (prices) s detailními informacemi o tarifech a jednotkových cenách
        -   Rozlišuje mezi standardní cenou STANDARD a korekcí CORRECTION 
-   data modely
    -   [PpasDistributionInvoiceModel](../src/schema-definitions/models/enapo/ppas/PpasDistributionInvoiceModel.ts) tabulka `ppas_distribution_invoice` - hlavičky faktur
    -   [PpasDistributionInvoiceDeviceModel](../src/schema-definitions/models/enapo/ppas/PpasDistributionInvoiceDeviceModel.ts) tabulka `ppas_distribution_invoice_device` - zařízení a odečty
    -   [PpasDistributionInvoicePriceModel](../src/schema-definitions/models/enapo/ppas/PpasDistributionInvoicePriceModel.ts) tabulka `ppas_distribution_invoice_price` - cenové položky

#### _task: PorsennaDistributionTask_

Task stahuje data o měřidlech a spotřebách z Porsenna API (e-Manazer).

-   vstupní rabbitmq fronta
    -   název: dataplatform.enapoenergetics.fetchPorsennaDistribution
    -   TTL: 1 hodina
    -   parametry: `{ yearFrom, yearTo }`
    -   validační schéma: [EnapoPorsennaDistributionParamsSchema](../src/integration-engine/enapo/workers/schema/EnapoPorsennaDistributionParamsSchema.ts)
-   závislé fronty (do kterých jsou odesílány zprávy z metody workeru)
    -   žádné
-   datové zdroje
    -   Porsenna e-Manazer API
    -   [PorsennaDataSource](../src/integration-engine/enapo/datasources/porsenna/PorsennaDataSource.ts)
-   transformace
    -   [PorsennaGaugeTransformation](../src/integration-engine/enapo/transformations/porsenna/PorsennaGaugeTransformation.ts) - transformace měřidel na budovy a zařízení
    -   [PorsennaConsumptionTransformation](../src/integration-engine/enapo/transformations/porsenna/PorsennaConsumptionTransformation.ts) - transformace spotřeb
-   data modely
    -   [PorsennaBuildingsModel](../src/schema-definitions/models/porsenna/PorsennaBuildingsModel.ts) tabulka `enapo_porsenna_buildings`
    -   [PorsennaDevicesModel](../src/schema-definitions/models/porsenna/PorsennaDevicesModel.ts) tabulka `enapo_porsenna_devices`
    -   [PorsennaConsumptionModel](../src/schema-definitions/models/porsenna/PorsennaConsumptionModel.ts) tabulka `enapo_porsenna_consumption`

## Uložení dat

-   typ databáze
    -   PSQL
-   databázové schéma
    -   OICT Energetika <br/>
        ![consumption energy diagram](./assets/consumption_energy_erd.png)
    -   Vrtbovský palác <br/>
        ![vpalac diagram](./assets/vpalac_erd.png)
    -   Poskytovatelé komodit <br/>
        ![commodity diagram](./assets/commodity_erd.jpg)
-   retence dat
    -   data si uchováváme

## Output API

### Obecné

-   OpenAPI v2 dokumentace
    -   zdrojový soubor: [openapi-output.yaml](./openapi-output.yaml)
    -   rabin: https://rabin.golemio.cz/v2/docs/openapi/
    -   golem: https://api.golemio.cz/v2/docs/openapi/
    -   přístup je řízen pomocí interního parametru `accessLimit`, který musí být vždy nastaven a omezen z permission proxy
        -   při obdržení dotazu na API se stáhnou povolené organizace z tabulky `access_limit` a omezí se podle toho dotazy do databáze
        -   pokud je `accessLimit` nastaven na `admin`, tak se vždy dotazuje na všechny organizace

### API

#### _/v2/energetics/buildings_

#### _/v2/energetics/buildings/:id_

-   zdrojové tabulky
    -   `consumption_energy_buildings_primary`
    -   `consumption_energy_buildings_secondary`

#### _/v2/energetics/organizations_

#### _/v2/energetics/organizations/:id_

-   zdrojové tabulky
    -   organizations
    -   organization_responsible_users
    -   organizations_buildings
    -   consumption_energy_buildings

#### _/v2/energetics/devices_

#### _/v2/energetics/devices/:id_

-   zdrojové tabulky
    -   consumption_energy_devices

#### _/v2/energetics/measurements_

#### _/v2/energetics/measurements/monthly-reading_

-   zdrojové tabulky
    -   consumption_energy_measurements