Promocode system

backend/app/models/__init__.py

@@ -17,6 +17,7 @@ from app.models.shop import ShopItem, ShopItemType, ItemRarity, ConsumableType
 from app.models.inventory import UserInventory
 from app.models.coin_transaction import CoinTransaction, CoinTransactionType
 from app.models.consumable_usage import ConsumableUsage
+from app.models.promo_code import PromoCode, PromoCodeRedemption
 
 __all__ = [
     "User",
@@ -62,4 +63,6 @@ __all__ = [
     "CoinTransaction",
     "CoinTransactionType",
     "ConsumableUsage",
+    "PromoCode",
+    "PromoCodeRedemption",
 ]

backend/app/models/coin_transaction.py

@@ -20,6 +20,7 @@ class CoinTransactionType(str, Enum):
     REFUND = "refund"
     ADMIN_GRANT = "admin_grant"
     ADMIN_DEDUCT = "admin_deduct"
+    PROMO_CODE = "promo_code"
 
 
 class CoinTransaction(Base):

backend/app/models/promo_code.py

@@ -0,0 +1,67 @@
+"""
+Promo Code models for coins distribution
+"""
+from datetime import datetime
+from sqlalchemy import DateTime, ForeignKey, Integer, String, Boolean, UniqueConstraint, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class PromoCode(Base):
+    """Promo code for giving coins to users"""
+    __tablename__ = "promo_codes"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    code: Mapped[str] = mapped_column(String(50), unique=True, index=True, nullable=False)
+    coins_amount: Mapped[int] = mapped_column(Integer, nullable=False)
+    max_uses: Mapped[int | None] = mapped_column(Integer, nullable=True)  # None = unlimited
+    uses_count: Mapped[int] = mapped_column(Integer, default=0, nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    created_by_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    valid_from: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    valid_until: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=func.now(), nullable=False)
+
+    # Relationships
+    created_by: Mapped["User"] = relationship("User", foreign_keys=[created_by_id])
+    redemptions: Mapped[list["PromoCodeRedemption"]] = relationship(
+        "PromoCodeRedemption", back_populates="promo_code", cascade="all, delete-orphan"
+    )
+
+    def is_valid(self) -> bool:
+        """Check if promo code is currently valid"""
+        if not self.is_active:
+            return False
+
+        now = datetime.utcnow()
+
+        if self.valid_from and now < self.valid_from:
+            return False
+
+        if self.valid_until and now > self.valid_until:
+            return False
+
+        if self.max_uses is not None and self.uses_count >= self.max_uses:
+            return False
+
+        return True
+
+
+class PromoCodeRedemption(Base):
+    """Record of promo code redemption by a user"""
+    __tablename__ = "promo_code_redemptions"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    promo_code_id: Mapped[int] = mapped_column(ForeignKey("promo_codes.id", ondelete="CASCADE"), nullable=False)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    coins_awarded: Mapped[int] = mapped_column(Integer, nullable=False)
+    redeemed_at: Mapped[datetime] = mapped_column(DateTime, default=func.now(), nullable=False)
+
+    __table_args__ = (
+        UniqueConstraint('promo_code_id', 'user_id', name='uq_promo_code_user'),
+    )
+
+    # Relationships
+    promo_code: Mapped["PromoCode"] = relationship("PromoCode", back_populates="redemptions")
+    user: Mapped["User"] = relationship("User")