FleetHub Documentação

Visão geral

FleetHub é um sistema de gestão de ativos de frota empresarial para veículos internos da empresa (50–200 veículos). Construído com Laravel 11, Vue 3 e Tailwind CSS — cobre veículos, motoristas, requisições, entregas com mapa de avarias, registros de combustível, despesas, análise TCO, acompanhamento de conformidade e pontuação de saúde da frota. Não é destinado a táxi ou locação de veículos.

Requisitos do servidor

• PHP 8.2 ou superior (8.3 recomendado)
• MySQL 5.7+ ou MariaDB 10.3+
• Composer 2.x (somente para desenvolvimento local — não é necessário em hospedagem compartilhada)
• Node.js 18+ e npm 9+ (somente para compilações de front-end local)
• Servidor Web: Apache ou Nginx

Extensões PHP necessárias

• OpenSSL, PDO, PDO_MySQL, Mbstring, Tokenizer, XML, Ctype, JSON, GD, Fileinfo

Espaço em disco

~ 200 MB no mínimo. Deixe espaço extra para fotos de veículos, recibos de combustível, imagens de entrega e documentos de conformidade.

Instalação

Opção A – Instalador da Web (recomendado)

1. Faça upload dos arquivos do projeto para o seu servidor web.
2. Aponte a raiz do documento do seu domínio para public/.
3. Definir permissões: storage/ e bootstrap/cache/ devem ser graváveis ​​(chmod 775).
4. Copie .env.example para .env e defina APP_KEY (execute php artisan key:generate se você tiver SSH/Terminal ou consulte cConfiguração do painel → Etapa 5).
5. Visite https://yourdomain.com/install no seu navegador.
6. Siga o assistente — Requisitos → Banco de dados → Migrar → Conta de administrador → Concluído. Marque Incluir dados de demonstração para carregar a frota de amostra com contas de demonstração (consulte Usuários e funções).

Opção B – Instalação CLI

# 1. Instale dependências
composer install --no-dev --optimize-autoloader
npm install
npm run build

# 2. Configurar ambiente
cp .env.example .env
php artisan key:generate

# 3. Edite .env para definir credenciais de banco de dados
# DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD

# 4. Crie tabelas de banco de dados e propague os dados iniciais
php artisan migrate --seed

# 5. Crie um link simbólico de armazenamento para uploads
php artisan storage:link

# 6. Configuração de cache para produção
php artisan config:cache
php artisan route:cache
php artisan view:cache

# 7. Marcar como instalado
echo "Installed" > storage/installed.lock

Etapa 2 do assistente — Configuração do banco de dados

Quando o assistente chegar à Etapa 2, insira os detalhes da conexão MySQL para o banco de dados que você criou em seu painel de hospedagem.

Onde encontrar essas credenciais no painel de hospedagem

• Hostinger: hPanel → Bancos de dados → Gerenciamento → clique em seu banco de dados.
• cPanel: cPanel → Bancos de dados MySQL. A lista do banco de dados mostra nomes; os usuários estão listados abaixo.
• Plesk: Plesk → Bancos de dados → clique no nome do banco de dados.
• DirectAdmin: DirectAdmin → Gerenciamento MySQL → clique no banco de dados.
• Banco de dados externo/gerenciado: AWS RDS, banco de dados gerenciado DigitalOcean, etc. Use credenciais do seu console de nuvem.

Erros comuns e como corrigi-los

Localhost (desenvolvimento local)

Guia rápido para executar o FleetHub em seu computador para teste ou desenvolvimento antes de implantar em produção. Escolha o ambiente que corresponde ao seu sistema operacional.

Opção 1 – Laravel Herd (recomendado, macOS e Windows)

Laravel Herd é o ambiente local oficial da equipe Laravel — gratuito, nativo, sem Docker. Pacotes PHP 8.2/8.3/8.4, Nginx e (no Herd Pro) MySQL/Redis.

1. Baixe e instale Laravel Herd em herd.laravel.com.
2. Coloque a pasta do projeto FleetHub dentro de ~/Herd/ (macOS) ou %USERPROFILE%\Herd\ (Windows). Herd cria automaticamente um domínio .test - por exemplo. http://fleethub.test.
3. Abra Herd → Sites e confirme se a versão do PHP é 8.2 ou 8.3. Clique com o botão direito no site → Secure para ativar HTTPS (necessário para scanner QR).
4. Crie um banco de dados MySQL. Com Herd Pro, use Services → MySQL → Abrir no TablePlus. Caso contrário, instale MySQL Community ou use SQLite (DB_CONNECTION=sqlite, touch database/database.sqlite).
5. Copie .env.example para .env, preencha as credenciais do banco de dados e execute php artisan key:generate na raiz do projeto.
6. Abra http://fleethub.test/install no seu navegador e siga o assistente de instalação.

Opção 2 – XAMPP (Windows, macOS, Linux)

