# Dynamic Service Availability System

## Overview

The Dynamic Service Availability System prevents overbooking within a single booking session by tracking service selections across all participants and dynamically adjusting availability in real-time. This ensures that services with limited capacity cannot be overbooked during the form creation process.

## Problem Statement

### Business Challenge
- Services have limited availability (e.g., "Advanced Ski Course: 5 available")
- Multiple participants in a booking can select the same services
- Without dynamic tracking, services could be overbooked within a single booking session
- Users need immediate feedback when services become unavailable

### Technical Requirements
- Track service selections across all participants in current booking session
- Recalculate remaining availability during HTMX form refresh cycles
- Hide services that have reached capacity limits
- Maintain session-scoped availability (not permanent database changes)
- Support all service types with consistent behavior

## Architecture Overview

### Core Components

#### 1. ServiceAvailabilityCalculator (`src/Service/ServiceAvailabilityCalculator.php`)
**Purpose**: Central service for calculating dynamic availability based on current selections

**Key Methods**:
```php
public function calculateRemainingAvailability(BookingCreateDto $bookingDto, int $currentParticipantIndex): array
public function filterAvailableServices(array $services, BookingCreateDto $bookingDto, int $participantIndex): array
public function isServiceAvailable(int $serviceId, BookingCreateDto $bookingDto, int $participantIndex): bool
```

**Responsibilities**:
- Calculate service usage across all participants (excluding current participant)
- Determine remaining availability per service
- Filter service arrays to only include available services
- Handle all service types consistently

#### 2. Enhanced ParticipantFieldOptionsProvider
**Integration Point**: Field option generation with availability filtering

**Enhanced Methods**:
```php
private function filterServicesByAvailability(array $services, BookingDtoInterface $bookingDto, int $participantIndex): array
```

**Updated Field Providers**:
- Courses (`TOKEN_COURSES`)
- Additional Services (`TOKEN_ADDITIONAL`)  
- Board/Meal Plans (`TOKEN_BOARD`)
- Rentals (`TOKEN_RENTALS`)
- Ski Passes (`TOKEN_SKI_PASS`)
- Transportation Services (Outbound/Inbound)

## Implementation Details

### Service Usage Calculation

The system tracks how many participants have selected each service:

```php
private function calculateServiceUsage(BookingCreateDto $bookingDto, int $currentParticipantIndex): array
{
    $serviceUsage = [];
    
    foreach ($bookingDto->participants as $index => $participant) {
        // Skip current participant to avoid counting their potential selections
        if ($index === $currentParticipantIndex) {
            continue;
        }
        
        // Count all service types for this participant
        $this->countParticipantServiceUsage($participant, $serviceUsage);
    }
    
    return $serviceUsage;
}
```

### Availability Calculation Logic

For each service, remaining availability is calculated as:
```
If service.available is null or <= 0:
    Service is unlimited (always available)
Else:
    Remaining = max(0, original_availability - usage_count)
```

### Service Type Handling

The system handles all major service types:

**Single Selection Services**:
- Board/Meal Plans
- Ski Passes  
- Transportation (Outbound/Inbound)

**Multiple Selection Services**:
- Courses
- Additional Services
- Rentals

### Integration with Form System

#### Field Option Filtering Chain
```php
'choices' => $this->filterServicesByAvailability(
    $this->filterServicesByAgeConstraints(
        $bookingDto->travel->getAdditionalServicesBySubTypes(Constants::TOKEN_COURSES),
        $bookingDto,
        $participantIndex
    ),
    $bookingDto,
    $participantIndex
),
```

#### HTMX Integration
- Availability recalculated during each form refresh cycle
- Services dynamically hidden when capacity reached
- Real-time feedback without full page refresh
- Maintains consistency across all participants

## Business Rules

### Availability Behavior
- **Available Services**: Shown normally with pricing
- **Unavailable Services**: Hidden completely from selection
- **High Availability**: Services with very high limits effectively always available
- **Per-Participant Limit**: Each participant can select a service maximum once

