Desenvolvimento

Este guia irá ajudá-lo a configurar o ambiente de desenvolvimento e entender a arquitetura do projeto MINECRAFT - FGA - 2025/1.

Estrutura do Projeto

2025.1-Minecraft/
├── app/                          # Aplicação principal
│   ├── main.py                   # Ponto de entrada
│   ├── Dockerfile                # Container da aplicação
│   ├── requirements.txt          # Dependências Python
│   ├── pytest.ini               # Configuração do pytest
│   ├── run_tests.py             # Script de execução de testes
│   ├── tests/                    # Testes organizados por categoria
│   │   ├── model/                # Testes de models
│   │   │   ├── test_bioma.py
│   │   │   ├── test_chunk.py
│   │   │   └── test_mapa.py
│   │   ├── repositorio/          # Testes de repositórios
│   │   │   └── test_repository_pattern.py
│   │   ├── servicos/             # Testes de serviços
│   │   │   ├── test_integration.py
│   │   │   └── test_singleton.py
│   │   ├── utils/                # Testes de utilitários (futuro)
│   │   ├── conftest.py           # Configuração compartilhada
│   │   └── __init__.py
│   └── src/                      # Código fonte
│       ├── interface/            # Interface do usuário
│       │   └── display.py        # Menus e exibição
│       ├── services/             # Lógica de negócio
│       │   ├── game_service.py   # Serviços do jogo
│       │   └── interface_service.py # Serviços da interface
│       ├── repositories/         # Acesso a dados
│       │   ├── player_repository.py
│       │   ├── chunk_repository.py
│       │   ├── mapa_repository.py
│       │   └── bioma_repository.py
│       ├── models/               # Entidades de domínio
│       │   ├── player.py         # Modelo do jogador
│       │   ├── chunk.py          # Modelo do chunk
│       │   ├── mapa.py           # Modelo do mapa
│       │   └── bioma.py          # Modelo do bioma
│       └── utils/                # Utilitários
│           └── db_helpers.py     # Helpers do banco de dados
├── db/                           # Scripts do banco de dados
│   ├── Dockerfile.db             # Container do PostgreSQL
│   ├── ddl.sql                   # Definição das tabelas
│   ├── trigger_SP.sql            # Triggers e stored procedures
│   ├── dml.sql                   # Dados iniciais
│   ├── dml_inst.sql              # Dados de instância
│   └── create_user.sql           # Criação de usuários
├── docs/                         # Documentação
│   ├── source/                   # Arquivos fonte do Sphinx
│   ├── build/                    # Documentação gerada
│   ├── architecture.md           # Documentação da arquitetura
│   └── build_docs.sh             # Script de build
├── docker-compose.yml            # Orquestração dos containers
└── README.md                     # Documentação principal

Arquitetura

Padrão de Arquitetura

O projeto segue uma arquitetura em camadas com padrão Repository:

Interface Layer (src/interface/) * Interface com o usuário * Menus e exibição * Validação de entrada
Service Layer (src/services/) * Lógica de negócio * Coordenação entre camadas * Validações de domínio
Repository Layer (src/repositories/) * Acesso a dados * Persistência * Operações CRUD
Model Layer (src/models/) * Entidades de domínio * Validações de modelo * Lógica de negócio específica
Utils Layer (src/utils/) * Funções auxiliares * Conexão com banco * Utilitários gerais

Fluxo de Dados

Interface recebe entrada do usuário
Service processa a lógica de negócio
Repository executa operações no banco
Model representa as entidades
Interface exibe resultados

Padrão Repository

Cada repositório implementa uma interface comum:

class PlayerRepository:
    def find_all(self) -> List[Player]
    def find_by_id(self, id: int) -> Optional[Player]
    def save(self, player: Player) -> Optional[Player]
    def delete(self, id: int) -> bool
    def find_by_name(self, name: str) -> Optional[Player]

Configuração do Ambiente

Pré-requisitos

Python 3.10+
Docker e Docker Compose
Git
Editor de código (VS Code, PyCharm, etc.)

Configuração Local

Clone o repositório:

git clone https://github.com/SBD1/2025.1-Minecraft.git cd 2025.1-Minecraft
Configure o ambiente virtual:

python -m venv venv source venv/bin/activate # Linux/macOS # ou venvScriptsactivate # Windows
Instale dependências:

pip install -r app/requirements.txt
Inicie os containers:

docker-compose up -d
Execute o jogo:

python app/main.py

Desenvolvimento com Docker

Para desenvolvimento dentro do container:

Acesse o container:

docker exec -it python_mine bash
Instale dependências de desenvolvimento:

pip install sphinx sphinx-rtd-theme
Execute o jogo:

python main.py

Estrutura do Código

Módulo Models

Entidades de domínio do jogo:

# Player - Representa um jogador
class Player:
    def __init__(self, id_jogador, nome, vida_max, vida_atual, xp, forca, id_chunk_atual=None)

    def is_alive(self) -> bool
    def take_damage(self, damage: int) -> None
    def heal(self, amount: int) -> None
    def gain_xp(self, amount: int) -> None

# Chunk - Representa uma divisão do mundo
class Chunk:
    def __init__(self, numero_chunk, id_bioma, id_mapa_nome, id_mapa_turno)

# Mapa - Representa um mapa do jogo
class Mapa:
    def __init__(self, nome, turno)

# Bioma - Representa um tipo de bioma
class Bioma:
    def __init__(self, nome_bioma)

Módulo Repositories

Acesso e persistência de dados:

# PlayerRepository - Operações com jogadores
class PlayerRepository:
    def find_all(self) -> List[Player]
    def find_by_id(self, id: int) -> Optional[Player]
    def save(self, player: Player) -> Optional[Player]
    def delete(self, id: int) -> bool
    def find_by_name(self, name: str) -> Optional[Player]

# ChunkRepository - Operações com chunks
class ChunkRepository:
    def find_all(self) -> List[Chunk]
    def find_by_id(self, id: int) -> Optional[Chunk]
    def find_adjacent_chunks(self, chunk_id: int, turno: str) -> List[tuple]

# MapaRepository - Operações com mapas
class MapaRepository:
    def find_all(self) -> List[Mapa]
    def find_by_name_and_turn(self, nome: str, turno: str) -> Optional[Mapa]

# BiomaRepository - Operações com biomas
class BiomaRepository:
    def find_all(self) -> List[Bioma]
    def find_by_name(self, nome: str) -> Optional[Bioma]

Módulo Services

Lógica de negócio e coordenação:

# InterfaceService - Coordena interface com repositórios
class InterfaceService:
    def get_all_players(self) -> List[Player]
    def create_player(self, nome: str, vida_maxima: int, forca: int) -> Optional[Player]
    def save_player(self, player: Player) -> Optional[Player]
    def delete_player(self, player_id: int) -> bool
    def move_player_to_chunk(self, player: Player, chunk_id: int) -> Optional[Player]
    def get_adjacent_chunks(self, chunk_id: int, turno: str) -> List[tuple]
    def get_player_statistics(self) -> Dict[str, Any]

# GameService - Lógica específica do jogo
class GameService:
    def start_game(self, player: Player) -> bool
    def end_game(self, player: Player) -> bool
    def process_turn(self, player: Player) -> Dict[str, Any]

Módulo Interface

Interface com o usuário:

def tela_inicial():
    """Tela principal do jogo"""

def menu_inicial():
    """Menu principal com opções"""

def criar_jogador():
    """Interface de criação de personagem"""

def listar_jogadores():
    """Lista personagens em grid"""

def ver_status_detalhado():
    """Mostra informações completas do personagem"""

def trocar_jogador():
    """Interface de troca de personagem"""

def sair_jogo():
    """Encerra o jogo"""

Módulo Utils

Funções auxiliares:

def connection_db():
    """Cria conexão com PostgreSQL"""

def setup_database():
    """Configura banco antes da execução"""

def check_tables_exist():
    """Verifica se tabelas existem"""

def initialize_database():
    """Inicializa estrutura e dados"""

Padrões de Código

Convenções de Nomenclatura

Funções: snake_case (criar_jogador)
Variáveis: snake_case (current_player)
Classes: PascalCase (PlayerSession)
Constantes: UPPER_CASE (MAX_LIFE)
Módulos: snake_case (player_manager)

Documentação

Use docstrings no formato Google:

def criar_personagem(nome: str, vida_max: int = 100) -> Optional[PlayerSession]:
    """Cria um novo personagem no banco de dados.

    Args:
        nome: Nome único do personagem
        vida_max: Vida máxima (padrão: 100)

    Returns:
        PlayerSession do personagem criado ou None se erro

    Raises:
        ValueError: Se nome for inválido
    """

Tratamento de Erros

Use try/except com mensagens específicas:

try:
    conn = connection_db()
    # Operações
except psycopg2.Error as e:
    print(f"❌ Erro de banco: {e}")
except Exception as e:
    print(f"❌ Erro inesperado: {e}")
finally:
    conn.close()

Validação de Dados

Valide sempre as entradas:

def validar_nome(nome: str) -> bool:
    """Valida nome do personagem"""
    if not nome or not nome.strip():
        return False
    if len(nome) > 100:
        return False
    return True

Testes

Estrutura de Testes

O projeto possui uma estrutura completa de testes:

