Starokostiantyniv Power Outage Monitor

Автоматичний моніторинг планових та аварійних відключень електроенергії для Старокостянтинівської міської територіальної громади.

Парсер збирає дані з офіційного сайту hoe.com.ua, фільтрує лише населені пункти громади (місто Старокостянтинів та 66 сіл), зберігає їх, а потім за допомогою ШІ (Gemini 2.0 Flash) генерує інформаційну стрічку та пости для Telegram.

Особливості

• Два блоки: Збирач (без ШІ) та Оформлювач (з Gemini).
• Повністю безкоштовне розгортання на GitHub Pages + GitHub Actions.
• Ковзне вікно публікацій: стрічка завжди містить інформацію на сьогодні та завтра; Telegram-пости генеруються окремо на кожен день (до 5 днів наперед).
• Приватна адмінка з паролем для безпечного перегляду.
• Автоматичне очищення бази повідомлень після 7 днів.
• Інтерактивна адмінка: бігуча стрічка з ефектом "прилипання", розумне групування вулиць, таблиця сирих даних із деталізацією номерів будинків.
• Захист від помилок на сайті-джерелі (перевірка структури HTML, логування).
• Валідація результатів ШІ, щоб уникнути вигаданих даних.

Швидкий старт (локальна розробка)

1. Клонуйте репозиторій або відкрийте теку проекту в VS Code.
2. Встановіть залежності: pip install -r requirements.txt
3. Отримайте API-ключ Gemini на Google AI Studio та встановіть змінну середовища GEMINI_API_KEY.
4. Запустіть збір даних: python collector.py Перевірте data/outages_snapshot.json.
5. Згенеруйте повідомлення: python formatter.py Відкрийте admin.html у браузері (локально), щоб переглянути результати.

Розгортання на GitHub

1. Створіть публічний репозиторій на основі цього шаблону.
2. Додайте секрети у Settings → Secrets and variables → Actions: GEMINI_API_KEY та ADMIN_PASSWORD.
3. Увімкніть GitHub Pages: Deploy from branch main → / (root).
4. Запустіть Workflow вручну або дочекайтеся розкладу. Адмінка: https://yourusername.github.io/repo-name/admin.html

Розклад виконання

• Збір даних: щогодини (cron 0 * * * *). Оновлює outages_snapshot.json лише за наявності змін.
• Форматування: о 06:00 за Києвом (cron 0 6 * * *). Генерує стрічку (сьогодні+завтра) та Telegram-пости (на кожен день).

Файли адмінки

• feed.html – публічна біжуча стрічка (можна вбудувати на сайт).
• admin.html – закрита панель для перегляду стрічки та постів (без можливості редагування).

Ліцензія MIT

Підтримка При виявленні проблем створюйте Issue у репозиторії.