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