From ed40ce37ef6bb227639cbe4221c7c5d91ae881c4 Mon Sep 17 00:00:00 2001 From: Edson Salvatore Date: Tue, 12 May 2026 12:27:13 -0500 Subject: [PATCH] docs: finaliza documentacao completa e configuracao de ambiente --- .env.example | 35 ++++------ README.md | 180 +++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 145 insertions(+), 70 deletions(-) diff --git a/.env.example b/.env.example index c0660ea..d14dfcb 100644 --- a/.env.example +++ b/.env.example @@ -1,17 +1,14 @@ -APP_NAME=Laravel +APP_NAME=WishlistService APP_ENV=local APP_KEY= APP_DEBUG=true -APP_URL=http://localhost +APP_URL=http://localhost:8000 -APP_LOCALE=en +APP_LOCALE=pt_BR APP_FALLBACK_LOCALE=en APP_FAKER_LOCALE=en_US APP_MAINTENANCE_DRIVER=file -# APP_MAINTENANCE_STORE=database - -# PHP_CLI_SERVER_WORKERS=4 BCRYPT_ROUNDS=12 @@ -20,12 +17,13 @@ LOG_STACK=single LOG_DEPRECATIONS_CHANNEL=null LOG_LEVEL=debug -DB_CONNECTION=sqlite -# DB_HOST=127.0.0.1 -# DB_PORT=3306 -# DB_DATABASE=laravel -# DB_USERNAME=root -# DB_PASSWORD= +# Configurações do Banco de Dados para o Docker +DB_CONNECTION=mysql +DB_HOST=mysql +DB_PORT=3306 +DB_DATABASE=gameverse_wishlist +DB_USERNAME=root +DB_PASSWORD=root SESSION_DRIVER=database SESSION_LIFETIME=120 @@ -36,9 +34,7 @@ SESSION_DOMAIN=null BROADCAST_CONNECTION=log FILESYSTEM_DISK=local QUEUE_CONNECTION=database - CACHE_STORE=database -# CACHE_PREFIX= MEMCACHED_HOST=127.0.0.1 @@ -56,10 +52,7 @@ MAIL_PASSWORD=null MAIL_FROM_ADDRESS="hello@example.com" MAIL_FROM_NAME="${APP_NAME}" -AWS_ACCESS_KEY_ID= -AWS_SECRET_ACCESS_KEY= -AWS_DEFAULT_REGION=us-east-1 -AWS_BUCKET= -AWS_USE_PATH_STYLE_ENDPOINT=false - -VITE_APP_NAME="${APP_NAME}" +# Variáveis da Fechadura JWT (Chaves de Segurança do Grupo 1) +JWT_ISSUER="https://sistema-distribuido-trabalho-faculd.vercel.app" +JWT_AUDIENCE="internal-apis" +JWT_PUBLIC_KEY_PEM="-----BEGIN PUBLIC KEY-----\nCOLE_AQUI_A_CHAVE_FORNECIDA\n-----END PUBLIC KEY-----" \ No newline at end of file diff --git a/README.md b/README.md index 727ae6a..82589c4 100644 --- a/README.md +++ b/README.md @@ -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 ` +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 ` +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* \ No newline at end of file