Índice

Manual Técnico

Documentação completa da estrutura e funcionamento do NextDesk

Visão Geral
O que é o NextDesk?

O NextDesk é uma plataforma de atendimento multiempresa (SaaS) semelhante ao Freshdesk, Zendesk e similares. Permite que múltiplas empresas utilizem a mesma plataforma de forma isolada.

Funcionalidades Principais
  • Abertura e gestão de tickets
  • Atendimento multicanal (Email, Chat)
  • Controle de SLA (horário comercial)
  • Atribuição de responsáveis e equipes
  • Histórico completo de interações
  • Automações baseadas em regras
  • Relatórios e dashboards
  • API REST para integrações
Modelo de Negócio

Plataforma SaaS com 4 planos:

Free
Gratuito limitado
Starter
Pequenas empresas
Pro
Mais popular
Enterprise
Personalizado
Stack Tecnológica
Backend
  • PHP 8.3 + CodeIgniter 4.7
  • MariaDB - Banco de dados
  • Redis - Cache e filas
  • JWT - Autenticação API
Frontend
  • Bootstrap 5 - Framework CSS
  • jQuery - Manipulação DOM
  • Bootstrap Icons - Ícones
  • Chart.js - Gráficos
Infraestrutura
  • Ubuntu 24 - Sistema operacional
  • Apache - Servidor web
  • SSL/TLS - Certificados HTTPS
Arquitetura
  • MVC - Padrão de projeto
  • API REST - Comunicação
  • Multitenancy - Isolamento por empresa
Áreas do Sistema

O sistema é dividido em 4 áreas distintas, cada uma com seu público e funcionalidades:

Painel Administrativo
nextdesk.pdvbox.com.br/admin

Área exclusiva dos administradores da plataforma (nós).

  • Gestão de empresas e planos
  • Métricas globais da plataforma
  • Configurações do sistema
Painel Empresa
nextdesk.pdvbox.com.br/{slug_empresa}

Área de trabalho das empresas clientes.

  • Dashboard e métricas
  • Gestão de tickets
  • Equipes e usuários
  • Configurações e relatórios
Portal do Cliente
nextdesk.pdvbox.com.br/{slug_empresa}/cliente

Portal onde os clientes finais abrem e acompanham tickets.

  • Meus tickets
  • Abrir novo ticket
  • Base de conhecimento (futuro)
Widget de Chat
Embed em sites

Widget embarcável para chat em tempo real.

  • Chat ao vivo
  • Criação automática de ticket
  • Customizável por empresa
Hierarquia de Perfis

O sistema possui 5 perfis com níveis hierárquicos. Cada nível inferior herda restrições do superior:

Admin Sistema
Nível 0
Nós
Admin Empresa
Nível 1
Empresa
Supervisor
Nível 2
Gerente
Atendente
Nível 3
Operador
Cliente
Nível 4
Usuário Final
Perfil Área de Acesso Descrição
Admin Sistema Painel Administrativo Administradores da plataforma. Gerencia todas as empresas e configurações globais.
Admin Empresa Painel Empresa Administrador da empresa cliente. Configura tudo dentro da sua empresa.
Supervisor Painel Empresa Gerente de equipe. Vê relatórios e gerencia membros da equipe.
Atendente Painel Empresa Operador de atendimento. Responde tickets da sua equipe.
Cliente Portal Cliente Usuário final. Abre e acompanha seus próprios tickets.
Matriz de Permissões
Módulo: Tickets
Permissão Admin Supervisor Atendente Cliente
Listar todos os tickets ✓ ✓ ✗ ✗
Listar tickets da equipe ✓ ✓ ✓ ✗
Listar tickets próprios ✓ ✓ ✓ ✓
Criar ticket ✓ ✓ ✓ ✓
Editar ticket ✓ ✓ ✓ ✗
Deletar ticket ✓ ✗ ✗ ✗
Atribuir responsável ✓ ✓ ✗ ✗
Ver notas internas ✓ ✓ ✓ ✗
Módulo: Usuários
Permissão Admin Supervisor Atendente Cliente
Listar usuários ✓ ✓ ✗ ✗
Criar usuário ✓ ✗ ✗ ✗
Editar usuário ✓ ✗ ✗ ✗
Deletar usuário ✓ ✗ ✗ ✗
Regra de Hierarquia: Um usuário não pode editar ou deletar usuários de nível igual ou superior ao seu.
Multitenancy
Isolamento de Dados

O sistema utiliza multitenancy via empresa_id, garantindo que cada empresa veja apenas seus próprios dados.

Como Funciona
  • Todas as tabelas possuem empresa_id
  • Queries filtram automaticamente por empresa
  • Usuário só acessa dados da sua empresa
  • Admin Sistema vê todas as empresas
Tabelas com empresa_id
  • users, tickets, ticket_mensagens
  • equipes, categorias, tags
  • clientes, sla_configs
  • automacoes, templates_email
Regras de Isolamento
  1. Multitenancy: Usuário só vê dados da própria empresa (exceto admin_sistema)
  2. Equipe: Atendente só vê tickets da sua equipe
  3. Próprios: Cliente só vê seus próprios tickets
  4. Hierarquia: Não pode editar usuário de nível igual ou superior
