Plataforma SaaS multi-tenant de gestão comercial para pequenos e médios estabelecimentos. O objetivo é dar ao lojista o mesmo nível de controle analítico das grandes redes de varejo, com uma interface simples o suficiente para o uso diário sem treinamento.

• O Problema
• Segmentos Suportados
• Funcionalidades
• Arquitetura
• Estrutura do Projeto
• Stack Tecnológica
• Modelo de Domínio
• Pré-requisitos
• Configuração do Ambiente
• Como Executar
• Endpoints e Documentação da API
• Equipe
• Licença

Pequenos empresários gerenciam estoque em planilhas, fecham o caixa manualmente e só percebem que um produto acabou quando o cliente pede. Faltam dados, sobra trabalho operacional.

O SGPE resolve isso automatizando o operacional e entregando inteligência sobre o negócio em tempo real: projeção de estoque, comportamento de compra dos clientes e fluxo de caixa com base em histórico.

Gestão multi-tenant Uma única plataforma hospeda múltiplos estabelecimentos com isolamento total de dados. Não há instalação local — o lojista acessa a conta e o ambiente já está configurado para o seu segmento.

Vendas e estoque Registro de venda em poucos cliques com atualização imediata de estoque. Alertas automáticos de baixo estoque e bloqueio de venda quando o saldo zera.

Financeiro automatizado Cada venda concluída gera um lançamento financeiro automaticamente. Painel de inadimplência com vencimentos em atraso e projeção de caixa por período.

Inteligência analítica Microserviço Python consome eventos de venda em tempo real e gera insights acionáveis:

• Previsão de ruptura de estoque com base no ritmo de saída
• Sugestão de produtos complementares por perfil de cliente
• Projeção de fluxo de caixa com base em sazonalidade histórica

+------------------+     +-------------------+     +-----------------+
|   Frontend       |---->|  Backend (Java)   |---->|   PostgreSQL    |
|   React + TS     |     |  Spring Boot      |     |                 |
+------------------+     +-------------------+     +-----------------+
                                  |
                          Eventos via Kafka
                                  |
                                  v
                         +-------------------+
                         |  Microservico     |
                         |  Analise (Python) |
                         +-------------------+

Decisões de design

• Arquitetura hexagonal no backend: o domínio de negócio não depende de frameworks. Services conhecem apenas ports (interfaces); os adapters JPA e HTTP ficam nas camadas externas. Isso facilita testes unitários e permite trocar a implementação de persistência sem alterar regras de negócio.

• Event-driven com Kafka: a análise de dados ocorre de forma assíncrona sem impactar a latência das vendas. O padrão Outbox garante que nenhum evento seja perdido mesmo em caso de falha do broker.

• Cache em dois níveis: Caffeine (in-process, sub-milissegundo) para leituras locais; Redis (distribuído) para compartilhar estado entre múltiplas instâncias da aplicação. Catálogo de itens e configurações de tenant são os principais candidatos.

• Isolamento por tenant: o tenantId é extraído do JWT em cada requisição e propagado via TenantContext (ThreadLocal). Nenhum endpoint expõe tenantId como parâmetro manipulável pelo cliente.

• Auditoria completa: todas as entidades registram createdBy, createdAt e updatedAt automaticamente via Spring Data JPA Auditing.

sgpe/
├── backend/
│   └── src/main/java/com/sgpe/
│       ├── domain/
│       │   ├── model/          # entidades de domínio puras (sem anotacoes JPA)
│       │   ├── enums/          # BusinessType, UserRole, SaleStatus, etc.
│       │   └── port/
│       │       ├── in/         # use cases (interfaces de entrada)
│       │       └── out/        # repository ports (interfaces de saida)
│       ├── application/
│       │   ├── service/        # implementacao dos use cases
│       │   └── dto/
│       │       ├── request/    # records de entrada com Bean Validation
│       │       └── response/   # records de saida
│       └── adapter/
│           ├── in/web/
│           │   └── controller/ # controllers REST
│           └── out/persistence/
│               ├── entity/     # entidades JPA
│               ├── mapper/     # MapStruct: dominio <-> JPA, dominio <-> DTO
│               └── repository/ # JPA repositories + adapters
├── analytics/                  # microservico Python
├── frontend/                   # React + TypeScript
├── docker-compose.yml
├── docker-compose.override.yml # ferramentas de desenvolvimento
└── .env.example

