🚀 Onboarding — Guia para Novos Devs¶

Guia rápido para quem está começando a contribuir no Datalake Lavoro.

📋 Pré-Requisitos¶

Ferramentas Obrigatórias¶

Ferramenta	Uso	Instalação
Python 3.10+	Desenvolvimento de DAGs	python.org
Docker Desktop	Airflow local via Docker Compose	docker.com
Git	Controle de versão	git-scm.com
gcloud CLI	Autenticação e interação com GCP	cloud.google.com/sdk
VS Code	IDE recomendada	code.visualstudio.com

Extensões VS Code Recomendadas¶

Python + Pylance
SQL Formatter
YAML
Docker
GitLens

Acessos Necessários¶

Solicite ao Tech Lead antes de começar

Você precisará dos acessos abaixo. Solicite via Jira ou diretamente ao Tech Lead do projeto.

Acesso	O que permite	Como solicitar
GitHub	Clone e push nos repositórios	Convite para a org via GitHub
GCP Console	Acesso ao BigQuery, Composer e VMs	IAM via Service Account ou convite
BigQuery	Consulta e validação de dados	Role `BigQuery Data Viewer` + `Job User`
Cloud Composer	Visualização das DAGs em produção	Role `Composer User`
Airflow (DEV/QA)	Acesso às VMs de desenvolvimento	SSH via gcloud ou IAP Tunnel
Jira	Gestão de tarefas e sprints	Convite pelo gestor

🏗️ Setup do Ambiente Local¶

1. Clone o repositório¶

# Escolha o repositório do projeto que irá trabalhar
git clone git@github.com:platformbuilders/lavoro-lakehouse.git
cd lavoro-lakehouse

Repositórios ativos (sob a organização github.com/LavoroAgro):

Repositório	Conteúdo	Composer
`LavoroAgro/lavoro-lakehouse`	DAGs, operators, hooks e templates SQL dos 4 projetos (Lakehouse, CDP, Operações, Pessoas)	Composer Lakehouse
`LavoroAgro/lavoro-iac`	Infraestrutura como código (Terraform)	—

Repositórios históricos

Os repositórios lavoro-cdp, lavoro-operacoes, lavoro-tesouraria e lavoro-pessoas existem apenas como histórico — todo o código foi consolidado em lavoro-lakehouse.

2. Configure as credenciais GCP¶

# Autentique no GCP
gcloud auth login
gcloud auth application-default login

# Defina o projeto
gcloud config set project <ID_DO_PROJETO_GCP>

3. Suba o Airflow local com Docker¶

cd docker
docker-compose up -d

O Airflow estará disponível em http://localhost:8080 (user: airflow / senha: airflow).

4. Valide que está funcionando¶

# Verifique se os containers estão rodando
docker ps

# Acesse o webserver e veja as DAGs carregadas
# http://localhost:8080

📂 Estrutura de um Repositório¶

lavoro-{projeto}/
├── dags/                          # DAGs do Airflow
│   ├── config/
│   │   └── project_params.py      # Configuração de ambientes (DEV/QA/PROD)
│   ├── task_groups/
│   │   ├── bronze/                # Tasks de ingestão
│   │   │   ├── *.py
│   │   │   └── sql/               # Queries SQL da camada Bronze
│   │   ├── silver/                # Tasks de transformação
│   │   │   ├── *.py
│   │   │   └── sql/               # Queries SQL da camada Silver
│   │   └── gold/                  # Tasks de consumo
│   │       ├── *.py
│   │       └── sql/               # Queries SQL da camada Gold
│   └── dag_*.py                   # Definições dos DAGs
├── docker/
│   └── docker-compose.yml         # Ambiente local
├── .github/
│   └── workflows/                 # CI/CD (GitHub Actions)
└── README.md

🔄 Fluxo de Trabalho¶

Ciclo de Desenvolvimento¶

graph LR
    A[Nova Task no Jira] --> B[Branch LBI-XXXX]
    B --> C[Desenvolve no DEV]
    C --> D[Testa localmente]
    D --> E[Push para branch qa]
    E --> F[Valida no QA]
    F --> G[PR para main]
    G --> H[Code Review]
    H --> I[Merge → Deploy PROD]

    style A fill:#e3f2fd
    style I fill:#e8f5e9

Padrões de Branch e Commit¶

Padrão	Formato	Exemplo
Branch	`LBI-XXXX/descricao-curta`	`LBI-9917/fix-fato-pedido`
Commit	`LBI-XXXX: descrição`	`LBI-9917: ajuste no JOIN de carteira`

Deploy Automático¶

Branch	Destino	Tipo
`qa`	VM Airflow QA	Automático (GitHub Actions)
`main`	Cloud Composer (Prod)	Automático (GitHub Actions)

🎯 Primeiro Dia — O que Fazer¶

Checklist do primeiro dia

Siga esta ordem para se ambientar rapidamente.

Peça os acessos (GitHub, GCP, Jira, BigQuery)
Clone o repositório do projeto que vai trabalhar
Suba o Airflow local e veja as DAGs existentes
Leia esta documentação — especialmente Arquitetura e Convenções
Explore o BigQuery — navegue pelos datasets (bronze, silver, gold)
Escolha uma task simples no Jira e comece a contribuir

📖 Leitura Recomendada¶

Leia nesta ordem para entender o ecossistema:

Arquitetura Técnica — visão geral do Medallion Architecture
Convenções de Dados — padrões de nomenclatura e estrutura
Orquestração (Airflow) — como os pipelines funcionam
Qualidade de Dados — validações com Soda
Glossário — termos técnicos

📅 Atualizado em Março 2026