Lesson 00b — TicketFlow initial modeling

User 1───N Reservation N───N Seat N───1 Event
                         │
                         └──── N ───1 Payment

draft ──publish()──▶ published ──cancel()──▶ cancelled
                        │
                        └──start_date passes──▶ completed

                 ┌───────── timeout / expire ─────────┐
                 ▼                                    │
PENDING_PAYMENT ──pay()──▶ CONFIRMED ──refund/cancel──▶ CANCELLED
                 │                                    ▲
                 └────── cancel() by the user ────────┘

PENDING ──webhook ok──▶ SUCCEEDED
   │──── webhook fail──▶ FAILED
   └──── timeout ──────▶ EXPIRED

# events/models.py
import uuid
from django.conf import settings
from django.db import models


class TimeStampedModel(models.Model):
    """Mixin: created_at/updated_at. Auditing "when" is cheap now and invaluable later."""
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True


class UserRole(models.TextChoices):
    BUYER = "BUYER", "Buyer"
    ORGANIZER = "ORGANIZER", "Organizer"
    ADMIN = "ADMIN", "Admin"


class User(TimeStampedModel):
    """Provisional: later we evaluate Django's User (native auth) vs this one.
    v1 decision: our own model to avoid coupling the domain to the auth mechanism yet."""
    email = models.EmailField(unique=True)
    role = models.CharField(max_length=16, choices=UserRole.choices, default=UserRole.BUYER)


class EventState(models.TextChoices):
    DRAFT = "DRAFT", "Draft"
    PUBLISHED = "PUBLISHED", "Published"
    CANCELLED = "CANCELLED", "Cancelled"
    COMPLETED = "COMPLETED", "Completed"


class Event(TimeStampedModel):
    title = models.CharField(max_length=200)
    description = models.TextField(blank=True)
    venue = models.CharField(max_length=200)              # place
    starts_at = models.DateTimeField()
    state = models.CharField(max_length=16, choices=EventState.choices, default=EventState.DRAFT)
    organizer = models.ForeignKey(
        settings.AUTH_USER_MODEL, on_delete=models.PROTECT, related_name="organized_events",
    )

    class Meta:
        indexes = [
            # Dominant query: "future published events, ordered by date"
            models.Index(fields=["state", "starts_at"]),
        ]

    def __str__(self):
        return f"{self.title} @ {self.venue}"


class Seat(TimeStampedModel):
    event = models.ForeignKey(Event, on_delete=models.CASCADE, related_name="seats")
    sector = models.CharField(max_length=50, default="GENERAL")
    row = models.CharField(max_length=10)
    number = models.PositiveIntegerField()

    class Meta:
        constraints = [
            # Physical identity of the seat within the event
            models.UniqueConstraint(fields=["event", "sector", "row", "number"], name="uniq_seat_per_event"),
        ]
        indexes = [
            # "Which seats of event X are free?" → filtering by event is 95% of the queries
            models.Index(fields=["event", "sector", "row", "number"]),
        ]

    def __str__(self):
        return f"{self.sector}·R{self.row}·{self.number} ({self.event_id})"


class ReservationState(models.TextChoices):
    PENDING_PAYMENT = "PENDING_PAYMENT", "Pending payment"
    CONFIRMED = "CONFIRMED", "Confirmed"
    CANCELLED = "CANCELLED", "Cancelled"


class Reservation(TimeStampedModel):
    user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.PROTECT, related_name="reservations")
    event = models.ForeignKey(Event, on_delete=models.PROTECT, related_name="reservations")
    status = models.CharField(max_length=20, choices=ReservationState.choices)
    expires_at = models.DateTimeField()  # PENDING_PAYMENT expires here (invariant I2)

    class Meta:
        indexes = [
            models.Index(fields=["status", "expires_at"]),
        ]


class ReservationItem(models.Model):
    """Each seat within a reservation. N:M bridge table with data of its own
    (price_at_purchase: the price is frozen at reservation time, not at payment)."""
    reservation = models.ForeignKey(Reservation, on_delete=models.CASCADE, related_name="items")
    seat = models.ForeignKey(Seat, on_delete=models.PROTECT, related_name="reservation_items")
    price_at_purchase = models.DecimalField(max_digits=10, decimal_places=2)

    class Meta:
        constraints = [
            models.UniqueConstraint(fields=["seat"], condition=models.Q(reservation__status="PENDING_PAYMENT"),
                                    name="uniq_active_reservation_per_seat"),
            models.UniqueConstraint(fields=["seat"], condition=models.Q(reservation__status="CONFIRMED"),
                                    name="uniq_confirmed_reservation_per_seat"),
        ]

class PaymentState(models.TextChoices):
    PENDING = "PENDING", "Pending"
    SUCCEEDED = "SUCCEEDED", "Succeeded"
    FAILED = "FAILED", "Failed"


class Payment(TimeStampedModel):
    reservation = models.ForeignKey(Reservation, on_delete=models.PROTECT, related_name="payments")
    amount = models.DecimalField(max_digits=10, decimal_places=2)
    status = models.CharField(max_length=16, choices=PaymentState.choices, default=PaymentState.PENDING)
    idempotency_key = models.UUIDField(unique=True)   # I3: one payment, one attempt
    gateway_reference = models.CharField(max_length=100, blank=True)  # what the gateway returns