python/models/outlet_model.py

"""
Outlet Model — ORM + Pydantic Schemas

ORM:     Outlet (SQLAlchemy table: outlets)
Schemas: OutletCreate, OutletResponse

Represents a coffee-shop branch that Ghost Shoppers visit.
"""

import uuid
from datetime import datetime
from typing import Optional

from sqlalchemy import String, Text, DateTime, func
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import Mapped, mapped_column, relationship

from pydantic import BaseModel, Field, ConfigDict

from models.base import Base


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# ORM Model
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

class Outlet(Base):
    """SQLAlchemy ORM model for the 'outlets' table."""

    __tablename__ = "outlets"

    id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
    )
    name: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
    location: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
    description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime, server_default=func.now()
    )
    updated_at: Mapped[datetime] = mapped_column(
        DateTime, server_default=func.now(), onupdate=func.now()
    )

    # Relationships
    visits = relationship("Visit", back_populates="outlet")

    def __repr__(self) -> str:
        return f"<Outlet(id={self.id}, name='{self.name}')>"


# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Pydantic Schemas
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

class OutletCreate(BaseModel):
    """Schema for creating a new outlet."""
    name: str = Field(..., min_length=1, max_length=255, description="Outlet name")
    location: Optional[str] = Field(None, max_length=255, description="Outlet address")
    description: Optional[str] = Field(None, description="Outlet description")


class OutletResponse(BaseModel):
    """Schema for an outlet in API responses."""
    model_config = ConfigDict(from_attributes=True)

    id: uuid.UUID
    name: str
    location: Optional[str]
    description: Optional[str]
    created_at: datetime
    updated_at: datetime