Skip to main content

Documento de Requisitos — Checkout API: Análise de fluxo CrmBonus

Tarefa: #193232 Contexto: Task 194884 — SPIKE CRM&Bônus

Visão Geral​

O fluxo de bônus CRM no checkout reserva o valor do bônus no momento da criação do pedido (baixa_bonus) e efetiva no finaliza_compra após captura do pagamento. Com a introdução do upsell (adição de itens recomendados após a criação do pedido), o valor total do carrinho pode aumentar depois da reserva, criando divergência entre o valor reservado e o valor final. Esta task especifica as investigações, análises e correções necessárias para garantir que o fluxo CrmBonus opere corretamente em cenários de upsell.

Papéis Envolvidos​

  • Time de checkout (devs) — investigação técnica, análise de código, implementação de correções
  • Parceiro CRM&Bonus — validação de comportamento da API externa
  • PO (negócio) — decisão sobre risco aceitável e postura sobre divergência de valores

Requisitos Funcionais​

RF-1 — Investigar validação de valor_bruto no finaliza_compra do CRM&Bonus​

História de Usuário: Como time de checkout, quero saber se o endpoint finaliza_compra do CRM&Bonus valida divergência entre o valor_bruto enviado e o valor reservado em baixa_bonus, para determinar se o upsell causa erros em produção ou se o CRM aceita valores diferentes.

Critérios de Aceitação:

  1. WHEN o time consultar o parceiro CRM&Bonus sobre a validação de valor_bruto no finaliza_compra THEN deve-se obter resposta clara sobre: (a) se há validação de correspondência com o baixa_bonus, (b) qual o comportamento em caso de divergência (rejeição, log, aceitação silenciosa), (c) se há impacto no cálculo de bônus gerado para o cliente

  2. WHEN a resposta do parceiro for obtida THEN deve-se documentar no contexto da task com data, meio de contato e conclusão

  3. WHEN houver registros em produção de chamadas finaliza_compra com valor_bruto divergente do baixa_bonus THEN o time técnico deve buscar logs de erro ou warning retornados pelo CRM nesses casos

Casos de Borda:

  • Parceiro não responder dentro do prazo acordado — documentar como pendente e escalar
  • Resposta ambígua ou contraditória — solicitar esclarecimento formal por escrito
  • Documentação do parceiro divergir do comportamento observado — priorizar a evidência observada

RF-2 — Avaliar risco da estratégia de cancel + re-reserva para atualização de reserva CRM​

História de Usuário: Como time de checkout, quero avaliar se a estratégia de cancelar (cancelarBonusEcom) e re-reservar (baixa_bonus) o bônus CRM é segura para cenários onde o valor do carrinho aumenta após criação do pedido, considerando atomicidade, race conditions e consistência.

Critérios de Aceitação:

  1. WHEN o time técnico analisar o comportamento do cancelarBonusEcom com used_bonus: true seguido de novo baixa_bonus THEN deve-se documentar se o CRM libera o bônus imediatamente ou se há janela de indisponibilidade

  2. WHEN houver risco de race condition identificado THEN deve-se quantificar a janela de risco e documentar cenários onde outro pedido poderia capturar o bônus

  3. WHEN a análise de risco for concluída THEN deve-se produzir recomendação formal: (a) estratégia viável com ressalvas, (b) inviável por risco inaceitável, ou (c) viável apenas com lock/mecanismo adicional

  4. WHEN a recomendação for "viável com ressalvas" ou "viável com lock adicional" THEN deve-se especificar o fluxo proposto com diagrama de sequência simplificado

Casos de Borda:

  • Chamada de cancelarBonusEcom bem-sucedida mas novo baixa_bonus falhar — o pedido fica sem reserva de bônus
  • Bônus expirado entre o cancelamento e a re-reserva
  • Concorrência: duas tentativas de upsell simultâneas no mesmo carrinho

RF-3 — Definir postura sobre divergência entre cart.Total e cart.CrmBonus.Total no finaliza_compra​

História de Usuário: Como PO, quero decidir se o PosCaptureService deve passar a usar cart.Total (incluindo upsell) em vez de cart.CrmBonus.Total no finaliza_compra, para que o CRM receba o valor real da compra.

