mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 10:11:09 -05:00
feat: Update parks API to remove note about ignored parameters; add comprehensive frontend integration prompts for park filtering
This commit is contained in:
pacnpal
164
docs/frontend-llm-prompt.md
Normal file
164
docs/frontend-llm-prompt.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# Frontend Integration Prompt: ThrillWiki Park Filter Endpoints
|
||||
|
||||
## Project Context
|
||||
You are working on the NextJS frontend for ThrillWiki, a theme park and ride database application. The Django backend has been updated to support comprehensive park filtering with 24 parameters. Your task is to integrate these filter endpoints into the frontend application.
|
||||
|
||||
## API Endpoint Information
|
||||
|
||||
### Base URL Structure
|
||||
- Main parks endpoint: `/parks/`
|
||||
- Individual park: `/parks/{park_slug}/`
|
||||
- Filter options: `/parks/filter-options/`
|
||||
|
||||
### Critical API Rules
|
||||
- ALL API endpoints MUST include trailing forward slashes unless ending with query parameters
|
||||
- Use GET requests for all filtering operations
|
||||
- Parameters are passed as query strings
|
||||
- Pagination is handled via `page` and `page_size` parameters
|
||||
|
||||
## Complete Filter Parameters (24 Total)
|
||||
|
||||
### Pagination & Search
|
||||
- `page` (number): Page number for pagination
|
||||
- `page_size` (number): Number of results per page
|
||||
- `search` (string): Text search across park names and descriptions
|
||||
- `ordering` (string): Sort field (name, opening_year, rating, ride_count, etc.)
|
||||
|
||||
### Geographic Filters
|
||||
- `continent` (string): Filter by continent (North America, Europe, Asia, etc.)
|
||||
- `country` (string): Filter by country name
|
||||
- `state` (string): Filter by state/province
|
||||
- `city` (string): Filter by city name
|
||||
|
||||
### Park Classification
|
||||
- `park_type` (string): Park category - options include:
|
||||
- THEME_PARK, AMUSEMENT_PARK, WATER_PARK, SAFARI_PARK, ZOO, AQUARIUM, FAMILY_ENTERTAINMENT_CENTER, CARNIVAL, FAIR, OTHER
|
||||
- `status` (string): Operational status of the park
|
||||
|
||||
### Company Relationships
|
||||
- `operator_id` (number): Filter by operating company ID
|
||||
- `operator_slug` (string): Filter by operating company slug
|
||||
- `property_owner_id` (number): Filter by property owner company ID
|
||||
- `property_owner_slug` (string): Filter by property owner company slug
|
||||
|
||||
### Rating Filters
|
||||
- `min_rating` (number): Minimum park rating
|
||||
- `max_rating` (number): Maximum park rating
|
||||
|
||||
### Ride Count Filters
|
||||
- `min_ride_count` (number): Minimum total number of rides
|
||||
- `max_ride_count` (number): Maximum total number of rides
|
||||
- `has_roller_coasters` (boolean): Whether park has roller coasters
|
||||
- `min_roller_coaster_count` (number): Minimum number of roller coasters
|
||||
- `max_roller_coaster_count` (number): Maximum number of roller coasters
|
||||
|
||||
### Temporal Filters
|
||||
- `opening_year` (number): Exact opening year
|
||||
- `min_opening_year` (number): Earliest opening year
|
||||
- `max_opening_year` (number): Latest opening year
|
||||
|
||||
## Filter Options Endpoint
|
||||
The `/parks/filter-options/` endpoint provides dynamic filter options based on actual database content:
|
||||
|
||||
### Response Structure
|
||||
- `continents`: Array of available continent strings
|
||||
- `countries`: Array of available country strings
|
||||
- `states`: Array of available state strings
|
||||
- `cities`: Array of available city strings
|
||||
- `park_types`: Array of objects with `value` and `label` properties
|
||||
- `operators`: Array of company objects with operator role
|
||||
- `property_owners`: Array of company objects with property owner role
|
||||
- `opening_years`: Array of available opening years
|
||||
- `rating_ranges`: Object with min/max rating values
|
||||
- `ride_count_ranges`: Object with min/max ride count values
|
||||
|
||||
## TypeScript Integration Requirements
|
||||
|
||||
### Type Safety
|
||||
- Create comprehensive TypeScript interfaces for all filter parameters
|
||||
- Define response types for park list and individual park data
|
||||
- Use proper union types for optional parameters
|
||||
- Import types from centralized types file using `@/types/api` pattern
|
||||
|
||||
### API Client Structure
|
||||
- Implement centralized API client with consistent error handling
|
||||
- Use proper HTTP methods and headers
|
||||
- Handle pagination metadata in responses
|
||||
- Implement request/response interceptors for authentication
|
||||
|
||||
## Frontend Implementation Considerations
|
||||
|
||||
### User Experience
|
||||
- Implement progressive disclosure for advanced filters
|
||||
- Provide clear visual feedback for active filters
|
||||
- Support filter combinations and complex queries
|
||||
- Include filter reset and clear functionality
|
||||
|
||||
### Performance Optimization
|
||||
- Implement debounced search input
|
||||
- Cache filter options to reduce API calls
|
||||
- Use proper loading states during filter operations
|
||||
- Consider implementing infinite scroll for large result sets
|
||||
|
||||
### State Management
|
||||
- Maintain filter state in URL query parameters for bookmarkability
|
||||
- Sync filter state with component state
|
||||
- Handle browser back/forward navigation properly
|
||||
- Persist user filter preferences where appropriate
|
||||
|
||||
## Data Relationships
|
||||
|
||||
### Geographic Hierarchy
|
||||
- Continent → Country → State → City relationship
|
||||
- Implement cascading dropdowns where appropriate
|
||||
- Handle cases where geographic data may be incomplete
|
||||
|
||||
### Company Relationships
|
||||
- Companies can have multiple roles (operator, property owner)
|
||||
- Same company may operate multiple parks
|
||||
- Support filtering by company name or slug
|
||||
|
||||
### Park-Ride Relationships
|
||||
- Parks contain multiple rides
|
||||
- Ride counts include all ride types
|
||||
- Roller coaster counts are subset of total ride counts
|
||||
|
||||
## Error Handling Requirements
|
||||
|
||||
### API Error Responses
|
||||
- Handle 400 Bad Request for invalid filter parameters
|
||||
- Handle 404 Not Found for invalid park slugs
|
||||
- Handle 500 Server Error with appropriate fallbacks
|
||||
- Implement retry logic for transient failures
|
||||
|
||||
### User Feedback
|
||||
- Display clear error messages for failed requests
|
||||
- Provide fallback content when filters return no results
|
||||
- Handle network connectivity issues gracefully
|
||||
|
||||
## Integration Testing Considerations
|
||||
|
||||
### Filter Validation
|
||||
- Test all 24 filter parameters individually
|
||||
- Test filter combinations and edge cases
|
||||
- Verify proper URL encoding of special characters
|
||||
- Test pagination with various filter combinations
|
||||
|
||||
### Data Consistency
|
||||
- Verify filter options match actual filterable data
|
||||
- Test geographic filter cascading behavior
|
||||
- Validate numeric range filters with boundary values
|
||||
|
||||
## Documentation Requirements
|
||||
- Update API documentation with all 24 parameters
|
||||
- Document TypeScript interfaces and their usage
|
||||
- Provide examples of common filter combinations
|
||||
- Document error handling patterns and fallback strategies
|
||||
|
||||
## Backend Compatibility Notes
|
||||
- All 24 filter parameters are fully supported by Django backend
|
||||
- Database fields exist for continent and park_type filtering
|
||||
- API responses include proper pagination metadata
|
||||
- Filter options endpoint returns real database values, not static lists
|
||||
- Geographic filtering uses case-insensitive matching
|
||||
- Company filtering supports both ID and slug-based queries
|
||||
Reference in New Issue
Block a user