Luckaskl/catalogo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

re estruturação do readme do projeto

Browse Source
This commit is contained in:
Luckaskl
2026-05-18 18:01:16 -05:00
parent 7669a1c77b
commit 16e410b12a
1 changed files with 75 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
readme.md
View File

@@ -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. # 🎮 API: Microsserviço de Catálogo e Metadados de Jogos
## 1. Nome do Microsserviço
**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.
## 2. Integrantes do grupo
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] [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. ### Responsabilidades do microsserviço
## 4. Responsabilidades do microsserviço * **Gerenciar o inventário:** Cadastrar, atualizar e remover jogos do catálogo.
* **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).
* **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.
* **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.
* **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.
* **Busca e Filtragem:** Permitir que outros serviços consultem jogos por critérios específicos.
## 5. Dados que o serviço precisa receber ### Dados que o serviço precisa receber
Para o cadastro ou atualização de um jogo, o serviço requer: Para o cadastro ou atualização de um jogo, o serviço requer:
* **Nome do jogo:** (String) * **Nome do jogo:** (String)
* **Descrição:** (Text/Markdown) * **Descrição:** (Text/Markdown)
* **Gêneros:** (Array de IDs ou nomes) * **Gêneros:** (Array de IDs ou nomes)
* **Plataformas:** (Array de IDs - ex: Steam, Epic, Xbox) * **Plataformas:** (Array de IDs - ex: Steam, Epic, Xbox)
* **Mídia:** (URLs de imagens de capa e galeria) * **Mídia:** (URLs de imagens de capa e galeria)
* **Desenvolvedora/Distribuidora:** (String) * **Desenvolvedora/Distribuidora:** (String)
* **Requisitos de Sistema:** (Objeto JSON com CPU, GPU, RAM mínimos e recomendados) * **Requisitos de Sistema:** (Objeto JSON com CPU, GPU, RAM mínimos e recomendados)
## 6. Dados que o serviço deve retornar
### Dados que o serviço deve retornar
Exemplo de resposta ao consultar um jogo específico: Exemplo de resposta ao consultar um jogo específico:
```json ```json
{ {
@@ -40,45 +71,31 @@ Exemplo de resposta ao consultar um jogo específico:
"active": true "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) ### Fluxo principal do serviço
Este projeto foi containerizado para facilitar a execuçã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 ### Rotas da API
- [Docker](https://www.docker.com/) e [Docker Compose](https://docs.docker.com/compose/) instalados. * `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 ### Possíveis erros
1. Execute o script na raiz do projeto: * **Jogo não encontrado:** Quando um ID inválido é solicitado.
```bash * **Título Duplicado:** Tentativa de cadastrar um jogo com nome ou slug já existente.
./run.sh * **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).
2. A aplicação FastAPI estará disponível em: http://localhost:8000 * **Incompatibilidade de Versão:** Tentativa de atualizar um jogo que foi removido ou arquivado.
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`.