Critérios de Aceitação:

  1. WHEN o time revisar a divergência atual (RF-1 concluída + RF-2 concluída) THEN o PO deve decidir entre: (a) corrigir PosCaptureService para usar cart.Total, (b) manter cart.CrmBonus.Total (risco aceito), ou (c) bloquear upsell em carrinhos com reserva CRM ativa

  2. WHEN a decisão for "corrigir PosCaptureService" THEN deve-se especificar a mudança: substituir cart.CrmBonus.Total por cart.Total na linha de valor_bruto do finaliza_compra

  3. WHEN a decisão for "manter cart.CrmBonus.Total (risco aceito)" THEN deve-se documentar a justificativa de negócio e o impacto no relatório de bônus do CRM

  4. WHEN a decisão envolver bloqueio de upsell THEN a RF-4 deve ser implementada

Casos de Borda:

  • Decisão mista: corrigir para upsell mas manter para fluxo sem upsell
  • Necessidade de validação com parceiro CRM sobre impacto da correção

RF-4 — Impedir upsell em carrinhos com reserva CRM ativa (condicional à RF-3)​

História de Usuário: Como sistema, quero impedir a adição de itens recomendados em carrinhos que já possuem reserva de bônus CRM ativa (aguardando finaliza_compra), para evitar inconsistência nos valores enviados ao CRM.

Critérios de Aceitação:

  1. WHEN o endpoint AddRecommendedItem for chamado para um carrinho com CrmBonus.RescuedBonus > 0 e pedido ainda não finalizado THEN o sistema deve rejeitar a requisição com código HTTP 409 (Conflict) e mensagem explicativa

  2. WHEN o endpoint RemoveRecommendedItem for chamado no mesmo cenário THEN o sistema deve rejeitar a requisição com código HTTP 409 e mensagem explicativa

  3. WHEN o carrinho não possui reserva CRM ativa (CrmBonus.RescuedBonus == 0 ou pedido já finalizado) THEN o upsell deve funcionar normalmente, sem bloqueio

Casos de Borda:

  • Carrinho com reserva CRM mas sem CrmBonus.Total (inconsistência de dados) — decidir comportamento
  • Upsell já realizado antes da reserva CRM ser ativada — permitir remoção mas bloquear nova adição
  • Mensagem de erro em pt-BR amigável para o cliente

RF-5 — Documentar CrmBonus.Total como termo imutável no glossário (CONTEXT.md)​

História de Usuário: Como dev, quero que cart.CrmBonus.Total (congelado na criação do carrinho) conste no CONTEXT.md como termo do glossário, para clareza do domínio e prevenção de interpretações incorretas futuras.

Critérios de Aceitação:

  1. WHEN o CONTEXT.md for atualizado THEN deve incluir CrmBonus.Total como termo, definindo: é um campo imutável, congelado no momento da criação do carrinho, usado como valor_bruto no finaliza_compra, e não reflete alterações de valor por upsell

  2. WHEN a atualização for revisada THEN o termo deve referenciar os ADRs relevantes (ADR-007) e as pesquisas que documentam a imutabilidade

Casos de Borda:

  • Nenhum identificado.

Dependências​

DependênciaDescriçãoStatus
Fluxo baixa_bonus / finaliza_compra existenteCódigo atual de integração CRM&Bonus no checkoutImplementado
ADR-007Ajuste síncrono do Payment.Total após AddRecommendedItemAceito
ADR-004Endpoint AddRecommendedItem no PaymentControllerAceito
Endpoints cancelarBonusEcom, baixa_bonus, finaliza_compraAPI CRM&Bonus (EcomV2) — documentação do parceiroExterna
Pesquisas CrmBonus (5)Análises já realizadas sobre fluxo, código, docs parceiro, docs internos, PIXConcluída

Questões em Aberto​

  • O CRM&Bonus precisa saber o valor real final da compra (com upsell) para fins de geração de bônus futuro ou relatório de cashback? Ou o valor_bruto é apenas usado para validar o limite do bônus resgatado?
  • Existe algum cenário já observado em produção onde baixa_bonus e finaliza_compra foram chamados com valor_bruto diferente?