Split payment POC: Commerce module AI prompt

Use this page to copy the full prompt that generates the Client_SplitPayment in-process module: REST, session handling, Checkout, and Admin display for the split payment proof of concept. Operator workflow stays in App Builder.

Como usar este prompt

Copie tudo de PROMPT START para End of prompt no Cursor (com Claude) ou diretamente no Claude. Run it from the root of your Commerce project or a directory where the AI can create files.

Customize before you run

O prompt

INÍCIO DA SOLICITAÇÃO

You are generating a complete, production-ready Adobe Commerce 2.4.5+ in-process module for a split payment feature. This module is the thin PHP adapter that exposes the right REST surface and attaches the right data at the right moments in the Commerce lifecycle. All operator workflow logic lives in Adobe App Builder (not in this module).

Module identity:

Gere cada arquivo listado na estrutura de arquivo abaixo. Não omita nenhum arquivo. Use declare(strict_types=1) em todos os arquivos PHP.

Estrutura de arquivo a ser gerada

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

Especificações comportamentais

​1. Esquema de Banco de Dados (etc/db_schema.xml)

Adicionar estas colunas a sales_order (recurso: sales):

Gere também o db_schema_whitelist.json para essas colunas.

​2. Atributos de Extensão (etc/extension_attributes.xml)

Adicionar split_store_credit_amount (flutuante), split_cash_amount (flutuante), split_cash_status (cadeia de caracteres) a:

