# Glossário do Portal

Esse documento define as **quatro categorias** de informação que o portal do
cliente entrega. Toda seção do `painel.html` cai em uma delas — se não cair,
ou é redundante ou o design ficou ambíguo.

Fonte-da-verdade técnica: [`portal-contract.ts`](../supabase/functions/client-insights/portal-contract.ts).
Esse glossário é a versão humana pro cliente final entender, e pro time
interno não confundir categoria na hora de pensar em nova feature.

---

## As 4 categorias

### 1. Métrica
**Um número do passado.** Determinístico, zero IA, os mesmos dados sempre
produzem o mesmo resultado. Serve pra medir operação, não pra decidir ação.

- Exemplo: "3 conversas esperando resposta" · "tempo médio 14 minutos"
- UI: KPI tile, barra de distribuição, comparação semanal
- Cliente espera: **consistência**. Se mudar sem explicação, perde confiança.

### 2. Alerta
**Um estado *agora* que pede atenção.** É sempre sobre *uma coisa específica*
(uma conversa, um lead, o dia inteiro). Se o cliente ignorar, a situação
continua ou piora.

- Exemplo: termômetro vermelho · conversa com cliente reclamando há 6h
- UI: hero com cor semântica (verde/amarelo/vermelho), item da lista
  "Prioridades do dia" com urgência
- Cliente espera: **urgência sincera**. Alerta toda hora = cliente aprende
  a ignorar. Usamos com parcimônia.

### 3. Insight
**Um padrão observado em *muitas* conversas.** É plural por natureza. Não
é algo pra agir *nesta* conversa — é algo pra entender o negócio.

- Exemplo: "7 dos 12 leads quentes perguntam prazo antes de fechar" ·
  "reclamações subiram 40% nesta semana"
- UI: seção "A IA percebeu", até 3 itens, cada um ≤200 chars
- Cliente espera: **algo que ele não tinha notado sozinho**. Se o insight
  for óbvio (ex.: "sábado tem menos mensagem"), é ruído.

### 4. Recomendação
**Uma próxima ação concreta sugerida.** É sempre acionável e tem sujeito
claro (quem responde, o que faz). Diferente de alerta porque já vem com
"o que fazer".

- Exemplo: "Responder João sobre orçamento do brownie — ele pediu 4h atrás
  e é um cliente quente" · "Pedir feedback do Carlos, que encerrou ontem"
- UI: cada item de "Prioridades do dia" tem `action_type` + `reason`
- Cliente espera: **uma tarefa, não um relatório**. Se a recomendação
  precisa de mais de 2 cliques pra virar ação, ela não é recomendação.

---

## Mapeamento: onde cada coisa aparece no portal

| Seção do `painel.html`           | Categoria    | Campo do contrato                         |
| -------------------------------- | ------------ | ----------------------------------------- |
| Hero — termômetro (dot + texto)  | Alerta       | `ai.thermometer` + `ai.thermometer_text`  |
| Hero — resumo inteligente        | Insight      | `ai.executive_summary`                    |
| Prioridades do dia               | Recomendação | `ai.actions[]` (cada uma com `urgency`)   |
| Seu dia em números (3 KPIs)      | Métrica      | `kpis.{waiting_response, avg_response_minutes, new_today}` |
| Como seus leads estão            | Métrica      | `tag_distribution.{topic, sentiment, funnel_stage}` |
| Sua semana                       | Métrica      | `week_comparison`                         |
| A IA percebeu (padrões)          | Insight      | `ai.patterns[]`                           |
| Tendência 7 dias (opcional)      | Métrica      | `trend`                                   |
| Preview de conversas             | Métrica      | `conversations_preview[]`                 |

A regra do "uma seção = uma categoria" **é rígida**. Se aparecer
um elemento que parece mistura (ex.: um insight que sugere ação), a
gente separa em dois elementos, não cria uma quinta categoria.

---

## Regras de estilo (quando desenhar algo novo)

- **Métrica:** número grande em Epilogue, label curto acima, legenda
  explicando o que conta.
- **Alerta:** cor semântica (verde/amarelo/vermelho), sem exagero visual
  quando é verde.
- **Insight:** prosa curta, começa quase sempre com um número ("7 dos 12…"),
  ícone 🧠 / `psychology` / `auto_awesome`.
- **Recomendação:** frase imperativa ou próxima ("Responder João…"),
  sempre com sujeito + ação + motivo em uma linha.

---

## Por que isso importa

Sem essa separação, o portal vira uma sopa de números e textos onde o dono
da PME não sabe o que é urgente vs. o que é pra meditar depois. O
glossário é o contrato cognitivo que garante que cada pixel entrega uma
promessa clara — se o cliente olhar um card e não souber em qual das 4
categorias ele cai, o design está errado, não o cliente.