marketing-parser/FRONTEND_API_GUIDE.md

Руководство по API для фронтенда

Обзор

После рефакторинга ParserController теперь поддерживает эффективную работу с фронтендом через строго типизированные DTO и расширенные возможности фильтрации и пагинации.

Основные изменения

1. Строгая типизация ответов

Все ответы API теперь используют DTO классы вместо Map<String, Object>:

• ApiResponse<T> - универсальный wrapper для всех ответов
• ParserResultDto - результат парсинга
• ParserStatsDto - статистика системы
• HealthCheckDto - состояние сервиса

2. Пагинация и сортировка

Поддержка Spring Data пагинации с параметрами:

• page - номер страницы (начиная с 0)
• size - количество элементов на странице
• sort - поле для сортировки и направление

3. Фильтрация данных

Возможность фильтрации по:

• sourceName - источнику новостей
• startDate - начальной дате
• endDate - конечной дате

API Endpoints

1. Получение записей с фильтрацией и пагинацией

GET /api/parser/items?page=0&size=10&sort=publishedAt,desc&sourceName=Kursiv&startDate=2025-01-01&endDate=2025-01-31

Параметры:

• page (optional, default: 0) - номер страницы
• size (optional, default: 20) - размер страницы
• sort (optional, default: "publishedAt,desc") - сортировка
• sourceName (optional) - фильтр по источнику
• startDate (optional) - начальная дата (ISO format)
• endDate (optional) - конечная дата (ISO format)

Ответ:

{
  "success": true,
  "message": "Записи получены успешно",
  "data": {
    "content": [
      {
        "id": "...",
        "sourceName": "Kursiv (Бизнес/экономика)",
        "title": "Заголовок новости",
        "url": "https://kursiv.media/...",
        "publishedAt": "2025-01-14T10:30:00",
        "addedAt": "2025-01-14T12:00:00",
        "rawText": "Текст статьи...",
        "hash": "...",
        "category": "Бизнес",
        "analytics": {
          "summary": null,
          "sentiment": null,
          "tags": [],
          "entities": {}
        }
      }
    ],
    "pageable": {
      "sort": {
        "sorted": true,
        "unsorted": false,
        "empty": false
      },
      "pageNumber": 0,
      "pageSize": 10,
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "totalElements": 25,
    "totalPages": 3,
    "last": false,
    "first": true,
    "numberOfElements": 10,
    "size": 10,
    "number": 0,
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "empty": false
  }
}

2. Статистика системы

GET /api/parser/stats

Ответ:

{
  "success": true,
  "message": "Статистика получена успешно",
  "data": {
    "totalItems": 150,
    "sourceStatistics": {
      "Kursiv (Бизнес/экономика)": 75,
      "Kapital.kz (Бизнес)": 75
    },
    "lastUpdate": "2025-01-14T12:00:00"
  }
}

3. Запуск парсинга

Парсинг всех источников

POST /api/parser/parse/all

Ответ:

{
  "success": true,
  "message": "Парсинг всех источников завершен успешно",
  "data": [
    {
      "source": "Kursiv",
      "processedItems": 15,
      "totalItemsInDb": 90,
      "status": "completed"
    },
    {
      "source": "Kapital",
      "processedItems": 12,
      "totalItemsInDb": 90,
      "status": "completed"
    }
  ]
}

Парсинг конкретного источника

POST /api/parser/parse/kursiv
POST /api/parser/parse/kapital

4. Проверка состояния

Общее состояние

GET /api/parser/health

Ответ:

{
  "success": true,
  "message": "Сервис работает",
  "data": {
    "status": "UP",
    "service": "RSS Parser System",
    "timestamp": 1705123456789,
    "scheduler": "Enabled - runs every 30 minutes"
  }
}

Состояние MongoDB

GET /api/parser/health/mongodb

Ответ при успехе:

{
  "success": true,
  "message": "MongoDB подключение успешно",
  "data": {
    "status": "UP",
    "message": "MongoDB подключение успешно",
    "timestamp": 1705123456789
  }
}

Ответ при ошибке:

{
  "success": false,
  "message": "Ошибка подключения к MongoDB",
  "data": {
    "status": "DOWN",
    "message": "Ошибка подключения к MongoDB: Command failed with error 13 (Unauthorized)",
    "timestamp": 1705123456789,
    "suggestion": "Проверьте учетные данные в application.properties"
  }
}

Примеры использования

1. Получение последних новостей с пагинацией

// Получить первую страницу с 10 записями, отсортированными по дате публикации
fetch('/api/parser/items?page=0&size=10&sort=publishedAt,desc')
  .then((response) => response.json())
  .then((data) => {
    if (data.success) {
      const items = data.data.content;
      const totalPages = data.data.totalPages;
      // Обработка данных
    }
  });

2. Фильтрация по источнику

// Получить только новости от Kursiv
fetch('/api/parser/items?sourceName=Kursiv (Бизнес/экономика)&page=0&size=20')
  .then((response) => response.json())
  .then((data) => {
    if (data.success) {
      const kursivNews = data.data.content;
      // Обработка данных
    }
  });

3. Фильтрация по датам

// Получить новости за последнюю неделю
const endDate = new Date().toISOString();
const startDate = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();

fetch(`/api/parser/items?startDate=${startDate}&endDate=${endDate}`)
  .then((response) => response.json())
  .then((data) => {
    if (data.success) {
      const recentNews = data.data.content;
      // Обработка данных
    }
  });

4. Комплексная фильтрация

// Получить новости Kapital за последний месяц, отсортированные по дате
const endDate = new Date().toISOString();
const startDate = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();

fetch(
  `/api/parser/items?sourceName=Kapital.kz (Бизнес)&startDate=${startDate}&endDate=${endDate}&sort=publishedAt,desc&page=0&size=50`
)
  .then((response) => response.json())
  .then((data) => {
    if (data.success) {
      const kapitalNews = data.data.content;
      const totalCount = data.data.totalElements;
      // Обработка данных
    }
  });

5. Получение статистики

fetch('/api/parser/stats')
  .then((response) => response.json())
  .then((data) => {
    if (data.success) {
      const stats = data.data;
      console.log(`Всего новостей: ${stats.totalItems}`);
      console.log('По источникам:', stats.sourceStatistics);
    }
  });

Поддерживаемые форматы дат

API поддерживает следующие форматы дат:

• yyyy-MM-dd (например: 2025-01-14)
• yyyy-MM-dd'T'HH:mm:ss (например: 2025-01-14T10:30:00)
• yyyy-MM-dd'T'HH:mm:ss.SSS (например: 2025-01-14T10:30:00.000)
• yyyy-MM-dd HH:mm:ss (например: 2025-01-14 10:30:00)

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

Все ответы API следуют единому формату:

{
  "success": false,
  "message": "Описание ошибки",
  "error": "Детальная информация об ошибке"
}

HTTP статус коды:

• 200 - Успешный запрос
• 500 - Внутренняя ошибка сервера
• 503 - Сервис недоступен (например, MongoDB)

Рекомендации для фронтенда

1. Кэширование: Используйте кэширование для статистики и часто запрашиваемых данных
2. Пагинация: Реализуйте бесконечную прокрутку или традиционную пагинацию
3. Фильтры: Предоставьте пользователю удобные фильтры по источнику и датам
4. Обновление: Используйте WebSocket или polling для обновления данных в реальном времени
5. Обработка ошибок: Всегда проверяйте поле success в ответе