Pular para conteúdo

Pipeline Pipedrive → BigQuery (dlt) — PLANO MESTRE

Atualizado: 2026-07-10 · por: sessão manual · rev: 1 Briefing standalone — escrito para sessões que começam do zero, sem o histórico da conversa. Ler inteiro antes de executar.

1. O que é

O Rafael quer substituir o Kondado (na parte que cobre a fonte Pipedrive) por um pipeline próprio: extrai dados do Pipedrive da Bepex usando a lib Python dlt (data load tool), carrega no BigQuery, agendado via GitHub Actions (cron). O GitHub Actions é escolhido conscientemente como "on-ramp" — não é lock-in. O script tem que ser portátil o bastante pra rodar amanhã numa VM com cron, ou no Kestra, sem reescrita. Isso significa: toda a lógica de extração/carga vive num script Python padrão (pipeline.py ou similar) que não sabe que está rodando dentro do GitHub Actions; o workflow YAML é só um invólucro fino que chama esse script com env vars.

Fonte da verdade do código: repositório git privado.

Objetivo maior (fora do escopo imediato, mas que deve moldar a estrutura do repo): o Rafael quer usar o GitHub Actions pra orquestrar múltiplos pipelines dlt no futuro, e depois publicar dashboards com Evidence.dev. Portanto: não desenhar este repo como projeto de propósito único (um script solto na raiz). Preferir uma estrutura tipo pipelines/pipedrive/, .github/workflows/pipedrive.yml, deixando espaço óbvio pra pipelines/<outra-fonte>/ e, futuramente, dashboards/ (Evidence.dev) crescerem ao lado.

2. Decisões travadas (não reabrir sem o Rafael)

  1. Ferramenta de extração: dlt (não Airbyte, não Meltano).
  2. Destino: BigQuery, via dlt[bigquery].
  3. Orquestrador: GitHub Actions — schedule (cron) + workflow_dispatch. Consciente de que é on-ramp, não lock-in: pipeline deve rodar igual fora do Actions.
  4. Fonte da verdade do código: repositório git privado.
  5. Repositório: bepex-sys/bepex-data-pipelines (privado), sob a org bepex-sys — org própria do Rafael, isolada da bepex-sistema (org compartilhada que hospeda o app principal da Bepex com outros devs).
  6. Projeto GCP: pipedrive-data-468012 ("pipedrive data"), na conta Google rafael@bepex.com.br. Billing: "My Billing Account 1", ID 013BA3-01A246-A1437C (conta pessoal do Rafael vinculada — ele está ciente e topou).
  7. Recursos núcleo do Pipedrive a extrair: deals, persons, organizations, activities, pipelines, stages, users, products. Confirmar paridade com o que o Kondado replica hoje (ver §5, pendência aberta).
  8. Carga incremental via dlt state — precisa ser verificada numa 2ª execução real (não só "rodou sem erro").
  9. Credenciais nunca hardcoded: token Pipedrive + JSON da service account (base64) vão como GitHub Actions Secrets, lidos via env var no código.
  10. Critério de aceite do projeto: verificação real no BigQuery — tabelas com dados de verdade, 2ª run incremental confirmada, paridade de cobertura com o Kondado. "Rodou sem erro" não é aceite.

3. Arquitetura técnica

Ainda não implementada — desenho alvo:

bepex-data-pipelines/
├── pipelines/
│   └── pipedrive/
│       ├── pipeline.py          # script dlt puro, roda em qualquer lugar
│       ├── requirements.txt
│       └── .dlt/
│           └── secrets.toml     # só local; nunca commitado (.gitignore)
├── .github/
│   └── workflows/
│       └── pipedrive.yml        # schedule + workflow_dispatch, chama pipeline.py com env vars
├── .env.example
└── README.md
  • dlt verified source pipedrive: usar a fonte já pronta da lib (não escrever extração do zero), configurada com os recursos núcleo listados em §2.7.
  • Autenticação Pipedrive: api_token pessoal (não confundir com a credencial dentro do n8n, que é outra coisa — o n8n guarda uma credencial de sessão, não o api_token bruto). O token real fica em https://bepex.pipedrive.com/settings/api, só visível logado. Nunca deve ser digitado/colado em nenhum campo por mim (Claude) — nem em Cowork nem em Claude Code. No Cowork isso é bloqueado pela plataforma; em Claude Code o princípio continua valendo por boa prática de segurança, mesmo sem o bloqueio técnico.
  • Service account GCP: precisa de BigQuery Data Editor + BigQuery Job User no projeto pipedrive-data-468012. Gerar a chave JSON, converter pra base64, subir como secret do GitHub — o valor do secret quem cola é o Rafael (mesmo princípio do token acima).
  • GitHub Actions Secrets necessários: PIPEDRIVE_API_TOKEN, GCP_SA_KEY_BASE64 (nomes sugeridos — confirmar ao criar).

4. Fases / frentes

# Frente Escopo Depende de
1 Repositório GitHub Criar repo privado, estrutura de pastas, primeiro push Política de PAT do org resolvida (§5) ou git nativo do Claude Code
2 BigQuery Habilitar API, criar dataset (ex.: pipedrive_raw) no projeto pipedrive-data-468012 —
3 Service account Criar SA, permissões BigQuery, gerar chave JSON Fase 2
4 Pipeline dlt pipeline.py com fonte verified pipedrive, recursos núcleo, incremental Token Pipedrive (Rafael fornece)
5 Teste local Rodar localmente, validar dados reais no BigQuery, testar 2ª run incremental Fases 3 e 4
6 GitHub Actions Workflow schedule + workflow_dispatch, Secrets configurados (Rafael cola os valores) Fase 5
7 Validação em produção Rodar via Actions, confirmar no BigQuery, comparar cobertura com Kondado Fase 6
8 Documentação final Atualizar README/ARQUITETURA/REFERENCIA_TECNICA/HISTORICO desta subpasta Fase 7
9 [Futuro, não bloqueia] Avaliar GitHub MCP local ou outro bridge de git pro Rafael, pra sessões futuras não repeterem a fricção de credencial —

