Files

Edson Salvatore ed40ce37ef docs: finaliza documentacao completa e configuracao de ambiente

2026-05-12 12:27:13 -05:00

6.8 KiB

Raw Permalink Blame History

🎮 Gameverse - Wishlist Service (Microsserviço de Lista de Desejos)

Este é o microsserviço responsável pelo gerenciamento de Favoritos e Listas de Desejos (Wishlist) dos usuários no ecossistema Gameverse. O serviço permite que os jogadores salvem jogos de interesse, marquem favoritos e configurem alertas de preço.

👥 Integrantes do Grupo

Edson Oliveira
Mateus Lima

📝 Descrição do Serviço

O Wishlist Service atua como o motor de engajamento do Gameverse. Ele resolve o problema da retenção de interesse do usuário, permitindo que ele armazene sua intenção de compra ou preferência por títulos do catálogo de forma segura e personalizada.

⚙️ Responsabilidades do Microsserviço

Gerenciamento de Intenção: Cadastrar, atualizar e remover jogos da lista de desejos.
Segmentação de Preferências: Diferenciar entre itens da "Wishlist", "Favoritos", "Salvar para depois" e "Alerta de Preço".
Isolamento de Dados: Garantir que cada usuário acesse e modifique apenas a sua própria lista.
Segurança: Validar a autenticidade das requisições via tokens JWT (RS256).

🛠️ Tecnologias Utilizadas

Linguagem/Framework: PHP 8.3 / Laravel 11
Banco de Dados: MySQL 8.2
Segurança: Autenticação JWT (firebase/php-jwt)
Ambiente de Execução: Docker e Docker Compose

⚙️ Requisitos Necessários

Para rodar este microsserviço localmente, você precisará ter instalado:

Docker Desktop (ou Docker Engine).
Git para clonagem do repositório.

🚀 Passo a Passo de Instalação e Execução (Via Docker)

1. Clonagem e Configuração do Ambiente

# Clone o repositório
git clone https://git.juancjc.com.br/Salvatore/wishlist-service.git
cd wishlist-service

# Crie o arquivo de ambiente a partir do exemplo
cp .env.example .env

2. Configuração do `.env`

Abra o arquivo .env recém-criado e certifique-se de que os dados do banco e as chaves de segurança estão corretos:

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=gameverse_wishlist
DB_USERNAME=root
DB_PASSWORD=root

JWT_ISSUER="https://sistema-distribuido-trabalho-faculd.vercel.app"
JWT_AUDIENCE="internal-apis"
JWT_PUBLIC_KEY_PEM="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"

3. Como Executar o Projeto

O projeto utiliza containers para isolar a aplicação (porta 8000) e o banco de dados (porta 3306). No terminal, na raiz do projeto, rode:

# Subir os containers (Build e Start)
docker compose up -d --build

# Instalar dependências do Laravel dentro do container
docker compose exec app composer install

# Gerar chave da aplicação e rodar as Migrations (cria as tabelas no MySQL)
docker compose exec app php artisan key:generate
docker compose exec app php artisan migrate

A aplicação estará acessível em: http://localhost:8000

🧪 Como Testar o Projeto

Para testar as rotas da API, utilize ferramentas como Postman, Insomnia ou o terminal (cURL / Invoke-RestMethod).

Obtenha um Token JWT válido fornecido pela equipe de Autenticação.
Em todas as requisições (exceto a rota /ping), envie o cabeçalho de segurança: Authorization: Bearer <SEU_TOKEN_AQUI>
Para requisições POST/PUT, certifique-se de enviar também: Accept: application/json e Content-Type: application/json

🔒 Rotas da API

Método	Endpoint	Descrição
GET	`/api/ping`	Teste de conectividade da API (Rota Pública)
POST	`/api/wishlist`	Cria ou atualiza as preferências de um jogo na lista
GET	`/api/wishlist`	Busca a lista de jogos salvos pelo usuário logado
DELETE	`/api/wishlist/{game_id}`	Remove um jogo específico da lista de desejos

Exemplos de Requisição e Resposta (JSON)

POST /api/wishlist (Criação/Atualização)

Corpo da Requisição (JSON de Entrada):

{
  "game_id": "jogo-cyberpunk-2077",
  "is_wishlist": true,
  "is_favorite": true,
  "price_alert": false
}

Retorno Esperado (JSON de Saída - 201 Created):

{
  "message": "Jogo salvo na lista com sucesso!",
  "data": {
    "user_id": "auth-uuid-123",
    "game_id": "jogo-cyberpunk-2077",
    "is_wishlist": true,
    "is_favorite": true,
    "price_alert": false,
    "updated_at": "2026-05-12T10:00:00.000000Z",
    "created_at": "2026-05-12T10:00:00.000000Z",
    "id": 1
  }
}

GET /api/wishlist (Listagem)

Retorno Esperado (JSON de Saída - 200 OK):

{
  "data": [
    {
      "id": 1,
      "user_id": "auth-uuid-123",
      "game_id": "jogo-cyberpunk-2077",
      "is_wishlist": 1,
      "is_favorite": 1,
      "saved_for_later": 0,
      "price_alert": 0
    }
  ]
}

🔗 Integrações com Outros Microsserviços

Este serviço trabalha de forma desacoplada, mas comunica-se no ecossistema da seguinte forma:

Consome de: Microsserviço de Autenticação (indiretamente, pois confia nos Tokens JWT gerados por eles e usa a chave pública para validar).
Utilizado por: Laravel Central (Gateway) e Frontend, que repassam as interações do usuário no site para salvar no nosso banco.
Fornece para: Futuro Microsserviço de Notificações, que precisará consultar quais usuários possuem a flag price_alert: true para disparar e-mails promocionais.

Fluxo Principal no Gameverse:

O usuário navega na loja/catálogo e clica no botão "Adicionar à Wishlist".
O Frontend envia a requisição para o Laravel Central (API Gateway).
O Gateway repassa a requisição para o nosso Wishlist Service, incluindo o Token JWT do usuário.
Nossa API valida a segurança do token e extrai o ID do usuário.
O serviço grava a intenção no banco de dados isolado (MySQL) e retorna a mensagem de sucesso.
A interface do usuário é atualizada mostrando o item como salvo.

⚠️ Possíveis Erros e Retornos Esperados

Caso algo saia do fluxo ideal, a API retornará os seguintes erros:

Usuário não autorizado (Erro 401): Token ausente, expirado, com assinatura inválida ou gerado por um issuer incorreto.
- Retorno: {"message": "Missing or invalid Authorization header"}
Dados inválidos (Erro 422): O cliente tenta salvar sem enviar o campo obrigatório game_id.
- Retorno: Erro de validação padrão do Laravel listando os campos faltantes.
Jogo não encontrado na lista (Erro 404): O usuário tenta remover da wishlist um jogo que não consta em seu banco de dados.
- Retorno: {"message": "Jogo não encontrado na sua lista."}
Serviço Indisponível (Erro 500): O banco de dados do container caiu ou a API perdeu comunicação interna.

Centro Educacional UniNorte - Projeto Gameverse

6.8 KiB Raw Permalink Blame History