refactor(backend): reorganize domains into Core, Commerce, Ticketing and Shared

app/Domains/Commerce/Purchase/Services/Checkout/CatalogSelectionResolver.php

@@ -0,0 +1,98 @@
+<?php
+
+namespace App\Domains\Purchase\Services\Checkout;
+
+use App\Domains\Catalog\Models\CatalogItem;
+use App\Domains\Catalog\Models\Inventory;
+use App\Domains\Catalog\Models\Variant;
+use App\Domains\Tenant\Models\Tenant;
+use Illuminate\Validation\ValidationException;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+class CatalogSelectionResolver
+{
+    public function resolve(
+        Tenant $tenant,
+        int $catalogItemId,
+        ?int $variantId,
+        string $fieldPrefix = 'direct_items',
+    ): CatalogItem|Variant {
+        /** @var CatalogItem|null $catalogItem */
+        $catalogItem = CatalogItem::query()
+            ->whereKey($catalogItemId)
+            ->where('tenant_code', $tenant->codigo)
+            ->lockForUpdate()
+            ->first();
+
+        if ($catalogItem === null) {
+            throw new NotFoundHttpException('Catalog item not found for tenant.');
+        }
+
+        if ($catalogItem->isBundle()) {
+            if ($variantId !== null) {
+                throw ValidationException::withMessages([
+                    "{$fieldPrefix}.variant_id" => __('api.cart.bundle_variant_forbidden'),
+                ]);
+            }
+
+            if (! $catalogItem->bundleComponents()->exists()) {
+                throw ValidationException::withMessages([
+                    "{$fieldPrefix}.catalog_item_id" => __('api.cart.empty_bundle'),
+                ]);
+            }
+
+            if ($catalogItem->bundleComponents()
+                ->whereNotNull('component_variant_id')
+                ->whereHas('variant', fn ($query) => $query
+                    ->whereNotNull('sales_disabled_at')
+                    ->orWhereNotNull('replaced_by_variant_id'))
+                ->exists()) {
+                throw ValidationException::withMessages([
+                    "{$fieldPrefix}.catalog_item_id" => [__('api.cart.bundle_component_unavailable')],
+                ]);
+            }
+
+            return $catalogItem;
+        }
+
+        if ($variantId === null) {
+            if ($catalogItem->inventory_id === null) {
+                throw ValidationException::withMessages([
+                    "{$fieldPrefix}.variant_id" => __('api.cart.variant_required'),
+                ]);
+            }
+
+            $catalogItem->setRelation(
+                'inventory',
+                Inventory::query()->whereKey($catalogItem->inventory_id)->lockForUpdate()->firstOrFail(),
+            );
+
+            return $catalogItem;
+        }
+
+        /** @var Variant|null $variant */
+        $variant = Variant::query()
+            ->whereKey($variantId)
+            ->where('catalog_item_id', $catalogItem->id)
+            ->lockForUpdate()
+            ->first();
+
+        if ($variant === null) {
+            throw new NotFoundHttpException('Variant not found for catalog item.');
+        }
+
+        if (! $variant->isSellable()) {
+            throw ValidationException::withMessages([
+                "{$fieldPrefix}.variant_id" => [__('api.cart.variant_unavailable')],
+            ]);
+        }
+
+        $variant->setRelation('catalogItem', $catalogItem);
+        $variant->setRelation(
+            'inventory',
+            Inventory::query()->whereKey($variant->inventory_id)->lockForUpdate()->firstOrFail(),
+        );
+
+        return $variant;
+    }
+}

app/Domains/Commerce/Purchase/Services/Checkout/CompleteCheckoutService.php

