# Story 3.4: Booking Request Submission

## Status
**Draft**

## Epic Reference
**Epic 3:** Booking & Consultation System

## Story
**As a** client,
**I want** to submit a consultation booking request,
**so that** I can schedule a meeting with the lawyer.

## Acceptance Criteria

### Booking Form (AC1-5)
1. Client must be logged in
2. Select date from availability calendar
3. Select available time slot
4. Problem summary field (required, textarea, min 20 characters)
5. Confirmation before submission

### Validation & Constraints (AC6-9)
6. Validate: no more than 1 booking per day for this client
7. Validate: selected slot is still available
8. Validate: problem summary is not empty
9. Show clear error messages for violations

### Submission Flow (AC10-14)
10. Booking enters "pending" status
11. Client sees "Pending Review" confirmation
12. Admin receives email notification
13. Client receives submission confirmation email
14. Redirect to consultations list after submission

### UI/UX (AC15-18)
15. Clear step-by-step flow
16. Loading state during submission
17. Success message with next steps
18. Bilingual labels and messages

### Quality Requirements (AC19-22)
19. Prevent double-booking (race condition)
20. Audit log entry for booking creation
21. Tests for submission flow
22. Tests for validation rules

## Tasks / Subtasks

- [ ] **Task 1: Create Volt component file** (AC: 1-5, 15-18)
  - [ ] Create `resources/views/livewire/client/consultations/book.blade.php`
  - [ ] Implement class-based Volt component with state properties
  - [ ] Add `selectSlot()`, `clearSelection()`, `showConfirm()`, `submit()` methods
  - [ ] Add validation rules for form fields

- [ ] **Task 2: Implement calendar integration** (AC: 2, 3)
  - [ ] Embed `availability-calendar` component
  - [ ] Handle slot selection via `$parent.selectSlot()` pattern
  - [ ] Display selected date/time with change option

- [ ] **Task 3: Implement problem summary form** (AC: 4, 8)
  - [ ] Add textarea with Flux UI components
  - [ ] Validate minimum 20 characters, maximum 2000 characters
  - [ ] Show validation errors with `<flux:error>`

- [ ] **Task 4: Implement 1-per-day validation** (AC: 6, 9)
  - [ ] Create `app/Rules/OneBookingPerDay.php` validation rule
  - [ ] Check against `booking_date` with pending/approved status
  - [ ] Display clear error message when violated

- [ ] **Task 5: Implement slot availability check** (AC: 7, 9)
  - [ ] Use `AvailabilityService::getAvailableSlots()` before confirmation
  - [ ] Display error if slot no longer available
  - [ ] Refresh calendar on error

- [ ] **Task 6: Implement confirmation step** (AC: 5, 15)
  - [ ] Show booking summary before final submission
  - [ ] Display date, time, duration (45 min), problem summary
  - [ ] Add back button to edit

- [ ] **Task 7: Implement race condition prevention** (AC: 19)
  - [ ] Use `DB::transaction()` with `lockForUpdate()` on slot check
  - [ ] Re-validate 1-per-day rule inside transaction
  - [ ] Throw exception if slot taken, catch and show error

- [ ] **Task 8: Create booking record** (AC: 10)
  - [ ] Create Consultation with status `ConsultationStatus::Pending`
  - [ ] Set `booking_date`, `booking_time`, `problem_summary`, `user_id`
  - [ ] Leave `consultation_type`, `payment_amount` as null (admin sets later)

- [ ] **Task 9: Create email notifications** (AC: 12, 13)
  - [ ] Create `app/Mail/BookingSubmittedMail.php` for client
  - [ ] Create `app/Mail/NewBookingRequestMail.php` for admin
  - [ ] Queue emails via `SendBookingNotification` job
  - [ ] Support bilingual content based on user's `preferred_language`

- [ ] **Task 10: Implement audit logging** (AC: 20)
  - [ ] Create AdminLog entry on booking creation
  - [ ] Set `admin_id` to null (client action)
  - [ ] Set `action` to 'create', `target_type` to 'consultation'

- [ ] **Task 11: Implement success flow** (AC: 11, 14, 17)
  - [ ] Flash success message to session
  - [ ] Redirect to `route('client.consultations.index')`

