← story.propek
STORY 9.20
CRM: Enriquecimento de Dados de Clientes via IA (Claude Opus)
PENDING
ACCEPTANCE CRITERIA (0/12)
**AC-1:** Script executável via `npx ts-node src/scripts/enrich-customers.ts` no servidor (dentro de `/root/propek-whatsapp-bot`)
**AC-2:** Script lê TODOS os clientes da tabela `customers` com suas mensagens via JOIN: `customers → conversations → messages`
**AC-3:** Para cada cliente, Claude Opus (`claude-opus-4-6`) analisa as mensagens concatenadas e retorna JSON estruturado com os campos extraídos (apenas o que encontrar — não inventa)
**AC-4:** Regra absoluta de classificação: CNPJ presente (encontrado nas mensagens OU já preenchido no cliente) = `customer_type: b2b`; somente CPF sem CNPJ = `customer_type: b2c`
**AC-5:** Campos extraídos pelo Claude: `contact_name`, `business_name`, `cnpj`, `cpf`, `email`, `address.cep`, `address.street`, `address.number`, `address.complement`, `address.neighborhood`, `address.city`, `address.state`, `customer_type`
**AC-6:** Script gera relatório dry-run em Markdown em `src/scripts/output/enrichment-report-{YYYY-MM-DD}.md` com tabela de todas as mudanças propostas (campo atual → campo proposto, por cliente)
**AC-7:** Mudanças só são aplicadas quando script é chamado com flag `--apply` (sem a flag, só gera o relatório)
**AC-8:** Antes de aplicar (`--apply`), script exporta backup JSON completo dos registros originais em `src/scripts/output/backup-{YYYY-MM-DD-HH-mm}.json`
**AC-9:** Log de todas as mudanças aplicadas com timestamp gravado em `src/scripts/output/enrichment-log-{YYYY-MM-DD}.md`
**AC-10:** CNPJ encontrado nas mensagens é validado via chamada interna à lógica do `cnpj-lookup` existente (função reutilizável extraída de `src/api/crm/cnpj.ts`) antes de ser salvo — se API Receita Federal retornar erro, CNPJ é salvo como encontrado mas sem validação (não bloqueia)
**AC-11:** Script não inventa dados — campos não encontrados nas mensagens são deixados como `null` no resultado (não sobrescrevem o que já existe se não há evidência)
**AC-12:** Campos já preenchidos corretamente NÃO são sobrescritos: script só preenche campos vazios (`null`/`''`) OU corrige `customer_type` quando a regra CNPJ/CPF se aplica com evidência explícita
TIMELINE
28/03/2026
chore: CRM v2 session — Stories 9.18-9.23, audits, deploy, gap analysis [Epic 9]
48ec80b