feat: downloader

internal/pkg/grib/README.md

@@ -0,0 +1,104 @@
+# GRIB Module
+
+Этот модуль реализует функциональность для работы с GRIB-файлами, аналогичную tawhiri-downloader и tawhiri, но на Go.
+
+## Основные возможности
+
+- **Скачивание GRIB-файлов** с NOMADS (GFS прогнозы)
+- **Сборка 5D-куба** (время, давление, широта, долгота, переменные u/v)
+- **Эффективное хранение** с использованием mmap
+- **Интерполяция** ветровых данных для произвольных координат и времени
+- **Кэширование** результатов (in-memory + Redis)
+- **Распределенные блокировки** для предотвращения дублирования загрузок
+
+## Архитектура
+
+### Основные компоненты
+
+- **Downloader** - скачивает GRIB-файлы с NOMADS
+- **Cube** - управляет 5D-массивом данных через mmap
+- **Extractor** - выполняет интерполяцию данных
+- **Cache** - кэширует результаты запросов
+- **Service** - основной интерфейс для работы с модулем
+
+### Структура данных
+
+5D-куб содержит:
+- **Время**: 17 временных срезов (0, 3, 6, ..., 48 часов)
+- **Давление**: 34 уровня давления (1000, 975, 950, ..., 2 hPa)
+- **Широта**: 361 точка (-90° до +90°)
+- **Долгота**: 720 точек (0° до 359.5°)
+- **Переменные**: u-ветер и v-ветер
+
+## Использование
+
+```go
+// Создание сервиса
+cfg := grib.ServiceConfig{
+    Dir:      "/tmp/grib",
+    TTL:      24 * time.Hour,
+    CacheTTL: 1 * time.Hour,
+    Redis:    redisClient,
+    Parallel: 4,
+    Client:   &http.Client{Timeout: 30 * time.Second},
+}
+
+service, err := grib.New(cfg)
+if err != nil {
+    log.Fatal(err)
+}
+defer service.Close()
+
+// Обновление данных
+err = service.Update(ctx)
+
+// Извлечение ветровых данных
+wind, err := service.Extract(ctx, lat, lon, alt, timestamp)
+// wind[0] - u-компонента ветра
+// wind[1] - v-компонента ветра
+```
+
+## Интерполяция
+
+Модуль выполняет 16-точечную интерполяцию:
+1. **Временная интерполяция** между двумя ближайшими срезами
+2. **Интерполяция по давлению** между двумя ближайшими уровнями
+3. **Билинейная интерполяция** по широте и долготе
+
+## Кэширование
+
+- **In-memory кэш**: быстрый доступ к недавно запрошенным данным
+- **Redis кэш**: распределенное кэширование для множественных реплик
+
+## Расписание обновлений
+
+Рекомендуемая частота вызова `Update()`:
+- **Каждые 6 часов** - для получения свежих GFS прогнозов
+- **При запуске** - для загрузки начальных данных
+- **По требованию** - при отсутствии данных для запрашиваемого времени
+
+## Отличия от tawhiri
+
+### Преимущества Go-реализации:
+- **Высокая производительность** (mmap, конкурентные загрузки)
+- **Эффективное использование памяти** (не загружает весь массив в RAM)
+- **Горизонтальное масштабирование** (stateless, множество реплик)
+- **Встроенное кэширование** (in-memory + Redis)
+
+### Особенности:
+- Использует `github.com/nilsmagnus/grib` вместо pygrib
+- Реализует собственную логику интерполяции
+- Поддерживает распределенные блокировки через Redis
+
+## Конфигурация
+
+### Переменные окружения:
+- `PREDICTOR_GRIB_DATASET_URL` - URL источника данных (опционально)
+
+### Параметры ServiceConfig:
+- `Dir` - директория для хранения файлов
+- `TTL` - время жизни данных (по умолчанию 24 часа)
+- `CacheTTL` - время жизни кэша (по умолчанию 1 час)
+- `Redis` - Redis клиент для блокировок и кэша
+- `Parallel` - количество параллельных загрузок
+- `Client` - HTTP клиент для загрузок