marketing-parser/RESEARCH_API_GUIDE.md

Руководство по 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")

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

{
  "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:

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

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

cURL

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)

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)

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:

./test_research_api.sh

Логирование

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

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 в ответе не пустое