from django.db import models
from ralph.lib.dj_choices import Choices
from ralph.lib.transitions.fields import TransitionField
from ralph.lib.transitions.models import TransitionWorkflowBase

class OrderStatus(Choices):
    _ = Choices.Choice
    
    NEW = _('New')
    PROCESSING = _('Processing')
    PACKED = _('Packed')
    SHIPPED = _('Shipped')
    DELIVERED = _('Delivered')
    CANCELLED = _('Cancelled')

class Order(models.Model, metaclass=TransitionWorkflowBase):
    name = models.CharField(max_length=255)
    status = TransitionField(
        default=OrderStatus.NEW.id,
        choices=OrderStatus(),
    )
    customer = models.ForeignKey('Customer', on_delete=models.CASCADE)
    created = models.DateTimeField(auto_now_add=True)

from ralph.lib.transitions.decorators import transition_action

class Order(models.Model, metaclass=TransitionWorkflowBase):
    status = TransitionField(
        default=OrderStatus.NEW.id,
        choices=OrderStatus(),
    )
    
    @classmethod
    @transition_action
    def pack(cls, instances, request, **kwargs):
        """Pack the order for shipping."""
        for instance in instances:
            # Your custom logic here
            notify_warehouse(f'Pack order {instance.name}')
            instance.packed_at = timezone.now()
    
    @classmethod
    @transition_action(
        verbose_name='Ship to Customer'
    )
    def ship(cls, instances, request, **kwargs):
        """Ship the order to customer."""
        for instance in instances:
            carrier = assign_shipping_carrier(instance)
            notify_customer(
                f'Order {instance.name} shipped via {carrier}'
            )
            instance.shipped_at = timezone.now()

from ralph.admin import RalphAdmin, register
from ralph.lib.transitions.admin import TransitionAdminMixin
from myapp.models import Order

@register(Order)
class OrderAdmin(TransitionAdminMixin, RalphAdmin):
    list_display = ['name', 'status', 'customer', 'created']
    list_filter = ['status']
    
    # Show transition history tab (default: True)
    show_transition_history = True

from django import forms
from ralph.lib.transitions.decorators import transition_action

@classmethod
@transition_action(
    form_fields={
        'tracking_number': {
            'field': forms.CharField(max_length=100),
        },
        'carrier': {
            'field': forms.ChoiceField(
                choices=[('ups', 'UPS'), ('fedex', 'FedEx'), ('dhl', 'DHL')]
            ),
        },
        'estimated_delivery': {
            'field': forms.DateField(),
        }
    }
)
def ship(cls, instances, request, tracking_number, carrier, estimated_delivery, **kwargs):
    """Ship order with tracking information."""
    for instance in instances:
        instance.tracking_number = tracking_number
        instance.carrier = carrier
        instance.estimated_delivery = estimated_delivery
        send_tracking_email(instance)

ALLOW_COMMENT = True

@classmethod
@transition_action(
    form_fields={
        'comment': {
            'field': forms.CharField(widget=forms.Textarea),
            'condition': lambda obj: (obj.status > 2) and ALLOW_COMMENT
        },
        'priority': {
            'field': forms.BooleanField(required=False),
            'condition': lambda obj: obj.customer.is_vip
        }
    }
)
def pack(cls, instances, request, comment=None, priority=False, **kwargs):
    """Pack order with optional comment."""
    for instance in instances:
        if comment:
            instance.packing_notes = comment
        if priority:
            instance.priority_shipping = True
        notify_warehouse(instance)

@classmethod
@transition_action(
    form_fields={
        'credit_card': {
            'field': forms.CharField(max_length=16),
            'exclude_from_history': True  # Don't save to history
        },
        'amount': {
            'field': forms.DecimalField(),
        }
    }
)
def process_payment(cls, instances, request, credit_card, amount, **kwargs):
    """Process payment for order."""
    for instance in instances:
        charge_payment(credit_card, amount)
        instance.payment_status = 'paid'

def check_inventory(instances, requester):
    """Check if items are in stock."""
    errors = {}
    for instance in instances:
        if not instance.items_in_stock():
            errors[instance] = 'Items out of stock'
    return errors

@classmethod
@transition_action(
    precondition=check_inventory,
    verbose_name='Pack Order'
)
def pack(cls, instances, request, **kwargs):
    """Pack order (only if items in stock)."""
    for instance in instances:
        instance.pack_items()

@classmethod
@transition_action
def validate_order(cls, instances, request, **kwargs):
    """Validate order details."""
    for instance in instances:
        instance.validate()

@classmethod
@transition_action
def allocate_inventory(cls, instances, request, **kwargs):
    """Allocate items from inventory."""
    for instance in instances:
        instance.allocate_items()

@classmethod
@transition_action(
    run_after=['validate_order', 'allocate_inventory']
)
def create_invoice(cls, instances, request, **kwargs):
    """Create invoice after validation and allocation."""
    for instance in instances:
        instance.generate_invoice()

@classmethod
@transition_action
def assign_courier(cls, instances, request, **kwargs):
    """Assign courier for delivery."""
    history_kwargs = kwargs.get('history_kwargs', {})
    
    for instance in instances:
        courier = get_available_courier(instance.location)
        instance.courier = courier
        
        # Store in history
        history_kwargs[instance.pk]['courier_name'] = courier.name
        history_kwargs[instance.pk]['assignment_time'] = timezone.now().isoformat()

@classmethod
@transition_action
def calculate_shipping(cls, instances, request, **kwargs):
    """Calculate shipping cost."""
    shared_params = kwargs.get('shared_params', {})
    
    for instance in instances:
        cost = calculate_cost(instance)
        shared_params[instance.pk]['shipping_cost'] = cost

