Transactions Domain - Serializers Documentation

class SaleLineItemWriteSerializer(serializers.Serializer):
    """
    Write-only serializer for creating line items during transaction creation.
    Uses plain Serializer to avoid ModelSerializer's ForeignKey resolution issues.
    """

class SaleLineItemSerializer(serializers.ModelSerializer):
    """Serializer for SaleLineItem model (read operations)"""

def get_sku(self, obj):
    """Get SKU from snapshot, fallback to productVariant if empty"""
    if obj.skuSnapshot:
        return obj.skuSnapshot
    if obj.productVariant:
        return obj.productVariant.sku or ''
    return ''

def get_name(self, obj):
    """Get name from snapshot, fallback to productVariant if empty"""
    if obj.nameSnapshot:
        return obj.nameSnapshot
    if obj.productVariant:
        return obj.productVariant.name or ''
    return ''

def get_product_name(self, obj):
    """Get product name from productVariant"""
    if obj.productVariant and obj.productVariant.product:
        return obj.productVariant.product.name or ''
    return ''

def get_variant_name(self, obj):
    """Get variant name from productVariant"""
    if obj.productVariant:
        return obj.productVariant.name or ''
    return ''

class PaymentProcessorSerializer(serializers.ModelSerializer):

def validate_processor_type(self, value):
    """Validate processor type"""
    valid_types = ['stripe', 'square', 'paypal', 'custom']
    return validate_enum_choice(value, valid_types, "processor type")

def validate_processing_fee_percentage(self, value):
    """Validate processing fee percentage"""
    if value < 0 or value > 10:  # 0% to 10% reasonable range
        raise serializers.ValidationError("Processing fee percentage must be between 0 and 10")
    return value

def validate_processing_fee_fixed(self, value):
    """Validate fixed processing fee"""
    try:
        return FinancialValidator.validate_amount(
            value,
            min_amount=Decimal('0.00'),
            max_amount=Decimal('100.00'),
            field_name="processing fee"
        )
    except DjangoValidationError as e:
        raise serializers.ValidationError(str(e))

class PaymentMethodSerializer(serializers.ModelSerializer):

def validate_method_type(self, value):
    """Validate method type"""
    valid_types = ['cash', 'credit_card', 'debit_card', 'digital_wallet', 'store_credit', 'gift_card', 'other']
    return validate_enum_choice(value, valid_types, "method type")

def validate_configuration(self, value):
    """Validate configuration JSON"""
    if not value:
        return {}

    allowed_config_keys = [
        'terminal_id', 'merchant_id', 'api_version', 'webhook_url',
        'require_cvv', 'require_signature', 'timeout_seconds'
    ]

    try:
        return validate_json_data(value, allowed_config_keys, "configuration")
    except DjangoValidationError as e:
        raise serializers.ValidationError(str(e))

def validate(self, attrs):
    """Cross-field validation"""
    minimum_amount = attrs.get('minimum_amount')
    maximum_amount = attrs.get('maximum_amount')

    if minimum_amount and maximum_amount and minimum_amount >= maximum_amount:
        raise serializers.ValidationError("Minimum amount must be less than maximum amount")

    return attrs

class TransactionPaymentSerializer(serializers.ModelSerializer):

def validate_amount(self, value):
    """Validate payment amount"""
    try:
        return FinancialValidator.validate_amount(
            value,
            min_amount=Decimal('0.01'),
            max_amount=Decimal('100000.00'),
            field_name="payment amount"
        )
    except DjangoValidationError as e:
        raise serializers.ValidationError(str(e))

class SaleTransactionSerializer(serializers.ModelSerializer):
    """
    Serializer for SaleTransaction with JSONField line_items.
    Matches Sanity salesTransaction schema structure.
    """

def get_payment_records(self, obj):
    """Serialize payment records - import here to avoid circular import"""
    from nextango.apps.payments.serializers import TransactionPaymentSerializer
    return TransactionPaymentSerializer(obj.payment_records.all(), many=True).data

def get_return_records(self, obj):
    """Serialize return records - provides complete transaction lifecycle"""
    from .models import Return
    returns = Return.objects.filter(
        originalSaleId=obj
    ).prefetch_related('return_line_items', 'refunds')
    return ReturnSerializer(returns, many=True).data

