🏦 ON WAY FINANCIAL
Copiloto financeiro familiar com bot de WhatsApp, IA, módulos especiais (Obra, Viagem, Carro Novo, Presente, Educação) e suporte a módulos personalizáveis.
Stack: Next.js 14 (App Router) · TypeScript · Tailwind + shadcn/ui · Supabase (Postgres + RLS + Auth + Storage) · WhatsApp Cloud API · Anthropic Claude · Vercel · PWA.
🚀 Setup local
Pré-requisitos
- Node.js 20+
- pnpm 9+ (
npm i -g pnpm)
- Conta Supabase (free)
- Conta Vercel (free)
- App WhatsApp Business no Meta for Developers
- API Key do Anthropic (Claude)
Passo a passo
# 1) instalar deps
pnpm install
# 2) configurar variáveis
cp .env.local.example .env.local
# preencha conforme seção "Variáveis de ambiente" abaixo
# 3) Supabase
supabase login
supabase link --project-ref <project-ref>
supabase db push # aplica migrations
pnpm db:types # gera src/types/database.ts
# 4) rodar
pnpm dev # http://localhost:3000
Testes & qualidade
pnpm typecheck # tsc --noEmit
pnpm lint
pnpm test # vitest unit
pnpm test:e2e # playwright e2e
pnpm format
🔐 Variáveis de ambiente
Veja .env.local.example. Todas validadas com Zod em src/lib/env.ts — se faltar alguma, o boot falha.
| Variável | Descrição |
|---|
NEXT_PUBLIC_SUPABASE_URL | URL do projeto Supabase |
NEXT_PUBLIC_SUPABASE_ANON_KEY | anon key (público) |
SUPABASE_SERVICE_ROLE_KEY | service role (server-only, ⚠️ NUNCA expor no client) |
NEXT_PUBLIC_APP_URL | URL pública do app |
WHATSAPP_PHONE_NUMBER_ID | Phone Number ID (Meta) |
WHATSAPP_BUSINESS_ACCOUNT_ID | WABA ID |
WHATSAPP_ACCESS_TOKEN | Token permanente (System User) |
WHATSAPP_VERIFY_TOKEN | string aleatória para handshake do webhook |
WHATSAPP_APP_SECRET | App Secret (para validar HMAC) |
ANTHROPIC_API_KEY | sk-ant-... |
ANTHROPIC_MODEL | default claude-haiku-4-5-20251001 |
CRON_SECRET | string aleatória para autenticar o Vercel Cron |
🗄️ Banco de dados
As migrations vivem em supabase/migrations:
0001_init.sql — households, members, invites, categorias, métodos, transações, alertas, audit log, rate limit.0002_rls.sql — Row Level Security em todas as tabelas + helpers is_member_of, has_role_in, module_household.0003_modules.sql — modules + tabelas por kind (obra_phases/workers/gallery/messages, travel_items, car_options, gift_items, education_items, custom_items).0004_seed.sql — trigger que ao criar household popula categorias padrão, métodos padrão e adiciona o criador como owner. Cria buckets de storage receipts e obra-gallery com policies por household.
Para zerar localmente: supabase db reset.
📲 Configurando o webhook do WhatsApp
- No Meta for Developers, vá em WhatsApp → Configuration → Callback URL.
- Cole
https://<seu-dominio>/api/whatsapp/webhook.
- Verify Token = valor de
WHATSAPP_VERIFY_TOKEN.
- Inscreva o webhook em
messages.
- Copie o App Secret da seção Basic Settings →
WHATSAPP_APP_SECRET.
Validação do payload usa HMAC SHA-256 (header x-hub-signature-256) com crypto.timingSafeEqual.
🤖 Bot — comandos e IA híbrida
Comandos /... (parser determinístico, grátis):
| Comando | Descrição |
|---|
/despesa <valor> <desc> [#cat] [@método] [data] | Cria despesa |
/receita <valor> <desc> [#cat] | Cria receita |
/saldo | Resumo do mês |
/categorias | Lista categorias |
/metodos | Lista métodos |
/obra <valor> <desc> | Atalho para obra ativa |
/viagem <valor> <desc> | Atalho para viagem ativa |
/cancelar | Desfaz última transação (5 min) |
/ajuda | Menu |
Texto livre vai para o parseFreeText (Claude haiku-4.5) que devolve JSON estruturado validado por Zod (src/lib/ai/parser.ts).
Mensagens de baixa confiança (< 0.7) viram pergunta no WhatsApp pedindo confirmação SIM / NÃO (estado em whatsapp_sessions.state.pending).
Rate limit: 60 msgs/min por telefone (tabela whatsapp_rate_limit).
⏰ Cron de alertas
Configurado em vercel.json:
{ "path": "/api/cron/alerts?secret=$CRON_SECRET", "schedule": "0 11 * * *" }
Roda diariamente às 08:00 BRT (11:00 UTC). Avalia budget_exceeded, invoice_closing, goal_progress, recurring_due, custom. Alertas large_expense disparam em tempo real dentro do handleIncoming quando uma despesa é registrada.
🧱 Módulos
| Kind | Rota | Funcionalidades |
|---|
obra | /modules/obra/[id] | Fases (kanban), Equipe (WhatsApp), Galeria (Storage), Despesas, % orçamento |
travel | /modules/travel/[id] | Itens (voo/hotel/transporte/comida/tour), planejado vs realizado |
car | /modules/car/[id] | Comparativo de modelos, simulador PRICE, "já poupei" |
gift | /modules/gift/[id] | Lista de presentes, ocasiões, marcado como comprado |
education | /modules/education/[id] | Cursos, mensalidades, projeção anual |
custom | /modules/custom/[id] | Campos definidos pelo usuário (texto/número/data) |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
