SaguiDesk 2.0.1

Requisitos

Instalar na hospedagem

1. Baixe o sagui_desk_v2.0.1.zip e envie o conteúdo da pasta saguidesk para public_html/ (ou para uma subpasta ou subdomínio) pelo Gerenciador de Arquivos.
2. No painel da hospedagem, crie um banco MySQL e um usuário com acesso total a ele. Anote nome do banco, usuário e senha.
3. Acesse https://seudominio.com.br/install/. O instalador confere os requisitos e mostra em vermelho o que faltar.
4. Preencha o banco, o nome do sistema, a URL e o administrador. Clique em Instalar SaguiDesk.
5. Pronto: entre com o e-mail e a senha do administrador.

Rodar localmente

Para testar no seu computador antes de publicar. No instalador há botões de atalho que preenchem os dados do banco de cada pacote.

MAMP (macOS)

1. Copie a pasta saguidesk para /Applications/MAMP/htdocs/ e clique em Start no MAMP.
2. Abra http://localhost:8888/saguidesk/.
3. No bloco do banco, clique em MAMP: servidor 127.0.0.1, porta 8889, usuário e senha root.

XAMPP, WAMP ou Laragon

Copie para htdocs (XAMPP) ou www (WAMP/Laragon), abra http://localhost/saguidesk/ e use o atalho XAMPP / WAMP / Laragon: porta 3306, usuário root, senha vazia.

Servidor embutido do PHP

Com PHP e MySQL instalados (no Mac, brew install php mysql):

cd saguidesk
php -S localhost:8000 router.php

O router.php faz o papel do .htaccess: rotas amigáveis e bloqueio das pastas internas.

Dados de demonstração

Marque Criar dados de demonstração no instalador para já começar com tickets, um atendente e dois clientes. Senha de todas as contas: Demo1234.

Exclua essas contas em Admin → Usuários antes de colocar o sistema em produção.

Instalação manual

Para quem prefere não usar o instalador:

1. Crie o banco e importe saguidesk.sql pelo phpMyAdmin.
2. Copie .env.example.php para .env.php e preencha os dados.
3. Gere a chave de criptografia e cole em APP_KEY.
4. Crie o administrador na tabela users com role = 'admin' e a senha gerada por password_hash().
5. Crie o arquivo vazio storage/installed.lock.

# chave AES-256 (32 bytes em base64)
php -r "echo base64_encode(random_bytes(32)), PHP_EOL;"

# hash da senha do admin
php -r "echo password_hash('SuaSenha123', PASSWORD_DEFAULT), PHP_EOL;"

Arquivo .env.php

Gerado pelo instalador na raiz do sistema. Guarda credenciais e nunca deve ser versionado (já está no .gitignore).

Configurações do painel

Em Admin → Configurações, dividido em cinco abas:

E-mail e SMTP

O SaguiDesk tem cliente SMTP próprio, sem bibliotecas externas. Com o SMTP desligado (padrão), cada e-mail é gravado em storage/logs/mail.log, inclusive o link de recuperação de senha. É assim que você testa tudo em localhost.

Notificações automáticas (cada uma pode ser desligada):

• Abertura: confirmação para o cliente e aviso para a equipe (o responsável, ou os atendentes do departamento, ou os administradores).
• Resposta: quando a equipe responde, o cliente recebe; quando o cliente responde, a equipe recebe. Notas internas nunca geram e-mail.
• Fechamento: o cliente é avisado e convidado a avaliar o atendimento.

Perfis e permissões

Permissões atribuíveis a cada atendente em Admin → Usuários:

Tickets

Cada ticket recebe um código público curto, como SD-4F7K2Q, que não revela quantos chamados existem.

Status

Na tela do ticket

• Responder ou nota interna: a nota fica destacada em amarelo e o cliente nunca a vê.
• Depois de responder: escolha se o ticket vai para "Aguardando cliente", fica "Em andamento" ou vira "Resolvido".
• Quem responde primeiro assume o ticket se ele estiver sem responsável.
• Mudanças de status, prioridade, departamento e responsável viram eventos na linha do tempo.
• Na lateral: dados do cliente, tempos de 1ª resposta e resolução e os outros chamados dele.
• Ctrl/⌘ + Enter envia a resposta.

