reviewed epic 8 stories
This commit is contained in:
Naser Mansour
@@ -3,6 +3,12 @@
|
||||
## Epic Reference
|
||||
**Epic 8:** Email Notification System
|
||||
|
||||
## Dependencies
|
||||
- **Story 8.1:** Email infrastructure setup (base template, queue config, SMTP)
|
||||
- **Story 8.4:** BookingApprovedEmail pattern and CalendarService integration
|
||||
- **Consultation Model:** Must have `status`, `scheduled_date`, `scheduled_time`, `consultation_type`, `payment_status` fields
|
||||
- **User Model:** Must have `preferred_language` field
|
||||
|
||||
## User Story
|
||||
As a **client**,
|
||||
I want **to receive a reminder 24 hours before my consultation**,
|
||||
@@ -11,54 +17,250 @@ So that **I don't forget my appointment**.
|
||||
## Acceptance Criteria
|
||||
|
||||
### Trigger
|
||||
- [ ] Scheduled job runs daily
|
||||
- [ ] Find consultations 24 hours away
|
||||
- [ ] Only for approved consultations
|
||||
- [ ] Skip cancelled/no-show
|
||||
- [ ] Scheduled artisan command runs hourly
|
||||
- [ ] Find consultations approximately 24 hours away (within 30-minute window)
|
||||
- [ ] Only for approved consultations (`status = 'approved'`)
|
||||
- [ ] Skip cancelled/no-show/completed consultations
|
||||
- [ ] Track sent reminders to prevent duplicates
|
||||
|
||||
### Content
|
||||
- [ ] "Reminder: Your consultation is tomorrow"
|
||||
- [ ] Date and time
|
||||
- [ ] Consultation type
|
||||
- [ ] Payment reminder (if paid and not received)
|
||||
- [ ] Calendar file link
|
||||
- [ ] Any preparation notes
|
||||
- [ ] Subject: "Reminder: Your consultation is tomorrow" / "تذكير: استشارتك غدًا"
|
||||
- [ ] Consultation date and time (formatted per locale)
|
||||
- [ ] Consultation type (free/paid)
|
||||
- [ ] Payment reminder: Show if `consultation_type = 'paid'` AND `payment_status != 'received'`
|
||||
- [ ] Calendar file download link (using route to CalendarService)
|
||||
- [ ] Office contact information for questions
|
||||
|
||||
### Language
|
||||
- [ ] Email in client's preferred language
|
||||
- [ ] Email rendered in client's `preferred_language` (ar/en)
|
||||
- [ ] Date/time formatted according to locale
|
||||
|
||||
## Technical Notes
|
||||
|
||||
### Database Migration
|
||||
Add tracking column to prevent duplicate reminders:
|
||||
|
||||
```php
|
||||
// Command: php artisan reminders:send-24h
|
||||
// database/migrations/xxxx_add_reminder_sent_columns_to_consultations_table.php
|
||||
Schema::table('consultations', function (Blueprint $table) {
|
||||
$table->timestamp('reminder_24h_sent_at')->nullable()->after('status');
|
||||
$table->timestamp('reminder_2h_sent_at')->nullable()->after('reminder_24h_sent_at');
|
||||
});
|
||||
```
|
||||
|
||||
### Artisan Command
|
||||
```php
|
||||
// app/Console/Commands/Send24HourReminders.php
|
||||
namespace App\Console\Commands;
|
||||
|
||||
use App\Models\Consultation;
|
||||
use App\Notifications\ConsultationReminder24h;
|
||||
use Carbon\Carbon;
|
||||
use Illuminate\Console\Command;
|
||||
|
||||
class Send24HourReminders extends Command
|
||||
{
|
||||
protected $signature = 'reminders:send-24h';
|
||||
protected $description = 'Send 24-hour consultation reminders';
|
||||
|
||||
public function handle(): int
|
||||
{
|
||||
$targetTime = now()->addHours(24);
|
||||
$windowStart = $targetTime->copy()->subMinutes(30);
|
||||
$windowEnd = $targetTime->copy()->addMinutes(30);
|
||||
|
||||
Consultation::where('status', 'approved')
|
||||
$consultations = Consultation::query()
|
||||
->where('status', 'approved')
|
||||
->whereNull('reminder_24h_sent_at')
|
||||
->whereDate('scheduled_date', $targetTime->toDateString())
|
||||
->each(function ($consultation) {
|
||||
$consultation->user->notify(new ConsultationReminder24h($consultation));
|
||||
$consultation->update(['reminder_24h_sent_at' => now()]);
|
||||
->get()
|
||||
->filter(function ($consultation) use ($windowStart, $windowEnd) {
|
||||
$consultationDateTime = Carbon::parse(
|
||||
$consultation->scheduled_date->format('Y-m-d') . ' ' . $consultation->scheduled_time
|
||||
);
|
||||
return $consultationDateTime->between($windowStart, $windowEnd);
|
||||
});
|
||||
|
||||
$count = 0;
|
||||
foreach ($consultations as $consultation) {
|
||||
$consultation->user->notify(new ConsultationReminder24h($consultation));
|
||||
$consultation->update(['reminder_24h_sent_at' => now()]);
|
||||
$count++;
|
||||
}
|
||||
|
||||
$this->info("Sent {$count} reminder(s).");
|
||||
|
||||
return Command::SUCCESS;
|
||||
}
|
||||
}
|
||||
|
||||
// Schedule: hourly
|
||||
```
|
||||
|
||||
### Notification Class
|
||||
```php
|
||||
// app/Notifications/ConsultationReminder24h.php
|
||||
namespace App\Notifications;
|
||||
|
||||
use App\Models\Consultation;
|
||||
use Illuminate\Bus\Queueable;
|
||||
use Illuminate\Contracts\Queue\ShouldQueue;
|
||||
use Illuminate\Notifications\Messages\MailMessage;
|
||||
use Illuminate\Notifications\Notification;
|
||||
|
||||
class ConsultationReminder24h extends Notification implements ShouldQueue
|
||||
{
|
||||
use Queueable;
|
||||
|
||||
public function __construct(
|
||||
public Consultation $consultation
|
||||
) {}
|
||||
|
||||
public function via(object $notifiable): array
|
||||
{
|
||||
return ['mail'];
|
||||
}
|
||||
|
||||
public function toMail(object $notifiable): MailMessage
|
||||
{
|
||||
$locale = $notifiable->preferred_language ?? 'ar';
|
||||
$consultation = $this->consultation;
|
||||
|
||||
$subject = $locale === 'ar'
|
||||
? 'تذكير: استشارتك غدًا'
|
||||
: 'Reminder: Your consultation is tomorrow';
|
||||
|
||||
$message = (new MailMessage)
|
||||
->subject($subject)
|
||||
->markdown("emails.reminders.consultation-24h.{$locale}", [
|
||||
'consultation' => $consultation,
|
||||
'user' => $notifiable,
|
||||
'showPaymentReminder' => $this->shouldShowPaymentReminder(),
|
||||
'calendarUrl' => route('consultations.calendar', $consultation),
|
||||
]);
|
||||
|
||||
return $message;
|
||||
}
|
||||
|
||||
private function shouldShowPaymentReminder(): bool
|
||||
{
|
||||
return $this->consultation->consultation_type === 'paid'
|
||||
&& $this->consultation->payment_status !== 'received';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Email Templates
|
||||
|
||||
**Arabic Template:** `resources/views/emails/reminders/consultation-24h/ar.blade.php`
|
||||
**English Template:** `resources/views/emails/reminders/consultation-24h/en.blade.php`
|
||||
|
||||
Template content should include:
|
||||
- Greeting with client name
|
||||
- Reminder message ("Your consultation is scheduled for tomorrow")
|
||||
- Date/time (formatted: `scheduled_date->translatedFormat()`)
|
||||
- Consultation type badge
|
||||
- Payment reminder section (conditional)
|
||||
- "Add to Calendar" button linking to `$calendarUrl`
|
||||
- Office contact information
|
||||
- Branded footer (from Story 8.1 base template)
|
||||
|
||||
### Schedule Registration
|
||||
```php
|
||||
// routes/console.php or bootstrap/app.php
|
||||
Schedule::command('reminders:send-24h')->hourly();
|
||||
```
|
||||
|
||||
## Edge Cases & Error Handling
|
||||
|
||||
| Scenario | Handling |
|
||||
|----------|----------|
|
||||
| Notification fails to send | Queue will retry; failed jobs logged to `failed_jobs` table |
|
||||
| Consultation rescheduled after reminder | New datetime won't trigger duplicate (24h check resets) |
|
||||
| Consultation cancelled after reminder sent | No action needed - reminder already sent |
|
||||
| User has no email | Notification skipped (Laravel handles gracefully) |
|
||||
| Timezone considerations | All times stored/compared in app timezone (configured in `config/app.php`) |
|
||||
|
||||
## Test Scenarios
|
||||
|
||||
### Unit Tests (`tests/Unit/Commands/Send24HourRemindersTest.php`)
|
||||
```php
|
||||
test('command finds consultations approximately 24 hours away', function () {
|
||||
// Create consultation 24 hours from now
|
||||
// Run command
|
||||
// Assert notification sent
|
||||
});
|
||||
|
||||
test('command skips consultations with reminder already sent', function () {
|
||||
// Create consultation with reminder_24h_sent_at set
|
||||
// Run command
|
||||
// Assert no notification sent
|
||||
});
|
||||
|
||||
test('command skips non-approved consultations', function () {
|
||||
// Create cancelled, no-show, pending consultations
|
||||
// Run command
|
||||
// Assert no notifications sent
|
||||
});
|
||||
```
|
||||
|
||||
### Feature Tests (`tests/Feature/Notifications/ConsultationReminder24hTest.php`)
|
||||
```php
|
||||
test('reminder email contains correct consultation details', function () {
|
||||
// Create consultation
|
||||
// Send notification
|
||||
// Assert email contains date, time, type
|
||||
});
|
||||
|
||||
test('payment reminder shown for unpaid paid consultations', function () {
|
||||
// Create paid consultation with payment_status = 'pending'
|
||||
// Assert email contains payment reminder section
|
||||
});
|
||||
|
||||
test('payment reminder hidden when payment received', function () {
|
||||
// Create paid consultation with payment_status = 'received'
|
||||
// Assert email does NOT contain payment reminder
|
||||
});
|
||||
|
||||
test('email uses client preferred language', function () {
|
||||
// Create user with preferred_language = 'en'
|
||||
// Assert email template is English version
|
||||
});
|
||||
|
||||
test('calendar download link is included', function () {
|
||||
// Assert email contains route('consultations.calendar', $consultation)
|
||||
});
|
||||
```
|
||||
|
||||
## Files to Create/Modify
|
||||
|
||||
| File | Action |
|
||||
|------|--------|
|
||||
| `database/migrations/xxxx_add_reminder_sent_columns_to_consultations_table.php` | CREATE |
|
||||
| `app/Console/Commands/Send24HourReminders.php` | CREATE |
|
||||
| `app/Notifications/ConsultationReminder24h.php` | CREATE |
|
||||
| `resources/views/emails/reminders/consultation-24h/ar.blade.php` | CREATE |
|
||||
| `resources/views/emails/reminders/consultation-24h/en.blade.php` | CREATE |
|
||||
| `routes/console.php` | MODIFY (add schedule) |
|
||||
| `tests/Unit/Commands/Send24HourRemindersTest.php` | CREATE |
|
||||
| `tests/Feature/Notifications/ConsultationReminder24hTest.php` | CREATE |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] Command runs successfully
|
||||
- [ ] Reminders sent to correct consultations
|
||||
- [ ] Payment reminder for unpaid
|
||||
- [ ] No duplicate reminders
|
||||
- [ ] Bilingual templates
|
||||
- [ ] Tests pass
|
||||
- [ ] Migration adds `reminder_24h_sent_at` column to consultations table
|
||||
- [ ] Artisan command `reminders:send-24h` created and works
|
||||
- [ ] Command scheduled to run hourly
|
||||
- [ ] Notification class implements `ShouldQueue`
|
||||
- [ ] Reminders only sent for approved consultations within 24h window
|
||||
- [ ] No duplicate reminders (tracking column updated)
|
||||
- [ ] Payment reminder shown only when `paid` AND `payment_status != 'received'`
|
||||
- [ ] Calendar download link included
|
||||
- [ ] Bilingual email templates (Arabic/English)
|
||||
- [ ] All unit and feature tests pass
|
||||
- [ ] Code formatted with `vendor/bin/pint`
|
||||
|
||||
## References
|
||||
- **PRD Section 5.4:** Email Notifications - "Consultation reminder (24 hours before)"
|
||||
- **PRD Section 8.2:** Email Templates - Template requirements and branding
|
||||
- **Story 8.1:** Base email template and queue configuration
|
||||
- **Story 8.4:** Pattern for calendar file attachment/linking
|
||||
|
||||
## Estimation
|
||||
**Complexity:** Medium | **Effort:** 3 hours
|
||||
|
||||
Reference in New Issue
Block a user