# W1-GATILHOS — relatório

**Worktree:** `/Users/rafaelmelgaco/fv-gatilhos` · **Branch:** `fv/gatilhos` (de `feat/followup-vivo` = `4f89a0da`)
**Autor:** DevGatilhos · **Data:** 2026-08-10

---

## 1. O que já era emitido em `event_log` (a lista levantada)

Trinta e cinco tipos, extraídos dos `p_event_type` de toda chamada a `emit_event`
em `lib/`, `app/` e `workers/` no SHA `4f89a0da` (excluindo `*.test.ts`):

```
ai.handoff_resolved            lead.created                   message.failed
ai.handoff_triggered           lead.risk_backlog_seeded       message.received
ai.responded                   lead.stage_changed             message.send_requested
ai.sentiment_alert             lead.tag_added                 message.sent
ai_agent.dispatch_requested    lead.updated                   org.updated
ai_agent.run_started           lgpd.data_request_received     user.profile_updated
contact.anonymized             lgpd.export_delivered          whatsapp.chat_id_not_recognized
contact.created                lgpd.export_generated          whatsapp.conversation_mark_failed
contact.tag_added              lgpd.redact_applied            knowledge_source.updated
contact.updated                lgpd.redact_failed             media.derive_requested
conversation.claimed           lgpd.redact_received           media.persist_requested
conversation.transferred       crm.activity_write_failed
```

Mais três emitidos por **trigger Postgres** (`fn_emit_event_on_lead_change`, via
`fn_log_event` — nenhum faz HTTP): `lead.won`, `lead.lost`, `lead.reopened`,
e `lead.assigned` na troca de dono.

Consumidores registrados hoje (`lib/event-log/register-handlers.ts`): resposta de
IA, sentimento, handoff por sentimento, indexador RAG, export e redact LGPD,
regras de automação, reatividade do follow-up, persistência e derivação de mídia
— e, agora, o gatilho de etapa.

### O achado que muda o desenho

`lead.stage_changed` sai de **exatamente três** rotas HTTP:

| Emissor | Linha | Quando |
|---|---|---|
| `app/api/v1/leads/[id]/move/route.ts` | 171 | arrasto do card no quadro |
| `app/api/v1/leads/_handler.ts` (`moveLeadHandler`) | 619 | MCP e regras de automação |
| `app/api/v1/leads/bulk/route.ts` | 200 | movimento em lote |

**`lib/leads/agent-stage-sync.ts` não é um deles.** O briefing afirmava que a
linha 220 desse arquivo emite `stage_changed` em `event_log`; medido, o arquivo
não tem uma única ocorrência de `event_log`. Ele escreve `crm_leads.stage_id`
direto (linha 238) e grava uma **atividade** em `crm_lead_activities` via
`emitLeadActivity` (linha 264). O maestro confirmou por medição independente e
corrigiu o briefing na fonte.

**Consequência que fica aberta, e não é só minha:** card movido pelo assistente
de IA não arma este gatilho — e também não dispara as **regras de automação**,
que consomem o mesmo `lead.stage_changed` (`lib/automation/engine.handler.ts:9`).
Não consertei porque o conserto muda comportamento de automação existente, fora
da minha fronteira de arquivos. Reportado ao maestro; o lugar do conserto é o
emissor, nunca um segundo produtor lendo a atividade — isso duplicaria a verdade
e passaria a disparar dois enrollments no dia em que o primeiro fosse corrigido.

---

## 2. "Caso" e "demanda": não são a mesma coisa, e o gatilho pedido colide

São **duas entidades distintas**, com donos e ciclos de vida diferentes:

| | `demandas` (migrations 0136–0138) | `agent_cases` (migration 0050) |
|---|---|---|
| O que é | o problema do cliente | o caso de **escalada** — a IA travou e passou ao humano |
| Como abre | **automática**, no primeiro `inbound` de todo contato sem demanda aberta (trigger `trg_demanda_abre_no_inbound` em `messages`) | quando o agente aciona handoff |
| Vocabulário | `estado`, `origem`, `proximo_passo`, `desfecho` | `status`, `blocker`, `followup_attempts` |
| Liga as duas | `demandas.agent_case_id` — ponteiro, não cópia | |

(O briefing citava a migration `0119`; a de demandas é a `0136`.)

Daí saem dois problemas com "caso aberto" como gatilho:

1. **Sobre `demandas`, o gatilho é vazio de significado.** Como toda primeira
   mensagem de todo contato abre demanda, "quando abrir um caso" equivale a
   "quando alguém escrever pela primeira vez" — o follow-up dispararia em cima
   de quem acabou de falar com a gente.
