Este é o microsserviço de Catálogo de Jogos, estruturado para atender a todos os requisitos do projeto GameVerse. Ele atua como a "vitrine" do ecossistema, centralizando e gerenciando todo o inventário de títulos disponíveis na plataforma, fornecendo os dados necessários para a Loja e para a Biblioteca do Usuário.

Desenvolvido em FastAPI (Python).

🚀 Como Executar a API

Este projeto foi containerizado para facilitar a execução local utilizando Docker.

Pré-requisitos

Docker e Docker Compose instalados.

Passos para rodar

Execute o script de inicialização na raiz do projeto (ele executará docker compose up --build -d):
```
./run.sh
```
A aplicação FastAPI estará disponível na URL base: http://localhost:8000
O banco de dados PostgreSQL estará rodando internamente na porta 5432.

📚 Documentação Interativa (Swagger)

Assim que a API estiver rodando, você pode testar os endpoints e ver a documentação completa através do Swagger UI acessando: 👉 http://localhost:8000/docs

📋 Requisitos e Planejamento do Projeto

Abaixo estão as informações detalhadas sobre as responsabilidades, fluxo e arquitetura que guiaram o desenvolvimento deste serviço.

Integrantes do grupo

[Inserir nome completo de todos os integrantes aqui]

Responsabilidades do microsserviço

Gerenciar o inventário: Cadastrar, atualizar e remover jogos do catálogo.
Categorização: Administrar gêneros (RPG, FPS, Indie) e plataformas (PC, Console, Cloud).
Curadoria de Conteúdo: Armazenar descrições detalhadas, notas de patch e classificações indicativas.
Gestão de Mídia: Vincular URLs de imagens, trailers e capas aos respectivos títulos.
Busca e Filtragem: Permitir que outros serviços consultem jogos por critérios específicos.

Dados que o serviço precisa receber

Para o cadastro de um jogo (POST /api/v1/catalog/games), o serviço requer o seguinte corpo JSON. Para atualização (PATCH), os campos são opcionais.

{
  "title": "Cyber-Acre 2077",
  "description": "Um RPG de ação em um futuro distópico no norte do Brasil.",
  "genres": ["Action", "RPG"],
  "platforms": ["PC", "Linux"],
  "developer": "Acre Studio",
  "images": {
    "thumbnail": "https://cdn.gameverse.com/covers/ca2077_thumb.jpg",
    "header": "https://cdn.gameverse.com/headers/ca2077_wide.jpg"
  },
  "system_requirements": {
    "cpu": "Intel Core i7-4790K",
    "gpu": "GTX 1060 6GB",
    "ram": "12GB"
  },
  "active": true
}

Dados que o serviço deve retornar

Exemplo de resposta ao consultar um jogo específico:

{
  "success": true,
  "message": "Detalhes do jogo",
  "data": {
    "id": 8829,
    "slug": "cyber-acre-2077",
    "title": "Cyber-Acre 2077",
    "description": "Um RPG de ação em um futuro distópico no norte do Brasil.",
    "genres": ["Action", "RPG"],
    "platforms": ["PC", "Linux"],
    "developer": "Acre Studio",
    "images": {
      "thumbnail": "https://cdn.gameverse.com/covers/ca2077_thumb.jpg",
      "header": "https://cdn.gameverse.com/headers/ca2077_wide.jpg"
    },
    "system_requirements": {
      "cpu": "Intel Core i7-4790K",
      "gpu": "GTX 1060 6GB",
      "ram": "12GB"
    },
    "active": true
  }
}

Com quais serviços ele precisa se comunicar

Loja de Jogos (Storefront): Para fornecer os dados que serão exibidos ao comprador.
Biblioteca do Usuário: Para validar se o ID do jogo que o usuário possui ainda existe e está atualizado.
Busca (Search Service): Para indexar novos títulos em motores de busca como Elasticsearch.
Laravel Central/API Gateway: Para autenticação de administradores que gerenciam o catálogo.

Fluxo principal do serviço

Administrador envia uma requisição de cadastro com os dados do novo jogo.
O serviço valida se o título já existe e se todos os campos obrigatórios estão presentes.
O serviço persiste os dados no banco de dados (Gêneros, Plataformas e Dados Gerais).
O serviço emite um evento (via RabbitMQ/Kafka ou Webhook) informando que um novo jogo foi adicionado.
A Loja recebe a atualização e passa a exibir o jogo para os usuários.
O Usuário realiza uma busca e o serviço retorna a lista filtrada de jogos.

Rotas da API

Important

Consulte o Swagger UI (http://localhost:8000/docs) O Swagger é a fonte oficial da verdade para a nossa API. Recomendamos fortemente utilizá-lo para testar os endpoints de forma interativa, consultar os esquemas de requisição exatos (schemas Pydantic), ver o que é obrigatório/opcional e realizar as chamadas autenticadas facilmente configurando seu Token JWT no botão "Authorize".

Todas as rotas abaixo requerem que o cliente envie o token de acesso (Authorization: Bearer <token>):

GET /api/v1/catalog/games (Listagem com paginação e filtros)
POST /api/v1/catalog/games (Criação de novo título)
GET /api/v1/catalog/games/{id_ou_slug} (Detalhes completos de um jogo)
PATCH /api/v1/catalog/games/{id} (Atualização parcial de dados)
DELETE /api/v1/catalog/games/{id_ou_slug} (Remoção do jogo do catálogo)

Possíveis erros

Jogo não encontrado: Quando um ID inválido é solicitado.
Título Duplicado: Tentativa de cadastrar um jogo com nome ou slug já existente.
Falha na persistência de mídia: Erro ao tentar vincular links de imagens inválidos.
Dados incompletos: Envio de formulário sem campos obrigatórios (ex: sem plataforma definida).
Incompatibilidade de Versão: Tentativa de atualizar um jogo que foi removido ou arquivado.