🏙️ DoaVille API

A DoaVille API é um sistema backend robusto, desenvolvido em Java com Spring Boot, para gerenciar o ciclo de vida de doações. A plataforma centraliza o cadastro de itens, o registro de solicitações e aplica regras de negócio para garantir a integridade e a organização do processo.

Nota: Este projeto foi criado como parte de um portfólio para demonstrar habilidades em desenvolvimento backend, aplicando padrões RESTful, arquitetura de microsserviços e boas práticas do ecossistema Spring.

🎯 Objetivo do Projeto

O objetivo principal da API é resolver o problema de organização e rastreamento de doações para pequenas e médias organizações, oferecendo uma solução centralizada para:

• Cadastrar e gerenciar um inventário de itens disponíveis para doação.
• Registrar e validar solicitações de doação, garantindo que as regras de negócio sejam cumpridas.
• Fornecer endpoints claros e bem documentados para consulta e filtragem de dados.
• Garantir a consistência e a segurança dos dados através de uma arquitetura bem definida e tratamento de erros.

✨ Features Principais

• ✅ CRUD completo para Itens de Doação: Crie, leia, atualize e delete itens do catálogo.
• ✅ CRUD para Solicitações de Doação: Registre e gerencie pedidos de doação.
• ✅ Validações de Negócio: Impede a solicitação de itens inativos e valida a quantidade solicitada.
• ✅ Tratamento de Erros Centralizado: Respostas de erro padronizadas e amigáveis para a API.
• ✅ Filtragem de Solicitações: Permite consultar solicitações com base no item de doação.
• ✅ Padrão DTO: Separação clara entre as entidades do banco de dados e os objetos transferidos pela API.

🛠️ Tecnologias e Arquitetura

Tecnologias

• Java 17: Versão LTS da linguagem, garantindo robustez e performance.
• Spring Boot 3.x: Framework principal para criação da API REST.
• Spring Data JPA: Para abstração da camada de persistência com o banco de dados.
• PostgreSQL: Banco de dados relacional para armazenamento dos dados.
• Lombok: Para reduzir código boilerplate em classes Java.
• Spring Validation: Para validações declarativas nos DTOs.
• Maven: Gerenciador de dependências e build do projeto.

Arquitetura e Boas Práticas

• API RESTful: Design de endpoints seguindo as convenções REST.
• Separação de Camadas: Estrutura organizada em Controller, Service, Repository, Mapper e DTOs.
• Mapeamento com MapStruct (implícito): Utilização de Mappers para converter DTOs em Entidades de forma limpa.
• Exception Handling Global: Um GlobalExceptionHandler captura e trata exceções, retornando respostas HTTP consistentes.

📂 Estrutura do Projeto

A estrutura segue as convenções do Spring Boot, separando as responsabilidades em pacotes específicos.

doaville-api/
└── src/
└── main/
├── java/com/doaville/
│   ├── controller/      (Controladores REST)
│   ├── dto/             (Data Transfer Objects)
│   ├── entity/          (Entidades JPA)
│   ├── exception/       (Classes de exceção customizadas)
│   ├── mapper/          (Mapeadores de DTO/Entidade)
│   ├── repository/      (Interfaces Spring Data JPA)
│   ├── service/         (Lógica de Negócio)
│   └── DoavilleApiApplication.java
└── resources/
└── application.properties

🚀 Como Executar o Projeto

Pré-requisitos

• Java JDK 17
• Apache Maven
• PostgreSQL
• Postman ou similar para testar a API.

Configuração e Execução

1. Clone o Repositório:

   git clone https://github.com/DougBrando/doaville-api.git
   cd doaville-api

2. Configure o Banco de Dados:

   • No PostgreSQL, crie um banco de dados chamado doaville_db.

     CREATE DATABASE doaville_db;

   • Abra o arquivo src/main/resources/application.properties e atualize as credenciais do seu banco:

     spring.datasource.url=jdbc:postgresql://localhost:5432/doaville_db
     spring.datasource.username=seu_usuario_postgres
     spring.datasource.password=sua_senha_postgres
     spring.jpa.hibernate.ddl-auto=update

3. Compile e Execute a Aplicação:

   mvn clean install
   mvn spring-boot:run

   • A API estará rodando em http://localhost:8080.

📝 Endpoints da API

A URL base para todos os endpoints é http://localhost:8080.

Itens de Doação (/api/itens-doacao)

Método HTTP	Endpoint	Descrição	Exemplo de Corpo (Body)
POST	/	Cria um novo item de doação.	{"nome": "Cesta Básica", "descricao": "Alimentos essenciais", "ativo": true}
GET	/	Lista todos os itens de doação.	N/A
GET	/{id}	Busca um item por ID.	N/A
PUT	/{id}	Atualiza um item existente.	{"nome": "Cesta Básica Familiar", "descricao": "Itens para uma família", "ativo": true}
DELETE	/{id}	Exclui um item de doação.	N/A

Solicitações de Doação (/api/solicitacoes-doacao)

Método HTTP	Endpoint	Descrição	Exemplo de Corpo (Body)
POST	/	Cria uma nova solicitação de doação.	{"idItemDoacao": 1, "quantidade": 5, "enderecoEntrega": "Rua Exemplo, 123", "bairroEntrega": "Centro"}
GET	/	Lista todas as solicitações.	N/A
GET	/filtrar-por-item?idItemDoacao={id}	Filtra solicitações por ID do item.	N/A
DELETE	/{id}	Exclui uma solicitação.	N/A

🔮 Próximos Passos

• Implementar autenticação e autorização com Spring Security e JWT.
• Adicionar paginação nas listagens (GET).
• Criar um endpoint para alterar o status de um item (ativo/inativo) sem precisar enviar o corpo todo.
• Implementar testes unitários e de integração.
• Dockerizar a aplicação e o banco de dados.

👨‍💻 Autor

Douglas Graça

• GitHub: @DougBrando
• LinkedIn: Douglas Graça