Ir para o conteúdo

Guia de Inicialização

Este guia irá auxiliá-lo a configurar o ambiente de desenvolvimento local para o Onboarding Hub.

Pré-requisitos

Para rodar este projeto localmente, garanta que você tenha instalado:

  1. Docker: Necessário para subir os bancos de dados locais e os tópicos do Kafka.
  2. UV: O gerenciador moderno de pacotes, ambientes e execução do Python utilizado no projeto.

Configuração do Repositório

1. Inicializar o Ambiente Virtual e Dependências

Execute os comandos a seguir para sincronizar o interpretador Python, criar o ambiente virtual (.venv) e registrar as ferramentas de qualidade de código no git (pre-commit):

# Sincroniza pacotes e cria o .venv
uv sync --extra dev --extra docs

# Registra os hooks do pre-commit
uv run pre-commit install

# Cria o arquivo de configuração local de ambiente
cp .env.example .env

[!NOTE] Se o comando uv não estiver no seu PATH no Windows, utilize python -m uv no lugar.

2. Subir os Serviços Locais (Docker)

O repositório possui arquivos Docker Compose modulares sob a pasta infra/ para que você suba apenas o que for usar no momento:

docker compose -f infra/docker-compose.yml up -d
Isso disponibilizará uma instância do PostgreSQL local na porta padrão 5432.

docker compose -f infra/docker-compose-kafka.yml up -d
Isso inicia uma fila do Kafka via Redpanda com Console Web disponível na porta 8090.

docker compose -f infra/docker-compose-airflow.yml up -d
Inicia uma instância leve do Airflow na porta 8080 (credenciais padrão: admin / admin).

3. Gerar Massa de Testes (Dados Sintéticos)

Após subir o banco de dados PostgreSQL, popule-o com cadastros sintéticos (gerados dinamicamente contendo dados sujos simulando falhas de conformidade):

uv run python scripts/seed.py

Comandos Úteis

O utilitário uv run garante a execução imediata dos scripts isoladamente dentro do ambiente virtual do projeto.

Desenvolvimento e Testes

  • Gerar mais registros sintéticos: 
    uv run python scripts/seed.py --records 5000
  • Regenerar o contrato de JSON Schema: 
    uv run python scripts/export_contract.py
  • Executar os testes unitários: 
    uv run pytest

Qualidade de Dados (Soda Core)

Valida se as linhas inseridas no banco de dados local violam regras do contrato de onboarding: 

uv run soda scan -d amazonia_postgres -c data_quality/soda/configuration.yml data_quality/soda/checks/onboarding_checks.yml

Qualidade de Código (Lint, Formatação e Tipos)

  • Análise estática de erros de estilo e bugs (Ruff): 
    uv run ruff check .
  • Formatação automática do código (Ruff): 
    uv run ruff format .
  • Checagem estática de tipos (Mypy): 
    uv run mypy src