LYNX-889: [AC-2.4.9] Merging guest and customer cart logic using Admin Configuration (#371)

* LYNX-899: [AC-2.4.9] Merge carts using configurations

* Performance failure fix

* PAT failure fix

* Review feedback fixed

* Review feedback fixed

* Review comments fixed

Author: cod40403

app/code/Magento/Checkout/Model/Config.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * Copyright 2025 Adobe
+ * All Rights Reserved.
+ */
+declare(strict_types=1);
+
+namespace Magento\Checkout\Model;
+
+use Magento\Framework\App\Config\ScopeConfigInterface;
+
+class Config
+{
+    public const CART_PREFERENCE_CUSTOMER = "customer";
+    public const CART_PREFERENCE_GUEST = "guest";
+    private const XML_PATH_CART_MERGE_PREFERENCE = 'checkout/cart/cart_merge_preference';
+
+    /**
+     * Config Constructor
+     *
+     * @param ScopeConfigInterface $scopeConfig
+     */
+    public function __construct(
+        private readonly ScopeConfigInterface $scopeConfig
+    ) {
+    }
+
+    /**
+     * Get Cart Merge Preference config to update cart quantities
+     *
+     * @return string
+     */
+    public function getCartMergePreference(): string
+    {
+        return $this->scopeConfig->getValue(self::XML_PATH_CART_MERGE_PREFERENCE);
+    }
+}

app/code/Magento/Checkout/Model/Config/Source/CartMergePreference.php

@@ -0,0 +1,27 @@
+<?php
+/**
+ * Copyright 2025 Adobe
+ * All Rights Reserved.
+ */
+declare(strict_types=1);
+
+namespace Magento\Checkout\Model\Config\Source;
+
+use Magento\Framework\Data\OptionSourceInterface;
+
+class CartMergePreference implements OptionSourceInterface
+{
+    /**
+     * Retrieve options for cart merge preference
+     *
+     * @return array[]
+     */
+    public function toOptionArray(): array
+    {
+        return [
+            ['value' => 'guest', 'label' => __('Guest Priority – Override with guest cart quantity')],
+            ['value' => 'customer', 'label' => __('Customer Priority – Override with customer cart quantity')],
+            ['value' => 'merge', 'label' => __('Merge Quantities – Merge quantities of customer and guest cart')]
+        ];
+    }
+}

app/code/Magento/Checkout/etc/adminhtml/system.xml

@@ -57,6 +57,11 @@
                     <label>Enable Clear Shopping Cart</label>
                     <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                 </field>
+                <field id="cart_merge_preference" translate="label" type="select" sortOrder="100" showInDefault="1" showInWebsite="0" showInStore="0">
+                    <label>Cart Merge Preference</label>
+                    <source_model>Magento\Checkout\Model\Config\Source\CartMergePreference</source_model>
+                    <comment>Select how cart item quantities should be merged</comment>
+                </field>
             </group>
             <group id="cart_link" translate="label" sortOrder="3" showInDefault="1" showInWebsite="1">
                 <label>My Cart Link</label>

app/code/Magento/Checkout/etc/config.xml

@@ -21,6 +21,7 @@
                 <number_items_to_display_pager>20</number_items_to_display_pager>
                 <crosssell_enabled>1</crosssell_enabled>
                 <enable_clear_shopping_cart>0</enable_clear_shopping_cart>
+                <cart_merge_preference>merge</cart_merge_preference>
             </cart>
             <cart_link>
                 <use_qty>1</use_qty>

app/code/Magento/QuoteGraphQl/Model/Cart/MergeCarts/CartQuantityValidator.php

@@ -1,46 +1,50 @@
 <?php
 /**
- * Copyright © Magento, Inc. All rights reserved.
- * See COPYING.txt for license details.
+ * Copyright 2025 Adobe
+ * All Rights Reserved.
  */
 declare(strict_types=1);
 
 namespace Magento\QuoteGraphQl\Model\Cart\MergeCarts;
 
-
 use Magento\CatalogInventory\Api\StockRegistryInterface;
 use Magento\Framework\Exception\CouldNotSaveException;
 use Magento\Framework\Exception\NoSuchEntityException;
 use Magento\Quote\Api\CartItemRepositoryInterface;
 use Magento\Quote\Api\Data\CartInterface;
 use Magento\Quote\Api\Data\CartItemInterface;
+use Magento\Quote\Model\Quote\Item;
+use Magento\Checkout\Model\Config;
+use Psr\Log\LoggerInterface;
+use Magento\Catalog\Api\Data\ProductInterface;
 
 class CartQuantityValidator implements CartQuantityValidatorInterface
 {
     /**
-     * @var CartItemRepositoryInterface
-     */
-    private $cartItemRepository;
-
-    /**
-     * @var StockRegistryInterface
+     * Array to hold cumulative quantities for each SKU
+     *
+     * @var array
      */
-    private $stockRegistry;
+    private array $cumulativeQty = [];
 
     /**
+     * CartQuantityValidator Constructor
+     *
      * @param CartItemRepositoryInterface $cartItemRepository
      * @param StockRegistryInterface $stockRegistry
+     * @param Config $config
+     * @param LoggerInterface $logger
      */
     public function __construct(
-        CartItemRepositoryInterface $cartItemRepository,
-        StockRegistryInterface $stockRegistry
+        private readonly CartItemRepositoryInterface $cartItemRepository,
+        private readonly StockRegistryInterface $stockRegistry,
+        private readonly Config $config,
+        private readonly LoggerInterface $logger
     ) {
-        $this->cartItemRepository = $cartItemRepository;
-        $this->stockRegistry = $stockRegistry;
     }
 
     /**
-     * Validate combined cart quantities to make sure they are within available stock
+     * Validate combined cart quantities to ensure they are within available stock
      *
      * @param CartInterface $customerCart
      * @param CartInterface $guestCart
@@ -49,28 +53,157 @@ public function __construct(
     public function validateFinalCartQuantities(CartInterface $customerCart, CartInterface $guestCart): bool
     {
         $modified = false;
-        /** @var CartItemInterface $guestCartItem */
-        foreach ($guestCart->getAllVisibleItems() as $guestCartItem) {
-            foreach ($customerCart->getAllItems() as $customerCartItem) {
-                if ($customerCartItem->compare($guestCartItem)) {
-                    $product = $customerCartItem->getProduct();
-                    $stockCurrentQty = $this->stockRegistry->getStockStatus(
-                        $product->getId(),
-                        $product->getStore()->getWebsiteId()
-                    )->getQty();
-                    if ($stockCurrentQty < $guestCartItem->getQty() + $customerCartItem->getQty()) {
-                        try {
-                            $this->cartItemRepository->deleteById($guestCart->getId(), $guestCartItem->getItemId());
-                            $modified = true;
-                        } catch (NoSuchEntityException $e) {
-                            continue;
-                        } catch (CouldNotSaveException $e) {
-                            continue;
-                        }
-                    }
+        $this->cumulativeQty = [];
+
+        foreach ($guestCart->getAllVisibleItems() as $guestItem) {
+            foreach ($customerCart->getAllItems() as $customerItem) {
+                if (!$customerItem->compare($guestItem)) {
+                    continue;
+                }
+
+                $mergePreference = $this->config->getCartMergePreference();
+
+                if ($mergePreference === Config::CART_PREFERENCE_CUSTOMER) {
+                    $this->safeDeleteCartItem((int)$guestCart->getId(), (int)$guestItem->getItemId());
+                    $modified = true;
+                    break;
+                }
+
+                $product = $customerItem->getProduct();
+                $sku = $product->getSku();
+                $websiteId = (int) $product->getStore()->getWebsiteId();
+
+                $isQtyValid = $customerItem->getChildren()
+                    ? $this->validateCompositeProductQty($guestItem, $customerItem)
+                    : $this->validateProductQty(
+                        $product,
+                        $sku,
+                        $guestItem->getQty(),
+                        $customerItem->getQty(),
+                        $websiteId
+                    );
+
+                if ($mergePreference === Config::CART_PREFERENCE_GUEST) {
+                    $this->safeDeleteCartItem((int)$customerCart->getId(), (int)$customerItem->getItemId());
+                    $modified = true;
+                }
+
+                if (!$isQtyValid) {
+                    $this->safeDeleteCartItem((int)$guestCart->getId(), (int)$guestItem->getItemId());
+                    $modified = true;
                 }
+
+                break;
             }
         }
+
+        $this->cumulativeQty = [];
+
         return $modified;
     }
+
+    /**
+     * Validate product quantity against available stock
+     *
+     * @param ProductInterface $product
+     * @param string $sku
+     * @param float $guestItemQty
+     * @param float $customerItemQty
+     * @param int $websiteId
+     * @return bool
+     */
+    private function validateProductQty(
+        ProductInterface $product,
+        string $sku,
+        float $guestItemQty,
+        float $customerItemQty,
+        int $websiteId
+    ): bool {
+        $salableQty = $this->stockRegistry->getStockStatus($product->getId(), $websiteId)->getQty();
+
+        $this->cumulativeQty[$sku] ??= 0;
+        $this->cumulativeQty[$sku] += $this->getCurrentCartItemQty($guestItemQty, $customerItemQty);
+
+        return $salableQty >= $this->cumulativeQty[$sku];
+    }
+
+    /**
+     * Validate composite product quantities against available stock
+     *
+     * @param Item $guestItem
+     * @param Item $customerItem
+     * @return bool
+     */
+    private function validateCompositeProductQty(Item $guestItem, Item $customerItem): bool
+    {
+        $guestChildren = $guestItem->getChildren();
+        $customerChildren = $customerItem->getChildren();
+
+        foreach ($customerChildren as $customerChild) {
+            $sku = $customerChild->getProduct()->getSku();
+            $guestChild = $this->retrieveChildItem($guestChildren, $sku);
+
+            $guestQty = $guestChild ? $guestItem->getQty() * $guestChild->getQty() : 0;
+            $customerQty = $customerItem->getQty() * $customerChild->getQty();
+
+            $product = $customerChild->getProduct();
+            $websiteId = (int) $product->getStore()->getWebsiteId();
+
+            if (!$this->validateProductQty($product, $sku, $guestQty, $customerQty, $websiteId)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Find a child item by SKU in the list of children
+     *
+     * @param CartItemInterface[] $children
+     * @param string $sku
+     * @return CartItemInterface|null
+     */
+    private function retrieveChildItem(array $children, string $sku): ?CartItemInterface
+    {
+        foreach ($children as $child) {
+            if ($child->getProduct()->getSku() === $sku) {
+                return $child;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Get the current cart item quantity based on the merge preference
+     *
+     * @param float $guestCartItemQty
+     * @param float $customerCartItemQty
+     * @return float
+     */
+    private function getCurrentCartItemQty(float $guestCartItemQty, float $customerCartItemQty): float
+    {
+        return match ($this->config->getCartMergePreference()) {
+            Config::CART_PREFERENCE_CUSTOMER => $customerCartItemQty,
+            Config::CART_PREFERENCE_GUEST => $guestCartItemQty,
+            default => $guestCartItemQty + $customerCartItemQty
+        };
+    }
+
+    /**
+     * Safely delete a cart item by ID, logging any exceptions
+     *
+     * @param int $cartId
+     * @param int $itemId
+     * @return void
+     */
+    private function safeDeleteCartItem(int $cartId, int $itemId): void
+    {
+        try {
+            $this->cartItemRepository->deleteById($cartId, $itemId);
+        } catch (NoSuchEntityException | CouldNotSaveException $e) {
+            $this->logger->error($e->getMessage());
+        }
+    }
 }

app/code/Magento/QuoteGraphQl/Model/Resolver/MergeCarts.php

@@ -24,11 +24,6 @@
 
 class MergeCarts implements ResolverInterface
 {
-    /**
-     * @var array
-     */
-    private array $fields;
-
     /**
      * MergeCarts Constructor
      *
@@ -45,9 +40,8 @@ public function __construct(
         private readonly CustomerCartResolver $customerCartResolver,
         private readonly QuoteIdToMaskedQuoteIdInterface $quoteIdToMaskedQuoteId,
         private readonly CartQuantityValidatorInterface $cartQuantityValidator,
-        array $fields
+        private readonly array $fields
     ) {
-        $this->fields = $fields;
     }
 
     /**
@@ -96,9 +90,10 @@ public function resolve(
         $customerCart = $this->getCartForUser->execute($customerMaskedCartId, $currentUserId, $storeId);
         $guestCart = $this->getCartForUser->execute($guestMaskedCartId, null, $storeId);
 
-        // Validate cart quantities before merging
+        // Validate cart quantities before merging and reload cart before cart merge
         if ($this->cartQuantityValidator->validateFinalCartQuantities($customerCart, $guestCart)) {
             $guestCart = $this->getCartForUser->execute($guestMaskedCartId, null, $storeId);
+            $customerCart = $this->getCartForUser->execute($customerMaskedCartId, $currentUserId, $storeId);
         }
 
         // Merge carts and save

app/code/Magento/QuoteGraphQl/etc/graphql/di.xml

@@ -73,6 +73,7 @@
                 <item name="grouped_product_image" xsi:type="string">checkout/cart/grouped_product_image</item>
                 <item name="configurable_product_image" xsi:type="string">checkout/cart/configurable_product_image</item>
                 <item name="is_checkout_agreements_enabled" xsi:type="string">checkout/options/enable_agreements</item>
+                <item name="cart_merge_preference" xsi:type="string">checkout/cart/cart_merge_preference</item>
             </argument>
         </arguments>
     </type>

app/code/Magento/QuoteGraphQl/etc/schema.graphqls

@@ -523,6 +523,7 @@ type StoreConfig {
     grouped_product_image: ProductImageThumbnail! @doc(description: "checkout/cart/grouped_product_image: which image to use for grouped products.") @resolver(class: "Magento\\QuoteGraphQl\\Model\\Resolver\\StoreConfig")
     configurable_product_image: ProductImageThumbnail! @doc(description: "checkout/cart/configurable_product_image: which image to use for configurable products.") @resolver(class: "Magento\\QuoteGraphQl\\Model\\Resolver\\StoreConfig")
     is_checkout_agreements_enabled: Boolean! @doc(description: "Configuration data from checkout/options/enable_agreements")
+    cart_merge_preference: String! @doc(description: "Configuration data from checkout/cart/cart_merge_preference")
 }
 
 enum ProductImageThumbnail {