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

Техническое задание: Реализация истории и загрузки отчётов

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

Контекст: Текущая реализация позволяет только генерировать отчёты. Необходимо создать механизм для их сохранения и последующего доступа к ним, чтобы пользователи могли скачивать ранее созданные документы.

---

Шаг 1: Реализация сохранения отчётов

1.1. Модель данных в MongoDB

Создайте новую коллекцию в MongoDB для хранения метаданных об отчётах, например, report_history.

Структура документа ReportHistory:

{
  "_id": "...", // ObjectId
  "reportTitle": "Еженедельный анализ новостного фона",
  "authorName": "Имя Аналитика",
  "companyName": "Название Компании Клиента",
  "startDate": "2025-09-10T00:00:00",
  "endDate": "2025-09-17T23:59:59",
  "format": "PDF",
  "filename": "report_2025-09-17-12345.pdf", // Уникальное имя файла
  "filePath": "/data/reports/report_2025-09-17-12345.pdf", // Путь на диске сервера
  "fileSize": 1234567, // Размер в байтах
  "createdAt": "2025-09-17T21:11:58" // Дата и время генерации
}

1.2. Хранение файлов

Сгенерированные отчёты (PDF/DOCX) должны сохраняться на файловой системе сервера в специальной директории. Путь к этой директории должен быть настраиваемым через application.properties (например, reports.storage.path=/data/reports).

1.3. Модификация ReportGenerationService

Необходимо изменить существующий сервис reportGenerationService. После успешной генерации файла (ReportBinary) он должен:

1. Сохранить бинарные данные файла на диск по указанному пути.
2. Создать запись с метаданными (включая путь к файлу) в новой коллекции report_history в MongoDB.

---

Шаг 2: Создание новых эндпоинтов в ReportController

2.1. Получение списка отчётов из истории

Эндпоинт: GET /api/parser/report/history

Описание: Возвращает пагинированный список метаданных всех ранее сгенерированных отчётов, отсортированных по дате создания (сначала новые).

Параметры:

• page (optional, default: 0) - номер страницы.
• size (optional, default: 20) - количество элементов на странице.
• sort (optional, default: "createdAt,desc") - поле и направление сортировки.

Успешный ответ (200 OK):

{
  "content": [
    {
      "id": "...",
      "reportTitle": "Еженедельный анализ",
      "authorName": "Имя Аналитика",
      "companyName": "Компания",
      "format": "PDF",
      "filename": "report_2025-09-17.pdf",
      "fileSize": 1234567,
      "createdAt": "2025-09-17T21:11:58"
    }
    // ... другие записи
  ],
  "pageable": { ... },
  "totalElements": 5,
  "totalPages": 1
  // ... стандартная структура Page из Spring Data
}

2.2. Скачивание конкретного отчёта из истории

Эндпоинт: GET /api/parser/report/history/{id}

Описание: Позволяет скачать конкретный файл отчёта по его уникальному ID из коллекции report_history.

Параметры:

• id (required, path variable) - ID записи об отчёте в MongoDB.

Логика работы:

1. Найти запись в report_history по id.
2. Если запись не найдена, вернуть 404 Not Found.
3. Из записи получить путь к файлу (filePath).
4. Прочитать файл с диска по этому пути.
5. Вернуть бинарные данные файла с соответствующими заголовками (Content-Disposition, Content-Type).

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

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

---

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

• Существующий эндпоинт POST /generate теперь сохраняет сгенерированный отчёт на диск и его метаданные в MongoDB.
• Новый эндпоинт GET /history успешно возвращает пагинированный список сохранённых отчётов.
• Новый эндпоинт GET /history/{id} успешно находит и отдаёт на скачивание ранее сгенерированный файл.