# Руководство по 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. Получение записей с фильтрацией и пагинацией

```http
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)

**Ответ:**

```json
{
    "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. Статистика системы

```http
GET /api/parser/stats
```

**Ответ:**

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

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

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

```http
POST /api/parser/parse/all
```

**Ответ:**

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

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

```http
POST /api/parser/parse/kursiv
POST /api/parser/parse/kapital
```

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

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

```http
GET /api/parser/health
```

**Ответ:**

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

#### Состояние MongoDB

```http
GET /api/parser/health/mongodb
```

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

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

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

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

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

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

```javascript
// Получить первую страницу с 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. Фильтрация по источнику

```javascript
// Получить только новости от 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. Фильтрация по датам

```javascript
// Получить новости за последнюю неделю
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. Комплексная фильтрация

```javascript
// Получить новости 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. Получение статистики

```javascript
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 следуют единому формату:

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

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

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

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

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