Delad betalnings-POC: Commerce module AI prompt

Använd den här sidan om du vill kopiera den fullständiga uppmaningen som genererar den Client_SplitPayment-processmodulen: REST, sessionshantering, Checkout och Admin visning för det delade betalningsbeviset för konceptet. Operatörens arbetsflöde behålls i App Builder.

Hur du använder den här uppmaningen

Kopiera allt från PROMPT START till End of prompt till Cursor (med Claude) eller direkt till Claude. Kör det från Commerce-projektets rot eller från en katalog där AI kan skapa filer.

Anpassa innan du kör

Uppmaningen

UPPMANA START

Du genererar en komplett, produktionsklar Adobe Commerce 2.4.5±modul för en delad betalningsfunktion. Modulen är det tunna PHP-adaptern som visar rätt REST-yta och bifogar rätt data i rätt ögonblick i Commerce livscykel. Alla operatorers arbetsflödeslogik finns i Adobe App Builder (inte i denna modul).

Modulidentitet:

Generera alla filer i filstrukturen nedan. Utelämna inte någon fil. Använd declare(strict_types=1) i alla PHP-filer.

Filstruktur att generera

app/code/Client/SplitPayment/
├── registration.php
├── composer.json
├── Api/
│   ├── Data/SplitPaymentInterface.php
│   └── SplitPaymentManagementInterface.php
├── Block/
│   └── Order/SplitPaymentInfo.php
├── Controller/
│   └── Checkout/StoreCreditBalance.php
├── etc/
│   ├── acl.xml
│   ├── config.xml
│   ├── db_schema.xml
│   ├── db_schema_whitelist.json
│   ├── di.xml
│   ├── events.xml
│   ├── extension_attributes.xml
│   ├── io_events.xml
│   ├── module.xml
│   ├── webapi.xml
│   └── frontend/
│       └── routes.xml
├── Model/
│   ├── SplitPaymentData.php
│   ├── SplitPaymentManagement.php
│   ├── Service/
│   │   └── SplitInvoiceService.php
│   └── Session/
│       └── SplitPaymentSession.php
├── Observer/
│   ├── AutoInvoiceStoreCreditOnOrderPlace.php
│   └── CopySplitPaymentToOrder.php
├── Plugin/
│   ├── CheckoutPlugin.php
│   ├── OrderRepositoryPlugin.php
│   ├── PlaceOrderPlugin.php
│   ├── Adminhtml/
│   │   └── OrderPaymentPlugin.php
│   ├── Checkout/
│   │   └── LayoutProcessorPlugin.php
│   ├── CustomerBalance/
│   │   └── CapCustomerBalanceCollectPlugin.php
│   ├── Payment/
│   │   ├── Block/
│   │   │   └── AdminSplitPaymentTitlePlugin.php
│   │   └── Checks/
│   │       └── SplitPaymentZeroTotalPlugin.php
│   ├── Quote/
│   │   └── FixSplitPaymentGrandTotalPlugin.php
│   └── Sales/
│       └── FixInvoiceCustomerBalanceAfterTotalsPlugin.php
├── Setup/
│   └── Patch/
│       └── Data/
│           └── AddSplitPaymentOrderAttribute.php
└── view/
    └── frontend/
        ├── requirejs-config.js
        ├── layout/
        │   └── sales_order_view.xml
        ├── templates/
        │   └── order/
        │       └── split-payment-info.phtml
        └── web/
            ├── js/
            │   ├── model/
            │   │   └── payment-method-helper.js
            │   └── view/
            │       └── payment/
            │           ├── cashondelivery-method.js
            │           └── split-payment.js
            └── template/
                └── payment/
                    ├── cashondelivery.html
                    └── split-payment.html

Beteendespecifikationer

​1. Databasschema (etc/db_schema.xml)

Lägg till de här kolumnerna i sales_order (resurs: sales):

Generera även db_schema_whitelist.json för dessa kolumner.

​2. Tilläggsattribut (etc/extension_attributes.xml)