Sistema de Tickets
Protocolo

Todo ticket possui um protocolo único no formato {ANO}-{SEQUENCIAL}. Exemplo: 2026-000001

Status
Status Pausa SLA
AbertoNão
Em atendimentoNão
Aguardando clienteSim
Aguardando terceiroSim
ResolvidoNão
FechadoNão
Prioridades
Prioridade Multiplicador SLA
Baixa1.5x (mais tempo)
Média1.0x (padrão)
Alta0.5x (menos tempo)
Urgente0.25x (muito menos)
Regras de Transição de Status
  1. Ticket novo → Status "Aberto"
  2. Primeira resposta do atendente → Status "Em atendimento"
  3. Atendente aguarda cliente → Status "Aguardando cliente" (SLA pausa)
  4. Cliente responde → Volta para "Em atendimento" (SLA retoma)
  5. Cliente responde ticket "Fechado" → Reabre como "Aberto"
  6. Ticket "Resolvido" sem resposta em 48h → Auto-fecha
Tipos de Mensagem
Resposta Pública

Cliente visualiza e recebe notificação

Nota Interna

Apenas equipe vê, não notifica cliente

Sistema

Registros automáticos do sistema

Regras de SLA
Cálculo de SLA
  • SLA calculado apenas em horário comercial
  • Horário padrão: Segunda a Sexta, 08:00-18:00 (configurável)
  • Feriados não contam para o cálculo
Métricas
Primeira Resposta

Tempo até a primeira resposta do atendente após abertura do ticket.

Resolução

Tempo total até o ticket receber status "Resolvido".

Pausas de SLA

O SLA é pausado automaticamente quando o ticket está em:

  • Aguardando cliente - Esperando resposta do cliente
  • Aguardando terceiro - Dependência externa

O tempo pausado é descontado do cálculo total do SLA.

Alertas
80% do prazo: Notifica atendente responsável
100% do prazo: Notifica supervisor + marca como "SLA Estourado"
Estrutura de Código
Organização de Pastas
app/ ├── Controllers/ │ ├── Admin/ # Controllers do painel admin │ ├── Api/ # Controllers da API REST │ ├── Cliente/ # Controllers do portal cliente │ └── Painel/ # Controllers do painel empresa ├── Models/ # Models do Eloquent ├── Views/ │ ├── admin/ # Views do painel admin │ ├── cliente/ # Views do portal cliente │ └── painel/ # Views do painel empresa ├── Filters/ # Middlewares de autenticação ├── Libraries/ # Classes auxiliares (JWT, Mailer) └── Config/ # Configurações do CI4 public/ └── assets/ ├── css/ # Arquivos CSS ├── js/ # Arquivos JavaScript └── img/ # Imagens docs/ # Documentação do projeto writable/ ├── uploads/ # Arquivos enviados ├── logs/ # Logs do sistema └── cache/ # Cache
Padrão de Desenvolvimento
Controllers Web

Apenas retornam views, sem lógica de negócio.

Controllers API

Contêm toda a lógica de negócio e validações.

Models

Queries e regras de acesso a dados.

Views

HTML + JS inline na section scripts.

Banco de Dados
Configuração
  • Banco: MariaDB
  • Charset: utf8mb4
  • Collation: utf8mb4_unicode_ci
  • Soft Delete: Todas as tabelas com deleted_at
Tabelas Principais
Módulo Tabelas
Empresas empresas, planos, empresa_configs
Usuários users, perfis, permissoes, user_tokens
Equipes equipes, user_equipes
Tickets tickets, ticket_mensagens, ticket_anexos
Configurações status, prioridades, categorias, tags
SLA sla_configs, horarios_funcionamento, feriados
Convenções
  • IDs são BIGINT com auto_increment
  • Todas as FKs terminam com _id
  • Timestamps: created_at, updated_at, deleted_at
  • Booleanos como TINYINT (0/1)
  • Configurações flexíveis em campos JSON
API REST
Autenticação

A API utiliza JWT (JSON Web Token) para autenticação.

POST /api/auth/login
Content-Type: application/json

{
  "email": "usuario@empresa.com",
  "password": "senha123"
}
Endpoints Principais
Método Endpoint Descrição
GET /api/tickets Listar tickets
POST /api/tickets Criar ticket
GET /api/tickets/{id} Detalhes do ticket
PUT /api/tickets/{id} Atualizar ticket
POST /api/tickets/{id}/mensagens Adicionar mensagem
Resposta Padrão
Sucesso
{
  "success": true,
  "data": { ... },
  "message": "Operação realizada"
}
Erro
{
  "success": false,
  "error": "Mensagem de erro",
  "errors": { ... }
}
Canais de Atendimento
Canais Disponíveis (MVP)
Email

Recebimento via IMAP
Envio via SMTP

Chat

Widget embarcável
Tempo real

API

REST + JWT
Integrações externas

Canais Futuros
WhatsApp Business API
Integração oficial Meta
Em breve
Telefonia VoIP
Integração com PABX
Planejado