Aktualizace nákupního košíku

Tento dokument popisuje postup aktualizace a modifikace obsahu nákupního košíku.

Aktualizace košíku se vždy provádí metodou ShoppingCartService#updateCart.

Tato operace je rozčleněna do tří částí: beforeCartUpdateInterceptor, cartUpdate a afterCartUpdateInterceptor. Všechny tyto části se však vykonávají v rámci jedné transakce.

CartUpdateZkopírovat odkaz na sekci

Každá aktualizace košíku (dále jen cartUpdate) implementuje rozhraní com.fg.cps.eshop.cart.service.update.CartUpdate. CartUpdate nese parametry aktualizace, např. "přidání produktu" nese identifikaci produktu, který se má přidat do košíku a také požadované množství.

Každá implementace CartUpdate pak musí být zaregistrována do com.fg.cps.eshop.order.OrderFeature:

1final OrderFeature orderFeature = getFeature(OrderFeature.class);2if (orderFeature.isFeatureEnabled() && getFeature(RestApiFeature.class).isFeatureEnabled()) {3    orderFeature.addCartUpdate(ActivateMarketingCampaignUpdate.class);4}

Důvodem je nutná inicializace serializace a deserializace cartUpdate pro RestApi.

CartUpdateAffectingPricesZkopírovat odkaz na sekci

V případě, že cartUpdate implementuje CartUpdateAffectingPrices, znamená to, že cartUpdate má vliv na celkovou cenu objednávku a je nutné např. přepočítat cenové politiky. Typickým příkladem je přidání produktu do košíku nebo uplatnění slevového poukazu. Příkladem aktualizace, která nemá vliv na cenu může být např. změna fakturační adresy nebo přidání poznámky k objednávce.

CartUpdaterZkopírovat odkaz na sekci

Každý cartUpdate musí mít odpovídající implementaci CartUpdater, který zajistí zpracování aktualizace. CartUpdater je nutné zaregistrovat do aplikačního (spring) kontextu EdeeShop modulu.

V případě jednoduchých updatů (např. změna nevyžaduje žádnou servisní třídu) může cartUpdate implementovat CartUpdateWithExecute. Pro takový cartUpdate již nemusí existovat CartUpdater.

CartUpdateInterceptorZkopírovat odkaz na sekci

Před každým cartUpdate je možné registrovat BeforeCartUpdateInterceptor. Tyto interceptory jsou vhodné například pro validaci dat v cartUpdate.

Po vykonání cartUpdate je možné přidat AfterCartUpdateInterceptor. Tyto interceptory jsou vhodné například k ověření dat v košíku, přepočtu cen a slev nebo k automatickým úpravám dat v košíku.

Ochrana proti zbytečnému založení košíkuZkopírovat odkaz na sekci

CartContext#getOrCreateShoppingCart košík založí, pokud ještě neexistuje. Interceptor, který se zajímá o obsah košíku, se proto musí nejdřív zeptat, jestli košík vůbec existuje — jinak už jen tím, že se na něj podívá, vytvoří prázdný košík (a s ním i řádky v DB) pro každého návštěvníka, přes kterého takový cartUpdate proteče:

