182 lines
6.8 KiB
Markdown
182 lines
6.8 KiB
Markdown
# 🎮 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](https://www.docker.com/products/docker-desktop/) (ou Docker Engine).
|
|
* [Git](https://git-scm.com/) para clonagem do repositório.
|
|
|
|
---
|
|
|
|
## 🚀 Passo a Passo de Instalação e Execução (Via Docker)
|
|
|
|
### 1. Clonagem e Configuração do Ambiente
|
|
```bash
|
|
# 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:
|
|
```env
|
|
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:
|
|
|
|
```bash
|
|
# 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**).
|
|
1. Obtenha um Token JWT válido fornecido pela equipe de Autenticação.
|
|
2. Em todas as requisições (exceto a rota `/ping`), envie o cabeçalho de segurança:
|
|
`Authorization: Bearer <SEU_TOKEN_AQUI>`
|
|
3. 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):*
|
|
```json
|
|
{
|
|
"game_id": "jogo-cyberpunk-2077",
|
|
"is_wishlist": true,
|
|
"is_favorite": true,
|
|
"price_alert": false
|
|
}
|
|
```
|
|
*Retorno Esperado (JSON de Saída - 201 Created):*
|
|
```json
|
|
{
|
|
"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):*
|
|
```json
|
|
{
|
|
"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:
|
|
1. **Consome de:** Microsserviço de **Autenticação** (indiretamente, pois confia nos Tokens JWT gerados por eles e usa a chave pública para validar).
|
|
2. **Utilizado por:** **Laravel Central (Gateway)** e **Frontend**, que repassam as interações do usuário no site para salvar no nosso banco.
|
|
3. **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:
|
|
1. O usuário navega na loja/catálogo e clica no botão "Adicionar à Wishlist".
|
|
2. O Frontend envia a requisição para o Laravel Central (API Gateway).
|
|
3. O Gateway repassa a requisição para o nosso **Wishlist Service**, incluindo o Token JWT do usuário.
|
|
4. Nossa API valida a segurança do token e extrai o ID do usuário.
|
|
5. O serviço grava a intenção no banco de dados isolado (MySQL) e retorna a mensagem de sucesso.
|
|
6. 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* |