Roadmap e Gaps Conhecidos¶

Atualizado: 2026-06-02

Branch atual: develop / staging

Este documento lista pendencias tecnicas, melhorias planejadas e debitos tecnicos conhecidos da aplicacao.

Pendencias por Prioridade¶

🔴 Alta Prioridade¶

1. Validacao HMAC do Webhook Meta¶

Status: Bloqueado, aguardando META_APP_SECRET do cliente Highlas

Impacto: Seguranca. Sem HMAC, terceiros podem injetar webhooks falsos na aplicacao.

Tarefas: - [ ] Receber META_APP_SECRET do cliente - [ ] Adicionar variavel em .env.example - [ ] Criar decorator @verify_meta_signature em whatsapp/views.py - [ ] Aplicar no meta_webhook - [ ] Testar com payloads validos e invalidos

Estimativa: 30min apos receber a secret

Referencia: diretrizes-meta.md#gap-1

🟡 Media Prioridade¶

2. Cooldown de Reenvio Apos Expiracao¶

Status: Nao iniciado

Impacto: Quality rating WhatsApp + custo de templates Meta

Cenario: hoje, assim que uma run expira, o operador pode disparar nova pesquisa imediatamente para o mesmo contato. Em massa, isso pode degradar reputacao e gerar gastos.

Tarefas: - [ ] Adicionar constante SURVEY_REUSE_COOLDOWN_DAYS (default 7) - [ ] Em start_survey, verificar se ha run expired/opt_out recente - [ ] Retornar payload estruturado com error_code='recent_expiration_cooldown' - [ ] Atualizar UX no frontend para mostrar quando podera reenviar - [ ] Adicionar testes unitarios

Estimativa: 1h

3. Tratamento de Codigos de Erro Especificos da Meta¶

Status: Nao iniciado

Impacto: Acoes automaticas mais inteligentes em vez de logs genericos

Codigos mais relevantes: - 131026 (mensagem nao entregavel) -> mark_as_expired() + flag no Contact - 131047 (re-engagement needed) -> mark_as_expired() - 131056 (pair rate limit) -> retry com backoff

Tarefas: - [ ] Parsear response do requests.exceptions.HTTPError em meta_graph_service.py - [ ] Extrair error.code do JSON - [ ] Mapear codigos -> acoes em uma funcao helper - [ ] Adicionar campo is_unreachable em Contact para 131026

Estimativa: 1-2h

🟢 Baixa Prioridade¶

4. Opt-out por Palavra-Chave¶

Status: Nao iniciado

Impacto: Conformidade adicional para templates MARKETING

Tarefas: - [ ] Detectar palavras-chave em survey_service.process_incoming_message - [ ] Lista: PARAR, STOP, CANCELAR, SAIR, DESCADASTRAR - [ ] Adicionar campo Contact.opted_out_at - [ ] Bloquear envios em start_survey se contact opted out - [ ] Adicionar coluna "Opt-out" na tela de contatos

Estimativa: 1-2h

5. Alerta de Quality Rating Baixo¶

Status: Nao iniciado

Impacto: Visibilidade operacional, evitar surpresas com bloqueio

Tarefas: - [ ] Adicionar handler para webhook account_update em meta_webhook - [ ] Persistir ultimo phone_number_quality_update no banco (tabela MetaAccountStatus) - [ ] Disparar email para admin se rating <> 'GREEN' - [ ] Exibir badge no header do frontend se rating baixo

Estimativa: 2-3h

6. Notificacao de Janela 24h Estourada Durante in_progress¶

Status: Nao iniciado

Cenario: cliente comeca pesquisa, demora > 24h para responder a proxima pergunta. Hoje fica em limbo ate a regra C expirar.

Tarefas: - [ ] Capturar error 131047 em meta_graph_service.send_message() - [ ] Marcar a run como expired imediatamente com meta={'expired_reason': 'window_closed'} - [ ] Log estruturado

Estimativa: 1h

Melhorias Tecnicas (Nao Funcionais)¶

Performance¶

• Cache de Contact por phone (Redis, 5min) - reduz queries em hot path de webhook
• Pre-calcular get_expiry_info() em annotation no list endpoint para evitar N queries

Observabilidade¶

• Adicionar metricas Prometheus para:
• Taxa de SIM/NAO ao convite
• Taxa de abandono no meio do fluxo
• Tempo medio de resposta entre perguntas

• Webhooks recebidos vs processados com sucesso

• Sentry para erros nao capturados em producao

Testes¶

• Cobertura atual ~40% (estimativa). Meta: 75%+
• Adicionar testes E2E para:
• Fluxo completo de pesquisa (criacao -> SIM -> respostas -> conclusao)
• Expiracao automatica em todas as 3 regras
• Opt-out via botao

Documentacao¶

• docs/tecnico/index.md
• docs/tecnico/expiracao-pesquisas.md
• docs/tecnico/diretrizes-meta.md
• docs/tecnico/roadmap-gaps.md (este arquivo)
• docs/tecnico/arquitetura-geral.md
• docs/tecnico/modelo-dados.md
• docs/tecnico/integracao-meta.md
• docs/tecnico/tarefas-periodicas.md
• docs/tecnico/backup-restauracao.md

Bugs Conhecidos (Nao Criticos)¶

Nenhum no momento. Bugs criticos historicos:

• ✅ Problema do "9" do celular BR no webhook (fix: feat/survey-expiration predecessor)
• ✅ sent_at nao preenchido em envio imediato (fix: fix/sent-at-on-immediate-send)
• ✅ Condicionais perdidas ao salvar pesquisa (fix em frontend/src/components/surveys/SurveyEditClient.tsx)
• ✅ Webhook bloqueado durante limpeza do banco (fix: validacao com variantes de phone)
• ✅ Token Meta expirado nao recarregado pelo Celery (fix: docker compose up -d --force-recreate)

Decisoes Arquiteturais Pendentes¶

A. Manter Evolution API como fallback?¶

O codigo ainda tem evolution_webhook ativo em whatsapp/views.py, mesmo que o sistema atual use exclusivamente Meta Graph API.

Opcoes: 1. Remover Evolution API completamente (simplifica codigo) 2. Manter como fallback para clientes futuros sem WABA aprovado 3. Manter mas desativar o endpoint (so reativa se necessario)

B. Versionamento da API¶

Hoje todos os endpoints estao em /api/v1/. Quando introduzirmos breaking changes, precisaremos /api/v2/. Vale planejar a estrategia de coexistencia (header X-API-Version?).

C. Filas Celery Separadas¶

Hoje toda task usa fila celery (default). Para producao mais robusta: - Fila whatsapp para tasks que falam com Meta (rate limited) - Fila analytics para tasks pesadas (calculo de metricas) - Fila default para o resto

Como Atualizar este Documento¶

Quando uma pendencia for endereçada: 1. Marque o item com [x] 2. Mova para a secao "Bugs Conhecidos > Bugs criticos historicos" se aplicavel 3. Atualize a data no topo do documento 4. Mencione o commit/PR nos detalhes