feat: Implement comprehensive email notifications system
This commit implements a complete email notifications system for purchase confirmations and event reminders as requested in the medium priority backlog tasks. ## Features Added ### Purchase Confirmation Emails - Automatically sent when orders are marked as paid - Supports both single tickets and multi-ticket orders - Includes PDF ticket attachments - Professional HTML and text templates in French ### Event Reminder Emails - Automated reminders sent 7 days, 1 day, and day of events - Only sent to users with active tickets - Smart messaging based on time until event - Venue details and ticket information included ### Background Jobs - EventReminderJob: Sends reminders to all users for a specific event - EventReminderSchedulerJob: Daily scheduler to queue reminder jobs - Proper error handling and logging ### Email Templates - Responsive HTML templates with ApéroNight branding - Text fallbacks for better email client compatibility - Dynamic content based on number of tickets and time until event ### Configuration & Testing - Environment-based SMTP configuration for production - Development setup with MailCatcher support - Comprehensive test suite with mocking for PDF generation - Integration tests for end-to-end functionality - Documentation with usage examples ## Technical Implementation - Enhanced TicketMailer with new notification methods - Background job scheduling via Rails initializer - Order model integration for automatic purchase confirmations - Proper associations handling for user/ticket relationships - Configurable via environment variables ## Files Added/Modified - Enhanced app/mailers/ticket_mailer.rb with order support - Added app/jobs/event_reminder_*.rb for background processing - Updated email templates in app/views/ticket_mailer/ - Added automatic scheduling in config/initializers/ - Comprehensive test coverage in test/ directory - Complete documentation in docs/email-notifications.md 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kbe
162
docs/email-notifications.md
Normal file
162
docs/email-notifications.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# Email Notifications System
|
||||
|
||||
This document describes the email notifications system implemented for ApéroNight.
|
||||
|
||||
## Overview
|
||||
|
||||
The email notifications system provides two main types of notifications:
|
||||
1. **Purchase Confirmation Emails** - Sent when orders are completed
|
||||
2. **Event Reminder Emails** - Sent at scheduled intervals before events
|
||||
|
||||
## Features
|
||||
|
||||
### Purchase Confirmation Emails
|
||||
|
||||
- **Trigger**: Automatically sent when an order is marked as paid
|
||||
- **Content**: Order details, ticket information, PDF attachments for each ticket
|
||||
- **Template**: Supports both single tickets and multi-ticket orders
|
||||
- **Languages**: French (can be extended)
|
||||
|
||||
### Event Reminder Emails
|
||||
|
||||
- **Schedule**: 7 days before, 1 day before, and day of event
|
||||
- **Content**: Event details, user's ticket information, venue information
|
||||
- **Recipients**: Only users with active tickets for the event
|
||||
- **Smart Content**: Different messaging based on time until event
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### Mailer Classes
|
||||
|
||||
#### TicketMailer
|
||||
- `purchase_confirmation_order(order)` - For complete orders with multiple tickets
|
||||
- `purchase_confirmation(ticket)` - For individual tickets
|
||||
- `event_reminder(user, event, days_before)` - For event reminders
|
||||
|
||||
### Background Jobs
|
||||
|
||||
#### EventReminderJob
|
||||
- Sends reminder emails to all users with active tickets for a specific event
|
||||
- Parameters: `event_id`, `days_before`
|
||||
- Error handling: Logs failures but continues processing other users
|
||||
|
||||
#### EventReminderSchedulerJob
|
||||
- Runs daily to schedule reminder emails
|
||||
- Automatically finds events starting in 7 days, 1 day, or same day
|
||||
- Only processes published events
|
||||
- Configurable via environment variables
|
||||
|
||||
### Email Templates
|
||||
|
||||
Templates are available in both HTML and text formats:
|
||||
|
||||
- `app/views/ticket_mailer/purchase_confirmation.html.erb`
|
||||
- `app/views/ticket_mailer/purchase_confirmation.text.erb`
|
||||
- `app/views/ticket_mailer/event_reminder.html.erb`
|
||||
- `app/views/ticket_mailer/event_reminder.text.erb`
|
||||
|
||||
### Configuration
|
||||
|
||||
#### Environment Variables
|
||||
- `MAILER_FROM_EMAIL` - From address for emails (default: no-reply@aperonight.fr)
|
||||
- `SMTP_*` - SMTP configuration for production
|
||||
- `SCHEDULE_REMINDERS` - Enable automatic reminder scheduling in non-production
|
||||
|
||||
#### Development Setup
|
||||
- Uses localhost:1025 for development (MailCatcher recommended)
|
||||
- Email delivery is configured but won't raise errors in development
|
||||
|
||||
## Usage
|
||||
|
||||
### Manual Testing
|
||||
|
||||
```ruby
|
||||
# Test purchase confirmation
|
||||
order = Order.last
|
||||
TicketMailer.purchase_confirmation_order(order).deliver_now
|
||||
|
||||
# Test event reminder
|
||||
user = User.first
|
||||
event = Event.published.first
|
||||
TicketMailer.event_reminder(user, event, 7).deliver_now
|
||||
|
||||
# Test scheduler job
|
||||
EventReminderSchedulerJob.perform_now
|
||||
```
|
||||
|
||||
### Integration in Code
|
||||
|
||||
Purchase confirmation emails are automatically sent when orders are marked as paid:
|
||||
|
||||
```ruby
|
||||
order.mark_as_paid! # Automatically sends confirmation email
|
||||
```
|
||||
|
||||
Event reminders are automatically scheduled via the initializer, but can be manually triggered:
|
||||
|
||||
```ruby
|
||||
# Schedule reminders for a specific event
|
||||
EventReminderJob.perform_later(event.id, 7) # 7 days before
|
||||
```
|
||||
|
||||
## Deployment Notes
|
||||
|
||||
### Production Configuration
|
||||
|
||||
1. Configure SMTP settings via environment variables
|
||||
2. Set `MAILER_FROM_EMAIL` to your domain
|
||||
3. Ensure `SCHEDULE_REMINDERS=true` to enable automatic reminders
|
||||
4. Configure solid_queue for background job processing
|
||||
|
||||
### Monitoring
|
||||
|
||||
- Check logs for email delivery failures
|
||||
- Monitor job queue for stuck reminder jobs
|
||||
- Verify SMTP configuration is working
|
||||
|
||||
### Customization
|
||||
|
||||
- Email templates can be customized in `app/views/ticket_mailer/`
|
||||
- Add new reminder intervals by modifying `EventReminderSchedulerJob`
|
||||
- Internationalization can be added using Rails I18n
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
app/
|
||||
├── jobs/
|
||||
│ ├── event_reminder_job.rb
|
||||
│ └── event_reminder_scheduler_job.rb
|
||||
├── mailers/
|
||||
│ ├── application_mailer.rb
|
||||
│ └── ticket_mailer.rb
|
||||
└── views/
|
||||
└── ticket_mailer/
|
||||
├── purchase_confirmation.html.erb
|
||||
├── purchase_confirmation.text.erb
|
||||
├── event_reminder.html.erb
|
||||
└── event_reminder.text.erb
|
||||
|
||||
config/
|
||||
├── environments/
|
||||
│ ├── development.rb (SMTP localhost:1025)
|
||||
│ └── production.rb (ENV-based SMTP)
|
||||
└── initializers/
|
||||
└── event_reminder_scheduler.rb
|
||||
|
||||
test/
|
||||
├── jobs/
|
||||
│ ├── event_reminder_job_test.rb
|
||||
│ └── event_reminder_scheduler_job_test.rb
|
||||
├── mailers/
|
||||
│ └── ticket_mailer_test.rb
|
||||
└── integration/
|
||||
└── email_notifications_integration_test.rb
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- No sensitive information in email templates
|
||||
- User data is properly escaped in templates
|
||||
- QR codes contain only necessary ticket verification data
|
||||
- Email addresses are validated through Devise
|
||||
Reference in New Issue
Block a user