marketing-parser/Техническое задание на доработку AI-агента для генерации PDF-отчётов.md

Техническое задание на доработку AI-агента для генерации PDF-отчётов

Дата: 5 октября 2025 г. Проект: Модификация существующего бэкенда для интеграции с сервисом deep-research.

1. Общее описание

Целью данной доработки является интеграция внешнего AI-сервиса deep-research (далее "Сервис Исследований") в существующий бэкенд. Необходимо модифицировать эндпоинт /api/parser/report таким образом, чтобы он принимал от пользователя тему для исследования, передавал её Сервису Исследований, получал в ответ сгенерированный текстовый отчёт и преобразовывал его в готовый для скачивания PDF-файл.

2. Требования к реализации

2.1. Модификация эндпоинта /api/parser/report

• Метод: POST

• URL: /api/parser/report

• Тело запроса (Request Body):

  • Формат: application/json
  • Поля:
    • query (string, обязательное) - Тема для исследования.
    • lang (string, опциональное, по умолчанию "ru") - Язык для итогового отчёта (например, "ru", "en").
    • depth (integer, опциональное, по умолчанию 3) - Глубина исследования (целое число от 1 до 5).
    • breadth (integer, опциональное, по умолчанию 5) - Широта исследования (целое число от 2 до 10).
    • report_type (string, опциональное, по умолчанию "report") - Тип отчёта ("report" для полного отчёта, "answer" для краткого ответа).

• Успешный ответ (Success Response):

  • Код: 200 OK
  • Заголовки:
    • Content-Type: application/pdf
    • Content-Disposition: attachment; filename="research_report.pdf" (имя файла можно генерировать динамически).
  • Тело ответа: Сгенерированный PDF-файл.

• Ответы с ошибками (Error Responses):

  • Код: 400 Bad Request - Если в запросе отсутствуют обязательные поля или их формат некорректен.
  • Код: 500 Internal Server Error - Если произошла внутренняя ошибка на бэкенде или при вызове Сервиса Исследований.
  • Код: 504 Gateway Timeout - Если Сервис Исследований не отвечает в течение заданного времени.

2.2. Логика работы агента

Процесс должен следовать по шагам:

1. Приём запроса: Эндпоинт /api/parser/report получает POST запрос с параметрами от фронтенда.
2. Валидация: Бэкенд проверяет корректность полученных данных (например, что query не пустое, а depth — число в нужном диапазоне).
3. Вызов Сервиса Исследований:
   • Бэкенд формирует и отправляет POST запрос на эндпоинт Сервиса Исследований, используя HTTP-клиент (например, axios для Node.js или requests для Python).
   • Целевой URL: http://185.35.223.45:3051/api/research
   • Тело запроса: JSON-объект, сформированный из параметров, полученных на шаге 1.
   • Все API-ключи (OPENAI_API_KEY, FIRECRAWL_API_KEY) должны быть безопасно сохранены в переменных окружения бэкенда и использоваться Сервисом Исследований.
4. Обработка ответа:
   • Бэкенд ожидает ответ от Сервиса Исследований в формате JSON.
   • Из ответа извлекается сгенерированный полный текст отчёта (предположительно, из поля report или answer), а также список использованных URL (visitedUrls).
   • В случае ошибки от Сервиса Исследований, ошибка логируется, и клиенту возвращается ответ с кодом 500.
5. Генерация PDF:
   • Полученный текст отчёта передаётся в модуль генерации PDF.
   • Используется специализированная библиотека (например, pdfkit или puppeteer для Node.js; ReportLab для Python).
   • PDF-файл формируется в соответствии с требованиями к форматированию (см. п. 2.3).
6. Отправка PDF клиенту: Бэкенд отправляет сгенерированный PDF-файл в теле ответа с соответствующими заголовками.

2.3. Требования к PDF-отчёту

Сгенерированный PDF-документ должен иметь профессиональный вид и чёткую структуру:

• Титульная страница: Название исследования (из поля query).
• Содержание (Table of Contents): Автоматически сгенерированное оглавление на основе заголовков в отчёте.
• Тело отчёта: Основной текст, полученный от Сервиса Исследований, с сохранением форматирования (заголовки, абзацы, списки).
• Список источников: В конце документа должен быть раздел "Источники" или "Библиография", содержащий список URL-адресов из поля visitedUrls.

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

• Бэкенд: Реализация должна использовать текущий стек бэкенда (например, Node.js/Express, Python/Django/FastAPI и т.д.).
• HTTP-клиент: Для взаимодействия с Сервисом Исследований (например, axios).
• Библиотека для генерации PDF: На выбор разработчика, в зависимости от стека (например, pdfkit, puppeteer, ReportLab).

4. Нефункциональные требования

• Асинхронность: Процесс исследования может занимать несколько минут. Необходимо реализовать асинхронную обработку, чтобы избежать таймаута HTTP-запроса от клиента.
  • Рекомендация: При получении запроса бэкенд может сразу возвращать 202 Accepted с ID задачи. Фронтенд будет периодически опрашивать другой эндпоинт (/api/parser/report/status/{id}), чтобы проверить готовность отчёта и получить ссылку на скачивание. (На первом этапе можно реализовать как долго выполняющийся запрос, но асинхронная модель является предпочтительной для будущего развития.)

5. Что не входит в задачи

• Разработка фронтенд-части для взаимодействия с API.
• Реализация аутентификации и авторизации пользователей.
• Создание системы очередей для обработки нескольких запросов одновременно (может быть добавлено на следующем этапе).