- [ ] **Task 12: Add route** (AC: 1)
  - [ ] Add route in `routes/web.php` under client middleware group
  - [ ] Route: `GET /client/consultations/book` → Volt component

- [ ] **Task 13: Add translation keys** (AC: 18)
  - [ ] Add keys to `lang/en/booking.php`
  - [ ] Add keys to `lang/ar/booking.php`

- [ ] **Task 14: Write tests** (AC: 21, 22)
  - [ ] Create `tests/Feature/Client/BookingSubmissionTest.php`
  - [ ] Test happy path submission
  - [ ] Test validation rules
  - [ ] Test 1-per-day constraint
  - [ ] Test race condition handling
  - [ ] Test notifications sent

- [ ] **Task 15: Run Pint and verify**
  - [ ] Run `vendor/bin/pint --dirty`
  - [ ] Verify all tests pass

## Dev Notes

### Relevant Source Tree
```
app/
├── Enums/
│   ├── ConsultationStatus.php    # Pending, Approved, Completed, Cancelled, NoShow
│   └── PaymentStatus.php         # Pending, Received, NotApplicable
├── Mail/
│   ├── BookingSubmittedMail.php  # TO CREATE
│   └── NewBookingRequestMail.php # TO CREATE
├── Models/
│   ├── Consultation.php          # EXISTS - booking_date, booking_time columns
│   ├── AdminLog.php              # EXISTS - action column (not action_type)
│   └── User.php
├── Rules/
│   └── OneBookingPerDay.php      # TO CREATE
├── Services/
│   └── AvailabilityService.php   # EXISTS - getAvailableSlots() method
└── Jobs/
    └── SendBookingNotification.php # TO CREATE (or use Mail directly)

resources/views/livewire/
├── availability-calendar.blade.php  # EXISTS - calendar component
└── client/
    └── consultations/
        └── book.blade.php           # TO CREATE - main booking form

lang/
├── en/booking.php                   # EXISTS - needs new keys added
└── ar/booking.php                   # EXISTS - needs new keys added
```

### Consultation Model Fields (Actual)
```php
// app/Models/Consultation.php - $fillable
'user_id',
'booking_date',      // NOT scheduled_date
'booking_time',      // NOT scheduled_time
'problem_summary',
'consultation_type', // null initially, admin sets later
'payment_amount',    // null initially
'payment_status',    // PaymentStatus::NotApplicable initially
'status',            // ConsultationStatus::Pending
'admin_notes',
```

**Important:** The model does NOT have a `duration` field. Duration (45 min) is a business constant, not stored per-consultation.

### AdminLog Model Fields (Actual)
```php
// app/Models/AdminLog.php - $fillable
'admin_id',      // null for client actions
'action',        // NOT action_type - values: 'create', 'update', 'delete'
'target_type',   // 'consultation', 'user', 'working_hours', etc.
'target_id',
'old_values',
'new_values',
'ip_address',
'created_at',
```

### Database Record Creation
```php
use App\Enums\ConsultationStatus;
use App\Enums\PaymentStatus;

$consultation = Consultation::create([
    'user_id' => auth()->id(),
    'booking_date' => $this->selectedDate,
    'booking_time' => $this->selectedTime,
    'problem_summary' => $this->problemSummary,
    'status' => ConsultationStatus::Pending,
    'payment_status' => PaymentStatus::NotApplicable,
    // consultation_type and payment_amount left null - admin sets later
]);
```

