Transactions Domain - Models Documentation

class SaleTransactionManager(models.Manager):
    """
    Custom manager for the SaleTransaction model.
    """

def create_transaction(self, store, employee=None, customer=None):

from nextango.apps.stores.models import Store
from nextango.apps.transactions.models import SaleTransaction

store = Store.objects.get(store_code='COL001')
transaction = SaleTransaction.objects.create_transaction(store=store)
# Result: transactionId = 'TXN-20251117-A3B4C5D6'

def create_transaction(self, store, employee=None, customer=None):
    transaction_id = f"TXN-{timezone.now().strftime('%Y%m%d')}-{uuid.uuid4().hex[:8].upper()}"
    return self.create(
        transactionId=transaction_id,
        store=store,
        employee=employee,
        customer=customer,
        status='pending'
    )

class ReturnManager(models.Manager):
    """
    Custom manager for the Return model.
    """

def create_return(self, original_transaction, employee, reason=""):

from nextango.apps.transactions.models import Return

return_record = Return.objects.create_return(
    original_transaction=transaction,
    employee=employee,
    reason="Customer requested refund"
)
# Result: returnId = 'RET-20251117-F7E8D9C0'

def create_return(self, original_transaction, employee, reason=""):
    return_id = f"RET-{timezone.now().strftime('%Y%m%d')}-{uuid.uuid4().hex[:8].upper()}"
    return self.create(
        returnId=return_id,
        originalSaleId=original_transaction,
        employeeId=employee,
        reason=reason,
        status='pending'
    )

class StoreCreditManager(models.Manager):
    """
    Custom manager for the StoreCredit model.
    """

def create_store_credit(self, customer, amount, expiration_days=365, source_return=None):

from decimal import Decimal
from nextango.apps.transactions.models import StoreCredit

store_credit = StoreCredit.objects.create_store_credit(
    customer=customer,
    amount=Decimal('50.00'),
    expiration_days=365,
    source_return=return_record
)
# Result: creditId = 'SC-20251117-B1C2D3E4'
#         expirationDate = 2026-11-17

def create_store_credit(self, customer, amount, expiration_days=365, source_return=None):
    credit_id = f"SC-{timezone.now().strftime('%Y%m%d')}-{uuid.uuid4().hex[:8].upper()}"
    expiration_date = timezone.now().date() + timezone.timedelta(days=expiration_days)

    return self.create(
        creditId=credit_id,
        customerId=customer,
        initialAmount=amount,
        remainingBalance=amount,
        expirationDate=expiration_date,
        sourceReturn=source_return
    )

class TransactionAuditLog(AuditableMixin):
    """
    Immutable audit log for all transaction operations
    """

class Action(models.TextChoices):
    CREATED = 'created', 'Transaction Created'
    ITEM_ADDED = 'item_added', 'Item Added'
    ITEM_REMOVED = 'item_removed', 'Item Removed'
    ITEM_UPDATED = 'item_updated', 'Item Updated'
    DISCOUNT_APPLIED = 'discount_applied', 'Discount Applied'
    PAYMENT_PROCESSED = 'payment_processed', 'Payment Processed'
    PAYMENT_FAILED = 'payment_failed', 'Payment Failed'
    TRANSACTION_COMPLETED = 'transaction_completed', 'Transaction Completed'
    TRANSACTION_VOIDED = 'transaction_voided', 'Transaction Voided'
    REFUND_PROCESSED = 'refund_processed', 'Refund Processed'

class Meta:
    ordering = ['-timestamp']
    indexes = [
        models.Index(fields=['transaction_id', 'timestamp']),
        models.Index(fields=['actor_id', 'actor_type']),
        models.Index(fields=['action', 'timestamp']),
    ]

class PaymentAttempt(models.Model):
    """
    Track all payment attempts for debugging and security
    """

class Status(models.TextChoices):
    INITIATED = 'initiated', 'Initiated'
    PROCESSING = 'processing', 'Processing'
    SUCCEEDED = 'succeeded', 'Succeeded'
    FAILED = 'failed', 'Failed'
    CANCELLED = 'cancelled', 'Cancelled'
    EXPIRED = 'expired', 'Expired'

def save(self, *args, **kwargs):
    if not self.expires_at:
        self.expires_at = timezone.now() + timezone.timedelta(minutes=15)
    super().save(*args, **kwargs)

