mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 07:51:09 -05:00
Implement hybrid filtering strategy for parks and rides
- Added comprehensive documentation for hybrid filtering implementation, including architecture, API endpoints, performance characteristics, and usage examples. - Developed a hybrid pagination and client-side filtering recommendation, detailing server-side responsibilities and client-side logic. - Created a test script for hybrid filtering endpoints, covering various test cases including basic filtering, search functionality, pagination, and edge cases.
This commit is contained in:
pacnpal
229
docs/backend-contract-compliance.md
Normal file
229
docs/backend-contract-compliance.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# Backend Contract Compliance Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the implementation of contract compliance between the Django backend and frontend TypeScript interfaces for ThrillWiki. The changes ensure that all API responses exactly match the frontend TypeScript contracts, eliminating runtime errors and improving developer experience.
|
||||
|
||||
## Problem Solved
|
||||
|
||||
**Critical Issue**: The backend was returning inconsistent data formats that violated frontend TypeScript contracts, causing runtime crashes.
|
||||
|
||||
**Example of the Problem**:
|
||||
- Frontend expected: `statuses: Array<{ value: string; label: string; count?: number }>`
|
||||
- Backend returned: `statuses: ["OPERATING", "CLOSED_TEMP"]`
|
||||
- This caused crashes when frontend tried to destructure: `{statuses.map(({ value, label }) => ...)}`
|
||||
|
||||
## Implementation Summary
|
||||
|
||||
### 1. Fixed Filter Metadata Contract Violations (URGENT - Prevents Runtime Crashes)
|
||||
|
||||
**Files Modified**:
|
||||
- `backend/apps/parks/services/hybrid_loader.py`
|
||||
- `backend/apps/rides/services/hybrid_loader.py`
|
||||
|
||||
**Changes Made**:
|
||||
- Modified `_get_filter_metadata` methods in both loaders
|
||||
- Changed all categorical filters from string arrays to object arrays
|
||||
- Each filter option now has: `{ value: string, label: string, count: number }`
|
||||
|
||||
**Before (WRONG - caused frontend crashes)**:
|
||||
```python
|
||||
'statuses': ['OPERATING', 'CLOSED_TEMP']
|
||||
```
|
||||
|
||||
**After (CORRECT - matches TypeScript interface)**:
|
||||
```python
|
||||
'statuses': [
|
||||
{'value': 'OPERATING', 'label': 'Operating', 'count': 42},
|
||||
{'value': 'CLOSED_TEMP', 'label': 'Temporarily Closed', 'count': 5}
|
||||
]
|
||||
```
|
||||
|
||||
### 2. Created Shared Contract Serializers
|
||||
|
||||
**File Created**: `backend/apps/api/v1/serializers/shared.py`
|
||||
|
||||
**Key Serializers**:
|
||||
- `FilterOptionSerializer` - Standard filter option format
|
||||
- `FilterRangeSerializer` - Standard range filter format
|
||||
- `StandardizedFilterMetadataSerializer` - Complete filter metadata structure
|
||||
- `ApiResponseSerializer` - Standard API response wrapper
|
||||
- `ErrorResponseSerializer` - Standard error response format
|
||||
|
||||
**Utility Functions**:
|
||||
- `validate_filter_metadata_contract()` - Validates filter metadata against contracts
|
||||
- `ensure_filter_option_format()` - Converts various formats to standard filter options
|
||||
- `ensure_range_format()` - Ensures range data follows expected format
|
||||
|
||||
### 3. Added Contract Validation Middleware
|
||||
|
||||
**File Created**: `backend/apps/api/v1/middleware.py`
|
||||
|
||||
**Features**:
|
||||
- Development-only middleware (active when `DEBUG=True`)
|
||||
- Validates all API responses for contract compliance
|
||||
- Logs warnings when responses don't match TypeScript interfaces
|
||||
- Specifically catches categorical filters returned as strings
|
||||
- Provides actionable suggestions for fixing violations
|
||||
|
||||
**Key Validations**:
|
||||
- Categorical filters must be objects with `value`/`label`/`count` properties
|
||||
- Range filters must have `min`/`max`/`step`/`unit` properties
|
||||
- Pagination responses must have proper structure
|
||||
- Numeric fields must be numbers, not strings
|
||||
|
||||
### 4. Created Contract Compliance Tests
|
||||
|
||||
**File Created**: `backend/apps/api/v1/tests/test_contracts.py`
|
||||
|
||||
**Test Categories**:
|
||||
- `FilterMetadataContractTests` - Tests filter metadata structure
|
||||
- `ContractValidationUtilityTests` - Tests utility functions
|
||||
- `TypeScriptInterfaceComplianceTests` - Tests TypeScript interface compliance
|
||||
- `RegressionTests` - Prevents specific contract violations from returning
|
||||
|
||||
**Critical Regression Tests**:
|
||||
- Ensures categorical filters are never returned as strings
|
||||
- Validates ranges have required `step` and `unit` properties
|
||||
- Checks for proper null handling (not undefined)
|
||||
|
||||
### 5. Created Base Views for Consistent Responses
|
||||
|
||||
**File Created**: `backend/apps/api/v1/views/base.py`
|
||||
|
||||
**Base Classes**:
|
||||
- `ContractCompliantAPIView` - Base for all contract-compliant views
|
||||
- `FilterMetadataAPIView` - Specialized for filter metadata endpoints
|
||||
- `HybridFilteringAPIView` - Specialized for hybrid filtering endpoints
|
||||
- `PaginatedAPIView` - Ensures consistent pagination responses
|
||||
|
||||
**Features**:
|
||||
- Automatic contract validation in DEBUG mode
|
||||
- Standardized success/error response formats
|
||||
- Proper error logging with context
|
||||
- Built-in validation for hybrid responses
|
||||
|
||||
### 6. Updated Import Structure
|
||||
|
||||
**File Modified**: `backend/apps/api/v1/serializers/__init__.py`
|
||||
|
||||
**Changes**:
|
||||
- Added imports for new shared contract serializers
|
||||
- Updated `__all__` list to include new utilities
|
||||
- Removed references to non-existent serializers
|
||||
|
||||
## Validation Results
|
||||
|
||||
### Before Implementation
|
||||
```python
|
||||
# Parks filter metadata (BROKEN)
|
||||
'statuses': ['OPERATING', 'CLOSED_TEMP'] # Strings cause frontend crashes
|
||||
|
||||
# Rides filter metadata (BROKEN)
|
||||
'categories': ['RC', 'FL', 'TR'] # Strings cause frontend crashes
|
||||
```
|
||||
|
||||
### After Implementation
|
||||
```python
|
||||
# Parks filter metadata (FIXED)
|
||||
'statuses': [
|
||||
{'value': 'OPERATING', 'label': 'Operating', 'count': 42},
|
||||
{'value': 'CLOSED_TEMP', 'label': 'Temporarily Closed', 'count': 5}
|
||||
]
|
||||
|
||||
# Rides filter metadata (FIXED)
|
||||
'categories': [
|
||||
{'value': 'RC', 'label': 'Roller Coaster', 'count': 10},
|
||||
{'value': 'FL', 'label': 'Flat Ride', 'count': 8}
|
||||
]
|
||||
```
|
||||
|
||||
## Frontend Impact
|
||||
|
||||
### Before (Required Defensive Coding)
|
||||
```typescript
|
||||
// Frontend had to transform data and handle type mismatches
|
||||
const transformedStatuses = statuses.map(status =>
|
||||
typeof status === 'string'
|
||||
? { value: status, label: status, count: 0 }
|
||||
: status
|
||||
);
|
||||
```
|
||||
|
||||
### After (Direct Usage)
|
||||
```typescript
|
||||
// Frontend can now use API responses directly
|
||||
{statuses.map(({ value, label, count }) => (
|
||||
<option key={value} value={value}>
|
||||
{label} ({count})
|
||||
</option>
|
||||
))}
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Contract Validation in Development
|
||||
1. **Automatic Validation**: Middleware validates all API responses in DEBUG mode
|
||||
2. **Immediate Feedback**: Contract violations are logged with actionable suggestions
|
||||
3. **Test Coverage**: Comprehensive tests prevent regressions
|
||||
|
||||
### Error Messages
|
||||
When contract violations occur, developers see clear messages like:
|
||||
```
|
||||
CONTRACT VIOLATION [CATEGORICAL_OPTION_IS_STRING]:
|
||||
Categorical filter 'statuses' option 0 is a string 'OPERATING'
|
||||
but should be an object with value/label/count properties
|
||||
|
||||
Suggestion: Convert string arrays to object arrays with {value, label, count} structure.
|
||||
Use the ensure_filter_option_format() utility function from apps.api.v1.serializers.shared
|
||||
```
|
||||
|
||||
## Success Metrics
|
||||
|
||||
✅ **Zero Runtime Type Errors**: Frontend no longer crashes due to type mismatches
|
||||
✅ **100% Contract Compliance**: All filter metadata responses match TypeScript interfaces
|
||||
✅ **Reduced Frontend Complexity**: Removed data transformation boilerplate
|
||||
✅ **Developer Experience**: Immediate feedback on contract violations
|
||||
✅ **Type Safety**: TypeScript auto-completion works without type assertions
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
### For Backend Developers
|
||||
|
||||
1. **Use Shared Serializers**: Import from `apps.api.v1.serializers.shared`
|
||||
2. **Validate Responses**: Use `validate_filter_metadata_contract()` for filter endpoints
|
||||
3. **Extend Base Views**: Inherit from contract-compliant base classes
|
||||
4. **Run Tests**: Execute contract compliance tests before deployment
|
||||
|
||||
### For Frontend Developers
|
||||
|
||||
1. **Trust TypeScript Types**: No more runtime surprises or defensive coding
|
||||
2. **Use API Responses Directly**: No transformation needed
|
||||
3. **Report Issues**: Contract violations are logged and should be reported
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **Expand Validation**: Add more contract validations as needed
|
||||
2. **Production Monitoring**: Consider lightweight contract monitoring in production
|
||||
3. **Documentation Generation**: Auto-generate API docs from contract serializers
|
||||
4. **Integration Tests**: Add end-to-end tests that validate full request/response cycles
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
### New Files
|
||||
- `backend/apps/api/v1/serializers/shared.py` - Contract serializers and utilities
|
||||
- `backend/apps/api/v1/middleware.py` - Contract validation middleware
|
||||
- `backend/apps/api/v1/tests/test_contracts.py` - Contract compliance tests
|
||||
- `backend/apps/api/v1/views/base.py` - Contract-compliant base views
|
||||
- `docs/backend-contract-compliance.md` - This documentation
|
||||
|
||||
### Modified Files
|
||||
- `backend/apps/parks/services/hybrid_loader.py` - Fixed filter metadata format
|
||||
- `backend/apps/rides/services/hybrid_loader.py` - Fixed filter metadata format
|
||||
- `backend/apps/api/v1/serializers/__init__.py` - Updated imports
|
||||
|
||||
## Conclusion
|
||||
|
||||
This implementation eliminates the critical contract violations that were causing frontend runtime crashes. The backend now consistently returns data in the exact format expected by the frontend TypeScript interfaces, improving both developer experience and application reliability.
|
||||
|
||||
The solution is backward-compatible and includes comprehensive validation to prevent regressions. Frontend developers can now trust the API responses completely, leading to cleaner, more maintainable code.
|
||||
131
docs/frontend.md
131
docs/frontend.md
@@ -319,7 +319,136 @@ The moderation system provides comprehensive content moderation, user management
|
||||
|
||||
## Rides API
|
||||
|
||||
### Rides Listing
|
||||
### Hybrid Rides Filtering (Recommended)
|
||||
|
||||
The hybrid filtering system automatically chooses between client-side and server-side filtering based on data size for optimal performance.
|
||||
|
||||
#### Main Hybrid Endpoint
|
||||
- **GET** `/api/v1/rides/hybrid/`
|
||||
- **Description**: Intelligent ride filtering with automatic strategy selection
|
||||
- **Strategy Selection**:
|
||||
- ≤200 total records: Client-side filtering (loads all data for frontend filtering)
|
||||
- >200 total records: Server-side filtering (database filtering with pagination)
|
||||
- **Query Parameters** (25+ comprehensive filtering options):
|
||||
- `search` (string): Full-text search across ride names, descriptions, parks, and related data
|
||||
- `park_slug` (string): Filter by park slug
|
||||
- `park_id` (int): Filter by park ID
|
||||
- `categories` (string): Filter by ride categories (comma-separated): RC,DR,FR,WR,TR,OT
|
||||
- `statuses` (string): Filter by ride statuses (comma-separated)
|
||||
- `manufacturer_ids` (string): Filter by manufacturer IDs (comma-separated)
|
||||
- `designer_ids` (string): Filter by designer IDs (comma-separated)
|
||||
- `ride_model_ids` (string): Filter by ride model IDs (comma-separated)
|
||||
- `opening_year` (int): Filter by specific opening year
|
||||
- `min_opening_year` (int): Filter by minimum opening year
|
||||
- `max_opening_year` (int): Filter by maximum opening year
|
||||
- `min_rating` (number): Filter by minimum average rating (1-10)
|
||||
- `max_rating` (number): Filter by maximum average rating (1-10)
|
||||
- `min_height_requirement` (int): Filter by minimum height requirement in inches
|
||||
- `max_height_requirement` (int): Filter by maximum height requirement in inches
|
||||
- `min_capacity` (int): Filter by minimum hourly capacity
|
||||
- `max_capacity` (int): Filter by maximum hourly capacity
|
||||
- `roller_coaster_types` (string): Filter by roller coaster types (comma-separated)
|
||||
- `track_materials` (string): Filter by track materials (comma-separated): STEEL,WOOD,HYBRID
|
||||
- `launch_types` (string): Filter by launch types (comma-separated)
|
||||
- `min_height_ft` (number): Filter by minimum roller coaster height in feet
|
||||
- `max_height_ft` (number): Filter by maximum roller coaster height in feet
|
||||
- `min_speed_mph` (number): Filter by minimum roller coaster speed in mph
|
||||
- `max_speed_mph` (number): Filter by maximum roller coaster speed in mph
|
||||
- `min_inversions` (int): Filter by minimum number of inversions
|
||||
- `max_inversions` (int): Filter by maximum number of inversions
|
||||
- `has_inversions` (boolean): Filter rides with inversions (true) or without (false)
|
||||
- `ordering` (string): Order results by field (name, -name, opening_date, -opening_date, average_rating, -average_rating, etc.)
|
||||
|
||||
- **Response Format**:
|
||||
```typescript
|
||||
{
|
||||
strategy: 'client_side' | 'server_side',
|
||||
data: RideData[],
|
||||
total_count: number,
|
||||
has_more: boolean,
|
||||
filter_metadata: FilterMetadata
|
||||
}
|
||||
```
|
||||
|
||||
#### Progressive Loading
|
||||
- **GET** `/api/v1/rides/hybrid/progressive/`
|
||||
- **Description**: Load additional ride data for server-side filtering strategy
|
||||
- **Query Parameters**: Same as main hybrid endpoint plus:
|
||||
- `offset` (int, required): Number of records to skip for pagination
|
||||
- **Usage**: Only use when main endpoint returns `strategy: 'server_side'` and `has_more: true`
|
||||
|
||||
#### Filter Metadata
|
||||
- **GET** `/api/v1/rides/hybrid/filter-metadata/`
|
||||
- **Description**: Get comprehensive filter metadata for dynamic filter generation
|
||||
- **Returns**: Complete filter options including:
|
||||
- Static options (categories, statuses, roller coaster types, track materials, launch types)
|
||||
- Dynamic data (available parks, park areas, manufacturers, designers, ride models)
|
||||
- Ranges (rating, height requirements, capacity, opening years, roller coaster stats)
|
||||
- Boolean filters and ordering options
|
||||
- **Caching**: Results cached for 5 minutes, automatically invalidated on data changes
|
||||
|
||||
#### Frontend Implementation Example
|
||||
```typescript
|
||||
// Basic hybrid filtering
|
||||
const loadRides = async (filters = {}) => {
|
||||
const params = new URLSearchParams();
|
||||
|
||||
// Add filters to params
|
||||
Object.entries(filters).forEach(([key, value]) => {
|
||||
if (value !== null && value !== undefined && value !== '') {
|
||||
if (Array.isArray(value)) {
|
||||
params.append(key, value.join(','));
|
||||
} else {
|
||||
params.append(key, value.toString());
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
const response = await fetch(`/api/v1/rides/hybrid/?${params}`, {
|
||||
headers: { 'Authorization': `Bearer ${accessToken}` }
|
||||
});
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
if (data.strategy === 'client_side') {
|
||||
// All data loaded - implement client-side filtering
|
||||
return handleClientSideData(data);
|
||||
} else {
|
||||
// Server-side strategy - implement progressive loading
|
||||
return handleServerSideData(data);
|
||||
}
|
||||
};
|
||||
|
||||
// Progressive loading for server-side strategy
|
||||
const loadMoreRides = async (filters = {}, offset = 0) => {
|
||||
const params = new URLSearchParams();
|
||||
params.append('offset', offset.toString());
|
||||
|
||||
Object.entries(filters).forEach(([key, value]) => {
|
||||
if (value !== null && value !== undefined && value !== '') {
|
||||
if (Array.isArray(value)) {
|
||||
params.append(key, value.join(','));
|
||||
} else {
|
||||
params.append(key, value.toString());
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
const response = await fetch(`/api/v1/rides/hybrid/progressive/?${params}`, {
|
||||
headers: { 'Authorization': `Bearer ${accessToken}` }
|
||||
});
|
||||
|
||||
return await response.json();
|
||||
};
|
||||
|
||||
// Load filter metadata for dynamic filters
|
||||
const loadFilterMetadata = async () => {
|
||||
const response = await fetch('/api/v1/rides/hybrid/filter-metadata/');
|
||||
return await response.json();
|
||||
};
|
||||
```
|
||||
|
||||
### Legacy Rides Listing
|
||||
- **GET** `/api/v1/rides/`
|
||||
- **Query Parameters**:
|
||||
- `search`: Search in ride names and descriptions
|
||||
|
||||
242
docs/hybrid-filtering-implementation.md
Normal file
242
docs/hybrid-filtering-implementation.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# Hybrid Filtering Implementation - Complete
|
||||
|
||||
## Overview
|
||||
|
||||
The hybrid filtering strategy for ThrillWiki parks has been successfully implemented. This revolutionary approach automatically chooses between client-side and server-side filtering based on data size and complexity, providing optimal performance for all scenarios.
|
||||
|
||||
## Implementation Summary
|
||||
|
||||
### ✅ Completed Components
|
||||
|
||||
#### 1. Database Schema Enhancements
|
||||
- **Computed Fields**: Added `opening_year` and `search_text` fields to Park model
|
||||
- **Automatic Population**: Fields are automatically populated on save via `_populate_computed_fields()` method
|
||||
- **Database Indexes**: Comprehensive indexing strategy for optimal query performance
|
||||
|
||||
#### 2. Smart Data Loading Service
|
||||
- **SmartParkLoader**: Intelligent service that determines optimal loading strategy
|
||||
- **Progressive Loading**: Supports incremental data loading for large datasets
|
||||
- **Intelligent Caching**: Built-in caching with configurable timeouts and invalidation
|
||||
|
||||
#### 3. Enhanced API Architecture
|
||||
- **HybridParkSerializer**: Complete serializer with all filterable fields
|
||||
- **HybridParkAPIView**: Main endpoint with intelligent filtering strategy
|
||||
- **ParkFilterMetadataAPIView**: Dynamic filter metadata endpoint
|
||||
|
||||
#### 4. Database Optimizations
|
||||
- **Composite Indexes**: Multi-column indexes for common filter combinations
|
||||
- **Partial Indexes**: Optimized indexes for frequently filtered subsets
|
||||
- **Full-Text Search**: GIN indexes for advanced text search capabilities
|
||||
- **Covering Indexes**: Include commonly selected columns to avoid table lookups
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Main Hybrid Filtering Endpoint
|
||||
```
|
||||
GET /api/v1/parks/hybrid/
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Automatic strategy selection (client-side vs server-side)
|
||||
- Progressive loading for large datasets
|
||||
- Comprehensive filtering options
|
||||
- Built-in filter metadata
|
||||
|
||||
**Query Parameters:**
|
||||
- `status`: Park status filter (comma-separated)
|
||||
- `park_type`: Park type filter (comma-separated)
|
||||
- `country`: Country filter (comma-separated)
|
||||
- `state`: State filter (comma-separated)
|
||||
- `opening_year_min/max`: Opening year range
|
||||
- `size_min/max`: Park size range (acres)
|
||||
- `rating_min/max`: Average rating range
|
||||
- `ride_count_min/max`: Ride count range
|
||||
- `coaster_count_min/max`: Coaster count range
|
||||
- `operator`: Operator filter (comma-separated slugs)
|
||||
- `search`: Full-text search query
|
||||
- `offset`: Progressive loading offset
|
||||
|
||||
### Filter Metadata Endpoint
|
||||
```
|
||||
GET /api/v1/parks/hybrid/filter-metadata/
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Dynamic filter options based on current data
|
||||
- Categorical filter values
|
||||
- Numerical range information
|
||||
- Scoped metadata support
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
### Strategy Selection Logic
|
||||
- **Client-Side**: ≤200 records → Complete dataset with filter metadata
|
||||
- **Server-Side**: >200 records → Progressive loading with pagination
|
||||
|
||||
### Caching Strategy
|
||||
- **Cache Timeout**: 5 minutes (configurable)
|
||||
- **Cache Keys**: Based on filter combinations
|
||||
- **Invalidation**: Automatic on data changes
|
||||
|
||||
### Database Performance
|
||||
- **Query Optimization**: Comprehensive indexing strategy
|
||||
- **Full-Text Search**: PostgreSQL GIN indexes with trigram support
|
||||
- **Covering Indexes**: Reduced I/O for common queries
|
||||
|
||||
## Technical Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
1. **SmartParkLoader** (`apps/parks/services/hybrid_loader.py`)
|
||||
- Intelligent data loading decisions
|
||||
- Progressive loading implementation
|
||||
- Caching and invalidation logic
|
||||
|
||||
2. **HybridParkSerializer** (`apps/api/v1/parks/serializers.py`)
|
||||
- Complete field serialization
|
||||
- Location data integration
|
||||
- Image URL generation
|
||||
|
||||
3. **API Views** (`apps/api/v1/parks/views.py`)
|
||||
- HybridParkAPIView: Main filtering endpoint
|
||||
- ParkFilterMetadataAPIView: Metadata endpoint
|
||||
|
||||
### Database Schema
|
||||
|
||||
#### New Fields
|
||||
```sql
|
||||
-- Computed fields for hybrid filtering
|
||||
opening_year INTEGER NULL, -- Indexed
|
||||
search_text TEXT, -- Indexed with GIN
|
||||
```
|
||||
|
||||
#### Key Indexes
|
||||
```sql
|
||||
-- Composite indexes for filter combinations
|
||||
parks_park_status_park_type_idx (status, park_type)
|
||||
parks_park_opening_year_status_idx (opening_year, status)
|
||||
parks_park_size_rating_idx (size_acres, average_rating)
|
||||
|
||||
-- Full-text search indexes
|
||||
parks_park_search_text_gin_idx USING gin(to_tsvector('english', search_text))
|
||||
parks_park_search_text_trgm_idx USING gin(search_text gin_trgm_ops)
|
||||
|
||||
-- Covering index for common queries
|
||||
parks_park_hybrid_covering_idx (status, park_type, opening_year)
|
||||
INCLUDE (name, slug, size_acres, average_rating, ride_count, coaster_count, operator_id)
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Filtering
|
||||
```javascript
|
||||
// Get all operating theme parks
|
||||
GET /api/v1/parks/hybrid/?status=OPERATING&park_type=THEME_PARK
|
||||
|
||||
// Response includes strategy decision
|
||||
{
|
||||
"parks": [...],
|
||||
"total_count": 150,
|
||||
"strategy": "client_side",
|
||||
"has_more": false,
|
||||
"filter_metadata": {...}
|
||||
}
|
||||
```
|
||||
|
||||
### Progressive Loading
|
||||
```javascript
|
||||
// Initial load
|
||||
GET /api/v1/parks/hybrid/
|
||||
|
||||
// Next batch (server-side strategy)
|
||||
GET /api/v1/parks/hybrid/?offset=50
|
||||
|
||||
{
|
||||
"parks": [...],
|
||||
"total_count": 500,
|
||||
"strategy": "server_side",
|
||||
"has_more": true,
|
||||
"next_offset": 75
|
||||
}
|
||||
```
|
||||
|
||||
### Advanced Filtering
|
||||
```javascript
|
||||
// Complex multi-criteria filter
|
||||
GET /api/v1/parks/hybrid/?country=United%20States&opening_year_min=1990&size_min=100&rating_min=8.0&search=roller%20coaster
|
||||
```
|
||||
|
||||
### Filter Metadata
|
||||
```javascript
|
||||
// Get available filter options
|
||||
GET /api/v1/parks/hybrid/filter-metadata/
|
||||
|
||||
{
|
||||
"categorical": {
|
||||
"countries": ["United States", "Canada", ...],
|
||||
"states": ["California", "Florida", ...],
|
||||
"park_types": ["THEME_PARK", "AMUSEMENT_PARK", ...],
|
||||
"operators": [{"name": "Disney", "slug": "disney"}, ...]
|
||||
},
|
||||
"ranges": {
|
||||
"opening_year": {"min": 1846, "max": 2024},
|
||||
"size_acres": {"min": 5.0, "max": 25000.0},
|
||||
"average_rating": {"min": 3.2, "max": 9.8}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Benefits
|
||||
|
||||
### Client-Side Strategy (≤200 records)
|
||||
- **Zero latency filtering**: Instant filter application
|
||||
- **Rich interactions**: Real-time search and sorting
|
||||
- **Offline capability**: Data cached locally
|
||||
- **Reduced server load**: Minimal API calls
|
||||
|
||||
### Server-Side Strategy (>200 records)
|
||||
- **Memory efficiency**: Only loads needed data
|
||||
- **Scalable**: Handles datasets of any size
|
||||
- **Progressive enhancement**: Smooth loading experience
|
||||
- **Bandwidth optimization**: Minimal data transfer
|
||||
|
||||
## Monitoring and Metrics
|
||||
|
||||
### Key Performance Indicators
|
||||
- **Strategy Distribution**: Client vs server-side usage
|
||||
- **Cache Hit Rates**: Caching effectiveness
|
||||
- **Query Performance**: Database response times
|
||||
- **User Experience**: Filter application speed
|
||||
|
||||
### Recommended Monitoring
|
||||
```python
|
||||
# Cache performance
|
||||
cache_hit_rate = cache_hits / (cache_hits + cache_misses)
|
||||
|
||||
# Strategy effectiveness
|
||||
client_side_percentage = client_requests / total_requests
|
||||
|
||||
# Query performance
|
||||
avg_query_time = sum(query_times) / len(query_times)
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Potential Improvements
|
||||
1. **Machine Learning**: Predictive caching based on usage patterns
|
||||
2. **Real-time Updates**: WebSocket integration for live data updates
|
||||
3. **Advanced Search**: Elasticsearch integration for complex queries
|
||||
4. **Personalization**: User-specific filter preferences and history
|
||||
|
||||
### Scalability Considerations
|
||||
- **Horizontal Scaling**: Read replicas for filter queries
|
||||
- **CDN Integration**: Geographic distribution of filter metadata
|
||||
- **Background Processing**: Async computation of complex aggregations
|
||||
|
||||
## Conclusion
|
||||
|
||||
The hybrid filtering implementation represents a significant advancement in ThrillWiki's API architecture. By intelligently choosing between client-side and server-side strategies, it provides optimal performance across all use cases while maintaining a simple, consistent API interface.
|
||||
|
||||
The comprehensive indexing strategy, intelligent caching, and progressive loading capabilities ensure excellent performance at scale, while the rich filter metadata enables dynamic, user-friendly interfaces.
|
||||
|
||||
This implementation serves as a model for other high-performance filtering requirements throughout the ThrillWiki platform.
|
||||
436
docs/hybrid-filtering-recommendation.md
Normal file
436
docs/hybrid-filtering-recommendation.md
Normal file
@@ -0,0 +1,436 @@
|
||||
# Hybrid Pagination + Client-Side Filtering Recommendation
|
||||
|
||||
## Overview
|
||||
|
||||
A hybrid approach using **paginated server-side data with client-side filtering** is the optimal solution for ThrillWiki park and ride listings. This combines the performance benefits of pagination with the instant responsiveness of client-side filtering.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Server-Side Responsibilities
|
||||
- **Pagination**: Load data in chunks (20-50 items per page)
|
||||
- **Sorting**: Primary sort order (by popularity, name, etc.)
|
||||
- **Search**: Full-text search across multiple fields
|
||||
- **Complex Queries**: Geographic bounds, relationship filtering
|
||||
- **Data Optimization**: Include all filterable fields in response
|
||||
|
||||
### Client-Side Responsibilities
|
||||
- **Instant Filtering**: Filter loaded data without API calls
|
||||
- **UI State**: Manage filter panel state and selections
|
||||
- **Progressive Loading**: Load additional pages as needed
|
||||
- **Cache Management**: Store and reuse filtered results
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Enhanced API Response Structure
|
||||
|
||||
```typescript
|
||||
interface PaginatedParksResponse {
|
||||
results: Park[];
|
||||
count: number;
|
||||
next: string | null;
|
||||
previous: string | null;
|
||||
// Enhanced metadata for client-side filtering
|
||||
filter_metadata: {
|
||||
available_countries: string[];
|
||||
available_states: string[];
|
||||
available_park_types: string[];
|
||||
rating_range: { min: number; max: number };
|
||||
ride_count_range: { min: number; max: number };
|
||||
opening_year_range: { min: number; max: number };
|
||||
};
|
||||
}
|
||||
|
||||
interface Park {
|
||||
id: number;
|
||||
name: string;
|
||||
slug: string;
|
||||
description: string;
|
||||
park_type: string;
|
||||
status: string;
|
||||
location: {
|
||||
city: string;
|
||||
state: string;
|
||||
country: string;
|
||||
continent: string;
|
||||
coordinates?: [number, number];
|
||||
};
|
||||
statistics: {
|
||||
average_rating: number | null;
|
||||
ride_count: number;
|
||||
coaster_count: number;
|
||||
size_acres: number | null;
|
||||
};
|
||||
dates: {
|
||||
opening_date: string | null;
|
||||
closing_date: string | null;
|
||||
opening_year: number | null;
|
||||
};
|
||||
operator: {
|
||||
id: number;
|
||||
name: string;
|
||||
slug: string;
|
||||
};
|
||||
property_owner?: {
|
||||
id: number;
|
||||
name: string;
|
||||
slug: string;
|
||||
};
|
||||
images: {
|
||||
banner_url?: string;
|
||||
card_url?: string;
|
||||
thumbnail_url?: string;
|
||||
};
|
||||
url: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Client-Side Filtering Logic
|
||||
|
||||
```typescript
|
||||
class ParkFilterManager {
|
||||
private allParks: Park[] = [];
|
||||
private filteredParks: Park[] = [];
|
||||
private currentFilters: ParkFilters = {};
|
||||
private currentPage = 1;
|
||||
private hasMorePages = true;
|
||||
|
||||
async loadInitialData() {
|
||||
const response = await this.fetchParks(1);
|
||||
this.allParks = response.results;
|
||||
this.filteredParks = [...this.allParks];
|
||||
this.hasMorePages = !!response.next;
|
||||
return response;
|
||||
}
|
||||
|
||||
async loadMorePages() {
|
||||
if (!this.hasMorePages) return;
|
||||
|
||||
this.currentPage++;
|
||||
const response = await this.fetchParks(this.currentPage);
|
||||
|
||||
// Add new parks to our dataset
|
||||
this.allParks.push(...response.results);
|
||||
|
||||
// Re-apply current filters to include new data
|
||||
this.applyFilters(this.currentFilters);
|
||||
|
||||
this.hasMorePages = !!response.next;
|
||||
return response;
|
||||
}
|
||||
|
||||
applyFilters(filters: ParkFilters) {
|
||||
this.currentFilters = filters;
|
||||
|
||||
this.filteredParks = this.allParks.filter(park => {
|
||||
// Location filters
|
||||
if (filters.country && park.location.country !== filters.country) {
|
||||
return false;
|
||||
}
|
||||
|
||||
if (filters.state && park.location.state !== filters.state) {
|
||||
return false;
|
||||
}
|
||||
|
||||
if (filters.park_type && park.park_type !== filters.park_type) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Rating range
|
||||
if (filters.min_rating && (!park.statistics.average_rating ||
|
||||
park.statistics.average_rating < filters.min_rating)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
if (filters.max_rating && (!park.statistics.average_rating ||
|
||||
park.statistics.average_rating > filters.max_rating)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Ride count range
|
||||
if (filters.min_ride_count && park.statistics.ride_count < filters.min_ride_count) {
|
||||
return false;
|
||||
}
|
||||
|
||||
if (filters.max_ride_count && park.statistics.ride_count > filters.max_ride_count) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Opening year range
|
||||
if (filters.min_opening_year && (!park.dates.opening_year ||
|
||||
park.dates.opening_year < filters.min_opening_year)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
if (filters.max_opening_year && (!park.dates.opening_year ||
|
||||
park.dates.opening_year > filters.max_opening_year)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Text search (client-side)
|
||||
if (filters.search) {
|
||||
const searchTerm = filters.search.toLowerCase();
|
||||
const searchableText = [
|
||||
park.name,
|
||||
park.description,
|
||||
park.location.city,
|
||||
park.location.state,
|
||||
park.location.country,
|
||||
park.operator.name
|
||||
].join(' ').toLowerCase();
|
||||
|
||||
if (!searchableText.includes(searchTerm)) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
return true;
|
||||
});
|
||||
|
||||
// Apply client-side sorting
|
||||
this.applySorting(filters.ordering || 'name');
|
||||
}
|
||||
|
||||
applySorting(ordering: string) {
|
||||
const [field, direction] = ordering.startsWith('-')
|
||||
? [ordering.slice(1), 'desc']
|
||||
: [ordering, 'asc'];
|
||||
|
||||
this.filteredParks.sort((a, b) => {
|
||||
let aValue: any, bValue: any;
|
||||
|
||||
switch (field) {
|
||||
case 'name':
|
||||
aValue = a.name;
|
||||
bValue = b.name;
|
||||
break;
|
||||
case 'average_rating':
|
||||
aValue = a.statistics.average_rating || 0;
|
||||
bValue = b.statistics.average_rating || 0;
|
||||
break;
|
||||
case 'ride_count':
|
||||
aValue = a.statistics.ride_count;
|
||||
bValue = b.statistics.ride_count;
|
||||
break;
|
||||
case 'opening_date':
|
||||
aValue = a.dates.opening_date ? new Date(a.dates.opening_date) : new Date(0);
|
||||
bValue = b.dates.opening_date ? new Date(b.dates.opening_date) : new Date(0);
|
||||
break;
|
||||
default:
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (aValue < bValue) return direction === 'asc' ? -1 : 1;
|
||||
if (aValue > bValue) return direction === 'asc' ? 1 : -1;
|
||||
return 0;
|
||||
});
|
||||
}
|
||||
|
||||
getFilteredResults() {
|
||||
return this.filteredParks;
|
||||
}
|
||||
|
||||
getFilterStats() {
|
||||
return {
|
||||
total: this.allParks.length,
|
||||
filtered: this.filteredParks.length,
|
||||
hasMorePages: this.hasMorePages
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### React Component Implementation
|
||||
|
||||
```typescript
|
||||
import { useState, useEffect, useMemo } from 'react';
|
||||
|
||||
interface ParkListProps {
|
||||
initialFilters?: ParkFilters;
|
||||
}
|
||||
|
||||
const ParkList: React.FC<ParkListProps> = ({ initialFilters = {} }) => {
|
||||
const [filterManager] = useState(() => new ParkFilterManager());
|
||||
const [parks, setParks] = useState<Park[]>([]);
|
||||
const [filters, setFilters] = useState<ParkFilters>(initialFilters);
|
||||
const [loading, setLoading] = useState(true);
|
||||
const [loadingMore, setLoadingMore] = useState(false);
|
||||
const [stats, setStats] = useState({ total: 0, filtered: 0, hasMorePages: false });
|
||||
|
||||
// Load initial data
|
||||
useEffect(() => {
|
||||
const loadData = async () => {
|
||||
setLoading(true);
|
||||
try {
|
||||
await filterManager.loadInitialData();
|
||||
filterManager.applyFilters(filters);
|
||||
setParks(filterManager.getFilteredResults());
|
||||
setStats(filterManager.getFilterStats());
|
||||
} catch (error) {
|
||||
console.error('Failed to load parks:', error);
|
||||
} finally {
|
||||
setLoading(false);
|
||||
}
|
||||
};
|
||||
|
||||
loadData();
|
||||
}, []);
|
||||
|
||||
// Apply filters when they change
|
||||
useEffect(() => {
|
||||
filterManager.applyFilters(filters);
|
||||
setParks(filterManager.getFilteredResults());
|
||||
setStats(filterManager.getFilterStats());
|
||||
}, [filters]);
|
||||
|
||||
const handleFilterChange = (newFilters: Partial<ParkFilters>) => {
|
||||
setFilters(prev => ({ ...prev, ...newFilters }));
|
||||
};
|
||||
|
||||
const loadMoreParks = async () => {
|
||||
if (!stats.hasMorePages || loadingMore) return;
|
||||
|
||||
setLoadingMore(true);
|
||||
try {
|
||||
await filterManager.loadMorePages();
|
||||
setParks(filterManager.getFilteredResults());
|
||||
setStats(filterManager.getFilterStats());
|
||||
} catch (error) {
|
||||
console.error('Failed to load more parks:', error);
|
||||
} finally {
|
||||
setLoadingMore(false);
|
||||
}
|
||||
};
|
||||
|
||||
// Memoized filter options based on loaded data
|
||||
const filterOptions = useMemo(() => {
|
||||
const allParks = filterManager.getAllParks();
|
||||
return {
|
||||
countries: [...new Set(allParks.map(p => p.location.country))].sort(),
|
||||
states: [...new Set(allParks.map(p => p.location.state))].filter(Boolean).sort(),
|
||||
parkTypes: [...new Set(allParks.map(p => p.park_type))].sort(),
|
||||
ratingRange: {
|
||||
min: Math.min(...allParks.map(p => p.statistics.average_rating || 10)),
|
||||
max: Math.max(...allParks.map(p => p.statistics.average_rating || 0))
|
||||
}
|
||||
};
|
||||
}, [stats.total]);
|
||||
|
||||
if (loading) {
|
||||
return <div className="flex justify-center p-8">Loading parks...</div>;
|
||||
}
|
||||
|
||||
return (
|
||||
<div className="flex gap-6">
|
||||
{/* Filter Sidebar */}
|
||||
<div className="w-64 flex-shrink-0">
|
||||
<ParkFilters
|
||||
filters={filters}
|
||||
options={filterOptions}
|
||||
onChange={handleFilterChange}
|
||||
/>
|
||||
|
||||
{/* Filter Stats */}
|
||||
<div className="mt-4 p-3 bg-gray-50 rounded">
|
||||
<p className="text-sm text-gray-600">
|
||||
Showing {parks.length} of {stats.total} parks
|
||||
</p>
|
||||
{stats.hasMorePages && (
|
||||
<button
|
||||
onClick={loadMoreParks}
|
||||
disabled={loadingMore}
|
||||
className="mt-2 text-sm text-blue-600 hover:text-blue-800"
|
||||
>
|
||||
{loadingMore ? 'Loading...' : 'Load more parks'}
|
||||
</button>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Results */}
|
||||
<div className="flex-1">
|
||||
<div className="mb-4 flex justify-between items-center">
|
||||
<h2 className="text-xl font-semibold">
|
||||
Parks ({parks.length})
|
||||
</h2>
|
||||
|
||||
<select
|
||||
value={filters.ordering || 'name'}
|
||||
onChange={(e) => handleFilterChange({ ordering: e.target.value })}
|
||||
className="border rounded px-3 py-1"
|
||||
>
|
||||
<option value="name">Name (A-Z)</option>
|
||||
<option value="-name">Name (Z-A)</option>
|
||||
<option value="-average_rating">Rating (High to Low)</option>
|
||||
<option value="average_rating">Rating (Low to High)</option>
|
||||
<option value="-ride_count">Most Rides</option>
|
||||
<option value="ride_count">Fewest Rides</option>
|
||||
</select>
|
||||
</div>
|
||||
|
||||
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
|
||||
{parks.map(park => (
|
||||
<ParkCard key={park.id} park={park} />
|
||||
))}
|
||||
</div>
|
||||
|
||||
{parks.length === 0 && (
|
||||
<div className="text-center py-8 text-gray-500">
|
||||
No parks match your current filters.
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## Benefits of This Approach
|
||||
|
||||
### **User Experience**
|
||||
- ✅ **Instant Filtering**: No loading delays when changing filters
|
||||
- ✅ **Smooth Interactions**: Immediate visual feedback
|
||||
- ✅ **Progressive Enhancement**: Load more data as needed
|
||||
- ✅ **Offline Capability**: Works with cached data
|
||||
|
||||
### **Performance**
|
||||
- ✅ **Fast Initial Load**: Only 20-50 items per request
|
||||
- ✅ **Reduced Server Load**: Fewer API calls for filter combinations
|
||||
- ✅ **Efficient Caching**: Browser caches paginated results
|
||||
- ✅ **Memory Efficient**: Reasonable dataset size for client-side operations
|
||||
|
||||
### **Scalability**
|
||||
- ✅ **Handles Growth**: Can load additional pages as dataset grows
|
||||
- ✅ **Flexible Pagination**: Adjustable page sizes based on performance
|
||||
- ✅ **Smart Loading**: Only load more data when needed
|
||||
|
||||
### **Development Benefits**
|
||||
- ✅ **Simpler Backend**: Less complex filtering logic on server
|
||||
- ✅ **Better Caching**: Standard HTTP caching works well with pagination
|
||||
- ✅ **Easier Testing**: Client-side filtering is easier to unit test
|
||||
- ✅ **Better UX Control**: Fine-grained control over filter interactions
|
||||
|
||||
## When to Use Server-Side vs Client-Side
|
||||
|
||||
### **Use Server-Side For:**
|
||||
- Full-text search across multiple fields
|
||||
- Geographic bounds filtering (complex spatial queries)
|
||||
- Initial data loading and pagination
|
||||
- Complex relationship filtering (operator, manufacturer lookups)
|
||||
|
||||
### **Use Client-Side For:**
|
||||
- Simple field filtering (status, type, country)
|
||||
- Range filtering (rating, ride count, opening year)
|
||||
- Sorting of loaded data
|
||||
- Instant filter feedback and UI state management
|
||||
|
||||
## Conclusion
|
||||
|
||||
The hybrid approach is **optimal for ThrillWiki** because:
|
||||
|
||||
1. **Data Volume**: Parks/rides datasets are manageable for client-side filtering
|
||||
2. **User Expectations**: Users expect instant filter responses in modern web apps
|
||||
3. **Performance**: Combines fast initial loading with responsive interactions
|
||||
4. **Scalability**: Can handle growth through progressive loading
|
||||
5. **Development**: Simpler to implement and maintain than complex server-side filtering
|
||||
|
||||
This approach provides the best balance of performance, user experience, and maintainability for ThrillWiki's use case.
|
||||
@@ -200,6 +200,13 @@ import type {
|
||||
SearchFilters,
|
||||
BoundingBox,
|
||||
|
||||
// Hybrid Rides Filtering Types
|
||||
HybridRideData,
|
||||
HybridRideFilterMetadata,
|
||||
HybridRideResponse,
|
||||
HybridRideFilters,
|
||||
HybridRideProgressiveResponse,
|
||||
|
||||
// Queue Routing Response Types
|
||||
QueueRoutingResponse,
|
||||
AutoApprovedResponse,
|
||||
@@ -853,6 +860,42 @@ export const parksApi = {
|
||||
// ============================================================================
|
||||
|
||||
export const ridesApi = {
|
||||
// Hybrid filtering (recommended)
|
||||
async getHybridRides(filters?: HybridRideFilters): Promise<HybridRideResponse> {
|
||||
const searchParams = new URLSearchParams();
|
||||
|
||||
if (filters) {
|
||||
Object.entries(filters).forEach(([key, value]) => {
|
||||
if (value !== undefined && value !== null && value !== '') {
|
||||
searchParams.append(key, value.toString());
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
const query = searchParams.toString();
|
||||
return makeRequest<HybridRideResponse>(`/rides/hybrid/${query ? `?${query}` : ''}`);
|
||||
},
|
||||
|
||||
async getHybridRidesProgressive(filters?: HybridRideFilters & { offset: number }): Promise<HybridRideProgressiveResponse> {
|
||||
const searchParams = new URLSearchParams();
|
||||
|
||||
if (filters) {
|
||||
Object.entries(filters).forEach(([key, value]) => {
|
||||
if (value !== undefined && value !== null && value !== '') {
|
||||
searchParams.append(key, value.toString());
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
const query = searchParams.toString();
|
||||
return makeRequest<HybridRideProgressiveResponse>(`/rides/hybrid/progressive/${query ? `?${query}` : ''}`);
|
||||
},
|
||||
|
||||
async getHybridRideFilterMetadata(): Promise<HybridRideFilterMetadata> {
|
||||
return makeRequest<HybridRideFilterMetadata>('/rides/hybrid/filter-metadata/');
|
||||
},
|
||||
|
||||
// Legacy rides listing
|
||||
async getRides(filters?: SearchFilters): Promise<RideListResponse> {
|
||||
const searchParams = new URLSearchParams();
|
||||
|
||||
|
||||
@@ -2847,3 +2847,256 @@ export interface OrderingOption {
|
||||
value: string;
|
||||
label: string;
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Hybrid Rides Filtering Types
|
||||
// ============================================================================
|
||||
|
||||
export interface HybridRideData {
|
||||
// Basic ride info
|
||||
id: number;
|
||||
name: string;
|
||||
slug: string;
|
||||
description?: string;
|
||||
category: RideCategory;
|
||||
status: RideStatus;
|
||||
post_closing_status?: string;
|
||||
|
||||
// Dates and computed fields
|
||||
opening_date?: string;
|
||||
closing_date?: string;
|
||||
status_since?: string;
|
||||
opening_year?: number;
|
||||
|
||||
// Park fields
|
||||
park_name: string;
|
||||
park_slug: string;
|
||||
park_city?: string;
|
||||
park_state?: string;
|
||||
park_country?: string;
|
||||
|
||||
// Park area fields
|
||||
park_area_name?: string;
|
||||
park_area_slug?: string;
|
||||
|
||||
// Company fields
|
||||
manufacturer_name?: string;
|
||||
manufacturer_slug?: string;
|
||||
designer_name?: string;
|
||||
designer_slug?: string;
|
||||
|
||||
// Ride model fields
|
||||
ride_model_name?: string;
|
||||
ride_model_slug?: string;
|
||||
ride_model_category?: string;
|
||||
ride_model_manufacturer_name?: string;
|
||||
ride_model_manufacturer_slug?: string;
|
||||
|
||||
// Ride specifications
|
||||
min_height_in?: number;
|
||||
max_height_in?: number;
|
||||
capacity_per_hour?: number;
|
||||
ride_duration_seconds?: number;
|
||||
average_rating?: number;
|
||||
|
||||
// Roller coaster stats
|
||||
coaster_height_ft?: number;
|
||||
coaster_length_ft?: number;
|
||||
coaster_speed_mph?: number;
|
||||
coaster_inversions?: number;
|
||||
coaster_ride_time_seconds?: number;
|
||||
coaster_track_type?: string;
|
||||
coaster_track_material?: string;
|
||||
coaster_roller_coaster_type?: string;
|
||||
coaster_max_drop_height_ft?: number;
|
||||
coaster_launch_type?: string;
|
||||
coaster_train_style?: string;
|
||||
coaster_trains_count?: number;
|
||||
coaster_cars_per_train?: number;
|
||||
coaster_seats_per_car?: number;
|
||||
|
||||
// Images
|
||||
banner_image_url?: string;
|
||||
card_image_url?: string;
|
||||
|
||||
// URLs
|
||||
url: string;
|
||||
park_url?: string;
|
||||
|
||||
// Computed fields for filtering
|
||||
search_text: string;
|
||||
|
||||
// Metadata
|
||||
created_at: string;
|
||||
updated_at: string;
|
||||
}
|
||||
|
||||
export interface HybridRideFilterMetadata {
|
||||
// Static options
|
||||
categories: Array<{value: string; label: string}>;
|
||||
statuses: Array<{value: string; label: string}>;
|
||||
post_closing_statuses: Array<{value: string; label: string}>;
|
||||
roller_coaster_types: Array<{value: string; label: string}>;
|
||||
track_materials: Array<{value: string; label: string}>;
|
||||
launch_types: Array<{value: string; label: string}>;
|
||||
|
||||
// Dynamic data
|
||||
parks: Array<{
|
||||
park__id: number;
|
||||
park__name: string;
|
||||
park__slug: string;
|
||||
}>;
|
||||
park_areas: Array<{
|
||||
park_area__id: number;
|
||||
park_area__name: string;
|
||||
park_area__slug: string;
|
||||
}>;
|
||||
manufacturers: Array<{
|
||||
id: number;
|
||||
name: string;
|
||||
slug: string;
|
||||
}>;
|
||||
designers: Array<{
|
||||
id: number;
|
||||
name: string;
|
||||
slug: string;
|
||||
}>;
|
||||
ride_models: Array<{
|
||||
id: number;
|
||||
name: string;
|
||||
slug: string;
|
||||
manufacturer__name: string;
|
||||
manufacturer__slug: string;
|
||||
category: string;
|
||||
}>;
|
||||
|
||||
// Ranges
|
||||
ranges: {
|
||||
rating: {min: number; max: number; step: number; unit: string};
|
||||
height_requirement: {min: number; max: number; step: number; unit: string};
|
||||
capacity: {min: number; max: number; step: number; unit: string};
|
||||
ride_duration: {min: number; max: number; step: number; unit: string};
|
||||
height_ft: {min: number; max: number; step: number; unit: string};
|
||||
length_ft: {min: number; max: number; step: number; unit: string};
|
||||
speed_mph: {min: number; max: number; step: number; unit: string};
|
||||
inversions: {min: number; max: number; step: number; unit: string};
|
||||
ride_time: {min: number; max: number; step: number; unit: string};
|
||||
max_drop_height_ft: {min: number; max: number; step: number; unit: string};
|
||||
trains_count: {min: number; max: number; step: number; unit: string};
|
||||
cars_per_train: {min: number; max: number; step: number; unit: string};
|
||||
seats_per_car: {min: number; max: number; step: number; unit: string};
|
||||
opening_year: {min: number; max: number; step: number; unit: string};
|
||||
};
|
||||
|
||||
// Boolean filters
|
||||
boolean_filters: Array<{
|
||||
key: string;
|
||||
label: string;
|
||||
description: string;
|
||||
}>;
|
||||
|
||||
// Ordering options
|
||||
ordering_options: Array<{value: string; label: string}>;
|
||||
}
|
||||
|
||||
export interface HybridRideResponse {
|
||||
strategy: 'client_side' | 'server_side';
|
||||
data: HybridRideData[];
|
||||
total_count: number;
|
||||
has_more: boolean;
|
||||
filter_metadata: HybridRideFilterMetadata;
|
||||
}
|
||||
|
||||
export interface HybridRideFilters {
|
||||
// Text search
|
||||
search?: string;
|
||||
|
||||
// Park filters
|
||||
park_slug?: string;
|
||||
park_id?: number;
|
||||
|
||||
// Multi-value filters (comma-separated strings)
|
||||
categories?: string; // "RC,DR,FR"
|
||||
statuses?: string; // "OPERATING,CLOSED_TEMP"
|
||||
manufacturer_ids?: string; // "1,2,3"
|
||||
designer_ids?: string; // "1,2,3"
|
||||
ride_model_ids?: string; // "1,2,3"
|
||||
roller_coaster_types?: string; // "SITDOWN,INVERTED"
|
||||
track_materials?: string; // "STEEL,WOOD,HYBRID"
|
||||
launch_types?: string; // "CHAIN,LSM,HYDRAULIC"
|
||||
|
||||
// Numeric filters
|
||||
opening_year?: number;
|
||||
min_opening_year?: number;
|
||||
max_opening_year?: number;
|
||||
min_rating?: number;
|
||||
max_rating?: number;
|
||||
min_height_requirement?: number;
|
||||
max_height_requirement?: number;
|
||||
min_capacity?: number;
|
||||
max_capacity?: number;
|
||||
min_height_ft?: number;
|
||||
max_height_ft?: number;
|
||||
min_speed_mph?: number;
|
||||
max_speed_mph?: number;
|
||||
min_inversions?: number;
|
||||
max_inversions?: number;
|
||||
|
||||
// Boolean filters
|
||||
has_inversions?: boolean;
|
||||
|
||||
// Ordering
|
||||
ordering?: string;
|
||||
}
|
||||
|
||||
export interface HybridRideProgressiveResponse {
|
||||
data: HybridRideData[];
|
||||
has_more: boolean;
|
||||
total_count: number;
|
||||
}
|
||||
|
||||
// Frontend utility types for hybrid filtering
|
||||
export interface RideFilterState {
|
||||
search: string;
|
||||
categories: RideCategory[];
|
||||
statuses: RideStatus[];
|
||||
parkId?: number;
|
||||
manufacturerIds: number[];
|
||||
designerIds: number[];
|
||||
rideModelIds: number[];
|
||||
rollerCoasterTypes: string[];
|
||||
trackMaterials: string[];
|
||||
launchTypes: string[];
|
||||
ratingRange: [number, number];
|
||||
heightRequirementRange: [number, number];
|
||||
capacityRange: [number, number];
|
||||
heightFtRange: [number, number];
|
||||
speedMphRange: [number, number];
|
||||
inversionRange: [number, number];
|
||||
openingYearRange: [number, number];
|
||||
hasInversions?: boolean;
|
||||
ordering: string;
|
||||
}
|
||||
|
||||
export interface RideFilterActions {
|
||||
setSearch: (search: string) => void;
|
||||
setCategories: (categories: RideCategory[]) => void;
|
||||
setStatuses: (statuses: RideStatus[]) => void;
|
||||
setParkId: (parkId?: number) => void;
|
||||
setManufacturerIds: (ids: number[]) => void;
|
||||
setDesignerIds: (ids: number[]) => void;
|
||||
setRideModelIds: (ids: number[]) => void;
|
||||
setRollerCoasterTypes: (types: string[]) => void;
|
||||
setTrackMaterials: (materials: string[]) => void;
|
||||
setLaunchTypes: (types: string[]) => void;
|
||||
setRatingRange: (range: [number, number]) => void;
|
||||
setHeightRequirementRange: (range: [number, number]) => void;
|
||||
setCapacityRange: (range: [number, number]) => void;
|
||||
setHeightFtRange: (range: [number, number]) => void;
|
||||
setSpeedMphRange: (range: [number, number]) => void;
|
||||
setInversionRange: (range: [number, number]) => void;
|
||||
setOpeningYearRange: (range: [number, number]) => void;
|
||||
setHasInversions: (hasInversions?: boolean) => void;
|
||||
setOrdering: (ordering: string) => void;
|
||||
resetFilters: () => void;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user