marketing-parser/EMAIL_INTEGRATION_GUIDE.md

Руководство по интеграции отправки отчетов по email

Обзор

В систему добавлена функциональность автоматической отправки сгенерированных PDF отчетов на email пользователя. После генерации отчета в формате PDF, система автоматически отправит его на указанный email адрес.

Настройка

1. Конфигурация email в application.properties

# Email Configuration
spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username=your-email@gmail.com
spring.mail.password=your-app-password
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true

Важно: Для Gmail необходимо использовать App Password вместо обычного пароля.

2. Настройка Gmail App Password

1. Включите двухфакторную аутентификацию в Google аккаунте
2. Перейдите в настройки безопасности Google
3. Создайте App Password для приложения
4. Используйте этот пароль в конфигурации

Использование

API Endpoint

POST /api/parser/report/generate

Пример запроса

{
  "reportTitle": "Аналитический отчет за декабрь 2024",
  "authorName": "Иван Петров",
  "companyName": "ООО Контурай",
  "startDate": "2024-12-01T00:00:00",
  "endDate": "2024-12-31T23:59:59",
  "format": "PDF",
  "recipientEmail": "user@example.com"
}

Параметры

• reportTitle - название отчета
• authorName - имя автора отчета
• companyName - название компании
• startDate - дата начала периода (ISO 8601)
• endDate - дата окончания периода (ISO 8601)
• format - формат отчета ("PDF" или "DOCX")
• recipientEmail - НОВОЕ ПОЛЕ email адрес для отправки отчета

Условия отправки email

Email отправляется только при выполнении следующих условий:

1. Указан recipientEmail (не пустой)
2. Формат отчета установлен как "PDF"
3. Отчет успешно сгенерирован

Формат письма

Письмо содержит:

• Красиво оформленный HTML текст с деталями отчета
• Прикрепленный PDF файл с отчетом
• Информацию об авторе, компании и дате создания

Компоненты системы

EmailService

Новый сервис для отправки email:

• sendReportByEmail() - основной метод отправки
• Поддержка HTML формата писем
• Прикрепление PDF файлов
• Обработка ошибок

ReportGenerationService

Обновлен для интеграции с EmailService:

• Автоматическая отправка PDF после генерации
• Обработка ошибок отправки без прерывания процесса
• Поддержка асинхронной генерации с email

ReportGenerateRequest

Добавлено новое поле:

• recipientEmail - email для отправки отчета

Тестирование

Unit тесты

Создан EmailServiceTest с тестами:

• Успешная отправка email
• Обработка null значений
• Обработка ошибок SMTP

Ручное тестирование

1. Настройте email конфигурацию
2. Отправьте POST запрос с валидными данными
3. Проверьте получение email с PDF вложением

Безопасность

• Email отправляется только на указанный адрес
• Используется TLS шифрование для SMTP
• App Password для Gmail вместо обычного пароля
• Обработка ошибок без раскрытия чувствительной информации

Мониторинг

• Логирование успешных отправок
• Логирование ошибок отправки
• Не прерывает процесс генерации отчета при ошибках email

Примеры использования

cURL

curl -X POST http://localhost:8080/api/parser/report/generate \
  -H "Content-Type: application/json" \
  -d '{
    "reportTitle": "Тестовый отчет",
    "authorName": "Тест Автор",
    "companyName": "Тест Компания",
    "startDate": "2024-12-01T00:00:00",
    "endDate": "2024-12-31T23:59:59",
    "format": "PDF",
    "recipientEmail": "test@example.com"
  }'

JavaScript (fetch)

const response = await fetch('/api/parser/report/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    reportTitle: 'Аналитический отчет',
    authorName: 'Иван Петров',
    companyName: 'ООО Контурай',
    startDate: '2024-12-01T00:00:00',
    endDate: '2024-12-31T23:59:59',
    format: 'PDF',
    recipientEmail: 'user@example.com',
  }),
});

const result = await response.json();
console.log(result);

Troubleshooting

Проблемы с Gmail

1. Ошибка аутентификации: Убедитесь, что используете App Password
2. Блокировка аккаунта: Проверьте настройки безопасности Gmail
3. Порт заблокирован: Попробуйте порт 465 с SSL

Общие проблемы

1. Email не отправляется: Проверьте логи приложения
2. PDF не прикрепляется: Убедитесь, что формат "PDF"
3. Пустой recipientEmail: Проверьте, что поле заполнено

Логи

Успешная отправка:

Email с отчетом успешно отправлен на: user@example.com

Ошибка отправки:

Ошибка при отправке email: [детали ошибки]