""" @model CouponModel (Backend/app/models/CouponModel.py) @purpose Unified database entities for rule-based promotional coupons, first-time buyer incentives, and customer redemption tracking. """ import ulid from datetime import datetime, timezone from sqlalchemy import Column, String, Boolean, Integer, Numeric, DateTime, JSON, ForeignKey, func from sqlalchemy.orm import relationship from app.core.database.db_session import Base class Coupon(Base): __tablename__ = "coupons" coupon_id = Column(String(26), primary_key=True, default=lambda: str(ulid.ULID())) code = Column(String(50), nullable=False, unique=True, index=True) title = Column(String(100), nullable=False) description = Column(String(255), nullable=True) discount_type = Column(String(20), nullable=False, default="PERCENTAGE") # PERCENTAGE, FIXED, FREE_SHIPPING discount_value = Column(Numeric(10, 2), nullable=False) max_discount_cap = Column(Numeric(10, 2), nullable=True) min_order_amount = Column(Numeric(10, 2), nullable=False, default=0.00) max_order_amount = Column(Numeric(10, 2), nullable=True) # Core E-Commerce Rules first_order_only = Column(Boolean, nullable=False, default=False, index=True) channel_scope = Column(String(20), nullable=False, default="OMNICHANNEL") # ONLINE_ONLY, POS_ONLY, OMNICHANNEL exclude_already_discounted = Column(Boolean, nullable=False, default=False) # Catalog Target Filtering (Stored as JSON lists of IDs) applicable_category_ids = Column(JSON, nullable=True) applicable_brand_ids = Column(JSON, nullable=True) applicable_model_ids = Column(JSON, nullable=True) # Validity & Caps valid_from = Column(DateTime, nullable=False) valid_to = Column(DateTime, nullable=False) usage_limit_total = Column(Integer, nullable=True) usage_limit_per_customer = Column(Integer, nullable=False, default=1) times_used = Column(Integer, nullable=False, default=0) is_active = Column(Boolean, nullable=False, default=True, index=True) created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc)) updated_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), onupdate=lambda: datetime.now(timezone.utc)) usages = relationship("CouponUsage", back_populates="coupon", cascade="all, delete-orphan") class CouponUsage(Base): __tablename__ = "coupon_usages" usage_id = Column(String(26), primary_key=True, default=lambda: str(ulid.ULID())) coupon_id = Column(String(26), ForeignKey("coupons.coupon_id", ondelete="CASCADE"), nullable=False, index=True) customer_id = Column(String(26), nullable=False, index=True) order_id = Column(String(26), ForeignKey("orders.order_id", ondelete="CASCADE"), nullable=False, index=True) discount_amount = Column(Numeric(10, 2), nullable=False) used_at = Column(DateTime, default=lambda: datetime.now(timezone.utc)) coupon = relationship("Coupon", back_populates="usages") order = relationship("Order", backref="coupon_usage")