@lionchat/mcp-server 0.2.1 → 0.3.1

package/dist/docs/resources/kanban-deep-dive.md

@@ -0,0 +1,295 @@
+# Kanban — Guia Profundo
+
+Tudo sobre o módulo Kanban/CRM do LionChat: funis, etapas, cards, valor, automações, integrações com conversação.
+
+## Estrutura
+
+### Funnel (Funil)
+Container de etapas. Conta pode ter vários funis (ex: "Vendas", "Pós-venda", "Renovação").
+
+| Campo | Descrição |
+|---|---|
+| `id` | Identificador |
+| `name` | Nome do funil (ex: "Vendas B2B") |
+| `description` | Descrição livre |
+| `stages` | jsonb com etapas (ver abaixo) |
+| `archived` | Boolean — funis arquivados não aparecem na UI ativa |
+| `active` | Boolean — controla se aceita movimentação |
+| `settings` | jsonb — config customizada (ex: cores, automações) |
+
+### Stages (Etapas) — dentro de `funnel.stages`
+
+Stages NÃO são tabela separada. São armazenadas como jsonb dentro do Funnel:
+
+```json
+{
+  "novo_lead": {
+    "name": "Novo Lead",
+    "color": "#3B82F6",
+    "position": 1,
+    "description": "Lead ainda não qualificado"
+  },
+  "qualificado": {
+    "name": "Qualificado",
+    "color": "#10B981",
+    "position": 2,
+    "description": "Lead com interesse confirmado"
+  },
+  "ganho": {
+    "name": "Ganho",
+    "color": "#22C55E",
+    "position": 99
+  },
+  "perdido": {
+    "name": "Perdido",
+    "color": "#EF4444",
+    "position": 100
+  }
+}
+```
+
+### KanbanItem (Card)
+Um card individual dentro de uma etapa.
+
+| Campo | Descrição |
+|---|---|
+| `id` | Identificador |
+| `funnel_id` | Funil ao qual pertence |
+| `funnel_stage` | Chave da etapa (ex: `"novo_lead"`) |
+| `position` | Ordem dentro da etapa |
+| `stage_entered_at` | Quando entrou na etapa atual (pra métrica de tempo) |
+| `conversation_display_id` | Conversa principal vinculada |
+| `linked_conversations` | jsonb array `[{display_id: 123}, {display_id: 456}]` — múltiplas conversas |
+| `item_details` | jsonb (ver abaixo) |
+| `custom_attributes` | jsonb — campos custom (igual contatos) |
+| `assigned_agents` | jsonb array de agentes responsáveis |
+| `activities` | jsonb array — log de atividades |
+| `checklist` | jsonb array de tarefas dentro do card |
+| `timer_started_at`, `timer_duration` | Timer interno do card |
+
+### item_details (detalhes do card)
+
+```json
+{
+  "title": "Cliente XYZ - Plano Pro",
+  "value": 5000.0,
+  "priority": "high",
+  "description": "Cliente interessado em upgrade",
+  "notes": [
+    {"text": "Ligou pedindo proposta", "created_at": "2026-05-15T10:00:00Z"}
+  ],
+  "offers": [
+    {"id": 12, "title": "Pro 12 meses", "value": 4800}
+  ],
+  "custom_attributes": {
+    "origem_lead": "Facebook Ads"
+  }
+}
+```
+
+**`value`** é onde fica o valor monetário do negócio (usado em pipelines).
+
+### assigned_agents
+
+```json
+[
+  {
+    "id": 5,
+    "name": "Maria Souza",
+    "email": "maria@empresa.com",
+    "avatar_url": "https://...",
+    "assigned_at": "2026-05-14T09:00:00Z",
+    "assigned_by": 1,
+    "source": "manual"
+  }
+]
+```
+
+Múltiplos agentes podem ter o mesmo card. `source` pode ser `manual`, `automation`, `inherited_from_conversation`.
+
+### linked_conversations — IMPORTANTE
+
+```json
+[{"display_id": 123}, {"display_id": 456}]
+```
+
+**NUNCA gravar inteiros direto** — sempre objetos com `{display_id: ...}`. Inteiros diretos causam TypeError no `as_json`.
+
+## Posição (ordering)
+
+Cada KanbanItem tem `position` (integer). Cards ordenados ASC dentro da etapa.
+
+Reordenação:
+- API endpoint: `POST /api/v2/kanban/items/reorder`
+- Recebe array com nova ordem `[{id: 5, position: 1}, {id: 8, position: 2}]`
+- Recalcula `position` em todas as etapas afetadas
+
+Mover entre etapas:
+- API endpoint: `POST /api/v2/kanban/items/{id}/move`
+- Body: `{funnel_stage: "qualificado", position: 1}`
+- Atualiza `funnel_stage`, `stage_entered_at`, e `position`
+
+## Atividades (activities)
+
+Log automático de eventos do card:
+
+```json
+[
+  {
+    "type": "stage_changed",
+    "from": "novo_lead",
+    "to": "qualificado",
+    "by_user_id": 1,
+    "at": "2026-05-15T10:00:00Z"
+  },
+  {
+    "type": "agent_assigned",
+    "agent_id": 5,
+    "by_user_id": 1,
+    "at": "2026-05-15T10:01:00Z"
+  },
+  {
+    "type": "note_added",
+    "note_id": 42,
+    "by_user_id": 5,
+    "at": "2026-05-15T10:05:00Z"
+  }
+]
+```
+
+Tipos comuns: `created`, `stage_changed`, `agent_assigned`, `agent_removed`, `note_added`, `value_changed`, `priority_changed`, `archived`.
+
+## Checklist (tarefas dentro do card)
+
+```json
+[
+  {
+    "id": "abc-123",
+    "title": "Enviar proposta por email",
+    "checked": true,
+    "completed_at": "2026-05-15T10:00:00Z",
+    "completed_by": 5
+  },
+  {
+    "id": "abc-124",
+    "title": "Agendar follow-up",
+    "checked": false
+  }
+]
+```
+
+Útil pra workflows internos. Não confundir com `tasks` (que é módulo separado de tarefas globais).
+
+## Pipeline (visão por valor)
+
+Pipeline = soma de `item_details.value` agrupado por etapa.
+
+Exemplo:
+```
+Funil "Vendas"
+├── Novo Lead: 12 cards | R$ 47.000
+├── Qualificado: 8 cards | R$ 38.000
+├── Negociação: 3 cards | R$ 22.000
+├── Ganho: 5 cards | R$ 28.000 (fechados no mês)
+└── Perdido: 2 cards | R$ 4.000
+```
+
+Endpoint: `GET /api/v2/kanban/items/counts` retorna contagem + soma por etapa.
+
+## Funil arquivado vs ativo
+
+- `archived = true`: funil escondido da UI principal. Cards ainda existem mas não aparecem nas listas
+- `active = false`: bloqueia movimentação (modo "somente leitura")
+
+Use cases:
+- Arquivar funis antigos no fim do ano
+- Pausar funil em manutenção sem deletar cards
+
+## Integração com Conversation
+
+### Quando uma conversa vincula a um card
+- Manual via UI ("vincular ao Kanban")
+- Automação via `automation_rule.actions` com action `add_to_kanban`
+- API call em `POST /api/v2/kanban/items` com `conversation_display_id`
+
+### Como o card "sabe" sobre o cliente
+
+```
+KanbanItem
+  └─ conversation_display_id → Conversation
+                                  └─ contact → Contact (nome, telefone, email)
+```
+
+NÃO existe `contact_id` direto no KanbanItem. Sempre via conversation_display_id.
+
+### Múltiplas conversas no mesmo card
+
+`linked_conversations` permite agrupar várias conversas (ex: cliente que falou em WhatsApp e Email):
+
+```json
+[
+  {"display_id": 100},
+  {"display_id": 101},
+  {"display_id": 105}
+]
+```
+
+A `conversation_display_id` (singular) ainda é a "principal" — mas todas as `linked_conversations` aparecem na sidebar do card.
+
+## Automações relacionadas a Kanban
+
+AutomationRule com evento `kanban_item_created`, `kanban_item_moved`, `kanban_item_stage_changed`:
+
+```json
+{
+  "event_name": "kanban_item_moved",
+  "conditions": [
+    {"attribute_key": "funnel_stage", "operator": "equal_to", "value": "ganho"}
+  ],
+  "actions": [
+    {"action_name": "send_message", "params": ["Parabéns pelo fechamento!"]},
+    {"action_name": "add_label", "params": ["cliente-pagante"]}
+  ]
+}
+```
+
+## Bulk operations
+
+- `POST /api/v2/kanban/items/bulk_actions` — operações em massa (mover, atribuir, arquivar)
+- `POST /api/v2/kanban/items/import` — importar CSV de cards
+- `GET /api/v2/kanban/items/export` — exportar funil completo
+
+## Custom attributes em cards
+
+Igual contatos, cards têm `custom_attributes` (jsonb):
+
+```json
+{
+  "origem_lead": "Google Ads",
+  "campanha": "Black Friday 2026",
+  "score": 85,
+  "produto_interesse": "Plano Pro"
+}
+```
+
+Configurar atributos no Super Admin ou via API `/api/v1/custom_attribute_definitions`.
+
+## Métricas úteis (via GET /api/v2/kanban/items)
+
+- Tempo médio em cada etapa: `stage_entered_at` vs agora
+- Taxa de conversão: cards em "ganho" vs total criado no período
+- Pipeline ativo: soma de `value` em etapas != ganho/perdido
+- Velocity: cards movidos pra "ganho" por mês
+
+## Diagnóstico: "Card sumiu do funil"
+
+1. Está arquivado? `archived = true` em algum nível?
+2. Etapa atual existe ainda? (etapa removida do funil deixa card "órfão")
+3. `position` está faltando? (cards sem position vão pro fim)
+4. Está em outro funil? (mover entre funis muda `funnel_id`)
+
+## Diagnóstico: "Valor do pipeline errado"
+
+1. Algum card sem `item_details.value`?
+2. Cards arquivados estão sendo contados?
+3. Etapas "ganho"/"perdido" estão incluídas no cálculo?

