Skip to content

artubss/SKILLS-CLAUDE-CODE / favorites/tpl-dominio-ecommerce-completo

tpl-dominio-ecommerce-completo

Verified

Template do pack (dominio/02-ecommerce-completo.md). Orienta o agente em regras de negocio e requisitos de produto alinhado a esse contexto.

DOMAIN: E-commerce Completo

Skill gerado a partir do pack templates-claude-code. Arquivo de origem: dominio/02-ecommerce-completo.md. Use como baseline e adapte ao projeto antes de mudancas grandes.

Conteudo do template

CONTEXT

E-commerce parece simples até o primeiro pedido com problema. Inventário que vende negativo, carrinho que não persiste entre dispositivos, tax calculation incorreta, estado de pedido inconsistente entre sistemas — são os bugs que chegam às 2h da manhã em produção. O coração do e-commerce é uma máquina de estados de pedido — modelar errado gera dívida técnica impossível de pagar.

STACK ASSUMPTIONS

  • Backend: Node.js / Laravel / Django / Rails
  • DB: PostgreSQL (transações, locks otimistas/pessimistas, constraints)
  • Cache: Redis (carrinho, sessions, rate limiting)
  • Storage: S3/GCS para imagens de produto
  • Search: Elasticsearch ou Algolia para catálogo
  • Queue: BullMQ / SQS para processamento de pedidos assíncrono
  • Tax: TaxJar / Avalara ou cálculo próprio (ICMS BR)

CORE CONCEPTS

  • SKU vs Product: Product é entidade de catálogo; SKU é a unidade vendável (cor+tamanho)
  • Cart Session: carrinho anônimo (session/Redis) vs carrinho autenticado (DB) — merge no login
  • Inventory Hold: reservar estoque no add-to-cart vs no checkout vs no pagamento
  • Order State Machine: pending → confirmed → processing → shipped → delivered | canceled | refunded
  • Proration/Return: pedido de devolução cria novo fluxo, não desfaz o original
  • Tax Calculation: deve ocorrer no checkout final, não no carrinho (endereço pode mudar)
  • Checkout Session: snapshot imutável do carrinho no momento do checkout (preços podem mudar)

ARCHITECTURE RULES

Catálogo de Produtos

  • Separar Product (info de catálogo) de ProductVariant (SKU, preço, estoque)
  • Imagens: armazenar URLs do CDN, nunca base64 em banco
  • Slug único global para SEO (não apenas por categoria)
  • Soft delete produtos — pedidos antigos precisam referenciar produto deletado

Carrinho

  • Carrinho anônimo: cart_id em cookie + dados no Redis (TTL 7 dias)
  • Carrinho autenticado: salvar no banco ao fazer login (merge com anônimo)
  • Ao merge: se mesmo produto em ambos, somar quantidades respeitando estoque
  • Nunca confiar no preço do carrinho para cobrança — sempre recalcular na hora do checkout

Gestão de Estoque

  • Usar SELECT ... FOR UPDATE (pessimistic lock) ao decrementar estoque
  • Reserva temporária no add-to-cart: decremento em reserved_quantity, não em quantity
  • Liberar reserva se checkout não completado em 15 min (job agendado)
  • Confirmar decremento em quantity apenas com pagamento confirmado
  • Nunca permitir quantidade negativa — constraint no banco + validação na aplicação

Máquina de Estados do Pedido

pending → payment_processing → confirmed → processing → shipped → delivered
                ↓                    ↓           ↓
           payment_failed        canceled    return_requested → returned → refunded
  • Transições de estado via eventos (domain events ou state machine lib)
  • Cada transição dispara: email, inventory update, webhook para ERP
  • Nunca saltar estados — validar transição antes de executar

Checkout Flow

  1. Criar CheckoutSession (snapshot de carrinho: produtos, preços, quantidades)
  2. Calcular tax com endereço de entrega final
  3. Reservar estoque
  4. Processar pagamento
  5. Em sucesso: confirmar pedido, decrementar estoque real, liberar reserva
  6. Em falha: liberar reserva, notificar usuário

ROUTING TABLE

