reade on
This commit is contained in:
446
README.md
446
README.md
@@ -1,61 +1,53 @@
|
||||
# 🎮 Microsserviço de Rankings de Jogos (Game Ranking API)
|
||||
# Game Ranking API
|
||||
|
||||
|
||||
|
||||
Microsserviço backend responsável por disponibilizar rankings e métricas de jogos para integração com o ecossistema GameVerse.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
# 📌 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.
|
||||
|
||||
Reference in New Issue
Block a user