Kommo Agent

info O que faz

Calculadora de malhas F5. Responde leads via Salesbot (return_url). Debounce 6s, allowlist pipelines. FSM - DÚVIDAS + funil de calculo.

schedule Agendamentos (1)

description Documentação (CLAUDE.md)

# CLAUDE.md — Contexto Permanente do Projeto
# F5 Têxtil | Kommo Agent
# Atualizado em: 2026-04-10

## 1. SOBRE O PROJETO

**Nome:** Kommo Agent
**Objetivo:** Agente conversacional que recebe leads pelo Kommo, roteia por funil para um dos três modos (cálculo de malhas, dúvidas do workshop FSM, consultor genérico) e responde via Salesbot mantendo a conversa rastreável no chat do Kommo.
**Fase atual:** Produção
**Documentação completa:** [PRD.md](PRD.md) · [ARCHITECTURE.md](ARCHITECTURE.md) · [SCHEMA.md](SCHEMA.md) · [STATUS.md](STATUS.md)

## 2. STACK TECNOLÓGICO

- **Linguagem:** Python 3.12
- **Backend:** FastAPI 0.115 + Uvicorn 0.30
- **LLM:** Anthropic SDK 0.40 — modelo `claude-haiku-4-5-20251001`
- **Banco:** SQLite — único banco vivo é `/app/data/conversations.db`. Outros `.db` no disco estão mortos e serão apagados na Fase 1.
- **Auth dashboard:** HTTP Basic (deprecated, marcado para remoção)
- **Deploy:** Docker Compose + Traefik (Let's Encrypt) → `https://kommo-agent.srv1440237.hstgr.cloud`
- **Envs:** `/root/shared.env` (montado como `env_file`)

## 3. INVARIANTES — NÃO QUEBRAR NUNCA

Estas são as leis do sistema. Mudar qualquer uma delas exige decisão arquitetural explícita do Sandro.

### I1. `return_url` do Salesbot é o ÚNICO gate
- Sem `return_url` armazenado para o `lead_id` → **não chama LLM, não responde, não faz nada**.
- O gate vive em [`main.py`:`_processar_lead_debounced`](main.py).
- **Proibido** adicionar filtros de `pipeline_id`/`status_id` no código que substituam o gate. Quem decide onde o agente atua é o Salesbot configurado dentro do Kommo.
- Audit notes (⚠️) no lead Kommo são **obrigatórias** quando o gate é atravessado erroneamente — foram elas que revelaram o vazamento do lead 38998716 historicamente.

### I2. Toda resposta de conversação sai pelo Salesbot `return_url`
- **Proibido** fallback WhatsApp direto para respostas de conversação geradas pelo LLM (modos `calculo`, `consultor`, `duvidas_workshop`).
- Motivo: rastreabilidade. Mensagem fora do Salesbot não aparece no chat do Kommo e desorganiza o histórico do lead.

**Exceções legítimas** (única parte do código onde WhatsApp direto é permitido):
- **[`leadform.py`](leadform.py):** inicializa conversa nova a partir de Facebook Lead Ads, onde o lead ainda não existe no Kommo e portanto **não há Salesbot ativo nem `return_url` disponível**. Usa `whatsapp_client.enviar_mensagem` direto + `message_router.enviar_template` para templates aprovados (`lead_form_resultado`, `lead_form_incompleto`).
- **Depois da primeira mensagem** do `leadform`, o lead vira contato no Kommo, o Salesbot assume o fluxo, e a exceção deixa de se aplicar — todas as próximas mensagens passam pelo caminho normal (webhook Kommo → Salesbot → return_url).
- **[`resgate.py`](resgate.py) reativado em 2026-04-26:** dispara pings de follow-up (3 mensagens em até 24h) via `whatsapp_client.enviar_mensagem` direto. Justificativa: o cron de varredura (2min) não recebe webhook do Salesbot, portanto **não tem `return_url` disponível**. Decisão Sandro 2026-04-25: rota A (WA Cloud direto) escolhida sobre rota B (Salesbot dedicado via API), porque a API `run salesbot` do Kommo só dispara para canais ativos com handler em pé — não é viável reproduzir o ciclo webhook→salesbot a partir de um cron. Rastreabilidade preservada via **nota `[RESGATE]` gravada no Kommo a cada disparo** (`kommo_client.adicionar_nota`). Escopo MVP: só pipeline 12458059. Flag de segurança: `RESGATE_ENABLED=0/1` em `/root/shared.env`. Cancelamento automático quando lead responde, é escalado, conclui cálculo ou recusa explícita (tool `marcar_recusa`).

**Regra para futuras exceções:** qualquer novo ponto de entrada que precise mandar WhatsApp direto (ex: importação via API externa, novo cron de re-engajamento) **exige decisão arquitetural explícita do Sandro antes de ser implementado**. Não copiar o padrão do `leadform.py`/`resgate.py` sem revalidar por que a exceção se aplica ao novo caso. Ver decisão D11 no [ARCHITECTURE.md](ARCHITECTURE.md).

### I3. Sem emoji nem travessão NAS RESPOSTAS QUE VÃO PELO SALESBOT
- **Escopo:** respostas do bot que saem pelo `return_url` do Salesbot (modos `calculo`, `consultor`, `duvidas_workshop`) **nunca** contêm emoji nem travessão (`—`).
- **Por quê:** o canal Salesbot → WhatsApp renderiza emoji como `?`, produzindo padrões `! ?` indesejados na conversa.
- **Como:** o LLM eventualmente desobedece o prompt → `_fix_whatsapp_formatting()` em [`agent.py`](agent.py) aplica regex pós-geração como defesa em profundidade. Cobre 8 ranges Unicode de emoji + `**bold**`→`*bold*` + travessão→vírgula + normalização de espaços.
- Use `*um asterisco*` para negrito (formatação WhatsApp), nunca `**dois**`.
- **Canais que podem usar emoji** (não passam pelo `_fix_whatsapp_formatting`):
  - Notas internas no Kommo via `kommo_client.adicionar_nota` (cabeçalhos `🧶`, `📊`, `🎯`, `🔍`, `⚠️` etc.)
  - Notificações Telegram via `_notificar_telegram` (`✅`, `💰`)
  - Templates WhatsApp aprovados