class IdempotencyRecord(models.Model):
    """
    Track idempotency keys to prevent duplicate operations
    """

def save(self, *args, **kwargs):
    if not self.expires_at:
        self.expires_at = timezone.now() + timezone.timedelta(hours=1)
    super().save(*args, **kwargs)

def is_expired(self):
    return timezone.now() > self.expires_at

class FraudDetectionResult(models.Model):
    """
    Store fraud detection results for payments
    """

class RiskLevel(models.TextChoices):
    LOW = 'low', 'Low Risk'
    MEDIUM = 'medium', 'Medium Risk'
    HIGH = 'high', 'High Risk'
    BLOCKED = 'blocked', 'Blocked'

class Status(models.TextChoices):
    PENDING = 'pending', 'Pending Review'
    APPROVED = 'approved', 'Approved'
    DECLINED = 'declined', 'Declined'
    MANUAL_REVIEW = 'manual_review', 'Manual Review Required'

class TransactionLock(models.Model):
    """
    Prevent concurrent modifications to transactions
    """

def save(self, *args, **kwargs):
    if not self.expires_at:
        self.expires_at = timezone.now() + timezone.timedelta(minutes=5)
    super().save(*args, **kwargs)

def is_expired(self):
    return timezone.now() > self.expires_at

class Cart(SanityIntegratedModel):
    """
    Represents a shopping cart for a customer or guest user.
    """

class Status(models.TextChoices):
    ACTIVE = 'active', 'Active'
    MERGED = 'merged', 'Merged'
    COMPLETED = 'completed', 'Completed'

class Meta:
    ordering = ['-updated_at']
    indexes = [
        models.Index(fields=['customer', 'status']),
        models.Index(fields=['created_at']),
        models.Index(fields=['sanity_id']),
        models.Index(fields=['last_synced_at']),
        models.Index(fields=['sync_enabled', 'sanity_id']),
    ]

@property
def item_count(self):
    """Returns the total number of items in the cart."""
    if isinstance(self.line_items, list):
        return sum(item.get('quantity', 0) for item in self.line_items)
    return 0

@property
def is_empty(self):
    """Returns True if the cart has no items."""
    return self.item_count == 0

def clear(self):
    """Removes all items from the cart."""
    self.line_items = []
    self.save(update_fields=['line_items', 'updated_at'])

line_items = [
    {
        'product_variant_id': 'uuid-here',
        'quantity': 2,
        'unit_price': '29.99',
        'total_price': '59.98'
    },
    {
        'product_variant_id': 'uuid-here-2',
        'quantity': 1,
        'unit_price': '49.99',
        'total_price': '49.99'
    }
]

class SaleTransaction(SanityIntegratedModel, AuditableMixin):
    """
    Represents a single sale transaction in a store.
    Inherits from SanityIntegratedModel for sync fields and AuditableMixin for audit fields.
    """

class Status(models.TextChoices):
    PENDING = 'pending', 'Pending'
    PARTIALLY_PAID = 'partially_paid', 'Partially Paid'
    COMPLETED = 'completed', 'Completed'
    VOIDED = 'voided', 'Voided'
    REFUNDED = 'refunded', 'Refunded'
    PARTIALLY_REFUNDED = 'partially_refunded', 'Partially Refunded'
    CANCELLED = 'cancelled', 'Cancelled'  # Customer-facing cancellation (pickup orders)
    PAYMENT_REQUIRES_ACTION = 'payment_requires_action', 'Payment Requires Action'  # 3DS / SCA pending

class SourceSystem(models.TextChoices):
    POS = 'pos', 'POS System'
    WEB_COMMERCE = 'web_commerce', 'Web Commerce'
    DASHBOARD = 'dashboard', 'Admin Dashboard'
    API = 'api', 'Direct API'

class FulfillmentMethod(models.TextChoices):
    PICKUP = 'pickup', 'In-Store Pickup'
    SHIP = 'ship', 'Ship to Customer'
    DIGITAL = 'digital', 'Digital Delivery'
    COUNTER_SALE = 'counter_sale', 'Counter Sale'

