req-098: Suporte Nativo ao Checkout Transparente e Tokenização na Biblioteca PayPal (PHP e JS)

Descrição do Problema / Contexto

Esta requisição (BATCH-104) tem como objetivo expandir a infraestrutura da biblioteca PayPal do core (conn2flow) para oferecer suporte nativo ao Checkout Transparente (Cartão de Crédito direto na tela via Hosted Fields / Card Fields) e ao fluxo de tokenização (PCI-DSS SAQ-A).

A demanda compreende a extensão das funções REST na biblioteca PHP (gestor/bibliotecas/paypal.php) para geração de client_token e suporte ao parâmetro payment_source, além da criação da biblioteca utilitária JavaScript (gestor/assets/paypal/paypal.js) para carregamento dinâmico do SDK oficial e gestão dos Card Fields no frontend.

Proposta de Alterações Detalhada

PARTE I: Extensão da Biblioteca PHP (gestor/bibliotecas/paypal.php)

1. paypal_gerar_client_token($params = false):

   • Endpoint: POST /v1/identity/generate-token

   • Headers: Authorization: Bearer <access_token> (usando paypal_autenticar()).

   • Parâmetros: Recebe opcionalmente $params['customer_id'] string (injetando {"customer_id": "..."} no payload JSON da requisição quando fornecido).

   • Retorno: Retorna a string client_token extraída da resposta da API do PayPal (ou false em caso de erro ou resposta com HTTP != 200).

2. Atualização de paypal_criar_pedido($params) e paypal_criar_assinatura($params):

   • Aceitar Parâmetro: Suportar a propriedade opcional $params['payment_source'] (array).

   • Injeção de Payload: Quando $params['payment_source'] for fornecido, injetá-lo diretamente no payload JSON enviado para os endpoints /v2/checkout/orders (paypal_criar_pedido) e /v1/billing/subscriptions (paypal_criar_assinatura).

   • Compatibilidade com Tokenização: Garantir suporte a payloads de cartão tokenizado (payment_source.card ou payment_source.token) e autorizações diretas via Hosted Fields.

3. Helper paypal_processar_pagamento_transparente($params = false):

   • Helper utilitário backend para validar o payload recebido do frontend.

   • Trata a execução da cobrança/autorização de pedido ou criação de assinatura invocando paypal_criar_pedido / paypal_capturar_pedido ou paypal_criar_assinatura com o payment_source apropriado.

PARTE II: Criação da Biblioteca JavaScript (gestor/assets/paypal/paypal.js)

1. Carregamento Dinâmico do SDK (paypalCarregamentoSDK(options)):

   • Função utilitária para carregar dinamicamente a tag <script src="[REDACTED]> no documento.

   • Parâmetros obrigatórios e opcionais na query string:

     • client-id: Client ID do PayPal (Sandbox ou Live).

     • components: padrão buttons,card-fields.

     • vault: true (quando aplicável).

     • intent: subscription ou capture (quando aplicável).

     • data-client-token: Client Token obtido do backend via paypal_gerar_client_token().

   • Retorna Promise que resolve quando o SDK é carregado e disponibilizado em window.paypal.

2. Inicialização de Card Fields / Hosted Fields (paypalCardFieldsInit(options)):

   • Renderização e estilização dos iFrames de segurança do PayPal nos contêineres do formulário:

     • #card-number-container (ou seletor customizado em options.numberContainer)

     • #card-expiry-container (ou seletor em options.expiryContainer)

     • #card-cvv-container (ou seletor em options.cvvContainer)

     • #card-holder-container (ou seletor em options.holderContainer)

   • Injeção de classes CSS para estados de foco, válido e inválido.

   • Adição de event listeners para validação em tempo real com retorno visual (número inválido, data expirada, CVV com tamanho incorreto).

3. Tokenização no Submit (paypalCardFieldsSubmit(options)):

   • Função executada no evento de submissão do formulário de pagamento.

   • Dispara o método de tokenização/submissão do CardFields do PayPal.

   • Retorna Promise com o objeto payment_source (contendo token/nonce de cartão) para ser enviado via AJAX ao backend.

PARTE III: Validação e Entrega no SDD

1. Validação de Sintaxe:

   • Executar php -l gestor/bibliotecas/paypal.php.

   • Executar node --check gestor/assets/paypal/paypal.js.

2. Suíte de Testes e Compatibilidade:

   • Garantir que todas as chamadas existentes em paypal.php continuem funcionando sem regressão (compatibilidade retroativa com fluxos padrão do PayPal).

   • Executar suíte de testes composer test.

3. Regras de Entrega:

   • Registrar alterações e decisões em sdd/decisions/DECISION-LOG.md (DEC-100) e sdd/implementation/BATCH-INDEX.md (BATCH-104).

   • NÃO realizar commit/push automático no Git sem autorização explícita do usuário.