### Service Capacity Management
- **Original Availability**: Parsed from XML data at booking initialization
- **Dynamic Availability**: Calculated in real-time based on current selections
- **Session Scope**: Availability tracking only within current booking session
- **No Persistence**: Changes not saved to database or XML files
- **Unlimited Services**: Services with null or ≤0 availability are treated as unlimited
- **Company Strategy**: High availability values used for services that should always be bookable

### Edge Cases Handled
- Null or missing availability values (treated as unlimited availability)
- Zero or negative availability values (treated as unlimited availability)  
- Services already selected by current participant (not counted against them)
- Invalid or missing participant data (gracefully ignored)
- Empty service arrays (handled without errors)
- Services without availability limits (always remain available)

## Usage Examples

### Scenario 1: Course Selection with Limited Capacity
```
Initial State:
- Advanced Ski Course: 3 available

Participant 1: Selects Advanced Ski Course → 2 remaining
Participant 2: Sees Advanced Ski Course available → Selects it → 1 remaining  
Participant 3: Sees Advanced Ski Course available → Selects it → 0 remaining
Participant 4: Advanced Ski Course hidden (not available)

Note: Most services will have unlimited availability (null or high values) and remain visible.
```

### Scenario 2: Multiple Service Types
```
Services with Limits:
- Rental Helmet: 10 available
- Advanced Course: 2 available
- Premium Board: 5 available

As participants select services:
- Each selection reduces availability for remaining participants
- Services become hidden when capacity reached
- Participants see only services they can still book
```

## Performance Considerations

### Optimization Strategies
- **Lightweight Calculations**: Simple arithmetic operations only
- **No Database Queries**: All data from memory (DTO objects)
- **Cached Service Lists**: Service collections retrieved once per request
- **Efficient Filtering**: Array operations with minimal overhead

### Scalability
- **Memory Usage**: Minimal additional memory footprint  
- **Processing Time**: Linear time complexity O(n) where n = participant count
- **HTMX Performance**: No impact on response times
- **Large Bookings**: Efficient even with many participants
- **Unlimited Services**: Zero-cost filtering for services without availability limits

## Configuration

### Service Registration
The ServiceAvailabilityCalculator is automatically registered via Symfony's autowiring:

```yaml
# config/services.yaml
services:
    _defaults:
        autowire: true
        autoconfigure: true

    App\:
        resource: '../src/'
        exclude:
            - '../src/Entity/'
            - '../src/Kernel.php'
```

### Field Provider Integration
```php
public function __construct(
    private readonly ParticipantRoomChoiceLoaderFactory $roomChoiceLoaderFactory,
    private readonly ServiceAvailabilityCalculator $serviceAvailabilityCalculator,
) {
    parent::__construct();
}
```

## Testing Strategy

### Unit Testing Scenarios
1. **Service Usage Calculation**: Test counting across multiple participants
2. **Availability Filtering**: Verify services hidden when capacity reached  
3. **Edge Cases**: Handle null values, empty arrays, invalid data
4. **Service Types**: Test all service categories (courses, rentals, etc.)
5. **Current Participant Exclusion**: Ensure current participant selections not counted

### Integration Testing
1. **Form Field Generation**: Verify filtered choices in field options
2. **HTMX Refresh Cycles**: Test availability updates during form interactions
3. **Multiple Participants**: Test complex scenarios with many participants
4. **Service Combinations**: Test mixed service types and availability levels

### Manual Testing Scenarios
```
Test Case 1: Basic Availability Reduction
- Create booking with 2 participants
- Select service with availability = 2 for participant 1
- Verify participant 2 sees availability reduced
- Select same service for participant 2  
- Verify service hidden for additional participants

Test Case 2: Mixed Service Types
- Test courses, rentals, and transportation together
- Verify each service type respects availability limits
- Confirm services with high limits remain available

Test Case 3: HTMX Integration  
- Make service selections via HTMX form refresh
- Verify real-time availability updates
- Test form submission and navigation between steps
```

## Error Handling