@@ -0,0 +1,216 @@
+<?php
+
+namespace App\Domains\Purchase\Services\Checkout;
+
+use App\Domains\Cart\Models\CartItem;
+use App\Domains\Catalog\Services\StockReservationService;
+use App\Domains\Purchase\Models\Purchase;
+use App\Domains\Purchase\Services\PurchaseStateGuard;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Validation\ValidationException;
+
+class CompleteCheckoutService
+{
+    public function __construct(
+        private readonly StockReservationService $reservations,
+        private readonly SourceCartService $sourceCart,
+        private readonly PurchaseStateGuard $purchaseState,
+    ) {}
+
+    public function complete(Purchase $purchase): Purchase
+    {
+        return DB::transaction(function () use ($purchase): Purchase {
+            $purchase = $this->lockPurchase($purchase);
+            $this->purchaseState->assertNotExpired($purchase);
+
+            if ($purchase->payment_method === null) {
+                throw ValidationException::withMessages([
+                    'payment_method' => __('api.purchase.payment_method_required'),
+                ]);
+            }
+
+            if ($this->isTerminal($purchase)) {
+                return $this->loadPurchase($purchase);
+            }
+
+            $this->purchaseState->lockCurrentCart($purchase);
+
+            $purchase->update([
+                'status' => Purchase::STATUS_PENDING_PAYMENT,
+                'total' => $purchase->calculateCurrentTotalAmount(),
+            ]);
+
+            return $this->loadPurchase($purchase);
+        });
+    }
+
+    public function submitForReview(Purchase $purchase): Purchase
+    {
+        return DB::transaction(function () use ($purchase): Purchase {
+            $purchase = $this->lockPurchase($purchase);
+            $this->purchaseState->assertNotExpired($purchase);
+
+            if ($purchase->status === Purchase::STATUS_PAID) {
+                return $this->loadPurchase($purchase);
+            }
+
+            if ($purchase->status === Purchase::STATUS_IN_REVIEW) {
+                return $this->loadPurchase($purchase);
+            }
+
+            $this->purchaseState->lockCurrentCart($purchase);
+
+            if ($purchase->status !== Purchase::STATUS_PENDING_PAYMENT) {
+                throw ValidationException::withMessages([
+                    'purchase' => __('api.purchase.not_available_for_review'),
+                ]);
+            }
+
+            $purchase->update([
+                'status' => Purchase::STATUS_IN_REVIEW,
+            ]);
+            $this->reservations->clearExpirationForReview($purchase);
+
+            return $this->loadPurchase($purchase);
+        });
+    }
+
+    public function confirm(Purchase $purchase): void
+    {
+        DB::transaction(function () use ($purchase): void {
+            $purchase = $this->lockPurchase($purchase);
+            $this->purchaseState->assertNotExpired($purchase);
+
+            if ($purchase->status === Purchase::STATUS_PAID) {
+                return;
+            }
+
+            if (in_array($purchase->status, [
+                Purchase::STATUS_CANCELLED,
+                Purchase::STATUS_REJECTED,
+                Purchase::STATUS_EXPIRED,
+                Purchase::STATUS_SUPERSEDED,
+            ], true)) {
+                throw ValidationException::withMessages([
+                    'purchase' => __('api.purchase.cannot_confirm'),
+                ]);
+            }
+
+            if (! $purchase->items()->exists()) {
+                throw ValidationException::withMessages([
+                    'items' => __('api.purchase.inconsistent_reservation'),
+                ]);
+            }
+
+            $cart = $this->purchaseState->lockCurrentCart($purchase);
+
+            if ($cart->status === 'converted' && $cart->trashed()) {
+                return;
+            }
+
+            if (! in_array($cart->status, ['active', 'checkout'], true)) {
+                throw ValidationException::withMessages([
+                    'items' => __('api.purchase.inconsistent_reservation'),
+                ]);
+            }
+
+            $cartItems = $cart->items()->orderBy('id')->lockForUpdate()->get();
+            if ($cartItems->isEmpty()) {
+                throw ValidationException::withMessages([
+                    'items' => __('api.purchase.inconsistent_reservation'),
+                ]);
+            }
+
+            $snapshotQuantities = $purchase->items()
+                ->lockForUpdate()
+                ->get(['source_catalog_item_id', 'source_variant_id', 'cantidad'])
+                ->groupBy(fn ($item): string => $this->itemKey(
+                    (int) $item->source_catalog_item_id,
+                    $item->source_variant_id === null ? null : (int) $item->source_variant_id,
+                ))
+                ->map(fn (Collection $items): int => (int) $items->sum('cantidad'))
+                ->sortKeys()
+                ->all();
+            $cartQuantities = $cartItems
+                ->groupBy(fn (CartItem $item): string => $this->itemKey(
+                    (int) $item->catalog_item_id,
+                    $item->variant_id === null ? null : (int) $item->variant_id,
+                ))
+                ->map(fn (Collection $items): int => (int) $items->sum('cantidad'))
+                ->sortKeys()
+                ->all();
+
+            if ($snapshotQuantities !== $cartQuantities) {
+                throw ValidationException::withMessages([
+                    'items' => __('api.purchase.inconsistent_reservation'),
+                ]);
+            }
+
+            $this->loadCartItems($cartItems);
+
+            foreach ($cartItems as $cartItem) {
+                $selection = $cartItem->selectedItem();
+                if ($selection === null) {
+                    throw ValidationException::withMessages([
+                        'items' => __('api.purchase.inconsistent_reservation'),
+                    ]);
+                }
+
+            }
+
+            try {
+                $this->reservations->commit($purchase);
+            } catch (\InvalidArgumentException) {
+                throw ValidationException::withMessages([
+                    'items' => __('api.purchase.inconsistent_reservation'),
+                ]);
+            }
+
+            $this->sourceCart->finalize($purchase);
+        });
+    }
+
+    private function isTerminal(Purchase $purchase): bool
+    {
+        return in_array($purchase->status, [
+            Purchase::STATUS_PAID,
+            Purchase::STATUS_IN_REVIEW,
+            Purchase::STATUS_CANCELLED,
+            Purchase::STATUS_REJECTED,
+            Purchase::STATUS_EXPIRED,
+            Purchase::STATUS_SUPERSEDED,
+        ], true);
+    }
+
+    private function lockPurchase(Purchase $purchase): Purchase
+    {
+        /** @var Purchase */
+        return Purchase::query()->lockForUpdate()->findOrFail($purchase->getKey());
+    }
+
+    private function loadPurchase(Purchase $purchase): Purchase
+    {
+        return $purchase->load(['items.imageAttachment', 'stockReservation']);
+    }
+
+    private function itemKey(int $catalogItemId, ?int $variantId): string
+    {
+        return $catalogItemId.':'.($variantId ?? 'none');
+    }
+
+    /** @param Collection<int, CartItem> $cartItems */
+    private function loadCartItems(Collection $cartItems): void
+    {
+        $cartItems->load([
+            'catalogItem.inventory',
+            'catalogItem.attachments',
+            'variant.inventory',
+            'variant.attachments',
+            'variant.catalogItem',
+            'variant.definitions.itemAttribute.attribute',
+            'variant.eventDates',
+            'variant.eventDate',
+        ]);
+    }
+}

