Create README.md

Author: HernandoJunior

README.md

@@ -0,0 +1,130 @@
+# API de Gerenciamento de CRM - Virtus
+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 (Virtus), 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:
+
+```bash
+./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.