Avalia Sales

Antes e depois da atualização

1. Revendas isoladas em duas camadas: aplicação e banco de dados

   Filtro do EF Core e row-level security no PostgreSQL: se a aplicação falhar, o banco recusa.

   Ver contexto e evidência

   Contexto

   Várias revendas usam o mesmo banco, cada uma com clientes, vendas e dinheiro próprios.

   Decisão

   Filtro global do EF Core pela revenda do login e row-level security forçada no PostgreSQL. A aplicação conecta com um papel sem permissão para ignorar a regra.

   Motivo

   Uma consulta que esqueça o filtro não alcança dados de outra revenda: o banco recusa.

   Evidência

   ADR 0001Testes de isolamento

   Um teste reprova a publicação se uma tabela com revenda nascer sem a regra.

   Vale em todas as etapas do fluxo de venda

2. Pagamento confirmado na origem, no gateway, e aplicado uma vez

   A venda só fica paga depois de o Worker reconsultar a cobrança no Pagar.me, uma vez por evento.

   Ver contexto e evidência

   Contexto

   O webhook do Pagar.me pode chegar repetido, fora de ordem ou forjado, e a rede pode cair no meio da cobrança.

   Decisão

   A cobrança é gravada antes de chamar o Pagar.me, numa transação que recusa uma segunda cobrança viva da mesma venda. O webhook só registra o evento. O Worker reconsulta a cobrança no gateway e trava a linha do evento (FOR UPDATE SKIP LOCKED) antes da baixa. Uma vez por dia reconsulta também as cobranças pagas, para pegar estorno e chargeback feitos no painel do Pagar.me.

   Motivo

   A venda só muda de situação pelo estado confirmado no Pagar.me, e o mesmo aviso não é aplicado duas vezes.

   Evidência

   ADR 0004ADR 0005Testes do pagamentoTeste de chargeback

   No fluxo: etapas 3 e 4

3. Aritmética monetária em inteiros e razão append-only

   Valores em centavos como inteiros, sem ponto flutuante, e razão só de inserção: correção entra como estorno.

   Ver contexto e evidência

   Contexto

   Split, comissão, estorno parcial e fechamento de mês precisam fechar ao centavo.

   Decisão

   Valores inteiros em centavos. O razão só recebe inserção: correção entra como estorno. O mês fechado é travado por trigger, e o banco nega UPDATE e DELETE no razão ao papel da aplicação.

   Motivo

   Qualquer saldo pode ser refeito a partir das linhas, e nenhuma correção apaga o que já foi lançado.

   Evidência

   ADR 0003ADR 0011ADR 0020

   No fluxo: etapa 5

4. Gravação repetida responde igual, sem efeito duplo

   Toda gravação POST autenticada aceita Idempotency-Key: a mesma chave devolve a resposta gravada, sem cobrar nem lançar de novo.

   Ver contexto e evidência

   Contexto

   Duplo clique, rede lenta e nova tentativa do navegador reenviam a mesma gravação.

   Decisão

   Um middleware guarda a resposta por 24 horas, por usuário e rota. A mesma chave com outro corpo responde 422, e a execução simultânea responde 409. O front manda uma chave por chamada.

   Motivo

   Repetir o pedido não cobra, não comissiona e não envia e-mail duas vezes.

   Evidência

   Testes de idempotênciaSDD

   No fluxo: etapa 3

5. Migração incremental a partir do sistema em Laravel/PHP

   Rotas trocadas uma a uma, dados importados numa transação e virada concluída em 24/10/2026, sem mudar o endereço das placas vendidas.

   Ver contexto e evidência

   Contexto

   O sistema anterior estava em uso, com placas impressas cujo endereço do QR Code não pode mudar.

   Decisão

   As rotas do sistema anterior passaram a redirecionar para a nova plataforma uma a uma (padrão strangler fig). Os dados foram convertidos a partir do backup e importados numa transação única, depois de um ensaio. As placas estão hoje na plataforma, e o endereço antigo (/q/) repassa para o novo com 302, sem cache. O histórico financeiro das vendas também é importável, para a DRE dos meses de origem.

   Motivo

   A operação continuou durante a troca, e uma importação com erro é desfeita por inteiro.

   Evidência

   OperaçãoConversorImportação

   No fluxo: etapa 6, o endereço da placa

• Testes automáticos

  519 testes da API (xUnit, contra PostgreSQL real, com o papel e o RLS da produção), 223 do front (Vitest, com axe) e 25 cenários ponta a ponta (Playwright), no celular e no computador.

  Testes da API

• Publicação controlada

  CI verde, com análise do SonarCloud, aprovação manual, cópia do banco antes de subir e health check pelo domínio. Rollback por nova publicação do commit anterior.

  Fluxo de publicação

• Contrato entre front e API

  Tipos do front gerados do OpenAPI da API. O CI falha se estiverem desatualizados.

  Verificações do CI

• Erros rastreados por versão

  Erros da API, do Worker e do navegador chegam ao Sentry marcados com o commit publicado. Monitor de disponibilidade em /api/health a cada 60 s e check-in do Worker a cada 5 minutos.

• Segurança e dados pessoais

  Revisão em quatro frentes (autorização e isolamento, dinheiro e fila, sessão e entrada, front-end), com testes no repositório. Sessão curta com refresh rotativo, segundo fator, captcha no cadastro público e cartão tokenizado no navegador. Contato de cliente alheio sai mascarado para o vendedor.

• Cópia do banco fora do servidor

  Cópia diária cifrada (AES-256) para um bucket no Cloudflare R2, conferida pelo ETag, com retenção de 30 dias, e também por e-mail, cifrada. Só vale a cópia que o pg_restore consegue ler.

  Backup e restauração

Integrações e o estado de cada uma

• Regras do produtoPDD: cada regra de venda, cobrança, comissão e placa
• ArquiteturaSDD: camadas, tabelas, integrações e o registro de mudanças
• 22 registros de decisãoADRs com contexto, opções e consequências
• OperaçãoInstalação, publicação, volta de versão, backup e restauração
• Contrato da APIOpenAPI de onde saem os tipos do front
• Código-fonteRepositório completo no GitHub

White label com contraste calculado

Cada revenda aplica logo e cor nas telas. A plataforma escolhe a cor do texto do botão e escurece o destaque até a leitura passar no critério do WCAG.