feat(purchase): implement purchase limit enforcement and custom exception handling

app/Domains/Cart/Models/Cart.php

@@ -103,9 +103,14 @@ class Cart extends Model
             $cartQuantity = (int) $this->items()
                 ->where('catalog_item_id', $catalogItemId)
                 ->sum('cantidad');
-            $this->assertUserPurchaseLimit($selectedItem, $cartQuantity + $quantity);
             $inventoryService = app(CatalogInventoryService::class);
             $availableQuantity = $inventoryService->availableQuantity($selectedItem);
+            $this->assertUserPurchaseLimit(
+                $selectedItem,
+                $cartQuantity + $quantity,
+                heldQuantity: $cartQuantity,
+                maximumAddableCeiling: $availableQuantity,
+            );
 
             if ($availableQuantity !== null && $availableQuantity < $quantity) {
                 throw ValidationException::withMessages([
@@ -181,10 +186,13 @@ class Cart extends Model
                     ->where('catalog_item_id', $item->catalog_item_id)
                     ->whereKeyNot($item->getKey())
                     ->sum('cantidad');
+                $nextAvailableQuantity = $inventoryService->availableQuantity($nextSelection);
                 $this->assertUserPurchaseLimit(
                     $nextSelection,
                     $otherVariantsQuantity + $quantity,
                     $excludedPurchaseId,
+                    $otherVariantsQuantity + $item->cantidad,
+                    $nextAvailableQuantity,
                 );
 
                 app(StockReservationService::class)->release($item, $currentSelection, $item->cantidad);
@@ -222,6 +230,7 @@ class Cart extends Model
             }
 
             $delta = $quantity - $item->cantidad;
+            $availableQuantity = $inventoryService->availableQuantity($currentSelection);
 
             if ($delta > 0) {
                 $otherVariantsQuantity = (int) $this->items()
@@ -232,11 +241,11 @@ class Cart extends Model
                     $currentSelection,
                     $otherVariantsQuantity + $quantity,
                     $excludedPurchaseId,
+                    $otherVariantsQuantity + $item->cantidad,
+                    $availableQuantity,
                 );
             }
 
-            $availableQuantity = $inventoryService->availableQuantity($currentSelection);
-
             if ($delta > 0 && $availableQuantity !== null && $availableQuantity < $delta) {
                 $maxAvailable = $availableQuantity + $item->cantidad;
                 throw ValidationException::withMessages([
@@ -355,6 +364,8 @@ class Cart extends Model
         CatalogItem|Variant $selectedItem,
         int $cartQuantity,
         ?int $excludedPurchaseId = null,
+        int $heldQuantity = 0,
+        ?int $maximumAddableCeiling = null,
     ): void {
         if ($this->user_id === null) {
             return;
@@ -370,6 +381,8 @@ class Cart extends Model
             $cartQuantity,
             $excludedPurchaseId,
             $this->getKey(),
+            $heldQuantity,
+            $maximumAddableCeiling,
             field: 'cantidad',
         );
     }