package/dist/docs/resources/reports-guide.md

@@ -0,0 +1,219 @@
+# Guia de Relatórios e Métricas
+
+Como interpretar cada um dos endpoints de relatório (`lionchat_reports_*`) e métricas correlatas. Use sempre que o usuário pedir métricas, KPIs, dashboards ou comparativos.
+
+## ⚠️ Unidades de tempo
+
+**TODOS os tempos médios são retornados em SEGUNDOS.** Sempre converta antes de exibir:
+
+```
+245 segundos → "4 min 5 seg" ou "4:05"
+3600 segundos → "1 hora"
+86400 segundos → "24 horas" ou "1 dia"
+```
+
+## Endpoints disponíveis (19 total)
+
+### 1. `lionchat_reports_summary` — Resumo geral
+**Use quando o usuário pedir:** "como tá o desempenho?", "resumo da semana", "visão geral"
+
+**Retorna:**
+```json
+{
+  "conversations_count": 142,
+  "incoming_messages_count": 1250,
+  "outgoing_messages_count": 980,
+  "resolutions_count": 98,
+  "avg_first_response_time": 245,       // segundos
+  "avg_resolution_time": 7200,          // segundos
+  "previous": { ...mesma estrutura para comparativo... }
+}
+```
+
+**Parâmetros principais:**
+- `type`: `account` (padrão), `agent`, `inbox`, `label`, `team`
+- `since` / `until`: Unix timestamp (segundos) — período
+- `business_hours`: `true` excluí horários fora do expediente
+
+**Exemplo de uso:**
+```
+since = 7 dias atrás
+until = agora
+type = account
+→ retorna resumo dos últimos 7 dias da conta toda
+```
+
+### 2. `lionchat_reports_list` — Por agente
+**Use quando:** "produtividade por atendente", "ranking de agentes"
+
+Retorna array de métricas, uma por agente. Cada item:
+```json
+{
+  "id": 6,
+  "name": "Elvis",
+  "conversations_count": 23,
+  "avg_first_response_time": 180,
+  "avg_resolution_time": 5400,
+  "csat_score_average": 4.3,
+  "online_at_total": 28800   // segundos online no período
+}
+```
+
+### 3. `lionchat_reports_list_1` — Por time
+**Use quando:** "comparar times", "como está o time Premium vs Standard"
+
+Mesma estrutura por team_id.
+
+### 4. `lionchat_reports_list_2` — Por inbox
+**Use quando:** "qual canal está com mais demanda", "comparar WhatsApp vs Email"
+
+Mesma estrutura por inbox_id.
+
+### 5. `lionchat_reports_list_3` — Por label
+**Use quando:** "quantas conversas urgentes", "comparativo por label"
+
+Mesma estrutura por label.
+
+### 6. `lionchat_reports_list_4` — Por canal
+**Use quando:** "WhatsApp vs Email vs Webchat"
+
+Agrupa por `channel_type`.
+
+### 7. `lionchat_reports_list_5` — Relatórios detalhados
+**Use quando:** "dia a dia da última semana", "evolução temporal"
+
+Retorna timeseries (data + valor) para um metric específico:
+- `metric`: `conversations_count`, `incoming_messages_count`, `outgoing_messages_count`, `resolutions_count`, `avg_first_response_time`, `avg_resolution_time`, `reply_time`, `resolutions_count`
+- `group_by`: `day`, `week`, `month`, `year`
+- `since`/`until`: período
+
+### 8. `lionchat_reports_list_6` — Resumo do Bot
+**Use quando:** "como tá o bot resolvendo", "% de handoff pra humano"
+
+```json
+{
+  "bot_resolutions_count": 45,
+  "bot_handoffs_count": 12,
+  "bot_resolution_rate": 0.79
+}
+```
+
+### 9. `lionchat_reports_list_7` — Conversation Traffic (tráfego)
+**Use quando:** "horário de pico", "quando tem mais demanda"
+
+Retorna heatmap por hora do dia ou dia da semana:
+```json
+[
+  { "hour": 9, "conversations_count": 18 },
+  { "hour": 10, "conversations_count": 25 },
+  ...
+]
+```
+
+### 10. `lionchat_reports_list_8` — Agente em tempo real
+**Use quando:** "quem tá online agora", "carga atual"
+
+```json
+[
+  { "id": 6, "name": "Elvis", "status": "online", "open_count": 5, "unattended_count": 2 }
+]
+```
+
+### 11-15. CSAT
+- `lionchat_csat_metrics`: agregação (média, distribuição)
+- `lionchat_csat_list`: respostas individuais
+- `lionchat_csat_download`: CSV pra download
+
+### 16-18. SLA
+- `lionchat_sla_metrics`: hits / breaches por período
+- `lionchat_sla_list`: SLAs aplicadas a conversas
+- `lionchat_sla_download`: CSV
+
+### 19. `lionchat_reports_list_9` — Aggregated agent overview
+**Use quando:** combinação de tudo: produtividade + CSAT + SLA por agente
+
+## Padrões de interpretação
+
+### Comparando períodos
+Quando passa `since/until`, a maioria dos endpoints retorna `previous` com o período anterior de mesmo tamanho:
+
+```
+Esta semana: 142 conversas
+Semana anterior: 120 conversas
+→ Crescimento de 18%
+```
+
+**Dica:** sempre apresente comparativos pra dar contexto.
+
+### Business hours
+- Sem `business_hours: true`: tempos médios incluem madrugada/feriado (puxa pra cima)
+- Com `business_hours: true`: só conta período de atendimento configurado (mais preciso pra SLA)
+
+**Use business_hours: true** quando o usuário perguntar de "produtividade real" ou comparar com SLA.
+
+### CSAT
+- Score: 1-5 estrelas
+- Médias típicas: 4.0+ é bom, 3.5-4.0 é OK, abaixo de 3.5 é alerta
+- `csat_response_rate`: % de conversas resolvidas que ganharam resposta CSAT (taxa baixa = pouco feedback)
+
+### SLA
+- `breach_count` alto = problema sério, agentes não cumprindo prazos
+- Sempre olhar `hit_rate` (hits / (hits + breaches)) — meta 95%+
+
+## Workflows comuns
+
+### "Relatório semanal completo"
+```
+1. reports_summary com since=7d, type=account → visão geral
+2. reports_list (por agente) → ranking
+3. reports_list_3 (por label) → tipos de demanda
+4. csat_metrics → satisfação
+5. sla_metrics → cumprimento
+6. Compilar resumo em markdown
+```
+
+### "Quem tá com gargalo"
+```
+1. reports_list_8 (real-time) → quem tá com muita conversa aberta
+2. reports_list (por agente, últimos 7d) → quem tá com avg_first_response alto
+3. Cruzar: agente sobrecarregado E com tempo médio alto
+```
+
+### "Mês a mês evolução"
+```
+reports_list_5 com group_by=month, metric=conversations_count, since=12 meses atrás
+```
+
+## Pegadinhas comuns
+
+### ⚠️ Comparar agente "online_at_total"
+Tempo online inclui breaks, almoço, etc. Pra produtividade real, prefira:
+- `conversations_count / online_at_total` = conversas por hora online
+
+### ⚠️ Avg time pode ser enganador
+Mediana é mais representativa que média (1 conversa que durou 5 dias puxa tudo).
+**Mas o LionChat hoje só retorna média.** Reporte com ressalva: "Tempo MÉDIO de X — pode ter outliers."
+
+### ⚠️ Reports não pegam conversas em tempo real
+A maioria dos endpoints é eventually consistent (cache 5min). Pra info real-time use `conversations_meta`.
+
+### ⚠️ Comparativos de período
+`previous` tem o MESMO tamanho do período atual. Se since-until = 7d, previous = 7d antes.
+NÃO compare manualmente "esse mês vs mês passado" — passe `since/until` com mês inteiro e use o `previous` retornado.
+
+## Quando o usuário pede algo MUITO específico que não existe num endpoint
+
+Se a pergunta requer cálculos custom (ex: "conversas por agente que duraram mais de X minutos"):
+1. Liste as conversations com filtros
+2. Filtre no client-side
+3. Agrege e apresente
+
+Mas avise: "essa métrica não existe pronta — vou compor a partir de dados crus"
+
+## Custos de chamadas (importante!)
+
+Endpoints de relatório podem retornar **MUITOS** dados:
+- `reports_list_5` com `group_by=day, since=1 ano` → 365 datapoints
+- `csat_list` sem filtro → milhares
+
+**Sempre limite período** quando o usuário não foi específico. Se pediu "esta semana", use 7d. Se pediu "vamos ver tudo", confirme antes (ano inteiro pode ser muito).