classDiagram
    direction BT

    class BaseEntity {
        <<abstract>>
        -Long id
        -Long tenantId
        -LocalDateTime createdAt
        -LocalDateTime updatedAt
        -String createdBy
    }

    class Tenant {
        -Long id
        -String businessName
        -String cnpj
        -BusinessType type
        -Boolean active
        -String settingsJson
    }

    class User {
        -String username
        -String passwordHash
        -String email
        -UserRole role
        -Boolean enabled
    }

    class Person {
        -String name
        -String document
        -String email
        -String phone
        -String address
        -PersonType type
        -Map~String,Object~ metadata
    }

    class Item {
        -String name
        -String description
        -BigDecimal price
        -Double stockBalance
        -String unit
        -ItemType type
        -Map~String,Object~ metadata
    }

    class Sale {
        -LocalDateTime saleDate
        -BigDecimal totalAmount
        -BigDecimal discount
        -SaleStatus status
        -PaymentMethod paymentMethod
        -String notes
    }

    class SaleItem {
        -Integer quantity
        -BigDecimal unitPrice
        -BigDecimal discount
        -BigDecimal subtotal
    }

    class FinancialRecord {
        -String description
        -BigDecimal value
        -TransactionType type
        -LocalDate dueDate
        -LocalDate paymentDate
        -Boolean paid
        -String notes
    }

    class SaleStatus {
        <<enumeration>>
        PENDING
        COMPLETED
        CANCELLED
    }

    class PaymentMethod {
        <<enumeration>>
        CASH
        CREDIT_CARD
        DEBIT_CARD
        PIX
        BANK_SLIP
    }

    class TransactionType {
        <<enumeration>>
        INCOME
        EXPENSE
    }

    BaseEntity <|-- User
    BaseEntity <|-- Person
    BaseEntity <|-- Item
    BaseEntity <|-- Sale
    BaseEntity <|-- SaleItem
    BaseEntity <|-- FinancialRecord

    Tenant "1" --> "n" BaseEntity : isola por tenantId
    Person "1" --> "n" Sale : realiza
    Sale "1" *--> "n" SaleItem : contem
    Item "1" --> "n" SaleItem : compoe
    Sale "1" --> "0..1" FinancialRecord : gera

Certifique-se de ter instalado na sua máquina antes de continuar:

1. Clone o repositório

git clone https://github.com/vitinh0z/sgpe.git
cd sgpe

2. Configure as variáveis de ambiente

Copie o arquivo de exemplo e preencha os valores:

cp .env.example .env

Variáveis obrigatórias para subir o projeto localmente:

# Banco de dados
DB_URL=jdbc:postgresql://postgres:5432/sgpe
DB_USER=sgpe
DB_PASSWORD=sgpe_local

# Redis
REDIS_HOST=redis
REDIS_PASSWORD=

# JWT
JWT_SECRET=troque-este-valor-em-producao
JWT_EXPIRATION=86400

# Kafka
KAFKA_BOOTSTRAP_SERVERS=kafka:9092

O arquivo .env esta no .gitignore e nunca deve ser versionado.

Subir toda a infraestrutura

docker compose up -d

Aguarde todos os containers ficarem healthy antes de acessar a aplicação. Você pode acompanhar com:

docker compose ps

Verificar se o backend esta pronto

curl http://localhost:8080/actuator/health/readiness
# esperado: {"status":"UP"}

Enderecos dos servicos

As ferramentas de desenvolvimento (Kafka UI, pgAdmin, Redis Commander) sobem automaticamente via docker-compose.override.yml quando o ambiente não é produção.

Rodar o backend sem Docker (desenvolvimento)

cd backend
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

Nesse caso o PostgreSQL, Redis e Kafka ainda precisam estar rodando via Docker:

docker compose up -d postgres redis kafka zookeeper

Rodar o frontend sem Docker

cd frontend
npm install
npm run dev

Com a aplicação rodando, acesse o Swagger UI em:

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

Todos os endpoints exigem autenticação JWT, exceto POST /auth/login. Para obter um token:

curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "senha"}'

Use o token retornado no header das demais requisições:

Authorization: Bearer <token>

Recursos disponíveis

Dúvidas ou sugestões? Abra uma issue.

Distribuído sob a licença MIT. Consulte o arquivo LICENSE para mais detalhes.