СВІТЛО⚡️ БЕЗПЕКА (POWER-SAFETY-UA) - Docker Edition

Power-Safety-UA (колишній Flash Monitor Kyiv) — це професійна автономна система моніторингу критичної інфраструктури та екологічної безпеки. Проєкт забезпечує прецизійний моніторинг електропостачання в реальному часі, інтелектуальну обробку графіків відключень (DTEK/Yasno), відстеження повітряних тривог, якості повітря (AQI) та радіаційного фону.

Ця гілка (main) містить Docker Edition проєкту, призначену для швидкого, портативного та ізольованого розгортання в будь-якому середовищі. Це повністю контейнеризована версія, яка є стандартом для сучасних серверів.

Статус проєкту: Stable v3.9.29 (Оновлено: 09.2026) Архітектура: FastAPI + Docker Compose + JSON Flat-DB & SQLite WAL Бренд: Weby Homelab

• Runtime: Python 3.12 (slim-bookworm) у мультиплатформному контейнері (linux/amd64, linux/arm64).
• Backend: FastAPI (Async) + Uvicorn для миттєвої реакції на Push-сигнали, Web Push (VAPID) та SSE.
• Storage: Гібридне сховище: легковагі JSON-файли для стану та розкладів + SQLite у режимі WAL (power_safety.db) для швидкого concurrent-логування подій.
• Observability: Prometheus метрики (/metrics), структуроване логування (structlog) та дворівневі перевірки працездатності (/health/live, /health/ready, /health/worker).
• Isolation: Повна контейнеризація Docker, безпечний запуск від непривілейованого користувача appuser (uid 1000).
• Persistence: Використання Docker Volumes для збереження бази даних (data/), графіків та логів.

Повністю автономний веб-інтерфейс у стилі Glassmorphism для керування всіма аспектами системи без необхідності редагування конфігураційних файлів через SSH.

• Асинхронна швидкодія: Асинхронний кеш унеможливлює дедлоки при одночасній роботі воркера та користувача.
• Інтелектуальні бекапи: Створення ручних та автоматичних точок відновлення конфігурації.
• Безпека (Zero-Trust): Захищена мобільна картка авторизації, зберігання токенів у sessionStorage, передача через заголовки X-Admin-Token / Bearer, маскування секретів у відповідях, логування лише sha256-відбитків та захист від LFI/SSRF.
• Універсальне збереження: Надійна валідація схем конфігурації (AdminConfigRequest) із підтримкою як плаского, так і вкладеного JSON.

Багаторівнева система відстеження небезпеки з захистом від збоїв зовнішніх сервісів:

• 🟡 Жовтий рівень (Warning): Підвищена небезпека, загроза ударних БПЛА (дронів/шахедів) чи тактичної авіації.
• 🔴 Червоний рівень (Active): Безпосередня повітряна тривога, ракетна небезпека, швидкісні цілі.
• 🟢 Відбій (Clear): Автоматична фіксація відбою окремих рівнів або повної відміни небезпеки з точним розрахунком тривалості за кожною загрозою окремо.
• 🏙 Ізоляція тривог для Києва: Моніторинг та сповіщення ізольовані виключно для міста Київ (м. Київ, UID 31), повністю виключаючи хибні спрацьовування від тривог у Київській області.
• 🛡 Мультиджерельна стійкість: Інтелектуальне опитування Alerts.in.ua v3 з автоматичною швидкою крос-перевіркою через державний JAAM API та Ubilling API.
• 🧹 Фільтр застарілих фантомів (Stale Ghost Alerts Filter): Автоматичне відсікання старих записів (> 12 годин), що запобігає зависанню хибних тривог при збоях сторонніх скраперів.

Графічні звіти, live dashboard та Telegram використовують чотири незалежні канали:

• Факт — суцільна смуга; стан світла: teal «є» (💡) та rose «немає» (⚡️).
• План — нейтральний трек, а планове відключення позначене indigo і hatch-патерном.
• Тривога — спокійний dotted-трек для clear (🟢), amber для warning (🟡), red для critical (🔴).
• Невідомо — slate + ?/патерн; AQI — тонка environmental-смуга.
• Семантичні іконки: Лаконічні та зрозумілі символи в інтерфейсі та повідомленнях (💡/⚡️/🟡/🔴/🟢) з автоматичною зворотно-сумісною міграцією legacy-налаштувань.

Сумісність: report statistics зберігають legacy fallback розкладу без metadata, щоб не змінювати історичну математику; live dashboard показує Невідомо, якщо schedule_known відсутній або false.

• Дзвіночок сповіщень (🔕 ➔ 🔔): Миттєвий відгук інтерфейсу після надання дозволу браузера, стійке кешування ресурсів Service Worker та безпечна підписка на Web Push з таймаутом.
• Двомовний перемикач: Кнопка перемикання чітко відображає дію переходу на наступну мову (EN при українському інтерфейсі, UA при англійському) з локалізованими підказками.

Унікальний алгоритм, що мінімізує «інформаційний шум». Система автоматично переходить у стан спокою, якщо за останні 24 години не було відключень, а в планах на завтра немає обмежень (або режим активовано примусово через адмінку).

• Повне глушіння реактивних сповіщень: У режимі спокою бот пригнічує реактивні сповіщення про зміну стану мережі, а також повністю глушить усі сповіщення про повітряні тривоги в Telegram-каналі, щоб не турбувати мешканців чату під час стабільної роботи.
• Гарантована доставка підсумків: Навіть у Quiet Mode гарантовано доставляється фінальний підсумок доби та щопонеділковий тижневий графічний звіт (керується через telegram_daily_reports та telegram_weekly_reports) із транзакційною персистентністю (report_delivery_state.json) та захистом від дублювання.

