📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados na Matriz de 20 Capítulos de Aplicações Full Stack. Recomendado revisar antes de iniciar a execução.

📦 Gestão de Estoque 02: Segurança JWT, RBAC & Relatórios

v1.0 — Continuação enterprise da solução de inventário com autenticação stateless via tokens JWT, controle granular de acessos por papel (RBAC), histórico auditado e relatórios gerenciais.

Trilha de Especialização Pedagógica — Série Gestão de Estoque (Projeto 2 de 2)

• Gestão de Estoque 01: Spring Boot 3 & SPA de Controle
• Gestão de Estoque 02 (este): Segurança JWT, RBAC (Admin vs Estoquista), Auditoria & Relatórios

🎓 Nível Profissional Simulado: Engenheiro Back-end Pleno (Java & Spring Security). O isolamento de privilégios de almoxarifado é uma exigência de compliance contábil e auditoria (SOX). Dominar filtros de segurança interceptores (OncePerRequestFilter), emissão criptográfica de tokens JWT com claims de roles e autorização declarativa nos métodos (@PreAuthorize) capacita o desenvolvedor a construir sistemas enterprise invioláveis.

🏛️ Galeria Arquitetural & Diagramas de Engenharia

Arquitetura de Segurança, RBAC e Camadas de Auditoria

Ciclo de Autenticação JWT e Autorização RBAC

📁 Estrutura Canônica de Pastas Anti-Colisão

O projeto adota a convenção padronizada de subpastas por camada e tecnologia <camada>-<tecnologia>:

catalogo_projetos/fullstack_estoque_02_spring_auth/
├── api-spring/                 # Backend enterprise em Java 21 e Spring Boot 3
│   ├── src/
│   │   ├── main/java/br/com/estoque/
│   │   │   ├── config/         # Filtros de segurança e SecurityFilterChain
│   │   │   ├── controller/     # Endpoints de autenticação, relatórios e estoque
│   │   │   ├── dto/            # LoginRequest, JwtResponse, MovimentacaoDTO
│   │   │   ├── model/          # Entidades Usuario, Role, MovimentacaoEstoque
│   │   │   ├── repository/     # Repositórios com queries de auditoria
│   │   │   ├── security/       # JwtService, UserDetailsService e hash Bcrypt
│   │   │   └── service/        # Regras de movimentação auditada e exportação
│   │   └── main/resources/
│   │       ├── application.yml # Configurações de segredos JWT e datasource
│   │       └── data.sql        # Seed com usuários padrão (admin e operador)
│   ├── Dockerfile              # Dockerfile multi-stage com OpenJDK 21
│   ├── docker-compose.yml      # Banco PostgreSQL e container da aplicação
│   └── pom.xml                 # Dependências jjwt, spring-boot-starter-security
├── assets/                     # Diagramas vetoriais SVG autorais
└── modulo00.md a modulo04.md   # Cadernos conceituais de implementação passo a passo

📚 Trilha Conceitual de Engenharia (Módulos 00 ao 04)

• Módulo 00: Levantamento de Requisitos de Segurança, Casos de Uso e Modelagem
• Módulo 01: Nova Modelagem Relacional, Tabela de Usuários e Auditoria
• Módulo 02: Regras de Negócio e o Papel do Operador Estoquista
• Módulo 03: API REST Segura, Busca Otimizada e Alerta de Estoque Mínimo
• Módulo 04: Relatórios Analíticos, Exportação e Integração com Frontend

🧑‍💼 Especificação Formal de Engenharia de Software

1. Histórias de Usuário (User Stories)