app/Domains/Commerce/Purchase/Services/Checkout/EditCheckoutService.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace App\Domains\Purchase\Services\Checkout;
+
+use App\Domains\Purchase\Models\Purchase;
+use App\Domains\Purchase\Services\PurchaseStateGuard;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Validation\ValidationException;
+
+class EditCheckoutService
+{
+    public function __construct(
+        private readonly PurchaseResponseLoader $responses,
+        private readonly PurchaseStateGuard $purchaseState,
+    ) {}
+
+    /** @param array<string, string> $customerData */
+    public function updateCustomer(Purchase $purchase, array $customerData): Purchase
+    {
+        return DB::transaction(function () use ($purchase, $customerData): Purchase {
+            /** @var Purchase $purchase */
+            $purchase = Purchase::query()->lockForUpdate()->findOrFail($purchase->getKey());
+            $this->purchaseState->assertNotExpired($purchase);
+
+            if (! in_array($purchase->status, [
+                Purchase::STATUS_CREATED,
+                Purchase::STATUS_PENDING_PAYMENT,
+            ], true)) {
+                throw ValidationException::withMessages([
+                    'purchase' => __('api.purchase.not_editable'),
+                ]);
+            }
+
+            $this->purchaseState->lockCurrentCart($purchase);
+
+            $purchase->update($customerData);
+
+            return $this->responses->load($purchase);
+        });
+    }
+}

app/Domains/Commerce/Purchase/Services/Checkout/InsufficientStockMessageBuilder.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Domains\Purchase\Services\Checkout;
+
+use App\Domains\Catalog\Enums\InventorySubject;
+use App\Domains\Catalog\Models\CatalogItem;
+use App\Domains\Catalog\Models\Variant;
+
+class InsufficientStockMessageBuilder
+{
+    public function build(
+        CatalogItem $catalogItem,
+        CatalogItem|Variant $selection,
+        int $availableQuantity,
+    ): string {
+        return match ($catalogItem->inventory_subject) {
+            InventorySubject::Seat => __('api.purchase.stock.seat_unavailable', [
+                'selection' => $selection->getSelectionLabel(),
+            ]),
+            InventorySubject::Ticket => __('api.purchase.stock.ticket_unavailable', [
+                'selection' => $selection->getSelectionLabel(),
+            ]),
+            InventorySubject::Product => __('api.purchase.stock.product_unavailable', [
+                'selection' => $this->productSelectionLabel($catalogItem, $selection),
+                'max' => $availableQuantity,
+            ]),
+        };
+    }
+
+    private function productSelectionLabel(
+        CatalogItem $catalogItem,
+        CatalogItem|Variant $selection,
+    ): string {
+        if ($selection instanceof CatalogItem) {
+            return $selection->getSelectionLabel();
+        }
+
+        return __('api.purchase.stock.product_selection', [
+            'product' => $catalogItem->getName(),
+            'selection' => $selection->getSelectionLabel(),
+        ]);
+    }
+}

app/Domains/Commerce/Purchase/Services/Checkout/PurchaseItemSnapshotFactory.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace App\Domains\Purchase\Services\Checkout;
+
+use App\Domains\Attachable\Models\Attachment;
+use App\Domains\Cart\Models\CartItem;
+use App\Domains\Catalog\Models\Variant;
+use Illuminate\Support\Collection;
+
+class PurchaseItemSnapshotFactory
+{
+    /**
+     * @param  Collection<int, CartItem>  $cartItems
+     * @return array<int, array<string, mixed>>
+     */
+    public function fromCartItems(Collection $cartItems): array
+    {
+        return $cartItems
+            ->map(function (CartItem $item): array {
+                $selectedItem = $item->selectedItem();
+                $quantity = (int) $item->cantidad;
+                $unitPrice = $selectedItem?->getPrice() ?? 0;
+
+                return [
+                    'source_catalog_item_id' => $item->catalog_item_id,
+                    'source_variant_id' => $item->variant_id,
+                    'image_attachment_id' => $this->firstImageAttachment($item)?->id,
+                    'nombre' => $item->catalogItem->nombre,
+                    'descripcion' => $selectedItem?->getDescription(),
+                    'slug' => $item->catalogItem->slug,
+                    'item_nombre' => $selectedItem->getName(),
+                    'variant_attributes' => $item->variant === null
+                        ? []
+                        : $this->snapshotAttributes($item->variant),
+                    'cantidad' => $quantity,
+                    'precio_unitario' => $unitPrice,
+                    'discount_total' => null,
+                    'tax_total' => null,
+                    'total' => $unitPrice * $quantity,
+                ];
+            })
+            ->all();
+    }
+
+    private function firstImageAttachment(CartItem $item): ?Attachment
+    {
+        return $item->variant?->attachments->first()
+            ?? $item->catalogItem?->attachments->first();
+    }
+
+    /** @return array<int, array{name: string, value: mixed}> */
+    private function snapshotAttributes(Variant $variant): array
+    {
+        $attributes = $variant->definitions
+            ->groupBy('item_attribute_id')
+            ->map(function ($definitions): array {
+                $itemAttribute = $definitions->first()?->itemAttribute;
+                $values = $definitions->pluck('value')->values();
+
+                return [
+                    'name' => (string) ($itemAttribute?->attribute?->nombre ?? ''),
+                    'value' => $itemAttribute?->allow_multi_select
+                        ? $values->all()
+                        : $values->first(),
+                ];
+            })
+            ->filter(fn (array $attribute): bool => $attribute['name'] !== '' || $attribute['value'] !== null)
+            ->values();
+
+        $eventDates = $variant->selectedEventDates();
+        if ($eventDates->isNotEmpty()) {
+            $attributes->prepend([
+                'name' => 'Fecha',
+                'value' => $eventDates
+                    ->map(fn ($eventDate): string => $eventDate->date->format('Y-m-d'))
+                    ->values()
+                    ->all(),
+            ]);
+        }
+
+        return $attributes->all();
+    }
+}