XAMPP agrupa Apache, MySQL/MariaDB e PHP. Gratuito e multiplataforma. Certifique-se de escolher uma versão com PHP 8.2 ou mais recente.

1. Baixe XAMPP 8.2+ de apachefriends.org e instale-o.
2. Copie o projeto FleetHub em C:\xampp\htdocs\FleetHub\ (Windows) ou /Applications/XAMPP/htdocs/FleetHub/ (macOS).
3. Abra Painel de controle XAMPP e inicie Apache e MySQL. Se as portas estiverem ocupadas, use Config → service.conf para mudar o Apache para 8080.
4. Vá para http://localhost/phpmyadmin → New → crie um banco de dados chamado fleethub com agrupamento utf8mb4.
5. Na pasta do projeto: copie .env.example para .env, defina DB_DATABASE=fleethub, DB_USERNAME=root, deixe DB_PASSWORD vazio (padrão XAMPP). Execute php artisan key:generate.
6. Visite http://localhost/FleetHub/public/install para executar o assistente de instalação.

Opção 3 – Laragão (Windows)

Laragon é uma pilha portátil do Windows projetada para Laravel - vhosts automáticos, URLs bonitos, MySQL/MariaDB e HeidiSQL incluído.

1. Baixe Laragon Full de laragon.org e instale-o.
2. No Laragon: Menu → PHP → Versão — mude para PHP 8.2 ou 8.3.
3. Copie o projeto FleetHub em C:\laragon\www\FleetHub\.
4. Clique em Iniciar tudo. O Laragon cria automaticamente o vhost: http://fleethub.test (apontando para a pasta public/).
5. Abra HeidiSQL (empacotado) → crie um banco de dados fleethub. Credenciais padrão: usuário root, senha vazia.
6. Edite .env com as credenciais do banco de dados, execute php artisan key:generate e visite http://fleethub.test/install.

Opção 4 – Servidor PHP integrado (não é necessário servidor web)

A opção mais simples: o Laravel vem com artisan serve, que inicia um servidor PHP de desenvolvimento. Não é necessário Apache ou Nginx. Melhor para testes rápidos.

# Instale dependências e configure
cd /path/to/FleetHub
composer install
cp .env.example .env
php artisan key:generate

# Execute migrações e propague dados iniciais
php artisan migrate --seed

# Inicie o servidor de desenvolvimento
php artisan serve
# Então visite: http://127.0.0.1:8000/install

Dicas comuns de host local

A câmera do scanner QR não abre em http://

As APIs da câmera do navegador requerem HTTPS, com uma exceção: http://localhost e http://127.0.0.1 são tratados como contextos seguros. Se você acessar o FleetHub através do IP da sua LAN (por exemplo, http://192.168.1.10), a câmera recusará. Use localhost para dev ou habilite HTTPS via Herd/mkcert.

Permissão negada no armazenamento (macOS/Linux)

Se você vir erros de gravação quando o aplicativo tentar registrar ou armazenar em cache, corrija as permissões: chmod -R 775 storage bootstrap/cache. No Windows, isso geralmente não é necessário.

Porta já em uso

Se a porta 8000 for usada por outro aplicativo, use uma porta diferente:

php artisan serve --port=8001

Testando e-mails localmente

O SMTP real não está disponível na maioria das configurações de host local. Duas opções seguras: (1) definir MAIL_MAILER=log em .env — os e-mails são despejados em storage/logs/laravel.log em vez de serem enviados; ou (2) use Mailtrap / MailHog para capturar mensagens enviadas em uma caixa de entrada falsa.

MAIL_MAILER=log
# Todos os e-mails são gravados em storage/logs/laravel.log

Ativos de front-end (Vite/Tailwind)

O front-end Vue/Tailwind do FleetHub é pré-construído no pacote. Se você editar os componentes do Vue ou a configuração do Tailwind, precisará do Node.js 18+:

npm install
npm run dev    # Hot-reload durante o desenvolvimento
npm run build  # Compilação de produção (executada antes da implantação)

Implantando no Hostinger Single (Hospedagem Compartilhada)

Este é o caminho recomendado para usuários sem VPS ou experiência técnica. FleetHub é totalmente compatível com o plano Hostinger Single Web Hosting mais barato (~$2,99/mês). Sem SSH, sem Composer, sem necessidade de linha de comando – Single inclui cron jobs nativos, PHP 8.3 e SSL grátis prontos para uso.

Passo 1 — Prepare sua hospedagem

1. Faça login em Hostinger hPanel.
2. Vá para Hospedagem → Gerenciar para seu domínio.
3. Defina a versão do PHP para 8.2 ou 8.3 via Avançado → Configuração do PHP.
4. Certifique-se de que estas extensões PHP estejam habilitadas (geralmente padrão):
   • OpenSSL, PDO, PDO_MySQL, Mbstring, GD, Tokenizer, XML, Ctype, JSON, Fileinfo

