feat: Implement initial schema and add various API, service, and management command enhancements across the application.

backend/apps/rides/models/rides.py

@@ -1,5 +1,4 @@
 import contextlib
-from typing import TYPE_CHECKING
 
 import pghistory
 from django.contrib.auth.models import AbstractBaseUser
@@ -14,10 +13,6 @@ from config.django import base as settings
 
 from .company import Company
 
-if TYPE_CHECKING:
-    from .rides import RollerCoasterStats
-
-
 
 @pghistory.track()
 class RideModel(TrackedModel):
@@ -30,9 +25,7 @@ class RideModel(TrackedModel):
     """
 
     name = models.CharField(max_length=255, help_text="Name of the ride model")
-    slug = models.SlugField(
-        max_length=255, help_text="URL-friendly identifier (unique within manufacturer)"
-    )
+    slug = models.SlugField(max_length=255, help_text="URL-friendly identifier (unique within manufacturer)")
     manufacturer = models.ForeignKey(
         Company,
         on_delete=models.SET_NULL,
@@ -42,9 +35,7 @@ class RideModel(TrackedModel):
         limit_choices_to={"roles__contains": ["MANUFACTURER"]},
         help_text="Primary manufacturer of this ride model",
     )
-    description = models.TextField(
-        blank=True, help_text="Detailed description of the ride model"
-    )
+    description = models.TextField(blank=True, help_text="Detailed description of the ride model")
     category = RichChoiceField(
         choice_group="categories",
         domain="rides",
@@ -125,9 +116,7 @@ class RideModel(TrackedModel):
         blank=True,
         help_text="Year of last installation of this model (if discontinued)",
     )
-    is_discontinued = models.BooleanField(
-        default=False, help_text="Whether this model is no longer being manufactured"
-    )
+    is_discontinued = models.BooleanField(default=False, help_text="Whether this model is no longer being manufactured")
     total_installations = models.PositiveIntegerField(
         default=0, help_text="Total number of installations worldwide (auto-calculated)"
     )
@@ -156,9 +145,7 @@ class RideModel(TrackedModel):
     )
 
     # SEO and metadata
-    meta_title = models.CharField(
-        max_length=60, blank=True, help_text="SEO meta title (auto-generated if blank)"
-    )
+    meta_title = models.CharField(max_length=60, blank=True, help_text="SEO meta title (auto-generated if blank)")
     meta_description = models.CharField(
         max_length=160,
         blank=True,
@@ -175,25 +162,21 @@ class RideModel(TrackedModel):
         constraints = [
             # Unique constraints (replacing unique_together for better error messages)
             models.UniqueConstraint(
-                fields=['manufacturer', 'name'],
-                name='ridemodel_manufacturer_name_unique',
-                violation_error_message='A ride model with this name already exists for this manufacturer'
+                fields=["manufacturer", "name"],
+                name="ridemodel_manufacturer_name_unique",
+                violation_error_message="A ride model with this name already exists for this manufacturer",
             ),
             models.UniqueConstraint(
-                fields=['manufacturer', 'slug'],
-                name='ridemodel_manufacturer_slug_unique',
-                violation_error_message='A ride model with this slug already exists for this manufacturer'
+                fields=["manufacturer", "slug"],
+                name="ridemodel_manufacturer_slug_unique",
+                violation_error_message="A ride model with this slug already exists for this manufacturer",
             ),
             # Height range validation
             models.CheckConstraint(
                 name="ride_model_height_range_logical",
                 condition=models.Q(typical_height_range_min_ft__isnull=True)
                 | models.Q(typical_height_range_max_ft__isnull=True)
-                | models.Q(
-                    typical_height_range_min_ft__lte=models.F(
-                        "typical_height_range_max_ft"
-                    )
-                ),
+                | models.Q(typical_height_range_min_ft__lte=models.F("typical_height_range_max_ft")),
                 violation_error_message="Minimum height cannot exceed maximum height",
             ),
             # Speed range validation
@@ -201,11 +184,7 @@ class RideModel(TrackedModel):
                 name="ride_model_speed_range_logical",
                 condition=models.Q(typical_speed_range_min_mph__isnull=True)
                 | models.Q(typical_speed_range_max_mph__isnull=True)
-                | models.Q(
-                    typical_speed_range_min_mph__lte=models.F(
-                        "typical_speed_range_max_mph"
-                    )
-                ),
+                | models.Q(typical_speed_range_min_mph__lte=models.F("typical_speed_range_max_mph")),
                 violation_error_message="Minimum speed cannot exceed maximum speed",
             ),
             # Capacity range validation
@@ -213,11 +192,7 @@ class RideModel(TrackedModel):
                 name="ride_model_capacity_range_logical",
                 condition=models.Q(typical_capacity_range_min__isnull=True)
                 | models.Q(typical_capacity_range_max__isnull=True)
-                | models.Q(
-                    typical_capacity_range_min__lte=models.F(
-                        "typical_capacity_range_max"
-                    )
-                ),
+                | models.Q(typical_capacity_range_min__lte=models.F("typical_capacity_range_max")),
                 violation_error_message="Minimum capacity cannot exceed maximum capacity",
             ),
             # Installation years validation
@@ -225,27 +200,19 @@ class RideModel(TrackedModel):
                 name="ride_model_installation_years_logical",
                 condition=models.Q(first_installation_year__isnull=True)
                 | models.Q(last_installation_year__isnull=True)
-                | models.Q(
-                    first_installation_year__lte=models.F("last_installation_year")
-                ),
+                | models.Q(first_installation_year__lte=models.F("last_installation_year")),
                 violation_error_message="First installation year cannot be after last installation year",
             ),
         ]
 
     def __str__(self) -> str:
-        return (
-            self.name
-            if not self.manufacturer
-            else f"{self.manufacturer.name} {self.name}"
-        )
+        return self.name if not self.manufacturer else f"{self.manufacturer.name} {self.name}"
 
     def clean(self) -> None:
         """Validate RideModel business rules."""
         super().clean()
         if self.is_discontinued and not self.last_installation_year:
-            raise ValidationError({
-                'last_installation_year': 'Discontinued models must have a last installation year'
-            })
+            raise ValidationError({"last_installation_year": "Discontinued models must have a last installation year"})
 
     def save(self, *args, **kwargs) -> None:
         if not self.slug:
@@ -257,11 +224,7 @@ class RideModel(TrackedModel):
 
             # Ensure uniqueness within the same manufacturer
             counter = 1
-            while (
-                RideModel.objects.filter(manufacturer=self.manufacturer, slug=self.slug)
-                .exclude(pk=self.pk)
-                .exists()
-            ):
+            while RideModel.objects.filter(manufacturer=self.manufacturer, slug=self.slug).exclude(pk=self.pk).exists():
                 self.slug = f"{base_slug}-{counter}"
                 counter += 1
 
@@ -269,16 +232,12 @@ class RideModel(TrackedModel):
         if not self.meta_title:
             self.meta_title = str(self)[:60]
         if not self.meta_description:
-            desc = (
-                f"{self} - {self.description[:100]}" if self.description else str(self)
-            )
+            desc = f"{self} - {self.description[:100]}" if self.description else str(self)
             self.meta_description = desc[:160]
 
         # Generate frontend URL
         if self.manufacturer:
-            frontend_domain = getattr(
-                settings, "FRONTEND_DOMAIN", "https://thrillwiki.com"
-            )
+            frontend_domain = getattr(settings, "FRONTEND_DOMAIN", "https://thrillwiki.com")
             self.url = f"{frontend_domain}/rides/manufacturers/{self.manufacturer.slug}/{self.slug}/"
 
         super().save(*args, **kwargs)
@@ -342,9 +301,7 @@ class RideModelVariant(TrackedModel):
         help_text="Base ride model this variant belongs to",
     )
     name = models.CharField(max_length=255, help_text="Name of this variant")
-    description = models.TextField(
-        blank=True, help_text="Description of variant differences"
-    )
+    description = models.TextField(blank=True, help_text="Description of variant differences")
 
     # Variant-specific specifications
     min_height_ft = models.DecimalField(
@@ -402,16 +359,12 @@ class RideModelPhoto(TrackedModel):
         help_text="Ride model this photo belongs to",
     )
     image = models.ForeignKey(
-        'django_cloudflareimages_toolkit.CloudflareImage',
+        "django_cloudflareimages_toolkit.CloudflareImage",
         on_delete=models.CASCADE,
-        help_text="Photo of the ride model stored on Cloudflare Images"
-    )
-    caption = models.CharField(
-        max_length=500, blank=True, help_text="Photo caption or description"
-    )
-    alt_text = models.CharField(
-        max_length=255, blank=True, help_text="Alternative text for accessibility"
+        help_text="Photo of the ride model stored on Cloudflare Images",
     )
+    caption = models.CharField(max_length=500, blank=True, help_text="Photo caption or description")
+    alt_text = models.CharField(max_length=255, blank=True, help_text="Alternative text for accessibility")
 
     # Photo metadata
     photo_type = RichChoiceField(
@@ -422,18 +375,12 @@ class RideModelPhoto(TrackedModel):
         help_text="Type of photo for categorization and display purposes",
     )
 
-    is_primary = models.BooleanField(
-        default=False, help_text="Whether this is the primary photo for the ride model"
-    )
+    is_primary = models.BooleanField(default=False, help_text="Whether this is the primary photo for the ride model")
 
     # Attribution
-    photographer = models.CharField(
-        max_length=255, blank=True, help_text="Name of the photographer"
-    )
+    photographer = models.CharField(max_length=255, blank=True, help_text="Name of the photographer")
     source = models.CharField(max_length=255, blank=True, help_text="Source of the photo")
-    copyright_info = models.CharField(
-        max_length=255, blank=True, help_text="Copyright information"
-    )
+    copyright_info = models.CharField(max_length=255, blank=True, help_text="Copyright information")
 
     class Meta(TrackedModel.Meta):
         verbose_name = "Ride Model Photo"
@@ -446,9 +393,9 @@ class RideModelPhoto(TrackedModel):
     def save(self, *args, **kwargs) -> None:
         # Ensure only one primary photo per ride model
         if self.is_primary:
-            RideModelPhoto.objects.filter(
-                ride_model=self.ride_model, is_primary=True
-            ).exclude(pk=self.pk).update(is_primary=False)
+            RideModelPhoto.objects.filter(ride_model=self.ride_model, is_primary=True).exclude(pk=self.pk).update(
+                is_primary=False
+            )
         super().save(*args, **kwargs)
 
 
@@ -474,15 +421,9 @@ class RideModelTechnicalSpec(TrackedModel):
     )
 
     spec_name = models.CharField(max_length=100, help_text="Name of the specification")
-    spec_value = models.CharField(
-        max_length=255, help_text="Value of the specification"
-    )
-    spec_unit = models.CharField(
-        max_length=20, blank=True, help_text="Unit of measurement"
-    )
-    notes = models.TextField(
-        blank=True, help_text="Additional notes about this specification"
-    )
+    spec_value = models.CharField(max_length=255, help_text="Value of the specification")
+    spec_unit = models.CharField(max_length=20, blank=True, help_text="Unit of measurement")
+    notes = models.TextField(blank=True, help_text="Additional notes about this specification")
 
     class Meta(TrackedModel.Meta):
         verbose_name = "Ride Model Technical Specification"
@@ -503,17 +444,15 @@ class Ride(StateMachineMixin, TrackedModel):
     jobs. Use selectors or annotations for real-time calculations if needed.
     """
 
