Kachau Store API

Backend REST API para a loja virtual Kachau Store, desenvolvido com Quarkus.

Demonstração ao vivo

• API: https://kachau-backend.onrender.com/
• Frontend: https://kachau.zernis.space/

Repositórios

• Frontend: https://github.com/Aiard0/kachau-frontend
• Backend: https://github.com/Aiard0/kachau-backend

---

Stack

Tecnologia	Propósito
Quarkus 3.39.1	Framework Java natif cloud-first
Java 21	Linguagem de programação
Hibernate ORM/Panache	ORM com abstração de acesso a dados
PostgreSQL	Banco de dados relacional
SmallRye JWT	Autenticação e autorização com JWT
Resend API	Envio de e-mails transacionais (HTML templates)
Maven	Gerenciamento de dependências e build
Docker	Containerização da aplicação
Render	Hospedagem (PaaS)

---

Funcionalidades

• Autenticação de usuários (login/cadastro) com JWT
• Gerenciamento de produtos (CRUD)
• Gerenciamento de pedidos e itens de pedido
• Checkout direto com cálculo automático de total
• Envio de e-mails transacionais (boas-vindas, confirmação de pedido)
• Validação de dados com Bean Validation
• DTOs como Java Records (imutáveis)
• Exceptions específicas para erros HTTP (404, 401)
• Templates HTML para e-mails
• Restrições de e-mail único por usuário

---

Estrutura do Projeto

src/main/java/br/zernis/kachau/
├── dto/
│   ├── auth/                    # DTOs de autenticação
│   │   ├── LoginDTO.java        # Record
│   │   ├── LoginResponseDTO.java # Record
│   │   └── RegisterDTO.java     # Record
│   ├── checkout/                # DTOs de checkout
│   │   ├── CheckoutDTO.java     # Record
│   │   └── CheckoutItemDTO.java # Record
│   ├── order/                   # DTOs de pedido
│   │   ├── OrderResponseDTO.java # Record
│   │   └── OrderItemResponseDTO.java # Record
│   └── user/
│       └── UserResponseDTO.java  # Record
├── entity/                      # Entidades JPA
│   ├── User.java
│   ├── Product.java
│   ├── Order.java
│   └── OrderItem.java
├── exception/                    # Exceções customizadas
│   ├── NotFoundException.java
│   └── NotAuthorizedException.java
├── repository/                   # Repositórios Panache
│   ├── UserRepository.java
│   ├── ProductRepository.java
│   ├── OrderRepository.java
│   └── OrderItemRepository.java
├── resource/                    # REST Resources (endpoints)
│   ├── AuthResource.java
│   ├── UserResource.java
│   ├── ProductResource.java
│   ├── OrderResource.java
│   └── CheckoutResource.java
├── service/                     # Lógica de negócio
│   ├── AuthService.java
│   ├── UserService.java
│   ├── ProductService.java
│   ├── OrderService.java
│   ├── CheckoutService.java
│   ├── MailService.java
│   └── GenerateToken.java
└── utils/
    └── GenerateToken.java       # Utilitário para gerar JWT

---

Começando

Pré-requisitos

• Java 21
• Maven 3.9+
• PostgreSQL 15+ (ou Docker)

Instalação

# Clone o repositório
git clone https://github.com/Aiard0/kachau-backend
cd kachau-backend

# Compile o projeto
./mvnw compile

Desenvolvimento

# Inicie o modo dev (com hot-reload)
./mvnw quarkus:dev

# A aplicação estará disponível em http://localhost:8080

Build

# Build para produção (JAR nativo ou JVM)
./mvnw package

# Build com skiptests
./mvnw package -DskipTests

---

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto ou configure no ambiente:

# Banco de dados
DB_USERNAME=seu_usuario
DB_PASSWORD=sua_senha
DB_NAME=kachau

