API de Gerenciamento de CRM

Esta é uma API RESTful completa desenvolvida em Java com Spring Boot 3. Ela serve como backend para um sistema de CRM e gerenciamento de vendas, permitindo o controle de usuários (administradores, supervisores, colaboradores), clientes, propostas, vendas e metas.

A API é projetada para ser robusta, segura e escalável, utilizando autenticação baseada em JWT, gerenciamento de banco de dados com Flyway e funcionalidades avançadas como importação de planilhas Excel para clientes e vendas.

🚀 Tecnologias Utilizadas

Este projeto utiliza um conjunto de tecnologias modernas para garantir performance e manutenibilidade:

• Core:

  • Java 17
  • Spring Boot 3.5.0

• Acesso a Dados:

  • Spring Data JPA (Hibernate)
  • MySQL (Driver mysql-connector-j)

• Migrações de Banco:

  • Flyway

• Segurança:

  • Spring Security 6
  • JWT (JSON Web Tokens) - via auth0/java-jwt

• Web:

  • Spring Web (para APIs RESTful)

• Utilitários:

  • Lombok (redução de boilerplate)
  • MapStruct (mapeamento eficiente de DTOs)
  • Apache POI (leitura e escrita de arquivos Excel .xlsx)

• Validação:

  • Spring Boot Starter Validation (Jakarta Bean Validation)

• Build:

  • Apache Maven

• Testes:

  • JUnit 5 (via spring-boot-starter-test)
  • H2 (banco de dados em memória para testes)

✨ Principais Funcionalidades

A API oferece um conjunto completo de funcionalidades para gerenciamento de vendas:

• Autenticação e Autorização:

  • Sistema de login seguro baseado em JWT (Email/Senha).
  • Controle de acesso baseado em papéis (RBAC) com 3 níveis: ADMIN, SUPERVISOR, e USER (Colaborador).

• Gerenciamento de Usuários:

  • CRUD completo para Administradores, Supervisores e Colaboradores (disponível apenas para ADMIN).

• Gestão de Clientes:

  • CRUD completo de clientes.
  • Listagem de clientes filtrada por permissão (Colaborador vê apenas os seus, Supervisor vê os da sua equipe, Admin vê todos).
  • Funcionalidade de importação de clientes em lote via planilha Excel (.xlsx).
  • Reatribuição de clientes entre colaboradores.

• Gestão de Vendas e Propostas:

  • Registro de Propostas de Venda.
  • Registro de Vendas efetivadas (com cálculo de comissão baseado no regime de contratação - CLT/MEI).
  • Importação de Vendas e Propostas em lote via planilhas.

• Metas e Performance:

  • Definição e acompanhamento de Metas de vendas, que podem ser individuais (por Colaborador) ou de equipe (por Supervisor).

• Dashboards e Relatórios:

  • Endpoints para popular dashboards com KPIs (taxa de conversão, clientes ativos, valor vendido, progresso da meta).
  • Relatórios filtráveis (vendas por período, por banco, comissões).

• Gestão de Carteiras:

  • Visualização da carteira de clientes e performance de vendas por Supervisor e sua respectiva equipe.

🔑 Segurança: Autenticação e Papéis

A segurança da API é gerenciada pelo Spring Security. O acesso aos endpoints é protegido e requer um token JWT válido, que deve ser enviado no header Authorization (ex: Bearer <token>). O acesso é diferenciado por papéis (Roles), definidos centralmente em SecurityConfig.java:

• ROLE_ADMIN:
  • Acesso total ao sistema.
  • Pode gerenciar (CRUD) Administradores, Supervisores e Colaboradores.
• ROLE_SUPERVISOR:
  • Acesso aos seus próprios dados e aos dados de toda a sua equipe (Colaboradores).
  • Pode acessar relatórios, dashboards da equipe e gerenciar metas.
  • Pode importar planilhas de clientes.
• ROLE_USER (Colaborador):
  • Acesso restrito apenas aos seus próprios dados.
  • Pode gerenciar seus clientes, propostas e vendas.

🗃️ Banco de Dados e Migrações

O esquema do banco de dados é gerenciado pelo Flyway. As migrações são executadas automaticamente na inicialização da aplicação.

• Localização dos Scripts: src/main/resources/db.migrations
• Banco de Dados: O projeto está configurado para MySQL.
• Principais Tabelas:
  • TBL_ADMINISTRADOR
  • TBL_SUPERVISOR
  • TBL_COLABORADOR
  • TBL_CLIENTES_DADOS
  • TBL_VENDA
  • TBL_PROPOSTA_VENDA
  • TBL_META

⚙️ Configuração e Variáveis de Ambiente

Para executar a aplicação, é necessário configurar as seguintes variáveis de ambiente. Elas são lidas a partir do arquivo application.properties.

• STORAGE_ACESS_LINK: A URL de conexão JDBC completa do banco de dados. (Ex: jdbc:mysql://servidor:3306/meu_banco)
• STORAGE_USER: O nome de usuário para conexão com o banco.
• STORAGE_PASS: A senha para conexão com o banco.
• TOKENPASS: A chave secreta utilizada para assinar e validar os tokens JWT.

📦 Build (Gerando o .jar)

Para gerar o arquivo .jar executável:

./mvnw clean package

O arquivo final estará em target/demo-0.0.1-SNAPSHOT.jar.

🔄 CI/CD - Implantação Contínua

O projeto está configurado com um fluxo de CI/CD usando GitHub Actions, definido em .github/workflows/deploy.yml.

• Gatilho: Qualquer push na branch dev.
• Ações:
  1. Checkout do código.
  2. Configuração do Java 17.
  3. Build do projeto com Maven (mvn clean package).
  4. Login no Azure.
  5. Deploy automático do .jar gerado para o Azure Web App configurado.