@golemio/rush-hour-aggregation 1.2.1 → 1.2.3-dev.1490349699

package/docs/asyncapi.yaml

@@ -0,0 +1,81 @@
+asyncapi: 3.0.0
+info:
+    title: Rush Hour Aggregation
+    version: 1.0.0
+    description: This document describes internal RabbitMQ queues of the Rush Hour Aggregation module. The module is responsible for aggregating traffic data from various sources for the purposes of the project Praha dopravní.
+    contact:
+        name: Golemio Prague Data Plaform
+        email: golemio@operatorict.cz
+        url: https://golemio.cz
+operations:
+    rush-hour-aggregation.aggregateData:
+        action: "send"
+        channel:
+            $ref: "#/channels/rush-hour-aggregation.aggregateData"
+    rush-hour-aggregation.refreshHistoricViews:
+        action: "send"
+        channel:
+            $ref: "#/channels/rush-hour-aggregation.refreshHistoricViews"
+channels:
+    rush-hour-aggregation.aggregateData:
+        address: dataplatform.rush-hour-aggregation.aggregateData
+        description: Aggregate traffic data of a given type from a given time period to database. If the given time period contains too much data, the task will be split into multiple subtasks. If no message is given, all types of data will be aggregated for time period of the last 10 minutes.
+        bindings:
+            amqp:
+                is: queue
+                queue:
+                    durable: true
+        messages:
+            empty:
+                $ref: "#/components/messages/emptyMessage"
+            data:
+                $ref: "#/components/messages/rush-hour-aggregation.aggregateData"
+    rush-hour-aggregation.refreshHistoricViews:
+        address: dataplatform.rush-hour-aggregation.refreshHistoricViews
+        description: Refresh historic database material views for traffic data aggregations
+        bindings:
+            amqp:
+                is: queue
+                queue:
+                    durable: true
+        messages:
+            empty:
+                $ref: "#/components/messages/emptyMessage"
+components:
+    messages:
+        emptyMessage:
+            title: Empty message
+        rush-hour-aggregation.aggregateData:
+            payload:
+                $ref: "#/components/schemas/rush-hour-aggregation.IAggregationTask"
+    schemas:
+        rush-hour-aggregation.IAggregationTask:
+            type: object
+            properties:
+                type:
+                    type: string
+                    description: Type of data to be aggregated
+                    enum:
+                        - SDDR
+                        - FCD
+                        - NDIC
+                        - WAZER
+                        - WAZEJ
+                from:
+                    type: string
+                    format: date-time
+                    description: Start of the time period to be aggregated
+                to:
+                    type: string
+                    format: date-time
+                    description: End of the time period to be aggregated
+                updateOnDuplicate:
+                    type: boolean
+                    description: If true, the aggregation will update existing records in the database. Defaults to `false`.
+                refreshView:
+                    type: boolean
+                    description: If true, the traffic data materialized views will be refreshed after the aggregation. Defaults to `false`.
+            required:
+                - type
+                - from
+                - to

package/docs/implementation_documentation.md

@@ -0,0 +1,92 @@
+# Implementační dokumentace modulu *Rush Hour Aggregator*
+
+## Záměr
+
+Modul agreguje dopravní data pro projekt Praha zasekaná.
+
+## Vstupní data
+
+Vstupem jsou 4 datové sady již existující v datové platformě:
+
+    - SDDŘ (TSK) - zdroj public.tsk_std_measurements, public.tsk_std
+    - FCD - public.fcd_traff_params_part
+    - NDIC - public.ndic_traffic_info
+    - Waze - public.wazeccp_jams
+
+### Data aktivně stahujeme
+
+Data se aktivně agregují pomocí cronu každých 5 minut. Kvůli možnému zpoždění obdržení některých dat je nastaven překryv a dohromady agreguje se posledních 10 minut. Existující položky jsou aktualizovaný na nový stav. Pro cron je nastavena priorita 1, pro VIP odbavení oproti historické agregaci viz níže.
+
+Příklad nastavení cronu:
+```json
+  {
+    "cronTime": "0 */5 * * * *",
+    "exchange": "dataplatform",
+    "message": "",
+    "routingKey": "cron.dataplatform.rush-hour-aggregation.aggregateData",
+    "options": {
+      "priority": 1
+    }
+  }
+```
+
+
+Zároveň je také možné spustit historickou agregaci, ať už pro doplnění historických dat nebo v případech jejich změny. Tato agregace spouští manuálně vložením message pro rabbit mq viz readme dokument modulu.
+
+## Zpracování dat / transformace
+
+
+Pro účely agregace bylo vytvořeno 5 sql skriptů, které jsou samostatne uloženy ve složce ./templates/sqlQueries. V každém skriptu jsou použity parametry *from* a *to* a dle typu data jsou uvozeny \$ nebo :. Obě verze jsou rozpoznatelné a spustitelné v DBeaver, ale pro kód **nejsou zaměnitelné**. V případě : kód resp. knihovna sequelize se stará o doplnění proměných a v případě \$ se o to stará databázová část. Pro jednoduší sql skripty Waze, Fcd je použit \$. Pro složitější NDIC, SSDŘ se používá :.
+
+Po nahraní dat do databáze se ještě "concurrently" obnoví nasledující materializované pohledy:
+
+    - fcd_events_snapshots_latest
+    - ndic_events_full_snapshots_latest
+    - tsk_std_last_30min_snapshots_latest
+    - waze_jams_snapshots_latest
+    - waze_jams_snapshots_latest
+
+Interní RabbitMQ fronty jsou popsány v [AsyncAPI](./asyncapi.yaml).
+
+### *AggregationWorker* - Metoda *aggregateData*:
+
+Podporuje několik scénářů zpracovaní podle obdržené zprávy:
+
+1) Prázdná zpráva
+Je obvykle generována cronem a spustí pro každý z typů agregace zpracování za posledních X minut dle nastavení workeru. V současnosti je tato hodnota nastavena na 10 minut.
+
+2) Validní json zpráva
+Validní json zpráva obsahuje údaje od, do a typ dat (v angličtině). Pro příklad zprávy viz readme modulu. Následně je zkontrolovano zda-li období zpracování není příliš dlouhé. Pro každý typ vstupních dat je toto období určeno jinak, dle množství generovaných dat a náročnosti zpracování:
+
+    | data | max období |
+    | --- | --- |
+    | FCD | 30 minut |
+    | NDIC | 2 hodiny |
+    | SDDŘ | 2 hodiny |
+    | Waze | 6 hodin |
+
+Pokud je období dlouhé tak se rozdělí na subtasky, které se uloží do fronty ke zpracování.
+V opačném případě se spustí agregační sql skript pro vybraný typ dat a výsledek se uloží do vybrané tabulky v db schématu praha_dopravni.
+
+### *AggregationWorker* - Metoda *refreshHistoricViews*:
+
+Je spuštěna cronem jednou za 24h s prázdnou zprávou a obnovuje "concurrently" historické pohledy, které připravují časová rozpětí pro již připravené agregace.
+
+Seznam pohledů:
+  - fcd_events_snapshots_history
+  - ndic_events_full_snapshots_history
+  - tsk_std_last_30min_snapshots_history
+  - waze_jams_snapshots_history
+  - waze_jams_snapshots_history
+
+
+### Obecné
+
+- typ databáze
+  - PSQL
+- datábázové schéma
+  - praha_dopravni, public
+- migrační skripty
+  - ano, součastí modulu
+- retence dat
+  - n/a

package/docs/index.md

@@ -0,0 +1,3 @@
+# @golemio/rush-hour-aggregation
+
+This module is intended for use with Golemio services. Refer [here](https://gitlab.com/operator-ict/golemio/code/modules/core/-/blob/development/README.md) for further information on usage, local development and more.

package/docs/keeping_a_changelog.md

@@ -0,0 +1,48 @@
+# Udržování changelogu v projektech
+
+_Tohle je výstup z [general#345](https://gitlab.com/operator-ict/golemio/code/general/-/issues/345)_
+
+Začínáme zavádět changelogy podle [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) a semantického verzování
+
+```markdown
+## [version] - release date
+
+### type of action
+
+-   Description (([project#issue](link to the issue)))
+```
+
+- Během vývoje a code reviews je potřeba kontrolovat existenci CHANGELOG.md a zda byl přidán záznam do Unreleased sekce pod správný typ změny
+  - Added
+  - Changed
+  - Deprecated
+  - Removed
+  - Fixed
+  - Security
+- Rovněž je potřeba ujistit, že aktuální kopie [keeping_a_changelog.md](/introduction/keeping_a_changelog.md) se nachází ve složce _docs/_, pokud tam už není
+- Před releasem nahradit Unreleased za _[version] - release date_
+- Po release bumpnout verzi a přidat novou Unreleased sekci (v případě částečného release přesunout nenasazené změny do Unreleased)
+
+**Příklad changelogu pro pid modul**
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+
+-   Modularized migrations ([pid#53](https://gitlab.com/operator-ict/golemio/code/modules/pid/-/issues/53))
+
+## [2.0.12] - 2021-10-18
+
+### Fixed
+
+-   Empty array of tripsIds in updateDelay
+```
+
+**Příklad projektů se zavedeným changelogem**
+
+- [Golemio CLI](https://gitlab.com/operator-ict/golemio/code/golemio-cli/-/blob/development/CHANGELOG.md)
+- [PID Module](https://gitlab.com/operator-ict/golemio/code/modules/pid/-/blob/development/CHANGELOG.md)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@golemio/rush-hour-aggregation",
-    "version": "1.2.1",
+    "version": "1.2.3-dev.1490349699",
     "description": "Rush hour data aggregation for Praha dopravní project",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",