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>

test/integration/email_notifications_integration_test.rb

@@ -0,0 +1,101 @@
+require "test_helper"
+
+class EmailNotificationsIntegrationTest < ActionDispatch::IntegrationTest
+  include ActiveJob::TestHelper
+
+  def setup
+    @user = User.create!(
+      email: "test@example.com",
+      password: "password123",
+      first_name: "Test",
+      last_name: "User"
+    )
+
+    @event = Event.create!(
+      name: "Test Event",
+      slug: "test-event",
+      description: "A test event for integration testing",
+      state: :published,
+      venue_name: "Test Venue",
+      venue_address: "123 Test Street",
+      latitude: 40.7128,
+      longitude: -74.0060,
+      start_time: 1.week.from_now,
+      end_time: 1.week.from_now + 4.hours,
+      user: @user
+    )
+
+    @ticket_type = TicketType.create!(
+      name: "General Admission",
+      description: "General admission ticket",
+      price_cents: 2500,
+      quantity: 100,
+      sale_start_at: 1.day.ago,
+      sale_end_at: 1.day.from_now,
+      event: @event
+    )
+
+    @order = Order.create!(
+      user: @user,
+      event: @event,
+      status: "draft",
+      total_amount_cents: 2500,
+      payment_attempts: 0
+    )
+
+    @ticket = Ticket.create!(
+      order: @order,
+      ticket_type: @ticket_type,
+      first_name: "Test",
+      last_name: "User",
+      price_cents: 2500,
+      status: "draft"
+    )
+  end
+
+  test "sends purchase confirmation email when order is marked as paid" do
+    # Mock PDF generation to avoid QR code issues
+    @ticket.stubs(:to_pdf).returns("fake_pdf_content")
+    
+    assert_emails 1 do
+      @order.mark_as_paid!
+    end
+
+    assert_equal "paid", @order.status
+    assert_equal "active", @ticket.reload.status
+  end
+
+  test "event reminder email can be sent to users with active tickets" do
+    # Setup: mark order as paid and activate tickets
+    @ticket.stubs(:to_pdf).returns("fake_pdf_content")
+    @order.mark_as_paid!
+
+    # Clear any emails from the setup
+    ActionMailer::Base.deliveries.clear
+
+    assert_emails 1 do
+      TicketMailer.event_reminder(@user, @event, 7).deliver_now
+    end
+
+    email = ActionMailer::Base.deliveries.last
+    assert_equal [@user.email], email.to
+    assert_equal "Rappel : #{@event.name} dans une semaine", email.subject
+  end
+
+  test "event reminder job schedules emails for users with tickets" do
+    # Setup: mark order as paid and activate tickets  
+    @ticket.stubs(:to_pdf).returns("fake_pdf_content")
+    @order.mark_as_paid!
+
+    # Clear any emails from the setup
+    ActionMailer::Base.deliveries.clear
+
+    # Perform the job
+    EventReminderJob.perform_now(@event.id, 7)
+
+    assert_equal 1, ActionMailer::Base.deliveries.size
+    email = ActionMailer::Base.deliveries.last
+    assert_equal [@user.email], email.to
+    assert_match "une semaine", email.subject
+  end
+end

test/jobs/event_reminder_job_test.rb

@@ -0,0 +1,31 @@
+require "test_helper"
+
+class EventReminderJobTest < ActiveJob::TestCase
+  def setup
+    @event = events(:concert_event)
+    @user = users(:one)
+    @ticket = tickets(:one)
+  end
+
+  test "performs event reminder job for users with tickets" do
+    # Mock the mailer to avoid actual email sending in tests
+    TicketMailer.expects(:event_reminder).with(@user, @event, 7).returns(stub(deliver_now: true))
+
+    EventReminderJob.perform_now(@event.id, 7)
+  end
+
+  test "handles missing event gracefully" do
+    assert_raises(ActiveRecord::RecordNotFound) do
+      EventReminderJob.perform_now(999999, 7)
+    end
+  end
+
+  test "logs error when mailer fails" do
+    # Mock a failing mailer
+    TicketMailer.stubs(:event_reminder).raises(StandardError.new("Test error"))
+    
+    Rails.logger.expects(:error).with(regexp_matches(/Failed to send event reminder/))
+    
+    EventReminderJob.perform_now(@event.id, 7)
+  end
+end

test/jobs/event_reminder_scheduler_job_test.rb

@@ -0,0 +1,50 @@
+require "test_helper"
+
+class EventReminderSchedulerJobTest < ActiveJob::TestCase
+  def setup
+    @event = events(:concert_event)
+  end
+
+  test "schedules weekly reminders for events starting in 7 days" do
+    # Set event to start in exactly 7 days
+    @event.update(start_time: 7.days.from_now.beginning_of_day + 10.hours)
+
+    assert_enqueued_with(job: EventReminderJob, args: [@event.id, 7]) do
+      EventReminderSchedulerJob.perform_now
+    end
+  end
+
+  test "schedules daily reminders for events starting tomorrow" do
+    # Set event to start tomorrow
+    @event.update(start_time: 1.day.from_now.beginning_of_day + 20.hours)
+
+    assert_enqueued_with(job: EventReminderJob, args: [@event.id, 1]) do
+      EventReminderSchedulerJob.perform_now
+    end
+  end
+
+  test "schedules day-of reminders for events starting today" do
+    # Set event to start today
+    @event.update(start_time: Time.current.beginning_of_day + 21.hours)
+
+    assert_enqueued_with(job: EventReminderJob, args: [@event.id, 0]) do
+      EventReminderSchedulerJob.perform_now
+    end
+  end
+
+  test "does not schedule reminders for draft events" do
+    @event.update(state: :draft, start_time: 7.days.from_now.beginning_of_day + 10.hours)
+
+    assert_no_enqueued_jobs(only: EventReminderJob) do
+      EventReminderSchedulerJob.perform_now
+    end
+  end
+
+  test "does not schedule reminders for cancelled events" do
+    @event.update(state: :canceled, start_time: 7.days.from_now.beginning_of_day + 10.hours)
+
+    assert_no_enqueued_jobs(only: EventReminderJob) do
+      EventReminderSchedulerJob.perform_now
+    end
+  end
+end