• US-GE01: Como estoquista credenciado, quero me autenticar com usuário e senha recebendo um token JWT para operar as rotas de movimentação de itens.
• US-GE02: Como gerente de almoxarifado (ADMIN), quero cadastrar novos usuários e definir suas respectivas permissões (ROLE_ADMIN ou ROLE_ESTOQUISTA).
• US-GE03: Como auditor fiscal, quero consultar o extrato completo de movimentações de um item contendo data, hora, tipo (entrada/saída), quantidade e o usuário responsável.
• US-GE04: Como comprador corporativo, quero emitir relatório de itens com estoque abaixo do limite de segurança para tomada de decisão de reposição.
• US-GE05: Como desenvolvedor de segurança, quero assegurar que tentativas de acesso a relatórios gerenciais por usuários sem privilégio retornem HTTP 403 Forbidden.

2. Requisitos Funcionais (RF)

• RF-GE01: O endpoint /api/auth/login deve validar as credenciais fornecidas contra o banco criptografado com BCrypt e emitir token JWT assinado digitalmente.
• RF-GE02: O token JWT deve conter claims públicas descrevendo a identificação do usuário e sua coleção de perfis (roles).
• RF-GE03: O filtro JwtAuthenticationFilter deve validar o cabeçalho Authorization: Bearer <token> em todas as requisições privadas populando o SecurityContextHolder.
• RF-GE04: Todas as operações de entrada e saída devem gravar obrigatoriamente um registro imutável na tabela movimentacoes_estoque.
• RF-GE05: O serviço de relatórios deve fornecer endpoint para exportação de dados agregados com métricas de giro e produtos críticos.

3. Requisitos Não-Funcionais (RNF)

• RNF-GE01 (Criptografia): Nenhuma senha em texto puro deve ser armazenada em disco; o hashing deve utilizar BCrypt com fator de custo mínimo igual a 10.
• RNF-GE02 (Expiração de Sessão): Os tokens JWT devem possuir tempo de expiração fixo de 2 horas, forçando reautenticação periódica.
• RNF-GE03 (Arquitetura Stateless): A aplicação não deve alocar sessão HTTP no servidor (SessionCreationPolicy.STATELESS), permitindo escalabilidade horizontal elástica.
• RNF-GE04 (Princípio do Menor Privilégio): Operações destrutivas e parametrização de estoques mínimos devem ser restritas exclusivamente ao papel ROLE_ADMIN.
• RNF-GE05 (Rastreabilidade): Toda exceção de acesso negado deve ser registrada em log com nível WARN incluindo IP de origem e tentativa de recurso.

📐 Diagrama de Casos de Uso (UML / Mermaid)

flowchart LR
    subgraph Atores
        Estoquista["👤 Estoquista"]
        Admin["🔑 Gerente / Admin"]
    end

    subgraph "Sistema de Gestão de Estoque v2 (Auth & RBAC)"
        UC01["UC01: Autenticar via JWT"]
        UC02["UC02: Registrar Entrada/Saída com Auditoria"]
        UC03["UC03: Gerenciar Usuários e Perfis"]
        UC04["UC04: Emitir Relatório de Auditoria"]
        UC05["UC05: Exportar Relatório de Itens Críticos"]
    end

    Estoquista --> UC01
    Estoquista --> UC02

    Admin --> UC01
    Admin --> UC02
    Admin --> UC03
    Admin --> UC04
    Admin --> UC05

📊 Matriz de Rastreabilidade de Requisitos (RTM)

🚀 Roteiro de Execução & Homologação no Laboratório

1. Inicialização do Backend Spring Boot com JWT (api-spring)

cd catalogo_projetos/fullstack_estoque_02_spring_auth/api-spring

# Execução em modo desenvolvimento com banco em memória
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

• Console H2: http://localhost:8080/h2-console
• Documentação interativa Swagger UI: http://localhost:8080/swagger-ui.html

2. Fluxo de Teste de Autenticação via cURL

# 1. Obter Token JWT como ADMIN
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password123"}'

# 2. Consultar Relatório com Token
curl -X GET http://localhost:8080/api/relatorios/criticos \
  -H "Authorization: Bearer <SEU_TOKEN_AQUI>"

🧪 Matriz de Checkpoints de Homologação (CP-01 a CP-05)