SmartStock AI

SmartStock AI é uma solução avançada de gerenciamento de inventário que combina a robustez do Spring Boot 3 com o poder da Inteligência Artificial (Google Gemini via Spring AI) para oferecer insights preditivos e automação no controle de estoque.

---

🌟 Diferenciais do Projeto

🧠 Inteligência Artificial Generativa

Integrado via Spring AI, o sistema oferece:

• Sugestão Automática de Produtos: A partir de uma descrição bruta (ex: "mouse sem fio preto"), a IA sugere nome profissional, categoria compatível e preço estimado.
• Análise Preditiva de Estoque: Analisa o histórico de movimentações dos últimos 90 dias para prever a duração do estoque e sugerir datas exatas de reposição com recomendações estratégicas.

🛡️ Segurança e Performance

• Autenticação JWT: Controle de acesso baseado em roles (ADMIN e USER) para proteção total dos endpoints.
• Cache Inteligente com Redis: Redução drástica de latência em consultas frequentes, com sistema de invalidação automática em movimentações de estoque.
• Locks Otimistas: Integridade de dados garantida via @Version do JPA, evitando condições de corrida em ambientes concorrentes.

📝 Código Documentado

Todo o código da aplicação está documentado com Javadoc, cobrindo controllers, services e modelos de domínio, seguindo as boas práticas de Clean Code para facilitar a manutenção e colaboração.

---

🛠️ Stack Tecnológica

Camada	Tecnologia
Linguagem	Java 21
Framework	Spring Boot 3.3.x
Persistência	Spring Data JPA / Hibernate
Banco de Dados	PostgreSQL 16
Cache	Redis
IA	Spring AI (Google Gemini)
Documentação da API	Swagger / OpenAPI 3
Documentação do Código	Javadoc
Containerização	Docker & Docker Compose
Segurança	Spring Security & JWT (Auth0)

---

🚀 Como Executar

Pré-requisitos

• Docker e Docker Compose instalados.
• JDK 21.
• Uma chave de API do Google AI (configurada no application.yml ou variável de ambiente).

Passo a Passo

1. Clone o repositório:

   git clone https://github.com/WellSCosta/SmartStockAI.git
   cd SmartStockAI

2. Configure sua chave de API: No arquivo src/main/resources/application.yml, adicione sua chave:

   spring:
     ai:
       google:
         api-key: ${GOOGLE_AI_API_KEY}

3. Suba o ambiente com Docker Compose:

   docker-compose up -d

   Isso iniciará o PostgreSQL 16 e o Redis automaticamente.

4. Execute a aplicação:

   mvn spring-boot:run

---

📖 Documentação da API (Swagger)

Uma vez que a aplicação esteja rodando, acesse a documentação completa e interativa: 👉 http://localhost:8080/swagger-ui.html

---

🔄 Fluxo da API

🔐 Autenticação

Cliente
  │
  ├─ POST /auth/register ──► AuthController ──► AuthorizationService ──► UserRepository (persiste)
  │                                                                    └─► TokenService (gera JWT)
  │
  └─ POST /auth/login ─────► AuthController ──► AuthorizationService ──► UserRepository (valida)
                                                                       └─► TokenService (gera JWT)
                                                                            └─► Retorna: { token }

📦 Gestão de Produtos (requer JWT)

Cliente + JWT
  │
  ├─ GET  /products        ──► SecurityFilter (valida JWT)
  │                        ──► ProductController ──► ProductService ──► Redis Cache (HIT?) ──► Retorna lista
  │                                                                                    └──── Miss ──► ProductRepository
  │
  ├─ POST /products        ──► SecurityFilter (ADMIN)
  │                        ──► ProductController ──► ProductService ──► ProductRepository (salva)
  │                                                                  └─► Invalida cache Redis
  │
  ├─ PUT  /products/{id}   ──► SecurityFilter (ADMIN) ──► ProductController ──► ProductService
  │                        ──► Lock Otimista (@Version) ──► ProductRepository (atualiza)
  │                                                      └─► Invalida cache Redis
  │
  └─ DELETE /products/{id} ──► SecurityFilter (ADMIN) ──► ProductController ──► ProductService
                           ──► ProductRepository (remove) └─► Invalida cache Redis

📊 Movimentação de Estoque (requer JWT)

Cliente + JWT
  │
  └─ POST /products/{id}/movement
       ──► SecurityFilter (ADMIN)
       ──► ProductController
       ──► StockService ──► StockTransactionRepository (persiste ENTRY/EXIT)
                        └─► ProductRepository (atualiza quantidade)
                        └─► Invalida cache Redis do produto

🤖 Inteligência Artificial (requer JWT)

