magico.prototype/prototype/telemetria/README.MD

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ę.