### Volt Component Structure
```php
<?php

use App\Enums\ConsultationStatus;
use App\Enums\PaymentStatus;
use App\Models\AdminLog;
use App\Models\Consultation;
use App\Models\User;
use App\Services\AvailabilityService;
use Carbon\Carbon;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Mail;
use Livewire\Volt\Component;

new class extends Component {
    public ?string $selectedDate = null;
    public ?string $selectedTime = null;
    public string $problemSummary = '';
    public bool $showConfirmation = false;

    public function selectSlot(string $date, string $time): void
    {
        $this->selectedDate = $date;
        $this->selectedTime = $time;
    }

    public function clearSelection(): void
    {
        $this->selectedDate = null;
        $this->selectedTime = null;
    }

    public function showConfirm(): void
    {
        $this->validate([
            'selectedDate' => ['required', 'date', 'after_or_equal:today'],
            'selectedTime' => ['required'],
            'problemSummary' => ['required', 'string', 'min:20', 'max:2000'],
        ]);

        // Check 1-per-day limit
        $existingBooking = Consultation::query()
            ->where('user_id', auth()->id())
            ->whereDate('booking_date', $this->selectedDate)
            ->whereIn('status', [ConsultationStatus::Pending, ConsultationStatus::Approved])
            ->exists();

        if ($existingBooking) {
            $this->addError('selectedDate', __('booking.already_booked_this_day'));
            return;
        }

        // Verify slot still available
        $service = app(AvailabilityService::class);
        $availableSlots = $service->getAvailableSlots(Carbon::parse($this->selectedDate));

        if (!in_array($this->selectedTime, $availableSlots)) {
            $this->addError('selectedTime', __('booking.slot_no_longer_available'));
            return;
        }

        $this->showConfirmation = true;
    }

    public function submit(): void
    {
        try {
            DB::transaction(function () {
                // Check slot one more time with lock
                $slotTaken = Consultation::query()
                    ->whereDate('booking_date', $this->selectedDate)
                    ->where('booking_time', $this->selectedTime)
                    ->whereIn('status', [ConsultationStatus::Pending, ConsultationStatus::Approved])
                    ->lockForUpdate()
                    ->exists();

                if ($slotTaken) {
                    throw new \Exception(__('booking.slot_taken'));
                }

                // Check 1-per-day again with lock
                $userHasBooking = Consultation::query()
                    ->where('user_id', auth()->id())
                    ->whereDate('booking_date', $this->selectedDate)
                    ->whereIn('status', [ConsultationStatus::Pending, ConsultationStatus::Approved])
                    ->lockForUpdate()
                    ->exists();

                if ($userHasBooking) {
                    throw new \Exception(__('booking.already_booked_this_day'));
                }

                // Create booking
                $consultation = Consultation::create([
                    'user_id' => auth()->id(),
                    'booking_date' => $this->selectedDate,
                    'booking_time' => $this->selectedTime,
                    'problem_summary' => $this->problemSummary,
                    'status' => ConsultationStatus::Pending,
                    'payment_status' => PaymentStatus::NotApplicable,
                ]);

                // Send email to client
                Mail::to(auth()->user())->queue(
                    new \App\Mail\BookingSubmittedMail($consultation)
                );

                // Send email to admin
                $admin = User::query()->where('user_type', 'admin')->first();
                if ($admin) {
                    Mail::to($admin)->queue(
                        new \App\Mail\NewBookingRequestMail($consultation)
                    );
                }

                // Log action
                AdminLog::create([
                    'admin_id' => null, // Client action
                    'action' => 'create',
                    'target_type' => 'consultation',
                    'target_id' => $consultation->id,
                    'new_values' => $consultation->toArray(),
                    'ip_address' => request()->ip(),
                    'created_at' => now(),
                ]);
            });

            session()->flash('success', __('booking.submitted_successfully'));
            $this->redirect(route('client.consultations.index'));

        } catch (\Exception $e) {
            $this->addError('selectedTime', $e->getMessage());
            $this->showConfirmation = false;
        }
    }
}; ?>
```

