API REST completa para controle financeiro pessoal: autenticação JWT, orçamentos por categoria, contas recorrentes, parcelamento no cartão, um assistente financeiro baseado em regras e 119 testes automatizados.
🚀 Acesse: https://financeiro-lk6d.onrender.com
⚠️ A rota raiz retorna 403 por segurança — use os endpoints abaixo (/auth,/gastos, etc.) para testar. ⏳ Hospedado no tier gratuito do Render: após ~15 min sem uso o servidor "dorme" e o primeiro request pode levar até 2 min pra responder (cold start).
Quer ver os dados sem criar conta? POST /auth/demo devolve um token válido direto, sem senha, para uma conta compartilhada de demonstração (somente leitura — ver seção Modo Demo abaixo). O mesmo fluxo tem um botão pronto no front-end.
O Meu Controle Financeiro é o backend de uma aplicação full stack de controle financeiro pessoal: gastos, salários, metas de orçamento, contas recorrentes e um assistente que avisa quando algo foge do planejado.
Construído com Java e Spring Boot, seguindo arquitetura em camadas com DTOs de entrada/saída, exceptions centralizadas, migrações de banco versionadas com Flyway e cobertura de testes (unitários + integração). Hospedado em produção no Render, com banco TiDB Serverless (compatível com MySQL).
- 🔐 Autenticação JWT completa — cadastro, login, recuperação de senha por e-mail (código com expiração de 15 min), política de senha forte (8+ caracteres, maiúscula, número) e revogação automática de token ao trocar a senha
- 🎭 Modo demo —
POST /auth/demolibera uma conta compartilhada com dados de exemplo realistas, sem senha e sem cadastro; qualquer escrita nessa conta é bloqueada no servidor (423 Locked), não só na interface - 💰 Gastos — CRUD completo com categoria fixa (enum), forma de pagamento e parcelamento no cartão de crédito (divide o valor automaticamente, sem perder centavo no arredondamento)
- 💼 Salários — CRUD com valor, comissão e adicional, filtrável por mês
- 🎯 Metas de orçamento — limite mensal por categoria, com cálculo automático de consumo e status (dentro do limite / atenção / estourado)
- 🔁 Contas fixas recorrentes — gera o gasto do mês automaticamente, status (pago / vencendo / atrasado / pendente), pausar/reativar sem perder o histórico, lembrete por e-mail opcional
- 🤖 Assistente financeiro — motor de regras (não depende de LLM) que cruza orçamentos, ritmo de gastos, variação por categoria e dicas educacionais em insights priorizados por severidade
- 📈 Evolução mensal — série histórica de entradas, saídas e saldo
- 📊 Resumo e relatório — saldo do mês, gasto por categoria, transações recentes
- 🛡️ Segurança em produção — rate limiting no login/recuperação, headers HSTS/CSP/X-Frame-Options, proteção contra IDOR (todo endpoint filtra por dono do recurso), senha com BCrypt
- 🗄️ 13 migrações versionadas com Flyway (schema evoluído incrementalmente, sem
ddl-auto=update) - ✅ 119 testes automatizados — JUnit 5 + Mockito nos services, testes de integração ponta a ponta com MockMvc
POST /auth/registrar→ Cadastro de usuárioPOST /auth/login→ Login e geração de token JWTPOST /auth/demo→ Token da conta demo, sem senhaPOST /auth/recuperar-senha→ Envia código de recuperação por e-mailPOST /auth/redefinir-senha→ Troca a senha com o código recebido
GET /usuario/me→ Dados do usuário logado (nome, e-mail, se é conta demo)PUT /usuario/perfil→ Atualiza o nome
POST /gastos→ Criar gasto (parcelado ou não)GET /gastos/filtrar?mes=&ano=&categoria=→ Listar com filtrosPUT /gastos/{id}→ EditarDELETE /gastos/{id}→ Remover (bloqueado se for parcela avulsa)DELETE /gastos/{id}/parcelamento→ Remove a compra parcelada inteiraPATCH /gastos/{id}/pagar→ Marca uma conta fixa gerada como pagaGET /gastos/resumo·/relatorio·/categorias·/parcelamentos·/evolucao?meses=N
POST /salario·GET /salario/filtrar?mes=&ano=·PUT /salario/{id}·DELETE /salario/{id}
POST /orcamentos→ Cria ou atualiza o limite da categoria (upsert)GET /orcamentos→ Lista com consumo do mês correnteDELETE /orcamentos/{id}
POST /gastos-fixos·GET /gastos-fixos·PUT /gastos-fixos/{id}·DELETE /gastos-fixos/{id}PATCH /gastos-fixos/{id}/pausar·/reativarGET /gastos-fixos/pendentes-alerta
GET /assistente/insights→ Top 5 insights do mês, por severidade
./mvnw test119 testes: services isolados com Mockito, e um conjunto de integração (IntegracaoEndpointTest) que sobe o contexto Spring completo (H2 + Security + JWT) para validar autenticação, autorização e IDOR ponta a ponta.
src/main/java/com/claudio/financeiro
├── controller # Endpoints da API (requisições HTTP)
├── service # Regras de negócio
├── repository # Acesso ao banco de dados (Spring Data JPA)
├── model # Entidades JPA e enums de domínio
├── dto # Objetos de entrada/saída — controllers nunca expõem entidade direto
├── exception # GlobalExceptionHandler — erros padronizados em {"erro": "..."}
└── config # Segurança (JWT, Spring Security), rate limiting, seed do modo demo
src/main/resources/db/migration # Migrações Flyway (V2 a V13)
Camadas clássicas (Controller → Service → Repository), com alguns pontos que valem destacar:
- DTOs de entrada e saída em todo endpoint novo — nenhuma entidade JPA trafega direto no
@RequestBody/@ResponseBodydos recursos principais - Services decompostos por responsabilidade:
GastoServicefoi quebrado emRelatorioService,EvolucaoServiceeCalculoFinanceiroUtilquando cresceu demais, em vez de virar um God Class GlobalExceptionHandlercentraliza erros de validação, ownership (403/404) e JSON inválido num formato único- Assistente financeiro atrás de uma interface (
GeradorDeInsight) — hoje é um motor de regras determinístico, mas o design já comporta uma implementação com LLM no futuro sem tocar no controller - Valores monetários em
BigDecimal, nuncaDouble— evita erro de arredondamento em soma/parcelamento - Migrações Flyway incrementais, com estratégia expand-and-contract nas mudanças que trocam o tipo de uma coluna existente
- Java 17
- MySQL rodando localmente (ou ajuste
application-dev.propertiespara outro banco)
# Clone o repositório
git clone https://github.com/claudiondev/financeiro
cd financeiro
# Configure as variáveis de ambiente
cp .env.example .env
# Preencha DB_USERNAME, DB_PASSWORD, JWT_SECRET (32+ caracteres) e, se quiser
# testar recuperação de senha/lembretes, MAIL_USERNAME/MAIL_PASSWORD
# Rode com o profile de desenvolvimento
./mvnw spring-boot:run -Dspring-boot.run.profiles=devA API sobe em http://localhost:8080. No primeiro boot, o Flyway aplica as migrações e uma conta demo com dados de exemplo é criada automaticamente (demo@meufinanceiro.app, sem senha — use POST /auth/demo).
| Tecnologia | Descrição |
|---|---|
| Java 17 | Linguagem principal do projeto |
| Spring Boot 3.4.3 | Framework para construção da API |
| Spring Security | Autenticação stateless via JWT, headers de segurança |
| JJWT 0.12.6 | Geração e validação de tokens JWT |
| Spring Data JPA | Comunicação com banco de dados |
| Flyway | Versionamento e migração de schema |
| MySQL / TiDB Serverless | Banco relacional (local: MySQL · produção: TiDB) |
| Lombok | Redução de boilerplate nos DTOs |
| JavaMailSender | Recuperação de senha e lembretes de conta fixa |
| JUnit 5 + Mockito | Testes unitários e de integração |
| Render | Deploy da aplicação |
Claudio Nascimento 🔗 https://github.com/claudiondev