Jokenpô API (Jogo Pedra, Papel e Tesoura)

Escolhi a opção: Jokenpô.

Tecnologias e frameworks:

• Python 3.10+
• FastAPI
• Uvicorn
• SQLite (armazenamento local)
• requests (CLI cliente)

Descrição

• API HTTP que permite criar jogadores, jogar contra a CPU (Jokenpô) e consultar histórico e placar.
• Armazenamento em SQLite (arquivo jokenpo.db no diretório do projeto).

Endpoints

1. Criar jogador

• POST /players
• Body: { "name": "Player" }
• Resposta (201): { "id": 1, "name": "Player" }

2. Jogar uma rodada (player vs CPU)

• POST /jokenpo/play
• Body: { "player_id": 1, "move": "PEDRA" }
• Resposta (200): { "player_id": 1, "player_move": "PEDRA", "cpu_move": "TESOURA", "result": "WIN", "message": "PEDRA quebra TESOURA. Você venceu!" }
• Possíveis valores para "move": "PEDRA", "PAPEL", "TESOURA" (case-insensitive)

3. Histórico de jogadas de um jogador

• GET /jokenpo/history/{player_id}
• Resposta (200): [ { "player_id": 1, "player_move": "PEDRA", "cpu_move": "TESOURA", "result": "WIN", "message": "PEDRA quebra TESOURA. Você venceu!", "played_at": "2025-11-25T12:34:56.789Z" } ]

4. Placar resumido

• GET /jokenpo/scoreboard
• Resposta (200): [ { "player_id": 1, "player_name": "Player", "wins": 3, "losses": 1, "draws": 0 } ]

Erros

• Se jogador não existir: Status: 404 Body: { "message": "Jogador com id X não encontrado." }
• Se movimento inválido: Status: 400 Body: { "message": "Movimento inválido. Use PEDRA, PAPEL ou TESOURA." }

Como rodar localmente (passo a passo)

1. Crie e ative um ambiente virtual (recomendado): python -m venv .venv source .venv/bin/activate # Linux / macOS .venv\Scripts\activate # Windows

2. Instale dependências: pip install -r requirements.txt

3. Rode a aplicação (em uma aba/terminal): uvicorn main:app --reload --host 0.0.0.0 --port 8000

   Ao subir, será criado automaticamente o arquivo SQLite jokenpo.db.

4. Use a CLI (cliente de terminal) em outra aba/terminal: python client.py

   O cliente irá mostrar um menu simples para:

   • criar jogador (nome padrão "Player" se deixar em branco)
   • escolher jogador existente
   • jogar (escolher PEDRA/PAPEL/TESOURA)
   • ver histórico do jogador
   • ver placar resumido

Acesso à documentação interativa (Swagger):

• http://localhost:8000/docs

Exemplos com curl

• Criar jogador: curl -X POST "http://localhost:8000/players" -H "Content-Type: application/json" -d '{"name":"Player"}'

• Jogar: curl -X POST "http://localhost:8000/jokenpo/play" -H "Content-Type: application/json" -d '{"player_id":1,"move":"PEDRA"}'

• Histórico: curl "http://localhost:8000/jokenpo/history/1"

• Placar: curl "http://localhost:8000/jokenpo/scoreboard"