### **Техническое задание на доработку 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.
- Реализация аутентификации и авторизации пользователей.
- Создание системы очередей для обработки нескольких запросов одновременно (может быть добавлено на следующем этапе).
