Skip to content

README.md

Latest commit

 

History

History
130 lines (99 loc) · 5.59 KB

README.md

File metadata and controls

130 lines (99 loc) · 5.59 KB

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.