-    if TYPE_CHECKING:
-        coaster_stats: 'RollerCoasterStats'
+    # Type hint for the reverse relation from RollerCoasterStats
+    coaster_stats: "RollerCoasterStats"
 
     state_field_name = "status"
 
     name = models.CharField(max_length=255)
     slug = models.SlugField(max_length=255)
     description = models.TextField(blank=True)
-    park = models.ForeignKey(
-        "parks.Park", on_delete=models.CASCADE, related_name="rides"
-    )
+    park = models.ForeignKey("parks.Park", on_delete=models.CASCADE, related_name="rides")
     park_area = models.ForeignKey(
         "parks.ParkArea",
         on_delete=models.SET_NULL,
@@ -527,7 +466,7 @@ class Ride(StateMachineMixin, TrackedModel):
         max_length=2,
         default="",
         blank=True,
-        help_text="Ride category classification"
+        help_text="Ride category classification",
     )
     manufacturer = models.ForeignKey(
         Company,
@@ -558,7 +497,7 @@ class Ride(StateMachineMixin, TrackedModel):
         domain="rides",
         max_length=20,
         default="OPERATING",
-        help_text="Current operational status of the ride"
+        help_text="Current operational status of the ride",
     )
     post_closing_status = RichChoiceField(
         choice_group="post_closing_statuses",
@@ -575,9 +514,7 @@ class Ride(StateMachineMixin, TrackedModel):
     max_height_in = models.PositiveIntegerField(null=True, blank=True)
     capacity_per_hour = models.PositiveIntegerField(null=True, blank=True)
     ride_duration_seconds = models.PositiveIntegerField(null=True, blank=True)
-    average_rating = models.DecimalField(
-        max_digits=3, decimal_places=2, null=True, blank=True
-    )
+    average_rating = models.DecimalField(max_digits=3, decimal_places=2, null=True, blank=True)
 
     # Computed fields for hybrid filtering
     opening_year = models.IntegerField(null=True, blank=True, db_index=True)
@@ -603,9 +540,7 @@ class Ride(StateMachineMixin, TrackedModel):
 
     # Frontend URL
     url = models.URLField(blank=True, help_text="Frontend URL for this ride")
-    park_url = models.URLField(
-        blank=True, help_text="Frontend URL for this ride's park"
-    )
+    park_url = models.URLField(blank=True, help_text="Frontend URL for this ride's park")
 
     class Meta(TrackedModel.Meta):
         verbose_name = "Ride"
@@ -635,17 +570,13 @@ class Ride(StateMachineMixin, TrackedModel):
                 name="ride_min_height_reasonable",
                 condition=models.Q(min_height_in__isnull=True)
                 | (models.Q(min_height_in__gte=30) & models.Q(min_height_in__lte=90)),
-                violation_error_message=(
-                    "Minimum height must be between 30 and 90 inches"
-                ),
+                violation_error_message=("Minimum height must be between 30 and 90 inches"),
             ),
             models.CheckConstraint(
                 name="ride_max_height_reasonable",
                 condition=models.Q(max_height_in__isnull=True)
                 | (models.Q(max_height_in__gte=30) & models.Q(max_height_in__lte=90)),
-                violation_error_message=(
-                    "Maximum height must be between 30 and 90 inches"
-                ),
+                violation_error_message=("Maximum height must be between 30 and 90 inches"),
             ),
             # Business rule: Rating must be between 1 and 10
             models.CheckConstraint(
@@ -657,14 +588,12 @@ class Ride(StateMachineMixin, TrackedModel):
             # Business rule: Capacity and duration must be positive
             models.CheckConstraint(
                 name="ride_capacity_positive",
-                condition=models.Q(capacity_per_hour__isnull=True)
-                | models.Q(capacity_per_hour__gt=0),
+                condition=models.Q(capacity_per_hour__isnull=True) | models.Q(capacity_per_hour__gt=0),
                 violation_error_message="Hourly capacity must be positive",
             ),
             models.CheckConstraint(
                 name="ride_duration_positive",
-                condition=models.Q(ride_duration_seconds__isnull=True)
-                | models.Q(ride_duration_seconds__gt=0),
+                condition=models.Q(ride_duration_seconds__isnull=True) | models.Q(ride_duration_seconds__gt=0),
                 violation_error_message="Ride duration must be positive",
             ),
         ]