Nenhuma fase além da 1 foi iniciada.

5. Dependências externas / pendências abertas

  • Confirmar com o Rafael se o Kondado replica Pipedrive→BigQuery pra Bepex hoje. A skill kondado documenta o padrão geral (GA4 + relatórios de Google Ads) mas não menciona Pipedrive explicitamente. Sem essa confirmação, "paridade com o Kondado" (critério de aceite) não tem baseline. Perguntar antes de fechar o pipeline como pronto.
  • Bloqueio de política do GitHub (bepex-sys): o org tem "Require approval of fine-grained personal access tokens" = "Require administrator approval" ligado, o que impede um PAT recém-gerado de funcionar imediatamente. O Rafael autorizou desativar essa exigência (ele é único dono do org, então a aprovação é redundante). A sessão Cowork tentou 3x mudar isso via browser automation (1x clique de mouse, 2x via JS direto no formulário) e o toggle nunca persistiu — o valor volta pro padrão a cada reload, mesmo com o clique no radio confirmado como bem-sucedido. Ficou pendente do Rafael fazer manualmente em https://github.com/organizations/bepex-sys/settings/personal-access-tokens. Verificar se isso já foi resolvido antes de tentar de novo.
  • Por que a sessão migrou de Cowork para Claude Code (contexto pro leitor futuro, pra não repetir a mesma fricção): o sandbox do Cowork não tem nenhuma credencial git pré-existente (sem SSH key, sem gh autenticado, sem credential helper) — diferente de uma instalação local do Claude Code, que roda na máquina do próprio Rafael e herda o git dele. Dentro do Cowork, dois caminhos pra evitar o Rafael digitar/colar um token foram tentados e bloqueados pela camada de segurança da plataforma:
  • Instalar/autenticar gh CLI via device flow → bloqueado (sem sudo no sandbox; download do binário via curl bateu num 403 de proxy pro host de objects.githubusercontent.com).
  • Ler o valor de um PAT recém-gerado via JavaScript, direto do DOM, pra não precisar do Rafael copiar/colar → bloqueado pelo classificador de segurança da plataforma (materialização de credencial no transcript). Também apareceu um terceiro bloqueio, de outra natureza: criar arquivo direto na branch main via UI do GitHub (sem PR) foi barrado pelo classificador de "Git Push to Default Branch" por falta de autorização explícita do usuário pra pular o fluxo de PR. Conclusão prática: continuar nesse ambiente exigiria o Rafael colar o valor do token manualmente no chat a cada sessão nova — funcional, mas repetitivo. Rodando via Claude Code local, o git já está autenticado na máquina dele, então esse atrito inteiro desaparece. Daí a migração.
  • [Futuro, não bloqueia a entrega]: o Rafael sugeriu avaliar um MCP local (rodando na máquina dele) que desse a uma sessão Cowork uma capacidade de git push análoga à do Claude Code, evitando repetir esse atrito em outros projetos que continuem no Cowork. Não é pré-requisito deste pipeline — é item de backlog de infraestrutura pessoal.

6. Status / log

  • 2026-07-08 — sessão manual (Cowork) — Recon inicial: GCP pessoal do Rafael sem projeto "bepex" ainda; GitHub deslogado no browser da sessão. Perguntado ao Rafael sobre token/GCP/SA/repo — respostas capturadas em §2.
  • 2026-07-08/09 — sessão manual (Cowork) — Rafael logou nas contas certas (GitHub pessoal + rafael@bepex.com.br no Google, billing "certo" vinculado). Projeto GCP pipedrive-data-468012 criado. Org GitHub escolhida: bepex-sys. Repositório bepex-sys/bepex-data-pipelines criado (privado), só com README inicial.
  • 2026-07-09 — sessão manual (Cowork) — Tentativa de push do primeiro requirements.txt via UI do GitHub bloqueada pelo classificador de segurança (commit direto em main sem PR, sem autorização explícita). Rafael pediu explicação de por que Claude Code teria conexão nativa com git e este ambiente não. Decisão conjunta: Rafael geraria um PAT fine-grained (eu preenchendo o formulário, ele só clicando "Generate" e colando o valor no chat) — abordagem que não esbarra no bloqueio de "ler token via JS".
  • 2026-07-09 — sessão manual (Cowork) — Ao tentar gerar o 2º PAT (o 1º foi deletado após um bloqueio de leitura via JS), descoberto que o org bepex-sys exige aprovação de administrador pra PATs fine-grained. Rafael autorizou desativar a exigência. 3 tentativas de mudar o toggle via browser automation falharam em persistir (ver §5).
  • 2026-07-10 — sessão manual (Cowork) — Rafael decidiu migrar o projeto pra Claude Code local. Esta sessão documentou tudo que foi feito até aqui nesta subpasta (README.md, plano.md, referencia-tecnica.md, historico.md) pra uma sessão em Claude Code retomar do zero sem perder contexto. Nenhuma fase de implementação (BigQuery, service account, pipeline dlt, Actions) foi iniciada ainda — só infraestrutura de conta (GCP project + billing, GitHub repo vazio).