ykiakao/api-ranking-jogos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

reade on

Browse Source
This commit is contained in:
gabriellina640
2026-05-18 17:45:52 -05:00
parent ff3eb18954
commit 8e9211bafd
1 changed files with 217 additions and 229 deletions
Download Patch File Download Diff File Expand all files Collapse all files

446
README.md
View File

@@ -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) Microsserviço backend responsável por disponibilizar rankings e métricas de jogos para integração com o ecossistema GameVerse.
![PHP](https://img.shields.io/badge/PHP-8.2-blue)
![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) ![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**. 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.
Ele é responsável por processar, armazenar e disponibilizar estatísticas de engajamento, permitindo que a plataforma exiba rankings dinâmicos e tendências globais.
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 * Kaiky Andrade de Oliveira
* Gabriel Henrique Lina Batista Pereira Nunes * 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: * Fornecer ranking semanal, mensal e anual de jogos
* Listar os jogos mais jogados
* pontuação * Consultar histórico de pontuação de um jogo
* tempo de jogo * Filtrar rankings por plataforma
* quantidade de jogadores ativos * Retornar dados estatísticos em formato JSON
* evolução de desempenho * Proteger as rotas da API usando JWT
* Disponibilizar documentação interativa com Scribe
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.
--- ---
# 🎯 Responsabilidades do Microsserviço ## Tecnologias Utilizadas
O serviço possui as seguintes responsabilidades: * PHP >= 8.1
* Laravel 10
* 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
* SQLite * SQLite
* Composer * 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. 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 | | 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 | | Pasta | Finalidade |
| ----- | ---------- | | ----- | ---------- |
| `app/Http/Controllers` | Controllers da API | | `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 | | `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/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 | | `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 * Composer
* Git * Git
* SQLite * SQLite
--- ---
# ⚙️ Variáveis de Ambiente ## Instalação
O projeto utiliza variáveis configuradas no arquivo `.env`. Clone o repositório:
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
```bash ```bash
git clone https://github.com/gabriellina640/api-ranking-jogos.git git clone https://github.com/gabriellina640/api-ranking-jogos.git
```
## 2. Acesse a pasta do projeto
```bash
cd api-ranking-jogos cd api-ranking-jogos
``` ```
## 3. Instale as dependências Instale as dependências:
```bash ```bash
composer install composer install
``` ```
--- Crie o arquivo `.env`:
# ⚙️ Configuração do .env
Crie uma cópia do arquivo de ambiente:
```bash ```bash
cp .env.example .env 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 ```env
DB_CONNECTION=sqlite DB_CONNECTION=sqlite
``` ```
---
# 🗄️ Preparação do Banco de Dados
Execute as migrations e seeders: Execute as migrations e seeders:
```bash ```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 | Variável | Descrição |
php artisan scribe:generate | -------- | --------- |
``` | `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: Inicie o servidor Laravel:
@@ -173,213 +183,191 @@ php artisan serve
A aplicação ficará disponível em: A aplicação ficará disponível em:
```bash ```text
http://localhost:8000 http://localhost:8000
``` ```
--- ---
# 📖 Documentação Interativa da API ## Documentação da API
Após iniciar o projeto, acesse: Gere a documentação:
```bash ```bash
php artisan scribe:generate
```
Acesse:
```text
http://localhost:8000/docs http://localhost:8000/docs
``` ```
A documentação gerada pelo Scribe permite: Links auxiliares:
* visualizar endpoints | Recurso | URL |
* testar requisições | ------- | --- |
* consultar parâmetros | Documentação interativa | `http://localhost:8000/docs` |
* visualizar respostas JSON | 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 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.
* Postman
* Insomnia
* Thunder Client
Exemplo:
```http
GET http://localhost:8000/api/v1/rankings/weekly
```
--- ---
# 📑 Rotas da API ## Exemplos de Requisição
| Método | Endpoint | Descrição | Ranking semanal:
| ------ | ------------------------------------- | ---------------------------------------- |
| 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
```http ```http
GET /api/v1/rankings/weekly HTTP/1.1 GET /api/v1/rankings/weekly HTTP/1.1
Host: localhost:8000 Host: localhost:8000
Accept: application/json 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 ```json
[ [
{ {
"id": 1, "id": 1,
"name": "Elden Ring", "name": "Counter-Strike 2",
"platform": "Steam", "platform": "Steam",
"active_players": 1500000, "active_players": 1086549,
"weekly_points": 850, "weekly_points": 729,
"monthly_points": 7000, "monthly_points": 1215,
"yearly_points": 85000, "yearly_points": 71182,
"created_at": "2026-05-04T22:00:00.000000Z", "created_at": "2026-05-18T21:57:31.000000Z",
"updated_at": "2026-05-04T22:00:00.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: Observação: quando uma plataforma não possui jogos, `/api/v1/rankings/platforms/{platform}` retorna `200` com lista vazia.
* IDs de jogos
* parâmetros de filtro
* plataformas
* períodos de ranking
--- ---
## Quais dados retorna ## Testes
O serviço retorna: Execute:
* 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
```bash ```bash
app/ php artisan test
bootstrap/
config/
database/
public/
resources/
routes/
storage/
tests/
``` ```
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: Este repositório contém:
* README.md * `README.md`
* .env.example * `.env.example`
* Código-fonte completo * 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. Projeto acadêmico desenvolvido para a disciplina de Microsserviços no contexto do ecossistema 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.