PrivaKit API (Priv@Kit) — Backend

Backend (API REST) do PrivaKit / Priv@Kit, um e-commerce de kits de servidores domésticos focados em privacidade (ex.: NAS, Firewall, HomeLab).

Links rápidos:

• Produção: https://privakit.onrender.com (frontend em manutenção)
• Health check: /healthz
• OpenAPI (dev): /q/openapi
• Swagger UI (dev): /q/swagger-ui
• Dev UI (dev): /q/dev-ui

Idioma: 🇧🇷 Português | 🇺🇸 English (README.en.md)

Visão geral

A API fornece:

• Autenticação via JWT (login)
• Controle de acesso por perfis (ADMIN e USER)
• Catálogo público (vitrine)
• Checkout (criação de pedido) com pagamento simulado
• Rotas administrativas para gerenciamento (catalogo/pedidos/usuários)
• Em caso de erro, a API retorna status HTTP apropriado e uma mensagem.

Observação:

• Os endpoints REST da API usam os prefixos /api e /auth

Stack

• Java 21 LTS
• Quarkus
• JAX-RS (REST)
• Hibernate ORM + Panache
• PostgreSQL
• Bean Validation
• SmallRye JWT
• OpenAPI / Swagger (Quarkus)

Como rodar localmente (dev)

Pré-requisitos:

• Java 21 instalado
• PostgreSQL rodando localmente

1. Configure seu banco PostgreSQL

   • Database: ecommerce
   • User: topicos1
   • Password: definida por variável de ambiente (ver abaixo)

2. Configure variáveis de ambiente (dev) A aplicação lê a senha do banco via env var no perfil dev.

   Exemplos:

   PowerShell: $env:DEV_DB_PASSWORD="sua_senha_aqui"

   Bash: export DEV_DB_PASSWORD="sua_senha_aqui"

   (Opcional) Se você tiver seed de admin via env var no seu projeto: DEV_ADMIN_PASSWORD="..."

3. Rode em modo dev: ./mvnw quarkus:dev

4. Acesse:

• API: http://localhost:8080
• Ao abrir http://localhost:8080 no navegador, você será redirecionado automaticamente para a Dev UI: /q/dev-ui/extensions

Configuração de Produção (Render)

Em produção (Render), as variáveis usadas são:

• DATABASE_URL
• DB_USER
• DB_PASSWORD
• JWT_PRIVATE_KEY
• JWT_PUBLIC_KEY

Base URL em produção:

• https://privakit.onrender.com

Autenticação (JWT)

• Issuer: unitins-jwt
• Expiração: 7 dias
• Perfis (roles) no claim groups: ADMIN e USER

Como autenticar:

1. Faça login em: POST /auth/login

2. Use o token retornado nas rotas protegidas: Header: Authorization: Bearer <SEU_TOKEN>

Endpoints públicos (sem token)

• GET /healthz

• POST /auth/login

• POST /api/usuarios/pub

• GET /api/faq

• GET /api/faq/{id}

• GET /api/estados/{id}

• GET /api/kits/public

• GET /api/kits/public/page

• GET /api/kits/public/{id}

• GET /api/kits/{id}

• GET /api/produtos

• GET /api/produtos/{id}

Paginação e busca

Paginação:

• O parâmetro page é 0-based (primeira página = 0) nos endpoints paginados.
• pageSize controla o tamanho da página.

Busca:

• Kits: suporte a search para buscar por nome (em rotas públicas e privadas).
• Produtos: suporte a search (quando aplicável).

Catálogo: Kits

A entidade principal do e-commerce é o Kit.

Campos do Kit (principais):

• nome (obrigatório)
• preco (obrigatório)
• idCategoria (obrigatório)
• estoque (obrigatório)
• descricao
• descricaoLonga
• informacoesTecnicas
• imageUrl
• produtos (List) — vínculo com itens internos/auxiliares quando aplicável

Rotas públicas:

• GET /api/kits/public Lista pública (sem paginação).

• GET /api/kits/public/page?page=0&pageSize=6&search=... Lista pública paginada (com search).

• GET /api/kits/public/{id} Detalhe público do kit.

