marketing-parser/EMAIL_INTEGRATION_GUIDE.md

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

## Обзор

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

## Настройка

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

```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`

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

```json
{
  "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

```bash
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)

```javascript
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: [детали ошибки]
```