Replan — Data lake do WhatsApp resistente a falhas

Data: 2026-06-12 · Origem: sessão grill-me (Clinton × Claude) Escopo: dois repos — wpp-tui (Collector / branch feat/whatsapp-collector) e he4rt-bot-api módulo integration-whatsapp (branch feat/integration-whatsapp-ingest). Substitui: plano 0001-ingest-implementation.md e a spec.md histórica. Decisão de arquitetura: este plano motiva um ADR-0003 que supersede partes do ADR-0002.

1. Contexto

Por que replanejar

O objetivo foi reescrito: um data lake dos dados importantes do WhatsApp, resistente a falhas (nenhum evento importante se perde). A análise de 2026-06-07 e a re-análise de 2026-06-11 expuseram que o desenho vigente (ADR-0002) tem dois pilares que contradizem esse objetivo:

1. event_id aleatório (randomUUID()) — decisão do ADR-0002 que o Clinton reconheceu como erro. Ela desarma a dedup na origem (INSERT OR IGNORE virou inerte) e faz re-emits do Baileys (reconexão, append, re-snapshot de groups.metadata) virarem linhas duplicadas no lake. O ADR chamou isso de "raro"; o código prova que é recorrente (toda reconexão).
2. Ingest assíncrono (job + 202 antes de persistir) — sob QUEUE_CONNECTION=redis (prod), o 202 é dado antes da gravação. Se o job falhar, o evento some em failed_jobs e o bot já apagou do outbox → perda silenciosa. Hoje mascarado por QUEUE_CONNECTION=sync, mas prod será Redis.

Some-se a isso o poison payload (�/UTF-8 inválido que o Postgres recusa no jsonb), eventos de grupo descartados por bug de extração de JID, e o outbox sem dead-letter (retry eterno em falha permanente).

Estado atual (arquivos afetados)

Bot (wpp-tui):

• src/collector/outbox.ts — event_id = randomUUID() (:47); INSERT OR IGNORE inerte.
• src/collector/extractors.ts — envelope enxuto {type,chat_jid,payload}; sem event_id determinístico.
• src/collector/event-router.ts — denylist + filtro @g.us.
• src/collector/webhook-sender.ts — markSent em qualquer res.ok; sem classificação de erro; sem timeout.
• src/hooks/use-socket.ts — router.handleEvent para todo evento (:185); groups.metadata re-emitido a cada open (:203,405).
• src/retention.ts — poda logs, não o outbox.

Backend (integration-whatsapp):

• src/Ingest/Http/Controllers/WhatsAppWebhookController.php — dispatch(job) + 202.
• src/Ingest/Jobs/ProcessWhatsAppEvent.php — firstOrCreate(event_id); Tries(3)/Backoff.
• src/Ingest/Http/Middleware/VerifyWhatsAppSignature.php — HMAC só do corpo; exige Str::isUuid.
• database/migrations/...whatsapp_event_logs... — event_id uuid UNIQUE, payload jsonb.

Constraints travados na sessão

• 🔒 Prod = Redis (async).
• 🔒 Governança/LGPD fora deste ciclo.
• 🔒 event_id volta a determinístico.
• 🔒 Filosofia: bot o mais burro possível dentro do necessário para montar a chave; backend guarda cru.

2. As 10 decisões

3. O novo contrato (ponta a ponta)

WhatsApp ──► bot captura ──► outbox (event_id DETERMINÍSTICO = PK)
                               │   • INSERT OR IGNORE → dedup na ORIGEM
                               │   • durável: segura o evento até confirmar gravação
                               ▼ (sender, background)
   POST /api/webhooks/whatsapp
   Headers: X-Event-Id (UUIDv5),  X-Signature = HMAC(`${eventId}.${rawBody}`)
   Body: { type, chat_jid, payload }   ← CRU
                               ▼
   middleware: valida HMAC(eventId+body) + UUID
                               ▼
   controller → Action: sanitiza payload → firstOrCreate(event_id) SÍNCRONO → commit
                               ▼
   2xx só após commit ──► bot markSent (apaga do outbox)   ← dedup no DESTINO
                          5xx/rede → retry · 401 → retry+alerta · 422 → dead-letter

