# Story 3.4: Booking Request Submission

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

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

## Story Context

### Existing System Integration
- **Integrates with:** `consultations` table, availability calendar (Story 3.3), notifications system
- **Technology:** Livewire Volt (class-based), Laravel form validation, DB transactions
- **Follows pattern:** Multi-step form submission with confirmation
- **Touch points:** Client dashboard, admin notifications, audit log
- **Component location:** `resources/views/livewire/booking/request.blade.php`

## Acceptance Criteria

### Booking Form
- [ ] Client must be logged in
- [ ] Select date from availability calendar
- [ ] Select available time slot
- [ ] Problem summary field (required, textarea)
- [ ] Confirmation before submission

### Validation & Constraints
- [ ] Validate: no more than 1 booking per day for this client
- [ ] Validate: selected slot is still available
- [ ] Validate: problem summary is not empty
- [ ] Show clear error messages for violations

### Submission Flow
- [ ] Booking enters "pending" status
- [ ] Client sees "Pending Review" confirmation
- [ ] Admin receives email notification
- [ ] Client receives submission confirmation email
- [ ] Redirect to consultations list after submission

### UI/UX
- [ ] Clear step-by-step flow
- [ ] Loading state during submission
- [ ] Success message with next steps
- [ ] Bilingual labels and messages

### Quality Requirements
- [ ] Prevent double-booking (race condition)
- [ ] Audit log entry for booking creation
- [ ] Tests for submission flow
- [ ] Tests for validation rules

## Technical Notes

### Database Record
```php
// consultations table fields on creation
$consultation = Consultation::create([
    'user_id' => auth()->id(),
    'scheduled_date' => $selectedDate,
    'scheduled_time' => $selectedTime,
    'duration' => 45, // default
    'status' => 'pending',
    'type' => null, // admin sets this later
    'payment_amount' => null,
    'payment_status' => 'not_applicable',
    'problem_summary' => $problemSummary,
]);
```

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

use App\Models\Consultation;
use App\Services\AvailabilityService;
use App\Notifications\BookingSubmittedClient;
use App\Notifications\NewBookingAdmin;
use Livewire\Volt\Component;
use Carbon\Carbon;

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::where('user_id', auth()->id())
            ->where('scheduled_date', $this->selectedDate)
            ->whereIn('status', ['pending', '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
    {
        // Double-check availability with lock
        DB::transaction(function () {
            // Check slot one more time with lock
            $exists = Consultation::where('scheduled_date', $this->selectedDate)
                ->where('scheduled_time', $this->selectedTime)
                ->whereIn('status', ['pending', 'approved'])
                ->lockForUpdate()
                ->exists();

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

            // Check 1-per-day again
            $userBooking = Consultation::where('user_id', auth()->id())
                ->where('scheduled_date', $this->selectedDate)
                ->whereIn('status', ['pending', 'approved'])
                ->lockForUpdate()
                ->exists();

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

            // Create booking
            $consultation = Consultation::create([
                'user_id' => auth()->id(),
                'scheduled_date' => $this->selectedDate,
                'scheduled_time' => $this->selectedTime,
                'duration' => 45,
                'status' => 'pending',
                'problem_summary' => $this->problemSummary,
            ]);

            // Send notifications
            auth()->user()->notify(new BookingSubmittedClient($consultation));

            // Notify admin
            $admin = User::where('user_type', 'admin')->first();
            $admin?->notify(new NewBookingAdmin($consultation));

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

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

### 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:booking.availability-calendar
                @slot-selected="selectSlot($event.detail.date, $event.detail.time)"
            />
        </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>
            @endif
        </div>
    @endif
</div>
```

### 1-Per-Day Validation Rule
```php
// app/Rules/OneBookingPerDay.php
use Illuminate\Contracts\Validation\ValidationRule;

class OneBookingPerDay implements ValidationRule
{
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        $exists = Consultation::where('user_id', auth()->id())
            ->where('scheduled_date', $value)
            ->whereIn('status', ['pending', 'approved'])
            ->exists();

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

### Advanced Pattern: Race Condition Prevention

The `submit()` method uses `DB::transaction()` with `lockForUpdate()` to prevent race conditions. This is an **advanced pattern** required because:
- Multiple clients could attempt to book the same slot simultaneously
- Without locking, both requests could pass validation and create duplicate bookings

The `lockForUpdate()` acquires a row-level lock, ensuring only one transaction completes while others wait and then fail validation.

## Files to Create

| File | Purpose |
|------|---------|
| `resources/views/livewire/booking/request.blade.php` | Main Volt component for booking submission |
| `app/Rules/OneBookingPerDay.php` | Custom validation rule for 1-per-day limit |
| `app/Notifications/BookingSubmittedClient.php` | Email notification to client on submission |
| `app/Notifications/NewBookingAdmin.php` | Email notification to admin for new booking |

### Notification Classes

Create notifications using artisan:
```bash
php artisan make:notification BookingSubmittedClient
php artisan make:notification NewBookingAdmin
```

Both notifications should:
- Accept `Consultation $consultation` in constructor
- Implement `toMail()` for email delivery
- Use bilingual subjects based on user's `preferred_language`

## Translation Keys Required

Add to `lang/en/booking.php` and `lang/ar/booking.php`:

```php
// lang/en/booking.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.',
```

## Testing Requirements

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

### Required Test Scenarios

```php
// Happy path
test('authenticated client can submit booking request')
test('booking is created with pending status')
test('client receives confirmation notification')
test('admin receives new booking notification')

// Validation
test('guest cannot access booking form')
test('problem summary is required')
test('problem summary must be at least 20 characters')
test('selected date must be today or future')

// Business rules
test('client cannot book more than once per day')
test('client cannot book unavailable slot')
test('booking fails if slot taken during submission', function () {
    // Test race condition prevention
    // Create booking for same slot in parallel/before submission completes
})

// UI flow
test('confirmation step displays before final submission')
test('user can go back from confirmation to edit')
test('success message shown after submission')
test('redirects to consultations list after submission')
```

## Definition of Done

- [ ] Can select date from calendar
- [ ] Can select time slot
- [ ] Problem summary required
- [ ] 1-per-day limit enforced
- [ ] Race condition prevented
- [ ] Confirmation step before submission
- [ ] Booking created with "pending" status
- [ ] Client notification sent
- [ ] Admin notification sent
- [ ] Bilingual support complete
- [ ] Tests for submission flow
- [ ] Code formatted with Pint

## Dependencies

- **Story 3.3:** Availability calendar (`docs/stories/story-3.3-availability-calendar-display.md`)
  - Provides `AvailabilityService` for slot availability checking
  - Provides `booking.availability-calendar` Livewire component
- **Epic 2:** User authentication (`docs/epics/epic-2-user-management.md`)
  - Client must be logged in to submit bookings
- **Epic 8:** Email notifications (partial)
  - Notification infrastructure for sending emails

## Risk Assessment

- **Primary Risk:** Double-booking from concurrent submissions
- **Mitigation:** Database transaction with row locking
- **Rollback:** Return to calendar with error message

## Estimation

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