Clean Architecture

# service/use_cases/ports/input/i_place_order_use_case.py
# Input Port: defines the contract any caller must use to invoke this use case.
# The task.py (Frameworks & Drivers) depends on this interface, NOT on
# the concrete PlaceOrderInteractor. This decouples the delivery mechanism
# from the implementation.

from abc import ABC, abstractmethod
from service.use_cases.dtos.order_dtos import OrderResponse, PlaceOrderRequest

class IPlaceOrderUseCase(ABC):
    """Input port that PlaceOrderInteractor must implement."""

    @abstractmethod
    def execute(self, request: PlaceOrderRequest) -> OrderResponse:
        """Place a new order; raise domain exceptions on validation failure."""

# service/use_cases/ports/output/i_order_gateway.py
# Output Port: defines what THIS use case needs from the outside world.
# It lives in the Use Cases layer, the use case decides what it needs.
# Concrete implementations (InMemoryOrderGateway, PostgresOrderGateway)
# live in the Interface Adapters layer and implement this interface.

from abc import ABC, abstractmethod
from typing import List, Optional
from service.entities.order import Order

class IOrderGateway(ABC):
    """Output port for Order persistence. Concrete adapters live in interface_adapters."""

    @abstractmethod
    def save(self, order: Order) -> None: ...

    @abstractmethod
    def find_by_id(self, order_id: str) -> Optional[Order]: ...

    @abstractmethod
    def find_by_customer_id(self, customer_id: str) -> List[Order]: ...

    @abstractmethod
    def delete(self, order_id: str) -> None: ...

# service/use_cases/interactors/place_order_interactor.py
# The Interactor is the concrete use case implementation.
# It implements the Input Port (IPlaceOrderUseCase) and
# depends ONLY on Output Ports and Entities, never on Interface Adapters.

class PlaceOrderInteractor(IPlaceOrderUseCase):

    def __init__(
        self,
        order_gateway: IOrderGateway,      # <- output port
        product_gateway: IProductGateway,  # <- output port
        customer_gateway: ICustomerGateway,# <- output port
        pricing_service: OrderPricingService,  # <- use cases service
    ) -> None:
        self._order_gateway    = order_gateway
        self._product_gateway  = product_gateway
        self._customer_gateway = customer_gateway
        self._pricing          = pricing_service

    def execute(self, request: PlaceOrderRequest) -> OrderResponse:
        customer = self._customer_gateway.find_by_id(request.customer_id)
        if customer is None:
            raise CustomerNotFoundError(...)

        # Pass 1: validate stock for all items before mutating anything
        resolved = []
        for item_req in request.items:
            product = self._product_gateway.find_by_id(item_req.product_id)
            if not product.has_sufficient_stock(item_req.quantity):
                raise InsufficientStockError(...)
            resolved.append((product, item_req.quantity))

        # Pass 2: all items validated, safe to decrement stock
        order_items = []
        for product, quantity in resolved:
            product.decrement_stock(quantity)
            order_items.append(OrderItem(...))

        total = self._pricing.calculate_total(order_items)
        order = Order(id=str(uuid.uuid4()), customer_id=customer.id, items=order_items)
        order.set_total(total)
        self._order_gateway.save(order)
        return order_to_response(order)