Task #193232 — Checkout API: Análise de fluxo CrmBonus

Task pai: Task 194884 — SPIKE CRM&Bônus

Status do refinamento: concluído Requisitos EARS: task-193232-checkout-crm-requisitos Pesquisas técnicas: pesquisa-crm-bonus · pesquisa-crm-bonus-analise-codigo · pesquisa-crm-bonus-documentacao-parceiro · pesquisa-crm-bonus-docs-internos · pesquisa-desconto-pix-crm-bonus ADRs: ADR-001 · ADR-004 · ADR-005 · ADR-006 · ADR-007

---

Resumo

Entender o fluxo de uso e geração de bônus CRM em um pedido no cenário onde o valor do carrinho pode aumentar após a geração do zzlink (upsell). A análise identificou que cart.CrmBonus.Total é um record imutável congelado na criação do carrinho, enquanto cart.Total pode crescer com upsell — divergência não tratada no finaliza_compra. Foram especificadas 5 RFs para investigar, decidir e corrigir essa inconsistência.

Regras principais:

• O total do carrinho pode aumentar com adição de novos produtos pelo cliente (upsell)
• O valor de bônus a ser usado como desconto é definido ao gerar o zzlink (pedido) e não será alterado
• CrmBonus é imutável após a criação do carrinho — não existem UPDATEs nas colunas CrmBonus*
• A API CRM&Bonus (EcomV2) não expõe endpoint para atualizar uma reserva existente

---

Arquivos desta pasta V2

Arquivo	Descrição
task-193232-checkout-crm	Este arquivo — sumário e índice da task
pesquisa-geracao-sem-resgate	pesquisa sobre geração e baixa de bonus CRM
task-193232-checkout-crm-requisitos	Documento de requisitos em formato EARS (pt-BR): 5 RFs abrangendo investigação com parceiro, análise de risco, decisão de negócio, bloqueio condicional e documentação

---

Análise consolidada

Fluxo atual confirmado em código

Operação	Endpoint CRM	Quando	Campo valor_bruto enviado
Reserva	baixa_bonus	Criação do pedido (CreatePaymentCommandHandler)	cart.Total — total atual do carrinho no momento da criação
Efetivação	finaliza_compra	Após captura do pagamento (PosCaptureService)	cart.CrmBonus.Total — valor congelado na criação do carrinho
Cancelamento	cancelarBonusEcom	Estorno, cancelamento, falha de captura	—

CrmBonus é imutável após a criação do carrinho

• CrmBonus é um record C# mapeado como OwnsOne na tabela Carts (colunas CrmBonusTotal, CrmBonusRescuedBonus, etc.)
• Não existe nenhum UPDATE nas colunas CrmBonus* após a criação — confirmado por análise de código e migrations
• CrmBonus.RescuedBonus e CrmBonus.Total são gravados uma única vez e nunca alterados

Divergência identificada

• CreatePaymentCommandHandler — valor_bruto = cart.Total
• PosCaptureService — valor_bruto = cart.CrmBonus.Total
• Upsell faz cart.Total crescer, mas cart.CrmBonus.Total permanece congelado → CRM recebe valor menor que o real
• ADR-007 documenta o mecanismo que torna essa divergência possível (atualização síncrona de Payment.Total)

ADRs relevantes

ADR	Relevância
ADR-007	Documenta o mecanismo que cria a divergência: Payment.Total é atualizado sincronamente com upsell
ADR-004	Endpoint AddRecommendedItem no PaymentController — mecanismo que insere itens após baixa_bonus
ADR-006	PaymentMethods recalculado quando valor muda — confirma que sistema reconhece mudança, mas CrmBonus não a vê
ADR-005	Segurança do endpoint — requisições autenticadas com JWT PaymentsScheme
ADR-001	Padrão de logging (ILogQueueService) usado também no fluxo CrmBonus