@classmethod
@transition_action(
    run_after=['calculate_shipping']
)
def send_invoice(cls, instances, request, **kwargs):
    """Send invoice including shipping cost."""
    shared_params = kwargs.get('shared_params', {})
    
    for instance in instances:
        shipping_cost = shared_params[instance.pk]['shipping_cost']
        send_invoice_email(instance, shipping_cost)

from ralph.attachments.models import Attachment

@classmethod
@transition_action(
    return_attachment=True
)
def generate_shipping_label(cls, instances, request, **kwargs):
    """Generate PDF shipping label."""
    attachments = []
    
    for instance in instances:
        pdf_content = create_shipping_label_pdf(instance)
        
        attachment = Attachment.objects.create(
            file=ContentFile(pdf_content, name=f'label_{instance.id}.pdf'),
            description=f'Shipping label for {instance.name}'
        )
        attachments.append(attachment)
    
    return attachments

@classmethod
@transition_action(
    is_async=True,
    verbose_name='Process Bulk Import'
)
def import_items(cls, instances, request, **kwargs):
    """Import items from external system (runs async)."""
    for instance in instances:
        # This runs in background worker
        items = fetch_from_external_api(instance.external_id)
        for item in items:
            instance.items.create(**item)
        instance.import_completed = True

from ralph.lib.transitions.exceptions import RescheduleAsyncTransitionActionLater

@classmethod
@transition_action(is_async=True)
def wait_for_external_approval(cls, instances, request, **kwargs):
    """Wait for external system approval."""
    for instance in instances:
        approval = check_external_approval_status(instance)
        
        if not approval.ready:
            # Reschedule to check again later
            raise RescheduleAsyncTransitionActionLater(
                'Approval not ready, will retry'
            )
        
        instance.approval_code = approval.code
        instance.approved_at = timezone.now()

@classmethod
@transition_action(
    disable_save_object=True
)
def preview_changes(cls, instances, request, **kwargs):
    """Preview changes without saving."""
    for instance in instances:
        # Modify instance but don't save
        instance.estimated_total = instance.calculate_total()
        # Instance is NOT saved automatically

# In settings.py
TRANSITION_TEMPLATES = [
    ('transitions/blue_theme.html', 'Blue Theme'),
    ('transitions/red_theme.html', 'Red Theme'),
    ('transitions/minimal.html', 'Minimal Layout'),
]

# Permission is auto-created as:
# "Can run {transition_name} transition"
# Codename: "can_run_{slugified_transition_name}_transition"

from ralph.lib.transitions.models import run_transition

# Run transition by name
order = Order.objects.get(id=123)
success, attachments = run_transition(
    instances=[order],
    transition_obj_or_name='Pack Order',
    field='status',
    requester=request.user,
    data={
        'tracking_number': 'TRK123456',
        'carrier': 'ups'
    }
)

if success:
    print('Transition executed successfully')
else:
    print('Transition failed')

# Get transitions for specific field
available = order.get_available_transitions_for_status(user=request.user)

for transition in available:
    print(f'{transition.name}: {transition.source} → {transition.target}')

# models.py
from django.db import models
from django.utils import timezone
from ralph.lib.dj_choices import Choices
from ralph.lib.transitions.fields import TransitionField
from ralph.lib.transitions.models import TransitionWorkflowBase
from ralph.lib.transitions.decorators import transition_action
from ralph.lib.mixins.models import AdminAbsoluteUrlMixin, TimeStampMixin

class OrderStatus(Choices):
    _ = Choices.Choice
    NEW = _('New')
    PROCESSING = _('Processing') 
    PACKED = _('Packed')
    SHIPPED = _('Shipped')
    DELIVERED = _('Delivered')
    CANCELLED = _('Cancelled')

class Order(AdminAbsoluteUrlMixin, TimeStampMixin, models.Model, metaclass=TransitionWorkflowBase):
    name = models.CharField(max_length=255)
    customer = models.ForeignKey('Customer', on_delete=models.CASCADE)
    status = TransitionField(
        default=OrderStatus.NEW.id,
        choices=OrderStatus(),
    )
    tracking_number = models.CharField(max_length=100, blank=True)
    shipped_at = models.DateTimeField(null=True, blank=True)
    
    def items_in_stock(self):
        return all(item.in_stock for item in self.items.all())
    
    @classmethod
    @transition_action(
        verbose_name='Validate and Process',
        precondition=lambda instances, requester: {
            instance: 'Items out of stock'
            for instance in instances
            if not instance.items_in_stock()
        }
    )
    def process_order(cls, instances, request, **kwargs):
        for instance in instances:
            instance.allocate_items()
            notify_warehouse(instance)
    
    @classmethod
    @transition_action(
        form_fields={
            'tracking_number': {'field': forms.CharField()},
            'carrier': {'field': forms.ChoiceField(
                choices=[('ups', 'UPS'), ('fedex', 'FedEx')]
            )}
        },
        return_attachment=True
    )
    def ship_order(cls, instances, request, tracking_number, carrier, **kwargs):
        attachments = []
        for instance in instances:
            instance.tracking_number = tracking_number
            instance.carrier = carrier
            instance.shipped_at = timezone.now()
            
            # Generate shipping label
            pdf = create_shipping_label(instance)
            attachment = Attachment.objects.create(
                file=ContentFile(pdf, name=f'label_{instance.id}.pdf')
            )
            attachments.append(attachment)
            
            send_tracking_email(instance)
        return attachments

# admin.py
from ralph.admin import RalphAdmin, register
from ralph.lib.transitions.admin import TransitionAdminMixin

@register(Order)
class OrderAdmin(TransitionAdminMixin, RalphAdmin):
    list_display = ['name', 'customer', 'status', 'created']
    list_filter = ['status']
    search_fields = ['name', 'tracking_number']
    show_transition_history = True