Betalingsconcepttest splitsen: beslissingen over architectuur en ontwerp

Op deze pagina wordt uitgelegd wat de architecturale keuzes zijn achter het concept van het proefdrukken van gesplitste betalingen. Lees het alvorens u de bouwstijlherinneringen in deze reeks gebruikt, zodat begrijpt u hoe elke component gestructureerd is, en hoe te om de patronen in uw eigen project aan te passen.

Het kernbeginsel

Het bewijs van concept gaat niet over de meest elegante uitvoering van gesplitste betalingen. Het is over het tonen van hoe te beginnen de logica van Commerce aan App Builder te bewegen zonder een big-bang herschrijft.

De regel die overal wordt toegepast is:

als iets synchroon in de het verzoekcyclus van Commerce moet lopen, of Commerce-interne APIs moet aanhalen die geen schoon extern oppervlak hebben, blijft het in PHP. Al het andere beweegt zich aan App Builder.

Wat leeft er in Commerce (PHP) en waarom?

​1. Winkelcredit-toepassing: PlaceOrderPlugin

Winkelcreditering wordt op de winkelwagentje toegepast met Magento\CustomerBalance\Api\BalanceManagementInterface::apply() . Deze methode werkt slechts aan een actieve kar. Het winkelwagentje wordt inactief op het moment dat de bestelling wordt geplaatst. App Builder ontvangt de I/O gebeurtenis nadat de orde wordt geplaatst, zodat is het toepassen van opslagkrediet van App Builder niet mogelijk.

de les: om het even wat die wortelstaat moet veranderen alvorens de plaatsing van de orde in Commerce moet lopen. Er is geen oplossing.

​2. Synchrone drempelwaarbescherming: CheckoutPlugin

De controle van de orderdrempel van $100 moet de klant bij de betalingsstap blokkeren, voordat deze Place Order selecteert. De reactie moet synchroon zijn in de Commerce-aanvraagcyclus. App Builder is gebeurtenisgestuurd en asynchroon, zodat het op dat moment geen directe fout kan retourneren.

App Builder bevestigt ook de drempel (als controle), maar de klantenervaring hangt van de controle af die van Commerce eerst loopt.

​3. Aangepaste REST-eindpunten: webapi.xml en SplitPaymentManagement

De volgende eindpunten moeten:

/V1/split-payment/orders/:id/cash-received en /V1/split-payment/orders/:id/cash-decline

Er is geen schone openbare REST-laag voor dat gedrag, zodat Commerce de eindpunten beschikbaar maakt. App Builder noemt ze.

​4. Hoeveelheden splitsen op aanhalingsteken en volgorde: waarnemers en plug-ins

Commerce heeft de gesplitste hoeveelheden (split_store_credit_amount, split_cash_amount, split_cash_status ) op de volgorde nodig, zowel voor de REST-reacties die App Builder leest als voor de Admin -ordeweergave. De bedragen zijn gekoppeld met extensiekenmerken en worden van het aanhalingsteken naar de volgorde gekopieerd in een waarnemer op sales_model_service_quote_submit_before .

Wat leeft er in App Builder en waarom?

​1. Bezig met verwerken van volgorde die aan gebeurtenissen is gekoppeld: payment-orchestrator

Nadat sales_order_place_before is geactiveerd, ontvangt App Builder de gebeurtenis. Het bevestigt de drempel (als controle) opnieuw, registreert a contant geld in afwachting van commentaar op de orde, en werkt ordestatus bij. Voor geen van deze dingen is nieuwe PHP nodig, alleen REST terug naar Commerce.

​2. Acceptatie van geld: payment-accept

Wanneer een ERP (of een operator op het dashboard) bevestigt dat er geld is ontvangen, roept payment-accept POST /V1/split-payment/orders/:id/cash-received aan. Factuur, verzending en orderstatus worden in Commerce afgehandeld. App Builder is de trigger.

​3. Verlaging van geld: payment-decline

payment-decline roept POST /V1/split-payment/orders/:id/cash-decline aan en Commerce annuleert de volgorde. Hetzelfde patroon als acceptatie van contant geld.

​4. Operator-dashboard: demo-dashboard

Een op zichzelf staand HTML-dashboard dat wordt aangeboden via een App Builder-webactie. Het haalt bestellingen op die wachten op geld van Commerce REST en biedt Accept / Decline -acties die de bovenstaande App Builder-acties aanroepen. Commerce Admin is niet vereist.