class Meta:
    indexes = [
        models.Index(fields=['timestamp', 'store']),
        models.Index(fields=['customer', 'timestamp']),
        models.Index(fields=['sanity_id']),
        models.Index(fields=['last_synced_at']),
        models.Index(fields=['sync_enabled', 'sanity_id']),
        models.Index(fields=['guest_access_token']),
        models.Index(
            fields=['voidedAt'],
            name='sale_txn_void_reconcile_idx',
            condition=models.Q(status='voided'),
        ),
    ]
    ordering = ['-timestamp']

def clean(self):
    """
    Custom model validation.
    """
    if self.status == self.Status.COMPLETED and not self.completedAt:
        self.completedAt = timezone.now()
    if self.status == self.Status.VOIDED and not self.voidedAt:
        self.voidedAt = timezone.now()

def save(self, *args, **kwargs):
    self.full_clean()
    super().save(*args, **kwargs)

def recalculate_totals(self, commit=True):

from nextango.apps.compliance.services.vertical_provider import get_active_vertical_provider
excise_components = get_active_vertical_provider().additional_excise(
    self, taxable_line_items, self.orderLevelDiscount, base_subtotal,
)

def calculate_tax(self) -> Decimal:
    """
    Calculates tax based on the store's tax rate.
    """
    tax_rate = getattr(self.store, 'tax_rate', Decimal('0.08'))
    return (self.subtotal * tax_rate).quantize(Decimal('0.01'), rounding=ROUND_HALF_UP)

@property
def payment_balance(self) -> Decimal:
    """
    Calculates the remaining balance to be paid.
    """
    total_paid = self.payment_records.filter(status='succeeded').aggregate(total=Sum('amount'))['total'] or Decimal('0.00')
    return self.totalAmount - total_paid

@property
def is_fully_paid(self) -> bool:
    """
    Checks if the transaction is fully paid.
    """
    return self.payment_balance <= 0

@property
def get_refundable_amount(self) -> Decimal:
    """
    Calculates the amount that can still be refunded.
    """
    if self.status not in [self.Status.COMPLETED, self.Status.PARTIALLY_REFUNDED]:
        return Decimal('0.00')

    # Get all processed returns for this transaction
    processed_returns = self.returns.filter(status=Return.Status.PROCESSED)

    # Sum refund amounts from all refund records related to these returns
    total_refunds = Decimal('0.00')
    for return_record in processed_returns:
        refund_total = return_record.refunds.aggregate(Sum('amount'))['amount__sum'] or Decimal('0.00')
        total_refunds += refund_total

    # Sum store credit amounts from all store credit transactions related to these returns
    total_store_credits = Decimal('0.00')
    for return_record in processed_returns:
        credit_total = return_record.store_credit_transactions.aggregate(Sum('amount'))['amount__sum'] or Decimal('0.00')
        total_store_credits += credit_total

    total_refunded = total_refunds + total_store_credits

    return max(Decimal('0.00'), self.totalAmount - total_refunded)

@property
def can_be_returned(self) -> bool:
    """
    Determines if the transaction can be returned.
    """
    return self.status in [self.Status.COMPLETED, self.Status.PARTIALLY_REFUNDED] and self.get_refundable_amount > 0

class Return(SanityIntegratedModel, AuditableMixin):
    """
    Represents a return of items from a completed sale.
    Now uses relational SalesReturnItem model instead of JSON array.
    """

class Status(models.TextChoices):
    PENDING = 'pending', 'Pending'
    PROCESSED = 'processed', 'Processed'
    CANCELLED = 'cancelled', 'Cancelled'

@property
def customer(self):
    """Get customer from original transaction"""
    return self.originalSaleId.customer if self.originalSaleId else None

@property
def isProcessed(self):
    """Boolean representation of processed status for Sanity sync"""
    return self.status == self.Status.PROCESSED

@property
def total_return_value(self) -> Decimal:
    """
    Total value returned to customer: sum of succeeded refunds + store credit issued.
    """
    refund_total = self.refunds.filter(status='succeeded').aggregate(
        total=Sum('amount')
    )['total'] or Decimal('0.00')
    credit_total = self.store_credit_transactions.aggregate(
        total=Sum('amount')
    )['total'] or Decimal('0.00')
    return refund_total + credit_total

def mark_as_processed(self, processed_by_employee):
    """Mark the return as processed"""
    self.status = self.Status.PROCESSED
    self.processedBy = processed_by_employee
    self.processedAt = timezone.now()
    self.save()

