# Руководство по 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 "http://localhost:8080/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(
    'http://localhost:8080/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` в ответе не пустое