# 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

```bash
# 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