Cliente + JWT
  │
  ├─ POST /ai/suggest
  │    ──► SecurityFilter (valida JWT)
  │    ──► AIController ──► InventoryAIService
  │                      ──► Spring AI (Google Gemini)
  │                      └─► Retorna: { name, category, estimatedPrice }
  │
  └─ GET /ai/insights/{id}
       ──► SecurityFilter (valida JWT)
       ──► AIController ──► InventoryAIService
                         ──► ProductRepository (busca produto)
                         ──► StockTransactionRepository (histórico 90 dias)
                         ──► Spring AI (Google Gemini) — análise preditiva
                         └─► Retorna: { prediction, restockDate, recommendations }

---

🗂️ Estrutura do Projeto

SmartStockAI/
├── src/
│   └── main/
│       ├── java/com/smartstock/
│       │   ├── SmartStockAiApplication.java       # Ponto de entrada da aplicação
│       │   │
│       │   ├── config/                            # Configurações da aplicação
│       │   │   ├── AIConfig.java                  # Bean do ChatClient (Spring AI)
│       │   │   ├── JpaConfig.java                 # Configuração de auditoria JPA
│       │   │   ├── RedisConfig.java               # Serialização e template Redis
│       │   │   ├── LoggingCache.java              # Cache com log de eventos
│       │   │   ├── LoggingCacheManager.java       # CacheManager com logging
│       │   │   ├── SecurityConfig.java            # Cadeia de filtros e CORS
│       │   │   ├── SecurityFilter.java            # Filtro JWT (OncePerRequestFilter)
│       │   │   └── SwaggerConfig.java             # Configuração OpenAPI/Swagger
│       │   │
│       │   ├── controller/                        # Camada de apresentação (REST)
│       │   │   ├── AIController.java              # Endpoints de IA (/ai/*)
│       │   │   ├── AuthController.java            # Endpoints de auth (/auth/*)
│       │   │   └── ProductController.java         # Endpoints de produto (/products/*)
│       │   │
│       │   ├── service/                           # Regras de negócio
│       │   │   ├── AuthorizationService.java      # Carregamento de usuário (UserDetailsService)
│       │   │   ├── InventoryAIService.java        # Lógica de IA e análise preditiva
│       │   │   ├── ProductService.java            # CRUD e cache de produtos
│       │   │   ├── StockService.java              # Registro de movimentações de estoque
│       │   │   └── TokenService.java              # Geração e validação de JWT
│       │   │
│       │   ├── model/                             # Entidades JPA
│       │   │   ├── Category.java                  # Entidade de categoria
│       │   │   ├── Product.java                   # Entidade de produto (com @Version)
│       │   │   ├── StockTransaction.java          # Entidade de transação de estoque
│       │   │   ├── TransactionType.java           # Enum: ENTRY | EXIT
│       │   │   ├── User.java                      # Entidade de usuário
│       │   │   └── UserRole.java                  # Enum: ADMIN | USER
│       │   │
│       │   ├── repository/                        # Interfaces Spring Data JPA
│       │   │   ├── CategoryRepository.java
│       │   │   ├── ProductRepository.java
│       │   │   ├── StockTransactionRepository.java
│       │   │   └── UserRepository.java
│       │   │
│       │   ├── dto/                               # Objetos de transferência de dados
│       │   │   ├── AISuggestionDTO.java           # Resposta da sugestão de produto
│       │   │   ├── AuthRequestDTO.java            # Requisição de login
│       │   │   ├── AuthResponseDTO.java           # Resposta com token JWT
│       │   │   ├── ProductRequestDTO.java         # Criação/atualização de produto
│       │   │   ├── ProductResponseDTO.java        # Dados públicos de produto
│       │   │   ├── RegisterRequestDTO.java        # Cadastro de novo usuário
│       │   │   ├── StockAnalysisResponse.java     # Resposta da análise preditiva de IA
│       │   │   └── StockMovementRequestDTO.java   # Requisição de movimentação de estoque
│       │   │
│       │   └── exception/                         # Tratamento global de erros
│       │       ├── GlobalExceptionHandler.java    # @RestControllerAdvice centralizado
│       │       └── ResourceNotFoundException.java # Exceção 404 customizada
│       │
│       └── resources/
│           ├── application.yml                    # Configurações da aplicação
│           └── data.sql                           # Seed de dados iniciais (categorias e produtos)
│
├── docker-compose.yml                             # PostgreSQL 16 + Redis
├── pom.xml                                        # Dependências Maven
└── README.md

---

📊 Estrutura de Dados Inicial

O projeto conta com um script data.sql que popula o banco com:

• Categorias (Eletrônicos, Papelaria, Móveis).
• Produtos com histórico real de 90 dias para testes da IA.

---

👨‍💻 Autor

Desenvolvido por Wellington Costa. Conecte-se comigo no LinkedIn.