Skip to content

README.md

Latest commit

 

History

History
116 lines (91 loc) · 6.83 KB

README.md

File metadata and controls

116 lines (91 loc) · 6.83 KB

API de Gerenciamento de Frotas (Localiza Backend)

Java Spring Security JPA MySQL Swagger

Este é o repositório do backend para a aplicação de gerenciamento de frotas. É uma API RESTful completa construída com Spring Boot, projetada para ser consumida por um frontend (Angular). O projeto implementa um fluxo de e-commerce completo, desde a autenticação de usuário até o checkout e criação de pedidos.

Funcionalidades Principais

O projeto é dividido em quatro módulos principais:

1. Módulo de Autenticação e Usuário

  • Autenticação JWT: Sistema de login (/api/login) que utiliza AuthenticationManager e retorna um token JWT.
  • Payload Customizado: O token JWT gerado inclui um payload customizado com id, username e role do usuário, permitindo ao frontend identificar o usuário sem requisições adicionais.
  • Registro de Usuário: Endpoint público (/api/auth/register) para criação de novas contas, com criptografia de senha (BCrypt) e atribuição da role "USER" por padrão.
  • Controle de Acesso (RBAC): Proteção de endpoints baseada em Roles (habilitado via @EnableMethodSecurity).
    • Ex: Métodos de save e delete em CarController exigem ADMIN via @PreAuthorize("hasAuthority('ADMIN')").
    • Endpoint para administradores alterarem a role de outros usuários (/api/auth/role/{userId}).

2. Módulo de E-Commerce (Carrinho & Pedidos)

  • Gerenciamento de Carrinho (/api/cart):
    • Cada usuário possui um carrinho de compras persistente (Cart).
    • Adiciona/Remove carros e seus acessórios selecionados (CartItem).
    • Lógica de Preço: O CartService calcula o preço final do item, aplicando um multiplicador (accMultiplier) do carro sobre o preço dos acessórios.
    • Endpoints para obter o carrinho (GET /), adicionar item (POST /add), remover item (DELETE /remove/{id}) e limpar o carrinho (DELETE /clear).
  • Fluxo de Checkout (/api/orders):
    • Endpoint de checkout (POST /orders/checkout) que orquestra todo o processo de finalização.
    • Orquestração de Serviços: O OrderService (transacional):
      1. Valida o carrinho do usuário.
      2. Processa o pagamento (simulado) através do PaymentService.
      3. Cria um "snapshot" da compra: converte CartItems em OrderItems, salvando os nomes e preços exatos da transação.
      4. Salva o Order com o status (ex: PAID).
      5. Limpa o carrinho do usuário (cartService.clearCart()).

3. Módulo de Gerenciamento (CRUDs)

  • CRUDs Completos:
    • Carros: (/api/car)
    • Marcas: (/api/brand)
    • Acessórios: (/api/acessory)
  • Exclusão Lógica (Soft Delete): Carros não são deletados; eles são desativados via carStatus = false (carService.softDelete()).
  • Busca Avançada e Paginação:
    • Paginação: Listagem de Acessórios é paginada (/api/acessory/findAll/...).
    • Busca (LIKE): Busca por nome com ContainingIgnoreCase para Carros, Marcas e Acessórios.
    • Filtros: Busca de carros por faixa de preço (/findByPriceRange), ano (/findByYearGte) e ID da marca (/findByBrand).

4. Tratamento de Erros e Validação

  • Global Exception Handler: Um @ControllerAdvice (GlobalExceptionHandler) centraliza o tratamento de exceções para uma API semântica.
  • Validação (400): Captura MethodArgumentNotValidException (para DTOs com @NotBlank, etc.) e retorna um JSON com os campos e mensagens de erro.
  • Recurso Não Encontrado (404): Captura a exceção customizada ResourceNotFoundException.
  • Conflito (409): Captura a exceção customizada DuplicateEntryException (ex: usuário já existe).

Tecnologias Utilizadas (Backend)

  • Java 17
  • Spring Boot 3.x.x
  • Spring Security: Autenticação JWT e autorização por Roles (@EnableMethodSecurity).
  • Spring Data JPA (Hibernate): Persistência de dados e queries customizadas.
  • MySQL: Banco de dados relacional.
  • Jakarta Bean Validation: Validação de DTOs de entrada (ex: @NotBlank).
  • Maven: Gerenciamento de dependências.
  • Lombok: Redução de boilerplate.
  • SpringDoc OpenAPI (Swagger): Documentação da API.
  • io.jsonwebtoken (JJWT): Biblioteca para criação e validação dos tokens JWT.

Contexto para o Frontend (Angular)

Este backend foi projetado para se integrar perfeitamente com um frontend Angular:

  • CORS: Configurado globalmente (@CrossOrigin("*")), permitindo requisições de localhost:4200.
  • Autenticação:
    1. O frontend envia username e password para /api/login.
    2. Recebe o token JWT e o armazena (ex: localStorage).
    3. O frontend pode decodificar este token para obter imediatamente o id, username e role do usuário logado, eliminando a necessidade de uma chamada extra /me.
  • Interceptor HTTP: Um HttpInterceptorFn deve ser usado para anexar automaticamente o token (Authorization: Bearar ...) a todas as requisições, exceto para /login e /register.
  • Guarda de Rotas: O frontend deve usar CanActivateFn (Guards) para ler a role do token decodificado e proteger rotas de admin (ex: /admin/**).
  • Tratamento de Erros: O frontend pode usar o HttpErrorResponse do interceptor para ler as mensagens de erro padronizadas enviadas pela API:
    • Erro 400 (Validation): Esperar um JSON Map<String, String> com os erros de campo.
    • Erro 404 (Not Found): Esperar uma mensagem de texto simples.
    • Erro 409 (Conflict): Esperar uma mensagem de texto simples.

Configuração e Execução

1. Variáveis de Ambiente

O projeto utiliza um arquivo application.properties.

# Configuração do Banco de Dados
spring.datasource.url=jdbc:mysql://localhost:3306/localiza
spring.datasource.username=seu-usuario-mysql
spring.datasource.password=sua-senha-mysql

# Atualiza o schema do banco ao iniciar
spring.jpa.hibernate.ddl-auto=update

# Configuração do JWT (use uma chave longa e aleatória)
jwt.secret=CHAVE_SECRETA_LONGA_E_ALEATORIA_PARA_GERAR_TOKENS_JWT
jwt.expiration-hours=1

mvn spring-boot:run

Documentação da API (Swagger) Após iniciar a aplicação, a documentação completa e interativa do Swagger (com os endpoints publicamente liberados no SecurityConfig) pode ser acessada em:

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