FINANCAAAS - Backend em Java Spring Boot

Sistema de gestão financeira pessoal (SaaS) que permite aos usuários gerenciar transações (receitas e despesas), configurar orçamentos por categoria, visualizar relatórios de gastos e classificar transações por categorias.

🚀 Stack Recomendado

• Java 17+
• Spring Boot 3.5.4
• Spring Data JPA
• Spring Security com JWT
• H2 Database (desenvolvimento) ou PostgreSQL (produção)
• Lombok
• MapStruct (DTOs)
• Spring Doc OpenAPI (Swagger/OpenAPI 3.0)

📋 Pré-requisitos

• Java 17+ instalado
• Maven 3.8+
• PostgreSQL 12+ (opcional, para produção)

📦 Instalação e Setup

1. Clonar ou preparar o projeto

cd financaaas-backend

2. Compilar o projeto

./mvnw clean compile

3. Executar o projeto

./mvnw spring-boot:run

Ou executar diretamente:

./mvnw clean build
java -jar target/api-0.0.1-SNAPSHOT.jar

A aplicação estará disponível em: http://localhost:8080

📚 Documentação da API

Após iniciar a aplicação, acesse a documentação interativa da API em:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/v3/api-docs
• H2 Console (dev): http://localhost:8080/h2-console

🏗️ Estrutura do Projeto

src/main/java/br/com/financas/api/
├── config/              # Configurações (Security, WebConfig, OpenAPI)
├── controller/          # Controllers (REST endpoints)
├── dto/                 # Data Transfer Objects
├── exception/           # Exceções customizadas e handlers
├── model/               # Entidades JPA
├── repository/          # Interfaces de repositório JPA
├── security/            # Componentes de segurança (JWT)
└── service/             # Lógica de negócio

🔐 Autenticação

A API utiliza JWT (JSON Web Tokens) para autenticação.

Fluxo de Autenticação

1. Registrar usuário: POST /api/auth/register
2. Fazer login: POST /api/auth/login
3. Receber tokens: Access Token + Refresh Token
4. Usar Access Token: Incluir no header Authorization: Bearer <token>
5. Renovar token: POST /api/auth/refresh

Exemplo de Requisição

# Registrar
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@example.com",
    "password": "senha123456",
    "name": "Nome Usuario"
  }'

# Login
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@example.com",
    "password": "senha123456"
  }'

# Usar o token
curl -X GET http://localhost:8080/api/transactions \
  -H "Authorization: Bearer <seu_access_token>"

📋 Endpoints da API

Autenticação

Método	Endpoint	Descrição
POST	/api/auth/register	Registrar novo usuário
POST	/api/auth/login	Login com email/password
POST	/api/auth/refresh	Renovar access token
POST	/api/auth/logout	Logout (remover token no cliente)

Transações

Método	Endpoint	Descrição
GET	/api/transactions	Listar transações (paginado, com filtros)
GET	/api/transactions/{id}	Obter transação específica
POST	/api/transactions	Criar nova transação
PUT	/api/transactions/{id}	Atualizar transação
DELETE	/api/transactions/{id}	Deletar transação
GET	/api/transactions/stats/monthly	Estatísticas do mês

Filtros disponíveis:

• type (INCOME/EXPENSE)
• category (nome da categoria)
• startDate (data inicial)
• endDate (data final)
• minAmount (valor mínimo)
• maxAmount (valor máximo)
• page (página, padrão 0)
• size (itens por página, padrão 10)
• sort (ordenação, padrão "date,desc")

Orçamentos

Método	Endpoint	Descrição
GET	/api/budgets	Listar orçamentos do usuário
GET	/api/budgets/{id}	Obter orçamento específico
POST	/api/budgets	Criar novo orçamento
PUT	/api/budgets/{id}	Atualizar orçamento
DELETE	/api/budgets/{id}	Deletar orçamento
GET	/api/budgets/status/{category}	Status do orçamento

Categorias

Método	Endpoint	Descrição
GET	/api/categories	Listar categorias
GET	/api/categories/{id}	Obter categoria específica
POST	/api/categories	Criar categoria personalizada
PUT	/api/categories/{id}	Atualizar categoria
DELETE	/api/categories/{id}	Deletar categoria

Filtro: type (INCOME/EXPENSE)

📊 Modelos de Dados

User

{
  "id": "uuid",
  "email": "user@example.com",
  "password": "hashed_password",
  "name": "Nome do Usuário",
  "createdAt": "2026-02-20T10:30:00",
  "updatedAt": "2026-02-20T10:30:00"
}

Transaction

{
  "id": "uuid",
  "description": "Descrição da transação",
  "amount": 123.45,
  "type": "INCOME",
  "category": "Salário",
  "date": "2026-02-20T10:30:00",
  "recurring": false,
  "createdAt": "2026-02-20T10:30:00",
  "updatedAt": "2026-02-20T10:30:00"
}

Budget

{
  "id": "uuid",
  "category": "Alimentação",
  "limit": 1000.00,
  "spent": 450.50,
  "percentageUsed": 45.05,
  "status": "WITHIN_BUDGET",
  "createdAt": "2026-02-20T10:30:00"
}

Category

{
  "id": "uuid",
  "name": "Alimentação",
  "type": "EXPENSE",
  "color": "#FF5733",
  "createdAt": "2026-02-20T10:30:00"
}

