Felipe Carvalho
038ce3f556
Template genérico de checkout com ASAAS, parametrizado via env vars. Inclui fluxo completo: checkout → pedido → polling → webhook → admin. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
128 lines
4.8 KiB
Markdown
128 lines
4.8 KiB
Markdown
# 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
|