Passo 2 — Criar banco de dados MySQL

1. No hPanel, vá para Bancos de dados → Bancos de dados MySQL.
2. Clique em Criar novo banco de dados.
3. Observe estes 3 valores:
   • Nome do banco de dados — por exemplo u123_FleetHub
   • Nome de usuário — por exemplo u123_admin
   • Senha — gerado automaticamente, mantenha-o seguro

Passo 3 — Carregar arquivos

1. Vá para Arquivos → Gerenciador de Arquivos no hPanel.
2. Navegue até public_html/ (esta é a raiz do seu domínio).
3. Exclua qualquer padrão index.html ou default.php nessa pasta.
4. Clique em Carregar arquivos e carregue todo o source.zip do pacote.
   Ou carregue o conteúdo da pasta /source/ diretamente via FTP, se preferir.
5. Se você carregou um ZIP, clique com o botão direito → Extrair. Após a extração, todos os arquivos deverão estar na raiz de public_html/.
6. Verifique se public_html/ contém: app/, public/, vendor/, .htaccess, index.php (em public/), .env, etc.

Passo 4 — Execute o instalador

1. Abra seu navegador e vá para https://yourdomain.com/install.
2. Você verá o instalador FleetHub.
3. Etapa 1: Requisitos — Todas as verificações devem passar (verde). Se alguma falhar, entre em contato com o suporte da Hostinger para ativar a extensão PHP ausente.
4. Etapa 2: Banco de dados — Insira as credenciais da Etapa 2 acima:
   • Hospedar: localhost
   • Porta: 3306
   • Banco de dados: u123_FleetHub
   • Nome de usuário: u123_admin
   • Senha: (a que a Hostinger gerou)
5. Etapa 3: Migrar — Clique em "Executar Migrações e Seed". Leva cerca de 10 segundos. Não atualize.
6. Etapa 4: Admin — Crie sua conta de administrador. Use uma senha forte.
7. Concluído! — Você verá a URL do Cron (salve!) e um botão para fazer login.

Passo 5 — Configure alertas automáticos por e-mail via Hostinger Cron

FleetHub usa o agendador do Laravel para tarefas em segundo plano: alertas de expiração de conformidade, lembretes de manutenção, avisos de requisições vencidas, alertas de carteira de motorista, atualizações de valor de veículos e recálculo de pontuação de saúde da frota. Configure o cron job one no hPanel e o Laravel decide qual tarefa executar e quando.

1. No hPanel, vá para Avançado → Cron Jobs.
2. Clique em Criar tarefa Cron.
3. Selecione o tipo: Custom (não "PHP" — precisamos passar um argumento).
4. Para o comando, digite (substitua uXXXXXX pelo nome de usuário da sua conta Hostinger):

   /usr/bin/php /home/uXXXXXX/public_html/artisan schedule:run

   Dica: abra o Gerenciador de Arquivos, localize o arquivo artisan (raiz do seu projeto), clique com o botão direito → Propriedades para copiar o caminho completo.
5. Defina a programação como A cada minuto — todos os cinco campos (Minuto, Hora, Dia, Mês, Dia da semana) definidos como *.
6. Clique em Salvar.

É isso aí - o FleetHub agora envia lembretes de requisições vencidas, alertas de manutenção, alertas de conformidade e expiração de licença, atualiza os valores de depreciação do veículo e recalcula automaticamente a pontuação de integridade da frota.

Passo 6 — Configurar e-mail (SMTP)

A Hostinger fornece contas de e-mail com cada plano. Para usá-los para notificações do FleetHub:

1. No hPanel, vá para Emails → Contas de Email e crie uma (por exemplo, noreply@yourdomain.com).
2. Edite o arquivo .env em public_html/ através do Gerenciador de Arquivos:

   MAIL_MAILER=smtp
   MAIL_HOST=smtp.hostinger.com
   MAIL_PORT=587
   MAIL_USERNAME=noreply@yourdomain.com
   MAIL_PASSWORD=your_email_password
   MAIL_ENCRYPTION=tls
   MAIL_FROM_ADDRESS=noreply@yourdomain.com
   MAIL_FROM_NAME="Your Company Name"

3. Salve o arquivo.
4. Faça login no FleetHub → Configurações → guia E-mail → Enviar e-mail de teste. Se você receber, está feito.

Problemas comuns no Hostinger Single

“500 Erro interno do servidor” após upload

• Verifique se .htaccess existe na raiz public_html/ e contém as regras de reescrita.
• Verifique se a versão do PHP está definida como 8.2 ou 8.3 no hPanel.
• Verifique storage/logs/laravel.log através do Gerenciador de Arquivos para ver o erro real.

"Permissão negada" em uploads

A Hostinger geralmente define as permissões corretas, mas se não:

