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

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