### Blade Template
```blade
<div class="max-w-4xl mx-auto">
    <flux:heading>{{ __('booking.request_consultation') }}</flux:heading>

    @if(!$selectedDate || !$selectedTime)
        <!-- Step 1: Calendar Selection -->
        <div class="mt-6">
            <p class="mb-4">{{ __('booking.select_date_time') }}</p>
            <livewire:availability-calendar />
        </div>
    @else
        <!-- Step 2: Problem Summary -->
        <div class="mt-6">
            <!-- Selected Time Display -->
            <div class="bg-gold/10 p-4 rounded-lg mb-6">
                <div class="flex justify-between items-center">
                    <div>
                        <p class="font-semibold">{{ __('booking.selected_time') }}</p>
                        <p>{{ \Carbon\Carbon::parse($selectedDate)->translatedFormat('l, d M Y') }}</p>
                        <p>{{ \Carbon\Carbon::parse($selectedTime)->format('g:i A') }}</p>
                    </div>
                    <flux:button size="sm" wire:click="clearSelection">
                        {{ __('common.change') }}
                    </flux:button>
                </div>
            </div>

            @if(!$showConfirmation)
                <!-- Problem Summary Form -->
                <flux:field>
                    <flux:label>{{ __('booking.problem_summary') }} *</flux:label>
                    <flux:textarea
                        wire:model="problemSummary"
                        rows="6"
                        placeholder="{{ __('booking.problem_summary_placeholder') }}"
                    />
                    <flux:description>
                        {{ __('booking.problem_summary_help') }}
                    </flux:description>
                    <flux:error name="problemSummary" />
                </flux:field>

                <flux:button
                    wire:click="showConfirm"
                    class="mt-4"
                    wire:loading.attr="disabled"
                >
                    <span wire:loading.remove>{{ __('booking.continue') }}</span>
                    <span wire:loading>{{ __('common.loading') }}</span>
                </flux:button>
            @else
                <!-- Confirmation Step -->
                <flux:callout>
                    <flux:heading size="sm">{{ __('booking.confirm_booking') }}</flux:heading>
                    <p>{{ __('booking.confirm_message') }}</p>

                    <div class="mt-4 space-y-2">
                        <p><strong>{{ __('booking.date') }}:</strong>
                            {{ \Carbon\Carbon::parse($selectedDate)->translatedFormat('l, d M Y') }}</p>
                        <p><strong>{{ __('booking.time') }}:</strong>
                            {{ \Carbon\Carbon::parse($selectedTime)->format('g:i A') }}</p>
                        <p><strong>{{ __('booking.duration') }}:</strong> 45 {{ __('common.minutes') }}</p>
                    </div>

                    <div class="mt-4">
                        <p><strong>{{ __('booking.problem_summary') }}:</strong></p>
                        <p class="mt-1 text-sm">{{ $problemSummary }}</p>
                    </div>
                </flux:callout>

                <div class="flex gap-3 mt-4">
                    <flux:button wire:click="$set('showConfirmation', false)">
                        {{ __('common.back') }}
                    </flux:button>
                    <flux:button
                        wire:click="submit"
                        variant="primary"
                        wire:loading.attr="disabled"
                    >
                        <span wire:loading.remove>{{ __('booking.submit_request') }}</span>
                        <span wire:loading>{{ __('common.submitting') }}</span>
                    </flux:button>
                </div>

                @error('selectedTime')
                    <flux:callout variant="danger" class="mt-4">
                        {{ $message }}
                    </flux:callout>
                @enderror
            @endif
        </div>
    @endif
</div>
```

### Calendar Integration Note
The `availability-calendar` component (from Story 3.3) uses the pattern `$parent.selectSlot()` to communicate slot selection back to the parent component. The parent booking component needs to have the `selectSlot(string $date, string $time)` method to receive this.

### 1-Per-Day Validation Rule
```php
<?php
// app/Rules/OneBookingPerDay.php

namespace App\Rules;

use App\Enums\ConsultationStatus;
use App\Models\Consultation;
use Closure;
use Illuminate\Contracts\Validation\ValidationRule;

class OneBookingPerDay implements ValidationRule
{
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        $exists = Consultation::query()
            ->where('user_id', auth()->id())
            ->whereDate('booking_date', $value)
            ->whereIn('status', [ConsultationStatus::Pending, ConsultationStatus::Approved])
            ->exists();

        if ($exists) {
            $fail(__('booking.already_booked_this_day'));
        }
    }
}
```

### Testing

#### Test File Location
`tests/Feature/Client/BookingSubmissionTest.php`

