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

Техническое Задание на доработку AI-агента для генерации отчётов в формате Markdown (.md)

Проект: Модификация существующего бэкенда для генерации отчётов.

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

Целью данной доработки является замена модуля генерации PDF-файлов на более простой и быстрый модуль, который будет формировать и отдавать пользователю итоговый отчёт в текстовом формате Markdown (.md).

Бэкенд по-прежнему будет выполнять многоступенчатый процесс исследования (вызов deep-research API, затем синтез отчёта через Ollama), но финальным результатом будет текстовый .md файл, а не PDF.

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

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

• Метод: POST

• Тело запроса (Request Body): Остаётся без изменений (принимает query, lang, depth и т.д.).

• Успешный ответ (Success Response): (Ключевое изменение)

  • Код: 200 OK
  • Заголовки:
    • Content-Type: text/markdown; charset=UTF-8 (Важно для корректного отображения кириллицы).
    • Content-Disposition: attachment; filename="research_report.md" (Этот заголовок заставит браузер скачать файл, а не просто показать его).
  • Тело ответа: Готовый текст отчёта в формате Markdown.

• Ответы с ошибками (Error Responses): Остаются без изменений (400, 500 и т.д.).

2.2. Изменение логики работы агента

Процесс будет выглядеть так:

1. Приём и валидация запроса: Логика остаётся без изменений.
2. Вызов deep-research API: Логика остаётся без изменений. Бэкенд получает "сырые" learnings и visitedUrls.
3. Вызов Ollama для синтеза: Логика остаётся без изменений. Бэкенд получает от Ollama финальный, красиво структурированный отчёт в виде строки Markdown.
4. ОТМЕНА: Шаг генерации PDF полностью удаляется. Сервис ResearchPdfService и зависимость от библиотеки iText больше не нужны.
5. НОВЫЙ ШАГ: Формирование итогового .md файла:
   • Бэкенд берёт строку Markdown, полученную от Ollama.
   • К этой строке в конец добавляется раздел "Источники". Бэкенд должен программно сгенерировать этот раздел, добавив заголовок ## Источники и пронумерованный список URL-адресов из visitedUrls.
6. Отправка .md файла клиенту: Бэкенд отправляет итоговую строку (отчёт + источники) как тело HTTP-ответа с заголовками, указанными в п. 2.1.

2.3. Формат итогового Markdown-файла

Итоговая строка, которая будет отправлена клиенту, должна иметь следующую структуру:

# {Заголовок, сгенерированный Ollama, или просто ваш query}

## Введение

... текст от Ollama ...

## Основная часть

... текст от Ollama ...

### Подраздел

... текст от Ollama ...

## Заключение

... текст от Ollama ...

---

## Источники

1. https://...
2. https://...
3. ...

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

• Бэкенд: Java/Spring Boot (без изменений).
• HTTP-клиент: WebClient (без изменений)

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

• Асинхронность: Рекомендация по асинхронной обработке запроса (через jobId и отдельный эндпоинт для статуса) остаётся актуальной, так как сам процесс исследования по-прежнему занимает много времени.

5. Ожидаемый результат

При отправке POST запроса на эндпоинт /api/parser/report браузер пользователя должен инициировать скачивание файла research_report.md. Этот файл должен корректно открываться в любом текстовом редакторе, поддерживающем Markdown, и содержать полный, структурированный отчёт на русском языке вместе со списком источников.