From 16e410b12a68f33737e7e9994301460d56178ba9 Mon Sep 17 00:00:00 2001 From: Luckaskl Date: Mon, 18 May 2026 18:01:16 -0500 Subject: [PATCH] =?UTF-8?q?re=20estrutura=C3=A7=C3=A3o=20do=20readme=20do?= =?UTF-8?q?=20projeto?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- readme.md | 133 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 75 insertions(+), 58 deletions(-) diff --git a/readme.md b/readme.md index 64cd4d3..a774292 100644 --- a/readme.md +++ b/readme.md @@ -1,26 +1,57 @@ -Este é um planejamento detalhado para o microsserviço de **Catálogo de Jogos**, estruturado para atender a todos os requisitos do projeto GameVerse. -## 1. Nome do Microsserviço -**Microsserviço de Catálogo e Metadados de Jogos** -## 2. Integrantes do grupo +# 🎮 API: Microsserviço de Catálogo e Metadados de Jogos + +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](https://www.docker.com/) e [Docker Compose](https://docs.docker.com/compose/) instalados. + +### Passos para rodar +1. Execute o script de inicialização na raiz do projeto (ele executará `docker compose up --build -d`): + ```bash + ./run.sh + ``` +2. A aplicação FastAPI estará disponível na URL base: **http://localhost:8000** +3. 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](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] -## 3. Objetivo do microsserviço -O objetivo deste serviço é centralizar e gerenciar todo o inventário de títulos disponíveis na plataforma GameVerse. Ele atua como a "vitrine" do ecossistema, resolvendo o problema de fragmentação de informações sobre os jogos. Sem ele, o sistema não teria uma fonte única de verdade para descrições, requisitos técnicos ou categorização. Ele é fundamental porque fornece os dados necessários para que a **Loja** exiba produtos e para que a **Biblioteca do Usuário** saiba exatamente o que o jogador adquiriu. -## 4. 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. -## 5. Dados que o serviço precisa receber + +### 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 ou atualização de um jogo, o serviço requer: - * **Nome do jogo:** (String) - * **Descrição:** (Text/Markdown) - * **Gêneros:** (Array de IDs ou nomes) - * **Plataformas:** (Array de IDs - ex: Steam, Epic, Xbox) - * **Mídia:** (URLs de imagens de capa e galeria) - * **Desenvolvedora/Distribuidora:** (String) - * **Requisitos de Sistema:** (Objeto JSON com CPU, GPU, RAM mínimos e recomendados) -## 6. Dados que o serviço deve retornar +* **Nome do jogo:** (String) +* **Descrição:** (Text/Markdown) +* **Gêneros:** (Array de IDs ou nomes) +* **Plataformas:** (Array de IDs - ex: Steam, Epic, Xbox) +* **Mídia:** (URLs de imagens de capa e galeria) +* **Desenvolvedora/Distribuidora:** (String) +* **Requisitos de Sistema:** (Objeto JSON com CPU, GPU, RAM mínimos e recomendados) + +### Dados que o serviço deve retornar Exemplo de resposta ao consultar um jogo específico: ```json { @@ -40,45 +71,31 @@ Exemplo de resposta ao consultar um jogo específico: "active": true } } - ``` -## 7. 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. -## 8. Fluxo principal do serviço - 1. **Administrador** envia uma requisição de cadastro com os dados do novo jogo. - 2. O serviço **valida** se o título já existe e se todos os campos obrigatórios estão presentes. - 3. O serviço **persiste** os dados no banco de dados (Gêneros, Plataformas e Dados Gerais). - 4. O serviço **emite um evento** (via RabbitMQ/Kafka ou Webhook) informando que um novo jogo foi adicionado. - 5. A **Loja** recebe a atualização e passa a exibir o jogo para os usuários. - 6. O **Usuário** realiza uma busca e o serviço retorna a lista filtrada de jogos. -## 9. Rotas iniciais da API - * GET /api/v1/catalog/games (Listagem com paginação e filtros de gênero/plataforma) - * POST /api/v1/catalog/games (Criação de novo título - Restrito a Admin) - * GET /api/v1/catalog/games/{id_ou_slug} (Detalhes completos de um jogo específico) - * PATCH /api/v1/catalog/games/{id} (Atualização parcial de dados como descrição ou imagens) -## 10. 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. -# DEVE SER FEITO EM FAST API (python) +### 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. -## 11. Como Executar (Docker) -Este projeto foi containerizado para facilitar a execução. +### Fluxo principal do serviço +1. **Administrador** envia uma requisição de cadastro com os dados do novo jogo. +2. O serviço **valida** se o título já existe e se todos os campos obrigatórios estão presentes. +3. O serviço **persiste** os dados no banco de dados (Gêneros, Plataformas e Dados Gerais). +4. O serviço **emite um evento** (via RabbitMQ/Kafka ou Webhook) informando que um novo jogo foi adicionado. +5. A **Loja** recebe a atualização e passa a exibir o jogo para os usuários. +6. O **Usuário** realiza uma busca e o serviço retorna a lista filtrada de jogos. -### Pré-requisitos -- [Docker](https://www.docker.com/) e [Docker Compose](https://docs.docker.com/compose/) instalados. +### Rotas da API +* `GET /api/v1/catalog/games` (Listagem com paginação e filtros de gênero/plataforma) +* `POST /api/v1/catalog/games` (Criação de novo título - Restrito a Admin) +* `GET /api/v1/catalog/games/{id_ou_slug}` (Detalhes completos de um jogo específico) +* `PATCH /api/v1/catalog/games/{id}` (Atualização parcial de dados como descrição ou imagens) -### Passos -1. Execute o script na raiz do projeto: - ```bash - ./run.sh - ``` -2. A aplicação FastAPI estará disponível em: http://localhost:8000 -3. A documentação interativa (Swagger UI) pode ser acessada em: http://localhost:8000/docs -4. O banco de dados PostgreSQL estará rodando internamente na porta `5432`. \ No newline at end of file +### 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. \ No newline at end of file