🏗️ Maiconsoft API - Estrutura do Banco de Dados
Sistema de Gestão Empresarial com Controle de Clientes, Vendas e Usuários
👥 Equipe de Desenvolvimento
Denise - Dev Full Stack/DBA
Leandro - QA Specialist
Luiz Antonio - Dev Front-end
João Vinícius - Líder do Projeto
📊 Visão Geral do Sistema
O Maiconsoft API é um sistema de gestão empresarial desenvolvido em Java com Spring Boot, projetado para gerenciar clientes, vendas, usuários e cupons de desconto de forma integrada e eficiente.
Por que funciona: O sistema utiliza uma arquitetura robusta baseada em camadas (Controller → Service → Repository) com JPA/Hibernate para persistência, garantindo transações seguras, relacionamentos consistentes e alta performance através do HikariCP como pool de conexões.
🚀 Backend
Java 21 + Spring Boot 3.5.5
Spring Security + JWT
🗄️ Banco de Dados
SQL Server + HikariCP
JPA/Hibernate ORM
📱 Frontend
HTML5 + CSS3 + JavaScript
Responsivo e Mobile-First
📋 Documentação
Swagger/OpenAPI 3
Testes automatizados
🔗 Arquitetura e Fluxo de Dados
HTML/CSS/JS
REST APIs
Lógica de Negócio
JPA/Hibernate
Banco de Dados
🗂️ Modelo Lógico do Banco de Dados
Diagrama de Relacionamento de Entidades (DER): O modelo abaixo representa a estrutura completa do banco de dados com todos os relacionamentos entre as tabelas, chaves primárias, chaves estrangeiras e cardinalidades.
📊 Diagrama Entidade-Relacionamento
Visualize o modelo completo do banco de dados
📋 Legenda:
🔍 Principais Relacionamentos:
- 👤 USERS ← USER_ROLES: Cada usuário possui uma role (N:1)
- 🏢 CLIENTES → VENDAS: Um cliente pode ter várias vendas (1:N)
- 🎫 CUPOM → VENDAS: Um cupom pode ser usado em várias vendas (1:N)
- 💰 VENDAS → PAGAMENTOS: Uma venda pode ter vários pagamentos (1:N)
- 🔧 VENDAS ↔ SERVICOS: Relacionamento N:N através da tabela VENDAS_SERVICOS
- 🔗 VENDAS_SERVICOS: Tabela associativa que permite múltiplos serviços por venda
- 👤 USERS → DASHBOARD_LOG: Um usuário pode gerar vários logs (1:N)
👤 Tabela: USERS
Propósito: Gerenciar usuários do sistema com controle de acesso baseado em roles (FUNCIONARIO, ADMIN, DIRETOR).
| Campo | Tipo | Restrições | Descrição |
|---|---|---|---|
| ID_USER | BIGINT | PK, AUTO_INCREMENT | Identificador único do usuário |
| CODIGO_ACESSO | VARCHAR(6) | NOT NULL, UNIQUE | Código único de acesso (6 caracteres) |
| NOME | VARCHAR(100) | NOT NULL | Nome completo do usuário |
| VARCHAR(100) | NOT NULL, UNIQUE | Email para login e comunicação | |
| CPF | VARCHAR(11) | NOT NULL, UNIQUE | CPF do usuário (somente números) |
| TELEFONE | VARCHAR(20) | NULLABLE | Telefone de contato |
| ID_ROLE | BIGINT | NOT NULL, FK | Referência para UserRole (nível de acesso) |
| SENHA | VARCHAR(255) | NOT NULL | Senha criptografada (BCrypt) |
🔐 Tabela: USER_ROLES
Propósito: Definir níveis de acesso e permissões no sistema (FUNCIONARIO, ADMIN, DIRETOR).
| Campo | Tipo | Restrições | Descrição |
|---|---|---|---|
| ID_ROLE | BIGINT | PK, AUTO_INCREMENT | Identificador único da role |
| NOME | VARCHAR(50) | NOT NULL, UNIQUE | Nome da role (FUNCIONARIO, ADMIN, DIRETOR) |
| DESCRICAO | VARCHAR(200) | NULLABLE | Descrição das permissões da role |
🏢 Tabela: CLIENTES
Propósito: Armazenar informações completas dos clientes, incluindo dados fiscais, endereço e contato.
| Campo | Tipo | Restrições | Descrição |
|---|---|---|---|
| ID_CLIENTE | BIGINT | PK, AUTO_INCREMENT | Identificador único do cliente |
| CODIGO | VARCHAR(10) | NOT NULL, UNIQUE | Código único do cliente |
| LOJA | VARCHAR(5) | NOT NULL | Código da loja/filial |
| RAZAO_SOCIAL | VARCHAR(150) | NOT NULL | Razão social da empresa |
| TIPO | VARCHAR(1) | NOT NULL | Tipo de pessoa (F=Física, J=Jurídica) |
| NOME_FANTASIA | VARCHAR(150) | NULLABLE | Nome fantasia da empresa |
| FINALIDADE | VARCHAR(1) | NULLABLE | Finalidade do cliente no sistema |
| CPF_CNPJ | VARCHAR(14) | NOT NULL | CPF ou CNPJ do cliente |
| CEP | VARCHAR(10) | NULLABLE | CEP do endereço (integração ViaCEP) |
| + Campos de endereço, contato e auditoria (DATA_CRIACAO, DATA_ATUALIZACAO) | |||
💰 Tabela: VENDAS
Propósito: Controlar vendas realizadas, orçamentos, valores e status dos pedidos.
| Campo | Tipo | Restrições | Descrição |
|---|---|---|---|
| ID_VENDA | BIGINT | PK, AUTO_INCREMENT | Identificador único da venda |
| NUMERO_ORCAMENTO | VARCHAR(20) | NOT NULL | Número do orçamento/pedido |
| ID_CLIENTE | BIGINT | NOT NULL, FK | Referência para Clientes |
| ID_CUPOM | BIGINT | NULLABLE, FK | Referência para Cupom (desconto) |
| STATUS | VARCHAR(20) | NOT NULL | Status da venda (PENDENTE, CONFIRMADA, CANCELADA) |
| VALOR_BRUTO | DECIMAL(10,2) | NOT NULL | Valor bruto da venda |
| VALOR_DESCONTO | DECIMAL(10,2) | NULLABLE | Valor do desconto aplicado |
| VALOR_TOTAL | DECIMAL(10,2) | NOT NULL | Valor final (bruto - desconto) |
| + Campos de auditoria (DATA_VENDA, DATA_CRIACAO, etc.) | |||
🎫 Tabela: CUPOM
Propósito: Gerenciar cupons de desconto com regras de validade e percentuais.
| Campo | Tipo | Restrições | Descrição |
|---|---|---|---|
| ID_CUPOM | BIGINT | PK, AUTO_INCREMENT | Identificador único do cupom |
| CODIGO | VARCHAR(20) | NOT NULL, UNIQUE | Código do cupom para aplicação |
| NOME | VARCHAR(100) | NULLABLE | Nome descritivo do cupom |
| DESCRICAO | TEXT | NULLABLE | Descrição detalhada do cupom |
| PERCENTUAL_DESCONTO | DECIMAL(5,2) | NOT NULL | Percentual de desconto (0.00 a 100.00) |
| DATA_VALIDADE | DATE | NOT NULL | Data limite para uso do cupom |
| ATIVO | BOOLEAN | NOT NULL | Status de ativação do cupom |
💳 Tabela: PAGAMENTOS
Propósito: Registrar formas de pagamento e controlar transações financeiras.
| Campo | Tipo | Restrições | Descrição |
|---|---|---|---|
| ID_PAGAMENTO | BIGINT | PK, AUTO_INCREMENT | Identificador único do pagamento |
| ID_VENDA | BIGINT | NOT NULL, FK | Referência para Vendas |
| FORMA_PAGAMENTO | VARCHAR(50) | NOT NULL | Forma de pagamento (DINHEIRO, CARTÃO, PIX, etc.) |
| VALOR_PAGO | DECIMAL(10,2) | NOT NULL | Valor pago nesta transação |
| DATA_PAGAMENTO | DATETIME | NOT NULL | Data e hora do pagamento |
| STATUS | VARCHAR(20) | NOT NULL | Status do pagamento (PENDENTE, APROVADO, REJEITADO) |
🔧 Tabela: SERVICOS
Propósito: Catalogar serviços oferecidos pela empresa com preços base.
| Campo | Tipo | Restrições | Descrição |
|---|---|---|---|
| ID_SERVICO | BIGINT | PK, AUTO_INCREMENT | Identificador único do serviço |
| NOME | VARCHAR(100) | NOT NULL | Nome do serviço oferecido |
| DESCRICAO | TEXT | NULLABLE | Descrição detalhada do serviço |
| PRECO_BASE | DECIMAL(10,2) | NOT NULL | Preço base do serviço |
| CATEGORIA | VARCHAR(50) | NULLABLE | Categoria do serviço (Construção, Reforma, etc.) |
| STATUS | VARCHAR(20) | NOT NULL, DEFAULT 'ATIVO' | Status do serviço (ATIVO, INATIVO) |
🔗 Tabela: VENDAS_SERVICOS
Propósito: Tabela de ligação entre VENDAS e SERVICOS (relacionamento N:N). Permite que uma venda tenha múltiplos serviços e um serviço pode estar em múltiplas vendas.
| Campo | Tipo | Restrições | Descrição |
|---|---|---|---|
| ID_VENDA_SERVICO | BIGINT | PK, AUTO_INCREMENT | Identificador único da associação |
| ID_VENDA | BIGINT | NOT NULL, FK → VENDAS | Referência para a venda |
| ID_SERVICO | BIGINT | NOT NULL, FK → SERVICOS | Referência para o serviço |
| QUANTIDADE | INT | NOT NULL, DEFAULT 1 | Quantidade do serviço na venda |
| PRECO_UNITARIO | DECIMAL(10,2) | NOT NULL | Preço unitário do serviço na venda |
📊 Tabela: DASHBOARD_LOG
Propósito: Auditar ações dos usuários e gerar relatórios de atividade do sistema.
| Campo | Tipo | Restrições | Descrição |
|---|---|---|---|
| ID_LOG | BIGINT | PK, AUTO_INCREMENT | Identificador único do log |
| ID_USER | BIGINT | NULLABLE, FK | Usuário que realizou a ação |
| ACAO | VARCHAR(100) | NOT NULL | Ação realizada (LOGIN, CADASTRO_CLIENTE, etc.) |
| DETALHES | TEXT | NULLABLE | Detalhes da ação realizada |
| DATA_ACAO | DATETIME | NOT NULL | Data e hora da ação |
| IP_ADDRESS | VARCHAR(45) | NULLABLE | Endereço IP de origem |
⚙️ Por Que o Sistema Funciona
🏗️ Arquitetura Robusta
O sistema utiliza Spring Boot 3.5.5 com Java 21, oferecendo performance otimizada e recursos modernos da linguagem. A arquitetura em camadas garante separação de responsabilidades e facilita manutenção.
🔐 Segurança Avançada
Spring Security + JWT garantem autenticação stateless e autorização baseada em roles. Senhas são criptografadas com BCrypt, e o sistema implementa rate limiting e CORS configurável.
💾 Persistência Otimizada
JPA/Hibernate com HikariCP oferecem ORM eficiente e pool de conexões de alta performance. O banco SQL Server garante transações ACID e integridade referencial.
🔗 Relacionamentos Inteligentes
As tabelas são interconectadas através de chaves estrangeiras que garantem consistência dos dados. O sistema suporta relacionamentos 1:N (Cliente→Vendas) e N:1 (User→Role).
📊 Monitoramento e Auditoria
A tabela DASHBOARD_LOG registra todas as ações críticas do sistema, permitindo auditoria completa e análise de comportamento dos usuários.
🎯 Integração Externa
O sistema integra com ViaCEP para preenchimento automático de endereços e serviços de email para notificações, mantendo os clientes sempre informados.
🚀 Tecnologias e Ferramentas
☕ Java Ecosystem
Java 21, Maven, JUnit 5, Mockito
🌱 Spring Framework
Spring Boot, Security, Data JPA, Actuator
🗄️ Database & ORM
SQL Server, Hibernate, HikariCP
📋 DevOps & Docs
Swagger/OpenAPI, Logback, Micrometer
✨ Sistema Pronto para Produção
Com essa estrutura robusta, o Maiconsoft API está preparado para atender empresas de todos os portes, oferecendo escalabilidade, segurança e facilidade de uso em um pacote completo.