StockWise API (Java)

Português

API backend em Java para gestão de produtos, estoque e pedidos, construída com Spring Boot, PostgreSQL e foco em qualidade (validação, tratamento de erros, testes e Docker).

Funcionalidades

• CRUD de produtos com paginação e filtro
• Movimentações de estoque (IN/OUT) com regra de saldo insuficiente
• Pedidos com consistência transacional (baixa/estorno de estoque)
• Autenticação JWT e rotas protegidas por role (ADMIN/USER)
• Migrações com Flyway
• Documentação via OpenAPI/Swagger
• Métricas com Actuator + Prometheus
• Testes de integração com JUnit 5 + Testcontainers

Tecnologias

Java 21, Spring Boot 3, Spring Data JPA, PostgreSQL, Flyway, Spring Security (JWT), Docker Compose, JUnit 5, Testcontainers, Micrometer/Prometheus.

Pré-requisitos

• Java 21
• Docker + Docker Compose

Como rodar

1. Suba o PostgreSQL:

docker compose up -d

2. Rode a aplicação:

./mvnw spring-boot:run

3. URLs principais:

• Swagger: http://localhost:8080/swagger-ui.html
• Healthcheck: http://localhost:8080/actuator/health
• Prometheus: http://localhost:8080/actuator/prometheus
• UI Home: http://localhost:8080/ui
• UI Produtos: http://localhost:8080/ui/products
• UI Estoque: http://localhost:8080/ui/stock

CI (GitHub Actions)

• Workflow: .github/workflows/ci.yml
• Etapas:
  • testes: ./mvnw -B -ntp test
  • build: ./mvnw -B -ntp package -DskipTests

Checklist rapido de portfolio

• Repositorio no GitHub
• Branch main
• Commit com workflow de CI
• Abrir PR para validar pipeline no historico

Auth

Usuário admin padrão:

• username: admin
• password: password

Endpoints públicos:

• POST /api/auth/register
• POST /api/auth/login

Exemplo rápido

# Login
TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"password"}' | jq -r '.token')

# Criar produto
curl -X POST http://localhost:8080/api/products \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"sku":"SKU-1","name":"Laptop","price":4999.90}'

---

English

Java backend API for products, inventory, and orders management, built with Spring Boot and PostgreSQL, with a strong focus on quality (validation, error handling, testing, and Docker).

Features

• Product CRUD with pagination and filtering
• Stock movements (IN/OUT) with insufficient stock protection
• Orders with transactional consistency (stock deduction/restock)
• JWT authentication and role-protected routes (ADMIN/USER)
• Flyway database migrations
• OpenAPI/Swagger documentation
• Actuator + Prometheus metrics
• Integration tests with JUnit 5 + Testcontainers

Tech Stack

Java 21, Spring Boot 3, Spring Data JPA, PostgreSQL, Flyway, Spring Security (JWT), Docker Compose, JUnit 5, Testcontainers, Micrometer/Prometheus.

Prerequisites

• Java 21
• Docker + Docker Compose

Running locally

1. Start PostgreSQL:

docker compose up -d

2. Run the application:

./mvnw spring-boot:run

3. Main URLs:

• Swagger: http://localhost:8080/swagger-ui.html
• Healthcheck: http://localhost:8080/actuator/health
• Prometheus: http://localhost:8080/actuator/prometheus
• UI Home: http://localhost:8080/ui
• UI Products: http://localhost:8080/ui/products
• UI Stock: http://localhost:8080/ui/stock

CI (GitHub Actions)

• Workflow: .github/workflows/ci.yml
• Steps:
  • tests: ./mvnw -B -ntp test
  • build: ./mvnw -B -ntp package -DskipTests

Quick portfolio checklist

• Repository on GitHub
• main branch
• Commit with CI workflow
• Open a PR to show CI history

Auth

Default admin user:

• username: admin
• password: password

Public endpoints:

• POST /api/auth/register
• POST /api/auth/login

Quick example

# Login
TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"password"}' | jq -r '.token')

# Create product
curl -X POST http://localhost:8080/api/products \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"sku":"SKU-1","name":"Laptop","price":4999.90}'