tests/
├── __init__.py
├── conftest.py                    # Configuração do pytest
├── test_bioma.py                  # Testes do modelo Bioma
├── test_chunk.py                  # Testes do modelo Chunk
├── test_mapa.py                   # Testes do modelo Mapa
├── test_integration.py            # Testes de integração
├── test_repository_pattern.py     # Testes do padrão Repository
└── test_singleton.py              # Testes de padrões de design

Tipos de Testes

Testes Unitários: Testam componentes isolados .. code-block:: python

def test_bioma_creation():
“””Testa criação de bioma””” bioma = Bioma(“Deserto”) assert bioma.nome_bioma == “Deserto”

def test_player_damage():
“””Testa sistema de dano””” player = Player(1, “Teste”, 100, 100, 0, 10) player.take_damage(20) assert player.vida_atual == 80

Testes de Integração: Testam interação entre camadas .. code-block:: python

def test_player_repository_integration():
“””Testa integração com banco de dados””” player = Player(1, “Teste”, 100, 100, 0, 10) saved_player = player_repository.save(player) assert saved_player is not None assert saved_player.id_jogador == 1

Testes de Padrões: Testam implementação de padrões de design .. code-block:: python

def test_repository_pattern():
“””Testa padrão Repository””” players = player_repository.find_all() assert isinstance(players, list)

Executando Testes

Organização dos Testes:

Os testes estão organizados em subpastas por categoria:

``tests/model/``: Testes de models (Player, Chunk, Mapa, Bioma)
``tests/repositorio/``: Testes de repositórios e padrão Repository
``tests/servicos/``: Testes de serviços e integração
``tests/utils/``: Testes de utilitários (preparado para futuro)

Com Docker (Recomendado): .. code-block:: bash

# Executar todos os testes docker compose exec app python -m pytest tests/ -v

# Executar com cobertura docker compose exec app python -m pytest tests/ –cov=src –cov-report=term-missing

# Executar testes por categoria docker compose exec app python -m pytest tests/model/ -v docker compose exec app python -m pytest tests/repositorio/ -v docker compose exec app python -m pytest tests/servicos/ -v

# Executar teste específico docker compose exec app python -m pytest tests/model/test_bioma.py::TestBioma::test_bioma_creation -v

# Executar testes de integração docker compose exec app python -m pytest tests/servicos/test_integration.py -v

Localmente: .. code-block:: bash

# Instalar dependências pip install -r app/requirements.txt

# Executar testes cd app python -m pytest tests/ -v

Script de Testes: .. code-block:: bash

# Usar script de execução cd app python run_tests.py

Configuração do Pytest

O projeto usa pytest.ini para configuração:

[tool:pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts =
    -v
    --tb=short
    --strict-markers
markers =
    unit: Unit tests
    integration: Integration tests
    slow: Slow running tests

Cobertura de Código

O projeto gera relatórios de cobertura:

# Gerar relatório HTML
docker compose exec app python -m pytest tests/ --cov=src --cov-report=html

# Ver relatório no navegador
open app/htmlcov/index.html

Cobertura Atual: O projeto mantém alta cobertura de código com relatórios enviados para Codecov.

Debugging

Logs

Use prints informativos para debug:

print(f"🔍 Debug: Criando personagem '{nome}'")
print(f"🔍 Debug: Dados salvos: {player.to_dict()}")

Debug no Container

# Acessar container
docker exec -it python_mine bash

# Executar com debug
python -u main.py

# Ver logs
docker-compose logs app

Debug no VS Code

Configure o launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Minecraft",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/app/main.py",
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}/app"
        }
    ]
}

Deploy e CI/CD

GitHub Actions

Configure workflows para:

Testes automáticos
Build da documentação
Deploy no GitHub Pages

name: Build Documentation
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: 3.10
      - name: Install dependencies
        run: |
          pip install sphinx sphinx-rtd-theme
      - name: Build docs
        run: |
          cd docs
          make html

Deploy Automático

Configure deploy automático no GitHub Pages:

name: Deploy to GitHub Pages
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/build/html

Versionamento

Semantic Versioning

Use o padrão MAJOR.MINOR.PATCH:

MAJOR: Mudanças incompatíveis
MINOR: Novas funcionalidades
PATCH: Correções de bugs

Changelog

Mantenha um CHANGELOG.md:

# Changelog

## [1.1.0] - 2025-01-XX
### Added
- Sistema de grid para lista de personagens
- Opção de deletar personagens

### Changed
- Melhorada interface de seleção

### Fixed
- Correção de mensagens duplicadas

Commits

Use commits semânticos:

feat: Nova funcionalidade
fix: Correção de bug
docs: Documentação
style: Formatação
refactor: Refatoração
test: Testes
chore: Tarefas de manutenção

Exemplo: feat: add character deletion functionality

Próximos Passos

Para continuar o desenvolvimento:

Contribuindo - Guia de contribuição
Referência da API - Documentação da API
Banco de Dados - Estrutura do banco