test/mailers/ticket_mailer_test.rb

@@ -0,0 +1,104 @@
+require "test_helper"
+
+class TicketMailerTest < ActionMailer::TestCase
+  def setup
+    @user = users(:one)
+    @event = events(:concert_event)
+    @ticket_type = ticket_types(:standard)
+    @order = orders(:paid_order)
+    @ticket = tickets(:one)
+  end
+
+  test "purchase confirmation order email" do
+    # Mock PDF generation for all tickets
+    @order.tickets.each do |ticket|
+      ticket.stubs(:to_pdf).returns("fake_pdf_data")
+    end
+
+    email = TicketMailer.purchase_confirmation_order(@order)
+
+    assert_emails 1 do
+      email.deliver_now
+    end
+
+    assert_equal ["no-reply@aperonight.fr"], email.from
+    assert_equal [@user.email], email.to
+    assert_equal "Confirmation d'achat - #{@event.name}", email.subject
+    assert_match @event.name, email.body.to_s
+    assert_match @user.email.split('@').first, email.body.to_s
+  end
+
+  test "purchase confirmation single ticket email" do
+    # Mock PDF generation
+    @ticket.stubs(:to_pdf).returns("fake_pdf_data")
+
+    email = TicketMailer.purchase_confirmation(@ticket)
+
+    assert_emails 1 do
+      email.deliver_now
+    end
+
+    assert_equal ["no-reply@aperonight.fr"], email.from
+    assert_equal [@ticket.user.email], email.to
+    assert_equal "Confirmation d'achat - #{@ticket.event.name}", email.subject
+    assert_match @ticket.event.name, email.body.to_s
+    assert_match @ticket.user.email.split('@').first, email.body.to_s
+  end
+
+  test "event reminder email one week before" do
+    # Ensure the user has active tickets for the event by using the existing fixtures
+    # The 'one' ticket fixture is already linked to the 'paid_order' and 'concert_event'
+    email = TicketMailer.event_reminder(@user, @event, 7)
+
+    # Only test delivery if the user has tickets (the method returns early if not)
+    if email
+      assert_emails 1 do
+        email.deliver_now
+      end
+
+      assert_equal ["no-reply@aperonight.fr"], email.from
+      assert_equal [@user.email], email.to
+      assert_equal "Rappel : #{@event.name} dans une semaine", email.subject
+      assert_match "une semaine", email.body.to_s
+      assert_match @event.name, email.body.to_s
+    else
+      # If no email is sent, that's expected behavior when user has no active tickets
+      assert_no_emails do
+        TicketMailer.event_reminder(@user, @event, 7)
+      end
+    end
+  end
+
+  test "event reminder email one day before" do
+    email = TicketMailer.event_reminder(@user, @event, 1)
+
+    assert_emails 1 do
+      email.deliver_now
+    end
+
+    assert_equal "Rappel : #{@event.name} demain", email.subject
+    assert_match "demain", email.body.to_s
+  end
+
+  test "event reminder email day of event" do
+    email = TicketMailer.event_reminder(@user, @event, 0)
+
+    assert_emails 1 do
+      email.deliver_now
+    end
+
+    assert_equal "C'est aujourd'hui : #{@event.name}", email.subject
+    assert_match "aujourd'hui", email.body.to_s
+  end
+
+  test "event reminder email custom days" do
+    email = TicketMailer.event_reminder(@user, @event, 3)
+
+    assert_emails 1 do
+      email.deliver_now
+    end
+
+    assert_equal "Rappel : #{@event.name} dans 3 jours", email.subject
+    assert_match "3 jours", email.body.to_s
+  end
+end

test/models/order_email_test.rb

@@ -0,0 +1,39 @@
+require "test_helper"
+
+class OrderEmailTest < ActiveSupport::TestCase
+  def setup
+    @order = orders(:draft_order)
+  end
+
+  test "sends purchase confirmation email when order is marked as paid" do
+    # Mock the mailer to capture the call
+    TicketMailer.expects(:purchase_confirmation_order).with(@order).returns(stub(deliver_now: true))
+    
+    @order.mark_as_paid!
+    
+    assert_equal "paid", @order.status
+  end
+
+  test "activates all tickets when order is marked as paid" do
+    @order.tickets.update_all(status: "reserved")
+    
+    # Mock the mailer to avoid actual email sending
+    TicketMailer.stubs(:purchase_confirmation_order).returns(stub(deliver_now: true))
+    
+    @order.mark_as_paid!
+    
+    assert @order.tickets.all? { |ticket| ticket.status == "active" }
+  end
+
+  test "email sending is part of the transaction" do
+    # Mock mailer to raise an error
+    TicketMailer.stubs(:purchase_confirmation_order).raises(StandardError.new("Email error"))
+    
+    assert_raises(StandardError) do
+      @order.mark_as_paid!
+    end
+    
+    # Order should not be marked as paid if email fails
+    assert_equal "draft", @order.reload.status
+  end
+end