1@Override2public void intercept(@NonNull CartContext cartContext, @NonNull CartUpdateContext cartUpdateContext,3                      @NonNull CartUpdate cartUpdate) throws CartUpdateException {4    if (!cartContext.isShoppingCartExists()) {5        return;6    }7    // ... práce s košíkem8}

isShoppingCartExists() košík nezakládá — jen se ho pokusí načíst (getShoppingCartIfExists). Guard platí stejně pro AfterCartUpdateInterceptor a pro filtry doprav/plateb; příkladem jsou SelectedShippingActuator, SelectedPaymentActuator nebo VoucherCodeCartValidator. Výjimkou jsou interceptory, které košík zakládat mají (typicky reakce na přidání položky).

Zpracování chybyZkopírovat odkaz na sekci

V případě, že cartUpdate nebo některý interceptor selže, musí být vyvolána chyba. Pokud se jedná o uživatelskou chybu, např.: uživatel zadal neplatná data pro daný okamžik nebo na ně nemá práva, měla by být vyvolána lokalizovaná CartUpdateException, která se zpropaguje přímo uživateli. Pokud však nastala při zpracování neočekávaná interní chyba, lze použít klasické výjimky např.: IllegalArgumentException. Celá aktualizace (tj. beforeCartUpdateInterceptor, cartUpdate, afterCartUpdateInterceptor) se vykonává v jedné transakci, tudíž pokud něco selže, provede se rollback celé aktualizace. V případě, že rollback celé aktualizace není žádoucí, je možné vyvolat výjimku CartUpdateNoRollbackException, která rollback transakce neprovede.

Zápis do dat košíkuZkopírovat odkaz na sekci

Data košíku jsou reprezentována CartData (a jeho rozšířením). Pro zápis existuje CartDataWriter. Toto rozhraní je "skryté", protože nechceme umožnit měnit košík jinak než přes ShoppingCartService#updateCart. V rámci cartUpdate a cartUpdateInterceptor je však možné CartData přetypovat na CartDataWriter a tak do něj zapisovat.

Zápis přes CartDataWriter mimo ShoppingCartService#updateCart může způsobit nekonzistentní stav košíku.

Tento "writer" mechanismus platí i pro vnořená data košíku, tedy položky, dopravy, platby, politiky a adresy. Např. pro CartItem existuje CartItemWriter.

Poznámka: K vytváření těchto vnořených dat, je nutné používat odpovídající metody na CartContext (více viz popis nákupního košíku).

BeforeCartUpdateEvent a AfterCartUpdateEventZkopírovat odkaz na sekci

Před a po aktualizaci košíku se vypalují BeforeCartUpdateEvent a AfterCartUpdateEvent.

Vytvoření vlastní aktualizace košíkuZkopírovat odkaz na sekci

Pro vytvoření nové aktualizace košíku je potřeba:

1. Vytvořit novou implementaci com.fg.cps.eshop.cart.service.update.CartUpdate (dále cartUpdate).
2. Implementovat com.fg.cps.eshop.cart.service.CartUpdater (neplatí pokud cartUpdate implementuje CartUpdateWithExecute).

Zprávy aktualizace košíkuZkopírovat odkaz na sekci

Během aktualizace košíku se mohou vyskytnout různé situace, o kterých je potřeba informovat zákazníka. Rejstřík všech možných zpráv se nachází zde.

Další možnosti přizpůsobeníZkopírovat odkaz na sekci

CartContextPriceListResolverZkopírovat odkaz na sekci

Pomocí implementace CartContextPriceListResolver je možné ovlivnit ceníky, které se použijí při výpočtech v košíku. Pokud není toto rozhraní implementováno, tak se použije výchozí seznam ceníků získaný pomocí PriceResolver#getPriceListCodesForCurrentUser(Catalog).

Systémové implementace aktualizace košíkuZkopírovat odkaz na sekci

V této sekci budou popsané již existující systémové implementace aktualizace košíku a jejich JSON payload.

AddItemByIdToCartZkopírovat odkaz na sekci

Tato aktualizace slouží k přidání položky do košíku pomocí id produktu. Nepovinné parametry:

• adjustment
• source
• sourceId Payload:

1{2	"type": "AddItemByIdToCart",3	"productId": 123,4	"quantity": 1,5    "adjustment": "xxx", 6    "source": "source",7    "sourceId": 123 8}

AddItemByCodeToCartZkopírovat odkaz na sekci

Tato aktualizace slouží k přidání položky do košíku pomocí kódu produktu. Nepovinné parametry:

• adjustment
• source
• sourceId Payload:

1{2	"type": "AddItemByCodeToCart",3	"productCode": "kolecko-cerne",4	"quantity": 1,5    "adjustment": "xxx", 6    "source": "source",7    "sourceId": 123 8}

AddItemsByCodeToCartZkopírovat odkaz na sekci

Tato aktualizace slouží k přidání více položek do košíku Nepovinné parametry:

• adjustment
• source
• sourceId Payload:

1{2	"type": "AddItemsByCodeToCart",3	"items": [4		{5			"productCode": "kolecko-cerna",6			"quantity": 1			7		},8		{9				"productCode": "kolecko-cerna",10				"quantity": 111		}12	],13      "source": "source",14      "sourceId": 12315}

AddItemsByIdToCartZkopírovat odkaz na sekci

Tato aktualizace slouží k přidání více položek do košíku Nepovinné parametry:

• adjustment
• source
• sourceId Payload:

1{2	"type": "AddItemsByIdToCart",3	"items": [4		{5			"productId": 123,6			"quantity": 1			7		},8		{9				"productCode": 321,10				"quantity": 111		}12	],13      "source": "source",14      "sourceId": 12315}

SetItemQuantityZkopírovat odkaz na sekci

Nastaví počet kusů existující položky v košíku.

Payload:

1{2	"type": "SetItemQuantity",3	"itemId": 377957122051,4	"quantity": 105}

SetItemsQuantityZkopírovat odkaz na sekci

Nastaví počet kusů existujících položek v košíku.

Payload:

1{2	"type": "SetItemsQuantity",3	"items": [4		{5			"itemId": 377957122051,6			"quantity": 107		}8	]9}

RemoveCartItemZkopírovat odkaz na sekci

Smazání položek z košíku, dle itemId položky.

Payload:

1{2  "type": "RemoveCartItem",3  "itemIds": [4    3779571220505  ]6}

ContactInformationUpdateZkopírovat odkaz na sekci

Aktualizace kontaktních informací košíku.

Payload:

1{2	"type": "ContactInformationUpdate",3	"customerEmail": "vomacka@fg.cz",4	"customerPhone": "+420777888999",5	"billingAddress": {6		"fullName": "Pepa vomacka",7		"street": "Vomackova",8		"city": "Hradec kralove",9		"postCode": "50003",10		"countryCode": "CZ",11		"companyName": "FG",12		"regNumber": "",13		"taxRegNumber": "",14		"idUserAddress": 12315	},16	"deliveryAddress": {17		"fullName": "",18		"street": "",19		"city": "",20		"postCode": "",21		"countryCode": "",22		"phone": "",23		"companyName": "",24		"idUserAddress": 32125	},26	"differentDeliveryAddress": 1,27	"customerType": 0,28	"note": "Tohle je ta nejlepsi objednavka."29
30}

InitDefaultShippingUpdateZkopírovat odkaz na sekci

Akce nastaví původní hodnotu pro dopravu. Payload:

1{2	"type": "InitDefaultShippingUpdate"3}

SetShippingByCodeUpdateZkopírovat odkaz na sekci

Akce nastaví dopravu dle kódu dopravy. Payload:

1{2	"type": "SetShippingByCodeUpdate",3	"shippingCode" : "osobni-odber"4}

SetShippingByIdUpdateZkopírovat odkaz na sekci

Akce nastaví dopravu dle id dopravy. Payload:

1{2	"type": "SetShippingByIdUpdate",3	"shippingId" : 1234}

SetPickupPointByCodeUpdateZkopírovat odkaz na sekci

Nastaví místo osobního odběru, dle kódu odběrového místa.

Payload:

1{2	"type": "SetPickupPointByCodeUpdate",3	"pickupPointCode": "xxx"4}

SetPickupPointByIdUpdateZkopírovat odkaz na sekci

Nastaví místo osobního odběru, dle id odběrového místa.

Payload:

1{2	"type": "SetPickupPointByIdUpdate",3	"pickupPointId": xxx4}

InitDefaultPaymentUpdateZkopírovat odkaz na sekci

Nastaví výchozí typ platby pro košík zákazníka

Payload:

1{2	"type": "InitDefaultPaymentUpdate"3}

SetPaymentByCodeUpdateZkopírovat odkaz na sekci

Nastaví platbu dle kódu pro košík zákazníka. Payload:

1{2	"type": "SetPaymentByCodeUpdate",3	"paymentCode" : "hotove"4}

SetPaymentByIdUpdateZkopírovat odkaz na sekci

Nastaví platbu dle id pro košík zákazníka. Payload:

1{2	"type": "SetPaymentByCodeUpdate",3	"paymentId" : 1234}

ConfirmOrderZkopírovat odkaz na sekci

Transformace (Potvrzení) aktuálního košíku do objednávky

Payload:

1{2	"type": "ConfirmOrder"3}

RefreshCartZkopírovat odkaz na sekci

Aktualizace košíku.

Payload:

1{2	"type": "RefreshCart"3}

ShoppingCartPageConfirmZkopírovat odkaz na sekci

Payload:

1{2	"type": "ShoppingCartPageConfirm"3}

VoucherUseUpdateZkopírovat odkaz na sekci

Přiřazení voucheru k aktuálnímu košíku.

Payload:

1{2	"type": "VoucherUseUpdate",3	"voucherCode": "xxx"4}

VoucherCancelUpdateZkopírovat odkaz na sekci

Smazání voucheru z aktuálního košíku. Payload:

1{2  "type": "VoucherCancelUpdate",3  "voucherCode": "xxx"4}

CreditUpdateZkopírovat odkaz na sekci

Slouží k nastavení použití kreditů v košíku.

Payload:

1{2	"type": "CreditUpdate",3	"useCredit": true4}

SelectBundleBonusZkopírovat odkaz na sekci

Vybere bonusový produkt v košíku.

Payload:

1{2	"type": "SelectBundleBonus",3	"bundleId": 1,4	"bonusProductId": 1,5	"requiredCartItemId": 1,6	"index": 1,7	"selected": true8}

BundleBonusChangeQuantityZkopírovat odkaz na sekci

Změní počet kusů bonusového produktu

Payload:

1{2	"type": "BundleBonusChangeQuantity",3	"bundleId": 1,4	"bonusProductId": 1,5	"requiredCartItemId": 1,6	"index": 1,7	"quantity": "1"8}

SelectBonusVariantZkopírovat odkaz na sekci

Vybere variantu bonusového produktu.

Payload:

1{2  "type": "SelectBonusVariant",3  "bundleId": 1,4  "bonusProductId": 1,5  "requiredCartItemId": 1,6  "index": 1,7  "selectedVariantCode": "tadada"8}

SelectNoBonusZkopírovat odkaz na sekci

Zruší vybraný bonusový produkt.

Payload:

1{2	"type": "SelectNoBonus",3	"bundleId": 1,4	"requiredCartItemId": 15}

ZboziGdprOptionUpdateZkopírovat odkaz na sekci

Potvrzení GDPR v rámci košíku.

Payload:

1{2	"type": "ZboziGdprOptionUpdate",3	"zboziGdprOption" : 14}

HeurekaOverenoOptionUpdateZkopírovat odkaz na sekci

Potvrzení heureky v rámci košíku.

Payload:

1{2	"type": "HeurekaOverenoOptionUpdate",3	"heurekaOverenoOption" : 14}