2. **Sobre `agent_cases`, o gatilho colide de frente com o que já existe.** A
   abertura do caso emite `ai.handoff_triggered`, e `lib/followup/reactivity.ts`
   já consome esse evento para **pausar ou cancelar** todos os follow-ups vivos
   do contato — porque tem um humano atendendo. Um gatilho que criasse um
   enrollment no mesmo evento estaria brigando com a política de handoff dentro
   do mesmo tick.

**Proposta:** o gatilho coerente é o **simétrico** — *caso encerrado*, que já
existe no schema como `conversation_end` e tem evento (`ai.handoff_resolved`, e o
fechamento de conversa que `fn_demanda_fecha_com_conversa` já observa). É o
momento em que um follow-up de pós-atendimento faz sentido. **Parei aqui e
aguardo a decisão do Rafael** antes de construir — construir "caso aberto" como
pedido literalmente entregaria um controle que briga com outro.

---

## 3. "Proposta feita": não existe tabela, e não precisa de uma

Varri `lib/`, `app/` e `supabase/`: não há entidade de proposta comercial. O que
existe é:

- **`crm_stages.agent_stage_hint`** (migration 0084) com o valor `negotiating`,
  definido no próprio classificador como *"há proposta/preço/condições na mesa e
  o lead está discutindo valor, desconto, parcelamento"*
  (`lib/agent-engine/agent/stage-classifier.ts:55`);
- `lib/leads/next-action.ts`, onde "proposta" significa outra coisa — a **próxima
  ação proposta pela IA** ao humano. Homônimo, não sinônimo.

Ou seja: **"proposta feita" já é uma etapa do funil.** No DeskcommCRM o negócio
que teve proposta é o negócio que está na coluna "Proposta enviada" (ou o nome
que o clone deu a ela). Aplicando DIRC, é caso de **Calcular/Referenciar**, não de
Duplicar: modelar uma tabela `propostas` criaria uma segunda verdade sobre um
estado que o funil já guarda, e cujo movimento já é auditado.

**Portanto o gatilho 3 está entregue pelo gatilho 1** — o usuário escolhe a etapa
"Proposta enviada" no mesmo controle. Zero tabela nova, zero campo novo.

---

## 4. O que foi construído

| Peça | Arquivo | Papel |
|---|---|---|
| Produtor | `lib/followup/gatilho-etapa.ts` | consome `lead.stage_changed`, aplica o gate, cria o enrollment, grava a proveniência |
| Adapter | `lib/followup/gatilho-etapa.handler.ts` | pluga no dispatcher genérico do `event_log` |
| Registro | `lib/event-log/register-handlers.ts` | +1 linha |
| Publish | `app/api/v1/ai/followup-flows/[id]/publish/route.ts` | libera `stage_change`; recusa etapa ausente, apagada ou arquivada |
| Tela | `.../TriggerConfigControl.tsx` | terceiro tipo de gatilho, seletor de etapa **por nome** |
| Leitura | `hooks/followup/useEtapasDeGatilho.ts` | id → nome da etapa, agrupada por funil |

**Event-driven, não time-driven**, porque "o lead entrou na etapa X" é um evento
com hora e autor — ao contrário de silêncio, que é ausência de evento e por isso
continua sendo varredura no tick do cron.

**As três regras do motor, respeitadas e provadas:** o índice org-wide
`idx_followup_enrollments_one_live` barra o segundo enrollment (23505 é caminho
normal, vira `skipped_existing`); `resolveAgentForAutomaticTrigger` gateia e
devolve o `agent_id` pinado; nada roda dentro da transação do banco.

**Sem migration.** A `0143` continua livre: não há mudança de schema. A
proveniência do enrollment (de que negócio, de qual etapa para qual, e por qual
linha do `event_log`) entra como `enrolled_by_stage_change` em
`followup_enrollment_events`, que já existe e já é a timeline que a fila lê. Uma
coluna `origem` em `followup_enrollments` seria uma segunda verdade sobre o mesmo
fato.

### Duas decisões de tela que não são cosméticas

- **A etapa é escolhida pelo nome, agrupada por funil.** Duas etapas podem se
  chamar "Proposta" em funis diferentes; sem o cabeçalho do funil, o operador
  escolheria a errada sem ter como saber.
- **O rótulo diz *quando*.** O disparo depende de dois crons de um minuto (o
  dreno do `event_log` e o tick do motor), então a tela promete "poucos minutos",
  não "na hora". Prometer instantâneo seria o controle mentindo sobre a própria
  função — que é exatamente o defeito que esta missão existe para consertar.
- **`conversation_end` continua escondido e continua recusado no publish**, porque
  continua sem produtor. A honestidade do arquivo foi preservada.

### Um efeito colateral em teste alheio

`tests/e2e/followup-builder.spec.ts` congelava "o seletor oferece exatamente 2
opções e nenhuma de `stage_change`". Ela reprovava, de propósito, a ausência do
produtor que esta entrega criou — atualizei para 3 opções, mantendo a asserção de
que `conversation_end` não aparece.