Técnico

CRM — Suporte técnico

Playbook do módulo CRM para o time de suporte: permissões, modelo de dados, como cada fluxo funciona e resolução de incidentes.

Visão de arquitetura

O CRM é multi-tenant e sempre org-scoped (nenhum dado de um tenant aparece para outro). Peças e endpoints: leads (/api/leads), follow-ups (/api/follow-ups), motivos de perda (/api/lead-loss-reasons), relatório de funil (/api/analytics/crm/funil), linha do tempo (/api/patients/:id/timeline) e campanhas↔leads (/api/whatsapp/campaigns). No front: página /crm (abas Funil e Follow-ups), relatório em /relatorios e a linha do tempo/responsável no detalhe do paciente.

Permissões (causa nº 1 de chamados)

O menu CRM aparece para admin, manager e reception. Excluir lead é só admin; excluir follow-up e CRUD de motivos são admin/manager. No backend o acesso é resolvido pelo módulo crm (guard global); perfis de acesso customizados podem conceder crm em leitura/escrita.

Dica: Para "não vejo o CRM / não consigo excluir": confira papel e perfil de acesso do usuário e peça logout/login — o cache de permissões é semeado no login e na troca de clínica.

Modelo de dados

Tabelas: leads (status/source/assignedToUserId/lossReasonId), lead_status_history (trilha de transições), follow_ups (tarefa de lead XOR paciente), lead_loss_reasons (catálogo por org), patients.ownerUserId (herdado do lead na conversão) e whatsapp_campaign_recipients.leadId. Isolamento reforçado: responsável (lead) e owner (paciente) são validados contra a organização ao gravar (id de outro tenant → 400).

Como cada fluxo funciona

Status/perda (PATCH /leads/:id/status): convertido não muda; ir para lost exige motivo (id do catálogo, validado ativo, ou texto). Conversão (POST /leads/:id/convert, transacional): checa limite do plano, cria paciente com ownerUserId herdado, marca convertido; idempotente. Agenda de follow-ups: classifica atrasado/hoje/futuro no fuso da clínica. Relatório: agrega leads criados na janela (conversão por canal, lead time, perdas). Campanhas para leads: padrão = funil ativo (convertidos/perdidos nunca entram), normaliza telefone, exclui opt-out por número e faz dedupe.

Playbook de incidentes

Sintoma → verificar → resolver:

Não vejo o menu / não excluo: papel + perfil de acesso; logout/login após ajustar.
Converti e não criou paciente: limite de pacientes do plano — orientar upgrade.
Não deixa marcar como perdido: motivo obrigatório; se o catálogo está vazio/inativo, cadastrar/ativar (admin/manager).
Tarefa no dia errado: fuso da clínica/organização.
Lead sumiu: filtros ativos (busca/origem/responsável/unidade) e escopo por clínica.
Campanha enviou a quem pediu para sair: conferir opt-out para o número normalizado.
Relatório zerado: conta leads criados na janela — ajustar as datas.

Escopo e limites (melhoria, não bug)

Hoje o CRM não tem: automação de follow-up (criar tarefa/lembrete automático ao mudar status), rastreamento UTM estruturado (a origem é enum + texto), conteúdo clínico na linha do tempo (fica no prontuário, por privacidade) e badge de pendências no menu. Pedidos desses itens são solicitação de melhoria.

Auditoria e diagnóstico

Ações sensíveis geram audit log (best-effort). A trilha do funil de um lead está em lead_status_history (inclui conversão e perda com o motivo). Para reproduzir, prefira a UI com o papel do usuário (respeita RBAC/escopo); consultas ao banco são N2 e sempre com organization_id no filtro. Ao escalar para engenharia, envie: organização, id do lead/paciente, papel do usuário, passos e horário (com fuso).