asaas-checkout/CLAUDE.md

CLAUDE.md — asaas-checkout (template)

Este arquivo define as regras de comportamento do Claude Code neste projeto.

O que é este projeto

asaas-checkout é um template white-label de checkout com ASAAS. Não é uma aplicação de produto específico — é uma base reutilizável.

Cada instância real (ex: vixcert, outra-empresa) é uma cópia/fork deste repo, parametrizada via variáveis de ambiente.

Estrutura

app/
  page.tsx               — homepage listando produtos
  comprar/page.tsx       — listagem de produtos
  comprar/[id]/page.tsx  — página de checkout do produto
  pedido/[id]/page.tsx   — acompanhamento de pedido
  api/
    checkout/route.ts    — cria pedido + pagamento ASAAS
    pedido/[id]/route.ts — polling de status (consulta ASAAS se PENDING)
    webhook/route.ts     — recebe notificações ASAAS
  admin/                 — dashboard admin
  login/page.tsx         — login simples via env vars

components/
  pedido-status.tsx      — cliente component com polling 5s
  product-buy-form.tsx   — formulário de compra
  site-header.tsx        — cabeçalho parametrizado
  dashboard-stats.tsx    — métricas do admin
  transaction-table.tsx  — tabela de pedidos com filtros
  pedido-detail-modal.tsx— modal de detalhes do pedido

lib/
  config.ts              — lê todas as env vars → appConfig
  auth-context.tsx       — autenticação admin via env vars
  supabase.ts            — cliente Supabase
  asaas.ts               — funções ASAAS (criar pagamento, buscar status)
  actions.ts             — server actions (getPedidos, etc.)

Variáveis de ambiente

Variável	Obrigatória	Descrição
NEXT_PUBLIC_APP_NAME	sim	Nome exibido na interface
NEXT_PUBLIC_APP_LOGO_URL	não	URL da logo (texto se vazio)
NEXT_PUBLIC_APP_PRIMARY_COLOR	não	Cor primária hex (default #1d4ed8)
NEXT_PUBLIC_AFTER_PAYMENT_REDIRECT	não	URL pós-pagamento (default /)
NEXT_PUBLIC_SUPPORT_EMAIL	não	Email de suporte
NEXT_PUBLIC_SUPPORT_WHATSAPP	não	WhatsApp de suporte (55119...)
NEXT_PUBLIC_ADMIN_USER	sim	Usuário do admin
NEXT_PUBLIC_ADMIN_PASSWORD	sim	Senha do admin
ASAAS_API_KEY	sim	Chave da API ASAAS
ASAAS_ENV	sim	sandbox ou production
NEXT_PUBLIC_SUPABASE_URL	sim	URL do projeto Supabase
NEXT_PUBLIC_SUPABASE_ANON_KEY	sim	Anon key Supabase
SUPABASE_SERVICE_ROLE_KEY	sim	Service role key Supabase
N8N_WEBHOOK_URL	não	Webhook pagamento confirmado
N8N_PIX_WEBHOOK_URL	não	Webhook PIX gerado

Ver .env.example para exemplo completo.

Como criar uma nova instância

# 1. Clonar o template
git clone git@git.oakia.com.br:admin/asaas-checkout.git meu-projeto
cd meu-projeto

# 2. Remover origin e apontar para novo repo
git remote remove origin
git remote add origin git@git.oakia.com.br:admin/meu-projeto.git

# 3. Rodar o setup interativo (gera .env.local e stack.yaml)
bash setup.sh

# 4. Instalar dependências e testar
npm install
npm run dev

# 5. Build e deploy
docker build -t meu-projeto:latest .
docker stack deploy -c stack.meu-projeto.yaml meu-projeto

Schema do banco (Supabase)

O template espera as seguintes tabelas (DDL em data/schema.sql se existir):

• clientes — nome, email, cpf_cnpj, telefone
• produtos — nome, descricao, valor_centavos, tipo, validade, midia, ativo
• pedidos — cliente_id, produto_id, status, valor_centavos, metodo_pagamento, asaas_payment_id, pix_copia_cola, pix_qrcode_url, asaas_invoice_url, paid_at

Fluxo de pagamento

1. Cliente preenche form → POST /api/checkout → cria pedido no Supabase + pagamento no ASAAS
2. Cliente é redirecionado para /pedido/[id]
3. Frontend faz polling em GET /api/pedido/[id] a cada 5s
4. Se status=PENDING, a API consulta ASAAS diretamente e atualiza o DB
5. ASAAS também dispara webhook para POST /api/webhook (registrar via ASAAS API)
6. Quando pago: exibe confirmação + botão para AFTER_PAYMENT_REDIRECT

Zonas de comportamento (herda do harness /root)

Verde

• Leitura de arquivos, logs, consultas
• Geração de specs e documentação

Amarelo (executa e avisa)

• Mudanças em componentes genéricos do template
• Atualização de dependências

Vermelho (nunca sem "confirmo, pode executar")

• Push para origin (afeta todas as instâncias futuras)
• Mudanças no schema SQL que quebram instâncias existentes
• Alteração nas variáveis obrigatórias (quebra instâncias sem a var)

Convenções

• Todo texto visível ao usuário deve vir de appConfig (nunca hardcoded)
• Referências a produto específico (ex: "certificado digital", "ICP-Brasil") são proibidas
• Componentes novos: genéricos, sem assumir domínio de negócio
• Testar sempre com ASAAS_ENV=sandbox antes de production