​3. Pontos de Extremidade REST (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

Todos os três mapeiam para Client\SplitPayment\Api\SplitPaymentManagementInterface.

​4. Eventos de E/S (etc/io_events.xml)

Inscrever-se em observer.sales_order_place_before e incluir campos:
entity_id, quote_id, increment_id, subtotal, split_store_credit_amount, split_cash_amount, split_cash_status

​5. SplitPaymentSession — Wrapper de Sessões

Armazena valores divididos declarados na sessão de finalização. Deve expor:

​6. SplitPaymentManagement — Controlador REST

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

markCashReceived(int $orderId): bool

markCashDeclined(int $orderId): bool

​7. PlaceOrderPlugin — aroundPlaceOrder em QuoteManagement

Este é o plug-in mais importante. Executa aroundPlaceOrder:

​8. CopySplitPaymentToOrder — Observador em sales_model_service_quote_submit_before

Lê valores divididos de sessão → pagamento additional_information → atributos de extensão de cotação (nessa ordem de prioridade). Grava split_store_credit_amount, split_cash_amount, split_cash_status = 'pending' no objeto de ordem.

​9. AutoInvoiceStoreCreditOnOrderPlace — Observador em sales_order_place_after

Após o posicionamento do pedido, se o pedido tiver um valor de crédito de armazenamento (split_store_credit_amount > 0), chame SplitInvoiceService::createStoreCreditPortionInvoice($orderId) para faturar imediatamente a parte de crédito de armazenamento.

10. SplitInvoiceService

createStoreCreditPortionInvoice(int $orderId): ?int
Cria uma fatura somente para a parte de crédito da loja. Define customer_balance_amount na fatura para o valor de crédito da loja. Registra e salva a fatura. Retorna a ID de entidade da fatura ou nulo na falha (log; não relançar).

createCashPortionInvoice(int $orderId): ?int
Cria uma fatura para a porção de caixa (os itens/valores restantes da ordem não cobertos pela fatura SC). Registra e salva. Retorna a ID da entidade ou nulo em caso de falha.

​11. CheckoutPlugin — em PaymentInformationManagement

Plug-in em Magento\Checkout\Model\PaymentInformationManagement::savePaymentInformationAndPlaceOrder. Antes de continuar:

​12. CapCustomerBalanceCollectPlugin — em Customerbalance total

Depois que a coleta de saldo total do cliente nativo for executada, limite de customer_balance_amount_used a SplitPaymentSession::getAmounts()['store_credit']. Isso evita que o Commerce aplique em excesso o saldo completo do cliente quando ele declarar uma parte menor de crédito da loja.

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

Após a coleta do total geral: se existir uma sessão de pagamento parcelado e isBalanceApplyInProgress() for falso, defina o total geral da cotação para o valor em dinheiro da sessão. Isso faz com que a interface do usuário de check-out mostre apenas o que está vencido em dinheiro.

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

Depois que os totais da fatura forem coletados, se a ordem associada da fatura tiver um split_sc_invoice_id, corrija o customer_balance_amount na fatura para evitar a aplicação dupla de crédito de loja.

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

Permitir pagamento de CQO quando SplitPaymentSession::getAmounts()['cash'] > 0, mesmo que o total geral da cotação seja $0 (porque o crédito da loja cobre a ordem inteira).

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

Depois que o layout for processado:

​17. OrderRepositoryPlugin — em OrderRepositoryInterface

Depois de get() e getList(), hidratar os atributos de extensão do pedido das sales_order colunas simples (split_store_credit_amount, split_cash_amount, split_cash_status).

​18. AdminSplitPaymentTitlePlugin — em Payment\Block\Info

Depois de getTitle() retornar, se o método de pagamento for cashondelivery e a ordem tiver um pagamento dividido, anexe " (Split: Cash $X.XX + Store Credit $Y.YY)" ao título.

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

Em _beforeToHtml ou via afterToHtml, anexe os detalhes do pagamento dividido (valor do pagamento à vista, valor do crédito da loja, status) ao bloco de pagamento HTML na exibição de ordem do Administrador do Commerce.

​20. Controlador de Saldo de Crédito da Loja

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

Retorna JSON: {"balance": float, "logged_in": bool}. Se o cliente não estiver conectado, retorna {"balance": 0, "logged_in": false}. Saldo de leitura de Magento\CustomerBalance\Model\Balance.

Registrar a rota de front-end em etc/frontend/routes.xml com frontName="splitpayment".

​21. Componente KnockoutJS de Check-out — split-payment.js

Um uiComponent que:

22. cashondelivery-method.js

Estende Magento_OfflinePayments/js/view/payment/offline-payments. Usa payment-method-helper.js para detectar o código do método de pagamento à vista. Registra o componente split-payment em sua região additional.

23. payment-method-helper.js

Utilitário retornando getCashMethodCode() — verifica window.checkoutConfig.paymentMethods para cashondelivery; retorna para checkmo se necessário.

​24. cashondelivery.html Modelo

Modelo CQO padrão, mas inclui a região <!-- ko foreach: getRegion('additional') --> para que o componente filho do pagamento dividido possa ser renderizado.

​25. split-payment.html Modelo

Modelo KnockoutJS para os campos de pagamento dividido:

26. requirejs-config.js

Mapas:

27. etc/config.xml

Valores padrão de configuração do sistema:

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

Notas de implementação críticas

O aplicativo de crédito de armazenamento deve usar BalanceManagementInterface, não a manipulação de modelo direta. BalanceManagementInterface::apply() manipula atentamente a sessão, a validação e o recálculo do carrinho.

PlaceOrderPlugindeve usar aroundPlaceOrder (não beforePlaceOrder). O crédito da loja deve ser aplicado enquanto o carrinho ainda está ativo, e isso deve ser garantido antes que $proceed() seja chamado.

O padrão de sinalizador de sessão para beginBalanceApply / endBalanceApply é crítico. Sem ele, FixSplitPaymentGrandTotalPlugin é executado durante collectTotals() dentro da operação de saldo e define o total geral como o restante do caixa, fazendo com que BalanceManagementInterface::apply() falhe ou limite o crédito.

Nunca exponha detalhes de erros internos ao cliente. Todos os blocos catch que superam para respostas REST devem lançar LocalizedException('Payment could not be processed. Please try again or contact support.').

entity_idis the numeric database ID. REST calls from App Builder always use entity_id, not increment_id.

SplitInvoiceServiceshould catch and log errors rather than propagate them. Invoice creation failure should not cancel an already-placed order — log the failure and let the Admin handle it manually.

Após gerar os arquivos

Run these commands in the Commerce project root:

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

Fim da solicitação

Related split payment POC resources