# JWT
JWT_ISSUER=https://kachau.zernis.space/
JWT_PUBLIC_KEY_LOCATION=publicKey.pem

# Resend (e-mail)
RESEND_API_KEY=re_xxxxxxxxxxxx

# Aplicação
APP_BASE_URL=https://kachau-backend.onrender.com

Variável	Descrição	Padrão
DB_USERNAME	Usuário do banco PostgreSQL	postgres
DB_PASSWORD	Senha do banco PostgreSQL	postgres
DB_NAME	Nome do banco de dados	kachau
QUARKUS_DATASOURCE_JDBC_URL	URL JDBC completa do banco	jdbc:postgresql://localhost:5432/kachau
JWT_ISSUER	Emissor esperado do JWT	—
JWT_PUBLIC_KEY_LOCATION	Caminho para chave pública RSA	publicKey.pem
RESEND_API_KEY	Chave da API Resend	—
APP_BASE_URL	URL base da aplicação (para e-mails)	—

---

Deploy

Render (Recomendado)

O backend está hospedado no Render como Web Service.

1. Conecte seu repositório GitHub ao Render
2. Configure as variáveis de ambiente na dashboard do Render
3. O Render detecta automaticamente builds Quarkus/Maven
4. Deploy automático a cada push na branch main

Branch de produção: main

Docker

A aplicação pode ser containerizada com Docker:

# Build da imagem Docker (JVM mode)
docker build -t kachau-backend .

# Ou usando Docker Compose com PostgreSQL
docker-compose up -d

Registrar imagem no GitHub Container Registry:

# Login no GHCR
echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin

# Build e tag
docker build -t ghcr.io/aiard0/kachau-backend:latest .

# Push
docker push ghcr.io/aiard0/kachau-backend:latest

---

Qualidade de Código

SonarCloud

O projeto é analisado pelo SonarCloud para garantir qualidade de código.

Métrica	Status
Bugs	0
Vulnerabilidades	0
Code Smells	Minimizados
Coverage	Verificado

A análise é executada automaticamente a cada PR e push na branch main através do GitHub Actions.

---

API Endpoints

Método	Caminho	Descrição	Auth Required
POST	/login	Autenticar usuário	Não
POST	/register	Cadastrar novo usuário	Não
GET	/test	Endpoint protegido (role: user)	Sim (JWT)
GET	/users	Listar todos os usuários	Não
GET	/users/{id}	Obter usuário por ID	Não
GET	/products	Listar todos os produtos	Não
GET	/products/{id}	Obter produto por ID	Não
POST	/products	Criar novo produto	Não
GET	/orders	Listar todos os pedidos	Não
GET	/orders/{id}	Obter pedido por ID	Não
GET	/orders/buyer/{buyerId}	Obter pedidos do comprador	Não
POST	/checkout/buyer/{buyerId}	Criar pedido (checkout)	Não

---

Scripts Maven

Comando	Descrição
./mvnw compile	Compilar o projeto
./mvnw test	Executar testes
./mvnw package	Criar artefato JAR
./mvnw quarkus:dev	Iniciar modo desenvolvimento (hot-reload)
./mvnw quarkus:build	Build nativo (se Quarkus Native habilitado)

---

Tecnologias Detalhadas

SmallRye JWT

JWTs são assinados com RSA-256. A aplicação:

• Valida tokens JWT no header Authorization: Bearer <token>
• Extrai roles dos tokens para controle de acesso
• Gera tokens no login com expiração de 24h

Hibernate ORM Panache

Repository pattern com Panache:

• Queries reativas e simplificadas
• Suporte a transacciones
• Timestamps automáticos (@CreationTimestamp, @UpdateTimestamp)

Resend API

E-mails transacionais em HTML:

• Boas-vindas (welcome.html): Enviado após registro
• Confirmação de pedido (order-confirmation.html): Enviado após checkout

---

Licença

Este é um projeto público, utilizado para um teste, use-o como quiser.