TriggerAction
GET /products?category=X&sort=priceBuscar com filtros, paginação cursor-based
GET /products/:slugRetornar produto com todas as variantes e estoque
POST /cart/itemsAdicionar ao carrinho (criar se não existe, verificar estoque)
PATCH /cart/items/:skuAtualizar quantidade (verificar disponibilidade)
DELETE /cart/items/:skuRemover item do carrinho
POST /cart/mergeMerge carrinho anônimo com autenticado no login
POST /checkout/sessionCriar checkout session (snapshot + tax calc + reserva)
POST /checkout/completeProcessar pagamento → confirmar ou falhar pedido
GET /orders/:idDetalhe do pedido (com linha do tempo de estados)
POST /orders/:id/cancelCancelar se estado permite → liberar estoque → estorno
POST /orders/:id/returnIniciar fluxo de devolução → gerar label → aguardar recebimento
POST /admin/inventory/adjustAjuste manual de estoque com motivo (auditoria)
GET /admin/orders?status=pendingListar com filtros, server-side pagination
POST /webhooks/shippingAtualizar tracking status → notificar cliente
POST /admin/products/:id/variantsCriar nova variante (SKU, preço, estoque inicial)

CRITICAL RULES

  1. NUNCA decrementar estoque sem transação de banco de dados com lock
  2. NUNCA confiar no preço enviado pelo frontend — sempre buscar do banco no checkout
  3. SEMPRE criar CheckoutSession como snapshot imutável antes de cobrar
  4. SEMPRE usar idempotency key no gateway de pagamento para evitar double charge
  5. Cancelamento só é possível em estados: pending, payment_failed, confirmed
  6. Pedido em shipped não pode ser cancelado — apenas devolvido
  7. Tax calculation com endereço final, não endereço salvo no perfil
  8. Imagens de produto: gerar thumbnails no upload (não on-the-fly)
  9. Variant sem estoque deve retornar available: false, não 404
  10. Carrinho abandonado (>1h sem checkout): disparar email automation
  11. Multi-currency: armazenar preço base em centavos + moeda base; converter na exibição
  12. Soft delete em produtos: nunca deletar produto com pedido associado

COMMON PITFALLS

❌ Race condition de estoque

-- ERRADO: dois usuários podem comprar o último item simultaneamente
SELECT quantity FROM product_variants WHERE id = $1;
-- (aqui outro usuário lê quantity = 1 também)
UPDATE product_variants SET quantity = quantity - 1 WHERE id = $1;

-- CORRETO: pessimistic lock
BEGIN;
SELECT quantity FROM product_variants WHERE id = $1 FOR UPDATE;
-- agora apenas esta transaction lê o valor
UPDATE product_variants SET quantity = quantity - 1 WHERE id = $1 AND quantity > 0;
COMMIT;

❌ Preço salvo no carrinho sem re-validação

// ERRADO: usar preço do carrinho/frontend diretamente
const total = cartItems.reduce((sum, item) => sum + item.price * item.qty, 0);

// CORRETO: buscar preço atual do banco
const variants = await db.productVariants.findMany({ where: { id: { in: cartItemIds } } });
const total = cartItems.reduce((sum, item) => {
  const variant = variants.find(v => v.id === item.variantId);
  return sum + variant.price * item.qty; // preço do banco
}, 0);

❌ Cancelar pedido já enviado

// ERRADO: permite cancelar qualquer pedido
await order.update({ status: 'canceled' });

// CORRETO: validar transição
const cancelableStates = ['pending', 'payment_failed', 'confirmed'];
if (!cancelableStates.includes(order.status)) {
  throw new BusinessError('ORDER_NOT_CANCELABLE', `Cannot cancel order in state: ${order.status}`);
}

QUALITY GATES

  • Estoque nunca fica negativo (constraint no DB + validação na aplicação)
  • Preço sempre re-validado no checkout a partir do banco
  • Lock pessimista implementado no decremento de estoque
  • Máquina de estados com transições validadas explicitamente
  • Carrinho anônimo faz merge correto ao autenticar
  • CheckoutSession é imutável após criação
  • Tax calculado com endereço final de entrega
  • Idempotency key usado em chamadas ao gateway de pagamento
  • Email disparado em cada mudança de estado relevante do pedido
  • Produtos soft-deleted mas visíveis em pedidos históricos

FORBIDDEN

  • Armazenar preço do produto apenas no carrinho sem re-validação
  • Decrementar estoque fora de uma transação de banco com lock
  • Permitir transições de estado de pedido sem validação (ex: de delivered para pending)
  • Deletar fisicamente produtos com histórico de pedidos
  • Calcular tax com endereço do perfil do usuário em vez do endereço de entrega do checkout
  • Pular a etapa de CheckoutSession e cobrar diretamente a partir dos dados do carrinho
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall