Telemetria: INIT i wstępna makieta

prototype/telemetria/README.MD

@@ -0,0 +1,196 @@
+Opis Biznesowy Aplikacji: telemetry.magico (Telemetry Manager)
+1. Wstęp i Cel Projektu
+telemetry.magico to nowoczesna, przemysłowa platforma klasy IoT (Internet of Things) oraz czasu rzeczywistego (Real-Time Monitoring), zintegrowana z ekosystemem biznesowym magico.pro.
+
+Głównym celem aplikacji jest agregacja, wizualizacja oraz analiza danych telemetrycznych pochodzących z rozproszonych urządzeń pomiarowych, sensorów i sterowników przemysłowych. Kluczowym założeniem biznesowym jest pełna agnostyczność danych (generyczność) – system projektowany jest w taki sposób, aby rodzaj monitorowanej infrastruktury (np. poziom gazu w zbiornikach, mikroklimat w kurnikach, parametry pracy maszyn HVAC) nie wpływał na strukturę rdzenia aplikacji, a jedynie na warstwę prezentacji danych i konfiguracji urządzeń.
+
+2. Grupa Docelowa i Zastosowanie Biznesowe
+Aplikacja odpowiada na potrzeby przedsiębiorstw zarządzających rozproszoną infrastrukturą techniczną. Przykładowe scenariusze wdrożeniowe obejmują:
+
+Sektor Energetyczny / Gazowy (Pierwsze wdrożenie): Monitoring poziomu napełnienia zbiorników LPG/CNG, ciśnienia oraz detekcja anomalii i wycieków. Optimale planowanie logistyki dostaw surowca.
+
+Agrotechnika (Smart Farming): Monitorowanie temperatury, wilgotności, poziomu CO2 czy zużycia paszy w obiektach inwentarskich (kurniki, chłodnie).
+
+Smart Building & Industry: Monitorowanie parametrów pracy maszyn, zużycia energii elektrycznej, statusów online/offline urządzeń produkcyjnych.
+
+3. Kluczowe Korzyści Biznesowe (Value Proposition)
+Redukcja kosztów operacyjnych: Automatyczna kontrola stanu urządzeń eliminuje konieczność fizycznych i rutynowych inspekcji obiektów przez pracowników.
+
+Zapobieganie awariom i przestojom: System wczesnego ostrzegania informuje o stanach krytycznych (np. drastyczny spadek ciśnienia, odcięcie zasilania), zanim wpłyną one na ciągłość biznesową.
+
+Optymalizacja logistyczna: Na podstawie trendów zużycia (np. gazu) system pozwala precyzyjnie planować terminy kolejnych dostaw lub serwisów.
+
+Skalowalność środowiska magico.pro: Moduł telemetryczny wymienia dane z innymi aplikacjami w ekosystemie (np. generowanie automatycznych ticketów w helpdesk.magico przy awarii sensora lub fakturowanie zużycia przez invoice.magico).
+
+4. Architektura Funkcjonalna Systemu (Struktura Modułowa)
+Aplikacja logicznie dzieli się na 5 głównych obszarów funkcjonalnych, które stanowią podstawę do zaprojektowania interfejsu użytkownika (UI):
+
+4.1. Dashboard (Pulpit Zarządczy)
+Centrum dowodzenia menedżera operacyjnego. Zapewnia natychmiastowy wgląd w kondycję całego parku maszynowego/sieci czujników bez konieczności przeklikiwania się przez poszczególne obiekty.
+
+KPI Statusów: Zagregowane liczniki urządzeń (Wszystkie, Online, Offline, W trakcie serwisu).
+
+Sekcja Alertów: Lista obiektów, które przekroczyły zdefiniowane normy bezpieczeństwa (kolorystyka czerwona/pomarańczowa).
+
+Geolokalizacja: Mapa z oznaczonymi punktami pomiarowymi (opcjonalnie, na podstawie koordynatów GPS wysyłanych przez minikomputery).
+
+4.2. Moduł: Urządzenia (Infrastruktura i Integracje)
+Miejsce zarządzania fizycznymi punktami pomiarowymi. Moduł opiera się na sztywnych definicjach typów urządzeń, pisanych przez deweloperów.
+
+Katalog urządzeń: Przeglądanie, filtrowanie po lokalizacji i typie.
+
+Kreator urządzeń (Provisioning): 1. Wybór predefiniowanego typu (np. Sensor-LPG-v2).
+2. Dynamiczny formularz konfiguracyjny (system podpowiada pola unikalne dla typu: np. maksymalna pojemność w litrach, adres IP, częstotliwość raportowania).
+3. Wygenerowanie bezpiecznego tokenu dostępowego API (Bearer Token) dla minikomputera brzegowego.
+
+4.3. Moduł: Aktualny Stan (Live Monitor)
+Narzędzie dedykowane dla operatorów i techników. Pozwala na podgląd zachowania wybranego obiektu w czasie rzeczywistym.
+
+Dynamiczny Grid Interfejsu: Layout dopasowuje się do typu urządzenia. Jeśli urządzenie mierzy 2 parametry, wyświetlane są 2 kafelki/wskaźniki zegarowe (gauges). Jeśli mierzy 10 parametrów – interfejs generuje adekwatną liczbę kontenerów.
+
+Wykresy Live: Wizualizacja trendu z ostatnich minut/godzin z automatycznym odświeżaniem danych.
+
+4.4. Moduł: Raporty i Historia (Analityka)
+Narzędzie służące do retrospektywnej analizy danych i wyciągania wniosków biznesowych.
+
+Agregacja danych: Filtrowanie według ram czasowych (dni, tygodnie, miesiące) oraz konkretnych parametrów.
+
+Eksport danych: Generowanie zestawień do formatów analitycznych (CSV, Excel) w celu dalszej obróbki lub audytów.
+
+Analiza trendów: Narzędzia wykresów liniowych umożliwiające nałożenie na siebie różnych metryk w celu znalezienia korelacji (np. wpływ temperatury otoczenia na ciśnienie w zbiorniku).
+
+4.5. Moduł: Ustawienia (Administracja)
+Konfiguracja zachowania systemu oraz progów bezpieczeństwa.
+
+Zarządzanie alertami (Progi krytyczne): Definiowanie reguł biznesowych typu: „Jeśli parametr gas_level na dowolnym urządzeniu typu gas_tank spadnie poniżej 15%, wyślij powiadomienie”.
+
+Zarządzanie uprawnieniami: Integracja z systemem uprawnień magico.pro (kto może tylko przeglądać wykresy, a kto ma prawo dodawać nowe urządzenia).
+
+5. Model Operacyjny (Jak to działa w praktyce?)
+Warstwa Fizyczna (Edge): Przy zbiorniku lub w kurniku znajduje się minikomputer (np. sterownik przemysłowy, Raspberry Pi, brama Teltonika). Odpytuje on lokalne czujniki fizyczne (poprzez Modbus, OneWire itp.).
+
+Warstwa Transmisyjna (API): Minikomputer formatuje uzyskane dane do ujednoliconego formatu JSON i za pomocą zapytania HTTP POST (zabezpieczonego tokenem) wypycha je do chmury telemetry.magico.
+
+Warstwa Przetwarzania (Core): Aplikacja identyfikuje urządzenie po tokenie, sprawdza jakie metryki zostały przesłane, zapisuje je w bazie danych serii czasowych (Time-Series format) i ewentualnie uruchamia procesy sprawdzania alertów.
+
+Warstwa Prezentacji (UI): Użytkownik końcowy widzi przetworzone, czytelne dane na wykresach i widgetach w panelu HTML.
+
+
+# Dokumentacja Funkcjonalna Modułów: telemetry.magico
+
+Ten dokument zawiera szczegółowy opis wymagań, logiki biznesowej oraz struktury interfejsu (UI) dla poszczególnych modułów aplikacji. Służy jako bezpośredni brief do przygotowania makiety HTML (Bootstrap) w ramach środowiska magico.pro.
+
+---
+
+## 1. Moduł: Dashboard (Pulpit Zarządczy)
+
+### 1.1. Cel biznesowy
+Zapewnienie użytkownikowi (zarządcy, dyspozytorowi) błyskawicznej oceny stanu technicznego i operacyjnego całej infrastruktury urządzeń bez konieczności wchodzenia w szczegóły każdego z nich.
+
+### 1.2. Struktura i Układ UI (Makieta HTML)
+* **Górny pasek statystyk (KPI Cards):** Cztery małe, sąsiadujące kafelki (`.card`) w jednym rzędzie:
+    * **Wszystkie urządzenia:** Łączna liczba zarejestrowanych maszyn (kolor neutralny / podstawowy magico).
+    * **Online:** Urządzenia, od których odebrano dane w zdefiniowanym oknie czasowym (zielony badge/tekst, ikona sygnału).
+    * **Offline:** Urządzenia, które utraciły łączność (czerwony badge/tekst, ikona wykrzyknika).
+    * **Aktywne Alerty:** Liczba urządzeń, na których aktualnie przekroczone są parametry krytyczne (pomarańczowy/czerwony puls).
+* **Główna sekcja (Układ dwukolumnowy - `row` z podziałem `col-md-8` i `col-md-4`):**
+    * **Kolumna Lewa (Szeroka): Tabela "Krytyczne stany i alerty".** Lista urządzeń wymagających natychmiastowej uwagi. Kolumny: Nazwa urządzenia, Typ, Lokalizacja, Parametr przekroczony (np. *Poziom gazu: 8%*), Czas wystąpienia, Akcja (Przejdź do Live Monitora).
+    * **Kolumna Prawa (Wąska): Widget "Ostatnie zdarzenia" (Activity Log).** Lista typu timeline (oś czasu) pokazująca ostatnie zmiany statusów (np. *10:15 - Urządzenie 'Zbiornik 3' przeszło w tryb OFFLINE*, *09:42 - Urządzenie 'Kurnik B' zarejestrowało spadek temperatury*).
+
+### 1.3. Logika i Zachowanie (JS / Backend)
+* **Definicja Offline:** Urządzenie zmienia status na Offline automatycznie, jeśli czas od ostatniego odczytu (`last_seen_at`) jest większy niż dwukrotność jego zadeklarowanego interwału wysyłki danych.
+* **Interakcja:** Kliknięcie w dowolny wiersz na liście alertów przenosi użytkownika bezpośrednio do widoku "Aktualny stan" (Live Monitor) z wybranym już tym konkretnym urządzeniem.
+
+---
+
+## 2. Moduł: Urządzenia (Device Management & Provisioning)
+
+### 2.1. Cel biznesowy
+Zarządzanie bazą fizycznych urządzeń oraz procesem ich bezpiecznego uwierzytelniania w chmurze magico.pro.
+
+### 2.2. Struktura i Układ UI (Makieta HTML)
+Moduł składa się z dwóch głównych widoków: **Listy urządzeń** oraz **Kreatora dodawania**.
+
+#### Widok: Lista Urządzeń (Tabela główna)
+* **Filtry nad tabelą:** Wyszukiwarka tekstowa, dropdown z filtrem po "Typie urządzenia" (Wszystkie, Zbiornik Gazu, Kurnik itp.) oraz filtr statusu (Online/Offline).
+* **Tabela danych:**
+    * Nazwa (np. *Zbiornik LPG #1 - Stalowa Wola, ul. Przemysłowa*).
+    * Typ urządzenia (Badge z ikoną dedykowaną dla typu, np. ikona płomienia dla gazu, ikona termometru dla kurnika).
+    * Ostatni kontakt (Względny format daty, np. *Przed 2 min*, *3 dni temu*).
+    * Status (`.badge-success` dla Online, `.badge-danger` dla Offline).
+    * Akcje: Przycisk "Podgląd Live" (ikona oka), "Edycja" (ikona ołówka).
+
+#### Widok: Kreator dodawania (Step-by-Step Wizard)
+Zrealizowany za pomocą zakładek (`nav-tabs` lub niestandardowy stepper komponentu Bootstrap).
+* **Krok 1: Wybór typu urządzenia.** Kafelki z ikonami i opisami predefiniowanych integracji (np. `Karta 1: Zbiornik Gazu standard (Modbus/LPG)`, `Karta 2: Sterownik Mikroklimatu Kurnika v1`). Użytkownik klika jeden z nich i przechodzi dalej.
+* **Krok 2: Konfiguracja parametrów (Dynamiczny formularz).** Pola ładują się w zależności od wyboru w Kroku 1:
+    * *Dla Zbiornika Gazu:* Pole tekstowe: Pojemność nominalna (litry), Maksymalne ciśnienie bezpieczne (bar), Stały adres IP minikomputera (opcjonalnie).
+    * *Dla Kurnika:* Pole liczbowe: Liczba stref grzewczych, Liczba wentylatorów, Interwał próbkowania (w sekundach).
+* **Krok 3: Generowanie tokenu.** Ekran podsumowania, na którym system wyświetla wygenerowany unikalny klucz API (`Device API Token`). Zawiera przycisk "Kopiuj do schowka".
+
+### 2.3. Logika i Zachowanie (JS / Backend)
+* **Bezpieczeństwo tokenów:** Token API (`api_token`) jest widoczny w pełnej krasie tylko raz – podczas tworzenia urządzenia (Krok 3). Potem w bazie jest haszowany lub maskowany (np. `mag_tlm_•••••••••1a2b`).
+* **Dynamiczne renderowanie:** W makiety HTML warto wbudować mechanizm (np. proste przełączanie klasami `d-none`), który zasymuluje, jak zmienia się formularz w Kroku 2 w zależności od wybranego w Kroku 1 typu urządzenia.
+
+---
+
+## 3. Moduł: Aktualny Stan (Live Monitor)
+
+### 3.1. Cel biznesowy
+Umożliwienie technikowi lub operatorowi zdalnego podglądu parametrów pracy wybranego obiektu w trybie "tu i teraz" w celu weryfikacji awarii lub kontroli procesów.
+
+### 3.2. Struktura i Układ UI (Makieta HTML)
+* **Górny pasek kontekstowy:** Duży Dropdown (`<select>` z obsługą wyszukiwania, np. Select2 w Bootstrapie) do wyboru urządzenia. Obok dropdownu wyświetla się duży badge aktualnego statusu wybranego urządzenia (Online/Offline) oraz data i godzina ostatniego odebranego pakietu danych.
+* **Siatka wskaźników (Dynamic Grid):** Rząd kafelków (`row-cols-1 row-cols-md-3 g-4`), gdzie każdy kafelek prezentuje **jedną metrykę/kanał danych**.
+    * *Przykład komponentu wskaźnika:* Duża wartość numeryczna w centrum (np. **22.4 °C** lub **74.5 %**), pod nią nazwa metryki ("Temperatura strefa A", "Poziom napełnienia"), a na dole mały badge informujący o trendzie w ciągu ostatniej godziny (np. zielona strzałka w górę "Wzrost o 1.2%").
+* **Dolna sekcja: Mini-wykres Live.** Wykres liniowy (zajmujący pełną szerokość `col-12`), pokazujący dane z wybranej kluczowej metryki z ostatnich 2 godzin, odświeżany automatycznie bez przeładowania strony.
+
+### 3.3. Logika i Zachowanie (JS / Backend)
+* **Agnostyczność interfejsu:** Layout HTML musi być przygotowany na to, że kafelków wskaźników może być 2 (dla prostego zbiornika), a może być 12 (dla rozbudowanego kurnika). Kafelki powinny płynnie zawijać się do kolejnych rzędów dzięki klasom flexbox Bootstrapa.
+* **Odświeżanie danych:** Widok symuluje połączenie WebSocket lub regularny odpytywacz (Polling AJAX) co 10-30 sekund, który aktualizuje wartości liczbowe w kafelkach oraz dopisuje nowy punkt na mini-wykresie.
+
+---
+
+## 4. Moduł: Raporty i Historia (Analityka Historyczna)
+
+### 4.1. Cel biznesowy
+Dostarczanie twardych danych analitycznych do celów optymalizacyjnych (planowanie dostaw gazu, audyty warunków chowu drobiu) oraz eksport danych do zewnętrznych systemów lub arkuszy kalkulacyjnych.
+
+### 4.2. Struktura i Układ UI (Makieta HTML)
+* **Pasek filtrów (Górny horyzontalny formularz card):**
+    * Wybór urządzenia (Dropdown).
+    * Wybór metryk (Multiselect checkbox / dropdown – np. użytkownik chce zobaczyć tylko poziom gazu, ignorując napięcie baterii minikomputera).
+    * Zakres dat (Komponent Date-Range Picker: Od, Do, wraz z szybkimi filtrami: *Dzisiaj, Ostatnie 7 dni, Ten miesiąc*).
+    * Przycisk akcji: "Generuj raport" (niebieski) oraz "Eksportuj do CSV" (zielony).
+* **Sekcja Główna - Wykres Analityczny:** Duży kontener wykresu liniowego (np. przy użyciu biblioteki Chart.js wbudowanej w layout Bootstrap). Wykres musi obsługiwać wiele osi Y, jeśli użytkownik porównuje różne jednostki (np. lewa oś dla temperatury w `°C`, prawa dla wilgotności w `%`).
+* **Sekcja Dolna - Tabela Surowych Danych:** Tabela z paginacją (np. stylizowana pod DataTables). Kolumny: Data i godzina (Timestamp), Nazwa metryki, Wartość, Jednostka.
+
+### 4.3. Logika i Zachowanie (JS / Backend)
+* **Agregacja danych (Downsampling):** Ponieważ dane telemetryczne przyrastają w ogromnym tempie, backend przy raportach z długich okresów (np. 3 miesiące) nie może przesłać milionów rekordów do JS. System musi agregować dane w locie (np. średnia godzinowa lub średnia dobowa) w zależności od wybranego zakresu czasu.
+
+---
+
+## 5. Moduł: Ustawienia (Settings & Alert Rules)
+
+### 5.1. Cel biznesowy
+Konfiguracja zachowań automatycznych systemu, w tym definiowanie progów bezpieczeństwa dla zbieranych danych.
+
+### 5.2. Struktura i Układ UI (Makieta HTML)
+Zorganizowany w formie pionowych zakładek (List-group tabs po lewej stronie, zawartość po prawej).
+
+#### Zakładka 1: Reguły Alertów (Alerts Configuration)
+* **Lista aktywnych reguł:** Tabela pokazująca zdefiniowane progi.
+* **Przycisk "Dodaj nową regułę"**, który otwiera modal (okno pop-up):
+    * Dropdown: "Jeśli urządzenie typu..." (Wybór typu, np. *Zbiornik Gazu*).
+    * Dropdown: "...zarejestruje parametr..." (Dynamiczna lista metryk dla typu, np. *gas_level*).
+    * Dropdown warunku: (Mniejsze niż, Większe niż, Równe).
+    * Pole numeryczne: Wartość progu (np. *15*).
+    * Sekcja akcji: Checkboxy "Wyślij e-mail do administratora", "Załóż ticket w helpdesk.magico".
+
+#### Zakładka 2: Globalna Konfiguracja Telemetrii
+* Formularze konfiguracyjne:
+    * Czas retencji danych (Dropdown: *Przechowuj surowe dane przez: 3 miesiące / 6 miesięcy / rok*).
+    * Domyślny interwał sprawdzania statusów offline (np. *Co ile minut system ma weryfikować brak kontaktu z minikomputerami*).
+
+### 5.3. Logika i Zachowanie (JS / Backend)
+* **Integracja wewnątrzmagico:** Powiązanie akcji alertu z modułem `helpdesk.magico` musi opierać się na wewnętrznym API ekosystemu magico.pro. W makiecie należy przewidzieć elementy UI (np. selecty grup użytkowników, kategorie ticketów), które odzwierciedlają tę integrację.