thrillwiki_django_no_react/docs/admin/base_classes.md

# Admin Base Classes and Mixins

This document describes the base admin classes and mixins available for building standardized Django admin interfaces in ThrillWiki.

## Overview

The admin infrastructure provides reusable components that ensure consistency, optimize performance, and reduce code duplication across all admin interfaces.

## Base Classes

### BaseModelAdmin

The foundational admin class that all model admins should inherit from.

```python
from apps.core.admin import BaseModelAdmin

class MyModelAdmin(BaseModelAdmin):
    list_display = ['name', 'status', 'created_at']
```

**Features:**
- Consistent pagination (50 items per page)
- Optimized result count behavior
- Standard empty value display
- Save buttons at top of forms
- Filter preservation after saves

## Mixins

### QueryOptimizationMixin

Provides automatic query optimization to prevent N+1 queries.

```python
from apps.core.admin import QueryOptimizationMixin, BaseModelAdmin

class RideAdmin(QueryOptimizationMixin, BaseModelAdmin):
    list_display = ['name', 'park', 'manufacturer']
    list_select_related = ['park', 'manufacturer']
    list_prefetch_related = ['reviews', 'photos']
```

**Attributes:**
- `list_select_related`: List of ForeignKey fields to select
- `list_prefetch_related`: List of related fields to prefetch

### ReadOnlyAdminMixin

Disables add, change, and delete permissions for auto-generated data.

```python
from apps.core.admin import ReadOnlyAdminMixin, BaseModelAdmin

class RankingAdmin(ReadOnlyAdminMixin, BaseModelAdmin):
    list_display = ['ride', 'rank', 'calculated_at']
```

**Use cases:**
- Rankings and leaderboards
- Audit logs and history
- Calculated statistics
- State transition logs

### TimestampFieldsMixin

Provides standard handling for `created_at` and `updated_at` fields.

```python
from apps.core.admin import TimestampFieldsMixin, BaseModelAdmin

class MyModelAdmin(TimestampFieldsMixin, BaseModelAdmin):
    fieldsets = [
        ('Basic Info', {'fields': ['name', 'description']}),
    ] + TimestampFieldsMixin.get_timestamp_fieldset()
```

**Features:**
- Automatically adds timestamp fields to readonly_fields
- Provides a collapsible fieldset for metadata

### SlugFieldMixin

Configures automatic slug population from name field.

```python
from apps.core.admin import SlugFieldMixin, BaseModelAdmin

class ParkAdmin(SlugFieldMixin, BaseModelAdmin):
    slug_source_field = 'name'  # Optional, defaults to 'name'
```

### ExportActionMixin

Adds CSV and JSON export functionality.

```python
from apps.core.admin import ExportActionMixin, BaseModelAdmin

class ParkAdmin(ExportActionMixin, BaseModelAdmin):
    export_fields = ['id', 'name', 'status', 'created_at']
    export_filename_prefix = 'parks'
```

**Actions added:**
- Export selected to CSV
- Export selected to JSON

### BulkStatusChangeMixin

Provides bulk status change actions.

```python
from apps.core.admin import BulkStatusChangeMixin, BaseModelAdmin

class RideAdmin(BulkStatusChangeMixin, BaseModelAdmin):
    status_field = 'status'
    status_choices = [
        ('active', 'Activate'),
        ('inactive', 'Deactivate'),
    ]
```

### ModerationMixin

Adds moderation actions for user-generated content.

```python
from apps.core.admin import ModerationMixin, BaseModelAdmin

class ReviewAdmin(ModerationMixin, BaseModelAdmin):
    moderation_status_field = 'moderation_status'
    moderated_by_field = 'moderated_by'
    moderated_at_field = 'moderated_at'
```

**Actions added:**
- Approve selected items
- Reject selected items

## Combining Mixins

Mixins can be combined to create feature-rich admin classes:

```python
from apps.core.admin import (
    BaseModelAdmin,
    QueryOptimizationMixin,
    ExportActionMixin,
    TimestampFieldsMixin,
    SlugFieldMixin,
)

class ParkAdmin(
    QueryOptimizationMixin,
    ExportActionMixin,
    TimestampFieldsMixin,
    SlugFieldMixin,
    BaseModelAdmin
):
    list_display = ['name', 'operator', 'status', 'created_at']
    list_select_related = ['operator', 'location']
    list_prefetch_related = ['areas', 'rides']
    export_fields = ['id', 'name', 'slug', 'status']
```

## Best Practices

1. **Always use BaseModelAdmin** as the final parent class
2. **List mixins before BaseModelAdmin** in inheritance order
3. **Define list_select_related** for all ForeignKey fields in list_display
4. **Use prefetch_related** for reverse relations and M2M fields
5. **Test query counts** using Django Debug Toolbar
6. **Add export_fields** explicitly for control over exported data

## Performance Targets

- List views: < 10 queries
- Change views: < 15 queries
- Page load time: < 500ms for 100 records