402 lines
15 KiB
Markdown
402 lines
15 KiB
Markdown
# Story 8.5: Booking Rejected Email
|
|
|
|
## Epic Reference
|
|
**Epic 8:** Email Notification System
|
|
|
|
## User Story
|
|
As a **client**,
|
|
I want **to be notified when my booking is rejected**,
|
|
So that **I can understand why and request a new consultation if needed**.
|
|
|
|
## Dependencies
|
|
- **Story 8.1:** Email Infrastructure Setup (provides base template, branding, queue configuration)
|
|
- **Epic 3:** Consultation/booking system with status management
|
|
|
|
## Assumptions
|
|
- `Consultation` model exists with `user` relationship (belongsTo User)
|
|
- `User` model has `preferred_language` field (defaults to `'ar'` if null)
|
|
- Admin rejection action captures optional `reason` field
|
|
- Consultation status changes to `'rejected'` when admin rejects
|
|
- Base email template and branding from Story 8.1 are available
|
|
|
|
## Acceptance Criteria
|
|
|
|
### Trigger
|
|
- [x] Sent when consultation status changes to `'rejected'`
|
|
|
|
### Content
|
|
- [x] "Your consultation request could not be approved"
|
|
- [x] Original requested date and time
|
|
- [x] Rejection reason (conditionally shown if provided by admin)
|
|
- [x] Invitation to request new consultation
|
|
- [x] Contact info for questions
|
|
|
|
### Tone
|
|
- [x] Empathetic, professional
|
|
|
|
### Language
|
|
- [x] Email in client's preferred language (Arabic or English)
|
|
- [x] Default to Arabic if no preference set
|
|
|
|
## Technical Notes
|
|
|
|
### Files to Create/Modify
|
|
|
|
| File | Action | Description |
|
|
|------|--------|-------------|
|
|
| `app/Mail/BookingRejectedEmail.php` | Create | Mailable class |
|
|
| `resources/views/emails/booking/rejected/ar.blade.php` | Create | Arabic template (RTL) |
|
|
| `resources/views/emails/booking/rejected/en.blade.php` | Create | English template (LTR) |
|
|
| `app/Listeners/SendBookingRejectedEmail.php` | Create | Event listener |
|
|
| `app/Events/ConsultationRejected.php` | Create | Event class (if not exists) |
|
|
|
|
### Mailable Implementation
|
|
|
|
```php
|
|
namespace App\Mail;
|
|
|
|
use App\Models\Consultation;
|
|
use Illuminate\Bus\Queueable;
|
|
use Illuminate\Contracts\Queue\ShouldQueue;
|
|
use Illuminate\Mail\Mailable;
|
|
use Illuminate\Mail\Mailables\Content;
|
|
use Illuminate\Mail\Mailables\Envelope;
|
|
use Illuminate\Queue\SerializesModels;
|
|
|
|
class BookingRejectedEmail extends Mailable implements ShouldQueue
|
|
{
|
|
use Queueable, SerializesModels;
|
|
|
|
public function __construct(
|
|
public Consultation $consultation,
|
|
public ?string $reason = null
|
|
) {}
|
|
|
|
public function envelope(): Envelope
|
|
{
|
|
$locale = $this->consultation->user->preferred_language ?? 'ar';
|
|
$subject = $locale === 'ar'
|
|
? 'تعذر الموافقة على طلب الاستشارة'
|
|
: 'Your Consultation Request Could Not Be Approved';
|
|
|
|
return new Envelope(subject: $subject);
|
|
}
|
|
|
|
public function content(): Content
|
|
{
|
|
$locale = $this->consultation->user->preferred_language ?? 'ar';
|
|
|
|
return new Content(
|
|
markdown: "emails.booking.rejected.{$locale}",
|
|
with: [
|
|
'consultation' => $this->consultation,
|
|
'reason' => $this->reason,
|
|
'hasReason' => !empty($this->reason),
|
|
],
|
|
);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Event/Listener Trigger
|
|
|
|
```php
|
|
// In admin controller or service when rejecting consultation:
|
|
use App\Events\ConsultationRejected;
|
|
|
|
$consultation->update(['status' => 'rejected']);
|
|
event(new ConsultationRejected($consultation, $reason));
|
|
|
|
// app/Events/ConsultationRejected.php
|
|
class ConsultationRejected
|
|
{
|
|
public function __construct(
|
|
public Consultation $consultation,
|
|
public ?string $reason = null
|
|
) {}
|
|
}
|
|
|
|
// app/Listeners/SendBookingRejectedEmail.php
|
|
class SendBookingRejectedEmail
|
|
{
|
|
public function handle(ConsultationRejected $event): void
|
|
{
|
|
Mail::to($event->consultation->user->email)
|
|
->send(new BookingRejectedEmail(
|
|
$event->consultation,
|
|
$event->reason
|
|
));
|
|
}
|
|
}
|
|
|
|
// Register in EventServiceProvider boot() or use event discovery
|
|
```
|
|
|
|
### Template Structure (Arabic Example)
|
|
|
|
```blade
|
|
{{-- resources/views/emails/booking/rejected/ar.blade.php --}}
|
|
<x-mail::message>
|
|
# تعذر الموافقة على طلب الاستشارة
|
|
|
|
عزيزي/عزيزتي {{ $consultation->user->name }},
|
|
|
|
نأسف لإبلاغك بأنه تعذر علينا الموافقة على طلب الاستشارة الخاص بك.
|
|
|
|
**التاريخ المطلوب:** {{ $consultation->scheduled_at->format('Y-m-d') }}
|
|
**الوقت المطلوب:** {{ $consultation->scheduled_at->format('H:i') }}
|
|
|
|
@if($hasReason)
|
|
**السبب:** {{ $reason }}
|
|
@endif
|
|
|
|
نرحب بك لتقديم طلب استشارة جديد في وقت آخر يناسبك.
|
|
|
|
<x-mail::button :url="route('client.consultations.create')">
|
|
طلب استشارة جديدة
|
|
</x-mail::button>
|
|
|
|
للاستفسارات، تواصل معنا على: info@libra.ps
|
|
|
|
مع أطيب التحيات,
|
|
مكتب ليبرا للمحاماة
|
|
</x-mail::message>
|
|
```
|
|
|
|
## Edge Cases
|
|
|
|
| Scenario | Handling |
|
|
|----------|----------|
|
|
| Reason is null/empty | Hide reason section in template using `@if($hasReason)` |
|
|
| User has no preferred_language | Default to Arabic (`'ar'`) |
|
|
| Queue failure | Standard Laravel queue retry (3 attempts) |
|
|
| User email invalid | Queue will fail, logged for admin review |
|
|
|
|
## Testing Requirements
|
|
|
|
### Unit Tests
|
|
```php
|
|
// tests/Unit/Mail/BookingRejectedEmailTest.php
|
|
|
|
test('booking rejected email renders with reason', function () {
|
|
$consultation = Consultation::factory()->create();
|
|
$reason = 'Schedule conflict';
|
|
|
|
$mailable = new BookingRejectedEmail($consultation, $reason);
|
|
|
|
$mailable->assertSeeInHtml($reason);
|
|
$mailable->assertSeeInHtml($consultation->scheduled_at->format('Y-m-d'));
|
|
});
|
|
|
|
test('booking rejected email renders without reason', function () {
|
|
$consultation = Consultation::factory()->create();
|
|
|
|
$mailable = new BookingRejectedEmail($consultation, null);
|
|
|
|
$mailable->assertDontSeeInHtml('السبب:');
|
|
$mailable->assertDontSeeInHtml('Reason:');
|
|
});
|
|
|
|
test('booking rejected email uses arabic template for arabic preference', function () {
|
|
$user = User::factory()->create(['preferred_language' => 'ar']);
|
|
$consultation = Consultation::factory()->for($user)->create();
|
|
|
|
$mailable = new BookingRejectedEmail($consultation);
|
|
|
|
expect($mailable->content()->markdown)->toBe('emails.booking.rejected.ar');
|
|
});
|
|
|
|
test('booking rejected email uses english template for english preference', function () {
|
|
$user = User::factory()->create(['preferred_language' => 'en']);
|
|
$consultation = Consultation::factory()->for($user)->create();
|
|
|
|
$mailable = new BookingRejectedEmail($consultation);
|
|
|
|
expect($mailable->content()->markdown)->toBe('emails.booking.rejected.en');
|
|
});
|
|
|
|
test('booking rejected email defaults to arabic when no language preference', function () {
|
|
$user = User::factory()->create(['preferred_language' => null]);
|
|
$consultation = Consultation::factory()->for($user)->create();
|
|
|
|
$mailable = new BookingRejectedEmail($consultation);
|
|
|
|
expect($mailable->content()->markdown)->toBe('emails.booking.rejected.ar');
|
|
});
|
|
```
|
|
|
|
### Feature Tests
|
|
```php
|
|
// tests/Feature/Mail/BookingRejectedEmailTest.php
|
|
|
|
test('email is queued when consultation is rejected', function () {
|
|
Mail::fake();
|
|
|
|
$consultation = Consultation::factory()->create(['status' => 'pending']);
|
|
$reason = 'Not available';
|
|
|
|
event(new ConsultationRejected($consultation, $reason));
|
|
|
|
Mail::assertQueued(BookingRejectedEmail::class, function ($mail) use ($consultation) {
|
|
return $mail->consultation->id === $consultation->id;
|
|
});
|
|
});
|
|
|
|
test('email is sent to correct recipient', function () {
|
|
Mail::fake();
|
|
|
|
$user = User::factory()->create(['email' => 'client@example.com']);
|
|
$consultation = Consultation::factory()->for($user)->create();
|
|
|
|
event(new ConsultationRejected($consultation));
|
|
|
|
Mail::assertQueued(BookingRejectedEmail::class, function ($mail) {
|
|
return $mail->hasTo('client@example.com');
|
|
});
|
|
});
|
|
```
|
|
|
|
## Definition of Done
|
|
- [x] `BookingRejectedEmail` mailable class created
|
|
- [x] Arabic template created with RTL layout and empathetic tone
|
|
- [x] English template created with LTR layout and empathetic tone
|
|
- [x] Event and listener wired for consultation rejection (via existing Notification pattern)
|
|
- [x] Reason conditionally displayed when provided
|
|
- [x] Defaults to Arabic when no language preference
|
|
- [x] Email queued (not sent synchronously)
|
|
- [x] All unit tests pass
|
|
- [x] All feature tests pass
|
|
- [x] Code formatted with Pint
|
|
|
|
## Estimation
|
|
**Complexity:** Low | **Effort:** 2-3 hours
|
|
|
|
---
|
|
|
|
## Dev Agent Record
|
|
|
|
### Status
|
|
**Ready for Review**
|
|
|
|
### Agent Model Used
|
|
Claude Opus 4.5 (claude-opus-4-5-20251101)
|
|
|
|
### File List
|
|
| File | Action | Description |
|
|
|------|--------|-------------|
|
|
| `app/Mail/BookingRejectedEmail.php` | Created | Mailable class with bilingual support, ShouldQueue |
|
|
| `resources/views/emails/booking/rejected/ar.blade.php` | Created | Arabic email template (RTL) |
|
|
| `resources/views/emails/booking/rejected/en.blade.php` | Created | English email template (LTR) |
|
|
| `app/Notifications/BookingRejected.php` | Modified | Updated to use new BookingRejectedEmail mailable |
|
|
| `tests/Feature/Mail/BookingRejectedEmailTest.php` | Created | 22 test cases for mailable and notification |
|
|
|
|
### Change Log
|
|
- Created `BookingRejectedEmail` mailable with bilingual template support (ar/en)
|
|
- Created Arabic email template with RTL layout, empathetic tone, conditional reason display
|
|
- Created English email template with LTR layout, empathetic tone, conditional reason display
|
|
- Updated existing `BookingRejected` notification to use the new mailable instead of inline view
|
|
- Created comprehensive test suite (22 tests) covering:
|
|
- Template selection based on language preference
|
|
- Subject lines in both languages
|
|
- Reason display/hide logic
|
|
- Date/time formatting
|
|
- Notification integration
|
|
- Email rendering
|
|
|
|
### Completion Notes
|
|
- **Implementation Note**: The story suggested Event/Listener pattern, but the codebase already had a `BookingRejected` Notification being dispatched from `admin/bookings/review.blade.php`. For consistency and to avoid duplication, I updated the existing notification to use the new Mailable instead of creating a separate Event/Listener system.
|
|
- **Database Schema**: The `preferred_language` column has a default of `'ar'` and is NOT NULL, so the "null handling" in the code is defensive but the database enforces Arabic as default.
|
|
- **All 22 tests pass**, all booking-related tests (141 total) pass, Pint formatting complete.
|
|
|
|
---
|
|
|
|
## QA Results
|
|
|
|
### Review Date: 2026-01-02
|
|
|
|
### Reviewed By: Quinn (Test Architect)
|
|
|
|
### Code Quality Assessment
|
|
|
|
**Overall Grade: Excellent**
|
|
|
|
The implementation is clean, well-structured, and follows established codebase patterns. The mailable class properly implements `ShouldQueue` for asynchronous processing, uses the correct bilingual template strategy, and maintains consistency with the existing `BookingApprovedMail` implementation.
|
|
|
|
**Strengths:**
|
|
- Consistent pattern with existing `BookingApprovedMail` class (same constructor style, locale handling, date/time formatting)
|
|
- Proper use of `ShouldQueue` and `SerializesModels` traits
|
|
- Clean separation of concerns with dedicated formatting methods
|
|
- Defensive null handling for `preferred_language` despite database default
|
|
- Empathetic tone in templates appropriate for rejection scenarios
|
|
- Proper RTL/LTR handling via `<div dir="rtl">` wrapper in Arabic template
|
|
|
|
**Minor Observations (No Action Required):**
|
|
- The class does not extend `BaseMailable` (like `WelcomeEmail` does), but this is consistent with `BookingApprovedMail` - both implement the pattern directly. No change needed for consistency.
|
|
- Button URL uses `config('app.url')` rather than `route('booking')` - this matches the pattern in `BookingApprovedMail` and is acceptable.
|
|
|
|
### Refactoring Performed
|
|
|
|
None required. The code is well-structured and follows established patterns.
|
|
|
|
### Compliance Check
|
|
|
|
- Coding Standards: ✓ Pint passes, follows PSR-12 conventions
|
|
- Project Structure: ✓ Files in correct locations (`app/Mail/`, `resources/views/emails/booking/rejected/`)
|
|
- Testing Strategy: ✓ Comprehensive test coverage with 22 tests covering all acceptance criteria
|
|
- All ACs Met: ✓ See traceability matrix below
|
|
|
|
### Requirements Traceability Matrix
|
|
|
|
| AC | Requirement | Test Coverage |
|
|
|----|-------------|---------------|
|
|
| Trigger | Sent when consultation status changes to 'rejected' | `notification sends booking rejected email`, `notification toMail returns BookingRejectedEmail mailable` |
|
|
| Content | "Your consultation request could not be approved" | `email renders without errors in english`, `email renders without errors in arabic` |
|
|
| Content | Original requested date and time | `date is formatted as d/m/Y for arabic users`, `date is formatted as m/d/Y for english users`, `time is formatted as h:i A`, `content includes all required data` |
|
|
| Content | Rejection reason (conditionally shown) | `booking rejected email includes reason when provided`, `booking rejected email handles null reason`, `booking rejected email handles empty reason`, `email renders reason section when reason provided`, `email does not render reason section when reason not provided` |
|
|
| Content | Invitation to request new consultation | `email renders without errors in english` (verifies button presence) |
|
|
| Content | Contact info for questions | Template contains `info@libra.ps` contact |
|
|
| Tone | Empathetic, professional | Manual review: ✓ Templates use appropriate language ("نأسف", "We regret") |
|
|
| Language | Email in client's preferred language | `booking rejected email uses arabic template for arabic preference`, `booking rejected email uses english template for english preference` |
|
|
| Language | Default to Arabic if no preference | `booking rejected email defaults to arabic from database default` |
|
|
|
|
### Improvements Checklist
|
|
|
|
All items satisfied - no improvements required:
|
|
|
|
- [x] Mailable implements ShouldQueue for async processing
|
|
- [x] Bilingual templates with proper RTL/LTR support
|
|
- [x] Conditional reason display with `@if($hasReason)` directive
|
|
- [x] Consistent date formatting per locale
|
|
- [x] Subject line in user's preferred language
|
|
- [x] 22 comprehensive tests covering all scenarios
|
|
- [x] Integration with existing Notification pattern
|
|
- [x] Pint formatting compliance
|
|
|
|
### Security Review
|
|
|
|
No security concerns identified:
|
|
- No user input is rendered unescaped
|
|
- Email content uses Blade's default escaping
|
|
- No SQL queries or user-controlled data paths
|
|
|
|
### Performance Considerations
|
|
|
|
No performance concerns:
|
|
- Email is queued via `ShouldQueue` (not sent synchronously)
|
|
- `SerializesModels` properly serializes the Consultation model for queue processing
|
|
- No N+1 queries in template rendering
|
|
|
|
### Files Modified During Review
|
|
|
|
None - no modifications were required.
|
|
|
|
### Gate Status
|
|
|
|
Gate: **PASS** → docs/qa/gates/8.5-booking-rejected-email.yml
|
|
|
|
### Recommended Status
|
|
|
|
✓ **Ready for Done**
|
|
|
|
All acceptance criteria are met, all 22 tests pass, code follows established patterns, and no security or performance concerns exist.
|