355 lines
10 KiB
Markdown
355 lines
10 KiB
Markdown
# Story 8.8: Timeline Update Notification
|
|
|
|
## Epic Reference
|
|
**Epic 8:** Email Notification System
|
|
|
|
## Story Context
|
|
This story implements email notifications when admin adds updates to a client's case timeline (from Epic 4). When admin creates a `TimelineUpdate` record, the associated client automatically receives an email with the update details, keeping them informed of their case progress without needing to manually check the portal.
|
|
|
|
## User Story
|
|
As a **client**,
|
|
I want **to be notified via email when my case timeline is updated**,
|
|
So that **I stay informed about my case progress without having to repeatedly check the portal**.
|
|
|
|
## Dependencies
|
|
- **Requires**: Story 8.1 (Email Infrastructure - `BaseMailable` class and templates)
|
|
- **Requires**: Epic 4 Stories 4.1-4.2 (Timeline and TimelineUpdate models must exist)
|
|
- **Blocks**: None
|
|
|
|
## Data Model Reference
|
|
|
|
From Epic 4, the relevant models are:
|
|
|
|
```
|
|
Timeline
|
|
├── id
|
|
├── user_id (FK → users.id, the client)
|
|
├── case_name (string, required)
|
|
├── case_reference (string, optional, unique if provided)
|
|
├── status (enum: 'active', 'archived')
|
|
├── created_at
|
|
└── updated_at
|
|
|
|
TimelineUpdate
|
|
├── id
|
|
├── timeline_id (FK → timelines.id)
|
|
├── admin_id (FK → users.id, the admin who created it)
|
|
├── update_text (text, the update content)
|
|
├── created_at
|
|
└── updated_at
|
|
|
|
Relationships:
|
|
- TimelineUpdate belongsTo Timeline
|
|
- Timeline belongsTo User (client)
|
|
- Timeline hasMany TimelineUpdate
|
|
- Access client: $timelineUpdate->timeline->user
|
|
```
|
|
|
|
## Acceptance Criteria
|
|
|
|
### Trigger
|
|
- [ ] Email sent automatically when `TimelineUpdate` is created
|
|
- [ ] Uses model observer pattern for clean separation
|
|
- [ ] Email queued for performance (not sent synchronously)
|
|
- [ ] Only triggered for active timelines (not archived)
|
|
|
|
### Content
|
|
- [ ] Subject: "Update on your case: [Case Name]" / "تحديث على قضيتك: [اسم القضية]"
|
|
- [ ] Case reference number (if exists)
|
|
- [ ] Full update content text
|
|
- [ ] Date of update (formatted for locale)
|
|
- [ ] "View Timeline" button linking to client dashboard timeline view
|
|
|
|
### Language
|
|
- [ ] Email template selected based on client's `preferred_language`
|
|
- [ ] Default to Arabic ('ar') if no preference set
|
|
- [ ] Date formatting appropriate for locale
|
|
|
|
### Design
|
|
- [ ] Uses base email template from Story 8.1 (Libra branding)
|
|
- [ ] Professional, informative tone
|
|
- [ ] Clear visual hierarchy: case name → update content → action button
|
|
|
|
## Technical Implementation
|
|
|
|
### Files to Create/Modify
|
|
|
|
| File | Action | Description |
|
|
|------|--------|-------------|
|
|
| `app/Mail/TimelineUpdateEmail.php` | Create | Mailable extending BaseMailable |
|
|
| `resources/views/emails/timeline/update-ar.blade.php` | Create | Arabic email template |
|
|
| `resources/views/emails/timeline/update-en.blade.php` | Create | English email template |
|
|
| `app/Observers/TimelineUpdateObserver.php` | Create | Observer to trigger email |
|
|
| `app/Providers/AppServiceProvider.php` | Modify | Register the observer |
|
|
|
|
### Mailable Implementation
|
|
|
|
```php
|
|
<?php
|
|
|
|
namespace App\Mail;
|
|
|
|
use App\Models\TimelineUpdate;
|
|
use Illuminate\Mail\Mailables\Content;
|
|
use Illuminate\Mail\Mailables\Envelope;
|
|
|
|
class TimelineUpdateEmail extends BaseMailable
|
|
{
|
|
public function __construct(
|
|
public TimelineUpdate $update
|
|
) {
|
|
$this->locale = $this->update->timeline->user->preferred_language ?? 'ar';
|
|
}
|
|
|
|
public function envelope(): Envelope
|
|
{
|
|
$caseName = $this->update->timeline->case_name;
|
|
$subject = $this->locale === 'ar'
|
|
? "تحديث على قضيتك: {$caseName}"
|
|
: "Update on your case: {$caseName}";
|
|
|
|
return new Envelope(
|
|
subject: $subject,
|
|
);
|
|
}
|
|
|
|
public function content(): Content
|
|
{
|
|
return new Content(
|
|
markdown: "emails.timeline.update-{$this->locale}",
|
|
with: [
|
|
'update' => $this->update,
|
|
'timeline' => $this->update->timeline,
|
|
'client' => $this->update->timeline->user,
|
|
'viewUrl' => route('client.timelines.show', $this->update->timeline),
|
|
],
|
|
);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Observer Implementation
|
|
|
|
```php
|
|
<?php
|
|
|
|
namespace App\Observers;
|
|
|
|
use App\Mail\TimelineUpdateEmail;
|
|
use App\Models\TimelineUpdate;
|
|
use Illuminate\Support\Facades\Mail;
|
|
|
|
class TimelineUpdateObserver
|
|
{
|
|
public function created(TimelineUpdate $update): void
|
|
{
|
|
// Only send for active timelines
|
|
if ($update->timeline->status !== 'active') {
|
|
return;
|
|
}
|
|
|
|
$client = $update->timeline->user;
|
|
|
|
Mail::to($client->email)->queue(
|
|
new TimelineUpdateEmail($update)
|
|
);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Register Observer
|
|
|
|
In `AppServiceProvider::boot()`:
|
|
|
|
```php
|
|
use App\Models\TimelineUpdate;
|
|
use App\Observers\TimelineUpdateObserver;
|
|
|
|
public function boot(): void
|
|
{
|
|
TimelineUpdate::observe(TimelineUpdateObserver::class);
|
|
}
|
|
```
|
|
|
|
### Arabic Template Structure (`update-ar.blade.php`)
|
|
|
|
```blade
|
|
<x-mail::message>
|
|
# تحديث على قضيتك
|
|
|
|
**اسم القضية:** {{ $timeline->case_name }}
|
|
@if($timeline->case_reference)
|
|
**رقم المرجع:** {{ $timeline->case_reference }}
|
|
@endif
|
|
|
|
---
|
|
|
|
## التحديث
|
|
|
|
{{ $update->update_text }}
|
|
|
|
**تاريخ التحديث:** {{ $update->created_at->locale('ar')->isoFormat('LL') }}
|
|
|
|
<x-mail::button :url="$viewUrl">
|
|
عرض الجدول الزمني
|
|
</x-mail::button>
|
|
|
|
مع تحياتنا,<br>
|
|
{{ config('app.name') }}
|
|
</x-mail::message>
|
|
```
|
|
|
|
### English Template Structure (`update-en.blade.php`)
|
|
|
|
```blade
|
|
<x-mail::message>
|
|
# Update on Your Case
|
|
|
|
**Case Name:** {{ $timeline->case_name }}
|
|
@if($timeline->case_reference)
|
|
**Reference:** {{ $timeline->case_reference }}
|
|
@endif
|
|
|
|
---
|
|
|
|
## Update
|
|
|
|
{{ $update->update_text }}
|
|
|
|
**Date:** {{ $update->created_at->format('F j, Y') }}
|
|
|
|
<x-mail::button :url="$viewUrl">
|
|
View Timeline
|
|
</x-mail::button>
|
|
|
|
Best regards,<br>
|
|
{{ config('app.name') }}
|
|
</x-mail::message>
|
|
```
|
|
|
|
## Edge Cases & Error Handling
|
|
|
|
| Scenario | Handling |
|
|
|----------|----------|
|
|
| Archived timeline gets update | No email sent (observer checks status) |
|
|
| Client has no `preferred_language` | Default to Arabic ('ar') |
|
|
| Client email is null/invalid | Mail will fail gracefully, logged to failed_jobs |
|
|
| Timeline has no case_reference | Template conditionally hides reference line |
|
|
| Multiple rapid updates | Each triggers separate email (acceptable per requirements) |
|
|
|
|
## Testing Requirements
|
|
|
|
### Test File
|
|
Create `tests/Feature/Mail/TimelineUpdateEmailTest.php`
|
|
|
|
### Test Scenarios
|
|
|
|
```php
|
|
<?php
|
|
|
|
use App\Mail\TimelineUpdateEmail;
|
|
use App\Models\Timeline;
|
|
use App\Models\TimelineUpdate;
|
|
use App\Models\User;
|
|
use Illuminate\Support\Facades\Mail;
|
|
|
|
test('email is queued when timeline update is created', function () {
|
|
Mail::fake();
|
|
|
|
$client = User::factory()->create(['preferred_language' => 'en']);
|
|
$timeline = Timeline::factory()->for($client)->create(['status' => 'active']);
|
|
|
|
TimelineUpdate::factory()->for($timeline)->create();
|
|
|
|
Mail::assertQueued(TimelineUpdateEmail::class);
|
|
});
|
|
|
|
test('email is not sent for archived timeline updates', function () {
|
|
Mail::fake();
|
|
|
|
$client = User::factory()->create();
|
|
$timeline = Timeline::factory()->for($client)->create(['status' => 'archived']);
|
|
|
|
TimelineUpdate::factory()->for($timeline)->create();
|
|
|
|
Mail::assertNothingQueued();
|
|
});
|
|
|
|
test('email uses arabic template when client prefers arabic', function () {
|
|
$client = User::factory()->create(['preferred_language' => 'ar']);
|
|
$timeline = Timeline::factory()->for($client)->create();
|
|
$update = TimelineUpdate::factory()->for($timeline)->create();
|
|
|
|
$mailable = new TimelineUpdateEmail($update);
|
|
|
|
expect($mailable->locale)->toBe('ar');
|
|
});
|
|
|
|
test('email uses english template when client prefers english', function () {
|
|
$client = User::factory()->create(['preferred_language' => 'en']);
|
|
$timeline = Timeline::factory()->for($client)->create();
|
|
$update = TimelineUpdate::factory()->for($timeline)->create();
|
|
|
|
$mailable = new TimelineUpdateEmail($update);
|
|
|
|
expect($mailable->locale)->toBe('en');
|
|
});
|
|
|
|
test('email defaults to arabic when no language preference', function () {
|
|
$client = User::factory()->create(['preferred_language' => null]);
|
|
$timeline = Timeline::factory()->for($client)->create();
|
|
$update = TimelineUpdate::factory()->for($timeline)->create();
|
|
|
|
$mailable = new TimelineUpdateEmail($update);
|
|
|
|
expect($mailable->locale)->toBe('ar');
|
|
});
|
|
|
|
test('email contains case name in subject', function () {
|
|
$client = User::factory()->create(['preferred_language' => 'en']);
|
|
$timeline = Timeline::factory()->for($client)->create(['case_name' => 'Smith vs Jones']);
|
|
$update = TimelineUpdate::factory()->for($timeline)->create();
|
|
|
|
$mailable = new TimelineUpdateEmail($update);
|
|
|
|
expect($mailable->envelope()->subject)->toContain('Smith vs Jones');
|
|
});
|
|
|
|
test('email contains update content', function () {
|
|
$client = User::factory()->create(['preferred_language' => 'en']);
|
|
$timeline = Timeline::factory()->for($client)->create();
|
|
$update = TimelineUpdate::factory()->for($timeline)->create([
|
|
'update_text' => 'Court date scheduled for next month.',
|
|
]);
|
|
|
|
$mailable = new TimelineUpdateEmail($update);
|
|
|
|
$mailable->assertSeeInHtml('Court date scheduled for next month.');
|
|
});
|
|
|
|
test('email contains view timeline link', function () {
|
|
$client = User::factory()->create(['preferred_language' => 'en']);
|
|
$timeline = Timeline::factory()->for($client)->create();
|
|
$update = TimelineUpdate::factory()->for($timeline)->create();
|
|
|
|
$mailable = new TimelineUpdateEmail($update);
|
|
|
|
$mailable->assertSeeInHtml(route('client.timelines.show', $timeline));
|
|
});
|
|
```
|
|
|
|
## Definition of Done
|
|
- [ ] `TimelineUpdateEmail` mailable created extending `BaseMailable`
|
|
- [ ] Arabic and English templates created with proper formatting
|
|
- [ ] Observer registered and triggers on `TimelineUpdate` creation
|
|
- [ ] Email only sent for active timelines (not archived)
|
|
- [ ] Email queued (not sent synchronously)
|
|
- [ ] Subject includes case name in appropriate language
|
|
- [ ] Email body includes case reference (if exists), update content, and date
|
|
- [ ] View Timeline button links to correct client dashboard route
|
|
- [ ] All tests pass
|
|
- [ ] Code formatted with Pint
|
|
|
|
## Estimation
|
|
**Complexity:** Low | **Effort:** 2-3 hours
|