@@ -699,9 +628,7 @@ class Ride(StateMachineMixin, TrackedModel):
         from django.core.exceptions import ValidationError
 
         if not post_closing_status:
-            raise ValidationError(
-                "post_closing_status must be set when entering CLOSING status"
-            )
+            raise ValidationError("post_closing_status must be set when entering CLOSING status")
         self.transition_to_closing(user=user)
         self.closing_date = closing_date
         self.post_closing_status = post_closing_status
@@ -770,7 +697,7 @@ class Ride(StateMachineMixin, TrackedModel):
             self._ensure_unique_slug_in_park()
 
         # Handle park area validation when park changes
-        if park_changed and self.park_area:
+        if park_changed and self.park_area:  # noqa: SIM102
             # Check if park_area belongs to the new park
             if self.park_area.park.id != self.park.id:
                 # Clear park_area if it doesn't belong to the new park
@@ -786,9 +713,7 @@ class Ride(StateMachineMixin, TrackedModel):
 
         # Generate frontend URLs
         if self.park:
-            frontend_domain = getattr(
-                settings, "FRONTEND_DOMAIN", "https://thrillwiki.com"
-            )
+            frontend_domain = getattr(settings, "FRONTEND_DOMAIN", "https://thrillwiki.com")
             self.url = f"{frontend_domain}/parks/{self.park.slug}/rides/{self.slug}/"
             self.park_url = f"{frontend_domain}/parks/{self.park.slug}/"
 
