199 lines
6.6 KiB
Markdown
199 lines
6.6 KiB
Markdown
# Руководство по интеграции отправки отчетов по 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: [детали ошибки]
|
||
```
|