De drempel: tweemaal toegepast

Customer at checkout
        |
        v
[Commerce: CheckoutPlugin]     <- Synchronous, blocks immediately, user sees error
        |
        |  (if somehow bypassed: direct API call, and so on)
        v
[Order placed] -> I/O Event -> [App Builder: payment-orchestrator]
                                        |
                                        v
                              [evaluateThreshold()]  <- Async audit, records failure comment

Commerce bezit de gebruiker-onder ogen ziet wacht; App Builder bezit de post-plaatsingscontrole. Dat is opzettelijk.

Het winkelkrediet: waarom het in PHP blijft

What you might think would work (it does not):
  Order placed -> I/O Event -> App Builder -> PUT /V1/carts/:id/store-credit
  (Fails: cart is inactive after place order)

What actually works:
  AroundPlaceOrder plugin
  -> BalanceManagementInterface::apply($cartId, $amount)  <- cart is still active
  -> place order
  -> order placed
  -> I/O event: App Builder (store credit is already applied)

Dit wordt door het store-credit.js -bestand in het Organizer-document gedocumenteerd. Het is een non-op stub met commentaren die verklaren waarom het niet wordt gebruikt.

Extensiekenmerken: de lijm

Gesplitste hoeveelheden worden door het systeem verplaatst bij extensiekenmerken:

Checkout JavaScript (Knockout)
    |  POST /V1/split-payment/set
    v
SplitPaymentSession (PHP session)
    |  AroundPlaceOrder reads the session
    v
CartInterface extension attributes
    |  `sales_model_service_quote_submit_before` observer
    v
OrderInterface extension attributes -> `sales_order` flat columns
    |  I/O event payload includes these fields
    v
App Builder `payment-orchestrator` reads the split amounts

Gegevensmodel

sales_ordervlakke kolommen die deze module toevoegt

de attributen van de Uitbreiding (op CartInterface, OrderInterface, en OrderPaymentInterface)

I/O-velden voor gebeurtenislading

observer.sales_order_place_before is geconfigureerd in io_events.xml om het volgende op te nemen in de gebeurtenis:

entity_id, quote_id, increment_id, subtotal,
split_store_credit_amount, split_cash_amount, split_cash_status

App Builder gebruikt entity_id als de bestellings-id en split_store_credit_amount en split_cash_amount voor drempelvalidatie.

De vijf randgevallen waarop het conceptbewijs betrekking heeft

1. CapCustomerBalanceCollectPlugin

De native Customer balance totale collector van Commerce kan te veel worden toegepast (het volledige beschikbare saldo wordt weergegeven, niet het door de sessie gedeclareerde gesplitste bedrag). Met deze insteekmodule wordt de hoeveelheid afgekapt die overeenkomt met de waarde die in de sessie is gedeclareerd.

2. FixSplitPaymentGrandTotalPlugin

Nadat de opslagcreditering is toegepast, kan het aanhalingsteken Grand Total naar het bedrag in contanten worden verlaagd. De controle JavaScript moet het ordertotaal voor gespleten bevestiging vóór berekenen die veranderen. De insteekmodule wordt uitgevoerd na de totalen die zijn verzameld en corrigeert de weergave, terwijl de JavaScript grand_total niet alleen vertrouwt en de waarde reconstrueert op basis van subtotaal-segmenten.

3. FixInvoiceCustomerBalanceAfterTotalsPlugin

Wanneer factuurtotalen worden herberekend, kan winkelkrediet tweemaal worden toegepast. Deze plug-in corrigeert customer_balance_amount op facturen.

4. SplitPaymentZeroTotalPlugin

Nadat het winkelkrediet is toegepast, kan het winkelwagentje Grand Total $0 zijn (volledige creditorder van de winkel). Met de controle Zero subtotal checkout van Commerce kunt u in dat geval de COD blokkeren. Met deze insteekmodule is CZV mogelijk wanneer het bedrag aan sessies groter is dan 0.

​5. Offerteherinnering voor BalanceManagementInterface::apply()

apply() controleert de hoeveelheid ten opzichte van de huidige Grand Total . Als het totaal al het geldgedeelte is, kan apply() mislukken of vastzetten. PlaceOrderPlugin schorst tijdelijk de correctie voor het totaal-generaal terwijl de balans wordt toegepast, met behulp van een sessiemarkering (beginBalanceApply / endBalanceApply).

Gerelateerde gesplitste betalingen POC-middelen