Lista e ações em massa

Filtre por status, prioridade, departamento e responsável, busque por assunto, código, nome ou e-mail e ordene por prioridade. Marque vários tickets para mudar status, atribuir ou excluir de uma vez. Tickets aguardando a equipe aparecem com um ponto colorido.

Anexos

Arraste arquivos para o formulário. O sistema confere a extensão, o tamanho e o conteúdo real do arquivo; um .php renomeado para .jpg é recusado. Os arquivos ficam em storage/uploads, fora do alcance da web, e só são entregues a quem pode ver o ticket.

Painel do cliente

O cliente vê quantos chamados estão com a equipe, quantos aguardam resposta dele e o histórico completo. Respostas novas da equipe ganham o selo Nova resposta. Ao encerrar, ele avalia o atendimento com 1 a 5 estrelas e um comentário opcional; a média aparece no dashboard e nos relatórios.

Dashboard

Atualiza sozinho a cada 20 segundos e pausa quando a aba fica em segundo plano. Mostra:

• Em aberto, aguardando a equipe, urgentes e sem responsável
• Novos e resolvidos hoje
• Tempo médio de 1ª resposta e de resolução (30 dias)
• Satisfação média (CSAT) e número de avaliações
• Gráfico de abertos x resolvidos dos últimos 14 dias
• Distribuição por status, prioridade e departamento, e ranking da equipe

O sino do topo conta, para a equipe, os tickets esperando resposta; para o cliente, os que a equipe respondeu.

Relatórios PDF e Excel

Em Admin → Relatórios, filtre por período (atalhos de 7, 30 e 90 dias e mês atual), status, prioridade, departamento e responsável. A tela mostra o resumo, o desempenho por responsável e a lista de tickets.

• PDF: A4 paisagem, com cabeçalho na cor do sistema, cartões de resumo, tabela paginada e "Página X de Y".
• Excel (.xlsx): cabeçalho fixo, autofiltro e números como número. Sem a extensão zip no servidor, gera .xls.

Logs de atividade

Registra logins, falhas e bloqueios de login, abertura, resposta, alteração e exclusão de tickets, mudanças em usuários e configurações, exportações e falhas de e-mail, com usuário, data e IP. Filtre por tipo, pessoa, período ou texto.

Segurança

Estrutura e rotas

saguidesk/
├── index.php            front controller
├── router.php           roteador para php -S
├── .htaccess            rotas amigáveis e bloqueios
├── nginx.conf.example
├── .env.example.php
├── saguidesk.sql
├── AGENTS.md            guia para agentes de código (Codex etc.)
├── install/             instalador web
├── app/
│   ├── bootstrap.php    configuração, erros, cabeçalhos, sessão
│   ├── routes.php       todas as rotas
│   ├── helpers.php      e(), url(), flash(), icon()…
│   ├── Core/            DB, Auth, Session, Crypto, Csrf, Mailer, PdfReport, XlsxWriter…
│   ├── Controllers/
│   └── Views/
├── assets/              css, js, logotipo enviado
└── storage/             anexos, logs, lock (bloqueado na web)

Banco de dados

Nove tabelas InnoDB em utf8mb4, com chaves estrangeiras:

Personalizar o código

O pacote traz um AGENTS.md com a arquitetura e as regras do projeto, lido automaticamente por agentes de código como Codex e Claude Code. As regras que valem para qualquer alteração:

• Manter compatibilidade com PHP 7.4 (nada de match, union types ou ?->).
• SQL só pela classe DB, com placeholders.
• Escapar toda saída com e(); nenhum JavaScript inline (a CSP bloqueia).
• Todo formulário POST com csrf_field().

Vindo da 1.x

A 2.0 é uma reescrita completa, com outro banco de dados. Não existe atualização automática:

1. Instale a 2.0.1 em uma pasta ou subdomínio novo, com um banco novo.
2. Recrie departamentos e atendentes; clientes podem se cadastrar sozinhos.
3. Mantenha a 1.x no ar, só para consulta, até encerrar os chamados antigos.

A base de conhecimento da 1.x não existe na 2.0.

Solução de problemas

Changelog