📚 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 01: Spring Boot 3 & SPA de Controle

v1.0 — Arquitetura em camadas (Layered Architecture) para controle de inventário físico com Spring Data JPA, H2 e PostgreSQL.

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

• Gestão de Estoque 01 (este): Backend Spring Boot 3, CRUD de Produtos, Categorias e Persistência
• Gestão de Estoque 02: Segurança JWT, RBAC & Relatórios

🎓 Nível Profissional Simulado: Desenvolvedor Back-end Java Júnior / Pleno. Em operações logísticas e varejistas, a consistência dos dados de estoque é crítica para o negócio. Dominar a arquitetura em camadas do ecossistema Spring (Controllers REST, Services transacionais, Repositórios JPA e DTOs imutáveis) prepara para desafios de alta concorrência e integridade relacional.

🏛️ Galeria Arquitetural & Diagramas de Engenharia

Arquitetura de Comunicação e Camadas da Solução

Fluxo Transacional de Movimentação de Estoque

📁 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_01_spring_spa/
├── api-spring/                 # Backend robusto em Java 21 e Spring Boot 3
│   ├── src/
│   │   ├── main/java/br/com/estoque/
│   │   │   ├── config/         # Configurações de CORS e documentação OpenAPI
│   │   │   ├── controller/     # Controladores REST com endpoints mapeados
│   │   │   ├── dto/            # Data Transfer Objects para requests e responses
│   │   │   ├── model/          # Entidades JPA mapeadas (Produto, Categoria, Estoque)
│   │   │   ├── repository/     # Interfaces Spring Data JPA
│   │   │   └── service/        # Regras de negócio e transações (@Transactional)
│   │   └── main/resources/
│   │       ├── application.yml # Perfis de ambiente (dev: H2 / prod: Postgres)
│   │       └── data.sql        # Carga inicial e seed de produtos de demonstração
│   ├── Dockerfile              # Empacotamento em imagem conteinerizada
│   ├── docker-compose.yml      # Subida de banco PostgreSQL de suporte
│   └── pom.xml                 # Gerenciamento de dependências Maven
├── assets/                     # Diagramas vetoriais SVG autorais
├── modulo00a.md                # Planejamento didático e levantamento de requisitos
└── modulo00.md a modulo09.md   # Cadernos conceituais de implementação passo a passo

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

• Planejamento Didático Original (8 Blocos de Engenharia)
• Módulo 00: Introdução ao Domínio de Estoque
• Módulo 01: Configuração do Projeto Spring Boot 3 e Dependências
• Módulo 02: Entidades JPA e Repositórios com Spring Data
• Módulo 03: Serviços Transacionais e Regras de Negócio
• Módulo 04: Controladores REST e Respostas Padronizadas
• Módulo 05: Fundamentos de Segurança e Isolamento
• Módulo 06: Configuração de CORS e Documentação OpenAPI
• Módulo 07: Testes Unitários e Testes de Integração com MockMvc
• Módulo 08: Integração com Frontend SPA e Consumo REST
• Módulo 09: Conclusão, Containerização e Próximos Passos

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

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

• US-GE01: Como operador de almoxarifado, quero cadastrar novos produtos informando SKU, nome, categoria, preço de custo e quantidade inicial para disponibilizá-los no estoque.
• US-GE02: Como estoquista, quero registrar entradas de mercadorias atualizando o saldo físico de forma transacional e atômica.
• US-GE03: Como estoquista, quero registrar baixas e saídas de mercadorias, impedindo operações que deixem o saldo negativo.
• US-GE04: Como gerente de compras, quero consultar a listagem de produtos com filtros por categoria e sinalização visual de estoque baixo.
• US-GE05: Como desenvolvedor de integrações, quero consultar a documentação interativa Swagger para validar payloads e códigos de status HTTP.

2. Requisitos Funcionais (RF)

• RF-GE01: A API Spring Boot deve fornecer endpoints REST completos (GET, POST, PUT, DELETE) para a entidade Produto sob o prefixo /api/produtos.
• RF-GE02: A entidade Produto deve manter obrigatoriamente os atributos id, sku (único), nome, preco, quantidadeEstoque e estoqueMinimo.
• RF-GE03: As operações de atualização de saldo devem ser anotadas com @Transactional garantindo isolamento ACID durante acessos simultâneos.
• RF-GE04: A API deve validar payloads de entrada com Bean Validation (@Valid, @NotNull, @PositiveOrZero), retornando 400 Bad Request com detalhamento das violações.
• RF-GE05: O sistema deve suportar alternância dinâmica entre banco em memória H2 (perfil dev) e PostgreSQL (perfil prod) via variáveis de ambiente.

3. Requisitos Não-Funcionais (RNF)

• RNF-GE01 (Idempotência): Operações de consulta e deleção devem ser estritamente idempotentes conforme as especificações HTTP RFC 7231.
• RNF-GE02 (Tempo de Resposta): O endpoint de busca paginada de produtos deve responder em menos de 100ms para bases de até 10.000 itens indexados por SKU.
• RNF-GE03 (Desacoplamento via DTO): As entidades de banco @Entity nunca devem ser retornadas diretamente aos clientes; todas as respostas devem trafegar via Java Records (ResponseDTO).
• RNF-GE04 (Padronização OpenAPI): Todos os endpoints devem estar documentados com anotações SpringDoc OpenAPI gerando a rota /swagger-ui.html.
• RNF-GE05 (Portabilidade de Ambiente): A suíte de build deve compilar o artefato executável .jar através do wrapper ./mvnw sem exigir instalação prévia do Maven no host.

📐 Diagrama de Casos de Uso (UML / Mermaid)

flowchart LR
    subgraph Atores
        Estoquista["👤 Estoquista"]
        Gerente["💼 Gerente de Compras"]
    end

    subgraph "Sistema de Gestão de Estoque v1"
        UC01["UC01: Cadastrar Produto com SKU"]
        UC02["UC02: Registrar Entrada de Mercadoria"]
        UC03["UC03: Registrar Baixa de Estoque"]
        UC04["UC04: Consultar Produtos em Alerta Mínimo"]
        UC05["UC05: Auditar Documentação OpenAPI"]
    end

    Estoquista --> UC01
    Estoquista --> UC02
    Estoquista --> UC03
    
    Gerente --> UC04
    Gerente --> UC05

📊 Matriz de Rastreabilidade de Requisitos (RTM)

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

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

cd catalogo_projetos/fullstack_estoque_01_spring_spa/api-spring

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

• Console do Banco H2: http://localhost:8080/h2-console (JDBC URL: jdbc:h2:mem:estoquedb).
• Documentação interativa Swagger UI: http://localhost:8080/swagger-ui.html.

2. Execução com Banco PostgreSQL via Docker Compose

cd catalogo_projetos/fullstack_estoque_01_spring_spa/api-spring

# Subida do contêiner do banco relacional
docker compose up -d

# Execução da aplicação no perfil de produção
./mvnw spring-boot:run -Dspring-boot.run.profiles=prod

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