ready

2025-10-05 02:56:17 +05:00
parent 18a363f772
commit 3caf1cce28
17 changed files with 1571 additions and 78 deletions
@@ -0,0 +1,198 @@
+# Руководство по интеграции отправки отчетов по 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: [детали ошибки]
+```