feat: initial commit — asaas-checkout template white-label
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>
This commit is contained in:
127
CLAUDE.md
Normal file
127
CLAUDE.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user