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 (`