# Projeto: Integração WhatsApp Business Platform

## Visão Geral
- **Objetivo**: permitir envio automático de mensagens WhatsApp diretamente pelo CRM, gatilhado por eventos (novo lead, atualização de status, lembretes), com rastreabilidade e conformidade LGPD.
- **Status**: documentação inicial concluída (vide `docs/whatsapp/README.md`); aguardando credenciais e setup de infraestrutura para iniciar implementação.

## Escopo Técnico
1. **Persistência**
   - Tabelas `whatsapp_schedules` (agendamentos) e `whatsapp_logs` (histórico de envios / status).
   - Campos extras no lead: `whatsapp_opt_in`, `whatsapp_last_contact_at`, etc.
2. **Core Services**
   - `App\Services\WhatsApp\WhatsAppClient` (REST client para Meta/BSP).
   - `WhatsAppSchedulerService` (gerencia fila de mensagens).
   - `SendScheduledWhatsAppMessagesCommand` (cron/worker).
3. **Webhook**
   - Endpoint dedicado (`WhatsAppWebhookController`) para eventos de entrega/leitura/erro.
   - Validação de assinatura/token, log detalhado e atualização do histórico do lead.
4. **Interface & Fluxos**
   - Formulário de agendamento pelo painel (leads/lembretes) com escolha de template e variáveis.
   - Visualização de histórico de mensagens dentro da timeline do lead.
   - Regras de negócio para disparos automáticos (ex.: lead novo consignado, proposta expira em X dias).

## Pré-Requisitos Externos
- Empresa verificada no Meta Business Manager.
- Número configurado na WhatsApp Business Platform ou BSP homologado.
- Templates aprovados e documentados (nome, idioma, placeholders).
- Token de acesso (cloud API) e URL pública HTTPS para webhook.
- Política/consentimento alinhados à LGPD.

## Dependências Internas
- Acesso à internet (porta 443) no servidor do CRM.
- Mecanismo de agendamento/worker (cron, queue runner).
- Logs centralizados (ex.: `storage/logs/whatsapp.log`).
- Integração com módulo de leads/lembretes já existente.

## Roadmap Proposto
1. Confirmar checklist externo (credenciais/tokens).
2. Criar migrações + modelos para agendamento/log.
3. Implementar cliente HTTP (com placeholders para tokens).
4. Construir scheduler service + comando de envio.
5. Desenvolver webhook e conectar ao histórico do lead.
6. Expor UI de agendamento e visualização.
7. Configurar feature flag e efetuar rollout controlado.
8. Validar end-to-end em sandbox antes de produção.

## Riscos & Mitigações
- **Tokens expirados**: renovar periodicamente; armazenar seguro.
- **Regras LGPD**: bloquear envio para leads sem opt-in; registrar consentimento.
- **Falhas de entrega**: re-tentar com backoff; alertar operador após N falhas.
- **Templates alterados**: versionar e sincronizar com base local para evitar inconsistências.

## Próximos Passos
- Aguardar instalação/validação das credenciais.
- Quando disponíveis, gerar branch de implementação seguindo roadmap acima.
- Integrar com pipeline de oportunidades (futuro motor de regras) para disparos inteligentes.