@golemio/parkings 1.1.1-dev.560668363 → 1.1.1-dev.570249156

package/docs/implementation-documentation.md

@@ -0,0 +1,297 @@
+# Implementační dokumentace modulu **parkings**
+
+## Záměr
+
+Modul slouží k ukládání a poskytování informací o parkování.
+
+**Dostupní poskytovatelé**:
+
+-   Korid (Liberec)
+-   TSK (Praha)
+-   IPR (Praha)
+
+## Vstupní data
+
+### Data nám jsou posílána
+
+- Přes Permission Proxy na Input Gateway, dodavatel Korid
+
+    - POST (/koridparkings/config) => RabbitMQ send Message `saveKoridConfToDB` ([Data example](../test/input-gateway/korid-parkings/data/korid-config.json))
+    - POST (/koridparkings/data) => RabbitMQ send Message `saveKoridDataToDB` ([Data example](../test/input-gateway/korid-parkings/data/korid-data.json))
+
+- na FTP, dodavatel TSK (parkovací zóny)
+
+### Data aktivně stahujeme
+
+Data stahujeme pravidelně od IPR, TSK.
+
+Pro ZTP parkoviště se z API se stahuje JSON z https://opendata.iprpraha.cz/CUR/DOP/DOP_TSK_Stani_ZTP_b/WGS_84/DOP_TSK_Stani_ZTP_b.json
+
+#### Zóny placeného stání
+
+Zóny placeného stání používají 2 datové zdroje - TSK a Opendata IPR, které mají přesnější geometrii.
+
+- zdroj dat (**TSK**):
+
+  config FTPProtocolStrategy:
+
+   ```
+   filename: "Area_YYYY-MM-DD.json", // "Tarif_YYYY-MM-DD.tsv" pro tarify
+    path: config.datasources.TSKFTPParkingZonesPath,
+    url: {
+        host: config.datasources.TSKFTP.host,
+        port: config.datasources.TSKFTP.port,
+        user: config.datasources.TSKFTP.user,
+        password: config.datasources.TSKFTP.password,
+    },
+    encoding: "utf8",
+    ```
+
+- formát dat (**TSK**)
+
+    - protokol: ftp
+    - datový typ:
+        - lokace: json
+        - tarify: tsv
+    - validační schéma:
+        - lokace: json
+        - tarify: tsv
+    - validační schéma:
+        - lokace [datasourceGeoJsonSchema](https://gitlab.com/operator-ict/golemio/code/modules/parkings/-/blob/development/src/schema-definitions/index.ts)
+        - tarify [datasourceTariffJsonSchema](https://gitlab.com/operator-ict/golemio/code/modules/parkings/-/blob/development/src/schema-definitions/index.ts)
+    - příklad vstupních dat:
+        - [lokace](https://gitlab.com/operator-ict/golemio/code/modules/parkings/-/blob/development/test/integration-engine/data/ipr-parking-data-input.json)
+        - [tarify (tsv->json)](https://gitlab.com/operator-ict/golemio/code/modules/parkings/-/blob/development/test/integration-engine/data/tsk-parking-tariff-data-input.json)
+
+- zdroj dat (**IPR**):
+
+  config HTTPProtocolStrategy:
+
+  ```
+  headers: {},
+  method: "GET",
+  url: config.datasources.ParkingZones,
+  ```
+
+- formát dat (**IPR**)
+
+    - protokol: http
+    - datový typ: json
+    - validační schéma: datasourceEcoCounterJsonSchema
+    - příklad vstupních dat
+
+- frekvence stahování
+
+    - cron definice:
+        - cron.dataplatform.parkings.saveParkingZonesPrague (`0 */5 * * * *`)
+
+- název rabbitmq fronty
+    - dataplatform.parkings.saveParkingZonesPrague
+
+#### Placené parkoviště
+
+- zdroj dat (**TSK**):
+
+  config HTTPProtocolStrategy:
+
+   ```
+   headers: {},
+    method: "GET",
+    url: config.datasources.TSKParkings,
+    ```
+
+    + filter `lastUpdated` ne starší než 48h
+
+- formát dat
+    - protokol: http
+    - datový typ: json
+    - [validační schéma: datasourceMSO](https://gitlab.com/operator-ict/golemio/code/modules/parkings/-/blob/development/src/schema-definitions/index.ts)
+    - [příklad vstupních dat](https://gitlab.com/operator-ict/golemio/code/modules/parkings/-/blob/development/test/integration-engine/data/parking-lots-data-input.json)
+
+
+- frekvence stahování
+
+    - cron definice:
+        - cron.dataplatform.parkings.saveParkingLotsPrague (`0 0 */6 * * *`)
+        - cron.dataplatform.parkings.saveParkingLotsMeasurementsPrague (`0 */5 * * * *`)
+
+- název rabbitmq fronty
+    - dataplatform.parkings.saveParkingLotsPrague
+    - dataplatform.parkings.saveParkingLotsMeasurementsPrague
+
+
+## Zpracování dat / transformace
+
+Při transformaci dat lokací data obohacujeme o adresu parkoviště, která vychází z centroidu geometrie daného parkoviště a získává se z Photon API metodou `GeocodeApi.getAddressByLatLngFromPhoton` v modulu Core.
+
+### Worker *ParkingsWorker*
+
+#### *saveParkingZonesPrague*
+
+- vstupní rabbitmq fronta
+    - název: `dataplatform.parkings.saveParkingZonesPrague`
+    - bez parametrů
+- datové zdroje
+    - dataSourceTSK (ftp),
+    - dataSourceTariffTSK (ftp),
+    - dataSourceIPR
+- transformace
+
+    Data pro `parkings` - TSK zdroj rozšiřujeme o geodata z Opendat IPR (geometrie stejné zóny mergujeme v jednu), které mají přesnější polohu parkovišť. Kde jsou k dispozici, nahrazujeme geometrii TSK.
+    Data pro `parkings_location` - IPR zdroj (původní detailní geometrie) rozšiřujeme o geodata z TSK, pouze kdyžkteré mají přesnější polohu parkovišť. Kde jsou k dispozici, nahrazujeme geometrii TSK.
+    - [TSKParkingTransformation](https://gitlab.com/operator-ict/golemio/code/modules/parkings/-/blob/development/src/integration-engine/TSKParkingTransformation.ts) - mapování pro `parkingsModel` a `parkingsLocationModel`
+    - [TSKParkingTariffTransformation](https://gitlab.com/operator-ict/golemio/code/modules/parkings/-/blob/development/src/integration-engine/TSKParkingTariffTransformation.ts) - mapování pro `parkingsTariffsModel`
+    - [IPRParkingTransformation](https://gitlab.com/operator-ict/golemio/code/modules/parkings/-/blob/development/src/integration-engine/IPRParkingTransformation.ts) - mapování pro `parkingsModel` a `parkingsLocationModel`
+- data modely
+    - parkingsModel -> (schéma public) `parkings`
+    - parkingsLocationModel -> (schéma public) `parkings_location` (detailnější geometrie, která vychází z položek IPRu)
+    - parkingsTariffsModel -> (schéma public) `parkings_tariffs`
+- Důležité informace pro zpracování dat ze zdroje TariffTSK
+    - U parkovišť ZPS pod správou TSK nastaveno ve payment_method hodnotu `litacka`
+
+
+#### *saveParkingLotsPrague*
+
+- vstupní rabbitmq fronta
+    - název: `dataplatform.parkings.saveParkingLotsPrague`
+    - bez parametrů
+- datové zdroje
+    - dataSource (http),
+- transformace
+    - [ParkingLotsTransformation](https://gitlab.com/operator-ict/golemio/code/modules/parkings/-/blob/development/src/integration-engine/ParkingLotsTransformation.ts) - mapování pro `parkingsModel` a `parkingsLocationModel`
+- data modely
+    - parkingsModel -> (schéma public) `parkings`
+- důležité informace pro zpracování dat ze zdroje TSKParkings
+    - V budoucnu přibydou další hodnoty parking_type: `park_sharing` pro službu Mr. Parkit atp.
+    - Parametr `zone_type` je povinný pokud je `parking_type == on_street`. Jinak má být `NULL`
+    - `zone_free` - placeholder pro Zóny neplaceného stání (zone_type), které se budou integrovat v budoucnu
+
+
+#### *saveParkingLotsMeasurementsPrague*
+
+- vstupní rabbitmq fronta
+    - název: `dataplatform.parkings.saveParkingLotsMeasurementsPrague`
+    - bez parametrů
+- datové zdroje
+    - dataSource (http),
+- transformace
+    - [ParkingLotsTransformation](https://gitlab.com/operator-ict/golemio/code/modules/parkings/-/blob/development/src/integration-engine/ParkingLotsTransformation.ts) - mapování pro `parkingsModel` a `parkingsLocationModel`
+- data modely
+    - parkingsMeasurementsModel -> (schéma public) `parkings_measurements_part`
+    - parkingsMeasurementsActualModel -> (schéma public) `parkings_measurements_actual`
+
+  Všechny historické údaje jsou uloženy v tabulce `parkings_measurements_part`. Aktualizujeme pouze aktuální údaje v tabulce `parkings_measurements_actual`.
+
+
+#### *saveKoridConfToDB*
+
+- vstupní rabbitmq fronta
+    - název: `dataplatform.parkings.saveKoridConfToDB`
+    - bez parametrů
+- datové zdroje
+    - IG
+- transformace
+    - [KoridParkingConfigTransformation](https://gitlab.com/operator-ict/golemio/code/modules/parkings/-/blob/development/src/integration-engine/KoridParkingConfigTransformation.ts) - mapování pro `parkingsModel` a `parkingsLocationModel`
+- data modely
+    - parkingsModel -> (schéma public) `parkings`
+
+#### *saveKoridDataToDB*
+
+- vstupní rabbitmq fronta
+    - název: `dataplatform.parkings.saveKoridDataToDB`
+    - bez parametrů
+- datové zdroje
+    - IG
+- transformace
+    - [KoridParkingDataTransformation](https://gitlab.com/operator-ict/golemio/code/modules/parkings/-/blob/development/src/integration-engine/KoridParkingDataTransformation.ts) - mapování pro `parkingsModel` a `parkingsLocationModel`
+- data modely
+    - parkingsMeasurementsModel -> (schéma public) `parkings_measurements_part`
+    - parkingsMeasurementsActualModel -> (schéma public) `parkings_measurements_actual`
+
+### ZtpParkingZonesWorker
+
+#### *updateZtpParkings*
+
+- vstupní rabbitmq fronta
+    - název: `dataplatform.parkings.updateZtpParkings`
+    - bez parametrů
+- datové zdroje
+    - JSON stahovaný z IPR
+- transformace
+  Mapování `IZtpParkingJsonFeature` na `IParking` + doplnění o adresu.
+  Získává se z Photon API metodou `GeocodeApi.getAddressByLatLngFromPhoton` v modulu Core.
+- data modely
+    - parkingsModel -> (schéma public) `parkings`
+
+### Legacy mongo modely
+
+**CronJob and Worker method refreshDataInDB**
+
+`cron.dataplatform.parkings.refreshDataInDB` ("`0 */5 * * * *`" Dev a Prod)
+
+Datasource TSKParkings, Transformovaná data jsou uložena v tabulce `public.parkings`
+
+Na základě dat metoda generuje 3 události RabbitMQ:
+
+- RabbitMQ send Message `saveDataToHistory`
+- RabbitMQ send Message `updateAddressAndDistrict`
+- RabbitMQ send Message `updateAverageOccupancy`
+
+
+## Uložení dat
+
+- typ databáze
+    - PSQL
+- databázové schéma
+    - ![parkings er diagram](assets/parkings_erd.png)
+- retence dat
+    - `parkingsModel`, `parkingsLocationModel`, `parkingsMeasurementsActualModel`, `parkingsTariffsModel` update
+    - `parkingsMeasurementsModel` historizace bez promazávání
+
+## Output API
+
+### Obecné
+
+-   Zdroj pro api
+    -   PSQL databáze viz výše
+-   OpenAPI dokumentace
+    -   [OpenAPI](./openapi.yaml)
+-   veřejné / neveřejné endpointy
+    -   částečně veřejná na úrovni filtrování podle poskytovatele dat
+-   postman kolekce
+    -   TBD
+
+#### _/parking_
+
+#### _/parking/:id_
+
+-   zdrojové tabulky
+    -   parkings
+    -   parkings_measurements_actual
+-   implementováno dodatečně
+    -   `reservation_url` - přidáno volitelný atribut, který použijeme v datech od MPLA
+    -   Nový číselník `payment_methods`. Example: `{ payment_methods: ["card_online", "cash"] }`
+
+#### _/parking/detail_
+
+#### _/parking/detail/:id_
+
+- zdrojové tabulky
+    - parkings
+    - parkings_location
+- detailnejší geometrie, vychází z OpenData IPR a doplňuje parametry z TSK (ftp)
+
+#### _/parking/tariffs/_
+
+#### _/parking/tariffs/:tariffId_
+
+-   zdrojové tabulky
+    -   parkings_tariffs
+
+#### _/parking/measurements_
+
+-   zdrojové tabulky
+    -   parkings_measurements_part
+-   implementováno dodatečně
+    -   stránkovací metadata jsou zahrnuta v odpovědi ve formách response headers (`X-Total-Count`, `Link`)
+    -   implementována možnost dotazování pomocí parametrů `pageSize` a `page`