def clean(self):
    if self.pk is None:
        refundable = self.originalSaleId.get_refundable_amount()
        if self.total_return_value > refundable:
            raise ValidationError(f"Return amount (\${self.total_return_value}) exceeds refundable amount (\${refundable}).")

class StoreCredit(SanityIntegratedModel, AuditableMixin):
    """
    Represents store credit issued to a customer.
    """

class Meta:
    constraints = [
        models.CheckConstraint(check=models.Q(initialAmount__gt=0), name='positive_credit_amount'),
        models.CheckConstraint(check=models.Q(remainingBalance__gte=0), name='non_negative_balance'),
        models.CheckConstraint(check=models.Q(remainingBalance__lte=models.F('initialAmount')), name='balance_not_exceed_amount'),
    ]
    ordering = ['-created_at']
    indexes = [
        models.Index(fields=['sanity_id']),
        models.Index(fields=['last_synced_at']),
        models.Index(fields=['sync_enabled', 'sanity_id']),
    ]

def clean(self):
    if self.remainingBalance > self.initialAmount:
        raise ValidationError("Remaining balance cannot exceed the original amount.")
    if self.remainingBalance <= 0:
        self.isActive = False

def is_expired(self) -> bool:
    """
    Checks if the store credit has expired.
    """
    if not self.expirationDate:
        return False
    return timezone.now().date() > self.expirationDate

@property
def is_usable(self) -> bool:
    """
    Determines if the store credit can be used.
    """
    return self.isActive and not self.is_expired()

def recalculate_balance(self):

from django.db.models import Sum, Q

# Calculate total credits issued (positive)
total_issued = self.credit_transactions.filter(
    transactionType='issue'
).aggregate(Sum('amount'))['amount__sum'] or Decimal('0.00')

# Calculate total credits redeemed (negative impact on balance)
total_redeemed = self.credit_transactions.filter(
    transactionType='redeem'
).aggregate(Sum('amount'))['amount__sum'] or Decimal('0.00')

# Calculate new balance: initial + issued - redeemed
new_balance = self.initialAmount + total_issued - total_redeemed

# Ensure balance cannot go negative
self.remainingBalance = max(Decimal('0.00'), new_balance)

# Deactivate if balance reaches zero
if self.remainingBalance <= 0:
    self.isActive = False

class CashDrawerEvent(SanityIntegratedModel, AuditableMixin):
    """
    Logs events related to a physical cash drawer.
    """

class EventType(models.TextChoices):
    OPEN = 'open', 'Drawer Opened'
    CLOSE = 'close', 'Drawer Closed'
    SALE = 'sale', 'Sale Transaction'
    RETURN = 'return', 'Return/Refund'
    CASH_IN = 'cash_in', 'Cash Added (Pay In)'
    CASH_OUT = 'cash_out', 'Cash Removed (Pay Out)'
    DEPOSIT = 'deposit', 'Cash Deposit'
    TILL_COUNT = 'till_count', 'Till Count'
    NO_SALE = 'no_sale', 'No Sale (Drawer Open)'

def save(self, *args, **kwargs):
    if not self.eventId:
        self.eventId = f"CDE-{timezone.now().strftime('%Y%m%d')}-{uuid.uuid4().hex[:8].upper()}"
    super().save(*args, **kwargs)

cashBreakdown = {
    'hundreds': 5,    # 5 x $100 bills
    'fifties': 3,     # 3 x $50 bills
    'twenties': 10,   # 10 x $20 bills
    'tens': 15,       # 15 x $10 bills
    'fives': 20,      # 20 x $5 bills
    'ones': 50,       # 50 x $1 bills
    'quarters': 40,   # 40 quarters
    'dimes': 50,      # 50 dimes
    'nickels': 20,    # 20 nickels
    'pennies': 100    # 100 pennies
}

class SaleLineItem(SanityIntegratedModel, AuditableMixin):
    """
    Individual line item within a sales transaction.

    This model replaces the JSON field storage with proper relational architecture.
    All fields are marked as read-only to create immutable historical records
    that capture point-in-time data for audit trails.
    """

