diff --git a/README.md b/README.md index 05f2d8e..f0c3034 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,53 @@ -# 🎮 Microsserviço de Rankings de Jogos (Game Ranking API) +# Game Ranking API -![Laravel](https://img.shields.io/badge/Laravel-11-red) -![PHP](https://img.shields.io/badge/PHP-8.2-blue) +Microsserviço backend responsável por disponibilizar rankings e métricas de jogos para integração com o ecossistema GameVerse. + +![Laravel](https://img.shields.io/badge/Laravel-10-red) +![PHP](https://img.shields.io/badge/PHP-%3E%3D8.1-blue) ![SQLite](https://img.shields.io/badge/SQLite-Database-green) +![Scribe](https://img.shields.io/badge/Docs-Scribe-purple) --- -# 📌 Sobre o Projeto +## Sobre o Projeto -Este microsserviço faz parte do ecossistema **GameVerse**. -Ele é responsável por processar, armazenar e disponibilizar estatísticas de engajamento, permitindo que a plataforma exiba rankings dinâmicos e tendências globais. +Este serviço centraliza dados de engajamento de jogos e disponibiliza endpoints JSON para que um site, frontend ou outro microsserviço consiga exibir rankings dinâmicos. + +O projeto contém apenas o backend da API. A interface visual do usuário final fica em outro projeto consumidor. --- -# 👥 Integrantes +## Integrantes * Kaiky Andrade de Oliveira * Gabriel Henrique Lina Batista Pereira Nunes --- -# 📝 Descrição do Serviço +## Responsabilidades do Microsserviço -O serviço centraliza métricas de performance dos jogos, como: - -* pontuação -* tempo de jogo -* quantidade de jogadores ativos -* evolução de desempenho - -Ele resolve o problema de sobrecarga do sistema principal ao isolar o processamento de grandes volumes de dados estatísticos em um microsserviço dedicado, garantindo que as tabelas de classificação sejam atualizadas e entregues rapidamente aos usuários finais. +* Fornecer ranking semanal, mensal e anual de jogos +* Listar os jogos mais jogados +* Consultar histórico de pontuação de um jogo +* Filtrar rankings por plataforma +* Retornar dados estatísticos em formato JSON +* Proteger as rotas da API usando JWT +* Disponibilizar documentação interativa com Scribe --- -# 🎯 Responsabilidades do Microsserviço +## Tecnologias Utilizadas -O serviço possui as seguintes responsabilidades: - -* Fornecer rankings de desempenho semanal, mensal e anual -* Listar os jogos mais populares -* Exibir histórico de evolução de pontuação -* Segmentar rankings por plataforma -* Disponibilizar dados estatísticos para outros microsserviços - ---- - -# 🛠️ Tecnologias Utilizadas - -* PHP 8.2 -* Laravel 11 +* PHP >= 8.1 +* Laravel 10 * SQLite * Composer -* Laravel Scribe (Documentação OpenAPI) +* Laravel Scribe +* PHPUnit --- -# 📂 Estrutura do Repositório +## Estrutura do Repositório Este repositório não está organizado como monorepo. Ele contém apenas o microsserviço backend da API de rankings de jogos. @@ -63,88 +55,73 @@ Este repositório não está organizado como monorepo. Ele contém apenas o micr | ------- | ----- | --------- | | API de Rankings de Jogos | `/` | Backend Laravel responsável pelas rotas, autenticação JWT, rankings e documentação Scribe | -Principais pastas do serviço: +Principais pastas: | Pasta | Finalidade | | ----- | ---------- | | `app/Http/Controllers` | Controllers da API | -| `app/Http/Middleware` | Middlewares, incluindo autenticação JWT | +| `app/Http/Middleware` | Middleware de autenticação JWT | | `app/Models` | Models Eloquent | -| `routes` | Definição das rotas web e API | +| `routes/api.php` | Rotas da API | +| `routes/web.php` | Rotas web básicas | | `database/migrations` | Estrutura das tabelas | -| `database/seeders` | Dados iniciais para testes e demonstração | +| `database/seeders` | Dados iniciais para demonstração | | `resources/views/scribe` | Documentação HTML gerada pelo Scribe | -| `public/vendor/scribe` | Arquivos públicos da documentação | +| `public/vendor/scribe` | Assets públicos da documentação | +| `tests/Feature` | Testes dos endpoints e da documentação | --- -# ✅ Requisitos Necessários +## Requisitos -Antes de executar o projeto, é necessário possuir instalado: +Antes de executar o projeto, instale: -* PHP >= 8.2 +* PHP >= 8.1 * Composer * Git * SQLite --- -# ⚙️ Variáveis de Ambiente +## Instalação -O projeto utiliza variáveis configuradas no arquivo `.env`. - -Exemplo: - -| Variável | Descrição | -| ------------- | ------------------------ | -| APP_NAME | Nome da aplicação | -| APP_ENV | Ambiente da aplicação | -| APP_KEY | Chave do Laravel | -| APP_DEBUG | Modo de depuração | -| DB_CONNECTION | Banco de dados utilizado | - ---- - -# 📥 Instalação do Projeto - -## 1. Clone o repositório +Clone o repositório: ```bash git clone https://github.com/gabriellina640/api-ranking-jogos.git -``` - -## 2. Acesse a pasta do projeto - -```bash cd api-ranking-jogos ``` -## 3. Instale as dependências +Instale as dependências: ```bash composer install ``` ---- - -# ⚙️ Configuração do .env - -Crie uma cópia do arquivo de ambiente: +Crie o arquivo `.env`: ```bash cp .env.example .env ``` -Configure o banco SQLite no arquivo `.env`: +Gere a chave da aplicação: + +```bash +php artisan key:generate +``` + +Crie o banco SQLite local: + +```bash +touch database/database.sqlite +``` + +No `.env`, configure: ```env DB_CONNECTION=sqlite ``` ---- - -# 🗄️ Preparação do Banco de Dados - Execute as migrations e seeders: ```bash @@ -153,17 +130,50 @@ php artisan migrate:fresh --seed --- -# 📚 Gerar Documentação da API +## Variáveis de Ambiente -Execute o comando: +Principais variáveis usadas pelo projeto: -```bash -php artisan scribe:generate -``` +| Variável | Descrição | +| -------- | --------- | +| `APP_NAME` | Nome da aplicação | +| `APP_ENV` | Ambiente da aplicação | +| `APP_KEY` | Chave interna do Laravel | +| `APP_DEBUG` | Ativa ou desativa debug | +| `APP_URL` | URL base da aplicação | +| `DB_CONNECTION` | Driver do banco, atualmente `sqlite` | +| `JWT_ISSUER` | Emissor esperado no token JWT | +| `JWT_AUDIENCE` | Audiência esperada no token JWT | +| `JWT_PUBLIC_KEY_PEM` | Chave pública usada para validar JWT RS256 | +| `SCRIBE_AUTH_KEY` | Token usado apenas para gerar exemplos 200 na documentação | --- -# 🚀 Executando o Projeto +## Autenticação + +As rotas da API usam autenticação via JWT no padrão Bearer Token. + +Todas as requisições para os endpoints `/api/v1/*` devem enviar: + +```http +Authorization: Bearer SEU_TOKEN_JWT +Accept: application/json +``` + +O token precisa: + +* usar algoritmo `RS256` +* ter `iss` igual ao valor de `JWT_ISSUER` +* ter `aud` igual ao valor de `JWT_AUDIENCE` +* ter `sub` preenchido +* ter `exp` válido +* ter assinatura compatível com `JWT_PUBLIC_KEY_PEM` + +Sem o header `Authorization`, a API retorna `401`. + +--- + +## Executando o Projeto Inicie o servidor Laravel: @@ -173,213 +183,191 @@ php artisan serve A aplicação ficará disponível em: -```bash +```text http://localhost:8000 ``` --- -# 📖 Documentação Interativa da API +## Documentação da API -Após iniciar o projeto, acesse: +Gere a documentação: ```bash +php artisan scribe:generate +``` + +Acesse: + +```text http://localhost:8000/docs ``` -A documentação gerada pelo Scribe permite: +Links auxiliares: -* visualizar endpoints -* testar requisições -* consultar parâmetros -* visualizar respostas JSON +| Recurso | URL | +| ------- | --- | +| Documentação interativa | `http://localhost:8000/docs` | +| Collection Postman | `http://localhost:8000/docs.postman` | +| OpenAPI | `http://localhost:8000/docs.openapi` | --- -# 🧪 Como Testar o Projeto +## Rotas da API -Você pode testar a API utilizando: +| Método | Endpoint | Descrição | Autenticação | +| ------ | -------- | --------- | ------------ | +| GET | `/api/v1/rankings/weekly` | Lista o top 10 jogos por pontuação semanal | JWT | +| GET | `/api/v1/rankings/monthly` | Lista o top 10 jogos por pontuação mensal | JWT | +| GET | `/api/v1/rankings/yearly` | Lista o top 10 jogos por pontuação anual | JWT | +| GET | `/api/v1/rankings/history/{id}` | Retorna o histórico de pontuação de um jogo | JWT | +| GET | `/api/v1/rankings/platforms/{platform}` | Lista jogos filtrados por plataforma | JWT | +| GET | `/api/v1/games/most-played` | Lista o top 10 jogos por jogadores ativos | JWT | -* Scribe -* Postman -* Insomnia -* Thunder Client - -Exemplo: - -```http -GET http://localhost:8000/api/v1/rankings/weekly -``` +Existe também a rota técnica `GET /api/test-auth`, usada apenas para validar o token JWT. Ela não faz parte da documentação pública principal. --- -# 📑 Rotas da API +## Exemplos de Requisição -| Método | Endpoint | Descrição | -| ------ | ------------------------------------- | ---------------------------------------- | -| GET | /api/v1/rankings/weekly | Lista o Top 10 jogos da última semana | -| GET | /api/v1/rankings/monthly | Lista o Top 10 jogos do último mês | -| GET | /api/v1/rankings/yearly | Lista o Top 10 jogos do último ano | -| GET | /api/v1/rankings/history/{id} | Busca a evolução de pontuação de um jogo | -| GET | /api/v1/games/most-played | Lista os jogos mais jogados | -| GET | /api/v1/rankings/platforms/{platform} | Lista rankings por plataforma | - ---- - -# 📥 Exemplo de Requisição - -## Buscar ranking semanal +Ranking semanal: ```http GET /api/v1/rankings/weekly HTTP/1.1 Host: localhost:8000 Accept: application/json +Authorization: Bearer SEU_TOKEN_JWT +``` + +Ranking por plataforma: + +```http +GET /api/v1/rankings/platforms/Steam HTTP/1.1 +Host: localhost:8000 +Accept: application/json +Authorization: Bearer SEU_TOKEN_JWT +``` + +Histórico de um jogo: + +```http +GET /api/v1/rankings/history/1 HTTP/1.1 +Host: localhost:8000 +Accept: application/json +Authorization: Bearer SEU_TOKEN_JWT ``` --- -# 📤 Exemplo de Resposta JSON +## Exemplo de Resposta ```json [ { "id": 1, - "name": "Elden Ring", + "name": "Counter-Strike 2", "platform": "Steam", - "active_players": 1500000, - "weekly_points": 850, - "monthly_points": 7000, - "yearly_points": 85000, - "created_at": "2026-05-04T22:00:00.000000Z", - "updated_at": "2026-05-04T22:00:00.000000Z" + "active_players": 1086549, + "weekly_points": 729, + "monthly_points": 1215, + "yearly_points": 71182, + "created_at": "2026-05-18T21:57:31.000000Z", + "updated_at": "2026-05-18T21:57:31.000000Z" } ] ``` --- -# 🔗 Integrações com Outros Microsserviços +## Retornos Esperados -## Quais dados recebe +| Código | Situação | Exemplo | +| ------ | -------- | ------- | +| 200 | Requisição autenticada com sucesso | Lista de jogos ou histórico | +| 401 | Token ausente, inválido ou expirado | `{"message":"Missing Authorization header"}` | +| 404 | Jogo inexistente em `/rankings/history/{id}` | Resposta padrão do Laravel para model não encontrado | +| 500 | Erro inesperado no servidor | Falha interna | -O microsserviço recebe: - -* IDs de jogos -* parâmetros de filtro -* plataformas -* períodos de ranking +Observação: quando uma plataforma não possui jogos, `/api/v1/rankings/platforms/{platform}` retorna `200` com lista vazia. --- -## Quais dados retorna +## Testes -O serviço retorna: - -* rankings -* estatísticas -* histórico de pontuação -* quantidade de jogadores ativos - -Todos os dados são retornados em formato JSON. - ---- - -## Quais serviços consome - -O microsserviço consome: - -* Microsserviço de Telemetria -* Microsserviço de Catálogo de Jogos - ---- - -## Quais serviços utilizam esta API - -Os serviços que utilizam esta API são: - -* Front-end GameVerse -* Microsserviço de Loja -* Sistema de Recomendações - ---- - -# 🔄 Fluxo Principal do Serviço - -1. O usuário acessa a plataforma GameVerse -2. O Front-end solicita os rankings -3. O microsserviço consulta o banco SQLite -4. Os dados são processados e ordenados -5. O JSON é retornado ao Front-end -6. Os rankings são exibidos ao usuário - ---- - -# ⚠️ Possíveis Erros e Retornos Esperados - -| Código | Erro | Descrição | -| ------ | ---------------------- | ------------------------- | -| 400 | Dados inválidos | Parâmetros incorretos | -| 404 | Jogo inexistente | Jogo não encontrado | -| 404 | Plataforma inexistente | Plataforma não encontrada | -| 500 | Erro interno | Falha no servidor | -| 503 | Serviço indisponível | Banco indisponível | - ---- - -# 📤 Exemplo de Erro JSON - -```json -{ - "success": false, - "message": "Jogo não encontrado" -} -``` - ---- - -# 📁 Estrutura do Projeto +Execute: ```bash -app/ -bootstrap/ -config/ -database/ -public/ -resources/ -routes/ -storage/ -tests/ +php artisan test ``` +Os testes cobrem: + +* exigência de autenticação JWT +* ranking semanal, mensal e anual +* jogos mais jogados +* histórico por jogo +* filtro por plataforma +* rota técnica de teste de autenticação +* correspondência entre OpenAPI/Scribe e rotas públicas da API + --- -# 📦 Arquivos Obrigatórios da Entrega +## Integração com o Projeto Consumidor + +O site ou microsserviço consumidor deve: + +1. obter um JWT válido no serviço de autenticação do ecossistema; +2. enviar o token no header `Authorization`; +3. consumir os endpoints `/api/v1/*`; +4. tratar respostas `401` quando o token estiver ausente, inválido ou expirado. + +Este microsserviço atualmente não emite tokens. Ele apenas valida tokens JWT RS256. + +--- + +## Dados do Serviço + +Atualmente os dados são armazenados na tabela `games` e podem ser populados pelos seeders do Laravel. + +Campos principais: + +| Campo | Descrição | +| ----- | --------- | +| `name` | Nome do jogo | +| `platform` | Plataforma do jogo | +| `active_players` | Quantidade de jogadores ativos | +| `weekly_points` | Pontuação semanal | +| `monthly_points` | Pontuação mensal | +| `yearly_points` | Pontuação anual | + +--- + +## Fluxo Principal + +1. O consumidor solicita um ranking. +2. A API valida o JWT. +3. O controller consulta a tabela `games`. +4. Os dados são ordenados conforme o endpoint. +5. A resposta JSON é retornada ao consumidor. + +--- + +## Arquivos da Entrega Este repositório contém: -* README.md -* .env.example -* Código-fonte completo +* `README.md` +* `.env.example` +* código-fonte Laravel +* migrations +* seeders +* testes +* documentação Scribe gerada -⚠️ A pasta `vendor/` não deve ser enviada para o GitHub. +A pasta `vendor/` não deve ser enviada para o GitHub. --- -# 📌 Participação no Ecossistema GameVerse +## Contato -Este microsserviço é responsável por fornecer estatísticas e rankings em tempo real dentro do GameVerse. - -Ele participa diretamente: - -* das vitrines de jogos populares -* das recomendações de destaque -* dos rankings competitivos -* das estatísticas globais da plataforma - -Seu objetivo é garantir alta performance na consulta de dados estatísticos. - ---- - -# 📬 Contato - -Projeto acadêmico desenvolvido para a disciplina de Microsserviços — GameVerse. +Projeto acadêmico desenvolvido para a disciplina de Microsserviços no contexto do ecossistema GameVerse.