@@ -817,7 +742,7 @@ class Ride(StateMachineMixin, TrackedModel):
         # Park info
         if self.park:
             search_parts.append(self.park.name)
-            if hasattr(self.park, 'location') and self.park.location:
+            if hasattr(self.park, "location") and self.park.location:
                 if self.park.location.city:
                     search_parts.append(self.park.location.city)
                 if self.park.location.state:
@@ -855,7 +780,7 @@ class Ride(StateMachineMixin, TrackedModel):
 
         # Roller coaster stats if available
         try:
-            if hasattr(self, 'coaster_stats') and self.coaster_stats:
+            if hasattr(self, "coaster_stats") and self.coaster_stats:
                 stats = self.coaster_stats
                 if stats.track_type:
                     search_parts.append(stats.track_type)
@@ -877,7 +802,7 @@ class Ride(StateMachineMixin, TrackedModel):
             # Ignore if coaster_stats doesn't exist or has issues
             pass
 
-        self.search_text = ' '.join(filter(None, search_parts)).lower()
+        self.search_text = " ".join(filter(None, search_parts)).lower()
 
     def _ensure_unique_slug_in_park(self) -> None:
         """Ensure the ride's slug is unique within its park."""
@@ -885,11 +810,7 @@ class Ride(StateMachineMixin, TrackedModel):
         self.slug = base_slug
 
         counter = 1