• Clique com o botão direito em storage/ no Gerenciador de Arquivos → Permissões → defina como 755 recursivamente.
• O mesmo para bootstrap/cache/.

A câmera do scanner de código QR não abre

As APIs da câmera do navegador exigem HTTPS. A Hostinger oferece SSL grátis via Let's Encrypt – habilite-o no hPanel em SSL → Manage.

E-mails programados não estão sendo enviados

• No hPanel → Cron Jobs → verifique a coluna Last run em sua entrada cron. Se estiver vazio, o cron não está disparando — verifique se o caminho do artesão está correto.
• Teste o comando manualmente: abra Terminal no hPanel (se disponível) e execute o comando cron. Se houver erro, a mensagem de erro identificará o problema (versão errada do PHP, caminho errado, etc.).
• Verifique se o SMTP está configurado corretamente (Configurações → Email → Enviar teste).
• Verifique storage/logs/laravel.log quanto a erros do agendador.

Desempenho lento

Hostinger Single compartilhou CPU/RAM. Se sua equipe tiver mais de 20 usuários, considere:

• Atualizando para Premium (~$3,99/mês) — servidores mais rápidos, mais recursos, vários bancos de dados.
• Ou Business (~$5,99/mês) — recursos dedicados, backups diários, ambiente de teste.

Implantando no cPanel (hospedagem compartilhada)

Este guia cobre hospedagem compartilhada padrão cPanel (Namecheap, Bluehost, GoDaddy e a maioria dos hosts econômicos). FleetHub é fornecido com vendor/ e ativos de front-end pré-construídos - sem necessidade de Composer, npm ou terminal web. Se o seu cPanel não tiver Terminal, use SSH Access ou as soluções alternativas do Gerenciador de Arquivos abaixo.

Passo 1 — Definir versão e extensões do PHP

1. Faça login em cPanel.
2. Abra MultiPHP Manager (ou Select PHP Version) e defina seu domínio para PHP 8.2 ou 8.3.
3. Abra MultiPHP INI Editor ou PHP Extensions e confirme se estão habilitados:
   • OpenSSL, PDO, PDO_MySQL, Mbstring, GD, Tokenizer, XML, Ctype, JSON, Fileinfo
4. Se uma extensão estiver faltando, habilite-a na lista de extensões ou entre em contato com o suporte do seu host.

Passo 2 — Habilitar SSL (HTTPS)

