feat(connector): HubSpot/CRM — Fase 0 do caminho Madruga (trial-to-buy)

[FabioLeitao]

Contexto

Origem: FOCUS_PATH_madruga_2026-07-05.md (vault, sessão de 05/07) — decisão do operador já tomada, nunca virou artefato rastreável no repo até hoje (13/07). Traduzindo fielmente o spec já escrito, sem inventar nada novo.

Objetivo de negócio: converter o trial do design-partner Madruga/MTIS em contrato assinado. HubSpot é o primeiro conector escolhido especificamente pra fechar esse trial — não é R&D genérico.

Regra de corte já definida: só entra no escopo o que responde SIM a "o trial do Madruga precisa disso?" ou "isso é o que faz ele assinar?". Google Workspace, Databricks, session-diff ficam explicitamente fora por enquanto (Fase 1, só se o trial pedir).

Tarefa — Fase 0 (mínimo vendável)

1. connectors/hubspot_connector.py

Seguir o padrão já existente (docs/ADDING_CONNECTORS.md) — extensão limpa, não reinvenção:

• Classe HubSpotConnector
• __init__(self, target_config, scanner, db_manager, sample_limit=5)
• connect() — cliente REST HubSpot a partir do target_config (private app token injetado, nunca no config commitado)
• run() — para cada object type (contacts/companies/deals): ler object properties, tratar cada propriedade como "coluna", amostrar valores → scanner.scan_column(prop_name, sample) → db_manager.save_finding(...)
• close() — encerra o cliente
• Registrar via register("hubspot", HubSpotConnector, ["name","type"]) + ramo em connector_for_target() pra type: hubspot
• API: REST /crm/v3/objects/{contacts|companies|deals} com properties=, paginação via after, rate limit respeitado
• Least privilege: private app token, escopo read-only, zero write

2. Garantir que HubSpot alimenta o Excel/heatmap existente

Reuso do output já existente, não construir novo relatório.

3. Fixtures sintéticas do cenário HubSpot

Gerador sintético BR (CPF com dígito válido em custom field), simulando o cenário real — nunca dado real do Madruga em repo/issue/commit/fixture.

Disciplina de dado real (inegociável, do próprio spec)

• Scan roda no ambiente do Madruga; só o manifesto (metadata) sai
• Nenhum dado real dele em repo/issue/commit/fixture
• Papéis LGPD: Madruga/MTIS = controlador; Data Boar = operador sob instrução

Cross-referência

#697 ([P2][Pro] PLAN_DPO_COMPLIANCE_SCORE_REPORT.md — compliance grade A+→F) é chamado de "o argumento de venda" no mesmo spec — versão mínima dele faz parte do mesmo caminho de fechamento, tratar como issue irmã, não parte desta.

Explicitamente fora de escopo aqui (Fase 1, só se o trial pedir)

Databricks connector, Google Workspace auditor, session diff/drift — não implementar agora.

Critério de aceite

• connectors/hubspot_connector.py implementado seguindo o padrão de ADDING_CONNECTORS.md
• Registrado no connector_registry
• HubSpot alimentando o Excel/heatmap existente
• Fixtures sintéticas (CPF válido em custom field), zero dado real
• Least-privilege confirmado (token read-only, zero write)
• PR referencia esta issue (Closes #<N>)

[FabioLeitao]

Correção importante (operador, 2026-07-13)

Google Workspace não é condicional como o vault sugeria ("Fase 1, só se o trial pedir") — o Madruga já verbalizou essa dor em pessoa, na reunião de apresentação do Data Boar 1.7.4-post2 com --demo. Junto com HubSpot, os dois já foram pedidos reais, não hipóteses.

Google Workspace (Docs, Drive, Gemini) vira issue própria, cross-referenciada aqui — API/modelo de auth diferente (OAuth Google vs private app token HubSpot), mais limpo rastrear separado.

Referência de origem pra quem for laborar (não reelaborar do zero):
p:/notes/obsidian_vault/databoar-commercial/ai-sessions/fable-opus-max-audit-2026-07-05/FOCUS_PATH_madruga_2026-07-05.md
(mesma pasta: SESSION_GUIDE_AND_SEEDS_2026-07-05.md, VERIFIED_LAYERS_2026-07-05.md como contexto adicional)

[FabioLeitao]

Cross-link

Google Workspace (Docs, Drive, Gemini) — mesma dor real, mesmo caminho-Madruga — virou issue própria: #1230