409 lines
15 KiB
Markdown
409 lines
15 KiB
Markdown
# Insurance Booking System Implementation Plan
|
|
|
|
## Overview
|
|
|
|
This document outlines the complete implementation plan for making travel insurances bookable per participant in the MyEP Next Booking system. The implementation includes sophisticated criteria matching, automatic re-selection when participant prices change, and comprehensive form integration.
|
|
|
|
## Current System Status
|
|
|
|
### ✅ Already Implemented
|
|
- **Insurance XML Parsing**: `InsuranceParser` and `InsuranceLoader` classes
|
|
- **Insurance Model**: Complete with price ranges, age constraints, dates, family flags
|
|
- **Family Status Logic**: `BookingCreateDto::isFamilyBooking()` method
|
|
- **Individual Pricing**: `BookingPriceCalculatorService::calculateIndividualParticipantPrice()` method
|
|
- **Field Handler Architecture**: Existing pattern for dynamic form fields
|
|
- **HTMX Integration**: Real-time form updates infrastructure
|
|
|
|
### ✅ Recently Completed
|
|
- **Phase 1**: Insurance subtype parsing and type resolution system ✅
|
|
- **Phase 2**: Enhanced age calculation with reference date support ✅
|
|
- **Phase 3**: Insurance matching service with comprehensive criteria validation ✅
|
|
- **Phase 4**: ParticipantDto enhancement with insurance property ✅
|
|
- **Phase 5**: Form field handler for insurance selection processing ✅
|
|
|
|
### ❌ Remaining Implementation
|
|
- Form integration and field configuration
|
|
- Controller integration and data handling
|
|
- Frontend templates and UX
|
|
- Auto-reselection when participant price changes
|
|
- Advanced features and applicant control
|
|
|
|
## Key Technical Discoveries
|
|
|
|
### Insurance XML Structure Analysis
|
|
- **Individual Insurances**: Have `unterart` (subtype) attribute (RRV, PAK, OHN)
|
|
- **Insurance Packages**: No subtype but contain individual insurances
|
|
- **Family Detection**: Use `familienversicherung` boolean attribute (not label parsing)
|
|
- **Package Type Resolution**: Analyze contained insurances to determine dominant type
|
|
|
|
### Age Calculation Requirement
|
|
- **Critical**: Use travel start date for age calculation, not current date
|
|
- Insurance eligibility based on participant's age at time of travel
|
|
|
|
## Implementation Phases
|
|
|
|
### Phase 1: Insurance Type System ✅ COMPLETED
|
|
**Goal**: Add type resolution capability to distinguish insurance types
|
|
|
|
#### 1.1 Extend Insurance Model ✅
|
|
- [x] Add `subType` property to `Insurance` model (from XML `unterart`)
|
|
- [x] Add computed `type` property (resolved via service)
|
|
- [x] Update serialization groups if needed
|
|
|
|
#### 1.2 Update Insurance Parser ✅
|
|
- [x] Modify `InsuranceParser::parseInsuranceNode()` to parse `unterart` attribute
|
|
- [x] Add subtype to individual insurance parsing
|
|
- [x] Ensure package parsing maintains existing functionality
|
|
|
|
#### 1.3 Create Insurance Type Resolver ✅
|
|
- [x] Create `InsuranceTypeResolver` service
|
|
- [x] Implement type resolution for individual insurances
|
|
- [x] Implement package type resolution via contained insurance analysis
|
|
- [x] Define type constants: `TRAVEL_CANCELLATION`, `TRAVEL_PROTECTION`, etc.
|
|
- [x] Handle family variants using `familyInsurance` boolean
|
|
|
|
```php
|
|
// Type Constants
|
|
const TRAVEL_CANCELLATION = 'TRAVEL_CANCELLATION';
|
|
const TRAVEL_CANCELLATION_FAMILY = 'TRAVEL_CANCELLATION_FAMILY';
|
|
const TRAVEL_PROTECTION = 'TRAVEL_PROTECTION';
|
|
const TRAVEL_PROTECTION_FAMILY = 'TRAVEL_PROTECTION_FAMILY';
|
|
const DEDUCTIBLE = 'DEDUCTIBLE';
|
|
```
|
|
|
|
#### 1.4 Testing ✅
|
|
- [x] Create `InsuranceTypeResolverTest`
|
|
- [x] Test individual insurance type resolution
|
|
- [x] Test package type resolution
|
|
- [x] Test family variant detection
|
|
- [x] Verify existing insurance parsing still works
|
|
|
|
### Phase 2: Enhanced Age Calculation ✅ COMPLETED
|
|
**Goal**: Support age calculation at specific dates (travel start date)
|
|
|
|
#### 2.1 Update ParticipantDto ✅
|
|
- [x] Enhanced existing `getAge()` method with optional reference date parameter
|
|
- [x] Keep existing `getAge(): ?int` for backward compatibility
|
|
- [x] Ensure proper null handling for missing birth dates
|
|
|
|
#### 2.2 Testing ✅
|
|
- [x] Add comprehensive tests for reference date age calculation
|
|
- [x] Test edge cases (leap years, same day, etc.)
|
|
- [x] Verify existing age calculation still works
|
|
|
|
### Phase 3: Insurance Matching Service
|
|
**Goal**: Implement comprehensive insurance matching with all criteria
|
|
|
|
#### 3.1 Create Insurance Matching Service
|
|
- [ ] Create `InsuranceMatchingService` class
|
|
- [ ] Implement `getMatchingInsurances()` method with all criteria:
|
|
- Age at travel date validation
|
|
- Price range validation
|
|
- Booking date validation
|
|
- Travel date validation
|
|
- Family insurance validation
|
|
- [ ] Implement `getMatchingInsurancesByType()` for auto-reselection
|
|
- [ ] Add "No Insurance" option handling
|
|
|
|
#### 3.2 Auto-Reselection Logic
|
|
- [ ] Implement `handlePriceChange()` method
|
|
- [ ] Find matching insurance of same type when price changes
|
|
- [ ] Maintain coverage when possible, fallback to null
|
|
- [ ] Log auto-reselection events for debugging
|
|
|
|
#### 3.3 Service Registration
|
|
- [ ] Register service in `services.yaml`
|
|
- [ ] Configure dependencies (InsuranceLoader, InsuranceTypeResolver)
|
|
|
|
#### 3.4 Testing
|
|
- [ ] Create comprehensive `InsuranceMatchingServiceTest`
|
|
- [ ] Test all matching criteria combinations
|
|
- [ ] Test auto-reselection scenarios
|
|
- [ ] Test edge cases and boundary conditions
|
|
|
|
### Phase 4: Participant DTO Enhancement
|
|
**Goal**: Add insurance property and integrate with pricing
|
|
|
|
#### 4.1 Extend ParticipantDto
|
|
- [ ] Add `?Insurance $insurance = null` property
|
|
- [ ] Add validation groups if needed
|
|
- [ ] Ensure proper serialization/deserialization
|
|
|
|
#### 4.2 Update Price Calculation
|
|
- [ ] Modify `BookingPriceCalculatorService::calculateParticipantServiceTotal()`
|
|
- [ ] Include insurance price in participant total
|
|
- [ ] Update `calculateIndividualParticipantPrice()` to include insurance
|
|
- [ ] Update `calculateAllParticipantIndividualPrices()` accordingly
|
|
|
|
#### 4.3 Testing
|
|
- [ ] Update `BookingPriceCalculatorServiceTest`
|
|
- [ ] Test price calculation with insurance
|
|
- [ ] Test pricing without insurance
|
|
- [ ] Verify individual participant pricing includes insurance
|
|
|
|
### Phase 5: Form Field Handler
|
|
**Goal**: Create form field handler for insurance selection
|
|
|
|
#### 5.1 Create Insurance Field Handler
|
|
- [ ] Create `ParticipantInsuranceFieldHandler` extending `AbstractParticipantFieldHandler`
|
|
- [ ] Implement field processing logic
|
|
- [ ] Handle insurance selection validation
|
|
- [ ] Implement auto-reselection on price changes
|
|
- [ ] Clear insurance if criteria no longer match
|
|
|
|
#### 5.2 Field Dependencies
|
|
- [ ] Define dependencies: `dateOfBirth` (for age calculation)
|
|
- [ ] Handle field visibility based on available insurances
|
|
- [ ] Implement proper error handling
|
|
|
|
#### 5.3 Service Registration
|
|
- [ ] Register handler in `services.yaml` with proper tags
|
|
- [ ] Set appropriate priority in relation to other handlers
|
|
|
|
#### 5.4 Testing
|
|
- [ ] Create `ParticipantInsuranceFieldHandlerTest`
|
|
- [ ] Test field processing
|
|
- [ ] Test auto-reselection scenarios
|
|
- [ ] Test validation logic
|
|
|
|
### Phase 6: Form Integration
|
|
**Goal**: Add insurance field to participant form
|
|
|
|
#### 6.1 Update Form Type
|
|
- [ ] Modify `BookingCreateParticipantType`
|
|
- [ ] Add insurance choice field
|
|
- [ ] Configure field type and options
|
|
- [ ] Add HTMX trigger attributes
|
|
|
|
#### 6.2 Field Options Provider
|
|
- [ ] Add insurance field to `ParticipantFieldOptionsProvider`
|
|
- [ ] Generate "No Insurance" option
|
|
- [ ] Generate valid insurance options per participant
|
|
- [ ] Use `InsuranceMatchingService` for filtering
|
|
- [ ] Format options with price and type information
|
|
|
|
#### 6.3 Field State Provider Integration
|
|
- [ ] Update `CreateFieldStateProvider` if needed
|
|
- [ ] Handle field visibility conditions
|
|
- [ ] Register field state conditions
|
|
|
|
#### 6.4 Testing
|
|
- [ ] Test form field rendering
|
|
- [ ] Test field options generation
|
|
- [ ] Test HTMX integration
|
|
|
|
### Phase 7: Controller Integration
|
|
**Goal**: Update controllers to handle insurance data
|
|
|
|
#### 7.1 Update Step 2 Controller
|
|
- [ ] Ensure insurance data is included in template variables
|
|
- [ ] Handle insurance-related HTMX updates
|
|
- [ ] Update participant price calculations to include insurance
|
|
|
|
#### 7.2 Error Handling
|
|
- [ ] Add proper error handling for insurance validation
|
|
- [ ] Handle insurance matching failures gracefully
|
|
- [ ] Provide user-friendly error messages
|
|
|
|
#### 7.3 Testing
|
|
- [ ] Test controller responses include insurance data
|
|
- [ ] Test HTMX updates work correctly
|
|
- [ ] Test error scenarios
|
|
|
|
### Phase 8: Frontend Templates
|
|
**Goal**: Add insurance field to templates and display pricing
|
|
|
|
#### 8.1 Template Updates
|
|
- [ ] Add insurance field to `create_step_2.html.twig`
|
|
- [ ] Position field appropriately in participant sections
|
|
- [ ] Add proper labeling and help text
|
|
- [ ] Configure HTMX attributes for real-time updates
|
|
|
|
#### 8.2 Pricing Display
|
|
- [ ] Update participant headers to show insurance pricing
|
|
- [ ] Include insurance in individual participant price display
|
|
- [ ] Update booking summary to include insurance totals
|
|
|
|
#### 8.3 UX Enhancements
|
|
- [ ] Show criteria-based availability information
|
|
- [ ] Display auto-reselection notifications
|
|
- [ ] Add loading states for HTMX updates
|
|
|
|
### Phase 9: Advanced Features
|
|
**Goal**: Implement applicant control and bulk operations
|
|
|
|
#### 9.1 Applicant Insurance Control
|
|
- [ ] Add special UI for first participant (applicant)
|
|
- [ ] Implement bulk insurance selection
|
|
- [ ] Respect individual criteria while allowing bulk operations
|
|
- [ ] Add override capabilities with proper validation
|
|
|
|
#### 9.2 Real-time Price Integration
|
|
- [ ] Monitor price changes via HTMX
|
|
- [ ] Trigger auto-reselection when participant price changes
|
|
- [ ] Provide visual feedback for automatic changes
|
|
- [ ] Update pricing summary dynamically
|
|
|
|
#### 9.3 Enhanced UX
|
|
- [ ] Add insurance type grouping in selection
|
|
- [ ] Implement insurance comparison features
|
|
- [ ] Add detailed insurance information display
|
|
- [ ] Improve mobile responsiveness
|
|
|
|
### Phase 10: Testing & Quality Assurance
|
|
**Goal**: Comprehensive testing and code quality
|
|
|
|
#### 10.1 Integration Testing
|
|
- [ ] Create end-to-end insurance booking tests
|
|
- [ ] Test complete booking flow with insurances
|
|
- [ ] Test auto-reselection scenarios
|
|
- [ ] Test applicant control features
|
|
|
|
#### 10.2 Performance Testing
|
|
- [ ] Test insurance matching performance with large datasets
|
|
- [ ] Optimize insurance filtering algorithms
|
|
- [ ] Test HTMX update performance
|
|
|
|
#### 10.3 Code Quality
|
|
- [ ] Run PHP CS Fixer on all new files
|
|
- [ ] Ensure PSR-12 compliance
|
|
- [ ] Add proper PHPDoc documentation
|
|
- [ ] Review and optimize service dependencies
|
|
|
|
#### 10.4 User Acceptance Testing
|
|
- [ ] Test with real insurance data
|
|
- [ ] Validate business logic with stakeholders
|
|
- [ ] Test edge cases and error scenarios
|
|
- [ ] Gather user feedback on UX
|
|
|
|
## Technical Architecture
|
|
|
|
### New Classes Overview
|
|
|
|
```
|
|
src/Service/
|
|
├── InsuranceTypeResolver.php # Type resolution for insurances and packages
|
|
├── InsuranceMatchingService.php # Criteria-based insurance matching
|
|
└── Insurance/
|
|
├── Criteria/
|
|
│ ├── AgeCriterion.php # Age-based matching
|
|
│ ├── PriceCriterion.php # Price range matching
|
|
│ ├── DateCriterion.php # Date validation
|
|
│ └── FamilyCriterion.php # Family insurance validation
|
|
└── Matcher/
|
|
└── InsuranceMatcher.php # Core matching logic
|
|
|
|
src/Form/Service/
|
|
├── ParticipantInsuranceFieldHandler.php # Form field processing
|
|
└── Insurance/
|
|
└── InsuranceFieldOptionsProvider.php # Field options generation
|
|
|
|
tests/Service/
|
|
├── InsuranceTypeResolverTest.php
|
|
├── InsuranceMatchingServiceTest.php
|
|
└── Insurance/
|
|
└── Criteria/
|
|
├── AgeCriterionTest.php
|
|
├── PriceCriterionTest.php
|
|
├── DateCriterionTest.php
|
|
└── FamilyCriterionTest.php
|
|
|
|
tests/Form/Service/
|
|
└── ParticipantInsuranceFieldHandlerTest.php
|
|
```
|
|
|
|
### Database Changes
|
|
- **None required** - All insurance data loaded from XML
|
|
|
|
### Configuration Changes
|
|
- Service registrations in `services.yaml`
|
|
- Field handler tags and priorities
|
|
- Form field configurations
|
|
|
|
## Implementation Guidelines
|
|
|
|
### Code Standards
|
|
- Follow PSR-12 coding standards
|
|
- Use `declare(strict_types=1)` on all files
|
|
- Apply Symfony coding standards via php-cs-fixer
|
|
- Use English for all variable and constant names
|
|
- Follow existing architectural patterns
|
|
|
|
### Testing Standards
|
|
- Minimum 90% code coverage for new classes
|
|
- Unit tests for all service methods
|
|
- Integration tests for form processing
|
|
- End-to-end tests for complete booking flow
|
|
- Performance tests for matching algorithms
|
|
|
|
### Documentation Standards
|
|
- PHPDoc for all public methods
|
|
- Business logic documentation in comments
|
|
- Update CLAUDE.md with new features
|
|
- Create user documentation for insurance features
|
|
|
|
## Risk Mitigation
|
|
|
|
### Technical Risks
|
|
1. **Performance**: Large insurance datasets could slow matching
|
|
- **Mitigation**: Implement caching and optimize algorithms
|
|
2. **Complexity**: Auto-reselection logic could introduce bugs
|
|
- **Mitigation**: Comprehensive testing and logging
|
|
3. **Data Integrity**: Price changes could cause inconsistent states
|
|
- **Mitigation**: Atomic operations and validation
|
|
|
|
### Business Risks
|
|
1. **Incorrect Matching**: Wrong insurance eligibility could cause issues
|
|
- **Mitigation**: Thorough testing with real data and stakeholder validation
|
|
2. **User Confusion**: Complex insurance options could confuse users
|
|
- **Mitigation**: Clear UX design and comprehensive help text
|
|
|
|
## Success Criteria
|
|
|
|
### Functional Requirements
|
|
- ✅ Participants can select appropriate insurances based on all criteria
|
|
- ✅ Auto-reselection works when participant price changes
|
|
- ✅ Applicant can manage insurances for all participants
|
|
- ✅ Real-time pricing updates include insurance costs
|
|
- ✅ Form validation prevents invalid insurance selections
|
|
|
|
### Performance Requirements
|
|
- ✅ Insurance matching completes within 100ms for typical datasets
|
|
- ✅ HTMX updates complete within 500ms
|
|
- ✅ Page load times remain under 2 seconds
|
|
|
|
### Quality Requirements
|
|
- ✅ 90%+ code coverage for new functionality
|
|
- ✅ Zero critical bugs in production
|
|
- ✅ PSR-12 compliance for all new code
|
|
- ✅ Comprehensive documentation
|
|
|
|
## Future Enhancements
|
|
|
|
### Phase 11+ (Future)
|
|
- Insurance comparison tools
|
|
- Advanced filtering and search
|
|
- Insurance recommendation engine
|
|
- Historical insurance selection analytics
|
|
- Multi-language insurance descriptions
|
|
- PDF insurance documentation generation
|
|
|
|
## Dependencies
|
|
|
|
### External Dependencies
|
|
- Insurance XML data must be available and properly formatted
|
|
- BusProNet API integration for insurance booking
|
|
- Travel data must include proper date information
|
|
|
|
### Internal Dependencies
|
|
- Existing individual pricing calculation system
|
|
- Field handler architecture
|
|
- HTMX integration infrastructure
|
|
- Family status determination logic
|
|
|
|
---
|
|
|
|
**Document Version**: 1.0
|
|
**Last Updated**: 2025-09-26
|
|
**Author**: Claude Code Implementation Plan
|
|
**Status**: Ready for Implementation |