libra/docs/stories/story-8.2-welcome-email.md

# Story 8.2: Welcome Email (Account Created)

## Epic Reference
**Epic 8:** Email Notification System

## Dependencies
**Requires:** Story 8.1 (Email Infrastructure Setup) - base template, queue configuration, SMTP setup

## User Story
As a **new client**,
I want **to receive a welcome email with my login credentials**,
So that **I can access the platform**.

## Acceptance Criteria

### Trigger
- [ ] Sent automatically on user creation by admin
- [ ] Queued for performance (implements `ShouldQueue`)
- [ ] Triggered via model observer on User created event

### Content
- [ ] Personalized greeting (name/company)
- [ ] "Your account has been created" message
- [ ] Login credentials (email, password)
- [ ] Login URL link with button
- [ ] Brief platform introduction
- [ ] Contact info for questions

### Language
- [ ] Email in user's `preferred_language` field
- [ ] Default to Arabic ('ar') if `preferred_language` is null
- [ ] Arabic template
- [ ] English template

### Design
- [ ] Professional branding (inherits from base template in Story 8.1)
- [ ] Call-to-action button: "Login Now" / "تسجيل الدخول"

## Technical Notes

### Prerequisites from Story 8.1
- Base email template with Libra branding (navy #0A1F44, gold #D4AF37)
- Queue configuration for async email delivery
- SMTP configuration via `.env`

### User Model Requirement
The User model requires a `preferred_language` field. If not already present, add:
- Migration: `$table->string('preferred_language', 2)->default('ar');`
- Fillable: Add `'preferred_language'` to `$fillable` array

### Files to Create

**Mailable Class:**
- `app/Mail/WelcomeEmail.php`

**View Templates:**
- `resources/views/emails/welcome/ar.blade.php` (Arabic)
- `resources/views/emails/welcome/en.blade.php` (English)

**Observer:**
- `app/Observers/UserObserver.php` (if not exists)
- Register in `AppServiceProvider` boot method

### Implementation

```php
// app/Mail/WelcomeEmail.php
class WelcomeEmail extends Mailable implements ShouldQueue
{
    use Queueable, SerializesModels;

    public function __construct(
        public User $user,
        public string $password
    ) {}

    public function envelope(): Envelope
    {
        return new Envelope(
            subject: $this->user->preferred_language === 'en'
                ? 'Welcome to Libra Law Firm'
                : 'مرحباً بك في مكتب ليبرا للمحاماة',
        );
    }

    public function content(): Content
    {
        return new Content(
            markdown: 'emails.welcome.' . ($this->user->preferred_language ?? 'ar'),
            with: [
                'loginUrl' => route('login'),
                'password' => $this->password,
            ],
        );
    }
}
```

```php
// app/Observers/UserObserver.php
class UserObserver
{
    public function created(User $user): void
    {
        // Only send if password was set (admin creation scenario)
        // The plain password must be passed from the creation context
    }
}
```

### Trigger Mechanism
The welcome email requires the plain-text password, which is only available at creation time. Options:
1. **Recommended:** Dispatch from the admin user creation action/controller after creating user
2. Alternative: Use a custom event `UserCreatedWithPassword` that carries both user and password

## Edge Cases

- **Missing `preferred_language`:** Default to Arabic ('ar')
- **Email delivery failure:** Handled by queue retry mechanism (Story 8.1)
- **Password in email:** This is intentional for admin-created accounts; password is shown once

## Testing Requirements

### Unit Tests
- [ ] `WelcomeEmail` mailable contains correct subject for Arabic user
- [ ] `WelcomeEmail` mailable contains correct subject for English user
- [ ] `WelcomeEmail` uses correct template based on language
- [ ] Default language is Arabic when `preferred_language` is null

### Feature Tests
- [ ] Email is queued when user is created
- [ ] Arabic template renders without errors
- [ ] English template renders without errors
- [ ] Email contains login URL
- [ ] Email contains user's password
- [ ] Email contains user's name

### Test Example
```php
use App\Mail\WelcomeEmail;
use App\Models\User;
use Illuminate\Support\Facades\Mail;

test('welcome email is sent when user is created', function () {
    Mail::fake();

    $user = User::factory()->create(['preferred_language' => 'ar']);

    Mail::to($user)->send(new WelcomeEmail($user, 'test-password'));

    Mail::assertQueued(WelcomeEmail::class, function ($mail) use ($user) {
        return $mail->user->id === $user->id;
    });
});

test('welcome email uses arabic template by default', function () {
    $user = User::factory()->create(['preferred_language' => null]);
    $mailable = new WelcomeEmail($user, 'password123');

    $mailable->assertSeeInHtml('تسجيل الدخول');
});
```

## Definition of Done
- [ ] `WelcomeEmail` mailable class created
- [ ] Arabic template (`emails/welcome/ar.blade.php`) created
- [ ] English template (`emails/welcome/en.blade.php`) created
- [ ] Email triggered on user creation by admin
- [ ] Email is queued (not sent synchronously)
- [ ] Credentials included in email
- [ ] Login button links to correct URL
- [ ] All tests pass
- [ ] Code formatted with Pint

## Estimation
**Complexity:** Low | **Effort:** 2-3 hours