🔧 Configuração

Desenvolvimento (application.properties padrão)

• Banco: H2 em memória
• URL: jdbc:h2:mem:testdb
• Console H2: http://localhost:8080/h2-console

Produção (PostgreSQL)

Criar arquivo application-prod.properties:

# Database
spring.datasource.url=jdbc:postgresql://localhost:5432/financaaas
spring.datasource.driverClassName=org.postgresql.Driver
spring.datasource.username=financaaas_user
spring.datasource.password=seu_password_seguro

# JPA
spring.jpa.database-platform=org.hibernate.dialect.PostgreSQLDialect
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

# JWT
api.security.token.secret=sua_chave_secreta_super_segura_minimo_32_caracteres
api.security.token.expiration=86400000
api.security.token.refresh-expiration=604800000

# Logging
logging.level.root=WARN
logging.level.br.com.financas.api=INFO

Executar em produção:

./mvnw spring-boot:run -Dspring-boot.run.arguments="--spring.profiles.active=prod"

🛡️ Segurança

Implementado

• ✅ Hash de senha com BCrypt
• ✅ JWT com expiração configurável
• ✅ CORS habilitado para múltiplas origens
• ✅ Validação de entrada com Bean Validation
• ✅ Tratamento de exceções centralizado
• ✅ Autorização por usuário (acesso aos dados próprios)
• ✅ Spring Security configurado

Recomendações para Produção

1. HTTPS: Use certificados SSL/TLS
2. CORS: Restrinja aos domínios conhecidos
3. Rate Limiting: Implemente limite de requisições
4. Logging de segurança: Registre acessos não autorizados
5. CSRF Protection: Para endpoints que usam formulários
6. SQL Injection: Use sempre prepared statements (JPA faz isso por padrão)
7. Variáveis de ambiente: Nunca commit secrets no código

📝 Validações Implementadas

• ✅ Amount >= 0
• ✅ Description não vazio
• ✅ Type deve ser INCOME ou EXPENSE
• ✅ Date não pode ser no futuro
• ✅ Email formato válido
• ✅ Senha mínimo 8 caracteres
• ✅ Usuário só acessa seus próprios dados
• ✅ Categoria única por usuário
• ✅ Orçamento único por usuário e categoria

🗄️ Índices de Banco de Dados

Automaticamente criados nas entidades:

CREATE INDEX idx_user_id ON transactions(user_id);
CREATE INDEX idx_date ON transactions(date);
CREATE INDEX idx_category ON transactions(category);
CREATE INDEX idx_budget_user_id ON budgets(user_id);
CREATE INDEX idx_budget_category ON budgets(category);
CREATE INDEX idx_category_user_id ON categories(user_id);
CREATE UNIQUE INDEX idx_category_name_user ON categories(user_id, name);

🧪 Testando a API

Exemplo: Fluxo Completo

# 1. Registrar usuário
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao@example.com",
    "password": "senha123456",
    "name": "João Silva"
  }'
# Response: { "accessToken": "...", "refreshToken": "...", ... }

# 2. Copiar accessToken e usar nas próximas requisições
TOKEN="seu_token_aqui"

# 3. Criar categoria
curl -X POST http://localhost:8080/api/categories \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "Alimentação",
    "type": "EXPENSE",
    "color": "#FF5733"
  }'

# 4. Criar transação
curl -X POST http://localhost:8080/api/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "description": "Compra no supermercado",
    "amount": 250.50,
    "type": "EXPENSE",
    "category": "Alimentação",
    "date": "2026-02-20T15:30:00",
    "recurring": false
  }'

# 5. Criar orçamento
curl -X POST http://localhost:8080/api/budgets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "category": "Alimentação",
    "limit": 1000.00
  }'

# 6. Listar transações
curl -X GET 'http://localhost:8080/api/transactions' \
  -H "Authorization: Bearer $TOKEN"

# 7. Obter estatísticas do mês
curl -X GET 'http://localhost:8080/api/transactions/stats/monthly?month=2026-02' \
  -H "Authorization: Bearer $TOKEN"

🐛 Troubleshooting

Erro: JAVA_HOME não definido

# Windows
set JAVA_HOME=C:\Program Files\Java\jdk-17

# Linux/Mac
export JAVA_HOME=/usr/libexec/java_home -v 17

Erro: Porta 8080 em uso

./mvnw spring-boot:run -Dspring-boot.run.arguments="--server.port=9090"

Erro de Validação JWT

Verifique se:

1. O token está no formato correto: Bearer <token>
2. O token não expirou
3. A secret key está correta

📈 Próximos Passos e Melhorias

• Implementar refresh token rotation
• Adicionar two-factor authentication (2FA)
• Implementar webhooks para eventos
• Adicionar suporte a múltiplas moedas
• Implementar análise preditiva de gastos
• Adicionar suporte a importação de extratos bancários
• Criar cache de categorias (Redis)
• Implementar soft deletes nas entidades
• Adicionar testes unitários e de integração
• Implementar documentação OpenAPI com exemplos
• Adicionar metrics com Micrometer/Prometheus

📞 Suporte

Para dúvidas ou problemas, consulte a documentação do Spring Boot ou crie uma issue no repositório.

📄 Licença

Apache License 2.0

---

Desenvolvido com ❤️ usando Spring Boot