app/Domains/Commerce/Purchase/Services/Checkout/PurchaseResponseLoader.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Domains\Purchase\Services\Checkout;
+
+use App\Domains\Purchase\Models\Purchase;
+
+class PurchaseResponseLoader
+{
+    public function load(Purchase $purchase): Purchase
+    {
+        $relations = ['tenant', 'items.imageAttachment', 'stockReservation'];
+
+        if (
+            $purchase->status === Purchase::STATUS_IN_REVIEW
+            && $purchase->payment_method === 'transfer'
+        ) {
+            $relations[] = 'telepagosPaymentCandidates.payment';
+        }
+
+        return $purchase->load($relations);
+    }
+}

app/Domains/Commerce/Purchase/Services/Checkout/ReleaseCheckoutService.php

@@ -0,0 +1,262 @@
+<?php
+
+namespace App\Domains\Purchase\Services\Checkout;
+
+use App\Domains\Cart\Models\Cart;
+use App\Domains\Cart\Models\CartItem;
+use App\Domains\Catalog\Models\StockReservation;
+use App\Domains\Catalog\Services\StockReservationService;
+use App\Domains\Purchase\Exceptions\PurchaseExpiredException;
+use App\Domains\Purchase\Models\Purchase;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Validation\ValidationException;
+
+class ReleaseCheckoutService
+{
+    public function __construct(
+        private readonly StockReservationService $reservations,
+    ) {}
+
+    public function cancel(Purchase $purchase): Purchase
+    {
+        return $this->release($purchase, Purchase::STATUS_CANCELLED);
+    }
+
+    public function cancelFromAdmin(Purchase $purchase): Purchase
+    {
+        return $this->release($purchase, Purchase::STATUS_CANCELLED, allowInReviewCancellation: true);
+    }
+
+    public function expire(Purchase $purchase): Purchase
+    {
+        return $this->release($purchase, Purchase::STATUS_EXPIRED);
+    }
+
+    private function release(
+        Purchase $purchase,
+        string $targetStatus,
+        bool $allowInReviewCancellation = false,
+    ): Purchase {
+        return DB::transaction(function () use (
+            $purchase,
+            $targetStatus,
+            $allowInReviewCancellation,
+        ): Purchase {
+            $purchase = $this->lockPurchase($purchase);
+
+            if ($purchase->status === Purchase::STATUS_EXPIRED
+                && $targetStatus === Purchase::STATUS_CANCELLED) {
+                return $this->loadPurchase($purchase);
+            }
+
+            if ($purchase->status === Purchase::STATUS_EXPIRED
+                && $targetStatus !== Purchase::STATUS_EXPIRED) {
+                throw new PurchaseExpiredException;
+            }
+
+            if ($purchase->status === Purchase::STATUS_PAID) {
+                if ($targetStatus === Purchase::STATUS_EXPIRED) {
+                    return $this->loadPurchase($purchase);
+                }
+
+                throw ValidationException::withMessages([
+                    'purchase' => __('api.purchase.paid_cannot_cancel'),
+                ]);
+            }
+
+            if (
+                $purchase->status === Purchase::STATUS_IN_REVIEW
+                && $targetStatus === Purchase::STATUS_CANCELLED
+                && ! $allowInReviewCancellation
+            ) {
+                return $this->createNewCartWithoutCancelling($purchase);
+            }
+
+            if ($this->isAlreadyReleased($purchase)) {
+                return $this->loadPurchase($purchase);
+            }
+
+            $cart = $purchase->cart()->withTrashed()->lockForUpdate()->first();
+
+            // Leaving checkout is allowed at the exact instant the reservation
+            // expires. Finish the expiration while holding the purchase lock so
+            // the request is idempotent with the scheduled expiration job.
+            if ($targetStatus === Purchase::STATUS_CANCELLED
+                && $this->hasOverdueActiveReservation($purchase)) {
+                $targetStatus = Purchase::STATUS_EXPIRED;
+            }
+
+            if ($targetStatus === Purchase::STATUS_CANCELLED
+                && $cart?->status === 'active'
+                && in_array($purchase->status, [
+                    Purchase::STATUS_CREATED,
+                    Purchase::STATUS_PENDING_PAYMENT,
+                ], true)) {
+                if ($this->hasUnavailableVariants($cart)) {
+                    $this->releasePurchaseReservations($purchase, $targetStatus, $cart);
+                    $cart->update([
+                        'status' => Cart::STATUS_EXPIRED,
+                        'current_purchase_id' => null,
+                        'current_stock_reservation_id' => null,
+                    ]);
+                } else {
+                    $this->reservations->returnToCart($purchase, $cart);
+                }
+                $purchase->update(['status' => Purchase::STATUS_CANCELLED]);
+
+                return $this->loadPurchase($purchase);
+            }
+
+            if (
+                $targetStatus === Purchase::STATUS_EXPIRED
+                && (! in_array($purchase->status, [
+                    Purchase::STATUS_CREATED,
+                    Purchase::STATUS_PENDING_PAYMENT,
+                ], true) || ! $this->hasOverdueActiveReservation($purchase))
+            ) {
+                return $this->loadPurchase($purchase);
+            }
+
+            $this->releasePurchaseReservations($purchase, $targetStatus, $cart);
+
+            $purchase->update(['status' => $targetStatus]);
+
+            return $this->loadPurchase($purchase);
+        });
+    }
+
+    private function hasUnavailableVariants(Cart $cart): bool
+    {
+        return $cart->items()
+            ->whereNotNull('variant_id')
+            ->with(['variant.eventDate', 'variant.eventDates'])
+            ->lockForUpdate()
+            ->get()
+            ->contains(fn (CartItem $item): bool => $item->variant === null
+                || ! $item->variant->isSellable());
+    }
+
+    private function releasePurchaseReservations(
+        Purchase $purchase,
+        string $targetStatus,
+        ?Cart $cart,
+    ): void {
+        try {
+            $this->reservations->releaseForPurchase(
+                $purchase,
+                $targetStatus === Purchase::STATUS_EXPIRED
+                    ? StockReservation::STATUS_EXPIRED
+                    : StockReservation::STATUS_RELEASED,
+                $targetStatus === Purchase::STATUS_CANCELLED
+                    ? StockReservationService::REASON_PURCHASE_CANCELLED
+                    : ($targetStatus === Purchase::STATUS_REJECTED
+                        ? StockReservationService::REASON_PAYMENT_REJECTED
+                        : null),
+            );
+        } catch (\InvalidArgumentException) {
+            throw ValidationException::withMessages([
+                'items' => __('api.purchase.inconsistent_reservation'),
+            ]);
+        }
+
+        if ($cart === null) {
+            return;
+        }
+
+        if ($targetStatus === Purchase::STATUS_EXPIRED
+            && in_array($cart->status, [Cart::STATUS_ACTIVE, Cart::STATUS_CHECKOUT], true)) {
+            Cart::query()
+                ->whereKey($cart->getKey())
+                ->where('current_purchase_id', $purchase->getKey())
+                ->where('current_stock_reservation_id', $purchase->stock_reservation_id)
+                ->update([
+                    'status' => Cart::STATUS_EXPIRED,
+                    'current_purchase_id' => null,
+                ]);
+
+            return;
+        }
+
+        if ($cart->status === Cart::STATUS_ACTIVE) {
+            $cartUpdate = [
+                'current_purchase_id' => null,
+                'current_stock_reservation_id' => null,
+            ];
+
+            Cart::query()
+                ->whereKey($cart->getKey())
+                ->where('current_purchase_id', $purchase->getKey())
+                ->update($cartUpdate);
+
+            return;
+        }
+
+        if ($cart->status !== Cart::STATUS_CHECKOUT) {
+            return;
+        }
+
+        if (! $cart->trashed()) {
+            $cart->update(['status' => Cart::STATUS_CONVERTED]);
+            $cart->delete();
+        }
+    }
+
+    private function createNewCartWithoutCancelling(Purchase $purchase): Purchase
+    {
+        return DB::transaction(function () use ($purchase): Purchase {
+            $purchase = $this->lockPurchase($purchase);
+
+            if ($purchase->status !== Purchase::STATUS_IN_REVIEW || $purchase->user_id === null) {
+                return $this->loadPurchase($purchase);
+            }
+
+            /** @var Cart|null $sourceCart */
+            $sourceCart = $purchase->cart()->withTrashed()->lockForUpdate()->first();
+            if ($sourceCart !== null && ! $sourceCart->trashed() && $sourceCart->status === 'active') {
+                $sourceCart->update(['status' => 'checkout']);
+            }
+
+            Cart::query()->firstOrCreate([
+                'tenant_codigo' => $purchase->tenant_codigo,
+                'user_id' => $purchase->user_id,
+                'guest_token' => null,
+                'status' => 'active',
+                'origin' => Cart::ORIGIN_USER,
+            ]);
+
+            return $this->loadPurchase($purchase);
+        });
+    }
+
+    private function isAlreadyReleased(Purchase $purchase): bool
+    {
+        return in_array($purchase->status, [
+            Purchase::STATUS_CANCELLED,
+            Purchase::STATUS_REJECTED,
+            Purchase::STATUS_EXPIRED,
+            Purchase::STATUS_SUPERSEDED,
+        ], true);
+    }
+
+    private function lockPurchase(Purchase $purchase): Purchase
+    {
+        /** @var Purchase */
+        return Purchase::query()->lockForUpdate()->findOrFail($purchase->getKey());
+    }
+
+    private function loadPurchase(Purchase $purchase): Purchase
+    {
+        return $purchase->load(['items.imageAttachment', 'stockReservation']);
+    }
+
+    private function hasOverdueActiveReservation(Purchase $purchase): bool
+    {
+        /** @var StockReservation|null $reservation */
+        $reservation = $purchase->stockReservation()->lockForUpdate()->first();
+
+        return $reservation !== null
+            && $reservation->status === StockReservation::STATUS_ACTIVE
+            && $reservation->expires_at !== null
+            && ! $reservation->expires_at->isFuture();
+    }
+}