Lägg till split_store_credit_amount (flyttal), split_cash_amount (flyttal), split_cash_status (sträng) i:

​3. REST-slutpunkter (etc/webapi.xml)

POST /V1/split-payment/set              → anonymous (session-scoped)
POST /V1/split-payment/orders/:orderId/cash-received  → Magento_Sales::actions
POST /V1/split-payment/orders/:orderId/cash-decline   → Magento_Sales::cancel

Alla tre kartor till Client\SplitPayment\Api\SplitPaymentManagementInterface.

​4. I/O-händelser (etc/io_events.xml)

Prenumerera på observer.sales_order_place_before och inkludera fält:
entity_id, quote_id, increment_id, subtotal, split_store_credit_amount, split_cash_amount, split_cash_status

​5. SplitPaymentSession - Sessionswrapper

Lagrar deklarerade delade belopp i utcheckningssessionen. Måste visa:

​6. SplitPaymentManagement - REST-styrenhet

setSplitPayment(float $storeCreditAmount, float $cashAmount, ?string $cartId = null): bool

markCashReceived(int $orderId): bool

markCashDeclined(int $orderId): bool

​7. PlaceOrderPlugin - aroundPlaceOrder på QuoteManagement

Det här är det viktigaste plugin-programmet. Kör aroundPlaceOrder:

​8. CopySplitPaymentToOrder — Observer på sales_model_service_quote_submit_before

Läser delningsbelopp från session → ytterligare_information → citera tilläggsattribut (i den prioritetsordningen). Skriver split_store_credit_amount, split_cash_amount, split_cash_status = 'pending' till orderobjektet.

​9. AutoInvoiceStoreCreditOnOrderPlace — Observer på sales_order_place_after

Efter orderplaceringen, om ordern har ett butikskreditbelopp (split_store_credit_amount > 0), anropar du SplitInvoiceService::createStoreCreditPortionInvoice($orderId) för att omedelbart fakturera butikskreditdelen.

10. SplitInvoiceService

createStoreCreditPortionInvoice(int $orderId): ?int
Skapar endast en faktura för butikskreditdelen. Anger customer_balance_amount på fakturan till butikskreditbeloppet. Registrerar och sparar fakturan. Returnerar fakturatabellens ID eller null vid fel (log; rethrow).

createCashPortionInvoice(int $orderId): ?int
Skapar en faktura för kassadelen (återstående orderartiklar/belopp som inte omfattas av SC-fakturan). Registrerar och sparar. Returnerar enhets-ID eller null vid fel.

​11. CheckoutPlugin — på PaymentInformationManagement

Plugin på Magento\Checkout\Model\PaymentInformationManagement::savePaymentInformationAndPlaceOrder. Innan du fortsätter:

​12. CapCustomerBalanceCollectPlugin - på totalt Customerbalance

Efter att den inbyggda summeringen av kundsaldo har körts, kan du sätta customer_balance_amount_used till SplitPaymentSession::getAmounts()['store_credit']. Detta förhindrar att Commerce överanvänder hela kundsaldot när kunden har deklarerat en mindre butik som kreditandel.

​13. FixSplitPaymentGrandTotalPlugin — den Quote\Address\Total\Grand

Efter summering av totalsummor: Om det finns en delad betalningssession och isBalanceApplyInProgress() är falskt, anger du totalsumman för offerten till sessionens kontantbelopp. Detta gör att kassan bara visar vad som förfaller i kontanter.

​14. FixInvoiceCustomerBalanceAfterTotalsPlugin — på Sales\Model\Order\Invoice

När fakturasummor har samlats in korrigerar du customer_balance_amount på fakturan om fakturans associerade order har en split_sc_invoice_id för att förhindra att butikskrediter används två gånger.

​15. SplitPaymentZeroTotalPlugin — på Payment\Model\Checks\ZeroTotal

Tillåt postförskott när SplitPaymentSession::getAmounts()['cash'] > 0, även om totalsumman för offerten är $0 (eftersom butikskrediten täcker hela ordern).

