8000 GitHub - javabetatester/FyNanceCtrl · GitHub
[go: up one dir, main page]

Skip to content

About

No description, website, or topics provided.

Resources

Stars

49 stars

Watchers

3 watching

Forks

Repository files navigation

Fynance - Sistema de Gestão Financeira Pessoal

API RESTful para gestão financeira pessoal desenvolvida em Go com foco em segurança, escalabilidade e facilidade de uso. A aplicação permite aos usuários gerenciar suas finanças pessoais, incluindo transações, categorias, metas financeiras, investimentos e relatórios.

Índice

Funcionalidades

Autenticação e Autorização

  • Registro de novos usuários
  • Autenticação via JWT (JSON Web Tokens)
  • Validação de propriedade de recursos
  • Sistema de planos de usuário com controle de acesso

Gestão de Transações

  • Registro de receitas e despesas
  • Categorização de transações
  • Consulta e filtragem de transações
  • Atualização e exclusão de transações

Categorias de Transações

  • Criação de categorias personalizadas
  • Listagem de categorias
  • Atualização e exclusão de categorias

Metas Financeiras

  • Criação de metas financeiras
  • Acompanhamento de progresso
  • Atualização e exclusão de metas

Investimentos

  • Registro de investimentos
  • Controle de contribuições e saques
  • Cálculo de retorno sobre investimentos
  • Consulta de histórico de investimentos

Dashboard e Relatórios

  • Visão consolidada da situação financeira
  • Relatórios e análises financeiras

Saúde Financeira

  • Cálculo de score de saúde financeira
  • Análise de orçamentos, metas, reserva de emergência e dívidas
  • Recomendações personalizadas para melhoria financeira

Tecnologias

Core

  • Go 1.25+: Linguagem de programação principal
  • Gin Framework: Framework web para construção da API REST
  • GORM: ORM para interação com banco de dados PostgreSQL
  • PostgreSQL: Banco de dados relacional

Segurança e Autenticação

  • golang-jwt/jwt: Geração e validação de tokens JWT
  • golang.org/x/crypto: Criptografia bcrypt para senhas

Documentação

  • Swagger/OpenAPI: Documentação interativa da API
  • swaggo/swag: Geração automática de documentação Swagger

Utilidades

  • oklog/ulid/v2: Geração de identificadores únicos (ULID)

Arquitetura

O projeto segue os princípios de Clean Architecture e SOLID, com separação clara de responsabilidades:

Camadas

  • Domain Layer (internal/domain/): Contém as entidades de negócio, interfaces de repositórios e serviços, e regras de domínio

    • auth/: Autenticação e autorização
    • user/: Gestão de usuários
    • transaction/: Transações financeiras
    • goal/: Metas financeiras
    • investment/: Investimentos
    • dashboard/: Dashboard e análises
    • reports/: Relatórios financeiros
    • healthscore/: Cálculo de saúde financeira
    • budget/: Orçamentos
    • account/: Contas financeiras
    • category/: Categorias de transações
    • creditcard/: Cartões de crédito
    • recurring/: Transações recorrentes
  • Infrastructure Layer (internal/infrastructure/): Implementações concretas de repositórios e conexão com banco de dados

    • Conexão PostgreSQL via GORM
    • Implementação de repositórios para todas as entidades
    • Migrações automáticas de banco de dados
  • Middleware Layer (internal/middleware/): Componentes para processamento de requisições HTTP

    • Autenticação JWT
    • Validação de propriedade de recursos
    • Validação de planos de usuário
  • Routes Layer (internal/routes/): Handlers HTTP que conectam as requisições às regras de negócio

    • Handlers para autenticação
    • Handlers para transações
    • Handlers para categorias
    • Handlers para metas
    • Handlers para investimentos
    • Handlers para health score
    • Handlers para orçamentos
    • Handlers para contas
    • Handlers para cartões de crédito
    • Handlers para transações recorrentes
  • Contracts Layer (internal/contracts/): DTOs (Data Transfer Objects) e contratos de API

  • Utils Layer (internal/utils/): Utilitários e serviços compartilhados