def validate_status(self, value):
    """Validate transaction status"""
    valid_statuses = ['pending', 'partially_paid', 'completed', 'voided', 'refunded', 'partially_refunded', 'cancelled']
    return validate_enum_choice(value, valid_statuses, "transaction status")

def validate_fulfillmentMethod(self, value):
    """Validate fulfillment method"""
    valid_methods = ['pickup', 'ship', 'digital', 'counter_sale']
    return validate_enum_choice(value, valid_methods, "fulfillment method")

def validate_line_items(self, value):
    """Validate line items array"""
    if not value:
        raise serializers.ValidationError("Transaction must have at least one line item")

    if len(value) > 100:
        raise serializers.ValidationError("Transaction cannot have more than 100 line items")

    return value

class ReturnLineItemSerializer(serializers.ModelSerializer):
    """Serializer for ReturnLineItem model"""

class ReturnSerializer(serializers.ModelSerializer):
    """Serializer for Return model with refund-first architecture"""

def get_customer_name(self, obj):
    """Get customer name from original transaction"""
    if obj.customer and hasattr(obj.customer, 'user'):
        return obj.customer.user.name
    return None

def get_total_return_value(self, obj):
    """Get total return value"""
    return obj.get_total_return_value()

def get_refunds(self, obj):
    """Serialize refunds - import here to avoid circular import"""
    from nextango.apps.payments.serializers import RefundSerializer
    return RefundSerializer(obj.refunds.all(), many=True).data

class StoreCreditSerializer(serializers.ModelSerializer):

def validate_amount(self, value):
    """Validate credit amount"""
    try:
        return FinancialValidator.validate_amount(
            value,
            min_amount=Decimal('0.01'),
            max_amount=Decimal('10000.00'),
            field_name="credit amount"
        )
    except DjangoValidationError as e:
        raise serializers.ValidationError(str(e))

def validate_remaining_balance(self, value):
    """Validate remaining balance"""
    try:
        return FinancialValidator.validate_amount(
            value,
            min_amount=Decimal('0.00'),
            max_amount=Decimal('10000.00'),
            field_name="remaining balance"
        )
    except DjangoValidationError as e:
        raise serializers.ValidationError(str(e))

class CashDrawerEventSerializer(serializers.ModelSerializer):

def validate_event_type(self, value):
    """Validate event type"""
    valid_types = ['open', 'close', 'sale', 'return', 'cash_in', 'cash_out', 'deposit', 'till_count', 'no_sale']
    return validate_enum_choice(value, valid_types, "event type")

def validate_amount(self, value):
    """Validate cash amount"""
    try:
        return FinancialValidator.validate_amount(
            value,
            min_amount=Decimal('-10000.00'),  # Allow negative for cash out
            max_amount=Decimal('10000.00'),
            field_name="cash amount"
        )
    except DjangoValidationError as e:
        raise serializers.ValidationError(str(e))

class CartSerializer(serializers.ModelSerializer):

def validate_status(self, value):
    """Validate cart status"""
    valid_statuses = ['active', 'merged', 'completed']
    return validate_enum_choice(value, valid_statuses, "cart status")

class SaleTransactionCreateSerializer(serializers.Serializer):
    """
    Serializer for creating new sale transactions from POS systems.

    SECURITY: Financial fields (subtotal, taxAmount, totalAmount) are IGNORED by backend.
    Backend calculates all totals from line items using recalculate_totals().
    These fields remain in serializer for backwards compatibility but are not required.
    """

class AddSaleLineItemSerializer(serializers.Serializer):
    """Serializer for adding line items to transactions"""
    product_variant_id = serializers.UUIDField(required=True)
    quantity = serializers.IntegerField(min_value=1, max_value=1000, default=1)
    unit_price = serializers.DecimalField(max_digits=10, decimal_places=2, required=False, allow_null=True)

class RemoveSaleLineItemSerializer(serializers.Serializer):
    """Serializer for removing line items from transactions"""
    line_item_id = serializers.UUIDField(required=True)

class UpdateSaleLineItemQuantitySerializer(serializers.Serializer):
    """Serializer for updating line item quantities"""
    line_item_id = serializers.UUIDField(required=True)
    quantity = serializers.IntegerField(min_value=1, max_value=1000)

class ProcessPaymentRequestSerializer(serializers.Serializer):
    """Serializer for processing payment requests"""
    payment_method_id = serializers.IntegerField(required=True)
    amount = serializers.DecimalField(max_digits=10, decimal_places=2, required=False, allow_null=True)
    tendered_amount = serializers.DecimalField(max_digits=10, decimal_places=2, required=False, allow_null=True)

