# View Pattern Guidelines

This document provides guidelines for implementing views in the ThrillWiki backend.

## When to Use CBVs

Use Class-Based Views for:
- CRUD operations (CreateView, UpdateView, DetailView, ListView, DeleteView)
- Complex views with multiple methods
- Views that benefit from inheritance and mixins
- Views with shared context or queryset logic

### CBV Examples

```python
class ParkDetailView(OptimizedDetailView):
    """Display park details with related data."""

    model = Park
    template_name = "parks/park_detail.html"
    select_related_fields = ["location", "operator"]
    prefetch_related_fields = ["photos", "rides"]
```

## When to Use FBVs

Use Function-Based Views for:
- Simple HTMX partial renders
- Single-purpose utility endpoints
- Search/autocomplete endpoints
- Status badge/action endpoints

### FBV Examples

```python
def search_parks(request: HttpRequest) -> HttpResponse:
    """
    HTMX endpoint for park search autocomplete.

    View Type: FBV (HTMX Partial)
    URL Pattern: /parks/search/
    Returns: HTML partial
    """
    query = request.GET.get("q", "").strip()
    parks = Park.objects.filter(name__icontains=query)[:10]
    return render(request, "parks/partials/search_results.html", {"parks": parks})
```

## When to Use ViewSets

Use DRF ViewSets for:
- REST API endpoints
- Resources with standard CRUD operations
- Resources requiring nested routing

### ViewSet Examples

```python
class ParkPhotoViewSet(ModelViewSet):
    """ViewSet for managing park photos via API."""

    queryset = ParkPhoto.objects.all()
    serializer_class = ParkPhotoSerializer
    permission_classes = [IsAuthenticated]
```

## View Inventory

### Parks App
- **CBVs**: ParkListView, ParkCreateView, ParkUpdateView, ParkDetailView, ParkAreaDetailView, OperatorListView
- **FBVs**: geocode_location, reverse_geocode, search_parks, roadtrip_* (HTMX)

### Rides App
- **CBVs**: RideDetailView, RideCreateView, RideUpdateView, RideListView, SingleCategoryListView, RideRankingsView, RideRankingDetailView, ManufacturerListView, DesignerListView
- **FBVs**: show_coaster_fields, ride_status_actions, ride_header_badge, search_companies, search_ride_models, get_search_suggestions, ranking_history_chart, ranking_comparisons

### Accounts App
- **CBVs**: ProfileView, SettingsView, CustomLoginView, CustomSignupView
- **FBVs**: user_redirect_view, email_required, request_password_reset, reset_password

### Moderation App
- **ViewSets**: ModerationReportViewSet, ModerationQueueViewSet, ModerationActionViewSet, BulkOperationViewSet, UserModerationViewSet

## View Type Indicators

Always include view type information in docstrings:

```python
class ParkDetailView(DetailView):
    """
    Display park details with related data.

    View Type: CBV (DetailView)
    URL Pattern: /parks/<slug>/
    Template: parks/park_detail.html
    Permissions: Public
    """

def search_parks(request: HttpRequest) -> HttpResponse:
    """
    HTMX endpoint for park search autocomplete.

    View Type: FBV (HTMX Partial)
    URL Pattern: /parks/search/
    Returns: HTML partial
    """
```

## Base Classes

### OptimizedListView

Automatically applies select_related and prefetch_related based on class attributes.

```python
from apps.core.views.base import OptimizedListView

class RideListView(OptimizedListView):
    model = Ride
    select_related_fields = ['park', 'manufacturer']
    prefetch_related_fields = ['photos']
```

### OptimizedDetailView

Automatically applies select_related and prefetch_related based on class attributes.

```python
from apps.core.views.base import OptimizedDetailView

class RideDetailView(OptimizedDetailView):
    model = Ride
    select_related_fields = ['park', 'park__location', 'manufacturer']
    prefetch_related_fields = ['photos', 'coaster_stats']
```

## Mixins

### RideFormMixin

Handles entity suggestions in ride forms (manufacturers, designers, models).

```python
from apps.rides.mixins import RideFormMixin

class RideCreateView(RideFormMixin, CreateView):
    def form_valid(self, form):
        self.handle_entity_suggestions(form)
        return super().form_valid(form)
```

## Best Practices

1. **Prefer CBVs for CRUD** - Use Django's built-in generic views
2. **Prefer FBVs for HTMX** - Simple endpoints are easier to understand as functions
3. **Document view types** - Include View Type in all docstrings
4. **Use mixins for shared logic** - Avoid code duplication
5. **Use base classes for query optimization** - OptimizedListView, OptimizedDetailView