marketing/a.md

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

Обзор

Это руководство описывает API сервиса Parser, который собирает и предоставляет новостные данные. API спроектировано для эффективной работы с клиентскими приложениями и поддерживает пагинацию, сортировку и фильтрацию.

Реализация в UI: что мы должны показать пользователю

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

1. Основной экран: Лента новостей 📰

Это главный экран приложения, где пользователь видит все собранные новости.

• Функционал:
  • Отображение новостей: Используйте GET /api/parser/items для загрузки и отображения списка новостей. Каждая новость в списке должна показывать заголовок, источник, дату публикации и краткий текст (rawText или analytics.summary, когда он будет готов).
  • Пагинация: Так как новостей может быть много, реализуйте "бесконечную прокрутку" (подгрузка новых статей при скролле вниз) или классические кнопки пагинации («1, 2, 3...»). API полностью это поддерживает.
  • Сортировка: По умолчанию новости должны быть отсортированы по дате публикации (sort=publishedAt,desc), чтобы пользователь видел сначала самое свежее.

2. Панель фильтров 🔎

Сбоку или сверху от ленты новостей должна быть панель, позволяющая пользователю отфильтровать данные.

• Функционал:
  • Фильтр по источнику: Добавьте выпадающий список или чекбоксы с названиями источников (например, "Kursiv", "Kapital.kz"). При выборе источника отправляйте его в параметре sourceName в запросе к GET /api/parser/items.
  • Фильтр по дате: Добавьте два поля для выбора даты ("от" и "до") с календарем. Это позволит пользователю смотреть новости за конкретный период. Используйте параметры startDate и endDate.

3. Дашборд/Статистика 📊

Нужно создать отдельную страницу "Дашборд" или "Статистика", где будет отображаться общая информация о системе.

• Функционал:
  • Общее количество новостей: Используйте GET /api/parser/stats для получения и отображения общего числа статей в базе (totalItems).
  • Разбивка по источникам: На основе поля sourceStatistics постройте круговую диаграмму (pie chart), которая наглядно покажет, сколько новостей пришло с каждого источника.
  • Статус системы: Используйте GET /api/parser/health, чтобы показать пользователю (скорее, администратору) текущий статус сервиса и планировщика. Можно добавить зелёный/красный индикатор.

4. Админ-панель: Управление парсером (опционально, для администраторов) ⚙️

Эта часть интерфейса может быть скрыта от обычных пользователей и доступна только администраторам.

• Функционал:
  • Ручной запуск парсинга: Добавьте кнопки "Запустить парсинг Kursiv", "Запустить парсинг Kapital" и "Запустить все". Эти кнопки будут отправлять запросы на эндпоинты POST /api/parser/parse/{source} и POST /api/parser/parse/all.
  • Мониторинг состояния БД: Используйте GET /api/parser/health/mongodb для проверки статуса подключения к базе данных и выводите сообщение об успехе или ошибке.

---

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 в ответе