class Meta:
    ordering = ['id']  # Preserve insertion order
    indexes = [
        models.Index(fields=['transaction', 'id']),
        models.Index(fields=['productVariant', 'transaction']),
        models.Index(fields=['skuSnapshot']),
        models.Index(fields=['sanity_id']),
        models.Index(fields=['last_synced_at']),
        models.Index(fields=['sync_enabled', 'sanity_id']),
    ]
    constraints = [
        models.CheckConstraint(check=models.Q(quantity__gt=0), name='positive_quantity'),
        models.CheckConstraint(check=models.Q(unitPrice__gte=0), name='non_negative_unit_price'),
        models.CheckConstraint(check=models.Q(totalPrice__gte=0), name='non_negative_total_price'),
        models.CheckConstraint(check=models.Q(lineDiscount__gte=0), name='non_negative_line_discount'),
    ]

@property
def is_sync_ready(self):
    """Check if line item has all data needed for sync"""
    return all([
        self.transaction_id,
        self.productVariant_id,
        self.totalPrice is not None,
        self.unitPrice is not None,
        self.quantity is not None and self.quantity > 0,
        self.skuSnapshot,
        self.nameSnapshot
    ])

def can_sync_to_sanity(self):
    """Check if ready AND parent is synced"""
    return (
        self.is_sync_ready and
        self.transaction.sanity_id is not None
    )

def save(self, *args, **kwargs):

if self._state.adding and self.productVariant:  # Only on creation
    # Capture immutable snapshots from current product state
    self.skuSnapshot = self.productVariant.sku or 'UNKNOWN-SKU'
    self.nameSnapshot = getattr(self.productVariant, 'name', '') or str(self.productVariant)

    # Auto-calculate totalPrice if not set
    if self.totalPrice is None:
        calculated_total = (self.unitPrice * self.quantity) - self.lineDiscount
        self.totalPrice = calculated_total

super().save(*args, **kwargs)

def clean(self):
    """Custom model validation for business rules."""
    super().clean()

    if self.quantity <= 0:
        raise ValidationError("Quantity must be positive.")

    if self.unitPrice < 0:
        raise ValidationError("Unit price cannot be negative.")

    if self.lineDiscount < 0:
        raise ValidationError("Line discount cannot be negative.")

    # Validate total price calculation
    expected_total = (self.unitPrice * self.quantity) - self.lineDiscount
    if abs(self.totalPrice - expected_total) > Decimal('0.01'):  # Allow for rounding
        raise ValidationError(
            f"Total price \${self.totalPrice} does not match calculated total \${expected_total}"
        )

promotionDiscounts = [
    {
        'promo_code': 'SPRING20',
        'campaign_name': 'Spring Sale 2025',
        'discount_amount': '5.99',
        'discount_type': 'percentage',
        'applied_at': '2025-11-17T10:30:00Z'
    },
    {
        'promo_code': None,
        'campaign_name': 'Black Friday',
        'discount_amount': '10.00',
        'discount_type': 'fixed',
        'applied_at': '2025-11-17T10:30:00Z'
    }
]

class StoreCreditTransaction(SanityIntegratedModel, AuditableMixin):
    """
    Represents individual transactions in store credit ledger system.
    Replaces JSON-based ledger with proper relational model for audit integrity.
    Mirrors Sanity storeCreditTransaction.js schema exactly.
    """

class TransactionType(models.TextChoices):
    ISSUE = 'issue', 'Issue'
    REDEEM = 'redeem', 'Redeem'

class Meta:
    ordering = ['-timestamp']  # Most recent first
    indexes = [
        models.Index(fields=['store_credit', '-timestamp']),
        models.Index(fields=['transactionType', 'store_credit']),
        models.Index(fields=['salesTransaction']),
        models.Index(fields=['salesReturn']),
        models.Index(fields=['sanity_id']),
        models.Index(fields=['last_synced_at']),
        models.Index(fields=['sync_enabled', 'sanity_id']),
    ]
    constraints = [
        models.CheckConstraint(check=models.Q(amount__gt=0), name='positive_credit_transaction_amount'),
    ]

def clean(self):
    """Custom model validation for business rules."""
    super().clean()

    if self.amount <= 0:
        raise ValidationError("Transaction amount must be positive.")

    # Validate transaction type requirements
    if self.transactionType == 'redeem' and not self.salesTransaction:
        raise ValidationError("Redeem transactions must reference a sales transaction.")

    if self.transactionType == 'issue' and not self.salesReturn and not self.notes:
        raise ValidationError("Issue transactions must reference a return or include notes explaining the issuance.")