Dupla proteção de idempotência: dedup na origem (INSERT OR IGNORE no outbox) e no destino (firstOrCreate + UNIQUE).

Chave determinística por tipo (UUIDv5)

senderTimestampMs da reação não entra na chave — é instável entre re-emissões (visto nos logs: mesma 😂 com 3 timestamps distintos). "canônico" (D9) = JSON com chaves ordenadas, participantes ordenados por id, campos voláteis (timestamps de subject, etc.) removidos antes do hash.

4. Comportamento esperado (BDD)

Idempotência — re-emit (happy path do objetivo):

• Dado uma mensagem key.id=M já no lake, Quando o Baileys reentrega M num append de reconexão, Então o event_id é idêntico → INSERT OR IGNORE ignora no bot (nem chega na rede) → nenhuma linha nova.

Idempotência — retry HTTP:

• Dado um item enviado mas cuja resposta se perdeu, Quando o bot reenvia o mesmo item, Então firstOrCreate no backend não cria duplicata.

Mudança de estado preservada:

• Dado uma reação 😂 de um usuário numa mensagem, Quando ele troca para ☕, Então o event_id difere (emoji na chave) → nova linha; a timeline 😂→☕ fica completa.

Ingest síncrono sob Redis:

• Dado prod com Redis, Quando o evento chega, Então o controller grava antes de responder e o 2xx significa "persistido"; E Quando o DB está fora, Então responde 5xx, o bot não apaga do outbox e re-tenta (sem perda).

Poison payload:

• Dado um payload com �, Quando chega no ingest, Então o backend sanitiza, grava em jsonb e responde 2xx (não trava, não perde, não duplica).

Falha permanente:

• Dado um item que o backend rejeita com 422, Quando o sender recebe, Então move para outbox_dead (preservado, fora do loop) + alerta — a fila ativa não entope.
• Dado segredo dessincronizado (401), Quando todo item falha, Então o bot mantém os itens e alerta (não descarta nada).

Bug corrigido (não perder dado importante):

• Dado um group.member-tag.update (JID em groupId), Quando chega ao extractor, Então o JID é resolvido por it.groupId → não é mais descartado silenciosamente.

Compatibilidade:

• A tabela whatsapp_event_logs não muda de schema (event_id uuid UNIQUE comporta UUIDv5). Linhas antigas (com event_id random) coexistem; a dedup determinística só vale daqui pra frente.

5. Antes/depois (trechos-chave)

Bot — outbox.enqueue volta a receber o event_id determinístico:

- enqueue(body) {
-   const eventId = randomUUID()
-   insert.run(eventId, body.type, JSON.stringify(body), now, now)
- }
+ enqueue(event) {                       // { event_id, body }
+   insert.run(event.event_id, event.body.type, JSON.stringify(event.body), now, now)
+ }                                       // INSERT OR IGNORE agora deduplica de fato

Bot — extractor calcula a chave (exemplo messages.upsert):

- return (d.messages ?? []).map((msg) => ({
-   type: 'messages.upsert', chat_jid: msg.key?.remoteJid ?? null, payload: msg,
- }))
+ return (d.messages ?? []).map((msg) => ({
+   event_id: uuidv5(`messages.upsert|${msg.key?.remoteJid}|${msg.key?.id}`, NS),
+   body: { type: 'messages.upsert', chat_jid: msg.key?.remoteJid ?? null, payload: msg },
+ }))

Bot — fix do group.member-tag.update (genericExtractor):

- chat_jid: (it?.id) ?? (it?.key?.remoteJid) ?? null,
+ chat_jid: (it?.id) ?? (it?.groupId) ?? (it?.key?.remoteJid) ?? null,

Bot — sender classifica a resposta:

- const ok = await sendOnce(...)
- if (ok) outbox.markSent(row.event_id)
- else outbox.reschedule(row.event_id, attempts, next)
+ const res = await sendWithTimeout(...)          // AbortController
+ if (res.status >= 200 && res.status < 300)  outbox.markSent(row.event_id)
+ else if (res.status === 422 || res.status === 400)  outbox.deadLetter(row.event_id, res.status)
+ else if (res.status === 401 || res.status === 403)  { outbox.reschedule(...); alert('auth') }
+ else  outbox.reschedule(...)                    // 5xx / rede / 408 / 429

