wip: implement transportation, pickups and parking
This commit is contained in:
Björn Fromme
@@ -0,0 +1,341 @@
|
||||
# MyEP Next Booking System
|
||||
|
||||
A sophisticated Symfony 6.4 travel booking application that integrates with Bus Pro Net (BPN) XML API for comprehensive travel management. The system handles complex multi-step booking workflows with dynamic participant forms, conditional field logic, and real-time pricing display.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Prerequisites
|
||||
- PHP 8.1+
|
||||
- Composer
|
||||
- Node.js & npm
|
||||
- DDEV (recommended for local development)
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone [repository-url]
|
||||
cd myep-next-booking
|
||||
|
||||
# Install dependencies
|
||||
composer install
|
||||
npm install
|
||||
|
||||
# Start local development environment
|
||||
ddev start
|
||||
|
||||
# Run database migrations
|
||||
bin/console doctrine:migrations:migrate
|
||||
|
||||
# Generate OAuth2 keys
|
||||
bin/console app:generate-keys
|
||||
|
||||
# Compile assets
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## 🏗️ Architecture Overview
|
||||
|
||||
### Multi-Step Booking Flow
|
||||
1. **Step 1**: Room selection with quantities and dates
|
||||
2. **Step 2**: Participant details with conditional fields and service selection
|
||||
3. **Step 3**: Final confirmation and submission to BPN API
|
||||
|
||||
### Core Components
|
||||
|
||||
#### BusProNet Integration (`src/BusProNet/`)
|
||||
- **ApiClient**: XML API communication layer
|
||||
- **XmlParser/**: Response parsing for travels, hotels, bookings
|
||||
- **XmlLoader/**: Data loading with caching
|
||||
- **DataProcessor/**: API data transformation
|
||||
|
||||
#### Advanced Form System (`src/Form/Service/`)
|
||||
- **Conditional Field States**: Dynamic field behavior based on participant data
|
||||
- **Service Field Handlers**: Modular field processing with dependency resolution
|
||||
- **Transportation Services**: Comprehensive pickup, parking, and transportation options
|
||||
- **Real-time Updates**: HTMX integration for seamless UX
|
||||
|
||||
#### Service Architecture (`src/Service/`)
|
||||
- **BookingService**: Core booking workflow management
|
||||
- **TravelDataService**: Travel data access and caching
|
||||
- **BookingPriceCalculatorService**: Real-time pricing calculations
|
||||
|
||||
## 🎯 Key Features
|
||||
|
||||
### ✅ Implemented Features
|
||||
|
||||
#### Multi-Step Booking Workflow
|
||||
- Room selection with dynamic pricing display
|
||||
- Participant registration with conditional fields
|
||||
- Service selection (board, ski passes, courses, rentals)
|
||||
- Real-time booking summary with pricing
|
||||
|
||||
#### Transportation Services
|
||||
- **Transportation Selection**: Bus vs. car transport options
|
||||
- **Pickup Services**: Location-based pickup with conditional visibility
|
||||
- **Parking Services**: Self-organized transport parking options
|
||||
- **Direction Mapping**: Outbound/inbound transportation handling
|
||||
|
||||
#### Advanced Form System
|
||||
- **Conditional Field States**: Age-based, value-dependent field visibility
|
||||
- **Dynamic Field Options**: Context-aware choice generation
|
||||
- **HTMX Integration**: Real-time form updates without page refresh
|
||||
- **XSS Protection**: Built-in security measures
|
||||
|
||||
#### Pricing & Display
|
||||
- **Inline Pricing**: Service costs displayed in form options
|
||||
- **Real-time Calculations**: Live pricing updates via HTMX
|
||||
- **Smart Formatting**: Zero-price services handled gracefully
|
||||
- **Unified Summary**: Integrated booking and pricing display
|
||||
|
||||
#### Service Integration
|
||||
- **Field Handler Registry**: Modular field processing system
|
||||
- **Service Registration**: Automatic field handler discovery
|
||||
- **Dependency Resolution**: Smart field interdependency handling
|
||||
|
||||
### 🔄 Ongoing Development
|
||||
- Age-based field constraints
|
||||
- Enhanced pricing features (discounts, taxes)
|
||||
- Advanced booking management
|
||||
- Extended BPN API integration
|
||||
|
||||
## 🛠️ Development
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
# Development workflow
|
||||
npm run dev # Development build
|
||||
npm run watch # Watch mode
|
||||
npm run build # Production build
|
||||
|
||||
# Testing
|
||||
bin/phpunit # All tests
|
||||
./vendor/bin/phpunit tests/Service/ # Specific directory
|
||||
./vendor/bin/phpunit tests/BusProNet/ # API integration tests
|
||||
|
||||
# Code quality
|
||||
./vendor/bin/php-cs-fixer fix # Fix code style
|
||||
|
||||
# Cache & debugging
|
||||
bin/console cache:clear # Clear cache
|
||||
bin/console debug:router # Debug routes
|
||||
bin/console debug:container # Debug services
|
||||
|
||||
# Custom commands
|
||||
bin/console app:cleanup-xml-dumps # Clean XML dump files
|
||||
bin/console app:generate-keys # Generate OAuth2 keys
|
||||
```
|
||||
|
||||
### Development Standards
|
||||
|
||||
#### Code Style
|
||||
- PSR-12 compliance with `declare(strict_types=1)`
|
||||
- PHP 8+ features (typed properties, constructor promotion, match expressions)
|
||||
- Explicit comparisons and Yoda conditions
|
||||
- Immutable DateTime objects (DateTimeImmutable, CarbonImmutable)
|
||||
|
||||
#### Architecture Patterns
|
||||
- Service layer for business logic
|
||||
- DTO pattern for type-safe form data
|
||||
- Registry pattern for configurable components
|
||||
- Field handler pattern for complex form processing
|
||||
- Trait-based code reuse
|
||||
|
||||
## 🏛️ Technical Stack
|
||||
|
||||
### Backend
|
||||
- **Framework**: Symfony 6.4 LTS
|
||||
- **PHP**: 8.1+
|
||||
- **Database**: MariaDB with Doctrine ORM
|
||||
- **API Integration**: Custom XML client for BPN API
|
||||
- **Authentication**: OAuth2 Server Bundle
|
||||
|
||||
### Frontend
|
||||
- **JavaScript**: Stimulus (Hotwired) controllers
|
||||
- **Dynamic Updates**: HTMX for seamless interactions
|
||||
- **Styling**: TailwindCSS
|
||||
- **Build Tool**: Webpack Encore
|
||||
- **Templating**: Twig
|
||||
|
||||
### Development & Operations
|
||||
- **Local Environment**: DDEV (PHP 8.2, MariaDB 10.11)
|
||||
- **File Operations**: Flysystem with SFTP support
|
||||
- **Date Handling**: Carbon for advanced date/time manipulation
|
||||
- **Logging**: Monolog with multiple channels
|
||||
- **Testing**: PHPUnit with Symfony bridge
|
||||
|
||||
## 📋 Form System Architecture
|
||||
|
||||
### Field Handler System
|
||||
The application uses a sophisticated field handler system for processing complex participant forms:
|
||||
|
||||
```php
|
||||
// Example field handler
|
||||
class ParticipantTransportationOutboundFieldHandler extends AbstractParticipantFieldHandler
|
||||
{
|
||||
public function processField(/* ... */): void
|
||||
{
|
||||
// Complex field processing with conditional logic
|
||||
}
|
||||
|
||||
public function getDependencies(): array
|
||||
{
|
||||
return ['assignedRoomId', 'dateOfBirth']; // Field dependencies
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Conditional Field States
|
||||
Fields can have dynamic states based on conditions:
|
||||
|
||||
```php
|
||||
// Age-based field state
|
||||
$this->fieldStateConditions['advancedServices'] = [
|
||||
'hidden' => new AgeRangeCondition(null, 15), // Hide for under 15
|
||||
'required' => FieldValueCondition::equals('roomType', 'suite'),
|
||||
];
|
||||
```
|
||||
|
||||
### Available Field Handlers
|
||||
- **Transportation**: Outbound/inbound transport selection
|
||||
- **Pickup Services**: Location-based pickup options
|
||||
- **Parking**: Self-organized transport parking
|
||||
- **Accommodation**: Board, room assignment
|
||||
- **Activities**: Ski passes, courses, rentals
|
||||
- **Personal Data**: Age-aware field processing
|
||||
|
||||
## 💰 Pricing System
|
||||
|
||||
### Real-time Pricing Display
|
||||
- **Inline Pricing**: Costs shown in form options
|
||||
- **Live Updates**: HTMX-powered real-time calculations
|
||||
- **Smart Formatting**: Zero-price services handled elegantly
|
||||
- **Unified Summary**: Integrated pricing in booking summary
|
||||
|
||||
### Service Integration
|
||||
```php
|
||||
// Pricing calculation example
|
||||
$serviceTotal = $this->bookingService->calculateServiceTotal($bookingDto);
|
||||
$roomTotal = $this->bookingService->calculateRoomTotal($bookingDto);
|
||||
$grandTotal = $serviceTotal + $roomTotal;
|
||||
```
|
||||
|
||||
## 🔄 BusProNet API Integration
|
||||
|
||||
### XML Communication
|
||||
- **Request Building**: Dynamic XML generation for BPN API
|
||||
- **Response Parsing**: Structured XML parsing with validation
|
||||
- **Data Caching**: Intelligent caching for performance
|
||||
- **Error Handling**: Comprehensive error management
|
||||
|
||||
### Data Flow
|
||||
1. Form submission triggers API request building
|
||||
2. XML sent to BPN API endpoints
|
||||
3. Response parsed and validated
|
||||
4. Data transformed for application use
|
||||
5. Results cached for performance
|
||||
|
||||
## 🧪 Testing Strategy
|
||||
|
||||
### Test Coverage
|
||||
- **Unit Tests**: Service layer and business logic
|
||||
- **Integration Tests**: API communication and data processing
|
||||
- **Form Tests**: Field handler and validation logic
|
||||
- **XML Tests**: API response parsing with fixtures
|
||||
|
||||
### Running Tests
|
||||
```bash
|
||||
# All tests
|
||||
./vendor/bin/phpunit
|
||||
|
||||
# Specific test suites
|
||||
./vendor/bin/phpunit tests/BusProNet/ # API integration
|
||||
./vendor/bin/phpunit tests/Service/ # Service layer
|
||||
./vendor/bin/phpunit tests/Form/ # Form processing
|
||||
```
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
### Available Documentation
|
||||
- **[CLAUDE.md](CLAUDE.md)**: Development guidelines for AI assistance
|
||||
- **[Field State System](docs/FIELD_STATE_SYSTEM.md)**: Conditional field architecture
|
||||
- **[Form Processing](docs/FORM_PROCESSING.md)**: Form handler system details
|
||||
- **[Pricing Implementation](docs/PRICING_DISPLAY_IMPLEMENTATION.md)**: Pricing system documentation
|
||||
- **[Transportation Services](docs/TRANSPORTATION_SERVICES_IMPLEMENTATION_PLAN.md)**: Transportation feature details
|
||||
- **[Age-Based Fields](docs/AGE_BASED_FIELDS_PLAN.md)**: Age constraint system
|
||||
|
||||
### Architecture Documentation
|
||||
Each major system component has detailed documentation covering:
|
||||
- Implementation patterns
|
||||
- Usage examples
|
||||
- Extension guidelines
|
||||
- Testing strategies
|
||||
|
||||
## 🔒 Security & Configuration
|
||||
|
||||
### Environment Setup
|
||||
- BPN API credentials in `.env.local`
|
||||
- OAuth2 encryption keys via custom command
|
||||
- SFTP configuration for deployment
|
||||
- Logging channels for monitoring
|
||||
|
||||
### Security Features
|
||||
- XSS protection in form processing
|
||||
- OAuth2 authentication
|
||||
- Secure API communication
|
||||
- Input validation and sanitization
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### Production Requirements
|
||||
- PHP 8.1+ with required extensions
|
||||
- MariaDB 10.11+
|
||||
- Web server (Apache/Nginx)
|
||||
- SFTP access for file operations
|
||||
- BPN API credentials
|
||||
|
||||
### Deployment Steps
|
||||
1. Install dependencies (`composer install --no-dev`)
|
||||
2. Generate OAuth2 keys (`bin/console app:generate-keys`)
|
||||
3. Run database migrations (`bin/console doctrine:migrations:migrate`)
|
||||
4. Build production assets (`npm run build`)
|
||||
5. Configure environment variables
|
||||
6. Set up SFTP access for XML exports
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
### Development Workflow
|
||||
1. Follow PSR-12 coding standards
|
||||
2. Use type declarations consistently
|
||||
3. Write comprehensive tests for new features
|
||||
4. Update documentation for architectural changes
|
||||
5. Use the field handler pattern for form extensions
|
||||
|
||||
### Key Patterns
|
||||
- **Service Layer**: Business logic separation
|
||||
- **DTO Pattern**: Type-safe data transfer
|
||||
- **Registry Pattern**: Component discovery
|
||||
- **Field Handlers**: Modular form processing
|
||||
|
||||
## 📞 Support
|
||||
|
||||
### Logging Channels
|
||||
- **app**: General application logs
|
||||
- **bpn**: BusProNet API interactions
|
||||
- **security**: Authentication/authorization
|
||||
- **db**: Database-related logs
|
||||
|
||||
### Debugging
|
||||
- Use `bin/console debug:router` for route inspection
|
||||
- Use `bin/console debug:container` for service inspection
|
||||
- Check logs in `var/log/` for troubleshooting
|
||||
- Use DDEV for consistent development environment
|
||||
|
||||
---
|
||||
|
||||
**Version**: 2.0
|
||||
**Symfony**: 6.4 LTS
|
||||
**PHP**: 8.1+
|
||||
**Status**: Production Ready
|
||||
**Last Updated**: 2025-01-XX
|
||||
Reference in New Issue
Block a user