-        while (
-            Ride.objects.filter(park=self.park, slug=self.slug)
-            .exclude(pk=self.pk)
-            .exists()
-        ):
+        while Ride.objects.filter(park=self.park, slug=self.slug).exclude(pk=self.pk).exists():
             self.slug = f"{base_slug}-{counter}"
             counter += 1
 
@@ -921,26 +842,15 @@ class Ride(StateMachineMixin, TrackedModel):
 
         # Return summary of changes
         changes = {
-            'old_park': {
-                'id': old_park.id,
-                'name': old_park.name,
-                'slug': old_park.slug
-            },
-            'new_park': {
-                'id': new_park.id,
-                'name': new_park.name,
-                'slug': new_park.slug
-            },
-            'url_changed': old_url != self.url,
-            'old_url': old_url,
-            'new_url': self.url,
-            'park_area_cleared': clear_park_area and old_park_area is not None,
-            'old_park_area': {
-                'id': old_park_area.id,
-                'name': old_park_area.name
-            } if old_park_area else None,
-            'slug_changed': self.slug != slugify(self.name),
-            'final_slug': self.slug
+            "old_park": {"id": old_park.id, "name": old_park.name, "slug": old_park.slug},
+            "new_park": {"id": new_park.id, "name": new_park.name, "slug": new_park.slug},
+            "url_changed": old_url != self.url,
+            "old_url": old_url,
+            "new_url": self.url,
+            "park_area_cleared": clear_park_area and old_park_area is not None,
+            "old_park_area": {"id": old_park_area.id, "name": old_park_area.name} if old_park_area else None,
+            "slug_changed": self.slug != slugify(self.name),
+            "final_slug": self.slug,
         }
 
         return changes
