# Story 2.4: Account Lifecycle Management

## Epic Reference
**Epic 2:** User Management System

## User Story
As an **admin**,
I want **to deactivate, reactivate, and permanently delete client accounts**,
So that **I can manage the full lifecycle of client relationships**.

## Story Context

### Existing System Integration
- **Integrates with:** Users table, consultations, timelines, notifications, sessions
- **Technology:** Livewire Volt (class-based), Flux UI modals, Pest tests
- **Follows pattern:** Same admin action patterns as Story 2.1/2.2, soft deactivation via status field, hard deletion with cascade
- **Touch points:** User model, AdminLog model, FortifyServiceProvider (authentication check)
- **PRD Reference:** Section 5.3 (User Management System - Account Lifecycle)
- **Key Files to Create/Modify:**
  - `resources/views/livewire/admin/users/partials/` - Lifecycle action components
  - `app/Notifications/` - Reactivation and password reset notifications
  - `app/Providers/FortifyServiceProvider.php` - Add deactivation check to authenticateUsing
  - `app/Models/User.php` - Add lifecycle methods and deleting event
  - `tests/Feature/Admin/AccountLifecycleTest.php` - Feature tests

## Acceptance Criteria

### Deactivate Account
- [ ] "Deactivate" button on user profile and list
- [ ] Confirmation dialog explaining consequences
- [ ] Effects of deactivation:
  - User cannot log in
  - All data retained (consultations, timelines)
  - Status changes to 'deactivated'
  - Can be reactivated by admin
- [ ] Visual indicator in user list (grayed out, badge)
- [ ] Audit log entry created

### Reactivate Account
- [ ] "Reactivate" button on deactivated profiles
- [ ] Confirmation dialog
- [ ] Effects of reactivation:
  - Restore login ability
  - Status changes to 'active'
  - All data intact
- [ ] Email notification sent to user
- [ ] Audit log entry created

### Delete Account (Permanent)
- [ ] "Delete" button (with danger styling)
- [ ] Confirmation dialog with strong warning:
  - "This action cannot be undone"
  - Lists what will be deleted
  - Requires typing confirmation (e.g., user email)
- [ ] Effects of deletion:
  - User record permanently removed
  - Cascades to: consultations, timelines, timeline_updates, notifications
  - Cannot be recovered
- [ ] Audit log entry preserved (for audit trail)
- [ ] No email sent (user no longer exists)

### Password Reset
- [ ] "Reset Password" action on user profile
- [ ] Options:
  - Generate random password
  - Set specific password manually
- [ ] Email new credentials to client
- [ ] Force password change on next login (optional)
- [ ] Audit log entry created

### Quality Requirements
- [ ] All actions logged in admin_logs table
- [ ] Bilingual confirmation messages
- [ ] Clear visual states for account status
- [ ] Tests for all lifecycle operations

## Technical Notes

### Files to Create
```
resources/views/livewire/admin/users/
├── partials/
│   ├── lifecycle-actions.blade.php   # Deactivate/Reactivate/Delete action buttons
│   └── password-reset-modal.blade.php # Password reset modal component
app/Notifications/
├── AccountReactivatedNotification.php
└── PasswordResetByAdminNotification.php
tests/Feature/Admin/
└── AccountLifecycleTest.php
```

### User Status Management
```php
// User model
public function isActive(): bool
{
    return $this->status === 'active';
}

public function isDeactivated(): bool
{
    return $this->status === 'deactivated';
}

public function deactivate(): void
{
    $this->update(['status' => 'deactivated']);
}

public function reactivate(): void
{
    $this->update(['status' => 'active']);
}
```

### Authentication Check
```php
// In FortifyServiceProvider or custom auth
Fortify::authenticateUsing(function (Request $request) {
    $user = User::where('email', $request->email)->first();

    if ($user &&
        $user->isActive() &&
        Hash::check($request->password, $user->password)) {
        return $user;
    }

    // Optionally: different error for deactivated
    return null;
});
```

### Cascade Deletion
```php
// In User model
protected static function booted(): void
{
    static::deleting(function (User $user) {
        // Log before deletion
        AdminLog::create([
            'admin_id' => auth()->id(),
            'action_type' => 'delete',
            'target_type' => 'user',
            'target_id' => $user->id,
            'old_values' => $user->toArray(),
            'ip_address' => request()->ip(),
        ]);

        // Cascade delete (or use foreign key CASCADE)
        $user->consultations()->delete();
        $user->timelines->each(function ($timeline) {
            $timeline->updates()->delete();
            $timeline->delete();
        });
        $user->notifications()->delete();
    });
}
```

