Salvatore/wishlist-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: finaliza documentacao completa e configuracao de ambiente

Browse Source
This commit is contained in:
Edson Salvatore
2026-05-12 12:27:13 -05:00
parent 8647c98146
commit ed40ce37ef
2 changed files with 145 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
README.md
View File

@@ -1,40 +1,55 @@
# 🎮 Gameverse - Wishlist Service
# 🎮 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. Desenvolvido com **Laravel 11**, operando em um ambiente isolado via **Docker** e protegido por autenticação **JWT (RS256)**.
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
* **Framework:** Laravel 11 (PHP 8.3)
* **Linguagem/Framework:** PHP 8.3 / Laravel 11
* **Banco de Dados:** MySQL 8.2
* **Infraestrutura:** Docker & Docker Compose (Ambiente customizado, sem dependência do Laravel Sail)
* **Segurança:** Autenticação via Token JWT (`firebase/php-jwt`)
* **Segurança:** Autenticação JWT (`firebase/php-jwt`)
* **Ambiente de Execução:** Docker e Docker Compose
---
## ⚙️ Pré-requisitos
Para rodar este microsserviço localmente, você precisará ter instalado em sua máquina:
* [Docker Desktop](https://www.docker.com/products/docker-desktop/) ou Docker Engine.
* [Git](https://git-scm.com/)
## ⚙️ 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
## 🚀 Passo a Passo de Instalação e Execução (Via Docker)
**1. Clone o repositório do Gitea:**
### 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
```
**2. Configure o ambiente:**
Crie uma cópia do arquivo de configuração base.
```bash
# Crie o arquivo de ambiente a partir do exemplo
cp .env.example .env
```
Abra o arquivo `.env` gerado e certifique-se de configurar a conexão com o banco de dados e as chaves públicas do JWT conforme fornecido pela equipe de Autenticação:
### 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
@@ -48,53 +63,120 @@ JWT_AUDIENCE="internal-apis"
JWT_PUBLIC_KEY_PEM="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
```
**3. Suba os containers do Docker:**
Este comando fará o build da imagem do PHP 8.3 com os drivers necessários e iniciará o MySQL.
### 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
```
**4. Instale as dependências do PHP:**
```bash
# Instalar dependências do Laravel dentro do container
docker compose exec app composer install
```
**5. Crie as tabelas no Banco de Dados:**
```bash
# 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
```
O servidor estará rodando e disponível em: `http://localhost:8000`
A aplicação estará acessível em: `http://localhost:8000`
---
## 🔒 Autenticação e Rotas (API)
## 🧪 Como Testar o Projeto
Todas as rotas da Wishlist são protegidas pelo middleware customizado `JwtAuthMiddleware`. O cliente deve enviar o Token JWT no cabeçalho da requisição:
`Authorization: Bearer <SEU_TOKEN_AQUI>`
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`
### Endpoints Disponíveis:
---
#### 1. Salvar ou Atualizar Jogo na Lista
* **Rota:** `POST /api/wishlist`
* **Body (JSON):**
```json
{
"game_id": "string (Obrigatório)",
"is_wishlist": "boolean (Opcional, default false)",
"is_favorite": "boolean (Opcional, default false)",
"saved_for_later": "boolean (Opcional, default false)",
"price_alert": "boolean (Opcional, default false)"
## 🔒 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
}
```
}
```
#### 2. Listar Jogos do Usuário
* **Rota:** `GET /api/wishlist`
* **Retorno:** Lista de objetos contendo os IDs dos jogos e suas respectivas flags (favorito, alerta de preço, etc) atrelados ao `auth_id` extraído do Token.
#### **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
}
]
}
```
#### 3. Remover Jogo da Lista
* **Rota:** `DELETE /api/wishlist/{game_id}`
* **Retorno:** Mensagem de sucesso confirmando a remoção do jogo da base de dados.
---
## 🔗 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*