1. Vá para SSL/TLS Status (ou Let's Encrypt SSL / AutoSSL).
2. Execute AutoSSL ou instale um certificado gratuito para o seu domínio.
3. HTTPS é obrigatório para que o scanner QR no navegador acesse a câmera.

Passo 3 — Criar banco de dados MySQL e usuário

1. Abra Gerenciar meus bancos de dados (em Bancos de dados).
2. Em Criar novo banco de dados, insira um nome (por exemplo, fleethub) e clique em Criar. O cPanel adiciona o prefixo da sua conta automaticamente – o nome completo será semelhante a cpaneluser_fleethub.
3. Em MySQL Users, crie um usuário com uma senha forte. Copie o nome de usuário prefixado completo.
4. Em Adicionar usuário ao banco de dados, selecione o usuário e o banco de dados, clique em Adicionar e conceda TODOS OS PRIVILÉGIOS. Esta etapa é fácil de perder - sem ela você obtém erros Access denied (1045).
5. Observe estes três valores exatamente como mostrado no cPanel:
   • Nome do banco de dados — por exemplo u123_FleetHub
   • Nome de usuário — por exemplo u123_admin
   • Senha — gerado automaticamente, mantenha-o seguro

Passo 4 — Carregar arquivos

1. Abra File Manager e vá para public_html/ (a raiz do documento do seu domínio).
2. Habilite Configurações → Mostrar arquivos ocultos para que você possa ver .htaccess e .env.
3. Exclua qualquer padrão index.html em public_html/, se presente.
4. Carregue o pacote source.zip e Extraia ou carregue o conteúdo da pasta /source/ via FTP.
5. Após a extração, public_html/ deve conter app/, public/, vendor/, raiz .htaccess e artisan no mesmo nível.

Passo 5 — Prepare .env antes de executar o instalador

Conclua esta etapa antes de visitar /install. Laravel requer um APP_KEY válido e configurações de banco de dados corretas em .env.

1. No Gerenciador de Arquivos, copie .env.example para .env (mesma pasta de artisan).
2. Edite .env e defina no mínimo:

   APP_NAME=FleetHub
   APP_ENV=production
   APP_DEBUG=false
   APP_URL=https://yourdomain.com
   
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=cpaneluser_fleethub
   DB_USERNAME=cpaneluser_admin
   DB_PASSWORD="your_password"
   
   SESSION_DRIVER=file
   CACHE_STORE=file

3. Defina DB_CONNECTION=mysql — o padrão .env.example usa SQLite; hospedagem compartilhada requer MySQL.
4. Defina SESSION_DRIVER=file e CACHE_STORE=file antes da primeira migração (evita erros de "tabela de sessões não encontrada").
5. Coloque DB_PASSWORD entre aspas duplas se contiver caracteres especiais (#, $, !, etc.).

Gere APP_KEY (sem necessidade de terminal)

Muitos planos cPanel não incluem um terminal web. Use um destes métodos:

• Acesso SSH (cPanel → Segurança → Acesso SSH): conecte-se com PuTTY ou PowerShell e execute cd ~/public_html && php artisan key:generate.
• Ajudante do Gerenciador de Arquivos — crie public/genkey.php temporariamente, visite-o em seu navegador, copie a saída para APP_KEY= e exclua o arquivo imediatamente.

  <?php
  echo 'base64:' . base64_encode(random_bytes(32));

• No seu PC — se o PHP estiver instalado localmente, execute php -r "echo 'base64:'.base64_encode(random_bytes(32));" e cole o resultado em .env.

• Defina as permissões storage/ e bootstrap/cache/ como 755 (recursiva) se o instalador relatar erros de gravação.

Passo 6 — Execute o instalador web

1. Abra https://yourdomain.com/install no seu navegador.
2. Etapa 1: Requisitos — todas as verificações devem ser aprovadas (verde). Corrija quaisquer extensões PHP ausentes na Etapa 1 acima.
3. Etapa 2: Banco de dados — insira os nomes prefixados exatos da Etapa 3:
   • Hospedar: 127.0.0.1 or localhost
   • Porta: 3306
   • Banco de dados: cpaneluser_fleethub
   • Nome de usuário: cpaneluser_admin
   • Senha: (your MySQL password)
4. Etapa 3: Migrar — clique em "Executar Migrações e Seed". Leva cerca de 10 segundos. Não atualize a página.
5. Desmarque Incluir dados de demonstração para uma instalação de produção limpa.
6. Etapa 4: Admin — crie sua conta de administrador.
7. Concluído! — salve o URL do Cron mostrado na tela final.

Passo 7 — Configurar Cron Jobs para alertas por e-mail

FleetHub precisa de um cron job em execução a cada minuto para que o Laravel possa enviar alertas de conformidade, lembretes de manutenção, avisos de requisições vencidas e outros e-mails programados.

1. No cPanel, vá para Avançado → Cron Jobs.
2. Em Adicionar novo cron job, defina a programação como Cada minuto (* * * * *).
3. Digite o comando (substitua CPANELUSER pelo seu nome de usuário cPanel em Informações Gerais):

   /usr/local/bin/php /home/CPANELUSER/public_html/artisan schedule:run

   Dica: o caminho do PHP pode ser /usr/local/bin/php ou /usr/bin/php — pergunte ao seu host se não tiver certeza. O caminho do artesão é onde você carregou o projeto (geralmente /home/CPANELUSER/public_html/artisan).
4. Clique em Adicionar novo cron job para salvar.

Passo 8 — Configurar e-mail (SMTP)

Crie uma conta de e-mail cPanel para notificações enviadas:

1. Vá para Contas de e-mail → crie, por exemplo. noreply@yourdomain.com.
2. Edite .env no Gerenciador de Arquivos:

   MAIL_MAILER=smtp
   MAIL_HOST=mail.yourdomain.com
   MAIL_PORT=587
   MAIL_USERNAME=noreply@yourdomain.com
   MAIL_PASSWORD=your_email_password
   MAIL_ENCRYPTION=tls
   MAIL_FROM_ADDRESS=noreply@yourdomain.com
   MAIL_FROM_NAME="Your Company Name"

3. Salve e, em seguida, no FleetHub: Configurações → Email → Enviar email de teste.

Problemas comuns no cPanel

“Acesso negado ao usuário” (SQLSTATE 1045)

• Copie o nome do banco de dados e o nome de usuário exatamente do cPanel – incluindo o prefixo da conta.
• Confirme que você concluiu Adicionar usuário ao banco de dados com TODOS OS PRIVILÉGIOS.
• Redefina a senha do MySQL no cPanel e atualize .env — use aspas em torno de DB_PASSWORD se contiver caracteres especiais.

A migração falha após a etapa do banco de dados ser concluída

• O assistente testa as credenciais do formulário, mas o Migrate lê .env. Certifique-se de que ambos correspondam.
• Exclua bootstrap/cache/config.php se existir e tente novamente.
• Certifique-se de que DB_CONNECTION=mysql esteja definido em .env (não sqlite).

“Valor padrão inválido” durante a migração (1067)

O modo estrito do MySQL em hospedagem compartilhada pode rejeitar certos padrões de coluna. Verifique storage/logs/laravel.log para o erro de migração exato e garanta o PHP 8.2+ com todas as extensões necessárias habilitadas.

“500 Erro interno do servidor” após upload

• Verifique se o root .htaccess existe e o PHP é 8.2+.
• Verifique storage/logs/laravel.log para ver o erro real.
• Confirme que APP_KEY está definido em .env — chave vazia causa 500 erros.

Nenhum terminal no cPanel

Isso é normal em muitos planos compartilhados. Use SSH Access (se ativado), o método temporário genkey.php na Etapa 5 ou gere a chave em seu PC local.

A câmera do scanner QR não abre

Habilite SSL via SSL/TLS Status → AutoSSL e acesse o site via https://.

Configuração

Arquivo .env

Configurações no aplicativo

A maioria das opções não confidenciais são configuráveis ​​em Admin → Configurações:

• Geral: nome/e-mail/telefone da empresa, marca
• Frota: prefixo do código do veículo, modelo de lista de verificação de entrega, padrões de manutenção, modo de página de veículo público
• Email: envie um email de teste para verificar o SMTP
• Notificações: alternar alertas de conformidade, manutenção, requisição e licença
• Localização: fuso horário, formato de data, moeda — aplicado em todo o aplicativo
• Conformidade: gerenciar predefinições de tipo de conformidade (seguro, registro, imposto rodoviário, etc.)
• Branding: nome e logotipo do aplicativo — atualiza o login, o rodapé e o título da página do navegador
• Aparência: personalize marca, status e cores de texto para modo claro e escuro — consulte guia de mudança de marca nas Perguntas frequentes

Suporte multilíngue

O FleetHub vem com 11 idiomas prontos para uso, incluindo RTL árabe e hindi. Os usuários trocam de idioma por meio do menu suspenso de sinalização no cabeçalho superior direito.

Idiomas enviados

Como mudar de idioma

1. Clique no ícone da bandeira no cabeçalho superior direito para abrir o menu suspenso.
2. Escolha seu idioma na lista.
3. A página é recarregada; todos os rótulos da interface do usuário, datas e formatos de moeda mudam.
4. A sua escolha é guardada na sua conta de utilizador e num cookie (1 ano).

Adicionando um idioma personalizado (admin)

Vá para Administração → Traduções (usuários administradores com permissão gerenciar traduções):

• Clique em "Adicionar localidade" - forneça um código (por exemplo, mk para macedônio), nome de exibição, nome nativo, nome do arquivo SVG da bandeira, direção (LTR/RTL) e uma localidade base para copiar as traduções.
• A nova localidade aparece no alternador de idiomas e na lista Configurações → Localização de idiomas padrão.
• As traduções armazenadas no banco de dados substituem automaticamente as traduções de arquivos em lang/{code}/.

Editor de tradução

O editor lista todas as chaves de tradução agrupadas por arquivo (por exemplo, ativos, navegação, configurações). As chaves mostram a linha de base do arquivo e qualquer substituição do banco de dados.

• Filtre por localidade, grupo de tradução ou texto de pesquisa.
• Clique em um valor para editar in-line; as alterações são salvas no banco de dados imediatamente.
• Redefina uma chave para reverter à linha de base do arquivo.
• As localidades integradas (en, vi, es,…) podem ser editadas; localidades personalizadas são totalmente orientadas por banco de dados.
• Somente usuários com permissão gerenciar traduções podem acessar esta página.

Importação/exportação de CSV

• Exportar — baixe todas as chaves de uma localidade como CSV (group,key,value).
• Import — carregue um CSV com as mesmas colunas; as substituições de banco de dados existentes são atualizadas, novas chaves são inseridas.

Localidade padrão por usuário

Cada usuário possui uma coluna locale. As notificações por e-mail são enviadas automaticamente no idioma preferido do destinatário graças ao contrato HasLocalePreference do Laravel.

O idioma padrão do site é definido em Configurações → Localização → Idioma padrão. Usuários individuais substituem isso por meio do alternador de idioma do cabeçalho.

Lista de recursos (15 grupos de módulos)

Usuários e funções

FleetHub vem com 5 funções pré-configuradas para operações internas de frota:

Contas demo (senha: password): admin@fleethub.test, manager@fleethub.test, dept@fleethub.test, accountant@fleethub.test, driver@fleethub.test. Habilite dados de demonstração durante a instalação ou propagação. As permissões são funções do Spatie – os administradores podem ajustar as permissões.

Gestão de Veículos

Criando Veículos

1. Navegue até Veículos → Novo veículo.
2. Preencha placa, marca, modelo, ano, tipo de combustível, categoria e departamento.
3. Adicione a data e o custo da compra (obrigatório para depreciação e TCO).
4. Faça upload de imagens (vários arquivos suportados, máximo de 5 MB cada – compactados automaticamente no celular).
5. Salvar – o código do veículo e o código QR são gerados automaticamente.

Formato do código do veículo

Padrão: {PREFIX}-{YEAR}-{NNNN}, por ex. VH-2026-0001. Configurável via Configurações → Frota → Prefixo do código do veículo.

Importação em massa

1. Clique em Importar na página Veículos.
2. Baixe o modelo do Excel.
3. Preencha seus dados - colunas obrigatórias: license_plate, make, model, category_name.
4. Carregue o arquivo.

Códigos QR e verificação rápida

Cada veículo recebe automaticamente um código QR na criação. A digitalização abre a página do veículo público ou ações rápidas no aplicativo para motoristas autenticados.

Impressão de etiquetas

• Etiqueta única: Clique no ícone da impressora em qualquer linha do veículo.
• Impressão em lote: Selecione vários veículos → Imprimir etiquetas QR. Formato A4, 2 etiquetas por linha.

Verificação no aplicativo

Clique em Scan QR na página Veículos. Permitir permissão da câmera. Funciona em qualquer navegador moderno com HTTPS ou localhost.

Página de veículo público

Cada veículo possui uma URL pública em /v/{vehicle_code} — útil para identificação rápida sem fazer login.

• Configure em Configurações → Frota → Página de veículo público: Público, Login necessário ou Desativado.
• O modo visitante mostra informações básicas somente leitura (placa, marca/modelo). As ações rápidas do driver exigem login.
• Após alterar APP_URL, clique em Regenerar todos os códigos QR em Configurações.

Fluxos de trabalho

Requisições de Veículos

Os funcionários enviam requisições dos veículos de que precisam. Fluxo: requested → approved → returned (ou rejected). O Gerente de Frota ou Chefe de Departamento aprova. A visualização do calendário mostra as reservas de toda a frota. Devoluções vencidas acionam alertas por e-mail.

Entrega de veículos

1. Quando uma requisição for aprovada, crie uma Entrega de saída antes que o motorista leve o veículo.
2. Registre o odômetro, preencha a lista de verificação, marque os danos no mapeador 2D, anexe fotos e capture assinatura digital.
3. Salve e baixe o relatório de entrega em PDF para seus registros.
4. Quando o veículo for devolvido, crie uma Entrega de entrada — compare a condição, atualize o odômetro, apague a atribuição do motorista.
5. Concluir a entrega de retorno marca a requisição como devolvida e define o veículo como disponível.

Depreciação e TCO

FleetHub calcula a depreciação do veículo usando um dos três métodos. A depreciação alimenta o painel de TCO junto com registros e despesas de combustível.

Os padrões são herdados da categoria do veículo. current_value é atualizado automaticamente mensalmente via fleethub:update-vehicle-values. TCO = custo de aquisição + soma dos gastos do veículo no período selecionado.

Campos personalizados

Admin → Campos personalizados permitem adicionar atributos personalizados ilimitados aos veículos:

• Tipos: texto, número, data, seleção (suspenso), área de texto, arquivo, caixa de seleção
• Escopo: aplica-se a todas as categorias ou categoria específica de veículo
• Reordenar: arraste e solte a alça
• Os campos obrigatórios são validados ao salvar o veículo

Relatórios

Sete relatórios de frota integrados, acessíveis no menu Relatórios:

1. Resumo TCO — custo total de propriedade por veículo e em toda a frota
2. Cronograma de depreciação — perda de valor por veículo com exportação
3. Custo de manutenção — gastos por veículo, tipo e mês
4. Consumo e custo de combustível — tendências de km/l com destaques de anomalias
5. Uso de requisição — porcentagem de reserva por veículo ao longo do tempo
6. Expiração de conformidade — documentos do veículo e carteiras de motorista expirando em breve
7. Alocação de veículos por departamento — veículos e utilização por departamento

Todos os relatórios suportam exportação Excel e PDF por meio de botões no cabeçalho da página.

Webhooks

FleetHub pode notificar serviços externos sobre eventos importantes da frota.

Eventos disponíveis

• vehicle.created, vehicle.updated, vehicle.deleted
• requisition.approved, requisition.rejected, requisition.overdue, requisition.returned
• handover.completed
• compliance.expiring, compliance.expired
• maintenance.due, maintenance.overdue, maintenance.completed
• fleet_health_score.dropped

Formato de carga útil

{
  "event": "handover.completed",
  "timestamp": "2026-06-23T08:00:00+00:00",
  "data": {
    "vehicle_id": 1,
    "vehicle_code": "VH-2026-0001",
    "license_plate": "51A-12345",
    "handover_id": 12,
    "direction": "outgoing",
    "driver_id": 4
  }
}

Verificação de assinatura

Se um segredo for configurado, as solicitações incluirão o cabeçalho X-FleetHub-Signature contendo HMAC-SHA256 do corpo da carga útil. Verifique do seu lado:

$expected = hash_hmac('sha256', $rawBody, $secret);
if (hash_equals($expected, $request->header('X-FleetHub-Signature'))) {
  // válido
}

Política de Nova Tentativa

Entregas com falha tentam novamente 3 vezes com atraso de 200 ms. Após 10 falhas consecutivas, o webhook é desativado automaticamente.

Tarefas agendadas

FleetHub usa o agendador do Laravel para trabalhos em segundo plano. Você só precisa da entrada one no cron — o Laravel despacha cada comando fleethub: no momento certo.

Hospedagem compartilhada (interface de usuário cPanel / Hostinger Cron Jobs)

Consulte Configuração do Painel → Etapa 7 ou Configuração do Hostinger → Etapa 5. Resumindo: Avançado → Cron Jobs, comando:

/usr/bin/php /home/uXXXXXX/public_html/artisan schedule:run

Programação: a cada minuto (* em todos os cinco campos).

Comando cron do cPanel

Substitua CPANELUSER pelo seu nome de usuário cPanel:

/usr/local/bin/php /home/CPANELUSER/public_html/artisan schedule:run

VPS/servidor dedicado (crontab)

Execute crontab -e como seu usuário da web e adicione:

* * * * * cd /path/to/FleetHub && php artisan schedule:run >> /dev/null 2>&1

Fallback: pinger de URL externo

Se o seu host não tiver cron, use o URL do Cron no aplicativo (Configurações → guia Sistema) com cron-job.org (gratuito, a cada 15 minutos).

Trabalhos que são executados automaticamente

Guias de atualização

FleetHub v1.0.0 é o lançamento inicial no CodeCanyon.

Solução de problemas

"Permissão negada" no armazenamento

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

O leitor de código QR não abre a câmera

As APIs da câmera do navegador exigem HTTPS. Instale SSL ou use localhost para teste.

E-mails não chegam

Verifique storage/logs/laravel.log. Use Configurações → E-mail → Enviar e-mail de teste para verificar o SMTP.

Banco de dados “Acesso negado” (1045) no cPanel

Nome de usuário/senha incorretos ou atribuição de usuário ao banco de dados ausente. Consulte Configuração do Painel → Problemas comuns.

Erros de migração em hospedagem compartilhada

Certifique-se de SESSION_DRIVER=file e CACHE_STORE=file em .env antes da primeira migração. Verifique storage/logs/laravel.log para obter detalhes.

Erro APP_KEY/500 ausente antes da instalação

Laravel requer APP_KEY em .env. Consulte Configuração do cPanel → Etapa 5 para métodos de geração sem Terminal.

Redefinir instalação

Exclua storage/installed.lock e visite /install novamente. Os dados existentes serão apagados se você executar novamente as migrações.

Desempenho – lista de veículos lenta

Execute php artisan optimize. Garanta índices MySQL em vehicles.vehicle_code, vehicles.license_plate, vehicles.status (criados por migrações).

Registro de alterações

v1.0.0 – Versão inicial (2026-06)

• Veículo CRUD com geração automática de código QR e página pública em /v/{vehicle_code}
• 5 funções de usuário (administrador, gerente de frota, chefe de departamento, contador, motorista)
• Gerenciamento de driver com sincronização de expiração de licença para itens de conformidade
• Fluxo de trabalho de requisição de veículos com calendário e alertas de atraso
• Entrega de veículos com mapeador de danos 2D, lista de verificação, assinatura e PDF
• Gerenciamento de registro de combustível com antifraude de hodômetro e sincronização automática de despesas
• Painel de despesas do veículo e TCO com análise de custo/km
• Motor de depreciação – linha reta, saldo decrescente, unidades de produção (km)
• Itens de conformidade genéricos com alertas de expiração em 30/14/7/1 dia
• Programação de manutenção com renovação automática preventiva e rastreamento de custos
• Fleet Health Score com recálculo diário e modal de detalhamento
• 7 relatórios de frota com exportação para Excel e PDF
• Campos personalizados (7 tipos) com escopo para categorias de veículos
• Webhooks com assinatura HMAC (X-FleetHub-Signature) e repetição automática
• Log de auditoria via Spatie Activitylog com visualizador de diferenças
• UI multilíngue: 11 localidades, incluindo RTL árabe e hindi
• UI de configurações para empresa, frota, e-mail, notificações, predefinições de conformidade
• Assistente de instalação baseado na Web com semeador de dados de demonstração
• Modo escuro, interface de usuário voltada para dispositivos móveis, compactação de imagem para uploads

Créditos

Bibliotecas de código aberto usadas

• Laravel 11 — MIT
• Vue 3 — MIT
• Inertia.js — MIT
• Tailwind CSS — MIT
• Spatie Permission, Media Library, Activitylog — MIT
• Phosphor Icons — MIT (duotone weight)
• ApexCharts — MIT
• html5-qrcode — Apache 2.0
• Simple QrCode — MIT
• Laravel Excel — MIT
• Laravel DomPDF — MIT