### Volt Component for Lifecycle Actions
```php
<?php

use App\Models\User;
use Livewire\Volt\Component;
use Illuminate\Support\Str;
use Illuminate\Support\Facades\Hash;

new class extends Component {
    public User $user;
    public string $deleteConfirmation = '';
    public bool $showDeleteModal = false;

    public function deactivate(): void
    {
        $this->user->deactivate();

        AdminLog::create([
            'admin_id' => auth()->id(),
            'action_type' => 'deactivate',
            'target_type' => 'user',
            'target_id' => $this->user->id,
            'old_values' => ['status' => 'active'],
            'new_values' => ['status' => 'deactivated'],
            'ip_address' => request()->ip(),
        ]);

        session()->flash('success', __('messages.user_deactivated'));
    }

    public function reactivate(): void
    {
        $this->user->reactivate();

        // Send notification
        $this->user->notify(new AccountReactivatedNotification());

        // Log action
        AdminLog::create([...]);

        session()->flash('success', __('messages.user_reactivated'));
    }

    public function delete(): void
    {
        if ($this->deleteConfirmation !== $this->user->email) {
            $this->addError('deleteConfirmation', __('validation.email_confirmation'));
            return;
        }

        $this->user->delete();

        session()->flash('success', __('messages.user_deleted'));
        $this->redirect(route('admin.users.index'));
    }

    public function resetPassword(): void
    {
        $newPassword = Str::random(12);

        $this->user->update([
            'password' => Hash::make($newPassword),
        ]);

        // Send new credentials email
        $this->user->notify(new PasswordResetByAdminNotification($newPassword));

        // Log action
        AdminLog::create([
            'admin_id' => auth()->id(),
            'action_type' => 'password_reset',
            'target_type' => 'user',
            'target_id' => $this->user->id,
            'ip_address' => request()->ip(),
        ]);

        session()->flash('success', __('messages.password_reset_sent'));
    }
};
```

### Delete Confirmation Modal
```blade
<flux:modal wire:model="showDeleteModal">
    <flux:heading>{{ __('messages.confirm_delete') }}</flux:heading>

    <flux:callout variant="danger">
        {{ __('messages.delete_warning') }}
    </flux:callout>

    <p>{{ __('messages.will_be_deleted') }}</p>
    <ul class="list-disc ps-5 mt-2">
        <li>{{ __('messages.all_consultations') }}</li>
        <li>{{ __('messages.all_timelines') }}</li>
        <li>{{ __('messages.all_notifications') }}</li>
    </ul>

    <flux:field>
        <flux:label>{{ __('messages.type_email_to_confirm', ['email' => $user->email]) }}</flux:label>
        <flux:input wire:model="deleteConfirmation" />
        <flux:error name="deleteConfirmation" />
    </flux:field>

    <div class="flex gap-3 mt-4">
        <flux:button wire:click="$set('showDeleteModal', false)">
            {{ __('messages.cancel') }}
        </flux:button>
        <flux:button variant="danger" wire:click="delete">
            {{ __('messages.delete_permanently') }}
        </flux:button>
    </div>
</flux:modal>
```

### Edge Cases & Error Handling
- **Active sessions on deactivation:** Invalidate all user sessions when deactivated (use `DB::table('sessions')->where('user_id', $user->id)->delete()`)
- **Deactivated user login attempt:** Show bilingual message: "Your account has been deactivated. Please contact the administrator."
- **Delete with related data:** Cascade deletion handles consultations/timelines automatically via model `deleting` event
- **Delete confirmation mismatch:** Display validation error, do not proceed with deletion
- **Password reset email failure:** Queue the email, log failure, show success message (email queued)
- **Reactivation email failure:** Queue the email, log failure, still complete reactivation

### Session Invalidation on Deactivation
```php
// Add to deactivate() method in Volt component
use Illuminate\Support\Facades\DB;

public function deactivate(): void
{
    $this->user->deactivate();

    // Invalidate all active sessions for this user
    DB::table('sessions')
        ->where('user_id', $this->user->id)
        ->delete();

    // Log action...
}
```

## Testing Requirements

### Test File Location
`tests/Feature/Admin/AccountLifecycleTest.php`

### Test Scenarios

#### Deactivation Tests
- [ ] Admin can deactivate an active user
- [ ] Deactivated user cannot login (returns null from authenticateUsing)
- [ ] Deactivated user shows visual indicator in user list
- [ ] User sessions are invalidated on deactivation
- [ ] AdminLog entry created with old/new status values
- [ ] Deactivation preserves all user data (consultations, timelines intact)

#### Reactivation Tests
- [ ] Admin can reactivate a deactivated user
- [ ] Reactivated user can login successfully
- [ ] Reactivated user status changes to 'active'
- [ ] Email notification queued on reactivation
- [ ] AdminLog entry created for reactivation

