FinControl

Sistema de controle financeiro pessoal com backend API e frontend web.

Funcionalidades

• Transações com parcelamento automático (6 tipos: despesa cartão, conta avulsa, conta recorrente, conta recorrente limitada, receita fixa, receita variável)
• Cartões de crédito com faturas mensais, fechamento, pagamento parcial/total e transferência de crédito
• Receitas e despesas recorrentes com dia fixo ou dia útil do mês
• Caixinhas de economia com metas e controle de sobra mensal automático
• Dashboard com resumo mensal, faturas, receitas previstas/recebidas e gastos por categoria
• WhatsApp para registrar transações, consultar saldo, faturas e parcelas via comandos de texto (integração com Evolution API)
• API Keys para automação via endpoints REST
• Segurança: valores financeiros criptografados (AES-256-GCM), senhas com bcrypt, JWT, rate limiting, Helmet.js

Tech Stack

Backend: Node.js, Express 4, TypeScript 5, PostgreSQL 16 (Docker)

Frontend: Next.js 16, React 19, TypeScript 5, Tailwind CSS 3

Como rodar

1. Clonar e configurar

git clone <repo-url>
cd fincontrol

# Backend
cp backend/.env.example backend/.env
# Edite backend/.env com suas credenciais (DB, JWT_SECRET, ENCRYPTION_KEY)

# Frontend
cp frontend/.env.example frontend/.env.local
# Edite se necessário (padrão: http://localhost:5000/api)

2. Subir o banco

docker compose up -d

3. Backend

cd backend
npm install
npm run dev    # http://localhost:5000

4. Frontend

cd frontend
npm install
npm run dev    # http://localhost:3001

5. Primeiro acesso

Acesse http://localhost:3001, crie uma conta e pronto.

Comandos WhatsApp

A integração com WhatsApp usa a Evolution API. Após vincular seu número na página /whatsapp, você pode usar:

Comando	Exemplo	Descrição
#cartao	#cartao 59.90 iFood 3x @nubank	Despesa no cartão (parcelas e alias opcionais)
#gasto	#gasto 30 Farmácia	Despesa avulsa
#receita	#receita 5000 Salário	Receita fixa
#extra	#extra 200 Freelance	Receita variável
#recorrente	#recorrente 5000 Salário 5	Receita recorrente (dia do mês)
#assinatura	#assinatura 44.90 Netflix @nubank	Assinatura no cartão
#saldo	#saldo	Saldo do mês atual
#fatura	#fatura	Faturas dos cartões
#cartoes	#cartoes	Lista cartões cadastrados
#parcelas	#parcelas	Parcelamentos ativos
#caixinhas	#caixinhas	Caixinhas de economia
#adiantar	#adiantar 42 1,2,3	Adiantar parcelas por código
#ajuda	#ajuda	Lista de comandos

API

Todos os endpoints exigem autenticação via Authorization: Bearer <token> ou X-API-Key: <chave>.

Recurso	Endpoints
Auth	POST /api/auth/register, POST /api/auth/login, GET /api/auth/me
API Keys	POST /api/api-keys, GET /api/api-keys, DELETE /api/api-keys/:id
Transações	POST /api/transactions, GET /api/transactions, GET /api/transactions/month/:m/:y, PUT /api/transactions/:id, DELETE /api/transactions/:id
Cartões	POST /api/cards, GET /api/cards, PUT /api/cards/:id, DELETE /api/cards/:id
Faturas	GET /api/invoices, GET /api/invoices/card/:id/current, POST /api/invoices/:id/close, POST /api/invoices/:id/pay
Categorias	POST /api/categories, GET /api/categories, PUT /api/categories/:id, DELETE /api/categories/:id
Contas	POST /api/accounts, GET /api/accounts, PUT /api/accounts/:id, DELETE /api/accounts/:id
Dashboard	GET /api/dashboard
Receitas Recorrentes	POST /api/recurring-incomes, GET /api/recurring-incomes, PUT /api/recurring-incomes/:id, DELETE /api/recurring-incomes/:id
Despesas Recorrentes	POST /api/recurring-expenses/card-subscription, GET /api/recurring-expenses, DELETE /api/recurring-expenses/:id
Caixinhas	POST /api/savings, GET /api/savings, POST /api/savings/movements, POST /api/savings/transfer
WhatsApp	POST /api/whatsapp/send-code, POST /api/whatsapp/verify-code, DELETE /api/whatsapp/unlink

Banco de Dados

PostgreSQL com 12 tabelas. Credenciais configuradas via variáveis de ambiente (ver backend/.env.example).

users, api_keys, categories, bank_accounts, credit_cards,
transactions, card_invoices, invoice_payments,
recurring_incomes, recurring_expenses, savings_boxes, savings_movements

Estrutura

backend/
  src/
    config/          # Database, JWT
    middleware/       # Auth, error handler, rate limiter
    models/          # Queries SQL
    services/        # Lógica de negócio
    controllers/     # Request handlers
    routes/          # Rotas da API
  database/
    schema.sql       # Schema completo
    migrations/      # Migrações incrementais

frontend/
  src/
    app/             # Pages (Next.js App Router)
    components/      # Componentes compartilhados
    lib/             # API client e utilitários

Licença

MIT