Backend — ingest síncrono via Action (convenção: Action, não Service):

- dispatch(new ProcessWhatsAppEvent(eventId, type, chatJid, payload));
- return response()->json(['status' => 'accepted'], 202);
+ resolve(StoreWhatsAppEventAction::class)($eventId, $type, $chatJid, $payload);  // síncrono
+ return response()->json(['status' => 'stored'], 201);                            // após commit

Backend — Action sanitiza antes do firstOrCreate:

// StoreWhatsAppEventAction (invokable)
$clean = $this->sanitize($payload); // remove �, JSON_INVALID_UTF8_SUBSTITUTE
WhatsAppEventLog::query()->firstOrCreate(
    ['event_id' => $eventId],
    ['type' => $type, 'chat_jid' => $chatJid, 'received_at' => now(), 'payload' => $clean],
);

Backend — HMAC cobre o event_id:

- $expected = hash_hmac('sha256', $request->getContent(), $secret);
+ $expected = hash_hmac('sha256', $eventId.'.'.$request->getContent(), $secret);

6. Sequência de implementação (fatias verticais)

Cada fatia é entregável e verificável de ponta a ponta.

1. Idempotência determinística (bot) — helper UUIDv5 + chave por tipo + enqueue(event_id) + INSERT OR IGNORE vivo. ✅ Verificar: reconexão não duplica.
2. Ingest síncrono + sanitização (backend) — controller→Action síncrona, drop do job, sanitizer, HMAC com event_id. ✅ Verificar: poison persiste, sem loss/loop; DB-down → 5xx → retry.
3. Resiliência do outbox (bot) — classificação de resposta, outbox_dead, timeout no fetch, alerta de estouro, poda por idade. ✅ Verificar: 422 → dead-letter; 401 → alerta sem descarte.
4. Segurança mínima (ambos) — event_id no HMAC (já na fatia 2 no backend; fechar no bot) + alinhar nome do env do segredo + fail-loud no 401 persistente.
5. Observabilidade (bot) — heartbeat (status, outbox.count(), idade do mais antigo) + alerta de desconexão.
6. Fix avulso (bot, a qualquer momento) — group.member-tag.update via groupId.
7. Docs — ADR-0003 + atualizar CONTEXT.md; apagar obsoletos (§7).

7. Reestruturação de documentação

Criar:

• docs/adr/0003-deterministic-id-and-synchronous-ingest.md — supersede as partes do ADR-0002: event_id random → determinístico; ingest assíncrono → síncrono sem fila; + sanitização, dead-letter, dupla dedup.

Atualizar:

• app-modules/integration-whatsapp/CONTEXT.md — glossário (event_id = determinístico por conteúdo; ingest síncrono; Redis só p/ futuro).
• wpp-tui docs/coletor-whatsapp-overview.md e docs/he4rt-platform-integration.md — novo contrato.

Apagar (obsoletos — git preserva o histórico):

• app-modules/integration-whatsapp/docs/spec.md (já marcado histórico/superado).
• app-modules/integration-whatsapp/docs/plans/0001-ingest-implementation.md.
• wpp-tui/docs/plans/2026-05-21-whatsapp-collector-bot.md e …-bot-design.md.

Manter como histórico: ADR-0001 e ADR-0002 (registro de por que o desenho evoluiu).

8. Pontos confirmados / em aberto

• D9 (canonicalização) — ✅ confirmado: canonicalizar (ordenar participantes, dropar voláteis) antes do hash.
• D10 (observabilidade) — ✅ confirmado: mínimo (heartbeat + alerta de desconexão). Ban-detection e healthcheck HTTP → fase futura.
• Migração de dados antigos — ✅ não se aplica: ambiente é só dev, sem dado de prod. Começar limpo (migrate:fresh); a dedup determinística vale desde a primeira linha. Sem etapa de migração.
• messages.upsert chave — ✅ confirmado: key.id + remoteJid.