Controle de Gastos Familiares (API)

Esta é a API do Sistema de Controle de Gastos Residenciais. Ela é responsável por armazenar os dados, aplicar as regras do sistema e fornecer as informações para o painel da aplicação.

Este projeto é o back-end da aplicação. O front-end (React + TypeScript) que consome esta API pode ser encontrado em:

Front-end: https://github.com/herminio-rocha/expense-control-frontend.git

---

O que essa API faz

A API permite:

• cadastrar pessoas da casa
• criar categorias para organizar o dinheiro
• registrar receitas e despesas
• gerar relatórios consolidados

Toda a lógica de validação fica aqui na API para garantir que os dados sempre estejam corretos, independentemente do cliente que estiver consumindo os endpoints (web, mobile, etc).

---

Tecnologias e Padrões Aplicados

Este projeto foi desenvolvido utilizando:

• .NET 9
• ASP.NET Core Web API
• Entity Framework Core
• SQLite
• Repository Pattern
• Injeção de Dependências
• JWT Authentication
• BCrypt para criptografia de senha
• Swagger para documentação da API com integração JWT
• Serilog (Logs Estruturados)
• FluentValidation
• AutoMapper
• Global Exceptions Middleware
• Manipulação de Variáveis de Ambiente (.env via DotNetEnv)
• Versionamento de API (URL)

---

Estrutura do projeto

O projeto foi separado em camadas para manter o código organizado e fácil de manter.

Controllers

Recebem as requisições HTTP e retornam as respostas. Não possuem regras de negócio.

Services

Aqui ficam todas as regras do sistema. Exemplos:

• validação de menor de idade
• validação de categorias compatíveis
• cálculo de relatórios

Repositories

Responsáveis por acessar o banco de dados.

Data

Configuração do Entity Framework e estrutura do banco SQLite.

DTOs

Objetos usados para entrada e saída de dados da API.

Middlewares

Camada usada para interceptar exceções e retornar respostas padronizadas.

---

Regras importantes do sistema

Algumas regras foram implementadas diretamente na API para garantir consistência dos dados.

Pessoas

• Cada pessoa possui um ID único
• Ao excluir uma pessoa, todas as transações relacionadas a ela também são removidas automaticamente
• Isso é feito usando Cascade Delete no banco.

Categorias

• Cada categoria possui um ID único

Cada categoria possui uma finalidade:

Valor	Significado
0	Despesa
1	Receita
2	Ambas

Isso define se a categoria pode ser usada para receitas, despesas ou ambas.

Transações

• Cada transação possui um ID único
• Algumas regras importantes:
  • O valor da transação deve ser sempre positivo
  • Pessoas menores de 18 anos só podem registrar despesas
  • Uma transação não pode usar uma categoria incompatível

Exemplo:

• Categoria "Salário" não pode ser usada para registrar uma despesa. Essas validações são feitas na camada de Services.

Relatórios

A API fornece relatórios prontos com:

Para cada pessoa:

• total de receitas
• total de despesas
• saldo

Também é calculado o saldo geral consolidado.

---

Endpoints da API

Todos os endpoints usam JSON.

Autenticação

Método	Endpoint
POST	/api/v1/auth/register
POST	/api/v1/auth/login

Após o login a API retorna um token JWT.

Esse token deve ser enviado nos próximos requests usando:

Authorization: Bearer {seu_token}

Pessoas

Método	Endpoint
GET	/api/v1/pessoas
GET	/api/v1/pessoas/{id}
POST	/api/v1/pessoas
PUT	/api/v1/pessoas/{id}
DELETE	/api/v1/pessoas/{id}

Categorias

Método	Endpoint
GET	/api/v1/categorias
POST	/api/v1/categorias

Transações

Método	Endpoint
GET	/api/v1/transacoes
POST	/api/v1/transacoes

Relatórios

Método	Endpoint
GET	/api/v1/relatorios/pessoas
GET	/api/v1/relatorios/categorias

---

Como Executar o Projeto

Pré-requisitos

1. Instalar o .NET 9 (Basta acessar o site oficial da Microsoft e baixar a versão para seu computador).

Passos para Exploração e Execução

1. Clone o repositório: Para clonar o repositório em seu ambiente local, execute o seguinte comando:

   git clone https://github.com/SEU_USUARIO/expense-control-API.git

   Substitua SEU_USUARIO pelo seu usuário do github

2. Entre na pasta do projeto:

   cd expense-control-API

3. Restaure as dependências:

   dotnet restore

4. Instalar a ferramenta do Entity Framework para acessar o banco de dados via terminal.

   dotnet tool install --global dotnet-ef

5. Configurar variáveis de ambiente Na raiz do projeto copie o arquivo:

   cp .env.example .env

   Dentro do arquivo .env defina:

   # Chave secreta para assinar os tokens (use uma string complexa!)
   JWT_KEY=your_super_secret_key_here_with_32_chars
   
   # Emissor do token (geralmente o nome da sua API/empresa)
   JWT_ISSUER=your_issuer_here
   
   # Audiência (qual serviço deve aceitar o token)
   JWT_AUDIENCE=your_audience_here

   Exemplos em Cenários reais por ambiente:

   # AMBIENTE DE DESENVOLVIMENTO (localhost)
   # ---------------------------------------
   JWT_KEY="dev-chave-local-com-trinta-e-dois-caracteres-123"
   JWT_ISSUER="api-local-dev"
   JWT_AUDIENCE="app-local-dev"
   
   # AMBIENTE DE HOMOLOGAÇÃO/TESTE
   # -----------------------------
   JWT_KEY="homologacao-chave-com-trinta-e-dois-caracteres-2024-segura"
   JWT_ISSUER="api-homolog.meusistema.com"
   JWT_AUDIENCE="app-homolog.meusistema.com"
   
   # AMBIENTE DE PRODUÇÃO
   # --------------------
   JWT_KEY="kj43h5k1j2h3g4f5g6h7j8k9l0q1w2e3r4t5y6u7i8o9p0" 
   JWT_ISSUER="api.meusistema.com"
   JWT_AUDIENCE="app.meusistema.com"

6. Crie os arquivos necessários para a modelagem do banco de dados:

   dotnet ef migrations add InitialCreate

7. Execute a migration. Isso irá criar o arquivo: ExpenseControl.db e toda a estrutura do banco de dados (Tabelas, Index, etc)

   dotnet ef database update

8. Rode a aplicação:

   dotnet run

9. Acessar o Swagger Abra no navegador:

   http://localhost:5112/swagger

No Swagger você consegue:

• criar usuário
• fazer login
• testar todos os endpoints

---

Observação importante sobre usuários

Atualmente os dados são compartilhados entre todos os usuários do sistema.

Ou seja, todos os usuários conseguem visualizar os mesmos registros de:

• pessoas
• categorias
• transações

Uma evolução natural do sistema seria vincular os registros ao usuário autenticado, adicionando um campo UsuarioId nas entidades.

Isso permitiria que cada usuário tivesse seus próprios dados isolados, algo comum em sistemas multiusuário.

---

Front-end da aplicação

Este projeto é apenas a API.

O Front-End da aplicação foi desenvolvido separadamente em React + TypeScript.

O repositório do front-end pode ser encontrado em:

Front-end: https://github.com/herminio-rocha/expense-control-frontend.git

Ele consome os endpoints desta API.