class VoidTransactionSerializer(serializers.Serializer):
    """Serializer for voiding transactions"""
    reason = serializers.CharField(max_length=1000, required=True)
    manager_override = serializers.BooleanField(default=False)

class AvailablePaymentMethodsSerializer(serializers.Serializer):
    """Serializer for getting available payment methods"""
    type = serializers.ChoiceField(choices=[('pos', 'POS'), ('online', 'Online')], default='pos')
    amount = serializers.DecimalField(max_digits=10, decimal_places=2, required=False, allow_null=True)

class OpenDrawerSerializer(serializers.Serializer):
    """Serializer for opening cash drawer"""
    store_id = serializers.UUIDField(required=True)
    register_id = serializers.CharField(max_length=50, required=True)
    shift_id = serializers.CharField(max_length=100, required=False)
    starting_amount = serializers.DecimalField(max_digits=10, decimal_places=2, default=Decimal('0.00'))

class CloseDrawerSerializer(serializers.Serializer):
    """Serializer for closing cash drawer"""
    store_id = serializers.UUIDField(required=True)
    register_id = serializers.CharField(max_length=50, required=True)
    shift_id = serializers.CharField(max_length=100, required=False)
    ending_amount = serializers.DecimalField(max_digits=10, decimal_places=2, required=True)
    cash_breakdown = serializers.JSONField(default=dict)

class CashOperationSerializer(serializers.Serializer):
    """Serializer for cash drawer operations (add/remove cash)"""
    store_id = serializers.UUIDField(required=True)
    register_id = serializers.CharField(max_length=50, required=True)
    amount = serializers.DecimalField(max_digits=10, decimal_places=2, required=True)
    reason = serializers.CharField(max_length=255, required=True)
    notes = serializers.CharField(max_length=1000, required=False, allow_blank=True)

class CashDrawerStatusSerializer(serializers.Serializer):
    """Serializer for getting cash drawer status"""
    store_id = serializers.UUIDField(required=True)
    register_id = serializers.CharField(max_length=50, required=True)

class TillCountSerializer(serializers.Serializer):
    """Serializer for recording till counts"""
    store_id = serializers.UUIDField(required=True)
    register_id = serializers.CharField(max_length=50, required=True)
    counted_amount = serializers.DecimalField(max_digits=10, decimal_places=2, required=True)
    cash_breakdown = serializers.JSONField(default=dict)
    notes = serializers.CharField(max_length=1000, required=False, allow_blank=True)

def validate_amount(self, value):
    try:
        return FinancialValidator.validate_amount(
            value,
            min_amount=Decimal('0.01'),
            max_amount=Decimal('100000.00'),
            field_name="payment amount"
        )
    except DjangoValidationError as e:
        raise serializers.ValidationError(str(e))

def validate_status(self, value):
    valid_statuses = ['pending', 'partially_paid', 'completed', 'voided', 'refunded', 'partially_refunded', 'cancelled']
    return validate_enum_choice(value, valid_statuses, "transaction status")

def validate(self, attrs):
    """Cross-field validation"""
    minimum_amount = attrs.get('minimum_amount')
    maximum_amount = attrs.get('maximum_amount')

    if minimum_amount and maximum_amount and minimum_amount >= maximum_amount:
        raise serializers.ValidationError("Minimum amount must be less than maximum amount")

    return attrs

def get_payment_records(self, obj):
    """Serialize payment records - import here to avoid circular import"""
    from nextango.apps.payments.serializers import TransactionPaymentSerializer
    return TransactionPaymentSerializer(obj.payment_records.all(), many=True).data

# IGNORED: Backend calculates these - frontend should NOT send them
subtotal = serializers.DecimalField(max_digits=10, decimal_places=2, required=False, allow_null=True)
taxAmount = serializers.DecimalField(max_digits=10, decimal_places=2, required=False, allow_null=True)
totalAmount = serializers.DecimalField(max_digits=10, decimal_places=2, required=False, allow_null=True)

SECURITY: Financial fields (subtotal, taxAmount, totalAmount) are IGNORED by backend.
Backend calculates all totals from line items using recalculate_totals().
These fields remain in serializer for backwards compatibility but are not required.

# Backend recalculates all totals
transaction.recalculate_totals(commit=True)