Princípios Aplicados

  • Single Responsibility Principle (SRP): Cada camada e componente tem uma responsabilidade única
  • Dependency Inversion: Dependências apontam para abstrações (interfaces), não implementações
  • Open/Closed Principle: Extensível através de interfaces, fechado para modificação
  • DRY (Don't Repeat Yourself): Código reutilizável e modularizado
  • KISS (Keep It Simple, Stupid): Soluções simples e diretas

Requisitos

Para Execução com Docker (Recomendado)

Para Execução Manual

Software

Variáveis de Ambiente (Obrigatórias)

A aplicação não inicia se as credenciais mínimas não estiverem definidas. Configure antes de executar:

DB_HOST=localhost
DB_PORT=5432
DB_USER=<usuario_do_banco>
DB_PASSWORD=<senha_do_banco>
DB_NAME=fynance
DB_SSL_MODE=disable
DB_TIMEZONE=UTC
DB_MAX_OPEN_CONNS=25
DB_MAX_IDLE_CONNS=5
DB_CONN_MAX_LIFETIME=5m
JWT_SECRET_KEY=<chave-com-no-minimo-32-caracteres>
JWT_ISSUER=fynance_api
JWT_EXPIRES_IN=24h
APP_ENV=development
LOG_LEVEL=info
SERVER_PORT=8080
SERVER_READ_TIMEOUT=15s
SERVER_WRITE_TIMEOUT=15s
SERVER_IDLE_TIMEOUT=60s

Sugestão: crie um arquivo .env (não comite) e carregue com ferramentas como direnv ou dotenvx. Em produção, armazene segredos em um secret manager (AWS Secrets Manager, HashiCorp Vault ou Secret Manager da sua cloud).

Instalação

Opção 1: Execução com Docker (Recomendado)

A forma mais rápida de executar o projeto é usando Docker e Docker Compose. Esta abordagem não requer instalação manual do Go ou PostgreSQL.

Pré-requisitos

Passos

Setup Manual

  1. Clonar o Repositório
git clone https://github.com/seu-usuario/fynance.git
cd fynance
  1. Configurar Variáveis de Ambiente

Copie o arquivo de exemplo e ajuste as variáveis conforme necessário:

cp .env.example .env

IMPORTANTE: Edite o arquivo .env e altere pelo menos:

  • JWT_SECRET_KEY: Use uma chave forte com mínimo 32 caracteres (gere com openssl rand -base64 32)
  • DB_PASSWORD: Defina uma senha segura para o banco de dados
  1. Iniciar os Serviços
docker-compose up -d

Este comando irá:

  • Criar e iniciar o container do PostgreSQL
  • Criar e iniciar o container da API
  • Executar as migrações automaticamente
  • Expor a API na porta 8080
  1. Verificar Status dos Containers
docker-compose ps
  1. Acessar a Aplicação

Comandos Úteis Docker

# Ver logs da API
docker-compose logs -f api

# Ver logs do banco de dados
docker-compose logs -f db

# Parar os serviços
docker-compose down

# Parar e remover volumes (dados do banco)
docker-compose down -v

# Rebuild da API após mudanças no código
docker-compose up -d --build api

# Executar comandos dentro do container da API
docker-compose exec api sh

Opção 2: Instalação Manual

Se preferir executar localmente sem Docker:

1. Clonar o Repositório

git clone https://github.com/seu-usuario/fynance.git
cd fynance

2. Instalar Dependências

go mod download

3. Configurar Banco de Dados PostgreSQL

Certifique-se de que o PostgreSQL está instalado e rodando e que as variáveis DB_* apontam para o servidor correto. Não é necessário alterar código; toda a configuração passa por variáveis de ambiente.

4. Criar Banco de Dados (se necessário)

CREATE DATABASE fynance;

As migrações são executadas automaticamente na inicialização da aplicação.

Configuração

Configuração do Banco de Dados

A carga de configuração ocorre em config/config.go. Recomendações para produção:

  1. Armazene segredos em secret manager com rotação automatizada
  2. Ative SSL/TLS para conexões seguras (DB_SSL_MODE=require)
  3. Ajuste DB_MAX_OPEN_CONNS, DB_MAX_IDLE_CONNS e DB_CONN_MAX_LIFETIME conforme a carga
  4. Restringa privilégios do usuário do banco apenas ao schema utilizado

Migrações

As migrações são executadas automaticamente via GORM AutoMigrate na inicialização da aplicação para as seguintes entidades:

  • User
  • Goal
  • Transaction
  • Category
  • Investment
  • Account
  • Budget
  • CreditCard
  • RecurringTransaction

Execução

Modo Desenvolvimento

go run cmd/api/main.go

Build e Execução

go build -o bin/api cmd/api/main.go
./bin/api

Execução com Swagger

A documentação Swagger estará disponível em:

http://localhost:8080/swagger/index.html

A API estará disponível em:

http://localhost:8080/api

Documentação da API

A documentação completa da API está disponível via Swagger UI:

http://localhost:8080/swagger/index.html

Gerar Documentação Swagger

Para regenerar a documentação Swagger após alterações:

swag init -g cmd/api/main.go

Endpoints

Rotas Públicas

Autenticação

  • POST /api/auth/register - Registro de novo usuário

    • Body: { "email": "string", "password": "string", "name": "string" }
    • Response: { "message": "string" }
  • POST /api/auth/login - Autenticação de usuário

    • Body: { "email": "string", "password": "string" }
    • Response: { "token": "string" }

Rotas Privadas (Requerem Autenticação)

Transações

  • POST /api/transactions - Criar nova transação
  • GET /api/transactions - Listar transações do usuário
  • GET /api/transactions/:id - Obter transação específica
  • PATCH /api/transactions/:id - Atualizar transação
  • DELETE /api/transactions/:id - Excluir transação

Categorias

  • POST /api/categories - Criar nova categoria
  • GET /api/categories - Listar categorias do usuário
  • PATCH /api/categories/:id - Atualizar categoria
  • DELETE /api/categories/:id - Excluir categoria

Metas

  • POST /api/goals - Criar nova meta financeira
  • GET /api/goals - Listar metas do usuário
  • GET /api/goals/:id - Obter meta específica
  • PATCH /api/goals/:id - Atualizar meta
  • DELETE /api/goals/:id - Excluir meta

Investimentos

  • POST /api/investments - Criar novo investimento
  • GET /api/investments - Listar investimentos do usuário
  • GET /api/investments/:id - Obter investimento específico
  • POST /api/investments/:id/contribution - Realizar contribuição
  • POST /api/investments/:id/withdraw - Realizar saque
  • GET /api/investments/:id/return - Obter retorno do investimento
  • PATCH /api/investments/:id - Atualizar investimento
  • DELETE /api/investments/:id - Excluir investimento

Saúde Financeira

  • GET /api/health-score - Obter score de saúde financeira
    • Response: { "score": number, "status": "string", "label": "string", "color": "string", "budgetHealth": number, "goalsHealth": number, "savingsHealth": number, "recommendations": string[] }

Dashboard

  • GET /api/dashboard - Obter dados consolidados do dashboard

Autenticação

Todas as rotas privadas requerem autenticação via JWT. Para acessar essas rotas:

  1. Faça login via POST /api/auth/login com suas credenciais
  2. Receba o token JWT na resposta
  3. Inclua o token no header Authorization de todas as requisições subsequentes:
Authorization: Bearer <seu_token_jwt>

Exemplo de Requisição Autenticada

curl -X GET http://localhost:8080/api/transactions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Validade do Token

Os tokens JWT têm validade de 24 horas. Após expirar, é necessário fazer login novamente.

Segurança

Medidas Implementadas

  • Criptografia de Senhas: Senhas são armazenadas com hash bcrypt (cost >= 12)
  • JWT com Assinatura: Tokens JWT são assinados e validados
  • Validação de Propriedade: Middleware garante que usuários só acessem seus próprios recursos
  • Validação de Planos: Sistema de planos permite controle granular de acesso
  • Validação de Entrada: Validação de dados de entrada em todos os endpoints
  • Tratamento Centralizado de Erros: API responde usando códigos padronizados (AppError) e logs estruturados
  • HTTPS Recomendado: Para produção, utilize HTTPS para proteger dados em trânsito

Boas Práticas

  • Nunca exponha credenciais em logs ou mensagens de erro
  • Use variáveis de ambiente para configurações sensíveis
  • Implemente rate limiting em produção
  • Configure CORS adequadamente
  • Monitore tentativas de acesso não autorizadas

Tratamento de Erros

  • Todas as exceções são convertidas em AppError, com código, mensagem e status HTTP padronizados
  • Logs estruturados (zerolog) registram código, rota e causa raiz dos erros
  • Middlewares retornam mensagens genéricas para evitar vazamento de detalhes sensíveis
  • Validações de entrada retornam VALIDATION_ERROR com o campo impactado e descrição
  • Falhas de infraestrutura são encapsuladas como DATABASE_ERROR, mantendo contexto para observabilidade

Estrutura do Projeto

Fynance/
├── cmd/
│   └── api/
│       └── main.go                    # Ponto de entrada da aplicação
├── internal/
│   ├── contracts/                     # DTOs e contratos de API
│   │   ├── auth.go
│   │   ├── common.go
│   │   ├── goal.go
│   │   ├── investment.go
│   │   ├── transaction.go
│   │   ├── user.go
│   │   ├── healthscore.go
│   │   ├── budget.go
│   │   ├── account.go
│   │   └── ...
│   ├── domain/                        # Camada de domínio (regras de negócio)
│   │   ├── auth/                      # Autenticação e autorização
│   │   ├── dashboard/                 # Dashboard e análises
│   │   ├── goal/                      # Metas financeiras
│   │   ├── investment/                # Investimentos
│   │   ├── reports/                   # Relatórios
│   │   ├── transaction/               # Transações
│   │   ├── user/                      # Usuários
│   │   ├── healthscore/               # Saúde financeira
│   │   ├── budget/                    # Orçamentos
│   │   ├── account/                   # Contas
│   │   ├── category/                  # Categorias
│   │   ├── creditcard/                # Cartões de crédito
│   │   └── recurring/                 # Transações recorrentes
│   ├── infrastructure/                # Camada de infraestrutura
│   │   ├── db.go                      # Conexão com banco de dados
│   │   ├── goal_repository.go
│   │   ├── investment_repository.go
│   │   ├── transaction_category_repository.go
│   │   ├── transaction_repository.go
│   │   ├── user_repository.go
│   │   ├── budget_repository.go
│   │   ├── account_repository.go
│   │   └── ...
│   ├── middleware/                    # Middlewares HTTP
│   │   ├── auth.go                    # Middleware de autenticação
│   │   ├── jwt.go                     # Serviço JWT
│   │   ├── jwt_service.go
│   │   ├── plan_validator.go          # Validação de planos
│   │   ├── plan_limiter.go            # Limites de planos
│   │   ├── rate_limiter.go            # Rate limiting
│   │   └── cors.go                    # CORS
│   ├── routes/                        # Handlers HTTP
│   │   ├── authentication.go
│   │   ├── goal.go
│   │   ├── handler.go
│   │   ├── investment.go
│   │   ├── transaction_category.go
│   │   ├── transaction.go
│   │   ├── healthscore.go
│   │   ├── budget.go
│   │   ├── account.go
│   │   └── ...
│   └── pkg/                           # Utilitários e pacotes compartilhados
│       ├── pagination.go
│       ├── ulid_utils.go
│       └── query/                     # Query builder
├── docs/                              # Documentação Swagger
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── go.mod                             # Gerenciamento de dependências
├── go.sum
└── README.md                          # Este arquivo

Testes

Executar Testes

go test ./...

Executar Testes com Coverage

go test -cover ./...

Executar Testes com Coverage Detalhado

go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Benchmarks

go test -bench=. ./...

Contribuição

Contribuições são bem-vindas! Para contribuir:

  1. Fork o projeto
  2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
  3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
  4. Push para a branch (git push origin feature/AmazingFeature)
  5. Abra um Pull Request

Diretrizes de Contribuição

  • Siga os princípios SOLID, DRY, KISS
  • Mantenha o código limpo e autoexplicativo
  • Adicione testes para novas funcionalidades
  • Atualize a documentação Swagger quando necessário
  • Siga os padrões de código Go (gofmt, go vet)

Licença

Este projeto está sob Licença Proprietária - Proibida Monetização.

✅ PERMITIDO - QUALQUER USO:

  • ✅ Qualquer uso que NÃO envolva monetização
  • ✅ Estudo, aprendizado e pesquisa
  • ✅ Incorporação em outros projetos (open source, privado, pessoal, etc.)
  • ✅ Criação de obras derivadas
  • ✅ Modificação, distribuição e compartilhamento
  • ✅ Fork e contribuições para este projeto
  • ✅ Uso em projetos pessoais, comerciais (não monetizados), experimentais
  • ✅ Uso educacional e acadêmico
  • ✅ Copiar código, funções ou módulos para outros projetos
  • ✅ Usar padrões arquiteturais em outros projetos
  • ✅ Criar aplicações baseadas neste código
  • ✅ Uso interno em empresas (desde que não vendido/licenciado)

Resumindo: PODE USAR EM QUALQUER COISA, MENOS PARA MONETIZAR!

❌ ESTRITAMENTE PROIBIDO - APENAS MONETIZAÇÃO:

  • ❌ Qualquer forma de monetização ou comercialização
  • ❌ Venda do código ou obras derivadas
  • ❌ Licenciamento do código por taxa
  • ❌ Uso em produtos ou serviços comerciais onde há cobrança
  • ❌ Uso em Software-as-a-Service (SaaS) com cobrança
  • ❌ Geração de receita através de publicidade relacionada ao código
  • ❌ Cobrança de taxas, assinaturas ou qualquer forma de pagamento
  • ❌ Qualquer método de obter ganho financeiro do código

Para mais informações sobre os termos de uso, consulte o arquivo LICENSE.

⚠️ AVISO LEGAL CRÍTICO:

A única restrição é: NÃO MONETIZE!

Você pode usar este código para QUALQUER OUTRO PROPÓSITO:

  • ✅ Em outros projetos
  • ✅ Para estudo
  • ✅ Para criar aplicações
  • ✅ Para compartilhar
  • ✅ Para qualquer coisa que NÃO envolva ganho financeiro

MAS: Qualquer tentativa de MONETIZAR este código constitui VIOLAÇÃO DE DIREITOS AUTORAIS e pode resultar em AÇÃO JUDICIAL IMEDIATA, incluindo:

  • Processo civil por violação de direitos autorais
  • Indenização por danos materiais e morais
  • Danos estatutários (até $150.000 por obra nos EUA)
  • Perdas e danos (incluindo todos os lucros obtidos com uso não autorizado)
  • Custas processuais e honorários advocatícios
  • Medidas cautelares para cessação imediata do uso não autorizado

Resumindo:

  • ✅ Qualquer uso = PERMITIDO (desde que não monetize)
  • ❌ Monetização = PROCESSO LEGAL ⚠️

Desenvolvido por Bernardo

Para mais informações, consulte a documentação Swagger em http://localhost:8080/swagger/index.html após iniciar a aplicação.

About

No description, website, or topics provided.

Resources

Stars

49 stars

Watchers

3 watching

Forks

Releases

Packages

Contributors

Languages

0