WeatherWise - Интерактивно уеб приложение за метеорологични статистики

Описание

WeatherWise е уеб приложение за визуализация и анализ на метеорологични данни. Приложението позволява преглед на текущото време, прогнози, исторически данни и климатични статистики за градове по целия свят. Включва интерактивен 3D глобус за избор на локация, система за потребителски акаунти, администраторски панел и модул за дарения.

Основни функционалности

• Текущо време за произволен град с температура, влажност, налягане, вятър и валежи
• 7-дневна прогноза и почасова прогноза
• Интерактивен 3D глобус с предварително зададени градове
• Търсене на градове по име с автоматично допълване
• Исторически данни за минали периоди с възможност за филтриране
• Графики и визуализации (температурни тенденции, сравнение на градове)
• Климатичен анализ и статистики
• Двуезичен интерфейс (български / английски)
• Автоматично определяне на местоположението на потребителя
• Динамични фонови изображения от Pexels API
• Система за регистрация, вход и потребителски профил
• Запазване на любими местоположения
• Администраторски панел за управление на потребители, региони, дарения и статистики
• Демо модул за дарения

Технологии

Компонент	Технология
Backend	Python 3, Flask 3.0
База данни	Microsoft SQL Server (MSSQL) с pyodbc
ORM	SQLAlchemy 2.0, Flask-SQLAlchemy
Миграции	Alembic
Автентикация	Flask-Login, Werkzeug (хеширане на пароли)
CSRF защита	Flask-WTF
Frontend	HTML5, CSS3, JavaScript (vanilla)
3D Глобус	Globe.gl
Графики	Plotly.js
API-та	Open-Meteo (прогноза и исторически данни), Pexels (изображения), Nominatim/OpenStreetMap (геокодиране)
Тестове	pytest, Selenium

Архитектура

Приложението следва MVC шаблон с разделяне на слоеве:

app/
  controllers/     - HTTP маршрути и обработка на заявки
  models/          - SQLAlchemy модели на данните
  repositories/    - Достъп до базата данни (CRUD операции)
  services/        - Бизнес логика
  templates/       - Jinja2 HTML шаблони
  static/          - CSS, JavaScript, изображения, JSON данни

Модели

• User - потребител с email, хеширана парола и роля (user/admin)
• Region - географски регион с име, държава и координати
• WeatherRecord - запис на метеорологични данни за регион
• ForecastRecord - запис на прогнозни данни за регион
• ClimateStatistic - климатична статистика за регион
• Donation - запис за дарение със сума, валута и статус
• SavedLocation - запазено местоположение на потребител
• UserPreference - потребителски настройки

Контролери

• main_controller - начална страница, API за фонови изображения, геокодиране, градове, преводи
• auth_controller - регистрация, вход, изход, смяна на парола
• weather_controller - API за текущо време и метеорологични данни
• forecast_controller - API за прогнози (дневна, почасова)
• history_controller - исторически данни и филтриране
• visualization_controller - графики и сравнения
• donation_controller - дарения (създаване, обработка, история)
• profile_controller - потребителски профил и настройки
• admin_controller - администраторски панел

Услуги (Services)

• AuthService - регистрация, вход, валидация на данни, смяна на парола
• WeatherService - извличане на текущо време от Open-Meteo
• ForecastService - извличане на прогнозни данни
• HistoryService - исторически метеорологични данни
• DonationService - управление на дарения
• ClimateAnalysisService - климатичен анализ
• VisualizationService - генериране на данни за визуализации
• StatisticsService - статистически изчисления
• TranslationService - превод на текст

Инсталация и стартиране

Изисквания

• Python 3.10 или по-нова версия
• Microsoft SQL Server (с ODBC Driver 17)
• Google Chrome (за Selenium тестовете)

Стъпки

1. Клониране на хранилището:

git clone <url>
cd 2526-dzi-python-KRRusev21

2. Създаване на виртуална среда и инсталиране на зависимости:

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

3. Създаване на база данни weather_app в SQL Server.

4. Задаване на променливи на средата (по избор):

set SQL_SERVER=localhost
set SQL_DATABASE=weather_app
set PEXELS_API_KEY=вашият_ключ
set SECRET_KEY=вашият_секретен_ключ

5. Стартиране на миграции:

alembic upgrade head

6. Стартиране на приложението:

python run.py

Приложението ще бъде достъпно на http://localhost:5000.

Тестове

Модулни тестове (pytest)

pytest tests/ -v

Selenium UI тестове

pytest tests/test_ui/ -v

Тестове за производителност

pytest tests/test_performance/ -v

Структура на тестовете

tests/
  conftest.py                          - общи фикстури
  test_models/                         - тестове на моделите
  test_controllers/                    - тестове на контролерите
  test_services/                       - тестове на услугите и валидация
  test_repositories/                   - тестове на хранилищата
  test_ui/                             - Selenium UI тестове
  test_performance/                    - тестове за производителност

Конфигурация

Приложението поддържа три среди:

• development - режим за разработка с активен debug
• testing - режим за тестове с отделна тестова база данни
• production - продукционен режим без debug

Конфигурацията се задава в app/config.py. Чувствителни данни (API ключове, секретен ключ) се четат от променливи на средата.

Автор

Кевин Русев