app/Domains/Commerce/Purchase/Services/Checkout/SourceCartService.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Domains\Purchase\Services\Checkout;
+
+use App\Domains\Cart\Models\Cart;
+use App\Domains\Purchase\Models\Purchase;
+
+class SourceCartService
+{
+    public function finalize(Purchase $purchase): void
+    {
+        $sourceCart = $this->findSourceCart($purchase);
+
+        if ($sourceCart === null || $sourceCart->trashed()) {
+            return;
+        }
+
+        $sourceCart->update([
+            'status' => 'converted',
+            'guest_token' => null,
+        ]);
+        $sourceCart->delete();
+    }
+
+    private function findSourceCart(Purchase $purchase): ?Cart
+    {
+        if ($purchase->cart_id === null) {
+            return null;
+        }
+
+        /** @var Cart|null */
+        return Cart::withTrashed()
+            ->whereKey($purchase->cart_id)
+            ->lockForUpdate()
+            ->first();
+    }
+}

app/Domains/Commerce/Purchase/Services/Checkout/StartCheckoutService.php

@@ -0,0 +1,444 @@
+<?php
+
+namespace App\Domains\Purchase\Services\Checkout;
+
+use App\Domains\Cart\Models\Cart;
+use App\Domains\Cart\Models\CartItem;
+use App\Domains\Cart\Services\CartVariantReplacementService;
+use App\Domains\Catalog\Exceptions\StockReservationExpiredException;
+use App\Domains\Catalog\Models\CatalogItem;
+use App\Domains\Catalog\Models\Variant;
+use App\Domains\Catalog\Services\CatalogInventoryService;
+use App\Domains\Catalog\Services\StockReservationService;
+use App\Domains\Purchase\Exceptions\InsufficientStockException;
+use App\Domains\Purchase\Models\Purchase;
+use App\Domains\Purchase\Services\UserPurchaseLimitService;
+use App\Domains\Tenant\Models\Tenant;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Validation\ValidationException;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+class StartCheckoutService
+{
+    public function __construct(
+        private readonly CatalogInventoryService $inventory,
+        private readonly StockReservationService $reservations,
+        private readonly UserPurchaseLimitService $purchaseLimits,
+        private readonly CatalogSelectionResolver $selections,
+        private readonly InsufficientStockMessageBuilder $stockMessages,
+        private readonly PurchaseResponseLoader $responses,
+        private readonly PurchaseItemSnapshotFactory $snapshots,
+        private readonly CartVariantReplacementService $variantReplacements,
+    ) {}
+
+    /** @param array<string, mixed> $purchaseData */
+    public function start(Tenant $tenant, int $userId, array $purchaseData): Purchase
+    {
+        return DB::transaction(function () use ($tenant, $userId, $purchaseData): Purchase {
+            /** @var Tenant $tenant */
+            $tenant = Tenant::query()
+                ->lockForUpdate()
+                ->findOrFail($tenant->getKey());
+
+            $directItems = $purchaseData['direct_items'] ?? null;
+            $cartId = isset($purchaseData['cart_id']) ? (int) $purchaseData['cart_id'] : null;
+            unset($purchaseData['direct_items'], $purchaseData['cart_id']);
+
+            if (is_array($directItems)) {
+                return $this->startDirectItems(
+                    $tenant,
+                    $userId,
+                    $purchaseData,
+                    $directItems,
+                );
+            }
+
+            if ($cartId === null) {
+                throw ValidationException::withMessages([
+                    'cart_id' => __('api.purchase.source_required'),
+                ]);
+            }
+
+            return $this->startFromCart($tenant, $userId, $purchaseData, $cartId);
+        });
+    }
+
+    /**
+     * @param  array<string, mixed>  $purchaseData
+     * @param  array<int, array<string, mixed>>  $directItems
+     */
+    private function startDirectItems(
+        Tenant $tenant,
+        int $userId,
+        array $purchaseData,
+        array $directItems,
+    ): Purchase {
+        $lines = collect(array_values($directItems))
+            ->map(function (array $item, int $index): array {
+                return [
+                    'index' => $index,
+                    'catalog_item_id' => (int) $item['catalog_item_id'],
+                    'variant_id' => isset($item['variant_id']) ? (int) $item['variant_id'] : null,
+                    'quantity' => (int) $item['cantidad'],
+                    'field' => "direct_items.{$index}",
+                ];
+            })
+            ->groupBy(fn (array $line): string => sprintf(
+                '%d:%s',
+                $line['catalog_item_id'],
+                $line['variant_id'] === null ? 'none' : (string) $line['variant_id'],
+            ))
+            ->map(function (Collection $duplicateLines): array {
+                $line = $duplicateLines->first();
+                $line['quantity'] = (int) $duplicateLines->sum('quantity');
+
+                return $line;
+            })
+            ->sortBy(fn (array $line): string => sprintf(
+                '%020d:%020d',
+                $line['catalog_item_id'],
+                $line['variant_id'] ?? 0,
+            ))
+            ->values();
+
+        $resolvedLines = $lines->map(function (array $line) use ($tenant): array {
+            $selection = $this->selections->resolve(
+                $tenant,
+                $line['catalog_item_id'],
+                $line['variant_id'],
+                $line['field'],
+            );
+
+            return [
+                ...$line,
+                'selection' => $selection,
+                'catalog_item' => $selection instanceof Variant
+                    ? $selection->catalogItem
+                    : $selection,
+            ];
+        });
+
+        $resolvedLines
+            ->groupBy(fn (array $line): int => $line['catalog_item']->getKey())
+            ->each(function (Collection $catalogLines) use ($userId): void {
+                /** @var CatalogItem $catalogItem */
+                $catalogItem = $catalogLines->first()['catalog_item'];
+                $availableQuantities = $catalogLines
+                    ->map(fn (array $line): ?int => $this->inventory->availableQuantity($line['selection']));
+                $maximumAddableCeiling = $availableQuantities->contains(null)
+                    ? null
+                    : (int) $availableQuantities->sum();
+                $this->purchaseLimits->assertCanPurchase(
+                    $catalogItem,
+                    $userId,
+                    (int) $catalogLines->sum('quantity'),
+                    maximumAddableCeiling: $maximumAddableCeiling,
+                    field: 'direct_items',
+                );
+            });
+
+        $unavailableItems = $resolvedLines
+            ->map(function (array $line): ?array {
+                $availableQuantity = $this->inventory->availableQuantity($line['selection']);
+
+                if ($availableQuantity === null || $availableQuantity >= $line['quantity']) {
+                    return null;
+                }
+
+                return $this->unavailableItem($line, $availableQuantity);
+            })
+            ->filter()
+            ->values()
+            ->all();
+
+        if ($unavailableItems !== []) {
+            throw new InsufficientStockException($unavailableItems);
+        }
+
+        $cart = Cart::query()->create([
+            'tenant_codigo' => $tenant->codigo,
+            'user_id' => $userId,
+            'guest_token' => null,
+            'status' => 'checkout',
+            'origin' => Cart::ORIGIN_DIRECT_CHECKOUT,
+        ]);
+
+        $cartItems = collect();
+        foreach ($resolvedLines as $line) {
+            $cartItem = $cart->items()->create([
+                'catalog_item_id' => $line['catalog_item_id'],
+                'variant_id' => $line['variant_id'],
+                'cantidad' => $line['quantity'],
+            ]);
+
+            $cartItem->setRelation('catalogItem', $line['catalog_item']);
+            $cartItem->setRelation('variant', $line['selection'] instanceof Variant ? $line['selection'] : null);
+            $cartItems->push($cartItem);
+        }
+
+        try {
+            $this->reservations->syncCart($cart);
+        } catch (\InvalidArgumentException) {
+            $unavailable = $resolvedLines
+                ->map(function (array $line): ?array {
+                    $availableQuantity = $this->inventory->availableQuantity($line['selection']);
+
+                    return $availableQuantity !== null && $availableQuantity < $line['quantity']
+                        ? $this->unavailableItem($line, $availableQuantity)
+                        : null;
+                })
+                ->filter()
+                ->values()
+                ->all();
+
+            throw new InsufficientStockException($unavailable !== [] ? $unavailable : [
+                $this->unavailableItem($resolvedLines->first(), 0),
+            ]);
+        }
+
+        $purchase = $this->createPurchase(
+            $tenant,
+            $userId,
+            $purchaseData,
+            (float) $resolvedLines->sum(
+                fn (array $line): float => $line['selection']->getPrice() * $line['quantity'],
+            ),
+            $cart->getKey(),
+        );
+        $cart->update(['current_purchase_id' => $purchase->getKey()]);
+        $this->reservations->attachToPurchase($cart, $purchase, $this->checkoutExpiration());
+
+        $cartItems = $cart->items()->orderBy('id')->lockForUpdate()->get();
+        $this->loadCartItems($cartItems);
+        $purchase->items()->createMany($this->snapshots->fromCartItems($cartItems));
+
+        return $this->loadPurchase($purchase);
+    }
+
+    /**
+     * @param  array<string, mixed>  $line
+     * @return array{
+     *     index: int,
+     *     catalog_item_id: int,
+     *     variant_id: int|null,
+     *     requested_quantity: int,
+     *     available_quantity: int,
+     *     message: string
+     * }
+     */
+    private function unavailableItem(array $line, int $availableQuantity): array
+    {
+        return [
+            'index' => $line['index'],
+            'catalog_item_id' => $line['catalog_item_id'],
+            'variant_id' => $line['variant_id'],
+            'requested_quantity' => $line['quantity'],
+            'available_quantity' => $availableQuantity,
+            'message' => $this->stockMessages->build(
+                $line['catalog_item'],
+                $line['selection'],
+                $availableQuantity,
+            ),
+        ];
+    }
+
+    /** @param array<string, mixed> $purchaseData */
+    private function startFromCart(
+        Tenant $tenant,
+        int $userId,
+        array $purchaseData,
+        int $cartId,
+    ): Purchase {
+        $cart = $this->resolveCart($tenant, $userId, $cartId);
+        $this->variantReplacements->replaceHistoricalVariants($cart);
+        $cartItems = $cart->items()->lockForUpdate()->get();
+
+        if ($cartItems->isEmpty()) {
+            throw ValidationException::withMessages([
+                'cart_id' => __('api.purchase.empty_cart'),
+            ]);
+        }
+
+        $this->loadCartItems($cartItems);
+        $this->verifyTenantItems($tenant, $cartItems);
+        $this->assertCartPurchaseLimits($tenant, $userId, $cartItems, $cart->getKey());
+        $cart->setRelation('items', $cartItems);
+        $this->reservations->syncCart($cart);
+
+        $purchase = $this->createPurchase(
+            $tenant,
+            $userId,
+            $purchaseData,
+            $cart->getTotalAmount(),
+            $cart->getKey(),
+        );
+        $cart->update(['current_purchase_id' => $purchase->getKey()]);
+        $this->reservations->attachToPurchase($cart, $purchase, $this->checkoutExpiration());
+        $purchase->items()->createMany($this->snapshots->fromCartItems($cartItems));
+
+        return $this->loadPurchase($purchase);
+    }
+
+    private function resolveCart(Tenant $tenant, int $userId, int $cartId): Cart
+    {
+        /** @var Cart|null $candidate */
+        $candidate = Cart::query()->find($cartId);
+
+        $this->assertCartCanCheckout($candidate, $tenant, $userId);
+
+        $candidatePurchaseId = $candidate->current_purchase_id;
+        $currentPurchase = $candidatePurchaseId === null
+            ? null
+            : Purchase::query()->lockForUpdate()->find($candidatePurchaseId);
+
+        /** @var Cart|null $cart */
+        $cart = Cart::query()->lockForUpdate()->find($cartId);
+
+        $this->assertCartCanCheckout($cart, $tenant, $userId);
+
+        if ($cart->current_purchase_id !== $candidatePurchaseId) {
+            if ($cart->current_purchase_id !== null) {
+                throw ValidationException::withMessages([
+                    'cart_id' => __('api.purchase.checkout_in_progress'),
+                ]);
+            }
+
+            $currentPurchase = null;
+        }
+
+        if ($currentPurchase?->status === Purchase::STATUS_PAID) {
+            throw ValidationException::withMessages([
+                'cart_id' => __('api.purchase.checkout_in_progress'),
+            ]);
+        }
+
+        if ($currentPurchase !== null && in_array($currentPurchase->status, [
+            Purchase::STATUS_CREATED,
+            Purchase::STATUS_PENDING_PAYMENT,
+        ], true)) {
+            $this->reservations->returnToCart($currentPurchase, $cart);
+            $currentPurchase->update([
+                'status' => Purchase::STATUS_SUPERSEDED,
+            ]);
+        }
+
+        return $cart;
+    }
+
+    private function assertCartCanCheckout(?Cart $cart, Tenant $tenant, int $userId): void
+    {
+        if ($cart === null || $cart->tenant_codigo !== $tenant->codigo || $cart->user_id !== $userId) {
+            throw new NotFoundHttpException('Cart not found for tenant.');
+        }
+
+        if ($cart->status === Cart::STATUS_EXPIRED) {
+            throw new StockReservationExpiredException;
+        }
+
+        if ($cart->status !== Cart::STATUS_ACTIVE) {
+            throw ValidationException::withMessages([
+                'cart_id' => __('api.purchase.inactive_cart'),
+            ]);
+        }
+    }
+
+    /** @param Collection<int, CartItem> $cartItems */
+    private function verifyTenantItems(Tenant $tenant, Collection $cartItems): void
+    {
+        foreach ($cartItems as $item) {
+            if ($item->selectedItem() === null) {
+                throw ValidationException::withMessages([
+                    'cart_id' => __('api.purchase.catalog_item_missing'),
+                ]);
+            }
+
+            if ($item->catalogItem?->tenant_code !== $tenant->codigo) {
+                throw ValidationException::withMessages([
+                    'cart_id' => __('api.purchase.catalog_item_wrong_tenant'),
+                ]);
+            }
+        }
+    }
+
+    /** @param Collection<int, CartItem> $cartItems */
+    private function assertCartPurchaseLimits(
+        Tenant $tenant,
+        int $userId,
+        Collection $cartItems,
+        int $cartId,
+    ): void {
+        $quantities = $cartItems
+            ->groupBy('catalog_item_id')
+            ->map(fn (Collection $items): int => (int) $items->sum('cantidad'))
+            ->sortKeys();
+
+        $catalogItems = CatalogItem::query()
+            ->where('tenant_code', $tenant->codigo)
+            ->whereKey($quantities->keys())
+            ->orderBy('id')
+            ->lockForUpdate()
+            ->get()
+            ->keyBy('id');
+
+        foreach ($quantities as $catalogItemId => $quantity) {
+            /** @var CatalogItem $catalogItem */
+            $catalogItem = $catalogItems->get($catalogItemId);
+            $this->purchaseLimits->assertCanPurchase(
+                $catalogItem,
+                $userId,
+                $quantity,
+                excludedCartId: $cartId,
+                heldQuantity: $quantity,
+                field: 'cart_id',
+            );
+        }
+    }
+
+    /** @param array<string, mixed> $purchaseData */
+    private function createPurchase(
+        Tenant $tenant,
+        int $userId,
+        array $purchaseData,
+        float $total,
+        ?int $cartId,
+    ): Purchase {
+        return Purchase::query()->create([
+            ...$purchaseData,
+            'cart_id' => $cartId,
+            'tenant_codigo' => $tenant->codigo,
+            'user_id' => $userId,
+            'status' => Purchase::STATUS_CREATED,
+            'payment_method' => null,
+            'total' => $total,
+        ]);
+    }
+
+    private function checkoutExpiration(): Carbon
+    {
+        return now()->addMinutes(
+            max(1, (int) config('purchase.checkout_expiration_minutes', 30)),
+        );
+    }
+
+    /** @param Collection<int, CartItem> $cartItems */
+    private function loadCartItems(Collection $cartItems): void
+    {
+        $cartItems->load([
+            'catalogItem.inventory',
+            'catalogItem.attachments',
+            'variant.inventory',
+            'variant.attachments',
+            'variant.catalogItem',
+            'variant.definitions.itemAttribute.attribute',
+            'variant.eventDates',
+            'variant.eventDate',
+        ]);
+    }
+
+    private function loadPurchase(Purchase $purchase): Purchase
+    {
+        return $this->responses->load($purchase);
+    }
+}