feat: models

app/infrastructure/db/models/enums.py

@@ -0,0 +1,66 @@
+"""Domain enums used by ORM columns.
+
+Plain ``str``-valued enums, stored as strings (not native PG enums) — adding a
+variant is a code change, never a migration (plan §4). Columns map these via
+``mapped_column(String(...))`` and persist ``Enum.value``.
+"""
+
+import enum
+
+
+class TrackSource(enum.StrEnum):
+    """Which backend imported a track. Drives ``is_replaceable`` (plan §6.6)."""
+
+    YOUTUBE = "youtube"
+    LOCAL = "local"
+    UPLOAD = "upload"
+    SOUNDCLOUD = "soundcloud"
+    BANDCAMP = "bandcamp"
+
+
+class StoragePolicy(enum.StrEnum):
+    """What the system did / must do with the stored format (plan §6.6).
+
+    ``master_keep`` is inviolable — never auto-optimized.
+    """
+
+    AS_IS = "as_is"
+    OPTIMIZED = "optimized"
+    MASTER_KEEP = "master_keep"
+
+
+class MetadataStatus(enum.StrEnum):
+    """Enrichment state. ``manual`` is never overwritten by auto-enrichment."""
+
+    PENDING = "pending"
+    ENRICHED = "enriched"
+    FAILED = "failed"
+    MANUAL = "manual"
+
+
+class LikeValue(enum.StrEnum):
+    """A like event's value. Likes are an append-only log, not a boolean —
+    current state is the latest event per ``(user, track)`` (plan §4.1)."""
+
+    LIKE = "like"
+    DISLIKE = "dislike"
+    NEUTRAL = "neutral"
+
+
+class DownloadStatus(enum.StrEnum):
+    """Lifecycle of a download job (plan §6.1)."""
+
+    QUEUED = "queued"
+    DOWNLOADING = "downloading"
+    ENRICHING = "enriching"
+    DONE = "done"
+    FAILED = "failed"
+
+
+class LyricsStatus(enum.StrEnum):
+    """Lyrics fetch outcome. ``not_found`` is cached too (with TTL) so we don't
+    hammer the provider for tracks that have no lyrics (plan §6.7)."""
+
+    FOUND = "found"
+    NOT_FOUND = "not_found"
+    PENDING = "pending"