Vetor Carrinho De Compras

Implementando um vetor para carrinho de compras

Um vetor de carrinho de compras é basicamente uma estrutura de dados que armazena os itens que um usuário adicionou à loja virtual antes de finalizar o pedido. No mundo real, isso geralmente significa um array ou lista que contém objetos com informações como código do produto, quantidade, preço unitário e às vezes variantes como cor ou tamanho. A simplicidade é enganosa. A parte difícil começa quando você precisa manter isso sincronizado entre página, sessão e servidor. Não é apenas um array com SKUs. Um vetor funcional precisa lidar com acúmulo de quantidades quando o mesmo item é adicionado múltiplas vezes, cálculo de subtotal por linha, subtotal geral, aplicação de desconto, taxa de envio e impostos. Se você tratar cada coisa separadamente, vai terminar com seis variáveis desincronizadas e um bug que só aparece quando o cupom de desconto é aplicado após a alteração da quantidade. Minha abordagem padrão tem sido usar um objeto mapeado por ID do produto dentro de um array, onde cada entrada carrega id, quantidade, preco_unitario, e metadados opcionais como variant_id. Quando o usuário adiciona o mesmo produto de novo, eu atualizo a quantidade em vez de criar outra entrada. Isso reduz complexidade e evita duplicação no frontend e no backend.

Um detalhe que todo mundo subestima: a formatação de moeda não deve existir no vetor. O vetor armazena valores numéricos inteiros em centavos, não strings formatadas. Eu perdi duas noites debugando um problema onde o frontend enviava "R$ 49,90" e o backend tentava somar com parseFloat, gerando NaN silenciosamente. A solução foi impor uma regra de conversão obrigatória na camada de API, com validação estrita e rejeição imediata de qualquer payload com campo de preço em formato texto.

Como construir do zero

O ponto de partida é definir o esquema do item. Algo simples assim: item: { id: string, quantity: number, price_cents: number, variant_id?: string } Depois, as operações básicas: adicionar, remover, atualizar quantidade, esvaziar e calcular total. Cada uma dessas operações deve retornar um novo estado, não modificar o existente, especialmente se você estiver usando React ou qualquer biblioteca reativa. Mutação direta de estado é uma das causas mais comuns de bugs randômicos em carrinho.

Para o cálculo do total, use uma função pura que recebe o vetor e retorna os subtotais. Isso facilita teste unitário e evita lógica espalhada por vários componentes. Eu costumo retornar um objeto com total_itens, total_soma, total_desconto e total_final, todos em centavos. Dessa forma, o frontend só format para exibição. A persistência é outra trincheira. Carrinho no localStorage sobrevive a recarregamentos mas não sincroniza entre dispositivos. Carrinho na sessão do servidor exige autenticação obrigatória ou pelo menos um identificador de sessão confiável. Eu sempre uso uma combinação: estado efêmero no cliente para velocidade, e sincronização assíncrona com o servidor a cada alteração relevante. O servidor é a fonte da verdade. Se houver conflito, o servidor vence. Isso evita situações absurdas onde dois abas diferentes atualizam o carrinho e sobrescrevem uma à outra.

Problema real que eu enfrentei e o workaround

Em um projeto com produtos de assinatura e produtos avulsos convivendo no mesmo carrinho, apareceu um bug intermitente onde o valor do frete era calculado errado quando havia itens de categorias diferentes. O vetor carregava os dados corretos, o cálculo parecia sólido, mas o resultado final estava sempre alguns reais abaixo do esperado. O problema era que um middleware de otimização dePayload estaba removendo campos considerados "órfãos" do objeto item, e o campo variant_id era apagado em alguns casos. Sem variant_id, a regra de frete que depende da categoria do produto recalculava com base na categoria padrão, que era mais barata. O fix foi adicionar uma lista branca explícita de campos que nunca podem ser removidos do payload do carrinho, incluindo variant_id, e forçar validação em tempo de build do vetor. Uma lição prática: sempre valide o formato do payload no ponto de entrada, não confie em camadas intermediárias. Esse tipo de bug passa semanas sem ser descoberto porque o log parece até o momento em que o usuário vê o valor errado no checkout.

Erros comuns que iniciantes cometem

Armazenar preço no vetor do cliente é o erro mais frequente. Preço deve vir sempre do servidor no momento da confirmação. Preço armazenado localmente pode ficar desatualizado se o produto sofreu reajuste. Carrinhos já foram entregues com preço antigo e o cliente reclamou. Isso gera perda financeira real e retrabalho no suporte. Outro erro comum é não tratar itens esgotados. O vetor pode continuar exibindo um produto que saiu de estoque. Você precisa de um mecanismo de verificação síncrona ou pelo menos um aviso claro antes do pagamento. Eu implemento uma verificação em lote que roda ao carregar o checkout e remove ou marca como indisponível itens cujo estoque caiu para zero.

Quando não usar vetor simples

Vetor é suficiente para a maioria dos casos, mas existe um limite. Se seu carrinho precisa lidar com milhares de itens, personalizações massivas por linha, ou regras de desconto extremamente complexas que dependem de combinações entre itens, um vetor plano se torna ingovernável. Nesse cenário, uma estrutura orientada a regras ou um motor de pricedesign separado faz mais sentido. Eu já vi equipe inteira migrar de vetor para um serviço de cálculo dedicado porque as exceções estavam sobrecarregando a lógica do carrinho. Se o seu produto tem variação combinatória, tipo camisa com tamanho e bordado personalizado, o vetor tradicional não comporta bem. Aí o modelo precisa evoluir para uma estrutura mais rica, com subitens ou linhas aninhadas, senão o custo de manutenção cresce exponencialmente.

Código básico de referência

Aqui está um exemplo mínimo em JavaScript que cobre as operações essenciais: function addItem(cart, product) {
const existing = cart.find(i => i.id === product.id);
if (existing) {
return cart.map(i => i.id === product.id ? {...i, quantity: i.quantity + product.quantity} : i);
}
return [...cart, {...product}];
}

function removeItem(cart, id) {
return cart.filter(i => i.id !== id);
}

function updateQuantity(cart, id, quantity) {
if (quantity <= 0) return removeItem(cart, id);
return cart.map(i => i.id === id ? {...i, quantity} : i);
}

function calculateTotal(cart) {
return cart.reduce((acc, item) => acc + item.price_cents * item.quantity, 0);
} Isso é o esqueleto. A produção exige muito mais: controle de concorrência, tratamento de falhas de rede, versionamento de preço, e integração com gateway de pagamento. Mas o conceito permanece o mesmo. Vetor limpo, funções puras, estado imutável e preço vindo do servidor.

Se você quer um repositório de exemplo funcional com essas práticas, posso indicar um template básico que use esse padrão em React com context API. Não tem vínculo com nenhum produto específico, é apenas estrutura pura. O importante é começar certo, porque refatorar carrinho depois que já está em produção custa caro e quebra experiência do usuário.