#### Required Test Scenarios
```php
<?php

use App\Enums\ConsultationStatus;
use App\Models\Consultation;
use App\Models\User;
use App\Models\WorkingHour;
use Livewire\Volt\Volt;

beforeEach(function () {
    // Setup working hours for Monday
    WorkingHour::factory()->create([
        'day_of_week' => 1,
        'start_time' => '09:00',
        'end_time' => '17:00',
        'is_active' => true,
    ]);
});

// Happy path
test('authenticated client can submit booking request', function () {
    $client = User::factory()->individual()->create();
    $monday = now()->next('Monday')->format('Y-m-d');

    Volt::test('client.consultations.book')
        ->actingAs($client)
        ->call('selectSlot', $monday, '10:00')
        ->set('problemSummary', 'I need legal advice regarding a contract dispute with my employer.')
        ->call('showConfirm')
        ->assertSet('showConfirmation', true)
        ->call('submit')
        ->assertRedirect(route('client.consultations.index'));

    expect(Consultation::where('user_id', $client->id)->exists())->toBeTrue();
});

test('booking is created with pending status', function () {
    $client = User::factory()->individual()->create();
    $monday = now()->next('Monday')->format('Y-m-d');

    Volt::test('client.consultations.book')
        ->actingAs($client)
        ->call('selectSlot', $monday, '10:00')
        ->set('problemSummary', 'I need legal advice regarding a contract dispute.')
        ->call('showConfirm')
        ->call('submit');

    $consultation = Consultation::where('user_id', $client->id)->first();
    expect($consultation->status)->toBe(ConsultationStatus::Pending);
});

// Validation
test('guest cannot access booking form', function () {
    $this->get(route('client.consultations.book'))
        ->assertRedirect(route('login'));
});

test('problem summary is required', function () {
    $client = User::factory()->individual()->create();
    $monday = now()->next('Monday')->format('Y-m-d');

    Volt::test('client.consultations.book')
        ->actingAs($client)
        ->call('selectSlot', $monday, '10:00')
        ->set('problemSummary', '')
        ->call('showConfirm')
        ->assertHasErrors(['problemSummary' => 'required']);
});

test('problem summary must be at least 20 characters', function () {
    $client = User::factory()->individual()->create();
    $monday = now()->next('Monday')->format('Y-m-d');

    Volt::test('client.consultations.book')
        ->actingAs($client)
        ->call('selectSlot', $monday, '10:00')
        ->set('problemSummary', 'Too short')
        ->call('showConfirm')
        ->assertHasErrors(['problemSummary' => 'min']);
});

// Business rules
test('client cannot book more than once per day', function () {
    $client = User::factory()->individual()->create();
    $monday = now()->next('Monday')->format('Y-m-d');

    // Create existing booking
    Consultation::factory()->pending()->create([
        'user_id' => $client->id,
        'booking_date' => $monday,
        'booking_time' => '09:00',
    ]);

    Volt::test('client.consultations.book')
        ->actingAs($client)
        ->call('selectSlot', $monday, '10:00')
        ->set('problemSummary', 'I need legal advice regarding a contract dispute.')
        ->call('showConfirm')
        ->assertHasErrors(['selectedDate']);
});

test('client cannot book unavailable slot', function () {
    $client = User::factory()->individual()->create();
    $monday = now()->next('Monday')->format('Y-m-d');

    // Create booking that takes the slot
    Consultation::factory()->approved()->create([
        'booking_date' => $monday,
        'booking_time' => '10:00',
    ]);

    Volt::test('client.consultations.book')
        ->actingAs($client)
        ->call('selectSlot', $monday, '10:00')
        ->set('problemSummary', 'I need legal advice regarding a contract dispute.')
        ->call('showConfirm')
        ->assertHasErrors(['selectedTime']);
});

// UI flow
test('confirmation step displays before final submission', function () {
    $client = User::factory()->individual()->create();
    $monday = now()->next('Monday')->format('Y-m-d');

    Volt::test('client.consultations.book')
        ->actingAs($client)
        ->call('selectSlot', $monday, '10:00')
        ->set('problemSummary', 'I need legal advice regarding a contract dispute.')
        ->assertSet('showConfirmation', false)
        ->call('showConfirm')
        ->assertSet('showConfirmation', true);
});

test('user can go back from confirmation to edit', function () {
    $client = User::factory()->individual()->create();
    $monday = now()->next('Monday')->format('Y-m-d');

    Volt::test('client.consultations.book')
        ->actingAs($client)
        ->call('selectSlot', $monday, '10:00')
        ->set('problemSummary', 'I need legal advice regarding a contract dispute.')
        ->call('showConfirm')
        ->assertSet('showConfirmation', true)
        ->set('showConfirmation', false)
        ->assertSet('showConfirmation', false);
});

test('success message shown after submission', function () {
    $client = User::factory()->individual()->create();
    $monday = now()->next('Monday')->format('Y-m-d');

    Volt::test('client.consultations.book')
        ->actingAs($client)
        ->call('selectSlot', $monday, '10:00')
        ->set('problemSummary', 'I need legal advice regarding a contract dispute.')
        ->call('showConfirm')
        ->call('submit')
        ->assertSessionHas('success');
});
```