​16. LayoutProcessorPlugin — på Checkout\Block\Checkout\LayoutProcessor

När layouten har bearbetats:

​17. OrderRepositoryPlugin — på OrderRepositoryInterface

Efter get() och getList(), hydrera ordningens tilläggsattribut från de platta sales_order kolumnerna (split_store_credit_amount, split_cash_amount, split_cash_status).

​18. AdminSplitPaymentTitlePlugin — på Payment\Block\Info

När getTitle() har returnerats, om betalningsmetoden är cashondelivery och ordern har en delad betalning, lägger du till " (Split: Cash $X.XX + Store Credit $Y.YY)" i titeln.

​19. OrderPaymentPlugin — på Sales\Block\Adminhtml\Order\Payment

I _beforeToHtml eller via afterToHtml lägger du till delad betalningsinformation (kontantbelopp, butikskreditbelopp, status) i betalningsblocket HTML i ordervyn i Commerce Admin.

​20. Styrenhet för kreditsaldo i butiksbutiken

Controller/Checkout/StoreCreditBalance.php — väg: GET /splitpayment/checkout/storecreditbalance

Returnerar JSON: {"balance": float, "logged_in": bool}. Om kunden inte är inloggad returnerar {"balance": 0, "logged_in": false}. Läser saldo från Magento\CustomerBalance\Model\Balance.

Registrera klientvägen i etc/frontend/routes.xml med frontName="splitpayment".

​21. Checka ut KnockoutJS-komponent — split-payment.js

En uiComponent som:

22. cashondelivery-method.js

Utökar Magento_OfflinePayments/js/view/payment/offline-payments. payment-method-helper.js används för att identifiera kassametodkoden. Registrerar split-payment-komponenten i dess additional-region.

23. payment-method-helper.js

Verktyget returnerar getCashMethodCode() - kontrollerar window.checkoutConfig.paymentMethods för cashondelivery; återgår till checkmo vid behov.

​24. cashondelivery.html Mall

Standardmall för postförskott men innehåller <!-- ko foreach: getRegion('additional') -->-region så att den underordnade komponenten för delad betalning kan återges.

​25. split-payment.html Mall

KnockoutJS-mall för de delade betalningsfälten:

26. requirejs-config.js

Kartor:

27. etc/config.xml

Standardvärden för systemkonfiguration:

<split_payment>
  <general>
    <threshold>100</threshold>
    <enabled>1</enabled>
  </general>
</split_payment>

Information om kritisk implementering

Butikskreditprogrammet måste använda BalanceManagementInterface, inte direkt modelländring. BalanceManagementInterface::apply() hanterar sessionen, valideringen och omberäkningen av kundvagnen automatiskt.

PlaceOrderPluginmåste använda aroundPlaceOrder (inte beforePlaceOrder). Butikskrediten måste tillämpas medan vagnen fortfarande är aktiv och det måste garanteras innan $proceed() anropas.

Sessionsflaggmönstret för beginBalanceApply / endBalanceApply är kritiskt. Utan den körs FixSplitPaymentGrandTotalPlugin under collectTotals() i saldooperationen och ställer in totalsumman till kontantresten, vilket får BalanceManagementInterface::apply() att misslyckas eller begränsa krediten.

Visa aldrig kundens interna felinformation. Alla catch-block som ytan ska REST-svar måste generera LocalizedException('Payment could not be processed. Please try again or contact support.').

entity_idär det numeriska databas-ID:t. REST-anrop från App Builder använder alltid entity_id, inte increment_id.

SplitInvoiceServicebör fånga upp och logga fel i stället för att sprida dem. Fakturaskapande kan inte avbryta en redan placerad order - logga felet och låt administratören hantera det manuellt.

Efter generering av filer

Kör dessa kommandon i Commerce projektrot:

bin/magento module:enable Client_SplitPayment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Frågeslut

Relaterade POC-resurser för delad betalning