def save(self, *args, **kwargs):
    """Override save to maintain immutable fields."""
    if self.pk:
        # Prevent modification of existing records
        raise ValidationError("StoreCreditTransaction records are immutable and cannot be modified.")

    super().save(*args, **kwargs)

    # Trigger store credit balance recalculation
    self.store_credit.recalculate_balance()
    self.store_credit.save()

class ReturnLineItem(SanityIntegratedModel, AuditableMixin):
    """
    Represents individual items in a sales return.
    Mirrors Sanity returnLineItem.js schema exactly with immutable snapshot fields.
    Functions as the return equivalent to SaleLineItem.
    """

class ReturnReason(models.TextChoices):
    DAMAGED = 'damaged', 'Damaged'
    WRONG_SIZE = 'wrong_size', 'Wrong Size'
    UNWANTED_GIFT = 'unwanted_gift', 'Unwanted Gift'
    DEFECTIVE = 'defective', 'Defective'
    NOT_AS_DESCRIBED = 'not_as_described', 'Not as Described'
    CHANGED_MIND = 'changed_mind', 'Changed Mind'

class Disposition(models.TextChoices):
    SELLABLE = 'sellable', 'Sellable'
    DEFECTIVE = 'defective', 'Defective'
    QUARANTINE = 'quarantine', 'Quarantine'
    DAMAGED_OUT = 'damaged_out', 'Damaged Out'
    VENDOR_RETURN = 'vendor_return', 'Vendor Return'

class Meta:
    db_table = 'returnlineitem'
    ordering = ['id']  # Preserve insertion order
    indexes = [
        models.Index(fields=['sales_return', 'id']),
        models.Index(fields=['original_sale_line_item']),
        models.Index(fields=['skuSnapshot']),
        models.Index(fields=['reason']),
        models.Index(fields=['disposition']),
        models.Index(fields=['sanity_id']),
        models.Index(fields=['last_synced_at']),
        models.Index(fields=['sync_enabled', 'sanity_id']),
    ]
    constraints = [
        models.CheckConstraint(check=models.Q(quantity__gt=0), name='positive_return_line_item_quantity'),
        models.CheckConstraint(check=models.Q(returnPrice__gte=0), name='non_negative_return_line_item_price'),
    ]

def save(self, *args, **kwargs):
    """
    Auto-populate immutable snapshot fields from original sale line item.
    This ensures historical accuracy even if product details change later.
    """
    if not self.pk and self.original_sale_line_item:  # Only on creation
        # Capture immutable snapshots from original sale line item
        self.nameSnapshot = self.original_sale_line_item.nameSnapshot
        self.skuSnapshot = self.original_sale_line_item.skuSnapshot

        # For return price, use the unit price from original transaction
        # (could also be calculated differently based on business rules)
        self.returnPrice = self.original_sale_line_item.unitPrice * self.quantity

    super().save(*args, **kwargs)

def clean(self):
    """Custom model validation for business rules."""
    super().clean()

    if self.quantity <= 0:
        raise ValidationError("Return quantity must be positive.")

    if self.returnPrice < 0:
        raise ValidationError("Return price cannot be negative.")

    # Validate that return quantity doesn't exceed original quantity
    if self.original_sale_line_item and self.quantity > self.original_sale_line_item.quantity:
        raise ValidationError(
            f"Return quantity ({self.quantity}) cannot exceed original quantity ({self.original_sale_line_item.quantity})"
        )

class Fulfillment(SanityIntegratedModel, AuditableMixin):
    """
    Captures user-submitted checkout data at time of purchase.
    One Fulfillment per SaleTransaction.
    May contain multiple Shipments for split fulfillment.

    This is a snapshot of the checkout form data - address, payment, delivery method.
    Syncs to Sanity checkoutForm document.
    """

class FulfillmentStatus(models.TextChoices):
    PENDING = 'pending', 'Pending'
    PROCESSING = 'processing', 'Processing'
    SHIPPED = 'shipped', 'Shipped'
    DELIVERED = 'delivered', 'Delivered'
    CANCELLED = 'cancelled', 'Cancelled'