marketing-parser/PARSER_README.md

# RSS Parser для Kursiv Media

Этот проект представляет собой RSS-парсер для сайта Kursiv Media, разработанный на Spring Boot с сохранением данных в MongoDB.

## Описание

Парсер получает данные из RSS-ленты `https://kursiv.media/feed/`, обрабатывает их и сохраняет в базу данных MongoDB с дедупликацией по хэшу.

**🔄 Автоматический режим работы:** Парсер автоматически запускается каждые 30 минут (в 0 и 30 минут каждого часа) для обеспечения актуальности данных.

## Технологический стек

- **Java 21**
- **Spring Boot 3.5.5**
- **Spring Data MongoDB**
- **Rome** - библиотека для парсинга RSS
- **JSoup** - для очистки HTML
- **MongoDB** - база данных

## Структура проекта

```
src/main/java/kz/konturai/parser/
├── ParserApplication.java          # Главный класс приложения
├── controller/
│   └── ParserController.java      # REST API контроллер
├── model/
│   └── MarketItem.java            # Модель данных для MongoDB
├── repository/
│   └── MarketItemRepository.java  # Репозиторий для работы с MongoDB
└── service/
    └── KursivParserService.java   # Основной сервис парсинга
```

## Установка и запуск

### Предварительные требования

1. **Java 21** или выше
2. **MongoDB** (локально или удаленно)
3. **Maven 3.6+**

### Шаги установки

1. **Клонируйте репозиторий:**

   ```bash
   git clone <repository-url>
   cd parser
   ```

2. **Установите MongoDB:**

   - Скачайте и установите MongoDB с официального сайта
   - Запустите MongoDB сервис
   - По умолчанию MongoDB работает на порту 27017

3. **Настройте конфигурацию:**

   Отредактируйте файл `src/main/resources/application.properties`:

   ```properties
   # MongoDB Configuration
   spring.data.mongodb.host=localhost
   spring.data.mongodb.port=27017
   spring.data.mongodb.database=parser_db

   # RSS Feed URL
   rss.feed.url=https://kursiv.media/feed/
   ```

4. **Соберите проект:**

   ```bash
   ./mvnw clean compile
   ```

5. **Запустите приложение:**

   ```bash
   ./mvnw spring-boot:run
   ```

   Приложение будет доступно по адресу: `http://localhost:8080`

## API Endpoints

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

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

**Ответ:**

```json
{
  "success": true,
  "message": "Парсинг завершен успешно",
  "processedItems": 15,
  "totalItemsInDb": 25
}
```

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

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

**Ответ:**

```json
{
  "success": true,
  "totalItems": 25,
  "message": "Статистика получена успешно"
}
```

### 3. Получение всех записей

```http
GET /api/parser/items
```

**Ответ:**

```json
{
  "success": true,
  "items": [...],
  "count": 25,
  "message": "Записи получены успешно"
}
```

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

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

**Ответ:**

```json
{
  "status": "UP",
  "service": "Kursiv RSS Parser",
  "timestamp": 1703123456789,
  "scheduler": "Enabled - runs every 30 minutes"
}
```

### 5. Информация о планировщике

```http
GET /api/parser/scheduler/info
```

**Ответ:**

```json
{
  "schedulerEnabled": true,
  "cronExpression": "0 0/30 * * * ?",
  "description": "Запуск каждые 30 минут (в 0 и 30 минут каждого часа)",
  "nextRun": "Следующий запуск будет в ближайшие 0 или 30 минут часа"
}
```

## Структура данных в MongoDB

Документы сохраняются в коллекции `market_items` со следующей структурой:

```json
{
  "_id": "ObjectId",
  "source_name": "Kursiv (Бизнес/экономика)",
  "url": "https://kursiv.media/article/...",
  "title": "Заголовок новости",
  "published_at": "2025-01-14T10:30:00",
  "added_at": "2025-01-14T12:00:00",
  "raw_text": "Очищенный от HTML текст статьи...",
  "hash": "sha256_hash_of_url_and_title",
  "category": "Бизнес",
  "analytics": {
    "summary": null,
    "sentiment": null,
    "tags": [],
    "entities": {}
  }
}
```

## Особенности реализации

### Дедупликация

- Каждая запись имеет уникальный хэш, сгенерированный по формуле: `SHA256(url + "::" + title)`
- При повторном парсинге существующие записи обновляются (upsert операция)

### Очистка данных

- HTML-теги удаляются из текста описания
- Даты приводятся к формату `LocalDateTime`
- Текстовое содержимое нормализуется

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

- Логирование всех операций
- Graceful handling ошибок парсинга отдельных записей
- Продолжение работы при ошибках в отдельных элементах RSS

### Автоматический планировщик

- **Автозапуск**: Парсер автоматически запускается каждые 30 минут
- **Cron выражение**: `0 0/30 * * * ?` (запуск в 0 и 30 минут каждого часа)
- **Логирование**: Все автоматические запуски логируются с эмодзи для удобства мониторинга
- **Обработка ошибок**: Ошибки в автоматическом режиме не останавливают планировщик

## Тестирование

Запуск тестов:

```bash
./mvnw test
```

Тесты включают:

- Проверку парсинга RSS-ленты
- Проверку сохранения в MongoDB
- Проверку дедупликации
- Проверку структуры данных

## Мониторинг и логирование

Приложение использует SLF4J для логирования. Уровень логирования можно настроить в `application.properties`:

```properties
logging.level.kz.konturai.parser=DEBUG
logging.level.org.springframework.data.mongodb=DEBUG
```

## Возможные проблемы и решения

### MongoDB не запущен

```
Error: Could not connect to MongoDB
```

**Решение:** Убедитесь, что MongoDB запущен и доступен на указанном хосте и порту.

### RSS-лента недоступна

```
Error: Could not fetch RSS feed
```

**Решение:** Проверьте доступность URL `https://kursiv.media/feed/` и интернет-соединение.

### Проблемы с кодировкой

Если возникают проблемы с кодировкой текста, убедитесь, что в системе установлена правильная локаль.

## Развертывание в продакшене

1. **Настройте переменные окружения:**

   ```bash
   export SPRING_DATA_MONGODB_HOST=your-mongodb-host
   export SPRING_DATA_MONGODB_PORT=27017
   export SPRING_DATA_MONGODB_DATABASE=parser_prod
   ```

2. **Соберите JAR файл:**

   ```bash
   ./mvnw clean package
   ```

3. **Запустите приложение:**
   ```bash
   java -jar target/parser-0.0.1-SNAPSHOT.jar
   ```

## Лицензия

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