feat: models

app/infrastructure/db/models/play_history.py

@@ -0,0 +1,36 @@
+"""ORM model for play history — an append-only event log (scrobbles).
+
+``play_duration_seconds`` (how long was actually listened) feeds skip-rate for
+future ML; ``completed`` marks a full play (plan §4).
+"""
+
+import datetime as dt
+import uuid
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, Index, Integer, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.infrastructure.db.base import Base
+from app.infrastructure.db.models.mixins import UUIDPrimaryKeyMixin
+
+
+class PlayHistoryModel(UUIDPrimaryKeyMixin, Base):
+    __tablename__ = "play_history"
+    __table_args__ = (Index("ix_play_history_user_id_played_at", "user_id", "played_at"),)
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    track_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("tracks.id", ondelete="CASCADE"),
+        index=True,
+        nullable=False,
+    )
+    played_at: Mapped[dt.datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+    )
+    play_duration_seconds: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    completed: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)