core/Техническое задание №6 Модуль сбора аналитики.md

Техническое задание №6: Модуль сбора аналитики

Цель: Реализовать автоматизированный процесс сбора ключевых показателей эффективности (KPI) по всем опубликованным постам. Эти данные необходимы для заполнения дашборда аналитики и оценки эффективности SMM-кампаний.

---

1. Расширение API-клиентов для соцсетей

Необходимо дополнить существующие API-клиенты (например, TelegramApiClient) методами для получения статистики.

TelegramApiClient.java

• Новый метод: PostStatsDto getPostStatistics(String apiToken, String chatId, String externalId)
  • Задача: Получить статистику по конкретному посту. В Telegram это может быть количество просмотров или реакции (если применимо).
  • Возвращаемое значение: DTO PostStatsDto, содержащий поля views, reactions, shares и т.д., в зависимости от возможностей API.

(По аналогии расширяются клиенты для других соцсетей, например, VkApiClient.java, который может возвращать просмотры, лайки, репосты, комментарии.)

---

2. Сервисный слой (Business Logic)

AnalyticsService.java

Основной сервис, управляющий процессом сбора и сохранения аналитики.

• Зависимости: MessageRepository, KpiSnapshotRepository, а также все API-клиенты (TelegramApiClient и др.).
• Ключевой метод: void collectAndSaveAnalytics()

Логика сбора и сохранения аналитики (collectAndSaveAnalytics)

Этот метод должен быть аннотирован @Scheduled для регулярного запуска (например, раз в час или раз в сутки).

• Алгоритм работы:
  1. Найти в MessageRepository все записи об опубликованных постах, для которых статистика еще не собиралась или собиралась давно (например, старше 24 часов).
  2. Для каждой найденной записи (Message):
     • Получить externalId поста и информацию о канале (channel).
     • Вызвать соответствующий API-клиент (например, telegramApiClient.getPostStatistics(...)) для получения актуальной статистики.
     • Обработка ошибки: Если API соцсети возвращает ошибку "пост не найден" (например, его удалили), пометить этот Message в нашей БД как удаленный, чтобы больше не пытаться его опрашивать.
  3. Агрегация и сохранение:
     • На основе полученных данных от API (просмотры, лайки, репосты) рассчитать ключевые метрики (KPI), например, ER (Engagement Rate).
     • Создать новые записи в KpiSnapshot для каждой рассчитанной метрики.
     • Каждая запись KpiSnapshot должна содержать:
       • date: Текущая дата.
       • channel: Ссылка на канал.
       • metric: Название метрики (например, "VIEWS", "LIKES", "ENGAGEMENT_RATE").
       • value: Значение метрики.

---

3. API Endpoint (REST Controller)

Для этого модуля не требуется создавать новые эндпоинты для фронтенда, так как он работает полностью в фоновом режиме. Однако, для удобства отладки можно добавить административный эндпоинт.

AnalyticsController.java (Опционально, для отладки)

• POST /api/smm/analytics/collect-now
  • Описание: Принудительно запускает один цикл сбора аналитики.
  • Успешный ответ (200 OK):

    {
      "success": true,
      "message": "Сбор аналитики запущен. Обработано N постов."
    }
    

---

4. Конфигурация планировщика

Метод collectAndSaveAnalytics в AnalyticsService должен быть аннотирован для периодического запуска.

// Запускать каждый час в 0 минут
@Scheduled(cron = "0 0 * * * *")
public void collectAndSaveAnalytics() {
    // ... логика ...
}

---

5. Обработка ошибок

• Ошибки API: Сервис должен быть устойчив к временным сбоям API соцсетей. Если API недоступно, сбор аналитики для этого поста можно отложить до следующего запуска.
• Удаленные посты: Важно корректно обрабатывать ситуацию, когда пост был удален из соцсети, чтобы избежать бесконечных попыток получить по нему статистику.

---

Критерии выполнения

• Существующие API-клиенты для соцсетей расширены методами для получения статистики.
• Реализован AnalyticsService с методом, запускаемым по расписанию.
• Процесс сбора статистики успешно находит опубликованные посты и запрашивает по ним данные у API соцсетей.
• Рассчитанные KPI-метрики корректно сохраняются в таблицу KpiSnapshot.
• Реализована корректная обработка ошибок, включая ситуацию с удаленными постами.
• Данные из KpiSnapshot готовы для использования на дашборде аналитики (который будет запрашивать их через GET эндпоинт, реализованный в рамках ТЗ №2 или №5).