# Руководство по API генерации исследовательских отчётов

## Обзор

Новый эндпоинт `/api/parser/report` интегрирован с сервисом `deep-research` для генерации PDF-отчётов на основе пользовательских запросов.

## Эндпоинт

**POST** `/api/parser/report`

### Параметры запроса

| Параметр      | Тип     | Обязательный | По умолчанию | Описание                        |
| ------------- | ------- | ------------ | ------------ | ------------------------------- |
| `query`       | string  | ✅           | -            | Тема для исследования           |
| `lang`        | string  | ❌           | "ru"         | Язык отчёта ("ru", "en")        |
| `depth`       | integer | ❌           | 3            | Глубина исследования (1-5)      |
| `breadth`     | integer | ❌           | 5            | Широта исследования (2-10)      |
| `report_type` | string  | ❌           | "report"     | Тип отчёта ("report", "answer") |

### Пример запроса

```json
{
    "query": "Искусственный интеллект в здравоохранении",
    "lang": "ru",
    "depth": 3,
    "breadth": 5,
    "report_type": "report"
}
```

### Ответы

#### Успешный ответ (200 OK)

-   **Content-Type**: `application/pdf`
-   **Content-Disposition**: `attachment; filename="research_report_[timestamp].pdf"`
-   **Тело**: PDF-файл с отчётом

#### Ошибки

| Код | Описание                                  |
| --- | ----------------------------------------- |
| 400 | Некорректные параметры запроса            |
| 500 | Внутренняя ошибка сервера                 |
| 504 | Таймаут при обращении к deep-research API |

## Структура PDF-отчёта

Сгенерированный PDF содержит:

1. **Титульная страница**

    - Название исследования (из поля `query`)
    - Дата создания
    - Подзаголовок "Исследовательский отчёт"

2. **Содержание**

    - Автоматически сгенерированное оглавление

3. **Основная часть**

    - Введение
    - Основной текст отчёта от deep-research API
    - Заключение

4. **Источники**
    - Список URL-адресов из поля `visitedUrls`

## Конфигурация

Настройки в `application.properties`:

```properties
# Deep Research API Configuration
deep-research.api.url=http://185.35.223.45:3051
deep-research.api.timeout=300000
```

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

### cURL

```bash
curl -X POST "https://api.konturai/api/parser/report" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Блокчейн технологии в финансах",
    "lang": "ru",
    "depth": 4,
    "breadth": 6
  }' \
  --output "blockchain_report.pdf"
```

### JavaScript (fetch)

```javascript
const response = await fetch('/api/parser/report', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        query: 'Квантовые вычисления',
        lang: 'ru',
        depth: 3,
        breadth: 5,
        report_type: 'report'
    })
});

if (response.ok) {
    const blob = await response.blob();
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'quantum_computing_report.pdf';
    a.click();
}
```

### Python (requests)

```python
import requests

response = requests.post(
    'https://api.konturai/api/parser/report',
    json={
        'query': 'Машинное обучение в медицине',
        'lang': 'ru',
        'depth': 3,
        'breadth': 5,
        'report_type': 'report'
    }
)

if response.status_code == 200:
    with open('ml_medicine_report.pdf', 'wb') as f:
        f.write(response.content)
    print("Отчёт сохранён как ml_medicine_report.pdf")
else:
    print(f"Ошибка: {response.status_code}")
```

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

Для тестирования API используйте скрипт `test_research_api.sh`:

```bash
./test_research_api.sh
```

## Логирование

Все операции логируются. Для отладки проверьте логи приложения:

```bash
tail -f logs/application.log | grep "DeepResearchService\|ResearchPdfService"
```

## Ограничения

-   Максимальное время ожидания: 5 минут (300 секунд)
-   Размер генерируемого PDF ограничен только ресурсами сервера
-   Deep-research API должен быть доступен по указанному URL

## Устранение неполадок

### Ошибка 504 (Gateway Timeout)

-   Проверьте доступность deep-research API
-   Увеличьте timeout в конфигурации
-   Проверьте сетевые настройки

### Ошибка 500 (Internal Server Error)

-   Проверьте логи приложения
-   Убедитесь, что все зависимости установлены
-   Проверьте конфигурацию MinIO для сохранения файлов

### Пустой PDF

-   Проверьте, что deep-research API возвращает корректные данные
-   Убедитесь, что поле `report` или `answer` в ответе не пустое
