marketing-parser/Техническое задание (Версия 4.0) Интеграция генерации отчётов в parser-service.md

Техническое задание (Версия 4.0): Интеграция генерации отчётов в parser-service

Задача: Модифицировать существующий parser-service, добавив в него функционал для автоматической генерации маркетинговых отчётов.

Контекст: Мы отказываемся от создания отдельного сервиса для отчётов. Вся логика по их созданию должна быть реализована внутри parser-service, который уже имеет доступ к данным в MongoDB и к AI-аналитике.

---

1. Архитектура и воркфлоу

1. Никаких новых сервисов. Вся логика реализуется в parser-service.
2. Новый API эндпоинт: В parser-service необходимо добавить новый REST API эндпоинт для запуска процесса генерации отчёта.
3. Внутренний воркфлоу:
   • Новый эндпоинт (например, в MarketItemController или новом ReportController) получает запрос с параметрами отчёта.
   • Контроллер вызывает новый ReportGenerationService (созданный внутри parser-service).
   • ReportGenerationService использует уже существующий MarketItemRepository для получения данных за указанный период.
   • Для генерации аннотации отчёта он обращается к существующему OllamaAnalyticsService.
   • Сервис формирует документ в заданном формате (PDF или DOCX).
   • Готовый файл возвращается пользователю в теле HTTP-ответа.

---

2. API эндпоинт

POST /api/report/generate

Этот эндпоинт будет находиться в parser-service и инициировать создание отчёта.

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

{
  "reportTitle": "Еженедельный анализ новостного фона",
  "authorName": "Имя Аналитика",
  "companyName": "Название Компании Клиента",
  "startDate": "2025-09-10T00:00:00",
  "endDate": "2025-09-17T23:59:59",
  "format": "PDF" // или "DOCX"
}

Успешный ответ:

• HTTP Статус: 200 OK
• Headers: Content-Disposition: attachment; filename="report_2025-09-17.pdf"
• Body: Бинарные данные сгенерированного файла.

---

3. Структура и содержание отчёта

Сервис должен динамически генерировать документ, следуя этой структуре:

1. Титульный лист

• Заголовок: Из поля reportTitle запроса.
• Автор: Из поля authorName запроса.
• Название компании: Из поля companyName запроса.
• Дата: Текущая дата генерации отчёта.

2. Содержание (Table of Contents)

• Автоматически генерируемое оглавление со ссылками на основные разделы.

3. Краткое содержание (Аннотация)

• Реализация:
  1. Получить все саммари (analytics.summary) статей за выбранный период из MongoDB.
  2. Объединить их в один большой текст.
  3. Отправить этот текст в Ollama с промптом: "На основе этих кратких сводок новостей напиши общую аннотацию на 2-3 абзаца, выделяя ключевые тренды и события."

4. Введение

• Использовать шаблонный текст с динамическими датами.
• Пример: "Целью данного отчёта является анализ новостного фона в сфере маркетинга и бизнеса за период с [startDate] по [endDate]. Были проанализированы публикации из ключевых источников для выявления основных трендов."

5. Основная часть

• Подраздел: Ключевые публикации
  • Вывести 5-10 самых важных новостей, для каждой указав: Заголовок, Источник, Дата публикации, Сгенерированное саммари (analytics.summary).
• Подраздел: Облако тегов
  • Собрать все теги (analytics.tags) и сформировать изображение "облака тегов".
• Подраздел: Анализ тональности
  • Подсчитать количество статей с тональностью positive, negative, neutral и представить в виде круговой диаграммы.
• Подраздел: Упоминаемые компании и персоны
  • Собрать и вывести списки наиболее часто упоминаемых компаний и персон из analytics.entities.

6. Рекомендации

• Использовать статический текст-заполнитель.

7. Список литературы

• Автоматически сгенерированный список всех проанализированных статей.
• Формат: [Заголовок статьи]. Источник: [Название источника]. URL: [Ссылка на статью]

8. Приложения

• Добавить полную таблицу со всеми статьями за период.

---

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

• DOCX: Apache POI
• PDF: OpenPDF или iText
• Графики и диаграммы: JFreeChart

---

5. Критерии выполнения

• parser-service расширен новым функционалом без создания отдельного сервиса.
• Реализован эндпоинт POST /api/report/generate, который принимает параметры отчёта.
• Сервис успешно генерирует и возвращает файлы в форматах PDF и DOCX.
• Структура и содержание сгенерированных документов полностью соответствуют описанию в ТЗ.