@@ -963,9 +873,9 @@ class Ride(StateMachineMixin, TrackedModel):
         except cls.DoesNotExist:
             # Try historical slugs in HistoricalSlug model
             content_type = ContentType.objects.get_for_model(cls)
-            historical_query = HistoricalSlug.objects.filter(
-                content_type=content_type, slug=slug
-            ).order_by("-created_at")
+            historical_query = HistoricalSlug.objects.filter(content_type=content_type, slug=slug).order_by(
+                "-created_at"
+            )
 
             for historical in historical_query:
                 try:
@@ -986,14 +896,13 @@ class Ride(StateMachineMixin, TrackedModel):
                     except cls.DoesNotExist:
                         continue
 
-            raise cls.DoesNotExist("No ride found with this slug")
+            raise cls.DoesNotExist("No ride found with this slug") from None
 
 
 @pghistory.track()
 class RollerCoasterStats(models.Model):
     """Model for tracking roller coaster specific statistics"""
 
-
     ride = models.OneToOneField(
         Ride,
         on_delete=models.CASCADE,
@@ -1021,22 +930,16 @@ class RollerCoasterStats(models.Model):
         blank=True,
         help_text="Maximum speed in mph",
     )
-    inversions = models.PositiveIntegerField(
-        default=0, help_text="Number of inversions"
-    )
-    ride_time_seconds = models.PositiveIntegerField(
-        null=True, blank=True, help_text="Duration of the ride in seconds"
-    )
-    track_type = models.CharField(
-        max_length=255, blank=True, help_text="Type of track (e.g., tubular steel, wooden)"
-    )
+    inversions = models.PositiveIntegerField(default=0, help_text="Number of inversions")
+    ride_time_seconds = models.PositiveIntegerField(null=True, blank=True, help_text="Duration of the ride in seconds")
+    track_type = models.CharField(max_length=255, blank=True, help_text="Type of track (e.g., tubular steel, wooden)")
     track_material = RichChoiceField(
         choice_group="track_materials",
         domain="rides",
         max_length=20,
         default="STEEL",
         blank=True,
-        help_text="Track construction material type"
+        help_text="Track construction material type",
     )
     roller_coaster_type = RichChoiceField(
         choice_group="coaster_types",
@@ -1044,7 +947,7 @@ class RollerCoasterStats(models.Model):
         max_length=20,
         default="SITDOWN",
         blank=True,
-        help_text="Roller coaster type classification"
+        help_text="Roller coaster type classification",
     )
     max_drop_height_ft = models.DecimalField(
         max_digits=6,
@@ -1058,20 +961,12 @@ class RollerCoasterStats(models.Model):
         domain="rides",
         max_length=20,
         default="CHAIN",
-        help_text="Propulsion or lift system type"
-    )
-    train_style = models.CharField(
-        max_length=255, blank=True, help_text="Style of train (e.g., floorless, inverted)"
-    )
-    trains_count = models.PositiveIntegerField(
-        null=True, blank=True, help_text="Number of trains"
-    )
-    cars_per_train = models.PositiveIntegerField(
-        null=True, blank=True, help_text="Number of cars per train"
-    )
-    seats_per_car = models.PositiveIntegerField(
-        null=True, blank=True, help_text="Number of seats per car"
+        help_text="Propulsion or lift system type",
     )
+    train_style = models.CharField(max_length=255, blank=True, help_text="Style of train (e.g., floorless, inverted)")
+    trains_count = models.PositiveIntegerField(null=True, blank=True, help_text="Number of trains")
+    cars_per_train = models.PositiveIntegerField(null=True, blank=True, help_text="Number of cars per train")
+    seats_per_car = models.PositiveIntegerField(null=True, blank=True, help_text="Number of seats per car")
 
     class Meta:
         verbose_name = "Roller Coaster Statistics"