Tickets

A área de Tickets (/tickets) organiza demandas operacionais em etapas, com ownership por operador e visão por prioridade.

Na prática, ela permite:

• acompanhar backlog por coluna (board) ou lista (table);
• aplicar filtros operacionais e salvar presets por host;
• distribuir tickets para operadores com regras de roteamento;
• atualizar operador, importância e etapa de cada ticket;
• exportar recortes para análise externa (CSV/XLSX).

​

Capacidades atuais no frontend (/tickets)

​

Visualização

• modo board (kanban por etapas);
• modo table (lista paginada);
• modo escolhido fica salvo em sessionStorage (tickets_viewMode).

​

Filtros operacionais

Filtros principais:

• operador: todos, meus, sem-operadores;
• período: hoje, semana, mês, todo período e período customizado;
• smart tags;
• busca textual/protocolo;
• integração externa (hasHubspot);
• importância;
• etapas;
• lead pausado (leadPaused).

​

Presets e persistência de filtros

• filtros atuais são salvos em localStorage por host;
• presets nomeados são persistidos no backend (custom_filters, tipo tickets);
• ao trocar de host, os filtros do host anterior não vazam para o novo contexto.

​

Ações em lote

Com seleção de múltiplos tickets:

• atribuir para mim (quando o usuário é operador válido no host);
• distribuir em massa via modal de distribuição;
• limpar seleção.

​

Exportação

• exporta o recorte filtrado em csv ou xlsx;
• o arquivo retorna com content-disposition para nome dinâmico;
• usa os mesmos filtros da tela de tickets.

​

Configurações relacionadas

​

settings/ticket-stages

Permite:

• listar etapas completas (name, statusLevel, color, labelColor, isClosed);
• criar/editar etapa;
• reordenar etapas;
• remover etapa (com opção de redirecionar tickets para outra etapa).

Regras relevantes:

• nome de etapa não pode duplicar dentro do host;
• se não houver etapa customizada do host, o sistema usa etapas globais (host_id nulo);
• alterar etapa com isClosed = true afeta lógica de fechamento.

​

settings/tickets-queue

Tela de operação de fila e distribuição com:

• indicadores em tempo real;
• forçar distribuição;
• configuração de janela e modo de distribuição.

No frontend, os endpoints consumidos são:

• GET /tickets-queue/stats
• GET /tickets-queue/config
• GET /tickets-queue/state
• POST /tickets-queue/force-distribution
• PUT /tickets-queue/config

​

Fluxo técnico (backend)

​

1) Consulta de tickets

GET /tickets retorna:

• columns: etapas com total por coluna;
• tickets: cards/linhas;
• totalCount: total do recorte.

Comportamentos importantes:

• hostId é obrigatório;
• quando boardMode = true, aplica limite por coluna (não paginação única global);
• ordenação por atividade mais recente (user_last_message_at, updated_at, created_at);
• fallback para etapas globais quando host não tem configuração própria.

​

2) Contadores de filtros

GET /tickets/filters-count retorna:

• all
• mine
• noOperators

Usa o mesmo conjunto de filtros da listagem para manter coerência visual.

​

3) Distribuição

POST /tickets/distribute suporta:

• active-only
• all-operators
• select-operators
• unassigned

Regras de distribuição:

• atua apenas em tickets não fechados;
• no modo unassigned, remove operador (host_people_id = null);
• no modo distribuído, faz round-robin entre operadores válidos;
• para tickets, sincroniza operador com a conversa associada.

​

4) Atualizações unitárias

Endpoints:

• POST /tickets/operator
• POST /tickets/importance
• POST /tickets/status
• POST /tickets/move

Regras técnicas:

• toda atualização registra evento de ticket e feature log;
• mudança de etapa recalcula flag closed conforme isClosed da etapa;
• ao fechar ticket com conversas abertas, a API pode exigir fechamento das conversas antes de concluir.

​

5) Criação de ticket por modal

POST /tickets/createTicketsForModalFront

Fluxo atual:

• frontend envia dados do modal de atendimento;
• backend repassa para endpoint externo de criação;
• após sucesso, invalida cache relacionado à configuração/etapas.

​

6) Exportação

GET /tickets/export

• respeita filtros enviados na query;
• formato aceito: csv ou xlsx;
• limite técnico atual na consulta de exportação: até 10.000 registros.

​

Filtros e parâmetros de API

Principais parâmetros de query em GET /tickets:

• hostId (obrigatório)
• avatarId
• operatorId
• mineOperatorId
• hasOperator
• smartTags[]
• startDate e endDate
• hasHubspot
• importanceLevels[]
• stages[]
• leadPaused
• limit, offset
• boardMode
• search

Observações:

• leadPaused aceita true e false; ausente significa sem filtro;
• search combina full-text (search_vector) + busca por id/protocolo;
• datas inválidas são ignoradas com fallback seguro no backend.

​

Entidades e tabelas relevantes

Domínios principais usados na área:

• tickets
• tickets_levels
• tickets_config
• tickets_events
• host_people
• leads
• conversations
• smart_tags
• smart_tags_conversations

​

Permissões e auditoria

Permissões observadas:

• módulo tickets para visualização/operação da área;
• módulo settings.ticket-stages para configuração de etapas.

Auditoria:

• mudanças relevantes disparam feature logs (ex.: criação, distribuição, mudança de status, exportação, atribuição de operador);
• atualizações também registram histórico em tickets_events.

​

Fluxo recomendado de operação

1. Confirmar etapas e configuração de urgência do host.
2. Entrar em /tickets e aplicar filtros do turno.
3. Salvar preset quando o recorte for recorrente.
4. Priorizar por etapa + importância.
5. Atribuir/distribuir lotes para reduzir fila sem operador.
6. Atualizar etapa conforme andamento real.
7. Exportar recortes quando necessário para gestão externa.
8. Revisar periodicamente tickets fechados e backlog antigo.

​

Checklist rápido para produção

• Etapas configuradas e ordenadas no host correto
• Operadores ativos com permissão de atendimento
• Filtros/presets validados por host
• Distribuição testada (inclusive select-operators e unassigned)
• Exportação CSV/XLSX validada com dados reais
• Fluxo de fechamento revisado para casos com conversas abertas