## Files to Create

| File | Purpose |
|------|---------|
| `resources/views/livewire/client/consultations/book.blade.php` | Main Volt component for booking submission |
| `app/Rules/OneBookingPerDay.php` | Custom validation rule for 1-per-day limit |
| `app/Mail/BookingSubmittedMail.php` | Email to client on submission |
| `app/Mail/NewBookingRequestMail.php` | Email to admin for new booking |
| `tests/Feature/Client/BookingSubmissionTest.php` | Feature tests for booking flow |

### Mail Classes

Create mail classes using artisan:
```bash
php artisan make:mail BookingSubmittedMail
php artisan make:mail NewBookingRequestMail
```

Both mail classes should:
- Accept `Consultation $consultation` in constructor
- Use bilingual subjects based on recipient's `preferred_language`
- Create corresponding email views in `resources/views/emails/`

## Translation Keys Required

Add to `lang/en/booking.php`:
```php
'request_consultation' => 'Request Consultation',
'select_date_time' => 'Select a date and time for your consultation',
'selected_time' => 'Selected Time',
'problem_summary' => 'Problem Summary',
'problem_summary_placeholder' => 'Please describe your legal issue or question in detail...',
'problem_summary_help' => 'Minimum 20 characters. This helps the lawyer prepare for your consultation.',
'continue' => 'Continue',
'confirm_booking' => 'Confirm Your Booking',
'confirm_message' => 'Please review your booking details before submitting.',
'date' => 'Date',
'time' => 'Time',
'duration' => 'Duration',
'submit_request' => 'Submit Request',
'submitted_successfully' => 'Your booking request has been submitted. You will receive an email confirmation shortly.',
'already_booked_this_day' => 'You already have a booking on this day.',
'slot_no_longer_available' => 'This time slot is no longer available. Please select another.',
'slot_taken' => 'This slot was just booked. Please select another time.',
```

Add corresponding Arabic translations to `lang/ar/booking.php`.

## Definition of Done

- [ ] Volt component created at correct path
- [ ] Can select date from calendar
- [ ] Can select time slot
- [ ] Problem summary required (min 20 chars)
- [ ] 1-per-day limit enforced
- [ ] Race condition prevented with DB locking
- [ ] Confirmation step before submission
- [ ] Booking created with "pending" status
- [ ] Client email sent
- [ ] Admin email sent
- [ ] Audit log entry created
- [ ] Bilingual support complete
- [ ] All tests passing
- [ ] Code formatted with Pint

## Dependencies

- **Story 3.3:** Availability calendar (COMPLETED)
  - Provides `AvailabilityService` for slot availability checking
  - Provides `availability-calendar` Livewire component
- **Epic 2:** User authentication (COMPLETED)
  - Client must be logged in to submit bookings
- **Epic 8:** Email notifications (partial - mail classes needed)

## Risk Assessment

| Risk | Impact | Mitigation |
|------|--------|------------|
| Double-booking race condition | High | DB transaction with `lockForUpdate()` |
| Email delivery failure | Medium | Use queue with retries |
| Timezone confusion | Low | Use `whereDate()` for date comparison |

## Estimation

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

---

## Change Log

| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-12-26 | 1.0 | Initial draft | - |
| 2025-12-26 | 1.1 | Fixed column names (booking_date/booking_time), removed hallucinated duration field, fixed AdminLog column, removed invalid cross-story task, added Tasks/Subtasks section, aligned with source tree architecture | QA Validation |