#### Permanent Deletion Tests
- [ ] Delete button shows danger styling
- [ ] Delete requires typing user email for confirmation
- [ ] Incorrect email confirmation shows validation error
- [ ] Successful deletion removes user record permanently
- [ ] Cascade deletion removes user's consultations
- [ ] Cascade deletion removes user's timelines and timeline_updates
- [ ] Cascade deletion removes user's notifications
- [ ] AdminLog entry preserved after user deletion (for audit trail)
- [ ] Redirect to users index after successful deletion

#### Password Reset Tests
- [ ] Admin can reset user password with random generation
- [ ] New password meets minimum requirements (8+ characters)
- [ ] Password reset email sent to user with new credentials
- [ ] AdminLog entry created for password reset
- [ ] User can login with new password

#### Authorization Tests
- [ ] Non-admin users cannot access lifecycle actions
- [ ] Admin cannot deactivate their own account
- [ ] Admin cannot delete their own account

#### Bilingual Tests
- [ ] Confirmation dialogs display in Arabic when locale is 'ar'
- [ ] Confirmation dialogs display in English when locale is 'en'
- [ ] Success/error messages respect user's preferred language

### Testing Approach
```php
use App\Models\User;
use App\Models\AdminLog;
use Livewire\Volt\Volt;
use Illuminate\Support\Facades\Notification;
use App\Notifications\AccountReactivatedNotification;

test('admin can deactivate active user', function () {
    $admin = User::factory()->admin()->create();
    $client = User::factory()->individual()->create(['status' => 'active']);

    Volt::actingAs($admin)
        ->test('admin.users.show', ['user' => $client])
        ->call('deactivate')
        ->assertHasNoErrors();

    expect($client->fresh()->status)->toBe('deactivated');
    expect(AdminLog::where('action_type', 'deactivate')->exists())->toBeTrue();
});

test('deactivated user cannot login', function () {
    $user = User::factory()->create(['status' => 'deactivated']);

    $this->post('/login', [
        'email' => $user->email,
        'password' => 'password',
    ])->assertSessionHasErrors();

    $this->assertGuest();
});

test('delete requires email confirmation', function () {
    $admin = User::factory()->admin()->create();
    $client = User::factory()->individual()->create();

    Volt::actingAs($admin)
        ->test('admin.users.show', ['user' => $client])
        ->set('deleteConfirmation', 'wrong@email.com')
        ->call('delete')
        ->assertHasErrors(['deleteConfirmation']);

    expect(User::find($client->id))->not->toBeNull();
});

test('reactivation sends email notification', function () {
    Notification::fake();

    $admin = User::factory()->admin()->create();
    $client = User::factory()->individual()->create(['status' => 'deactivated']);

    Volt::actingAs($admin)
        ->test('admin.users.show', ['user' => $client])
        ->call('reactivate')
        ->assertHasNoErrors();

    Notification::assertSentTo($client, AccountReactivatedNotification::class);
});
```

## Definition of Done

- [ ] Deactivate prevents login but preserves data
- [ ] Reactivate restores login ability
- [ ] Delete permanently removes all user data
- [ ] Delete requires email confirmation
- [ ] Password reset sends new credentials
- [ ] Visual indicators show account status
- [ ] Audit logging for all actions
- [ ] Email notifications sent appropriately
- [ ] Bilingual support complete
- [ ] Tests for all lifecycle states
- [ ] Code formatted with Pint

## Dependencies

### Required Before Implementation
- **Story 1.1:** Database schema must include:
  - `users.status` column (enum: 'active', 'deactivated')
  - `users.user_type` column (enum: 'individual', 'company', 'admin')
  - `admin_logs` table with columns: `admin_id`, `action_type`, `target_type`, `target_id`, `old_values`, `new_values`, `ip_address`
- **Story 1.2:** Authentication system with admin role, AdminLog model
- **Story 2.1:** Individual client management (establishes CRUD patterns)
- **Story 2.2:** Company client management

### Soft Dependencies (Can Be Empty/Stubbed)
- **Epic 3:** Consultations table (cascade delete - can be empty if not yet implemented)
- **Epic 4:** Timelines table (cascade delete - can be empty if not yet implemented)

### Notification Classes (Created in This Story)
This story creates the following notification classes:
- `App\Notifications\AccountReactivatedNotification` - Sent when account is reactivated
- `App\Notifications\PasswordResetByAdminNotification` - Sent with new credentials after admin password reset

> **Note:** These are simple notifications. Full email infrastructure (templates, queuing) is handled in Epic 8. These notifications will use Laravel's default mail driver.

## Risk Assessment

- **Primary Risk:** Accidental permanent deletion
- **Mitigation:** Strong confirmation dialog, email confirmation, audit log
- **Rollback:** Not possible for delete - warn user clearly

## Estimation

**Complexity:** Medium
**Estimated Effort:** 4-5 hours