feat(auditoria): script CRM→ERP + relatório (R$ 10,5M de vazamento)

[Warleypablo]

🎯 TL;DR

Script one-shot que audita o funil Bitrix → ClickUp → Conta Azul em 23 categorias e gera um relatório Markdown + 23 CSVs versionados em docs/auditoria/. A primeira execução em produção encontrou R$ 10.495.223,52 de vazamento financeiro estimado nos últimos 12 meses (worst case).

Documentos de referência:

• Spec: docs/superpowers/specs/2026-04-14-auditoria-crm-erp-design.md
• Plano: docs/superpowers/plans/2026-04-14-auditoria-crm-erp.md
• Relatório: docs/auditoria/2026-04-15-auditoria-crm-erp.md

🔥 Top 5 vazamentos identificados

#	Categoria	Casos	R$ Impacto
1	Deals ganhos sem CNPJ no Bitrix	407	R$ 7.149.365
2	MRR contratado ≠ MRR cobrado	42	R$ 821.517
3	Valor pontual no Bitrix sem parcela no CAZ	80	R$ 790.152
4	Contratos encerrados com parcelas abertas (risco jurídico)	203	R$ 630.167
5	Inadimplência pós-churn > 90 dias	161	R$ 409.374

O #1 sozinho explica 68% do vazamento — 407 deals em "Negócio Ganho" no Bitrix sem CNPJ preenchido, impossibilitando o JOIN com o ERP.

📦 O que tem na diff

Código novo (scripts/auditoria/):

• auditoria-crm-erp.ts — runner principal (orquestra catalog + queries + render)
• lib/normalize-cnpj.ts, validate-cnpj.ts (módulo 11), format-currency.ts (BRL)
• lib/run-query.ts — wrapper de execução com timing + erro graceful
• lib/render-csv.ts — exporta CSV via csv-stringify/sync
• lib/render-markdown.ts — gera o relatório completo com headline, top 5, seções, ações ROI, anexo
• catalog.ts — metadados das 23 categorias
• queries/01..23-*.sql — 23 SQLs validadas em prod
• lib/__tests__/*.test.ts — 14 testes unitários (helpers)
• DISCOVERY.md — gotchas de schema descobertos durante o plan-writing

Artefatos (committed):

• docs/auditoria/2026-04-15-auditoria-crm-erp.md — relatório principal (42KB)
• docs/auditoria/2026-04-15/csv/*.csv — 23 CSVs (3.838 linhas)

Modificações:

• package.json — adiciona script `auditoria-crm-erp` + dep `csv-stringify@^6.7.0`

▶️ Como rodar

```bash
AUDITORIA_DATABASE_URL='postgresql://postgres:...@34.95.249.110:5432/dados_turbo' \
npm run auditoria-crm-erp
```

• Tempo total: ~3,5s contra prod
• Multi-empresa: Turbo Partners + PEIXOTO DEBBANE unificadas
• Janela: 12 meses + snapshot atual
• Idempotente: roda quantas vezes quiser; sobrescreve artefatos do dia
• Dry-run: `--dry-run` roda só as 3 primeiras queries pra validar setup

`AUDITORIA_DATABASE_URL` é necessário porque o `DATABASE_URL` padrão do projeto aponta pro banco local de dev.

🩺 Achados estruturais (sub-tasks de remediação sugeridas, fora deste PR)

1. CNPJ no Bitrix é o nó do problema — apenas 7,4% dos deals do CRM têm CNPJ. Tornar obrigatório no stage "Negócio Ganho".
2. `crm_deal.stage_semantic` 0,21% — bug ETL, deveria estar populado com S/F/P. Investigar pipeline de ingest do Bitrix.
3. `caz_parcelas.tipo_fatura` 100% NULL — coluna existe mas nunca foi populada.
4. 154 grupos de duplicatas no CAZ vs 17 no ClickUp — cadastro do CAZ é 9× mais bagunçado.
5. 1011 "CNPJs malformados" — em sua maioria são CPFs em campo CNPJ. Erro de cadastro sistêmico.
6. 322 clientes ativos no ClickUp sem deal correspondente no Bitrix — comissionamento órfão de origem desconhecida.
7. DATABASE.md está desatualizado — falta documentar colunas reais de `crm_deal` (`cnpj`, `valor_recorrente`, `valor_pontual`, `closer`, `sdr`, etc.).

⚠️ Caveats e limitações (também documentadas no anexo do relatório)

• Estimativas são teto worst case, não previsão. Cada caso precisa ser validado individualmente antes de virar planilha de cobrança.
• Cat 12 tem 1 row de noise: o CNPJ da própria Turbo Partners aparece 6× porque está em ambas as empresas do CAZ. Filtrar manualmente do top.
• Cat 16 (nomes divergentes) tem alta taxa de falso positivo — abreviações vs nomes legais.
• Cat 08 (reajustes não refletidos) marcada como exploratória — pode vir com falsos positivos altos. Retornou 0 nesta execução.
• Pipelines do Bitrix além de 0 e 12 ficaram fora por escopo.
• Auditoria de despesas (`tipo_evento='DESPESA'`) está fora — escopo é receita.

✅ Test plan

• Helpers TS: `npx vitest run scripts/auditoria/lib/tests/` → 14/14 passando
• Smoke test dry-run: `npm run auditoria-crm-erp -- --dry-run` → 3 queries executam, exit 0
• Execução completa em prod: 23/23 queries executam sem erro, 3,5s wall time
• Sanity check manual: validados casos individuais das categorias 01, 05, 12 (top rows fazem sentido)
• Sem regressão: PR só adiciona arquivos novos sob `scripts/auditoria/` e `docs/auditoria/`, modifica apenas `package.json` (adiciona 1 script + 1 dep)
• Validação humana de 3 casos das categorias com maior impacto antes de pautar como ação:
  • Cat 01: abrir 5 dos 407 deals sem CNPJ no Bitrix e confirmar
  • Cat 05: abrir 3 dos 457 contratos cup ativos sem recorrente e confirmar via Conta Azul
  • Cat 09: confirmar 3 dos 203 casos de "cobrando após encerramento" (risco jurídico)

🤖 Generated with Claude Code