### Graceful Degradation
- **Missing Availability Data**: Treats as unavailable (hidden)
- **Invalid Service Objects**: Safely ignored in calculations  
- **Corrupted Participant Data**: Skips invalid participants
- **Service Lookup Failures**: Continues processing other services

### Logging and Monitoring
- No explicit logging (availability is business logic, not error condition)
- Integrates with existing form processing error handling
- Symfony debug toolbar shows service container usage

## Future Enhancements

### Potential Improvements
1. **Availability Display**: Show remaining count in service labels (optional)
2. **Reservation System**: Temporary hold on services during selection
3. **Priority Booking**: VIP participants get access to limited services first
4. **Cross-Session Tracking**: Track availability across multiple booking sessions
5. **Analytics**: Collect data on service demand and capacity utilization

### Performance Optimizations
1. **Caching Layer**: Cache availability calculations for identical participant sets
2. **Lazy Loading**: Only calculate availability for visible services
3. **Background Updates**: Pre-calculate availability for common scenarios
4. **Delta Updates**: Only recalculate changed services during HTMX updates

## Troubleshooting

### Common Issues

**Services Always Hidden**:
- Check if services have availability limits set (should be null/0 for unlimited)
- Verify service ID matching between travel data and participant selections  
- Confirm participant data structure is correct
- Most services should be unlimited and always visible

**Availability Not Updating**:
- Verify HTMX integration is working
- Check that form refresh includes all participant data
- Ensure ServiceAvailabilityCalculator is being called

**Performance Problems**:
- Review participant count and service selection complexity
- Check for inefficient service lookups or data processing
- Monitor memory usage with large booking sessions

### Debugging Tools
```php
// Debug availability calculation
$calculator = $container->get(ServiceAvailabilityCalculator::class);
$availability = $calculator->calculateRemainingAvailability($bookingDto, $participantIndex);
dump($availability);

// Debug service filtering  
$filtered = $calculator->filterAvailableServices($services, $bookingDto, $participantIndex);
dump($filtered);
```

## Integration Points

### Dependencies
- `App\BusProNet\Model\Service` - Service data objects
- `App\Form\Model\BookingCreateDto` - Booking and participant data
- `App\BusProNet\Constants` - Service type constants
- `App\BusProNet\Utility\DirectionMapper` - Transportation direction mapping

### Related Systems
- **Field State System**: Availability filtering integrates with conditional field states
- **Pricing System**: Available services included in pricing calculations  
- **HTMX Updates**: Availability changes trigger form refreshes
- **Form Handlers**: Service selections processed by specialized field handlers

## Future Enhancements

### Planned: API Validation Stage

**Important Note**: The current availability system uses XML data that may become outdated during the booking creation process. A future enhancement will implement a **validation stage** that checks final service selections against real-time availability via the BusProNet API before final booking confirmation.

#### Planned Implementation
- **Pre-Submission Validation**: Before final booking submission, validate all selected services against current API availability
- **Real-Time Check**: Call BusProNet API to get current availability status
- **Conflict Resolution**: Handle cases where selected services are no longer available
- **User Feedback**: Provide clear messaging when services become unavailable during booking process

#### Technical Integration Points
```php
// Future validation service (planned)
class BookingValidationService 
{
    public function validateServiceAvailability(BookingCreateDto $bookingDto): ValidationResult;
    public function resolveAvailabilityConflicts(BookingCreateDto $bookingDto): ConflictResolution;
}
```

#### Business Logic
- **Session Availability**: Current system prevents overbooking within single booking session
- **API Validation**: Future system will prevent overbooking across all booking sessions system-wide
- **Two-Stage Protection**: Provides both immediate feedback and final validation

This planned enhancement will complement the existing dynamic availability system by adding a final validation layer that ensures booking integrity against the authoritative BusProNet API data.

---

**Implementation Status**: ✅ **Completed and Tested**  
**Last Updated**: January 2025  
**Integration**: Seamless with existing form system  
**Performance**: Optimized for real-time updates  
**Testing**: Verified working in development environment  
**Future Enhancement**: API validation stage planned for booking finalization  
**Documentation**: Comprehensive with examples and troubleshooting