mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-25 03:11:09 -05:00
Add secret management guide, client-side performance monitoring, and search accessibility enhancements
- Introduced a comprehensive Secret Management Guide detailing best practices, secret classification, development setup, production management, rotation procedures, and emergency protocols. - Implemented a client-side performance monitoring script to track various metrics including page load performance, paint metrics, layout shifts, and memory usage. - Enhanced search accessibility with keyboard navigation support for search results, ensuring compliance with WCAG standards and improving user experience.
This commit is contained in:
180
docs/admin/base_classes.md
Normal file
180
docs/admin/base_classes.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user