mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 17:51:08 -05:00
feat: Implement comprehensive ride filtering system with API integration
- Added `useRideFiltering` composable for managing ride filters and fetching rides from the API. - Created `useParkRideFiltering` for park-specific ride filtering. - Developed `useTheme` composable for theme management with localStorage support. - Established `rideFiltering` Pinia store for centralized state management of ride filters and UI state. - Defined enhanced filter types in `filters.ts` for better type safety and clarity. - Built `RideFilteringPage.vue` to provide a user interface for filtering rides with responsive design. - Integrated filter sidebar and ride list display components for a cohesive user experience. - Added support for filter presets and search suggestions. - Implemented computed properties for active filters, average ratings, and operating counts.
This commit is contained in:
pacnpal
169
backend/docs/ride_filtering_design.md
Normal file
169
backend/docs/ride_filtering_design.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# Comprehensive Ride Filtering System Design
|
||||
|
||||
## Overview
|
||||
This document outlines the design for a robust ride filtering system with PostgreSQL full-text search capabilities, organized in logical filter categories with a beautiful Tailwind 4 UI.
|
||||
|
||||
## Filter Categories
|
||||
|
||||
### 1. Search & Text Filters
|
||||
- **Main Search Bar**: Full-text search across name, description, park name using PostgreSQL SearchVector
|
||||
- **Advanced Search**: Separate fields for ride name, park name, description
|
||||
- **Fuzzy Search**: TrigramSimilarity for typo-tolerant searching
|
||||
|
||||
### 2. Basic Ride Information
|
||||
- **Category**: Multi-select dropdown (Roller Coaster, Dark Ride, Flat Ride, Water Ride, Transport, Other)
|
||||
- **Status**: Multi-select dropdown (Operating, Temporarily Closed, SBNO, Closing, Permanently Closed, Under Construction, Demolished, Relocated)
|
||||
|
||||
### 3. Date Filters
|
||||
- **Opening Date Range**: Date picker for from/to dates
|
||||
- **Closing Date Range**: Date picker for from/to dates
|
||||
- **Status Since**: Date picker for from/to dates
|
||||
|
||||
### 4. Height & Safety Requirements
|
||||
- **Minimum Height**: Range slider (30-90 inches)
|
||||
- **Maximum Height**: Range slider (30-90 inches)
|
||||
- **Height Requirement Type**: No requirement, minimum only, maximum only, both
|
||||
|
||||
### 5. Performance Metrics
|
||||
- **Capacity per Hour**: Range slider (0-5000+ people)
|
||||
- **Ride Duration**: Range slider (0-600+ seconds)
|
||||
- **Average Rating**: Range slider (1-10 stars)
|
||||
|
||||
### 6. Location & Relationships
|
||||
- **Park**: Multi-select autocomplete dropdown
|
||||
- **Park Area**: Multi-select dropdown (filtered by selected parks)
|
||||
- **Manufacturer**: Multi-select autocomplete dropdown
|
||||
- **Designer**: Multi-select autocomplete dropdown
|
||||
- **Ride Model**: Multi-select autocomplete dropdown
|
||||
|
||||
### 7. Roller Coaster Specific (only shown when RC category selected)
|
||||
- **Height**: Range slider (0-500+ feet)
|
||||
- **Length**: Range slider (0-10000+ feet)
|
||||
- **Speed**: Range slider (0-150+ mph)
|
||||
- **Inversions**: Range slider (0-20+)
|
||||
- **Max Drop Height**: Range slider (0-500+ feet)
|
||||
- **Track Material**: Multi-select (Steel, Wood, Hybrid)
|
||||
- **Coaster Type**: Multi-select (Sit Down, Inverted, Flying, Stand Up, Wing, Dive, Family, Wild Mouse, Spinning, 4th Dimension, Other)
|
||||
- **Launch Type**: Multi-select (Chain Lift, LSM Launch, Hydraulic Launch, Gravity, Other)
|
||||
|
||||
### 8. Company Information (when manufacturer/designer filters are used)
|
||||
- **Company Founded**: Date range picker
|
||||
- **Company Roles**: Multi-select (Manufacturer, Designer, Operator, Property Owner)
|
||||
- **Rides Count**: Range slider (1-500+)
|
||||
- **Coasters Count**: Range slider (1-200+)
|
||||
|
||||
## Sorting Options
|
||||
- **Name** (A-Z, Z-A)
|
||||
- **Opening Date** (Newest, Oldest)
|
||||
- **Average Rating** (Highest, Lowest)
|
||||
- **Height** (Tallest, Shortest) - for roller coasters
|
||||
- **Speed** (Fastest, Slowest) - for roller coasters
|
||||
- **Capacity** (Highest, Lowest)
|
||||
- **Recently Updated** (using pghistory)
|
||||
- **Relevance** (for text searches using SearchRank)
|
||||
|
||||
## UI/UX Design Principles
|
||||
|
||||
### Layout Structure
|
||||
- **Desktop**: Sidebar filter panel (collapsible) + main content area
|
||||
- **Mobile**: Overlay filter modal with bottom sheet design
|
||||
- **Filter Organization**: Collapsible sections with clean headers and icons
|
||||
|
||||
### Tailwind 4 Design System
|
||||
- **Color Scheme**: Modern neutral palette with theme support
|
||||
- **Typography**: Clear hierarchy with proper contrast
|
||||
- **Spacing**: Consistent spacing scale (4, 8, 16, 24, 32px)
|
||||
- **Interactive Elements**: Smooth transitions and hover states
|
||||
- **Form Controls**: Custom-styled inputs, dropdowns, sliders
|
||||
|
||||
### Dark Mode Support
|
||||
- Full dark mode implementation using Tailwind's dark: variants
|
||||
- Theme toggle in header
|
||||
- Proper contrast ratios for accessibility
|
||||
- Dark-friendly color selections for data visualization
|
||||
|
||||
### Responsive Design
|
||||
- **Mobile First**: Progressive enhancement approach
|
||||
- **Breakpoints**: sm (640px), md (768px), lg (1024px), xl (1280px)
|
||||
- **Touch Friendly**: Larger touch targets on mobile
|
||||
- **Collapsible Filters**: Smart grouping on smaller screens
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### Backend Architecture
|
||||
1. **Search Service**: Django service layer for search logic
|
||||
2. **PostgreSQL Features**: SearchVector, SearchQuery, SearchRank, GIN indexes
|
||||
3. **Fuzzy Matching**: TrigramSimilarity for typo tolerance
|
||||
4. **Caching**: Redis for popular filter combinations
|
||||
5. **Pagination**: Efficient pagination with search ranking
|
||||
|
||||
### Frontend Features
|
||||
1. **HTMX Integration**: Real-time filtering without full page reloads
|
||||
2. **URL Persistence**: Filter state preserved in URL parameters
|
||||
3. **Autocomplete**: Intelligent suggestions for text fields
|
||||
4. **Filter Counts**: Show result counts for each filter option
|
||||
5. **Active Filters**: Visual indicators of applied filters
|
||||
6. **Reset Functionality**: Clear individual or all filters
|
||||
|
||||
### Performance Optimizations
|
||||
1. **Database Indexes**: GIN indexes on search vectors
|
||||
2. **Query Optimization**: Efficient JOIN strategies
|
||||
3. **Caching Layer**: Popular searches cached in Redis
|
||||
4. **Debounced Input**: Prevent excessive API calls
|
||||
5. **Lazy Loading**: Load expensive filter options on demand
|
||||
|
||||
## Accessibility Features
|
||||
- **Keyboard Navigation**: Full keyboard support for all controls
|
||||
- **Screen Readers**: Proper ARIA labels and descriptions
|
||||
- **Color Contrast**: WCAG AA compliance
|
||||
- **Focus Management**: Clear focus indicators
|
||||
- **Alternative Text**: Descriptive labels for all controls
|
||||
|
||||
## Search Algorithm Details
|
||||
|
||||
### PostgreSQL Full-Text Search
|
||||
```sql
|
||||
-- Search vector combining multiple fields with weights
|
||||
search_vector = (
|
||||
setweight(to_tsvector('english', name), 'A') ||
|
||||
setweight(to_tsvector('english', park.name), 'B') ||
|
||||
setweight(to_tsvector('english', description), 'C') ||
|
||||
setweight(to_tsvector('english', manufacturer.name), 'D')
|
||||
)
|
||||
|
||||
-- Search query with ranking
|
||||
SELECT *, ts_rank(search_vector, query) as rank
|
||||
FROM rides
|
||||
WHERE search_vector @@ query
|
||||
ORDER BY rank DESC, name
|
||||
```
|
||||
|
||||
### Trigram Similarity
|
||||
```sql
|
||||
-- Fuzzy matching for typos
|
||||
SELECT *
|
||||
FROM rides
|
||||
WHERE similarity(name, 'search_term') > 0.3
|
||||
ORDER BY similarity(name, 'search_term') DESC
|
||||
```
|
||||
|
||||
## Filter State Management
|
||||
- **URL Parameters**: All filter state stored in URL for shareability
|
||||
- **Local Storage**: Remember user preferences
|
||||
- **Session State**: Maintain state during browsing session
|
||||
- **Bookmark Support**: Full filter state can be bookmarked
|
||||
|
||||
## Testing Strategy
|
||||
1. **Unit Tests**: Individual filter components
|
||||
2. **Integration Tests**: Full filtering workflows
|
||||
3. **Performance Tests**: Large dataset filtering
|
||||
4. **Accessibility Tests**: Screen reader and keyboard testing
|
||||
5. **Mobile Tests**: Touch interface testing
|
||||
6. **Browser Tests**: Cross-browser compatibility
|
||||
|
||||
## Future Enhancements
|
||||
1. **Saved Filters**: User accounts can save filter combinations
|
||||
2. **Advanced Analytics**: Popular filter combinations tracking
|
||||
3. **Machine Learning**: Personalized filter suggestions
|
||||
4. **Export Features**: Export filtered results to CSV/PDF
|
||||
5. **Comparison Mode**: Side-by-side ride comparisons
|
||||
Reference in New Issue
Block a user