307 lines
8.5 KiB
Markdown
307 lines
8.5 KiB
Markdown
# Epic 8: Email Notification System
|
|
|
|
> **Note:** The color palette referenced in this epic (Navy+Gold) has been superseded.
|
|
> Epic 10 (Brand Color Refresh) updated all colors to Charcoal+Warm Gray palette.
|
|
> See `docs/brand.md` for current brand specifications.
|
|
|
|
## Epic Goal
|
|
|
|
Implement a comprehensive email notification system with professional templates, bilingual support, and reliable delivery for all platform communications.
|
|
|
|
## Epic Description
|
|
|
|
### Business Context
|
|
|
|
Email is the primary communication channel. Clients receive mandatory notifications (no opt-out) for account creation, booking updates, reminders, and timeline updates. Admin receives notifications for new bookings and system events.
|
|
|
|
### Technical Context
|
|
|
|
- **Sender:** no-reply@libra.ps
|
|
- **Sender Name:** Libra Law Firm / مكتب ليبرا للمحاماة
|
|
- **SMTP:** Configured via .env
|
|
- **Delivery:** All mandatory (no opt-out for clients)
|
|
- **Templates:** Professional with branding
|
|
|
|
### Success Criteria
|
|
|
|
- [ ] Professional email templates with branding
|
|
- [ ] Bilingual emails (based on recipient preference)
|
|
- [ ] All 9+ notification types implemented
|
|
- [ ] Calendar file attachments
|
|
- [ ] Queued delivery for performance
|
|
- [ ] Plain text fallback
|
|
- [ ] Consistent branding across all emails
|
|
|
|
---
|
|
|
|
## Stories
|
|
|
|
### Story 8.1: Email Infrastructure Setup
|
|
|
|
**Description:** Configure email sending infrastructure and base template.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] SMTP configuration via .env:
|
|
- MAIL_MAILER
|
|
- MAIL_HOST
|
|
- MAIL_PORT
|
|
- MAIL_USERNAME
|
|
- MAIL_PASSWORD
|
|
- MAIL_ENCRYPTION
|
|
- MAIL_FROM_ADDRESS (no-reply@libra.ps)
|
|
- MAIL_FROM_NAME
|
|
- [ ] Base email template with:
|
|
- Libra logo header
|
|
- Navy blue (#0A1F44) and gold (#D4AF37) colors
|
|
- Professional typography
|
|
- Footer with firm contact info
|
|
- Mobile-responsive layout
|
|
- [ ] Plain text fallback generation
|
|
- [ ] Queue configuration for async sending
|
|
- [ ] Email logging for debugging
|
|
|
|
**Technical Notes:**
|
|
- Use Laravel Mail with Mailable classes
|
|
- Create base Mailable with shared layout
|
|
- Configure queue connection
|
|
|
|
---
|
|
|
|
### Story 8.2: Welcome Email (Account Created)
|
|
|
|
**Description:** Email sent when admin creates a new client account.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Triggered on user creation
|
|
- [ ] **Content:**
|
|
- Personalized greeting (name/company)
|
|
- "Your account has been created"
|
|
- Login credentials (email, password)
|
|
- Login URL link
|
|
- Brief platform introduction
|
|
- Contact info for questions
|
|
- [ ] Language based on user's preferred_language
|
|
- [ ] Call-to-action button: "Login Now"
|
|
- [ ] Security note about changing password (N/A - admin only)
|
|
|
|
**Technical Notes:**
|
|
- Mailable: WelcomeEmail
|
|
- Trigger: User created event
|
|
- Queue for performance
|
|
|
|
---
|
|
|
|
### Story 8.3: Booking Submitted Confirmation
|
|
|
|
**Description:** Email to client confirming their booking request was submitted.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Triggered on booking submission
|
|
- [ ] **Content:**
|
|
- "Your consultation request has been submitted"
|
|
- Requested date and time
|
|
- Problem summary preview
|
|
- "Pending Review" status note
|
|
- Expected response timeframe (general)
|
|
- [ ] Language based on client preference
|
|
- [ ] No action required message
|
|
|
|
**Technical Notes:**
|
|
- Mailable: BookingSubmittedEmail
|
|
- Trigger: Consultation created with status 'pending'
|
|
|
|
---
|
|
|
|
### Story 8.4: Booking Approved Email
|
|
|
|
**Description:** Email to client when admin approves their booking.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Triggered on booking approval
|
|
- [ ] **Content:**
|
|
- "Your consultation has been approved"
|
|
- Confirmed date and time
|
|
- Duration (45 minutes)
|
|
- Consultation type (free/paid)
|
|
- If paid: amount and payment instructions
|
|
- Calendar file (.ics) attached
|
|
- "Add to Calendar" button/link
|
|
- Location/contact information
|
|
- [ ] Language based on client preference
|
|
- [ ] Professional confirmation tone
|
|
|
|
**Technical Notes:**
|
|
- Mailable: BookingApprovedEmail
|
|
- Attach .ics file from Epic 3
|
|
- Trigger: Consultation status changed to 'approved'
|
|
|
|
---
|
|
|
|
### Story 8.5: Booking Rejected Email
|
|
|
|
**Description:** Email to client when admin rejects their booking.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Triggered on booking rejection
|
|
- [ ] **Content:**
|
|
- "Your consultation request could not be approved"
|
|
- Original requested date and time
|
|
- Rejection reason (if provided by admin)
|
|
- Invitation to request new consultation
|
|
- Contact info for questions
|
|
- [ ] Empathetic, professional tone
|
|
- [ ] Language based on client preference
|
|
|
|
**Technical Notes:**
|
|
- Mailable: BookingRejectedEmail
|
|
- Optional reason field from admin
|
|
- Trigger: Consultation status changed to 'rejected'
|
|
|
|
---
|
|
|
|
### Story 8.6: Consultation Reminder (24 Hours)
|
|
|
|
**Description:** Reminder email sent 24 hours before scheduled consultation.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Scheduled job runs daily
|
|
- [ ] Find consultations 24 hours away
|
|
- [ ] **Content:**
|
|
- "Reminder: Your consultation is tomorrow"
|
|
- Date and time
|
|
- Consultation type
|
|
- Payment reminder (if paid and not received)
|
|
- Calendar file link
|
|
- Any preparation notes
|
|
- [ ] Skip cancelled/no-show consultations
|
|
- [ ] Language based on client preference
|
|
|
|
**Technical Notes:**
|
|
- Scheduled command: php artisan reminders:send-24h
|
|
- Run via Laravel scheduler
|
|
- Mailable: ConsultationReminder24Email
|
|
|
|
---
|
|
|
|
### Story 8.7: Consultation Reminder (2 Hours)
|
|
|
|
**Description:** Reminder email sent 2 hours before scheduled consultation.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Scheduled job runs hourly
|
|
- [ ] Find consultations 2 hours away
|
|
- [ ] **Content:**
|
|
- "Your consultation is in 2 hours"
|
|
- Date and time
|
|
- Final payment reminder (if applicable)
|
|
- Contact info for last-minute issues
|
|
- [ ] Skip cancelled/no-show consultations
|
|
- [ ] Language based on client preference
|
|
|
|
**Technical Notes:**
|
|
- Scheduled command: php artisan reminders:send-2h
|
|
- More frequent checks for accuracy
|
|
- Mailable: ConsultationReminder2hEmail
|
|
|
|
---
|
|
|
|
### Story 8.8: Timeline Update Notification
|
|
|
|
**Description:** Email to client when admin adds update to their timeline.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Triggered on timeline update creation
|
|
- [ ] **Content:**
|
|
- "Update on your case: [Case Name]"
|
|
- Case reference number
|
|
- Update content (full or summary)
|
|
- Date of update
|
|
- "View Timeline" button/link
|
|
- [ ] Language based on client preference
|
|
- [ ] Professional, informative tone
|
|
|
|
**Technical Notes:**
|
|
- Mailable: TimelineUpdateEmail
|
|
- Trigger: TimelineUpdate created event
|
|
- Link to client dashboard timeline view
|
|
|
|
---
|
|
|
|
### Story 8.9: Admin Notification - New Booking
|
|
|
|
**Description:** Email to admin when client submits new booking request.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Triggered on booking submission
|
|
- [ ] Sent to admin email
|
|
- [ ] **Content:**
|
|
- "New Consultation Request"
|
|
- Client name (individual or company)
|
|
- Requested date and time
|
|
- Problem summary (full)
|
|
- Client contact info
|
|
- "Review Request" button/link
|
|
- [ ] Admin language preference (or default)
|
|
- [ ] Priority indicator in subject line
|
|
|
|
**Technical Notes:**
|
|
- Mailable: NewBookingAdminEmail
|
|
- Send to configured admin email
|
|
- Include direct link to booking management
|
|
|
|
---
|
|
|
|
### Story 8.10: Admin Notification - System Events
|
|
|
|
**Description:** Critical system notifications to admin.
|
|
|
|
**Acceptance Criteria:**
|
|
- [ ] Email failures notification
|
|
- [ ] Scheduled job failures notification
|
|
- [ ] Critical errors summary
|
|
- [ ] **Content:**
|
|
- Event type and description
|
|
- Timestamp
|
|
- Relevant details
|
|
- Recommended action (if any)
|
|
- [ ] Sent immediately (not queued)
|
|
- [ ] Clear subject line indicating urgency
|
|
|
|
**Technical Notes:**
|
|
- Use Laravel exception handler
|
|
- Monitor queues and scheduler
|
|
- Consider separate notification channel
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
| Epic | Dependency |
|
|
|------|------------|
|
|
| Epic 1 | Base application, user preferences |
|
|
| Epic 2 | User creation (welcome email) |
|
|
| Epic 3 | Booking events, calendar files |
|
|
| Epic 4 | Timeline updates |
|
|
|
|
## Risks & Mitigations
|
|
|
|
| Risk | Impact | Mitigation |
|
|
|------|--------|------------|
|
|
| Email delivery failures | High | Queue retry, logging, admin alerts |
|
|
| SMTP configuration issues | High | Test email feature, validation |
|
|
| Spam filtering | Medium | Proper SPF/DKIM, professional content |
|
|
| Timezone issues in reminders | Medium | Store and display in consistent timezone |
|
|
|
|
## Definition of Done
|
|
|
|
- [ ] All stories completed with acceptance criteria met
|
|
- [ ] All 9+ email types implemented
|
|
- [ ] Emails render correctly (HTML and plain text)
|
|
- [ ] Bilingual emails working
|
|
- [ ] Branding consistent across all emails
|
|
- [ ] Queue processing reliable
|
|
- [ ] Reminder jobs scheduled and tested
|
|
- [ ] Calendar attachments working
|
|
- [ ] Admin notifications delivered
|
|
- [ ] Code formatted with Pint
|