Aufspaltung des Zahlungs-POC: Commerce-Modul-KI-Eingabeaufforderung

Verwenden Sie diese Seite, um die vollständige Eingabeaufforderung zu kopieren, die das Client_SplitPayment Modul „In-Process“ generiert: REST, Sitzungsbehandlung, Checkout und Admin für den Konzeptnachweis für aufgeteilte Zahlungen. Der Benutzer-Workflow verbleibt in App Builder.

So verwenden Sie diese Eingabeaufforderung

Kopieren Sie alles von PROMPT START bis Ende der Eingabeaufforderung nach Cursor (mit Claude) oder direkt nach Claude. Führen Sie sie aus dem Stammverzeichnis Ihres Commerce-Projekts oder aus einem Verzeichnis aus, in dem die API Dateien erstellen kann.

Vor der Ausführung anpassen

Die Eingabeaufforderung

PROMPT START

Sie generieren ein vollständiges, produktionsfähiges Adobe Commerce 2.4.5+ In-Process-Modul für eine Split-Payment-Funktion. Dieses Modul ist der dünne PHP-Adapter, der die richtige REST-Oberfläche bereitstellt und die richtigen Daten zum richtigen Zeitpunkt im Commerce-Lebenszyklus anbringt. Die gesamte Workflow-Logik des Benutzers lebt in Adobe App Builder (nicht in diesem Modul).

Modulidentität:

Generate every file listed in the file structure below. Do not omit any file. Use declare(strict_types=1) in all PHP files.

Zu erzeugende Dateistruktur

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

Behavioral Specifications

1. Database Schema (etc/db_schema.xml)

Add these columns to sales_order (resource: sales):

Generieren Sie auch die db_schema_whitelist.json für diese Spalten.

​2. Erweiterungsattribute (etc/extension_attributes.xml)

Fügen Sie split_store_credit_amount (float), split_cash_amount (float), split_cash_status (string) zu hinzu:

​3. REST-Endpunkte (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

Alle drei sind Client\SplitPayment\Api\SplitPaymentManagementInterface zugeordnet.

​4. I/O-Ereignisse (etc/io_events.xml)

observer.sales_order_place_before abonnieren und Felder einschließen:
entity_id, quote_id, increment_id, subtotal, split_store_credit_amount, split_cash_amount, split_cash_status

​5. SplitPaymentSession — Sitzungs-Wrapper

Speichert deklarierte aufgeteilte Beträge in der Kassensitzung. Muss Folgendes offenlegen:

​6. SplitPaymentManagement — REST-Controller

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

markCashReceived(int $orderId): bool

markCashDeclined(int $orderId): bool

​7. PlaceOrderPlugin — aroundPlaceOrder auf QuoteManagement

Dies ist das wichtigste Plug-in. Ausführungen aroundPlaceOrder:

​8. CopySplitPaymentToOrder — Beobachter auf sales_model_service_quote_submit_before

Liest aufgeteilte Beträge aus Sitzungs- → Zahlungs-Zusatzinformationen → Angebotserweiterungsattributen (in dieser Prioritätsreihenfolge). Schreibt split_store_credit_amount, split_cash_amount, split_cash_status = 'pending' in das Bestellobjekt.

​9. AutoInvoiceStoreCreditOnOrderPlace — Beobachter auf sales_order_place_after

Wenn der Auftrag nach der Auftragserteilung über einen Store-Guthabenbetrag (split_store_credit_amount > 0) verfügt, rufen Sie SplitInvoiceService::createStoreCreditPortionInvoice($orderId) an, um den Store-Guthabenanteil sofort zu fakturieren.

10. SplitInvoiceService

createStoreCreditPortionInvoice(int $orderId): ?int
Erstellt eine Rechnung nur für den Gutschriftanteil des Geschäfts. Setzt customer_balance_amount auf der Rechnung auf den Gutschriftsbetrag. Registriert und speichert die Rechnung. Gibt bei einem Fehler die Rechnungsentitäts-ID oder null aus (Protokoll; nicht erneut auslösen).

createCashPortionInvoice(int $orderId): ?int
Erstellt eine Rechnung für den Baranteil (die verbleibenden Auftragspositionen/Beträge, die nicht von der SC-Rechnung abgedeckt sind). Registriert und speichert. Gibt bei einem Fehler die Entitäts-ID oder null zurück.

​11. CheckoutPlugin — PaymentInformationManagement

Plug-in auf Magento\Checkout\Model\PaymentInformationManagement::savePaymentInformationAndPlaceOrder. Bevor Sie fortfahren:

​12. CapCustomerBalanceCollectPlugin — auf Customerbalance Gesamtbetrag

Nach der Ausführung des nativen Sammelvorgangs für den Kundensaldo ist die Obergrenze auf customer_balance_amount_used zu SplitPaymentSession::getAmounts()['store_credit']. Dadurch wird verhindert, dass Commerce den gesamten Kundensaldo überzieht, wenn der Kunde einen kleineren Anteil des Filialguthabens angegeben hat.

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

Nach der Gesamterhebung der Gesamtsumme: Wenn eine Aufspaltungszahlungssitzung vorhanden ist und isBalanceApplyInProgress() „false“ ist, setzen Sie die Gesamtsumme des Angebots auf den Barbetrag der Sitzung. Dadurch wird in der Benutzeroberfläche an der Kasse nur angezeigt, was in bar fällig ist.

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

Wenn die zugehörige Bestellung der Rechnung nach dem Einzug der Rechnungssummen einen split_sc_invoice_id aufweist, korrigieren Sie die customer_balance_amount auf der Rechnung, um eine doppelte Zuordnung der Warenkorbgutschrift zu verhindern.

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

Nachnahme bei SplitPaymentSession::getAmounts()['cash'] > 0 zulassen, auch wenn die Gesamtsumme des Angebots 0 USD beträgt (da die gesamte Bestellung durch eine Gutschrift im Geschäft abgedeckt ist).

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

Nachdem das Layout verarbeitet wurde:

​17. OrderRepositoryPlugin — OrderRepositoryInterface

Hydrieren Sie nach dem get() und getList() die Erweiterungsattribute der Bestellung aus den flachen sales_order (split_store_credit_amount, split_cash_amount, split_cash_status).

​18. AdminSplitPaymentTitlePlugin — Payment\Block\Info

Wenn nach getTitle() Rückgabe die Zahlungsmethode cashondelivery ist und die Bestellung eine aufgeteilte Zahlung aufweist, hängen Sie " (Split: Cash $X.XX + Store Credit $Y.YY)" an den Titel an.

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

Hängen Sie in _beforeToHtml oder über „afterToHtml“ die aufgeteilten Zahlungsdetails (Barbetrag, Kreditbetrag speichern, Status) an den Zahlungsblock “HTML” in der Commerce Admin-Auftragsansicht an.

​20. Storefront Store-Guthabencontroller

Controller/Checkout/StoreCreditBalance.php — Strecke: GET /splitpayment/checkout/storecreditbalance

Gibt JSON zurück: {"balance": float, "logged_in": bool}. Wenn der Kunde nicht angemeldet ist, gibt {"balance": 0, "logged_in": false} zurück. Liest den Saldo aus Magento\CustomerBalance\Model\Balance.

Registrieren Sie die Frontend-Route in etc/frontend/routes.xml bei frontName="splitpayment".

​21. Checkout-KnockoutJS-Komponente — split-payment.js

Eine uiComponent, die:

22. cashondelivery-method.js

Erweitert Magento_OfflinePayments/js/view/payment/offline-payments. Verwendet payment-method-helper.js zur Erkennung des Bargeldmethodencodes. Registers split-payment component in its additional region.

23. payment-method-helper.js

Utility returning getCashMethodCode() — checks window.checkoutConfig.paymentMethods for cashondelivery; falls back to checkmo if needed.

24. cashondelivery.html Template

Standard COD template but includes <!-- ko foreach: getRegion('additional') --> region so the split payment child component can render.

25. split-payment.html Template

KnockoutJS template for the split payment fields:

26. requirejs-config.js

Maps:

27. etc/config.xml

Default system config values:

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

Critical Implementation Notes

Store credit application must use BalanceManagementInterface, not direct model manipulation. BalanceManagementInterface::apply() handles the session, validation, and cart recalculation atomically.

PlaceOrderPluginmust use aroundPlaceOrder (not beforePlaceOrder). The store credit must be applied while the cart is still active, and that must be guaranteed before $proceed() is called.

The session flag pattern for beginBalanceApply / endBalanceApply is critical. Without it, FixSplitPaymentGrandTotalPlugin runs during collectTotals() inside the balance operation and sets grand total to the cash remainder, causing BalanceManagementInterface::apply() to fail or cap the credit.

Never expose internal error details to the customer. All catch blocks that surface to REST responses must throw LocalizedException('Payment could not be processed. Please try again or contact support.').

entity_idist die numerische Datenbank-ID. REST-Aufrufe aus App Builder verwenden immer entity_id, nicht increment_id.

SplitInvoiceServicesollten Fehler erfassen und protokollieren, anstatt sie zu propagieren. Fehlgeschlagene Rechnungserstellung sollte eine bereits platzierte Bestellung nicht stornieren - protokollieren Sie den Fehler und lassen Sie ihn vom Administrator manuell bearbeiten.

Nach dem Generieren von Dateien

Führen Sie diese Befehle im Commerce-Projektstamm aus:

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

Ende der Eingabeaufforderung

Gerelateerde gesplitste betalingen POC-middelen