• GET /api/kits/{id} Busca por id (permitida publicamente no seu backend).

Rotas privadas (exigem token):

• GET /api/kits?page=0&pageSize=10&search=... Lista paginada (ADMIN/USER).

Rotas administrativas (ADMIN):

• POST /api/kits
• PUT /api/kits/{id}
• DELETE /api/kits/{id}

Categorias

Rotas (geral):

• GET /api/categorias
• GET /api/categorias/{id}

Rotas administrativas (ADMIN):

• POST /api/categorias
• PUT /api/categorias/{id}
• DELETE /api/categorias/{id}

Usuários

Cadastro público:

• POST /api/usuarios/pub

Usuário logado:

• GET /api/usuarios/me
• PUT /api/usuarios/senha

Admin (ADMIN):

• GET /api/usuarios?page=0&pageSize=10
• GET /api/usuarios/{id}
• POST /api/usuarios
• PUT /api/usuarios/{id}
• DELETE /api/usuarios/{id}

Pedidos (checkout)

Criação de pedido:

• POST /api/pedidos Requer token (USER/ADMIN).

Estrutura do body (exemplo):

{
    "itens": [
        { "idKit": 1, "quantidade": 2 }
    ],
    "enderecoEntrega": {
        "rua": "...",
        "numero": "...",
        "complemento": "...",
        "bairro": "...",
        "cidade": "...",
        "estado": "...",
        "cep": "..."
    },
    "pagamento": {
    "formaPagamento": "PIX",
    "chavePix": "...",
    "numeroCartao": "...",
    "nomeTitular": "...",
    "validade": "...",
    "cvv": "...",
    "codigoDeBarras": "...",
    "linhaDigitavel": "..."
    }
}

Status do pedido:

• PENDENTE
• PAGO
• ENVIADO
• CANCELADO

Rotas típicas:

• GET /api/pedidos?page=0&pageSize=10 (ADMIN)
• GET /api/pedidos/usuario (USER/ADMIN) — “meus pedidos”
• PUT /api/pedidos/{id}/status (ADMIN)

Estados

• GET /api/estados?page=0&pageSize=10 (protegido, quando aplicável)
• GET /api/estados/{id} (público)

Admin (ADMIN):

• POST /api/estados
• PUT /api/estados/{id}
• DELETE /api/estados/{id}

FAQ

Público:

• GET /api/faq
• GET /api/faq/{id}

Admin (ADMIN):

• POST /api/faq
• PUT /api/faq/{id}
• DELETE /api/faq/{id}

Produtos (rotas existentes)

A API possui rotas para “produtos” disponíveis publicamente:

• GET /api/produtos
• GET /api/produtos/{id}

Essas rotas existem no backend e podem ser usadas como suporte/estrutura auxiliar, enquanto o fluxo principal do e-commerce se concentra na vitrine e compra de Kits.

Exemplos rápidos (cURL)

1. Login

   curl -X POST http://localhost:8080/auth/login \
   -H "Content-Type: application/json" \
   -d '{"email":"seu_email","senha":"sua_senha"}'
   

2. Listar kits públicos paginados

   curl "http://localhost:8080/api/kits/public/page?page=0&pageSize=6&search=nas"
   

3. Criar pedido (substitua TOKEN)

   curl -X POST http://localhost:8080/api/pedidos \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer TOKEN_AQUI" \
   -d '{
   "itens":[{"idKit":1,"quantidade":1}],
   "enderecoEntrega":{
   "rua":"Rua A","numero":"123","complemento":"Casa",
   "bairro":"Centro","cidade":"Palmas","estado":"TO","cep":"77000-000"
   },
   "pagamento":{"formaPagamento":"PIX","chavePix":"email@pix.com"}
   }'
   

Estrutura do projeto

Padrão de pacotes (camadas):

• br.unitins.topicos1.model (Entidades JPA e enums)
• br.unitins.topicos1.dto (DTOs)
• br.unitins.topicos1.repository (Repositórios Panache)
• br.unitins.topicos1.service (Regras de negócio)
• br.unitins.topicos1.resource (Endpoints REST)

Licença: MIT