telegram-helper-bot/.cursor/rules/dependencies-and-utils.md

---
description: "Работа с зависимостями, утилитами, метриками и внешними сервисами"
globs: ["helper_bot/utils/**/*.py", "helper_bot/config/**/*.py"]
---

# Зависимости и утилиты

## BaseDependencyFactory

Центральный класс для управления зависимостями проекта.

### Использование

```python
from helper_bot.utils.base_dependency_factory import get_global_instance

# Получение глобального экземпляра
bdf = get_global_instance()

# Доступ к зависимостям
db = bdf.get_db()              # AsyncBotDB
settings = bdf.get_settings()  # dict с настройками
s3_storage = bdf.get_s3_storage()  # S3StorageService или None
```

### Структура settings

Настройки загружаются из `.env` и структурированы:

```python
settings = {
    'Telegram': {
        'bot_token': str,
        'listen_bot_token': str,
        'preview_link': bool,
        'main_public': str,
        'group_for_posts': int,
        'important_logs': int,
        ...
    },
    'Settings': {
        'logs': bool,
        'test': bool
    },
    'Metrics': {
        'host': str,
        'port': int
    },
    'S3': {
        'enabled': bool,
        'endpoint_url': str,
        'access_key': str,
        'secret_key': str,
        'bucket_name': str,
        'region': str
    }
}
```

## Метрики

### Декораторы метрик

Используйте декораторы из `helper_bot.utils.metrics`:

```python
from helper_bot.utils.metrics import track_time, track_errors, db_query_time

@track_time("method_name", "module_name")
@track_errors("module_name", "method_name")
async def some_method():
    """Метод с отслеживанием времени и ошибок."""
    ...

@db_query_time("method_name", "table_name", "operation")
async def db_method():
    """Метод БД с отслеживанием времени запросов."""
    ...
```

### Доступ к метрикам

```python
from helper_bot.utils.metrics import metrics

# Метрики доступны через Prometheus на порту из settings['Metrics']['port']
```

## Rate Limiting

### RateLimiter

Используется для ограничения частоты запросов:

```python
from helper_bot.utils.rate_limiter import RateLimiter

limiter = RateLimiter(...)
if await limiter.is_allowed(user_id):
    # Разрешить действие
    ...
else:
    # Отклонить действие
    ...
```

### RateLimitMiddleware

Автоматически применяет rate limiting ко всем запросам через middleware.

## S3 Storage

### S3StorageService

Используется для хранения медиафайлов:

```python
from helper_bot.utils.s3_storage import S3StorageService

# Получение через BaseDependencyFactory
s3_storage = bdf.get_s3_storage()

if s3_storage:
    # Загрузка файла
    url = await s3_storage.upload_file(file_path, object_key)
    
    # Удаление файла
    await s3_storage.delete_file(object_key)
```

### Проверка доступности

Всегда проверяйте, что S3 включен:

```python
s3_storage = bdf.get_s3_storage()
if s3_storage:
    # Работа с S3
    ...
else:
    # Fallback логика
    ...
```

## Утилиты

### helper_func.py

Содержит вспомогательные функции для работы с:
- Датами и временем
- Форматированием данных
- Валидацией
- Преобразованием данных

Используйте эти функции вместо дублирования логики.

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

### rate_limit_config.py

Конфигурация rate limiting находится в `helper_bot/config/rate_limit_config.py`.

Используйте конфигурацию вместо хардкода значений.

## Best Practices

1. **Всегда получайте зависимости через BaseDependencyFactory** - не создавайте экземпляры напрямую
2. **Используйте декораторы метрик** для всех важных методов
3. **Проверяйте доступность внешних сервисов** (S3) перед использованием
4. **Используйте утилиты** из `helper_func.py` вместо дублирования кода
5. **Читайте настройки из settings** вместо хардкода значений
6. **Логируйте важные операции** с внешними сервисами