Internal-apps/roles/trade_hub/files/trade-hub/backend/app/models.py

"""SQLAlchemy models for mutable user data (accounts + personal inventories).

The scunpacked catalog is deliberately NOT modeled here. It stays read-only in
memory (see app/catalog.py); inventory rows reference catalog items only by
`class_name`, so the catalog can be replaced wholesale without touching user
data.
"""
from datetime import datetime, timezone

from sqlalchemy import (
    CheckConstraint,
    DateTime,
    ForeignKey,
    Integer,
    String,
    Text,
    UniqueConstraint,
)
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship


def utcnow() -> datetime:
    """Timezone-aware current time (portable across SQLite and PostgreSQL)."""
    return datetime.now(timezone.utc)


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    # Display name as typed at registration.
    username: Mapped[str] = mapped_column(String(32), nullable=False)
    # Lowercased form, unique: gives case-insensitive uniqueness without citext.
    username_key: Mapped[str] = mapped_column(
        String(32), nullable=False, unique=True, index=True
    )
    password_hash: Mapped[str] = mapped_column(String(255), nullable=False)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, default=utcnow
    )

    sessions: Mapped[list["UserSession"]] = relationship(
        back_populates="user", cascade="all, delete-orphan"
    )
    inventory: Mapped[list["InventoryEntry"]] = relationship(
        back_populates="user", cascade="all, delete-orphan"
    )
    orders: Mapped[list["Order"]] = relationship(
        back_populates="user", cascade="all, delete-orphan"
    )


class UserSession(Base):
    __tablename__ = "sessions"

    # Only the SHA-256 of the cookie token is persisted.
    token_hash: Mapped[str] = mapped_column(String(64), primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
    )
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, default=utcnow
    )
    expires_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False
    )

    user: Mapped[User] = relationship(back_populates="sessions")


class InventoryEntry(Base):
    __tablename__ = "inventory_entries"
    __table_args__ = (
        UniqueConstraint("user_id", "class_name", name="uq_inventory_user_item"),
        CheckConstraint("quantity >= 1", name="ck_inventory_quantity_positive"),
        CheckConstraint(
            "visibility IN ('private', 'available')",
            name="ck_inventory_visibility",
        ),
        CheckConstraint(
            "quality IS NULL OR (quality >= 1 AND quality <= 1000)",
            name="ck_inventory_quality_range",
        ),
    )

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
    )
    class_name: Mapped[str] = mapped_column(String(255), nullable=False)
    quantity: Mapped[int] = mapped_column(Integer, nullable=False, default=1)
    notes: Mapped[str] = mapped_column(Text, nullable=False, default="")
    # Mining/refining quality (1-1000) for commodities where it applies. NULL
    # means "not specified"; non-quality commodities must keep this NULL. The
    # applicability itself is catalog data, not stored here.
    quality: Mapped[int | None] = mapped_column(Integer, nullable=True)
    # "private" (default): only the owner sees the row. "available": the owner
    # is offering the item. Unrelated to the response flag `available`, which
    # only reports whether the catalog still contains the referenced item.
    visibility: Mapped[str] = mapped_column(
        String(16), nullable=False, default="private", server_default="private"
    )
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, default=utcnow
    )
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow
    )

    user: Mapped[User] = relationship(back_populates="inventory")


class Order(Base):
    """A public request for a catalog item placed by a logged-in user.

    Orders are intentionally visible to everyone (see app/orders.py). They
    reference catalog items by `class_name` only, exactly like inventory rows,
    so a catalog refresh cannot break them.
    """

    __tablename__ = "orders"
    __table_args__ = (
        CheckConstraint("quantity >= 1", name="ck_orders_quantity_positive"),
        CheckConstraint(
            "quality IS NULL OR (quality >= 1 AND quality <= 1000)",
            name="ck_orders_quality_range",
        ),
        CheckConstraint(
            "status IN ('open', 'fulfilled')",
            name="ck_orders_status",
        ),
    )

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
    )
    class_name: Mapped[str] = mapped_column(String(255), nullable=False)
    quantity: Mapped[int] = mapped_column(Integer, nullable=False, default=1)
    # Mining/refining quality (1-1000); only valid for quality-applicable ores.
    quality: Mapped[int | None] = mapped_column(Integer, nullable=True)
    notes: Mapped[str] = mapped_column(Text, nullable=False, default="")
    status: Mapped[str] = mapped_column(
        String(16), nullable=False, default="open", server_default="open"
    )
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, default=utcnow
    )
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow
    )

    user: Mapped[User] = relationship(back_populates="orders")