Гібридна система обробки графіків. Якщо хоча б одне джерело вказує на відключення, система відображає його як пріоритетне. Старі записи ніколи не затираються «чистими» планами.

• 📊 Щоденний графік "План vs Факт" (Smart Daily Report)
• 📈 Тижнева аналітика відключень
• 🔴 Сповіщення про відключення світла з точністю до графіка
• 🟢 Сповіщення про увімкнення світла з точністю до графіка
• ⚠️ Миттєвий алерт про зміну графіків від ДТЕК
• 📈 Публікація графіків від ДТЕК та YASNO
• 🚨 Сповіщення про повітряну тривогу в Києві
• ✅ Сповіщення про відбій повітряної тривоги

flowchart BT
    %% ================================================
    %% НОВА КОНЦЕПЦІЯ 2026 для README.md
    %% "End-to-End Pipeline" — динамічний потік даних
    %% ================================================

    classDef external fill:#0f766e,stroke:#14b8a6,stroke-width:3px,color:#fff,rx:16px,ry:16px
    classDef core fill:#1e293b,stroke:#22d3ee,stroke-width:3.5px,color:#fff,rx:14px,ry:14px
    classDef gateway fill:#7c3aed,stroke:#a78bfa,stroke-width:3px,color:#fff,rx:16px,ry:16px
    classDef client fill:#1e293b,stroke:#60a5fa,stroke-width:3px,color:#fff,rx:16px,ry:16px
    classDef db fill:#1e293b,stroke:#ec4899,stroke-width:3px,color:#fff,rx:12px,ry:12px

    %% ====================== ЛІВА ЧАСТИНА: ДЖЕРЕЛА ДАНИХ ======================
    subgraph External ["🔌 Джерела даних"]
        direction TB
        Energy["⚡ Yasno / DTEK API<br>Розклади відключень"]:::external
        Alerts["🚨 Alerts.in.ua / JAAM / Ubilling<br>Повітряні тривоги (Yellow/Red)"]:::external
        Meteo["OpenMeteo + SaveEcoBot<br>Погода та AQI"]:::external
    end

    %% ====================== ЦЕНТР: CORE PIPELINE ======================
    subgraph Core ["⚙️ Power Safety Core<br>light_service.py + FastAPI"]
        direction TB

        Worker["🔄 Background Worker<br>power-safety-ua-worker<br>python app/run_background.py"]:::core

        subgraph Processing ["Обробка та логіка"]
            direction LR
            Rules["🛡️ Rules Engine<br>False Always Wins • Safety Net<br>Quiet Mode • Stale Filter"]:::core
            Reports["📊 Reports Generator<br>Matplotlib charts"]:::core
            Storage["💾 Storage<br>JSON Flat-DB + SQLite WAL<br>config • state • logs • db"]:::db
        end

        API["🔌 FastAPI Service<br>power-safety-ua<br>uvicorn app.main:app"]:::core
        TgClient["🤖 Telegram Client"]:::core
    end

    %% ====================== ШЛЮЗ ======================
    subgraph Gateway ["🔐 Cloudflare Tunnel<br>Zero Trust + Reverse Proxy"]
        CF["☁️ Cloudflare Tunnel<br>порт 5050"]:::gateway
    end

    %% ====================== ПРАВА ЧАСТИНА: КЛІЄНТИ ======================
    subgraph Clients ["👥 Інтерфейси користувачів"]
        direction TB
        PWA["📱 PWA Dashboard"]:::client
        Admin["🛠️ Admin Panel"]:::client
        Telegram["📨 Telegram Channel<br>+ Push Notifications"]:::client
    end

    %% ====================== ПОТІК ДАНИХ ======================
    Energy & Alerts & Meteo -->|Скрейпінг + Fetch| Worker

    Worker -->|Перевірка правил| Rules
    Rules -->|Рішення| Worker

    Worker -->|Збереження| Storage
    Storage -->|Читання стану| Worker

    Worker -->|Генерація| Reports
    Worker -->|Сповіщення| TgClient
    Reports -->|Графіки| TgClient

    Worker <-->|REST + SSE + SQLite| API

    API -->|Reverse Proxy| CF
    CF <-->|HTTPS + WSS| PWA
    CF <-->|HTTPS + X-Admin-Token| Admin
    TgClient -->|Bot API| Telegram

    %% Додаткові push-сповіщення
    API -.->|"Web Push API (VAPID)"| PWA

    %% ====================== Стиль для заголовків підграфів ======================
    classDef subgraphTitle fill:#0f172a,stroke:none,color:#64748b,font-size:15px

Для отримання детальної покрокової інструкції з розгортання проєкту за допомогою Docker та Docker Compose, перейдіть за посиланням нижче:

📖 ПОВНА ІНСТРУКЦІЯ З ВСТАНОВЛЕННЯ (DOCKER EDITION)

Цей проєкт поширюється на умовах ліцензії GNU General Public License v3.0 (GPLv3). Детальніше див. у файлі LICENSE.

• 🌐 Документація сайту (MkDocs)
• ⚙️ Налаштування Telegram та IoT
• Історія змін (CHANGELOG.md)
• 🔒 Політика безпеки (SECURITY.md)

Built in Ukraine under air raid sirens & blackouts ⚡
© 2026 Weby Homelab